18 Adding a raco Command
The set of commands supported by raco can be extended by installed packages, PLaneT packages, and other collections. A command is added by defining raco-commands in the "info.rkt" library of a collection (see "info.rkt" File Format), and then raco setup (as called directly or as part of a package or PLaneT installation) must index the "info.rkt" file.
The value bound to raco-commands must be a list of command specifications, where each specification is a list of four values:
(list command-string implementation-module-path description-string prominence)
The command-string is the command name. Any unambiguous prefix of a command name can be supplied to raco to invoke the command.
The implementation-module-path names the implementation though a module path (in the sense of module-path?). The module is loaded and invoked through dynamic-require to run the command. The module can access command-line arguments through the current-command-line-arguments parameter, which is adjusted before loading the command module to include only the arguments to the command. The current-command-name parameter is also set to the command name used to load the command. When raco help is used on a command, the command is launched with an initial --help argument in current-command-line-arguments.
The description-string is a short string used to describe the command in response to raco help. The description should not be capitalized or end with a period.
The prominence value should be a real number or #f. A #f value means that the command should not be included in the short list of “frequently used commands.” A number indicates the relative prominence of the command; the help command has a value of 110, and probably no command should be more prominent. The pack tool, which is currently ranked as the least-prominent of the frequently used commands, has a value of 10.
As an example, the "info.rkt" of the "compiler" collection might contain the
(define raco-commands '(("make" compiler/commands/make "compile source to bytecode" 100) ("decompile" compiler/commands/decompile "decompile bytecode" #f)))
so that make is treated as a frequently used command, while decompile is available as an infrequently used command.
18.1 Command Argument Parsing
|(require raco/command-name)||package: base|
(current-command-name) → (or/c string? #f)
(current-command-name name) → void? name : (or/c string? #f)
A command implementation can use this parameter to determine whether it was invoked via raco or through some other means.
The result of this function is suitable for use with command-line. For example, the decompile tool parses command-line arguments with
(define source-files (command-line #:program (short-program+command-name) #:args source-or-bytecode-file source-or-bytecode-file))
so that raco decompile --help prints
usage: raco decompile [ <option> ... ] [<source-or-bytecode-file>] ...
<option> is one of
Show this help
Do not treat any remaining argument as a switch (at this level)
Multiple single-letter switches can be combined after
one `-`. For example, `-h-` is the same as `-h --`.
18.2 Accessing raco Commands
|(require raco/all-tools)||package: base|
(require raco/all-tools) (define raco-make-spec (hash-ref (all-tools) "make")) (parameterize ([current-command-line-arguments (vector "file.rkt")]) (dynamic-require (second raco-make-spec) #f))