[[TOC]]

= uste parser syntax =
This page describes the syntax of the parser module of libuste. This syntax is used within all templates (as parsed by libuste).

== Introduction ==
The parser reads the document and scans it for commands. uste commands start and end with 3 @s (@@@cmd@@@) while in "document" mode. with the ''pragma'' command you can switch into "uste" mode which will allow you to skip them. This is used to allow bigger blocks to be more easy to read. While in uste mode you can prefix all commands with any number of spaces to make blocks more readable.

Here is an example in document mode:
{{{
@@@set answer to 42@@@
Answer is: @@@var answer@@@
}}}

This is an example in uste mode:
{{{
@@@pragma code uste@@@
 set answer to 42
 literal: Answer is:
 var answer
 literal special newline
@@@end@@@
}}}

So software like web servers can detect the file to be a uste template there is the uste magic number. This magic is the special command ''TEMPLATE'' (@@@TEMPLATE@@@). This magic should be used at the begin of each template so it can be detected by such software. This special command is stripped while rendering and will not generate any output.

== Basic command syntax ==
Each command is started and ended with ''@@@'' if not in uste mode. The first word of the command is the command name. In addition command parameters can follow. After the parameters there can be the ''extra'' parameter which is always a string literal.
So the basic syntax is:
{{{
@@@command[ ARG[ ARG[ ARG...]]][: extra]@@@
}}}

A simple example is setting a variable to a string:
{{{
@@@set var: string@@@
}}}

The number and type of arguments as well as the usage of extra depends on the command.

== Block commands ==
There are some ''block commands''. Those commands are control structures e.g. loops or scopes. Those blocks start with the block command and end with the special ''end'' command like this:
{{{
@@@if defined a@@@
a is: @@@var a@@@
@@@end@@@
}}}

It is also possible to end the block with a bang version of the command:
{{{
@@@if defined a@@@
a is: @@@var a@@@
@@@!if@@@
}}}
However this syntax is more uncommon yet it may be useful when using complex nesting within the template (document mode) with only few or no line breaks.

== Commands ==
=== Normal commands ===
==== TEMPLATE ====
===== Syntax: =====
{{{
@@@TEMPLATE@@@
}}}
===== Description: =====
This is used as magic. It does not do anything or generate any output.
===== Parameters: =====
none.

==== run ====
===== Syntax: =====
{{{
@@@run $func [{put into $outvar|print [as $encoding]|discard}] [with $argvar]... [errorvar $errvar][: $extra]@@@
}}}
===== Description: =====
This command runs a function. A function can be provided by a module (see ''module'' command) or by the host application or any other library currently loaded.

The function will return a variable. It can be stored (''put into $outvar'') or printed (the default, ''print [[as $encoding'') or simply discarded (''discard'').

The meaning of $argbar and $extra depends on the function called.

===== Parameters: =====
* ''$func'': This is the function name. It is in form ''namespace''bang''function'' (e.g. `std!uname`).
* ''$outvar'': Thi is the variable to store the result of the function call in.
* ''$encoding'': This is the encoding of the output.
* ''$argvar'': This is an variable passed as argument to the function.
* ''$errvar'': This is the name of the variable to store the error value in case of function failure. If this is not set and the function fails the rendering is stopped and the renderer will return in failure.
* ''$extra'': This is a string literal which is passed to the function.

===== Example =====
{{{
@@@run std!uname put into uname@@@
}}}

==== var ====
===== Syntax: =====
{{{
@@@var $var[ as $encoding]@@@
}}}
===== Description: =====
This prints the contents of a variable. If the variable is a structure (array or kv) the structure is printed recursively.
===== Parameters: =====
* ''$var'': The variable to print.
* ''$encoding'': The encoding to print the variable in.

==== varname ====
===== Syntax: =====
{{{
@@@varname $var[ as $encoding]@@@
}}}
===== Description: =====
This is the same as the ''var'' command but prints the name of the variable not it's name. This can be useful when walking thru kvs.
===== Parameters: =====
See ''var''.

==== set ====
===== Syntax: =====
{{{
@@@set $var [of type $type] [to $val]@@@
@@@set $var [of type $type]: $val@@@
}}}
===== Description: =====
Set the variable ''$var'' to value ''$val''.
The syntax using the extra argument is used for strings while the syntax with using the ''to'' keyword is used for other types.
===== Parameters: =====
* ''$var'': The variable to be set.
* ''$type'': The type of variable.
* ''$val'': The value to set ''$var'' to.

==== unset ====
===== Syntax: =====
{{{
@@@unset $var@@@
}}}
===== Description: =====
Unsets (deletes) a the variable ''$var''.
===== Parameters: =====
* ''$var'': The variable to unset.

==== comment ====
===== Syntax: =====
{{{
@@@comment[: $comment]@@@
}}}
===== Description: =====
This is a comment. It will not generate any output.
===== Parameters: =====
* ''$comment'': The comment.

==== include ====
===== Syntax: =====
{{{
@@@include [rootvar $rootvar]: $file@@@
}}}
===== Description: =====
This includes another uste template for processing.
===== Parameters: =====
* ''$rootvar'': This is the new rootvar for the included file. The rootvar is a kv containing all the visible variables.
* ''$file'': The filename of the file to include. This is opened using DSTR.

==== literalinclude ====
===== Syntax: =====
{{{
@@@literalinclude: $file@@@
}}}
===== Description: =====
This includes a file literally. The content of the file is not processed.
===== Parameters: =====
* ''$file'': The filename of the file to include. This is opened using DSTR.

==== literal ====
===== Syntax: =====
{{{
@@@literal: $literal@@@
@@@literal special $special@@@
}}}
===== Description: =====
This prints a literal string. It is mostly useful within a uste mode block to print constant strings.
===== Parameters: =====
* ''$literal'': The string to print.
* ''$special'': A special character to print. Currently supported is "at" ("@") and newline ("\n").

==== at ====
===== Syntax: =====
{{{
@@@at@@@
}}}
===== Description: =====
This is the same as ''@@@literal special at@@@''
===== Parameters: =====
none.

==== module ====
===== Syntax: =====
{{{
@@@module $mod [with para $para] [type $type]@@@
}}}
===== Description: =====
This lodes a module. A module can provide additional features like functions for ''run'' but also other kind of features. The name of the module is always the same as the namespace for exported functions (see ''run'').
===== Parameters: =====
* ''$mod'': Name of the module to load.
* ''$para'': A variable of type kv containing arguments to be passed to the module.
* ''$type'': The type of the module. This is "module" for an uste module or "plugin" for any roardl plugin.

=== Block commands ===

==== ROOT ====
===== Syntax: =====
{{{
@@@ROOT@@@
}}}
===== Description: =====
This is the root element of each processed file. This command is normally not used in templates.
===== Parameters: =====
none.

==== foreach ====
===== Syntax: =====
{{{
@@@foreach $val in $var@@@
@@@foreach $key $val in $var@@@
}}}
===== Description: =====
This walks thru the array or kv ''$var''. ''$val'' is set to the current element and ''$key'' is set to the (key) name of the the current element.
===== Parameters: =====
* ''$val'': The variable to store the current element.
* ''$key'': The variable to store the name of the current element.
* ''$var'': The array or kv to walk thru.

===== Example =====
{{{
@@@foreach key val in var@@@@@@var key@@@: @@@var val@@@
@@@end@@@
}}}

==== if ====
===== Syntax: =====
{{{
@@@if [not] [{true|exists|defined}] $a@@@
@@@if [not] [case [in]sense] {eq|ne|gt|ge|lt|le|begins|ends} $a $b@@@
}}}
===== Description: =====
Test a variable or compare to variables.

The first syntax will test ''$a'' to be true, to exist at all or to be defined.
The second syntax will test if ''$a'' is equal, not equal, grater than, greater or equal than, less than, less or equal than, begins with or ends with ''$b''.

In case floats are compared the equal is ''equal within a range of a maximum error of 0.1%''.
===== Parameters: =====
* ''$a'', ''$b'': variables to test or compare.

==== for ====
===== Syntax: =====
{{{
@@@for $var from $start to $end@@@
}}}
===== Description: =====
This runs a block of multiple times.
===== Parameters: =====
* ''$var'': The variable to store the current value.
* ''$start'': The value to start at (must be a integer literal).
* ''$end'': The value to end at (must be a integer literal).

==== while ====
===== Syntax: =====
To be defined.
===== Description: =====
Reserved for future use.
===== Parameters: =====
To be defined.

==== end ====
===== Syntax: =====
{{{
@@@end@@@
}}}
===== Description: =====
Ends the current (most inner) block.
===== Parameters: =====
none.

==== pragma ====
===== Syntax: =====
{{{
@@@pragma [rootvar $rootvar] [literals $literals] [code $code]@@@
}}}
===== Description: =====
The ''pragma'' command changes settings of the current scope.
===== Parameters: =====
* ''$rootvar'': Set the current rootvar. The rootvar is a kv holding all currently visible variables.
* ''$literals'': Set the type of processing literals. Must be "true" or "false". If enabled ("true", default) all literals between commands are print. If set to "false" they are discarded.
* ''$code'': This is the code processing mode. Must be "document" (default) or "uste". See ''Introduction'' for more information.