Module parseopt

This module provides the standard Nim command line parser. It supports one convenience iterator over all command line options and some lower-level features.

Supported syntax with default empty shortNoVal/longNoVal:

1. short options - -abcd, where a, b, c, d are names
2. long option - --foo:bar, --foo=bar or --foo
3. argument - everything else

When shortNoVal/longNoVal are non-empty then the ':' and '=' above are still accepted, but become optional. Note that these option key sets must be updated along with the set of option keys taking no value, but keys which do take values need no special updates as their set evolves.

When option values begin with ':' or '=' they need to be doubled up (as in --delim::) or alternated (as in --delim=:).

The common -- non-option argument delimiter appears as an empty string long option key. OptParser.cmd, OptParser.pos, and os.parseCmdLine may be used to complete parsing in that case.

Imports

os, strutils

Types

CmdLineKind = enum
  cmdEnd,                     ## end of command line reached
  cmdArgument,                ## argument detected
  cmdLongOption,              ## a long option ``--option`` detected
  cmdShortOption              ## a short option ``-c`` detected

the detected command line token

OptParser = object of RootObj
  cmd*: string
  pos*: int
  inShortState: bool
  shortNoVal: set[char]
  longNoVal: seq[string]
  cmds: seq[string]
  idx: int
  kind*: CmdLineKind           ## the dected command line token
  key*, val*: TaintedString     ## key and value pair; ``key`` is the option
                         ## or the argument, ``value`` is not "" if
                         ## the option was given a value

this object implements the command line parser

Procs

proc initOptParser(cmdline = ""; shortNoVal: set[char] = {};
                  longNoVal: seq[string] = @[]): OptParser {...}{.raises: [],
    tags: [ReadIOEffect].}

inits the option parser. If cmdline == "", the real command line (as provided by the OS module) is taken. If shortNoVal is provided command users do not need to delimit short option keys and values with a ':' or '='. If longNoVal is provided command users do not need to delimit long option keys and values with a ':' or '=' (though they still need at least a space). In both cases, ':' or '=' may still be used if desired. They just become optional.

proc initOptParser(cmdline: seq[TaintedString]; shortNoVal: set[char] = {};
                  longNoVal: seq[string] = @[]): OptParser {...}{.raises: [],
    tags: [ReadIOEffect].}

inits the option parser. If cmdline.len == 0, the real command line (as provided by the OS module) is taken. shortNoVal and longNoVal behavior is the same as for initOptParser(string,...).

proc next(p: var OptParser) {...}{.gcsafe, extern: "npo$1", raises: [], tags: [].}

parses the first or next option; p.kind describes what token has been parsed. p.key and p.val are set accordingly.

proc cmdLineRest(p: OptParser): TaintedString {...}{.gcsafe, extern: "npo$1", raises: [],
    tags: [].}

retrieves the rest of the command line that has not been parsed yet.

Iterators

iterator getopt(p: var OptParser): tuple[kind: CmdLineKind, key, val: TaintedString] {...}{.
    raises: [], tags: [].}

This is an convenience iterator for iterating over the given OptParser object. Example:

var p = initOptParser("--left --debug:3 -l -r:2")
for kind, key, val in p.getopt():
  case kind
  of cmdArgument:
    filename = key
  of cmdLongOption, cmdShortOption:
    case key
    of "help", "h": writeHelp()
    of "version", "v": writeVersion()
  of cmdEnd: assert(false) # cannot happen
if filename == "":
  # no filename has been given, so we show the help:
  writeHelp()

iterator getopt(cmdline: seq[TaintedString] = commandLineParams();
               shortNoVal: set[char] = {}; longNoVal: seq[string] = @[]): tuple[
    kind: CmdLineKind, key, val: TaintedString] {...}{.raises: [], tags: [ReadIOEffect].}

This is an convenience iterator for iterating over command line arguments. This creates a new OptParser. See the above getopt(var OptParser) example for using default empty NoVal parameters. This example is for the same option keys as that example but here option key-value separators become optional for command users:

for kind, key, val in getopt(shortNoVal = { 'l' },
                             longNoVal = @[ "left" ]):
  case kind
  of cmdArgument:
    filename = key
  of cmdLongOption, cmdShortOption:
    case key
    of "help", "h": writeHelp()
    of "version", "v": writeVersion()
  of cmdEnd: assert(false) # cannot happen
if filename == "":
  writeHelp()