git.sr.ht/~pingoo/stdx@v0.0.0-20240218134121-094174641f6e/cobra/shell_completions.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  	"github.com/spf13/pflag"
    19  )
    20  
    21  // MarkFlagRequired instructs the various shell completion implementations to
    22  // prioritize the named flag when performing completion,
    23  // and causes your command to report an error if invoked without the flag.
    24  func (c *Command) MarkFlagRequired(name string) error {
    25  	return MarkFlagRequired(c.Flags(), name)
    26  }
    27  
    28  // MarkPersistentFlagRequired instructs the various shell completion implementations to
    29  // prioritize the named persistent flag when performing completion,
    30  // and causes your command to report an error if invoked without the flag.
    31  func (c *Command) MarkPersistentFlagRequired(name string) error {
    32  	return MarkFlagRequired(c.PersistentFlags(), name)
    33  }
    34  
    35  // MarkFlagRequired instructs the various shell completion implementations to
    36  // prioritize the named flag when performing completion,
    37  // and causes your command to report an error if invoked without the flag.
    38  func MarkFlagRequired(flags *pflag.FlagSet, name string) error {
    39  	return flags.SetAnnotation(name, BashCompOneRequiredFlag, []string{"true"})
    40  }
    41  
    42  // MarkFlagFilename instructs the various shell completion implementations to
    43  // limit completions for the named flag to the specified file extensions.
    44  func (c *Command) MarkFlagFilename(name string, extensions ...string) error {
    45  	return MarkFlagFilename(c.Flags(), name, extensions...)
    46  }
    47  
    48  // MarkFlagCustom adds the BashCompCustom annotation to the named flag, if it exists.
    49  // The bash completion script will call the bash function f for the flag.
    50  //
    51  // This will only work for bash completion.
    52  // It is recommended to instead use c.RegisterFlagCompletionFunc(...) which allows
    53  // to register a Go function which will work across all shells.
    54  func (c *Command) MarkFlagCustom(name string, f string) error {
    55  	return MarkFlagCustom(c.Flags(), name, f)
    56  }
    57  
    58  // MarkPersistentFlagFilename instructs the various shell completion
    59  // implementations to limit completions for the named persistent flag to the
    60  // specified file extensions.
    61  func (c *Command) MarkPersistentFlagFilename(name string, extensions ...string) error {
    62  	return MarkFlagFilename(c.PersistentFlags(), name, extensions...)
    63  }
    64  
    65  // MarkFlagFilename instructs the various shell completion implementations to
    66  // limit completions for the named flag to the specified file extensions.
    67  func MarkFlagFilename(flags *pflag.FlagSet, name string, extensions ...string) error {
    68  	return flags.SetAnnotation(name, BashCompFilenameExt, extensions)
    69  }
    70  
    71  // MarkFlagCustom adds the BashCompCustom annotation to the named flag, if it exists.
    72  // The bash completion script will call the bash function f for the flag.
    73  //
    74  // This will only work for bash completion.
    75  // It is recommended to instead use c.RegisterFlagCompletionFunc(...) which allows
    76  // to register a Go function which will work across all shells.
    77  func MarkFlagCustom(flags *pflag.FlagSet, name string, f string) error {
    78  	return flags.SetAnnotation(name, BashCompCustom, []string{f})
    79  }
    80  
    81  // MarkFlagDirname instructs the various shell completion implementations to
    82  // limit completions for the named flag to directory names.
    83  func (c *Command) MarkFlagDirname(name string) error {
    84  	return MarkFlagDirname(c.Flags(), name)
    85  }
    86  
    87  // MarkPersistentFlagDirname instructs the various shell completion
    88  // implementations to limit completions for the named persistent flag to
    89  // directory names.
    90  func (c *Command) MarkPersistentFlagDirname(name string) error {
    91  	return MarkFlagDirname(c.PersistentFlags(), name)
    92  }
    93  
    94  // MarkFlagDirname instructs the various shell completion implementations to
    95  // limit completions for the named flag to directory names.
    96  func MarkFlagDirname(flags *pflag.FlagSet, name string) error {
    97  	return flags.SetAnnotation(name, BashCompSubdirsInDir, []string{})
    98  }