Difference between revisions of "GrammarWML"

Revision as of 06:10, 19 March 2026

Note: This page is currently undergoing reconstruction. Information on the page may become misleading or occasionally wrong for brief periods of time.

This page contains a formal grammar of the Wesnoth domain-specific languages, including WML and its preprocessor. It does not attempt to capture any of the ways that the Wesnoth engine may interpret a string, such as WML variable substitution. It also doesn't fully capture the potential consequences of macros, for example the use of unbalanced WML tags. The syntax used is regular-expression-like (which is not quite the same as regex-like!), with the following conventions:

Literal values are enclosed in either 'single quotes' or "double quotes".
Square brackets enclose character classes, with initial ^ inverting them
Whitespace within an expression (unless quoted) is used only for readability or to separate non-terminals
The meta-characters * + ? | have the same meaning as is typical in regular expressions
The sequence «tab» represents a tab character, and «nl» represents an end-of-line character or character sequence
Multiple definitions of a non-terminal are equivalent to alternation (ie, x:=4 and x:=7 combine to produce x:=4|7)

WML Preprocessor

The WML preprocessor knows little of the grammar of the WML language itself; it is primarily just a text-substitution engine. Currently this is just a draft and may not be entirely accurate.

preproc_doc = {preproc_directive | preproc_line} ;
preproc_directive = simple_directive | macro_definition | if_block ;
preproc_line = {preproc_text} , ['<'] , [comment] , ?newline? ;
preproc_text = preproc_char | '<' , preproc_char | '<<' , macro_free_text , '>>' | macro_inclusion ;
preproc_char = char - ('<' | '{' | '#' | ?newline?) ;
macro_free_text = {macro_free_char | '>' , macro_free_char} ;
macro_free_char = char - '>' ; (* Note: this can include newlines! *)
macro_inclusion = '{' , macro_name , {req_ws , macro_argument} , '}' ;
macro_name = macro_name_char , {macro_name_char}
macro_name_char = char - ('}' | ws) ;
macro_argument = macro_component , {macro_component}
macro_component = macro_name
                | macro_inclusion
                | '(' , [preproc_doc] , ')'
                | ['_'] , opt_ws , '"' , {quoted_char | macro_inclusion} , '"'
                | '<<' , macro_free_text , '>>'
                ;
quoted_char = char - ( '}' | '"' ) | '""' ;
comment = opt_ws , '#' , {comment_char} , ?newline? ;
comment_char = char - ?newline? ;
ws = ?space? | ?tab?
opt_ws = {ws}
req_ws = ws , {ws}
simple_directive = '#undef' , req_ws , macro_name , opt_ws , ?newline?
                 | ('#warning' | '#error') req_ws , {comment_char} , ?newline? ;
macro_definition = '#define' , req_ws , macro_name , {req_ws macro_name} , ?newline? , {opt_arg_definition} , {macro_content} , '#enddef' , ?newline? ;
macro_content = simple_directive | if_block | preproc_line ;
opt_arg_definition = '#arg' , req_ws , macro_name , ?newline? , {macro_content} , '#endarg' , ?newline? ;
if_block = (ifdef_header | ifver_header | ifhave_header) , ?newline? , preproc_doc ['#else' , ?newline? , preproc_doc] '#endif' , ?newline? ;
ifdef_header = ('#ifdef' | '#ifndef') , req_ws , macro_name ;
ifver_header = ('#ifver' | '#ifnver') , req_ws , macro_name , opt_ws , comparison_op , opt_ws , version_string ;
ifhave_header = ('#ifhave' | '#ifnhave') , req_ws , comment_char ;
comparison_op = '<' | '<=' | '==' | '!=' | '>=' | '>' ;
version_string = integer , ['.' , integer] ;
integer = digit , {digit} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
char = ?any unicode character? ;

WML

This grammar describes WML after the preprocessor is finished with it, and as such does not account for macros, preprocessor directives, or comments. It also assumes tokenization has already occurred and thus does not specify whitespace, except for newlines. Note that it omits the requirement for opening and closing tags to match.

wml_doc = {wml_tag | wml_attribute} ;
wml_tag = '[' , ['+'] , wml_name , ']' , wml_doc , '[/' , wml_name , ']' ;
wml_name = wml_id_char , {wml_id_char} ;
wml_attribute = [textdomain] , wml_key_sequence , '=' , wml_value , ?newline? ;
wml_key_sequence = wml_name , {',' , wml_name} ;
wml_value = wml_value_component , {'+' , [?newline? , [textdomain]] , wml_value_component} ;
wml_value_component = text | ['_'] , (string | raw_string) ;
text = {char - '+' | '"' | ?newline?} ;
string = '"' . {char - '"' | '""'} , '"' ;
raw_string = '<<' , {char - '>' | '>' , char - '>'} , '>>' ;
textdomain = '#textdomain' domain_char , {domain_char} , ?newline? ;
wml_id_char = lowercase | uppercase | digit | '_' ;
lowercase = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm'
          | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' ;
uppercase = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M'
          | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
domain_char = wml_id_char | '-' ;
char = ?any unicode character? ;

WML Substitutions

This grammar describes the syntax of WML substitutions, the syntax used to specify that variables should be substituted into the value of a WML attribute. The grammar here describes a single placeholder, without regard to the fact that they can be nested. Thus, parsing a string using this grammar would only succeed if done from right to left while performing the substitutions.

wml_substitution = wml_var | wml_formula | '$|' ;
wml_var = '$' , wml_var_path , [wml_var_default | '|'] ;
wml_var_path = {wml_var_name , [wml_var_index] , '.'} , wml_var_name ;
wml_var_name = wml_id_char, {wml_id_char} ; (* wml_id_char is defined in the WML grammar, above *)
wml_var_index = '[' , digit , {digit} , ']' ; (* as is digit *)
wml_var_default = '?' , default_char, {default_char} , '|' ;
default_char = char - '|' ;
wml_formula = '$' , '(' , wfl_document , ')' ;

Wesnoth Formula Language

This grammar describes the syntax of the Wesnoth Formula Language. Though it specifies the format of comments and file markers, they are not integrated into the main grammar since it treats the equivalently to whitespace. The grammar may not be completely accurate to the actual in-game parser.

wfl_comment := '#' [^#]* '#'
wfl_file_run := 'wfl' wfl_string «any token»* 'wflend'
wfl_document := wfl_function_definition* wfl_formula
wfl_function_definition := 'def' wfl_name '(' wfl_function_args ')' wfl_formula ';'
wfl_function_args := (wfl_function_arg (',' wfl_function_arg)*)?
wfl_function_arg := wfl_name '*'?
wfl_formula := 'not'? where_expression
wfl_formula := bracketed_expression
bracketed_expression := '(' wfl_formula ')'
where_expression := (boolean_or_expression | bracketed_expression) ('where' wfl_variables)*
wfl_variables := wfl_variable (',' wfl_variable)*
wfl_variable := wfl_name '=' wfl_formula
boolean_or_expression := (boolean_and_expression | bracketed_expression) ('or' wfl_formula)*
boolean_and_expression := (comparison_expression | bracketed_expression) ('and' wfl_formula)*
comparison_expression := (containment_expression | bracketed_expression) (comparison_op wfl_formula)*
comparison_op := '=' | '!=' | '<' | '>' | '<=' | '>='
containment_expression := (range_expression | bracketed_expression) ('in' wfl_formula)*
range_expression := (additive_expression | bracketed_expression) ('~' wfl_formula)*
additive_expression := negation_opt? (multiplicative_expression | bracketed_expression) (additive_op wfl_formula)*
negation_op := '-' | '+'
additive_op := '-' | '+' | '..'
multiplicative_expression := (exponent_expression | bracketed_expression) (multiplicative_op wfl_formula)*
muliplicative_op := '*' | '/' | '%'
exponent_expression := (wfl_formula '^')* (dice_expression | bracketed_expression)
dice_expression := (dot_expression | bracketed_expression) ('d' wfl_formula)*
dot_expression := (wfl_value | bracketed_expression) ('.' wfl_formula)*
wfl_value := 'functions' | wfl_name | wfl_number | wfl_string | wfl_container | wfl_function_call
wfl_name := [a-zA-Z_]+
wfl_number := [0-9]+ ('.' [0-9]+)?
wfl_string := "'" ([^'[]+ | wfl_string_subst | wfl_string_escape)* "'"
wfl_string_subst := '[' wfl_formula ']'
wfl_string_escape := "[']" | '[(]' | '[)]'
wfl_container := '[' ('->' | wfl_expression_list | wfl_key_value_list)? ']'
wfl_expression_list := wfl_formula (',' wfl_formula)*
wfl_key_value_list := wfl_formula '->' wfl_formula (',' wfl_formula '->' wfl_formula)*
wfl_function_call := wfl_name '(' wfl_expression_list? ')'

@@ Line 89: / Line 89: @@
 This grammar describes the syntax of WML substitutions, the syntax used to specify that variables should be substituted into the value of a WML attribute. The grammar here describes a single placeholder, without regard to the fact that they can be nested. Thus, parsing a string using this grammar would only succeed if done from right to left ''while'' performing the substitutions.
- wml_substitution := wml_var | wml_formula | '$|'
+<syntaxhighlight lang=ebnf>
- wml_var := '$' wml_var_path (wml_var_default | '|')?
+wml_substitution = wml_var | wml_formula | '$|' ;
- wml_var_path := (wml_var_name wml_var_index? '.')* wml_var_name
+wml_var = '$' , wml_var_path , [wml_var_default | '|'] ;
- wml_var_name := [a-zA-Z0-9_]+
+wml_var_path = {wml_var_name , [wml_var_index] , '.'} , wml_var_name ;
- wml_var_index := '[' [0-9]+ ']'
+wml_var_name = wml_id_char, {wml_id_char} ; (* wml_id_char is defined in the WML grammar, above *)
- wml_var_default := '?' [^|]+ '|'
+wml_var_index = '[' , digit , {digit} , ']' ; (* as is digit *)
- wml_formula := '$' '(' wfl_document ')'
+wml_var_default = '?' , default_char, {default_char} , '|' ;
+default_char = char - '|' ;
+wml_formula = '$' , '(' , wfl_document , ')' ;
+</syntaxhighlight>
 == Wesnoth Formula Language ==

Difference between revisions of "GrammarWML"

Revision as of 06:10, 19 March 2026

Contents

WML Preprocessor

WML

WML Substitutions

Wesnoth Formula Language