4 Command Line Flags
(require denxi/cli-flag) | package: denxi |
When parsing command line flags, Denxi does not store user-defined values as a side effect. Instead, it defers binding values from a command line to settings. Once a process is ready to determine a runtime configuration, it binds values from a command line using call-with-bound-cli-flags.
denxi/cli-flag provides identifiers that are not documented in this section. Each of these provided identifiers match the --<id> form of available setting names, so the cli-flag instance for DENXI_VERBOSE is provided as --DENXI_VERBOSE. You can view all acceptable flags for an instance using cli-flag-strings.
struct
(struct cli-flag ( setting kind additional-flag-strings arity convert help-strings) #:transparent) setting : setting? kind : (or/c 'once-each 'once-any 'multi) additional-flag-strings : (listof string?) arity : exact-nonnegative-integer? convert : procedure? help-strings : (listof string?)
An instance of this structure corresponds to a suitable flag table entry in parse-command-line. The value of kind has the same meaning as it does in parse-command-line.
An instance is used to generate deferred bindings for setting, such that the strings passed in the command line are turned into a Racket values for the setting using convert.
Each instance of cli-flag implicitly carries a longform flag equal to (format "--~a" (setting-id setting)). additional-flag-strings holds acceptable flags recognized by an instance.
convert and help-strings are related in the same way as they are in a program using parse-command-line (see example below). However, arity describes the number of formals accepted by convert minus the flag argument. Therefore it must be the case that (equal? (procedure-arity convert) (add1 arity)).
The below example shows a setting that holds a list of lists, where each sublist holds three numbers. The following cli-flag instance describes the corresponding command line flag and the conversion from user-provided strings to a valid value for the setting.
(define-setting TRIPLET_LIST (listof (list/c real? real? real?)) null) (define --triplet (cli-flag TRIPLET_LIST 'multi '("-t" "--triplet") 3 (λ (flag a b c) (cons (list (string->number a) (string->number b) (string->number c)) (TRIPLET_LIST))) '("number" "number" "number")))
struct
(struct cli-flag-state (flag-string flag-definition bind) #:transparent) flag-string : string? flag-definition : cli-flag? bind : (-> (-> any) any)
flag-string is bound to the exact flag used by the user. bind applies a given thunk such that the setting in flag-definition is bound to a user-defined value in the extent of said thunk.
A particular use of --triplet from the earlier example could generate this state.
; Generated from -t 9 7 22 -t 10 0 0 -t 2 4 5 (cli-flag-state "-t" --triplet (lambda (proc) (TRIPLET_LIST '((2 4 5) (10 0 0) (9 7 22)) proc)))
procedure
(find-cli-flag s) → (or/c #f cli-flag?)
s : setting?
procedure
(make-cli-flag-table c ...) → list?
c : cli-flag?
procedure
(cli-flag-strings c) → (non-empty-listof string?)
c : cli-flag?
procedure
(shortest-cli-flag c) → string?
c : cli-flag?
procedure
(make-cli-flag-string variant) → string?
variant : (or/c string? cli-flag?)
procedure
(format-cli-flags c) → string?
c : cli-flag?
procedure
(call-with-bound-cli-flags flag-states continue) → any flag-states : (listof cli-flag-state?) continue : (-> any)