This is a simple text macro replacement facility. Texts in the form
"text %macro% text" are processed, and the macro variables enclosed
in '%' are replaced with their associated strings. Two
consecutive % are replaced by one %. Macros are defined
in a specific wordlist, and return a string upon execution; the standard
defines only one way to declare macros, replaces, which creates a
macro that just returns a string.
macros-wordlist ( – wid ) gforth-experimental “macros-wordlist”
wordlist for string replacement macros
replaces ( addr1 len1 addr2 len2 – ) string-ext “replaces”
create a macro with name addr2 len2 and content addr1 len1. If the macro already exists, just change the content.
replacer: ( "name" – ) gforth-experimental “replacer:”
Start a colon definition name in macros-wordlist,
i.e. this colon definition is a macro. It must have the stack
effect ( – addr u ).
.substitute ( addr1 len1 – n / ior ) gforth-experimental “dot-substitute”
substitute all macros in text addr1 len1 and print the result. n is the number of substitutions or, if negative, a throwable ior.
$substitute ( addr1 len1 – addr2 len2 n/ior ) gforth-experimental “string-substitute”
substitute all macros in text addr1 len1. n is the number of substitutions, if negative, it’s a throwable ior, addr2 len2 the result.
substitute ( addr1 len1 addr2 len2 – addr2 len3 n/ior ) string-ext “substitute”
substitute all macros in text addr1 len1, and copy the result to addr2 len2. n is the number of substitutions or, if negative, a throwable ior, addr2 len3 the result.
unescape ( addr1 u1 dest – dest u2 ) string-ext “unescape”
double all delimiters in addr1 u1, so that substitute will result in the original text. Note that the buffer dest does not have a size, as in worst case, it will need just twice as many characters as u1. dest u2 is the resulting string.
$unescape ( addr1 u1 – addr2 u2 ) gforth-experimental “string-unescape”
same as unescape, but creates a temporary destination string with
$tmp.