7.8 KiB
wand
Synopsis:
wand [options]... [--] [args string]...
wand <subcommand>
Description:
executes a Go function expression parameterized by the subsequent command line arguments.
It has two modes. When called with arguments, the first argument must be the function expression, and the rest of the arguments are the command line flags and positional arguments. When no arguments are provided, it starts reading from the input, and considers every line as the expected function expression followed by the options and positional arguments. In the latter case, the escaping is mostly identical to that of bash input. It keeps executing the input expressions until the input is closed (Ctrl+D).
Options:
- --cache-dir, -d string: specifies a custom cache dir for wand. Default: ~/.wand.
- --clear-cache, -c bool: clears the cached artifacts resulting from a previous execution before the current execution.
- --import string [*]: lists the packages required for the expression to be executed. It accepts versioned package specifications, or it uses the latest version. When a package spec is prefixed with alias= or .=, it will import the package for the expression with the specified alias or inline.
- --no-cache, -f bool: causes the execution to avoid relying on the cached artifacts resulting from a previous execution.
- --replace-module string [*]: replaces imported Go modules with local or other versions of the given modules. The format of the items is: <module-path>=<replacement-module-path>, like for the go mod edit -replace command.
- --help: Show help.
Hints:
- Options marked with [*] accept any number of instances.
- Bool options can be used with implicit true values.
- The short form of bool options can be combined. The last short form does not need to be a bool option. E.g. -abc=42.
- Option values can be set both via = or just separated by space.
Subcommands:
Show help for each subcommand by calling <command> help or <command> --help.
wand docreflect
Synopsis:
wand docreflect [options]... [--] <packageName string> [gopaths string]...
wand docreflect <subcommand>
Description:
generates documentation from the go docs of a package to be included in the compiled binary and to be accessed by the automatic help and documentation generator.
The packageName parameter specifies the package name for the generated Go code.
The gopath arguments accept any number of package, package level symbol, or struct field paths. It is recommended to use package paths unless there are special circumstances.
Options:
- --main bool: indicates that the docs for the symbols will be lookded up as part of the main package of an executable.
- --help: Show help.
wand man
Synopsis:
wand man [options]... [--] <commandDir string>
wand man <subcommand>
Description:
generates a man page in roff format for a command defined with wand. It relies on the go doc entries extracted by Docreflect.
Options:
- --date-string string: provides the value for the release date field in a man page.
- --version string: provides the value for the release version field in a man page.
- --help: Show help.
wand markdown
Synopsis:
wand markdown [options]... [--] <commandDir string>
wand markdown <subcommand>
Description:
generates a markdown page for a command defined with wand. It relies on the go doc entries extracted by Docreflect.
Options:
- --level int: provides a default title level offset for the titles in a markdown document.
- --help: Show help.
wand exec (default)
Synopsis:
wand exec [options]... [--] [args string]...
wand exec <subcommand>
Description:
executes a Go function expression parameterized by the subsequent command line arguments.
It has two modes. When called with arguments, the first argument must be the function expression, and the rest of the arguments are the command line flags and positional arguments. When no arguments are provided, it starts reading from the input, and considers every line as the expected function expression followed by the options and positional arguments. In the latter case, the escaping is mostly identical to that of bash input. It keeps executing the input expressions until the input is closed (Ctrl+D).
Options:
- --cache-dir, -d string: specifies a custom cache dir for wand. Default: ~/.wand.
- --clear-cache, -c bool: clears the cached artifacts resulting from a previous execution before the current execution.
- --import string [*]: lists the packages required for the expression to be executed. It accepts versioned package specifications, or it uses the latest version. When a package spec is prefixed with alias= or .=, it will import the package for the expression with the specified alias or inline.
- --no-cache, -f bool: causes the execution to avoid relying on the cached artifacts resulting from a previous execution.
- --replace-module string [*]: replaces imported Go modules with local or other versions of the given modules. The format of the items is: <module-path>=<replacement-module-path>, like for the go mod edit -replace command.
- --help: Show help.
wand version
Show version.
Environment variables:
Every command line option's value can also be provided as an environment variable. Environment variable names need to use snake casing like myapp_foo_bar_baz or MYAPP_FOO_BAR_BAZ, or other casing that doesn't include the '-' dash character, and they need to be prefixed with the name of the application, as in the base name of the command.
When both the environment variable and the command line option is defined, the command line option overrides the environment variable. Multiple values for the same environment variable can be defined by concatenating the values with the ':' separator character. When overriding multiple values with command line options, all the environment values of the same field are dropped.
Example environment variable:
WAND_MAIN=true
Configuration:
Every command line option's value can also be provided as an entry in a configuration file.
Configuration file entries can use keys with different casings, e.g. snake case foo_bar_baz, or kebab case foo-bar-baz. The keys of the entries can use a limited set of characters: [a-zA-Z0-9_-], and the first character needs to be one of [a-zA-Z_]. Entry values can consist of any characters, except for newline, control characters, " (quote) and \ (backslash), or the values can be quoted, in which case they can consist of any characters, spanning multiple lines, and only the " (quote) and \ (backslash) characters need to be escaped by the \ (backslash) character.
Configuration files allow multiple entries with the same key, when if the associated command line option also allows multiple instances (marked with [*]). When an entry is defined multiple configuration files, the effective value is overridden in the order of the definition of the possible config files (see the listing order below). To discard values defined in the overridden config files without defining new ones, we can set entries with only the key, omitting the = key/value separator. Entries in the config files are overridden by the environment variables, when defined, and by the command line options when defined.
Config files marked as optional don't need to be present in the file system, but if they exist, then they must contain valid configuration syntax which is wand's flavor of .ini files (https://code.squareroundforest.org/arpio/wand/src/branch/main/ini.treerack).
Configuration files:
- /etc/wand/config (optional)
- /Users/arpio/.wand/config (optional)
- /Users/arpio/.config/wand/config (optional)
Example configuration entry:
# Default value for --main:
main = true
Example for discarding an inherited entry:
# Discarding an inherited entry:
main