vinchent/cobra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

changes README to have go code ran through gofmt

Browse Source
This commit is contained in:
Austin Riendeau 2015-11-07 18:37:52 -07:00 committed by spf13
parent 1e1d5137bf
commit d4c0084f5d
1 changed files with 78 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

173
README.md
View File

@ -1,13 +1,13 @@
![cobra logo](https://cloud.githubusercontent.com/assets/173412/10886352/ad566232-814f-11e5-9cd0-aa101788c117.png) ![cobra logo](https://cloud.githubusercontent.com/assets/173412/10886352/ad566232-814f-11e5-9cd0-aa101788c117.png)
Cobra is both a library for creating powerful modern CLI applications as well as a program to generate applications and command files. Cobra is both a library for creating powerful modern CLI applications as well as a program to generate applications and command files.
Many of the most widely used Go projects are built using Cobra including: Many of the most widely used Go projects are built using Cobra including:
* [Kubernetes](http://kubernetes.io/) * [Kubernetes](http://kubernetes.io/)
* [Hugo](http://gohugo.io) * [Hugo](http://gohugo.io)
* [rkt](https://github.com/coreos/rkt) * [rkt](https://github.com/coreos/rkt)
* [Docker (distribution)](https://github.com/docker/distribution) * [Docker (distribution)](https://github.com/docker/distribution)
* [OpenShift](https://www.openshift.com/) * [OpenShift](https://www.openshift.com/)
* [Delve](https://github.com/derekparker/delve) * [Delve](https://github.com/derekparker/delve)
* [GopherJS](http://www.gopherjs.org/) * [GopherJS](http://www.gopherjs.org/)
@ -119,29 +119,33 @@ The root command represents your binary itself.
Cobra doesn't require any special constructors. Simply create your commands. Cobra doesn't require any special constructors. Simply create your commands.
var HugoCmd = &cobra.Command{ ```go
Use: "hugo", var HugoCmd = &cobra.Command{
Short: "Hugo is a very fast static site generator", Use: "hugo",
Long: `A Fast and Flexible Static Site Generator built with Short: "Hugo is a very fast static site generator",
Long: `A Fast and Flexible Static Site Generator built with
love by spf13 and friends in Go. love by spf13 and friends in Go.
Complete documentation is available at http://hugo.spf13.com`, Complete documentation is available at http://hugo.spf13.com`,
Run: func(cmd *cobra.Command, args []string) { Run: func(cmd *cobra.Command, args []string) {
// Do Stuff Here // Do Stuff Here
}, },
} }
```
### Create additional commands ### Create additional commands
Additional commands can be defined. Additional commands can be defined.
var versionCmd = &cobra.Command{ ```go
Use: "version", var versionCmd = &cobra.Command{
Short: "Print the version number of Hugo", Use: "version",
Long: `All software has versions. This is Hugo's`, Short: "Print the version number of Hugo",
Run: func(cmd *cobra.Command, args []string) { Long: `All software has versions. This is Hugo's`,
fmt.Println("Hugo Static Site Generator v0.9 -- HEAD") Run: func(cmd *cobra.Command, args []string) {
}, fmt.Println("Hugo Static Site Generator v0.9 -- HEAD")
} },
}
```
### Attach command to its parent ### Attach command to its parent
In this example we are attaching it to the root, but commands can be attached at any level. In this example we are attaching it to the root, but commands can be attached at any level.
@ -198,59 +202,62 @@ by not providing a 'Run' for the 'rootCmd'.
We have only defined one flag for a single command. We have only defined one flag for a single command.
More documentation about flags is available at https://github.com/spf13/pflag More documentation about flags is available at https://github.com/spf13/pflag
```go
package main
import( import (
"github.com/spf13/cobra" "fmt"
"fmt" "strings"
"strings"
)
func main() { "github.com/spf13/cobra"
)
var echoTimes int func main() {
var cmdPrint = &cobra.Command{ var echoTimes int
Use: "print [string to print]",
Short: "Print anything to the screen", var cmdPrint = &cobra.Command{
Long: `print is for printing anything back to the screen. Use: "print [string to print]",
Short: "Print anything to the screen",
Long: `print is for printing anything back to the screen.
For many years people have printed back to the screen. For many years people have printed back to the screen.
`, `,
Run: func(cmd *cobra.Command, args []string) { Run: func(cmd *cobra.Command, args []string) {
fmt.Println("Print: " + strings.Join(args, " ")) fmt.Println("Print: " + strings.Join(args, " "))
}, },
} }
var cmdEcho = &cobra.Command{ var cmdEcho = &cobra.Command{
Use: "echo [string to echo]", Use: "echo [string to echo]",
Short: "Echo anything to the screen", Short: "Echo anything to the screen",
Long: `echo is for echoing anything back. Long: `echo is for echoing anything back.
Echo works a lot like print, except it has a child command. Echo works a lot like print, except it has a child command.
`, `,
Run: func(cmd *cobra.Command, args []string) { Run: func(cmd *cobra.Command, args []string) {
fmt.Println("Print: " + strings.Join(args, " ")) fmt.Println("Print: " + strings.Join(args, " "))
}, },
} }
var cmdTimes = &cobra.Command{ var cmdTimes = &cobra.Command{
Use: "times [# times] [string to echo]", Use: "times [# times] [string to echo]",
Short: "Echo anything to the screen more times", Short: "Echo anything to the screen more times",
Long: `echo things multiple times back to the user by providing Long: `echo things multiple times back to the user by providing
a count and a string.`, a count and a string.`,
Run: func(cmd *cobra.Command, args []string) { Run: func(cmd *cobra.Command, args []string) {
for i:=0; i < echoTimes; i++ { for i := 0; i < echoTimes; i++ {
fmt.Println("Echo: " + strings.Join(args, " ")) fmt.Println("Echo: " + strings.Join(args, " "))
} }
}, },
} }
cmdTimes.Flags().IntVarP(&echoTimes, "times", "t", 1, "times to echo the input") cmdTimes.Flags().IntVarP(&echoTimes, "times", "t", 1, "times to echo the input")
var rootCmd = &cobra.Command{Use: "app"}
rootCmd.AddCommand(cmdPrint, cmdEcho)
cmdEcho.AddCommand(cmdTimes)
rootCmd.Execute()
}
var rootCmd = &cobra.Command{Use: "app"}
rootCmd.AddCommand(cmdPrint, cmdEcho)
cmdEcho.AddCommand(cmdTimes)
rootCmd.Execute()
}
```
For a more complete example of a larger application, please checkout [Hugo](http://hugo.spf13.com) For a more complete example of a larger application, please checkout [Hugo](http://hugo.spf13.com)
## The Help Command ## The Help Command
@ -308,18 +315,20 @@ You can provide your own Help command or you own template for the default comman
The default help command is The default help command is
func (c *Command) initHelp() { ```go
if c.helpCommand == nil { func (c *Command) initHelp() {
c.helpCommand = &Command{ if c.helpCommand == nil {
Use: "help [command]", c.helpCommand = &Command{
Short: "Help about any command", Use: "help [command]",
Long: `Help provides help for any command in the application. Short: "Help about any command",
Long: `Help provides help for any command in the application.
Simply type ` + c.Name() + ` help [path to command] for full details.`, Simply type ` + c.Name() + ` help [path to command] for full details.`,
Run: c.HelpFunc(), Run: c.HelpFunc(),
} }
} }
c.AddCommand(c.helpCommand) c.AddCommand(c.helpCommand)
} }
```
You can provide your own command, function or template through the following methods. You can provide your own command, function or template through the following methods.
@ -462,32 +471,6 @@ Cobra also has functions where the return signature is an error. This allows for
**Example Usage using RunE:** **Example Usage using RunE:**
```go ```go
package main
import (
"errors"
"log"
"github.com/spf13/cobra"
)
func main() {
var rootCmd = &cobra.Command{
Use: "hugo",
Short: "Hugo is a very fast static site generator",
Long: `A Fast and Flexible Static Site Generator built with
love by spf13 and friends in Go.
Complete documentation is available at http://hugo.spf13.com`,
RunE: func(cmd *cobra.Command, args []string) error {
// Do Stuff Here
return errors.New("some random error")
},
}
if err := rootCmd.Execute(); err != nil {
log.Fatal(err)
}
}
``` ```
## Suggestions when "unknown command" happens ## Suggestions when "unknown command" happens