A subex (Substitution Expression) represents an advanted string substitution. In contrast to a regex which deals with string analysis, a subex deals with string synthesis.
Thanks to its conditional construct $[0|1|2|else] it supports internationalization of format string literals quite well.
| Notation | meaning |
|---|---|
| $# | use first or next argument |
| $name | use named argument, you can wrap the named argument in curly braces (eg. ${name}) to separate it from the next characters. |
| $1 | use first argument |
| $-1 | use last argument |
| ${1..3} | use arguments 1 to 3 |
| ${..} | use all arguments |
| ${#..} | use all remaining arguments |
| ${..-2} | use all arguments except the last argument |
| ${$1} | use argument X where X = parseInt(arg[1]) |
| ${$1..$2} | use arguments X to Y where X = parseInt(arg[1]) and Y = parseInt(arg[2]) |
| $','{1..3} | use arguments 1 to 3 and join them with ',' |
| $','80c'\n'{..} | use all arguments, join them with ','. Insert '\n' before the resulting string exceeds 80 chars. |
| $','8i'\n'{..} | use all arguments, join them with ','. Insert '\n' after every 8th item. |
| $' '~{1..3} | use arguments 1 to 3 with a leading space if the concatenation of 1..3 is not the empty string |
| $[zero|one|def]1 | use X = parseInt(arg[1]) to determine which branch to use. If X == 0 the 'zero' branch is selected, if X == 1 the 'one' branch is selected, etc. Otherwise the 'def' branch is selected. $x is interpreted in branches too. If a branch needs to contain |, ] put them in single quotes. To produce a verbatim single quote, use ''. |
Examples
subex"$1($', '{2..})" % ["f", "a", "b", "c"] == "f(a, b, c)" subex"$1 $[files|file|files]{1} copied" % ["1"] == "1 file copied" subex"$['''|'|''''|']']#" % "0" == "'|" subex("type\n TEnum = enum\n $', '40c'\n '{..}") % [ "fieldNameA", "fieldNameB", "fieldNameC", "fieldNameD"]
Types
EInvalidSubex = object of EInvalidValue
- exception that is raised for an invalid subex
TSubex = distinct string
- string that contains a substitution expression
Procs
proc subex(s: string): TSubex {.raises: [], tags: [].}
- constructs a substitution expression from s. Currently this performs no syntax checking but this may change in later versions.
proc addf(s: var string; formatstr: TSubex; a: varargs[string, `$`]) {. noSideEffect, rtl, extern: "nfrmtAddf", raises: [EInvalidSubex, EOverflow, EInvalidValue, E_Base], tags: [TEffect].}
- The same as add(s, formatstr % a), but more efficient.
proc `%`(formatstr: TSubex; a: openArray[string]): string {.noSideEffect, rtl, extern: "nfrmtFormatOpenArray", raises: [EInvalidSubex, EOverflow, EInvalidValue, E_Base], tags: [TEffect].}
- The substitution operator performs string substitutions in formatstr and returns a modified formatstr. This is often called string interpolation.
proc `%`(formatstr: TSubex; a: string): string {.noSideEffect, rtl, extern: "nfrmtFormatSingleElem", raises: [EInvalidSubex, EOverflow, EInvalidValue, E_Base], tags: [TEffect].}
- This is the same as formatstr % [a].
proc format(formatstr: TSubex; a: varargs[string, `$`]): string {.noSideEffect, rtl, extern: "nfrmtFormatVarargs", raises: [EInvalidSubex, EOverflow, EInvalidValue, E_Base], tags: [TEffect].}
- The substitution operator performs string substitutions in formatstr and returns a modified formatstr. This is often called string interpolation.