Lexical Structure of the Alexa Conversations Description Language

An Alexa Conversations Description Language (ACDL) file is an ordered sequence of Unicode characters encoded in UTF-8.

The lexical processing of an ACDL file consists of transforming the file into a sequence of whitespaces, line-end signifiers, comments, and tokens.

Whitespace

Whitespace is any non-empty sequence of characters that consists of only the ASCII space and tab character. Whitespace serves only to separate tokens and has no semantic significance.

 WS : [ \t]+;

Line-end signifiers

Line-end signifiers are one or more LF or CR LF ASCII characters. You use them to separate namespace declarations, import declarations, and action declarations. In all other contexts, a line-end signifier serves as a separator for tokens.

LINE_TERMINATOR : NewLine+;
NewLine : '\r'?'\n'

Punctuators

ACDL has the following punctuators: braces, brackets, parenthesis, and angle brackets.

Braces

You use braces for the following purposes:

LBRACE       : '{';
RBRACE       : '}';

Brackets

You use brackets to declare lists. You also use brackets to index into a list to access the item at that index.

LBRACK       : '[';
RBRACK       : ']';

Parentheses

You use parentheses for the following purposes:

LPAREN       : '(';
RPAREN       : ')';

Angle brackets

When you're not using angle brackets as Boolean operators, you use angle brackets to provide the type parameters for generic types or the type arguments for an action.

GT           : '>';
LT           : '<';

Comments

ACDL supports two types of comments: line comments and block comments. Line comments start with the characters // and extend to the end of the line. Block comments start with the characters /* and end with the characters */. Block comments can span multiple lines.

Comments don't nest. The character sequences /* and */ have no special meaning within a line comment, and the character sequences // and /* have no special meaning within a block comment.

The ACDL compiler doesn't process comments within string literals.

// This is a line comment

/* This is
   a block comment
*/

dialog Nothing myDialog { // This is also a line comment
  sample { ... }
}

dialog /* this is also a block comment */ Nothing myDialog {
  sample { ... }
}

Tokens

Tokens form the vocabulary of the language. There are four kinds of tokens: keywords, identifiers, literals, and operators.

Keywords

The following is the list of the keywords in ACDL. You can't use keywords as names in any declaration, or as components in the name of a namespace declaration.

  • namespace
  • import
  • dialog
  • sample
  • action
  • type
  • optional
  • if
  • else
  • default

You also can't use literals true, false, and nothing as a name in a declaration.

Forbidden keywords

The word default is a forbidden keyword; you can't use it in an ACDL file.

Identifiers

An identifier is any non-empty sequence of characters in the following form:

  • The first character is a letter or _.
  • The remaining characters are alphanumeric or _.
IDENTIFIER : Letter LetterOrDigit*;
LetterOrDigit : Letter | Digit;
Letter : [_a-zA-Z];
Digit : [0-9];

A token that consists only of _ is not a valid identifier.

Literals

A literal is a single token that directly represents the value of a primitive.

String literals

A string literal consists of zero or more characters enclosed in double quotes, as in "hello." A string literal can include simple escape sequences (such as \t for the tab character) and Unicode escape sequences.

STRING_LITERAL   : '"' (~["\\\r\n] | EscapeSequence)* '"';

fragment EscapeSequence
    : '\\' [btnfr"'\\]
    | '\\' ([0-3]? [0-7])? [0-7]
    | '\\' 'u'+ HexDigit HexDigit HexDigit HexDigit
    ;

fragment HexDigit
    : [0-9a-fA-F]

A string literal is always of type String.

String interpolation

You can annotate the string literals that you use for the samples of the utterances() action with braces to enclose the properties of the given T type.

Number literals

A number literal consists of one or more digits and can include one dot (.).

NUMBER_LITERAL : Digit+ ('.' Digit+ )?

Digit : [0-9];

A number literal is always of type Number.

Boolean literals

There are two literals, true and false, of type Boolean.

BOOL_LITERAL   : 'true' | 'false';

Nothing literal

There is a single value of the type Nothing denoted by nothing.

NOTHING_LITERAL  : 'nothing';

Operators

Operators are short versions for the following actions that return a Boolean result, except the assignment operator (=), declared in the Alexa Conversations Core Library (ACCL). For example, > is equivalent to the gt() action.

The following table shows the precedence of operators.

Operator Usage Action declaration
> To do a "greater than" comparison of two expressions of type Number. action Boolean greater(Number left, Number right)
< To do a "less than" comparison of two expressions of type Number. action Boolean less(Number left, Number right)
>= To do a "greater than or equal" comparison of two expressions of type Number. action Boolean greaterEqual(Number left, Number right)
<= To do a "less than or equal" comparison of two expressions of type Number. action Boolean lessEqual(Number left, Number right)
== To compare two expressions and evaluates to true if both the expressions have the same value. action Boolean equal<T>(T left, T right)
!= To compare two expressions and evaluates to false if both the expressions have the same value. action Boolean notEqual<T>(T left, T right)
! To do a logical NOT of a Boolean type expressions. action Boolean not(Boolean expression)
&& To do a logical AND of two Boolean type expressions. action Boolean and(Boolean left, Boolean right)
|| To do a logical OR of two Boolean type expressions. action Boolean or(Boolean left, Boolean right)

Assignment operator

You use the assignment operator (=) to declare new names in named expressions. You also use the assignment operator in an action declaration to specify the default value of an argument and in a call expression to assign an expression to an argument.

Operator precedence

There are six precedence levels for operators. ! has the highest precedence, followed by relational (>, <, >=, <=) operators, equality (==, !=) operators, &&, ||, and finally =.

The following table shows the operator precedence, from highest to lowest.

Precedence Operator
6 !
5 > < >= <=
4 == !=
3 &&
2 ||
1 =

Lists

The [ <expression > ] syntax denotes a List expression.

numbers = [ 1, 2, 3 ]

In ACDL, the previous expression is short for the following, which is also valid ACDL syntax.

numbers = List<Number> [ 1, 2, 3 ]
Was this page helpful?

Last updated: Nov 27, 2023