std/data/yaml

=encoding utf8

=head1 NAME

std/data/yaml - YAML encoding and decoding for ZuzuScript.

=head1 SYNOPSIS

  from std/data/yaml import YAML;

  let codec := new YAML( pretty: true, canonical: true );
  let text := codec.encode({ answer: 42, ok: true });
  let data := codec.decode(text);

=head1 IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and
Electron. It is partially supported by zuzu-js in the browser: in-memory
YAML encode/decode coverage passes, but file-backed load/dump coverage is
unsupported because browser filesystem capability is unavailable.

=head1 DESCRIPTION

This module provides a C<YAML> class for turning ZuzuScript values
into YAML text and parsing YAML text back into ZuzuScript values.

=head1 EXPORTS

=head2 Classes

=over

=item C<< YAML({ utf8?: Bool, pretty?: Bool, canonical?: Bool }) >>

Constructs a YAML codec. Returns: C<YAML>.

The constructor accepts named options:

=over

=item * C<utf8> (default true)

Accepted for API compatibility with C<std/data/json> and C<std/data/toml>.

=item * C<pretty> (default false)

Keep the final trailing newline generated by the emitter.

=item * C<canonical> (default false)

Accepted for API compatibility with C<std/data/json> and C<std/data/toml>.

=back

=item C<< codec.encode(value) >>

Parameters: C<value> is any YAML-encodable ZuzuScript value. Returns:
C<String>. Encodes C<value> as YAML text.

=item C<< codec.encode_binarystring(value) >>

Parameters: C<value> is any YAML-encodable ZuzuScript value. Returns:
C<BinaryString>. Encodes C<value> as UTF-8 YAML bytes.

=item C<< codec.decode(String yaml) >>

Parameters: C<yaml> is YAML text. Returns: value. Decodes YAML into the
equivalent ZuzuScript value.

=item C<< codec.decode_binarystring(BinaryString yaml) >>

Parameters: C<yaml> is UTF-8 YAML bytes. Returns: value. Decodes YAML
into the equivalent ZuzuScript value.

=item C<< codec.load(Path path) >>

Parameters: C<path> is a C<std/io> C<Path>. Returns: value. Reads YAML
text from C<path> and decodes it.

=item C<< codec.dump(Path path, value) >>

Parameters: C<path> is a C<std/io> C<Path> and C<value> is any
YAML-encodable value. Returns: C<null>. Encodes C<value> and writes YAML
text to C<path>.

=back

=head1 COPYRIGHT AND LICENCE

B<< std/data/yaml >> is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under
the terms of either the Artistic License 1.0 or the GNU General Public
License version 2.
Module
