view release on metacpan or  search on metacpan

lib/Data/Roundtrip.pm  view on Meta::CPAN

=over 4

=item * C<$filehandle> : the handle to an already opened file (for writing).

=back

Return value:

=over 4

=item * 1 on success or 0 on failure.

=back

It writes content to the specified file handle. Upon return
the file handle is still open.

It returns 1 on success or 0 on failure.

=head1 SCRIPTS

A few scripts have been put together and offer the functionality of this
module to the command line. They are part of this distribution and can
be found in the C<script> directory.

These are: C<json2json.pl>,  C<json2yaml.pl>,  C<yaml2json.pl>,
C<json2perl.pl>, C<perl2json.pl>, C<yaml2perl.pl>

=head1 CAVEATS

I have to apologise here to the authors of L<YAML::PP>
for defaming them because I clumsily wrote L<YAML::PP>
when I wanted to write L<YAML>.

So, the reality is that L<YAML::PP> does not have any
problem in handling the edge-case below.

A valid Perl variable may kill L<YAML>'s C<Load()> because
of escapes and quotes. For example this:

    my $yamlstr = <<'EOS';
    ---
    - 682224
    - "\"w": 1
    EOS
    my $pv = eval { YAML::Load($yamlstr) };
    if( $@ ){ die "failed(1): ". $@ }
    # it's dead

Strangely, there is no problem for this:

    my $yamlstr = <<'EOS';
    ---
    - 682224
    - "\"w"
    EOS
    # this is OK also:
    # - \"w: 1
    my $pv = eval { YAML::Load($yamlstr) };
    if( $@ ){ die "failed(1): ". $@ }
    # it's OK! still alive.

I have provided an author-only test (C<make deficiencies>) which
tests all three of them on the edge cases. Both L<YAML::PP>
and L<YAML::XS> pass the tests.

This L<YAML issue|https://github.com/ingydotnet/yaml-pm/issues/224> is
relevant. Many thanks to CPAN authors L<TINITA|https://metacpan.org/author/TINITA>
and L<INGY|https://metacpan.org/author/INGY> for their work on this, and
on C<YAML*> too.

For now, the plan is to still use L<YAML::PP> and avoid explicitly requiring
L<YAML::XS> until L<YAML::Any> is ready.

Be warned that sub C<dump2perl()> C<eval()>'s
its input. If this comes from the user and
it is not checked then it is considered a security
problem. Subs C<dump2json()>, C<dump2yaml()>, C<dump2dump()>
use C<dump2perl()>. The four subs will issue a warning whenever
you call them. Additionally, as from version 0.28, they need
to be explicitly imported like:

    use Data::Roundtrip qw/... dump2perl .../

They are no longer part of export tag C<:dump> nor C<:all>.
If their input comes from the user please check the input
not to contain malicious code which when C<eval()>'ed
can create security concerns.


=head1 AUTHOR

Andreas Hadjiprocopis, C<< <bliako at cpan.org> / <andreashad2 at gmail.com> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-data-roundtrip at rt.cpan.org>, or through
the web interface at L<https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-Roundtrip>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

=head1 SEE ALSO

=over 4

=item L<Convert JSON to Perl and back with unicode|https://perlmonks.org/?node_id=11115241>

=item L<RFC: PerlE<lt>-E<gt>JSONE<lt>-E<gt>YAMLE<lt>-E<gt>Dumper : roundtripping and possibly with unicode|https://perlmonks.org/?node_id=11115280>

=back

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Data::Roundtrip


You can also look for information at:

=over 4