diff options
| author | dkf <donal.k.fellows@manchester.ac.uk> | 2004-10-27 14:24:37 (GMT) |
|---|---|---|
| committer | dkf <donal.k.fellows@manchester.ac.uk> | 2004-10-27 14:24:37 (GMT) |
| commit | f2710bf0bb0c6ace5d1bc4f424b400537ffdb21c (patch) | |
| tree | c19b22fbb2165682630fecbf3779e53b26c9002f | |
| parent | 4c2d0f20bfa9108949678cf49bfdc58eedc7bb93 (diff) | |
| download | tcl-f2710bf0bb0c6ace5d1bc4f424b400537ffdb21c.zip tcl-f2710bf0bb0c6ace5d1bc4f424b400537ffdb21c.tar.gz tcl-f2710bf0bb0c6ace5d1bc4f424b400537ffdb21c.tar.bz2 | |
More minor doc fixes
| -rw-r--r-- | ChangeLog | 2 | ||||
| -rw-r--r-- | doc/after.n | 18 | ||||
| -rw-r--r-- | doc/array.n | 28 | ||||
| -rw-r--r-- | doc/binary.n | 6 | ||||
| -rw-r--r-- | doc/clock.n | 28 | ||||
| -rw-r--r-- | doc/dde.n | 4 | ||||
| -rw-r--r-- | doc/encoding.n | 10 | ||||
| -rw-r--r-- | doc/file.n | 42 | ||||
| -rw-r--r-- | doc/info.n | 8 | ||||
| -rw-r--r-- | doc/interp.n | 20 | ||||
| -rw-r--r-- | doc/msgcat.n | 36 | ||||
| -rw-r--r-- | doc/namespace.n | 176 | ||||
| -rw-r--r-- | doc/open.n | 5 | ||||
| -rw-r--r-- | doc/package.n | 6 | ||||
| -rw-r--r-- | doc/pid.n | 4 | ||||
| -rw-r--r-- | doc/proc.n | 18 | ||||
| -rw-r--r-- | doc/puts.n | 18 | ||||
| -rw-r--r-- | doc/pwd.n | 3 | ||||
| -rw-r--r-- | doc/read.n | 6 | ||||
| -rw-r--r-- | doc/regexp.n | 16 | ||||
| -rw-r--r-- | doc/registry.n | 6 | ||||
| -rw-r--r-- | doc/regsub.n | 12 | ||||
| -rw-r--r-- | doc/rename.n | 5 | ||||
| -rw-r--r-- | doc/return.n | 106 | ||||
| -rw-r--r-- | doc/scan.n | 24 | ||||
| -rw-r--r-- | doc/seek.n | 8 | ||||
| -rw-r--r-- | doc/set.n | 24 | ||||
| -rw-r--r-- | doc/socket.n | 20 | ||||
| -rw-r--r-- | doc/source.n | 10 | ||||
| -rw-r--r-- | doc/split.n | 29 | ||||
| -rw-r--r-- | doc/string.n | 8 | ||||
| -rw-r--r-- | doc/subst.n | 26 | ||||
| -rw-r--r-- | doc/switch.n | 17 |
33 files changed, 359 insertions, 390 deletions
@@ -1,6 +1,6 @@ 2004-10-27 Donal K. Fellows <donal.k.fellows@man.ac.uk> - * doc/[a-l]*.n: Many small general documentation fixes. + * doc/[a-s]*.n: Many small general documentation fixes. 2004-10-26 David Gravereaux <davygrvy@pobox.com> diff --git a/doc/after.n b/doc/after.n index 6e6ab1a..5cabb98 100644 --- a/doc/after.n +++ b/doc/after.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: after.n,v 1.5 2004/10/27 09:36:58 dkf Exp $ +'\" RCS: @(#) $Id: after.n,v 1.6 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH after n 7.5 Tcl "Tcl Built-In Commands" @@ -101,24 +101,21 @@ will not be executed unless the application enters the event loop. In applications that are not normally event-driven, such as \fBtclsh\fR, the event loop can be entered with the \fBvwait\fR and \fBupdate\fR commands. - .SH "EXAMPLES" This defines a command to make Tcl do nothing at all for \fIN\fR seconds: - .CS proc sleep {N} { - \fBafter\fR [expr {int($N * 1000)}] + \fBafter\fR [expr {int($N * 1000)}] } .CE - +.PP This arranges for the command \fIwake_up\fR to be run in eight hours (providing the event loop is active at that time): - .CS \fBafter\fR [expr {1000 * 60 * 60 * 8}] wake_up .CE - +.PP The following command can be used to do long-running calculations (as represented here by \fI::my_calc::one_step\fR, which is assumed to return a boolean indicating whether another step should be performed) @@ -129,12 +126,11 @@ processing steps (arranging for the next step to be done using an already-triggered timer event only when the event queue has been drained) and is useful when you want to ensure that a Tk GUI remains responsive during a slow task. - .CS proc doOneStep {} { - if {[::my_calc::one_step]} { - \fBafter\fR idle [list \fBafter\fR 0 doOneStep] - } + if {[::my_calc::one_step]} { + \fBafter idle\fR [list \fBafter\fR 0 doOneStep] + } } doOneStep .CE diff --git a/doc/array.n b/doc/array.n index 1ef31e8..84dda45 100644 --- a/doc/array.n +++ b/doc/array.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: array.n,v 1.12 2004/03/28 00:48:03 msofer Exp $ +'\" RCS: @(#) $Id: array.n,v 1.13 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH array n 8.3 Tcl "Tcl Built-In Commands" @@ -140,42 +140,40 @@ error will be raised. If \fIpattern\fR is omitted and \fIarrayName\fR is an array variable, then the command unsets the entire array. The command always returns an empty string. .VE 8.3 - .SH EXAMPLES - .CS -array set colorcount { - red 1 - green 5 - blue 4 - white 9 +\fBarray set\fR colorcount { + red 1 + green 5 + blue 4 + white 9 } -foreach {color count} [array get colorcount] { - puts "Color: $color Count: $count" +foreach {color count} [\fBarray get\fR colorcount] { + puts "Color: $color Count: $count" } => Color: blue Count: 4 Color: white Count: 9 Color: green Count: 5 Color: red Count: 1 -foreach color [array names colorcount] { - puts "Color: $color Count: $colorcount($color)" +foreach color [\fBarray names\fR colorcount] { + puts "Color: $color Count: $colorcount($color)" } => Color: blue Count: 4 Color: white Count: 9 Color: green Count: 5 Color: red Count: 1 -foreach color [lsort [array names colorcount]] { - puts "Color: $color Count: $colorcount($color)" +foreach color [lsort [\fBarray names\fR colorcount]] { + puts "Color: $color Count: $colorcount($color)" } => Color: blue Count: 4 Color: green Count: 5 Color: red Count: 1 Color: white Count: 9 -array statistics colorcount +\fBarray statistics\fR colorcount => 4 entries in table, 4 buckets number of buckets with 0 entries: 1 number of buckets with 1 entries: 2 diff --git a/doc/binary.n b/doc/binary.n index 54bf6c4..ca75b6a 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: binary.n,v 1.21 2004/10/27 09:36:58 dkf Exp $ +'\" RCS: @(#) $Id: binary.n,v 1.22 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH binary n 8.0 Tcl "Tcl Built-In Commands" @@ -750,7 +750,7 @@ UTF-8 data preceded by a length word: .CS proc writeString {channel string} { set data [encoding convertto utf-8 $string] - puts -nonewline [\fBbinary\fR format Ia* \e + puts -nonewline [\fBbinary format\fR Ia* \e [string length $data] $data] } .CE @@ -759,7 +759,7 @@ This procedure reads a string from a channel that was written by the previously presented \fBwriteString\fR procedure: .CS proc readString {channel} { - if {![\fBbinary\fR scan [read $channel 4] I length]} { + if {![\fBbinary scan\fR [read $channel 4] I length]} { error "missing length" } set data [read $channel $length] diff --git a/doc/clock.n b/doc/clock.n index c1f1f4d..3f19644 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -190,10 +190,10 @@ that observe summer time (Daylight Saving Time). For example, the following code sets the value of \fBx\fR to \fB04:00:00\fR because the clock has changed in the interval in question. .CS -set s [\fBclock\fR scan {2004-10-30 05:00:00} \\ +set s [\fBclock scan\fR {2004-10-30 05:00:00} \\ -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] -set a [\fBclock\fR add $s 24 hours -timezone :America/New_York] -set x [\fBclock\fR format $a \\ +set a [\fBclock add\fR $s 24 hours -timezone :America/New_York] +set x [\fBclock format\fR $a \\ -format {%H:%M:%S} -timezone :America/New_York] .CE .PP @@ -209,10 +209,10 @@ the time changes at the start or end of summer time (Daylight Saving Time) results in the \fIsame local time\fR on the day in question. For instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR. .CS -set s [\fBclock\fR scan {2004-10-30 05:00:00} \\ +set s [\fBclock scan\fR {2004-10-30 05:00:00} \\ -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] -set a [\fBclock\fR add $s 1 day -timezone :America/New_York] -set x [\fBclock\fR format $a \\ +set a [\fBclock add\fR $s 1 day -timezone :America/New_York] +set x [\fBclock format\fR $a \\ -format {%H:%M:%S} -timezone :America/New_York] .CE .PP @@ -223,10 +223,10 @@ Daylight Saving Time change using US rules), the time is converted as if the clock had not changed. Thus, the following code will set the value of \fBx\fR to \fB03:30:00\fR. .CS -set s [\fBclock\fR scan {2004-04-03 02:30:00} \\ +set s [\fBclock scan\fR {2004-04-03 02:30:00} \\ -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] -set a [\fBclock\fR add $s 1 day -timezone :America/New_York] -set x [\fBclock\fR format $a \\ +set a [\fBclock add\fR $s 1 day -timezone :America/New_York] +set x [\fBclock format\fR $a \\ -format {%H:%M:%S} -timezone :America/New_York] .CE .PP @@ -234,9 +234,9 @@ Adding a given number of days or weeks works correctly across the conversion between the Julian and Gregorian calendars; the omitted days are skipped. The following code sets \fBz\fR to \fB1752-09-14\fR. .CS -set x [\fBclock\fR scan 1752-09-02 -format %Y-%m-%d -locale en_US] -set y [\fBclock\fR add $x 1 day -locale en_US] -set z [\fBclock\fR format $y -format %Y-%m-%d -locale en_US] +set x [\fBclock scan\fR 1752-09-02 -format %Y-%m-%d -locale en_US] +set y [\fBclock add\fR $x 1 day -locale en_US] +set z [\fBclock format\fR $y -format %Y-%m-%d -locale en_US] .CE .PP In the bizarre case that adding the given number of days yields a date @@ -846,9 +846,9 @@ years. This means that when crossing the daylight savings time boundary, different results will be given for \fBclock scan "1 day"\fR and \fBclock scan "24 hours"\fR: .CS -% \fBclock\fR scan "1 day" -base [\fBclock\fR scan 1999-10-31] +% \fBclock scan\fR "1 day" -base [\fBclock scan\fR 1999-10-31] 941443200 -% \fBclock\fR scan "24 hours" -base [\fBclock\fR scan 1999-10-31] +% \fBclock scan\fR "24 hours" -base [\fBclock scan\fR 1999-10-31] 941439600 .CE .SH "SEE ALSO" @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: dde.n,v 1.15 2004/10/27 09:36:58 dkf Exp $ +'\" RCS: @(#) $Id: dde.n,v 1.16 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH dde n 1.2 dde "Tcl Bundled Packages" @@ -149,7 +149,7 @@ This asks Internet Explorer (which must already be running) to go to a particularly important website: .CS package require dde -\fBdde\fR execute iexplore WWW_OpenURL http://www.tcl.tk/ +\fBdde execute\fR iexplore WWW_OpenURL http://www.tcl.tk/ .CE .SH "SEE ALSO" diff --git a/doc/encoding.n b/doc/encoding.n index e97db96..36db314 100644 --- a/doc/encoding.n +++ b/doc/encoding.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: encoding.n,v 1.5 2004/10/27 09:36:58 dkf Exp $ +'\" RCS: @(#) $Id: encoding.n,v 1.6 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH encoding n "8.1" Tcl "Tcl Built-In Commands" @@ -21,13 +21,12 @@ Strings in Tcl are encoded using 16-bit Unicode characters. Different operating system interfaces or applications may generate strings in other encodings such as Shift-JIS. The \fBencoding\fR command helps to bridge the gap between Unicode and these other formats. - .SH DESCRIPTION .PP Performs one of several encoding related operations, depending on \fIoption\fR. The legal \fIoption\fRs are: .TP -\fBencoding convertfrom ?\fIencoding\fR? \fIdata\fR +\fBencoding convertfrom\fR ?\fIencoding\fR? \fIdata\fR Convert \fIdata\fR to Unicode from the specified \fIencoding\fR. The characters in \fIdata\fR are treated as binary data where the lower 8-bits of each character is taken as a single byte. The resulting @@ -35,7 +34,7 @@ sequence of bytes is treated as a string in the specified \fIencoding\fR. If \fIencoding\fR is not specified, the current system encoding is used. .TP -\fBencoding convertto ?\fIencoding\fR? \fIstring\fR +\fBencoding convertto\fR ?\fIencoding\fR? \fIstring\fR Convert \fIstring\fR from Unicode to the specified \fIencoding\fR. The result is a sequence of bytes that represents the converted string. Each byte is stored in the lower 8-bits of a Unicode @@ -50,7 +49,6 @@ currently available. Set the system encoding to \fIencoding\fR. If \fIencoding\fR is omitted then the command returns the current system encoding. The system encoding is used whenever Tcl passes strings to system calls. - .SH EXAMPLE .PP It is common practice to write script files using a text editor that @@ -71,7 +69,7 @@ of the original string. The \fBencoding\fR command can be used to convert this string to the expected Japanese Unicode characters. For example, .CS -set s [\fBencoding\fR convertfrom euc-jp "\\xA4\\xCF"] +set s [\fBencoding convertfrom\fR euc-jp "\\xA4\\xCF"] .CE would return the Unicode string "\\u306F", which is the Hiragana letter HA. @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: file.n,v 1.37 2004/10/27 12:53:22 dkf Exp $ +'\" RCS: @(#) $Id: file.n,v 1.38 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH file n 8.3 Tcl "Tcl Built-In Commands" @@ -437,22 +437,22 @@ that have a correspondingly-named object file in the current directory: .CS proc findMatchingCFiles {dir} { - set files {} - switch $::tcl_platform(platform) { - windows { - set ext .obj - } - unix { - set ext .o - } - } - foreach file [glob -nocomplain -directory $dir *.c] { - set objectFile [\fBfile\fR tail [\fBfile\fR rootname $file]]$ext - if {[\fBfile\fR exists $objectFile]} { - lappend files $file - } - } - return $files + set files {} + switch $::tcl_platform(platform) { + windows { + set ext .obj + } + unix { + set ext .o + } + } + foreach file [glob -nocomplain -directory $dir *.c] { + set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext + if {[\fBfile exists\fR $objectFile]} { + lappend files $file + } + } + return $files } .CE .PP @@ -462,11 +462,11 @@ to the new place: set oldName foobar.txt set newName foo/bar.txt # Make sure that where we're going to move to exists... -if {![\fBfile\fR isdirectory [\fBfile\fR dirname $newName]]} { - \fBfile\fR mkdir [\fBfile\fR dirname $newName] +if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} { + \fBfile mkdir\fR [\fBfile dirname\fR $newName] } -\fBfile\fR rename $oldName $newName -\fBfile\fR link -symbolic $oldName $newName +\fBfile rename\fR $oldName $newName +\fBfile link\fR -symbolic $oldName $newName .CE .SH "SEE ALSO" @@ -7,7 +7,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: info.n,v 1.13 2004/10/27 12:53:22 dkf Exp $ +'\" RCS: @(#) $Id: info.n,v 1.14 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH info n 8.4 Tcl "Tcl Built-In Commands" @@ -214,8 +214,8 @@ script: proc printProc {procName} { set result [list proc $procName] set formals {} - foreach var [\fBinfo\fR args $procName] { - if {[\fBinfo\fR default $procName $var def]} { + foreach var [\fBinfo args\fR $procName] { + if {[\fBinfo default\fR $procName $var def]} { lappend formals [list $var $def] } else { # Still need the list-quoting because variable @@ -223,7 +223,7 @@ proc printProc {procName} { lappend formals [list $var] } } - puts [lappend result $formals [\fBinfo\fR body $procName]] + puts [lappend result $formals [\fBinfo body\fR $procName]] } .CE diff --git a/doc/interp.n b/doc/interp.n index e219d15..8516941 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: interp.n,v 1.18 2004/10/27 12:53:22 dkf Exp $ +'\" RCS: @(#) $Id: interp.n,v 1.19 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH interp n 7.6 Tcl "Tcl Built-In Commands" @@ -717,30 +717,30 @@ by Nathaniel Borenstein and Marshall Rose. .SH EXAMPLES Creating and using an alias for a command in the current interpreter: .CS -\fBinterp\fR alias {} getIndex {} lsearch {alpha beta gamma delta} +\fBinterp alias\fR {} getIndex {} lsearch {alpha beta gamma delta} set idx [getIndex delta] .CE .PP Executing an arbitrary command in a safe interpreter where every invokation of \fBlappend\fR is logged: .CS -set i [\fBinterp\fR create -safe] -\fBinterp\fR hide $i lappend -\fBinterp\fR alias $i lappend {} loggedLappend $i +set i [\fBinterp create\fR -safe] +\fBinterp hide\fR $i lappend +\fBinterp alias\fR $i lappend {} loggedLappend $i proc loggedLappend {i args} { puts "logged invokation of lappend $args" - \fBinterp\fR invokehidden $i lappend {expand}$args + \fBinterp invokehidden\fR $i lappend {expand}$args } -\fBinterp\fR eval $i $someUntrustedScript +\fBinterp eval\fR $i $someUntrustedScript .CE .PP .VS 8.5 Setting a resource limit on an interpreter so that an infinite loop terminates. .CS -set i [\fBinterp\fR create] -\fBinterp\fR limit $i command -value 1000 -\fBinterp\fR eval $i { +set i [\fBinterp create\fR] +\fBinterp limit\fR $i command -value 1000 +\fBinterp eval\fR $i { set x 0 while {1} { puts "Counting up... [incr x]" diff --git a/doc/msgcat.n b/doc/msgcat.n index 5cd6e0e..a00d8fa 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -55,7 +55,7 @@ Returns a translation of \fIsrc-string\fR according to the user's current locale. If additional arguments past \fIsrc-string\fR are given, the \fBformat\fR command is used to substitute the additional arguments in the translation of \fIsrc-string\fR. - +.PP \fB::msgcat::mc\fR will search the messages defined in the current namespace for a translation of \fIsrc-string\fR; if none is found, it will search in the parent of the current namespace, @@ -185,10 +185,12 @@ error. .PP For example, executing the code .CS -mcset en hello "hello from ::" -namespace eval foo {mcset en hello "hello from ::foo"} -puts [mc hello] -namespace eval foo {puts [mc hello]} +\fB::msgcat::mcset\fR en hello "hello from ::" +namespace eval foo { + \fB::msgcat::mcset\fR en hello "hello from ::foo" +} +puts [\fB::msgcat::mc\fR hello] +namespace eval foo {puts [\fB::msgcat::mc\fR hello]} .CE will print .CS @@ -204,19 +206,20 @@ to "inherit" messages from their parent namespace. .PP For example, executing (in the ``en'' locale) the code .CS -mcset en m1 ":: message1" -mcset en m2 ":: message2" -mcset en m3 ":: message3" +\fB::msgcat::mcset\fR en m1 ":: message1" +\fB::msgcat::mcset\fR en m2 ":: message2" +\fB::msgcat::mcset\fR en m3 ":: message3" namespace eval ::foo { - mcset en m2 "::foo message2" - mcset en m3 "::foo message3" + \fB::msgcat::mcset\fR en m2 "::foo message2" + \fB::msgcat::mcset\fR en m3 "::foo message3" } namespace eval ::foo::bar { - mcset en m3 "::foo::bar message3" + \fB::msgcat::mcset\fR en m3 "::foo::bar message3" } -puts "[mc m1]; [mc m2]; [mc m3]" -namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc m3]"} -namespace eval ::foo::bar {puts "[mc m1]; [mc m2]; [mc m3]"} +namespace import \fB::msgcat::mc\fR +puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]" +namespace eval ::foo {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"} +namespace eval ::foo::bar {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"} .CE will print .CS @@ -251,7 +254,7 @@ so that all source strings are tied to the namespace of the package. For example, a short \fBes.msg\fR might contain: .CS namespace eval ::mypackage { - ::msgcat::mcset es "Free Beer!" "Cerveza Gracias!" + \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!" } .CE .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES" @@ -269,7 +272,7 @@ Copy your *.msg files into that directory. initialization script: .CS # load language files, stored in msgs subdirectory -::msgcat::mcload [file join [file dirname [info script]] msgs] +\fB::msgcat::mcload\fR [file join [file dirname [info script]] msgs] .CE .SH "POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS" .PP @@ -292,7 +295,6 @@ format "In location %2\\$s we produced %1\\$d units" $num $city .PP Similarly, positional parameters can be used with \fBscan\fR to extract values from internationalized strings. - .SH CREDITS .PP The message catalog code was developed by Mark Harrison. diff --git a/doc/namespace.n b/doc/namespace.n index c9d974d..07dfc3d 100644 --- a/doc/namespace.n +++ b/doc/namespace.n @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: namespace.n,v 1.15 2004/08/31 15:19:36 dkf Exp $ +'\" RCS: @(#) $Id: namespace.n,v 1.16 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH namespace n 8.5 Tcl "Tcl Built-In Commands" @@ -262,15 +262,15 @@ The global namespace holds all global variables and commands. The \fBnamespace eval\fR command lets you create new namespaces. For example, .CS -\fBnamespace eval Counter { - namespace export bump - variable num 0 +\fBnamespace eval\fR Counter { + \fBnamespace export\fR bump + variable num 0 - proc bump {} { - variable num - incr num - } -}\fR + proc bump {} { + variable num + incr num + } +} .CE creates a new namespace containing the variable \fBnum\fR and the procedure \fBbump\fR. @@ -292,21 +292,21 @@ namespace over time using a series of \fBnamespace eval\fR commands. For example, the following series of commands has the same effect as the namespace definition shown above: .CS -\fBnamespace eval Counter { - variable num 0 - proc bump {} { - variable num - return [incr num] - } +\fBnamespace eval\fR Counter { + variable num 0 + proc bump {} { + variable num + return [incr num] + } } -namespace eval Counter { - proc test {args} { - return $args - } +\fBnamespace eval\fR Counter { + proc test {args} { + return $args + } } -namespace eval Counter { +\fBnamespace eval\fR Counter { rename test "" -}\fR +} .CE Note that the \fBtest\fR procedure is added to the \fBCounter\fR namespace, and later removed via the \fBrename\fR command. @@ -339,12 +339,12 @@ Names must be qualified by the namespace that contains them. From the global namespace, we might access the \fBCounter\fR procedures like this: .CS -\fBCounter::bump 5 -Counter::Reset\fR +Counter::bump 5 +Counter::Reset .CE We could access the current count like this: .CS -\fBputs "count = $Counter::num"\fR +puts "count = $Counter::num" .CE When one namespace contains another, you may need more than one qualifier to reach its elements. @@ -352,18 +352,18 @@ If we had a namespace \fBFoo\fR that contained the namespace \fBCounter\fR, you could invoke its \fBbump\fR procedure from the global namespace like this: .CS -\fBFoo::Counter::bump 3\fR +Foo::Counter::bump 3 .CE .PP You can also use qualified names when you create and rename commands. For example, you could add a procedure to the \fBFoo\fR namespace like this: .CS -\fBproc Foo::Test {args} {return $args}\fR +proc Foo::Test {args} {return $args} .CE And you could move the same procedure to another namespace like this: .CS -\fBrename Foo::Test Bar::Test\fR +rename Foo::Test Bar::Test .CE .PP There are a few remaining points about qualified names @@ -396,10 +396,10 @@ by looking in only the current namespace. .PP In the following example, .CS -\fBset traceLevel 0 -namespace eval Debug { - printTrace $traceLevel -}\fR +set traceLevel 0 +\fBnamespace eval\fR Debug { + printTrace $traceLevel +} .CE Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR and then in the global namespace. @@ -408,14 +408,14 @@ If a variable or command name is not found in either context, the name is undefined. To make this point absolutely clear, consider the following example: .CS -\fBset traceLevel 0 -namespace eval Foo { - variable traceLevel 3 +set traceLevel 0 +\fBnamespace eval\fR Foo { + variable traceLevel 3 - namespace eval Debug { - printTrace $traceLevel - } -}\fR + \fBnamespace eval\fR Debug { + printTrace $traceLevel + } +} .CE Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR. Since it is not found there, Tcl then looks for it @@ -427,12 +427,12 @@ You can use the \fBnamespace which\fR command to clear up any question about name resolution. For example, the command: .CS -\fBnamespace eval Foo::Debug {namespace which \-variable traceLevel}\fR +\fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR \-variable traceLevel} .CE returns \fB::traceLevel\fR. On the other hand, the command, .CS -\fBnamespace eval Foo {namespace which \-variable traceLevel}\fR +\fBnamespace eval\fR Foo {\fBnamespace which\fR \-variable traceLevel} .CE returns \fB::Foo::traceLevel\fR. .PP @@ -472,21 +472,21 @@ For example, suppose that all of the commands in a package like BLT are contained in a namespace called \fBBlt\fR. Then you might access these commands like this: .CS -\fBBlt::graph .g \-background red -Blt::table . .g 0,0\fR +Blt::graph .g \-background red +Blt::table . .g 0,0 .CE If you use the \fBgraph\fR and \fBtable\fR commands frequently, you may want to access them without the \fBBlt::\fR prefix. You can do this by importing the commands into the current namespace, like this: .CS -\fBnamespace import Blt::*\fR +\fBnamespace import\fR Blt::* .CE This adds all exported commands from the \fBBlt\fR namespace into the current namespace context, so you can write code like this: .CS -\fBgraph .g \-background red -table . .g 0,0\fR +graph .g \-background red +table . .g 0,0 .CE The \fBnamespace import\fR command only imports commands from a namespace that that namespace exported @@ -497,7 +497,7 @@ a bad idea since you don't know what you will get. It is better to import just the specific commands you need. For example, the command .CS -\fBnamespace import Blt::graph Blt::table\fR +\fBnamespace import\fR Blt::graph Blt::table .CE imports only the \fBgraph\fR and \fBtable\fR commands into the current context. @@ -510,12 +510,12 @@ reissue the \fBnamespace import\fR command to pick up new commands that have appeared in a namespace. In that case, you can use the \fB\-force\fR option, and existing commands will be silently overwritten: .CS -\fBnamespace import \-force Blt::graph Blt::table\fR +\fBnamespace import\fR \-force Blt::graph Blt::table .CE If for some reason, you want to stop using the imported commands, you can remove them with a \fBnamespace forget\fR command, like this: .CS -\fBnamespace forget Blt::*\fR +\fBnamespace forget\fR Blt::* .CE This searches the current namespace for any commands imported from \fBBlt\fR. If it finds any, it removes them. Otherwise, it does nothing. @@ -524,41 +524,41 @@ prefix. .PP When you delete a command from the exporting namespace like this: .CS -\fBrename Blt::graph ""\fR +rename Blt::graph "" .CE the command is automatically removed from all namespaces that import it. .SH "EXPORTING COMMANDS" You can export commands from a namespace like this: .CS -\fBnamespace eval Counter { - namespace export bump reset - variable Num 0 - variable Max 100 +\fBnamespace eval\fR Counter { + \fBnamespace export\fR bump reset + variable Num 0 + variable Max 100 - proc bump {{by 1}} { - variable Num - incr Num $by - Check - return $Num - } - proc reset {} { - variable Num - set Num 0 - } - proc Check {} { - variable Num - variable Max - if {$Num > $Max} { - error "too high!" - } - } -}\fR + proc bump {{by 1}} { + variable Num + incr Num $by + Check + return $Num + } + proc reset {} { + variable Num + set Num 0 + } + proc Check {} { + variable Num + variable Max + if {$Num > $Max} { + error "too high!" + } + } +} .CE The procedures \fBbump\fR and \fBreset\fR are exported, so they are included when you import from the \fBCounter\fR namespace, like this: .CS -\fBnamespace import Counter::*\fR +\fBnamespace import\fR Counter::* .CE However, the \fBCheck\fR procedure is not exported, so it is ignored by the import operation. @@ -577,14 +577,14 @@ and traces for evaluation in the global context. For instance, the following code indicates how to direct a variable trace callback into the current namespace: .CS -namespace eval a { - variable b - proc theTraceCallback { n1 n2 op } { - upvar 1 $n1 var - puts "the value of $n1 has changed to $var" - return - } - trace variable b w [namespace code theTraceCallback] +\fBnamespace eval\fR a { + variable b + proc theTraceCallback { n1 n2 op } { + upvar 1 $n1 var + puts "the value of $n1 has changed to $var" + return + } + trace variable b w [\fBnamespace code\fR theTraceCallback] } set a::b c .CE @@ -751,16 +751,16 @@ delete its namespace. .SH EXAMPLES Create a namespace containing a variable and an exported command: .CS -namespace eval foo { +\fBnamespace eval\fR foo { variable bar 0 proc grill {} { variable bar puts "called [incr bar] times" } - namespace export grill + \fBnamespace export\fR grill } .CE - +.PP Call the command defined in the previous example in various ways. .CS # Direct call @@ -772,17 +772,17 @@ grill # Create two ensembles, one with the default name and one with a # specified name. Then call through the ensembles. -namespace eval foo { - namespace ensemble create - namespace ensemble create -command ::foobar +\fBnamespace eval\fR foo { + \fBnamespace ensemble\fR create + \fBnamespace ensemble\fR create -command ::foobar } foo grill foobar grill .CE - +.PP Look up where the command imported in the previous example came from: .CS -puts "grill came from [namespace which grill]" +puts "grill came from [\fBnamespace which\fR grill]" .CE .SH "SEE ALSO" @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: open.n,v 1.20 2004/04/26 14:38:09 dkf Exp $ +'\" RCS: @(#) $Id: open.n,v 1.21 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH open n 8.3 Tcl "Tcl Built-In Commands" @@ -403,9 +403,8 @@ information not specific to command pipelines about executing applications on the various platforms .SH "EXAMPLE" Open a command pipeline and catch any errors: - .CS -set fl [open "| ls this_file_does_not_exist"] +set fl [\fBopen\fR "| ls this_file_does_not_exist"] set data [read $fl] if {[catch {close $fl} err]} { puts "ls command failed: $err" diff --git a/doc/package.n b/doc/package.n index 2137044..1ce0b79 100644 --- a/doc/package.n +++ b/doc/package.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: package.n,v 1.8 2004/06/02 19:14:22 dgp Exp $ +'\" RCS: @(#) $Id: package.n,v 1.9 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH package n 7.5 Tcl "Tcl Built-In Commands" @@ -201,9 +201,9 @@ To test to see if the Snack package is available and load if it is the functionality is not critical) do this: .CS if {[catch {\fBpackage require\fR Snack}]} { - # We have the package, configure the app to use it + # We have the package, configure the app to use it } else { - # Set up a dummy interface to work around the absence + # Set up a dummy interface to work around the absence } .CE .PP @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: pid.n,v 1.5 2004/08/31 15:19:36 dkf Exp $ +'\" RCS: @(#) $Id: pid.n,v 1.6 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH pid n 7.0 Tcl "Tcl Built-In Commands" @@ -32,7 +32,7 @@ All process identifiers are returned as decimal strings. .SH EXAMPLE Print process information about the processes in a pipeline using the SysV \fBps\fR program before reading the output of that pipeline: - +.PP .CS set pipeline [open "| zcat somefile.gz | grep foobar | sort -u"] # Print process information @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: proc.n,v 1.4 2004/05/24 23:31:42 dkf Exp $ +'\" RCS: @(#) $Id: proc.n,v 1.5 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH proc n "" Tcl "Tcl Built-In Commands" @@ -73,20 +73,20 @@ body, then the procedure-as-a-whole will return that same error. This is a procedure that accepts arbitrarily many arguments and prints them out, one by one. .CS -proc printArguments args { - foreach arg $args { - puts $arg - } +\fBproc\fR printArguments args { + foreach arg $args { + puts $arg + } } .CE - +.PP This procedure is a bit like the \fBincr\fR command, except it multiplies the contents of the named variable by the value, which defaults to \fB2\fR: .CS -proc mult {varName {multiplier 2}} { - upvar 1 $varName var - set var [expr {$var * $multiplier}] +\fBproc\fR mult {varName {multiplier 2}} { + upvar 1 $varName var + set var [expr {$var * $multiplier}] } .CE @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: puts.n,v 1.7 2004/04/30 15:29:03 dkf Exp $ +'\" RCS: @(#) $Id: puts.n,v 1.8 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH puts n 7.5 Tcl "Tcl Built-In Commands" @@ -71,25 +71,25 @@ via a file event that the channel is ready for more output data). Write a short message to the console (or wherever \fBstdout\fR is directed): .CS -puts "Hello, World!" +\fBputs\fR "Hello, World!" .CE - +.PP Print a message in several parts: .CS -puts -nonewline "Hello, " -puts "World!" +\fBputs\fR -nonewline "Hello, " +\fBputs\fR "World!" .CE - +.PP Print a message to the standard error channel: .CS -puts stderr "Hello, World!" +\fBputs\fR stderr "Hello, World!" .CE - +.PP Append a log message to a file: .CS set chan [open my.log a] set timestamp [clock format [clock seconds]] -puts $chan "$timestamp - Hello, World!" +\fBputs\fR $chan "$timestamp - Hello, World!" close $chan .CE @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: pwd.n,v 1.5 2004/06/10 17:15:59 vasiljevic Exp $ +'\" RCS: @(#) $Id: pwd.n,v 1.6 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH pwd n "" Tcl "Tcl Built-In Commands" @@ -34,7 +34,6 @@ cd /tmp exec tar -xf $tarFile cd $savedDir .CE - .SH "SEE ALSO" file(n), cd(n), glob(n), filename(n) @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: read.n,v 1.8 2004/04/19 22:47:37 dkf Exp $ +'\" RCS: @(#) $Id: read.n,v 1.9 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH read n 8.1 Tcl "Tcl Built-In Commands" @@ -73,14 +73,12 @@ In this form \fBread\fR blocks until the reception of the end-of-file character, see \fBfconfigure -eofchar\fR. If there no end-of-file character has been configured for the channel, then \fBread\fR will block forever. - .SH "EXAMPLE" This example code reads a file all at once, and splits it into a list, with each line in the file corresponding to an element in the list: - .CS set fl [open /proc/meminfo] -set data [read $fl] +set data [\fBread\fR $fl] close $fl set lines [split $data \\n] .CE diff --git a/doc/regexp.n b/doc/regexp.n index 5f3d13e..cd3576b 100644 --- a/doc/regexp.n +++ b/doc/regexp.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: regexp.n,v 1.15 2004/05/21 23:50:26 dkf Exp $ +'\" RCS: @(#) $Id: regexp.n,v 1.16 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH regexp n 8.3 Tcl "Tcl Built-In Commands" @@ -131,27 +131,27 @@ Find the first occurrence of a word starting with \fBfoo\fR in a string that is not actually an instance of \fBfoobar\fR, and get the letters following it up to the end of the word into a variable: .CS -regexp {\\<foo(?!bar\\>)(\\w*)} $string \-> restOfWord +\fBregexp\fR {\\<foo(?!bar\\>)(\\w*)} $string \-> restOfWord .CE Note that the whole matched substring has been placed in the variable \fB\->\fR which is a name chosen to look nice given that we are not actually interested in its contents. - +.PP Find the index of the word \fBbadger\fR (in any case) within a string and store that in the variable \fBlocation\fR: .CS -regexp \-indices {(?i)\\<badger\\>} $string location +\fBregexp\fR \-indices {(?i)\\<badger\\>} $string location .CE - +.PP Count the number of octal digits in a string: .CS -regexp \-all {[0\-7]} $string +\fBregexp\fR \-all {[0\-7]} $string .CE - +.PP List all words (consisting of all sequences of non-whitespace characters) in a string: .CS -regexp \-all \-inline {\\S+} $string +\fBregexp\fR \-all \-inline {\\S+} $string .CE .SH "SEE ALSO" diff --git a/doc/registry.n b/doc/registry.n index 027ae3a..54074ce 100644 --- a/doc/registry.n +++ b/doc/registry.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: registry.n,v 1.11 2004/08/31 15:19:36 dkf Exp $ +'\" RCS: @(#) $Id: registry.n,v 1.12 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH registry n 1.1 registry "Tcl Bundled Packages" @@ -189,11 +189,11 @@ package require registry set ext .tcl # Read the type name -set type [registry get HKEY_CLASSES_ROOT\e\e$ext {}] +set type [\fBregistry get\fR HKEY_CLASSES_ROOT\e\e$ext {}] # Work out where to look for the command set path HKEY_CLASSES_ROOT\e\e$type\e\eShell\e\eOpen\e\ecommand # Read the command! -set command [registry get $path {}] +set command [\fBregistry get\fR $path {}] puts "$ext opens with $command" .CE diff --git a/doc/regsub.n b/doc/regsub.n index 1d436a3..e6738ce 100644 --- a/doc/regsub.n +++ b/doc/regsub.n @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: regsub.n,v 1.11 2004/09/01 09:50:45 dkf Exp $ +'\" RCS: @(#) $Id: regsub.n,v 1.12 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH regsub n 8.3 Tcl "Tcl Built-In Commands" @@ -118,15 +118,15 @@ of regular expressions. Replace (in the string in variable \fIstring\fR) every instance of \fBfoo\fR which is a word by itself with \fBbar\fR: .CS -regsub -all {\e<foo\e>} $string bar string +\fBregsub\fR -all {\e<foo\e>} $string bar string .CE - +.PP Insert double-quotes around the first instance of the word \fBinteresting\fR, however it is capitalised. .CS -regsub -nocase {\e<interesting\e>} $string {"&"} string +\fBregsub\fR -nocase {\e<interesting\e>} $string {"&"} string .CE - +.PP Convert all non-ASCII and Tcl-significant characters into \eu escape sequences by using \fBregsub\fR and \fBsubst\fR in combination: .CS @@ -138,7 +138,7 @@ set substitution {[format \e\e\e\eu%04x [scan "\e\e&" %c]]} # Now we apply the substitution to get a subst-string that # will perform the computational parts of the conversion. -set quoted [subst [regsub -all $RE $string $substitution]] +set quoted [subst [\fBregsub\fR -all $RE $string $substitution]] .CE .SH "SEE ALSO" diff --git a/doc/rename.n b/doc/rename.n index 96e0507..fde6d1c 100644 --- a/doc/rename.n +++ b/doc/rename.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: rename.n,v 1.4 2004/04/30 20:25:26 dkf Exp $ +'\" RCS: @(#) $Id: rename.n,v 1.5 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH rename n "" Tcl "Tcl Built-In Commands" @@ -31,9 +31,8 @@ The \fBrename\fR command returns an empty string as result. The \fBrename\fR command can be used to wrap the standard Tcl commands with your own monitoring machinery. For example, you might wish to count how often the \fBsource\fR command is called: - .CS -rename ::source ::theRealSource +\fBrename\fR ::source ::theRealSource set sourceCount 0 proc ::source args { global sourceCount diff --git a/doc/return.n b/doc/return.n index c1c09b7..e08dc05 100644 --- a/doc/return.n +++ b/doc/return.n @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: return.n,v 1.10 2004/09/18 17:01:06 dkf Exp $ +'\" RCS: @(#) $Id: return.n,v 1.11 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH return n 8.5 Tcl "Tcl Built-In Commands" @@ -37,7 +37,6 @@ evaluates the contents of a file as a script, an invocation of the \fBreturn\fR command will cause script evaluation to immediately cease, and the value \fIresult\fR (or an empty string) will be returned as the result of the \fBsource\fR command. - .SH "EXCEPTIONAL RETURN CODES" .PP In addition to the result of a procedure, the return @@ -89,7 +88,6 @@ files that are evaluated by the \fBsource\fR command. During the evaluation of the contents of a file as a script by \fBsource\fR, an invocation of the \fBreturn -code \fIcode\fR command will cause the return code of \fBsource\fR to be \fIcode\fR. - .SH "RETURN OPTIONS" .PP .VS 8.5 @@ -153,7 +151,6 @@ The value \fIoptions\fR must be a valid dictionary. The entries of that dictionary are treated as additional \fIoption value\fR pairs for the \fBreturn\fR command. .VE 8.5 - .SH "RETURN CODE HANDLING MECHANISMS" .PP Return codes are used in Tcl to control program flow. A Tcl script @@ -208,99 +205,90 @@ for the \fB-level\fR option (including the default value of 1) will cause the return code of the \fBreturn\fR command itself to be \fBTCL_RETURN\fR, triggering a return from the enclosing procedure. .VE 8.5 - .SH EXAMPLES - First, a simple example of using \fBreturn\fR to return from a procedure, interrupting the procedure body. - .CS proc printOneLine {} { - puts "line 1" ;# This line will be printed. - return - puts "line 2" ;# This line will not be printed. + puts "line 1" ;# This line will be printed. + \fBreturn\fR + puts "line 2" ;# This line will not be printed. } .CE - +.PP Next, an example of using \fBreturn\fR to set the value returned by the procedure. - .CS -proc returnX {} {return X} +proc returnX {} {\fBreturn\fR X} puts [returnX] ;# prints "X" .CE - +.PP Next, a more complete example, using \fBreturn -code error\fR to report invalid arguments. - .CS proc factorial {n} { - if {![string is integer $n] || ($n < 0)} { - return -code error \\ - "expected non-negative integer,\\ - but got \\"$n\\"" - } - if {$n < 2} { - return 1 - } - set m [expr {$n - 1}] - set code [catch {factorial $m} factor] - if {$code != 0} { - return -code $code $factor - } - set product [expr {$n * $factor}] - if {$product < 0} { - return -code error \\ - "overflow computing factorial of $n" - } - return $product + if {![string is integer $n] || ($n < 0)} { + \fBreturn\fR -code error \\ + "expected non-negative integer,\\ + but got \\"$n\\"" + } + if {$n < 2} { + \fBreturn\fR 1 + } + set m [expr {$n - 1}] + set code [catch {factorial $m} factor] + if {$code != 0} { + \fBreturn\fR -code $code $factor + } + set product [expr {$n * $factor}] + if {$product < 0} { + \fBreturn\fR -code error \\ + "overflow computing factorial of $n" + } + \fBreturn\fR $product } .CE - +.PP Next, a procedure replacement for \fBbreak\fR. - .CS proc myBreak {} { - return -code break + \fBreturn\fR -code break } .CE - +.PP .VS 8.5 With the \fB-level 0\fR option, \fBreturn\fR itself can serve as a replacement for \fBbreak\fR. - .CS -interp alias {} Break {} return -level 0 -code break +interp alias {} Break {} \fBreturn\fR -level 0 -code break .CE - +.PP An example of using \fBcatch\fR and \fBreturn -options\fR to re-raise a caught error: - .CS proc doSomething {} { - set resource [allocate] - catch { - # Long script of operations - # that might raise an error - } result options - deallocate $resource - return -options $options $result + set resource [allocate] + catch { + # Long script of operations + # that might raise an error + } result options + deallocate $resource + \fBreturn\fR -options $options $result } .CE - +.PP Finally an example of advanced use of the \fBreturn\fR options to create a procedure replacement for \fBreturn\fR itself: - .CS proc myReturn {args} { - set result "" - if {[llength $args] % 2} { - set result [lindex $args end] - set args [lrange $args 0 end-1] - } - set options [dict merge {-level 1} $args] - dict incr options -level - return -options $options $result + set result "" + if {[llength $args] % 2} { + set result [lindex $args end] + set args [lrange $args 0 end-1] + } + set options [dict merge {-level 1} $args] + dict incr options -level + \fBreturn\fR -options $options $result } .CE .VE 8.5 @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: scan.n,v 1.11 2004/05/11 09:08:49 dkf Exp $ +'\" RCS: @(#) $Id: scan.n,v 1.12 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH scan n 8.4 Tcl "Tcl Built-In Commands" @@ -212,35 +212,35 @@ Parse a simple color specification of the form \fI#RRGGBB\fR using hexadecimal conversions with field sizes: .CS set string "#08D03F" -scan $string "#%2x%2x%2x" r g b +\fBscan\fR $string "#%2x%2x%2x" r g b .CE - +.PP Parse a \fIHH:MM\fR time string, noting that this avoids problems with octal numbers by forcing interpretation as decimals (if we did not care, we would use the \fB%i\fR conversion instead): .CS set string "08:08" ;# *Not* octal! -if {[scan $string "%d:%d" hours minutes] != 2} { - error "not a valid time string" +if {[\fBscan\fR $string "%d:%d" hours minutes] != 2} { + error "not a valid time string" } # We have to understand numeric ranges ourselves... if {$minutes < 0 || $minutes > 59} { - error "invalid number of minutes" + error "invalid number of minutes" } .CE - +.PP Break a string up into sequences of non-whitespace characters (note the use of the \fB%n\fR conversion so that we get skipping over leading whitespace correct): .CS set string " a string {with braced words} + leading space " set words {} -while {[scan $string %s%n word length] == 2} { - lappend words $word - set string [string range $string $length end] +while {[\fBscan\fR $string %s%n word length] == 2} { + lappend words $word + set string [string range $string $length end] } .CE - +.PP Parse a simple coordinate string, checking that it is complete by looking for the terminating character explicitly: .CS @@ -249,7 +249,7 @@ set string "(5.2,-4e-2)" # the scan pattern are significant, and that ")" is # the Unicode character \\u0029 if { - [scan $string " (%f ,%f %c" x y last] != 3 + [\fBscan\fR $string " (%f ,%f %c" x y last] != 3 || $last != 0x0029 } then { error "invalid coordinate string" @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: seek.n,v 1.6 2004/05/17 15:16:14 dkf Exp $ +'\" RCS: @(#) $Id: seek.n,v 1.7 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH seek n 8.1 Tcl "Tcl Built-In Commands" @@ -67,19 +67,19 @@ Read a file twice: .CS set f [open file.txt] set data1 [read $f] -seek $f 0 +\fBseek\fR $f 0 set data2 [read $f] close $f # $data1 == $data2 if the file wasn't updated .CE - +.PP Read the last 10 bytes from a file: .CS set f [open file.data] # This is guaranteed to work with binary data but # may fail with other encodings... fconfigure $f -translation binary -seek $f -10 end +\fBseek\fR $f -10 end set data [read $f 10] close $f .CE @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: set.n,v 1.5 2004/05/24 19:18:05 msofer Exp $ +'\" RCS: @(#) $Id: set.n,v 1.6 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH set n "" Tcl "Tcl Built-In Commands" @@ -44,28 +44,28 @@ unless \fIvarName\fR was declared to resolve differently through one of the .SH EXAMPLES Store a random number in the variable \fIr\fR: .CS -set r [expr rand()] +\fBset\fR r [expr rand()] .CE - +.PP Store a short message in an array element: .CS -set anAry(msg) "Hello, World!" +\fBset\fR anAry(msg) "Hello, World!" .CE - +.PP Store a short message in an array element specified by a variable: .CS -set elemName "msg" -set anAry($elemName) "Hello, World!" +\fBset\fR elemName "msg" +\fBset\fR anAry($elemName) "Hello, World!" .CE - +.PP Copy a value into the variable \fIout\fR from a variable whose name is stored in the \fIvbl\fR (note that it is often easier to use arrays in practice instead of doing double-dereferencing): .CS -set in0 "small random" -set in1 "large random" -set vbl in[expr {rand() >= 0.5}] -set out [set $vbl] +\fBset\fR in0 "small random" +\fBset\fR in1 "large random" +\fBset\fR vbl in[expr {rand() >= 0.5}] +\fBset\fR out [\fBset\fR $vbl] .CE .SH "SEE ALSO" diff --git a/doc/socket.n b/doc/socket.n index 5fc5874..201fff0 100644 --- a/doc/socket.n +++ b/doc/socket.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: socket.n,v 1.11 2004/08/31 15:19:36 dkf Exp $ +'\" RCS: @(#) $Id: socket.n,v 1.12 2004/10/27 14:24:37 dkf Exp $ .so man.macros .TH socket n 8.0 Tcl "Tcl Built-In Commands" .BS @@ -36,7 +36,6 @@ will need to use \fBfconfigure\fR to alter this to something else, such as \fIutf\-8\fR (ideal for communicating with other Tcl processes) or \fIiso8859\-1\fR (useful for many network protocols, especially the older ones). - .SH "CLIENT SOCKETS" .PP If the \fB\-server\fR option is not specified, then the client side of a @@ -78,7 +77,6 @@ operation will wait until the connection is completed or fails. If the socket is in nonblocking mode and a \fBgets\fR or \fBflush\fR is done on the socket before the connection attempt succeeds or fails, the operation returns immediately and \fBfblocked\fR on the socket returns 1. - .SH "SERVER SOCKETS" .PP If the \fB\-server\fR option is specified then the new socket @@ -121,7 +119,6 @@ an unused port for use as a server socket. The port number actually allocated may be retrieved from the created server socket using the \fBfconfigure\fR command to retrieve the \fB\-sockname\fR option as described below. - .SH "CONFIGURATION OPTIONS" The \fBfconfigure\fR command can be used to query several readonly configuration options for socket channels: @@ -145,26 +142,23 @@ address, the host name and the port to which the peer socket is connected or bound. If the host name cannot be computed, the second element of the list is identical to the address, its first element. .PP - .SH "EXAMPLES" Here is a very simple time server: - .CS proc Server {channel clientaddr clientport} { - puts "Connection from $clientaddr registered" - puts $channel [clock format [clock seconds]] - close $channel + puts "Connection from $clientaddr registered" + puts $channel [clock format [clock seconds]] + close $channel } -socket -server Server 9900 +\fBsocket\fR -server Server 9900 vwait forever .CE - +.PP And here is the corresponding client to talk to the server: - .CS set server localhost -set sockChan [socket $server 9900] +set sockChan [\fBsocket\fR $server 9900] gets $sockChan line close $sockChan puts "The time on $server is $line" diff --git a/doc/source.n b/doc/source.n index c936d71..6469286 100644 --- a/doc/source.n +++ b/doc/source.n @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: source.n,v 1.9 2004/05/28 12:59:01 dkf Exp $ +'\" RCS: @(#) $Id: source.n,v 1.10 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH source n "" Tcl "Tcl Built-In Commands" @@ -50,18 +50,18 @@ is omitted, the system encoding is assumed. Run the script in the file \fBfoo.tcl\fR and then the script in the file \fBbar.tcl\fR: .CS -source foo.tcl -source bar.tcl +\fBsource\fR foo.tcl +\fBsource\fR bar.tcl .CE Alternatively: .CS foreach scriptFile {foo.tcl bar.tcl} { - source $scriptFile + \fBsource\fR $scriptFile } .CE .SH "SEE ALSO" -file(n), cd(n), encoding(n) +file(n), cd(n), encoding(n), info(n) .SH KEYWORDS file, script diff --git a/doc/split.n b/doc/split.n index f3f979c..1333716 100644 --- a/doc/split.n +++ b/doc/split.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: split.n,v 1.4 2004/05/11 21:20:22 dkf Exp $ +'\" RCS: @(#) $Id: split.n,v 1.5 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH split n "" Tcl "Tcl Built-In Commands" @@ -33,33 +33,32 @@ If \fIsplitChars\fR is an empty string then each character of .SH EXAMPLES Divide up a USENET group name into its hierarchical components: .CS -split "comp.lang.tcl.announce" . - \fB=> comp lang tcl announce\fR +\fBsplit\fR "comp.lang.tcl.announce" . + \fI=> comp lang tcl announce\fR .CE - +.PP See how the \fBsplit\fR command splits on \fIevery\fR character in \fIsplitChars\fR, which can result in information loss if you are not careful: .CS -split "alpha beta gamma" "temp" - \fB=> al {ha b} {} {a ga} {} a\fR +\fBsplit\fR "alpha beta gamma" "temp" + \fI=> al {ha b} {} {a ga} {} a\fR .CE - +.PP Extract the list words from a string that is not a well-formed list: .CS -split "Example with {unbalanced brace character" - \fB=> Example with \\{unbalanced brace character\fR +\fBsplit\fR "Example with {unbalanced brace character" + \fI=> Example with \\{unbalanced brace character\fR .CE - +.PP Split a string into its constituent characters .CS -split "Hello world" {} - \fB=> H e l l o { } w o r l d\fR +\fBsplit\fR "Hello world" {} + \fI=> H e l l o { } w o r l d\fR .CE .SS "PARSING RECORD-ORIENTED FILES" Parse a Unix /etc/passwd file, which consists of one entry per line, with each line consisting of a colon-separated list of fields: - .CS ## Read the file set fid [open /etc/passwd] @@ -67,13 +66,13 @@ set content [read $fid] close $fid ## Split into records on newlines -set records [split $content "\\n"] +set records [\fBsplit\fR $content "\\n"] ## Iterate over the records foreach rec $records { ## Split into fields on colons - set fields [split $rec ":"] + set fields [\fBsplit\fR $rec ":"] ## Assign fields to variables and print some out... lassign $fields \\ diff --git a/doc/string.n b/doc/string.n index 02e5ed2..f0f21ad 100644 --- a/doc/string.n +++ b/doc/string.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: string.n,v 1.23 2004/10/27 09:36:58 dkf Exp $ +'\" RCS: @(#) $Id: string.n,v 1.24 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH string n 8.1 Tcl "Tcl Built-In Commands" @@ -321,11 +321,11 @@ single character other than these. Test if the string in the variable \fIstring\fR is a proper non-empty prefix of the string \fBfoobar\fR. .CS -set length [\fBstring\fR length $string] +set length [\fBstring length\fR $string] if {$length == 0} { - set isPrefix 0 + set isPrefix 0 } else { - set isPrefix [\fBstring\fR equal -length $string $string "foobar"] + set isPrefix [\fBstring equal\fR -length $string $string "foobar"] } .CE diff --git a/doc/subst.n b/doc/subst.n index 829b077..7309515 100644 --- a/doc/subst.n +++ b/doc/subst.n @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: subst.n,v 1.5 2002/04/18 16:31:40 dgp Exp $ +'\" RCS: @(#) $Id: subst.n,v 1.6 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH subst n 7.4 Tcl "Tcl Built-In Commands" @@ -66,31 +66,31 @@ When it performs its substitutions, \fIsubst\fR does not give any special treatment to double quotes or curly braces (except within command substitutions) so the script .CS -\fBset a 44 -subst {xyz {$a}}\fR +set a 44 +\fBsubst\fR {xyz {$a}} .CE returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR'' .VS 8.4 and the script .CS -\fBset a "p\\} q \\{r" -subst {xyz {$a}}\fR +set a "p\\} q \\{r" +\fBsubst\fR {xyz {$a}} .CE return ``\fBxyz {p} q {r}\fR'', not ``\fBxyz {p\\} q \\{r}\fR''. .PP When command substitution is performed, it includes any variable substitution necessary to evaluate the script. .CS -\fBset a 44 -subst -novariables {$a [format $a]}\fR +set a 44 +\fBsubst\fR -novariables {$a [format $a]} .CE returns ``\fB$a 44\fR'', not ``\fB$a $a\fR''. Similarly, when variable substitution is performed, it includes any command substitution necessary to retrieve the value of the variable. .CS -\fBproc b {} {return c} +proc b {} {return c} array set a {c c [b] tricky} -subst -nocommands {[b] $a([b])}\fR +\fBsubst\fR -nocommands {[b] $a([b])} .CE returns ``\fB[b] c\fR'', not ``\fB[b] tricky\fR''. .PP @@ -99,21 +99,21 @@ prevent substitution of the rest of the command substitution and the rest of \fIstring\fR respectively, giving script authors more options when processing text using \fIsubst\fR. For example, the script .CS -\fBsubst {abc,[break],def}\fR +\fBsubst\fR {abc,[break],def} .CE returns ``\fBabc,\fR'', not ``\fBabc,,def\fR'' and the script .CS -\fBsubst {abc,[continue;expr 1+2],def}\fR +\fBsubst\fR {abc,[continue;expr 1+2],def} .CE returns ``\fBabc,,def\fR'', not ``\fBabc,3,def\fR''. .PP Other exceptional return codes substitute the returned value .CS -\fBsubst {abc,[return foo;expr 1+2],def}\fR +\fBsubst\fR {abc,[return foo;expr 1+2],def} .CE returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR'' and .CS -\fBsubst {abc,[return -code 10 foo;expr 1+2],def}\fR +\fBsubst\fR {abc,[return -code 10 foo;expr 1+2],def} .CE also returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR''. .VE diff --git a/doc/switch.n b/doc/switch.n index 3719a78..c508262 100644 --- a/doc/switch.n +++ b/doc/switch.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: switch.n,v 1.7 2004/04/22 22:36:22 dkf Exp $ +'\" RCS: @(#) $Id: switch.n,v 1.8 2004/10/27 14:24:37 dkf Exp $ '\" .so man.macros .TH switch n 7.0 Tcl "Tcl Built-In Commands" @@ -109,31 +109,30 @@ several patterns. Beware of how you place comments in \fBswitch\fR commands. Comments should only be placed \fBinside\fR the execution body of one of the patterns, and not intermingled with the patterns. - .SH "EXAMPLES" The \fBswitch\fR command can match against variables and not just literals, as shown here (the result is \fI2\fR): .CS set foo "abc" -switch abc a \- b {expr 1} $foo {expr 2} default {expr 3} +\fBswitch\fR abc a \- b {expr 1} $foo {expr 2} default {expr 3} .CE - +.PP Using glob matching and the fall-through body is an alternative to writing regular expressions with alternations, as can be seen here (this returns \fI1\fR): .CS -switch \-glob aaab { +\fBswitch\fR \-glob aaab { a*b \- b {expr 1} a* {expr 2} default {expr 3} } .CE - +.PP Whenever nothing matches, the \fBdefault\fR clause (which must be last) is taken. This example has a result of \fI3\fR: .CS -switch xyz { +\fBswitch\fR xyz { a \- b { # Correct Comment Placement @@ -147,12 +146,12 @@ switch xyz { } } .CE - +.PP .VS 8.5 When matching against regular expressions, information about what exactly matched is easily obtained using the \fB\-matchvar\fR option: .CS -switch -regexp -matchvar foo -- $bar { +\fBswitch\fR -regexp -matchvar foo -- $bar { a(b*)c { puts "Found [string length [lindex $foo 1]] 'b's" } |