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.


== Supported Types

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 any
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.

----
0o77
o77
0O77
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.

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.