argParse determines how string args are converted to native Nim types. argHelp explains this interpretation to a command-line user. Define new overloads in-scope of dispatch to override these or support more types.
PARSING AGGREGATES (set,seq,..)
This module also defines argParse/argHelp pairs for seq[T] and such (set[T], HashSet[T], ..) with a full complement of operations: prepend (^=), subtract/delete (-=), as well as the usual append (+= or just =|nothing as is customary, e.g. cc -Ipath1 -Ipath2).
string is treated more as a scalar variable by cligen in that an unqualified [:=<SPACE>] does an overwriting/clobbering assignment rather than adding to the end of the string, but += effects the append if desired. E.g., --foo="" overwrites the value to be an empty string, --foo+="" leaves it unaltered, and --foo^=new prepends "new".
This module also supports a ,-prefixed family of enhanced Delimiter- Prefixed Separated Value operators that allow passing multiple slots to the above operators. DPSV is like typical regex substitution syntax, e.g., /old/new or %search%replace where the first char indicates the delimiter for the rest. Delimiting is strict. (E.g., --foo,^=/old/new/ prepends 3 items @["old", "new", ""] to some foo: seq[string]). Available only in the ,-family is also ,@ as in ,@=<D>V1<D>V2... which does a clobbering assignment of @["V1", "V2", ...]. No delimiter (i.e. "--foo,@=") clips any aggregate to its empty version, e.g. @[].
See more examples and comments in cligen/syntaxHelp.nim
Types
ArgcvtParams = object key*: string ## key actually used for this option val*: string ## value actually given by user sep*: string ## separator actually used (including before '=' text) parNm*: string ## long option key/parameter name parRend*: string ## long option key/parameter name rendered for help parSh*: string ## short key for this option key parCount*: int ## count of times this parameter has been invoked parReq*: int ## flag indicating parameter is mandatory val4req*: string ## how a required/mandatory default value is rendered help*: string ## the whole help string, for parse errors msg*: string ## Error message from a bad parse shortNoVal*: set[char] ## short options keys where value may be omitted longNoVal*: seq[string] ## long option keys where value may be omitted
- Abstraction of non-param-type arguments to argParse and argHelp. Per-use data, then per-parameter data, then per-command/global data.
ClHelpContext = enum clLongOpt, ## a long option identifier clSubCmd, ## a sub-command name identifier clEnumVal ## an enum value name identifier
ElementError = object of ValueError
Procs
proc argAggHelp(dfls: seq[string]; aggTyp: string; typ, dfl: var string) {. ...raises: [], tags: [], forbids: [].}
proc argAggSplit[T](a: var ArgcvtParams; split = true): seq[T]
- Split DPSV (e.g. ",hello,world") into a parsed seq[T].
proc argDf(a: ArgcvtParams; dv: string): string {. ...deprecated: "Deprecated since v0.9.24; No longer needed.", raises: [], tags: [], forbids: [].}
- Deprecated since v0.9.24; No longer needed. Remove call.
proc argHelp(dfl: bool; a: var ArgcvtParams): seq[string] {. ...raises: [ValueError], tags: [], forbids: [].}
proc argHelp(dfl: char; a: var ArgcvtParams): seq[string] {. ...raises: [ValueError], tags: [], forbids: [].}
proc argHelp(dfl: cstring; a: var ArgcvtParams): seq[string] {. ...raises: [ValueError], tags: [], forbids: [].}
proc argHelp(dfl: string; a: var ArgcvtParams): seq[string] {. ...raises: [ValueError], tags: [], forbids: [].}
proc argHelp[T, U](dfl: HSlice[T, U]; a: var ArgcvtParams): seq[string]
proc argHelp[T: enum](dfl: T; a: var ArgcvtParams): seq[string]
proc argHelp[T: SomeNumber](dfl: T; a: var ArgcvtParams): seq[string]
proc argHelp[T](dfl: HashSet[T]; a: var ArgcvtParams): seq[string]
proc argHelp[T](dfl: seq[T]; a: var ArgcvtParams): seq[string]
proc argHelp[T](dfl: set[T]; a: var ArgcvtParams): seq[string]
proc argKeys(a: ArgcvtParams; argSep = "="): string {....raises: [ValueError], tags: [], forbids: [].}
- argKeys generates the option keys column in help tables
proc argParse(dst: var bool; dfl: bool; a: var ArgcvtParams): bool {. ...raises: [ValueError], tags: [], forbids: [].}
proc argParse(dst: var char; dfl: char; a: var ArgcvtParams): bool {. ...raises: [ValueError], tags: [], forbids: [].}
proc argParse(dst: var cstring; dfl: cstring; a: var ArgcvtParams): bool {. ...raises: [], tags: [], forbids: [].}
proc argParse(dst: var string; dfl: string; a: var ArgcvtParams): bool {. ...raises: [ValueError], tags: [], forbids: [].}
proc argParse[T, U](dst: var HSlice[T, U]; dfl: HSlice[T, U]; a: var ArgcvtParams): bool
- Parse i (=== i..i) | a:b (exclusive) | a..b (inclusive) into HSlice. Interpretation is up to caller/slice user. Missing sides get 0.
proc argParse[T: enum](dst: var T; dfl: T; a: var ArgcvtParams): bool
proc argParse[T: SomeNumber](dst: var T; dfl: T; a: var ArgcvtParams): bool
proc argParse[T](dst: var HashSet[T]; dfl: HashSet[T]; a: var ArgcvtParams): bool
proc argParse[T](dst: var seq[T]; dfl: seq[T]; a: var ArgcvtParams): bool
proc argParse[T](dst: var set[T]; dfl: set[T]; a: var ArgcvtParams): bool
proc excl[T](dst: var set[T]; toExcl: openArray[T])
- excl from an openArray; How can this NOT be in the stdlib?
proc getDescription[T](defVal: T; parNm: string; defaultHelp: string): string
proc helpCase(inp: string; context: ClHelpContext = clSubCmd): string {. ...raises: [], tags: [], forbids: [].}
- This is a string-to-string transformer hook to convert whatever the native Nim code identifier casing is into a string for presentation to CLI users. By default it converts snake_case to kebab-case.
proc incl[T](dst: var set[T]; toIncl: openArray[T])
- incl from an openArray; How can this NOT be in the stdlib?
proc nimEscape(s: string; quote = '\"'): string {....raises: [], tags: [], forbids: [].}
- Until strutils gets a nimStringEscape that is not deprecated
proc plural(word: string): string {....raises: [], tags: [], forbids: [].}
- Form English plural of word via all rules not needing a real dictionary.
proc unescape(s: string): string {....raises: [ValueError], tags: [], forbids: [].}
- Handles 1-byte octal, [abtnvfre], and xDD hex escapes