Just starting a new thread here to discuss true annotations vs a
DocBlock Parser:
RFC Referenced:
https://wiki.php.net/rfc/annotations
I've started working on a new proposal, but I'm getting hung up on the
syntax - if we can't use angle brackets anymore, what can we use? Virtually
every symbol on a standard US keyword is an operator of some sort, does
that mean those are all out of the question?e.g. thinking of concrete possible basic syntax, neither of the following
delimiters would work:[Foo('bar')]
Why would this not work? I'm struggling to think of a place where one
would want to use an annotation where it could be misinterpreted as an
array literal. If anything, the visual "conflict" or association with
the array syntax is a good thing in my book: my brain parses it as an
array of one or more annotations.
I agree here, I think the above, if possible would be best. In my mind
annotations should proabably be limited in scope to class declarations
and thus only before a class keyword, before a property or method
declaration.
In none of those scopes would [ ] be a parsing issue I believe...
The one case would be at the beginning of a class, but if simply added
something such as:
[:SomeAttribute(xyz,abc),SomeAttribute2]
It could never be confused with short array syntax and is still brief.
--
-Clint
Just starting a new thread here to discuss true annotations vs a DocBlock
Parser:RFC Referenced:
https://wiki.php.net/rfc/annotations
I've started working on a new proposal, but I'm getting hung up on the
syntax - if we can't use angle brackets anymore, what can we use?
Virtually
every symbol on a standard US keyword is an operator of some sort, does
that mean those are all out of the question?e.g. thinking of concrete possible basic syntax, neither of the following
delimiters would work:[Foo('bar')]
Why would this not work? I'm struggling to think of a place where one
would want to use an annotation where it could be misinterpreted as an
array literal. If anything, the visual "conflict" or association with
the array syntax is a good thing in my book: my brain parses it as an
array of one or more annotations.
I agree here, I think the above, if possible would be best. In my mind
annotations should proabably be limited in scope to class declarations and
thus only before a class keyword, before a property or method declaration.In none of those scopes would [ ] be a parsing issue I believe...
The one case would be at the beginning of a class, but if simply added
something such as:
[:SomeAttribute(xyz,abc),SomeAttribute2]
I've never ever seen an annotation like this in a docblock. What kind of
wacky syntax is this?! And will we now need a parser for docblocks in
style "phpdocumenter" and those annotations above‽
cheers,
Derick
--
http://derickrethans.nl | http://xdebug.org
Like Xdebug? Consider a donation: http://xdebug.org/donate.php
twitter: @derickr and @xdebug
Posted with an email client that doesn't mangle email: alpine
Hi,
I agree here, I think the above, if possible would be best. In my
mind annotations should proabably be limited in scope to class
declarations and thus only before a class keyword, before a property
or method declaration.In none of those scopes would [ ] be a parsing issue I believe...
The one case would be at the beginning of a class, but if simply
added something such as:
[:SomeAttribute(xyz,abc),SomeAttribute2]It could never be confused with short array syntax and is still
brief.
I think when implementing real annotations, then it should be possible
to declare arrays in it. So I think the square brackets don't work.
[Foo([1,2,3])]
Cheers,
Christian
On Wed, Jan 9, 2013 at 1:57 PM, Christian Kaps christian.kaps@mohiva.comwrote:
Hi,
I agree here, I think the above, if possible would be best. In my
mind annotations should proabably be limited in scope to class
declarations and thus only before a class keyword, before a property
or method declaration.In none of those scopes would [ ] be a parsing issue I believe...
The one case would be at the beginning of a class, but if simply
added something such as:
[:SomeAttribute(xyz,abc),**SomeAttribute2]It could never be confused with short array syntax and is still brief.
I think when implementing real annotations, then it should be possible to
declare arrays in it. So I think the square brackets don't work.
[Foo([1,2,3])]Cheers,
Christian--
But the colon prefix won't cover this case?
You can, as I've mentioned in my post at the doc-block parser discussion,
use a keyword inside the brackets to symbolize annotation, for example
[metadata: Key]
[metadata: MaxLength(10)]
[metadata: Relations(["foo", "bar", "baz"])]
public $id;
Am 09.01.2013 13:03, schrieb Yahav Gindi Bar:
On Wed, Jan 9, 2013 at 1:57 PM, Christian Kaps
christian.kaps@mohiva.comwrote:Hi,
I agree here, I think the above, if possible would be best. In my
mind annotations should proabably be limited in scope to class
declarations and thus only before a class keyword, before a
property
or method declaration.In none of those scopes would [ ] be a parsing issue I believe...
The one case would be at the beginning of a class, but if simply
added something such as:
[:SomeAttribute(xyz,abc),**SomeAttribute2]It could never be confused with short array syntax and is still
brief.I think when implementing real annotations, then it should be
possible to
declare arrays in it. So I think the square brackets don't work.
[Foo([1,2,3])]Cheers,
Christian--
But the colon prefix won't cover this case?
You can, as I've mentioned in my post at the doc-block parser
discussion,
use a keyword inside the brackets to symbolize annotation, for
example[metadata: Key]
[metadata: MaxLength(10)]
[metadata: Relations(["foo", "bar", "baz"])]
public $id;
Then rather [@Foo([1,2,3])] if it's possible!
On Wed, Jan 9, 2013 at 2:09 PM, Christian Kaps christian.kaps@mohiva.comwrote:
Am 09.01.2013 13:03, schrieb Yahav Gindi Bar:
On Wed, Jan 9, 2013 at 1:57 PM, Christian Kaps <christian.kaps@mohiva.com
**wrote:
Hi,
I agree here, I think the above, if possible would be best. In my
mind annotations should proabably be limited in scope to class
declarations and thus only before a class keyword, before a property
or method declaration.In none of those scopes would [ ] be a parsing issue I believe...
The one case would be at the beginning of a class, but if simply
added something such as:
[:SomeAttribute(xyz,abc),****SomeAttribute2]It could never be confused with short array syntax and is still brief.
I think when implementing real annotations, then it should be possible to
declare arrays in it. So I think the square brackets don't work.
[Foo([1,2,3])]Cheers,
Christian--
But the colon prefix won't cover this case?
You can, as I've mentioned in my post at the doc-block parser discussion,
use a keyword inside the brackets to symbolize annotation, for example[metadata: Key]
[metadata: MaxLength(10)]
[metadata: Relations(["foo", "bar", "baz"])]
public $id;Then rather [@Foo([1,2,3])] if it's possible!
--
Yeah, that's cool. To be honest, I took that idea from C# which has, for
example (Quoted from standard template AssemblyInfo.cs):
// Version information for an assembly consists of the following four
values:
//
// Major Version
// Minor Version
// Build Number
// Revision
//
// You can specify all the values or you can default the Revision and Build
Numbers
// by using the '*' as shown below:
[assembly: AssemblyVersion("1.0.0.0")]
[assembly: AssemblyFileVersion("1.0.0.0")]
Before we all bikeshed on the syntax, shouldn't we be figuring out the
feature-set first?
Over in PHP-FIG, we've found it useful to audit the existing market to
see what's in use. That doesn't dictate decisions we make, but it can
be instructional. Eg, if we find that most annotation-using projects
out there currently support and use arrays in annotations, then any core
implementation really needs to support that as well in order to be a
reasonable replacement. Maybe not in the same way, but feature-parity
with the current market is the bare-minimum for any such core feature to
be successful. It could certainly go farther, but it cannot go less-far.
--Larry Garfield
We should probably be referring to this type of syntax as attributes
rather than annotations since annotations are currently defined in
docblock comments and are recognized by certain software and utilities.
Whereas annotations have no effect on compilation or at runtime,
attributes do have the possibility of affecting compilation or runtime.
I like the idea of having a schema parameter like metadata: as that
would allow php to reserve php: for example. Almost like a namespace,
in fact it could actually be a namespace, such as:
class a {
[php:Param($s) = StringLength(4, ErrorMessage='Parameter $s length
cannnot exceed 4.', ErrorLevel=E_USER_ERROR)]
public function foo($s) { ... ]
}
I also think that providing no schema should be allowed as well, such as:
[: ... ]
We could, again, model this after the C# model whereby user-land
attributes may be defined, PHP could also provide it's own standard ones.
The only reason I mention C# here is that it's been in wide use for some
time now.
On Wed, Jan 9, 2013 at 1:57 PM, Christian Kaps christian.kaps@mohiva.comwrote:
Hi,
I agree here, I think the above, if possible would be best. In my
mind annotations should proabably be limited in scope to class
declarations and thus only before a class keyword, before a property
or method declaration.In none of those scopes would [ ] be a parsing issue I believe...
The one case would be at the beginning of a class, but if simply
added something such as:
[:SomeAttribute(xyz,abc),**SomeAttribute2]It could never be confused with short array syntax and is still brief.
I think when implementing real annotations, then it should be possible to
declare arrays in it. So I think the square brackets don't work.
[Foo([1,2,3])]Cheers,
Christian--
But the colon prefix won't cover this case?
You can, as I've mentioned in my post at the doc-block parser discussion,
use a keyword inside the brackets to symbolize annotation, for example[metadata: Key]
[metadata: MaxLength(10)]
[metadata: Relations(["foo", "bar", "baz"])]
public $id;
--
-Clint
Hi!
class a {
[php:Param($s) = StringLength(4, ErrorMessage='Parameter $s length
cannnot exceed 4.', ErrorLevel=E_USER_ERROR)]
public function foo($s) { ... ]
}
What this is supposed to do?
--
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227
I was just looking into C# attributes at the time since I had used them
in the past.
It was a loose translation to something for php from the example on this
page:
http://msdn.microsoft.com/en-us/library/system.componentmodel.dataannotations.stringlengthattribute.aspx
In essence the example would be something along the lines of "$s must be
a string with length exactly 4 and if not, trigger_error() with the
given error message and error level.
One of the beautiful things about the C# way of attributes is that they
can be user-defined, so long as they are written to the API for C#
Attributes.
A similar type of thing could occur for PHP, the recent use case of
Nullable for Type Hints would be a great use of such attributes, but
there are dozens of other uses for them, especially if implemented in a
way similar to C#.
Hi!
class a {
[php:Param($s) = StringLength(4, ErrorMessage='Parameter $s length
cannnot exceed 4.', ErrorLevel=E_USER_ERROR)]
public function foo($s) { ... ]
}
What this is supposed to do?
--
-Clint
Hi!
In essence the example would be something along the lines of "$s must be
a string with length exactly 4 and if not,trigger_error()with the
given error message and error level.
OK, I see what you mean, but it is still unclear what such construct
does. At least conceptually, I do not understand what is php:Param, what
is StringLength, what is the relationship between them, which code is
called when and why, what are ErrorMessage= and ErrorLevel=. In C# I can
understand that that declaration is completely passive and is used by
some .net classes to perform their validation work. What would be
performing this work in PHP?
It also raises some future compatibility questions: if we would want to
have named parameters for functions it'd be very awkward if we had one
syntax for named parameters here and another for functions.
A similar type of thing could occur for PHP, the recent use case of
Nullable for Type Hints would be a great use of such attributes, but
I'm not sure it would be the same, as type hints are supposed to be
validated automatically on each call, and data annotations, of which you
brought the example, do not work like that, if I understand this correctly:
http://stackoverflow.com/questions/6496705/how-do-data-annotations-work
class a {
[php:Param($s) = StringLength(4, ErrorMessage='Parameter $s length
cannnot exceed 4.', ErrorLevel=E_USER_ERROR)]
public function foo($s) { ... ]
}
--
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227
Hi internals,
I would like to give you my thoughts about annotations.
An annotation must not change the code behavior but add a useful
information for the users or tools.
The syntax used most of the time is very restrictive (such as
Foo('Bar'), DateType('datetime'), MinLength(42) etc.). We cannot express
any logic formula, disjunction, conjunction or anything else. There are
other annotation and specification languages, that exist for PHP and
that are much more complete. So, the referenced RFC is very very
restrictive. The purpose of annotations could be larger than "weakly
type" some data, because it can contain informations of very different
natures.
Fortunately, there is a common syntax between all existing ones. In Java
or PHP, we use the @ symbol to introduce a keyword, followed by a
description. The set of keywords with their descriptions is an
annotation. For instance: @param, @return, @requires, @ensures,
@throwable etc. The @ symbol can be different but it is not the purpose
for now. So, if PHP would propose an API, it would be a way to get the
description of a keyword. Something like:
$reflectionAnnotation->getValue('requires') for example, or
$reflectionAnnotation['requires']. Then, it is part to the user or the
tool to analyse (maybe to parse) the description of the keyword to
give it a semantics. It would be a compromise between all existing
implementations and languages, but it will not close the door to more
sophisticated annotation or specification languages.
The fact that it is part to the user or the tool to analyse the
description is not a bad thing. Analyzing annotations should be static,
not dynamic (i.e. during the runtime). Maybe there are different points
of view but as annotations must not change the code behavior, runtime
use cases are very rare.
Then, there is also a confusion between API documentation (not just
simple documentation) and annotations. API documentation is an
annotation. It does not change the code behavior, it is a useful
information for users and tools, so it is an annotation. There is
different API documentation syntaxes (or languages), but most of them
also introduce descriptions by the @ symbol combined with a keyword, so
it respects my previous words.
As an example of what kind of annotations we are able to have:
contracts. This is a more complex example of a specification. It does
not change the code behavior, it is a very important information for the
user and some tools that automate the test process (by making
contract-based testing or the design-by-contract paradigm).
So, to summarize myself, I propose that PHP has a native parser for the
following annotation grammar (not in a formal syntax):
@keyword description;
Maybe, a description can be a block, thus we have:
@keyword { description }
And in the description, we could have other keywords:
@keyword {
@key description;
@word description;
}
It also could be useful to label/index the keyword, maybe by using the
following syntax:
@keyword[label] description;
It could fit the most existing use cases around without closing the door
to "exotic" (i.e. not common) ones, such as contracts or alike
specifications.
Best regards.
Just starting a new thread here to discuss true annotations vs a
DocBlock Parser:RFC Referenced:
https://wiki.php.net/rfc/annotations
I've started working on a new proposal, but I'm getting hung up on the
syntax - if we can't use angle brackets anymore, what can we use?
Virtually
every symbol on a standard US keyword is an operator of some sort, does
that mean those are all out of the question?e.g. thinking of concrete possible basic syntax, neither of the
following
delimiters would work:[Foo('bar')]
Why would this not work? I'm struggling to think of a place where one
would want to use an annotation where it could be misinterpreted as an
array literal. If anything, the visual "conflict" or association with
the array syntax is a good thing in my book: my brain parses it as an
array of one or more annotations.
I agree here, I think the above, if possible would be best. In my
mind annotations should proabably be limited in scope to class
declarations and thus only before a class keyword, before a property
or method declaration.In none of those scopes would [ ] be a parsing issue I believe...
The one case would be at the beginning of a class, but if simply added
something such as:
[:SomeAttribute(xyz,abc),SomeAttribute2]It could never be confused with short array syntax and is still brief.
--
Ivan Enderlin
Developer of Hoa
http://hoa.42/ or http://hoa-project.net/
PhD. student at DISC/Femto-ST (Vesontio) and INRIA (Cassis)
http://disc.univ-fcomte.fr/ and http://www.inria.fr/
Member of HTML and WebApps Working Group of W3C
http://w3.org/
Annotations can be nested so in this case [Foo([BAR])] there is a big
ambiguity and we can not determine if [BAR] is an array with the BAR
constant in it or an annotation.
Pierrick
In none of those scopes would [ ] be a parsing issue I believe...
Regarding syntax... Would this work?
<|foo|>
<|bar( <|baz|> )|>
best regards
Patrick
No please, two symbols for each side looks ugly.
BTW There's number sign (#) which is, as far as I remember, not used in
PHP at all. Could be something like:
#JoinColumn(name="...", type="...", ...)
#Foo(Bar())
Or
#Foo(#Bar())
(should we put a "annotation-sign" in front of a nested annotation?)
Regarding syntax... Would this work?
<|foo|>
<|bar( <|baz|> )|>best regards
Patrick
The # would be parsed as a comment
Kind Regards
Pierre du Plessis
Cell: 072 775 3477
Fax: 086 650 4991
Email: info@customscripts.co.za admin@customscripts.co.za
www: http://www.customscripts.co.za
No please, two symbols for each side looks ugly.
BTW There's number sign (#) which is, as far as I remember, not used in
PHP at all. Could be something like:
#JoinColumn(name="...", type="...", ...)
#Foo(Bar())Or
#Foo(#Bar())
(should we put a "annotation-sign" in front of a nested annotation?)
Regarding syntax... Would this work?
<|foo|>
<|bar( <|baz|> )|>best regards
Patrick
is an alternative syntax for comments
#Foo(#Bar())
I think this RFC syntax is outdated. We can remove the whole new syntax and
just make everything between <> php code that returns the last statement
because of the array short syntax this ends up to be stuff like:
<['foo' => bar']>
<['foo' => foo()]>
<['foo' => new Foo('bar')]>
This would greatly simplify the feature, because then its just PHP code and
everybody allready knows that.
Just starting a new thread here to discuss true annotations vs a DocBlock
Parser:RFC Referenced:
https://wiki.php.net/rfc/**annotationshttps://wiki.php.net/rfc/annotations
I've started working on a new proposal, but I'm getting hung up on the
syntax - if we can't use angle brackets anymore, what can we use?
Virtually
every symbol on a standard US keyword is an operator of some sort, does
that mean those are all out of the question?e.g. thinking of concrete possible basic syntax, neither of the following
delimiters would work:[Foo('bar')]
Why would this not work? I'm struggling to think of a place where one
would want to use an annotation where it could be misinterpreted as an
array literal. If anything, the visual "conflict" or association with
the array syntax is a good thing in my book: my brain parses it as an
array of one or more annotations.I agree here, I think the above, if possible would be best. In my mind
annotations should proabably be limited in scope to class declarations and
thus only before a class keyword, before a property or method declaration.In none of those scopes would [ ] be a parsing issue I believe...
The one case would be at the beginning of a class, but if simply added
something such as:
[:SomeAttribute(xyz,abc),**SomeAttribute2]It could never be confused with short array syntax and is still brief.
--
-Clint
Perhaps I am blind, but I do not see where in the RFC is defends its
choice to use <>. Every other language I know of uses @, and I do
not know of technical reasons why we couldn't use the same symbol.
Annotations wouldn't be able to contain expressions so there wouldn't
be anything that could generate a suppressible error.
Every other language used :: or . for namespaces. The problem with @ is its
definition as error suppression operator, and Guilherme and Pierrick didn't
come up with a solution to stay BC using the @. Additionally some other
languages use [] (which also doesnt work in PHP).
On Wed, Jan 9, 2013 at 4:15 PM, Levi Morrison morrison.levi@gmail.comwrote:
Perhaps I am blind, but I do not see where in the RFC is defends its
choice to use<>. Every other language I know of uses@, and I do
not know of technical reasons why we couldn't use the same symbol.
Annotations wouldn't be able to contain expressions so there wouldn't
be anything that could generate a suppressible error.
Levi,
On Wed, Jan 9, 2013 at 10:15 AM, Levi Morrison morrison.levi@gmail.comwrote:
Perhaps I am blind, but I do not see where in the RFC is defends its
choice to use<>. Every other language I know of uses@, and I do
not know of technical reasons why we couldn't use the same symbol.
Annotations wouldn't be able to contain expressions so there wouldn't
be anything that could generate a suppressible error.
Think about a function declaration:
@param("bar")
function foo($bar) {}
What's the parser supposed to do there? Is it an annotation? Or an
error-silenced function call?
Granted, leaving off the ; may make it possible to parse without
ambiguity (since the @ - Const String - ( - ... - ) sequence, followed by a
function declaration direclty may be possible)...
But it's ambiguous at best (especially to read)...
Anthony
Levi,
On Wed, Jan 9, 2013 at 10:15 AM, Levi Morrison morrison.levi@gmail.com
wrote:Perhaps I am blind, but I do not see where in the RFC is defends its
choice to use<>. Every other language I know of uses@, and I do
not know of technical reasons why we couldn't use the same symbol.
Annotations wouldn't be able to contain expressions so there wouldn't
be anything that could generate a suppressible error.Think about a function declaration:
@param("bar")
function foo($bar) {}What's the parser supposed to do there? Is it an annotation? Or an
error-silenced function call?Granted, leaving off the
;may make it possible to parse without ambiguity
(since the @ - Const String - ( - ... - ) sequence, followed by a function
declaration direclty may be possible)...But it's ambiguous at best (especially to read)...
Anthony
Maybe I'm a complete fool, but since annotations aren't executed (they
are declarative only), this should cause no problems.
Levi
Maybe I'm a complete fool, but since annotations aren't executed (they
are declarative only), this should cause no problems.
You're not a fool. And the point is not that they are executed, but because
they are nearly syntactically identical to executable code. So parser and
readability wise they can be easily confused. Which is the problem...
Anthony
they are nearly syntactically identical to executable code.
"nearly" is the keyword there. They lack the ending semi-colon. Sure,
this might mean PHP has to actually use an abstract syntax tree, but
that's long overdue in my opinion. I know others disagree. This is
only tangentially related, so I won't say more.
they are nearly syntactically identical to executable code.
"nearly" is the keyword there. They lack the ending semi-colon. Sure,
this might mean PHP has to actually use an abstract syntax tree, but
that's long overdue in my opinion. I know others disagree. This is
only tangentially related, so I won't say more.
Even if the parser is adjusted to cope with that, it's still an
extremely subtle difference for developers to keep track of. Consider
the following procedural snippets:
@Foo[narf]
function something($narf) {}
@Foo[narf];
function something($narf) {}
The first one says that $narf should pass @Foo validation.
The second one says to call the function Foo with the string constant
"narf", and then define a function called something().
That's the sort of subtle bug that's just begging for someone to make an
honest typo and spend the next 6 hours tracking it down, until he
realizes what he did and proceeds to bang his head against his desk in
frustration for missing such a "simple" error.
Let's not subsidize the headache drug manufacturers with PHP syntax
decisions. :-)
--Larry Garfield
Let's not subsidize the headache drug manufacturers with PHP syntax
decisions. :-)
Too late.
On Wed, Jan 9, 2013 at 5:20 PM, Larry Garfield larry@garfieldtech.comwrote:
they are nearly syntactically identical to executable code.
"nearly" is the keyword there. They lack the ending semi-colon. Sure,
this might mean PHP has to actually use an abstract syntax tree, but
that's long overdue in my opinion. I know others disagree. This is
only tangentially related, so I won't say more.Even if the parser is adjusted to cope with that, it's still an extremely
subtle difference for developers to keep track of. Consider the following
procedural snippets:@Foo[narf]
function something($narf) {}@Foo[narf];
function something($narf) {}The first one says that $narf should pass @Foo validation.
The second one says to call the function Foo with the string constant
"narf", and then define a function called something().That's the sort of subtle bug that's just begging for someone to make an
honest typo and spend the next 6 hours tracking it down, until he realizes
what he did and proceeds to bang his head against his desk in frustration
for missing such a "simple" error.Let's not subsidize the headache drug manufacturers with PHP syntax
decisions. :-)--Larry Garfield
I agree with the risks here.
But i also really prefer a Token: <content> approach then a [open token]
<content> [close token] approach
Can we use a combination? like:
@annot: Foo[narf]
--
Rafael Dohms
PHP Evangelist and Community Leader
http://doh.ms
http://wwwamsterdamphp.nl
Why don't we pick a commonly used annotation symbol like * then? It
currently can't start an expression so there's not an ambiguity (that
I can think of).
be anything that could generate a suppressible error.
Not true:
@ORM\Column()
class Test() {
}
What if there's a function in the ORM namespace called Column.
Is this a supressed error of a function call and we've missed the ";"
or is it an annotation?
Hi!
Just starting a new thread here to discuss true annotations vs a
DocBlock Parser:RFC Referenced:
Didn't look into it in detail but one note - can we please come up with
something that doesn't look like broken HTML?
--
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227