1 | ---
|
2 | default_highlighter: oils-sh
|
3 | ---
|
4 |
|
5 | Guide to YSH Error Handling
|
6 | ===========================
|
7 |
|
8 | There are just a few concepts to know:
|
9 |
|
10 | - [error][] builtin - "Throw" an error, with a custom message, error code, and
|
11 | other properties.
|
12 | - [try][] builtin - Run a block, and set the [_error][] register to a `Dict`.
|
13 | - `_error.code` will be `0` on success, or non-zero if an error is thrown in
|
14 | the block.
|
15 | - [failed][] builtin - A handy shortcut to test for a non-zero error code.
|
16 |
|
17 | [try]: ref/chap-builtin-cmd.html#try
|
18 | [_error]: ref/chap-special-var.html#_error
|
19 |
|
20 | [error]: ref/chap-builtin-cmd.html#error
|
21 | [failed]: ref/chap-builtin-cmd.html#failed
|
22 |
|
23 | <div id="toc">
|
24 | </div>
|
25 |
|
26 | ## Examples
|
27 |
|
28 | ### Handle command and expression errors with `try`
|
29 |
|
30 | Here's the most basic form:
|
31 |
|
32 | try {
|
33 | ls /zz
|
34 | }
|
35 | if (_error.code !== 0) {
|
36 | echo "ls failed with $[_error.code]"
|
37 | }
|
38 | # => ls failed with error 2
|
39 |
|
40 |
|
41 | ### The `failed` builtin is a shortcut
|
42 |
|
43 | Instead of writing `if (_error.code !== 0)`, you can write `if failed`:
|
44 |
|
45 | if failed {
|
46 | echo "ls failed with $[_error.code]"
|
47 | }
|
48 |
|
49 | This saves you 7 punctuation characters: `( _ . !== )`
|
50 |
|
51 | ### Use a `case` statement if it's not just pass/fail
|
52 |
|
53 | Sometimes it's nicer to use `case` rather than `if`:
|
54 |
|
55 | try {
|
56 | grep '[0-9]+' foo.txt
|
57 | }
|
58 | case (_error.code) {
|
59 | (0) { echo 'found' }
|
60 | (1) { echo 'not found' }
|
61 | (else) { echo 'error invoking grep' }
|
62 | }
|
63 |
|
64 | ### Error may have more attributes, like `_error.message`
|
65 |
|
66 | try {
|
67 | var x = fromJson('{')
|
68 | }
|
69 | if failed {
|
70 | echo "JSON failure: $[_error.message]"
|
71 | }
|
72 | # => JSON failure: expected string, got EOF
|
73 |
|
74 | ### The `error` builtin throws custom errors
|
75 |
|
76 | A non-zero exit code results in a simple shell-style error:
|
77 |
|
78 | proc simple-failure {
|
79 | return 2
|
80 | }
|
81 |
|
82 | try {
|
83 | simple-failure
|
84 | }
|
85 | echo "status is $[_error.code]"
|
86 | # => status is 2
|
87 |
|
88 | The `error` builtin is more informative:
|
89 |
|
90 | proc better-failure {
|
91 | error 'Custom message' (code=99, foo='zz')
|
92 | }
|
93 |
|
94 | try {
|
95 | better-failure
|
96 | }
|
97 | echo "$[_error.code] $[_error.message] foo=$[_error.foo]"
|
98 | # => 99 Custom message foo=zz"
|
99 |
|
100 | ## Related
|
101 |
|
102 | - [YSH vs. Shell Idioms > Error Handling](idioms.html#error-handling)
|
103 | - [YSH Fixes Shell's Error Handling (`errexit`)](error-handling.html) - Long
|
104 | design doc.
|
105 |
|
106 |
|