CPAN::Groonga

##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

=pod

=cut

##========================================================================
## NAME
=pod

=head1 NAME

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

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 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

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

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

=cut

##----------------------------------------------------------------
## DESCRIPTION: Tie::File::Indexed: Constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item new

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

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

=over 4

=item *

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

=item *

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

=back

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
 }

=back

=cut


##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

=pod

=cut

##========================================================================
## CAVEATS
=pod

=head1 CAVEATS

=head2 General caveats

See L<Tie::File::Indexed/CAVEATS> for general issues regarding the Tie::File::Indexed
base class.

=head2 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 B<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.

=head2 Limited datatype support

Only datatypes which can be successfully encoded and decoded by the L<JSON|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 C<allow_blessed> and C<convert_blessed> parameters)
via their C<TO_JSON()> methods whenever these are available.  See the
L<JSON|JSON> module documentation for details.

=cut

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 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.

=cut