/** @mainpage Qore yaml Module

    @tableofcontents

    Contents of this documentation:
    - @ref yamlintro
    - @ref functions
    - @ref qore_to_yaml_type_mappings
    - @ref yaml_emitter_option_constants
    - @ref yamlreleasenotes

    @section yamlintro Introduction

    The yaml module provides <a href="http://www.yaml.org">YAML</a> functionality to Qore, allowing qore programs to read and write information in %YAML syntax.

This module is released under a choice of two licenses:
    - <a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">LGPL 2.1</a>
    - MIT (see COPYING.MIT in the source distribution for more information)
    .
    The module is tagged as such in the module's header (meaning it can be loaded unconditionally regardless of how the %Qore library was initialized).

    Like all Qore components, the yaml module is thread-safe.

    The underlying %YAML functionality is provided by <a href="http://pyyaml.org/wiki/LibYAML">libyaml</a>.

    User modules implementing the following HTTP-based protocols using YAML for data serialization are included:
    - YAML-RPC: similar to JSON-RPC but using YAML-serialized data (<a href="../../YamlRpcClient/html/index.html">YamlRpcClient</a>, <a href="../../YamlRpcHandler/html/index.html">YamlRpcHandler</a>)
    - DataStream: allows for data streaming with HTTP 1.1 chunked data transfers where each chunk is a unique data entity (<a href="../../DataStreamUtil/html/index.html">DataStreamUtil</a>, <a href="../../DataStreamClient/html/index.html">DataStreamClient</a>, <a href="../../DataStreamRequestHandler/html/index.html">DataStreamRequestHandler</a>)

    Also included with the binary yaml module:
    - <a href="../../DataStreamUtil/html/index.html">DataStreamUtil user module</a>
    - <a href="../../DataStreamClient/html/index.html">DataStreamClient user module</a>
    - <a href="../../DataStreamRequestHandler/html/index.html">DataStreamRequestHandler user module</a>
    - <a href="../../YamlRpcClient/html/index.html">YamlRpcClient user module</a>
    - <a href="../../YamlRpcHandler/html/index.html">YamlRpcHandler user module</a>

    @section Examples
    
    @par To serialize a simple value or a complex data structure to a YAML string:
    @code
%requires yaml
my string $yaml_str = makeYAML($data, YAML::Canonical);
    @endcode

    @par To deserialize a YAML string to a Qore value:
    @code
%requires yaml
my any $data = parseYAML($yaml_str);
    @endcode

    @section functions Available Functions
    
    @htmlonly <style><!-- td.qore { background-color: #5b9409; color: white; } --></style> @endhtmlonly
    <table>
      <tr>
        <td class="qore"><b>Function</b></td>
        <td class="qore"><b>Description</b></td>
      </tr>
      <tr>
        <td>@ref makeYAML()</td>
        <td>creates a %YAML string from Qore data</td>
      </tr>
      <tr>
        <td>@ref parseYAML()</td>
        <td>parses a %YAML string and returns Qore data</td>
      </tr>
      <tr>
        <td>@ref getYAMLInfo()</td>
        <td>returns version information about <a href="http://pyyaml.org/wiki/LibYAML">libyaml</a></td>
      </tr>
    </table>

    @section qore_to_yaml_type_mappings Qore to YAML Type Mappings
    
    Note that all Qore types except objects can be serialized to YAML,
    however \c NULL will be deserialized as \c NOTHING.

    <table>
      <tr>
        <td class="qore"><b>QoreType</b></td>
        <td class="qore"><b>YAML Tag</b></td>
        <td class="qore"><b>Qore Example</b></td>
        <td class="qore"><b>YAML Example</b></td>
        <td class="qore"><b>Notes</b></td>
      </tr>
      <tr>
        <td>int</td>
        <td>\c !!int</td>
        <td>\c 300</td>
        <td>\c 300</td>
        <td>direct serialization</td>
      </tr>
      <tr>
        <td>float</td>
        <td>\c !!float</td>
        <td>\c 3.5</td>
        <td>\c 3.5</td>
        <td>direct serialization; infinity is serialized as <tt>\@inf\@</tt>, "not a number" as <tt>\@nan\@</tt></td>
      </tr>
      <tr>
        <td>number</td>
        <td>\c !number</td>
        <td>\c 3.5</td>
        <td><tt>3.5n{128}</tt></td>
        <td>String serialization in scientific notation (for brevity) with the number appended with an \c "n"; the number is serialized so that no precision is lost.<br><br>Infinity is serialized as <tt>\@inf\@n{128}</tt>, "not a number" as <tt>\@nan\@n{128}</tt><br><br>The precision is appended to the string in curly brackets (ex: \"1.1n{128}" means the number <tt>1.1</tt> with 128 bits of precision)<br><br>This tag is a custom tag used only by Qore to serialize Qore arbitrary-precision numeric values with YAML</td>
      </tr>
      <tr>
        <td>string</td>
        <td>\c !!str</td>
        <td>\c "hello"</td>
        <td>\c "hello"</td>
        <td>YAML strings are enclosed in double-quotes, and libyaml will perform escaping as necessary to form a proper YAML string</td>
      </tr>
      <tr>
        <td>bool</td>
        <td>\c !!bool</td>
        <td>\c True</td>
        <td>\c true</td>
        <td>direct serialization to \c true and \c false</td>
      </tr>
      <tr>
        <td>date (relative)</td>
        <td>\c !duration</td>
        <td>\c P2M3DT10H14u</td>
        <td>\c P2M3DT10H14u</td>
        <td>Relative date/time values (durations) are serialized with Qore's <a href="http://en.wikipedia.org/wiki/ISO_8601#Durations">ISO-8601</a>-based format.<br><br>This tag is a custom tag used only by Qore to serialize Qore relative date/time values with YAML</td>
      </tr>
      <tr>
        <td>date (absolute)</td>
        <td>\c !!timestamp</td>
        <td>\c 2010-05-05T15:35:02.100</td>
        <td>\c 2010-05-05T15:35:02.1+02:00</td>
        <td>Absolute date/time values are serialized with YAML's <a href="http://yaml.org/type/timestamp.html">timestamp</a> format.<br><br>Note that qore date/time values without an explicit time zone are assumed to be in the local time zone.<br><br>When converting a YAML timestamp to a Qore date, because Qore supports only up to microsecond resolution in date/time values, any digits after microseconds are lost.</td>
      </tr>
      <tr>
        <td>NOTHING</td>
        <td>\c !!null</td>
        <td>\c NOTHING</td>
        <td>\c null</td>
        <td>direct serialization</td>
      </tr>
      <tr>
        <td>NULL</td>
        <td>\c !!null</td>
        <td>\c NULL</td>
        <td>\c null</td>
        <td>serialization to YAML null, just like \c NOTHING; will be deserialized as \c NOTHING.</td>
      </tr>
      <tr>
        <td>list</td>
        <td>\c !!seq</td>
        <td>\c (1, 2, "three")</td>
        <td>\c [1, 2, "three"]</td>
        <td>direct serialization</td>
      </tr>
      <tr>
        <td>hash</td>
        <td>\c !!map</td>
        <td>\c ("key" : 1, "other" : 2.0, "data" : "three")</td>
        <td>\c {key: 1, other: 2.0, data: "three"}</td>
        <td>direct serialization, although qore will maintain key order as well even though this property is only defined for an ordered map</td>
      </tr>
    </table>

    @section yamlreleasenotes Release Notes

    @subsection yaml05 yaml Module Version 0.5

    <b>New Features and Bug Fixes</b>
    - new user modules for DataStream protocol support: YAML-encoded HTTP chunked transfers where each chunk is a unique data entity
      - <a href="../../DataStreamClient/html/index.html">DataStreamClient user module</a>
      - <a href="../../DataStreamRequestHandler/html/index.html">DataStreamRequestHandler user module</a>
      - <a href="../../DataStreamUtil/html/index.html">DataStreamUtil user module</a>
    - user modules moved to top-level qore module directory from version-specific module directory since they are valid for multiple versions of qore

    @subsection yaml04 yaml Module Version 0.4

    <b>New Features and Bug Fixes</b>
    - fixed a problem serializing and deserializing 0-length durations; they were serialized as \c "P" and then deserialized as a string; now they are serialized as \c "P0D" and deserialized correctly as a zero-length duration
    - enhanced the YamlRpcHandler module for more flexible logging
    - added the MIT license as a source license option

    @subsection yaml03 yaml Module Version 0.3

    <b>New Features and Bug Fixes</b>
    - fixed a problem where an exception was not raised with invalid YAML input when parsing, instead NOTHING was returned
    - fixed a problem deserializing integers; the number was converted to a C++ double (floating-point type) first, causing precision to be lost with large numbers
    - added support for Qore's new number type when compiled with Qore 0.8.6+
    - added support for serializing special floating point numbers (nan as <tt>\@nan\@</tt>, inf as <tt>\@inf\@</tt>)

    @subsection yaml02 yaml Module Version 0.2

    <b>New Features and Bug Fixes</b>
    - fixed a problem with deserializing untagged and not double quoted integer and floating-point 0 and 0.0; they were incorrectly deserialized as strings
    - added additional information to the exception when a scalar value cannot be serialized (normally this happens when a string has an encoding error)
*/