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
18package cobra
19
20import (
21 "fmt"
22 "io"
23 "os"
24 "reflect"
25 "strconv"
26 "strings"
27 "text/template"
28 "time"
29 "unicode"
30)
31
32var 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
42var initializers []func()
43var finalizers []func()
44
45const (
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.
55var 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.
59var EnableCommandSorting = defaultCommandSorting
60
61// EnableCaseInsensitive allows case-insensitive commands names. (case sensitive by default)
62var 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.
66var 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.
72var MousetrapHelpText = `This is a command line tool.
73
74You 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.
81var MousetrapDisplayDuration = 5 * time.Second
82
83// AddTemplateFunc adds a template function that's available to Usage and Help
84// template generation.
85func 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.
91func 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.
99func 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.
105func 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.
114func 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.
144func 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
159func 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.
166func 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.
174func rpad(s string, padding int) string {
175 formattedString := fmt.Sprintf("%%-%ds", padding)
176 return fmt.Sprintf(formattedString, s)
177}
178
179func tmpl(text string) *tmplFunc {
180 return &tmplFunc{
181 tmpl: text,
182 fn: func(w io.Writer, data interface{}) error {
183 t := template.New("top")
184 t.Funcs(templateFuncs)
185 template.Must(t.Parse(text))
186 return t.Execute(w, data)
187 },
188 }
189}
190
191// ld compares two strings and returns the levenshtein distance between them.
192func ld(s, t string, ignoreCase bool) int {
193 if ignoreCase {
194 s = strings.ToLower(s)
195 t = strings.ToLower(t)
196 }
197 d := make([][]int, len(s)+1)
198 for i := range d {
199 d[i] = make([]int, len(t)+1)
200 d[i][0] = i
201 }
202 for j := range d[0] {
203 d[0][j] = j
204 }
205 for j := 1; j <= len(t); j++ {
206 for i := 1; i <= len(s); i++ {
207 if s[i-1] == t[j-1] {
208 d[i][j] = d[i-1][j-1]
209 } else {
210 min := d[i-1][j]
211 if d[i][j-1] < min {
212 min = d[i][j-1]
213 }
214 if d[i-1][j-1] < min {
215 min = d[i-1][j-1]
216 }
217 d[i][j] = min + 1
218 }
219 }
220
221 }
222 return d[len(s)][len(t)]
223}
224
225func stringInSlice(a string, list []string) bool {
226 for _, b := range list {
227 if b == a {
228 return true
229 }
230 }
231 return false
232}
233
234// CheckErr prints the msg with the prefix 'Error:' and exits with error code 1. If the msg is nil, it does nothing.
235func CheckErr(msg interface{}) {
236 if msg != nil {
237 fmt.Fprintln(os.Stderr, "Error:", msg)
238 os.Exit(1)
239 }
240}
241
242// WriteStringAndCheck writes a string into a buffer, and checks if the error is not nil.
243func WriteStringAndCheck(b io.StringWriter, s string) {
244 _, err := b.WriteString(s)
245 CheckErr(err)
246}