Annotation Proposal

Annotations

Annotations are values stored in chunks and function definitions accessed through the Closure class. These allow for Metadata to be included in scripts. This is enabled only for C-Like mode.

Writing Annotations

Annotations for chunks will be specified in code with @name value, the name immediately following the @ symbol, and the value being the rest of the source line after the first encountered whitespace.

Annotations for functions will be similar, but be specified with @@ at the start of the line. These annotations will be stored with the next function definition. It will be illegal to have @@ hanging at the end of a source file, this will throw a compiler error.

@meta one

@@functionmeta two words
function hello()
{

}

This will add the annotation meta:one to the chunk, and the annotation functionmeta:two words to the hello() function.

Enabling Annotations

ScriptOptions will contain an instance of IAnnotationPolicy, an interface defined by:

public interface IAnnotationPolicy
{
    bool ErrorOnDisallowed { get; }
    bool IsAnnotationAllowed(string name);
}

IsAnnotationAllowed will control whether or not an annotation is stored by the compiler, based on the name provided. If an annotation is not allowed, and ErrorOnDisallowed is set to true a compiler error will be thrown. This allows consumers to protect against typos in annotations.

Three default policies will be implemented, AnnotationPolicies.Allow, AnnotationPolicies.Ignore, AnnotationPolicies.Error. These will allow all annotations, ignore all annotations, or error on any annotation respectively. The default value will be set to Allow.

Loading from bytecode will bypass the annotation policy as it only controls the compiler.

Accessing Annotations

Add to Closure class. Default initialised to Array.Empty<ClosureAnnotation>() Use the LoadFile/LoadString/LoadStream functions of script to get a DynValue containing the closure for the main script chunk.

public ClosureAnnotation[] Annotations { get; private set; }

public class ClosureAnnotation
{
    public string Name { get; private set; }
    public string Value { get; private set; }
    
    public ClosureAnnotation(string name, string value)
    {
        Name = name;
        Value = value
    }
}

In the bytecode these annotations will be stored in a special Annot instruction included immediately after Meta. If there are no annotations, no Annot opcode will be emitted.