command

README

command

command is a tiny package that helps you to add cli subcommands to your Go program with no effort, and prints a pretty guide if needed.

Usage: program <command>

where <command> is one of:
  version   prints the version
  command1  some description about command1
  command2  some description about command2

available flags:
  -exec-path="": a custom path to executable

program <command> -h for subcommand help

Usage

In order to start, go get this repository:

go get github.com/odeke-em/command

This package allows you to use flags package as you used to do, and provides additional parsing for subcommands and subcommand flags.

import "github.com/odeke-em/command"

// register any global flags
var flagExecPath = flag.String("exec-path", "", "a custom path to executable")

type VersionCommand struct{
	flagVerbose *bool
}

func (cmd *VersionCommand) Flags(fs *flag.FlagSet) *flag.FlagSet {
	// define subcommand's flags
	cmd.flagVerbose = fs.Bool("v", false, "provides verbose output")
	return fs
}

func (cmd *VersionCommand) Run(args []string) {
	// implement the main body of the subcommand here
  // required and optional arguments are found in args
}

// register version as a subcommand
command.On("version", "prints the version", &VersionCommand{}, []string{"<required-arg>"})
command.On("command1", "some description about command1", ..., []string{})
command.On("command2", "some description about command2", ..., []string{})
command.Parse()
// ...
command.Run()

The program above will handle the registered commands and invoke the matching command's Run or print subcommand help if -h is set.

$ program -exec-path=/home/user/bin/someexec version -v=true history

will output the version of the program in a verbose way requring an argument (history), and will set the exec path to the provided path. If arguments doesn't match any subcommand or illegal arguments are provided, it will print the usage guide.

License

Copyright 2013 Google Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Documentation

Overview

Package command allows you to define subcommands for your command line interfaces. It extends the flag package to provide flag support for subcommands.

Index

• Variables
• func DefineHelp(help Cmd)
• func On(name, description string, command Cmd, requiredFlags []string)
• func Parse()
• func ParseAndRun()
• func Run()
• func Usage()
• type Cmd

Variables

var (
	OutFileDesc = os.Stdout
)

Functions

func DefineHelp

func DefineHelp(help Cmd)

func On

func On(name, description string, command Cmd, requiredFlags []string)

Registers a Cmd for the provided sub-command name. E.g. name is the `status` in `git status`.

func Parse

func Parse()

Parses the flags and leftover arguments to match them with a sub-command. Evaluate all of the global flags and register sub-command handlers before calling it. Sub-command handler's `Run` will be called if there is a match. A usage with flag defaults will be printed if provided arguments don't match the configuration. Global flags are accessible once Parse executes.

func ParseAndRun

func ParseAndRun()

Parses flags and run's matching subcommand's runnable.

func Run

func Run()

Runs the subcommand's runnable. If there is no subcommand registered, it silently returns.

func Usage

func Usage()

Prints the usage.

Types

type Cmd

type Cmd interface {
	Flags(*flag.FlagSet) *flag.FlagSet
	Run(args []string)
}

Cmd represents a sub command, allowing to define subcommand flags and runnable to run once arguments match the subcommand requirements.