diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/clock.n | 9 | ||||
| -rw-r--r-- | doc/fcopy.n | 9 | ||||
| -rw-r--r-- | doc/http.n | 8 | ||||
| -rw-r--r-- | doc/lsort.n | 14 | ||||
| -rw-r--r-- | doc/registry.n | 23 | ||||
| -rw-r--r-- | doc/safe.n | 37 | ||||
| -rw-r--r-- | doc/tcltest.n | 73 |
7 files changed, 117 insertions, 56 deletions
diff --git a/doc/clock.n b/doc/clock.n index 0493389..0f85a7d 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -191,7 +191,8 @@ 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 scan\fR {2004-10-30 05:00:00} \\ - -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] + -format {%Y-%m-%d %H:%M:%S} \\ + -timezone :America/New_York] 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] @@ -210,7 +211,8 @@ 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 scan\fR {2004-10-30 05:00:00} \\ - -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] + -format {%Y-%m-%d %H:%M:%S} \\ + -timezone :America/New_York] 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] @@ -224,7 +226,8 @@ 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 scan\fR {2004-04-03 02:30:00} \\ - -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] + -format {%Y-%m-%d %H:%M:%S} \\ + -timezone :America/New_York] 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] diff --git a/doc/fcopy.n b/doc/fcopy.n index 6513542..77135b9 100644 --- a/doc/fcopy.n +++ b/doc/fcopy.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: fcopy.n,v 1.9 2007/01/29 16:51:38 dgp Exp $ +'\" RCS: @(#) $Id: fcopy.n,v 1.10 2007/07/04 14:45:19 dkf Exp $ '\" .so man.macros .TH fcopy n 8.0 Tcl "Tcl Built-In Commands" @@ -132,15 +132,16 @@ proc CopyMore {in out chunk bytes {error {}}} { close $in close $out } else { - \fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] \\ - -size $chunk + \fBfcopy\fR $in $out -size $chunk \\ + -command [list CopyMore $in $out $chunk] } } set in [open $file1] set out [socket $server $port] set chunk 1024 set total 0 -\fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] -size $chunk +\fBfcopy\fR $in $out -size $chunk \\ + -command [list CopyMore $in $out $chunk] vwait done .DE @@ -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: http.n,v 1.24 2006/11/15 09:23:01 dkf Exp $ +'\" RCS: @(#) $Id: http.n,v 1.25 2007/07/04 14:45:19 dkf Exp $ '\" .so man.macros .TH "http" n 2.5 http "Tcl Bundled Packages" @@ -179,10 +179,12 @@ of bytes read from the socket. Here is a template for the callback: proc httpHandlerCallback {socket token} { upvar #0 $token state # Access socket, and state as a Tcl array + # For example... ... - (example: set data [read $socket 1000];set nbytes [string length $data]) + set data [read $socket 1000] + set nbytes [string length $data] ... - return nbytes + return $nbytes } .CE .RE diff --git a/doc/lsort.n b/doc/lsort.n index 09962d2..5eda016 100644 --- a/doc/lsort.n +++ b/doc/lsort.n @@ -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: lsort.n,v 1.21 2005/06/01 11:00:33 dkf Exp $ +'\" RCS: @(#) $Id: lsort.n,v 1.22 2007/07/04 14:45:19 dkf Exp $ '\" .so man.macros .TH lsort n 8.5 Tcl "Tcl Built-In Commands" @@ -83,20 +83,26 @@ each sublist For example, .RS .CS -lsort -integer -index 1 {{First 24} {Second 18} {Third 30}} +lsort -integer -index 1 \\ + {{First 24} {Second 18} {Third 30}} .CE returns \fB{Second 18} {First 24} {Third 30}\fR, and '\" '\" This example is from the test suite! '\" .CS -lsort -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}} +lsort -index end-1 \\ + {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}} .CE returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR, .VS 8.5 and .CS -lsort -index {0 1} {{{b i g} 12345} {{d e m o} 34512} {{c o d e} 54321}} +lsort -index {0 1} { + {{b i g} 12345} + {{d e m o} 34512} + {{c o d e} 54321} +} .CE returns \fB{{d e m o} 34512} {{b i g} 12345} {{c o d e} 54321}\fR (because \fBe\fR sorts before \fBi\fR which sorts before \fBo\fR.) diff --git a/doc/registry.n b/doc/registry.n index d1cb370..a3e3489 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.14 2005/05/10 18:34:03 kennykb Exp $ +'\" RCS: @(#) $Id: registry.n,v 1.15 2007/07/04 14:45:19 dkf Exp $ '\" .so man.macros .TH registry n 1.1 registry "Tcl Bundled Packages" @@ -58,12 +58,22 @@ milliseconds, to wait for applications to respond to the broadcast message. It defaults to 3000. The following example demonstrates how to add a path to the global Environment and notify applications of the change without requiring a logoff/logon step (assumes admin privileges): +.RS +.PP .CS -set regPath {HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment} -set curPath [registry get $regPath "Path"] -registry set $regPath "Path" "$curPath;$addPath" -registry broadcast "Environment" +set regPath [join { + HKEY_LOCAL_MACHINE + SYSTEM + CurrentControlSet + Control + {Session Manager} + Environment +} "\\\\"] +set curPath [\fBregistry get\fR $regPath "Path"] +\fBregistry set\fR $regPath "Path" "$curPath;$addPath" +\fBregistry broadcast\fR "Environment" .CE +.RE .TP \fBregistry delete \fIkeyName\fR ?\fIvalueName\fR? . @@ -111,7 +121,6 @@ If \fIpattern\fR isn't specified, returns a list of names of all the values of \fIkeyName\fR. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring\fR \fBmatch\fR. - .SH "SUPPORTED TYPES" Each value under a key in the registry contains some data of a particular type in a type-specific representation. The \fBregistry\fR @@ -180,6 +189,7 @@ The registry command is only available on Windows. .SH EXAMPLE Print out how double-clicking on a Tcl script file will invoke a Tcl interpreter: +.PP .CS package require registry set ext .tcl @@ -193,6 +203,5 @@ set command [\fBregistry get\fR $path {}] puts "$ext opens with $command" .CE - .SH KEYWORDS registry @@ -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: safe.n,v 1.7 2004/09/06 09:44:57 dkf Exp $ +'\" RCS: @(#) $Id: safe.n,v 1.8 2007/07/04 14:45:19 dkf Exp $ '\" .so man.macros .TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands" @@ -26,7 +26,7 @@ Safe\ Base \- A mechanism for creating and manipulating safe interpreters \fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR .sp \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? -.SH OPTIONS +.SS OPTIONS .PP ?\fB\-accessPath\fR \fIpathList\fR? ?\fB\-statics\fR \fIboolean\fR? ?\fB\-noStatics\fR? @@ -63,8 +63,7 @@ Different levels of security can be selected by using the optional flags of the commands described below. .PP All commands provided in the master interpreter by the Safe Base reside in -the \fBsafe\fR namespace: - +the \fBsafe\fR namespace. .SH COMMANDS The following commands are provided in the master interpreter: .TP @@ -95,14 +94,17 @@ safe interpreter and change each and only the provided options. See the section on \fBOPTIONS\fR below for options description. Example of use: .RS +.PP .CS -# Create a new interp with the same configuration as "$i0" : -set i1 [eval safe::interpCreate [safe::interpConfigure $i0]] +# Create new interp with the same configuration as "$i0": +set i1 [safe::interpCreate {*}[safe::interpConfigure $i0]] + # Get the current deleteHook set dh [safe::interpConfigure $i0 \-del] -# Change (only) the statics loading ok attribute of an interp -# and its deleteHook (leaving the rest unchanged) : -safe::interpConfigure $i0 \-delete {foo bar} \-statics 0 ; + +# Change (only) the statics loading ok attribute of an +# interp and its deleteHook (leaving the rest unchanged): +safe::interpConfigure $i0 \-delete {foo bar} \-statics 0 .CE .RE .TP @@ -119,8 +121,10 @@ This command finds and returns the token for the real directory It generates an error if the directory is not found. Example of use: .RS +.PP .CS -$slave eval [list set tk_library [::safe::interpFindInAccessPath $name $tk_library]] +$slave eval [list set tk_library \\ + [::safe::interpFindInAccessPath $name $tk_library]] .CE .RE .TP @@ -132,8 +136,10 @@ If the directory is already in the virtual path, it only returns the token without adding the directory to the virtual path again. Example of use: .RS +.PP .CS -$slave eval [list set tk_library [::safe::interpAddToAccessPath $name $tk_library]] +$slave eval [list set tk_library \\ + [::safe::interpAddToAccessPath $name $tk_library]] .CE .RE .TP @@ -153,13 +159,16 @@ and other events that might contain sensitive information such as real directory names. .RS Example of use: +.PP .CS ::safe::setLogCmd puts stderr .CE +.PP Below is the output of a sample session in which a safe interpreter attempted to source a file not found in its virtual access path. Note that the safe interpreter only received an error message saying that the file was not found: +.PP .CS NOTICE for slave interp10 : Created NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=() @@ -167,8 +176,7 @@ NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)} ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory .CE .RE - -.SH OPTIONS +.SS OPTIONS The following options are common to \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, and \fB::safe::interpConfigure\fR. @@ -254,7 +262,6 @@ the system encoding, but allows all other subcommands including \fBexit\fR The calling interpreter is deleted and its computation is stopped, but the Tcl process in which this interpreter exists is not terminated. - .SH SECURITY The Safe Base does not attempt to completely prevent annoyance and denial of service attacks. These forms of attack prevent the @@ -340,10 +347,8 @@ When the \fIaccessPath\fR is changed after the first creation or initialization (i.e. through \fBinterpConfigure -accessPath \fR\fIlist\fR), an \fBauto_reset\fR is automatically evaluated in the safe interpreter to synchronize its \fBauto_index\fR with the new token list. - .SH "SEE ALSO" interp(n), library(n), load(n), package(n), source(n), unknown(n) - .SH KEYWORDS alias, auto\-loading, auto_mkindex, load, master interpreter, safe interpreter, slave interpreter, source diff --git a/doc/tcltest.n b/doc/tcltest.n index e177f1e..fb3a184 100644 --- a/doc/tcltest.n +++ b/doc/tcltest.n @@ -8,7 +8,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tcltest.n,v 1.47 2007/02/20 17:54:02 dgp Exp $ +'\" RCS: @(#) $Id: tcltest.n,v 1.48 2007/07/04 14:45:19 dkf Exp $ '\" .so man.macros .TH "tcltest" n 2.3 tcltest "Tcl Bundled Packages" @@ -376,24 +376,27 @@ the expected result. Some configuration options of \fBtcltest\fR also influence how [\fBtest\fR] operates. .PP The valid options for [\fBtest\fR] are summarized: +.PP .CS -.ta 0.8i \fBtest\fR \fIname\fR \fIdescription\fR - ?-constraints \fIkeywordList|expression\fR? - ?-setup \fIsetupScript\fR? - ?-body \fItestScript\fR? - ?-cleanup \fIcleanupScript\fR? - ?-result \fIexpectedAnswer\fR? - ?-output \fIexpectedOutput\fR? - ?-errorOutput \fIexpectedError\fR? - ?-returnCodes \fIcodeList\fR? - ?-match \fImode\fR? + ?-constraints \fIkeywordList|expression\fR? + ?-setup \fIsetupScript\fR? + ?-body \fItestScript\fR? + ?-cleanup \fIcleanupScript\fR? + ?-result \fIexpectedAnswer\fR? + ?-output \fIexpectedOutput\fR? + ?-errorOutput \fIexpectedError\fR? + ?-returnCodes \fIcodeList\fR? + ?-match \fImode\fR? .CE +.PP The \fIname\fR may be any string. It is conventional to choose a \fIname\fR according to the pattern: +.PP .CS \fItarget\fR-\fImajorNum\fR.\fIminorNum\fR .CE +.PP For white-box (regression) tests, the target should be the name of the C function or Tcl procedure being tested. For black-box tests, the target should be the name of the feature being tested. Some conventions @@ -662,11 +665,13 @@ when both options [\fBconfigure -constraints\fR] and only constraints from the [\fBconfigure -constraints\fR] list are run; all others are skipped. For example, one might set up a configuration with +.PP .CS \fBconfigure\fR -constraints knownBug \e -limitconstraints true \e -verbose pass .CE +.PP to run exactly those tests that exercise known bugs, and discover whether any of them pass, indicating the bug had been fixed. .SH "RUNNING ALL TESTS" @@ -874,14 +879,19 @@ The fundamental element of a test suite is the individual [\fBtest\fR] command. We begin with several examples. .IP [1] Test of a script that returns normally. +.RS +.PP .CS \fBtest\fR example-1.0 {normal return} { format %s value } value .CE +.RE .IP [2] Test of a script that requires context setup and cleanup. Note the bracing and indenting style that avoids any need for line continuation. +.RS +.PP .CS \fBtest\fR example-1.1 {test file existence} -setup { set file [makeFile {} test] @@ -891,15 +901,21 @@ bracing and indenting style that avoids any need for line continuation. removeFile test } -result 1 .CE +.RE .IP [3] Test of a script that raises an error. +.RS +.PP .CS \fBtest\fR example-1.2 {error return} -body { error message } -returnCodes error -result message .CE +.RE .IP [4] Test with a constraint. +.RS +.PP .CS \fBtest\fR example-1.3 {user owns created files} -constraints { unix @@ -911,6 +927,7 @@ Test with a constraint. removeFile test } -result $::tcl_platform(user) .CE +.RE .PP At the next higher layer of organization, several [\fBtest\fR] commands are gathered together into a single test file. Test files should have @@ -922,23 +939,32 @@ together, keeping tests synchronized with code changes. .PP Most of the code in the test file should be the [\fBtest\fR] commands. Use constraints to skip tests, rather than conditional evaluation -of [\fBtest\fR]. That is, do this: +of [\fBtest\fR]. .IP [5] +Recommended system for writing conditional tests, using constraints to +guard: +.RS +.PP .CS \fBtestConstraint\fR X [expr $myRequirement] \fBtest\fR goodConditionalTest {} X { # body } result .CE -and do not do this: +.RE .IP [6] +Discouraged system for writing conditional tests, using \fBif\fR to +guard: +.RS +.PP .CS if $myRequirement { test badConditionalTest {} { - #body + #body } result } .CE +.RE .PP Use the \fB-setup\fR and \fB-cleanup\fR options to establish and release all context requirements of the test body. Do not make tests depend on @@ -967,6 +993,8 @@ After all [\fBtest\fR]s in a test file, the command [\fBcleanupTests\fR] should be called. .IP [7] Here is a sketch of a sample test file illustrating those points: +.RS +.PP .CS package require tcltest 2.2 eval \fB::tcltest::configure\fR $argv @@ -977,18 +1005,19 @@ namespace eval ::example::test { variable SETUP {#common setup code} variable CLEANUP {#common cleanup code} \fBtest\fR example-1 {} -setup $SETUP -body { - # First test + # First test } -cleanup $CLEANUP -result {...} \fBtest\fR example-2 {} -constraints X -setup $SETUP -body { - # Second test; constrained + # Second test; constrained } -cleanup $CLEANUP -result {...} \fBtest\fR example-3 {} { - # Third test; no context required + # Third test; no context required } {...} \fBcleanupTests\fR } namespace delete ::example::test .CE +.RE .PP The next level of organization is a full test suite, made up of several test files. One script is used to control the entire suite. The @@ -998,15 +1027,18 @@ because that's the default name used by [\fBrunAllTests\fR] when combining multiple test suites into one testing run. .IP [8] Here is a sketch of a sample test suite master script: +.RS +.PP .CS package require Tcl 8.4 package require tcltest 2.2 package require example -\fB::tcltest::configure\fR -testdir \ +\fB::tcltest::configure\fR -testdir \\ [file dirname [file normalize [info script]]] eval \fB::tcltest::configure\fR $argv \fB::tcltest::runAllTests\fR .CE +.RE .SH COMPATIBILITY .PP A number of commands and variables in the \fB::tcltest\fR namespace @@ -1022,15 +1054,18 @@ from the variable \fB::argv\fR. This is to support test suites that depend on the old behavior that \fBtcltest\fR was automatically configured from command line arguments. New test files should not depend on this, but should explicitly include +.PP .CS eval \fB::tcltest::configure\fR $::argv .CE +.PP to establish a configuration from command line arguments. .SH "KNOWN ISSUES" There are two known issues related to nested evaluations of [\fBtest\fR]. The first issue relates to the stack level in which test scripts are executed. Tests nested within other tests may be executed at the same stack level as the outermost test. For example, in the following code: +.PP .CS \fBtest\fR level-1.1 {level 1} { -body { @@ -1039,6 +1074,7 @@ stack level as the outermost test. For example, in the following code: } } .CE +.PP any script executed in level-2.1 may be executed at the same stack level as the script defined for level-1.1. .PP @@ -1060,6 +1096,5 @@ directly from C applications will not be caught by the test command. Therefore, usage of the \fB-output\fR and \fB-errorOutput\fR options to [\fBtest\fR] is useful only for pure Tcl applications that use [\fB::puts\fR] to produce output. - .SH KEYWORDS test, test harness, test suite |