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

• Introduction
• Background
• Installation
• Components
• Examples
• Project Information
  • Where to get help
  • Contribution guidelines
  • Dependencies
    • Development/Testing Dependencies
  • Related projects
  • License

Background

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

Install via go get, as in:

go get "github.com/synesissoftware/libCLImate.Go"

and then import as:

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

or, simply, as:

import "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
	}, libclimate.InitFlag_PanicOnFailure)

	r, _ = 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

Several 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
• ver2go

Development/Testing Dependencies

• testify;
• ANGoLS;

Related projects

• libCLImate
• libCLImate.Python
• libCLImate.Ruby

License

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