Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::HashArray(3)    User Contributed Perl Documentation   Data::HashArray(3)

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.

perl v5.32.0			  2014-07-13		    Data::HashArray(3)

NAME | ISA | SYNOPSIS | DESCRIPTION | OVERLOADS | METHODS | BUGS & CAVEATS | AUTHOR | COPYRIGHT | DISCLAIMER

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::HashArray&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help