@author Jean-Sébastien Pédron @copyright 2012-2014 Yakaz, 2016-2017 Jean-Sébastien Pédron @doc == 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 === === Caveats === == Features == == 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 {@link yamerl_constr} module to parse and construct a list of documents from: Because a YAML input stream may contain multiple documents, {@link yamerl_constr} always returns a list of documents, even if the input stream only contains one. == Examples == === Basic parsing ===
  1. Start the yamerl application. This is a mandatory step. ``` application:start(yamerl). '''
  2. 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, ""}), % 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 {@link yamerl_constr} for more informations. === Error handling === yamerl throws an exception when an error occurs.
  1. Start the yamerl application. This is a mandatory step. ``` application:start(yamerl). '''
  2. 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:
  1. `type', either `error' or `warning';
  2. `text', a human-readable error message.
Following members depend on the error record. Two records are currently defined: See {@link yamerl_constr} for more informations. == Alternatives to yamerl == === YAML parsers === === JSON parsers === There are too many to choose from now to list them here. Use your preferred search engine :-)