view release on metacpan or  search on metacpan

BBDB.pm  view on Meta::CPAN

    my $result = $bbdb->$sub;
    push @lines, $result if $result;
  }
  return join("\n", @lines);
  
}


1;

=head1 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


=head1 DESCRIPTION


=head2 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 C<$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',

BBDB.pm  view on Meta::CPAN

=item address_as_text()

=item notes_as_text()

=item 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


=back

=head2 Debugging

If you find that some records in your BBDB file are failing to be
recognized, trying setting C<$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.

=head1 AUTHOR

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

=head1 SEE ALSO

BBDB texinfo documentation

=cut


=head1 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.


=cut