Skip to content

Commit 701466f

Browse files
akinomyogaakinomyoga
committed
docs(api-and-naming): add rules for xfuncs and generators
scop#954 (comment) scop#964 scop#962 (comment)
1 parent 5d57dd0 commit 701466f

File tree

1 file changed

+72
-9
lines changed

1 file changed

+72
-9
lines changed

‎doc/api-and-naming.md

+72-9
Original file line numberDiff line numberDiff line change
@@ -41,15 +41,17 @@ deprecated in.
4141
Due to its nature, bash-completion adds a number of functions and variables in
4242
the shell's environment.
4343

44-
| | `bash_completion` | `completions/*` |
45-
|:------------------------------------|:--------------------|:---------------------------------------------------------------------------|
46-
| public configuration variables | `BASH_COMPLETION_*` | `BASH_COMPLETION_CMD_${Command^^}_${Config^^}` |
47-
| private non-local variables | `_comp__*` | `_comp_cmd_${Command}__${Data}` |
48-
| private non-local mutable variables | `_comp__*_mut_*` | `_comp_cmd_${Command}__mut_${Data}` |
49-
| exporter function local variables | `_*` (not `_comp*`) | `_*` (not `_comp*`) |
50-
| public/exported functions | `_comp_*` | `_comp_cmd_${Command}` (functions for `complete -F`) |
51-
| | | `_comp_xfunc_${Command}_${Utility}` (functions for use with `_comp_xfunc`) |
52-
| private/internal functions | `_comp__*` | `_comp_cmd_${Command}__${Utility}` (utility functions) |
44+
| | `bash_completion` | `completions/*` |
45+
|:------------------------------------|:------------------------|:--------------------------------------------------------------------------------------|
46+
| public configuration variables | `BASH_COMPLETION_*` | `BASH_COMPLETION_CMD_${Command^^}_${Config^^}` |
47+
| private non-local variables | `_comp__*` | `_comp_cmd_${Command}__${Data}` |
48+
| private non-local mutable variables | `_comp__*_mut_*` | `_comp_cmd_${Command}__mut_${Data}` |
49+
| exporter function local variables | `_*` (not `_comp*`) | `_*` (not `_comp*`) |
50+
| public/exported functions | `_comp_*` | `_comp_cmd_${Command}` (functions for `complete -F`) |
51+
| | | `_comp_xfunc_${Command}_${Utility}` (functions for use with `_comp_xfunc`) |
52+
| | `_comp_compgen_${Name}` | `_comp_xfunc_${Command}_compgen_${Name}` (generators for use with `_comp_compgen -x`) |
53+
| private/internal functions | `_comp__*` | `_comp_cmd_${Command}__${Utility}` (utility functions) |
54+
| | | `_comp_cmd_${Command}__compgen_${Name}` (generators for use with `_comp_compgen -i`) |
5355

5456
`${Command}` refers to a command name (with characters not allowed in POSIX
5557
function or variable names replaced by an underscore), `${Config}` the name of
@@ -110,3 +112,64 @@ distinctive and clash free enough.
110112
It is known that a lot of functions and variables in the tree do not follow
111113
these naming rules yet. Things introduced after version 2.11 should, and we are
112114
evaluating our options for handling older ones.
115+
116+
## Exported functions (xfunc)
117+
118+
Exported functions (xfunc) are the functions defined in completion files for
119+
specific commands but exposed to other completion files. The xfuncs have the
120+
name `_comp_xfunc_CMD_NAME` where `CMD` is the name of the associated command,
121+
and `NAME` is the name of the utility. The other functions defined in specific
122+
completion files are considered private and should not be called outside the
123+
file.
124+
125+
The xfuncs can be called by `_comp_xfunc CMD NAME ARGS` from external files.
126+
The xfuncs are supposed to be directly called as `_comp_xfunc_CMD_NAME ARGS`
127+
from the same file where they are defined.
128+
129+
Note: The name `xfunc` was initially the name of a utility function, `_xfunc`,
130+
to call "eXternal FUNCtions" that are defined in other completion files. The
131+
concept is later extended to also mean "eXported".
132+
133+
## Generator functions
134+
135+
The generator functions, which have names of the form `_comp_compgen_NAME`, are
136+
used to generate completion candidates. A generator function is supposed to be
137+
called by `_comp_compgen [OPTS] NAME ARGS` where `OPTS = -aRl|-v var|-c cur|-C
138+
dir|-F sep` are the options to modify the behavior (see the code comment of
139+
`_comp_compgen` for details). When there are no `opts`, the generator function
140+
is supposed to be directly called as `_comp_compgen_NAME ARGS`. The result is
141+
stored in the target variable (which is `COMPREPLY` by default but can be
142+
specified by `-v var` in `OPTS`).
143+
144+
### Implementing a generator function
145+
146+
To implement a generator function, one should generate completion candidates by
147+
calling `_comp_compgen` or other generators. One should not directly modify or
148+
reference the target variable. When post-filtering is needed, store them in
149+
local arrays, filter them, and finally append them by `_comp_compgen -- -W
150+
"${arr[@]}"`.
151+
152+
A generator function should replace the existing content of the variable by
153+
default. When the appending behavior is favored, the caller should specify it
154+
through `_comp_compgen -a NAME`. The generator function do not need to process
155+
it because internal `_comp_compgen` calls automatically reflects the option
156+
`-a` specified to the outer calls of `_comp_compgen`.
157+
158+
The exit status is implementation-defined.
159+
160+
- The `_comp_compgen -- COMPGEN_ARGS` returns whether there is at least one
161+
completions. This is useful when one wants to reuse the array content with
162+
`"${tmp[@]}"` avoiding `nounset` error.
163+
- Some use other rules for the exit status. E.g., `help` and `usage` return
164+
whether there were options *before* filtering by cur. This is used for
165+
`_comp_compgen_help || _comp_compgen_usage`.
166+
167+
Whether to clear the target variable on the runtime error (when `-a` is not
168+
specified in `OPTS`) is implementation-defuned. On the other hand, the
169+
generator function should not leave any side effects in the target variable on
170+
the usage error.
171+
172+
Exported generators are defined with the names `_comp_xfunc_CMD_compgen_NAME`
173+
and called by `_comp_compgen [opts] -x CMD NAME args`. Internal generators are
174+
defined with the names `_comp_cmd_CMD__compgen_NAME` and called by
175+
`_comp_compgen [opts] -i CMD NAME args`.

0 commit comments

Comments
 (0)