NAME

BBDB - Read and Write BBDB files

VERSION

Version 1.40

SYNOPSIS

use BBDB;
my $x = new BBDB();
$x->decode($string);
my $str = $x->encode();
# At this point, subject to the BUGS below
# $str is the same as $string

my $allR = BBDB::simple('/home/henry/.bbdb');
map { print $_->part('first')} @$allR;   # print out all the first names

DESCRIPTION

Data Format

The following is the data layout for a BBDB record. I have created a sample record with my own data. Each field is just separated by a space. I have added comments to the right

["Henry"                             The first name - a string
"Laxen"                              The last name - a string
("Henry, Enrique")                   Also Known As - comma separated list
"Elegant Solution"                   Business name - a string
(["home" 415 789 1159 0]             Phone number field - US style
 ["fax" 415 789 1156 0]              Phone number field - US style
 ["mazatlan" "011-5269-164195"]      Phone number field - International style
)
(["mailing"                          The address location, then a list
  ("PMB 141" "524 San Anselmo Ave.") for the street address, then one each
  "San Anselmo" "CA" "94960" "USA"   for City, State, Zip Code, and country
 ]
 ["mazatlan"                         another Address field
  ("Reino de Navarra #757" "Frac. El Cid") The street list
  "Mazatlan" "Sinaloa"               City State
  "82110" "Mexico"                   Zip and country
 ]
 )
("nadine.and.henry@pobox.com"        The net addresses - a list of strings
 "maztravel@maztravel.com")
((creation-date . "1999-09-02")      The notes field - a list of alists
 (timestamp . "1999-10-17")
 (notes . "Always split aces and eights")
 (birthday "6/15")
)
nil                                  The cache vector - always nil
]

After this is decoded it will be returned as a reference to a BBDB object. The internal structure of the BBDB object mimics the lisp structure of the BBDB string. It consists of a reference to an array with 9 elements The Data::Dumper output of the above BBDB string would just replaces all of the ()s with []s. It can be accessed by using the $bbdb-part('all')> method. For completeness, here is the output of Data::Dumper for the above record:

$VAR1 = bless( {
                'data' => [
                            'Henry',
                            'Laxen',
                            [
                              'Henry, Enrique'
                            ],
                            'Elegant Solutions',
                            [
                              [
                                'home',
                                [
                                  '415',
                                  '789',
                                  '1159',
                                  '0'
                                ]
                              ],
                              [
                                'fax',
                                [
                                  '415',
                                  '789',
                                  '1156',
                                  '0'
                                ]
                              ],
                              [
                                'mazatlan',
                                '011-5269-164195'
                              ]
                            ],
                            [
                              [
                                'mailing',
                                [
                                  'PMB 141',
                                  '524 San Anselmo Ave.'
                                ],
                                'San Anselmo',
                                'CA',
                                '94960',
                                'USA'
                              ],
                              [
                                'mazatlan',
                                [
                                  'Reino de Navarra #757',
                                  'Frac. El Cid'
                                ],
                                'Mazatlan',
                                'Sinaloa',
                                'CP-82110',
                                'Mexico'
                              ]
                            ],
                            [
                              'nadine.and.henry@pobox.com',
                              'maztravel@maztravel.com'
                            ],
                            [
                              [
                                'creation-date',
                                '1999-09-02'
                              ],
                              [
                                'timestamp',
                                '1999-10-17'
                              ],
                              [
                                'notes',
                                'Always split aces and eights'
                              ],
                              [
                                'birthday',
                                '6/15'
                              ]
                            ]
                          ]
              }, 'BBDB' );

Methods

new()

called whenever you want to create a new BBDB object. my $bbdb = new BBDB();

part(name [value])

Called to get or set all or part of a BBDB object. The parts of the object are:

all first last aka company phone address net notes

any other value in the name argument results in death. Some of these parts, namely phone, address, net, and notes have an internal structure and are returned as references to arrays. The others are returned just as strings. The optional second argument sets the part of this BBDB object to the value you provided. There is no consistency checking at this point, so be sure the value you are setting this to is correct.

my $first = $bbdb->part('first');    # get the value of the first field
$bbdb->part('last','Laxen');         # set the value of the last field
my $everything = $bbdb->part('all'); # get the whole record

BBDB::simple(file_name,[array_ref_of_bbdb])

This is a "simple" interface for reading or writing an entire BBDB file. If called with one argument, it returns a reference to an array of BBDB objects. Each object contains the data from the file. Thus the number of BBDB entries equals scalar(@$bbdb) if you use:

$bbdb = BBDB::simple('/home/henry/.bbdb');

If called with two arguments, the first is the filename to create, and the second is a reference to an array of BBDB objects, such as was returned in the one argument version. The objects are scanned for unique user defined fields, which are written out as the 2nd line in the BBDB file, and then the individual records are written out.

decode(string)

Takes a string as written in a BBDB file of a single BBDB record and decodes it into its PERL representation. Returns undef if it couldn't decode the record for some reason, otherwise returns true.

$bbdb->decode($entry);

encode()

This is the inverse of decode. Takes an internal PERL version of a BBDB records and returns a string which is a lisp version of the data that BBDB understands. There are some ambiguities, noted in BUGS below.

my $string = $bbdb->encode();

note_by_name('key')

Returns the value associated the the specified key in the notes part. Returns undef if the key is not found or is not unique (which I don't think can happen)

Printing methods

The parts first, last, and company, are all stored as strings, so you can print them out with a simple print $bbdb->part('name') if you like. The rest of the parts have an internal structure, and a method is provided to return them as a string, suitable for printing. The method names are the same as the part names, with a _as_text appended to the part name. For example to print out all of the addresses for a particular BBDB object, just say $bbdb->address_as_text Just for completeness, the methods are named here:

aka_as_text()

net_as_text()

phone_as_text()

address_as_text()

notes_as_text()

all_as_text()

This returns as a string the entire BBDB object using the methods defined above. For example, the sample record will print out as follows:

Henry Laxen
Elegant Solutions
Henry, Enrique
nadine.and.henry@pobox.com
maztravel@maztravel.com
home: (415)-789-1159
fax: (415)-789-1156
mazatlan: 011-5269-164195
mailing: PMB 141
         524 San Anselmo Ave.
         San Anselmo, CA
         94960 USA
mazatlan: Reino de Navarra #757
          Frac. El Cid
          Mazatlan, Sinaloa
          CP-82110 Mexico
creation-date: 1999-09-02
timestamp: 1999-10-17
notes: Always split aces and eights
birthday: 6/15

Debugging

If you find that some records in your BBDB file are failing to be recognized, trying setting $BBDB::debug = 1; to turn on debugging. We will then print out to STDERR the first field of the record that we were unable to recognize. Very handy for complicated BBDB records.

AUTHOR

Henry Laxen <nadine.and.henry@pobox.com> http://www.maztravel.com/perl

SEE ALSO

BBDB texinfo documentation

BUGS

In version 2.32 of BBDB, despite what the documentation says, it seems that zip codes are always stored quoted strings, even though it seems to be impossible to enter anything other than an integer.

Phone numbers may be converted from strings to integers if they are decoded and encoded. This should not affect the operation of BBDB. Also a null last name is converted from "" to nil, which also doesn't hurt anything.

You might ask why I use arrays instead of hashes to encode the data in the BBDB file. The answer is that order matters in the bbdb file, and order isn't well defined in hashes. Also, if you use hashes, at least in the simple minded way, you can easily find yourself with legitimate duplicate keys.