Changes between Version 2 and Version 3 of uste/ParserSyntax

Timestamp:

02/03/13 15:05:22 (11 years ago)

Author:

ph3-der-loewe

Comment:

+ infos about all commands

uste/ParserSyntax

@@ -57 +57 @@
 == 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.