Home Page | Project Page at SourceForge


This file is a tutorial that demonstrates the [addressbook] command defined by the Tcladdressbook extension for Tcl. It documents version 1.1.3. All the Tcl instructions in the sections below are very short one-line commands which you can try in any Tcl shell, like tclsh for instance.

For a detailed and complete description of the syntax of each subcommand, refer to the help file. The home page for Tcladdressbook is on the SourceForge site.


First load the extension like this
	package require addressbook

Using the commands

The [groups] subcommand

List all the groups (ID and name)
	addressbook groups
List all the groups (only ID)
	addressbook groups -ids
List the subgroups of a specific group (ID and name)
	set groupid [lindex [addressbook groups -ids] 0]
	addressbook groups -ingroup $groupid
List the subgroups of a specific group (only ID)
	addressbook groups -ids -ingroup $groupid

The [persons] subcommand

List all the persons records (ID and name)
	addressbook persons
List all the persons records (only ID)
	addressbook persons -ids

The [count] subcommand

Count the existing groups and persons records
	addressbook count -groups
	addressbook count -persons
	addressbook count -persons -ingroup [lindex [addressbook groups -ids] 0]

The [getme] subcommand

Store the info about "me" in the variable myrecord.
	set myrecord [addressbook getme]
The value of myrecord is a keyed list. One can use the usual Tcl list commands to parse this value or special commands defined in the TclX extension (see section Using keyed lists below).

The getme command can also be used with an -id option. In that case the unique ID of the "Me" record is returned:

	set myID [addressbook getme -id]

The [setme] subcommand

Set the record that will represent in the database the logged-in user.
	set theid [lindex [addressbook persons -ids] 2]
	addressbook setme $theid
	addressbook save

The [record] subcommand

Store the ID of the first record in the variable theid
	set theid [lindex [addressbook persons -ids] 0]
Store the info about this record in the variable person. The returned value has the same keyed list format as with the [getme] subcommand.
	set person [addressbook record $theid]

Similarly with a group: store the ID of the first group in the variable theid

	set theid [lindex [addressbook groups -ids] 0]
Store the info about this group in the variable grp
	set grp [addressbook record $theid]

The [type] subcommand

Find the type (ABPerson or ABGroup) of the object corresponding to the ID $theid
	addressbook type $theid

The [create] subcommand

One can create either a group's or a person's record. The third argument will be the "name" of the new record, that is to say the name of the new group or the last name of the new person respectively. The command returns the unique ID of the created record. For instance:
	addressbook create group WorkingCommittee
	addressbook create person Beethoven
One can make them subgroups or members of an already existing group using the -ingroup option:
	set grpid [lindex [addressbook groups -ids] 0]	
	set subgrpid [addressbook create group Composers -ingroup $grpid]
	addressbook create person Beethoven -ingroup $subgrpid

The [delete] subcommand

Remove from the database the record corresponding to the ID $theid
	addressbook delete $theid
Check that there were changes (1 if yes, 0 if no)
	addressbook changed
Save the changes to make them permanent
	addressbook save

The [add] subcommand

Add to a specific group the record corresponding to the ID $theid: this can be a person as well as a group (which would then become a subgroup of the group to which it is added).
	set groupid [lindex [addressbook groups -ids] 0]
	set theid [lindex [addressbook persons -ids] 0]
	addressbook add $groupid $theid
One can add several items at a time with this command:
	addressbook add $groupid $theid1 $theid2 $theid3

The [remove] subcommand

Remove from a specific group the record corresponding to the ID $theid: this can be a person as well as a group.
	set groupid [lindex [addressbook groups -ids] 0]
	set theid [lindex [addressbook persons -ids] 0]
	addressbook remove $groupid $theid
One can remove several items at a time with this command:
	addressbook remove $groupid $theid1 $theid2 $theid3

The [parents] subcommand

List the parents of a person record (the various groups it belongs to).
	set theid [lindex [addressbook persons -ids] 0]
	addressbook parents $theid
List the parents of a person record (only ID)
	addressbook parents -ids $theid

One can also find the parents of a group using this command.

The [label] subcommand

Let's find the label of the first phone number for a record:
    set theid [addressbook getme -id]
    addressbook label $theid Phone 0
The returned string could be Home for instance. Let's change it to Personal:
    addressbook label $theid Phone 0 Personal
    addressbook save

The [set] subcommand

This command lets you get or set the value of a particular field. For instance, to get the first name, dates and address fields of the first record:
	set theid [lindex [addressbook persons -ids] 0]
	addressbook set $theid First
	addressbook set $theid ABDate
	addressbook set $theid Address
To change the first name of the first record:
	addressbook set $theid First Georgios
	addressbook changed
	addressbook save
Note that the addressbook save command must be invoked to make the changes permanent.

When setting the value of a field it is important that the new value be formatted correctly with respect to the type of the property, as explained in the help file. Here are a few examples corresponding to various property types:

The [search] subcommand

This command can be used to report the IDs of the records corresponding to a single criterion. The criterion is expressed by a three elements list: the first element is the name of a property, the second is a comparison operator and the third is the value to search for. Refer to the help file for a complete description of the possible comparison operators. A few options are available (-persons, -ids and -nocase). Here are a few simple examples:

	addressbook search Last == "Bach"
	addressbook search -persons -ids -nocase Last > "Ba"
	addressbook search -persons Modification >= 1070199949
	addressbook search -persons Modification < 1070199949

When searching on a particular property, it is important that the searched value be formatted correctly with respect to the type of the property, as explained in the help file. Specify an empty label or an empty key to search on all possible labels or keys respectively. Here are a few examples corresponding to various property types:

The [property] subcommand

This command accepts four subcommands: names, type, add, and remove.

The [property names] subcommand

Get the list of all existing properties for groups or for persons
	addressbook property names -groups
	addressbook property names -persons

The [property type] subcommand

Get the type of a particular property
	addressbook property type -groups UID
	addressbook property type -persons Address
For the two examples above, the result is respectively String and MultiDictionary.

The [property add] subcommand

Add a new person's property called Instrument with type String
	addressbook property add -persons Instrument String

Add a new group's property called Meeting with type Date

	addressbook property add -groups Meeting Date

The [property remove] subcommand

The third argument of this command can be either a record ID or the -persons and -groups keywords. If it is the former, the property is removed from the specified record, otherwise it is removed from all the records of this type and the return value is now the number of properties successfully removed.
    set theid [addressbook getme -id]
    addressbook set $theid MaidenName Violet
    addressbook save
    addressbook property remove $theid MaidenName

Remove the properties created above:

	addressbook property remove -persons Instrument
	addressbook property remove -groups Meeting

The [identifier] subcommand

This command is useful to manage distribution lists, groups used as a mailing list for instance. It has several subcommands (count, get, index, primary, and set).

The [identifier count] subcommand

Suppose theid is the record ID of a person in the group groupid:

    set groupid [lindex [addressbook groups -ids] 0]
    set theid [lindex [addressbook persons -ids -ingroup $groupid] 0]

Count the identifiers of the Phone property:

    addressbook identifier count $theid Phone

The [identifier get] subcommand

Get some identifiers by index (suppose here that there are at least two of them). Indices start at 0:

    set ident1 [addressbook identifier get $theid Phone 0]
    set ident2 [addressbook identifier get $theid Phone 1]

The [identifier primary] subcommand

Get the primary identifier (the one which is chosen by default if none has been specified otherwise):

    addressbook identifier primary $theid Phone

The [identifier set] subcommand

Get the current distribution identifier:

    addressbook identifier set $groupid $theid Phone

Set the distribution identifier to ident2:

    addressbook identifier set $groupid $theid Phone $ident2

The [identifier index] subcommand

The reverse operation of the addressbook identifier get command is the addressbook identifier index command which returns the index corresponding to a given identifier. For instance, the following instruction will return the index 1:

    addressbook identifier index $theid Phone $ident2

The [export] subcommand

Create a VCard corresponding to a particular record:
	set theid [lindex [addressbook persons -ids] 0]
	set vcardData [addressbook export $theid]
The data returned is binary. You can store it in a file for instance.

The [import] subcommand

Import in the database some information stored in a .vcf file. A new record containing this info, is created in the database:
	set fname [file join /Users bernardo someVcard.vcf]
	set fid [open $fname r]
	set vcard [read $fid]
	close $fid
	addressbook import $vcard

The [image] subcommand

Get the custom image corresponding to a particular record:
	set theid [lindex [addressbook persons -ids] 0]
	set img [addressbook image $theid]
The data returned is binary. You can store it in a file for instance. An error is raised if there is no custom image for this record.

Using keyed lists

Keyed lists can be easily manipulated using the keylget and keylset commands defined by the TclX extension. For instance, if a record has been stored in some variable myrecord, one can extract various fields like this:
	package require tclx
	keylkeys myrecord
	keylget myrecord Email.work
	keylget myrecord Address.home.ZIP
	clock format [keylget myrecord Birthday]
Similarly, with a group, one can invoke:
	set theid [lindex [addressbook groups -ids] 0]
	set grp [addressbook record $theid]
	keylkeys grp
	keylget grp GroupName
	clock format [keylget grp Modification]


Last updated 2004-08-02 09:34:50