Language Syntax
This section is normative.This section of the document defines the types used within this specification using EBNF notation with corresponding railroad diagrams.
Atomic Types
literal
A literal is a terminal atom that may be assigned to a variable, used in a dictionary, or used as an operand to build an expression.
literal ::= string | number | boolean | 'null'
boolean
A boolean may take on values true or false.
boolean ::= 'true' | 'false'
name
A name is a sequence of characters conforming to those in the [[XML-NAMES]] standard.
name ::= [ http://www.w3.org/TR/xml-names/#NT-NCName ]
quote_start
A quote_start is the starting quotation mark, which indicates the beginning of a string.
quote_start ::= '"' '`'
quote_close
A quote_close is the ending quotation mark, which indicates the termination of a string.
quote_close ::= '`' '"'
string
A string literal represents a finite sequence of characters. It is surrounded by starting and ending quotation marks.
string ::= quote_start name quote_close
"`hello`"
digit
A digit represents a real valued integer in the range [0-9].
digit ::= [0-9]
number
A number literal may represent either a positive or negative decimal value.
number ::= '-'? ( digit+ ( '.' digit* )? | '.' digit+ )
0.2
Container Structures
variable
A variable is a named reference to the result of evaluating an expression.
variable :: = '"' name '"'
"num_correct_answers" // => 3
A variable should not be confused with a string, which uses backticks (`) like so:
"`num_correct_answers`" // => "num_correct_answers"
dictionary
A dictionary is a structure that maps data in key-value pairs. The keys and values are all evaluated. The keys can be either strings or variables that evaluate to strings.
dictionary : : = '{' ( string | variable ) ':' expression
( ',' ( string | variable ) ':' expression )* '}'
{"`age`": "x", "`score`": 10, "`name`": "`Joe`"}
expression
An expression may be evaluated, and that result is stored in memory to be referenced later. An expression may be denoted by a JSON array [[RFC7159]], in which case it is also called a function. The first element of the array represents the operator of the function. The operator can be either a string or a variable that evaluates to a string. All remaining elements of the array constitute the operands.
expression ::= literal
| variable
| dictionary
| '[' ( literal | variable ) ( ',' expression )* ']'
| Return Type | Operator | Example |
|---|---|---|
| string | "to_str" |
["to_str", 4] // => "4" |
| string | "+" |
["+", "`hello `", "`world`"] // => "hello world" |
| number | "+" |
["+", 1, 2] // => 3 |
| number | "-" |
["-", 5, 3] // => 2 |
| number | "*" |
["*", 2, 4] // => 8 |
| number | "/" |
["/", 1, 2] // => 0.5 |
| number | "//" |
["//", 1, 2] // => 0 |
| number | "%" |
["%", 168, 2] // => 0 |
| number | "to_num" |
["to_num", "`4`"] // => 4 |
| number | "len" |
["len", ["", 1, 2, 3]] // => 3 |
| number | "floor" |
["floor", 1.5] // => 1 |
| list | "" |
["", 1, 2, 3, 4, 5] // => [1, 2, 3, 4, 5] |
| list | "++" |
["++", ["", 1, 2], ["", "`hello`"]] // => [1, 2, "hello"] |
| list | "range" |
["range", 1, 5] // => [1, 2, 3, 4] ["range", 0, 8, 2] // => [0, 2, 4, 6] |
| list | "map" |
["map", "to_str", ["", 1, 2, 3]] // => ["1", "2", "3"]
["map", "+", ["", 1, 2, 3], ["", 4, 5, 6]] // => [5, 7, 9]
|
| list | "foldl" |
["foldl", "+", 0, ["", 1, 2, 3]] // => 6
|
| list | "sort" |
["sort", ["", 1, 3, 2]] // => [1, 2, 3]
|
| list | "shuffle" |
["shuffle", ["", 1, 2, 3]] // => [1, 3, 2] randomly shuffled
|
| list | "reverse" |
["reverse", ["", 1, 2, 3]] // => [3, 2, 1]
|
| boolean | "==" |
["==", 1, 2] // => false |
| boolean | "!=" |
["!=", 1, 2] // => true |
| boolean | ">" |
[">", 2, 3] // => false |
| boolean | ">=" |
[">=", 2, 3] // => false |
| boolean | "<" |
["<", 2, 3] // => true |
| boolean | "<=" |
["<=", 2, 3] // => true |
| boolean | "&&" |
["&&", true, false] // => false |
| boolean | "||" |
["||", true, false] // => true |
| boolean | "!" |
["!", false] // => true |
| boolean | "in" |
["in", 3, ["", 1, 2, 3]] // => true |
| boolean | "input" |
["input"] // => true if there's an input ["input", "`yes`"] // => true if there's an input and it equals "yes" |
| boolean | "return" |
["return"] // => true if there's an return result from callee |
| boolean | "?" |
["?", "`is_greeted`"] // => true if variable defined |
| dynamic | "get" |
["get", 0, ["", 1, 2, 3]] // => 1 ["get", "`a`", {"`a`": 1}] // => 1
|
| dynamic | "pick" |
["pick", ["", 1, 2, 3]] // => 1, 2, or 3 uniformly at random |
| dynamic | "patch" |
["patch", {"`a`": 1, "`b`": 2}, {"`a`": 2}] // => {a: 2, b: 2}
Reference: RFC 7386
|
| dynamic | "edit" |
["edit", {"`a`": 1}, 2, "`a`"] // => {a: 2}
|
| dynamic | "from_list" |
["from_list", ["", ["", "`a`", 1], ["", "`b`", 2]]] // => {a: 1, b: 2}
|
Statements
statement
A statement may be a non-terminal such as do or fork, or a terminal such as effect. Optionally, statements may contain condition, await, or once flags.
statement ::= '{' ( condition ',' )?
( await ',' )?
( once ',' )?
( effect | do | fork ) '}'
condition
A condition is a boolean expression that runs the statement if the expression evaluates to true. A condition check takes priority over other parts of the statement. If a statement does not explicitly contain a condition, then that statement's condition is trivially true.
condition : : = '"if"' ':' expression
"if": [">", "num_wrong_answers", 3]
await
An await blocks execution until a boolean expression evaluates to true.
await ::= '"await"' ':' expression
"await": ["input"]
once
A once flag specifies whether the statement can only be run once. The statement is then ignored in all subsequent instances. By default, the once flag is set to false.
once ::= '"once"' ':' boolean
"once": true
effect
An effect is a terminal node, meaning it does not produce more statements. There are 6 types of effects.
effect ::= act | set | def | run | use | pop
act
An act represents an action for the client to realize. The expression is evaluated before being sent out to the client. For example, the payload of the act statement may be represented using Behavior Markup Language (BML). The client is then responsible for realizing the behavior defined in the act message.
act ::= '"@act"' ':' expression
"@act": {
"`object`": "`tutor`",
"`action`": "`say`",
"`params`": {"`intent`": "`greeting`"}
}
set
A set updates the value of a variable, where the names of the variables and the updated values are specified by evaluating the corresponding expressions. The expression specifying the names of the variables must evaluate to a string, a list consisting of only strings, or a dictionary consisting of only strings.
set ::= '"@set"' ':' expression ',' '"val"' ':' expression
"@set": "`is_user_greeted`", "val": true
"@set": ["", "`is_user_greeted`", "`num_questions`"], "val": ["", true, 7]
def
A def defines a new expression operator that can be used later in the code. The signature of the new expression operator is specified by an expression that must evaluate to a list of strings, which maps to the operator name followed by the argument names. These argument names are valid only for this scope, and may shadow global variables. The result is returned by a pop statement.
When running a user-defined operator, a copy of its surrounding environment (e.g. variables/operators) is coupled to the newly defined operator. In contrast, functions in Javascript keep references to the surrounding state.
Custom operators support closure, since the operator is enclosed with a copy of its surrounding environment. After an operator is defined, the copy of the enclosing scope does not change. When an operator is called, def and set statements inside the body of the operator will only create local symbols that shadow symbols in the enclosing scope.
def ::= '"@def"' ':' expression ',' '"val"' ':' statement
"@def": ["", "`inc`", "`x`"], "val": {"@pop": ["+", 1, "x"]}
"@def":["","`custom`","`divisor`"], "val":{
"@do":[
{"@def":["","`mod`","`num`"], "val": {"@pop":["%","num","divisor"]}},
{"@pop":"mod"}
]
}
run
A run calls DMPL code from another component, optionally passing in arguments. The name of the called component is specified by an expression that must evaluate to a string. The current variables stored in memory are pushed to a stack before the call, and popped back after the call.
The passed in arguments is a JSON array [[RFC7159]] accessible inside the called component, stored in a built-in variable called _args. Note that _args is null by default if the component is not called by another component. If a component is called with no passed in arguments, _args will be an empty array.
run ::= '"@run"' ':' expression ( ',' '"args"' ':' expression )?
"@run": "`Outro`"
"@run": "`Question`", "args": ["", "`What's the largest planet?`", "`Jupiter`"]
use
A use imports variables and expression operators defined in another component.
The name of the imported component is specified by an expression that must evaluate to a string.
The variable and expression operator names can be optionally specified, or all variables and expression operators will be imported.
It's similar to the Python notation: from os import path.
use ::= '"@use"' ':' expression ( ',' '"import"' ':' expression )?
"@use": "`MathExpressions`", "import": ["", "`inc`", "`square`", "`exp`"]
pop
A pop quits execution on the current DMPL code, pops the variables from the stack, and resumes execution from the previous run location.
pop ::= '"@pop"' ':' expression
"@pop": true
do
A do statement specifies a list of statements to be executed.
do ::= '"@do"' ':' '[' ( statement ( ',' statement )* )? ']'
"@do": [
{"@act": "a"},
{"@act": "b"},
{"@act": "c"}
]
fork
A fork statement specifies a branch in program-execution for the list of statements that follow. Only one is chosen, and the strategy to pick one may be provided using the scheme attribute. By default, a greedy scheme is used, meaning the first statement whose condition is met will be chosen. More complicated schemes, such as depth-first-search or Monte Carlo Tree Search may be indicated, leaving the implementation up to the interpreter.
fork ::= '"@fork"' ':' '[' ( statement ( ',' statement )* )? ']' ( ',' scheme )?
When no scheme is provided, a fork is essentially the traditional if/elif/else logical flow:
"@fork": [
{"if": "is_user_greeted", "@act": "a"},
{"if": [">", "num_wrong_answers", 3], "@act": "b"},
{"@act": "c"}
]
Providing a scheme allows stochastic behavior to take place:
"scheme": {"depth": 3}, "@fork": [
{"@set": "`do_action_1`", "val": "true"},
{"@set": "`do_action_2`", "val": "true"},
{"@set": "`do_action_3`", "val": "true"},
{"if": "is_entry_condition_met", "@set": "`do_action_4`", "val": "true"},
{"if": false, "@act": "`never reached`"}
]
scheme
A scheme is associated with a fork statement, and it describes the fork branch resolution strategy.
scheme ::= '"scheme"' ':' expression
{"depth": 3}