The [contactRef] command.
Contact Properties
Examples
Introduction
The contactRef command gives access to your contacts for AlphaTcl
packages. It lets you manage the contacts stored in the system-wide Address
Book database, retrieve information, create new records, organize them in
subgroups, etc.
Conceptually, the database is made of two kinds of records: person
records and group records. The groups are containers that let you organize
your contacts. A person can belong to multiple groups or to none at all.
Groups can contain persons and subgroups. A group to which a person or subgroup
belongs is called a parent group.
All the items (persons or groups) have a unique identifier
(referred to, in this document, as their unique ID).
Each record contains an arbitrary number of fields known as
properties. See the Contact Properties section for
more information.
Synopsis
The formal syntax of the [contactRef] command is:
| contactRef subcommand ?options? |
The possible subcommands are described below. Depending on the
subcommand, some options may be specified.
The [add] subcommand
This subcommand adds items to a group. The complete syntax is:
contactRef add groupID recordID ?recordID ...?
The groupID argument is the unique identifier of a group. The recordID arguments are the identifiers of the items you want to add to
the group. These items can be either groups or persons. If an item is
already part of this group, it is ignored. Recursions are not allowed (you
cannot add a group to itself) and are silently ignored.
The [count] subcommand
This subcommand lets you get the count of items (groups or persons) in the
database. The complete syntax is:
contactRef count ?-groups? ?-in groupID?
By default, the command reports the number of people. If the -groups option is specified, it reports the number
of groups instead.
If the -in option is
specified, the count is limited to the contents of the group designated by
the groupID identifier.
The [create] subcommand
This subcommand creates a new record (group or person). The complete syntax is:
contactRef create (group|person) name
In case of success, the command returns the unique ID of the newly created
item. Note that the record is created in memory and that you must invoke
the [contactRef save] to actually write it in the
Address Book database.
The [delete] subcommand
This subcommand removes a record (group or person) from the Address Book
database. The complete syntax is:
contactRef delete recordID
If recordID is not a valid record identifier, the command raises an
error. Otherwise, the return value is empty.
The [groups] subcommand
This subcommand returns all the groups in the AddressBook database. The
complete syntax is:
contactRef groups ?-in groupID?
It returns a list of identifiers.
The -in option lets you specify the
identifier of a group: in that case, the output is limited to the subgroups
of this group.
The [identifiers] subcommand
This subcommand lets you manage the identifiers of multivalue properties.
The complete syntax is:
contactRef identifiers subcommand ?options?
This command applies only to multivalue properties. As explained in the
section Property Labels and Identifiers, all the values
in a multivalue have a unique identifier (not to be confused with record
identifiers). It supports the following subcommands.
The [identifiers distribution] subcommand
contactRef identifiers distribution personID propName groupID ?id?
This command lets you get or set the distribution identifier. The
propName property must be a multivalue property and personID must belong to the group groupID. If the id argument is
not specified, the command returns the current distribution identifier
(which would be, by default, the primary identifier). If id is
specified, it must be one of the identifiers of the multivalued property
propName: the command then makes it the new distribution
identifier.
The command will raise an error if the property is not a multivalue
list property, or if the person is not a member of the group.
For more information about the distribution identifier, see the
Distribution identifier section.
The [identifiers get] subcommand
contactRef identifiers get recordID propName
This command returns the identifiers of all the values of the propName property for the record recordID.
The [identifiers primary] subcommand
contactRef identifiers primary recordID propName ?id?
This command lets you get or set the primary identifier. The propName property must be a multivalue property for the recordID record. If the id argument is not specified, the command
returns the current primary identifier. If id is specified, it must
be one of the identifiers of the multivalued property propName: the
command then makes it the new primary identifier.
For more information about the primary identifier, see the
Primary identifier section.
The [image] subcommand
This subcommand lets you get or set the image of a person in the Address
Book. The complete syntax is:
contactRef image personID
contactRef image personID (data | -token imgToken)
In the first form, the command returns the current image representation (if
it exists) of the person with unique ID personID. The return value
is binary. It raises an error if no image is available.
In the second form, the command sets the image of the person record
with unique ID personID. The contents of the image can be passed
directly as binary data. Alternatively, one can specify the image using the
-token argument: its value must be
a valid image token (typically obtained with the [imageRef create] command). Data should be in an NSImage/QuickTime compatible format.
The [labels] subcommand
This subcommand lets you get or set the labels of multivalue properties.
The complete syntax is:
contactRef labels recordID propName
contactRef labels recordID propName index
contactRef labels recordID propName index value
The first form of the command lets you get the all the labels of a multivalue
property.
The second form of the command allows you to get the label of the
value at a given index in a multivalued property (the first value is at
index 0).
The third form of the command lets you set the label at the given
index to the given value.
This command applies only to multivalue properties: if propName is a single value property, the command raises an error. If index is out of range, the command also raises an error.
For more information about labels, see the
Property Labels and Identifiers section.
The [me] subcommand
This subcommand lets you get the record of the current user. The
complete syntax is:
contactRef me
The command returns the unique ID of the record that represents
the user.
The [modified] subcommand
This subcommand tells whether the address book has unsaved changes. The
complete syntax is:
contactRef modified
It returns 1 if changes were made in the database, 0
otherwise. Changes are made in memory with commands such as
[contactRef create],
[contactRef remove] or
[contactRef set].
The [name] subcommand
This subcommand builds a display name for a given item (group or
person). The complete syntax is:
contactRef name recordID
It returns a formatted name for the record with unique ID recordID
suitable for displaying to the user. This display name is composed using
the available name or organization properties.
The [parents] subcommand
This subcommand lists all the groups containing a given item (group or
person). The complete syntax is:
contactRef parents recordID
If the recordID argument represents a person, the command returns
the unique IDs of all the groups this person belongs to, otherwise, if
recordID represents a group, it returns the unique IDs of all the
groups this group belongs to.
The [persons] subcommand
This subcommand returns all the people in the AddressBook database. The
complete syntax is:
contactRef persons ?-in groupID?
It returns a list of identifiers.
The -in option lets you specify the
identifier of a group: in that case, the output is limited to the members
of this group.
The [property] subcommand
This subcommand lets you get information about the existing properties and
add new ones. The complete syntax is:
contactRef property subcommand ?options?
It supports the following subcommands.
The [property add] subcommand
contactRef property add ?-groups? propName propType
This command lets you define custom properties. The propName
argument is the name of the new property. Property names must be unique:
you may want to use Java-style package names for your properties, for
example, org.dogclub.dogname or com.alphacocoa.fans.
The propType argument is the type of the new property: see the
possible values in the
Types table below.
By default, this command applies to person properties, but if the
-groups option is specified,
it applies to group properties.
Caveat:
- this command fails if the property propName already
exists, so it is best to call it within a [catch] statement.
- there is unfortunately no way to remove a custom property. This is an
OS X bug: as stated in Apple's documentation for the ABRecord class, the
[removeProperties]
method is not implemented.
The [property list] subcommand
contactRef property list recordID
This command returns the list of the currently defined properties in the
record with unique ID recordID. The record can be either a person,
or a group.
The [property names] subcommand
contactRef property names ?-groups?
This command returns the names of the currently defined properties
(built-in and custom properties).
By default, it applies to person properties, but if the
-groups option is specified,
it returns group properties.
The [property type] subcommand
contactRef property type ?-groups? propName
This command lets you query the type of a given property. The propName
argument must be the name of an existing property.
By default, it applies to person properties, but if the
-groups option is specified,
it applies to group properties.
The return value is one of the values listed in the Types table below.
The [remove] subcommand
This subcommand removes items from a group. The complete syntax is:
contactRef remove groupID recordID ?recordID ...?
The groupID argument is the unique identifier of a group. The
recordID arguments are the identifiers of the items you want to
remove from the group. These items can be either groups or persons. If an
item is not part of the group, it is ignored.
The [save] subcommand
This subcommand lets you save the changes made in the address book. The
complete syntax is:
contactRef save
It saves on disk the changes made since the last save.
If the operation fails, the command raises an error. See the command
[contactRef modified] to check if the database has
unsaved changes.
The [search] subcommand
This subcommand lets you perform simple searches on the Address Book
database. The complete syntax is:
contactRef search ?-groups? ?-nocase? ?-key str? ?-label str? property op value
This command searches all the records corresponding to the criterion
described by the last three arguments:
- the property argument is the name of the property you are searching on.
- the op argument is an operator specifying the type of comparison. It can be
one of the following symbols:
which are interpreted differently depending on whether the value is
numeric or is a string.
- For a numeric value, the operators have the following meaning:
| Symbol | Description |
| == | Equal |
| != | Not Equal |
| < | Less Than |
| <= | Less Than or Equal |
| !> | Less Than or Equal |
| > | Greater Than |
| >= | Greater Than or Equal |
| !< | Greater Than or Equal |
The ^= and =$ operators are not applicable for numeric
values and will raise an error.
- For a string value, they correspond respectively to:
| Symbol | Description |
| == | Equal |
| != | Not Equal |
| > | Contains Substring |
| !> | Does Not Contain Substring |
| ^= | Prefix Match |
| =$ | Suffix Match |
The ^= and =$ operators match respectively at the
beginning or at the end of the string value (similar to the ^
and $ symbols used in regular expressions).
The <, <= and !< operators are not applicable for
string values and will raise an error. The > and >=
operators are equivalent.
- the value argument is the value you are searching for.
It must have the appropriate format for the given property: a numeric value
for types like Integer, Real, or Date, and a string otherwise.
By default, this command applies to person properties, but if the -groups option is specified, it
applies to group properties instead.
The -nocase option concerns
string comparisons and indicates that no distinction is made between upper
and lower case.
The -label option lets you
specify a particular label in case the property argument
corresponds to a multivalue property. Do not specify this option if you
want to perform the search over all the possible labels.
The -key option lets you
specify a particular key in case the property argument corresponds
to a dictionary. Do not specify this option if you want to search all keys.
The command returns a list of unique IDs for all the records matching the
search criterion.
The [set] subcommand
This subcommand lets you get or set the value of a property for a given
item (group or person). The complete syntax is:
contactRef set recordID propertyName
contactRef set recordID propertyName value
In the first form, the command returns the value of the property propertyName for the item designated by the recordID argument.
If propertyName is a multivalue property, the command returns a
keyed list (see the Property Labels and Identifiers
section).
In the second form, the command sets the value of the property propertyName to value for the item designated by the recordID argument. If the value argument is an empty string,
the property's value is removed. If propertyName is a multivalue
property, the value must be formatted as a keyed list.
The command raise an error in case of failure, for instance if the
item does not support the requested property or if the value is
ill-formatted.
The [type] subcommand
This subcommand returns a record's type. The complete syntax is:
contactRef type recordID
The return value is either group or person. If recordID is not a
valid record identifier, the command raises an error.
The [vcard] subcommand
This subcommand manages vCard representations of a person. The complete syntax is:
contactRef vcard personID
contactRef vcard -create data
In the first form, the personID argument must be the unique ID of
a person and the command returns a vCard representation for this person.
Note that the returned data can be binary (if the record contains an image).
In the second form, if the -create option is specified, the command attempts to create, in the
Address Book database, a new entry corresponding to the given data.
If data is not a valid vCard representation, the command raises an
error. In case of success, it returns the unique ID of the new entry.
Contact Properties
The various fields contained in Address Book records are known as
properties.
Property Names
The following table gives the name of the built-in properties and their
corresponding type. One can also declare custom properties
and types (see the [contactRef property] command).
| Name | Description | Type |
| Address | Street addresses | MultiDictionary |
| AlternateBirthdayComponents | Alternate non-Gregorian birth date | DateComponents |
| BirthdayComponents | Birth date | DateComponents |
| Birthday | Birth date | Date |
| calendarURIs | Calendar URIs | MultiString |
| Creation | Creation date (when first saved) | Date |
| ABDepartment | Department name | String |
| Email | Email(s) | MultiString |
| FirstPhonetic | First name phonetic | String |
| First | First name | String |
| GroupName | Name of the group | String |
| HomePage | Home Web page | String |
| InstantMessage | Instant messaging | MultiDictionary |
| JobTitle | Job title | String |
| LastPhonetic | Last name phonetic | String |
| Last | Last name | String |
| MaidenName | Maiden name | String |
| MiddlePhonetic | Middle name phonetic | String |
| Middle | Middle name | String |
| Modification | Last saved date | Date |
| Nickname | Nickname | String |
| Note | Note | String |
| OrganizationPhonetic | Company name phonetic | String |
| Organization | Company name | String |
| Phone | Generic phone number | MultiString |
| SocialProfile | Social profiles | MultiDictionary |
| Suffix | "Sr.", "Jr.", "III" | String |
| Title | "Sir", "Duke", "General", "Lord" | String |
| UID | The UID property | String |
| URLs | URLs | MultiString |
The following table gives the supported key names for properties stored in
dictionaries:
| Names | Dictionary keys |
| Address | City, CountryCode, Country, State, Street, ZIP |
| InstantMessage | InstantMessageUsername, InstantMessageService |
| SocialProfile | serviceName, url, userIdentifier, username |
The InstantMessageService key currently supports the following
values: Facebook, Flickr, LinkedIn, MySpace, SinaWeibo, TencentWeibo,
Twitter, Yelp.
The serviceName key currently supports the following
values: AIMInstant, FacebookInstant, GaduGaduInstant, GoogleTalkInstant,
ICQInstant, JabberInstant, MSNInstant, QQInstant, SkypeInstant, YahooInstant.
Property Values and Types
Some properties have a single value (like your last name, birthday, etc.)
while others have multiple values. For instance, the Phone or Email properties are multivalue properties since a person can have
several phone numbers and several different emails.
Each value has a type and each type has its own internal
representation. For instance, the FirstName and LastName
properties are strings, the Birthday property is a date.
The following table gives the name and data representation of the
available types:
| Type | Representation |
| String | string |
| Integer | number |
| Real | number |
| Date | date |
| Array | array |
| Dictionary | dictionary |
| Data | data |
| DateComponents | date components |
| MultiString | list of strings |
| MultiInteger | list of numbers |
| MultiReal | list of numbers |
| MultiDate | list of dates |
| MultiArray | list of arrays |
| MultiDictionary | list of dictionaries |
| MultiData | list of data |
| MultiDateComponents | list of date components |
Multivalue properties are represented as lists. For instance, the
Address property is a list since one can have several addresses
(for home, work, summer vacations, etc.) : each address value is
represented as a dictionary (with keys corresponding to the street, city,
ZIP code etc.). The exact format for these multivalue lists is described in
the next section (Property Labels and Identifiers).
Dates are returned as numeric values suitable for use with the [clock format] Tcl command. The value is the number of seconds relative to
"Thu Jan 01 00:00:00 GMT 1970" (values are negative for dates prior to
this date).
Property Labels and Identifiers
Each item in a multivalue property has a numeric index (its position within
the list), a unique identifier, a string label (such as Home or Work), and a value. The labels are not necessarily unique, but the
identifiers are. For instance, you can have multiple phone numbers labeled
as Mobile, but each of these phone numbers has its own identifier.
The multivalue properties are conveniently represented in Tcl by
keyed lists. A keyed list is a list in which each element contains a key
and value pair. These pairs are stored as two-element lists, where
the key is the first element of the list, and the value is the second. For
instance: a value of the Phone property could be represented as
{Home 12345678} {Work 87654321} {iPhone 01234567}
The TclX extension defines useful
procs (keylget, keylset, etc.) to manipulate keyed lists.
Remarks:
- only multivalue properties have labels and identifiers, single
value properties do not.
- the identifiers of multivalue fields are not to be
confused with the unique ID of person or group records.
Primary and Distribution Identifiers
The notions of primary and distribution identifiers make sense for multivalue
properties only.
Primary identifier
The notion of primary identifier must be understood in the context of
a multivalue.
As seen in the previous section, each value within a multivalue
property has an identifier. Each multivalue list has a primary value, which is the item the user most strongly associates with that person.
For example, friends may have both home and work addresses, but the home
address is their primary address. And coworkers may have both home and work
phone numbers, but the work number is their primary number.
To manipulate primary identifiers see the
[contactRef identifiers primary] command.
Distribution identifier
The notion of distribution identifier must be understood in the
context of a group.
Groups not only help to organize person records, but also allow you
to create email distribution lists. Distribution identifiers let you use
groups as distribution lists, by indicating which value in a multivalue
property should be used when addressing the group or sending a message to
this group.
The default distribution identifier is the property's primary
identifier. Generally, users will want to use the value marked as primary
as the distribution identifier, but in some cases they will want to
designate another one.
To manipulate distribution identifiers see the
[contactRef identifiers distribution] command.
Note that users can also edit this from the OSX Address Book
application, by selecting Edit Distribution List from the Edit menu of this application.
Examples
Last updated 2020-06-13 19:28:56