From 842e3ff91428c72a2ce0d4df4889778af82f4b12 Mon Sep 17 00:00:00 2001 From: dkf Date: Fri, 17 Oct 2008 10:22:24 +0000 Subject: Improve clarity of formatting. --- ChangeLog | 12 +++-- doc/AddErrInfo.3 | 4 +- doc/CrtChannel.3 | 3 +- doc/CrtChnlHdlr.3 | 3 +- doc/CrtMathFnc.3 | 4 +- doc/Encoding.3 | 5 +- doc/GetTime.3 | 1 + doc/Hash.3 | 3 +- doc/Namespace.3 | 3 +- doc/OpenTcp.3 | 3 +- doc/ParseCmd.3 | 3 +- doc/SplitList.3 | 4 +- doc/Tcl_Main.3 | 4 +- doc/apply.n | 3 ++ doc/bgerror.n | 3 +- doc/break.n | 4 +- doc/catch.n | 3 +- doc/cd.n | 8 +-- doc/class.n | 9 ++-- doc/clock.n | 8 +++ doc/close.n | 6 +-- doc/concat.n | 14 +++-- doc/continue.n | 7 ++- doc/copy.n | 7 +-- doc/dde.n | 5 +- doc/eof.n | 8 +-- doc/error.n | 6 +-- doc/eval.n | 3 +- doc/exit.n | 6 +-- doc/expr.n | 3 +- doc/fconfigure.n | 6 ++- doc/fcopy.n | 10 ++-- doc/flush.n | 7 ++- doc/for.n | 8 +-- doc/foreach.n | 7 ++- doc/format.n | 8 ++- doc/glob.n | 159 ++++++++++++++++++++++++++++++++---------------------- doc/global.n | 8 +-- doc/http.n | 94 +++++++++++++++++++++++++++++--- doc/if.n | 13 +++-- doc/incr.n | 8 ++- doc/info.n | 4 +- doc/interp.n | 8 ++- doc/join.n | 8 +-- doc/lappend.n | 7 ++- doc/lassign.n | 11 ++-- doc/library.n | 12 ++++- doc/lindex.n | 14 ++++- doc/linsert.n | 3 +- doc/list.n | 10 +++- doc/llength.n | 10 ++-- doc/load.n | 8 ++- doc/lrange.n | 7 ++- doc/lreplace.n | 6 ++- doc/lsearch.n | 7 ++- doc/lset.n | 20 ++++++- doc/lsort.n | 23 +++++++- doc/mathop.n | 5 +- doc/memory.n | 7 ++- doc/msgcat.n | 22 +++++++- doc/my.n | 6 ++- doc/namespace.n | 51 +++++++++++++++++- doc/next.n | 6 ++- doc/object.n | 8 +-- doc/open.n | 3 +- doc/package.n | 20 ++++++- doc/prefix.n | 10 +++- doc/proc.n | 8 +-- doc/puts.n | 10 ++-- doc/pwd.n | 6 +-- doc/read.n | 12 ++--- doc/regexp.n | 12 ++++- doc/regsub.n | 7 ++- doc/rename.n | 7 ++- doc/return.n | 11 +++- doc/scan.n | 8 ++- doc/seek.n | 15 +++--- doc/self.n | 6 +-- doc/set.n | 7 ++- doc/socket.n | 17 ++++-- doc/source.n | 4 +- doc/split.n | 16 +++--- doc/string.n | 15 +++++- doc/subst.n | 21 +++++++- doc/switch.n | 7 ++- doc/tclsh.1 | 5 +- doc/tcltest.n | 5 +- doc/tell.n | 7 ++- doc/time.n | 13 +++-- doc/tm.n | 16 +++++- doc/trace.n | 17 +++++- doc/unload.n | 9 +++- doc/unset.n | 4 +- doc/update.n | 7 ++- doc/uplevel.n | 10 +++- doc/upvar.n | 11 ++-- doc/variable.n | 9 ++-- doc/vwait.n | 8 +-- doc/while.n | 8 +-- 99 files changed, 816 insertions(+), 281 deletions(-) diff --git a/ChangeLog b/ChangeLog index 47d21d2..f1e0cba 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2008-10-17 Donal K. Fellows + + * doc/*: Many very small formatting fixes. + * doc/{glob,http,if}.n: More substantial reformatting for clarity. + * doc/split.n: Remove mention of defunct c.l.t.announce + 2008-10-16 Jan Nijtmans * generic/regc_locale.c: Add "const" to many internal @@ -37,9 +43,9 @@ 2008-10-16 Don Porter * library/init.tcl: Revised [unknown] so that it carefully - preserves the state of the ::errorInfo and ::errorCode variables - at the start of auto-loading and restores that state before the - autoloaded command is evaluated. [Bug 2140628] + preserves the state of the ::errorInfo and ::errorCode variables at + the start of auto-loading and restores that state before the + autoloaded command is evaluated. [Bug 2140628] 2008-10-15 Jan Nijtmans diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index ae535d7..0de0a0f 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -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: AddErrInfo.3,v 1.22 2008/10/15 10:43:37 dkf Exp $ +'\" RCS: @(#) $Id: AddErrInfo.3,v 1.23 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures" @@ -109,6 +109,7 @@ any entries in it, with the need to check for a shared object. A typical usage for \fBTcl_GetReturnOptions\fR is to retrieve the stack trace when script evaluation returns \fBTCL_ERROR\fR, like so: +.PP .CS int code = Tcl_Eval(interp, script); if (code == TCL_ERROR) { @@ -133,6 +134,7 @@ keys in \fIoptions\fR will be returned. As an example, Tcl's \fBreturn\fR command itself could be implemented in terms of \fBTcl_SetReturnOptions\fR like so: +.PP .CS if ((objc % 2) == 0) { /* explicit result argument */ objc--; diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index 1aaf3be..c5773a1 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -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: CrtChannel.3,v 1.42 2008/10/04 12:33:34 nijtmans Exp $ +'\" RCS: @(#) $Id: CrtChannel.3,v 1.43 2008/10/17 10:22:25 dkf Exp $ .so man.macros .TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures" .BS @@ -310,6 +310,7 @@ channel drivers. See the \fBOLD CHANNEL TYPES\fR section below for details about the old structure. .PP The \fBTcl_ChannelType\fR structure contains the following fields: +.PP .CS typedef struct Tcl_ChannelType { const char *\fItypeName\fR; diff --git a/doc/CrtChnlHdlr.3 b/doc/CrtChnlHdlr.3 index 5cb6b0c..08f419e 100644 --- a/doc/CrtChnlHdlr.3 +++ b/doc/CrtChnlHdlr.3 @@ -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: CrtChnlHdlr.3,v 1.7 2008/06/29 22:28:23 dkf Exp $ +'\" RCS: @(#) $Id: CrtChnlHdlr.3,v 1.8 2008/10/17 10:22:25 dkf Exp $ .so man.macros .TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures" .BS @@ -46,6 +46,7 @@ invoked are specified by the \fImask\fR argument. See the manual entry for \fBfileevent\fR for a precise description of what it means for a channel to be readable or writable. \fIProc\fR must conform to the following prototype: +.PP .CS typedef void \fBTcl_ChannelProc\fR( ClientData \fIclientData\fR, diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3 index 3ad4a00..3f4f7c0 100644 --- a/doc/CrtMathFnc.3 +++ b/doc/CrtMathFnc.3 @@ -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: CrtMathFnc.3,v 1.18 2008/06/29 22:28:23 dkf Exp $ +'\" RCS: @(#) $Id: CrtMathFnc.3,v 1.19 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures" @@ -86,6 +86,7 @@ or any, respectively. Whenever the function is invoked in an expression Tcl will invoke \fIproc\fR. \fIProc\fR should have arguments and result that match the type \fBTcl_MathProc\fR: +.PP .CS typedef int \fBTcl_MathProc\fR( ClientData \fIclientData\fR, @@ -98,6 +99,7 @@ When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR. \fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures, which describe the actual arguments to the function: +.PP .CS typedef struct Tcl_Value { Tcl_ValueType \fItype\fR; diff --git a/doc/Encoding.3 b/doc/Encoding.3 index 5fadc44..1545c21 100644 --- a/doc/Encoding.3 +++ b/doc/Encoding.3 @@ -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.3,v 1.31 2008/10/15 10:43:37 dkf Exp $ +'\" RCS: @(#) $Id: Encoding.3,v 1.32 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures" @@ -414,6 +414,7 @@ procedure will be a non-NULL location. .PP The callback procedure \fIfreeProc\fR, if non-NULL, should match the type \fBTcl_EncodingFreeProc\fR: +.PP .CS typedef void \fBTcl_EncodingFreeProc\fR( ClientData \fIclientData\fR); @@ -490,6 +491,7 @@ Cases [1], [2], and [3] are collectively referred to as table-based encoding files. The lines in a table-based encoding file are in the same format as this example taken from the \fBshiftjis\fR encoding (this is not the complete file): +.PP .CS # Encoding file: shiftjis, multi-byte M @@ -555,6 +557,7 @@ If all characters on a page would map to 0000, that page can be omitted. Case [4] is the escape-sequence encoding file. The lines in an this type of file are in the same format as this example taken from the \fBiso2022-jp\fR encoding: +.PP .CS .ta 1.5i # Encoding file: iso2022-jp, escape-driven diff --git a/doc/GetTime.3 b/doc/GetTime.3 index a180860..6927c5e 100644 --- a/doc/GetTime.3 +++ b/doc/GetTime.3 @@ -43,6 +43,7 @@ Pointer to place the currently registered pass-through value into. The \fBTcl_GetTime\fR function retrieves the current time as a \fITcl_Time\fR structure in memory the caller provides. This structure has the following definition: +.PP .CS typedef struct Tcl_Time { long sec; diff --git a/doc/Hash.3 b/doc/Hash.3 index 13bfe3b..6e57cf3 100644 --- a/doc/Hash.3 +++ b/doc/Hash.3 @@ -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: Hash.3,v 1.29 2008/10/15 10:43:37 dkf Exp $ +'\" RCS: @(#) $Id: Hash.3,v 1.30 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" @@ -247,6 +247,7 @@ Extension writers can define new hash key types by defining four procedures, initializing a \fBTcl_HashKeyType\fR structure to describe the type, and calling \fBTcl_InitCustomHashTable\fR. The \fBTcl_HashKeyType\fR structure is defined as follows: +.PP .CS typedef struct Tcl_HashKeyType { int \fIversion\fR; diff --git a/doc/Namespace.3 b/doc/Namespace.3 index 9f78b83..629eba9 100644 --- a/doc/Namespace.3 +++ b/doc/Namespace.3 @@ -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: Namespace.3,v 1.10 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: Namespace.3,v 1.11 2008/10/17 10:22:25 dkf Exp $ '\" '\" Note that some of these functions do not seem to belong, but they '\" were all introduced with the same TIP (#139) @@ -116,6 +116,7 @@ the global namespace.) .PP \fBTcl_CreateNamespace\fR creates a new namespace. The \fIdeleteProc\fR will have the following type signature: +.PP .CS typedef void \fBTcl_NamespaceDeleteProc\fR( ClientData \fIclientData\fR); diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3 index 6dd78f6..7224ec3 100644 --- a/doc/OpenTcp.3 +++ b/doc/OpenTcp.3 @@ -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: OpenTcp.3,v 1.12 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: OpenTcp.3,v 1.13 2008/10/17 10:22:25 dkf Exp $ .so man.macros .TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures" .BS @@ -116,6 +116,7 @@ allow connections from any network interface. Each time a client connects to this socket, Tcl creates a channel for the new connection and invokes \fIproc\fR with information about the channel. \fIProc\fR must match the following prototype: +.PP .CS typedef void \fBTcl_TcpAcceptProc\fR( ClientData \fIclientData\fR, diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 index a75262e..b134a1e 100644 --- a/doc/ParseCmd.3 +++ b/doc/ParseCmd.3 @@ -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: ParseCmd.3,v 1.28 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: ParseCmd.3,v 1.29 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures" @@ -208,6 +208,7 @@ of \fBTcl_EvalTokens\fR is deprecated. \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR return parse information in two data structures, Tcl_Parse and Tcl_Token: +.PP .CS typedef struct Tcl_Parse { const char *\fIcommentStart\fR; diff --git a/doc/SplitList.3 b/doc/SplitList.3 index e70199a..73ff969 100644 --- a/doc/SplitList.3 +++ b/doc/SplitList.3 @@ -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: SplitList.3,v 1.15 2008/10/15 10:43:37 dkf Exp $ +'\" RCS: @(#) $Id: SplitList.3,v 1.16 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures" @@ -88,8 +88,8 @@ char *string; char **argv; \&... code = Tcl_SplitList(interp, string, &argc, &argv); -.PP .CE +.PP Then you should eventually free the storage with a call like the following: .PP diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3 index edbe115..462a4de 100644 --- a/doc/Tcl_Main.3 +++ b/doc/Tcl_Main.3 @@ -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: Tcl_Main.3,v 1.17 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: Tcl_Main.3,v 1.18 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures" @@ -98,6 +98,7 @@ for the application to perform its own initialization of the interpreter created by \fBTcl_Main\fR, such as defining application-specific commands. The procedure must have an interface that matches the type \fBTcl_AppInitProc\fR: +.PP .CS typedef int \fBTcl_AppInitProc\fR( Tcl_Interp *\fIinterp\fR); @@ -131,6 +132,7 @@ When the loop procedure returns in interactive mode, interactive operation will continue. The main loop procedure must have an interface that matches the type \fBTcl_MainLoopProc\fR: +.PP .CS typedef void \fBTcl_MainLoopProc\fR(void); .CE diff --git a/doc/apply.n b/doc/apply.n index 8a38aac..8fd568c 100644 --- a/doc/apply.n +++ b/doc/apply.n @@ -63,8 +63,10 @@ proc apply {fun args} { } .CE .SH EXAMPLES +.PP This shows how to make a simple general command that applies a transformation to each element of a list. +.PP .CS proc map {lambda list} { set result {} @@ -81,6 +83,7 @@ map {x {expr {$x**2 + 3*$x - 2}}} {-4 -3 -2 -1 0 1 2 3 4} .PP The \fBapply\fR command is also useful for defining callbacks for use in the \fBtrace\fR command: +.PP .CS set vbl "123abc" trace add variable vbl write {\fBapply\fR {{v1 v2 op} { diff --git a/doc/bgerror.n b/doc/bgerror.n index 5f09133..b71ed3d 100644 --- a/doc/bgerror.n +++ b/doc/bgerror.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: bgerror.n,v 1.14 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: bgerror.n,v 1.15 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH bgerror n 7.5 Tcl "Tcl Built-In Commands" @@ -77,6 +77,7 @@ have trouble integrating your code. .SH "EXAMPLE" .PP This \fBbgerror\fR procedure appends errors to a file, with a timestamp. +.PP .CS proc bgerror {message} { set timestamp [clock format [clock seconds]] diff --git a/doc/break.n b/doc/break.n index bd63b3e..77a0d97 100644 --- a/doc/break.n +++ b/doc/break.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: break.n,v 1.10 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: break.n,v 1.11 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH break n "" Tcl "Tcl Built-In Commands" @@ -30,7 +30,9 @@ Break exceptions are also handled in a few other situations, such as the \fBcatch\fR command, Tk event bindings, and the outermost scripts of procedure bodies. .SH EXAMPLE +.PP Print a line for each of the integers from 0 to 5: +.PP .CS for {set x 0} {$x<10} {incr x} { if {$x > 5} { diff --git a/doc/catch.n b/doc/catch.n index b108565..bf302ba 100644 --- a/doc/catch.n +++ b/doc/catch.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: catch.n,v 1.19 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: catch.n,v 1.20 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH catch n "8.5" Tcl "Tcl Built-In Commands" @@ -79,6 +79,7 @@ above. .PP The \fBcatch\fR command may be used in an \fBif\fR to branch based on the success of a script. +.PP .CS if { [\fBcatch\fR {open $someFile w} fid] } { puts stderr "Could not open $someFile for writing\en$fid" diff --git a/doc/cd.n b/doc/cd.n index 2a4f1b5..5968446 100644 --- a/doc/cd.n +++ b/doc/cd.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: cd.n,v 1.9 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: cd.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH cd n "" Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ cd \- Change working directory .SH SYNOPSIS \fBcd \fR?\fIdirName\fR? .BE - .SH DESCRIPTION .PP Change the current working directory to \fIdirName\fR, or to the @@ -27,19 +26,20 @@ Note that the current working directory is a per-process resource; the \fBcd\fR command changes the working directory for all interpreters and (in a threaded environment) all threads. .SH EXAMPLES +.PP Change to the home directory of the user \fBfred\fR: +.PP .CS \fBcd\fR ~fred .CE .PP Change to the directory \fBlib\fR that is a sibling directory of the current one: +.PP .CS \fBcd\fR ../lib .CE - .SH "SEE ALSO" filename(n), glob(n), pwd(n) - .SH KEYWORDS working directory diff --git a/doc/class.n b/doc/class.n index 02dfc46..ec06706 100644 --- a/doc/class.n +++ b/doc/class.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: class.n,v 1.1 2008/05/31 11:42:06 dkf Exp $ +'\" RCS: @(#) $Id: class.n,v 1.2 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH class n 0.1 TclOO "TclOO Commands" @@ -24,8 +24,8 @@ package require TclOO \(-> \fBoo::class\fR .fi .BE - .SH DESCRIPTION +.PP The \fBoo::class\fR class is the class of all classes; every class is an instance of this class, which is consequently an instance of itself. This class is a subclass of \fBoo::object\fR, so every class is also an object. @@ -34,6 +34,7 @@ by subclassing \fBoo::class\fR. Note that the \fBoo::class\fR object hides the \fBnew\fR method on itself, so new classes should always be made using the \fBcreate\fR method. .SS CONSTRUCTOR +.PP The constructor of the \fBoo::class\fR class takes an optional argument which, if present, is sent to the \fBoo::define\fR command (along with the name of the newly-created class) to allow the class to be conveniently configured at @@ -65,6 +66,7 @@ the result of this method call. Note that this method is not exported by the \fBoo::class\fR object itself, so classes should not be created using this method. .SS "NON-EXPORTED METHODS" +.PP The \fBoo::class\fR class supports the following non-exported methods: .TP \fIobj \fBcreateWithNamespace\fI name nsName\fR ?\fIarg ...\fR? @@ -79,9 +81,11 @@ internal namespace will be \fInsName\fR unless that namespace already exists (i.e. returns a non-OK result) then the object is destroyed and the error message is the result of this method call. .SH EXAMPLES +.PP This example defines a simple class hierarchy and creates a new instance of it. It then invokes a method of the object before destroying the hierarchy and showing that the destruction is transitive. +.PP .CS \fBoo::class create\fR fruit { method eat {} { @@ -119,7 +123,6 @@ $b eat \fI\(-> error "unknown command"\fR oo::define(n), oo::object(n) .SH KEYWORDS class, metaclass, object - .\" Local variables: .\" mode: nroff .\" fill-column: 78 diff --git a/doc/clock.n b/doc/clock.n index d4bb1b9..60042be 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -111,6 +111,7 @@ and their interpretation, are described under \fBFORMAT GROUPS\fR. .RS .PP On \fBclock format\fR, the default format is +.PP .CS %a %b %d %H:%M:%S %z %Y .CE @@ -195,6 +196,7 @@ absolute time means that it will add fixed amounts of time in time zones 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. +.PP .CS set s [\fBclock scan\fR {2004-10-30 05:00:00} \e -format {%Y-%m-%d %H:%M:%S} \e @@ -215,6 +217,7 @@ Adding and subtracting a given number of days across the point that 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. +.PP .CS set s [\fBclock scan\fR {2004-10-30 05:00:00} \e -format {%Y-%m-%d %H:%M:%S} \e @@ -230,6 +233,7 @@ yields an impossible time (for instance, 02:30 during the Spring 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. +.PP .CS set s [\fBclock scan\fR {2004-04-03 02:30:00} \e -format {%Y-%m-%d %H:%M:%S} \e @@ -242,6 +246,7 @@ set x [\fBclock format\fR $a \e 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. +.PP .CS 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] @@ -901,3 +906,6 @@ msgcat(n) clock, date, time .SH "COPYRIGHT" Copyright (c) 2004 Kevin B. Kenny . All rights reserved. +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/close.n b/doc/close.n index bc5fa86..800ee8a 100644 --- a/doc/close.n +++ b/doc/close.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: close.n,v 1.13 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: close.n,v 1.14 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH close n 7.5 Tcl "Tcl Built-In Commands" @@ -57,9 +57,11 @@ an error occurs while flushing output. If a command in a command pipeline created with \fBopen\fR returns an error, \fBclose\fR generates an error (similar to the \fBexec\fR command.) .SH EXAMPLE +.PP This illustrates how you can use Tcl to ensure that files get closed even when errors happen by combining \fBcatch\fR, \fBclose\fR and \fBreturn\fR: +.PP .CS proc withOpenFile {filename channelVar script} { upvar 1 $channelVar chan @@ -71,9 +73,7 @@ proc withOpenFile {filename channelVar script} { return -options $options $result } .CE - .SH "SEE ALSO" file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3) - .SH KEYWORDS blocking, channel, close, nonblocking diff --git a/doc/concat.n b/doc/concat.n index c54f662..d34d48c 100644 --- a/doc/concat.n +++ b/doc/concat.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: concat.n,v 1.11 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: concat.n,v 1.12 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH concat n 8.3 Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ concat \- Join lists together .SH SYNOPSIS \fBconcat\fI \fR?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP This command joins each of its arguments together with spaces after @@ -27,32 +26,39 @@ It permits any number of arguments; if no \fIarg\fRs are supplied, the result is an empty string. .SH EXAMPLES Although \fBconcat\fR will concatenate lists (so the command: +.PP .CS \fBconcat\fR a b {c d e} {f {g h}} .CE +.PP will return .QW "\fBa b c d e f {g h}\fR" as its result), it will also concatenate things that are not lists, and hence the command: +.PP .CS \fBconcat\fR " a b {c " d " e} f" .CE +.PP will return .QW "\fBa b {c d e} f\fR" as its result. .PP Note that the concatenation does not remove spaces from the middle of its arguments, so the command: +.PP .CS \fBconcat\fR "a b c" { d e f } .CE +.PP will return .QW "\fBa b c d e f\fR" (i.e. with three spaces between the \fBa\fR, the \fBb\fR and the \fBc\fR). - .SH "SEE ALSO" append(n), eval(n) - .SH KEYWORDS concatenate, join, lists +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/continue.n b/doc/continue.n index ce7dc52..e98763c 100644 --- a/doc/continue.n +++ b/doc/continue.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: continue.n,v 1.10 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: continue.n,v 1.11 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH continue n "" Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ continue \- Skip to the next iteration of a loop .SH SYNOPSIS \fBcontinue\fR .BE - .SH DESCRIPTION .PP This command is typically invoked inside the body of a looping command @@ -30,7 +29,9 @@ Catch exceptions are also handled in a few other situations, such as the \fBcatch\fR command and the outermost scripts of procedure bodies. .SH EXAMPLE +.PP Print a line for each of the integers from 0 to 10 \fIexcept\fR 5: +.PP .CS for {set x 0} {$x<10} {incr x} { if {$x == 5} { @@ -39,9 +40,7 @@ for {set x 0} {$x<10} {incr x} { puts "x is $x" } .CE - .SH "SEE ALSO" break(n), for(n), foreach(n), return(n), while(n) - .SH KEYWORDS continue, iteration, loop diff --git a/doc/copy.n b/doc/copy.n index 291d2fc..023a281 100644 --- a/doc/copy.n +++ b/doc/copy.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: copy.n,v 1.1 2008/05/31 11:42:12 dkf Exp $ +'\" RCS: @(#) $Id: copy.n,v 1.2 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH copy n 0.1 TclOO "TclOO Commands" @@ -19,8 +19,8 @@ package require TclOO \fBoo::copy\fI sourceObject \fR?\fItargetObject\fR? .fi .BE - .SH DESCRIPTION +.PP The \fBoo::copy\fR command creates a copy of an object or class. It takes the name of the object or class to be copied, \fIsourceObject\fR, and optionally the name of the object or class to create, \fItargetObject\fR, which will be @@ -33,8 +33,10 @@ contents of the source object's private namespace \fIwill not\fR be copied; it is up to the caller to do this. The result of this command will be the fully-qualified name of the new object or class. .SH EXAMPLES +.PP This example creates an object, copies it, modifies the source object, and then demonstrates that the copied object is indeed a copy. +.PP .CS oo::object create src oo::define src method msg {} {puts foo} @@ -47,7 +49,6 @@ dst msg \fI\(-> prints "foo"\fR oo::class(n), oo::define(n), oo::object(n) .SH KEYWORDS clone, copy, duplication, object - .\" Local variables: .\" mode: nroff .\" fill-column: 78 diff --git a/doc/dde.n b/doc/dde.n index d5a6e78..7859de1 100644 --- a/doc/dde.n +++ b/doc/dde.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: dde.n,v 1.24 2008/01/18 15:59:22 dkf Exp $ +'\" RCS: @(#) $Id: dde.n,v 1.25 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH dde n 1.3 dde "Tcl Bundled Packages" @@ -125,6 +125,7 @@ command returns an error message if the script did not run, unless the \fB\-async\fR flag was used, in which case the command returns immediately with no error. This command can be used to replace send on Windows. .SH "DDE AND TCL" +.PP A Tcl interpreter always has a service name of \fBTclEval\fR. Each different interpreter of all running Tcl applications must be given a unique @@ -157,8 +158,10 @@ If for any reason the event queue is not flushed, DDE commands may hang until the event queue is flushed. This can create a deadlock situation. .SH EXAMPLE +.PP This asks Internet Explorer (which must already be running) to go to a particularly important website: +.PP .CS package require dde \fBdde execute\fR iexplore WWW_OpenURL http://www.tcl.tk/ diff --git a/doc/eof.n b/doc/eof.n index 4601f82..bf492bc 100644 --- a/doc/eof.n +++ b/doc/eof.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: eof.n,v 1.9 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: eof.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH eof n 7.5 Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ eof \- Check for end of file condition on channel .SH SYNOPSIS \fBeof \fIchannelId\fR .BE - .SH DESCRIPTION .PP Returns 1 if an end of file condition occurred during the most @@ -28,7 +27,9 @@ Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), the return value from an invocation of \fBopen\fR or \fBsocket\fR, or the result of a channel creation command provided by a Tcl extension. .SH EXAMPLES +.PP Read and print out the contents of a file line-by-line: +.PP .CS set f [open somefile.txt] while {1} { @@ -42,6 +43,7 @@ while {1} { .CE .PP Read and print out the contents of a file by fixed-size records: +.PP .CS set f [open somefile.dat] fconfigure $f -translation binary @@ -55,9 +57,7 @@ while {1} { puts "Read record: $record" } .CE - .SH "SEE ALSO" file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3) - .SH KEYWORDS channel, end of file diff --git a/doc/error.n b/doc/error.n index 5c81878..2ac0a65 100644 --- a/doc/error.n +++ b/doc/error.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: error.n,v 1.12 2008/10/15 10:43:37 dkf Exp $ +'\" RCS: @(#) $Id: error.n,v 1.13 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH error n "" Tcl "Tcl Built-In Commands" @@ -63,15 +63,15 @@ of the error in cases where such information is available; see the \fBreturn\fR manual page for information on the proper format for this option's value. .SH EXAMPLE +.PP Generate an error if a basic mathematical operation fails: +.PP .CS if {1+2 != 3} { \fBerror\fR "something is very wrong with addition" } .CE - .SH "SEE ALSO" catch(n), return(n) - .SH KEYWORDS error diff --git a/doc/eval.n b/doc/eval.n index 1f32697..47a8aee 100644 --- a/doc/eval.n +++ b/doc/eval.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: eval.n,v 1.12 2008/10/15 10:43:37 dkf Exp $ +'\" RCS: @(#) $Id: eval.n,v 1.13 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH eval n "" Tcl "Tcl Built-In Commands" @@ -72,6 +72,7 @@ proc lprepend {varName args} { .PP However, the last line would now normally be written without \fBeval\fR, like this: +.PP .CS set var [linsert $var 0 {*}$args] .CE diff --git a/doc/exit.n b/doc/exit.n index 9feb3ff..6fdc8eb 100644 --- a/doc/exit.n +++ b/doc/exit.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: exit.n,v 1.9 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: exit.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH exit n "" Tcl "Tcl Built-In Commands" @@ -24,10 +24,12 @@ system as the exit status. If \fIreturnCode\fR is not specified then it defaults to 0. .SH EXAMPLE +.PP Since non-zero exit codes are usually interpreted as error cases by the calling process, the \fBexit\fR command is an important part of signaling that something fatal has gone wrong. This code fragment is useful in scripts to act as a general problem trap: +.PP .CS proc main {} { # ... put the real main code in here ... @@ -45,9 +47,7 @@ if {[catch {main} msg options]} { \fBexit\fR 2 } .CE - .SH "SEE ALSO" exec(n) - .SH KEYWORDS exit, process diff --git a/doc/expr.n b/doc/expr.n index b078873..b3c80cc 100644 --- a/doc/expr.n +++ b/doc/expr.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: expr.n,v 1.36 2008/10/15 10:43:37 dkf Exp $ +'\" RCS: @(#) $Id: expr.n,v 1.37 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH expr n 8.5 Tcl "Tcl Built-In Commands" @@ -105,6 +105,7 @@ For some examples of simple expressions, suppose the variable the variable \fBb\fR has the value 6. Then the command on the left side of each of the lines below will produce the value on the right side of the line: +.PP .CS .ta 6c \fBexpr\fR 3.1 + $a \fI6.1\fR diff --git a/doc/fconfigure.n b/doc/fconfigure.n index 6df3037..610c898 100644 --- a/doc/fconfigure.n +++ b/doc/fconfigure.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: fconfigure.n,v 1.21 2008/10/14 14:02:55 dkf Exp $ +'\" RCS: @(#) $Id: fconfigure.n,v 1.22 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH fconfigure n 8.3 Tcl "Tcl Built-In Commands" @@ -216,14 +216,17 @@ If, for example, a Tcl application is started by the \fBinet\fR super-server common on Unix system its Tcl standard channels will be sockets and thus support the socket options. .SH EXAMPLES +.PP Instruct Tcl to always send output to \fBstdout\fR immediately, whether or not it is to a terminal: +.PP .CS \fBfconfigure\fR stdout -buffering none .CE .PP Open a socket and read lines from it without ever blocking the processing of other events: +.PP .CS set s [socket some.where.com 12345] \fBfconfigure\fR $s -blocking 0 @@ -244,6 +247,7 @@ proc readMe chan { .CE .PP Read a PPM-format image from a file: +.PP .CS # Open the file and put it into Unix ASCII mode set f [open teapot.ppm] diff --git a/doc/fcopy.n b/doc/fcopy.n index 2aa5276..c4eaae2 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.17 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: fcopy.n,v 1.18 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH fcopy n 8.0 Tcl "Tcl Built-In Commands" @@ -92,13 +92,13 @@ the system will assume that the incoming bytes are valid UTF-8 characters and convert them according to the output encoding. The behaviour of the system for bytes which are not valid UTF-8 characters is undefined in this case. - .SH EXAMPLES .PP The first example transfers the contents of one channel exactly to another. Note that when copying one file to another, it is better to use \fBfile copy\fR which also copies file metadata (e.g. the file access permissions) where possible. +.PP .CS fconfigure $in -translation binary fconfigure $out -translation binary @@ -110,6 +110,7 @@ passed the number of bytes transferred. It also uses vwait to put the application into the event loop. Of course, this simplified example could be done without the command callback. +.PP .CS proc Cleanup {in out bytes {error {}}} { global total @@ -127,7 +128,8 @@ vwait total .CE .PP The third example copies in chunks and tests for end of file -in the command callback +in the command callback. +.PP .CS proc CopyMore {in out chunk bytes {error {}}} { global total done @@ -149,9 +151,7 @@ set total 0 -command [list CopyMore $in $out $chunk] vwait done .CE - .SH "SEE ALSO" eof(n), fblocked(n), fconfigure(n), file(n) - .SH KEYWORDS blocking, channel, end of line, end of file, nonblocking, read, translation diff --git a/doc/flush.n b/doc/flush.n index 8ee4870..288b8fc 100644 --- a/doc/flush.n +++ b/doc/flush.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: flush.n,v 1.8 2005/05/10 18:34:00 kennykb Exp $ +'\" RCS: @(#) $Id: flush.n,v 1.9 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH flush n 7.5 Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ flush \- Flush buffered output for a channel .SH SYNOPSIS \fBflush \fIchannelId\fR .BE - .SH DESCRIPTION .PP Flushes any output that has been buffered for \fIchannelId\fR. @@ -33,16 +32,16 @@ nonblocking mode, the command may return before all buffered output has been flushed; the remainder will be flushed in the background as fast as the underlying file or device is able to absorb it. .SH EXAMPLE +.PP Prompt for the user to type some information in on the console: +.PP .CS puts -nonewline "Please type your name: " \fBflush\fR stdout gets stdin name puts "Hello there, $name!" .CE - .SH "SEE ALSO" file(n), open(n), socket(n), Tcl_StandardChannels(3) - .SH KEYWORDS blocking, buffer, channel, flush, nonblocking, output diff --git a/doc/for.n b/doc/for.n index 5999683..1931538 100644 --- a/doc/for.n +++ b/doc/for.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: for.n,v 1.9 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: for.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH for n "" Tcl "Tcl Built-In Commands" @@ -50,7 +50,9 @@ expression is evaluated (before each loop iteration), so changes in the variables will be visible. See below for an example: .SH EXAMPLES +.PP Print a line for each of the integers from 0 to 10: +.PP .CS for {set x 0} {$x<10} {incr x} { puts "x is $x" @@ -64,6 +66,7 @@ before the \fBfor\fR command is run and whether its value is a value that is less than or greater than/equal to ten, and this is because the expression will be substituted before the \fBfor\fR command is executed. +.PP .CS for {set x 0} $x<10 {incr x} { puts "x is $x" @@ -71,14 +74,13 @@ for {set x 0} $x<10 {incr x} { .CE .PP Print out the powers of two from 1 to 1024: +.PP .CS for {set x 1} {$x<=1024} {set x [expr {$x * 2}]} { puts "x is $x" } .CE - .SH "SEE ALSO" break, continue, foreach, while - .SH KEYWORDS for, iteration, looping diff --git a/doc/foreach.n b/doc/foreach.n index 949db4c..47488c7 100644 --- a/doc/foreach.n +++ b/doc/foreach.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: foreach.n,v 1.10 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: foreach.n,v 1.11 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH foreach n "" Tcl "Tcl Built-In Commands" @@ -51,8 +51,10 @@ The \fBbreak\fR and \fBcontinue\fR statements may be invoked inside \fIbody\fR, with the same effect as in the \fBfor\fR command. \fBForeach\fR returns an empty string. .SH EXAMPLES +.PP This loop prints every value in a list together with the square and cube of the value: +.PP .CS '\" Maintainers: notice the tab hacking below! .ta 3i @@ -65,6 +67,7 @@ puts "Value\etSquare\etCube" ;# Neat-looking header .PP The following loop uses i and j as loop variables to iterate over pairs of elements of a single list. +.PP .CS set x {} \fBforeach\fR {i j} {a b c d e f} { @@ -75,6 +78,7 @@ set x {} .CE .PP The next loop uses i and j to iterate over two lists in parallel. +.PP .CS set x {} \fBforeach\fR i {a b c} j {d e f g} { @@ -85,6 +89,7 @@ set x {} .CE .PP The two forms are combined in the following example. +.PP .CS set x {} \fBforeach\fR i {a b c} {j k} {d e f g} { diff --git a/doc/format.n b/doc/format.n index 1b5a44c..dab6b8b 100644 --- a/doc/format.n +++ b/doc/format.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: format.n,v 1.20 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: format.n,v 1.21 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH format n 8.1 Tcl "Tcl Built-In Commands" @@ -204,8 +204,10 @@ which will then be converted to the corresponding character value. The size modifiers are ignored when formatting floating-point values. The \fBll\fR modifier has no \fBsprintf\fR counterpart. .SH EXAMPLES +.PP Convert the numeric value of a UNICODE character to the character itself: +.PP .CS set value 120 set char [\fBformat\fR %c $value] @@ -213,12 +215,14 @@ set char [\fBformat\fR %c $value] .PP Convert the output of \fBtime\fR into seconds to an accuracy of hundredths of a second: +.PP .CS set us [lindex [time $someTclCode] 0] puts [\fBformat\fR "%.2f seconds to execute" [expr {$us / 1e6}]] .CE .PP Create a packed X11 literal color specification: +.PP .CS # Each color-component should be in range (0..255) set color [\fBformat\fR "#%02x%02x%02x" $r $g $b] @@ -227,6 +231,7 @@ set color [\fBformat\fR "#%02x%02x%02x" $r $g $b] Use XPG3 format codes to allow reordering of fields (a technique that is often used in localized message catalogs; see \fBmsgcat\fR) without reordering the data values passed to \fBformat\fR: +.PP .CS set fmt1 "Today, %d shares in %s were bought at $%.2f each" puts [\fBformat\fR $fmt1 123 "Global BigCorp" 19.37] @@ -236,6 +241,7 @@ puts [\fBformat\fR $fmt2 123 "Global BigCorp" 19.37] .CE .PP Print a small table of powers of three: +.PP .CS # Set up the column widths set w1 5 diff --git a/doc/glob.n b/doc/glob.n index e254e6d..101fee5 100644 --- a/doc/glob.n +++ b/doc/glob.n @@ -4,9 +4,9 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: glob.n,v 1.24 2008/10/15 10:43:37 dkf Exp $ -'\" +'\" +'\" RCS: @(#) $Id: glob.n,v 1.25 2008/10/17 10:22:25 dkf Exp $ +'\" .so man.macros .TH glob n 8.3 Tcl "Tcl Built-In Commands" .BS @@ -16,60 +16,71 @@ glob \- Return names of files that match patterns .SH SYNOPSIS \fBglob \fR?\fIswitches\fR? ?\fIpattern ...\fR? .BE - .SH DESCRIPTION .PP This command performs file name .QW globbing in a fashion similar to -the csh shell. It returns a list of the files whose names match any -of the \fIpattern\fR arguments. No particular order is guaranteed -in the list, so if a sorted list is required the caller should use +the csh shell or bash shell. +It returns a list of the files whose names match any +of the \fIpattern\fR arguments. No particular order is guaranteed +in the list, so if a sorted list is required the caller should use \fBlsort\fR. -.LP +.SS OPTIONS +.PP If the initial arguments to \fBglob\fR start with \fB\-\fR then -they are treated as switches. The following switches are +they are treated as switches. The following switches are currently supported: .TP \fB\-directory\fR \fIdirectory\fR +. Search for files which match the given patterns starting in the given -\fIdirectory\fR. This allows searching of directories whose name +\fIdirectory\fR. This allows searching of directories whose name contains glob-sensitive characters without the need to quote such -characters explicitly. This option may not be used in conjunction with +characters explicitly. This option may not be used in conjunction with \fB\-path\fR, which is used to allow searching for complete file paths whose names may contain glob-sensitive characters. .TP \fB\-join\fR +. The remaining pattern arguments are treated as a single pattern obtained by joining the arguments with directory separators. .TP \fB\-nocomplain\fR -Allows an empty list to be returned without error; without this +. +Allows an empty list to be returned without error; without this switch an error is returned if the result list would be empty. .TP \fB\-path\fR \fIpathPrefix\fR +. Search for files with the given \fIpathPrefix\fR where the rest of the name -matches the given patterns. This allows searching for files with names -similar to a given file (as opposed to a directory) even when the names -contain glob-sensitive -characters. This option may not be used in conjunction with -\fB\-directory\fR. For example, to find all files with the same root name -as $path, but differing extensions, you should use \fBglob --path [file rootname $path] .*\fR which will work even if $path contains +matches the given patterns. This allows searching for files with names +similar to a given file (as opposed to a directory) even when the names +contain glob-sensitive +characters. This option may not be used in conjunction with +\fB\-directory\fR. For example, to find all files with the same root name +as $path, but differing extensions, you should use +.QW "\fBglob \-path [file rootname $path] .*\fR" +which will work even if \fB$path\fR contains numerous glob-sensitive characters. .TP \fB\-tails\fR +. Only return the part of each file found which follows the last directory -named in any \fB\-directory\fR or \fB\-path\fR path specification. -Thus \fBglob -tails -directory $dir *\fR is equivalent to -\fBset pwd [pwd] ; cd $dir ; glob *; cd $pwd\fR. For -\fB\-path\fR specifications, the returned names will include the last -path segment, so \fBglob -tails -path [file rootname ~/foo.tex] .*\fR +named in any \fB\-directory\fR or \fB\-path\fR path specification. +Thus +.QW "\fBglob \-tails \-directory $dir *\fR" +is equivalent to +.QW "\fBset pwd [pwd]; cd $dir; glob *; cd $pwd\fR" . +For \fB\-path\fR specifications, the returned names will include the last +path segment, so +.QW "\fBglob \-tails \-path [file rootname ~/foo.tex] .*\fR" will return paths like \fBfoo.aux foo.bib foo.tex\fR etc. .TP \fB\-types\fR \fItypeList\fR +. Only list files or directories which match \fItypeList\fR, where the items -in the list have two forms. The first form is like the \-type option of +in the list have two forms. The first form is like the \-type option of the Unix find command: \fIb\fR (block special file), \fIc\fR (character special file), @@ -79,31 +90,29 @@ the Unix find command: \fIp\fR (named pipe), or \fIs\fR (socket), where multiple types may be specified in the list. \fBGlob\fR will return all files which match at least one of the types given. -Note that symbolic links will be returned both if \fB\-types l\fR is given, -or if the target of a link matches the requested type. So, a link to +Note that symbolic links will be returned both if \fB\-types l\fR is given, +or if the target of a link matches the requested type. So, a link to a directory will be returned if \fB\-types d\fR was specified. .RS .PP The second form specifies types where all the types given must match. These are \fIr\fR, \fIw\fR, \fIx\fR as file permissions, and -\fIreadonly\fR, \fIhidden\fR as special permission cases. On the +\fIreadonly\fR, \fIhidden\fR as special permission cases. On the Macintosh, MacOS types and creators are also supported, where any item which is four characters long is assumed to be a MacOS type -(e.g. \fBTEXT\fR). Items which are of the form \fI{macintosh type XXXX}\fR +(e.g. \fBTEXT\fR). Items which are of the form \fI{macintosh type XXXX}\fR or \fI{macintosh creator XXXX}\fR will match types or creators -respectively. Unrecognized types, or specifications of multiple MacOS +respectively. Unrecognized types, or specifications of multiple MacOS types/creators will signal an error. .PP The two forms may be mixed, so \fB\-types {d f r w}\fR will find all regular files OR directories that have both read AND write permissions. The following are equivalent: -.RS .PP .CS \fBglob \-type d *\fR \fBglob */\fR .CE -.RE .PP except that the first case doesn't return the trailing .QW / @@ -111,45 +120,53 @@ and is more platform independent. .RE .TP \fB\-\|\-\fR -Marks the end of switches. The argument following this one will +. +Marks the end of switches. The argument following this one will be treated as a \fIpattern\fR even if it starts with a \fB\-\fR. +.SS "GLOBBING PATTERNS" .PP The \fIpattern\fR arguments may contain any of the following -special characters: +special characters, which are a superset of those supported by +\fBstring match\fR: .TP 10 \fB?\fR +. Matches any single character. .TP 10 \fB*\fR +. Matches any sequence of zero or more characters. .TP 10 \fB[\fIchars\fB]\fR -Matches any single character in \fIchars\fR. If \fIchars\fR +. +Matches any single character in \fIchars\fR. If \fIchars\fR contains a sequence of the form \fIa\fB\-\fIb\fR then any character between \fIa\fR and \fIb\fR (inclusive) will match. .TP 10 \fB\e\fIx\fR +. Matches the character \fIx\fR. .TP 10 \fB{\fIa\fB,\fIb\fB,\fI...\fR} -Matches any of the strings \fIa\fR, \fIb\fR, etc. -.LP +. +Matches any of the sub-patterns \fIa\fR, \fIb\fR, etc. +.PP On Unix, as with csh, a -.QW . +.QW . \| at the beginning of a file's name or just after a .QW / must be matched explicitly or with a {} construct, unless the \fB\-types hidden\fR flag is given (since -.QW . -at the beginning of a file's name indicates that it is hidden). On +.QW . \| +at the beginning of a file's name indicates that it is hidden). On other platforms, files beginning with a -.QW . +.QW . \| are handled no differently to any others, except the special directories -.QW . +.QW . \| and -.QW .. +.QW .. \| which must be matched explicitly (this is to avoid a recursive pattern like -.QW "glob -join * * * *" +.QW "glob \-join * * * *" from recursing up the directory hierarchy as well as down). In addition, all .QW / characters must be matched explicitly. @@ -163,50 +180,61 @@ If the is followed immediately by .QW / then the value of the HOME environment variable is used. -.LP +.PP The \fBglob\fR command differs from csh globbing in two ways. First, it does not sort its result list (use the \fBlsort\fR command if you want the list sorted). Second, \fBglob\fR only returns the names of files that actually -exist; in csh no check for existence is made unless a pattern +exist; in csh no check for existence is made unless a pattern contains a ?, *, or [] construct. .LP When the \fBglob\fR command returns relative paths whose filenames start with a tilde .QW ~ -(for example through \fBglob *\fR or \fBglob -tails\fR, the returned +(for example through \fBglob *\fR or \fBglob \-tails\fR, the returned list will not quote the tilde with .QW ./ . This means care must be taken if those names are later to be used with \fBfile join\fR, to avoid them being interpreted as absolute paths pointing to a given user's home directory. -.SH "PORTABILITY ISSUES" +.SH "WINDOWS PORTABILITY ISSUES" .PP -\fBWindows\fR -. For Windows UNC names, the servername and sharename components of the path -may not contain ?, *, or [] constructs. On Windows NT, if \fIpattern\fR is +may not contain ?, *, or [] constructs. On Windows NT, if \fIpattern\fR is of the form .QW \fB~\fIusername\fB@\fIdomain\fR , it refers to the home directory of the user whose account information resides on the specified NT -domain server. Otherwise, user account information is obtained from -the local computer. On Windows 95 and 98, \fBglob\fR accepts patterns +domain server. Otherwise, user account information is obtained from +the local computer. On Windows 95 and 98, \fBglob\fR accepted patterns like .QW .../ and .QW ..../ -for successively higher up parent directories. -.PP -Since the backslash character has a special meaning to the glob -command, glob patterns containing Windows style path separators need -special care. The pattern \fIC:\e\efoo\e\e*\fR is interpreted as -\fIC:\efoo\e*\fR where \fI\ef\fR will match the single character \fIf\fR -and \fI\e*\fR will match the single character \fI*\fR and will not be -interpreted as a wildcard character. One solution to this problem is -to use the Unix style forward slash as a path separator. Windows style -paths can be converted to Unix style paths with the command \fBfile -join $path\fR (or \fBfile normalize $path\fR in Tcl 8.4). +for successively higher up parent directories, but later versions of +Windows do not accept these forms. +.PP +Since the backslash character has a special meaning to the glob +command, glob patterns containing Windows style path separators need +special care. The pattern +.QW \fIC:\e\efoo\e\e*\fR +is interpreted as +.QW \fIC:\efoo\e*\fR +where +.QW \fI\ef\fR +will match the single character +.QW \fIf\fR +and +.QW \fI\e*\fR +will match the single character +.QW \fI*\fR +and will not be +interpreted as a wildcard character. One solution to this problem is +to use the Unix style forward slash as a path separator. Windows style +paths can be converted to Unix style paths with the command +.QW "\fBfile join $path\fR" +or +.QW "\fBfile normalize $path\fR" . .SH EXAMPLES .PP Find all the Tcl files in the current directory: @@ -242,3 +270,6 @@ or the sequence file(n) .SH KEYWORDS exist, file, glob, pattern +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/global.n b/doc/global.n index bcf4391..5ccf587 100644 --- a/doc/global.n +++ b/doc/global.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: global.n,v 1.13 2008/09/25 19:26:36 dgp Exp $ +'\" RCS: @(#) $Id: global.n,v 1.14 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH global n "" Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ global \- Access global variables .SH SYNOPSIS \fBglobal \fR?\fIvarname ...\fR? .BE - .SH DESCRIPTION .PP This command has no effect unless executed in the context of a proc body. @@ -33,7 +32,9 @@ the unqualified name of the global variable, as determined by the array element. An error is returned if the name looks like an array element, such as \fBa(b)\fR. .SH EXAMPLES +.PP This procedure sets the namespace variable \fI::a::x\fR +.PP .CS proc reset {} { \fBglobal\fR a::x @@ -46,15 +47,14 @@ buffer, separated by newlines. It is useful for situations when you want to build a message piece-by-piece (as if with \fBputs\fR) but send that full message in a single piece (e.g. over a connection opened with \fBsocket\fR or as part of a counted HTTP response). +.PP .CS proc accum {string} { \fBglobal\fR accumulator append accumulator $string \en } .CE - .SH "SEE ALSO" namespace(n), upvar(n), variable(n) - .SH KEYWORDS global, namespace, procedure, variable diff --git a/doc/http.n b/doc/http.n index 6cfb7cb..0c533b8 100644 --- a/doc/http.n +++ b/doc/http.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: http.n,v 1.37 2008/07/13 23:15:23 nijtmans Exp $ +'\" RCS: @(#) $Id: http.n,v 1.38 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH "http" n 2.7 http "Tcl Bundled Packages" @@ -78,6 +78,7 @@ applications, the caller can use \fB::http::wait\fR after calling .SH COMMANDS .TP \fB::http::config\fR ?\fIoptions\fR? +. The \fB::http::config\fR command is used to set and query the name of the proxy server and port, and the User-Agent name used in the HTTP requests. If no options are specified, then the current configuration @@ -88,6 +89,7 @@ flags and values that define the configuration: .RS .TP \fB\-accept\fR \fImimetypes\fR +. The Accept header of the request. The default is */*, which means that all types of documents are accepted. Otherwise you can supply a comma-separated list of mime type patterns that you are @@ -95,13 +97,16 @@ willing to receive. For example, .QW "image/gif, image/jpeg, text/*" . .TP \fB\-proxyhost\fR \fIhostname\fR +. The name of the proxy host, if any. If this value is the empty string, the URL host is contacted directly. .TP \fB\-proxyport\fR \fInumber\fR +. The proxy port number. .TP \fB\-proxyfilter\fR \fIcommand\fR +. The command is a callback that is made during \fB::http::geturl\fR to determine if a proxy is required for a given host. One argument, a @@ -113,6 +118,7 @@ an empty list. The default filter returns the values of the non-empty. .TP \fB\-urlencoding\fR \fIencoding\fR +. The \fIencoding\fR used for creating the x-url-encoded URLs with \fB::http::formatQuery\fR. The default is \fButf-8\fR, as specified by RFC 2718. Prior to http 2.5 this was unspecified, and that behavior can be @@ -122,11 +128,13 @@ returned by specifying the empty string (\fB{}\fR), although characters. .TP \fB\-useragent\fR \fIstring\fR +. The value of the User-Agent header in the HTTP request. The default is .QW "\fBTcl http client package 2.7\fR" . .RE .TP \fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR? +. The \fB::http::geturl\fR command is the main procedure in the package. The \fB\-query\fR option causes a POST operation and the \fB\-validate\fR option causes a HEAD operation; @@ -141,21 +149,25 @@ that is invoked when the HTTP transaction completes. .RS .TP \fB\-binary\fR \fIboolean\fR +. Specifies whether to force interpreting the URL data as binary. Normally this is auto-detected (anything not beginning with a \fBtext\fR content type or whose content encoding is \fBgzip\fR or \fBcompress\fR is considered binary data). .TP \fB\-blocksize\fR \fIsize\fR +. The block size used when reading the URL. At most \fIsize\fR bytes are read at once. After each block, a call to the \fB\-progress\fR callback is made (if that option is specified). .TP \fB\-channel\fR \fIname\fR +. Copy the URL contents to channel \fIname\fR instead of saving it in \fBstate(body)\fR. .TP \fB\-command\fR \fIcallback\fR +. Invoke \fIcallback\fR after the HTTP transaction completes. This option causes \fB::http::geturl\fR to return immediately. The \fIcallback\fR gets an additional argument that is the \fItoken\fR returned @@ -163,6 +175,7 @@ from \fB::http::geturl\fR. This token is the name of an array that is described in the \fBSTATE ARRAY\fR section. Here is a template for the callback: .RS +.PP .CS proc httpCallback {token} { upvar #0 $token state @@ -172,6 +185,7 @@ proc httpCallback {token} { .RE .TP \fB\-handler\fR \fIcallback\fR +. Invoke \fIcallback\fR whenever HTTP data is available; if present, nothing else will be done with the HTTP data. This procedure gets two additional arguments: the socket for the HTTP data and the \fItoken\fR returned from @@ -180,6 +194,7 @@ described in the \fBSTATE ARRAY\fR section. The procedure is expected to return the number of bytes read from the socket. Here is a template for the callback: .RS +.PP .CS proc httpHandlerCallback {socket token} { upvar #0 $token state @@ -195,6 +210,7 @@ proc httpHandlerCallback {socket token} { .RE .TP \fB\-headers\fR \fIkeyvaluelist\fR +. This option is used to add extra headers to the HTTP request. The \fIkeyvaluelist\fR argument must be a list with an even number of elements that alternate between keys and values. The keys become @@ -202,24 +218,31 @@ header field names. Newlines are stripped from the values so the header cannot be corrupted. For example, if \fIkeyvaluelist\fR is \fBPragma no-cache\fR then the following header is included in the HTTP request: +.RS +.PP .CS Pragma: no-cache .CE +.RE .TP \fB\-keepalive\fR \fIboolean\fR +. If true, attempt to keep the connection open for servicing multiple requests. Default is 0. .TP \fB\-method\fR \fItype\fR +. Force the HTTP request method to \fItype\fR. \fB::http::geturl\fR will auto-select GET, POST or HEAD based on other options, but this option enables choices like PUT and DELETE for webdav support. .TP \fB\-myaddr\fR \fIaddress\fR +. Pass an specific local address to the underlying \fBsocket\fR call in case multiple interfaces are available. .TP \fB\-progress\fR \fIcallback\fR +. The \fIcallback\fR is made after each transfer of data from the URL. The callback gets three additional arguments: the \fItoken\fR from \fB::http::geturl\fR, the expected total size of the contents from the @@ -228,6 +251,7 @@ transferred so far. The expected total size may be unknown, in which case zero is passed to the callback. Here is a template for the progress callback: .RS +.PP .CS proc httpProgress {token total current} { upvar #0 $token state @@ -236,17 +260,20 @@ proc httpProgress {token total current} { .RE .TP \fB\-protocol\fR \fIversion\fR +. Select the HTTP protocol version to use. This should be 1.0 or 1.1 (the default). Should only be necessary for servers that do not understand or otherwise complain about HTTP/1.1. .TP \fB\-query\fR \fIquery\fR +. This flag causes \fB::http::geturl\fR to do a POST request that passes the \fIquery\fR to the server. The \fIquery\fR must be an x-url-encoding formatted query. The \fB::http::formatQuery\fR procedure can be used to do the formatting. .TP \fB\-queryblocksize\fR \fIsize\fR +. The block size used when posting query data to the URL. At most \fIsize\fR @@ -255,6 +282,7 @@ bytes are written at once. After each block, a call to the callback is made (if that option is specified). .TP \fB\-querychannel\fR \fIchannelID\fR +. This flag causes \fB::http::geturl\fR to do a POST request that passes the data contained in \fIchannelID\fR to the server. The data contained in \fIchannelID\fR must be an x-url-encoding @@ -265,14 +293,17 @@ in order to create that header. If it is unable to determine the size, it returns an error. .TP \fB\-queryprogress\fR \fIcallback\fR +. The \fIcallback\fR is made after each transfer of data to the URL (i.e. POST) and acts exactly like the \fB\-progress\fR option (the callback format is the same). .TP \fB\-strict\fR \fIboolean\fR +. Whether to enforce RFC 3986 URL validation on the request. Default is 1. .TP \fB\-timeout\fR \fImilliseconds\fR +. If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout to occur after the specified number of milliseconds. A timeout results in a call to \fB::http::reset\fR and to @@ -281,11 +312,13 @@ The return value of \fB::http::status\fR is \fBtimeout\fR after a timeout has occurred. .TP \fB\-type\fR \fImime-type\fR +. Use \fImime-type\fR as the \fBContent-Type\fR value, instead of the default value (\fBapplication/x-www-form-urlencoded\fR) during a POST operation. .TP \fB\-validate\fR \fIboolean\fR +. If \fIboolean\fR is non-zero, then \fB::http::geturl\fR does an HTTP HEAD request. This request returns meta information about the URL, but the contents are not returned. The meta information is available in the @@ -294,6 +327,7 @@ contents are not returned. The meta information is available in the .RE .TP \fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...? +. This procedure does x-url-encoding of query data. It takes an even number of arguments that are the keys and values of the query. It encodes the keys and values, and generates one string that has the @@ -301,10 +335,13 @@ proper & and = separators. The result is suitable for the \fB\-query\fR value passed to \fB::http::geturl\fR. .TP \fB::http::reset\fR \fItoken\fR ?\fIwhy\fR? -This command resets the HTTP transaction identified by \fItoken\fR, if -any. This sets the \fBstate(status)\fR value to \fIwhy\fR, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback. +. +This command resets the HTTP transaction identified by \fItoken\fR, if any. +This sets the \fBstate(status)\fR value to \fIwhy\fR, which defaults to +\fBreset\fR, and then calls the registered \fB\-command\fR callback. .TP \fB::http::wait\fR \fItoken\fR +. This is a convenience procedure that blocks and waits for the transaction to complete. This only works in trusted code because it uses \fBvwait\fR. Also, it is not useful for the case where @@ -314,36 +351,44 @@ until the HTTP transaction is complete, and thus there is nothing to wait for. .TP \fB::http::data\fR \fItoken\fR +. This is a convenience procedure that returns the \fBbody\fR element (i.e., the URL data) of the state array. .TP \fB::http::error\fR \fItoken\fR +. This is a convenience procedure that returns the \fBerror\fR element of the state array. .TP \fB::http::status\fR \fItoken\fR +. This is a convenience procedure that returns the \fBstatus\fR element of the state array. .TP \fB::http::code\fR \fItoken\fR +. This is a convenience procedure that returns the \fBhttp\fR element of the state array. .TP \fB::http::ncode\fR \fItoken\fR +. This is a convenience procedure that returns just the numeric return code (200, 404, etc.) from the \fBhttp\fR element of the state array. .TP \fB::http::size\fR \fItoken\fR +. This is a convenience procedure that returns the \fBcurrentsize\fR element of the state array, which represents the number of bytes received from the URL in the \fB::http::geturl\fR call. .TP \fB::http::meta\fR \fItoken\fR +. This is a convenience procedure that returns the \fBmeta\fR element of the state array which contains the HTTP response headers. See below for an explanation of this element. .TP \fB::http::cleanup\fR \fItoken\fR +. This procedure cleans up the state associated with the connection identified by \fItoken\fR. After this call, the procedures like \fB::http::data\fR cannot be used to get information @@ -354,10 +399,12 @@ so will result in memory not being freed, and if your app calls performance hit...or worse. .TP \fB::http::register\fR \fIproto port command\fR +. This procedure allows one to provide custom HTTP transport types such as HTTPS, by registering a prefix, the default port, and the command to execute to create the Tcl \fBchannel\fR. E.g.: .RS +.PP .CS package require http package require tls @@ -369,6 +416,7 @@ set token [::http::geturl https://my.secure.site/] .RE .TP \fB::http::unregister\fR \fIproto\fR +. This procedure unregisters a protocol handler that was previously registered via \fB::http::register\fR. .SH ERRORS @@ -409,7 +457,8 @@ There are other possible results of the HTTP transaction determined by examining the status from \fB::http::status\fR. These are described below. .TP -ok +\fBok\fR +. If the HTTP transaction completes entirely, then status will be \fBok\fR. However, you should still check the \fB::http::code\fR value to get the HTTP status. The \fB::http::ncode\fR procedure provides just @@ -417,11 +466,13 @@ the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fR procedure returns a value like .QW "HTTP 404 File not found" . .TP -eof +\fBeof\fR +. If the server closes the socket without replying, then no error is raised, but the status of the transaction will be \fBeof\fR. .TP -error +\fBerror\fR +. The error message will also be stored in the \fBerror\fR status array element, accessible via \fB::http::error\fR. .PP @@ -438,9 +489,11 @@ an \fBeof\fR status. The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to get to the state of the HTTP transaction in the form of a Tcl array. Use this construct to create an easy-to-use array variable: +.PP .CS upvar #0 $token state .CE +.PP Once the data associated with the URL is no longer needed, the state array should be unset to free up storage. The \fB::http::cleanup\fR procedure is provided for that purpose. @@ -449,33 +502,41 @@ the array are supported: .RS .TP \fBbody\fR +. The contents of the URL. This will be empty if the \fB\-channel\fR option has been specified. This value is returned by the \fB::http::data\fR command. .TP \fBcharset\fR +. The value of the charset attribute from the \fBContent-Type\fR meta-data value. If none was specified, this defaults to the RFC standard \fBiso8859-1\fR, or the value of \fB$::http::defaultCharset\fR. Incoming text data will be automatically converted from this charset to utf-8. .TP \fBcoding\fR +. A copy of the \fBContent-Encoding\fR meta-data value. .TP \fBcurrentsize\fR +. The current number of bytes fetched from the URL. This value is returned by the \fB::http::size\fR command. .TP \fBerror\fR +. If defined, this is the error string seen when the HTTP transaction was aborted. .TP \fBhttp\fR +. The HTTP status reply from the server. This value is returned by the \fB::http::code\fR command. The format of this value is: .RS +.PP .CS \fIHTTP/1.1 code string\fR .CE +.PP The \fIcode\fR is a three-digit number defined in the HTTP standard. A code of 200 is OK. Codes beginning with 4 or 5 indicate errors. Codes beginning with 3 are redirection errors. In this case the @@ -484,52 +545,66 @@ requested information. .RE .TP \fBmeta\fR +. The HTTP protocol returns meta-data that describes the URL contents. The \fBmeta\fR element of the state array is a list of the keys and values of the meta-data. This is in a format useful for initializing an array that just contains the meta-data: .RS +.PP .CS array set meta $state(meta) .CE +.PP Some of the meta-data keys are listed below, but the HTTP standard defines more, and servers are free to add their own. .TP \fBContent-Type\fR +. The type of the URL contents. Examples include \fBtext/html\fR, \fBimage/gif,\fR \fBapplication/postscript\fR and \fBapplication/x-tcl\fR. .TP \fBContent-Length\fR +. The advertised size of the contents. The actual size obtained by \fB::http::geturl\fR is available as \fBstate(size)\fR. .TP \fBLocation\fR +. An alternate URL that contains the requested data. .RE .TP \fBposterror\fR +. The error, if any, that occurred while writing the post query data to the server. .TP \fBstatus\fR +. Either \fBok\fR, for successful completion, \fBreset\fR for user-reset, \fBtimeout\fR if a timeout occurred before the transaction could complete, or \fBerror\fR for an error condition. During the transaction this value is the empty string. .TP \fBtotalsize\fR +. A copy of the \fBContent-Length\fR meta-data value. .TP \fBtype\fR +. A copy of the \fBContent-Type\fR meta-data value. .TP \fBurl\fR +. The requested URL. .RE .SH EXAMPLE +.PP +This example creates a procedure to copy a URL to a file while printing a +progress meter, and prints the meta-data associated with the URL. +.PP .CS -# Copy a URL to a file and print meta-data proc httpcopy { url file {chunk 4096} } { set out [open $file w] set token [\fB::http::geturl\fR $url -channel $out \e @@ -566,4 +641,7 @@ proc httpCopyProgress {args} { .SH "SEE ALSO" safe(n), socket(n), safesock(n) .SH KEYWORDS -security policy, socket +internet, security policy, socket, www +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/if.n b/doc/if.n index 524f7a6..d80c684 100644 --- a/doc/if.n +++ b/doc/if.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: if.n,v 1.9 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: if.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH if n "" Tcl "Tcl Built-In Commands" @@ -40,12 +40,15 @@ The return value from the command is the result of the body script that was executed, or an empty string if none of the expressions was non-zero and there was no \fIbodyN\fR. .SH EXAMPLES +.PP A simple conditional: +.PP .CS \fBif\fR {$vbl == 1} { puts "vbl is one" } .CE .PP With an \fBelse\fR-clause: +.PP .CS \fBif\fR {$vbl == 1} { puts "vbl is one" @@ -55,6 +58,7 @@ With an \fBelse\fR-clause: .CE .PP With an \fBelseif\fR-clause too: +.PP .CS \fBif\fR {$vbl == 1} { puts "vbl is one" @@ -67,16 +71,17 @@ With an \fBelseif\fR-clause too: .PP Remember, expressions can be multi-line, but in that case it can be a good idea to use the optional \fBthen\fR keyword for clarity: +.PP .CS \fBif\fR { - $vbl == 1 || $vbl == 2 || $vbl == 3 + $vbl == 1 + || $vbl == 2 + || $vbl == 3 } \fBthen\fR { puts "vbl is one, two or three" } .CE - .SH "SEE ALSO" expr(n), for(n), foreach(n) - .SH KEYWORDS boolean, conditional, else, false, if, true diff --git a/doc/incr.n b/doc/incr.n index e7587a6..972f78b 100644 --- a/doc/incr.n +++ b/doc/incr.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: incr.n,v 1.7 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: incr.n,v 1.8 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH incr n "" Tcl "Tcl Built-In Commands" @@ -32,17 +32,20 @@ the value \fIincrement\fR or to the default increment value of \fB1\fR. .SH EXAMPLES .PP Add one to the contents of the variable \fIx\fR: +.PP .CS \fBincr\fR x .CE .PP Add 42 to the contents of the variable \fIx\fR: +.PP .CS \fBincr\fR x 42 .CE .PP Add the contents of the variable \fIy\fR to the contents of the variable \fIx\fR: +.PP .CS \fBincr\fR x $y .CE @@ -50,10 +53,11 @@ variable \fIx\fR: Add nothing at all to the variable \fIx\fR (often useful for checking whether an argument to a procedure is actually integral and generating an error if it is not): +.PP .CS \fBincr\fR x 0 .CE .SH "SEE ALSO" -expr(n) +expr(n), set(n) .SH KEYWORDS add, increment, variable, value diff --git a/doc/info.n b/doc/info.n index 66ec0c4..a5a3eaa 100644 --- a/doc/info.n +++ b/doc/info.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: info.n,v 1.30 2008/10/02 23:03:58 andreas_kupries Exp $ +'\" RCS: @(#) $Id: info.n,v 1.31 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH info n 8.4 Tcl "Tcl Built-In Commands" @@ -604,6 +604,7 @@ proc printProc {procName} { .PP Every object necessarily knows what its class is; this information is trivially extractable through introspection: +.PP .CS oo::class create c c create o @@ -615,6 +616,7 @@ puts [\fBinfo object class\fR c] .PP The introspection capabilities can be used to discover what class implements a method and get how it is defined. This procedure illustrates how: +.PP .CS proc getDef {obj method} { if {$method in [\fBinfo object methods\fR $obj]} { diff --git a/doc/interp.n b/doc/interp.n index bd7b276..c986519 100644 --- a/doc/interp.n +++ b/doc/interp.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: interp.n,v 1.40 2008/06/29 13:50:49 dkf Exp $ +'\" RCS: @(#) $Id: interp.n,v 1.41 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH interp n 8.6 Tcl "Tcl Built-In Commands" @@ -350,9 +350,11 @@ new Tcl command is created in the master interpreter with the same name as the new interpreter. This command may be used to invoke various operations on the interpreter. It has the following general form: +.PP .CS \fIslave command \fR?\fIarg arg ...\fR? .CE +.PP \fISlave\fR is the name of the interpreter, and \fIcommand\fR and the \fIarg\fRs determine the exact behavior of the command. The valid forms of this command are: @@ -811,7 +813,9 @@ performed. The safe interpreter mechanism is based on the Safe-Tcl prototype implemented by Nathaniel Borenstein and Marshall Rose. .SH EXAMPLES +.PP Creating and using an alias for a command in the current interpreter: +.PP .CS \fBinterp alias\fR {} getIndex {} lsearch {alpha beta gamma delta} set idx [getIndex delta] @@ -819,6 +823,7 @@ set idx [getIndex delta] .PP Executing an arbitrary command in a safe interpreter where every invocation of \fBlappend\fR is logged: +.PP .CS set i [\fBinterp create\fR -safe] \fBinterp hide\fR $i lappend @@ -832,6 +837,7 @@ proc loggedLappend {i args} { .PP Setting a resource limit on an interpreter so that an infinite loop terminates. +.PP .CS set i [\fBinterp create\fR] \fBinterp limit\fR $i command -value 1000 diff --git a/doc/join.n b/doc/join.n index 086ed7d..e0583ef 100644 --- a/doc/join.n +++ b/doc/join.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: join.n,v 1.9 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: join.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH join n "" Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ join \- Create a string by joining together list elements .SH SYNOPSIS \fBjoin \fIlist \fR?\fIjoinString\fR? .BE - .SH DESCRIPTION .PP The \fIlist\fR argument must be a valid Tcl list. @@ -25,7 +24,9 @@ formed by joining all of the elements of \fIlist\fR together with \fIjoinString\fR separating each adjacent pair of elements. The \fIjoinString\fR argument defaults to a space character. .SH EXAMPLES +.PP Making a comma-separated list: +.PP .CS set data {1 2 3 4 5} \fBjoin\fR $data ", " @@ -33,14 +34,13 @@ set data {1 2 3 4 5} .CE .PP Using \fBjoin\fR to flatten a list by a single level: +.PP .CS set data {1 {2 3} 4 {5 {6 7} 8}} \fBjoin\fR $data \fB\(-> 1 2 3 4 5 {6 7} 8\fR .CE - .SH "SEE ALSO" list(n), lappend(n), split(n) - .SH KEYWORDS element, join, list, separator diff --git a/doc/lappend.n b/doc/lappend.n index a3c40cf..3a31a57 100644 --- a/doc/lappend.n +++ b/doc/lappend.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: lappend.n,v 1.16 2008/03/26 09:59:22 dkf Exp $ +'\" RCS: @(#) $Id: lappend.n,v 1.17 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH lappend n "" Tcl "Tcl Built-In Commands" @@ -17,7 +17,6 @@ lappend \- Append list elements onto a variable .SH SYNOPSIS \fBlappend \fIvarName \fR?\fIvalue value value ...\fR? .BE - .SH DESCRIPTION .PP This command treats the variable given by \fIvarName\fR as a list @@ -34,7 +33,9 @@ is much more efficient than .QW "\fBset a [concat $a [list $b]]\fR" when \fB$a\fR is long. .SH EXAMPLE +.PP Using \fBlappend\fR to build up a list of numbers. +.PP .CS % set var 1 1 @@ -43,10 +44,8 @@ Using \fBlappend\fR to build up a list of numbers. % \fBlappend\fR var 3 4 5 1 2 3 4 5 .CE - .SH "SEE ALSO" list(n), lindex(n), linsert(n), llength(n), lset(n), lsort(n), lrange(n) - .SH KEYWORDS append, element, list, variable diff --git a/doc/lassign.n b/doc/lassign.n index 57bd7b4..f2bfcda 100644 --- a/doc/lassign.n +++ b/doc/lassign.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: lassign.n,v 1.6 2008/09/26 19:12:40 dgp Exp $ +'\" RCS: @(#) $Id: lassign.n,v 1.7 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH lassign n 8.5 Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ lassign \- Assign list elements to variables .SH SYNOPSIS \fBlassign \fIlist \fR?\fIvarName ...\fR? .BE - .SH DESCRIPTION .PP This command treats the value \fIlist\fR as a list and assigns @@ -26,8 +25,10 @@ than list elements, the remaining variables are set to the empty string. If there are more list elements than variables, a list of unassigned elements is returned. .SH EXAMPLES +.PP An illustration of how multiple assignment works, and what happens when there are either too few or too many elements. +.PP .CS lassign {a b c} x y z ;# Empty return puts $x ;# Prints "a" @@ -43,15 +44,19 @@ lassign {f g h i} x y ;# Returns "h i" puts $x ;# Prints "f" puts $y ;# Prints "g" .CE +.PP The \fBlassign\fR command has other uses. It can be used to create the analogue of the .QW shift command in many shell languages like this: +.PP .CS set ::argv [lassign $::argv argumentToReadOff] .CE .SH "SEE ALSO" lindex(n), list(n), lset(n), set(n) - .SH KEYWORDS assign, element, list, multiple, set, variable +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/library.n b/doc/library.n index 9a9f47e..98c578c 100644 --- a/doc/library.n +++ b/doc/library.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: library.n,v 1.23 2008/08/27 12:47:26 dkf Exp $ +'\" RCS: @(#) $Id: library.n,v 1.24 2008/10/17 10:22:25 dkf Exp $ .so man.macros .TH library n "8.0" Tcl "Tcl Built-In Commands" .BS @@ -45,9 +45,11 @@ For example, the location of the Tk library is kept in the variable To access the procedures in the Tcl library, an application should source the file \fBinit.tcl\fR in the library, for example with the Tcl command +.PP .CS \fBsource [file join [info library] init.tcl]\fR .CE +.PP If the library procedure \fBTcl_Init\fR is invoked from an application's \fBTcl_AppInit\fR procedure, this happens automatically. The code in \fBinit.tcl\fR will define the \fBunknown\fR procedure @@ -106,6 +108,7 @@ cached index information may be deleted with the command reload the index database from disk. .TP \fBauto_mkindex \fIdir pattern pattern ...\fR +. Generates an index suitable for use by \fBauto_load\fR. The command searches \fIdir\fR for all files whose names match any of the \fIpattern\fR arguments (matching is done with the \fBglob\fR @@ -114,10 +117,11 @@ in all the matching files, and stores the index information in a file named \fBtclIndex\fR in \fIdir\fR. If no pattern is given a pattern of \fB*.tcl\fR will be assumed. For example, the command .RS +.PP .CS \fBauto_mkindex foo *.tcl\fR .CE -.LP +.PP will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR and generate a new index file \fBfoo/tclIndex\fR. .PP @@ -143,6 +147,7 @@ code or procedure names with special characters like \fB$\fR, .RE .TP \fBauto_reset\fR +. Destroys all the information cached by \fBauto_execok\fR and \fBauto_load\fR. This information will be re-read from disk the next time it is needed. \fBAuto_reset\fR also deletes any procedures @@ -297,3 +302,6 @@ Unix, words are comprised of numbers, letters or underscores. info(n), re_syntax(n), tclvars(n) .SH KEYWORDS auto-exec, auto-load, library, unknown, word, whitespace +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/lindex.n b/doc/lindex.n index 3214cc7..4eac53a 100644 --- a/doc/lindex.n +++ b/doc/lindex.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: lindex.n,v 1.20 2008/07/13 23:15:23 nijtmans Exp $ +'\" RCS: @(#) $Id: lindex.n,v 1.21 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH lindex n 8.4 Tcl "Tcl Built-In Commands" @@ -26,13 +26,17 @@ command line, or grouped in a Tcl list and presented as a single argument. .PP If no indices are presented, the command takes the form: +.PP .CS lindex list .CE +.PP or +.PP .CS lindex list {} .CE +.PP In this case, the return value of \fBlindex\fR is simply the value of the \fIlist\fR parameter. .PP @@ -53,14 +57,19 @@ arithmetic and indices relative to the end of the list. If additional \fIindex\fR arguments are supplied, then each argument is used in turn to select an element from the previous indexing operation, allowing the script to select elements from sublists. The command, +.PP .CS lindex $a 1 2 3 .CE +.PP or +.PP .CS lindex $a {1 2 3} .CE +.PP is synonymous with +.PP .CS lindex [lindex [lindex $a 1] 2] 3 .CE @@ -113,3 +122,6 @@ lset(n), lsort(n), lrange(n), lreplace(n), string(n) .SH KEYWORDS element, index, list +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/linsert.n b/doc/linsert.n index c552a54..22ad6ae 100644 --- a/doc/linsert.n +++ b/doc/linsert.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: linsert.n,v 1.16 2008/09/29 15:38:32 dgp Exp $ +'\" RCS: @(#) $Id: linsert.n,v 1.17 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH linsert n 8.2 Tcl "Tcl Built-In Commands" @@ -31,6 +31,7 @@ arithmetic and indices relative to the end of the list. .PP Putting some values into a list, first indexing from the start and then indexing from the end, and then chaining them together: +.PP .CS set oldList {the fox jumps over the dog} set midList [\fBlinsert\fR $oldList 1 quick] diff --git a/doc/list.n b/doc/list.n index 87cdcd6..6ec1b7c 100644 --- a/doc/list.n +++ b/doc/list.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: list.n,v 1.12 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: list.n,v 1.13 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH list n "" Tcl "Tcl Built-In Commands" @@ -31,14 +31,19 @@ the list, while \fBlist\fR works directly from the original arguments. .SH EXAMPLE .PP The command +.PP .CS \fBlist\fR a b "c d e " " f {g h}" .CE +.PP will return +.PP .CS \fBa b {c d e } { f {g h}}\fR .CE +.PP while \fBconcat\fR with the same arguments will return +.PP .CS \fBa b c d e f {g h}\fR .CE @@ -48,3 +53,6 @@ lrepeat(n), lreplace(n), lsearch(n), lset(n), lsort(n) .SH KEYWORDS element, list +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/llength.n b/doc/llength.n index 282bd8b..e050ed9 100644 --- a/doc/llength.n +++ b/doc/llength.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: llength.n,v 1.14 2008/03/26 09:59:22 dkf Exp $ +'\" RCS: @(#) $Id: llength.n,v 1.15 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH llength n "" Tcl "Tcl Built-In Commands" @@ -17,14 +17,14 @@ llength \- Count the number of elements in a list .SH SYNOPSIS \fBllength \fIlist\fR .BE - .SH DESCRIPTION .PP Treats \fIlist\fR as a list and returns a decimal string giving the number of elements in it. - .SH EXAMPLES +.PP The result is the number of elements: +.PP .CS % \fBllength\fR {a b c d e} 5 @@ -36,6 +36,7 @@ The result is the number of elements: .PP Elements are not guaranteed to be exactly words in a dictionary sense of course, especially when quoting is used: +.PP .CS % \fBllength\fR {a b {c d} e} 4 @@ -44,14 +45,13 @@ of course, especially when quoting is used: .CE .PP An empty list is not necessarily an empty string: +.PP .CS % set var { }; puts "[string length $var],[\fBllength\fR $var]" 1,0 .CE - .SH "SEE ALSO" list(n), lappend(n), lindex(n), linsert(n), lsearch(n), lset(n), lsort(n), lrange(n), lreplace(n) - .SH KEYWORDS element, list, length diff --git a/doc/load.n b/doc/load.n index 4982c96..08adefb 100644 --- a/doc/load.n +++ b/doc/load.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: load.n,v 1.23 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: load.n,v 1.24 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH load n 7.5 Tcl "Tcl Built-In Commands" @@ -57,10 +57,12 @@ by the package that is safe for use by untrusted code. For more information on Safe\-Tcl, see the \fBsafe\fR manual entry. .PP The initialization procedure must match the following prototype: +.PP .CS typedef int \fBTcl_PackageInitProc\fR( Tcl_Interp *\fIinterp\fR); .CE +.PP The \fIinterp\fR argument identifies the interpreter in which the package is to be loaded. The initialization procedure must return \fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed @@ -119,6 +121,7 @@ When loading a DLL in the current directory, Windows will ignore .QW ./ as a path specifier and use a search heuristic to find the DLL instead. To avoid this, load the DLL with: +.PP .CS \fBload\fR [file join [pwd] mylib.DLL] .CE @@ -172,3 +175,6 @@ foo info sharedlibextension, Tcl_StaticPackage(3), safe(n) .SH KEYWORDS binary code, loading, safe interpreter, shared library +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/lrange.n b/doc/lrange.n index 830d7fa..bf67022 100644 --- a/doc/lrange.n +++ b/doc/lrange.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: lrange.n,v 1.18 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: lrange.n,v 1.19 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH lrange n 7.4 Tcl "Tcl Built-In Commands" @@ -39,19 +39,23 @@ does not always produce the same result as braces); it does, however, produce exactly the same results as .QW "\fBlist [lindex \fIlist first\fB]\fR" .SH EXAMPLES +.PP Selecting the first two elements: +.PP .CS % \fBlrange\fR {a b c d e} 0 1 a b .CE .PP Selecting the last three elements: +.PP .CS % \fBlrange\fR {a b c d e} end-2 end c d e .CE .PP Selecting everything except the first and last element: +.PP .CS % \fBlrange\fR {a b c d e} 1 end-1 b c d @@ -59,6 +63,7 @@ b c d .PP Selecting a single element with \fBlrange\fR is not the same as doing so with \fBlindex\fR: +.PP .CS % set var {some {elements to} select} some {elements to} select diff --git a/doc/lreplace.n b/doc/lreplace.n index 605e46f..5509367 100644 --- a/doc/lreplace.n +++ b/doc/lreplace.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: lreplace.n,v 1.20 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: lreplace.n,v 1.21 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH lreplace n 7.4 Tcl "Tcl Built-In Commands" @@ -49,18 +49,21 @@ is empty, any \fIelement\fR arguments are added to the end of the list. .SH EXAMPLES .PP Replacing an element of a list with another: +.PP .CS % \fBlreplace\fR {a b c d e} 1 1 foo a foo c d e .CE .PP Replacing two elements of a list with three: +.PP .CS % \fBlreplace\fR {a b c d e} 1 2 three more elements a three more elements d e .CE .PP Deleting the last element from a list in a variable: +.PP .CS % set var {a b c d e} a b c d e @@ -69,6 +72,7 @@ a b c d .CE .PP A procedure to delete a given element from a list: +.PP .CS proc lremove {listVariable value} { upvar 1 $listVariable var diff --git a/doc/lsearch.n b/doc/lsearch.n index cd4363d..1caf479 100644 --- a/doc/lsearch.n +++ b/doc/lsearch.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: lsearch.n,v 1.36 2008/09/29 12:25:22 dkf Exp $ +'\" RCS: @(#) $Id: lsearch.n,v 1.37 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH lsearch n 8.6 Tcl "Tcl Built-In Commands" @@ -167,6 +167,7 @@ overall list to the term found. This option has no effect unless the .SH EXAMPLES .PP Basic searching: +.PP .CS \fBlsearch\fR {a b c d e} c \fI\(-> 2\fR @@ -175,6 +176,7 @@ Basic searching: .CE .PP Using \fBlsearch\fR to filter lists: +.PP .CS \fBlsearch\fR -inline {a20 b35 c47} b* \fI\(-> b35\fR @@ -189,18 +191,21 @@ Using \fBlsearch\fR to filter lists: This can even do a .QW set-like removal operation: +.PP .CS \fBlsearch\fR -all -inline -not -exact {a b c a d e a f g a} a \fI\(-> b c d e f g\fR .CE .PP Searching may start part-way through the list: +.PP .CS \fBlsearch\fR -start 3 {a b c a b c} c \fI\(-> 5\fR .CE .PP It is also possible to search inside elements: +.PP .CS \fBlsearch\fR -index 1 -all -inline {{a abc} {b bcd} {c cde}} *bc* \fI\(-> {a abc} {b bcd}\fR diff --git a/doc/lset.n b/doc/lset.n index e6966aa..74d47e6 100755 --- a/doc/lset.n +++ b/doc/lset.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: lset.n,v 1.18 2008/10/06 04:25:24 kennykb Exp $ +'\" RCS: @(#) $Id: lset.n,v 1.19 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH lset n 8.4 Tcl "Tcl Built-In Commands" @@ -26,13 +26,17 @@ Tcl list and presented as a single argument. Finally, it accepts a new value for an element of \fIvarName\fR. .PP If no indices are presented, the command takes the form: +.PP .CS lset varName newValue .CE +.PP or +.PP .CS lset varName {} newValue .CE +.PP In this case, \fInewValue\fR replaces the old value of the variable \fIvarName\fR. .PP @@ -64,13 +68,17 @@ used in turn to address an element within a sublist designated by the previous indexing operation, allowing the script to alter elements in sublists (or append elements to sublists). The command, +.PP .CS lset a 1 2 newValue .CE +.PP or +.PP .CS lset a {1 2} newValue .CE +.PP replaces element 2 of sublist 1 with \fInewValue\fR. .PP The integer appearing in each \fIindex\fR argument must be greater @@ -82,13 +90,16 @@ end). If an index is outside the permitted range, an error is reported. .SH EXAMPLES .PP In each of these examples, the initial value of \fIx\fR is: +.PP .CS set x [list [list a b c] [list d e f] [list g h i]] \fI\(-> {a b c} {d e f} {g h i}\fR .CE +.PP The indicated return value also becomes the new value of \fIx\fR (except in the last case, which is an error which leaves the value of \fIx\fR unchanged.) +.PP .CS \fBlset\fR x {j k l} \fI\(-> j k l\fR @@ -109,13 +120,17 @@ The indicated return value also becomes the new value of \fIx\fR \fBlset\fR x {2 3} j \fI\(-> list index out of range\fR .CE +.PP In the following examples, the initial value of \fIx\fR is: +.PP .CS set x [list [list [list a b] [list c d]] \e [list [list e f] [list g h]]] \fI\(-> {{a b} {c d}} {{e f} {g h}}\fR .CE +.PP The indicated return value also becomes the new value of \fIx\fR. +.PP .CS \fBlset\fR x 1 1 0 j \fI\(-> {{a b} {c d}} {{e f} {j h}}\fR @@ -128,3 +143,6 @@ lsort(n), lrange(n), lreplace(n), string(n) .SH KEYWORDS element, index, list, replace, set +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/lsort.n b/doc/lsort.n index 6253a5e..f83ace5 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.31 2008/09/29 13:33:18 dkf Exp $ +'\" RCS: @(#) $Id: lsort.n,v 1.32 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH lsort n 8.5 Tcl "Tcl Built-In Commands" @@ -88,11 +88,14 @@ element and the \fIindexList\fR were passed to \fBlindex\fR) and sort based on the given element. For example, .RS +.PP .CS lsort -integer -index 1 \e {{First 24} {Second 18} {Third 30}} .CE -returns \fB{Second 18} {First 24} {Third 30}\fR, and +.PP +returns \fB{Second 18} {First 24} {Third 30}\fR, +.PP '\" '\" This example is from the test suite! '\" @@ -100,8 +103,10 @@ returns \fB{Second 18} {First 24} {Third 30}\fR, and lsort -index end-1 \e {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}} .CE +.PP returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR, and +.PP .CS lsort -index {0 1} { {{b i g} 12345} @@ -109,6 +114,7 @@ lsort -index {0 1} { {{c o d e} 54321} } .CE +.PP 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.) This option is much more efficient than using \fB\-command\fR @@ -129,15 +135,19 @@ The list length must be an integer multiple of \fIstrideLength\fR, which in turn must be at least 2. .PP For example, +.PP .CS lsort \-stride 2 {carrot 10 apple 50 banana 25} .CE +.PP returns .QW "apple 50 banana 25 carrot 10" , and +.PP .CS lsort \-stride 2 \-index 1 \-integer {carrot 10 apple 50 banana 25} .CE +.PP returns .QW "carrot 10 banana 25 apple 50" . .RE @@ -169,18 +179,21 @@ option. .SH "EXAMPLES" .PP Sorting a list using ASCII sorting: +.PP .CS % \fBlsort\fR {a10 B2 b1 a1 a2} B2 a1 a10 a2 b1 .CE .PP Sorting a list using Dictionary sorting: +.PP .CS % \fBlsort\fR -dictionary {a10 B2 b1 a1 a2} a1 a2 a10 b1 B2 .CE .PP Sorting lists of integers: +.PP .CS % \fBlsort\fR -integer {5 3 1 2 11 4} 1 2 3 4 5 11 @@ -189,6 +202,7 @@ Sorting lists of integers: .CE .PP Sorting lists of floating-point numbers: +.PP .CS % \fBlsort\fR -real {5 3 1 2 11 4} 1 2 3 4 5 11 @@ -197,6 +211,7 @@ Sorting lists of floating-point numbers: .CE .PP Sorting using indices: +.PP .CS % # Note the space character before the c % \fBlsort\fR {{a 5} { c 3} {b 4} {e 1} {d 2}} @@ -209,6 +224,7 @@ Sorting using indices: .PP .VS 8.6 Sorting a dictionary: +.PP .CS % set d [dict create c d a b h i f g c e] c e a b h i f g @@ -217,6 +233,7 @@ a b c e f g h i .CE .PP Sorting using striding and multiple indices: +.PP .CS % # Note the first index value is relative to the group % \fBlsort\fR \-stride 3 \-index {0 1} \e @@ -226,12 +243,14 @@ Sorting using striding and multiple indices: .VE 8.6 .PP Stripping duplicate values using sorting: +.PP .CS % \fBlsort\fR -unique {a b c a b c a b c} a b c .CE .PP More complex sorting using a comparison function: +.PP .CS % proc compare {a b} { set a0 [lindex $a 0] diff --git a/doc/mathop.n b/doc/mathop.n index 9210430..ac3212d 100644 --- a/doc/mathop.n +++ b/doc/mathop.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: mathop.n,v 1.11 2008/09/23 13:22:18 dkf Exp $ +.\" RCS: @(#) $Id: mathop.n,v 1.12 2008/10/17 10:22:25 dkf Exp $ .\" .so man.macros .TH mathop n 8.5 Tcl "Tcl Mathematical Operator Commands" @@ -133,6 +133,7 @@ Each \fInumber\fR must have an integral value. Note that Tcl defines this operation exactly even for negative numbers, so that the following equality holds true: .RS +.PP .CS (\fIx \fB/ \fIy\fR) \fB* \fIy \fB== \fIx \fB-\fR (\fIx \fB% \fIy\fR) .CE @@ -272,9 +273,11 @@ Returns whether the value \fIarg\fR is present in the list \fIlist\fR Returns whether the value \fIarg\fR is not present in the list \fIlist\fR (according to exact string comparison of elements). .SH EXAMPLES +.PP The simplest way to use the operators is often by using \fBnamespace path\fR to make the commands available. This has the advantage of not affecting the set of commands defined by the current namespace. +.PP .CS namespace path {\fB::tcl::mathop\fR ::tcl::mathfunc} diff --git a/doc/memory.n b/doc/memory.n index 7e49882..0bc1b64 100644 --- a/doc/memory.n +++ b/doc/memory.n @@ -3,7 +3,7 @@ '\" Copyright (c) 2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: memory.n,v 1.12 2008/01/18 15:51:08 dkf Exp $ +'\" RCS: @(#) $Id: memory.n,v 1.13 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH memory n 8.1 Tcl "Tcl Built-In Commands" @@ -69,9 +69,11 @@ to \fBckalloc\fR causes a line of trace information to be written to address returned, the amount of memory allocated, and the C filename and line number of the code performing the allocation. For example: .RS +.PP .CS ckalloc 40e478 98 tclProc.c 1406 .CE +.PP Calls to \fBckfree\fR are traced in the same manner. .RE .TP @@ -103,3 +105,6 @@ occur long after the overwrite occurred. ckalloc, ckfree, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory, TCL_MEM_DEBUG .SH KEYWORDS memory, debug +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/msgcat.n b/doc/msgcat.n index 4ed83eb..a212b2f 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -165,14 +165,18 @@ according to the user's environment. The variables \fBenv(LC_ALL)\fR, \fBenv(LC_MESSAGES)\fR, and \fBenv(LANG)\fR are examined in order. The first of them to have a non-empty value is used to determine the initial locale. The value is parsed according to the XPG4 pattern +.PP .CS language[_country][.codeset][@modifier] .CE +.PP to extract its parts. The initial locale is then set by calling \fB::msgcat::mclocale\fR with the argument +.PP .CS language[_country][_modifier] .CE +.PP On Windows, if none of those environment variables is set, msgcat will attempt to extract locale information from the registry. If all these attempts to discover an initial locale @@ -204,6 +208,7 @@ source string to be shorter and less prone to typographical error. .PP For example, executing the code +.PP .CS \fB::msgcat::mcset\fR en hello "hello from ::" namespace eval foo { @@ -212,7 +217,9 @@ namespace eval foo { puts [\fB::msgcat::mc\fR hello] namespace eval foo {puts [\fB::msgcat::mc\fR hello]} .CE +.PP will print +.PP .CS hello from :: hello from ::foo @@ -228,6 +235,7 @@ messages from their parent namespace. For example, executing (in the .QW en locale) the code +.PP .CS \fB::msgcat::mcset\fR en m1 ":: message1" \fB::msgcat::mcset\fR en m2 ":: message2" @@ -244,7 +252,9 @@ 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 +.PP will print +.PP .CS :: message1; :: message2; :: message3 :: message1; ::foo message2; ::foo message3 @@ -260,10 +270,12 @@ All message files for a package are in the same directory. The message file name is a msgcat locale specifier (all lowercase) followed by .QW .msg . For example: +.PP .CS es.msg \(em spanish en_gb.msg \(em United Kingdom English .CE +.PP \fIException:\fR The message file for the root locale .MT is called @@ -278,6 +290,7 @@ The file contains a series of calls to \fBmcset\fR and for the language, likely enclosed in a \fBnamespace eval\fR so that all source strings are tied to the namespace of the package. For example, a short \fBes.msg\fR might contain: +.PP .CS namespace eval ::mypackage { \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!" @@ -294,8 +307,8 @@ During package installation, create a subdirectory .IP [2] Copy your *.msg files into that directory. .IP [3] - Add the following command to your package -initialization script: +Add the following command to your package initialization script: +.PP .CS # load language files, stored in msgs subdirectory \fB::msgcat::mcload\fR [file join [file dirname [info script]] msgs] @@ -307,6 +320,7 @@ to \fBformat\fR might have positionally dependent parameters that might need to be repositioned. For example, it might be syntactically desirable to rearrange the sentence structure while translating. +.PP .CS format "We produced %d units in location %s" $num $city format "In location %s we produced %d units" $city $num @@ -314,6 +328,7 @@ format "In location %s we produced %d units" $city $num .PP This can be handled by using the positional parameters: +.PP .CS format "We produced %1\e$d units in location %2\e$s" $num $city format "In location %2\e$s we produced %1\e$d units" $num $city @@ -328,3 +343,6 @@ The message catalog code was developed by Mark Harrison. format(n), scan(n), namespace(n), package(n) .SH KEYWORDS internationalization, i18n, localization, l10n, message, text, translation +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/doc/my.n b/doc/my.n index 75d7bac..fed03d6 100644 --- a/doc/my.n +++ b/doc/my.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: my.n,v 1.1 2008/05/31 11:42:13 dkf Exp $ +'\" RCS: @(#) $Id: my.n,v 1.2 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH my n 0.1 TclOO "TclOO Commands" @@ -19,8 +19,8 @@ package require TclOO \fBmy\fI methodName\fR ?\fIarg ...\fR? .fi .BE - .SH DESCRIPTION +.PP The \fBmy\fR command is used to allow methods of objects to invoke any method of the object (or its class). In particular, the set of valid values for \fImethodName\fR is the set of all methods supported by an object and its @@ -31,8 +31,10 @@ method is invoked is always the one that is the current context of the method .PP Each object has its own \fBmy\fR command, contained in its unique namespace. .SH EXAMPLES +.PP This example shows basic use of \fBmy\fR to use the \fBvariables\fR method of the \fBoo::object\fR class, which is not publically visible by default: +.PP .CS oo::class create c { method count {} { diff --git a/doc/namespace.n b/doc/namespace.n index faee9c8..dfd0467 100644 --- a/doc/namespace.n +++ b/doc/namespace.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: namespace.n,v 1.34 2008/09/28 22:17:39 dkf Exp $ +'\" RCS: @(#) $Id: namespace.n,v 1.35 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH namespace n 8.5 Tcl "Tcl Built-In Commands" @@ -216,10 +216,13 @@ as proper list elements. .CS \fBnamespace inscope ::foo $script $x $y $z\fR .CE +.PP is equivalent to +.PP .CS \fBnamespace eval ::foo [concat $script [list $x $y $z]]\fR .CE +.PP thus additional arguments will not undergo a second round of substitution, as is the case with \fBnamespace eval\fR. .RE @@ -326,6 +329,7 @@ which we refer to as the \fIglobal namespace\fR. The global namespace holds all global variables and commands. The \fBnamespace eval\fR command lets you create new namespaces. For example, +.PP .CS \fBnamespace eval\fR Counter { \fBnamespace export\fR bump @@ -337,6 +341,7 @@ For example, } } .CE +.PP creates a new namespace containing the variable \fBnum\fR and the procedure \fBbump\fR. The commands and variables in this namespace are separate from @@ -356,6 +361,7 @@ so you can build up the contents of a 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: +.PP .CS \fBnamespace eval\fR Counter { variable num 0 @@ -373,6 +379,7 @@ as the namespace definition shown above: rename test "" } .CE +.PP Note that the \fBtest\fR procedure is added to the \fBCounter\fR namespace, and later removed via the \fBrename\fR command. .PP @@ -404,19 +411,24 @@ you must use some extra syntax. Names must be qualified by the namespace that contains them. From the global namespace, we might access the \fBCounter\fR procedures like this: +.PP .CS Counter::bump 5 Counter::Reset .CE +.PP We could access the current count like this: +.PP .CS puts "count = $Counter::num" .CE +.PP When one namespace contains another, you may need more than one qualifier to reach its elements. 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: +.PP .CS Foo::Counter::bump 3 .CE @@ -424,10 +436,13 @@ Foo::Counter::bump 3 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: +.PP .CS proc Foo::Test {args} {return $args} .CE +.PP And you could move the same procedure to another namespace like this: +.PP .CS rename Foo::Test Bar::Test .CE @@ -467,18 +482,21 @@ Namespace names, on the other hand, are always resolved by looking in only the current namespace. .PP In the following example, +.PP .CS set traceLevel 0 \fBnamespace eval\fR Debug { printTrace $traceLevel } .CE +.PP Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR and then in the global namespace. It looks up the command \fBprintTrace\fR in the same way. 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: +.PP .CS set traceLevel 0 \fBnamespace eval\fR Foo { @@ -489,6 +507,7 @@ set traceLevel 0 } } .CE +.PP Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR. Since it is not found there, Tcl then looks for it in the global namespace. @@ -498,14 +517,18 @@ during the name resolution process. You can use the \fBnamespace which\fR command to clear up any question about name resolution. For example, the command: +.PP .CS \fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR \-variable traceLevel} .CE +.PP returns \fB::traceLevel\fR. On the other hand, the command, +.PP .CS \fBnamespace eval\fR Foo {\fBnamespace which\fR \-variable traceLevel} .CE +.PP returns \fB::Foo::traceLevel\fR. .PP As mentioned above, @@ -543,23 +566,29 @@ that it is a nuisance to type their qualified names. 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: +.PP .CS Blt::graph .g \-background red Blt::table . .g 0,0 .CE +.PP 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: +.PP .CS \fBnamespace import\fR Blt::* .CE +.PP This adds all exported commands from the \fBBlt\fR namespace into the current namespace context, so you can write code like this: +.PP .CS graph .g \-background red table . .g 0,0 .CE +.PP The \fBnamespace import\fR command only imports commands from a namespace that that namespace exported with a \fBnamespace export\fR command. @@ -568,9 +597,11 @@ Importing \fIevery\fR command from a namespace is generally a bad idea since you do not know what you will get. It is better to import just the specific commands you need. For example, the command +.PP .CS \fBnamespace import\fR Blt::graph Blt::table .CE +.PP imports only the \fBgraph\fR and \fBtable\fR commands into the current context. .PP @@ -581,26 +612,33 @@ you may want to get around this restriction. You may want to 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: +.PP .CS \fBnamespace import\fR \-force Blt::graph Blt::table .CE +.PP If for some reason, you want to stop using the imported commands, you can remove them with a \fBnamespace forget\fR command, like this: +.PP .CS \fBnamespace forget\fR Blt::* .CE +.PP This searches the current namespace for any commands imported from \fBBlt\fR. If it finds any, it removes them. Otherwise, it does nothing. After this, the \fBBlt\fR commands must be accessed with the \fBBlt::\fR prefix. .PP When you delete a command from the exporting namespace like this: +.PP .CS rename Blt::graph "" .CE +.PP the command is automatically removed from all namespaces that import it. .SH "EXPORTING COMMANDS" You can export commands from a namespace like this: +.PP .CS \fBnamespace eval\fR Counter { \fBnamespace export\fR bump reset @@ -626,12 +664,15 @@ You can export commands from a namespace like this: } } .CE +.PP The procedures \fBbump\fR and \fBreset\fR are exported, so they are included when you import from the \fBCounter\fR namespace, like this: +.PP .CS \fBnamespace import\fR Counter::* .CE +.PP However, the \fBCheck\fR procedure is not exported, so it is ignored by the import operation. .PP @@ -648,6 +689,7 @@ was created. It is used most often to create event handlers, Tk bindings, 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: +.PP .CS \fBnamespace eval\fR a { variable b @@ -660,7 +702,9 @@ namespace: } set a::b c .CE +.PP When executed, it prints the message: +.PP .CS the value of a::b has changed to c .CE @@ -837,6 +881,7 @@ reparsing. It is also an error for an \fB\-unknown\fR handler to delete its namespace. .SH EXAMPLES Create a namespace containing a variable and an exported command: +.PP .CS \fBnamespace eval\fR foo { variable bar 0 @@ -849,6 +894,7 @@ Create a namespace containing a variable and an exported command: .CE .PP Call the command defined in the previous example in various ways. +.PP .CS # Direct call ::foo::grill @@ -874,11 +920,13 @@ foobar grill .CE .PP Look up where the command imported in the previous example came from: +.PP .CS puts "grill came from [\fBnamespace origin\fR grill]" .CE .PP Remove all imported commands from the current namespace: +.PP .CS namespace forget {*}[namespace import] .CE @@ -887,6 +935,7 @@ namespace forget {*}[namespace import] Create an ensemble for simple working with numbers, using the \fB\-parameters\fR option to allow the operator to be put between the first and second arguments. +.PP .CS \fBnamespace eval\fR do { \fBnamespace export\fR * diff --git a/doc/next.n b/doc/next.n index 898b79b..1240c1b 100644 --- a/doc/next.n +++ b/doc/next.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: next.n,v 1.2 2008/06/19 21:29:03 dkf Exp $ +'\" RCS: @(#) $Id: next.n,v 1.3 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH next n 0.1 TclOO "TclOO Commands" @@ -94,6 +94,7 @@ invoking either constructors or destructors. .PP This example demonstrates how to use the \fBnext\fR command to call the (super)class's implementation of a method. The script: +.PP .CS oo::class create theSuperclass { method example {args} { @@ -117,7 +118,9 @@ oo::define obj method example args { } obj example 1 2 3 .CE +.PP prints the following: +.PP .CS per-object method, args = 1 2 3 before chaining from subclass, args = x 1 2 3 y @@ -188,7 +191,6 @@ puts [demo compute 1 2 3] \fI\(-> prints "7" after delay\fR oo::class(n), oo::define(n), oo::object(n), self(n) .SH KEYWORDS call, method, method chain - .\" Local variables: .\" mode: nroff .\" fill-column: 78 diff --git a/doc/object.n b/doc/object.n index 47acd04..0836728 100644 --- a/doc/object.n +++ b/doc/object.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: object.n,v 1.3 2008/09/26 20:16:39 dgp Exp $ +'\" RCS: @(#) $Id: object.n,v 1.4 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH object n 0.1 TclOO "TclOO Commands" @@ -23,8 +23,8 @@ package require TclOO \fBoo::object\fR .fi .BE - .SH DESCRIPTION +.PP The \fBoo::object\fR class is the root class of the object hierarchy; every object (and hence every class) is an instance of this class. Objects are always referred to by their name, and may be \fBrename\fRd while maintaining @@ -46,6 +46,7 @@ any destructors on the object's class in the process. It is equivalent to using \fBrename\fR to delete the object command. The result of this method is always the empty string. .SS "NON-EXPORTED METHODS" +.PP The \fBoo::object\fR class supports the following non-exported methods: .TP \fIobj \fBeval\fR ?\fIarg ...\fR? @@ -76,7 +77,9 @@ must not have any namespace separators in it. The result is the empty string. This method returns the globally qualified name of the variable \fIvarName\fR in the unique namespace for the object \fIobj\fR. .SH EXAMPLES +.PP This example demonstrates basic use of an object. +.PP .CS set obj [\fBoo::object\fR new] $obj foo \fI\(-> error "unknown method foo"\fR @@ -94,7 +97,6 @@ $obj foo \fI\(-> error "unknown command obj"\fR my(n), oo::class(n) .SH KEYWORDS base class, class, object, root class - .\" Local variables: .\" mode: nroff .\" fill-column: 78 diff --git a/doc/open.n b/doc/open.n index 3b26d21..285103b 100644 --- a/doc/open.n +++ b/doc/open.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: open.n,v 1.35 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: open.n,v 1.36 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH open n 8.3 Tcl "Tcl Built-In Commands" @@ -446,6 +446,7 @@ applications on the various platforms .SH "EXAMPLE" .PP Open a command pipeline and catch any errors: +.PP .CS set fl [\fBopen\fR "| ls this_file_does_not_exist"] set data [read $fl] diff --git a/doc/package.n b/doc/package.n index aafce5e..913d3af 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.22 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: package.n,v 1.23 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH package n 7.5 Tcl "Tcl Built-In Commands" @@ -29,7 +29,6 @@ package \- Facilities for package loading and version control \fBpackage prefer \fR?\fBlatest\fR|\fBstable\fR? .fi .BE - .SH DESCRIPTION .PP This command keeps a simple database of the packages available for @@ -47,11 +46,13 @@ The behavior of the \fBpackage\fR command is determined by its first argument. The following forms are permitted: .TP \fBpackage forget ?\fIpackage package ...\fR? +. Removes all information about each specified package from this interpreter, including information provided by both \fBpackage ifneeded\fR and \fBpackage provide\fR. .TP \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR? +. This command typically appears only in system configuration scripts to set up the package database. It indicates that a particular version of @@ -73,6 +74,7 @@ or an empty string if no \fBpackage ifneeded\fR command has been invoked for this \fIpackage\fR and \fIversion\fR. .TP \fBpackage names\fR +. Returns a list of the names of all packages in the interpreter for which a version has been provided (via \fBpackage provide\fR) or for which a \fBpackage ifneeded\fR @@ -80,10 +82,12 @@ script is available. The order of elements in the list is arbitrary. .TP \fBpackage present\fR +. This command is equivalent to \fBpackage require\fR except that it does not try and load the package if it is not already loaded. .TP \fBpackage provide \fIpackage \fR?\fIversion\fR? +. This command is invoked to indicate that version \fIversion\fR of package \fIpackage\fR is now present in the interpreter. It is typically invoked once as part of an \fBifneeded\fR script, @@ -96,6 +100,7 @@ empty string if no \fBpackage provide\fR command has been invoked for \fIpackage\fR in this interpreter. .TP \fBpackage require \fR\fIpackage \fR?\fIrequirement...\fR? +. This command is typically invoked by Tcl code that wishes to use a particular version of a particular package. The arguments indicate which package is wanted, and the command ensures that @@ -141,11 +146,13 @@ package, then the command returns an error. .RE .TP \fBpackage require \-exact \fIpackage version\fR +. This form of the command is used when only the given \fIversion\fR of \fIpackage\fR is acceptable to the caller. This command is equivalent to \fBpackage require \fIpackage version\fR-\fIversion\fR. .TP \fBpackage unknown \fR?\fIcommand\fR? +. This command supplies a .QW "last resort" command to invoke during @@ -167,30 +174,36 @@ If \fIcommand\fR is specified as an empty string, then the current \fBpackage unknown\fR script is removed, if there is one. .TP \fBpackage vcompare \fIversion1 version2\fR +. Compares the two version numbers given by \fIversion1\fR and \fIversion2\fR. Returns -1 if \fIversion1\fR is an earlier version than \fIversion2\fR, 0 if they are equal, and 1 if \fIversion1\fR is later than \fBversion2\fR. .TP \fBpackage versions \fIpackage\fR +. Returns a list of all the version numbers of \fIpackage\fR for which information has been provided by \fBpackage ifneeded\fR commands. .TP \fBpackage vsatisfies \fIversion requirement...\fR +. Returns 1 if the \fIversion\fR satisfies at least one of the given requirements, and 0 otherwise. Each \fIrequirement\fR is allowed to have any of the forms: .RS .TP min +. This form is called .QW min-bounded . .TP min- +. This form is called .QW min-unbound . .TP min-max +. This form is called .QW bounded . .RE @@ -329,8 +342,10 @@ Once you have done this, packages will be loaded automatically in response to \fBpackage require\fR commands. See the documentation for \fBpkg_mkIndex\fR for details. .SH EXAMPLES +.PP To state that a Tcl script requires the Tk and http packages, put this at the top of the script: +.PP .CS \fBpackage require\fR Tk \fBpackage require\fR http @@ -339,6 +354,7 @@ at the top of the script: To test to see if the Snack package is available and load if it is (often useful for optional enhancements to programs where the loss of the functionality is not critical) do this: +.PP .CS if {[catch {\fBpackage require\fR Snack}]} { # Error thrown - package not found. diff --git a/doc/prefix.n b/doc/prefix.n index f72c4be..6247583 100644 --- a/doc/prefix.n +++ b/doc/prefix.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: prefix.n,v 1.2 2008/10/03 13:24:45 dkf Exp $ +'\" RCS: @(#) $Id: prefix.n,v 1.3 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH prefix n 8.6 Tcl "Tcl Built-In Commands" @@ -20,18 +20,22 @@ prefix \- Facilities for prefix matching .fi .BE .SH DESCRIPTION +.PP This document describes commands looking up a prefix in a list of strings. The following commands are supported: .TP \fB::tcl::prefix all\fR \fItable\fR \fIstring\fR +. Returns a list of all elements in \fItable\fR that begins with the prefix \fIstring\fR. .TP \fB::tcl::prefix longest\fR \fItable\fR \fIstring\fR +. Returns the longest common prefix among all elements in \fItable\fR that begins with the prefix \fIstring\fR. .TP \fB::tcl::prefix match\fR ?\fIoptions\fR? \fItable\fR \fIstring\fR +. If \fIstring\fR equals one element in \fItable\fR or is a prefix to exactly one element, the matched element is returned. If not, the result depends on the \fB\-error\fR option. @@ -54,6 +58,7 @@ message. The default corresponds to setting Example: If \fB\-error\fR "\-errorcode MyError \-level 1" is used, an error would be generated as: .RS +.PP .CS return \-errorcode MyError \-level 1 \-code error "ErrMsg" .CE @@ -61,6 +66,7 @@ return \-errorcode MyError \-level 1 \-code error "ErrMsg" .SH "EXAMPLES" .PP Basic use: +.PP .CS namespace import ::tcl::prefix \fBprefix match\fR {apa bepa cepa} apa @@ -78,6 +84,7 @@ namespace import ::tcl::prefix .CE .PP Simplifying option matching: +.PP .CS array set opts {\-apa 1 \-bepa "" \-cepa 0} foreach {arg val} $args { @@ -86,6 +93,7 @@ foreach {arg val} $args { .CE .PP Switch supporting prefixes: +.PP .CS switch [prefix match {apa bepa cepa} $arg] { apa { } diff --git a/doc/proc.n b/doc/proc.n index 30b8bba..bed20a0 100644 --- a/doc/proc.n +++ b/doc/proc.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: proc.n,v 1.10 2008/01/17 00:56:49 msofer Exp $ +'\" RCS: @(#) $Id: proc.n,v 1.11 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH proc n "" Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ proc \- Create a Tcl procedure .SH SYNOPSIS \fBproc \fIname args body\fR .BE - .SH DESCRIPTION .PP The \fBproc\fR command creates a new Tcl procedure named @@ -76,8 +75,10 @@ executed in the procedure's body. If an error occurs while executing the procedure body, then the procedure-as-a-whole will return that same error. .SH EXAMPLES +.PP This is a procedure that accepts arbitrarily many arguments and prints them out, one by one. +.PP .CS \fBproc\fR printArguments args { foreach arg $args { @@ -89,15 +90,14 @@ them out, one by one. 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: +.PP .CS \fBproc\fR mult {varName {multiplier 2}} { upvar 1 $varName var set var [expr {$var * $multiplier}] } .CE - .SH "SEE ALSO" info(n), unknown(n) - .SH KEYWORDS argument, procedure diff --git a/doc/puts.n b/doc/puts.n index ac579c9..45e67b7 100644 --- a/doc/puts.n +++ b/doc/puts.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: puts.n,v 1.13 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: puts.n,v 1.14 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH puts n 7.5 Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ puts \- Write to a channel .SH SYNOPSIS \fBputs \fR?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR .BE - .SH DESCRIPTION .PP Writes the characters given by \fIstring\fR to the channel given @@ -66,33 +65,36 @@ be used in an event-driven fashion with the \fBfileevent\fR command (do not invoke \fBputs\fR unless you have recently been notified via a file event that the channel is ready for more output data). .SH EXAMPLES +.PP Write a short message to the console (or wherever \fBstdout\fR is directed): +.PP .CS \fBputs\fR "Hello, World!" .CE .PP Print a message in several parts: +.PP .CS \fBputs\fR -nonewline "Hello, " \fBputs\fR "World!" .CE .PP Print a message to the standard error channel: +.PP .CS \fBputs\fR stderr "Hello, World!" .CE .PP Append a log message to a file: +.PP .CS set chan [open my.log a] set timestamp [clock format [clock seconds]] \fBputs\fR $chan "$timestamp - Hello, World!" close $chan .CE - .SH "SEE ALSO" file(n), fileevent(n), Tcl_StandardChannels(3) - .SH KEYWORDS channel, newline, output, write diff --git a/doc/pwd.n b/doc/pwd.n index aeb94c5..7761aab 100644 --- a/doc/pwd.n +++ b/doc/pwd.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: pwd.n,v 1.7 2007/02/18 18:42:55 dkf Exp $ +'\" RCS: @(#) $Id: pwd.n,v 1.8 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH pwd n "" Tcl "Tcl Built-In Commands" @@ -16,17 +16,18 @@ pwd \- Return the absolute path of the current working directory .SH SYNOPSIS \fBpwd\fR .BE - .SH DESCRIPTION .PP Returns the absolute path name of the current working directory. .SH EXAMPLE +.PP Sometimes it is useful to change to a known directory when running some external command using \fBexec\fR, but it is important to keep the application usually running in the directory that it was started in (unless the user specifies otherwise) since that minimizes user confusion. The way to do this is to save the current directory while the external command is being run: +.PP .CS set tarFile [file normalize somefile.tar] set savedDir [\fBpwd\fR] @@ -36,6 +37,5 @@ cd $savedDir .CE .SH "SEE ALSO" file(n), cd(n), glob(n), filename(n) - .SH KEYWORDS working directory diff --git a/doc/read.n b/doc/read.n index 7465f10..72db6ed 100644 --- a/doc/read.n +++ b/doc/read.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.15 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: read.n,v 1.16 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH read n 8.1 Tcl "Tcl Built-In Commands" @@ -18,7 +18,6 @@ read \- Read from a channel .sp \fBread \fIchannelId numChars\fR .BE - .SH DESCRIPTION .PP In the first form, the \fBread\fR command reads all of the data from @@ -53,36 +52,37 @@ newline characters according to the \fB\-translation\fR option for the channel. See the \fBfconfigure\fR manual entry for a discussion on ways in which \fBfconfigure\fR will alter input. - .SH "USE WITH SERIAL PORTS" '\" Note: this advice actually applies to many versions of Tcl - +.PP For most applications a channel connected to a serial port should be configured to be nonblocking: \fBfconfigure \fIchannelId \fB\-blocking \fI0\fR. Then \fBread\fR behaves much like described above. Care must be taken when using \fBread\fR on blocking serial ports: .TP \fBread \fIchannelId numChars\fR +. In this form \fBread\fR blocks until \fInumChars\fR have been received from the serial port. .TP \fBread \fIchannelId\fR +. 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" +.PP 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: +.PP .CS set fl [open /proc/meminfo] set data [\fBread\fR $fl] close $fl set lines [split $data \en] .CE - .SH "SEE ALSO" file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3) - .SH KEYWORDS blocking, channel, end of line, end of file, nonblocking, read, translation, encoding diff --git a/doc/regexp.n b/doc/regexp.n index 7da20eb..4bdf467 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.31 2008/09/23 13:22:18 dkf Exp $ +'\" RCS: @(#) $Id: regexp.n,v 1.32 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH regexp n 8.3 Tcl "Tcl Built-In Commands" @@ -122,12 +122,15 @@ list will be concatenated at each iteration, such that a flat list is always returned. For each match iteration, the command will append the overall match data, plus one element for each subexpression in the regular expression. Examples are: +.RS +.PP .CS \fBregexp\fR -inline -- {\ew(\ew)} " inlined " \fI\(-> in n\fR \fBregexp\fR -all -inline -- {\ew(\ew)} " inlined " \fI\(-> in n li i ne e\fR .CE +.RE .TP 15 \fB\-start\fR \fIindex\fR . @@ -160,9 +163,11 @@ if \fB\-indices\fR has been specified or to an empty string otherwise. 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: +.PP .CS \fBregexp\fR {\emfoo(?!bar\eM)(\ew*)} $string \-> restOfWord .CE +.PP Note that the whole matched substring has been placed in the variable .QW \fB\->\fR , which is a name chosen to look nice given that we are not @@ -170,17 +175,21 @@ 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: +.PP .CS \fBregexp\fR \-indices {(?i)\embadger\eM} $string location .CE +.PP This could also be written as a \fIbasic\fR regular expression (as opposed to using the default syntax of \fIadvanced\fR regular expressions) match by prefixing the expression with a suitable flag: +.PP .CS \fBregexp\fR \-indices {(?ib)\e} $string location .CE .PP This counts the number of octal digits in a string: +.PP .CS \fBregexp\fR \-all {[0\-7]} $string .CE @@ -188,6 +197,7 @@ This counts the number of octal digits in a string: This lists all words (consisting of all sequences of non-whitespace characters) in a string, and is useful as a more powerful version of the \fBsplit\fR command: +.PP .CS \fBregexp\fR \-all \-inline {\eS+} $string .CE diff --git a/doc/regsub.n b/doc/regsub.n index f3371e6..33a2e6f 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.25 2008/09/23 13:22:18 dkf Exp $ +'\" RCS: @(#) $Id: regsub.n,v 1.26 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH regsub n 8.3 Tcl "Tcl Built-In Commands" @@ -148,24 +148,29 @@ of regular expressions. .PP Replace (in the string in variable \fIstring\fR) every instance of \fBfoo\fR which is a word by itself with \fBbar\fR: +.PP .CS \fBregsub\fR -all {\emfoo\eM} $string bar string .CE +.PP or (using the .QW "basic regular expression" syntax): +.PP .CS \fBregsub\fR -all {(?b)\e} $string bar string .CE .PP Insert double-quotes around the first instance of the word \fBinteresting\fR, however it is capitalized. +.PP .CS \fBregsub\fR -nocase {\eyinteresting\ey} $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: +.PP .CS # This RE is just a character class for everything "bad" set RE {[][{};#\e\e\e$\es\eu0080-\euffff]} diff --git a/doc/rename.n b/doc/rename.n index fde6d1c..7852937 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.5 2004/10/27 14:24:37 dkf Exp $ +'\" RCS: @(#) $Id: rename.n,v 1.6 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH rename n "" Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ rename \- Rename or delete a command .SH SYNOPSIS \fBrename \fIoldName newName\fR .BE - .SH DESCRIPTION .PP Rename the command that used to be called \fIoldName\fR so that it @@ -28,9 +27,11 @@ If a command is renamed into a different namespace, future invocations of it will execute in the new namespace. The \fBrename\fR command returns an empty string as result. .SH EXAMPLE +.PP 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: +.PP .CS \fBrename\fR ::source ::theRealSource set sourceCount 0 @@ -40,9 +41,7 @@ proc ::source args { uplevel 1 ::theRealSource $args } .CE - .SH "SEE ALSO" namespace(n), proc(n) - .SH KEYWORDS command, delete, namespace, rename diff --git a/doc/return.n b/doc/return.n index 7432491..5630206 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.20 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: return.n,v 1.21 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH return n 8.5 Tcl "Tcl Built-In Commands" @@ -211,6 +211,7 @@ to be \fBTCL_RETURN\fR, triggering a return from the enclosing procedure. .PP First, a simple example of using \fBreturn\fR to return from a procedure, interrupting the procedure body. +.PP .CS proc printOneLine {} { puts "line 1" ;# This line will be printed. @@ -221,6 +222,7 @@ proc printOneLine {} { .PP Next, an example of using \fBreturn\fR to set the value returned by the procedure. +.PP .CS proc returnX {} {\fBreturn\fR X} puts [returnX] ;# prints "X" @@ -228,6 +230,7 @@ puts [returnX] ;# prints "X" .PP Next, a more complete example, using \fBreturn -code error\fR to report invalid arguments. +.PP .CS proc factorial {n} { if {![string is integer $n] || ($n < 0)} { @@ -253,6 +256,7 @@ proc factorial {n} { .CE .PP Next, a procedure replacement for \fBbreak\fR. +.PP .CS proc myBreak {} { \fBreturn\fR -code break @@ -260,13 +264,15 @@ proc myBreak {} { .CE .PP With the \fB\-level 0\fR option, \fBreturn\fR itself can serve -as a replacement for \fBbreak\fR. +as a replacement for \fBbreak\fR, with the help of \fBinterp alias\fR. +.PP .CS 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: +.PP .CS proc doSomething {} { set resource [allocate] @@ -281,6 +287,7 @@ proc doSomething {} { .PP Finally an example of advanced use of the \fBreturn\fR options to create a procedure replacement for \fBreturn\fR itself: +.PP .CS proc myReturn {args} { set result "" diff --git a/doc/scan.n b/doc/scan.n index 621e919..4612467 100644 --- a/doc/scan.n +++ b/doc/scan.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: scan.n,v 1.25 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: scan.n,v 1.26 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH scan n 8.4 Tcl "Tcl Built-In Commands" @@ -205,6 +205,7 @@ performed and no variables are given, an empty string is returned. .SH EXAMPLES .PP Convert a UNICODE character to its numeric value: +.PP .CS set char "x" set value [\fBscan\fR $char %c] @@ -212,6 +213,7 @@ set value [\fBscan\fR $char %c] .PP Parse a simple color specification of the form \fI#RRGGBB\fR using hexadecimal conversions with substring sizes: +.PP .CS set string "#08D03F" \fBscan\fR $string "#%2x%2x%2x" r g b @@ -220,6 +222,7 @@ set string "#08D03F" 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): +.PP .CS set string "08:08" ;# *Not* octal! if {[\fBscan\fR $string "%d:%d" hours minutes] != 2} { @@ -234,6 +237,7 @@ if {$minutes < 0 || $minutes > 59} { 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): +.PP .CS set string " a string {with braced words} + leading space " set words {} @@ -245,6 +249,7 @@ while {[\fBscan\fR $string %s%n word length] == 2} { .PP Parse a simple coordinate string, checking that it is complete by looking for the terminating character explicitly: +.PP .CS set string "(5.2,-4e-2)" # Note that the spaces before the literal parts of @@ -261,6 +266,7 @@ puts "X=$x, Y=$y" .PP An interactive session demonstrating the truncation of integer values determined by size modifiers: +.PP .CS % set tcl_platform(wordSize) 4 diff --git a/doc/seek.n b/doc/seek.n index 6883b98..9bc0923 100644 --- a/doc/seek.n +++ b/doc/seek.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: seek.n,v 1.9 2005/05/10 18:34:03 kennykb Exp $ +'\" RCS: @(#) $Id: seek.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH seek n 8.1 Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ seek \- Change the access position for an open channel .SH SYNOPSIS \fBseek \fIchannelId offset \fR?\fIorigin\fR? .BE - .SH DESCRIPTION .PP Changes the current access position for \fIchannelId\fR. @@ -32,20 +31,23 @@ for \fIchannelId\fR. \fIOffset\fR must be an integer (which may be negative) and \fIorigin\fR must be one of the following: .TP 10 \fBstart\fR +. The new access position will be \fIoffset\fR bytes from the start of the underlying file or device. .TP 10 \fBcurrent\fR +. The new access position will be \fIoffset\fR bytes from the current access position; a negative \fIoffset\fR moves the access position backwards in the underlying file or device. .TP 10 \fBend\fR +. The new access position will be \fIoffset\fR bytes from the end of the file or device. A negative \fIoffset\fR places the access position before the end of file, and a positive \fIoffset\fR places the access position after the end of file. -.LP +.PP The \fIorigin\fR argument defaults to \fBstart\fR. .PP The command flushes all buffered output for the channel before the command @@ -59,17 +61,20 @@ Note that \fIoffset\fR values are byte offsets, not character offsets. Both \fBseek\fR and \fBtell\fR operate in terms of bytes, not characters, unlike \fBread\fR. .SH EXAMPLES +.PP Read a file twice: +.PP .CS set f [open file.txt] set data1 [read $f] \fBseek\fR $f 0 set data2 [read $f] close $f -# $data1 == $data2 if the file wasn't updated +# $data1 eq $data2 if the file wasn't updated .CE .PP Read the last 10 bytes from a file: +.PP .CS set f [open file.data] # This is guaranteed to work with binary data but @@ -79,9 +84,7 @@ fconfigure $f -translation binary set data [read $f 10] close $f .CE - .SH "SEE ALSO" file(n), open(n), close(n), gets(n), tell(n), Tcl_StandardChannels(3) - .SH KEYWORDS access position, file, seek diff --git a/doc/self.n b/doc/self.n index 2c66edb..7e564b7 100644 --- a/doc/self.n +++ b/doc/self.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: self.n,v 1.1 2008/05/31 11:42:13 dkf Exp $ +'\" RCS: @(#) $Id: self.n,v 1.2 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH self n 0.1 TclOO "TclOO Commands" @@ -19,7 +19,6 @@ package require TclOO \fBself\fR ?\fIsubcommand\fR? .fi .BE - .SH DESCRIPTION The \fBself\fR command, which should only be used from within the context of a call to a method (i.e. inside a method, constructor or destructor body) is @@ -87,8 +86,10 @@ element list describing the method being filtered. The first element will be the name of the declarer of the method, and the second element will be the actual name of the method. .SH EXAMPLES +.PP This example shows basic use of \fBself\fR to provide information about the current object: +.PP .CS oo::class create c { method foo {} { @@ -104,7 +105,6 @@ b foo \fI\(-> prints "this is the ::b object"\fR info(n), next(n) .SH KEYWORDS call, introspection, object - .\" Local variables: .\" mode: nroff .\" fill-column: 78 diff --git a/doc/set.n b/doc/set.n index b99e4fb..e964425 100644 --- a/doc/set.n +++ b/doc/set.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: set.n,v 1.9 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: set.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH set n "" Tcl "Tcl Built-In Commands" @@ -41,17 +41,21 @@ If a procedure is active and \fIvarName\fR is unqualified, then unless \fIvarName\fR was declared to resolve differently through one of the \fBglobal\fR, \fBvariable\fR or \fBupvar\fR commands. .SH EXAMPLES +.PP Store a random number in the variable \fIr\fR: +.PP .CS \fBset\fR r [expr {rand()}] .CE .PP Store a short message in an array element: +.PP .CS \fBset\fR anAry(msg) "Hello, World!" .CE .PP Store a short message in an array element specified by a variable: +.PP .CS \fBset\fR elemName "msg" \fBset\fR anAry($elemName) "Hello, World!" @@ -60,6 +64,7 @@ Store a short message in an array element specified by a variable: 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): +.PP .CS \fBset\fR in0 "small random" \fBset\fR in1 "large random" diff --git a/doc/socket.n b/doc/socket.n index bb14993..45e2986 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.15 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: socket.n,v 1.16 2008/10/17 10:22:25 dkf Exp $ .so man.macros .TH socket n 8.0 Tcl "Tcl Built-In Commands" .BS @@ -18,7 +18,6 @@ socket \- Open a TCP network connection .sp \fBsocket\fR \fB\-server \fIcommand\fR ?\fIoptions\fR? \fIport\fR .BE - .SH DESCRIPTION .PP This command opens a network socket and returns a channel @@ -54,6 +53,7 @@ The following options may also be present before \fIhost\fR to specify additional information about the connection: .TP \fB\-myaddr\fI addr\fR +. \fIAddr\fR gives the domain-style name or numerical IP address of the client-side network interface to use for the connection. This option may be useful if the client machine has multiple network @@ -61,6 +61,7 @@ interfaces. If the option is omitted then the client-side interface will be chosen by the system software. .TP \fB\-myport\fI port\fR +. \fIPort\fR specifies an integer port number (or service name, where supported and understood by the host operating system) to use for the client's @@ -68,6 +69,7 @@ side of the connection. If this option is omitted, the client's port number will be chosen at random by the system software. .TP \fB\-async\fR +. The \fB\-async\fR option will cause the client socket to be connected asynchronously. This means that the socket will be created immediately but may not yet be connected to the server, when the call to \fBsocket\fR @@ -80,6 +82,7 @@ returns immediately and \fBfblocked\fR on the socket returns 1. Synchronous client sockets may be switched (after they have connected) to operating in asynchronous mode using: .RS +.PP .CS \fBfconfigure \fIchan \fB\-blocking 0\fR .CE @@ -104,6 +107,7 @@ the client's port number. The following additional option may also be specified before \fIhost\fR: .TP \fB\-myaddr\fI addr\fR +. \fIAddr\fR gives the domain-style name or numerical IP address of the server-side network interface to use for the connection. This option may be useful if the server machine has multiple network @@ -129,22 +133,26 @@ 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" +.PP The \fBfconfigure\fR command can be used to query several readonly configuration options for socket channels: .TP \fB\-error\fR +. This option gets the current error status of the given socket. This is useful when you need to determine if an asynchronous connect operation succeeded. If there was an error, the error message is returned. If there was no error, an empty string is returned. .TP \fB\-sockname\fR +. This option returns a list of three elements, the address, the host name and the port number for the socket. If the host name cannot be computed, the second element is identical to the address, the first element of the list. .TP \fB\-peername\fR +. This option is not supported by server sockets. For client and accepted sockets, this option returns a list of three elements; these are the address, the host name and the port to which the peer socket is connected @@ -152,7 +160,9 @@ 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" +.PP Here is a very simple time server: +.PP .CS proc Server {channel clientaddr clientport} { puts "Connection from $clientaddr registered" @@ -165,6 +175,7 @@ vwait forever .CE .PP And here is the corresponding client to talk to the server: +.PP .CS set server localhost set sockChan [\fBsocket\fR $server 9900] @@ -172,9 +183,7 @@ gets $sockChan line close $sockChan puts "The time on $server is $line" .CE - .SH "SEE ALSO" fconfigure(n), flush(n), open(n), read(n) - .SH KEYWORDS bind, channel, connection, domain name, host, network address, socket, tcp diff --git a/doc/source.n b/doc/source.n index 6428d80..49ecbf7 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.19 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: source.n,v 1.20 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH source n "" Tcl "Tcl Built-In Commands" @@ -52,12 +52,14 @@ is omitted, the system encoding is assumed. .PP Run the script in the file \fBfoo.tcl\fR and then the script in the file \fBbar.tcl\fR: +.PP .CS \fBsource\fR foo.tcl \fBsource\fR bar.tcl .CE .PP Alternatively: +.PP .CS foreach scriptFile {foo.tcl bar.tcl} { \fBsource\fR $scriptFile diff --git a/doc/split.n b/doc/split.n index 4defc5c..ef5470b 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.10 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: split.n,v 1.11 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH split n "" Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ split \- Split a string into a proper Tcl list .SH SYNOPSIS \fBsplit \fIstring \fR?\fIsplitChars\fR? .BE - .SH DESCRIPTION .PP Returns a list created by splitting \fIstring\fR at each character @@ -31,34 +30,41 @@ If \fIsplitChars\fR is an empty string then each character of \fIstring\fR becomes a separate element of the result list. \fISplitChars\fR defaults to the standard white-space characters. .SH EXAMPLES +.PP Divide up a USENET group name into its hierarchical components: +.PP .CS -\fBsplit\fR "comp.lang.tcl.announce" . - \fI\(-> comp lang tcl announce\fR +\fBsplit\fR "comp.lang.tcl" . + \fI\(-> comp lang tcl\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: +.PP .CS \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: +.PP .CS \fBsplit\fR "Example with {unbalanced brace character" \fI\(-> Example with \e{unbalanced brace character\fR .CE .PP Split a string into its constituent characters +.PP .CS \fBsplit\fR "Hello world" {} \fI\(-> H e l l o { } w o r l d\fR .CE .SS "PARSING RECORD-ORIENTED FILES" +.PP Parse a Unix /etc/passwd file, which consists of one entry per line, with each line consisting of a colon-separated list of fields: +.PP .CS ## Read the file set fid [open /etc/passwd] @@ -80,9 +86,7 @@ foreach rec $records { puts "$longName uses [file tail $shell] for a login shell" } .CE - .SH "SEE ALSO" join(n), list(n), string(n) - .SH KEYWORDS list, split, string diff --git a/doc/string.n b/doc/string.n index d0cb8d8..6e4a8a4 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.44 2008/06/29 22:28:24 dkf Exp $ +.\" RCS: @(#) $Id: string.n,v 1.45 2008/10/17 10:22:25 dkf Exp $ .\" .so man.macros .TH string n 8.1 Tcl "Tcl Built-In Commands" @@ -61,13 +61,17 @@ forms accepted by the \fBindex\fR method), then the search is constrained to start with the character in \fIhaystackString\fR specified by the index. For example, .RS +.PP .CS \fBstring first a 0a23456789abcdef 5\fR .CE +.PP will return \fB10\fR, but +.PP .CS \fBstring first a 0123456789abcdef 11\fR .CE +.PP will return \fB\-1\fR. .RE .TP @@ -207,13 +211,17 @@ of the forms accepted by the \fBindex\fR method), then only the characters in \fIhaystackString\fR at or before the specified \fIlastIndex\fR will be considered by the search. For example, .RS +.PP .CS \fBstring last a 0a23456789abcdef 15\fR .CE +.PP will return \fB10\fR, but +.PP .CS \fBstring last a 0a23456789abcdef 9\fR .CE +.PP will return \fB1\fR. .RE .TP @@ -238,17 +246,21 @@ appearing first in the list will be checked first, and so on. \fIstring\fR is only iterated over once, so earlier key replacements will have no affect for later key matches. For example, .RS +.PP .CS \fBstring map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc\fR .CE +.PP will return the string \fB01321221\fR. .PP Note that if an earlier \fIkey\fR is a prefix of a later one, it will completely mask the later one. So if the previous example is reordered like this, +.PP .CS \fBstring map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc\fR .CE +.PP it will return the string \fB02c322c222c\fR. .RE .TP @@ -392,6 +404,7 @@ single character other than these. .PP Test if the string in the variable \fIstring\fR is a proper non-empty prefix of the string \fBfoobar\fR. +.PP .CS set length [\fBstring length\fR $string] if {$length == 0} { diff --git a/doc/subst.n b/doc/subst.n index 75fe00f..3685c0f 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.16 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: subst.n,v 1.17 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH subst n 7.4 Tcl "Tcl Built-In Commands" @@ -64,19 +64,23 @@ itself will either return an error, or will complete successfully. 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 +.PP .CS set a 44 \fBsubst\fR {xyz {$a}} .CE +.PP returns .QW "\fBxyz {44}\fR" , not .QW "\fBxyz {$a}\fR" and the script +.PP .CS set a "p\e} q \e{r" \fBsubst\fR {xyz {$a}} .CE +.PP returns .QW "\fBxyz {p} q {r}\fR" , not @@ -84,10 +88,12 @@ not .PP When command substitution is performed, it includes any variable substitution necessary to evaluate the script. +.PP .CS set a 44 \fBsubst\fR -novariables {$a [format $a]} .CE +.PP returns .QW "\fB$a 44\fR" , not @@ -95,11 +101,13 @@ not Similarly, when variable substitution is performed, it includes any command substitution necessary to retrieve the value of the variable. +.PP .CS proc b {} {return c} array set a {c c [b] tricky} \fBsubst\fR -nocommands {[b] $a([b])} .CE +.PP returns .QW "\fB[b] c\fR" , not @@ -109,34 +117,42 @@ The continue and break exceptions allow command substitutions to 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 +.PP .CS \fBsubst\fR {abc,[break],def} .CE +.PP returns .QW \fBabc,\fR , not .QW \fBabc,,def\fR and the script +.PP .CS \fBsubst\fR {abc,[continue;expr {1+2}],def} .CE +.PP returns .QW \fBabc,,def\fR , not .QW \fBabc,3,def\fR . .PP Other exceptional return codes substitute the returned value +.PP .CS \fBsubst\fR {abc,[return foo;expr {1+2}],def} .CE +.PP returns .QW \fBabc,foo,def\fR , not .QW \fBabc,3,def\fR and +.PP .CS \fBsubst\fR {abc,[return -code 10 foo;expr {1+2}],def} .CE +.PP also returns .QW \fBabc,foo,def\fR , not @@ -145,3 +161,6 @@ not Tcl(n), eval(n), break(n), continue(n) .SH KEYWORDS backslash substitution, command substitution, variable substitution +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/doc/switch.n b/doc/switch.n index 21ecfc2..2f638de 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.19 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: switch.n,v 1.20 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH switch n 8.5 Tcl "Tcl Built-In Commands" @@ -124,8 +124,10 @@ 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" +.PP The \fBswitch\fR command can match against variables and not just literals, as shown here (the result is \fI2\fR): +.PP .CS set foo "abc" \fBswitch\fR abc a \- b {expr {1}} $foo {expr {2}} default {expr {3}} @@ -134,6 +136,7 @@ set foo "abc" 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): +.PP .CS \fBswitch\fR \-glob aaab { a*b \- @@ -145,6 +148,7 @@ writing regular expressions with alternations, as can be seen here .PP Whenever nothing matches, the \fBdefault\fR clause (which must be last) is taken. This example has a result of \fI3\fR: +.PP .CS \fBswitch\fR xyz { a \- @@ -163,6 +167,7 @@ last) is taken. This example has a result of \fI3\fR: .PP When matching against regular expressions, information about what exactly matched is easily obtained using the \fB\-matchvar\fR option: +.PP .CS \fBswitch\fR \-regexp \-matchvar foo \-\- $bar { a(b*)c { diff --git a/doc/tclsh.1 b/doc/tclsh.1 index 71932e1..db07346 100644 --- a/doc/tclsh.1 +++ b/doc/tclsh.1 @@ -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: tclsh.1,v 1.15 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: tclsh.1,v 1.16 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH tclsh 1 "" Tcl "Tcl Applications" @@ -55,9 +55,11 @@ of a script file is presented on the \fBtclsh\fR command line, but the script file can always \fBsource\fR it if desired. .PP If you create a Tcl script in a file whose first line is +.PP .CS \fB#!/usr/local/bin/tclsh\fR .CE +.PP then you can invoke the script file directly from your shell if you mark the file as executable. This assumes that \fBtclsh\fR has been installed in the default @@ -69,6 +71,7 @@ executable can be accessed with a short file name. .PP An even better approach is to start your script files with the following three lines: +.PP .CS \fB#!/bin/sh # the next line restarts using tclsh \e diff --git a/doc/tcltest.n b/doc/tcltest.n index 88320cc..82691f9 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.56 2008/07/13 23:15:23 nijtmans Exp $ +'\" RCS: @(#) $Id: tcltest.n,v 1.57 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH "tcltest" n 2.3 tcltest "Tcl Bundled Packages" @@ -1128,3 +1128,6 @@ 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 +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/doc/tell.n b/doc/tell.n index a25b111..c62b22a 100644 --- a/doc/tell.n +++ b/doc/tell.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: tell.n,v 1.9 2005/05/10 18:34:03 kennykb Exp $ +'\" RCS: @(#) $Id: tell.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH tell n 8.1 Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ tell \- Return current access position for an open channel .SH SYNOPSIS \fBtell \fIchannelId\fR .BE - .SH DESCRIPTION .PP Returns an integer string giving the current access position in @@ -31,7 +30,9 @@ Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), the return value from an invocation of \fBopen\fR or \fBsocket\fR, or the result of a channel creation command provided by a Tcl extension. .SH EXAMPLE +.PP Read a line from a file channel only if it starts with \fBfoobar\fR: +.PP .CS # Save the offset in case we need to undo the read... set offset [\fBtell\fR $chan] @@ -43,9 +44,7 @@ if {[read $chan 6] eq "foobar"} { seek $chan $offset } .CE - .SH "SEE ALSO" file(n), open(n), close(n), gets(n), seek(n), Tcl_StandardChannels(3) - .SH KEYWORDS access position, channel, seeking diff --git a/doc/time.n b/doc/time.n index fff9274..9d7aa5f 100644 --- a/doc/time.n +++ b/doc/time.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: time.n,v 1.9 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: time.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH time n "" Tcl "Tcl Built-In Commands" @@ -16,21 +16,23 @@ time \- Time the execution of a script .SH SYNOPSIS \fBtime \fIscript\fR ?\fIcount\fR? .BE - .SH DESCRIPTION .PP This command will call the Tcl interpreter \fIcount\fR times to evaluate \fIscript\fR (or once if \fIcount\fR is not specified). It will then return a string of the form +.PP .CS -\fB503 microseconds per iteration\fR +\fB503.2 microseconds per iteration\fR .CE +.PP which indicates the average amount of time required per iteration, in microseconds. Time is measured in elapsed time, not CPU time. .SH EXAMPLE Estimate how long it takes for a simple Tcl \fBfor\fR loop to count to a thousand: +.PP .CS time { for {set i 0} {$i<1000} {incr i} { @@ -38,9 +40,10 @@ time { } } .CE - .SH "SEE ALSO" clock(n) - .SH KEYWORDS script, time +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/doc/tm.n b/doc/tm.n index 3deca0f..59980f0 100644 --- a/doc/tm.n +++ b/doc/tm.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: tm.n,v 1.17 2008/09/26 19:54:56 dgp Exp $ +'\" RCS: @(#) $Id: tm.n,v 1.18 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH tm n 8.5 Tcl "Tcl Built-In Commands" @@ -79,6 +79,7 @@ additional root paths beyond those described by this document. A Tcl Module is a Tcl Package contained in a single file, and no other files required by it. This file has to be \fBsource\fRable. In other words, a Tcl Module is always imported via: +.PP .CS source module_file .CE @@ -92,6 +93,7 @@ attached data in any it chooses to fully import and activate the package. .PP The name of a module file has to match the regular expression: +.PP .CS ([[:alpha:]][:[:alnum:]]*)-([[:digit:]].*)\e.tm .CE @@ -100,11 +102,12 @@ The first capturing parentheses provides the name of the package, the second clause its version. In addition to matching the pattern, the extracted version number must not raise an error when used in the command: +.PP .CS package vcompare $version 0 .CE -.PP .SH "FINDING MODULES" +.PP The directory tree for storing Tcl modules is separate from other parts of the filesystem and independent of \fBauto_path\fR. .PP @@ -165,10 +168,13 @@ Note that packages in module form have \fIno\fR control over the \fIindex\fR and \fIprovide script\fRs entered into the package database for them. For a module file \fBMF\fR the \fIindex script\fR is always: +.PP .CS package ifneeded \fBPNAME PVERSION\fR [list source \fBMF\fR] .CE +.PP and the \fIprovide script\fR embedded in the above is: +.PP .CS source \fBMF\fR .CE @@ -176,6 +182,7 @@ source \fBMF\fR Both package name \fBPNAME\fR and package version \fBPVERSION\fR are extracted from the filename \fBMF\fR according to the definition below: +.PP .CS \fBMF\fR = /module_path/\fBPNAME\(fm\fR-\fBPVERSION\fR.tm .CE @@ -224,6 +231,7 @@ to the minor version of the interpreter. .RS .PP For example for Tcl 8.4 the paths searched are: +.PP .CS \fB[info library]/../tcl8/8.4\fR \fB[info library]/../tcl8/8.3\fR @@ -277,6 +285,7 @@ These paths are seen and therefore shared by all Tcl shells in the Note that \fIX\fR and \fIy\fR follow the general rules set out above. In other words, Tcl 8.4, for example, will look at these 5 environment variables: +.PP .CS \fB$::env(TCL8.4_TM_PATH)\fR \fB$::env(TCL8_4_TM_PATH)\fR \fB$::env(TCL8.3_TM_PATH)\fR \fB$::env(TCL8_3_TM_PATH)\fR @@ -292,3 +301,6 @@ package(n), Tcl Improvement Proposal #189 (online at http://tip.tcl.tk/190.html) .SH "KEYWORDS" modules, package +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/doc/trace.n b/doc/trace.n index 88a9e81..37e5532 100644 --- a/doc/trace.n +++ b/doc/trace.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: trace.n,v 1.26 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: trace.n,v 1.27 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH trace n "8.4" Tcl "Tcl Built-In Commands" @@ -56,9 +56,11 @@ execute them. When the trace triggers, depending on the operations being traced, a number of arguments are appended to \fIcommandPrefix\fR so that the actual command is as follows: +.PP .CS \fIcommandPrefix oldName newName op\fR .CE +.PP \fIOldName\fR and \fInewName\fR give the traced command's current (old) name, and the name to which it is being renamed (the empty string if this is a .QW delete @@ -123,9 +125,11 @@ number of arguments are appended to \fIcommandPrefix\fR so that the actual command is as follows: .PP For \fBenter\fR and \fBenterstep\fR operations: +.PP .CS \fIcommandPrefix command-string op\fR .CE +.PP \fICommand-string\fR gives the complete current command being executed (the traced command for a \fBenter\fR operation, an arbitrary command for a \fBenterstep\fR operation), including @@ -139,9 +143,11 @@ course when the command is subsequently executed, an error will occur. .PP For \fBleave\fR and \fBleavestep\fR operations: +.PP .CS \fIcommand command-string code result op\fR .CE +.PP \fICommand-string\fR gives the complete current command being executed (the traced command for a \fBenter\fR operation, an arbitrary command for a \fBenterstep\fR operation), including @@ -219,9 +225,11 @@ interpreter in which to execute them. .PP When the trace triggers, three arguments are appended to \fIcommandPrefix\fR so that the actual command is as follows: +.PP .CS \fIcommandPrefix name1 name2 op\fR .CE +.PP \fIName1\fR and \fIname2\fR give the name(s) for the variable being accessed: if the variable is a scalar then \fIname1\fR gives the variable's name and \fIname2\fR is an empty string; @@ -370,9 +378,11 @@ future version of Tcl. They use an older syntax in which \fBarray\fR, list, but simply a string concatenation of the operations, such as \fBrwua\fR. .SH EXAMPLES +.PP Print a message whenever either of the global variables \fBfoo\fR and \fBbar\fR are updated, even if they have a different local name at the time (which can be done with the \fBupvar\fR command): +.PP .CS proc tracer {varname args} { upvar #0 $varname var @@ -384,6 +394,7 @@ proc tracer {varname args} { .PP Ensure that the global variable \fBfoobar\fR always contains the product of the global variables \fBfoo\fR and \fBbar\fR: +.PP .CS proc doMult args { global foo bar foobar @@ -395,6 +406,7 @@ proc doMult args { .PP Print a trace of what commands are executed during the processing of a Tcl procedure: +.PP .CS proc x {} { y } proc y {} { z } @@ -411,3 +423,6 @@ x set(n), unset(n) .SH KEYWORDS read, command, rename, variable, write, trace, unset +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/doc/unload.n b/doc/unload.n index b02c124..965149a 100644 --- a/doc/unload.n +++ b/doc/unload.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: unload.n,v 1.12 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: unload.n,v 1.13 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH unload n 8.5 Tcl "Tcl Built-In Commands" @@ -90,6 +90,7 @@ detached from the process. .SS "UNLOAD HOOK PROTOTYPE" .PP The unload procedure must match the following prototype: +.PP .CS typedef int \fBTcl_PackageUnloadProc\fR( Tcl_Interp *\fIinterp\fR, @@ -149,10 +150,13 @@ from the application while some interpreters will continue to use it). .PP If an unloadable module in the file \fBfoobar.dll\fR had been loaded using the \fBload\fR command like this (on Windows): +.PP .CS load c:/some/dir/foobar.dll .CE +.PP then it would be unloaded like this: +.PP .CS \fBunload\fR c:/some/dir/foobar.dll .CE @@ -165,3 +169,6 @@ without having to shut down the overall Tcl process. info sharedlibextension, load(n), safe(n) .SH KEYWORDS binary code, unloading, safe interpreter, shared library +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/doc/unset.n b/doc/unset.n index ab8e4e1..2608051 100644 --- a/doc/unset.n +++ b/doc/unset.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: unset.n,v 1.13 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: unset.n,v 1.14 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH unset n 8.4 Tcl "Tcl Built-In Commands" @@ -37,8 +37,10 @@ deleted. An error can occur when the named variable does not exist, or the name refers to an array element but the variable is a scalar, or the name refers to a variable in a non-existent namespace. .SH EXAMPLE +.PP Create an array containing a mapping from some numbers to their squares and remove the array elements for non-prime numbers: +.PP .CS array set squares { 1 1 6 36 diff --git a/doc/update.n b/doc/update.n index 2738782..91f329c 100644 --- a/doc/update.n +++ b/doc/update.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: update.n,v 1.10 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: update.n,v 1.11 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH update n 7.5 Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ update \- Process pending events and idle callbacks .SH SYNOPSIS \fBupdate\fR ?\fBidletasks\fR? .BE - .SH DESCRIPTION .PP This command is used to bring the application @@ -45,7 +44,9 @@ the application to respond to events such as user interactions; if you occasionally call \fBupdate\fR then user input will be processed during the next call to \fBupdate\fR. .SH EXAMPLE +.PP Run computations for about a second and then finish: +.PP .CS set x 1000 set done 0 @@ -60,9 +61,7 @@ while {!$done} { \fBupdate\fR } .CE - .SH "SEE ALSO" after(n), interp(n) - .SH KEYWORDS event, flush, handler, idle, update diff --git a/doc/uplevel.n b/doc/uplevel.n index d1e5dc1..f4a26e7 100644 --- a/doc/uplevel.n +++ b/doc/uplevel.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: uplevel.n,v 1.10 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: uplevel.n,v 1.11 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH uplevel n "" Tcl "Tcl Built-In Commands" @@ -42,16 +42,20 @@ at top-level (only global variables will be visible). The \fBuplevel\fR command causes the invoking procedure to disappear from the procedure calling stack while the command is being executed. In the above example, suppose \fBc\fR invokes the command +.PP .CS \fBuplevel\fR 1 {set x 43; d} .CE +.PP where \fBd\fR is another Tcl procedure. The \fBset\fR command will modify the variable \fBx\fR in \fBb\fR's context, and \fBd\fR will execute at level 3, as if called from \fBb\fR. If it in turn executes the command +.PP .CS \fBuplevel\fR {set x 42} .CE +.PP then the \fBset\fR command will modify the same variable \fBx\fR in \fBb\fR's context: the procedure \fBc\fR does not appear to be on the call stack when \fBd\fR is executing. The \fBinfo level\fR command may @@ -77,6 +81,7 @@ control constructs. This example shows how (without error handling) it can be used to create a \fBdo\fR command that is the counterpart of \fBwhile\fR except for always performing the test after running the loop body: +.PP .CS proc do {body while condition} { if {$while ne "while"} { @@ -95,3 +100,6 @@ proc do {body while condition} { apply(n), namespace(n), upvar(n) .SH KEYWORDS context, level, namespace, stack frame, variables +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/doc/upvar.n b/doc/upvar.n index 214aea9..8242a43 100644 --- a/doc/upvar.n +++ b/doc/upvar.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: upvar.n,v 1.16 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: upvar.n,v 1.17 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH upvar n "" Tcl "Tcl Built-In Commands" @@ -45,12 +45,14 @@ The \fBupvar\fR command simplifies the implementation of call-by-name procedure calling and also makes it easier to build new control constructs as Tcl procedures. For example, consider the following procedure: +.PP .CS proc \fIadd2\fR name { \fBupvar\fR $name x set x [expr {$x + 2}] } .CE +.PP If \fIadd2\fR is invoked with an argument giving the name of a variable, it adds two to the value of that variable. Although \fIadd2\fR could have been implemented using \fBuplevel\fR @@ -85,6 +87,7 @@ will be .QW "\fIlocalVar\fR" rather than .QW "\fIoriginalVar\fR" : +.PP .CS proc \fItraceproc\fR { name index op } { puts $name @@ -106,15 +109,17 @@ made to \fImyVar\fR will not be passed to subprocesses correctly. .SH EXAMPLE A \fBdecr\fR command that works like \fBincr\fR except it subtracts the value from the variable instead of adding it: +.PP .CS proc decr {varName {decrement 1}} { \fBupvar\fR 1 $varName var incr var [expr {-$decrement}] } .CE - .SH "SEE ALSO" global(n), namespace(n), uplevel(n), variable(n) - .SH KEYWORDS context, frame, global, level, namespace, procedure, variable +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/doc/variable.n b/doc/variable.n index 0bb7ce9..5497977 100644 --- a/doc/variable.n +++ b/doc/variable.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: variable.n,v 1.11 2008/10/02 19:18:12 mistachkin Exp $ +'\" RCS: @(#) $Id: variable.n,v 1.12 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH variable n 8.0 Tcl "Tcl Built-In Commands" @@ -18,7 +18,6 @@ variable \- create and initialize a namespace variable .sp \fBvariable \fR?\fIname value...\fR? .BE - .SH DESCRIPTION .PP This command is normally used within a @@ -61,7 +60,9 @@ After the variable has been declared, elements within the array can be set using ordinary \fBset\fR or \fBarray\fR commands. .SH EXAMPLES +.PP Create a variable in a namespace: +.PP .CS namespace eval foo { \fBvariable\fR bar 12345 @@ -69,6 +70,7 @@ namespace eval foo { .CE .PP Create an array in a namespace: +.PP .CS namespace eval someNS { \fBvariable\fR someAry @@ -80,6 +82,7 @@ namespace eval someNS { .CE .PP Access variables in namespaces from a procedure: +.PP .CS namespace eval foo { proc spong {} { @@ -93,9 +96,7 @@ namespace eval foo { } } .CE - .SH "SEE ALSO" global(n), namespace(n), upvar(n) - .SH KEYWORDS global, namespace, procedure, variable diff --git a/doc/vwait.n b/doc/vwait.n index 1982c9a..89796c6 100644 --- a/doc/vwait.n +++ b/doc/vwait.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: vwait.n,v 1.7 2008/01/09 08:09:56 georgeps Exp $ +'\" RCS: @(#) $Id: vwait.n,v 1.8 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH vwait n 8.0 Tcl "Tcl Built-In Commands" @@ -15,7 +15,6 @@ vwait \- Process events until a variable is written .SH SYNOPSIS \fBvwait\fR \fIvarName\fR .BE - .SH DESCRIPTION .PP This command enters the Tcl event loop to process events, blocking @@ -36,15 +35,18 @@ for a long time. During this time the top-level \fBvwait\fR is blocked waiting for the event handler to complete, so it cannot return either. .SH EXAMPLES +.PP Run the event-loop continually until some event calls \fBexit\fR. (You can use any variable not mentioned elsewhere, but the name \fIforever\fR reminds you at a glance of the intent.) +.PP .CS \fBvwait\fR forever .CE .PP Wait five seconds for a connection to a server socket, otherwise close the socket and continue running the script: +.PP .CS # Initialise the state after 5000 set state timeout @@ -73,9 +75,7 @@ switch $state { } } .CE - .SH "SEE ALSO" global(n), update(n) - .SH KEYWORDS event, variable, wait diff --git a/doc/while.n b/doc/while.n index bd74f45..cc4921c 100644 --- a/doc/while.n +++ b/doc/while.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: while.n,v 1.5 2004/10/27 14:43:54 dkf Exp $ +'\" RCS: @(#) $Id: while.n,v 1.6 2008/10/17 10:22:25 dkf Exp $ '\" .so man.macros .TH while n "" Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ while \- Execute script repeatedly as long as a condition is met .SH SYNOPSIS \fBwhile \fItest body\fR .BE - .SH DESCRIPTION .PP The \fBwhile\fR command evaluates \fItest\fR as an expression @@ -43,6 +42,7 @@ expression is evaluated (before each loop iteration), so changes in the variables will be visible. For an example, try the following script with and without the braces around \fB$x<10\fR: +.PP .CS set x 0 \fBwhile\fR {$x<10} { @@ -51,17 +51,17 @@ set x 0 } .CE .SH EXAMPLE +.PP Read lines from a channel until we get to the end of the stream, and print them out with a line-number prepended: +.PP .CS set lineCount 0 \fBwhile\fR {[gets $chan line] >= 0} { puts "[incr lineCount]: $line" } .CE - .SH "SEE ALSO" break(n), continue(n), for(n), foreach(n) - .SH KEYWORDS boolean value, loop, test, while -- cgit v0.12