高级特性 (Advanced)

❯ go run ./examples/subcommands/ --tree
ROOT
  snd, soundex, sndx, sound - soundex test
  pa, panic-test - test panic inside cmdr actions
    dz, division-by-zero - 
    pa, panic - 
  d1, demo-1 - [sub] check-in sub
    d2, demo-2 - [sub][sub] check-in sub
      d3, demo-3 - [sub][sub][sub] check-in sub
  sorted - [grouped] Tags operations
    d1, demo-1 - [sub][sub] check-in sub
    d2, demo-2 - [sub][sub] check-in sub
    c1, cmd-1 - [sub][sub] check-in sub
    c2, cmd-2 - [sub][sub] check-in sub
    c3, cmd-3 - [sub][sub] check-in sub
  g, generate, gen - generators for this app.
    s, shell, sh - generate the bash/zsh auto-completion script or install it.
    m, manual, man - generate linux man page.
    d, doc, markdown, pdf, docx, tex - generate a markdown document, or: pdf/TeX/...
    
❯ go run ./examples/subcommands/ pan
subcommands is an effective devops tool by hedzr - v1.0.0
 
Usages:
    subcommands [Commands] [tail args...] [Options] [Parent/Global Options]
 
Description:
    subcommands is an effective devops tool. It make an demo application for `cmdr`.
 
Examples:
    
    $ subcommands gen shell [--bash|--zsh|--auto]
      generate bash/shell completion scripts
    $ subcommands gen man
      generate linux man page 1
    $ subcommands --help
      show help screen.
    
 
Commands:
  [Grouped]
  sorted                                     [grouped] Tags operations
  [Nested]
  d1, demo-1                                 [sub] check-in sub
  [Test]
  pa, panic-test                             test panic inside cmdr actions
  snd, soundex, sndx, sound                  soundex test
  [Misc]
  g, generate, gen                           generators for this app.
 
Options:
  [Misc]
      --config=[Locations of config files]   load config files from where you specified (default [Locations of config files]=)
  -q, --quiet                                No more screen output. [env: QUITE] (default=false)
  -v, --verbose                              Show this help screen [env: VERBOSE] (default=false)
 
Type '-h'/'-?' or '--help' to get command help screen. 
More: '-D'/'--debug'['--env'|'--raw'|'--more'], '-V'/'--version', '-#'/'--build-info', '--no-color', '--strict-mode', '--no-env-overrides'...
 
Unknown command: pan
  - do you mean: pa
  - do you mean: panic-test

// WithSimilarThreshold defines a threshold for command/option similar detector.
// Default threshold is 0.6666666666666666.
// See also JaroWinklerDistance
func WithSimilarThreshold(similarThreshold float64) ExecOption {
 return func(w *ExecWorker) {
  w.similarThreshold = similarThreshold
 }
}

type (
 // UnknownOptionHandler for WithSimilarThreshold/SetUnknownOptionHandler
 UnknownOptionHandler func(isFlag bool, title string, cmd *Command, args []string) (fallbackToDefaultDetector bool)
)
 
func WithUnknownOptionHandler(handler UnknownOptionHandler) ExecOption {
 return func(w *ExecWorker) {
  unknownOptionHandler = handler
 }
}

func myUnknownOptionHandler func(isFlag bool, title string, cmd *Command, args []string) (fallbackToDefaultDetector bool) {
  print("halo terrible")
  return
}
 
// ...
err = cmdr.Exec(buildRootCmd(), 
                WithUnknownOptionHandler(myUnknownOptionHandler),
               )

go run ./examples/panics pa pa # panic test
go run ./examples/panics pa pa --enable-ueh # panic test with UnhandledExceptionHandler
go run ./examples/panics pa dz # divide by zero

package main
 
import (
 "fmt"
 "github.com/hedzr/cmdr"
 cmdr_examples "github.com/hedzr/cmdr-examples"
 "github.com/hedzr/cmdr/tool"
 "github.com/hedzr/logex/logx/logrus"
 "gopkg.in/hedzr/errors.v2"
)
 
func main() {
 Entry()
}
 
func Entry() {
 if err := cmdr.Exec(buildRootCmd(),
  cmdr.WithLogx(logrus.New("debug", false, true)),
  cmdr.WithUnhandledErrorHandler(onUnhandledErrorHandler),
 ); err != nil {
  cmdr.Logger.Fatalf("error: %+v", err)
 }
}
 
func onUnhandledErrorHandler(err interface{}) {
 if cmdr.GetBoolR("enable-ueh") {
  dumpStacks()
  return
 }
 
 panic(err)
}
 
func dumpStacks() {
 fmt.Printf("=== BEGIN goroutine stack dump ===\n%s\n=== END goroutine stack dump ===\n", errors.DumpStacksAsString(true))
}
 
// ...

// Logger is a minimal logger with no more dependencies
 Logger interface {
  Tracef(msg string, args ...interface{})
  Debugf(msg string, args ...interface{})
  Infof(msg string, args ...interface{})
  Warnf(msg string, args ...interface{})
  Errorf(msg string, args ...interface{})
  Fatalf(msg string, args ...interface{})
  Printf(msg string, args ...interface{})
 
  SetLevel(lvl Level)
  GetLevel() Level
 
  // Setup will be invoked once an instance created
  Setup()
 
  // AsFieldLogger() FieldLogger
 }

 // LoggerConfig is used for creating a minimal logger with no more dependencies
 LoggerConfig struct {
  Enabled   bool
  Backend   string // zap, sugar, logrus
  Level     string
  Format    string // text, json, ...
  Target    string // console, file, console+file
  Directory string
  DebugMode bool `json:"-" yaml:"-"`
  TraceMode bool `json:"-" yaml:"-"`
 
  // MaxSize is the maximum size in megabytes of the log file before it gets
  // rotated. It defaults to 100 megabytes.
  MaxSize int `json:"maxsize" yaml:"maxsize"`
 
  // MaxAge is the maximum number of days to retain old log files based on the
  // timestamp encoded in their filename.  Note that a day is defined as 24
  // hours and may not exactly correspond to calendar days due to daylight
  // savings, leap seconds, etc. The default is not to remove old log files
  // based on age.
  MaxAge int `json:"maxage" yaml:"maxage"`
 
  // MaxBackups is the maximum number of old log files to retain.  The default
  // is to retain all old log files (though MaxAge may still cause them to get
  // deleted.)
  MaxBackups int `json:"maxbackups" yaml:"maxbackups"`
 
  // LocalTime determines if the time used for formatting the timestamps in
  // backup files is the computer's local time.  The default is to use UTC
  // time.
  LocalTime bool `json:"localtime" yaml:"localtime"`
 
  // Compress determines if the rotated log files should be compressed
  // using gzip. The default is not to perform compression.
  Compress bool `json:"compress" yaml:"compress"`
 }

std := log.NewStdLogger()
dummy := log.NewDummyLogger()

// Logger for cmdr
var Logger log.Logger = log.NewDummyLogger()

cmdr.Logger.Fatalf("%v", err)

import (
 "github.com/hedzr/cmdr"
 "github.com/hedzr/log"
 "github.com/hedzr/logex/build"
 "gopkg.in/hedzr/errors.v2"
)
 
func Entry() {
 if err := cmdr.Exec(buildRootCmd(),
  // cmdr.WithLogx(logrus.New("debug", false, true)),
  cmdr.WithLogx(build.New(log.NewLoggerConfigWith(true, "logrus", "debug"))),
 ); err != nil {
  cmdr.Logger.Fatalf("error: %+v", err)
 }
 
 cmdr.Logger.Debugf("hello")
}

WithLogx(log.NewDummyLogger()), // import "github.com/hedzr/log"
WithLogx(log.NewStdLogger()), // import "github.com/hedzr/log"
WithLogx(logrus.New(...)),  // import "github.com/hedzr/logex/logx/logrus"
WithLogx(sugar.New(...)),  // import "github.com/hedzr/logex/logx/zap/sugar"
WithLogx(zap.New(...)),   // import "github.com/hedzr/logex/logx/zap"

app:
  # autoconfig for logger/logging-system.
  # cmdr will load this configuration and initialize the logging
  # system via build.New(loggerConfig).
  # see also:
  #   cmdr.Logger,
  #   log.LoggerConfig           (hedzr/log)
  #   build.New(loggerConfig)    (hedzr/logex/build)
  logger:
    # The field 'level' will be reset to "debug" while the app
    # is started up within a debugger
    # available levels are:
    #   "disable"/"off", "panic", "fatal", "error", "warn",
    #   "info", "debug", "trace"
    level:  info
    format: text                  # text, json, logfmt, ...
    backend: sugar                # zap, sugar(sugared-zap) or logrus, std, off
    target: console               # console, file
    directory: /var/log/$APPNAME

cd ./examples/logging
go run .

cmdr.Exec(buildRootCmd(), 
          cmdr.WithConfigSubDirAutoName("myapp.d"))

cmdr.Exec(buildRootCmd(), 
          cmdr.WithSearchAlterConfigFiles(true))

certCmd := root.NewSubCommand("create", "c").
  Description("create NEW certification").
    TailPlaceholder(`input-cert-file input-cert-key-file output-cert-file`)

// WithHelpTailLine setup the tail line in help screen
//
// Default line is:
//   "\nType '-h' or '--help' to get command help screen."
func WithHelpTailLine(line string) ExecOption {
   return func(w *ExecWorker) {
      w.helpTailLine = line
   }
}

// WithOnSwitchCharHit handle the exact single switch-char (such as '-', '/', '~') matched.
// For example, type `bin/fluent mx -d - --help` will trigger this callback at the 2nd flag '-'.
func WithOnSwitchCharHit(fn func(parsed *Command, switchChar string, args []string) (err error)) ExecOption {
   return func(w *ExecWorker) {
      w.onSwitchCharHit = fn
   }
}

// WithOnPassThruCharHit handle the passthrough char(s) (i.e. '--') matched
// For example, type `bin/fluent mx -d -- --help` will trigger this callback at the 2nd flag '--'.
func WithOnPassThruCharHit(fn func(parsed *Command, switchChar string, args []string) (err error)) ExecOption {
   return func(w *ExecWorker) {
      w.onPassThruCharHit = fn
   }
}

func WithAfterArgsParsed(hookFunc Handler) ExecOption {
 return func(w *ExecWorker) {
  w.afterArgsParsed = hookFunc
 }
}
 
type Handler func(cmd *Command, args []string) (err error)

func dumpTreeForAllCommands(cmd *Command, args []string) (err error) {
 command := &rootCommand.Command
 _ = walkFromCommand(command, 0, func(cmd *Command, index int) (e error) {
  if cmd.Hidden {
   return
  }
 
  deep := findDepth(cmd) - 1
  if deep == 0 {
   fmt.Println("ROOT")
  } else {
   sp := strings.Repeat("  ", deep)
   // fmt.Printf("%s%v - \x1b[%dm\x1b[%dm%s\x1b[0m\n",
   //  sp, cmd.GetTitleNames(),
   //  BgNormal, CurrentDescColor, cmd.Description)
 
   if len(cmd.Deprecated) > 0 {
    fmt.Printf("%s\x1b[%dm\x1b[%dm%s - %s\x1b[0m [deprecated since %v]\n",
     sp, BgNormal, CurrentDescColor, cmd.GetTitleNames(), cmd.Description,
     cmd.Deprecated)
   } else {
    fmt.Printf("%s%s - \x1b[%dm\x1b[%dm%s\x1b[0m\n",
     sp, cmd.GetTitleNames(), BgNormal, CurrentDescColor, cmd.Description)
   }
  }
  return
 })
 return ErrShouldBeStopException
}

package cmdrplugin
 
// PluginEntry entry of an addon (golang plugin)
type PluginEntry interface {
 PluginCmd
 AddonTitle() string
 AddonDescription() string
 AddonCopyright() string
 AddonVersion() string
}
 
// PluginCompBase component for cmd and flag of an addon
type PluginCompBase interface {
 Name() string
 ShortName() string
 Aliases() []string
 Description() string
}
 
// PluginCmd a command of an addon
type PluginCmd interface {
 PluginCompBase
 SubCommands() []PluginCmd
 Flags() []PluginFlag
 Action(args []string) (err error)
}
 
// PluginFlag a flag of a command of an addon
type PluginFlag interface {
 PluginCompBase
 DefaultValue() interface{}
 PlaceHolder() string
 Action() (err error) // onSet
}

package main
 
import (
 "fmt"
 "github.com/hedzr/cmdr"
 cmdrbase "github.com/hedzr/cmdr-base"
)
 
// NewAddon returns an addon with cmdr.PluginEntry
func NewAddon() cmdrbase.PluginEntry {
 return &addon{
  //
 }
}
 
type addon struct {
}
 
func (p *addon) AddonTitle() string       { return "demo addon" }
func (p *addon) AddonDescription() string { return "demo addon desc" }
func (p *addon) AddonCopyright() string   { return "copyright (c) hedzr, 2020" }
func (p *addon) AddonVersion() string     { panic("0.1.1") }
func (p *addon) Name() string             { return "demo" }
func (p *addon) ShortName() string        { return "dx" }
func (p *addon) Aliases() []string        { return nil }
func (p *addon) Description() string      { return "the demo addon for testing purpose" }
 
func (p *addon) SubCommands() []cmdrbase.PluginCmd {
 return nil
}
 
func (p *addon) Flags() []cmdrbase.PluginFlag {
 return []cmdrbase.PluginFlag{
  newFlag1(),
 }
}
 
func (p *addon) Action(args []string) (err error) {
 cmdr.Logger.Infof("hello, args: %v", args)
 fmt.Printf("Logger: %v\n", cmdr.Logger)
 return
}
 
//
 
func newFlag1() *flag1 {
 return &flag1{}
}
 
type flag1 struct{}
 
func (f *flag1) Name() string              { return "bool-flag" }
func (f *flag1) ShortName() string         { return "bf" }
func (f *flag1) Aliases() []string         { return []string{} }
func (f *flag1) Description() string       { return "a bool flag" }
func (f *flag1) DefaultValue() interface{} { return false }
func (f *flag1) PlaceHolder() string       { return "" }
 
func (f *flag1) Action() (err error) {
 return
}

$ go build -v -race -buildmode=plugin -o ./ci/local/share/fluent/addons/demo.so ./plugin/demo
 chmod +x ./ci/local/share/fluent/addons/demo.so

"./ci/local/share/$APPNAME/addons",
"$HOME/.local/share/$APPNAME/addons",
"$HOME/.$APPNAME/addons",
"/usr/local/share/$APPNAME/addons",
"/usr/share/$APPNAME/addons",

./bin/fluent dx

git config --global alias.co checkout
git co master # == git checkout master

app:
 
  aliases:
    group:
    commands:
      - title: ls
        invoke-sh: ls -la -G                # for macOS, -G = --color; for linux: -G = --no-group
        desc: list the current directory
      - title: pwd
        invoke-sh: pwd
        desc: print the current directory
      - title: services
        desc: "the service commands and options"
        subcmds:
          - title: ls
            invoke: /server/list            # invoke a command from the command tree in this app
            invoke-proc:                    # invoke the external commands (via: executable)
            invoke-sh:                      # invoke the external commands (via: shell)
            shell: /bin/bash                # or /usr/bin/env bash|zsh|...
            desc: list the services
          - title: start
            flags: []
            desc: start a service
          - title: stop
            flags: []
            desc: stop a service
          - title: git-version
            invoke-proc: git describe --tags --abbrev=0
            desc: print the git version
            group: Proc
          - title: git-revision
            invoke-proc: git rev-parse --short HEAD
            desc: print the git revision
            group: Proc
          - title: kx1
            invoke: /kb
            desc: invoke /kb command
            group: Internal
          - title: kx2
            invoke: ../.././//kb --size 32mb
            desc: invoke /kb command
            group: Internal
          - title: kx3
            invoke: /kb --size 2kb
            desc: invoke /kb command
            group: Internal
        flags:
          - title: name
            default: noname
            type: string          # bool, string, duration, int, uint, ...
            group:
            toggle-group:
            desc: specify the name of a service

          - title: kx1
            invoke: /kb
            desc: invoke /kb command
            group: Internal
          - title: kx2
            invoke: ../.././//kb --size 32mb
            desc: invoke /kb command
            group: Internal
          - title: kx3
            invoke: /kb --size 2kb
            desc: invoke /kb command
            group: Internal

          - title: git-version
            invoke-proc: git describe --tags --abbrev=0
            desc: print the git version
            group: Proc
          - title: git-revision
            invoke-proc: git rev-parse --short HEAD
            desc: print the git revision
            group: Proc

      - title: ls
        invoke-sh: ls -la -G                # for macOS, -G = --color; for linux: -G = --no-group
        desc: list the current directory
      - title: pwd
        invoke-sh: pwd
        desc: print the current directory