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

<syntaxhighlight lang="bash">cpanel_json_xs -f storable <foo.storable >bar.json
cpanel_json_xs -t storable <foo.json >bar.storable</syntaxhighlight>

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

<syntaxhighlight lang="bash">cpanel_json_xs -f bencode <foo.benc >bar.json
cpanel_json_xs -t bencode <foo.json >bar.benc</syntaxhighlight>

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

<syntaxhighlight lang="bash">cpanel_json_xs -f clzf <foo.storable.lzf >bar.json
cpanel_json_xs -t clzf <foo.json >bar.storable.lzf</syntaxhighlight>

yaml

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

CODE

<syntaxhighlight lang="bash">cpanel_json_xs -f yaml <foo.yaml >bar.yaml
cpanel_json_xs -t yaml <foo.json >bar.storable.yaml</syntaxhighlight>

yaml-tiny

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

CODE

<syntaxhighlight lang="bash">cpanel_json_xs -f yaml-tiny <foo.yaml >bar.yaml
cpanel_json_xs -t yaml-tiny <foo.json >bar.storable.yaml</syntaxhighlight>

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

<syntaxhighlight lang="bash">cpanel_json_xs -f yaml-xs <foo.yaml >bar.yaml
cpanel_json_xs -t yaml-xs <foo.json >bar.storable.yaml</syntaxhighlight>

yaml-syck

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

CODE

<syntaxhighlight lang="bash">cpanel_json_xs -f yaml-syck <foo.yaml >bar.yaml
cpanel_json_xs -t yaml-syck <foo.json >bar.storable.yaml</syntaxhighlight>

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

<syntaxhighlight lang="bash">cpanel_json_xs -t dumper <foo.json >bar.pl
cpanel_json_xs -f eval <foo.pl >bar.json</syntaxhighlight>

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

<syntaxhighlight lang="bash">cpanel_json_xs -t dump <foo.json >bar.pl
cpanel_json_xs -f eval <foo.pl >bar.json</syntaxhighlight>

This requires installing dev-perl/Data-Dump

sereal

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

CODE

<syntaxhighlight lang="bash">cpanel_json_xs -t sereal <foo.json >bar.sereal
cpanel_json_xs -f sereal <foo.sereal >bar.json</syntaxhighlight>

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

<syntaxhighlight lang="bash">cpanel_json_xs -f cbor <foo.cbor >bar.json</syntaxhighlight>

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)

This article is issued from Gentoo. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.