:Title:			TcladdressbookHelp
:Man:Title:     tcladdressbook
:DestFolder:    ../../Help
:Project:		addressbook extension for Tcl
:Author:		Bernard Desgraupes <bdesgraupes@users.sourceforge.net>
:Homepage:		<http://sourceforge.net/projects/tcladdressbook>
:Created: 		2003-11-26 14:30:03
:Modified:	 	2009-03-13 09:54:28
:Keywords:		Address book, data base
:TclCmd:		set pkgversion 1.1
:ManSection:	1


((if $aida_params(target) eq "Pdf"
((s [set aida_keywd(TocDepth) 2; return ""] s))
((s [set aida_keywd(NumberingDepth) 2; return ""] s))
if))
((if $aida_params(target) eq "Html"
!! logo
((im ../Images/TclAB_logo.gif 
TclAB Logo im))
((nl ((lk TclAB.html )) Home Page lk)) | ((lk http://sourceforge.net/projects/tcladdressbook )) Project Page at SourceForge lk))
if))

((if $aida_params(target) ne "Man"
((/
This is a manual page for the Tcladdressbook extension for Tcl. It 
documents version ((s [package require addressbook] s)).
/))
((toc

((np
if))

((if $aida_params(target) eq "Man"
This page documents version ((s [package require addressbook] s))
of the Tcladdressbook extension.
if))

((s1 NAME
addressbook - manipulate the Macintosh OS X Address Book database

((s1 SYNOPSIS
((b package require addressbook b))
((nl ((b addressbook subcommand b)) ?((i arg arg i))...?

((s1 INTRODUCTION

The argument ((i subcommand i)) indicates the operation to perform. Any
unique abbreviation for each subcommand is acceptable. The valid
subcommands are explained in the next sections.


((s1 SUBCOMMANDS

((s3 addressbook add ((i groupID i)) ((i recordID ?recordID ...? i))
This command lets you add one or more already existing items (persons or
groups) designated by their unique ID ((i recordID i)) to the group with ID
((i groupID i)).

((s3 addressbook changed
This command returns 1 if there has been changes made to the database, 0
otherwise. Changes are made in memory with commands such as ((b addressbook
set b)), ((b addressbook create b)), ((b addressbook delete b)). To make
these changes permanent, one must call the ((b addressbook save b))
command. 

((s3 addressbook count (-groups | -persons) ?-ingroup ((i groupID i))?
This command returns the count of existing groups or persons in the 
database. One can specify a particular group with the -ingroup option 
to count only the subgroups or members in this group.

((s3 addressbook create (group | person) ((i name i)) ?-ingroup ((i groupID i))?
This command lets you create a new group or a new person record. The 
((i name i)) argument is the name to give to the new group or the last name of
the person for which a new record is created. With the ((i -ingroup i))
option one can make the newly created record a subgroup or a member of the
particular group with unique ID ((i groupID i)). If no error occurs, the
command returns the unique ID of the created record.

((s3 addressbook delete ((i recordID i))
This command removes the record with unique ID ((i recordID i)) from the
database. Note that any changes made to the database won't be definitive
until you invoke the ((b addressbook save b)) command.
((nl In version 1.0 of the extension, this command used to accept an option
called ((i -fromgroup i)) in order to remove the record from a particular
subgroup. This is achieved now by the ((b addressbook remove b)) command.

((s3 addressbook export ((i personID i))
This command lets you export the record with unique ID ((i personID i)) as
a VCard. The result should be considered as binary data since it can
contain an image associated to the record.

((s3 addressbook getme ?((i -id i))?
This command returns the ID or the data corresponding to the logged-in user
("Me", aka personal record). If the ((i -id i)) option is specified, it
returns the unique ID of the logged-in user. Otherwise the returned value
takes the form of a keyed list: see the ((b addressbook record b)) command
for a description of this format. Keyed lists can be easily manipulated
with the ((b keylget b)) and ((b keylset b)) commands defined in the TclX
extension. If no record is declared as the personal record, the command
raises an error.

((s3 addressbook groups ?-ids? ?-ingroup ((i groupID i))?
This command returns a list of all the existing group records: if no option
is specified, it is a list whose elements are sublists made of two
elements. The first element is the unique ID associated with the group and
the second is its name. If the ((i -ids i)) argument is specified, the
returned list will contain only the unique IDs of the groups. If the 
((i -ingroup i)) option is specified, only the subgroups contained in the group
with ID ((i groupID i)) will be returned.

((s3 addressbook identifier count ((i personID i)) ((i propName i))
This command returns the number of items in a multi-value list property
(such as ((i Phone, Email, Address, MSNInstant i)) etc.). 

((s3 addressbook identifier get ((i personID i)) ((i propName i)) ((i index i))
This command gets the unique identifier of an item in a multi-value list
property (such as ((i Phone, Email, Address i))). It returns the identifier
of the item at index ((i index i)) in the multi-value list of property ((i
propName i)) for the record corresponding to ((i personID i)). One can get
the count of identifiers using the ((b addressbook identifier count b))
command. Identifiers are used by the ((b addressbook identifier set b))
command. 
See the section ((lk #dist ))Distribution lists and identifiers lk)) 
below for explanations about identifiers.

((s3 addressbook identifier index ((i personID i)) ((i propName i)) ((i ident i))
This command returns the index in a multi-value list corresponding to the
identifier given in the ((i ident i)) argument. If ((i ident i)) is not a
valid identifier, the command raises an error. The valid identifers are the
values obtained by the ((b addressbook identifier get b)) command.

((s3 addressbook identifier primary ((i personID i)) ((i propName i)) ?((i ident i))?
This command lets you get or set the primary identifier of property 
((i propName i)) in the record ((i personID i)). This is the identifier
which will be used by default if no ((i distribution identifier i)) has
been specified using the ((b addressbook identifier set b)) command.
Property ((i propName i)) must be a multi-value list property (such as 
((i Phone, Email, Address i))). 
((nl Used without the ((i ident i)) argument, the command will return the
((i primary identifier i)) concerning property ((i propName i)) for the
person ((i personID i)).
((nl If the ((i ident i)) argument is specified, the command will set the
primary value to be the value for the given identifier ((i ident i)). This
value must be a valid identifier used by the multi-value list: one can get
the identifiers of any element of a multi-value list using the 
((b addressbook identifier get b)) command.

((s3 addressbook identifier set ((i groupID i)) ((i personID i)) ((i propName i)) ?((i ident i))?
This command lets you get or set the ((i distribution identifier i)) for a
multi-value list property of a person in a group. See the section
((lk #dist )) Distribution lists and identifiers lk)) below for 
explanations about identifiers.
((nl Used without the ((i ident i)) argument, the command will return the
((i distribution identifier i)) for the person ((i personID i)) belonging to the
group ((i groupID i)) concerning property ((i propName i)) if it was set,
otherwise the property's primary identifier. Property ((i propName i)) must
be a multi-value list property (such as ((i Phone, Email, Address i))).
((nl If the ((i ident i)) argument is specified, this will assign a
specific ((i distribution identifier i)) for the person's multi-value list
property so that the group can be used as a distribution list (a mailing
list for instance, in the case of an email property). This value must be a
valid identifier used by the multi-value list: one can get the identifiers
of any element of a multi-value list using the ((b addressbook identifier
get b)) command.

((s3 addressbook image ((i personID i)) ?((i imageData i))?
If no ((i imageData i)) argument is specified, this command returns the
custom image associated with the record corresponding to the unique ID 
((i personID i)). The returned bytes are binary data. If no image exists, it
raises an error. If an ((i imageData i)) argument is specified, it should
contain valid binary data defining an image which will be associated to the
record with unique ID ((i personID i)).

((s3 addressbook import ((i vCardData i))
This command imports data in VCard format. The data specified by the ((i
vCardData i)) argument must be valid data in VCard format: a new person's
record is created in the database corresponding to the information
contained in the VCard. The VCard data must correspond to a single person:
the command can't import multiple VCards, only one at a time. The return 
value, in case of success, it the record ID of the newly created person's 
record.

Note that the data can be binary if the VCard contains an image. 
Starting from version 1.1.1 of the extension, the image is also imported by
the command as a custom icon for the record.

((s3 addressbook label ((i recordID i)) ((i propName i)) ((i index i)) ?((i value i))?
This command lets you get or set the label of a value in a multi-value property 
for a particular record. If the property  ((i propName i)) is not a 
multivalue property, the command raises an error.
((nl Used without the ((i value i)) argument, the command will return the
current label at index ((i index i)) in property ((i propName i)) for the
record specified by ((i recordID i)). To determine the index range, one can
use the ((b addressbook identifier count b)) command.
((nl If the ((i value i)) argument is specified, the command will set the
label at index ((i index i)) to this value.

((s3 addressbook parents ?-ids? ((i recordID i))
This command returns a list of all the groups the record with unique ID 
((i recordID i)) belongs to. The elements of this list are sublists made of one
or two items: the unique ID and, possibly, the name of the record if this
field exists. If the ((i -ids i)) option is specified, only IDs are
returned. 

((s3 addressbook persons ?-ids? ?-ingroup ((i groupID i))?
This command returns a list of all the existing person records: if no
option is specified, it is a list whose elements are sublists made of one
or two items: the unique ID and, possibly, the name of the record if this
field exists. If the ((i -ids i)) argument is specified, the returned list
will contain only the unique IDs. If the ((i -ingroup i)) option is
specified, only the members belonging to the group with ID ((i groupID i))
will be returned.

((s3 addressbook property names (-groups | -persons)
This command returns a list of all the properties defined in the database
for group or person records. New properties can be created or removed with
the ((b addressbook property add b)) and ((b addressbook property remove b)) commands.

((s3 addressbook property type (-groups | -persons) ((i propName i))
This command returns the type of the property specified by the
((i propName i)) argument. The returned type is one of the values
listed with the ((b addressbook property add b)) command below 
or ((i Unknown i)). 

((s3 addressbook property add (-groups | -persons) ((i propName i)) ((i propType i))
This command lets you add a new property to the database, either for person
or for group records. The name of the new property is specified by the 
((i propName i)) argument: it must be unique. One can get the list of all the
existing properties with the ((b addressbook property names b)) command.
The type of the property is specified by the ((i propType i)) argument.
This argument can have one of the following values: ((i Array, Data, Date,
Dictionary, Integer, Real, String, MultiArray, MultiData, MultiDate,
MultiDictionary, MultiInteger, MultiReal, MultiString. i))

((s3 addressbook property remove (-groups | -persons | ((i recordID i))) ((i propName i))
This command lets you remove a property from the database, either for
person or group records, or for a particular record specified by the ((i
recordID i)) argument.

The name of the property is specified in the
((i propName i)) argument. If the third argument is either ((b -groups b)) or
((b -persons b)), the command should remove the given property from all
the records of this type in the Address Book database. Otherwise the third 
argument should be the record ID of a particular person or group: the 
property is removed for this record only. The command returns 1 in case of 
success.
((nl One can get the list of all the existing
properties with the ((b addressbook property names b)) command.

((nl ((b WARNING: b))
This command is currently only working with a ((i recordID i)) argument. It
((i does not work i)) with the ((i -groups i)) or ((i -persons i)) options
and always returns the value 0 in that case, because the function
ABRemoveProperties is not fully implemented in the AddressBook framework.
Invoking it leaves the following message in the console:
((nl    ((i "Removal of custom properties is not yet implemented" i))

((s3 addressbook record ((i recordID i))
This command returns all the data available in the database concerning
the record with unique ID ((i recordID i)).  The returned value
takes the form of a keyed list.
((nl The format used for a particular property's value depends on the type of
the property (string, integer, date, multivalue etc.). Some properties have
a multiple type: ((i MultiString i)) for fields like Email, Phone etc., ((i MultiDate i))
for fields like ABDate, ((i MultiDictionary i)) for the Address field. In case of a
multivalue, the returned value is a keyed list itself. Each element of the list
corresponds to a single property. For instance:
((lu
((li the elements of a ((i MultiString i)) or ((i MultiDate i)) value list are two-elements 
sublists: the first element is the label of the corresponding 
property (like ((i Home, Work i)) etc.) and the second is the value itself.
((li the elements of a ((i MultiDictionary i)) value list are lists themselves,
representing a Label/Dictionary pair (dictionary in the AddressBook sense,
not a Tcl dictionary as defined in version 8.5 of Tcl). Each element of
this list has two elements: the first one is the label describing the
address (like ((i Home, Work i)) etc.) and the second one is a list representing
the dictionary. The lists representing dictionaries contain two-elements
sublists: the first item is the key in the dictionary and the second one is
the value associated with this key. For instance a person could have two
addresses: each address will be returned as a Label/Dictionary pair; the
elements of the dictionary are pairs like {City Paris} or {CountryCode fr}.
lu))
((nl Dates are returned as values suitable for use with the ((b clock
format b)) Tcl command. 
It is the number of seconds relative to "Thu Jan 01 00:00:00 GMT 1970".
((nl Note that keyed lists can be easily manipulated 
using the ((b keylget b)) and ((b keylset b)) commands defined in the TclX 
extension.

((s3 addressbook remove ((i groupID i)) ((i recordID ?recordID ...? i))
This command lets you remove one or more already existing items (persons or
groups) designated by their unique ID ((i recordID i)) from the group with ID
((i groupID i)).

((s3 addressbook save
This command lets you save the changes made in the database. Commands such
as ((b addressbook set b)), ((b addressbook create b)) or ((b addressbook
delete b)) modify the data in memory: to make the changes definitive in the
database, one must call explicitely the ((b addressbook save b)) command.
To check whether there has been changes in the database, use the 
((b addressbook changed b)) command.

((s3 addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? ((i property op value i))
This command returns all the records corresponding to the criterion 
described by the last three arguments:
((lu
((li ((i property i)) is the name of the property you are searching on. 

((li ((i op i)) is an operator specifying the type of comparison. It can be 
one of the following symbols: 
((|
    ==, !=, <, <=, >, >=, !<, !>, ^=, =$
|))
which may have different interpretations depending on whether the value is 
numeric or is a string. 
((lu
((li For a numeric value, they correspond respectively to: 
((|
    ==	Equal
    !=	Not Equal
    <	Less Than
    <=	Less Than or Equal
    !>	Less Than or Equal
    >	Greater Than
    >=	Greater Than or Equal
    !<	Greater Than or Equal
|))
The ((v ^= v)) and ((v =$ v)) operators are not applicable for numeric
values and will raise an error.

((li For a string value, they correspond respectively to: 
((|
    ==	Equal
    !=	Not Equal
    >	Contains Substring
    !>	Does Not Contain Substring
    ^=	Prefix Match
    =$	Suffix Match
|))
The ((v ^= v)) and ((v =$ v)) operators match respectively at the 
beginning or at the end of the string value (they are inspired by the ^ 
and $ symbols used in regular expressions).
The ((v < v)), ((v <= v)) and ((v !< v)) operators are not applicable for
string values and will raise an error. The ((v > v)) and ((v >= v))
operators are equivalent.
lu))

((li the argument ((i value i)) is the value you are searching for. In the case  of
a simple property, ((i value i)) will be a simple string. In the case of  a
MultiString, MultiInteger or MultiDate property, ((i value i))  will  be  a
two-elements list representing  a  label/value  pair.  In  the  case  of  a
MultiDictionary property,  ((i  value  i))  will  be  a  two-elements  list
representing  a  label/dictionary  pair,  the  dictionary  itself  being  a
two-elements list representing a single key/value pair. For instance:
((|
    {Phone "01 02 03 04 05"}
    {Home {City Paris}}
|))
((nl One can specify an empty string for the label in order to perform the 
search over all the possible labels. One can also specify an empty string for 
the key in order to perform the search over all the possible keys in a dictionary. 
lu))
((nl The ((i -groups i)) or ((i -persons i)) options let you specify the
kind of records you want to search. If it is not specified, the default is
((i -persons i)). If the ((i -ids i)) option is specified, only IDs of the
matching records are returned, rather than pairs made of the ID and the
name. The ((i -nocase i)) argument concerns string comparisons and requires
that no distinction be made between uppercase and lowercase letters.
((nl To get a list of all possible properties, use the ((b addressbook 
property names b)) command. To know the type of a particular property, use 
the ((b addressbook property type b)) command.

((s3 addressbook set ((i recordID propertyName i)) ?((i value i))?
This command lets you get or set the value of a particular property for the
record with unique ID ((i recordID i)). If the ((i value i)) argument is
not specified, it returns the current value of the property specified in
the ((i propertyName i)) argument. If ((i value i)) is specified, the
property ((i propertyName i)) will be set to this value. See the 
((b addressbook record b)) command for a description of the format used for the
various kinds of properties.

((s3 addressbook setme ((i recordID i))
This command sets the record that represents the logged-in user. 

((s3 addressbook type ((i recordID i))
This command returns the type (((i ABPerson i)) or ((i ABGroup i))) of the record with 
unique ID ((i recordID i)).

((a dist )) a))
((s1 DISTRIBUTION LISTS AND IDENTIFIERS
Identifiers are necessary when one wants to use a group as a distribution
list, that is send something to all the members of the group. The members
can be addressed by ((i Address, Phone, Email i)) etc. For instance, a
group could be used as a mailing list. The ((i Address, Phone, Email i))
properties are multi-value list properties: since a person can have several
e-mail addresses, one must specify which one is to be used in the
distribution list. Labels (such as Home, Work etc.) are not sufficient to
specify precisely an e-mail because they are not unique: one can have
several e-mails with the label Work. Here the identifiers come in: each
value of a multi-value list property has an identifier. One of them can be
designated as the ((i distribution identifier i)). The AddressBook database
also has a notion of a ((i primary identifier i)): it is the identifier
which will be used by default by the distribution list if no 
((i distribution identifier i)) as been specified.


((s1 INSTALLATION
The extension is made of two files: the dynamic library (called
libTcladdressbook((s $pkgversion s)).dylib in version ((s $pkgversion s))) and a
file pkgIndex.tcl necessary for Tcl to be able to locate the extension upon
request. Both files are contained in a directory called 
TclAddressBook((s $pkgversion s)), in version ((s $pkgversion s)). 

This directory should be installed on your system in /Library/Tcl or in
~/Library/Tcl or, more generally, in any directory contained in your 
((b auto_path b)) Tcl variable. If you use the extension within the AlphaX
editor (version 8.0b11 or greater), you can also install it in the 
((i Tclextensions i)) directory located inside the
application bundle.


((if $aida_params(target) ne "Man"

((s1 VERSION HISTORY
((lu
((li 1.0b1 -- 2004/01/25 -- First public release.
((li 1.1b1 -- 2004/07/28 -- New commands [add] and [remove]. Modified
[delete] command. Modified [property remove]
command.
((li 1.1b2 -- 2004/07/29 -- New command [setme].
((li 1.1b3 -- 2004/07/30 -- New command [identifier] to handle 
distribution lists. Subcommands: count, get, primary, set.
((li 1.1b4 -- 2004/07/31 -- New command [identifier index].
((li 1.1b5 -- 2004/08/01 -- New command [identifier label]. Fixed 
setting value with [identifier primary].
((li 1.1 -- 2004/08/02 -- Tests passed. Release of 1.1 version. 
((li 1.1.1 -- 2004/08/09 -- Technical upgrade. More error checking. 
Fixed a memory leak. Images imported from VCards. 
((li 1.1.2 -- 2004/08/15 -- Technical upgrade. More error checking. 
((li 1.1.3 -- 2004/09/09 -- ABSearchComparison fix
((li 1.1.4 -- 2005/06/06 -- Compliant with TEA.
((li 1.1.5 -- 2006/01/05 -- Fixed gcc 4.0.1 warnings.
((li 1.2.1 -- 2007/11/06 -- TEA update. Universal build.
((li 1.2.2 -- 2009/03/09 -- Fixed crash in [addressbook set] with
illformatted values. Added new operators for [search] subcommand. Enabled
[label] command for group records. Added complete tests suite.
lu))
if))


((s1 REQUIREMENTS AND PORTABILITY
This extension is only useful on Macintosh platforms. Version 10.2 or
greater of the system is required: the AddressBook framework was introduced
in version 10.2 of the System (aka Jaguar).


((s1 KNOW ISSUES
Tcladdressbook was written by Bernard Desgraupes. 
Please e-mail any bug or problem you encounter: 
<bdesgraupes@users.sourceforge.net>


((s1 SOURCE CODE
Tcladdressbook is an Open Source Project. Its source code is public and can 
be found on the SourceForge site at the following address:
((nl <http://sourceforge.net/projects/tcladdressbook>

((nl Tcladdressbook binary releases are available at
((nl  <http://sourceforge.net/project/showfiles.php?group_id=96169> 
or on my web page at
((nl  <http://pagesperso-orange.fr/bdesgraupes/tcl.html>

((nl The code is under Subversion control. You can retrieve the latest stage of 
development using any Subversion client. See instructions at:
((nl <http://sourceforge.net/svn/?group_id=96169>

((nl You can also browse the Subversion repository online at
((nl <http://tcladdressbook.svn.sourceforge.net/viewvc/tcladdressbook/> 

((s1 CONTRIBUTIONS
Code contributions (Tcl scripts making use of the Tcladdressbook extension)
are very welcome. There is a "Contribs"  directory  in  the  Tcladdressbook
project on SourceForge for code contributions. They must be free  software,
distributed under an Open Source license acceptable by the SourceForge site
(for instance, the same licensing terms as the Tcl language itself).

((s1 LICENSE AND DISCLAIMER
This software is free software and distributed under the same licensing terms 
as the Tcl language itself. See license.terms in the Tcl distribution.

((nl (c) Copyright Bernard Desgraupes 2003-2009

((s1 SEE ALSO
See the TclX extension for keyed lists: TclX(n). See the Mk4Tcl extension
for commands to open the database file directly.

((s1 KEYWORDS
Address book, data base.


((-
((if $aida_params(target) ne "Man"
((nl Last updated ((s [ISOTime::ISODateAndTimeRelaxed] s))
if))



