/ 
XML-Pastor-0.50
River stage zero No dependents
/ XML::Pastor::NodeArray

NAME

XML::Pastor::NodeArray - 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 = XML::Pastor::NodeArray->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 NodeArray of hashes)
  my $h = $a->hash{'size', 'code'};	# Two level hash (returns a hash of a hash of a NodeArray  of hashes)

DESCRIPTION

XML::Pastor::NodeArray is an array class that is used for element multiplicity in XML::Pastor.

Normally, XML::Pastor::NodeArray 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 XML::Pastor::NodeARray 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 XML::Pastor::NodeArray 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 = XML::Pastor::NodeArray->new();		# An empty array
my $array = XML::Pastor::NodeArray->new(@items);	# An array with initial items in it.

CONSTRUCTOR.

The new() constructor method instantiates a new XML::Pastor::NodeArray 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

OBJECT METHOD.

Remember that the items of a XML::Pastor::NodeArray 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 XML::Pastor::NodeArray 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'}
                   ], 'XML::Pastor::NodeArray');

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'], 'XML::Pastor::NodeArray'),
         TR=> bless ([{code=>'TR', name=>'Turkey', size=>'medium'], 'XML::Pastor::NodeArray'),
         US=> bless ([{code=>'US', name=>'United States', size=>'large'}, 'XML::Pastor::NodeArray')
};

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'}, 'XML::Pastor::NodeArray')
              },
 	medium => {
               FR=> bless ([{code=>'FR', name=>'France', size=>'medium'}], 'XML::Pastor::NodeArray'),
               TR=> bless ([{code=>'TR', name=>'Turkey', size=>'medium'}], 'XML::Pastor::NodeArray')
               }
 };

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

.

BUGS & CAVEATS

There no known bugs at this time, but this doesn't mean there are aren't any. Note that, although some testing was done prior to releasing the module, this should still be considered alpha code. So 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-2007 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.

SEE ALSO

See also XML::Pastor, XML::Pastor::ComplexType