Document "try" and update resources.GetRemote examples

Closes gohugoio#2808

Author: jmooring

content/en/content-management/content-adapters.md

@@ -193,14 +193,14 @@ Step 3
 {{/* Get remote data. */}}
 {{ $data := dict }}
 {{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "Unable to get remote resource %s: %s" $url . }}
-  {{ else }}
+  {{ else with .Value }}
     {{ $data = . | transform.Unmarshal }}
+  {{ else }}
+    {{ errorf "Unable to get remote resource %s" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %s" $url }}
 {{ end }}
 
 {{/* Add pages and page resources. */}}
@@ -223,10 +223,10 @@ Step 3
   {{/* Add page resource. */}}
   {{ $item := . }}
   {{ with $url := $item.cover }}
-    {{ with resources.GetRemote $url }}
+    {{ with try (resources.GetRemote $url) }}
       {{ with .Err }}
         {{ errorf "Unable to get remote resource %s: %s" $url . }}
-      {{ else }}
+      {{ else with .Value }}
         {{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
         {{ $params := dict "alt" $item.title }}
         {{ $resource := dict
@@ -235,9 +235,9 @@ Step 3
           "path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
         }}
         {{ $.AddResource $resource }}
+      {{ else }}
+        {{ errorf "Unable to get remote resource %s" $url }}
       {{ end }}
-    {{ else }}
-      {{ errorf "Unable to get remote resource %s" $url }}
     {{ end }}
   {{ end }}
 

content/en/content-management/image-processing/index.md

@@ -88,15 +88,15 @@ Example 3: A more concise way to skip image rendering if the resource is not fou
 Example 4: Skips rendering if there's problem accessing a remote resource.
 
 ```go-html-template
-{{ $u := "https://gohugo.io/img/hugo-logo.png" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://gohugo.io/img/hugo-logo.png" }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $u }}
 {{ end }}
 ```
 

content/en/functions/data/GetCSV.md

@@ -134,16 +134,16 @@ Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`]
 
 ```go-html-template
 {{ $data := dict }}
-{{ $u := "https://example.org/pets.csv" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://example.org/pets.csv" }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     {{ $opts := dict "delimiter" "," }}
     {{ $data = . | transform.Unmarshal $opts }}
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $u }}
 {{ end }}
 ```
 

content/en/functions/data/GetJSON.md

@@ -137,15 +137,15 @@ Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`]
 
 ```go-html-template
 {{ $data := dict }}
-{{ $u := "https://example.org/books.json" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://example.org/books.json" }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     {{ $data = . | transform.Unmarshal }}
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $u }}
 {{ end }}
 ```
 

content/en/functions/encoding/Base64Decode.md

@@ -25,16 +25,16 @@ https://api.github.com/repos/gohugoio/hugo/readme
 To retrieve and render the content:
 
 ```go-html-template
-{{ $u := "https://api.github.com/repos/gohugoio/hugo/readme" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://api.github.com/repos/gohugoio/hugo/readme" }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value}}
     {{ with . | transform.Unmarshal }}
       {{ .content | base64Decode | markdownify }}
     {{ end }}
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $u }}
 {{ end }}
 ```

content/en/functions/go-template/return.md

@@ -13,7 +13,7 @@ action:
 toc: true
 ---
 
-The `return` statement is a custom addition to Go's [text/template] package. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
+The `return` statement is a non-standard extension to Go's [text/template package]. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
 
 The returned value may be of any data type including, but not limited to, [`bool`], [`float`], [`int`], [`map`], [`resource`], [`slice`], and [`string`].
 

content/en/functions/go-template/try.md

@@ -0,0 +1,106 @@
+---
+title: try
+description: Returns a TryValue object after evaluating the given expression.
+categories: []
+keywords: []
+action:
+  aliases: []
+  related: []
+  returnType: TryValue
+  signatures: ['try EXPRESSION']
+toc: true
+---
+
+{{< new-in 0.141.0 >}}
+
+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.
+
+[text/template]: https://pkg.go.dev/text/template
+
+## Methods
+
+The `TryValue` object encapsulates the result of evaluating the expression, and provides two methods:
+
+Err
+: (`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.
+
+Value
+: (`any`) Returns the result of the expression if the evaluation was successful, or returns `nil` if an error occurred while evaluating the expression.
+
+## Explanation
+
+By way of example, let's divide a number by zero:
+
+```go-html-template
+{{ $x := 1 }}
+{{ $y := 0 }}
+{{ $result := div $x $y }}
+{{ printf "%v divided by %v equals %v" $x $y .Value }}
+```
+
+As expected, the example above throws an error and fails the build:
+
+```terminfo
+Error: error calling div: can't divide the value by 0
+```
+
+Instead of failing the build, we can catch the error and emit a warning:
+
+```go-html-template
+{{ $x := 1 }}
+{{ $y := 0 }}
+{{ with try (div $x $y) }}
+  {{ with .Err }}
+    {{ warnf "%s" . }}
+  {{ else }}
+    {{ printf "%v divided by %v equals %v" $x $y .Value }}
+  {{ end }}
+{{ end }}
+```
+
+The error thrown by the expression is logged to the console as a warning:
+
+```terminfo
+WARN error calling div: can't divide the value by 0
+```
+
+Now let's change the arguments to avoid dividing by zero:
+
+```go-html-template
+{{ $x := 42 }}
+{{ $y := 6 }}
+{{ with try (div $x $y) }}
+  {{ with .Err }}
+    {{ warnf "%s" . }}
+  {{ else }}
+    {{ printf "%v divided by %v equals %v" $x $y .Value }}
+  {{ end }}
+{{ end }}
+```
+
+Hugo renders the above to:
+
+```html
+42 divided by 6 equals 7
+```
+
+## Example
+
+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.
+
+[`resources.GetRemote`]: /functions/resources/getremote/
+
+Instead of failing the build, we can catch the error and emit a warning:
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with try (resources.GetRemote $url) }}
+  {{ with .Err }}
+    {{ warnf "%s" . }}
+  {{ else with .Value }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
+  {{ end }}
+{{ end }}
+```

content/en/functions/images/Text.md

@@ -48,14 +48,14 @@ Capture the font as a resource:
 ```go-html-template
 {{ $font := "" }}
 {{ $path := "https://github.com/google/fonts/raw/main/ofl/lato/Lato-Regular.ttf" }}
-{{ with resources.GetRemote $path }}
+{{ with try (resources.GetRemote $path) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     {{ $font = . }}
+  {{ else }}
+    {{ errorf "Unable to get resource %q" $path }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get resource %q" $path }}
 {{ end }}
 ```
 

content/en/functions/openapi3/Unmarshal.md

@@ -22,14 +22,14 @@ For example, to work with a remote [OpenAPI] definition:
 ```go-html-template
 {{ $url := "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json" }}
 {{ $api := "" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     {{ $api = . | openapi3.Unmarshal }}
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $url }}
 {{ end }}
 ```
 

content/en/functions/resources/GetRemote.md

@@ -20,14 +20,14 @@ toc: true
 
 ```go-html-template
 {{ $url := "https://example.org/images/a.jpg" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $url }}
 {{ end }}
 ```
 
@@ -75,14 +75,14 @@ When retrieving remote data, use the [`transform.Unmarshal`] function to [unmars
 ```go-html-template
 {{ $data := dict }}
 {{ $url := "https://example.org/books.json" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     {{ $data = . | transform.Unmarshal }}
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $url }}
 {{ end }}
 ```
 
@@ -98,39 +98,39 @@ In these cases, pass the resource `Content` through the `transform.Unmarshal` fu
 
 ## Error handling
 
-The [`Err`] method on a resource returned by the `resources.GetRemote` function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build.
+Use the [`try`] statement to capture HTTP request errors. If you do not handle the error yourself, Hugo will fail the build.
 
-[`Err`]: /methods/resource/err/
+[`try`]: /functions/go-template/try
 
 {{% note %}}
 Hugo does not classify an HTTP response with status code 404 as an error. In this case the function returns nil.
 {{% /note %}}
 
 ```go-html-template
 {{ $url := "https://broken-example.org/images/a.jpg" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $url }}
 {{ end }}
 ```
 
 To log an error as a warning instead of an error:
 
 ```go-html-template
 {{ $url := "https://broken-example.org/images/a.jpg" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ warnf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ else }}
+    {{ warnf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $url }}
 {{ end }}
 ```
 
@@ -142,20 +142,20 @@ The [`Data`] method on a resource returned by the `resources.GetRemote` function
 
 ```go-html-template
 {{ $url := "https://example.org/images/a.jpg" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     {{ with .Data }}
       {{ .ContentLength }} → 42764
       {{ .ContentType }} → image/jpeg
       {{ .Status }} → 200 OK
       {{ .StatusCode }} → 200
       {{ .TransferEncoding }} → []
     {{ end }}
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $url }}
 {{ end }}
 ```