From 771fef9f4545a08b5690b7a40ed57cea8ae9a95a Mon Sep 17 00:00:00 2001 From: Thomas Jensen Date: Wed, 17 Feb 2021 20:58:16 +0100 Subject: [PATCH] Update regex usage info --- docs/config-syntax.html | 23 ++++++++++++++++------- examples.html | 19 ++++++++++++++++++- images/example-with-tools.png | Bin 0 -> 5895 bytes 3 files changed, 34 insertions(+), 8 deletions(-) create mode 100644 images/example-with-tools.png 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 0000000000000000000000000000000000000000..96c19d8ba848332bf321c85dbc9ed8dc595cc9c3 GIT binary patch literal 5895 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 literal 0 HcmV?d00001