Project:Perl/maint-notes/dev-perl/Cpanel-JSON-XS

Optional Features

This package ships a /usr/bin script cpanel_json_xs, which, in addition to parsing and emitting JSON, supports a variety of different input and output formats.

Some of these formats require additional dependencies to work, and it so far hasn't been worth our while to generically make them available by default with USE flags. If you would benefit from any of these being made available by USE flags, please file a bug. ( Though I'd probably default to making all requested dependencies turned on with USE="-minimal", instead of independent use flags for each feature )

storable

This emits a binary blob in perls Storable format.

CODE

cpanel_json_xs -f storable <foo.storable >bar.json
cpanel_json_xs -t storable <foo.json >bar.storable

This should be supported presently out-of-the-box, as Storable is presently shipped in perl itself. If you're unsure, make sure virtual/perl-Storable is installed.

bencode

This feature requires modules currently not shipped in Gentoo. It will pick the first of the following if they're available:

Net::BitTorrent::Protocol::BEP03::Bencode from Net-BitTorrent-Protocol which would be shipped as dev-perl/Net-BitTorrent-Protocol
Bencode from the perl dist 'Bencode' which would be shipped as dev-perl/Bencode
Convert::Bencode from Convert-Bencode which would be shipped as dev-perl/Convert-Bencode

CODE

cpanel_json_xs -f bencode <foo.benc >bar.json
cpanel_json_xs -t bencode <foo.json >bar.benc

If you desire this functionality, please file a bug indicating your preferred bencode implementation.

clzf

This feature provides an LZF compressed version of the storable option, and requires dev-perl/Compress-LZF

CODE

cpanel_json_xs -f clzf <foo.storable.lzf >bar.json
cpanel_json_xs -t clzf <foo.json >bar.storable.lzf

yaml

This feature provides reading/writing YAML files using the CPAN YAML backend, and requires dev-perl/YAML

CODE

cpanel_json_xs -f yaml <foo.yaml >bar.yaml
cpanel_json_xs -t yaml <foo.json >bar.storable.yaml

yaml-tiny

This feature provides reading/writing YAML files using the CPAN YAML::Tiny backend, and requires dev-perl/YAML-Tiny

CODE

cpanel_json_xs -f yaml-tiny <foo.yaml >bar.yaml
cpanel_json_xs -t yaml-tiny <foo.json >bar.storable.yaml

yaml-xs

This feature provides reading/writing YAML files using the CPAN YAML-LibYAML backend, also known as YAML::XS, and requires dev-perl/YAML-LibYAML

CODE

cpanel_json_xs -f yaml-xs <foo.yaml >bar.yaml
cpanel_json_xs -t yaml-xs <foo.json >bar.storable.yaml

yaml-syck

This feature provides reading/writing YAML files using the CPAN YAML::SyckLibYAML backend, and requires dev-perl/YAML-Syck

CODE

cpanel_json_xs -f yaml-syck <foo.yaml >bar.yaml
cpanel_json_xs -t yaml-syck <foo.json >bar.storable.yaml

dumper

This emits data structures in a pure-perl compatible form, using Data::Dumper. This format can only be emitted with this engine, as decoding it is basically performed by executing it as perl code.

CODE

cpanel_json_xs -t dumper <foo.json >bar.pl
cpanel_json_xs -f eval <foo.pl >bar.json

This should be supported presently out-of-the-box, as Data::Dumper is presently shipped in perl itself. If you're unsure, make sure virtual/perl-Data-Dumper is installed.

dump

This emits data structures in a pure-perl compatible form, using Data::Dump, which is a slightly more compact, but less tuneable equivalent of the dumper option. This format can only be emitted with this engine, as decoding it is basically performed by executing it as perl code.

CODE

cpanel_json_xs -t dump <foo.json >bar.pl
cpanel_json_xs -f eval <foo.pl >bar.json

This requires installing dev-perl/Data-Dump

sereal

This works with data structures in the new "Sereal" binary format.

CODE

cpanel_json_xs -t sereal <foo.json >bar.sereal
cpanel_json_xs -f sereal <foo.sereal >bar.json

To work with this format, make sure you install dev-perl/Sereal-Encoder for writing sereal files, and dev-perl/Sereal-Decoder for reading sereal files. ( Though, both of these should become available by installing dev-perl/Sereal )

cbor

This option allows for decoding (but for some reason, not writing) data in CBOR/RFC7049 format, using CBOR::XS.

CODE

cpanel_json_xs -f cbor <foo.cbor >bar.json

To use this option, make sure you install dev-perl/CBOR-XS

Tests

This package includes various interop tests, which would be potentially prohibitive to add as explicit dependencies.

This is likely not a complete list, but to enable these tests, one must first install:

If, while testing, you spot anything else not already in this list, either:

If it breaks tests, file a bug
If it emits something like
CODE
```
skipped: Mojo::JSON required for testing interop
```
please add it to the above list (or contact me to add it to the list)