NAME¶
Data::JavaScript - Dump perl data structures into JavaScript code
SYNOPSIS¶
use Data::JavaScript; # Use defaults
@code = jsdump('my_array', $array_ref); # Return array for formatting
$code = jsdump('my_object', $hash_ref); # Return convenient string
$html = hjsdump('my_stuff', $reference); # Convenience wrapper
DESCRIPTION¶
This module is mainly intended for CGI programming, when a perl script generates
a page with client side JavaScript code that needs access to structures
created on the server.
It works by creating one line of JavaScript code per datum. Therefore,
structures cannot be created anonymously and need to be assigned to variables.
However, this format enables dumping large structures.
The module can output code for different versions of JavaScript. It currently
supports 1.1, 1.3 and you specify the version on the "use" line like
so:
use Data::JavaScript {JS=>1.3}; # The new default
use Data::JavaScript {JS=>1.1}; # Old (pre module v1.10) format
JavaScript 1.3 contains support for UTF-8 and a native "undefined"
datatype. Earlier versions support neither, and will default to an empty
string '' for undefined values. You may define your own default--for either
version--at compile time by supplying the default value on the "use"
line:
use Data::JavaScript {JS=>1.1, UNDEF=>'null'};
Other useful values might be 0, "null", or "NaN".
EXPORT¶
In addition, althought the module no longer uses Exporter, it heeds its import
conventions; "qw(:all"), "()", etc.
- jsdump('name', \$reference, [$undef]);
- The first argument is required, the name of JavaScript
object to create.
The second argument is required, a hashref or arrayref. Structures can be
nested, circular referrencing is supported (experimentally).
The third argument is optional, a scalar whose value is to be used en lieu
of undefined values when dumping a structure.
When called in list context, the function returns a list of lines. In scalar
context, it returns a string.
- hjsdump('name', \$reference, [$undef]);
- hjsdump is identical to jsdump except that it wraps the
content in script tags.
EXPORTABLE¶
- __quotemeta($str)
- This function escapes non-printable and Unicode characters
(where possible) to promote playing nice with others.
CAVEATS¶
Previously, the module eval'd any data it received that looked like a number;
read: real, hexadecimal, octal, or engineering notations. It now passes all
non-decimal values through as strings. You will need to "eval" on
the client or server side if you wish to use other notations as numbers. This
is meant to protect people who store ZIP codes with leading 0's.
Unicode support requires perl 5.8 or later. Older perls will gleefully escape
the non-printable portions of any UTF-8 they are fed, likely munging it in the
process as far as JavaScript is concerned. If this turns out to be a problem
and there is sufficient interest it may be possible to hack-in UTF-8 escaping
for older perls.
LICENSE¶
- •
- Thou shalt not claim ownership of unmodified
materials.
- •
- Thou shalt not claim whole ownership of modified
materials.
- •
- Thou shalt grant the indemnity of the provider of
materials.
- •
- Thou shalt use and dispense freely without other
restrictions.
Or if you truly insist, you may use and distribute this under ther terms of Perl
itself (GPL and/or Artistic License).
SEE ALSO¶
Data::JavaScript::LiteObject, Data::JavaScript::Anon, CGI::AJAX
AUTHOR¶
Maintained by Jerrad Pierce <jpierce@cpan.org>
Created by Ariel Brosh <schop cpan.org>. Inspired by WDDX.pm JavaScript
support.