view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        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

    The export keyword/parameter no-unicode-escape-permanently affects all
    the *2dump* subs by setting unicode escaping permanently to false. This
    improves efficiency, although one will ever need to use this in extreme
    situations where a *2dump* sub is called repeatedly in a loop of a few
    hundreds or thousands of iterations or more.

    Each time a *2dump* is called, the dont-bloody-escape-unicode flag is
    checked and if it is set, then Data::Dumper's qquote() is overriden
    with _qquote_redefinition_by_Corion() just for that instance and will
    be restored as soon as the dump is finished. Similarly, a filter for
    not escaping unicode is added to Data::Dump just for that particular
    call and is removed immediately after. This has some computational cost
    and can be avoided completely by overriding the sub and adding the
    filter once, at loading (in import()).

    The price to pay for this added efficiency is that unicode in any dump
    will never be escaped (e.g. \x{3b1}), but will be rendered (e.g. α, a
    greek alpha). Always. The option dont-bloody-escape-unicode will
    permanently be set to true.

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

    See "BENCHMARKS" on how to find the fastest *2dump* sub.

BENCHMARKS

    The special Makefile target benchmarks will time calls to each of the
    *2dump* subs under

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

    and for 'dont-bloody-escape-unicode' => 0 and
    'dont-bloody-escape-unicode' => 1.

    In general, "perl2dump" is faster by 25% when one of the permanent
    import parameters is used (either of the last two cases above).

SUBROUTINES

 perl2json

      my $ret = perl2json($perlvar, $optional_paramshashref)

    Arguments:

      * $perlvar

      * $optional_paramshashref

    Return value:

      * $ret

    Given an input $perlvar (which can be a simple scalar or a nested data
    structure, but not an object), it will return the equivalent JSON
    string. In $optional_paramshashref one can specify whether to escape
    unicode with 'escape-unicode' => 1 and/or prettify the returned result
    with 'pretty' => 1 and/or allow conversion of blessed objects with
    'convert_blessed' => 1.