load help;


@[name]
dao.grammar
@[name]

@[title]
Dao Grammar Specifications
@[title]

@[text]
This documentation includes the specifications for the grammar of Dao.
It is mainly for advanced users and language specialists who want to 
go into the details of the language.
@[text]


################################################################################
################################################################################
#### Dao Grammar Notations
################################################################################
################################################################################
@[name]
dao.grammar.notation
@[name]

@[title]
Grammar Notations
@[title]

@[text]
Syntax definition: @[green]A ::= B@[green], @[green]A@[green] is defined
as @[green]B@[green] , which can be a descriptive sentence or a combination 
of the following definition items,
@[list]
== Token: @[green]'token'@[green]
== Descriptive: @[green]"description"@[green]
== Alternative: @[green]S | Y@[green]
== Optional: @[green][ S ]@[green]
== Grouping: @[green]( S )@[green]
== Repeating: @[green]S *@[green] or @[green]S +@[green]
   @[list(sub)]
   -- @[green]*@[green] : zero or more times;
   -- @[green]+@[green] : once or more times;
   @[list(sub)]
   For convenience, @[green]{ S }@[green] is also used to represent repeating
   of @[green]S@[green] for zero or more times.
@[list]


Examples,
@[list]
-- @[cyan]( S | Y )+@[cyan] represents all the possible sequences composed 
   of @[cyan]S@[cyan] and @[cyan]Y@[cyan], such as: @[cyan]S@[cyan]; 
   @[cyan]Y@[cyan]; @[cyan]SY@[cyan]; @[cyan]YS@[cyan]; @[cyan]SSY@[cyan] ...
-- @[cyan]S ( Y | N ) T@[cyan] represents: @[cyan]S Y T@[cyan] 
   or @[cyan]S N T@[cyan]
@[list]

@[text]



################################################################################
################################################################################
#### Dao Grammar Specification
################################################################################
################################################################################
@[name]
dao.grammar.lexical
@[name]

@[title]
Lexical Structures
@[title]

@[text]

The standard encoding for Dao program source code is UTF-8.
But the system encoding of the execution environment is also supported,
and source code in such encoding is automatically converted to UTF-8
before parsing.


@[subsection]Comments@[subsection]

Dao uses the number sign @[green]#@[green] to mark comments.
@[list]
-- Single line comment: from @[green]#@[green] to the end of the line;
-- Multiple line comment: paired with @[green]#{@[green] and @[green]#}@[green];
@[list]
Multiple line comments may contain other @[green]#{@[green] and @[green]#}@[green],
if they are properly paired, namely, they are allowed to be nested.


@[subsection]Quotation Marks@[subsection]

Both the single quotation mark (0x27) and the double quotation mark (0x22)
can be used to quote string literals. They must be used in pairs, and no escape
is required for one kind of quotation mark inside strings quoted with the other
kind quotation marks.


@[subsection]Keywords@[subsection]

The following keywords are reserved for the language:
@[list]
-- Types:
@[code(syntax)]
TypeKeyword ::= type | any | bool | int | float | complex | string
               | enum | array | list | map | tuple
@[code(syntax)]

-- Structures:
@[code(syntax)]
StructKeyword ::= interface | class | routine
@[code(syntax)]

-- Storage/scoping:
@[code(syntax)]
StorageKeyword ::= const | var | invar | static
@[code(syntax)]

-- Permisions:
@[code(syntax)]
PermKeyword ::= private | protected | public
@[code(syntax)]

-- Built-in constants/variables:
@[code(syntax)]
ConstVarKeyword ::= none | false | true | self
@[code(syntax)]

-- Control statements:
@[code(syntax)]
ControlKeyword ::= if | else | for | while | do 
                  | switch | case | default | break | skip
				  | defer | return | yield
@[code(syntax)]

-- Other statements:
@[code(syntax)]
OtherStmtKeyword ::= load | import | as
@[code(syntax)]

-- Operators:
@[code(syntax)]
OperatorKeyword ::= and | or | not | in
@[code(syntax)]

-- Miscellaneous:
@[code(syntax)]
MiscKeyword ::= 
@[code(syntax)]

@[list]
@[code(syntax)]
Keyword ::= TypeKeyword | StructKeyword | StorageKeyword 
          | PermKeyword | ConstVarKeyword | ControlKeyword
          | OtherStmtKeyword | OperatorKeyword | MiscKeyword
@[code(syntax)]

@[subsection]Basic Character Class Definitions@[subsection]

Basic character classes:
@[code(syntax)]
DecDigit ::= '0' ... '9'
HexDigit ::= DecDigit | 'a' ... 'f' | 'A' ... 'F'
AsciiLetter ::= 'a' ... 'z' | 'A' ... 'Z'

WideChar ::= "UTF-8 encoded unit of one or more bytes"
WideAlpha ::= WideChar & iswalpha( WideChar ) != 0
WideAlnum ::= WideChar & iswalnum( WideChar ) != 0
@[code(syntax)]
Where @[green]iswalpha()@[green] and @[green]iswalnum()@[green] are the C99 functions
that test if a wide character is belonging to certain class.
Here @[green]WideChar@[green] can be more than one byte,
in such case, these UTF-8 bytes are converted into Unicode before passing
to the C99 test functions.


@[subsection]Identifiers@[subsection]

@[code(syntax)]
AsciiIdentifier ::= ( AsciiLetter | '_' ) ( AsciiLetter | DecDigit | '_' )*
WideIdentifier ::= ( WideAlpha | '_' ) ( WideAlnum | '_' )*

Identifier ::= AsciiIdentifier | WideIdentifier
@[code(syntax)]


@[subsection]Literals@[subsection]

@[subsection]Number Literals@[subsection]
Integer literals:
@[code(syntax)]
DecInteger ::= DecDigit +
HexInteger ::= ( '0x' | '0X' ) HexDigit +

Integer ::= DecInteger | HexInteger
@[code(syntax)]


Floating pointer number literals:
@[code(syntax)]
DotDec ::= DecDigit * '.' DecDigit +
DecDot ::= DecDigit + '.' DecDigit *
DecNumber ::= DotDec | DecDot
DecNumber ::= DecInteger | DecNumber
SciNumber ::= DecNumber ( 'e' | 'E' ) [ '+' | '-' ] DecInteger

Float  ::= DecNumber | SciNumber;
@[code(syntax)]

Complex number, imaginary part literal:
@[code(syntax)]
ComplexImaginary ::= [ Float ] 'C'
@[code(syntax)]

Symbol literal:
@[code(syntax)]
Symbol ::= '$' Identifier
@[code(syntax)]

Type holder literal:
@[code(syntax)]
TypeHolder ::= '@' Identifier
@[code(syntax)]



@[subsection]String Literal@[subsection]

Basic string literal:
@[code(syntax)]
SingleQuoteString ::= ' ' ' ValidCharSequence ' ' '
DoubleQuoteString ::= ' " ' ValidCharSequence ' " '
@[code(syntax)]

Verbatim string literal:
@[code(syntax)]
VerbatimString ::= '@[' [Delimiter] ']' Characters '@[' [Delimiter] ']'
@[code(syntax)]
Where @[cyan]Delimiter@[cyan] can contain letters, digits, underscores, 
blank spaces, dots, colons, dashes and assignment marks.
It must be unique such that @[green]'@[' [Delimiter] ']'@[green]
or @[green]'@@[' [Delimiter] ']'@[green] does not appear in the string content.


Here a @[green]ValidCharSequence@[green] is a sequence of characters where
the enclosing quotation marks may only appear inside the sequence as escaped characters.
So the followings are valid string literals:
@[code(dao)]
' " '
" ' "
' \' '
" \" "
@[code(dao)]

String literal:
@[code(syntax)]
String ::= SingleQuoteString + | DoubleQuoteString + | VerbatimString
@[code(syntax)]
Here the repeating marks mean two or more @[green]SingleQuoteString@[green]
or @[green]DoubleQuoteString@[green] can be placed one after another,
and they will will be jointed into a single string literal during preprocessing.


@[subsection]Escape Sequences in String Literal@[subsection]

Escape characters:
@[list]
--@[green]\\@[green]: backslash;
--@[green]\t@[green]: horizontal tab;
--@[green]\f@[green]: form feed; (not implemented)
--@[green]\n@[green]: line feed;
--@[green]\r@[green]: carriage return;
--@[green]\'@[green]: single quotation mark;
--@[green]\"@[green]: double quotation mark;
@[list]

Escape digits (not implemented):
@[list]
--@[green]\ooo@[green]: character with octal value @[green]ooo@[green];
--@[green]\xhh@[green]: character with hex value @[green]hh@[green];
--@[green]\uxxxx@[green]: Unicode character with hex value @[green]xxxx@[green];
--@[green]\uxxxxxxxx@[green]: Unicode character with hex value @[green]xxxxxxxx@[green];
@[list]


@[subsection]Operators@[subsection]

@[list]
-- Left unary operators:
@[code(syntax)]
LeftUnaryOperater ::= '++' | '--' | '!' | '~' | '%' | 'not'
@[code(syntax)]
-- Right unary operators:
@[code(syntax)]
RightUnaryOperator ::=
@[code(syntax)]
-- Binary operators:
@[code(syntax)]
BinArith ::= '+' | '-' | '*' | '/' | '%' | '**'
BinComp  ::= '==' | '!=' | '<' | '>' | '<=' | '>='
BinBool  ::= '&&' | '||' | 'and' | 'or'
BinBit   ::= '&' | '|' | '^' | '<<' | '>>'
BinMisc  ::= 'in' | 'not in' | '?=' | '?<'

BinaryOperator ::= BinArith | BinComp | BinBool | BinBit | BinMisc
@[code(syntax)]

-- Composite assignment operators:
@[code(syntax)]
AssignmentOperator ::= '+=' | '-=' | '*=' | '/=' | '&=' | '|='
@[code(syntax)]

-- Other operators:
@[code(syntax)]
OtherOperator ::= '->' | '=>' | ':' | '.' | '...'
@[code(syntax)]
@[list]
@[code(syntax)]
UnaryOperator ::= LeftUnaryOperater | RightUnaryOperator

Operator ::= UnaryOperator | BinaryOperator 
           | AssignmentOperator | OtherOperator
@[code(syntax)]

@[subsection]Miscellaneous@[subsection]

@[subsection]Semicolon@[subsection]

Like in some other languages, semicolon can be used to mark the end
of a statement. However the use of semicolon is optional, the compiler
is able to determine the end of a statement based on some semantic rules.




@[text]



################################################################################
################################################################################
#### Dao Grammar Specification
################################################################################
################################################################################
@[name]
dao.grammar.constexpr
@[name]

@[title]
Constant Expressions
@[title]

@[text]

Drafting in progress.




@[subsection]
Constant Atomic Expression
@[subsection]

@[code(syntax)]
ConstAtomicExpression ::= ConstIdentifier | Integer | Float
                        | ComplexImaginary | LongInteger | String | Symbol
						| none | false | true
@[code(syntax)]
Where @[green]ConstIdentifier@[green] represents identifiers for constants
such as routines, classes, namespaces, type names and user defined constants.


@[subsection]
Constant Primary Expression
@[subsection]

@[code(syntax)]
BuiltinMathFuncsMinusRand ::= 'abs' | 'ceil' | 'floor'
                        | 'real' | 'imag' | 'arg' | 'norm'
                        | 'acos' | 'cos' | 'cosh'
                        | 'asin' | 'sin' | 'sinh'
                        | 'atan' | 'tan' | 'tanh'
                        | 'exp'  | 'log' | 'sqrt'

ConstPrimaryExpression ::= ConstAtomicExpression 
                         | ConstEnumerativeExpression
                         | '(' ConstExpression ')'
                         | ConstPrimaryExpression '::' Identifier
                         | ConstPrimaryExpression '[' [ ConstExpression ] ']'
                         | BuiltinMathFuncsMinusRand '(' ConstExpression ')'
                         | ConstExpression '(' [ ConstExpressionList ] ')'
@[code(syntax)]


@[subsection]
Constant Expression List
@[subsection]

@[code(syntax)]
ConstExpressionList ::= ConstExpression { ',' ConstExpression }
@[code(syntax)]



@[subsection]
Constant Enumerative Expression
@[subsection]

@[code(syntax)]
ConstEnumerativeExpression ::= ConstArray | ConstList | ConstMap | ConstTuple
@[code(syntax)]


@[subsection]
Constant Array
@[subsection]

@[code(syntax)]
ConstVector  ::= '[' [ ConstExpressionList [ ',' ] ] ']'
ConstMatrix  ::= '[' ConstExpressionList { ';' ConstExpressionList } ']'
ConstVector2 ::= 'array' '{' [ ConstExpressionList [ ',' ] ] '}'
ConstMatrix2 ::= 'array' '{' ConstExpressionList { ';' ConstExpressionList } '}'

ConstArray   ::= ConstVector | ConstMatrix | ConstVector2 | ConstMatrix2
@[code(syntax)]


@[subsection]
Constant List
@[subsection]

@[code(syntax)]
ConstList ::= [ 'list' ] '{' [ ConstExpressionList [ ',' ] ] '}'
@[code(syntax)]
Note: a list enumeration started with @[green]{@[green] has to appear inside an expression.



@[subsection]
Constant Map
@[subsection]

@[code(syntax)]
ConstMapKeyValue  ::= ConstExpression => ConstExpression
ConstHashKeyValue ::= ConstExpression -> ConstExpression

ConstEmptyMap  ::= '{' '=>' '}' | 'map' '{' [ '=>' ] '}'
ConstEmptyHash ::= '{' '->' '}' | 'map' '{'   '->'   '}'

ConstMapEnum  ::= [ 'map' ] '{' ConstMapKeyValue  { ',' ConstMapKeyValue  } [ ',' ] '}'
ConstHashEnum ::= [ 'map' ] '{' ConstHashKeyValue { ',' ConstHashKeyValue } [ ',' ] '}'

ConstMap ::= ConstEmptyMap | ConstEmptyHash | ConstMapEnum | ConstHashEnum
@[code(syntax)]


@[subsection]
Constant Tuple
@[subsection]

@[code(syntax)]
ConstArgumentItem ::= [ Identifier '=' ] ConstExpression

ConstTupleEnum1 ::=         '('   ConstArgumentItem ',' ')'
ConstTupleEnum2 ::=         '('   ConstArgumentItem ( ',' ConstArgumentItem ) + [ ',' ] ')'
ConstTupleEnum3 ::= 'tuple' '{' [ ConstArgumentItem { ',' ConstArgumentItem } [ ',' ] ] '}'

ConstTuple ::= ConstTupleEnum1 | ConstTupleEnum2 | ConstTupleEnum3
@[code(syntax)]



@[subsection]
Constant Expression
@[subsection]

@[code(syntax)]
ConstExpression ::= ConstPrimaryExpression
                  | LeftUnaryOperator ConstPrimaryExpression
                  | ConstPrimaryExpression BinaryOperator ConstPrimaryExpression
@[code(syntax)]



@[text]



################################################################################
################################################################################
#### Dao Grammar Specification
################################################################################
################################################################################
@[name]
dao.grammar.typename
@[name]

@[title]
Type Name
@[title]

@[text]

Drafting in progress.




@[subsection]
Special Types
@[subsection]

@[code(syntax)]
NoneType       ::= [ 'dao' '::' ] 'none'
AnyType        ::= [ 'dao' '::' ] 'any'
VariantHolder  ::= TypeHolder '<' VariantType '>'
SpecialType    ::= NoneType | AnyType | TypeHolder | VariantHolder
@[code(syntax)]



@[subsection]
Primitive Types
@[subsection]

@[code(syntax)]
PrimitiveType ::= 'int' | 'float' | 'complex' | 'string'
@[code(syntax)]


@[subsection]
Enum Symbol Types
@[subsection]

@[code(syntax)]
SymbolItem ::= Identifier [ '=' Integer ]

SymbolType ::= 'enum' '<' [ SymbolItem { ',' SymbolItem } ] '>'
FlagType   ::= 'enum' '<' [ SymbolItem { ';' SymbolItem } ] '>'
BoolType   ::= 'enum' '<' [ SymbolItem  ':' SymbolItem ] '>'

EnumSymbolType ::= 'enum' | SymbolType | FlagType | BoolType
@[code(syntax)]



@[subsection]
Array Type
@[subsection]

@[code(syntax)]
ArrayNumType ::= 'int' | 'float' | 'complex'
ArrayType ::= 'array' [ '<' ( ArrayNumType | TypeHolder ) '>' ]
@[code(syntax)]


@[subsection]
List Type
@[subsection]

@[code(syntax)]
ListType ::= 'list' [ '<' Type '>' ]
@[code(syntax)]


@[subsection]
Map Type
@[subsection]

@[code(syntax)]
MapType ::= 'map' [ '<' Type, Type '>' ]
@[code(syntax)]


@[subsection]
Tuple Type
@[subsection]

@[code(syntax)]
TupleItemType ::= [ 'invar' ] [ Identifier ':' ] Type
TupleType ::= 'tuple' [ '<' TupleItemType { ',' TupleItemType } '>' ]
@[code(syntax)]



@[subsection]
Routine Type
@[subsection]

@[code(syntax)]
ParamTypeItem1 ::= [ 'invar' ] 'Identifier' [ ':' Type ]
ParamTypeItem2 ::= [ 'invar' ] 'Identifier' [ '=' Type ]
ParamTypeList1 ::= ParamTypeItem1 { ',' ParamTypeItem1 } { ',' ParamTypeItem2 } [ ',' '...' ]
ParamTypeList2 ::= ParamTypeItem2 { ',' ParamTypeItem2 } [ ',' '...' ]
ParamTypeList  ::= ParamTypeList1 | ParamTypeList2 | '...'

ParamTypeItem3 ::= 'Identifier' ':' Type
ParamTypeList3 ::= ParamTypeItem3 { ',' ParamTypeItem3 } 
CodeBlockReturn ::= '[' ParamTypeList3 ']'

RoutineType ::= 'routine' [ '<' [ ParamTypeList ] [ '=>' Type ] '>' [ CodeBlockReturn ] ]
@[code(syntax)]


@[subsection]
User Type
@[subsection]

@[code(syntax)]
# For unspecialized C data types:
TemplParamList1 ::= TypeHolder { ',' TypeHolder } { ',' TypeHolder '=' Type }
TemplParamList2 ::= TypeHolder '=' Type { ',' TypeHolder '=' Type }


# For specialized C data types:
TemplArgList   ::= ( Type | ConstExpression) { ',' Type | ConstExpression }

TemplType ::= Identifier '<' ( TemplParamList1 | TemplParamList2 | TemplType ) '>'

UserType ::= Identifier
           | UserType '::' Identifier
           | UserType '::' TemplType
@[code(syntax)]




@[subsection]
Variant Type
@[subsection]

@[code(syntax)]
VariantType ::= Type ( '|' Type )+
@[code(syntax)]





@[subsection]
Type
@[subsection]

@[code(syntax)]
Type ::= SpecialType 
       | [ 'dao' '::' ] PrimitiveType
       | [ 'dao' '::' ] EnumSymbolType
       | [ 'dao' '::' ] ArrayType
       | [ 'dao' '::' ] ListType
       | [ 'dao' '::' ] MapType
       | [ 'dao' '::' ] TupleType
       | [ 'dao' '::' ] RoutineType
       | { Identifier '::' } UserType
       | ( 'var' | 'invar' ) '<' Type '>'
@[code(syntax)]




@[text]



################################################################################
################################################################################
#### Dao Grammar Specification
################################################################################
################################################################################
@[name]
dao.grammar.expression
@[name]

@[title]
Expressions
@[title]

@[text]

Drafting in progress.





@[subsection]
Atomic Expression
@[subsection]

@[code(syntax)]
AtomicExpression ::= Identifier | Integer | LongInteger | Float
                   | ComplexImaginary | String | Symbol
@[code(syntax)]


@[subsection]
Primary Expression
@[subsection]

@[code(syntax)]
SectionParamValist ::= '...'
SectionParamNames ::= Identifier { ',' Identifier }
SectionParamItems ::= SectionParamValist | SectionParamNames [ ',' SectionParamValist ]
SectionParamList ::= '[' [ SectionParamItems ] [ 'as' Identifier ] ']'

PrimaryExpression ::= AtomicExpression 
                    | EnumerativeExpression
                    | '(' Expression ')'
                    | PrimaryExpression '::' Identifier
                    | PrimaryExpression '.'  Identifier
                    | PrimaryExpression '(' [ ArgumentList ] ')'
                    | PrimaryExpression '[' [ ExpressionList [ ',' ] ] ']'
                    | PrimaryExpression '{' [ SectionParamList ] [StatementBlock] '}'
                    | PrimaryExpression '.{' [ ArgumentList ] '}'
@[code(syntax)]


@[subsection]
Expression List
@[subsection]

@[code(syntax)]
ExpressionList ::= Expression { ',' Expression }
@[code(syntax)]



@[subsection]
Argument List
@[subsection]

@[code(syntax)]
ArgumentItem ::= [ Identifier '=' ] Expression

ArgumentList = ArgumentItem { ',' ArgumentItem }
@[code(syntax)]



@[subsection]
Enumerative Expression
@[subsection]

@[code(syntax)]
EnumerativeExpression ::= Array | List | Map | Tuple
@[code(syntax)]


@[subsection]
Array
@[subsection]

@[code(syntax)]
Vector  ::= '[' [ ExpressionList [ ',' ] ] ']'
Matrix  ::= '[' ExpressionList { ';' ExpressionList } ']'
Vector2 ::= 'array' '{' [ ExpressionList [ ',' ] ] '}'
Matrix2 ::= 'array' '{' ExpressionList { ';' ExpressionList } '}'

ArithProgArray  ::=         '[' Expression ':' [ Expression ':' ] Expression ']'
ArithProgArray2 ::= 'array' '{' Expression ':' [ Expression ':' ] Expression '}'

Array ::= Vector | Matrix | ArithProgArray | Vector2 | Matrix2 | ArithProgArray2
@[code(syntax)]


@[subsection]
List
@[subsection]

@[code(syntax)]
ListEnum      ::= [ 'list' ] '{' [ ExpressionList [ ',' ] ] '}'
ArithProgList ::= [ 'list' ] '{' Expression ':' [ Expression ':' ] Expression '}'

List ::= ListEnum | ArithProgList
@[code(syntax)]
Note: a list enumeration started with @[green]{@[green] has to appear inside an expression.



@[subsection]
Map
@[subsection]

@[code(syntax)]
MapKeyValue  ::= Expression => Expression
HashKeyValue ::= Expression -> Expression

MapEnum  ::= [ 'map' ] '{' MapKeyValue  { ',' MapKeyValue  } [ ',' ] '}'
HashEnum ::= [ 'map' ] '{' HashKeyValue { ',' HashKeyValue } [ ',' ] '}'

Map ::= ConstEmptyMap | ConstEmptyHash | MapEnum | HashEnum
@[code(syntax)]


@[subsection]
Tuple
@[subsection]

@[code(syntax)]
TupleEnum1 ::=         '('   ArgumentItem ',' ')'
TupleEnum2 ::=         '('   ArgumentItem { ',' ArgumentItem } [ ',' ]   ')'
TupleEnum3 ::= 'tuple' '{' [ ArgumentItem { ',' ArgumentItem } [ ',' ] ] '}'

Tuple ::= TupleEnum1 | TupleEnum2 | TupleEnum3
@[code(syntax)]



@[subsection]
Anonymous Routine
@[subsection]

@[code(syntax)]
AnParamItem1 ::= [ 'invar' ] Identifier [ ':' Type ]
AnParamItem2 ::= [ 'invar' ] Identifier [ ':' Type ] '=' Expression
ValistParam  ::= [ 'invar' ] '...' [ ':' Type ]

AnParamList1 ::= AnParamItem1 { ',' AnParamItem1 }
AnParamList2 ::= AnParamList1 { ',' AnParamItem2 } [ ',' ValistParam ]
AnParamList3 ::= AnParamItem2 { ',' AnParamItem2 } [ ',' ValistParam ]
AnParamList  ::= ( AnParamList2 | AnParamList3 | ValistParam ) [ 'as' Identifier ]

AnonymousRoutine ::= 'routine' [ '(' [ AnParamList ] ')' ] '{' StatementBlock '}'
@[code(syntax)]






@[subsection]
Expression
@[subsection]

@[code(syntax)]
Expression ::= PrimaryExpression
             | LeftUnaryOperator PrimaryExpression
             | PrimaryExpression BinaryOperator PrimaryExpression
             | '(' Type ')' PrimaryExpression
             | AnonymousRoutine
@[code(syntax)]


@[text]




################################################################################
################################################################################
#### Dao Grammar Specification
################################################################################
################################################################################
@[name]
dao.grammar.statement
@[name]

@[title]
Statements
@[title]

@[text]

Drafting in progress.


@[subsection]
Declaration Statements
@[subsection]

@[code(syntax)]
ConstStatic    ::= 'const' | 'static'
VarGlobal      ::= 'var' | 'invar'
IdentifierList ::= Identifier {',' Identifier }

ConstStaticDecl ::= ConstStatic IdentifierList [ ':' Type ] [ '=' ConstExpression ]
VarGlobalDecl   ::= VarGlobal   IdentifierList [ ':' Type ] [ '=' Expression ]

DeclarationStmt ::= ConstStaticDecl | VarGlobalDecl
@[code(syntax)]




@[subsection]
Basic Statement
@[subsection]

@[code(syntax)]
BasicStatement ::= DeclarationStmt | Expression | 'break' | 'skip'
@[code(syntax)]




@[subsection]
If-else Statement
@[subsection]

@[code(syntax)]
ControlBlock ::= Statement | '{' [ StatementBlock ] '}'

IfElseStmt ::= 'if' '(' [ LocalVarDeclaration ';' ] Expression ')' ControlBlock
               { 'else' 'if' '(' [ LocalVarDeclaration ';' ] Expression  ')' ControlBlock }
			   [ 'else' ControlBlock ]
@[code(syntax)]


@[subsection]
For Loop Statement
@[subsection]

@[code(syntax)]
ForIn ::= 'for' '(' [ 'var' ] Identifier 'in' Expression {';' Identifier 'in' Expression} ')'
              ControlBlock

RangeFor ::= 'for' '(' [ 'var' ] Identifier '=' Expression ':' [ Expression ':' ] Expression ')'
              ControlBlock

CFor  ::= 'for' '(' [ LocalVarDeclaration ] ';' [ Expression ] ';' [ ExpressionList ] ')'
              ControlBlock

ForStmt ::= ForIn | RangeFor | CFor
@[code(syntax)]



@[subsection]
While Loop Statement
@[subsection]

@[code(syntax)]
WhileStmt ::= 'while' '(' [ LocalVarDeclaration ';' ] Expression ')' ControlBlock
@[code(syntax)]



@[subsection]
Do-while Looping Statement
@[subsection]

@[code(syntax)]
DoWhileStmt ::= 'do' ControlBlock 'while' '(' Expression ')'
@[code(syntax)]




@[subsection]
Switch-case Statement
@[subsection]

@[code(syntax)]
ValueSwitch ::= 'switch' '(' [ ('var' | 'invar') '=' ] Expression ')' '{'
                   { 'case' ConstExpression [ ( ',' | '...' ) ConstExpression ] ':' 
				                   ControlBlock }
				   [ 'default' ':' ControlBlock ]
                   '}'

TypeSwitch ::= 'switch' '(' [ ('var' | 'invar') '=' ] Expression ')' 'type' '{'
                   { 'case' Type [ ( ',' | '...' ) Type ] ':' ControlBlock }
				   [ 'default' ':' ControlBlock ]
                   '}'

SwitchCaseStmt ::= ValueSwitch | TypeSwitch
@[code(syntax)]




@[subsection]
Defer Statement
@[subsection]

@[code(syntax)]
DeferStmt ::= 'defer' [ '(' [ Type ] ')' ] '{' StatementBlock '}'
@[code(syntax)]







@[subsection]
Type Aliasing Statement
@[subsection]

@[code(syntax)]
TypeAlias ::= 'type' Identifier '=' Type
@[code(syntax)]





@[subsection]
Load Statement
@[subsection]

@[code(syntax)]
LoadFile ::= 'load' ( String | { Identifier ('.' | '::') } Identifier ) [ 'as' Identifier ]
LoadResultMod ::= 'load' Identifier '(' [ ConstArgumentItem { ',' ConstArgumentItem } ')'

LoadStmt ::= LoadFile | LoadResultMod
@[code(syntax)]





@[subsection]
Import Statement
@[subsection]

@[code(syntax)]
SingleImport ::= 'import' Identifier '.' Identifier
MultipleImport ::= 'import' Identifier '.' '{' [ IdentifierList ] '}'

ImportStmt ::= SingleImport | MultipleImport
@[code(syntax)]
Import the constants and globals from another namespace to the current scope.





@[subsection]
Yield Statement
@[subsection]

@[code(syntax)]
YieldStmt ::= 'yield' '(' [ ArgumentList ] ')'
@[code(syntax)]




@[subsection]
Return Statement
@[subsection]

@[code(syntax)]
ReturnStmt ::= 'return' [ ExpressionList ]
@[code(syntax)]




@[subsection]
Statement and Block
@[subsection]


@[code(syntax)]
Statement ::= DeclarationStmt
            | BasicStatement
            | IfElseStmt
            | ForStmt
            | WhileStmt
            | DoWhileStmt
            | SwitchCaseStmt
            | DeferStmt
            | TypeAlias
            | LoadStmt
            | ImportStmt
			| YieldStmt
			| ReturnStmt

StatementBlock ::= { Statement }
@[code(syntax)]
Note: the @[code]LoadStmt@[code] is only allowed at the top lexical scope.


@[text]







################################################################################
################################################################################
#### Dao Grammar Specification
################################################################################
################################################################################
@[name]
dao.grammar.routine
@[name]

@[title]
Routines (Functions)
@[title]

@[text]

@[code(syntax)]
ParamItem1 ::= [ 'invar' ] Identifier [ ':' Type ]
ParamItem2 ::= [ 'invar' ] Identifier [ ':' Type ] '=' ConstExpression
ValistParam  ::= [ 'invar' ] '...' [ ':' Type ]

ParamList1 ::= ParamItem1 { ',' ParamItem1 }
ParamList2 ::= ParamList1 { ',' ParamItem2 } [ ',' ValistParam ]
ParamList3 ::= ParamItem2 { ',' ParamItem2 } [ ',' ValistParam ]
ParamList  ::= ( ParamList2 | ParamList3 | ValistParam ) [ 'as' Identifier ]

OverloadableOperator ::= Operator | '.' Identifier [ '=' ] | '[' ']' [ '=' ]

ParamReturn ::= '(' [ ParamList ] ')' [ '=>' Type ]

RoutineSig   ::= Identifier '(' [ ParamList ] ')' [ '=>' Type ]
CodeBlockSig ::= Identifier '(' [ ParamList ] ')' '[' [ ParamList1 ] ']' [ '=>' Type ]

RoutineDecl1 ::= 'routine' { Identifier '::' } ( RoutineSig | CodeBlockSig )
RoutineDecl2 ::= 'routine' { Identifier '::' } OverloadableOperator ParamReturn

RoutineDecl ::= RoutineDecl1 | RoutineDecl2

Routine ::= RoutineDecl '{' StatementBlock '}'
@[code(syntax)]

@[text]




################################################################################
################################################################################
#### Dao Grammar Specification
################################################################################
################################################################################
@[name]
dao.grammar.class
@[name]

@[title]
Class
@[title]

@[text]

@[code(syntax)]
ClassConstField ::= 'const' Identifier '=' ConstExpression
ClassVarField   ::= ( 'var' | 'invar' | 'static' ) Identifier [ '=' ConstExpression ]

Mixins  ::= '(' [ UserType { ',' UserType } ] ')'

ClassBody ::= { ClassConstField | ClassVarField | Routine }

Class ::= 'class' { Identifier '::' } Identifier [ Mixins ] [ ':' UserType ]
              '{' [ ClassBody ] '}'
@[code(syntax)]


@[text]