Skip to content

Commit eaa04f7

Browse files
DannyBenDannyBen
authored
Merge pull request #230 from DannyBen/add/deep_help
Add ability to show subcommands in parent command's help
2 parents 7de6544 + 169a684 commit eaa04f7

File tree

23 files changed

+489
-47
lines changed

23 files changed

+489
-47
lines changed

‎examples/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ Each of these examples demonstrates one aspect or feature of bashly.
3232
- [command-private](command-private#readme) - hiding commands from the command list
3333
- [stdin](stdin#readme) - reading input from stdin
3434
- [filters](filters#readme) - preventing commands from running unless custom conditions are met
35+
- [commands-expose](commands-expose#readme) - showing subcommands in the parent's help
3536

3637
## Customization
3738

‎examples/command-groups/README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,8 @@ commands:
2525
- name: download
2626
help: Download a file
2727

28-
# By specifying a group, the `download` comnmand (and all subsequent
29-
# commands until the next `group`) will be printed under this `File`
30-
# caption.
28+
# By specifying a group, the `download` comnmand will be printed under
29+
# this `File` caption.
3130
group: File
3231

3332
args:
@@ -37,6 +36,7 @@ commands:
3736

3837
- name: upload
3938
help: Upload a file
39+
group: File
4040

4141
args:
4242
- name: file
@@ -46,12 +46,12 @@ commands:
4646
- name: login
4747
help: Write login credentials to the config file
4848

49-
# The `login` command (and all subsequent commands) will be printed under
50-
# the `Login` caption.
49+
# The `login` command will be printed under the `Login` caption.
5150
group: Login
5251

5352
- name: logout
5453
help: Delete login credentials to the config file
54+
group: Login
5555
```
5656
5757

‎examples/command-groups/src/bashly.yml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,8 @@ commands:
66
- name: download
77
help: Download a file
88

9-
# By specifying a group, the `download` comnmand (and all subsequent
10-
# commands until the next `group`) will be printed under this `File`
11-
# caption.
9+
# By specifying a group, the `download` comnmand will be printed under
10+
# this `File` caption.
1211
group: File
1312

1413
args:
@@ -18,6 +17,7 @@ commands:
1817

1918
- name: upload
2019
help: Upload a file
20+
group: File
2121

2222
args:
2323
- name: file
@@ -27,10 +27,10 @@ commands:
2727
- name: login
2828
help: Write login credentials to the config file
2929

30-
# The `login` command (and all subsequent commands) will be printed under
31-
# the `Login` caption.
30+
# The `login` command will be printed under the `Login` caption.
3231
group: Login
3332

3433
- name: logout
3534
help: Delete login credentials to the config file
35+
group: Login
3636

‎examples/command-private/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ Usage:
6767
cli --version | -v
6868
6969
Commands:
70-
connect Connect to the metaverse
70+
connect Connect to the metaverse
7171
7272
7373
@@ -84,7 +84,7 @@ Usage:
8484
cli --version | -v
8585
8686
Commands:
87-
connect Connect to the metaverse
87+
connect Connect to the metaverse
8888
8989
Options:
9090
--help, -h

‎examples/commands-expose/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
cli
2+
src/*.sh

‎examples/commands-expose/README.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Commands Expose Example
2+
3+
Demonstrates how to show the summary help of subcommands in the `--help`
4+
message of their parent command.
5+
6+
This example was generated with:
7+
8+
```bash
9+
$ bashly init
10+
# ... now edit src/bashly.yml to match the example ...
11+
$ bashly generate
12+
```
13+
14+
-----
15+
16+
## `bashly.yml`
17+
18+
```yaml
19+
name: cli
20+
21+
commands:
22+
- name: init
23+
help: Start a new project
24+
25+
- name: config
26+
help: Config management commands
27+
28+
# Setting `expose` to true will show the summary of the subcommands when
29+
# running the help for the parent command. In this case, `config edit` and
30+
# `config show` will be displayed when running `cli --help`.
31+
expose: true
32+
commands:
33+
- name: edit
34+
help: Edit config file
35+
- name: show
36+
help: Show config file
37+
38+
- name: server
39+
help: Server management commands
40+
41+
# Adding a `group` works well with `expose`. In this case, `server start` and
42+
# `server stop` will be listed under `Cluster Commands`.
43+
expose: true
44+
group: Cluster
45+
46+
commands:
47+
- name: start
48+
help: Start the server
49+
- name: stop
50+
help: Stop the server
51+
52+
- name: container
53+
alias: c
54+
help: Container management commands
55+
expose: true
56+
group: Cluster
57+
commands:
58+
- name: exec
59+
help: Run a command in the container
60+
- name: down
61+
help: Terminate a container
62+
```
63+
64+
65+
66+
## Generated script output
67+
68+
### `$ ./cli`
69+
70+
```shell
71+
cli
72+
73+
Usage:
74+
cli [command]
75+
cli [command] --help | -h
76+
cli --version | -v
77+
78+
Commands:
79+
init Start a new project
80+
config Config management commands
81+
config edit Edit config file
82+
config show Show config file
83+
84+
Cluster Commands:
85+
server Server management commands
86+
server start Start the server
87+
server stop Stop the server
88+
container Container management commands
89+
container exec Run a command in the container
90+
container down Terminate a container
91+
92+
93+
94+
```
95+
96+
### `$ ./cli -h`
97+
98+
```shell
99+
cli
100+
101+
Usage:
102+
cli [command]
103+
cli [command] --help | -h
104+
cli --version | -v
105+
106+
Commands:
107+
init Start a new project
108+
config Config management commands
109+
config edit Edit config file
110+
config show Show config file
111+
112+
Cluster Commands:
113+
server Server management commands
114+
server start Start the server
115+
server stop Stop the server
116+
container Container management commands
117+
container exec Run a command in the container
118+
container down Terminate a container
119+
120+
Options:
121+
--help, -h
122+
Show this help
123+
124+
--version, -v
125+
Show version number
126+
127+
128+
129+
```
130+
131+
132+

‎examples/commands-expose/src/bashly.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: cli
2+
3+
commands:
4+
- name: init
5+
help: Start a new project
6+
7+
- name: config
8+
help: Config management commands
9+
10+
# Setting `expose` to true will show the summary of the subcommands when
11+
# running the help for the parent command. In this case, `config edit` and
12+
# `config show` will be displayed when running `cli --help`.
13+
expose: true
14+
commands:
15+
- name: edit
16+
help: Edit config file
17+
- name: show
18+
help: Show config file
19+
20+
- name: server
21+
help: Server management commands
22+
23+
# Adding a `group` works well with `expose`. In this case, `server start` and
24+
# `server stop` will be listed under `Cluster Commands`.
25+
expose: true
26+
group: Cluster
27+
28+
commands:
29+
- name: start
30+
help: Start the server
31+
- name: stop
32+
help: Stop the server
33+
34+
- name: container
35+
alias: c
36+
help: Container management commands
37+
expose: true
38+
group: Cluster
39+
commands:
40+
- name: exec
41+
help: Run a command in the container
42+
- name: down
43+
help: Terminate a container

‎examples/commands-expose/test.sh‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#!/usr/bin/env bash
2+
3+
rm -f ./src/*.sh
4+
5+
set -x
6+
7+
bashly generate
8+
9+
### Try Me ###
10+
11+
./cli
12+
./cli -h

‎examples/completions/README.md‎

Lines changed: 50 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -200,24 +200,58 @@ Options:
200200
# Modifying it manually is not recommended
201201

202202
_cli_completions() {
203-
local cur compline
204-
_init_completion -s || return
205-
cur=${COMP_WORDS[COMP_CWORD]}
206-
compline="${COMP_WORDS[@]:1:$COMP_CWORD-1}"
203+
local cur=${COMP_WORDS[COMP_CWORD]}
204+
local compline="${COMP_WORDS[@]:1:$COMP_CWORD-1}"
207205

208206
case "$compline" in
209-
'download'*'--handler') COMPREPLY=($(compgen -W "curl wget" -- "$cur")) ;;
210-
'upload'*'--user') COMPREPLY=($(compgen -A user -- "$cur")) ;;
211-
'completions'*) COMPREPLY=($(compgen -W "--help -h" -- "$cur")) ;;
212-
'd'*'--handler') COMPREPLY=($(compgen -W "curl wget" -- "$cur")) ;;
213-
'upload'*'-u') COMPREPLY=($(compgen -A user -- "$cur")) ;;
214-
'download'*) COMPREPLY=($(compgen -A file -W "--force --handler --help -f -h" -- "$cur")) ;;
215-
'u'*'--user') COMPREPLY=($(compgen -A user -- "$cur")) ;;
216-
'upload'*) COMPREPLY=($(compgen -A directory -A user -W "--help --password --user -h -p -u CHANGELOG.md README.md" -- "$cur")) ;;
217-
'u'*'-u') COMPREPLY=($(compgen -A user -- "$cur")) ;;
218-
'd'*) COMPREPLY=($(compgen -A file -W "--force --handler --help -f -h" -- "$cur")) ;;
219-
'u'*) COMPREPLY=($(compgen -A directory -A user -W "--help --password --user -h -p -u CHANGELOG.md README.md" -- "$cur")) ;;
220-
*) COMPREPLY=($(compgen -W "--help --version -h -v completions d download u upload" -- "$cur")) ;;
207+
'download'*'--handler')
208+
COMPREPLY=($(compgen -W "curl wget" -- "$cur"))
209+
;;
210+
211+
'upload'*'--user')
212+
COMPREPLY=($(compgen -A user -- "$cur"))
213+
;;
214+
215+
'completions'*)
216+
COMPREPLY=($(compgen -W "--help -h" -- "$cur"))
217+
;;
218+
219+
'd'*'--handler')
220+
COMPREPLY=($(compgen -W "curl wget" -- "$cur"))
221+
;;
222+
223+
'upload'*'-u')
224+
COMPREPLY=($(compgen -A user -- "$cur"))
225+
;;
226+
227+
'download'*)
228+
COMPREPLY=($(compgen -A file -W "--force --handler --help -f -h" -- "$cur"))
229+
;;
230+
231+
'u'*'--user')
232+
COMPREPLY=($(compgen -A user -- "$cur"))
233+
;;
234+
235+
'upload'*)
236+
COMPREPLY=($(compgen -A directory -A user -W "--help --password --user -h -p -u CHANGELOG.md README.md" -- "$cur"))
237+
;;
238+
239+
'u'*'-u')
240+
COMPREPLY=($(compgen -A user -- "$cur"))
241+
;;
242+
243+
'd'*)
244+
COMPREPLY=($(compgen -A file -W "--force --handler --help -f -h" -- "$cur"))
245+
;;
246+
247+
'u'*)
248+
COMPREPLY=($(compgen -A directory -A user -W "--help --password --user -h -p -u CHANGELOG.md README.md" -- "$cur"))
249+
;;
250+
251+
*)
252+
COMPREPLY=($(compgen -W "--help --version -h -v completions d download u upload" -- "$cur"))
253+
;;
254+
221255
esac
222256
} &&
223257
complete -F _cli_completions cli

‎lib/bashly/concerns/command_scopes.rb‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,23 @@ def command_aliases
1616
commands.map(&:aliases).flatten
1717
end
1818

19+
# Returns a data structure for displaying subcommands help
20+
def command_help_data
21+
result = {}
22+
23+
public_commands.each do |command|
24+
result[command.group_string] ||= {}
25+
result[command.group_string][command.name] = command.summary_string
26+
next unless command.expose
27+
28+
command.public_commands.each do |subcommand|
29+
result[command.group_string]["#{command.name} #{subcommand.name}"] = subcommand.summary_string
30+
end
31+
end
32+
33+
result
34+
end
35+
1936
# Returns only the names of the Commands
2037
def command_names
2138
commands.map &:name
@@ -70,6 +87,10 @@ def required_flags
7087
flags.select &:required
7188
end
7289

90+
def public_commands
91+
commands.reject &:private
92+
end
93+
7394
# Returns an array of all the args with a whitelist
7495
def whitelisted_args
7596
args.select &:allowed

0 commit comments

Comments
 (0)