W3cubDocs

/Nim

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

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.
$$ produces a single $
$1 use first argument
$-1 use 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]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"]

Imports

strutils, strutils

Types

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

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.
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.
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.
proc `%`(formatstr: Subex; a: string): string {.noSideEffect, gcsafe,
    extern: "nfrmtFormatSingleElem",
    raises: [SubexError, OverflowError, ValueError, Exception], tags: [RootEffect].}
This is the same as formatstr % [a].
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.

© 2006–2017 Andreas Rumpf
Licensed under the MIT License.
https://nim-lang.org/docs/subexes.html