/ 
Data-Toolkit-1.1
River stage zero No dependents
/ Data::Toolkit::Map

NAME

Data::Toolkit::Map

DESCRIPTION

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.

SYNOPSIS

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();

DEPENDENCIES

Carp
Clone
Data::Dumper

Constructor

new

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:

caseSensitiveNames

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.

defaultMissingValueBehaviour

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

missing

Defines the behaviour when an input attribute is entirely missing.

noValues

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

nullValue

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

emptyString

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

The possible values are:

delete

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

noValues

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.

nullValue

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.

emptyString

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

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:

$map->generate("fn",$entry)

would result in a call like this:

firstValue("fn","xyzzy",$entry)

unset

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

outputs

Return the list of attributes that the map generates.

Returns an empty list if there are no attributes.

$arrayRef = $map->outputs();

generate

Generate a list of values for a given attribute.

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

newEntry

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

Delete an output from a map.

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

Debugging methods

debug

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

dump

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

andrew.findlay@skills-1st.co.uk

http://www.skills-1st.co.uk/