[Tcladdressbook-commits] Help TclAB_QuickStart.tcl,1.3,1.4
Status: Alpha
Brought to you by:
bdesgraupes
Menu
▾
▴
[Tcladdressbook-commits] Help TclAB_QuickStart.tcl,1.3,1.4
|
From: <bde...@us...> - 2004-01-05 05:38:35
|
Update of /cvsroot/tcladdressbook/Help In directory sc8-pr-cvs1:/tmp/cvs-serv3376/Help Modified Files: TclAB_QuickStart.tcl Log Message: Update syntax before beta Index: TclAB_QuickStart.tcl =================================================================== RCS file: /cvsroot/tcladdressbook/Help/TclAB_QuickStart.tcl,v retrieving revision 1.3 retrieving revision 1.4 diff -u -d -r1.3 -r1.4 --- TclAB_QuickStart.tcl 28 Dec 2003 07:47:23 -0000 1.3 +++ TclAB_QuickStart.tcl 5 Jan 2004 05:38:32 -0000 1.4 @@ -1,294 +1,320 @@ -# This file is a tutorial that demonstrates the [addressbook] command. -# For a detailed and complete description of the syntax of each subcommand, -# see the file TclAddressBookHelp (text format) or TclAddressBookHelp.html -# (to be viewed in a browser). -# -# Author: Bernard Desgraupes -# e-mail: <bde...@ea...> -# Web page of the Tcladdressbook extension: -# <http://sourceforge.net/projects/tcladdressbook> -# -# $Date$ -# $Revision$ +# 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>. # Load the extension - package require addressbook +% package require addressbook -# Using the commands -# The [groups] command -# List the groups (name and ID) +# # Using the commands +# # The [groups] command +# List all the groups (ID and name) - addressbook groups +% addressbook groups -# List the groups (only ID) +# List all the groups (only ID) - addressbook groups -ids +% addressbook groups -ids -# List the subgroups of a specific group (name and ID) +# List the subgroups of a specific group (ID and name) - set groupid [lindex [addressbook groups -ids] 2] - addressbook groups -ingroup $groupid +% set groupid [lindex [addressbook groups -ids] 0] +% addressbook groups -ingroup $groupid # List the subgroups of a specific group (only ID) - addressbook groups -ids -ingroup $groupid +% addressbook groups -ids -ingroup $groupid -# The [persons] command -# List the person records (name and ID) +# # The [persons] command +# List all the persons records (ID and name) - addressbook persons +% addressbook persons -# List the person records (only ID) +# List all the persons records (only ID) - addressbook persons -ids +% addressbook persons -ids -# The [count] command -# Count the existing groups and person records +# # The [count] command +# Count the existing groups and persons records - addressbook count -groups - addressbook count -persons - addressbook count -persons -ingroup [lindex [addressbook groups -ids] 0] +% addressbook count -groups +% addressbook count -persons +% addressbook count -persons -ingroup [lindex [addressbook groups -ids] 0] -# The [getme] command +# # The [getme] command # Store the info about "me" in the variable myrecord. - set myrecord [addressbook getme] +% set myrecord [addressbook getme] # The value of myrecord is a keyed list. One can use the usual Tcl list -# commands or the special keylist commands defined in the TclX extension -# like this: - - keylkeys myrecord - keylget myrecord Email.work - keylget myrecord Address.home.ZIP - clock format [keylget myrecord Birthday] - +# commands to parse this value or special commands defined in the TclX +# extension (see section Using keyed lists below). -# The [record] command +# # The [record] command # Store the ID of the first record in the variable theid - set theid [lindex [addressbook persons -ids] 0] +% set theid [lindex [addressbook persons -ids] 0] -# Store the info about this record in the variable "person". The syntax is -# the same as with the [getme] command. +# Store the info about this record in the variable person. The +# returned value has the same keyed list format as with the [getme] command. - set person [addressbook record $theid] - keylkeys person - keylget person Email.work - keylget person Address.home.ZIP - clock format [keylget person Birthday] +% set person [addressbook record $theid] -# Store the ID of the first group in the variable theid +# Similarly with a group: store the ID of the first group in the variable theid - set theid [lindex [addressbook groups -ids] 0] +% set theid [lindex [addressbook groups -ids] 0] # Store the info about this group in the variable grp - set grp [addressbook record $theid] - keylkeys grp - keylget grp GroupName - clock format [keylget grp Modification] +% set grp [addressbook record $theid] -# The [type] command +# # The [type] command # Find the type (ABPerson or ABGroup) of the object corresponding # to the ID $theid - addressbook type $theid - - - -# The [property names] command -# Get the list of all existing properties for groups or persons - - addressbook property names -groups - addressbook property names -persons +% addressbook type $theid -# The [remove] command -# Remove the record corresponding to the ID $theid from the database +# # The [remove] command +# Remove from the database the record corresponding to the ID $theid - addressbook delete $theid +% addressbook delete $theid # Check that there were changes (1 if yes, 0 if no) - addressbook changed +% addressbook changed # Save the changes to make them permanent - addressbook save +% addressbook save -# Remove the record corresponding to the ID $theid from a specific group: +# 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. - set groupid [lindex [addressbook groups -ids] 0] - set theid [lindex [addressbook persons -ids] 0] - addressbook delete $theid -fromgroup $groupid +% set groupid [lindex [addressbook groups -ids] 0] +% set theid [lindex [addressbook persons -ids] 0] +% addressbook delete $theid -fromgroup $groupid -# The [parents] command +# # The [parents] command # List the parents of a person record (the various groups it belongs to). -# One can also find the parents of a group with this command. - set theid [lindex [addressbook persons -ids] 0] - addressbook parents $theid +% set theid [lindex [addressbook persons -ids] 0] +% addressbook parents $theid # List the parents of a person record (only ID) - addressbook parents -ids $theid +% addressbook parents -ids $theid +# One can also find the parents of a group using this command. -# The [create] command - (group|person) +# # The [create] command -# The [property type] command -# Get the name of a particular property - addressbook property type -groups UID - addressbook property type -persons Address +# # The [property names] command +# Get the list of all existing properties for groups or for persons +% addressbook property names -groups +% addressbook property names -persons -# The [property add] command -# Add a new property of type String called Instrument - addressbook property add -persons Instrument String +# # The [property type] command +# Get the type of a particular property -# Add a new property of type Date called Meeting +% addressbook property type -groups UID +% addressbook property type -persons Address - addressbook property add -groups Meeting Date +# For the two examples above, the result is respectively +# String and MultiDictionary. +# # The [property add] command +# Add a new person's property called Instrument with type String -# The [property remove] command -# Remove the properties created above +% addressbook property add -persons Instrument String - addressbook property remove -persons Instrument - addressbook property remove -groups Meeting +# Add a new group's property called Meeting with type Date +% addressbook property add -groups Meeting Date -# The [export] command -# Create a VCard corresponding to a particular record. - set theid [lindex [addressbook persons -ids] 0] +# # The [property remove] command +# Remove the properties created above: -# The data returned is binary. You can store it in a file. +% addressbook property remove -persons Instrument +% addressbook property remove -groups Meeting - set vcardData [addressbook export $theid] +# # The [export] command +# Create a VCard corresponding to a particular record: -# The [import] command +% set theid [lindex [addressbook persons -ids] 0] +% set vcardData [addressbook export $theid] - set fname [file join /Users bernardo someVcard.vcf] - set fid [open $fname r] - set vcard [read $fid] - close $fid - addressbook import $vcard +# The data returned is binary. You can store it in a file for instance. +# # The [import] command +# Import in the database some information stored in a .vcf file. A new +# record containing this info, is created in the database: -# The [image] command +% set fname [file join /Users bernardo someVcard.vcf] +% set fid [open $fname r] +% set vcard [read $fid] +% close $fid +% addressbook import $vcard - set theid [lindex [addressbook persons -ids] 0] - set img [addressbook image $theid] +# # The [image] command +# Get the custom image corresponding to a particular record: -# The [set] command +% set theid [lindex [addressbook persons -ids] 0] +% set img [addressbook image $theid] - set theid [lindex [addressbook persons -ids] 0] - addressbook set $theid First +# 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 +# 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: +% set theid [lindex [addressbook persons -ids] 0] +% addressbook set $theid First +% addressbook set $theid ABDate +% addressbook set $theid Address - addressbook set $theid First Georgios - addressbook changed - addressbook save +# To change the first name of the first record: +% addressbook set $theid First Georgios +% addressbook changed +% addressbook save +# Note that the addressbook save command must be invoked to make the changes +# 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 +# examples corresponding to various property types: - addressbook set $theid First Johann-Sebastian +# Multi string value -# Multi string value - addressbook set $theid Email {{Work wo...@ha...} {Concerts DD...@su...}} - addressbook set $theid Email {{Work op...@or...} {Concerts BW...@CA...}} +% addressbook set $theid Email {{Work BW...@ha...} {Concerts op...@so...}} + +# Date value -# Date value - addressbook set $theid Birthday [clock scan "1 Apr 1985"] +% addressbook set $theid Birthday [clock scan "1 Apr 1985"] -# Multi date value - addressbook set $theid ABDate - addressbook set $theid ABDate [list [list "birthday Franny" 621597600] [list "birthday Zooey" 816692400]] +# Multi date value +% addressbook set $theid ABDate [list [list "birthday Franny" 621597600] [list "birthday Zooey" 816692400]] -# Multi dictionary value - addressbook set $theid Address - addressbook set $theid Address [list [list Home [list {CountryCode fr} {City Paris} {Country France} {ZIP 75001} {Street "1, avenue de l'Opéra"}] ] ] +# 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 - addressbook search -persons -ids -nocase Last == "Bach" - addressbook search -persons -ids -nocase Last > "Ba" +# # The [search] command +# 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 +# the third is the value to search for. Refer to the help file for a complete +# description of the possible comparison operators. A few options are available +# (-persons, -ids and -nocase). Here are a few simple examples: - addressbook search -persons -nocase Modification >= 1070199949 - addressbook search -persons -nocase Modification < 1070199949 +% addressbook search Last == "Bach" +% addressbook search -persons -ids -nocase Last > "Ba" +% addressbook search -persons Modification >= 1070199949 +% addressbook search -persons Modification < 1070199949 -# Multi string value. It searches one value at a time. - addressbook search -persons Phone == {Work "01 02 03 04 05"} +# # 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 +# 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: -# Empty label --> to search on all phones - addressbook search -persons Phone >= {"" "01 02 03 04 05"} +# Multi string value. This instruction searches one value at a time. +% addressbook search -persons Phone == {Work "01 02 03 04 05"} -# Multi dict value. It 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 phone numbers -# Empty label --> to search on all labels - addressbook search -persons -nocase Address >= {"" {City Paris}} +% addressbook search -persons Phone >= {"" "01 02 03 04 05"} -# Empty key --> to search on all keys - addressbook search -persons -nocase Address >= {home {"" abc}} +# Multi dictionary value. This instruction searches one key +# in one dictionary at a time. -# Empty label and key --> to search on all labels and keys - addressbook search -persons -nocase Address >= {"" {"" abc}} +% addressbook search -persons -nocase Address == {Home {ZIP 98765}} +% addressbook search -persons -nocase Address >= {Home {ZIP 98}} +# Empty label to search on all labels +% addressbook search -persons -nocase Address >= {"" {City Paris}} -# Using keyed lists +# Empty key to search on all keys - package require tclx +% addressbook search -persons -nocase Address >= {home {"" abc}} +# Empty label and key to search on all labels and keys -# ---------------------------------------------------------------------- -# Last updated 2003-12-28 08:36:25 +% addressbook search -persons -nocase Address >= {"" {"" abc}} + + + +# # Using keyed lists +# 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: + +% package require tclx +% keylkeys myrecord +% keylget myrecord Email.work +% keylget myrecord Address.home.ZIP +% clock format [keylget myrecord Birthday] + +# Similarly, with a group, one can invoke: + +% set theid [lindex [addressbook groups -ids] 0] +% set grp [addressbook record $theid] +% keylkeys grp +% keylget grp GroupName +% clock format [keylget grp Modification] + + + + +# # ---------------------------------------------------------------------- +# # Last updated ((s [ISOTime::ISODateAndTimeRelaxed] s)) |
