subexes

Nim support for substitution expressions (subex).

Substitution Expressions (subex)

A subex (Substitution Expression) represents an advanced 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.

Notationmeaning
$#use first or next argument
$nameuse named argument, you can wrap the named argument in curly braces (eg. ${name}) to separate it from the next characters.
$$produces a single $
$1use first argument
$-1use last argument
${1..3}use arguments 1 to 3
${..}use all arguments
$*use all arguments (same as ${..})
${#..}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]1use 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

SubexError = object of ValueError
exception that is raised for an invalid subex   Source Edit
Subex = distinct string
string that contains a substitution expression   Source Edit

Procs

proc subex(s: string): Subex {...}{.raises: [], tags: [].}
constructs a substitution expression from s. Currently this performs no syntax checking but this may change in later versions.   Source Edit
proc addf(s: var string; formatstr: Subex; a: varargs[string, `$`]) {...}{.noSideEffect,
    gcsafe, extern: "nfrmtAddf",
    raises: [SubexError, OverflowError, ValueError, Exception], tags: [RootEffect].}
The same as add(s, formatstr % a), but more efficient.   Source Edit
proc `%`(formatstr: Subex; a: openArray[string]): string {...}{.noSideEffect, gcsafe,
    extern: "nfrmtFormatOpenArray",
    raises: [SubexError, OverflowError, ValueError, Exception], tags: [RootEffect].}
The substitution operator performs string substitutions in formatstr and returns a modified formatstr. This is often called string interpolation.   Source Edit
proc `%`(formatstr: Subex; a: string): string {...}{.noSideEffect, gcsafe,
    extern: "nfrmtFormatSingleElem",
    raises: [SubexError, OverflowError, ValueError, Exception], tags: [RootEffect].}
This is the same as formatstr % [a].   Source Edit
proc format(formatstr: Subex; a: varargs[string, `$`]): string {...}{.noSideEffect, gcsafe,
    extern: "nfrmtFormatVarargs",
    raises: [SubexError, OverflowError, ValueError, Exception], tags: [RootEffect].}
The substitution operator performs string substitutions in formatstr and returns a modified formatstr. This is often called string interpolation.   Source Edit