olive

package module
v0.0.0-...-c9916e4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 23, 2021 License: MIT Imports: 7 Imported by: 0

README

Olive

Go Report Card Coverage Status Build Status

Olive is a delightful, little argument parsing library for Golang designed to replace the builtin flag package. Olive is lightweight, easy to use, and intuitive while still being powerful enough and customizable enough to suit your needs.

Installation

To get started using Olive, enter the following command into your terminal of choice.

go get -u github.com/ComedicChimera/olive

Note that Olive uses Go modules -- you will need to make sure you are on a version of Go that supports modules.

Quickstart

Once you have installed Olive, using it is easy. Here is a quick sample of parsing command line arguments for a simple application.

import (
    "fmt"
    "os"
    "errors"

    "github.com/ComedicChimera/olive"
)

func main() {
    cli := olive.NewCLI("sample", "A sample command line utility for Olive")

    cli.AddFlag("show-expr", "se", help: "Show the expression computed")

    cli.AddIntArg("value1", "v1", help: "The first value", required: true)
    
    argv2 := cli.AddIntArg("value2", "v2", help: "The second value", required: true)
    argv2.SetValidator(func(v int) error {
        if v != 0 {
            return errors.New("cannot divide by zero")
        }

        return nil
    })

    result, err := olive.ParseArgs(cli, os.Args)
    if err != nil {
        fmt.Println(err)
        return
    }

    v1 := result.Arguments["value1"].(int)
    v2 := result.Arguments["value2"].(int)

    if result.GetFlag("show-expr") {
        fmt.Printf("%d / %d ", v1, v2)
    }

    fmt.Println("=", v1 / v2)
}

A sample call of this program would look like:

> sample -v1=10 -v2=2 --show-expr
10 / 2 = 5

Documentation

For more specific information on how to use Olive, check out the wiki.

Contributing

If you would like to contribute to this repository, there are a number of things that could be worked on/need doing. Just fork this repo and make a pull request once you have finished modifying it.

  • Adding more tests
  • Adding additional argument types
  • Adding constraints and/or validators to primary arguments
  • Improving/adding to documentation

If you encounter any bugs or think any additional features that this repo should have, but don't have the time to implement them yourself, feel free to open an issue.

Note that Olive is not really my primary project atm (I basically made it to fill a need I had in another, more serious project) so there may be a bit of a delay in feature releases.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ArgParseResult 

type ArgParseResult struct {
	Arguments map[string]interface{}
	// contains filtered or unexported fields
}

ArgParseResult is the result produced by the argument parser representing the inputted arguments if parsing succeeded.

func ParseArgs 

func ParseArgs(cli *Command, args []string) (*ArgParseResult, error)

ParseArgs parses the slice of arguments provided against a customized CLI. It returns an ArgParseResult representing the accumulated result of parsing and an error which will be `nil` if no error occured

func (*ArgParseResult) HasFlag 

func (apr *ArgParseResult) HasFlag(name string) bool

HasFlag checks if a flag has been set during argument parsing

func (*ArgParseResult) PrimaryArg 

func (apr *ArgParseResult) PrimaryArg() (string, bool)

PrimaryArg gets the primary argument if one exists

func (*ArgParseResult) Subcommand 

func (apr *ArgParseResult) Subcommand() (string, *ArgParseResult, bool)

Subcommand gets the subcommand if one exists

type Argument 

type Argument interface {
	// Name gives the full name of the argument
	Name() string

	// ShortName gives the short name of the argument
	ShortName() string

	// Description returns the description of the argument
	Description() string

	// Required indicates whether or not the argument is required
	Required() bool

	// GetDefaultValue gets the default value of the argument
	GetDefaultValue() (interface{}, bool)
	// contains filtered or unexported methods
}

Argument represents a value that can be passed to the application via a label (eg. `--loglevel=silent`). There are many different kinds of arguments and so this is an interface to allow for sub-arguments

type Command 

type Command struct {
	// Name is the name of the command
	Name string

	// Description is a descriptive string for the command
	Description string

	// Requires subcommand indicates if this command expects a subcommand or can
	// be satisfied without one
	RequiresSubcommand bool
	// contains filtered or unexported fields
}

Command represents a keyword which determines the state of the parser and how it should continue to parse: it is a directive or subdirective to the application. (eg. `go build` has a command of `go` and a subcommand of `build`).

func NewCLI 

func NewCLI(name, desc string, helpEnabled bool) *Command

NewCLI creates a new CLI (initial command) to be customized by the user

func (*Command) AddFlag 

func (c *Command) AddFlag(name, shortName, desc string) *Flag

AddFlag adds a flag to the command

func (*Command) AddFloatArg 

func (c *Command) AddFloatArg(name, shortName, desc string, required bool) *FloatArgument

AddFloatArg adds a named float argument

func (*Command) AddIntArg 

func (c *Command) AddIntArg(name, shortName, desc string, required bool) *IntArgument

AddIntArg adds a named integer argument

func (*Command) AddPrimaryArg 

func (c *Command) AddPrimaryArg(name, desc string, required bool) *PrimaryArgument

AddPrimaryArg adds a primary argument to the command

func (*Command) AddSelectorArg 

func (c *Command) AddSelectorArg(name, shortName, desc string, required bool, possibleValues []string) *SelectorArgument

AddSelectorArg adds a named selector argument

func (*Command) AddStringArg 

func (c *Command) AddStringArg(name, shortName, desc string, required bool) *StringArgument

AddStringArg adds a named string argument

func (*Command) AddSubcommand 

func (c *Command) AddSubcommand(name, desc string, helpEnabled bool) *Command

AddSubcommand adds a subcommand to the command

func (*Command) DisableHelp 

func (c *Command) DisableHelp()

DisableHelp disables the help flag (`--help` or `-h`).

func (*Command) EnableHelp 

func (c *Command) EnableHelp()

EnableHelp enables the help flag (`--help` or `-h`).

func (*Command) Help 

func (c *Command) Help()

Help displays the help message for a given command

func (*Command) HelpMessage 

func (c *Command) HelpMessage() string

HelpMessage returns the stringified help message for a given command

type Flag 

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

Flag represents a flag that when encountered stores true

func (*Flag) Description 

func (f *Flag) Description() string

Description gets the description of the flag

func (*Flag) Name 

func (f *Flag) Name() string

Name gets the name of the flag

func (*Flag) SetAction 

func (f *Flag) SetAction(fn func())

SetAction sets an action function to be run if this flag is encountered

func (*Flag) ShortName 

func (f *Flag) ShortName() string

ShortName gets the short name of the flag

type FloatArgument 

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

FloatArgument is an argument whose value must be a float

func (*FloatArgument) Description 

func (ab *FloatArgument) Description() string

func (*FloatArgument) GetDefaultValue 

func (ab *FloatArgument) GetDefaultValue() (interface{}, bool)

func (*FloatArgument) Name 

func (ab *FloatArgument) Name() string

func (*FloatArgument) Required 

func (ab *FloatArgument) Required() bool

func (*FloatArgument) SetDefaultValue 

func (fa *FloatArgument) SetDefaultValue(v float64)

SetDefaultValue sets the default value of this argument

func (*FloatArgument) SetValidator 

func (fa *FloatArgument) SetValidator(v func(float64) error)

SetValidator sets a validation function for this argument

func (*FloatArgument) ShortName 

func (ab *FloatArgument) ShortName() string

type IntArgument 

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

IntArgument is an argument whose value must be an integer

func (*IntArgument) Description 

func (ab *IntArgument) Description() string

func (*IntArgument) GetDefaultValue 

func (ab *IntArgument) GetDefaultValue() (interface{}, bool)

func (*IntArgument) Name 

func (ab *IntArgument) Name() string

func (*IntArgument) Required 

func (ab *IntArgument) Required() bool

func (*IntArgument) SetDefaultValue 

func (ia *IntArgument) SetDefaultValue(v int)

SetDefaultValue sets the default value of this argument

func (*IntArgument) SetValidator 

func (ia *IntArgument) SetValidator(v func(int) error)

SetValidator sets a validation function for this argument

func (*IntArgument) ShortName 

func (ab *IntArgument) ShortName() string

type PrimaryArgument 

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

PrimaryArgument is an argument that is passed to command without an explicit label (eg. for `go build <filename>`, `<filename>` is the primary argument). Note that a command cannot both take a primary argument and subcommands.

func (*PrimaryArgument) Description 

func (pa *PrimaryArgument) Description() string

Description returns the description of the primary argument

func (*PrimaryArgument) Name 

func (pa *PrimaryArgument) Name() string

Name returns the name of the primary argument

func (*PrimaryArgument) Required 

func (pa *PrimaryArgument) Required() bool

Required indicates whether or not this argument must be supplied

type SelectorArgument 

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

SelectorArgument is an argument whose value is constained to a finite set of string values

func (*SelectorArgument) Description 

func (ab *SelectorArgument) Description() string

func (*SelectorArgument) GetDefaultValue 

func (ab *SelectorArgument) GetDefaultValue() (interface{}, bool)

func (*SelectorArgument) Name 

func (ab *SelectorArgument) Name() string

func (*SelectorArgument) Required 

func (ab *SelectorArgument) Required() bool

func (*SelectorArgument) SetDefaultValue 

func (sea *SelectorArgument) SetDefaultValue(v string)

SetDefaultValue sets the default value of this argument

func (*SelectorArgument) SetValidator 

func (sea *SelectorArgument) SetValidator(v func(string) error)

SetValidator sets a validation function for this argument

func (*SelectorArgument) ShortName 

func (ab *SelectorArgument) ShortName() string

type StringArgument 

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

StringArgument is an argument whose value must be a string

func (*StringArgument) Description 

func (ab *StringArgument) Description() string

func (*StringArgument) GetDefaultValue 

func (ab *StringArgument) GetDefaultValue() (interface{}, bool)

func (*StringArgument) Name 

func (ab *StringArgument) Name() string

func (*StringArgument) Required 

func (ab *StringArgument) Required() bool

func (*StringArgument) SetDefaultValue 

func (sa *StringArgument) SetDefaultValue(v string)

SetDefaultValue sets the default value of this argument

func (*StringArgument) SetValidator 

func (sa *StringArgument) SetValidator(v func(string) error)

SetValidator sets a validation function for this argument

func (*StringArgument) ShortName 

func (ab *StringArgument) ShortName() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.