Skip to content

Commit 5728ace

Browse files
DannyBenDannyBen
authored
Merge pull request #284 from DannyBen/add/examples-as-string
Allow command.examples to be a string
2 parents 687ed09 + 213e2b5 commit 5728ace

File tree

14 files changed

+570
-1
lines changed

14 files changed

+570
-1
lines changed

‎examples/README.md‎

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

1313
- [command-default](command-default#readme) - configuring a default command
1414
- [command-aliases](command-aliases#readme) - allowing a command to be called with multiple names
15+
- [command-examples](command-examples#readme) - configuring command examples
1516
- [dependencies](dependencies#readme) - halting script execution unless certain dependencies are installed
1617
- [environment-variables](environment-variables#readme) - halting script execution unless certain environment variables are set
1718
- [default-values](default-values#readme) - arguments and flags with default values

‎examples/command-examples/.gitignore‎

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

‎examples/command-examples/README.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Command Examples Example
2+
3+
Demonstrates how to add examples to your command.
4+
5+
This example was generated with:
6+
7+
```bash
8+
$ bashly init
9+
# ... now edit src/bashly.yml to match the example ...
10+
$ bashly generate
11+
```
12+
13+
-----
14+
15+
## `bashly.yml`
16+
17+
```yaml
18+
name: cli
19+
help: Sample application
20+
version: 0.1.0
21+
22+
commands:
23+
- name: download
24+
alias: d
25+
help: Download a file
26+
27+
args:
28+
- name: source
29+
required: true
30+
help: URL to download from
31+
- name: target
32+
help: "Target filename (default: same as source)"
33+
34+
flags:
35+
- long: --force
36+
short: -f
37+
help: Overwrite existing files
38+
39+
# Examples can be provided either as an array, or as a string.
40+
# The array form is convenient when you just want to provide one-liner
41+
# examples.
42+
examples:
43+
- cli download example.com
44+
- cli download example.com ./output -f
45+
46+
- name: upload
47+
alias: u
48+
help: Upload a file
49+
args:
50+
- name: source
51+
required: true
52+
help: File to upload
53+
54+
flags:
55+
- long: --user
56+
short: -u
57+
arg: user
58+
help: Username to use for logging in
59+
required: true
60+
- long: --password
61+
short: -p
62+
arg: password
63+
help: Password to use for logging in
64+
65+
# The string form examples is useful when you wish to have more control
66+
# over how the examples are displayed. Note the use of the '|-' marker
67+
# that tells YAML to use the string as is, including the newlines it contains.
68+
examples: |-
69+
Upload a file
70+
$ cli upload profile.png --user admin
71+
72+
Upload a file and prompt for password
73+
$ cli upload profile.png -u admin -p
74+
```
75+
76+
77+
78+
## Generated script output
79+
80+
### `$ ./cli download -h`
81+
82+
```shell
83+
cli download - Download a file
84+
85+
Alias: d
86+
87+
Usage:
88+
cli download SOURCE [TARGET] [OPTIONS]
89+
cli download --help | -h
90+
91+
Options:
92+
--help, -h
93+
Show this help
94+
95+
--force, -f
96+
Overwrite existing files
97+
98+
Arguments:
99+
SOURCE
100+
URL to download from
101+
102+
TARGET
103+
Target filename (default: same as source)
104+
105+
Examples:
106+
cli download example.com
107+
cli download example.com ./output -f
108+
109+
110+
111+
```
112+
113+
### `$ ./cli upload -h`
114+
115+
```shell
116+
cli upload - Upload a file
117+
118+
Alias: u
119+
120+
Usage:
121+
cli upload SOURCE [OPTIONS]
122+
cli upload --help | -h
123+
124+
Options:
125+
--help, -h
126+
Show this help
127+
128+
--user, -u USER (required)
129+
Username to use for logging in
130+
131+
--password, -p PASSWORD
132+
Password to use for logging in
133+
134+
Arguments:
135+
SOURCE
136+
File to upload
137+
138+
Examples:
139+
Upload a file
140+
$ cli upload profile.png --user admin
141+
142+
Upload a file and prompt for password
143+
$ cli upload profile.png -u admin -p
144+
145+
146+
147+
```
148+
149+
150+

‎examples/command-examples/download‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
#!/usr/bin/env bash
2+
# This script was generated by bashly 0.8.8 (https://bashly.dannyb.co)
3+
# Modifying it manually is not recommended
4+
5+
# :wrapper.bash3_bouncer
6+
if [[ "${BASH_VERSINFO:-0}" -lt 4 ]]; then
7+
printf "bash version 4 or higher is required\n" >&2
8+
exit 1
9+
fi
10+
11+
# :command.master_script
12+
# :command.root_command
13+
root_command() {
14+
# src/root_command.sh
15+
echo "# this file is located in 'src/root_command.sh'"
16+
echo "# you can edit it freely and regenerate (it will not be overwritten)"
17+
inspect_args
18+
19+
}
20+
21+
# :command.version_command
22+
version_command() {
23+
echo "$version"
24+
}
25+
26+
# :command.usage
27+
download_usage() {
28+
if [[ -n $long_usage ]]; then
29+
printf "download - Sample minimal application without commands\n"
30+
echo
31+
32+
else
33+
printf "download - Sample minimal application without commands\n"
34+
echo
35+
36+
fi
37+
38+
printf "Usage:\n"
39+
printf " download SOURCE [TARGET] [OPTIONS]\n"
40+
printf " download --help | -h\n"
41+
printf " download --version | -v\n"
42+
echo
43+
44+
# :command.long_usage
45+
if [[ -n $long_usage ]]; then
46+
printf "Options:\n"
47+
48+
# :command.usage_fixed_flags
49+
echo " --help, -h"
50+
printf " Show this help\n"
51+
echo
52+
echo " --version, -v"
53+
printf " Show version number\n"
54+
echo
55+
56+
# :command.usage_flags
57+
# :flag.usage
58+
echo " --force, -f"
59+
printf " Overwrite existing files\n"
60+
echo
61+
62+
# :command.usage_args
63+
printf "Arguments:\n"
64+
65+
# :argument.usage
66+
echo " SOURCE"
67+
printf " URL to download from\n"
68+
echo
69+
70+
# :argument.usage
71+
echo " TARGET"
72+
printf " Target filename (default: same as source)\n"
73+
echo
74+
75+
# :command.usage_examples
76+
printf "Examples:\n"
77+
printf " download example.com\n"
78+
printf " download example.com ./output -f\n"
79+
echo
80+
81+
fi
82+
}
83+
84+
# :command.normalize_input
85+
normalize_input() {
86+
local arg flags
87+
88+
while [[ $# -gt 0 ]]; do
89+
arg="$1"
90+
if [[ $arg =~ ^(--[a-zA-Z0-9_\-]+)=(.+)$ ]]; then
91+
input+=("${BASH_REMATCH[1]}")
92+
input+=("${BASH_REMATCH[2]}")
93+
elif [[ $arg =~ ^(-[a-zA-Z0-9])=(.+)$ ]]; then
94+
input+=("${BASH_REMATCH[1]}")
95+
input+=("${BASH_REMATCH[2]}")
96+
elif [[ $arg =~ ^-([a-zA-Z0-9][a-zA-Z0-9]+)$ ]]; then
97+
flags="${BASH_REMATCH[1]}"
98+
for (( i=0 ; i < ${#flags} ; i++ )); do
99+
input+=("-${flags:i:1}")
100+
done
101+
else
102+
input+=("$arg")
103+
fi
104+
105+
shift
106+
done
107+
}
108+
# :command.inspect_args
109+
inspect_args() {
110+
readarray -t sorted_keys < <(printf '%s\n' "${!args[@]}" | sort)
111+
if (( ${#args[@]} )); then
112+
echo args:
113+
for k in "${sorted_keys[@]}"; do echo "- \${args[$k]} = ${args[$k]}"; done
114+
else
115+
echo args: none
116+
fi
117+
118+
if (( ${#other_args[@]} )); then
119+
echo
120+
echo other_args:
121+
echo "- \${other_args[*]} = ${other_args[*]}"
122+
for i in "${!other_args[@]}"; do
123+
echo "- \${other_args[$i]} = ${other_args[$i]}"
124+
done
125+
fi
126+
}
127+
128+
# :command.command_functions
129+
130+
# :command.parse_requirements
131+
parse_requirements() {
132+
# :command.fixed_flags_filter
133+
case "${1:-}" in
134+
--version | -v )
135+
version_command
136+
exit
137+
;;
138+
139+
--help | -h )
140+
long_usage=yes
141+
download_usage
142+
exit
143+
;;
144+
145+
esac
146+
147+
# :command.command_filter
148+
action="root"
149+
150+
# :command.parse_requirements_while
151+
while [[ $# -gt 0 ]]; do
152+
key="$1"
153+
case "$key" in
154+
# :flag.case
155+
--force | -f )
156+
157+
# :flag.case_no_arg
158+
args[--force]=1
159+
shift
160+
;;
161+
162+
-?* )
163+
printf "invalid option: %s\n" "$key" >&2
164+
exit 1
165+
;;
166+
167+
* )
168+
# :command.parse_requirements_case
169+
# :command.parse_requirements_case_simple
170+
if [[ -z ${args[source]+x} ]]; then
171+
172+
args[source]=$1
173+
shift
174+
elif [[ -z ${args[target]+x} ]]; then
175+
176+
args[target]=$1
177+
shift
178+
else
179+
printf "invalid argument: %s\n" "$key" >&2
180+
exit 1
181+
fi
182+
183+
;;
184+
185+
esac
186+
done
187+
# :command.required_args_filter
188+
if [[ -z ${args[source]+x} ]]; then
189+
printf "missing required argument: SOURCE\nusage: download SOURCE [TARGET] [OPTIONS]\n" >&2
190+
exit 1
191+
fi
192+
193+
}
194+
195+
# :command.initialize
196+
initialize() {
197+
version="0.1.0"
198+
long_usage=''
199+
set -e
200+
201+
# src/initialize.sh
202+
203+
}
204+
205+
# :command.run
206+
run() {
207+
declare -A args=()
208+
declare -a other_args=()
209+
declare -a input=()
210+
normalize_input "$@"
211+
parse_requirements "${input[@]}"
212+
213+
if [[ $action == "root" ]]; then
214+
root_command
215+
fi
216+
}
217+
218+
initialize
219+
run "$@"

0 commit comments

Comments
 (0)