cli

README

= Argonaut
:source-highlighter: pygments
:pygments-style: monokai
:toc: preamble

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/github/license/Foxcapades/Argonaut[GitHub]
++++
<p align="center" role="Header">
  <img src="https://raw.githubusercontent.com/Foxcapades/Argonaut/master/meta/assets/argonaut.png"/>
</p>
++++

A builder style CLI creation kit.

== Features

* Builder-style construction of singular commands or command trees.
+
.Example
[%collapsible]
====
[source, go]
----
    com := cli.Command().
        WithFlag(cli.Flag().
            WithLongForm("string-slice").
            WithShortForm('s').
            WithBinding(&conf.Strings, true)).
        WithFlag(cli.Flag().
            WithLongForm("int-bool-map").
            WithShortForm('i').
            WithBinding(&conf.IntToBool, true)).
        WithFlag(cli.Flag().
            WithLongForm("string-bytes").
            WithShortForm('b').
            WithBinding(&conf.StringToBytes, true)).
        MustParse(os.Args)
----
====
* Automatic help text generation.
+
.Example
[%collapsible]
====
[source]
----
Usage:
  main [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
----
====
* API that allows for unmarshalling of command line arguments into arbitrary
  types, including custom types using the `argo.Unmarshaler` interface.
+
.Example
[%collapsible]
====
[source, go]
----
type MyType struct {
    Value int
}

func (h *MyType) Unmarshal(value string) (err error) {
    h.Value, err = strconv.ParseInt(value, 16, strconv.IntSize)
    return
}

func main() {
    var val MyType
    var foo string
    var bar []int

    cli.Command().
        WithFlag(cli.ShortFlag('f').WithBinding(&foo, true)).
        WithFlag(cli.LongFlag("bar").WithBinding(&bar, true)).
        WithArgument(cli.Argument().WithBinding(&val).Require()).
        MustParse(os.Args)

    fmt.Println(val)
    fmt.Println(foo)
    fmt.Println(bar)
}
----
====
* Default values for flags and arguments.
+
.Example
[%collapsible]
====
[source, go]
----
var arg int

com := cli.Command().
    WithArgument(cli.Argument().WithBinding(&arg).WithDefault(3)).
    MustParse(os.Args)
----
====

== Supported Types

=== Built-In

By default, Argonaut can parse the following built-in Go types.

==== Basic Types

In following tables, all entries in this table will be referenced by `<basic>`.

.Basic Types
[cols="m,m,m,m,m", width="100%"]
|===
| int    | int8   | int16  | int32  | int64
| uint   | uint8  | uint16 | uint32 | uint64
| string | bool   | (byte) | (rune) |
| time.Duration | | | |
|===

Currently `complex64` and `complex128` are not supported.

Additionally, pointers of arbitrary depth to these types are can also be parsed.

==== Container Types

Like with the basic types, references to `<basic>` here can be pointers of
arbitrary depth to those basic types.

Additionally, `[]byte` can also be referenced by pointers of
arbitrary depth.

.Slices
[cols="m,m,m,m", width="100%"]
|===
| []<basic> | [][]byte | []*[]byte | []interface{}
|===

.Maps
[cols="m,m", width="100%"]
|===
| map[<basic>]<basic> | map[<basic>][]byte
|===

A planned future feature is to allow maps to slices of the basic types.

=== Custom types

Argonaut provides an API which can be used to allow parsing custom types or
controlling the specifics of how a type get unmarshalled.

== Formats

=== Number

By default, numeric argument types can be handled in base 8, 10, and 16 using
the formats or provided types below.

==== Hexadecimal

Argonaut will automatically parse values with the following formats as base16.

These prefixes can be overridden or disabled entirely using the
`argo.UnmarshalProps` type.

----
0xFF
xFF
0XFF
XFF
----

Additionally, the `argo` package contains predefined types to force base16
parsing without requiring a prefix.

.Provided Hex Types
[cols="m,m,m", width="100%"]
|===
| argo.Hex    -> int    | argo.Hex8   -> int8   | argo.Hex16  -> int16
| argo.Hex32  -> int32  | argo.Hex64  -> int64  |
| argo.UHex   -> uint   | argo.UHex8  -> uint8  | argo.UHex16 -> uint16
| argo.UHex32 -> uint32 | argo.UHex64 -> uint64 |
|===


==== Octal

Argonaut will automatically parse values with the following formats as base8.

These prefixes can be overridden or disabled entirely using the
`argo.UnmarshalProps` type.

----
077
0o77
0O77
o77
O77
----

Additionally, the `argo` package contains predefined types to force base8
parsing without requiring a prefix.

.Provided Octal Types
[cols="m,m,m", width="100%"]
|===
| argo.Octal    -> int    | argo.Octal8   -> int8   | argo.Octal16  -> int16
| argo.Octal32  -> int32  | argo.Octal64  -> int64  |
| argo.UOctal   -> uint   | argo.UOctal8  -> uint8  | argo.UOctal16 -> uint16
| argo.UOctal32 -> uint32 | argo.UOctal64 -> uint64 |
|===


=== Boolean

Arguments of type `bool` can be represented by the following formats.

[cols="h,m,m,m,m,m,m", width="100%"]
|===
| true  | true  | t | yes | y | 1 | on
| false | false | f | no  | n | 0 | off
|===

A boolean argument attached to a flag can also be set to `true` simply by the
existence of that flag in the CLI input.

== 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

Index

• func Argument() argo.ArgumentBuilder
• func Branch(name string) argo.CommandBranchBuilder
• func Command() argo.CommandBuilder
• 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

Functions

func Argument

func Argument() argo.ArgumentBuilder

Argument returns a new ArgumentBuilder instance which can be used to construct an Argument instance.

func Branch

func Branch(name string) argo.CommandBranchBuilder

Branch returns a new CommandBranchBuilder instance which can be used to construct an CommandBranch instance.

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:

cli.Command().
    WithFlag(cli.Flag().
        WithLongForm("hex").
        WithShortForm('x').
        WithDescription("Hex value").
        WithBinding(&conf.Hex, true)).
    WithFlag(cli.Flag().
        WithLongForm("uhex").
        WithShortForm('u').
        WithDescription("Unsigned hex value").
        WithBinding(&conf.UHex, true)).
    WithFlag(cli.Flag().
        WithLongForm("octal").
        WithShortForm('o').
        WithDescription("Octal value").
        WithBinding(&conf.Octal, true)).
    MustParse(os.Args)

func Flag

func Flag() argo.FlagBuilder

Flag returns a new FlagBuilder instance which can be used to construct a Flag instance.

func FlagGroup

func FlagGroup(name string) argo.FlagGroupBuilder

FlagGroup returns a new FlagGroupBuilder instance which can be used to construct an FlagGroup instance.

func Leaf

func Leaf(name string) argo.CommandLeafBuilder

Leaf returns a new CommandLeafBuilder instance which can be used to construct an CommandLeaf instance.

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(...)

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(...)

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.