README
¶
cli
A simple library for writing applications with a command line interface.
import mellium.im/cli
License
The package may be used under the terms of the BSD 2-Clause License a copy of which may be found in the file LICENSE.md.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed as above, without any additional terms or conditions.
Documentation
¶
Overview ¶
Package cli can be used to create modern command line interfaces.
User interfaces created with Command and CommandSet take the form of the application name followed by the subcommand which may do its own parsing on all arguments after it. For instance, if recreating the "git" command it might have a subcommand called "commit" and each could have their own flags:
git -config mygit.config commit -interactive
See the examples for the definition of this command.
Example ¶
package main
import (
"flag"
"fmt"
"os"
"mellium.im/cli"
)
func commitCmd(cfg string) *cli.Command {
commitFlags := flag.NewFlagSet("commit", flag.ExitOnError)
help := commitFlags.Bool("h", false, "Print this commands help output…")
interactive := commitFlags.Bool("interactive", false, "Run commit in interactive mode.")
return &cli.Command{
Usage: `commit [-h] [-interactive] …`,
Description: `Records changes to the repository.
Stores the current contents of the index in a new commit…`,
Flags: commitFlags,
Run: func(c *cli.Command, args ...string) error {
commitFlags.Parse(args)
fmt.Printf("Using config file: %s\n", cfg)
if *interactive {
fmt.Println("Interactive mode enabled.")
}
if *help {
c.Help(os.Stdout)
}
return nil
},
}
}
func main() {
globalFlags := flag.NewFlagSet("git", flag.ExitOnError)
cfg := globalFlags.String("config", "gitconfig", "A custom config file to load")
// In a real main function, this would probably be os.Args[1:]
globalFlags.Parse([]string{"-config", "mygit.config", "commit", "-interactive", "-h"})
cmds := &cli.CommandSet{
Name: "git",
Commands: []*cli.Command{
commitCmd(*cfg),
},
}
cmds.Run(globalFlags.Args()...)
}
Output: Using config file: mygit.config Interactive mode enabled. Usage: commit [-h] [-interactive] … Options: -h Print this commands help output… -interactive Run commit in interactive mode. Records changes to the repository. Stores the current contents of the index in a new commit…
Example (Articles) ¶
package main
import (
"fmt"
"mellium.im/cli"
)
// Returns a help article about the config file format.
func articleHelp() *cli.Command {
return &cli.Command{
Usage: `article`,
Description: `Help article about help articles.
Help articles are "commands" that do not provide any functionality. They
only exist so that their description can be shown using the help command
(or your own help system):
$ ./yourcmd help articlename`,
}
}
func main() {
cmds := &cli.CommandSet{
Name: "git",
Commands: []*cli.Command{
commitCmd(""),
articleHelp(),
},
}
cmds.Commands = append(cmds.Commands, cli.Help(cmds))
fmt.Println("$ git help")
cmds.Run("help")
fmt.Println("$ git help article")
cmds.Run("help", "article")
}
Output: $ git help Usage of git: git [options] command Commands: commit Records changes to the repository. help Print articles and detailed information about subcommands. Articles: article Help article about help articles. $ git help article Help article about help articles. Help articles are "commands" that do not provide any functionality. They only exist so that their description can be shown using the help command (or your own help system): $ ./yourcmd help articlename
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command struct {
// Usage always starts with the name of the command, followed by a description
// of its usage. For more information, see the Name method.
Usage string
// Description starts with a short, one line description. It can optionally be
// followed by a blank line and then a longer description or help info.
Description string
// Flags is a flag set that provides options that are specific to this
// subcommand.
Flags *flag.FlagSet
// The action to take when this command is executed. The args will be the
// remaining command line args after all flags have been parsed.
// Run is normally called by a CommandSet and shouldn't be called directly.
Run func(c *Command, args ...string) error
}
Command represents a new subcommand.
func Help ¶ added in v0.0.4
func Help(cs *CommandSet) *Command
Help returns a Command that prints help information about its command set to stdout, or about a specific command if one is provided as an argument.
For example, in a program called "git" running:
git help commit
would print information about the "commit" subcommand.
Example ¶
cmds := &cli.CommandSet{
Name: "git",
}
cmds.Commands = []*cli.Command{
commitCmd(""),
cli.Help(cmds),
}
cmds.Run("help")
Output: Usage of git: git [options] command Commands: commit Records changes to the repository. help Print articles and detailed information about subcommands.
func (*Command) Help ¶
Help writes the usage line, flags, and description for the command to the provided io.Writer. If c.Flags is a valid flag set, calling Help sets the output of c.Flags.
func (*Command) Name ¶
Name returns the first word of c.Usage which will be the name of the command. For example with a usage line of:
commit [options]
Name returns "commit".
type CommandSet ¶ added in v0.0.2
CommandSet is a set of application subcommands and application level flags.
func (*CommandSet) Help ¶ added in v0.0.2
func (cs *CommandSet) Help(w io.Writer)
Help prints a usage line for the command set and a list of commands to the provided writer.
func (*CommandSet) Run ¶ added in v0.0.2
func (cs *CommandSet) Run(args ...string) error
Run attempts to run the command in the CommandSet that matches the first argument passed in. If no arguments are passed in, run prints help information to stdout. If the first argument does not match a command in the CommandSet, run prints the same help information to stderr.
Source Files