active_help.go (2700B)
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 package cobra 16 17 import ( 18 "fmt" 19 "os" 20 "strings" 21 ) 22 23 const ( 24 activeHelpMarker = "_activeHelp_ " 25 // The below values should not be changed: programs will be using them explicitly 26 // in their user documentation, and users will be using them explicitly. 27 activeHelpEnvVarSuffix = "_ACTIVE_HELP" 28 activeHelpGlobalEnvVar = "COBRA_ACTIVE_HELP" 29 activeHelpGlobalDisable = "0" 30 ) 31 32 // AppendActiveHelp adds the specified string to the specified array to be used as ActiveHelp. 33 // Such strings will be processed by the completion script and will be shown as ActiveHelp 34 // to the user. 35 // The array parameter should be the array that will contain the completions. 36 // This function can be called multiple times before and/or after completions are added to 37 // the array. Each time this function is called with the same array, the new 38 // ActiveHelp line will be shown below the previous ones when completion is triggered. 39 func AppendActiveHelp(compArray []string, activeHelpStr string) []string { 40 return append(compArray, fmt.Sprintf("%s%s", activeHelpMarker, activeHelpStr)) 41 } 42 43 // GetActiveHelpConfig returns the value of the ActiveHelp environment variable 44 // <PROGRAM>_ACTIVE_HELP where <PROGRAM> is the name of the root command in upper 45 // case, with all - replaced by _. 46 // It will always return "0" if the global environment variable COBRA_ACTIVE_HELP 47 // is set to "0". 48 func GetActiveHelpConfig(cmd *Command) string { 49 activeHelpCfg := os.Getenv(activeHelpGlobalEnvVar) 50 if activeHelpCfg != activeHelpGlobalDisable { 51 activeHelpCfg = os.Getenv(activeHelpEnvVar(cmd.Root().Name())) 52 } 53 return activeHelpCfg 54 } 55 56 // activeHelpEnvVar returns the name of the program-specific ActiveHelp environment 57 // variable. It has the format <PROGRAM>_ACTIVE_HELP where <PROGRAM> is the name of the 58 // root command in upper case, with all - replaced by _. 59 func activeHelpEnvVar(name string) string { 60 // This format should not be changed: users will be using it explicitly. 61 activeHelpEnvVar := strings.ToUpper(fmt.Sprintf("%s%s", name, activeHelpEnvVarSuffix)) 62 return strings.ReplaceAll(activeHelpEnvVar, "-", "_") 63 }