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.

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 [, $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/

cpanm Data::Toolkit

perl -MCPAN -e shell
install Data::Toolkit