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:
- short options - -abcd, where a, b, c, d are names
- long option - --foo:bar, --foo=bar or --foo
- 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.
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 Source Edit
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 Source Edit
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. Source Edit
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,...). Source Edit
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. Source Edit
proc cmdLineRest(p: OptParser): TaintedString {...}{.gcsafe, extern: "npo$1", raises: [], tags: [].}
- retrieves the rest of the command line that has not been parsed yet. Source Edit
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()
Source Edit 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()
Source Edit