6.9.7 Substitute

This is a simple text macro replacement facility; it is particularly useful for working with localized strings (see Internationalization and localization). In other contexts, using >string-execute (see String words) is often easier.

When using substitute, strings in the form "text%macro%text" (with an arbitrary number of macros) are processed, and the macro variables enclosed in '%' are replaced by 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

wordlist for string replacement macros

replaces ( addr1 len1 addr2 len2 –  ) string-ext

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-colon”

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 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

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.