oracular (3) Data::Pond.3pm.gz
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.