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.

Variables

uste can handle variables of different types. Those types include integers, strings, floating points, kv (ordered key value pairs (called "hash" in Perl), arrays and more. Some of the commands use variables. Variable names are passed as literals (e.g. @@@var bla@@@ where bla is the name of the variable). Variable names can contain the following characters: "a" to "z", "A" to "Z", underscore ("_"), dash ("-") and dollar ("$"). Both dash and dollar are uncommon. The implementation may allow more characters.

The characters dot (".") and hash ("#") have special meanings. The dot is used to access a member of a kv or array (e.g. mykv.mymemver). The hash is used as special escape sequence. If it is followed by a integer it accesses the member with the given number (e.g. myarray.#0 to access the first element of an array).

The special (read-only) variable ###ROOTVAR### accesses the current rootvar. This way of accessing can be useful with foreach to travel all variables.

Encodings

Encodings are ways to render data. Whenever a variable is printed the encoding can be set. The following encodings exist as of writing this document:

• literal (default): The variable is printed unprocessed.
• html: The variable is processed in a way characters with special meanings in HTML are escaped.
• xml: The variable is processed in a way characters with special meanings in XML are escaped.
• uri: The variable is processed in way it could be used within an URL (e.g. "file?name=@@@var name as uri@@@").
• int: An integer representation of the variable is printed.
• numeric: An numeric representation of the variable is printed.
• hex: An base 16 representation is printed.
• discid: CDDB DiscID representation as used by the RoarAudio PlayList? Daemon.
• uuid: UUID in dashed-hex format.

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 namespacebangfunction (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] [code $code]: $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.
• $code: This is the code processing mode. Must be "document" (default) or "uste". See Introduction for more information.
• $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.