hadfield: hawx.me/code/hadfield Index | Examples | Files

package hadfield

import "hawx.me/code/hadfield"

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

Code:

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)
}

Index

Examples

Package Files

command.go hadfield.go template.go

Variables

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.

func CommandUsage Uses

func CommandUsage(c Interface, templates Templates)

CommandUsage writes a help message for the subcommand to Stdout.

func Run Uses

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 Uses

func Usage(cmds Commands, templates Templates)

Usage writes a help message to Stdout.

type Command Uses

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 Uses

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 Uses

func (c *Command) Callable() bool

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

func (*Command) Category Uses

func (c *Command) Category() string

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

func (*Command) Data Uses

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

Data returns the information required for rendering the help templates.

func (*Command) Name Uses

func (c *Command) Name() string

Name returns the first word in Usage.

type Commands Uses

type Commands []Interface

func (Commands) Data Uses

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

type Interface Uses

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 Uses

type Template string

func (*Template) Render Uses

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

type Templates Uses

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.

Package hadfield imports 8 packages (graph) and is imported by 10 packages. Updated 2018-06-28. Refresh now. Tools for package owners.