[Tcladdressbook-commits] Help TclAddressBookHelp.html,1.18,1.19
Status: Alpha
Brought to you by:
bdesgraupes
|
From: Bernard D. <bde...@us...> - 2004-07-30 11:17:15
|
Update of /cvsroot/tcladdressbook/Help In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18842/Help Modified Files: TclAddressBookHelp.html Log Message: Doc [identifier] subcommands (count, get, primary, set) Index: TclAddressBookHelp.html =================================================================== RCS file: /cvsroot/tcladdressbook/Help/TclAddressBookHelp.html,v retrieving revision 1.18 retrieving revision 1.19 diff -u -d -r1.18 -r1.19 --- TclAddressBookHelp.html 29 Jul 2004 20:15:15 -0000 1.18 +++ TclAddressBookHelp.html 30 Jul 2004 11:17:03 -0000 1.19 @@ -8,7 +8,7 @@ <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.1b2. +documents version 1.1b3. </I></P></BLOCKQUOTE><HR> <UL> <LI><A HREF="#M1">NAME</A> @@ -23,31 +23,35 @@ <UL><UL><LI><A HREF="#M10">addressbook export <I>personID</I></A></UL></UL> <UL><UL><LI><A HREF="#M11">addressbook getme ?<I>-id</I>?</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 identifier <I>personID</I> <I>groupID</I> <I>propName</I> ?<I>label</I>?</A></UL></UL> -<UL><UL><LI><A HREF="#M14">addressbook image <I>personID</I> ?<I>imageData</I>?</A></UL></UL> -<UL><UL><LI><A HREF="#M15">addressbook import <I>vCardData</I></A></UL></UL> -<UL><UL><LI><A HREF="#M16">addressbook parents ?-ids? <I>recordID</I></A></UL></UL> -<UL><UL><LI><A HREF="#M17">addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</A></UL></UL> -<UL><UL><LI><A HREF="#M18">addressbook property names (-groups | -persons)</A></UL></UL> -<UL><UL><LI><A HREF="#M19">addressbook property type (-groups | -persons) <I>propName</I></A></UL></UL> -<UL><UL><LI><A HREF="#M20">addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></A></UL></UL> -<UL><UL><LI><A HREF="#M21">addressbook property remove (-groups | -persons | recordID) <I>propName</I></A></UL></UL> -<UL><UL><LI><A HREF="#M22">addressbook record <I>recordID</I></A></UL></UL> -<UL><UL><LI><A HREF="#M23">addressbook remove <I>recordID</I> <I>groupID</I></A></UL></UL> -<UL><UL><LI><A HREF="#M24">addressbook save</A></UL></UL> -<UL><UL><LI><A HREF="#M25">addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></A></UL></UL> -<UL><UL><LI><A HREF="#M26">addressbook set <I>recordID propertyName</I> ?<I>value</I>?</A></UL></UL> -<UL><UL><LI><A HREF="#M27">addressbook setme <I>recordID</I></A></UL></UL> -<UL><UL><LI><A HREF="#M28">addressbook type <I>recordID</I></A></UL></UL> -<LI><A HREF="#M29">INSTALLATION</A> -<LI><A HREF="#M30">VERSION HISTORY</A> -<LI><A HREF="#M31">REQUIREMENTS AND PORTABILITY</A> -<LI><A HREF="#M32">KNOW ISSUES</A> -<LI><A HREF="#M33">SOURCE CODE</A> -<LI><A HREF="#M34">CONTRIBUTIONS</A> -<LI><A HREF="#M35">LICENSE AND DISCLAIMER</A> -<LI><A HREF="#M36">SEE ALSO</A> -<LI><A HREF="#M37">KEYWORDS</A> +<UL><UL><LI><A HREF="#M13">addressbook identifier count <I>personID</I> <I>propName</I></A></UL></UL> +<UL><UL><LI><A HREF="#M14">addressbook identifier get <I>personID</I> <I>propName</I> <I>index</I></A></UL></UL> +<UL><UL><LI><A HREF="#M15">addressbook identifier primary <I>personID</I> <I>propName</I></A></UL></UL> +<UL><UL><LI><A HREF="#M16">addressbook identifier set <I>groupID</I> <I>personID</I> <I>propName</I> ?<I>ident</I>?</A></UL></UL> +<UL><UL><LI><A HREF="#M17">addressbook image <I>personID</I> ?<I>imageData</I>?</A></UL></UL> +<UL><UL><LI><A HREF="#M18">addressbook import <I>vCardData</I></A></UL></UL> +<UL><UL><LI><A HREF="#M19">addressbook parents ?-ids? <I>recordID</I></A></UL></UL> +<UL><UL><LI><A HREF="#M20">addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</A></UL></UL> +<UL><UL><LI><A HREF="#M21">addressbook property names (-groups | -persons)</A></UL></UL> +<UL><UL><LI><A HREF="#M22">addressbook property type (-groups | -persons) <I>propName</I></A></UL></UL> +<UL><UL><LI><A HREF="#M23">addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></A></UL></UL> +<UL><UL><LI><A HREF="#M24">addressbook property remove (-groups | -persons | recordID) <I>propName</I></A></UL></UL> +<UL><UL><LI><A HREF="#M25">addressbook record <I>recordID</I></A></UL></UL> +<UL><UL><LI><A HREF="#M26">addressbook remove <I>recordID</I> <I>groupID</I></A></UL></UL> +<UL><UL><LI><A HREF="#M27">addressbook save</A></UL></UL> +<UL><UL><LI><A HREF="#M28">addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></A></UL></UL> +<UL><UL><LI><A HREF="#M29">addressbook set <I>recordID propertyName</I> ?<I>value</I>?</A></UL></UL> +<UL><UL><LI><A HREF="#M30">addressbook setme <I>recordID</I></A></UL></UL> +<UL><UL><LI><A HREF="#M31">addressbook type <I>recordID</I></A></UL></UL> +<LI><A HREF="#M32">DISTRIBUTION LIST AND IDENTIFIERS</A> +<LI><A HREF="#M33">INSTALLATION</A> +<LI><A HREF="#M34">VERSION HISTORY</A> +<LI><A HREF="#M35">REQUIREMENTS AND PORTABILITY</A> +<LI><A HREF="#M36">KNOW ISSUES</A> +<LI><A HREF="#M37">SOURCE CODE</A> +<LI><A HREF="#M38">CONTRIBUTIONS</A> +<LI><A HREF="#M39">LICENSE AND DISCLAIMER</A> +<LI><A HREF="#M40">SEE ALSO</A> +<LI><A HREF="#M41">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> @@ -93,51 +97,67 @@ 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="M13"></A>addressbook identifier <I>personID</I> <I>groupID</I> <I>propName</I> ?<I>label</I>?</H4> -This command lets you get or set the distribution identifier for a -multi-value list property of a person in a group. -<P> Used without a <I>label</I> argument, this will return the -distribution identifier for the person <I>personID</I> belonging to the +with ID <I>groupID</I> will be returned.<P><H4><A NAME="M13"></A>addressbook identifier count <I>personID</I> <I>propName</I></H4> +This command returns the number of items in a multi-value list property +(such as Address, Phone, Email). <P><H4><A NAME="M14"></A>addressbook identifier get <I>personID</I> <I>propName</I> <I>index</I></H4> +This command gets the unique identifier of an item in a multi-value list +property (such as Address, Phone, Email). 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 <A HREF="#dist">Distribution list and identifiers</A> +below for explanations about identifiers.<P><H4><A NAME="M15"></A>addressbook identifier primary <I>personID</I> <I>propName</I></H4> +This command returns 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>Address, Phone, Email</I>).<P><H4><A NAME="M16"></A>addressbook identifier set <I>groupID</I> <I>personID</I> <I>propName</I> ?<I>ident</I>?</H4> +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 +<A HREF="#dist"> Distribution list and identifiers</A> below for +explanations about identifiers. +<P> 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 -<P> If the <I>label</I> argument is specified, this will assign a -specific distribution identifier 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 label -used by the multi-value list (such as <I>home</I> for an <I>address</I> -property). If <I>label</I> is an empty string, this command resets the -distribution identifier to its default, i-e the multi-value list¹s primary -identifier.<P><H4><A NAME="M14"></A>addressbook image <I>personID</I> ?<I>imageData</I>?</H4> +otherwise the property's primary identifier. Property <I>propName</I> must +be a multi-value list property (such as <I>Address, Phone, Email</I>). +<P> 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.<P><H4><A NAME="M17"></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="M15"></A>addressbook import <I>vCardData</I></H4> +record with unique ID <I>personID</I>.<P><H4><A NAME="M18"></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="M16"></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="M19"></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="M17"></A>addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</H4> +returned. <P><H4><A NAME="M20"></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="M18"></A>addressbook property names (-groups | -persons)</H4> +will be returned.<P><H4><A NAME="M21"></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="M19"></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="M22"></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="M20"></A>addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></H4> +or <I>Unknown</I>. <P><H4><A NAME="M23"></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 @@ -145,7 +165,7 @@ 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="M21"></A>addressbook property remove (-groups | -persons | recordID) <I>propName</I></H4> +MultiDictionary, MultiInteger, MultiReal, MultiString.</I><P><H4><A NAME="M24"></A>addressbook property remove (-groups | -persons | recordID) <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. If the third argument is either <B>-groups</B> or @@ -156,7 +176,7 @@ property is removed for this record only and the command returns an empty string. <P> One can get the list of all the existing -properties with the <B>addressbook property names</B> command.<P><H4><A NAME="M22"></A>addressbook record <I>recordID</I></H4> +properties with the <B>addressbook property names</B> command.<P><H4><A NAME="M25"></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. @@ -186,16 +206,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="M23"></A>addressbook remove <I>recordID</I> <I>groupID</I></H4> +extension.<P><H4><A NAME="M26"></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="M24"></A>addressbook save</H4> +<I>groupID</I>.<P><H4><A NAME="M27"></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="M25"></A>addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></H4> +<B>addressbook changed</B> command.<P><H4><A NAME="M28"></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> @@ -251,17 +271,31 @@ 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="M26"></A>addressbook set <I>recordID propertyName</I> ?<I>value</I>?</H4> +the <B>addressbook property type</B> command.<P><H4><A NAME="M29"></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="M27"></A>addressbook setme <I>recordID</I></H4> -This command sets the record that represents the logged-in user. <P><H4><A NAME="M28"></A>addressbook type <I>recordID</I></H4> +various kinds of properties.<P><H4><A NAME="M30"></A>addressbook setme <I>recordID</I></H4> +This command sets the record that represents the logged-in user. <P><H4><A NAME="M31"></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="M29"></A>INSTALLATION</H2> +unique ID <I>recordID</I>.<P><A NAME="dist"></A> +<H2><A NAME="M32"></A>DISTRIBUTION LIST AND IDENTIFIERS</H2> +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>Phone, Email, Address</I> etc. For instance, a group could +be used as a mailing list. The <I>Phone, Email, Address</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.<P><H2><A NAME="M33"></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 @@ -271,20 +305,22 @@ <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="M30"></A>VERSION HISTORY</H2> +application. <P><H2><A NAME="M34"></A>VERSION HISTORY</H2> <UL> <LI> 1.0b1 -- 2004/01/25 -- First public release. <LI> 1.1b1 -- 2004/07/28 -- New commands [add] and [remove]. Modified -[delete] command. New command [identifier]. Modified [property remove] +[delete] command. Modified [property remove] command. <LI> 1.1b2 -- 2004/07/29 -- New command [setme]. -</UL><P><H2><A NAME="M31"></A>REQUIREMENTS AND PORTABILITY</H2> + <LI> 1.1b3 -- 2004/07/30 -- New command [identifier] to handle +distribution lists. +</UL><P><H2><A NAME="M35"></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="M32"></A>KNOW ISSUES</H2> +in version 10.2 of the System (aka Jaguar).<P><H2><A NAME="M36"></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="M33"></A>SOURCE CODE</H2> +<A HREF="mailto:bde...@us...">bde...@us...</A><P><H2><A NAME="M37"></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 @@ -293,17 +329,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="M34"></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="M38"></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="M35"></A>LICENSE AND DISCLAIMER</H2> +(for instance, the same licensing terms as the Tcl language itself).<P><H2><A NAME="M39"></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="M36"></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="M40"></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="M37"></A>KEYWORDS</H2> +commands to open directly the database file.<P><H2><A NAME="M41"></A>KEYWORDS</H2> Address book, data base.<P><HR> -<P> Last updated 2004-07-29 22:00:15<P> +<P> Last updated 2004-07-30 13:05:27<P> </BODY> </HTML> \ No newline at end of file |