1Data::Pond(3pm) User Contributed Perl Documentation Data::Pond(3pm)
2
6 Data::Pond - Perl-based open notation for data
7
9 use Data::Pond qw($pond_datum_rx);
10 if($expr =~ /\A$pond_datum_rx\z/o) { ...
12 # and other regular expressions
13 use Data::Pond qw(pond_read_datum pond_write_datum);
15 $datum = pond_read_datum($text);
17 $text = pond_write_datum($datum);
18 $text = pond_write_datum($datum, { indent => 0 });
19
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 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 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 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 This module is implemented in XS, with a pure Perl backup version for
60 systems that can't handle XS.
61
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 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 $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 $pond_array_rx
79 $pond_ascii_array_rx
80 An array "[]" constructor.
81 $pond_hash_rx
83 $pond_ascii_hash_rx
84 A hash "{}" constructor.
85 $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
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 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 OPTIONS, if present, must be a reference to a hash, containing
106 options that control the serialisation process. The recognised
107 options are:
108 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 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 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
130 Data::Dumper, JSON::XS, "eval" in perlfunc
131
133 Andrew Main (Zefram) <zefram@fysh.org>
134
136 Copyright (C) 2009 PhotoBox Ltd
137 Copyright (C) 2010, 2012, 2017 Andrew Main (Zefram) <zefram@fysh.org>
139
141 This module is free software; you can redistribute it and/or modify it
142 under the same terms as Perl itself.
143perl v5.38.0 2023-07-20 Data::Pond(3pm)