Data::Toolkit::Map
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();
Carp Clone Data::Dumper
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.
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', };
Set or replace a mapping.
$map->set( outputAttribute, generator )
outputAttribute must be a text string. Generator can be of several types:
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:
$map->generate("fn",$entry)
would result in a call like this:
firstValue("fn","xyzzy",$entry)
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');
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();
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".
Andrew Findlay
Skills 1st Ltd
andrew.findlay@skills-1st.co.uk
http://www.skills-1st.co.uk/
To install Data::Toolkit, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Toolkit
CPAN shell
perl -MCPAN -e shell install Data::Toolkit
For more information on module installation, please visit the detailed CPAN module installation guide.