/** @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
    
    |!Function|!Description|
    |@ref makeYAML()|creates a %YAML string from Qore data|
    |@ref parseYAML()|parses a %YAML string and returns Qore data|
    |@ref getYAMLInfo()|returns version information about <a href="http://pyyaml.org/wiki/LibYAML">libyaml</a>|

    @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.

    |!QoreType|!YAML Tag|!Qore Example|!YAML Example|!Notes
    |int|\c !!int|\c 300|\c 300|direct serialization
    |float|\c !!float|\c 3.5|\c 3.5|direct serialization; infinity is serialized as <tt>\@inf\@</tt>, "not a number" as <tt>\@nan\@</tt>
    |number|\c !number|\c 3.5|<tt>3.5n{128}</tt>|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
    |string|\c !!str|\c "hello"|\c "hello"|YAML strings are enclosed in double-quotes, and libyaml will perform escaping as necessary to form a proper YAML string
    |bool|\c !!bool|\c True|\c true|direct serialization to \c true and \c false
    |date (relative)|\c !duration|\c P2M3DT10H14u|\c P2M3DT10H14u|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
    |date (absolute)|\c !!timestamp|\c 2010-05-05T15:35:02.100|\c 2010-05-05T15:35:02.1+02:00|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.
    |NOTHING|\c !!null|\c NOTHING|\c null|direct serialization
    |NULL|\c !!null|\c NULL|\c null|serialization to YAML null, just like \c NOTHING; will be deserialized as \c NOTHING.
    |list|\c !!seq|\c (1, 2, "three")|\c [1, 2, "three"]|direct serialization
    |hash|\c !!map|\c ("key" : 1, "other" : 2.0, "data" : "three")|\c {key: 1, other: 2.0, data: "three"}|direct serialization, although qore will maintain key order as well even though this property is only defined for an ordered map

    @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)
*/