Skip to content

Commit b753035

Browse files
DannyBenDannyBen
committed
- Add structured runtime completions
1 parent 9f4582f commit b753035

49 files changed

Lines changed: 847 additions & 240 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎examples/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ Each of these examples demonstrates one aspect or feature of bashly.
2525

2626
## Advanced configuration features
2727

28+
- [completions-advanced](completions-advanced#readme) - configuring static, dynamic, and option-based runtime completions
2829
- [catch-all](catch-all#readme) - a command that can receive an arbitrary number of arguments
2930
- [catch-all-advanced](catch-all-advanced#readme) - another example for the `catch_all` option
3031
- [catch-all-stdin](catch-all-stdin#readme) - combining `catch_all` with `stdin` to read multiple files

‎examples/completions-advanced/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
cli

‎examples/completions-advanced/README.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Advanced Runtime Completions Example
2+
3+
Demonstrates configured runtime completions, including static candidates,
4+
dynamic external commands and internal functions, file and directory sources,
5+
and the `no-space` option.
6+
7+
Runtime completions are enabled in `settings.yml`. Users can load the generated
8+
Bash wrapper with:
9+
10+
```bash
11+
source <(cli completions)
12+
```
13+
14+
<!-- include: settings.yml src/completions_command.sh src/lib/completions.sh -->
15+
16+
-----
17+
18+
## `bashly.yml`
19+
20+
````yaml
21+
name: cli
22+
help: Advanced runtime completions example
23+
version: 0.1.0
24+
25+
commands:
26+
- name: completions
27+
help: Generate a shell completion script
28+
args:
29+
- name: shell
30+
help: Shell to generate completions for
31+
allowed: [bash]
32+
default: bash
33+
34+
- name: deploy
35+
help: Deploy a branch
36+
args:
37+
- name: branch
38+
help: Branch to deploy
39+
required: true
40+
41+
# Run an external Bash command and add each output line as a candidate.
42+
completions:
43+
dynamic:
44+
- git branch --format='%(refname:short)'
45+
- name: environment
46+
help: Environment to deploy to
47+
48+
# Combine literal candidates with an internal function. Prevent the shell
49+
# from appending a space after the selected completion.
50+
completions:
51+
static: [staging, production]
52+
dynamic: [completion_environments]
53+
options: [no-space]
54+
flags:
55+
- long: --config
56+
arg: file
57+
help: Deployment configuration file
58+
59+
# Ask the shell to add file and directory candidates.
60+
completions:
61+
options: [files]
62+
- long: --directory
63+
arg: path
64+
help: Deployment directory
65+
66+
# Ask the shell to add directory candidates only.
67+
completions:
68+
options: [directories]
69+
````
70+
## `settings.yml`
71+
72+
````yaml
73+
enable_completions: always
74+
75+
````
76+
77+
## `src/completions_command.sh`
78+
79+
````bash
80+
send_completions "${args[shell]}"
81+
82+
````
83+
84+
## `src/lib/completions.sh`
85+
86+
````bash
87+
completion_environments() {
88+
printf 'development\nstaging\n'
89+
}
90+
91+
````
92+
93+
94+
## Output
95+
96+
### `$ ./cli completions | head -n3`
97+
98+
````shell
99+
_cli_completions() {
100+
local completion_command="${COMP_WORDS[0]}"
101+
local completion_current="${COMP_WORDS[COMP_CWORD]:-}"
102+
103+
104+
````
105+
106+
### `$ ./cli __complete ""`
107+
108+
````shell
109+
completions
110+
deploy
111+
:options=
112+
113+
114+
````
115+
116+
### `$ ./cli __complete deploy main st`
117+
118+
````shell
119+
staging
120+
:options=no-space
121+
122+
123+
````
124+
125+
### `$ ./cli __complete deploy --config ""`
126+
127+
````shell
128+
:options=files
129+
130+
131+
````
132+
133+
### `$ ./cli __complete deploy --directory ""`
134+
135+
````shell
136+
:options=directories
137+
138+
139+
````

‎examples/completions-advanced/settings.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
enable_completions: always

‎examples/completions-advanced/src/bashly.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: cli
2+
help: Advanced runtime completions example
3+
version: 0.1.0
4+
5+
commands:
6+
- name: completions
7+
help: Generate a shell completion script
8+
args:
9+
- name: shell
10+
help: Shell to generate completions for
11+
allowed: [bash]
12+
default: bash
13+
14+
- name: deploy
15+
help: Deploy a branch
16+
args:
17+
- name: branch
18+
help: Branch to deploy
19+
required: true
20+
21+
# Run an external Bash command and add each output line as a candidate.
22+
completions:
23+
dynamic:
24+
- git branch --format='%(refname:short)'
25+
- name: environment
26+
help: Environment to deploy to
27+
28+
# Combine literal candidates with an internal function. Prevent the shell
29+
# from appending a space after the selected completion.
30+
completions:
31+
static: [staging, production]
32+
dynamic: [completion_environments]
33+
options: [no-space]
34+
35+
flags:
36+
- long: --config
37+
arg: file
38+
help: Deployment configuration file
39+
40+
# Ask the shell to add file and directory candidates.
41+
completions:
42+
options: [files]
43+
44+
- long: --directory
45+
arg: path
46+
help: Deployment directory
47+
48+
# Ask the shell to add directory candidates only.
49+
completions:
50+
options: [directories]

‎examples/completions-advanced/src/completions_command.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
send_completions "${args[shell]}"

‎examples/completions-advanced/src/deploy_command.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
inspect_args

‎examples/completions-advanced/src/lib/completions.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
completion_environments() {
2+
printf 'development\nstaging\n'
3+
}

‎examples/completions-advanced/test.sh‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#!/usr/bin/env bash
2+
3+
set -x
4+
5+
bashly generate
6+
7+
### Try Me ###
8+
9+
./cli completions | head -n3
10+
./cli __complete ""
11+
./cli __complete deploy main st
12+
./cli __complete deploy --config ""
13+
./cli __complete deploy --directory ""

‎examples/completions/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,11 +79,12 @@ _cli_completions() {
7979

8080
````
8181

82-
### `$ ./cli __complete`
82+
### `$ ./cli __complete ""`
8383

8484
````shell
8585
completions
8686
download
87+
:options=
8788

8889

8990
````
@@ -95,6 +96,7 @@ download
9596
-h
9697
--force
9798
-f
99+
:options=
98100

99101

100102
````

0 commit comments

Comments
 (0)