diff --git a/docs/config-syntax.html b/docs/config-syntax.html index 35deecd..fdabcb2 100644 --- a/docs/config-syntax.html +++ b/docs/config-syntax.html @@ -103,19 +103,28 @@ The `REPLACE` statement in the above example may be used to quote closing commen The search pattern may be a regular expression, and the replacement string may include backreferences. This gives you quite a powerful means for text modification. The following example is used to insert a space between all characters of the input text: - replace "(.)" with "\\1 " - reverse "(.) " to "\\1" + replace "(.)" with "$1 " + reverse "(.) " to "$1" -There may be many `REPLACE`/`REVERSE` statements in one design definition. They will be executed one after the other, starting from the top. +There may be many `REPLACE`/`REVERSE` statements in one design definition. They will be executed one after the other, +starting from the top. -Note that as in all strings, backslashes must be doubled, i.e. *boxes* "consumes one layer of backslashes". This is why in the first example, there are two backslashes at the beginning of the search pattern, when only one would have been needed to escape the star operator. Alternately, you may use the [`delimiter` statement](#delim) to change the string delimiting and escape character. +Note that as in all strings, backslashes must be doubled, i.e. *boxes* "consumes one layer of backslashes". This is +why in the first example, there are two backslashes at the beginning of the search pattern, when only one would have +been needed to escape the star operator. -You may choose if the replacement is performed *once* per line or as many times as necessary to replace all occurrences -of the sarch pattern (*global*). Put this indication in front of the search pattern (the default is `global`): +The [`delimiter` statement](#delim) should not be used to change the string delimiting and escape character in +regular expressions. While this is possible, it only affects *boxes*' processing, not the regular expression engine's. +This will most likely cause confusion. + +You may choose if the replacement is performed `once` per line or as many times as necessary to replace all occurrences +of the sarch pattern (`global`). Put this indication in front of the search pattern (the default is `global`): replace once "foo" with "bar" -For more information on how to use regular expressions, please see `man 5 regexp`, under "Basic Regular Expressions" or any other source. +We use [PCRE2](https://www.pcre.org/current/doc/html/) regular expression syntax. In order to craft the proper +regular expressions, online tools such as [Regex101](https://regex101.com/) or [Regexper](https://regexper.com/) might +come in handy. ### Indentation Mode diff --git a/examples.html b/examples.html index 91841f5..fcdabd4 100644 --- a/examples.html +++ b/examples.html @@ -27,6 +27,21 @@ Unless stated otherwise, the input used for these examples is the following: Draws a standard box of the first valid design found in your config file. If you have the config file as it comes with the *boxes* distribution, you get a "C" box, as you can see above. + + +## Combining with other tools + +As a text filter, *boxes* can be combined easily with other tools, for example *figlet* and *lolcat*: + +`figlet "boxes . . . !" | lolcat -f | boxes -d unicornthink` + +
+boxes with figlet and lolcat +
+ +Note: *lolcat* is supported since *boxes* v2.0.0. + + ## Choosing a different design @@ -303,7 +318,9 @@ Finally, it is also possible to throw away any indentation altogether by specify /* G l o b a l V a r i a b l e s */ /*************************************/ -The `replace` and `reverse` statements may contain regular expressions and backreferences, which can be used for more elaborate text modifications. The example shown here, where spaces are inserted between the individual characters, is configured [like this](https://github.com/{{ site.github }}/blob/9eb1472f9c54d88f574017ad4b4912a94bd5a2f0/boxes-config#L1942-L1945). +The `replace` and `reverse` statements may contain regular expressions and backreferences, which can be used for more +elaborate text modifications. The example shown here, where spaces are inserted between the individual characters, is +configured [like this](https://github.com/{{ site.github }}/blob/ac8617b3839d372e108b6eea3a5e7743232281da/boxes-config#L1734-L1739). `boxes -d headline -r` diff --git a/images/example-with-tools.png b/images/example-with-tools.png new file mode 100644 index 0000000..96c19d8 Binary files /dev/null and b/images/example-with-tools.png differ