/ 
JSON-TypeEncoder-0.01
/ JSON::TypeEncoder

NAME

JSON::TypeEncoder - serialize JSON using type information

SYNOPSIS

use JSON::TypeEncoder;
use Types::Standard -types;

my $type = Dict[a => Str, b => Int, c => Bool];

my $jsont = JSON::TypeEncoder->new;
my $encode = $jsont->encoder($type);

$encode->({ a => 'foo', b => 30, c => !!1 });
# => {"a":"foo","b":30,"c":true}

DESCRIPTION

JSON::TypeEncoder serialize Perl data structures to JSON using type information. This module goal is to be correct and fast.

FEATURES

Correct

This module encodes according to the specified type information. For example, it encodes as following:

use JSON::TypeEncoder;
use Types::Standard -types;

my $jsont = JSON::TypeEncoder->new;

my $s = $jsont->encoder(Dict[a => Str]);
$s->({a => 123}); # => {"a":"123"}

my $i = $jsont->encoder(Dict[a => Int]);
$i->({a => 123}); # => {"a":123}

my $b = $jsont->encoder(Dict[a => Bool]);
$b->({a => !!0}); # => {"a":false}

This will prevent unintended encoding.

Fast

Encoding performance is improved by string eval using type information. You can get speed comparable to JSON::XS. The results of a simple benchmark is as following.

First comes a comparison using a very short single-line JSON string (also available at http://dist.schmorp.de/misc/json/short.json).

{"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7, 1,  0]}

It shows the number of encodes per second. Higher is better:

#                       Rate JSON::PP JSON::XS w/ Types JSON::TypeEncoder JSON::XS
# JSON::PP           39739/s       --              -83%              -90%     -95%
# JSON::XS w/ Types 234056/s     489%                --              -42%     -72%
# JSON::TypeEncoder 405736/s     921%               73%                --     -51%
# JSON::XS          825118/s    1976%              253%              103%       --

Using a longer test string (roughly 18KB, generated from Yahoo! Locals search API (http://dist.schmorp.de/misc/json/long.json).

#                      Rate          JSON::PP          JSON::XS JSON::TypeEncoder
# JSON::PP            984/s                --              -96%              -97%
# JSON::XS          26946/s             2639%                --              -13%
# JSON::TypeEncoder 30919/s             3043%               15%                --

Pure Perl

This module is written by pure Perl. So you can easily install it.

NOT FEATURES

This module NOT supports decode JSON to Perl data structures. You should use other modules like JSON::XS to decode.

TYPE SPECIFICATION

Types::Standard is used for type specification. The basic types are as follows, you can specify the type of JSON by this combination.

Basic Types

Str

Subtype of Str encodes always to string.

my $encode = $jsont->encoder(Str);
$encode->(123) # => "123"
Num

Subtype of Num encodes always to number.

my $encode = $jsont->encoder(Num);
$encode->(123) # => 123
Bool

Subtype of Bool encodes always to boolean.

my $encode = $jsont->encoder(Bool);
$encode->(123) # => true
Dict[...]

Subtype of Dict[...] encodes always to map.

my $encode = $jsont->encoder(Dict[a => Int]);
$encode->({ a => 123 });   # => {"a":123}
$encode->({ a => '123' }); # => {"a":123}
Tuple[...]

Subtype of Tuple[A, B] encodes always to list of type A and B.

my $encode = $jsont->encoder(Tuple[Int, Str]);
$encode->([123, 456]); # => [123,"456"]
ArrayRef[`a]

Subtype of ArrayRef[A] encodes always to list of all elements type A.

my $encode = $jsont->encoder(ArrayRef[Bool]);
$encode->([1,0,undef,!!0,\0]); # => [true,false,false,false,true]
Maybe

Maybe encodes to undef if value is undef.

my $encode = $jsont->encoder(Maybe[Str]);
$encode->('hello'); # => "hello"
$encode->(undef); # => null
Optional[`a]

Dict[name => Str, id => Optional[Int]] allows { name => "Bob" } but not { name => "Bob", id => "BOB" }.

my $encode = $jsont->encoder(Dict[a => Optional[Str]]);
$encode->({a => 'foo'}); # => {"a":"foo"}
$encode->({}); # => {}

More Example

use Types::Standard -types;
use JSON::TypeEncoder;

my $type = ArrayRef[
    Dict[
        name => Str,
        fg => Bool,
        foo => Optional[Str],
        bar => Maybe[Num]
    ]
];

my $encode = JSON::TypeEncoder->new->encoder($type);
$encode->(
    [
        { name => 'a', fg => !!1, foo => '1', bar => '10' },
        { name => 'b', fg => !!0,             bar => '11' },
        { name => 'c', fg => !!1, foo => '2', bar => undef },
        { name => 'd', fg => !!0,             bar => undef },
    ]
);

# =>
# [
#   {"bar":10,"fg":true,"foo":"1","name":"a"},
#   {"bar":11,"fg":false,"name":"b"},
#   {"bar":null,"fg":true,"foo":"2","name":"c"},
#   {"bar":null,"fg":false,"name":"d"}
# ]

SEE ALSO

JSON::XS

JSON::Types

Types::Standard

LICENSE

Copyright (C) kfly8.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

kfly8 <kfly@cpan.org>

CONTRIBUTORS

karupanerura