Qore YAML Module  0.6
 All Namespaces Functions Variables Groups Pages
Qore yaml Module

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:
1 %new-style
2 %strict-args
3 %require-types
4 %enable-all-warnings
5 
6 %requires yaml
7 string yaml_str = make_yaml(data, YAML::Canonical);
To deserialize a YAML string to a Qore value:
1 %new-style
2 %strict-args
3 %require-types
4 %enable-all-warnings
5 
6 any 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 NULL null serialization to YAML null, just like NOTHING; will be deserialized as NOTHING.
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.6

  • 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)