git.sr.ht/~pingoo/stdx@v0.0.0-20240218134121-094174641f6e/cobra/active_help.go (about)

     1  // Copyright 2013-2022 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  }