1Data::Pond(3pm)       User Contributed Perl Documentation      Data::Pond(3pm)
2
3
4

NAME

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

SYNOPSIS

9               use Data::Pond qw($pond_datum_rx);
10
11               if($expr =~ /\A$pond_datum_rx\z/o) { ...
12               # and other regular expressions
13
14               use Data::Pond qw(pond_read_datum pond_write_datum);
15
16               $datum = pond_read_datum($text);
17               $text = pond_write_datum($datum);
18               $text = pond_write_datum($datum, { indent => 0 });
19

DESCRIPTION

21       This module is concerned with representing data structures in a textual
22       notation known as "Pond" (Perl-based open notation for data).  The
23       notation is a strict subset of Perl expression syntax, but is intended
24       to have language-independent use.  It is similar in spirit to JSON,
25       which is based on JavaScript, but Pond represents fewer data types
26       directly.
27
28       The data that can be represented in Pond consist of strings (of
29       characters), arrays, and string-keyed hashes.  Arrays and hashes can
30       recursively (but not cyclically) contain any of these kinds of data.
31       This does not cover the full range of data types that Perl or other
32       languages can handle, but is intended to be a limited, fixed repertoire
33       of data types that many languages can readily process.  It is intended
34       that more complex data can be represented using these basic types.  The
35       arrays and hashes provide structuring facilities (ordered and unordered
36       collections, respectively), and strings are a convenient way to
37       represent atomic data.
38
39       The Pond syntax is a subset of Perl expression syntax, consisting of
40       string literals and constructors for arrays and hashes.  Strings may be
41       single-quoted or double-quoted, or may be decimal integer literals.
42       Double-quoted strings are restricted in which backslash sequences they
43       can use: the permitted ones are the single-character ones (such as
44       "\n"), "\x" sequences (such as "\xe3" and "\x{e3}"), and octal digit
45       sequences (such as "\010").  Non-ASCII characters are acceptable in
46       quoted strings.  Strings may also appear as pure-ASCII barewords, when
47       they directly precede "=>" in an array or hash constructor.  Array
48       ("[]") and hash ("{}") constructors must contain data items separated
49       by "," and "=>" commas, and can have a trailing comma but not adjacent
50       commas.  Whitespace is permitted where Perl allows it.  Control
51       characters are not permitted, except for whitespace outside strings.
52
53       A Pond expression can be "eval"ed by Perl to yield the data item that
54       it represents, but this is not the recommended way to do it.  Any use
55       of "eval" on data opens up security issues.  Instead use the
56       "pond_read_datum" function of this module, which does not use Perl's
57       parser but directly parses the restricted Pond syntax.
58
59       This module is implemented in XS, with a pure Perl backup version for
60       systems that can't handle XS.
61

REGULAR EXPRESSIONS

63       Each of these regular expressions corresponds precisely to part of Pond
64       syntax.  The regular expressions do not include any anchors, so to
65       check whether an entire string matches a production you must supply the
66       anchors yourself.
67
68       The regular expressions with "_ascii_" in the name match the subset of
69       the grammar that uses only ASCII characters.  All Pond data can be
70       expressed using only ASCII characters.
71
72       $pond_string_rx
73       $pond_ascii_string_rx
74           A string literal.  This may be a double-quoted string, a single-
75           quoted string, or a decimal integer literal.  It does not accept
76           barewords.
77
78       $pond_array_rx
79       $pond_ascii_array_rx
80           An array "[]" constructor.
81
82       $pond_hash_rx
83       $pond_ascii_hash_rx
84           A hash "{}" constructor.
85
86       $pond_datum_rx
87       $pond_ascii_datum_rx
88           Any permitted expression.  This may be a string literal, array
89           constructor, or hash constructor.
90

FUNCTIONS

92       pond_read_datum(TEXT)
93           TEXT is a character string.  This function parses it as a Pond-
94           encoded datum, with optional surrounding whitespace, returning the
95           represented item as a Perl native datum.  "die"s if a malformed
96           item is encountered.
97
98       pond_write_datum(DATUM[, OPTIONS])
99           DATUM is a Perl native datum.  This function serialises it as a
100           character string using Pond encoding.  The data to be serialised
101           can recursively contain Perl strings, arrays, and hashes.  Numbers
102           are implicitly stringified, and "undef" is treated as the empty
103           string.  "die"s if an unserialisable datum is encountered.
104
105           OPTIONS, if present, must be a reference to a hash, containing
106           options that control the serialisation process.  The recognised
107           options are:
108
109           indent
110               If "undef" (which is the default), no optional whitespace will
111               be added.  Otherwise it must be a non-negative integer, and the
112               datum will be laid out with whitespace (where it is optional)
113               to illustrate the structure by indentation.  The number given
114               must be the number of leading spaces on the line on which the
115               resulting element will be placed.  If whitespace is added, the
116               element will be arranged to end on a line of the same
117               indentation, and all intermediate lines will have greater
118               indentation.
119
120           undef_is_empty
121               If false (the default), "undef" will be treated as invalid
122               data.  If true, "undef" will be serialised as an empty string.
123
124           unicode
125               If false (the default), the datum will be expressed using only
126               ASCII characters.  If true, non-ASCII characters may be used in
127               string literals.
128

SEE ALSO

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

AUTHOR

133       Andrew Main (Zefram) <zefram@fysh.org>
134
136       Copyright (C) 2009 PhotoBox Ltd
137
138       Copyright (C) 2010, 2012, 2017 Andrew Main (Zefram) <zefram@fysh.org>
139

LICENSE

141       This module is free software; you can redistribute it and/or modify it
142       under the same terms as Perl itself.
143
144
145
146perl v5.38.0                      2023-07-20                   Data::Pond(3pm)
Impressum