NAME

JSON::Builder - to build large JSON with temp files when memory limit, and compress optionaly.

SYNOPSIS

 use JSON::Builder;
 
 my $json = JSON::XS->new()->utf8(1)->ascii(1);
 my ($fh, $filename) = tempfile();
 unlink $filename;
 
 my $builder = JSON::Builder->new(json => $json, fh => $fh);
 or
 my $builder = JSON::Builder::Compress->new(json => $json, fh => $fh); # Compress, Base64
  
 my $fv = $builder->val( { a => 'b', c => 'd' } );
 
 my $l = $builder->list();
 $l->add( { 1 => 'a', 2 => 'b' } );
 $l->add( { 1 => 'c', 2 => 'd' } );
 my $fl = $l->end();
 
 my $o = $builder->obj();
 $o->add( o1 => ['a', 'b'] );
 $o->add( o2 => ['c', 'd'] );
 my $fo = $o->end();
 
 my %d = (
        one => 1,
        v   => $fv,
        l   => $fl,
        o   => $fo,
 );
 
 $builder->encode(\%d);
 
 # print for test
 $fh->flush();
 $fh->seek(0,0);
 print <$fh>;

MOTIVATION

Task: to create JSON while having the memory limitations.

If you have only one large value in JSON, or, large values are created one by one, you can use the streaming generator. Otherwise, you should use such a perl structure where large elements are the filehandle with the json fragments. When a perl structure is transformed into json, it bypasses and large elements are excluded from the files. The result json is written into the file.

DESCRIPTION

JSON::Builder

new

The constructor accepts the following arguments:

json

JSON object with the encode and allow_nonref methods support, e.g. JSON::XS.

fh

The filehandle of the file where the result should be written into.

read_in

LENGTH of read function. Optional.

 my $builder = JSON::Builder->new(json => $json, fh => $fh);

val

It turns the data to JSON, saves JSON into the variable file created and returns the filehandle of this temporary file:

 my $fv = $builder->val( { a => 'b', c => 'd' } );

list

Its returns the object JSON::Builder::List

obj

Its returns the object JSON::Builder::Obj

encode

Turns the passed data structure into JSON.

 my %d = (
        one => 1,
        v   => $fv, # file handler if $builder->val(...)
        l   => $fl, # file handler of JSON::Builder::List
        o   => $fo, # file handler of JSON::Builder::Obj
 );

 $builder->encode(\%d)

JSON::Builder::List

It is aimed to write the JSON elements list into the temporary file.

 my $l = $builder->list();
 $l->add( { 1 => 'a', 2 => 'b' } );
 $l->add( { 1 => 'c', 2 => 'd' } );
 my $fl = $l->end();

new

Don't use the constructor directly: use the object list method JSON::Builder.

add

It adds the element:

end

It returns the filehandle of the file with the JSON list.

JSON::Builder::Obj

It is for writing the JSON Obj to the temporary file.

 my $o = $builder->obj();
 $o->add( o1 => ['a', 'b'] );
 $o->add( o2 => ['c', 'd'] );
 my $fo = $o->end();

new

Don't use the constructor directly: use the object obj method JSON::Builder.

add

Its adds the key-value

end

It returns the filehandle of the file with the JSON object.

JSON::Builder::Compress

To ensure that the results file includes the JSON packed, use JSON::Builder::Compress instead of JSON::Builder. The packing algorithm: deflate ÉÚ Compress::Zlib. The results of that is encoded with the help of encode_base64url ÉÚ MIME::Base64.

JSON::Builder::Compress constructor can additionally take optional arguments:

fh_plain

Filehandle to save not compressed json.

encode_sub

Sub to encode chunk of compressed data. Default is sub { MIME::Base64::encode_base64url($_[0], "") }.

encode_chunk_size

Size of chunk of compressed data. Default is 57 (see MIME::Base64)

Inheritance

If you want to use your own processing algorithm of the JSON portions, you should redeclarate the init, write, write_flush methods for the JSON::Builder object.

AUTHOR

Nick Kostyria <kni@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Nick Kostyria

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.

cpanm JSON::Builder

perl -MCPAN -e shell
install JSON::Builder