# 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"]```

# Imports

strutils, strutils

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