基於 cmdr v1.0.3
從 golang
flag遷移到cmdr
採用一個新的命令列直譯器框架，最痛苦地莫過於編寫資料結構或者流式定義了。我們首先回顧一下 cmdr 和其它大多數三方增強命令列直譯器都支援的最典型的兩種命令列介面定義方式，然後再來研究一下 cmdr 新增的最平滑的遷移方案。
典型的方式
通過結構資料體定義
有的增強工具（例如 cobra, viper）採用結構體資料定義方式來完成介面指定，如同 cmdr 的這樣：
rootCmd = &cmdr.RootCommand{
Command: cmdr.Command{
BaseOpt: cmdr.BaseOpt{
Name: appName,
Description: desc,
LongDescription: longDesc,
Examples: examples,
},
Flags: []*cmdr.Flag{},
SubCommands: []*cmdr.Command{
// generatorCommands,
// serverCommands,
msCommands,
testCommands,
{
BaseOpt: cmdr.BaseOpt{
Short: "xy",
Full: "xy-print",
Description: `test terminal control sequences`,
Action: func(cmd *cmdr.Command, args []string) (err error) {
fmt.Println("\x1b[2J") // clear screen
for i, s := range args {
fmt.Printf("\x1b[s\x1b[%d;%dH%s\x1b[u", 15+i, 30, s)
}
return
},
},
},
{
BaseOpt: cmdr.BaseOpt{
Short: "mx",
Full: "mx-test",
Description: `test new features`,
Action: func(cmd *cmdr.Command, args []string) (err error) {
fmt.Printf("*** Got pp: %s\n", cmdr.GetString("app.mx-test.password"))
fmt.Printf("*** Got msg: %s\n", cmdr.GetString("app.mx-test.message"))
return
},
},
Flags: []*cmdr.Flag{
{
BaseOpt: cmdr.BaseOpt{
Short: "pp",
Full: "password",
Description: "the password requesting.",
},
DefaultValue: "",
ExternalTool: cmdr.ExternalToolPasswordInput,
},
{
BaseOpt: cmdr.BaseOpt{
Short: "m",
Full: "message",
Description: "the message requesting.",
},
DefaultValue: "",
ExternalTool: cmdr.ExternalToolEditor,
},
},
},
},
},
AppName: appName,
Version: cmdr.Version,
VersionInt: cmdr.VersionInt,
Copyright: copyright,
Author: "xxx <xxx@gmail.com>",
}
//... More
複製程式碼它的問題在於，如果你有 docker 那樣的較多的子命令以及選項需要安排的話，這個方案會相當難定位，寫起來也很痛苦，改起來更痛苦。
通過流式呼叫鏈方式定義
比結構體資料定義方案更好一點的是採用流式呼叫鏈方式。它可能長得像這樣：
// root
root := cmdr.Root(appName, "1.0.1").
Header("fluent - test for cmdr - no version - hedzr").
Description(desc, longDesc).
Examples(examples)
rootCmd = root.RootCommand()
// soundex
root.NewSubCommand().
Titles("snd", "soundex", "sndx", "sound").
Description("", "soundex test").
Group("Test").
Action(func(cmd *cmdr.Command, args []string) (err error) {
for ix, s := range args {
fmt.Printf("%5d. %s => %s\n", ix, s, cmdr.Soundex(s))
}
return
})
// xy-print
root.NewSubCommand().
Titles("xy", "xy-print").
Description("test terminal control sequences", "test terminal control sequences,\nverbose long descriptions here.").
Group("Test").
Action(func(cmd *cmdr.Command, args []string) (err error) {
fmt.Println("\x1b[2J") // clear screen
for i, s := range args {
fmt.Printf("\x1b[s\x1b[%d;%dH%s\x1b[u", 15+i, 30, s)
}
return
})
// mx-test
mx := root.NewSubCommand().
Titles("mx", "mx-test").
Description("test new features", "test new features,\nverbose long descriptions here.").
Group("Test").
Action(func(cmd *cmdr.Command, args []string) (err error) {
fmt.Printf("*** Got pp: %s\n", cmdr.GetString("app.mx-test.password"))
fmt.Printf("*** Got msg: %s\n", cmdr.GetString("app.mx-test.message"))
fmt.Printf("*** Got fruit: %v\n", cmdr.GetString("app.mx-test.fruit"))
fmt.Printf("*** Got head: %v\n", cmdr.GetInt("app.mx-test.head"))
return
})
mx.NewFlag(cmdr.OptFlagTypeString).
Titles("pp", "password").
Description("the password requesting.", "").
Group("").
DefaultValue("", "PASSWORD").
ExternalTool(cmdr.ExternalToolPasswordInput)
mx.NewFlag(cmdr.OptFlagTypeString).
Titles("m", "message", "msg").
Description("the message requesting.", "").
Group("").
DefaultValue("", "MESG").
ExternalTool(cmdr.ExternalToolEditor)
mx.NewFlag(cmdr.OptFlagTypeString).
Titles("fr", "fruit").
Description("the message.", "").
Group("").
DefaultValue("", "FRUIT").
ValidArgs("apple", "banana", "orange")
mx.NewFlag(cmdr.OptFlagTypeInt).
Titles("hd", "head").
Description("the head lines.", "").
Group("").
DefaultValue(1, "LINES").
HeadLike(true, 1, 3000)
// kv
kvCmd := root.NewSubCommand().
Titles("kv", "kvstore").
Description("consul kv store operations...", ``)
//...More
複製程式碼這種方式很有效地改進的痛苦之源。要說起來，也沒有什麼缺點了。所以這也是 cmdr 主要推薦你採用的方案。
通過結構 Tag 方式定義
這種方式被有一些第三方直譯器所採用，可以算是比較有價值的定義方式。其特點在於直觀、易於管理。
它的典型案例可能是這樣子的：
type argT struct {
cli.Helper
Port int `cli:"p,port" usage:"short and long format flags both are supported"`
X bool `cli:"x" usage:"boolean type"`
Y bool `cli:"y" usage:"boolean type, too"`
}
func main() {
os.Exit(cli.Run(new(argT), func(ctx *cli.Context) error {
argv := ctx.Argv().(*argT)
ctx.String("port=%d, x=%v, y=%v\n", argv.Port, argv.X, argv.Y)
return nil
}))
}
複製程式碼不過，由於 cmdr 沒有打算支援這種方案，所以這裡僅介紹到這個程度。
說明一下，
cmdr之所以不打算支援這種方案，是因為這樣做好處固然明顯，壞處也同樣令人煩惱：複雜的定義可能會因為被巢狀在 Tag 內而導致難以編寫，例如多行字串在這裡就很難過。
cmdr 新增的相容 flag 的定義方式
那麼，我們回顧了兩種或者三種典型的命令列介面定義方式之後，可以發現他們和 flag 之前的區別是比較大的，當你一開始設計你的 app 時，如果為了便宜和最快開始而採用了 flag 方案的話（畢竟，這是golang自帶的包嘛），再要想切換到一個增強版本的話，無論哪一個都會令你痛一下。
flag 方式
我們看看當你採用 flag 方式時，你的 main 入口可能是這樣的：
// old codes
package main
import "flag"
var (
serv = flag.String("service", "hello_service", "service name")
host = flag.String("host", "localhost", "listening host")
port = flag.Int("port", 50001, "listening port")
reg = flag.String("reg", "localhost:32379", "register etcd address")
count = flag.Int("count", 3, "instance's count")
connectTimeout = flag.Duration("connect-timeout", 5*time.Second, "connect timeout")
)
func main(){
flag.Parse()
// ...
}
複製程式碼遷移到 cmdr
為了遷移為使用 cmdr，你可以簡單地替換 import "flag" 語句為這樣：
import (
// “flag”
"github.com/hedzr/cmdr/flag"
)
複製程式碼其它內容一律不變，也就是說完整的入口現在像這樣：
// new codes
package main
import (
// “flag”
"github.com/hedzr/cmdr/flag"
)
var (
serv = flag.String("service", "hello_service", "service name")
host = flag.String("host", "localhost", "listening host")
port = flag.Int("port", 50001, "listening port")
reg = flag.String("reg", "localhost:32379", "register etcd address")
count = flag.Int("count", 3, "instance's count")
connectTimeout = flag.Duration("connect-timeout", 5*time.Second, "connect timeout")
)
func main(){
flag.Parse()
// ...
}
複製程式碼怎麼樣，足夠簡單吧？
引入增強特性
那麼我們現在期望引入更多 cmdr 專有特性怎麼辦呢？
例如想要全名（完整單詞）作為長選項，補充短選項定義，這可以通過如下的序列來達成：
import (
// “flag”
"github.com/hedzr/cmdr"
"github.com/hedzr/cmdr/flag"
)
var(
// uncomment this line if you like long opt (such as --service)
treatAsLongOpt = flag.TreatAsLongOpt(true)
serv = flag.String("service", "hello_service", "service name",
flag.WithShort("s"),
flag.WithDescription("single line desc", `long desc`))
)
複製程式碼類似的可以完成其他增強特性的定義。
可用的增強特性
所有 cmdr 特性被濃縮在幾個少量的介面中了。此外，某些特性是當你使用 cmdr 時就立即獲得了，無需其它表述或設定（例如短選項的組合，自動的幫助屏，多級命令等等）。
所有的這些需要指定適當引數的特性，包含在如下的這些定義中：
flag.WithTitles(short, long string, aliases ...string) (opt Option)
定義短選項，長選項，別名。
綜合來說，你必須在某個地方定義了一個選項的長名字，因為這是內容索引的依據，如果長名字缺失，那麼可能會有意料之外的錯誤。
別名是隨意的。
如果可以，儘可能提供短選項。
短選項一般來說是一個字母，然而使用兩個甚至更多字母是被允許的，這是為了提供多種風格的命令列介面的相容性。例如 wget, rar 都採用了雙字母的短選項。而 golang flag 自身支援的是任意長度的短選項，沒有長選項支援。cmdr 在短選項上的寬鬆和相容程度，是其它幾乎所有第三方命令列引數直譯器所不能達到的。
flag.WithShort(short string) (opt Option)
提供短選項定義。
flag.WithLong(long string) (opt Option)
提供長選項定義。
flag.WithAliases(aliases ...string) (opt Option)
提供別名定義。別名是任意多、可選的。
flag.WithDescription(oneLine, long string) (opt Option)
提供描述行文字。
oneLine 提供單行描述文字，這通常是在引數被列表時。long 提供的多行描述文字是可選的，你可以提供空字串給它，這個文字在引數被單獨顯示幫助詳情時會給予使用者更多的描述資訊。
flag.WithExamples(examples string) (opt Option)
可以提供引數用法的命令列例項樣本。
這個字串可以是多行的，它遵照一定的格式要求，我們以前的文章中對該格式有過描述。這樣的格式要求是為了在 man/info page 中能夠獲得更視覺敏銳的條目，所以你可以自行判定要不要遵守規則。
flag.WithGroup(group string) (opt Option)
命令或者引數都是可以被分組的。
分組是可以被排序的。給 group 字串一個帶句點的字首，則這個字首會被切割出來用於排序，排序規則是 A-Z0-9a-z 按照 ASCII 順序。所以：
-
1001.c++,1100.golang,1200.java, …; -
abcd.c++,b999.golang,zzzz.java, …;
是有順序的。
由於第一個句點之前的排序用子串被切掉了，因此你的 group 名字可以不受這個序號的影響。
給分組一個空字串，意味著使用內建的 空 分組，這個分組被排列在其他所有分組之前。
給分組一個 cmdr.UnsortedGroup 常量，則它會被歸納到最後一個分組中。值得注意的是，最後一個分組，依賴的是 cmdr.UnsortedGroup 常量的具體值zzzz.unsorted，所以，你仍然有機會定義一個別的序號來繞過這個“最後”。
flag.WithHidden(hidden bool) (opt Option)
hidden為true是，該選項不會被列舉到幫助屏中。
flag.WithDeprecated(deprecation string) (opt Option)
一般來說，你需要給 deprecation 提供一個版本號。這意味著，你提醒終端使用者該選項從某個版本號開始就已經被廢棄了。
按照 Deprecated 的禮貌規則，我們廢棄一個選項時，首先標記它，並給出替代提示，然後在若干次版本迭代之後正式取消它。
flag.WithAction(action func(cmd *Command, args []string) (err error)) (opt Option)
按照 cmdr 的邏輯，一個選項在被顯式命中時，你可以提供一個即時的響應動作，這可能允許你完成一些特別的操作，例如為相關聯的其它一組選項調整預設值什麼的。
flag.WithToggleGroup(group string) (opt Option)
如果你打算定義一組選項，帶有互斥效果，如同 radio button group 那樣，那麼你可以為它們提供相同的 WithToggleGroup group name，這個名字和 WithGroup group name 沒有任何關聯關係。
flag.WithDefaultValue(val interface{}, placeholder string) (opt Option)
提供選項的預設值以及佔位符。
預設值的資料型別相當重要，因為這個資料型別時後續抽取該選項真實值的參考依據。
例如，int資料一定要提供一個 int 數值，Duration資料一定要提供一個 3*time.Second 這樣的確切數值。
flag.WithExternalTool(envKeyName string) (opt Option)
提供一個環境變數名，例如 EDITOR。那麼，如果該選項的 value 部分沒有在命令列中被提供時，cmdr 會搜尋環境變數的值，將其作為控制檯終端應用程式執行，並收集該執行的結果（一個臨時檔案的檔案內容）用於為該選項複製。
如同 git commit -m 那樣。
flag.WithValidArgs(list ...string) (opt Option)
提供一個列舉表，用於約束使用者所提供的值。
flag.WithHeadLike(enable bool, min, max int64) (opt Option)
當該選項被設定為 enable=true 時，識別使用者輸入的諸如 -1973, -211 之類的整數短選項，將其整數數值作為本選項的數值。
如同 head -9 等效於 head -n 9 那樣。
結束語
好了。很多內容。不過還是堆出來了，自己欣慰一下。
真正的結束語
嗯，cmdr 的 v1.0.3 是一個 pre-release 版本，我們已經提供一個 flag 的最平滑遷移的基本實現。
最近的日子裡，我們會考慮完成子命令部分，並最終釋出 v1.1.0，請期待。
如果認為這樣做有價值的話，考慮去鼓勵一下。