cobra.go

Documentation: github.com/spf13/cobra

     1  // Copyright 2013-2023 The Cobra Authors
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Commands similar to git, go tools and other modern CLI tools
    16  // inspired by go, go-Commander, gh and subcommand
    17  
    18  package cobra
    19  
    20  import (
    21  	"fmt"
    22  	"io"
    23  	"os"
    24  	"reflect"
    25  	"strconv"
    26  	"strings"
    27  	"text/template"
    28  	"time"
    29  	"unicode"
    30  )
    31  
    32  var templateFuncs = template.FuncMap{
    33  	"trim":                    strings.TrimSpace,
    34  	"trimRightSpace":          trimRightSpace,
    35  	"trimTrailingWhitespaces": trimRightSpace,
    36  	"appendIfNotPresent":      appendIfNotPresent,
    37  	"rpad":                    rpad,
    38  	"gt":                      Gt,
    39  	"eq":                      Eq,
    40  }
    41  
    42  var initializers []func()
    43  var finalizers []func()
    44  
    45  const (
    46  	defaultPrefixMatching   = false
    47  	defaultCommandSorting   = true
    48  	defaultCaseInsensitive  = false
    49  	defaultTraverseRunHooks = false
    50  )
    51  
    52  // EnablePrefixMatching allows setting automatic prefix matching. Automatic prefix matching can be a dangerous thing
    53  // to automatically enable in CLI tools.
    54  // Set this to true to enable it.
    55  var EnablePrefixMatching = defaultPrefixMatching
    56  
    57  // EnableCommandSorting controls sorting of the slice of commands, which is turned on by default.
    58  // To disable sorting, set it to false.
    59  var EnableCommandSorting = defaultCommandSorting
    60  
    61  // EnableCaseInsensitive allows case-insensitive commands names. (case sensitive by default)
    62  var EnableCaseInsensitive = defaultCaseInsensitive
    63  
    64  // EnableTraverseRunHooks executes persistent pre-run and post-run hooks from all parents.
    65  // By default this is disabled, which means only the first run hook to be found is executed.
    66  var EnableTraverseRunHooks = defaultTraverseRunHooks
    67  
    68  // MousetrapHelpText enables an information splash screen on Windows
    69  // if the CLI is started from explorer.exe.
    70  // To disable the mousetrap, just set this variable to blank string ("").
    71  // Works only on Microsoft Windows.
    72  var MousetrapHelpText = `This is a command line tool.
    73  
    74  You need to open cmd.exe and run it from there.
    75  `
    76  
    77  // MousetrapDisplayDuration controls how long the MousetrapHelpText message is displayed on Windows
    78  // if the CLI is started from explorer.exe. Set to 0 to wait for the return key to be pressed.
    79  // To disable the mousetrap, just set MousetrapHelpText to blank string ("").
    80  // Works only on Microsoft Windows.
    81  var MousetrapDisplayDuration = 5 * time.Second
    82  
    83  // AddTemplateFunc adds a template function that's available to Usage and Help
    84  // template generation.
    85  func AddTemplateFunc(name string, tmplFunc interface{}) {
    86  	templateFuncs[name] = tmplFunc
    87  }
    88  
    89  // AddTemplateFuncs adds multiple template functions that are available to Usage and
    90  // Help template generation.
    91  func AddTemplateFuncs(tmplFuncs template.FuncMap) {
    92  	for k, v := range tmplFuncs {
    93  		templateFuncs[k] = v
    94  	}
    95  }
    96  
    97  // OnInitialize sets the passed functions to be run when each command's
    98  // Execute method is called.
    99  func OnInitialize(y ...func()) {
   100  	initializers = append(initializers, y...)
   101  }
   102  
   103  // OnFinalize sets the passed functions to be run when each command's
   104  // Execute method is terminated.
   105  func OnFinalize(y ...func()) {
   106  	finalizers = append(finalizers, y...)
   107  }
   108  
   109  // FIXME Gt is unused by cobra and should be removed in a version 2. It exists only for compatibility with users of cobra.
   110  
   111  // Gt takes two types and checks whether the first type is greater than the second. In case of types Arrays, Chans,
   112  // Maps and Slices, Gt will compare their lengths. Ints are compared directly while strings are first parsed as
   113  // ints and then compared.
   114  func Gt(a interface{}, b interface{}) bool {
   115  	var left, right int64
   116  	av := reflect.ValueOf(a)
   117  
   118  	switch av.Kind() {
   119  	case reflect.Array, reflect.Chan, reflect.Map, reflect.Slice:
   120  		left = int64(av.Len())
   121  	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
   122  		left = av.Int()
   123  	case reflect.String:
   124  		left, _ = strconv.ParseInt(av.String(), 10, 64)
   125  	}
   126  
   127  	bv := reflect.ValueOf(b)
   128  
   129  	switch bv.Kind() {
   130  	case reflect.Array, reflect.Chan, reflect.Map, reflect.Slice:
   131  		right = int64(bv.Len())
   132  	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
   133  		right = bv.Int()
   134  	case reflect.String:
   135  		right, _ = strconv.ParseInt(bv.String(), 10, 64)
   136  	}
   137  
   138  	return left > right
   139  }
   140  
   141  // FIXME Eq is unused by cobra and should be removed in a version 2. It exists only for compatibility with users of cobra.
   142  
   143  // Eq takes two types and checks whether they are equal. Supported types are int and string. Unsupported types will panic.
   144  func Eq(a interface{}, b interface{}) bool {
   145  	av := reflect.ValueOf(a)
   146  	bv := reflect.ValueOf(b)
   147  
   148  	switch av.Kind() {
   149  	case reflect.Array, reflect.Chan, reflect.Map, reflect.Slice:
   150  		panic("Eq called on unsupported type")
   151  	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
   152  		return av.Int() == bv.Int()
   153  	case reflect.String:
   154  		return av.String() == bv.String()
   155  	}
   156  	return false
   157  }
   158  
   159  func trimRightSpace(s string) string {
   160  	return strings.TrimRightFunc(s, unicode.IsSpace)
   161  }
   162  
   163  // FIXME appendIfNotPresent is unused by cobra and should be removed in a version 2. It exists only for compatibility with users of cobra.
   164  
   165  // appendIfNotPresent will append stringToAppend to the end of s, but only if it's not yet present in s.
   166  func appendIfNotPresent(s, stringToAppend string) string {
   167  	if strings.Contains(s, stringToAppend) {
   168  		return s
   169  	}
   170  	return s + " " + stringToAppend
   171  }
   172  
   173  // rpad adds padding to the right of a string.
   174  func rpad(s string, padding int) string {
   175  	formattedString := fmt.Sprintf("%%-%ds", padding)
   176  	return fmt.Sprintf(formattedString, s)
   177  }
   178  
   179  // tmpl executes the given template text on data, writing the result to w.
   180  func tmpl(w io.Writer, text string, data interface{}) error {
   181  	t := template.New("top")
   182  	t.Funcs(templateFuncs)
   183  	template.Must(t.Parse(text))
   184  	return t.Execute(w, data)
   185  }
   186  
   187  // ld compares two strings and returns the levenshtein distance between them.
   188  func ld(s, t string, ignoreCase bool) int {
   189  	if ignoreCase {
   190  		s = strings.ToLower(s)
   191  		t = strings.ToLower(t)
   192  	}
   193  	d := make([][]int, len(s)+1)
   194  	for i := range d {
   195  		d[i] = make([]int, len(t)+1)
   196  	}
   197  	for i := range d {
   198  		d[i][0] = i
   199  	}
   200  	for j := range d[0] {
   201  		d[0][j] = j
   202  	}
   203  	for j := 1; j <= len(t); j++ {
   204  		for i := 1; i <= len(s); i++ {
   205  			if s[i-1] == t[j-1] {
   206  				d[i][j] = d[i-1][j-1]
   207  			} else {
   208  				min := d[i-1][j]
   209  				if d[i][j-1] < min {
   210  					min = d[i][j-1]
   211  				}
   212  				if d[i-1][j-1] < min {
   213  					min = d[i-1][j-1]
   214  				}
   215  				d[i][j] = min + 1
   216  			}
   217  		}
   218  
   219  	}
   220  	return d[len(s)][len(t)]
   221  }
   222  
   223  func stringInSlice(a string, list []string) bool {
   224  	for _, b := range list {
   225  		if b == a {
   226  			return true
   227  		}
   228  	}
   229  	return false
   230  }
   231  
   232  // CheckErr prints the msg with the prefix 'Error:' and exits with error code 1. If the msg is nil, it does nothing.
   233  func CheckErr(msg interface{}) {
   234  	if msg != nil {
   235  		fmt.Fprintln(os.Stderr, "Error:", msg)
   236  		os.Exit(1)
   237  	}
   238  }
   239  
   240  // WriteStringAndCheck writes a string into a buffer, and checks if the error is not nil.
   241  func WriteStringAndCheck(b io.StringWriter, s string) {
   242  	_, err := b.WriteString(s)
   243  	CheckErr(err)
   244  }
   245
View as plain text