Skip to content

Commit 58d7f20

Browse files
DannyBenDannyBen
authored
Merge pull request #530 from DannyBen/add/show-examples-on-error
Add `show_examples_on_error` setting
2 parents 5e9e322 + 8b01029 commit 58d7f20

File tree

17 files changed

+255
-4
lines changed

17 files changed

+255
-4
lines changed

‎examples/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ Each of these examples demonstrates one aspect or feature of bashly.
3838
- [filters](filters#readme) - preventing commands from running unless custom conditions are met
3939
- [commands-expose](commands-expose#readme) - showing sub-commands in the parent's help
4040
- [key-value-pairs](key-value-pairs#readme) - parsing key=value arguments and flags
41+
- [command-examples-on-error](command-examples-on-error#readme) - showing examples on error
4142

4243
## Customization
4344

‎examples/command-examples-on-error/.gitignore

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

‎examples/command-examples-on-error/README.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Command Examples on Error Example
2+
3+
Demonstrates how to show examples whenever the user does not provide all the
4+
required arguments.
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 add settings
12+
# ... now edit settings.yml to match the example ...
13+
$ bashly generate
14+
```
15+
16+
<!-- include: settings.yml -->
17+
18+
-----
19+
20+
## `bashly.yml`
21+
22+
````yaml
23+
name: cli
24+
help: Sample application
25+
version: 0.1.0
26+
27+
commands:
28+
- name: download
29+
alias: d
30+
help: Download a file
31+
32+
args:
33+
- name: source
34+
required: true
35+
help: URL to download from
36+
- name: target
37+
help: "Target filename (default: same as source)"
38+
39+
flags:
40+
- long: --force
41+
short: -f
42+
help: Overwrite existing files
43+
44+
# Examples can be provided either as an array, or as a string.
45+
# The array form is convenient when you just want to provide one-liner
46+
# examples.
47+
examples:
48+
- cli download example.com
49+
- cli download example.com ./output -f
50+
51+
- name: upload
52+
alias: u
53+
help: Upload a file
54+
args:
55+
- name: source
56+
required: true
57+
help: File to upload
58+
59+
flags:
60+
- long: --user
61+
short: -u
62+
arg: user
63+
help: Username to use for logging in
64+
required: true
65+
- long: --password
66+
short: -p
67+
arg: password
68+
help: Password to use for logging in
69+
70+
# The string form examples is useful when you wish to have more control
71+
# over how the examples are displayed. Note the use of the '|-' marker
72+
# that tells YAML to use the string as is, including the newlines it contains.
73+
examples: |-
74+
Upload a file
75+
$ cli upload profile.png -u admin -p s3cr3t
76+
77+
Upload a file (you will be prompted to provide a password)
78+
$ cli upload profile.png --user admin
79+
````
80+
81+
## `settings.yml`
82+
83+
````yaml
84+
show_examples_on_error: true
85+
86+
````
87+
88+
89+
## Output
90+
91+
### `$ ./cli download`
92+
93+
````shell
94+
missing required argument: SOURCE
95+
usage: cli download SOURCE [TARGET] [OPTIONS]
96+
examples:
97+
cli download example.com
98+
cli download example.com ./output -f
99+
100+
101+
````
102+
103+
### `$ ./cli upload`
104+
105+
````shell
106+
missing required argument: SOURCE
107+
usage: cli upload SOURCE [OPTIONS]
108+
examples:
109+
Upload a file
110+
$ cli upload profile.png -u admin -p s3cr3t
111+
112+
Upload a file (you will be prompted to provide a password)
113+
$ cli upload profile.png --user admin
114+
115+
116+
````
117+
118+
119+

‎examples/command-examples-on-error/settings.yml

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

‎examples/command-examples-on-error/src/bashly.yml

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: cli
2+
help: Sample application
3+
version: 0.1.0
4+
5+
commands:
6+
- name: download
7+
alias: d
8+
help: Download a file
9+
10+
args:
11+
- name: source
12+
required: true
13+
help: URL to download from
14+
- name: target
15+
help: "Target filename (default: same as source)"
16+
17+
flags:
18+
- long: --force
19+
short: -f
20+
help: Overwrite existing files
21+
22+
# Examples can be provided either as an array, or as a string.
23+
# The array form is convenient when you just want to provide one-liner
24+
# examples.
25+
examples:
26+
- cli download example.com
27+
- cli download example.com ./output -f
28+
29+
- name: upload
30+
alias: u
31+
help: Upload a file
32+
args:
33+
- name: source
34+
required: true
35+
help: File to upload
36+
37+
flags:
38+
- long: --user
39+
short: -u
40+
arg: user
41+
help: Username to use for logging in
42+
required: true
43+
- long: --password
44+
short: -p
45+
arg: password
46+
help: Password to use for logging in
47+
48+
# The string form examples is useful when you wish to have more control
49+
# over how the examples are displayed. Note the use of the '|-' marker
50+
# that tells YAML to use the string as is, including the newlines it contains.
51+
examples: |-
52+
Upload a file
53+
$ cli upload profile.png -u admin -p s3cr3t
54+
55+
Upload a file (you will be prompted to provide a password)
56+
$ cli upload profile.png --user admin
57+
58+

‎examples/command-examples-on-error/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/command-examples-on-error/src/upload_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/upload_command.sh'"
2+
echo "# code for 'cli upload' goes here"
3+
echo "# you can edit it freely and regenerate (it will not be overwritten)"
4+
inspect_args

‎examples/command-examples-on-error/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 download
12+
./cli upload

‎lib/bashly/libraries/settings/settings.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,10 @@ env: development
5555
# The extension to use when reading/writing partial script snippets
5656
partials_extension: sh
5757

58+
# Show command examples (if any) whenever the user does not provide the
59+
# required arguments
60+
show_examples_on_error: false
61+
5862
# Display various usage elements in color by providing the name of the color
5963
# function. The value for each property is a name of a function that is
6064
# available in your script, for example: `green` or `bold`.

‎lib/bashly/libraries/strings/strings.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ missing_required_argument: "missing required argument: %{arg}\\nusage: %{usage}"
3333
missing_required_flag: "missing required flag: %{usage}"
3434
missing_required_environment_variable: "missing required environment variable: %{var}"
3535
missing_dependency: "missing dependency: %{dependency}"
36+
examples_caption_on_error: 'examples:'
3637
disallowed_flag: "%{name} must be one of: %{allowed}"
3738
disallowed_argument: "%{name} must be one of: %{allowed}"
3839
disallowed_environment_variable: "%{name} environment variable must be one of: %{allowed}"

0 commit comments

Comments
 (0)