Qore YAML Module  0.7
Qore yaml Module

Table of Contents

Introduction

The yaml module provides YAML functionality to Qore, allowing qore programs to read and write information in YAML syntax.

This module is released under a choice of two licenses:

  • LGPL 2.1
  • 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 libyaml.

User modules implementing the following HTTP-based protocols using YAML for data serialization are included:

Also included with the binary yaml module:

Examples

To serialize a simple value or a complex data structure to a YAML string:
%new-style
%strict-args
%require-types
%enable-all-warnings
%requires yaml
string yaml_str = make_yaml(data, YAML::Canonical);
To deserialize a YAML string to a Qore value:
%new-style
%strict-args
%require-types
%enable-all-warnings
auto data = parse_yaml(yaml_str);

Available Functions

Function Description
make_yaml() creates a YAML string from Qore data
parse_yaml() parses a YAML string and returns Qore data
get_yaml_info() returns version information about libyaml

Deprecated Functions

The following camel-case functions were deprecated in yaml 0.5:

Deprecated Function New Function
makeYAML() make_yaml()
parseYAML() parse_yaml()
getYAMLInfo() get_yaml_info()

Qore to YAML Type Mappings

Note that all Qore types except objects can be serialized to YAML, however NULL will be deserialized as NOTHING.

QoreType YAML Tag Qore Example YAML Example Notes
int !!int 300 300 direct serialization
float !!float 3.5 3.5 direct serialization; infinity is serialized as @inf@, "not a number" as @nan@
number !number 3.5 3.5n{128} String serialization in scientific notation (for brevity) with the number appended with an "n"; the number is serialized so that no precision is lost.

Infinity is serialized as @inf@n{128}, "not a number" as @nan@n{128}

The precision is appended to the string in curly brackets (ex: "1.1n{128}" means the number 1.1 with 128 bits of precision)

This tag is a custom tag used only by Qore to serialize Qore arbitrary-precision numeric values with YAML
string !!str "hello" "hello" YAML strings are enclosed in double-quotes, and libyaml will perform escaping as necessary to form a proper YAML string
bool !!bool True true direct serialization to true and false
date (relative) !duration P2M3DT10H14u P2M3DT10H14u Relative date/time values (durations) are serialized with Qore's ISO-8601-based format.

This tag is a custom tag used only by Qore to serialize Qore relative date/time values with YAML
date (absolute) !!timestamp 2010-05-05T15:35:02.100 2010-05-05T15:35:02.1+02:00 Absolute date/time values are serialized with YAML's timestamp format.

Note that qore date/time values without an explicit time zone are assumed to be in the local time zone.

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 !!null NOTHING null direct serialization
NULL !!null or !sqlnull NULL null or !sqlnull without EmitSqlNull, serialization to YAML null, just like NOTHING; will be deserialized as NOTHING, with EmitSqlNull will be deserialized to NULL.
list !!seq (1, 2, "three") [1, 2, "three"] direct serialization
hash !!map ("key" : 1, "other" : 2.0, "data" : "three") {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

Release Notes

yaml Module Version 0.7

  • fixed a bug deserializing implicit string values in some cases (issue 4241)
  • implemented support for serializing connection objects (issue 3696)
  • fixed parsing XML in XML encoded responses (issue 3587)
  • fixed the return types of deserializtion to avoid type stripping (issue 3432)
  • fixed output of excess noise in floating-point values (issue 3375)
  • fixed a bug in the DataStreamClient module where the "response-code" key of the info output hash could be missing in some cases (issue 3237)
  • added optional support for serializing SQL NULL values with EmitSqlNull
  • updated the YamlRpcClient module to support the updated abstract connection API (issue 2628)

yaml Module Version 0.6

  • fixed a bug where strings with invalid encodings were being emitted as-is in exception strings (issue 3394)
  • improved the description for the DESERIALIZATION-ERROR exception for non-deserializable message bodies from HTTP servers with error responses (issue 1033)
  • added the YamlRpcConnection class to the YamlRpcClient module
  • updated the DataStreamClient module for complex types and new internal RestClient API changes (issue 2073)
  • updated the DataStreamUtil module for complex types
  • fixed a bug deserializing single-quoted strings; also serialized "!number" values will always include the tag to avoid potential future ambiguity (issue 2343)
  • improved argument error messages with RPC calls in the YamlRpcHandler module (issue 2573)

yaml Module Version 0.5.1

yaml Module Version 0.5

New Features and Bug Fixes

  • new user modules for DataStream protocol support: YAML-encoded HTTP chunked transfers where each chunk is a unique data entity
  • user modules moved to top-level qore module directory from version-specific module directory since they are valid for multiple versions of qore
  • date/time values (yaml !!timestamp type) are now always returned in the current time zone locale so that time zone rules can be applied to deserialized dates; previously time zone information was always lost which could cause errors when performing date arithmetic on deserialized yaml dates
  • fixed bugs deserializing canonically-encoded YAML strings; arbitrary-precision numeric values were deserialized with their precision values ignored and floating point +/-inf were deserialized as zero
  • deprecated old camel-case names and implemented new function names confirming to the standard naming convention for functions

yaml Module Version 0.4

New Features and Bug Fixes

  • fixed a problem serializing and deserializing 0-length durations; they were serialized as "P" and then deserialized as a string; now they are serialized as "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

yaml Module Version 0.3

New Features and Bug Fixes

  • 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 @nan@, inf as @inf@)

yaml Module Version 0.2

New Features and Bug Fixes

  • 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)
Qore::YAML::parse_yaml
auto parse_yaml(string yaml)
Parses a YAML string and returns the corresponding Qore value or data structure.
Qore::YAML::make_yaml
string make_yaml(auto data, int flags=Qore::YAML::None, softint width=-1, softint indent=2)
Creates a YAML string from Qore data.