view release on metacpan or  search on metacpan

a.html  view on Meta::CPAN

# 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).</code></pre>

<h1 id="EXPORT">EXPORT</h1>

<p>By default no symbols are exported. However, the following export tags are available (:all will export all of them):</p>

<ul>

<li><p><code>:json</code> : <code>perl2json()</code>, <code>json2perl()</code>, <code>json2dump()</code>, <code>json2yaml()</code>, <code>json2json()</code>, <code>jsonfile2perl()</code></p>

</li>
<li><p><code>:yaml</code> : <code>perl2yaml()</code>, <code>yaml2perl()</code>, <code>yaml2dump()</code>, <code>yaml2yaml()</code>, <code>yaml2json()</code>, <code>yamlfile2perl()</code></p>

</li>
<li><p><code>:dump</code> : <code>perl2dump()</code>, <code>perl2dump_filtered()</code>, <code>perl2dump_homebrew()</code></p>

</li>
<li><p><code>:io</code> : <code>read_from_file()</code>, <code>write_to_file()</code>, <code>read_from_filehandle()</code>, <code>write_to_filehandle()</code>,</p>

</li>
<li><p><code>:all</code> : everything above.</p>

</li>
<li><p>Additionally, these four subs: <code>dump2perl()</code>, <code>dump2json()</code>, <code>dump2yaml()</code>, <code>dump2dump()</code> do not belong to any export tag. However they can be imported explicitly by the caller in the usual way (e.g....

</li>
<li><p><code>no-unicode-escape-permanently</code> : this is not an export keyword/parameter but a parameter which affects all the <code>*2dump*</code> subs by setting unicode escaping permanently to false. See <a href="#EFFICIENCY">&quot;EFFICIENCY&q...

</li>
<li><p><code>unicode-escape-permanently</code> : this is not an export keyword/parameter but a parameter which affects all the <code>*2dump*</code> subs by setting unicode escaping permanently to true. See <a href="#EFFICIENCY">&quot;EFFICIENCY&quot;...

</li>
</ul>

<h1 id="EFFICIENCY">EFFICIENCY</h1>

<p>The export keyword/parameter <code>no-unicode-escape-permanently</code> affects all the <code>*2dump*</code> subs by setting unicode escaping permanently to false. This improves efficiency, although one will ever need to use this in extreme situat...

<p>Each time a <code>*2dump*</code> is called, the <code>dont-bloody-escape-unicode</code> flag is checked and if it is set, then <a>Data::Dumper</a>&#39;s <code>qquote()</code> is overriden with <code>_qquote_redefinition_by_Corion()</code> just for...

<p>The price to pay for this added efficiency is that unicode in any dump will never be escaped (e.g. <code>\x{3b1})</code>, but will be rendered (e.g. <code>&alpha;</code>, a greek alpha). Always. The option <code>dont-bloody-escape-unicode</code> w...

<p>Similarly, the export keyword/parameter <code>unicode-escape-permanently</code> affects all the <code>*2dump*</code> subs by setting unicode escaping permanently to true. This improves efficiency as well.</p>

<p>See <a href="#BENCHMARKS">&quot;BENCHMARKS&quot;</a> on how to find the fastest <code>*2dump*</code> sub.</p>

<h1 id="BENCHMARKS">BENCHMARKS</h1>

<p>The special Makefile target <code>benchmarks</code> will time calls to each of the <code>*2dump*</code> subs under</p>

<pre><code>use Data::Roundtrip;

use Data::Roundtrip qw/no-unicode-escape-permanently/;

use Data::Roundtrip qw/unicode-escape-permanently/;</code></pre>

<p>and for <code>&#39;dont-bloody-escape-unicode&#39; =&gt; 0</code> and <code>&#39;dont-bloody-escape-unicode&#39; =&gt; 1</code>.</p>

<p>In general, <a href="#perl2dump">&quot;perl2dump&quot;</a> is faster by 25% when one of the permanent import parameters is used (either of the last two cases above).</p>

<h1 id="SUBROUTINES">SUBROUTINES</h1>

<h2 id="perl2json"><code>perl2json</code></h2>

<pre><code>my $ret = perl2json($perlvar, $optional_paramshashref)</code></pre>

<p>Arguments:</p>

<ul>

<li><p><code>$perlvar</code></p>

</li>
<li><p><code>$optional_paramshashref</code></p>

</li>
</ul>

<p>Return value:</p>

<ul>

<li><p><code>$ret</code></p>

</li>
</ul>

<p>Given an input <code>$perlvar</code> (which can be a simple scalar or a nested data structure, but not an object), it will return the equivalent JSON string. In <code>$optional_paramshashref</code> one can specify whether to escape unicode with <c...

<p>The latter is useful when the input (Perl) data structure contains Perl objects (blessed refs!). But in addition to setting it, each of the Perl objects (their class) must implement a <code>TO_JSON()</code> method which will simply convert the obj...

<pre><code>sub TO_JSON { shift-&gt;data }</code></pre>

<p>the converter will replace what is returned with the blessed object which does not know what to do with it. See <a href="https://perldoc.perl.org/JSON::PP#2.-convert_blessed-is-enabled-and-the-object-has-a-TO_JSON-method.">https://perldoc.perl.org...

<p>The output can be fed back to <a href="#json2perl">&quot;json2perl&quot;</a> for getting the Perl variable back.</p>