# 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]( You may also want to check the
[YAML Wikipedia article](

**yamerl** is a pure [Erlang application](
which is able to parse [YAML 1.1]( and [YAML
1.2]( documents, as well as
JSON 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`.

[![Build Status](](

## Installation

### Rebar

If you use rebar, you can run the following command to build the
rebar compile

### Autotools

If you use the Autotools and `make(1)`, run the following commands to
build the application:
# Generate Autotools files.
autoreconf -vif

# Build the application.

# Install it.
sudo make install

The default installation path is your Erlang's distribution libraries
directory (see `code:lib_dir()`).

## Getting started

Before using yamerl, the application must be started:

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 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

yamerl_constr:string("Hello World!").
% 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:
# 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

% 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.

% 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
* 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:
# system.yaml
- os: FreeBSD
  version: 9.0-RELEASE-p3

Simple documents:
% List of documents.
 % List of mappings.
  % Mapping with two entries.
   {"os", "FreeBSD"},

Full documents:
yamerl_constr:file("system.yaml", [{detailed_constr, true}]).
% List of documents.
 % Document with a list as its root node.
  {yamerl_seq, yamerl_node_seq, ",2002:seq", [{line, 2}, {column, 1}], [
   % Mapping #1.
   {yamerl_map, yamerl_node_map, ",2002:map", [{line, 2}, {column, 3}], [
     % Mapping entry #1.
     {yamerl_str, yamerl_node_str, ",2002:str", [{line, 2}, {column, 3}], "os"},
     {yamerl_str, yamerl_node_str, ",2002:str", [{line, 2}, {column, 7}], "FreeBSD"}
    }, {
     % Mapping entry #2.
     {yamerl_str, yamerl_node_str, ",2002:str", [{line, 3}, {column, 3}], "version"},
     {yamerl_str, yamerl_node_str, ",2002:str", [{line, 3}, {column, 12}], "9.0-RELEASE-p3"}

## Complete documentation

See the `doc` subdirectory for a complete user guide and reference