[Tcladdressbook-commits] Help TclAB_QuickStart.tcl,1.5,1.6
Status: Alpha
Brought to you by:
bdesgraupes
Menu
▾
▴
[Tcladdressbook-commits] Help TclAB_QuickStart.tcl,1.5,1.6
|
From: Bernard D. <bde...@us...> - 2004-08-02 06:20:12
|
Update of /cvsroot/tcladdressbook/Help In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv7629/Help Modified Files: TclAB_QuickStart.tcl Log Message: Updated to 1.1b5 Index: TclAB_QuickStart.tcl =================================================================== RCS file: /cvsroot/tcladdressbook/Help/TclAB_QuickStart.tcl,v retrieving revision 1.5 retrieving revision 1.6 diff -u -d -r1.5 -r1.6 --- TclAB_QuickStart.tcl 6 Jan 2004 06:58:38 -0000 1.5 +++ TclAB_QuickStart.tcl 2 Aug 2004 06:20:01 -0000 1.6 @@ -1,18 +1,32 @@ + + + + + + + # This file is a tutorial that demonstrates the [addressbook] command # defined by the Tcladdressbook extension for Tcl. It documents -# version ((s $currentversion s)). -# For a detailed and complete description of the syntax of each subcommand, -# refer to the help file <TclAddressBookHelp.html>. +# version 1.1. All the Tcl instructions in the sections +# below are very short one-line commands which you can try in any Tcl shell, +# like tclsh for instance. +# # For a detailed and complete description of the syntax of each subcommand, +# refer to the help file <TclAddressBookHelp.html>. +# The home page for Tcladdressbook is +# on the SourceForge site <http://tcladdressbook.sourceforge.net/>. -# Load the extension + + + +# First load the extension like this % package require addressbook # # Using the commands -# # The [groups] command +# # The [groups] subcommand # List all the groups (ID and name) % addressbook groups @@ -32,7 +46,7 @@ -# # The [persons] command +# # The [persons] subcommand # List all the persons records (ID and name) % addressbook persons @@ -43,7 +57,7 @@ -# # The [count] command +# # The [count] subcommand # Count the existing groups and persons records % addressbook count -groups @@ -52,7 +66,7 @@ -# # The [getme] command +# # The [getme] subcommand # Store the info about "me" in the variable myrecord. % set myrecord [addressbook getme] @@ -60,20 +74,33 @@ # The value of myrecord is a keyed list. One can use the usual Tcl list # commands to parse this value or special commands defined in the TclX # extension (see section Using keyed lists below). +# # The getme command can also be used with an -id option. +# In that case the unique ID of the "Me" record is returned: +% set myID [addressbook getme -id] -# # The [record] command + + +# # The [setme] subcommand +# Set the record that will represent in the database the logged-in user. + +% set theid [lindex [addressbook persons -ids] 2] +% addressbook setme $theid +% addressbook save + + + +# # The [record] subcommand # Store the ID of the first record in the variable theid % set theid [lindex [addressbook persons -ids] 0] # Store the info about this record in the variable person. The -# returned value has the same keyed list format as with the [getme] command. +# returned value has the same keyed list format as with the [getme] subcommand. % set person [addressbook record $theid] - # Similarly with a group: store the ID of the first group in the variable theid % set theid [lindex [addressbook groups -ids] 0] @@ -84,7 +111,7 @@ -# # The [type] command +# # The [type] subcommand # Find the type (ABPerson or ABGroup) of the object corresponding # to the ID $theid @@ -92,7 +119,7 @@ -# # The [remove] command +# # The [delete] subcommand # Remove from the database the record corresponding to the ID $theid % addressbook delete $theid @@ -106,17 +133,37 @@ % addressbook save + +# # The [add] subcommand +# Add to a specific group the record corresponding to the ID $theid: +# this can be a person as well as a group (which would then become a +# subgroup of the group to which it is added). + +% set groupid [lindex [addressbook groups -ids] 0] +% set theid [lindex [addressbook persons -ids] 0] +% addressbook add $groupid $theid + +# One can add several items at a time with this command: + +% addressbook add $groupid $theid1 $theid2 $theid3 + + + +# # The [remove] subcommand # Remove from a specific group the record corresponding to the ID $theid: -# it is removed as member of this subgroup but will be removed from the -# database only if it does not belong to other groups. +# this can be a person as well as a group. % set groupid [lindex [addressbook groups -ids] 0] % set theid [lindex [addressbook persons -ids] 0] -% addressbook delete $theid -fromgroup $groupid +% addressbook remove $groupid $theid + +# One can remove several items at a time with this command: +% addressbook remove $groupid $theid1 $theid2 $theid3 -# # The [parents] command + +# # The [parents] subcommand # List the parents of a person record (the various groups it belongs to). % set theid [lindex [addressbook persons -ids] 0] @@ -129,7 +176,8 @@ # One can also find the parents of a group using this command. -# # The [create] command + +# # The [create] subcommand # One can create either a group's or a person's record. The third argument # will be the "name" of the new record, that is to say the name of the new # group or the last name of the new person respectively. The command returns @@ -147,7 +195,7 @@ -# # The [property names] command +# # The [property names] subcommand # Get the list of all existing properties for groups or for persons % addressbook property names -groups @@ -155,7 +203,7 @@ -# # The [property type] command +# # The [property type] subcommand # Get the type of a particular property % addressbook property type -groups UID @@ -164,7 +212,8 @@ # For the two examples above, the result is respectively # String and MultiDictionary. -# # The [property add] command + +# # The [property add] subcommand # Add a new person's property called Instrument with type String % addressbook property add -persons Instrument String @@ -175,7 +224,20 @@ % addressbook property add -groups Meeting Date -# # The [property remove] command + +# # The [property remove] subcommand +# The third argument of this command can be either a record ID or the +# -persons and -groups keywords. If it is the former, the property is removed +# from the specified record, otherwise it is removed from all the records of +# this type and the return value is now the number of properties successfully +# removed. + +% set theid [addressbook getme -id] +% addressbook set $theid MaidenName Violet +% addressbook save +% addressbook property remove $theid MaidenName + + # Remove the properties created above: % addressbook property remove -persons Instrument @@ -183,7 +245,7 @@ -# # The [export] command +# # The [export] subcommand # Create a VCard corresponding to a particular record: % set theid [lindex [addressbook persons -ids] 0] @@ -192,7 +254,7 @@ # The data returned is binary. You can store it in a file for instance. -# # The [import] command +# # The [import] subcommand # Import in the database some information stored in a .vcf file. A new # record containing this info, is created in the database: @@ -204,7 +266,7 @@ -# # The [image] command +# # The [image] subcommand # Get the custom image corresponding to a particular record: % set theid [lindex [addressbook persons -ids] 0] @@ -213,7 +275,8 @@ # The data returned is binary. You can store it in a file for instance. # An error is raised if there is no custom image for this record. -# # The [set] command + +# # The [set] subcommand # This command lets you get or set the value of a particular field. For # instance, to get the first name, dates and address fields of the first record: @@ -232,32 +295,31 @@ # permanent. # # When setting the value of a field it is important that the new value # be formatted correctly with respect to the type of the property, as explained -# in the help file <TclAddressBookHelp.html>. Here are a few +# in the help file <TclAddressBookHelp.html>. Here are a few # examples corresponding to various property types: - -# Multi string value +% Multi string value % addressbook set $theid Email {{Work BW...@ha...} {Concerts op...@so...}} -# Date value +% Date value % addressbook set $theid Birthday [clock scan "1 Apr 1985"] -# Multi date value +% Multi date value % addressbook set $theid ABDate [list [list "birthday Franny" 621597600] [list "birthday Zooey" 816692400]] -# Multi dictionary value +% Multi dictionary value % addressbook set $theid Address [list [list Home [list {CountryCode fr} {City Paris} {Country France} {ZIP 75001} {Street "1, avenue de l'Opéra"}]]] -# # The [search] command +# # The [search] subcommand # This command can be used to report the IDs of the records corresponding to # a single criterion. The criterion is expressed by a three elements list: # the first element is the name of a property, the second is a comparison operator and @@ -274,38 +336,96 @@ # # When searching on a particular property, it is important that the # searched value be formatted correctly with respect to the type of the property, -# as explained in the help file <TclAddressBookHelp.html>. Specify +# as explained in the help file <TclAddressBookHelp.html>. Specify # an empty label or an empty key to search on all possible labels or keys # respectively. Here are a few examples corresponding to various property types: - -# Multi string value. This instruction searches one value at a time. +% Multi string value. This instruction searches one value at a time. % addressbook search -persons Phone == {Work "01 02 03 04 05"} -# Empty label to search on all phone numbers +% Empty label to search on all phone numbers % addressbook search -persons Phone >= {"" "01 02 03 04 05"} -# Multi dictionary value. This instruction searches one key +% Multi dictionary value. This instruction searches one key # in one dictionary at a time. % addressbook search -persons -nocase Address == {Home {ZIP 98765}} % addressbook search -persons -nocase Address >= {Home {ZIP 98}} -# Empty label to search on all labels +% Empty label to search on all labels % addressbook search -persons -nocase Address >= {"" {City Paris}} -# Empty key to search on all keys +% Empty key to search on all keys % addressbook search -persons -nocase Address >= {home {"" abc}} -# Empty label and key to search on all labels and keys +% Empty label and key to search on all labels and keys % addressbook search -persons -nocase Address >= {"" {"" abc}} + + + +# # The [identifier] subcommand +# This command is useful to manage distribution lists, groups used +# as a mailing list for instance. It has several subcommands (count, +# get, primary, set). +# # Suppose theid is the record ID of a person in the +# group groupid: + +% set groupid [lindex [addressbook groups -ids] 0] +% set theid [lindex [addressbook persons -ids -ingroup $groupid] 0] + +# # Count the identifiers of the Phone property: + +% addressbook identifier count $theid Phone + +# # Get some identifiers (suppose here that there are at least two of them): + +% set ident1 [addressbook identifier get $theid Phone 0] +% set ident2 [addressbook identifier get $theid Phone 1] + +# # Get the primary identifier (the one which is chosen by default if +# none has been specified otherwise): + +% addressbook identifier primary $theid Phone + +# # Get the current distribution identifier: + +% addressbook identifier set $groupid $theid Phone + +# # Set the distribution identifier to ident2: + +% addressbook identifier set $groupid $theid Phone $ident2 + +# # The reverse operation of the addressbook identifier get command +# is the addressbook identifier index command which returns the +# index corresponding to a given identifier. For instance, the following +# instruction will return the index 1: + +% addressbook identifier index $theid Phone $ident2 + + +# # The [label] subcommand +# Let's find the label of the first phone number for a record: + +% set theid [addressbook getme -id] +% addressbook label $theid Phone 0 + +# The returned string could be Home for instance. Let's change it to +# "Personal": + +% addressbook label $theid Phone 0 Personal +% addressbook save + + + + +# ((a ukl)) # # Using keyed lists -# Keyed lists can be easily manipulated using the keylget and +# Keyed lists can be easily manipulated using the keylget and # keylset commands defined by the TclX extension. For instance, if a # record has been stored in some variable myrecord, one can extract # various fields like this: @@ -326,3 +446,8 @@ + +# # ---------------------------------------------------------------------- +# # Last updated 2004-08-02 08:13:35 + + |
