Qore YAML Module  0.4
 All Namespaces Functions Variables Groups
Qore yaml Module

Table of Contents

Contents of this documentation:

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.

Also included with the binary yaml module:

Examples

To serialize a simple value or a complex data structure to a YAML string:
%requires yaml
my string $yaml_str = makeYAML($data, YAML::Canonical);
To deserialize a YAML string to a Qore value:
%requires yaml
my any $data = parseYAML($yaml_str);

Available Functions

Function Description
makeYAML() creates a YAML string from Qore data
parseYAML() parses a YAML string and returns Qore data
getYAMLInfo() returns version information about libyaml

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 store Qore relative date/time values in 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 store Qore relative date/time values in 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.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)