libclimate

README

libCLImate.Go

Command-Line Interface boilerplate mini-framework, for Go

Introduction

libCLImate is a Command-Line Interface boilerplate mini-framework, which encapsulates the common aspects of Command-Line Interface boilerplate. The first libCLImate was a C/C++ library. There have been several implementations in other languages. libCLImate.Go is the Go version.

Table of Contents

1. Introduction
2. Installation
3. Components
4. Examples
5. Project Information

Introduction

As described in the CLASP project, command-line arguments may be discriminated as flags, options, and values:

• flags are arguments that begin with 1+ hyphens and have a name, and whose presence/absence alter program behaviour, e.g. -f, --verbose;
• options are arguments that begin with 1+ hyphens and have a name and a value, e.g. --verbosity=terse, -v t;
• values are arguments that do not begin with hyphens (and are not the value of an option), e.g. ~/my-files/.

libCLImate builds upon this discrimination of arguments to provide higher-level facilities and more succinct specification. All variants (except for the C/C++ version) provide this in the form of a Climate class type, which is specified according to a lightweight DSL. The constructed Climate instance is then used to parse the command-line arguments, and provides a number of facilities, including:

• parsing into flags, options, values, including recognition of special flag -- as marking end of flags/options (which is done via the underlying CLASP library);
• automatic handling of --help flag, printing out a full description of the program features and all flags/options in details, and then terminating with exit code 0;
• automatic handling of --version flag, printing out the program name and version, and then terminating with exit code 0;
• detection and reporting of unrecognised flags/options, and then terminating with exit code 1;
• sundry other helper functions and parsed information.

libCLImate.Go, which is built from CLASP.Go, provides access to an instance of Climate (a Go struct) via the Init() function's callback function argument, as illustrated in brief in the Components section below and extensively in the EXAMPLES.md.

Installation

import libclimate "github.com/synesissoftware/libCLImate.Go"

Components

With libCLImate.Go, specification of the Climate struct is done via the Init() function by specifying a callback within which the features are specified, as in:

// README_Components.go

func main() {

	climate, err := libclimate.Init(func (cl *libclimate.Climate) (error) {

        . . . // specify features HERE

		return nil
	});
	if err != nil {

		fmt.Fprintf(os.Stderr, "failed to create CLI parser: %v\n", err)
	}

	_, _ = climate.ParseAndVerify(os.Args, libclimate.ParseFlag_PanicOnFailure)

    . . . // rest of program
}

Inside "constructor" - at specify features HERE - the various features of the Climate instance under construction can be specified, including:

• the version as a string or an array (of numbers or strings), as in:

        cl.Version = "0.0.1"

• the info lines as an array of strings (including special value ":version:", which prints program name and version), as in:

        cl.InfoLines = []string{ "Example program", "", ":version:", "", }

Even with just those two attributes set, the program will now respond to --help and --version with useful output:

• --help

Example program

README_Components 0.0.1

USAGE: README_Components [ ... flags and options ... ]

flags/options:

	--help
		Shows this help and exits

	--version
		Shows version information and exits

• --version

README_Components 0.0.1

Specification of program-specific flags/options is straightforward, e.g.

• a flag --debug:

        cl.AddFlag(clasp.Flag("--debug").SetHelp("runs in Debug mode").SetAlias("-d"))

• an option --verbosity, with a callback function:

        o_Verbosity := clasp.Option("--verbosity").SetHelp("specifies verbosity").SetAlias("-v").SetValues("terse", "quiet", "silent", "chatty")

        cl.AddOptionFunc(o_Verbosity, func (o *clasp.Argument, a *clasp.Alias) {

			fmt.Printf("verbosity specified as: %v\n", o.Value)
		})

Now the program will respond to the flag --help with:

Example program

README_Components 0.0.1

USAGE: README_Components [ ... flags and options ... ]

flags/options:

	--help
		Shows this help and exits

	--version
		Shows version information and exits

	-d
	--debug
		runs in Debug mode

	-v <value>
	--verbosity=<value>
		specifies verbosity
		where <value> one of:
			terse
			quiet
			silent
			chatty

And will respond to the option -v silent (which is equivalent to --verbosity=silent) with:

verbosity specified as: silent

Examples

Examples are provided in the examples directory, along with a markdown description for each. A detailed list TOC of them is provided in EXAMPLES.md.

Project Information

Where to get help

GitHub Page

Contribution guidelines

Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/libCLImate.Go.

Dependencies

libCLImate.Go depends on:

• CLASP.Go

Related projects

• libCLImate
• libCLImate.Python
• libCLImate.Ruby

License

libCLImate.Go is released under the 3-clause BSD license. See LICENSE for details.

Documentation

Index

• Constants
• type AliasFlag
• type Climate
  • func Init(initFn InitFunc, options ...interface{}) (climate *Climate, err error)
  • func (cl Climate) Abort(message string, err error, options ...interface{})
  • func (cl *Climate) AddAlias(resolved_name, alias string)
  • func (cl *Climate) AddFlag(flag clasp.Alias, flags ...AliasFlag)
  • func (cl *Climate) AddFlagFunc(flag clasp.Alias, flagFn FlagFunc, flags ...AliasFlag)
  • func (cl *Climate) AddOption(option clasp.Alias, flags ...AliasFlag)
  • func (cl *Climate) AddOptionFunc(option clasp.Alias, optionFn OptionFunc, flags ...AliasFlag)
  • func (cl Climate) Parse(argv []string, options ...interface{}) (result Result, err error)
  • func (cl Climate) ParseAndVerify(argv []string, options ...interface{}) (result Result, err error)
• type FlagFunc
• type InitFlag
• type InitFunc
• type OptionFunc
• type ParseFlag
• type Result
  • func (result Result) FlagIsSpecified(id interface{}) bool
  • func (result Result) LookupFlag(id interface{}) (*clasp.Argument, bool)
  • func (result Result) LookupOption(id interface{}) (*clasp.Argument, bool)
  • func (result Result) Verify(options ...interface{})

Constants

const (
	VersionMajor int16 = 0
	VersionMinor int16 = 5
	VersionPatch int16 = 0
	Version      int64 = (int64(VersionMajor) << 48) + (int64(VersionMinor) << 32) + (int64(VersionPatch) << 16)

	VersionRevision int16 = VersionPatch
)

Types

type AliasFlag

type AliasFlag int

Type of flags passed to the libclimate.AddFlag(), and libclimate.AddOption() methods

type Climate

type Climate struct {
	Aliases       []*clasp.Alias
	ParseFlags    clasp.ParseFlag
	Version       interface{}
	VersionPrefix string
	InfoLines     []string
	ProgramName   string
	// contains filtered or unexported fields
}

Structure representing a CLI parsing context, obtained from libclimate.Init()

func Init

func Init(initFn InitFunc, options ...interface{}) (climate *Climate, err error)

Initialises a Climate instance, according to the given function (which may not be nil) and arguments

func (Climate) Abort

func (cl Climate) Abort(message string, err error, options ...interface{})

Emits the given message and, optionally, err to the standard error stream, prefixed with the program name, and then terminates the process with a non-0 exit code.

func (*Climate) AddAlias

func (cl *Climate) AddAlias(resolved_name, alias string)

Adds an alias to the Climate instance

The resolved_name param can be the name of a flag or option, or an option-with-value. The alias param is the alias (which must not contain an equals sign.

func (*Climate) AddFlag

func (cl *Climate) AddFlag(flag clasp.Alias, flags ...AliasFlag)

Adds a (copy of the) flag to the Climate instance

func (*Climate) AddFlagFunc

func (cl *Climate) AddFlagFunc(flag clasp.Alias, flagFn FlagFunc, flags ...AliasFlag)

Adds a (copy of the) flag to the Climate instance

func (*Climate) AddOption

func (cl *Climate) AddOption(option clasp.Alias, flags ...AliasFlag)

Adds a (copy of the) option to the Climate instance

func (*Climate) AddOptionFunc

func (cl *Climate) AddOptionFunc(option clasp.Alias, optionFn OptionFunc, flags ...AliasFlag)

Adds a (copy of the) option to the Climate instance

func (Climate) Parse

func (cl Climate) Parse(argv []string, options ...interface{}) (result Result, err error)

Parses a command line, obtaining a Result instance representing the arguments received by the process

func (Climate) ParseAndVerify

func (cl Climate) ParseAndVerify(argv []string, options ...interface{}) (result Result, err error)

Parses via Parse() and verifies via Verify()

Panics, rather than returns, if the ParseFlag_PanicOnFailure flag is specified

type FlagFunc

type FlagFunc func()

type InitFlag

type InitFlag int

Type of flags passed to the libclimate.Init() method

const (
	InitFlag_None           InitFlag = 1 << iota
	InitFlag_PanicOnFailure InitFlag = 1 << iota
	InitFlag_NoHelpFlag     InitFlag = 1 << iota
	InitFlag_NoVersionFlag  InitFlag = 1 << iota
)

type InitFunc

type InitFunc func(cl *Climate) error

Callback function for specification of Climate via DSL

type OptionFunc

type OptionFunc func(option *clasp.Argument, alias *clasp.Alias)

type ParseFlag

type ParseFlag int

Type of flags passed to the libclimate.Parse() method

const (
	ParseFlag_None            ParseFlag = 1 << iota
	ParseFlag_PanicOnFailure  ParseFlag = 1 << iota
	ParseFlag_DontCheckUnused ParseFlag = 1 << iota
)

type Result

type Result struct {
	Flags       []*clasp.Argument
	Options     []*clasp.Argument
	Values      []*clasp.Argument
	ProgramName string
	Argv        []string
	// contains filtered or unexported fields
}

Structure representing CLI results, obtained from Climate.Parse()

func (Result) FlagIsSpecified

func (result Result) FlagIsSpecified(id interface{}) bool

Determines if the given flag is specified

func (Result) LookupFlag

func (result Result) LookupFlag(id interface{}) (*clasp.Argument, bool)

Looks for a flag with the given id - name, or the alias instance - and returns it and the value true if found; if not, returns nil and false

func (Result) LookupOption

func (result Result) LookupOption(id interface{}) (*clasp.Argument, bool)

Looks for an option with the given id - name, or the alias instance - and returns it and the value true if found; if not, returns nil and false

func (Result) Verify

func (result Result) Verify(options ...interface{})

Verifies that all given arguments received are recognised according to the specified flags and options