NAME

       Data::Pond - Perl-based open notation for data

SYNOPSIS

               use Data::Pond qw($pond_datum_rx);

               if($expr =~ /\A$pond_datum_rx\z/o) { ...
               # and other regular expressions

               use Data::Pond qw(pond_read_datum pond_write_datum);

               $datum = pond_read_datum($text);
               $text = pond_write_datum($datum);
               $text = pond_write_datum($datum, { indent => 0 });

DESCRIPTION

       This module is concerned with representing data structures in a textual notation known as
       "Pond" (Perl-based open notation for data).  The notation is a strict subset of Perl
       expression syntax, but is intended to have language-independent use.  It is similar in
       spirit to JSON, which is based on JavaScript, but Pond represents fewer data types
       directly.

       The data that can be represented in Pond consist of strings (of characters), arrays, and
       string-keyed hashes.  Arrays and hashes can recursively (but not cyclically) contain any
       of these kinds of data.  This does not cover the full range of data types that Perl or
       other languages can handle, but is intended to be a limited, fixed repertoire of data
       types that many languages can readily process.  It is intended that more complex data can
       be represented using these basic types.  The arrays and hashes provide structuring
       facilities (ordered and unordered collections, respectively), and strings are a convenient
       way to represent atomic data.

       The Pond syntax is a subset of Perl expression syntax, consisting of string literals and
       constructors for arrays and hashes.  Strings may be single-quoted or double-quoted, or may
       be decimal integer literals.  Double-quoted strings are restricted in which backslash
       sequences they can use: the permitted ones are the single-character ones (such as "\n"),
       "\x" sequences (such as "\xe3" and "\x{e3}"), and octal digit sequences (such as "\010").
       Non-ASCII characters are acceptable in quoted strings.  Strings may also appear as pure-
       ASCII barewords, when they directly precede "=>" in an array or hash constructor.  Array
       ("[]") and hash ("{}") constructors must contain data items separated by "," and "=>"
       commas, and can have a trailing comma but not adjacent commas.  Whitespace is permitted
       where Perl allows it.  Control characters are not permitted, except for whitespace outside
       strings.

       A Pond expression can be "eval"ed by Perl to yield the data item that it represents, but
       this is not the recommended way to do it.  Any use of "eval" on data opens up security
       issues.  Instead use the "pond_read_datum" function of this module, which does not use
       Perl's parser but directly parses the restricted Pond syntax.

       This module is implemented in XS, with a pure Perl backup version for systems that can't
       handle XS.

REGULAR EXPRESSIONS

       Each of these regular expressions corresponds precisely to part of Pond syntax.  The
       regular expressions do not include any anchors, so to check whether an entire string
       matches a production you must supply the anchors yourself.

       The regular expressions with "_ascii_" in the name match the subset of the grammar that
       uses only ASCII characters.  All Pond data can be expressed using only ASCII characters.

       $pond_string_rx
       $pond_ascii_string_rx
           A string literal.  This may be a double-quoted string, a single-quoted string, or a
           decimal integer literal.  It does not accept barewords.

       $pond_array_rx
       $pond_ascii_array_rx
           An array "[]" constructor.

       $pond_hash_rx
       $pond_ascii_hash_rx
           A hash "{}" constructor.

       $pond_datum_rx
       $pond_ascii_datum_rx
           Any permitted expression.  This may be a string literal, array constructor, or hash
           constructor.

FUNCTIONS

       pond_read_datum(TEXT)
           TEXT is a character string.  This function parses it as a Pond-encoded datum, with
           optional surrounding whitespace, returning the represented item as a Perl native
           datum.  "die"s if a malformed item is encountered.

       pond_write_datum(DATUM[, OPTIONS])
           DATUM is a Perl native datum.  This function serialises it as a character string using
           Pond encoding.  The data to be serialised can recursively contain Perl strings,
           arrays, and hashes.  Numbers are implicitly stringified, and "undef" is treated as the
           empty string.  "die"s if an unserialisable datum is encountered.

           OPTIONS, if present, must be a reference to a hash, containing options that control
           the serialisation process.  The recognised options are:

           indent
               If "undef" (which is the default), no optional whitespace will be added.
               Otherwise it must be a non-negative integer, and the datum will be laid out with
               whitespace (where it is optional) to illustrate the structure by indentation.  The
               number given must be the number of leading spaces on the line on which the
               resulting element will be placed.  If whitespace is added, the element will be
               arranged to end on a line of the same indentation, and all intermediate lines will
               have greater indentation.

           undef_is_empty
               If false (the default), "undef" will be treated as invalid data.  If true, "undef"
               will be serialised as an empty string.

           unicode
               If false (the default), the datum will be expressed using only ASCII characters.
               If true, non-ASCII characters may be used in string literals.

SEE ALSO

       Data::Dumper, JSON::XS, "eval" in perlfunc

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

       Copyright (C) 2009 PhotoBox Ltd

       Copyright (C) 2010, 2012, 2017 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.