/ 
Data-Clean-JSON-0.10
River stage three • 9 direct dependents • 612 total dependents
/ Data::Clean::JSON

NAME

Data::Clean::JSON - Clean data so it is safe to output to JSON

VERSION

version 0.10

SYNOPSIS

use Data::Clean::JSON;
my $cleanser = Data::Clean::JSON->new;    # there are some options
my $data     = { code=>sub {}, re=>qr/abc/i };

my $cleaned;

# modifies data in-place
$cleaned = $cleanser->clean_in_place($data);

# ditto, but deep clone first, return
$cleaned = $cleanser->clone_and_clean($data);

# now output it
use JSON;
print encode_json($cleaned); # prints '{"code":"CODE","re":"(?^i:abc)"}'

DESCRIPTION

This class cleans data from anything that might be problematic when encoding to JSON. This includes coderefs, globs, and so on.

Data that has been cleaned will probably not be convertible back to the original, due to information loss (for example, coderefs converted to string "CODE").

The design goals are good performance, good defaults, and just enough flexibility. The original use-case is for returning JSON response in HTTP API service.

This module is significantly faster than Data::Rmap because with Rmap you repeatedly invoke anonymous subroutine for each data item. This module, on the other hand, generates a cleanser code using eval(), using native Perl for() loops.

The generated cleanser code is logged using Log::Any at trace level. You can see it, e.g. using Log::Any::App:

% TRACE=1 perl -MLog::Any::App -MData::Clean::JSON -e'$c=Data::Clean::JSON->new; ...'

METHODS

new(%opts) => $obj

Create a new instance. For list of known options, see Data::Clean::Base. Data::Clean::JSON sets some defaults.

DateTime  => [call_method => 'epoch']
Regexp    => ['stringify']
SCALAR    => ['deref_scalar']
-ref      => ['replace_with_ref']
-circular => ['detect_circular']
-obj      => ['unbless']

$obj->clean_in_place($data) => $cleaned

Clean $data. Modify data in-place.

$obj->clone_and_clean($data) => $cleaned

Clean $data. Clone $data first.

FAQ

Why clone/modify? Why not directly output JSON?

So that the data can be used for other stuffs, like outputting to YAML, etc.

Why is it slow?

First make sure that you do not construct the Data::Clean::JSON object repeatedly, as the constructor generates the cleanser code first using eval(). A short benchmark (run on my slow Atom netbook):

% bench -MData::Clean::JSON -b'$c=Data::Clean::JSON->new' \
    'Data::Clean::JSON->new->clone_and_clean([1..100])' \
    '$c->clone_and_clean([1..100])'
Benchmarking sub { Data::Clean::JSON->new->clean_in_place([1..100]) }, sub { $c->clean_in_place([1..100]) } ...
a: 302 calls (291.3/s), 1.037s (3.433ms/call)
b: 7043 calls (4996/s), 1.410s (0.200ms/call)
Fastest is b (17.15x a)

Second, you can turn off some checks if you are sure you will not be getting bad data. For example, if you know that your input will not contain circular references, you can turn off circular detection:

$cleanser = Data::Clean::JSON->new(-circular => 0);

Benchmark:

$ perl -MData::Clean::JSON -MBench -E '
  $data = [[1],[2],[3],[4],[5]];
  bench {
      circ   => sub { state $c = Data::Clean::JSON->new;               $c->clone_and_clean($data) },
      nocirc => sub { state $c = Data::Clean::JSON->new(-circular=>0); $c->clone_and_clean($data) }
  }, -1'
circ: 9456 calls (9425/s), 1.003s (0.106ms/call)
nocirc: 13161 calls (12885/s), 1.021s (0.0776ms/call)
Fastest is nocirc (1.367x circ)

The less number of checks you do, the faster the cleansing process will be.

Why am I getting 'Not a CODE reference at lib/Data/Clean/Base.pm line xxx'?

[2013-08-07 ] This error message is from Data::Clone::clone() when it is cloning an object. If you are cleaning objects, instead of using clone_and_clean(), try using clean_in_place(). Or, clone your data first using something else like Storable.

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Steven Haryanto.

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