YAML

A YAML parser that converts YAML to JSON. More...

Classes
class	sourcemeta::core::YAMLError
class	sourcemeta::core::YAMLParseError
class	sourcemeta::core::YAMLFileParseError
class	sourcemeta::core::YAMLUnknownAnchorError
class	sourcemeta::core::YAMLDuplicateKeyError
class	sourcemeta::core::YAMLRoundTrip

Functions
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::parse_yaml (std::basic_istream< JSON::Char, JSON::CharTraits > &stream) -> JSON
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::parse_yaml (const JSON::String &input) -> JSON
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::read_yaml (const std::filesystem::path &path) -> JSON
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::parse_yaml (std::basic_istream< JSON::Char, JSON::CharTraits > &stream, JSON &output, const JSON::ParseCallback &callback) -> void
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::parse_yaml (const JSON::String &input, JSON &output, const JSON::ParseCallback &callback) -> void
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::read_yaml (const std::filesystem::path &path, JSON &output, const JSON::ParseCallback &callback) -> void
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::read_yaml_or_json (const std::filesystem::path &path) -> JSON
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::read_yaml_or_json (const std::filesystem::path &path, JSON &output, const JSON::ParseCallback &callback) -> void
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::parse_yaml (const JSON::String &input, YAMLRoundTrip &roundtrip) -> JSON
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::parse_yaml (const JSON::String &input, YAMLRoundTrip &roundtrip, JSON &output, const JSON::ParseCallback &callback) -> void
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::stringify_yaml (const JSON &document, std::basic_ostream< JSON::Char, JSON::CharTraits > &stream, const YAMLRoundTrip &roundtrip) -> void
SOURCEMETA_CORE_YAML_EXPORT auto	sourcemeta::core::stringify_yaml (const JSON &document, std::basic_ostream< JSON::Char, JSON::CharTraits > &stream) -> void

Detailed Description

A YAML parser that converts YAML to JSON.

This functionality is included as follows:

#include <sourcemeta/core/yaml.h>

---

Class Documentation

sourcemeta::core::YAMLError

class sourcemeta::core::YAMLError

An error that represents a general YAML error event

Inheritance diagram for sourcemeta::core::YAMLError:

Public Member Functions
	YAMLError (const char *message)
	Create a general error.
	YAMLError (std::string message)=delete
	YAMLError (std::string &&message)=delete
	YAMLError (std::string_view message)=delete

sourcemeta::core::YAMLParseError

class sourcemeta::core::YAMLParseError

An error that represents a YAML parse error event

Inheritance diagram for sourcemeta::core::YAMLParseError:

Public Member Functions
	YAMLParseError (const std::uint64_t line, const std::uint64_t column)
	Create a parsing error.
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, const char *message)
	Create a parsing error with a custom error.
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string message)=delete
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string &&message)=delete
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string_view message)=delete
auto	line () const noexcept -> std::uint64_t
	Get the line number of the error.
auto	column () const noexcept -> std::uint64_t
	Get the column number of the error.

sourcemeta::core::YAMLFileParseError

class sourcemeta::core::YAMLFileParseError

An error that represents a YAML parse error occurring from parsing a file

Inheritance diagram for sourcemeta::core::YAMLFileParseError:

Public Member Functions
	YAMLFileParseError (std::filesystem::path path, const std::uint64_t line, const std::uint64_t column, const char *message)
	Create a file parsing error.
	YAMLFileParseError (std::filesystem::path path, const std::uint64_t line, const std::uint64_t column, std::string message)=delete
	YAMLFileParseError (std::filesystem::path path, const std::uint64_t line, const std::uint64_t column, std::string &&message)=delete
	YAMLFileParseError (std::filesystem::path path, const std::uint64_t line, const std::uint64_t column, std::string_view message)=delete
	YAMLFileParseError (std::filesystem::path path, const YAMLParseError &parent)
	Create a file parsing error from a parse error.
auto	path () const noexcept -> const std::filesystem::path &
	Get the file path of the error.
Public Member Functions inherited from sourcemeta::core::YAMLParseError
	YAMLParseError (const std::uint64_t line, const std::uint64_t column)
	Create a parsing error.
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, const char *message)
	Create a parsing error with a custom error.
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string message)=delete
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string &&message)=delete
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string_view message)=delete
auto	line () const noexcept -> std::uint64_t
	Get the line number of the error.
auto	column () const noexcept -> std::uint64_t
	Get the column number of the error.

sourcemeta::core::YAMLUnknownAnchorError

class sourcemeta::core::YAMLUnknownAnchorError

An error that represents an unknown anchor reference in YAML

Inheritance diagram for sourcemeta::core::YAMLUnknownAnchorError:

Public Member Functions
	YAMLUnknownAnchorError (const std::string_view anchor_name, const std::uint64_t line, const std::uint64_t column)
	Create an unknown anchor error.
auto	anchor () const noexcept -> std::string_view
	Get the anchor name of the error.
Public Member Functions inherited from sourcemeta::core::YAMLParseError
	YAMLParseError (const std::uint64_t line, const std::uint64_t column)
	Create a parsing error.
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, const char *message)
	Create a parsing error with a custom error.
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string message)=delete
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string &&message)=delete
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string_view message)=delete
auto	line () const noexcept -> std::uint64_t
	Get the line number of the error.
auto	column () const noexcept -> std::uint64_t
	Get the column number of the error.

sourcemeta::core::YAMLDuplicateKeyError

class sourcemeta::core::YAMLDuplicateKeyError

An error that represents a duplicate key in a YAML mapping YAML 1.2.2 requires unique keys in mappings, unlike JSON where duplicate keys are undefined behavior. See https://yaml.org/spec/1.2.2/#mapping

Inheritance diagram for sourcemeta::core::YAMLDuplicateKeyError:

Public Member Functions
	YAMLDuplicateKeyError (const std::string_view key_name, const std::uint64_t line, const std::uint64_t column)
	Create a duplicate key error.
auto	key () const noexcept -> std::string_view
	Get the key name of the error.
Public Member Functions inherited from sourcemeta::core::YAMLParseError
	YAMLParseError (const std::uint64_t line, const std::uint64_t column)
	Create a parsing error.
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, const char *message)
	Create a parsing error with a custom error.
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string message)=delete
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string &&message)=delete
	YAMLParseError (const std::uint64_t line, const std::uint64_t column, std::string_view message)=delete
auto	line () const noexcept -> std::uint64_t
	Get the line number of the error.
auto	column () const noexcept -> std::uint64_t
	Get the column number of the error.

sourcemeta::core::YAMLRoundTrip

class sourcemeta::core::YAMLRoundTrip

Holds per-node metadata collected during YAML parsing to reproduce the original formatting

Public Types
enum class	ScalarStyle : std::uint8_t {   Plain , SingleQuoted , DoubleQuoted , Literal ,   Folded }
	The presentation style of a scalar value. More...
enum class	CollectionStyle : std::uint8_t { Block , Flow }
	The presentation style of a collection. More...
enum class	Chomping : std::uint8_t { Clip , Strip , Keep }
	The chomping behavior applied to a block scalar. More...
Public Attributes
std::unordered_map< Pointer, NodeStyle, Pointer::Hasher >	styles
	The recorded formatting for each node by pointer.
std::unordered_map< Pointer, std::string, Pointer::Hasher >	aliases
	The alias name for each node referencing an anchor.
std::unordered_map< Pointer, ScalarStyle, Pointer::Hasher >	key_styles
	The scalar style for each mapping key by pointer.
std::unordered_map< Pointer, std::string, Pointer::Hasher >	key_quoted_contents
	The original quoted content for each mapping key.
bool	explicit_document_start {false}
	Whether the document begins with an explicit start marker.
bool	explicit_document_end {false}
	Whether the document ends with an explicit end marker.
std::optional< std::string >	document_start_comment
	The comment on the document start marker.
std::optional< std::string >	document_end_comment
	The comment on the document end marker.
std::vector< std::string >	leading_comments
	The comments preceding the document.
std::vector< std::string >	post_start_comments
	The comments following the document start marker.
std::vector< std::string >	pre_end_comments
	The comments preceding the document end marker.
std::vector< std::string >	trailing_comments
	The comments following the document.
std::size_t	indent_width {2}
	The indentation width used when emitting the document.

Member Enumeration Documentation

Chomping

enum class sourcemeta::core::YAMLRoundTrip::Chomping : std::uint8_t

strong

The chomping behavior applied to a block scalar.

Enumerator
Clip	Keep a single trailing line break and drop the rest.
Strip	Remove all trailing line breaks.
Keep	Preserve every trailing line break.

CollectionStyle

enum class sourcemeta::core::YAMLRoundTrip::CollectionStyle : std::uint8_t

strong

The presentation style of a collection.

Enumerator
Block	The indentation-based block collection style.
Flow	The inline flow collection style delimited by brackets or braces.

ScalarStyle

enum class sourcemeta::core::YAMLRoundTrip::ScalarStyle : std::uint8_t

strong

The presentation style of a scalar value.

Enumerator
Plain	The unquoted scalar style.
SingleQuoted	The single-quoted scalar style.
DoubleQuoted	The double-quoted scalar style.
Literal	The literal block scalar style that preserves line breaks.
Folded	The folded block scalar style that joins lines with spaces.

Function Documentation

parse_yaml() [1/6]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::parse_yaml

(

const JSON::String &

input

)

-> JSON

Create a JSON document from a C++ standard input stream that represents a YAML document. The input must be UTF-8, optionally preceded by a UTF-8 byte order mark, as UTF-16 and UTF-32 input are not supported. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/yaml.h>
 
#include <iostream>
 
const std::string input{"hello: world"};
const sourcemeta::core::JSON document =
  sourcemeta::core::parse_yaml(input);
sourcemeta::core::prettify(document, std::cerr);
std::cerr << "\n";

parse_yaml() [2/6]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::parse_yaml	(	const JSON::String &	input,
		JSON &	output,
		const JSON::ParseCallback &	callback ) -> void

Parse a YAML string into an existing JSON value, invoking the given callback during parsing. The result is constructed directly into the given reference rather than returned by value to ensure that references passed through the parse callback remain valid after parsing completes.

parse_yaml() [3/6]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::parse_yaml	(	const JSON::String &	input,
		YAMLRoundTrip &	roundtrip ) -> JSON

Create a JSON document from a YAML string, collecting round-trip metadata to reproduce the original formatting. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/yaml.h>
 
sourcemeta::core::YAMLRoundTrip roundtrip;
const std::string input{"hello: world"};
const sourcemeta::core::JSON document =
  sourcemeta::core::parse_yaml(input, roundtrip);

parse_yaml() [4/6]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::parse_yaml	(	const JSON::String &	input,
		YAMLRoundTrip &	roundtrip,
		JSON &	output,
		const JSON::ParseCallback &	callback ) -> void

Parse a YAML string with round-trip metadata into an existing JSON value, invoking the given callback during parsing. The result is constructed directly into the given reference rather than returned by value to ensure that references passed through the parse callback remain valid after parsing completes.

parse_yaml() [5/6]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::parse_yaml

(

std::basic_istream< JSON::Char, JSON::CharTraits > &

stream

)

-> JSON

Create a JSON document from a C++ standard input stream that represents a YAML document. The input must be UTF-8, optionally preceded by a UTF-8 byte order mark, as UTF-16 and UTF-32 input are not supported. For example:

#include <sourcemeta/core/json.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"foo: bar"};
const sourcemeta::core::JSON document =
  sourcemeta::core::parse_yaml(stream);
assert(document.is_object());

parse_yaml() [6/6]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::parse_yaml	(	std::basic_istream< JSON::Char, JSON::CharTraits > &	stream,
		JSON &	output,
		const JSON::ParseCallback &	callback ) -> void

Parse a YAML document from a C++ standard input stream into an existing JSON value, invoking the given callback during parsing. The result is constructed directly into the given reference rather than returned by value to ensure that references passed through the parse callback remain valid after parsing completes.

read_yaml() [1/2]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::read_yaml

(

const std::filesystem::path &

path

)

-> JSON

Read a JSON document from a file location that represents a YAML file. The file must be UTF-8, optionally preceded by a UTF-8 byte order mark, as UTF-16 and UTF-32 input are not supported. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/yaml.h>
 
#include <iostream>
#include <filesystem>
 
const std::filesystem::path path{"test.yaml"};
const sourcemeta::core::JSON document =
  sourcemeta::core::read_yaml(path);
sourcemeta::core::prettify(document, std::cerr);
std::cerr << "\n";

read_yaml() [2/2]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::read_yaml	(	const std::filesystem::path &	path,
		JSON &	output,
		const JSON::ParseCallback &	callback ) -> void

Read a YAML file into an existing JSON value, invoking the given callback during parsing. The result is constructed directly into the given reference rather than returned by value to ensure that references passed through the parse callback remain valid after parsing completes.

read_yaml_or_json() [1/2]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::read_yaml_or_json

(

const std::filesystem::path &

path

)

-> JSON

Read a JSON document from a file location that represents a YAML file or a JSON file. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/yaml.h>
 
#include <iostream>
#include <filesystem>
 
const std::filesystem::path path{"test.yaml"};
const sourcemeta::core::JSON document =
  sourcemeta::core::read_yaml_or_json(path);
sourcemeta::core::prettify(document, std::cerr);
std::cerr << "\n";

read_yaml_or_json() [2/2]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::read_yaml_or_json	(	const std::filesystem::path &	path,
		JSON &	output,
		const JSON::ParseCallback &	callback ) -> void

Read a JSON document from a file that represents YAML or JSON, constructing into the given reference and invoking the callback during parsing. The result is constructed directly into the given reference rather than returned by value to ensure that references passed through the parse callback (such as object property names) remain valid after parsing completes.

stringify_yaml() [1/2]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::stringify_yaml	(	const JSON &	document,
		std::basic_ostream< JSON::Char, JSON::CharTraits > &	stream ) -> void

Stringify a JSON document as YAML. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/yaml.h>
 
#include <iostream>
 
const sourcemeta::core::JSON document =
  sourcemeta::core::parse_json(R"JSON({ "foo": "bar" })JSON");
sourcemeta::core::stringify_yaml(document, std::cout);

stringify_yaml() [2/2]

SOURCEMETA_CORE_YAML_EXPORT auto sourcemeta::core::stringify_yaml	(	const JSON &	document,
		std::basic_ostream< JSON::Char, JSON::CharTraits > &	stream,
		const YAMLRoundTrip &	roundtrip ) -> void

Stringify a JSON document as YAML, using round-trip metadata collected during parsing to preserve the original formatting. The document may be modified in between, in which case the nodes that changed are written from the document, keeping their original presentation style where that style can still express them. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/yaml.h>
 
#include <iostream>
 
sourcemeta::core::YAMLRoundTrip roundtrip;
const std::string input{"hello: world"};
const sourcemeta::core::JSON document =
  sourcemeta::core::parse_yaml(input, roundtrip);
sourcemeta::core::stringify_yaml(document, std::cout, roundtrip);