add safe mode

docs/docs/advanced/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "⚡ Advanced",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Advanced concepts"
+  }
+}

docs/docs/advanced/safe.mdx

@@ -0,0 +1,36 @@
+---
+sidebar_position: 1
+---
+
+# Safe Mode
+
+When using a wide glob pattern (such as `*/**`), utpp may match files that you don't want to be processed like compiled binaries etc.
+This could result in the following errors if utpp tries to match a pattern in them:
+
+```
+foo.txt: Command '$[�u�`�F�C���2���%�bԪ]$' found but it is not part of any block.
+foo.txt: Found 1 unmatched commands. Please check your syntax.
+```
+
+or
+
+```
+bar.txt: Command '�Z��C��9�' does not exist.
+```
+
+To prevent this, you can use the `--safe` flag. This will cause utpp to only process files that contains the string `///utpp` anywhere in the file.
+This is a good way to ensure that utpp only processes files that you want it to if you are unable to restrict your glob pattern.
+All occurances of `///utpp` will be removed from the file.
+
+### Ignore unkown commands
+
+As an alternative to safe mode, you can use the `--ignore-unknown` flag. This will cause utpp to ignore any commands that it doesn't recognize.
+If a command is not recognized in a block, the entire block will be ignored (unchanged).
+
+:::caution
+Typos in commands will be ignored with this flag and no error will be thrown. This could result in unwanted behavior.
+:::
+
+:::info
+This flag only checks for unkown **commands**, not variables.
+:::

docs/docs/development/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "🛠️ Development",
-  "position": 5,
+  "position": 9,
   "link": {
     "type": "generated-index",
     "description": "Contribute to the development of the project",

docs/docs/getting-started/usage.mdx

@@ -10,26 +10,30 @@ Universal Text Pre-Processor ('utpp') is a tool for preprocessing any file
 Usage: utpp [options] <files> [variables]
 
 Options:
-      --help         Show help                                         [boolean]
-      --version      Show version number                               [boolean]
-  -o, --output       write to output file                               [string]
-  -c, --check        checks the file's syntax only    [boolean] [default: false]
-  -v, --verbose      show more debug logs             [boolean] [default: false]
-  -p, --print        prints the output to stdout instead of files      [boolean]
-  -q, --quiet        makes the preprocessor quiet     [boolean] [default: false]
-      --ignore       glob pattern to ignore files         [string] [default: ""]
-      --no-eval      disables eval function                            [boolean]
-      --no-files     disables inclusion from files                     [boolean]
-      --no-urls      disables inclusion from urls                      [boolean]
-      --no-env       disables inclusion of environment variables       [boolean]
-      --no-template  disables template replacement                     [boolean]
-      --no-vars      disables variables replacement                    [boolean]
+      --help           Show help                                       [boolean]
+      --version        Show version number                             [boolean]
+  -o, --output         write to output file                             [string]
+  -c, --check          checks the file's syntax only  [boolean] [default: false]
+  -v, --verbose        show more debug logs           [boolean] [default: false]
+  -p, --print          prints the output to stdout instead of files    [boolean]
+  -q, --quiet          makes the preprocessor quiet   [boolean] [default: false]
+      --ignore         glob pattern to ignore files       [string] [default: ""]
+      --no-eval        disables eval function                          [boolean]
+      --no-files       disables inclusion from files                   [boolean]
+      --no-urls        disables inclusion from urls                    [boolean]
+      --no-env         disables inclusion of environment variables     [boolean]
+      --no-template    disables template replacement                   [boolean]
+      --no-vars        disables variables replacement                  [boolean]
+      --ignore-unkown  ignores unknown commands to improve compat      [boolean]
+      --safe           enables safe mode: only process marked files    [boolean]
 
 Examples:
   utpp -o out.txt input.txt  runs the preprocessor on input.txt and write output
                              to out.txt
   utpp input.txt foo=bar     runs the preprocessor on input.txt and sets
                              variable foo to bar
+  utpp "*/**" foo=bar        runs the preprocessor on all files in the current &
+                             sub directory and sets variable foo to bar
   utpp -c input.txt          validates the syntax of input.txt file
 
 for more info and support visit https://github.com/adrianschubek/utpp
@@ -38,6 +42,7 @@ for more info and support visit https://github.com/adrianschubek/utpp
 :::tip
 You can use any glob pattern as *files* argument to select multiple files.
 For example `utpp "*/**" foo=bar` will run the preprocessor on all files in the current directory and all subdirectories and set the variable `foo` to `bar`.
+Or `utpp "foo.txt;bar.tex;baz.html"` will run the preprocessor on `foo.txt`, `bar.tex` and `baz.html`.
 :::
 
 :::info

docs/versioned_docs/version-0.3.x/getting-started/usage.mdx

@@ -38,6 +38,7 @@ for more info and support visit https://github.com/adrianschubek/utpp
 :::tip
 You can use any glob pattern as *files* argument to select multiple files.
 For example `utpp "*/**" foo=bar` will run the preprocessor on all files in the current directory and all subdirectories and set the variable `foo` to `bar`.
+Or `utpp "foo.txt;bar.tex;baz.html"` will run the preprocessor on `foo.txt`, `bar.tex` and `baz.html`.
 :::
 
 :::info

docs/versioned_docs/version-0.4.x/advanced/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "⚡ Advanced",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Advanced concepts"
+  }
+}

docs/versioned_docs/version-0.4.x/advanced/safe.mdx

@@ -0,0 +1,36 @@
+---
+sidebar_position: 1
+---
+
+# Safe Mode
+
+When using a wide glob pattern (such as `*/**`), utpp may match files that you don't want to be processed like compiled binaries etc.
+This could result in the following errors if utpp tries to match a pattern in them:
+
+```
+foo.txt: Command '$[�u�`�F�C���2���%�bԪ]$' found but it is not part of any block.
+foo.txt: Found 1 unmatched commands. Please check your syntax.
+```
+
+or
+
+```
+bar.txt: Command '�Z��C��9�' does not exist.
+```
+
+To prevent this, you can use the `--safe` flag. This will cause utpp to only process files that contains the string `///utpp` anywhere in the file.
+This is a good way to ensure that utpp only processes files that you want it to if you are unable to restrict your glob pattern.
+All occurances of `///utpp` will be removed from the file.
+
+### Ignore unkown commands
+
+As an alternative to safe mode, you can use the `--ignore-unknown` flag. This will cause utpp to ignore any commands that it doesn't recognize.
+If a command is not recognized in a block, the entire block will be ignored (unchanged).
+
+:::caution
+Typos in commands will be ignored with this flag and no error will be thrown. This could result in unwanted behavior.
+:::
+
+:::info
+This flag only checks for unkown **commands**, not variables.
+:::

docs/versioned_docs/version-0.4.x/api/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "🤖 API Reference",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "API Reference"
+  }
+}

docs/versioned_docs/version-0.4.x/api/commands.mdx

@@ -0,0 +1,45 @@
+# Commands
+
+## Commands without side effects
+
+`if <value>` - return true when `<value>` is truthy, otherwise false.
+
+`ifdef <name>` - return true when a variable with name `<name>` is defined, otherwise false.
+
+`ifndef <name>` - return true when a variable with name `<name>` is not defined, otherwise false.
+
+`ifeq <value1> <value2>` - return true when `<value1>` is equal to `<value2>`, otherwise false.
+
+`ifne <value1> <value2>` - return true when `<value1>` is not equal to `<value2>`, otherwise false.
+
+`iflt <value1> <value2>` - return true when `<value1>` is less than `<value2>`, otherwise false.
+
+`ifgt <value1> <value2>` - return true when `<value1>` is greater than `<value2>`, otherwise false.
+
+`ifge <value1> <value2>` - return true when `<value1>` is greater than or equal to `<value2>`, otherwise false.
+
+`ifle <value1> <value2>` - return true when `<value1>` is less than or equal to `<value2>`, otherwise false.
+
+## Commands with side effects
+
+`ifdefs <name> <variable> <newvalue>` - return true when a variable with name `<name>` is defined, otherwise false. If the statement is true, `<variable>` will be set to `<newvalue>`.
+
+`ifndefs <name> <variable> <newvalue>` - return true when a variable with name `<name>` is not defined, otherwise false. If the statement is true, `<variable>` will be set to `<newvalue>`.
+
+`ifeqs <value1> <value2> <variable> <newvalue>` - return true when `<value1>` is equal to `<value2>`, otherwise false. If the statement is true, `<variable>` will be set to `<newvalue>`.
+
+`ifnes <value1> <value2> <variable> <newvalue>` - return true when `<value1>` is not equal to `<value2>`, otherwise false. If the statement is true, `<variable>` will be set to `<newvalue>`.
+
+`iflts <value1> <value2> <variable> <newvalue>` - return true when `<value1>` is less than `<value2>`, otherwise false. If the statement is true, `<variable>` will be set to `<newvalue>`.
+
+`ifgts <value1> <value2> <variable> <newvalue>` - return true when `<value1>` is greater than `<value2>`, otherwise false. If the statement is true, `<variable>` will be set to `<newvalue>`.
+
+`ifges <value1> <value2> <variable> <newvalue>` - return true when `<value1>` is greater than or equal to `<value2>`, otherwise false. If the statement is true, `<variable>` will be set to `<newvalue>`.
+
+`ifles <value1> <value2> <variable> <newvalue>` - return true when `<value1>` is less than or equal to `<value2>`, otherwise false. If the statement is true, `<variable>` will be set to `<newvalue>`.
+
+## Special Commands
+
+`else` - used in a block to define an alternative output when no statement in the block is truthy.	
+
+`end` - used to end a block.

docs/versioned_docs/version-0.4.x/development/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "🛠️ Development",
+  "position": 9,
+  "link": {
+    "type": "generated-index",
+    "description": "Contribute to the development of the project",
+  }
+}

docs/versioned_docs/version-0.4.x/development/contribute.mdx

@@ -0,0 +1,9 @@
+---
+sidebar_position: 2
+---
+# Development
+
+1. clone this repo
+2. run `npm install`
+3. run `npm run build:watch` 
+4. run `node out/index.js`

docs/versioned_docs/version-0.4.x/development/roadmap.mdx

@@ -0,0 +1,10 @@
+---
+sidebar_position: 1
+---
+# Roadmap
+- [x] no-template option
+- [x] include data from other files
+- [x] include data from urls
+- [x] support mutliple files as input
+- [ ] custom markers
+- [ ] possibility to reference variables inside JavaScript expressions

docs/versioned_docs/version-0.4.x/examples/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "✨ Examples",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Examples"
+  }
+}

docs/versioned_docs/version-0.4.x/examples/basic.mdx

@@ -0,0 +1,45 @@
+---
+sidebar_position: 1
+---
+
+# Basic
+
+*Example: test.txt*
+```
+foobar
+$[if `1 + 2 == 4`]$
+a
+$[ifeq foo bar]$
+b ${{foo}}$
+$[else]$
+c
+$[end]$
+
+${{`0.1 + 0.2`}}$
+
+${{file:incl.txt}}$
+
+${{url:https://httpbin.org/uuid}}$
+
+${{env:HOME}}$
+```
+*and incl.txt:* `This was included from incl.txt`
+
+Running this example with `utpp test.txt foo=bar` will result in the following output:
+```
+foobar
+
+b bar
+
+
+0.30000000000000004
+
+This was included from incl.txt
+
+{
+  "uuid": "ba95cd1c-2bb9-4a54-a1a4-5379ce1f2fac"
+}
+
+
+/home/adrian
+```

docs/versioned_docs/version-0.4.x/getting-started/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "🚀 Getting Started",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Getting started"
+  }
+}

docs/versioned_docs/version-0.4.x/getting-started/blocks.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_position: 4
+---
+
+# Blocks
+
+A (template) block can be declared by using one or more `$[<command>]$` statements where `<command>` is a valid command (see API reference below) and must end in a `$[end]$` statement. 
+
+A block's statements are evaluated from top to bottom. If the result of a command is truthy, the guarded section will be outputted and all other commands in this block ignored. 
+
+Otherwise this statement will be skipped and the next statement is evaluated. If no statement in this block is truthy, the `else` section will be outputted and if no `else` section is present, nothing will be outputted.
+
+There can be any number of blocks declared in a file, but blocks **cannot** be nested.

docs/versioned_docs/version-0.4.x/getting-started/commands.mdx

@@ -0,0 +1,7 @@
+---
+sidebar_position: 5
+---
+
+# Commands
+A command generally follows this syntax `$[<name> [arg1] [arg2] ... [argN]]$` 
+where `<name>` is a [command's name](#commands-reference) `[arg]` is a [*Value*](#values). All commands return either `true` or `false`.

docs/versioned_docs/version-0.4.x/getting-started/how-it-works.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 2
+---
+
+# How it works
+
+```mermaid
+graph LR;
+    a(Read file)-->b[Apply template]-->c[Apply variables]-->e(Write file);
+
+```