glazer_yaml (glazer v0.5.2)

View Source

Fast YAML encoding and decoding using the glaze C++ library.

By default nulls are represented as the atom null. To change it application-wide, set the null env key in your config:

{glazer, [{null, nil}]}.

Features

  • Decoding YAML mappings/sequences/scalars to Erlang maps/lists/scalars, including big integers
  • Encoding Erlang terms to YAML in block style
  • Configurable representation of YAML null and mapping keys, with optional YAML 1.1 boolean compatibility (yes/no/on/off)
  • read_file/1,2 and write_file/2,3 helpers for decoding/encoding directly to/from a file

Example

1> glazer_yaml:decode(<<"a: 1\nb:\n  - true\n  - null\n  - 3.5\n">>).
#{<<"a">> => 1, <<"b">> => [true, null, 3.5]}

2> glazer_yaml:encode(#{<<"a">> => 1, <<"b">> => [true, null, 3.5]}).
<<"a: 1\nb:\n  - true\n  - null\n  - 3.5\n">>

See also [https://github.com/stephenberry/glaze]

Summary

Types

decode_opt()
decode_opts()

YAML decode options

encode_opt()
encode_opts()

YAML encode options

Functions

decode(Input)

Decode a YAML binary or iolist to an Erlang term. YAML mappings are returned as maps (default). Raises {parse_error, Reason} on invalid input.

decode(Input, Opts)

Decode a YAML binary or iolist to an Erlang term with options. Raises {parse_error, Msg} on invalid input.

encode(Data)

Encode an Erlang term to a YAML binary in block style (2-space indentation, sequences at the same indentation as the mapping key that owns them).

encode(Data, Opts)

Encode an Erlang term to a YAML binary in block style with options.

read_file(Filename)

Read Filename and decode its contents as YAML.

read_file(Filename, Opts)

Read Filename and decode its contents as YAML, with decode options (see decode/2).

try_decode(Input)

Decode a YAML binary or iolist, returning {ok, Term} or {error, Msg} instead of raising.

try_decode(Input, Opts)

Decode a YAML binary or iolist with options, returning {ok, Term} or {error, Msg} instead of raising.

write_file(Filename, Data)

Encode Data to YAML and write it to Filename, overwriting any existing file.

write_file(Filename, Data, Opts)

Encode Data to YAML with encode options (see encode/2) and write it to Filename, overwriting any existing file.

Types

decode_opt()

-type decode_opt() ::
          use_nil | {null_term, atom()} | {keys, atom | existing_atom | binary} | yaml_1_1_bools.

decode_opts()

-type decode_opts() :: [decode_opt()].

YAML decode options:

  • use_nil - use the atom nil for YAML null/~/empty values
  • {null_term, Atom} - use Atom for YAML null/~/empty values
  • {keys, atom} - decode mapping keys as atoms
  • {keys, existing_atom} - decode mapping keys as existing atoms, fall back to binary
  • {keys, binary} - decode mapping keys as binaries (default)
  • yaml_1_1_bools - additionally treat yes/no/on/off (and case variants) as booleans, per the YAML 1.1 core schema. By default (YAML 1.2 core schema) only true/false are recognized as booleans.

encode_opt()

-type encode_opt() :: use_nil | {null_term, atom()}.

encode_opts()

-type encode_opts() :: [encode_opt()].

YAML encode options:

  • use_nil - treat the atom nil as YAML null
  • {null_term, Atom} - treat Atom as YAML null

Functions

decode(Input)

-spec decode(binary() | iolist()) -> term().

Decode a YAML binary or iolist to an Erlang term. YAML mappings are returned as maps (default). Raises {parse_error, Reason} on invalid input.

decode(Input, Opts)

-spec decode(binary() | iolist(), decode_opts()) -> term().

Decode a YAML binary or iolist to an Erlang term with options. Raises {parse_error, Msg} on invalid input.

Example

1> glazer_yaml:decode(<<"a: ~\n">>, [use_nil]).
#{<<"a">> => nil}

2> glazer_yaml:decode(<<"a: 1\n">>, [{keys, atom}]).
#{a => 1}

3> glazer_yaml:decode(<<"a: yes\n">>, [yaml_1_1_bools]).
#{<<"a">> => true}

encode(Data)

-spec encode(term()) -> binary().

Encode an Erlang term to a YAML binary in block style (2-space indentation, sequences at the same indentation as the mapping key that owns them).

encode(Data, Opts)

-spec encode(term(), encode_opts()) -> binary().

Encode an Erlang term to a YAML binary in block style with options.

Example

1> glazer_yaml:encode(#{<<"a">> => nil}, [use_nil]).
<<"a: null\n">>

read_file(Filename)

-spec read_file(file:name_all()) -> term().

Read Filename and decode its contents as YAML.

Raises {parse_error, Reason} if the file's contents aren't valid YAML, or a binary "Filename: Reason" message (see file:format_error/1) if the file can't be read.

Example

1> glazer_yaml:read_file("data.yaml").
#{<<"a">> => 1}

read_file(Filename, Opts)

-spec read_file(file:name_all(), decode_opts()) -> term().

Read Filename and decode its contents as YAML, with decode options (see decode/2).

try_decode(Input)

-spec try_decode(binary() | iolist()) -> {ok, term()} | {error, binary()}.

Decode a YAML binary or iolist, returning {ok, Term} or {error, Msg} instead of raising.

try_decode(Input, Opts)

-spec try_decode(binary() | iolist(), decode_opts()) -> {ok, term()} | {error, binary()}.

Decode a YAML binary or iolist with options, returning {ok, Term} or {error, Msg} instead of raising.

write_file(Filename, Data)

-spec write_file(file:name_all(), term()) -> ok.

Encode Data to YAML and write it to Filename, overwriting any existing file.

Raises a binary "Filename: Reason" message (see file:format_error/1) if the file can't be written.

Example

1> glazer_yaml:write_file("data.yaml", #{<<"a">> => 1}).
ok

write_file(Filename, Data, Opts)

-spec write_file(file:name_all(), term(), encode_opts()) -> ok.

Encode Data to YAML with encode options (see encode/2) and write it to Filename, overwriting any existing file.