cli

Documentation

Overview

cli is a library to handle different data types directly from cli arguments.

Data Types: Bool, String, Bytes, Int, Float
	    Date, Duration, Link (URI), IP, CIDR, Bind

Two types of options can be used. Short with a default prefix of - and long options with --. Short options of the type Bool can be combined as -vxi (-v -x -i). Short options are single value chars and must be part of this regexp token [a-zA-Z0-9].

Date input uses the fomat "2006-01-02T15:04:05" by default. You can modify this via TimeFormat global variable.

Index

• Variables
• type Data
  • func (d *Data) Name() string
  • func (d *Data) Value() any
• type Kind
• type Options
  • func New() *Options
  • func (o *Options) Add(data Kind, short byte, long string) *option
  • func (o *Options) Args() error
  • func (o *Options) Bind(name string) *bind.Target
  • func (o *Options) Binds(name string) []*bind.Target
  • func (o *Options) Bool(name string) bool
  • func (o *Options) Bytes(name string) []byte
  • func (o *Options) BytesN(name string) [][]byte
  • func (o *Options) CIDR(name string) netip.Prefix
  • func (o *Options) CIDRs(name string) []netip.Prefix
  • func (o *Options) Date(name string) time.Time
  • func (o *Options) Dates(name string) []time.Time
  • func (o *Options) Debug(logger *log.Logger)
  • func (o *Options) Duration(name string) time.Duration
  • func (o *Options) Durations(name string) []time.Duration
  • func (o *Options) Filtered() ([]string, []string)
  • func (o *Options) Float(name string) float64
  • func (o *Options) Floats(name string) []float64
  • func (o *Options) Get(name string) any
  • func (o *Options) HasValue(name string) bool
  • func (o *Options) IP(name string) netip.Addr
  • func (o *Options) IPs(name string) []netip.Addr
  • func (o *Options) Ignored() []string
  • func (o *Options) Int(name string) int64
  • func (o *Options) Ints(name string) []int64
  • func (o *Options) Link(name string) *url.URL
  • func (o *Options) Links(name string) []*url.URL
  • func (o *Options) Parse(args []string) error
  • func (o *Options) Parsed() bool
  • func (o *Options) Size(name string) int
  • func (o *Options) String(name string) string
  • func (o *Options) Strings(name string) []string

Examples

• Options.Args
• Options.Float
• Options.Parse
• Options.Size
• Options.Strings

Variables

var (
	PrefixShort string = "-"
	PrefixLong  string = "--"
	TimeFormat  string = "2006-01-02T15:04:05"
)

Types

type Data

type Data struct {
	Pass any
	// contains filtered or unexported fields
}

Data contains Pass as any to pass your needed data to passed Direct() functions.

func (*Data) Name

func (d *Data) Name() string

Name is used in the Direct() context. It returns the option name (usually the long value).

func (*Data) Value

func (d *Data) Value() any

Value is used in the Direct() context. It returns the value of that option after Parse().

type Kind

type Kind uint8

Kind represents all data types that option can be converted to.

const (
	Bool Kind = iota
	String
	Bytes
	// Int = int64
	Int
	// Float = float64
	Float
	Date
	Duration
	Link
	IP
	CIDR
	Bind
)

type Options

type Options struct {
	// contains filtered or unexported fields
}

Options holds all values around the used/given options.

func New

func New() *Options

New creates a map and returns an *Options pointer.

func (*Options) Add

func (o *Options) Add(data Kind, short byte, long string) *option

Add enables the possibility to parse for these short or long options. If the same name is used more than once, it will be overwritten by the last definition.

func (*Options) Args

func (o *Options) Args() error

Args is a shortcut for Parse(os.Args[1:])

Example

package main

import (
	"fmt"

	"catinello.eu/cli"
)

func main() {
	o := cli.New()
	o.Add(cli.Bool, 0, "verbose")
	o.Add(cli.Bool, 0, "help")
	o.Add(cli.Bool, 0, "license")

	err := o.Args()
	if err != nil {
		panic(err)
	}

	fmt.Println(len(o.Ignored()))
}

Output:

3

func (*Options) Bind

func (o *Options) Bind(name string) *bind.Target

Bind returns the single value for the given name as Bind.

func (*Options) Binds

func (o *Options) Binds(name string) []*bind.Target

Binds returns all values for the given name or an empty slice.

func (*Options) Bool

func (o *Options) Bool(name string) bool

Bool returns the value for the given name as boolean or false if not found.

func (*Options) Bytes

func (o *Options) Bytes(name string) []byte

Bytes returns the single value for the given name as []byte.

func (*Options) BytesN

func (o *Options) BytesN(name string) [][]byte

BytesN returns all values for the given name or an emtpy slice.

func (*Options) CIDR

func (o *Options) CIDR(name string) netip.Prefix

CIDR returns the single value for the given IP prefix.

func (*Options) CIDRs

func (o *Options) CIDRs(name string) []netip.Prefix

CIDRs returns all values for the given IP prefix or an empty slice.

func (*Options) Date

func (o *Options) Date(name string) time.Time

Date returns the single value for the given name as time.Time.

func (*Options) Dates

func (o *Options) Dates(name string) []time.Time

Dates returns all values for the given name or an empty slice.

func (*Options) Debug

func (o *Options) Debug(logger *log.Logger)

Debug takes a logger to print debug messages to.

func (*Options) Duration

func (o *Options) Duration(name string) time.Duration

Duration returns the single value for the given name as time.Duration.

func (*Options) Durations

func (o *Options) Durations(name string) []time.Duration

Durations returns all values for the given name or an empty slice.

func (*Options) Filtered

func (o *Options) Filtered() ([]string, []string)

Filtered returns a list of filtered (short- and long-options) and a list of the removed options from the Ignored() subset of unused parameters/options.

func (*Options) Float

func (o *Options) Float(name string) float64

Float returns the single value for the given name as float64.

Example

package main

import (
	"fmt"

	"catinello.eu/cli"
)

var opts *cli.Options

func main() {
	fmt.Println(opts.Float("π"))
}

Output:

3.14159

func (*Options) Floats

func (o *Options) Floats(name string) []float64

Floats returns all values for the given name or an emtpy slice.

func (*Options) Get

func (o *Options) Get(name string) any

Get returns the value for the given name as any type or returns nil if not found.

func (*Options) HasValue

func (o *Options) HasValue(name string) bool

HasValue returns true if the options called by name was set at least once.

func (*Options) IP

func (o *Options) IP(name string) netip.Addr

IP returns the single value for the given name as IP.

func (*Options) IPs

func (o *Options) IPs(name string) []netip.Addr

IPs returns all values for the given name or an empty slice.

func (*Options) Ignored

func (o *Options) Ignored() []string

Ignored returns a list of the unused parameters/options.

func (*Options) Int

func (o *Options) Int(name string) int64

Int returns the single value for the given name as int64.

func (*Options) Ints

func (o *Options) Ints(name string) []int64

Ints returns all values for the given name or an empty slice.

func (*Options) Link

func (o *Options) Link(name string) *url.URL

Link returns the single value for the given name as url.URL.

func (*Options) Links

func (o *Options) Links(name string) []*url.URL

Links returns all values for the given name or an empty slice.

func (*Options) Parse

func (o *Options) Parse(args []string) error

Parse all strings from given args.

Example

package main

import (
	"fmt"

	"catinello.eu/cli"
)

var opts *cli.Options

func main() {
	opts = cli.New()

	opts.Add(cli.Bool, 0, "verbose")
	opts.Add(cli.Bool, 0, "help")
	opts.Add(cli.Bool, 0, "license")
	opts.Add(cli.String, 'h', "hosts").Multi()
	opts.Add(cli.Int, 'c', "connections")
	opts.Add(cli.Float, 'p', "π")

	err := opts.Parse([]string{"--verbose", "-h", "example.org", "--hosts", "example.net", "-c", "3", "--π", "3.14159"})
	if err != nil {
		panic(err)
	}

	fmt.Println(opts.Bool("verbose"))
}

Output:

true

func (*Options) Parsed

func (o *Options) Parsed() bool

Parsed returns true if parsing was successful once.

func (*Options) Size

func (o *Options) Size(name string) int

Size returns the amount of values that the given name is carrying.

Example

package main

import (
	"fmt"

	"catinello.eu/cli"
)

var opts *cli.Options

func main() {
	fmt.Println(opts.Size("hosts"))
}

Output:

2

func (*Options) String

func (o *Options) String(name string) string

String returns the single value for the given name as string.

func (*Options) Strings

func (o *Options) Strings(name string) []string

Strings returns all values for the given name or an empty slice.

Example

package main

import (
	"fmt"

	"catinello.eu/cli"
)

var opts *cli.Options

func main() {
	hosts := opts.Strings("hosts")
	fmt.Println(hosts)
}

Output:

[example.org example.net]