diff options
author | Karel Kočí <cynerd@email.cz> | 2016-06-01 09:53:03 +0200 |
---|---|---|
committer | Karel Kočí <cynerd@email.cz> | 2016-06-30 17:34:29 +0200 |
commit | e0fb161f1cfa3da9ddfe7f6fe5a82d0273cd34f1 (patch) | |
tree | 25a383a98305ad72639a0828e11b3727c689d615 /docs/builtin_commands.md | |
parent | dfb1010bec3950544eb2875d893de377e6e97f2a (diff) | |
download | geml-e0fb161f1cfa3da9ddfe7f6fe5a82d0273cd34f1.tar.gz geml-e0fb161f1cfa3da9ddfe7f6fe5a82d0273cd34f1.tar.bz2 geml-e0fb161f1cfa3da9ddfe7f6fe5a82d0273cd34f1.zip |
Documentation update
This is update of documentation draft before code implementation.
Diffstat (limited to 'docs/builtin_commands.md')
-rw-r--r-- | docs/builtin_commands.md | 107 |
1 files changed, 107 insertions, 0 deletions
diff --git a/docs/builtin_commands.md b/docs/builtin_commands.md new file mode 100644 index 0000000..79222ad --- /dev/null +++ b/docs/builtin_commands.md @@ -0,0 +1,107 @@ +Built-in commands +================= +Here is full list of all build in commands including its description and sometime +usage examples. For more information see syntax documentation. + +All build in commands are defined in lover case as they are presented here, but +also in upper case. Also you can change initial character, we use here default one +(`$`). + +### $include(PATH) +Includes file content to its place. `PATH` is system path relative to current file +folder or absolute path. + +With this command you can nest any other file content and this content. Note that +because of evaluation principles, content can be evaluated multiple times. If it +is not what you want, common idiom would be use: +``` +$limit(0)$include(file)$endlimit +``` + +### $load(...) +This loads additional modules. sgp searches with precedence for modules in file +directory and in paths defined by environment variable `SGPMODULES`. `NAME` is in +such case relative path to module, but also absolute path can be used. + +Be aware that modules stays loaded even after current file preprocessing is +finished. They are not unloaded automatically after return from include. + +For more information see module documentation. + +### $unload(...) +Serves as opposite to `load` command. It is as it says unloading modules. But it +is not paired with load. + +Without any argument `unload` will unload all loaded modules. + +### $limit(NUM) +This command limits number of evaluation cycles for some text (see evaluation +documentation). After this command all text will be evaluated only `NUM` times. +So `NUM` should be number. Passing empty string results in disabled evaluation +until end of limit command. Default value if not limit command is used is `inf`, +that means no limit. Limit can be ended using `endlimit` command. + +Because of how limit works. Most likely you will use limit without any argument or +with `inf`, or with `1`. Lets see once again what every one does. No argument is +same as `0` so no evaluation is done until `endlimit` command. `inf` removes any +limit and allows any number of nested evaluations. `1` specifies that evaluation +should be done only once. + +You can nest limits together. This results to situation when content is evaluated +limited times but some part of it that is wrapped in another limit block will be +evaluated few times more without sucking up its root limit. + +### $endlimit +This ends previous evaluation limit. Text after this command is not limited by +that. + +### $" +### $' +This is almost same command as `$"`. It has same behavior as if you would write: +``` +$"$limit $Text $endlimit$" +``` +Where result would be: +``` + $Text +``` +So its also limits evaluation. + +### $set(VAR,VALUE) +### $define(VAR,...) +### $enddefine +### $undefine(VAR) +### $math(EQ) +### $if(COND) +### $ifdef(VAR) +### $ifndef(VAR) +### $elif(COND) +### $else +### $endif +### $for(VAR,COND,EQ) +### $endfor +### $while(COND) +### $endwhile +### $switch(VAR) +### $case(VAL) +### $default +### $break +### $continue +### $exec(EXEC,...) +Calls executable `EXEC` with rest of arguments as arguments for executed program. +Standard output from this program is than included to same place as `exec`. + +### $shell(CMD) +This is same as exec, except that instead of defining executable and command line +arguments separately they are defined together in `CMD` argument. In fact you can +specify any shell command in `CMD`. + +### $error(TEXT) +`TEXT` is printed to error output and spg is terminated. + +### $warning(TEXT) +`TEXT` is printed to error output, but sgp continuous preprocessing text. + +### $info(TEXT) +Simply prints `TEXT` to standard output. If standard output is used as output of +result, info is printed to error output. |