[Tcladdressbook-commits] Help TclAddressBookHelp.html,1.15,1.16
Status: Alpha
Brought to you by:
bdesgraupes
|
From: Bernard D. <bde...@us...> - 2004-07-28 23:11:51
|
Update of /cvsroot/tcladdressbook/Help In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19445/Help Modified Files: TclAddressBookHelp.html Log Message: New "add" and "remove" subcommands Index: TclAddressBookHelp.html =================================================================== RCS file: /cvsroot/tcladdressbook/Help/TclAddressBookHelp.html,v retrieving revision 1.15 retrieving revision 1.16 diff -u -d -r1.15 -r1.16 --- TclAddressBookHelp.html 26 Jan 2004 23:09:14 -0000 1.15 +++ TclAddressBookHelp.html 28 Jul 2004 23:11:40 -0000 1.16 @@ -1,6 +1,6 @@ <HTML> <HEAD> -<TITLE>Tcladdressbook Help</TITLE> +<TITLE>TcladdressbookHelp</TITLE> <META NAME=GENERATOR CONTENT="Aida Mode"> </HEAD> <BODY> @@ -8,111 +8,118 @@ <P><IMG SRC="Images/TclAB_logo.gif " ALT="TclAB Logo" ALIGN=bottom></P> <P> <A HREF="TclAB.html"> Home Page</A> | <A HREF="http://sourceforge.net/projects/tcladdressbook"> Project Page at SourceForge</A><P><HR><BLOCKQUOTE><P><I> This is a manual page for the Tcladdressbook extension for Tcl. It -documents version 1.0b1. +documents version 1.1b1. </I></P></BLOCKQUOTE><HR> <UL> <LI><A HREF="#M1">NAME</A> <LI><A HREF="#M2">SYNOPSIS</A> <LI><A HREF="#M3">INTRODUCTION</A> <LI><A HREF="#M4">SUBCOMMANDS</A> -<UL><UL><LI><A HREF="#M5">addressbook changed</A></UL></UL> -<UL><UL><LI><A HREF="#M6">addressbook count (-groups | -persons) ?-ingroup <I>groupID</I>?</A></UL></UL> -<UL><UL><LI><A HREF="#M7">addressbook create (group | person) <I>name</I> ?-ingroup <I>groupID</I>?</A></UL></UL> -<UL><UL><LI><A HREF="#M8">addressbook delete <I>recordID</I> ?-fromgroup <I>groupID</I>?</A></UL></UL> -<UL><UL><LI><A HREF="#M9">addressbook export <I>personID</I></A></UL></UL> -<UL><UL><LI><A HREF="#M10">addressbook getme</A></UL></UL> -<UL><UL><LI><A HREF="#M11">addressbook groups ?-ids? ?-ingroup <I>groupID</I>?</A></UL></UL> -<UL><UL><LI><A HREF="#M12">addressbook image <I>personID</I> ?<I>imageData</I>?</A></UL></UL> -<UL><UL><LI><A HREF="#M13">addressbook import <I>vCardData</I></A></UL></UL> -<UL><UL><LI><A HREF="#M14">addressbook parents ?-ids? <I>recordID</I></A></UL></UL> -<UL><UL><LI><A HREF="#M15">addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</A></UL></UL> -<UL><UL><LI><A HREF="#M16">addressbook property names (-groups | -persons)</A></UL></UL> -<UL><UL><LI><A HREF="#M17">addressbook property type (-groups | -persons) <I>propName</I></A></UL></UL> -<UL><UL><LI><A HREF="#M18">addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></A></UL></UL> -<UL><UL><LI><A HREF="#M19">addressbook property remove (-groups | -persons) <I>propName</I></A></UL></UL> -<UL><UL><LI><A HREF="#M20">addressbook record <I>recordID</I></A></UL></UL> -<UL><UL><LI><A HREF="#M21">addressbook save</A></UL></UL> -<UL><UL><LI><A HREF="#M22">addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></A></UL></UL> -<UL><UL><LI><A HREF="#M23">addressbook set <I>recordID propertyName</I> ?<I>value</I>?</A></UL></UL> -<UL><UL><LI><A HREF="#M24">addressbook type <I>recordID</I></A></UL></UL> -<LI><A HREF="#M25">INSTALLATION</A> -<LI><A HREF="#M26">VERSION HISTORY</A> -<LI><A HREF="#M27">REQUIREMENTS AND PORTABILITY</A> -<LI><A HREF="#M28">KNOW ISSUES</A> -<LI><A HREF="#M29">SOURCE CODE</A> -<LI><A HREF="#M30">CONTRIBUTIONS</A> -<LI><A HREF="#M31">LICENSE AND DISCLAIMER</A> -<LI><A HREF="#M32">SEE ALSO</A> -<LI><A HREF="#M33">KEYWORDS</A> +<UL><UL><LI><A HREF="#M5">addressbook add <I>recordID</I> <I>groupID</I></A></UL></UL> +<UL><UL><LI><A HREF="#M6">addressbook changed</A></UL></UL> +<UL><UL><LI><A HREF="#M7">addressbook count (-groups | -persons) ?-ingroup <I>groupID</I>?</A></UL></UL> +<UL><UL><LI><A HREF="#M8">addressbook create (group | person) <I>name</I> ?-ingroup <I>groupID</I>?</A></UL></UL> +<UL><UL><LI><A HREF="#M9">addressbook delete <I>recordID</I></A></UL></UL> +<UL><UL><LI><A HREF="#M10">addressbook export <I>personID</I></A></UL></UL> +<UL><UL><LI><A HREF="#M11">addressbook getme</A></UL></UL> +<UL><UL><LI><A HREF="#M12">addressbook groups ?-ids? ?-ingroup <I>groupID</I>?</A></UL></UL> +<UL><UL><LI><A HREF="#M13">addressbook image <I>personID</I> ?<I>imageData</I>?</A></UL></UL> +<UL><UL><LI><A HREF="#M14">addressbook import <I>vCardData</I></A></UL></UL> +<UL><UL><LI><A HREF="#M15">addressbook parents ?-ids? <I>recordID</I></A></UL></UL> +<UL><UL><LI><A HREF="#M16">addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</A></UL></UL> +<UL><UL><LI><A HREF="#M17">addressbook property names (-groups | -persons)</A></UL></UL> +<UL><UL><LI><A HREF="#M18">addressbook property type (-groups | -persons) <I>propName</I></A></UL></UL> +<UL><UL><LI><A HREF="#M19">addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></A></UL></UL> +<UL><UL><LI><A HREF="#M20">addressbook property remove (-groups | -persons) <I>propName</I></A></UL></UL> +<UL><UL><LI><A HREF="#M21">addressbook record <I>recordID</I></A></UL></UL> +<UL><UL><LI><A HREF="#M22">addressbook remove <I>recordID</I> <I>groupID</I></A></UL></UL> +<UL><UL><LI><A HREF="#M23">addressbook save</A></UL></UL> +<UL><UL><LI><A HREF="#M24">addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></A></UL></UL> +<UL><UL><LI><A HREF="#M25">addressbook set <I>recordID propertyName</I> ?<I>value</I>?</A></UL></UL> +<UL><UL><LI><A HREF="#M26">addressbook type <I>recordID</I></A></UL></UL> +<LI><A HREF="#M27">INSTALLATION</A> +<LI><A HREF="#M28">VERSION HISTORY</A> +<LI><A HREF="#M29">REQUIREMENTS AND PORTABILITY</A> +<LI><A HREF="#M30">KNOW ISSUES</A> +<LI><A HREF="#M31">SOURCE CODE</A> +<LI><A HREF="#M32">CONTRIBUTIONS</A> +<LI><A HREF="#M33">LICENSE AND DISCLAIMER</A> +<LI><A HREF="#M34">SEE ALSO</A> +<LI><A HREF="#M35">KEYWORDS</A> </UL> <P><H2><A NAME="M1"></A>NAME</H2> addressbook - manipulate the Macintosh OSX Address Book database<P><H2><A NAME="M2"></A>SYNOPSIS</H2> <B>package require addressbook</B> <P> <B>addressbook subcommand</B> ?<I>arg arg</I>...?<P><H2><A NAME="M3"></A>INTRODUCTION</H2><P>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.<P><H2><A NAME="M4"></A>SUBCOMMANDS</H2><P><H4><A NAME="M5"></A>addressbook changed</H4> +subcommands are explained in the next sections.<P><H2><A NAME="M4"></A>SUBCOMMANDS</H2><P><H4><A NAME="M5"></A>addressbook add <I>recordID</I> <I>groupID</I></H4> +This command lets you add an already existing item (person or group) +designated by its unique ID <I>recordID</I> to the group with ID +<I>groupID</I>.<P><H4><A NAME="M6"></A>addressbook changed</H4> 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. <P><H4><A NAME="M6"></A>addressbook count (-groups | -persons) ?-ingroup <I>groupID</I>?</H4> +command. <P><H4><A NAME="M7"></A>addressbook count (-groups | -persons) ?-ingroup <I>groupID</I>?</H4> 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.<P><H4><A NAME="M7"></A>addressbook create (group | person) <I>name</I> ?-ingroup <I>groupID</I>?</H4> +to count only the subgroups or members in this group.<P><H4><A NAME="M8"></A>addressbook create (group | person) <I>name</I> ?-ingroup <I>groupID</I>?</H4> 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.<P><H4><A NAME="M8"></A>addressbook delete <I>recordID</I> ?-fromgroup <I>groupID</I>?</H4> +command returns the unique ID of the created record.<P><H4><A NAME="M9"></A>addressbook delete <I>recordID</I></H4> 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.<P><H4><A NAME="M9"></A>addressbook export <I>personID</I></H4> +database. Note that any changes made to the database won't be definitive +until you invoke the <B>addressbook save</B> command. +<P> 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.<P><H4><A NAME="M10"></A>addressbook export <I>personID</I></H4> 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.<P><H4><A NAME="M10"></A>addressbook getme</H4> +contain an image associated to the record.<P><H4><A NAME="M11"></A>addressbook getme</H4> This command returns all the data available in the database concerning the logged-in user ("Me"). 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.<P><H4><A NAME="M11"></A>addressbook groups ?-ids? ?-ingroup <I>groupID</I>?</H4> +<B>keylget</B> and <B>keylset</B> commands defined in the TclX extension.<P><H4><A NAME="M12"></A>addressbook groups ?-ids? ?-ingroup <I>groupID</I>?</H4> 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.<P><H4><A NAME="M12"></A>addressbook image <I>personID</I> ?<I>imageData</I>?</H4> +with ID <I>groupID</I> will be returned.<P><H4><A NAME="M13"></A>addressbook image <I>personID</I> ?<I>imageData</I>?</H4> 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 the -record with unique ID <I>personID</I>.<P><H4><A NAME="M13"></A>addressbook import <I>vCardData</I></H4> +record with unique ID <I>personID</I>.<P><H4><A NAME="M14"></A>addressbook import <I>vCardData</I></H4> 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.<P><H4><A NAME="M14"></A>addressbook parents ?-ids? <I>recordID</I></H4> +VCard. Note that the data can be binary if the VCard contains an image.<P><H4><A NAME="M15"></A>addressbook parents ?-ids? <I>recordID</I></H4> 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. <P><H4><A NAME="M15"></A>addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</H4> +returned. <P><H4><A NAME="M16"></A>addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</H4> 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.<P><H4><A NAME="M16"></A>addressbook property names (-groups | -persons)</H4> +will be returned.<P><H4><A NAME="M17"></A>addressbook property names (-groups | -persons)</H4> 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.<P><H4><A NAME="M17"></A>addressbook property type (-groups | -persons) <I>propName</I></H4> +the <B>addressbook property add</B> and <B>addressbook property remove</B> commands.<P><H4><A NAME="M18"></A>addressbook property type (-groups | -persons) <I>propName</I></H4> 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>. <P><H4><A NAME="M18"></A>addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></H4> +or <I>Unknown</I>. <P><H4><A NAME="M19"></A>addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></H4> 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 @@ -120,11 +127,11 @@ 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><P><H4><A NAME="M19"></A>addressbook property remove (-groups | -persons) <I>propName</I></H4> +MultiDictionary, MultiInteger, MultiReal, MultiString.</I><P><H4><A NAME="M20"></A>addressbook property remove (-groups | -persons) <I>propName</I></H4> 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.<P><H4><A NAME="M20"></A>addressbook record <I>recordID</I></H4> +properties with the <B>addressbook property names</B> command.<P><H4><A NAME="M21"></A>addressbook record <I>recordID</I></H4> 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. @@ -154,13 +161,16 @@ 00:00:00 CET 1970". <P> Note that keyed lists can be easily manipulated using the <B>keylget</B> and <B>keylset</B> commands defined in the TclX -extension.<P><H4><A NAME="M21"></A>addressbook save</H4> +extension.<P><H4><A NAME="M22"></A>addressbook remove <I>recordID</I> <I>groupID</I></H4> +This command lets you remove an already existing item (person or group) +designated by its unique ID <I>recordID</I> from the group with ID +<I>groupID</I>.<P><H4><A NAME="M23"></A>addressbook save</H4> 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.<P><H4><A NAME="M22"></A>addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></H4> +<B>addressbook changed</B> command.<P><H4><A NAME="M24"></A>addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></H4> This command returns all the records corresponding to the criterion described by the last three arguments: <UL> @@ -197,7 +207,7 @@ 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 +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: <PRE> @@ -216,16 +226,16 @@ that no distinction be made between uppercase and lowercase letters. <P> 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.<P><H4><A NAME="M23"></A>addressbook set <I>recordID propertyName</I> ?<I>value</I>?</H4> +the <B>addressbook property type</B> command.<P><H4><A NAME="M25"></A>addressbook set <I>recordID propertyName</I> ?<I>value</I>?</H4> 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.<P><H4><A NAME="M24"></A>addressbook type <I>recordID</I></H4> +various kinds of properties.<P><H4><A NAME="M26"></A>addressbook type <I>recordID</I></H4> This command returns the type (<I>ABPerson</I> or <I>ABGroup</I>) of the record with -unique ID <I>recordID</I>.<P><H2><A NAME="M25"></A>INSTALLATION</H2> +unique ID <I>recordID</I>.<P><H2><A NAME="M27"></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 @@ -235,16 +245,18 @@ <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. <P><H2><A NAME="M26"></A>VERSION HISTORY</H2> +application. <P><H2><A NAME="M28"></A>VERSION HISTORY</H2> <UL> <LI> 1.0b1 -- 2004/01/25 -- First public release. -</UL><P><H2><A NAME="M27"></A>REQUIREMENTS AND PORTABILITY</H2> + <LI> 1.1b1 -- 2004/08/01 -- New commands "add" and "remove". Modified +"delete" command. +</UL><P><H2><A NAME="M29"></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).<P><H2><A NAME="M28"></A>KNOW ISSUES</H2> +in version 10.2 of the System (aka Jaguar).<P><H2><A NAME="M30"></A>KNOW ISSUES</H2> Tcladdressbook was written by Bernard Desgraupes. Please e-mail any bug or problem you encounter: -<A HREF="mailto:bde...@us...">bde...@us...</A><P><H2><A NAME="M29"></A>SOURCE CODE</H2> +<A HREF="mailto:bde...@us...">bde...@us...</A><P><H2><A NAME="M31"></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: <P> <A HREF="http://sourceforge.net/projects/tcladdressbook">http://sourceforge.net/projects/tcladdressbook</A><P><P> Tcladdressbook binary releases are available at @@ -253,17 +265,17 @@ <P> <A HREF="http://webperso.easyconnect.fr/bdesgraupes/tcl.html">http://webperso.easyconnect.fr/bdesgraupes/tcl.html</A><P><P> The code is under CVS control. You can retrieve the latest stage of development using any CVS client. See instructions at: <P> <A HREF="http://sourceforge.net/cvs/?group_id=96169">http://sourceforge.net/cvs/?group_id=96169</A><P><P> You can also browse the cvs repository online at -<P> <A HREF="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook</A> <P><H2><A NAME="M30"></A>CONTRIBUTIONS</H2> +<P> <A HREF="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook</A> <P><H2><A NAME="M32"></A>CONTRIBUTIONS</H2> 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).<P><H2><A NAME="M31"></A>LICENSE AND DISCLAIMER</H2> +(for instance, the same licensing terms as the Tcl language itself).<P><H2><A NAME="M33"></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.<P><P> © Copyright Bernard Desgraupes 2003-2004<P><H2><A NAME="M32"></A>SEE ALSO</H2> +as the Tcl language itself. See license.terms in the Tcl distribution.<P><P> © Copyright Bernard Desgraupes 2003-2004<P><H2><A NAME="M34"></A>SEE ALSO</H2> See the TclX extension for keyed lists: TclX(n). See the Mk4Tcl extension for -commands to open directly the database file.<P><H2><A NAME="M33"></A>KEYWORDS</H2> +commands to open directly the database file.<P><H2><A NAME="M35"></A>KEYWORDS</H2> Address book, data base.<P><HR> -<P> Last updated 2004-01-24 13:24:29<P> +<P> Last updated 2004-07-29 01:08:28<P> </BODY> </HTML> \ No newline at end of file |