Skip to content

Commit 52073cc

Browse files
DannyBenDannyBen
committed
- Add examples/stacktrace
1 parent b94baf2 commit 52073cc

File tree

9 files changed

+247
-0
lines changed

9 files changed

+247
-0
lines changed

‎examples/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ Each of these examples demonstrates one aspect or feature of bashly.
6767
- [completions](completions#readme) - adding bash completion functionality
6868
- [validations](validations#readme) - adding validation functions for arguments, flags or environment variables
6969
- [hooks](hooks#readme) - adding before/after hooks
70+
- [stacktrace](stacktrace#readme) - adding stacktrace on error
7071

7172
## Real-world-like examples
7273

‎examples/stacktrace/.gitignore‎

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

‎examples/stacktrace/README.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Stack Trace Example
2+
3+
Demonstrates how to show stack trace on error.
4+
5+
This example was generated with:
6+
7+
```bash
8+
$ bashly init --minimal
9+
$ bashly add stacktrace
10+
$ bashly generate
11+
# ... now create and edit src/initialize.sh to match the example ...
12+
# ... now edit src/root_command.sh to match the example ...
13+
$ bashly generate
14+
```
15+
16+
<!-- include: src/initialize.sh -->
17+
<!-- include: src/root_command.sh -->
18+
19+
-----
20+
21+
## `bashly.yml`
22+
23+
````yaml
24+
name: download
25+
help: Sample minimal application without commands
26+
version: 0.1.0
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+
- download example.com
42+
- download example.com ./output -f
43+
````
44+
45+
## `src/initialize.sh`
46+
47+
````bash
48+
## initialize hook
49+
##
50+
## Any code here will be placed inside the `initialize()` function and called
51+
## before running anything else.
52+
##
53+
## You can safely delete this file if you do not need it.
54+
trap 'stacktrace' ERR
55+
set -o errtrace
56+
57+
````
58+
59+
60+
## Output
61+
62+
### `$ ./download`
63+
64+
````shell
65+
missing required argument: SOURCE
66+
usage: download SOURCE [TARGET] [OPTIONS]
67+
68+
69+
````
70+
71+
### `$ ./download --help`
72+
73+
````shell
74+
download - Sample minimal application without commands
75+
76+
Usage:
77+
download SOURCE [TARGET] [OPTIONS]
78+
download --help | -h
79+
download --version | -v
80+
81+
Options:
82+
--force, -f
83+
Overwrite existing files
84+
85+
--help, -h
86+
Show this help
87+
88+
--version, -v
89+
Show version number
90+
91+
Arguments:
92+
SOURCE
93+
URL to download from
94+
95+
TARGET
96+
Target filename (default: same as source)
97+
98+
Examples:
99+
download example.com
100+
download example.com ./output -f
101+
102+
103+
104+
````
105+
106+
### `$ ./download something`
107+
108+
````shell
109+
./download: line 15: no_such_command: command not found
110+
./download:15 in `root_command`: no_such_command
111+
112+
Stack trace:
113+
from ./download:15 in `root_command`
114+
from ./download:254 in `run`
115+
from ./download:260 in `main`
116+
117+
118+
````
119+
120+
121+

‎examples/stacktrace/src/bashly.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: download
2+
help: Sample minimal application without commands
3+
version: 0.1.0
4+
5+
args:
6+
- name: source
7+
required: true
8+
help: URL to download from
9+
- name: target
10+
help: "Target filename (default: same as source)"
11+
12+
flags:
13+
- long: --force
14+
short: -f
15+
help: Overwrite existing files
16+
17+
examples:
18+
- download example.com
19+
- download example.com ./output -f

‎examples/stacktrace/src/initialize.sh‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## initialize hook
2+
##
3+
## Any code here will be placed inside the `initialize()` function and called
4+
## before running anything else.
5+
##
6+
## You can safely delete this file if you do not need it.
7+
trap 'stacktrace' ERR
8+
set -o errtrace

‎examples/stacktrace/src/lib/stacktrace.sh‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## Stack trace functions [@bashly-upgrade stacktrace]
2+
## This file is a part of Bashly standard library
3+
##
4+
## Usage:
5+
## This function is designed to be called on error.
6+
##
7+
## To enable this functionality, add these lines to your `src/initialize.sh`
8+
## file (Run `bashly add hooks` to add this file):
9+
##
10+
## trap 'stacktrace' ERR
11+
## set -o errtrace
12+
##
13+
## Note that this functionality also requires `set -e`, which is enabled by
14+
## default in bashly generated scripts.
15+
##
16+
stacktrace() {
17+
local i=0
18+
local caller_output line func file
19+
20+
printf "%s:%s in \`%s\`: %s\n" "${BASH_SOURCE[0]}" "${BASH_LINENO[0]}" "${FUNCNAME[1]}" "$BASH_COMMAND"
21+
printf "\nStack trace:\n"
22+
while caller_output="$(caller $i)"; do
23+
read -r line func file <<< "$caller_output"
24+
printf "\tfrom %s:%s in \`%s\`\n" "$file" "$line" "$func"
25+
i=$((i + 1))
26+
done
27+
exit 1
28+
} >&2

‎examples/stacktrace/src/root_command.sh‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
## trigger an error by calling a function that does not exist
2+
no_such_command

‎examples/stacktrace/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+
set -x
4+
5+
bashly add stacktrace --force
6+
bashly generate
7+
8+
### Try Me ###
9+
10+
./download
11+
./download --help
12+
./download something

‎spec/approvals/examples/stacktrace‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
+ bashly add stacktrace --force
2+
created src/lib/stacktrace.sh
3+
4+
The stacktrace function is designed to be called automatically on error.
5+
6+
To enable this functionality, add these lines to your `initialize.sh`:
7+
8+
trap 'stacktrace' ERR
9+
set -o errtrace
10+
11+
+ bashly generate
12+
creating user files in src
13+
skipped src/root_command.sh (exists)
14+
created ./download
15+
run ./download --help to test your bash script
16+
+ ./download
17+
missing required argument: SOURCE
18+
usage: download SOURCE [TARGET] [OPTIONS]
19+
+ ./download --help
20+
download - Sample minimal application without commands
21+
22+
Usage:
23+
download SOURCE [TARGET] [OPTIONS]
24+
download --help | -h
25+
download --version | -v
26+
27+
Options:
28+
--force, -f
29+
Overwrite existing files
30+
31+
--help, -h
32+
Show this help
33+
34+
--version, -v
35+
Show version number
36+
37+
Arguments:
38+
SOURCE
39+
URL to download from
40+
41+
TARGET
42+
Target filename (default: same as source)
43+
44+
Examples:
45+
download example.com
46+
download example.com ./output -f
47+
48+
+ ./download something
49+
./download: line 15: no_such_command: command not found
50+
./download:15 in `root_command`: no_such_command
51+
52+
Stack trace:
53+
from ./download:15 in `root_command`
54+
from ./download:254 in `run`
55+
from ./download:260 in `main`

0 commit comments

Comments
 (0)