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

NAME

Data::Toolkit::Entry

DESCRIPTION

Data::Toolkit::Entry objects store attribute-value data. Attributes can have zero or more values. By default, attribute names are case-insensitive and are always returned in lower case.

Each attribute can have zero or more values. The list of values is kept sorted, and by default only one copy of each value is permitted. The sort order is selectable.

Data::Toolkit::Entry objects are ideal for carrying entries in directory synchronisation systems and other data-pump applications.

DEPENDENCIES

Carp
Clone
Data::Dumper
Data::MultiValuedHash

SYNOPSIS

my $entry = Data::Toolkit::Entry->new();

$count = $entry->set("surname", [ "Findlay" ]);
$count = $entry->set("cn", [ "Andrew Findlay", "A J Findlay" ]);
$count = $entry->set("mobile", []);

$count = $entry->add("newAttribute", [ "Apples" ]);
$count = $entry->add("newAttribute", [ "Pears", "Oranges" ]);

$arrayRef = $entry->get("myAttribute");
print (join ":", $arrayref), "\n";

$arrayRef = $entry->attributes();

$result = $entry->attribute_match( 'attribname', ['value1','value2'] );

$newEntry = $entry->map($thisMap);
$newEntry = $entry->map($thisMap,$entry2,$entry3,...);

$result = $entry->delete('thisAttribute','thisValue');

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

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

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

Constructor

new

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

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

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.

defaultValueComparator

If this is defined its value sets the default method of comparing values in all attributes. See comparator below for details.

defaultUniqueValues

If this is defined its value is the default for each new attribute's uniqueValues flag.

Methods

set

Set the value of an attribute, overriding what was there before. Creates the attribute if necessary.

Passing an empty list of values creates an empty attribute (this is different from the attribute not existing at all).

Passing an undef list of values deletes the attribute and returns undef.

$count = $entry->set("surname", [ "Findlay" ]);
$count = $entry->set("cn", [ "Andrew Findlay", "A J Findlay" ]);
$count = $entry->set("mobile", []);

The method returns the number of values that the attribute has, so in the examples above, $count would be 1, 2, and 0 respectively.

add

Add one or more values to an attribute. Creates the attribute if necessary.

Passing an undef list of values does nothing.

Passing an empty list of values creates an empty attribute or leaves an existing one unchanged.

$count = $entry->add("newAttribute", [ "Apples" ]);
$count = $entry->add("newAttribute", [ "Pears", "Oranges" ]);
$count = $entry->add("anotherAttribute", []);
$count = $entry->add("anotherAttribute", undef);

The method returns the number of values that the attribute has after the add operation has completed. If an undef list is added to a non-existant attribute then the return will be undef.

attrCmp

Compare two values of a specific attribute using the defined comparator for that attribute. Returns negative, zero, or positive.

$result = $entry->attrCmp( 'attributename', 'value1', 'value2' );

get

Get the list of values for an attribute.

Returns an empty list if the attribute exists but has no values.

Returns undef if the attribute does not exist.

$arrayRef = $entry->get("myAttribute");

attributes

Get the list of attributes in an entry.

Returns an empty list if there are no attributes.

Note that attributes can exist but not have values.

$arrayRef = $entry->attributes();

attribute_match

Return true or false depending on whether the named attribute contains a list of values exactly matching the one supplied.

$result = $entry->attribute_match( 'attribname', ['value1','value2'] );

The supplied list must be sorted into the same order that Data::Toolkit::Entry uses. This will automatically be done in the common case of comparing an attribute in two entries:

$result = $entry->attribute_match( 'name', $secondEntry->get('name') );

An undef list is treated as if it were an empty list.

uniqueValues

Define whether an attribute should have unique values.

By default, values are unique: an attribute will not store more than one copy of a given value, which is compared using the comparator method set for the attribute.

$uniqVal = $entry->uniqueValues( 'attributeName', 1 );
$uniqVal = $entry->uniqueValues( 'attributeName', 0 );
$uniqVal = $entry->uniqueValues( 'attributeName' );

Setting an undefined value has no effect other than to return the current setting.

Returns the setting of the uniqueValues flag.

Note that changing this flag on an attribute which already has values does not affect those values.

Passing a hash reference causes all existing uniqueValues flags to be replaced by the values specified in the hash:

$hashRef = $entry->uniqueValues( \%mySettings );

comparator

Define how values should be compared for a particular attribute.

By default, values are treated as case-insensitive text strings.

$func = $entry->comparator( 'attributeName', 'caseIgnore' );
$func = $entry->comparator( 'attributeName', 'caseSensitive' );
$func = $entry->comparator( 'attributeName', 'integer' );
$func = $entry->comparator( 'attributeName', \&myComparatorFunction );
$func = $entry->comparator( 'attributeName' );

If supplying a function of your own, it should be suitable for use in Perl's "sort" operation: it should return an integer less than, equal to, or greater than zero depending on whether its first argument is less than, equal to, or greater than its second argument. Note that sort's $a,$b convention should not be used.

Returns the name of the comparison method or a reference to a function as appropriate.

Note that changing this flag on an attribute which already has values does not affect those values.

Passing a hash reference causes all existing comparator flags to be replaced by the values specified in the hash:

$hashRef = $entry->comparator( \%myHash );

map

Create a new entry object by applying a map to the current one. Further entries can also be specified. They will be passed to the Data::Toolkit::Map generate method.

$newEntry = $entry->map($thisMap);
$newEntry = $entry->map($thisMap,$entry2,$entry3,...);

The map is a Data::Toolkit::Map object.

delete

Delete a value from an attribute:

$result = $entry->delete('thisAttribute','thisValue');

Delete an attribute and all its values:

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

In both cases, returns a list containing any values that it deleted. If nothing was deleted, returns false.

Note that deleting an attribute does not delete setting such as the comparator for that attribute.

Debugging methods

debug

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

my $currentDebugLevel = Data::Toolkit::Entry->debug();
my $newDebugLevel = Data::Toolkit::Entry(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 entry.

my $string = $entry->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/