view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    # 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"](#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

README.md  view on Meta::CPAN

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).

## `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](https://metacpan.org/pod/Data%3A%3ADump),
[Data::Dumper](https://metacpan.org/pod/Data%3A%3ADumper) or our own ["perl2dump"](#perl2dump),
["perl2dump\_filtered"](#perl2dump_filtered),
["perl2dump\_homebrew"](#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](https://metacpan.org/pod/JSON%3A%3APP%3A%3ABoolean) 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](https://metacpan.org/pod/YAML)
by first converting JSON to a Perl variable and then
converting that variable to YAML using ["perl2yaml"](#perl2yaml).
All the parameters supported by ["perl2yaml"](#perl2yaml)
are accepted.

It returns the YAML string on success or `undef` on failure.

## `yaml2json`

    my $ret = yaml2json($yamlstring, $optional_paramshashref)

Arguments: