從 golang flag 遷移到 cmdr

基於 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 <[email protected]>",
}
//... 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 那樣。

結束語

好了。很多內容。不過還是堆出來了,自己欣慰一下。

真正的結束語

嗯,cmdrv1.0.3 是一個 pre-release 版本,我們已經提供一個 flag 的最平滑遷移的基本實現。

最近的日子裏,我們會考慮完成子命令部分,並最終釋出 v1.1.0,請期待。

如果認爲這樣做有價值的話,考慮去鼓勵一下。

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章