Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AddressBook::DB::BBDB(User Contributed Perl DocumentatAddressBook::DB::BBDB(3)

NAME
       bbdb - Perl extension for reading and writing bbdb files

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" "PMB 141"		     Address field - There are 3 fields	for
	  "524 San Anselmo Ave." ""	      for the street address, then one each
	  "San Anselmo"	"CA" (94960 2614)"     for City, State,	and Zip	Code
	 ]
	 ["mazatlan" "Reino de Navarra #757" Address field - Note that there is	no
	  "Frac. El Cid" ""		      field for	Country.  That is unfortunate
	  "Mazatlan" "Sinaloa, Mexico"	      The zip code field is quoted if its
	  ("CP"	"82110")		      not an integer
	 ]
	 )
	("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.

   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();

   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
       Phone numbers and zip codes 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.

perl v5.24.1			  2000-11-28	      AddressBook::DB::BBDB(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=AddressBook::DB::BBDB&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help