# yamerl: YAML 1.2 parser in Erlang
YAML is a human-friendly data serialization format. The specification
for this language and many examples are available from the [Official
YAML web site](http://www.yaml.org/). You may also want to check the
[YAML Wikipedia article](http://en.wikipedia.org/wiki/YAML).
**yamerl** is a pure [Erlang application](http://www.erlang.org/)
which is able to parse [YAML 1.1](http://yaml.org/spec/1.1/) and
[YAML 1.2](http://www.yaml.org/spec/1.2/spec.html) documents, as well
as [JSON](http://json.org/) documents. It only depends on standard
Erlang/OTP applications; no external dependency is required. It doesn't
use native code either (neither port drivers nor NIFs).
yamerl is distributed under the terms of the **2-clause BSD license**;
see `COPYING`.
[](https://travis-ci.org/yakaz/yamerl)
## Integrate to your project
yamerl uses [Rebar 3](http://www.rebar3.org/) as its build system so
it can be integrated to many common build systems.
### Rebar
yamerl is available as a [Hex.pm package](https://hex.pm/packages/yamerl).
Thus you can simply list it as a package dependency in your `rebar.config`:
```erlang
{deps, [yamerl]}.
```
### Erlang.mk
Erlang.mk knows about yamerl. You just need to add `yamerl` as a
dependency in your `Makefile`:
```make
DEPS = yamerl
```
### Mix
yamerl is available as a [Hex.pm package](https://hex.pm/packages/yamerl).
Thus you can simply list its name in your `mix.exs`:
```elixir
def project do
[
deps: [{:yamerl, ">= 0.4.0"}]
]
end
```
## Getting started
Before using yamerl, the application must be started:
```erlang
application:start(yamerl).
```
Now, one can use the `yamerl_constr` module to parse and construct a
list of documents from:
* an in-memory document (string or binary);
* a regualr file;
* a stream.
Because a YAML input stream may contain multiple documents,
`yamerl_constr` always returns a list of documents, even if the input
stream only contains one.
### Parsing an in-memory document
```erlang
yamerl_constr:string("Hello World!").
```
```erlang
% List of documents; here, only one document.
[
% Document #1; contains a single scalar.
"Hello World!"
]
```
Here, the returned value is a list of documents containing one document.
This document has a scalar as its sole node.
### Parsing a file
Considering the following YAML file:
```yaml
# applications.yaml
- application: kernel
version: 2.15.3
path: /usr/local/lib/erlang/lib/kernel-2.15.3
- application: stdlib
version: 1.18.3
path: /usr/local/lib/erlang/lib/stdlib-1.18.3
- application: sasl
version: 2.2.1
path: /usr/local/lib/erlang/lib/sasl-2.2.1
```
```erlang
yamerl_constr:file("applications.yaml").
```
```erlang
% List of documents; again, only one document here.
[
% List of mappings.
[
% Mapping, represented as a proplist: each entry has the form {Key, Value}.
[
{"application", "kernel"},
{"version", "2.15.3"},
{"path", "/usr/local/lib/erlang/lib/kernel-2.15.3"}
], [
{"application", "stdlib"},
{"version", "1.18.3"},
{"path", "/usr/local/lib/erlang/lib/stdlib-1.18.3"}
], [
{"application", "sasl"},
{"version", "2.2.1"},
{"path", "/usr/local/lib/erlang/lib/sasl-2.2.1"}
]
]
]
```
### Parsing a stream
The developer is responsible for reading the stream and provide the
chunks to yamerl.
```erlang
% Initialize a new construction state. It takes a term describing the
% source; it may be any Erlang term.
Parser0 = yamerl_constr:new({file, "<stdin>"}),
% Read chunks and feed the parser. A new parser state is returned.
{continue, Parser1} = yamerl_constr:next_chunk(Parser0, Chunk1),
% ...
{continue, Parser2} = yamerl_constr:next_chunk(Parser1, Chunk2),
% When the stream ends, tell the parser it's the last chunk.
Documents = yamerl_constr:last_chunk(Parser2, Chunk3).
```
## Simple vs. full document structures
`yamerl_constr` comes with two built-in modes:
* It can output simple documents, eg. documents based on basic Erlang
structures (strings, numbers, lists, proplists). This is the default
mode.
* It can output detailed documents using records. These records carry
more information such as line/column, tag URI, YAML node type, module
used to construct it, etc.
If we use the following YAML document:
```yaml
# system.yaml
- os: FreeBSD
version: 9.0-RELEASE-p3
```
Simple documents:
```erlang
yamerl_constr:file("system.yaml").
```
```erlang
% List of documents.
[
% List of mappings.
[
% Mapping with two entries.
[
{"os", "FreeBSD"},
{"version","9.0-RELEASE-p3"}
]
]
]
```
Full documents:
```erlang
yamerl_constr:file("system.yaml", [{detailed_constr, true}]).
```
```erlang
% List of documents.
[
% Document with a list as its root node.
{yamerl_doc,
{yamerl_seq, yamerl_node_seq, "tag:yaml.org,2002:seq", [{line, 2}, {column, 1}], [
% Mapping #1.
{yamerl_map, yamerl_node_map, "tag:yaml.org,2002:map", [{line, 2}, {column, 3}], [
{
% Mapping entry #1.
{yamerl_str, yamerl_node_str, "tag:yaml.org,2002:str", [{line, 2}, {column, 3}], "os"},
{yamerl_str, yamerl_node_str, "tag:yaml.org,2002:str", [{line, 2}, {column, 7}], "FreeBSD"}
}, {
% Mapping entry #2.
{yamerl_str, yamerl_node_str, "tag:yaml.org,2002:str", [{line, 3}, {column, 3}], "version"},
{yamerl_str, yamerl_node_str, "tag:yaml.org,2002:str", [{line, 3}, {column, 12}], "9.0-RELEASE-p3"}
}
]}
],
1}
}
]
```
## Complete documentation
See https://hexdocs.pm/yamerl/ for a complete user guide and reference
manual.
