The yamerl application

Authors: Jean-Sébastien Pédron (jean-sebastien.pedron@dumbbell.fr).

Introduction

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). At this time, it has no support to serialize a YAML document.

yamerl is distributed under the terms of the 2-clause BSD license; see COPYING.

When to use yamerl or not

Advantages

Pure Erlang implementation:
- should scale more easily than a port-driver based implementation;
- won't take the whole VM down in case of a crash.
YAML 1.2 support, which is not widely supported in many other languages.

Caveats

Current implementation is slow, compared to yamler (NIF-based) or any JSON-only parsers.
Adding schemas is not easy.
No support for YAML serialization.

Features

Supports YAML 1.2 parsing:
```
yamerl_constr:string("YAML snippet").
```

Supports [YAML 1.1 parsing:

yamerl_constr:string("YAML snippet", [{schema, yaml11}]).

Supports JSON parsing:

yamerl_constr:string(<<"JSON snippet">>, [{schema, json}]).

Supports Erlang atom node type, either when tagged as atom, or if autodetected in plain scalars, and, if asked, only if the atom already exists:

% Enable support for Erlang atoms.
yamerl_app:set_param(node_mods, [yamerl_node_erlang_atom]),
yamerl_constr:string("!<tag:yamerl,2012:atom> atom").

% Autodetect Erlang atoms in plain scalars.
yamerl_app:set_param(node_mods, [yamerl_node_erlang_atom]),
yamerl_constr:string("atom", [{erlang_atom_autodetection, true}]).

% Atoms must already exist.
yamerl_app:set_param(node_mods, [yamerl_node_erlang_atom]),
yamerl_constr:string("atom", [
    {erlang_atom_autodetection, true},
    {erlang_atom_only_if_exist, true}
]).

Supports Erlang fun() node type:

% Enable support for Erlang fun().
yamerl_app:set_param(node_mods, [yamerl_node_erlang_fun]),
[Plus_One_Fun] = yamerl_constr:string(<<"!<tag:yamerl,2012:fun> fun(X) -> X + 1 end.">>),

Plus_One_Fun(2). % Return 3.

Provides a yamler compatibility layer:

% Both calls return the same value.
yaml:load_file("input.yaml", [{schema, yaml_schema_failsafe}]),
yamerl_yamler_compat:load_file("input.yaml", [{schema, yaml_schema_failsafe}])

Prerequisites

Before using yamerl, the application must be started:

application:start(yamerl).

This is required so that application environment variables are available.

Now, you can use the yamerl_constr module to parse and construct a list of documents from:

an in-memory document (string or binary);
a regular 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.

Examples

Basic parsing

Start the yamerl application. This is a mandatory step.
```
application:start(yamerl).
```

You're now ready to parse a serialized document:

To parse an in-memory string or binary:

Documents = yamerl_constr:string("Hello!").
% Documents is a list of constructed documents.

To parse a file:

Documents = yamerl_constr:file("input.yaml").
% Documents is a list of constructed documents.

To parse a stream:

% Create a new construction state. The only required argument is an
% arbitrary term describing the source of the data. Here, we use the
% same term structure as yamerl_constr:file/{1, 2}.
Constr_State = yamerl_constr:new({file, "<stdin>"}),

% Feed the parser with binary chunks. The developer is responsible for
% reading the chunk from the backing source.
%
% The function returns an updated construction state, which replaces the
% previous one.
%
% yamerl_constr:next_chunk/2 can be called as many times as necessary.
{continue, Constr_State2} = yamerl_constr:next_chunk(Constr_State, Chunk),

% When the last chunk is reached, call yamerl_constr:last_chunk/2.
Documents = yamerl_constr:last_chunk(Constr_State2, Last_Chunk).
% Documents is a list of constructed documents.

See yamerl_constr for more information.

Error handling

yamerl throws an exception when an error occurs.

Start the yamerl application. This is a mandatory step.
```
application:start(yamerl).
```

You're now ready to parse a serialized document. To parse an in-memory string or binary:

-include_lib("yamerl/include/yamerl_errors.hrl").

% ...

try
  Documents = yamerl_constr:string("Hello!"),
  % Documents is a list of constructed documents.
  Documents
catch
  throw:#yamerl_exception{errors = Errors} ->
    % Do something with the exception.
    Errors
end.

As you can see, the #yamerl_exception{} record embeds all encountered errors:

#yamerl_exception{
  errors = [] % List of errors.
}.

Errors are records where the two first members are always:

type, either error or warning;
text, a human-readable error message.

Following members depend on the error record. Two records are currently defined:

#yamerl_invalid_option{};
#yamerl_parsing_error{}.

See yamerl_constr for more information.

Alternatives to yamerl

YAML parsers

yamler:
- Based on libyaml, wrapped in a NIF
- Supports YAML 1.1
- Faster than yamerl
- Supports Erlang atoms, however, single-quoted scalar are treated as atom, which breaks the YAML specifications
- Doesn't support Erlang fun()

JSON parsers

There are too many to choose from now to list them here. Use your preferred search engine :-)

Generated by EDoc