Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1453 from hay-kot/main
docs: split documentation into individual pages
- Loading branch information
Showing
35 changed files
with
3,356 additions
and
3,185 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
--- | ||
tags: | ||
- v1 | ||
--- | ||
|
||
You can lookup arguments by calling the `Args` function on `cli.Context`, e.g.: | ||
|
||
<!-- { | ||
"output": "Hello \"" | ||
} --> | ||
``` go | ||
package main | ||
|
||
import ( | ||
"fmt" | ||
"log" | ||
"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 | ||
} | ||
|
||
err := app.Run(os.Args) | ||
if err != nil { | ||
log.Fatal(err) | ||
} | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,119 @@ | ||
--- | ||
tags: | ||
- v1 | ||
--- | ||
|
||
You can enable completion commands by setting the `EnableBashCompletion` | ||
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 | ||
the App or its subcommands. | ||
|
||
<!-- { | ||
"args": ["complete", "--generate-bash-completion"], | ||
"output": "laundry" | ||
} --> | ||
``` go | ||
package main | ||
|
||
import ( | ||
"fmt" | ||
"log" | ||
"os" | ||
|
||
"github.com/urfave/cli" | ||
) | ||
|
||
func main() { | ||
tasks := []string{"cook", "clean", "laundry", "eat", "sleep", "code"} | ||
|
||
app := cli.NewApp() | ||
app.EnableBashCompletion = true | ||
app.Commands = []cli.Command{ | ||
{ | ||
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) | ||
} | ||
}, | ||
}, | ||
} | ||
|
||
err := app.Run(os.Args) | ||
if err != nil { | ||
log.Fatal(err) | ||
} | ||
} | ||
``` | ||
|
||
#### Enabling | ||
|
||
Source the `autocomplete/bash_autocomplete` file in your `.bashrc` file while | ||
setting the `PROG` variable to the name of your program: | ||
|
||
`PROG=myprogram source /.../cli/autocomplete/bash_autocomplete` | ||
|
||
#### Distribution | ||
|
||
Copy `autocomplete/bash_autocomplete` into `/etc/bash_completion.d/` and rename | ||
it to the name of the program you wish to add autocomplete support for (or | ||
automatically install it there if you are distributing a package). Don't forget | ||
to source the file to make it active in the current shell. | ||
|
||
``` | ||
sudo cp src/bash_autocomplete /etc/bash_completion.d/<myprogram> | ||
source /etc/bash_completion.d/<myprogram> | ||
``` | ||
|
||
Alternatively, you can just document that users should source the generic | ||
`autocomplete/bash_autocomplete` in their bash configuration with `$PROG` set | ||
to the name of their program (as above). | ||
|
||
#### Customization | ||
|
||
The default bash completion flag (`--generate-bash-completion`) is defined as | ||
`cli.BashCompletionFlag`, and may be redefined if desired, e.g.: | ||
|
||
<!-- { | ||
"args": ["--compgen"], | ||
"output": "wat\nhelp\nh" | ||
} --> | ||
``` go | ||
package main | ||
|
||
import ( | ||
"log" | ||
"os" | ||
|
||
"github.com/urfave/cli" | ||
) | ||
|
||
func main() { | ||
cli.BashCompletionFlag = cli.BoolFlag{ | ||
Name: "compgen", | ||
Hidden: true, | ||
} | ||
|
||
app := cli.NewApp() | ||
app.EnableBashCompletion = true | ||
app.Commands = []cli.Command{ | ||
{ | ||
Name: "wat", | ||
}, | ||
} | ||
err := app.Run(os.Args) | ||
if err != nil { | ||
log.Fatal(err) | ||
} | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,72 @@ | ||
--- | ||
tags: | ||
- v1 | ||
--- | ||
|
||
Traditional use of options using their shortnames look like this: | ||
|
||
``` | ||
$ cmd -s -o -m "Some message" | ||
``` | ||
|
||
Suppose you want users to be able to combine options with their shortnames. This | ||
can be done using the `UseShortOptionHandling` bool in your app configuration, | ||
or for individual commands by attaching it to the command configuration. For | ||
example: | ||
|
||
<!-- { | ||
"args": ["short", "-som", "Some message"], | ||
"output": "serve: true\noption: true\nmessage: Some message\n" | ||
} --> | ||
``` go | ||
package main | ||
|
||
import ( | ||
"fmt" | ||
"log" | ||
"os" | ||
|
||
"github.com/urfave/cli" | ||
) | ||
|
||
func main() { | ||
app := cli.NewApp() | ||
app.UseShortOptionHandling = true | ||
app.Commands = []cli.Command{ | ||
{ | ||
Name: "short", | ||
Usage: "complete a task on the list", | ||
Flags: []cli.Flag{ | ||
cli.BoolFlag{Name: "serve, s"}, | ||
cli.BoolFlag{Name: "option, o"}, | ||
cli.StringFlag{Name: "message, m"}, | ||
}, | ||
Action: func(c *cli.Context) error { | ||
fmt.Println("serve:", c.Bool("serve")) | ||
fmt.Println("option:", c.Bool("option")) | ||
fmt.Println("message:", c.String("message")) | ||
return nil | ||
}, | ||
}, | ||
} | ||
|
||
err := app.Run(os.Args) | ||
if err != nil { | ||
log.Fatal(err) | ||
} | ||
} | ||
``` | ||
|
||
If your program has any number of bool flags such as `serve` and `option`, and | ||
optionally one non-bool flag `message`, with the short options of `-s`, `-o`, | ||
and `-m` respectively, setting `UseShortOptionHandling` will also support the | ||
following syntax: | ||
|
||
``` | ||
$ cmd -som "Some message" | ||
``` | ||
|
||
If you enable `UseShortOptionHandling`, then you must not use any flags that | ||
have a single leading `-` or this will result in failures. For example, | ||
`-option` can no longer be used. Flags with two leading dashes (such as | ||
`--options`) are still valid. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
--- | ||
tags: | ||
- v1 | ||
--- | ||
|
||
Calling `App.Run` will not automatically call `os.Exit`, which means that by | ||
default the exit code will "fall through" to being `0`. An explicit exit code | ||
may be set by returning a non-nil error that fulfills `cli.ExitCoder`, *or* a | ||
`cli.MultiError` that includes an error that fulfills `cli.ExitCoder`, e.g.: | ||
<!-- { | ||
"error": "Ginger croutons are not in the soup" | ||
} --> | ||
``` go | ||
package main | ||
|
||
import ( | ||
"log" | ||
"os" | ||
|
||
"github.com/urfave/cli" | ||
) | ||
|
||
func main() { | ||
app := cli.NewApp() | ||
app.Flags = []cli.Flag{ | ||
cli.BoolFlag{ | ||
Name: "ginger-crouton", | ||
Usage: "Add ginger croutons to the soup", | ||
}, | ||
} | ||
app.Action = func(ctx *cli.Context) error { | ||
if !ctx.Bool("ginger-crouton") { | ||
return cli.NewExitError("Ginger croutons are not in the soup", 86) | ||
} | ||
return nil | ||
} | ||
|
||
err := app.Run(os.Args) | ||
if err != nil { | ||
log.Fatal(err) | ||
} | ||
} | ||
``` |
Oops, something went wrong.