Module yamerl_constr

Description
Data Types
Function Index
Function Details

yamerl_constr implements a YAML constructor.

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

Description

yamerl_constr implements a YAML constructor. It uses yamerl_parser as the underlying parser. The parser emits YAML nodes which are assembled as structured YAML documents by the constructor.

It is able to construct YAML documents from in-memory strings (see string/1 and string/2), regular files (see file/1 and file/2) or streams (see new/1, new/2 and next_chunk/3).

YAML documents can be constructed in simple or detailed modes. In simple mode, they are made of simple builting Erlang types. In detailed mode, they are made of records, holding more informations about YAML nodes and their presentation.

The yamerl application must be started to use the constructor.

Example: parse a string in simple mode

  yamerl_constr:string("Hello!").

It returns:

  % List of documents; here, only one.
  [
    % Document root node: a string.
    "Hello!"
  ].

Example: parse a stream in detailed mode

  Stream_St1 = yamerl_constr:new({file, "<stdin>"}, [{detailed_constr, true}]),
  {continue, Stream_St2} = yamerl_constr:next_chunk(Stream_St1, <<"He">>),
  {continue, Stream_St3} = yamerl_constr:next_chunk(Stream_St2, <<"ll">>),
  yamerl_constr:last_chunk(Stream_St3, <<"o!">>).

It returns:

  % List of documents; here, only one.
  [
    % Document #1.
    {yamerl_doc,
      % Document root node: a string.
      {yamerl_str, yamerl_node_str, "tag:yaml.org,2002:str",
        [{line, 1}, {column, 1}], % Node location in the original string.
        "Hello!"                  % String value.
      }
    }
  ].

Data Types

yamerl_constr()

yamerl_constr() = #yamerl_constr{}

Function Index

file/1	Equivalent to `file(Filename, [])`.
file/2	Constructs a YAML document from a regular file.
get_pres_details/1	Returns presentation informations in the stream for the given node.
last_chunk/2	Equivalent to `next_chunk(Constr, Chunk, true)`.
new/1	Equivalent to `new(Source, [])`.
new/2	Creates and returns a new YAML construction state.
next_chunk/2	Equivalent to `next_chunk(Constr, Chunk, false)`.
next_chunk/3	Feeds the constructor with the next chunk from the YAML stream.
node_column/1	Returns the column number in the stream for the given node.
node_line/1	Returns the line number in the stream for the given node.
string/1	Equivalent to `string(String, [])`.
string/2	Constructs a YAML document from an in-memory YAML string.

Function Details

file/1

file(Filename) -> Result | no_return()

Filename = string()
Result = [yamerl_doc()] | [yamerl_simple_doc()] | term()

Equivalent to file(Filename, []).

file/2

file(Filename, Options) -> Result | no_return()

Filename = string()
Options = [yamerl_parser:yamerl_parser_option() | yamerl_constr_option() | proplists:property()]
Result = [yamerl_doc()] | [yamerl_simple_doc()] | term()

Constructs a YAML document from a regular file.

Filename must be a string indicating the filename. The file must contain one or more YAML documents. The file must be encoded using UTF-8, UTF-16 or UTF-32. A leading BOM character is used to determine the encoding and endianness. If no BOM is present, UTF-8 is assumed.

Options is a list of options for the parser and the constructor. See new/2 for valid options.

It returns a list of YAML documents. See next_chunk/3 for more details about the returned documents.

It throws an exception if there is a parsing or construction error.

See string/2 for some examples.

get_pres_details/1

get_pres_details(Token) -> any()

Returns presentation informations in the stream for the given node.

This only makes sense when the detailed construction mode is enabled (ie. {detailed_constr, true} was passed as an option to new/2, file/2 or string/2).

last_chunk/2

last_chunk(Constr, Chunk) -> Result | no_return()

Constr = yamerl_parser:yamerl_parser()
Chunk = unicode_binary()
Result = [yamerl_doc()] | [yamerl_simple_doc()]

Equivalent to next_chunk(Constr, Chunk, true).

new/1

new(Source) -> Constr | no_return()

Source = term()
Constr = yamerl_parser:yamerl_parser()

Equivalent to new(Source, []).

new/2

new(Source, Options) -> Constr | no_return()

Source = term()
Options = [yamerl_constr_option() | yamerl_parser:yamerl_parser_option() | proplists:property()]
Constr = yamerl_parser:yamerl_parser()

Creates and returns a new YAML construction state.

When you want to parse a stream (as opposed to in-memory strings or regular files), this is the first function you call before feeding the constructor with stream "chunks".

Source can be any term describing the stream. string/1 and string/2 sets it to the atom string. file/1 and file/2 sets it to {file, Filename}. The constructor doesn't use that value.

Options is a list of options for the parser and the constructor. Valid options are:

{detailed_constr, boolean()}: Flag to enable/disable the detailed construction mode. In simple construction mode, YAML nodes are returned as Erlang integers, strings, lists, proplists, etc. In other words, only simple builtin types. In detailed construction mode, YAML nodes are returned using records. Those records gives additional informations such as the YAML node type, the location in the stream (line and column number) and so on.
{ignore_unrecognized_tags, boolean()}: Indicate if unrecognized tags should be ignored. When false (the default), a node with an unrecognized tag can't be constructed because yamerl doesn't know how to interpret the node. When this happens an exception is raised. When set to true, the node is constructed as if it was a plain YAML node without any tag.; Default: false.; Default: false
{node_mods, Mods_List}: List of Erlang modules to extend support node types.; Default: [].
{schema, failsafe | json | core | yaml11}: Name of the official schema to use.; Default: core.

The returned state is opaque value. You then pass it to next_chunk/2, next_chunk/3 and last_chunk/2.

If an option is invalid, an exception is thrown.

Example: parse a valid stream

  Stream_St1 = yamerl_constr:new({file, "<stdin>"}),
  {continue, Stream_St2} = yamerl_constr:next_chunk(Stream_St1, <<"He">>),
  {continue, Stream_St3} = yamerl_constr:next_chunk(Stream_St2, <<"ll">>),
  yamerl_constr:last_chunk(Stream_St3, <<"o!">>).

It returns:

  % List of documents; here, only one.
  [
    % Document root node: a string.
    "Hello!"
  ].

Example: parse an invalid stream

  Stream_St1 = yamerl_constr:new({file, "<stdin>"}),
  {continue, Stream_St2} = yamerl_constr:next_chunk(Stream_St1, <<"'He">>),
  {continue, Stream_St3} = yamerl_constr:next_chunk(Stream_St2, <<"ll">>),
  yamerl_constr:last_chunk(Stream_St3, <<"o!">>) % Unfinished single-quoted scalar.

It throws:

  {yamerl_exception,
    % List of warnings and errors; here, one fatal error.
    [
      % Error #1.
      {yamerl_parsing_error, error,
        "Unexpected end-of-stream while parsing flow scalar",          % Human-readable message.
        1, 8,                                                          % Error location.
        unexpected_eos,
        {yamerl_scalar, 1, 1, {yamerl_tag, 1, 1, {non_specific, "!"}}, % Token being parsed.
          flow, single_quoted,
          "Hello!"},
        []
      }
    ]
  }

See also: new/1.

next_chunk/2

next_chunk(Constr, Chunk) -> Ret | no_return()

Constr = yamerl_parser:yamerl_parser()
Chunk = unicode_binary()
Ret = {continue, New_Constr}
New_Constr = yamerl_parser:yamerl_parser()

Equivalent to next_chunk(Constr, Chunk, false).

next_chunk/3

next_chunk(Constr, Chunk, EOS::false) -> Ret | no_return()

Constr = yamerl_parser:yamerl_parser()
Chunk = unicode_binary()
Ret = {continue, New_Constr}
New_Constr = yamerl_parser:yamerl_parser()

Feeds the constructor with the next chunk from the YAML stream.

Constr is the constructor state returned by a previous call to new/1, new/2, next_chunk/2 or next_chunk/3.

Chunk must be an Erlang binary using the UTF-8, UTF-16 or UTF-32 Unicode encoding. A leading BOM character in the first chunk is used to determine the encoding and endianness. If no BOM is present, UTF-8 is assumed.

EOS indicates the constructor if this is the last chunk from the stream.

If this is not the last chunk (EOS = false), it returns {continue, New_Constr} where New_Constr is an updated state which replaces Constr. The new state is to be passed to future calls to next_chunk/2, next_chunk/3 or last_chunk/2.

If this is the last chunk (EOS = true), it returns a list of YAML documents. Documents are made of simple builtin Erlang types if the detailed construction mode is disabled, or records if the detailed construction mode is enabled ({detailed_constr, boolean()} passed as an option; default is false).

It throws an exception if there is a parsing or construction error.

node_column/1

node_column(Node) -> any()

Returns the column number in the stream for the given node.

This only makes sense when the detailed construction mode is enabled (ie. {detailed_constr, true} was passed as an option to new/2, file/2 or string/2).

node_line/1

node_line(Node) -> any()

Returns the line number in the stream for the given node.

This only makes sense when the detailed construction mode is enabled (ie. {detailed_constr, true} was passed as an option to new/2, file/2 or string/2).

string/1

string(String) -> Result | no_return()

String = unicode_data()
Result = [yamerl_doc()] | [yamerl_simple_doc()] | term()

Equivalent to string(String, []).

string/2

string(String, Options) -> Result | no_return()

String = unicode_data()
Options = [yamerl_parser:yamerl_parser_option() | yamerl_constr_option() | proplists:property()]
Result = [yamerl_doc()] | [yamerl_simple_doc()] | term()

Constructs a YAML document from an in-memory YAML string.

String must be an Erlang list or binary containing one or more YAML documents. If it is a binary, it must be encoded using UTF-8, UTF-16 or UTF-32. A leading BOM character is used to determine the encoding and endianness. If no BOM is present, UTF-8 is assumed.

Options is a list of options for the parser and the constructor. See new/2 for valid options.

It returns a list of YAML documents. See next_chunk/3 for more details about the returned documents.

It throws an exception if there is a parsing or construction error.

Example: parse an Erlang list

  yamerl_constr:string("This is a string").

Example: parse an UTF-8-encoded Erlang binary

  yamerl_constr:string(<<50,32,226,130,172>>). % The string "2 €" encoded in UTF-8.

Example: parse a string in simple mode

  yamerl_constr:string("Hello!").

It returns:

  % List of documents; here, only one.
  [
    % Document root node: a string.
    "Hello!"
  ].

Example: parse a string in detailed mode

  yamerl_constr:string("Hello!", [{detailed_constr, true}]).

It returns:

  % List of documents; here, only one.
  [
    % Document #1.
    {yamerl_doc,
      % Document root node: a string.
      {yamerl_str, yamerl_node_str, "tag:yaml.org,2002:str",
        [{line, 1}, {column, 1}], % Node location in the original string.
        "Hello!"                  % String value.
      }
    }
  ].

Example: parse an invalid document

  yamerl_constr:string(<<"'Oh-oh...">>). % Unfinished single-quoted scalar.

It throws:

  {yamerl_exception,
    % List of warnings and errors; here, one fatal error.
    [
      % Error #1.
      {yamerl_parsing_error, error,
        "Unexpected end-of-stream while parsing flow scalar",          % Human-readable message.
        1, 10,                                                         % Error location.
        unexpected_eos,
        {yamerl_scalar, 1, 1, {yamerl_tag, 1, 1, {non_specific, "!"}}, % Token being parsed.
          flow, single_quoted,
          "Oh-oh..."},
        []
      }
    ]
  }.

Generated by EDoc