3.0 Abstract Syntax Tree (AST)

This section describes the nodes of a RD-VBA abstract syntax tree, which is the output of the parser.

3.0.1 Token Semantics

The token semantics of RD-VBA are as specified by MS-VBAL, with the exception(s) described in this sub-section.

Note

RDCore uses the same grammar as the legacy Rubberduck project; this grammar was designed around the MS-VBAL specifications and is deemed compliant enough to be able to generate a concrete syntax tree (CST) that can be traversed to produce an abstract syntax tree that is appropriately structured and detailed for RD-VBA.

Token semantics are be provided to the parser by a ITokenSemanticsProvider that is implemented by the environment host and may provide semantics that may themselves be provided by platform-level extensions.

The token semantics provider specifics are not yet designed, but its requirements are as follows:

  • The provider accepts a base Antlr4.Runtime.

3.0.1.1 Comment Annotations Syntax

RD-VBA comments can contain semantically meaningful metadata in the form of annotations, that both the language core and platform extensions can consume as they see fit.

Annotations can bind to:

  • Modules
  • Members (declarations, procedures)
  • Statements in a logical line of code.

There are different rules of annotation bindings, depending on their intended target:

  • Module annotations may only be used to bind at module level and must be specified in the declarations section;
  • Member annotations must appear immediately above the member declaration;
  • It is implementation-dependent how any other annotation types bind to their target.
Note

This explicit disambiguation is necessary, because an edge case allows an annotation comment on the last line of the declarations section to perhaps unexpectedly bind to the first module procedure member instead of the module itself if there is no vertical empty space between them.

Exactly what annotations are supported or semantically meaningful is implementation-dependent.

3.0.1.1 Annotation List

Annotations may appear as a comma-separated annotations list, defined as follows:

annotationList: SINGLEQUOTE (AT annotation)+ (COLON commentBody)?;

Where:

  • SINGLEQUOTE is a comment marker token;
  • AT is a literal @ token;
  • COLON is a literal : token;
  • LPAREN is a literal ( token;
  • RPAREN is a literal ) token;
  • COMMA is a literal , token;
  • WS is a literal whitespace token;
  • LINE_CONTINUATION consists of a whitespace followed by a literal _ underscore token.

👉 Note that anything that follows a : colon is considered a regular comment.

3.0.1.2 Annotation

The annotation itself consists of its name and an optional argument list:

annotation: annotationName annotationArgList? whiteSapce?;
whiteSpace : (WS | LINE_CONTINUATION)+;

Where:

  • WS is a literal empty space token;
  • LINE_CONTINUATION consists of an empty space followed by a literal _ underscore token;
  • unrestrictedIdentifier may be any valid identifier name.

Examples:

  1. Marker annotation
'@ExampleAnnotation : this is a regular comment that may explain why there's an annotation here.
  1. Annotation list
'@ExampleAnnotation1, @ExampleAnnotation2
  1. Parameterized

Annotations may be parameterized. If the annotation is part of an annotations list, the arguments must be enclosed in parentheses, otherwise they are optional:

'@ExampleAnnotation "Argument1", 42
'@ExampleAnnotation("Argument1", 42)
'@ExampleAnnotation("Argument1", 42), @ExampleAnnotation2

3.0.1.3 Annotation Arguments

Tip

Whether annotation arguments can be another type of expression than literal expressions is host-dependent; annotation comments are not intended to be executable.

annotationArgList:
annotationArgList : 
    whiteSpace? LPAREN whiteSpace? annotationArg whiteSpace? RPAREN
    | whiteSpace? LPAREN whiteSpace? RPAREN
    | whiteSpace? LPAREN annotationArg (whiteSpace? COMMA whiteSpace? annotationArg)+ whiteSpace? RPAREN
    | whiteSpace annotationArg
    | whiteSpace annotationArg (whiteSpace? COMMA whiteSpace? annotationArg)+
;
annotationArg : expression;
whiteSpace : (WS | LINE_CONTINUATION)+;

Where:

  • LPAREN is a literal ( token;
  • RPAREN is a literal ) token;
  • COMMA is a literal , token;
  • WS is a literal empty space token;
  • LINE_CONTINUATION consists of an empty space followed by a literal _ underscore token.

3.0.2 Node Types

All AST nodes inherit BoundNode, an abstract node that associates a semantic ID (Uri) with a specific location in a workspace source file.

The node types directly derived from BoundNode are as follows:

3.0.3 Binding Contexts

MS-VBAL§5.6.4 breaks down expression binding contexts (for resolving name lookups) as follows:

  • Default binding context used by most expressions;
  • Type binding context used by expressions that expect to reference a type or class name;
  • Procedure pointer binding context used by expressions that expect to return a pointer to a procedure;
  • Conditional compilation binding context used by expressions within conditional compilation statements.

The RDCore interpretation is reflected in its modelization as follows:

  • 🎯 name lookups become an explicit evaluation step involving specific AST nodes such as VBSimpleNameExpression;
  • 🎯 Evaluation returns an evaluation result record describing and encapsulating the result, or runtime error metadata.

Because the type system includes and leverages meta-types such as VBTypeDescValue, the binding context is easily inferred from the managed type of a provided value.

Warning

Because a VBTypeDescValue is a data value that represents a data type, the implementation of both static and runtime semantics must be mindful of the possbility of accidentally pattern-matching such a type descriptor.

In this section

⏮️ RD-VBAL §2.0 Computational Environment | ⏭️ RD-VBAL §4.0 Program Structure

Edit this page