|
| 1 | +--- |
| 2 | +title: try |
| 3 | +description: Returns a TryValue object after evaluating the given expression. |
| 4 | +categories: [] |
| 5 | +keywords: [] |
| 6 | +action: |
| 7 | + aliases: [] |
| 8 | + related: [] |
| 9 | + returnType: TryValue |
| 10 | + signatures: ['try EXPRESSION'] |
| 11 | +toc: true |
| 12 | +--- |
| 13 | + |
| 14 | +{{< new-in 0.141.0 >}} |
| 15 | + |
| 16 | +The `try` statement is a non-standard extension to Go's [text/template] package. It introduces a mechanism for handling errors within templates, mimicking the `try-catch` constructs found in other programming languages. |
| 17 | + |
| 18 | +[text/template]: https://pkg.go.dev/text/template |
| 19 | + |
| 20 | +## Methods |
| 21 | + |
| 22 | +The `TryValue` object encapsulates the result of evaluating the expression, and provides two methods: |
| 23 | + |
| 24 | +Err |
| 25 | +: (`string`) Returns a string representation of the error thrown by the expression, if an error occurred, or returns `nil` if the expression evaluated without errors. |
| 26 | + |
| 27 | +Value |
| 28 | +: (`any`) Returns the result of the expression if the evaluation was successful, or returns `nil` if an error occurred while evaluating the expression. |
| 29 | + |
| 30 | +## Explanation |
| 31 | + |
| 32 | +By way of example, let's divide a number by zero: |
| 33 | + |
| 34 | +```go-html-template |
| 35 | +{{ $x := 1 }} |
| 36 | +{{ $y := 0 }} |
| 37 | +{{ $result := div $x $y }} |
| 38 | +{{ printf "%v divided by %v equals %v" $x $y .Value }} |
| 39 | +``` |
| 40 | + |
| 41 | +As expected, the example above throws an error and fails the build: |
| 42 | + |
| 43 | +```terminfo |
| 44 | +Error: error calling div: can't divide the value by 0 |
| 45 | +``` |
| 46 | + |
| 47 | +Instead of failing the build, we can catch the error and emit a warning: |
| 48 | + |
| 49 | +```go-html-template |
| 50 | +{{ $x := 1 }} |
| 51 | +{{ $y := 0 }} |
| 52 | +{{ with try (div $x $y) }} |
| 53 | + {{ with .Err }} |
| 54 | + {{ warnf "%s" . }} |
| 55 | + {{ else }} |
| 56 | + {{ printf "%v divided by %v equals %v" $x $y .Value }} |
| 57 | + {{ end }} |
| 58 | +{{ end }} |
| 59 | +``` |
| 60 | + |
| 61 | +The error thrown by the expression is logged to the console as a warning: |
| 62 | + |
| 63 | +```terminfo |
| 64 | +WARN error calling div: can't divide the value by 0 |
| 65 | +``` |
| 66 | + |
| 67 | +Now let's change the arguments to avoid dividing by zero: |
| 68 | + |
| 69 | +```go-html-template |
| 70 | +{{ $x := 42 }} |
| 71 | +{{ $y := 6 }} |
| 72 | +{{ with try (div $x $y) }} |
| 73 | + {{ with .Err }} |
| 74 | + {{ warnf "%s" . }} |
| 75 | + {{ else }} |
| 76 | + {{ printf "%v divided by %v equals %v" $x $y .Value }} |
| 77 | + {{ end }} |
| 78 | +{{ end }} |
| 79 | +``` |
| 80 | + |
| 81 | +Hugo renders the above to: |
| 82 | + |
| 83 | +```html |
| 84 | +42 divided by 6 equals 7 |
| 85 | +``` |
| 86 | + |
| 87 | +## Example |
| 88 | + |
| 89 | +Error handling is essential when using the [`resources.GetRemote`] function to capture remote resources such as data or images. When calling this function, if the HTTP request fails, Hugo will fail the build. |
| 90 | + |
| 91 | +[`resources.GetRemote`]: /functions/resources/getremote/ |
| 92 | + |
| 93 | +Instead of failing the build, we can catch the error and emit a warning: |
| 94 | + |
| 95 | +```go-html-template |
| 96 | +{{ $url := "https://broken-example.org/images/a.jpg" }} |
| 97 | +{{ with try (resources.GetRemote $url) }} |
| 98 | + {{ with .Err }} |
| 99 | + {{ warnf "%s" . }} |
| 100 | + {{ else with .Value }} |
| 101 | + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> |
| 102 | + {{ else }} |
| 103 | + {{ errorf "Unable to get remote resource %q" $url }} |
| 104 | + {{ end }} |
| 105 | +{{ end }} |
| 106 | +``` |
| 107 | + |
| 108 | +{{% note %}} |
| 109 | +Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil. |
| 110 | +{{% /note %}} |
0 commit comments