▼Denxi Reference
►3 Command Line Utilities
On this page:
3.1 CLI Value Types
exit-code/  c
exit-handler/  c
bound-program/  c
arguments/  c
argument-parser/  c
program-log/  c
coerce-command-line-argument-string
make-command-line-arguments
coerce-command-line-argument-list
3.2 CLI Flow Control
run-entry-point!
cli
3.3 CLI Messages
$cli
$cli:  undefined-command
$cli:  show-help
8.12
  top  contents    up   

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)

An exit code for use in an exit handler.

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)

A procedure that reacts to an exit code, like exit.

value

bound-program/c : contract?

 = (-> (-> exit-code/c (or/c $message? subprogram-log/c) any) any)
A procedure meant to run predetermined program logic in the context of a runtime configuration.

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 : chaperone-contract?

 = (or/c (listof string?) (listof vector?))
Represents arguments provided in a command line. An argument list may be a vector or list of strings for flexibility reasons.

value

argument-parser/c : contract?

 = (-> arguments/c (values (listof cli-flag-state?) bound-program/c))
A procedure that parses command line arguments and plans further action.

value

program-log/c : chaperone-contract?

 = (or/c $message? (listof $message?))
A program log is a single message or list of messages that report exact program behavior. The list is sorted such that the first element is the first message to report in the respective program.

procedure

(coerce-command-line-argument-string value) → string?

  value : any/c
Returns

procedure

(make-command-line-arguments value ...) → (listof string?)

  value : any/c
Returns a list built using coerce-command-line-argument-string on the arguments.

procedure

(coerce-command-line-argument-list variant) → (listof string?)

  variant : arguments/c
Applies make-command-line-arguments to a list or vector, and returns a list.

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 translates the given command-line arguments to a program to run in the relevant runtime configuration, and applies on-exit to the exit code of the process.

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))
Returns captured command line flags and a procedure representing the program’s behavior.

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 $message ()
    #:prefab)
A message that pertains to a command line interface.

struct

(struct $cli:undefined-command $cli (command)
    #:prefab)
  command : string?
A user passed command as a subcommand, but it is not defined.

struct

(struct $cli:show-help $cli (body-string string-suffix-key)
    #:prefab)
  body-string : string?
  string-suffix-key : (or/c #f symbol?)
A message that formats as context-sensitive help. body-string is help content generated by parse-command-line. string-suffix-key is an internal value used to select a localized string to append to said help.

  top  contents    up