README
¶
= Argonaut
:repo: https://github.com/Foxcapades/Argonaut
++++
<p align="center" role="Header">
<img src="https://raw.githubusercontent.com/Foxcapades/Argonaut/master/meta/assets/argonaut.png"/>
</p>
++++
Argonaut is a builder-style CLI creation kit packed with features.
image:https://img.shields.io/github/license/Foxcapades/Argonaut[GitHub]
image:https://img.shields.io/github/v/tag/Foxcapades/Argonaut?label=version[GitHub tag (latest SemVer), link=https://github.com/Foxcapades/Argonaut/releases/latest]
image:https://goreportcard.com/badge/github.com/Foxcapades/Argonaut[link=https://goreportcard.com/report/github.com/Foxcapades/Argonaut]
image:https://img.shields.io/badge/go-docs-blue[Static Badge,link=https://pkg.go.dev/github.com/Foxcapades/Argonaut]
image:https://img.shields.io/badge/wiki-docs-purple[Wiki,link=https://github.com/Foxcapades/Argonaut/wiki]
[source, go]
----
import (
cli "github.com/Foxcapades/Argonaut"
)
----
== Features
* Builder-style API.
+
[source, go]
----
cli.Flag().
WithArgument(cli.Argument().
WithName("file").
Require())
----
* Build singular command applications or command trees.
+
[source, go]
----
cli.Command()
// OR
cli.Tree()
----
* Overridable automatic help text generation.
+
[source, console]
----
Usage:
my-app [options] <command>
This is a simple command tree example.
Flags
-h | --help
Prints this help text.
Commands
fizz Aliases: fi
This is the description for the fizz branch.
foo Aliases: fo
this is the description for the foo branch
----
* Bind command line arguments to variables of arbitrary types.
+
[source, go]
----
foo := uint8(0)
cli.Argument().WithBinding(&foo)
----
* Multi-use flags.
+
[source, console]
----
$ foo --bar --bar --bar
bar = 3
----
* Stackable short flags.
+
[source, console]
----
$ app -abc=4
a = true
b = true
c = 4
----
* Callback hooks.
+
[source, go]
----
cli.Flag().WithCallback(func(Flag){})
cli.Command().WithCallback(func(Command){})
cli.Tree().WithCallback(func(Tree){})
cli.Branch().WithCallback(func(Branch){})
cli.Leaf().WithCallback(func(Leaf){})
----
* Customizable or overridable unmarshalling of almost any type.
+
[source, go]
----
var options argo.UnmarshalProps
...
cli.Argument().WithUnmarshaler(argo.NewMagicUnmarshaler(options))
----
* Default values for flags and arguments.
+
[source, go]
----
var foo int32
cli.Argument().WithBinding(&foo).WithDefault(int32(666))
----
* Input validation hooks.
+
[source, go]
----
var bind uint8
cli.Argument().
WithBinding(&bind)
WithValidator(func(string) {}).
WithValidator(func(string, int8) {})
----
* Automatic capturing of "passthrough" flags and arguments.
+
[source, console]
----
$ foo bar --fizz=buzz -- apple banana canteloupe
Passthroughs: apple, banana, canteloupe
----
* And more!
== Examples
. https://github.com/Foxcapades/Argonaut/tree/master/examples/complex-type[Complex Types]
. https://github.com/Foxcapades/Argonaut/tree/master/examples/number-extras[Number Format Extras]
. https://github.com/Foxcapades/Argonaut/tree/master/examples/simple-tree[Simple Tree]
Documentation
¶
Overview ¶
Package cli provides a convenience methods for constructing command line interfaces using the argo package.
Commands may be either singular commands or command trees. A singular command has no subcommand and may take any number of flags and/or arguments. A command tree is a root command that may have an arbitrary depth of branching subcommands which each may take their own flags, with the leaf nodes of the tree also accepting arguments.
An example single command:
tar -xf foo.tgz
Here the single command `tar` accepts the flags `-x` and -f`, with the `-f` flag taking the argument `foo.tgz`.
An example command tree:
docker compose -f my-docker-compose.yml up my-service
Here the command tree is constructed of 3 levels, the root of the tree (docker), the intermediary branch (compose) and the leaf command (up). The branch is taking a flag (-f) which is itself taking an argument (my-docker-compose.yml). The leaf command (up) is accepting an optional argument (my-service).
Command construction starts with either the `cli.Command` function or the `cli.Tree` function.
Index ¶
- func Argument() argo.ArgumentBuilder
- func Branch(name string) argo.CommandBranchBuilder
- func ComboFlag(short byte, long string) argo.FlagBuilder
- func Command() argo.CommandBuilder
- func CommandGroup(name string) argo.CommandGroupBuilder
- func Flag() argo.FlagBuilder
- func FlagGroup(name string) argo.FlagGroupBuilder
- func Leaf(name string) argo.CommandLeafBuilder
- func LongFlag(name string) argo.FlagBuilder
- func ShortFlag(f byte) argo.FlagBuilder
- func Tree() argo.CommandTreeBuilder
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Argument ¶
func Argument() argo.ArgumentBuilder
Argument returns a new ArgumentBuilder instance which can be used to construct an Argument instance.
Example ¶
package main
import (
"fmt"
cli "github.com/Foxcapades/Argonaut"
)
func main() {
var file string
var count uint
cli.Command().
WithArgument(cli.Argument().
WithName("file").
WithBinding(&file)).
WithArgument(cli.Argument().
WithName("count").
WithBinding(&count)).
MustParse([]string{"command", "foo.txt", "36"})
fmt.Println(file, count)
}
Output: foo.txt 36
func Branch ¶
func Branch(name string) argo.CommandBranchBuilder
Branch returns a new CommandBranchBuilder instance which can be used to construct an CommandBranch instance.
Example ¶
package main
import (
"fmt"
cli "github.com/Foxcapades/Argonaut"
"github.com/Foxcapades/Argonaut/pkg/argo"
)
func main() {
cli.Tree().
WithBranch(cli.Branch("foo").
WithCallback(func(branch argo.CommandBranch) {
fmt.Print("hello from ")
}).
WithLeaf(cli.Leaf("bar").
WithCallback(func(leaf argo.CommandLeaf) {
fmt.Println("a branch!")
}))).
MustParse([]string{"command", "foo", "bar"})
}
Output: hello from a branch!
func ComboFlag ¶ added in v1.2.1
func ComboFlag(short byte, long string) argo.FlagBuilder
ComboFlag returns a new FlagBuilder instance with the short and long forms already set to the given values.
This function is a shortcut for:
cli.Flag().WithShortForm(...).WithLongForm(...)
func Command ¶
func Command() argo.CommandBuilder
Command returns a new CommandBuilder instance which can be used to construct a Command instance.
This function and Tree are the two entrypoints into the Argonaut library. This function returns a value that may be used in a call chain to construct a full-featured command line interface.
Example ¶
package main
import (
"fmt"
cli "github.com/Foxcapades/Argonaut"
"github.com/Foxcapades/Argonaut/pkg/argo"
)
func main() {
cli.Command().
WithCallback(func(command argo.Command) {
fmt.Println(command.UnmappedInputs())
}).
MustParse([]string{"command", "foo", "bar", "fizz", "buzz"})
}
Output: [foo bar fizz buzz]
Example (Complex) ¶
package main
import (
"fmt"
cli "github.com/Foxcapades/Argonaut"
)
func main() {
var config = struct {
NilDelim bool
}{}
cli.Command().
WithFlagGroup(cli.FlagGroup("Output Control").
WithFlag(cli.Flag().
WithShortForm('0').
WithLongForm("nil-delim").
WithDescription("End output with a null byte instead of a newline.").
WithBinding(&config.NilDelim, false))).
MustParse([]string{"command", "-0"})
fmt.Println(config.NilDelim)
}
Output: true
func CommandGroup ¶ added in v1.1.0
func CommandGroup(name string) argo.CommandGroupBuilder
CommandGroup returns a new CommandGroupBuilder in stance which can be used to construct a CommandGroup instance.
Example ¶
package main
import (
"fmt"
cli "github.com/Foxcapades/Argonaut"
)
func main() {
com := cli.Tree().
WithCommandGroup(cli.CommandGroup("my commands").
WithDescription("a group of commands for me").
WithLeaf(cli.Leaf("foo")).
WithLeaf(cli.Leaf("bar"))).
MustParse([]string{"command", "foo"})
fmt.Println(com.SelectedCommand().Name())
}
Output: foo
func Flag ¶
func Flag() argo.FlagBuilder
Flag returns a new FlagBuilder instance which can be used to construct a Flag instance.
Example ¶
package main
import (
"fmt"
cli "github.com/Foxcapades/Argonaut"
"github.com/Foxcapades/Argonaut/pkg/argo"
)
func main() {
cli.Command().
WithFlag(cli.Flag().
WithShortForm('s').
WithLongForm("selection").
WithCallback(func(flag argo.Flag) {
fmt.Println(flag.HitCount())
})).
MustParse([]string{"command", "-ssss", "--selection", "--selection"})
}
Output: 6
func FlagGroup ¶
func FlagGroup(name string) argo.FlagGroupBuilder
FlagGroup returns a new FlagGroupBuilder instance which can be used to construct an FlagGroup instance.
Example ¶
package main
import (
"fmt"
cli "github.com/Foxcapades/Argonaut"
"github.com/Foxcapades/Argonaut/pkg/argo"
)
func main() {
cli.Command().
WithFlagGroup(cli.FlagGroup("my flags").
WithFlag(cli.ShortFlag('c').
WithCallback(func(flag argo.Flag) { fmt.Print("hello ") }))).
WithFlagGroup(cli.FlagGroup("your flags").
WithFlag(cli.LongFlag("clutch").
WithCallback(func(flag argo.Flag) { fmt.Println("world") }))).
MustParse([]string{"command", "-c", "--clutch"})
}
Output: hello world
func Leaf ¶
func Leaf(name string) argo.CommandLeafBuilder
Leaf returns a new CommandLeafBuilder instance which can be used to construct an CommandLeaf instance.
Example ¶
package main
import (
"fmt"
cli "github.com/Foxcapades/Argonaut"
)
func main() {
var zone string
cli.Tree().
WithLeaf(cli.Leaf("time").
WithArgument(cli.Argument().
WithName("zone").
WithBinding(&zone))).
MustParse([]string{"command", "time", "UTC"})
fmt.Println(zone)
}
Output: UTC
func LongFlag ¶
func LongFlag(name string) argo.FlagBuilder
LongFlag returns a new FlagBuilder instance with the long form already set to the given value.
This function is a shortcut for:
cli.Flag().WithLongForm(...)
Example ¶
package main
import (
"fmt"
cli "github.com/Foxcapades/Argonaut"
"github.com/Foxcapades/Argonaut/pkg/argo"
)
func main() {
cli.Command().
WithFlag(cli.LongFlag("hello").
WithCallback(func(flag argo.Flag) {
fmt.Println(flag.WasHit())
})).
MustParse([]string{"command", "--hello"})
}
Output: true
func ShortFlag ¶
func ShortFlag(f byte) argo.FlagBuilder
ShortFlag returns a new FlagBuilder instance with the short form already set to the given value.
This function is a shortcut for:
cli.Flag().WithShortForm(...)
Example ¶
package main
import (
"fmt"
cli "github.com/Foxcapades/Argonaut"
"github.com/Foxcapades/Argonaut/pkg/argo"
)
func main() {
cli.Command().
WithFlag(cli.ShortFlag('a').
WithCallback(func(flag argo.Flag) { fmt.Println(flag.HitCount()) })).
MustParse([]string{"command", "-aaa", "-a", "-a"})
}
Output: 5
func Tree ¶
func Tree() argo.CommandTreeBuilder
Tree returns a new CommandTreeBuilder instance which can be used to construct a CommandTree instance.
A command tree is a tree of nested subcommands of arbitrary depth. The tree consists of branch and leaf nodes, with the leaf nodes being the selectable final commands.
Example ¶
package main
import (
"fmt"
cli "github.com/Foxcapades/Argonaut"
"github.com/Foxcapades/Argonaut/pkg/argo"
)
func main() {
cli.Tree().
WithLeaf(cli.Leaf("foo").
WithCallback(func(leaf argo.CommandLeaf) {
fmt.Println(leaf.PassthroughInputs())
})).
MustParse([]string{"command", "foo", "--", "bar"})
}
Output: [bar]
Types ¶
This section is empty.
Source Files
Directories