This module implements a command-line parser. It has been forked from cligen/parseopt3.

Types

CmdLineKind = enum cmdEnd, ## end of parameters reached cmdArgument, ## non-option argument cmdLongOption, ## long option (`--option`) cmdShortOption, ## short option (`-o`) cmdError ## error encountered during parsing: The detected command-line token
GetOptResult = tuple[kind: CmdLineKind, key, val: string]
OptParser = object of RootObj cmd*: seq[string] ## command line being parsed pos*: int ## current command parameter to inspect offset*: int ## current offset in cmd[pos] for short key block optsDone*: bool ## `--` or a stop word has been seen shortNoVal*: set[char] ## short options not requiring values longNoVal*: seq[string] ## long options not requiring values sepChars*: set[char] ## all chars that can be valid separators requireSep*: bool ## whether =|: required between key and value opChars*: set[char] ## all chars that can prefix a sepChar stopWords*: seq[string] ## special literal parameters acting like `--` sep*: string ## actual string separating key and value kind*: CmdLineKind ## the detected command-line token message*: string ## a message to display on cmdError key*: string ## the argument or option name val*: string ## the value of an option (blank if noVal opt) normalizeOption*: (string) -> string ## normalizes long opts before comparing to longNoVal normalizeStopWord*: (string) -> string ## normalizes stop words before comparing to stopWords

Procs

proc cmdLineRest(p: OptParser): string {....raises: [], tags: [].}

Returns a string of the args that have not yet been parsed.

proc getopt[T: string | seq[string]](cmdline: T = commandLineParams();
                                     shortNoVal: set[char] = {};
                                     longNoVal: seq[string] = @[];
                                     requireSeparator: bool = false;
                                     sepChars: set[char] = {'=', ':'};
                                     opChars: set[char] = {};
                                     stopWords: seq[string] = @[];
    normalizeOption: (string) -> string = (s: string) => s; normalizeStopWord: (
    string) ->
    string = (s: string) => s): seq[GetOptResult]

As the getopt iterator, but returns a sequence.

proc initOptParser[T: string | seq[string]](cmdline: T = commandLineParams();
    shortNoVal: set[char] = {}; longNoVal: seq[string] = @[];
    requireSeparator: bool = false; sepChars: set[char] = {'=', ':'};
    opChars: set[char] = {}; stopWords: seq[string] = @[];
    normalizeOption: (string) -> string = (s: string) => s;
    normalizeStopWord: (string) -> string = (s: string) => s): OptParser

Initializes a command-line parser. cmdline should not include the program name (parameter 0). If cmdline is not given, will default to the current program parameters. If cmdline is a string, it will be split using os.parseCmdLine.

shortNoVal and longNoVal respectively specify short- and long-option keys that do not expect a value.

If requireSeparator is true, option keys and values must be separated by one of the characters in sepChars (e.g., --key=value). If false, the parser understands that only non-noVal arguments will expect args and users may say -aboVal or -o Val or --option Val (as well as the -o=Val or --option=Val syntax, which always works).

If opChars is not empty, then any of those characters that occur before the separator character will be included in the parser's .sep field. This allows "incremental" syntax such as --option+=val.

stopWords are arguments that when seen cause all remaining parameters to be treated as arguments even if they look like options. This is useful for programs with subcommands (e.g., git); it allows you to fully process the command line and reprocess its tail. -- functions as a built-in stopWord. It differs from those in stopWords in that it is not itself returned as an argument.

normalizeOption and normalizeStopWord are procs that alter words before comparing them to longNoVal or stopWords, respectively. For example, passing strutils.normalize will allow the matching of --myOption with --my_option. The default behavior is to match verbatim.

proc next(p: var OptParser) {....raises: [Exception], tags: [RootEffect].}

Advances the parser to the next token. p.kind specifies the kind of token that has been parsed; p.key and p.val are set accordingly.

proc remainingArgs(p: OptParser): seq[string] {....raises: [], tags: [].}

Returns a sequence of the args that have not yet been parsed.

Iterators

iterator getopt(p: var OptParser; reset = false): GetOptResult {. ...raises: [Exception], tags: [RootEffect].}: Convenience iterator for iterating over the given OptParser. Will continue parsing where previous parsing had left off unless reset is true.
iterator getopt[T: string | seq[string]](cmdline: T = commandLineParams(); shortNoVal: set[char] = {}; longNoVal: seq[string] = @[]; requireSeparator: bool = false; sepChars: set[char] = {'=', ':'}; opChars: set[char] = {}; stopWords: seq[string] = @[]; normalizeOption: (string) -> string = (s: string) => s; normalizeStopWord: (string) -> string = (s: string) => s): GetOptResult: Convenience operator that initializes an OptParser and iterates over it.

src/blarg

Types

Procs

Iterators