3 Command Line Utilities
| (require denxi/cmdline) | package: denxi |
denxi/cmdline provides all bindings from racket/cmdline, as well as the bindings documented in this section. Unlike denxi/cli, denxi/cmdline does not actually define a command line interface. It only helps denxi/cli do so.
3.1 CLI Value Types
value
exit-code/c : flat-contract? = (integer-in 0 255)
Denxi does not currently lean on the exit code to convey much meaning, so expect to see 1 (E_FAIL) to represent an error state. Lean on the program log for specifics.
value
exit-handler/c : contract? = (-> exit-code/c any)
value
= (-> (-> exit-code/c (or/c $message? subprogram-log/c) any) any)
The only argument is a procedure (probably representing a continuation) that accepts an exit code and a subprogram log representing program output. That continuation will decide how to react to the given information.
value
= (-> arguments/c (values (listof cli-flag-state?) bound-program/c))
procedure
(coerce-command-line-argument-string value) → string?
value : any/c
value, if value is a string.
(make-cli-flag-string value), if value is a cli-flag.
(~a value), if value is a path.
(~s value) otherwise.
procedure
(make-command-line-arguments value ...) → (listof string?)
value : any/c
procedure
(coerce-command-line-argument-list variant) → (listof string?)
variant : arguments/c
3.2 CLI Flow Control
procedure
(run-entry-point! args formatter parse-args on-exit) → any args : arguments/c formatter : message-formatter/c parse-args : argument-parser/c on-exit : exit-handler/c
This module mimics production behavior.
(module+ main (run-entry-point! (current-command-line-arguments) (get-message-formatter) top-level-cli exit))
procedure
(cli #:program program [ #:flags flags #:args args #:help-suffix-string-key help-suffix-string-key] #:arg-help-strings arg-help-strings handle-arguments)
→
(listof cli-flag-state?) bound-program/c program : string? flags : list? = null
args : (or/c (vector/c string?) (listof string?)) = (current-command-line-arguments) help-suffix-string-key : (or/c #f symbol?) = #f arg-help-strings : (listof string?)
handle-arguments :
(->* ((listof cli-flag-state?)) () #:rest list? (values (listof cli-flag-state?) bound-program/c))
First, cli applies the following expression:
(parse-command-line program args flags handle-arguments arg-help-strings handle-help)
Note that some arguments used as-is. Others are computed towards the same ends.
handle-help adds localized contextual help using help-suffix-string-key. The exit code from such a program is 0 if the user actually requested help in args. 1 otherwise. The same help suffix is used in the event the user does not pass enough positional arguments for handle-arguments.
The following example shows the relationship between command line parsing, a runtime configuration based on flags, and actual program execution.
(define (say-hello . args) (cli #:program "hi" #:flags null #:args args #:arg-help-strings '("names") (lambda (flags . names) (values flags (lambda (halt) (halt 0 (for/list ([name names]) ($show-string (format "Hello, ~a!" name))))))))) (define-values (flags program) (say-hello "john" "sage" "mary")) (define message->string (get-message-formatter)) (call-with-bound-cli-flags flags (lambda () (program (lambda (exit-code messages) (printf "Exit code: ~a~n" exit-code) (for ([m messages]) (write-message m message->string))))))
3.3 CLI Messages
struct
(struct $cli:undefined-command $cli (command) #:prefab) command : string?
struct
(struct $cli:show-help $cli (body-string string-suffix-key) #:prefab) body-string : string? string-suffix-key : (or/c #f symbol?)