2. Grammar

2.1. Lexical Conventions

As a super language on top of ECMAScript, the same lexical conventions are supported as described in [ECMA11a(p.S7)] within strict mode. Some further constraints are defined, however, restricting certain constructs. These constraints are described in the following.

2.1.1. Identifier Names and Identifiers

Cf. [ECMA11a(p.S7.6)], [ECMA11a(p.S11.1.2, p.p.63)] and [ECMA11a(p.S01.2, p.p.51ff)].

As a reminder, identifiers are defined as follows in the ECMAScript specification:

IdentifierName: IdentifierStart* IdentifierPart;
IdentifierStart : UnicodeLetter | '_';
                \ UnicodeEscapeSequence

N4JS supports a limited form of computed-names for member declarations:

N4JSPropertyComputedName:
    '[' (SymbolLiteralComputedName | StringLiteralComputedName) ']'
;

SymbolLiteralComputedName: N4JSIdentifier '.' N4JSIdentifier ;

StringLiteralComputedName: STRING ;

As can be seen, a computed-name must be either

  • a symbol reference, e.g., Symbol.iterator

  • a string literal, i.e., a compile time known constant. This notation is useful when interoperating with libraries that define members whose names contain special characters (e.g., a field name starting with commercial-at)

In N4JS, identifiers are further constrained in order to avoid ambiguities and to make code more readable. Some of these constraints will lead to errors, others only to warnings. They do not apply for identifiers declared in definitions file (n4jsd) in order to enable declaration of external entities.

Req. IDE-1: N4JS Identifier Restrictions (ver. 1)

  1. If the following constraints do not hold, errors are created.

    1. Leading $ (dollar sign) character is prohibited for any variable name such as fields, variables, types functions and methods.

    2. Leading _ (underscore) character is not allowed for identifying any functions or methods.

Req. IDE-2: N4JS identifier recommendations (ver. 1)

  1. If the following constraints do not hold, warnings are created.

  2. Variable names should, in general, be constructed form the 26 ASCII upper and lower case alphabetic letters (a..z, A..Z), from the 10 decimal digits (0..9) and from the _ (underscore). Although the usage of the international characters are allowed (according to the ECMAScript specification) it is discouraged because these characters may not be read or understood well in every circumstance [3].

    1. Type (and Type Variable) Identifiers

      TypeIdentifier: [_A-Z][_a-zA-Z0-9]*
TypeVariableIdentifier: [_A-Z][_a-zA-Z0-9]*

    2. Package Identifiers

      PackageIdentifier: [_a-z][._a-zA-Z0-9]*; // i.e. the folder names, must not end with .

    3. Member Identifiers and Enum Literals

      InstanceFieldIdentifier: [_a-z][_a-zA-Z0-9]*
StaticFieldIdentifier: [_A-Z][_A-Z0-9]*([_A-Z0-9]+)*
EnumLiteral: [_A-Z][_A-Z0-9]*([_A-Z0-9]+)*

    4. Variable and Parameter Names

      VariableIdentifier: [_a-zA-Z0-9]*
􏰀ParameterIdentifier: [_a-z][_a-zA-Z0-9]*

    5. Methods

      MethodIdentifier: [_a-z][_a-zA-Z0-9]*;

    6. Annotations

      AnnotationIdentifier: [_A-Z][_a-zA-Z0-9]*

The following rules describe how fully qualified names of elements are created. Note that these fully qualified names cannot be used in N4JS directly. Though they may be shown in error messages etc. to identify elements.

TypeIdentifier:         [A-Z][a-zA-Z0-9]*;
PackageIdentifier:      [a-z][a-zA-Z0-9]*;
FQNType:                (PackageIdentifier '.')+ TypeIdentifier;

2.1.2. This Keyword

Cf. [ECMA11a(p.S11.1.1, p.p.63)]

2.1.3. Regular Expression Literals

Cf. [ECMA11a(p.S7.8.5)]

2.1.4. Automatic Semicolon Insertion

Cf. [ECMA11a(p.S7.9)]

ASI is supported by the parser, however warnings are issued.

2.1.5. JSDoc

JSDoc are comments similar to JavaDoc in Java for documenting types, functions and members. There is no semantic information expressed in JSDoc, that is, the behavior of a program must not change if all the JSDoc is removed. The JSDoc tags and overall syntax is a mixture of tags defined by the Google Closure Compiler, Java’s JavaDoc tool and N4-specific tags.

JSDoc comments are multiline comments, starting with /** (instead of simple multiline comments, starting with /*).

MultiLineComment: '/*' MultiLineCommentChars? '*/'  // from ECMAScript specification
JSDoc:            '/**' MultiLineCommentChars? '*/'

In general, JSDoc comments are placed directly before the annotated language element. In some cases, this is slightly different, such as for method parameters, for example, where it is then explicitly specified.

The content of JSDoc comments will be covered in more detail in upcoming chapters. For documentation purposes, multi- and single-line descriptions are used in several constructs.

MLVALUE:         ([^@]+[^\n]+)+;
SLVALUE:         ([^\n]+);
MLVALUE

short for multi-line value. This is usually only used for the general description of types or members.

SLVALUE

short for single-line value. This is a description which ends at the end of a line. It is usually used in combination with other tags, e.g., to further describe a parameter of a method.

Quick Links