1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
Crazy-Complete Documentation
============================
.. contents::
:local:
:depth: 2
This documentation provides an overview of how to define shell completions for commands using **crazy-complete**.
Command Definition
------------------
To define a completion for a command, use the following structure:
.. code-block:: yaml
prog: "<PROGRAM NAME>"
help: "<PROGRAM DESCRIPTION>"
options:
<OPTION ...>
positionals:
<POSITIONAL ...>
:prog:
The name of the program for which you want to create completion.
:help:
*(optional)* A short description of the program.
:options:
*(optional)* A list of options the program accepts.
:positionals:
*(optional)* A list of positional arguments the program uses.
Example:
.. code-block:: yaml
prog: "git"
help: "Distributed version control system"
Option Definition
-----------------
Options are defined as follows:
.. code-block:: yaml
options:
- option_strings: ["<OPTION STRING>", ...]
metavar: "<METAVAR>"
help: "<OPTION DESCRIPTION>"
optional_arg: <BOOL>
complete: <COMPLETE ACTION>
repeatable: <BOOL>
final: <BOOL>
hidden: <BOOL>
groups: ["<GROUP>", ...]
when: "<CONDITION>"
:option_strings:
A list of option strings (e.g., ``["-h", "--help"]``).
:metavar:
*(optional)* The placeholder used for the argument (e.g., ``FILE``).
:help:
*(optional)* A description of the option.
:optional_arg:
*(optional)* Indicates if the option's argument is optional (default: ``false``).
:complete:
*(optional)* Defines the completion method.
If not set, the option does not take an argument.
Use ``["none"]`` if the option accepts an argument but no specific completion method applies.
:repeatable:
*(optional)* Whether an option can be used multiple times (default: ``false``).
:final:
*(optional)* If true, no further options are suggested after this one.
Commonly used for ``--help`` or ``--version`` (default: ``false``).
:hidden:
*(optional)* Excludes this option from completion suggestions, but it remains valid when typed manually.
:groups:
*(optional)* Assigns this option to one or more groups.
Multiple options from the same group cannot be suggested at once, useful for mutually exclusive flags.
:when:
*(optional)* Enables this option only if the condition evaluates to true.
Example:
.. code-block:: yaml
options:
- option_strings: ["--directory", "-C"]
metavar: "PATH"
help: "Run as if git was started in PATH"
complete: ["directory"]
Positional Arguments
--------------------
Positional arguments are defined as follows:
.. code-block:: yaml
positionals:
- number: <NUMBER>
metavar: "<METAVAR>"
help: "<POSITIONAL DESCRIPTION>"
repeatable: <BOOL>
complete: <COMPLETE ACTION>
when: "<CONDITION>"
:number:
The order of the positional argument (e.g., ``1`` for the first argument).
:metavar:
*(optional)* Placeholder for the positional argument in the help text.
:help:
*(optional)* A description of the positional argument.
:repeatable:
*(optional)* Whether this argument can be repeated (default: ``false``).
:complete:
*(optional)* Completion method to generate possible values (default: ``["none"]``).
:when:
*(optional)* Enables this positional only if the condition evaluates to true.
Example:
.. code-block:: yaml
positionals:
- number: 1
metavar: "FILE"
help: "File to process"
complete: ["file"]
Subcommands
-----------
Subcommands are defined by appending them to the program name:
.. code-block:: yaml
prog: "<PROGRAM NAME> <SUBCOMMAND> ..."
aliases: ["<ALIAS>", ...]
help: "<SUBCOMMAND DESCRIPTION>"
:prog:
The name of the program, followed by the subcommand(s).
:aliases:
*(optional)* A list of alternative names for the subcommand.
Aliases must not include the program name.
:help:
*(optional)* A description of the subcommand.
Example:
.. code-block:: yaml
prog: "kubectl get"
help: "Display one or many resources"
options:
- option_strings: ["--output"]
complete: ["choices", ["json", "yaml", "wide"]]
Best Practices
--------------
* Use ``["none"]`` only when a value is required but no completion applies.
* Use ``repeatable: true`` for options like ``--tag`` or ``--define``.
* Set ``final: true`` for options like ``--help`` or ``--version`` so no further suggestions appear afterward.
* Use groups for mutually exclusive flags to improve user experience.
|
