cli

README

cli

A library to easily create command line interfaces.

Example

The following example creates a simple CLI action for running commands at a remote host (like example run on host -c "uname -a" 192.168.1.1 given the binary has the example name and the uname command should be executed on 192.168.1.1).

// Struct used to configure an action.
type ExampleRunner struct {
	Verbose bool   `cli:"type=opt short=v long=verbose"`               // Flag (boolean option) example. This is either set or not.
	Command string `cli:"type=opt short=c long=command required=true"` // Option that has a default value.
	Hosts   string `cli:"type=arg required=true"`                      // Argument with at least one required.
}

// Run the action. Called when the cli.Run function is called with a route matching the one of this action.
func (er *ExampleRunner) Run() error {
	// Called when action matches route.
	if er.Verbose {
		log.Printf("Going to execute %q at the following hosts: %v", er.Command, er.Hosts)
	}
	// [..] Executing the SSH command is left to the reader.
	return nil
}

// Basic example that shows how to register an action to a route and execute it.
func Example_basic() {
	router := NewRouter()
	router.Register("run/on/hosts", &ExampleRunner{}, "This is an example that pretends to run a given command on a set of hosts.")
	router.Run("run", "on", "host", "-v", "-c", "uname -a", "192.168.1.1")
	router.RunWithArgs() // Run with args given on the command line.
}

Usage

There are three steps to take: 1. Create a struct with the options and arguments to be supported. Description of those entities is done using annotations. 2. Implement the Runner interface for this struct. 3. Register the struct as action with a path on the router.

Documentation

Overview

golang CLI parameter handling

This is dynport's version of a golang CLI handler. Given a struct that implements an interface with fields that have annotations, an CLI is built that can be run against a list of strings (taken from os.Args for example).

See the basic example on how to use this library.

The following constraints or special behaviors are to be taken into account:

• Options (type "opt") are given in short or long form ("-h" vs. "--help"). Each option must have at least one modifier set.
• Required options must be present. A default value is preset in the struct.
• Options with a boolean value are internally handled as flags, i.e. presence of the flag indicates true (or opposite of a defined default value).
• Ordering of arguments is defined by the position in the action's struct (first come first serve).
• Arguments (type "arg") may be variadic (type in the struct must be a slice), i.e. arbitrary can be given. If the argument is required, at least one value must be present. Only the last arguments can be variadic.
• Non variadic arguments must always be given.

Example (Basic)

Basic example that shows how to register an action to a route and execute it.

package main

import (
	"log"
)

// Struct used to configure an action.
type ExampleRunner struct {
	Verbose bool   `cli:"type=opt short=v long=verbose"`               // Flag (boolean option) example. This is either set or not.
	Command string `cli:"type=opt short=c long=command required=true"` // Option that has a default value.
	Hosts   string `cli:"type=arg required=true"`                      // Argument with at least one required.
}

// Run the action. Called when the cli.Run function is called with a route matching the one of this action.
func (er *ExampleRunner) Run() error {
	// Called when action matches route.
	if er.Verbose {
		log.Printf("Going to execute %q at the following hosts: %v", er.Command, er.Hosts)
	}
	// [..] Executing the SSH command is left to the reader.
	return nil
}

// Basic example that shows how to register an action to a route and execute it.
func main() {
	router := NewRouter()
	router.Register("run/on/hosts", &ExampleRunner{}, "This is an example that pretends to run a given command on a set of hosts.")
	router.Run("run", "on", "host", "-v", "-c", "uname -a", "192.168.1.1")
	router.RunWithArgs() // Run with args given on the command line.
}

Index

• Variables
• func RunAction(runner Runner, args ...string) (e error)
• func RunActionWithArgs(runner Runner) (e error)
• type Router
  • func NewRouter() *Router
  • func (r *Router) Register(path string, runner Runner, desc string)
  • func (r *Router) RegisterFunc(path string, f func() error, desc string)
  • func (r *Router) Run(args ...string) (e error)
  • func (r *Router) RunWithArgs() (e error)
• type Runner

Examples

• Package (Basic)

Variables

var NoRouteError = fmt.Errorf("no route matched")

Functions

func RunAction

func RunAction(runner Runner, args ...string) (e error)

Run the given action with given arguments.

func RunActionWithArgs

func RunActionWithArgs(runner Runner) (e error)

Run the given action with the arguments given on the command line.

Types

type Router

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

The basic datastructure used in cli. A router is added actions for different paths using the "Register" and "RegisterFunc" methods. These actions can be executed using the "Run" and "RunWithArgs" methods.

func NewRouter

func NewRouter() *Router

Create a new router.

func (*Router) Register

func (r *Router) Register(path string, runner Runner, desc string)

Register the given action (some struct implementing the Runner interface) for the given route.

func (*Router) RegisterFunc

func (r *Router) RegisterFunc(path string, f func() error, desc string)

Register the given function as handler for the given route. This is a shortcut for actions that don't need options or arguments. A description can be provided as an optional argument.

func (*Router) Run

func (r *Router) Run(args ...string) (e error)

Run the given arguments against the registered actions, i.e. try to find a matching route and run the according action.

func (*Router) RunWithArgs

func (r *Router) RunWithArgs() (e error)

Run the arguments from the commandline (aka os.Args) against the registered actions, i.e. try to find a matching route and run the according action.

type Runner

type Runner interface {
	Run() error
}

Interface that must be implemented by actions. This is interface is used by the RegisterAction function. The Run method of the implementing type will be called if the given route matches it.