lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]


Actually the form "@ID(parameters)" is used in Java, but the host language construct is not embedded inside the parameters of annotations (which are special constructor invocations that will instanciate separate objects, linked to the host language).
They have various use. The oldest form was for hinting the documentation (allowing inserting parsable comments that would be able to build API help files for example). But they evolved to be insertable in many places.
The rule (with which I agree) was to not modify the host language (or modify it a minimum: they are allowed almost anywhere a whitespace is allowed): you can always safely remove the whole annotation and parse the rest of the source code and compile it: all annotations are ignorable if needed and this should not make the program invalid and not working as expected (even if this causes some additional costs in memory or speed when not using them).
As well annotations should be complete bny themselves, not separated in multiple parts, so:
- the concept of using "!" as a prefix, and "{...}" is suffix for parameters is bad, and in fact it just adds various syntaxic ambiguities which are hard to resolve: this would prohibit using "{...}" table constructors in the host language)
- the same is true when using "@ID(..." for the annotation, followed by the host language constructor, and terminated just by a ")" would also be very quirky (dangerous I think)

My opinion is the the non-ambiguous form for annotation is: - "@ID" without parameters, or "@{ID, parameter...}". Then where we can place the whole annotation to attach it to the host language construct if left to specify (but these annotation tags can normally occur only between host tokens where spaces are allowed.
There may however be a need for annotation with long scopes (applying to multiple host-language constructs). Their form could be "@{begin ID, parameter...}"  for the begining of scope, and ""@{end ID}" for the end of scope (the additional reindication of the annotation ID may help diagnose non matching end).

Now we can as well use "{}" or "()" or "[]" or "<>" to bracket the annotation ID and its parameters in the same tag (either the opening tag or close tag). The initial bracket is disambiguated by the leading "@", which should be one of the character unassigned in Lua: "@" is perfect for that fine (I don't like using "!" because sooner or later it will become an interesting operator).

Note that annotations have their own namespace: they create a secondary metadata language. Binding the metadata language to a specific recognizer (with its own resource loaders and so on) can also use scopes. For this reason, it would be convenient to support not just the forms "@ID" or "@{ID, parameters...}" or "@{begin ID, parameters...}, or "@{end ID}", but also "@namespace:ID" or "@{namespace:ID, parameters...}" or "@{begin namespace:ID, parameters...}, or "@{end namespace:ID}".

The identifiers without namespaces should be reserved to Lua specification (or there would be a special namespace declaration to specify which namespace is attached to annotation IDs without namespaces). Other metatdata languages will use their own namespaces. Namespaces may be either "strings" (like "org.lua") or suites of IDs separated by dots or columns. I have no preference about it:

If there are syntaxic ambiguities, the simple form "@namespace:ID" or "@ID" should always be equivalent (as a shortcut notation) for the complete annotation tag using delimiting brackets like "@{ID}" or "@{namespace:ID}" (i.e. the "{}" brackets surrounding the annotation typename and its parameters is also correct without parameters).






Le jeu. 25 avr. 2019 à 18:29, Sean Conner <sean@conman.org> a écrit :
It was thus said that the Great Dibyendu Majumdar once stated:
> On Thu, 25 Apr 2019 at 06:54, Dirk Laurie <dirk.laurie@gmail.com> wrote:
> >
> > Op Do. 25 Apr. 2019 om 03:33 het Philippe Verdy <verdy_p@wanadoo.fr> geskryf:
> > > I also agree that the "*xxx" or "*(xxx, params...)" syntax is very fuzzy and will not work with the future evolution of annotations
> > >
> > > Le jeu. 25 avr. 2019 à 00:22, Dibyendu Majumdar <mobile@majumdar.org.uk> a écrit :
> > >> I am writing about this again in the hope that it is not too late to
> > >> change the syntax of the *toclose attribute. I think there is an
> > >> opportunity to allow a general way of introducing annotations in Lua,
> > >> which can be exploited by extensions. It would be sad if that
> > >> opportunity is lost.
> >
> > Therefore I would suggest that an annotation starts with ! and
> > continues until but not including the first termination character.
> > Sensible termination characters might be comma, semicolon and end-of
> > line, allowing annotations for every item in a parameter/return list,
> > table constructor etc, but not encumbering the parser with a difficult
> > decision whether the annotation is done. In the contex of "local", an
> > empty annotation could default to 'toclose', so that "local a!, b, c!`
> > is all that one needs to supply "toclose" directives.
> >
>
> I would suggest that the syntax should be:
>
> <special character><optional name><optional table with only literal
> keys and values>

  So I'm looking at Java because they now have annotations.  >>From a cursory
look, it appears the syntax to be:

        '@' ID

  So things like

        @Override
        @Deprecated
        @SuppressWarnings

  Annotations can be used at development time, compile time or runtime [1].
They can also be targetted towards a particular usage [2].  In Java, custom
annotations are handled with creating an interface.

  Assuming we use something similar to Java, the "to-close" annotation of
Lua 5.4 could probably look somthign like:

        @target(local)
        function @to_close(var)
          -- whatever this does
        end

        do
          local @to_close file = io.open(...)
          lcoal @to_close obj  = custom:blah(...)
          -- code code code
        end

> So assuming your choice of !, we could have:
>
> local a!
> local b !go_to_space { when=true }
> local c !array { 20 }

  Well ...

        local @my_annotation a
        local @go_to_space { when = true } b
        local @array(20) c

where '@array' is a special function called with certain parameters
depending on what it's targetting and any parameters given to it.  Too
magical?  Not magical enough?  Too much like Java? I don't know, it's
beginning to look a bit heavy to me.

  -spc

[1]     https://stackoverflow.com/questions/1372876/how-and-where-are-annotations-used-in-java

[2]     https://beginnersbook.com/2014/09/java-annotations/