NAME

Tie::Array::CustomStorage - Tie array and value storage

SYNOPSIS

  tie @array , 'Tie::Array::CustomStorage',
   [ 
     tie_array => 'My_Tie_Array', | 
     tie_array => [ 'My_Tie_Array' , @my_args ],
   ] ,

   [
     init_storage => \&my_sub, | 
     init_storage => [ \&my_sub, @my_args ], | 
     tie_storage => 'MyTieScalar' , |
     tie_storage => [ 'MyTieScalar', @my_args], |
     class_storage => 'MyClass' , |
     class_storage => [ 'MyClass' , @my_args ], 
   ]
   [ autovivify => [ 0 | 1 ] , ]
   [ init_object => sub{ my ($obj,$idx) = @_ ; ... } , ]

DESCRIPTION

This module provides a kind of a proxy tied array. By default (without any constructor parameter), this class provides a regular array.

With a tie_array parameter (and a tied array class provided by the user), this class provides a regular tied array (as usual). All STORE and FETCH call are delegated to the user tied array class.

With a tie_storage parameter (and a tied scalar class), all value of the array are tied to the tied scalar class passed by the user. This way, you can get a array of tied scalars.

With a class_storage parameter (and a class name), you get a strongly typed array where value can only be instance of the class passed with the class_storage parameter. This object can be autovivified or not depending on the value of <autovivify> parameter.

With a init_storage parameter (and a sub ref), you get a regular array where all value are initialized with the passed sub.

By combining tie_array parameter with one of the *_storage parameter, you can get a tied array of tied scalars, or a tied array of objects or a tied array with auto-initialized values.

What's going on here ?

When the user calls tie @array , 'Tie::Array::CustomStorage', a tied array is created, let's call it a proxy array.

To let the user define its own array behavior, the proxy array contains a array that will be tied by the user class when the proxy array is created with a tie_array parameters. Let's call it the user array.

The values of the user array will contain the data that the user care about. These scalar values are contained in the storage of the user array.

This storage of the user array can also be specialized by using the tie_storage parameter or the class_storage parameter or the init_storage parameter.

CONSTRUCTOR

Parameters are:

tie_array => "Tie::MyArray"

The class to tie the user array.

tie_storage => "Tie::MyScalar"

The class to tie to the scalars contained in the user array.

class_storage => "My::Class"

All scalar contained in the values of the user array will be instances of class_storage

autovivify [ 0 | 1 ]

When fetched, the value of the user array will be automatically initialized with and instance of class_storage. (this parameter can only be used with class_storage). Default is 1.

init_object => sub { ... }

After a new object is created, this sub ref will be called with (object, index). Can be used only with class_storage.

init_storage => sub { ... }

When fetched, the value of the user array will be automatically initialized by calling this subroutine and storing its return value into the user array.

The sub ref will be called with one parameter: the index of the fetched item.

I.e., calling $array{foo} will perform:

 $array{foo} = $init_storage->('foo') ;

Requirement regarding tie_array class

Automatic tying of the scalar contained by the array means the the tying must be done on the actual scalar storage. For a standard array this variable is $self-{$name}{$key}>. For a tied array, this scalar storage is actually contained in a class provided by the user through the tie_array parameter.

The user class passed through the tie_array parameter must satisfy one of the following conditions:

• Inherit from Tie::StdArray

• Store its data in $self->{DATA} or $self->{data}

• Provide a get_data_ref method that will return a ref of the array containing the data.

EXAMPLES

  # create a array where value are initialized with a sub and arguments
  tie @array, 'Tie::Array::CustomStorage',
    init => [ \&my_sub, @my_args ] ;

  # create a regular tied array. This is equivalent to
  # tie @array, 'My_Tie_Array';
  tie @array, 'Tie::Array::CustomStorage',
    tie_array => 'My_Tie_Array' ;

  # create a regular tied array. This is equivalent to
  # tie @array, 'My_Tie_Array', foo => 'bar' ;
  tie @array, 'Tie::Array::CustomStorage',
    tie_array => [ 'My_Tie_Array', foo => 'bar' ]  ;

  # create a array where values are tied scalars
  tie @array, 'Tie::Array::CustomStorage',
    tie_storage => [ 'MyTieScalar', @my_args] ;

  # create a array where values are autovivified objects
  tie @array, 'Tie::Array::CustomStorage',
    class_storage => [ 'MyClass' , @my_args ] ;

  # create a array where values are objects (must be assigned)
  tie @array, 'Tie::Array::CustomStorage',
    class_storage => 'MyClass', autovivify => 0 ;

COPYRIGHT

Copyright (c) 2004 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Tie::Array,