[Tcladdressbook-commits] Help TclAddressBookHelp.html,1.3,1.4
Status: Alpha
Brought to you by:
bdesgraupes
Menu
▾
▴
[Tcladdressbook-commits] Help TclAddressBookHelp.html,1.3,1.4
|
From: <bde...@us...> - 2003-12-08 23:12:33
|
Update of /cvsroot/tcladdressbook/Help In directory sc8-pr-cvs1:/tmp/cvs-serv23749/Help Modified Files: TclAddressBookHelp.html Log Message: Doc for all the subcommands Index: TclAddressBookHelp.html =================================================================== RCS file: /cvsroot/tcladdressbook/Help/TclAddressBookHelp.html,v retrieving revision 1.3 retrieving revision 1.4 diff -u -d -r1.3 -r1.4 --- TclAddressBookHelp.html 6 Dec 2003 06:23:22 -0000 1.3 +++ TclAddressBookHelp.html 8 Dec 2003 23:12:30 -0000 1.4 @@ -11,7 +11,7 @@ <!-- :Author: Bernard Desgraupes <A HREF="mailto:bde...@ea...">bde...@ea...</A> --> <!-- :Homepage: <A HREF="http://webperso.easyconnect.fr/bdesgraupes/">http://webperso.easyconnect.fr/bdesgraupes/</A> --> <!-- :Created: 2003-11-26 14:30:03 --> -<!-- :Modified: 2003-12-04 14:12:26 --> +<!-- :Modified: 2003-12-08 08:21:01 --> <!-- :Keywords: Address book, data base --> @@ -23,19 +23,20 @@ <LI><A HREF="#M2">SYNOPSIS</A> <LI><A HREF="#M3">INTRODUCTION</A> <LI><A HREF="#M4">SUBCOMMANDS</A> -<LI><A HREF="#M5">PORTABILITY ISSUES</A> +<LI><A HREF="#M5">INSTALLATION</A> <LI><A HREF="#M6">VERSION HISTORY</A> -<LI><A HREF="#M7">KNOW ISSUES</A> -<LI><A HREF="#M8">LICENSE AND DISCLAIMER</A> -<LI><A HREF="#M9">SOURCE CODE</A> -<LI><A HREF="#M10">SEE ALSO</A> -<LI><A HREF="#M11">KEYWORDS</A> +<LI><A HREF="#M7">REQUIREMENTS AND PORTABILITY</A> +<LI><A HREF="#M8">KNOW ISSUES</A> +<LI><A HREF="#M9">LICENSE AND DISCLAIMER</A> +<LI><A HREF="#M10">SOURCE CODE</A> +<LI><A HREF="#M11">SEE ALSO</A> +<LI><A HREF="#M12">KEYWORDS</A> </UL> <H2><A NAME="M1"></A> NAME</H2> -addressbook - Manipulate the Macintosh OSX Address Book +addressbook - manipulate the Macintosh OSX Address Book database <H2><A NAME="M2"></A> SYNOPSIS</H2> <PRE> @@ -44,63 +45,202 @@ </PRE> <H2><A NAME="M3"></A> INTRODUCTION</H2> -<PRE> - package require addressbook -</PRE> -The argument <I>subcommand</I> indicates what operation to perform. Any unique abbreviation -for each subcommand is acceptable. The valid subcommands are explained in the next -sections. +The argument <I>subcommand</I> indicates what operation to perform. Any +unique abbreviation for each subcommand is acceptable. The valid +subcommands are explained in the next sections. + <H2><A NAME="M4"></A> SUBCOMMANDS</H2> -<H5>addressbook add (group | person) <I>name</I> ?-ingroup <I>groupID</I>?</H5> +<H5>addressbook changed</H5> +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 value</B>, +<B>addressbook create</B>, <B>addressbook remove</B>. To make these changes permanent, +one must call the <B>addressbook save</B> command. -<H5>addressbook add property (-groups|-persons) <I>propName</I> <I>propType</I></H5> +<H5>addressbook count</H5> +<!-- ((s4 addressbook count (-groups | -persons) --> +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 of this group. --> -<H5>addressbook changed</H5> -<H5>addressbook count (-groups | -persons)</H5> +<H5>addressbook create (group | person) <I>name</I> ?-ingroup <I>groupID</I>?</H5> +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. -<H5>addressbook export <I>recordID</I></H5> +<H5>addressbook export <I>personID</I></H5> +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. <H5>addressbook getme <I>arrayvar</I></H5> +This command retrieves all the data available in the database concerning the logged-in user +("Me") and stores it in the array variable specified by the <I>arrayvar</I> +argument. See the <B>addressbook record</B> +command for a description of the format of the various kinds of +properties. <H5>addressbook groups ?-ids? ?-ingroup <I>groupID</I>?</H5> +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. -<H5>addressbook image <I>recordID</I> ?<I>imageData</I>?</H5> +<H5>addressbook image <I>personID</I> ?<I>imageData</I>?</H5> +This command returns the custom image associated with the record +corresponding to the unique ID <I>personID</I>. If no +image exists, it raises an error. The returned bytes are binary data. <H5>addressbook import <I>vCardData</I></H5> +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 record is created in the database corresponding to the information +contained in the VCard. Note that the data can be binary if the VCard contains an +image. -<H5>addressbook parents <I>recordID</I> ?-ids?</H5> +<H5>addressbook parents ?-ids? <I>recordID</I></H5> +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. <H5>addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</H5> +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. -<H5>addressbook properties (-groups | -persons)</H5> +<H5>addressbook property names (-groups | -persons)</H5> +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. + +<H5>addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></H5> +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> + +<H5>addressbook property remove (-groups | -persons) <I>propName</I></H5> +This command lets you remove a property from the database, either for +person or for group records. The name of the property is specified in the +<I>propName</I> argument. One can get the list of all +the existing properties with the <B>addressbook property names</B> command. <H5>addressbook record <I>recordID arrayvar</I></H5> +This command retrieves all the data available in the database concerning +the record with unique ID <I>recordID</I> and stores it in the array +variable specified by the <I>arrayvar</I> argument. The keys of the array +(as returned by the <B>array names</B> Tcl command) are the names of the +properties: the values are the current values of the corresponding +property. Only existing properties for the specified record are returned +by this command: you should unset the <I>arrayvar</I> variable before +invoking <B>addressbook record</B> in case you use this command repeatedly +in order to be sure it does not keep stale information. +<P> The format used to return a particular value depends on the type of +the property (string, integer, date, multivalue etc.). Some properties have +a multiple type: MultiString for fields like Email, Phone etc., MultiDate +for fields like ABDate, MultiDictionary for the Address field. In case of a +multivalue, the returned value is a Tcl list. Each element of the list +corresponds to a single property. For instance: +<UL> + <LI> the elements of a MultiString or MultiDate value list are two-elements +sublists: the first element is the label of the corresponding +property (like Home, Work etc.) and the second is the value itself. + <LI> the elements of a MultiDictionary 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 +Home, Work 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}. -<H5>addressbook remove record <I>recordID</I> ?-fromgroup <I>groupID</I>?</H5> +</UL> +<P> 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 +CET 1970". -<H5>addressbook remove property (-groups|-persons) <I>propName</I></H5> +<H5>addressbook remove <I>recordID</I> ?-fromgroup <I>groupID</I>?</H5> +This command removes the record with unique ID <I>recordID</I> from the +database or from a particular subgroup specified by its unique ID with the +<I>-fromgroup</I> option. Note that any changes made to the database +won't be definitive until you invoke the <B>addressbook save</B> command. <H5>addressbook save</H5> +This command lets you save the changes made in the database. Commands such +as <B>addressbook value</B>, <B>addressbook create</B> or <B>addressbook +remove</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. -<H5>addressbook search <I>property value</I> ?<I>property value</I> ...?</H5> +<H5>addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></H5> +This command returns all the records corresponding to the criterion +described by the last three arguments: +<UL> + <LI> <I>property</I> is the name of the property whose value will be +compared to the <I>value</I> argument + <LI> <I>op</I> is an operator specifying the type of comparison. It can be +one of the following symbols: +<PRE> + ==, !=, <, <=, >, >= +</PRE> + <LI> <I>value</I> is the value property you are searching -<H5>addressbook type <I>recordID</I></H5> +</UL> +<P> The <I>-groups</I> or <I>-persons</I> arguments let you specify the kind of records +you want to search. If it is not specified, the default is <I>-person</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. -<H5>addressbook value <I>recordID property</I> ?<I>value</I>?</H5> +<H5>addressbook type <I>recordID</I></H5> +This command returns the type (ABPerson or ABGroup) of the record with +unique ID <I>recordID</I>. +<H5>addressbook value <I>recordID propertyName</I> ?<I>value</I>?</H5> +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. -<H2><A NAME="M5"></A> PORTABILITY ISSUES</H2> -The [addressbook] command is only available on Macintosh. It is made -available as an extension which should be loaded by Tcl scripts with the -following instruction: -<PRE> - package require addressbook -</PRE> +<H2><A NAME="M5"></A> INSTALLATION</H2> +The extension is made of two files: the dynamic library (called +addressbook1.0.dylib in version 1.0) and a file pkgIndex.tcl necessary for +Tcl to be able to locate the extension upon request. Both files are +contained in a folder called, in version 1.0, TclAddressBook1.0. This folder +should be installed on your system in /Library/Tcl or in ~/Library/Tcl or, +more generally, in any folder 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> folder which is located at the +same level as the application. <H2><A NAME="M6"></A> VERSION HISTORY</H2> @@ -109,12 +249,19 @@ </UL> -<H2><A NAME="M7"></A> KNOW ISSUES</H2> -The [addressbook] command has been created on OSX as a Tcl extension by Bernard -Desgraupes. Please e-mail any bug or problem you encounter: -<A HREF="mailto:bde...@ea...">bde...@ea...</A> -<H2><A NAME="M8"></A> LICENSE AND DISCLAIMER</H2> +<H2><A NAME="M7"></A> REQUIREMENTS AND PORTABILITY</H2> +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). + + +<H2><A NAME="M8"></A> KNOW ISSUES</H2> +Please e-mail any bug or problem you encounter: +<A HREF="mailto:bde...@us...">bde...@us...</A> + + +<H2><A NAME="M9"></A> LICENSE AND DISCLAIMER</H2> This software is free software and distributed under the same licensing terms as the Tcl language itself. See license.terms in the Tcl distribution. @@ -122,7 +269,8 @@ © Copyright Bernard Desgraupes 2003 </PRE> -<H2><A NAME="M9"></A> SOURCE CODE</H2> + +<H2><A NAME="M10"></A> SOURCE CODE</H2> Tcladdressbook is an Open Source Project. Its source code is public and can be found on the SourceForge site at the following address: <A HREF="http://sourceforge.net/projects/tcladdressbook">http://sourceforge.net/projects/tcladdressbook</A> @@ -135,14 +283,14 @@ development using any CVS client. See instructions at: <A HREF="http://sourceforge.net/cvs/?group_id=96169">http://sourceforge.net/cvs/?group_id=96169</A> -<P> You can browse the cvs repository online at +<P> You can also browse the cvs repository online at <A HREF="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook</A> -<H2><A NAME="M10"></A> SEE ALSO</H2> - +<H2><A NAME="M11"></A> SEE ALSO</H2> +The Mk4Tcl extension. -<H2><A NAME="M11"></A> KEYWORDS</H2> +<H2><A NAME="M12"></A> KEYWORDS</H2> Address book, data base |
