hadfield

package module
Version: v0.0.0-...-72744ca Latest Latest
Warning

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

Go to latest
Published: Apr 20, 2018 License: MIT Imports: 8 Imported by: 11

README

Hadfield docs

A basic subcommand package to complement flag.

Documentation

Overview

Package hadfield implements a basic subcommand system to complement the flag package.

Example
package main

import (
	"fmt"
	"os"

	"hawx.me/code/hadfield"
)

var cmdGreet = &hadfield.Command{
	Usage: "greet [options]",
	Short: "displays a greeting",
	Long: `
  Greet displays a formatted greeting to a person in the language specified.

    --person <name>     # Name of person to greet
    --lang <en|fr>      # Language to use, English or French
`,
}

func runGreet(cmd *hadfield.Command, args []string) {
	switch greetLang {
	case "en":
		fmt.Println("Hello", greetPerson)
	case "fr":
		fmt.Println("Bonjour", greetPerson)
	default:
		os.Exit(2)
	}
}

var greetPerson, greetLang string

func init() {
	cmdGreet.Run = runGreet

	cmdGreet.Flag.StringVar(&greetPerson, "person", "someone?", "")
	cmdGreet.Flag.StringVar(&greetLang, "lang", "en", "")
}

var templates = hadfield.Templates{
	Help: `usage: example [command] [arguments]

  This is an example.

  Commands: {{range .}}
    {{.Name | printf "%-15s"}} # {{.Short}}{{end}}
`,
	Command: `usage: example {{.Usage}}
{{.Long}}
`,
}

var commands = hadfield.Commands{
	cmdGreet,
}

func main() {
	hadfield.Run(commands, templates)
}
Output:

Index

Examples

Constants

This section is empty.

Variables

View Source
var Exit = os.Exit

Customisable Exit function. This is used for exiting in various places throughout and can be overriden for testing purposes or to perform other tasks.

Functions

func CommandUsage

func CommandUsage(c Interface, templates Templates)

CommandUsage writes a help message for the subcommand to Stdout.

func Run

func Run(cmds Commands, templates Templates)

Run executes the correct subcommand.

The special subcommand 'help' is defined and displays either the usage message, or if called with an argument the help message for a particular subcommand.

If the subcommand cannot be found a message is displayed and it exits with status code 2.

func Usage

func Usage(cmds Commands, templates Templates)

Usage writes a help message to Stdout.

Types

type Command

type Command struct {
	// Run runs the command. It is passed the list of args that came after the
	// command name.
	Run func(cmd *Command, args []string)

	// Usage returns the one-line usage string. The first word on the line is
	// taken to be the command name.
	Usage string

	// Short is a single line description used in the help listing.
	Short string

	// Long is the detailed and formatted message shown in the full help for the
	// command.
	Long string

	Flag        flag.FlagSet
	CustomFlags bool
}

func (*Command) Call

func (c *Command) Call(cmd Interface, templates Templates, args []string)

Call parses the flags if CustomFlags is not set, then calls the function defined by Run, and finally exits.

func (*Command) Callable

func (c *Command) Callable() bool

Callable returns true if Run is defined, and false otherwise.

func (*Command) Category

func (c *Command) Category() string

Category returns "Command" if Run is defined, and otherwise "Documentation".

func (*Command) Data

func (c *Command) Data() interface{}

Data returns the information required for rendering the help templates.

func (*Command) Name

func (c *Command) Name() string

Name returns the first word in Usage.

type Commands

type Commands []Interface

func (Commands) Data

func (cs Commands) Data() []interface{}

type Interface

type Interface interface {
	// Name is the word used to call the subcommand.
	Name() string

	// Data is used when rendering help and usage templates. Values that should be
	// expected are:
	//
	// Callable:
	//   i.e. Callable()
	// Category:
	//   i.e. Category().
	// Usage:
	//   The string starting with the commands name.
	// Short:
	//   A short, one-line, description.
	// Long:
	//   A long description.
	// Name:
	//   i.e. Name().
	Data() interface{}

	// Category is the type of subcommand, it can be anything and can be used to
	// group subcommands together.
	Category() string

	// Callable is true if the Call() method actually does something.
	Callable() bool

	// Call runs the subcommand.
	Call(cmd Interface, templates Templates, args []string)
}

Interface defines the common behaviour of subcommands. The default implementation is Command, but it is possible to mix these with other types of subcommand such as those dynamically discovered when used.

type Template

type Template string

func (*Template) Render

func (text *Template) Render(w io.Writer, data interface{})

type Templates

type Templates struct {
	// Help is the template rendered to display the help for the executable, that
	// is the one shown when "$0 help", "$0 -h" or "$0 --help" are called.
	Help Template

	// Command is the template rendered to display help for a particular
	// subcommand, it is shown when "$0 help [subcommand]", "$0 [subcommand] -h"
	// or "$0 [subcommand] --help" are called.
	Command Template
}

Templates defines how the help screens are displayed given in the text/template format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL