mirror of
https://github.com/gohugoio/hugo.git
synced 2025-04-26 21:51:02 +03:00
Merge commit '35dec7c96f'
This commit is contained in:
Bjørn Erik Pedersen
commit
d19ed4d4e6
810 changed files with 24147 additions and 7766 deletions
|
|
@ -1,83 +1,289 @@
|
|||
---
|
||||
title: transform.Unmarshal
|
||||
description: Parses the input and converts it into a map or an array. Supported formats are JSON, TOML, YAML, XML and CSV.
|
||||
categories: [functions]
|
||||
description: Parses serialized data and returns a map or an array. Supports CSV, JSON, TOML, YAML, and XML.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
function:
|
||||
action:
|
||||
aliases: [unmarshal]
|
||||
related:
|
||||
- functions/transform/Remarshal
|
||||
- functions/resources/Get
|
||||
- functions/resources/GetRemote
|
||||
- functions/encoding/Jsonify
|
||||
returnType: any
|
||||
signatures:
|
||||
- RESOURCE or STRING | transform.Unmarshal [OPTIONS]
|
||||
- RESOURCE or STRING | unmarshal [OPTIONS]
|
||||
relatedFunctions:
|
||||
- encoding.Jsonify
|
||||
- transform.Remarshal
|
||||
- transform.Unmarshal
|
||||
signatures: ['transform.Unmarshal [OPTIONS] INPUT']
|
||||
toc: true
|
||||
aliases: [/functions/transform.unmarshal]
|
||||
---
|
||||
|
||||
The function accepts either a `Resource` created in [Hugo Pipes](/hugo-pipes/) or via [Page Bundles](/content-management/page-bundles/), or simply a string. The two examples below will produce the same map:
|
||||
The input can be a string or a [resource].
|
||||
|
||||
## Unmarshal a string
|
||||
|
||||
```go-html-template
|
||||
{{ $greetings := "hello = \"Hello Hugo\"" | transform.Unmarshal }}`
|
||||
{{ $string := `
|
||||
title: Les Misérables
|
||||
author: Victor Hugo
|
||||
`}}
|
||||
|
||||
{{ $book := unmarshal $string }}
|
||||
{{ $book.title }} → Les Misérables
|
||||
{{ $book.author }} → Victor Hugo
|
||||
```
|
||||
|
||||
## Unmarshal a resource
|
||||
|
||||
Use the `transform.Unmarshal` function with global, page, and remote resources.
|
||||
|
||||
### Global resource
|
||||
|
||||
A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
|
||||
|
||||
```text
|
||||
assets/
|
||||
└── data/
|
||||
└── books.json
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $greetings := "hello = \"Hello Hugo\"" | resources.FromString "data/greetings.toml" | transform.Unmarshal }}
|
||||
{{ $data := "" }}
|
||||
{{ $path := "data/books.json" }}
|
||||
{{ with resources.Get $path }}
|
||||
{{ with unmarshal . }}
|
||||
{{ $data = . }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get global resource %q" $path }}
|
||||
{{ end }}
|
||||
|
||||
{{ range where $data "author" "Victor Hugo" }}
|
||||
{{ .title }} → Les Misérables
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
In both the above examples, you get a map you can work with:
|
||||
### Page resource
|
||||
|
||||
A page resource is a file within a [page bundle].
|
||||
|
||||
```text
|
||||
content/
|
||||
├── post/
|
||||
│ └── book-reviews/
|
||||
│ ├── books.json
|
||||
│ └── index.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $greetings.hello }}
|
||||
{{ $data := "" }}
|
||||
{{ $path := "books.json" }}
|
||||
{{ with .Resources.Get $path }}
|
||||
{{ with unmarshal . }}
|
||||
{{ $data = . }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get page resource %q" $path }}
|
||||
{{ end }}
|
||||
|
||||
{{ range where $data "author" "Victor Hugo" }}
|
||||
{{ .title }} → Les Misérables
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The above prints `Hello Hugo`.
|
||||
### Remote resource
|
||||
|
||||
## CSV options
|
||||
A remote resource is a file on a remote server, accessible via HTTP or HTTPS.
|
||||
|
||||
Unmarshal with CSV as input has some options you can set:
|
||||
```go-html-template
|
||||
{{ $data := "" }}
|
||||
{{ $url := "https://example.org/books.json" }}
|
||||
{{ with resources.GetRemote $url }}
|
||||
{{ with .Err }}
|
||||
{{ errorf "%s" . }}
|
||||
{{ else }}
|
||||
{{ $data = . | transform.Unmarshal }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %q" $url }}
|
||||
{{ end }}
|
||||
|
||||
{{ range where $data "author" "Victor Hugo" }}
|
||||
{{ .title }} → Les Misérables
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[resource]: /getting-started/glossary/#resource
|
||||
[page bundle]: /content-management/page-bundles
|
||||
|
||||
## Options
|
||||
|
||||
When unmarshaling a CSV file, provide an optional map of options.
|
||||
|
||||
delimiter
|
||||
: The delimiter used, default is `,`.
|
||||
: (`string`) The delimiter used, default is `,`.
|
||||
|
||||
comment
|
||||
: The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.:
|
||||
|
||||
Example:
|
||||
: (`string`) The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.
|
||||
|
||||
```go-html-template
|
||||
{{ $csv := "a;b;c" | transform.Unmarshal (dict "delimiter" ";") }}
|
||||
```
|
||||
|
||||
## XML data
|
||||
## Working with XML
|
||||
|
||||
As a convenience, Hugo allows you to access XML data in the same way that you access JSON, TOML, and YAML: you do not need to specify the root node when accessing the data.
|
||||
|
||||
To get the contents of `<title>` in the document below, you use `{{ .message.title }}`:
|
||||
When unmarshaling an XML file, do not include the root node when accessing data. For example, after unmarshaling the RSS feed below, access the feed title with `$data.channel.title`.
|
||||
|
||||
```xml
|
||||
<root>
|
||||
<message>
|
||||
<title>Hugo rocks!</title>
|
||||
<description>Thanks for using Hugo</description>
|
||||
</message>
|
||||
</root>
|
||||
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
|
||||
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
|
||||
<channel>
|
||||
<title>Books on Example Site</title>
|
||||
<link>https://example.org/books/</link>
|
||||
<description>Recent content in Books on Example Site</description>
|
||||
<language>en-US</language>
|
||||
<atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" />
|
||||
<item>
|
||||
<title>The Hunchback of Notre Dame</title>
|
||||
<description>Written by Victor Hugo</description>
|
||||
<link>https://example.org/books/the-hunchback-of-notre-dame/</link>
|
||||
<pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate>
|
||||
<guid>https://example.org/books/the-hunchback-of-notre-dame/</guid>
|
||||
</item>
|
||||
<item>
|
||||
<title>Les Misérables</title>
|
||||
<description>Written by Victor Hugo</description>
|
||||
<link>https://example.org/books/les-miserables/</link>
|
||||
<pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate>
|
||||
<guid>https://example.org/books/les-miserables/</guid>
|
||||
</item>
|
||||
</channel>
|
||||
</rss>
|
||||
```
|
||||
|
||||
The following example lists the items of an RSS feed:
|
||||
Get the remote data:
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.GetRemote "https://example.com/rss.xml" | transform.Unmarshal }}
|
||||
{{ range .channel.item }}
|
||||
<strong>{{ .title | plainify | htmlUnescape }}</strong><br>
|
||||
<p>{{ .description | plainify | htmlUnescape }}</p>
|
||||
{{ $link := .link | plainify | htmlUnescape }}
|
||||
<a href="{{ $link }}">{{ $link }}</a><br>
|
||||
<hr>
|
||||
{{ $data := "" }}
|
||||
{{ $url := "https://example.org/books/index.xml" }}
|
||||
{{ with resources.GetRemote $url }}
|
||||
{{ with .Err }}
|
||||
{{ errorf "%s" . }}
|
||||
{{ else }}
|
||||
{{ $data = . | transform.Unmarshal }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %q" $url }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Inspect the data structure:
|
||||
|
||||
```go-html-template
|
||||
<pre>{{ jsonify (dict "indent" " ") $data }}</pre>
|
||||
```
|
||||
|
||||
List the book titles:
|
||||
|
||||
```go-html-template
|
||||
{{ with $data.channel.item }}
|
||||
<ul>
|
||||
{{ range . }}
|
||||
<li>{{ .title }}</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li>The Hunchback of Notre Dame</li>
|
||||
<li>Les Misérables</li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
### XML attributes and namespaces
|
||||
|
||||
Let's add a `lang` attribute to the `title` nodes of our RSS feed, and a namespaced node for the ISBN number:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
|
||||
<rss version="2.0"
|
||||
xmlns:atom="http://www.w3.org/2005/Atom"
|
||||
xmlns:isbn="http://schemas.isbn.org/ns/1999/basic.dtd"
|
||||
>
|
||||
<channel>
|
||||
<title>Books on Example Site</title>
|
||||
<link>https://example.org/books/</link>
|
||||
<description>Recent content in Books on Example Site</description>
|
||||
<language>en-US</language>
|
||||
<atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" />
|
||||
<item>
|
||||
<title lang="fr">The Hunchback of Notre Dame</title>
|
||||
<description>Written by Victor Hugo</description>
|
||||
<isbn:number>9780140443530</isbn:number>
|
||||
<link>https://example.org/books/the-hunchback-of-notre-dame/</link>
|
||||
<pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate>
|
||||
<guid>https://example.org/books/the-hunchback-of-notre-dame/</guid>
|
||||
</item>
|
||||
<item>
|
||||
<title lang="en">Les Misérables</title>
|
||||
<description>Written by Victor Hugo</description>
|
||||
<isbn:number>9780451419439</isbn:number>
|
||||
<link>https://example.org/books/les-miserables/</link>
|
||||
<pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate>
|
||||
<guid>https://example.org/books/les-miserables/</guid>
|
||||
</item>
|
||||
</channel>
|
||||
</rss>
|
||||
```
|
||||
|
||||
After retrieving the remote data, inspect the data structure:
|
||||
|
||||
```go-html-template
|
||||
<pre>{{ jsonify (dict "indent" " ") $data }}</pre>
|
||||
```
|
||||
|
||||
Each item node looks like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Written by Victor Hugo",
|
||||
"guid": "https://example.org/books/the-hunchback-of-notre-dame/",
|
||||
"link": "https://example.org/books/the-hunchback-of-notre-dame/",
|
||||
"number": "9780140443530",
|
||||
"pubDate": "Mon, 09 Oct 2023 09:27:12 -0700",
|
||||
"title": {
|
||||
"#text": "The Hunchback of Notre Dame",
|
||||
"-lang": "fr"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The title keys do not begin with an underscore or a letter---they are not valid [identifiers]. Use the [`index`] function to access the values:
|
||||
|
||||
```go-html-template
|
||||
{{ with $data.channel.item }}
|
||||
<ul>
|
||||
{{ range . }}
|
||||
{{ $title := index .title "#text" }}
|
||||
{{ $lang := index .title "-lang" }}
|
||||
{{ $ISBN := .number }}
|
||||
<li>{{ $title }} ({{ $lang }}) {{ $ISBN }}</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li>The Hunchback of Notre Dame (fr) 9780140443530</li>
|
||||
<li>Les Misérables (en) 9780451419439</li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
[`index`]: /functions/collections/indexfunction
|
||||
[identifiers]: https://go.dev/ref/spec#Identifiers
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue