NAME

AddressBook::Entry - An entry in the AddressBook

SYNOPSIS

An AddressBook::Entry object contains an addressbook entry's attributes, attribute metadata, and information about how to translate the attributes between different backend databases. An Entry's attributes can be accessed using either cannonical attribute names, or database-specific names.

DESCRIPTION

The following examples assume a configuration file which maps the cannonical attribute named "lastname" to the ldap attribute named "sn" and the cannonical attribute named "firstname" to the ldap attribute named "givenname". For example,

  <field name="lastname">        
    <db type="LDAP" name="sn">
  </field>
  <field name="firstname">
    <db type="LDAP" name="givenname">
  </field>

Each of the following pairs of commands will give the same result:

  $entry=AddressBook::Entry->new(attr=> {
                                   lastname=>Doe,
                                   firstname => John
                                        });
  $entry=AddressBook::Entry->new(db=>LDAP,
                                 attr=>{
                                   sn=>Doe,
                                   givenname => John
                                        });

  $entry->add(attr=>{lastname=>Doe,firstname=>John})
  $entry->add(attr=>{sn=Doe,givenname=John},db=>LDAP)

  $entry->replace(attr=>{firstname=>Jane})
  $entry->replace(attr=>{givenname=>Jane},db=>LDAP)

  $entry->delete(attrs=>[firstname,lastname])
  $entry->delete(attrs=>[givenname,sn],db=>LDAP)

Reading and writing an entry from a backend database:

  $db = AddressBook->new(source=>LDAP);
  $entry = $db->read;
  $db->write($entry);

Generating values in calculated fields:

  $entry->calculate;

Comparing entries:

  AddressBook::Entry::Compare($entry1,$entry2);

Dumping an entry:

  $entry->dump;

Note: Each attribute contains a reference to an array of values.

new

    $entry=AddressBook->new();
    $entry=AddressBook::Entry->new(attr=>\%attr);
    $entry=AddressBook::Entry->new(attr=>\%attr,db=>$db)

Create and optionally load an entry object.

All of the following parameters are optional:

%attr: An optional hash containing the attributes to add to the entry. The attribute values may be scalars or array references.
$config: An AddressBook::Config reference. If supplied, this configuration will be used and any $config_file paramater is ignored.
$config_file: The configuration file to use instead of the default (/etc/AddressBook.conf).
$db: Can be used to specify that the keys of %attr are those for a specific backend.

add

    $entry->add(attr=>\%attr);
    $entry->add(attr=>\%attr,db=>$db);

Adds attributes to the entry object. New data is added to attributes which already exist

%attr: Required hash containing the attributes to add to the entry. The attribute values may be specified as scalars or array references.
$db: Can be used to specify that the keys of %attr are those for a specific backend.

replace

    $entry->replace(attr=>\%attr);
    $entry->replace(attr=>\%attr,db=>$db);

Adds attributes to the entry object. New data is added to attributes which already exist

%attr: Required hash containing the attributes to add to the entry. The attribute values may be specified as scalars or array references.
$db: Can be used to specify that the keys of %attr are those for a specific backend.

delete

  $entry->delete(attrs=>\@attrs)
  $entry->delete(attrs=>\@attrs,db=>$db)

Remove attributes from the Entry.

@attrs: Required array containing the attributes to delete from the entry.
$db: Can be used to specify that the keys of %attr are those for a specific backend.

get

    $attr_ref = $entry->get();
    $attr_ref = $entry->get(db=>$db);
    $attr_ref = $entry->get(db=>$db,values_only=>1);

Get attributes from the Entry. Returns a hash with cannonical attribute names as keys.

$values_only: Unless "values_only" is specified, each value in the result is a hash with a "value" key pointing to the attribute value array, and a "meta" key pointing to the attribute metadata hash. If "values_only" is specified, each value in the result points to the attribute value array.
$db: Can be used to specify that the keys of %attr are those for a specific backend.

calculate

    $entry->calculate

Computes all calculated attributes. Does so in the order specified by the calc_order attribute metadata value.

compare

  AddressBook::Entry::compare($entry1,$entry2)

Returns true if all attributes in both entries match, false otherwise.

fill

  $entry->fill(db=>$db);
  $entry->fill(db=>$db,defaults=>1);

Ensures that the Entry includes all attributes for a specific backend database. New attributes are added with null values. If the "defaults" parameter is specified, new attributes are added with values as specified by the attribute "default" metadata specified in the config file.

chop

  $entry->chop

Removes null valued attributes from an Entry.

dump

    print $entry->dump

Returns the (cannonical) attribute names and values. Primarily used for debugging purposes.

AUTHOR

Mark A. Hershberger, <mah@everybody.org> David L. Leigh, <dleigh@sameasiteverwas.net>