NAME

Tie::File::Indexed::JSON - tied array access to indexed data files: JSON-encoded data structures

SYNOPSIS

 use Tie::File::Indexed::JSON;
 tie(my @data, 'Tie::File::Indexed::JSON', $filename, %options) or die ...
 
 $data[0] = {foo=>'bar'}; # transparently encode/decode perl hashes
 $data[1] = [1..10];      # ... or arrays
 $data[2] = 42;           # ... or scalars
 $data[3] = undef;        # ... or undef
 print $data[1];          # retrieve & print a stored value

DESCRIPTION

Tie::File::Indexed::JSON provides a Tie::File::Indexed subclass for storing arrays of perl data structures encoded using the JSON module.

Constructors etc.

new

 $tfij = CLASS->new(%opts);
 $tfij = CLASS->new($file,%opts);
 $tfij = tie(@array, CLASS, $file, %opts);

In addition to the options supported by the Tie::File::Indexed superclass, Tie::File::Indexed::JSON also supports a 'json' option, which may be either:

• a JSON object to be used for encoding/decoding of values in the data-file, or

• a HASH-ref whose keys are the names of configuration methods for JSON objects and whose values are the arguments to those methods.

The default value of the 'json' option is:

 {
  utf8=>1,
  relaxed=>1,
  allow_nonref=>1,
  allow_unknown=>1,
  allow_blessed=>1,
  convert_blessed=>1,
  pretty=>0,
  canonical=>0
 }

CAVEATS

General caveats

See "CAVEATS" in Tie::File::Indexed for general issues regarding the Tie::File::Indexed base class.

In-place item modification not supported

Although this module supports transparent encoding and decoding of complex data structures to and from tied arrays, it does NOT support in-place modification of array items. This means that if you do something like:

 $data[0]{baz} = 'bonk';  # fails silently (array not updated)
 $val = $data[0]{baz};    # $val is undef, not 'bonk'

... the array data will not be updated. Updating any part of a complex data structure stored in the tied array requires that you re-store the entire item, e.g.

 my $tmp=$data[0];        # first extract to a temporary variable
 $tmp->{baz} = 'bonk';    # ... modify the temporary
 $data[0]    = $tmp;      # ... and then store the modified value

... or, more concisely:

 $data[0] = do { (my $tmp=$data[0])->{baz}='bonk'; $tmp };

Updating array items in this manner will cause the associated data-file to grow by the entire length of the newly stored record, orphaning the old record for the updated item. Consider using the consolidate() method to discard orphaned data-blocks if you need to perform a lot of updates.

Limited datatype support

Only datatypes which can be successfully encoded and decoded by the JSON module are supported by this class. In particlar, that means that you can't store SCALAR refs, CODE refs, or any other kind of bless()ed object without further ado. The default 'json' options are however configured to allow (en|de)coding of blessed references (via the allow_blessed and convert_blessed parameters) via their TO_JSON() methods whenever these are available. See the JSON module documentation for details.

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Bryan Jurish

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