[Tcladdressbook-commits] Help tcladdressbook.n,1.2,1.3
Status: Alpha
Brought to you by:
bdesgraupes
Menu
▾
▴
[Tcladdressbook-commits] Help tcladdressbook.n,1.2,1.3
|
From: <bde...@pr...> - 2004-01-26 23:08:57
|
Update of /cvsroot/tcladdressbook/Help In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19427/Help Modified Files: tcladdressbook.n Log Message: Update for 1.0b1 release Index: tcladdressbook.n =================================================================== RCS file: /cvsroot/tcladdressbook/Help/tcladdressbook.n,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- tcladdressbook.n 9 Jan 2004 14:32:51 -0000 1.2 +++ tcladdressbook.n 26 Jan 2004 23:07:51 -0000 1.3 @@ -1,67 +1,83 @@ .de uline \Z'\\$1'\v'.25m'\D'l \w'\\$1'u 0'\v'-.25m' .. -.TH tcladdressbook n "" "2004-01-09" "addressbook extension for Tcl" -.\" :Title: Tcladdressbook Help -.\" :Project: addressbook extension for Tcl -.\" :Author: Bernard Desgraupes <bde...@ea...> -.\" :Homepage: <http://webperso.easyconnect.fr/bdesgraupes/> -.\" :Modified: 2004-01-05 06:42:28 +.TH tcladdressbook n "" "2004-01-24" "addressbook extension for Tcl" +.PP .SH NAME .PP +.PP addressbook - manipulate the Macintosh OSX Address Book database +.PP .SH SYNOPSIS .PP +.PP \fBpackage require addressbook\fP .PP -\fBaddressbook subcommand\fP ?\fI arg arg\fP...? + \fBaddressbook subcommand\fP ?\fI arg arg\fP...? +.PP .SH INTRODUCTION .PP +.PP The argument \fI subcommand\fP indicates what operation to perform. Any unique abbreviation for each subcommand is acceptable. The valid subcommands are explained in the next sections. +.PP .SH SUBCOMMANDS .PP +.PP .SS addressbook changed .PP +.PP This command returns 1 if there has been changes made to the database, 0 otherwise. Changes are made in memory with commands such as \fBaddressbook set\fP, \fBaddressbook create\fP, \fBaddressbook delete\fP. To make these changes permanent, one must call the \fBaddressbook save\fP command. +.PP .SS addressbook count (-groups | -persons) ?-ingroup \fI groupID\fP? .PP +.PP 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. +.PP .SS addressbook create (group | person) \fI name\fP ?-ingroup \fI groupID\fP? .PP +.PP This command lets you create a new group or a new person record. The \fI name\fP 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 \fI -ingroup\fP option one can make the newly created record a subgroup or a member of the particular group with unique ID \fI groupID\fP. If no error occurs, the command returns the unique ID of the created record. +.PP .SS addressbook delete \fI recordID\fP ?-fromgroup \fI groupID\fP? .PP +.PP This command removes the record with unique ID \fI recordID\fP from the database or from a particular subgroup specified by its unique ID with the \fI -fromgroup\fP option. Note that any changes made to the database won't be definitive until you invoke the \fBaddressbook save\fP command. +.PP .SS addressbook export \fI personID\fP .PP +.PP This command lets you export the record with unique ID \fI personID\fP as a VCard. The result should be considered as binary data since it can contain an image associated to the record. +.PP .SS addressbook getme .PP +.PP 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 \fBaddressbook record\fP command for a description of this format. Keyed lists can be easily manipulated with the \fBkeylget\fP and \fBkeylset\fP commands defined in the TclX extension. +.PP .SS addressbook groups ?-ids? ?-ingroup \fI groupID\fP? .PP +.PP 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 @@ -69,29 +85,37 @@ returned list will contain only the unique IDs of the groups. If the \fI -ingroup\fP option is specified, only the subgroups contained in the group with ID \fI groupID\fP will be returned. +.PP .SS addressbook image \fI personID\fP ?\fI imageData\fP? .PP +.PP If no \fI imageData\fP argument is specified, this command returns the custom image associated with the record corresponding to the unique ID \fI personID\fP. The returned bytes are binary data. If no image exists, it raises an error. If an \fI imageData\fP argument is specified, it should contain valid binary data defining an image which will be associated the record with unique ID \fI personID\fP. +.PP .SS addressbook import \fI vCardData\fP .PP +.PP This command imports data in VCard format. The data specified by the \fI vCardData\fP 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. +.PP .SS addressbook parents ?-ids? \fI recordID\fP .PP +.PP This command returns a list of all the groups the record with unique ID \fI recordID\fP 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 \fI -ids\fP option is specified, only IDs are returned. +.PP .SS addressbook persons ?-ids? ?-ingroup \fI groupID\fP? .PP +.PP 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 @@ -99,19 +123,25 @@ will contain only the unique IDs. If the \fI -ingroup\fP option is specified, only the members belonging to the group with ID \fI groupID\fP will be returned. +.PP .SS addressbook property names (-groups | -persons) .PP +.PP 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 \fBaddressbook property add\fP and \fBaddressbook property remove\fP commands. +.PP .SS addressbook property type (-groups | -persons) \fI propName\fP .PP +.PP This command returns the type of the property specified by the \fI propName\fP argument. The returned type is one of the values listed with the \fBaddressbook property add\fP command below or \fI Unknown\fP. +.PP .SS addressbook property add (-groups | -persons) \fI propName\fP \fI propType\fP .PP +.PP 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 \fI propName\fP argument: it must be unique. One can get the list of all the @@ -120,14 +150,18 @@ This argument can have one of the following values: \fI Array, Data, Date, Dictionary, Integer, Real, String, MultiArray, MultiData, MultiDate, MultiDictionary, MultiInteger, MultiReal, MultiString.\fP +.PP .SS addressbook property remove (-groups | -persons) \fI propName\fP .PP +.PP 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 \fI propName\fP argument. One can get the list of all the existing properties with the \fBaddressbook property names\fP command. +.PP .SS addressbook record \fI recordID\fP .PP +.PP This command returns all the data available in the database concerning the record with unique ID \fI recordID\fP. The returned value takes the form of a keyed list. @@ -139,10 +173,12 @@ multivalue, the returned value is a keyed list itself. Each element of the list corresponds to a single property. For instance: .RS +.PP .IP * 4 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. +.PP .IP * 4 the elements of a MultiDictionary value list are lists themselves, representing a Label/Dictionary pair (dictionary in the AddressBook sense, @@ -154,8 +190,10 @@ 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}. +.PP .RE .PP +.PP Dates are returned as values suitable for use with the \fBclock format\fP Tcl command. It is the number of seconds relative to "Thu Jan 01 00:00:00 CET 1970". @@ -163,21 +201,27 @@ Note that keyed lists can be easily manipulated using the \fBkeylget\fP and \fBkeylset\fP commands defined in the TclX extension. +.PP .SS addressbook save .PP +.PP This command lets you save the changes made in the database. Commands such as \fBaddressbook set\fP, \fBaddressbook create\fP or \fBaddressbook delete\fP modify the data in memory: to make the changes definitive in the database, one must call explicitely the \fBaddressbook save\fP command. To check whether there has been changes in the database, use the \fBaddressbook changed\fP command. +.PP .SS addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? \fI property op value\fP .PP +.PP This command returns all the records corresponding to the criterion described by the last three arguments: .RS +.PP .IP * 4 \fI property\fP is the name of the property you are searching on. +.PP .IP * 4 \fI op\fP is an operator specifying the type of comparison. It can be one of the following symbols: @@ -191,7 +235,8 @@ which may have different interpretations depending on whether the value is numeric or is a string. .RS -.IP * 4 +.PP +.IP * 8 For a numeric value, they correspond respectively to: .RS .nf @@ -207,7 +252,8 @@ .RE .sp The ^= operator is not applicable (and will default to Greater Than or Equal). -.IP * 4 +.PP +.IP * 8 For a string value, they correspond respectively to: .RS .nf @@ -223,7 +269,9 @@ .RE .sp The < and <= operators are not applicable and will both default to Equal. +.PP .RE +.PP .IP * 4 the argument \fI value\fP is the value you are searching for. In the case of a simple property, \fI value\fP will be a simple string. In the case of a @@ -244,8 +292,10 @@ One can specify an empty string for the label in order to perform the search over all the possible labels. One can also specify an empty string for the key in order to perform the search over all the possible keys in a dictionary. +.PP .RE .PP +.PP The \fI -groups\fP or \fI -persons\fP options let you specify the kind of records you want to search. If it is not specified, the default is \fI -person\fP. If the \fI -ids\fP option is specified, only IDs of the @@ -256,8 +306,10 @@ To get a list of all possible properties, use the \fBaddressbook property names\fP command. To know the type of a particular property, use the \fBaddressbook property type\fP command. +.PP .SS addressbook set \fI recordID propertyName\fP ?\fI value\fP? .PP +.PP This command lets you get or set the value of a particular property for the record with unique ID \fI recordID\fP. If the \fI value\fP argument is not specified, it returns the current value of the property specified in @@ -265,12 +317,16 @@ property \fI propertyName\fP will be set to this value. See the \fBaddressbook record\fP command for a description of the format used for the various kinds of properties. +.PP .SS addressbook type \fI recordID\fP .PP -This command returns the type (ABPerson or ABGroup) of the record with +.PP +This command returns the type (\fI ABPerson\fP or \fI ABGroup\fP) of the record with unique ID \fI recordID\fP. +.PP .SH INSTALLATION .PP +.PP 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 @@ -281,57 +337,88 @@ editor (version 8.0b11 or greater), you can also install it in the \fI Tclextensions\fP folder which is located at the same level as the application. +.PP .SH VERSION HISTORY .PP +.PP .RS +.PP .IP * 4 -1.0 - - +1.0b1 -- 2004/01/25 -- First public release. +.PP .RE +.PP .SH REQUIREMENTS AND PORTABILITY .PP +.PP 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). +.PP .SH KNOW ISSUES .PP +.PP +Tcladdressbook was written by Bernard Desgraupes. Please e-mail any bug or problem you encounter: <bde...@us...> -.SH LICENSE AND DISCLAIMER -.PP -This software is free software and distributed under the same licensing terms -as the Tcl language itself. See license.terms in the Tcl distribution. .PP - © Copyright Bernard Desgraupes 2003-2004 .SH SOURCE CODE .PP +.PP Tcladdressbook is an Open Source Project. Its source code is public and can be found on the SourceForge site at the following address: -<http://sourceforge.net/projects/tcladdressbook> +.PP + <http://sourceforge.net/projects/tcladdressbook> +.PP .PP Tcladdressbook binary releases are available at -<http://sourceforge.net/project/showfiles.php?group_id=96169> or on my web -page at <http://webperso.easyconnect.fr/bdesgraupes/tcl.html> +.PP + <http://sourceforge.net/project/showfiles.php?group_id=96169> +or on my web page at +.PP + <http://webperso.easyconnect.fr/bdesgraupes/tcl.html> +.PP .PP The code is under CVS control. You can retrieve the latest stage of development using any CVS client. See instructions at: -<http://sourceforge.net/cvs/?group_id=96169> +.PP + <http://sourceforge.net/cvs/?group_id=96169> +.PP .PP You can also browse the cvs repository online at -<http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook> +.PP + <http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook> +.PP .SH CONTRIBUTIONS .PP +.PP 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). +.PP +.SH LICENSE AND DISCLAIMER +.PP +.PP +This software is free software and distributed under the same licensing terms +as the Tcl language itself. See license.terms in the Tcl distribution. +.PP +.PP + © Copyright Bernard Desgraupes 2003-2004 +.PP .SH SEE ALSO .PP -See the TclX extension for keyed lists. See the Mk4Tcl extension for +.PP +See the TclX extension for keyed lists: TclX(n). See the Mk4Tcl extension for commands to open directly the database file. +.PP .SH KEYWORDS .PP +.PP Address book, data base. .PP +.PP \l'70\(ul' .PP +.PP |
