# Fast YAML

[![Coverage Status](](
[![Hex version]( "Hex version")](

Fast YAML is an Erlang wrapper for
[libyaml]( "C" library.

It is designed to be fast and efficient.

## Installation

### Dependencies

Fast YAML depends on native LibYaml library. You need development
headers for LibYaml library to build it.

The minimum required Erlang/OTP version is 18.0

### Generic build

You can trigger build with:

    ./configure && make

### OSX build example

You can install LibYaml and with Homebrew:

    brew install libyaml

You can then export environment variable to use LibYaml as installed
by Homebrew, before issuing compilation commands:

    export LDFLAGS="-L/usr/local/lib"
    export CFLAGS="-I/usr/local/include"
    export CPPFLAGS="-I/usr/local/include"

    ./configure && make

## Example usage

erl -pa ebin -pa deps/*/ebin
Erlang/OTP 18 [erts-7.1] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false] [dtrace]

Eshell V7.1  (abort with ^G)

1> application:start(fast_yaml).

2> fast_yaml:decode(<<"a: 1\nb: -3.0">>).

## Option `plain_as_atom`

Converts all unquoted YAML values to atoms

3> fast_yaml:decode(<<"a: 1\nb: -3.0">>, [{plain_as_atom, true}]).

4> fast_yaml:decode(<<"a: b\nc">>).
{error,{scanner_error,<<"could not find expected ':'">>,2,

5> fast_yaml:decode_from_file("test/test2.yml", [plain_as_atom]).
{ok,[[[{step,[{instrument,<<"Lasik 2000">>},
      [{step,[{instrument,<<"Lasik 2000">>},

## Option `sane_scalars`

Converts the following scalar values to their Erlang-native data type:

`"null"` → `undefined`
`"true"` → `true`
`"false"` → `false`

Integer and float values also get converted. All other scalar values
stay binaries. Key in mappings also stay binary and never get coerced
into int / float / atom .

An unquoted mapping value that is an empty string gets converted into
`undefined`. (e.g. the string `"foo:"` decodes as `[{<<"foo">>, undefined}]`)

## Option `maps`

Convert YAML mappings into Erlang maps.

7> fast_yaml:decode(<<"a: true\nb: -3.0\nc: string">>, [{maps, true}]).
{ok, [#{"a" => "true", "b" => -3.0, "c" => "string"}]}

> For compatibility with the `yamerl` and `YamlElixir` libraries, use the `[sane_scalars, maps]` options.

## Development

### Test

#### Unit test

You can run eunit test with the command:

    make test

## EDoc documentation

You can check this library's 
[EDoc documentation](edoc.html), 
generated automatically from the source code comments.