diff options
| author | jan.nijtmans <nijtmans@users.sourceforge.net> | 2024-06-11 12:13:54 (GMT) |
|---|---|---|
| committer | jan.nijtmans <nijtmans@users.sourceforge.net> | 2024-06-11 12:13:54 (GMT) |
| commit | b67bee2a5ef32b3377cebaa30c9ddbd1067f05e0 (patch) | |
| tree | 7505fba0f488a1dd043bfbf51b5806504f5d09d6 | |
| parent | 7546332ccf74bd863948ec07c404e163023ee445 (diff) | |
| download | tcl-b67bee2a5ef32b3377cebaa30c9ddbd1067f05e0.zip tcl-b67bee2a5ef32b3377cebaa30c9ddbd1067f05e0.tar.gz tcl-b67bee2a5ef32b3377cebaa30c9ddbd1067f05e0.tar.bz2 | |
Backport: Another round of small fixes, especially spelling errors...
104 files changed, 1514 insertions, 1431 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index e77df6c..fd36aab 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -75,9 +75,11 @@ An argument list which must have been initialized using .AP int lineNum The line number of a script where an error occurred. .AP "const char" *script in -Pointer to first character in script containing command (must be <= command) +Pointer to first character in script containing command +(must be <= \fIcommand\fR). .AP "const char" *command in -Pointer to first character in command that generated the error +Pointer to first character in the command that generated the error; must +point within the string given by \fIscript\fR. .AP int commandLength in Number of bytes in command; -1 means use all bytes up to first null byte .BE diff --git a/doc/Alloc.3 b/doc/Alloc.3 index 70b0f7d..ddc1e46 100644 --- a/doc/Alloc.3 +++ b/doc/Alloc.3 @@ -92,7 +92,7 @@ calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however, these macros are redefined to be special debugging versions of these procedures. To support Tcl's memory debugging within a module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc. - +.PP \fBTcl_GetMemoryInfo\fR appends a list-of-lists of memory stats to the provided DString. This function cannot be used in stub-enabled extensions, and it is only available if Tcl is compiled with the threaded memory allocator. diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3 index 8ddc28c..e21bc81 100644 --- a/doc/ByteArrObj.3 +++ b/doc/ByteArrObj.3 @@ -60,7 +60,7 @@ a finite byte sequence. A byte is an 8-bit quantity with no inherent meaning. When the 8 bits are interpreted as an integer value, the range of possible values is (0-255). The C type best suited to store a byte is the \fBunsigned char\fR. -An \fBunsigned char\fR array of size \fIN\fR stores an aribtrary binary +An \fBunsigned char\fR array of size \fIN\fR stores an arbitrary binary value of size \fIN\fR bytes. We call this representation a byte-array. Here we document the routines that allow us to operate on Tcl values as byte-arrays. diff --git a/doc/CallDel.3 b/doc/CallDel.3 index 33b8afc..d8fab2a 100644 --- a/doc/CallDel.3 +++ b/doc/CallDel.3 @@ -60,7 +60,8 @@ If there is no deletion callback that matches \fIinterp\fR, .PP Note that if the callback is being used to delete a resource that \fImust\fR be released on exit, \fBTcl_CreateExitHandler\fR should be used to ensure that -a callback is received even if the application terminates without deleting the interpreter. +a callback is received even if the application terminates without deleting the +interpreter. .SH "SEE ALSO" Tcl_CreateExitHandler(3), Tcl_CreateThreadExitHandler(3) .SH KEYWORDS diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index 1496631..2a2169f 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -328,7 +328,7 @@ details about the old structure. The \fBTcl_ChannelType\fR structure contains the following fields: .PP .CS -typedef struct Tcl_ChannelType { +typedef struct { const char *\fItypeName\fR; Tcl_ChannelTypeVersion \fIversion\fR; Tcl_DriverCloseProc *\fIcloseProc\fR; @@ -386,7 +386,6 @@ This value can be retrieved with \fBTcl_ChannelName\fR, which returns a pointer to the string. .SS VERSION .PP - The \fIversion\fR field should be set to the version of the structure that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended. \fBTCL_CHANNEL_VERSION_3\fR must be set to specify the \fIwideSeekProc\fR member. diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3 index bf76d48..d15a920 100644 --- a/doc/CrtCommand.3 +++ b/doc/CrtCommand.3 @@ -16,6 +16,7 @@ Tcl_CreateCommand \- implement new commands in C .sp Tcl_Command \fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR) +.fi .SH ARGUMENTS .AS Tcl_CmdDeleteProc *deleteProc .AP Tcl_Interp *interp in @@ -25,7 +26,7 @@ Name of command. .AP Tcl_CmdProc *proc in Implementation of new command: \fIproc\fR will be called whenever \fIcmdName\fR is invoked as a command. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR. .AP Tcl_CmdDeleteProc *deleteProc in Procedure to call before \fIcmdName\fR is deleted from the interpreter; @@ -75,7 +76,7 @@ and it returns NULL. .PP .CS typedef int \fBTcl_CmdProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIargc\fR, const char *\fIargv\fR[]); @@ -92,11 +93,11 @@ the command name) and \fIargv\fR giving the values of the arguments as strings. The \fIargv\fR array will contain \fIargc\fR+1 values; the first \fIargc\fR values point to the argument strings, and the last value is NULL. +.PP Note that the argument strings should not be modified as they may point to constant strings or may be shared with other parts of the interpreter. -.PP -Note that the argument strings are encoded in normalized UTF-8 since +Note also that the argument strings are encoded in normalized UTF-8 since version 8.1 of Tcl. .PP \fIProc\fR must return an integer code that is expected to be one of @@ -131,7 +132,7 @@ result that match the type \fBTcl_CmdDeleteProc\fR: .PP .CS typedef void \fBTcl_CmdDeleteProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP The \fIclientData\fR argument will be the same as the \fIclientData\fR diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 index bb63937..bcb8c86 100644 --- a/doc/CrtObjCmd.3 +++ b/doc/CrtObjCmd.3 @@ -290,8 +290,7 @@ Note that \fBTcl_SetCommandInfo\fR and \fBTcl_SetCommandInfoFromToken\fR both allow the ClientData for a command's deletion procedure to be given a different value than the ClientData for its command procedure. -.PP -Note that neither \fBTcl_SetCommandInfo\fR nor +Note also that neither \fBTcl_SetCommandInfo\fR nor \fBTcl_SetCommandInfoFromToken\fR will change a command's namespace. Use \fBTcl_Eval\fR to call the \fBrename\fR command to do that. .PP diff --git a/doc/DoOneEvent.3 b/doc/DoOneEvent.3 index d48afd0..17c76e6 100644 --- a/doc/DoOneEvent.3 +++ b/doc/DoOneEvent.3 @@ -53,24 +53,18 @@ If the \fIflags\fR argument to \fBTcl_DoOneEvent\fR is non-zero, it restricts the kinds of events that will be processed by \fBTcl_DoOneEvent\fR. \fIFlags\fR may be an OR-ed combination of any of the following bits: -.TP 27 -\fBTCL_WINDOW_EVENTS\fR \- +.IP \fBTCL_WINDOW_EVENTS\fR Process window system events. -.TP 27 -\fBTCL_FILE_EVENTS\fR \- +.IP \fBTCL_FILE_EVENTS\fR Process file events. -.TP 27 -\fBTCL_TIMER_EVENTS\fR \- +.IP \fBTCL_TIMER_EVENTS\fR Process timer events. -.TP 27 -\fBTCL_IDLE_EVENTS\fR \- +.IP \fBTCL_IDLE_EVENTS\fR Process idle callbacks. -.TP 27 -\fBTCL_ALL_EVENTS\fR \- +.IP \fBTCL_ALL_EVENTS\fR Process all kinds of events: equivalent to OR-ing together all of the above flags or specifying none of them. -.TP 27 -\fBTCL_DONT_WAIT\fR \- +.IP \fBTCL_DONT_WAIT\fR Do not sleep: process only events that are ready at the time of the call. .LP diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3 index cfdbff9..f342820 100644 --- a/doc/DoWhenIdle.3 +++ b/doc/DoWhenIdle.3 @@ -17,11 +17,12 @@ Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pendi \fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR) .sp \fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR) +.fi .SH ARGUMENTS .AS Tcl_IdleProc clientData .AP Tcl_IdleProc *proc in Procedure to invoke. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -43,7 +44,7 @@ type \fBTcl_IdleProc\fR: .PP .CS typedef void \fBTcl_IdleProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3 index c70f5d1..f7edcec 100644 --- a/doc/DoubleObj.3 +++ b/doc/DoubleObj.3 @@ -73,4 +73,5 @@ is holding a reference to the object, it will be deleted. .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult .SH KEYWORDS -double, double value, double type, internal representation, value, value type, string representation +double, double value, double type, internal representation, value, value type, +string representation diff --git a/doc/Encoding.3 b/doc/Encoding.3 index c357ecd..c94f000 100644 --- a/doc/Encoding.3 +++ b/doc/Encoding.3 @@ -232,12 +232,12 @@ be used to specify the profile to be used for the transform. The ignored as the function assumes the entire source string to be decoded is passed into the function. On success, the function returns \fBTCL_OK\fR with the converted string stored in \fB*dstPtr\fR. For errors \fIother than conversion -errors\fR, such as invalid flags, the function returns \fBTCL_ERROR\fR with an error -message in \fBinterp\fR if it is not NULL. +errors\fR, such as invalid flags, the function returns \fBTCL_ERROR\fR with an +error message in \fBinterp\fR if it is not NULL. For conversion errors, \fBTcl_ExternalToUtfDStringEx\fR returns one of the \fBTCL_CONVERT_*\fR errors listed below for \fBTcl_ExternalToUtf\fR. -When one of these conversion errors is returned, an error message is -stored in \fBinterp\fR only if \fBerrorIdxPtr\fR is NULL. Otherwise, no error message +When one of these conversion errors is returned, an error message is stored +in \fBinterp\fR only if \fBerrorIdxPtr\fR is NULL. Otherwise, no error message is stored as the function expects the caller is interested the decoded data up to that point and not treating this as an immediate error condition. The index of the error location is stored in \fB*errorIdxPtr\fR. @@ -266,8 +266,8 @@ the unconverted bytes that remained in \fIsrc\fR plus some further bytes from the source stream to properly convert the formerly split-up multibyte sequence. .IP \fBTCL_CONVERT_SYNTAX\fR 29 -The source buffer contained an invalid byte or character sequence. This may occur -if the input stream has been damaged or if the input encoding method was +The source buffer contained an invalid byte or character sequence. This may +occur if the input stream has been damaged or if the input encoding method was misidentified. .IP \fBTCL_CONVERT_UNKNOWN\fR 29 The source buffer contained a character that could not be represented in @@ -284,11 +284,12 @@ encoding, a default fallback character will be used. The return value is a pointer to the value stored in the DString. .PP \fBTcl_UtfToExternalDStringEx\fR is an enhanced version of -\fBTcl_UtfToExternalDString\fR that transforms UTF-8 encoded source data to a specified -\fIencoding\fR. Except for the direction of the transform, the parameters and -return values are identical to those of \fBTcl_ExternalToUtfDStringEx\fR. See +\fBTcl_UtfToExternalDString\fR that transforms UTF-8 encoded source data to a +specified \fIencoding\fR. Except for the direction of the transform, the +parameters and return values are identical to those of +\fBTcl_ExternalToUtfDStringEx\fR. See that function above for details about the same. - +.PP Irrespective of the return code from the function, the caller must free resources associated with \fB*dstPtr\fR when the function returns. .PP @@ -364,7 +365,7 @@ about the name of the encoding and the procedures that will be called to convert between this encoding and UTF-8. It is defined as follows: .PP .CS -typedef struct Tcl_EncodingType { +typedef struct { const char *\fIencodingName\fR; Tcl_EncodingConvertProc *\fItoUtfProc\fR; Tcl_EncodingConvertProc *\fIfromUtfProc\fR; diff --git a/doc/Ensemble.3 b/doc/Ensemble.3 index 71a53ac..96fff06 100644 --- a/doc/Ensemble.3 +++ b/doc/Ensemble.3 @@ -161,6 +161,7 @@ All command names in prefixes set via \fBTcl_SetEnsembleMappingDict\fR must be fully qualified. .TP \fBformal pre-subcommand parameter list\fR (read-write) +. A list of formal parameter names (the names only being used when generating error messages) that come at invocation of the ensemble between the name of the ensemble and the subcommand argument. NULL (the default) is equivalent to @@ -35,8 +35,8 @@ Tcl_ExitProc * .AS Tcl_ExitProc clientData .AP int status in Provides information about why the application or thread exited. -Exact meaning may -be platform-specific. 0 usually means a normal exit, any nonzero value +Exact meaning may be platform-specific. +0 usually means a normal exit, any nonzero value usually means that an error occurred. .AP Tcl_ExitProc *proc in Procedure to invoke before exiting application, or (for @@ -53,14 +53,14 @@ execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the application's state before ending the execution of \fBTcl\fR code. .PP Invoke \fBTcl_Exit\fR to end a \fBTcl\fR application and to exit from this -process. This procedure is invoked by the \fBexit\fR command, and can be +process. This procedure is invoked by the \fBexit\fR Tcl command, and can be invoked anyplace else to terminate the application. -No-one should ever invoke the \fBexit\fR system procedure directly; always +No-one should ever invoke the \fBexit()\fR system call directly; always invoke \fBTcl_Exit\fR instead, so that it can invoke exit handlers. -Note that if other code invokes \fBexit\fR system procedure directly, or +Note that if other code invokes \fBexit()\fR system call directly, or otherwise causes the application to terminate without calling \fBTcl_Exit\fR, the exit handlers will not be run. -\fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never +\fBTcl_Exit\fR internally invokes the \fBexit()\fR system call, thus it never returns control to its caller. If an application exit handler has been installed (see \fBTcl_SetExitProc\fR), that handler is invoked with an argument @@ -140,4 +140,5 @@ entry in the stub table is deprecated and it will be removed in Tcl 9.0. .SH "SEE ALSO" exit(n) .SH KEYWORDS -abort, callback, cleanup, dynamic loading, end application, exit, unloading, thread +abort, callback, cleanup, dynamic loading, end application, exit, unloading, +thread diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index cc19ea8..b015133 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.3 @@ -372,7 +372,8 @@ variable to the POSIX error code (which signifies a .QW "cross-domain link" ). .PP -\fBTcl_FSCopyDirectory\fR attempts to copy the directory given by \fIsrcPathPtr\fR to the +\fBTcl_FSCopyDirectory\fR attempts to copy the directory given by +\fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR. If the two paths given lie in the same filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that filesystem's @@ -482,8 +483,9 @@ is a Tcl_Obj specifying the contents of the symbolic link given by \fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned by the caller, which should call \fBTcl_DecrRefCount\fR when the result is no longer needed. If the \fItoPtr\fR is not NULL, Tcl should create a link -of one of the types passed in in the \fIlinkAction\fR flag. This flag is -an OR'ed combination of \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR. +of one of the types passed in in the \fIlinkAction\fR flag. +This flag is an OR'ed combination of \fBTCL_CREATE_SYMBOLIC_LINK\fR +and \fBTCL_CREATE_HARD_LINK\fR. Where a choice exists (i.e.\ more than one flag is passed in), the Tcl convention is to prefer symbolic links. When a link is successfully created, the return value should be \fItoPtr\fR (which is therefore @@ -848,7 +850,7 @@ longer be correct. The \fBTcl_Filesystem\fR structure contains the following fields: .PP .CS -typedef struct Tcl_Filesystem { +typedef struct { const char *\fItypeName\fR; int \fIstructureLength\fR; Tcl_FSVersion \fIversion\fR; @@ -1263,7 +1265,7 @@ The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR parameter contains the following fields: .PP .CS -typedef struct Tcl_GlobTypeData { +typedef struct { /* Corresponds to bcdpfls as in 'find -t' */ int \fItype\fR; /* Corresponds to file permissions */ @@ -1391,10 +1393,10 @@ typedef int \fBTcl_FSFileAttrsGetProc\fR( .PP Returns a standard Tcl return code. The attribute value retrieved, which corresponds to the \fIindex\fR'th element in the list returned by -the \fBTcl_FSFileAttrStringsProc\fR, is a Tcl_Obj placed in \fIobjPtrRef\fR (if -\fBTCL_OK\fR was returned) and is likely to have a reference count of zero. Either -way we must either store it somewhere (e.g.\ the Tcl result), or -Incr/Decr its reference count to ensure it is properly freed. +the \fBTcl_FSFileAttrStringsProc\fR, is a Tcl_Obj placed in \fIobjPtrRef\fR +(if \fBTCL_OK\fR was returned) and is likely to have a reference count of +zero. Either way we must either store it somewhere (e.g.\ the Tcl result), +or Incr/Decr its reference count to ensure it is properly freed. .SS FILEATTRSSETPROC .PP Function to process a \fBTcl_FSFileAttrsSet\fR call, used by \fBfile diff --git a/doc/GetCwd.3 b/doc/GetCwd.3 index b19f587..7a3b811 100644 --- a/doc/GetCwd.3 +++ b/doc/GetCwd.3 @@ -46,7 +46,7 @@ The format of the path is UTF\-8. .PP \fBTcl_Chdir\fR changes the applications current working directory to the value specified in \fIdirName\fR. The format of the passed in string -must be UTF\-8. The function returns -1 on error or 0 on success. +must be UTF\-8. The function returns \-1 on error or 0 on success. .SH KEYWORDS pwd diff --git a/doc/GetIndex.3 b/doc/GetIndex.3 index 176b0b2..ce01a5d 100644 --- a/doc/GetIndex.3 +++ b/doc/GetIndex.3 @@ -89,7 +89,7 @@ the table and the index of the matching entry. If \fBTcl_GetIndexFromObj\fR is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR arguments (e.g. during a reinvocation of a Tcl command), it returns the matching index immediately without having to redo the lookup -operation. Note: \fBTcl_GetIndexFromObj\fR assumes that the entries +operation. Note that \fBTcl_GetIndexFromObj\fR assumes that the entries in \fItablePtr\fR are static: they must not change between invocations. This caching mechanism can be disallowed by specifying the \fBTCL_INDEX_TEMP_TABLE\fR flag. diff --git a/doc/GetTime.3 b/doc/GetTime.3 index 9dc4056..0756d25 100644 --- a/doc/GetTime.3 +++ b/doc/GetTime.3 @@ -43,7 +43,7 @@ The \fBTcl_GetTime\fR function retrieves the current time as a structure has the following definition: .PP .CS -typedef struct Tcl_Time { +typedef struct { long \fIsec\fR; long \fIusec\fR; } \fBTcl_Time\fR; @@ -52,7 +52,7 @@ typedef struct Tcl_Time { On return, the \fIsec\fR member of the structure is filled in with the number of seconds that have elapsed since the \fIepoch:\fR the epoch is the point in time of 00:00 UTC, 1 January 1970. This number does -\fInot\fR count leap seconds \- an interval of one day advances it by +\fInot\fR count leap seconds; an interval of one day advances it by 86400 seconds regardless of whether a leap second has been inserted. .PP The \fIusec\fR member of the structure is filled in with the number of @@ -247,7 +247,7 @@ calling \fBTcl_InitCustomHashTable\fR. The \fBTcl_HashKeyType\fR structure is defined as follows: .PP .CS -typedef struct Tcl_HashKeyType { +typedef struct { int \fIversion\fR; int \fIflags\fR; Tcl_HashKeyProc *\fIhashKeyProc\fR; @@ -16,6 +16,7 @@ int .sp const char * \fBTcl_SetPreInitScript\fR(\fIscriptPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in @@ -38,9 +39,8 @@ A value of \fINULL\fR may be passed to not register any script. The pre-initialization script is executed by \fBTcl_Init\fR before accessing the file system. The purpose is to typically prepare a custom file system (like an embedded zip-file) to be activated before the search. - +.PP .SH "SEE ALSO" Tcl_AppInit, Tcl_Main - .SH KEYWORDS application, initialization, interpreter @@ -158,7 +158,7 @@ the routine. .SH EXAMPLE .PP The following command uses \fBTcl_EvalObjEx\fR, which consumes space on the C -stack, to evalute a script: +stack, to evaluate a script: .PP .CS int diff --git a/doc/Notifier.3 b/doc/Notifier.3 index 7cb02f6..6c379bc 100644 --- a/doc/Notifier.3 +++ b/doc/Notifier.3 @@ -266,7 +266,7 @@ a structure that describes a time interval in seconds and microseconds: .PP .CS -typedef struct Tcl_Time { +typedef struct { long \fIsec\fR; long \fIusec\fR; } \fBTcl_Time\fR; @@ -328,7 +328,7 @@ structure is used when communicating between the event source and the rest of the notifier. A \fBTcl_Event\fR has the following definition: .PP .CS -typedef struct { +typedef struct Tcl_Event { Tcl_EventProc *\fIproc\fR; struct Tcl_Event *\fInextPtr\fR; } \fBTcl_Event\fR; @@ -544,7 +544,7 @@ passing a pointer to a \fBTcl_NotifierProcs\fR data structure. The structure has the following layout: .PP .CS -typedef struct Tcl_NotifierProcs { +typedef struct { Tcl_SetTimerProc *\fIsetTimerProc\fR; Tcl_WaitForEventProc *\fIwaitForEventProc\fR; Tcl_CreateFileHandlerProc *\fIcreateFileHandlerProc\fR; @@ -627,4 +627,5 @@ mode. Tcl_CreateFileHandler(3), Tcl_DeleteFileHandler(3), Tcl_Sleep(3), Tcl_DoOneEvent(3), Thread(3) .SH KEYWORDS -event, notifier, event queue, event sources, file events, timer, idle, service mode, threads +event, notifier, event queue, event sources, file events, timer, idle, +service mode, threads diff --git a/doc/Object.3 b/doc/Object.3 index 2099552..818ba45 100644 --- a/doc/Object.3 +++ b/doc/Object.3 @@ -27,6 +27,7 @@ int \fBTcl_IsShared\fR(\fIobjPtr\fR) .sp \fBTcl_InvalidateStringRep\fR(\fIobjPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_Obj *objPtr .AP Tcl_Obj *objPtr in @@ -110,7 +111,7 @@ Each Tcl value is represented by a \fBTcl_Obj\fR structure which is defined as follows. .PP .CS -typedef struct Tcl_Obj { +typedef struct { int \fIrefCount\fR; char *\fIbytes\fR; int \fIlength\fR; @@ -278,26 +279,26 @@ The string representation is now \fB124\fR and both representations are again valid. .SH "STORAGE MANAGEMENT OF VALUES" .PP -Tcl values are allocated on the heap and are shared as much as possible -to reduce storage requirements. -Reference counting is used to determine when a value is -no longer needed and can safely be freed. -A value just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR -has \fIrefCount\fR 0, meaning that the object can often be given to a function -like \fBTcl_SetObjResult\fR, \fBTcl_ListObjAppendElement\fR, or -\fBTcl_DictObjPut\fR (as a value) without explicit reference management, all -of which are common use cases. (The latter two require that the the target -list or dictionary be well-formed, but that is often easy to arrange when the -value is being initially constructed.) -The macro \fBTcl_IncrRefCount\fR increments the reference count -when a new reference to the value is created. -The macro \fBTcl_DecrRefCount\fR decrements the count -when a reference is no longer needed and, -if the value's reference count drops to zero, frees its storage. +Tcl values are allocated on the heap and are shared as much as +possible to reduce storage requirements. Reference counting is used +to determine when a value is no longer needed and can safely be freed. +A value just created by \fBTcl_NewObj\fR, \fBTcl_NewStringObj\fR, or +any Abstract List command or function, has \fIrefCount\fR 0, meaning +that the object can often be given to a function like +\fBTcl_SetObjResult\fR, \fBTcl_ListObjAppendElement\fR, or +\fBTcl_DictObjPut\fR (as a value) without explicit reference +management, all of which are common use cases. (The latter two require +that the target list or dictionary be well-formed, but that is +often easy to arrange when the value is being initially constructed.) +The macro \fBTcl_IncrRefCount\fR increments the reference count when a +new reference to the value is created. +The macro \fBTcl_DecrRefCount\fR decrements the count when a reference +is no longer needed. If the value's reference count drops to zero, frees +its storage. A value shared by different code or data structures has -\fIrefCount\fR greater than 1. -Incrementing a value's reference count ensures that -it will not be freed too early or have its value change accidentally. +\fIrefCount\fR greater than 1. Incrementing a value's reference count +ensures that it will not be freed too early or have its value change +accidentally. .PP As an example, the bytecode interpreter shares argument values between calling and called Tcl procedures to avoid having to copy values. diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 index 4a4ca13..cc33a0a 100644 --- a/doc/ObjectType.3 +++ b/doc/ObjectType.3 @@ -154,17 +154,16 @@ This definition permits us to pass internal representations and pointers to them as arguments and results in public routines. .SH "THE TCL_OBJTYPE STRUCTURE" .PP -Extension writers can define new value types by defining four -procedures and -initializing a Tcl_ObjType structure to describe the type. -Extension writers may also pass a pointer to their Tcl_ObjType -structure to \fBTcl_RegisterObjType\fR if they wish to permit -other extensions to look up their Tcl_ObjType by name with -the \fBTcl_GetObjType\fR routine. -The \fBTcl_ObjType\fR structure is defined as follows: +Extension writers can define new value types by defining four to eight +procedures and initializing a Tcl_ObjType structure to describe the +type. Extension writers may also pass a pointer to their Tcl_ObjType +structure to \fBTcl_RegisterObjType\fR if they wish to permit other +extensions to look up their Tcl_ObjType by name with the +\fBTcl_GetObjType\fR routine. The \fBTcl_ObjType\fR structure is +defined as follows: .PP .CS -typedef struct Tcl_ObjType { +typedef struct { const char *\fIname\fR; Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR; Tcl_DupInternalRepProc *\fIdupIntRepProc\fR; @@ -334,4 +333,5 @@ then those subsidiary values may have their reference counts modified. .SH "SEE ALSO" Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3) .SH KEYWORDS -internal representation, value, value type, string representation, type conversion +internal representation, value, value type, string representation, +type conversion diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index 85100fc..7c6df60 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -391,7 +391,7 @@ If the channel is being closed synchronously and an error occurs during closing of the channel and \fIinterp\fR is not NULL, an error message is left in the interpreter's result. .PP -Note: it is not safe to call \fBTcl_Close\fR on a channel that has been +Note that it is not safe to call \fBTcl_Close\fR on a channel that has been registered using \fBTcl_RegisterChannel\fR; see the documentation for \fBTcl_RegisterChannel\fR, above, for details. If the channel has ever been given as the \fBchan\fR argument in a call to diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3 index e72556a..63e6aab 100644 --- a/doc/OpenTcp.3 +++ b/doc/OpenTcp.3 @@ -51,7 +51,7 @@ If nonzero, the client socket is connected asynchronously to the server. Length of OS listen backlog queue. Use -1 for default value. .AP "unsigned int" flags in ORed combination of \fBTCL_TCPSERVER_*\fR flags that specify additional -informations about the socket being created. +information about the socket being created. .AP ClientData sock in Platform-specific handle for client TCP socket. .AP Tcl_TcpAcceptProc *proc in diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3 index ecff658..72cd75c 100644 --- a/doc/ParseArgs.3 +++ b/doc/ParseArgs.3 @@ -57,20 +57,14 @@ The collection of arguments to be parsed is described by the \fIargTable\fR parameter. This points to a table of descriptor structures that is terminated by an entry with the \fItype\fR field set to TCL_ARGV_END. As convenience, the following prototypical entries are provided: -.TP -\fBTCL_ARGV_AUTO_HELP\fR -. +.IP \fBTCL_ARGV_AUTO_HELP\fR Enables the argument processor to provide help when passed the argument .QW \fB\-help\fR . -.TP -\fBTCL_ARGV_AUTO_REST\fR -. +.IP \fBTCL_ARGV_AUTO_REST\fR Instructs the argument processor that arguments after .QW \fB\-\-\fR are to be unprocessed. -.TP -\fBTCL_ARGV_TABLE_END\fR -. +.IP \fBTCL_ARGV_TABLE_END\fR Marks the end of the table of argument descriptors. .SS "ARGUMENT DESCRIPTOR ENTRIES" .PP @@ -99,27 +93,19 @@ users when they request it. As noted above, the \fItype\fR field is used to describe the interpretation of the argument's value. The following values are acceptable values for \fItype\fR: -.TP -\fBTCL_ARGV_CONSTANT\fR -. +.IP \fBTCL_ARGV_CONSTANT\fR The argument does not take any following value argument. If this argument is present, the (integer) value of the \fIsrcPtr\fR field is copied to the variable pointed to by the \fIdstPtr\fR field. The \fIclientData\fR field is ignored. -.TP -\fBTCL_ARGV_END\fR -. +.IP \fBTCL_ARGV_END\fR This value marks the end of all option descriptors in the table. All other fields are ignored. -.TP -\fBTCL_ARGV_FLOAT\fR -. +.IP \fBTCL_ARGV_FLOAT\fR This argument takes a following floating point value argument. The value (once parsed by \fBTcl_GetDoubleFromObj\fR) will be stored as a double-precision value in the variable pointed to by the \fIdstPtr\fR field. The \fIsrcPtr\fR and \fIclientData\fR fields are ignored. -.TP -\fBTCL_ARGV_FUNC\fR -. +.IP \fBTCL_ARGV_FUNC\fR This argument optionally takes a following value argument; it is up to the handler callback function passed in \fIsrcPtr\fR to decide. That function will have the following signature: @@ -138,9 +124,7 @@ argument. The \fIclientData\fR is the value from the table entry, the there are no following arguments at all, and the \fIdstPtr\fR argument to the \fBTcl_ArgvFuncProc\fR is the location to write the parsed value to. .RE -.TP -\fBTCL_ARGV_GENFUNC\fR -. +.IP \fBTCL_ARGV_GENFUNC\fR This argument takes zero or more following arguments; the handler callback function passed in \fIsrcPtr\fR returns how many (or a negative number to signal an error, in which case it should also set the interpreter result). The @@ -162,28 +146,20 @@ an array of all the remaining arguments, and \fIdstPtr\fR argument to the \fBTcl_ArgvGenFuncProc\fR is the location to write the parsed value (or values) to. .RE -.TP -\fBTCL_ARGV_HELP\fR -. +.IP \fBTCL_ARGV_HELP\fR This special argument does not take any following value argument, but instead causes \fBTcl_ParseArgsObjv\fR to generate an error message describing the arguments supported. All other fields except the \fIhelpStr\fR field are ignored. -.TP -\fBTCL_ARGV_INT\fR -. +.IP \fBTCL_ARGV_INT\fR This argument takes a following integer value argument. The value (once parsed by \fBTcl_GetIntFromObj\fR) will be stored as an int in the variable pointed to by the \fIdstPtr\fR field. The \fIsrcPtr\fR field is ignored. -.TP -\fBTCL_ARGV_REST\fR -. +.IP \fBTCL_ARGV_REST\fR This special argument does not take any following value argument, but instead marks all following arguments to be left unprocessed. The \fIsrcPtr\fR, \fIdstPtr\fR and \fIclientData\fR fields are ignored. -.TP -\fBTCL_ARGV_STRING\fR -. +.IP \fBTCL_ARGV_STRING\fR This argument takes a following string value argument. A pointer to the string will be stored at \fIdstPtr\fR; the string inside will have a lifetime linked to the lifetime of the string representation of the argument value that it diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 index d413315..e61cbf3 100644 --- a/doc/ParseCmd.3 +++ b/doc/ParseCmd.3 @@ -209,7 +209,7 @@ of \fBTcl_EvalTokens\fR is deprecated. return parse information in two data structures, Tcl_Parse and Tcl_Token: .PP .CS -typedef struct Tcl_Parse { +typedef struct { const char *\fIcommentStart\fR; int \fIcommentSize\fR; const char *\fIcommandStart\fR; @@ -220,7 +220,7 @@ typedef struct Tcl_Parse { ... } \fBTcl_Parse\fR; -typedef struct Tcl_Token { +typedef struct { int \fItype\fR; const char *\fIstart\fR; int \fIsize\fR; @@ -234,8 +234,7 @@ These fields are not used by the other parsing procedures. .PP \fBTcl_ParseCommand\fR fills in a Tcl_Parse structure with information that describes one Tcl command and any comments that -precede the command. -If there are comments, +precede the command. If there are comments, the \fIcommentStart\fR field points to the \fB#\fR character that begins the first comment and \fIcommentSize\fR indicates the number of bytes in all of the comments preceding the command, including the newline @@ -265,9 +264,7 @@ such as \fBTCL_TOKEN_WORD\fR and \fBTCL_TOKEN_VARIABLE\fR, consist of several component tokens, which immediately follow the parent token; the \fInumComponents\fR field describes how many of these there are. The \fItype\fR field has one of the following values: -.TP 20 -\fBTCL_TOKEN_WORD\fR -. +.IP \fBTCL_TOKEN_WORD\fR This token ordinarily describes one word of a command but it may also describe a quoted or braced string in an expression. The token describes a component of the script that is @@ -280,42 +277,30 @@ space, semicolon, close bracket, close quote, or close brace that terminates the component. The \fInumComponents\fR field counts the total number of sub-tokens that make up the word, including sub-tokens of \fBTCL_TOKEN_VARIABLE\fR and \fBTCL_TOKEN_BS\fR tokens. -.TP -\fBTCL_TOKEN_SIMPLE_WORD\fR -. +.IP \fBTCL_TOKEN_SIMPLE_WORD\fR This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR sub-token. The \fInumComponents\fR field is always 1. -.TP -\fBTCL_TOKEN_EXPAND_WORD\fR -. +.IP \fBTCL_TOKEN_EXPAND_WORD\fR This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that the command parser notes this word began with the expansion prefix \fB{*}\fR, indicating that after substitution, the list value of this word should be expanded to form multiple arguments in command evaluation. This token type can only be created by Tcl_ParseCommand. -.TP -\fBTCL_TOKEN_TEXT\fR -. +.IP \fBTCL_TOKEN_TEXT\fR The token describes a range of literal text that is part of a word. The \fInumComponents\fR field is always 0. -.TP -\fBTCL_TOKEN_BS\fR -. +.IP \fBTCL_TOKEN_BS\fR The token describes a backslash sequence such as \fB\en\fR or \fB\e0xA3\fR. The \fInumComponents\fR field is always 0. -.TP -\fBTCL_TOKEN_COMMAND\fR -. +.IP \fBTCL_TOKEN_COMMAND\fR The token describes a command whose result must be substituted into the word. The token includes the square brackets that surround the command. The \fInumComponents\fR field is always 0 (the nested command is not parsed; call \fBTcl_ParseCommand\fR recursively if you want to see its tokens). -.TP -\fBTCL_TOKEN_VARIABLE\fR -. +.IP \fBTCL_TOKEN_VARIABLE\fR The token describes a variable substitution, including the \fB$\fR, variable name, and array index (if there is one) up through the close parenthesis that terminates the index. This token is followed @@ -329,9 +314,7 @@ token giving the array name and the remaining sub-tokens are \fBTCL_TOKEN_VARIABLE\fR tokens that must be concatenated to produce the array index. The \fInumComponents\fR field includes nested sub-tokens that are part of \fBTCL_TOKEN_VARIABLE\fR tokens in the array index. -.TP -\fBTCL_TOKEN_SUB_EXPR\fR -. +.IP \fBTCL_TOKEN_SUB_EXPR\fR The token describes one subexpression of an expression (or an entire expression). A subexpression may consist of a value @@ -356,9 +339,7 @@ one of the token types \fBTCL_TOKEN_WORD\fR, \fBTCL_TOKEN_TEXT\fR, The \fInumComponents\fR field counts the total number of sub-tokens that make up the subexpression; this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens. -.TP -\fBTCL_TOKEN_OPERATOR\fR -. +.IP \fBTCL_TOKEN_OPERATOR\fR The token describes one operator of an expression such as \fB&&\fR or \fBhypot\fR. A \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a @@ -472,4 +453,5 @@ result value to dispose of it. (The equivalent with \fBTcl_EvalTokenStandard\fR is just the interpreter result, which can be retrieved with \fBTcl_GetObjResult\fR.) .SH KEYWORDS -backslash substitution, braces, command, expression, parse, token, variable substitution +backslash substitution, braces, command, expression, parse, token, +variable substitution diff --git a/doc/RegConfig.3 b/doc/RegConfig.3 index ef46ba5..46be360 100644 --- a/doc/RegConfig.3 +++ b/doc/RegConfig.3 @@ -87,20 +87,23 @@ their associated values can be retrieved through calls to The command \fBpkgconfig\fR will provide two subcommands, \fBlist\fR and \fBget\fR: .RS +.\" METHOD: list .TP ::\fIpkgName\fR::\fBpkgconfig\fR list +. Returns a list containing the names of all defined keys. +.\" METHOD: get .TP ::\fIpkgName\fR::\fBpkgconfig\fR get \fIkey\fR -Returns the configuration value associated with the specified -\fIkey\fR. +. +Returns the configuration value associated with the specified \fIkey\fR. .RE .SH TCL_CONFIG .PP The \fBTcl_Config\fR structure contains the following fields: .PP .CS -typedef struct Tcl_Config { +typedef struct { const char *\fIkey\fR; const char *\fIvalue\fR; } \fBTcl_Config\fR; diff --git a/doc/RegExp.3 b/doc/RegExp.3 index 40429c9..4010f13 100644 --- a/doc/RegExp.3 +++ b/doc/RegExp.3 @@ -124,7 +124,7 @@ used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR. If an error occurs while compiling the regular expression then \fBTcl_RegExpCompile\fR returns NULL and leaves an error message in the interpreter result. -Note: the return value from \fBTcl_RegExpCompile\fR is only valid +Note that the return value from \fBTcl_RegExpCompile\fR is only valid up to the next call to \fBTcl_RegExpCompile\fR; it is not safe to retain these values for long periods of time. .PP @@ -190,6 +190,7 @@ zero or more of the following flags that control the compilation of .RS 2 .TP \fBTCL_REG_ADVANCED\fR +. Compile advanced regular expressions .PQ ARE s . This mode corresponds to @@ -197,6 +198,7 @@ the normal regular expression syntax accepted by the Tcl \fBregexp\fR and \fBregsub\fR commands. .TP \fBTCL_REG_EXTENDED\fR +. Compile extended regular expressions .PQ ERE s . This mode corresponds @@ -204,6 +206,7 @@ to the regular expression syntax recognized by Tcl 8.0 and earlier versions. .TP \fBTCL_REG_BASIC\fR +. Compile basic regular expressions .PQ BRE s . This mode corresponds @@ -212,18 +215,22 @@ like \fBsed\fR and \fBgrep\fR. This is the default if no flags are specified. .TP \fBTCL_REG_EXPANDED\fR +. Compile the regular expression (basic, extended, or advanced) using an expanded syntax that allows comments and whitespace. This mode causes non-backslashed non-bracket-expression white space and #-to-end-of-line comments to be ignored. .TP \fBTCL_REG_QUOTE\fR +. Compile a literal string, with all characters treated as ordinary characters. .TP \fBTCL_REG_NOCASE\fR +. Compile for matching that ignores upper/lower case distinctions. .TP \fBTCL_REG_NEWLINE\fR +. Compile for newline-sensitive matching. By default, newline is a completely ordinary character with no special meaning in either regular expressions or strings. With this flag, @@ -241,6 +248,7 @@ an empty string before any newline in addition to its normal function. \fBREG_NLANCH\fR. .TP \fBTCL_REG_NLSTOP\fR +. Compile for partial newline-sensitive matching, with the behavior of .QW [^ @@ -257,6 +265,7 @@ bracket expressions and never match newline. .TP \fBTCL_REG_NLANCH\fR +. Compile for inverse partial newline-sensitive matching, with the behavior of .QW ^ @@ -277,12 +286,14 @@ matches an empty string before any newline in addition to its normal function. .TP \fBTCL_REG_NOSUB\fR +. Compile for matching that reports only success or failure, not what was matched. This reduces compile overhead and may improve performance. Subsequent calls to \fBTcl_RegExpGetInfo\fR or \fBTcl_RegExpRange\fR will not report any match information. .TP \fBTCL_REG_CANMATCH\fR +. Compile for matching that reports the potential to complete a partial match given more text (see below). .RE @@ -312,6 +323,7 @@ zero or more of the following flags: .RS 2 .TP \fBTCL_REG_NOTBOL\fR +. The starting character will not be treated as the beginning of a line or the beginning of the string, so .QW ^ @@ -321,6 +333,7 @@ Note that this flag has no effect on how matches. .TP \fBTCL_REG_NOTEOL\fR +. The last character in the string will not be treated as the end of a line or the end of the string, so .QW $ @@ -336,7 +349,7 @@ performed with a given regular expression \fIregexp\fR. The defined as follows: .PP .CS -typedef struct Tcl_RegExpInfo { +typedef struct { int \fInsubs\fR; Tcl_RegExpIndices *\fImatches\fR; long \fIextendStart\fR; @@ -354,7 +367,7 @@ appear in the pattern. Each element is a structure that is defined as follows: .PP .CS -typedef struct Tcl_RegExpIndices { +typedef struct { long \fIstart\fR; long \fIend\fR; } \fBTcl_RegExpIndices\fR; @@ -396,4 +409,5 @@ additional reference being taken. .SH "SEE ALSO" re_syntax(n) .SH KEYWORDS -match, pattern, regular expression, string, subexpression, Tcl_RegExpIndices, Tcl_RegExpInfo +match, pattern, regular expression, string, subexpression, +Tcl_RegExpIndices, Tcl_RegExpInfo diff --git a/doc/SetVar.3 b/doc/SetVar.3 index 9d8e0b7..98b46d8 100644 --- a/doc/SetVar.3 +++ b/doc/SetVar.3 @@ -168,6 +168,7 @@ options to the procedures. It consists of an OR-ed combination of the following bits. .TP \fBTCL_GLOBAL_ONLY\fR +. Under normal circumstances the procedures look up variables as follows. If a procedure call is active in \fIinterp\fR, the variable is looked up at the current level of procedure call. @@ -180,12 +181,14 @@ If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given, \fBTCL_GLOBAL_ONLY\fR is ignored. .TP \fBTCL_NAMESPACE_ONLY\fR +. If this bit is set in \fIflags\fR then the variable is looked up only in the current namespace; if a procedure is active its variables are ignored, and the global namespace is also ignored unless it is the current namespace. .TP \fBTCL_LEAVE_ERR_MSG\fR +. If an error is returned and this bit is set in \fIflags\fR, then an error message will be left in the interpreter's result, where it can be retrieved with \fBTcl_GetObjResult\fR @@ -194,12 +197,14 @@ If this flag bit is not set then no error message is left and the interpreter's result will not be modified. .TP \fBTCL_APPEND_VALUE\fR +. If this bit is set then \fInewValuePtr\fR or \fInewValue\fR is appended to the current value instead of replacing it. If the variable is currently undefined, then the bit is ignored. This bit is only used by the \fBTcl_Set*\fR procedures. .TP \fBTCL_LIST_ELEMENT\fR +. If this bit is set, then \fInewValue\fR is converted to a valid Tcl list element before setting (or appending to) the variable. A separator space is appended before the new list element unless diff --git a/doc/StdChannels.3 b/doc/StdChannels.3 index d3ecff2..e22e326 100644 --- a/doc/StdChannels.3 +++ b/doc/StdChannels.3 @@ -45,8 +45,7 @@ standard channels. (A channel is not if it could not be successfully opened; for example, in a Tcl application run as a Windows NT service.) -.TP -1) +.IP 1) A single standard channel is initialized when it is explicitly specified in a call to \fBTcl_SetStdChannel\fR. The states of the other standard channels are unaffected. @@ -55,17 +54,14 @@ other standard channels are unaffected. Missing platform-specific standard channels do not matter here. This approach is not available at the script level. .RE -.TP -2) +.IP 2) All uninitialized standard channels are initialized to platform-specific default values: .RS -.TP -(a) +.IP (a) when open channels are listed with \fBTcl_GetChannelNames\fR (or the \fBfile channels\fR script command), or -.TP -(b) +.IP (b) when information about any standard channel is requested with a call to \fBTcl_GetStdChannel\fR, or with a call to \fBTcl_GetChannel\fR which specifies one of the standard names (\fBstdin\fR, \fBstdout\fR @@ -76,8 +72,7 @@ standard channels are considered as initialized and then immediately closed. This means that the first three Tcl channels then opened by the application are designated as the Tcl standard channels. .RE -.TP -3) +.IP 3) All uninitialized standard channels are initialized to platform-specific default values when a user-requested channel is registered with \fBTcl_RegisterChannel\fR. diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 87a6c58..44b2500 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -84,6 +84,7 @@ int .sp Tcl_Obj * \fBTcl_ConcatObj\fR(\fIobjc, objv\fR) +.fi .SH ARGUMENTS .AS "const Tcl_UniChar" *appendObjPtr in/out .AP "const char" *bytes in @@ -118,7 +119,7 @@ The index of the last Unicode character in the Unicode range to be returned as a new value. If negative, take all characters up to the last one available. .AP Tcl_Obj *objPtr in/out -Points to a value to manipulate. +A pointer to a value to read, or to an unshared value to modify. .AP Tcl_Obj *appendObjPtr in The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. .AP int *lengthPtr out diff --git a/doc/TclZlib.3 b/doc/TclZlib.3 index c2d7f6d..7a9628c 100644 --- a/doc/TclZlib.3 +++ b/doc/TclZlib.3 @@ -219,47 +219,33 @@ an unshared dictionary value). .PP The following fields in the dictionary value are understood. All other fields are ignored. No field is required when creating a gzip-format stream. -.TP -\fBcomment\fR -. +.IP \fBcomment\fR This holds the comment field of the header, if present. If absent, no comment was supplied (on decompression) or will be created (on compression). -.TP -\fBcrc\fR -. +.IP \fBcrc\fR A boolean value describing whether a CRC of the header is computed. Note that the \fBgzip\fR program does \fInot\fR use or allow a CRC on the header. -.TP -\fBfilename\fR -. +.IP \fBfilename\fR The name of the file that held the uncompressed data. This should not contain any directory separators, and should be sanitized before use on decompression with \fBfile tail\fR. -.TP -\fBos\fR -. +.IP \fBos\fR The operating system type code field from the header (if not the .QW unknown value). See RFC 1952 for the meaning of these codes. On compression, if this is absent then the field will be set to the .QW unknown value. -.TP -\fBsize\fR -. +.IP \fBsize\fR The size of the uncompressed data. This is ignored on compression; the size of the data compressed depends on how much data is supplied to the compression engine. -.TP -\fBtime\fR -. +.IP \fBtime\fR The time field from the header if non-zero, expected to be the time that the file named by the \fBfilename\fR field was modified. Suitable for use with \fBclock format\fR. On creation, the right value to use is that from \fBclock seconds\fR or \fBfile mtime\fR. -.TP -\fBtype\fR -. +.IP \fBtype\fR The type of the uncompressed data (either \fBbinary\fR or \fBtext\fR) if known. .SH "REFERENCE COUNT MANAGEMENT" diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3 index 99914a6..94e8e64 100644 --- a/doc/TraceCmd.3 +++ b/doc/TraceCmd.3 @@ -54,9 +54,11 @@ trace procedure is to be invoked. It consists of an OR'ed combination of any of the following values: .TP \fBTCL_TRACE_RENAME\fR +. Invoke \fIproc\fR whenever the command is renamed. .TP \fBTCL_TRACE_DELETE\fR +. Invoke \fIproc\fR when the command is deleted. .PP Whenever one of the specified operations occurs to the command, diff --git a/doc/TraceVar.3 b/doc/TraceVar.3 index 5de6a44..587ca70 100644 --- a/doc/TraceVar.3 +++ b/doc/TraceVar.3 @@ -76,22 +76,27 @@ for setting up the trace. It consists of an OR-ed combination of any of the following values: .TP \fBTCL_GLOBAL_ONLY\fR +. Normally, the variable will be looked up at the current level of procedure call; if this bit is set then the variable will be looked up at global level, ignoring any active procedures. .TP \fBTCL_NAMESPACE_ONLY\fR +. Normally, the variable will be looked up at the current level of procedure call; if this bit is set then the variable will be looked up in the current namespace, ignoring any active procedures. .TP \fBTCL_TRACE_READS\fR +. Invoke \fIproc\fR whenever an attempt is made to read the variable. .TP \fBTCL_TRACE_WRITES\fR +. Invoke \fIproc\fR whenever an attempt is made to modify the variable. .TP \fBTCL_TRACE_UNSETS\fR +. Invoke \fIproc\fR whenever the variable is unset. A variable may be unset either explicitly by an \fBunset\fR command, or implicitly when a procedure returns (its local variables are @@ -99,18 +104,21 @@ automatically unset) or when the interpreter or namespace is deleted (all variables are automatically unset). .TP \fBTCL_TRACE_ARRAY\fR +. Invoke \fIproc\fR whenever the array command is invoked. This gives the trace procedure a chance to update the array before array names or array get is called. Note that this is called before an array set, but that will trigger write traces. .TP \fBTCL_TRACE_RESULT_DYNAMIC\fR +. The result of invoking the \fIproc\fR is a dynamically allocated string that will be released by the Tcl library via a call to \fBckfree\fR. Must not be specified at the same time as \fBTCL_TRACE_RESULT_OBJECT\fR. .TP \fBTCL_TRACE_RESULT_OBJECT\fR +. The result of invoking the \fIproc\fR is a Tcl_Obj* (cast to a char*) with a reference count of at least one. The ownership of that reference will be transferred to the Tcl core for release (when the diff --git a/doc/UniCharIsAlpha.3 b/doc/UniCharIsAlpha.3 index 61490ed..3ce402a 100644 --- a/doc/UniCharIsAlpha.3 +++ b/doc/UniCharIsAlpha.3 @@ -45,6 +45,7 @@ int .sp int \fBTcl_UniCharIsWordChar\fR(\fIch\fR) +.fi .SH ARGUMENTS .AS int ch .AP int ch in @@ -61,15 +62,18 @@ with the various routines. .SH "CHARACTER CLASSES" .PP -\fBTcl_UniCharIsAlnum\fR tests if the character is an alphanumeric Unicode character. +\fBTcl_UniCharIsAlnum\fR tests if the character is an alphanumeric Unicode +character. .PP -\fBTcl_UniCharIsAlpha\fR tests if the character is an alphabetic Unicode character. +\fBTcl_UniCharIsAlpha\fR tests if the character is an alphabetic Unicode +character. .PP \fBTcl_UniCharIsControl\fR tests if the character is a Unicode control character. .PP \fBTcl_UniCharIsDigit\fR tests if the character is a numeric Unicode character. .PP -\fBTcl_UniCharIsGraph\fR tests if the character is any Unicode print character except space. +\fBTcl_UniCharIsGraph\fR tests if the character is any Unicode print character +except space. .PP \fBTcl_UniCharIsLower\fR tests if the character is a lowercase Unicode character. .PP diff --git a/doc/WrongNumArgs.3 b/doc/WrongNumArgs.3 index 533cb4f..4f587aa 100644 --- a/doc/WrongNumArgs.3 +++ b/doc/WrongNumArgs.3 @@ -63,7 +63,7 @@ a subcommand. The command into an \fIindexObject\fR. If an error occurs in the parsing of the subcommand we would like to use the full subcommand name rather than the abbreviation. If the \fBTcl_WrongNumArgs\fR command finds any -\fIindexObjects\fR in the \fIobjv\fR array it will use the full subcommand +\fIindexObject\fRs in the \fIobjv\fR array, it will use the full subcommand name in the error message instead of the abbreviated name that was originally passed in. Using the above example, let us assume that \fIbar\fR is actually an abbreviation for \fIbarfly\fR and the value diff --git a/doc/after.n b/doc/after.n index 1a814e0..db3ffc4 100644 --- a/doc/after.n +++ b/doc/after.n @@ -54,7 +54,7 @@ registered with \fBinterp bgerror\fR. The \fBafter\fR command returns an identifier that can be used to cancel the delayed command using \fBafter cancel\fR. A \fIms\fR value of 0 (or negative) queues the event immediately with -priority over other event types (if not installed withn an event proc, +priority over other event types (if not installed with an event proc, which will wait for next round of events). .TP \fBafter cancel \fIid\fR diff --git a/doc/binary.n b/doc/binary.n index 7968d77..6df3e5a 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -56,11 +56,13 @@ information. .RS .PP During encoding, the following options are supported: +.\" OPTION: -maxlen .TP \fB\-maxlen \fIlength\fR . Indicates that the output should be split into lines of no more than \fIlength\fR characters. By default, lines are not split. +.\" OPTION: -wrapchar .TP \fB\-wrapchar \fIcharacter\fR . @@ -70,6 +72,7 @@ newline character, .QW \en . .PP During decoding, the following options are supported: +.\" OPTION: -strict .TP \fB\-strict\fR . @@ -88,6 +91,7 @@ When decoding, upper and lower characters are accepted. .PP No options are supported during encoding. During decoding, the following options are supported: +.\" OPTION: -strict .TP \fB\-strict\fR . @@ -104,12 +108,14 @@ largely superseded by the \fBbase64\fR binary encoding. .PP During encoding, the following options are supported (though changing them may produce files that other implementations of decoders cannot process): +.\" OPTION: -maxlen .TP \fB\-maxlen \fIlength\fR . Indicates the maximum number of characters to produce for each encoded line. The valid range is 5 to 85. Line lengths outside that range cannot be accommodated by the encoding format. The default value is 61. +.\" OPTION: -wrapchar .TP \fB\-wrapchar \fIcharacter\fR . @@ -121,6 +127,7 @@ they would generate encoded text that could not be decoded. The default value is a single newline. .PP During decoding, the following options are supported: +.\" OPTION: -strict .TP \fB\-strict\fR . @@ -1096,7 +1103,7 @@ base64 and prints them: set f [open $filename rb] set data [read $f] close $f -puts [\fBbinary encode\fR base64 \-maxlen 64 $data] +puts [\fBbinary encode\fR base64 -maxlen 64 $data] .CE .SH "SEE ALSO" encoding(n), format(n), scan(n), string(n), tcl_platform(n) @@ -20,6 +20,7 @@ Change the current working directory to \fIdirName\fR, or to the home directory (as specified in the HOME environment variable) if \fIdirName\fR is not given. Returns an empty string. +.PP Note that the current working directory is a per-process resource; the \fBcd\fR command changes the working directory for all interpreters and all threads. diff --git a/doc/classvariable.n b/doc/classvariable.n index 70d9f13..2eef7e8 100644 --- a/doc/classvariable.n +++ b/doc/classvariable.n @@ -26,8 +26,8 @@ elements. The originating scope for the variables is the namespace of the class that the method was defined by. In other words, the referenced variables are shared between all instances of that class. .PP -Note: This command is equivalent to the command \fBtypevariable\fR provided by -the snit package in tcllib for approximately the same purpose. If used in a +Note that this command is equivalent to the command \fBtypevariable\fR provided +by the snit package in tcllib for approximately the same purpose. If used in a method defined directly on a class instance (e.g., through the \fBoo::objdefine\fR \fBmethod\fR definition) this is very much like just using: diff --git a/doc/configurable.n b/doc/configurable.n index 0102f8c..798612d 100644 --- a/doc/configurable.n +++ b/doc/configurable.n @@ -84,6 +84,7 @@ The \fBproperty\fR command takes the name of a property to define first, \fIwithout a leading hyphen\fR, followed by a number of option-value pairs that modify the basic behavior of the property. This can then be followed by an arbitrary number of other property definitions. The supported options are: +.\" OPTION: -get .TP \fB\-get \fIgetterScript\fR . @@ -97,6 +98,7 @@ of the instance variable with the same name as the property (e.g., will result in a method .QW <ReadProp-xyz> being created). +.\" OPTION: -kind .TP \fB\-kind \fIpropertyKind\fR . @@ -112,6 +114,7 @@ Note that write-only properties are not particularly discoverable as they are never reported by the \fBconfigure\fR method other than by error messages when attempting to write to a property that does not exist. .RE +.\" OPTION: -set .TP \fB\-set \fIsetterScript\fR . diff --git a/doc/cookiejar.n b/doc/cookiejar.n index 7d2f46b..1befca9 100644 --- a/doc/cookiejar.n +++ b/doc/cookiejar.n @@ -44,6 +44,7 @@ to be the given value. .RS .PP Supported options are: +.\" OPTION: -domainfile .TP \fB\-domainfile \fIfilename\fR . @@ -53,6 +54,7 @@ list of top-level domains (e.g., \fB.com\fR or \fB.co.jp\fR). Such domains domains is both security-sensitive and \fInot\fR constant and should be periodically refetched. Cookie jars maintain their own cache of the domain list. +.\" OPTION: -domainlist .TP \fB\-domainlist \fIurl\fR . @@ -61,33 +63,39 @@ A URL to fetch the list of top-level domains (e.g., \fB.com\fR or them. Note that the list of such domains is both security-sensitive and \fInot\fR constant and should be periodically refetched. Cookie jars maintain their own cache of the domain list. +.\" OPTION: -domainrefresh .TP \fB\-domainrefresh \fIintervalMilliseconds\fR . -The number of milliseconds between checks of the \fI\-domainlist\fR for new +The number of milliseconds between checks of the \fB\-domainlist\fR for new domains. +.\" OPTION: -loglevel .TP \fB\-loglevel \fIlevel\fR . The logging level of this package. The logging level must be (in order of decreasing verbosity) one of \fBdebug\fR, \fBinfo\fR, \fBwarn\fR, or \fBerror\fR. +.\" OPTION: -offline .TP \fB\-offline \fIflag\fR . -Allows the cookie managment engine to be placed into offline mode. In offline +Allows the cookie management engine to be placed into offline mode. In offline mode, the list of domains is read immediately from the file configured in the \fB\-domainfile\fR option, and the \fB\-domainlist\fR option is not used; it also makes the \fB\-domainrefresh\fR option be effectively ignored. +.\" OPTION: -purgeold .TP \fB\-purgeold \fIintervalMilliseconds\fR . The number of milliseconds between checks of the database for expired cookies; expired cookies are deleted. +.\" OPTION: -retain .TP \fB\-retain \fIcookieCount\fR . The maximum number of cookies to retain in the database. +.\" OPTION: -vacuumtrigger .TP \fB\-vacuumtrigger \fIdeletionCount\fR . @@ -102,8 +110,8 @@ creation methods (\fBcreate\fR or \fBnew\fR). . If a \fIfilename\fR argument is provided, it is the name of a file containing an SQLite database that will contain the persistent cookies maintained by the -cookie jar; the database will be created if the file does not already -exist. If \fIfilename\fR is not supplied, the database will be held entirely within +cookie jar; the database will be created if the file does not already exist. +If \fIfilename\fR is not supplied, the database will be held entirely within memory, which effectively forces all cookies within it to be session cookies. .SS "INSTANCE METHODS" .PP @@ -137,17 +145,11 @@ after the built-in security checks are done, and should return a boolean value; if the value is false, the operation is rejected and the database is not modified. The supported \fIoperation\fRs are: .RS -.TP -\fBdelete\fR -. +.IP \fBdelete\fR The \fIdomain\fR is seeking to delete a cookie. -.TP -\fBsession\fR -. +.IP \fBsession\fR The \fIdomain\fR is seeking to create or update a session cookie. -.TP -\fBset\fR -. +.IP \fBset\fR The \fIdomain\fR is seeking to create or update a persistent cookie (with a defined lifetime). .PP diff --git a/doc/define.n b/doc/define.n index ef2735e..775cdc4 100644 --- a/doc/define.n +++ b/doc/define.n @@ -48,6 +48,7 @@ and define a class in one step. .PP The following commands are supported in the \fIdefScript\fR for \fBoo::define\fR, each of which may also be used in the \fIsubcommand\fR form: +.\" METHOD: classmethod .TP \fBclassmethod\fI name\fR ?\fIargList bodyScrip\fR? .VS TIP478 @@ -69,6 +70,7 @@ In a private definition context, the methods as invoked on classes are private. .RE .VE TIP478 +.\" METHOD: constructor .TP \fBconstructor\fI argList bodyScript\fR . @@ -85,6 +87,7 @@ string, the constructor will be deleted. Classes do not need to have a constructor defined. If none is specified, the superclass's constructor will be used instead. .RE +.\" METHOD: destructor .TP \fBdestructor\fI bodyScript\fR . @@ -101,6 +104,7 @@ Note that errors during the evaluation of a destructor \fIare not returned\fR to the code that causes the destruction of an object. Instead, they are passed to the currently-defined \fBbgerror\fR handler. .RE +.\" METHOD: export .TP \fBexport\fI name \fR?\fIname ...\fR? . @@ -109,6 +113,7 @@ This arranges for each of the named methods, \fIname\fR, to be exported class being defined. Note that the methods themselves may be actually defined by a superclass; subclass exports override superclass visibility, and may in turn be overridden by instances. +.\" METHOD: forward .TP \fBforward\fI name cmdName \fR?\fIarg ...\fR? . @@ -128,6 +133,7 @@ If in a private definition context (see the \fBprivate\fR definition command, below), this command creates private forwarded methods. .VE TIP500 .RE +.\" METHOD: initialise .TP \fBinitialise\fI script\fR .TP @@ -137,6 +143,7 @@ This evaluates \fIscript\fR in a context which supports local variables and where the current namespace is the instance namespace of the class object itself. This is useful for setting up, e.g., class-scoped variables. .VE TIP478 +.\" METHOD: method .TP \fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR . @@ -161,6 +168,7 @@ below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command creates private procedure-like methods. .VE TIP500 .RE +.\" METHOD: private .TP \fBprivate \fIcmd arg...\fR .TP @@ -180,6 +188,7 @@ commands have no difference in behavior when used in a private definition context. .RE .VE TIP500 +.\" METHOD: self .TP \fBself\fI subcommand arg ...\fR .TP @@ -207,6 +216,7 @@ below), the definitions on the class object will also be made in a private definition context. .VE TIP500 .RE +.\" METHOD: superclass .TP \fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? . @@ -218,6 +228,7 @@ being non-classes or vice-versa, that an empty parent class is equivalent to \fBoo::object\fR, and that the parent classes of \fBoo::object\fR and \fBoo::class\fR may not be modified. By default, this slot works by replacement. +.\" METHOD: unexport .TP \fBunexport\fI name \fR?\fIname ...\fR? . @@ -227,6 +238,7 @@ but instead just through the \fBmy\fR command visible in each object's context) by the class being defined. Note that the methods themselves may be actually defined by a superclass; subclass unexports override superclass visibility, and may be overridden by instance unexports. +.\" METHOD: variable .TP \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR? . @@ -258,6 +270,7 @@ extremely unlikely. .PP The following definitions are also supported, but are not required in simple programs: +.\" METHOD: definitionnamespace .TP \fBdefinitionnamespace\fR ?\fIkind\fR? \fInamespaceName\fR .VS TIP524 @@ -284,6 +297,7 @@ locked to \fB::oo::define\fR. A consequence of this is that effective use of this feature for classes requires the definition of a metaclass. .RE .VE TIP524 +.\" METHOD: deletemethod .TP \fBdeletemethod\fI name\fR ?\fIname ...\fR? . @@ -292,6 +306,7 @@ must have previously existed in that class. Does not affect the superclasses of the class, nor does it affect the subclasses or instances of the class (except when they have a call chain through the class being modified) or the class object itself. +.\" METHOD: filter .TP \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? . @@ -302,6 +317,7 @@ results are. Each \fImethodName\fR names a single filtering method (which may be exposed or not exposed); it is not an error for a non-existent method to be named since they may be defined by subclasses. By default, this slot works by appending. +.\" METHOD: mixin .TP \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? . @@ -310,6 +326,7 @@ sets or updates the list of additional classes that are to be mixed into all the instances of the class being defined. Each \fIclassName\fR argument names a single class that is to be mixed in. By default, this slot works by replacement. +.\" METHOD: renamemethod .TP \fBrenamemethod\fI fromName toName\fR . @@ -326,6 +343,7 @@ be afterwards. The following commands are supported in the \fIdefScript\fR for \fBoo::objdefine\fR, each of which may also be used in the \fIsubcommand\fR form: +.\" METHOD: export .TP \fBexport\fI name \fR?\fIname ...\fR? . @@ -333,6 +351,7 @@ This arranges for each of the named methods, \fIname\fR, to be exported (i.e. usable outside the object through the object's command) by the object being defined. Note that the methods themselves may be actually defined by a class or superclass; object exports override class visibility. +.\" METHOD: forward .TP \fBforward\fI name cmdName \fR?\fIarg ...\fR? . @@ -349,6 +368,7 @@ If in a private definition context (see the \fBprivate\fR definition command, below), this command creates private forwarded methods. .VE TIP500 .RE +.\" METHOD: method .TP \fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR . @@ -372,6 +392,7 @@ below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command creates private procedure-like methods. .VE TIP500 .RE +.\" METHOD: mixin .TP \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? . @@ -380,6 +401,7 @@ sets or updates a per-object list of additional classes that are to be mixed into the object. Each argument, \fIclassName\fR, names a single class that is to be mixed in. By default, this slot works by replacement. +.\" METHOD: private .TP \fBprivate \fIcmd arg...\fR .TP @@ -397,6 +419,7 @@ just a private definition context. All other definition commands have no difference in behavior when used in a private definition context. .RE .VE TIP500 +.\" METHOD: unexport .TP \fBunexport\fI name \fR?\fIname ...\fR? . @@ -405,6 +428,7 @@ This arranges for each of the named methods, \fIname\fR, to be not exported just through the \fBmy\fR command visible in the object's context) by the object being defined. Note that the methods themselves may be actually defined by a class; instance unexports override class visibility. +.\" METHOD: variable .TP \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR? . @@ -434,12 +458,14 @@ superclass methods extremely unlikely. .PP The following definitions are also supported, but are not required in simple programs: +.\" METHOD: class .TP \fBclass\fI className\fR . This allows the class of an object to be changed after creation. Note that the class's constructors are not called when this is done, and so the object may well be in an inconsistent state unless additional configuration work is done. +.\" METHOD: deletemethod .TP \fBdeletemethod\fI name\fR ?\fIname ...\fR . @@ -448,6 +474,7 @@ must have previously existed in that object (e.g., because it was created through \fBoo::objdefine method\fR). Does not affect the classes that the object is an instance of, or remove the exposure of those class-provided methods in the instance of that class. +.\" METHOD: filter .TP \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? . @@ -459,6 +486,7 @@ not exposed); it is not an error for a non-existent method to be named. Note that the actual list of filters also depends on the filters set upon any classes that the object is an instance of. By default, this slot works by appending. +.\" METHOD: renamemethod .TP \fBrenamemethod\fI fromName toName\fR . @@ -469,6 +497,7 @@ that the object is an instance of and cannot rename in an instance object the methods provided by those classes (though a \fBoo::objdefine forward\fRed method may provide an equivalent capability). Does not change the export status of the method; if it was exported before, it will be afterwards. +.\" METHOD: self .TP \fBself \fR .VS TIP470 @@ -494,32 +523,38 @@ object, that is an instance of the class \fBoo::Slot\fR, which manages a list of values (class names, variable names, etc.) that comprises the contents of the slot. .PP -The \fBoo::Slot\fR class defines five operations (as methods) that may be done +The \fBoo::Slot\fR class defines six operations (as methods) that may be done on the slot: +.\" METHOD: -append .TP \fIslot\fR \fB\-append\fR ?\fImember ...\fR? . This appends the given \fImember\fR elements to the slot definition. +.\" METHOD: -appendifnew .TP \fIslot\fR \fB\-appendifnew\fR ?\fImember ...\fR? .VS TIP558 This appends the given \fImember\fR elements to the slot definition if they do not already exist. .VE TIP558 +.\" METHOD: -clear .TP \fIslot\fR \fB\-clear\fR . This sets the slot definition to the empty list. +.\" METHOD: -prepend .TP \fIslot\fR \fB\-prepend\fR ?\fImember ...\fR? .VS TIP516 This prepends the given \fImember\fR elements to the slot definition. .VE TIP516 +.\" METHOD: -remove .TP \fIslot\fR \fB\-remove\fR ?\fImember ...\fR? .VS TIP516 This removes the given \fImember\fR elements from the slot definition. .VE TIP516 +.\" METHOD: -set .TP \fIslot\fR \fB\-set\fR ?\fImember ...\fR? . @@ -533,12 +568,14 @@ You only need to make an instance of \fBoo::Slot\fR if you are definining your own slot that behaves like a standard slot. .PP .SS "SLOT IMPLEMENTATION" +.\" METHOD: --default-operation Internally, slot objects also define a method \fB\-\-default\-operation\fR which is forwarded to the default operation of the slot (thus, for the class .QW \fBvariable\fR slot, this is forwarded to .QW "\fBmy \-append\fR" ), and these methods which provide the implementation interface: +.\" METHOD: Get .TP \fIslot\fR \fBGet\fR . @@ -554,8 +591,9 @@ The elements of the list should be fully resolved, if that is a meaningful concept to the slot. .VE TIP516 .RE +.\" METHOD: Resolve .TP -\fIslot\fR \fBResolve\fR \fIslotElement\fR +\fIslot\fR \fBResolve\fI slotElement\fR .VS TIP516 Returns \fIslotElement\fR with a resolution operation applied to it, but does not modify the slot. For slots of simple strings, this is an operation that @@ -572,6 +610,7 @@ Implementations \fIshould not\fR enforce uniqueness and ordering constraints in this method; that is the responsibility of the \fBSet\fR method. .RE .VE TIP516 +.\" METHOD: Resolve .TP \fIslot\fR \fBResolve \fIelement\fR .VS @@ -581,6 +620,7 @@ references to commands or classes it should convert those into their fully-qualified forms (so they can be compared with \fBstring equals\fR): that could be done by forwarding to \fBnamespace which\fR or similar. .VE +.\" METHOD: Set .TP \fIslot\fR \fBSet \fIelementList\fR . @@ -621,7 +661,7 @@ for reading from slots is via \fBinfo class\fR and \fBinfo object\fR). .SH EXAMPLES This example demonstrates how to use both forms of the \fBoo::define\fR and \fBoo::objdefine\fR commands (they work in the same way), as well as -illustrating four of the subcommands of them. +illustrating four of their subcommands. .PP .CS oo::class create c @@ -285,6 +285,7 @@ it is recommended that this command only be used in a local scope (\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of this, the variables set by \fBdict update\fR will continue to exist after the command finishes (unless explicitly \fBunset\fR). +.PP Note that the mapping of values to variables does not use traces; changes to the \fIdictionaryVariable\fR's contents only happen when \fIbody\fR terminates. @@ -324,6 +325,7 @@ it is recommended that this command only be used in a local scope (\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of this, the variables set by \fBdict with\fR will continue to exist after the command finishes (unless explicitly \fBunset\fR). +.PP Note that the mapping of values to variables does not use traces; changes to the \fIdictionaryVariable\fR's contents only happen when \fIbody\fR terminates. @@ -22,6 +22,7 @@ script containing one or more commands. fashion as the \fBconcat\fR command, passes the concatenated string to the Tcl interpreter recursively, and returns the result of that evaluation (or any error generated by it). +.PP Note that the \fBlist\fR command quotes sequences of words in such a way that they are not further expanded by the \fBeval\fR command; for \fIany\fR values, $a, $b, and $c, these two lines are effectively @@ -31,16 +31,19 @@ If the initial arguments to \fBexec\fR start with \fB\-\fR then they are treated as command-line switches and are not part of the pipeline specification. The following switches are currently supported: +.\" OPTION: -ignorestderr .TP 13 \fB\-ignorestderr\fR . Stops the \fBexec\fR command from treating the output of messages to the pipeline's standard error channel as an error case. +.\" OPTION: -keepnewline .TP 13 \fB\-keepnewline\fR . Retains a trailing newline in the pipeline's output. Normally a trailing newline will be deleted. +.\" OPTION: -- .TP 13 \fB\-\|\-\fR . @@ -54,12 +54,10 @@ ignored. Each operand is interpreted as a numeric value if at all possible. .PP Each operand has one of the following forms: .RS -.PP .TP A \fBnumeric value\fR .PP .RS -. Either integer or floating-point. The first two characters of an integer may also be \fB0d\fR for decimal, \fB0b\fR for binary, \fB0o\fR for octal or \fB0x\fR for hexadicimal. For compatibility with older Tcl releases, an @@ -90,7 +88,6 @@ end of a numeric value. Here are some examples: \fBexpr\fR 3_141_592_653_589e-1_2 \fI3.141592653589\fR .CE .RE - .TP A \fBboolean value\fR . @@ -108,6 +105,7 @@ Backslash, variable, and command substitution are performed according to the rules for \fBTcl\fR. .TP A string enclosed in \fBbraces\fR. +. The operand is treated as a braced value according to the rule for braces in \fBTcl\fR. .TP @@ -116,8 +114,10 @@ A Tcl command enclosed in \fBbrackets\fR Command substitution is performed as according to the command substitution rule for \fBTcl\fR. .TP -A mathematical function such as \fBsin($x)\fR, whose arguments have any of the above -forms for operands. See \fBMATH FUNCTIONS\fR below for +A function call. +. +This is mathematical function such as \fBsin($x)\fR, whose arguments have any of +the above forms for operands. See \fBMATH FUNCTIONS\fR below for a discussion of how mathematical functions are handled. .RE .PP @@ -143,8 +143,8 @@ produces the value on the right side. For operators having both a numeric mode and a string mode, the numeric mode is chosen when all operands have a numeric interpretation. The integer interpretation of an operand is preferred over the floating-point -interpretation. To ensure string operations on arbitrary values it is generally a -good idea to use \fBeq\fR, \fBne\fR, or the \fBstring\fR command instead of +interpretation. To ensure string operations on arbitrary values it is generally +a good idea to use \fBeq\fR, \fBne\fR, or the \fBstring\fR command instead of more versatile operators such as \fB==\fR. .PP Unless otherwise specified, operators accept non-numeric operands. The value @@ -204,7 +204,7 @@ comparison operators below, which have the same precedence. Boolean string comparisons: less than, greater than, less than or equal, and greater than or equal. These always compare values using their UNICODE strings (also see \fBstring compare\fR), unlike with the numeric-preferring -comparisons abov, which have the same precedence. +comparisons above, which have the same precedence. .VE "8.7, TIP461" .TP 20 \fB==\0\0!=\fR @@ -292,8 +292,8 @@ For more details on the results produced by each operator, see the documentation for C. .SS "MATH FUNCTIONS" .PP -A mathematical function such as \fBsin($x)\fR is replaced with a call to an ordinary -Tcl command in the \fBtcl::mathfunc\fR namespace. The evaluation +A mathematical function such as \fBsin($x)\fR is replaced with a call to an +ordinary Tcl command in the \fBtcl::mathfunc\fR namespace. The evaluation of an expression such as .PP .CS @@ -313,12 +313,13 @@ tcl::mathfunc::sin [\fBexpr\fR {$x+$y}] .CE .PP \fBtcl::mathfunc::sin\fR is resolved as described in -\fBNAMESPACE RESOLUTION\fR in the \fBnamespace\fR(n) documentation. Given the +\fBNAMESPACE RESOLUTION\fR in the \fBnamespace\fR(n) documentation. Given the default value of \fBnamespace path\fR, \fB[namespace current]::tcl::mathfunc::sin\fR or \fB::tcl::mathfunc::sin\fR are the typical resolutions. .PP -As in C, a mathematical function may accept multiple arguments separated by commas. Thus, +As in C, a mathematical function may accept multiple arguments separated by +commas. Thus, .PP .CS \fBexpr\fR {hypot($x,$y)} @@ -381,13 +382,12 @@ the expression, resulting in better speed and smaller storage requirements. This also avoids issues that can arise if Tcl is allowed to perform substitution on the value before \fBexpr\fR is called. .PP -In the following example, the value of the expression is 11 because the Tcl parser first -substitutes \fB$b\fR and \fBexpr\fR then substitutes \fB$a\fR as part -of evaluating the expression +In the following example, the value of the expression is 11 because the Tcl +parser first substitutes \fB$b\fR and \fBexpr\fR then substitutes \fB$a\fR as +part of evaluating the expression .QW "$a + 2*4" . -Enclosing the -expression in braces would result in a syntax error as \fB$b\fR does -not evaluate to a numeric value. +Enclosing the expression in braces would result in a syntax error as \fB$b\fR +does not evaluate to a numeric value. .PP .CS set a 3 diff --git a/doc/fcopy.n b/doc/fcopy.n index dc6d8ea..e044fb7 100644 --- a/doc/fcopy.n +++ b/doc/fcopy.n @@ -12,30 +12,28 @@ .SH NAME fcopy \- Copy data from one channel to another .SH SYNOPSIS -\fBfcopy \fIinputChan\fR \fIoutputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? +\fBfcopy \fIinputChan outputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? .BE - .SH DESCRIPTION .PP -The \fBfcopy\fR command copies data from one I/O channel, \fIinchan\fR to another I/O channel, \fIoutchan\fR. +The \fBfcopy\fR command copies data from one I/O channel, \fIinchan\fR, to +another I/O channel, \fIoutchan\fR. The \fBfcopy\fR command leverages the buffering in the Tcl I/O system to avoid extra copies and to avoid buffering too much data in main memory when copying large files to destinations like network sockets. -. .SS "DATA QUANTITY" All data until \fIEOF\fR is copied. -In addition, the quantity of copied data may be specified by the option \fB-size\fR. -The given size is in bytes, if the input channel is in binary mode. -Otherwise, it is in characters. +In addition, the quantity of copied data may be specified by the option +\fB\-size\fR. The given size is in bytes, if the input channel is in binary +mode. Otherwise, it is in characters. .PP -The transfer is treated as a binary transfer, if the encoding -profile is set to +Depreciated feature: the transfer is treated as a binary transfer, if the +encoding profile is set to .QW tcl8 and the input encoding matches the output encoding. In this case, eventual encoding errors are not handled. An eventually given size is in bytes in this case. -This feature is depreciated in TCL 9. . .SS "BLOCKING OPERATION MODE" Without the \fB\-command\fR option, \fBfcopy\fR blocks until the copy is complete @@ -71,7 +69,8 @@ then all data already queued for \fIoutchan\fR is written out. Note that \fIinchan\fR can become readable during a background copy. You should turn off any \fBfileevent\fR handlers during a background copy so those handlers do not interfere with the copy. -Any wrong-sided I/O attempted (by a \fBfileevent\fR handler or otherwise) will get a +Any wrong-sided I/O attempted (by a \fBfileevent\fR handler or otherwise) will +get a .QW "channel busy" error. . @@ -111,15 +110,16 @@ channel is configured to the .QW strict encoding profile. .PP -If an encoding error arises on the input channel, any data before the error byte is -written to the output channel. The input file pointer is located just before the -values causing the encoding error. +If an encoding error arises on the input channel, any data before the error +byte is written to the output channel. The input file pointer is located just +before the values causing the encoding error. Error inspection or recovery is possible by changing the encoding parameters and invoking a file command (\fBread\fR, \fBfcopy\fR). .PP -If an encoding error arises on the output channel, the errorneous data is lost. -To make the difference between the input error case and the output error case, only the -error message may be inspected (read or write), as both throw the error code \fIEILSEQ\fR. +If an encoding error arises on the output channel, the erroneous data is lost. +To make the difference between the input error case and the output error case, +only the error message may be inspected (read or write), as both throw the +error code \fIEILSEQ\fR. .SH EXAMPLES .PP The first example transfers the contents of one channel exactly to @@ -62,7 +62,7 @@ write permission for the file's group and other users. An \fBls\fR-style string of the form \fBrwxrwxrwx\fR is also accepted but must always be 9 characters long. E.g., \fBrwxr-xr-t\fR is equivalent to \fB01755\fR. On versions of Unix supporting file flags, -\fB-readonly\fR returns the value of, or sets, or clears the readonly +\fB\-readonly\fR returns the value of, or sets, or clears the readonly attribute of a file, i.e., the user immutable flag (\fBuchg\fR) to the \fBchflags\fR command. .PP @@ -88,14 +88,40 @@ off the file. .PP On all platforms, files in \fBzipfs\fR mounted archives return the following attributes. These are all read-only and cannot be directly set. -\fB-archive\fR gives the path of the mounted ZIP archive containing the file. -\fB-compsize\fR gives the compressed size of the file within the archive. -This is \fB0\fR for directories. -\fB-crc\fR gives the CRC of the file if present, else \fB0\fR. -\fB-mount\fR gives the path where the containing archive is mounted. -\fB-offset\fR gives the offset of the file within the archive. -\fB-uncompsize\fR gives the uncompressed size of the file. +.RS +.\" OPTION: -archive +.TP +\fB\-archive\fR +. +The path of the mounted ZIP archive containing the file. +.\" OPTION: -compsize +.TP +\fB\-compsize\fR +. +The compressed size of the file within the archive. This is \fB0\fR for directories. +.\" OPTION: -crc +.TP +\fB\-crc\fR +. +The CRC of the file if present, else \fB0\fR. +.\" OPTION: -mount +.TP +\fB\-mount\fR +. +The path where the containing archive is mounted. +.\" OPTION: -offset +.TP +\fB\-offset\fR +. +The offset of the file within the archive. +.\" OPTION: -uncompsize +.TP +\fB\-uncompsize\fR +. +The uncompressed size of the file. This is \fB0\fR for directories. +.RE +.PP Other attributes may be present in the returned list. These should be ignored. .RE @@ -504,7 +530,7 @@ between platforms: .VE "8.7, TIP 431" .TP \fBfile tempfile\fR ?\fInameVar\fR? ?\fItemplate\fR? -'\" TIP #210 +.\" TIP #210 Creates a temporary file and returns a read-write channel opened on that file. If the \fInameVar\fR is given, it specifies a variable that the name of the temporary file will be written into; if absent, Tcl will attempt to arrange @@ -561,12 +587,12 @@ Returns \fB1\fR if file \fIname\fR is writable by the current user, \fB0\fR otherwise. .SH "PORTABILITY ISSUES" .TP -\fBUnix\fR\0\0\0\0\0\0\0 +\fBUnix\fR . These commands always operate using the real user and group identifiers, not the effective ones. .TP -\fBWindows\fR\0\0\0\0 +\fBWindows\fR . The \fBfile owned\fR subcommand uses the user identifier (SID) of the process token, not the thread token which may be impersonating @@ -588,7 +614,7 @@ proc findMatchingCFiles {dir} { set ext .o } } - foreach file [glob \-nocomplain \-directory $dir *.c] { + foreach file [glob -nocomplain -directory $dir *.c] { set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext if {[\fBfile exists\fR $objectFile]} { lappend files $file @@ -609,7 +635,7 @@ if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} { \fBfile mkdir\fR [\fBfile dirname\fR $newName] } \fBfile rename\fR $oldName $newName -\fBfile link\fR \-symbolic $oldName $newName +\fBfile link\fR -symbolic $oldName $newName .CE .PP On Windows, a file can be diff --git a/doc/filename.n b/doc/filename.n index d8a3364..0520677 100644 --- a/doc/filename.n +++ b/doc/filename.n @@ -41,6 +41,7 @@ The rules for native names depend on the value reported in the Tcl \fBplatform\fR element of the \fBtcl_platform\fR array: .TP 10 \fBUnix\fR +. On Unix and Apple MacOS X platforms, Tcl uses path names where the components are separated by slashes. Path names may be relative or absolute, and file names may contain any character other than slash. @@ -58,28 +59,35 @@ The following examples illustrate various forms of path names: .TP 15 \fB/\fR +. Absolute path to the root directory. .TP 15 \fB/etc/passwd\fR +. Absolute path to the file named \fBpasswd\fR in the directory \fBetc\fR in the root directory. .TP 15 \fB\&.\fR +. Relative path to the current directory. .TP 15 \fBfoo\fR +. Relative path to the file \fBfoo\fR in the current directory. .TP 15 \fBfoo/bar\fR +. Relative path to the file \fBbar\fR in the directory \fBfoo\fR in the current directory. .TP 15 \fB\&../foo\fR +. Relative path to the file \fBfoo\fR in the directory above the current directory. .RE .TP \fBWindows\fR +. On Microsoft Windows platforms, Tcl supports both drive-relative and UNC style names. Both \fB/\fR and \fB\e\fR may be used as directory separators in either type of name. Drive-relative names consist of an optional drive @@ -93,28 +101,34 @@ following examples illustrate various forms of path names: .RS .TP 15 \fB\&\e\eHost\eshare/file\fR +. Absolute UNC path to a file called \fBfile\fR in the root directory of the export point \fBshare\fR on the host \fBHost\fR. Note that repeated use of \fBfile dirname\fR on this path will give \fB//Host/share\fR, and will never give just \fB//Host\fR. .TP 15 \fBc:foo\fR +. Volume-relative path to a file \fBfoo\fR in the current directory on drive \fBc\fR. .TP 15 \fBc:/foo\fR +. Absolute path to a file \fBfoo\fR in the root directory of drive \fBc\fR. .TP 15 \fBfoo\ebar\fR +. Relative path to a file \fBbar\fR in the \fBfoo\fR directory in the current directory on the current volume. .TP 15 \fB\&\efoo\fR +. Volume-relative path to a file \fBfoo\fR in the root directory of the current volume. .TP 15 \fB\&\e\efoo\fR +. Volume-relative path to a file \fBfoo\fR in the root directory of the current volume. This is not a valid UNC path, so the assumption is that the extra backslashes are superfluous. @@ -38,7 +38,7 @@ The operation of \fBbreak\fR and \fBcontinue\fR are similar to the corresponding statements in C. \fBFor\fR returns an empty string. .PP -Note: \fItest\fR should almost always be enclosed in braces. If not, +Note that \fItest\fR should almost always be enclosed in braces. If not, variable substitutions will be made before the \fBfor\fR command starts executing, which means that variable changes made by the loop body will not be considered in the expression. diff --git a/doc/format.n b/doc/format.n index b0a0107..78fd352 100644 --- a/doc/format.n +++ b/doc/format.n @@ -64,25 +64,20 @@ then all of the specifiers must be positional. .PP The second portion of a conversion specifier may contain any of the following flag characters, in any order: -.TP 10 -\fB\-\fR +.IP \fB\-\fR 10 Specifies that the converted argument should be left-justified in its field (numbers are normally right-justified with leading spaces if needed). -.TP 10 -\fB+\fR +.IP \fB+\fR 10 Specifies that a number should always be printed with a sign, even if positive. -.TP 10 -\fIspace\fR +.IP \fIspace\fR 10 Specifies that a space should be added to the beginning of the number if the first character is not a sign. -.TP 10 -\fB0\fR +.IP \fB0\fR 10 Specifies that the number should be padded on the left with zeroes instead of spaces. -.TP 10 -\fB#\fR +.IP \fB#\fR 10 Requests an alternate output form. For \fBo\fR conversions, \fB0o\fR will be added to the beginning of the result unless it is zero. For \fBx\fR or \fBX\fR conversions, \fB0x\fR @@ -126,8 +121,8 @@ be omitted unless the \fB#\fR flag has been specified). For integer conversions, it specifies a minimum number of digits to print (leading zeroes will be added if necessary). For \fBs\fR conversions it specifies the maximum number of characters to be -printed; if the string is longer than this then the trailing characters will be dropped. -If the precision is specified with \fB*\fR rather than a number +printed; if the string is longer than this then the trailing characters will +be dropped. If the precision is specified with \fB*\fR rather than a number then the next argument to the \fBformat\fR command determines the precision; it must be a numeric string. .SS "OPTIONAL SIZE MODIFIER" @@ -154,67 +149,53 @@ truncated to the range determined by the value of the The last thing in a conversion specifier is an alphabetic character that determines what kind of conversion to perform. The following conversion characters are currently supported: -.TP 10 -\fBd\fR +.IP \fBd\fR 10 Convert integer to signed decimal string. -.TP 10 -\fBu\fR +.IP \fBu\fR 10 Convert integer to unsigned decimal string. -.TP 10 -\fBi\fR +.IP \fBi\fR 10 Convert integer to signed decimal string (equivalent to \fBd\fR). -.TP 10 -\fBo\fR +.IP \fBo\fR 10 Convert integer to unsigned octal string. -.TP 10 -\fBx\fR or \fBX\fR +.IP "\fBx\fR or \fBX\fR" 10 Convert integer to unsigned hexadecimal string, using digits .QW 0123456789abcdef for \fBx\fR and .QW 0123456789ABCDEF for \fBX\fR). -.TP 10 -\fBb\fR +.IP \fBb\fR 10 Convert integer to unsigned binary string, using digits 0 and 1. -.TP 10 -\fBc\fR +.IP \fBc\fR 10 Convert integer to the Unicode character it represents. -.TP 10 -\fBs\fR +.IP \fBs\fR 10 No conversion; just insert string. -.TP 10 -\fBf\fR +.IP \fBf\fR 10 Convert number to signed decimal string of the form \fIxx.yyy\fR, where the number of \fIy\fR's is determined by the precision (default: 6). If the precision is 0 then no decimal point is output. -.TP 10 -\fBe\fR or \fBE\fR +.IP "\fBe\fR or \fBE\fR" 10 Convert number to scientific notation in the form \fIx.yyy\fBe\(+-\fIzz\fR, where the number of \fIy\fR's is determined by the precision (default: 6). If the precision is 0 then no decimal point is output. If the \fBE\fR form is used then \fBE\fR is printed instead of \fBe\fR. -.TP 10 -\fBg\fR or \fBG\fR +.IP "\fBg\fR or \fBG\fR" 10 If the exponent is less than \-4 or greater than or equal to the precision, then convert number as for \fB%e\fR or \fB%E\fR. Otherwise convert as for \fB%f\fR. Trailing zeroes and a trailing decimal point are omitted. -.TP 10 -\fBa\fR or \fBA\fR +.IP "\fBa\fR or \fBA\fR" 10 Convert double to hexadecimal notation in the form \fI0x1.yyy\fBp\(+-\fIzz\fR, where the number of \fIy\fR's is determined by the precision (default: 13). If the \fBA\fR form is used then the hex characters are printed in uppercase. -.TP 10 -\fB%\fR +.IP \fB%\fR 10 No conversion: just insert \fB%\fR. -.TP 10 -\fBp\fR +.IP \fBp\fR 10 Shorthand form for \fB0x%zx\fR, so it outputs the integer in hexadecimal form with \fB0x\fR prefix. .SH "DIFFERENCES FROM ANSI SPRINTF" diff --git a/doc/fpclassify.n b/doc/fpclassify.n index 22d365e..c1db73b 100644 --- a/doc/fpclassify.n +++ b/doc/fpclassify.n @@ -19,26 +19,16 @@ package require \fBtcl 8.7\fR .SH DESCRIPTION The \fBfpclassify\fR command takes a floating point number, \fIvalue\fR, and returns one of the following strings that describe it: -.TP -\fBzero\fR -. +.IP \fBzero\fR \fIvalue\fR is a floating point zero. -.TP -\fBsubnormal\fR -. +.IP \fBsubnormal\fR \fIvalue\fR is the result of a gradual underflow. -.TP -\fBnormal\fR -. +.IP \fBnormal\fR \fIvalue\fR is an ordinary floating-point number (not zero, subnormal, infinite, nor NaN). -.TP -\fBinfinite\fR -. +.IP \fBinfinite\fR \fIvalue\fR is a floating-point infinity. -.TP -\fBnan\fR -. +.IP \fBnan\fR \fIvalue\fR is Not-a-Number. .PP The \fBfpclassify\fR command throws an error if value is not a floating-point @@ -28,6 +28,7 @@ in the list, so if a sorted list is required the caller should use If the initial arguments to \fBglob\fR start with \fB\-\fR then they are treated as switches. The following switches are currently supported: +.\" OPTION: -directory .TP \fB\-directory\fR \fIdirectory\fR . @@ -37,17 +38,20 @@ contains glob-sensitive characters without the need to quote such characters explicitly. This option may not be used in conjunction with \fB\-path\fR, which is used to allow searching for complete file paths whose names may contain glob-sensitive characters. +.\" OPTION: -join .TP \fB\-join\fR . The remaining pattern arguments, after option processing, are treated as a single pattern obtained by joining the arguments with directory separators. +.\" OPTION: -nocomplain .TP \fB\-nocomplain\fR . Allows an empty list to be returned without error; without this switch an error is returned if the result list would be empty. +.\" OPTION: -path .TP \fB\-path\fR \fIpathPrefix\fR . @@ -61,6 +65,7 @@ as $path, but differing extensions, you should use .QW "\fBglob \-path [file rootname $path] .*\fR" which will work even if \fB$path\fR contains numerous glob-sensitive characters. +.\" OPTION: -tails .TP \fB\-tails\fR . @@ -74,6 +79,7 @@ For \fB\-path\fR specifications, the returned names will include the last path segment, so .QW "\fBglob \-tails \-path [file rootname ~/foo.tex] .*\fR" will return paths like \fBfoo.aux foo.bib foo.tex\fR etc. +.\" OPTION: -types .TP \fB\-types\fR \fItypeList\fR . @@ -116,6 +122,7 @@ except that the first case doesn't return the trailing .QW / and is more platform independent. .RE +.\" OPTION: -- .TP \fB\-\|\-\fR . @@ -126,27 +133,17 @@ be treated as a \fIpattern\fR even if it starts with a \fB\-\fR. The \fIpattern\fR arguments may contain any of the following special characters, which are a superset of those supported by \fBstring match\fR: -.TP 10 -\fB?\fR -. +.IP \fB?\fR 10 Matches any single character. -.TP 10 -\fB*\fR -. +.IP \fB*\fR 10 Matches any sequence of zero or more characters. -.TP 10 -\fB[\fIchars\fB]\fR -. +.IP \fB[\fIchars\fB]\fR 10 Matches any single character in \fIchars\fR. If \fIchars\fR contains a sequence of the form \fIa\fB\-\fIb\fR then any character between \fIa\fR and \fIb\fR (inclusive) will match. -.TP 10 -\fB\e\fIx\fR -. +.IP \fB\e\fIx\fR 10 Matches the character \fIx\fR. -.TP 10 -\fB{\fIa\fB,\fIb\fB,\fI...\fR} -. +.IP \fB{\fIa\fB,\fIb\fB,\fI...\fB}\fR 10 Matches any of the sub-patterns \fIa\fR, \fIb\fR, etc. .PP On Unix, as with csh, a diff --git a/doc/history.n b/doc/history.n index 05d936e..5bdd7c2 100644 --- a/doc/history.n +++ b/doc/history.n @@ -37,8 +37,8 @@ matches the event in the sense of the \fBstring match\fR command. The \fBhistory\fR command can take any of the following forms: .TP \fBhistory\fR -Same -as \fBhistory info\fR, described below. +. +Same as \fBhistory info\fR, described below. .TP \fBhistory add\fI command \fR?\fBexec\fR? Adds the \fIcommand\fR argument to the history list as a new event. If @@ -13,6 +13,7 @@ .SH NAME http \- Client-side implementation of the HTTP/1.1 protocol .SH SYNOPSIS +.nf \fBpackage require http\fR ?\fB2.10\fR? .\" See Also -useragent option documentation in body! .sp @@ -20,11 +21,11 @@ http \- Client-side implementation of the HTTP/1.1 protocol .sp \fB::http::geturl \fIurl\fR ?\fI\-option value\fR ...? .sp -\fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...? +\fB::http::formatQuery\fI key value\fR ?\fIkey value\fR ...? .sp -\fB::http::quoteString\fR \fIvalue\fR +\fB::http::quoteString\fI value\fR .sp -\fB::http::reset\fR \fItoken\fR ?\fIwhy\fR? +\fB::http::reset\fI token\fR ?\fIwhy\fR? .sp \fB::http::wait \fItoken\fR .sp @@ -38,25 +39,25 @@ http \- Client-side implementation of the HTTP/1.1 protocol .sp \fB::http::cleanup \fItoken\fR .sp -\fB::http::requestLine\fR \fItoken\fR +\fB::http::requestLine\fI token\fR .sp -\fB::http::requestHeaders\fR \fItoken\fR ?\fIheaderName\fR? +\fB::http::requestHeaders\fI token\fR ?\fIheaderName\fR? .sp -\fB::http::requestHeaderValue\fR \fItoken\fR \fIheaderName\fR +\fB::http::requestHeaderValue\fI token headerName\fR .sp -\fB::http::responseLine\fR \fItoken\fR +\fB::http::responseLine\fI token\fR .sp -\fB::http::responseCode\fR \fItoken\fR +\fB::http::responseCode\fI token\fR .sp -\fB::http::reasonPhrase\fR \fIcode\fR +\fB::http::reasonPhrase\fI code\fR .sp -\fB::http::responseHeaders\fR \fItoken\fR ?\fIheaderName\fR? +\fB::http::responseHeaders\fI token\fR ?\fIheaderName\fR? .sp -\fB::http::responseHeaderValue\fR \fItoken\fR \fIheaderName\fR +\fB::http::responseHeaderValue\fI token headerName\fR .sp -\fB::http::responseInfo\fR \fItoken\fR +\fB::http::responseInfo\fI token\fR .sp -\fB::http::responseBody\fR \fItoken\fR +\fB::http::responseBody\fI token\fR .sp \fB::http::register \fIproto port command\fR ?\fIsocketCmdVarName\fR? ?\fIuseSockThread\fR? ?\fIendToEndProxy\fR? .sp @@ -70,9 +71,10 @@ http \- Client-side implementation of the HTTP/1.1 protocol .sp \fB::http::meta \fItoken\fR ?\fIheaderName\fR? .sp -\fB::http::metaValue\fR \fItoken\fR \fIheaderName\fR +\fB::http::metaValue\fI token headerName\fR .sp \fB::http::ncode \fItoken\fR +.fi .SH "EXPORTED COMMANDS" .PP Namespace \fBhttp\fR exports the commands \fBconfig\fR, \fBformatQuery\fR, @@ -130,6 +132,7 @@ The response itself is returned by command \fB::http::responseBody\fR, unless it has been redirected to a file by the \fI\-channel\fR option of \fB::http::geturl\fR. .SH COMMANDS +.\" COMMAND: config .TP \fB::http::config\fR ?\fIoptions\fR? . @@ -141,16 +144,18 @@ of the flags described below. In this case the current value of that setting is returned. Otherwise, the options should be a set of flags and values that define the configuration: .RS +.\" OPTION: -accept .TP -\fB\-accept\fR \fImimetypes\fR +\fB\-accept\fI mimetypes\fR . The Accept header of the request. The default is */*, which means that all types of documents are accepted. Otherwise you can supply a comma-separated list of mime type patterns that you are willing to receive. For example, .QW "image/gif, image/jpeg, text/*" . +.\" OPTION: -cookiejar .TP -\fB\-cookiejar\fR \fIcommand\fR +\fB\-cookiejar\fI command\fR .VS TIP406 The cookie store for the package to use to manage HTTP cookies. \fIcommand\fR is a command prefix list; if the empty list (the @@ -158,21 +163,24 @@ default value) is used, no cookies will be sent by requests or stored from responses. The command indicated by \fIcommand\fR, if supplied, must obey the \fBCOOKIE JAR PROTOCOL\fR described below. .VE TIP406 +.\" OPTION: -pipeline .TP -\fB\-pipeline\fR \fIboolean\fR +\fB\-pipeline\fI boolean\fR . Specifies whether HTTP/1.1 transactions on a persistent socket will be pipelined. See the \fBPERSISTENT SOCKETS\fR section for details. The default is 1. +.\" OPTION: -postfresh .TP -\fB\-postfresh\fR \fIboolean\fR +\fB\-postfresh\fI boolean\fR . Specifies whether requests that use the \fBPOST\fR method will always use a fresh socket, overriding the \fB\-keepalive\fR option of command \fBhttp::geturl\fR. See the \fBPERSISTENT SOCKETS\fR section for details. The default is 0. +.\" OPTION: -proxyauth .TP -\fB\-proxyauth\fR \fIstring\fR +\fB\-proxyauth\fI string\fR . If non-empty, the string is supplied to the proxy server as the value of the request header Proxy-Authorization. This option can be used for HTTP Basic @@ -181,8 +189,9 @@ technique, e.g. Digest Authentication, the \fB\-proxyauth\fR option is not useful. In that case the caller must expect a 407 response from the proxy, compute the authentication value to be supplied, and use the \fB\-headers\fR option to supply it as the value of the Proxy-Authorization header. +.\" OPTION: -proxyfilter .TP -\fB\-proxyfilter\fR \fIcommand\fR +\fB\-proxyfilter\fI command\fR . The command is a callback that is made during \fB::http::geturl\fR @@ -208,14 +217,16 @@ a \fBcatch\fR command. Therefore an error in the callback command does not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for details. .RE +.\" OPTION: -proxyhost .TP -\fB\-proxyhost\fR \fIhostname\fR +\fB\-proxyhost\fI hostname\fR . The host name or IP address of the proxy server, if any. If this value is the empty string, the URL host is contacted directly. See \fB\-proxyfilter\fR for how the value is used. +.\" OPTION: -proxynot .TP -\fB\-proxynot\fR \fIlist\fR +\fB\-proxynot\fI list\fR . A Tcl list of domain names and IP addresses that should be accessed directly, not through the proxy server. The target hostname is compared with each list @@ -223,13 +234,15 @@ element using a case-insensitive \fBstring match\fR. It is often convenient to use the wildcard "*" at the start of a domain name (e.g. *.example.com) or at the end of an IP address (e.g. 192.168.0.*). See \fB\-proxyfilter\fR for how the value is used. +.\" OPTION: -proxyport .TP -\fB\-proxyport\fR \fInumber\fR +\fB\-proxyport\fI number\fR . The port number of the proxy server. See \fB\-proxyfilter\fR for how the value is used. +.\" OPTION: -repost .TP -\fB\-repost\fR \fIboolean\fR +\fB\-repost\fI boolean\fR . Specifies what to do if a POST request over a persistent connection fails because the server has half-closed the connection. If boolean \fBtrue\fR, the @@ -240,32 +253,36 @@ that uses \fBhttp::geturl\fR is expected to seek user confirmation before retrying the POST. The value \fBtrue\fR should be used only under certain conditions. See the \fBPERSISTENT SOCKETS\fR section for details. The default is 0. +.\" OPTION: -threadlevel .TP -\fB\-threadlevel\fR \fIlevel\fR +\fB\-threadlevel\fI level\fR . Specifies whether and how to use the \fBThread\fR package. Possible values of \fIlevel\fR are 0, 1 or 2. .RS +.IP \fB0\fR +(the default) do not use Thread +.IP \fB1\fR +use Thread if it is available, do not use it if it is unavailable +.IP \fB2\fR +use Thread if it is available, raise an error if it is unavailable .PP -.DS -0 - (the default) do not use Thread -1 - use Thread if it is available, do not use it if it is unavailable -2 - use Thread if it is available, raise an error if it is unavailable -.DE The Tcl \fBsocket -async\fR command can block in adverse cases (e.g. a slow DNS lookup). Using the Thread package works around this problem, for both HTTP and HTTPS transactions. Values of \fIlevel\fR other than 0 are available only to the main interpreter in each thread. See section \fBTHREADS\fR for more information. .RE +.\" OPTION: -urlencoding .TP -\fB\-urlencoding\fR \fIencoding\fR +\fB\-urlencoding\fI encoding\fR . The \fIencoding\fR used for creating the x-url-encoded URLs with \fB::http::formatQuery\fR and \fB::http::quoteString\fR. The default is \fButf-8\fR, as specified by RFC 2718. +.\" OPTION: -useragent .TP -\fB\-useragent\fR \fIstring\fR +\fB\-useragent\fI string\fR . The value of the User-Agent header in the HTTP request. In an unsafe interpreter, the default value depends upon the operating system, and @@ -274,8 +291,9 @@ the version numbers of \fBhttp\fR and \fBTcl\fR, and is (for example) A safe interpreter cannot determine its operating system, and so the default in a safe interpreter is to use a Windows 10 value with the current version numbers of \fBhttp\fR and \fBTcl\fR. +.\" OPTION: -zip .TP -\fB\-zip\fR \fIboolean\fR +\fB\-zip\fI boolean\fR . If the value is boolean \fBtrue\fR, then by default requests will send a header .QW "\fBAccept-Encoding: gzip,deflate\fR" . @@ -285,8 +303,9 @@ In either case the default can be overridden for an individual request by supplying a custom \fBAccept-Encoding\fR header in the \fB\-headers\fR option of \fBhttp::geturl\fR. The default value is 1. .RE +.\" COMMAND: geturl .TP -\fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR? +\fB::http::geturl\fI url\fR ?\fIoptions\fR? . The \fB::http::geturl\fR command is the main procedure in the package. The \fB\-query\fR or \fB\-querychannel\fR option causes a POST operation and @@ -300,26 +319,30 @@ completes, unless the \fB\-command\fR option specifies a callback that is invoked when the HTTP transaction completes. \fB::http::geturl\fR takes several options: .RS +.\" OPTION: -binary .TP -\fB\-binary\fR \fIboolean\fR +\fB\-binary\fI boolean\fR . Specifies whether to force interpreting the URL data as binary. Normally this is auto-detected (anything not beginning with a \fBtext\fR content type or whose content encoding is \fBgzip\fR or \fBdeflate\fR is considered binary data). +.\" OPTION: -blocksize .TP -\fB\-blocksize\fR \fIsize\fR +\fB\-blocksize\fI size\fR . The block size used when reading the URL. At most \fIsize\fR bytes are read at once. After each block, a call to the \fB\-progress\fR callback is made (if that option is specified). +.\" OPTION: -channel .TP -\fB\-channel\fR \fIname\fR +\fB\-channel\fI name\fR . Copy the URL contents to channel \fIname\fR instead of saving it in a Tcl variable for retrieval by \fB::http::responseBody\fR. +.\" OPTION: -command .TP -\fB\-command\fR \fIcallback\fR +\fB\-command\fI callback\fR . The presence of this option causes \fB::http::geturl\fR to return immediately. After the HTTP transaction completes, the value of \fIcallback\fR is expanded, @@ -344,8 +367,9 @@ a \fBcatch\fR command. Therefore an error in the callback command does not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for details. .RE +.\" OPTION: -guesstype .TP -\fB\-guesstype\fR \fIboolean\fR +\fB\-guesstype\fI boolean\fR . Attempt to guess the \fBContent-Type\fR and character set when a misconfigured server provides no information. The default value is \fIfalse\fR (do @@ -357,9 +381,10 @@ detecting XML documents that begin with an XML declaration. In this case the \fBContent-Type\fR is changed to "application/xml", the binary flag state(binary) is changed to 0, and the character set is changed to the one specified by the "encoding" tag of the XML line, or to utf-8 if no -encoding is specified. Not used if a \fI\-channel\fR is specified. +encoding is specified. Not used if a \fB\-channel\fR is specified. +.\" OPTION: -handler .TP -\fB\-handler\fR \fIcallback\fR +\fB\-handler\fI callback\fR . If this option is absent, \fBhttp::geturl\fR processes incoming data itself, either appending it to the state(body) variable or writing it to the -channel. @@ -405,8 +430,9 @@ a \fBcatch\fR command. Therefore an error in the callback command does not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for details. .RE +.\" OPTION: -headers .TP -\fB\-headers\fR \fIkeyvaluelist\fR +\fB\-headers\fI keyvaluelist\fR . This option is used to add headers not already specified by \fB::http::config\fR to the HTTP request. The @@ -422,13 +448,15 @@ HTTP request: Pragma: no-cache .CE .RE +.\" OPTION: -keepalive .TP -\fB\-keepalive\fR \fIboolean\fR +\fB\-keepalive\fI boolean\fR . If boolean \fBtrue\fR, attempt to keep the connection open for servicing multiple requests. Default is 0. +.\" OPTION: -method .TP -\fB\-method\fR \fItype\fR +\fB\-method\fI type\fR . Force the HTTP request method to \fItype\fR. \fB::http::geturl\fR will auto-select GET, POST or HEAD based on other options, but this option overrides @@ -437,20 +465,22 @@ that selection and enables choices like PUT and DELETE for WebDAV support. .PP It is the caller's responsibility to ensure that the headers and request body (if any) conform to the requirements of the request method. For example, if -using \fB\-method\fR \fIPOST\fR to send a POST with an empty request body, the +using \fB\-method\fI POST\fR to send a POST with an empty request body, the caller must also supply the option .PP .CS \-headers {Content-Length 0} .CE .RE +.\" OPTION: -myaddr .TP -\fB\-myaddr\fR \fIaddress\fR +\fB\-myaddr\fI address\fR . Pass an specific local address to the underlying \fBsocket\fR call in case multiple interfaces are available. +.\" OPTION: -progress .TP -\fB\-progress\fR \fIcallback\fR +\fB\-progress\fI callback\fR . If the \fB\-progress\fR option is present, then the \fIcallback\fR is made after each transfer of data from the URL. @@ -475,14 +505,16 @@ proc httpProgress {token total current} { } .CE .RE +.\" OPTION: -protocol .TP -\fB\-protocol\fR \fIversion\fR +\fB\-protocol\fI version\fR . Select the HTTP protocol version to use. This should be 1.0 or 1.1 (the default). Should only be necessary for servers that do not understand or otherwise complain about HTTP/1.1. +.\" OPTION: -query .TP -\fB\-query\fR \fIquery\fR +\fB\-query\fI query\fR . This flag (if the value is non-empty) causes \fB::http::geturl\fR to do a POST request that passes the string @@ -499,8 +531,9 @@ x-url-encoding formatted query-string (this \fB\-type\fR and query format are used in a POST submitted from an html form). The \fB::http::formatQuery\fR procedure can be used to do the formatting. .RE +.\" OPTION: -queryblocksize .TP -\fB\-queryblocksize\fR \fIsize\fR +\fB\-queryblocksize\fI size\fR . The block size used when posting query data to the URL. At most @@ -508,8 +541,9 @@ At most bytes are written at once. After each block, a call to the \fB\-queryprogress\fR callback is made (if that option is specified). +.\" OPTION: -querychannel .TP -\fB\-querychannel\fR \fIchannelID\fR +\fB\-querychannel\fI channelID\fR . This flag causes \fB::http::geturl\fR to do a POST request that passes the data contained in \fIchannelID\fR to the server. The data contained in @@ -519,22 +553,25 @@ If a \fBContent-Length\fR header is not specified via the \fB\-headers\fR options, \fB::http::geturl\fR attempts to determine the size of the post data in order to create that header. If it is unable to determine the size, it returns an error. +.\" OPTION: -queryprogress .TP -\fB\-queryprogress\fR \fIcallback\fR +\fB\-queryprogress\fI callback\fR . If the \fB\-queryprogress\fR option is present, then the \fIcallback\fR is made after each transfer of data to the URL in a POST request (i.e. a call to \fB::http::geturl\fR with option \fB\-query\fR or \fB\-querychannel\fR) and acts exactly like the \fB\-progress\fR option (the callback format is the same). +.\" OPTION: -strict .TP -\fB\-strict\fR \fIboolean\fR +\fB\-strict\fI boolean\fR . If true then the command will test that the URL complies with RFC 3986, i.e. that it has no characters that should be "x-url-encoded" (e.g. a space should be encoded to "%20"). Default value is 1. +.\" OPTION: -timeout .TP -\fB\-timeout\fR \fImilliseconds\fR +\fB\-timeout\fI milliseconds\fR . If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout to occur after the specified number of milliseconds. @@ -543,14 +580,16 @@ the \fB\-command\fR callback, if specified. The return value of \fB::http::status\fR (and the value of the \fIstatus\fR key in the dictionary returned by \fB::http::responseInfo\fR) is \fBtimeout\fR after a timeout has occurred. +.\" OPTION: -type .TP -\fB\-type\fR \fImime-type\fR +\fB\-type\fI mime-type\fR . Use \fImime-type\fR as the \fBContent-Type\fR value, instead of the default value (\fBapplication/x-www-form-urlencoded\fR) during a POST operation. +.\" OPTION: -validate .TP -\fB\-validate\fR \fIboolean\fR +\fB\-validate\fI boolean\fR . If \fIboolean\fR is non-zero, then \fB::http::geturl\fR does an HTTP HEAD request. This server returns the same status line and response headers as it @@ -559,27 +598,31 @@ would for a HTTP GET request, but omits the response entity transaction using command \fB::http::responseHeaders\fR or, for selected information, \fB::http::responseInfo\fR. .RE +.\" COMMAND: formatQuery .TP -\fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...? +\fB::http::formatQuery\fI key value\fR ?\fIkey value\fR ...? . This procedure does x-url-encoding of query data. It takes an even number of arguments that are the keys and values of the query. It encodes the keys and values, and generates one string that has the proper & and = separators. The result is suitable for the \fB\-query\fR value passed to \fB::http::geturl\fR. +.\" COMMAND: quoteString .TP -\fB::http::quoteString\fR \fIvalue\fR +\fB::http::quoteString\fI value\fR . This procedure does x-url-encoding of string. It takes a single argument and encodes it. +.\" COMMAND: reset .TP -\fB::http::reset\fR \fItoken\fR ?\fIwhy\fR? +\fB::http::reset\fI token\fR ?\fIwhy\fR? . This command resets the HTTP transaction identified by \fItoken\fR, if any. This sets the \fBstate(status)\fR value to \fIwhy\fR, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback. +.\" COMMAND: wait .TP -\fB::http::wait\fR \fItoken\fR +\fB::http::wait\fI token\fR . This command blocks and waits for the transaction to complete. This only works in trusted code because it @@ -588,8 +631,9 @@ uses \fBvwait\fR. Also, it is not useful for the case where because in this case the \fB::http::geturl\fR call does not return until the HTTP transaction is complete, and thus there is nothing to wait for. +.\" COMMAND: status .TP -\fB::http::status\fR \fItoken\fR +\fB::http::status\fI token\fR . This command returns a description of the status of the HTTP transaction. The return value is the empty string until the HTTP transaction is @@ -601,19 +645,22 @@ section \fBERRORS\fR (below). The name "status" is not related to the terms "status line" and "status code" that are defined for a HTTP response. .RE +.\" COMMAND: size .TP -\fB::http::size\fR \fItoken\fR +\fB::http::size\fI token\fR . This command returns the number of bytes received so far from the URL in the \fB::http::geturl\fR call. +.\" COMMAND: error .TP -\fB::http::error\fR \fItoken\fR +\fB::http::error\fI token\fR . This command returns the error information if the HTTP transaction failed, or the empty string if there was no error. The information is a Tcl list of the error message, stack trace, and error code. +.\" COMMAND: postError .TP -\fB::http::postError\fR \fItoken\fR +\fB::http::postError\fI token\fR . A POST request is a call to \fB::http::geturl\fR with either the \fB\-query\fR or \fB\-querychannel\fR option. @@ -623,8 +670,9 @@ string if there was no error. The information is a Tcl list of the error message, stack trace, and error code. When this type of error occurs, the \fB::http::geturl\fR command continues the transaction and attempts to receive a response from the server. +.\" COMMAND: cleanup .TP -\fB::http::cleanup\fR \fItoken\fR +\fB::http::cleanup\fI token\fR . This procedure cleans up the state associated with the connection identified by \fItoken\fR. After this call, the procedures @@ -634,8 +682,9 @@ this function after you are done with a given HTTP request. Not doing so will result in memory not being freed, and if your app calls \fB::http::geturl\fR enough times, the memory leak could cause a performance hit...or worse. +.\" COMMAND: requestLine .TP -\fB::http::requestLine\fR \fItoken\fR +\fB::http::requestLine\fI token\fR . This command returns the "request line" sent to the server. The "request line" is the first line of a HTTP client request, and has three @@ -647,8 +696,9 @@ GET / HTTP/1.1 GET /introduction.html?subject=plumbing HTTP/1.1 POST /forms/order.html HTTP/1.1 .RE +.\" COMMAND: requestHeaders .TP -\fB::http::requestHeaders\fR \fItoken\fR ?\fIheaderName\fR? +\fB::http::requestHeaders\fI token\fR ?\fIheaderName\fR? . This command returns the HTTP request header names and values, in the order that they were sent to the server, as a Tcl list of the form @@ -659,8 +709,9 @@ are returned. If two arguments are supplied, the second provides the value of a header name. Only headers with the requested name (converted to lower case) are returned. If no such headers are found, an empty list is returned. +.\" COMMAND: requestHeaderValue .TP -\fB::http::requestHeaderValue\fR \fItoken\fR \fIheaderName\fR +\fB::http::requestHeaderValue\fI token headerName\fR . This command returns the value of the HTTP request header named \fIheaderName\fR. Header names are case-insensitive and are converted to @@ -668,8 +719,9 @@ lower case. If no such header exists, the return value is the empty string. If there are multiple headers named \fIheaderName\fR, the result is obtained by joining the individual values with the string ", " (comma and space), preserving their order. +.\" COMMAND: responseLine .TP -\fB::http::responseLine\fR \fItoken\fR +\fB::http::responseLine\fI token\fR . This command returns the first line of the server response: the HTTP "status line". The "status line" has three @@ -695,15 +747,17 @@ and can be changed without affecting the HTTP protocol. The recommended values (RFC 7231 and IANA assignments) for each code are provided by the command \fB::http::reasonPhrase\fR. .RE +.\" COMMAND: responseCode .TP -\fB::http::responseCode\fR \fItoken\fR +\fB::http::responseCode\fI token\fR . This command returns the "status code" (200, 404, etc.) of the server "status line". If a three-digit code cannot be found, the full status line is returned. See command \fB::http::responseLine\fR for more information on the "status line". +.\" COMMAND: reasonPhrase .TP -\fB::http::reasonPhrase\fR \fIcode\fR +\fB::http::reasonPhrase\fI code\fR . This command returns the IANA recommended "reason phrase" for a particular "status code" returned by a HTTP server. The argument \fIcode\fR is a valid @@ -724,8 +778,9 @@ the "reason phrase" stored in key \fIreasonPhrase\fR). A registry of valid status codes is maintained at https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml .RE +.\" COMMAND: responseHeaders .TP -\fB::http::responseHeaders\fR \fItoken\fR ?\fIheaderName\fR? +\fB::http::responseHeaders\fI token\fR ?\fIheaderName\fR? . The response from a HTTP server includes metadata headers that describe the response body and the transaction itself. @@ -739,8 +794,9 @@ supplied, it provides the value of a header name. Only headers with the requested name (converted to lower case) are returned. If no such headers are found, an empty list is returned. See section \fBMETADATA\fR for more information. +.\" COMMAND: responseHeaderValue .TP -\fB::http::responseHeaderValue\fR \fItoken\fR \fIheaderName\fR +\fB::http::responseHeaderValue\fI token headerName\fR . This command returns the value of the HTTP response header named \fIheaderName\fR. Header names are case-insensitive and are converted to @@ -751,9 +807,10 @@ preserving their order. Multiple headers with the same name may be processed in this manner, except \fBSet-Cookie\fR which does not conform to the comma-separated-list syntax and cannot be combined into a single value. Each \fBSet-Cookie\fR header must be treated individually, e.g. by processing -the return value of \fB::http::responseHeaders\fR \fItoken\fR \fBSet-Cookie\fR. +the return value of \fB::http::responseHeaders\fI token\fR \fBSet-Cookie\fR. +.\" COMMAND: responseInfo .TP -\fB::http::responseInfo\fR \fItoken\fR +\fB::http::responseInfo\fI token\fR . This command returns a \fBdict\fR of selected response metadata that are essential for identifying a successful transaction and making use of the @@ -775,8 +832,9 @@ text resource as a binary, or vice versa. After a POST transaction, check the value of \fIpostError\fR to verify that the request body was uploaded without error. .RE +.\" COMMAND: responseBody .TP -\fB::http::responseBody\fR \fItoken\fR +\fB::http::responseBody\fI token\fR . This command returns the entity sent by the HTTP server (unless \fI-channel\fR was used, in which case the entity was delivered to the @@ -788,8 +846,9 @@ Other terms for "resource", "response body after decoding", "payload", "message body after decoding", "content(s)", and "file". .RE +.\" COMMAND: register .TP -\fB::http::register\fR \fIproto port command\fR ?\fIsocketCmdVarName\fR? ?\fIuseSockThread\fR? ?\fIendToEndProxy\fR? +\fB::http::register\fI proto port command\fR ?\fIsocketCmdVarName\fR? ?\fIuseSockThread\fR? ?\fIendToEndProxy\fR? . This procedure allows one to provide custom HTTP transport types such as HTTPS, by registering a prefix, the default port, and the @@ -809,7 +868,7 @@ arguments \fIuseSockThread\fR, \fIendToEndProxy\fR, which take boolean values with default value \fIfalse\fR. .PP Iff argument \fIuseSockThread\fR is supplied and is boolean \fItrue\fR, -then iff permitted by the value [\fBhttp::config\fR \fI-threadlevel\fR] +then iff permitted by the value [\fBhttp::config\fI \-threadlevel\fR] and by the availability of package \fBThread\fR, sockets created for the transport will be opened in a different thread so that a slow DNS lookup will not cause the script to block. @@ -825,7 +884,6 @@ For example, .PP .CS package require http - package require tls ::http::register https 443 ::tls::socket ::tls::socketCmd 1 1 @@ -834,8 +892,9 @@ set token [::http::geturl https://my.secure.site/] .CE .RE .RE +.\" COMMAND: registerError .TP -\fB::http::registerError\fR \fIsock\fR ?\fImessage\fR? +\fB::http::registerError\fI sock\fR ?\fImessage\fR? . This procedure allows a registered protocol handler to deliver an error message for use by \fBhttp\fR. Calling this command does not raise an @@ -845,27 +904,32 @@ propagate to \fBhttp\fR. The command allows \fBhttp\fR to provide a precise error message rather than a general one. The command returns the value provided by the last call with argument \fImessage\fR, or the empty string if no such call has been made. +.\" COMMAND: unregister .TP -\fB::http::unregister\fR \fIproto\fR +\fB::http::unregister\fI proto\fR . This procedure unregisters a protocol handler that was previously registered via \fB::http::register\fR, returning a six-item list of the values that were previously supplied to \fB::http::register\fR if there was such a handler, and an error if there was no such handler. +.\" COMMAND: code .TP -\fB::http::code\fR \fItoken\fR +\fB::http::code\fI token\fR . An alternative name for the command \fB::http::responseLine\fR +.\" COMMAND: data .TP -\fB::http::data\fR \fItoken\fR +\fB::http::data\fI token\fR . An alternative name for the command \fB::http::responseBody\fR. +.\" COMMAND: meta .TP -\fB::http::meta\fR \fItoken\fR ?\fIheaderName\fR? +\fB::http::meta\fI token\fR ?\fIheaderName\fR? . An alternative name for the command \fB::http::responseHeaders\fR +.\" COMMAND: ncode .TP -\fB::http::ncode\fR \fItoken\fR +\fB::http::ncode\fI token\fR . An alternative name for the command \fB::http::responseCode\fR .SH ERRORS @@ -914,41 +978,29 @@ determined by examining the status from \fB::http::status\fR (or the value of the \fIstatus\fR key in the dictionary returned by \fB::http::responseInfo\fR). These are described below. -.TP -\fBok\fR -. +.IP \fBok\fR If the HTTP transaction completes entirely, then status will be \fBok\fR. However, you should still check the \fB::http::responseLine\fR value to get the HTTP status. The \fB::http::responseCode\fR procedure provides just the numeric error (e.g., 200, 404 or 500) while the \fB::http::responseLine\fR procedure returns a value like .QW "HTTP 404 File not found" . -.TP -\fBeof\fR -. +.IP \fBeof\fR If the server closes the socket without replying, then no error is raised, but the status of the transaction will be \fBeof\fR. -.TP -\fBerror\fR -. +.IP \fBerror\fR The error message, stack trace, and error code are accessible via \fB::http::error\fR. The error message is also provided by the value of the \fIerror\fR key in the dictionary returned by \fB::http::responseInfo\fR. -.TP -\fBtimeout\fR -. +.IP \fBtimeout\fR A timeout occurred before the transaction could complete. -.TP -\fBreset\fR -. +.IP \fBreset\fR The user has called \fB::http::reset\fR. -.TP -\fB""\fR -. +.IP \fB""\fR (empty string) The transaction has not yet finished. .PP Another error possibility is that \fB::http::geturl\fR failed to -write the whole of the POST request body (\fB-query\fR or \fB-querychannel\fR +write the whole of the POST request body (\fB\-query\fR or \fB\-querychannel\fR data) to the server. \fB::http::geturl\fR stores the error message for later retrieval by the \fB::http::postError\fR or \fB::http::responseInfo\fR commands, and then attempts to complete the transaction. @@ -974,46 +1026,35 @@ the \fBdict\fR are: .PP .RS .RS +.\" TODO: Find a better way to mark this up! \fB===== Essential Values =====\fR .RE .RE -.TP -\fBstage\fR -. +.IP \fBstage\fR This value, set by \fB::http::geturl\fR, describes the stage that the transaction has reached. Values, in order of the transaction lifecycle, are: "created", "connecting", "header", "body", and "complete". The other \fBdict\fR keys will not be available until the value of \fBstage\fR is "body" or "complete". The key \fBcurrentSize\fR has its final value only when \fBstage\fR is "complete". -.TP -\fBstatus\fR -. +.IP \fBstatus\fR This value, set by \fB::http::geturl\fR, is "ok" for a successful transaction; "eof", "error", "timeout", or "reset" for an unsuccessful transaction; or "" if the transaction is still in progress. The value is the same as that returned by command \fB::http::status\fR. The meaning of these values is described in the section \fBERRORS\fR (above). -.TP -\fBresponseCode\fR -. +.IP \fBresponseCode\fR The "HTTP status code" sent by the server in the first line (the "status line") of the response. If the value cannot be extracted from the status line, the full status line is returned. -.TP -\fBreasonPhrase\fR -. +.IP \fBreasonPhrase\fR The "reason phrase" sent by the server as a description of the HTTP status code. If the value cannot be extracted from the status line, the full status line is returned. -.TP -\fBcontentType\fR -. +.IP \fBcontentType\fR The value of the \fBContent-Type\fR response header or, if the header was not supplied, the default value "application/octet-stream". -.TP -\fBbinary\fR -. +.IP \fBbinary\fR This boolean value, set by \fB::http::geturl\fR, describes how the command has interpreted the entity returned by the server (after decoding any compression specified by the \fBContent-Encoding\fR response header). @@ -1025,7 +1066,7 @@ The value is \fBtrue\fR if http has interpreted the decoded entity as binary. The value returned by \fB::http::responseBody\fR is a Tcl binary string. This is a suitable format for image data, zip files, etc. \fB::http::geturl\fR chooses this value if the user has requested a binary -interpretation by passing the option \fI\-binary\fR to the command, or if the +interpretation by passing the option \fB\-binary\fR to the command, or if the server has supplied a binary content type in a \fBContent-Type\fR response header, or if the server has not supplied any \fBContent-Type\fR header. .PP @@ -1038,15 +1079,11 @@ It is always worth checking the value of "binary" after a HTTP transaction, to determine whether a misconfigured server has caused http to interpret a text resource as a binary, or vice versa. .RE -.TP -\fBredirection\fR -. +.IP \fBredirection\fR The URL that is the redirection target. The value is that of the \fBLocation\fR response header. This header is sent when a response has status code 3XX (redirection). -.TP -\fBupgrade\fR -. +.IP \fBupgrade\fR If not empty, the value indicates the protocol(s) to which the server will switch after completion of this transaction, while continuing to use the same connection. When the server intends to switch protocols, it will also @@ -1054,14 +1091,10 @@ send the value "101" as the status code (the \fBresponseCode\fR key), and the word "upgrade" as an element of the \fBConnection\fR response header (the \fBconnectionResponse\fR key), and it will not send a response body. See the section \fBPROTOCOL UPGRADES\fR for more information. -.TP -\fBerror\fR -. +.IP \fBerror\fR The error message, if there is one. Further information, including a stack trace and error code, are available from command \fB::http::error\fR. -.TP -\fBpostError\fR -. +.IP \fBpostError\fR The error message (if any) generated when a HTTP POST request sends its request-body to the server. Further information, including a stack trace and error code, are available from command \fB::http::postError\fR. A POST @@ -1075,13 +1108,9 @@ the request-body. \fB===== Informational Values =====\fR .RE .RE -.TP -\fBmethod\fR -. +.IP \fBmethod\fR The HTTP method used in the request. -.TP -\fBcharset\fR -. +.IP \fBcharset\fR The value of the charset attribute of the \fBContent-Type\fR response header. The charset value is used only for a text resource. If the server did not specify a charset, the value defaults to that of the @@ -1089,72 +1118,48 @@ variable \fB::http::defaultCharset\fR, which unless it has been deliberately modified by the caller is \fBiso8859-1\fR. Incoming text data is automatically converted from the character set defined by \fBcharset\fR to Tcl's internal Unicode representation, i.e. to a Tcl string. -.TP -\fBcompression\fR -. +.IP \fBcompression\fR A copy of the \fBContent-Encoding\fR response-header value. -.TP -\fBhttpRequest\fR -. +.IP \fBhttpRequest\fR The version of HTTP specified in the request (i.e. sent in the request line). The value is that of the option \fB\-protocol\fR supplied to \fB::http::geturl\fR (default value "1.1"), unless the command reduced the value to "1.0" because it was passed the \fB\-handler\fR option. -.TP -\fBhttpResponse\fR -. +.IP \fBhttpResponse\fR The version of HTTP used by the server (obtained from the response "status line"). The server uses this version of HTTP in its response, but ensures that this response is compatible with the HTTP version specified in the client's request. If the value cannot be extracted from the status line, the full status line is returned. -.TP -\fBurl\fR -. +.IP \fBurl\fR The requested URL, typically the URL supplied as an argument to \fB::http::geturl\fR but without its "fragment" (the final part of the URL beginning with "#"). -.TP -\fBconnectionRequest\fR -. +.IP \fBconnectionRequest\fR The value, if any, sent to the server in \fBConnection\fR request header(s). -.TP -\fBconnectionResponse\fR -. +.IP \fBconnectionResponse\fR The value, if any, received from the server in \fBConnection\fR response header(s). -.TP -\fBconnectionActual\fR -. +.IP \fBconnectionActual\fR This value, set by \fB::http::geturl\fR, reports whether the connection was closed after the transaction (value "close"), or left open (value "keep-alive"). -.TP -\fBtransferEncoding\fR -. +.IP \fBtransferEncoding\fR The value of the Transfer-Encoding response header, if it is present. The value is either "chunked" (indicating HTTP/1.1 "chunked encoding") or the empty string. -.TP -\fBtotalPost\fR -. +.IP \fBtotalPost\fR The total length of the request body in a POST request. -.TP -\fBcurrentPost\fR -. +.IP \fBcurrentPost\fR The number of bytes of the POST request body sent to the server so far. The value is the same as that returned by command \fB::http::size\fR. -.TP -\fBtotalSize\fR -. +.IP \fBtotalSize\fR A copy of the \fBContent-Length\fR response-header value. The number of bytes specified in a \fBContent-Length\fR header, if one was sent. If none was sent, the value is 0. A correctly configured server omits this header if the transfer-encoding is "chunked", or (for older servers) if the server closes the connection when it reaches the end of the resource. -.TP -\fBcurrentSize\fR -. +.IP \fBcurrentSize\fR The number of bytes fetched from the server so far. .PP .SS "MORE METADATA" @@ -1179,63 +1184,49 @@ Some of the header names (metadata keys) are listed below, but the HTTP standard defines several more, and servers are free to add their own. When a dictionary key is mentioned below, this refers to the \fBdict\fR value returned by command \fB::http::responseInfo\fR. -.TP -\fBContent-Type\fR -. +.IP \fBContent-Type\fR The content type of the URL contents. Examples include \fBtext/html\fR, \fBimage/gif,\fR \fBapplication/postscript\fR and \fBapplication/x-tcl\fR. Text values typically specify a character set, e.g. \fBtext/html; charset=UTF-8\fR. Dictionary key \fIcontentType\fR. -.TP -\fBContent-Length\fR -. +.IP \fBContent-Length\fR The advertised size in bytes of the contents, available as dictionary key \fItotalSize\fR. The actual number of bytes read by \fB::http::geturl\fR so far is available as dictionary key \fBcurrentSize\fR. -.TP -\fBContent-Encoding\fR -. +.IP \fBContent-Encoding\fR The compression algorithm used for the contents. Examples include \fBgzip\fR, \fBdeflate\fR. Dictionary key \fIcontent\fR. -.TP -\fBLocation\fR -. +.IP \fBLocation\fR This header is sent when a response has status code 3XX (redirection). It provides the URL that is the redirection target. Dictionary key \fIredirection\fR. -.TP -\fBSet-Cookie\fR -. +.IP \fBSet-Cookie\fR This header is sent to offer a cookie to the client. Cookie management is -done by the \fB::http::config\fR option \fI\-cookiejar\fR, and so +done by the \fB::http::config\fR option \fB\-cookiejar\fR, and so the \fBSet-Cookie\fR headers need not be parsed by user scripts. See section \fBCOOKIE JAR PROTOCOL\fR. -.TP -\fBConnection\fR -. +.IP \fBConnection\fR The value can be supplied as a comma-separated list, or by multiple headers. The list often has only one element, either "close" or "keep-alive". The value "upgrade" indicates a successful upgrade request and is typically combined with the status code 101, an \fBUpgrade\fR response header, and no response body. Dictionary key \fIconnectionResponse\fR. -.TP -\fBUpgrade\fR -. +.IP \fBUpgrade\fR The value indicates the protocol(s) to which the server will switch immediately after the empty line that terminates the 101 response headers. Dictionary key \fIupgrade\fR. .RE .PP .SS "EVEN MORE METADATA" -.PP -1. Details of the HTTP request. The request is determined by the options +.IP 1. +Details of the HTTP request. The request is determined by the options supplied to \fB::http::geturl\fR and \fB::http::config\fR. However, it is sometimes helpful to examine what \fB::http::geturl\fR actually sent to the server, and this information is available through commands \fB::http::requestHeaders\fR and \fB::http::requestLine\fR. -.PP -2. The state array: the internal variables of \fB::http::geturl\fR. +.IP 2. +The state array: the internal variables of \fB::http::geturl\fR. It may sometimes be helpful to examine this array. Details are given in the next section. .SH "STATE ARRAY" @@ -1263,114 +1254,60 @@ values returned by commands as described below. When a dictionary key is mentioned below, this refers to the \fBdict\fR value returned by command \fB::http::responseInfo\fR. .RS -.TP -\fBbinary\fR -. +.IP \fBbinary\fR For dictionary key \fIbinary\fR. -.TP -\fBbody\fR -. +.IP \fBbody\fR For command \fB::http::responseBody\fR. -.TP -\fBcharset\fR -. +.IP \fBcharset\fR For dictionary key \fIcharset\fR. -.TP -\fBcoding\fR -. +.IP \fBcoding\fR For dictionary key \fIcompression\fR. -.TP -\fBconnection\fR -. +.IP \fBconnection\fR For dictionary key \fIconnectionActual\fR. -.TP -\fBcurrentsize\fR -. +.IP \fBcurrentsize\fR For command \fB::http::size\fR; and for dictionary key \fIcurrentSize\fR. -.TP -\fBerror\fR -. +.IP \fBerror\fR For command \fB::http::error\fR; part is used in dictionary key \fIerror\fR. -.TP -\fBhttp\fR -. +.IP \fBhttp\fR For command \fB::http::responseLine\fR. -.TP -\fBhttpResponse\fR -. +.IP \fBhttpResponse\fR For dictionary key \fIhttpResponse\fR. -.TP -\fBmeta\fR -. +.IP \fBmeta\fR For command \fB::http::responseHeaders\fR. Further discussion above in the section \fBMORE METADATA\fR. -.TP -\fBmethod\fR -. +.IP \fBmethod\fR For dictionary key \fImethod\fR. -.TP -\fBposterror\fR -. +.IP \fBposterror\fR For dictionary key \fIpostError\fR. -.TP -\fBpostErrorFull\fR -. +.IP \fBpostErrorFull\fR For command \fB::http::postError\fR. -.TP -\fB\-protocol\fR -. +.IP \fB\-protocol\fR For dictionary key \fIhttpRequest\fR. -.TP -\fBquerylength\fR -. +.IP \fBquerylength\fR For dictionary key \fItotalPost\fR. -.TP -\fBqueryoffset\fR -. +.IP \fBqueryoffset\fR For dictionary key \fIcurrentPost\fR. -.TP -\fBreasonPhrase\fR -. +.IP \fBreasonPhrase\fR For dictionary key \fIreasonPhrase\fR. -.TP -\fBrequestHeaders\fR -. +.IP \fBrequestHeaders\fR For command \fB::http::requestHeaders\fR. -.TP -\fBrequestLine\fR -. +.IP \fBrequestLine\fR For command \fB::http::requestLine\fR. -.TP -\fBresponseCode\fR -. +.IP \fBresponseCode\fR For dictionary key \fIresponseCode\fR. -.TP -\fBstate\fR -. +.IP \fBstate\fR For dictionary key \fIstage\fR. -.TP -\fBstatus\fR -. +.IP \fBstatus\fR For command \fB::http::status\fR; and for dictionary key \fIstatus\fR. -.TP -\fBtotalsize\fR -. +.IP \fBtotalsize\fR For dictionary key \fItotalSize\fR. -.TP -\fBtransfer\fR -. +.IP \fBtransfer\fR For dictionary key \fItransferEncoding\fR. -.TP -\fBtype\fR -. +.IP \fBtype\fR For dictionary key \fIcontentType\fR. -.TP -\fBupgrade\fR -. +.IP \fBupgrade\fR For dictionary key \fIupgrade\fR. -.TP -\fBurl\fR -. +.IP \fBurl\fR For dictionary key \fIurl\fR. .RE .SH "PERSISTENT CONNECTIONS" @@ -1481,7 +1418,7 @@ Cookies are short key-value pairs used to implement sessions within the otherwise-stateless HTTP protocol. (See RFC 6265 for details; Tcl does not implement the Cookie2 protocol as that is rarely seen in the wild.) .PP -Cookie storage managment commands \(em +Cookie storage management commands \(em .QW "cookie jars" \(em must support these subcommands which form the HTTP cookie storage management protocol. Note that \fIcookieJar\fR below does not have to be a @@ -1493,6 +1430,7 @@ values of \fIcookieJar\fR will correspond to sessions; it is up to the caller of \fB::http::config\fR to decide what session applies and to manage the deletion of said sessions when they are no longer desired (which should be when they not configured as the current cookie jar). +.\" METHOD: getCookies .TP \fIcookieJar \fBgetCookies \fIprotocol host requestPath\fR . @@ -1509,6 +1447,7 @@ request (typically the one with the most specific \fIhost\fR/domain match and most specific \fIrequestPath\fR/path match), but there may be many cookies with different names in any request. .RE +.\" METHOD: storeCookie .TP \fIcookieJar \fBstoreCookie \fIcookieDictionary\fR . @@ -1517,58 +1456,40 @@ returned by a request; the result of this command is ignored. The cookie (which will have been parsed by the http package) is described by a dictionary, \fIcookieDictionary\fR, that may have the following keys: .RS -.TP -\fBdomain\fR -. +.IP \fBdomain\fR This is always present. Its value describes the domain hostname \fIor prefix\fR that the cookie should be returned for. The checking of the domain against the origin (below) should be careful since sites that issue cookies should only do so for domains related to themselves. Cookies that do not obey a relevant origin matching rule should be ignored. -.TP -\fBexpires\fR -. +.IP \fBexpires\fR This is optional. If present, the cookie is intended to be a persistent cookie and the value of the option is the Tcl timestamp (in seconds from the same base as \fBclock seconds\fR) of when the cookie expires (which may be in the past, which should result in the cookie being deleted immediately). If absent, the cookie is intended to be a session cookie that should be not persisted beyond the lifetime of the cookie jar. -.TP -\fBhostonly\fR -. +.IP \fBhostonly\fR This is always present. Its value is a boolean that describes whether the cookie is a single host cookie (true) or a domain-level cookie (false). -.TP -\fBhttponly\fR -. +.IP \fBhttponly\fR This is always present. Its value is a boolean that is true when the site wishes the cookie to only ever be used with HTTP (or HTTPS) traffic. -.TP -\fBkey\fR -. +.IP \fBkey\fR This is always present. Its value is the \fIkey\fR of the cookie, which is part of the information that must be return when sending this cookie back in a future request. -.TP -\fBorigin\fR -. +.IP \fBorigin\fR This is always present. Its value describes where the http package believes it received the cookie from, which may be useful for checking whether the cookie's domain is valid. -.TP -\fBpath\fR -. +.IP \fBpath\fR This is always present. Its value describes the path prefix of requests to the cookie domain where the cookie should be returned. -.TP -\fBsecure\fR -. +.IP \fBsecure\fR This is always present. Its value is a boolean that is true when the cookie should only used on requests sent over secure channels (typically HTTPS). -.TP -\fBvalue\fR -. +.IP \fBvalue\fR This is always present. Its value is the value of the cookie, which is part of the information that must be return when sending this cookie back in a future request. @@ -1618,19 +1539,19 @@ See https://w3c.github.io/webappsec-upgrade-insecure-requests/ .SS "PURPOSE" .PP Command \fB::http::geturl\fR uses the Tcl \fB::socket\fR command with -the \fI\-async\fR option to connect to a remote server, but the return from +the \fB\-async\fR option to connect to a remote server, but the return from this command can be delayed in adverse cases (e.g. a slow DNS lookup), preventing the event loop from processing other events. This delay is avoided if the \fB::socket\fR command is evaluated in another thread. The Thread package is not part of Tcl but is provided in "Batteries Included" distributions. Instead of the \fB::socket\fR command, the http package uses \fB::http::socket\fR which makes connections in the -manner specified by the value of \fI\-threadlevel\fR and the availability +manner specified by the value of \fB\-threadlevel\fR and the availability of package Thread. .PP .SS "WITH TLS (HTTPS)" .PP -The same \fI\-threadlevel\fR configuration applies to both HTTP and HTTPS +The same \fB\-threadlevel\fR configuration applies to both HTTP and HTTPS connections. HTTPS is enabled by using the \fBhttp::register\fR command, typically by specifying the \fB::tls::socket\fR command of the tls package to handle TLS @@ -1648,10 +1569,10 @@ for integrating \fB::http::socket\fR into its own replacement command. .PP The peer thread can transfer the socket only to the main interpreter of the script's thread. Therefore the thread-based \fB::http::socket\fR works with -non-zero \fI\-threadlevel\fR values only if the script runs in the main -interpreter. A child interpreter must use \fI\-threadlevel 0\fR unless the +non-zero \fB\-threadlevel\fR values only if the script runs in the main +interpreter. A child interpreter must use \fB\-threadlevel 0\fR unless the parent interpreter has provided alternative facilities. The main parent -interpreter may grant full \fI\-threadlevel\fR facilities to a child +interpreter may grant full \fB\-threadlevel\fR facilities to a child interpreter, for example by aliasing, to \fB::http::socket\fR in the child, a command that runs \fBhttp::socket\fR in the parent, and then transfers the socket to the child. @@ -1691,7 +1612,7 @@ proc httpcopy { url file {chunk 4096} } { return $token } proc httpCopyProgress {args} { - puts \-nonewline stderr . + puts -nonewline stderr . flush stderr } .CE @@ -149,60 +149,37 @@ is seen by \fBinfo frame\fR invoked within .QW x . .PP The dictionary may contain the following keys: -.TP -\fBtype\fR -. +.IP \fBtype\fR Always present. Possible values are \fBsource\fR, \fBproc\fR, \fBeval\fR, and \fBprecompiled\fR. .RS -.TP -\fBsource\fR\0\0\0\0\0\0\0\0 -. -A script loaded via the \fBsource\fR -command. -.TP -\fBproc\fR\0\0\0\0\0\0\0\0 -. +.IP \fBsource\fR +A script loaded via the \fBsource\fR command. +.IP \fBproc\fR The body of a procedure that could not be traced back to a line in a particular script. -.TP -\fBeval\fR\0\0\0\0\0\0\0\0 -. +.IP \fBeval\fR The body of a script provided to \fBeval\fR or \fBuplevel\fR. -.TP -\fBprecompiled\fR\0\0\0\0\0\0\0\0 -. +.IP \fBprecompiled\fR A precompiled script (loadable by the package \fBtbcload\fR), and no further information is available. .RE -.TP -\fBline\fR -. +.IP \fBline\fR The line number of of the command inside its script. Not available for \fBprecompiled\fR commands. When the type is \fBsource\fR, the line number is relative to the beginning of the file, whereas for the last two types it is relative to the start of the script. -.TP -\fBfile\fR -. +.IP \fBfile\fR For type \fBsource\fR, provides the normalized path of the file that contains the command. -.TP -\fBcmd\fR -. +.IP \fBcmd\fR The command before substitutions were performed. -.TP -\fBproc\fR -. +.IP \fBproc\fR For type \fBprod\fR, the name of the procedure containing the command. -.TP -\fBlambda\fR -. +.IP \fBlambda\fR For a command in a script evaluated as the body of an unnamed routine via the \fBapply\fR command, the definition of that routine. -.TP -\fBlevel\fR -. +.IP \fBlevel\fR For a frame that corresponds to a level, (to be determined). .PP When a command can be traced to its literal definition in some script, e.g. @@ -262,7 +239,7 @@ If \fInumber\fR is not given, the level this routine was called from. Otherwise returns the complete command active at the given level. If \fInumber\fR is greater than \fB0\fR, it is the desired level. Otherwise, it is \fInumber\fR levels up from the current level. A complete command is the -words in the command, with all subsitutions performed, meaning that it is a +words in the command, with all substitutions performed, meaning that it is a list. See \fBuplevel\fR for more information on levels. .TP \fBinfo library\fR @@ -433,6 +410,7 @@ This subcommand returns a list of all public (i.e. exported) methods of the class called \fIclass\fR. Any of the following \fIoption\fRs may be given, controlling exactly which method names are returned: .RS +.\" OPTION: -all .TP \fB\-all\fR . @@ -443,6 +421,7 @@ and the \fB\-scope\fR flag is not given, the list of methods will include those methods defined not just by the class, but also by the class's superclasses and mixins. +.\" OPTION: -private .TP \fB\-private\fR . @@ -457,6 +436,7 @@ mixins, if \fB\-all\fR is also given). Note that this naming is an unfortunate clash with true private methods; this option name is retained for backward compatibility. .VE TIP500 +.\" OPTION: -scope .TP \fB\-scope\fI scope\fR .VS TIP500 @@ -465,14 +445,14 @@ Returns a list of all methods on \fIclass\fR that have the given visibility \fB\-private\fR options are ignored. The valid values for \fIscope\fR are: .RS .IP \fBpublic\fR 3 -Only methods with \fIpublic\fR scope (i.e., callable from anywhere by any instance -of this class) are to be returned. +Only methods with \fIpublic\fR scope (i.e., callable from anywhere by any +instance of this class) are to be returned. .IP \fBunexported\fR 3 -Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to -be returned. +Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) +are to be returned. .IP \fBprivate\fR 3 -Only methods with \fIprivate\fR scope (i.e., only callable from within this class's -methods) are to be returned. +Only methods with \fIprivate\fR scope (i.e., only callable from within this +class's methods) are to be returned. .RE .VE TIP500 .RE @@ -495,16 +475,19 @@ class named \fIclass\fR. This subcommand returns a sorted list of properties defined on the class named \fIclass\fR. The \fIoptions\fR define exactly which properties are returned: .RS +.\" OPTION: -all .TP \fB\-all\fR . With this option, the properties from the superclasses and mixins of the class are also returned. +.\" OPTION: -readable .TP \fB\-readable\fR . This option (the default behavior) asks for the readable properties to be returned. Only readable or writable properties are returned, not both. +.\" OPTION: -writable .TP \fB\-writable\fR . @@ -640,6 +623,7 @@ This subcommand returns a list of all public (i.e. exported) methods of the object called \fIobject\fR. Any of the following \fIoption\fRs may be given, controlling exactly which method names are returned: .RS +.\" OPTION: -all .TP \fB\-all\fR . @@ -650,6 +634,7 @@ and the \fB\-scope\fR flag is not given, the list of methods will include those methods defined not just by the object, but also by the object's class and mixins, plus the superclasses of those classes. +.\" OPTION: -private .TP \fB\-private\fR . @@ -664,6 +649,7 @@ the non-exported methods of the object (and classes, if Note that this naming is an unfortunate clash with true private methods; this option name is retained for backward compatibility. .VE TIP500 +.\" OPTION: -scope .TP \fB\-scope\fI scope\fR .VS TIP500 @@ -675,11 +661,11 @@ Returns a list of all methods on \fIobject\fR that have the given visibility Only methods with \fIpublic\fR scope (i.e., callable from anywhere) are to be returned. .IP \fBunexported\fR 3 -Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to -be returned. +Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) +are to be returned. .IP \fBprivate\fR 3 -Only methods with \fIprivate\fR scope (i.e., only callable from within this object's -instance methods) are to be returned. +Only methods with \fIprivate\fR scope (i.e., only callable from within this +object's instance methods) are to be returned. .RE .VE TIP500 .RE @@ -708,16 +694,19 @@ This subcommand returns a sorted list of properties defined on the object named \fIobject\fR. The \fIoptions\fR define exactly which properties are returned: .RS +.\" OPTION: -all .TP \fB\-all\fR . With this option, the properties from the class, superclasses and mixins of the object are also returned. +.\" OPTION: -readable .TP \fB\-readable\fR . This option (the default behavior) asks for the readable properties to be returned. Only readable or writable properties are returned, not both. +.\" OPTION: -writable .TP \fB\-writable\fR . @@ -726,7 +715,7 @@ writable properties are returned, not both. .RE .VE "TIP 558" .TP -\fBinfo object variables\fI object\fRR ?\fB\-private\fR? +\fBinfo object variables\fI object\fR ?\fB\-private\fR? . This subcommand returns a list of all variables that have been declared for the object named \fIobject\fR (i.e. that are automatically present in the diff --git a/doc/interp.n b/doc/interp.n index 08bed1c..cddf283 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -87,8 +87,9 @@ The \fBinterp\fR command is used to create, delete, and manipulate child interpreters, and to share or transfer channels between interpreters. It can have any of several forms, depending on the \fIsubcommand\fR argument: +.\" METHOD: alias .TP -\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR +\fBinterp alias\fI srcPath srcToken\fR . Returns a Tcl list whose elements are the \fItargetCmd\fR and \fIarg\fRs associated with the alias represented by \fIsrcToken\fR @@ -96,7 +97,7 @@ Returns a Tcl list whose elements are the \fItargetCmd\fR and created; it is possible that the name of the source command in the child is different from \fIsrcToken\fR). .TP -\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR \fB{}\fR +\fBinterp alias\fI srcPath srcToken\fR \fB{}\fR . Deletes the alias for \fIsrcToken\fR in the child interpreter identified by \fIsrcPath\fR. @@ -104,7 +105,7 @@ Deletes the alias for \fIsrcToken\fR in the child interpreter identified by was created; if the source command has been renamed, the renamed command will be deleted. .TP -\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fItargetPath\fR \fItargetCmd \fR?\fIarg arg ...\fR? +\fBinterp alias\fI srcPath srcCmd targetPath targetCmd \fR?\fIarg arg ...\fR? . This command creates an alias between one child and another (see the \fBalias\fR child command below for creating aliases between a child @@ -135,14 +136,16 @@ more details. The command returns a token that uniquely identifies the command created \fIsrcCmd\fR, even if the command is renamed afterwards. The token may but does not have to be equal to \fIsrcCmd\fR. +.\" METHOD: aliases .TP -\fBinterp\fR \fBaliases \fR?\fIpath\fR? +\fBinterp aliases \fR?\fIpath\fR? . This command returns a Tcl list of the tokens of all the source commands for aliases defined in the interpreter identified by \fIpath\fR. The tokens correspond to the values returned when the aliases were created (which may not be the same as the current names of the commands). +.\" METHOD: bgerror .TP \fBinterp bgerror \fIpath\fR ?\fIcmdPrefix\fR? . @@ -152,8 +155,10 @@ absent, the current background exception handler is returned, and if it is present, it is a list of words (of minimum length one) that describes what to set the interpreter's background exception handler to. See the \fBBACKGROUND EXCEPTION HANDLING\fR section for more details. +.\" METHOD: cancel .TP -\fBinterp\fR \fBcancel \fR?\fB\-unwind\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? ?\fIresult\fR? +\fBinterp cancel \fR?\fB\-unwind\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? ?\fIresult\fR? +. Cancels the script being evaluated in the interpreter identified by \fIpath\fR. Without the \fB\-unwind\fR switch the evaluation stack for the interpreter is unwound until an enclosing catch command is found or @@ -166,8 +171,16 @@ switches; it may be needed if \fIpath\fR is an unusual value such as \fB\-safe\fR. If \fIresult\fR is present, it will be used as the error message string; otherwise, a default error message string will be used. +.\" METHOD: children +.TP +\fBinterp children\fR ?\fIpath\fR? +. +Returns a Tcl list of the names of all the child interpreters associated +with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted, +the invoking interpreter is used. +.\" METHOD: create .TP -\fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? +\fBinterp create \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? . Creates a child interpreter identified by \fIpath\fR and a new command, called a \fIchild command\fR. The name of the child command is the last @@ -191,8 +204,9 @@ the children for its parent; an error occurs if a child interpreter by the given name already exists in this parent. The initial recursion limit of the child interpreter is set to the current recursion limit of its parent interpreter. +.\" METHOD: debug .TP -\fBinterp\fR \fBdebug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR?? +\fBinterp debug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR?? . Controls whether frame-level stack information is captured in the child interpreter identified by \fIpath\fR. If no arguments are @@ -233,16 +247,18 @@ Note that once it is on, this flag cannot be switched back off: such attempts are silently ignored. This is needed to maintain the consistency of the underlying interpreter's state. .RE +.\" METHOD: delete .TP -\fBinterp\fR \fBdelete \fR?\fIpath ...\fR? +\fBinterp delete \fR?\fIpath ...\fR? . Deletes zero or more interpreters given by the optional \fIpath\fR arguments, and for each interpreter, it also deletes its children. The command also deletes the child command for each interpreter deleted. For each \fIpath\fR argument, if no interpreter by that name exists, the command raises an error. +.\" METHOD: eval .TP -\fBinterp\fR \fBeval\fR \fIpath arg \fR?\fIarg ...\fR? +\fBinterp eval\fI path arg \fR?\fIarg ...\fR? . This command concatenates all of the \fIarg\fR arguments in the same fashion as the \fBconcat\fR command, then evaluates the resulting string as @@ -250,19 +266,24 @@ a Tcl script in the child interpreter identified by \fIpath\fR. The result of this evaluation (including all \fBreturn\fR options, such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an error occurs) is returned to the invoking interpreter. +.RS +.PP Note that the script will be executed in the current context stack frame of the \fIpath\fR interpreter; this is so that the implementations (in a parent interpreter) of aliases in a child interpreter can execute scripts in the child that find out information about the child's current state and stack frame. +.RE +.\" METHOD: exists .TP \fBinterp exists \fIpath\fR . Returns \fB1\fR if a child interpreter by the specified \fIpath\fR exists in this parent, \fB0\fR otherwise. If \fIpath\fR is omitted, the invoking interpreter is used. +.\" METHOD: expose .TP -\fBinterp expose \fIpath\fR \fIhiddenName\fR ?\fIexposedCmdName\fR? +\fBinterp expose \fIpath hiddenName\fR ?\fIexposedCmdName\fR? . Makes the hidden command \fIhiddenName\fR exposed, eventually bringing it back under a new \fIexposedCmdName\fR name (this name is currently @@ -272,8 +293,9 @@ denoted by \fIpath\fR. If an exposed command with the targeted name already exists, this command fails. Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. +.\" METHOD: hide .TP -\fBinterp\fR \fBhide\fR \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR? +\fBinterp hide\fI path exposedCmdName\fR ?\fIhiddenCmdName\fR? . Makes the exposed command \fIexposedCmdName\fR hidden, renaming it to the hidden command \fIhiddenCmdName\fR, or keeping the same name if @@ -288,13 +310,15 @@ namespace even if the current namespace is not the global one. This prevents children from fooling a parent interpreter into hiding the wrong command, by making the current namespace be different from the global one. Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. +.\" METHOD: hidden .TP -\fBinterp\fR \fBhidden\fR \fIpath\fR +\fBinterp hidden\fI path\fR . Returns a list of the names of all hidden commands in the interpreter identified by \fIpath\fR. +.\" METHOD: invokehidden .TP -\fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fI\-option ...\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR? +\fBinterp invokehidden\fI path\fR ?\fI\-option ...\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR? . Invokes the hidden command \fIhiddenCmdName\fR with the arguments supplied in the interpreter denoted by \fIpath\fR. No substitutions or evaluation @@ -312,16 +336,22 @@ The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a character, and is otherwise unnecessary. If both the \fB\-namespace\fR and \fB\-global\fR flags are present, the \fB\-namespace\fR flag is ignored. +.RS +.PP Note that the hidden command will be executed (by default) in the current context stack frame of the \fIpath\fR interpreter. +.PP Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. +.RE +.\" METHOD: issafe .TP \fBinterp issafe\fR ?\fIpath\fR? . Returns \fB1\fR if the interpreter identified by the specified \fIpath\fR is safe, \fB0\fR otherwise. +.\" METHOD: limit .TP -\fBinterp\fR \fBlimit\fR \fIpath\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR? +\fBinterp limit\fI path limitType\fR ?\fI\-option\fR? ?\fIvalue ...\fR? . Sets up, manipulates and queries the configuration of the resource limit \fIlimitType\fR for the interpreter denoted by \fIpath\fR. If @@ -330,16 +360,18 @@ limit. If \fI\-option\fR is the sole argument, return the value of that option. Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of what limits and options are supported. +.\" METHOD: marktrusted .TP -\fBinterp marktrusted\fR \fIpath\fR +\fBinterp marktrusted\fI path\fR . Marks the interpreter identified by \fIpath\fR as trusted. Does not expose the hidden commands. This command can only be invoked from a trusted interpreter. The command has no effect if the interpreter identified by \fIpath\fR is already trusted. +.\" METHOD: recursionlimit .TP -\fBinterp\fR \fBrecursionlimit\fR \fIpath\fR ?\fInewlimit\fR? +\fBinterp recursionlimit\fI path\fR ?\fInewlimit\fR? . Returns the maximum allowable nesting depth for the interpreter specified by \fIpath\fR. If \fInewlimit\fR is specified, @@ -358,8 +390,9 @@ may get stack overflows before reaching the limit set by the command. If this happens, see if there is a mechanism in your system for increasing the maximum size of the C stack. .RE +.\" METHOD: share .TP -\fBinterp\fR \fBshare\fR \fIsrcPath channelId destPath\fR +\fBinterp share\fI srcPath channelId destPath\fR . Causes the IO channel identified by \fIchannelId\fR to become shared between the interpreter identified by \fIsrcPath\fR and the interpreter @@ -368,18 +401,14 @@ on the IO channel. Both interpreters must close it to close the underlying IO channel; IO channels accessible in an interpreter are automatically closed when an interpreter is destroyed. +.\" METHOD: slaves .TP -\fBinterp\fR \fBchildren\fR ?\fIpath\fR? -. -Returns a Tcl list of the names of all the child interpreters associated -with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted, -the invoking interpreter is used. -.TP -\fBinterp\fR \fBslaves\fR ?\fIpath\fR? +\fBinterp slaves\fR ?\fIpath\fR? . Synonym for . \fBinterp\fR \fBchildren\fR ?\fIpath\fR? +.\" METHOD: target .TP -\fBinterp\fR \fBtarget\fR \fIpath alias\fR +\fBinterp target\fI path alias\fR . Returns a Tcl list describing the target interpreter for an alias. The alias is specified with an interpreter path and source command name, just @@ -389,8 +418,9 @@ If the target interpreter for the alias is the invoking interpreter then an empty list is returned. If the target interpreter for the alias is not the invoking interpreter or one of its descendants then an error is generated. The target command does not have to be defined at the time of this invocation. +.\" METHOD: transfer .TP -\fBinterp\fR \fBtransfer\fR \fIsrcPath channelId destPath\fR +\fBinterp transfer\fI srcPath channelId destPath\fR . Causes the IO channel identified by \fIchannelId\fR to become available in the interpreter identified by \fIdestPath\fR and unavailable in the @@ -410,6 +440,7 @@ general form: \fIChild\fR is the name of the interpreter, and \fIcommand\fR and the \fIarg\fRs determine the exact behavior of the command. The valid forms of this command are: +.\" METHOD: aliases .TP \fIchild \fBaliases\fR . @@ -417,6 +448,7 @@ Returns a Tcl list whose elements are the tokens of all the aliases in \fIchild\fR. The tokens correspond to the values returned when the aliases were created (which may not be the same as the current names of the commands). +.\" METHOD: alias .TP \fIchild \fBalias \fIsrcToken\fR . @@ -444,6 +476,7 @@ See \fBALIAS INVOCATION\fR below for details. The command returns a token that uniquely identifies the command created \fIsrcCmd\fR, even if the command is renamed afterwards. The token may but does not have to be equal to \fIsrcCmd\fR. +.\" METHOD: bgerror .TP \fIchild \fBbgerror\fR ?\fIcmdPrefix\fR? . @@ -453,6 +486,7 @@ absent, the current background exception handler is returned, and if it is present, it is a list of words (of minimum length one) that describes what to set the interpreter's background exception handler to. See the \fBBACKGROUND EXCEPTION HANDLING\fR section for more details. +.\" METHOD: eval .TP \fIchild \fBeval \fIarg \fR?\fIarg ..\fR? . @@ -462,11 +496,15 @@ the resulting string as a Tcl script in \fIchild\fR. The result of this evaluation (including all \fBreturn\fR options, such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an error occurs) is returned to the invoking interpreter. +.RS +.PP Note that the script will be executed in the current context stack frame of \fIchild\fR; this is so that the implementations (in a parent interpreter) of aliases in a child interpreter can execute scripts in the child that find out information about the child's current state and stack frame. +.RE +.\" METHOD: expose .TP \fIchild \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR? . @@ -477,6 +515,7 @@ in \fIchild\fR. If an exposed command with the targeted name already exists, this command fails. For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. +.\" METHOD: hide .TP \fIchild \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR? . @@ -492,10 +531,12 @@ namespace even if the current namespace is not the global one. This prevents children from fooling a parent interpreter into hiding the wrong command, by making the current namespace be different from the global one. For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. +.\" METHOD: hidden .TP \fIchild \fBhidden\fR . Returns a list of the names of all hidden commands in \fIchild\fR. +.\" METHOD: invokehidden .TP \fIchild \fBinvokehidden\fR ?\fI\-option ...\fR? \fIhiddenName \fR?\fIarg ..\fR? . @@ -514,16 +555,21 @@ The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a character, and is otherwise unnecessary. If both the \fB\-namespace\fR and \fB\-global\fR flags are given, the \fB\-namespace\fR flag is ignored. +.RS +.PP Note that the hidden command will be executed (by default) in the current context stack frame of \fIchild\fR. -For more details on hidden commands, -see \fBHIDDEN COMMANDS\fR, below. +.PP +For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. +.RE +.\" METHOD: issafe .TP \fIchild \fBissafe\fR . -Returns \fB1\fR if the child interpreter is safe, \fB0\fR otherwise. +Returns \fB1\fR if the child interpreter is safe, \fB0\fR otherwise. +.\" METHOD: limit .TP -\fIchild \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR? +\fIchild \fBlimit\fI limitType\fR ?\fI\-option\fR? ?\fIvalue ...\fR? . Sets up, manipulates and queries the configuration of the resource limit \fIlimitType\fR for the child interpreter. If no \fI\-option\fR @@ -532,6 +578,7 @@ is specified, return the current configuration of the limit. If Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of what limits and options are supported. +.\" METHOD: marktrusted .TP \fIchild \fBmarktrusted\fR . @@ -539,8 +586,9 @@ Marks the child interpreter as trusted. Can only be invoked by a trusted interpreter. This command does not expose any hidden commands in the child interpreter. The command has no effect if the child is already trusted. +.\" METHOD: recursionlimit .TP -\fIchild\fR \fBrecursionlimit\fR ?\fInewlimit\fR? +\fIchild \fBrecursionlimit\fR ?\fInewlimit\fR? . Returns the maximum allowable nesting depth for the \fIchild\fR interpreter. If \fInewlimit\fR is specified, the recursion limit in \fIchild\fR will be @@ -793,6 +841,7 @@ catch and handle. Every limit has a number of options associated with it, some of which are common across all kinds of limits, and others of which are particular to the kind of limit. +.\" OPTION: -command .TP \fB\-command\fR . @@ -803,9 +852,13 @@ The callback may modify the limit on the interpreter if it wishes the limited interpreter to continue executing. If the callback generates an exception, it is reported through the background exception mechanism (see \fBBACKGROUND EXCEPTION HANDLING\fR). +.RS +.PP Note that the callbacks defined by one interpreter are completely isolated from the callbacks defined by another, and that the order in which those callbacks are called is undefined. +.RE +.\" OPTION: -granularity .TP \fB\-granularity\fR . @@ -814,6 +867,7 @@ points when the Tcl interpreter is in a consistent state where limit checking is possible) that the limit is actually checked. This allows the tuning of how frequently a limit is checked, and hence how often the limit-checking overhead (which may be substantial in the case of time limits) is incurred. +.\" OPTION: -milliseconds .TP \fB\-milliseconds\fR . @@ -821,6 +875,7 @@ This option specifies the number of milliseconds after the moment defined in the \fB\-seconds\fR option that the time limit will fire. It should only ever be specified in conjunction with the \fB\-seconds\fR option (whether it was set previously or is being set this invocation.) +.\" OPTION: -seconds .TP \fB\-seconds\fR . @@ -830,6 +885,7 @@ limit will be triggered at the start of the second unless specified at a sub-second level using the \fB\-milliseconds\fR option. This option may be the empty string, which indicates that a time limit is not set for the interpreter. +.\" OPTION: -value .TP \fB\-value\fR . @@ -849,14 +905,15 @@ necessary. .PP When an exception happens in a situation where it cannot be reported directly up the stack (e.g. when processing events in an \fBupdate\fR or \fBvwait\fR call) -the exception is instead reported through the background exception handling mechanism. -Every interpreter has a background exception handler registered; the default exception +the exception is instead reported through the background exception handling +mechanism. Every interpreter has a background exception handler registered; +the default exception handler arranges for the \fBbgerror\fR command in the interpreter's global namespace to be called, but other exception handlers may be installed and process background exceptions in substantially different ways. .PP -A background exception handler consists of a non-empty list of words to which will -be appended two further words at invocation time. The first word will be the +A background exception handler consists of a non-empty list of words to which +will be appended two further words at invocation time. The first word will be the interpreter result at time of the exception, typically an error message, and the second will be the dictionary of return options at the time of the exception. These are the same values that \fBcatch\fR can capture @@ -904,7 +961,8 @@ set i [\fBinterp create\fR] } .CE .SH "SEE ALSO" -bgerror(n), load(n), safe(n), Tcl_CreateChild(3), Tcl_Eval(3), Tcl_BackgroundException(3) +bgerror(n), load(n), safe(n), +Tcl_CreateChild(3), Tcl_Eval(3), Tcl_BackgroundException(3) .SH KEYWORDS alias, parent interpreter, safe interpreter, child interpreter '\"Local Variables: @@ -122,7 +122,7 @@ use this when you know what you are doing, you will not get a nice error message when something is wrong with the loaded library. .SH "PORTABILITY ISSUES" .TP -\fBWindows\fR\0\0\0\0\0 +\fBWindows\fR . When a load fails with .QW "library not found" diff --git a/doc/lrange.n b/doc/lrange.n index 38c4abf..8dac91f 100644 --- a/doc/lrange.n +++ b/doc/lrange.n @@ -29,7 +29,8 @@ If \fIlast\fR is greater than or equal to the number of elements in the list, then it is treated as if it were \fBend\fR. If \fIfirst\fR is greater than \fIlast\fR then an empty string is returned. -Note: +.PP +Note that .QW "\fBlrange \fIlist first first\fR" does not always produce the same result as .QW "\fBlindex \fIlist first\fR" diff --git a/doc/lrepeat.n b/doc/lrepeat.n index cd672db..8e4cc41 100644 --- a/doc/lrepeat.n +++ b/doc/lrepeat.n @@ -18,7 +18,9 @@ lrepeat \- Build a list by repeating elements The \fBlrepeat\fR command creates a list of size \fIcount * number of elements\fR by repeating \fIcount\fR times the sequence of elements \fIelement ...\fR. \fIcount\fR must be a non-negative integer, -\fIelement\fR can be any Tcl value. Note that \fBlrepeat 1 element ...\fR +\fIelement\fR can be any Tcl value. +.PP +Note that \fBlrepeat 1 element ...\fR is identical to \fBlist element ...\fR. .SH EXAMPLES .CS diff --git a/doc/lsearch.n b/doc/lsearch.n index dc6d1f7..20d497f 100644 --- a/doc/lsearch.n +++ b/doc/lsearch.n @@ -31,22 +31,26 @@ indicates how the elements of the list are to be matched against If all matching style options are omitted, the default matching style is \fB\-glob\fR. If more than one matching style is specified, the last matching style given takes precedence. +.\" OPTION: -exact .TP \fB\-exact\fR . \fIPattern\fR is a literal string that is compared for exact equality against each list element. +.\" OPTION: -glob .TP \fB\-glob\fR . \fIPattern\fR is a glob-style pattern which is matched against each list element using the same rules as the \fBstring match\fR command. +.\" OPTION: -regexp .TP \fB\-regexp\fR . \fIPattern\fR is treated as a regular expression and matched against each list element using the rules described in the \fBre_syntax\fR reference page. +.\" OPTION: -sorted .TP \fB\-sorted\fR . @@ -60,6 +64,7 @@ is treated exactly like \fB\-exact\fR when either \fB\-all\fR or .SS "GENERAL MODIFIER OPTIONS" .PP These options may be given with all matching styles. +.\" OPTION: -all .TP \fB\-all\fR . @@ -67,17 +72,20 @@ Changes the result to be the list of all matching indices (or all matching values if \fB\-inline\fR is specified as well.) If indices are returned, the indices will be in numeric order. If values are returned, the order of the values will be the order of those values within the input \fIlist\fR. +.\" OPTION: -inline .TP \fB\-inline\fR . The matching value is returned instead of its index (or an empty string if no value matches.) If \fB\-all\fR is also specified, then the result of the command is the list of all values that matched. +.\" OPTION: -not .TP \fB\-not\fR . This negates the sense of the match, returning the index of the first non-matching value in the list. +.\" OPTION: -start .TP \fB\-start\fR\0\fIindex\fR . @@ -91,11 +99,13 @@ These options describe how to interpret the items in the list being searched. They are only meaningful when used with the \fB\-exact\fR and \fB\-sorted\fR options. If more than one is specified, the last one takes precedence. The default is \fB\-ascii\fR. +.\" OPTION: -ascii .TP \fB\-ascii\fR . The list elements are to be examined as Unicode strings (the name is for backward-compatibility reasons.) +.\" OPTION: -dictionary .TP \fB\-dictionary\fR . @@ -104,16 +114,19 @@ comparisons (see \fBlsort\fR for a fuller description). Note that this only makes a meaningful difference from the \fB\-ascii\fR option when the \fB\-sorted\fR option is given, because values are only dictionary-equal when exactly equal. +.\" OPTION: -integer .TP \fB\-integer\fR . The list elements are to be compared as integers. +.\" OPTION: -nocase .TP \fB\-nocase\fR . Causes comparisons to be handled in a case-insensitive manner. Has no effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or \fB\-real\fR options. +.\" OPTION: -real .TP \fB\-real\fR . @@ -123,18 +136,22 @@ The list elements are to be compared as floating-point values. These options (only meaningful with the \fB\-sorted\fR option) specify how the list is sorted. If more than one is given, the last one takes precedence. The default option is \fB\-increasing\fR. +.\" OPTION: -decreasing .TP \fB\-decreasing\fR . The list elements are sorted in decreasing order. This option is only meaningful when used with \fB\-sorted\fR. +.\" OPTION: -increasing .TP \fB\-increasing\fR . The list elements are sorted in increasing order. This option is only meaningful when used with \fB\-sorted\fR. +.\" OPTION: -bisect .TP \fB\-bisect\fR +. Inexact search when the list elements are in sorted order. For an increasing list the last index where the element is less than or equal to the pattern is returned. For a decreasing list the last index where the element is greater @@ -146,6 +163,7 @@ or \fB\-not\fR. .PP These options are used to search lists of lists. They may be used with any other options. +.\" OPTION: -stride .TP \fB\-stride\0\fIstrideLength\fR . @@ -159,6 +177,7 @@ index always points to the first element in a group. The list length must be an integer multiple of \fIstrideLength\fR, which in turn must be at least 1. A \fIstrideLength\fR of 1 is the default and indicates no grouping. +.\" OPTION: -index .TP \fB\-index\fR\0\fIindexList\fR . @@ -166,6 +185,7 @@ This option is designed for use when searching within nested lists. The \fIindexList\fR argument gives a path of indices (much as might be used with the \fBlindex\fR or \fBlset\fR commands) within each element to allow the location of the term being matched against. +.\" OPTION: -subindices .TP \fB\-subindices\fR . diff --git a/doc/lsort.n b/doc/lsort.n index 1695ea8..4e4f720 100644 --- a/doc/lsort.n +++ b/doc/lsort.n @@ -20,18 +20,20 @@ lsort \- Sort the elements of a list .PP This command sorts the elements of \fIlist\fR, returning a new list in sorted order. The implementation of the \fBlsort\fR command -uses the merge\-sort algorithm which is a stable sort that has O(n log +uses the merge-sort algorithm which is a stable sort that has O(n log n) performance characteristics. .PP By default ASCII sorting is used with the result returned in increasing order. However, any of the following options may be specified before \fIlist\fR to control the sorting process (unique abbreviations are accepted): +.\" OPTION: -ascii .TP \fB\-ascii\fR . Use string comparison with Unicode code-point collation order (the name is for backward-compatibility reasons.) This is the default. +.\" OPTION: -dictionary .TP \fB\-dictionary\fR . @@ -42,14 +44,17 @@ not characters. For example, in \fB\-dictionary\fR mode, \fBbigBoy\fR sorts between \fBbigbang\fR and \fBbigboy\fR, and \fBx10y\fR sorts between \fBx9y\fR and \fBx11y\fR. Overrides the \fB\-nocase\fR option. +.\" OPTION: -integer .TP \fB\-integer\fR . Convert list elements to integers and use integer comparison. +.\" OPTION: -real .TP \fB\-real\fR . Convert list elements to floating-point values and use floating comparison. +.\" OPTION: -command .TP \fB\-command\0\fIcommand\fR . @@ -60,22 +65,26 @@ arguments. The script should return an integer less than, equal to, or greater than zero if the first element is to be considered less than, equal to, or greater than the second, respectively. +.\" OPTION: -increasing .TP \fB\-increasing\fR . Sort the list in increasing order .PQ smallest "items first" . This is the default. +.\" OPTION: -decreasing .TP \fB\-decreasing\fR . Sort the list in decreasing order .PQ largest "items first" . +.\" OPTION: -indices .TP \fB\-indices\fR . Return a list of indices into \fIlist\fR in sorted order instead of the values themselves. +.\" OPTION: -index .TP \fB\-index\0\fIindexList\fR . @@ -119,6 +128,7 @@ returns \fB{{d e m o} 34512} {{b i g} 12345} {{c o d e} 54321}\fR This option is much more efficient than using \fB\-command\fR to achieve the same effect. .RE +.\" OPTION: -stride .TP \fB\-stride\0\fIstrideLength\fR . @@ -136,7 +146,7 @@ in turn must be at least 2. For example, .PP .CS -\fBlsort\fR \-stride 2 {carrot 10 apple 50 banana 25} +\fBlsort\fR -stride 2 {carrot 10 apple 50 banana 25} .CE .PP returns @@ -144,18 +154,20 @@ returns and .PP .CS -\fBlsort\fR \-stride 2 \-index 1 \-integer {carrot 10 apple 50 banana 25} +\fBlsort\fR -stride 2 -index 1 -integer {carrot 10 apple 50 banana 25} .CE .PP returns .QW "carrot 10 banana 25 apple 50" . .RE +.\" OPTION: -nocase .TP \fB\-nocase\fR . Causes comparisons to be handled in a case-insensitive manner. Has no effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or \fB\-real\fR options. +.\" OPTION: -unique .TP \fB\-unique\fR . @@ -234,7 +246,7 @@ Sorting using striding and multiple indices: .PP .CS \fI%\fR # Note the first index value is relative to the group -\fI%\fR \fBlsort\fR \-stride 3 \-index {0 1} \e +\fI%\fR \fBlsort\fR -stride 3 -index {0 1} \e {{Bob Smith} 25 Audi {Jane Doe} 40 Ford} {{Jane Doe} 40 Ford {Bob Smith} 25 Audi} .CE diff --git a/doc/msgcat.n b/doc/msgcat.n index c39dc87..9d82688 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -11,6 +11,7 @@ .SH NAME msgcat \- Tcl message catalog .SH SYNOPSIS +.nf \fBpackage require tcl 8.7\fR .sp \fBpackage require msgcat 1.7\fR @@ -20,7 +21,7 @@ msgcat \- Tcl message catalog \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR? .sp .VS "TIP 412" -\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? \fIsrc-string\fR +\fB::msgcat::mcexists\fR ?\fB\-exactnamespace\fR? ?\fB\-exactlocale\fR? \fIsrc-string\fR .VE "TIP 412" .sp .VS "TIP 490" @@ -52,7 +53,7 @@ msgcat \- Tcl message catalog .VS "TIP 412" \fB::msgcat::mcpackagelocale subcommand\fR ?\fIlocale\fR? .sp -\fB::msgcat::mcpackageconfig subcommand\fR \fIoption\fR ?\fIvalue\fR? +\fB::msgcat::mcpackageconfig subcommand\fI option\fR ?\fIvalue\fR? .sp \fB::msgcat::mcforgetpackage\fR .VE "TIP 412" @@ -60,6 +61,7 @@ msgcat \- Tcl message catalog .VS "TIP 499" \fB::msgcat::mcutil subcommand\fR ?\fIlocale\fR? .VS "TIP 499" +.fi .BE .SH DESCRIPTION .PP @@ -73,20 +75,23 @@ the application source code. New languages or locales may be provided by adding a new file to the message catalog. .PP -\fBmsgcat\fR distinguishes packages by its namespace. -Each package has its own message catalog and configuration settings in \fBmsgcat\fR. +\fBmsgcat\fR distinguishes packages by its namespace. Each package has +its own message catalog and configuration settings in \fBmsgcat\fR. .PP -A \fIlocale\fR is a specification string describing a user language like \fBde_ch\fR for Swiss German. -In \fBmsgcat\fR, there is a global locale initialized by the system locale of the current system. -Each package may decide to use the global locale or to use a package specific locale. +A \fIlocale\fR is a specification string describing a user language like +\fBde_ch\fR for Swiss German. In \fBmsgcat\fR, there is a global locale +initialized by the system locale of the current system. Each package may +decide to use the global locale or to use a package specific locale. .PP -The global locale may be changed on demand, for example by a user initiated language change or within a multi user application like a web server. +The global locale may be changed on demand, for example by a user initiated +language change or within a multi user application like a web server. .PP .VS tip490 Object oriented programming is supported by the use of a package namespace. .VE tip490 .PP .SH COMMANDS +.\" COMMAND: mc .TP \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? . @@ -110,17 +115,20 @@ use the result. If an application is written for a single language in this fashion, then it is easy to add support for additional languages later simply by defining new message catalog entries. .RE -.VS "TIP 490" +.\" COMMAND: mcn .TP -\fB::msgcat::mcn \fInamespace\fR \fIsrc-string\fR ?\fIarg arg ...\fR? -. -Like \fB::msgcat::mc\fR, but with the message namespace specified as first argument. +\fB::msgcat::mcn \fInamespace src-string\fR ?\fIarg arg ...\fR? +.VS "TIP 490" +Like \fB::msgcat::mc\fR, but with the message namespace specified as first +argument. .PP .RS -\fBmcn\fR may be used for cases where the package namespace is not the namespace of the caller. -An example is shown within the description of the command \fB::msgcat::mcpackagenamespaceget\fR below. +\fBmcn\fR may be used for cases where the package namespace is not the +namespace of the caller. An example is shown within the description of the +command \fB::msgcat::mcpackagenamespaceget\fR below. .RE -.PP +.VE +.\" COMMAND: mcmax .TP \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR? . @@ -128,33 +136,37 @@ Given several source strings, \fB::msgcat::mcmax\fR returns the length of the longest translated string. This is useful when designing localized GUIs, which may require that all buttons, for example, be a fixed width (which will be the width of the widest button). -.VS "TIP 412" +.\" COMMAND: mcexists .TP -\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? ?\fB-namespace\fR \fInamespace\fR? \fIsrc-string\fR -. +\fB::msgcat::mcexists\fR ?\fB\-exactnamespace\fR? ?\fB\-exactlocale\fR? ?\fB\-namespace\fI namespace\fR? \fIsrc-string\fR +.VS "TIP 412" Return true, if there is a translation for the given \fIsrc-string\fR. .PP .RS -The search may be limited by the option \fB\-exactnamespace\fR to only check the current namespace and not any parent namespaces. +The search may be limited by the option \fB\-exactnamespace\fR to only check +the current namespace and not any parent namespaces. .PP -It may also be limited by the option \fB\-exactlocale\fR to only check the first prefered locale (e.g. first element returned by \fB::msgcat::mcpreferences\fR if global locale is used). +It may also be limited by the option \fB\-exactlocale\fR to only check the +first prefered locale (e.g. first element returned by +\fB::msgcat::mcpreferences\fR if global locale is used). .PP .VE "TIP 412" .VS "TIP 490" -An explicit package namespace may be specified by the option \fB-namespace\fR. +An explicit package namespace may be specified by the option \fB\-namespace\fR. The namespace of the caller is used if not explicitly specified. .RE .PP .VE "TIP 490" -.VS "TIP 490" +.\" COMMAND: mcpackagenamespaceget .TP \fB::msgcat::mcpackagenamespaceget\fR -. -Return the package namespace of the caller. -This command handles all cases described in section \fBOBJECT ORIENTED PROGRAMMING\fR. +.VS "TIP 490" +Return the package namespace of the caller. This command handles all cases +described in section \fBOBJECT ORIENTED PROGRAMMING\fR. .PP .RS -Example usage is a tooltip package, which saves the caller package namespace to update the translation each time the tooltip is shown: +Example usage is a tooltip package, which saves the caller package namespace +to update the translation each time the tooltip is shown: .CS proc ::tooltip::tooltip {widget message} { ... @@ -172,19 +184,24 @@ proc ::tooltip::show {widget messagenamespace message} { .RE .PP .VE "TIP 490" +.\" COMMAND: mclocale .TP \fB::msgcat::mclocale \fR?\fInewLocale\fR? . -If \fInewLocale\fR is omitted, the current locale is returned, otherwise the current locale -is set to \fInewLocale\fR. +If \fInewLocale\fR is omitted, the current locale is returned, otherwise the +current locale is set to \fInewLocale\fR. .PP .RS -If the new locale is set to \fInewLocale\fR, the corresponding preferences are calculated and set. -For example, if the current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR returns \fB{en_us_funky en_us en {}}\fR. +If the new locale is set to \fInewLocale\fR, the corresponding preferences +are calculated and set. +For example, if the current locale is en_US_funky, then +\fB::msgcat::mcpreferences\fR returns \fB{en_us_funky en_us en {}}\fR. .PP -The same result may be acheved by \fB::msgcat::mcpreferences\fR {*}[\fB::msgcat::mcutil getpreferences\fR \fInewLocale\fR]. +The same result may be achieved by \fB::msgcat::mcpreferences\fR +{*}[\fB::msgcat::mcutil getpreferences\fI newLocale\fR]. .PP -The current locale is always the first element of the list returned by \fBmcpreferences\fR. +The current locale is always the first element of the list returned by +\fBmcpreferences\fR. .PP msgcat stores and compares the locale in a case-insensitive manner, and returns locales in lowercase. @@ -197,6 +214,7 @@ If the locale is set, the preference list of locales is evaluated. Locales in this list are loaded now, if not jet loaded. .VE "TIP 412" .RE +.\" COMMAND: mcpreferences .TP \fB::msgcat::mcpreferences\fR ?\fIlocale preference\fR? ... . @@ -207,34 +225,40 @@ The list is ordered from most specific to least preference. .VS "TIP 499" .RS A set of locale preferences may be given to set the list of locale preferences. -The current locale is also set, which is the first element of the locale preferences list. +The current locale is also set, which is the first element of the locale +preferences list. .PP Locale preferences are loaded now, if not jet loaded. .PP -As an example, the user may prefer French or English text. This may be configured by: +As an example, the user may prefer French or English text. This may be +configured by: .CS ::msgcat::mcpreferences fr en {} .CE .RE .PP -.VS "TIP 499" +.\" COMMAND: mcloadedlocales .TP \fB::msgcat::mcloadedlocales subcommand\fR ?\fIlocale\fR? -. -This group of commands manage the list of loaded locales for packages not setting a package locale. +.VS "TIP 499" +This group of commands manage the list of loaded locales for packages not +setting a package locale. .PP .RS The subcommand \fBloaded\fR returns the list of currently loaded locales. .PP -The subcommand \fBclear\fR removes all locales and their data, which are not in the current preference list. +The subcommand \fBclear\fR removes all locales and their data, which are not in +the current preference list. .RE +.VE +.\" COMMAND: mcload .TP \fB::msgcat::mcload \fIdirname\fR -. .VS "TIP 412" Searches the specified directory for files that match the language specifications returned by \fB::msgcat::mcloadedlocales loaded\fR -(or \fBmsgcat::mcpackagelocale preferences\fR if a package locale is set) (note that these are all lowercase), extended by the file extension +(or \fBmsgcat::mcpackagelocale preferences\fR if a package locale is set) +(note that these are all lowercase), extended by the file extension .QW .msg . Each matching file is read in order, assuming a UTF-8 encoding. The file contents are @@ -245,9 +269,12 @@ evaluation. The number of message files which matched the specification and were loaded is returned. .RS .PP -In addition, the given folder is stored in the \fBmsgcat\fR package configuration option \fImcfolder\fR to eventually load message catalog files required by a locale change. +In addition, the given folder is stored in the \fBmsgcat\fR package +configuration option \fImcfolder\fR to eventually load message catalog +files required by a locale change. .VE "TIP 412" .RE +.\" COMMAND: mcset .TP \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? . @@ -255,6 +282,7 @@ Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the specified \fIlocale\fR and the current namespace. If \fItranslate-string\fR is not specified, \fIsrc-string\fR is used for both. The function returns \fItranslate-string\fR. +.\" COMMAND: mcmset .TP \fB::msgcat::mcmset \fIlocale src-trans-list\fR . @@ -266,15 +294,19 @@ the form {\fIsrc-string translate-string\fR ?\fIsrc-string translate-string ...\fR?} \fB::msgcat::mcmset\fR can be significantly faster than multiple invocations of \fB::msgcat::mcset\fR. The function returns the number of translations set. +.\" COMMAND: mcflset .TP \fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR? +. Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the current namespace for the locale implied by the name of the message catalog being loaded via \fB::msgcat::mcload\fR. If \fItranslate-string\fR is not specified, \fIsrc-string\fR is used for both. The function returns \fItranslate-string\fR. +.\" COMMAND: mcflmset .TP \fB::msgcat::mcflmset \fIsrc-trans-list\fR +. Sets the translation for multiple source strings in \fIsrc-trans-list\fR in the current namespace for the locale implied by the name of the message catalog being loaded via \fB::msgcat::mcload\fR. \fIsrc-trans-list\fR must @@ -282,6 +314,7 @@ have an even number of elements and is in the form {\fIsrc-string translate-string\fR ?\fIsrc-string translate-string ...\fR?} \fB::msgcat::mcflmset\fR can be significantly faster than multiple invocations of \fB::msgcat::mcflset\fR. The function returns the number of translations set. +.\" COMMAND: mcunknown .TP \fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR? . @@ -298,28 +331,37 @@ to \fB::msgcat::mc\fR. .VS "TIP 412" .RS .PP -Note that this routine is only called if the concerned package did not set a package locale unknown command name. +Note that this routine is only called if the concerned package did not set a +package locale unknown command name. .RE +.\" COMMAND: mcforgetpackage .TP \fB::msgcat::mcforgetpackage\fR . -The calling package clears all its state within the \fBmsgcat\fR package including all settings and translations. +The calling package clears all its state within the \fBmsgcat\fR package +including all settings and translations. .VE "TIP 412" .PP +.\" COMMAND: mcutil +.\" METHOD: getpreferences .VS "TIP 499" .TP -\fB::msgcat::mcutil getpreferences\fR \fIlocale\fR +\fB::msgcat::mcutil getpreferences\fI locale\fR . -Return the preferences list of the given locale as described in section \fBLOCALE SPECIFICATION\fR. -An example is the composition of a preference list for the bilingual region "Biel/Bienne" as a concatenation of swiss german and swiss french: +Return the preferences list of the given locale as described in the section +\fBLOCALE SPECIFICATION\fR. +An example is the composition of a preference list for the bilingual region +"Biel/Bienne" as a concatenation of swiss german and swiss french: .CS % concat [lrange [msgcat::mcutil getpreferences fr_CH] 0 end-1] [msgcat::mcutil getpreferences de_CH] fr_ch fr de_ch de {} .CE +.\" METHOD: getsystemlocale .TP \fB::msgcat::mcutil getsystemlocale\fR . -The system locale is returned as described by the section \fBLOCALE SPECIFICATION\fR. +The system locale is returned as described by the section +\fBLOCALE SPECIFICATION\fR. .VE "TIP 499" .PP .SH "LOCALE SPECIFICATION" @@ -360,7 +402,7 @@ msgcat will attempt to extract locale information from the registry. From Windows Vista on, the RFC4747 locale name "lang-script-country-options" is transformed to the locale as "lang_country_script" (Example: sr-Latn-CS -> sr_cs_latin). For Windows XP, the language id is -transformed analoguously (Example: 0c1a -> sr_yu_cyrillic). +transformed analogously (Example: 0c1a -> sr_yu_cyrillic). If all these attempts to discover an initial locale from the user's environment fail, msgcat defaults to an initial locale of .QW C . @@ -533,58 +575,73 @@ A package using \fBmsgcat\fR may choose to use its own package private locale and its own set of loaded locales, independent to the global locale set by \fB::msgcat::mclocale\fR. .PP -This allows a package to change its locale without causing any locales load or removal in other packages and not to invoke the global locale change callback (see below). +This allows a package to change its locale without causing any locales load or +removal in other packages and not to invoke the global locale change callback +(see below). .PP This action is controled by the following ensemble: +.\" COMMAND: mcpackagelocale +.\" METHOD: set .TP \fB::msgcat::mcpackagelocale set\fR ?\fIlocale\fR? . Set or change a package private locale. -The package private locale is set to the given \fIlocale\fR if the \fIlocale\fR is given. -If the option \fIlocale\fR is not given, the package is set to package private locale mode, but no locale is changed (e.g. if the global locale was valid for the package before, it is copied to the package private locale). +The package private locale is set to the given \fIlocale\fR if the \fIlocale\fR +is given. If the option \fIlocale\fR is not given, the package is set to package +private locale mode, but no locale is changed (e.g. if the global locale was +valid for the package before, it is copied to the package private locale). .PP .RS This command may cause the load of locales. .RE +.\" METHOD: get .TP \fB::msgcat::mcpackagelocale get\fR . -Return the package private locale or the global locale, if no package private locale is set. +Return the package private locale or the global locale, if no package private +locale is set. +.\" METHOD: preferences .TP \fB::msgcat::mcpackagelocale preferences\fR ?\fIlocale preference\fR? ... . -With no parameters, return the package private preferences or the global preferences, -if no package private locale is set. -The package locale state (set or not) is not changed (in contrast to the command \fB::msgcat::mcpackagelocale set\fR). +With no parameters, return the package private preferences or the global +preferences, if no package private locale is set. +The package locale state (set or not) is not changed (in contrast to the +command \fB::msgcat::mcpackagelocale set\fR). .PP .RS .VS "TIP 499" -If a set of locale preferences is given, it is set as package locale preference list. -The package locale is set to the first element of the preference list. +If a set of locale preferences is given, it is set as package locale preference +list. The package locale is set to the first element of the preference list. A package locale is activated, if it was not set so far. .PP Locale preferences are loaded now for the package, if not jet loaded. .VE "TIP 499" .RE .PP +.\" METHOD: loaded .TP \fB::msgcat::mcpackagelocale loaded\fR . Return the list of locales loaded for this package. +.\" METHOD: isset .TP \fB::msgcat::mcpackagelocale isset\fR . Returns true, if a package private locale is set. +.\" METHOD: unset .TP \fB::msgcat::mcpackagelocale unset\fR . -Unset the package private locale and use the globale locale. +Unset the package private locale and use the global locale. Load and remove locales to adjust the list of loaded locales for the package to the global loaded locales list. +.\" METHOD: present .TP -\fB::msgcat::mcpackagelocale present\fR \fIlocale\fR +\fB::msgcat::mcpackagelocale present\fI locale\fR . Returns true, if the given locale is loaded for the package. +.\" METHOD: clear .TP \fB::msgcat::mcpackagelocale clear\fR . @@ -594,24 +651,31 @@ Clear any loaded locales of the package not present in the package preferences. .PP Each package using msgcat has a set of options within \fBmsgcat\fR. The package options are described in the next sectionPackage options. -Each package option may be set or unset individually using the following ensemble: +Each package option may be set or unset individually using the following +ensemble: +.\" COMMAND: mcpackageconfig +.\" METHOD: get .TP -\fB::msgcat::mcpackageconfig get\fR \fIoption\fR +\fB::msgcat::mcpackageconfig get\fI option\fR . Return the current value of the given \fIoption\fR. This call returns an error if the option is not set for the package. +.\" METHOD: isset .TP -\fB::msgcat::mcpackageconfig isset\fR \fIoption\fR +\fB::msgcat::mcpackageconfig isset\fI option\fR . Returns 1, if the given \fIoption\fR is set for the package, 0 otherwise. +.\" METHOD: set .TP -\fB::msgcat::mcpackageconfig set\fR \fIoption\fR \fIvalue\fR +\fB::msgcat::mcpackageconfig set\fI option value\fR . Set the given \fIoption\fR to the given \fIvalue\fR. This may invoke additional actions in dependency of the \fIoption\fR. -The return value is 0 or the number of loaded packages for the option \fBmcfolder\fR. +The return value is 0 or the number of loaded packages for the option +\fBmcfolder\fR. +.\" METHOD: unset .TP -\fB::msgcat::mcpackageconfig unset\fR \fIoption\fR +\fB::msgcat::mcpackageconfig unset\fI option\fR . Unsets the given \fIoption\fR for the package. No action is taken if the \fIoption\fR is not set for the package. @@ -622,30 +686,40 @@ The following package options are available for each package: .TP \fBmcfolder\fR . -This is the message folder of the package. This option is set by mcload and by the subcommand set. Both are identical and both return the number of loaded message catalog files. +This is the message folder of the package. This option is set by mcload and by +the subcommand set. Both are identical and both return the number of loaded +message catalog files. .RS .PP -Setting or changing this value will load all locales contained in the preferences valid for the package. This implies also to invoke any set loadcmd (see below). +Setting or changing this value will load all locales contained in the +preferences valid for the package. This implies also to invoke any set +loadcmd (see below). .PP Unsetting this value will disable message file load for the package. .RE .TP \fBloadcmd\fR . -This callback is invoked before a set of message catalog files are loaded for the package which has this property set. +This callback is invoked before a set of message catalog files are loaded for +the package which has this property set. .PP .RS -This callback may be used to do any preparation work for message file load or to get the message data from another source like a data base. In this case, no message files are used (mcfolder is unset). +This callback may be used to do any preparation work for message file load or +to get the message data from another source like a data base. In this case, no +message files are used (mcfolder is unset). .PP See section \fBcallback invocation\fR below. The parameter list appended to this callback is the list of locales to load. .PP -If this callback is changed, it is called with the preferences valid for the package. +If this callback is changed, it is called with the preferences valid for the +package. .RE .TP \fBchangecmd\fR . -This callback is invoked when a default local change was performed. Its purpose is to allow a package to update any dependency on the default locale like showing the GUI in another language. +This callback is invoked when a default local change was performed. Its +purpose is to allow a package to update any dependency on the default locale +like showing the GUI in another language. .PP .RS See the callback invocation section below. @@ -655,15 +729,19 @@ The registered callbacks are invoked in no particular order. .TP \fBunknowncmd\fR . -Use a package locale mcunknown procedure instead of the standard version supplied by the msgcat package (msgcat::mcunknown). +Use a package locale mcunknown procedure instead of the standard version +supplied by the msgcat package (\fBmsgcat::mcunknown\fR). .PP .RS -The called procedure must return the formatted message which will finally be returned by msgcat::mc. +The called procedure must return the formatted message which will finally be +returned by \fBmsgcat::mc\fR. .PP -A generic unknown handler is used if set to the empty string. This consists in returning the key if no arguments are given. With given arguments, format is used to process the arguments. +A generic unknown handler is used if set to the empty string. This consists of +returning the key if no arguments are given. With given arguments, the +\fBformat\fR command is used to process the arguments. .PP See section \fBcallback invocation\fR below. -The appended arguments are identical to \fB::msgcat::mcunknown\fR. +The appended arguments are identical to \fBmsgcat::mcunknown\fR. .RE .SH "Callback invocation" A package may decide to register one or multiple callbacks, as described above. @@ -676,15 +754,20 @@ Callbacks are invoked, if: .PP 3. the registering namespace exists. .PP -If a called routine fails with an error, the \fBbgerror\fR routine for the interpreter is invoked after command completion. -Only exception is the callback \fBunknowncmd\fR, where an error causes the invoking \fBmc\fR-command to fail with that error. +If a called routine fails with an error, the \fBbgerror\fR routine for the +interpreter is invoked after command completion. +Only exception is the callback \fBunknowncmd\fR, where an error causes the +invoking \fBmc\fR-command to fail with that error. .PP .VS tip490 .SH "OBJECT ORIENTED PROGRAMMING" \fBmsgcat\fR supports packages implemented by object oriented programming. Objects and classes should be defined within a package namespace. .PP -There are 3 supported cases where package namespace sensitive commands of msgcat (\fBmc\fR, \fBmcexists\fR, \fBmcpackagelocale\fR, \fBmcforgetpackage\fR, \fBmcpackagenamespaceget\fR, \fBmcpackageconfig\fR, \fBmcset\fR and \fBmcmset\fR) may be called: +There are 3 supported cases where package namespace sensitive commands of msgcat +(\fBmc\fR, \fBmcexists\fR, \fBmcpackagelocale\fR, \fBmcforgetpackage\fR, +\fBmcpackagenamespaceget\fR, \fBmcpackageconfig\fR, \fBmcset\fR and \fBmcmset\fR) +may be called: .PP .TP \fB1) In class definition script\fR @@ -700,7 +783,8 @@ namespace eval ::N2 { .TP \fB2) method defined in a class\fR . -\fBmsgcat\fR command is called from a method in an object and the method is defined in a class. +\fBmsgcat\fR command is called from a method in an object and the method is +defined in a class. .CS namespace eval ::N3Class { mcload $dir/msgs @@ -727,8 +811,8 @@ namespace eval ::N4 { .PP .VE tip490 .SH EXAMPLES -Packages which display a GUI may update their widgets when the global locale changes. -To register to a callback, use: +Packages which display a GUI may update their widgets when the global locale +changes. To register to a callback, use: .CS namespace eval gui { msgcat::mcpackageconfig changecmd updateGUI @@ -742,7 +826,8 @@ fr % New locale is 'fr'. .CE .PP -If locales (or additional locales) are contained in another source like a data base, a package may use the load callback and not mcload: +If locales (or additional locales) are contained in another source like a +database, a package may use the load callback and not \fBmcload\fR: .CS namespace eval db { msgcat::mcpackageconfig loadcmd loadMessages @@ -757,10 +842,12 @@ namespace eval db { } .CE .PP -The \fBclock\fR command implementation uses \fBmsgcat\fR with a package locale to implement the command line parameter \fB-locale\fR. +The \fBclock\fR command implementation uses \fBmsgcat\fR with a package +locale to implement the command line parameter \fB\-locale\fR. Here are some sketches of the implementation: .PP -First, a package locale is initialized and the generic unknown function is desactivated: +First, a package locale is initialized and the generic unknown function is +deactivated: .CS msgcat::mcpackagelocale set msgcat::mcpackageconfig unknowncmd "" @@ -769,13 +856,15 @@ As an example, the user requires the week day in a certain locale as follows: .CS clock format [clock seconds] -format %A -locale fr .CE -\fBclock\fR sets the package locale to \fBfr\fR and looks for the day name as follows: +\fBclock\fR sets the package locale to \fBfr\fR and looks for the day name as +follows: .CS msgcat::mcpackagelocale set $locale return [lindex [msgcat::mc DAYS_OF_WEEK_FULL] $day] ### Returns "mercredi" .CE -Within \fBclock\fR, some message-catalog items are heavy in computation and thus are dynamically cached using: +Within \fBclock\fR, some message-catalog items are heavy in computation and +thus are dynamically cached using: .CS proc ::tcl::clock::LocalizeFormat { locale format } { set key FORMAT_$format @@ -794,7 +883,8 @@ The message catalog code was developed by Mark Harrison. .SH "SEE ALSO" format(n), scan(n), namespace(n), package(n), oo::class(n), oo::object .SH KEYWORDS -internationalization, i18n, localization, l10n, message, text, translation, class, object +internationalization, i18n, localization, l10n, message, text, translation, +class, object .\" Local Variables: .\" mode: nroff .\" End: @@ -35,9 +35,9 @@ defined by that object or class. .VE TIP500 .PP The object upon which the method is invoked via \fBmy\fR is the one that owns -the namespace that the \fBmy\fR command is contained in initially (\fBNB:\fR the link -remains if the command is renamed), which is the currently invoked object by -default. +the namespace that the \fBmy\fR command is contained in initially (\fBNB:\fR the +link remains if the command is renamed), which is the currently invoked object +by default. .VS TIP478 Similarly, the object on which the method is invoked via \fBmyclass\fR is the object that is the current class of the object that owns the namespace that diff --git a/doc/namespace.n b/doc/namespace.n index 4be0a3a..5b09890 100644 --- a/doc/namespace.n +++ b/doc/namespace.n @@ -272,8 +272,7 @@ For the \fIstring\fR \fB::foo::bar::x\fR, this command returns \fB::foo::bar\fR, and for \fB::\fR it returns an empty string. This command is the complement of the \fBnamespace tail\fR command. -Note that it does not check whether the -namespace names are, in fact, +It does not check whether the namespace names are, in fact, the names of currently defined namespaces. .TP \fBnamespace tail\fR \fIstring\fR @@ -527,14 +526,14 @@ about name resolution. For example, the command: .PP .CS -\fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR \-variable traceLevel} +\fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR -variable traceLevel} .CE .PP returns \fB::traceLevel\fR. On the other hand, the command, .PP .CS -\fBnamespace eval\fR Foo {\fBnamespace which\fR \-variable traceLevel} +\fBnamespace eval\fR Foo {\fBnamespace which\fR -variable traceLevel} .CE .PP returns \fB::Foo::traceLevel\fR. @@ -576,7 +575,7 @@ like BLT are contained in a namespace called \fBBlt\fR. Then you might access these commands like this: .PP .CS -Blt::graph .g \-background red +Blt::graph .g -background red Blt::table . .g 0,0 .CE .PP @@ -593,7 +592,7 @@ This adds all exported commands from the \fBBlt\fR namespace into the current namespace context, so you can write code like this: .PP .CS -graph .g \-background red +graph .g -background red table . .g 0,0 .CE .PP @@ -622,7 +621,7 @@ that have appeared in a namespace. In that case, you can use the \fB\-force\fR option, and existing commands will be silently overwritten: .PP .CS -\fBnamespace import\fR \-force Blt::graph Blt::table +\fBnamespace import\fR -force Blt::graph Blt::table .CE .PP If for some reason, you want to stop using the imported commands, @@ -771,6 +770,7 @@ the \fBuplevel\fR or \fBinfo level\fR commands. The following options, supported by the \fBnamespace ensemble create\fR and \fBnamespace ensemble configure\fR commands, control how an ensemble command behaves: +.\" OPTION: -map .TP \fB\-map\fR . @@ -786,12 +786,15 @@ will be from the local name of the subcommand to its fully-qualified name. Note that when this option is non-empty and the \fB\-subcommands\fR option is empty, the ensemble subcommand names will be exactly those words that have mappings in the dictionary. +.\" OPTION: -parameters .TP \fB\-parameters\fR +. This option gives a list of named arguments (the names being used during generation of error messages) that are passed by the caller of the ensemble between the name of the ensemble and the subcommand argument. By default, it is the empty list. +.\" OPTION: -prefixes .TP \fB\-prefixes\fR . @@ -799,6 +802,7 @@ This option (which is enabled by default) controls whether the ensemble command recognizes unambiguous prefixes of its subcommands. When turned off, the ensemble command requires exact matching of subcommand names. +.\" OPTION: -subcommands .TP \fB\-subcommands\fR . @@ -810,6 +814,7 @@ empty, the subcommands of the namespace will either be the keys of the dictionary listed in the \fB\-map\fR option or the exported commands of the linked namespace at the time of the invocation of the ensemble command. +.\" OPTION: -unknown .TP \fB\-unknown\fR . @@ -824,6 +829,7 @@ unable to determine how to implement a particular subcommand. See .PP The following extra option is allowed by \fBnamespace ensemble create\fR: +.\" OPTION: -command .TP \fB\-command\fR . @@ -835,6 +841,7 @@ command is invoked. .PP The following extra option is allowed by \fBnamespace ensemble configure\fR: +.\" OPTION: -namespace .TP \fB\-namespace\fR . @@ -34,10 +34,10 @@ chain. .PP The \fBnextto\fR command is the same as the \fBnext\fR command, except that it takes an additional \fIclass\fR argument that identifies a class whose -implementation of the current method chain (see \fBinfo object\fR \fBcall\fR) should -be used; the method implementation selected will be the one provided by the -given class, and it must refer to an existing non-filter invocation that lies -further along the chain than the current implementation. +implementation of the current method chain (see \fBinfo object\fR \fBcall\fR) +should be used; the method implementation selected will be the one provided by +the given class, and it must refer to an existing non-filter invocation that +lies further along the chain than the current implementation. .SH "THE METHOD CHAIN" .PP When a method of an object is invoked, things happen in several stages: @@ -32,35 +32,23 @@ conventions described in the \fBfilename\fR manual entry. The \fIaccess\fR argument, if present, indicates the way in which the file (or command pipeline) is to be accessed. In the first form \fIaccess\fR may have any of the following values: -.TP 15 -\fBr\fR -. +.IP \fBr\fR Open the file for reading only; the file must already exist. This is the default value if \fIaccess\fR is not specified. -.TP 15 -\fBr+\fR -. +.IP \fBr+\fR Open the file for both reading and writing; the file must already exist. -.TP 15 -\fBw\fR -. +.IP \fBw\fR Open the file for writing only. Truncate it if it exists. If it does not exist, create a new file. -.TP 15 -\fBw+\fR -. +.IP \fBw+\fR Open the file for reading and writing. Truncate it if it exists. If it does not exist, create a new file. -.TP 15 -\fBa\fR -. +.IP \fBa\fR Open the file for writing only. If the file does not exist, create a new empty file. Set the file pointer to the end of the file prior to each write. -.TP 15 -\fBa+\fR -. +.IP \fBa+\fR Open the file for reading and writing. If the file does not exist, create a new empty file. Set the initial access position to the end of the file. @@ -74,44 +62,26 @@ reading or writing of binary data. In the second form, \fIaccess\fR consists of a list of any of the following flags, most of which have the standard POSIX meanings. One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR. -.TP 15 -\fBRDONLY\fR -. +.IP \fBRDONLY\fR Open the file for reading only. -.TP 15 -\fBWRONLY\fR -. +.IP \fBWRONLY\fR Open the file for writing only. -.TP 15 -\fBRDWR\fR -. +.IP \fBRDWR\fR Open the file for both reading and writing. -.TP 15 -\fBAPPEND\fR -. +.IP \fBAPPEND\fR Set the file pointer to the end of the file prior to each write. -.TP 15 -\fBBINARY\fR -. +.IP \fBBINARY\fR Configure the opened channel with the \fB\-translation binary\fR option. -.TP 15 -\fBCREAT\fR -. +.IP \fBCREAT\fR Create the file if it does not already exist (without this flag it is an error for the file not to exist). -.TP 15 -\fBEXCL\fR -. +.IP \fBEXCL\fR If \fBCREAT\fR is also specified, an error is returned if the file already exists. -.TP 15 -\fBNOCTTY\fR -. +.IP \fBNOCTTY\fR If the file is a terminal device, this flag prevents the file from becoming the controlling terminal of the process. -.TP 15 -\fBNONBLOCK\fR -. +.IP \fBNONBLOCK\fR Prevents the process from blocking while opening the file, and possibly in subsequent I/O operations. The exact behavior of this flag is system- and device-dependent; its use is discouraged @@ -119,9 +89,7 @@ this flag is system- and device-dependent; its use is discouraged in nonblocking mode). For details refer to your system documentation on the \fBopen\fR system call's \fBO_NONBLOCK\fR flag. -.TP 15 -\fBTRUNC\fR -. +.IP \fBTRUNC\fR If the file exists it is truncated to zero length. .PP If a new file is created as part of opening it, \fIpermissions\fR @@ -133,6 +101,7 @@ conjunction with the process's file mode creation mask. When the file opened is an ordinary disk file, the \fBchan configure\fR and \fBfconfigure\fR commands can be used to query this additional configuration option: +.\" OPTION: -stat .TP \fB\-stat\fR . @@ -191,6 +160,7 @@ the PORTABILITY ISSUES section. The \fBchan configure\fR and \fBfconfigure\fR commands can be used to query and set additional configuration options specific to serial ports (where supported): +.\" OPTION: -mode .TP \fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR . @@ -208,6 +178,7 @@ or \fIData\fR is the number of data bits and should be an integer from 5 to 8, while \fIstop\fR is the number of stop bits and should be the integer 1 or 2. +.\" OPTION: -handshake .TP \fB\-handshake\fR \fItype\fR . @@ -226,12 +197,14 @@ There is no default handshake configuration, the initial value depends on your operating system settings. The \fB\-handshake\fR option cannot be queried. .RE +.\" OPTION: -queue .TP \fB\-queue\fR . (Windows and Unix). The \fB\-queue\fR option can only be queried. It returns a list of two integers representing the current number of bytes in the input and output queue respectively. +.\" OPTION: -timeout .TP \fB\-timeout\fR \fImsec\fR . @@ -242,6 +215,7 @@ For Unix systems the granularity is 100 milliseconds. The \fB\-timeout\fR option does not affect write operations or nonblocking reads. This option cannot be queried. +.\" OPTION: -ttycontrol .TP \fB\-ttycontrol\fR \fI{signal boolean signal boolean ...}\fR . @@ -255,6 +229,7 @@ It is not a good idea to change the \fBRTS\fR (or \fBDTR\fR) signal with active hardware handshake \fBrtscts\fR (or \fBdtrdsr\fR). The result is unpredictable. The \fB\-ttycontrol\fR option cannot be queried. +.\" OPTION: -ttystatus .TP \fB\-ttystatus\fR . @@ -264,6 +239,7 @@ queried. It returns the current modem status and handshake input signals The result is a list of signal,value pairs with a fixed order, e.g. \fB{CTS 1 DSR 0 RING 1 DCD 0}\fR. The \fIsignal\fR names are returned upper case. +.\" OPTION: -xchar .TP \fB\-xchar\fR \fI{xonChar xoffChar}\fR . @@ -271,6 +247,7 @@ The \fIsignal\fR names are returned upper case. handshake characters. Normally the operating system default should be DC1 (0x11) and DC3 (0x13) representing the ASCII standard XON and XOFF characters. +.\" OPTION: -closemode .TP \fB\-closemode\fR \fIcloseMode\fR .VS "8.7, TIP 160" @@ -279,24 +256,19 @@ the serial channel, which defines how pending output in operating system buffers is handled when the channel is closed. The following values for \fIcloseMode\fR are supported: .RS -.TP -\fBdefault\fR -. +.IP \fBdefault\fR indicates that a system default operation should be used; all serial channels default to this. -.TP -\fBdiscard\fR -. +.IP \fBdiscard\fR indicates that the contents of the OS buffers should be discarded. Note that this is \fInot recommended\fR when writing to a POSIX terminal, as it can interact unexpectedly with handling of \fBstderr\fR. -.TP -\fBdrain\fR -. +.IP \fBdrain\fR indicates that Tcl should wait when closing the channel until all output has been consumed. This may slow down \fBclose\fR noticeably. .RE .VE "8.7, TIP 160" +.\" OPTION: -inputmode .TP \fB\-inputmode\fR \fIinputMode\fR .VS "8.7, TIP 160" @@ -306,26 +278,18 @@ the assumption that it is talking to a terminal, which controls how interactive input from users is handled. The following values for \fIinputMode\fR are supported: .RS -.TP -\fBnormal\fR -. +.IP \fBnormal\fR indicates that normal line-oriented input should be used, with standard terminal editing capabilities enabled. -.TP -\fBpassword\fR -. +.IP \fBpassword\fR indicates that non-echoing input should be used, with standard terminal editing capabilities enabled but no writing of typed characters to the terminal (except for newlines). Some terminals may indicate this specially. -.TP -\fBraw\fR -. +.IP \fBraw\fR indicates that all keyboard input should be given directly to Tcl with the terminal doing no processing at all. It does not echo the keys, leaving it up to the Tcl script to interpret what to do. -.TP -\fBreset\fR (set only) -. +.IP "\fBreset\fR (set only)" indicates that the terminal should be reset to what state it was in when the terminal was opened. .PP @@ -333,6 +297,7 @@ Note that setting this option (technically, anything that changes the terminal state from its initial value \fIvia this option\fR) will cause the channel to turn on an automatic reset of the terminal when the channel is closed. .RE +.\" OPTION: -winsize .TP \fB\-winsize\fR . @@ -340,6 +305,7 @@ turn on an automatic reset of the terminal when the channel is closed. option is query only. It retrieves a two-element list with the the current width and height of the terminal. .VE "8.7, TIP 160" +.\" OPTION: -pollinterval .TP \fB\-pollinterval\fR \fImsec\fR . @@ -349,6 +315,7 @@ This affects the time interval between checking for events throughout the Tcl interpreter (the smallest value always wins). Use this option only if you want to poll the serial port more or less often than 10 msec (the default). +.\" OPTION: -sysbuffer .TP \fB\-sysbuffer\fR \fIinSize\fR .TP @@ -359,6 +326,7 @@ system buffers for a serial channel. Especially at higher communication rates the default input buffer size of 4096 bytes can overrun for latent systems. The first form specifies the input buffer size, in the second form both input and output buffers are defined. +.\" OPTION: -lasterror .TP \fB\-lasterror\fR . @@ -377,29 +345,29 @@ lines and handshaking. Here we are using the terms \fIworkstation\fR for your computer and \fImodem\fR for the external device, because some signal names (DCD, RI) come from modems. Of course your external device may use these signal lines for other purposes. -.IP \fBTXD\fR(output) +.IP "\fBTXD\fR (output)" \fBTransmitted Data:\fR Outgoing serial data. -.IP \fBRXD\fR(input) +.IP "\fBRXD\fR (input)" \fBReceived Data:\fRIncoming serial data. -.IP \fBRTS\fR(output) +.IP "\fBRTS\fR (output)" \fBRequest To Send:\fR This hardware handshake line informs the modem that your workstation is ready to receive data. Your workstation may automatically reset this signal to indicate that the input buffer is full. -.IP \fBCTS\fR(input) +.IP "\fBCTS\fR (input)" \fBClear To Send:\fR The complement to RTS. Indicates that the modem is ready to receive data. -.IP \fBDTR\fR(output) +.IP "\fBDTR\fR (output)" \fBData Terminal Ready:\fR This signal tells the modem that the workstation is ready to establish a link. DTR is often enabled automatically whenever a serial port is opened. -.IP \fBDSR\fR(input) +.IP "\fBDSR\fR (input)" \fBData Set Ready:\fR The complement to DTR. Tells the workstation that the modem is ready to establish a link. -.IP \fBDCD\fR(input) +.IP "\fBDCD\fR (input)" \fBData Carrier Detect:\fR This line becomes active when a modem detects a .QW Carrier signal. -.IP \fBRI\fR(input) +.IP "\fBRI\fR (input)" \fBRing Indicator:\fR Goes active when the modem detects an incoming call. .IP \fBBREAK\fR A BREAK condition is not a hardware signal line, but a logical zero on the @@ -417,39 +385,27 @@ settings may be wrong. That is why a reliable software should always \fBcatch\fR serial read operations. In cases of an error Tcl returns a general file I/O error. Then \fBfconfigure\fR \fB\-lasterror\fR may help to locate the problem. The following error codes may be returned. -.TP 10 -\fBRXOVER\fR -. +.IP \fBRXOVER\fR Windows input buffer overrun. The data comes faster than your scripts reads -it or your system is overloaded. Use \fBfconfigure\fR \fB\-sysbuffer\fR to avoid a -temporary bottleneck and/or make your script faster. -.TP 10 -\fBTXFULL\fR -. +it or your system is overloaded. Use \fBfconfigure\fR \fB\-sysbuffer\fR to +avoid a temporary bottleneck and/or make your script faster. +.IP \fBTXFULL\fR Windows output buffer overrun. Complement to RXOVER. This error should practically not happen, because Tcl cares about the output buffer status. -.TP 10 -\fBOVERRUN\fR -. +.IP \fBOVERRUN\fR UART buffer overrun (hardware) with data lost. The data comes faster than the system driver receives it. Check your advanced serial port settings to enable the FIFO (16550) buffer and/or setup a lower(1) interrupt threshold value. -.TP 10 -\fBRXPARITY\fR -. +.IP \fBRXPARITY\fR A parity error has been detected by your UART. -Wrong parity settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line (RXD) -may cause this error. -.TP 10 -\fBFRAME\fR -. +Wrong parity settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line +(RXD) may cause this error. +.IP \fBFRAME\fR A stop-bit error has been detected by your UART. -Wrong mode settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line (RXD) -may cause this error. -.TP 10 -\fBBREAK\fR -. +Wrong mode settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line +(RXD) may cause this error. +.IP \fBBREAK\fR A BREAK condition has been detected by your UART (see above). .SS "PORTABILITY ISSUES" .TP @@ -483,7 +439,7 @@ before each write, which is not an atomic operation and does not carry the guarantee of strict appending that is present on POSIX platforms. .RE .TP -\fBUnix\fR\0\0\0\0\0\0\0 +\fBUnix \fR . Valid values for \fIfileName\fR to open a serial port are generally of the form \fB/dev/tty\fIX\fR, where \fIX\fR is \fBa\fR or \fBb\fR, but the name @@ -510,6 +466,7 @@ applications on the various platforms .VS "8.7, TIP 160" On Windows only, console channels (usually \fBstdin\fR or \fBstdout\fR) support the following options: +.\" OPTION: -inputmode .TP \fB\-inputmode\fR \fIinputMode\fR . @@ -517,20 +474,14 @@ This option is used to query or change the input mode of the console channel, which controls how interactive input from users is handled. The following values for \fIinputMode\fR are supported: .RS -.TP -\fBnormal\fR -. +.IP \fBnormal\fR indicates that normal line-oriented input should be used, with standard console editing capabilities enabled. -.TP -\fBpassword\fR -. +.IP \fBpassword\fR indicates that non-echoing input should be used, with standard console -editing capabilitied enabled but no writing of typed characters to the +editing capabilities enabled but no writing of typed characters to the terminal (except for newlines). -.TP -\fBraw\fR -. +.IP \fBraw\fR indicates that all keyboard input should be given directly to Tcl with the console doing no processing at all. It does not echo the keys, leaving it up to the Tcl script to interpret what to do. @@ -544,11 +495,12 @@ Note that setting this option (technically, anything that changes the console state from its default \fIvia this option\fR) will cause the channel to turn on an automatic reset of the console when the channel is closed. .RE +.\" OPTION: -winsize .TP \fB\-winsize\fR . This option is query only. -It retrieves a two-element list with the the current width and height of the +It retrieves a two-element list with the current width and height of the console that this channel is talking to. .PP Note that the equivalent options exist on Unix, but are on the serial channel diff --git a/doc/package.n b/doc/package.n index 5687480..bb53390 100644 --- a/doc/package.n +++ b/doc/package.n @@ -197,33 +197,23 @@ Returns 1 if the \fIversion\fR satisfies at least one of the given requirements, and 0 otherwise. Each \fIrequirement\fR is allowed to have any of the forms: .RS -.TP -min -. +.IP \fImin\fR This form is called .QW min-bounded . -.TP -min- -. +.IP \fImin\fB\-\fR This form is called .QW min-unbound . -.TP -min-max -. +.IP \fImin\fB\-\fImax\fR This form is called .QW bounded . -.RE -.RS .PP where -.QW min +.QW \fImin\fR and -.QW max +.QW \fImax\fR are valid version numbers. The legacy syntax is a special case of the extended syntax, keeping backward compatibility. Regarding satisfaction the rules are: -.RE -.RS .IP [1] The \fIversion\fR has to pass at least one of the listed \fIrequirement\fRs to be satisfactory. diff --git a/doc/packagens.n b/doc/packagens.n index d55151f..6d7f624 100644 --- a/doc/packagens.n +++ b/doc/packagens.n @@ -21,14 +21,20 @@ command for a given package specification. It can be used to construct a .SH OPTIONS The parameters supported are: +.\" OPTION: -name .TP \fB\-name \fIpackageName\fR +. This parameter specifies the name of the package. It is required. +.\" OPTION: -version .TP \fB\-version \fIpackageVersion\fR +. This parameter specifies the version of the package. It is required. +.\" OPTION: -load .TP \fB\-load \fIfilespec\fR +. This parameter specifies a library that must be loaded with the \fBload\fR command. \fIfilespec\fR is a list with two elements. The first element is the name of the file to load. The second, optional @@ -36,8 +42,10 @@ element is a list of commands supplied by loading that file. If the list of procedures is empty or omitted, \fB::pkg::create\fR will set up the library for direct loading (see \fBpkg_mkIndex\fR). Any number of \fB\-load\fR parameters may be specified. +.\" OPTION: -source .TP \fB\-source \fIfilespec\fR +. This parameter is similar to the \fB\-load\fR parameter, except that it specifies a Tcl library that must be loaded with the \fBsource\fR command. Any number of \fB\-source\fR parameters may be diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n index f98cbcd..3d10360 100644 --- a/doc/pkgMkIndex.n +++ b/doc/pkgMkIndex.n @@ -96,29 +96,39 @@ Different versions of a package may be loaded in different interpreters. .SH OPTIONS The optional switches are: +.\" OPTION: -direct .TP 15 \fB\-direct\fR +. The generated index will implement direct loading of the package upon \fBpackage require\fR. This is the default. +.\" OPTION: -lazy .TP 15 \fB\-lazy\fR +. The generated index will manage to delay loading the package until the use of one of the commands provided by the package, instead of loading it immediately upon \fBpackage require\fR. This is not compatible with the use of \fIauto_reset\fR, and therefore its use is discouraged. +.\" OPTION: -load .TP 15 \fB\-load \fIpkgPat\fR +. The index process will preload any packages that exist in the current interpreter and match \fIpkgPat\fR into the child interpreter used to generate the index. The pattern match uses string match rules, but without making case distinctions. See \fBCOMPLEX CASES\fR below. +.\" OPTION: -verbose .TP 15 \fB\-verbose\fR +. Generate output during the indexing process. Output is via the \fBtclLog\fR procedure, which by default prints to stderr. +.\" OPTION: -- .TP 15 \fB\-\-\fR +. End of the flags, in case \fIdir\fR begins with a dash. .SH "PACKAGES AND THE AUTO-LOADER" .PP diff --git a/doc/platform.n b/doc/platform.n index 7cb685d..78dfc79 100644 --- a/doc/platform.n +++ b/doc/platform.n @@ -43,6 +43,7 @@ establishes a standard naming convention for architectures running Tcl and makes it more convenient for developers to identify the current architecture a Tcl program is running on. .SH COMMANDS +.\" COMMAND: identify .TP \fBplatform::identify\fR . @@ -52,6 +53,7 @@ core is running on. The returned identifier has the general format details like kernel version, libc version, etc., and this information may contain dashes as well. The \fICPU\fR part will not contain dashes, making the preceding dash the last dash in the result. +.\" COMMAND: generic .TP \fBplatform::generic\fR . @@ -59,6 +61,7 @@ This command returns a simplified identifier describing the platform the Tcl core is running on. In contrast to \fBplatform::identify\fR it leaves out details like kernel version, libc version, etc. The returned identifier has the general format \fIOS\fR-\fICPU\fR. +.\" COMMAND: patterns .TP \fBplatform::patterns \fIidentifier\fR . diff --git a/doc/platform_shell.n b/doc/platform_shell.n index a9e14d0..8844ad6 100644 --- a/doc/platform_shell.n +++ b/doc/platform_shell.n @@ -41,16 +41,22 @@ the architecture of the shell which will actually run the installed packages, versus the architecture of the shell running the repository software. .SH COMMANDS +.\" COMMAND: identify .TP \fBplatform::shell::identify \fIshell\fR +. This command does the same identification as \fBplatform::identify\fR, for the specified Tcl shell, in contrast to the running shell. +.\" COMMAND: generic .TP \fBplatform::shell::generic \fIshell\fR +. This command does the same identification as \fBplatform::generic\fR, for the specified Tcl shell, in contrast to the running shell. +.\" COMMAND: platform .TP \fBplatform::shell::platform \fIshell\fR +. This command returns the contents of \fBtcl_platform(platform)\fR for the specified Tcl shell. .SH KEYWORDS diff --git a/doc/prefix.n b/doc/prefix.n index d327a78..309bfef 100644 --- a/doc/prefix.n +++ b/doc/prefix.n @@ -41,15 +41,18 @@ before use with this subcommand, so that the list of matches presented in the error message also becomes sorted, though this is not strictly necessary for the operation of this subcommand itself.) .RS +.\" OPTION: -exact .TP -\fB\-exact\fR\0 +\fB\-exact\fR . Accept only exact matches. +.\" OPTION: -message .TP \fB\-message\0\fIstring\fR . Use \fIstring\fR in the error message at a mismatch. Default is .QW option . +.\" OPTION: -error .TP \fB\-error\0\fIoptions\fR . @@ -64,7 +67,7 @@ is used, an error would be generated as: .RS .PP .CS -return \-errorcode MyError \-level 1 \-code error \e +return -errorcode MyError -level 1 -code error \e "ambiguous option ..." .CE .RE @@ -79,9 +82,9 @@ namespace import ::tcl::prefix \fI\(-> apa\fR \fBprefix match\fR {apa bepa cepa} a \fI\(-> apa\fR -\fBprefix match\fR \-exact {apa bepa cepa} a +\fBprefix match\fR -exact {apa bepa cepa} a \fI\(-> bad option "a": must be apa, bepa, or cepa\fR -\fBprefix match\fR \-message "switch" {apa ada bepa cepa} a +\fBprefix match\fR -message "switch" {apa ada bepa cepa} a \fI\(-> ambiguous switch "a": must be apa, ada, bepa, or cepa\fR \fBprefix longest\fR {fblocked fconfigure fcopy file fileevent flush} fc \fI\(-> fco\fR @@ -92,9 +95,9 @@ namespace import ::tcl::prefix Simplifying option matching: .PP .CS -array set opts {\-apa 1 \-bepa "" \-cepa 0} +array set opts {-apa 1 -bepa "" -cepa 0} foreach {arg val} $args { - set opts([\fBprefix match\fR {\-apa \-bepa \-cepa} $arg]) $val + set opts([\fBprefix match\fR {-apa -bepa -cepa} $arg]) $val } .CE .PP @@ -57,10 +57,10 @@ There is one special case to permit procedures with variable numbers of arguments. If the last formal argument has the name .QW \fBargs\fR , then a call to the procedure may contain more actual arguments -than the procedure has formal arguments. In this case, all of the actual arguments -starting at the one that would be assigned to \fBargs\fR are combined into -a list (as if the \fBlist\fR command had been used); this combined value -is assigned to the local variable \fBargs\fR. +than the procedure has formal arguments. In this case, all of the actual +arguments starting at the one that would be assigned to \fBargs\fR are +combined into a list (as if the \fBlist\fR command had been used); this +combined value is assigned to the local variable \fBargs\fR. .PP When \fIbody\fR is being executed, variable names normally refer to local variables, which are created automatically when referenced and diff --git a/doc/process.n b/doc/process.n index 165e413..b006134 100644 --- a/doc/process.n +++ b/doc/process.n @@ -53,16 +53,16 @@ processes, the status is a list with the following format: where: .RS .TP -\fIcode\fR\0 +\fIcode\fR . is a standard Tcl return code, i.e., \fB0\fR for TCL_OK and \fB1\fR for TCL_ERROR, .TP -\fImsg\fR\0 +\fImsg\fR . is the human-readable error message, .TP -\fIerrorCode\fR\0 +\fIerrorCode\fR . uses the same format as the \fBerrorCode\fR global variable .PP @@ -72,14 +72,16 @@ hood this command calls \fBTcl_WaitPid\fR with the \fBWNOHANG\fR flag set for non-blocking behavior, unless the \fB\-wait\fR switch is set (see below). .PP Additionally, \fB::tcl::process status\fR accepts the following switches: +.\" OPTION: -wait .TP -\fB\-wait\fR\0 +\fB\-wait\fR . By default the command returns immediately (the underlying \fBTcl_WaitPid\fR is called with the \fBWNOHANG\fR flag set) unless this switch is set. If \fIpids\fR is specified as a list of PIDs then the command waits until the status of the matching subprocesses are available. If \fIpids\fR was not specified, this command will wait for all known subprocesses. +.\" OPTION: -- .TP \fB\-\|\-\fR . diff --git a/doc/re_syntax.n b/doc/re_syntax.n index ef8c570..3aed36d 100644 --- a/doc/re_syntax.n +++ b/doc/re_syntax.n @@ -57,29 +57,17 @@ Without a quantifier, it matches a single match for the atom. The quantifiers, and what a so-quantified atom matches, are: .RS 2 -.TP 6 -\fB*\fR -. +.IP \fB*\fR 6 a sequence of 0 or more matches of the atom -.TP -\fB+\fR -. +.IP \fB+\fR 6 a sequence of 1 or more matches of the atom -.TP -\fB?\fR -. +.IP \fB?\fR 6 a sequence of 0 or 1 matches of the atom -.TP -\fB{\fIm\fB}\fR -. +.IP \fB{\fIm\fB}\fR 6 a sequence of exactly \fIm\fR matches of the atom -.TP -\fB{\fIm\fB,}\fR -. +.IP \fB{\fIm\fB,}\fR 6 a sequence of \fIm\fR or more matches of the atom -.TP -\fB{\fIm\fB,\fIn\fB}\fR -. +.IP \fB{\fIm\fB,\fIn\fB}\fR 6 a sequence of \fIm\fR through \fIn\fR (inclusive) matches of the atom; \fIm\fR may not exceed \fIn\fR .TP @@ -99,32 +87,32 @@ An atom is one of: .IP \fB(\fIre\fB)\fR 6 matches a match for \fIre\fR (\fIre\fR is any regular expression) with the match noted for possible reporting -.IP \fB(?:\fIre\fB)\fR +.IP \fB(?:\fIre\fB)\fR 6 as previous, but does no reporting (a .QW non-capturing set of parentheses) -.IP \fB()\fR +.IP \fB()\fR 6 matches an empty string, noted for possible reporting -.IP \fB(?:)\fR +.IP \fB(?:)\fR 6 matches an empty string, without reporting -.IP \fB[\fIchars\fB]\fR +.IP \fB[\fIchars\fB]\fR 6 a \fIbracket expression\fR, matching any one of the \fIchars\fR (see \fBBRACKET EXPRESSIONS\fR for more detail) -.IP \fB.\fR +.IP \fB.\fR 6 matches any single character -.IP \fB\e\fIk\fR +.IP \fB\e\fIk\fR 6 matches the non-alphanumeric character \fIk\fR taken as an ordinary character, e.g. \fB\e\e\fR matches a backslash character -.IP \fB\e\fIc\fR +.IP \fB\e\fIc\fR 6 where \fIc\fR is alphanumeric (possibly followed by other characters), an \fIescape\fR (AREs only), see \fBESCAPES\fR below -.IP \fB{\fR +.IP \fB{\fR 6 when followed by a character other than a digit, matches the left-brace character .QW \fB{\fR ; when followed by a digit, it is the beginning of a \fIbound\fR (see above) -.IP \fIx\fR +.IP \fIx\fR 6 where \fIx\fR is a single character with no other significance, matches that character. .RE @@ -334,82 +322,50 @@ is the one actual incompatibility between EREs and AREs.) Character-entry escapes (AREs only) exist to make it easier to specify non-printing and otherwise inconvenient characters in REs: .RS 2 -.TP 5 -\fB\ea\fR -. +.IP \fB\ea\fR 5 alert (bell) character, as in C -.TP -\fB\eb\fR -. +.IP \fB\eb\fR 5 backspace, as in C -.TP -\fB\eB\fR -. +.IP \fB\eB\fR 5 synonym for \fB\e\fR to help reduce backslash doubling in some applications where there are multiple levels of backslash processing -.TP -\fB\ec\fIX\fR -. +.IP \fB\ec\fIX\fR 5 (where \fIX\fR is any character) the character whose low-order 5 bits are the same as those of \fIX\fR, and whose other bits are all zero -.TP -\fB\ee\fR -. +.IP \fB\ee\fR 5 the character whose collating-sequence name is .QW \fBESC\fR , or failing that, the character with octal value 033 -.TP -\fB\ef\fR -. +.IP \fB\ef\fR 5 formfeed, as in C -.TP -\fB\en\fR -. +.IP \fB\en\fR 5 newline, as in C -.TP -\fB\er\fR -. +.IP \fB\er\fR 5 carriage return, as in C -.TP -\fB\et\fR -. +.IP \fB\et\fR 5 horizontal tab, as in C -.TP -\fB\eu\fIwxyz\fR -. +.IP \fB\eu\fIwxyz\fR 5 (where \fIwxyz\fR is one up to four hexadecimal digits) the Unicode character \fBU+\fIwxyz\fR in the local byte ordering -.TP -\fB\eU\fIstuvwxyz\fR -. +.IP \fB\eU\fIstuvwxyz\fR 5 (where \fIstuvwxyz\fR is one up to eight hexadecimal digits) reserved for a Unicode extension up to 21 bits. The digits are parsed until the -first non-hexadecimal character is encountered, the maximun of eight +first non-hexadecimal character is encountered, the maximum of eight hexadecimal digits are reached, or an overflow would occur in the maximum value of \fBU+\fI10ffff\fR. -.TP -\fB\ev\fR -. +.IP \fB\ev\fR 5 vertical tab, as in C are all available. -.TP -\fB\ex\fIhh\fR -. +.IP \fB\ex\fIhh\fR 5 (where \fIhh\fR is one or two hexadecimal digits) the character whose hexadecimal value is \fB0x\fIhh\fR. -.TP -\fB\e0\fR -. +.IP \fB\e0\fR 5 the character whose value is \fB0\fR -.TP -\fB\e\fIxyz\fR -. +.IP \fB\e\fIxyz\fR 5 (where \fIxyz\fR is exactly three octal digits, and is not a \fIback reference\fR (see below)) the character whose octal value is \fB0\fIxyz\fR. The first digit must be in the range 0-3, otherwise the two-digit form is assumed. -.TP -\fB\e\fIxy\fR -. +.IP \fB\e\fIxy\fR 5 (where \fIxy\fR is exactly two octal digits, and is not a \fIback reference\fR (see below)) the character whose octal value is \fB0\fIxy\fR @@ -446,7 +402,8 @@ commonly-used character classes: .TP \fB\ew\fR . -\fB[[:alnum:]_\eu203F\eu2040\eu2054\euFE33\euFE34\euFE4D\euFE4E\euFE4F\euFF3F]\fR (including punctuation connector characters) +\fB[[:alnum:]_\eu203F\eu2040\eu2054\euFE33\euFE34\euFE4D\euFE4E\euFE4F\euFF3F]\fR +(including punctuation connector characters) .TP \fB\eD\fR . @@ -458,7 +415,8 @@ commonly-used character classes: .TP \fB\eW\fR . -\fB[^[:alnum:]_\eu203F\eu2040\eu2054\euFE33\euFE34\euFE4D\euFE4E\euFE4F\euFF3F]\fR (including punctuation connector characters) +\fB[^[:alnum:]_\eu203F\eu2040\eu2054\euFE33\euFE34\euFE4D\euFE4E\euFE4F\euFF3F]\fR +(including punctuation connector characters) .RE .PP Within bracket expressions, @@ -484,41 +442,25 @@ is illegal.) A constraint escape (AREs only) is a constraint, matching the empty string if specific conditions are met, written as an escape: .RS 2 -.TP 6 -\fB\eA\fR -. +.IP \fB\eA\fR 6 matches only at the beginning of the string (see \fBMATCHING\fR, below, for how this differs from .QW \fB^\fR ) -.TP -\fB\em\fR -. +.IP \fB\em\fR 6 matches only at the beginning of a word -.TP -\fB\eM\fR -. +.IP \fB\eM\fR 6 matches only at the end of a word -.TP -\fB\ey\fR -. +.IP \fB\ey\fR 6 matches only at the beginning or end of a word -.TP -\fB\eY\fR -. +.IP \fB\eY\fR 6 matches only at a point that is not the beginning or end of a word -.TP -\fB\eZ\fR -. +.IP \fB\eZ\fR 6 matches only at the end of the string (see \fBMATCHING\fR, below, for how this differs from .QW \fB$\fR ) -.TP -\fB\e\fIm\fR -. +.IP \fB\e\fIm\fR 6 (where \fIm\fR is a nonzero digit) a \fIback reference\fR, see below -.TP -\fB\e\fImnn\fR -. +.IP \fB\e\fImnn\fR 6 (where \fIm\fR is a nonzero digit, and \fInn\fR is some more digits, and the decimal value \fImnn\fR is not greater than the number of closing capturing parentheses seen so far) a \fIback reference\fR, see diff --git a/doc/refchan.n b/doc/refchan.n index 94823c5..75c8cd0 100644 --- a/doc/refchan.n +++ b/doc/refchan.n @@ -238,17 +238,11 @@ the channel. .PP The \fIbase\fR argument is the same as the equivalent argument of the builtin \fBchan seek\fR, namely: -.TP 10 -\fBstart\fR -. +.IP \fBstart\fR 10 Seeking is relative to the beginning of the channel. -.TP 10 -\fBcurrent\fR -. +.IP \fBcurrent\fR 10 Seeking is relative to the current seek position. -.TP 10 -\fBend\fR -. +.IP \fBend\fR 10 Seeking is relative to the end of the channel. .PP The \fIoffset\fR is an integer number specifying the amount of diff --git a/doc/regexp.n b/doc/regexp.n index 6f303a4..7bb97fb 100644 --- a/doc/regexp.n +++ b/doc/regexp.n @@ -34,6 +34,7 @@ subexpression to the right in \fIexp\fR, and so on. If the initial arguments to \fBregexp\fR start with \fB\-\fR then they are treated as switches. The following switches are currently supported: +.\" OPTION: -about .TP 15 \fB\-about\fR . @@ -42,12 +43,14 @@ containing information about the regular expression. The first element of the list is a subexpression count. The second element is a list of property names that describe various attributes of the regular expression. This switch is primarily intended for debugging purposes. +.\" OPTION: -expanded .TP 15 \fB\-expanded\fR . Enables use of the expanded regular expression syntax where whitespace and comments are ignored. This is the same as specifying the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page). +.\" OPTION: -indices .TP 15 \fB\-indices\fR . @@ -57,6 +60,7 @@ each variable will contain a list of two decimal strings giving the indices in \fIstring\fR of the first and last characters in the matching range of characters. +.\" OPTION: -line .TP 15 \fB\-line\fR . @@ -75,6 +79,7 @@ matches an empty string before any newline in addition to its normal function. This flag is equivalent to specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page). +.\" OPTION: -linestop .TP 15 \fB\-linestop\fR . @@ -85,6 +90,7 @@ bracket expressions and so that they stop at newlines. This is the same as specifying the \fB(?p)\fR embedded option (see the \fBre_syntax\fR manual page). +.\" OPTION: -lineanchor .TP 15 \fB\-lineanchor\fR . @@ -98,11 +104,13 @@ so they match the beginning and end of a line respectively. This is the same as specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR manual page). +.\" OPTION: -nocase .TP 15 \fB\-nocase\fR . Causes upper-case characters in \fIstring\fR to be treated as lower case during the matching process. +.\" OPTION: -all .TP 15 \fB\-all\fR . @@ -110,6 +118,7 @@ Causes the regular expression to be matched as many times as possible in the string, returning the total number of matches found. If this is specified with match variables, they will contain information for the last match only. +.\" OPTION: -inline .TP 15 \fB\-inline\fR . @@ -129,6 +138,7 @@ regular expression. Examples are: \fI\(-> in n li i ne e\fR .CE .RE +.\" OPTION: -start .TP 15 \fB\-start\fR \fIindex\fR . @@ -143,6 +153,7 @@ match the start of the string at \fIindex\fR. If \fB\-indices\fR is specified, the indices will be indexed starting from the absolute beginning of the input string. \fIindex\fR will be constrained to the bounds of the input string. +.\" OPTION: -- .TP 15 \fB\-\|\-\fR . @@ -175,7 +186,7 @@ Find the index of the word \fBbadger\fR (in any case) within a string and store that in the variable \fBlocation\fR: .PP .CS -\fBregexp\fR \-indices {(?i)\embadger\eM} $string location +\fBregexp\fR -indices {(?i)\embadger\eM} $string location .CE .PP This could also be written as a \fIbasic\fR regular expression (as opposed @@ -183,13 +194,13 @@ to using the default syntax of \fIadvanced\fR regular expressions) match by prefixing the expression with a suitable flag: .PP .CS -\fBregexp\fR \-indices {(?ib)\e<badger\e>} $string location +\fBregexp\fR -indices {(?ib)\e<badger\e>} $string location .CE .PP This counts the number of octal digits in a string: .PP .CS -\fBregexp\fR \-all {[0\-7]} $string +\fBregexp\fR -all {[0-7]} $string .CE .PP This lists all words (consisting of all sequences of non-whitespace @@ -197,7 +208,7 @@ characters) in a string, and is useful as a more powerful version of the \fBsplit\fR command: .PP .CS -\fBregexp\fR \-all \-inline {\eS+} $string +\fBregexp\fR -all -inline {\eS+} $string .CE .SH "SEE ALSO" re_syntax(n), regsub(n), string(n) diff --git a/doc/registry.n b/doc/registry.n index 66b2dd9..8a73cc6 100644 --- a/doc/registry.n +++ b/doc/registry.n @@ -136,53 +136,35 @@ data, but does not actually change the representation. For some types, the \fBregistry\fR command returns the data in a different form to make it easier to manipulate. The following types are recognized by the registry command: -.TP 17 -\fBbinary\fR -. +.IP \fBbinary\fR The registry value contains arbitrary binary data. The data is represented exactly in Tcl, including any embedded nulls. -.TP -\fBnone\fR -. +.IP \fBnone\fR The registry value contains arbitrary binary data with no defined type. The data is represented exactly in Tcl, including any embedded nulls. -.TP -\fBsz\fR -. +.IP \fBsz\fR The registry value contains a null-terminated string. The data is represented in Tcl as a string. -.TP -\fBexpand_sz\fR -. +.IP \fBexpand_sz\fR The registry value contains a null-terminated string that contains unexpanded references to environment variables in the normal Windows style (for example, .QW %PATH% ). The data is represented in Tcl as a string. -.TP -\fBdword\fR -. +.IP \fBdword\fR The registry value contains a little-endian 32-bit number. The data is represented in Tcl as a decimal string. -.TP -\fBdword_big_endian\fR -. +.IP \fBdword_big_endian\fR The registry value contains a big-endian 32-bit number. The data is represented in Tcl as a decimal string. -.TP -\fBlink\fR -. +.IP \fBlink\fR The registry value contains a symbolic link. The data is represented exactly in Tcl, including any embedded nulls. -.TP -\fBmulti_sz\fR -. +.IP \fBmulti_sz\fR The registry value contains an array of null-terminated strings. The data is represented in Tcl as a list of strings. -.TP -\fBresource_list\fR -. +.IP \fBresource_list\fR The registry value contains a device-driver resource list. The data is represented exactly in Tcl, including any embedded nulls. .PP diff --git a/doc/return.n b/doc/return.n index e3d7c06..36c09c0 100644 --- a/doc/return.n +++ b/doc/return.n @@ -105,6 +105,7 @@ script. As documented above, the \fB\-code\fR entry in the return options dictionary receives special treatment by Tcl. There are other return options also recognized and treated specially by Tcl. They are: +.\" OPTION: -errorcode .TP \fB\-errorcode \fIlist\fR . @@ -117,6 +118,7 @@ the \fB\-code error\fR option is provided, Tcl will set the value of the \fB\-errorcode\fR entry in the return options dictionary to the default value of \fBNONE\fR. The \fB\-errorcode\fR return option will also be stored in the global variable \fBerrorCode\fR. +.\" OPTION: -errorinfo .TP \fB\-errorinfo \fIinfo\fR . @@ -135,11 +137,14 @@ the procedure. Typically the \fIinfo\fR value is supplied from the value of \fB\-errorinfo\fR in a return options dictionary captured by the \fBcatch\fR command (or from the copy of that information stored in the global variable \fBerrorInfo\fR). +.\" OPTION: -errorstack .TP \fB\-errorstack \fIlist\fR +. The \fB\-errorstack\fR option receives special treatment only when the value of the \fB\-code\fR option is \fBTCL_ERROR\fR. Then \fIlist\fR is the initial -error stack, recording actual argument values passed to each proc level. The error stack will +error stack, recording actual argument values passed to each proc level. +The error stack will also be reachable through \fBinfo errorstack\fR. If no \fB\-errorstack\fR option is provided to \fBreturn\fR when the \fB\-code error\fR option is provided, Tcl will provide its own @@ -151,6 +156,7 @@ the procedure. Typically the \fIlist\fR value is supplied from the value of \fB\-errorstack\fR in a return options dictionary captured by the \fBcatch\fR command (or from the copy of that information from \fBinfo errorstack\fR). +.\" OPTION: -level .TP \fB\-level \fIlevel\fR . @@ -163,6 +169,7 @@ be \fIcode\fR. If no \fB\-level\fR option is provided, the default value of \fIlevel\fR is 1, so that \fBreturn\fR sets the return code that the current procedure returns to its caller, 1 level up the call stack. The mechanism by which these options work is described in more detail below. +.\" OPTION: -options .TP \fB\-options \fIoptions\fR . @@ -108,15 +108,16 @@ Example of use: set i1 [safe::interpCreate {*}[safe::interpConfigure $i0]] # Get the current deleteHook -set dh [safe::interpConfigure $i0 \-del] +set dh [safe::interpConfigure $i0 -del] # Change (only) the statics loading ok attribute of an # interp and its deleteHook (leaving the rest unchanged): -safe::interpConfigure $i0 \-delete {foo bar} \-statics 0 +safe::interpConfigure $i0 -delete {foo bar} -statics 0 .CE .RE .TP \fB::safe::interpDelete\fR \fIchild\fR +. Deletes the safe interpreter and cleans up the corresponding parent interpreter data structures. If a \fIdeleteHook\fR script was specified for this interpreter it is @@ -201,6 +202,7 @@ and \fB::safe::interpConfigure\fR. Any option name can be abbreviated to its minimal non-ambiguous name. Option names are not case sensitive. +.\" OPTION: -accessPath .TP \fB\-accessPath\fR \fIdirectoryList\fR This option sets the list of directories from which the safe interpreter @@ -210,6 +212,7 @@ empty list, the safe interpreter will use the same directories as its parent for auto-loading. See the section \fBSECURITY\fR below for more detail about virtual paths, tokens and access control. +.\" OPTION: -autoPath .TP \fB\-autoPath\fR \fIdirectoryList\fR This option sets the list of directories in the safe interpreter's @@ -217,17 +220,20 @@ This option sets the list of directories in the safe interpreter's - in that case the safe interpreter's ::auto_path is managed by the Safe Base and is a tokenized form of its access path. See the section \fBSYNC MODE\fR below for details. +.\" OPTION: -statics .TP \fB\-statics\fR \fIboolean\fR This option specifies if the safe interpreter will be allowed to load statically linked packages (like \fBload {} Tk\fR). The default value is \fBtrue\fR : safe interpreters are allowed to load statically linked packages. +.\" OPTION: -noStatics .TP \fB\-noStatics\fR This option is a convenience shortcut for \fB\-statics false\fR and thus specifies that the safe interpreter will not be allowed to load statically linked packages. +.\" OPTION: -nested .TP \fB\-nested\fR \fIboolean\fR This option specifies if the safe interpreter will be allowed @@ -235,11 +241,13 @@ to load packages into its own sub-interpreters. The default value is \fBfalse\fR : safe interpreters are not allowed to load packages into their own sub-interpreters. +.\" OPTION: -nestedLoadOk .TP \fB\-nestedLoadOk\fR This option is a convenience shortcut for \fB\-nested true\fR and thus specifies the safe interpreter will be allowed to load packages into its own sub-interpreters. +.\" OPTION: -deleteHook .TP \fB\-deleteHook\fR \fIscript\fR When this option is given a non-empty \fIscript\fR, it will be @@ -271,14 +279,14 @@ the safe interpreter for it to be found successfully. Additionally, the shared object file must contain a safe entry point; see the manual page for the \fBload\fR command for more details. .TP -\fBfile\fR ?\fIsubCmd args...\fR? +\fBfile\fR ?\fIsubcommand args...\fR? The \fBfile\fR alias provides access to a safe subset of the subcommands of the \fBfile\fR command; it allows only \fBdirname\fR, \fBjoin\fR, \fBextension\fR, \fBroot\fR, \fBtail\fR, \fBpathname\fR and \fBsplit\fR subcommands. For more details on what these subcommands do see the manual page for the \fBfile\fR command. .TP -\fBencoding\fR ?\fIsubCmd args...\fR? +\fBencoding\fR ?\fIsubcommand args...\fR? The \fBencoding\fR alias provides access to a safe subset of the subcommands of the \fBencoding\fR command; it disallows setting of the system encoding, but allows all other subcommands including @@ -435,9 +443,9 @@ parent interpreter to packages, modules, and autoloader files. With parent's ::auto_path, and will set the child's ::auto_path to a tokenized form of the parent's ::auto_path. .PP -With "Sync Mode" off, if a value is specified for \fB\-autoPath\fR, even the empty -list, in a call to \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, or -\fB::safe::interpConfigure\fR, it will be tokenized and used as the safe +With "Sync Mode" off, if a value is specified for \fB\-autoPath\fR, even the +empty list, in a call to \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, +or \fB::safe::interpConfigure\fR, it will be tokenized and used as the safe interpreter's ::auto_path. Any directories that do not also belong to the access path cannot be tokenized and will be silently ignored. However, the value of \fB\-autoPath\fR will remain as specified, and will be used to @@ -446,15 +454,15 @@ to change the value of \fB\-accessPath\fR. .PP With "Sync Mode" off, if the access path is reset to the values in the parent interpreter by calling \fB::safe::interpConfigure\fR with arguments -\fB\-accessPath\fR {}, then the ::auto_path will also be reset unless the argument -\fB\-autoPath\fR is supplied to specify a different value. +\fB\-accessPath\fR {}, then the ::auto_path will also be reset unless the +argument \fB\-autoPath\fR is supplied to specify a different value. .PP With "Sync Mode" off, if a non-empty value of \fB\-accessPath\fR is supplied, the safe interpreter's ::auto_path will be set to {} (by \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR) or left unchanged (by \fB::safe::interpConfigure\fR). If the same command specifies a new -value for \fB\-autoPath\fR, it will be applied after the \fB\-accessPath\fR argument has -been processed. +value for \fB\-autoPath\fR, it will be applied after the \fB\-accessPath\fR +argument has been processed. Examples of use with "Sync Mode" off: any of these commands will set the ::auto_path to a tokenized form of its value in the parent interpreter: @@ -524,7 +532,7 @@ Example of use with "Sync Mode" off: the command interp(n), library(n), load(n), package(n), pkg_mkIndex(n), source(n), tm(n), unknown(n) .SH KEYWORDS -alias, auto\-loading, auto_mkindex, load, parent interpreter, safe +alias, auto-loading, auto_mkindex, load, parent interpreter, safe interpreter, child interpreter, source '\" Local Variables: '\" mode: nroff @@ -86,66 +86,49 @@ the integer range to be stored is unlimited. .SS "MANDATORY CONVERSION CHARACTER" .PP The following conversion characters are supported: -.TP -\fBd\fR -. +.IP \fBd\fR The input substring must be a decimal integer. It is read in and the integer value is stored in the variable, truncated as required by the size modifier value. -.TP -\fBo\fR -. +.IP \fBo\fR The input substring must be an octal integer. It is read in and the integer value is stored in the variable, truncated as required by the size modifier value. -.TP -\fBx\fR or \fBX\fR -. +.IP "\fBx\fR or \fBX\fR" The input substring must be a hexadecimal integer. It is read in and the integer value is stored in the variable, truncated as required by the size modifier value. -.TP -\fBb\fR -. +.IP \fBb\fR The input substring must be a binary integer. It is read in and the integer value is stored in the variable, truncated as required by the size modifier value. -.TP -\fBu\fR -. +.IP \fBu\fR The input substring must be a decimal integer. The integer value is truncated as required by the size modifier value, and the corresponding unsigned value for that truncated range is computed and stored in the variable as a decimal string. -.TP -\fBi\fR -. -The input substring must be an integer. The base (i.e. decimal, octal, or hexadecimal) is determined by the C convention (leading 0 for octal; prefix 0x for hexadecimal). The integer value is stored in the variable, -truncated as required by the size modifier value. -.TP -\fBc\fR -. +.IP \fBi\fR +The input substring must be an integer. The base (i.e. decimal, +octal, or hexadecimal) is determined by the C convention (leading +0 for octal; prefix 0x for hexadecimal). The integer value is +stored in the variable, truncated as required by the size modifier +value. +.IP \fBc\fR A single character is read in and its Unicode value is stored in the variable as an integer value. Initial white space is not skipped in this case, so the input substring may be a white-space character. -.TP -\fBs\fR -. +.IP \fBs\fR The input substring consists of all the characters up to the next white-space character; the characters are copied to the variable. -.TP -\fBe\fR or \fBf\fR or \fBg\fR or \fBE\fR or \fBG\fR -. +.IP "\fBe\fR or \fBf\fR or \fBg\fR or \fBE\fR or \fBG\fR" The input substring must be a floating-point number consisting of an optional sign, a string of decimal digits possibly containing a decimal point, and an optional exponent consisting of an \fBe\fR or \fBE\fR followed by an optional sign and a string of decimal digits. It is read in and stored in the variable as a floating-point value. -.TP -\fB[\fIchars\fB]\fR -. +.IP \fB[\fIchars\fB]\fR The input substring consists of one or more characters in \fIchars\fR. The matching string is stored in the variable. If the first character between the brackets is a \fB]\fR then @@ -156,9 +139,7 @@ contains a sequence of the form \fIa\fB\-\fIb\fR then any character between \fIa\fR and \fIb\fR (inclusive) will match. If the first or last character between the brackets is a \fB\-\fR, then it is treated as part of \fIchars\fR rather than indicating a range. -.TP -\fB[^\fIchars\fB]\fR -. +.IP \fB[^\fIchars\fB]\fR The input substring consists of one or more characters not in \fIchars\fR. The matching string is stored in the variable. If the character immediately following the \fB^\fR is a \fB]\fR then it is @@ -170,9 +151,7 @@ character between \fIa\fR and \fIb\fR (inclusive) will be excluded from the set. If the first or last character between the brackets is a \fB\-\fR, then it is treated as part of \fIchars\fR rather than indicating a range value. -.TP -\fBn\fR -. +.IP \fBn\fR No input is consumed from the input string. Instead, the total number of characters scanned from the input string so far is stored in the variable. .PP @@ -70,7 +70,8 @@ practice instead of doing double-dereferencing): \fBset\fR out [\fBset\fR $vbl] .CE .SH "SEE ALSO" -expr(n), global(n), namespace(n), proc(n), trace(n), unset(n), upvar(n), variable(n) +expr(n), global(n), namespace(n), proc(n), trace(n), unset(n), upvar(n), +variable(n) .SH KEYWORDS read, write, variable '\" Local Variables: diff --git a/doc/singleton.n b/doc/singleton.n index 3ccbdd3..ce35593 100644 --- a/doc/singleton.n +++ b/doc/singleton.n @@ -47,6 +47,7 @@ The \fBoo::singleton\fR class does not define an explicit destructor; destroying an instance of it is just like destroying an ordinary class (and will destroy the singleton object). .SS "EXPORTED METHODS" +.\" METHOD: new .TP \fIcls \fBnew \fR?\fIarg ...\fR? . @@ -63,7 +64,8 @@ identical call signature to the superclass's implementation. .SS "NON-EXPORTED METHODS" The \fBoo::singleton\fR class explicitly states that \fBcreate\fR and \fBcreateWithNamespace\fR are unexported; callers should not assume that they -have control over either the name or the namespace name of the singleton instance. +have control over either the name or the namespace name of the singleton +instance. .SH EXAMPLE .PP This example demonstrates that there is only one instance even though the diff --git a/doc/socket.n b/doc/socket.n index b7b3228..8630bea 100644 --- a/doc/socket.n +++ b/doc/socket.n @@ -49,6 +49,7 @@ Use \fIlocalhost\fR to refer to the host on which the command is invoked. .PP The following options may also be present before \fIhost\fR to specify additional information about the connection: +.\" OPTION: -myaddr .TP \fB\-myaddr\fI addr\fR . @@ -57,6 +58,7 @@ the client-side network interface to use for the connection. This option may be useful if the client machine has multiple network interfaces. If the option is omitted then the client-side interface will be chosen by the system software. +.\" OPTION: -myport .TP \fB\-myport\fI port\fR . @@ -65,6 +67,7 @@ supported and understood by the host operating system) to use for the client's side of the connection. If this option is omitted, the client's port number will be chosen at random by the system software. +.\" OPTION: -async .TP \fB\-async\fR . @@ -98,9 +101,12 @@ asynchronous connection has succeeded or failed. See the \fBvwait\fR and the \fBchan\fR commands for more details on the event loop and channel events. .PP -The \fBchan configure\fR option \fB-connecting\fR may be used to check if the connect is still running. To verify a successful connect, the option \fB-error\fR may be checked when \fB-connecting\fR returned 0. +The \fBchan configure\fR option \fB\-connecting\fR may be used to check +if the connect is still running. To verify a successful connect, the +option \fB\-error\fR may be checked when \fB\-connecting\fR returned 0. .PP -Operation without the event queue requires at the moment calls to \fBchan configure\fR to advance the internal state machine. +Operation without the event queue requires at the moment calls to +\fBchan configure\fR to advance the internal state machine. .RE .SH "SERVER SOCKETS" .PP @@ -120,6 +126,7 @@ network address notation, of the client's host, and the client's port number. .PP The following additional option may also be specified before \fIport\fR: +.\" OPTION: -myaddr .TP \fB\-myaddr\fI addr\fR . @@ -131,11 +138,13 @@ wildcard address so that it can accept connections from any interface. If \fIaddr\fR is a domain name that resolves to multiple IP addresses that are available on the local machine, the socket will listen on all of them. +.\" OPTION: -reuseaddr .TP \fB\-reuseaddr\fI boolean\fR . Tells the kernel whether to reuse the local address if there is no socket actively listening on it. This is the default on Windows. +.\" OPTION: -reuseport .TP \fB\-reuseport\fI boolean\fR . @@ -164,6 +173,7 @@ described below. The \fBchan configure\fR command can be used to query several readonly configuration options for socket channels or in some cases to set alternative properties on socket channels: +.\" OPTION: -error .TP \fB\-error\fR . @@ -176,6 +186,7 @@ returned. If there was no error, an empty string is returned. Note that the error status is reset by the read operation; this mimics the underlying getsockopt(SO_ERROR) call. .RE +.\" OPTION: -sockname .TP \fB\-sockname\fR . @@ -193,6 +204,7 @@ was created without \fB\-myaddr\fR or with the argument to \fB\-myaddr\fR being a domain name that resolves multiple IP addresses that are local to the invoking host. .RE +.\" OPTION: -peername .TP \fB\-peername\fR . @@ -201,15 +213,19 @@ sockets, this option returns a list of three elements; these are the address, the host name and the port to which the peer socket is connected or bound. If the host name cannot be computed, the second element of the list is identical to the address, its first element. +.\" OPTION: -connecting .TP \fB\-connecting\fR . -This option is not supported by server sockets. For client sockets, this option returns 1 if an asyncroneous connect is still in progress, 0 otherwise. +This option is not supported by server sockets. For client sockets, this +option returns 1 if an asynchronous connect is still in progress, 0 otherwise. +.\" OPTION: -keepalive .TP \fB\-keepalive\fR . This option sets or queries the TCP keepalive option on the socket as 1 if keepalive is turned on, 0 otherwise. +.\" OPTION: -nodelay .TP \fB\-nodelay\fR . @@ -250,7 +266,8 @@ Support for IPv6 was added in Tcl 8.6. .SH "SEE ALSO" chan(n), flush(n), open(n), read(n) .SH KEYWORDS -asynchronous I/O, bind, channel, connection, domain name, host, network address, socket, tcp +asynchronous I/O, bind, channel, connection, domain name, host, +network address, socket, tcp '\" Local Variables: '\" mode: nroff '\" End: diff --git a/doc/source.n b/doc/source.n index 0364c41..a26507d 100644 --- a/doc/source.n +++ b/doc/source.n @@ -41,7 +41,8 @@ in code for string comparison, you can use which will be safely substituted by the Tcl interpreter into .QW ^Z . .PP -A leading BOM (Byte order mark) contained in the file is ignored for unicode encodings (utf-8, utf-16, ucs-2). +A leading BOM (Byte order mark) contained in the file is ignored for +unicode encodings (utf-8, utf-16, ucs-2). .PP The \fB\-encoding\fR option is used to specify the encoding of the data stored in \fIfileName\fR. When the \fB\-encoding\fR option diff --git a/doc/string.n b/doc/string.n index aefe485..987aeae 100644 --- a/doc/string.n +++ b/doc/string.n @@ -18,6 +18,7 @@ string \- Manipulate strings .PP Performs one of several string operations, depending on \fIoption\fR. The legal \fIoption\fRs (which may be abbreviated) are: +.\" METHOD: cat .TP \fBstring cat\fR ?\fIstring1\fR? ?\fIstring2...\fR? . @@ -32,6 +33,7 @@ of a concatenation without resorting to \fBreturn\fR \fB\-level 0\fR, and is more efficient than building a list of arguments and using \fBjoin\fR with an empty join string. .RE +.\" METHOD: compare .TP \fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length\fI length\fR? \fIstring1 string2\fR . @@ -42,6 +44,7 @@ than \fIstring2\fR. If \fB\-length\fR is specified, then only the first \fIlength\fR characters are used in the comparison. If \fB\-length\fR is negative, it is ignored. If \fB\-nocase\fR is specified, then the strings are compared in a case-insensitive manner. +.\" METHOD: equal .TP \fBstring equal\fR ?\fB\-nocase\fR? ?\fB\-length\fI length\fR? \fIstring1 string2\fR . @@ -51,6 +54,7 @@ identical, or 0 when not. If \fB\-length\fR is specified, then only the first \fIlength\fR characters are used in the comparison. If \fB\-length\fR is negative, it is ignored. If \fB\-nocase\fR is specified, then the strings are compared in a case-insensitive manner. +.\" METHOD: first .TP \fBstring first \fIneedleString haystackString\fR ?\fIstartIndex\fR? . @@ -75,6 +79,7 @@ will return \fB10\fR, but .PP will return \fB\-1\fR. .RE +.\" METHOD: index .TP \fBstring index \fIstring charIndex\fR . @@ -87,6 +92,7 @@ string. \fIcharIndex\fR may be specified as described in the If \fIcharIndex\fR is less than 0 or greater than or equal to the length of the string then this command returns an empty string. .RE +.\" METHOD: insert .TP \fBstring insert \fIstring index insertString\fR .VS "TIP 504" @@ -105,6 +111,7 @@ or after the end of \fIstring\fR (e.g., \fIindex\fR is \fBend\fR), \fIinsertString\fR is appended to \fIstring\fR. .RE .VE "TIP 504" +.\" METHOD: is .TP \fBstring is \fIclass\fR ?\fB\-strict\fR? ?\fB\-failindex \fIvarname\fR? \fIstring\fR . @@ -190,6 +197,7 @@ In the case of \fBboolean\fR, \fBtrue\fR and \fBfalse\fR, if the function will return 0, then the \fIvarname\fR will always be set to 0, due to the varied nature of a valid boolean value. .RE +.\" METHOD: last .TP \fBstring last \fIneedleString haystackString\fR ?\fIlastIndex\fR? . @@ -214,6 +222,7 @@ will return \fB10\fR, but .PP will return \fB1\fR. .RE +.\" METHOD: length .TP \fBstring length \fIstring\fR . @@ -222,6 +231,7 @@ Returns a decimal string giving the number of characters in number of bytes used to store the string. If the value is a byte array value (such as those returned from reading a binary encoded channel), then this will return the actual byte length of the value. +.\" METHOD: map .TP \fBstring map\fR ?\fB\-nocase\fR? \fImapping string\fR . @@ -253,8 +263,9 @@ reordered like this, .PP it will return the string \fB02c322c222c\fR. .RE +.\" METHOD: match .TP -\fBstring match\fR ?\fB\-nocase\fR? \fIpattern\fR \fIstring\fR +\fBstring match\fR ?\fB\-nocase\fR? \fIpattern string\fR . See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0 if it does not. If \fB\-nocase\fR is specified, then the pattern attempts @@ -287,6 +298,7 @@ Matches the single character \fIx\fR. This provides a way of avoiding the special interpretation of the characters \fB*?[]\e\fR in \fIpattern\fR. .RE +.\" METHOD: range .TP \fBstring range \fIstring first last\fR . @@ -301,12 +313,14 @@ it is treated as if it were zero, and if \fIlast\fR is greater than or equal to the length of the string then it is treated as if it were \fBend\fR. If \fIfirst\fR is greater than \fIlast\fR then an empty string is returned. +.\" METHOD: repeat .TP \fBstring repeat \fIstring count\fR . Returns a string consisting of \fIstring\fR concatenated with itself \fIcount\fR times. If \fIcount\fR is 0, the empty string will be returned. +.\" METHOD: replace .TP \fBstring replace \fIstring first last\fR ?\fInewstring\fR? . @@ -323,11 +337,13 @@ then it is treated as if it were \fBend\fR. The initial string is returned untouched, if \fIfirst\fR is greater than \fIlast\fR, or if \fIfirst\fR is equal to or greater than the length of the initial string, or \fIlast\fR is less than 0. +.\" METHOD: reverse .TP \fBstring reverse \fIstring\fR . Returns a string that is the same length as \fIstring\fR but with its characters in the reverse order. +.\" METHOD: tolower .TP \fBstring tolower \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? . @@ -337,6 +353,7 @@ specified, it refers to the first char index in the string to start modifying. If \fIlast\fR is specified, it refers to the char index in the string to stop at (inclusive). \fIfirst\fR and \fIlast\fR may be specified using the forms described in \fBSTRING INDICES\fR. +.\" METHOD: totitle .TP \fBstring totitle \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? . @@ -348,6 +365,7 @@ refers to the first char index in the string to start modifying. If \fIlast\fR is specified, it refers to the char index in the string to stop at (inclusive). \fIfirst\fR and \fIlast\fR may be specified using the forms described in \fBSTRING INDICES\fR. +.\" METHOD: toupper .TP \fBstring toupper \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? . @@ -357,6 +375,7 @@ specified, it refers to the first char index in the string to start modifying. If \fIlast\fR is specified, it refers to the char index in the string to stop at (inclusive). \fIfirst\fR and \fIlast\fR may be specified using the forms described in \fBSTRING INDICES\fR. +.\" METHOD: trim .TP \fBstring trim \fIstring\fR ?\fIchars\fR? . @@ -364,6 +383,7 @@ Returns a value equal to \fIstring\fR except that any leading or trailing characters present in the string given by \fIchars\fR are removed. If \fIchars\fR is not specified then white space is removed (any character for which \fBstring is space\fR returns 1, and "\e0"). +.\" METHOD: trimleft .TP \fBstring trimleft \fIstring\fR ?\fIchars\fR? . @@ -371,6 +391,7 @@ Returns a value equal to \fIstring\fR except that any leading characters present in the string given by \fIchars\fR are removed. If \fIchars\fR is not specified then white space is removed (any character for which \fBstring is space\fR returns 1, and "\e0"). +.\" METHOD: trimright .TP \fBstring trimright \fIstring\fR ?\fIchars\fR? . @@ -383,6 +404,7 @@ for which \fBstring is space\fR returns 1, and "\e0"). These subcommands are currently supported, but are likely to go away in a future release as their functionality is either virtually never used or highly misleading. +.\" METHOD: bytelength .TP \fBstring bytelength \fIstring\fR . @@ -424,6 +446,7 @@ and then apply \fBstring length\fR to that. .CE .RE .TP +.\" METHOD: wordend \fBstring wordend \fIstring charIndex\fR . Returns the index of the character just after the last one in the word @@ -432,6 +455,7 @@ may be specified using the forms in \fBSTRING INDICES\fR. A word is considered to be any contiguous range of alphanumeric (Unicode letters or decimal digits) or underscore (Unicode connector punctuation) characters, or any single character other than these. +.\" METHOD: wordstart .TP \fBstring wordstart \fIstring charIndex\fR . @@ -500,14 +524,14 @@ set length [\fBstring length\fR $string] if {$length == 0} { set isPrefix 0 } else { - set isPrefix [\fBstring equal\fR \-length $length $string "foobar"] + set isPrefix [\fBstring equal\fR -length $length $string "foobar"] } .CE .SH "SEE ALSO" expr(n), list(n) .SH KEYWORDS -case conversion, compare, index, integer value, match, pattern, string, word, equal, -ctype, character, reverse +case conversion, compare, index, integer value, match, pattern, string, +word, equal, ctype, character, reverse .\" Local Variables: .\" mode: nroff .\" End: diff --git a/doc/subst.n b/doc/subst.n index 4518140..4c9a519 100644 --- a/doc/subst.n +++ b/doc/subst.n @@ -158,7 +158,8 @@ not .SH "SEE ALSO" Tcl(n), eval(n), break(n), continue(n) .SH KEYWORDS -backslash substitution, command substitution, quoting, substitution, variable substitution +backslash substitution, command substitution, quoting, substitution, +variable substitution .\" Local Variables: .\" mode: nroff .\" End: diff --git a/doc/switch.n b/doc/switch.n index 70eeb09..d004c03 100644 --- a/doc/switch.n +++ b/doc/switch.n @@ -35,26 +35,31 @@ unless there are exactly two arguments to \fBswitch\fR (in which case the first must the \fIstring\fR and the second must be the \fIpattern\fR/\fIbody\fR list). The following options are currently supported: +.\" OPTION: -exact .TP 10 \fB\-exact\fR . Use exact matching when comparing \fIstring\fR to a pattern. This is the default. +.\" OPTION: -glob .TP 10 \fB\-glob\fR . When matching \fIstring\fR to the patterns, use glob-style matching (i.e. the same as implemented by the \fBstring match\fR command). +.\" OPTION: -regexp .TP 10 \fB\-regexp\fR . When matching \fIstring\fR to the patterns, use regular expression matching (as described in the \fBre_syntax\fR reference page). +.\" OPTION: -nocase .TP 10 \fB\-nocase\fR . Causes comparisons to be handled in a case-insensitive manner. +.\" OPTION: -matchvar .TP 10 \fB\-matchvar\fR \fIvarName\fR . @@ -68,6 +73,7 @@ capturing parenthesis in the regular expression that matched, and so on. When a \fBdefault\fR branch is taken, the variable will have the empty list written to it. This option may be specified at the same time as the \fB\-indexvar\fR option. +.\" OPTION: -indexvar .TP 10 \fB\-indexvar\fR \fIvarName\fR . @@ -85,6 +91,7 @@ capturing parenthesis in the regular expression that matched, and so on. When a \fBdefault\fR branch is taken, the variable will have the empty list written to it. This option may be specified at the same time as the \fB\-matchvar\fR option. +.\" OPTION: -- .TP 10 \fB\-\|\-\fR . @@ -128,7 +135,7 @@ literals, as shown here (the result is \fI2\fR): .PP .CS set foo "abc" -\fBswitch\fR abc a \- b {expr {1}} $foo {expr {2}} default {expr {3}} +\fBswitch\fR abc a - b {expr {1}} $foo {expr {2}} default {expr {3}} .CE .PP Using glob matching and the fall-through body is an alternative to @@ -136,8 +143,8 @@ writing regular expressions with alternations, as can be seen here (this returns \fI1\fR): .PP .CS -\fBswitch\fR \-glob aaab { - a*b \- +\fBswitch\fR -glob aaab { + a*b - b {expr {1}} a* {expr {2}} default {expr {3}} @@ -149,7 +156,7 @@ last) is taken. This example has a result of \fI3\fR: .PP .CS \fBswitch\fR xyz { - a \- + a - b { # Correct Comment Placement expr {1} @@ -167,7 +174,7 @@ When matching against regular expressions, information about what exactly matched is easily obtained using the \fB\-matchvar\fR option: .PP .CS -\fBswitch\fR \-regexp \-matchvar foo \-\- $bar { +\fBswitch\fR -regexp -matchvar foo -- $bar { a(b*)c { puts "Found [string length [lindex $foo 1]] 'b's" } diff --git a/doc/tclsh.1 b/doc/tclsh.1 index 965e76d..3ea9eb1 100644 --- a/doc/tclsh.1 +++ b/doc/tclsh.1 @@ -101,21 +101,25 @@ start up uniformly across different versions of Tcl. \fBTclsh\fR sets the following global Tcl variables in addition to those created by the Tcl library itself (such as \fBenv\fR, which maps environment variables such as \fBPATH\fR into Tcl): +.\" VARIABLE: argc .TP 15 \fBargc\fR . Contains a count of the number of \fIarg\fR arguments (0 if none), not including the name of the script file. +.\" VARIABLE: argv .TP 15 \fBargv\fR . Contains a Tcl list whose elements are the \fIarg\fR arguments, in order, or an empty string if there are no \fIarg\fR arguments. +.\" VARIABLE: argv0 .TP 15 \fBargv0\fR . Contains \fIfileName\fR if it was specified. Otherwise, contains the name by which \fBtclsh\fR was invoked. +.\" VARIABLE: tcl_interactive .TP 15 \fBtcl_interactive\fR . @@ -123,6 +127,8 @@ Contains 1 if \fBtclsh\fR is running interactively (no \fIfileName\fR was specified and standard input is a terminal-like device), 0 otherwise. .SH PROMPTS +.\" VARIABLE: tcl_prompt1 +.\" VARIABLE: tcl_prompt2 .PP When \fBtclsh\fR is invoked interactively it normally prompts for each command with diff --git a/doc/tcltest.n b/doc/tcltest.n index 965ed64..6fbf16b 100644 --- a/doc/tcltest.n +++ b/doc/tcltest.n @@ -490,6 +490,7 @@ description for regression tests. If the test case exists to reproduce a bug, include the bug ID in the description. .PP Valid attributes and associated values are: +.\" OPTION: -constraints .TP \fB\-constraints \fIkeywordList\fR|\fIexpression\fR . @@ -500,9 +501,12 @@ defined by a call to \fBtestConstraint\fR. If any of the listed constraints is false or does not exist, the test is skipped. If the \fB\-constraints\fR value is an expression, that expression is evaluated. If the expression evaluates to true, then the test is run. +.RS +.PP Note that the expression form of \fB\-constraints\fR may interfere with the operation of \fBconfigure \-constraints\fR and \fBconfigure \-limitconstraints\fR, and is not recommended. +.PP Appropriate constraints should be added to any tests that should not always be run. That is, conditional evaluation of a test should be accomplished by the \fB\-constraints\fR option, not by @@ -512,6 +516,8 @@ the number skipped may change based on the testing environment. The default value is an empty list. See \fBTEST CONSTRAINTS\fR below for a list of built-in constraints and information on how to add your own constraints. +.RE +.\" OPTION: -setup .TP \fB\-setup \fIscript\fR . @@ -519,6 +525,7 @@ The optional \fB\-setup\fR attribute indicates a \fIscript\fR that will be run before the script indicated by the \fB\-body\fR attribute. If evaluation of \fIscript\fR raises an error, the test will fail. The default value is an empty script. +.\" OPTION: -body .TP \fB\-body \fIscript\fR . @@ -528,6 +535,7 @@ If evaluation of \fIscript\fR raises an error, the test will fail (unless the \fB\-returnCodes\fR option is used to state that an error is expected). The default value is an empty script. +.\" OPTION: -cleanup .TP \fB\-cleanup \fIscript\fR . @@ -535,6 +543,7 @@ The optional \fB\-cleanup\fR attribute indicates a \fIscript\fR that will be run after the script indicated by the \fB\-body\fR attribute. If evaluation of \fIscript\fR raises an error, the test will fail. The default value is an empty script. +.\" OPTION: -match .TP \fB\-match \fImode\fR . @@ -543,12 +552,14 @@ The \fB\-match\fR attribute determines how expected answers supplied by values for \fImode\fR are \fBregexp\fR, \fBglob\fR, \fBexact\fR, and any value registered by a prior call to \fBcustomMatch\fR. The default value is \fBexact\fR. +.\" OPTION: -result .TP \fB\-result \fIexpectedValue\fR . The \fB\-result\fR attribute supplies the \fIexpectedValue\fR against which the return value from script will be compared. The default value is an empty string. +.\" OPTION: -output .TP \fB\-output \fIexpectedValue\fR . @@ -558,6 +569,7 @@ of the script(s) will be compared. Note that only output printed using the global \fBputs\fR command is used for comparison. If \fB\-output\fR is not specified, output sent to \fBstdout\fR and \fBoutputChannel\fR is not processed for comparison. +.\" OPTION: -errorOutput .TP \fB\-errorOutput \fIexpectedValue\fR . @@ -567,6 +579,7 @@ evaluation of the script(s) will be compared. Note that only output printed using the global \fBputs\fR command is used for comparison. If \fB\-errorOutput\fR is not specified, output sent to \fBstderr\fR and \fBerrorChannel\fR is not processed for comparison. +.\" OPTION: -returnCodes .TP \fB\-returnCodes \fIexpectedCodeList\fR . @@ -578,6 +591,7 @@ return codes known to \fBreturn\fR, in both numeric and symbolic form, including extended return codes, are acceptable elements in the \fIexpectedCodeList\fR. Default value is .QW "\fBok return\fR" . +.\" OPTION: -errorCode .TP \fB\-errorCode \fIexpectedErrorCode\fR . @@ -634,134 +648,82 @@ options. .PP The following is a list of constraints predefined by the \fBtcltest\fR package itself: -.TP -\fIsingleTestInterp\fR -. +.IP \fIsingleTestInterp\fR This test can only be run if all test files are sourced into a single interpreter. -.TP -\fIunix\fR -. +.IP \fIunix\fR This test can only be run on any Unix platform. -.TP -\fIwin\fR -. +.IP \fIwin\fR This test can only be run on any Windows platform. -.TP -\fInt\fR -. +.IP \fInt\fR This test can only be run on any Windows NT platform. -.TP -\fImac\fR -. +.IP \fImac\fR This test can only be run on any Mac platform. -.TP -\fIunixOrWin\fR -. +.IP \fIunixOrWin\fR This test can only be run on a Unix or Windows platform. -.TP -\fImacOrWin\fR -. +.IP \fImacOrWin\fR This test can only be run on a Mac or Windows platform. -.TP -\fImacOrUnix\fR -. +.IP \fImacOrUnix\fR This test can only be run on a Mac or Unix platform. -.TP -\fItempNotWin\fR -. +.IP \fItempNotWin\fR This test can not be run on Windows. This flag is used to temporarily disable a test. -.TP -\fItempNotMac\fR -. +.IP \fItempNotMac\fR This test can not be run on a Mac. This flag is used to temporarily disable a test. -.TP -\fIunixCrash\fR -. +.IP \fIunixCrash\fR This test crashes if it is run on Unix. This flag is used to temporarily disable a test. -.TP -\fIwinCrash\fR -. +.IP \fIwinCrash\fR This test crashes if it is run on Windows. This flag is used to temporarily disable a test. -.TP -\fImacCrash\fR -. +.IP \fImacCrash\fR This test crashes if it is run on a Mac. This flag is used to temporarily disable a test. -.TP -\fIemptyTest\fR -. +.IP \fIemptyTest\fR This test is empty, and so not worth running, but it remains as a place-holder for a test to be written in the future. This constraint has value false to cause tests to be skipped unless the user specifies otherwise. -.TP -\fIknownBug\fR -. +.IP \fIknownBug\fR This test is known to fail and the bug is not yet fixed. This constraint has value false to cause tests to be skipped unless the user specifies otherwise. -.TP -\fInonPortable\fR -. +.IP \fInonPortable\fR This test can only be run in some known development environment. Some tests are inherently non-portable because they depend on things like word length, file system configuration, window manager, etc. This constraint has value false to cause tests to be skipped unless the user specifies otherwise. -.TP -\fIuserInteraction\fR -. +.IP \fIuserInteraction\fR This test requires interaction from the user. This constraint has value false to causes tests to be skipped unless the user specifies otherwise. -.TP -\fIinteractive\fR -. +.IP \fIinteractive\fR This test can only be run in if the interpreter is in interactive mode -(when the global tcl_interactive variable is set to 1). -.TP -\fInonBlockFiles\fR -. +(when the global \fB::tcl_interactive\fR variable is set to 1). +.IP \fInonBlockFiles\fR This test can only be run if platform supports setting files into nonblocking mode. -.TP -\fIasyncPipeClose\fR -. +.IP \fIasyncPipeClose\fR This test can only be run if platform supports async flush and async close on a pipe. -.TP -\fIunixExecs\fR -. +.IP \fIunixExecs\fR This test can only be run if this machine has Unix-style commands \fBcat\fR, \fBecho\fR, \fBsh\fR, \fBwc\fR, \fBrm\fR, \fBsleep\fR, \fBfgrep\fR, \fBps\fR, \fBchmod\fR, and \fBmkdir\fR available. -.TP -\fIhasIsoLocale\fR -. +.IP \fIhasIsoLocale\fR This test can only be run if can switch to an ISO locale. -.TP -\fIroot\fR -. +.IP \fIroot\fR This test can only run if Unix user is root. -.TP -\fInotRoot\fR -. +.IP \fInotRoot\fR This test can only run if Unix user is not root. -.TP -\fIeformat\fR -. +.IP \fIeformat\fR This test can only run if app has a working version of sprintf with respect to the .QW e format of floating-point numbers. -.TP -\fIstdio\fR -. +.IP \fIstdio\fR This test can only be run if \fBinterpreter\fR can be \fBopen\fRed as a pipe. .PP @@ -846,12 +808,14 @@ command. .SH "CONFIGURABLE OPTIONS" The \fBconfigure\fR command is used to set and query the configurable options of \fBtcltest\fR. The valid options are: +.\" OPTION: -singleproc .TP \fB\-singleproc \fIboolean\fR . Controls whether or not \fBrunAllTests\fR spawns a child process for each test file. No spawning when \fIboolean\fR is true. Default value is false. +.\" OPTION: -debug .TP \fB\-debug \fIlevel\fR . @@ -877,6 +841,7 @@ that exist in the current namespace as they are used. Display information regarding what individual procs in the test harness are doing. .RE +.\" OPTION: -verbose .TP \fB\-verbose \fIlevel\fR . @@ -906,7 +871,7 @@ Print each test's execution time in milliseconds Print each test's execution time in microseconds .PP Note that the \fBmsec\fR and \fBusec\fR verbosity levels are provided as -indicative measures only. They do not tackle the problem of repeatibility which +indicative measures only. They do not tackle the problem of repeatability which should be considered in performance tests or benchmarks. To use these verbosity levels to thoroughly track performance degradations, consider wrapping your test bodies with \fBtime\fR commands. @@ -917,6 +882,7 @@ so that is the same as .QW "\fBconfigure \-verbose {pass start}\fR" . .RE +.\" OPTION: -preservecore .TP \fB\-preservecore \fIlevel\fR . @@ -934,11 +900,13 @@ Also check for core files at the end of each \fBtest\fR command. Check for core files at all times described above, and save a copy of each core file produced in \fBconfigure \-tmpdir\fR. .RE +.\" OPTION: -limitconstraints .TP \fB\-limitconstraints \fIboolean\fR . Sets the mode by which \fBtest\fR honors constraints as described in \fBTESTS\fR above. Default value is false. +.\" OPTION: -constraints .TP \fB\-constraints \fIlist\fR . @@ -946,6 +914,7 @@ Sets all the constraints in \fIlist\fR to true. Also used in combination with \fBconfigure \-limitconstraints true\fR to control an alternative constraint mode as described in \fBTESTS\fR above. Default value is an empty list. +.\" OPTION: -tmpdir .TP \fB\-tmpdir \fIdirectory\fR . @@ -954,17 +923,20 @@ Sets the temporary directory to be used by \fBmakeFile\fR, and \fBremoveDirectory\fR as the default directory where temporary files and directories created by test files should be created. Default value is \fBworkingDirectory\fR. +.\" OPTION: -testdir .TP \fB\-testdir \fIdirectory\fR . Sets the directory searched by \fBrunAllTests\fR for test files and subdirectories. Default value is \fBworkingDirectory\fR. +.\" OPTION: -file .TP \fB\-file \fIpatternList\fR . Sets the list of patterns used by \fBrunAllTests\fR to determine what test files to evaluate. Default value is .QW \fB*.test\fR . +.\" OPTION: -notfile .TP \fB\-notfile \fIpatternList\fR . @@ -972,6 +944,7 @@ Sets the list of patterns used by \fBrunAllTests\fR to determine what test files to skip. Default value is .QW \fBl.*.test\fR , so that any SCCS lock files are skipped. +.\" OPTION: -relateddir .TP \fB\-relateddir \fIpatternList\fR . @@ -979,40 +952,47 @@ Sets the list of patterns used by \fBrunAllTests\fR to determine what subdirectories to search for an \fBall.tcl\fR file. Default value is .QW \fB*\fR . +.\" OPTION: -asidefromdir .TP \fB\-asidefromdir \fIpatternList\fR . Sets the list of patterns used by \fBrunAllTests\fR to determine what subdirectories to skip when searching for an \fBall.tcl\fR file. Default value is an empty list. +.\" OPTION: -match .TP \fB\-match \fIpatternList\fR . Set the list of patterns used by \fBtest\fR to determine whether a test should be run. Default value is .QW \fB*\fR . +.\" OPTION: -skip .TP \fB\-skip \fIpatternList\fR . Set the list of patterns used by \fBtest\fR to determine whether a test should be skipped. Default value is an empty list. +.\" OPTION: -load .TP \fB\-load \fIscript\fR . Sets a script to be evaluated by \fBloadTestedCommands\fR. Default value is an empty script. +.\" OPTION: -loadfile .TP \fB\-loadfile \fIfilename\fR . Sets the filename from which to read a script to be evaluated by \fBloadTestedCommands\fR. This is an alternative to \fB\-load\fR. They cannot be used together. +.\" OPTION: -outfile .TP \fB\-outfile \fIfilename\fR . Sets the file to which all output produced by tcltest should be written. A file named \fIfilename\fR will be \fBopen\fRed for writing, and the resulting channel will be set as the value of \fBoutputChannel\fR. +.\" OPTION: -errfile .TP \fB\-errfile \fIfilename\fR . diff --git a/doc/tclvars.n b/doc/tclvars.n index 4d1413c..c883651 100644 --- a/doc/tclvars.n +++ b/doc/tclvars.n @@ -285,71 +285,48 @@ retrieve any relevant information. In addition, extensions and applications may add additional values to the array. The predefined elements are: .RS -.TP -\fBbyteOrder\fR -. +.IP \fBbyteOrder\fR The native byte order of this machine: either \fBlittleEndian\fR or \fBbigEndian\fR. -.TP -\fBdebug\fR -. +.IP \fBdebug\fR If this variable exists, then the interpreter was compiled with and linked to a debug-enabled C run-time. This variable will only exist on Windows, so extension writers can specify which package to load depending on the C run-time library that is in use. This is not an indication that this core contains symbols. -.TP -\fBengine\fR -. +.IP \fBengine\fR The name of the Tcl language implementation. When the interpreter is first created, this is always set to the string \fBTcl\fR. -.TP -\fBmachine\fR -. +.IP \fBmachine\fR The instruction set executed by this machine, such as \fBintel\fR, \fBPPC\fR, \fB68k\fR, or \fBsun4m\fR. On UNIX machines, this is the value returned by \fBuname -m\fR. -.TP -\fBos\fR -. +.IP \fBos\fR The name of the operating system running on this machine, such as \fBWindows NT\fR or \fBSunOS\fR. On UNIX machines, this is the value returned by \fBuname -s\fR. -.TP -\fBosVersion\fR -. +.IP \fBosVersion\fR The version number for the operating system running on this machine. On UNIX machines, this is the value returned by \fBuname -r\fR. -.TP -\fBpathSeparator\fR +.IP \fBpathSeparator\fR '\" Defined by TIP #315 The character that should be used to \fBsplit\fR PATH-like environment variables into their corresponding list of directory names. -.TP -\fBplatform\fR -. +.IP \fBplatform\fR Either \fBwindows\fR, or \fBunix\fR. This identifies the general operating environment of the machine. -.TP -\fBpointerSize\fR -. +.IP \fBpointerSize\fR This gives the size of the native-machine pointer in bytes (strictly, it is same as the result of evaluating \fIsizeof(void*)\fR in C.) -.TP -\fBthreaded\fR -. +.IP \fBthreaded\fR If this variable exists, then the interpreter was compiled with threads enabled. -.TP -\fBuser\fR -. +.IP \fBuser\fR This identifies the current user based on the login information available on the platform. This value comes from the getuid() and getpwuid() system calls on Unix, and the value from the GetUserName() system call on Windows. -.TP -\fBwordSize\fR -. +.IP \fBwordSize\fR This gives the size of the native-machine word in bytes (strictly, it is same as the result of evaluating \fIsizeof(long)\fR in C.) .RE @@ -434,6 +411,7 @@ tracking down suspected problems with the Tcl compiler. .RS This variable and functionality only exist if \fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation. +.\" tcl::unsupported::disassemble always works, but we don't document it .RE .TP \fBtcl_traceExec\fR @@ -472,6 +450,7 @@ selecting a word by double-clicking in text in Tk. It is platform dependent. On Windows, it defaults to \fB\eS\fR, meaning anything but a Unicode space character. Otherwise it defaults to \fB\ew\fR, which is any Unicode word character (number, letter, or underscore). +.\" VARIABLE: tcl_nonwordchars .TP \fBtcl_nonwordchars\fR . diff --git a/doc/timerate.n b/doc/timerate.n index 5d49c86..a334d81 100644 --- a/doc/timerate.n +++ b/doc/timerate.n @@ -11,11 +11,13 @@ .SH NAME timerate \- Calibrated performance measurements of script execution time .SH SYNOPSIS +.nf \fBtimerate \fIscript\fR ?\fItime\fR? ?\fImax-count\fR? .sp -\fBtimerate \fR?\fB\-direct\fR? ?\fB\-overhead\fI double\fR? \fIscript\fR ?\fItime\fR? ?\fImax-count\fR? +\fBtimerate \fR?\fB\-direct\fR? ?\fB\-overhead\fI estimate\fR? \fIscript\fR ?\fItime\fR? ?\fImax-count\fR? .sp \fBtimerate \fR?\fB\-calibrate\fR? ?\fB\-direct\fR? \fIscript\fR ?\fItime\fR? ?\fImax-count\fR? +.fi .BE .SH DESCRIPTION .PP @@ -32,12 +34,12 @@ application performance. The first and second form will evaluate \fIscript\fR until the interval \fItime\fR given in milliseconds elapses, or for 1000 milliseconds (1 second) if \fItime\fR is not specified. -.sp +.PP The parameter \fImax-count\fR could additionally impose a further restriction by the maximal number of iterations to evaluate the script. If \fImax-count\fR is specified, the evaluation will stop either this count of iterations is reached or the time is exceeded. -.sp +.PP It will then return a canonical Tcl-list of the form: .PP .CS @@ -46,15 +48,18 @@ It will then return a canonical Tcl-list of the form: .PP which indicates: .IP \(bu 3 -the average amount of time required per iteration, in microseconds ([\fBlindex\fR $result 0]) +the average amount of time required per iteration, in microseconds +([\fBlindex\fR $result 0]) .IP \(bu 3 the count how many times it was executed ([\fBlindex\fR $result 2]) .IP \(bu 3 the estimated rate per second ([\fBlindex\fR $result 4]) .IP \(bu 3 -the estimated real execution time without measurement overhead ([\fBlindex\fR $result 6]) +the estimated real execution time without measurement overhead +([\fBlindex\fR $result 6]) .PP The following options may be supplied to the \fBtimerate\fR command: +.\" OPTION: -calibrate .TP \fB\-calibrate\fR . @@ -66,31 +71,36 @@ for future invocations of the \fBtimerate\fR command. If the \fItime\fR parameter is not specified, the calibrate procedure runs for up to 10 seconds. .RS .PP -Note that calibration is not thread safe in the current implementation. +Note that the calibration process is not thread safe in the current +implementation. .RE +.\" OPTION: -overhead .TP -\fB\-overhead \fIdouble\fR +\fB\-overhead \fIestimate\fR . -The \fB\-overhead\fR parameter supplies an estimate (in microseconds) of the +The \fB\-overhead\fR parameter supplies an estimate (in microseconds, which may +be a floating point number) of the measurement overhead of each iteration of the tested script. This quantity will be subtracted from the measured time prior to reporting results. This can be useful for removing the cost of interpreter state reset commands from the script being measured. +.\" OPTION: -direct .TP \fB\-direct\fR . -The \fB-direct\fR option causes direct execution of the supplied script, +The \fB\-direct\fR option causes direct execution of the supplied script, without compilation, in a manner similar to the \fBtime\fR command. It can be used to measure the cost of \fBTcl_EvalObjEx\fR, of the invocation of canonical lists, and of the uncompiled versions of bytecoded commands. .PP -As opposed to the \fBtime\fR commmand, which runs the tested script for a fixed +As opposed to the \fBtime\fR command, which runs the tested script for a fixed number of iterations, the \fBtimerate\fR command runs it for a fixed time. Additionally, the compiled variant of the script will be used during the entire -measurement, as if the script were part of a compiled procedure, if the \fB\-direct\fR -option is not specified. The fixed time period and possibility of compilation allow -for more precise results and prevent very long execution times by slow scripts, making -it practical for measuring scripts with highly uncertain execution times. +measurement, as if the script were part of a compiled procedure, +if the \fB\-direct\fR option is not specified. The fixed time period and +possibility of compilation allow for more precise results and prevent very long +execution times by slow scripts, making it practical for measuring scripts with +highly uncertain execution times. .SH EXAMPLES Estimate how fast it takes for a simple Tcl \fBfor\fR loop (including operations on variable \fIi\fR) to count to ten: @@ -116,9 +126,9 @@ set i 0; \fBtimerate\fR -calibrate {expr {$i<10}; incr i} 1000 } 5000 .CE .PP -Estimate the speed of calculating the hour of the day using \fBclock format\fR only, -ignoring overhead of the portion of the script that prepares the time for it to -calculate: +Estimate the speed of calculating the hour of the day using \fBclock format\fR +only, ignoring overhead of the portion of the script that prepares the time for +it to calculate: .PP .CS \fI# calibrate\fR diff --git a/doc/trace.n b/doc/trace.n index 9b8fd57..8f3cc3d 100644 --- a/doc/trace.n +++ b/doc/trace.n @@ -89,10 +89,12 @@ an error will be thrown. one or more of the following items: .TP \fBenter\fR +. Invoke \fIcommandPrefix\fR whenever the command \fIname\fR is executed, just before the actual execution takes place. .TP \fBleave\fR +. Invoke \fIcommandPrefix\fR whenever the command \fIname\fR is executed, just after the actual execution takes place. .TP @@ -156,6 +158,7 @@ the result string. \fIOp\fR indicates what operation is being performed on the command execution, and is one of \fBleave\fR or \fBleavestep\fR as defined above. +.PP Note that the creation of many \fBenterstep\fR or \fBleavestep\fR traces can lead to unintuitive results, since the invoked commands from one trace can themselves lead to further @@ -187,6 +190,7 @@ The behavior of execution traces is currently undefined for a command .RE .TP \fBtrace add variable\fI name ops commandPrefix\fR +. Arrange for \fIcommandPrefix\fR to be executed whenever variable \fIname\fR is accessed in one of the ways given by the list \fIops\fR. \fIName\fR may refer to a normal variable, an element of an array, or to an array @@ -202,6 +206,7 @@ queries, but not to \fBinfo exists\fR queries. one or more of the following items: .TP \fBarray\fR +. Invoke \fIcommandPrefix\fR whenever the variable is accessed or modified via the \fBarray\fR command, provided that \fIname\fR is not a scalar variable at the time that the \fBarray\fR command is invoked. If @@ -209,12 +214,15 @@ variable at the time that the \fBarray\fR command is invoked. If command will not trigger the trace. .TP \fBread\fR +. Invoke \fIcommandPrefix\fR whenever the variable is read. .TP \fBwrite\fR +. Invoke \fIcommandPrefix\fR whenever the variable is written. .TP \fBunset\fR +. Invoke \fIcommandPrefix\fR whenever the variable is unset. Variables can be unset explicitly with the \fBunset\fR command, or implicitly when procedures return (all of their local variables @@ -304,10 +312,12 @@ This command returns an empty string. .RE .TP \fBtrace remove \fItype name opList commandPrefix\fR +. Where \fItype\fR is either \fBcommand\fR, \fBexecution\fR or \fBvariable\fR. .RS .TP \fBtrace remove command\fI name opList commandPrefix\fR +. If there is a trace set on command \fIname\fR with the operations and command given by \fIopList\fR and \fIcommandPrefix\fR, then the trace is removed, so that \fIcommandPrefix\fR will never again be invoked. Returns @@ -315,6 +325,7 @@ an empty string. If \fIname\fR does not exist, the command will throw an error. .TP \fBtrace remove execution\fI name opList commandPrefix\fR +. If there is a trace set on command \fIname\fR with the operations and command given by \fIopList\fR and \fIcommandPrefix\fR, then the trace is removed, so that \fIcommandPrefix\fR will never again be invoked. Returns @@ -322,6 +333,7 @@ an empty string. If \fIname\fR does not exist, the command will throw an error. .TP \fBtrace remove variable\fI name opList commandPrefix\fR +. If there is a trace set on variable \fIname\fR with the operations and command given by \fIopList\fR and \fIcommandPrefix\fR, then the trace is removed, so that \fIcommandPrefix\fR will never again be invoked. Returns @@ -329,10 +341,12 @@ an empty string. .RE .TP \fBtrace info \fItype name\fR +. Where \fItype\fR is either \fBcommand\fR, \fBexecution\fR or \fBvariable\fR. .RS .TP \fBtrace info command\fI name\fR +. Returns a list containing one element for each trace currently set on command \fIname\fR. Each element of the list is itself a list containing two elements, which are the \fIopList\fR and \fIcommandPrefix\fR @@ -341,6 +355,7 @@ then the result of the command will be an empty string. If \fIname\fR does not exist, the command will throw an error. .TP \fBtrace info execution\fI name\fR +. Returns a list containing one element for each trace currently set on command \fIname\fR. Each element of the list is itself a list containing two elements, which are the \fIopList\fR and \fIcommandPrefix\fR @@ -349,6 +364,7 @@ then the result of the command will be an empty string. If \fIname\fR does not exist, the command will throw an error. .TP \fBtrace info variable\fI name\fR +. Returns a list containing one element for each trace currently set on variable \fIname\fR. Each element of the list is itself a list containing two elements, which are the \fIopList\fR and \fIcommandPrefix\fR diff --git a/doc/transchan.n b/doc/transchan.n index b9a0f21..abae7b9 100644 --- a/doc/transchan.n +++ b/doc/transchan.n @@ -12,7 +12,7 @@ transchan \- command handler API of channel transforms .SH SYNOPSIS .nf -\fBchan push \fIchannelName cmdPrefix\fR +\fBchan push \fIchannelId cmdPrefix\fR \fIcmdPrefix \fBclear \fIhandle\fR \fIcmdPrefix \fBdrain \fIhandle\fR @@ -44,6 +44,7 @@ create the transformation. .SS "GENERIC SUBCOMMANDS" .PP The following subcommands are relevant to all types of channel. +.\" METHOD: clear .TP \fIcmdPrefix \fBclear \fIhandle\fR . @@ -51,6 +52,7 @@ This optional subcommand is called to signify to the transformation that any data stored in internal buffers (either incoming or outgoing) must be cleared. It is called when a \fBchan seek\fR is performed on the channel being transformed. +.\" METHOD: finalize .TP \fIcmdPrefix \fBfinalize \fIhandle\fR . @@ -59,6 +61,7 @@ never again, and it exists to allow for cleaning up any Tcl-level data structures associated with the transformation. \fIWarning!\fR Any errors thrown by this subcommand will be ignored. It is not guaranteed to be called if the interpreter is deleted. +.\" METHOD: initialize .TP \fIcmdPrefix \fBinitialize \fIhandle mode\fR . @@ -67,13 +70,9 @@ This mandatory subcommand is called first, and then never again (for the given transformation at the Tcl level. The \fImode\fR is a list containing any of \fBread \fRand \fBwrite\fR. .RS -.TP -\fBwrite\fR -. +.IP \fBwrite\fR implies that the channel is writable. -.TP -\fBread\fR -. +.IP \fBread\fR implies that the channel is readable. .PP The return value of the subcommand should be a list containing the names of @@ -86,6 +85,7 @@ as error thrown by \fBchan push\fR. These subcommands are used for handling transformations applied to readable channels; though strictly \fBread \fRis optional, it must be supported if any of the others is or the channel will be made non-readable. +.\" METHOD: drain .TP \fIcmdPrefix \fBdrain \fIhandle\fR . @@ -100,6 +100,7 @@ In other words, when this method is called the transformation cannot defer the actual transformation operation anymore and has to transform all data waiting in its internal read buffers and return the result of that action. .RE +.\" METHOD: limit? .TP \fIcmdPrefix \fBlimit? \fIhandle\fR . @@ -108,6 +109,7 @@ how far ahead it should read. If present, it should return an integer number greater than zero which indicates how many bytes ahead should be read, or an integer less than zero to indicate that the I/O engine may read as far ahead as it likes. +.\" METHOD: read .TP \fIcmdPrefix \fBread \fIhandle buffer\fR . @@ -131,6 +133,7 @@ defer the actual transformation until it has more data. These subcommands are used for handling transformations applied to writable channels; though strictly \fBwrite\fR is optional, it must be supported if any of the others is or the channel will be made non-writable. +.\" METHOD: flush .TP \fIcmdPrefix \fBflush \fIhandle\fR . @@ -145,6 +148,7 @@ In other words, when this subcommand is called the transformation cannot defer the actual transformation operation anymore and has to transform all data waiting in its internal write buffers and return the result of that action. .RE +.\" METHOD: write .TP \fIcmdPrefix \fBwrite \fIhandle buffer\fR . diff --git a/doc/unload.n b/doc/unload.n index 00b709b..dfa823b 100644 --- a/doc/unload.n +++ b/doc/unload.n @@ -36,16 +36,19 @@ interpreter in which the \fBunload\fR command was invoked. If the initial arguments to \fBunload\fR start with \fB\-\fR then they are treated as switches. The following switches are currently supported: +.\" OPTION: -nocomplain .TP \fB\-nocomplain\fR . Suppresses all error messages. If this switch is given, \fBunload\fR will never report an error. +.\" OPTION: -keeplibrary .TP \fB\-keeplibrary\fR . This switch will prevent \fBunload\fR from issuing the operating system call that will unload the library from the process. +.\" OPTION: -- .TP \fB\-\|\-\fR . @@ -81,10 +84,10 @@ instead of \fIpkg\fB_Unload\fR. If \fBunload\fR determines that a library is not unloadable (or unload functionality has been disabled during compilation), an error will be returned. If the library is unloadable, then \fBunload\fR will call the unload -procedure. If the unload procedure returns \fBTCL_OK\fR, \fBunload\fR will proceed -and decrease the proper reference count (depending on the target interpreter -type). When both reference counts have reached 0, the library will be -detached from the process. +procedure. If the unload procedure returns \fBTCL_OK\fR, \fBunload\fR will +proceed and decrease the proper reference count (depending on the target +interpreter type). When both reference counts have reached 0, the library will +be detached from the process. .SS "UNLOAD HOOK PROTOTYPE" .PP The unload procedure must match the following prototype: @@ -130,7 +133,7 @@ For example, the command \fBunload libxyz4.2.so\fR uses the prefix prefix \fBLast\fR. .SH "PORTABILITY ISSUES" .TP -\fBUnix\fR\0\0\0\0\0 +\fBUnix\fR . Not all unix operating systems support library unloading. Under such an operating system \fBunload\fR returns an error (unless \fB\-nocomplain\fR diff --git a/doc/uplevel.n b/doc/uplevel.n index cda1652..8687416 100644 --- a/doc/uplevel.n +++ b/doc/uplevel.n @@ -26,7 +26,8 @@ it gives a distance (up the procedure calling stack) to move before executing the command. If \fIlevel\fR consists of \fB#\fR followed by a integer then the level gives an absolute level. If \fIlevel\fR is omitted then it defaults to \fB1\fR. \fILevel\fR cannot be -defaulted if the first \fIcommand\fR argument is an integer or starts with \fB#\fR. +defaulted if the first \fIcommand\fR argument is an integer or starts +with \fB#\fR. .PP For example, suppose that procedure \fBa\fR was invoked from top-level, and that it called \fBb\fR, and that \fBb\fR called \fBc\fR. diff --git a/doc/vwait.n b/doc/vwait.n index e595a74..fde41f6 100644 --- a/doc/vwait.n +++ b/doc/vwait.n @@ -28,52 +28,63 @@ namespace's variables if the fully-qualified name is given. .PP In the second more complex command form \fIoptions\fR allow for finer control of the wait operation and to deal with multiple event sources. -\fIOptions\fR can be made up of +\fIOptions\fR can be made up of: +.\" OPTION: -- .TP \fB\-\-\fR . Marks the end of options. All following arguments are handled as variable names. +.\" OPTION: -all .TP \fB\-all\fR . All conditions for the wait operation must be met to complete the wait operation. Otherwise (the default) the first event completes the wait. +.\" OPTION: -extended .TP \fB\-extended\fR . An extended result in list form is returned, see below for explanation. +.\" OPTION: -nofileevents .TP \fB\-nofileevents\fR . File events are not handled in the wait operation. +.\" OPTION: -noidleevents .TP \fB\-noidleevents\fR . Idle handlers are not invoked during the wait operation. +.\" OPTION: -notimerevents .TP \fB\-notimerevents\fR . Timer handlers are not serviced during the wait operation. +.\" OPTION: -nowindowevents .TP \fB\-nowindowevents\fR . Events of the windowing system are not handled during the wait operation. +.\" OPTION: -readable .TP \fB\-readable\fR \fIchannel\fR . \fIChannel\fR must name a Tcl channel open for reading. If \fIchannel\fR is or becomes readable the wait operation completes. +.\" OPTION: -timeout .TP \fB\-timeout\fR \fImilliseconds\fR . The wait operation is constrained to \fImilliseconds\fR. +.\" OPTION: -variable .TP \fB\-variable\fR \fIvarName\fR . \fIVarName\fR must be the name of a global variable. Writing or unsetting this variable completes the wait operation. +.\" OPTION: -writable .TP \fB\-writable\fR \fIchannel\fR . @@ -81,11 +92,11 @@ unsetting this variable completes the wait operation. is or becomes writable the wait operation completes. .PP The result returned by \fBvwait\fR is for the simple form an empty -string. If the \fI\-timeout\fR option is specified, the result is the +string. If the \fB\-timeout\fR option is specified, the result is the number of milliseconds remaining when the wait condition has been met, or -1 if the wait operation timed out. .PP -If the \fI\-extended\fR option is specified, the result is made up +If the \fB\-extended\fR option is specified, the result is made up of a Tcl list with an even number of elements. Odd elements take the values \fBreadable\fR, \fBtimeleft\fR, \fBvariable\fR, and \fBwritable\fR. Even elements are the corresponding variable diff --git a/doc/while.n b/doc/while.n index 6acc909..bacc782 100644 --- a/doc/while.n +++ b/doc/while.n @@ -30,7 +30,7 @@ commands may be executed inside \fIbody\fR to cause immediate termination of the \fBwhile\fR command. The \fBwhile\fR command always returns an empty string. .PP -Note: \fItest\fR should almost always be enclosed in braces. If not, +Note that \fItest\fR should almost always be enclosed in braces. If not, variable substitutions will be made before the \fBwhile\fR command starts executing, which means that variable changes made by the loop body will not be considered in the expression. diff --git a/doc/zipfs.3 b/doc/zipfs.3 index 571647f..0c2773c 100644 --- a/doc/zipfs.3 +++ b/doc/zipfs.3 @@ -83,7 +83,7 @@ example, the Tcl 8.7.2 release would be searched for in a file On Windows, \fBTclZipfs_AppHook\fR has a slightly different signature, since it uses WCHAR instead of char. As a result, it requires your application to be compiled with the UNICODE preprocessor symbol defined (e.g., via the -\fB-DUNICODE\fR compiler flag). +\fB\-DUNICODE\fR compiler flag). .PP The result of \fBTclZipfs_AppHook\fR is the full Tcl version with build information (e.g., \fB8.7.0+abcdef...abcdef.gcc-1002\fR). diff --git a/doc/zipfs.n b/doc/zipfs.n index 9776590..dc53ea6 100644 --- a/doc/zipfs.n +++ b/doc/zipfs.n @@ -16,7 +16,7 @@ zipfs \- Mount and work with ZIP files within Tcl .nf \fBpackage require tcl::zipfs \fR?\fB1.0\fR? .sp -\fBzipfs canonical\fR ?\fImntpnt\fR? \fIfilename\fR ?\fIZIPFS\fR? +\fBzipfs canonical\fR ?\fImountpoint\fR? \fIfilename\fR ?\fIZIPFS\fR? \fBzipfs exists\fR \fIfilename\fR \fBzipfs find\fR \fIdirectoryName\fR \fBzipfs info\fR \fIfilename\fR @@ -83,18 +83,18 @@ the compressed size of the file, and .IP (4) the offset of the compressed data in the ZIP archive file. .PP -As a special case, querying the mount point gives the start of the zip data as the offset -in (4), which can be used to truncate the zip information from an executable. -Querying an ancestor of a mount point will raise an error. +As a special case, querying the mount point gives the start of the zip data +as the offset in (4), which can be used to truncate the zip information from +an executable. Querying an ancestor of a mount point will raise an error. .RE .TP \fBzipfs list\fR ?(\fB\-glob\fR|\fB\-regexp\fR)? ?\fIpattern\fR? . If \fIpattern\fR is not specified, the command returns a list of files across all zipfs mounted archives. If \fIpattern\fR is specified, only those paths -matching the pattern are returned. By default, or with the \fB-glob\fR option, +matching the pattern are returned. By default, or with the \fB\-glob\fR option, the pattern is treated as a glob pattern and matching is done as described for -the \fBstring match\fR command. Alternatively, the \fB-regexp\fR option may be +the \fBstring match\fR command. Alternatively, the \fB\-regexp\fR option may be used to specify matching \fBpattern\fR as a regular expression. The file names are returned in arbitrary order. Note that path separators are treated as ordinary characters in the matching. Thus forward slashes should be used @@ -118,10 +118,10 @@ mount points to the path of the corresponding ZIP archive. In the single argument form, the command returns the file path of the ZIP archive mounted at the specified mount point. .PP -In the third form, the command mounts the ZIP archive \fIzipfile\fR as a Tcl virtual -filesystem at \fImountpoint\fR. After this command executes, files contained -in \fIzipfile\fR will appear to Tcl to be regular files at the mount point. -If \fImountpoint\fR is +In the third form, the command mounts the ZIP archive \fIzipfile\fR as a Tcl +virtual filesystem at \fImountpoint\fR. After this command executes, files +contained in \fIzipfile\fR will appear to Tcl to be regular files at the +mount point. If \fImountpoint\fR is specified as an empty string, it is defaulted to the \fB[zipfs root]\fR. The command returns the normalized mount point path. .PP @@ -47,37 +47,23 @@ have been in gzip format. If \fB\-headerVar\fR is given, store a dictionary describing the contents of the gzip header in the variable called \fIvarName\fR. The keys of the dictionary that may be present are: .RS -.TP -\fBcomment\fR -. +.IP \fBcomment\fR The comment field from the header, if present. -.TP -\fBcrc\fR -. +.IP \fBcrc\fR A boolean value describing whether a CRC of the header is computed. -.TP -\fBfilename\fR -. +.IP \fBfilename\fR The filename field from the header, if present. -.TP -\fBos\fR -. +.IP \fBos\fR The operating system type code field from the header (if not the QW unknown value). See RFC 1952 for the meaning of these codes. -.TP -\fBsize\fR -. +.IP \fBsize\fR The size of the uncompressed data. -.TP -\fBtime\fR -. +.IP \fBtime\fR The time field from the header if non-zero, expected to be time that the file named by the \fBfilename\fR field was modified. Suitable for use with \fBclock format\fR. -.TP -\fBtype\fR -. +.IP \fBtype\fR The type of the uncompressed data (\fBbinary\fR or \fBtext\fR) if known. .RE .TP @@ -89,33 +75,21 @@ If \fB\-level\fR is given, \fIlevel\fR gives the compression level to use is given, \fIdict\fR is a dictionary containing values used for the gzip header. The following keys may be defined: .RS -.TP -\fBcomment\fR -. +.IP \fBcomment\fR Add the given comment to the header of the gzip-format data. -.TP -\fBcrc\fR -. +.IP \fBcrc\fR A boolean saying whether to compute a CRC of the header. Note that if the data is to be interchanged with the \fBgzip\fR program, a header CRC should \fInot\fR be computed. -.TP -\fBfilename\fR -. +.IP \fBfilename\fR The name of the file that the data to be compressed came from. -.TP -\fBos\fR -. +.IP \fBos\fR The operating system type code, which should be one of the values described in RFC 1952. -.TP -\fBtime\fR -. +.IP \fBtime\fR The time that the file named in the \fBfilename\fR key was last modified. This will be in the same as is returned by \fBclock seconds\fR or \fBfile mtime\fR. -.TP -\fBtype\fR -. +.IP \fBtype\fR The type of the data being compressed, being \fBbinary\fR or \fBtext\fR. .RE .TP @@ -134,34 +108,22 @@ The transformation can be removed again with \fBchan pop\fR. The \fImode\fR argument determines what type of transformation is pushed; the following are supported: .RS -.TP -\fBcompress\fR -. +.IP \fBcompress\fR The transformation will be a compressing transformation that produces zlib-format data on \fIchannel\fR, which must be writable. -.TP -\fBdecompress\fR -. +.IP \fBdecompress\fR The transformation will be a decompressing transformation that reads zlib-format data from \fIchannel\fR, which must be readable. -.TP -\fBdeflate\fR -. +.IP \fBdeflate\fR The transformation will be a compressing transformation that produces raw compressed data on \fIchannel\fR, which must be writable. -.TP -\fBgunzip\fR -. +.IP \fBgunzip\fR The transformation will be a decompressing transformation that reads gzip-format data from \fIchannel\fR, which must be readable. -.TP -\fBgzip\fR -. +.IP \fBgzip\fR The transformation will be a compressing transformation that produces gzip-format data on \fIchannel\fR, which must be writable. -.TP -\fBinflate\fR -. +.IP \fBinflate\fR The transformation will be a decompressing transformation that reads raw compressed data from \fIchannel\fR, which must be readable. .PP @@ -169,6 +131,7 @@ The following options may be set when creating a transformation via the .QW "\fIoptions ...\fR" to the \fBzlib push\fR command: +.\" OPTION: -dictionary .TP \fB\-dictionary\fI binData\fR .VS "TIP 400" @@ -180,16 +143,19 @@ with the most commonly used strings preferably put towards the end of the dictionary. Tcl provides no mechanism for choosing a good such dictionary for a particular data sequence. .VE +.\" OPTION: -header .TP \fB\-header\fI dictionary\fR . Passes a description of the gzip header to create, in the same format that \fBzlib gzip\fR understands. +.\" OPTION: -level .TP \fB\-level\fI compressionLevel\fR . How hard to compress the data. Must be an integer from 0 (uncompressed) to 9 (maximally compressed). +.\" OPTION: -limit .TP \fB\-limit\fI readaheadLimit\fR . @@ -209,6 +175,7 @@ to further readers. Both compressing and decompressing channel transformations add extra configuration options that may be accessed through \fBchan configure\fR. The options are: +.\" OPTION: -checksum .TP \fB\-checksum\fI checksum\fR . @@ -216,6 +183,7 @@ This read-only option gets the current checksum for the uncompressed data that the compression engine has seen so far. It is valid for both compressing and decompressing transforms, but not for the raw inflate and deflate formats. The compression algorithm depends on what format is being produced or consumed. +.\" OPTION: -dictionary .TP \fB\-dictionary\fI binData\fR .VS "TIP 400" @@ -227,6 +195,7 @@ the transformation is stacked. Note that this cannot be used to get the current active compression dictionary mid-stream, as that information is not exposed by the underlying library. .VE +.\" OPTION: -flush .TP \fB\-flush\fI type\fR . @@ -236,12 +205,14 @@ underlying channel. It is only valid for compressing transformations. The expensive flush respectively. Flushing degrades the compression ratio, but makes it easier for a decompressor to recover more of the file in the case of data corruption. +.\" OPTION: -header .TP \fB\-header\fI dictionary\fR . This read-only option, only valid for decompressing transforms that are processing gzip-format data, returns the dictionary describing the header read off the data stream. +.\" OPTION: -limit .TP \fB\-limit\fI readaheadLimit\fR . @@ -386,12 +357,14 @@ buffers while applying the transformation. The following \fIoption\fRs are supported (or an unambiguous prefix of them), which are used to modify the way in which the transformation is applied: .RS +.\" OPTION: -dictionary .TP \fB\-dictionary\fI binData\fR .VS "TIP 400" Sets the compression dictionary to use when working with compressing or decompressing the data to be \fIbinData\fR. .VE +.\" OPTION: -finalize .TP \fB\-finalize\fR . @@ -405,6 +378,7 @@ of the stream with the \fBget\fR subcommand. This option is mutually exclusive with the \fB\-flush\fR and \fB\-fullflush\fR options. .RE +.\" OPTION: -flush .TP \fB\-flush\fR . @@ -416,6 +390,7 @@ compressed so far, at some performance penalty. This option is mutually exclusive with the \fB\-finalize\fR and \fB\-fullflush\fR options. .RE +.\" OPTION: -fullflush .TP \fB\-fullflush\fR . |