Data-Roundtrip
view release on metacpan or search on metacpan
# NOTE: long strings have been broken into multilines
# and/or truncated (replaced with ...)
#---
#Artist: Καζαντζίδης ΣτÎλιος/ΒίÏβος Κώστας
#Songname: ΑπόκληÏος της κοινωνίας
$yamlstr = json2yaml($jsonstr, {'escape-unicode'=>1});
print $yamlstr;
#---
#Artist: \u039a\u03b1\u03b6\u03b1 ...
#Songname: \u0391\u03c0\u03cc\u03ba ...
$backtojson = yaml2json($yamlstr);
# $backtojson is a string representation
# of following JSON structure:
# {"Artist":"Καζαντζίδης ΣτÎλιος/ΒίÏβος Κώστας",
# "Songname":"ΑπόκληÏος της κοινωνίας"}
# This is useful when sending JSON via
# a POST request and it needs unicode escaped:
$backtojson = yaml2json($yamlstr, {'escape-unicode'=>1});
# $backtojson is a string representation
# of following JSON structure:
# but this time with unicode escaped
# (pod content truncated for readbility)
# {"Artist":"\u039a\u03b1\u03b6 ...",
# "Songname":"\u0391\u03c0\u03cc ..."}
# this is the usual Data::Dumper dump:
print json2dump($jsonstr);
#$VAR1 = {
# 'Songname' => "\x{391}\x{3c0}\x{3cc} ...",
# 'Artist' => "\x{39a}\x{3b1}\x{3b6} ...",
#};
# and this is a more human-readable version:
print json2dump($jsonstr, {'dont-bloody-escape-unicode'=>1});
# $VAR1 = {
# "Artist" => "Καζαντζίδης ΣτÎλιος/ΒίÏβος Κώστας",
# "Songname" => "ΑπόκληÏος της κοινωνίας"
# };
# pass some parameters to Data::Dumper
# like: be terse (no $VAR1):
print json2dump($jsonstr,
{'dont-bloody-escape-unicode'=>0, 'terse'=>1}
#{'dont-bloody-escape-unicode'=>0, 'terse'=>1, 'indent'=>0}
);
# {
# "Artist" => "Καζαντζίδης ΣτÎλιος/ΒίÏβος Κώστας",
# "Songname" => "ΑπόκληÏος της κοινωνίας"
# }
# this is how to reformat a JSON string to
# have its unicode content escaped:
my $json_with_unicode_escaped =
json2json($jsonstr, {'escape-unicode'=>1});
# sometimes we want JSON's true and false values
# to be mapped to something other than JSON::PP::Boolean objects:
my $json_with_custom_boolean_mapping = json2perl($jsonstr,
{'boolean_values' => 'myfalse', 'mytrue'});
my $json_with_custom_boolean_mapping = json2perl($jsonstr,
{'boolean_values' => 0, 1});
# With version 0.18 and up two more exported-on-demand
# subs were added to read JSON or YAML directly from a file:
# jsonfile2perl() and yamlfile2perl()
my $perldata = jsonfile2perl("file.json");
my $perldata = yamlfile2perl("file.yaml");
die "failed" unless defined $perldata;
# For some of the above functions there exist command-line scripts:
perl2json.pl -i "perl-data-structure.pl" -o "output.json" --pretty
json2json.pl -i "with-unicode.json" -o "unicode-escaped.json" --escape-unicode
# etc.
# only for *2dump: perl2dump, json2dump, yaml2dump
# and if no escape-unicode is required (i.e.
# setting 'dont-bloody-escape-unicode' => 1 permanently)
# and if efficiency is important,
# meaning that perl2dump is run in a loop thousand of times,
# then import the module like this:
use Data::Roundtrip qw/:all no-unicode-escape-permanently/;
# or like this
use Data::Roundtrip qw/:all unicode-escape-permanently/;
# then perl2dump() is more efficient but unicode characters
# will be permanently not-escaped (1st case) or escaped (2nd case).
EXPORT
By default no symbols are exported. However, the following export tags
are available (:all will export all of them):
* :json : perl2json(), json2perl(), json2dump(), json2yaml(),
json2json(), jsonfile2perl()
* :yaml : perl2yaml(), yaml2perl(), yaml2dump(), yaml2yaml(),
yaml2json(), yamlfile2perl()
* :dump : perl2dump(), perl2dump_filtered(), perl2dump_homebrew()
* :io : read_from_file(), write_to_file(), read_from_filehandle(),
write_to_filehandle(),
* :all : everything above.
* Additionally, these four subs: dump2perl(), dump2json(),
dump2yaml(), dump2dump() do not belong to any export tag. However
they can be imported explicitly by the caller in the usual way (e.g.
use Data::Roundtrip qw/dump2perl perl2json .../). Section CAVEATS,
under "dump2perl", describes how these subs eval() a string possibly
coming from user, possibly being unchecked.
* no-unicode-escape-permanently : this is not an export
keyword/parameter but a parameter which affects all the *2dump* subs
by setting unicode escaping permanently to false. See "EFFICIENCY".
* unicode-escape-permanently : this is not an export
keyword/parameter but a parameter which affects all the *2dump* subs
by setting unicode escaping permanently to true. See "EFFICIENCY".
EFFICIENCY
escaping unicode - this is not an option, it returns a string
representation of the input perl var
There are 2 obvious limitations:
1. indentation is very basic,
2. it supports only scalars, hashes and arrays, (which will dive into
them no problem) This sub can be used in conjuction with
DataDumpFilterino() to create a Data::Dump filter like,
Data::Dump::Filtered::add_dump_filter( \& DataDumpFilterino );
or
dumpf($perl_var, \& DataDumpFilterino);
the input is a Perl variable as a reference, so no %inp but $inp={}
and $inp=[].
This function is recursive. Beware of extremely deep nested data
structures. Deep not long! But it probably is as efficient as it can
be but definetely lacks in aesthetics and functionality compared to
Dump and Dumper.
The output is a, possibly multiline, string. Which it can then be fed
back to "dump2perl".
dump2perl
# CAVEAT: it will eval($dumpstring) internally, so
# check $dumpstring for malicious code beforehand
# it is a security risk if you don't.
# Don't use it if $dumpstring comes from
# untrusted sources (user input for example).
my $ret = dump2perl($dumpstring)
Arguments:
* $dumpstring, this comes from the output of Data::Dump, Data::Dumper
or our own "perl2dump", "perl2dump_filtered", "perl2dump_homebrew".
Escaped, or unescaped.
Return value:
* $ret, the Perl data structure on success or undef on failure.
CAVEAT: it eval()'s the input $dumpstring in order to create the Perl
data structure. eval()'ing unknown or unchecked input is a security
risk. Always check input to eval() which comes from untrusted sources,
like user input, scraped documents, email content. Anything really.
json2perl
my $ret = json2perl($jsonstring, $optional_paramshashref)
Arguments:
* $jsonstring
* $optional_paramshashref is an optional hashref as it is blindingly
obvious from the name. At the moment only one parameter is
understood: boolean_values. It must be an ARRAYREF of 0 or 2
elements. If 0 elements, then it resets the boolean values mapping of
the JSON converter to its default state (which is JSON::PP::Boolean
objects. If it contains 2 elements, then the JSON converter will map
a JSON false value to the first element of the ARRAYREF and a JSON
true value to the second element of the ARRAYREF.
Return value:
* $ret
Given an input $jsonstring as a string, it will return the equivalent
Perl data structure using
JSON::decode_json(Encode::encode_utf8($jsonstring)).
It returns the Perl data structure on success or undef on failure.
jsonfile2perl
my $ret = jsonfile2perl($filename)
Arguments:
* $filename
Return value:
* $ret
Given an input $filename which points to a file containing JSON
content, it will return the equivalent Perl data structure.
It returns the Perl data structure on success or undef on failure.
json2yaml
my $ret = json2yaml($jsonstring, $optional_paramshashref)
Arguments:
* $jsonstring
* $optional_paramshashref
Return value:
* $ret
Given an input JSON string $jsonstring, it will return the equivalent
YAML string YAML by first converting JSON to a Perl variable and then
converting that variable to YAML using "perl2yaml". All the parameters
supported by "perl2yaml" are accepted.
It returns the YAML string on success or undef on failure.
yaml2json
my $ret = yaml2json($yamlstring, $optional_paramshashref)
Arguments:
( run in 0.744 second using v1.01-cache-2.11-cpan-39bf76dae61 )