Skip to content

Commit 41b0438

Browse files
DannyBenDannyBen
authored
Merge pull request #232 from DannyBen/update/expose-behavior
Update expose behavior to only show on --help
2 parents 7bd5203 + 6011426 commit 41b0438

File tree

17 files changed

+544
-26
lines changed

17 files changed

+544
-26
lines changed

‎examples/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,3 +62,4 @@ Each of these examples demonstrates one aspect or feature of bashly.
6262
- [heredoc](heredoc#readme) - using heredoc strings
6363
- [heredoc-alt](heredoc-alt#readme) - using heredoc strings in the lib directory
6464
- [settings](settings#readme) - using the `settings.yml` file to adjust bashly's behavior
65+
- [help-command](help-command#readme) - adding a help command to your script

‎examples/commands-expose/README.md‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -78,16 +78,10 @@ Usage:
7878
Commands:
7979
init Start a new project
8080
config Config management commands
81-
config edit Edit config file
82-
config show Show config file
8381
8482
Cluster Commands:
8583
server Server management commands
86-
server start Start the server
87-
server stop Stop the server
8884
container Container management commands
89-
container exec Run a command in the container
90-
container down Terminate a container
9185
9286
9387

‎examples/help-command/.gitignore‎

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

‎examples/help-command/README.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# Help Command Example
2+
3+
Demonstrates how to add a `help` command to your script. This is only needed
4+
if you prefer to have the `your-cli help COMMAND` syntax in addition to the
5+
natively supported `your-cli COMMAND --help` syntax.
6+
7+
This functionality is achieved by adding a custom validation filter that
8+
verifies the requested help function is callable.
9+
10+
This example was generated with:
11+
12+
```bash
13+
$ bashly init
14+
$ bashly add lib
15+
# ... now edit src/bashly.yml to match the example ...
16+
# ... now edit src/lib/validate_help_exists.sh to match the example ...
17+
$ bashly generate
18+
# ... now edit src/help_command.sh to match the example ...
19+
$ bashly generate
20+
21+
```
22+
23+
<!-- include: src/lib/validate_help_exists.sh src/help_command.sh -->
24+
25+
-----
26+
27+
## `bashly.yml`
28+
29+
```yaml
30+
name: cli
31+
help: Sample application
32+
version: 0.1.0
33+
34+
environment_variables:
35+
- name: api_key
36+
help: Set your API key
37+
38+
commands:
39+
# Here we are adding the help command
40+
- name: help
41+
alias: h
42+
help: Show help about a command
43+
args:
44+
45+
# The command argument will be validated with our custom validation
46+
# `help_exists`, which is placed in `src/lib/validate_help_exists.sh`
47+
- name: command
48+
validate: help_exists
49+
help: Help subject
50+
51+
# The rest of this file is not important for the purpose of this example
52+
53+
- name: download
54+
alias: d
55+
help: Download a file
56+
57+
args:
58+
- name: source
59+
required: true
60+
help: URL to download from
61+
- name: target
62+
help: "Target filename (default: same as source)"
63+
64+
flags:
65+
- long: --force
66+
short: -f
67+
help: Overwrite existing files
68+
69+
examples:
70+
- cli download example.com
71+
- cli download example.com ./output -f
72+
73+
environment_variables:
74+
- name: default_target_location
75+
help: Set the default location to download to
76+
77+
- name: upload
78+
alias: u
79+
help: Upload a file
80+
args:
81+
- name: source
82+
required: true
83+
help: File to upload
84+
85+
flags:
86+
- long: --user
87+
short: -u
88+
arg: user
89+
help: Username to use for logging in
90+
required: true
91+
- long: --password
92+
short: -p
93+
arg: password
94+
help: Password to use for logging in
95+
```
96+
97+
## `src/lib/validate_help_exists.sh`
98+
99+
```bash
100+
# This function will be called automatically with the argument under validation
101+
# as provided by the user.
102+
# It will then check that the internal bashly function responsible for showing
103+
# help exists, and echo an error if it does not.
104+
validate_help_exists() {
105+
command="$1"
106+
107+
if [[ -z "$command" ]]; then
108+
# The user called `cli help` - so the help function is the root cli_usage
109+
# function (replace 'cli' with the name of your script).
110+
function_name="cli_usage"
111+
112+
else
113+
# The user called `cli help COMMAND` - so we check that the command is valid
114+
# by ensuring we have a help function for it.
115+
function_name="cli_${command}_usage"
116+
fi
117+
118+
[[ $(type -t "$function_name") ]] || echo "no help for this command"
119+
}
120+
```
121+
122+
## `src/help_command.sh`
123+
124+
```bash
125+
command="${args[command]}"
126+
long_usage=yes
127+
128+
# If we have reached this point, we know that the help subject is valid, so
129+
# just call the relevant help function.
130+
if [[ -z "$command" ]]; then
131+
cli_usage
132+
else
133+
"cli_${command}_usage"
134+
fi
135+
136+
```
137+
138+
139+
## Generated script output
140+
141+
### `$ ./cli`
142+
143+
```shell
144+
cli - Sample application
145+
146+
Usage:
147+
cli [command]
148+
cli [command] --help | -h
149+
cli --version | -v
150+
151+
Commands:
152+
help Show help about a command
153+
download Download a file
154+
upload Upload a file
155+
156+
157+
158+
```
159+
160+
### `$ ./cli -h`
161+
162+
```shell
163+
cli - Sample application
164+
165+
Usage:
166+
cli [command]
167+
cli [command] --help | -h
168+
cli --version | -v
169+
170+
Commands:
171+
help Show help about a command
172+
download Download a file
173+
upload Upload a file
174+
175+
Options:
176+
--help, -h
177+
Show this help
178+
179+
--version, -v
180+
Show version number
181+
182+
Environment Variables:
183+
API_KEY
184+
Set your API key
185+
186+
187+
188+
```
189+
190+
### `$ ./cli help`
191+
192+
```shell
193+
cli - Sample application
194+
195+
Usage:
196+
cli [command]
197+
cli [command] --help | -h
198+
cli --version | -v
199+
200+
Commands:
201+
help Show help about a command
202+
download Download a file
203+
upload Upload a file
204+
205+
Options:
206+
--help, -h
207+
Show this help
208+
209+
--version, -v
210+
Show version number
211+
212+
Environment Variables:
213+
API_KEY
214+
Set your API key
215+
216+
217+
218+
```
219+
220+
### `$ ./cli help download`
221+
222+
```shell
223+
cli download - Download a file
224+
225+
Alias: d
226+
227+
Usage:
228+
cli download SOURCE [TARGET] [options]
229+
cli download --help | -h
230+
231+
Options:
232+
--help, -h
233+
Show this help
234+
235+
--force, -f
236+
Overwrite existing files
237+
238+
Arguments:
239+
SOURCE
240+
URL to download from
241+
242+
TARGET
243+
Target filename (default: same as source)
244+
245+
Environment Variables:
246+
DEFAULT_TARGET_LOCATION
247+
Set the default location to download to
248+
249+
Examples:
250+
cli download example.com
251+
cli download example.com ./output -f
252+
253+
254+
255+
```
256+
257+
### `$ ./cli help no_such_command`
258+
259+
```shell
260+
validation error in COMMAND:
261+
no help for this command
262+
263+
264+
```
265+
266+
267+

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

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: cli
2+
help: Sample application
3+
version: 0.1.0
4+
5+
environment_variables:
6+
- name: api_key
7+
help: Set your API key
8+
9+
commands:
10+
# Here we are adding the help command
11+
- name: help
12+
alias: h
13+
help: Show help about a command
14+
args:
15+
16+
# The command argument will be validated with our custom validation
17+
# `help_exists`, which is placed in `src/lib/validate_help_exists.sh`
18+
- name: command
19+
validate: help_exists
20+
help: Help subject
21+
22+
# The rest of this file is not important for the purpose of this example
23+
24+
- name: download
25+
alias: d
26+
help: Download a file
27+
28+
args:
29+
- name: source
30+
required: true
31+
help: URL to download from
32+
- name: target
33+
help: "Target filename (default: same as source)"
34+
35+
flags:
36+
- long: --force
37+
short: -f
38+
help: Overwrite existing files
39+
40+
examples:
41+
- cli download example.com
42+
- cli download example.com ./output -f
43+
44+
environment_variables:
45+
- name: default_target_location
46+
help: Set the default location to download to
47+
48+
- name: upload
49+
alias: u
50+
help: Upload a file
51+
args:
52+
- name: source
53+
required: true
54+
help: File to upload
55+
56+
flags:
57+
- long: --user
58+
short: -u
59+
arg: user
60+
help: Username to use for logging in
61+
required: true
62+
- long: --password
63+
short: -p
64+
arg: password
65+
help: Password to use for logging in

‎examples/help-command/src/download_command.sh‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
echo "# this file is located in 'src/download_command.sh'"
2+
echo "# code for 'cli download' goes here"
3+
echo "# you can edit it freely and regenerate (it will not be overwritten)"
4+
inspect_args

‎examples/help-command/src/help_command.sh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
command="${args[command]}"
2+
long_usage=yes
3+
4+
# If we have reached this point, we know that the help subject is valid, so
5+
# just call the relevant help function.
6+
if [[ -z "$command" ]]; then
7+
cli_usage
8+
else
9+
"cli_${command}_usage"
10+
fi

‎examples/help-command/src/initialize.sh‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
## Code here runs inside the initialize() function
2+
## Use it for anything that you need to run before any other function, like
3+
## setting environment vairables:
4+
## CONFIG_FILE=settings.ini
5+
##
6+
## Feel free to empty (but not delete) this file.

‎examples/help-command/src/lib/sample_function.sh‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## Add any function here that is needed in more than one parts of your
2+
## application, or that you otherwise wish to extract from the main function
3+
## scripts.
4+
##
5+
## Note that code here should be wrapped inside bash functions, and it is
6+
## recommended to have a separate file for each function.
7+
##
8+
## Subdirectories will also be scanned for *.sh, so you have no reason not
9+
## to organize your code neatly.
10+
##
11+
sample_function() {
12+
echo "it works"
13+
}

0 commit comments

Comments
 (0)