From e0fb161f1cfa3da9ddfe7f6fe5a82d0273cd34f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karel=20Ko=C4=8D=C3=AD?= Date: Wed, 1 Jun 2016 09:53:03 +0200 Subject: Documentation update This is update of documentation draft before code implementation. --- docs/builtin_commands.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++ docs/evaluation.md | 2 + docs/index.md | 1 + docs/module_creation.md | 0 docs/modules/array.md | 1 + docs/modules/file.md | 1 + docs/modules/protect.md | 1 + docs/modules/python.md | 1 + docs/syntax.md | 66 +++++++++++++++++++++++++++++ 9 files changed, 180 insertions(+) create mode 100644 docs/builtin_commands.md create mode 100644 docs/evaluation.md create mode 120000 docs/index.md create mode 100644 docs/module_creation.md create mode 120000 docs/modules/array.md create mode 120000 docs/modules/file.md create mode 120000 docs/modules/protect.md create mode 120000 docs/modules/python.md create mode 100644 docs/syntax.md (limited to 'docs') 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. diff --git a/docs/evaluation.md b/docs/evaluation.md new file mode 100644 index 0000000..04d8854 --- /dev/null +++ b/docs/evaluation.md @@ -0,0 +1,2 @@ +Evaluation process +================== diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 0000000..32d46ee --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/docs/module_creation.md b/docs/module_creation.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/modules/array.md b/docs/modules/array.md new file mode 120000 index 0000000..1c9ed09 --- /dev/null +++ b/docs/modules/array.md @@ -0,0 +1 @@ +../../modules/array/README.md \ No newline at end of file diff --git a/docs/modules/file.md b/docs/modules/file.md new file mode 120000 index 0000000..82313a3 --- /dev/null +++ b/docs/modules/file.md @@ -0,0 +1 @@ +../../modules/file/README.md \ No newline at end of file diff --git a/docs/modules/protect.md b/docs/modules/protect.md new file mode 120000 index 0000000..5a63a23 --- /dev/null +++ b/docs/modules/protect.md @@ -0,0 +1 @@ +../../modules/protect/README.md \ No newline at end of file diff --git a/docs/modules/python.md b/docs/modules/python.md new file mode 120000 index 0000000..cdce586 --- /dev/null +++ b/docs/modules/python.md @@ -0,0 +1 @@ +../../modules/python/README.md \ No newline at end of file diff --git a/docs/syntax.md b/docs/syntax.md new file mode 100644 index 0000000..fa00287 --- /dev/null +++ b/docs/syntax.md @@ -0,0 +1,66 @@ +Syntax +====== +Syntax consist from expandable macros and commands. They are both used in code +with initial character. In default `$`, but other can be used if specified as +argument to program. After this character is name of macro. Names are case +sensitive, without spaces and special character, except underscore. + +For example this text: +``` +$set(VAR, Hello)$VAR World! +``` +Is expanded to: +``` +Hello World! +``` + +If you want use initial character without preprocessing, you should write it two +times. So if our initial character is `$`, you should use `$$`. Also you can use +`--permissive` argument to disable error when initial character is not followed by +known name. In such case is preprocessor treating it as it is part of text and let +it be without change. Be aware that collisions with names can occur and no typing +errors will be reported. Also you can limit preprocessing with `limit` command. If +you set limit, only given number of macros and commands is expanded. + +Macros and commands can have arguments. Arguments are used to pass text to them. +Every argument can be specified on multiple lines and separated from others using +coma. All empty characters (spaces, tabulators and new lines) are removed from +beginning and end of argument. You can enclosure argument using `$'` or `$"`, which +will ensure that empty characters will stay in argument. But be aware that even +when `$'` or `$"` is used macros and functions inside argument is evaluated. Another +usage for enclosing argument to `$'` or `$"` is to ignore `)` and `,`. + +End of macro or command is identified by other character that is not known. Or +bracket that is used to bound arguments to commands and macros. Or you can use `-` +as special meaning. `-` is removed during processing which allows you to paste +anything anywhere. For example `Without$SPACE-spaces`. + +Difference between macros and commands is that macros are defined in text and +allows only simple expansion. Additional commands are defined using modules. +At the end, commands are more versatile than macros, but requires more work to +create. + +Some commands can be paired with some other commands. Common example is "if" with +its paired commands "else", "elif" and "endif". Paired commands are defined as +that first of them defines behavior and second one ends it or changes it for next +text. It should newer be that second one somehow defines behavior for previous +processed text. Also to ensure that code is contained inside file, all first +commands allowing pairs has default ending command. If file is read to end and no +pair is found, default end is artificially inserted. Also no paired command opened +before including can be ended in included file. + +Special macros +-------------- +These macros has special meaning. They can't be redefined, but can be overloaded +using modules. And they are not defined in processed text. +### SGP_VERSION +Expands to version of sgp tool. +### FILE +Expands to name of file that is processed. This macro is not changing during whole +preprocessing. Note that you can use it in included files to identify name of +original preprocessed file. +### LINE +This macro is expanded always to line number on which it is specified in source +text. +### MODULES +This macro specifies coma separated list of active modules. -- cgit v1.2.3