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
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
crazy-complete
==============
Every program should have autocompletion in the shell to enhance user experience and productivity. crazy-complete helps solve this task by generating robust and reliable autocompletion scripts.
**Key Features**:
- **Generates Robust Scripts**: Ensures that the autocompletion scripts are reliable and efficient.
- **Multi-Shell Support**: Works seamlessly with **Bash**, **Fish**, and **Zsh**, providing flexibility across different environments.
- **Minimal Dependencies**: The only external dependency is PyYAML.
- **Configurable and Extendable**: The generated autocompletion scripts are highly configurable and can be easily extended to suit your specific needs.
- **Standalone Scripts**: The generated scripts are standalone and do not depend on modified environments, unlike some alternatives like argcomplete.
- **Easy to Use**: Simple and intuitive to set up, allowing you to quickly add autocompletion functionality to your programs.
With crazy-complete, adding autocompletion to your programs has never been easier. Try it out and see the difference it makes in your command-line applications!
Table of Contents
=================
- [Benefits of Using crazy-complete](#benefits-of-using-crazy-complete)
- [Disadvantages of crazy-complete](#disadvantages-of-crazy-complete)
- [Installation](#installation)
- [Synposis](#synopsis)
- [Options](#options)
- [Usage examples](#usage-examples)
- [Definition file examples](#definition-file-examples)
- [Documentation](#documentation)
- [Comparision with other auto-complete generators](#comparision-with-other-auto-complete-generators)
- [Questions or problems](#questions-or-problems)
Benefits of Using crazy-complete
================================
- **Focus on what matters:**
crazy-complete generates the basic structure of your autocompletion scripts,
so you can focus entirely on defining options and their completions instead of dealing with repetitive setup code.
- **Cross-shell consistency:**
Write your completion logic once and get reliable completions for **Bash**, **Zsh**, and **Fish**, with identical behavior across all shells.
- **Powerful argument completion:**
crazy-complete provides a rich set of [built-in](docs/documentation.md#built-in-commands) helpers for argument completion and makes it simple to define your own [custom argument handlers](docs/documentation.md#user-defined-commands).
- **Arbitrary levels of subcommands:**
No matter how deeply nested your CLI structure is, crazy-complete can handle it.
You can define completions for commands, subcommands, and even sub-subcommands without extra effort.
- **Full control over options:**
- **Repeatable / non-repeatable options**: control whether options can be used once or multiple times.
- **Mutually exclusive options**: ensure that incompatible options cannot appear together.
- **Conditional options**: only suggest options when certain conditions are met.
- **Final options**: options that prevent any further options from being completed.
- **Hidden options**: completable options that are not shown in the suggestion list.
- **Capturing options**: collect options and their values to enable advanced, context-sensitive completions.
Disadvantages of crazy-complete
===============================
While crazy-complete offers many advantages, there are some trade-offs to be aware of:
- **Code size and verbosity:**
Its biggest strength - **secure, fully controlled completions** - can also be its biggest weakness.
- For **Bash**, this means the generated scripts contain a significant amount of boilerplate code for parsing options and positional arguments.
- For **Fish**, large command-line definitions may result in slower completions, although performance is usually acceptable for most use cases.
- **Mitigation:** There are ways to reduce script size and improve performance. See [Tips And Tricks](docs/documentation.md#tips-and-tricks) for more details.
- **Not as optimized as hand-written scripts:**
The generated scripts prioritize correctness and reliability over minimal size or maximum performance. Hand-written scripts may be more compact and slightly faster in some cases.
Installation
============
- Using Arch Linux:
Use the \*.pkg.tar.zst file that has been released in this repository.
Or use:
```
git clone https://github.com/crazy-complete/crazy-complete
cd crazy-complete
makepkg -c && sudo pacman -U python-crazy-complete*.pkg.*
```
- Using Debian:
Use the \*.deb file that has been released in this repository.
- Using Fedora / OpenSuse:
Use the \*.rpm file that has been released in this repository.
- For other Linux distributions:
```
git clone https://github.com/crazy-complete/crazy-complete
cd crazy-complete
python3 -m pip install .
```
Synopsis
========
> `crazy-complete [OPTIONS] {bash,fish,zsh,yaml,json} <DEFINITION_FILE>`
Options
=======
**--input-type={yaml,json,python,help,auto}**
> Specify input file type. With 'auto' the file extension will be used
> to determine the input type.
**--abbreviate-commands={True,False}**
> Sets whether commands can be abbreviated.
**--abbreviate-options={True,False}**
> Sets whether options can be abbreviated.
> Note: abbreviated options are not supported by FISH and ZSH.
**--repeatable-options={True,False}**
> Sets whether options are suggested multiple times during completion.
**--inherit-options={True,False}**
> Sets whether parent options are visible to subcommands.
**--disable=FEATURES** *(hidden,final,groups,repeatable,when)*
> Disable a list of features.
**--vim-modeline={True,False}**
> Sets whether a vim modeline comment shall be appended to the generated code.
**--include-file=FILE**
> Include contents of FILE in output.
**-o|--output=FILE**
> Write output to destination file [default: stdout].
**-i|--install-system-wide**
> Write output to the system-wide completions dir of shell.
**-u|--uninstall-system-wide**
> Uninstall the system-wide completion file for program.
Completions for crazy-complete
==============================
To install system-wide completion files for crazy-complete, execute the following:
```
sudo crazy-complete --input-type=python -i bash "$(which crazy-complete)"
sudo crazy-complete --input-type=python -i fish "$(which crazy-complete)"
sudo crazy-complete --input-type=python -i zsh "$(which crazy-complete)"
```
If you want to uninstall the completion files, pass `-u` to crazy-complete:
```
sudo crazy-complete --input-type=python -u bash "$(which crazy-complete)"
sudo crazy-complete --input-type=python -u fish "$(which crazy-complete)"
sudo crazy-complete --input-type=python -u zsh "$(which crazy-complete)"
```
Usage examples
==============
Converting a Python script to YAML:
```
crazy-complete --input-type=python yaml my_program.py
```
Generate a YAML file from help text:
```
grep --help > help_file
crazy-complete --input-type=help yaml help_file
- or -
grep --help | crazy-complete --input-type=help yaml /dev/stdin
```
Generate shell auto completions for BASH:
```
crazy-complete --input-type=yaml --include my_program.bash bash my_program.yaml
```
Definition file examples
========================
See [examples](https://github.com/crazy-complete/crazy-complete/tree/main/examples) for examples.
See [completions](https://github.com/crazy-complete/completions) for real world applications of crazy-complete.
You can even have a look at the [tests](https://github.com/crazy-complete/crazy-complete/tree/main/test).
Documentation
=============
See [docs/documentation.md](docs/documentation.md).
Comparision with other auto-complete generators
===============================================
See [docs/comparision.md](docs/comparision.md) for a comparision with other tools.
Questions or problems
=====================
Don't hesitate to open an issue on [GitHub](https://github.com/crazy-complete/crazy-complete/issues).
|
