golang命令列庫cobra的使用

簡介

Cobra既是一個用來建立強大的現代CLI命令列的golang庫，也是一個產生程式應用和命令列檔案的程式。下面是Cobra使用的一個示範：

Cobra提供的功能

• 簡易的子命令列模式，如 app server， app fetch等等
• 完全相容posix命令列模式
• 嵌套子命令subcommand
• 支援全域，局部，串聯flags
• 使用Cobra很容易的產生應用程式和命令，使用cobra create appname和cobra add cmdname
• 如果命令輸入錯誤，將提供智能建議，如 app srver，將提示srver沒有，是否是app server
• 自動產生commands和flags的協助資訊
• 自動產生詳細的help資訊，如app help
• 自動識別-h，--help協助flag
• 自動產生應用程式在bash下命令自動完成功能
• 自動產生應用程式的man手冊
• 命令列別名
• 自訂help和usage資訊
• 可選的緊密整合的viper apps

如何使用

上面所有列出的功能我沒有一一去使用，下面我來簡單介紹一下如何使用Cobra，基本能夠滿足一般命令列程式的需求，如果需要更多功能，可以研究一下源碼github。

安裝cobra

Cobra是非常容易使用的，使用go get來安裝最新版本的庫。當然這個庫還是相對比較大的，可能需要安裝它可能需要相當長的時間，這取決於你的速網。安裝完成後，開啟GOPATH目錄，bin目錄下應該有已經編譯好的cobra.exe程式，當然你也可以使用原始碼自己產生一個最新的cobra程式。

> go get -v github.com/spf13/cobra/cobra

使用cobra產生應用程式

假設現在我們要開發一個基於CLIs的命令程式，名字為demo。首先開啟CMD，切換到GOPATH的src目錄下[^1]，執行如下指令：
[^1]:cobra.exe只能在GOPATH目錄下執行

src> ..\bin\cobra.exe init demo Your Cobra application is ready atC:\Users\liubo5\Desktop\transcoding_tool\src\demoGive it a try by going there and running `go run main.go`Add commands to it by running `cobra add [cmdname]`

在src目錄下會產生一個demo的檔案夾，如下：

▾ demo    ▾ cmd/        root.go    main.go

如果你的demo程式沒有subcommands，那麼cobra產生應用程式的操作就結束了。

如何?沒有子命令的CLIs程式

接下來就是可以繼續demo的功能設計了。例如我在demo下面建立一個包，名稱為imp。如下：

▾ demo    ▾ cmd/        root.go    ▾ imp/        imp.go        imp_test.go    main.go

imp.go檔案的代碼如下：

package impimport(    "fmt")func Show(name string, age int) {    fmt.Printf("My Name is %s, My age is %d\n", name, age)}

demo程式成命令列接收兩個參數name和age，然後列印出來。開啟cobra自動產生的main.go檔案查看：

// Copyright  2016 NAME HERE <EMAIL ADDRESS>//// Licensed under the Apache License, Version 2.0 (the "License");// you may not use this file except in compliance with the License.// You may obtain a copy of the License at////     http://www.apache.org/licenses/LICENSE-2.0//// Unless required by applicable law or agreed to in writing, software// distributed under the License is distributed on an "AS IS" BASIS,// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.// See the License for the specific language governing permissions and// limitations under the License.package mainimport "demo/cmd"func main() {    cmd.Execute()}

可以看出main函數執行cmd包，所以我們只需要在cmd包內調用imp包就能實現demo程式的需求。接著開啟root.go檔案查看：

// Copyright  2016 NAME HERE <EMAIL ADDRESS>//// Licensed under the Apache License, Version 2.0 (the "License");// you may not use this file except in compliance with the License.// You may obtain a copy of the License at////     http://www.apache.org/licenses/LICENSE-2.0//// Unless required by applicable law or agreed to in writing, software// distributed under the License is distributed on an "AS IS" BASIS,// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.// See the License for the specific language governing permissions and// limitations under the License.package cmdimport (    "fmt"    "os"    "github.com/spf13/cobra"    "github.com/spf13/viper")var cfgFile string// RootCmd represents the base command when called without any subcommandsvar RootCmd = &cobra.Command{    Use:   "demo",    Short: "A brief description of your application",    Long: `A longer description that spans multiple lines and likely containsexamples and usage of using your application. For example:Cobra is a CLI library for Go that empowers applications.This application is a tool to generate the needed filesto quickly create a Cobra application.`,// Uncomment the following line if your bare application// has an action associated with it://  Run: func(cmd *cobra.Command, args []string) { },}// Execute adds all child commands to the root command sets flags appropriately.// This is called by main.main(). It only needs to happen once to the rootCmd.func Execute() {    if err := RootCmd.Execute(); err != nil {        fmt.Println(err)        os.Exit(-1)    }}func init() {    cobra.OnInitialize(initConfig)    // Here you will define your flags and configuration settings.    // Cobra supports Persistent Flags, which, if defined here,    // will be global for your application.    RootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.demo.yaml)")    // Cobra also supports local flags, which will only run    // when this action is called directly.    RootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")}// initConfig reads in config file and ENV variables if set.func initConfig() {    if cfgFile != "" { // enable ability to specify config file via flag        viper.SetConfigFile(cfgFile)    }    viper.SetConfigName(".demo") // name of config file (without extension)    viper.AddConfigPath("$HOME")  // adding home directory as first search path    viper.AutomaticEnv()          // read in environment variables that match    // If a config file is found, read it in.    if err := viper.ReadInConfig(); err == nil {        fmt.Println("Using config file:", viper.ConfigFileUsed())    }}

從原始碼來看cmd包進行了一些初始化操作並提供了Execute介面。十分簡單，其中viper是cobra整合的設定檔讀取的庫，這裡不需要使用，我們可以注釋掉（不注釋可能產生的應用程式很大約10M，這裡沒喲用到最好是注釋掉）。cobra的所有命令都是通過cobra.Command這個結構體實現的。為了實現demo功能，顯然我們需要修改RootCmd。修改後的代碼如下：

// Copyright  2016 NAME HERE <EMAIL ADDRESS>//// Licensed under the Apache License, Version 2.0 (the "License");// you may not use this file except in compliance with the License.// You may obtain a copy of the License at////     http://www.apache.org/licenses/LICENSE-2.0//// Unless required by applicable law or agreed to in writing, software// distributed under the License is distributed on an "AS IS" BASIS,// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.// See the License for the specific language governing permissions and// limitations under the License.package cmdimport (    "fmt"    "os"    "github.com/spf13/cobra"    //  "github.com/spf13/viper"    "demo/imp")//var cfgFile stringvar name stringvar age int// RootCmd represents the base command when called without any subcommandsvar RootCmd = &cobra.Command{    Use:   "demo",    Short: "A test demo",    Long:  `Demo is a test appcation for print things`,    // Uncomment the following line if your bare application    // has an action associated with it:    Run: func(cmd *cobra.Command, args []string) {        if len(name) == 0 {            cmd.Help()            return        }        imp.Show(name, age)    },}// Execute adds all child commands to the root command sets flags appropriately.// This is called by main.main(). It only needs to happen once to the rootCmd.func Execute() {    if err := RootCmd.Execute(); err != nil {        fmt.Println(err)        os.Exit(-1)    }}func init() {    //  cobra.OnInitialize(initConfig)    // Here you will define your flags and configuration settings.    // Cobra supports Persistent Flags, which, if defined here,    // will be global for your application.    //  RootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.demo.yaml)")    // Cobra also supports local flags, which will only run    // when this action is called directly.    //  RootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")    RootCmd.Flags().StringVarP(&name, "name", "n", "", "person's name")    RootCmd.Flags().IntVarP(&age, "age", "a", 0, "person's age")}// initConfig reads in config file and ENV variables if set.//func initConfig() {//  if cfgFile != "" { // enable ability to specify config file via flag//      viper.SetConfigFile(cfgFile)//  }//  viper.SetConfigName(".demo") // name of config file (without extension)//  viper.AddConfigPath("$HOME") // adding home directory as first search path//  viper.AutomaticEnv()         // read in environment variables that match//  // If a config file is found, read it in.//  if err := viper.ReadInConfig(); err == nil {//      fmt.Println("Using config file:", viper.ConfigFileUsed())//  }//}

到此demo的功能已經實現了，我們編譯運行一下看看實際效果：

>demo.exeDemo is a test appcation for print thingsUsage:  demo [flags]Flags:  -a, --age int       person's age  -h, --help          help for demo  -n, --name string   person's name

>demo -n borey --age 26My Name is borey, My age is 26

如何?帶有子命令的CLIs程式

在執行cobra.exe init demo之後，繼續使用cobra為demo添加子命令test：

src\demo>..\..\bin\cobra add testtest created at C:\Users\liubo5\Desktop\transcoding_tool\src\demo\cmd\test.go

在src目錄下demo的檔案夾下產生了一個cmd\test.go檔案，如下：

▾ demo    ▾ cmd/        root.go        test.go    main.go

接下來的操作就和上面修改root.go檔案一樣去配置test子命令。效果如下：

src\demo>demoDemo is a test appcation for print thingsUsage:  demo [flags]  demo [command]Available Commands:  test        A brief description of your commandFlags:  -a, --age int       person's age  -h, --help          help for demo  -n, --name string   person's nameUse "demo [command] --help" for more information about a command.

可以看出demo既支援直接使用標記flag，又能使用子命令

src\demo>demo test -hA longer description that spans multiple lines and likely contains examplesand usage of using your command. For example:Cobra is a CLI library for Go that empowers applications.This application is a tool to generate the needed filesto quickly create a Cobra application.Usage:  demo test [flags]

調用test命令輸出資訊，這裡沒有對預設資訊進行修改。

src\demo>demo tstError: unknown command "tst" for "demo"Did you mean this?        testRun 'demo --help' for usage.unknown command "tst" for "demo"Did you mean this?        test

這是錯誤命令提示功能

OVER

Cobra的使用就介紹到這裡，更新細節可去github詳細研究一下。這裡只是一個簡單的使用入門介紹，如果有錯誤之處，敬請指出，謝謝～