[Tcladdressbook-commits] Help TclAddressBookHelp,1.4,1.5
Status: Alpha
Brought to you by:
bdesgraupes
Menu
▾
▴
[Tcladdressbook-commits] Help TclAddressBookHelp,1.4,1.5
|
From: <bde...@us...> - 2003-12-11 07:16:52
|
Update of /cvsroot/tcladdressbook/Help In directory sc8-pr-cvs1:/tmp/cvs-serv1534/Help Modified Files: TclAddressBookHelp Log Message: Sync with aida file 1.2 Index: TclAddressBookHelp =================================================================== RCS file: /cvsroot/tcladdressbook/Help/TclAddressBookHelp,v retrieving revision 1.4 retrieving revision 1.5 diff -u -d -r1.4 -r1.5 --- TclAddressBookHelp 8 Dec 2003 23:12:24 -0000 1.4 +++ TclAddressBookHelp 11 Dec 2003 07:16:48 -0000 1.5 @@ -1,12 +1,6 @@ Title: Tcladdressbook Help Project: addressbook extension for Tcl -Version: $Revision$ -CVSDate: $Date$ -Author: Bernard Desgraupes <bde...@ea...> -Homepage: <http://webperso.easyconnect.fr/bdesgraupes/> -Created: 2003-11-26 14:30:03 Modified: 2003-12-08 08:21:01 -Keywords: Address book, data base Abstract @@ -18,6 +12,25 @@ 2. SYNOPSIS 3. INTRODUCTION 4. SUBCOMMANDS + addressbook changed + addressbook count (-groups | -persons) ?-ingroup groupID? + addressbook create (group | person) name ?-ingroup groupID? + addressbook export personID + addressbook getme arrayvar + addressbook groups ?-ids? ?-ingroup groupID? + addressbook image personID ?imageData? + addressbook import vCardData + addressbook parents ?-ids? recordID + addressbook persons ?-ids? ?-ingroup groupID? + addressbook property names (-groups | -persons) + addressbook property add (-groups | -persons) propName propType + addressbook property remove (-groups | -persons) propName + addressbook record recordID arrayvar + addressbook remove recordID ?-fromgroup groupID? + addressbook save + addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? property op value + addressbook type recordID + addressbook set recordID propertyName ?value? 5. INSTALLATION 6. VERSION HISTORY 7. REQUIREMENTS AND PORTABILITY @@ -42,206 +55,237 @@ 3. INTRODUCTION -The argument subcommand indicates what operation to perform. Any -unique abbreviation for each subcommand is acceptable. The valid +The argument subcommand indicates what operation to perform. Any +unique abbreviation for each subcommand is acceptable. The valid subcommands are explained in the next sections. 4. SUBCOMMANDS -addressbook changed -This command returns 1 if there has been changes made to the database, 0 -otherwise. Changes are made in memory with commands such as addressbook value, -addressbook create, addressbook remove. To make these changes permanent, -one must call the addressbook save command. + addressbook changed +This command returns 1 if there has been changes made to the database, 0 +otherwise. Changes are made in memory with commands such as addressbook +set, addressbook create, addressbook remove. To make +these changes permanent, one must call the addressbook save +command. -addressbook count + addressbook count (-groups | -persons) ?-ingroup groupID? This command returns the count of existing groups or persons in the -database. - +database. One can specify a particular group with the -ingroup option +to count only the subgroups or members in this group. -addressbook create (group | person) name ?-ingroup groupID? -This command lets you create a new group or a new person record. The name -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 -ingroup option one can -make the newly created record a subgroup or a member of the particular -group with unique ID groupID. If no error occurs, the command returns -the unique ID of the created record. + addressbook create (group | person) name ?-ingroup groupID? +This command lets you create a new group or a new person record. The +name 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 -ingroup +option one can make the newly created record a subgroup or a member of the +particular group with unique ID groupID. If no error occurs, the +command returns the unique ID of the created record. -addressbook export personID -This command lets you export the record with unique ID -personID as a VCard. The result should be -considered as binary data since it can contain an image associated to the -record. + addressbook export personID +This command lets you export the record with unique ID personID as +a VCard. The result should be considered as binary data since it can +contain an image associated to the record. -addressbook getme arrayvar -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 arrayvar -argument. See the addressbook record -command for a description of the format of the various kinds of -properties. + addressbook getme arrayvar +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 arrayvar argument. See the addressbook record command +for a description of the format of the various kinds of properties. -addressbook groups ?-ids? ?-ingroup groupID? -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 -ids argument is specified, the returned -list will contain only the unique IDs of the groups. If the -ingroup -option is specified, only the subgroups contained in the group + addressbook groups ?-ids? ?-ingroup groupID? +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 -ids argument is specified, the +returned list will contain only the unique IDs of the groups. If the +-ingroup option is specified, only the subgroups contained in the group with ID groupID will be returned. -addressbook image personID ?imageData? -This command returns the custom image associated with the record -corresponding to the unique ID personID. If no -image exists, it raises an error. The returned bytes are binary data. + addressbook image personID ?imageData? +If no imageData argument is specified, this command returns the +custom image associated with the record corresponding to the unique ID +personID. The returned bytes are binary data. If no image exists, it +raises an error. If an imageData argument is specified, it should +contain valid binary data defining an image which will be associated the +record with unique ID personID. -addressbook import vCardData -This command imports data in VCard format. The data specified by -the vCardData 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. + addressbook import vCardData +This command imports data in VCard format. The data specified by the +vCardData 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. -addressbook parents ?-ids? recordID -This command returns a list of all the groups the record with unique ID -recordID 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 -ids option is specified, only IDs are -returned. + addressbook parents ?-ids? recordID +This command returns a list of all the groups the record with unique ID +recordID 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 -ids option is specified, only IDs are +returned. -addressbook persons ?-ids? ?-ingroup groupID? + addressbook persons ?-ids? ?-ingroup groupID? 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 -ids argument is specified, the -returned list will contain only the unique IDs. If the --ingroup option is specified, only the members belonging to the group -with ID groupID will be returned. +field exists. If the -ids argument is specified, the returned list +will contain only the unique IDs. If the -ingroup option is +specified, only the members belonging to the group with ID groupID +will be returned. -addressbook property names (-groups | -persons) -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 + addressbook property names (-groups | -persons) +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 addressbook property add and addressbook property remove commands. -addressbook property add (-groups | -persons) propName propType -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 propName argument: it must be unique. One can get the list of -all the existing properties with the addressbook property names command. -The type of the property is specified by -the propType argument. This argument can have one of the following values: -Array, Data, Date, Dictionary, Integer, Real, String, MultiArray, -MultiData, MultiDate, MultiDictionary, MultiInteger, MultiReal, MultiString. + addressbook property add (-groups | -persons) propName propType +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 +propName argument: it must be unique. One can get the list of all the +existing properties with the addressbook property names command. +The type of the property is specified by the propType argument. +This argument can have one of the following values: Array, Data, Date, +Dictionary, Integer, Real, String, MultiArray, MultiData, MultiDate, +MultiDictionary, MultiInteger, MultiReal, MultiString. -addressbook property remove (-groups | -persons) propName -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 -propName argument. One can get the list of all -the existing properties with the addressbook property names command. + addressbook property remove (-groups | -persons) propName +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 +propName argument. One can get the list of all the existing +properties with the addressbook property names command. -addressbook record recordID arrayvar + addressbook record recordID arrayvar This command retrieves all the data available in the database concerning the record with unique ID recordID and stores it in the array -variable specified by the arrayvar argument. The keys of the array +variable specified by the arrayvar argument. The keys of the array (as returned by the array names 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 arrayvar variable before +property. Only existing properties for the specified record are returned by +this command: you should unset the arrayvar variable before invoking addressbook record in case you use this command repeatedly in order to be sure it does not keep stale information. - 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 + 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: 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. 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 +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}. - Dates are returned as values suitable for use with the clock format -Tcl command. It is the number of seconds relative to "Thu Jan 01 00:00:00 -CET 1970". + Dates are returned as values suitable for use with the clock +format Tcl command. It is the number of seconds relative to "Thu Jan 01 +00:00:00 CET 1970". -addressbook remove recordID ?-fromgroup groupID? + addressbook remove recordID ?-fromgroup groupID? This command removes the record with unique ID recordID from the database or from a particular subgroup specified by its unique ID with the --fromgroup option. Note that any changes made to the database -won't be definitive until you invoke the addressbook save command. +-fromgroup option. Note that any changes made to the database won't +be definitive until you invoke the addressbook save command. -addressbook save -This command lets you save the changes made in the database. Commands such -as addressbook value, addressbook create or addressbook -remove modify the data in memory: to make the changes definitive in the -database, one must call explicitely the addressbook save command. + addressbook save +This command lets you save the changes made in the database. Commands such +as addressbook set, addressbook create or addressbook +remove modify the data in memory: to make the changes definitive in the +database, one must call explicitely the addressbook save command. To check whether there has been changes in the database, use the addressbook changed command. -addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? property op value + addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? property op value This command returns all the records corresponding to the criterion described by the last three arguments: property is the name of the property whose value will be -compared to the value argument +compared to the value argument op is an operator specifying the type of comparison. It can be one of the following symbols: - ==, !=, <, <=, >, >= + ==, !=, <, <=, >, >=, ^= + +which may have different interpretations depending on whether the value is +numeric or is a string. + + For a numeric value, they correspond respectively to: + + == Equal + != Not Equal + < Less Than + <= Less Than or Equal + > Greater Than + >= Greater Than or Equal + ^= not applicable + +The ^= operator is not applicable (and will default to Greater Than or Equal). + + For a string value, they correspond respectively to: + + == Equal + != Not Equal + < not applicable + <= not applicable + > Contains Substring + >= Contains Substring + ^= Prefix Match + +The < and <= operators are not applicable and will both default to Equal. + + value is the value property you are searching - The -groups or -persons arguments let you specify the kind of records -you want to search. If it is not specified, the default is -person. -If the -ids option is specified, only IDs of the matching records are -returned, rather than pairs made of the ID and the name. The -nocase -argument concerns string comparisons and requires that no distinction be -made between uppercase and lowercase letters. + The -groups or -persons arguments let you specify the +kind of records you want to search. If it is not specified, the default is +-person. If the -ids option is specified, only IDs of the +matching records are returned, rather than pairs made of the ID and the +name. The -nocase argument concerns string comparisons and requires +that no distinction be made between uppercase and lowercase letters. -addressbook type recordID + addressbook type recordID This command returns the type (ABPerson or ABGroup) of the record with unique ID recordID. -addressbook value recordID propertyName ?value? -This command lets you get or set the value of a particular property for -the record with unique ID recordID. If the value argument is not -specified, it returns the current value of the property specified in the -propertyName argument. If value is specified, the property -propertyName will be set to this value. See the addressbook record -command for a description of the format used for the various kinds of -properties. + addressbook set recordID propertyName ?value? +This command lets you get or set the value of a particular property for the +record with unique ID recordID. If the value argument is +not specified, it returns the current value of the property specified in +the propertyName argument. If value is specified, the +property propertyName will be set to this value. See the +addressbook record command for a description of the format used for the +various kinds of properties. 5. INSTALLATION -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 auto_path Tcl variable. If -you use the extension within the AlphaX editor (version 8.0b11 or greater), -you can also install it in the Tclextensions folder which is located at the -same level as the application. +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 +auto_path Tcl variable. If you use the extension within the AlphaX +editor (version 8.0b11 or greater), you can also install it in the +Tclextensions folder which is located at the same level as the +application. 6. VERSION HISTORY - 1.0 - + 1.0 - 7. REQUIREMENTS AND PORTABILITY -This extension is only useful on Macintosh platforms. Version 10.2 or +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). @@ -255,9 +299,7 @@ This software is free software and distributed under the same licensing terms as the Tcl language itself. See license.terms in the Tcl distribution. - - © Copyright Bernard Desgraupes 2003 - + © Copyright Bernard Desgraupes 2003 10. SOURCE CODE @@ -282,6 +324,8 @@ 12. KEYWORDS Address book, data base + + |
