Andrew Findlay > Data-Toolkit > Data::Toolkit::Map



Annotate this POD

View/Report Bugs
Module Version: 1.0   Source  




Data::Toolkit::Map objects implement mapping functions for attribute names and values in Data::Toolkit::Entry objects. This is useful when converting between different data representations in directory-synchronisation projects.


   my $map = Data::Toolkit::Map->new();

   $map->set("surname", "sn" );

   $map->set("objectclass", [ "inetOrgPerson", "organizationalPerson", "person" ] );
   $map->set("phone","+44 1234 567890");
   $map->set("address", \&buildAddress);
   $map->set("fn", sub { return firstValue("fullname", @_) });

   $arrayRef = $map->outputs();

   $values = $map->generate('attributeName', $entry [, $entry...]);

   $newEntry = $map->newEntry($source1, $source2 ...);

   $result = $map->delete('thisAttribute');

   my $currentDebugLevel = Data::Toolkit::Map->debug();
   my $newDebugLevel = Data::Toolkit::Map->debug(1);

   my $string = $map->dump();



Constructor ^


   my $map = Data::Toolkit::Map->new();
   my $map = Data::Toolkit::Map->new( {configAttrib => value, ....} );

Creates an object of type Data::Toolkit::Map

Optionally accepts a hash of configuration items chosen from this list:


If this is defined with a true value then attribute names are case-sensitive. By default they are not, so "Surname", "surname", and "SurName" are all the same attribute.


This is a hash defining what to do when mapping attributes that do not have values. The keys are:


Defines the behaviour when an input attribute is entirely missing.


Defines the behaviour when an input attribute exists but it has no values.


Defines the behaviour when an input attribute exists and its first value is undef.


Defines the behaviour when an input attribute has an empty string as its first value.

The possible values are:


Delete the attribute entirely from the output of the map. If the generate method is used on such an attribute, it will return undef.


The attribute will appear in the output of the map but no values will be defined. If the generate method is used on such an attribute, it will return an empty array.


The attribute will appear in the output of the map and its single value will be undef. If the generate method is used on such an attribute, it will return an array containing one undef element.


The attribute will appear in the output of the map with a single empty string value.

A subroutine reference or closure

If a pointer to an executable procedure is used as the value, that procedure will be called and its return value used as the value of the attribute. The return value can be undef, scalar, vector, or hash. There is no way for the subroutine to request deletion of the entire attribute.

The subroutine is called with the name of the attribute being generated as its first parameter, an indication of whether an array result is wanted as its second parameter, and a reference to the input entry as its third parameter:

subroutine( $attributename, $wantarray, $entry);

The default missing value behaviour is:

                        missing => 'delete',
                        noValues => 'noValues',
                        nullValue => 'nullValue',
                        emptyString => 'emptyString',

Methods ^


Set or replace a mapping.

   $map->set( outputAttribute, generator )

outputAttribute must be a text string. Generator can be of several types:

SCALAR - the value is the name of an attribute in the source entry, which is copied to the outputAttribute
ARRAY - the value is a fixed array of strings which will be used as the value of the outputAttribute
CODE - the value is a procedure or closure that is run to generate the value of the outputAttribute. The procedure must return undef or an array reference.

This is a simple mapping that generates a "surname" attribute by copying the value of the input entry's "sn" attribute:

   $map->set("surname", "sn" );

This is a fixed mapping generating an LDAP objectClass attribute with several values:

   $map->set("objectclass", [ "inetOrgPerson", "organizationalPerson", "person" ] );

This is a fixed mapping generating a single value (note the use of a list to distinguish this from the first case above):

   $map->set("phone", ["+44 1234 567890"]);

This is a dynamic mapping where the attribute is generated by a procedure:

   $map->set("address", \&buildAddress);

When a dynamic mapping is evaluated, it is given the name of the attribute being generated followed by all the parameters that were passed to the "generate" call, so it can refer to entries and other objects.

Similarly, closures can be used:

   $map->set("fn", sub { return firstValue("xyzzy", @_) });

In this example, when the firstValue() procedure is called by "generate", it gets one fixed parameter plus anything else that was passed to the "generate" call. Thus the call:


would result in a call like this:



Removes an attribute from a map. Returns a reference to the deleted value.


Return the list of attributes that the map generates.

Returns an empty list if there are no attributes.

   $arrayRef = $map->outputs();


Generate a list of values for a given attribute.

   $values = $map->generate('attributeName', $entry );


Create a new entry object by applying a map to one or more existing entries

   $newEntry = $map->newEntry($source1, $source2 ...);

The source objects are Data::Toolkit::Entry objects


Delete an output from a map.

   $result = $map->delete('thisAttribute');

Debugging methods ^


Set and/or get the debug level for Data::Toolkit::Map

   my $currentDebugLevel = Data::Toolkit::Map->debug();
   my $newDebugLevel = Data::Toolkit::Map->debug(1);

Any non-zero debug level causes the module to print copious debugging information.

Note that this is a package method, not an object method. It should always be called exactly as shown above.

All debug information is reported using "carp" from the Carp module, so if you want a full stack backtrace included you can run your program like this:

   perl -MCarp=verbose myProg


Returns a text representation of the map.

   my $string = $map->dump();

Error handling ^

If you miss out an essential parameter, the module will throw an exception using "croak" from the Carp module. These exceptions represent programming errors in most cases so there is little point in trapping them with "eval".

Author ^

Andrew Findlay

Skills 1st Ltd

syntax highlighting: