x/urfave-cli
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #440 from urfave/more-v1-examples

Browse Source 
Enable more examples as runnable in README
This commit is contained in:
Dan Buch 2016-06-01 09:49:21 -04:00
commit ddb6f44179
1 changed files with 388 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

561
README.md
View File

@ -13,13 +13,19 @@
`github.com/codegangsta/cli` -- Github will automatically redirect requests `github.com/codegangsta/cli` -- Github will automatically redirect requests
to this repository, but we recommend updating your references for clarity. to this repository, but we recommend updating your references for clarity.
cli is a simple, fast, and fun package for building command line apps in Go. The goal is to enable developers to write fast and distributable command line applications in an expressive way. cli is a simple, fast, and fun package for building command line apps in Go. The
goal is to enable developers to write fast and distributable command line
applications in an expressive way.
## Overview ## Overview
Command line apps are usually so tiny that there is absolutely no reason why your code should *not* be self-documenting. Things like generating help text and parsing command flags/options should not hinder productivity when writing a command line app. Command line apps are usually so tiny that there is absolutely no reason why
your code should *not* be self-documenting. Things like generating help text and
parsing command flags/options should not hinder productivity when writing a
command line app.
**This is where cli comes into play.** cli makes command line programming fun, organized, and expressive! **This is where cli comes into play.** cli makes command line programming fun,
organized, and expressive!
## Installation ## Installation
@ -33,7 +39,8 @@ To install cli, simply run:
$ go get github.com/urfave/cli $ go get github.com/urfave/cli
``` ```
Make sure your `PATH` includes to the `$GOPATH/bin` directory so your commands can be easily used: Make sure your `PATH` includes to the `$GOPATH/bin` directory so your commands
can be easily used:
``` ```
export PATH=$PATH:$GOPATH/bin export PATH=$PATH:$GOPATH/bin
``` ```
@ -86,13 +93,19 @@ import (
## Getting Started ## Getting Started
One of the philosophies behind cli is that an API should be playful and full of discovery. So a cli app can be as little as one line of code in `main()`. One of the philosophies behind cli is that an API should be playful and full of
discovery. So a cli app can be as little as one line of code in `main()`.
<!-- {
"args": ["&#45;&#45;help"],
"output": "A new cli application"
} -->
``` go ``` go
package main package main
import ( import (
"os" "os"
"github.com/urfave/cli" "github.com/urfave/cli"
) )
@ -101,7 +114,8 @@ func main() {
} }
``` ```
This app will run and show help text, but is not very useful. Let's give an action to execute and some help documentation: This app will run and show help text, but is not very useful. Let's give an
action to execute and some help documentation:
<!-- { <!-- {
"output": "boom! I say!" "output": "boom! I say!"
@ -129,13 +143,17 @@ func main() {
} }
``` ```
Running this already gives you a ton of functionality, plus support for things like subcommands and flags, which are covered below. Running this already gives you a ton of functionality, plus support for things
like subcommands and flags, which are covered below.
## Example ## Examples
Being a programmer can be a lonely job. Thankfully by the power of automation that is not the case! Let's create a greeter app to fend off our demons of loneliness! Being a programmer can be a lonely job. Thankfully by the power of automation
that is not the case! Let's create a greeter app to fend off our demons of
loneliness!
Start by creating a directory named `greet`, and within it, add a file, `greet.go` with the following code in it: Start by creating a directory named `greet`, and within it, add a file,
`greet.go` with the following code in it:
<!-- { <!-- {
"output": "Hello friend!" "output": "Hello friend!"
@ -198,86 +216,158 @@ GLOBAL OPTIONS
### Arguments ### Arguments
You can lookup arguments by calling the `Args` function on `cli.Context`. You can lookup arguments by calling the `Args` function on `cli.Context`, e.g.:
<!-- {
"output": "Hello \""
} -->
``` go ``` go
... package main
app.Action = func(c *cli.Context) error {
fmt.Println("Hello", c.Args()[0]) import (
return nil "fmt"
"os"
"github.com/urfave/cli"
)
func main() {
app := cli.NewApp()
app.Action = func(c *cli.Context) error {
fmt.Printf("Hello %q", c.Args().Get(0))
return nil
}
app.Run(os.Args)
} }
...
``` ```
### Flags ### Flags
Setting and querying flags is simple. Setting and querying flags is simple.
<!-- {
"output": "Hello Nefertiti"
} -->
``` go ``` go
... package main
app.Flags = []cli.Flag {
cli.StringFlag{ import (
Name: "lang", "fmt"
Value: "english", "os"
Usage: "language for the greeting",
}, "github.com/urfave/cli"
} )
app.Action = func(c *cli.Context) error {
name := "someone" func main() {
if c.NArg() > 0 { app := cli.NewApp()
name = c.Args()[0]
app.Flags = []cli.Flag {
cli.StringFlag{
Name: "lang",
Value: "english",
Usage: "language for the greeting",
},
} }
if c.String("lang") == "spanish" {
fmt.Println("Hola", name) app.Action = func(c *cli.Context) error {
} else { name := "Nefertiti"
fmt.Println("Hello", name) if c.NArg() > 0 {
name = c.Args().Get(0)
}
if c.String("lang") == "spanish" {
fmt.Println("Hola", name)
} else {
fmt.Println("Hello", name)
}
return nil
} }
return nil
app.Run(os.Args)
} }
...
``` ```
You can also set a destination variable for a flag, to which the content will be scanned. You can also set a destination variable for a flag, to which the content will be
scanned.
<!-- {
"output": "Hello someone"
} -->
``` go ``` go
... package main
var language string
app.Flags = []cli.Flag { import (
cli.StringFlag{ "os"
Name: "lang", "fmt"
Value: "english",
Usage: "language for the greeting", "github.com/urfave/cli"
Destination: &language, )
},
} func main() {
app.Action = func(c *cli.Context) error { var language string
name := "someone"
if c.NArg() > 0 { app := cli.NewApp()
name = c.Args()[0]
app.Flags = []cli.Flag {
cli.StringFlag{
Name: "lang",
Value: "english",
Usage: "language for the greeting",
Destination: &language,
},
} }
if language == "spanish" {
fmt.Println("Hola", name) app.Action = func(c *cli.Context) error {
} else { name := "someone"
fmt.Println("Hello", name) if c.NArg() > 0 {
name = c.Args()[0]
}
if language == "spanish" {
fmt.Println("Hola", name)
} else {
fmt.Println("Hello", name)
}
return nil
} }
return nil
app.Run(os.Args)
} }
...
``` ```
See full list of flags at http://godoc.org/github.com/urfave/cli See full list of flags at http://godoc.org/github.com/urfave/cli
#### Placeholder Values #### Placeholder Values
Sometimes it's useful to specify a flag's value within the usage string itself. Such placeholders are Sometimes it's useful to specify a flag's value within the usage string itself.
indicated with back quotes. Such placeholders are indicated with back quotes.
For example this: For example this:
<!-- {
"args": ["&#45;&#45;help"],
"output": "&#45;&#45;config FILE, &#45;c FILE"
} -->
```go ```go
cli.StringFlag{ package main
Name: "config, c",
Usage: "Load configuration from `FILE`", import (
"os"
"github.com/urfave/cli"
)
func main() {
app := cli.NewApp()
app.Flags = []cli.Flag{
cli.StringFlag{
Name: "config, c",
Usage: "Load configuration from `FILE`",
},
}
app.Run(os.Args)
} }
``` ```
@ -287,145 +377,244 @@ Will result in help output like:
--config FILE, -c FILE Load configuration from FILE --config FILE, -c FILE Load configuration from FILE
``` ```
Note that only the first placeholder is used. Subsequent back-quoted words will be left as-is. Note that only the first placeholder is used. Subsequent back-quoted words will
be left as-is.
#### Alternate Names #### Alternate Names
You can set alternate (or short) names for flags by providing a comma-delimited list for the `Name`. e.g. You can set alternate (or short) names for flags by providing a comma-delimited
list for the `Name`. e.g.
<!-- {
"args": ["&#45;&#45;help"],
"output": "&#45;&#45;lang value, &#45;l value.*language for the greeting.*default: \"english\""
} -->
``` go ``` go
app.Flags = []cli.Flag { package main
cli.StringFlag{
Name: "lang, l", import (
Value: "english", "os"
Usage: "language for the greeting",
}, "github.com/urfave/cli"
)
func main() {
app := cli.NewApp()
app.Flags = []cli.Flag {
cli.StringFlag{
Name: "lang, l",
Value: "english",
Usage: "language for the greeting",
},
}
app.Run(os.Args)
} }
``` ```
That flag can then be set with `--lang spanish` or `-l spanish`. Note that giving two different forms of the same flag in the same command invocation is an error. That flag can then be set with `--lang spanish` or `-l spanish`. Note that
giving two different forms of the same flag in the same command invocation is an
error.
#### Values from the Environment #### Values from the Environment
You can also have the default value set from the environment via `EnvVar`. e.g. You can also have the default value set from the environment via `EnvVar`. e.g.
<!-- {
"args": ["&#45;&#45;help"],
"output": "language for the greeting.*APP_LANG"
} -->
``` go ``` go
app.Flags = []cli.Flag { package main
cli.StringFlag{
Name: "lang, l", import (
Value: "english", "os"
Usage: "language for the greeting",
EnvVar: "APP_LANG", "github.com/urfave/cli"
}, )
func main() {
app := cli.NewApp()
app.Flags = []cli.Flag {
cli.StringFlag{
Name: "lang, l",
Value: "english",
Usage: "language for the greeting",
EnvVar: "APP_LANG",
},
}
app.Run(os.Args)
} }
``` ```
The `EnvVar` may also be given as a comma-delimited "cascade", where the first environment variable that resolves is used as the default. The `EnvVar` may also be given as a comma-delimited "cascade", where the first
environment variable that resolves is used as the default.
<!-- {
"args": ["&#45;&#45;help"],
"output": "language for the greeting.*LEGACY_COMPAT_LANG.*APP_LANG.*LANG"
} -->
``` go ``` go
app.Flags = []cli.Flag { package main
cli.StringFlag{
Name: "lang, l", import (
Value: "english", "os"
Usage: "language for the greeting",
EnvVar: "LEGACY_COMPAT_LANG,APP_LANG,LANG", "github.com/urfave/cli"
}, )
func main() {
app := cli.NewApp()
app.Flags = []cli.Flag {
cli.StringFlag{
Name: "lang, l",
Value: "english",
Usage: "language for the greeting",
EnvVar: "LEGACY_COMPAT_LANG,APP_LANG,LANG",
},
}
app.Run(os.Args)
} }
``` ```
#### Values from alternate input sources (YAML and others) #### Values from alternate input sources (YAML and others)
There is a separate package altsrc that adds support for getting flag values from other input sources like YAML. There is a separate package altsrc that adds support for getting flag values
from other input sources like YAML.
In order to get values for a flag from an alternate input source the following code would be added to wrap an existing cli.Flag like below: In order to get values for a flag from an alternate input source the following
code would be added to wrap an existing cli.Flag like below:
``` go ``` go
altsrc.NewIntFlag(cli.IntFlag{Name: "test"}) altsrc.NewIntFlag(cli.IntFlag{Name: "test"})
``` ```
Initialization must also occur for these flags. Below is an example initializing getting data from a yaml file below. Initialization must also occur for these flags. Below is an example initializing
getting data from a yaml file below.
``` go ``` go
command.Before = altsrc.InitInputSourceWithContext(command.Flags, NewYamlSourceFromFlagFunc("load")) command.Before = altsrc.InitInputSourceWithContext(command.Flags, NewYamlSourceFromFlagFunc("load"))
``` ```
The code above will use the "load" string as a flag name to get the file name of a yaml file from the cli.Context. The code above will use the "load" string as a flag name to get the file name of
It will then use that file name to initialize the yaml input source for any flags that are defined on that command. a yaml file from the cli.Context. It will then use that file name to initialize
As a note the "load" flag used would also have to be defined on the command flags in order for this code snipped to work. the yaml input source for any flags that are defined on that command. As a note
the "load" flag used would also have to be defined on the command flags in order
for this code snipped to work.
Currently only YAML files are supported but developers can add support for other input sources by implementing the Currently only YAML files are supported but developers can add support for other
altsrc.InputSourceContext for their given sources. input sources by implementing the altsrc.InputSourceContext for their given
sources.
Here is a more complete sample of a command using YAML support: Here is a more complete sample of a command using YAML support:
<!-- {
"args": ["test-cmd", "&#45;&#45;help"],
"output": "&#45&#45;test value.*default: 0"
} -->
``` go ``` go
command := &cli.Command{ package notmain
Name: "test-cmd",
Aliases: []string{"tc"}, import (
Usage: "this is for testing", "fmt"
Description: "testing", "os"
Action: func(c *cli.Context) error {
// Action to run "github.com/urfave/cli"
return nil "github.com/urfave/cli/altsrc"
}, )
Flags: []cli.Flag{
NewIntFlag(cli.IntFlag{Name: "test"}), func main() {
cli.StringFlag{Name: "load"}}, app := cli.NewApp()
flags := []cli.Flag{
altsrc.NewIntFlag(cli.IntFlag{Name: "test"}),
cli.StringFlag{Name: "load"},
} }
command.Before = InitInputSourceWithContext(command.Flags, NewYamlSourceFromFlagFunc("load"))
err := command.Run(c) app.Action = func(c *cli.Context) error {
fmt.Println("yaml ist rad")
return nil
}
app.Before = altsrc.InitInputSourceWithContext(flags, altsrc.NewYamlSourceFromFlagFunc("load"))
app.Flags = flags
app.Run(os.Args)
}
``` ```
### Subcommands ### Subcommands
Subcommands can be defined for a more git-like command line app. Subcommands can be defined for a more git-like command line app.
<!-- {
"args": ["template", "add"],
"output": "new task template: .+"
} -->
```go ```go
... package main
app.Commands = []cli.Command{
{ import (
Name: "add", "fmt"
Aliases: []string{"a"}, "os"
Usage: "add a task to the list",
Action: func(c *cli.Context) error { "github.com/urfave/cli"
fmt.Println("added task: ", c.Args().First()) )
return nil
}, func main() {
}, app := cli.NewApp()
{
Name: "complete", app.Commands = []cli.Command{
Aliases: []string{"c"}, {
Usage: "complete a task on the list", Name: "add",
Action: func(c *cli.Context) error { Aliases: []string{"a"},
fmt.Println("completed task: ", c.Args().First()) Usage: "add a task to the list",
return nil Action: func(c *cli.Context) error {
}, fmt.Println("added task: ", c.Args().First())
}, return nil
{
Name: "template",
Aliases: []string{"r"},
Usage: "options for task templates",
Subcommands: []cli.Command{
{
Name: "add",
Usage: "add a new template",
Action: func(c *cli.Context) error {
fmt.Println("new task template: ", c.Args().First())
return nil
},
}, },
{ },
Name: "remove", {
Usage: "remove an existing template", Name: "complete",
Action: func(c *cli.Context) error { Aliases: []string{"c"},
fmt.Println("removed task template: ", c.Args().First()) Usage: "complete a task on the list",
return nil Action: func(c *cli.Context) error {
fmt.Println("completed task: ", c.Args().First())
return nil
},
},
{
Name: "template",
Aliases: []string{"t"},
Usage: "options for task templates",
Subcommands: []cli.Command{
{
Name: "add",
Usage: "add a new template",
Action: func(c *cli.Context) error {
fmt.Println("new task template: ", c.Args().First())
return nil
},
},
{
Name: "remove",
Usage: "remove an existing template",
Action: func(c *cli.Context) error {
fmt.Println("removed task template: ", c.Args().First())
return nil
},
}, },
}, },
}, },
}, }
app.Run(os.Args)
} }
...
``` ```
### Subcommands categories ### Subcommands categories
@ -437,7 +626,17 @@ output.
E.g. E.g.
```go ```go
... package main
import (
"os"
"github.com/urfave/cli"
)
func main() {
app := cli.NewApp()
app.Commands = []cli.Command{ app.Commands = []cli.Command{
{ {
Name: "noop", Name: "noop",
@ -451,20 +650,20 @@ E.g.
Category: "template", Category: "template",
}, },
} }
...
app.Run(os.Args)
}
``` ```
Will include: Will include:
``` ```
...
COMMANDS: COMMANDS:
noop noop
Template actions: Template actions:
add add
remove remove
...
``` ```
### Exit code ### Exit code
@ -509,32 +708,48 @@ flag on the `App` object. By default, this setting will only auto-complete to
show an app's subcommands, but you can write your own completion methods for show an app's subcommands, but you can write your own completion methods for
the App or its subcommands. the App or its subcommands.
```go <!-- {
... "args": ["complete", "&#45;&#45;generate&#45;bash&#45;completion"],
var tasks = []string{"cook", "clean", "laundry", "eat", "sleep", "code"} "output": "laundry"
app := cli.NewApp() } -->
app.EnableBashCompletion = true ``` go
app.Commands = []cli.Command{ package main
{
Name: "complete", import (
Aliases: []string{"c"}, "fmt"
Usage: "complete a task on the list", "os"
Action: func(c *cli.Context) error {
fmt.Println("completed task: ", c.Args().First()) "github.com/urfave/cli"
return nil )
},
BashComplete: func(c *cli.Context) { func main() {
// This will complete if no args are passed tasks := []string{"cook", "clean", "laundry", "eat", "sleep", "code"}
if c.NArg() > 0 {
return app := cli.NewApp()
} app.EnableBashCompletion = true
for _, t := range tasks { app.Commands = []cli.Command{
fmt.Println(t) {
} Name: "complete",
Aliases: []string{"c"},
Usage: "complete a task on the list",
Action: func(c *cli.Context) error {
fmt.Println("completed task: ", c.Args().First())
return nil
},
BashComplete: func(c *cli.Context) {
// This will complete if no args are passed
if c.NArg() > 0 {
return
}
for _, t := range tasks {
fmt.Println(t)
}
},
}, },
} }
app.Run(os.Args)
} }
...
``` ```
#### To Enable #### To Enable