Feature: AST annotations

[elsassph]

Annotations are metadata expressions attached to AST statements.

• any statement can receive multiple annotations,
• annotations can be on the same line as the statement,
• annotations can have arguments; arguments can be any valid BrightScript expression,
• name of the annotation must be a valid identifier; it can't be a keyword (e.g. sub, while...),
• annotations have a method to obtain JS-friendly types (annotation.getArguments()); basic types, arrays and roAssocArrays are converted.

Limitation:

• annotations aren't validated if they are mis-named; could be declared by the plugins using them in the future,
• currently these expressions are not walked, for various reasons.

Example:

@someFlag
sub someFunction()
  '...
end sub

@configuration("param", [1, 2, 3], { prop: "value" })
@andAnotherFlag
function anotherFunction()
  @translate print "this can also have meta"
end function

@replaceWith(45 * 3, sub ()
  print "you could have whole expressions here - why tho?"
end sub)
sub replaceMe()
    '...
end sub

A plugin can explore the AST and look at the annotations:

const annotations = statement.annotations;
if (annotations) {
    annotations.forEach(a => console.log(a.name, a.getArguments()));
    // ex: configuration ["param", [1, 2, 3], { prop: "value" }]
}

[georgejecook]

simply marvellous. I will put this to good use. Thanks @elsassph

[TwitchBronBron]

shouldn't this be this.pendingAnnotations.length > 0?

[TwitchBronBron]

If you're ordering these alphabetically, might as well swap functionStatements and functionExpressions too.

[TwitchBronBron]

@elsassph this looks great. As soon as you address this comment I'll be ready to merge.