arpio/wand
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

type and grammar fixes

Browse Source
This commit is contained in:
Arpad Ryszka 2026-01-07 22:21:54 +01:00
parent 07f334cb9e
commit d3c148363d
5 changed files with 41 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
cmd/wand/readme.md
View File

@ -12,9 +12,9 @@ wand <subcommand>
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 the command line flags and positional arguments. When no arguments are provided, it starts
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 the bash input. It keeps
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:
@ -24,10 +24,10 @@ executing the input expressions until the input is closed (Ctrl+D).
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 for the expression with the specified alias or inline.
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.
- --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.
@ -55,13 +55,13 @@ wand docreflect <subcommand>
#### Description:
generates documentation from the go docs of a package to be included in the compiled binary and accessed by the
automatic help and documentation generator.
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 special circumstances.
recommended to use package paths unless there are special circumstances.
#### Options:
@ -120,9 +120,9 @@ wand exec <subcommand>
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 the command line flags and positional arguments. When no arguments are provided, it starts
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 the bash input. It keeps
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:
@ -132,10 +132,10 @@ executing the input expressions until the input is closed (Ctrl+D).
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 for the expression with the specified alias or inline.
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.
- --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.

8
docreflect.gen.go
View File

@ -8,14 +8,14 @@ import "code.squareroundforest.org/arpio/docreflect"
func init() {
docreflect.Register("code.squareroundforest.org/arpio/wand/tools", "Package tools provides tools to work with the wand library. The functions in this package serve primarily as\nthe implementation of the wand executable command.\n")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Docreflect", "Docreflect generates documentation from the go docs of a package to be included in the compiled binary and\naccessed by the automatic help and documentation generator.\n\nThe packageName parameter specifies the package name for the generated Go code.\n\nThe gopath arguments accept any number of package, package level symbol, or struct field paths. It is\nrecommended to use package paths unless special circumstances.\n\nfunc(out, packageName, gopaths)")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Exec", "Exec executes a Go function expression parameterized by the subsequent command line arguments.\n\nIt has two modes. When called with arguments, the first argument must be the function expression, and the\nrest of the arguments the command line flags and positional arguments. When no arguments are provided, it\nstarts reading from the input, and considers every line as the expected function expression followed by the\noptions and positional arguments. In the latter case, the escaping is mostly identical to that of the bash\ninput. It keeps executing the input expressions until the input is closed (Ctrl+D).\n\nfunc(o, stdin, stdout, args)")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Docreflect", "Docreflect generates documentation from the go docs of a package to be included in the compiled binary and\nto be accessed by the automatic help and documentation generator.\n\nThe packageName parameter specifies the package name for the generated Go code.\n\nThe gopath arguments accept any number of package, package level symbol, or struct field paths. It is\nrecommended to use package paths unless there are special circumstances.\n\nfunc(out, packageName, gopaths)")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Exec", "Exec executes a Go function expression parameterized by the subsequent command line arguments.\n\nIt has two modes. When called with arguments, the first argument must be the function expression, and the\nrest of the arguments are the command line flags and positional arguments. When no arguments are provided, it\nstarts reading from the input, and considers every line as the expected function expression followed by the\noptions and positional arguments. In the latter case, the escaping is mostly identical to that of bash input.\nIt keeps executing the input expressions until the input is closed (Ctrl+D).\n\nfunc(o, stdin, stdout, args)")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions", "ExecOptions represents input options for executing a function from the command line using the wand mechanism.\n")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.CacheDir", "CacheDir specifies a custom cache dir for wand. Default: ~/.wand.\n")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.ClearCache", "ClearCache clears the cached artifacts resulting from a previous execution before the current execution.\n")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.Import", "Import lists the packages required for the expression to be executed. It accepts versioned package\nspecifications, or it uses the latest version. When a package spec is prefixed with alias= or .=, it will\nimport the for the expression with the specified alias or inline.\n")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.Import", "Import lists the packages required for the expression to be executed. It accepts versioned package\nspecifications, or it uses the latest version. When a package spec is prefixed with alias= or .=, it will\nimport the package for the expression with the specified alias or inline.\n")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.NoCache", "NoCache causes the execution to avoid relying on the cached artifacts resulting from a previous\nexecution.\n")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.ReplaceModule", "ReplaceModule replaces imported go modules with local or other versions of the given modules. The format\nof the items is: <module-path>=<replacement-module-path>, like for the go mod edit -replace command.\n")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.ReplaceModule", "ReplaceModule replaces imported Go modules with local or other versions of the given modules. The format\nof the items is: <module-path>=<replacement-module-path>, like for the go mod edit -replace command.\n")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Man", "Man generates a man page in roff format for a command defined with wand. It relies on the go doc entries\nextracted by Docreflect.\n\nfunc(out, o, commandDir)")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions", "ManOptions represents input options for generating man pages for a command created with wand.\n")
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions.DateString", "DateString provides the value for the release date field in a man page.\n")

18
lib.go
View File

@ -46,7 +46,7 @@ type Cmd struct {
// Scalar arguments are considered as positional arguments of the command. Variadic arguments are supported.
//
// The fields of struct arguments define which command line options are supported by the command. Input
// for the options is accepted both from command line flags or environment variables, and, if defined, from
// for the options is accepted from both command line flags or environment variables, and, if defined, from
// configuration. Values defined in the environment override the configuration, and values passed in as command
// line flags override the environment (not propagated automatically to the environment of any child processes).
// Zero or more struct parameters are accepted, e.g. func(g Globals, o Options).
@ -55,26 +55,26 @@ type Cmd struct {
// kebab case with double leading dashes, unless a short form is defined. Option values are accepted both
// with = or just space separated following the flag. In case of bool options, omitting the value is considered
// as true value. Since the struct path and field names are collapsed into their flat kebab case representation,
// this results in ambiguity, e.g. Foo.BarBaz and Foo.Bar.Baz. In such cases, the types of the ambigous fields
// this results in ambiguity, e.g. Foo.BarBaz and Foo.Bar.Baz. In such cases, the types of the ambiguous fields
// must be compatible, and each such field will be bound to the same input value. Slice fields are supported,
// they accept zero or more options of the same name, every option value is bound as an item of the slice, e.g.
// --foo one --foo two --foo three.
//
// The names of the environment variables are inferred from the struct path and field names, are prefixed with
// the name of the execting binary, and are expected in lower or upper snake case. E.g. for a field InputValue:
// the name of the executing binary, and are expected in lower or upper snake case. E.g. for a field InputValue:
// FOO_BAR_INPUT_VALUE=42 /usr/bin/foo-bar. The same ambiguity rules apply as in case of the command line
// flags. Slice fields are supported, the values slice fields can be separated by the : character, like in case
// of the PATH environment variable. When necessary, the : character can be escaped as \:.
//
// For the implementation function, zero or one io.Reader and zero or one io.Writer parameter is accepted. When
// present, io.Reader is poplated by os.Stdin and io.Writer is populated by os.Stdout.
// present, io.Reader is populated by os.Stdin and io.Writer is populated by os.Stdout.
//
// The implementation function can have zero or more output parameters. If the last output parameter is of type
// error, and the returned value is not nil, the rest of the output parameters will be ignored and the error
// will be printed onto os.Stderr, and the command will exit with a non zero code. In case of no error, every
// return value will be printed on its own line, and if a return value is a slice, then every item will also be
// printed on its own line. If a return value is an io.Reader, that reader will be copied onto os.Stdout. If a
// values is a primitive value, it will be printed onto os.Stdout using the stdlib fmt package. Complex values
// value is a primitive value, it will be printed onto os.Stdout using the stdlib fmt package. Complex values
// will be printed to os.Stdout using code.squareroundforest.org/arpio/notation.
//
// A command can have zero or more subcommands. When executing a subcommand, the subcommands path must be at the
@ -83,7 +83,7 @@ type Cmd struct {
//
// If a struct field doesn't override it, a --help command line flag will be automatically injected, and calling
// it will display an automatically generated help. Similarly, a help subcommand is also automatically injected
// under every command in the command tree, if a subcommand does not have already taken the name help. The help
// under every command in the command tree, if a subcommand has not already taken the name help. The help
// subcommand has the same effect as the --help flag. When the user provides invalid input, the command exits
// with a non zero code, and displays a short suggestion to the user on how to display this help.
//
@ -94,7 +94,7 @@ type Cmd struct {
// and the description of the fields that serve as the command line options. It is also possible to generate man
// pages or markdown from the godoc documentation. For more details, see the documentation of the wand tool.
//
// When executing a command, there is two distinct stages of validation. The first one validates that the
// When executing a command, there are two distinct stages of validation. The first one validates that the
// command definition itself is valid, while the second stage validates the user input against the command
// definition. The validation of the command definition happens without considering the user input, and errors
// are prefixed with "program error:". This way we can know during development time if the command definition is
@ -125,7 +125,7 @@ func Args(cmd Cmd, min, max int) Cmd {
}
// ShortForm can be used to define short-form flags for command line options. E.g:
// ShortForm(cmd, "f", "foo", "b", "bar", "z", "baz"). In which case the resulting command be called as:
// ShortForm(cmd, "f", "foo", "b", "bar", "z", "baz"). In which case the resulting command can be called as:
// my-command -f one -b two -z three. If say the Foo and Bar fields are of type boolean, then the flags can be
// grouped as:
// my-command -fbz three. The defined short forms apply to the entire command tree represented by the cmd
@ -226,7 +226,7 @@ func MergeConfig(conf ...Config) Config {
}
// OptionalConfig marks a configuration file definition as optional. Without it, the configuration is expected
// to be present during executing the command.
// to be present during the execution of the command.
func OptionalConfig(conf Config) Config {
conf.optional = true
for i := range conf.merge {

20
readme.md
View File

@ -2,7 +2,7 @@
Wand is a library to wrap Go functions as executable binaries. It supports:
- hierarch of subcommands
- hierarchy of subcommands
- binding of command line options
- binding of environment variables
- binding of configuration entries
@ -31,9 +31,9 @@ func main() {
## wand tool
The wand tool helps with following tasks:
The wand tool helps with the following tasks:
- generating code from the go doc of the library that is converted by the wand library into an executable binary
- generating code from the go doc of the library that is converted into an executable binary by wand
- generating man (roff) or markdown documentation
- executing arbitrary Go functions in the command line addressed by their go path
@ -60,11 +60,9 @@ prefix=~/.local make install
(See the recommended way below on how to use the locked version in the build tooling of a project.)
tool usage: docreflect for lib and man for cmd
### wand tool usage
Let's consider a project hierarchy such as in the root we have a library (mylib), and in the ./cmd directory we
Let's consider a project hierarchy where in the root we have a library (mylib), and in the ./cmd directory we
have a main package, wrapping one or more functions of that library with wand as an executable binary:
```
@ -72,7 +70,7 @@ have a main package, wrapping one or more functions of that library with wand as
./lib.go
```
Generating the compiled docs from go doc of a library:
Generating the compiled docs from the go doc of a library:
```
wand docreflect mylib .
@ -81,7 +79,7 @@ wand docreflect mylib .
Generating a man page for the command:
```
wand manpages --date-string $(2026-01-07) --version v1.0.0 ./cmd
wand manpages --date-string 2026-01-07 --version v1.0.0 ./cmd
```
### wand tool bonus usage
@ -108,9 +106,9 @@ wand help
### wand tool usage with go.mod version
When generating the docs for a shared project, we may want to ensure that always the same version of wand is
used for both docreflect and manpages. Best is to use the version that is defined in go.mod. This can be
achieved using trivial scripts, the example below showing docreflect:
When generating the docs for a shared project, we may want to ensure that the same version of wand is used for
both docreflect and manpages in every environment. It is best to use the version that is defined in go.mod. This
can be achieved using some trivial scripts. The example below shows docreflect:
```
package main

14
tools/lib.go
View File

@ -41,21 +41,21 @@ type ExecOptions struct {
// Import 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 for the expression with the specified alias or inline.
// import the package for the expression with the specified alias or inline.
Import []string
// ReplaceModule replaces imported go modules with local or other versions of the given modules. The format
// ReplaceModule 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.
ReplaceModule []string
}
// Docreflect generates documentation from the go docs of a package to be included in the compiled binary and
// accessed by the automatic help and documentation generator.
// 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 special circumstances.
// recommended to use package paths unless there are special circumstances.
func Docreflect(out io.Writer, packageName string, gopaths ...string) error {
return generate.GenerateRegistry(out, packageName, gopaths...)
}
@ -86,10 +86,10 @@ func Markdown(out io.Writer, o MarkdownOptions, commandDir string) error {
// Exec 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 the command line flags and positional arguments. When no arguments are provided, it
// 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 the bash
// input. It keeps executing the input expressions until the input is closed (Ctrl+D).
// 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).
func Exec(o ExecOptions, stdin io.Reader, stdout io.Writer, args ...string) error {
return execInput(o, stdin, stdout, os.Stderr, args...)
}