Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
| Comment: | * changes: Updated for 8.5b2 release. * doc/*.1: Revert doc changes that broke * doc/*.3: `make html` so we can get the release * doc/*.n: out the door. |
|---|---|
| Downloads: | Tarball | ZIP archive | SQL archive |
| Timelines: | family | ancestors | descendants | both | trunk | core-8-5-b2 |
| Files: | files | file ages | folders |
| SHA1: |
b67e3f215e5ed2c3abc44b48bd54a2c3 |
| User & Date: | dgp 2007-10-26 20:11:50 |
Context
|
2007-10-26
| ||
| 23:52 | Make the man->HTML scraper work better. check-in: 84dfc4343b user: dkf tags: trunk | |
| 20:11 |
* changes: Updated for 8.5b2 release. * doc/*.1: Revert d...check-in: b67e3f215e user: dgp tags: trunk, core-8-5-b2 | |
| 16:54 | tag: 8.5b2 check-in: 3b4a8c5724 user: dgp tags: trunk | |
Changes
Changes to ChangeLog.
1 1 2007-10-26 Don Porter <[email protected]> 2 2 3 3 *** 8.5b2 TAGGED FOR RELEASE *** 4 4 5 5 * changes: Updated for 8.5b2 release. 6 + 7 + * doc/*.1: Revert doc changes that broke 8 + * doc/*.3: `make html` so we can get the release 9 + * doc/*.n: out the door. 6 10 7 11 * README: Bump version number to 8.5b2. 8 12 * generic/tcl.h: 9 13 * library/init.tcl: 10 14 * tools/tcl.wse.in: 11 15 * unix/configure.in: 12 16 * unix/tcl.spec:
Changes to changes.
1 1 Recent user-visible changes to Tcl: 2 2 3 -RCS: @(#) $Id: changes,v 1.120 2007/10/26 15:53:43 dgp Exp $ 3 +RCS: @(#) $Id: changes,v 1.121 2007/10/26 20:11:50 dgp Exp $ 4 4 5 5 1. No more [command1] [command2] construct for grouping multiple 6 6 commands on a single command line. 7 7 8 8 2. Semi-colon now available for grouping commands on a line. 9 9 10 10 3. For a command to span multiple lines, must now use backslash-return ................................................................................ 7031 7031 7032 7032 2007-10-11 (bug fix)[1805887] [string is int -failindex] for 0o, 0b (porter) 7033 7033 7034 7034 2007-10-15 (bug fix)[1813528] Tcl_ParseBraces read past buffer (mistachkin) 7035 7035 7036 7036 2007-10-25 (bug fix)[1726873] intermittent crash in threads (vasiljevic) 7037 7037 7038 -New doc macros for improved formatting. Docs updated to use. (fellows) 7039 - 7040 7038 --- Released 8.5b2, October 26, 2007 --- See ChangeLog for details ---
Changes to doc/AppInit.3.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: AppInit.3,v 1.6 2007/10/24 14:29:37 dkf Exp $ 8 +'\" RCS: @(#) $Id: AppInit.3,v 1.7 2007/10/26 20:11:51 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_AppInit \- perform application-specific initialization 15 15 .SH SYNOPSIS ................................................................................ 22 22 .AS Tcl_Interp *interp 23 23 .AP Tcl_Interp *interp in 24 24 Interpreter for the application. 25 25 .BE 26 26 27 27 .SH DESCRIPTION 28 28 .PP 29 -\fBTcl_AppInit\fR is a 30 -.QW hook 31 -procedure that is invoked by 29 +\fBTcl_AppInit\fR is a ``hook'' procedure that is invoked by 32 30 the main programs for Tcl applications such as \fBtclsh\fR and \fBwish\fR. 33 31 Its purpose is to allow new Tcl applications to be created without 34 32 modifying the main programs provided as part of Tcl and Tk. 35 33 To create a new application you write a new version of 36 34 \fBTcl_AppInit\fR to replace the default version provided by Tcl, 37 35 then link your new \fBTcl_AppInit\fR with the Tcl library. 38 36 .PP
Changes to doc/BackgdErr.3.
1 1 '\" 2 2 '\" Copyright (c) 1992-1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: BackgdErr.3,v 1.5 2007/10/24 14:29:37 dkf Exp $ 8 +'\" RCS: @(#) $Id: BackgdErr.3,v 1.6 2007/10/26 20:11:51 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_BackgroundError \- report Tcl error that occurred in background processing 15 15 .SH SYNOPSIS ................................................................................ 22 22 .AP Tcl_Interp *interp in 23 23 Interpreter in which the error occurred. 24 24 .BE 25 25 26 26 .SH DESCRIPTION 27 27 .PP 28 28 This procedure is typically invoked when a Tcl error occurs during 29 -.QW "background processing" 30 -such as executing an event handler. 29 +``background processing'' such as executing an event handler. 31 30 When such an error occurs, the error condition is reported to Tcl 32 31 or to a widget or some other C code, and there is not usually any 33 32 obvious way for that code to report the error to the user. 34 33 In these cases the code calls \fBTcl_BackgroundError\fR with an 35 34 \fIinterp\fR argument identifying the interpreter in which the 36 35 error occurred. At the time \fBTcl_BackgroundError\fR is invoked, 37 36 the interpreter's result is expected to contain an error message.
Changes to doc/CrtChannel.3.
1 1 '\" 2 2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc. 3 3 '\" Copyright (c) 1997-2000 Ajuba Solutions. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: CrtChannel.3,v 1.36 2007/10/24 14:29:37 dkf Exp $ 8 +'\" RCS: @(#) $Id: CrtChannel.3,v 1.37 2007/10/26 20:11:51 dgp Exp $ 9 9 .so man.macros 10 10 .TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures" 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels 15 15 .SH SYNOPSIS ................................................................................ 869 869 .CS 870 870 bad option "-blah": should be one of -blocking, 871 871 -buffering, -buffersize, -eofchar, -translation, 872 872 -peername, or -sockname 873 873 .CE 874 874 when called with \fIoptionList\fR="peername sockname" 875 875 .PP 876 -.QW blah 877 -is the \fIoptionName\fR argument and 878 -.QW "<specific options>" 876 +``blah'' is the \fIoptionName\fR argument and ``<specific options>'' 879 877 is a space separated list of specific option words. 880 878 The function takes good care of inserting minus signs before 881 -each option, commas after, and an 882 -.QW or 883 -before the last option. 879 +each option, commas after, and an ``or'' before the last option. 884 880 .SH "OLD CHANNEL TYPES" 885 881 The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains 886 882 the following fields: 887 883 .PP 888 884 .CS 889 885 typedef struct Tcl_ChannelType { 890 886 char *\fItypeName\fR;
Changes to doc/CrtSlave.3.
1 1 '\" 2 2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: CrtSlave.3,v 1.17 2007/10/24 14:29:37 dkf Exp $ 7 +'\" RCS: @(#) $Id: CrtSlave.3,v 1.18 2007/10/26 20:11:51 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures" 11 11 .BS 12 12 .SH NAME 13 13 Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands 14 14 .SH SYNOPSIS ................................................................................ 57 57 .SH ARGUMENTS 58 58 .AS "const char *const" **targetInterpPtr out 59 59 .AP Tcl_Interp *interp in 60 60 Interpreter in which to execute the specified command. 61 61 .AP "const char" *slaveName in 62 62 Name of slave interpreter to create or manipulate. 63 63 .AP int isSafe in 64 -If non-zero, a 65 -.QW safe 66 -slave that is suitable for running untrusted code 64 +If non-zero, a ``safe'' slave that is suitable for running untrusted code 67 65 is created, otherwise a trusted slave is created. 68 66 .AP Tcl_Interp *slaveInterp in 69 67 Interpreter to use for creating the source command for an alias (see 70 68 below). 71 69 .AP "const char" *slaveCmd in 72 70 Name of source command for alias. 73 71 .AP Tcl_Interp *targetInterp in ................................................................................ 124 122 then the \fBresult\fR field of the interpreter contains an error message. 125 123 .PP 126 124 \fBTcl_CreateSlave\fR creates a new interpreter as a slave of \fIinterp\fR. 127 125 It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which 128 126 allows \fIinterp\fR to manipulate the new slave. 129 127 If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl 130 128 code has access to all the Tcl commands. 131 -If it is \fB1\fR, the command creates a 132 -.QW safe 133 -slave in which Tcl code has access only to set of Tcl commands defined as 134 -.QW "Safe Tcl" ; 135 -see the manual entry for the Tcl \fBinterp\fR command for details. 129 +If it is \fB1\fR, the command creates a ``safe'' slave in which Tcl code 130 +has access only to set of Tcl commands defined as ``Safe Tcl''; see the 131 +manual entry for the Tcl \fBinterp\fR command for details. 136 132 If the creation of the new slave interpreter failed, \fBNULL\fR is returned. 137 133 .PP 138 -\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is 139 -.QW safe 140 -(was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified), 134 +\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is ``safe'' (was created 135 +with the \fBTCL_SAFE_INTERPRETER\fR flag specified), 141 136 \fB0\fR otherwise. 142 137 .PP 143 -\fBTcl_MakeSafe\fR marks \fIinterp\fR as 144 -.QW safe , 145 -so that future 138 +\fBTcl_MakeSafe\fR marks \fIinterp\fR as ``safe'', so that future 146 139 calls to \fBTcl_IsSafe\fR will return 1. It also removes all known 147 140 potentially-unsafe core functionality (both commands and variables) 148 141 from \fIinterp\fR. However, it cannot know what parts of an extension 149 142 or application are safe and does not make any attempt to remove those 150 143 parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR. 151 144 Callers will want to take care with their use of \fBTcl_MakeSafe\fR 152 145 to avoid false claims of safety. For many situations, \fBTcl_CreateSlave\fR
Changes to doc/DString.3.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: DString.3,v 1.14 2007/10/24 14:29:37 dkf Exp $ 8 +'\" RCS: @(#) $Id: DString.3,v 1.15 2007/10/26 20:11:51 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings 15 15 .SH SYNOPSIS ................................................................................ 89 89 \fBTcl_DStringAppendElement\fR is similar to \fBTcl_DStringAppend\fR 90 90 except that it doesn't take a \fIlength\fR argument (it appends 91 91 all of \fIelement\fR) and it converts the string to a proper list element 92 92 before appending. 93 93 \fBTcl_DStringAppendElement\fR adds a separator space before the 94 94 new list element unless the new list element is the first in a 95 95 list or sub-list (i.e. either the current string is empty, or it 96 -contains the single character 97 -.QW { , 98 -or the last two characters of the current string are 99 -.QW " {" ). 96 +contains the single character ``{'', or the last two characters of 97 +the current string are `` {''). 100 98 \fBTcl_DStringAppendElement\fR returns a pointer to the 101 99 characters of the new string. 102 100 .PP 103 101 \fBTcl_DStringStartSublist\fR and \fBTcl_DStringEndSublist\fR can be 104 102 used to create nested lists. 105 103 To append a list element that is itself a sublist, first 106 104 call \fBTcl_DStringStartSublist\fR, then call \fBTcl_DStringAppendElement\fR
Changes to doc/Encoding.3.
1 1 '\" 2 2 '\" Copyright (c) 1997-1998 Sun Microsystems, Inc. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: Encoding.3,v 1.26 2007/10/24 14:29:37 dkf Exp $ 7 +'\" RCS: @(#) $Id: Encoding.3,v 1.27 2007/10/26 20:11:51 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures" 11 11 .BS 12 12 .SH NAME 13 13 Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings 14 14 .SH SYNOPSIS ................................................................................ 453 453 ignored. 454 454 .PP 455 455 \fBTcl_GetDefaultEncodingDir\fR and \fBTcl_SetDefaultEncodingDir\fR 456 456 are obsolete interfaces best replaced with calls to 457 457 \fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR. 458 458 They are called to access and set the first element of the \fIsearchPath\fR 459 459 list. Since Tcl searches \fIsearchPath\fR for encoding data files in 460 -list order, these routines establish the 461 -.QW default 462 -directory in which to find encoding data files. 460 +list order, these routines establish the ``default'' directory in which 461 +to find encoding data files. 463 462 .VE 8.5 464 463 .SH "ENCODING FILES" 465 464 Space would prohibit precompiling into Tcl every possible encoding 466 465 algorithm, so many encodings are stored on disk as dynamically-loadable 467 466 encoding files. This behavior also allows the user to create additional 468 467 encoding files that can be loaded using the same mechanism. These 469 468 encoding files contain information about the tables and/or escape 470 469 sequences used to map between an external encoding and Unicode. The 471 470 external encoding may consist of single-byte, multi-byte, or double-byte 472 471 characters. 473 472 .PP 474 473 Each dynamically-loadable encoding is represented as a text file. The 475 -initial line of the file, beginning with a 476 -.QW # 477 -symbol, is a comment 474 +initial line of the file, beginning with a ``#'' symbol, is a comment 478 475 that provides a human-readable description of the file. The next line 479 476 identifies the type of encoding file. It can be one of the following 480 477 letters: 481 478 .IP "[1] \fBS\fR" 482 479 A single-byte encoding, where one character is always one byte long in the 483 480 encoding. An example is \fBiso8859-1\fR, used by many European languages. 484 481 .IP "[2] \fBD\fR" ................................................................................ 583 580 .PP 584 581 In the file, the first column represents an option and the second column 585 582 is the associated value. \fBinit\fR is a string to emit or expect before 586 583 the first character is converted, while \fBfinal\fR is a string to emit 587 584 or expect after the last character. All other options are names of 588 585 table-based encodings; the associated value is the escape-sequence that 589 586 marks that encoding. Tcl syntax is used for the values; in the above 590 -example, for instance, 591 -.QW \fB{}\fR 592 -represents the empty string and 593 -.QW \fB\ex1b\fR 594 -represents character 27. 587 +example, for instance, ``\fB{}\fR'' represents the empty string and 588 +``\fB\\x1b\fR'' represents character 27. 595 589 .PP 596 590 When \fBTcl_GetEncoding\fR encounters an encoding \fIname\fR that has not 597 591 been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR 598 592 from the \fBencoding\fR subdirectory of each directory that Tcl searches 599 593 for its script library. If the encoding file exists, but is 600 594 malformed, an error message will be left in \fIinterp\fR. 601 595 .SH KEYWORDS 602 596 utf, encoding, convert
Changes to doc/Eval.3.
2 2 '\" Copyright (c) 1989-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2000 Scriptics Corporation. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: Eval.3,v 1.24 2007/10/24 14:29:37 dkf Exp $ 9 +'\" RCS: @(#) $Id: Eval.3,v 1.25 2007/10/26 20:11:51 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures" 13 13 .BS 14 14 .SH NAME 15 15 Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts 16 16 .SH SYNOPSIS ................................................................................ 97 97 .PP 98 98 \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates 99 99 its contents as a Tcl script. It returns the same information as 100 100 \fBTcl_EvalObjEx\fR. 101 101 If the file couldn't be read then a Tcl error is returned to describe 102 102 why the file couldn't be read. 103 103 The eofchar for files is '\\32' (^Z) for all platforms. 104 -If you require a 105 -.QW ^Z 106 -in code for string comparison, you can use 107 -.QW \e032 108 -or 109 -.QW \eu001a , 110 -which will be safely substituted by the Tcl interpreter into 111 -.QW ^Z . 104 +If you require a ``^Z'' in code for string comparison, you can use 105 +``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl 106 +interpreter into ``^Z''. 112 107 .PP 113 108 \fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a 114 109 script. The \fIobjc\fR and \fIobjv\fR arguments contain the values 115 110 of the words for the Tcl command, one word in each object in 116 111 \fIobjv\fR. \fBTcl_EvalObjv\fR evaluates the command and returns 117 112 a completion code and result just like \fBTcl_EvalObjEx\fR. 118 113 The caller of \fBTcl_EvalObjv\fR has to manage the reference count of the
Changes to doc/ExprLong.3.
1 1 '\" 2 2 '\" Copyright (c) 1989-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: ExprLong.3,v 1.12 2007/10/24 14:29:37 dkf Exp $ 8 +'\" RCS: @(#) $Id: ExprLong.3,v 1.13 2007/10/26 20:11:51 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString \- evaluate an expression 15 15 .SH SYNOPSIS ................................................................................ 87 87 an error is returned. 88 88 .PP 89 89 \fBTcl_ExprBoolean\fR stores a 0/1 integer value at \fI*booleanPtr\fR. 90 90 If the expression's actual value is an integer or floating-point 91 91 number, then they store 0 at \fI*booleanPtr\fR if 92 92 the value was zero and 1 otherwise. 93 93 If the expression's actual value is a non-numeric string then 94 -it must be one of the values accepted by \fBTcl_GetBoolean\fR such as 95 -.QW yes 96 -or 97 -.QW no , 98 -or else an error occurs. 94 +it must be one of the values accepted by \fBTcl_GetBoolean\fR 95 +such as ``yes'' or ``no'', or else an error occurs. 99 96 .PP 100 97 \fBTcl_ExprString\fR returns the value of the expression as a 101 98 string stored in the interpreter's result. 102 99 103 100 .SH "SEE ALSO" 104 101 Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj 105 102 106 103 .SH KEYWORDS 107 104 boolean, double, evaluate, expression, integer, object, string
Changes to doc/ExprLongObj.3.
1 1 '\" 2 2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: ExprLongObj.3,v 1.6 2007/10/24 14:29:37 dkf Exp $ 7 +'\" RCS: @(#) $Id: ExprLongObj.3,v 1.7 2007/10/26 20:11:51 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH Tcl_ExprLongObj 3 8.0 Tcl "Tcl Library Procedures" 11 11 .BS 12 12 .SH NAME 13 13 Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj \- evaluate an expression 14 14 .SH SYNOPSIS ................................................................................ 83 83 an error is returned. 84 84 .PP 85 85 \fBTcl_ExprBooleanObj\fR stores a 0/1 integer value at \fI*booleanPtr\fR. 86 86 If the expression's actual value is an integer or floating-point 87 87 number, then they store 0 at \fI*booleanPtr\fR if 88 88 the value was zero and 1 otherwise. 89 89 If the expression's actual value is a non-numeric string then 90 -it must be one of the values accepted by \fBTcl_GetBoolean\fR such as 91 -.QW yes 92 -or 93 -.QW no , 94 -or else an error occurs. 90 +it must be one of the values accepted by \fBTcl_GetBoolean\fR 91 +such as ``yes'' or ``no'', or else an error occurs. 95 92 .PP 96 93 If \fBTcl_ExprObj\fR successfully evaluates the expression, 97 94 it stores a pointer to the Tcl object 98 95 containing the expression's value at \fI*resultPtrPtr\fR. 99 96 In this case, the caller is responsible for calling 100 97 \fBTcl_DecrRefCount\fR to decrement the object's reference count 101 98 when it is finished with the object. 102 99 103 100 .SH "SEE ALSO" 104 101 Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult 105 102 106 103 .SH KEYWORDS 107 104 boolean, double, evaluate, expression, integer, object, string
Changes to doc/FileSystem.3.
1 1 '\" 2 2 '\" Copyright (c) 2001 Vincent Darley 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: FileSystem.3,v 1.58 2007/10/24 14:29:37 dkf Exp $ 7 +'\" RCS: @(#) $Id: FileSystem.3,v 1.59 2007/10/26 20:11:51 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures" 11 11 .BS 12 12 .SH NAME 13 13 Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSEvalFileEx, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_AllocStatBuf \- procedures to interact with any filesystem 14 14 .SH SYNOPSIS ................................................................................ 348 348 its contents as a Tcl script. It returns the same information as 349 349 \fBTcl_EvalObjEx\fR. 350 350 If \fIencodingName\fR is NULL, the system encoding is used for 351 351 reading the file contents. 352 352 If the file couldn't be read then a Tcl error is returned to describe 353 353 why the file couldn't be read. 354 354 The eofchar for files is '\\32' (^Z) for all platforms. 355 -If you require a 356 -.QW ^Z 357 -in code for string comparison, you can use 358 -.QW \e032 359 -or 360 -.QW \eu001a , 361 -which will be safely substituted by the Tcl interpreter into 362 -.QW ^Z . 355 +If you require a ``^Z'' in code for string comparison, you can use 356 +``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl 357 +interpreter into ``^Z''. 363 358 \fBTcl_FSEvalFile\fR is a simpler version of 364 359 \fBTcl_FSEvalFileEx\fR that always uses the system encoding 365 360 when reading the file. 366 361 .VE 8.5 367 362 .PP 368 363 \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and 369 364 returns the addresses of two procedures within that file, if they are ................................................................................ 846 841 a particular filesystem with a file path, and deal with the internal 847 842 handling of path representations, for example copying and freeing such 848 843 representations. 849 844 .SS TYPENAME 850 845 .PP 851 846 The \fItypeName\fR field contains a null-terminated string that 852 847 identifies the type of the filesystem implemented, e.g. 853 -.QW native , 854 -.QW zip 855 -or 856 -.QW vfs . 848 +``native'' or ``zip'' or ```vfs''. 857 849 .SS "STRUCTURE LENGTH" 858 850 .PP 859 851 The \fIstructureLength\fR field is generally implemented as 860 852 \fIsizeof(Tcl_Filesystem)\fR, and is there to allow easier 861 853 binary backwards compatibility if the size of the structure 862 854 changes in a future Tcl release. 863 855 .SS VERSION
Changes to doc/GetInt.3.
1 1 '\" 2 2 '\" Copyright (c) 1989-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: GetInt.3,v 1.11 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: GetInt.3,v 1.12 2007/10/26 20:11:51 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean \- convert from string to integer, double, or boolean 15 15 .SH SYNOPSIS ................................................................................ 51 51 desired type then \fBTCL_ERROR\fR is returned, an error message is left 52 52 in the interpreter's result, and nothing is stored at *\fIintPtr\fR 53 53 or *\fIdoublePtr\fR or *\fIboolPtr\fR. 54 54 .PP 55 55 \fBTcl_GetInt\fR expects \fIsrc\fR to consist of a collection 56 56 of integer digits, optionally signed and optionally preceded by 57 57 white space. If the first two characters of \fIsrc\fR 58 -after the optional white space and sign are 59 -.QW 0x 58 +after the optional white space and sign are ``0x'' 60 59 then \fIsrc\fR is expected to be in hexadecimal form; otherwise, 61 -if the first such character is 62 -.QW 0 63 -then \fIsrc\fR 60 +if the first such character is ``0'' then \fIsrc\fR 64 61 is expected to be in octal form; otherwise, \fIsrc\fR is 65 62 expected to be in decimal form. 66 63 .PP 67 64 \fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point 68 65 number, which is: white space; a sign; a sequence of digits; a 69 -decimal point; a sequence of digits; the letter 70 -.QW e ; 71 -a signed decimal exponent ; and more white space. 66 +decimal point; a sequence of digits; the letter ``e''; a 67 +signed decimal exponent ; and more white space. 72 68 Any of the fields may be omitted, except that 73 69 the digits either before or after the decimal point must be present 74 -and if the 75 -.QW e 76 -is present then it must be followed by the exponent number. 70 +and if the ``e'' is present then it must be followed by the 71 +exponent number. 77 72 .PP 78 73 \fBTcl_GetBoolean\fR expects \fIsrc\fR to specify a boolean 79 74 value. If \fIsrc\fR is any of \fB0\fR, \fBfalse\fR, 80 75 \fBno\fR, or \fBoff\fR, then \fBTcl_GetBoolean\fR stores a zero 81 76 value at \fI*boolPtr\fR. 82 77 If \fIsrc\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR, 83 78 then 1 is stored at \fI*boolPtr\fR. 84 79 Any of these values may be abbreviated, and upper-case spellings 85 80 are also acceptable. 86 81 87 82 .SH KEYWORDS 88 83 boolean, conversion, double, floating-point, integer
Changes to doc/Hash.3.
1 1 '\" 2 2 '\" Copyright (c) 1989-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: Hash.3,v 1.22 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: Hash.3,v 1.23 2007/10/26 20:11:51 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_InitHashTable, Tcl_InitCustomHashTable, Tcl_InitObjHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats \- procedures to manage hash tables 15 15 .SH SYNOPSIS ................................................................................ 84 84 may have the same value. Keys can take one of four forms: strings, 85 85 one-word values, integer arrays, or custom keys defined by a 86 86 Tcl_HashKeyType structure (See section \fBTHE TCL_HASHKEYTYPE 87 87 STRUCTURE\fR below). All of the keys in a given table have the same 88 88 form, which is specified when the table is initialized. 89 89 .PP 90 90 The value of a hash table entry can be anything that fits in the same 91 -space as a 92 -.QW "char *" 93 -pointer. Values for hash table entries are 91 +space as a ``char *'' pointer. Values for hash table entries are 94 92 managed entirely by clients, not by the hash module itself. Typically 95 93 each entry's value is a pointer to a data structure managed by client 96 94 code. 97 95 .PP 98 96 Hash tables grow gracefully as the number of entries increases, so 99 97 that there are always less than three entries per hash bucket, on 100 98 average. This allows for fast lookups regardless of the number of ................................................................................ 122 120 \fIKeyType\fR must have one of the following values: 123 121 .IP \fBTCL_STRING_KEYS\fR 25 124 122 Keys are null-terminated strings. 125 123 They are passed to hashing routines using the address of the 126 124 first character of the string. 127 125 .IP \fBTCL_ONE_WORD_KEYS\fR 25 128 126 Keys are single-word values; they are passed to hashing routines 129 -and stored in hash table entries as 130 -.QW "char *" 131 -values. 127 +and stored in hash table entries as ``char *'' values. 132 128 The pointer value is the key; it need not (and usually doesn't) 133 129 actually point to a string. 134 130 .IP \fBTCL_CUSTOM_TYPE_KEYS\fR 25 135 131 Keys are of arbitrary type, and are stored in the entry. Hashing 136 132 and comparison is determined by \fItypePtr\fR. The Tcl_HashKeyType 137 133 structure is described in the section 138 134 \fBTHE TCL_HASHKEYTYPE STRUCTURE\fR below. ................................................................................ 140 136 Keys are pointers to an arbitrary type, and are stored in the entry. Hashing 141 137 and comparison is determined by \fItypePtr\fR. The Tcl_HashKeyType 142 138 structure is described in the section 143 139 \fBTHE TCL_HASHKEYTYPE STRUCTURE\fR below. 144 140 .IP \fIother\fR 25 145 141 If \fIkeyType\fR is not one of the above, 146 142 then it must be an integer value greater than 1. 147 -In this case the keys will be arrays of 148 -.QW int 149 -values, where \fIkeyType\fR gives the number of ints in each key. 143 +In this case the keys will be arrays of ``int'' values, where 144 +\fIkeyType\fR gives the number of ints in each key. 150 145 This allows structures to be used as keys. 151 146 All keys must have the same size. 152 147 Array keys are passed into hashing functions using the address 153 148 of the first int in the array. 154 149 .PP 155 150 \fBTcl_DeleteHashTable\fR deletes all of the entries in a hash 156 151 table and frees up the memory associated with the table's ................................................................................ 183 178 .PP 184 179 \fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR 185 180 except that it doesn't create a new entry if the key doesn't exist; 186 181 instead, it returns NULL as result. 187 182 .PP 188 183 \fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to 189 184 read and write an entry's value, respectively. 190 -Values are stored and retrieved as type 191 -.QW ClientData , 192 -which is 185 +Values are stored and retrieved as type ``ClientData'', which is 193 186 large enough to hold a pointer value. On almost all machines this is 194 187 large enough to hold an integer value too. 195 188 .PP 196 189 \fBTcl_GetHashKey\fR returns the key for a given hash table entry, 197 -either as a pointer to a string, a one-word (e.g. 198 -.QW "char *" ) 199 -key, or as a pointer to the first word of an array of integers, depending 190 +either as a pointer to a string, a one-word (``char *'') key, or 191 +as a pointer to the first word of an array of integers, depending 200 192 on the \fIkeyType\fR used to create a hash table. 201 193 In all cases \fBTcl_GetHashKey\fR returns a result with type 202 -.QW "char *" . 194 +``char *''. 203 195 When the key is a string or array, the result of \fBTcl_GetHashKey\fR 204 196 points to information in the table entry; this information will 205 197 remain valid until the entry is deleted or its table is deleted. 206 198 .PP 207 199 \fBTcl_FirstHashEntry\fR and \fBTcl_NextHashEntry\fR may be used 208 -to scan all of the entries in a hash table. A structure of type 209 -.QW Tcl_HashSearch , 210 -provided by the client, is used to keep track of progress through the 211 -table. \fBTcl_FirstHashEntry\fR initializes the search record and 200 +to scan all of the entries in a hash table. 201 +A structure of type ``Tcl_HashSearch'', provided by the client, 202 +is used to keep track of progress through the table. 203 +\fBTcl_FirstHashEntry\fR initializes the search record and 212 204 returns the first entry in the table (or NULL if the table is 213 205 empty). 214 206 Each subsequent call to \fBTcl_NextHashEntry\fR returns the 215 207 next entry in the table or 216 208 NULL if the end of the table has been reached. 217 209 A call to \fBTcl_FirstHashEntry\fR followed by calls to 218 210 \fBTcl_NextHashEntry\fR will return each of the entries in
Changes to doc/LinkVar.3.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: LinkVar.3,v 1.13 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: LinkVar.3,v 1.14 2007/10/26 20:11:51 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable 15 15 .SH SYNOPSIS ................................................................................ 162 162 '\" FIXME! Use bignums instead. 163 163 attempts to write non-integer values into \fIvarName\fR will be 164 164 rejected with Tcl errors. 165 165 .VE 8.5 166 166 .TP 167 167 \fBTCL_LINK_BOOLEAN\fR 168 168 The C variable is of type \fBint\fR. 169 -If its value is zero then it will read from Tcl as 170 -.QW 0 ; 171 -otherwise it will read from Tcl as 172 -.QW 1 . 169 +If its value is zero then it will read from Tcl as ``0''; 170 +otherwise it will read from Tcl as ``1''. 173 171 Whenever \fIvarName\fR is 174 172 modified, the C variable will be set to a 0 or 1 value. 175 173 Any value written into the Tcl variable must have a proper boolean 176 174 form acceptable to \fBTcl_GetBooleanFromObj\fR; attempts to write 177 175 non-boolean values into \fIvarName\fR will be rejected with 178 176 Tcl errors. 179 177 .TP ................................................................................ 181 179 The C variable is of type \fBchar *\fR. 182 180 If its value is not NULL then it must be a pointer to a string 183 181 allocated with \fBTcl_Alloc\fR or \fBckalloc\fR. 184 182 Whenever the Tcl variable is modified the current C string will be 185 183 freed and new memory will be allocated to hold a copy of the variable's 186 184 new value. 187 185 If the C variable contains a NULL pointer then the Tcl variable 188 -will read as 189 -.QW NULL . 186 +will read as ``NULL''. 190 187 .PP 191 188 If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the 192 189 variable will be read-only from Tcl, so that its value can only be 193 190 changed by modifying the C variable. 194 191 Attempts to write the variable from Tcl will be rejected with errors. 195 192 .PP 196 193 \fBTcl_UnlinkVar\fR removes the link previously set up for the
Changes to doc/Notifier.3.
1 1 '\" 2 2 '\" Copyright (c) 1998-1999 Scriptics Corporation 3 3 '\" Copyright (c) 1995-1997 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: Notifier.3,v 1.18 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: Notifier.3,v 1.19 2007/10/26 20:11:51 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Notifier 3 8.1 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces 15 15 .SH SYNOPSIS ................................................................................ 450 450 \fBTcl_InitNotifier\fR initializes the notifier state and returns 451 451 a handle to the notifier state. Tcl calls this 452 452 procedure when initializing a Tcl interpreter. Similarly, 453 453 \fBTcl_FinalizeNotifier\fR shuts down the notifier, and is 454 454 called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter. 455 455 .PP 456 456 \fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier; 457 -it is responsible for waiting for an 458 -.QW interesting 459 -event to occur or 457 +it is responsible for waiting for an ``interesting'' event to occur or 460 458 for a given time to elapse. Before \fBTcl_WaitForEvent\fR is invoked, 461 459 each of the event sources' setup procedure will have been invoked. 462 460 The \fItimePtr\fR argument to 463 461 \fBTcl_WaitForEvent\fR gives the maximum time to block for an event, 464 462 based on calls to \fBTcl_SetMaxBlockTime\fR made by setup procedures 465 463 and on other information (such as the \fBTCL_DONT_WAIT\fR bit in 466 464 \fIflags\fR).
Changes to doc/PrintDbl.3.
1 1 '\" 2 2 '\" Copyright (c) 1989-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: PrintDbl.3,v 1.8 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: PrintDbl.3,v 1.9 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_PrintDouble 3 8.0 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_PrintDouble \- Convert floating value to string 15 15 .SH SYNOPSIS ................................................................................ 32 32 .BE 33 33 34 34 .SH DESCRIPTION 35 35 .PP 36 36 \fBTcl_PrintDouble\fR generates a string that represents the value 37 37 of \fIvalue\fR and stores it in memory at the location given by 38 38 \fIdst\fR. It uses \fB%g\fR format to generate the string, with one 39 -special twist: the string is guaranteed to contain either a 40 -.QW . 41 -or an 42 -.QW e 43 -so that it doesn't look like an integer. Where \fB%g\fR would generate 44 -an integer with no decimal point, \fBTcl_PrintDouble\fR adds 45 -.QW .0 . 39 +special twist: the string is guaranteed to contain either 40 +a ``.'' or an ``e'' so that it doesn't look like an integer. Where 41 +\fB%g\fR would generate an integer with no decimal point, \fBTcl_PrintDouble\fR 42 +adds ``.0''. 46 43 .VS 8.5 47 44 .PP 48 45 If the \fBtcl_precision\fR value is non-zero, the result will have 49 46 precisely that many digits of significance. If the value is zero 50 47 (the default), the result will have the fewest digits needed to 51 48 represent the number in such a way that \fBTcl_NewDoubleObj\fR 52 49 will generate the same number when presented with the given string. 53 50 IEEE semantics of rounding to even apply to the conversion. 54 51 .VE 55 52 56 53 .SH KEYWORDS 57 54 conversion, double-precision, floating-point, string
Changes to doc/RegExp.3.
2 2 '\" Copyright (c) 1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 1998-1999 Scriptics Corporation 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: RegExp.3,v 1.24 2007/10/24 14:29:38 dkf Exp $ 9 +'\" RCS: @(#) $Id: RegExp.3,v 1.25 2007/10/26 20:11:52 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures" 13 13 .BS 14 14 .SH NAME 15 15 Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo \- Pattern matching with regular expressions 16 16 .SH SYNOPSIS ................................................................................ 182 182 long as the internal representation of \fIpatObj\fR refers to the 183 183 compiled form. The \fIeflags\fR argument is a bit-wise OR of 184 184 zero or more of the following flags that control the compilation of 185 185 \fIpatObj\fR: 186 186 .RS 2 187 187 .TP 188 188 \fBTCL_REG_ADVANCED\fR 189 -Compile advanced regular expressions 190 -.PQ ARE s . 191 -This mode corresponds to the normal regular expression syntax accepted by the 192 -Tcl \fBregexp\fR and \fBregsub\fR commands. 189 +Compile advanced regular expressions (`AREs'). This mode corresponds to 190 +the normal regular expression syntax accepted by the Tcl \fBregexp\fR and 191 +\fBregsub\fR commands. 193 192 .TP 194 193 \fBTCL_REG_EXTENDED\fR 195 -Compile extended regular expressions 196 -.PQ ERE s . 197 -This mode corresponds to the regular expression syntax recognized by Tcl 8.0 198 -and earlier versions. 194 +Compile extended regular expressions (`EREs'). This mode corresponds 195 +to the regular expression syntax recognized by Tcl 8.0 and earlier 196 +versions. 199 197 .TP 200 198 \fBTCL_REG_BASIC\fR 201 -Compile basic regular expressions 202 -.PQ BRE s . 203 -This mode corresponds to the regular expression syntax recognized by common 204 -Unix utilities like \fBsed\fR and \fBgrep\fR. This is the default if no flags 205 -are specified. 199 +Compile basic regular expressions (`BREs'). This mode corresponds 200 +to the regular expression syntax recognized by common Unix utilities 201 +like \fBsed\fR and \fBgrep\fR. This is the default if no flags are 202 +specified. 206 203 .TP 207 204 \fBTCL_REG_EXPANDED\fR 208 205 Compile the regular expression (basic, extended, or advanced) using an 209 206 expanded syntax that allows comments and whitespace. This mode causes 210 207 non-backslashed non-bracket-expression white 211 208 space and #-to-end-of-line comments to be ignored. 212 209 .TP ................................................................................ 215 212 .TP 216 213 \fBTCL_REG_NOCASE\fR 217 214 Compile for matching that ignores upper/lower case distinctions. 218 215 .TP 219 216 \fBTCL_REG_NEWLINE\fR 220 217 Compile for newline-sensitive matching. By default, newline is a 221 218 completely ordinary character with no special meaning in either 222 -regular expressions or strings. With this flag, 223 -.QW [^ 224 -bracket expressions and 225 -.QW . 226 -never match newline, 227 -.QW ^ 228 -matches an empty string 229 -after any newline in addition to its normal function, and 230 -.QW $ 231 -matches an empty string before any newline in addition to its normal 232 -function. \fBREG_NEWLINE\fR is the bit-wise OR of \fBREG_NLSTOP\fR and 219 +regular expressions or strings. With this flag, `[^' bracket 220 +expressions and `.' never match newline, `^' matches an empty string 221 +after any newline in addition to its normal function, and `$' matches 222 +an empty string before any newline in addition to its normal function. 223 +\fBREG_NEWLINE\fR is the bit-wise OR of \fBREG_NLSTOP\fR and 233 224 \fBREG_NLANCH\fR. 234 225 .TP 235 226 \fBTCL_REG_NLSTOP\fR 236 -Compile for partial newline-sensitive matching, with the behavior of 237 -.QW [^ 238 -bracket expressions and 239 -.QW . 240 -affected, but not the behavior of 241 -.QW ^ 242 -and 243 -.QW $ . 244 -In this mode, 245 -.QW [^ 246 -bracket expressions and 247 -.QW . 248 -never match newline. 227 +Compile for partial newline-sensitive matching, 228 +with the behavior of 229 +`[^' bracket expressions and `.' affected, 230 +but not the behavior of `^' and `$'. In this mode, `[^' bracket 231 +expressions and `.' never match newline. 249 232 .TP 250 233 \fBTCL_REG_NLANCH\fR 251 -Compile for inverse partial newline-sensitive matching, with the behavior of 252 -.QW ^ 253 -and 254 -.QW $ 255 -(the 256 -.QW anchors ) 257 -affected, but not the behavior of 258 -.QW [^ 259 -bracket expressions and 260 -.QW . . 261 -In this mode 262 -.QW ^ 263 -matches an empty string after any newline in addition to its normal function, 264 -and 265 -.QW $ 266 -matches an empty string before any newline in addition to its normal function. 234 +Compile for inverse partial newline-sensitive matching, 235 +with the behavior 236 +of `^' and `$' (the ``anchors'') affected, but not the behavior of 237 +`[^' bracket expressions and `.'. In this mode `^' matches an empty string 238 +after any newline in addition to its normal function, and `$' matches 239 +an empty string before any newline in addition to its normal function. 267 240 .TP 268 241 \fBTCL_REG_NOSUB\fR 269 242 Compile for matching that reports only success or failure, 270 243 not what was matched. This reduces compile overhead and may improve 271 244 performance. Subsequent calls to \fBTcl_RegExpGetInfo\fR or 272 245 \fBTcl_RegExpRange\fR will not report any match information. 273 246 .TP ................................................................................ 298 271 offset value. Instead the behavior of the anchors is explicitly 299 272 controlled by the \fIeflags\fR argument, which is a bit-wise OR of 300 273 zero or more of the following flags: 301 274 .RS 2 302 275 .TP 303 276 \fBTCL_REG_NOTBOL\fR 304 277 The starting character will not be treated as the beginning of a 305 -line or the beginning of the string, so 306 -.QW ^ 307 -will not match there. Note that this flag has no effect on how 308 -.QW \fB\eA\fR 309 -matches. 278 +line or the beginning of the string, so `^' will not match there. 279 +Note that this flag has no effect on how `\fB\eA\fR' matches. 310 280 .TP 311 281 \fBTCL_REG_NOTEOL\fR 312 282 The last character in the string will not be treated as the end of a 313 -line or the end of the string, so 314 -.QW $ 315 -will not match there. Note that this flag has no effect on how 316 -.QW \fB\eZ\fR 317 -matches. 283 +line or the end of the string, so '$' will not match there. 284 +Note that this flag has no effect on how `\fB\eZ\fR' matches. 318 285 .RE 319 286 .PP 320 287 \fBTcl_RegExpGetInfo\fR retrieves information about the last match 321 288 performed with a given regular expression \fIregexp\fR. The 322 289 \fIinfoPtr\fR argument contains a pointer to a structure that is 323 290 defined as follows: 324 291 .PP
Changes to doc/SetResult.3.
1 1 '\" 2 2 '\" Copyright (c) 1989-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: SetResult.3,v 1.15 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: SetResult.3,v 1.16 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_FreeResult \- manipulate Tcl result 15 15 .SH SYNOPSIS ................................................................................ 159 159 \fIelement\fR will be extracted as a single element. 160 160 Under normal conditions, \fBTcl_AppendElement\fR will add a space 161 161 character to \fIinterp\fR's result just before adding the new 162 162 list element, so that the list elements in the result are properly 163 163 separated. 164 164 However if the new list element is the first in a list or sub-list 165 165 (i.e. \fIinterp\fR's current result is empty, or consists of the 166 -single character 167 -.QW { , 168 -or ends in the characters 169 -.QW " {" ) 170 -then no space is added. 166 +single character ``{'', or ends in the characters `` {'') then no 167 +space is added. 171 168 .PP 172 169 \fBTcl_FreeResult\fR performs part of the work 173 170 of \fBTcl_ResetResult\fR. 174 171 It frees up the memory associated with \fIinterp\fR's result. 175 172 It also sets \fIinterp->freeProc\fR to zero, but doesn't 176 173 change \fIinterp->result\fR or clear error state. 177 174 \fBTcl_FreeResult\fR is most commonly used when a procedure
Changes to doc/SetVar.3.
1 1 '\" 2 2 '\" Copyright (c) 1989-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: SetVar.3,v 1.13 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: SetVar.3,v 1.14 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_SetVar2Ex, Tcl_SetVar, Tcl_SetVar2, Tcl_ObjSetVar2, Tcl_GetVar2Ex, Tcl_GetVar, Tcl_GetVar2, Tcl_ObjGetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables 15 15 .SH SYNOPSIS ................................................................................ 203 203 .TP 204 204 \fBTCL_LIST_ELEMENT\fR 205 205 If this bit is set, then \fInewValue\fR is converted to a valid 206 206 Tcl list element before setting (or appending to) the variable. 207 207 A separator space is appended before the new list element unless 208 208 the list element is going to be the first element in a list or 209 209 sublist (i.e. the variable's current value is empty, or contains 210 -the single character 211 -.QW { , 212 -or ends in 213 -.QW " }" ). 210 +the single character ``{'', or ends in `` }''). 214 211 When appending, the original value of the variable must also be 215 212 a valid list, so that the operation is the appending of a new 216 213 list element onto a list. 217 214 .PP 218 215 \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR 219 216 return the current value of a variable. 220 217 The arguments to these procedures are treated in the same way
Changes to doc/SplitList.3.
1 1 '\" 2 2 '\" Copyright (c) 1989-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: SplitList.3,v 1.10 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: SplitList.3,v 1.11 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement, Tcl_ScanCountedElement, Tcl_ConvertCountedElement \- manipulate Tcl lists 15 15 .SH SYNOPSIS ................................................................................ 165 165 used to generate a portion of an argument for a Tcl command. 166 166 In this case, surrounding \fIsrc\fR with curly braces would cause 167 167 the command not to be parsed correctly. 168 168 .PP 169 169 .VS 8.5 170 170 By default, \fBTcl_ConvertElement\fR will use quoting in its output 171 171 to be sure the first character of an element is not the hash 172 -character (i.e. 173 -.QW # ). 174 -This is to be sure the first element of any list 172 +character (``#''). This is to be sure the first element of any list 175 173 passed to \fBeval\fR is not mis-parsed as the beginning of a comment. 176 174 When a list element is not the first element of a list, this quoting 177 175 is not necessary. When the caller can be sure that the element is 178 176 not the first element of a list, it can disable quoting of the leading 179 177 hash character by OR-ing the flag value returned by \fBTcl_ScanElement\fR 180 178 with \fBTCL_DONT_QUOTE_HASH\fR. 181 179 .VE 8.5
Changes to doc/StdChannels.3.
1 1 '\" 2 2 '\" Copyright (c) 2001 by ActiveState Corporation 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: StdChannels.3,v 1.11 2007/10/24 14:29:38 dkf Exp $ 7 +'\" RCS: @(#) $Id: StdChannels.3,v 1.12 2007/10/26 20:11:52 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH "Standard Channels" 3 7.5 Tcl "Tcl Library Procedures" 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 Tcl_StandardChannels \- How the Tcl library deals with the standard channels ................................................................................ 38 38 .PP 39 39 Standard channels are initialized by the Tcl library in three cases: 40 40 when explicitly requested, when implicitly required before returning 41 41 channel information, or when implicitly required during registration 42 42 of a new channel. 43 43 .PP 44 44 These cases differ in how they handle unavailable platform- specific 45 -standard channels. (A channel is not 46 -.QW available 47 -if it could not be successfully opened; for example, in a Tcl 48 -application run as a Windows NT service.) 45 +standard channels. (A channel is not ``available'' if it could not be 46 +successfully opened; for example, in a Tcl application run as a 47 +Windows NT service.) 49 48 .TP 50 49 1) 51 50 A single standard channel is initialized when it is explicitly 52 51 specified in a call to \fBTcl_SetStdChannel\fR. The states of the 53 52 other standard channels are unaffected. 54 53 .RS 55 54 .PP
Changes to doc/StrMatch.3.
1 1 '\" 2 2 '\" Copyright (c) 1989-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: StrMatch.3,v 1.10 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: StrMatch.3,v 1.11 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_StringMatch 3 8.1 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_StringMatch, Tcl_StringCaseMatch \- test whether a string matches a pattern 15 15 .SH SYNOPSIS ................................................................................ 34 34 .BE 35 35 36 36 .SH DESCRIPTION 37 37 .PP 38 38 This utility procedure determines whether a string matches 39 39 a given pattern. If it does, then \fBTcl_StringMatch\fR returns 40 40 1. Otherwise \fBTcl_StringMatch\fR returns 0. The algorithm 41 -used for matching is the same algorithm used in the 42 -.QW "string match" 41 +used for matching is the same algorithm used in the ``string match'' 43 42 Tcl command and is similar to the algorithm used by the C-shell 44 43 for file name matching; see the Tcl manual entry for details. 45 44 .PP 46 45 In \fBTcl_StringCaseMatch\fR, the algorithm is the same, but you have 47 46 the option to make the matching case-insensitive. If you choose this 48 47 (by passing \fBnocase\fR as 1), then the string and pattern are 49 48 essentially matched in the lower case. 50 49 51 50 .SH KEYWORDS 52 51 match, pattern, string
Changes to doc/SubstObj.3.
1 1 '\" 2 2 '\" Copyright (c) 2001 Donal K. Fellows 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: SubstObj.3,v 1.4 2007/10/24 14:29:38 dkf Exp $ 7 +'\" RCS: @(#) $Id: SubstObj.3,v 1.5 2007/10/26 20:11:52 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH Tcl_SubstObj 3 8.4 Tcl "Tcl Library Procedures" 11 11 .BS 12 12 .SH NAME 13 13 Tcl_SubstObj \- perform substitutions on Tcl objects 14 14 .SH SYNOPSIS ................................................................................ 51 51 .PP 52 52 When the \fBTCL_SUBST_VARIABLES\fR bit is set in \fIflags\fR, 53 53 sequences that look like variable substitutions for Tcl commands are 54 54 replaced by the contents of the named variable. 55 55 .PP 56 56 When the \fBTCL_SUBST_COMMANDS\fR bit is set in \fIflags\fR, sequences 57 57 that look like command substitutions for Tcl commands are replaced by 58 -the result of evaluating that script. Where an uncaught 59 -.QW "continue exception" 60 -occurs during the evaluation of a command substitution, an 61 -empty string is substituted for the command. Where an uncaught 62 -.QW "break exception" 63 -occurs during the evaluation of a command substitution, the 58 +the result of evaluating that script. Where an uncaught `continue 59 +exception' occurs during the evaluation of a command substitution, an 60 +empty string is substituted for the command. Where an uncaught `break 61 +exception' occurs during the evaluation of a command substitution, the 64 62 result of the whole substitution on \fIobjPtr\fR will be truncated at 65 63 the point immediately before the start of the command substitution, 66 64 and no characters will be added to the result or substitutions 67 65 performed after that point. 68 66 69 67 .SH "SEE ALSO" 70 68 subst(n) 71 69 72 70 .SH KEYWORDS 73 71 backslash substitution, command substitution, variable substitution
Changes to doc/TCL_MEM_DEBUG.3.
1 1 '\" 2 2 '\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans. 3 3 '\" Copyright (c) 2000 by Scriptics Corporation. 4 4 '\" All rights reserved. 5 5 '\" 6 -'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.8 2007/10/24 14:29:38 dkf Exp $ 6 +'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.9 2007/10/26 20:11:52 dgp Exp $ 7 7 '\" 8 8 .so man.macros 9 9 .TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures" 10 10 .BS 11 11 .SH NAME 12 12 TCL_MEM_DEBUG \- Compile-time flag to enable Tcl memory debugging 13 13 .BE ................................................................................ 37 37 and the Tcl \fBmemory\fR command can be used to validate and examine 38 38 memory usage. 39 39 40 40 .SH "GUARD ZONES" 41 41 .PP 42 42 When memory debugging is enabled, whenever a call to \fBckalloc\fR is 43 43 made, slightly more memory than requested is allocated so the memory debugging 44 -code can keep track of the allocated memory, and eight-byte 45 -.QW "guard zones" 46 -are placed in front of and behind the space that will be 44 +code can keep track of the allocated memory, and eight-byte ``guard 45 +zones'' are placed in front of and behind the space that will be 47 46 returned to the caller. (The sizes of the guard zones are defined by the 48 47 C #define \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR 49 48 in the file \fIgeneric/tclCkalloc.c\fR -- it can 50 49 be extended if you suspect large overwrite problems, at some cost in 51 50 performance.) A known pattern is written into the guard zones and, on 52 51 a call to \fBckfree\fR, the guard zones of the space being freed are 53 52 checked to see if either zone has been modified in any way. If one 54 53 has been, the guard bytes and their new contents are identified, and a 55 -.QW "low guard failed" 56 -or 57 -.QW "high guard failed" 58 -message is issued. The 59 -.QW "guard failed" 60 -message includes the address of the memory packet and 54 +``low guard failed'' or ``high guard failed'' message is issued. The 55 +``guard failed'' message includes the address of the memory packet and 61 56 the file name and line number of the code that called \fBckfree\fR. 62 57 This allows you to detect the common sorts of one-off problems, where 63 58 not enough space was allocated to contain the data written, for 64 59 example. 65 60 66 61 .SH "DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS" 67 62 .PP
Changes to doc/Tcl.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: Tcl.n,v 1.15 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: Tcl.n,v 1.16 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl n "8.5" Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 .SH NAME 14 14 Tcl \- Tool Command Language 15 15 .SH SYNOPSIS ................................................................................ 37 37 in any way it likes, such as an integer, variable name, list, 38 38 or Tcl script. 39 39 Different commands interpret their words differently. 40 40 .IP "[3] \fBWords.\fR" 41 41 Words of a command are separated by white space (except for 42 42 newlines, which are command separators). 43 43 .IP "[4] \fBDouble quotes.\fR" 44 -If the first character of a word is double-quote 45 -.PQ \N'34' 46 -then the word is terminated by the next double-quote character. 44 +If the first character of a word is double-quote (``"'') then 45 +the word is terminated by the next double-quote character. 47 46 If semi-colons, close brackets, or white space characters 48 47 (including newlines) appear between the quotes then they are treated 49 48 as ordinary characters and included in the word. 50 49 Command substitution, variable substitution, and backslash substitution 51 50 are performed on the characters between the quotes as described below. 52 51 The double-quotes are not retained as part of the word. 53 52 .VS 8.5 br 54 53 .IP "[5] \fBArgument expansion.\fR" 55 -If a word starts with the string 56 -.QW {*} 57 -followed by a non-whitespace character, then the leading 58 -.QW {*} 59 -is removed and the rest of the word is parsed and substituted as any 60 -other word. After substitution, the word is parsed again without 54 +If a word starts with the string ``{*}'' followed by a 55 +non-whitespace character, then the leading ``{*}'' is removed 56 +and the rest of the word is parsed and substituted as any other 57 +word. After substitution, the word is parsed again without 61 58 substitutions, and its words are added to the command being 62 -substituted. For instance, 63 -.QW "cmd a {*}{b c} d {*}{e f}" 64 -is equivalent to 65 -.QW "cmd a b c d e f" . 59 +substituted. For instance, ``cmd a {*}{b c} d {*}{e f}'' is 60 +equivalent to ``cmd a b c d e f''. 66 61 .VE 8.5 67 62 .IP "[6] \fBBraces.\fR" 68 -If the first character of a word is an open brace 69 -.PQ { 70 -and rule [5] does not apply, then 71 -the word is terminated by the matching close brace 72 -.PQ } "" . 63 +If the first character of a word is an open brace (``{'') and 64 +rule [5] does not apply, then 65 +the word is terminated by the matching close brace (``}''). 73 66 Braces nest within the word: for each additional open 74 67 brace there must be an additional close brace (however, 75 68 if an open brace or close brace within the word is 76 69 quoted with a backslash then it is not counted in locating the 77 70 matching close brace). 78 71 No substitutions are performed on the characters between the 79 72 braces except for backslash-newline substitutions described 80 73 below, nor do semi-colons, newlines, close brackets, 81 74 or white space receive any special interpretation. 82 75 The word will consist of exactly the characters between the 83 76 outer braces, not including the braces themselves. 84 77 .IP "[7] \fBCommand substitution.\fR" 85 -If a word contains an open bracket 86 -.PQ [ 87 -then Tcl performs \fIcommand substitution\fR. 78 +If a word contains an open bracket (``['') then Tcl performs 79 +\fIcommand substitution\fR. 88 80 To do this it invokes the Tcl interpreter recursively to process 89 81 the characters following the open bracket as a Tcl script. 90 82 The script may contain any number of commands and must be terminated 91 -by a close bracket 92 -.PQ ] "" . 83 +by a close bracket (``]''). 93 84 The result of the script (i.e. the result of its last command) is 94 85 substituted into the word in place of the brackets and all of the 95 86 characters between them. 96 87 There may be any number of command substitutions in a single word. 97 88 Command substitution is not performed on words enclosed in braces. 98 89 .IP "[8] \fBVariable substitution.\fR" 99 -If a word contains a dollar-sign 100 -.PQ $ 101 -followed by one of the forms described below, then Tcl performs \fIvariable 90 +If a word contains a dollar-sign (``$'') followed by one of the forms 91 +described below, then Tcl performs \fIvariable 102 92 substitution\fR: the dollar-sign and the following characters are 103 93 replaced in the word by the value of a variable. 104 94 Variable substitution may take any of the following forms: 105 95 .RS 106 96 .TP 15 107 97 \fB$\fIname\fR 108 98 \fIName\fR is the name of a scalar variable; the name is a sequence ................................................................................ 121 111 \fIName\fR is the name of a scalar variable. It may contain any 122 112 characters whatsoever except for close braces. 123 113 .LP 124 114 There may be any number of variable substitutions in a single word. 125 115 Variable substitution is not performed on words enclosed in braces. 126 116 .RE 127 117 .IP "[9] \fBBackslash substitution.\fR" 128 -If a backslash 129 -.PQ \e 130 -appears within a word then \fIbackslash substitution\fR occurs. 118 +If a backslash (``\e'') appears within a word then 119 +\fIbackslash substitution\fR occurs. 131 120 In all cases but those described below the backslash is dropped and 132 121 the following character is treated as an ordinary 133 122 character and included in the word. 134 123 This allows characters such as double quotes, close brackets, 135 124 and dollar signs to be included in words without triggering 136 125 special processing. 137 126 The following table lists the backslash sequences that are ................................................................................ 165 154 and tabs after the newline. This backslash sequence is unique in that it 166 155 is replaced in a separate pre-pass before the command is actually parsed. 167 156 This means that it will be replaced even when it occurs between braces, 168 157 and the resulting space will be treated as a word separator if it isn't 169 158 in braces or quotes. 170 159 .TP 7 171 160 \e\e 172 -Backslash 173 -.PQ \e "" . 161 +Backslash (``\e''). 174 162 .TP 7 175 163 \e\fIooo\fR 176 164 . 177 165 The digits \fIooo\fR (one, two, or three of them) give an eight-bit octal 178 166 value for the Unicode character that will be inserted. The upper bits of the 179 167 Unicode character will be 0. 180 168 .TP 7 ................................................................................ 192 180 sixteen-bit hexadecimal value for the Unicode character that will be 193 181 inserted. 194 182 .LP 195 183 Backslash substitution is not performed on words enclosed in braces, 196 184 except for backslash-newline as described above. 197 185 .RE 198 186 .IP "[10] \fBComments.\fR" 199 -If a hash character 200 -.PQ # 201 -appears at a point where Tcl is 187 +If a hash character (``#'') appears at a point where Tcl is 202 188 expecting the first character of the first word of a command, 203 189 then the hash character and the characters that follow it, up 204 190 through the next newline, are treated as a comment and ignored. 205 191 The comment character only has significance when it appears 206 192 at the beginning of a command. 207 193 .IP "[11] \fBOrder of substitution.\fR" 208 194 Each character is processed exactly once by the Tcl interpreter
Changes to doc/Tcl_Main.3.
2 2 '\" Copyright (c) 1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2000 Ajuba Solutions. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: Tcl_Main.3,v 1.12 2007/10/24 14:29:38 dkf Exp $ 9 +'\" RCS: @(#) $Id: Tcl_Main.3,v 1.13 2007/10/26 20:11:52 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures" 13 13 .BS 14 14 .SH NAME 15 15 Tcl_Main, Tcl_SetMainLoop \- main program and event loop definition for Tcl-based applications 16 16 .SH SYNOPSIS ................................................................................ 32 32 .AP Tcl_MainLoopProc *mainLoopProc in 33 33 Address of an application-specific event loop procedure. 34 34 .BE 35 35 36 36 .SH DESCRIPTION 37 37 .PP 38 38 \fBTcl_Main\fR can serve as the main program for Tcl-based shell 39 -applications. A 40 -.QW "shell application" 41 -is a program like tclsh or wish that supports both interactive interpretation 39 +applications. A ``shell application'' is a program 40 +like tclsh or wish that supports both interactive interpretation 42 41 of Tcl and evaluation of a script contained in a file given as 43 42 a command line argument. \fBTcl_Main\fR is offered as a convenience 44 43 to developers of shell applications, so they do not have to 45 44 reproduce all of the code for proper initialization of the Tcl 46 45 library and interactive shell operation. Other styles of embedding 47 46 Tcl in an application are not supported by \fBTcl_Main\fR. Those 48 47 must be achieved by calling lower level functions in the Tcl library ................................................................................ 88 87 .PP 89 88 In either mode, \fBTcl_Main\fR will define in its master interpreter 90 89 the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and 91 90 \fItcl_interactive\fR, as described in the documentation for \fBtclsh\fR. 92 91 .PP 93 92 When it has finished its own initialization, but before it processes 94 93 commands, \fBTcl_Main\fR calls the procedure given by the 95 -\fIappInitProc\fR argument. This procedure provides a 96 -.QW hook 97 -for the application to perform its own initialization of the interpreter 94 +\fIappInitProc\fR argument. This procedure provides a ``hook'' for 95 +the application to perform its own initialization of the interpreter 98 96 created by \fBTcl_Main\fR, such as defining application-specific 99 97 commands. The procedure must have an interface that matches the 100 98 type \fBTcl_AppInitProc\fR: 101 99 .CS 102 100 typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR); 103 101 .CE 104 102
Changes to doc/TraceVar.3.
1 1 '\" 2 2 '\" Copyright (c) 1989-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: TraceVar.3,v 1.16 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: TraceVar.3,v 1.17 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 \- monitor accesses to a variable 15 15 .SH SYNOPSIS ................................................................................ 349 349 350 350 .SH "UNDEFINED VARIABLES" 351 351 .PP 352 352 It is legal to set a trace on an undefined variable. 353 353 The variable will still appear to be undefined until the 354 354 first time its value is set. 355 355 If an undefined variable is traced and then unset, the unset will fail 356 -with an error, 357 -.QW "no such variable" , 358 -but the trace procedure will still be invoked. 356 +with an error (``no such variable''), but the trace 357 +procedure will still be invoked. 359 358 360 359 .SH "TCL_TRACE_DESTROYED FLAG" 361 360 .PP 362 361 In an unset callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit 363 362 is set in \fIflags\fR if the trace is being removed as part 364 363 of the deletion. 365 364 Traces on a variable are always removed whenever the variable
Changes to doc/Translate.3.
1 1 '\" 2 2 '\" Copyright (c) 1989-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1998 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: Translate.3,v 1.10 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: Translate.3,v 1.11 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH Tcl_TranslateFileName 3 8.1 Tcl "Tcl Library Procedures" 12 12 .BS 13 13 .SH NAME 14 14 Tcl_TranslateFileName \- convert file name to native form and replace tilde with home directory 15 15 .SH SYNOPSIS ................................................................................ 19 19 char * 20 20 \fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR) 21 21 .SH ARGUMENTS 22 22 .AS Tcl_DString *bufferPtr in/out 23 23 .AP Tcl_Interp *interp in 24 24 Interpreter in which to report an error, if any. 25 25 .AP "const char" *name in 26 -File name, which may start with a 27 -.QW ~ . 26 +File name, which may start with a ``~''. 28 27 .AP Tcl_DString *bufferPtr in/out 29 28 If needed, this dynamic string is used to store the new file name. 30 29 At the time of the call it should be uninitialized or free. The 31 30 caller must eventually call \fBTcl_DStringFree\fR to free up 32 31 anything stored here. 33 32 .BE 34 33
Changes to doc/WrongNumArgs.3.
1 1 '\" 2 2 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: WrongNumArgs.3,v 1.9 2007/10/24 14:29:38 dkf Exp $ 7 +'\" RCS: @(#) $Id: WrongNumArgs.3,v 1.10 2007/10/26 20:11:52 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures" 11 11 .BS 12 12 .SH NAME 13 13 Tcl_WrongNumArgs \- generate standard error message for wrong number of arguments 14 14 .SH SYNOPSIS ................................................................................ 37 37 \fBTcl_WrongNumArgs\fR is a utility procedure that is invoked by 38 38 command procedures when they discover that they have received the 39 39 wrong number of arguments. \fBTcl_WrongNumArgs\fR generates a 40 40 standard error message and stores it in the result object of 41 41 \fIinterp\fR. The message includes the \fIobjc\fR initial 42 42 elements of \fIobjv\fR plus \fImessage\fR. For example, if 43 43 \fIobjv\fR consists of the values \fBfoo\fR and \fBbar\fR, 44 -\fIobjc\fR is 1, and \fImessage\fR is 45 -.QW "\fBfileName count\fR" 44 +\fIobjc\fR is 1, and \fImessage\fR is ``\fBfileName count\fR'' 46 45 then \fIinterp\fR's result object will be set to the following 47 46 string: 48 47 .CS 49 48 wrong # args: should be "foo fileName count" 50 49 .CE 51 50 If \fIobjc\fR is 2, the result will be set to the following string: 52 51 .CS
Changes to doc/after.n.
1 1 '\" 2 2 '\" Copyright (c) 1990-1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: after.n,v 1.8 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: after.n,v 1.9 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH after n 7.5 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 after \- Execute a command after a time delay ................................................................................ 132 132 proc doOneStep {} { 133 133 if {[::my_calc::one_step]} { 134 134 \fBafter idle\fR [list \fBafter\fR 0 doOneStep] 135 135 } 136 136 } 137 137 doOneStep 138 138 .CE 139 + 139 140 .SH "SEE ALSO" 140 141 concat(n), interp(n), update(n), vwait(n) 142 + 141 143 .SH KEYWORDS 142 144 cancel, delay, idle callback, sleep, time
Changes to doc/append.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: append.n,v 1.7 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: append.n,v 1.8 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH append n "" Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 append \- Append to variable ................................................................................ 23 23 of variable \fIvarName\fR. If \fIvarName\fR doesn't exist, 24 24 it is given a value equal to the concatenation of all the 25 25 \fIvalue\fR arguments. 26 26 The result of this command is the new value stored in variable 27 27 \fIvarName\fR. 28 28 This command provides an efficient way to build up long 29 29 variables incrementally. 30 -For example, 31 -.QW "\fBappend a $b\fR" 32 -is much more efficient than 33 -.QW "\fBset a $a$b\fR" , 34 -especially when \fB$a\fR is long. 30 +For example, ``\fBappend a $b\fR'' is much more efficient than 31 +``\fBset a $a$b\fR'' if \fB$a\fR is long. 35 32 .SH EXAMPLE 36 33 Building a string of comma-separated numbers piecemeal using a loop. 37 34 .CS 38 35 set var 0 39 36 for {set i 1} {$i<=10} {incr i} { 40 37 \fBappend\fR var "," $i 41 38 } 42 39 puts $var 43 40 # Prints 0,1,2,3,4,5,6,7,8,9,10 44 41 .CE 42 + 45 43 .SH "SEE ALSO" 46 44 concat(n), lappend(n) 45 + 47 46 .SH KEYWORDS 48 47 append, variable
Changes to doc/apply.n.
37 37 the \fBvariable\fR command or the \fBupvar\fR command. 38 38 .PP 39 39 The invocation of \fBapply\fR adds a call frame to Tcl's evaluation stack 40 40 (the stack of frames accessed via \fBuplevel\fR). The execution of \fIbody\fR 41 41 proceeds in this call frame, in the namespace given by \fInamespace\fR or 42 42 in the global namespace if none was specified. If given, \fInamespace\fR is 43 43 interpreted relative to the global namespace even if its name does not start 44 -with 45 -.QW :: . 44 +with '::'. 46 45 .PP 47 46 The semantics of \fBapply\fR can also be described by: 48 47 .PP 49 48 .CS 50 49 proc apply {fun args} { 51 50 set len [llength $fun] 52 51 if {($len < 2) || ($len > 3)} { ................................................................................ 62 61 return -options $opt $res 63 62 } 64 63 .CE 65 64 .SH EXAMPLES 66 65 This shows how to make a simple general command that applies a transformation 67 66 to each element of a list. 68 67 .CS 69 -.ta 2i 70 68 proc map {lambda list} { 71 69 set result {} 72 70 foreach $item $list { 73 71 lappend result [\fBapply\fR $lambda $item] 74 72 } 75 73 return $result 76 74 } 77 75 map {x {return [string length $x]:$x}} {a bb ccc dddd} 78 - \fB\(->\fI 1:a 2:bb 3:ccc 4:dddd\fR 76 + \fI=> 1:a 2:bb 3:ccc 4:dddd\fR 79 77 map {x {expr {$x**2 + 3*$x - 2}}} {-4 -3 -2 -1 0 1 2 3 4} 80 - \fB\(->\fI 2 -2 -4 -4 -2 2 8 16 26\fR 78 + \fI=> 2 -2 -4 -4 -2 2 8 16 26\fR 81 79 .CE 82 80 .PP 83 81 The \fBapply\fR command is also useful for defining callbacks for use in the 84 82 \fBtrace\fR command: 85 83 .CS 86 -.ta 2i 87 84 set vbl "123abc" 88 85 trace add variable vbl write {\fBapply\fR {v1 v2 op} { 89 86 upvar 1 $v1 v 90 - puts "updated variable to \e"$v\e"" 87 + puts "updated variable to \\"$v\\"" 91 88 }} 92 89 set vbl 123 93 - \fB\(->\fI updated variable to "123"\fR 94 90 set vbl abc 95 - \fB\(->\fI updated variable to "abc"\fR 96 91 .CE 97 92 .SH "SEE ALSO" 98 93 proc(n), uplevel(n) 99 94 .SH KEYWORDS 100 95 argument, procedure, anonymous function
Changes to doc/array.n.
1 1 '\" 2 2 '\" Copyright (c) 1993-1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: array.n,v 1.17 2007/10/25 09:25:27 dkf Exp $ 8 +'\" RCS: @(#) $Id: array.n,v 1.18 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH array n 8.3 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 array \- Manipulate array variables ................................................................................ 144 144 blue 4 145 145 white 9 146 146 } 147 147 148 148 foreach {color count} [\fBarray get\fR colorcount] { 149 149 puts "Color: $color Count: $count" 150 150 } 151 - \(-> Color: blue Count: 4 151 + => Color: blue Count: 4 152 152 Color: white Count: 9 153 153 Color: green Count: 5 154 154 Color: red Count: 1 155 155 156 156 foreach color [\fBarray names\fR colorcount] { 157 157 puts "Color: $color Count: $colorcount($color)" 158 158 } 159 - \(-> Color: blue Count: 4 159 + => Color: blue Count: 4 160 160 Color: white Count: 9 161 161 Color: green Count: 5 162 162 Color: red Count: 1 163 163 164 164 foreach color [lsort [\fBarray names\fR colorcount]] { 165 165 puts "Color: $color Count: $colorcount($color)" 166 166 } 167 - \(-> Color: blue Count: 4 167 + => Color: blue Count: 4 168 168 Color: green Count: 5 169 169 Color: red Count: 1 170 170 Color: white Count: 9 171 171 172 172 \fBarray statistics\fR colorcount 173 - \(-> 4 entries in table, 4 buckets 173 + => 4 entries in table, 4 buckets 174 174 number of buckets with 0 entries: 1 175 175 number of buckets with 1 entries: 2 176 176 number of buckets with 2 entries: 1 177 177 number of buckets with 3 entries: 0 178 178 number of buckets with 4 entries: 0 179 179 number of buckets with 5 entries: 0 180 180 number of buckets with 6 entries: 0 181 181 number of buckets with 7 entries: 0 182 182 number of buckets with 8 entries: 0 183 183 number of buckets with 9 entries: 0 184 184 number of buckets with 10 or more entries: 0 185 185 average search distance for entry: 1.2 186 186 .CE 187 + 187 188 .SH "SEE ALSO" 188 189 list(n), string(n), variable(n), trace(n), foreach(n) 190 + 189 191 .SH KEYWORDS 190 192 array, element names, search
Changes to doc/bgerror.n.
1 1 '\" 2 2 '\" Copyright (c) 1990-1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: bgerror.n,v 1.10 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: bgerror.n,v 1.11 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH bgerror n 7.5 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 bgerror \- Command invoked to process background errors ................................................................................ 82 82 proc bgerror {message} { 83 83 set timestamp [clock format [clock seconds]] 84 84 set fl [open mylog.txt {WRONLY CREAT APPEND}] 85 85 puts $fl "$timestamp: bgerror in $::argv '$message'" 86 86 close $fl 87 87 } 88 88 .CE 89 + 89 90 .SH "SEE ALSO" 90 91 after(n), interp(n), tclvars(n) 92 + 91 93 .SH KEYWORDS 92 94 background error, reporting
Changes to doc/binary.n.
1 1 '\" 2 2 '\" Copyright (c) 1997 by Sun Microsystems, Inc. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: binary.n,v 1.31 2007/10/25 14:07:32 dkf Exp $ 7 +'\" RCS: @(#) $Id: binary.n,v 1.32 2007/10/26 20:11:52 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH binary n 8.0 Tcl "Tcl Built-In Commands" 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 binary \- Insert and extract fields from binary strings ................................................................................ 125 125 \fBbinary format\fR B5B* 11100 111000011010 126 126 .CE 127 127 will return a string equivalent to \fB\\xe0\\xe1\\xa0\fR. 128 128 .RE 129 129 .IP \fBh\fR 5 130 130 Stores a string of \fIcount\fR hexadecimal digits in low-to-high 131 131 within each byte in the output string. \fIArg\fR must contain a 132 -sequence of characters in the set 133 -.QW 0123456789abcdefABCDEF . 134 -The resulting bytes are emitted in first to last order with the hex digits 132 +sequence of characters in the set ``0123456789abcdefABCDEF''. The 133 +resulting bytes are emitted in first to last order with the hex digits 135 134 being formatted in low-to-high order within each byte. If \fIarg\fR 136 135 has fewer than \fIcount\fR digits, then zeros will be used for the 137 136 remaining digits. If \fIarg\fR has more than the specified number of 138 137 digits, the extra digits will be ignored. If \fIcount\fR is 139 138 \fB*\fR, then all of the digits in \fIarg\fR will be formatted. If 140 139 \fIcount\fR is omitted, then one digit will be formatted. If the 141 140 number of digits formatted does not end at a byte boundary, the ................................................................................ 392 391 \fIcount\fR is a non-negative decimal integer or \fB*\fR, which 393 392 normally indicates that all of the remaining items in the data are to 394 393 be used. If there are not enough bytes left after the current cursor 395 394 position to satisfy the current field specifier, then the 396 395 corresponding variable is left untouched and \fBbinary scan\fR returns 397 396 immediately with the number of variables that were set. If there are 398 397 not enough arguments for all of the fields in the format string that 399 -consume arguments, then an error is generated. The flag character 400 -.QW u 398 +consume arguments, then an error is generated. The flag character 'u' 401 399 may be given to cause some types to be read as unsigned values. The flag 402 400 is accepted for all field types but is ignored for non-integer fields. 403 401 .PP 404 402 A similar example as with \fBbinary format\fR should explain the 405 403 relation between field specifiers and arguments in case of the binary 406 404 scan subcommand: 407 405 .CS ................................................................................ 432 430 long data size values. In doing this, values that have their high 433 431 bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints), 434 432 will be sign extended. Thus the following will occur: 435 433 .CS 436 434 set signShort [\fBbinary format\fR s1 0x8000] 437 435 \fBbinary scan\fR $signShort s1 val; \fI# val == 0xFFFF8000\fR 438 436 .CE 439 -If you require unsigned values you can include the 440 -.QW u 441 -flag character following the field type. For example, to read an 442 -unsigned short value: 437 +If you require unsigned values you can include the 'u' flag character following 438 +the field type. For example, to read an unsigned short value: 443 439 .CS 444 440 set signShort [\fBbinary format\fR s1 0x8000] 445 441 \fBbinary scan\fR $signShort su1 val; \fI# val == 0x00008000\fR 446 442 .CE 447 443 .PP 448 444 Each type-count pair moves an imaginary cursor through the binary data, 449 445 reading bytes from the current position. The cursor is initially ................................................................................ 472 468 .CS 473 469 \fBbinary scan\fR "abc efghi \\000" A* var1 474 470 .CE 475 471 will return \fB1\fR with \fBabc efghi\fR stored in \fIvar1\fR. 476 472 .RE 477 473 .IP \fBb\fR 5 478 474 The data is turned into a string of \fIcount\fR binary digits in 479 -low-to-high order represented as a sequence of 480 -.QW 1 481 -and 482 -.QW 0 475 +low-to-high order represented as a sequence of ``1'' and ``0'' 483 476 characters. The data bytes are scanned in first to last order with 484 477 the bits being taken in low-to-high order within each byte. Any extra 485 478 bits in the last byte are ignored. If \fIcount\fR is \fB*\fR, then 486 479 all of the remaining bits in \fIstring\fR will be scanned. If 487 480 \fIcount\fR is omitted, then one bit will be scanned. For example, 488 481 .RS 489 482 .CS ................................................................................ 501 494 .CE 502 495 will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and 503 496 \fB1000011100000101\fR stored in \fIvar2\fR. 504 497 .RE 505 498 .IP \fBH\fR 5 506 499 The data is turned into a string of \fIcount\fR hexadecimal digits in 507 500 high-to-low order represented as a sequence of characters in the set 508 -.QW 0123456789abcdef . 509 -The data bytes are scanned in first to last 501 +``0123456789abcdef''. The data bytes are scanned in first to last 510 502 order with the hex digits being taken in high-to-low order within each 511 503 byte. Any extra bits in the last byte are ignored. If \fIcount\fR is 512 504 \fB*\fR, then all of the remaining hex digits in \fIstring\fR will be 513 505 scanned. If \fIcount\fR is omitted, then one hex digit will be 514 506 scanned. For example, 515 507 .RS 516 508 .CS ................................................................................ 787 779 if {![\fBbinary scan\fR [read $channel 4] I length]} { 788 780 error "missing length" 789 781 } 790 782 set data [read $channel $length] 791 783 return [encoding convertfrom utf-8 $data] 792 784 } 793 785 .CE 786 + 794 787 .SH "SEE ALSO" 795 788 format(n), scan(n), tclvars(n) 789 + 796 790 .SH KEYWORDS 797 791 binary, format, scan
Changes to doc/break.n.
1 1 '\" 2 2 '\" Copyright (c) 1993-1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: break.n,v 1.8 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: break.n,v 1.9 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH break n "" Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 break \- Abort looping command ................................................................................ 35 35 for {set x 0} {$x<10} {incr x} { 36 36 if {$x > 5} { 37 37 \fBbreak\fR 38 38 } 39 39 puts "x is $x" 40 40 } 41 41 .CE 42 + 42 43 .SH "SEE ALSO" 43 44 catch(n), continue(n), for(n), foreach(n), return(n), while(n) 45 + 44 46 .SH KEYWORDS 45 47 abort, break, loop
Changes to doc/catch.n.
2 2 '\" Copyright (c) 1993-1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Contributions from Don Porter, NIST, 2003. (not subject to US copyright) 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: catch.n,v 1.14 2007/10/24 14:29:38 dkf Exp $ 9 +'\" RCS: @(#) $Id: catch.n,v 1.15 2007/10/26 20:11:52 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH catch n "8.5" Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 catch \- Evaluate script and trap exceptional returns ................................................................................ 86 86 puts stderr "Could not open $someFile for writing\\n$fid" 87 87 exit 1 88 88 } 89 89 .CE 90 90 .PP 91 91 There are more complex examples of \fBcatch\fR usage in the 92 92 documentation for the \fBreturn\fR command. 93 + 93 94 .SH "SEE ALSO" 94 95 break(n), continue(n), dict(n), error(n), return(n), tclvars(n) 96 + 95 97 .SH KEYWORDS 96 98 catch, error
Changes to doc/cd.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: cd.n,v 1.7 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: cd.n,v 1.8 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH cd n "" Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 cd \- Change working directory ................................................................................ 33 33 .CE 34 34 .PP 35 35 Change to the directory \fBlib\fR that is a sibling directory of the 36 36 current one: 37 37 .CS 38 38 \fBcd\fR ../lib 39 39 .CE 40 + 40 41 .SH "SEE ALSO" 41 42 filename(n), glob(n), pwd(n) 43 + 42 44 .SH KEYWORDS 43 45 working directory
Changes to doc/chan.n.
1 1 '\" 2 2 '\" Copyright (c) 2005-2006 Donal K. Fellows 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: chan.n,v 1.12 2007/10/25 14:07:32 dkf Exp $ 7 +'\" RCS: @(#) $Id: chan.n,v 1.13 2007/10/26 20:11:52 dgp Exp $ 8 8 .so man.macros 9 9 .TH chan n 8.5 Tcl "Tcl Built-In Commands" 10 10 .BS 11 11 '\" Note: do not modify the .SH NAME line immediately below! 12 12 .SH NAME 13 13 chan \- Read, write and manipulate channels 14 14 .SH SYNOPSIS ................................................................................ 289 289 \fInot\fR made. If \fIinputChan\fR is closed, then all data already 290 290 queued for \fIoutputChan\fR is written out. 291 291 .PP 292 292 Note that \fIinputChan\fR can become readable during a background 293 293 copy. You should turn off any \fBchan event\fR or \fBfileevent\fR 294 294 handlers during a background copy so those handlers do not interfere 295 295 with the copy. Any I/O attempted by a \fBchan event\fR or 296 -\fBfileevent\fR handler will get a 297 -.QW "channel busy" 298 -error. 296 +\fBfileevent\fR handler will get a "channel busy" error. 299 297 .PP 300 298 \fBChan copy\fR translates end-of-line sequences in \fIinputChan\fR 301 299 and \fIoutputChan\fR according to the \fB\-translation\fR option for 302 300 these channels (see \fBchan configure\fR above). The translations 303 301 mean that the number of bytes read from \fIinputChan\fR can be 304 302 different than the number of bytes written to \fIoutputChan\fR. Only 305 303 the number of bytes written to \fIoutputChan\fR is reported, either as ................................................................................ 331 329 returned as the result of the \fBchan create\fR command, and the 332 330 channel is open. Use either \fBclose\fR or \fBchan close\fR to remove 333 331 the channel. 334 332 .RS 335 333 .PP 336 334 The argument \fImode\fR specifies if the new channel is opened for 337 335 reading, writing, or both. It has to be a list containing any of the 338 -strings 339 -.QW "\fBread\fR" 340 -or 341 -.QW "\fBwrite\fR" . 342 -The list must have at least one 336 +strings "\fBread\fR" or "\fBwrite\fR". The list must have at least one 343 337 element, as a channel you can neither write to nor read from makes no 344 338 sense. The handler command for the new channel must support the chosen 345 339 mode, or an error is thrown. 346 340 .PP 347 341 The command prefix is executed in the global namespace, at the top of 348 342 call stack, following the appending of arguments as described in the 349 343 \fBreflectedchan\fR manual page. Command resolution happens at the ................................................................................ 413 407 writable. File event handlers are most commonly used to allow data to 414 408 be received from another process on an event-driven basis, so that the 415 409 receiver can continue to interact with the user or with other channels 416 410 while waiting for the data to arrive. If an application invokes 417 411 \fBchan gets\fR or \fBchan read\fR on a blocking channel when there is 418 412 no input data available, the process will block; until the input data 419 413 arrives, it will not be able to service other events, so it will 420 -appear to the user to 421 -.QW "freeze up" . 422 -With \fBchan event\fR, the 414 +appear to the user to ``freeze up''. With \fBchan event\fR, the 423 415 process can tell when data is present and only invoke \fBchan gets\fR 424 416 or \fBchan read\fR when they won't block. 425 417 .PP 426 418 A channel is considered to be readable if there is unread data 427 419 available on the underlying device. A channel is also considered to 428 420 be readable if there is unread data in an input buffer, except in the 429 421 special case where the most recent attempt to read from the channel ................................................................................ 500 492 . 501 493 Produces a list of all channel names. If \fIpattern\fR is specified, 502 494 only those channel names that match it (according to the rules of 503 495 \fBstring match\fR) will be returned. 504 496 .TP 505 497 \fBchan pending \fImode channelId\fR 506 498 . 507 -Depending on whether \fImode\fR is 508 -.QW "input" 509 -or 510 -.QW "output" , 511 -returns the number of 499 +Depending on whether \fImode\fR is "input" or "output", returns the number of 512 500 bytes of input or output (respectively) currently buffered 513 501 internally for \fIchannelId\fR (especially useful in a readable event 514 502 callback to impose application-specific limits on input line lengths to avoid 515 503 a potential denial-of-service attack where a hostile user crafts 516 504 an extremely long line that exceeds the available memory to buffer it). 517 505 Returns -1 if the channel was not opened for the mode in question. 518 506 .TP 519 507 \fBchan postevent \fIchannelId eventSpec\fR 520 508 . 521 509 This subcommand is used by command handlers specified with \fBchan 522 510 create\fR. It notifies the channel represented by the handle 523 511 \fIchannelId\fR that the event(s) listed in the \fIeventSpec\fR have 524 512 occurred. The argument has to be a list containing any of the strings 525 -.QW "\fBread\fR" 526 -and 527 -.QW "\fBwrite\fR" . 528 -The list must contain at least one 513 +"\fBread\fR" and "\fBwrite\fR". The list must contain at least one 529 514 element as it does not make sense to invoke the command if there are 530 515 no events to post. 531 516 .RS 532 517 .PP 533 518 Note that this subcommand can only be used with channel handles that 534 519 were created/opened by \fBchan create\fR. All other channels will 535 520 cause this subcommand to report an error.
Changes to doc/clock.n.
6 6 .TH "clock" n 8.5 Tcl "Tcl Built-In Commands" 7 7 .BS 8 8 .SH NAME 9 9 clock \- Obtain and manipulate dates and times 10 10 .SH "SYNOPSIS" 11 11 package require \fBTcl 8.5\fR 12 12 .sp 13 -\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? 13 +\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI-option value\fR? 14 14 .sp 15 -\fBclock clicks\fR ?\fI\-option\fR? 15 +\fBclock clicks\fR ?\fI-option\fR? 16 16 .sp 17 -\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...? 17 +\fBclock format\fR \fItimeVal\fR ?\fI-option value\fR...? 18 18 .sp 19 19 \fBclock microseconds\fR 20 20 .sp 21 21 \fBclock milliseconds\fR 22 22 .sp 23 -\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...? 23 +\fBclock scan\fR \fIinputString\fR ?\fI-option value\fR...? 24 24 .sp 25 25 \fBclock seconds\fR 26 26 .sp 27 27 .BE 28 28 .SH "DESCRIPTION" 29 29 .PP 30 30 The \fBclock\fR command performs several operations that obtain and 31 31 manipulate values that represent times. The command supports several 32 32 subcommands that determine what action is carried out by the command. 33 33 .TP 34 -\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? 34 +\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI-option value\fR? 35 35 Adds a (possibly negative) offset to a time that is expressed as an 36 36 integer number of seconds. See \fBCLOCK ARITHMETIC\fR for a full description. 37 37 .TP 38 -\fBclock clicks\fR ?\fI\-option\fR? 39 -If no \fI\-option\fR argument is supplied, returns a high-resolution 38 +\fBclock clicks\fR ?\fI-option\fR? 39 +If no \fI-option\fR argument is supplied, returns a high-resolution 40 40 time value as a system-dependent integer value. The unit of the value 41 41 is system-dependent but should be the highest resolution clock available 42 42 on the system such as a CPU cycle counter. See \fBHIGH RESOLUTION TIMERS\fR for a full description. 43 43 .sp 44 -If the \fI\-option\fR argument is \fI\-milliseconds\fR, then the command 44 +If the \fI-option\fR argument is \fI-milliseconds\fR, then the command 45 45 is synonymous with \fBclock milliseconds\fR (see below). This 46 46 usage is obsolete, and \fBclock milliseconds\fR is to be 47 47 considered the preferred way of obtaining a count of milliseconds. 48 48 .sp 49 -If the \fI\-option\fR argument is \fI\-microseconds\fR, then the command 49 +If the \fI-option\fR argument is \fI-microseconds\fR, then the command 50 50 is synonymous with \fBclock microseconds\fR (see below). This 51 51 usage is obsolete, and \fBclock microseconds\fR is to be 52 52 considered the preferred way of obtaining a count of microseconds. 53 53 .TP 54 -\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...? 54 +\fBclock format\fR \fItimeVal\fR ?\fI-option value\fR...? 55 55 Formats a time that is expressed as an integer number of seconds into a format 56 56 intended for consumption by users or external programs. 57 57 See \fBFORMATTING TIMES\fR for a full description. 58 58 .TP 59 59 \fBclock microseconds\fR 60 60 Returns the current time as an integer number of microseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. 61 61 .TP 62 62 \fBclock milliseconds\fR 63 63 Returns the current time as an integer number of milliseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. 64 64 .TP 65 -\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...? 65 +\fBclock scan\fR \fIinputString\fR ?\fI-option value\fR...? 66 66 Scans a time that is expressed as a character string and produces an 67 67 integer number of seconds. 68 68 See \fBSCANNING TIMES\fR for a full description. 69 69 .TP 70 70 \fBclock seconds\fR 71 71 Returns the current time as an integer number of seconds. 72 72 .SS "PARAMETERS" ................................................................................ 89 89 One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR, 90 90 \fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or 91 91 any unique prefix of such a word. Used in conjunction with \fIcount\fR 92 92 to identify an interval of time, for example, \fI3 seconds\fR or 93 93 \fI1 year\fR. 94 94 .SS "OPTIONS" 95 95 .TP 96 -\fB\-base\fR time 96 +\fB-base\fR time 97 97 Specifies that any relative times present in a \fBclock scan\fR command 98 98 are to be given relative to \fItime\fR. \fItime\fR must be expressed as 99 99 a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC. 100 100 .TP 101 -\fB\-format\fR format 101 +\fB-format\fR format 102 102 Specifies the desired output format for \fBclock format\fR or the 103 103 expected input format for \fBclock scan\fR. The \fIformat\fR string consists 104 -of any number of characters other than the per-cent sign 105 -.PQ \fI%\fR 104 +of any number of characters other than the per-cent sign ('\fI%\fR') 106 105 interspersed with any number of \fIformat groups\fR, which are two-character 107 106 sequences beginning with the per-cent sign. The permissible format groups, 108 107 and their interpretation, are described under \fBFORMAT GROUPS\fR. 109 108 .RS 110 109 .PP 111 110 On \fBclock format\fR, the default format is 112 111 .CS 113 112 %a %b %d %H:%M:%S %z %Y 114 113 .CE 115 114 .PP 116 -On \fBclock scan\fR, the lack of a \fI\-format\fR option indicates that a 117 -.QW "free format scan" 118 -is requested; see \fBFREE FORM SCAN\fR for a description of what happens. 115 +On \fBclock scan\fR, the lack of a \fI-format\fR option indicates that 116 +a "free format scan" is requested; see \fBFREE FORM SCAN\fR for a 117 +description of what happens. 119 118 .RE 120 119 .TP 121 -\fB\-gmt\fR boolean 120 +\fB-gmt\fR boolean 122 121 If \fIboolean\fR is true, specifies that a time specified to \fBclock add\fR, 123 122 \fBclock format\fR or \fBclock scan\fR should be processed in 124 123 UTC. If \fIboolean\fR is false, the processing defaults to the local time 125 124 zone. This usage is obsolete; the correct current usage is to 126 -specify the UTC time zone with 127 -.QW "\fB\-timezone\fR \fI:UTC\fR" 128 -or any of the equivalent ways to specify it. 125 +specify the UTC time zone with '\fB-timezone\fR \fI:UTC\fR' or any of 126 +the equivalent ways to specify it. 129 127 .TP 130 -\fB\-locale\fR localeName 128 +\fB-locale\fR localeName 131 129 Specifies that locale-dependent scanning and formatting (and date arithmetic 132 130 for dates preceding the adoption of the Gregorian calendar) is to be done in 133 131 the locale identified by \fIlocaleName\fR. The locale name may be any of 134 132 the locales acceptable to the \fBmsgcat\fR package, or it may be the special 135 133 name \fIsystem\fR, which represents the current locale of the process, or 136 134 the null string, which represents Tcl's default locale. 137 135 .sp 138 136 The effect of locale on scanning and formatting is discussed in the 139 137 descriptions of the individual format groups under \fBFORMAT GROUPS\fR. 140 138 The effect of locale on clock arithmetic is discussed under 141 139 \fBCLOCK ARITHMETIC\fR. 142 140 .TP 143 -\fB\-timezone\fR zoneName 141 +\fB-timezone\fR zoneName 144 142 Specifies that clock arithmetic, formatting, and scanning are to be done 145 143 according to the rules for the time zone specified by \fIzoneName\fR. 146 144 The permissible values, and their interpretation, are discussed under 147 145 \fBTIME ZONES\fR. 148 -On subcommands that expect a \fB\-timezone\fR argument, the default 146 +On subcommands that expect a \fB-timezone\fR argument, the default 149 147 is to use the \fIcurrent time zone\fR. The current time zone is 150 148 determined, in order of preference, by: 151 149 .RS 152 150 .IP [1] 153 151 the environment variable \fBTCL_TZ\fR. 154 152 .IP [2] 155 153 the environment variable \fBTZ\fR. ................................................................................ 161 159 Greenwich. On 32-bit systems, this approach is likely to have bugs, 162 160 particularly for times that lie outside the window (approximately the 163 161 years 1902 to 2037) that can be represented in a 32-bit integer. 164 162 .SH "CLOCK ARITHMETIC" 165 163 The \fBclock add\fR command performs clock arithmetic on a value 166 164 (expressed as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC) 167 165 given as its first argument. The remaining arguments (other than the 168 -possible \fB\-timezone\fR, \fB\-locale\fR and \fB\-gmt\fR options) 166 +possible \fB-timezone\fR, \fB-locale\fR and \fB-gmt\fR options) 169 167 are integers and keywords in alternation, where the keywords are chosen 170 168 from \fBseconds\fR, \fBminutes\fR, \fBhours\fR, 171 169 \fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or 172 170 any unique prefix of such a word. 173 171 .PP 174 172 Addition of seconds, minutes and hours is fairly straightforward; 175 173 the given time increment (times sixty for minutes, or 3600 for hours) ................................................................................ 282 280 .SH "FORMATTING TIMES" 283 281 The \fBclock format\fR command produces times for display to a user 284 282 or writing to an external medium. The command accepts times that are 285 283 expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC, 286 284 as returned by \fBclock seconds\fR, \fBclock scan\fR, \fBclock add\fR, 287 285 \fBfile atime\fR or \fBfile mtime\fR. 288 286 .PP 289 -If a \fB\-format\fR option is present, the following argument is 287 +If a \fB-format\fR option is present, the following argument is 290 288 a string that specifies how the date and time are to be formatted. 291 289 The string consists 292 -of any number of characters other than the per-cent sign 293 -.PQ \fI%\fR 290 +of any number of characters other than the per-cent sign ('\fI%\fR') 291 +interspersed with any number of \fIformat groups\fR, which are two-character 292 +sequences beginning with the per-cent sign. The permissible format groups, 293 +and their interpretation, are described under \fBFORMAT GROUPS\fR. 294 +.PP 295 +If a \fB-timezone\fR option is present, the following 296 +argument is a string that specifies the time zone in which the date and time 297 +are to be formatted. As an alternative to \fB-timezone\fR \fI:UTC\fR, 298 +the obsolete usage \fB-gmt\fR \fItrue\fR may be used. See 299 +\fBTIME ZONES\fR for the permissible variants for the time zone. 300 +.PP 301 +If a \fB-locale\fR option is present, the following argument is 302 +a string that specifies the locale in which the time is to be formatted, 303 +in the same format that is used for the \fBmsgcat\fR package. Note 304 +that the default, if \fB-locale\fR is not specified, is the root locale 305 +\fB{}\fR rather than the current locale. The current locale may 306 +be obtained by using \fB-locale\fR \fBcurrent\fR. 307 +In addition, some platforms support a \fBsystem\fR locale that 308 +reflects the user's current choices. For instance, on Windows, the 309 +format that the user has selected from dates and times in the Control 310 +Panel can be obtained by using the \fBsystem\fR locale. On 311 +platforms that do not define a user selection of date and time formats 312 +separate from \fBLC_TIME\fR, \fB-locale\fR \fBsystem\fR is 313 +synonymous with \fB-locale\fR \fBcurrent\fR. 314 +.SH "SCANNING TIMES" 315 +The \fBclock scan\fR command accepts times that are formatted as 316 +strings and converts them to counts of seconds from the epoch time 317 +of 1 January 1970, 00:00 UTC. It normally takes a \fB-format\fR 318 +option that is followed by a string describing 319 +the expected format of the input. (See 320 +\fBFREE FORM SCAN\fR for the effect of \fBclock scan\fR 321 +without such an argument.) The string consists of any number of 322 +characters other than the per-cent sign ('\fI%\fR'), 294 323 interspersed with any number of \fIformat groups\fR, which are two-character 295 324 sequences beginning with the per-cent sign. The permissible format groups, 296 325 and their interpretation, are described under \fBFORMAT GROUPS\fR. 297 326 .PP 298 -If a \fB\-timezone\fR option is present, the following 327 +If a \fB-timezone\fR option is present, the following 299 328 argument is a string that specifies the time zone in which the date and time 300 -are to be formatted. As an alternative to 301 -.QW "\fB\-timezone\fR \fI:UTC\fR" , 302 -the obsolete usage 303 -.QW "\fB\-gmt\fR \fItrue\fR" 304 -may be used. See \fBTIME ZONES\fR for the permissible variants for the time 305 -zone. 329 +are to be interpreted. As an alternative to \fB-timezone\fR \fI:UTC\fR, 330 +the obsolete usage \fB-gmt\fR \fItrue\fR may be used. See 331 +\fBTIME ZONES\fR for the permissible variants for the time zone. 306 332 .PP 307 -If a \fB\-locale\fR option is present, the following argument is 308 -a string that specifies the locale in which the time is to be formatted, 333 +If a \fB-locale\fR option is present, the following argument is 334 +a string that specifies the locale in which the time is to be interpreted, 309 335 in the same format that is used for the \fBmsgcat\fR package. Note 310 -that the default, if \fB\-locale\fR is not specified, is the root locale 336 +that the default, if \fB-locale\fR is not specified, is the root locale 311 337 \fB{}\fR rather than the current locale. The current locale may 312 -be obtained by using 313 -.QW "\fB\-locale\fR \fBcurrent\fR" . 338 +be obtained by using \fB-locale\fR \fBcurrent\fR. 314 339 In addition, some platforms support a \fBsystem\fR locale that 315 340 reflects the user's current choices. For instance, on Windows, the 316 341 format that the user has selected from dates and times in the Control 317 342 Panel can be obtained by using the \fBsystem\fR locale. On 318 343 platforms that do not define a user selection of date and time formats 319 -separate from \fBLC_TIME\fR, 320 -.QW "\fB\-locale\fR \fBsystem\fR" 321 -is synonymous with 322 -.QW "\fB\-locale\fR \fBcurrent\fR" . 323 -.SH "SCANNING TIMES" 324 -The \fBclock scan\fR command accepts times that are formatted as 325 -strings and converts them to counts of seconds from the epoch time 326 -of 1 January 1970, 00:00 UTC. It normally takes a \fB\-format\fR 327 -option that is followed by a string describing 328 -the expected format of the input. (See 329 -\fBFREE FORM SCAN\fR for the effect of \fBclock scan\fR 330 -without such an argument.) The string consists of any number of 331 -characters other than the per-cent sign 332 -.PQ \fI%\fR "" , 333 -interspersed with any number of \fIformat groups\fR, which are two-character 334 -sequences beginning with the per-cent sign. The permissible format groups, 335 -and their interpretation, are described under \fBFORMAT GROUPS\fR. 344 +separate from \fBLC_TIME\fR, \fB-locale\fR \fBsystem\fR is 345 +synonymous with \fB-locale\fR \fBcurrent\fR. 336 346 .PP 337 -If a \fB\-timezone\fR option is present, the following 338 -argument is a string that specifies the time zone in which the date and time 339 -are to be interpreted. As an alternative to 340 -.QW "\fB\-timezone\fR \fI:UTC\fR" , 341 -the obsolete usage 342 -.QW "\fB\-gmt\fR \fItrue\fR" 343 -may be used. See \fBTIME ZONES\fR for the permissible variants for the time 344 -zone. 345 -.PP 346 -If a \fB\-locale\fR option is present, the following argument is 347 -a string that specifies the locale in which the time is to be interpreted, 348 -in the same format that is used for the \fBmsgcat\fR package. Note 349 -that the default, if \fB\-locale\fR is not specified, is the root locale 350 -.MT 351 -rather than the current locale. The current locale may be obtained by using 352 -.QW "\fB\-locale\fR \fBcurrent\fR" . 353 -In addition, some platforms support a \fBsystem\fR locale that 354 -reflects the user's current choices. For instance, on Windows, the 355 -format that the user has selected from dates and times in the Control 356 -Panel can be obtained by using the \fBsystem\fR locale. On 357 -platforms that do not define a user selection of date and time formats 358 -separate from \fBLC_TIME\fR, 359 -.QW "\fB\-locale\fR \fBsystem\fR" 360 -is synonymous with 361 -.QW "\fB\-locale\fR \fBcurrent\fR" . 362 -.PP 363 -If a \fB\-base\fR option is present, the following argument is 347 +If a \fB-base\fR option is present, the following argument is 364 348 a time (expressed in seconds from the epoch time) that is used as 365 349 a \fIbase time\fR for interpreting relative times. If no 366 -\fB\-base\fR option is present, the base time is the current time. 350 +\fB-base\fR option is present, the base time is the current time. 367 351 .PP 368 352 Scanning of times in fixed format works by determining three things: 369 353 the date, the time of day, and the time zone. These three are then 370 354 combined into a point in time, which is returned as the number of seconds 371 355 from the epoch. 372 356 .PP 373 357 Before scanning begins, the format string is preprocessed ................................................................................ 434 418 the minute of the hour, that group combines with the hour. If the string 435 419 further contains a group specifying the second of the minute, that group 436 420 combines with the hour and minute. 437 421 .IP [3] 438 422 If the string contains neither a \fB%s\fR format group nor 439 423 a group specifying the hour of the day, then midnight (\fB00:00\fR, the start 440 424 of the given date) is used. 441 -The time zone is determined by either the \fB\-timezone\fR or \fB\-gmt\fR 425 +The time zone is determined by either the \fB-timezone\fR or \fB-gmt\fR 442 426 options, or by using the current time zone. 443 427 .PP 444 428 If a format string lacks a \fB%z\fR or \fB%Z\fR format group, 445 429 it is possible for the time to be ambiguous because it appears twice 446 430 in the same day, once without and once with Daylight Saving Time. 447 431 If this situation occurs, the first occurrence of the time is chosen. 448 432 (For this reason, it is wise to have the input string contain the ................................................................................ 599 583 \fB%N\fR 600 584 On output, produces the number of the month (1-12) with one or two digits. 601 585 digits. On input, accepts one or two digits, possibly with leading whitespace, 602 586 and interprets them as the number of the month. 603 587 .TP 604 588 \fB%Od\fR, \fB%Oe\fR, \fB%OH\fR, \fB%OI\fR, \fB%Ok\fR, \fB%Ol\fR, \fB%Om\fR, \fB%OM\fR, \fB%OS\fR, \fB%Ou\fR, \fB%Ow\fR, \fB%Oy\fR 605 589 All of these format groups are synonymous with their counterparts 606 -without the 607 -.QW \fBO\fR , 608 -except that the string is produced and parsed in the locale-dependent 609 -alternative numerals. 590 +without the '\fBO\fR', except that the string is produced and parsed in the 591 +locale-dependent alternative numerals. 610 592 .TP 611 593 \fB%p\fR 612 -. 613 594 On output, produces an indicator for the part of the day, \fBAM\fR 614 595 or \fBPM\fR, appropriate to the given locale. If the script of the 615 596 given locale supports multiple letterforms, lowercase is preferred. 616 597 On input, matches the representation \fBAM\fR or \fBPM\fR in 617 598 the given locale, in either case. 618 599 .TP 619 600 \fB%P\fR ................................................................................ 724 705 time zone. This option should, in general, be used on input only when 725 706 parsing RFC822 dates. Other uses are fraught with ambiguity; for 726 707 instance, the string \fBBST\fR may represent British Summer Time or 727 708 Brazilian Standard Time. It is recommended that date/time strings for 728 709 use by computers use numeric time zones instead. 729 710 .TP 730 711 \fB%%\fR 731 -On output, produces a literal 732 -.QW \fB%\fR 733 -character. On input, matches a literal 734 -.QW \fB%\fR 735 -character. 712 +On output, produces a literal '\fB%\fR' character. On input, matches 713 +a literal '\fB%\fR' character. 736 714 .TP 737 715 \fB%+\fR 738 -Synonymous with 739 -.QW "\fB%a %b %e %H:%M:%S %Z %Y\fR" . 716 +Synonymous with '\fB%a %b %e %H:%M:%S %Z %Y\fR'. 740 717 .SH "TIME ZONES" 741 718 When the \fBclock\fR command is processing a local time, it has several 742 719 possible sources for the time zone to use. In order of preference, they 743 720 are: 744 721 .IP [1] 745 722 A time zone specified inside a string being parsed and matched by a \fB%z\fR 746 723 or \fB%Z\fR format group. 747 724 .IP [2] 748 -A time zone specified with the \fB\-timezone\fR option to the \fBclock\fR 749 -command (or, equivalently, by 750 -.QW "\fB\-gmt\fR \fB1\fR" ). 725 +A time zone specified with the \fB-timezone\fR option to the \fBclock\fR 726 +command (or, equivalently, by \fB-gmt\fR \fB1\fR). 751 727 .IP [3] 752 728 A time zone specified in an environment variable \fBTCL_TZ\fR. 753 729 .IP [4] 754 730 A time zone specified in an environment variable \fBTZ\fR. 755 731 .IP [5] 756 732 The local time zone from the Control Panel on Windows systems. 757 733 .IP [6] ................................................................................ 779 755 .PP 780 756 If the time zone begins with a colon, it is one of a 781 757 standardized list of names like \fB:America/New_York\fR 782 758 that give the rules for various locales. A complete list 783 759 of the location names is too lengthy to be listed here. 784 760 On most Tcl installations, the definitions of the locations 785 761 are to be found in named files in the directory 786 -.QW "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR" . 787 -On some Unix systems, these 762 + "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR". On some Unix systems, these 788 763 files are omitted, and the definitions are instead 789 -obtained from system files in 790 -.QW "\fI/usr/share/zoneinfo\fR" , 791 -.QW "\fI/usr/share/lib/zoneinfo\fR" 792 -or 793 -.QW "\fI/usr/local/etc/zoneinfo\fR" . 764 +obtained from system files in "\fI/usr/share/zoneinfo\fR", 765 + "\fI/usr/share/lib/zoneinfo\fR" or "\fI/usr/local/etc/zoneinfo\fR". 794 766 As a special case, the name \fB:localtime\fR refers to 795 767 the local time zone as defined by the C library. 796 768 .PP 797 769 A time zone string consisting of a plus or minus sign followed by 798 770 four or six decimal digits is interpreted as an offset in 799 771 hours, minutes, and seconds (if six digits are present) from 800 772 UTC. The plus sign denotes a sign east of Greenwich; ................................................................................ 808 780 Any other time zone string is processed by prefixing a colon and attempting 809 781 to use it as a location name, as above. 810 782 .SH "LOCALIZATION" 811 783 Developers wishing to localize the date and time formatting and parsing 812 784 are referred to \fIhttp://tip.tcl.tk/173\fR for a 813 785 specification. 814 786 .SH "FREE FORM SCAN" 815 -If the \fBclock scan\fR command is invoked without a \fB\-format\fR 787 +If the \fBclock scan\fR command is invoked without a \fB-format\fR 816 788 option, then it requests a \fIfree-form scan.\fR \fI 817 789 This form of scan is deprecated.\fR The reason for the deprecation 818 -is that there are too many ambiguities. (Does the string 819 -.QW 2000 790 +is that there are too many ambiguities. (Does the string '2000' 820 791 represent a year, a time of day, or a quantity?) No set of rules 821 792 for interpreting free-form dates and times has been found to 822 793 give unsurprising results in all cases. 823 794 .PP 824 -If free-form scan is used, only the \fB\-base\fR and \fB\-gmt\fR 825 -options are accepted. The \fB\-timezone\fR and \fB\-locale\fR 826 -options will result in an error if \fB\-format\fR is not supplied. 795 +If free-form scan is used, only the \fB-base\fR and \fB-gmt\fR 796 +options are accepted. The \fB-timezone\fR and \fB-locale\fR 797 +options will result in an error if \fB-format\fR is not supplied. 827 798 .PP 828 799 For the benefit of users who need to understand legacy code that 829 800 uses free-form scan, the documentation for how free-form scan 830 801 interprets a string is included here: 831 802 .PP 832 803 If only a time is 833 804 specified, the current date is assumed. If the \fIinputString\fR 834 805 does not contain a 835 -time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR 806 +time zone mnemonic, the local time zone is assumed, unless the \fB-gmt\fR 836 807 argument is true, in which case the clock value is calculated assuming 837 808 that the specified time is relative to Greenwich Mean Time. 838 -\fB\-gmt\fR, if specified, affects only the computed time value; it does not 839 -impact the interpretation of \fB\-base\fR. 809 +\fB-gmt\fR, if specified, affects only the computed time value; it does not 810 +impact the interpretation of \fB-base\fR. 840 811 .PP 841 -If the \fB\-base\fR flag is specified, the next argument should contain 812 +If the \fB-base\fR flag is specified, the next argument should contain 842 813 an integer clock value. Only the date in this value is used, not the 843 814 time. This is useful for determining the time on a specific day or 844 815 doing other date-relative conversions. 845 816 .PP 846 817 The \fIinputString\fR argument consists of zero or more specifications of the 847 818 following form: 848 819 .TP ................................................................................ 849 820 \fItime\fR 850 821 A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR 851 822 or \fBhhmm ?meridian? ?zone?\fR 852 823 If no meridian is specified, \fBhh\fR is interpreted on 853 824 a 24-hour clock. 854 825 .TP 855 826 \fIdate\fR 856 -A specific month and day with optional year. The acceptable formats are 857 -.QW "\fBmm/dd\fR?\fB/yy\fR?" , 858 -.QW "\fBmonthname dd\fR?\fB, yy\fR?" , 859 -.QW "\fBday, dd monthname \fR?\fByy\fR?" , 860 -.QW "\fBdd monthname yy\fR" , 861 -.QW "?\fBCC\fR?\fByymmdd\fR" , 862 -and 863 -.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" . 827 +A specific month and day with optional year. The 828 +acceptable formats are "\fBmm/dd\fR?\fB/yy\fR?", 829 + "\fBmonthname dd\fR?\fB, yy\fR?", 830 + "\fBday, dd monthname \fR?\fByy\fR?", 831 + "\fBdd monthname yy\fR", 832 + "?\fBCC\fR?\fByymmdd\fR", and 833 + "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR". 864 834 The default year is the current year. If the year is less 865 835 than 100, we treat the years 00-68 as 2000-2068 and the years 69-99 866 836 as 1969-1999. Not all platforms can represent the years 38-70, so 867 837 an error may result if these years are used. 868 838 .TP 869 839 \fIISO 8601 point-in-time\fR 870 840 An ISO 8601 point-in-time specification, such as \fBCCyymmddThhmmss\fR, 871 -where \fBT\fR is the literal 872 -.QW T , 873 -.QW "\fBCCyymmdd hhmmss\fR" , 874 -or 875 -.QW \fBCCyymmddThh:mm:ss\fR . 876 -Note that only these three formats are accepted. 841 +where \fBT\fR is the literal T, "\fBCCyymmdd hhmmss\fR", or 842 +\fBCCyymmddThh:mm:ss\fR. Note that only these three formats are accepted. 877 843 The command does \fInot\fR accept the full range of point-in-time 878 844 specifications specified in ISO8601. Other formats can be recognized by 879 -giving an explicit \fI\-format\fR option to the \fBclock scan\fR command. 845 +giving an explicit \fI-format\fR option to the \fBclock scan\fR command. 880 846 .TP 881 847 \fIrelative time\fR 882 848 A specification relative to the current time. The format is \fBnumber 883 849 unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR, 884 850 \fBmonth\fR, \fBweek\fR, \fBday\fR, 885 851 \fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR). The 886 852 unit can be specified as a singular or plural, as in \fB3 weeks\fR.
Changes to doc/close.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: close.n,v 1.11 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: close.n,v 1.12 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH close n 7.5 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 close \- Close an open channel ................................................................................ 67 67 catch { 68 68 uplevel 1 $script 69 69 } result options 70 70 \fBclose\fR $chan 71 71 return -options $options $result 72 72 } 73 73 .CE 74 + 74 75 .SH "SEE ALSO" 75 76 file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3) 77 + 76 78 .SH KEYWORDS 77 79 blocking, channel, close, nonblocking
Changes to doc/concat.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: concat.n,v 1.8 2007/10/25 14:07:32 dkf Exp $ 8 +'\" RCS: @(#) $Id: concat.n,v 1.9 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH concat n 8.3 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 concat \- Join lists together ................................................................................ 26 26 It permits any number of arguments; 27 27 if no \fIarg\fRs are supplied, the result is an empty string. 28 28 .SH EXAMPLES 29 29 Although \fBconcat\fR will concatenate lists (so the command: 30 30 .CS 31 31 \fBconcat\fR a b {c d e} {f {g h}} 32 32 .CE 33 -will return 34 -.QW "\fBa b c d e f {g h}\fR" 35 -as its result), it will also 33 +will return "\fBa b c d e f {g h}\fR" as its result), it will also 36 34 concatenate things that are not lists, and hence the command: 37 35 .CS 38 36 \fBconcat\fR " a b {c " d " e} f" 39 37 .CE 40 -will return 41 -.QW "\fBa b {c d e} f\fR" 42 -as its result. 38 +will return "\fBa b {c d e} f\fR" as its result. 43 39 .PP 44 40 Note that the concatenation does not remove spaces from the middle of 45 41 its arguments, so the command: 46 42 .CS 47 43 \fBconcat\fR "a b c" { d e f } 48 44 .CE 49 -will return 50 -.QW "\fBa b c d e f\fR" 51 -(i.e. with three spaces between the 52 -.QW \fBa\fR , 53 -the 54 -.QW \fBb\fR 55 -and the 56 -.QW \fBc\fR ). 45 +will return "\fBa b c d e f\fR" (i.e. with three spaces between 46 +the \fBa\fR, the \fBb\fR and the \fBc\fR). 47 + 57 48 .SH "SEE ALSO" 58 49 append(n), eval(n) 50 + 59 51 .SH KEYWORDS 60 52 concatenate, join, lists
Changes to doc/continue.n.
1 1 '\" 2 2 '\" Copyright (c) 1993-1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: continue.n,v 1.8 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: continue.n,v 1.9 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH continue n "" Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 continue \- Skip to the next iteration of a loop ................................................................................ 35 35 for {set x 0} {$x<10} {incr x} { 36 36 if {$x == 5} { 37 37 \fBcontinue\fR 38 38 } 39 39 puts "x is $x" 40 40 } 41 41 .CE 42 + 42 43 .SH "SEE ALSO" 43 44 break(n), for(n), foreach(n), return(n), while(n) 45 + 44 46 .SH KEYWORDS 45 47 continue, iteration, loop
Changes to doc/dde.n.
1 1 '\" 2 2 '\" Copyright (c) 1997 Sun Microsystems, Inc. 3 3 '\" Copyright (c) 2001 ActiveState Corporation. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: dde.n,v 1.19 2007/10/25 14:07:32 dkf Exp $ 8 +'\" RCS: @(#) $Id: dde.n,v 1.20 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH dde n 1.3 dde "Tcl Bundled Packages" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 dde \- Execute a Dynamic Data Exchange command ................................................................................ 44 44 .PP 45 45 .SH "DDE COMMANDS" 46 46 .PP 47 47 The following commands are a subset of the full Dynamic Data Exchange 48 48 set of commands. 49 49 .TP 50 50 \fBdde servername \fR?\fB-force\fR? ?\fB-handler \fIproc\fR? ?\fB--\fR? ?\fItopic\fR? 51 -. 52 51 \fBdde servername\fR registers the interpreter as a DDE server with 53 52 the service name \fBTclEval\fR and the topic name specified by \fItopic\fR. 54 53 If no \fItopic\fR is given, \fBdde servername\fR returns the name 55 54 of the current topic or the empty string if it is not registered as a 56 55 service. If the given \fItopic\fR name is already in use, then a 57 -suffix of the form 58 -.QW " #2" 59 -or 60 -.QW " #3" 61 -is appended to the name to make it 56 +suffix of the form ' #2' or ' #3' is appended to the name to make it 62 57 unique. The command's result will be the name actually used. The 63 -\fB\-force\fR option is used to force registration of precisely the 58 +\fB-force\fR option is used to force registration of precisely the 64 59 given \fItopic\fR name. 65 60 .IP 66 61 The \fB-handler\fR option specifies a Tcl procedure that will be called to 67 62 process calls to the dde server. If the package has been loaded into a 68 63 safe interpreter then a \fB-handler\fR procedure must be defined. The 69 64 procedure is called with all the arguments provided by the remote 70 65 call. 71 66 .TP 72 67 \fBdde execute\fR ?\fB\-async\fR? \fIservice topic data\fR 73 -. 74 68 \fBdde execute\fR takes the \fIdata\fR and sends it to the server indicated 75 69 by \fIservice\fR with the topic indicated by \fItopic\fR. Typically, 76 70 \fIservice\fR is the name of an application, and \fItopic\fR is a file to 77 71 work on. The \fIdata\fR field is given to the remote application. 78 72 Typically, the application treats the \fIdata\fR field as a script, and the 79 73 script is run in the application. The \fB\-async\fR option requests 80 74 asynchronous invocation. The command returns an error message if the 81 75 script did not run, unless the \fB\-async\fR flag was used, in which case 82 76 the command returns immediately with no error. 83 77 .TP 84 78 \fBdde poke \fIservice topic item data\fR 85 -. 86 79 \fBdde poke\fR passes the \fIdata\fR to the server indicated by 87 80 \fIservice\fR using the \fItopic\fR and \fIitem\fR specified. Typically, 88 81 \fIservice\fR is the name of an application. \fItopic\fR is application 89 82 specific but can be a command to the server or the name of a file to work 90 83 on. The \fIitem\fR is also application specific and is often not used, but 91 84 it must always be non-null. The \fIdata\fR field is given to the remote 92 85 application. 93 86 .TP 94 87 \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR 95 -. 96 88 \fBdde request\fR is typically used to get the value of something; the 97 89 value of a cell in Microsoft Excel or the text of a selection in 98 90 Microsoft Word. \fIservice\fR is typically the name of an application, 99 91 \fItopic\fR is typically the name of the file, and \fIitem\fR is 100 92 application-specific. The command returns the value of \fIitem\fR as 101 93 defined in the application. Normally this is interpreted to be a 102 94 string with terminating null. If \fB\-binary\fR is specified, the 103 95 result is returned as a byte array. 104 96 .TP 105 97 \fBdde services \fIservice topic\fR 106 -. 107 98 \fBdde services\fR returns a list of service-topic pairs that 108 99 currently exist on the machine. If \fIservice\fR and \fItopic\fR are 109 100 both empty strings ({}), then all service-topic pairs currently 110 101 available on the system are returned. If \fIservice\fR is empty and 111 102 \fItopic\fR is not, then all services with the specified topic are 112 103 returned. If \fIservice\fR is non-empty and \fItopic\fR is, all topics 113 104 for a given service are returned. If both are non-empty, if that 114 105 service-topic pair currently exists, it is returned; otherwise, an 115 106 empty string is returned. 116 107 .TP 117 108 \fBdde eval\fR ?\fB\-async\fR? \fItopic cmd \fR?\fIarg arg ...\fR? 118 -. 119 109 \fBdde eval\fR evaluates a command and its arguments using the interpreter 120 110 specified by \fItopic\fR. The DDE service must be the \fBTclEval\fR 121 111 service. The \fB\-async\fR option requests asynchronous invocation. The 122 112 command returns an error message if the script did not run, unless the 123 113 \fB\-async\fR flag was used, in which case the command returns immediately 124 114 with no error. This command can be used to replace send on Windows. 125 115 .SH "DDE AND TCL" ................................................................................ 157 147 .SH EXAMPLE 158 148 This asks Internet Explorer (which must already be running) to go to a 159 149 particularly important website: 160 150 .CS 161 151 package require dde 162 152 \fBdde execute\fR iexplore WWW_OpenURL http://www.tcl.tk/ 163 153 .CE 154 + 164 155 .SH "SEE ALSO" 165 156 tk(n), winfo(n), send(n) 157 + 166 158 .SH KEYWORDS 167 159 application, dde, name, remote execution
Changes to doc/dict.n.
1 1 '\" 2 2 '\" Copyright (c) 2003 Donal K. Fellows 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: dict.n,v 1.13 2007/10/24 14:29:38 dkf Exp $ 7 +'\" RCS: @(#) $Id: dict.n,v 1.14 2007/10/26 20:11:52 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH dict n 8.5 Tcl "Tcl Built-In Commands" 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 dict \- Manipulate dictionaries ................................................................................ 253 253 } 254 254 } 255 255 # Another way to iterate and pick out names... 256 256 foreach id [\fBdict keys\fR $employeeInfo] { 257 257 puts "Hello, [\fBdict get\fR $employeeInfo $id forenames]!" 258 258 } 259 259 .CE 260 -.PP 260 + 261 261 A localizable version of \fBstring toupper\fR: 262 262 .CS 263 263 # Set up the basic C locale 264 264 set capital [\fBdict create\fR C [\fBdict create\fR]] 265 265 foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] { 266 266 \fBdict set\fR capital C $c [string toupper $c] 267 267 } ................................................................................ 273 273 274 274 # ... and so on for other supported languages ... 275 275 276 276 # Now get the mapping for the current locale and use it. 277 277 set upperCaseMap [\fBdict get\fR $capital $env(LANG)] 278 278 set upperCase [string map $upperCaseMap $string] 279 279 .CE 280 + 280 281 .SH "SEE ALSO" 281 282 append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n) 283 + 282 284 .SH KEYWORDS 283 285 dictionary, create, update, lookup, iterate, filter
Changes to doc/encoding.n.
1 1 '\" 2 2 '\" Copyright (c) 1998 by Scriptics Corporation. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: encoding.n,v 1.11 2007/10/26 12:25:06 dkf Exp $ 7 +'\" RCS: @(#) $Id: encoding.n,v 1.12 2007/10/26 20:11:52 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH encoding n "8.1" Tcl "Tcl Built-In Commands" 11 11 .BS 12 12 .SH NAME 13 13 encoding \- Manipulate encodings 14 14 .SH SYNOPSIS ................................................................................ 78 78 that maps to the 00 page in Unicode. The resulting Tcl strings will 79 79 not contain the expected Japanese characters. Instead, they will 80 80 contain a sequence of Latin-1 characters that correspond to the bytes 81 81 of the original string. The \fBencoding\fR command can be used to 82 82 convert this string to the expected Japanese Unicode characters. For 83 83 example, 84 84 .CS 85 -set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"] 85 +set s [\fBencoding convertfrom\fR euc-jp "\\xA4\\xCF"] 86 86 .CE 87 -would return the Unicode string 88 -.QW "\eu306F" , 89 -which is the Hiragana letter HA. 87 +would return the Unicode string "\\u306F", which is the Hiragana 88 +letter HA. 89 + 90 90 .SH "SEE ALSO" 91 -fconfigure(n), Tcl_GetEncoding(3) 91 +Tcl_GetEncoding(3) 92 + 92 93 .SH KEYWORDS 93 94 encoding
Changes to doc/eof.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: eof.n,v 1.7 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: eof.n,v 1.8 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH eof n 7.5 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 eof \- Check for end of file condition on channel ................................................................................ 51 51 if {[\fBeof\fR $f]} { 52 52 close $f 53 53 break 54 54 } 55 55 puts "Read record: $record" 56 56 } 57 57 .CE 58 + 58 59 .SH "SEE ALSO" 59 60 file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3) 61 + 60 62 .SH KEYWORDS 61 63 channel, end of file
Changes to doc/exec.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2006 Donal K. Fellows. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: exec.n,v 1.18 2007/10/25 14:07:32 dkf Exp $ 9 +'\" RCS: @(#) $Id: exec.n,v 1.19 2007/10/26 20:11:52 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH exec n 8.5 Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 exec \- Invoke subprocesses ................................................................................ 45 45 Marks the end of switches. The argument following this one will 46 46 be treated as the first \fIarg\fR even if it starts with a \fB\-\fR. 47 47 .PP 48 48 If an \fIarg\fR (or pair of \fIarg\fRs) has one of the forms 49 49 described below then it is used by \fBexec\fR to control the 50 50 flow of input and output among the subprocess(es). 51 51 Such arguments will not be passed to the subprocess(es). In forms 52 -such as 53 -.QW "< \fIfileName\fR" , 54 -\fIfileName\fR may either be in a separate argument from 55 -.QW < 56 -or in the same argument with no intervening space (i.e. 57 -.QW <\fIfileName\fR ). 52 +such as ``< \fIfileName\fR'' \fIfileName\fR may either be in a 53 +separate argument from ``<'' or in the same argument with no 54 +intervening space (i.e. ``<\fIfileName\fR''). 58 55 .TP 15 59 56 | 60 57 Separates distinct commands in the pipeline. The standard output 61 58 of the preceding command will be piped into the standard input 62 59 of the next command. 63 60 .TP 15 64 61 |& ................................................................................ 133 130 all commands are redirected to \fIfileId\fR's file. 134 131 The file must have been opened for writing. 135 132 .PP 136 133 If standard output has not been redirected then the \fBexec\fR 137 134 command returns the standard output from the last command 138 135 in the pipeline, 139 136 .VS 8.5 140 -unless 141 -.QW 2>@1 142 -was specified, in which case standard error is included as well. 137 +unless ``2>@1'' was specified, in which case 138 +standard error is included as well. 143 139 .VE 8.5 144 140 If any of the commands in the pipeline exit abnormally or 145 141 are killed or suspended, then \fBexec\fR will return an error 146 142 and the error message will include the pipeline's output followed by 147 143 error messages describing the abnormal terminations; the 148 144 \fB-errorcode\fR return option will contain additional information 149 145 about the last abnormal termination encountered. ................................................................................ 161 157 is a newline then that character is normally deleted 162 158 from the result or error message. 163 159 This is consistent with other Tcl return values, which don't 164 160 normally end with newlines. 165 161 However, if \fB\-keepnewline\fR is specified then the trailing 166 162 newline is retained. 167 163 .PP 168 -If standard input isn't redirected with 169 -.QW < , 170 -.QW << 171 -or 172 -.QW <@ 173 -then the standard input for the first command in the 164 +If standard input isn't redirected with ``<'' or ``<<'' 165 +or ``<@'' then the standard input for the first command in the 174 166 pipeline is taken from the application's current standard input. 175 167 .PP 176 -If the last \fIarg\fR is 177 -.QW & 178 -then the pipeline will be executed in background. 168 +If the last \fIarg\fR is ``&'' then the pipeline will be 169 +executed in background. 179 170 In this case the \fBexec\fR command will return a list whose 180 171 elements are the process identifiers for all of the subprocesses 181 172 in the pipeline. 182 173 The standard output from the last command in the pipeline will 183 174 go to the application's standard output if it hasn't been 184 175 redirected, and error output from all of 185 176 the commands in the pipeline will go to the application's ................................................................................ 187 178 .PP 188 179 The first word in each command is taken as the command name; 189 180 tilde-substitution is performed on it, and if the result contains 190 181 no slashes then the directories 191 182 in the PATH environment variable are searched for 192 183 an executable by the given name. 193 184 If the name contains a slash then it must refer to an executable 194 -reachable from the current directory. No 195 -.QW glob 196 -expansion or other shell-like substitutions 185 +reachable from the current directory. 186 +No ``glob'' expansion or other shell-like substitutions 197 187 are performed on the arguments to commands. 198 188 .SH "PORTABILITY ISSUES" 199 189 .TP 200 190 \fBWindows\fR (all versions) 201 191 . 202 -Reading from or writing to a socket, using the 203 -.QW \[email protected]\0\fIfileId\fR 192 +Reading from or writing to a socket, using the ``\[email protected]\0\fIfileId\fR'' 204 193 notation, does not work. When reading from a socket, a 16-bit DOS 205 194 application will hang and a 32-bit application will return immediately with 206 195 end-of-file. When either type of application writes to a socket, the 207 196 information is instead sent to the console, if one is present, or is 208 197 discarded. 209 198 .RS 210 199 .PP ................................................................................ 221 210 backslashes only in paths. Any arguments to an application that specify a 222 211 path name with forward slashes will not automatically be converted to use 223 212 the backslash character. If an argument contains forward slashes as the 224 213 path separator, it may or may not be recognized as a path name, depending on 225 214 the program. 226 215 .PP 227 216 Additionally, when calling a 16-bit DOS or Windows 3.X application, all path 228 -names must use the short, cryptic, path format (e.g., using 229 -.QW applba~1.def 230 -instead of 231 -.QW applbakery.default ), 232 -which can be obtained with the 217 +names must use the short, cryptic, path format (e.g., using ``applba~1.def'' 218 +instead of ``applbakery.default''), which can be obtained with the 233 219 \fBfile attributes $fileName -shortname\fR command. 234 220 .PP 235 221 Two or more forward or backward slashes in a row in a path refer to a 236 222 network path. For example, a simple concatenation of the root directory 237 223 \fBc:/\fR with a subdirectory \fB/windows/system\fR will yield 238 224 \fBc://windows/system\fR (two slashes together), which refers to the mount 239 225 point called \fBsystem\fR on the machine called \fBwindows\fR (and the ................................................................................ 284 270 The Windows NT 16-bit system directory. 285 271 .IP \(bu 286 272 The Windows NT home directory. 287 273 .IP \(bu 288 274 The directories listed in the path. 289 275 .PP 290 276 In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR, 291 -the caller must prepend the desired command with 292 -.QW "\fBcmd.exe /c\0\fR" 277 +the caller must prepend the desired command with ``\fBcmd.exe /c\0\fR'' 293 278 because built-in commands are not implemented using executables. 294 279 .RE 295 280 .TP 296 281 \fBWindows 9x\fR 297 282 . 298 283 When attempting to execute an application, \fBexec\fR first searches for 299 284 the name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and ................................................................................ 310 295 The Windows 9x system directory. 311 296 .IP \(bu 312 297 The Windows 9x home directory. 313 298 .IP \(bu 314 299 The directories listed in the path. 315 300 .PP 316 301 In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR, 317 -the caller must prepend the desired command with 318 -.QW "\fBcommand.com /c\0\fR" 302 +the caller must prepend the desired command with ``\fBcommand.com /c\0\fR'' 319 303 because built-in commands are not implemented using executables. 320 304 .PP 321 305 Once a 16-bit DOS application has read standard input from a console and 322 306 then quit, all subsequently run 16-bit DOS applications will see the 323 307 standard input as already closed. 32-bit applications do not have this 324 308 problem and will run correctly, even after a 16-bit DOS application thinks 325 309 that standard input is closed. There is no known workaround for this bug 326 310 at this time. 327 311 .PP 328 312 Redirection between the \fBNUL:\fR device and a 16-bit application does not 329 313 always work. When redirecting from \fBNUL:\fR, some applications may hang, 330 -others will get an infinite stream of 331 -.QW 0x01 332 -bytes, and some will actually 314 +others will get an infinite stream of ``0x01'' bytes, and some will actually 333 315 correctly get an immediate end-of-file; the behavior seems to depend upon 334 316 something compiled into the application itself. When redirecting greater than 335 317 4K or so to \fBNUL:\fR, some applications will hang. The above problems do not 336 318 happen with 32-bit applications. 337 319 .PP 338 320 All DOS 16-bit applications are run synchronously. All standard input from 339 321 a pipe to a 16-bit DOS application is collected into a temporary file; the ................................................................................ 424 406 same name and be in the path. It can then happen that typing a command 425 407 at the DOS prompt finds \fIa different program\fR than the same 426 408 command run via \fBexec\fR. This is because of the (documented) 427 409 differences in behaviour between \fBexec\fR and DOS batch files. 428 410 .PP 429 411 When in doubt, use the command \fBauto_execok\fR: it will return the 430 412 complete path to the program as seen by the \fBexec\fR command. This 431 -applies especially when you want to run 432 -.QW "internal" 433 -commands like \fIdir\fR from a Tcl script (if you just want to list 434 -filenames, use the \fBglob\fR command.) To do that, use this: 413 +applies especially when you want to run "internal" commands like 414 +\fIdir\fR from a Tcl script (if you just want to list filenames, use 415 +the \fBglob\fR command.) To do that, use this: 435 416 .CS 436 417 \fBexec\fR {*}[auto_execok dir] *.tcl 437 418 .CE 438 419 .SH "SEE ALSO" 439 420 error(n), open(n) 440 421 .SH KEYWORDS 441 422 execute, pipeline, redirection, subprocess
Changes to doc/expr.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-2000 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2005 by Kevin B. Kenny <[email protected]>. All rights reserved 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: expr.n,v 1.26 2007/10/25 09:35:14 dkf Exp $ 9 +'\" RCS: @(#) $Id: expr.n,v 1.27 2007/10/26 20:11:52 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH expr n 8.5 Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 expr \- Evaluate an expression ................................................................................ 103 103 .PP 104 104 For some examples of simple expressions, suppose the variable 105 105 \fBa\fR has the value 3 and 106 106 the variable \fBb\fR has the value 6. 107 107 Then the command on the left side of each of the lines below 108 108 will produce the value on the right side of the line: 109 109 .CS 110 -.ta 3.5i 111 -\fBexpr\fR 3.1 + $a \fB\(-> \fI6.1\fR 112 -\fBexpr\fR 2 + "$a.$b" \fB\(-> \fI5.6\fR 113 -\fBexpr\fR 4*[llength "6 2"] \fB\(-> \fI8\fR 114 -\fBexpr\fR {{word one} < "word $a"} \fB\(-> \fI0\fR 110 +.ta 6c 111 +\fBexpr\fR 3.1 + $a \fI6.1\fR 112 +\fBexpr\fR 2 + "$a.$b" \fI5.6\fR 113 +\fBexpr\fR 4*[llength "6 2"] \fI8\fR 114 +\fBexpr\fR {{word one} < "word $a"} \fI0\fR 115 115 .CE 116 116 .SS OPERATORS 117 117 .PP 118 118 The valid operators are listed below, grouped in decreasing order 119 119 of precedence: 120 120 .TP 20 121 121 \fB\-\0\0+\0\0~\0\0!\fR ................................................................................ 199 199 All of the binary operators group left-to-right within the same 200 200 precedence level. For example, the command 201 201 .CS 202 202 \fBexpr\fR {4*2 < 7} 203 203 .CE 204 204 returns 0. 205 205 .PP 206 -The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have 207 -.QW "lazy evaluation" , 208 -just as in C, which means that operands are not evaluated if they are 206 +The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have ``lazy 207 +evaluation'', just as in C, 208 +which means that operands are not evaluated if they are 209 209 not needed to determine the outcome. For example, in the command 210 210 .CS 211 211 \fBexpr {$v ? [a] : [b]}\fR 212 212 .CE 213 213 only one of \fB[a]\fR or \fB[b]\fR will actually be evaluated, 214 214 depending on the value of \fB$v\fR. Note, however, that this is 215 215 only true if the entire expression is enclosed in braces; otherwise ................................................................................ 269 269 \fBexpr\fR {5 / 4} 270 270 .CE 271 271 returns 1, while 272 272 .CS 273 273 \fBexpr\fR {5 / 4.0} 274 274 \fBexpr\fR {5 / ( [string length "abcd"] + 0.0 )} 275 275 .CE 276 -both return 1.25. Floating-point values are always returned with a 277 -.QW \fB.\fR 276 +both return 1.25. 277 +Floating-point values are always returned with a ``\fB.\fR'' 278 278 or an \fBe\fR so that they will not look like integer values. For 279 279 example, 280 280 .CS 281 281 \fBexpr\fR {20.0/5.0} 282 282 .CE 283 283 returns \fB4.0\fR, not \fB4\fR. 284 284 .SS "STRING OPERATIONS" ................................................................................ 334 334 the bytecode compiler must emit 335 335 additional instructions to handle this situation. 336 336 The most expensive code is required for 337 337 unbraced expressions that contain command substitutions. 338 338 These expressions must be implemented by generating new code 339 339 each time the expression is executed. 340 340 .SH EXAMPLES 341 -Define a procedure that computes an 342 -.QW "interesting" 343 -mathematical function: 341 +Define a procedure that computes an "interesting" mathematical 342 +function: 344 343 .CS 345 344 proc tcl::mathfunc::calc {x y} { 346 345 \fBexpr\fR { ($x**2 - $y**2) / exp($x**2 + $y**2) } 347 346 } 348 347 .CE 349 348 .PP 350 349 Convert polar coordinates into cartesian coordinates: ................................................................................ 376 375 }] 377 376 .CE 378 377 .PP 379 378 Generate a random integer in the range 0..99 inclusive: 380 379 .CS 381 380 set randNum [\fBexpr\fR { int(100 * rand()) }] 382 381 .CE 382 + 383 383 .SH "SEE ALSO" 384 -array(n), for(n), if(n), mathfunc(n), namespace(n), proc(n), string(n), 385 -Tcl(n), while(n) 384 +array(n), for(n), if(n), mathfunc(n), namespace(n), proc(n), string(n), Tcl(n), while(n) 385 + 386 386 .SH KEYWORDS 387 387 arithmetic, boolean, compare, expression, fuzzy comparison 388 + 388 389 .SH COPYRIGHT 389 -.nf 390 -Copyright \(co 1993 The Regents of the University of California. 391 -Copyright \(co 1994-2000 Sun Microsystems Incorporated. 392 -Copyright \(co 2005 by Kevin B. Kenny. All rights reserved. 393 -.fi 390 +Copyright (c) 1993 The Regents of the University of California. 391 +.br 392 +Copyright (c) 1994-2000 Sun Microsystems Incorporated. 393 +.br 394 +Copyright (c) 2005 by Kevin B. Kenny <[email protected]>. All rights reserved.
Changes to doc/fcopy.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: fcopy.n,v 1.13 2007/10/25 14:07:32 dkf Exp $ 8 +'\" RCS: @(#) $Id: fcopy.n,v 1.14 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH fcopy n 8.0 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 fcopy \- Copy data from one channel to another ................................................................................ 55 55 and the command callback is \fInot\fR made. 56 56 If \fIinchan\fR is closed, 57 57 then all data already queued for \fIoutchan\fR is written out. 58 58 .PP 59 59 Note that \fIinchan\fR can become readable during a background copy. 60 60 You should turn off any \fBfileevent\fR handlers during a background 61 61 copy so those handlers do not interfere with the copy. 62 -Any I/O attempted by a \fBfileevent\fR handler will get a 63 -.QW "channel busy" 64 -error. 62 +Any I/O attempted by a \fBfileevent\fR handler will get a "channel busy" error. 65 63 .PP 66 64 \fBFcopy\fR translates end-of-line sequences in \fIinchan\fR and \fIoutchan\fR 67 65 according to the \fB\-translation\fR option 68 66 for these channels. 69 67 See the manual entry for \fBfconfigure\fR for details on the 70 68 \fB\-translation\fR option. 71 69 The translations mean that the number of bytes read from \fIinchan\fR ................................................................................ 76 74 .PP 77 75 \fBFcopy\fR obeys the encodings and character translations configured 78 76 for the channels. This 79 77 means that the incoming characters are converted internally first 80 78 UTF-8 and then into the encoding of the channel \fBfcopy\fR writes 81 79 to. See the manual entry for \fBfconfigure\fR for details on the 82 80 \fB\-encoding\fR and \fB\-translation\fR options. No conversion is 83 -done if both channels are set to encoding 84 -.QW "binary" 85 -and have matching translations. If only the output channel is set to encoding 86 -.QW "binary" 87 -the system will write the internal UTF-8 representation of the incoming 88 -characters. If only the input channel is set to encoding 89 -.QW "binary" 90 -the system will assume that the incoming bytes are valid UTF-8 characters and 91 -convert them according to the output encoding. The behaviour of the system for 92 -bytes which are not valid UTF-8 characters is undefined in this case. 81 +done if both channels are 82 +set to encoding "binary" and have matching translations. If only the 83 +output channel is set to 84 +encoding "binary" the system will write the internal UTF-8 85 +representation of the incoming characters. If only the input channel 86 +is set to encoding "binary" the system will assume that the incoming 87 +bytes are valid UTF-8 characters and convert them according to the 88 +output encoding. The behaviour of the system for bytes which are not 89 +valid UTF-8 characters is undefined in this case. 90 + 93 91 .SH EXAMPLES 94 92 .PP 95 93 The first example transfers the contents of one channel exactly to 96 94 another. Note that when copying one file to another, it is better to 97 95 use \fBfile copy\fR which also copies file metadata (e.g. the file 98 96 access permissions) where possible. 99 97 .CS ................................................................................ 142 140 set out [socket $server $port] 143 141 set chunk 1024 144 142 set total 0 145 143 \fBfcopy\fR $in $out -size $chunk \\ 146 144 -command [list CopyMore $in $out $chunk] 147 145 vwait done 148 146 .CE 147 + 149 148 .SH "SEE ALSO" 150 149 eof(n), fblocked(n), fconfigure(n), file(n) 150 + 151 151 .SH KEYWORDS 152 152 blocking, channel, end of line, end of file, nonblocking, read, translation
Changes to doc/file.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: file.n,v 1.46 2007/10/25 14:07:32 dkf Exp $ 8 +'\" RCS: @(#) $Id: file.n,v 1.47 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH file n 8.3 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 file \- Manipulate file names and attributes ................................................................................ 43 43 .RS 44 44 This subcommand returns or sets platform specific values associated 45 45 with a file. The first form returns a list of the platform specific 46 46 flags and their values. The second form returns the value for the 47 47 specific option. The third form sets one or more of the values. The 48 48 values are as follows: 49 49 .PP 50 -On Unix, \fB\-group\fR gets or sets the group name for the file. A group id 51 -can be given to the command, but it returns a group name. \fB\-owner\fR gets 50 +On Unix, \fB-group\fR gets or sets the group name for the file. A group id 51 +can be given to the command, but it returns a group name. \fB-owner\fR gets 52 52 or sets the user name of the owner of the file. The command returns the 53 53 owner name, but the numerical id can be passed when setting the 54 -owner. \fB\-permissions\fR sets or retrieves the octal code that chmod(1) 54 +owner. \fB-permissions\fR sets or retrieves the octal code that chmod(1) 55 55 uses. This command does also has limited support for setting using the 56 56 symbolic attributes for chmod(1), of the form [ugo]?[[+\-=][rwxst],[...]], 57 57 where multiple symbolic attributes can be separated by commas (example: 58 58 \fBu+s,go\-rw\fR add sticky bit for user, remove read and write 59 59 permissions for group and other). A simplified \fBls\fR style string, 60 60 of the form rwxrwxrwx (must be 9 characters), is also supported 61 61 (example: \fBrwxr\-xr\-t\fR is equivalent to 01755). 62 -On versions of Unix supporting file flags, \fB\-readonly\fR gives the 62 +On versions of Unix supporting file flags, \fB-readonly\fR gives the 63 63 value or sets or clears the readonly attribute of the file, 64 64 i.e. the user immutable flag \fBuchg\fR to chflags(1). 65 65 .PP 66 -On Windows, \fB\-archive\fR gives the value or sets or clears the 67 -archive attribute of the file. \fB\-hidden\fR gives the value or sets 68 -or clears the hidden attribute of the file. \fB\-longname\fR will 66 +On Windows, \fB-archive\fR gives the value or sets or clears the 67 +archive attribute of the file. \fB-hidden\fR gives the value or sets 68 +or clears the hidden attribute of the file. \fB-longname\fR will 69 69 expand each path element to its long version. This attribute cannot be 70 -set. \fB\-readonly\fR gives the value or sets or clears the readonly 71 -attribute of the file. \fB\-shortname\fR gives a string where every 70 +set. \fB-readonly\fR gives the value or sets or clears the readonly 71 +attribute of the file. \fB-shortname\fR gives a string where every 72 72 path element is replaced with its short (8.3) version of the 73 -name. This attribute cannot be set. \fB\-system\fR gives or sets or 73 +name. This attribute cannot be set. \fB-system\fR gives or sets or 74 74 clears the value of the system attribute of the file. 75 75 .PP 76 -On Mac OS X and Darwin, \fB\-creator\fR gives or sets the 77 -Finder creator type of the file. \fB\-hidden\fR gives or sets or clears 78 -the hidden attribute of the file. \fB\-readonly\fR gives or sets or 79 -clears the readonly attribute of the file. \fB\-rsrclength\fR gives 76 +On Mac OS X and Darwin, \fB-creator\fR gives or sets the 77 +Finder creator type of the file. \fB-hidden\fR gives or sets or clears 78 +the hidden attribute of the file. \fB-readonly\fR gives or sets or 79 +clears the readonly attribute of the file. \fB-rsrclength\fR gives 80 80 the length of the resource fork of the file, this attribute can only be 81 81 set to the value 0, which results in the resource fork being stripped 82 82 off the file. 83 83 .RE 84 84 .TP 85 85 \fBfile channels ?\fIpattern\fR? 86 86 . ................................................................................ 118 118 argument. Non-empty directories will be removed only if the 119 119 \fB\-force\fR option is specified. When operating on symbolic links, 120 120 the links themselves will be deleted, not the objects they point to. 121 121 Trying to delete a non-existent file is not considered an error. 122 122 Trying to delete a read-only file will cause the file to be deleted, 123 123 even if the \fB\-force\fR flags is not specified. If the \fB\-force\fR 124 124 option is specified on a directory, Tcl will attempt both to change 125 -permissions and move the current directory 126 -.QW pwd 127 -out of the given path 125 +permissions and move the current directory 'pwd' out of the given path 128 126 if that is necessary to allow the deletion to proceed. Arguments are 129 127 processed in the order specified, halting at the first error, if any. 130 128 A \fB\-\|\-\fR marks the end of switches; the argument following the 131 129 \fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with 132 130 a \fB\-\fR. 133 131 .TP 134 132 \fBfile dirname \fIname\fR 135 133 Returns a name comprised of all of the path components in \fIname\fR 136 134 excluding the last element. If \fIname\fR is a relative file name and 137 -only contains one path element, then returns 138 -.QW \fB.\fR . 139 -If \fIname\fR refers to a root directory, then the root directory is 140 -returned. For example, 135 +only contains one path element, then returns ``\fB.\fR''. If \fIname\fR 136 +refers to a root directory, then the root directory is returned. For 137 +example, 141 138 .RS 142 139 .CS 143 140 \fBfile dirname c:/\fR 144 141 .CE 145 142 returns \fBc:/\fR. 146 143 .PP 147 144 Note that tilde substitution will only be ................................................................................ 194 191 returns \fB/foo/bar\fR. 195 192 .PP 196 193 Note that any of the names can contain separators, and that the result 197 194 is always canonical for the current platform: \fB/\fR for Unix and 198 195 Windows. 199 196 .RE 200 197 .TP 201 -\fBfile link ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR? 198 +\fBfile link ?\fI-linktype\fR? \fIlinkName\fR ?\fItarget\fR? 202 199 . 203 200 If only one argument is given, that argument is assumed to be 204 201 \fIlinkName\fR, and this command returns the value of the link given by 205 202 \fIlinkName\fR (i.e. the name of the file it points to). If 206 203 \fIlinkName\fR isn't a link or its value cannot be read (as, for example, 207 204 seems to be the case with hard links, which look just like ordinary 208 205 files), then an error is returned. ................................................................................ 215 212 type of the link is platform-specific (on Unix a symbolic link will be 216 213 the default). This is useful for the case where the user wishes to 217 214 create a link in a cross-platform way, and doesn't care what type of 218 215 link is created. 219 216 . 220 217 If the user wishes to make a link of a specific type only, (and signal an 221 218 error if for some reason that is not possible), then the optional 222 -\fI\-linktype\fR argument should be given. Accepted values for 223 -\fI\-linktype\fR are 224 -.QW "\-symbolic" 225 -and 226 -.QW "\-hard" . 219 +\fI-linktype\fR argument should be given. Accepted values for 220 +\fI-linktype\fR are "-symbolic" and "-hard". 227 221 . 228 222 On Unix, symbolic links can be made to relative paths, and those paths 229 223 must be relative to the actual \fIlinkName\fR's location (not to the 230 224 cwd), but on all other platforms where relative links are not supported, 231 225 target paths will always be converted to absolute, normalized form 232 226 before the link is created (and therefore relative paths are interpreted 233 -as relative to the cwd). Furthermore, 234 -.QW "~user" 235 -paths are always expanded 227 +as relative to the cwd). Furthermore, "~user" paths are always expanded 236 228 to absolute form. When creating links on filesystems that either do not 237 229 support any links, or do not support the specific type requested, an 238 230 error message will be returned. In particular Windows 95, 98 and ME do 239 231 not support any links at present, but most Unix platforms support both 240 232 symbolic and hard links (the latter for files only) and Windows 241 233 NT/2000/XP (on NTFS drives) support symbolic 242 234 directory links and hard file links. ................................................................................ 276 268 .TP 277 269 \fBfile normalize \fIname\fR 278 270 . 279 271 .RS 280 272 Returns a unique normalized path representation for the file-system 281 273 object (file, directory, link, etc), whose string value can be used as a 282 274 unique identifier for it. A normalized path is an absolute path which has 283 -all 284 -.QW ../ , 285 -.QW ./ 286 -removed. Also it is one which is in the 287 -.QW standard 275 +all '../', './' removed. Also it is one which is in the ``standard'' 288 276 format for the native platform. On Unix, this means the segments 289 277 leading up to the path must be free of symbolic links/aliases (but the 290 278 very last path component may be a symbolic link), and on Windows it also 291 279 means we want the long form with that form's case-dependence (which 292 280 gives us a unique, case-dependent path). The one exception concerning the 293 281 last link in the path is necessary, because Tcl or the user may wish to 294 -operate on the actual symbolic link itself (for example \fBfile 295 -delete\fR, \fBfile rename\fR, \fBfile copy\fR are defined to operate 296 -on symbolic links, not on the things that they point to). 282 +operate on the actual symbolic link itself (for example 'file delete', 'file 283 +rename', 'file copy' are defined to operate on symbolic links, not on the 284 +things that they point to). 297 285 .RE 298 286 .TP 299 287 \fBfile owned \fIname\fR 300 288 . 301 289 Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR 302 290 otherwise. 303 291 .TP ................................................................................ 342 330 switches; the argument following the \fB\-\|\-\fR will be treated as a 343 331 \fIsource\fR even if it starts with a \fB\-\fR. 344 332 .RE 345 333 .TP 346 334 \fBfile rootname \fIname\fR 347 335 . 348 336 Returns all of the characters in \fIname\fR up to but not including the 349 -last 350 -.QW . 351 -character in the last component of name. If the last 337 +last ``.'' character in the last component of name. If the last 352 338 component of \fIname\fR doesn't contain a dot, then returns \fIname\fR. 353 339 .TP 354 340 \fBfile separator\fR ?\fIname\fR? 355 341 . 356 342 If no argument is given, returns the character which is used to separate 357 343 path segments for native files on this platform. If a path is given, 358 344 the filesystem responsible for that path is asked to return its ................................................................................ 398 384 \fBfile system \fIname\fR 399 385 . 400 386 Returns a list of one or two elements, the first of which is the name of 401 387 the filesystem to use for the file, and the second, if given, an 402 388 arbitrary string representing the filesystem-specific nature or type of 403 389 the location within that filesystem. If a filesystem only supports one 404 390 type of file, the second element may not be supplied. For example the 405 -native files have a first element 406 -.QW native , 407 -and a second element which 391 +native files have a first element 'native', and a second element which 408 392 when given is a platform-specific type name for the file's system 409 -(e.g. 410 -.QW NTFS , 411 -.QW FAT , 412 -on Windows). A generic virtual file system might return the list 413 -.QW "vfs ftp" 414 -to represent a file on a remote ftp site mounted as a virtual 415 -filesystem through an extension called 416 -.QW vfs . 417 -If the file does not belong to any filesystem, an error is generated. 393 +(e.g. 'NTFS', 'FAT', on Windows). A generic virtual file system might return 394 +the list 'vfs ftp' to represent a file on a remote ftp site mounted as a 395 +virtual filesystem through an extension called 'vfs'. If the file does 396 +not belong to any filesystem, an error is generated. 418 397 .TP 419 398 \fBfile tail \fIname\fR 420 399 . 421 400 Returns all of the characters in the last filesystem component of 422 401 \fIname\fR. Any trailing directory separator in \fIname\fR is ignored. 423 402 If \fIname\fR contains no separators then returns \fIname\fR. So, 424 403 \fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all ................................................................................ 428 407 . 429 408 Returns a string giving the type of file \fIname\fR, which will be one of 430 409 \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR, 431 410 \fBfifo\fR, \fBlink\fR, or \fBsocket\fR. 432 411 .TP 433 412 \fBfile volumes\fR 434 413 . 435 -Returns the absolute paths to the volumes mounted on the system, as a proper 436 -Tcl list. Without any virtual filesystems mounted as root volumes, on UNIX, 437 -the command will always return 438 -.QW "/" , 439 -since all filesystems are locally mounted. On Windows, it will return a list 440 -of the available local drives (e.g. 441 -.QW "a:/ c:/" ). 442 -If any virtual filesystem has mounted additional volumes, they will be in the 443 -returned list. 414 +Returns the absolute paths to the volumes mounted on the system, as a 415 +proper Tcl list. Without any virtual filesystems mounted as root 416 +volumes, on UNIX, the command will always return "/", since all 417 +filesystems are locally mounted. 418 +On Windows, it will return a list of the available local drives 419 +(e.g. {a:/ c:/}). If any virtual filesystem has mounted additional 420 +volumes, they will be in the returned list. 444 421 .TP 445 422 \fBfile writable \fIname\fR 446 423 . 447 424 Returns \fB1\fR if file \fIname\fR is writable by the current user, 448 425 \fB0\fR otherwise. 449 426 .SH "PORTABILITY ISSUES" 450 427 .TP ................................................................................ 483 460 Rename a file and leave a symbolic link pointing from the old location 484 461 to the new place: 485 462 .CS 486 463 set oldName foobar.txt 487 464 set newName foo/bar.txt 488 465 # Make sure that where we're going to move to exists... 489 466 if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} { 490 - \fBfile mkdir\fR [\fBfile dirname\fR $newName] 467 + \fBfile mkdir\fR [\fBfile dirname\fR $newName] 491 468 } 492 469 \fBfile rename\fR $oldName $newName 493 470 \fBfile link\fR -symbolic $oldName $newName 494 471 .CE 495 472 496 473 .SH "SEE ALSO" 497 474 chan(n), close(n), eof(n), fblocked(n), filename(n), flush(n), gets(n), 498 475 open(n), seek(n), tell(n) 499 476 .SH KEYWORDS 500 477 attributes, copy files, delete files, directory, file, move files, name, rename files, stat
Changes to doc/fileevent.n.
1 1 '\" 2 2 '\" Copyright (c) 1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: fileevent.n,v 1.10 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: fileevent.n,v 1.11 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH fileevent n 7.5 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 fileevent \- Execute a script when a channel becomes readable or writable ................................................................................ 26 26 is evaluated whenever the channel becomes readable or writable. File event 27 27 handlers are most commonly used to allow data to be received from another 28 28 process on an event-driven basis, so that the receiver can continue to 29 29 interact with the user while waiting for the data to arrive. If an 30 30 application invokes \fBgets\fR or \fBread\fR on a blocking channel when 31 31 there is no input data available, the process will block; until the input 32 32 data arrives, it will not be able to service other events, so it will 33 -appear to the user to 34 -.QW "freeze up" . 35 -With \fBfileevent\fR, the process can 33 +appear to the user to ``freeze up''. With \fBfileevent\fR, the process can 36 34 tell when data is present and only invoke \fBgets\fR or \fBread\fR when 37 35 they won't block. 38 36 .PP 39 37 The \fIchannelId\fR argument to \fBfileevent\fR refers to an open 40 38 channel such as a Tcl standard channel (\fBstdin\fR, \fBstdout\fR, 41 39 or \fBstderr\fR), the return value from an invocation of \fBopen\fR 42 40 or \fBsocket\fR, or the result of a channel creation command provided ................................................................................ 108 106 if {![eof $chan]} { 109 107 puts [gets $chan] 110 108 } 111 109 } 112 110 113 111 \fBfileevent\fR $chan readable [list GetData $chan] 114 112 .CE 113 + 115 114 .SH CREDITS 116 115 .PP 117 116 \fBfileevent\fR is based on the \fBaddinput\fR command created 118 117 by Mark Diekhans. 118 + 119 119 .SH "SEE ALSO" 120 120 fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3) 121 + 121 122 .SH KEYWORDS 122 123 asynchronous I/O, blocking, channel, event handler, nonblocking, readable, 123 124 script, writable.
Changes to doc/filename.n.
1 1 '\" 2 2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: filename.n,v 1.16 2007/10/25 14:07:32 dkf Exp $ 7 +'\" RCS: @(#) $Id: filename.n,v 1.17 2007/10/26 20:11:52 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH filename n 7.5 Tcl "Tcl Built-In Commands" 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 filename \- File name conventions supported by Tcl commands ................................................................................ 138 138 Tcl attempts to interpret that part of the path or otherwise access the 139 139 file. The behaviour of these paths when not trying to interpret them is 140 140 the same as on Unix. File names that have a tilde without a user name 141 141 will be correctly substituted using the \fB$HOME\fR environment 142 142 variable, just like for Unix. 143 143 .SH "PORTABILITY ISSUES" 144 144 .PP 145 -Not all file systems are case sensitive, so scripts should avoid code that 146 -depends on the case of characters in a file name. In addition, the character 147 -sets allowed on different devices may differ, so scripts should choose file 148 -names that do not contain special characters like: \fB<>:?"/\e|\fR. 149 -.\"" Reset emacs highlighting 150 -The safest approach is to use names consisting of alphanumeric characters 151 -only. Care should be taken with filenames which contain spaces (common on 152 -Windows systems) and filenames where the backslash is the directory separator 153 -(Windows native path names). Also Windows 3.1 only supports file names with a 154 -root of no more than 8 characters and an extension of no more than 3 155 -characters. 145 +Not all file systems are case sensitive, so scripts should avoid code 146 +that depends on the case of characters in a file name. In addition, 147 +the character sets allowed on different devices may differ, so scripts 148 +should choose file names that do not contain special characters like: 149 +\fB<>:?"/\e|\fR. The safest approach is to use names consisting of 150 +alphanumeric characters only. Care should be taken with filenames 151 +which contain spaces (common on Windows systems) and 152 +filenames where the backslash is the directory separator (Windows 153 +native path names). Also Windows 3.1 only supports file 154 +names with a root of no more than 8 characters and an extension of no 155 +more than 3 characters. 156 156 .PP 157 -On Windows platforms there are file and path length restrictions. Complete 158 -paths or filenames longer than about 260 characters will lead to errors in 159 -most file operations. 157 +On Windows platforms there are file and path length restrictions. 158 +Complete paths or filenames longer than about 260 characters will lead 159 +to errors in most file operations. 160 160 .PP 161 -Another Windows peculiarity is that any number of trailing dots 162 -.QW "." 163 -in filenames are totally ignored, so, for example, attempts to create a file 164 -or directory with a name 165 -.QW "foo." 166 -will result in the creation of a file or directory with name 167 -.QW "foo" . 168 -This fact is reflected in the results of 169 -.QW \fBfile normalize\fR . 170 -Furthermore, a file name consisting only of dots 171 -.QW "........." 172 -or dots with trailing characters 173 -.QW ".....abc" 174 -is illegal. 161 +Another Windows peculiarity is that any number of trailing dots '.' in 162 +filenames are totally ignored, so, for example, attempts to create a 163 +file or directory with a name "foo." will result in the creation of a 164 +file/directory with name "foo". This fact is reflected in the 165 +results of 'file normalize'. Furthermore, a file name consisting only 166 +of dots '.........' or dots with trailing characters '.....abc' is 167 +illegal. 175 168 .SH KEYWORDS 176 169 current directory, absolute file name, relative file name, 177 170 volume-relative file name, portability 178 171 .SH "SEE ALSO" 179 172 file(n), glob(n)
Changes to doc/for.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: for.n,v 1.6 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: for.n,v 1.7 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH for n "" Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 -for \- `For' loop 15 +for \- ``For'' loop 16 16 .SH SYNOPSIS 17 17 \fBfor \fIstart test next body\fR 18 18 .BE 19 19 20 20 .SH DESCRIPTION 21 21 .PP 22 22 \fBFor\fR is a looping command, similar in structure to the C
Changes to doc/format.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: format.n,v 1.16 2007/10/25 14:07:32 dkf Exp $ 8 +'\" RCS: @(#) $Id: format.n,v 1.17 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH format n 8.1 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 format \- Format a string in the style of sprintf ................................................................................ 46 46 a set of flags, a minimum field width, a precision, a size modifier, 47 47 and a conversion character. 48 48 Any of these fields may be omitted except for the conversion character. 49 49 The fields that are present must appear in the order given above. 50 50 The paragraphs below discuss each of these fields in turn. 51 51 .PP 52 52 If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in 53 -.QW \fB%2$d\fR , 54 -then the value to convert is not taken from the next sequential argument. 53 +``\fB%2$d\fR'', then the value to convert is not taken from the 54 +next sequential argument. 55 55 Instead, it is taken from the argument indicated by the number, 56 56 where 1 corresponds to the first \fIarg\fR. 57 57 If the conversion specifier requires multiple arguments because 58 58 of \fB*\fR characters in the specifier then 59 59 successive arguments are used, starting with the argument 60 60 given by the number. 61 61 This follows the XPG3 conventions for positional specifiers. ................................................................................ 152 152 Convert integer to signed decimal string (equivalent to \fBd\fR). 153 153 .TP 10 154 154 \fBo\fR 155 155 Convert integer to unsigned octal string. 156 156 .TP 10 157 157 \fBx\fR or \fBX\fR 158 158 Convert integer to unsigned hexadecimal string, using digits 159 -.QW 0123456789abcdef 160 -for \fBx\fR and 161 -.QW 0123456789ABCDEF 162 -for \fBX\fR). 159 +``0123456789abcdef'' for \fBx\fR and ``0123456789ABCDEF'' for \fBX\fR). 163 160 .TP 10 164 161 \fBc\fR 165 162 Convert integer to the Unicode character it represents. 166 163 .TP 10 167 164 \fBs\fR 168 165 No conversion; just insert string. 169 166 .TP 10 ................................................................................ 171 168 Convert number to signed decimal string of 172 169 the form \fIxx.yyy\fR, where the number of \fIy\fR's is determined by 173 170 the precision (default: 6). 174 171 If the precision is 0 then no decimal point is output. 175 172 .TP 10 176 173 \fBe\fR or \fBE\fR 177 174 Convert number to scientific notation in the 178 -form 179 -.QW "\fIx.yyy\fBe\(+-\fIzz\fR" , 180 -where the number of \fIy\fR's is determined by the precision (default: 6). 175 +form \fIx.yyy\fBe\(+-\fIzz\fR, where the number of \fIy\fR's is determined 176 +by the precision (default: 6). 181 177 If the precision is 0 then no decimal point is output. 182 178 If the \fBE\fR form is used then \fBE\fR is 183 179 printed instead of \fBe\fR. 184 180 .TP 10 185 181 \fBg\fR or \fBG\fR 186 182 If the exponent is less than \-4 or greater than or equal to the 187 183 precision, then convert number as for \fB%e\fR or
Changes to doc/glob.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: glob.n,v 1.19 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: glob.n,v 1.20 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH glob n 8.3 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 glob \- Return names of files that match patterns 16 16 .SH SYNOPSIS 17 17 \fBglob \fR?\fIswitches\fR? \fIpattern \fR?\fIpattern ...\fR? 18 18 .BE 19 19 20 20 .SH DESCRIPTION 21 21 .PP 22 -This command performs file name 23 -.QW globbing 24 -in a fashion similar to 22 +This command performs file name ``globbing'' in a fashion similar to 25 23 the csh shell. It returns a list of the files whose names match any 26 24 of the \fIpattern\fR arguments. No particular order is guaranteed 27 25 in the list, so if a sorted list is required the caller should use 28 26 \fBlsort\fR. 29 27 .LP 30 28 If the initial arguments to \fBglob\fR start with \fB\-\fR then 31 29 they are treated as switches. The following switches are ................................................................................ 99 97 The following are equivalent: 100 98 .RS 101 99 .CS 102 100 \fBglob \-type d *\fR 103 101 \fBglob */\fR 104 102 .CE 105 103 .RE 106 -except that the first case doesn't return the trailing 107 -.QW / 108 -and is more platform independent. 104 +except that the first case doesn't return the trailing ``/'' and 105 +is more platform independent. 109 106 .RE 110 107 .TP 111 108 \fB\-\|\-\fR 112 109 Marks the end of switches. The argument following this one will 113 110 be treated as a \fIpattern\fR even if it starts with a \fB\-\fR. 114 111 .PP 115 112 The \fIpattern\fR arguments may contain any of the following ................................................................................ 128 125 .TP 10 129 126 \fB\e\fIx\fR 130 127 Matches the character \fIx\fR. 131 128 .TP 10 132 129 \fB{\fIa\fB,\fIb\fB,\fI...\fR} 133 130 Matches any of the strings \fIa\fR, \fIb\fR, etc. 134 131 .LP 135 -On Unix, as with csh, a 136 -.QW . 137 -at the beginning of a file's name or just after a 138 -.QW / 139 -must be matched explicitly or with a {} construct, unless the 140 -.QW "-types hidden" 141 -flag is given (since 142 -.QW . 143 -at the beginning 132 +On Unix, as with csh, a ``.'' at the beginning of a file's name or just 133 +after a ``/'' must be matched explicitly or with a {} construct, 134 +unless the ``-types hidden'' flag is given (since ``.'' at the beginning 144 135 of a file's name indicates that it is hidden). On other platforms, 145 -files beginning with a 146 -.QW . 147 -are handled no differently to any others, 148 -except the special directories 149 -.QW . 150 -and 151 -.QW .. 152 -which must be matched explicitly (this is to avoid a recursive pattern like 153 -.QW "glob -join * * * *" 154 -from recursing up the directory hierarchy as well as down). In addition, all 155 -.QW / 156 -characters must be matched explicitly. 136 +files beginning with a ``.'' are handled no differently to any others, 137 +except the special directories ``.'' and ``..'' which must be matched 138 +explicitly (this is to avoid a recursive pattern like ``glob -join * * 139 +* *'' from recursing up the directory hierarchy as well as down). 140 +In addition, all ``/'' characters must be matched explicitly. 157 141 .LP 158 -If the first character in a \fIpattern\fR is 159 -.QW ~ 160 -then it refers to the home directory for the user whose name follows the 161 -.QW ~ . 162 -If the 163 -.QW ~ 164 -is followed immediately by 165 -.QW / 166 -then the value of the HOME environment variable is used. 142 +If the first character in a \fIpattern\fR is ``~'' then it refers 143 +to the home directory for the user whose name follows the ``~''. 144 +If the ``~'' is followed immediately by ``/'' then the value of 145 +the HOME environment variable is used. 167 146 .LP 168 147 The \fBglob\fR command differs from csh globbing in two ways. 169 148 First, it does not sort its result list (use the \fBlsort\fR 170 149 command if you want the list sorted). 171 150 Second, \fBglob\fR only returns the names of files that actually 172 151 exist; in csh no check for existence is made unless a pattern 173 152 contains a ?, *, or [] construct. 174 153 .LP 175 154 When the \fBglob\fR command returns relative paths whose filenames 176 -start with a tilde 177 -.QW ~ 178 -(for example through \fBglob *\fR or 155 +start with a tilde ``~'' (for example through \fBglob *\fR or 179 156 \fBglob -tails\fR, the returned list will not quote the tilde with 180 -.QW ./ . 181 -This means care must be taken if those names are later to 157 +``./''. This means care must be taken if those names are later to 182 158 be used with \fBfile join\fR, to avoid them being interpreted as 183 159 absolute paths pointing to a given user's home directory. 184 160 .SH "PORTABILITY ISSUES" 185 -.TP 161 +.PP 186 162 \fBWindows\fR 187 163 . 188 164 For Windows UNC names, the servername and sharename components of the path 189 165 may not contain ?, *, or [] constructs. On Windows NT, if \fIpattern\fR is 190 -of the form 191 -.QW \fB~\fIusername\[email protected]\fIdomain\fR 192 -it refers to the home 166 +of the form ``\fB~\fIusername\[email protected]\fIdomain\fR'' it refers to the home 193 167 directory of the user whose account information resides on the specified NT 194 168 domain server. Otherwise, user account information is obtained from 195 169 the local computer. On Windows 95 and 98, \fBglob\fR accepts patterns 196 -like 197 -.QW .../ 198 -and 199 -.QW ..../ 200 -for successively higher up parent directories. 201 -.RS 202 -.PP 170 +like ``.../'' and ``..../'' for successively higher up parent directories. 171 + 172 +. 203 173 Since the backslash character has a special meaning to the glob 204 174 command, glob patterns containing Windows style path separators need 205 175 special care. The pattern \fIC:\e\efoo\e\e*\fR is interpreted as 206 176 \fIC:\efoo\e*\fR where \fI\ef\fR will match the single character \fIf\fR 207 177 and \fI\e*\fR will match the single character \fI*\fR and will not be 208 178 interpreted as a wildcard character. One solution to this problem is 209 179 to use the Unix style forward slash as a path separator. Windows style ................................................................................ 222 192 .CE 223 193 .PP 224 194 Find all subdirectories of the current directory: 225 195 .CS 226 196 \fBglob\fR \-type d * 227 197 .CE 228 198 .PP 229 -Find all files whose name contains an 230 -.QW a , 231 -a 232 -.QW b 233 -or the sequence 234 -.QW cde : 199 +Find all files whose name contains an "a", a "b" or the sequence "cde": 235 200 .CS 236 201 \fBglob\fR \-type f *{a,b,cde}* 237 202 .CE 238 203 239 204 .SH "SEE ALSO" 240 205 file(n) 241 206 242 207 .SH KEYWORDS 243 208 exist, file, glob, pattern
Changes to doc/history.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: history.n,v 1.5 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: history.n,v 1.6 2007/10/26 20:11:52 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH history n "" Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 history \- Manipulate the history list ................................................................................ 17 17 \fBhistory \fR?\fIoption\fR? ?\fIarg arg ...\fR? 18 18 .BE 19 19 20 20 .SH DESCRIPTION 21 21 .PP 22 22 The \fBhistory\fR command performs one of several operations related to 23 23 recently-executed commands recorded in a history list. Each of 24 -these recorded commands is referred to as an 25 -.QW event . 26 -When specifying an event to the \fBhistory\fR command, the following 24 +these recorded commands is referred to as an ``event''. When 25 +specifying an event to the \fBhistory\fR command, the following 27 26 forms may be used: 28 27 .IP [1] 29 28 A number: if positive, it refers to the event with 30 29 that number (all events are numbered starting at 1). If the number 31 30 is negative, it selects an event relative to the current event 32 31 (\fB\-1\fR refers to the previous event, \fB\-2\fR to the one before that, and 33 32 so on). Event \fB0\fR refers to the current event. ................................................................................ 89 88 .SH "HISTORY REVISION" 90 89 .PP 91 90 Pre-8.0 Tcl had a complex history revision mechanism. 92 91 The current mechanism is more limited, and the old 93 92 history operations \fBsubstitute\fR and \fBwords\fR have been removed. 94 93 (As a consolation, the \fBclear\fR operation was added.) 95 94 .PP 96 -The history option \fBredo\fR results in much simpler 97 -.QW "history revision" . 95 +The history option \fBredo\fR results in much simpler ``history revision''. 98 96 When this option is invoked then the most recent event 99 97 is modified to eliminate the history command and replace it with 100 98 the result of the history command. 101 99 If you want to redo an event without modifying history, then use 102 100 the \fBevent\fR operation to retrieve some event, 103 101 and the \fBadd\fR operation to add it to history and execute it. 104 102 105 103 .SH KEYWORDS 106 104 event, history, record
Changes to doc/http.n.
2 2 '\" Copyright (c) 1995-1997 Sun Microsystems, Inc. 3 3 '\" Copyright (c) 1998-2000 by Ajuba Solutions. 4 4 '\" Copyright (c) 2004 ActiveState Corporation. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: http.n,v 1.26 2007/10/24 14:29:38 dkf Exp $ 9 +'\" RCS: @(#) $Id: http.n,v 1.27 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH "http" n 2.5 http "Tcl Bundled Packages" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 http \- Client-side implementation of the HTTP/1.0 protocol ................................................................................ 85 85 flags and values that define the configuration: 86 86 .RS 87 87 .TP 88 88 \fB\-accept\fR \fImimetypes\fR 89 89 The Accept header of the request. The default is */*, which means that 90 90 all types of documents are accepted. Otherwise you can supply a 91 91 comma-separated list of mime type patterns that you are 92 -willing to receive. For example, 93 -.QW "image/gif, image/jpeg, text/*" . 92 +willing to receive. For example, "image/gif, image/jpeg, text/*". 94 93 .TP 95 94 \fB\-proxyhost\fR \fIhostname\fR 96 95 The name of the proxy host, if any. If this value is the 97 96 empty string, the URL host is contacted directly. 98 97 .TP 99 98 \fB\-proxyport\fR \fInumber\fR 100 99 The proxy port number. ................................................................................ 117 116 returned by specifying the empty string (\fB{}\fR), although 118 117 \fIiso8859-1\fR is recommended to restore similar behavior but without the 119 118 \fB::http::formatQuery\fR throwing an error processing non-latin-1 120 119 characters. 121 120 .TP 122 121 \fB\-useragent\fR \fIstring\fR 123 122 The value of the User-Agent header in the HTTP request. The default 124 -is 125 -.QW "\fBTcl http client package 2.5\fR" . 123 +is \fB"Tcl http client package 2.4."\fR 126 124 .RE 127 125 .TP 128 126 \fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR? 129 127 The \fB::http::geturl\fR command is the main procedure in the package. 130 128 The \fB\-query\fR option causes a POST operation and 131 129 the \fB\-validate\fR option causes a HEAD operation; 132 130 otherwise, a GET operation is performed. The \fB::http::geturl\fR command ................................................................................ 338 336 set token [::http::geturl https://my.secure.site/] 339 337 .CE 340 338 .RE 341 339 .TP 342 340 \fB::http::unregister\fR \fIproto\fR 343 341 This procedure unregisters a protocol handler that was previously 344 342 registered via \fB::http::register\fR. 343 + 345 344 .SH "ERRORS" 346 345 The \fB::http::geturl\fR procedure will raise errors in the following cases: 347 346 invalid command line options, 348 347 an invalid URL, 349 348 a URL on a non-existent host, 350 349 or a URL at a bad port on an existing host. 351 350 These errors mean that it ................................................................................ 382 381 These are described below. 383 382 .TP 384 383 ok 385 384 If the HTTP transaction completes entirely, then status will be \fBok\fR. 386 385 However, you should still check the \fB::http::code\fR value to get 387 386 the HTTP status. The \fB::http::ncode\fR procedure provides just 388 387 the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fR 389 -procedure returns a value like 390 -.QW "HTTP 404 File not found" . 388 +procedure returns a value like "HTTP 404 File not found". 391 389 .TP 392 390 eof 393 391 If the server closes the socket without replying, then no error 394 392 is raised, but the status of the transaction will be \fBeof\fR. 395 393 .TP 396 394 error 397 395 The error message will also be stored in the \fBerror\fR status ................................................................................ 402 400 responds and closes the socket. 403 401 The error message is saved in the \fBposterror\fR status array 404 402 element and then \fB::http::geturl\fR attempts to complete the 405 403 transaction. 406 404 If it can read the server's response 407 405 it will end up with an \fBok\fR status, otherwise it will have 408 406 an \fBeof\fR status. 407 + 409 408 .SH "STATE ARRAY" 410 409 The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to 411 410 get to the state of the HTTP transaction in the form of a Tcl array. 412 411 Use this construct to create an easy-to-use array variable: 413 412 .CS 414 413 upvar #0 $token state 415 414 .CE ................................................................................ 531 530 return $token 532 531 } 533 532 proc httpCopyProgress {args} { 534 533 puts -nonewline stderr . 535 534 flush stderr 536 535 } 537 536 .CE 537 + 538 538 .SH "SEE ALSO" 539 539 safe(n), socket(n), safesock(n) 540 + 540 541 .SH KEYWORDS 541 542 security policy, socket
Changes to doc/if.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: if.n,v 1.6 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: if.n,v 1.7 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH if n "" Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 if \- Execute scripts conditionally ................................................................................ 28 28 if it is true then \fIbody1\fR is executed by passing it to the 29 29 Tcl interpreter. 30 30 Otherwise \fIexpr2\fR is evaluated as an expression and if it is true 31 31 then \fBbody2\fR is executed, and so on. 32 32 If none of the expressions evaluates to true then \fIbodyN\fR is 33 33 executed. 34 34 The \fBthen\fR and \fBelse\fR arguments are optional 35 -.QW noise words 36 -to make the command easier to read. 35 +``noise words'' to make the command easier to read. 37 36 There may be any number of \fBelseif\fR clauses, including zero. 38 37 \fIBodyN\fR may also be omitted as long as \fBelse\fR is omitted too. 39 38 The return value from the command is the result of the body script 40 39 that was executed, or an empty string 41 40 if none of the expressions was non-zero and there was no \fIbodyN\fR. 42 41 .SH EXAMPLES 43 42 A simple conditional:
Changes to doc/info.n.
3 3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies 5 5 '\" Copyright (c) 1998-2000 Ajuba Solutions 6 6 '\" 7 7 '\" See the file "license.terms" for information on usage and redistribution 8 8 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 9 9 '\" 10 -'\" RCS: @(#) $Id: info.n,v 1.20 2007/10/25 14:07:32 dkf Exp $ 10 +'\" RCS: @(#) $Id: info.n,v 1.21 2007/10/26 20:11:53 dgp Exp $ 11 11 '\" 12 12 .so man.macros 13 13 .TH info n 8.4 Tcl "Tcl Built-In Commands" 14 14 .BS 15 15 '\" Note: do not modify the .SH NAME line immediately below! 16 16 .SH NAME 17 17 info \- Return information about the state of the Tcl interpreter ................................................................................ 19 19 \fBinfo \fIoption \fR?\fIarg arg ...\fR? 20 20 .BE 21 21 22 22 .SH DESCRIPTION 23 23 .PP 24 24 This command provides information about various internals of the Tcl 25 25 interpreter. 26 -The legal \fIoption\fRs (which may be abbreviated) are: 26 +The legal \fIoption\fR's (which may be abbreviated) are: 27 27 .TP 28 28 \fBinfo args \fIprocname\fR 29 29 Returns a list containing the names of the arguments to procedure 30 30 \fIprocname\fR, in order. \fIProcname\fR must be the name of a 31 31 Tcl command procedure. 32 32 .TP 33 33 \fBinfo body \fIprocname\fR ................................................................................ 94 94 If \fInumber\fR is positive (> 0) then it selects a particular stack 95 95 level (1 refers to the top-most active command, i.e., \fBinfo frame\fR 96 96 itself, 2 to the command it was called from, and so on); otherwise it 97 97 gives a level relative to the current command (0 refers to the current 98 98 command, i.e., \fBinfo frame\fR itself, -1 to its caller, and so on). 99 99 .sp 100 100 This is similar to how \fBinfo level\fR works, except that this 101 -subcommand reports all frames, like \fBsource\fRd scripts, 102 -\fBeval\fRs, \fBuplevel\fRs, etc. 101 +subcommand reports all frames, like \fBsource\fR'd scripts, 102 +\fBeval\fR's, \fBuplevel\fR's, etc. 103 103 .sp 104 -Note that for nested commands, like 105 -.QW "foo [[bar [[x]]]]" 106 -only 107 -.QW "x" 108 -will be seen by an \fBinfo frame\fR invoked within 109 -.QW "x" . 110 -This is the same as for \fBinfo level\fR and error stack traces. 104 +Note that for nested commands, like "foo [[bar [[x]]]]" only "x" will 105 +be seen by an \fBinfo frame\fR invoked within "x". This is the same as 106 +for \fBinfo level\fR and error stack traces. 111 107 .sp 112 108 The result dictionary may contain the keys listed below, with the 113 109 specified meanings for their values: 114 110 .RS 115 111 .TP 116 112 \fItype\fR 117 113 This entry is always present and describes the nature of the location ................................................................................ 313 309 using a sequence of namespace names separated by double colons (\fB::\fR), 314 310 and may have pattern matching special characters 315 311 at the end to specify a set of variables in that namespace. 316 312 If \fIpattern\fR is a qualified name, 317 313 the resulting list of variable names 318 314 has each matching namespace variable qualified with the name 319 315 of its namespace. 320 -Note that a currently-visible variable may not yet 321 -.QW "exist" 322 -if it has not 316 +Note that a currently-visible variable may not yet "exist" if it has not 323 317 been set (e.g. a variable declared but not set by \fBvariable\fR). 324 318 .SH EXAMPLE 325 319 This command prints out a procedure suitable for saving in a Tcl 326 320 script: 327 321 .PP 328 322 .CS 329 323 proc printProc {procName} {
Changes to doc/interp.n.
1 1 '\" 2 2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. 3 3 '\" Copyright (c) 2004 Donal K. Fellows 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: interp.n,v 1.30 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: interp.n,v 1.31 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH interp n 7.6 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 interp \- Create and manipulate Tcl interpreters ................................................................................ 103 103 This command creates an alias between one slave and another (see the 104 104 \fBalias\fR slave command below for creating aliases between a slave 105 105 and its master). In this command, either of the slave interpreters 106 106 may be anywhere in the hierarchy of interpreters under the interpreter 107 107 invoking the command. 108 108 \fISrcPath\fR and \fIsrcCmd\fR identify the source of the alias. 109 109 \fISrcPath\fR is a Tcl list whose elements select a particular 110 -interpreter. For example, 111 -.QW "\fBa b\fR" 112 -identifies an interpreter 110 +interpreter. For example, ``\fBa b\fR'' identifies an interpreter 113 111 \fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave 114 112 of the invoking interpreter. An empty list specifies the interpreter 115 113 invoking the command. \fIsrcCmd\fR gives the name of a new 116 114 command, which will be created in the source interpreter. 117 115 \fITargetPath\fR and \fItargetCmd\fR specify a target interpreter 118 116 and command, and the \fIarg\fR arguments, if any, specify additional 119 117 arguments to \fItargetCmd\fR which are prepended to any arguments specified ................................................................................ 566 564 When the source for an alias is invoked in the slave interpreter, the 567 565 usual Tcl substitutions are performed when parsing that command. 568 566 These substitutions are carried out in the source interpreter just 569 567 as they would be for any other command invoked in that interpreter. 570 568 The command procedure for the source command takes its arguments 571 569 and merges them with the \fItargetCmd\fR and \fIarg\fRs for the 572 570 alias to create a new array of arguments. If the words 573 -of \fIsrcCmd\fR were 574 -.QW "\fIsrcCmd arg1 arg2 ... argN\fR" , 571 +of \fIsrcCmd\fR were ``\fIsrcCmd arg1 arg2 ... argN\fR'', 575 572 the new set of words will be 576 -.QW "\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR" , 573 +``\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR'', 577 574 where \fItargetCmd\fR and \fIarg\fRs are the values supplied when the 578 575 alias was created. \fITargetCmd\fR is then used to locate a command 579 576 procedure in the target interpreter, and that command procedure 580 577 is invoked with the new set of arguments. An error occurs if 581 578 there is no command named \fItargetCmd\fR in the target interpreter. 582 579 No additional substitutions are performed on the words: the 583 580 target command procedure is invoked directly, without
Changes to doc/join.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: join.n,v 1.6 2007/10/25 09:25:27 dkf Exp $ 8 +'\" RCS: @(#) $Id: join.n,v 1.7 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH join n "" Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 join \- Create a string by joining together list elements 16 16 .SH SYNOPSIS 17 17 \fBjoin \fIlist \fR?\fIjoinString\fR? 18 18 .BE 19 + 19 20 .SH DESCRIPTION 20 21 .PP 21 22 The \fIlist\fR argument must be a valid Tcl list. 22 23 This command returns the string 23 24 formed by joining all of the elements of \fIlist\fR together with 24 25 \fIjoinString\fR separating each adjacent pair of elements. 25 26 The \fIjoinString\fR argument defaults to a space character. 26 27 .SH EXAMPLES 27 28 Making a comma-separated list: 28 29 .CS 29 -.ta 2i 30 30 set data {1 2 3 4 5} 31 31 \fBjoin\fR $data ", " 32 - \fB\(->\fI 1, 2, 3, 4, 5\fR 32 + \fB=> 1, 2, 3, 4, 5\fR 33 33 .CE 34 34 .PP 35 35 Using \fBjoin\fR to flatten a list by a single level: 36 36 .CS 37 -.ta 2i 38 37 set data {1 {2 3} 4 {5 {6 7} 8}} 39 38 \fBjoin\fR $data 40 - \fB\(->\fI 1 2 3 4 5 {6 7} 8\fR 39 + \fB=> 1 2 3 4 5 {6 7} 8\fR 41 40 .CE 41 + 42 42 .SH "SEE ALSO" 43 43 list(n), lappend(n), split(n) 44 + 44 45 .SH KEYWORDS 45 46 element, join, list, separator
Changes to doc/lappend.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: lappend.n,v 1.12 2007/10/24 14:29:38 dkf Exp $ 9 +'\" RCS: @(#) $Id: lappend.n,v 1.13 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH lappend n "" Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 lappend \- Append list elements onto a variable ................................................................................ 24 24 and appends each of the \fIvalue\fR arguments to that list as a separate 25 25 element, with spaces between elements. 26 26 If \fIvarName\fR doesn't exist, it is created as a list with elements 27 27 given by the \fIvalue\fR arguments. 28 28 \fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs 29 29 are appended as list elements rather than raw text. 30 30 This command provides a relatively efficient way to build up 31 -large lists. For example, 32 -.QW "\fBlappend a $b\fR" 33 -is much more efficient than 34 -.QW "\fBset a [concat $a [list $b]]\fR" , 35 -especially when \fB$a\fR is long. 31 +large lists. For example, ``\fBlappend a $b\fR'' is much 32 +more efficient than ``\fBset a [concat $a [list $b]]\fR'' when 33 +\fB$a\fR is long. 36 34 .SH EXAMPLE 37 35 Using \fBlappend\fR to build up a list of numbers. 38 36 .CS 39 37 % set var 1 40 38 1 41 39 % \fBlappend\fR var 2 42 40 1 2
Changes to doc/lassign.n.
1 1 '\" 2 2 '\" Copyright (c) 1992-1999 Karl Lehenbauer & Mark Diekhans 3 3 '\" Copyright (c) 2004 Donal K. Fellows 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: lassign.n,v 1.2 2007/10/25 09:31:52 dkf Exp $ 8 +'\" RCS: @(#) $Id: lassign.n,v 1.3 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH lassign n 8.5 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 lassign \- Assign list elements to variables 16 16 .SH SYNOPSIS 17 17 \fBlassign \fIlist varName \fR?\fIvarName ...\fR? 18 18 .BE 19 + 19 20 .SH DESCRIPTION 20 21 .PP 21 22 This command treats the value \fIlist\fR as a list and assigns 22 23 successive elements from that list to the variables given by the 23 24 \fIvarName\fR arguments in order. If there are more variable names 24 25 than list elements, the remaining variables are set to the empty 25 26 string. If there are more list elements than variables, a list of 26 27 unassigned elements is returned. 27 28 .SH EXAMPLES 28 29 An illustration of how multiple assignment works, and what happens 29 30 when there are either too few or too many elements. 30 31 .CS 31 -.ta 2.5i 32 -lassign {a b c} x y z \fB\(->\fI Empty return\fR 33 -puts $x \fB\(->\fI Prints "a"\fR 34 -puts $y \fB\(->\fI Prints "b"\fR 35 -puts $z \fB\(->\fI Prints "c"\fR 32 +lassign {a b c} x y z ;# Empty return 33 +puts $x ;# Prints "a" 34 +puts $y ;# Prints "b" 35 +puts $z ;# Prints "c" 36 36 37 -lassign {d e} x y z \fB\(->\fI Empty return\fR 38 -puts $x \fB\(->\fI Prints "d"\fR 39 -puts $y \fB\(->\fI Prints "e"\fR 40 -puts $z \fB\(->\fI Prints ""\fR 37 +lassign {d e} x y z ;# Empty return 38 +puts $x ;# Prints "d" 39 +puts $y ;# Prints "e" 40 +puts $z ;# Prints "" 41 41 42 -lassign {f g h i} x y \fB\(->\fI Returns "h i"\fR 43 -puts $x \fB\(->\fI Prints "f"\fR 44 -puts $y \fB\(->\fI Prints "g"\fR 42 +lassign {f g h i} x y ;# Returns "h i" 43 +puts $x ;# Prints "f" 44 +puts $y ;# Prints "g" 45 45 .CE 46 -.PP 47 46 The \fBlassign\fR command has other uses. It can be used to create 48 -the analogue of the 49 -.QW shift 50 -command in many shell languages like this: 47 +the analogue of the "shift" command in many shell languages like this: 51 48 .CS 52 49 set ::argv [lassign $::argv argumentToReadOff] 53 50 .CE 54 51 .SH "SEE ALSO" 55 52 lindex(n), list(n), lset(n), set(n) 53 + 56 54 .SH KEYWORDS 57 55 assign, element, list, multiple, set, variable
Changes to doc/library.n.
1 1 '\" 2 2 '\" Copyright (c) 1991-1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: library.n,v 1.19 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: library.n,v 1.20 2007/10/26 20:11:53 dgp Exp $ 9 9 .so man.macros 10 10 .TH library n "8.0" Tcl "Tcl Built-In Commands" 11 11 .BS 12 12 .SH NAME 13 13 auto_execok, auto_import, auto_load, auto_mkindex, auto_mkindex_old, auto_qualify, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore \- standard library of Tcl procedures 14 14 .SH SYNOPSIS 15 15 .nf ................................................................................ 50 50 \fBsource [file join [info library] init.tcl]\fR 51 51 .CE 52 52 If the library procedure \fBTcl_Init\fR is invoked from an application's 53 53 \fBTcl_AppInit\fR procedure, this happens automatically. 54 54 The code in \fBinit.tcl\fR will define the \fBunknown\fR procedure 55 55 and arrange for the other procedures to be loaded on-demand using 56 56 the auto-load mechanism defined below. 57 + 57 58 .SH "COMMAND PROCEDURES" 58 59 .PP 59 60 The following procedures are provided in the Tcl library: 60 61 .TP 61 62 \fBauto_execok \fIcmd\fR 62 63 Determines whether there is an executable file or shell builtin 63 64 by the name \fIcmd\fR. If so, it returns a list of arguments to be ................................................................................ 132 133 \fBAuto_mkindex_old\fR parses the Tcl scripts in a relatively 133 134 unsophisticated way: if any line contains the word \fBproc\fR 134 135 as its first characters then it is assumed to be a procedure 135 136 definition and the next word of the line is taken as the 136 137 procedure's name. 137 138 Procedure definitions that don't appear in this way (e.g. they 138 139 have spaces before the \fBproc\fR) will not be indexed. If your 139 -script contains 140 -.QW dangerous 141 -code, such as global initialization 140 +script contains "dangerous" code, such as global initialization 142 141 code or procedure names with special characters like \fB$\fR, 143 142 \fB*\fR, \fB[\fR or \fB]\fR, you are safer using auto_mkindex_old. 144 143 .RE 145 144 .TP 146 145 \fBauto_reset\fR 147 146 Destroys all the information cached by \fBauto_execok\fR and 148 147 \fBauto_load\fR. This information will be re-read from disk the next ................................................................................ 171 170 .TP 172 171 \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR 173 172 This is a standard search procedure for use by extensions during 174 173 their initialization. They call this procedure to look for their 175 174 script library in several standard directories. 176 175 The last component of the name of the library directory is 177 176 normally \fIbasenameversion\fR 178 -(e.g., tk8.0), but it might be 179 -.QW library 180 -when in the build hierarchies. 177 +(e.g., tk8.0), but it might be "library" when in the build hierarchies. 181 178 The \fIinitScript\fR file will be sourced into the interpreter 182 179 once it is found. The directory in which this file is found is 183 180 stored into the global variable \fIvarName\fR. 184 181 If this variable is already defined (e.g., by C code during 185 182 application initialization) then no searching is done. 186 183 Otherwise the search looks in these directories: 187 184 the directory named by the environment variable \fIenVarName\fR; ................................................................................ 229 226 .TP 230 227 \fBtcl_wordBreakBefore \fIstr start\fR 231 228 Returns the index of the first word boundary before the starting index 232 229 \fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more 233 230 boundaries before the starting point in the given string. The index 234 231 returned refers to the second character of the pair that comprises a 235 232 boundary. 233 + 236 234 .SH "VARIABLES" 237 235 .PP 238 236 The following global variables are defined or used by the procedures in 239 237 the Tcl library: 240 238 .TP 241 239 \fBauto_execs\fR 242 240 Used by \fBauto_execok\fR to record information about whether ................................................................................ 269 267 assigned to the \fBtcl_library\fR variable and therefore returned by 270 268 the command \fBinfo library\fR). If this variable isn't set then 271 269 a default value is used. 272 270 .TP 273 271 \fBenv(TCLLIBPATH)\fR 274 272 If set, then it must contain a valid Tcl list giving directories to 275 273 search during auto-load operations. Directories must be specified in 276 -Tcl format, using 277 -.QW / 278 -as the path separator, regardless of platform. 274 +Tcl format, using "/" as the path separator, regardless of platform. 279 275 This variable is only used when initializing the \fBauto_path\fR variable. 280 276 .TP 281 277 \fBtcl_nonwordchars\fR 282 278 This variable contains a regular expression that is used by routines 283 279 like \fBtcl_endOfWord\fR to identify whether a character is part of a 284 280 word or not. If the pattern matches a character, the character is 285 281 considered to be a non-word character. On Windows platforms, spaces, ................................................................................ 290 286 \fBtcl_wordchars\fR 291 287 This variable contains a regular expression that is used by routines 292 288 like \fBtcl_endOfWord\fR to identify whether a character is part of a 293 289 word or not. If the pattern matches a character, the character is 294 290 considered to be a word character. On Windows platforms, words are 295 291 comprised of any character that is not a space, tab, or newline. Under 296 292 Unix, words are comprised of numbers, letters or underscores. 293 + 297 294 .SH "SEE ALSO" 298 295 info(n), re_syntax(n) 296 + 299 297 .SH KEYWORDS 300 298 auto-exec, auto-load, library, unknown, word, whitespace
Changes to doc/lindex.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2001 by Kevin B. Kenny. All rights reserved. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: lindex.n,v 1.13 2007/10/25 09:25:27 dkf Exp $ 9 +'\" RCS: @(#) $Id: lindex.n,v 1.14 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH lindex n 8.4 Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 lindex \- Retrieve an element from a list ................................................................................ 63 63 lindex $a {1 2 3} 64 64 .CE 65 65 is synonymous with 66 66 .CS 67 67 lindex [lindex [lindex $a 1] 2] 3 68 68 .CE 69 69 .SH EXAMPLES 70 -.PP 71 -Demonstrating how the index list system works. 72 70 .CS 73 -.ta 5i 74 -\fBlindex\fR {a b c} \fB\(->\fI a b c\fR 75 -\fBlindex\fR {a b c} {} \fB\(->\fI a b c\fR 76 -\fBlindex\fR {a b c} 0 \fB\(->\fI a\fR 77 -\fBlindex\fR {a b c} 2 \fB\(->\fI c\fR 78 -\fBlindex\fR {a b c} end \fB\(->\fI c\fR 79 -\fBlindex\fR {a b c} end-1 \fB\(->\fI b\fR 80 -\fBlindex\fR {{a b c} {d e f} {g h i}} 2 1 \fB\(->\fI h\fR 81 -\fBlindex\fR {{a b c} {d e f} {g h i}} {2 1} \fB\(->\fI h\fR 82 -\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0 \fB\(->\fI g\fR 83 -\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0} \fB\(->\fI g\fR 71 +\fBlindex\fR {a b c} \fI=> a b c\fR 72 +\fBlindex\fR {a b c} {} \fI=> a b c\fR 73 +\fBlindex\fR {a b c} 0 \fI=> a\fR 74 +\fBlindex\fR {a b c} 2 \fI=> c\fR 75 +\fBlindex\fR {a b c} end \fI=> c\fR 76 +\fBlindex\fR {a b c} end-1 \fI=> b\fR 77 +\fBlindex\fR {{a b c} {d e f} {g h i}} 2 1 \fI=> h\fR 78 +\fBlindex\fR {{a b c} {d e f} {g h i}} {2 1} \fI=> h\fR 79 +\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0 \fI=> g\fR 80 +\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0} \fI=> g\fR 84 81 .CE 85 82 .SH "SEE ALSO" 86 83 list(n), lappend(n), linsert(n), llength(n), lsearch(n), 87 84 lset(n), lsort(n), lrange(n), lreplace(n), 88 85 .VS 8.5 89 86 string(n) 90 87 .VE 88 + 91 89 .SH KEYWORDS 92 90 element, index, list
Changes to doc/llength.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: llength.n,v 1.11 2007/10/24 14:29:38 dkf Exp $ 9 +'\" RCS: @(#) $Id: llength.n,v 1.12 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH llength n "" Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 llength \- Count the number of elements in a list 17 17 .SH SYNOPSIS 18 18 \fBllength \fIlist\fR 19 19 .BE 20 + 20 21 .SH DESCRIPTION 21 22 .PP 22 23 Treats \fIlist\fR as a list and returns a decimal string giving 23 24 the number of elements in it. 25 + 24 26 .SH EXAMPLES 25 27 The result is the number of elements: 26 28 .CS 27 29 % \fBllength\fR {a b c d e} 28 30 5 29 31 % \fBllength\fR {a b c} 30 32 3 ................................................................................ 42 44 .CE 43 45 .PP 44 46 An empty list is not necessarily an empty string: 45 47 .CS 46 48 % set var { }; puts "[string length $var],[\fBllength\fR $var]" 47 49 1,0 48 50 .CE 51 + 49 52 .SH "SEE ALSO" 50 53 list(n), lappend(n), lindex(n), linsert(n), lsearch(n), 51 54 lset(n), lsort(n), lrange(n), lreplace(n) 55 + 52 56 .SH KEYWORDS 53 57 element, list, length
Changes to doc/load.n.
1 1 '\" 2 2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: load.n,v 1.18 2007/10/24 14:29:38 dkf Exp $ 7 +'\" RCS: @(#) $Id: load.n,v 1.19 2007/10/26 20:11:53 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH load n 7.5 Tcl "Tcl Built-In Commands" 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 load \- Load machine code and initialize new commands ................................................................................ 106 106 package by that name, and uses it if it is found. If several 107 107 different files have been \fBload\fRed with different versions of 108 108 the package, Tcl picks the file that was loaded first. 109 109 .SH "PORTABILITY ISSUES" 110 110 .TP 111 111 \fBWindows\fR\0\0\0\0\0 112 112 . 113 -When a load fails with a 114 -.QW "library not found" 115 -error, it is also possible that a dependent library was not found. To 116 -see the dependent libraries, type 117 -.QW "dumpbin -imports <dllname>" 118 -in a DOS console to see what the library must import. 119 -When loading a DLL in the current directory, Windows will ignore 120 -.QW ./ 121 -as a path specifier and use a search heuristic to find the DLL instead. 113 +When a load fails with "library not found" error, it is also possible 114 +that a dependent library was not found. To see the dependent libraries, 115 +type ``dumpbin -imports <dllname>'' in a DOS console to see what the 116 +library must import. 117 +When loading a DLL in the current directory, Windows will ignore ``./'' as 118 +a path specifier and use a search heuristic to find the DLL instead. 122 119 To avoid this, load the DLL with: 123 120 .CS 124 121 \fBload\fR [file join [pwd] mylib.DLL] 125 122 .CE 126 123 .SH BUGS 127 124 .PP 128 125 If the same file is \fBload\fRed by different \fIfileName\fRs, it will
Changes to doc/lrange.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: lrange.n,v 1.13 2007/10/24 14:29:38 dkf Exp $ 9 +'\" RCS: @(#) $Id: lrange.n,v 1.14 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH lrange n 7.4 Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 lrange \- Return one or more adjacent elements from a list ................................................................................ 30 30 end of the list. 31 31 .VE 32 32 If \fIfirst\fR is less than zero, it is treated as if it were zero. 33 33 If \fIlast\fR is greater than or equal to the number of elements 34 34 in the list, then it is treated as if it were \fBend\fR. 35 35 If \fIfirst\fR is greater than \fIlast\fR then an empty string 36 36 is returned. 37 -Note: 38 -.QW "\fBlrange \fIlist first first\fR" 39 -does not always produce the same result as 40 -.QW "\fBlindex \fIlist first\fR" 41 -(although it often does 37 +Note: ``\fBlrange \fIlist first first\fR'' does not always produce the 38 +same result as ``\fBlindex \fIlist first\fR'' (although it often does 42 39 for simple fields that aren't enclosed in braces); it does, however, 43 -produce exactly the same results as 44 -.QW "\fBlist [lindex \fIlist first\fB]\fR" . 40 +produce exactly the same results as ``\fBlist [lindex \fIlist first\fB]\fR'' 45 41 .SH EXAMPLES 46 42 Selecting the first two elements: 47 43 .CS 48 44 % \fBlrange\fR {a b c d e} 0 1 49 45 a b 50 46 .CE 51 47 .PP
Changes to doc/lrepeat.n.
1 1 '\" 2 2 '\" Copyright (c) 2003 by Simon Geard. All rights reserved. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: lrepeat.n,v 1.3 2007/10/25 09:25:27 dkf Exp $ 7 +'\" RCS: @(#) $Id: lrepeat.n,v 1.4 2007/10/26 20:11:53 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH lrepeat n 8.5 Tcl "Tcl Built-In Commands" 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 lrepeat \- Build a list by repeating elements 15 15 .SH SYNOPSIS 16 16 \fBlrepeat \fInumber element1 \fR?\fIelement2 element3 ...\fR? 17 17 .BE 18 18 .SH DESCRIPTION 19 19 .PP 20 -The \fBlrepeat\fR command creates a list of size \fInumber\fR \(mu \fInumber 21 -of elements\fR by repeating \fInumber\fR times the sequence of elements 22 -\fIelement1 element2 ...\fR. The \fInumber\fR must be a positive integer, and 23 -each \fIelementN\fR can be any Tcl value. 24 -.PP 25 -Note that 26 -.QW "\fBlrepeat 1 arg ...\fR" 27 -is identical to 28 -.QW "\fBlist arg ...\fR" , 29 -though the \fIarg\fR is required with \fBlrepeat\fR. 20 +The \fBlrepeat\fR command creates a list of size \fInumber * number of 21 +elements\fR by repeating \fInumber\fR times the sequence of elements 22 +\fIelement1 element2 ...\fR. \fInumber\fR must be a positive integer, 23 +\fIelementn\fR can be any Tcl value. Note that \fBlrepeat 1 arg ...\fR 24 +is identical to \fBlist arg ...\fR, though the \fIarg\fR is required 25 +with \fBlrepeat\fR. 30 26 .SH EXAMPLES 31 27 .CS 32 -.ta 3i 33 -lrepeat 3 a \fB\(->\fI a a a\fR 34 -lrepeat 3 [lrepeat 3 0] \fB\(->\fI {0 0 0} {0 0 0} {0 0 0}\fR 35 -lrepeat 3 a b c \fB\(->\fI a b c a b c a b c\fR 36 -lrepeat 3 [lrepeat 2 a] b c \fB\(->\fI {a a} b c {a a} b c {a a} b c\fR 28 +lrepeat 3 a => a a a 29 +lrepeat 3 [lrepeat 3 0] => {0 0 0} {0 0 0} {0 0 0} 30 +lrepeat 3 a b c => a b c a b c a b c 31 +lrepeat 3 [lrepeat 2 a] b c => {a a} b c {a a} b c {a a} b c 37 32 .CE 38 33 .SH "SEE ALSO" 39 34 list(n), lappend(n), linsert(n), llength(n), lset(n) 40 35 41 36 .SH KEYWORDS 42 37 element, index, list
Changes to doc/lreplace.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: lreplace.n,v 1.14 2007/10/24 14:29:38 dkf Exp $ 9 +'\" RCS: @(#) $Id: lreplace.n,v 1.15 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH lreplace n 7.4 Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 lreplace \- Replace elements in a list with new elements 17 17 .SH SYNOPSIS 18 18 \fBlreplace \fIlist first last \fR?\fIelement element ...\fR? 19 19 .BE 20 + 20 21 .SH DESCRIPTION 21 22 .PP 22 23 \fBlreplace\fR returns a new list formed by replacing one or more elements of 23 24 \fIlist\fR with the \fIelement\fR arguments. 24 25 .VS 8.5 25 26 \fIfirst\fR and \fIlast\fR are index values specifying the first and 26 27 last elements of the range to replace. ................................................................................ 28 29 the same as index values for the command \fBstring index\fR, 29 30 supporting simple index arithmetic and indices relative to the 30 31 end of the list. 31 32 0 refers to the first element of the 32 33 list, and \fBend\fR refers to the last element of the list. 33 34 If \fIlist\fR is empty, then \fIfirst\fR and \fIlast\fR are ignored. 34 35 .VE 35 -.PP 36 + 36 37 If \fIfirst\fR is less than zero, it is considered to refer to the 37 38 first element of the list. For non-empty lists, the element indicated 38 39 by \fIfirst\fR must exist. 39 -.PP 40 + 40 41 If \fIlast\fR is less than zero but greater than \fIfirst\fR, then any 41 42 specified elements will be prepended to the list. If \fIlast\fR is 42 43 less than \fIfirst\fR then no elements are deleted; the new elements 43 44 are simply inserted before \fIfirst\fR. 44 -.PP 45 + 45 46 The \fIelement\fR arguments specify zero or more new arguments to 46 47 be added to the list in place of those that were deleted. 47 48 Each \fIelement\fR argument will become a separate element of 48 49 the list. If no \fIelement\fR arguments are specified, then the elements 49 50 between \fIfirst\fR and \fIlast\fR are simply deleted. If \fIlist\fR 50 51 is empty, any \fIelement\fR arguments are added to the end of the list. 51 52 .SH EXAMPLES ................................................................................ 64 65 Deleting the last element from a list in a variable: 65 66 .CS 66 67 % set var {a b c d e} 67 68 a b c d e 68 69 % set var [\fBlreplace\fR $var end end] 69 70 a b c d 70 71 .CE 72 + 71 73 .SH "SEE ALSO" 72 74 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 73 75 lset(n), lrange(n), lsort(n), 74 76 .VS 8.5 75 77 string(n) 76 78 .VE 79 + 80 + 77 81 .SH KEYWORDS 78 82 element, list, replace
Changes to doc/lreverse.n.
1 -.\" -*- nroff -*- 2 -.\" Copyright (c) 2006 by Donal K. Fellows. All rights reserved. 3 -.\" 4 -.\" See the file "license.terms" for information on usage and redistribution 5 -.\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 -.\" 7 -.\" RCS: @(#) $Id: lreverse.n,v 1.3 2007/10/25 09:25:27 dkf Exp $ 8 -.\" 1 +'\" -*- nroff -*- 2 +'\" Copyright (c) 2006 by Donal K. Fellows. All rights reserved. 3 +'\" 4 +'\" See the file "license.terms" for information on usage and redistribution 5 +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 +'\" 7 +'\" RCS: @(#) $Id: lreverse.n,v 1.4 2007/10/26 20:11:53 dgp Exp $ 8 +'\" 9 9 .so man.macros 10 10 .TH lreverse n 8.5 Tcl "Tcl Built-In Commands" 11 11 .BS 12 -.\" Note: do not modify the .SH NAME line immediately below! 12 +'\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 lreverse \- Reverse the order of a list 15 15 .SH SYNOPSIS 16 16 \fBlreverse \fIlist\fR 17 17 .BE 18 18 .SH DESCRIPTION 19 19 .PP 20 20 The \fBlreverse\fR command returns a list that has the same elements as its 21 21 input list, \fIlist\fR, except with the elements in the reverse order. 22 22 .SH EXAMPLES 23 23 .CS 24 -.ta 3i 25 -\fBlreverse\fR {a a b c} \fB\(->\fI c b a a\fR 26 -\fBlreverse\fR {a b {c d} e f} \fB\(->\fI f e {c d} b a\fR 24 +\fBlreverse\fR {a a b c} => c b a a 25 +\fBlreverse\fR {a b {c d} e f} => f e {c d} b a 27 26 .CE 28 27 .SH "SEE ALSO" 29 28 list(n), lsearch(n), lsort(n) 29 + 30 30 .SH KEYWORDS 31 31 element, list, reverse
Changes to doc/lsearch.n.
3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved. 5 5 '\" Copyright (c) 2003-2004 Donal K. Fellows. 6 6 '\" 7 7 '\" See the file "license.terms" for information on usage and redistribution 8 8 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 9 9 '\" 10 -'\" RCS: @(#) $Id: lsearch.n,v 1.28 2007/10/25 09:25:27 dkf Exp $ 10 +'\" RCS: @(#) $Id: lsearch.n,v 1.29 2007/10/26 20:11:53 dgp Exp $ 11 11 '\" 12 12 .so man.macros 13 13 .TH lsearch n 8.5 Tcl "Tcl Built-In Commands" 14 14 .BS 15 15 '\" Note: do not modify the .SH NAME line immediately below! 16 16 .SH NAME 17 17 lsearch \- See if a list contains a particular element 18 18 .SH SYNOPSIS 19 19 \fBlsearch \fR?\fIoptions\fR? \fIlist pattern\fR 20 20 .BE 21 + 21 22 .SH DESCRIPTION 22 23 .PP 23 24 This command searches the elements of \fIlist\fR to see if one 24 25 of them matches \fIpattern\fR. If so, the command returns the index 25 26 of the first matching element 26 27 (unless the options \fB\-all\fR or \fB\-inline\fR are specified.) 27 28 If not, the command returns \fB\-1\fR. The \fIoption\fR arguments ................................................................................ 29 30 \fIpattern\fR and must have one of the values below: 30 31 .SS "MATCHING STYLE OPTIONS" 31 32 If all matching style options are omitted, the default matching style 32 33 is \fB\-glob\fR. If more than one matching style is specified, the 33 34 last matching style given takes precedence. 34 35 .TP 35 36 \fB\-exact\fR 36 -. 37 37 \fIPattern\fR is a literal string that is compared for exact equality 38 38 against each list element. 39 39 .TP 40 40 \fB\-glob\fR 41 -. 42 41 \fIPattern\fR is a glob-style pattern which is matched against each list 43 42 element using the same rules as the \fBstring match\fR command. 44 43 .TP 45 44 \fB\-regexp\fR 46 -. 47 45 \fIPattern\fR is treated as a regular expression and matched against 48 46 each list element using the rules described in the \fBre_syntax\fR 49 47 reference page. 50 48 .TP 51 49 \fB\-sorted\fR 52 -. 53 50 The list elements are in sorted order. If this option is specified, 54 51 \fBlsearch\fR will use a more efficient searching algorithm to search 55 52 \fIlist\fR. If no other options are specified, \fIlist\fR is assumed 56 53 to be sorted in increasing order, and to contain ASCII strings. This 57 54 option is mutually exclusive with \fB\-glob\fR and \fB\-regexp\fR, and 58 55 is treated exactly like \fB-exact\fR when either \fB\-all\fR or 59 56 \fB\-not\fR are specified. ................................................................................ 64 61 . 65 62 Changes the result to be the list of all matching indices (or all matching 66 63 values if \fB\-inline\fR is specified as well.) If indices are returned, the 67 64 indices will be in numeric order. If values are returned, the order of the 68 65 values will be the order of those values within the input \fIlist\fR. 69 66 .TP 70 67 \fB\-inline\fR 71 -. 72 68 The matching value is returned instead of its index (or an empty 73 69 string if no value matches.) If \fB\-all\fR is also specified, then 74 70 the result of the command is the list of all values that matched. 75 71 .TP 76 72 \fB\-not\fR 77 -. 78 73 This negates the sense of the match, returning the index of the first 79 74 non-matching value in the list. 80 75 .TP 81 76 \fB\-start\fR\0\fIindex\fR 82 -. 83 77 The list is searched starting at position \fIindex\fR. 84 78 .VS 8.5 85 79 The interpretation of the \fIindex\fR value is the same as 86 80 for the command \fBstring index\fR, supporting simple index 87 81 arithmetic and indices relative to the end of the list. 88 82 .VE 8.5 89 83 .SS "CONTENTS DESCRIPTION OPTIONS" 90 84 These options describe how to interpret the items in the list being 91 85 searched. They are only meaningful when used with the \fB\-exact\fR 92 86 and \fB\-sorted\fR options. If more than one is specified, the last 93 87 one takes precedence. The default is \fB\-ascii\fR. 94 88 .TP 95 89 \fB\-ascii\fR 96 -. 97 90 The list elements are to be examined as Unicode strings (the name is 98 91 for backward-compatibility reasons.) 99 92 .TP 100 93 \fB\-dictionary\fR 101 -. 102 94 The list elements are to be compared using dictionary-style 103 95 comparisons (see \fBlsort\fR for a fuller description). Note that this 104 96 only makes a meaningful difference from the \fB\-ascii\fR option when 105 97 the \fB\-sorted\fR option is given, because values are only 106 98 dictionary-equal when exactly equal. 107 99 .TP 108 100 \fB\-integer\fR 109 -. 110 101 The list elements are to be compared as integers. 111 102 .VS 8.5 112 103 .TP 113 104 \fB\-nocase\fR 114 -. 115 105 Causes comparisons to be handled in a case-insensitive manner. Has no 116 106 effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or 117 107 \fB\-real\fR options. 118 108 .VE 8.5 119 109 .TP 120 110 \fB\-real\fR 121 -. 122 111 The list elements are to be compared as floating-point values. 123 112 .SS "SORTED LIST OPTIONS" 124 113 These options (only meaningful with the \fB\-sorted\fR option) specify 125 114 how the list is sorted. If more than one is given, the last one takes 126 115 precedence. The default option is \fB\-increasing\fR. 127 116 .TP 128 117 \fB\-decreasing\fR 129 -. 130 118 The list elements are sorted in decreasing order. This option is only 131 119 meaningful when used with \fB\-sorted\fR. 132 120 .TP 133 121 \fB\-increasing\fR 134 -. 135 122 The list elements are sorted in increasing order. This option is only 136 123 meaningful when used with \fB\-sorted\fR. 137 124 .SS "NESTED LIST OPTIONS" 138 125 .VS 8.5 139 126 These options are used to search lists of lists. They may be used 140 127 with any other options. 141 128 .TP 142 129 \fB\-index\fR\0\fIindexList\fR 143 -. 144 130 This option is designed for use when searching within nested lists. 145 131 The \fIindexList\fR argument gives a path of indices (much as might be 146 132 used with the \fBlindex\fR or \fBlset\fR commands) within each element 147 133 to allow the location of the term being matched against. 148 134 .TP 149 135 \fB\-subindices\fR 150 -. 151 136 If this option is given, the index result from this command (or every 152 137 index result when \fB\-all\fR is also specified) will be a complete 153 138 path (suitable for use with \fBlindex\fR or \fBlset\fR) within the 154 139 overall list to the term found. This option has no effect unless the 155 140 \fI\-index\fR is also specified, and is just a convenience short-cut. 156 141 .VE 8.5 157 142 .SH EXAMPLES 158 143 Basic searching: 159 144 .CS 160 -.ta 2i 161 145 \fBlsearch\fR {a b c d e} c 162 - \fB\(->\fI 2\fR 146 + => 2 163 147 \fBlsearch\fR -all {a b c a b c} c 164 - \fB\(->\fI 2 5\fR 148 + => 2 5 165 149 .CE 166 -.PP 150 + 167 151 Using \fBlsearch\fR to filter lists: 168 152 .CS 169 -.ta 2i 170 153 \fBlsearch\fR -inline {a20 b35 c47} b* 171 - \fB\(->\fI b35\fR 154 + => b35 172 155 \fBlsearch\fR -inline -not {a20 b35 c47} b* 173 - \fB\(->\fI a20\fR 156 + => a20 174 157 \fBlsearch\fR -all -inline -not {a20 b35 c47} b* 175 - \fB\(->\fI a20 c47\fR 158 + => a20 c47 176 159 \fBlsearch\fR -all -not {a20 b35 c47} b* 177 - \fB\(->\fI 0 2\fR 160 + => 0 2 178 161 .CE 179 -This can even do a 180 -.QW set-like 181 -removal operation: 162 +This can even do a "set-like" removal operation: 182 163 .CS 183 -.ta 2i 184 164 \fBlsearch\fR -all -inline -not -exact {a b c a d e a f g a} a 185 - \fB\(->\fI b c d e f g\fR 165 + => b c d e f g 186 166 .CE 187 -.PP 167 + 188 168 Searching may start part-way through the list: 189 169 .CS 190 -.ta 2i 191 170 \fBlsearch\fR -start 3 {a b c a b c} c 192 - \fB\(->\fI 5\fR 171 + => 5 193 172 .CE 194 -.PP 173 + 195 174 It is also possible to search inside elements: 196 175 .CS 197 -.ta 2i 198 176 \fBlsearch\fR -index 1 -all -inline {{a abc} {b bcd} {c cde}} *bc* 199 - \fB\(->\fI {a abc} {b bcd}\fR 177 + => {a abc} {b bcd} 200 178 .CE 179 + 201 180 .SH "SEE ALSO" 202 181 foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n), 203 182 lset(n), lsort(n), lrange(n), lreplace(n), 204 183 .VS 8.5 205 184 string(n) 206 185 .VE 186 + 187 + 207 188 .SH KEYWORDS 208 189 list, match, pattern, regular expression, search, string 209 -.\" Local Variables: 210 -.\" mode: nroff 211 -.\" End: 190 + 191 +'\" Local Variables: 192 +'\" mode: nroff 193 +'\" End:
Changes to doc/lset.n.
1 1 '\" 2 2 '\" Copyright (c) 2001 by Kevin B. Kenny. All rights reserved. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: lset.n,v 1.11 2007/10/25 09:25:27 dkf Exp $ 7 +'\" RCS: @(#) $Id: lset.n,v 1.12 2007/10/26 20:11:53 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH lset n 8.4 Tcl "Tcl Built-In Commands" 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 lset \- Change an element in a list ................................................................................ 75 75 than or equal to zero. The integer appearing in each \fIindex\fR 76 76 argument must be strictly less than the length of the corresponding 77 77 list. In other words, the \fBlset\fR command cannot change the size 78 78 of a list. If an index is outside the permitted range, an error is reported. 79 79 .SH EXAMPLES 80 80 In each of these examples, the initial value of \fIx\fR is: 81 81 .CS 82 -.ta 2i 83 82 set x [list [list a b c] [list d e f] [list g h i]] 84 - \fB\(->\fR {a b c} {d e f} {g h i} 83 + => {a b c} {d e f} {g h i} 85 84 .CE 86 85 The indicated return value also becomes the new value of \fIx\fR 87 86 (except in the last case, which is an error which leaves the value of 88 87 \fIx\fR unchanged.) 89 88 .CS 90 -.ta 2i 91 -lset x {j k l} \fB\(->\fR j k l 92 -lset x {} {j k l} \fB\(->\fR j k l 93 -lset x 0 j \fB\(->\fR j {d e f} {g h i} 94 -lset x 2 j \fB\(->\fR {a b c} {d e f} j 95 -lset x end j \fB\(->\fR {a b c} {d e f} j 96 -lset x end-1 j \fB\(->\fR {a b c} j {g h i} 97 -lset x 2 1 j \fB\(->\fR {a b c} {d e f} {g j i} 98 -lset x {2 1} j \fB\(->\fR {a b c} {d e f} {g j i} 99 -lset x {2 3} j \fB\(->\fR \fIlist index out of range\fR 89 +lset x {j k l} => j k l 90 +lset x {} {j k l} => j k l 91 +lset x 0 j => j {d e f} {g h i} 92 +lset x 2 j => {a b c} {d e f} j 93 +lset x end j => {a b c} {d e f} j 94 +lset x end-1 j => {a b c} j {g h i} 95 +lset x 2 1 j => {a b c} {d e f} {g j i} 96 +lset x {2 1} j => {a b c} {d e f} {g j i} 97 +lset x {2 3} j => \fIlist index out of range\fR 100 98 .CE 101 99 In the following examples, the initial value of \fIx\fR is: 102 100 .CS 103 -.ta 2i 104 101 set x [list [list [list a b] [list c d]] \e 105 102 [list [list e f] [list g h]]] 106 - \fB\(->\fR {{a b} {c d}} {{e f} {g h}} 103 + => {{a b} {c d}} {{e f} {g h}} 107 104 .CE 108 105 The indicated return value also becomes the new value of \fIx\fR. 109 106 .CS 110 -.ta 2i 111 -lset x 1 1 0 j \fB\(->\fR {{a b} {c d}} {{e f} {j h}} 112 -lset x {1 1 0} j \fB\(->\fR {{a b} {c d}} {{e f} {j h}} 107 +lset x 1 1 0 j => {{a b} {c d}} {{e f} {j h}} 108 +lset x {1 1 0} j => {{a b} {c d}} {{e f} {j h}} 113 109 .CE 114 110 .SH "SEE ALSO" 115 111 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 116 112 lsort(n), lrange(n), lreplace(n), 117 113 .VS 8.5 118 114 string(n) 119 115 .VE 116 + 117 + 120 118 .SH KEYWORDS 121 119 element, index, list, replace, set
Changes to doc/lsort.n.
3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 1999 Scriptics Corporation 5 5 '\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved. 6 6 '\" 7 7 '\" See the file "license.terms" for information on usage and redistribution 8 8 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 9 9 '\" 10 -'\" RCS: @(#) $Id: lsort.n,v 1.23 2007/10/24 14:29:38 dkf Exp $ 10 +'\" RCS: @(#) $Id: lsort.n,v 1.24 2007/10/26 20:11:53 dgp Exp $ 11 11 '\" 12 12 .so man.macros 13 13 .TH lsort n 8.5 Tcl "Tcl Built-In Commands" 14 14 .BS 15 15 '\" Note: do not modify the .SH NAME line immediately below! 16 16 .SH NAME 17 17 lsort \- Sort the elements of a list ................................................................................ 55 55 \fIcommand\fR with the two elements appended as additional 56 56 arguments. The script should return an integer less than, 57 57 equal to, or greater than zero if the first element is to 58 58 be considered less than, equal to, or greater than the second, 59 59 respectively. 60 60 .TP 20 61 61 \fB\-increasing\fR 62 -Sort the list in increasing order (i.e. 63 -.QW smallest 64 -items first). This is the default. 62 +Sort the list in increasing order (``smallest'' items first). 63 +This is the default. 65 64 .TP 20 66 65 \fB\-decreasing\fR 67 -Sort the list in decreasing order (i.e. 68 -.QW largest 69 -items first). 66 +Sort the list in decreasing order (``largest'' items first). 70 67 .TP 20 71 68 \fB\-indices\fR 72 69 .VS "8.5 (TIP#217)" 73 70 Return a list of indices into \fIlist\fR in sorted order instead of 74 71 the values themselves. 75 72 .VE "8.5 (TIP#217)" 76 73 .TP 20
Changes to doc/mathfunc.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-2000 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2005 by Kevin B. Kenny <[email protected]>. All rights reserved 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: mathfunc.n,v 1.14 2007/10/25 14:07:32 dkf Exp $ 9 +'\" RCS: @(#) $Id: mathfunc.n,v 1.15 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH mathfunc n 8.5 Tcl "Tcl Mathematical Functions" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 mathfunc \- Mathematical functions for Tcl expressions ................................................................................ 81 81 .br 82 82 \fB::tcl::mathfunc::wide\fR \fIarg\fR 83 83 .sp 84 84 .BE 85 85 .SH "DESCRIPTION" 86 86 .PP 87 87 The \fBexpr\fR command handles mathematical functions of the form 88 -.QW \fBsin($x)\fR 89 -or 90 -.QW \fBatan2($y,$x)\fR 91 -by converting them to calls of the form 92 -.QW "\fB[tcl::mathfunc::sin [expr {$x}]]\fR" 93 -or 94 -.QW "\fB[tcl::mathfunc::atan2 [expr {$y}] [expr {$x}]]\fR" . 88 +\fBsin($x)\fR or \fBatan2($y,$x)\fR by converting them to calls of the 89 +form \fB[tcl::mathfunc::sin [expr {$x}]]\fR or 90 +\fB[tcl::mathfunc::atan2 [expr {$y}] [expr {$x}]]\fR. 95 91 A number of math functions are available by default within the 96 92 namespace \fB::tcl::mathfunc\fR; these functions are also available 97 93 for code apart from \fBexpr\fR, by invoking the given commands 98 94 directly. 99 95 .PP 100 96 Tcl supports the following mathematical functions in expressions, all 101 97 of which work solely with floating-point numbers unless otherwise noted: ................................................................................ 109 105 \fBmin\fR \fBpow\fR \fBrand\fR \fBround\fR 110 106 \fBsin\fR \fBsinh\fR \fBsqrt\fR \fBsrand\fR 111 107 \fBtan\fR \fBtanh\fR \fBwide\fR 112 108 .DE 113 109 .PP 114 110 .TP 115 111 \fBabs(\fIarg\fB)\fR 116 -. 117 112 Returns the absolute value of \fIarg\fR. \fIArg\fR may be either 118 113 integer or floating-point, and the result is returned in the same form. 119 114 .TP 120 115 \fBacos(\fIarg\fB)\fR 121 -. 122 116 Returns the arc cosine of \fIarg\fR, in the range [\fI0\fR,\fIpi\fR] 123 117 radians. \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR]. 124 118 .TP 125 119 \fBasin(\fIarg\fB)\fR 126 -. 127 120 Returns the arc sine of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR] 128 121 radians. \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR]. 129 122 .TP 130 123 \fBatan(\fIarg\fB)\fR 131 -. 132 124 Returns the arc tangent of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR] 133 125 radians. 134 126 .TP 135 127 \fBatan2(\fIy, x\fB)\fR 136 -. 137 128 Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI-pi\fR,\fIpi\fR] 138 129 radians. \fIx\fR and \fIy\fR cannot both be 0. If \fIx\fR is greater 139 130 than \fI0\fR, this is equivalent to \fBatan(\fIy/x\fB)\fR. 140 131 .TP 141 132 \fBbool(\fIarg\fB)\fR 142 -. 143 133 Accepts any numeric value, or any string acceptable to 144 134 \fBstring is boolean\fR, and returns the corresponding 145 135 boolean value \fB0\fR or \fB1\fR. Non-zero numbers are true. 146 136 Other numbers are false. Non-numeric strings produce boolean value in 147 -agreement with 148 -.QW "\fBstring is true\fR" 149 -and 150 -.QW "\fBstring is false\fR" . 137 +agreement with \fBstring is true\fR and \fBstring is false\fR. 151 138 .TP 152 139 \fBceil(\fIarg\fB)\fR 153 -. 154 140 Returns the smallest integral floating-point value (i.e. with a zero 155 141 fractional part) not less than \fIarg\fR. The argument may be any 156 142 numeric value. 157 143 .TP 158 144 \fBcos(\fIarg\fB)\fR 159 -. 160 145 Returns the cosine of \fIarg\fR, measured in radians. 161 146 .TP 162 147 \fBcosh(\fIarg\fB)\fR 163 -. 164 148 Returns the hyperbolic cosine of \fIarg\fR. If the result would cause 165 149 an overflow, an error is returned. 166 150 .TP 167 151 \fBdouble(\fIarg\fB)\fR 168 -. 169 152 The argument may be any numeric value, 170 153 If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts 171 154 \fIarg\fR to floating-point and returns the converted value. May return 172 155 \fBInf\fR or \fB-Inf\fR when the argument is a numeric value that exceeds 173 156 the floating-point range. 174 157 .TP 175 158 \fBentier(\fIarg\fB)\fR ................................................................................ 177 160 The argument may be any numeric value. The integer part of \fIarg\fR 178 161 is determined and returned. The integer range returned by this function 179 162 is unlimited, unlike functions \fBint()\fR and \fBwide()\fR which 180 163 truncate their range to fit in particular storage widths. 181 164 .VE 8.5 182 165 .TP 183 166 \fBexp(\fIarg\fB)\fR 184 -. 185 167 Returns the exponential of \fIarg\fR, defined as \fIe\fR**\fIarg\fR. 186 168 If the result would cause an overflow, an error is returned. 187 169 .TP 188 170 \fBfloor(\fIarg\fB)\fR 189 -. 190 171 Returns the largest integral floating-point value (i.e. with a zero 191 172 fractional part) not greater than \fIarg\fR. The argument may be 192 173 any numeric value. 193 174 .TP 194 175 \fBfmod(\fIx, y\fB)\fR 195 -. 196 176 Returns the floating-point remainder of the division of \fIx\fR by 197 177 \fIy\fR. If \fIy\fR is 0, an error is returned. 198 178 .TP 199 179 \fBhypot(\fIx, y\fB)\fR 200 -. 201 180 Computes the length of the hypotenuse of a right-angled triangle 202 -.QW "\fBsqrt(\fIx\fR*\fIx\fR+\fIy\fR*\fIy\fB)\fR" . 181 +\fBsqrt(\fIx\fR*\fIx\fR+\fIy\fR*\fIy\fB)\fR. 203 182 .TP 204 183 \fBint(\fIarg\fB)\fR 205 -. 206 184 The argument may be any numeric value. The integer part of \fIarg\fR 207 185 is determined, and then the low order bits of that integer value up 208 186 to the machine word size are returned as an integer value. For reference, 209 187 the number of bytes in the machine word are stored in 210 188 \fBtcl_platform(wordSize)\fR. 211 189 .TP 212 190 \fBisqrt(\fIarg\fB)\fR 213 -. 214 191 Computes the integer part of the square root of \fIarg\fR. \fIArg\fR must be 215 192 a positive value, either an integer or a floating point number. 216 193 Unlike \fBsqrt\fR, which is limited to the precision of a floating point 217 194 number, \fIisqrt\fR will return a result of arbitrary precision. 218 195 .TP 219 196 \fBlog(\fIarg\fB)\fR 220 -. 221 197 Returns the natural logarithm of \fIarg\fR. \fIArg\fR must be a 222 198 positive value. 223 199 .TP 224 200 \fBlog10(\fIarg\fB)\fR 225 -. 226 201 Returns the base 10 logarithm of \fIarg\fR. \fIArg\fR must be a 227 202 positive value. 228 203 .TP 229 204 \fBmax(\fIarg\fB, \fI...\fB)\fR 230 -. 231 205 Accepts one or more numeric arguments. Returns the one argument 232 206 with the greatest value. 233 207 .TP 234 208 \fBmin(\fIarg\fB, \fI...\fB)\fR 235 -. 236 209 Accepts one or more numeric arguments. Returns the one argument 237 210 with the least value. 238 211 .TP 239 212 \fBpow(\fIx, y\fB)\fR 240 -. 241 213 Computes the value of \fIx\fR raised to the power \fIy\fR. If \fIx\fR 242 214 is negative, \fIy\fR must be an integer value. 243 215 .TP 244 216 \fBrand()\fR 245 -. 246 217 Returns a pseudo-random floating-point value in the range (\fI0\fR,\fI1\fR). 247 218 The generator algorithm is a simple linear congruential generator that 248 219 is not cryptographically secure. Each result from \fBrand\fR completely 249 220 determines all future results from subsequent calls to \fBrand\fR, so 250 221 \fBrand\fR should not be used to generate a sequence of secrets, such as 251 222 one-time passwords. The seed of the generator is initialized from the 252 223 internal clock of the machine or may be set with the \fBsrand\fR function. 253 224 .TP 254 225 \fBround(\fIarg\fB)\fR 255 -. 256 226 If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts 257 227 \fIarg\fR to integer by rounding and returns the converted value. 258 228 .TP 259 229 \fBsin(\fIarg\fB)\fR 260 -. 261 230 Returns the sine of \fIarg\fR, measured in radians. 262 231 .TP 263 232 \fBsinh(\fIarg\fB)\fR 264 -. 265 233 Returns the hyperbolic sine of \fIarg\fR. If the result would cause 266 234 an overflow, an error is returned. 267 235 .TP 268 236 \fBsqrt(\fIarg\fB)\fR 269 -. 270 237 The argument may be any non-negative numeric value. Returns a floating-point 271 238 value that is the square root of \fIarg\fR. May return \fBInf\fR when the 272 239 argument is a numeric value that exceeds the square of the maximum value of 273 240 the floating-point range. 274 241 .TP 275 242 \fBsrand(\fIarg\fB)\fR 276 -. 277 243 The \fIarg\fR, which must be an integer, is used to reset the seed for 278 244 the random number generator of \fBrand\fR. Returns the first random 279 245 number (see \fBrand()\fR) from that seed. Each interpreter has its own seed. 280 246 .TP 281 247 \fBtan(\fIarg\fB)\fR 282 -. 283 248 Returns the tangent of \fIarg\fR, measured in radians. 284 249 .TP 285 250 \fBtanh(\fIarg\fB)\fR 286 -. 287 251 Returns the hyperbolic tangent of \fIarg\fR. 288 252 .TP 289 253 \fBwide(\fIarg\fB)\fR 290 -. 291 254 The argument may be any numeric value. The integer part of \fIarg\fR 292 255 is determined, and then the low order 64 bits of that integer value 293 256 are returned as an integer value. 294 257 .PP 295 258 In addition to these predefined functions, applications may 296 259 define additional functions by using \fBproc\fR (or any other method, 297 260 such as \fBinterp alias\fR or \fBTcl_CreateObjCommand\fR) to define ................................................................................ 298 261 new commands in the \fBtcl::mathfunc\fR namespace. In addition, an 299 262 obsolete interface named \fBTcl_CreateMathFunc\fR() is available to 300 263 extensions that are written in C. The latter interface is not recommended 301 264 for new implementations. 302 265 .SH "SEE ALSO" 303 266 expr(n), namespace(n) 304 267 .SH "COPYRIGHT" 305 -.nf 306 -Copyright \(co 1993 The Regents of the University of California. 307 -Copyright \(co 1994-2000 Sun Microsystems Incorporated. 308 -Copyright \(co 2005, 2006 by Kevin B. Kenny <[email protected]>. 309 -.fi 268 +Copyright (c) 1993 The Regents of the University of California. 269 +.br 270 +Copyright (c) 1994-2000 Sun Microsystems Incorporated. 271 +.br 272 +Copyright (c) 2005, 2006 by Kevin B. Kenny <[email protected]>.
Changes to doc/mathop.n.
1 1 .\" -*- nroff -*- 2 2 .\" Copyright (c) 2006 Donal K. Fellows. 3 3 .\" 4 4 .\" See the file "license.terms" for information on usage and redistribution 5 5 .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 .\" 7 -.\" RCS: @(#) $Id: mathop.n,v 1.5 2007/10/25 14:07:32 dkf Exp $ 7 +.\" RCS: @(#) $Id: mathop.n,v 1.6 2007/10/26 20:11:53 dgp Exp $ 8 8 .\" 9 9 .so man.macros 10 10 .TH mathop n 8.5 Tcl "Tcl Mathematical Operator Commands" 11 11 .BS 12 12 .\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 mathop \- Mathematical operators as Tcl commands ................................................................................ 121 121 Returns the integral modulus of the first argument with respect to the second. 122 122 Each \fInumber\fR must have an integral value. 123 123 .TP 124 124 \fB**\fR ?\fInumber\fR ...? 125 125 . 126 126 Returns the result of raising each value to the power of the result of 127 127 recursively operating on the result of processing the following arguments, so 128 -.QW "\fB** 2 3 4\fR" 129 -is the same as 130 -.QW "\fB** 2 [** 3 4]\fR" . 131 -Each \fInumber\fR may be 128 +\fB** 2 3 4\fR is the same as \fB** 2 [** 3 4]\fR. Each \fInumber\fR may be 132 129 any numeric value, though the second number must not be fractional if the 133 130 first is negative. If no arguments are given, the result will be one, and if 134 131 only one argument is given, the result will be that argument. 135 132 .TP 136 133 \fB&\fR ?\fInumber\fR ...? 137 134 . 138 135 Returns the bit-wise AND of each of the arbitrarily many arguments. Each
Changes to doc/memory.n.
1 1 '\" 2 2 '\" Copyright (c) 1992-1999 by Karl Lehenbauer and Mark Diekhans 3 3 '\" Copyright (c) 2000 by Scriptics Corporation. 4 4 '\" All rights reserved. 5 5 '\" 6 -'\" RCS: @(#) $Id: memory.n,v 1.7 2007/10/25 14:07:32 dkf Exp $ 6 +'\" RCS: @(#) $Id: memory.n,v 1.8 2007/10/26 20:11:53 dgp Exp $ 7 7 '\" 8 8 .so man.macros 9 9 .TH memory n 8.1 Tcl "Tcl Built-In Commands" 10 10 .BS 11 11 .SH NAME 12 12 memory \- Control Tcl memory debugging capabilities 13 13 .SH SYNOPSIS 14 14 \fBmemory \fIoption \fR?\fIarg arg ...\fR? 15 15 .BE 16 + 16 17 .SH DESCRIPTION 17 18 .PP 18 19 The \fBmemory\fR command gives the Tcl developer control of Tcl's memory 19 20 debugging capabilities. The memory command has several suboptions, which are 20 21 described below. It is only available when Tcl has been compiled with 21 22 memory debugging enabled (when \fBTCL_MEM_DEBUG\fR is defined at 22 23 compile time), and after \fBTcl_InitMemory\fR has been called. 23 24 .TP 24 25 \fBmemory active\fR \fIfile\fR 25 -. 26 26 Write a list of all currently allocated memory to the specified \fIfile\fR. 27 27 .TP 28 28 \fBmemory break_on_malloc\fR \fIcount\fR 29 -. 30 29 After the \fIcount\fR allocations have been performed, \fBckalloc\fR 31 30 outputs a message to this effect and that it is now attempting to enter 32 31 the C debugger. Tcl will then issue a \fISIGINT\fR signal against itself. 33 32 If you are running Tcl under a C debugger, it should then enter the debugger 34 33 command mode. 35 34 .TP 36 35 \fBmemory info\fR 37 -. 38 36 Returns a report containing the total allocations and frees since 39 37 Tcl began, the current packets allocated (the current 40 38 number of calls to \fBckalloc\fR not met by a corresponding call 41 39 to \fBckfree\fR), the current bytes allocated, and the maximum number 42 40 of packets and bytes allocated. 43 41 .TP 44 -\fBmemory init \fR[\fBon\fR|\fBoff\fR] 45 -. 42 +\fB memory init [on|off]\fR 46 43 Turn on or off the pre-initialization of all allocated memory 47 44 with bogus bytes. Useful for detecting the use of uninitialized values. 48 45 .TP 49 46 \fBmemory onexit\fR \fIfile\fR 50 -. 51 47 Causes a list of all allocated memory to be written to the specified \fIfile\fR 52 48 during the finalization of Tcl's memory subsystem. Useful for checking 53 49 that memory is properly cleaned up during process exit. 54 50 .TP 55 51 \fBmemory tag\fR \fIstring\fR 56 -. 57 52 Each packet of memory allocated by \fBckalloc\fR can have associated 58 53 with it a string-valued tag. In the lists of allocated memory generated 59 54 by \fBmemory active\fR and \fBmemory onexit\fR, the tag for each packet 60 55 is printed along with other information about the packet. The 61 56 \fBmemory tag\fR command sets the tag value for subsequent calls 62 57 to \fBckalloc\fR to be \fIstring\fR. 63 58 .TP 64 -\fBmemory trace \fR[\fBon\fR|\fBoff\fR] 65 -. 59 +\fBmemory trace [on|off]\fR 60 +.br 66 61 Turns memory tracing on or off. When memory tracing is on, every call 67 62 to \fBckalloc\fR causes a line of trace information to be written to 68 63 \fIstderr\fR, consisting of the word \fIckalloc\fR, followed by the 69 64 address returned, the amount of memory allocated, and the C filename 70 65 and line number of the code performing the allocation. For example: 71 66 .RS 72 67 .CS 73 68 ckalloc 40e478 98 tclProc.c 1406 74 69 .CE 75 70 Calls to \fBckfree\fR are traced in the same manner. 76 71 .RE 77 72 .TP 78 73 \fBmemory trace_on_at_malloc\fR \fIcount\fR 79 -. 80 -Enable memory tracing after \fIcount\fR \fBckalloc\fRs have been performed. 81 -For example, if you enter 82 -.QW "\fBmemory trace_on_at_malloc 100\fR" , 83 -. 74 +Enable memory tracing after \fIcount\fR \fBckalloc\fR's have been performed. 75 +For example, if you enter \fBmemory trace_on_at_malloc 100\fR, 84 76 after the 100th call to \fBckalloc\fR, memory trace information will begin 85 77 being displayed for all allocations and frees. Since there can be a lot 86 78 of memory activity before a problem occurs, judicious use of this option 87 79 can reduce the slowdown caused by tracing (and the amount of trace information 88 80 produced), if you can identify a number of allocations that occur before 89 81 the problem sets in. The current number of memory allocations that have 90 82 occurred since Tcl started is printed on a guard zone failure. 91 83 .TP 92 -\fBmemory validate \fR[\fBon\fR|\fBoff\fR] 93 -. 84 +\fBmemory validate [on|off]\fR 94 85 Turns memory validation on or off. When memory validation is enabled, 95 86 on every call to \fBckalloc\fR or \fBckfree\fR, the guard zones are 96 87 checked for every piece of memory currently in existence that was 97 88 allocated by \fBckalloc\fR. This has a large performance impact and 98 89 should only be used when overwrite problems are strongly suspected. 99 90 The advantage of enabling memory validation is that a guard zone 100 91 overwrite can be detected on the first call to \fBckalloc\fR or 101 92 \fBckfree\fR after the overwrite occurred, rather than when the 102 93 specific memory with the overwritten guard zone(s) is freed, which may 103 94 occur long after the overwrite occurred. 95 + 104 96 .SH "SEE ALSO" 105 -ckalloc(3), ckfree(3), Tcl_ValidateAllMemory(3), Tcl_DumpActiveMemory(3), 106 -TCL_MEM_DEBUG 97 +ckalloc, ckfree, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory, TCL_MEM_DEBUG 98 + 107 99 .SH KEYWORDS 108 100 memory, debug
Changes to doc/msgcat.n.
29 29 .sp 30 30 \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? 31 31 .sp 32 32 \fB::msgcat::mcmset \fIlocale src-trans-list\fR 33 33 .sp 34 34 \fB::msgcat::mcunknown \fIlocale src-string\fR 35 35 .BE 36 + 36 37 .SH DESCRIPTION 37 38 .PP 38 39 The \fBmsgcat\fR package provides a set of functions 39 40 that can be used to manage multi-lingual user interfaces. 40 -Text strings are defined in a 41 -.QW "message catalog" 42 -which is independent from the application, and 41 +Text strings are defined in a ``message catalog'' which 42 +is independent from the application, and 43 43 which can be edited or localized without modifying 44 44 the application source code. New languages 45 45 or locales are provided by adding a new file to 46 46 the message catalog. 47 47 .PP 48 48 Use of the message catalog is optional by any application 49 49 or package, but is encouraged if the application or package ................................................................................ 90 90 the user, based on the user's language specification. 91 91 The list is ordered from most specific to least 92 92 preference. The list is derived from the current 93 93 locale set in msgcat by \fB::msgcat::mclocale\fR, and 94 94 cannot be set independently. For example, if the 95 95 current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR 96 96 .VS 1.4 97 -returns 98 -.QW "\fBen_US_funky en_US en {}\fR" . 97 +returns \fB{en_US_funky en_US en {}}\fR. 99 98 .VE 1.4 100 99 .TP 101 100 \fB::msgcat::mcload \fIdirname\fR 102 101 Searches the specified directory for files that match 103 102 the language specifications returned by \fB::msgcat::mcpreferences\fR 104 -(note that these are all lowercase), extended by the file extension 105 -.QW .msg . 106 -Each matching file is 103 +(note that these are all lowercase), extended by the file 104 +extension ``.msg''. Each matching file is 107 105 read in order, assuming a UTF-8 encoding. The file contents are 108 106 then evaluated as a Tcl script. This means that Unicode characters 109 107 may be present in the message file either directly in their UTF-8 110 108 encoded form, or by use of the backslash-u quoting recognized by Tcl 111 109 evaluation. The number of message files which matched the specification 112 110 and were loaded is returned. 113 111 .TP ................................................................................ 118 116 for both. The function returns \fItranslate-string\fR. 119 117 .TP 120 118 \fB::msgcat::mcmset \fIlocale src-trans-list\fR 121 119 Sets the translation for multiple source strings in 122 120 \fIsrc-trans-list\fR in the specified \fIlocale\fR and the current 123 121 namespace. 124 122 \fIsrc-trans-list\fR must have an even number of elements and is in 125 -the form 126 -.QW "\fIsrc-string translate-string\fR ?\fIsrc-string translate-string ...\fR?}" . 127 -The \fB::msgcat::mcmset\fR command can be significantly 123 +the form {\fIsrc-string translate-string\fR ?\fIsrc-string 124 +translate-string ...\fR?} \fB::msgcat::mcmset\fR can be significantly 128 125 faster than multiple invocations of \fB::msgcat::mcset\fR. The function 129 126 returns the number of translations set. 130 127 .TP 131 128 \fB::msgcat::mcunknown \fIlocale src-string\fR 132 129 This routine is called by \fB::msgcat::mc\fR in the case when 133 130 a translation for \fIsrc-string\fR is not defined in the 134 131 current locale. The default action is to return ................................................................................ 140 137 to \fB::msgcat::mc\fR. 141 138 .SH "LOCALE SPECIFICATION" 142 139 .PP 143 140 The locale is specified to \fBmsgcat\fR by a locale string 144 141 passed to \fB::msgcat::mclocale\fR. 145 142 The locale string consists of 146 143 a language code, an optional country code, and an optional 147 -system-specific code, each separated by 148 -.QW _ . 149 -The country and language 144 +system-specific code, each separated by ``_''. The country and language 150 145 codes are specified in standards ISO-639 and ISO-3166. 151 -For example, the locale 152 -.QW en 153 -specifies English and 154 -.QW en_US 155 -specifies U.S. English. 146 +For example, the locale ``en'' specifies English and ``en_US'' specifies 147 +U.S. English. 156 148 .PP 157 149 When the msgcat package is first loaded, the locale is initialized 158 150 according to the user's environment. The variables \fBenv(LC_ALL)\fR, 159 151 \fBenv(LC_MESSAGES)\fR, and \fBenv(LANG)\fR are examined in order. 160 152 The first of them to have a non-empty value is used to determine the 161 153 initial locale. The value is parsed according to the XPG4 pattern 162 154 .CS ................................................................................ 167 159 .CS 168 160 language[_country][_modifier] 169 161 .CE 170 162 On Windows, if none of those environment variables is set, msgcat will 171 163 attempt to extract locale information from the 172 164 registry. If all these attempts to discover an initial locale 173 165 from the user's environment fail, msgcat defaults to an initial 174 -locale of 175 -.QW C . 166 +locale of ``C''. 176 167 .PP 177 -When a locale is specified by the user, a 178 -.QW "best match" 179 -search is 168 +When a locale is specified by the user, a ``best match'' search is 180 169 performed during string translation. For example, if a user specifies 181 170 .VS 1.4 182 -en_GB_Funky, the locales 183 -.QW en_GB_Funky , 184 -.QW en_GB , 185 -.QW en 186 -and 187 -.MT 171 +en_GB_Funky, the locales ``en_GB_Funky'', ``en_GB'', ``en'' and ``'' 188 172 (the empty string) 189 173 .VE 1.4 190 174 are searched in order until a matching translation 191 175 string is found. If no translation string is available, then 192 176 \fB::msgcat::mcunknown\fR is called. 193 177 .SH "NAMESPACES AND MESSAGE CATALOGS" 194 178 .PP ................................................................................ 213 197 hello from :: 214 198 hello from ::foo 215 199 .CE 216 200 .PP 217 201 When searching for a translation of a message, the 218 202 message catalog will search first the current namespace, 219 203 then the parent of the current namespace, and so on until 220 -the global namespace is reached. This allows child namespaces to 221 -.QW inherit 222 -messages from their parent namespace. 204 +the global namespace is reached. This allows child namespaces 205 +to "inherit" messages from their parent namespace. 223 206 .PP 224 -For example, executing (in the 225 -.QW en 226 -locale) the code 207 +For example, executing (in the ``en'' locale) the code 227 208 .CS 228 209 \fB::msgcat::mcset\fR en m1 ":: message1" 229 210 \fB::msgcat::mcset\fR en m2 ":: message2" 230 211 \fB::msgcat::mcset\fR en m3 ":: message3" 231 212 namespace eval ::foo { 232 213 \fB::msgcat::mcset\fR en m2 "::foo message2" 233 214 \fB::msgcat::mcset\fR en m3 "::foo message3" ................................................................................ 250 231 .PP 251 232 Message files can be located in any directory, subject 252 233 to the following conditions: 253 234 .IP [1] 254 235 All message files for a package are in the same directory. 255 236 .IP [2] 256 237 The message file name is a msgcat locale specifier (all lowercase) 257 -followed by 258 -.QW .msg . 259 -For example: 260 -.RS 238 +followed by ``.msg''. For example: 261 239 .CS 262 240 es.msg -- spanish 263 241 en_gb.msg -- United Kingdom English 264 242 .CE 265 243 .VS 1.4 266 -\fIException:\fR The message file for the root locale 267 -.MT 268 -is called \fBROOT.msg\fR. This exception is made so as not to 244 +\fIException:\fR The message file for the root locale ``'' is 245 +called \fBROOT.msg\fR. This exception is made so as not to 269 246 cause peculiar behavior, such as marking the message file as 270 -.QW hidden 271 -on Unix file systems. 247 +``hidden'' on Unix file systems. 272 248 .VE 1.4 273 -.RE 274 249 .IP [3] 275 250 The file contains a series of calls to \fBmcset\fR and 276 251 \fBmcmset\fR, setting the necessary translation strings 277 252 for the language, likely enclosed in a \fBnamespace eval\fR 278 253 so that all source strings are tied to the namespace of 279 254 the package. For example, a short \fBes.msg\fR might contain: 280 -.RS 281 255 .CS 282 256 namespace eval ::mypackage { 283 257 \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!" 284 258 } 285 259 .CE 286 -.RE 287 260 .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES" 288 261 .PP 289 262 If a package is installed into a subdirectory of the 290 263 \fBtcl_pkgPath\fR and loaded via \fBpackage require\fR, the 291 264 following procedure is recommended. 292 265 .IP [1] 293 266 During package installation, create a subdirectory 294 267 \fBmsgs\fR under your package directory. 295 268 .IP [2] 296 269 Copy your *.msg files into that directory. 297 270 .IP [3] 298 -Add the following command to your package initialization script: 299 -.RS 271 + Add the following command to your package 272 +initialization script: 300 273 .CS 301 274 # load language files, stored in msgs subdirectory 302 275 \fB::msgcat::mcload\fR [file join [file dirname [info script]] msgs] 303 276 .CE 304 -.RE 305 277 .SH "POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS" 306 278 .PP 307 279 It is possible that a message string used as an argument 308 280 to \fBformat\fR might have positionally dependent parameters that 309 281 might need to be repositioned. For example, it might be 310 282 syntactically desirable to rearrange the sentence structure 311 283 while translating. 312 284 .CS 313 285 format "We produced %d units in location %s" $num $city 314 286 format "In location %s we produced %d units" $city $num 315 287 .CE 316 288 .PP 317 -This can be handled by using the positional parameters: 289 +This can be handled by using the positional 290 +parameters: 318 291 .CS 319 292 format "We produced %1\\$d units in location %2\\$s" $num $city 320 293 format "In location %2\\$s we produced %1\\$d units" $num $city 321 294 .CE 322 295 .PP 323 296 Similarly, positional parameters can be used with \fBscan\fR to 324 297 extract values from internationalized strings. 325 -.PP 326 -\fINote:\fR for the specific case of formatting a string, you should 327 -take advantage of the fact that the \fB::msgcat::mc\fR command already 328 -passes its string through \fBformat\fR internally. 329 298 .SH CREDITS 330 299 .PP 331 300 The message catalog code was developed by Mark Harrison. 301 + 332 302 .SH "SEE ALSO" 333 303 format(n), scan(n), namespace(n), package(n) 304 + 334 305 .SH KEYWORDS 335 306 internationalization, i18n, localization, l10n, message, text, translation
Changes to doc/namespace.n.
3 3 '\" Copyright (c) 1997 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2000 Scriptics Corporation. 5 5 '\" Copyright (c) 2004-2005 Donal K. Fellows. 6 6 '\" 7 7 '\" See the file "license.terms" for information on usage and redistribution 8 8 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 9 9 '\" 10 -'\" RCS: @(#) $Id: namespace.n,v 1.22 2007/10/24 14:29:38 dkf Exp $ 10 +'\" RCS: @(#) $Id: namespace.n,v 1.23 2007/10/26 20:11:53 dgp Exp $ 11 11 '\" 12 12 .so man.macros 13 13 .TH namespace n 8.5 Tcl "Tcl Built-In Commands" 14 14 .BS 15 -.\" Note: do not modify the .SH NAME line immediately below! 15 +'\" Note: do not modify the .SH NAME line immediately below! 16 16 .SH NAME 17 17 namespace \- create and manipulate contexts for commands and variables 18 18 .SH SYNOPSIS 19 19 \fBnamespace \fR?\fIoption\fR? ?\fIarg ...\fR? 20 20 .BE 21 21 22 22 .SH DESCRIPTION ................................................................................ 51 51 The new script has two important properties. 52 52 First, it can be evaluated in any namespace and will cause 53 53 \fIscript\fR to be evaluated in the current namespace 54 54 (the one where the \fBnamespace code\fR command was invoked). 55 55 Second, additional arguments can be appended to the resulting script 56 56 and they will be passed to \fIscript\fR as additional arguments. 57 57 For example, suppose the command 58 -.QW "\fBset script [namespace code {foo bar}]\fR" 58 +\fBset script [namespace code {foo bar}]\fR 59 59 is invoked in namespace \fB::a::b\fR. 60 -Then 61 -.QW \fBeval\0"$script\0x\0y"\fR 60 +Then \fBeval "$script x y"\fR 62 61 can be executed in any namespace (assuming the value of 63 62 \fBscript\fR has been passed in properly) 64 63 and will have the same effect as the command 65 64 \fB::namespace eval ::a::b {foo bar x y}\fR. 66 65 This command is needed because 67 66 extensions like Tk normally execute callback scripts 68 67 in the global namespace. ................................................................................ 69 68 A scoped command captures a command together with its namespace context 70 69 in a way that allows it to be executed properly later. 71 70 See the section \fBSCOPED SCRIPTS\fR for some examples 72 71 of how this is used to create callback scripts. 73 72 .TP 74 73 \fBnamespace current\fR 75 74 Returns the fully-qualified name for the current namespace. 76 -The actual name of the global namespace is 77 -.MT 75 +The actual name of the global namespace is ``'' 78 76 (i.e., an empty string), 79 77 but this command returns \fB::\fR for the global namespace 80 78 as a convenience to programmers. 81 79 .TP 82 80 \fBnamespace delete \fR?\fInamespace namespace ...\fR? 83 81 Each namespace \fInamespace\fR is deleted 84 82 and all variables, procedures, and child namespaces ................................................................................ 216 214 \fBnamespace parent\fR ?\fInamespace\fR? 217 215 Returns the fully-qualified name of the parent namespace 218 216 for namespace \fInamespace\fR. 219 217 If \fInamespace\fR is not specified, 220 218 the fully-qualified name of the current namespace's parent is returned. 221 219 .TP 222 220 \fBnamespace path\fR ?\fInamespaceList\fR? 223 -.\" Should really have the .TP inside the .VS, but that triggers a groff bug 221 +'\" Should really have the .TP inside the .VS, but that triggers a groff bug 224 222 .VS 8.5 225 223 Returns the command resolution path of the current namespace. If 226 224 \fInamespaceList\fR is specified as a list of named namespaces, the 227 225 current namespace's command resolution path is set to those namespaces 228 226 and returns the empty list. The default command resolution path is 229 227 always empty. See the section \fBNAME RESOLUTION\fR below for an 230 228 explanation of the rules regarding name resolution. ................................................................................ 357 355 Since namespaces may nest, 358 356 qualified names are used to refer to 359 357 commands, variables, and child namespaces contained inside namespaces. 360 358 Qualified names are similar to the hierarchical path names for 361 359 Unix files or Tk widgets, 362 360 except that \fB::\fR is used as the separator 363 361 instead of \fB/\fR or \fB.\fR. 364 -The topmost or global namespace has the name 365 -.MT 366 -(i.e., an empty string), although \fB::\fR is a synonym. 362 +The topmost or global namespace has the name ``'' (i.e., an empty string), 363 +although \fB::\fR is a synonym. 367 364 As an example, the name \fB::safe::interp::create\fR 368 365 refers to the command \fBcreate\fR in the namespace \fBinterp\fR 369 366 that is a child of namespace \fB::safe\fR, 370 367 which in turn is a child of the global namespace, \fB::\fR. 371 368 .PP 372 369 If you want to access commands and variables from another namespace, 373 370 you must use some extra syntax. ................................................................................ 830 827 foobar grill 831 828 .CE 832 829 .PP 833 830 Look up where the command imported in the previous example came from: 834 831 .CS 835 832 puts "grill came from [\fBnamespace origin\fR grill]" 836 833 .CE 834 + 837 835 .SH "SEE ALSO" 838 836 interp(n), upvar(n), variable(n) 837 + 839 838 .SH KEYWORDS 840 839 command, ensemble, exported, internal, variable
Changes to doc/open.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: open.n,v 1.29 2007/10/24 14:29:38 dkf Exp $ 8 +'\" RCS: @(#) $Id: open.n,v 1.30 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH open n 8.3 Tcl "Tcl Built-In Commands" 12 12 .BS 13 -.\" Note: do not modify the .SH NAME line immediately below! 13 +'\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 open \- Open a file-based or command pipeline channel 16 16 .SH SYNOPSIS 17 17 .sp 18 18 \fBopen \fIfileName\fR 19 19 .br 20 20 \fBopen \fIfileName access\fR ................................................................................ 62 62 create a new empty file. 63 63 Set the initial access position to the end of the file. 64 64 .VS 8.5 65 65 .PP 66 66 All of the legal \fIaccess\fR values above may have the character 67 67 \fBb\fR added as the second or third character in the value to 68 68 indicate that the opened channel should be configured with the 69 -\fB\-translation binary\fR option, making the channel suitable for 69 +\fB-translation binary\fR option, making the channel suitable for 70 70 reading or writing of binary data. 71 71 .VE 8.5 72 72 .PP 73 73 In the second form, \fIaccess\fR consists of a list of any of the 74 74 following flags, all of which have the standard POSIX meanings. 75 75 One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR. 76 76 .TP 15 ................................................................................ 84 84 Open the file for both reading and writing. 85 85 .TP 15 86 86 \fBAPPEND\fR 87 87 Set the file pointer to the end of the file prior to each write. 88 88 .VS 8.5 89 89 .TP 15 90 90 \fBBINARY\fR 91 -Configure the opened channel with the \fB\-translation binary\fR option. 91 +Configure the opened channel with the \fB-translation binary\fR option. 92 92 .VE 8.5 93 93 .TP 15 94 94 \fBCREAT\fR 95 95 Create the file if it doesn't already exist (without this flag it 96 96 is an error for the file not to exist). 97 97 .TP 15 98 98 \fBEXCL\fR ................................................................................ 115 115 \fBTRUNC\fR 116 116 If the file exists it is truncated to zero length. 117 117 .PP 118 118 If a new file is created as part of opening it, \fIpermissions\fR 119 119 (an integer) is used to set the permissions for the new file in 120 120 conjunction with the process's file mode creation mask. 121 121 \fIPermissions\fR defaults to 0666. 122 + 122 123 .SH "COMMAND PIPELINES" 123 124 .PP 124 -If the first character of \fIfileName\fR is 125 -.QW | 126 -then the remaining characters of \fIfileName\fR are treated as a list of 127 -arguments that describe a command pipeline to invoke, in the same style as the 125 +If the first character of \fIfileName\fR is ``|'' then the 126 +remaining characters of \fIfileName\fR are treated as a list of arguments 127 +that describe a command pipeline to invoke, in the same style as the 128 128 arguments for \fBexec\fR. 129 129 In this case, the channel identifier returned by \fBopen\fR may be used 130 130 to write to the command's input pipe or read from its output pipe, 131 131 depending on the value of \fIaccess\fR. 132 132 If write-only access is used (e.g. \fIaccess\fR is \fBw\fR), then 133 133 standard output for the pipeline is directed to the current standard 134 134 output unless overridden by the command. ................................................................................ 158 158 configuration options specific to serial ports (where supported): 159 159 .TP 160 160 \fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR 161 161 This option is a set of 4 comma-separated values: the baud rate, parity, 162 162 number of data bits, and number of stop bits for this serial port. The 163 163 \fIbaud\fR rate is a simple integer that specifies the connection speed. 164 164 \fIParity\fR is one of the following letters: \fBn\fR, \fBo\fR, \fBe\fR, 165 -\fBm\fR, \fBs\fR; respectively signifying the parity options of 166 -.QW none , 167 -.QW odd , 168 -.QW even , 169 -.QW mark , 170 -or 171 -.QW space . 172 -\fIData\fR is the number of data bits and should be an integer from 5 to 8, 173 -while \fIstop\fR is the number of stop bits and should be the integer 1 or 2. 165 +\fBm\fR, \fBs\fR; respectively signifying the parity options of ``none'', 166 +``odd'', ``even'', ``mark'', or ``space''. \fIData\fR is the number of 167 +data bits and should be an integer from 5 to 8, while \fIstop\fR is the 168 +number of stop bits and should be the integer 1 or 2. 174 169 .TP 175 170 \fB\-handshake\fR \fItype\fR 176 171 (Windows and Unix). This option is used to setup automatic handshake 177 172 control. Note that not all handshake types maybe supported by your operating 178 173 system. The \fItype\fR parameter is case-independent. 179 174 .sp 180 175 If \fItype\fR is \fBnone\fR then any handshake is switched off. 181 176 \fBrtscts\fR activates hardware handshake. Hardware handshake signals 182 177 are described below. 183 178 For software handshake \fBxonxoff\fR the handshake characters can be redefined 184 -with \fB\-xchar\fR. 179 +with \fB-xchar\fR. 185 180 An additional hardware handshake \fBdtrdsr\fR is available only under Windows. 186 181 There is no default handshake configuration, the initial value depends 187 182 on your operating system settings. 188 -The \fB\-handshake\fR option cannot be queried. 183 +The \fB-handshake\fR option cannot be queried. 189 184 .TP 190 185 \fB\-queue\fR 191 -(Windows and Unix). The \fB\-queue\fR option can only be queried. 186 +(Windows and Unix). The \fB-queue\fR option can only be queried. 192 187 It returns a list of two integers representing the current number 193 188 of bytes in the input and output queue respectively. 194 189 .TP 195 190 \fB\-timeout\fR \fImsec\fR 196 191 (Windows and Unix). This option is used to set the timeout for blocking 197 192 read operations. It specifies the maximum interval between the 198 193 reception of two bytes in milliseconds. 199 194 For Unix systems the granularity is 100 milliseconds. 200 -The \fB\-timeout\fR option does not affect write operations or 195 +The \fB-timeout\fR option does not affect write operations or 201 196 nonblocking reads. 202 197 This option cannot be queried. 203 198 .TP 204 199 \fB\-ttycontrol\fR \fI{signal boolean signal boolean ...}\fR 205 200 (Windows and Unix). This option is used to setup the handshake 206 201 output lines (see below) permanently or to send a BREAK over the serial line. 207 202 The \fIsignal\fR names are case-independent. 208 203 \fB{RTS 1 DTR 0}\fR sets the RTS output to high and the DTR output to low. 209 204 The BREAK condition (see below) is enabled and disabled with \fB{BREAK 1}\fR and 210 205 \fB{BREAK 0}\fR respectively. 211 206 It's not a good idea to change the \fBRTS\fR (or \fBDTR\fR) signal 212 207 with active hardware handshake \fBrtscts\fR (or \fBdtrdsr\fR). 213 208 The result is unpredictable. 214 -The \fB\-ttycontrol\fR option cannot be queried. 209 +The \fB-ttycontrol\fR option cannot be queried. 215 210 .TP 216 211 \fB\-ttystatus\fR 217 -(Windows and Unix). The \fB\-ttystatus\fR option can only be 212 +(Windows and Unix). The \fB-ttystatus\fR option can only be 218 213 queried. It returns the current modem status and handshake input signals 219 214 (see below). 220 215 The result is a list of signal,value pairs with a fixed order, 221 216 e.g. \fB{CTS 1 DSR 0 RING 1 DCD 0}\fR. 222 217 The \fIsignal\fR names are returned upper case. 223 218 .TP 224 219 \fB\-xchar\fR \fI{xonChar xoffChar}\fR ................................................................................ 246 241 .TP 247 242 \fB\-lasterror\fR 248 243 (Windows only). This option is query only. 249 244 In case of a serial communication error, \fBread\fR or \fBputs\fR 250 245 returns a general Tcl file I/O error. 251 246 \fBfconfigure -lasterror\fR can be called to get a list of error details. 252 247 See below for an explanation of the various error codes. 248 + 253 249 .SH "SERIAL PORT SIGNALS" 254 250 .PP 255 251 RS-232 is the most commonly used standard electrical interface for serial 256 252 communications. A negative voltage (-3V..-12V) define a mark (on=1) bit and 257 253 a positive voltage (+3..+12V) define a space (off=0) bit (RS-232C). The 258 254 following signals are specified for incoming and outgoing data, status 259 255 lines and handshaking. Here we are using the terms \fIworkstation\fR for ................................................................................ 276 272 \fBData Terminal Ready:\fR This signal tells the modem that the workstation 277 273 is ready to establish a link. DTR is often enabled automatically whenever a 278 274 serial port is opened. 279 275 .IP \fBDSR(input)\fR 280 276 \fBData Set Ready:\fR The complement to DTR. Tells the workstation that the 281 277 modem is ready to establish a link. 282 278 .IP \fBDCD(input)\fR 283 -\fBData Carrier Detect:\fR This line becomes active when a modem detects a 284 -.QW Carrier 285 -signal. 279 +\fBData Carrier Detect:\fR This line becomes active when a modem detects 280 +a "Carrier" signal. 286 281 .IP \fBRI(input)\fR 287 282 \fBRing Indicator:\fR Goes active when the modem detects an incoming call. 288 283 .IP \fBBREAK\fR 289 284 A BREAK condition is not a hardware signal line, but a logical zero on the 290 285 TXD or RXD lines for a long period of time, usually 250 to 500 291 286 milliseconds. Normally a receive or transmit data signal stays at the mark 292 287 (on=1) voltage until the next character is transferred. A BREAK is sometimes 293 288 used to reset the communications line or change the operating mode of 294 289 communications hardware. 290 + 295 291 .SH "ERROR CODES (Windows only)" 296 292 .PP 297 293 A lot of different errors may occur during serial read operations or during 298 294 event polling in background. The external device may have been switched 299 295 off, the data lines may be noisy, system buffers may overrun or your mode 300 296 settings may be wrong. That's why a reliable software should always 301 297 \fBcatch\fR serial read operations. In cases of an error Tcl returns a ................................................................................ 326 322 \fBFRAME\fR 327 323 A stop-bit error has been detected by your UART. 328 324 Wrong mode settings with \fBfconfigure -mode\fR or a noisy data line (RXD) 329 325 may cause this error. 330 326 .TP 10 331 327 \fBBREAK\fR 332 328 A BREAK condition has been detected by your UART (see above). 329 + 333 330 .SH "PORTABILITY ISSUES" 334 331 .TP 335 332 \fBWindows \fR(all versions) 336 -. 337 333 Valid values for \fIfileName\fR to open a serial port are of the form 338 334 \fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4. 339 335 This notation only works for serial ports from 1 to 9, if the system 340 336 happens to have more than four. An attempt to open a serial port that 341 337 does not exist or has a number greater than 9 will fail. An alternate 342 338 form of opening serial ports is to use the filename \fB\e\e.\ecomX\fR, 343 339 where X is any number that corresponds to a serial port; please note 344 340 that this method is considerably slower on Windows 95 and Windows 98. 345 341 .TP 346 342 \fBWindows NT\fR 347 -. 348 343 When running Tcl interactively, there may be some strange interactions 349 344 between the real console, if one is present, and a command pipeline that uses 350 345 standard input or output. If a command pipeline is opened for reading, some 351 346 of the lines entered at the console will be sent to the command pipeline and 352 347 some will be sent to the Tcl evaluator. If a command pipeline is opened for 353 348 writing, keystrokes entered into the console are not visible until the 354 349 pipe is closed. This behavior occurs whether the command pipeline is ................................................................................ 355 350 executing 16-bit or 32-bit applications. These problems only occur because 356 351 both Tcl and the child application are competing for the console at 357 352 the same time. If the command pipeline is started from a script, so that Tcl 358 353 is not accessing the console, or if the command pipeline does not use 359 354 standard input or output, but is redirected from or to a file, then the 360 355 above problems do not occur. 361 356 .TP 362 -\fBWindows 95\fR 363 -. 357 +\fBWindows 95\fR 364 358 A command pipeline that executes a 16-bit DOS application cannot be opened 365 359 for both reading and writing, since 16-bit DOS applications that receive 366 360 standard input from a pipe and send standard output to a pipe run 367 361 synchronously. Command pipelines that do not execute 16-bit DOS 368 362 applications run asynchronously and can be opened for both reading and 369 363 writing. 370 -.RS 371 -.PP 364 +.sp 372 365 When running Tcl interactively, there may be some strange interactions 373 366 between the real console, if one is present, and a command pipeline that uses 374 367 standard input or output. If a command pipeline is opened for reading from 375 368 a 32-bit application, some of the keystrokes entered at the console will be 376 369 sent to the command pipeline and some will be sent to the Tcl evaluator. If 377 370 a command pipeline is opened for writing to a 32-bit application, no output 378 371 is visible on the console until the pipe is closed. These problems only 379 372 occur because both Tcl and the child application are competing for the 380 373 console at the same time. If the command pipeline is started from a script, 381 374 so that Tcl is not accessing the console, or if the command pipeline does 382 375 not use standard input or output, but is redirected from or to a file, then 383 376 the above problems do not occur. 384 -.PP 377 +.sp 385 378 Whether or not Tcl is running interactively, if a command pipeline is opened 386 379 for reading from a 16-bit DOS application, the call to \fBopen\fR will not 387 380 return until end-of-file has been received from the command pipeline's 388 381 standard output. If a command pipeline is opened for writing to a 16-bit DOS 389 382 application, no data will be sent to the command pipeline's standard output 390 383 until the pipe is actually closed. This problem occurs because 16-bit DOS 391 384 applications are run synchronously, as described above. 392 -.RE 393 385 .TP 394 386 \fBUnix\fR\0\0\0\0\0\0\0 395 -. 396 387 Valid values for \fIfileName\fR to open a serial port are generally of the 397 388 form \fB/dev/tty\fIX\fR, where \fIX\fR is \fBa\fR or \fBb\fR, but the name 398 389 of any pseudo-file that maps to a serial port may be used. 399 390 Advanced configuration options are only supported for serial ports 400 391 when Tcl is built to use the POSIX serial interface. 401 -.RS 402 -.PP 392 +.sp 403 393 When running Tcl interactively, there may be some strange interactions 404 394 between the console, if one is present, and a command pipeline that uses 405 395 standard input. If a command pipeline is opened for reading, some 406 396 of the lines entered at the console will be sent to the command pipeline and 407 397 some will be sent to the Tcl evaluator. This problem only occurs because 408 398 both Tcl and the child application are competing for the console at the 409 399 same time. If the command pipeline is started from a script, so that Tcl is 410 400 not accessing the console, or if the command pipeline does not use standard 411 401 input, but is redirected from a file, then the above problem does not occur. 412 -.RE 413 402 .LP 414 403 See the PORTABILITY ISSUES section of the \fBexec\fR command for additional 415 404 information not specific to command pipelines about executing 416 405 applications on the various platforms 417 406 .SH "EXAMPLE" 418 407 Open a command pipeline and catch any errors: 419 408 .CS 420 409 set fl [\fBopen\fR "| ls this_file_does_not_exist"] 421 410 set data [read $fl] 422 411 if {[catch {close $fl} err]} { 423 412 puts "ls command failed: $err" 424 413 } 425 414 .CE 415 + 426 416 .SH "SEE ALSO" 427 -chan(n), close(n), exec(n), fconfigure(n), file(n), filename(n), gets(n), 428 -pid(n), puts(n), read(n), fopen(3) 417 +file(n), close(n), filename(n), fconfigure(n), gets(n), read(n), 418 +puts(n), exec(n), pid(n), fopen(3) 419 + 429 420 .SH KEYWORDS 430 421 access mode, append, create, file, non-blocking, open, permissions, 431 422 pipeline, process, serial
Changes to doc/package.n.
1 1 '\" 2 2 '\" Copyright (c) 1996 Sun Microsystems, Inc. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: package.n,v 1.19 2007/10/25 10:13:35 dkf Exp $ 7 +'\" RCS: @(#) $Id: package.n,v 1.20 2007/10/26 20:11:53 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH package n 7.5 Tcl "Tcl Built-In Commands" 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 package \- Facilities for package loading and version control ................................................................................ 25 25 \fBpackage unknown \fR?\fIcommand\fR? 26 26 \fBpackage vcompare \fIversion1 version2\fR 27 27 \fBpackage versions \fIpackage\fR 28 28 \fBpackage vsatisfies \fIversion requirement...\fR 29 29 \fBpackage prefer \fR?\fBlatest\fR|\fBstable\fR? 30 30 .fi 31 31 .BE 32 + 32 33 .SH DESCRIPTION 33 34 .PP 34 35 This command keeps a simple database of the packages available for 35 36 use by the current interpreter and how to load them into the 36 37 interpreter. 37 38 It supports multiple versions of each package and arranges 38 39 for the correct version of a package to be loaded based on what ................................................................................ 105 106 .PP 106 107 A suitable version of the package is any version which satisfies at 107 108 least one of the requirements, per the rules of \fBpackage 108 109 vsatisfies\fR. If multiple versions are suitable the implementation 109 110 with the highest version is chosen. This last part is additionally 110 111 influenced by the selection mode set with \fBpackage prefer\fR. 111 112 .PP 112 -In the 113 -.QW "stable" 114 -selection mode the command will select the highest 113 +In the "stable" selection mode the command will select the highest 115 114 stable version satisfying the requirements, if any. If no stable 116 115 version satisfies the requirements, the highest unstable version 117 -satisfying the requirements will be selected. In the 118 -.QW "latest" 116 +satisfying the requirements will be selected. In the "latest" 119 117 selection mode the command will accept the highest version satisfying 120 118 all the requirements, regardless of its stableness. 121 119 .PP 122 120 If a version of \fIpackage\fR has already been provided (by invoking 123 121 the \fBpackage provide\fR command), then its version number must 124 122 satisfy the \fIrequirement\fRs and the command returns immediately. 125 123 Otherwise, the command searches the database of information provided by ................................................................................ 141 139 .TP 142 140 \fBpackage require \-exact \fIpackage version\fR 143 141 This form of the command is used when only the given \fIversion\fR 144 142 of \fIpackage\fR is acceptable to the caller. This command is 145 143 equivalent to \fBpackage require \fIpackage version\fR-\fIversion\fR. 146 144 .TP 147 145 \fBpackage unknown \fR?\fIcommand\fR? 148 -. 149 -This command supplies a 150 -.QW "last resort" 151 -command to invoke during 146 +This command supplies a ``last resort'' command to invoke during 152 147 \fBpackage require\fR if no suitable version of a package can be found 153 148 in the \fBpackage ifneeded\fR database. 154 149 If the \fIcommand\fR argument is supplied, it contains the first part 155 150 of a command; when the command is invoked during a \fBpackage require\fR 156 151 command, Tcl appends one or more additional arguments giving the desired 157 152 package name and requirements. 158 153 For example, if \fIcommand\fR is \fBfoo bar\fR and later the command ................................................................................ 179 174 \fBpackage vsatisfies \fIversion requirement...\fR 180 175 Returns 1 if the \fIversion\fR satisfies at least one of the given 181 176 requirements, and 0 otherwise. Each \fIrequirement\fR is allowed to 182 177 have any of the forms: 183 178 .RS 184 179 .TP 185 180 min 186 -This form is called 187 -.QW "min-bounded" . 181 +This form is called "min-bounded". 188 182 .TP 189 183 min- 190 -This form is called 191 -.QW "min-unbound" . 184 +This form is called "min-unbound". 192 185 .TP 193 186 min-max 194 -This form is called 195 -.QW "bounded" . 187 +This form is called "bounded". 196 188 .RE 197 189 .RS 198 190 .PP 199 -where 200 -.QW "min" 201 -and 202 -.QW "max" 203 -are valid version numbers. The legacy syntax is 191 +where "min" and "max" are valid version numbers. The legacy syntax is 204 192 a special case of the extended syntax, keeping backward 205 193 compatibility. Regarding satisfaction the rules are: 206 194 .RE 207 195 .RS 208 196 .IP [1] 209 197 The \fIversion\fR has to pass at least one of the listed 210 198 \fIrequirement\fRs to be satisfactory. 211 199 .IP [2] 212 -A version satisfies a 213 -.QW "bounded" 214 -requirement when 200 +A version satisfies a "bounded" requirement when 215 201 .RS 216 202 .IP [a] 217 203 For \fImin\fR equal to the \fImax\fR if, and only if the \fIversion\fR 218 204 is equal to the \fImin\fR. 219 205 .IP [b] 220 206 Otherwise if, and only if the \fIversion\fR is greater than or equal 221 207 to the \fImin\fR, and less than the \fImax\fR, where both \fImin\fR 222 -and \fImax\fR have been padded internally with 223 -.QW a0 . 224 -Note that while the comparison to \fImin\fR is inclusive, the comparison to 208 +and \fImax\fR have been padded internally with 'a0'. Note that while 209 +the comparison to \fImin\fR is inclusive, the comparison to 225 210 \fImax\fR is exclusive. 226 211 .RE 227 212 .IP [3] 228 -A 229 -.QW "min-bounded" 230 -requirement is a 231 -.QW "bounded" 232 -requirement in disguise, 213 +A "min-bounded" requirement is a "bounded" requirement in disguise, 233 214 with the \fImax\fR part implicitly specified as the next higher major 234 215 version number of the \fImin\fR part. A version satisfies it per the 235 216 rules above. 236 217 .IP [4] 237 -A \fIversion\fR satisfies a 238 -.QW "min-unbound" 239 -requirement if, and only if 218 +A \fIversion\fR satisfies a "min-unbound" requirement if, and only if 240 219 it is greater than or equal to the \fImin\fR, where the \fImin\fR has 241 -been padded internally with 242 -.QW a0 . 243 -There is no constraint to a maximum. 220 +been padded internally with 'a0'. There is no constraint to a maximum. 244 221 .RE 245 222 .TP 246 223 \fBpackage prefer \fR?\fBlatest\fR|\fBstable\fR? 247 -With no arguments, the commands returns either 248 -.QW "latest" 249 -or 250 -.QW "stable" , 224 +With no arguments, the commands returns either "latest" or "stable", 251 225 whichever describes the current mode of selection logic used by 252 226 \fBpackage require\fR. 253 227 .RS 254 228 .PP 255 -When passed the argument 256 -.QW "latest" , 257 -it sets the selection logic mode to 258 -.QW "latest" . 229 +When passed the argument "latest", it sets the selection logic mode to 230 +"latest". 259 231 .PP 260 -When passed the argument 261 -.QW "stable" , 262 -if the mode is already 263 -.QW "stable" , 264 -that value is kept. If the mode is already 265 -.QW "latest" , then the attempt to set it back to 266 -.QW "stable" 267 -is ineffective and the mode value remains 268 -.QW "latest" . 232 +When passed the argument "stable", if the mode is already "stable", 233 +that value is kept. If the mode is already "latest", then the attempt 234 +to set it back to "stable" is ineffective and the mode value remains 235 +"latest". 269 236 .PP 270 237 When passed any other value as an argument, raise an invalid argument 271 238 error. 272 239 .PP 273 240 When an interpreter is created, its initial selection mode value is set to 274 -.QW "stable" 275 -unless the environment variable \fBTCL_PKG_PREFER_LATEST\fR 241 +"stable" unless the environment variable \fBTCL_PKG_PREFER_LATEST\fR 276 242 is set. If that environment variable is defined (with any value) then 277 -the initial (and permanent) selection mode value is set to 278 -.QW "latest" . 243 +the initial (and permanent) selection mode value is set to "latest". 279 244 .RE 280 245 .SH "VERSION NUMBERS" 281 246 .PP 282 247 Version numbers consist of one or more decimal numbers separated 283 248 by dots, such as 2 or 1.162 or 3.1.13.1. 284 249 The first number is called the major version number. 285 250 Larger numbers correspond to later versions of a package, with 286 251 leftmost numbers having greater significance. 287 252 For example, version 2.1 is later than 1.3 and version 288 253 3.4.6 is later than 3.3.5. 289 254 Missing fields are equivalent to zeroes: version 1.3 is the 290 255 same as version 1.3.0 and 1.3.0.0, so it is earlier than 1.3.1 or 1.3.0.2. 291 -In addition, the letters 292 -.QW a 293 -(alpha) and/or 294 -.QW b 295 -(beta) may appear 256 +In addition, the letters 'a' (alpha) and/or 'b' (beta) may appear 296 257 exactly once to replace a dot for separation. These letters 297 -semantically add a negative specifier into the version, where 298 -.QW a 299 -is -2, and 300 -.QW b 301 -is -1. Each may be specified only once, and 302 -.QW a 303 -and 304 -.QW b 305 -are mutually exclusive in a specifier. Thus 1.3a1 becomes (semantically) 258 +semantically add a negative specifier into the version, where 'a' is 259 +-2, and 'b' is -1. Each may be specified only once, and 'a' or 'b' are 260 +mutually exclusive in a specifier. Thus 1.3a1 becomes (semantically) 306 261 1.3.-2.1, 1.3b1 is 1.3.-1.1. Negative numbers are not directly allowed 307 262 in version specifiers. 308 -A version number not containing the letters 309 -.QW a 310 -or 311 -.QW b 312 -as specified above is called a \fBstable\fR version, whereas presence 313 -of the letters causes the version to be called is \fBunstable\fR. 263 +A version number not containing the letters 'a' or 'b' as specified 264 +above is called a \fBstable\fR version, whereas presence of the letters 265 +causes the version to be called is \fBunstable\fR. 314 266 A later version number is assumed to be upwards compatible with 315 267 an earlier version number as long as both versions have the same 316 268 major version number. 317 269 For example, Tcl scripts written for version 2.3 of a package should 318 270 work unchanged under versions 2.3.2, 2.4, and 2.5.1. 319 271 Changes in the major version number signify incompatible changes: 320 272 if code is written to use version 2.1 of a package, it is not guaranteed 321 273 to work unmodified with either version 1.7.3 or version 3.1. 322 274 .SH "PACKAGE INDICES" 323 275 .PP 324 276 The recommended way to use packages in Tcl is to invoke \fBpackage require\fR 325 277 and \fBpackage provide\fR commands in scripts, and use the procedure 326 278 \fBpkg_mkIndex\fR to create package index files. 327 -Once you have done this, packages will be loaded automatically 279 +Once you've done this, packages will be loaded automatically 328 280 in response to \fBpackage require\fR commands. 329 281 See the documentation for \fBpkg_mkIndex\fR for details. 330 282 .SH EXAMPLES 331 283 To state that a Tcl script requires the Tk and http packages, put this 332 284 at the top of the script: 333 285 .CS 334 286 \fBpackage require\fR Tk ................................................................................ 342 294 if {[catch {\fBpackage require\fR Snack}]} { 343 295 # Error thrown - package not found. 344 296 # Set up a dummy interface to work around the absence 345 297 } else { 346 298 # We have the package, configure the app to use it 347 299 } 348 300 .CE 301 + 349 302 .SH "SEE ALSO" 350 303 msgcat(n), packagens(n), pkgMkIndex(n) 304 + 351 305 .SH KEYWORDS 352 306 package, version
Changes to doc/packagens.n.
1 1 '\" 2 2 '\" Copyright (c) 1998-2000 by Scriptics Corporation. 3 3 '\" All rights reserved. 4 4 '\" 5 -'\" RCS: @(#) $Id: packagens.n,v 1.6 2007/10/24 14:29:38 dkf Exp $ 5 +'\" RCS: @(#) $Id: packagens.n,v 1.7 2007/10/26 20:11:53 dgp Exp $ 6 6 '\" 7 7 .so man.macros 8 8 .TH pkg::create n 8.3 Tcl "Tcl Built-In Commands" 9 9 .BS 10 10 '\" Note: do not modify the .SH NAME line immediately below! 11 11 .SH NAME 12 12 pkg::create \- Construct an appropriate `package ifneeded' command for a given package specification ................................................................................ 16 16 17 17 .SH DESCRIPTION 18 18 .PP 19 19 \fB::pkg::create\fR is a utility procedure that is part of the standard Tcl 20 20 library. It is used to create an appropriate \fBpackage ifneeded\fR 21 21 command for a given package specification. It can be used to construct a 22 22 \fBpkgIndex.tcl\fR file for use with the \fBpackage\fR mechanism. 23 + 23 24 .SH OPTIONS 24 25 The parameters supported are: 25 26 .TP 26 27 \fB\-name\fR\0\fIpackageName\fR 27 28 This parameter specifies the name of the package. It is required. 28 29 .TP 29 30 \fB\-version\fR\0\fIpackageVersion\fR ................................................................................ 41 42 \fB\-source\fR\0\fIfilespec\fR 42 43 This parameter is similar to the \fB\-load\fR parameter, except that it 43 44 specifies a Tcl library that must be loaded with the 44 45 \fBsource\fR command. Any number of \fB\-source\fR parameters may be 45 46 specified. 46 47 .PP 47 48 At least one \fB\-load\fR or \fB\-source\fR parameter must be given. 49 + 48 50 .SH "SEE ALSO" 49 51 package(n) 52 + 50 53 .SH KEYWORDS 51 54 auto-load, index, package, version
Changes to doc/pkgMkIndex.n.
1 1 '\" 2 2 '\" Copyright (c) 1996 Sun Microsystems, Inc. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.19 2007/10/24 14:29:38 dkf Exp $ 7 +'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.20 2007/10/26 20:11:53 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH pkg_mkIndex n 8.3 Tcl "Tcl Built-In Commands" 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 pkg_mkIndex \- Build an index for automatic loading of packages ................................................................................ 36 36 a call to \fBTcl_PkgProvide\fR. 37 37 .IP [2] 38 38 Create the index by invoking \fBpkg_mkIndex\fR. 39 39 The \fIdir\fR argument gives the name of a directory and each 40 40 \fIpattern\fR argument is a \fBglob\fR-style pattern that selects 41 41 script or binary files in \fIdir\fR. 42 42 The default pattern is \fB*.tcl\fR and \fB*.[info sharedlibextension]\fR. 43 -.RS 44 -.PP 43 +.br 45 44 \fBPkg_mkIndex\fR will create a file \fBpkgIndex.tcl\fR in \fIdir\fR 46 45 with package information about all the files given by the \fIpattern\fR 47 46 arguments. 48 47 It does this by loading each file into a slave 49 48 interpreter and seeing what packages 50 49 and new commands appear (this is why it is essential to have 51 50 \fBpackage provide\fR commands or \fBTcl_PkgProvide\fR calls 52 51 in the files, as described above). 53 52 If you have a package split among scripts and binary files, 54 53 or if you have dependencies among files, 55 54 you may have to use the \fB\-load\fR option 56 55 or adjust the order in which \fBpkg_mkIndex\fR processes 57 56 the files. See COMPLEX CASES below. 58 -.RE 57 + 59 58 .IP [3] 60 59 Install the package as a subdirectory of one of the directories given by 61 60 the \fBtcl_pkgPath\fR variable. If \fB$tcl_pkgPath\fR contains more 62 61 than one directory, machine-dependent packages (e.g., those that 63 62 contain binary shared libraries) should normally be installed 64 63 under the first directory and machine-independent packages (e.g., 65 64 those that contain only Tcl scripts) should be installed under the 66 65 second directory. 67 66 The subdirectory should include 68 67 the package's script and/or binary files as well as the \fBpkgIndex.tcl\fR 69 68 file. As long as the package is installed as a subdirectory of a 70 69 directory in \fB$tcl_pkgPath\fR it will automatically be found during 71 70 \fBpackage require\fR commands. 72 -.RS 73 -.PP 71 +.br 74 72 If you install the package anywhere else, then you must ensure that 75 73 the directory containing the package is in the \fBauto_path\fR global variable 76 74 or an immediate subdirectory of one of the directories in \fBauto_path\fR. 77 75 \fBAuto_path\fR contains a list of directories that are searched 78 76 by both the auto-loader and the package loader; by default it 79 77 includes \fB$tcl_pkgPath\fR. 80 78 The package loader also checks all of the subdirectories of the 81 79 directories in \fBauto_path\fR. 82 80 You can add a directory to \fBauto_path\fR explicitly in your 83 81 application, or you can add the directory to your \fBTCLLIBPATH\fR 84 82 environment variable: if this environment variable is present, 85 83 Tcl initializes \fBauto_path\fR from it during application startup. 86 -.RE 87 84 .IP [4] 88 85 Once the above steps have been taken, all you need to do to use a 89 86 package is to invoke \fBpackage require\fR. 90 87 For example, if versions 2.1, 2.3, and 3.1 of package \fBTest\fR 91 88 have been indexed by \fBpkg_mkIndex\fR, the command 92 89 \fBpackage require Test\fR will make version 3.1 available 93 90 and the command \fBpackage require \-exact Test 2.1\fR will 94 91 make version 2.1 available. 95 92 There may be many versions of a package in the various index files 96 93 in \fBauto_path\fR, but only one will actually be loaded in a given 97 94 interpreter, based on the first call to \fBpackage require\fR. 98 95 Different versions of a package may be loaded in different 99 96 interpreters. 97 + 100 98 .SH OPTIONS 101 99 The optional switches are: 102 100 .TP 15 103 101 \fB\-direct\fR 104 102 The generated index will implement direct loading of the package 105 103 upon \fBpackage require\fR. This is the default. 106 104 .TP 15 ................................................................................ 119 117 .TP 15 120 118 \fB\-verbose\fR 121 119 Generate output during the indexing process. Output is via 122 120 the \fBtclLog\fR procedure, which by default prints to stderr. 123 121 .TP 15 124 122 \fB\-\-\fR 125 123 End of the flags, in case \fIdir\fR begins with a dash. 124 + 126 125 .SH "PACKAGES AND THE AUTO-LOADER" 127 126 .PP 128 127 The package management facilities overlap somewhat with the auto-loader, 129 128 in that both arrange for files to be loaded on-demand. 130 129 However, package management is a higher-level mechanism that uses 131 130 the auto-loader for the last step in the loading process. 132 131 It is generally better to index a package with \fBpkg_mkIndex\fR ................................................................................ 138 137 it can only handle a single version of each package. 139 138 It is probably not a good idea to index a given package with both 140 139 \fBpkg_mkIndex\fR and \fBauto_mkindex\fR. 141 140 If you use \fBpkg_mkIndex\fR to index a package, its commands cannot 142 141 be invoked until \fBpackage require\fR has been used to select a 143 142 version; in contrast, packages indexed with \fBauto_mkindex\fR 144 143 can be used immediately since there is no version control. 144 + 145 145 .SH "HOW IT WORKS" 146 146 .PP 147 147 \fBPkg_mkIndex\fR depends on the \fBpackage unknown\fR command, 148 148 the \fBpackage ifneeded\fR command, and the auto-loader. 149 149 The first time a \fBpackage require\fR command is invoked, 150 150 the \fBpackage unknown\fR script is invoked. 151 151 This is set by Tcl initialization to a script that ................................................................................ 160 160 was generated, 161 161 a given file of a given version of a given package isn't 162 162 actually loaded until the first time one of its commands 163 163 is invoked. 164 164 Thus, after invoking \fBpackage require\fR you may 165 165 not see the package's commands in the interpreter, but you will be able 166 166 to invoke the commands and they will be auto-loaded. 167 + 167 168 .SH "DIRECT LOADING" 168 169 .PP 169 170 Some packages, for instance packages which use namespaces and export 170 171 commands or those which require special initialization, might select 171 172 that their package files be loaded immediately upon \fBpackage require\fR 172 173 instead of delaying the actual loading to the first use of one of the 173 174 package's command. This is the default mode when generating the package 174 175 index. It can be overridden by specifying the \fI\-lazy\fR argument. 176 + 175 177 .SH "COMPLEX CASES" 176 178 Most complex cases of dependencies among scripts 177 179 and binary files, and packages being split among scripts and 178 180 binary files are handled OK. However, you may have to adjust 179 181 the order in which files are processed by \fBpkg_mkIndex\fR. 180 182 These issues are described in detail below. 181 183 .PP ................................................................................ 223 225 If you have a package that is split across scripts and a binary file, 224 226 then you should avoid the \fB\-load\fR flag. The problem is that 225 227 if you load a package before computing the index it masks any 226 228 other files that provide part of the same package. 227 229 If you must use \fB\-load\fR, 228 230 then you must specify the scripts first; otherwise the package loaded from 229 231 the binary file may mask the package defined by the scripts. 232 + 230 233 .SH "SEE ALSO" 231 234 package(n) 235 + 232 236 .SH KEYWORDS 233 237 auto-load, index, package, version
Changes to doc/re_syntax.n.
1 1 '\" 2 2 '\" Copyright (c) 1998 Sun Microsystems, Inc. 3 3 '\" Copyright (c) 1999 Scriptics Corporation 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: re_syntax.n,v 1.12 2007/10/26 12:25:06 dkf Exp $ 8 +'\" RCS: @(#) $Id: re_syntax.n,v 1.13 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH re_syntax n "8.1" Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 .SH NAME 14 14 re_syntax \- Syntax of Tcl regular expressions 15 15 .BE 16 16 17 17 .SH DESCRIPTION 18 18 .PP 19 19 A \fIregular expression\fR describes strings of characters. 20 20 It's a pattern that matches certain strings and doesn't match others. 21 21 .SH "DIFFERENT FLAVORS OF REs" 22 -Regular expressions 23 -.PQ RE s , 24 -as defined by POSIX, come in two flavors: \fIextended\fR REs 25 -.PQ ERE s 26 -and \fIbasic\fR REs 27 -.PQ BRE s . 22 +Regular expressions (``RE''s), as defined by POSIX, come in two 23 +flavors: \fIextended\fR REs (``EREs'') and \fIbasic\fR REs (``BREs''). 28 24 EREs are roughly those of the traditional \fIegrep\fR, while BREs are 29 25 roughly those of the traditional \fIed\fR. This implementation adds 30 -a third flavor, \fIadvanced\fR REs 31 -.PQ ARE s , 32 -basically EREs with some significant extensions. 26 +a third flavor, \fIadvanced\fR REs (``AREs''), basically EREs with 27 +some significant extensions. 33 28 .PP 34 29 This manual page primarily describes AREs. BREs mostly exist for 35 30 backward compatibility in some old programs; they will be discussed at 36 31 the end. POSIX EREs are almost an exact subset of AREs. Features of 37 32 AREs that are not present in EREs will be indicated. 38 33 .SH "REGULAR EXPRESSION SYNTAX" 39 34 .PP 40 35 Tcl regular expressions are implemented using the package written by 41 36 Henry Spencer, based on the 1003.2 spec and some (not quite all) of 42 37 the Perl5 extensions (thanks, Henry!). Much of the description of 43 38 regular expressions below is copied verbatim from his manual entry. 44 39 .PP 45 40 An ARE is one or more \fIbranches\fR, 46 -separated by 47 -.QW \fB|\fR , 41 +separated by `\fB|\fR', 48 42 matching anything that matches any of the branches. 49 43 .PP 50 44 A branch is zero or more \fIconstraints\fR or \fIquantified atoms\fR, 51 45 concatenated. 52 46 It matches a match for the first, followed by a match for the second, etc; 53 47 an empty branch matches the empty string. 54 48 .PP ................................................................................ 91 85 .PP 92 86 An atom is one of: 93 87 .RS 2 94 88 .IP \fB(\fIre\fB)\fR 6 95 89 matches a match for \fIre\fR (\fIre\fR is any regular expression) with 96 90 the match noted for possible reporting 97 91 .IP \fB(?:\fIre\fB)\fR 98 -as previous, but does no reporting (a 99 -.QW non-capturing 100 -set of parentheses) 92 +as previous, but does no reporting (a ``non-capturing'' set of 93 +parentheses) 101 94 .IP \fB()\fR 102 95 matches an empty string, noted for possible reporting 103 96 .IP \fB(?:)\fR 104 97 matches an empty string, without reporting 105 98 .IP \fB[\fIchars\fB]\fR 106 99 a \fIbracket expression\fR, matching any one of the \fIchars\fR (see 107 100 \fBBRACKET EXPRESSIONS\fR for more detail) 108 101 .IP \fB.\fR 109 102 matches any single character 110 103 .IP \fB\e\fIk\fR 111 104 matches the non-alphanumeric character \fIk\fR 112 -taken as an ordinary character, e.g. 113 -.QW \fB\e\e\fR 114 -matches a backslash character 105 +taken as an ordinary character, e.g. \fB\e\e\fR matches a backslash 106 +character 115 107 .IP \fB\e\fIc\fR 116 108 where \fIc\fR is alphanumeric (possibly followed by other characters), 117 109 an \fIescape\fR (AREs only), see \fBESCAPES\fR below 118 110 .IP \fB{\fR 119 111 when followed by a character other than a digit, matches the 120 -left-brace character 121 -.QW \fB{\fR ; 122 -when followed by a digit, it is the beginning of a \fIbound\fR (see above) 112 +left-brace character `\fB{\fR'; when followed by a digit, it is the 113 +beginning of a \fIbound\fR (see above) 123 114 .IP \fIx\fR 124 115 where \fIx\fR is a single character with no other significance, 125 116 matches that character. 126 117 .RE 127 118 .PP 128 119 A \fIconstraint\fR matches an empty string when specific conditions 129 120 are met. A constraint may not be followed by a quantifier. The ................................................................................ 145 136 \fInegative lookahead\fR (AREs only), matches at any point where no 146 137 substring matching \fIre\fR begins 147 138 .RE 148 139 .PP 149 140 The lookahead constraints may not contain back references (see later), 150 141 and all parentheses within them are considered non-capturing. 151 142 .PP 152 -An RE may not end with 153 -.QW \fB\e\fR . 143 +An RE may not end with `\fB\e\fR'. 154 144 .SH "BRACKET EXPRESSIONS" 155 145 A \fIbracket expression\fR is a list of characters enclosed in 156 -.QW \fB[\|]\fR . 157 -It normally matches any single character from the list (but see 158 -below). If the list begins with 159 -.QW \fB^\fR , 160 -it matches any single character (but see below) \fInot\fR from the 161 -rest of the list. 162 -.PP 163 -If two characters in the list are separated by 164 -.QW \fB\-\fR , 165 -this is shorthand for the full \fIrange\fR of characters between those two 166 -(inclusive) in the collating sequence, e.g. 167 -.QW \fB[0\-9]\fR 168 -in Unicode matches any conventional decimal digit. Two ranges may not share an 169 -endpoint, so e.g. 170 -.QW \fBa\-c\-e\fR 171 -is illegal. Ranges are very collating-sequence-dependent, and portable 172 -programs should avoid relying on them. 173 -.PP 174 -To include a literal 175 -.QW \fB]\fR 176 -or 177 -.QW \fB\-\fR 178 -in the list, the simplest method is to enclose it in 179 -.QW \fB[.\fR 180 -and 181 -.QW \fB.]\fR 182 -to make it a collating element (see below). Alternatively, make it the first 183 -character (following a possible 184 -.QW \fB^\fR ), 185 -or (AREs only) precede it with 186 -.QW \fB\e\fR . 187 -Alternatively, for 188 -.QW \fB\-\fR , 189 -make it the last character, or the second endpoint of a range. To use a 190 -literal 191 -.QW \fB\-\fR 192 -as the first endpoint of a range, make it a collating element 193 -or (AREs only) precede it with 194 -.QW \fB\e\fR . 195 -With the exception of these, some combinations using 196 -.QW \fB[\fR 197 -(see next paragraphs), and escapes, all other special characters lose their 198 -special significance within a bracket expression. 146 +`\fB[\|]\fR'. It normally matches any single character from the list 147 +(but see below). If the list begins with `\fB^\fR', it matches any 148 +single character (but see below) \fInot\fR from the rest of the list. 149 +.PP 150 +If two characters in the list are separated by `\fB\-\fR', this is 151 +shorthand for the full \fIrange\fR of characters between those two 152 +(inclusive) in the collating sequence, e.g. \fB[0\-9]\fR in Unicode 153 +matches any conventional decimal digit. Two ranges may not share an 154 +endpoint, so e.g. \fBa\-c\-e\fR is illegal. Ranges are very 155 +collating-sequence-dependent, and portable programs should avoid 156 +relying on them. 157 +.PP 158 +To include a literal \fB]\fR or \fB\-\fR in the list, the simplest 159 +method is to enclose it in \fB[.\fR and \fB.]\fR to make it a 160 +collating element (see below). Alternatively, make it the first 161 +character (following a possible `\fB^\fR'), or (AREs only) precede it 162 +with `\fB\e\fR'. Alternatively, for `\fB\-\fR', make it the last 163 +character, or the second endpoint of a range. To use a literal 164 +\fB\-\fR as the first endpoint of a range, make it a collating element 165 +or (AREs only) precede it with `\fB\e\fR'. With the exception of 166 +these, some combinations using \fB[\fR (see next paragraphs), and 167 +escapes, all other special characters lose their special significance 168 +within a bracket expression. 199 169 .PP 200 170 Within a bracket expression, a collating element (a character, a 201 171 multi-character sequence that collates as if it were a single 202 172 character, or a collating-sequence name for either) enclosed in 203 -.QW \fB[.\fR 204 -and 205 -.QW \fB.]\fR 206 -stands for the sequence of characters of that collating element. 207 -The sequence is a single element of the bracket 173 +\fB[.\fR and \fB.]\fR stands for the sequence of characters of that 174 +collating element. The sequence is a single element of the bracket 208 175 expression's list. A bracket expression in a locale that has 209 176 multi-character collating elements can thus match more than one 210 177 character. So (insidiously), a bracket expression that starts with 211 -.QW \fB^\fR 212 -can match multi-character collating elements even if none of 178 +\fB^\fR can match multi-character collating elements even if none of 213 179 them appear in the bracket expression! (\fINote:\fR Tcl currently has 214 180 no multi-character collating elements. This information is only for 215 181 illustration.) 216 182 .PP 217 -For example, assume the collating sequence includes a 218 -.QW \fBch\fR 219 -multi-character collating element. Then the RE 220 -.QW \fB[[.ch.]]*c\fR 221 -(zero or more 222 -.QW \fBch\fR 's 223 -followed by 224 -.QW \fBc\fR ) 225 -matches the first five characters of 226 -.QW \fBchchcc\fR . 227 -Also, the RE 228 -.QW \fB[^c]b\fR 229 -matches all of 230 -.QW \fBchb\fR 231 -(because 232 -.QW \fB[^c]\fR 233 -matches the multi-character 234 -.QW \fBch\fR ). 183 +For example, assume the collating sequence includes a \fBch\fR 184 +multi-character collating element. Then the RE \fB[[.ch.]]*c\fR (zero 185 +or more \fBch\fR's followed by \fBc\fR) matches the first five 186 +characters of `\fBchchcc\fR'. Also, the RE \fB[^c]b\fR matches all of 187 +`\fBchb\fR' (because \fB[^c]\fR matches the multi-character \fBch\fR). 235 188 .PP 236 -Within a bracket expression, a collating element enclosed in 237 -.QW \fB[=\fR 238 -and 239 -.QW \fB=]\fR 240 -is an equivalence class, standing for the sequences of 189 +Within a bracket expression, a collating element enclosed in \fB[=\fR 190 +and \fB=]\fR is an equivalence class, standing for the sequences of 241 191 characters of all collating elements equivalent to that one, including 242 192 itself. (If there are no other equivalent collating elements, the 243 -treatment is as if the enclosing delimiters were 244 -.QW \fB[.\fR \& 245 -and 246 -.QW \fB.]\fR .) 247 -For example, if 248 -.QW \fBo\fR 249 -and 250 -.QW \fB\N'244'\fR 251 -are the members of an equivalence class, then 252 -.QW \fB[[=o=]]\fR , 253 -.QW \fB[[=\N'244'=]]\fR , 254 -and 255 -.QW \fB[o\N'244']\fR \& 256 -are all synonymous. An equivalence class may 193 +treatment is as if the enclosing delimiters were `\fB[.\fR'\& and 194 +`\fB.]\fR'.) For example, if \fBo\fR and \fB\o'o^'\fR are the members 195 +of an equivalence class, then `\fB[[=o=]]\fR', `\fB[[=\o'o^'=]]\fR', 196 +and `\fB[o\o'o^']\fR'\& are all synonymous. An equivalence class may 257 197 not be an endpoint of a range. (\fINote:\fR Tcl currently implements 258 198 only the Unicode locale. It doesn't define any equivalence classes. 259 199 The examples above are just illustrations.) 260 200 .PP 261 201 Within a bracket expression, the name of a \fIcharacter class\fR 262 -enclosed in 263 -.QW \fB[:\fR 264 -and 265 -.QW \fB:]\fR 266 -stands for the list of all 267 -characters (not all collating elements!) belonging to that class. 202 +enclosed in \fB[:\fR and \fB:]\fR stands for the list of all 203 +characters (not all collating elements!) belonging to that class. 268 204 Standard character classes are: 269 205 .IP \fBalpha\fR 8 270 206 A letter. 271 207 .IP \fBupper\fR 8 272 208 An upper-case letter. 273 209 .IP \fBlower\fR 8 274 210 A lower-case letter. ................................................................................ 275 211 .IP \fBdigit\fR 8 276 212 A decimal digit. 277 213 .IP \fBxdigit\fR 8 278 214 A hexadecimal digit. 279 215 .IP \fBalnum\fR 8 280 216 An alphanumeric (letter or digit). 281 217 .IP \fBprint\fR 8 282 -A 283 -.QW "printable" 284 -(same as graph, except also including space). 218 +A "printable" (same as graph, except also including space). 285 219 .IP \fBblank\fR 8 286 220 A space or tab character. 287 221 .IP \fBspace\fR 8 288 222 A character producing white space in displayed text. 289 223 .IP \fBpunct\fR 8 290 224 A punctuation character. 291 225 .IP \fBgraph\fR 8 ................................................................................ 294 228 A control character. 295 229 .PP 296 230 A locale may provide others. (Note that the current Tcl 297 231 implementation has only one locale: the Unicode locale.) A character 298 232 class may not be used as an endpoint of a range. 299 233 .PP 300 234 There are two special cases of bracket expressions: the bracket 301 -expressions 302 -.QW \fB[[:<:]]\fR 303 -and 304 -.QW \fB[[:>:]]\fR 305 -are constraints, matching 235 +expressions \fB[[:<:]]\fR and \fB[[:>:]]\fR are constraints, matching 306 236 empty strings at the beginning and end of a word respectively. 307 -.\" note, discussion of escapes below references this definition of word 237 +'\" note, discussion of escapes below references this definition of word 308 238 A word is defined as a sequence of word characters that is neither 309 239 preceded nor followed by word characters. A word character is an 310 -\fIalnum\fR character or an underscore 311 -.PQ \fB_\fR "" . 312 -These special bracket expressions are deprecated; users of AREs should use 240 +\fIalnum\fR character or an underscore (\fB_\fR). These special 241 +bracket expressions are deprecated; users of AREs should use 313 242 constraint escapes instead (see below). 314 243 .SH ESCAPES 315 -Escapes (AREs only), which begin with a 316 -.QW \fB\e\fR 317 -followed by an 244 +Escapes (AREs only), which begin with a \fB\e\fR followed by an 318 245 alphanumeric character, come in several varieties: character entry, 319 -class shorthands, constraint escapes, and back references. A 320 -.QW \fB\e\fR 246 +class shorthands, constraint escapes, and back references. A \fB\e\fR 321 247 followed by an alphanumeric character but not constituting a valid 322 248 escape is illegal in AREs. In EREs, there are no escapes: outside a 323 -bracket expression, a 324 -.QW \fB\e\fR 325 -followed by an alphanumeric character 249 +bracket expression, a \fB\e\fR followed by an alphanumeric character 326 250 merely stands for that character as an ordinary character, and inside 327 -a bracket expression, 328 -.QW \fB\e\fR 329 -is an ordinary character. (The latter 251 +a bracket expression, \fB\e\fR is an ordinary character. (The latter 330 252 is the one actual incompatibility between EREs and AREs.) 331 253 .PP 332 254 Character-entry escapes (AREs only) exist to make it easier to specify 333 255 non-printing and otherwise inconvenient characters in REs: 334 256 .RS 2 335 257 .TP 5 336 258 \fB\ea\fR ................................................................................ 344 266 applications where there are multiple levels of backslash processing 345 267 .TP 346 268 \fB\ec\fIX\fR 347 269 (where \fIX\fR is any character) the character whose low-order 5 bits 348 270 are the same as those of \fIX\fR, and whose other bits are all zero 349 271 .TP 350 272 \fB\ee\fR 351 -the character whose collating-sequence name is 352 -.QW \fBESC\fR , 353 -or failing that, the character with octal value 033 273 +the character whose collating-sequence name is `\fBESC\fR', or failing 274 +that, the character with octal value 033 354 275 .TP 355 276 \fB\ef\fR 356 277 formfeed, as in C 357 278 .TP 358 279 \fB\en\fR 359 280 newline, as in C 360 281 .TP ................................................................................ 390 311 .TP 391 312 \fB\e\fIxyz\fR 392 313 (where \fIxyz\fR is exactly three octal digits, and is not a back 393 314 reference (see below)) the character whose octal value is 394 315 \fB0\fIxyz\fR 395 316 .RE 396 317 .PP 397 -Hexadecimal digits are 398 -.QR 0 9 , 399 -.QR a f , 400 -and 401 -.QR A F . 402 -Octal digits are 403 -.QR 0 7 . 318 +Hexadecimal digits are `\fB0\fR'-`\fB9\fR', `\fBa\fR'-`\fBf\fR', and 319 +`\fBA\fR'-`\fBF\fR'. Octal digits are `\fB0\fR'-`\fB7\fR'. 404 320 .PP 405 321 The character-entry escapes are always taken as ordinary characters. 406 -For example, 407 -.QW \fB\e135\fR 408 -is 409 -.QW \fB]\fR 410 -in Unicode, but 411 -.QW \fB\e135\fR 412 -does not terminate a bracket expression. Beware, however, that some 322 +For example, \fB\e135\fR is \fB]\fR in Unicode, but \fB\e135\fR does 323 +not terminate a bracket expression. Beware, however, that some 413 324 applications (e.g., C compilers and the Tcl interpreter if the regular 414 325 expression is not quoted with braces) interpret such sequences 415 326 themselves before the regular-expression package gets to see them, 416 -which may require doubling (quadrupling, etc.) the 417 -.QW \fB\e\fR . 327 +which may require doubling (quadrupling, etc.) the `\fB\e\fR'. 418 328 .PP 419 329 Class-shorthand escapes (AREs only) provide shorthands for certain 420 330 commonly-used character classes: 421 331 .RS 2 422 332 .TP 10 423 333 \fB\ed\fR 424 334 \fB[[:digit:]]\fR ................................................................................ 435 345 \fB\eS\fR 436 346 \fB[^[:space:]]\fR 437 347 .TP 438 348 \fB\eW\fR 439 349 \fB[^[:alnum:]_]\fR (note underscore) 440 350 .RE 441 351 .PP 442 -Within bracket expressions, 443 -.QW \fB\ed\fR , 444 -.QW \fB\es\fR , 445 -and 446 -.QW \fB\ew\fR \& 447 -lose their outer brackets, and 448 -.QW \fB\eD\fR , 449 -.QW \fB\eS\fR , 450 -and 451 -.QW \fB\eW\fR \& 452 -are illegal. (So, for example, 453 -.QW \fB[a-c\ed]\fR 454 -is equivalent to 455 -.QW \fB[a-c[:digit:]]\fR . 456 -Also, 457 -.QW \fB[a-c\eD]\fR , 458 -which is equivalent to 459 -.QW \fB[a-c^[:digit:]]\fR , 460 -is illegal.) 352 +Within bracket expressions, `\fB\ed\fR', `\fB\es\fR', and 353 +`\fB\ew\fR'\& lose their outer brackets, and `\fB\eD\fR', `\fB\eS\fR', 354 +and `\fB\eW\fR'\& are illegal. (So, for example, \fB[a-c\ed]\fR is 355 +equivalent to \fB[a-c[:digit:]]\fR. Also, \fB[a-c\eD]\fR, which is 356 +equivalent to \fB[a-c^[:digit:]]\fR, is illegal.) 461 357 .PP 462 358 A constraint escape (AREs only) is a constraint, matching the empty 463 359 string if specific conditions are met, written as an escape: 464 360 .RS 2 465 361 .TP 6 466 362 \fB\eA\fR 467 363 matches only at the beginning of the string (see \fBMATCHING\fR, 468 -below, for how this differs from 469 -.QW \fB^\fR ) 364 +below, for how this differs from `\fB^\fR') 470 365 .TP 471 366 \fB\em\fR 472 367 matches only at the beginning of a word 473 368 .TP 474 369 \fB\eM\fR 475 370 matches only at the end of a word 476 371 .TP ................................................................................ 478 373 matches only at the beginning or end of a word 479 374 .TP 480 375 \fB\eY\fR 481 376 matches only at a point that is not the beginning or end of a word 482 377 .TP 483 378 \fB\eZ\fR 484 379 matches only at the end of the string (see \fBMATCHING\fR, below, for 485 -how this differs from 486 -.QW \fB$\fR ) 380 +how this differs from `\fB$\fR') 487 381 .TP 488 382 \fB\e\fIm\fR 489 383 (where \fIm\fR is a nonzero digit) a \fIback reference\fR, see below 490 384 .TP 491 385 \fB\e\fImnn\fR 492 386 (where \fIm\fR is a nonzero digit, and \fInn\fR is some more digits, 493 387 and the decimal value \fImnn\fR is not greater than the number of 494 388 closing capturing parentheses seen so far) a \fIback reference\fR, see 495 389 below 496 390 .RE 497 391 .PP 498 -A word is defined as in the specification of 499 -.QW \fB[[:<:]]\fR 500 -and 501 -.QW \fB[[:>:]]\fR 502 -above. Constraint escapes are illegal within bracket expressions. 392 +A word is defined as in the specification of \fB[[:<:]]\fR and 393 +\fB[[:>:]]\fR above. Constraint escapes are illegal within bracket 394 +expressions. 503 395 .PP 504 396 A back reference (AREs only) matches the same string matched by the 505 397 parenthesized subexpression specified by the number, so that (e.g.) 506 -.QW \fB([bc])\e1\fR 507 -matches 508 -.QW \fBbb\fR 509 -or 510 -.QW \fBcc\fR 511 -but not 512 -.QW \fBbc\fR . 513 -The subexpression must entirely precede the back reference in the RE. 398 +\fB([bc])\e1\fR matches \fBbb\fR or \fBcc\fR but not `\fBbc\fR'. The 399 +subexpression must entirely precede the back reference in the RE. 514 400 Subexpressions are numbered in the order of their leading parentheses. 515 401 Non-capturing parentheses do not define subexpressions. 516 402 .PP 517 403 There is an inherent historical ambiguity between octal 518 404 character-entry escapes and back references, which is resolved by 519 405 heuristics, as hinted at above. A leading zero always indicates an 520 406 octal escape. A single non-zero digit, not followed by another digit, ................................................................................ 524 410 back reference), and otherwise is taken as octal. 525 411 .SH "METASYNTAX" 526 412 In addition to the main syntax described above, there are some special 527 413 forms and miscellaneous syntactic facilities available. 528 414 .PP 529 415 Normally the flavor of RE being used is specified by 530 416 application-dependent means. However, this can be overridden by a 531 -\fIdirector\fR. If an RE of any flavor begins with 532 -.QW \fB***:\fR , 533 -the rest of the RE is an ARE. If an RE of any flavor begins with 534 -.QW \fB***=\fR , 535 -the rest of the RE is taken to be a literal string, with 417 +\fIdirector\fR. If an RE of any flavor begins with `\fB***:\fR', the 418 +rest of the RE is an ARE. If an RE of any flavor begins with 419 +`\fB***=\fR', the rest of the RE is taken to be a literal string, with 536 420 all characters considered ordinary characters. 537 421 .PP 538 422 An ARE may begin with \fIembedded options\fR: a sequence 539 -.QW \fB(?\fIxyz\fB)\fR 540 -where 541 -.QW \fIxyz\fR 542 -is one or more alphabetic characters) specifies options affecting the rest of 543 -the RE. These supplement, and can override, any options specified by the 423 +\fB(?\fIxyz\fB)\fR (where \fIxyz\fR is one or more alphabetic 424 +characters) specifies options affecting the rest of the RE. These 425 +supplement, and can override, any options specified by the 544 426 application. The available option letters are: 545 427 .RS 2 546 428 .TP 3 547 429 \fBb\fR 548 430 rest of RE is a BRE 549 431 .TP 3 550 432 \fBc\fR ................................................................................ 562 444 \fBn\fR 563 445 newline-sensitive matching (see \fBMATCHING\fR, below) 564 446 .TP 3 565 447 \fBp\fR 566 448 partial newline-sensitive matching (see \fBMATCHING\fR, below) 567 449 .TP 3 568 450 \fBq\fR 569 -rest of RE is a literal 570 -.PQ quoted 571 -string, all ordinary characters 451 +rest of RE is a literal (``quoted'') string, all ordinary characters 572 452 .TP 3 573 453 \fBs\fR 574 454 non-newline-sensitive matching (usual default) 575 455 .TP 3 576 456 \fBt\fR 577 457 tight syntax (usual default; see below) 578 458 .TP 3 579 459 \fBw\fR 580 -inverse partial newline-sensitive 581 -.PQ weird 582 -matching (see \fBMATCHING\fR, below) 460 +inverse partial newline-sensitive (``weird'') matching (see 461 +\fBMATCHING\fR, below) 583 462 .TP 3 584 463 \fBx\fR 585 464 expanded syntax (see below) 586 465 .RE 587 466 .PP 588 -Embedded options take effect at the 589 -.QW \fB)\fR 590 -terminating the sequence. They are available only at the start of an ARE, and 591 -may not be used later within it. 467 +Embedded options take effect at the \fB)\fR terminating the sequence. 468 +They are available only at the start of an ARE, and may not be used 469 +later within it. 592 470 .PP 593 471 In addition to the usual (\fItight\fR) RE syntax, in which all 594 472 characters are significant, there is an \fIexpanded\fR syntax, 595 473 available in all flavors of RE with the \fB-expanded\fR switch, or in 596 474 AREs with the embedded x option. In the expanded syntax, white-space 597 475 characters are ignored and all characters between a \fB#\fR and the 598 476 following newline (or the end of the RE) are ignored, permitting 599 477 paragraphing and commenting a complex RE. There are three exceptions 600 478 to that basic rule: 601 479 .IP \(bu 3 602 -a white-space character or 603 -.QW \fB#\fR 604 -preceded by 605 -.QW \fB\e\fR 606 -is retained 480 +a white-space character or `\fB#\fR' preceded by `\fB\e\fR' is 481 +retained 607 482 .IP \(bu 3 608 -white space or 609 -.QW \fB#\fR 610 -within a bracket expression is retained 483 +white space or `\fB#\fR' within a bracket expression is retained 611 484 .IP \(bu 3 612 485 white space and comments are illegal within multi-character symbols 613 -like the ARE 614 -.QW \fB(?:\fR 615 -or the BRE 616 -.QW \fB\e(\fR 486 +like the ARE `\fB(?:\fR' or the BRE `\fB\e(\fR' 617 487 .PP 618 488 Expanded-syntax white-space characters are blank, tab, newline, and 619 489 any character that belongs to the \fIspace\fR character class. 620 490 .PP 621 491 Finally, in an ARE, outside bracket expressions, the sequence 622 -.QW \fB(?#\fIttt\fB)\fR 623 -(where \fIttt\fR is any text not containing a 624 -.QW \fB)\fR ) 625 -is a comment, completely ignored. Again, this is not allowed between the 626 -characters of multi-character symbols like 627 -.QW \fB(?:\fR . 628 -Such comments are more a historical artifact than a 492 +`\fB(?#\fIttt\fB)\fR' (where \fIttt\fR is any text not containing a 493 +`\fB)\fR') is a comment, completely ignored. Again, this is not 494 +allowed between the characters of multi-character symbols like 495 +`\fB(?:\fR'. Such comments are more a historical artifact than a 629 496 useful facility, and their use is deprecated; use the expanded syntax 630 497 instead. 631 498 .PP 632 499 \fINone\fR of these metasyntax extensions is available if the 633 -application (or an initial 634 -.QW \fB***=\fR 635 -director) has specified that the 500 +application (or an initial \fB***=\fR director) has specified that the 636 501 user's input be treated as a literal string rather than as an RE. 637 502 .SH MATCHING 638 503 In the event that an RE could match more than one substring of a given 639 504 string, the RE matches the one starting earliest in the string. If 640 505 the RE could match more than one substring starting at that point, its 641 506 choice is determined by its \fIpreference\fR: either the longest 642 507 substring, or the shortest. 643 508 .PP 644 509 Most atoms, and all constraints, have no preference. A parenthesized 645 510 RE has the same preference (possibly none) as the RE. A quantified 646 -atom with quantifier 647 -.QW \fB{\fIm\fB}\fR 648 -or 649 -.QW \fB{\fIm\fB}?\fR 650 -has the same 511 +atom with quantifier \fB{\fIm\fB}\fR or \fB{\fIm\fB}?\fR has the same 651 512 preference (possibly none) as the atom itself. A quantified atom with 652 -other normal quantifiers (including 653 -.QW \fB{\fIm\fB,\fIn\fB}\fR 654 -with \fIm\fR equal to \fIn\fR) prefers longest match. A quantified atom 655 -with other non-greedy quantifiers (including 656 -.QW \fB{\fIm\fB,\fIn\fB}?\fR 513 +other normal quantifiers (including \fB{\fIm\fB,\fIn\fB}\fR with 514 +\fIm\fR equal to \fIn\fR) prefers longest match. A quantified atom 515 +with other non-greedy quantifiers (including \fB{\fIm\fB,\fIn\fB}?\fR 657 516 with \fIm\fR equal to \fIn\fR) prefers shortest match. A branch has 658 517 the same preference as the first quantified atom in it which has a 659 518 preference. An RE consisting of two or more branches connected by the 660 -.QW \fB|\fR 661 -operator prefers longest match. 519 +\fB|\fR operator prefers longest match. 662 520 .PP 663 521 Subject to the constraints imposed by the rules for matching the whole 664 522 RE, subexpressions also match the longest or shortest possible 665 523 substrings, based on their preferences, with subexpressions starting 666 524 earlier in the RE taking priority over ones starting later. Note that 667 525 outer subexpressions thus take priority over their component 668 526 subexpressions. 669 527 .PP 670 -Note that the quantifiers 671 -.QW \fB{1,1}\fR 672 -and 673 -.QW \fB{1,1}?\fR 674 -can be used to force longest and shortest preference, respectively, on a 528 +Note that the quantifiers \fB{1,1}\fR and \fB{1,1}?\fR can be used to 529 +force longest and shortest preference, respectively, on a 675 530 subexpression or a whole RE. 676 531 .PP 677 532 Match lengths are measured in characters, not collating elements. An 678 533 empty string is considered longer than no match at all. For example, 679 -.QW \fBbb*\fR 680 -matches the three middle characters of 681 -.QW \fBabbbc\fR , 682 -.QW \fB(week|wee)(night|knights)\fR 683 -matches all ten characters of 684 -.QW \fBweeknights\fR , 685 -when 686 -.QW \fB(.*).*\fR 687 -is matched against 688 -.QW \fBabc\fR 689 -the 534 +\fBbb*\fR matches the three middle characters of `\fBabbbc\fR', 535 +\fB(week|wee)(night|knights)\fR matches all ten characters of 536 +`\fBweeknights\fR', when \fB(.*).*\fR is matched against \fBabc\fR the 690 537 parenthesized subexpression matches all three characters, and when 691 -.QW \fB(a*)*\fR 692 -is matched against 693 -.QW \fBbc\fR 694 -both the whole RE and the 538 +\fB(a*)*\fR is matched against \fBbc\fR both the whole RE and the 695 539 parenthesized subexpression match an empty string. 696 540 .PP 697 541 If case-independent matching is specified, the effect is much as if 698 542 all case distinctions had vanished from the alphabet. When an 699 543 alphabetic that exists in multiple cases appears as an ordinary 700 544 character outside a bracket expression, it is effectively transformed 701 -into a bracket expression containing both cases, so that 702 -.QW \fBx\fR 703 -becomes 704 -.QW \fB[xX]\fR . 705 -When it appears inside a bracket expression, 545 +into a bracket expression containing both cases, so that \fBx\fR 546 +becomes `\fB[xX]\fR'. When it appears inside a bracket expression, 706 547 all case counterparts of it are added to the bracket expression, so 707 -that 708 -.QW \fB[x]\fR 709 -becomes 710 -.QW \fB[xX]\fR 711 -and 712 -.QW \fB[^x]\fR 713 -becomes 714 -.QW \fB[^xX]\fR. 548 +that \fB[x]\fR becomes \fB[xX]\fR and \fB[^x]\fR becomes 549 +`\fB[^xX]\fR'. 715 550 .PP 716 -If newline-sensitive matching is specified, 717 -.QW \fB.\fR 718 -and bracket expressions using 719 -.QW \fB^\fR 720 -will never match the newline character (so 551 +If newline-sensitive matching is specified, \fB.\fR and bracket 552 +expressions using \fB^\fR will never match the newline character (so 721 553 that matches will never cross newlines unless the RE explicitly 722 -arranges it) and 723 -.QW \fB^\fR 724 -and 725 -.QW \fB$\fR 726 -will match the empty string after 554 +arranges it) and \fB^\fR and \fB$\fR will match the empty string after 727 555 and before a newline respectively, in addition to matching at 728 -beginning and end of string respectively. ARE 729 -.QW \fB\eA\fR 730 -and 731 -.QW \fB\eZ\fR 556 +beginning and end of string respectively. ARE \fB\eA\fR and \fB\eZ\fR 732 557 continue to match beginning or end of string \fIonly\fR. 733 558 .PP 734 559 If partial newline-sensitive matching is specified, this affects 735 -.QW \fB.\fR 736 -and bracket expressions as with newline-sensitive matching, but not 737 -.QW \fB^\fR 738 -and 739 -.QW \fB$\fR. 560 +\fB.\fR and bracket expressions as with newline-sensitive matching, 561 +but not \fB^\fR and `\fB$\fR'. 740 562 .PP 741 563 If inverse partial newline-sensitive matching is specified, this 742 -affects 743 -.QW \fB^\fR 744 -and 745 -.QW \fB$\fR 746 -as with newline-sensitive matching, but not 747 -.QW \fB.\fR 748 -and bracket expressions. This isn't very useful but is 564 +affects \fB^\fR and \fB$\fR as with newline-sensitive matching, but 565 +not \fB.\fR and bracket expressions. This isn't very useful but is 749 566 provided for symmetry. 750 567 .SH "LIMITS AND COMPATIBILITY" 751 568 No particular limit is imposed on the length of REs. Programs 752 569 intended to be highly portable should not employ REs longer than 256 753 570 bytes, as a POSIX-compliant implementation can refuse to accept such 754 571 REs. 755 572 .PP 756 573 The only feature of AREs that is actually incompatible with POSIX EREs 757 -is that 758 -.QW \fB\e\fR 759 -does not lose its special significance inside bracket 574 +is that \fB\e\fR does not lose its special significance inside bracket 760 575 expressions. All other ARE features use syntax which is illegal or 761 -has undefined or unspecified effects in POSIX EREs; the 762 -.QW \fB***\fR 576 +has undefined or unspecified effects in POSIX EREs; the \fB***\fR 763 577 syntax of directors likewise is outside the POSIX syntax for both BREs 764 578 and EREs. 765 579 .PP 766 580 Many of the ARE extensions are borrowed from Perl, but some have been 767 581 changed to clean them up, and a few Perl extensions are not present. 768 -Incompatibilities of note include 769 -.QW \fB\eb\fR , 770 -.QW \fB\eB\fR , 771 -the lack of special treatment for a trailing newline, the addition of 582 +Incompatibilities of note include `\fB\eb\fR', `\fB\eB\fR', the lack 583 +of special treatment for a trailing newline, the addition of 772 584 complemented bracket expressions to the things affected by 773 585 newline-sensitive matching, the restrictions on parentheses and back 774 586 references in lookahead constraints, and the longest/shortest-match 775 587 (rather than first-match) matching semantics. 776 588 .PP 777 589 The matching rules for REs containing both normal and non-greedy 778 590 quantifiers have changed since early beta-test versions of this 779 591 package. (The new rules are much simpler and cleaner, but don't work 780 592 as hard at guessing the user's real intentions.) 781 593 .PP 782 594 Henry Spencer's original 1986 \fIregexp\fR package, still in 783 595 widespread use (e.g., in pre-8.1 releases of Tcl), implemented an 784 596 early version of today's EREs. There are four incompatibilities 785 -between \fIregexp\fR's near-EREs 786 -.PQ RRE "s for short" 787 -and AREs. In roughly increasing order of significance: 597 +between \fIregexp\fR's near-EREs (`RREs' for short) and AREs. In 598 +roughly increasing order of significance: 788 599 .IP \(bu 3 789 -In AREs, 790 -.QW \fB\e\fR 791 -followed by an alphanumeric character is either an 600 +In AREs, \fB\e\fR followed by an alphanumeric character is either an 792 601 escape or an error, while in RREs, it was just another way of writing 793 602 the alphanumeric. This should not be a problem because there was no 794 603 reason to write such a sequence in RREs. 795 604 .IP \(bu 3 796 -.QW \fB{\fR 797 -followed by a digit in an ARE is the beginning of a bound, 798 -while in RREs, 799 -.QW \fB{\fR 800 -was always an ordinary character. Such 605 +\fB{\fR followed by a digit in an ARE is the beginning of a bound, 606 +while in RREs, \fB{\fR was always an ordinary character. Such 801 607 sequences should be rare, and will often result in an error because 802 608 following characters will not look like a valid bound. 803 609 .IP \(bu 3 804 -In AREs, 805 -.QW \fB\e\fR 806 -remains a special character within 807 -.QW \fB[\|]\fR , 808 -so a literal 809 -.QW \fB\e\fR 810 -within 811 -.QW \fB[\|]\fR 812 -must be written 813 -.QW \fB\e\e\fR . 814 -.QW \fB\e\e\fR 815 -also gives a literal 816 -.QW \fB\e\fR 817 -within 818 -.QW \fB[\|]\fR 819 -in RREs, but only truly paranoid programmers routinely doubled the backslash. 610 +In AREs, \fB\e\fR remains a special character within `\fB[\|]\fR', so 611 +a literal \fB\e\fR within \fB[\|]\fR must be written `\fB\e\e\fR'. 612 +\fB\e\e\fR also gives a literal \fB\e\fR within \fB[\|]\fR in RREs, 613 +but only truly paranoid programmers routinely doubled the backslash. 820 614 .IP \(bu 3 821 615 AREs report the longest/shortest match for the RE, rather than the 822 616 first found in a specified search order. This may affect some RREs 823 617 which were written in the expectation that the first match would be 824 618 reported. (The careful crafting of RREs to optimize the search order 825 619 for fast matching is obsolete (AREs examine all possible matches in 826 620 parallel, and their performance is largely insensitive to their 827 621 complexity) but cases where the search order was exploited to 828 622 deliberately find a match which was \fInot\fR the longest/shortest 829 623 will need rewriting.) 830 624 .SH "BASIC REGULAR EXPRESSIONS" 831 -BREs differ from EREs in several respects. 832 -.QW \fB|\fR , 833 -.QW \fB+\fR , 834 -and 835 -.QW \fB?\fR 836 -are ordinary characters and there is no equivalent for their 837 -functionality. The delimiters for bounds are 838 -.QW \fB\e{\fR 839 -and 840 -.QW \fB\e}\fR , 841 -with 842 -.QW \fB{\fR 843 -and 844 -.QW \fB}\fR 845 -by themselves ordinary characters. The parentheses for nested subexpressions 846 -are 847 -.QW \fB\e(\fR 848 -and 849 -.QW \fB\e)\fR , 850 -with 851 -.QW \fB(\fR 852 -and 853 -.QW \fB)\fR 854 -by themselves ordinary characters. 855 -.QW \fB^\fR 856 -is an ordinary character except at the beginning 857 -of the RE or the beginning of a parenthesized subexpression, 858 -.QW \fB$\fR 625 +BREs differ from EREs in several respects. `\fB|\fR', `\fB+\fR', and 626 +\fB?\fR are ordinary characters and there is no equivalent for their 627 +functionality. The delimiters for bounds are \fB\e{\fR and 628 +`\fB\e}\fR', with \fB{\fR and \fB}\fR by themselves ordinary 629 +characters. The parentheses for nested subexpressions are \fB\e(\fR 630 +and `\fB\e)\fR', with \fB(\fR and \fB)\fR by themselves ordinary 631 +characters. \fB^\fR is an ordinary character except at the beginning 632 +of the RE or the beginning of a parenthesized subexpression, \fB$\fR 859 633 is an ordinary character except at the end of the RE or the end of a 860 -parenthesized subexpression, and 861 -.QW \fB*\fR 862 -is an ordinary character if 634 +parenthesized subexpression, and \fB*\fR is an ordinary character if 863 635 it appears at the beginning of the RE or the beginning of a 864 -parenthesized subexpression (after a possible leading 865 -.QW \fB^\fR ). 866 -Finally, single-digit back references are available, and 867 -.QW \fB\e<\fR 868 -and 869 -.QW \fB\e>\fR 870 -are synonyms for 871 -.QW \fB[[:<:]]\fR 872 -and 873 -.QW \fB[[:>:]]\fR 636 +parenthesized subexpression (after a possible leading `\fB^\fR'). 637 +Finally, single-digit back references are available, and \fB\e<\fR and 638 +\fB\e>\fR are synonyms for \fB[[:<:]]\fR and \fB[[:>:]]\fR 874 639 respectively; no other escapes are available. 640 + 875 641 .SH "SEE ALSO" 876 642 RegExp(3), regexp(n), regsub(n), lsearch(n), switch(n), text(n) 643 + 877 644 .SH KEYWORDS 878 645 match, regular expression, string 879 -.\" Local Variables: 880 -.\" mode: nroff 881 -.\" End: 646 + 647 +'\" Local Variables: 648 +'\" mode: nroff 649 +'\" End:
Changes to doc/read.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: read.n,v 1.12 2007/10/24 14:29:39 dkf Exp $ 8 +'\" RCS: @(#) $Id: read.n,v 1.13 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH read n 8.1 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 read \- Read from a channel ................................................................................ 49 49 the command returns before reaching the end of the file. 50 50 .PP 51 51 \fBRead\fR translates end-of-line sequences in the input into 52 52 newline characters according to the \fB\-translation\fR option 53 53 for the channel. 54 54 See the \fBfconfigure\fR manual entry for a discussion on ways in 55 55 which \fBfconfigure\fR will alter input. 56 + 56 57 .SH "USE WITH SERIAL PORTS" 57 -.\" Note: this advice actually applies to many versions of Tcl 58 +'\" Note: this advice actually applies to many versions of Tcl 59 + 58 60 For most applications a channel connected to a serial port should be 59 61 configured to be nonblocking: \fBfconfigure \fIchannelId \fB\-blocking 60 62 \fI0\fR. Then \fBread\fR behaves much like described above. Care 61 63 must be taken when using \fBread\fR on blocking serial ports: 62 64 .TP 63 65 \fBread \fIchannelId numChars\fR 64 66 In this form \fBread\fR blocks until \fInumChars\fR have been received ................................................................................ 74 76 with each line in the file corresponding to an element in the list: 75 77 .CS 76 78 set fl [open /proc/meminfo] 77 79 set data [\fBread\fR $fl] 78 80 close $fl 79 81 set lines [split $data \\n] 80 82 .CE 83 + 81 84 .SH "SEE ALSO" 82 85 file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3) 86 + 83 87 .SH KEYWORDS 84 88 blocking, channel, end of line, end of file, nonblocking, read, translation, encoding
Changes to doc/refchan.n.
1 1 '\" 2 2 '\" Copyright (c) 2006 Andreas Kupries 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: refchan.n,v 1.6 2007/10/25 09:44:22 dkf Exp $ 7 +'\" RCS: @(#) $Id: refchan.n,v 1.7 2007/10/26 20:11:53 dgp Exp $ 8 8 .so man.macros 9 9 .TH reflectedchan n 8.5 Tcl "Tcl Built-In Commands" 10 10 .BS 11 11 '\" Note: do not modify the .SH NAME line immediately below! 12 12 .SH NAME 13 13 reflectedchan \- Command handler API of reflected channels, version 1 14 14 .SH SYNOPSIS ................................................................................ 49 49 (e.g. \fBbreak\fR, etc.) is treated as (and converted to) an error. 50 50 .PP 51 51 \fBNote:\fR If the creation of the channel was aborted due to failures 52 52 here, then the \fBfinalize\fR subcommand will not be called. 53 53 .PP 54 54 The \fImode\fR argument tells the handler whether the channel was 55 55 opened for reading, writing, or both. It is a list containing any of 56 -the strings 57 -.QW "\fBread\fR" 58 -or 59 -.QW "\fBwrite\fR" . 60 -The list will always contain at least one element. 56 +the strings "\fBread\fR" or "\fBwrite\fR". The list will always 57 +contain at least one element. 61 58 .PP 62 59 The subcommand must throw an error if the chosen mode is not 63 60 supported by the \fIcmdPrefix\fR. 64 61 .RE 65 62 .TP 66 63 \fIcmdPrefix \fBfinalize \fIchannelId\fR 67 64 . ................................................................................ 85 82 aborted during \fBinitialize\fR (See above). 86 83 .RE 87 84 .TP 88 85 \fIcmdPrefix \fBwatch \fIchannelId eventspec\fR 89 86 . 90 87 This subcommand notifies the \fIcmdPrefix\fR that the specified 91 88 \fIchannelId\fR is interested in the events listed in the 92 -\fIeventspec\fR. This argument is a list containing any of 93 -.QW "\fBread\fR" 94 -and 95 -.QW "\fBwrite\fR" . 96 -The list may be empty, which signals that the 89 +\fIeventspec\fR. This argument is a list containing any of "\fBread\fR" 90 +and "\fBwrite\fR". The list may be empty, which signals that the 97 91 channel does not wish to be notified of any events. In that situation, 98 92 the handler should disable event generation completely. 99 93 .RS 100 94 .PP 101 95 \fBWarning:\fR Any return value of the subcommand is ignored. This 102 96 includes all errors thrown by the subcommand, break, continue, and 103 97 custom return codes. ................................................................................ 187 181 greater than or equal to zero. 188 182 .PP 189 183 If the subcommand throws an error the command which caused its 190 184 invocation (usually \fBseek\fR, or \fBtell\fR) will appear to have 191 185 thrown this error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, 192 186 etc.) is treated as and converted to an error. 193 187 .PP 194 -The offset/base combination of 0/\fBcurrent\fR signals a \fBtell\fR 188 +The offset/base combination of 0/"\fBcurrent\fR" signals a \fBtell\fR 195 189 request, i.e. seek nothing relative to the current location, making 196 190 the new location identical to the current one, which is then returned. 197 191 .RE 198 192 .TP 199 193 \fIcmdPrefix \fBconfigure \fIchannelId option value\fR 200 194 . 201 195 This \fIoptional\fR subcommand is for setting the type-specific options of
Changes to doc/regexp.n.
1 1 '\" 2 2 '\" Copyright (c) 1998 Sun Microsystems, Inc. 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 -'\" RCS: @(#) $Id: regexp.n,v 1.22 2007/10/25 14:07:32 dkf Exp $ 7 +'\" RCS: @(#) $Id: regexp.n,v 1.23 2007/10/26 20:11:53 dgp Exp $ 8 8 '\" 9 9 .so man.macros 10 10 .TH regexp n 8.3 Tcl "Tcl Built-In Commands" 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 regexp \- Match a regular expression against a string 15 + 15 16 .SH SYNOPSIS 16 17 \fBregexp \fR?\fIswitches\fR? \fIexp string \fR?\fImatchVar\fR? ?\fIsubMatchVar subMatchVar ...\fR? 17 18 .BE 18 19 19 20 .SH DESCRIPTION 20 21 .PP 21 22 Determines whether the regular expression \fIexp\fR matches part or ................................................................................ 57 58 will contain a list of two decimal strings giving the indices 58 59 in \fIstring\fR of the first and last characters in the matching 59 60 range of characters. 60 61 .TP 15 61 62 \fB\-line\fR 62 63 Enables newline-sensitive matching. By default, newline is a 63 64 completely ordinary character with no special meaning. With this 64 -flag, 65 -.QW [^ 66 -bracket expressions and 67 -.QW . 68 -never match newline, 69 -.QW ^ 65 +flag, `[^' bracket expressions and `.' never match newline, `^' 70 66 matches an empty string after any newline in addition to its normal 71 -function, and 72 -.QW $ 73 -matches an empty string before any newline in 67 +function, and `$' matches an empty string before any newline in 74 68 addition to its normal function. This flag is equivalent to 75 69 specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the 76 70 \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page). 77 71 .TP 15 78 72 \fB\-linestop\fR 79 -Changes the behavior of 80 -.QW [^ 81 -bracket expressions and 82 -.QW . 83 -so that they 73 +Changes the behavior of `[^' bracket expressions and `.' so that they 84 74 stop at newlines. This is the same as specifying the \fB(?p)\fR 85 75 embedded option (see the \fBre_syntax\fR manual page). 86 76 .TP 15 87 77 \fB\-lineanchor\fR 88 -Changes the behavior of 89 -.QW ^ 90 -and 91 -.QW $ 92 -(the 93 -.QW anchors ) 94 -so they match the 78 +Changes the behavior of `^' and `$' (the ``anchors'') so they match the 95 79 beginning and end of a line respectively. This is the same as 96 80 specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR 97 81 manual page). 98 82 .TP 15 99 83 \fB\-nocase\fR 100 84 Causes upper-case characters in \fIstring\fR to be treated as 101 85 lower case during the matching process. ................................................................................ 110 94 Causes the command to return, as a list, the data that would otherwise 111 95 be placed in match variables. When using \fB-inline\fR, 112 96 match variables may not be specified. If used with \fB-all\fR, the 113 97 list will be concatenated at each iteration, such that a flat list is 114 98 always returned. For each match iteration, the command will append the 115 99 overall match data, plus one element for each subexpression in the 116 100 regular expression. Examples are: 117 -.RS 118 101 .CS 119 -.ta 2i 120 -\fBregexp\fR -inline -- {\\w(\\w)} " inlined " 121 - \fB\(->\fI in n\fR 122 -\fBregexp\fR -all -inline -- {\\w(\\w)} " inlined " 123 - \fB\(->\fI in n li i ne e\fR 102 + regexp -inline -- {\\w(\\w)} " inlined " 103 + => {in n} 104 + regexp -all -inline -- {\\w(\\w)} " inlined " 105 + => {in n li i ne e} 124 106 .CE 125 -.RE 126 107 .TP 15 127 108 \fB\-start\fR \fIindex\fR 128 109 Specifies a character index offset into the string to start 129 110 matching the regular expression at. 130 111 .VS 8.5 131 112 The \fIindex\fR value is interpreted in the same manner 132 113 as the \fIindex\fR argument to \fBstring index\fR. 133 114 .VE 8.5 134 -When using this switch, 135 -.QW ^ 115 +When using this switch, `^' 136 116 will not match the beginning of the line, and \\A will still 137 117 match the start of the string at \fIindex\fR. If \fB\-indices\fR 138 118 is specified, the indices will be indexed starting from the 139 119 absolute beginning of the input string. 140 120 \fIindex\fR will be constrained to the bounds of the input string. 141 121 .TP 15 142 122 \fB\-\|\-\fR 143 123 Marks the end of switches. The argument following this one will 144 124 be treated as \fIexp\fR even if it starts with a \fB\-\fR. 145 125 .PP 146 -If there are more \fIsubMatchVar\fRs than parenthesized 126 +If there are more \fIsubMatchVar\fR's than parenthesized 147 127 subexpressions within \fIexp\fR, or if a particular subexpression 148 128 in \fIexp\fR doesn't match the string (e.g. because it was in a 149 129 portion of the expression that wasn't matched), then the corresponding 150 -\fIsubMatchVar\fR will be set to 151 -.QW "\fB\-1 \-1\fR" 152 -if \fB\-indices\fR has been specified or to an empty string otherwise. 130 +\fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR 131 +has been specified or to an empty string otherwise. 153 132 .SH EXAMPLES 154 133 Find the first occurrence of a word starting with \fBfoo\fR in a 155 134 string that is not actually an instance of \fBfoobar\fR, and get the 156 135 letters following it up to the end of the word into a variable: 157 136 .CS 158 137 \fBregexp\fR {\\<foo(?!bar\\>)(\\w*)} $string \-> restOfWord 159 138 .CE ................................................................................ 173 152 .CE 174 153 .PP 175 154 List all words (consisting of all sequences of non-whitespace 176 155 characters) in a string: 177 156 .CS 178 157 \fBregexp\fR \-all \-inline {\\S+} $string 179 158 .CE 159 + 180 160 .SH "SEE ALSO" 181 161 re_syntax(n), regsub(n), 182 162 .VS 8.5 183 163 string(n) 184 164 .VE 165 + 166 + 185 167 .SH KEYWORDS 186 168 match, regular expression, string
Changes to doc/registry.n.
1 1 '\" 2 2 '\" Copyright (c) 1997 Sun Microsystems, Inc. 3 3 '\" Copyright (c) 2002 ActiveState Corporation. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: registry.n,v 1.16 2007/10/25 14:07:32 dkf Exp $ 8 +'\" RCS: @(#) $Id: registry.n,v 1.17 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH registry n 1.1 registry "Tcl Bundled Packages" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 registry \- Manipulate the Windows registry ................................................................................ 148 148 The registry value contains a null-terminated string. The data is 149 149 represented in Tcl as a string. 150 150 .TP 151 151 \fBexpand_sz\fR 152 152 . 153 153 The registry value contains a null-terminated string that contains 154 154 unexpanded references to environment variables in the normal Windows 155 -style (for example, 156 -.QW "%PATH%" ). 157 -The data is represented in Tcl as a string. 155 +style (for example, "%PATH%"). The data is represented in Tcl as a 156 +string. 158 157 .TP 159 158 \fBdword\fR 160 159 . 161 160 The registry value contains a little-endian 32-bit number. The data is 162 161 represented in Tcl as a decimal string. 163 162 .TP 164 163 \fBdword_big_endian\fR
Changes to doc/regsub.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2000 Scriptics Corporation. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: regsub.n,v 1.18 2007/10/24 14:29:39 dkf Exp $ 9 +'\" RCS: @(#) $Id: regsub.n,v 1.19 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH regsub n 8.3 Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 regsub \- Perform substitutions based on regular expression pattern matching ................................................................................ 27 27 present. 28 28 (Regular expression matching is described in the \fBre_syntax\fR 29 29 reference page.) 30 30 If there is a match, then while copying \fIstring\fR to \fIvarName\fR 31 31 (or to the result of this command if \fIvarName\fR is not present) 32 32 the portion of \fIstring\fR that 33 33 matched \fIexp\fR is replaced with \fIsubSpec\fR. 34 -If \fIsubSpec\fR contains a 35 -.QW & 36 -or 37 -.QW \e0 , 38 -then it is replaced in the substitution with the portion of \fIstring\fR that 34 +If \fIsubSpec\fR contains a ``&'' or ``\e0'', then it is replaced 35 +in the substitution with the portion of \fIstring\fR that 39 36 matched \fIexp\fR. 40 -If \fIsubSpec\fR contains a 41 -.QW \e\fIn\fR , 42 -where \fIn\fR is a digit 37 +If \fIsubSpec\fR contains a ``\e\fIn\fR'', where \fIn\fR is a digit 43 38 between 1 and 9, then it is replaced in the substitution with 44 39 the portion of \fIstring\fR that matched the \fIn\fR-th 45 40 parenthesized subexpression of \fIexp\fR. 46 41 Additional backslashes may be used in \fIsubSpec\fR to prevent special 47 -interpretation of 48 -.QW & 49 -or 50 -.QW \e0 51 -or 52 -.QW \e\fIn\fR 53 -or backslash. 42 +interpretation of ``&'' or ``\e0'' or ``\e\fIn\fR'' or 43 +backslash. 54 44 The use of backslashes in \fIsubSpec\fR tends to interact badly 55 45 with the Tcl parser's use of backslashes, so it's generally 56 46 safest to enclose \fIsubSpec\fR in braces if it includes 57 47 backslashes. 58 48 .LP 59 49 If the initial arguments to \fBregsub\fR start with \fB\-\fR then 60 50 they are treated as switches. The following switches are ................................................................................ 61 51 currently supported: 62 52 .TP 10 63 53 \fB\-all\fR 64 54 All ranges in \fIstring\fR that match \fIexp\fR are found and 65 55 substitution is performed for each of these ranges. 66 56 Without this switch only the first 67 57 matching range is found and substituted. 68 -If \fB\-all\fR is specified, then 69 -.QW & 70 -and 71 -.QW \e\fIn\fR 58 +If \fB\-all\fR is specified, then ``&'' and ``\e\fIn\fR'' 72 59 sequences are handled for each substitution using the information 73 60 from the corresponding match. 74 61 .TP 15 75 62 \fB\-expanded\fR 76 63 Enables use of the expanded regular expression syntax where 77 64 whitespace and comments are ignored. This is the same as specifying 78 65 the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page). 79 66 .TP 15 80 67 \fB\-line\fR 81 68 Enables newline-sensitive matching. By default, newline is a 82 69 completely ordinary character with no special meaning. With this 83 -flag, 84 -.QW [^ 85 -bracket expressions and 86 -.QW . 87 -never match newline, 88 -.QW ^ 70 +flag, `[^' bracket expressions and `.' never match newline, `^' 89 71 matches an empty string after any newline in addition to its normal 90 -function, and 91 -.QW $ 92 -matches an empty string before any newline in 72 +function, and `$' matches an empty string before any newline in 93 73 addition to its normal function. This flag is equivalent to 94 74 specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the 95 75 \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page). 96 76 .TP 15 97 77 \fB\-linestop\fR 98 -Changes the behavior of 99 -.QW [^ 100 -bracket expressions and 101 -.QW . 102 -so that they stop at newlines. This is the same as specifying the \fB(?p)\fR 78 +Changes the behavior of `[^' bracket expressions and `.' so that they 79 +stop at newlines. This is the same as specifying the \fB(?p)\fR 103 80 embedded option (see the \fBre_syntax\fR manual page). 104 81 .TP 15 105 82 \fB\-lineanchor\fR 106 -Changes the behavior of 107 -.QW ^ 108 -and 109 -.QW $ 110 -(the 111 -.QW anchors ) 112 -so they match the 83 +Changes the behavior of `^' and `$' (the ``anchors'') so they match the 113 84 beginning and end of a line respectively. This is the same as 114 85 specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR 115 86 manual page). 116 87 .TP 10 117 88 \fB\-nocase\fR 118 89 Upper-case characters in \fIstring\fR will be converted to lower-case 119 90 before matching against \fIexp\fR; however, substitutions specified ................................................................................ 122 93 \fB\-start\fR \fIindex\fR 123 94 Specifies a character index offset into the string to start 124 95 matching the regular expression at. 125 96 .VS 8.5 126 97 The \fIindex\fR value is interpreted in the same manner 127 98 as the \fIindex\fR argument to \fBstring index\fR. 128 99 .VE 8.5 129 -When using this switch, 130 -.QW ^ 100 +When using this switch, `^' 131 101 will not match the beginning of the line, and \\A will still 132 102 match the start of the string at \fIindex\fR. 133 103 \fIindex\fR will be constrained to the bounds of the input string. 134 104 .TP 10 135 105 \fB\-\|\-\fR 136 106 Marks the end of switches. The argument following this one will 137 107 be treated as \fIexp\fR even if it starts with a \fB\-\fR.
Changes to doc/return.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Contributions from Don Porter, NIST, 2003. (not subject to US copyright) 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: return.n,v 1.13 2007/10/25 09:49:18 dkf Exp $ 9 +'\" RCS: @(#) $Id: return.n,v 1.14 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH return n 8.5 Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 return \- Return from a procedure, or set return code of a script ................................................................................ 17 17 .SH SYNOPSIS 18 18 \fBreturn \fR?\fIresult\fR? 19 19 .sp 20 20 \fBreturn \fR?\fB-code \fIcode\fR? ?\fIresult\fR? 21 21 .sp 22 22 \fBreturn \fR?\fIoption value \fR...? ?\fIresult\fR? 23 23 .BE 24 + 24 25 .SH DESCRIPTION 25 26 .PP 26 27 In its simplest usage, the \fBreturn\fR command is used without options 27 28 in the body of a procedure to immediately return control to the caller 28 29 of the procedure. If a \fIresult\fR argument is provided, its value 29 30 becomes the result of the procedure passed back to the caller. 30 31 If \fIresult\fR is not specified then an empty string will be returned ................................................................................ 36 37 the \fBreturn\fR command will cause script evaluation 37 38 to immediately cease, and the value \fIresult\fR (or an empty string) 38 39 will be returned as the result of the \fBsource\fR command. 39 40 .SH "EXCEPTIONAL RETURN CODES" 40 41 .PP 41 42 In addition to the result of a procedure, the return 42 43 code of a procedure may also be set by \fBreturn\fR 43 -through use of the \fB\-code\fR option. 44 +through use of the \fB-code\fR option. 44 45 In the usual case where the \fB\-code\fR option isn't 45 46 specified the procedure will return normally. 46 47 However, the \fB\-code\fR option may be used to generate an 47 48 exceptional return from the procedure. 48 49 \fICode\fR may have any of the following values: 49 50 .TP 13 50 -\fBok (\fRor \fB0)\fR 51 +\fBok (or 0)\fR 51 52 Normal return: same as if the option is omitted. The return code 52 53 of the procedure is 0 (\fBTCL_OK\fR). 53 54 .TP 13 54 55 \fBerror (1)\fR 55 56 Error return: the return code of the procedure is 1 (\fBTCL_ERROR\fR). 56 57 The procedure command behaves in its calling context as if it 57 58 were the command \fBerror \fIresult\fR. See below for additional ................................................................................ 73 74 were the command \fBcontinue\fR. 74 75 .TP 13 75 76 \fIvalue\fR 76 77 \fIValue\fR must be an integer; it will be returned as the 77 78 return code for the current procedure. 78 79 .LP 79 80 When a procedure wants to signal that it has received invalid 80 -arguments from its caller, it may use 81 -.QW "\fBreturn \-code error\fR" 81 +arguments from its caller, it may use \fBreturn -code error\fR 82 82 with \fIresult\fR set to a suitable error message. Otherwise 83 83 usage of the \fBreturn -code\fR option is mostly limited to 84 84 procedures that implement a new control structure. 85 85 .PP 86 86 The \fBreturn -code\fR command acts similarly within script 87 87 files that are evaluated by the \fBsource\fR command. During the 88 88 evaluation of the contents of a file as a script by \fBsource\fR, 89 -an invocation of the 90 -.QW "\fBreturn -code \fIcode\fR" 91 -command will cause the return code of \fBsource\fR to be \fIcode\fR. 89 +an invocation of the \fBreturn -code \fIcode\fR command will cause 90 +the return code of \fBsource\fR to be \fIcode\fR. 92 91 .SH "RETURN OPTIONS" 93 92 .PP 94 93 .VS 8.5 95 94 In addition to a result and a return code, evaluation of a command 96 95 in Tcl also produces a dictionary of return options. In general 97 96 usage, all \fIoption value\fR pairs given as arguments to \fBreturn\fR 98 97 become entries in the return options dictionary, and any values at all 99 98 are acceptable except as noted below. The \fBcatch\fR command may be 100 -used to capture all of this information \(em the return code, the result, 101 -and the return options dictionary \(em that arise from evaluation of a script. 99 +used to capture all of this information -- the return code, the result, 100 +and the return options dictionary -- that arise from evaluation of a script. 102 101 .VE 8.5 103 102 .PP 104 -As documented above, the \fB\-code\fR entry in the return options dictionary 103 +As documented above, the \fB-code\fR entry in the return options dictionary 105 104 receives special treatment by Tcl. There are other return options also 106 105 recognized and treated specially by Tcl. They are: 107 106 .TP 108 -\fB\-errorcode \fIlist\fR 109 -The \fB\-errorcode\fR option receives special treatment only when the value 110 -of the \fB\-code\fR option is \fBTCL_ERROR\fR. Then the \fIlist\fR value 107 +\fB-errorcode \fIlist\fR 108 +The \fB-errorcode\fR option receives special treatment only when the value 109 +of the \fB-code\fR option is \fBTCL_ERROR\fR. Then the \fIlist\fR value 111 110 is meant to be additional information about the error, 112 111 presented as a Tcl list for further processing by programs. 113 -If no \fB\-errorcode\fR option is provided to \fBreturn\fR when 114 -the \fB\-code error\fR option is provided, Tcl will set the value 115 -of the \fB\-errorcode\fR entry in the return options dictionary 116 -to the default value of \fBNONE\fR. The \fB\-errorcode\fR return 112 +If no \fB-errorcode\fR option is provided to \fBreturn\fR when 113 +the \fB-code error\fR option is provided, Tcl will set the value 114 +of the \fB-errorcode\fR entry in the return options dictionary 115 +to the default value of \fBNONE\fR. The \fB-errorcode\fR return 117 116 option will also be stored in the global variable \fBerrorCode\fR. 118 117 .TP 119 -\fB\-errorinfo \fIinfo\fR 120 -The \fB\-errorinfo\fR option receives special treatment only when the value 121 -of the \fB\-code\fR option is \fBTCL_ERROR\fR. Then \fIinfo\fR is the initial 118 +\fB-errorinfo \fIinfo\fR 119 +The \fB-errorinfo\fR option receives special treatment only when the value 120 +of the \fB-code\fR option is \fBTCL_ERROR\fR. Then \fIinfo\fR is the initial 122 121 stack trace, meant to provide to a human reader additional information 123 122 about the context in which the error occurred. The stack trace will 124 123 also be stored in the global variable \fBerrorInfo\fR. 125 -If no \fB\-errorinfo\fR option is provided to \fBreturn\fR when 126 -the \fB\-code error\fR option is provided, Tcl will provide its own 127 -initial stack trace value in the entry for \fB\-errorinfo\fR. Tcl's 124 +If no \fB-errorinfo\fR option is provided to \fBreturn\fR when 125 +the \fB-code error\fR option is provided, Tcl will provide its own 126 +initial stack trace value in the entry for \fB-errorinfo\fR. Tcl's 128 127 initial stack trace will include only the call to the procedure, and 129 128 stack unwinding will append information about higher stack levels, but 130 129 there will be no information about the context of the error within 131 130 the procedure. Typically the \fIinfo\fR value is supplied from 132 -the value of \fB\-errorinfo\fR in a return options dictionary captured 131 +the value of \fB-errorinfo\fR in a return options dictionary captured 133 132 by the \fBcatch\fR command (or from the copy of that information 134 133 stored in the global variable \fBerrorInfo\fR). 135 134 .TP 136 -\fB\-level \fIlevel\fR 135 +\fB-level \fIlevel\fR 137 136 .VS 8.5 138 -The \fB\-level\fR and \fB\-code\fR options work together to set the return 137 +The \fB-level\fR and \fB-code\fR options work together to set the return 139 138 code to be returned by one of the commands currently being evaluated. 140 139 The \fIlevel\fR value must be a non-negative integer representing a number 141 140 of levels on the call stack. It defines the number of levels up the stack 142 141 at which the return code of a command currently being evaluated should 143 -be \fIcode\fR. If no \fB\-level\fR option is provided, the default value 142 +be \fIcode\fR. If no \fB-level\fR option is provided, the default value 144 143 of \fIlevel\fR is 1, so that \fBreturn\fR sets the return code that the 145 144 current procedure returns to its caller, 1 level up the call stack. The 146 145 mechanism by which these options work is described in more detail below. 147 146 .VE 8.5 148 147 .TP 149 -\fB\-options \fIoptions\fR 148 +\fB-options \fIoptions\fR 150 149 .VS 8.5 151 150 The value \fIoptions\fR must be a valid dictionary. The entries of that 152 151 dictionary are treated as additional \fIoption value\fR pairs for the 153 152 \fBreturn\fR command. 154 153 .VE 8.5 155 154 .SH "RETURN CODE HANDLING MECHANISMS" 156 155 .PP ................................................................................ 166 165 of the call stack. It is also the mechanism by which commands 167 166 like \fBbreak\fR, \fBcontinue\fR, and \fBreturn\fR cause script 168 167 evaluation to terminate without evaluating all commands in sequence. 169 168 .PP 170 169 Some of Tcl's built-in commands evaluate scripts as part of their 171 170 functioning. These commands can make use of exceptional return 172 171 codes to enable special features. For example, the built-in 173 -Tcl commands that provide loops \(em such as \fBwhile\fR, \fBfor\fR, 174 -and \fBforeach\fR \(em evaluate a script that is the body of the 172 +Tcl commands that provide loops -- such as \fBwhile\fR, \fBfor\fR, 173 +and \fBforeach\fR -- evaluate a script that is the body of the 175 174 loop. If evaluation of the loop body returns the return code 176 175 of \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR, the loop command can react in such 177 176 a way as to give the \fBbreak\fR and \fBcontinue\fR commands 178 177 their documented interpretation in loops. 179 178 .PP 180 179 .VS 8.5 181 180 Procedure invocation also involves evaluation of a script, the body 182 181 of the procedure. Procedure invocation provides special treatment 183 182 when evaluation of the procedure body returns the return code 184 -\fBTCL_RETURN\fR. In that circumstance, the \fB\-level\fR entry in the 183 +\fBTCL_RETURN\fR. In that circumstance, the \fB-level\fR entry in the 185 184 return options dictionary is decremented. If after decrementing, 186 -the value of the \fB\-level\fR entry is 0, then the value of 187 -the \fB\-code\fR entry becomes the return code of the procedure. 188 -If after decrementing, the value of the \fB\-level\fR entry is 185 +the value of the \fB-level\fR entry is 0, then the value of 186 +the \fB-code\fR entry becomes the return code of the procedure. 187 +If after decrementing, the value of the \fB-level\fR entry is 189 188 greater than zero, then the return code of the procedure is 190 189 \fBTCL_RETURN\fR. If the procedure invocation occurred during the 191 190 evaluation of the body of another procedure, the process will 192 191 repeat itself up the call stack, decrementing the value of the 193 -\fB\-level\fR entry at each level, so that the \fIcode\fR will 192 +\fB-level\fR entry at each level, so that the \fIcode\fR will 194 193 be the return code of the current command \fIlevel\fR levels 195 194 up the call stack. The \fBsource\fR command performs the 196 195 same handling of the \fBTCL_RETURN\fR return code, which explains 197 196 the similarity of \fBreturn\fR invocation during a \fBsource\fR 198 197 to \fBreturn\fR invocation within a procedure. 199 198 .PP 200 199 The return code of the \fBreturn\fR command itself triggers this 201 200 special handling by procedure invocation. If \fBreturn\fR 202 -is provided the option \fB\-level 0\fR, then the return code 201 +is provided the option \fB-level 0\fR, then the return code 203 202 of the \fBreturn\fR command itself will be the value \fIcode\fR 204 -of the \fB\-code\fR option (or \fBTCL_OK\fR by default). Any other value 205 -for the \fB\-level\fR option (including the default value of 1) 203 +of the \fB-code\fR option (or \fBTCL_OK\fR by default). Any other value 204 +for the \fB-level\fR option (including the default value of 1) 206 205 will cause the return code of the \fBreturn\fR command itself 207 206 to be \fBTCL_RETURN\fR, triggering a return from the enclosing procedure. 208 207 .VE 8.5 209 208 .SH EXAMPLES 210 209 First, a simple example of using \fBreturn\fR to return from a 211 210 procedure, interrupting the procedure body. 212 211 .CS ................................................................................ 220 219 Next, an example of using \fBreturn\fR to set the value 221 220 returned by the procedure. 222 221 .CS 223 222 proc returnX {} {\fBreturn\fR X} 224 223 puts [returnX] ;# prints "X" 225 224 .CE 226 225 .PP 227 -Next, a more complete example, using 228 -.QW "\fBreturn \-code error\fR" 226 +Next, a more complete example, using \fBreturn -code error\fR 229 227 to report invalid arguments. 230 228 .CS 231 229 proc factorial {n} { 232 230 if {![string is integer $n] || ($n < 0)} { 233 - \fBreturn\fR -code error \e 234 - "expected non-negative integer,\e 235 - but got \e"$n\e"" 231 + \fBreturn\fR -code error \\ 232 + "expected non-negative integer,\\ 233 + but got \\"$n\\"" 236 234 } 237 235 if {$n < 2} { 238 236 \fBreturn\fR 1 239 237 } 240 238 set m [expr {$n - 1}] 241 239 set code [catch {factorial $m} factor] 242 240 if {$code != 0} { 243 241 \fBreturn\fR -code $code $factor 244 242 } 245 243 set product [expr {$n * $factor}] 246 244 if {$product < 0} { 247 - \fBreturn\fR -code error \e 245 + \fBreturn\fR -code error \\ 248 246 "overflow computing factorial of $n" 249 247 } 250 248 \fBreturn\fR $product 251 249 } 252 250 .CE 253 251 .PP 254 252 Next, a procedure replacement for \fBbreak\fR. ................................................................................ 255 253 .CS 256 254 proc myBreak {} { 257 255 \fBreturn\fR -code break 258 256 } 259 257 .CE 260 258 .PP 261 259 .VS 8.5 262 -With the \fB\-level 0\fR option, \fBreturn\fR itself can serve 260 +With the \fB-level 0\fR option, \fBreturn\fR itself can serve 263 261 as a replacement for \fBbreak\fR. 264 262 .CS 265 263 interp alias {} Break {} \fBreturn\fR -level 0 -code break 266 264 .CE 267 265 .PP 268 -An example of using \fBcatch\fR and \fBreturn \-options\fR to 266 +An example of using \fBcatch\fR and \fBreturn -options\fR to 269 267 re-raise a caught error: 270 268 .CS 271 269 proc doSomething {} { 272 270 set resource [allocate] 273 271 catch { 274 272 # Long script of operations 275 273 # that might raise an error ................................................................................ 290 288 } 291 289 set options [dict merge {-level 1} $args] 292 290 dict incr options -level 293 291 \fBreturn\fR -options $options $result 294 292 } 295 293 .CE 296 294 .VE 8.5 295 + 297 296 .SH "SEE ALSO" 298 -break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), 299 -tclvars(n) 297 +break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n) 298 + 300 299 .SH KEYWORDS 301 300 break, catch, continue, error, procedure, return
Changes to doc/scan.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2000 Scriptics Corporation. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: scan.n,v 1.20 2007/10/24 14:29:39 dkf Exp $ 9 +'\" RCS: @(#) $Id: scan.n,v 1.21 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH scan n 8.4 Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 scan \- Parse string using conversion specifiers in the style of sscanf ................................................................................ 56 56 first skips any white-space characters in \fIstring\fR (unless the 57 57 conversion character is \fB[\fR or \fBc\fR). 58 58 Then it converts the next input characters according to the 59 59 conversion specifier and stores the result in the variable given 60 60 by the next argument to \fBscan\fR. 61 61 .PP 62 62 If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in 63 -.QW \fB%2$d\fR , 64 -then the variable to use is not taken from the next 63 +``\fB%2$d\fR'', then the variable to use is not taken from the next 65 64 sequential argument. Instead, it is taken from the argument indicated 66 65 by the number, where 1 corresponds to the first \fIvarName\fR. If 67 66 there are any positional specifiers in \fIformat\fR then all of the 68 67 specifiers must be positional. Every \fIvarName\fR on the argument 69 68 list must correspond to exactly one conversion specifier or an error 70 69 is generated, or in the inline case, any position can be specified 71 70 at most once and the empty positions will be filled in with empty strings.
Changes to doc/source.n.
2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2000 Scriptics Corporation. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: source.n,v 1.13 2007/10/25 14:07:32 dkf Exp $ 9 +'\" RCS: @(#) $Id: source.n,v 1.14 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH source n "" Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 source \- Evaluate a file or resource as a Tcl script ................................................................................ 17 17 .SH SYNOPSIS 18 18 \fBsource \fIfileName\fR 19 19 .sp 20 20 .VS 8.5 21 21 \fBsource\fR \fB\-encoding \fIencodingName fileName\fR 22 22 .VE 8.5 23 23 .BE 24 + 24 25 .SH DESCRIPTION 25 26 .PP 26 27 This command takes the contents of the specified file or resource 27 28 and passes it to the Tcl interpreter as a text script. The return 28 29 value from \fBsource\fR is the return value of the last command 29 30 executed in the script. If an error occurs in evaluating the contents 30 31 of the script then the \fBsource\fR command will return that error. 31 32 If a \fBreturn\fR command is invoked from within the script then the 32 33 remainder of the file will be skipped and the \fBsource\fR command 33 34 will return normally with the result from the \fBreturn\fR command. 34 35 .PP 35 -The end-of-file character for files is 36 -.QW \e032 37 -(^Z) for all platforms. The source command will read files up to this 38 -character. This 36 +The end-of-file character for files is '\\32' (^Z) for all platforms. 37 +The source command will read files up to this character. This 39 38 restriction does not exist for the \fBread\fR or \fBgets\fR commands, 40 39 allowing for files containing code and data segments (scripted documents). 41 -If you require a 42 -.QW ^Z 43 -in code for string comparison, you can use 44 -.QW \e032 45 -or 46 -.QW \eu001a , 47 -which will be safely substituted by the Tcl 48 -interpreter into 49 -.QW ^Z . 40 +If you require a ``^Z'' in code for string comparison, you can use 41 +``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl 42 +interpreter into ``^Z''. 50 43 .PP 51 44 .VS 8.5 52 45 The \fB-encoding\fR option is used to specify the encoding of 53 46 the data stored in \fIfileName\fR. When the \fB-encoding\fR option 54 47 is omitted, the system encoding is assumed. 55 48 .VE 8.5 56 49 .SH EXAMPLE 57 50 Run the script in the file \fBfoo.tcl\fR and then the script in the 58 51 file \fBbar.tcl\fR: 59 52 .CS 60 53 \fBsource\fR foo.tcl 61 54 \fBsource\fR bar.tcl 62 55 .CE 63 -.PP 64 56 Alternatively: 65 57 .CS 66 58 foreach scriptFile {foo.tcl bar.tcl} { 67 59 \fBsource\fR $scriptFile 68 60 } 69 61 .CE 62 + 70 63 .SH "SEE ALSO" 71 64 file(n), cd(n), encoding(n), info(n) 65 + 72 66 .SH KEYWORDS 73 67 file, script
Changes to doc/split.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: split.n,v 1.6 2007/10/25 09:25:27 dkf Exp $ 8 +'\" RCS: @(#) $Id: split.n,v 1.7 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH split n "" Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 split \- Split a string into a proper Tcl list 16 16 .SH SYNOPSIS 17 17 \fBsplit \fIstring \fR?\fIsplitChars\fR? 18 18 .BE 19 + 19 20 .SH DESCRIPTION 20 21 .PP 21 22 Returns a list created by splitting \fIstring\fR at each character 22 23 that is in the \fIsplitChars\fR argument. 23 24 Each element of the result list will consist of the 24 25 characters from \fIstring\fR that lie between instances of the 25 26 characters in \fIsplitChars\fR. ................................................................................ 28 29 character of \fIstring\fR is in \fIsplitChars\fR. 29 30 If \fIsplitChars\fR is an empty string then each character of 30 31 \fIstring\fR becomes a separate element of the result list. 31 32 \fISplitChars\fR defaults to the standard white-space characters. 32 33 .SH EXAMPLES 33 34 Divide up a USENET group name into its hierarchical components: 34 35 .CS 35 -.ta 2i 36 36 \fBsplit\fR "comp.lang.tcl.announce" . 37 - \fB\(->\fI comp lang tcl announce\fR 37 + \fI=> comp lang tcl announce\fR 38 38 .CE 39 39 .PP 40 40 See how the \fBsplit\fR command splits on \fIevery\fR character in 41 41 \fIsplitChars\fR, which can result in information loss if you are not 42 42 careful: 43 43 .CS 44 -.ta 2i 45 44 \fBsplit\fR "alpha beta gamma" "temp" 46 - \fB\(->\fI al {ha b} {} {a ga} {} a\fR 45 + \fI=> al {ha b} {} {a ga} {} a\fR 47 46 .CE 48 47 .PP 49 48 Extract the list words from a string that is not a well-formed list: 50 49 .CS 51 -.ta 2i 52 50 \fBsplit\fR "Example with {unbalanced brace character" 53 - \fB\(->\fI Example with \\{unbalanced brace character\fR 51 + \fI=> Example with \\{unbalanced brace character\fR 54 52 .CE 55 53 .PP 56 54 Split a string into its constituent characters 57 55 .CS 58 -.ta 2i 59 56 \fBsplit\fR "Hello world" {} 60 - \fB\(->\fI H e l l o { } w o r l d\fR 57 + \fI=> H e l l o { } w o r l d\fR 61 58 .CE 62 59 .SS "PARSING RECORD-ORIENTED FILES" 63 60 Parse a Unix /etc/passwd file, which consists of one entry per line, 64 61 with each line consisting of a colon-separated list of fields: 65 62 .CS 66 63 ## Read the file 67 64 set fid [open /etc/passwd] ................................................................................ 79 76 80 77 ## Assign fields to variables and print some out... 81 78 lassign $fields \\ 82 79 userName password uid grp longName homeDir shell 83 80 puts "$longName uses [file tail $shell] for a login shell" 84 81 } 85 82 .CE 83 + 86 84 .SH "SEE ALSO" 87 85 join(n), list(n), string(n) 86 + 88 87 .SH KEYWORDS 89 88 list, split, string
Changes to doc/string.n.
1 1 .\" 2 2 .\" Copyright (c) 1993 The Regents of the University of California. 3 3 .\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 .\" 5 5 .\" See the file "license.terms" for information on usage and redistribution 6 6 .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 .\" 8 -.\" RCS: @(#) $Id: string.n,v 1.37 2007/10/25 14:07:32 dkf Exp $ 8 +.\" RCS: @(#) $Id: string.n,v 1.38 2007/10/26 20:11:53 dgp Exp $ 9 9 .\" 10 10 .so man.macros 11 11 .TH string n 8.1 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 .\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 string \- Manipulate strings 16 16 .SH SYNOPSIS 17 17 \fBstring \fIoption arg \fR?\fIarg ...?\fR 18 18 .BE 19 + 19 20 .SH DESCRIPTION 20 21 .PP 21 22 Performs one of several string operations, depending on \fIoption\fR. 22 23 The legal \fIoption\fRs (which may be abbreviated) are: 23 24 .TP 24 25 \fBstring bytelength \fIstring\fR 25 -. 26 26 Returns a decimal string giving the number of bytes used to represent 27 27 \fIstring\fR in memory. Because UTF\-8 uses one to three bytes to 28 28 represent Unicode characters, the byte length will not be the same as 29 29 the character length in general. The cases where a script cares about 30 30 the byte length are rare. In almost all cases, you should use the 31 31 \fBstring length\fR operation (including determining the length of a 32 32 Tcl ByteArray object). Refer to the \fBTcl_NumUtfChars\fR manual 33 33 entry for more details on the UTF\-8 representation. 34 34 .TP 35 35 \fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length int\fR? \fIstring1 string2\fR 36 -. 37 36 Perform a character-by-character comparison of strings \fIstring1\fR 38 37 and \fIstring2\fR. Returns \-1, 0, or 1, depending on whether 39 38 \fIstring1\fR is lexicographically less than, equal to, or greater 40 39 than \fIstring2\fR. If \fB\-length\fR is specified, then only the 41 40 first \fIlength\fR characters are used in the comparison. If 42 41 \fB\-length\fR is negative, it is ignored. If \fB\-nocase\fR is 43 42 specified, then the strings are compared in a case-insensitive manner. 44 43 .TP 45 44 \fBstring equal\fR ?\fB\-nocase\fR? ?\fB-length int\fR? \fIstring1 string2\fR 46 -. 47 45 Perform a character-by-character comparison of strings \fIstring1\fR 48 46 and \fIstring2\fR. Returns 1 if \fIstring1\fR and \fIstring2\fR are 49 47 identical, or 0 when not. If \fB\-length\fR is specified, then only 50 48 the first \fIlength\fR characters are used in the comparison. If 51 49 \fB\-length\fR is negative, it is ignored. If \fB\-nocase\fR is 52 50 specified, then the strings are compared in a case-insensitive manner. 53 51 .TP 54 52 \fBstring first \fIneedleString haystackString\fR ?\fIstartIndex\fR? 55 -. 56 53 Search \fIhaystackString\fR for a sequence of characters that exactly match 57 54 the characters in \fIneedleString\fR. If found, return the index of the 58 55 first character in the first such match within \fIhaystackString\fR. If not 59 56 found, return \-1. If \fIstartIndex\fR is specified (in any of the 60 57 forms accepted by the \fBindex\fR method), then the search is 61 58 constrained to start with the character in \fIhaystackString\fR specified by 62 59 the index. For example, ................................................................................ 68 65 .CS 69 66 \fBstring first a 0123456789abcdef 11\fR 70 67 .CE 71 68 will return \fB\-1\fR. 72 69 .RE 73 70 .TP 74 71 \fBstring index \fIstring charIndex\fR 75 -. 76 72 Returns the \fIcharIndex\fR'th character of the \fIstring\fR argument. 77 73 A \fIcharIndex\fR of 0 corresponds to the first character of the 78 74 string. \fIcharIndex\fR may be specified as follows: 79 75 .VS 8.5 80 76 .RS 81 77 .IP \fIinteger\fR 10 82 78 For any index value that passes \fBstring is integer -strict\fR, 83 79 the char specified at this integral index 84 -(e.g. \fB2\fR would refer to the 85 -.QW "c" 86 -in 87 -.QW "abcd" ). 80 +(e.g. \fB2\fR would refer to the "c" in "abcd"). 88 81 .IP \fBend\fR 10 89 82 The last char of the string 90 -(e.g. \fBend\fR would refer to the 91 -.QW "d" 92 -in 93 -.QW "abcd" ). 83 +(e.g. \fBend\fR would refer to the "d" in "abcd"). 94 84 .IP \fBend\fR\-\fIN\fR 10 95 85 The last char of the string minus the specified integer offset \fIN\fR 96 -(e.g. \fBend\fR\-1 would refer to the 97 -.QW "c" 98 -in 99 -.QW "abcd" ). 86 +(e.g. \fBend\fR\-1 would refer to the "c" in "abcd"). 100 87 .IP \fBend\fR+\fIN\fR 10 101 88 The last char of the string plus the specified integer offset \fIN\fR 102 -(e.g. \fBend\fR+\-1 would refer to the 103 -.QW "c" 104 -in 105 -"abcd" ). 89 +(e.g. \fBend\fR+\-1 would refer to the "c" in "abcd"). 106 90 .IP \fIM\fR+\fIN\fR 10 107 91 The char specified at the integral index that is the sum of 108 92 integer values \fIM\fR and \fIN\fR 109 -(e.g. \fB1+1\fR would refer to the 110 -.QW "c" 111 -in 112 -.QW "abcd" ). 93 +(e.g. \fB1+1\fR would refer to the "c" in "abcd"). 113 94 .IP \fIM\fR\-\fIN\fR 10 114 95 The char specified at the integral index that is the difference of 115 96 integer values \fIM\fR and \fIN\fR 116 -(e.g. \fB2\-1\fR would refer to the 117 -.QW "b" 118 -in 119 -.QW "abcd" ). 97 +(e.g. \fB2\-1\fR would refer to the "b" in "abcd"). 120 98 .PP 121 99 In the specifications above, the integer value \fIM\fR contains no 122 100 trailing whitespace and the integer value \fIN\fR contains no 123 101 leading whitespace. 124 102 .PP 125 103 If \fIcharIndex\fR is less than 0 or greater than or equal to the 126 104 length of the string then this command returns an empty string. 127 105 .RE 128 106 .VE 129 107 .TP 130 108 \fBstring is \fIclass\fR ?\fB\-strict\fR? ?\fB\-failindex \fIvarname\fR? \fIstring\fR 131 -. 132 109 Returns 1 if \fIstring\fR is a valid member of the specified character 133 110 class, otherwise returns 0. If \fB\-strict\fR is specified, then an 134 111 empty string returns 0, otherwise an empty string will return 1 on 135 112 any class. If \fB\-failindex\fR is specified, then if the function 136 113 returns 0, the index in the string where the class was no longer valid 137 114 will be stored in the variable named \fIvarname\fR. The \fIvarname\fR 138 115 will not be set if the function returns 1. The following character ................................................................................ 164 141 .IP \fBinteger\fR 12 165 142 Any of the valid string formats for a 32-bit integer value in Tcl, 166 143 with optional surrounding whitespace. In case of under/overflow in 167 144 the value, 0 is returned and the \fIvarname\fR will contain \-1. 168 145 .IP \fBlist\fR 12 169 146 Any proper list structure, with optional surrounding whitespace. In 170 147 case of improper list structure, 0 is returned and the \fIvarname\fR 171 -will contain the index of the 172 -.QW element 173 -where the list parsing fails, or \-1 if this cannot be determined. 148 +will contain the index of the "element" where the list parsing fails, 149 +or \-1 if this cannot be determined. 174 150 .IP \fBlower\fR 12 175 151 Any Unicode lower case alphabet character. 176 152 .IP \fBprint\fR 12 177 153 Any Unicode printing character, including space. 178 154 .IP \fBpunct\fR 12 179 155 Any Unicode punctuation character. 180 156 .IP \fBspace\fR 12 ................................................................................ 198 174 .PP 199 175 In the case of \fBboolean\fR, \fBtrue\fR and \fBfalse\fR, if the 200 176 function will return 0, then the \fIvarname\fR will always be set to 201 177 0, due to the varied nature of a valid boolean value. 202 178 .RE 203 179 .TP 204 180 \fBstring last \fIneedleString haystackString\fR ?\fIlastIndex\fR? 205 -. 206 181 Search \fIhaystackString\fR for a sequence of characters that exactly match 207 182 the characters in \fIneedleString\fR. If found, return the index of the 208 183 first character in the last such match within \fIhaystackString\fR. If there 209 184 is no match, then return \-1. If \fIlastIndex\fR is specified (in any 210 185 of the forms accepted by the \fBindex\fR method), then only the 211 186 characters in \fIhaystackString\fR at or before the specified \fIlastIndex\fR 212 187 will be considered by the search. For example, ................................................................................ 218 193 .CS 219 194 \fBstring last a 0a23456789abcdef 9\fR 220 195 .CE 221 196 will return \fB1\fR. 222 197 .RE 223 198 .TP 224 199 \fBstring length \fIstring\fR 225 -. 226 200 Returns a decimal string giving the number of characters in 227 201 \fIstring\fR. Note that this is not necessarily the same as the 228 202 number of bytes used to store the string. If the object is a 229 203 ByteArray object (such as those returned from reading a binary encoded 230 204 channel), then this will return the actual byte length of the object. 231 205 .TP 232 206 \fBstring map\fR ?\fB\-nocase\fR? \fImapping string\fR 233 -. 234 207 Replaces substrings in \fIstring\fR based on the key-value pairs in 235 208 \fImapping\fR. \fImapping\fR is a list of \fIkey value key value ...\fR 236 209 as in the form returned by \fBarray get\fR. Each instance of a 237 210 key in the string will be replaced with its corresponding value. If 238 211 \fB\-nocase\fR is specified, then matching is done without regard to 239 212 case differences. Both \fIkey\fR and \fIvalue\fR may be multiple 240 213 characters. Replacement is done in an ordered manner, so the key ................................................................................ 253 226 .CS 254 227 \fBstring map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc\fR 255 228 .CE 256 229 it will return the string \fB02c322c222c\fR. 257 230 .RE 258 231 .TP 259 232 \fBstring match\fR ?\fB\-nocase\fR? \fIpattern\fR \fIstring\fR 260 -. 261 233 See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0 if 262 234 it doesn't. If \fB\-nocase\fR is specified, then the pattern attempts 263 235 to match against the string in a case insensitive manner. For the two 264 236 strings to match, their contents must be identical except that the 265 237 following special sequences may appear in \fIpattern\fR: 266 238 .RS 267 239 .IP \fB*\fR 10 ................................................................................ 270 242 .IP \fB?\fR 10 271 243 Matches any single character in \fIstring\fR. 272 244 .IP \fB[\fIchars\fB]\fR 10 273 245 Matches any character in the set given by \fIchars\fR. If a sequence 274 246 of the form \fIx\fB\-\fIy\fR appears in \fIchars\fR, then any 275 247 character between \fIx\fR and \fIy\fR, inclusive, will match. When 276 248 used with \fB\-nocase\fR, the end points of the range are converted to 277 -lower case first. Whereas 278 -.QW [A\-z] 279 -matches 280 -.QW _ 281 -when matching case-sensitively (since 282 -.QW _ 283 -falls between the 284 -.QW Z 285 -and 286 -.QW a ), 287 -with \fB\-nocase\fR this is considered like 288 -.QW [A\-Za\-z] 289 -(and probably what was meant in the first place). 249 +lower case first. Whereas {[A\-z]} matches '_' when matching 250 +case-sensitively ('_' falls between the 'Z' and 'a'), with 251 +\fB\-nocase\fR this is considered like {[A\-Za\-z]} (and probably what 252 +was meant in the first place). 290 253 .IP \fB\e\fIx\fR 10 291 -Matches the single character \fIx\fR. This provides a way of avoiding 254 +Matches the single character \fIx\fR. This provides a way of avoiding 292 255 the special interpretation of the characters \fB*?[]\e\fR in 293 256 \fIpattern\fR. 294 257 .RE 295 258 .TP 296 259 \fBstring range \fIstring first last\fR 297 -. 298 260 Returns a range of consecutive characters from \fIstring\fR, starting 299 261 with the character whose index is \fIfirst\fR and ending with the 300 262 character whose index is \fIlast\fR. An index of 0 refers to the first 301 263 character of the string. \fIfirst\fR and \fIlast\fR may be specified 302 264 as for the \fBindex\fR method. If \fIfirst\fR is less than zero then 303 265 it is treated as if it were zero, and if \fIlast\fR is greater than or 304 266 equal to the length of the string then it is treated as if it were 305 267 \fBend\fR. If \fIfirst\fR is greater than \fIlast\fR then an empty 306 268 string is returned. 307 269 .TP 308 270 \fBstring repeat \fIstring count\fR 309 -. 310 -Returns the concatenation of \fIstring\fR repeated \fIcount\fR number 311 -of times. 271 +Returns \fIstring\fR repeated \fIcount\fR number of times. 312 272 .TP 313 273 \fBstring replace \fIstring first last\fR ?\fInewstring\fR? 314 -. 315 274 Removes a range of consecutive characters from \fIstring\fR, starting 316 275 with the character whose index is \fIfirst\fR and ending with the 317 276 character whose index is \fIlast\fR. An index of 0 refers to the 318 277 first character of the string. \fIFirst\fR and \fIlast\fR may be 319 278 specified as for the \fBindex\fR method. If \fInewstring\fR is 320 279 specified, then it is placed in the removed character range. If 321 280 \fIfirst\fR is less than zero then it is treated as if it were zero, 322 281 and if \fIlast\fR is greater than or equal to the length of the string 323 282 then it is treated as if it were \fBend\fR. If \fIfirst\fR is greater 324 283 than \fIlast\fR or the length of the initial string, or \fIlast\fR is 325 284 less than 0, then the initial string is returned untouched. 285 +.VS 8.5 326 286 .TP 327 287 \fBstring reverse \fIstring\fR 328 -. 329 -.VS 8.5 330 288 Returns a string that is the same length as \fIstring\fR but with its 331 289 characters in the reverse order. 332 290 .VE 8.5 333 291 .TP 334 292 \fBstring tolower \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? 335 -. 336 293 Returns a value equal to \fIstring\fR except that all upper (or title) 337 294 case letters have been converted to lower case. If \fIfirst\fR is 338 295 specified, it refers to the first char index in the string to start 339 296 modifying. If \fIlast\fR is specified, it refers to the char index in 340 297 the string to stop at (inclusive). \fIfirst\fR and \fIlast\fR may be 341 298 specified as for the \fBindex\fR method. 342 299 .TP 343 300 \fBstring totitle \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? 344 -. 345 301 Returns a value equal to \fIstring\fR except that the first character 346 302 in \fIstring\fR is converted to its Unicode title case variant (or 347 303 upper case if there is no title case variant) and the rest of the 348 304 string is converted to lower case. If \fIfirst\fR is specified, it 349 305 refers to the first char index in the string to start modifying. If 350 306 \fIlast\fR is specified, it refers to the char index in the string to 351 307 stop at (inclusive). \fIfirst\fR and \fIlast\fR may be specified as 352 308 for the \fBindex\fR method. 353 309 .TP 354 310 \fBstring toupper \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? 355 -. 356 311 Returns a value equal to \fIstring\fR except that all lower (or title) 357 312 case letters have been converted to upper case. If \fIfirst\fR is 358 313 specified, it refers to the first char index in the string to start 359 314 modifying. If \fIlast\fR is specified, it refers to the char index in 360 315 the string to stop at (inclusive). \fIfirst\fR and \fIlast\fR may be 361 316 specified as for the \fBindex\fR method. 362 317 .TP 363 318 \fBstring trim \fIstring\fR ?\fIchars\fR? 364 -. 365 319 Returns a value equal to \fIstring\fR except that any leading or 366 320 trailing characters present in the string given by \fIchars\fR are removed. If 367 321 \fIchars\fR is not specified then white space is removed (spaces, 368 322 tabs, newlines, and carriage returns). 369 323 .TP 370 324 \fBstring trimleft \fIstring\fR ?\fIchars\fR? 371 -. 372 325 Returns a value equal to \fIstring\fR except that any leading 373 326 characters present in the string given by \fIchars\fR are removed. If 374 327 \fIchars\fR is not specified then white space is removed (spaces, 375 328 tabs, newlines, and carriage returns). 376 329 .TP 377 330 \fBstring trimright \fIstring\fR ?\fIchars\fR? 378 -. 379 331 Returns a value equal to \fIstring\fR except that any trailing 380 332 characters present in the string given by \fIchars\fR are removed. If 381 333 \fIchars\fR is not specified then white space is removed (spaces, 382 334 tabs, newlines, and carriage returns). 383 335 .TP 384 336 \fBstring wordend \fIstring charIndex\fR 385 -. 386 337 Returns the index of the character just after the last one in the word 387 338 containing character \fIcharIndex\fR of \fIstring\fR. \fIcharIndex\fR 388 339 may be specified as for the \fBindex\fR method. A word is 389 340 considered to be any contiguous range of alphanumeric (Unicode letters 390 341 or decimal digits) or underscore (Unicode connector punctuation) 391 342 characters, or any single character other than these. 392 343 .TP 393 344 \fBstring wordstart \fIstring charIndex\fR 394 -. 395 345 Returns the index of the first character in the word containing 396 346 character \fIcharIndex\fR of \fIstring\fR. \fIcharIndex\fR may be 397 347 specified as for the \fBindex\fR method. A word is considered to be any 398 348 contiguous range of alphanumeric (Unicode letters or decimal digits) 399 349 or underscore (Unicode connector punctuation) characters, or any 400 350 single character other than these. 401 351 .SH EXAMPLE ................................................................................ 405 355 set length [\fBstring length\fR $string] 406 356 if {$length == 0} { 407 357 set isPrefix 0 408 358 } else { 409 359 set isPrefix [\fBstring equal\fR -length $length $string "foobar"] 410 360 } 411 361 .CE 362 + 412 363 .SH "SEE ALSO" 413 364 expr(n), list(n) 365 + 414 366 .SH KEYWORDS 415 367 case conversion, compare, index, match, pattern, string, word, equal, 416 368 ctype, character, reverse 369 + 417 370 .\" Local Variables: 418 371 .\" mode: nroff 419 372 .\" End:
Changes to doc/subst.n.
2 2 '\" Copyright (c) 1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" Copyright (c) 2001 Donal K. Fellows 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -'\" RCS: @(#) $Id: subst.n,v 1.11 2007/10/26 12:25:06 dkf Exp $ 9 +'\" RCS: @(#) $Id: subst.n,v 1.12 2007/10/26 20:11:53 dgp Exp $ 10 10 '\" 11 11 .so man.macros 12 12 .TH subst n 7.4 Tcl "Tcl Built-In Commands" 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 16 subst \- Perform backslash, command, and variable substitutions ................................................................................ 52 52 raised the exception. If a continue exception occurs during the 53 53 evaluation of a command or variable substitution, an empty string 54 54 will be substituted for that entire command or variable substitution 55 55 (as long as it is well-formed Tcl.) If a return exception occurs, 56 56 or any other return code is returned during command or variable 57 57 substitution, then the returned value is substituted for that 58 58 substitution. See the EXAMPLES below. In this way, all exceptional 59 -return codes are 60 -.QW caught 61 -by \fBsubst\fR. The \fBsubst\fR command 59 +return codes are ``caught'' by \fBsubst\fR. The \fBsubst\fR command 62 60 itself will either return an error, or will complete successfully. 63 61 .SH EXAMPLES 64 62 .PP 65 63 When it performs its substitutions, \fIsubst\fR does not give any 66 64 special treatment to double quotes or curly braces (except within 67 65 command substitutions) so the script 68 66 .CS 69 67 set a 44 70 68 \fBsubst\fR {xyz {$a}} 71 69 .CE 72 -returns 73 -.QW "\fBxyz {44}\fR" , 74 -not 75 -.QW "\fBxyz {$a}\fR" 70 +returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR'' 76 71 and the script 77 72 .CS 78 -set a "p\e} q \e{r" 73 +set a "p\\} q \\{r" 79 74 \fBsubst\fR {xyz {$a}} 80 75 .CE 81 -return 82 -.QW "\fBxyz {p} q {r}\fR" , 83 -not 84 -.QW "\fBxyz {p\e} q \e{r}\fR" . 76 +return ``\fBxyz {p} q {r}\fR'', not ``\fBxyz {p\\} q \\{r}\fR''. 85 77 .PP 86 78 When command substitution is performed, it includes any variable 87 79 substitution necessary to evaluate the script. 88 80 .CS 89 81 set a 44 90 82 \fBsubst\fR -novariables {$a [format $a]} 91 83 .CE 92 -returns 93 -.QW "\fB$a 44\fR" , 94 -not 95 -.QW "\fB$a $a\fR" . 96 -Similarly, when 84 +returns ``\fB$a 44\fR'', not ``\fB$a $a\fR''. Similarly, when 97 85 variable substitution is performed, it includes any command 98 86 substitution necessary to retrieve the value of the variable. 99 87 .CS 100 88 proc b {} {return c} 101 89 array set a {c c [b] tricky} 102 90 \fBsubst\fR -nocommands {[b] $a([b])} 103 91 .CE 104 -returns 105 -.QW "\fB[b] c\fR" , 106 -not 107 -.QW "\fB[b] tricky\fR". 92 +returns ``\fB[b] c\fR'', not ``\fB[b] tricky\fR''. 108 93 .PP 109 94 The continue and break exceptions allow command substitutions to 110 95 prevent substitution of the rest of the command substitution and the 111 96 rest of \fIstring\fR respectively, giving script authors more options 112 97 when processing text using \fIsubst\fR. For example, the script 113 98 .CS 114 99 \fBsubst\fR {abc,[break],def} 115 100 .CE 116 -returns 117 -.QW \fBabc,\fR , 118 -not 119 -.QW \fBabc,,def\fR 120 -and the script 101 +returns ``\fBabc,\fR'', not ``\fBabc,,def\fR'' and the script 121 102 .CS 122 103 \fBsubst\fR {abc,[continue;expr {1+2}],def} 123 104 .CE 124 -returns 125 -.QW \fBabc,,def\fR , 126 -not 127 -.QW \fBabc,3,def\fR . 105 +returns ``\fBabc,,def\fR'', not ``\fBabc,3,def\fR''. 128 106 .PP 129 107 Other exceptional return codes substitute the returned value 130 108 .CS 131 109 \fBsubst\fR {abc,[return foo;expr {1+2}],def} 132 110 .CE 133 -returns 134 -.QW \fBabc,foo,def\fR , 135 -not 136 -.QW \fBabc,3,def\fR 137 -and 111 +returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR'' and 138 112 .CS 139 113 \fBsubst\fR {abc,[return -code 10 foo;expr {1+2}],def} 140 114 .CE 141 -also returns 142 -.QW \fBabc,foo,def\fR , 143 -not 144 -.QW \fBabc,3,def\fR . 115 +also returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR''. 116 + 145 117 .SH "SEE ALSO" 146 118 Tcl(n), eval(n), break(n), continue(n) 147 119 148 120 .SH KEYWORDS 149 121 backslash substitution, command substitution, variable substitution
Changes to doc/switch.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: switch.n,v 1.11 2007/10/24 14:29:39 dkf Exp $ 8 +'\" RCS: @(#) $Id: switch.n,v 1.12 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH switch n 8.5 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 switch \- Evaluate one of several scripts, depending on a given value ................................................................................ 98 98 since the braces around the whole list make it unnecessary to include a 99 99 backslash at the end of each line. 100 100 Since the \fIpattern\fR arguments are in braces in the second form, 101 101 no command or variable substitutions are performed on them; this makes 102 102 the behavior of the second form different than the first form in some 103 103 cases. 104 104 .PP 105 -If a \fIbody\fR is specified as 106 -.QW \fB\-\fR 107 -it means that the \fIbody\fR 105 +If a \fIbody\fR is specified as ``\fB\-\fR'' it means that the \fIbody\fR 108 106 for the next pattern should also be used as the body for this 109 -pattern (if the next pattern also has a body of 110 -.QW \fB\-\fR 107 +pattern (if the next pattern also has a body of ``\fB\-\fR'' 111 108 then the body after that is used, and so on). 112 109 This feature makes it possible to share a single \fIbody\fR among 113 110 several patterns. 114 111 .PP 115 112 Beware of how you place comments in \fBswitch\fR commands. Comments 116 113 should only be placed \fBinside\fR the execution body of one of the 117 114 patterns, and not intermingled with the patterns.
Changes to doc/tclsh.1.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: tclsh.1,v 1.11 2007/10/24 14:29:39 dkf Exp $ 8 +'\" RCS: @(#) $Id: tclsh.1,v 1.12 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH tclsh 1 "" Tcl "Tcl Applications" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 tclsh \- Simple shell containing Tcl interpreter ................................................................................ 44 44 read Tcl commands from the named file; \fBtclsh\fR will exit 45 45 when it reaches the end of the file. 46 46 The end of the file may be marked either by the physical end of 47 47 the medium, or by the character, '\\032' ('\\u001a', control-Z). 48 48 If this character is present in the file, the \fBtclsh\fR application 49 49 will read text up to but not including the character. An application 50 50 that requires this character in the file may safely encode it as 51 -.QW \e032 , 52 -.QW \ex1a , 53 -or 54 -.QW \eu001a ; 55 -or may generate it by use of commands 51 +``\\032'', ``\\x1a'', or ``\\u001a''; or may generate it by use of commands 56 52 such as \fBformat\fR or \fBbinary\fR. 57 53 There is no automatic evaluation of \fB.tclshrc\fR when the name 58 54 of a script file is presented on the \fBtclsh\fR command 59 55 line, but the script file can always \fBsource\fR it if desired. 60 56 .PP 61 57 If you create a Tcl script in a file whose first line is 62 58 .CS ................................................................................ 123 119 Contains 1 if \fBtclsh\fR is running interactively (no 124 120 \fIfileName\fR was specified and standard input is a terminal-like 125 121 device), 0 otherwise. 126 122 127 123 .SH PROMPTS 128 124 .PP 129 125 When \fBtclsh\fR is invoked interactively it normally prompts for each 130 -command with 131 -.QW "\fB% \fR" . 132 -You can change the prompt by setting the 126 +command with ``\fB% \fR''. You can change the prompt by setting the 133 127 variables \fBtcl_prompt1\fR and \fBtcl_prompt2\fR. If variable 134 128 \fBtcl_prompt1\fR exists then it must consist of a Tcl script 135 129 to output a prompt; instead of outputting a prompt \fBtclsh\fR 136 130 will evaluate the script in \fBtcl_prompt1\fR. 137 131 The variable \fBtcl_prompt2\fR is used in a similar way when 138 132 a newline is typed but the current command isn't yet complete; 139 133 if \fBtcl_prompt2\fR isn't set then no prompt is output for
Changes to doc/tcltest.n.
4 4 '\" Copyright (c) 1998-1999 Scriptics Corporation 5 5 '\" Copyright (c) 2000 Ajuba Solutions 6 6 '\" Contributions from Don Porter, NIST, 2002. (not subject to US copyright) 7 7 '\" 8 8 '\" See the file "license.terms" for information on usage and redistribution 9 9 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 10 10 '\" 11 -'\" RCS: @(#) $Id: tcltest.n,v 1.50 2007/10/25 14:07:32 dkf Exp $ 11 +'\" RCS: @(#) $Id: tcltest.n,v 1.51 2007/10/26 20:11:53 dgp Exp $ 12 12 '\" 13 13 .so man.macros 14 14 .TH "tcltest" n 2.3 tcltest "Tcl Bundled Packages" 15 15 .BS 16 16 '\" Note: do not modify the .SH NAME line immediately below! 17 17 .SH NAME 18 18 tcltest \- Test harness support code and utilities ................................................................................ 75 75 tcltest package. 76 76 .PP 77 77 All the commands provided by the \fBtcltest\fR package are defined 78 78 in and exported from the \fB::tcltest\fR namespace, as indicated in 79 79 the \fBSYNOPSIS\fR above. In the following sections, all commands 80 80 will be described by their simple names, in the interest of brevity. 81 81 .PP 82 -The central command of \fBtcltest\fR is \fBtest\fR that defines 83 -and runs a test. Testing with \fBtest\fR involves evaluation 82 +The central command of \fBtcltest\fR is [\fBtest\fR] that defines 83 +and runs a test. Testing with [\fBtest\fR] involves evaluation 84 84 of a Tcl script and comparing the result to an expected result, as 85 85 configured and controlled by a number of options. Several other 86 86 commands provided by \fBtcltest\fR govern the configuration of 87 -\fBtest\fR and the collection of many \fBtest\fR commands into 87 +[\fBtest\fR] and the collection of many [\fBtest\fR] commands into 88 88 test suites. 89 89 .PP 90 90 See \fBCREATING TEST SUITES WITH TCLTEST\fR below for an extended example 91 91 of how to use the commands of \fBtcltest\fR to produce test suites 92 92 for your Tcl-enabled code. 93 93 .SH COMMANDS 94 94 .TP 95 95 \fBtest\fR \fIname description ?option value ...?\fR 96 96 Defines and possibly runs a test with the name \fIname\fR and 97 97 description \fIdescription\fR. The name and description of a test 98 -are used in messages reported by \fBtest\fR during the 98 +are used in messages reported by [\fBtest\fR] during the 99 99 test, as configured by the options of \fBtcltest\fR. The 100 -remaining \fIoption value\fR arguments to \fBtest\fR 100 +remaining \fIoption value\fR arguments to [\fBtest\fR] 101 101 define the test, including the scripts to run, the conditions 102 102 under which to run them, the expected result, and the means 103 103 by which the expected and actual results should be compared. 104 104 See \fBTESTS\fR below for a complete description of the valid 105 -options and how they define a test. The \fBtest\fR command 105 +options and how they define a test. The [\fBtest\fR] command 106 106 returns an empty string. 107 107 .TP 108 108 \fBtest\fR \fIname description ?constraints? body result\fR 109 -. 110 -This form of \fBtest\fR is provided to support test suites written 109 +This form of [\fBtest\fR] is provided to support test suites written 111 110 for version 1 of the \fBtcltest\fR package, and also a simpler 112 111 interface for a common usage. It is the same as 113 -.QW "\fBtest\fR \fIname description\fB \-constraints \fIconstraints\fB \-body \fIbody\fB \-result \fIresult\fR" . 114 -All other options to \fBtest\fR 112 +[\fBtest\fR \fIname description\fB -constraints \fIconstraints\fB -body 113 +\fIbody\fB -result \fIresult\fR]. All other options to [\fBtest\fR] 115 114 take their default values. When \fIconstraints\fR is omitted, this 116 -form of \fBtest\fR can be distinguished from the first because 117 -all \fIoption\fRs begin with 118 -.QW \- . 115 +form of [\fBtest\fR] can be distinguished from the first because 116 +all \fIoption\fRs begin with ``-''. 119 117 .TP 120 118 \fBloadTestedCommands\fR 121 119 Evaluates in the caller's context the script specified by 122 -\fBconfigure \-load\fR or \fBconfigure \-loadfile\fR. 120 +[\fBconfigure -load\fR] or [\fBconfigure -loadfile\fR]. 123 121 Returns the result of that script evaluation, including any error 124 122 raised by the script. Use this command and the related 125 123 configuration options to provide the commands to be tested to 126 124 the interpreter running the test suite. 127 125 .TP 128 126 \fBmakeFile\fR \fIcontents name ?directory?\fR 129 127 Creates a file named \fIname\fR relative to 130 128 directory \fIdirectory\fR and write \fIcontents\fR 131 -to that file using the encoding \fBencoding system\fR. 129 +to that file using the encoding [\fBencoding system\fR]. 132 130 If \fIcontents\fR does not end with a newline, a newline 133 131 will be appended so that the file named \fIname\fR 134 132 does end with a newline. Because the system encoding is used, 135 133 this command is only suitable for making text files. 136 134 The file will be removed by the next evaluation 137 -of \fBcleanupTests\fR, unless it is removed by 138 -\fBremoveFile\fR first. The default value of 139 -\fIdirectory\fR is the directory \fBconfigure -tmpdir\fR. 135 +of [\fBcleanupTests\fR], unless it is removed by 136 +[\fBremoveFile\fR] first. The default value of 137 +\fIdirectory\fR is the directory [\fBconfigure -tmpdir\fR]. 140 138 Returns the full path of the file created. Use this command 141 139 to create any text file required by a test with contents as needed. 142 140 .TP 143 141 \fBremoveFile\fR \fIname ?directory?\fR 144 142 Forces the file referenced by \fIname\fR to be removed. This file name 145 143 should be relative to \fIdirectory\fR. The default value of 146 -\fIdirectory\fR is the directory \fBconfigure -tmpdir\fR. 144 +\fIdirectory\fR is the directory [\fBconfigure -tmpdir\fR]. 147 145 Returns an empty string. Use this command to delete files 148 -created by \fBmakeFile\fR. 146 +created by [\fBmakeFile\fR]. 149 147 .TP 150 148 \fBmakeDirectory\fR \fIname ?directory?\fR 151 149 Creates a directory named \fIname\fR relative to directory \fIdirectory\fR. 152 -The directory will be removed by the next evaluation of \fBcleanupTests\fR, 153 -unless it is removed by \fBremoveDirectory\fR first. 150 +The directory will be removed by the next evaluation of [\fBcleanupTests\fR], 151 +unless it is removed by [\fBremoveDirectory\fR] first. 154 152 The default value of \fIdirectory\fR is the directory 155 -\fBconfigure -tmpdir\fR. 153 +[\fBconfigure -tmpdir\fR]. 156 154 Returns the full path of the directory created. Use this command 157 155 to create any directories that are required to exist by a test. 158 156 .TP 159 157 \fBremoveDirectory\fR \fIname ?directory?\fR 160 158 Forces the directory referenced by \fIname\fR to be removed. This 161 159 directory should be relative to \fIdirectory\fR. 162 160 The default value of \fIdirectory\fR is the directory 163 -\fBconfigure -tmpdir\fR. 161 +[\fBconfigure -tmpdir\fR]. 164 162 Returns an empty string. Use this command to delete any directories 165 -created by \fBmakeDirectory\fR. 163 +created by [\fBmakeDirectory\fR]. 166 164 .TP 167 165 \fBviewFile\fR \fIfile ?directory?\fR 168 166 Returns the contents of \fIfile\fR, except for any 169 -final newline, just as \fBread -nonewline\fR would return. 167 +final newline, just as [\fBread -nonewline\fR] would return. 170 168 This file name should be relative to \fIdirectory\fR. 171 169 The default value of \fIdirectory\fR is the directory 172 -\fBconfigure -tmpdir\fR. Use this command 170 +[\fBconfigure -tmpdir\fR]. Use this command 173 171 as a convenient way to turn the contents of a file generated 174 172 by a test into the result of that test for matching against 175 173 an expected result. The contents of the file are read using 176 174 the system encoding, so its usefulness is limited to text 177 175 files. 178 176 .TP 179 177 \fBcleanupTests\fR 180 178 Intended to clean up and summarize after several tests have been 181 179 run. Typically called once per test file, at the end of the file 182 180 after all tests have been completed. For best effectiveness, be 183 -sure that the \fBcleanupTests\fR is evaluated even if an error 181 +sure that the [\fBcleanupTests\fR] is evaluated even if an error 184 182 occurs earlier in the test file evaluation. 185 183 .sp 186 184 Prints statistics about the tests run and removes files that were 187 -created by \fBmakeDirectory\fR and \fBmakeFile\fR since the 188 -last \fBcleanupTests\fR. Names of files and directories 189 -in the directory \fBconfigure -tmpdir\fR created since 190 -the last \fBcleanupTests\fR, but not created by 191 -\fBmakeFile\fR or \fBmakeDirectory\fR are printed 192 -to \fBoutputChannel\fR. This command also restores the original 185 +created by [\fBmakeDirectory\fR] and [\fBmakeFile\fR] since the 186 +last [\fBcleanupTests\fR]. Names of files and directories 187 +in the directory [\fBconfigure -tmpdir\fR] created since 188 +the last [\fBcleanupTests\fR], but not created by 189 +[\fBmakeFile\fR] or [\fBmakeDirectory\fR] are printed 190 +to [\fBoutputChannel\fR]. This command also restores the original 193 191 shell environment, as described by the ::env 194 192 array. Returns an empty string. 195 193 .TP 196 194 \fBrunAllTests\fR 197 195 This is a master command meant to run an entire suite of tests, 198 196 spanning multiple files and/or directories, as governed by 199 197 the configurable options of \fBtcltest\fR. See \fBRUNNING ALL TESTS\fR 200 198 below for a complete description of the many variations possible 201 -with \fBrunAllTests\fR. 199 +with [\fBrunAllTests\fR]. 202 200 .SH "CONFIGURATION COMMANDS" 203 201 .TP 204 202 \fBconfigure\fR 205 203 Returns the list of configurable options supported by \fBtcltest\fR. 206 204 See \fBCONFIGURABLE OPTIONS\fR below for the full list of options, 207 205 their valid values, and their effect on \fBtcltest\fR operations. 208 206 .TP ................................................................................ 212 210 .TP 213 211 \fBconfigure \fIoption value ?option value ...?\fR 214 212 Sets the value of each configurable option \fIoption\fR to the 215 213 corresponding value \fIvalue\fR, in order. Raises an error if 216 214 an \fIoption\fR is not a supported configurable option, or if 217 215 \fIvalue\fR is not a valid value for the corresponding \fIoption\fR, 218 216 or if a \fIvalue\fR is not provided. When an error is raised, the 219 -operation of \fBconfigure\fR is halted, and subsequent \fIoption value\fR 217 +operation of [\fBconfigure\fR] is halted, and subsequent \fIoption value\fR 220 218 arguments are not processed. 221 219 .sp 222 220 If the environment variable \fB::env(TCLTEST_OPTIONS)\fR exists when 223 -the \fBtcltest\fR package is loaded (by 224 -.QW "\fBpackage require tcltest\fR" ) 225 -then its value is taken as a list of arguments to pass to \fBconfigure\fR. 221 +the \fBtcltest\fR package is loaded (by [\fBpackage require tcltest\fR]) 222 +then its value is taken as a list of arguments to pass to [\fBconfigure\fR]. 226 223 This allows the default values of the configuration options to be 227 224 set by the environment. 228 225 .TP 229 226 \fBcustomMatch \fImode script\fR 230 -Registers \fImode\fR as a new legal value of the \fB\-match\fR option 231 -to \fBtest\fR. When the \fB\-match \fImode\fR option is 232 -passed to \fBtest\fR, the script \fIscript\fR will be evaluated 227 +Registers \fImode\fR as a new legal value of the \fB-match\fR option 228 +to [\fBtest\fR]. When the \fB-match \fImode\fR option is 229 +passed to [\fBtest\fR], the script \fIscript\fR will be evaluated 233 230 to compare the actual result of evaluating the body of the test 234 231 to the expected result. 235 232 To perform the match, the \fIscript\fR is completed with two additional 236 233 words, the expected result, and the actual result, and the completed script 237 234 is evaluated in the global namespace. 238 235 The completed script is expected to return a boolean value indicating 239 236 whether or not the results match. The built-in matching modes of 240 -\fBtest\fR are \fBexact\fR, \fBglob\fR, and \fBregexp\fR. 237 +[\fBtest\fR] are \fBexact\fR, \fBglob\fR, and \fBregexp\fR. 241 238 .TP 242 239 \fBtestConstraint \fIconstraint ?boolean?\fR 243 240 Sets or returns the boolean value associated with the named \fIconstraint\fR. 244 241 See \fBTEST CONSTRAINTS\fR below for more information. 245 242 .TP 246 243 \fBinterpreter\fR \fI?executableName?\fR 247 -Sets or returns the name of the executable to be \fBexec\fRed by 248 -\fBrunAllTests\fR to run each test file when 249 -\fBconfigure -singleproc\fR is false. 250 -The default value for \fBinterpreter\fR is the name of the 251 -currently running program as returned by \fBinfo nameofexecutable\fR. 244 +Sets or returns the name of the executable to be [\fBexec\fR]ed by 245 +[\fBrunAllTests\fR] to run each test file when 246 +[\fBconfigure -singleproc\fR] is false. 247 +The default value for [\fBinterpreter\fR] is the name of the 248 +currently running program as returned by [\fBinfo nameofexecutable\fR]. 252 249 .TP 253 250 \fBoutputChannel\fR \fI?channelID?\fR 254 251 Sets or returns the output channel ID. This defaults to stdout. 255 252 Any test that prints test related output should send 256 -that output to \fBoutputChannel\fR rather than letting 253 +that output to [\fBoutputChannel\fR] rather than letting 257 254 that output default to stdout. 258 255 .TP 259 256 \fBerrorChannel\fR \fI?channelID?\fR 260 257 Sets or returns the error channel ID. This defaults to stderr. 261 258 Any test that prints error messages should send 262 -that output to \fBerrorChannel\fR rather than printing 259 +that output to [\fBerrorChannel\fR] rather than printing 263 260 directly to stderr. 264 261 .SH "SHORTCUT COMMANDS" 265 262 .TP 266 263 \fBdebug \fI?level?\fR 267 -Same as \fBconfigure -debug \fI?level?\fR. 264 +Same as [\fBconfigure -debug \fI?level?\fR]. 268 265 .TP 269 266 \fBerrorFile \fI?filename?\fR 270 -Same as \fBconfigure -errfile \fI?filename?\fR. 267 +Same as [\fBconfigure -errfile \fI?filename?\fR]. 271 268 .TP 272 269 \fBlimitConstraints \fI?boolean?\fR 273 -Same as \fBconfigure -limitconstraints \fI?boolean?\fR. 270 +Same as [\fBconfigure -limitconstraints \fI?boolean?\fR]. 274 271 .TP 275 272 \fBloadFile \fI?filename?\fR 276 -Same as \fBconfigure -loadfile \fI?filename?\fR. 273 +Same as [\fBconfigure -loadfile \fI?filename?\fR]. 277 274 .TP 278 275 \fBloadScript \fI?script?\fR 279 -Same as \fBconfigure -load \fI?script?\fR. 276 +Same as [\fBconfigure -load \fI?script?\fR]. 280 277 .TP 281 278 \fBmatch \fI?patternList?\fR 282 -Same as \fBconfigure -match \fI?patternList?\fR. 279 +Same as [\fBconfigure -match \fI?patternList?\fR]. 283 280 .TP 284 281 \fBmatchDirectories \fI?patternList?\fR 285 -Same as \fBconfigure -relateddir \fI?patternList?\fR. 282 +Same as [\fBconfigure -relateddir \fI?patternList?\fR]. 286 283 .TP 287 284 \fBmatchFiles \fI?patternList?\fR 288 -Same as \fBconfigure -file \fI?patternList?\fR. 285 +Same as [\fBconfigure -file \fI?patternList?\fR]. 289 286 .TP 290 287 \fBoutputFile \fI?filename?\fR 291 -Same as \fBconfigure -outfile \fI?filename?\fR. 288 +Same as [\fBconfigure -outfile \fI?filename?\fR]. 292 289 .TP 293 290 \fBpreserveCore \fI?level?\fR 294 -Same as \fBconfigure -preservecore \fI?level?\fR. 291 +Same as [\fBconfigure -preservecore \fI?level?\fR]. 295 292 .TP 296 293 \fBsingleProcess \fI?boolean?\fR 297 -Same as \fBconfigure -singleproc \fI?boolean?\fR. 294 +Same as [\fBconfigure -singleproc \fI?boolean?\fR]. 298 295 .TP 299 296 \fBskip \fI?patternList?\fR 300 -Same as \fBconfigure -skip \fI?patternList?\fR. 297 +Same as [\fBconfigure -skip \fI?patternList?\fR]. 301 298 .TP 302 299 \fBskipDirectories \fI?patternList?\fR 303 -Same as \fBconfigure -asidefromdir \fI?patternList?\fR. 300 +Same as [\fBconfigure -asidefromdir \fI?patternList?\fR]. 304 301 .TP 305 302 \fBskipFiles \fI?patternList?\fR 306 -Same as \fBconfigure -notfile \fI?patternList?\fR. 303 +Same as [\fBconfigure -notfile \fI?patternList?\fR]. 307 304 .TP 308 305 \fBtemporaryDirectory \fI?directory?\fR 309 -Same as \fBconfigure -tmpdir \fI?directory?\fR. 306 +Same as [\fBconfigure -tmpdir \fI?directory?\fR]. 310 307 .TP 311 308 \fBtestsDirectory \fI?directory?\fR 312 -Same as \fBconfigure -testdir \fI?directory?\fR. 309 +Same as [\fBconfigure -testdir \fI?directory?\fR]. 313 310 .TP 314 311 \fBverbose \fI?level?\fR 315 -Same as \fBconfigure -verbose \fI?level?\fR. 312 +Same as [\fBconfigure -verbose \fI?level?\fR]. 316 313 .SH "OTHER COMMANDS" 317 314 .PP 318 315 The remaining commands provided by \fBtcltest\fR have better 319 316 alternatives provided by \fBtcltest\fR or \fBTcl\fR itself. They 320 317 are retained to support existing test suites, but should be avoided 321 318 in new code. 322 319 .TP 323 320 \fBtest\fR \fIname description optionList\fR 324 -This form of \fBtest\fR was provided to enable passing many 325 -options spanning several lines to \fBtest\fR as a single 321 +This form of [\fBtest\fR] was provided to enable passing many 322 +options spanning several lines to [\fBtest\fR] as a single 326 323 argument quoted by braces, rather than needing to backslash quote 327 -the newlines between arguments to \fBtest\fR. The \fIoptionList\fR 324 +the newlines between arguments to [\fBtest\fR]. The \fIoptionList\fR 328 325 argument is expected to be a list with an even number of elements 329 326 representing \fIoption\fR and \fIvalue\fR arguments to pass 330 -to \fBtest\fR. However, these values are not passed directly, as 331 -in the alternate forms of \fBswitch\fR. Instead, this form makes 327 +to [\fBtest\fR]. However, these values are not passed directly, as 328 +in the alternate forms of [\fBswitch\fR]. Instead, this form makes 332 329 an unfortunate attempt to overthrow Tcl's substitution rules by 333 330 performing substitutions on some of the list elements as an attempt to 334 -implement a 335 -.QW "do what I mean" 336 -interpretation of a brace-enclosed 337 -.QW block . 338 -The result is nearly impossible to document clearly, and 331 +implement a ``do what I mean'' interpretation of a brace-enclosed 332 +``block''. The result is nearly impossible to document clearly, and 339 333 for that reason this form is not recommended. See the examples in 340 334 \fBCREATING TEST SUITES WITH TCLTEST\fR below to see that this 341 335 form is really not necessary to avoid backslash-quoted newlines. 342 336 If you insist on using this form, examine 343 337 the source code of \fBtcltest\fR if you want to know the substitution 344 338 details, or just enclose the third through last argument 345 -to \fBtest\fR in braces and hope for the best. 339 +to [\fBtest\fR] in braces and hope for the best. 346 340 .TP 347 341 \fBworkingDirectory\fR \fI?directoryName?\fR 348 342 Sets or returns the current working directory when the test suite is 349 343 running. The default value for workingDirectory is the directory in 350 -which the test suite was launched. The Tcl commands \fBcd\fR and 351 -\fBpwd\fR are sufficient replacements. 344 +which the test suite was launched. The Tcl commands [\fBcd\fR] and 345 +[\fBpwd\fR] are sufficient replacements. 352 346 .TP 353 347 \fBnormalizeMsg\fR \fImsg\fR 354 -Returns the result of removing the 355 -.QW extra 356 -newlines from \fImsg\fR, where 357 -.QW extra 358 -is rather imprecise. Tcl offers plenty of string 348 +Returns the result of removing the ``extra'' newlines from \fImsg\fR, 349 +where ``extra'' is rather imprecise. Tcl offers plenty of string 359 350 processing commands to modify strings as you wish, and 360 -\fBcustomMatch\fR allows flexible matching of actual and expected 351 +[\fBcustomMatch\fR] allows flexible matching of actual and expected 361 352 results. 362 353 .TP 363 354 \fBnormalizePath\fR \fIpathVar\fR 364 355 Resolves symlinks in a path, thus creating a path without internal 365 356 redirection. It is assumed that \fIpathVar\fR is absolute. 366 -\fIpathVar\fR is modified in place. The Tcl command \fBfile normalize\fR 357 +\fIpathVar\fR is modified in place. The Tcl command [\fBfile normalize\fR] 367 358 is a sufficient replacement. 368 359 .TP 369 360 \fBbytestring\fR \fIstring\fR 370 361 Construct a string that consists of the requested sequence of bytes, 371 362 as opposed to a string of properly formed UTF-8 characters using the 372 363 value supplied in \fIstring\fR. This allows the tester to create 373 364 denormalized or improperly formed strings to pass to C procedures that 374 365 are supposed to accept strings with embedded NULL types and confirm 375 366 that a string result has a certain pattern of bytes. This is 376 -exactly equivalent to the Tcl command \fBencoding convertfrom identity\fR. 367 +exactly equivalent to the Tcl command [\fBencoding convertfrom identity\fR]. 377 368 .SH TESTS 378 369 .PP 379 -The \fBtest\fR command is the heart of the \fBtcltest\fR package. 370 +The [\fBtest\fR] command is the heart of the \fBtcltest\fR package. 380 371 Its essential function is to evaluate a Tcl script and compare 381 -the result with an expected result. The options of \fBtest\fR 372 +the result with an expected result. The options of [\fBtest\fR] 382 373 define the test script, the environment in which to evaluate it, 383 374 the expected result, and how the compare the actual result to 384 375 the expected result. Some configuration options of \fBtcltest\fR 385 -also influence how \fBtest\fR operates. 376 +also influence how [\fBtest\fR] operates. 386 377 .PP 387 -The valid options for \fBtest\fR are summarized: 378 +The valid options for [\fBtest\fR] are summarized: 388 379 .PP 389 380 .CS 390 381 \fBtest\fR \fIname\fR \fIdescription\fR 391 382 ?-constraints \fIkeywordList|expression\fR? 392 383 ?-setup \fIsetupScript\fR? 393 384 ?-body \fItestScript\fR? 394 385 ?-cleanup \fIcleanupScript\fR? ................................................................................ 399 390 ?-match \fImode\fR? 400 391 .CE 401 392 .PP 402 393 The \fIname\fR may be any string. It is conventional to choose 403 394 a \fIname\fR according to the pattern: 404 395 .PP 405 396 .CS 406 -\fItarget\fR\-\fImajorNum\fR.\fIminorNum\fR 397 +\fItarget\fR-\fImajorNum\fR.\fIminorNum\fR 407 398 .CE 408 399 .PP 409 400 For white-box (regression) tests, the target should be the name of the 410 401 C function or Tcl procedure being tested. For black-box tests, the 411 402 target should be the name of the feature being tested. Some conventions 412 403 call for the names of black-box tests to have the suffix \fB_bb\fR. 413 404 Related tests should share a major number. As a test suite evolves, 414 405 it is best to have the same test name continue to correspond to the 415 -same test, so that it remains meaningful to say things like 416 -.QW "Test foo-1.3 passed in all releases up to 3.4, but began failing in release 3.5." 406 +same test, so that it remains meaningful to say things like ``Test 407 +foo-1.3 passed in all releases up to 3.4, but began failing in 408 +release 3.5.'' 417 409 .PP 418 -During evaluation of \fBtest\fR, the \fIname\fR will be compared 410 +During evaluation of [\fBtest\fR], the \fIname\fR will be compared 419 411 to the lists of string matching patterns returned by 420 -\fBconfigure -match\fR, and \fBconfigure -skip\fR. The test 412 +[\fBconfigure -match\fR], and [\fBconfigure -skip\fR]. The test 421 413 will be run only if \fIname\fR matches any of the patterns from 422 -\fBconfigure -match\fR and matches none of the patterns 423 -from \fBconfigure -skip\fR. 414 +[\fBconfigure -match\fR] and matches none of the patterns 415 +from [\fBconfigure -skip\fR]. 424 416 .PP 425 417 The \fIdescription\fR should be a short textual description of the 426 418 test. The \fIdescription\fR is included in output produced by the 427 419 test, typically test failure messages. Good \fIdescription\fR values 428 420 should briefly explain the purpose of the test to users of a test suite. 429 421 The name of a Tcl or C function being tested should be included in the 430 422 description for regression tests. If the test case exists to reproduce 431 423 a bug, include the bug ID in the description. 432 424 .PP 433 425 Valid attributes and associated values are: 434 426 .TP 435 -\fB\-constraints \fIkeywordList|expression\fR 436 -The optional \fB\-constraints\fR attribute can be list of one or more 437 -keywords or an expression. If the \fB\-constraints\fR value is a list of 427 +\fB-constraints \fIkeywordList|expression\fR 428 +The optional \fB-constraints\fR attribute can be list of one or more 429 +keywords or an expression. If the \fB-constraints\fR value is a list of 438 430 keywords, each of these keywords should be the name of a constraint 439 -defined by a call to \fBtestConstraint\fR. If any of the listed 431 +defined by a call to [\fBtestConstraint\fR]. If any of the listed 440 432 constraints is false or does not exist, the test is skipped. If the 441 -\fB\-constraints\fR value is an expression, that expression 433 +\fB-constraints\fR value is an expression, that expression 442 434 is evaluated. If the expression evaluates to true, then the test is run. 443 -Note that the expression form of \fB\-constraints\fR may interfere with the 444 -operation of \fBconfigure -constraints\fR and 445 -\fBconfigure -limitconstraints\fR, and is not recommended. 435 +Note that the expression form of \fB-constraints\fR may interfere with the 436 +operation of [\fBconfigure -constraints\fR] and 437 +[\fBconfigure -limitconstraints\fR], and is not recommended. 446 438 Appropriate constraints should be added to any tests that should 447 439 not always be run. That is, conditional evaluation of a test 448 -should be accomplished by the \fB\-constraints\fR option, not by 449 -conditional evaluation of \fBtest\fR. In that way, the same 440 +should be accomplished by the \fB-constraints\fR option, not by 441 +conditional evaluation of [\fBtest\fR]. In that way, the same 450 442 number of tests are always reported by the test suite, though 451 443 the number skipped may change based on the testing environment. 452 444 The default value is an empty list. 453 445 See \fBTEST CONSTRAINTS\fR below for a list of built-in constraints 454 446 and information on how to add your own constraints. 455 447 .TP 456 -\fB\-setup \fIscript\fR 457 -The optional \fB\-setup\fR attribute indicates a \fIscript\fR that will be run 458 -before the script indicated by the \fB\-body\fR attribute. If evaluation 448 +\fB-setup \fIscript\fR 449 +The optional \fB-setup\fR attribute indicates a \fIscript\fR that will be run 450 +before the script indicated by the \fB-body\fR attribute. If evaluation 459 451 of \fIscript\fR raises an error, the test will fail. The default value 460 452 is an empty script. 461 453 .TP 462 -\fB\-body \fIscript\fR 463 -The \fB\-body\fR attribute indicates the \fIscript\fR to run to carry out the 454 +\fB-body \fIscript\fR 455 +The \fB-body\fR attribute indicates the \fIscript\fR to run to carry out the 464 456 test. It must return a result that can be checked for correctness. 465 457 If evaluation of \fIscript\fR raises an error, the test will fail. 466 458 The default value is an empty script. 467 459 .TP 468 -\fB\-cleanup \fIscript\fR 469 -The optional \fB\-cleanup\fR attribute indicates a \fIscript\fR that will be 470 -run after the script indicated by the \fB\-body\fR attribute. 460 +\fB-cleanup \fIscript\fR 461 +The optional \fB-cleanup\fR attribute indicates a \fIscript\fR that will be 462 +run after the script indicated by the \fB-body\fR attribute. 471 463 If evaluation of \fIscript\fR raises an error, the test will fail. 472 464 The default value is an empty script. 473 465 .TP 474 -\fB\-match \fImode\fR 475 -The \fB\-match\fR attribute determines how expected answers supplied by 476 -\fB\-result\fR, \fB\-output\fR, and \fB\-errorOutput\fR are compared. Valid 466 +\fB-match \fImode\fR 467 +The \fB-match\fR attribute determines how expected answers supplied by 468 +\fB-result\fR, \fB-output\fR, and \fB-errorOutput\fR are compared. Valid 477 469 values for \fImode\fR are \fBregexp\fR, \fBglob\fR, \fBexact\fR, and 478 -any value registered by a prior call to \fBcustomMatch\fR. The default 470 +any value registered by a prior call to [\fBcustomMatch\fR]. The default 479 471 value is \fBexact\fR. 480 472 .TP 481 -\fB\-result \fIexpectedValue\fR 482 -The \fB\-result\fR attribute supplies the \fIexpectedValue\fR against which 473 +\fB-result \fIexpectedValue\fR 474 +The \fB-result\fR attribute supplies the \fIexpectedValue\fR against which 483 475 the return value from script will be compared. The default value is 484 476 an empty string. 485 477 .TP 486 -\fB\-output \fIexpectedValue\fR 487 -The \fB\-output\fR attribute supplies the \fIexpectedValue\fR against which 488 -any output sent to \fBstdout\fR or \fBoutputChannel\fR during evaluation 478 +\fB-output \fIexpectedValue\fR 479 +The \fB-output\fR attribute supplies the \fIexpectedValue\fR against which 480 +any output sent to \fBstdout\fR or [\fBoutputChannel\fR] during evaluation 489 481 of the script(s) will be compared. Note that only output printed using 490 -\fB::puts\fR is used for comparison. If \fB\-output\fR is not specified, 491 -output sent to \fBstdout\fR and \fBoutputChannel\fR is not processed for 482 +[\fB::puts\fR] is used for comparison. If \fB-output\fR is not specified, 483 +output sent to \fBstdout\fR and [\fBoutputChannel\fR] is not processed for 492 484 comparison. 493 485 .TP 494 -\fB\-errorOutput \fIexpectedValue\fR 495 -The \fB\-errorOutput\fR attribute supplies the \fIexpectedValue\fR against 496 -which any output sent to \fBstderr\fR or \fBerrorChannel\fR during 486 +\fB-errorOutput \fIexpectedValue\fR 487 +The \fB-errorOutput\fR attribute supplies the \fIexpectedValue\fR against 488 +which any output sent to \fBstderr\fR or [\fBerrorChannel\fR] during 497 489 evaluation of the script(s) will be compared. Note that only output 498 -printed using \fB::puts\fR is used for comparison. If \fB\-errorOutput\fR 499 -is not specified, output sent to \fBstderr\fR and \fBerrorChannel\fR is 490 +printed using [\fB::puts\fR] is used for comparison. If \fB-errorOutput\fR 491 +is not specified, output sent to \fBstderr\fR and [\fBerrorChannel\fR] is 500 492 not processed for comparison. 501 493 .TP 502 -\fB\-returnCodes \fIexpectedCodeList\fR 503 -The optional \fB\-returnCodes\fR attribute supplies \fIexpectedCodeList\fR, 494 +\fB-returnCodes \fIexpectedCodeList\fR 495 +The optional \fB-returnCodes\fR attribute supplies \fIexpectedCodeList\fR, 504 496 a list of return codes that may be accepted from evaluation of the 505 -\fB\-body\fR script. If evaluation of the \fB\-body\fR script returns 497 +\fB-body\fR script. If evaluation of the \fB-body\fR script returns 506 498 a code not in the \fIexpectedCodeList\fR, the test fails. All 507 -return codes known to \fBreturn\fR, in both numeric and symbolic 499 +return codes known to [\fBreturn\fR], in both numeric and symbolic 508 500 form, including extended return codes, are acceptable elements in 509 501 the \fIexpectedCodeList\fR. Default value is \fB{ok return}\fR. 510 502 .PP 511 -To pass, a test must successfully evaluate its \fB\-setup\fR, \fB\-body\fR, 512 -and \fB\-cleanup\fR scripts. The return code of the \fB\-body\fR script and 503 +To pass, a test must successfully evaluate its \fB-setup\fR, \fB-body\fR, 504 +and \fB-cleanup\fR scripts. The return code of the \fB-body\fR script and 513 505 its result must match expected values, and if specified, output and error 514 -data from the test must match expected \fB\-output\fR and \fB\-errorOutput\fR 506 +data from the test must match expected \fB-output\fR and \fB-errorOutput\fR 515 507 values. If any of these conditions are not met, then the test fails. 516 508 Note that all scripts are evaluated in the context of the caller 517 -of \fBtest\fR. 509 +of [\fBtest\fR]. 518 510 .PP 519 -As long as \fBtest\fR is called with valid syntax and legal 511 +As long as [\fBtest\fR] is called with valid syntax and legal 520 512 values for all attributes, it will not raise an error. Test 521 -failures are instead reported as output written to \fBoutputChannel\fR. 513 +failures are instead reported as output written to [\fBoutputChannel\fR]. 522 514 In default operation, a successful test produces no output. The output 523 -messages produced by \fBtest\fR are controlled by the 524 -\fBconfigure \-verbose\fR option as described in \fBCONFIGURABLE OPTIONS\fR 515 +messages produced by [\fBtest\fR] are controlled by the 516 +[\fBconfigure -verbose\fR] option as described in \fBCONFIGURABLE OPTIONS\fR 525 517 below. Any output produced by the test scripts themselves should be 526 -produced using \fB::puts\fR to \fBoutputChannel\fR or 527 -\fBerrorChannel\fR, so that users of the test suite may 528 -easily capture output with the \fBconfigure \-outfile\fR and 529 -\fBconfigure \-errfile\fR options, and so that the \fB\-output\fR 530 -and \fB\-errorOutput\fR attributes work properly. 518 +produced using [\fB::puts\fR] to [\fBoutputChannel\fR] or 519 +[\fBerrorChannel\fR], so that users of the test suite may 520 +easily capture output with the [\fBconfigure -outfile\fR] and 521 +[\fBconfigure -errfile\fR] options, and so that the \fB-output\fR 522 +and \fB-errorOutput\fR attributes work properly. 531 523 .SH "TEST CONSTRAINTS" 532 524 .PP 533 525 Constraints are used to determine whether or not a test should be skipped. 534 526 Each constraint has a name, which may be any string, and a boolean 535 -value. Each \fBtest\fR has a \fB\-constraints\fR value which is a 527 +value. Each [\fBtest\fR] has a \fB-constraints\fR value which is a 536 528 list of constraint names. There are two modes of constraint control. 537 529 Most frequently, the default mode is used, indicated by a setting 538 -of \fBconfigure \-limitconstraints\fR to false. The test will run 530 +of [\fBconfigure -limitconstraints\fR] to false. The test will run 539 531 only if all constraints in the list are true-valued. Thus, 540 -the \fB\-constraints\fR option of \fBtest\fR is a convenient, symbolic 532 +the \fB-constraints\fR option of [\fBtest\fR] is a convenient, symbolic 541 533 way to define any conditions required for the test to be possible or 542 -meaningful. For example, a \fBtest\fR with \fB\-constraints unix\fR 534 +meaningful. For example, a [\fBtest\fR] with \fB-constraints unix\fR 543 535 will only be run if the constraint \fBunix\fR is true, which indicates 544 536 the test suite is being run on a Unix platform. 545 537 .PP 546 -Each \fBtest\fR should include whatever \fB\-constraints\fR are 538 +Each [\fBtest\fR] should include whatever \fB-constraints\fR are 547 539 required to constrain it to run only where appropriate. Several 548 540 constraints are pre-defined in the \fBtcltest\fR package, listed 549 541 below. The registration of user-defined constraints is performed 550 -by the \fBtestConstraint\fR command. User-defined constraints 542 +by the [\fBtestConstraint\fR] command. User-defined constraints 551 543 may appear within a test file, or within the script specified 552 -by the \fBconfigure \-load\fR or \fBconfigure \-loadfile\fR 544 +by the [\fBconfigure -load\fR] or [\fBconfigure -loadfile\fR] 553 545 options. 554 546 .PP 555 547 The following is a list of constraints pre-defined by the 556 548 \fBtcltest\fR package itself: 557 549 .TP 558 550 \fIsingleTestInterp\fR 559 551 test can only be run if all test files are sourced into a single interpreter ................................................................................ 651 643 \fIroot\fR 652 644 test can only run if Unix user is root 653 645 .TP 654 646 \fInotRoot\fR 655 647 test can only run if Unix user is not root 656 648 .TP 657 649 \fIeformat\fR 658 -test can only run if app has a working version of sprintf with respect to the 659 -.QW "e" 660 -format of floating-point numbers. 650 +test can only run if app has a working version of sprintf with respect 651 +to the "e" format of floating-point numbers. 661 652 .TP 662 653 \fIstdio\fR 663 -test can only be run if \fBinterpreter\fR can be \fBopen\fRed 654 +test can only be run if [\fBinterpreter\fR] can be [\fBopen\fR]ed 664 655 as a pipe. 665 656 .PP 666 657 The alternative mode of constraint control is enabled by setting 667 -\fBconfigure \-limitconstraints\fR to true. With that configuration 658 +[\fBconfigure -limitconstraints\fR] to true. With that configuration 668 659 setting, all existing constraints other than those in the constraint 669 -list returned by \fBconfigure \-constraints\fR are set to false. 670 -When the value of \fBconfigure \-constraints\fR 660 +list returned by [\fBconfigure -constraints\fR] are set to false. 661 +When the value of [\fBconfigure -constraints\fR] 671 662 is set, all those constraints are set to true. The effect is that 672 -when both options \fBconfigure \-constraints\fR and 673 -\fBconfigure \-limitconstraints\fR are in use, only those tests including 674 -only constraints from the \fBconfigure \-constraints\fR list 663 +when both options [\fBconfigure -constraints\fR] and 664 +[\fBconfigure -limitconstraints\fR] are in use, only those tests including 665 +only constraints from the [\fBconfigure -constraints\fR] list 675 666 are run; all others are skipped. For example, one might set 676 667 up a configuration with 677 668 .PP 678 669 .CS 679 670 \fBconfigure\fR -constraints knownBug \e 680 671 -limitconstraints true \e 681 672 -verbose pass 682 673 .CE 683 674 .PP 684 675 to run exactly those tests that exercise known bugs, and discover 685 676 whether any of them pass, indicating the bug had been fixed. 686 677 .SH "RUNNING ALL TESTS" 687 678 .PP 688 -The single command \fBrunAllTests\fR is evaluated to run an entire 679 +The single command [\fBrunAllTests\fR] is evaluated to run an entire 689 680 test suite, spanning many files and directories. The configuration 690 681 options of \fBtcltest\fR control the precise operations. The 691 -\fBrunAllTests\fR command begins by printing a summary of its 692 -configuration to \fBoutputChannel\fR. 682 +[\fBrunAllTests\fR] command begins by printing a summary of its 683 +configuration to [\fBoutputChannel\fR]. 693 684 .PP 694 685 Test files to be evaluated are sought in the directory 695 -\fBconfigure \-testdir\fR. The list of files in that directory 696 -that match any of the patterns in \fBconfigure \-file\fR and 697 -match none of the patterns in \fBconfigure \-notfile\fR is generated 686 +[\fBconfigure -testdir\fR]. The list of files in that directory 687 +that match any of the patterns in [\fBconfigure -file\fR] and 688 +match none of the patterns in [\fBconfigure -notfile\fR] is generated 698 689 and sorted. Then each file will be evaluated in turn. If 699 -\fBconfigure \-singleproc\fR is true, then each file will 700 -be \fBsource\fRd in the caller's context. If it is false, 701 -then a copy of \fBinterpreter\fR will be \fBexec\fRd to 690 +[\fBconfigure -singleproc\fR] is true, then each file will 691 +be [\fBsource\fR]d in the caller's context. If it is false, 692 +then a copy of [\fBinterpreter\fR] will be [\fBexec\fR]d to 702 693 evaluate each file. The multi-process operation is useful 703 694 when testing can cause errors so severe that a process 704 695 terminates. Although such an error may terminate a child 705 696 process evaluating one file, the master process can continue 706 697 with the rest of the test suite. In multi-process operation, 707 698 the configuration of \fBtcltest\fR in the master process is 708 699 passed to the child processes as command line arguments, 709 -with the exception of \fBconfigure \-outfile\fR. The 710 -\fBrunAllTests\fR command in the 700 +with the exception of [\fBconfigure -outfile\fR]. The 701 +[\fBrunAllTests\fR] command in the 711 702 master process collects all output from the child processes 712 703 and collates their results into one master report. Any 713 704 reports of individual test failures, or messages requested 714 -by a \fBconfigure \-verbose\fR setting are passed directly 715 -on to \fBoutputChannel\fR by the master process. 705 +by a [\fBconfigure -verbose\fR] setting are passed directly 706 +on to [\fBoutputChannel\fR] by the master process. 716 707 .PP 717 708 After evaluating all selected test files, a summary of the 718 -results is printed to \fBoutputChannel\fR. The summary 719 -includes the total number of \fBtest\fRs evaluated, broken 709 +results is printed to [\fBoutputChannel\fR]. The summary 710 +includes the total number of [\fBtest\fR]s evaluated, broken 720 711 down into those skipped, those passed, and those failed. 721 712 The summary also notes the number of files evaluated, and the names 722 713 of any files with failing tests or errors. A list of 723 714 the constraints that caused tests to be skipped, and the 724 715 number of tests skipped for each is also printed. Also, 725 716 messages are printed if it appears that evaluation of 726 717 a test file has caused any temporary files to be left 727 -behind in \fBconfigure \-tmpdir\fR. 718 +behind in [\fBconfigure -tmpdir\fR]. 728 719 .PP 729 720 Having completed and summarized all selected test files, 730 -\fBrunAllTests\fR then recursively acts on subdirectories 731 -of \fBconfigure \-testdir\fR. All subdirectories that 732 -match any of the patterns in \fBconfigure \-relateddir\fR 721 +[\fBrunAllTests\fR] then recursively acts on subdirectories 722 +of [\fBconfigure -testdir\fR]. All subdirectories that 723 +match any of the patterns in [\fBconfigure -relateddir\fR] 733 724 and do not match any of the patterns in 734 -\fBconfigure \-asidefromdir\fR are examined. If 725 +[\fBconfigure -asidefromdir\fR] are examined. If 735 726 a file named \fBall.tcl\fR is found in such a directory, 736 -it will be \fBsource\fRd in the caller's context. 727 +it will be [\fBsource\fR]d in the caller's context. 737 728 Whether or not an examined directory contains an 738 729 \fBall.tcl\fR file, its subdirectories are also scanned 739 -against the \fBconfigure \-relateddir\fR and 740 -\fBconfigure \-asidefromdir\fR patterns. In this way, 730 +against the [\fBconfigure -relateddir\fR] and 731 +[\fBconfigure -asidefromdir\fR] patterns. In this way, 741 732 many directories in a directory tree can have all their 742 -test files evaluated by a single \fBrunAllTests\fR 733 +test files evaluated by a single [\fBrunAllTests\fR] 743 734 command. 744 735 .SH "CONFIGURABLE OPTIONS" 745 -The \fBconfigure\fR command is used to set and query the configurable 736 +The [\fBconfigure\fR] command is used to set and query the configurable 746 737 options of \fBtcltest\fR. The valid options are: 747 738 .TP 748 -\fB\-singleproc \fIboolean\fR 749 -Controls whether or not \fBrunAllTests\fR spawns a child process for 739 +\fB-singleproc \fIboolean\fR 740 +Controls whether or not [\fBrunAllTests\fR] spawns a child process for 750 741 each test file. No spawning when \fIboolean\fR is true. Default 751 742 value is false. 752 743 .TP 753 -\fB\-debug \fIlevel\fR 744 +\fB-debug \fIlevel\fR 754 745 Sets the debug level to \fIlevel\fR, an integer value indicating how 755 746 much debugging information should be printed to stdout. Note that 756 747 debug messages always go to stdout, independent of the value of 757 -\fBconfigure \-outfile\fR. Default value is 0. Levels are defined as: 748 +[\fBconfigure -outfile\fR]. Default value is 0. Levels are defined as: 758 749 .RS 759 750 .IP 0 760 751 Do not display any debug information. 761 752 .IP 1 762 753 Display information regarding whether a test is skipped because it 763 754 doesn't match any of the tests that were specified using by 764 -\fBconfigure \-match\fR (userSpecifiedNonMatch) or matches any of 765 -the tests specified by \fBconfigure \-skip\fR (userSpecifiedSkip). Also 755 +[\fBconfigure -match\fR] (userSpecifiedNonMatch) or matches any of 756 +the tests specified by [\fBconfigure -skip\fR] (userSpecifiedSkip). Also 766 757 print warnings about possible lack of cleanup or balance in test files. 767 758 Also print warnings about any re-use of test names. 768 759 .IP 2 769 760 Display the flag array parsed by the command line processor, the 770 761 contents of the ::env array, and all user-defined variables that exist 771 762 in the current namespace as they are used. 772 763 .IP 3 773 764 Display information regarding what individual procs in the test 774 765 harness are doing. 775 766 .RE 776 767 .TP 777 -\fB\-verbose \fIlevel\fR 768 +\fB-verbose \fIlevel\fR 778 769 Sets the type of output verbosity desired to \fIlevel\fR, 779 770 a list of zero or more of the elements \fBbody\fR, \fBpass\fR, 780 771 \fBskip\fR, \fBstart\fR, \fBerror\fR and \fBline\fR. Default value 781 772 is \fB{body error}\fR. 782 773 Levels are defined as: 783 774 .RS 784 775 .IP "body (b)" ................................................................................ 792 783 .IP "error (e)" 793 784 Print errorInfo and errorCode, if they exist, when a test return code 794 785 does not match its expected return code 795 786 .IP "line (l)" 796 787 Print source file line information of failed tests 797 788 .RE 798 789 The single letter abbreviations noted above are also recognized 799 -so that 800 -.QW "\fBconfigure \-verbose pt\fR" 801 -is the same as 802 -.QW "\fBconfigure \-verbose {pass start}\fR" . 790 +so that [\fBconfigure -verbose pt\fR] is the same as 791 +[\fBconfigure -verbose {pass start}\fR]. 803 792 .TP 804 -\fB\-preservecore \fIlevel\fR 793 +\fB-preservecore \fIlevel\fR 805 794 Sets the core preservation level to \fIlevel\fR. This level 806 795 determines how stringent checks for core files are. Default 807 796 value is 0. Levels are defined as: 808 797 .RS 809 798 .IP 0 810 -No checking \(em do not check for core files at the end of each test 811 -command, but do check for them in \fBrunAllTests\fR after all 799 +No checking - do not check for core files at the end of each test 800 +command, but do check for them in [\fBrunAllTests\fR] after all 812 801 test files have been evaluated. 813 802 .IP 1 814 -Also check for core files at the end of each \fBtest\fR command. 803 +Also check for core files at the end of each [\fBtest\fR] command. 815 804 .IP 2 816 805 Check for core files at all times described above, and save a 817 -copy of each core file produced in \fBconfigure \-tmpdir\fR. 806 +copy of each core file produced in [\fBconfigure -tmpdir\fR]. 818 807 .RE 819 808 .TP 820 -\fB\-limitconstraints \fIboolean\fR 821 -Sets the mode by which \fBtest\fR honors constraints as described 809 +\fB-limitconstraints \fIboolean\fR 810 +Sets the mode by which [\fBtest\fR] honors constraints as described 822 811 in \fBTESTS\fR above. Default value is false. 823 812 .TP 824 -\fB\-constraints \fIlist\fR 813 +\fB-constraints \fIlist\fR 825 814 Sets all the constraints in \fIlist\fR to true. Also used in 826 -combination with 827 -.QW "\fBconfigure \-limitconstraints true\fR" 828 -to control an 815 +combination with [\fBconfigure -limitconstraints true\fR] to control an 829 816 alternative constraint mode as described in \fBTESTS\fR above. 830 817 Default value is an empty list. 831 818 .TP 832 -\fB\-tmpdir \fIdirectory\fR 833 -Sets the temporary directory to be used by \fBmakeFile\fR, 834 -\fBmakeDirectory\fR, \fBviewFile\fR, \fBremoveFile\fR, 835 -and \fBremoveDirectory\fR as the default directory where 819 +\fB-tmpdir \fIdirectory\fR 820 +Sets the temporary directory to be used by [\fBmakeFile\fR], 821 +[\fBmakeDirectory\fR], [\fBviewFile\fR], [\fBremoveFile\fR], 822 +and [\fBremoveDirectory\fR] as the default directory where 836 823 temporary files and directories created by test files should 837 -be created. Default value is \fBworkingDirectory\fR. 824 +be created. Default value is [\fBworkingDirectory\fR]. 838 825 .TP 839 -\fB\-testdir \fIdirectory\fR 840 -Sets the directory searched by \fBrunAllTests\fR for test files 841 -and subdirectories. Default value is \fBworkingDirectory\fR. 826 +\fB-testdir \fIdirectory\fR 827 +Sets the directory searched by [\fBrunAllTests\fR] for test files 828 +and subdirectories. Default value is [\fBworkingDirectory\fR]. 842 829 .TP 843 -\fB\-file \fIpatternList\fR 844 -Sets the list of patterns used by \fBrunAllTests\fR to determine 830 +\fB-file \fIpatternList\fR 831 +Sets the list of patterns used by [\fBrunAllTests\fR] to determine 845 832 what test files to evaluate. Default value is \fB*.test\fR. 846 833 .TP 847 -\fB\-notfile \fIpatternList\fR 848 -Sets the list of patterns used by \fBrunAllTests\fR to determine 849 -what test files to skip. Default value is 850 -.QW \fBl.*.test\fR , 851 -so that any SCCS lock files are skipped. 834 +\fB-notfile \fIpatternList\fR 835 +Sets the list of patterns used by [\fBrunAllTests\fR] to determine 836 +what test files to skip. Default value is \fBl.*.test\fR, so 837 +that any SCCS lock files are skipped. 852 838 .TP 853 -\fB\-relateddir \fIpatternList\fR 854 -Sets the list of patterns used by \fBrunAllTests\fR to determine 839 +\fB-relateddir \fIpatternList\fR 840 +Sets the list of patterns used by [\fBrunAllTests\fR] to determine 855 841 what subdirectories to search for an \fBall.tcl\fR file. Default 856 -value is 857 -.QW \fB*\fR . 842 +value is \fB*\fR. 858 843 .TP 859 -\fB\-asidefromdir \fIpatternList\fR 860 -Sets the list of patterns used by \fBrunAllTests\fR to determine 844 +\fB-asidefromdir \fIpatternList\fR 845 +Sets the list of patterns used by [\fBrunAllTests\fR] to determine 861 846 what subdirectories to skip when searching for an \fBall.tcl\fR file. 862 847 Default value is an empty list. 863 848 .TP 864 -\fB\-match \fIpatternList\fR 865 -Set the list of patterns used by \fBtest\fR to determine whether 866 -a test should be run. Default value is 867 -.QW \fB*\fR . 849 +\fB-match \fIpatternList\fR 850 +Set the list of patterns used by [\fBtest\fR] to determine whether 851 +a test should be run. Default value is \fB*\fR. 868 852 .TP 869 -\fB\-skip \fIpatternList\fR 870 -Set the list of patterns used by \fBtest\fR to determine whether 853 +\fB-skip \fIpatternList\fR 854 +Set the list of patterns used by [\fBtest\fR] to determine whether 871 855 a test should be skipped. Default value is an empty list. 872 856 .TP 873 -\fB\-load \fIscript\fR 874 -Sets a script to be evaluated by \fBloadTestedCommands\fR. 857 +\fB-load \fIscript\fR 858 +Sets a script to be evaluated by [\fBloadTestedCommands\fR]. 875 859 Default value is an empty script. 876 860 .TP 877 -\fB\-loadfile \fIfilename\fR 861 +\fB-loadfile \fIfilename\fR 878 862 Sets the filename from which to read a script to be evaluated 879 -by \fBloadTestedCommands\fR. This is an alternative to 880 -\fB\-load\fR. They cannot be used together. 863 +by [\fBloadTestedCommands\fR]. This is an alternative to 864 +\fB-load\fR. They cannot be used together. 881 865 .TP 882 -\fB\-outfile \fIfilename\fR 866 +\fB-outfile \fIfilename\fR 883 867 Sets the file to which all output produced by tcltest should be 884 -written. A file named \fIfilename\fR will be \fBopen\fRed for writing, 885 -and the resulting channel will be set as the value of \fBoutputChannel\fR. 868 +written. A file named \fIfilename\fR will be [\fBopen\fR]ed for writing, 869 +and the resulting channel will be set as the value of [\fBoutputChannel\fR]. 886 870 .TP 887 -\fB\-errfile \fIfilename\fR 871 +\fB-errfile \fIfilename\fR 888 872 Sets the file to which all error output produced by tcltest 889 -should be written. A file named \fIfilename\fR will be \fBopen\fRed 873 +should be written. A file named \fIfilename\fR will be [\fBopen\fR]ed 890 874 for writing, and the resulting channel will be set as the value 891 -of \fBerrorChannel\fR. 875 +of [\fBerrorChannel\fR]. 892 876 .SH "CREATING TEST SUITES WITH TCLTEST" 893 877 .PP 894 -The fundamental element of a test suite is the individual \fBtest\fR 878 +The fundamental element of a test suite is the individual [\fBtest\fR] 895 879 command. We begin with several examples. 896 880 .IP [1] 897 881 Test of a script that returns normally. 898 882 .RS 899 883 .PP 900 884 .CS 901 885 \fBtest\fR example-1.0 {normal return} { ................................................................................ 941 925 file attributes $file -owner 942 926 } -cleanup { 943 927 removeFile test 944 928 } -result $::tcl_platform(user) 945 929 .CE 946 930 .RE 947 931 .PP 948 -At the next higher layer of organization, several \fBtest\fR commands 932 +At the next higher layer of organization, several [\fBtest\fR] commands 949 933 are gathered together into a single test file. Test files should have 950 934 names with the \fB.test\fR extension, because that is the default pattern 951 -used by \fBrunAllTests\fR to find test files. It is a good rule of 935 +used by [\fBrunAllTests\fR] to find test files. It is a good rule of 952 936 thumb to have one test file for each source code file of your project. 953 937 It is good practice to edit the test file and the source code file 954 938 together, keeping tests synchronized with code changes. 955 939 .PP 956 -Most of the code in the test file should be the \fBtest\fR commands. 940 +Most of the code in the test file should be the [\fBtest\fR] commands. 957 941 Use constraints to skip tests, rather than conditional evaluation 958 -of \fBtest\fR. 942 +of [\fBtest\fR]. 959 943 .IP [5] 960 944 Recommended system for writing conditional tests, using constraints to 961 945 guard: 962 946 .RS 963 947 .PP 964 948 .CS 965 949 \fBtestConstraint\fR X [expr $myRequirement] ................................................................................ 978 962 test badConditionalTest {} { 979 963 #body 980 964 } result 981 965 } 982 966 .CE 983 967 .RE 984 968 .PP 985 -Use the \fB\-setup\fR and \fB\-cleanup\fR options to establish and release 969 +Use the \fB-setup\fR and \fB-cleanup\fR options to establish and release 986 970 all context requirements of the test body. Do not make tests depend on 987 971 prior tests in the file. Those prior tests might be skipped. If several 988 972 consecutive tests require the same context, the appropriate setup 989 973 and cleanup scripts may be stored in variable for passing to each tests 990 -\fB\-setup\fR and \fB\-cleanup\fR options. This is a better solution than 991 -performing setup outside of \fBtest\fR commands, because the setup will 974 +\fB-setup\fR and \fB-cleanup\fR options. This is a better solution than 975 +performing setup outside of [\fBtest\fR] commands, because the setup will 992 976 only be done if necessary, and any errors during setup will be reported, 993 977 and not cause the test file to abort. 994 978 .PP 995 979 A test file should be able to be combined with other test files and not 996 -interfere with them, even when 997 -.QW "\fBconfigure -singleproc 1\fR" 998 -causes all files to be evaluated in a common interpreter. A simple way to 980 +interfere with them, even when [\fBconfigure -singleproc 1\fR] causes 981 +all files to be evaluated in a common interpreter. A simple way to 999 982 achieve this is to have your tests define all their commands and variables 1000 983 in a namespace that is deleted when the test file evaluation is complete. 1001 984 A good namespace to use is a child namespace \fBtest\fR of the namespace 1002 985 of the module you are testing. 1003 986 .PP 1004 987 A test file should also be able to be evaluated directly as a script, 1005 -not depending on being called by a master \fBrunAllTests\fR. This 988 +not depending on being called by a master [\fBrunAllTests\fR]. This 1006 989 means that each test file should process command line arguments to give 1007 990 the tester all the configuration control that \fBtcltest\fR provides. 1008 991 .PP 1009 -After all \fBtest\fRs in a test file, the command \fBcleanupTests\fR 992 +After all [\fBtest\fR]s in a test file, the command [\fBcleanupTests\fR] 1010 993 should be called. 1011 994 .IP [7] 1012 995 Here is a sketch of a sample test file illustrating those points: 1013 996 .RS 1014 997 .PP 1015 998 .CS 1016 999 package require tcltest 2.2 ................................................................................ 1034 1017 } 1035 1018 namespace delete ::example::test 1036 1019 .CE 1037 1020 .RE 1038 1021 .PP 1039 1022 The next level of organization is a full test suite, made up of several 1040 1023 test files. One script is used to control the entire suite. The 1041 -basic function of this script is to call \fBrunAllTests\fR after 1024 +basic function of this script is to call [\fBrunAllTests\fR] after 1042 1025 doing any necessary setup. This script is usually named \fBall.tcl\fR 1043 -because that's the default name used by \fBrunAllTests\fR when combining 1026 +because that's the default name used by [\fBrunAllTests\fR] when combining 1044 1027 multiple test suites into one testing run. 1045 1028 .IP [8] 1046 1029 Here is a sketch of a sample test suite master script: 1047 1030 .RS 1048 1031 .PP 1049 1032 .CS 1050 1033 package require Tcl 8.4 1051 1034 package require tcltest 2.2 1052 1035 package require example 1053 -\fB::tcltest::configure\fR -testdir \e 1036 +\fB::tcltest::configure\fR -testdir \\ 1054 1037 [file dirname [file normalize [info script]]] 1055 1038 eval \fB::tcltest::configure\fR $argv 1056 1039 \fB::tcltest::runAllTests\fR 1057 1040 .CE 1058 1041 .RE 1059 1042 .SH COMPATIBILITY 1060 1043 .PP ................................................................................ 1061 1044 A number of commands and variables in the \fB::tcltest\fR namespace 1062 1045 provided by earlier releases of \fBtcltest\fR have not been documented 1063 1046 here. They are no longer part of the supported public interface of 1064 1047 \fBtcltest\fR and should not be used in new test suites. However, 1065 1048 to continue to support existing test suites written to the older 1066 1049 interface specifications, many of those deprecated commands and 1067 1050 variables still work as before. For example, in many circumstances, 1068 -\fBconfigure\fR will be automatically called shortly after 1069 -.QW "\fBpackage require tcltest 2.1\fR" 1070 -succeeds with arguments 1051 +[\fBconfigure\fR] will be automatically called shortly after 1052 +[\fBpackage require tcltest 2.1\fR] succeeds with arguments 1071 1053 from the variable \fB::argv\fR. This is to support test suites 1072 1054 that depend on the old behavior that \fBtcltest\fR was automatically 1073 1055 configured from command line arguments. New test files should not 1074 1056 depend on this, but should explicitly include 1075 1057 .PP 1076 1058 .CS 1077 1059 eval \fB::tcltest::configure\fR $::argv 1078 1060 .CE 1079 1061 .PP 1080 1062 to establish a configuration from command line arguments. 1081 1063 .SH "KNOWN ISSUES" 1082 -There are two known issues related to nested evaluations of \fBtest\fR. 1064 +There are two known issues related to nested evaluations of [\fBtest\fR]. 1083 1065 The first issue relates to the stack level in which test scripts are 1084 1066 executed. Tests nested within other tests may be executed at the same 1085 1067 stack level as the outermost test. For example, in the following code: 1086 1068 .PP 1087 1069 .CS 1088 1070 \fBtest\fR level-1.1 {level 1} { 1089 1071 -body { ................................................................................ 1092 1074 } 1093 1075 } 1094 1076 .CE 1095 1077 .PP 1096 1078 any script executed in level-2.1 may be executed at the same stack 1097 1079 level as the script defined for level-1.1. 1098 1080 .PP 1099 -In addition, while two \fBtest\fRs have been run, results will only 1100 -be reported by \fBcleanupTests\fR for tests at the same level as 1081 +In addition, while two [\fBtest\fR]s have been run, results will only 1082 +be reported by [\fBcleanupTests\fR] for tests at the same level as 1101 1083 test level-1.1. However, test results for all tests run prior to 1102 1084 level-1.1 will be available when test level-2.1 runs. What this 1103 1085 means is that if you try to access the test results for test level-2.1, 1104 -it will may say that 1105 -.QW m 1106 -tests have run, 1107 -.QW n 1108 -tests have been skipped, 1109 -.QW o 1110 -tests have passed and 1111 -.QW p 1112 -tests have failed, where 1113 -.QW m , 1114 -.QW n , 1115 -.QW o , 1116 -and 1117 -.QW p 1118 -refer to tests that were run at the same test level as test level-1.1. 1086 +it will may say that 'm' tests have run, 'n' tests have 1087 +been skipped, 'o' tests have passed and 'p' tests have failed, 1088 +where 'm', 'n', 'o', and 'p' refer to tests that were run at the 1089 +same test level as test level-1.1. 1119 1090 .PP 1120 1091 Implementation of output and error comparison in the test command 1121 1092 depends on usage of ::puts in your application code. Output is 1122 1093 intercepted by redefining the ::puts command while the defined test 1123 1094 script is being run. Errors thrown by C procedures or printed 1124 1095 directly from C applications will not be caught by the test command. 1125 -Therefore, usage of the \fB\-output\fR and \fB\-errorOutput\fR 1126 -options to \fBtest\fR is useful only for pure Tcl applications 1127 -that use \fB::puts\fR to produce output. 1096 +Therefore, usage of the \fB-output\fR and \fB-errorOutput\fR 1097 +options to [\fBtest\fR] is useful only for pure Tcl applications 1098 +that use [\fB::puts\fR] to produce output. 1128 1099 .SH KEYWORDS 1129 1100 test, test harness, test suite
Changes to doc/tclvars.n.
1 1 '\" 2 2 '\" Copyright (c) 1993 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -'\" RCS: @(#) $Id: tclvars.n,v 1.28 2007/10/24 14:29:39 dkf Exp $ 8 +'\" RCS: @(#) $Id: tclvars.n,v 1.29 2007/10/26 20:11:53 dgp Exp $ 9 9 '\" 10 10 .so man.macros 11 11 .TH tclvars n 8.0 Tcl "Tcl Built-In Commands" 12 12 .BS 13 13 '\" Note: do not modify the .SH NAME line immediately below! 14 14 .SH NAME 15 15 tclvars \- Variables used by Tcl ................................................................................ 35 35 passed to children by commands like \fBexec\fR. 36 36 If the entire \fBenv\fR array is unset then Tcl will stop 37 37 monitoring \fBenv\fR accesses and will not update environment 38 38 variables. 39 39 .RS 40 40 Under Windows, the environment variables PATH and COMSPEC in any 41 41 capitalization are converted automatically to upper case. For instance, the 42 -PATH variable could be exported by the operating system as 43 -.QW path , 44 -.QW Path , 45 -.QW PaTh , 46 -etc., causing otherwise simple Tcl code to have to 42 +PATH variable could be exported by the operating system as ``path'', 43 +``Path'', ``PaTh'', etc., causing otherwise simple Tcl code to have to 47 44 support many special cases. All other environment variables inherited by 48 45 Tcl are left unmodified. Setting an env array variable to blank is the 49 46 same as unsetting it as this is the behavior of the underlying Windows OS. 50 47 It should be noted that relying on an existing and empty environment variable 51 48 won't work on windows and is discouraged for cross-platform usage. 52 49 .RE 53 50 .TP ................................................................................ 77 74 \fBCHILDKILLED\fI pid sigName msg\fR 78 75 This format is used when a child process has been killed because of 79 76 a signal. The \fIpid\fR element will be the process's identifier (in decimal). 80 77 The \fIsigName\fR element will be the symbolic name of the signal that caused 81 78 the process to terminate; it will be one of the names from the 82 79 include file signal.h, such as \fBSIGPIPE\fR. 83 80 The \fImsg\fR element will be a short human-readable message 84 -describing the signal, such as 85 -.QW "write on pipe with no readers" 81 +describing the signal, such as ``write on pipe with no readers'' 86 82 for \fBSIGPIPE\fR. 87 83 .TP 88 84 \fBCHILDSTATUS\fI pid code\fR 89 85 This format is used when a child process has exited with a non-zero 90 86 exit status. The \fIpid\fR element will be the 91 87 process's identifier (in decimal) and the \fIcode\fR element will be the exit 92 88 code returned by the process (also in decimal). ..............................