NAME
    Data::HashArray - An array class of hashes that has magical properties
    via overloading and AUTOLOAD.

ISA
    This class does not descend from any other class.

SYNOPSIS
      my $a = Data::HashArray->new(
                                              {code=>'FR', name=>'France', size=>'medium'},
                                              {code=>'TR', name=>'Turkey', size=>'medium'},
                                              {code=>'US', name=>'United States', size=>'large'}
                                              );

      print $a->[2]->{name};    # Prints 'United States'. No surprise.
      print $a->[0]->{name};    # Prints 'France'. No surprise.
      print $a->{name};             # Prints 'France'. OVERLOADED hash access.

      my $h = $a->hash('code');             # One level hash (returns a hash of a HashArray of hashes)
      my $h = $a->hash('size', 'code');     # Two level hash (returns a hash of a hash of a HashArray  of hashes)

      my $h = $a->hash('size')                                              # One level hash on 'size'.  
      my $h = $a->hash(sub { shift->{'size'}; })    # Same as above, but with a CODE reference

DESCRIPTION
    Normally, Data::HashArray is an array of hashes or hash-based objects.
    This class has some magical properties that make it easier to deal with
    multiplicity.

    First, there exist two overloads. One for hash access and the other for
    stringification. Both will act on the first element of the array. In
    other words, performing a hash access on an object of this class will be
    equivalent to performing a hash access on the first element of the
    array.

    Second, the AUTOLOAD method will delegate any method unkown to this
    class to the first item in the array as well. For this to work, at least
    the first item of the array better be an object on which one could call
    such a method.

    Both of these magical properties make it easier to deal with
    unpredictable multiplicity. You can both treat the object as an array or
    as hash (the first one in the array). This way, if your code deosn't
    know that an element can occur multiple times (in other words, if the
    code treats the element as singular), the same code should still largely
    work when the singualr element is replaced by a Data::HashArray object.

    The other practical feature of this class is the capabality to place the
    objects (or hashes) in the array into a hash keyed on the value of a
    given field or fields (see the "hash()" method for further details).

OVERLOADS
    Two overloads are performed so that a Data::HashArray object looks like
    a simple hash or a singular object if treated like one.

   hash access
    If an object of this class is accessed as if it were a reference to a
    hash with the usual "$object->{$key}" syntax, it will *behave* just like
    a genuine hash. The access will be made on the first item of the array
    (as this is an array class) assuming this item is a hash or hash-based
    object.

   stringification
    If an object of this class is accessed as if it were a string, then the
    stringification of the first item of the array will be returned.

METHODS
  CONSTRUCTORS
   new()
      my $array = Data::HashArray->new();           # An empty array
      my $array = Data::HashArray->new(@items);     # An array with initial items in it.

    CONSTRUCTOR.

    The new() constructor method instantiates a new Data::HashArray object.
    This method is inheritable.

    Any items that are passed in the parameter list will form the initial
    items of the array.

  OTHER METHODS
   hash()
      my $h = $array->hash($field);         # Single hash level with one key field
      my $h = $array->hash(@fields);        # Multiple hash levels with several key fields
      
  my $h = $array->hash('size')                                          # Concrete example. Hash on 'size'.  
      my $h = $array->hash(sub { shift->{'size'}; })        # Same as above, but with a CODE reference

    OBJECT METHOD.

    Remember that the items of a Data::HashArray object are supposed to be
    hashes or at least hash-based objects.

    When called with a single argument, the hash() method will create a hash
    of the items of the array keyed on the value of the argument 'field'.

    An example is best. Assume that we have a Data::HashArray object that
    looks like the following :

      my $array = bless ([
                          {code=>'FR', name=>'France', size=>'medium'},
                          {code=>'TR', name=>'Turkey', size=>'medium'},
                          {code=>'US', name=>'United States', size=>'large'}
                         ], 'Data::HashArray');

    Now, if we make a call to hash() as follows:

      my $hash = $array->hash('code');

    Then the resulting hash will look like the following:

      $hash = {
               FR=> bless ([{code=>'FR', name=>'France', size=>'medium'], 'Data::HashArray'),
               TR=> bless ([{code=>'TR', name=>'Turkey', size=>'medium'], 'Data::HashArray'),
               US=> bless ([{code=>'US', name=>'United States', size=>'large'}, 'Data::HashArray')
      };

    When, multiple fields are passes, then multiple levels of hashes will be
    created each keyed on the field of the corresponding level.

    If, for example, we had done the following call on the above array: my
    $hash = $array->hash('size', 'code'};

    We would then get the following hash:

      $hash = {
            large =>  {
                    US=> bless ([{code=>'US', name=>'United States', size=>'large'}, 'Data::HashArray')
                    },
            medium => {
                     FR=> bless ([{code=>'FR', name=>'France', size=>'medium'}], 'Data::HashArray'),
                     TR=> bless ([{code=>'TR', name=>'Turkey', size=>'medium'}], 'Data::HashArrayy')
                     }
       };

    Note that the last level of the hierarachy is always a HashArray of
    hashes. This is done to accomodate the case where more then one item can
    have the same key.

    Note that the arguments to this method could also be CODE references. In
    that case, the CODE is executed for each item in the array, passing the
    item reference as the first argument to the CODE refernce. The code
    BLOCK should return the expected key value for the item.

    For example, the following are equivalent:

      my $h = $array->hash('size')                                          # Concrete example. Hash on 'size'.  
      my $h = $array->hash(sub { shift->{'size'}; })        # Same as above, but with a CODE reference passed as an argument.

    .

BUGS & CAVEATS
    There no known bugs at this time, but this doesn't mean there are aren't
    any. Use it at your own risk.

    Note that there may be other bugs or limitations that the author is not
    aware of.

AUTHOR
    Ayhan Ulusoy <dev@ulusoy.name>

COPYRIGHT
      Copyright (C) 2006-2008 Ayhan Ulusoy. All Rights Reserved.

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

DISCLAIMER
    BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
    FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
    OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
    PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
    EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
    ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
    YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
    NECESSARY SERVICING, REPAIR, OR CORRECTION.

    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
    WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
    REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
    TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
    CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
    SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
    RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
    FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
    SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
    DAMAGES.