On this page:
launch-denxi!
top-level-cli
do-command
gc-command
show-command
fetch-command
2.1 CLI Functional Testing
functional-test/  install-all
functional-test/  install-one
check-cli
test-cli
get-checked-links
get-checked-installed-outputs
check-garbage-collection
8.12

2 Command Line Argument Parsers🔗ℹ

 (require denxi/cli) package: denxi

denxi/cli implements the command line parsers for Denxi in terms of denxi/cmdline. Each parser prepares a program that uses continuation passing style to return output and an exit code.

procedure

(launch-denxi! [#:arguments arguments    
  #:format-message format-message    
  #:handle-exit handle-exit])  any
  arguments : (or/c list? vector?)
   = (current-command-line-arguments)
  format-message : message-formatter/c = (get-message-formatter)
  handle-exit : (-> any/c any) = exit
Returns (handle-exit status), where status depends on program behavior caused as a side-effect.

The side-effect is to parse the given command line arguments, then perform work described therein. Any messages encountered are printed to (current-output-port) after being formatted by format-message.

value

top-level-cli : argument-parser/c

Returns a bound-program/c based on the first argument, subcommand, with consideration to command line flags that apply to every possible subcommand. If subcommand is not defined, then the program halts with exit code 1 and output ($cli:undefined-command subcommand).

value

do-command : argument-parser/c

Returns a bound-program/c that carries out work defined in args. In the event no work is possible, then the program will trivially halt with exit code 0 and produce no output.

Otherwise, the command will build a transaction where command-line flags add work to execute in reading order.

value

gc-command : argument-parser/c

Returns a bound-program/c that collects garbage in a target workspace.

Assuming no exceptional behavior, the bound program halts with exit code 0 with output ($finished-collecting-garbage (denxi-collect-garbage)).

value

show-command : argument-parser/c

Returns a bound-program/c with behavior based on the first argument A.

If A is "installed", the program halts with exit code 0 and output (list ($show-datum (list Q O D)) ...), where Q is a string for an exact package query, O is the name of the output from a package defintion identified by Q, and D is a directory path containing the files from the output. All entries represent all installed outputs in the target workspace.

If A is "log", the program halts with exit code 0 and an empty program log. As a side-effect, the program prints all data read from standard input using (current-message-formatter). This is useful when one Denxi user dumps a log to a file, and another wants to read the messages in a different human language or notation.

If "links", the program halts with exit code 0 and output (list ($show-datum (list L T)) ...), where L is a path to a symbolic link, and T is a path to another filesystem entry referenced by that link. These symbolic links are tracked by Denxi for garbage collection purposes, and therefore all T are deleted by gc-command when all relevant values of L do not exist.

In all other cases, the program halts with exit code 1 and output ($cli:undefined-command A).

value

fetch-command : argument-parser/c

Returns a bound-program/c based on the first argument A.

A is treated as a string representation of a datum to evaluate using eval-untrusted-source-expression. If the result is a source and the evaluation produced no I/O (for security), then the command sents bytes produced from the source to (current-output-port). Information about the process is sent to (current-error-port).

This all happens under a runtime configuration, so transfers can be halted by settings like DENXI_FETCH_TOTAL_SIZE_MB.

2.1 CLI Functional Testing🔗ℹ

 (require (submod denxi/cli test))

Reprovides racket, racket/runtime-path, and rackunit.

procedure

(functional-test/install-all definition-variant)  void?

  definition-variant : racket-module-input-variant/c
Effect: For each output of the given package definition, create an ephemeral workspace, install the output, and then uninstall the output.

Call only in the context of a unit test. This function makes many assertions.

If this function runs to completion, the current parameterization is compatible with the given package definition.

procedure

(functional-test/install-one definition-variant    
  [output-name])  void?
  definition-variant : racket-module-input-variant/c
  output-name : string? = DEFAULT_NAME
Like functional-test/install-all, but for a single output in the definition.

procedure

(check-cli arguments continue)  any

  arguments : (or/c (listof string?) (vectorof string?))
  continue : 
(-> exit-code/c
    program-log/c
    bytes?
    bytes?
    any)
Sends command line to Denxi to processing.

Applies continue in tail position to the following arguments:

  1. The exit code of the program

  2. The program log at the end of evaluation.

  3. The contents of standard output after evaluation. Includes localized form of program log.

  4. The contents of standard error after evaluation.

continue may therefore make assertions about the functional correctness of a command line.

procedure

(test-cli message arguments continue)  any

  message : string?
  arguments : (or/c (listof string?) (vectorof string?))
  continue : 
(-> exit-code/c
    program-log/c
    bytes?
    bytes?
    any)
The test form of check-cli.

procedure

(get-checked-links)  (hash/c path-string? path-string?)

Run the show-command with links, makes related assertioins on the data, then returns a hash table. The keys of the hash tables are paths to links. The values are the targets of the links.

Relative paths are made in regards to (DENXI_WORKSPACE).

procedure

(get-checked-installed-outputs)

  (listof (list/c exact-package-query? string? path-string?))
Run the show-command with installed, makes related assertions on the data, then returns a list of lists. The first element of a sublist is an exact package query that identifies a package definition responsible for an output. The second element is the name of that output. The third element, when passed to build-object-path, returns the path to the installed output.

procedure

(check-garbage-collection ok?)  void?

  ok? : predicate/c
Run the gc command, assert expected behaviors, then assert ok? returns #t when applied to the number of bytes recovered.