Module parseutils

This module contains helpers for parsing tokens, numbers, identifiers, etc.

Imports

sequtils

Types

InterpolatedKind = enum
  ikStr,                      ## ``str`` part of the interpolated string
  ikDollar,                   ## escaped ``$`` part of the interpolated string
  ikVar,                      ## ``var`` part of the interpolated string
  ikExpr                      ## ``expr`` part of the interpolated string

describes for interpolatedFragments which part of the interpolated string is yielded; for example in "str$$$var${expr}"

Procs

proc parseHex(s: string; number: var int; start = 0; maxLen = 0): int {.gcsafe,
    extern: "npuParseHex", noSideEffect, raises: [], tags: [].}

Parses a hexadecimal number and stores its value in number.

Returns the number of the parsed characters or 0 in case of an error. This proc is sensitive to the already existing value of number and will likely not do what you want unless you make sure number is zero. You can use this feature to chain calls, though the result int will quickly overflow. Example:

var value = 0
discard parseHex("0x38", value)
assert value == 56
discard parseHex("0x34", value)
assert value == 56 * 256 + 52
value = -1
discard parseHex("0x38", value)
assert value == -200

If 'maxLen==0' the length of the hexadecimal number has no upper bound. Not more than ```maxLen`` characters are parsed.

proc parseOct(s: string; number: var int; start = 0): int {.gcsafe, extern: "npuParseOct",
    noSideEffect, raises: [], tags: [].}

parses an octal number and stores its value in number. Returns the number of the parsed characters or 0 in case of an error.

proc parseIdent(s: string; ident: var string; start = 0): int {.raises: [], tags: [].}

parses an identifier and stores it in ident. Returns the number of the parsed characters or 0 in case of an error.

proc parseIdent(s: string; start = 0): string {.raises: [], tags: [].}

parses an identifier and stores it in ident. Returns the parsed identifier or an empty string in case of an error.

proc parseToken(s: string; token: var string; validChars: set[char]; start = 0): int {.
    inline, deprecated, raises: [], tags: [].}

parses a token and stores it in token. Returns the number of the parsed characters or 0 in case of an error. A token consists of the characters in validChars.

Deprecated since version 0.8.12: Use parseWhile instead.

proc skipWhitespace(s: string; start = 0): int {.inline, raises: [], tags: [].}

skips the whitespace starting at s[start]. Returns the number of skipped characters.

proc skip(s, token: string; start = 0): int {.inline, raises: [], tags: [].}

skips the token starting at s[start]. Returns the length of token or 0 if there was no token at s[start].

proc skipIgnoreCase(s, token: string; start = 0): int {.raises: [], tags: [].}

same as skip but case is ignored for token matching.

proc skipUntil(s: string; until: set[char]; start = 0): int {.inline, raises: [], tags: [].}

Skips all characters until one char from the set until is found or the end is reached. Returns number of characters skipped.

proc skipUntil(s: string; until: char; start = 0): int {.inline, raises: [], tags: [].}

Skips all characters until the char until is found or the end is reached. Returns number of characters skipped.

proc skipWhile(s: string; toSkip: set[char]; start = 0): int {.inline, raises: [], tags: [].}

Skips all characters while one char from the set token is found. Returns number of characters skipped.

proc parseUntil(s: string; token: var string; until: set[char]; start = 0): int {.inline,
    raises: [], tags: [].}

parses a token and stores it in token. Returns the number of the parsed characters or 0 in case of an error. A token consists of the characters notin until.

proc parseUntil(s: string; token: var string; until: char; start = 0): int {.inline,
    raises: [], tags: [].}

parses a token and stores it in token. Returns the number of the parsed characters or 0 in case of an error. A token consists of any character that is not the until character.

proc parseUntil(s: string; token: var string; until: string; start = 0): int {.inline,
    raises: [], tags: [].}

parses a token and stores it in token. Returns the number of the parsed characters or 0 in case of an error. A token consists of any character that comes before the until token.

proc parseWhile(s: string; token: var string; validChars: set[char]; start = 0): int {.
    inline, raises: [], tags: [].}

parses a token and stores it in token. Returns the number of the parsed characters or 0 in case of an error. A token consists of the characters in validChars.

proc captureBetween(s: string; first: char; second = '\0'; start = 0): string {.raises: [],
    tags: [].}

Finds the first occurrence of first, then returns everything from there up to second (if second is '0', then first is used).

proc parseBiggestInt(s: string; number: var BiggestInt; start = 0): int {.gcsafe,
    extern: "npuParseBiggestInt", noSideEffect, raises: [], tags: [].}

parses an integer starting at start and stores the value into number. Result is the number of processed chars or 0 if there is no integer. EOverflow is raised if an overflow occurs.

proc parseInt(s: string; number: var int; start = 0): int {.gcsafe, extern: "npuParseInt",
    noSideEffect, raises: [OverflowError], tags: [].}

parses an integer starting at start and stores the value into number. Result is the number of processed chars or 0 if there is no integer. EOverflow is raised if an overflow occurs.

proc parseBiggestUInt(s: string; number: var BiggestUInt; start = 0): int {.gcsafe,
    extern: "npuParseBiggestUInt", noSideEffect, raises: [], tags: [].}

parses an unsigned integer starting at start and stores the value into number. Result is the number of processed chars or 0 if there is no integer or overflow detected.

proc parseUInt(s: string; number: var uint; start = 0): int {.gcsafe,
    extern: "npuParseUInt", noSideEffect, raises: [], tags: [].}

parses an unsigned integer starting at start and stores the value into number. Result is the number of processed chars or 0 if there is no integer or overflow detected.

proc parseBiggestFloat(s: string; number: var BiggestFloat; start = 0): int {.
    magic: "ParseBiggestFloat", importc: "nimParseBiggestFloat", noSideEffect.}

parses a float starting at start and stores the value into number. Result is the number of processed chars or 0 if a parsing error occurred.

proc parseFloat(s: string; number: var float; start = 0): int {.gcsafe,
    extern: "npuParseFloat", noSideEffect, raises: [], tags: [].}

parses a float starting at start and stores the value into number. Result is the number of processed chars or 0 if there occurred a parsing error.

Iterators

iterator interpolatedFragments(s: string): tuple[kind: InterpolatedKind,
    value: string] {.raises: [ValueError], tags: [].}

Tokenizes the string s into substrings for interpolation purposes.

Example:

for k, v in interpolatedFragments("  $this is ${an  example}  $$"):
  echo "(", k, ", \"", v, "\")"

Results in:

(ikString, "  ")
(ikExpr, "this")
(ikString, " is ")
(ikExpr, "an  example")
(ikString, "  ")
(ikDollar, "$")