README
¶
Climax
Climax is an alternative CLI that looks like Go command
Climax is a handy alternative CLI (command-line interface) for Go apps.
It looks pretty much exactly like the output of the default go command and
incorporates some fancy features from it. For instance, Climax does support
so-called topics (some sort of Wiki entries for CLI). You can define some
annotated use cases of some command that would get displayed in the
help section of corresponding command also.
I didn't like existing solutions (e.g. codegangsta/cli | spf13/cobra) either for bloated codebase (I dislike the huge complex libraries) or poor output style / API. This project is just an another view on the subject, it has slightly different API than, let's say, Cobra; I find it much more convenient.
A sample application output, Climax produces:
Camus is a modern content writing suite.
Usage:
camus command [arguments]
The commands are:
init starts a new project
new creates flavored book parts
Use "camus help [command]" for more information about a command.
Additional help topics:
writing markdown language cheatsheet
metadata intro to yaml-based metadata
realtime effective real-time writing
Use "camus help [topic]" for more information about a topic.
Here is an example of a trivial CLI application that does nothing, but provides a single string split-like functionality:
demo := climax.New("demo")
demo.Brief = "Demo is a funky demonstation of Climax capabilities."
demo.Version = "stable"
joinCmd := climax.Command{
Name: "join",
Brief: "merges the strings given",
Usage: `[-s=] "a few" distinct strings`,
Help: `Lorem ipsum dolor sit amet amet sit todor...`,
Flags: []climax.Flag{
{
Name: "separator",
Short: "s",
Usage: `--separator="."`,
Help: `Put some separating string between all the strings given.`,
Variable: true,
},
},
Examples: []climax.Example{
{
Usecase: `-s . "google" "com"`,
Description: `Results in "google.com"`,
},
},
Handle: func(ctx climax.Context) int {
var separator string
if sep, ok := ctx.Get("separator"); ok {
separator = sep
}
fmt.Println(strings.Join(ctx.Args, separator))
return 0
},
}
demo.AddCommand(joinCmd)
demo.Run()
Have fun!
Documentation
¶
Overview ¶
Package climax is a handy alternative CLI for Go applications. It looks pretty much exactly like the output of the default `go` command and incorporates some cool features from it. For instance, Climax does support so-called topics (some sort of Wiki entries for CLI). You can also define some annotated use cases of some command that would get displayed in the help section of corresponding command.
Climax applications produce this sort of output:
Camus is a modern content writing suite. Usage: camus command [arguments] The commands are: init starts a new project new creates flavored book parts Use "camus help [command]" for more information about a command. Additional help topics: writing markdown language cheatsheet metadata intro to yaml-based metadata realtime effective real-time writing Use "camus help [topic]" for more information about a topic.
Example (Application) ¶
package main
import (
"fmt"
"github.com/tucnak/climax"
"strings"
)
func main() {
demo := climax.New("demo")
demo.Brief = "Demo is a funky demonstation of Climax capabilities."
demo.Version = "stable"
joinCmd := climax.Command{
Name: "join",
Brief: "merges the strings given",
Usage: `[-s=] "a few" distinct strings`,
Help: `Lorem ipsum dolor sit amet amet sit todor...`,
Flags: []climax.Flag{
{
Name: "separator",
Short: "s",
Usage: `--separator="."`,
Help: `Put some separating string between all the strings given.`,
Variable: true,
},
},
Examples: []climax.Example{
{
Usecase: `-s . "google" "com"`,
Description: `Results in "google.com"`,
},
},
Handle: func(ctx climax.Context) int {
var separator string
if sep, ok := ctx.Get("separator"); ok {
separator = sep
}
fmt.Println(strings.Join(ctx.Args, separator))
return 0
},
}
demo.AddCommand(joinCmd)
demo.Run()
}
// Handler accepts a climax.Context object and returns an exitcode integer.
func main(ctx climax.Context) int {
if len(ctx.Args) < 2 {
ctx.Log("not enough arguments")
// with os.Exit(1)
return 1
}
if name, ok := ctx.Get("name"); ok {
// argument `name` parsed
fmt.Println(name)
} else {
ctx.Log("name not specified")
return 1
}
return 0
}
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Application ¶
type Application struct {
Name string // `go`
Brief string // `Go is a tool for managing Go source code.`
Version string // `1.5`
Commands []Command
Topics []Topic
Groups []Group
// Default is a default handler. It gets executed if there are
// no command line arguments (except the program name), when
// otherwise, by default, the help entry is being shown.
Default CmdHandler
// contains filtered or unexported fields
}
Application is a main CLI instance.
By default, Climax provides its own implementation of version command, but it will use "version" command instead if you provide one.
func New ¶
func New(name string) *Application
New constructs a new CLI application with a given name. In case of an empty name it will panic.
func (*Application) AddCommand ¶
func (a *Application) AddCommand(command Command)
AddCommand does literally what its name says.
func (*Application) AddGroup ¶
func (a *Application) AddGroup(name string) string
AddGroup adds a new empty, named group.
Pass the returned group name to Command's Group member to make the command part of the group.
func (*Application) AddTopic ¶
func (a *Application) AddTopic(topic Topic)
AddTopic does literally what its name says.
func (*Application) Log ¶
func (a *Application) Log(lines ...interface{})
Log prints the message to stderrr (each argument takes a distinct line).
func (*Application) Run ¶
func (a *Application) Run() int
Run executes a CLI.
Take a note, Run panics if len(os.Args) < 1
type CmdHandler ¶
CmdHandler is a handling function type for functions.
Returned integer would be used as application exit status.
type Command ¶
type Command struct {
// Name is a [A-Za-z_0-9] identifier of up to 11 characters.
//
// Keep command names short, reasonable, catchy and
// easy to type. At best, keep it a single word.
//
// Examples: build, list, install
Name string
// Brief is a short annotation of action command is capable of.
//
// Climax doesn't provide any limitations on the brief string
// format, however it's highly recommended to keep it a single
// lowercase phrase of 3-5 words without any punctuation marks.
//
// Example: compile packages and dependencies
Brief string
// Usage is a generic command use case, suggested by help.
//
// This string gets displayed on the usage line of command
// help entry. You should NOT include command name itself.
//
// Example: [-o output] [-i] [build flags] [packages]
Usage string
// Help is a detailed command reference displayed after
// the usage line and before the available flags block
// of the help entry.
//
// Try to stick to the 80 character limit, so it looks fine
// in the split terminal window.
Help string
// The group name this command belongs to.
Group string
// Handling, I bet it's pretty straight-forward.
Handle CmdHandler
// Flags are command-line options.
Flags []Flag
// Examples are annotated tips on command usage.
Examples []Example
}
Command represents a top-level application subcommand.
func (*Command) AddExample ¶
AddExample does exactly what its name says.
type Context ¶
type Context struct {
// Real arguments, excluding any option flags and their values.
//
// Example:
//
// $ app command --force -s="magic" 42 fairy
//
// []string{"42", "fairy"}
//
Args []string
NonVariable map[string]bool
Variable map[string]string
// contains filtered or unexported fields
}
Context is a set of arguments and options of command call.
func (*Context) Get ¶
Get returns a value of corresponding variable flag. Second (bool) parameter says whether it's really defined or not.
type Example ¶
type Example struct {
// Usecase is a typical use of command.
//
// Make sure to omit application and command name here,
// since Climax appends it by default.
Usecase string
// Be descriptive, but keep it under 3-5 sentences.
Description string
}
Example is an annotated use case of the command.
type Flag ¶
type Flag struct {
// A flag label without the prefix (--, -, whatever).
//
// Flag names can't contain more than 11 alphanumeric characters.
Name string
// Usually the first letter of the name.
//
// Short names can't contain more than 3 alphanumeric characters.
Short string
// Suggested use case, a generic example, showing
// user how to use the flag.
//
// Example: --filter="token"
Usage string
// Help is displayed under the corresponding flag's
// usage in the available commands section of help entry.
//
// Example: Limit tool output to tokens given.
Help string
// Variable flags have a flag value, non-variable don't.
//
// Flag value is a string assigned to particular flag.
// For instance, --force is a non-variable flag and
// --filter="token" is a variable flag.
Variable bool
}
Flag is an optional command-line option.
type Group ¶
Group connects a list of commands with a descriptive string.
The Name is used in the help output to group related commands together.
type Topic ¶
type Topic struct {
// Name is a [A-Za-z_0-9] identifier of up to 11 characters.
//
// Keep topic names short, reasonable, catchy and
// easy to type. At best, keep it a single word.
//
// Examples: buildmode, packages, filetype
Name string
// Brief is a short annotation of the topic.
//
// Climax doesn't provide any limitations on the brief string
// format, however it's highly recommended to keep it a single
// lowercase phrase of 3-5 words without any punctuation marks.
//
// Example: description of package lists
Brief string
// Text is the actual topic content.
//
// Try to stick to the 80 character limit, so it looks fine
// in the split terminal window.
Text string
}
Topic is some sort of a concise wiki page.
Source Files