| 1 |
Data::Pond |
| 2 |
|
| 3 |
This module is concerned with representing data structures in a textual |
| 4 |
notation known as "Pond" (*P*erl-based *o*pen *n*otation for *d*ata). |
| 5 |
The notation is a strict subset of Perl expression syntax, but is |
| 6 |
intended to have language-independent use. It is similar in spirit to |
| 7 |
JSON, which is based on JavaScript, but Pond represents fewer data types |
| 8 |
directly. |
| 9 |
|
| 10 |
The data that can be represented in Pond consist of strings (of |
| 11 |
characters), arrays, and string-keyed hashes. Arrays and hashes can |
| 12 |
recursively (but not cyclically) contain any of these kinds of data. |
| 13 |
This does not cover the full range of data types that Perl or other |
| 14 |
languages can handle, but is intended to be a limited, fixed repertoire |
| 15 |
of data types that many languages can readily process. It is intended |
| 16 |
that more complex data can be represented using these basic types. The |
| 17 |
arrays and hashes provide structuring facilities (ordered and unordered |
| 18 |
collections, respectively), and strings are a convenient way to |
| 19 |
represent atomic data. |
| 20 |
|
| 21 |
The Pond syntax is a subset of Perl expression syntax, consisting of |
| 22 |
string literals and constructors for arrays and hashes. Strings may be |
| 23 |
single-quoted or double-quoted, or may be decimal integer literals. |
| 24 |
Double-quoted strings are restricted in which backslash sequences they |
| 25 |
can use: the permitted ones are the single-character ones (such as |
| 26 |
"\n"), "\x" sequences (such as "\xe3" and "\x{e3}"), and octal digit |
| 27 |
sequences (such as "\010"). Non-ASCII characters are acceptable in |
| 28 |
quoted strings. Strings may also appear as pure-ASCII barewords, when |
| 29 |
they directly precede "=>" in an array or hash constructor. Array ("[]") |
| 30 |
and hash ("{}") constructors must contain data items separated by "," |
| 31 |
and "=>" commas, and can have a trailing comma but not adjacent commas. |
| 32 |
Whitespace is permitted where Perl allows it. Control characters are not |
| 33 |
permitted, except for whitespace outside strings. |
| 34 |
|
| 35 |
A Pond expression can be "eval"ed by Perl to yield the data item that it |
| 36 |
represents, but this is not the recommended way to do it. Any use of |
| 37 |
"eval" on data opens up security issues. Instead use the |
| 38 |
"pond_read_datum" function of this module, which does not use Perl's |
| 39 |
parser but directly parses the restricted Pond syntax. |
| 40 |
|
| 41 |
This module is implemented in XS, with a pure Perl backup version for |
| 42 |
systems that can't handle XS. |
| 43 |
|
| 44 |
INSTALLATION |
| 45 |
|
| 46 |
This is a Perl module distribution. It should be installed with whichever |
| 47 |
tool you use to manage your installation of Perl, e.g. any of |
| 48 |
|
| 49 |
cpanm . |
| 50 |
cpan . |
| 51 |
cpanp -i . |
| 52 |
|
| 53 |
Consult http://www.cpan.org/modules/INSTALL.html for further instruction. |
| 54 |
Should you wish to install this module manually, the procedure is |
| 55 |
|
| 56 |
perl Build.PL |
| 57 |
./Build |
| 58 |
./Build test |
| 59 |
./Build install |
| 60 |
|
| 61 |
COPYRIGHT |
| 62 |
|
| 63 |
Copyright (C) 2009 PhotoBox Ltd |
| 64 |
|
| 65 |
Copyright (C) 2010, 2012, 2017 Andrew Main (Zefram) <[email protected]> |
| 66 |
|
| 67 |
LICENSE |
| 68 |
|
| 69 |
This module is free software; you can redistribute it and/or modify it |
| 70 |
under the same terms as Perl itself. |