diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/AddErrInfo.3 | 5 | ||||
| -rw-r--r-- | doc/CrtInterp.3 | 6 | ||||
| -rw-r--r-- | doc/CrtObjCmd.3 | 29 | ||||
| -rw-r--r-- | doc/Encoding.3 | 18 | ||||
| -rw-r--r-- | doc/Ensemble.3 | 4 | ||||
| -rw-r--r-- | doc/Eval.3 | 5 | ||||
| -rw-r--r-- | doc/Exit.3 | 3 | ||||
| -rw-r--r-- | doc/FileSystem.3 | 10 | ||||
| -rw-r--r-- | doc/FindExec.3 | 4 | ||||
| -rw-r--r-- | doc/GetInt.3 | 7 | ||||
| -rw-r--r-- | doc/Hash.3 | 2 | ||||
| -rw-r--r-- | doc/InitStubs.3 | 6 | ||||
| -rw-r--r-- | doc/InitSubSyst.3 | 31 | ||||
| -rw-r--r-- | doc/IntObj.3 | 19 | ||||
| -rw-r--r-- | doc/Interp.3 | 121 | ||||
| -rw-r--r-- | doc/LinkVar.3 | 146 | ||||
| -rw-r--r-- | doc/Method.3 | 44 | ||||
| -rw-r--r-- | doc/Notifier.3 | 32 | ||||
| -rw-r--r-- | doc/OpenTcp.3 | 18 | ||||
| -rw-r--r-- | doc/Panic.3 | 20 | ||||
| -rw-r--r-- | doc/RecEvalObj.3 | 2 | ||||
| -rw-r--r-- | doc/SaveResult.3 | 107 | ||||
| -rw-r--r-- | doc/SetResult.3 | 21 | ||||
| -rw-r--r-- | doc/StaticPkg.3 | 3 | ||||
| -rw-r--r-- | doc/StringObj.3 | 10 | ||||
| -rw-r--r-- | doc/Tcl.n | 13 | ||||
| -rw-r--r-- | doc/Tcl_Main.3 | 2 | ||||
| -rw-r--r-- | doc/Thread.3 | 12 | ||||
| -rw-r--r-- | doc/ToUpper.3 | 13 | ||||
| -rw-r--r-- | doc/TraceVar.3 | 33 | ||||
| -rw-r--r-- | doc/UniCharIsAlpha.3 | 2 | ||||
| -rw-r--r-- | doc/Utf.3 | 90 | ||||
| -rw-r--r-- | doc/abstract.n | 77 | ||||
| -rw-r--r-- | doc/append.n | 12 | ||||
| -rw-r--r-- | doc/array.n | 62 | ||||
| -rw-r--r-- | doc/binary.n | 362 | ||||
| -rw-r--r-- | doc/callback.n | 88 | ||||
| -rw-r--r-- | doc/catch.n | 6 | ||||
| -rw-r--r-- | doc/cd.n | 6 | ||||
| -rw-r--r-- | doc/chan.n | 10 | ||||
| -rw-r--r-- | doc/classvariable.n | 78 | ||||
| -rw-r--r-- | doc/clock.n | 43 | ||||
| -rw-r--r-- | doc/close.n | 4 | ||||
| -rw-r--r-- | doc/continue.n | 2 | ||||
| -rw-r--r-- | doc/cookiejar.n | 217 | ||||
| -rw-r--r-- | doc/coroutine.n | 108 | ||||
| -rw-r--r-- | doc/dde.n | 6 | ||||
| -rw-r--r-- | doc/define.n | 597 | ||||
| -rw-r--r-- | doc/dict.n | 55 | ||||
| -rw-r--r-- | doc/eof.n | 4 | ||||
| -rw-r--r-- | doc/exec.n | 2 | ||||
| -rw-r--r-- | doc/exit.n | 4 | ||||
| -rw-r--r-- | doc/expr.n | 456 | ||||
| -rw-r--r-- | doc/fblocked.n | 4 | ||||
| -rw-r--r-- | doc/file.n | 34 | ||||
| -rw-r--r-- | doc/fileevent.n | 4 | ||||
| -rw-r--r-- | doc/filename.n | 4 | ||||
| -rw-r--r-- | doc/flush.n | 4 | ||||
| -rw-r--r-- | doc/foreach.n | 4 | ||||
| -rw-r--r-- | doc/format.n | 29 | ||||
| -rw-r--r-- | doc/fpclassify.n | 83 | ||||
| -rw-r--r-- | doc/global.n | 4 | ||||
| -rw-r--r-- | doc/history.n | 4 | ||||
| -rw-r--r-- | doc/http.n | 115 | ||||
| -rw-r--r-- | doc/idna.n | 88 | ||||
| -rw-r--r-- | doc/incr.n | 9 | ||||
| -rw-r--r-- | doc/info.n | 651 | ||||
| -rw-r--r-- | doc/interp.n | 4 | ||||
| -rw-r--r-- | doc/join.n | 4 | ||||
| -rw-r--r-- | doc/lappend.n | 15 | ||||
| -rw-r--r-- | doc/lassign.n | 4 | ||||
| -rw-r--r-- | doc/library.n | 9 | ||||
| -rw-r--r-- | doc/lindex.n | 7 | ||||
| -rw-r--r-- | doc/link.n | 124 | ||||
| -rw-r--r-- | doc/linsert.n | 5 | ||||
| -rw-r--r-- | doc/list.n | 6 | ||||
| -rw-r--r-- | doc/llength.n | 9 | ||||
| -rw-r--r-- | doc/lmap.n | 5 | ||||
| -rw-r--r-- | doc/lpop.n | 97 | ||||
| -rw-r--r-- | doc/lrange.n | 9 | ||||
| -rw-r--r-- | doc/lremove.n | 57 | ||||
| -rw-r--r-- | doc/lrepeat.n | 9 | ||||
| -rw-r--r-- | doc/lreplace.n | 5 | ||||
| -rw-r--r-- | doc/lreverse.n | 5 | ||||
| -rw-r--r-- | doc/lsearch.n | 28 | ||||
| -rw-r--r-- | doc/lset.n | 5 | ||||
| -rw-r--r-- | doc/lsort.n | 7 | ||||
| -rw-r--r-- | doc/mathfunc.n | 81 | ||||
| -rw-r--r-- | doc/mathop.n | 67 | ||||
| -rw-r--r-- | doc/msgcat.n | 205 | ||||
| -rw-r--r-- | doc/my.n | 93 | ||||
| -rw-r--r-- | doc/namespace.n | 4 | ||||
| -rw-r--r-- | doc/next.n | 5 | ||||
| -rw-r--r-- | doc/open.n | 146 | ||||
| -rw-r--r-- | doc/package.n | 12 | ||||
| -rw-r--r-- | doc/packagens.n | 4 | ||||
| -rw-r--r-- | doc/pid.n | 5 | ||||
| -rw-r--r-- | doc/platform.n | 2 | ||||
| -rw-r--r-- | doc/platform_shell.n | 6 | ||||
| -rw-r--r-- | doc/prefix.n | 12 | ||||
| -rw-r--r-- | doc/process.n | 150 | ||||
| -rw-r--r-- | doc/puts.n | 4 | ||||
| -rw-r--r-- | doc/pwd.n | 4 | ||||
| -rw-r--r-- | doc/re_syntax.n | 6 | ||||
| -rw-r--r-- | doc/registry.n | 2 | ||||
| -rw-r--r-- | doc/regsub.n | 74 | ||||
| -rw-r--r-- | doc/rename.n | 4 | ||||
| -rw-r--r-- | doc/return.n | 2 | ||||
| -rw-r--r-- | doc/self.n | 7 | ||||
| -rw-r--r-- | doc/set.n | 4 | ||||
| -rw-r--r-- | doc/singleton.n | 99 | ||||
| -rw-r--r-- | doc/socket.n | 10 | ||||
| -rw-r--r-- | doc/source.n | 6 | ||||
| -rw-r--r-- | doc/string.n | 47 | ||||
| -rw-r--r-- | doc/tclsh.1 | 9 | ||||
| -rw-r--r-- | doc/tclvars.n | 2 | ||||
| -rw-r--r-- | doc/tell.n | 6 | ||||
| -rw-r--r-- | doc/trace.n | 3 | ||||
| -rw-r--r-- | doc/unknown.n | 4 | ||||
| -rw-r--r-- | doc/update.n | 4 | ||||
| -rw-r--r-- | doc/uplevel.n | 4 | ||||
| -rw-r--r-- | doc/while.n | 4 | ||||
| -rw-r--r-- | doc/zipfs.3 | 120 | ||||
| -rw-r--r-- | doc/zipfs.n | 254 |
124 files changed, 4620 insertions, 1339 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index caba125..5b0fe5a 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -119,7 +119,7 @@ retrieve the stack trace when script evaluation returns \fBTCL_ERROR\fR, like so: .PP .CS -int code = Tcl_Eval(interp, script); +int code = Tcl_EvalEx(interp, script, -1, 0); if (code == TCL_ERROR) { Tcl_Obj *options = \fBTcl_GetReturnOptions\fR(interp, code); Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1); @@ -247,6 +247,9 @@ record instead of a value. Otherwise, it is similar to .PP \fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that instead of taking a variable number of arguments it takes an argument list. +Interfaces using argument lists have been found to be nonportable in practice. +This function is deprecated and will be removed in Tcl 9.0. + .PP The procedure \fBTcl_GetErrorLine\fR is used to read the integer value of the \fB\-errorline\fR return option without the overhead of a full diff --git a/doc/CrtInterp.3 b/doc/CrtInterp.3 index 1d49158..aacb868 100644 --- a/doc/CrtInterp.3 +++ b/doc/CrtInterp.3 @@ -22,10 +22,8 @@ Tcl_Interp * int \fBTcl_InterpDeleted\fR(\fIinterp\fR) .sp -.VS 8.6 int \fBTcl_InterpActive\fR(\fIinterp\fR) -.VE 8.6 .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in @@ -70,14 +68,12 @@ deleted and when the whole interpreter is being deleted. In the former case the callback may recreate the data being deleted, but this would lead to an infinite loop if the interpreter were being deleted. .PP -.VS 8.6 \fBTcl_InterpActive\fR is useful for determining whether there is any execution of scripts ongoing in an interpreter, which is a useful piece of information when Tcl is embedded in a garbage-collected environment and it becomes necessary to determine whether the interpreter is a candidate for deletion. The function returns a true value if the interpreter has at least one active execution running inside it, and a false value otherwise. -.VE 8.6 .SH "INTERPRETERS AND MEMORY MANAGEMENT" .PP \fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may @@ -138,12 +134,10 @@ All uses of interpreters in Tcl and Tk have already been protected. Extension writers should ensure that their code also properly protects any additional interpreters used, as described above. .PP -.VS 8.6 Note that the protection mechanisms do not work well with conventional garbage collection systems. When in such a managed environment, \fBTcl_InterpActive\fR should be used to determine when an interpreter is a candidate for deletion due to inactivity. -.VE 8.6 .SH "SEE ALSO" Tcl_Preserve(3), Tcl_Release(3) .SH KEYWORDS diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 index 6714bd7..2cd9222 100644 --- a/doc/CrtObjCmd.3 +++ b/doc/CrtObjCmd.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj \- implement new commands in C +Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj, Tcl_RegisterCommandTypeName, Tcl_GetCommandTypeName \- implement new commands in C .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -42,6 +42,14 @@ void .sp Tcl_Command \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR) +.sp +.VS "info cmdtype feature" +void +\fBTcl_RegisterCommandTypeName\fR(\fIproc, typeName\fR) +.sp +const char * +\fBTcl_GetCommandTypeName\fR(\fItoken\fR) +.VE "info cmdtype feature" .SH ARGUMENTS .AS Tcl_CmdDeleteProc *deleteProc in/out .AP Tcl_Interp *interp in @@ -65,6 +73,9 @@ Pointer to structure containing various information about a Tcl command. .AP Tcl_Obj *objPtr in Value containing the name of a Tcl command. +.AP "const char" *typeName in +Indicates the name of the type of command implementation associated +with a particular \fIproc\fR, or NULL to break the association. .BE .SH DESCRIPTION .PP @@ -296,6 +307,22 @@ is appended to the value specified by \fIobjPtr\fR. specified by the name in a \fBTcl_Obj\fR. The command name is resolved relative to the current namespace. Returns NULL if the command is not found. +.PP +.VS "info cmdtype feature" +\fBTcl_RegisterCommandTypeName\fR is used to associate a name (the +\fItypeName\fR argument) with a particular implementation function so that it +can then be looked up with \fBTcl_GetCommandTypeName\fR, which in turn is +called with a command token that information is wanted for and which returns +the name of the type that was registered for the implementation function used +for that command. (The lookup functionality is surfaced virtually directly in Tcl via +\fBinfo cmdtype\fR.) If there is no function registered for a particular +function, the result will be the string literal +.QW \fBnative\fR . +The registration of a name can be undone by registering a mapping to NULL +instead. The result from \fBTcl_GetCommandTypeName\fR will be exactly that +string which was registered, and not a copy; use of a compile-time constant +string is \fIstrongly recommended\fR. +.VE "info cmdtype feature" .SH "SEE ALSO" Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3) .SH KEYWORDS diff --git a/doc/Encoding.3 b/doc/Encoding.3 index 79fca0f..2d2461e 100644 --- a/doc/Encoding.3 +++ b/doc/Encoding.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings +Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -255,11 +255,17 @@ is filled with the corresponding number of bytes that were stored in \fIdst\fR. The return values are the same as the return values for \fBTcl_ExternalToUtf\fR. .PP -\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are -Windows-only convenience -functions for converting between UTF-8 and Windows strings -based on the TCHAR type which is by convention -a Unicode character on Windows NT. +\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are Windows-only +convenience functions for converting between UTF-8 and Windows strings +based on the TCHAR type which is by convention a Unicode character on +Windows NT. Those functions are deprecated. You can use +\fBTcl_UtfToWCharDString\fR resp. \fBTcl_WCharToUtfDString\fR as replacement. +If you want compatibility with earlier Tcl releases than 8.7, use +\fBTcl_UtfToUniCharDString\fR resp. \fBTcl_UniCharToUtfDString\fR as +replacement, and make sure you compile your extension with -DTCL_UTF_MAX=3. +Beware: Those replacement functions don't initialize their Tcl_DString (you'll +have to do that yourself), and \fBTcl_UniCharToUtfDString\fR from Tcl 8.6 +doesn't accept -1 as length parameter. .PP \fBTcl_GetEncodingName\fR is roughly the inverse of \fBTcl_GetEncoding\fR. Given an \fIencoding\fR, the return value is the \fIname\fR argument that diff --git a/doc/Ensemble.3 b/doc/Ensemble.3 index 30c1d3b..febc48f 100644 --- a/doc/Ensemble.3 +++ b/doc/Ensemble.3 @@ -36,13 +36,11 @@ int int \fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR) .sp -.VS 8.6 int \fBTcl_GetEnsembleParameterList\fR(\fIinterp, token, listObjPtr\fR) .sp int \fBTcl_SetEnsembleParameterList\fR(\fIinterp, token, listObj\fR) -.VE 8.6 .sp int \fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR) @@ -163,7 +161,6 @@ All command names in prefixes set via \fBTcl_SetEnsembleMappingDict\fR must be fully qualified. .TP \fBformal pre-subcommand parameter list\fR (read-write) -.VS 8.6 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 @@ -174,7 +171,6 @@ respectively. The result of both of those functions is a Tcl result code ensemble) and the dictionary obtained from \fBTcl_GetEnsembleParameterList\fR should always be treated as immutable even if it is unshared. -.VE 8.6 .TP \fBsubcommand list\fR (read-write) . @@ -150,13 +150,14 @@ equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below). of any length, concatenates them into a single string, then calls \fBTcl_Eval\fR to execute that string as a Tcl command. It returns the result of the command and also modifies -\fIinterp->result\fR in the same way as \fBTcl_Eval\fR. +the interpreter result in the same way as \fBTcl_Eval\fR. The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end of arguments. \fBTcl_VarEval\fR is now deprecated. .PP \fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that instead of taking a variable number of arguments it takes an argument -list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated. +list. Interfaces using argument lists have been found to be nonportable +in practice. This function is deprecated and will be removed in Tcl 9.0. .SH "FLAG BITS" .PP @@ -134,6 +134,9 @@ finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an appropriate time. The argument passed to \fIproc\fR when it is invoked will be the exit status code (as passed to \fBTcl_Exit\fR) cast to a ClientData value. +.PP +\fBTcl_SetExitProc\fR can not be used in stub-enabled extensions. Its symbol +entry in the stub table is deprecated and it will be removed in Tcl 9.0. .SH "SEE ALSO" exit(n) .SH KEYWORDS diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index 28ee8f0..3b50232 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.3 @@ -63,10 +63,8 @@ int \fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr, loadHandlePtr, unloadProcPtr\fR) .sp -.VS 8.6 int \fBTcl_FSUnloadFile\fR(\fIinterp, loadHandle\fR) -.VE 8.6 .sp int \fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, pathPtr, pattern, types\fR) @@ -146,7 +144,6 @@ Tcl_Obj * Tcl_StatBuf * \fBTcl_AllocStatBuf\fR() .sp -.VS 8.6 Tcl_WideInt \fBTcl_GetAccessTimeFromStat\fR(\fIstatPtr\fR) .sp @@ -185,7 +182,6 @@ Tcl_WideUInt .sp int \fBTcl_GetUserIdFromStat\fR(\fIstatPtr\fR) -.VE 8.6 .SH ARGUMENTS .AS Tcl_GlobTypeData **srcPathPtr out .AP "const Tcl_Filesystem" *fsPtr in @@ -444,20 +440,16 @@ belongs will be called. If that filesystem does not implement this function (most virtual filesystems will not, because of OS limitations in dynamically loading binary code), Tcl will attempt to copy the file to a temporary directory and load that temporary file. -.VS 8.6 \fBTcl_FSUnloadFile\fR reverses the operation, asking for the library indicated by the \fIloadHandle\fR to be removed from the process. Note that, unlike with the \fBunload\fR command, this does not give the library any opportunity to clean up. -.VE 8.6 .PP Both the above functions return a standard Tcl completion code. If an error occurs, an error message is left in the \fIinterp\fR's result. .PP -.VS 8.6 The token provided via the variable indicated by \fIloadHandlePtr\fR may be used with \fBTcl_FindSymbol\fR. -.VE 8.6 .PP \fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a directory for all files which match a given pattern. The appropriate @@ -795,7 +787,6 @@ may be deallocated by being passed to \fBckfree\fR). This allows extensions to invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the size of the buffer. That in turn depends on the flags used to build Tcl. .PP -.VS 8.6 The portable fields of a \fITcl_StatBuf\fR may be read using the following functions, each of which returns the value of the corresponding field listed in the table below. Note that on some platforms there may be other fields in @@ -819,7 +810,6 @@ for a full description of these fields. \fBTcl_GetBlocksFromStat\fR st_blocks \fBTcl_GetBlockSizeFromStat\fR st_blksize .DE -.VE 8.6 .SH "THE VIRTUAL FILESYSTEM API" .PP A filesystem provides a \fBTcl_Filesystem\fR structure that contains diff --git a/doc/FindExec.3 b/doc/FindExec.3 index 1fd57db..149ef8a 100644 --- a/doc/FindExec.3 +++ b/doc/FindExec.3 @@ -58,6 +58,8 @@ internal full path name of the executable file as computed by equivalent to the \fBinfo nameofexecutable\fR command. NULL is returned if the internal full path name has not been computed or unknown. - +.PP +\fBTcl_FindExecutable\fR can not be used in stub-enabled extensions. Its symbol +entry in the stub table is deprecated and it will be removed in Tcl 9.0. .SH KEYWORDS binary, executable file diff --git a/doc/GetInt.3 b/doc/GetInt.3 index 5a3304a..eba549d 100644 --- a/doc/GetInt.3 +++ b/doc/GetInt.3 @@ -57,6 +57,9 @@ after the optional white space and sign are .QW \fB0x\fR then \fIsrc\fR is expected to be in hexadecimal form; otherwise, if the first such characters are +.QW \fB0d\fR +then \fIsrc\fR is expected to be in decimal form; otherwise, +if the first such characters are .QW \fB0o\fR then \fIsrc\fR is expected to be in octal form; otherwise, if the first such characters are @@ -65,8 +68,8 @@ then \fIsrc\fR is expected to be in binary form; otherwise, if the first such character is .QW \fB0\fR then \fIsrc\fR -is expected to be in octal form; otherwise, \fIsrc\fR is -expected to be in decimal form. +is expected to be in octal form; otherwise, \fIsrc\fR +is expected to be in decimal form. .PP \fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point number, which is: white space; a sign; a sequence of digits; a @@ -281,7 +281,7 @@ The \fIhashKeyProc\fR member contains the address of a function called to calculate a hash value for the key. .PP .CS -typedef unsigned int \fBTcl_HashKeyProc\fR( +typedef TCL_HASH_TYPE \fBTcl_HashKeyProc\fR( Tcl_HashTable *\fItablePtr\fR, void *\fIkeyPtr\fR); .CE diff --git a/doc/InitStubs.3 b/doc/InitStubs.3 index fbb3f56..4423666 100644 --- a/doc/InitStubs.3 +++ b/doc/InitStubs.3 @@ -23,11 +23,11 @@ Tcl interpreter handle. A version string consisting of one or more decimal numbers separated by dots. .AP int exact in -Non-zero means that only the particular version specified by +1 means that only the particular version specified by \fIversion\fR is acceptable. -Zero means that versions newer than \fIversion\fR are also +0 means that versions newer than \fIversion\fR are also acceptable as long as they have the same major version number -as \fIversion\fR. +as \fIversion\fR. Other bits have no effect. .BE .SH INTRODUCTION .PP diff --git a/doc/InitSubSyst.3 b/doc/InitSubSyst.3 new file mode 100644 index 0000000..3c138a4 --- /dev/null +++ b/doc/InitSubSyst.3 @@ -0,0 +1,31 @@ +'\" +'\" Copyright (c) 2018 Tcl Core Team +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.so man.macros +.TH Tcl_InitSubsystems 3 8.7 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_InitSubsystems \- initialize the Tcl library. +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +void +\fBTcl_InitSubsystems\fR(\fIvoid\fR) +.SH DESCRIPTION +.PP +The \fBTcl_InitSubsystems\fR procedure initializes the Tcl +library. This procedure is typically invoked as the very +first thing in the application's main program. +.PP +\fBTcl_InitSubsystems\fR is very similar in use to +\fBTcl_FindExecutable\fR. It can be used when Tcl is +used as utility library, no other encodings than utf8, +iso8859-1 or unicode are used, and no interest exists in the +value of \fBinfo nameofexecutable\fR. The system encoding will not +be extracted from the environment, but falls back to iso8859-1. +.SH KEYWORDS +binary, executable file diff --git a/doc/IntObj.3 b/doc/IntObj.3 index 2acb446..e793303 100644 --- a/doc/IntObj.3 +++ b/doc/IntObj.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers +Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -32,6 +32,9 @@ int \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR) .sp int +\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, intPtr\fR) +.sp +int \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR) .sp int @@ -55,6 +58,8 @@ int \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR) .SH ARGUMENTS .AS Tcl_WideInt doubleValue in/out +.AP int endValue in +\fBTcl_GetIntForIndex\fR will return this when the input value is "end". .AP int intValue in Integer value used to initialize or set a Tcl value. .AP long longValue in @@ -97,7 +102,7 @@ are provided by the C language standard. The \fBTcl_WideInt\fR type is a typedef defined to be whatever signed integral type covers at least the 64-bit integer range (-9223372036854775808 to 9223372036854775807). Depending on the platform and the C compiler, the actual type might be -\fBlong int\fR, \fBlong long int\fR, \fB__int64\fR, or something else. +\fBlong long int\fR, \fB__int64\fR, or something else. The \fBmp_int\fR type is a multiple-precision integer type defined by the LibTomMath multiple-precision integer library. .PP @@ -115,6 +120,16 @@ violates Tcl's copy-on-write policy. Any existing string representation or internal representation in the unshared Tcl value will be freed as a consequence of setting the new value. .PP +The \fBTcl_GetIntForIndex\fR routine attempts to retrieve an index +value from the Tcl value \fIobjPtr\fR. If the attempt succeeds, +then \fBTCL_OK\fR is returned, and the value is written to the +storage provided by the caller. The attempt might fail if +\fIobjPtr\fR does not hold an index value. If the attempt fails, +then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL, +an error message is left in \fIinterp\fR. The \fBTcl_ObjType\fR +of \fIobjPtr\fR may be changed to make subsequent calls to the +same routine more efficient. +.PP The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR, \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral diff --git a/doc/Interp.3 b/doc/Interp.3 index 731007b..c1b9803 100644 --- a/doc/Interp.3 +++ b/doc/Interp.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures" +.TH Tcl_Interp 3 8.7 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -15,9 +15,9 @@ Tcl_Interp \- client-visible fields of interpreter structures \fB#include <tcl.h>\fR .sp typedef struct { - char *\fIresult\fR; - Tcl_FreeProc *\fIfreeProc\fR; - int \fIerrorLine\fR; + char *\fIresult\fR; /* NO LONGER AVAILABLE */ + Tcl_FreeProc *\fIfreeProc\fR; /* NO LONGER AVAILABLE */ + int \fIerrorLine\fR; /* NO LONGER AVAILABLE */ } \fBTcl_Interp\fR; typedef void \fBTcl_FreeProc\fR( @@ -25,110 +25,17 @@ typedef void \fBTcl_FreeProc\fR( .BE .SH DESCRIPTION .PP -The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp +The \fBTcl_CreateInterp\fR procedure returns a pointer to a \fBTcl_Interp\fR structure. Callers of \fBTcl_CreateInterp\fR should use this pointer as an opaque token, suitable for nothing other than passing back to -other routines in the Tcl interface. Accessing fields directly through -the pointer as described below is no longer supported. The supported -public routines \fBTcl_SetResult\fR, \fBTcl_GetResult\fR, -\fBTcl_SetErrorLine\fR, \fBTcl_GetErrorLine\fR must be used instead. -.PP -For legacy programs and extensions no longer being maintained, compiles -against the Tcl 8.6 header files are only possible with the compiler -directives -.CS -#define USE_INTERP_RESULT -.CE -and/or -.CS -#define USE_INTERP_ERRORLINE -.CE -depending on which fields of the \fBTcl_Interp\fR struct are accessed. -These directives may be embedded in code or supplied via compiler options. -.PP -The \fIresult\fR and \fIfreeProc\fR fields are used to return -results or error messages from commands. -This information is returned by command procedures back to \fBTcl_Eval\fR, -and by \fBTcl_Eval\fR back to its callers. -The \fIresult\fR field points to the string that represents the -result or error message, and the \fIfreeProc\fR field tells how -to dispose of the storage for the string when it is not needed anymore. -The easiest way for command procedures to manipulate these -fields is to call procedures like \fBTcl_SetResult\fR -or \fBTcl_AppendResult\fR; they -will hide all the details of managing the fields. -The description below is for those procedures that manipulate the -fields directly. -.PP -Whenever a command procedure returns, it must ensure -that the \fIresult\fR field of its interpreter points to the string -being returned by the command. -The \fIresult\fR field must always point to a valid string. -If a command wishes to return no result then \fIinterp->result\fR -should point to an empty string. -Normally, results are assumed to be statically allocated, -which means that the contents will not change before the next time -\fBTcl_Eval\fR is called or some other command procedure is invoked. -In this case, the \fIfreeProc\fR field must be zero. -Alternatively, a command procedure may dynamically -allocate its return value (e.g. using \fBTcl_Alloc\fR) -and store a pointer to it in \fIinterp->result\fR. -In this case, the command procedure must also set \fIinterp->freeProc\fR -to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR -if the storage was allocated directly by Tcl or by a call to -\fBTcl_Alloc\fR. -If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR -to free the space pointed to by \fIinterp->result\fR before it -invokes the next command. -If a client procedure overwrites \fIinterp->result\fR when -\fIinterp->freeProc\fR is non-zero, then it is responsible for calling -\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR -macro should be used for this purpose). -.PP -\fIFreeProc\fR should have arguments and result that match the -\fBTcl_FreeProc\fR declaration above: it receives a single -argument which is a pointer to the result value to free. -In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever -used for \fIfreeProc\fR. -However, an application may store a different procedure address -in \fIfreeProc\fR in order to use an alternate memory allocator -or in order to do other cleanup when the result memory is freed. -.PP -As part of processing each command, \fBTcl_Eval\fR initializes -\fIinterp->result\fR -and \fIinterp->freeProc\fR just before calling the command procedure for -the command. The \fIfreeProc\fR field will be initialized to zero, -and \fIinterp->result\fR will point to an empty string. Commands that -do not return any value can simply leave the fields alone. -Furthermore, the empty string pointed to by \fIresult\fR is actually -part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200). -If a command wishes to return a short string, it can simply copy -it to the area pointed to by \fIinterp->result\fR. Or, it can use -the sprintf procedure to generate a short result string at the location -pointed to by \fIinterp->result\fR. -.PP -It is a general convention in Tcl-based applications that the result -of an interpreter is normally in the initialized state described -in the previous paragraph. -Procedures that manipulate an interpreter's result (e.g. by -returning an error) will generally assume that the result -has been initialized when the procedure is called. -If such a procedure is to be called after the result has been -changed, then \fBTcl_ResetResult\fR should be called first to -reset the result to its initialized state. The direct use of -\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR). -.PP -The \fIerrorLine\fR -field is valid only after \fBTcl_Eval\fR returns -a \fBTCL_ERROR\fR return code. In this situation the \fIerrorLine\fR -field identifies the line number of the command being executed when -the error occurred. The line numbers are relative to the command -being executed: 1 means the first line of the command passed to -\fBTcl_Eval\fR, 2 means the second line, and so on. -The \fIerrorLine\fR field is typically used in conjunction with -\fBTcl_AddErrorInfo\fR to report information about where an error -occurred. -\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR. +other routines in the Tcl interface from the same thread that called +\fBTcl_CreateInterp\fR. The \fBTcl_Interp\fR struct no longer has any +supported client-visible fields. Supported public routines such as +\fBTcl_SetResult\fR, \fBTcl_GetResult\fR, \fBTcl_SetErrorLine\fR, +\fBTcl_GetErrorLine\fR must be used instead. +.PP +Any legacy programs and extensions trying to access the fields above +in their source code will need conversion to compile for Tcl 8.7 and later. .SH KEYWORDS -free, initialized, interpreter, malloc, result +interpreter, result diff --git a/doc/LinkVar.3 b/doc/LinkVar.3 index c80d30d..92e7d03 100644 --- a/doc/LinkVar.3 +++ b/doc/LinkVar.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable +Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -17,27 +17,52 @@ Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variab int \fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR) .sp +.VS "TIP 312" +int +\fBTcl_LinkArray\fR(\fIinterp, varName, addr, type, size\fR) +.VE "TIP 312" +.sp \fBTcl_UnlinkVar\fR(\fIinterp, varName\fR) .sp \fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR) .SH ARGUMENTS -.AS Tcl_Interp writable +.AS Tcl_Interp varName in .AP Tcl_Interp *interp in Interpreter that contains \fIvarName\fR. Also used by \fBTcl_LinkVar\fR to return error messages. .AP "const char" *varName in Name of global variable. -.AP char *addr in +.AP void *addr in Address of C variable that is to be linked to \fIvarName\fR. +.sp +.VS "TIP 312" +In \fBTcl_LinkArray\fR, may be NULL to tell Tcl to create the storage +for the array in the variable. +.VE "TIP 312" .AP int type in -Type of C variable. Must be one of \fBTCL_LINK_INT\fR, +Type of C variable for \fBTcl_LinkVar\fR or type of array element for +\fBTcl_LinkArray\fR. Must be one of \fBTCL_LINK_INT\fR, \fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR, \fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR, \fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR, -\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, -\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or -\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR -to make Tcl variable read-only. +\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, \fBTCL_LINK_DOUBLE\fR, +\fBTCL_LINK_BOOLEAN\fR, or one of the extra ones listed below. +.sp +In \fBTcl_LinkVar\fR, the additional linked type \fBTCL_LINK_STRING\fR may be +used. +.sp +.VS "TIP 312" +In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and +\fBTCL_LINK_BYTES\fR may be used. +.VE "TIP 312" +.sp +All the above for both functions may be +optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR to make the Tcl +variable read-only. +.AP int size in +.VS "TIP 312" +The number of elements in the C array. Must be greater than zero. +.VE "TIP 312" .BE .SH DESCRIPTION .PP @@ -52,130 +77,179 @@ while setting up the link (e.g. because \fIvarName\fR is the name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result contains an error message. .PP +.VS "TIP 312" +\fBTcl_LinkArray\fR is similar, but for arrays of fixed size (given by +the \fIsize\fR argument). When asked to allocate the backing C array +storage (via the \fIaddr\fR argument being NULL), it writes the +address that it allocated to the Tcl interpreter result. +.VE "TIP 312" +.PP The \fItype\fR argument specifies the type of the C variable, +or the type of the elements of the C array, and must have one of the following values, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR: .TP \fBTCL_LINK_INT\fR -The C variable is of type \fBint\fR. +. +The C variable, or each element of the C array, is of type \fBint\fR. Any value written into the Tcl variable must have a proper integer form acceptable to \fBTcl_GetIntFromObj\fR; attempts to write non-integer values into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer representations (like the empty -string, '+', '-' or the hex/octal/binary prefix) are accepted +string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. .TP \fBTCL_LINK_UINT\fR -The C variable is of type \fBunsigned int\fR. +. +The C variable, or each element of the C array, is of type \fBunsigned int\fR. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the platform's defined range for the \fBunsigned int\fR type; attempts to write non-integer values (or values outside the range) into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/binary +representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. .TP \fBTCL_LINK_CHAR\fR -The C variable is of type \fBchar\fR. +. +The C variable, or each element of the C array, is of type \fBchar\fR. Any value written into the Tcl variable must have a proper integer form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the \fBchar\fR datatype; attempts to write non-integer or out-of-range values into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the -hex/octal/binary prefix) are accepted as if they are valid too. +hex/octal/decimal/binary prefix) are accepted as if they are valid too. +.RS +.PP +.VS "TIP 312" +If using an array of these, consider using \fBTCL_LINK_CHARS\fR instead. +.VE "TIP 312" +.RE +.TP +\fBTCL_LINK_CHARS\fR +.VS "TIP 312" +The C array is of type \fBchar *\fR and is mapped into Tcl as a string. +Any value written into the Tcl variable must have the same length as +the underlying storage. Only supported with \fBTcl_LinkArray\fR. +.VE "TIP 312" .TP \fBTCL_LINK_UCHAR\fR -The C variable is of type \fBunsigned char\fR. +. +The C variable, or each element of the C array, is of type \fBunsigned char\fR. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to \fBTcl_GetIntFromObj\fR and in the platform's defined range for the \fBunsigned char\fR type; attempts to write non-integer values (or values outside the range) into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/binary +representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. +.RS +.PP +.VS "TIP 312" +If using an array of these, consider using \fBTCL_LINK_BYTES\fR instead. +.VE "TIP 312" +.RE +.TP +\fBTCL_LINK_BYTES\fR +.VS "TIP 312" +The C array is of type \fBunsigned char *\fR and is mapped into Tcl +as a bytearray. +Any value written into the Tcl variable must have the same length as +the underlying storage. Only supported with \fBTcl_LinkArray\fR. +.VE "TIP 312" .TP \fBTCL_LINK_SHORT\fR -The C variable is of type \fBshort\fR. +. +The C variable, or each element of the C array, is of type \fBshort\fR. Any value written into the Tcl variable must have a proper integer form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the \fBshort\fR datatype; attempts to write non-integer or out-of-range values into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the -hex/octal/binary prefix) are accepted as if they are valid too. +hex/octal/decimal/binary prefix) are accepted as if they are valid too. .TP \fBTCL_LINK_USHORT\fR -The C variable is of type \fBunsigned short\fR. +. +The C variable, or each element of the C array, is of type \fBunsigned short\fR. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to \fBTcl_GetIntFromObj\fR and in the platform's defined range for the \fBunsigned short\fR type; attempts to write non-integer values (or values outside the range) into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/binary +representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. .TP \fBTCL_LINK_LONG\fR -The C variable is of type \fBlong\fR. +. +The C variable, or each element of the C array, is of type \fBlong\fR. Any value written into the Tcl variable must have a proper integer form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write non-integer or out-of-range values into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the -hex/octal/binary prefix) are accepted as if they are valid too. +hex/octal/decimal/binary prefix) are accepted as if they are valid too. .TP \fBTCL_LINK_ULONG\fR -The C variable is of type \fBunsigned long\fR. +. +The C variable, or each element of the C array, is of type \fBunsigned long\fR. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the platform's defined range for the \fBunsigned long\fR type; attempts to write non-integer values (or values outside the range) into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/binary +representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. .TP \fBTCL_LINK_DOUBLE\fR -The C variable is of type \fBdouble\fR. +. +The C variable, or each element of the C array, is of type \fBdouble\fR. Any value written into the Tcl variable must have a proper real form acceptable to \fBTcl_GetDoubleFromObj\fR; attempts to write non-real values into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer or real representations (like the -empty string, '.', '+', '-' or the hex/octal/binary prefix) are +empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. .TP \fBTCL_LINK_FLOAT\fR -The C variable is of type \fBfloat\fR. +. +The C variable, or each element of the C array, is of type \fBfloat\fR. Any value written into the Tcl variable must have a proper real form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the range acceptable for a \fBfloat\fR; attempts to write non-real values (or values outside the range) into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer or real representations (like the empty string, '.', '+', '-' or -the hex/octal/binary prefix) are accepted as if they are valid too. +the hex/octal/decimal/binary prefix) are accepted as if they are valid too. .TP \fBTCL_LINK_WIDE_INT\fR -The C variable is of type \fBTcl_WideInt\fR (which is an integer type +. +The C variable, or each element of the C array, is of type \fBTcl_WideInt\fR +(which is an integer type at least 64-bits wide on all platforms that can support it.) Any value written into the Tcl variable must have a proper integer form acceptable to \fBTcl_GetWideIntFromObj\fR; attempts to write non-integer values into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer representations (like the empty -string, '+', '-' or the hex/octal/binary prefix) are accepted +string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. .TP \fBTCL_LINK_WIDE_UINT\fR -The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned -integer type at least 64-bits wide on all platforms that can support -it.) +. +The C variable, or each element of the C array, is of type \fBTcl_WideUInt\fR +(which is an unsigned integer type at least 64-bits wide on all platforms that +can support it.) Any value written into the Tcl variable must have a proper unsigned integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be cast to unsigned); .\" FIXME! Use bignums instead. attempts to write non-integer values into \fIvarName\fR will be rejected with Tcl errors. Incomplete integer representations (like -the empty string, '+', '-' or the hex/octal/binary prefix) are accepted +the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. .TP \fBTCL_LINK_BOOLEAN\fR -The C variable is of type \fBint\fR. +. +The C variable, or each element of the C array, is of type \fBint\fR. If its value is zero then it will read from Tcl as .QW 0 ; otherwise it will read from Tcl as @@ -188,6 +262,7 @@ non-boolean values into \fIvarName\fR will be rejected with Tcl errors. .TP \fBTCL_LINK_STRING\fR +. The C variable is of type \fBchar *\fR. If its value is not NULL then it must be a pointer to a string allocated with \fBTcl_Alloc\fR or \fBckalloc\fR. @@ -197,6 +272,7 @@ new value. If the C variable contains a NULL pointer then the Tcl variable will read as .QW NULL . +This is only supported by \fBTcl_LinkVar\fR. .PP If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the variable will be read-only from Tcl, so that its value can only be diff --git a/doc/Method.3 b/doc/Method.3 index 225da00..9e636a1 100644 --- a/doc/Method.3 +++ b/doc/Method.3 @@ -9,18 +9,18 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts +Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsPrivate, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts .SH SYNOPSIS .nf \fB#include <tclOO.h>\fR .sp Tcl_Method -\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, isPublic, - methodTypePtr, clientData\fR) +\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, flags, methodTypePtr, + clientData\fR) .sp Tcl_Method -\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, isPublic, - methodTypePtr, clientData\fR) +\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, flags, methodTypePtr, + clientData\fR) .sp \fBTcl_ClassSetConstructor\fR(\fIinterp, class, method\fR) .sp @@ -35,8 +35,13 @@ Tcl_Object Tcl_Obj * \fBTcl_MethodName\fR(\fImethod\fR) .sp +.VS TIP500 int \fBTcl_MethodIsPublic\fR(\fImethod\fR) +.VE TIP500 +.sp +int +\fBTcl_MethodIsPrivate\fR(\fImethod\fR) .sp int \fBTcl_MethodIsType\fR(\fImethod, methodTypePtr, clientDataPtr\fR) @@ -66,10 +71,15 @@ The class to create the method in. .AP Tcl_Obj *nameObj in The name of the method to create. Should not be NULL unless creating constructors or destructors. -.AP int isPublic in -A flag saying what the visibility of the method is. The only supported public -values of this flag are 0 for a non-exported method, and 1 for an exported -method. +.AP int flags in +A flag saying (currently) what the visibility of the method is. The supported +public values of this flag are \fBTCL_OO_METHOD_PUBLIC\fR (which is fixed at 1 +for backward compatibility) for an exported method, +\fBTCL_OO_METHOD_UNEXPORTED\fR (which is fixed at 0 for backward +compatibility) for a non-exported method, +.VS TIP500 +and \fBTCL_OO_METHOD_PRIVATE\fR for a private method. +.VE TIP500 .AP Tcl_MethodType *methodTypePtr in A description of the type of the method to create, or the type of method to compare against. @@ -105,8 +115,12 @@ Given a method, the entity that declared it can be found using attached to (or NULL if the method is not attached to any class) and \fBTcl_MethodDeclarerObject\fR which returns the object that the method is attached to (or NULL if the method is not attached to an object). The name of -the method can be retrieved with \fBTcl_MethodName\fR and whether the method -is exported is retrieved with \fBTcl_MethodIsPublic\fR. The type of the method +the method can be retrieved with \fBTcl_MethodName\fR, whether the method +is exported is retrieved with \fBTcl_MethodIsPublic\fR, +.VS TIP500 +and whether the method is private is retrieved with \fBTcl_MethodIsPrivate\fR. +.VE TIP500 +The type of the method can also be introspected upon to a limited degree; the function \fBTcl_MethodIsType\fR returns whether a method is of a particular type, assigning the per-method \fIclientData\fR to the variable pointed to by @@ -117,8 +131,12 @@ Methods are created by \fBTcl_NewMethod\fR and \fBTcl_NewInstanceMethod\fR, which create a method attached to a class or an object respectively. In both cases, the \fInameObj\fR argument gives the name of the method to create, the -\fIisPublic\fR argument states whether the method should be exported -initially, the \fImethodTypePtr\fR argument describes the implementation of +\fIflags\fR argument states whether the method should be exported +initially +.VS TIP500 +or be marked as a private method, +.VE TIP500 +the \fImethodTypePtr\fR argument describes the implementation of the method (see the \fBMETHOD TYPES\fR section below) and the \fIclientData\fR argument gives some implementation-specific data that is passed on to the implementation of the method when it is called. diff --git a/doc/Notifier.3 b/doc/Notifier.3 index 16f9f8d..ec9f910 100644 --- a/doc/Notifier.3 +++ b/doc/Notifier.3 @@ -132,22 +132,17 @@ higher-level software that they have occurred. The procedures and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and \fBTcl_DeleteEvents\fR are used primarily by event sources. .IP [2] -The event queue: for non-threaded applications, -there is a single queue for the whole application, -containing events that have been detected but not yet serviced. Event -sources place events onto the queue so that they may be processed in -order at appropriate times during the event loop. The event queue -guarantees a fair discipline of event handling, so that no event -source can starve the others. It also allows events to be saved for -servicing at a future time. Threaded applications work in a -similar manner, except that there is a separate event queue for -each thread containing a Tcl interpreter. +The event queue: there is a single queue for each thread containing +a Tcl interpreter, containing events that have been detected but not +yet serviced. Event sources place events onto the queue so that they +may be processed in order at appropriate times during the event loop. +The event queue guarantees a fair discipline of event handling, so that +no event source can starve the others. It also allows events to be +saved for servicing at a future time. \fBTcl_QueueEvent\fR is used (primarily -by event sources) to add events to the event queue and +by event sources) to add events to the current thread's event queue and \fBTcl_DeleteEvents\fR is used to remove events from the queue without -processing them. In a threaded application, \fBTcl_QueueEvent\fR adds -an event to the current thread's queue, and \fBTcl_ThreadQueueEvent\fR -adds an event to a queue in a specific thread. +processing them. .IP [3] The event loop: in order to detect and process events, the application enters a loop that waits for events to occur, places them on the event @@ -403,11 +398,7 @@ the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR) before calling \fBTcl_QueueEvent\fR, but it will be freed by \fBTcl_ServiceEvent\fR, not by the event source. .PP -Threaded applications work in a -similar manner, except that there is a separate event queue for -each thread containing a Tcl interpreter. -Calling \fBTcl_QueueEvent\fR in a multithreaded application adds -an event to the current thread's queue. +Calling \fBTcl_QueueEvent\fR adds an event to the current thread's queue. To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR. \fBTcl_ThreadQueueEvent\fR accepts as an argument a Tcl_ThreadId argument, which uniquely identifies a thread in a Tcl application. To obtain the @@ -498,8 +489,7 @@ under Unix it happens when \fBTcl_WaitForEvent\fR would have waited forever because there were no active event sources and the timeout was infinite. .PP -\fBTcl_AlertNotifier\fR is used in multithreaded applications to allow -any thread to +\fBTcl_AlertNotifier\fR is used to allow any thread to .QW "wake up" the notifier to alert it to new events on its queue. \fBTcl_AlertNotifier\fR requires as an argument the notifier diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3 index 4a7dc1e..5b941dc 100644 --- a/doc/OpenTcp.3 +++ b/doc/OpenTcp.3 @@ -4,12 +4,12 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures" +.TH Tcl_OpenTcpClient 3 8.7 Tcl "Tcl Library Procedures" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets +Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer, Tcl_OpenTcpServerEx \- procedures to open channels using TCP sockets .SH SYNOPSIS .nf \fB#include <tcl.h> \fR @@ -23,6 +23,9 @@ Tcl_Channel Tcl_Channel \fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR) .sp +Tcl_Channel +\fBTcl_OpenTcpServerEx\fR(\fIinterp, service, myaddr, flags, proc, clientData\fR) +.sp .SH ARGUMENTS .AS Tcl_TcpAcceptProc clientData .AP Tcl_Interp *interp in @@ -30,6 +33,9 @@ Tcl interpreter to use for error reporting. If non-NULL and an error occurs, an error message is left in the interpreter's result. .AP int port in A port number to connect to as a client or to listen on as a server. +.AP "const char" *service in +A string specifying the port number to connect to as a client or to listen on as + a server. .AP "const char" *host in A string specifying a host name or address for the remote end of the connection. .AP int myport in @@ -41,6 +47,9 @@ for the local end of the connection. If NULL, a default interface is chosen. .AP int async in If nonzero, the client socket is connected asynchronously to the server. +.AP "unsigned int" flags in +ORed combination of \fBTCL_TCPSERVER\fR flags that specify additional +informations about the socket being created. .AP ClientData sock in Platform-specific handle for client TCP socket. .AP Tcl_TcpAcceptProc *proc in @@ -158,6 +167,11 @@ register it, use \fBTcl_RegisterChannel\fR. If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. +.SS TCL_OPENTCPSERVEREX +.PP +\fBTcl_OpenTcpServerEx\fR behaviour is identical to \fBTcl_OpenTcpServer\fR but +gives more flexibility to the user by providing a mean to further customize some +aspects of the socket via the \fIflags\fR parameter. .SH "PLATFORM ISSUES" .PP On Unix platforms, the socket handle is a Unix file descriptor as diff --git a/doc/Panic.3 b/doc/Panic.3 index 5f4763f..53b84da 100644 --- a/doc/Panic.3 +++ b/doc/Panic.3 @@ -7,7 +7,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc \- report fatal error and abort +Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc, Tcl_ConsolePanic \- report fatal error and abort .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -21,6 +21,9 @@ void void \fBTcl_SetPanicProc\fR(\fIpanicProc\fR) .sp +void +\fBTcl_ConsolePanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR) +.sp .SH ARGUMENTS .AS Tcl_PanicProc *panicProc .AP "const char*" format in @@ -54,6 +57,14 @@ message is sent to the debugger instead. If the windows executable does not have a stderr channel (e.g. \fBwish.exe\fR), then a system dialog box is used to display the panic message. .PP +If your application doesn't use \fBTcl_Main\fR or \fBTk_Main\fR +and you want to implicitly use the stderr channel of your +application's C runtime (instead of the stderr channel of the +C runtime used by Tcl), you can call \fBTcl_SetPanicProc\fR +with \fBTcl_ConsolePanic\fR as its argument. On platforms which +only have one C runtime (almost all platforms except Windows) +\fBTcl_ConsolePanic\fR is equivalent to NULL. +.PP \fBTcl_SetPanicProc\fR may be used to modify the behavior of \fBTcl_Panic\fR. The \fIpanicProc\fR argument should match the type \fBTcl_PanicProc\fR: @@ -75,6 +86,9 @@ The typical use of \fBTcl_SetPanicProc\fR arranges for the error message to be displayed or reported in a manner more suitable for the application or the platform. .PP +\fBTcl_SetPanicProc\fR can not be used in stub-enabled extensions. Its symbol +entry in the stub table is deprecated and it will be removed in Tcl 9.0. +.PP Although the primary callers of \fBTcl_Panic\fR are the procedures of the Tcl library, \fBTcl_Panic\fR is a public function and may be called by any extension or application that wishes to abort the process and @@ -82,7 +96,9 @@ have a panic message displayed the same way that panic messages from Tcl will be displayed. .PP \fBTcl_PanicVA\fR is the same as \fBTcl_Panic\fR except that instead of -taking a variable number of arguments it takes an argument list. +taking a variable number of arguments it takes an argument list. Interfaces +using argument lists have been found to be nonportable in practice. This +function is deprecated and will be removed in Tcl 9.0. .SH "SEE ALSO" abort(3), printf(3), exec(n), format(n) .SH KEYWORDS diff --git a/doc/RecEvalObj.3 b/doc/RecEvalObj.3 index 1b0f292..f9550a2 100644 --- a/doc/RecEvalObj.3 +++ b/doc/RecEvalObj.3 @@ -32,8 +32,6 @@ the command at global level instead of the current stack level. .PP \fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event on the history list and then execute it using \fBTcl_EvalObjEx\fR -(or \fBTcl_GlobalEvalObj\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set -in \fIflags\fR). It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\fR, as well as a result value containing additional information (a result value or error message) diff --git a/doc/SaveResult.3 b/doc/SaveResult.3 index 6dd6cb6..e62d22d 100644 --- a/doc/SaveResult.3 +++ b/doc/SaveResult.3 @@ -1,6 +1,7 @@ '\" '\" Copyright (c) 1997 by Sun Microsystems, Inc. '\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright) +'\" Copyright (c) 2018 Nathan Coulter. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -9,7 +10,9 @@ .so man.macros .BS .SH NAME -Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's state +Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, +Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- Save and restore the +state of an an interpreter. .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -30,91 +33,53 @@ int .SH ARGUMENTS .AS Tcl_InterpState savedPtr .AP Tcl_Interp *interp in -Interpreter for which state should be saved. +The interpreter for the operation. .AP int status in -Return code value to save as part of interpreter state. +The return code for the state. .AP Tcl_InterpState state in -Saved state token to be restored or discarded. +A token for saved state. .AP Tcl_SavedResult *savedPtr in -Pointer to location where interpreter result should be saved or restored. +A pointer to storage for saved state. .BE .SH DESCRIPTION .PP -These routines allows a C procedure to take a snapshot of the current -state of an interpreter so that it can be restored after a call -to \fBTcl_Eval\fR or some other routine that modifies the interpreter -state. There are two triplets of routines meant to work together. +These routines save the state of an interpreter before a call to a routine such +as \fBTcl_Eval\fR, and restore the state afterwards. .PP -The first triplet stores the snapshot of interpreter state in -an opaque token returned by \fBTcl_SaveInterpState\fR. That token -value may then be passed back to one of \fBTcl_RestoreInterpState\fR -or \fBTcl_DiscardInterpState\fR, depending on whether the interp -state is to be restored. So long as one of the latter two routines -is called, Tcl will take care of memory management. +\fBTcl_SaveInterpState\fR saves the parts of \fIinterp\fR that comprise the +result of a script, including the resulting value, the return code passed as +\fIstatus\fR, and any options such as \fB\-errorinfo\fR and \fB\-errorcode\fR. +It returns a token for the saved state. The interpreter result is not reset +and no interpreter state is changed. .PP -The second triplet stores the snapshot of only the interpreter -result (not its complete state) in memory allocated by the caller. -These routines are passed a pointer to \fBTcl_SavedResult\fR -that is used to store enough information to restore the interpreter result. -\fBTcl_SavedResult\fR can be allocated on the stack of the calling -procedure. These routines do not save the state of any error -information in the interpreter (e.g. the \fB\-errorcode\fR or -\fB\-errorinfo\fR return options, when an error is in progress). +\fBTcl_RestoreInterpState\fR restores the state indicated by \fIstate\fR and +returns the \fIstatus\fR originally passed in the corresponding call to +\fBTcl_SaveInterpState\fR. .PP -Because the routines \fBTcl_SaveInterpState\fR, -\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR perform -a superset of the functions provided by the other routines, -any new code should only make use of the more powerful routines. -The older, weaker routines \fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR, -and \fBTcl_DiscardResult\fR continue to exist only for the sake -of existing programs that may already be using them. +If a saved state is not restored, \fBTcl_DiscardInterpState\fR must be called +to release it. A token used to discard or restore state must not be used +again. .PP -\fBTcl_SaveInterpState\fR takes a snapshot of those portions of -interpreter state that make up the full result of script evaluation. -This include the interpreter result, the return code (passed in -as the \fIstatus\fR argument, and any return options, including -\fB\-errorinfo\fR and \fB\-errorcode\fR when an error is in progress. -This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR. -The call to \fBTcl_SaveInterpState\fR does not itself change the -state of the interpreter. Unlike \fBTcl_SaveResult\fR, it does -not reset the interpreter. +\fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR, and \fBTcl_DiscardResult\fR are +deprecated. Instead use \fBTcl_SaveInterpState\fR, +\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR, which are more +capable. .PP -\fBTcl_RestoreInterpState\fR accepts a \fBTcl_InterpState\fR token -previously returned by \fBTcl_SaveInterpState\fR and restores the -state of the interp to the state held in that snapshot. The return -value of \fBTcl_RestoreInterpState\fR is the status value originally -passed to \fBTcl_SaveInterpState\fR when the snapshot token was -created. +\fBTcl_SaveResult\fR moves the result of \fIinterp\fR to the location +\fIstatePtr\fR points to and returns the interpreter result to its initial +state. It does not save options such as \fB\-errorcode\fR or +\fB\-errorinfo\fR. .PP -\fBTcl_DiscardInterpState\fR is called to release a \fBTcl_InterpState\fR -token previously returned by \fBTcl_SaveInterpState\fR when that -snapshot is not to be restored to an interp. -.PP -The \fBTcl_InterpState\fR token returned by \fBTcl_SaveInterpState\fR -must eventually be passed to either \fBTcl_RestoreInterpState\fR -or \fBTcl_DiscardInterpState\fR to avoid a memory leak. Once -the \fBTcl_InterpState\fR token is passed to one of them, the -token is no longer valid and should not be used anymore. -.PP -\fBTcl_SaveResult\fR moves the string and value results -of \fIinterp\fR into the location specified by \fIstatePtr\fR. -\fBTcl_SaveResult\fR clears the result for \fIinterp\fR and -leaves the result in its normal empty initialized state. -.PP -\fBTcl_RestoreResult\fR moves the string and value results from -\fIstatePtr\fR back into \fIinterp\fR. Any result or error that was -already in the interpreter will be cleared. The \fIstatePtr\fR is left -in an uninitialized state and cannot be used until another call to +\fBTcl_RestoreResult\fR clears any existing result or error in \fIinterp\fR and +moves the result from \fIstatePtr\fR back to \fIinterp\fR. \fIstatePtr\fR is +then in an undefined state and must not be used until passed again to \fBTcl_SaveResult\fR. .PP -\fBTcl_DiscardResult\fR releases the saved interpreter state -stored at \fBstatePtr\fR. The state structure is left in an -uninitialized state and cannot be used until another call to +\fBTcl_DiscardResult\fR releases the state stored at \fBstatePtr\fR, which is +then in an undefined state and must not be used until passed again to \fBTcl_SaveResult\fR. .PP -Once \fBTcl_SaveResult\fR is called to save the interpreter -result, either \fBTcl_RestoreResult\fR or -\fBTcl_DiscardResult\fR must be called to properly clean up the -memory associated with the saved state. +If a saved result is not restored, \fBTcl_DiscardResult\fR must be called to +release it. .SH KEYWORDS result, state, interp diff --git a/doc/SetResult.3 b/doc/SetResult.3 index e50650e..1622290 100644 --- a/doc/SetResult.3 +++ b/doc/SetResult.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH Tcl_SetResult 3 8.6 Tcl "Tcl Library Procedures" +.TH Tcl_SetResult 3 8.7 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -30,9 +30,7 @@ const char * .sp \fBTcl_ResetResult\fR(\fIinterp\fR) .sp -.VS 8.6 \fBTcl_TransferResult\fR(\fIsourceInterp, code, targetInterp\fR) -.VE 8.6 .sp \fBTcl_AppendElement\fR(\fIinterp, element\fR) .sp @@ -57,17 +55,11 @@ Address of procedure to call to release storage at An argument list which must have been initialized using \fBva_start\fR, and cleared using \fBva_end\fR. .AP Tcl_Interp *sourceInterp in -.VS 8.6 Interpreter that the result and return options should be transferred from. -.VE 8.6 .AP Tcl_Interp *targetInterp in -.VS 8.6 Interpreter that the result and return options should be transferred to. -.VE 8.6 .AP int code in -.VS 8.6 Return code value that controls transfer of return options. -.VE 8.6 .BE .SH DESCRIPTION .PP @@ -153,8 +145,9 @@ call; the last argument in the list must be a NULL pointer. .PP \fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that instead of taking a variable number of arguments it takes an argument list. +Interfaces using argument lists have been found to be nonportable in practice. +This function is deprecated and will be removed in Tcl 9.0. .PP -.VS 8.6 \fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR to \fItargetInterp\fR. The two interpreters must have been created in the same thread. If \fIsourceInterp\fR and \fItargetInterp\fR are the same, @@ -163,7 +156,6 @@ from \fIsourceInterp\fR to \fItargetInterp\fR, and resets the result in \fIsourceInterp\fR. It also moves the return options dictionary as controlled by the return code value \fIcode\fR in the same manner as \fBTcl_GetReturnOptions\fR. -.VE 8.6 .SH "DEPRECATED INTERFACES" .SS "OLD STRING PROCEDURES" .PP @@ -205,14 +197,9 @@ is about to replace one result value with another. It used to be legal for programs to directly read and write \fIinterp->result\fR to manipulate the interpreter result. The Tcl headers no longer -permit this access by default, and C code still doing this must +permit this access. C code still doing this must be updated to use supported routines \fBTcl_GetObjResult\fR, \fBTcl_GetStringResult\fR, \fBTcl_SetObjResult\fR, and \fBTcl_SetResult\fR. -As a migration aid, access can be restored with the compiler directive -.CS -#define USE_INTERP_RESULT -.CE -but this is meant only to offer life support to otherwise dead code. .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT" .PP \fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3 index 41e2d65..b22edcc 100644 --- a/doc/StaticPkg.3 +++ b/doc/StaticPkg.3 @@ -64,6 +64,9 @@ the event of an error it should set the interpreter's result to point to an error message. The result or error from the initialization procedure will be returned as the result of the \fBload\fR command that caused the initialization procedure to be invoked. +.PP +\fBTcl_StaticPackage\fR can not be used in stub-enabled extensions. Its symbol +entry in the stub table is deprecated and it will be removed in Tcl 9.0. .SH KEYWORDS initialization procedure, package, static linking .SH "SEE ALSO" diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 7870b21..2b665cc 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -37,7 +37,7 @@ Tcl_UniChar * Tcl_UniChar * \fBTcl_GetUnicode\fR(\fIobjPtr\fR) .sp -Tcl_UniChar +int \fBTcl_GetUniChar\fR(\fIobjPtr, index\fR) .sp int @@ -204,8 +204,8 @@ where the caller does not need the length of the unicode string representation. .PP \fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the -value's Unicode representation. The index is assumed to be in the -appropriate range. +value's Unicode representation. If the index is out of range or +it references a low surrogate preceded by a high surrogate, it returns -1; .PP \fBTcl_GetRange\fR returns a newly created value comprised of the characters between \fIfirst\fR and \fIlast\fR (inclusive) in the @@ -249,7 +249,9 @@ must be a NULL pointer to indicate the end of the list. .PP \fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR except that instead of taking a variable number of arguments it takes an -argument list. +argument list. Interfaces using argument lists have been found to be +nonportable in practice. This function is deprecated and will be removed +in Tcl 9.0. .PP \fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR except that it imposes a limit on how many bytes are appended. @@ -28,10 +28,10 @@ First, the Tcl interpreter breaks the command into \fIwords\fR and performs substitutions as described below. These substitutions are performed in the same way for all commands. -Secondly, the first word is used to locate a command procedure to -carry out the command, then all of the words of the command are -passed to the command procedure. -The command procedure is free to interpret each of its words +Secondly, the first word is used to locate a routine to +carry out the command, and the remaining words of the command are +passed to that routine. +The routine is free to interpret each of its words in any way it likes, such as an integer, variable name, list, or Tcl script. Different commands interpret their words differently. @@ -223,7 +223,10 @@ before this range overflows, or when the maximum of eight digits is reached. The upper bits of the Unicode character will be 0. .RS .PP -The range U+010000\(enU+10FFFD is reserved for the future. +The range U+00D800\(enU+00DFFF is reserved for surrogates, which +are illegal on its own. Therefore, such sequences will result in +the replacement character U+FFFD. Surrogate pairs should be +encoded as single \e\fBU\fIhhhhhhhh\fR character. .RE .PP Backslash substitution is not performed on words enclosed in braces, diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3 index 3ec33d1..dc4f45f 100644 --- a/doc/Tcl_Main.3 +++ b/doc/Tcl_Main.3 @@ -189,6 +189,8 @@ procedure (if any) returns. In non-interactive mode, after \fBTcl_Main\fR evaluates the startup script, and the main loop procedure (if any) returns, \fBTcl_Main\fR will also evaluate the \fBexit\fR command. +.PP +\fBTcl_Main\fR can not be used in stub-enabled extensions. .SH "SEE ALSO" tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3), exit(n), encoding(n) diff --git a/doc/Thread.3 b/doc/Thread.3 index 5966a71..2005c93 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -45,7 +45,9 @@ int .AP Tcl_Condition *condPtr in A condition variable, which must be associated with a mutex lock. .AP Tcl_Mutex *mutexPtr in -A mutex lock. +.VS TIP509 +A recursive mutex lock. +.VE TIP509 .AP "const Tcl_Time" *timePtr in A time limit on the condition wait. NULL to wait forever. Note that a polling value of 0 seconds does not make much sense. @@ -140,8 +142,12 @@ of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR. If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will block until \fBTcl_MutexUnlock\fR is called. A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR. -The result of locking a mutex twice from the same thread is undefined. -On some platforms it will result in a deadlock. +.VS TIP509 +Mutexes are reentrant: they can be locked several times from the same +thread. However there must be exactly one call to +\fBTcl_MutexUnlock\fR for each call to \fBTcl_MutexLock\fR in order +for a thread to release a mutex completely. +.VE TIP509 The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR procedures are defined as empty macros if not compiling with threads enabled. For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used. diff --git a/doc/ToUpper.3 b/doc/ToUpper.3 index 629a8e5..fd9ddfb 100644 --- a/doc/ToUpper.3 +++ b/doc/ToUpper.3 @@ -13,13 +13,13 @@ Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper, Tcl_ .nf \fB#include <tcl.h>\fR .sp -Tcl_UniChar +int \fBTcl_UniCharToUpper\fR(\fIch\fR) .sp -Tcl_UniChar +int \fBTcl_UniCharToLower\fR(\fIch\fR) .sp -Tcl_UniChar +int \fBTcl_UniCharToTitle\fR(\fIch\fR) .sp int @@ -78,12 +78,5 @@ turns each character in the string into its lower-case equivalent. turns the first character in the string into its title-case equivalent and all following characters into their lower-case equivalents. -.SH BUGS -.PP -At this time, the case conversions are only defined for the Unicode -plane 0 characters. The result for Unicode characters above 0xFFFF -is undefined, but - actually - only the lower 16 bits of the -character value is handled. - .SH KEYWORDS utf, unicode, toupper, tolower, totitle, case diff --git a/doc/TraceVar.3 b/doc/TraceVar.3 index c3edfa4..82aa7b8 100644 --- a/doc/TraceVar.3 +++ b/doc/TraceVar.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures" +.TH Tcl_TraceVar 3 8.7 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -95,7 +95,7 @@ Invoke \fIproc\fR whenever an attempt is made to modify the variable. 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 -automatically unset) or when the interpreter is deleted (all +automatically unset) or when the interpreter or namespace is deleted (all variables are automatically unset). .TP \fBTCL_TRACE_ARRAY\fR @@ -160,10 +160,6 @@ The bit \fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about to be destroyed; this information may be useful to \fIproc\fR so that it can clean up its own internal data structures (see the section \fBTCL_TRACE_DESTROYED\fR below for more details). -Lastly, the bit \fBTCL_INTERP_DESTROYED\fR will be set if the entire -interpreter is being destroyed. -When this bit is set, \fIproc\fR must be especially careful in -the things it does (see the section \fBTCL_INTERP_DESTROYED\fR below). The trace procedure's return value should normally be NULL; see \fBERROR RETURNS\fR below for information on other possibilities. .PP @@ -330,6 +326,15 @@ During unset traces, the return value is ignored and all relevant trace procedures will always be invoked. .SH "RESTRICTIONS" .PP +Because operations on variables may take place as part of the deletion +of the interp that contains them, \fIproc\fR must be careful about checking +what the \fIinterp\fR parameter can be used to do. +The routine \fBTcl_InterpDeleted\fR is an important tool for this. +When \fBTcl_InterpDeleted\fR returns 1, \fIproc\fR will not be able +to invoke any scripts in \fIinterp\fR. You may encounter old code using +a deprecated flag value \fBTCL_INTERP_DESTROYED\fR to signal this +condition, but any supported code should be converted to stop using it. +.PP A trace procedure can be called at any time, even when there are partially formed results stored in the interpreter. If the trace procedure does anything that could damage this result (such @@ -354,24 +359,8 @@ Traces on a variable are always removed whenever the variable is deleted; the only time \fBTCL_TRACE_DESTROYED\fR is not set is for a whole-array trace invoked when only a single element of an array is unset. -.SH "TCL_INTERP_DESTROYED" -.PP -When an interpreter is destroyed, unset traces are called for -all of its variables. -The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR -argument passed to the trace procedures. -Trace procedures must be extremely careful in what they do if -the \fBTCL_INTERP_DESTROYED\fR bit is set. -It is not safe for the procedures to invoke any Tcl procedures -on the interpreter, since its state is partially deleted. -All that trace procedures should do under these circumstances is -to clean up and free their own internal data structures. .SH BUGS .PP -Tcl does not do any error checking to prevent trace procedures -from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR -set. -.PP Array traces are not yet integrated with the Tcl \fBinfo exists\fR command, nor is there Tcl-level access to array traces. .SH "SEE ALSO" diff --git a/doc/UniCharIsAlpha.3 b/doc/UniCharIsAlpha.3 index 5ba3fc9..61490ed 100644 --- a/doc/UniCharIsAlpha.3 +++ b/doc/UniCharIsAlpha.3 @@ -48,7 +48,7 @@ int .SH ARGUMENTS .AS int ch .AP int ch in -The Tcl_UniChar to be examined. +The Unicode character to be examined. .BE .SH DESCRIPTION @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UniCharNcasecmp, Tcl_UniCharCaseMatch, Tcl_UtfNcmp, Tcl_UtfNcasecmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings +Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UtfToChar16, Tcl_UtfToWChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_Char16ToUtfDString, Tcl_UtfToWCharDString, Tcl_UtfToChar16DString, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UniCharNcasecmp, Tcl_UniCharCaseMatch, Tcl_UtfNcmp, Tcl_UtfNcasecmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -21,12 +21,30 @@ int int \fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR) .sp +int +\fBTcl_UtfToChar16\fR(\fIsrc, uPtr\fR) +.sp +int +\fBTcl_UtfToWChar\fR(\fIsrc, wPtr\fR) +.sp char * \fBTcl_UniCharToUtfDString\fR(\fIuniStr, uniLength, dsPtr\fR) .sp +char * +\fBTcl_Char16ToUtfDString\fR(\fIuStr, uniLength, dsPtr\fR) +.sp +char * +\fBTcl_WCharToUtfDString\fR(\fIwStr, uniLength, dsPtr\fR) +.sp Tcl_UniChar * \fBTcl_UtfToUniCharDString\fR(\fIsrc, length, dsPtr\fR) .sp +unsigned short * +\fBTcl_UtfToChar16DString\fR(\fIsrc, length, dsPtr\fR) +.sp +wchar_t * +\fBTcl_UtfToWCharDString\fR(\fIsrc, length, dsPtr\fR) +.sp int \fBTcl_UniCharLen\fR(\fIuniStr\fR) .sp @@ -63,7 +81,7 @@ const char * const char * \fBTcl_UtfPrev\fR(\fIsrc, start\fR) .sp -Tcl_UniChar +int \fBTcl_UniCharAtIndex\fR(\fIsrc, index\fR) .sp const char * @@ -75,11 +93,15 @@ int .AS "const Tcl_UniChar" *uniPattern in/out .AP char *buf out Buffer in which the UTF-8 representation of the Tcl_UniChar is stored. At most -\fBTCL_UTF_MAX\fR bytes are stored in the buffer. +4 bytes are stored in the buffer. .AP int ch in The Unicode character to be converted or examined. .AP Tcl_UniChar *chPtr out Filled with the Tcl_UniChar represented by the head of the UTF-8 string. +.AP unsigned short *uPtr out +Filled with the utf-16 represented by the head of the UTF-8 string. +.AP wchar_t *wPtr out +Filled with the wchar_t represented by the head of the UTF-8 string. .AP "const char" *src in Pointer to a UTF-8 string. .AP "const char" *cs in @@ -94,12 +116,21 @@ A null-terminated Unicode string. A null-terminated Unicode string. .AP "const Tcl_UniChar" *uniPattern in A null-terminated Unicode string. +.AP "const unsigned short" *uStr in +A null-terminated UTF-16 string. +.AP "const wchar_t" *wStr in +A null-terminated wchar_t string. +.AP "const unsigned short" *utf16s in +A null-terminated utf-16 string. +.AP "const unsigned short" *utf16t in +A null-terminated utf-16 string. +.AP "const unsigned short" *utf16Pattern in +A null-terminated utf-16 string. .AP int length in The length of the UTF-8 string in bytes (not UTF-8 characters). If negative, all bytes up to the first null byte are used. .AP int uniLength in -The length of the Unicode string in characters. Must be greater than or -equal to 0. +The length of the Unicode string in characters. .AP "Tcl_DString" *dsPtr in/out A pointer to a previously initialized \fBTcl_DString\fR. .AP "unsigned long" numChars in @@ -113,7 +144,7 @@ If non-NULL, filled with the number of bytes in the backslash sequence, including the backslash character. .AP char *dst out Buffer in which the bytes represented by the backslash sequence are stored. -At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer. +At most 4 bytes are stored in the buffer. .AP int nocase in Specifies whether the match should be done case-sensitive (0) or case-insensitive (1). @@ -121,18 +152,21 @@ case-insensitive (1). .SH DESCRIPTION .PP -These routines convert between UTF-8 strings and Tcl_UniChars. A -Tcl_UniChar is a Unicode character represented as an unsigned, fixed-size -quantity. A UTF-8 character is a Unicode character represented as -a varying-length sequence of up to \fBTCL_UTF_MAX\fR bytes. A multibyte UTF-8 -sequence consists of a lead byte followed by some number of trail bytes. +These routines convert between UTF-8 strings and Unicode/Utf-16 characters. +A UTF-8 character is a Unicode character represented as a varying-length +sequence of up to \fB4\fR bytes. A multibyte UTF-8 sequence +consists of a lead byte followed by some number of trail bytes. .PP -\fBTCL_UTF_MAX\fR is the maximum number of bytes that it takes to -represent one Unicode character in the UTF-8 representation. +\fBTCL_UTF_MAX\fR is the maximum number of bytes that \fBTcl_UtfToUniChar\fR +can consume in a single call. .PP -\fBTcl_UniCharToUtf\fR stores the Tcl_UniChar \fIch\fR as a UTF-8 string +\fBTcl_UniCharToUtf\fR stores the character \fIch\fR as a UTF-8 string in starting at \fIbuf\fR. The return value is the number of bytes stored -in \fIbuf\fR. +in \fIbuf\fR. If ch is a high surrogate (range U+D800 - U+DBFF), then +the return value will be 1 and a single byte in the range 0xF0 - 0xF4 +will be stored. If you still want to produce UTF-8 output for it (even +though knowing it's an illegal code-point on its own), just call +\fBTcl_UniCharToUtf\fR again specifying ch = -1. .PP \fBTcl_UtfToUniChar\fR reads one UTF-8 character starting at \fIsrc\fR and stores it as a Tcl_UniChar in \fI*chPtr\fR. The return value is the @@ -140,13 +174,15 @@ number of bytes read from \fIsrc\fR. The caller must ensure that the source buffer is long enough such that this routine does not run off the end and dereference non-existent or random memory; if the source buffer is known to be null-terminated, this will not happen. If the input is +a byte in the range 0x80 - 0x9F, \fBTcl_UtfToUniChar\fR assumes the +cp1252 encoding, stores the corresponding Tcl_UniChar in \fI*chPtr\fR +and returns 1. If the input is otherwise not in proper UTF-8 format, \fBTcl_UtfToUniChar\fR will store the first -byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x0080 and +byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x00A0 and 0x00FF and return 1. .PP \fBTcl_UniCharToUtfDString\fR converts the given Unicode string to UTF-8, storing the result in a previously initialized \fBTcl_DString\fR. -You must specify \fIuniLength\fR, the length of the given Unicode string. The return value is a pointer to the UTF-8 representation of the Unicode string. Storage for the return value is appended to the end of the \fBTcl_DString\fR. @@ -200,7 +236,7 @@ of \fIlength\fR bytes is long enough to be decoded by \fBTcl_UtfToUniChar\fR, or 0 otherwise. This function does not guarantee that the UTF-8 string is properly formed. This routine is used by procedures that are operating on a byte at a time and need to know if a -full Tcl_UniChar has been seen. +full Unicode character has been seen. .PP \fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings. It returns the number of Tcl_UniChars that are represented by the UTF-8 string @@ -208,12 +244,12 @@ returns the number of Tcl_UniChars that are represented by the UTF-8 string length is negative, all bytes up to the first null byte are used. .PP \fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings. It -returns a pointer to the first occurrence of the Tcl_UniChar \fIch\fR +returns a pointer to the first occurrence of the Unicode character \fIch\fR in the null-terminated UTF-8 string \fIsrc\fR. The null terminator is considered part of the UTF-8 string. .PP \fBTcl_UtfFindLast\fR corresponds to \fBstrrchr\fR for UTF-8 strings. It -returns a pointer to the last occurrence of the Tcl_UniChar \fIch\fR +returns a pointer to the last occurrence of the Unicode character \fIch\fR in the null-terminated UTF-8 string \fIsrc\fR. The null terminator is considered part of the UTF-8 string. .PP @@ -246,21 +282,25 @@ byte \fIsrc[0]\fR nor the byte \fIstart[-1]\fR nor the byte \fIsrc[-\fBTCL_UTF_MAX\fI-1]\fR. .PP \fBTcl_UniCharAtIndex\fR corresponds to a C string array dereference or the -Pascal Ord() function. It returns the Tcl_UniChar represented at the +Pascal Ord() function. It returns the Unicode character represented at the specified character (not byte) \fIindex\fR in the UTF-8 string \fIsrc\fR. The source string must contain at least \fIindex\fR -characters. Behavior is undefined if a negative \fIindex\fR is given. +characters. If a negative \fIindex\fR is given or \fIindex\fR points +to the second half of a surrogate pair, it returns -1. .PP \fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not byte) \fIindex\fR in the UTF-8 string \fIsrc\fR. The source string must contain at least \fIindex\fR characters. This is equivalent to calling -\fBTcl_UtfToUniChar\fR \fIindex\fR times. If a negative \fIindex\fR is given, -the return pointer points to the first character in the source string. +\fBTcl_UtfToUniChar\fR \fIindex\fR times, except if that would return +a pointer to the second byte of a valid 4-byte UTF-8 sequence, in which +case, \fBTcl_UtfToUniChar\fR will be called once more to find the end +of the sequence. If a negative \fIindex\fR is given, the returned pointer +points to the first character in the source string. .PP \fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl commands. It parses a backslash sequence and stores the properly formed UTF-8 character represented by the backslash sequence in the output -buffer \fIdst\fR. At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer. +buffer \fIdst\fR. At most 4 bytes are stored in the buffer. \fBTcl_UtfBackslash\fR modifies \fI*readPtr\fR to contain the number of bytes in the backslash sequence, including the backslash character. The return value is the number of bytes stored in the output buffer. diff --git a/doc/abstract.n b/doc/abstract.n new file mode 100644 index 0000000..022c24b --- /dev/null +++ b/doc/abstract.n @@ -0,0 +1,77 @@ +'\" +'\" Copyright (c) 2018 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH abstract n 0.3 TclOO "TclOO Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +oo::abstract \- a class that does not allow direct instances of itself +.SH SYNOPSIS +.nf +package require TclOO + +\fBoo::abstract\fI method \fR?\fIarg ...\fR? +.fi +.SH "CLASS HIERARCHY" +.nf +\fBoo::object\fR + \(-> \fBoo::class\fR + \(-> \fBoo::abstract\fR +.fi +.BE +.SH DESCRIPTION +Abstract classes are classes that can contain definitions, but which cannot be +directly manufactured; they are intended to only ever be inherited from and +instantiated indirectly. The characteristic methods of \fBoo::class\fR +(\fBcreate\fR and \fBnew\fR) are not exported by an instance of +\fBoo::abstract\fR. +.PP +Note that \fBoo::abstract\fR is not itself an instance of \fBoo::abstract\fR. +.SS CONSTRUCTOR +The \fBoo::abstract\fR class does not define an explicit constructor; this +means that it is effectively the same as the constructor of the +\fBoo::class\fR class. +.SS DESTRUCTOR +The \fBoo::abstract\fR class does not define an explicit destructor; +destroying an instance of it is just like destroying an ordinary class (and +will destroy all its subclasses). +.SS "EXPORTED METHODS" +The \fBoo::abstract\fR class defines no new exported methods. +.SS "NON-EXPORTED METHODS" +The \fBoo::abstract\fR class explicitly states that \fBcreate\fR, +\fBcreateWithNamespace\fR, and \fBnew\fR are unexported. +.SH EXAMPLES +.PP +This example defines a simple class hierarchy and creates a new instance of +it. It then invokes a method of the object before destroying the hierarchy and +showing that the destruction is transitive. +.PP +.CS +\fBoo::abstract\fR create fruit { + method eat {} { + puts "yummy!" + } +} +oo::class create banana { + superclass fruit + method peel {} { + puts "skin now off" + } +} +set b [banana \fBnew\fR] +$b peel \fI\(-> prints 'skin now off'\fR +$b eat \fI\(-> prints 'yummy!'\fR +set f [fruit new] \fI\(-> error 'unknown method "new"...'\fR +.CE +.SH "SEE ALSO" +oo::define(n), oo::object(n) +.SH KEYWORDS +abstract class, class, metaclass, object +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/append.n b/doc/append.n index e3bf224..99b4ece 100644 --- a/doc/append.n +++ b/doc/append.n @@ -20,6 +20,11 @@ Append all of the \fIvalue\fR arguments to the current value of variable \fIvarName\fR. If \fIvarName\fR does not exist, it is given a value equal to the concatenation of all the \fIvalue\fR arguments. +.VS TIP508 +If \fIvarName\fR indicate an element that does not exist of an array that has +a default value set, the concatenation of the default value and all the +\fIvalue\fR arguments will be stored in the array element. +.VE TIP508 The result of this command is the new value stored in variable \fIvarName\fR. This command provides an efficient way to build up long @@ -44,6 +49,7 @@ puts $var concat(n), lappend(n) .SH KEYWORDS append, variable -'\" Local Variables: -'\" mode: nroff -'\" End: +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/array.n b/doc/array.n index 25ad0c6..268597d 100644 --- a/doc/array.n +++ b/doc/array.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH array n 8.3 Tcl "Tcl Built-In Commands" +.TH array n 8.7 Tcl "Tcl Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! @@ -36,6 +36,53 @@ with an empty name, since the return value from \fBarray nextelement\fR will not indicate whether the search has been completed. .TP +\fBarray default \fIsubcommand arrayName args...\fR +.VS TIP508 +Manages the default value of the array. Arrays initially have no default +value, but this command allows you to set one; the default value will be +returned when reading from an element of the array \fIarrayName\fR if the read +would otherwise result in an error. Note that this may cause the \fBappend\fR, +\fBdict\fR, \fBincr\fR and \fBlappend\fR commands to change their behavior in +relation to non-existing array elements. +.RS +.PP +The \fIsubcommand\fR argument controls what exact operation will be performed +on the default value of \fIarrayName\fR. Supported \fIsubcommand\fRs are: +.VE TIP508 +.TP +\fBarray default exists \fIarrayName\fR +.VS TIP508 +This returns a boolean value indicating whether a default value has been set +for the array \fIarrayName\fR. Returns a false value if \fIarrayName\fR does +not exist. Raises an error if \fIarrayName\fR is an existing variable that is +not an array. +.VE TIP508 +.TP +\fBarray default get \fIarrayName\fR +.VS TIP508 +This returns the current default value for the array \fIarrayName\fR. Raises +an error if \fIarrayName\fR is an existing variable that is not an array, or +if \fIarrayName\fR is an array without a default value. +.VE TIP508 +.TP +\fBarray default set \fIarrayName value\fR +.VS TIP508 +This sets the default value for the array \fIarrayName\fR to \fIvalue\fR. +Returns the empty string. Raises an error if \fIarrayName\fR is an existing +variable that is not an array, or if \fIarrayName\fR is an illegal name for an +array. If \fIarrayName\fR does not currently exist, it is created as an empty +array as well as having its default value set. +.VE TIP508 +.TP +\fBarray default unset \fIarrayName\fR +.VS TIP508 +This removes the default value for the array \fIarrayName\fR and returns the +empty string. Does nothing if \fIarrayName\fR does not have a default +value. Raises an error if \fIarrayName\fR is an existing variable that is not +an array. +.VE TIP508 +.RE +.TP \fBarray donesearch \fIarrayName searchId\fR This command terminates an array search and destroys all the state associated with that search. \fISearchId\fR indicates @@ -47,6 +94,15 @@ been the return value from a previous invocation of Returns 1 if \fIarrayName\fR is an array variable, 0 if there is no variable by that name or if it is a scalar variable. .TP +\fBarray for {\fIkeyVariable valueVariable\fB} \fIarrayName body\fP +The first argument is a two element list of variable names for the +key and value of each entry in the array. The second argument is the +array name to iterate over. The third argument is the body to execute +for each key and value returned. +The ordering of the returned keys is undefined. +If an array element is deleted or a new array element is inserted during +the \fIarray for\fP process, the command will terminate with an error. +.TP \fBarray get \fIarrayName\fR ?\fIpattern\fR? Returns a list containing pairs of elements. The first element in each pair is the name of an element in \fIarrayName\fR @@ -185,3 +241,7 @@ foreach color [lsort [\fBarray names\fR colorcount]] { list(n), string(n), variable(n), trace(n), foreach(n) .SH KEYWORDS array, element names, search +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/binary.n b/doc/binary.n index 92a939a..0e8b28e 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -12,12 +12,10 @@ .SH NAME binary \- Insert and extract fields from binary strings .SH SYNOPSIS -.VS 8.6 \fBbinary decode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR .br \fBbinary encode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR .br -.VE 8.6 \fBbinary format \fIformatString \fR?\fIarg arg ...\fR? .br \fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR? @@ -31,11 +29,9 @@ architecture, it might produce an 8-byte binary string consisting of two 4-byte integers, one for each of the numbers. The subcommand \fBbinary scan\fR, does the opposite: it extracts data from a binary string and returns it as ordinary Tcl string values. -.VS 8.6 The \fBbinary encode\fR and \fBbinary decode\fR subcommands convert binary data to or from string encodings such as base64 (used in MIME messages for example). -.VE 8.6 .PP Note that other operations on binary data, such as taking a subsequence of it, getting its length, or reinterpreting it as a string in some encoding, are @@ -44,7 +40,6 @@ done by other Tcl commands (respectively \fBstring range\fR, binary string in Tcl is merely one where all the characters it contains are in the range \eu0000\-\eu00FF. .SH "BINARY ENCODE AND DECODE" -.VS 8.6 .PP When encoding binary data as a readable string, the starting binary data is passed to the \fBbinary encode\fR command, together with the name of the @@ -135,7 +130,6 @@ between the encoder and decoder. Note that neither the encoder nor the decoder handle the header and footer of the uuencode format. .RE -.VE 8.6 .SH "BINARY FORMAT" .PP The \fBbinary format\fR command generates a binary string whose layout @@ -150,7 +144,9 @@ Most field specifiers consume one argument to obtain the value to be formatted. The type character specifies how the value is to be formatted. The \fIcount\fR typically indicates how many items of the specified type are taken from the value. If present, the \fIcount\fR -is a non-negative decimal integer or \fB*\fR, which normally indicates +is a non-negative decimal integer or +.QW \fB*\fR , +which normally indicates that all of the items in the value are to be used. If the number of arguments does not match the number of fields in the format string that consume arguments, then an error is generated. The flag character @@ -158,6 +154,7 @@ is ignored for \fBbinary format\fR. .PP Here is a small example to clarify the relation between the field specifiers and the arguments: +.PP .CS \fBbinary format\fR d3d {1.0 2.0 3.0 4.0} 0.1 .CE @@ -185,29 +182,63 @@ not part of the ISO 8859\-1 character set.) If \fIarg\fR has fewer than \fIcount\fR bytes, then additional zero bytes are used to pad out the field. If \fIarg\fR is longer than the specified length, the extra characters will be ignored. If -\fIcount\fR is \fB*\fR, then all of the bytes in \fIarg\fR will be +\fIcount\fR is +.QW \fB*\fR , +then all of the bytes in \fIarg\fR will be formatted. If \fIcount\fR is omitted, then one character will be -formatted. For example, +formatted. For example, the command: .RS +.PP .CS \fBbinary format\fR a7a*a alpha bravo charlie .CE -will return a string equivalent to \fBalpha\e000\e000bravoc\fR, +.PP +will return a binary string equivalent to: +.PP +.CS +\fBalpha\e000\e000bravoc\fR +.CE +.PP +the command: +.PP .CS \fBbinary format\fR a* [encoding convertto utf-8 \eu20ac] .CE -will return a string equivalent to \fB\e342\e202\e254\fR (which is the -UTF-8 byte sequence for a Euro-currency character) and +.PP +will return a binary string equivalent to: +.PP +.CS +\fB\e342\e202\e254\fR +.CE +.PP +(which is the +UTF-8 byte sequence for a Euro-currency character), and the command: +.PP .CS \fBbinary format\fR a* [encoding convertto iso8859-15 \eu20ac] .CE -will return a string equivalent to \fB\e244\fR (which is the ISO +.PP +will return a binary string equivalent to: +.PP +.CS +\fB\e244\fR +.CE +.PP +(which is the ISO 8859\-15 byte sequence for a Euro-currency character). Contrast these last two with: +.PP .CS \fBbinary format\fR a* \eu20ac .CE -which returns a string equivalent to \fB\e254\fR (i.e. \fB\exac\fR) by +.PP +which returns a binary string equivalent to: +.PP +.CS +\fB\e254\fR +.CE +.PP +(i.e. \fB\exac\fR) by truncating the high-bits of the character, and which is probably not what is desired. .RE @@ -215,42 +246,62 @@ what is desired. This form is the same as \fBa\fR except that spaces are used for padding instead of nulls. For example, .RS +.PP .CS \fBbinary format\fR A6A*A alpha bravo charlie .CE -will return \fBalpha bravoc\fR. +.PP +will return +.PP +.CS +\fBalpha bravoc\fR +.CE .RE .IP \fBb\fR 5 Stores a string of \fIcount\fR binary digits in low-to-high order -within each byte in the output string. \fIArg\fR must contain a +within each byte in the output binary string. \fIArg\fR must contain a sequence of \fB1\fR and \fB0\fR characters. The resulting bytes are emitted in first to last order with the bits being formatted in low-to-high order within each byte. If \fIarg\fR has fewer than \fIcount\fR digits, then zeros will be used for the remaining bits. If \fIarg\fR has more than the specified number of digits, the extra -digits will be ignored. If \fIcount\fR is \fB*\fR, then all of the +digits will be ignored. If \fIcount\fR is +.QW \fB*\fR , +then all of the digits in \fIarg\fR will be formatted. If \fIcount\fR is omitted, then one digit will be formatted. If the number of bits formatted does not end at a byte boundary, the remaining bits of the last byte will be zeros. For example, .RS +.PP .CS \fBbinary format\fR b5b* 11100 111000011010 .CE -will return a string equivalent to \fB\ex07\ex87\ex05\fR. +.PP +will return a binary string equivalent to: +.PP +.CS +\fB\ex07\ex87\ex05\fR +.CE .RE .IP \fBB\fR 5 This form is the same as \fBb\fR except that the bits are stored in high-to-low order within each byte. For example, .RS +.PP .CS \fBbinary format\fR B5B* 11100 111000011010 .CE -will return a string equivalent to \fB\exe0\exe1\exa0\fR. +.PP +will return a binary string equivalent to: +.PP +.CS +\fB\exe0\exe1\exa0\fR +.CE .RE .IP \fBH\fR 5 Stores a string of \fIcount\fR hexadecimal digits in high-to-low -within each byte in the output string. \fIArg\fR must contain a +within each byte in the output binary string. \fIArg\fR must contain a sequence of characters in the set .QW 0123456789abcdefABCDEF . The resulting bytes are emitted in first to last order with the hex digits @@ -258,43 +309,66 @@ being formatted in high-to-low order within each byte. If \fIarg\fR has fewer than \fIcount\fR digits, then zeros will be used for the remaining digits. If \fIarg\fR has more than the specified number of digits, the extra digits will be ignored. If \fIcount\fR is -\fB*\fR, then all of the digits in \fIarg\fR will be formatted. If +.QW \fB*\fR , +then all of the digits in \fIarg\fR will be formatted. If \fIcount\fR is omitted, then one digit will be formatted. If the number of digits formatted does not end at a byte boundary, the remaining bits of the last byte will be zeros. For example, .RS +.PP .CS \fBbinary format\fR H3H*H2 ab DEF 987 .CE -will return a string equivalent to \fB\exab\ex00\exde\exf0\ex98\fR. +.PP +will return a binary string equivalent to: +.PP +.CS +\fB\exab\ex00\exde\exf0\ex98\fR +.CE .RE .IP \fBh\fR 5 This form is the same as \fBH\fR except that the digits are stored in low-to-high order within each byte. This is seldom required. For example, .RS +.PP .CS \fBbinary format\fR h3h*h2 AB def 987 .CE -will return a string equivalent to \fB\exba\ex00\exed\ex0f\ex89\fR. +.PP +will return a binary string equivalent to: +.PP +.CS +\fB\exba\ex00\exed\ex0f\ex89\fR +.CE .RE .IP \fBc\fR 5 Stores one or more 8-bit integer values in the output string. If no \fIcount\fR is specified, then \fIarg\fR must consist of an integer value. If \fIcount\fR is specified, \fIarg\fR must consist of a list containing at least that many integers. The low-order 8 bits of each integer -are stored as a one-byte value at the cursor position. If \fIcount\fR -is \fB*\fR, then all of the integers in the list are formatted. If the +are stored as a one-byte value at the cursor position. If \fIcount\fR is +.QW \fB*\fR , +then all of the integers in the list are formatted. If the number of elements in the list is greater than \fIcount\fR, then the extra elements are ignored. For example, .RS +.PP .CS \fBbinary format\fR c3cc* {3 -3 128 1} 260 {2 5} .CE -will return a string equivalent to -\fB\ex03\exfd\ex80\ex04\ex02\ex05\fR, whereas +.PP +will return a binary string equivalent to: +.PP +.CS +\fB\ex03\exfd\ex80\ex04\ex02\ex05\fR +.CE +.PP +whereas: +.PP .CS \fBbinary format\fR c {2 5} .CE +.PP will generate an error. .RE .IP \fBs\fR 5 @@ -304,22 +378,32 @@ low-order 16-bits of each integer are stored as a two-byte value at the cursor position with the least significant byte stored first. For example, .RS +.PP .CS \fBbinary format\fR s3 {3 -3 258 1} .CE -will return a string equivalent to -\fB\ex03\ex00\exfd\exff\ex02\ex01\fR. +.PP +will return a binary string equivalent to: +.PP +.CS +\fB\ex03\ex00\exfd\exff\ex02\ex01\fR +.CE .RE .IP \fBS\fR 5 This form is the same as \fBs\fR except that it stores one or more 16-bit integers in big-endian byte order in the output string. For example, .RS +.PP .CS \fBbinary format\fR S3 {3 -3 258 1} .CE -will return a string equivalent to -\fB\ex00\ex03\exff\exfd\ex01\ex02\fR. +.PP +will return a binary string equivalent to: +.PP +.CS +\fB\ex00\ex03\exff\exfd\ex01\ex02\fR +.CE .RE .IP \fBt\fR 5 This form (mnemonically \fItiny\fR) is the same as \fBs\fR and \fBS\fR @@ -334,22 +418,32 @@ low-order 32-bits of each integer are stored as a four-byte value at the cursor position with the least significant byte stored first. For example, .RS +.PP .CS \fBbinary format\fR i3 {3 -3 65536 1} .CE -will return a string equivalent to +.PP +will return a binary string equivalent to: +.PP +.CS \fB\ex03\ex00\ex00\ex00\exfd\exff\exff\exff\ex00\ex00\ex01\ex00\fR +.CE .RE .IP \fBI\fR 5 This form is the same as \fBi\fR except that it stores one or more one or more 32-bit integers in big-endian byte order in the output string. For example, .RS +.PP .CS \fBbinary format\fR I3 {3 -3 65536 1} .CE -will return a string equivalent to +.PP +will return a binary string equivalent to: +.PP +.CS \fB\ex00\ex00\ex00\ex03\exff\exff\exff\exfd\ex00\ex01\ex00\ex00\fR +.CE .RE .IP \fBn\fR 5 This form (mnemonically \fInumber\fR or \fInormal\fR) is the same as @@ -365,20 +459,24 @@ low-order 64-bits of each integer are stored as an eight-byte value at the cursor position with the least significant byte stored first. For example, .RS +.PP .CS \fBbinary format\fR w 7810179016327718216 .CE -will return the string \fBHelloTcl\fR +.PP +will return the binary string \fBHelloTcl\fR. .RE .IP \fBW\fR 5 This form is the same as \fBw\fR except that it stores one or more one or more 64-bit integers in big-endian byte order in the output string. For example, .RS +.PP .CS \fBbinary format\fR Wc 4785469626960341345 110 .CE -will return the string \fBBigEndian\fR +.PP +will return the binary string \fBBigEndian\fR .RE .IP \fBm\fR 5 This form (mnemonically the mirror of \fBw\fR) is the same as \fBw\fR @@ -401,11 +499,16 @@ double-precision floating point numbers internally, there may be some loss of precision in the conversion to single-precision. For example, on a Windows system running on an Intel Pentium processor, .RS +.PP .CS \fBbinary format\fR f2 {1.6 3.4} .CE -will return a string equivalent to -\fB\excd\excc\excc\ex3f\ex9a\ex99\ex59\ex40\fR. +.PP +will return a binary string equivalent to: +.PP +.CS +\fB\excd\excc\excc\ex3f\ex9a\ex99\ex59\ex40\fR +.CE .RE .IP \fBr\fR 5 This form (mnemonically \fIreal\fR) is the same as \fBf\fR except that @@ -422,11 +525,16 @@ or more double-precision floating point numbers in the machine's native representation in the output string. For example, on a Windows system running on an Intel Pentium processor, .RS +.PP .CS \fBbinary format\fR d1 {1.6} .CE -will return a string equivalent to -\fB\ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f\fR. +.PP +will return a binary string equivalent to: +.PP +.CS +\fB\ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f\fR +.CE .RE .IP \fBq\fR 5 This form (mnemonically the mirror of \fBd\fR) is the same as \fBd\fR @@ -439,26 +547,37 @@ This form is the same as \fBq\fR except that it stores the double-precision floating point numbers in big-endian order. .IP \fBx\fR 5 Stores \fIcount\fR null bytes in the output string. If \fIcount\fR is -not specified, stores one null byte. If \fIcount\fR is \fB*\fR, +not specified, stores one null byte. If \fIcount\fR is +.QW \fB*\fR , generates an error. This type does not consume an argument. For example, .RS +.PP .CS \fBbinary format\fR a3xa3x2a3 abc def ghi .CE -will return a string equivalent to \fBabc\e000def\e000\e000ghi\fR. +.PP +will return a binary string equivalent to: +.PP +.CS +\fBabc\e000def\e000\e000ghi\fR +.CE .RE .IP \fBX\fR 5 Moves the cursor back \fIcount\fR bytes in the output string. If -\fIcount\fR is \fB*\fR or is larger than the current cursor position, +\fIcount\fR is +.QW \fB*\fR +or is larger than the current cursor position, then the cursor is positioned at location 0 so that the next byte stored will be the first byte in the result string. If \fIcount\fR is omitted then the cursor is moved back one byte. This type does not consume an argument. For example, .RS +.PP .CS \fBbinary format\fR a3X*a3X2a3 abc def ghi .CE +.PP will return \fBdghi\fR. .RE .IP \fB@\fR 5 @@ -467,14 +586,22 @@ specified by \fIcount\fR. Position 0 refers to the first byte in the output string. If \fIcount\fR refers to a position beyond the last byte stored so far, then null bytes will be placed in the uninitialized locations and the cursor will be placed at the specified location. If -\fIcount\fR is \fB*\fR, then the cursor is moved to the current end of +\fIcount\fR is +.QW \fB*\fR , +then the cursor is moved to the current end of the output string. If \fIcount\fR is omitted, then an error will be generated. This type does not consume an argument. For example, .RS +.PP .CS \fBbinary format\fR a5@2a1@*a3@10a1 abcde f ghi j .CE -will return \fBabfdeghi\e000\e000j\fR. +.PP +will return +.PP +.CS +\fBabfdeghi\e000\e000j\fR +.CE .RE .SH "BINARY SCAN" .PP @@ -496,8 +623,9 @@ argument to obtain the variable into which the scanned values should be placed. The type character specifies how the binary data is to be interpreted. The \fIcount\fR typically indicates how many items of the specified type are taken from the data. If present, the -\fIcount\fR is a non-negative decimal integer or \fB*\fR, which -normally indicates that all of the remaining items in the data are to +\fIcount\fR is a non-negative decimal integer or +.QW \fB*\fR , +which normally indicates that all of the remaining items in the data are to be used. If there are not enough bytes left after the current cursor position to satisfy the current field specifier, then the corresponding variable is left untouched and \fBbinary scan\fR returns @@ -511,6 +639,7 @@ is accepted for all field types but is ignored for non-integer fields. A similar example as with \fBbinary format\fR should explain the relation between field specifiers and arguments in case of the binary scan subcommand: +.PP .CS \fBbinary scan\fR $bytes s3s first second .CE @@ -522,12 +651,15 @@ If \fIbytes\fR contains fewer than 8 bytes (i.e. four 2-byte integers), no assignment to \fIsecond\fR will be made, and if \fIbytes\fR contains fewer than 6 bytes (i.e. three 2-byte integers), no assignment to \fIfirst\fR will be made. Hence: +.PP .CS puts [\fBbinary scan\fR abcdefg s3s first second] puts $first puts $second .CE +.PP will print (assuming neither variable is set previously): +.PP .CS 1 25185 25699 26213 @@ -539,14 +671,17 @@ It is \fIimportant\fR to note that the \fBc\fR, \fBs\fR, and \fBS\fR long data size values. In doing this, values that have their high bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints), will be sign extended. Thus the following will occur: +.PP .CS set signShort [\fBbinary format\fR s1 0x8000] \fBbinary scan\fR $signShort s1 val; \fI# val == 0xFFFF8000\fR .CE +.PP If you require unsigned values you can include the .QW u flag character following the field type. For example, to read an unsigned short value: +.PP .CS set signShort [\fBbinary format\fR s1 0x8000] \fBbinary scan\fR $signShort su1 val; \fI# val == 0x00008000\fR @@ -557,8 +692,9 @@ reading bytes from the current position. The cursor is initially at position 0 at the beginning of the data. The type may be any one of the following characters: .IP \fBa\fR 5 -The data is a byte string of length \fIcount\fR. If \fIcount\fR -is \fB*\fR, then all of the remaining bytes in \fIstring\fR will be +The data is a byte string of length \fIcount\fR. If \fIcount\fR is +.QW \fB*\fR , +then all of the remaining bytes in \fIstring\fR will be scanned into the variable. If \fIcount\fR is omitted, then one byte will be scanned. All bytes scanned will be interpreted as being characters in the @@ -567,24 +703,30 @@ needed if the string is not a binary string or a string encoded in ISO 8859\-1. For example, .RS +.PP .CS \fBbinary scan\fR abcde\e000fghi a6a10 var1 var2 .CE +.PP will return \fB1\fR with the string equivalent to \fBabcde\e000\fR stored in \fIvar1\fR and \fIvar2\fR left unmodified, and +.PP .CS \fBbinary scan\fR \e342\e202\e254 a* var1 set var2 [encoding convertfrom utf-8 $var1] .CE +.PP will store a Euro-currency character in \fIvar2\fR. .RE .IP \fBA\fR 5 This form is the same as \fBa\fR, except trailing blanks and nulls are stripped from the scanned value before it is stored in the variable. For example, .RS +.PP .CS \fBbinary scan\fR "abc efghi \e000" A* var1 .CE +.PP will return \fB1\fR with \fBabc efghi\fR stored in \fIvar1\fR. .RE .IP \fBb\fR 5 @@ -595,13 +737,16 @@ and .QW 0 characters. The data bytes are scanned in first to last order with the bits being taken in low-to-high order within each byte. Any extra -bits in the last byte are ignored. If \fIcount\fR is \fB*\fR, then -all of the remaining bits in \fIstring\fR will be scanned. If +bits in the last byte are ignored. If \fIcount\fR is +.QW \fB*\fR , +then all of the remaining bits in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one bit will be scanned. For example, .RS +.PP .CS \fBbinary scan\fR \ex07\ex87\ex05 b5b* var1 var2 .CE +.PP will return \fB2\fR with \fB11100\fR stored in \fIvar1\fR and \fB1110000110100000\fR stored in \fIvar2\fR. .RE @@ -609,9 +754,11 @@ will return \fB2\fR with \fB11100\fR stored in \fIvar1\fR and This form is the same as \fBb\fR, except the bits are taken in high-to-low order within each byte. For example, .RS +.PP .CS \fBbinary scan\fR \ex70\ex87\ex05 B5B* var1 var2 .CE +.PP will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and \fB1000011100000101\fR stored in \fIvar2\fR. .RE @@ -622,13 +769,16 @@ high-to-low order represented as a sequence of characters in the set The data bytes are scanned in first to last order with the hex digits being taken in high-to-low order within each byte. Any extra bits in the last byte are ignored. If \fIcount\fR is -\fB*\fR, then all of the remaining hex digits in \fIstring\fR will be +.QW \fB*\fR , +then all of the remaining hex digits in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one hex digit will be scanned. For example, .RS +.PP .CS \fBbinary scan\fR \ex07\exC6\ex05\ex1f\ex34 H3H* var1 var2 .CE +.PP will return \fB2\fR with \fB07c\fR stored in \fIvar1\fR and \fB051f34\fR stored in \fIvar2\fR. .RE @@ -636,9 +786,11 @@ will return \fB2\fR with \fB07c\fR stored in \fIvar1\fR and This form is the same as \fBH\fR, except the digits are taken in reverse (low-to-high) order within each byte. For example, .RS +.PP .CS \fBbinary scan\fR \ex07\ex86\ex05\ex12\ex34 h3h* var1 var2 .CE +.PP will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and \fB502143\fR stored in \fIvar2\fR. .PP @@ -647,135 +799,151 @@ multiple bytes in order should use the \fBH\fR format. .RE .IP \fBc\fR 5 The data is turned into \fIcount\fR 8-bit signed integers and stored -in the corresponding variable as a list. If \fIcount\fR is \fB*\fR, +in the corresponding variable as a list, or as unsigned if \fBu\fR is placed +immediately after the \fBc\fR. If \fIcount\fR is +.QW \fB*\fR , then all of the remaining bytes in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one 8-bit integer will be scanned. For example, .RS +.PP .CS \fBbinary scan\fR \ex07\ex86\ex05 c2c* var1 var2 .CE +.PP will return \fB2\fR with \fB7 -122\fR stored in \fIvar1\fR and \fB5\fR -stored in \fIvar2\fR. Note that the integers returned are signed, but -they can be converted to unsigned 8-bit quantities using an expression -like: -.CS -set num [expr { $num & 0xFF }] -.CE +stored in \fIvar2\fR. Note that the integers returned are signed unless +\fBcu\fR in place of \fBc\fR. .RE .IP \fBs\fR 5 The data is interpreted as \fIcount\fR 16-bit signed integers -represented in little-endian byte order. The integers are stored in -the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then -all of the remaining bytes in \fIstring\fR will be scanned. If +represented in little-endian byte order, or as unsigned if \fBu\fR is placed +immediately after the \fBs\fR. The integers are stored in +the corresponding variable as a list. If \fIcount\fR is +.QW \fB*\fR , +then all of the remaining bytes in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one 16-bit integer will be scanned. For example, .RS +.PP .CS \fBbinary scan\fR \ex05\ex00\ex07\ex00\exf0\exff s2s* var1 var2 .CE +.PP will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR -stored in \fIvar2\fR. Note that the integers returned are signed, but -they can be converted to unsigned 16-bit quantities using an expression -like: -.CS -set num [expr { $num & 0xFFFF }] -.CE +stored in \fIvar2\fR. Note that the integers returned are signed unless +\fBsu\fR is used in place of \fBs\fR. .RE .IP \fBS\fR 5 This form is the same as \fBs\fR except that the data is interpreted -as \fIcount\fR 16-bit signed integers represented in big-endian byte +as \fIcount\fR 16-bit integers represented in big-endian byte order. For example, .RS +.PP .CS \fBbinary scan\fR \ex00\ex05\ex00\ex07\exff\exf0 S2S* var1 var2 .CE +.PP will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR stored in \fIvar2\fR. .RE .IP \fBt\fR 5 The data is interpreted as \fIcount\fR 16-bit signed integers represented in the native byte order of the machine running the Tcl -script. It is otherwise identical to \fBs\fR and \fBS\fR. +script, or as unsigned if \fBu\fR is placed +immediately after the \fBt\fR. It is otherwise identical to \fBs\fR and \fBS\fR. To determine what the native byte order of the machine is, refer to the \fBbyteOrder\fR element of the \fBtcl_platform\fR array. .IP \fBi\fR 5 The data is interpreted as \fIcount\fR 32-bit signed integers -represented in little-endian byte order. The integers are stored in -the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then -all of the remaining bytes in \fIstring\fR will be scanned. If +represented in little-endian byte order, or as unsigned if \fBu\fR is placed +immediately after the \fBi\fR. The integers are stored in +the corresponding variable as a list. If \fIcount\fR is +.QW \fB*\fR , +then all of the remaining bytes in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one 32-bit integer will be scanned. For example, .RS +.PP .CS set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff \fBbinary scan\fR $str i2i* var1 var2 .CE +.PP will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR -stored in \fIvar2\fR. Note that the integers returned are signed, but -they can be converted to unsigned 32-bit quantities using an expression -like: -.CS -set num [expr { $num & 0xFFFFFFFF }] -.CE +stored in \fIvar2\fR. Note that the integers returned are signed unless +\fBiu\fR is used in place of \fBi\fR. .RE .IP \fBI\fR 5 This form is the same as \fBI\fR except that the data is interpreted as \fIcount\fR 32-bit signed integers represented in big-endian byte -order. For example, +order, or as unsigned if \fBu\fR is placed +immediately after the \fBI\fR. For example, .RS +.PP .CS set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0 \fBbinary scan\fR $str I2I* var1 var2 .CE +.PP will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR stored in \fIvar2\fR. .RE .IP \fBn\fR 5 The data is interpreted as \fIcount\fR 32-bit signed integers represented in the native byte order of the machine running the Tcl -script. It is otherwise identical to \fBi\fR and \fBI\fR. +script, or as unsigned if \fBu\fR is placed +immediately after the \fBn\fR. It is otherwise identical to \fBi\fR and \fBI\fR. To determine what the native byte order of the machine is, refer to the \fBbyteOrder\fR element of the \fBtcl_platform\fR array. .IP \fBw\fR 5 The data is interpreted as \fIcount\fR 64-bit signed integers -represented in little-endian byte order. The integers are stored in -the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then -all of the remaining bytes in \fIstring\fR will be scanned. If +represented in little-endian byte order, or as unsigned if \fBu\fR is placed +immediately after the \fBw\fR. The integers are stored in +the corresponding variable as a list. If \fIcount\fR is +.QW \fB*\fR , +then all of the remaining bytes in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one 64-bit integer will be scanned. For example, .RS +.PP .CS set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff \fBbinary scan\fR $str wi* var1 var2 .CE +.PP will return \fB2\fR with \fB30064771077\fR stored in \fIvar1\fR and -\fB\-16\fR stored in \fIvar2\fR. Note that the integers returned are -signed and cannot be represented by Tcl as unsigned values. +\fB\-16\fR stored in \fIvar2\fR. .RE .IP \fBW\fR 5 This form is the same as \fBw\fR except that the data is interpreted as \fIcount\fR 64-bit signed integers represented in big-endian byte -order. For example, +order, or as unsigned if \fBu\fR is placed +immediately after the \fBW\fR. For example, .RS +.PP .CS set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0 \fBbinary scan\fR $str WI* var1 var2 .CE +.PP will return \fB2\fR with \fB21474836487\fR stored in \fIvar1\fR and \fB\-16\fR stored in \fIvar2\fR. .RE .IP \fBm\fR 5 The data is interpreted as \fIcount\fR 64-bit signed integers represented in the native byte order of the machine running the Tcl -script. It is otherwise identical to \fBw\fR and \fBW\fR. +script, or as unsigned if \fBu\fR is placed +immediately after the \fBm\fR. It is otherwise identical to \fBw\fR and \fBW\fR. To determine what the native byte order of the machine is, refer to the \fBbyteOrder\fR element of the \fBtcl_platform\fR array. .IP \fBf\fR 5 The data is interpreted as \fIcount\fR single-precision floating point numbers in the machine's native representation. The floating point numbers are stored in the corresponding variable as a list. If -\fIcount\fR is \fB*\fR, then all of the remaining bytes in +\fIcount\fR is +.QW \fB*\fR , +then all of the remaining bytes in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one single-precision floating point number will be scanned. The size of a floating point number may vary across architectures, so the number of @@ -784,9 +952,11 @@ valid floating point number, the resulting value is undefined and compiler dependent. For example, on a Windows system running on an Intel Pentium processor, .RS +.PP .CS \fBbinary scan\fR \ex3f\excc\excc\excd f var1 .CE +.PP will return \fB1\fR with \fB1.6000000238418579\fR stored in \fIvar1\fR. .RE @@ -806,9 +976,11 @@ as \fIcount\fR double-precision floating point numbers in the machine's native representation. For example, on a Windows system running on an Intel Pentium processor, .RS +.PP .CS \fBbinary scan\fR \ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f d var1 .CE +.PP will return \fB1\fR with \fB1.6000000000000001\fR stored in \fIvar1\fR. .RE @@ -824,28 +996,36 @@ order. This conversion is not portable to the minority of systems not using IEEE floating point representations. .IP \fBx\fR 5 Moves the cursor forward \fIcount\fR bytes in \fIstring\fR. If -\fIcount\fR is \fB*\fR or is larger than the number of bytes after the +\fIcount\fR is +.QW \fB*\fR +or is larger than the number of bytes after the current cursor position, then the cursor is positioned after the last byte in \fIstring\fR. If \fIcount\fR is omitted, then the cursor is moved forward one byte. Note that this type does not consume an argument. For example, .RS +.PP .CS \fBbinary scan\fR \ex01\ex02\ex03\ex04 x2H* var1 .CE +.PP will return \fB1\fR with \fB0304\fR stored in \fIvar1\fR. .RE .IP \fBX\fR 5 Moves the cursor back \fIcount\fR bytes in \fIstring\fR. If -\fIcount\fR is \fB*\fR or is larger than the current cursor position, +\fIcount\fR is +.QW \fB*\fR +or is larger than the current cursor position, then the cursor is positioned at location 0 so that the next byte scanned will be the first byte in \fIstring\fR. If \fIcount\fR is omitted then the cursor is moved back one byte. Note that this type does not consume an argument. For example, .RS +.PP .CS \fBbinary scan\fR \ex01\ex02\ex03\ex04 c2XH* var1 var2 .CE +.PP will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR stored in \fIvar2\fR. .RE @@ -856,9 +1036,11 @@ by \fIcount\fR. Note that position 0 refers to the first byte in \fIstring\fR, then the cursor is positioned after the last byte. If \fIcount\fR is omitted, then an error will be generated. For example, .RS +.PP .CS \fBbinary scan\fR \ex01\ex02\ex03\ex04 c2@1H* var1 var2 .CE +.PP will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR stored in \fIvar2\fR. .RE diff --git a/doc/callback.n b/doc/callback.n new file mode 100644 index 0000000..95838a9 --- /dev/null +++ b/doc/callback.n @@ -0,0 +1,88 @@ +'\" +'\" Copyright (c) 2018 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH callback n 0.3 TclOO "TclOO Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +callback, mymethod \- generate callbacks to methods +.SH SYNOPSIS +.nf +package require TclOO + +\fBcallback\fR \fImethodName\fR ?\fIarg ...\fR? +\fBmymethod\fR \fImethodName\fR ?\fIarg ...\fR? +.fi +.BE +.SH DESCRIPTION +The \fBcallback\fR command, +'\" Based on notes in the tcllib docs, we know the provenance of mymethod +also called \fBmymethod\fR for compatibility with the ooutil and snit packages +of Tcllib, +and which should only be used from within the context of a call to a method +(i.e. inside a method, constructor or destructor body) is used to generate a +script fragment that will invoke the method, \fImethodName\fR, on the current +object (as reported by \fBself\fR) when executed. Any additional arguments +provided will be provided as leading arguments to the callback. The resulting +script fragment shall be a proper list. +.PP +Note that it is up to the caller to ensure that the current object is able to +handle the call of \fImethodName\fR; this command does not check that. +\fImethodName\fR may refer to any exported or unexported method, but may not +refer to a private method as those can only be invoked directly from within +methods. If there is no such method present at the point when the callback is +invoked, the standard \fBunknown\fR method handler will be called. +.SH EXAMPLE +This is a simple echo server class. The \fBcallback\fR command is used in two +places, to arrange for the incoming socket connections to be handled by the +\fIAccept\fR method, and to arrange for the incoming bytes on those +connections to be handled by the \fIReceive\fR method. +.PP +.CS +oo::class create EchoServer { + variable server clients + constructor {port} { + set server [socket -server [\fBcallback\fR Accept] $port] + set clients {} + } + destructor { + chan close $server + foreach client [dict keys $clients] { + chan close $client + } + } + + method Accept {channel clientAddress clientPort} { + dict set clients $channel [dict create \e + address $clientAddress port $clientPort] + chan event $channel readable [\fBcallback\fR Receive $channel] + } + method Receive {channel} { + if {[chan gets $channel line] >= 0} { + my echo $channel $line + } else { + chan close $channel + dict unset clients $channel + } + } + + method echo {channel line} { + dict with clients $channel { + chan puts $channel \e + [format {[%s:%d] %s} $address $port $line] + } + } +} +.CE +.SH "SEE ALSO" +chan(n), fileevent(n), my(n), self(n), socket(n), trace(n) +.SH KEYWORDS +callback, object +.\" Local Variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/catch.n b/doc/catch.n index d43a7ec..8d885d4 100644 --- a/doc/catch.n +++ b/doc/catch.n @@ -56,9 +56,7 @@ When the return code from evaluation of \fIscript\fR is \fBTCL_ERROR\fR, four additional entries are defined in the dictionary of return options stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR, \fB\-errorcode\fR, \fB\-errorline\fR, and -.VS 8.6 \fB\-errorstack\fR. -.VE 8.6 The value of the \fB\-errorinfo\fR entry is a formatted stack trace containing more information about the context in which the error happened. The formatted stack trace is meant to be read by a person. The value of the @@ -67,7 +65,6 @@ list. The \fB\-errorcode\fR value is meant to be further processed by programs, and may not be particularly readable by people. The value of the \fB\-errorline\fR entry is an integer indicating which line of \fIscript\fR was being evaluated when the error occurred. -.VS 8.6 The value of the \fB\-errorstack\fR entry is an even-sized list made of token-parameter pairs accumulated while unwinding the stack. The token may be @@ -87,14 +84,11 @@ the static text of the calling sites, and .IP [3] it is coarser-grained, with only one element per stack frame (like procs; no separate elements for \fBforeach\fR constructs for example). -.VE 8.6 .PP The values of the \fB\-errorinfo\fR and \fB\-errorcode\fR entries of the most recent error are also available as values of the global variables \fB::errorInfo\fR and \fB::errorCode\fR respectively. -.VS 8.6 The value of the \fB\-errorstack\fR entry surfaces as \fBinfo errorstack\fR. -.VE 8.6 .PP Tcl packages may provide commands that set other entries in the dictionary of return options, and the \fBreturn\fR command may be @@ -22,7 +22,7 @@ home directory (as specified in the HOME environment variable) if Returns an empty string. Note that the current working directory is a per-process resource; the \fBcd\fR command changes the working directory for all interpreters -and (in a threaded environment) all threads. +and all threads. .SH EXAMPLES .PP Change to the home directory of the user \fBfred\fR: @@ -41,3 +41,7 @@ current one: filename(n), glob(n), pwd(n) .SH KEYWORDS working directory +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: @@ -35,7 +35,6 @@ turned on by default. . Close and destroy the channel called \fIchannelId\fR. Note that this deletes all existing file-events registered on the channel. -.VS 8.6 If the \fIdirection\fR argument (which must be \fBread\fR or \fBwrite\fR or any unique abbreviation of them) is present, the channel will only be half-closed, so that it can go from being read-write to write-only or @@ -45,7 +44,6 @@ write-only channels. Without the \fIdirection\fR argument, the channel is closed for both reading and writing (but only if those directions are currently open). It is an error to close a read-only channel for writing, or a write-only channel for reading. -.VE 8.6 .RS .PP As part of closing the channel, all buffered output is flushed to the @@ -83,12 +81,10 @@ an error occurs while flushing output. If a command in a command pipeline created with \fBopen\fR returns an error, \fBchan close\fR generates an error (similar to the \fBexec\fR command.) .PP -.VS 8.6 Note that half-closes of sockets and command pipelines can have important side effects because they result in a shutdown() or close() of the underlying system resource, which can change how other processes or systems respond to the Tcl program. -.VE 8.6 .RE .TP \fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... @@ -540,7 +536,6 @@ an extremely long line that exceeds the available memory to buffer it). Returns -1 if the channel was not opened for the mode in question. .TP \fBchan pipe\fR -.VS 8.6 Creates a standalone pipe whose read- and write-side channels are returned as a 2-element list, the first element being the read side and the second the write side. Can be useful e.g. to redirect @@ -561,16 +556,13 @@ is most likely to show up when using pipelines for testing; care should be taken to ensure that deadlocks do not occur and that potential short reads are allowed for. .RE -.VE 8.6 .TP \fBchan pop \fIchannelId\fR -.VS 8.6 Removes the topmost transformation from the channel \fIchannelId\fR, if there is any. If there are no transformations added to \fIchannelId\fR, this is equivalent to \fBchan close\fR of that channel. The result is normally the empty string, but can be an error in some situations (i.e. where the underlying system stream is closed and that results in an error). -.VE 8.6 .TP \fBchan postevent \fIchannelId eventSpec\fR . @@ -609,7 +601,6 @@ executed in the interpreter that set them up. .RE .TP \fBchan push \fIchannelId cmdPrefix\fR -.VS 8.6 Adds a new transformation on top of the channel \fIchannelId\fR. The \fIcmdPrefix\fR argument describes a list of one or more words which represent a handler that will be used to implement the transformation. The command @@ -618,7 +609,6 @@ The result of this subcommand is a handle to the transformation. Note that it is important to make sure that the transformation is capable of supporting the channel mode that it is used with or this can make the channel neither readable nor writable. -.VE 8.6 .TP \fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR . diff --git a/doc/classvariable.n b/doc/classvariable.n new file mode 100644 index 0000000..0798bb2 --- /dev/null +++ b/doc/classvariable.n @@ -0,0 +1,78 @@ +'\" +'\" Copyright (c) 2011-2015 Andreas Kupries +'\" Copyright (c) 2018 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH classvariable n 0.3 TclOO "TclOO Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +classvariable \- create link from local variable to variable in class +.SH SYNOPSIS +.nf +package require TclOO + +\fBclassvariable\fR \fIvariableName\fR ?\fI...\fR? +.fi +.BE +.SH DESCRIPTION +The \fBclassvariable\fR command is available within methods. It takes a series +of one or more variable names and makes them available in the method's scope; +those variable names must not be qualified and must not refer to array +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 +method defined directly on a class instance (e.g., through the +\fBoo::objdefine\fR \fBmethod\fR definition) this is very much like just +using: +.PP +.CS +namespace upvar [namespace current] $var $var +.CE +.PP +for each variable listed to \fBclassvariable\fR. +.SH EXAMPLE +This class counts how many instances of it have been made. +.PP +.CS +oo::class create Counted { + initialise { + variable count 0 + } + + variable number + constructor {} { + \fBclassvariable\fR count + set number [incr count] + } + + method report {} { + \fBclassvariable\fR count + puts "This is instance $number of $count" + } +} + +set a [Counted new] +set b [Counted new] +$a report + \fI\(-> This is instance 1 of 2\fR +set c [Counted new] +$b report + \fI\(-> This is instance 2 of 3\fR +$c report + \fI\(-> This is instance 3 of 3\fR +.CE +.SH "SEE ALSO" +global(n), namespace(n), oo::class(n), oo::define(n), upvar(n), variable(n) +.SH KEYWORDS +class, class variable, variable +.\" Local Variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/clock.n b/doc/clock.n index a8c6d29..a3f934a 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -89,10 +89,9 @@ have 59 or 61 seconds. .TP \fIunit\fR One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR, -\fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or -any unique prefix of such a word. Used in conjunction with \fIcount\fR -to identify an interval of time, for example, \fI3 seconds\fR or -\fI1 year\fR. +\fBdays\fR, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR. +Used in conjunction with \fIcount\fR to identify an interval of time, +for example, \fI3 seconds\fR or \fI1 year\fR. .SS "OPTIONS" .TP \fB\-base\fR time @@ -175,8 +174,7 @@ given as its first argument. The remaining arguments (other than the possible \fB\-timezone\fR, \fB\-locale\fR and \fB\-gmt\fR options) are integers and keywords in alternation, where the keywords are chosen from \fBseconds\fR, \fBminutes\fR, \fBhours\fR, -\fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or -any unique prefix of such a word. +\fBdays\fR, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR. .PP Addition of seconds, minutes and hours is fairly straightforward; the given time increment (times sixty for minutes, or 3600 for hours) @@ -213,7 +211,8 @@ the given time to a calendar day and time of day in the appropriate time zone and locale. The requisite number of days (weeks are converted to days by multiplying by seven) is added to the calendar day, and the date and time are then converted back to a count of seconds from -the epoch time. +the epoch time. The \fBweekdays\fR keyword is similar to \fBdays\fR, +with the only difference that weekends - Saturdays and Sundays - are skipped. .PP Adding and subtracting a given number of days across the point that the time changes at the start or end of summer time (Daylight Saving Time) @@ -887,41 +886,47 @@ The \fIinputString\fR argument consists of zero or more specifications of the following form: .TP \fItime\fR -A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR -or \fBhhmm ?meridian? ?zone?\fR -If no meridian is specified, \fBhh\fR is interpreted on +. +A time of day, which is of the form: +.QW "\fIhh\fR?\fB:\fImm\fR?\fB:\fIss\fR?? ?\fImeridian\fR? ?\fIzone\fR?" +or +.QW "\fBhhmm \fR?\fBmeridian\fR? ?\fBzone\fR?" . +If no \fImeridian\fR is specified, \fIhh\fR is interpreted on a 24-hour clock. .TP \fIdate\fR +. A specific month and day with optional year. The acceptable formats are -.QW "\fBmm/dd\fR?\fB/yy\fR?" , -.QW "\fBmonthname dd\fR?\fB, yy\fR?" , -.QW "\fBday, dd monthname \fR?\fByy\fR?" , -.QW "\fBdd monthname yy\fR" , -.QW "?\fBCC\fR?\fByymmdd\fR" , +.QW "\fImm\fB/\fIdd\fR?\fB/\fIyy\fR?" , +.QW "\fImonthname dd\fR?\fB, \fIyy\fR?" , +.QW "\fIday\fB, \fIdd monthname \fR?\fIyy\fR?" , +.QW "\fIdd monthname yy\fR" , +.QW "?\fICC\fR?\fIyymmdd\fR" , and -.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" . +.QW "\fIdd\fB-\fImonthname\fB-\fR?\fICC\fR?\fIyy\fR" . The default year is the current year. If the year is less than 100, we treat the years 00-68 as 2000-2068 and the years 69-99 as 1969-1999. Not all platforms can represent the years 38-70, so an error may result if these years are used. .TP \fIISO 8601 point-in-time\fR +. An ISO 8601 point-in-time specification, such as -.QW \fICCyymmdd\fBT\fIhhmmss\fR, +.QW "\fICCyymmdd\fBT\fIhhmmss\fR", where \fBT\fR is the literal .QW T , .QW "\fICCyymmdd hhmmss\fR" , -.QW \fICCyymmdd\fBT\fIhh:mm:ss\fR , +.QW "\fICCyymmdd\fBT\fIhh:mm:ss\fR" , or -.QW \fICCyy-mm-dd\fBT\fIhh:mm:ss\fR. +.QW "\fICCyy-mm-dd\fBT\fIhh\fB:\fImm\fB:\fIss\fR". Note that only these four formats are accepted. The command does \fInot\fR accept the full range of point-in-time specifications specified in ISO8601. Other formats can be recognized by giving an explicit \fB\-format\fR option to the \fBclock scan\fR command. .TP \fIrelative time\fR +. A specification relative to the current time. The format is \fBnumber unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR, \fBmonth\fR, \fBweek\fR, \fBday\fR, diff --git a/doc/close.n b/doc/close.n index 5daf3e2..3d18aea 100644 --- a/doc/close.n +++ b/doc/close.n @@ -49,16 +49,13 @@ When the last interpreter in which the channel is registered invokes .PP Channels are automatically closed when an interpreter is destroyed and when the process exits. -.VS 8.6 From 8.6 on (TIP#398), nonblocking channels are no longer switched to blocking mode when exiting; this guarantees a timely exit even when the peer or a communication channel is stalled. To ensure proper flushing of stalled nonblocking channels on exit, one must now either (a) actively switch them back to blocking or (b) use the environment variable TCL_FLUSH_NONBLOCKING_ON_EXIT, which when set and not equal to "0" restores the previous behavior. -.VE 8.6 .PP The command returns an empty string, and may generate an error if an error occurs while flushing output. If a command in a command pipeline created with \fBopen\fR returns an error, \fBclose\fR generates an error (similar to the \fBexec\fR command.) .PP -.VS 8.6 The two-argument form is a .QW "half-close" : given a bidirectional channel like a @@ -80,7 +77,6 @@ abnormal exit error. .PP Currently only sockets and command pipelines support half-close. A future extension will allow reflected and stacked channels to do so. -.VE 8.6 .SH EXAMPLE .PP This illustrates how you can use Tcl to ensure that files get closed diff --git a/doc/continue.n b/doc/continue.n index 92ff3b4..5eca861 100644 --- a/doc/continue.n +++ b/doc/continue.n @@ -23,7 +23,7 @@ exception to occur. The exception causes the current script to be aborted out to the innermost containing loop command, which then continues with the next iteration of the loop. -Catch exceptions are also handled in a few other situations, such +Continue exceptions are also handled in a few other situations, such as the \fBcatch\fR command and the outermost scripts of procedure bodies. .SH EXAMPLE diff --git a/doc/cookiejar.n b/doc/cookiejar.n new file mode 100644 index 0000000..0d8b81a --- /dev/null +++ b/doc/cookiejar.n @@ -0,0 +1,217 @@ +'\" +'\" Copyright (c) 2014-2018 Donal K. Fellows. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH "cookiejar" n 0.1 http "Tcl Bundled Packages" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +cookiejar \- Implementation of the Tcl http package cookie jar protocol +.SH SYNOPSIS +.nf +\fBpackage require\fR \fBcookiejar\fR ?\fB0.1\fR? + +\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? +\fB::http::cookiejar create\fR \fIname\fR ?\fIfilename\fR? +\fB::http::cookiejar new\fR ?\fIfilename\fR? + +\fIcookiejar\fR \fBdestroy\fR +\fIcookiejar\fR \fBforceLoadDomainData\fR +\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR +\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR +\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? +.fi +.SH DESCRIPTION +.PP +The cookiejar package provides an implementation of the http package's cookie +jar protocol using an SQLite database. It provides one main command, +\fB::http::cookiejar\fR, which is a TclOO class that should be instantiated to +create a cookie jar that manages a particular HTTP session. +.PP +The database management policy can be controlled at the package level by the +\fBconfigure\fR method on the \fB::http::cookiejar\fR class object: +.TP +\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? +. +If neither \fIoptionName\fR nor \fIoptionValue\fR are supplied, this returns a +copy of the configuration as a Tcl dictionary. If just \fIoptionName\fR is +supplied, just the value of the named option is returned. If both +\fIoptionName\fR and \fIoptionValue\fR are given, the named option is changed +to be the given value. +.RS +.PP +Supported options are: +.TP +\fB\-domainfile \fIfilename\fR +. +A file (defaulting to within the cookiejar package) with a description of the +list of top-level domains (e.g., \fB.com\fR or \fB.co.jp\fR). Such domains +\fImust not\fR accept cookies set upon 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. +.TP +\fB\-domainlist \fIurl\fR +. +A URL to fetch the list of top-level domains (e.g., \fB.com\fR or +\fB.co.jp\fR) from. Such domains \fImust not\fR accept cookies set upon +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. +.TP +\fB\-domainrefresh \fIintervalMilliseconds\fR +. +The number of milliseconds between checks of the \fI\-domainlist\fR for new +domains. +.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. +.TP +\fB\-offline \fIflag\fR +. +Allows the cookie managment 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. +.TP +\fB\-purgeold \fIintervalMilliseconds\fR +. +The number of milliseconds between checks of the database for expired +cookies; expired cookies are deleted. +.TP +\fB\-retain \fIcookieCount\fR +. +The maximum number of cookies to retain in the database. +.TP +\fB\-vacuumtrigger \fIdeletionCount\fR +. +A count of the number of persistent cookie deletions to go between vacuuming +the database. +.RE +.PP +Cookie jar instances may be made with any of the standard TclOO instance +creation methods (\fBcreate\fR or \fBnew\fR). +.TP +\fB::http::cookiejar new\fR ?\fIfilename\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 +memory, which effectively forces all cookies within it to be session cookies. +.SS "INSTANCE METHODS" +.PP +The following methods are supported on the instances: +.TP +\fIcookiejar\fR \fBdestroy\fR +. +This is the standard TclOO destruction method. It does \fInot\fR delete the +SQLite database if it is written to disk. Callers are responsible for ensuring +that the cookie jar is not in use by the http package at the time of +destruction. +.TP +\fIcookiejar\fR \fBforceLoadDomainData\fR +. +This method causes the cookie jar to immediately load (and cache) the domain +list data. The domain list will be loaded from the \fB\-domainlist\fR +configured a the package level if that is enabled, and otherwise will be +obtained from the \fB\-domainfile\fR configured at the package level. +.TP +\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR +. +This method obtains the cookies for a particular HTTP request. \fIThis +implements the http cookie jar protocol.\fR +.TP +\fIcookiejar\fR \fBpolicyAllow\fR \fIoperation domain path\fR +. +This method is called by the \fBstoreCookie\fR method to get a decision on +whether to allow \fIoperation\fR to be performed for the \fIdomain\fR and +\fIpath\fR. This is checked immediately before the database is updated but +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 +. +The \fIdomain\fR is seeking to delete a cookie. +.TP +\fBsession\fR +. +The \fIdomain\fR is seeking to create or update a session cookie. +.TP +\fBset\fR +. +The \fIdomain\fR is seeking to create or update a persistent cookie (with a +defined lifetime). +.PP +The default implementation of this method just returns true, but subclasses of +this class may impose their own rules. +.RE +.TP +\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR +. +This method stores a single cookie from a particular HTTP response. Cookies +that fail security checks are ignored. \fIThis implements the http cookie jar +protocol.\fR +.TP +\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? +. +This method looks a cookie by exact host (or domain) matching. If neither +\fIhost\fR nor \fIkey\fR are supplied, the list of hosts for which a cookie is +stored is returned. If just \fIhost\fR (which may be a hostname or a domain +name) is supplied, the list of cookie keys stored for that host is returned. +If both \fIhost\fR and \fIkey\fR are supplied, the value for that key is +returned; it is an error if no such host or key match exactly. +.SH "EXAMPLES" +.PP +The simplest way of using a cookie jar is to just permanently configure it at +the start of the application. +.PP +.CS +package require http +\fBpackage require cookiejar\fR + +set cookiedb ~/.tclcookies.db +http::configure -cookiejar [\fBhttp::cookiejar new\fR $cookiedb] + +# No further explicit steps are required to use cookies +set tok [http::geturl http://core.tcl.tk/] +.CE +.PP +To only allow a particular domain to use cookies, perhaps because you only +want to enable a particular host to create and manipulate sessions, create a +subclass that imposes that policy. +.PP +.CS +package require http +\fBpackage require cookiejar\fR + +oo::class create MyCookieJar { + superclass \fBhttp::cookiejar\fR + + method \fBpolicyAllow\fR {operation domain path} { + return [expr {$domain eq "my.example.com"}] + } +} + +set cookiedb ~/.tclcookies.db +http::configure -cookiejar [MyCookieJar new $cookiedb] + +# No further explicit steps are required to use cookies +set tok [http::geturl http://core.tcl.tk/] +.CE +.SH "SEE ALSO" +http(n), oo::class(n), sqlite3(n) +.SH KEYWORDS +cookie, internet, security policy, www +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/coroutine.n b/doc/coroutine.n index 52775ef..11f9069 100644 --- a/doc/coroutine.n +++ b/doc/coroutine.n @@ -9,15 +9,18 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -coroutine, yield, yieldto \- Create and produce values from coroutines +coroutine, yield, yieldto, coroinject, coroprobe \- Create and produce values from coroutines .SH SYNOPSIS .nf \fBcoroutine \fIname command\fR ?\fIarg...\fR? \fByield\fR ?\fIvalue\fR? -.VS TIP396 \fByieldto\fR \fIcommand\fR ?\fIarg...\fR? \fIname\fR ?\fIvalue...\fR? -.VE TIP396 +.sp +.VS "8.7, TIP383" +\fBcoroinject \fIcoroName command\fR ?\fIarg...\fR? +\fBcoroprobe \fIcoroName command\fR ?\fIarg...\fR? +.VE "8.7, TIP383" .fi .BE .SH DESCRIPTION @@ -39,7 +42,6 @@ the context to be suspended. If the coroutine context never yields and instead returns conventionally, the result of the \fBcoroutine\fR command will be the result of the evaluation of the context. .PP -.VS TIP396 The coroutine may also suspend its execution by use of the \fByieldto\fR command, which instead of returning, cedes execution to some command called \fIcommand\fR (resolved in the context of the coroutine) and to which \fIany @@ -58,11 +60,10 @@ with multiple arguments is by using \fByieldto\fR and the \fBreturn\fR command, like this: .PP .CS -proc yieldm {value} { - \fByieldto\fR return -level 0 $value +proc yieldMultiple {value} { + tailcall \fByieldto\fR string cat $value } .CE -.VE TIP396 .PP The coroutine can also be deleted by destroying the command \fIname\fR, and the name of the current coroutine can be retrieved by using @@ -75,6 +76,51 @@ At the point when \fIcommand\fR is called, the current namespace will be the global namespace and there will be no stack frames above it (in the sense of \fBupvar\fR and \fBuplevel\fR). However, which command to call will be determined in the namespace that the \fBcoroutine\fR command was called from. +.PP +.VS "8.7, TIP383" +A suspended coroutine (i.e., one that has \fByield\fRed or \fByieldto\fR-d) +may have its state inspected (or modified) at that point by using +\fBcoroprobe\fR to run a command at the point where the coroutine is at. The +command takes the name of the coroutine to run the command in, \fIcoroName\fR, +and the name of a command (any any arguments it requires) to immediately run +at that point. The result of that command is the result of the \fBcoroprobe\fR +command, and the gross state of the coroutine remains the same afterwards +(i.e., the coroutine is still expecting the results of a \fByield\fR or +\fByieldto\fR as before) though variables may have been changed. +.PP +Similarly, the \fBcoroinject\fR command may be used to place a command to be +run inside a suspended coroutine (when it is resumed) to process arguments, +with quite a bit of similarity to \fBcoroprobe\fR. However, with +\fBcoroinject\fR there are several key differences: +.VE "8.7, TIP383" +.IP \(bu +.VS "8.7, TIP383" +The coroutine is not immediately resumed after the injection has been done. A +consequence of this is that multiple injections may be done before the +coroutine is resumed. There injected commands are performed in \fIreverse +order of definition\fR (that is, they are internally stored on a stack). +.VE "8.7, TIP383" +.IP \(bu +.VS "8.7, TIP383" +An additional two arguments are appended to the list of arguments to be run +(that is, the \fIcommand\fR and its \fIargs\fR are extended by two elements). +The first is the name of the command that suspended the coroutine (\fByield\fR +or \fByieldto\fR), and the second is the argument (or list of arguments, in +the case of \fByieldto\fR) that is the current resumption value. +.VE "8.7, TIP383" +.IP \(bu +.VS "8.7, TIP383" +The result of the injected command is used as the result of the \fByield\fR or +\fByieldto\fR that caused the coroutine to become suspended. Where there are +multiple injected commands, the result of one becomes the resumption value +processed by the next. +.PP +The injection is a one-off. It is not retained once it has been executed. It +may \fByield\fR or \fByieldto\fR as part of its execution. +.PP +Note that running coroutines may be neither probed nor injected; the +operations may only be applied to +.VE "8.7, TIP383" .SH EXAMPLES .PP This example shows a coroutine that will produce an infinite sequence of @@ -138,7 +184,6 @@ for {set i 1} {$i <= 20} {incr i} { } .CE .PP -.VS TIP396 This example shows how a value can be passed around a group of three coroutines that yield to each other: .PP @@ -150,14 +195,57 @@ proc juggler {name target {value ""}} { while {$value ne ""} { puts "$name : $value" set value [string range $value 0 end-1] - lassign [\fByieldto\fR $target $value] value + lassign [\fByieldto\fR \fI$target\fR $value] value } } \fBcoroutine\fR j1 juggler Larry [ \fBcoroutine\fR j2 juggler Curly [ \fBcoroutine\fR j3 juggler Moe j1]] "Nyuck!Nyuck!Nyuck!" .CE -.VE TIP396 +.PP +.VS "8.7, TIP383" +This example shows a simple coroutine that collects non-empty values and +returns a list of them when not given an argument. It also shows how we can +look inside the coroutine to find out what it is doing, and how we can modify +the input on a one-off basis. +.PP +.CS +proc collectorImpl {} { + set me [info coroutine] + set accumulator {} + for {set val [\fByield\fR $me]} {$val ne ""} {set val [\fByield\fR]} { + lappend accumulator $val + } + return $accumulator +} + +\fBcoroutine\fR collect collectorImpl +\fIcollect\fR 123 +\fIcollect\fR "abc def" +\fIcollect\fR 456 + +puts [\fBcoroprobe \fIcollect\fR set accumulator] +# ==> 123 {abc def} 456 + +\fIcollect\fR "pqr" + +\fBcoroinject \fIcollect\fR apply {{type value} { + puts "Received '$value' at a $type in [info coroutine]" + return [string toupper $value] +}} + +\fIcollect\fR rst +# ==> Received 'rst' at a yield in ::collect +\fIcollect\fR xyz + +puts [\fIcollect\fR] +# ==> 123 {abc def} 456 pqr RST xyz +.CE +.PP +This example shows a simple coroutine that collects non-empty values and +returns a list of them when not given an argument. It also shows how we can +look inside the coroutine to find out what it is doing. +.VE "8.7, TIP383" .SS "DETAILED SEMANTICS" .PP This example demonstrates that coroutines start from the global namespace, and @@ -17,11 +17,9 @@ dde \- Execute a Dynamic Data Exchange command .sp \fBdde servername\fR ?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR? .sp -.VS 8.6 \fBdde execute\fR ?\fB\-async\fR? ?\fB\-binary\fR? \fIservice topic data\fR .sp \fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR -.VE 8.6 .sp \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR .sp @@ -82,13 +80,11 @@ script is run in the application. The \fB\-async\fR option requests asynchronous invocation. The command returns an error message if the script did not run, unless the \fB\-async\fR flag was used, in which case the command returns immediately with no error. -.VS 8.6 Without the \fB\-binary\fR option all data will be sent in unicode. For dde clients which don't implement the CF_UNICODE clipboard format, this will automatically be translated to the system encoding. You can use the \fB\-binary\fR option in combination with the result of \fBencoding convertto\fR to send data in any other encoding. -.VE 8.6 .TP \fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR . @@ -99,13 +95,11 @@ specific but can be a command to the server or the name of a file to work on. The \fIitem\fR is also application specific and is often not used, but it must always be non-null. The \fIdata\fR field is given to the remote application. -.VS 8.6 Without the \fB\-binary\fR option all data will be sent in unicode. For dde clients which don't implement the CF_UNICODE clipboard format, this will automatically be translated to the system encoding. You can use the \fB\-binary\fR option in combination with the result of \fBencoding convertto\fR to send data in any other encoding. -.VE 8.6 .TP \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR . diff --git a/doc/define.n b/doc/define.n index ad991e1..9046203 100644 --- a/doc/define.n +++ b/doc/define.n @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 2007 Donal K. Fellows +'\" Copyright (c) 2007-2018 Donal K. Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -34,11 +34,36 @@ either the \fIdefScript\fR argument or by the \fIsubcommand\fR and following \fIarg\fR arguments; when the second is present, it is exactly as if all the arguments from \fIsubcommand\fR onwards are made into a list and that list is used as the \fIdefScript\fR argument. -.SS "CONFIGURING CLASSES" +.PP +Note that the constructor for \fBoo::class\fR will call \fBoo::define\fR on +the script argument that it is provided. This is a convenient way to create +and define a class in one step. +.SH "CONFIGURING CLASSES" .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: .TP +\fBclassmethod\fI name\fR ?\fIargList bodyScrip\fR? +.VS TIP478 +This creates a class method, or (if \fIargList\fR and \fIbodyScript\fR are +omitted) promotes an existing method on the class object to be a class +method. The \fIname\fR, \fIargList\fR and \fIbodyScript\fR arguments are as in +the \fBmethod\fR definition, below. +.RS +.PP +Class methods can be called on either the class itself or on the instances of +that class. When they are called, the current object (see the \fBsel\fR and +\fBmy\fR commands) is the class on which they are called or the class of the +instance on which they are called, depending on whether they are called on the +class or an instance of the class, respectively. If called on a subclass or +instance of the subclass, the current object is the subclass. +.PP +In a private definition context, the methods as invoked on classes are +\fInot\fR private, but the methods as invoked on instances of classes are +private. +.RE +.VE TIP478 +.TP \fBconstructor\fI argList bodyScript\fR . This creates or updates the constructor for a class. The formal arguments to @@ -49,14 +74,11 @@ namespace of the constructor will be a namespace that is unique to the object being constructed. Within the constructor, the \fBnext\fR command should be used to call the superclasses' constructors. If \fIbodyScript\fR is the empty string, the constructor will be deleted. -.TP -\fBdeletemethod\fI name\fR ?\fIname ...\fR? -. -This deletes each of the methods called \fIname\fR from a class. The methods -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. +.RS +.PP +Classes do not need to have a constructor defined. If none is specified, the +superclass's constructor will be used instead. +.RE .TP \fBdestructor\fI bodyScript\fR . @@ -82,19 +104,6 @@ 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. .TP -\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? -.VS -This slot (see \fBSLOTTED DEFINITIONS\fR below) -.VE -sets or updates the list of method names that are used to guard whether -method call to instances of the class may be called and what the method's -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. -.VS -By default, this slot works by appending. -.VE -.TP \fBforward\fI name cmdName \fR?\fIarg ...\fR? . This creates or updates a forwarded method called \fIname\fR. The method is @@ -106,8 +115,24 @@ fully-qualified, the command will be searched for in each object's namespace, using the instances' namespace's path, or by looking in the global namespace. The method will be exported if \fIname\fR starts with a lower-case letter, and non-exported otherwise. +.RS +.PP +.VS TIP500 +If in a private definition context (see the \fBprivate\fR definition command, +below), this command creates private forwarded methods. +.VE TIP500 +.RE +.TP +\fBinitialise\fI script\fR +.TP +\fBinitialize\fI script\fR +.VS TIP478 +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 .TP -\fBmethod\fI name argList bodyScript\fR +\fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR . This creates or updates a method that is implemented as a procedure-like script. The name of the method is \fIname\fR, the formal arguments to the @@ -117,33 +142,44 @@ the body of the method is evaluated, the current namespace of the method will be a namespace that is unique to the current object. The method will be exported if \fIname\fR starts with a lower-case letter, and non-exported otherwise; this behavior can be overridden via \fBexport\fR and -\fBunexport\fR. +\fBunexport\fR +.VS TIP519 +or by specifying \fB\-export\fR, \fB\-private\fR or \fB\-unexport\fR in the +optional parameter \fIoption\fR. +.VE TIP519 +.RS +.PP +.VS TIP500 +If in a private definition context (see the \fBprivate\fR definition command, +below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command +creates private procedure-like methods. +.VE TIP500 +.RE .TP -\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? -.VS -This slot (see \fBSLOTTED DEFINITIONS\fR below) -.VE -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. -.VS -By default, this slot works by replacement. -.VE +\fBprivate \fIcmd arg...\fR .TP -\fBrenamemethod\fI fromName toName\fR +\fBprivate \fIscript\fR . -This renames the method called \fIfromName\fR in a class to \fItoName\fR. The -method must have previously existed in the class, and \fItoName\fR must not -previously refer to a method 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. Does -not change the export status of the method; if it was exported before, it will -be afterwards. +.VS TIP500 +This evaluates the \fIscript\fR (or the list of command and arguments given by +\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the +current class will be private definitions. +.RS +.PP +The following class definition commands are affected by \fBprivate\fR: +\fBforward\fR, \fBmethod\fR, \fBself\fR, and \fBvariable\fR. Nesting +\fBprivate\fR inside \fBprivate\fR has no cumulative effect; the innermost +definition context is just a private definition context. All other definition +commands have no difference in behavior when used in a private definition +context. +.RE +.VE TIP500 .TP \fBself\fI subcommand arg ...\fR .TP \fBself\fI script\fR +.TP +\fBself\fR . This command is equivalent to calling \fBoo::objdefine\fR on the class being defined (see \fBCONFIGURING OBJECTS\fR below for a description of the @@ -153,20 +189,29 @@ and .QW "\fBoo::define \fIcls \fBself \fIsubcommand ...\fR" operates identically to .QW "\fBoo::objdefine \fIcls subcommand ...\fR" . +.RS +.PP +.VS TIP470 +If no arguments at all are used, this gives the name of the class currently +being configured. +.VE TIP470 +.VS TIP500 +If in a private definition context (see the \fBprivate\fR definition command, +below), the definitions on the class object will also be made in a private +definition context. +.VE TIP500 +.RE .TP \fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? -.VS +. This slot (see \fBSLOTTED DEFINITIONS\fR below) -.VE allows the alteration of the superclasses of the class being defined. Each \fIclassName\fR argument names one class that is to be a superclass of the defined class. Note that objects must not be changed from being classes to 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. -.VS By default, this slot works by replacement. -.VE .TP \fBunexport\fI name \fR?\fIname ...\fR? . @@ -178,37 +223,103 @@ actually defined by a superclass; subclass unexports override superclass visibility, and may be overridden by instance unexports. .TP \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR? -.VS +. This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named variables to be automatically made available in the methods, constructor and destructor declared by the class being defined. Each variable name must not have any namespace separators and must not look like an array access. All variables will be -actually present in the instance object on which the method is executed. Note +actually present in the namespace of the instance object on which the method +is executed. Note that the variable lists declared by a superclass or subclass are completely disjoint, as are variable lists declared by instances; the list of variable names is just for methods (and constructors and destructors) declared by this class. By default, this slot works by appending. -.VE -.SS "CONFIGURING OBJECTS" +.RS .PP -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: +.VS TIP500 +If in a private definition context (see the \fBprivate\fR definition command, +below), this slot manipulates the list of private variable bindings for this +class. In a private variable binding, the name of the variable within the +instance object is different to the name given in the definition; the name +used in the definition is the name that you use to access the variable within +the methods of this class, and the name of the variable in the instance +namespace has a unique prefix that makes accidental use from other classes +extremely unlikely. +.VE TIP500 +.RE +.SS "ADVANCED CLASS CONFIGURATION OPTIONS" +.PP +The following definitions are also supported, but are not required in simple +programs: .TP -\fBclass\fI className\fR +\fBdefinitionnamespace\fR ?\fIkind\fR? \fInamespaceName\fR +.VS TIP524 +This allows control over what namespace will be used by the \fBoo::define\fR +and \fBoo::objdefine\fR commands to look up the definition commands they +use. When any object has a definition operation applied to it, \fIthe class that +it is an instance of\fR (and its superclasses and mixins) is consulted for +what definition namespace to use. \fBoo::define\fR gets the class definition +namespace, and \fB::oo::objdefine\fR gets the instance definition namespace, +but both otherwise use the identical lookup operation. +.RS +.PP +This sets the definition namespace of kind \fIkind\fR provided by the current +class to \fInamespaceName\fR. The \fInamespaceName\fR must refer to a +currently existing namespace, or must be the empty string (to stop the current +class from having such a namespace connected). The \fIkind\fR, if supplied, +must be either \fB\-class\fR (the default) or \fB\-instance\fR to specify the +whether the namespace for use with \fBoo::define\fR or \fBoo::objdefine\fR +respectively is being set. +.PP +The class \fBoo::object\fR has its instance namespace locked to +\fB::oo::objdefine\fR, and the class \fBoo::class\fR has its class namespace +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 +.TP +\fBdeletemethod\fI name\fR ?\fIname ...\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. +This deletes each of the methods called \fIname\fR from a class. The methods +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. .TP -\fBdeletemethod\fI name\fR ?\fIname ...\fR +\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? . -This deletes each of the methods called \fIname\fR from an object. The methods -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. +This slot (see \fBSLOTTED DEFINITIONS\fR below) +sets or updates the list of method names that are used to guard whether +method call to instances of the class may be called and what the method's +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. +.TP +\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? +. +This slot (see \fBSLOTTED DEFINITIONS\fR below) +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. +.TP +\fBrenamemethod\fI fromName toName\fR +. +This renames the method called \fIfromName\fR in a class to \fItoName\fR. The +method must have previously existed in the class, and \fItoName\fR must not +previously refer to a method 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. Does +not change the export status of the method; if it was exported before, it will +be afterwards. +.SH "CONFIGURING OBJECTS" +.PP +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: .TP \fBexport\fI name \fR?\fIname ...\fR? . @@ -217,20 +328,6 @@ This arranges for each of the named methods, \fIname\fR, to be exported being defined. Note that the methods themselves may be actually defined by a class or superclass; object exports override class visibility. .TP -\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? -.VS -This slot (see \fBSLOTTED DEFINITIONS\fR below) -.VE -sets or updates the list of method names that are used to guard whether a -method call to the object may be called and what the method's 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. Note -that the actual list of filters also depends on the filters set upon any -classes that the object is an instance of. -.VS -By default, this slot works by appending. -.VE -.TP \fBforward\fI name cmdName \fR?\fIarg ...\fR? . This creates or updates a forwarded object method called \fIname\fR. The @@ -239,8 +336,15 @@ additional arguments, \fIarg\fR etc., added before those arguments specified by the caller of the method. Forwarded methods should be deleted using the \fBmethod\fR subcommand. The method will be exported if \fIname\fR starts with a lower-case letter, and non-exported otherwise. +.RS +.PP +.VS TIP500 +If in a private definition context (see the \fBprivate\fR definition command, +below), this command creates private forwarded methods. +.VE TIP500 +.RE .TP -\fBmethod\fI name argList bodyScript\fR +\fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR . This creates, updates or deletes an object method. The name of the method is \fIname\fR, the formal arguments to the method (defined using the same format @@ -248,28 +352,45 @@ as for the Tcl \fBproc\fR command) will be \fIargList\fR, and the body of the method will be \fIbodyScript\fR. When the body of the method is evaluated, the current namespace of the method will be a namespace that is unique to the object. The method will be exported if \fIname\fR starts with a lower-case -letter, and non-exported otherwise. +letter, and non-exported otherwise; +.VS TIP519 +this can be overridden by specifying \fB\-export\fR, \fB\-private\fR or +\fB\-unexport\fR in the optional parameter \fIoption\fR, or via the +\fBexport\fR and \fBunexport\fR definitions. +.VE TIP519 +.RS +.PP +.VS TIP500 +If in a private definition context (see the \fBprivate\fR definition command, +below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command +creates private procedure-like methods. +.VE TIP500 +.RE .TP \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? -.VS +. This slot (see \fBSLOTTED DEFINITIONS\fR below) -.VE 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. -.VS By default, this slot works by replacement. -.VE .TP -\fBrenamemethod\fI fromName toName\fR -. -This renames the method called \fIfromName\fR in an object to \fItoName\fR. -The method must have previously existed in the object, and \fItoName\fR must -not previously refer to a method in that object. Does not affect the classes -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. +\fBprivate \fIcmd arg...\fR +.TP +\fBprivate \fIscript\fR +.VS TIP500 +This evaluates the \fIscript\fR (or the list of command and arguments given by +\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the +current object will be private definitions. +.RS +.PP +The following class definition commands are affected by \fBprivate\fR: +\fBforward\fR, \fBmethod\fR, and \fBvariable\fR. Nesting \fBprivate\fR inside +\fBprivate\fR has no cumulative effect; the innermost definition context is +just a private definition context. All other definition commands have no +difference in behavior when used in a private definition context. +.RE +.VE TIP500 .TP \fBunexport\fI name \fR?\fIname ...\fR? . @@ -280,36 +401,114 @@ object being defined. Note that the methods themselves may be actually defined by a class; instance unexports override class visibility. .TP \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR? -.VS +. This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named variables to be automatically made available in the methods declared by the object being defined. Each variable name must not have any namespace separators and must not look like an array access. All variables will be -actually present in the object on which the method is executed. Note that the +actually present in the namespace of the object on which the method is +executed. Note that the variable lists declared by the classes and mixins of which the object is an instance are completely disjoint; the list of variable names is just for methods declared by this object. By default, this slot works by appending. +.RS +.PP +.VS TIP500 +If in a private definition context (see the \fBprivate\fR definition command, +below), this slot manipulates the list of private variable bindings for this +object. In a private variable binding, the name of the variable within the +instance object is different to the name given in the definition; the name +used in the definition is the name that you use to access the variable within +the methods of this instance object, and the name of the variable in the +instance namespace has a unique prefix that makes accidental use from +superclass methods extremely unlikely. +.VE TIP500 +.RE +.SS "ADVANCED OBJECT CONFIGURATION OPTIONS" +.PP +The following definitions are also supported, but are not required in simple +programs: +.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. +.TP +\fBdeletemethod\fI name\fR ?\fIname ...\fR +. +This deletes each of the methods called \fIname\fR from an object. The methods +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. +.TP +\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? +. +This slot (see \fBSLOTTED DEFINITIONS\fR below) +sets or updates the list of method names that are used to guard whether a +method call to the object may be called and what the method's 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. 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. +.TP +\fBrenamemethod\fI fromName toName\fR +. +This renames the method called \fIfromName\fR in an object to \fItoName\fR. +The method must have previously existed in the object, and \fItoName\fR must +not previously refer to a method in that object. Does not affect the classes +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. +.TP +\fBself \fR +.VS TIP470 +This gives the name of the object currently being configured. +.VE TIP470 +.SH "PRIVATE METHODS" +.VS TIP500 +When a class or instance has a private method, that private method can only be +invoked from within methods of that class or instance. Other callers of the +object's methods \fIcannot\fR invoke private methods, it is as if the private +methods do not exist. However, a private method of a class \fIcan\fR be +invoked from the class's methods when those methods are being used on another +instance object; this means that a class can use them to coordinate behaviour +between several instances of itself without interfering with how other +classes (especially either subclasses or superclasses) interact. Private +methods precede all mixed in classes in the method call order (as reported by +\fBself call\fR). +.VE TIP500 .SH "SLOTTED DEFINITIONS" Some of the configurable definitions of a class or object are \fIslotted definitions\fR. This means that the configuration is implemented by a slot 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. The class defines three operations (as methods) that may be done on +the slot. The class defines five operations (as methods) that may be done on the slot: -.VE .TP \fIslot\fR \fB\-append\fR ?\fImember ...\fR? -.VS +. This appends the given \fImember\fR elements to the slot definition. -.VE .TP \fIslot\fR \fB\-clear\fR -.VS +. This sets the slot definition to the empty list. -.VE +.TP +\fIslot\fR \fB\-prepend\fR ?\fImember ...\fR? +.VS TIP516 +This prepends the given \fImember\fR elements to the slot definition. +.VE TIP516 +.TP +\fIslot\fR \fB\-remove\fR ?\fImember ...\fR? +.VS TIP516 +This removes the given \fImember\fR elements from the slot definition. +.VE TIP516 .TP \fIslot\fR \fB\-set\fR ?\fImember ...\fR? -.VS +. This replaces the slot definition with the given \fImember\fR elements. .PP A consequence of this is that any use of a slot's default operation where the @@ -322,20 +521,55 @@ which is forwarded to the default operation of the slot (thus, for the class slot, this is forwarded to .QW "\fBmy \-append\fR" ), and these methods which provide the implementation interface: -.VE .TP \fIslot\fR \fBGet\fR -.VS -Returns a list that is the current contents of the slot. This method must -always be called from a stack frame created by a call to \fBoo::define\fR or -\fBoo::objdefine\fR. -.VE +. +Returns a list that is the current contents of the slot, but does not modify +the slot. This method must always be called from a stack frame created by a +call to \fBoo::define\fR or \fBoo::objdefine\fR. This method \fIshould not\fR +return an error unless it is called from outside a definition context or with +the wrong number of arguments. +.RS +.PP +.VS TIP516 +The elements of the list should be fully resolved, if that is a meaningful +concept to the slot. +.VE TIP516 +.RE +.TP +\fIslot\fR \fBResolve\fR \fIslotElement\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 +does nothing, whereas for slots of classes, this maps a class name to its +fully-qualified class name. This method must always be called from a stack +frame created by a call to \fBoo::define\fR or \fBoo::objdefine\fR. This +method \fIshould not\fR return an error unless it is called from outside a +definition context or with the wrong number of arguments; unresolvable +arguments should be returned as is (as not all slot operations strictly +require that values are resolvable to work). +.RS +.PP +Implementations \fIshould not\fR enforce uniqueness and ordering constraints +in this method; that is the responsibility of the \fBSet\fR method. +.RE +.VE TIP516 .TP \fIslot\fR \fBSet \fIelementList\fR -.VS +. Sets the contents of the slot to the list \fIelementList\fR and returns the empty string. This method must always be called from a stack frame created by -a call to \fBoo::define\fR or \fBoo::objdefine\fR. +a call to \fBoo::define\fR or \fBoo::objdefine\fR. This method may return an +error if it rejects the change to the slot contents (e.g., because of invalid +values) as well as if it is called from outside a definition context or with +the wrong number of arguments. +.RS +.PP +This method \fImay\fR reorder and filter the elements if this is necessary in +order to satisfy the underlying constraints of the slot. (For example, slots +of classes enforce a uniqueness constraint that places each element in the +earliest location in the slot that it can.) +.RE .PP The implementation of these methods is slot-dependent (and responsible for accessing the correct part of the class or object definition). Slots also have @@ -343,7 +577,14 @@ an unknown method handler to tie all these pieces together, and they hide their \fBdestroy\fR method so that it is not invoked inadvertently. It is \fIrecommended\fR that any user changes to the slot mechanism be restricted to defining new operations whose names start with a hyphen. -.VE +.PP +.VS TIP516 +Most slot operations will initially \fBResolve\fR their argument list, combine +it with the results of the \fBGet\fR method, and then \fBSet\fR the result. +Some operations omit one or both of the first two steps; omitting the third +would result in an idempotent read-only operation (but the standard mechanism +for reading from slots is via \fBinfo class\fR and \fBinfo object\fR). +.VE TIP516 .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 @@ -400,6 +641,138 @@ oo::class create B { inst m1 \fI\(-> prints "red brick"\fR inst m2 \fI\(-> prints "blue brick"\fR .CE +.PP +.VS TIP478 +This example shows how to create and use class variables. It is a class that +counts how many instances of itself have been made. +.PP +.CS +oo::class create Counted +\fBoo::define\fR Counted { + \fBinitialise\fR { + variable count 0 + } + + \fBvariable\fR number + \fBconstructor\fR {} { + classvariable count + set number [incr count] + } + + \fBmethod\fR report {} { + classvariable count + puts "This is instance $number of $count" + } +} + +set a [Counted new] +set b [Counted new] +$a report + \fI\(-> This is instance 1 of 2\fR +set c [Counted new] +$b report + \fI\(-> This is instance 2 of 3\fR +$c report + \fI\(-> This is instance 3 of 3\fR +.CE +.PP +This example demonstrates how to use class methods. (Note that the constructor +for \fBoo::class\fR calls \fBoo::define\fR on the class.) +.PP +.CS +oo::class create DBTable { + \fBclassmethod\fR find {description} { + puts "DB: locate row from [self] matching $description" + return [my new] + } + \fBclassmethod\fR insert {description} { + puts "DB: create row in [self] matching $description" + return [my new] + } + \fBmethod\fR update {description} { + puts "DB: update row [self] with $description" + } + \fBmethod\fR delete {} { + puts "DB: delete row [self]" + my destroy; # Just delete the object, not the DB row + } +} + +oo::class create Users { + \fBsuperclass\fR DBTable +} +oo::class create Groups { + \fBsuperclass\fR DBTable +} + +set u1 [Users insert "username=abc"] + \fI\(-> DB: create row from ::Users matching username=abc\fR +set u2 [Users insert "username=def"] + \fI\(-> DB: create row from ::Users matching username=def\fR +$u2 update "group=NULL" + \fI\(-> DB: update row ::oo::Obj124 with group=NULL\fR +$u1 delete + \fI\(-> DB: delete row ::oo::Obj123\fR +set g [Group find "groupname=webadmins"] + \fI\(-> DB: locate row ::Group with groupname=webadmins\fR +$g update "emailaddress=admins" + \fI\(-> DB: update row ::oo::Obj125 with emailaddress=admins\fR +.CE +.VE TIP478 +.PP +.VS TIP524 +This example shows how to make a custom definition for a class. Note that it +explicitly includes delegation to the existing definition commands via +\fBnamespace path\fR. +.PP +.CS +namespace eval myDefinitions { + # Delegate to existing definitions where not overridden + namespace path \fB::oo::define\fR + + # A custom type of method + proc exprmethod {name arguments body} { + tailcall \fBmethod\fR $name $arguments [list expr $body] + } + + # A custom way of building a constructor + proc parameters args { + uplevel 1 [list \fBvariable\fR {*}$args] + set body [join [lmap a $args { + string map [list VAR $a] { + set [my varname VAR] [expr {double($VAR)}] + } + }] ";"] + tailcall \fBconstructor\fR $args $body + } +} + +# Bind the namespace into a (very simple) metaclass for use +oo::class create exprclass { + \fBsuperclass\fR oo::class + \fBdefinitionnamespace\fR myDefinitions +} + +# Use the custom definitions +exprclass create quadratic { + parameters a b c + exprmethod evaluate {x} { + ($a * $x**2) + ($b * $x) + $c + } +} + +# Showing the resulting class and object in action +quadratic create quad 1 2 3 +for {set x 0} {$x <= 4} {incr x} { + puts [format "quad(%d) = %.2f" $x [quad evaluate $x]] +} + \fI\(-> quad(0) = 3.00\fR + \fI\(-> quad(1) = 6.00\fR + \fI\(-> quad(2) = 11.00\fR + \fI\(-> quad(3) = 18.00\fR + \fI\(-> quad(4) = 27.00\fR +.CE +.VE TIP524 .SH "SEE ALSO" next(n), oo::class(n), oo::object(n) .SH KEYWORDS @@ -27,6 +27,11 @@ key maps to in the dictionary value contained in the given variable, writing the resulting dictionary value back to that variable. Non-existent keys are treated as if they map to an empty string. The updated dictionary value is returned. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the appending operation. +.VE TIP508 .TP \fBdict create \fR?\fIkey value ...\fR? . @@ -49,10 +54,8 @@ type (which may be abbreviated.) Supported filter types are: .RS .TP \fBdict filter \fIdictionaryValue \fBkey\fR ?\fIglobPattern ...\fR? -.VS 8.6 The key rule only matches those key/value pairs whose keys match any of the given patterns (in the style of \fBstring match\fR.) -.VE 8.6 .TP \fBdict filter \fIdictionaryValue \fBscript {\fIkeyVariable valueVariable\fB} \fIscript\fR . @@ -69,10 +72,8 @@ result. The key/value pairs are tested in the order in which the keys were inserted into the dictionary. .TP \fBdict filter \fIdictionaryValue \fBvalue \fR?\fIglobPattern ...\fR? -.VS 8.6 The value rule only matches those key/value pairs whose values match any of the given patterns (in the style of \fBstring match\fR.) -.VE 8.6 .RE .TP \fBdict for {\fIkeyVariable valueVariable\fB} \fIdictionaryValue body\fR @@ -115,6 +116,22 @@ It is an error to attempt to retrieve a value for a key that is not present in the dictionary. .RE .TP +\fBdict getdef \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR +.TP +\fBdict getwithdefault \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR +.VS "8.7, TIP342" +This behaves the same as \fBdict get\fR (with at least one \fIkey\fR +argument), returning the value that the key path maps to in the +dictionary \fIdictionaryValue\fR, except that instead of producing an +error because the \fIkey\fR (or one of the \fIkey\fRs on the key path) +is absent, it returns the \fIdefault\fR argument instead. +.RS +.PP +Note that there must always be at least one \fIkey\fR provided, and that +\fBdict getdef\fR and \fBdict getwithdefault\fR are aliases for each other. +.RE +.VE "8.7, TIP342" +.TP \fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR? . This adds the given increment value (an integer that defaults to 1 if @@ -124,6 +141,11 @@ resulting dictionary value back to that variable. Non-existent keys are treated as if they map to 0. It is an error to increment a value for an existing key if that value is not an integer. The updated dictionary value is returned. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the incrementing operation. +.VE TIP508 .TP \fBdict info \fIdictionaryValue\fR . @@ -149,6 +171,11 @@ keys are treated as if they map to an empty list, and it is legal for there to be no items to append to the list. It is an error for the value that the key maps to to not be representable as a list. The updated dictionary value is returned. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the list-appending operation. +.VE TIP508 .TP \fBdict map \fR{\fIkeyVariable valueVariable\fR} \fIdictionaryValue body\fR . @@ -206,6 +233,11 @@ value and places an updated dictionary value in that variable containing a mapping from the given key to the given value. When multiple keys are present, this operation creates or updates a chain of nested dictionaries. The updated dictionary value is returned. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the value insert/update operation. +.VE TIP508 .TP \fBdict size \fIdictionaryValue\fR . @@ -221,6 +253,11 @@ through nested dictionaries to the mapping to remove. At least one key must be specified, but the last key on the key-path need not exist. All other components on the path must exist. The updated dictionary value is returned. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the value remove operation. +.VE TIP508 .TP \fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR . @@ -236,6 +273,11 @@ are silently discarded), even if the result of \fIbody\fR is an error or some other kind of exceptional exit. The result of \fBdict update\fR is (unless some kind of error occurs) the result of the evaluation of \fIbody\fR. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the update operation. +.VE TIP508 .RS .PP Each \fIvarName\fR is mapped in the scope enclosing the \fBdict update\fR; @@ -270,6 +312,11 @@ dictionary be discarded, and this also happens if the contents of dictionaries no longer exists. The result of \fBdict with\fR is (unless some kind of error occurs) the result of the evaluation of \fIbody\fR. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the updating operation. +.VE TIP508 .RS .PP The variables are mapped in the scope enclosing the \fBdict with\fR; @@ -59,3 +59,7 @@ while {1} { file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3) .SH KEYWORDS channel, end of file +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: @@ -338,7 +338,6 @@ if {[catch {\fBexec\fR grep foo bar.txt} results options]} { } } .CE -.VS 8.6 .PP This is more easily written using the \fBtry\fR command, as that makes it simpler to trap specific types of errors. This is @@ -352,7 +351,6 @@ try { set status [lindex [dict get $options -errorcode] 2] } .CE -.VE 8.6 .SS "WORKING WITH QUOTED ARGUMENTS" .PP When translating a command from a Unix shell invocation, care should @@ -49,3 +49,7 @@ if {[catch {main} msg options]} { exec(n) .SH KEYWORDS abort, exit, process +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: @@ -17,14 +17,14 @@ expr \- Evaluate an expression .BE .SH DESCRIPTION .PP -Concatenates \fIarg\fRs (adding separator spaces between them), -evaluates the result as a Tcl expression, and returns the value. -The operators permitted in Tcl expressions include a subset of +The \fIexpr\fR command concatenates \fIarg\fRs, separated by a space, into an expression, and evaluates +that expression, returning its value. +The operators permitted in an expression include a subset of the operators permitted in C expressions. For those operators common to both Tcl and C, Tcl applies the same meaning and precedence as the corresponding C operators. -Expressions almost always yield numeric results -(integer or floating-point values). +The value of an expression is often a numeric result, either an integer or a +floating-point value, but may also be a non-numeric value. For example, the expression .PP .CS @@ -32,78 +32,53 @@ For example, the expression .CE .PP evaluates to 14.2. -Tcl expressions differ from C expressions in the way that -operands are specified. Also, Tcl expressions support -non-numeric operands and string comparisons, as well as some +Expressions differ from C expressions in the way that +operands are specified. Expressions also support +non-numeric operands, string comparisons, and some additional operators not found in C. +.PP +When an expression evaluates to an integer, the value is the decimal form of +the integer, and when an expression evaluates to a floating-point number, the +value is the form produced by the \fB%g\fR format specifier of Tcl's +\fBformat\fR command. .SS OPERANDS .PP -A Tcl expression consists of a combination of operands, operators, -parentheses and commas. -White space may be used between the operands and operators and -parentheses (or commas); it is ignored by the expression's instructions. -Where possible, operands are interpreted as integer values. -Integer values may be specified in decimal (the normal case), in binary -(if the first two characters of the operand are \fB0b\fR), in octal -(if the first two characters of the operand are \fB0o\fR), or in hexadecimal -(if the first two characters of the operand are \fB0x\fR). For -compatibility with older Tcl releases, an octal integer value is also -indicated simply when the first character of the operand is \fB0\fR, -whether or not the second character is also \fBo\fR. -If an operand does not have one of the integer formats given -above, then it is treated as a floating-point number if that is -possible. Floating-point numbers may be specified in any of several -common formats making use of the decimal digits, the decimal point \fB.\fR, -the characters \fBe\fR or \fBE\fR indicating scientific notation, and -the sign characters \fB+\fR or \fB\-\fR. For example, all of the -following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. -Also recognized as floating point values are the strings \fBInf\fR -and \fBNaN\fR making use of any case for each character. -If no numeric interpretation is possible (note that all literal -operands that are not numeric or boolean must be quoted with either -braces or with double quotes), then an operand is left as a string -(and only a limited set of operators may be applied to it). -.PP -Operands may be specified in any of the following ways: +An expression consists of a combination of operands, operators, parentheses and +commas, possibly with whitespace between any of these elements, which is +ignored. +.PP +An operand may be specified in any of the following ways: .IP [1] As a numeric value, either integer or floating-point. .IP [2] As a boolean value, using any form understood by \fBstring is\fR \fBboolean\fR. .IP [3] -As a Tcl variable, using standard \fB$\fR notation. -The variable's value will be used as the operand. +As a variable, using standard \fB$\fR notation. +The value of the variable is then the value of the operand. .IP [4] As a string enclosed in double-quotes. -The expression parser will perform backslash, variable, and -command substitutions on the information between the quotes, -and use the resulting value as the operand +Backslash, variable, and command substitution are performed as described in +\fBTcl\fR. .IP [5] As a string enclosed in braces. -The characters between the open brace and matching close brace -will be used as the operand without any substitutions. +The operand is treated as a braced value as described in \fBTcl\fR. .IP [6] As a Tcl command enclosed in brackets. -The command will be executed and its result will be used as -the operand. +Command substitution is performed as described in \fBTcl\fR. .IP [7] -As a mathematical function whose arguments have any of the above -forms for operands, such as \fBsin($x)\fR. See \fBMATH FUNCTIONS\fR below for +As 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 discussion of how mathematical functions are handled. .PP -Where the above substitutions occur (e.g. inside quoted strings), they -are performed by the expression's instructions. -However, the command parser may already have performed one round of -substitution before the expression processor was called. -As discussed below, it is usually best to enclose expressions -in braces to prevent the command parser from performing substitutions -on the contents. +Because \fBexpr\fR parses and performs substitutions on values that have +already been parsed and substituted by \fBTcl\fR, it is usually best to enclose +expressions in braces to avoid the first round of substitutions by +\fBTcl\fR. .PP -For some examples of simple expressions, suppose the variable -\fBa\fR has the value 3 and -the variable \fBb\fR has the value 6. -Then the command on the left side of each of the lines below -will produce the value on the right side of the line: +Below are some examples of simple expressions where the value of \fBa\fR is 3 +and the value of \fBb\fR is 6. The command on the left side of each line +produces the value on the right side. .PP .CS .ta 9c @@ -112,37 +87,87 @@ will produce the value on the right side of the line: \fBexpr\fR 4*[llength "6 2"] \fI8\fR \fBexpr\fR {{word one} < "word $a"} \fI0\fR .CE +.PP +\fBInteger value\fR +.PP +An integer operand may be specified in decimal (the normal case, the optional +first two characters are \fB0d\fR), binary +(the first two characters are \fB0b\fR), octal +(the first two characters are \fB0o\fR), or hexadecimal +(the first two characters are \fB0x\fR) form. For +compatibility with older Tcl releases, an operand that begins with \fB0\fR is +interpreted as an octal integer even if the second character is not \fBo\fR. +.PP +\fBFloating-point value\fR +.PP +A floating-point number may be specified in any of several +common decimal formats, and may use the decimal point \fB.\fR, +\fBe\fR or \fBE\fR for scientific notation, and +the sign characters \fB+\fR and \fB\-\fR. The +following are all valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. +The strings \fBInf\fR +and \fBNaN\fR, in any combination of case, are also recognized as floating point +values. An operand that doesn't have a numeric interpretation must be quoted +with either braces or with double quotes. +.PP +\fBBoolean value\fR +.PP +A boolean value may be represented by any of the values \fB0\fR, \fBfalse\fR, \fBno\fR, +or \fBoff\fR and any of the values \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR. +.PP +\fBDigit Separator\fR +.PP +Digits in any numeric value may be separated with one or more underscore +characters, "\fB_\fR", to improve readability. These separators may only +appear between digits. The separator may not appear at the start of a +numeric value, between the leading 0 and radix specifier, or at the +end of a numeric value. Here are some examples: +.PP +.CS +.ta 9c +\fBexpr\fR 100_000_000 \fI100000000\fR +\fBexpr\fR 0xffff_ffff \fI4294967295\fR +\fBformat\fR 0x%x 0b1111_1110_1101_1011 \fI0xfedb\fR +.CE +.PP .SS OPERATORS .PP -The valid operators (most of which are also available as commands in -the \fBtcl::mathop\fR namespace; see the \fBmathop\fR(n) manual page -for details) are listed below, grouped in decreasing order of precedence: +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 +more versatile operators such as \fB==\fR. +.PP +Unless otherwise specified, operators accept non-numeric operands. The value +of a boolean operation is 1 if true, 0 otherwise. See also \fBstring is\fR +\fBboolean\fR. The valid operators, most of which are also available as +commands in the \fBtcl::mathop\fR namespace (see \fBmathop\fR(n)), are listed +below, grouped in decreasing order of precedence: .TP 20 \fB\-\0\0+\0\0~\0\0!\fR . -Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operators -may be applied to string operands, and bit-wise NOT may be -applied only to integers. +Unary minus, unary plus, bit-wise NOT, logical NOT. These operators +may only be applied to numeric operands, and bit-wise NOT may only be +applied to integers. .TP 20 \fB**\fR . -Exponentiation. Valid for any numeric operands. The maximum exponent value +Exponentiation. Valid for numeric operands. The maximum exponent value that Tcl can handle if the first number is an integer > 1 is 268435455. .TP 20 \fB*\0\0/\0\0%\fR . -Multiply, divide, remainder. None of these operators may be -applied to string operands, and remainder may be applied only -to integers. -The remainder will always have the same sign as the divisor and -an absolute value smaller than the absolute value of the divisor. +Multiply and divide, which are valid for numeric operands, and remainder, which +is valid for integers. The remainder, an absolute value smaller than the +absolute value of the divisor, has the same sign as the divisor. .RS .PP -When applied to integers, the division and remainder operators can be -considered to partition the number line into a sequence of equal-sized -adjacent non-overlapping pieces where each piece is the size of the divisor; -the division result identifies which piece the divisor lay within, and the -remainder result identifies where within that piece the divisor lay. A +When applied to integers, division and remainder can be +considered to partition the number line into a sequence of +adjacent non-overlapping pieces, where each piece is the size of the divisor; +the quotient identifies which piece the dividend lies within, and the +remainder identifies where within that piece the dividend lies. A consequence of this is that the result of .QW "-57 \fB/\fR 10" is always -6, and the result of @@ -152,183 +177,175 @@ is always 3. .TP 20 \fB+\0\0\-\fR . -Add and subtract. Valid for any numeric operands. +Add and subtract. Valid for numeric operands. .TP 20 \fB<<\0\0>>\fR . -Left and right shift. Valid for integer operands only. +Left and right shift. Valid for integers. A right shift always propagates the sign bit. .TP 20 \fB<\0\0>\0\0<=\0\0>=\fR . -Boolean less, greater, less than or equal, and greater than or equal. -Each operator produces 1 if the condition is true, 0 otherwise. -These operators may be applied to strings as well as numeric operands, -in which case string comparison is used. +Boolean numeric-preferring comparisons: less than, greater than, less than or +equal, and greater than or equal. If either argument is not numeric, the +comparison is done using UNICODE string comparison, as with the string +comparison operators below, which have the same precedence. +.TP 20 +\fBlt\0\0gt\0\0le\0\0ge\fR +.VS "8.7, TIP461" +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. +.VE "8.7, TIP461" .TP 20 \fB==\0\0!=\fR . -Boolean equal and not equal. Each operator produces a zero/one result. -Valid for all operand types. +Boolean equal and not equal. .TP 20 \fBeq\0\0ne\fR . -Boolean string equal and string not equal. Each operator produces a -zero/one result. The operand types are interpreted only as strings. +Boolean string equal and string not equal. .TP 20 \fBin\0\0ni\fR . -List containment and negated list containment. Each operator produces -a zero/one result and treats its first argument as a string and its -second argument as a Tcl list. The \fBin\fR operator indicates -whether the first argument is a member of the second argument list; -the \fBni\fR operator inverts the sense of the result. +List containment and negated list containment. The first argument is +interpreted as a string, the second as a list. \fBin\fR tests for membership +in the list, and \fBni\fR is the inverse. .TP 20 \fB&\fR . -Bit-wise AND. Valid for integer operands only. +Bit-wise AND. Valid for integer operands. .TP 20 \fB^\fR . -Bit-wise exclusive OR. Valid for integer operands only. +Bit-wise exclusive OR. Valid for integer operands. .TP 20 \fB|\fR . -Bit-wise OR. Valid for integer operands only. +Bit-wise OR. Valid for integer operands. .TP 20 \fB&&\fR . -Logical AND. Produces a 1 result if both operands are non-zero, -0 otherwise. -Valid for boolean and numeric (integers or floating-point) operands only. +Logical AND. If both operands are true, the result is 1, or 0 otherwise. +This operator evaluates lazily; it only evaluates its second operand if it +must in order to determine its result. This operator evaluates lazily; it only evaluates its second operand if it must in order to determine its result. .TP 20 \fB||\fR . -Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. -Valid for boolean and numeric (integers or floating-point) operands only. +Logical OR. If both operands are false, the result is 0, or 1 otherwise. This operator evaluates lazily; it only evaluates its second operand if it must in order to determine its result. .TP 20 \fIx \fB?\fI y \fB:\fI z\fR . -If-then-else, as in C. If \fIx\fR -evaluates to non-zero, then the result is the value of \fIy\fR. -Otherwise the result is the value of \fIz\fR. -The \fIx\fR operand must have a boolean or numeric value. +If-then-else, as in C. If \fIx\fR is false , the result is the value of +\fIy\fR. Otherwise the result is the value of \fIz\fR. This operator evaluates lazily; it evaluates only one of \fIy\fR or \fIz\fR. .PP -See the C manual for more details on the results -produced by each operator. -The exponentiation operator promotes types like the multiply and -divide operators, and produces a result that is the same as the output -of the \fBpow\fR function (after any type conversions.) -All of the binary operators but exponentiation group left-to-right -within the same precedence level; exponentiation groups right-to-left. For example, the command +The exponentiation operator promotes types in the same way that the multiply +and divide operators do, and the result is is the same as the result of +\fBpow\fR. +Exponentiation groups right-to-left within a precedence level. Other binary +operators group left-to-right. For example, the value of .PP .PP .CS \fBexpr\fR {4*2 < 7} .CE .PP -returns 0, while +is 0, while the value of .PP .CS \fBexpr\fR {2**3**2} .CE .PP -returns 512. +is 512. .PP -The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have +As in C, \fB&&\fR, \fB||\fR, and \fB?:\fR feature .QW "lazy evaluation" , -just as in C, which means that operands are not evaluated if they are -not needed to determine the outcome. For example, in the command +which means that operands are not evaluated if they are +not needed to determine the outcome. For example, in .PP .CS \fBexpr\fR {$v ? [a] : [b]} .CE .PP -only one of -.QW \fB[a]\fR -or -.QW \fB[b]\fR -will actually be evaluated, -depending on the value of \fB$v\fR. Note, however, that this is -only true if the entire expression is enclosed in braces; otherwise -the Tcl parser will evaluate both -.QW \fB[a]\fR -and -.QW \fB[b]\fR -before invoking the \fBexpr\fR command. +only one of \fB[a]\fR or \fB[b]\fR is evaluated, +depending on the value of \fB$v\fR. This is not true of the normal Tcl parser, +so it is normally recommended to enclose the arguments to \fBexpr\fR in braces. +Without braces, as in +\fBexpr\fR $v ? [a] : [b] +both \fB[a]\fR and \fB[b]\fR are evaluated before \fBexpr\fR is even called. +.PP +For more details on the results +produced by each operator, see the documentation for C. .SS "MATH FUNCTIONS" .PP -When the expression parser encounters a mathematical function -such as \fBsin($x)\fR, it replaces it with a call to an ordinary -Tcl command in the \fBtcl::mathfunc\fR namespace. The processing -of an expression such as: +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 \fBexpr\fR {sin($x+$y)} .CE .PP -is the same in every way as the processing of: +is the same in every way as the evaluation of .PP .CS \fBexpr\fR {[tcl::mathfunc::sin [\fBexpr\fR {$x+$y}]]} .CE .PP -which in turn is the same as the processing of: +which in turn is the same as the evaluation of .PP .CS tcl::mathfunc::sin [\fBexpr\fR {$x+$y}] .CE .PP -The executor will search for \fBtcl::mathfunc::sin\fR using the usual -rules for resolving functions in namespaces. Either -\fB::tcl::mathfunc::sin\fR or \fB[namespace -current]::tcl::mathfunc::sin\fR will satisfy the request, and others -may as well (depending on the current \fBnamespace path\fR setting). +\fBtcl::mathfunc::sin\fR is resolved as described in +\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 -Some mathematical functions have several arguments, separated by commas like in C. Thus: +As in C, a mathematical function may accept multiple arguments separated by commas. Thus, .PP .CS \fBexpr\fR {hypot($x,$y)} .CE .PP -ends up as +becomes .PP .CS tcl::mathfunc::hypot $x $y .CE .PP -See the \fBmathfunc\fR(n) manual page for the math functions that are +See the \fBmathfunc\fR(n) documentation for the math functions that are available by default. .SS "TYPES, OVERFLOW, AND PRECISION" .PP -All internal computations involving integers are done calling on the -LibTomMath multiple precision integer library as required so that all -integer calculations are performed exactly. Note that in Tcl releases -prior to 8.5, integer calculations were performed with one of the C types +When needed to guarantee exact performance, internal computations involving +integers use the LibTomMath multiple precision integer library. In Tcl releases +prior to 8.5, integer calculations were performed using one of the C types \fIlong int\fR or \fITcl_WideInt\fR, causing implicit range truncation in those calculations where values overflowed the range of those types. -Any code that relied on these implicit truncations will need to explicitly -add \fBint()\fR or \fBwide()\fR function calls to expressions at the points -where such truncation is required to take place. +Any code that relied on these implicit truncations should instead call +\fBint()\fR or \fBwide()\fR, which do truncate. .PP -All internal computations involving floating-point are -done with the C type \fIdouble\fR. -When converting a string to floating-point, exponent overflow is +Internal floating-point computations are +performed using the \fIdouble\fR C type. +When converting a string to floating-point value, exponent overflow is detected and results in the \fIdouble\fR value of \fBInf\fR or \fB\-Inf\fR as appropriate. Floating-point overflow and underflow are detected to the degree supported by the hardware, which is generally -pretty reliable. +fairly reliable. .PP -Conversion among internal representations for integer, floating-point, -and string operands is done automatically as needed. -For arithmetic computations, integers are used until some -floating-point number is introduced, after which floating-point is used. -For example, +Conversion among internal representations for integer, floating-point, and +string operands is done automatically as needed. For arithmetic computations, +integers are used until some floating-point number is introduced, after which +floating-point values are used. For example, .PP .CS \fBexpr\fR {5 / 4} @@ -342,53 +359,35 @@ returns 1, while .CE .PP both return 1.25. -Floating-point values are always returned with a +A floating-point result can be distinguished from an integer result by the +presence of either .QW \fB.\fR -or an +or .QW \fBe\fR -so that they will not look like integer values. For example, +.PP +. For example, .PP .CS \fBexpr\fR {20.0/5.0} .CE .PP returns \fB4.0\fR, not \fB4\fR. -.SS "STRING OPERATIONS" -.PP -String values may be used as operands of the comparison operators, -although the expression evaluator tries to do comparisons as integer -or floating-point when it can, -i.e., when all arguments to the operator allow numeric interpretations, -except in the case of the \fBeq\fR and \fBne\fR operators. -If one of the operands of a comparison is a string and the other -has a numeric value, a canonical string representation of the numeric -operand value is generated to compare with the string operand. -Canonical string representation for integer values is a decimal string -format. Canonical string representation for floating-point values -is that produced by the \fB%g\fR format specifier of Tcl's -\fBformat\fR command. For example, the commands -.PP -.CS -\fBexpr\fR {"0x03" > "2"} -\fBexpr\fR {"0y" > "0x12"} -.CE -.PP -both return 1. The first comparison is done using integer -comparison, and the second is done using string comparison. -Because of Tcl's tendency to treat values as numbers whenever -possible, it is not generally a good idea to use operators like \fB==\fR -when you really want string comparison and the values of the -operands could be arbitrary; it is better in these cases to use -the \fBeq\fR or \fBne\fR operators, or the \fBstring\fR command instead. .SH "PERFORMANCE CONSIDERATIONS" .PP -Enclose expressions in braces for the best speed and the smallest -storage requirements. -This allows the Tcl bytecode compiler to generate the best code. -.PP -As mentioned above, expressions are substituted twice: -once by the Tcl parser and once by the \fBexpr\fR command. -For example, the commands +Where an expression contains syntax that Tcl would otherwise perform +substitutions on, enclosing an expression in braces or otherwise quoting it +so that it's a static value allows the Tcl compiler to generate bytecode for +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 +.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. .PP .CS set a 3 @@ -396,25 +395,18 @@ set b {$a + 2} \fBexpr\fR $b*4 .CE .PP -return 11, not a multiple of 4. -This is because the Tcl parser will first substitute -.QW "\fB$a + 2\fR" -for the variable \fBb\fR, -then the \fBexpr\fR command will evaluate the expression -.QW "\fB$a + 2*4\fR" . -.PP -Most expressions do not require a second round of substitutions. -Either they are enclosed in braces or, if not, -their variable and command substitutions yield numbers or strings -that do not themselves require substitutions. -However, because a few unbraced expressions -need two rounds of substitutions, -the bytecode compiler must emit -additional instructions to handle this situation. -The most expensive code is required for -unbraced expressions that contain command substitutions. -These expressions must be implemented by generating new code -each time the expression is executed. +When an expression is generated at runtime, like the one above is, the bytecode +compiler must ensure that new code is generated each time the expression +is evaluated. This is the most costly kind of expression from a performance +perspective. In such cases, consider directly using the commands described in +the \fBmathfunc\fR(n) or \fBmathop\fR(n) documentation instead of \fBexpr\fR. +.PP +Most expressions are not formed at runtime, but are literal strings or contain +substitutions that don't introduce other substitutions. To allow the bytecode +compiler to work with an expression as a string literal at compilation time, +ensure that it contains no substitutions or that it is enclosed in braces or +otherwise quoted to prevent Tcl from performing substitutions, allowing +\fBexpr\fR to perform them instead. .PP If it is necessary to include a non-constant expression string within the wider context of an otherwise-constant expression, the most efficient @@ -430,11 +422,33 @@ set b {$a + 2} \fBexpr\fR {[\fBexpr\fR $b] * 4} .CE .PP -When the expression is unbraced to allow the substitution of a function or -operator, consider using the commands documented in the \fBmathfunc\fR(n) or -\fBmathop\fR(n) manual pages directly instead. +In general, you should enclose your expression in braces wherever possible, +and where not possible, the argument to \fBexpr\fR should be an expression +defined elsewhere as simply as possible. It is usually more efficient and +safer to use other techniques (e.g., the commands in the \fBtcl::mathop\fR +namespace) than it is to do complex expression generation. .SH EXAMPLES .PP +A numeric comparison whose result is 1: +.PP +.CS +\fBexpr\fR {"0x03" > "2"} +.CE +.PP +A string comparison whose result is 1: +.PP +.CS +\fBexpr\fR {"0y" > "0x12"} +.CE +.PP +.VS "8.7, TIP461" +A forced string comparison whose result is 0: +.PP +.CS +\fBexpr\fR {"0x03" gt "2"} +.CE +.VE "8.7, TIP461" +.PP Define a procedure that computes an .QW interesting mathematical function: @@ -468,8 +482,8 @@ each other: puts "a and b are [\fBexpr\fR {$a eq $b ? {equal} : {different}}]" .CE .PP -Set a variable to whether an environment variable is both defined at -all and also set to a true boolean value: +Set a variable indicating whether an environment variable is defined and has +value of true: .PP .CS set isTrue [\fBexpr\fR { @@ -487,12 +501,12 @@ set randNum [\fBexpr\fR { int(100 * rand()) }] array(n), for(n), if(n), mathfunc(n), mathop(n), namespace(n), proc(n), string(n), Tcl(n), while(n) .SH KEYWORDS -arithmetic, boolean, compare, expression, fuzzy comparison +arithmetic, boolean, compare, expression, fuzzy comparison, integer value .SH COPYRIGHT .nf -Copyright (c) 1993 The Regents of the University of California. -Copyright (c) 1994-2000 Sun Microsystems Incorporated. -Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. +Copyright \(co 1993 The Regents of the University of California. +Copyright \(co 1994-2000 Sun Microsystems Incorporated. +Copyright \(co 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. .fi '\" Local Variables: '\" mode: nroff diff --git a/doc/fblocked.n b/doc/fblocked.n index 93cfe87..0a28dcf 100644 --- a/doc/fblocked.n +++ b/doc/fblocked.n @@ -65,3 +65,7 @@ vwait forever gets(n), open(n), read(n), socket(n), Tcl_StandardChannels(3) .SH KEYWORDS blocking, nonblocking +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: @@ -390,7 +390,7 @@ that use the third component do not attempt to perform tilde substitution. .RE .TP -\fBfile stat \fIname varName\fR +\fBfile stat \fIname varName\fR . Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the variable given by \fIvarName\fR to hold information returned from the kernel call. @@ -433,9 +433,38 @@ If \fIname\fR contains no separators then returns \fIname\fR. So, \fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all return \fBb\fR. .TP +\fBfile tempdir\fR ?\fItemplate\fR? +.VS "8.7, TIP 431" +Creates a temporary directory (guaranteed to be newly created and writable by +the current script) and returns its name. If \fItemplate\fR is given, it +specifies one of or both of the existing directory (on a filesystem controlled +by the operating system) to contain the temporary directory, and the base part +of the directory name; it is considered to have the location of the directory +if there is a directory separator in the name, and the base part is everything +after the last directory separator (if non-empty). The default containing +directory is determined by system-specific operations, and the default base +name prefix is +.QW \fBtcl\fR . +.RS +.PP +The following output is typical and illustrative; the actual output will vary +between platforms: +.PP +.CS +% \fBfile tempdir\fR +/var/tmp/tcl_u0kuy5 + % \fBfile tempdir\fR /tmp/myapp +/tmp/myapp_8o7r9L +% \fBfile tempdir\fR /tmp/ +/tmp/tcl_1mOJHD +% \fBfile tempdir\fR myapp +/var/tmp/myapp_0ihS0n +.CE +.RE +.VE "8.7, TIP 431" +.TP \fBfile tempfile\fR ?\fInameVar\fR? ?\fItemplate\fR? '\" TIP #210 -.VS 8.6 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 @@ -450,7 +479,6 @@ Note that temporary files are \fIonly\fR ever created on the native filesystem. As such, they can be relied upon to be used with operating-system native APIs and external programs that require a filename. .RE -.VE 8.6 .TP \fBfile type \fIname\fR . diff --git a/doc/fileevent.n b/doc/fileevent.n index 2751040..bbba997 100644 --- a/doc/fileevent.n +++ b/doc/fileevent.n @@ -154,3 +154,7 @@ fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3) .SH KEYWORDS asynchronous I/O, blocking, channel, event handler, nonblocking, readable, script, writable. +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/filename.n b/doc/filename.n index 87ba467..f160eff 100644 --- a/doc/filename.n +++ b/doc/filename.n @@ -176,3 +176,7 @@ file(n), glob(n) .SH KEYWORDS current directory, absolute file name, relative file name, volume-relative file name, portability +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/flush.n b/doc/flush.n index 6b98ab7..1d84383 100644 --- a/doc/flush.n +++ b/doc/flush.n @@ -43,3 +43,7 @@ puts "Hello there, $name!" file(n), open(n), socket(n), Tcl_StandardChannels(3) .SH KEYWORDS blocking, buffer, channel, flush, nonblocking, output +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/foreach.n b/doc/foreach.n index 925ec1f..43f961a 100644 --- a/doc/foreach.n +++ b/doc/foreach.n @@ -102,3 +102,7 @@ for(n), while(n), break(n), continue(n) .SH KEYWORDS foreach, iteration, list, loop +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/format.n b/doc/format.n index 1c511e8..eb64491 100644 --- a/doc/format.n +++ b/doc/format.n @@ -83,12 +83,15 @@ Specifies that the number should be padded on the left with zeroes instead of spaces. .TP 10 \fB#\fR -Requests an alternate output form. For \fBo\fR -conversions it guarantees that the first digit is always \fB0\fR. -For \fBx\fR or \fBX\fR conversions, \fB0x\fR or \fB0X\fR (respectively) +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 will be added to the beginning of the result unless it is zero. For \fBb\fR conversions, \fB0b\fR will be added to the beginning of the result unless it is zero. +For \fBd\fR conversions, \fB0d\fR there is no effect unless +the \fB0\fR specifier is used as well: In that case, \fB0d\fR +will be added to the beginning. For all floating-point conversions (\fBe\fR, \fBE\fR, \fBf\fR, \fBg\fR, and \fBG\fR) it guarantees that the result always has a decimal point. @@ -130,7 +133,7 @@ it must be a numeric string. .SS "OPTIONAL SIZE MODIFIER" .PP The fifth part of a conversion specifier is a size modifier, -which must be \fBll\fR, \fBh\fR, or \fBl\fR. +which must be \fBll\fR, \fBh\fR, \fBl\fR, or \fBL\fR. If it is \fBll\fR it specifies that an integer value is taken without truncation for conversion to a formatted substring. If it is \fBh\fR it specifies that an integer value is @@ -138,7 +141,9 @@ truncated to a 16-bit range before converting. This option is rarely useful. If it is \fBl\fR it specifies that the integer value is truncated to the same range as that produced by the \fBwide()\fR function of the \fBexpr\fR command (at least a 64-bit range). -If neither \fBh\fR nor \fBl\fR are present, the integer value is +If it is \fBL\fR it specifies that an integer or double value is taken +without truncation for conversion to a formatted substring. +If neither \fBh\fR nor \fBl\fR nor \fBL\fR are present, the integer value is truncated to the same range as that produced by the \fBint()\fR function of the \fBexpr\fR command (at least a 32-bit range, but determined by the value of the \fBwordSize\fR element of the @@ -198,8 +203,19 @@ precision, then convert number as for \fB%e\fR or Otherwise convert as for \fB%f\fR. Trailing zeroes and a trailing decimal point are omitted. .TP 10 +\fBa\fR or \fBA\fR +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 No conversion: just insert \fB%\fR. +.TP 10 +\fBp\fR +Shorthand form for \fB0x%zx\fR, so it outputs the integer in +hexadecimal form with \fB0x\fR prefix. .SH "DIFFERENCES FROM ANSI SPRINTF" .PP The behavior of the format command is the same as the @@ -208,13 +224,12 @@ differences: .IP [1] Tcl guarantees that it will be working with UNICODE characters. .IP [2] -\fB%p\fR and \fB%n\fR specifiers are not supported. +\fB%n\fR specifier is not supported. .IP [3] For \fB%c\fR conversions the argument must be an integer value, which will then be converted to the corresponding character value. .IP [4] The size modifiers are ignored when formatting floating-point values. -The \fBll\fR modifier has no \fBsprintf\fR counterpart. The \fBb\fR specifier has no \fBsprintf\fR counterpart. .SH EXAMPLES .PP diff --git a/doc/fpclassify.n b/doc/fpclassify.n new file mode 100644 index 0000000..5bf21c5 --- /dev/null +++ b/doc/fpclassify.n @@ -0,0 +1,83 @@ +'\" +'\" Copyright (c) 2018 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved +'\" Copyright (c) 2019 by Donal Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH fpclassify n 8.7 Tcl "Tcl Float Classifier" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +fpclassify \- Floating point number classification of Tcl values +.SH SYNOPSIS +package require \fBTcl 8.7\fR +.sp +\fBfpclassify \fIvalue\fR +.BE +.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 +. +\fIvalue\fR is a floating point zero. +.TP +\fBsubnormal\fR +. +\fIvalue\fR is the result of a gradual underflow. +.TP +\fBnormal\fR +. +\fIvalue\fR is an ordinary floating-point number (not zero, subnormal, +infinite, nor NaN). +.TP +\fBinfinite\fR +. +\fIvalue\fR is a floating-point infinity. +.TP +\fBnan\fR +. +\fIvalue\fR is Not-a-Number. +.PP +The \fBfpclassify\fR command throws an error if value is not a floating-point +value and cannot be converted to one. +.SH EXAMPLE +.PP +This shows how to check whether the result of a computation is numerically +safe or not. (Note however that it does not guard against numerical errors; +just against representational problems.) +.PP +.CS +set value [command-that-computes-a-value] +switch [\fBfpclassify\fR $value] { + normal - zero { + puts "Result is $value" + } + infinite { + puts "Result is infinite" + } + subnormal { + puts "Result is $value - WARNING! precision lost" + } + nan { + puts "Computation completely failed" + } +} +.CE +.SH "SEE ALSO" +expr(n), mathfunc(n) +.SH KEYWORDS +floating point +.SH STANDARDS +This command depends on the \fBfpclassify\fR() C macro conforming to +.QW "ISO C99" +(i.e., to ISO/IEC 9899:1999). +.SH COPYRIGHT +.nf +Copyright \(co 2018 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved +.fi +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/global.n b/doc/global.n index 9848817..e6d2678b 100644 --- a/doc/global.n +++ b/doc/global.n @@ -56,3 +56,7 @@ proc accum {string} { namespace(n), upvar(n), variable(n) .SH KEYWORDS global, namespace, procedure, variable +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/history.n b/doc/history.n index 0391948..05d936e 100644 --- a/doc/history.n +++ b/doc/history.n @@ -100,3 +100,7 @@ the \fBevent\fR operation to retrieve some event, and the \fBadd\fR operation to add it to history and execute it. .SH KEYWORDS event, history, record +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: @@ -13,10 +13,10 @@ .SH NAME http \- Client-side implementation of the HTTP/1.1 protocol .SH SYNOPSIS -\fBpackage require http ?2.9?\fR +\fBpackage require http\fI ?\fB2.9\fR? .\" See Also -useragent option documentation in body! .sp -\fB::http::config ?\fI\-option value\fR ...? +\fB::http::config\fR ?\fI\-option value\fR ...? .sp \fB::http::geturl \fIurl\fR ?\fI\-option value\fR ...? .sp @@ -99,6 +99,15 @@ comma-separated list of mime type patterns that you are willing to receive. For example, .QW "image/gif, image/jpeg, text/*" . .TP +\fB\-cookiejar\fR \fIcommand\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 +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 +.TP \fB\-pipeline\fR \fIboolean\fR . Specifies whether HTTP/1.1 transactions on a persistent socket will be @@ -770,6 +779,108 @@ Subsequent GET and HEAD requests in a failed pipeline will also be retried. that the retry is appropriate\fR - specifically, the application must know that if the failed POST successfully modified the state of the server, a repeat POST would have no adverse effect. +.VS TIP406 +.SH "COOKIE JAR PROTOCOL" +.PP +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 +.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 +command name; it is properly a command prefix (a Tcl list of words that will +be expanded in place) and admits many possible implementations. +.PP +Though not formally part of the protocol, it is expected that particular +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). +.TP +\fIcookieJar \fBgetCookies \fIprotocol host requestPath\fR +. +This command asks the cookie jar what cookies should be supplied for a +particular request. It should take the \fIprotocol\fR (typically \fBhttp\fR or +\fBhttps\fR), \fIhost\fR name and \fIrequestPath\fR (parsed from the \fIurl\fR +argument to \fB::http::geturl\fR) and return a list of cookie keys and values +that describe the cookies to supply to the remote host. The list must have an +even number of elements. +.RS +.PP +There should only ever be at most one cookie with a particular key for any +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 +.TP +\fIcookieJar \fBstoreCookie \fIcookieDictionary\fR +. +This command asks the cookie jar to store a particular cookie that was +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 +. +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 +. +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 +. +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 +. +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 +. +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 +. +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 +. +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 +. +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 +. +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. +.PP +Other keys may always be ignored; they have no meaning in this protocol. +.RE +.VE TIP406 .SH EXAMPLE .PP This example creates a procedure to copy a URL to a file while printing a diff --git a/doc/idna.n b/doc/idna.n new file mode 100644 index 0000000..744bf67 --- /dev/null +++ b/doc/idna.n @@ -0,0 +1,88 @@ +'\" +'\" Copyright (c) 2014-2018 Donal K. Fellows. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH "idna" n 0.1 http "Tcl Bundled Packages" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tcl::idna \- Support for normalization of Internationalized Domain Names +.SH SYNOPSIS +.nf +package require tcl::idna 1.0 + +\fBtcl::idna decode\fR \fIhostname\fR +\fBtcl::idna encode\fR \fIhostname\fR +\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR? +\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR? +\fBtcl::idna version\fR +.fi +.SH DESCRIPTION +This package provides an implementation of the punycode scheme used in +Internationalised Domain Names, and some access commands. (See RFC 3492 for a +description of punycode.) +.TP +\fBtcl::idna decode\fR \fIhostname\fR +. +This command takes the name of a host that potentially contains +punycode-encoded character sequences, \fIhostname\fR, and returns the hostname +as might be displayed to the user. Note that there are often UNICODE +characters that have extremely similar glyphs, so care should be taken with +displaying hostnames to users. +.TP +\fBtcl::idna encode\fR \fIhostname\fR +. +This command takes the name of a host as might be displayed to the user, +\fIhostname\fR, and returns the version of the hostname with characters not +permitted in basic hostnames encoded with punycode. +.TP +\fBtcl::idna puny\fR \fIsubcommand ...\fR +. +This command provides direct access to the basic punycode encoder and +decoder. It supports two \fIsubcommand\fRs: +.RS +.TP +\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR? +. +This command decodes the punycode-encoded string, \fIstring\fR, and returns +the result. If \fIcase\fR is provided, it is a boolean to make the case be +folded to upper case (if \fIcase\fR is true) or lower case (if \fIcase\fR is +false) during the decoding process; if omitted, no case transformation is +applied. +.TP +\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR? +. +This command encodes the string, \fIstring\fR, and returns the +punycode-encoded version of the string. If \fIcase\fR is provided, it is a +boolean to make the case be folded to upper case (if \fIcase\fR is true) or +lower case (if \fIcase\fR is false) during the encoding process; if omitted, +no case transformation is applied. +.RE +.TP +\fBtcl::idna version\fR +. +This returns the version of the \fBtcl::idna\fR package. +.SH "EXAMPLE" +.PP +This is an example of how punycoding of a string works: +.PP +.CS +package require tcl::idna + +puts [\fBtcl::idna puny encode\fR "abc\(->def"] +# prints: \fIabcdef-kn2c\fR +puts [\fBtcl::idna puny decode\fR "abcdef-kn2c"] +# prints: \fIabc\(->def\fR +.CE +'\" TODO: show how it handles a real domain name +.SH "SEE ALSO" +http(n), cookiejar(n) +.SH KEYWORDS +internet, www +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: @@ -27,6 +27,11 @@ and also returned as result. Starting with the Tcl 8.5 release, the variable \fIvarName\fR passed to \fBincr\fR may be unset, and in that case, it will be set to the value \fIincrement\fR or to the default increment value of \fB1\fR. +.VS TIP508 +If \fIvarName\fR indicate an element that does not exist of an array that has +a default value set, the sum of the default value and the \fIincrement\fR (or +1) will be stored in the array element. +.VE TIP508 .SH EXAMPLES .PP Add one to the contents of the variable \fIx\fR: @@ -59,3 +64,7 @@ an error if it is not): expr(n), set(n) .SH KEYWORDS add, increment, variable, value +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: @@ -13,95 +13,102 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -info \- Return information about the state of the Tcl interpreter +info \- Information about the state of the Tcl interpreter .SH SYNOPSIS \fBinfo \fIoption \fR?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP -This command provides information about various internals of the Tcl -interpreter. -The legal \fIoption\fRs (which may be abbreviated) are: +Available commands: .TP \fBinfo args \fIprocname\fR . -Returns a list containing the names of the arguments to procedure -\fIprocname\fR, in order. \fIProcname\fR must be the name of a -Tcl command procedure. +Returns the names of the parameters to the procedure named \fIprocname\fR. .TP \fBinfo body \fIprocname\fR . -Returns the body of procedure \fIprocname\fR. \fIProcname\fR must be -the name of a Tcl command procedure. +Returns the body of the procedure named \fIprocname\fR. .TP \fBinfo class\fI subcommand class\fR ?\fIarg ...\fR -.VS 8.6 -Returns information about the class, \fIclass\fR. The \fIsubcommand\fRs are -described in \fBCLASS INTROSPECTION\fR below. -.VE 8.6 +. +Returns information about the class named \fIclass\fR. +See \fBCLASS INTROSPECTION\fR below. .TP \fBinfo cmdcount\fR . -Returns a count of the total number of commands that have been invoked -in this interpreter. +Returns the total number of commands evaluated in this interpreter. +.TP +\fBinfo cmdtype \fIcommandName\fR +.VS TIP426 +Returns a the type of the command named \fIcommandName\fR. +Built-in types are: +.RS +.IP \fBalias\fR +\fIcommandName\fR was created by \fBinterp alias\fR. +In a safe interpreter an alias is only visible if both the alias and the +target are visible. +.IP \fBcoroutine\fR +\fIcommandName\fR was created by \fBcoroutine\fR. +.IP \fBensemble\fR +\fIcommandName\fR was created by \fBnamespace ensemble\fR. +.IP \fBimport\fR +\fIcommandName\fR was created by \fBnamespace import\fR. +.IP \fBnative\fR +\fIcommandName\fR was created by the \fBTcl_CreateObjProc\fR +interface directly without further registration of the type of command. +.IP \fBobject\fR +\fIcommandName\fR is the public command that represents an +instance of \fBoo::object\fR or one of its subclasses. +.IP \fBprivateObject\fR +\fIcommandName\fR is the private command, \fBmy\fR by default, +that represents an instance of \fBoo::object\fR or one of its subclasses. +.IP \fBproc\fR +\fIcommandName\fR was created by \fBproc\fR. +.IP \fBslave\fR +\fIcommandName\fR was created by \fBinterp create\fR. +.IP \fBzlibStream\fR +\fIcommandName\fR was created by \fBzlib stream\fR. +.PP +Other types may be also registered as well. See \fBTcl_RegisterCommandTypeName\fR. +.RE +.VE TIP426 .TP \fBinfo commands \fR?\fIpattern\fR? . -If \fIpattern\fR is not specified, -returns a list of names of all the Tcl commands visible -(i.e. executable without using a qualified name) to the current namespace, -including both the built-in commands written in C and -the command procedures defined using the \fBproc\fR command. -If \fIpattern\fR is specified, -only those names matching \fIpattern\fR are returned. -Matching is determined using the same rules as for \fBstring match\fR. -\fIpattern\fR can be a qualified name like \fBFoo::print*\fR. -That is, it may specify a particular namespace -using a sequence of namespace names separated by double colons (\fB::\fR), -and may have pattern matching special characters -at the end to specify a set of commands in that namespace. -If \fIpattern\fR is a qualified name, -the resulting list of command names has each one qualified with the name -of the specified namespace, and only the commands defined in the named -namespace are returned. -.\" Technically, most of this hasn't changed; that's mostly just the -.\" way it always worked. Hardly anyone knew that though. +Returns the names of all commands visible in the current namespace. If +\fIpattern\fR is given, returns only those names that match according to +\fBstring match\fR. Only the last component of \fIpattern\fR is a pattern. +Other components identify a namespace. See \fBNAMESPACE RESOLUTION\fR in the +\fBnamespace\fR(n) documentation. .TP \fBinfo complete \fIcommand\fR . -Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of -having no unclosed quotes, braces, brackets or array element names. -If the command does not appear to be complete then 0 is returned. -This command is typically used in line-oriented input environments -to allow users to type in commands that span multiple lines; if the -command is not complete, the script can delay evaluating it until additional -lines have been typed to complete the command. +Returns 1 if \fIcommand\fR is a complete command, and \fB0\fR otherwise. +Typically used in line-oriented input environments +to allow users to type in commands that span multiple lines. .TP \fBinfo coroutine\fR -.VS 8.6 -Returns the name of the currently executing \fBcoroutine\fR, or the empty -string if either no coroutine is currently executing, or the current coroutine -has been deleted (but has not yet returned or yielded since deletion). -.VE 8.6 +. +Returns the name of the current \fBcoroutine\fR, or the empty +string if there is no current coroutine or the current coroutine +has been deleted. .TP -\fBinfo default \fIprocname arg varname\fR +\fBinfo default \fIprocname parameter varname\fR . -\fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR -must be the name of an argument to that procedure. If \fIarg\fR -does not have a default value then the command returns \fB0\fR. -Otherwise it returns \fB1\fR and places the default value of \fIarg\fR -into variable \fIvarname\fR. +If the parameter \fIparameter\fR for the procedure named \fIprocname\fR has a +default value, stores that value in \fIvarname\fR and returns \fB1\fR. +Otherwise, returns \fB0\fR. .TP \fBinfo errorstack \fR?\fIinterp\fR? -.VS 8.6 -Returns, in a form that is programmatically easy to parse, the function names -and arguments at each level from the call stack of the last error in the given -\fIinterp\fR, or in the current one if not specified. +. +Returns a description of the active command at each level for the +last error in the current interpreter, or in the interpreter named +\fIinterp\fR if given. .RS .PP -This form is an even-sized list alternating tokens and parameters. Tokens are +The description is a dictionary of tokens and parameters. Tokens are currently either \fBCALL\fR, \fBUP\fR, or \fBINNER\fR, but other values may be -introduced in the future. \fBCALL\fR indicates a procedure call, and its +introduced in the future. \fBCALL\fR indicates a command call, and its parameter is the corresponding \fBinfo level\fR \fB0\fR. \fBUP\fR indicates a shift in variable frames generated by \fBuplevel\fR or similar, and applies to the previous \fBCALL\fR item. Its parameter is the level offset. \fBINNER\fR @@ -109,127 +116,103 @@ identifies the .QW "inner context" , which is the innermost atomic command or bytecode instruction that raised the error, along with its arguments when available. While \fBCALL\fR and \fBUP\fR -allow to follow complex call paths, \fBINNER\fR homes in on the offending -operation in the innermost procedure call, even going to sub-expression +provide a trail of the call path, \fBINNER\fR provides details of the offending +operation in the innermost procedure call, even to sub-expression granularity. .PP This information is also present in the \fB\-errorstack\fR entry of the options dictionary returned by 3-argument \fBcatch\fR; \fBinfo errorstack\fR is a convenient way of retrieving it for uncaught errors at top-level in an -interactive \fBtclsh\fR. +interactive \fBinterpreter\fR. .RE -.VE 8.6 .TP \fBinfo exists \fIvarName\fR . -Returns \fB1\fR if the variable named \fIvarName\fR exists in the -current context (either as a global or local variable) and has been -defined by being given a value, returns \fB0\fR otherwise. +Returns \fB1\fR if a variable named \fIvarName\fR is visible and has been +defined, and \fB0\fR otherwise. .TP -\fBinfo frame\fR ?\fInumber\fR? +\fBinfo frame\fR ?\fIdepth\fR? . -This command provides access to all frames on the stack, even those -hidden from \fBinfo level\fR. If \fInumber\fR is not specified, this -command returns a number giving the frame level of the command. This -is 1 if the command is invoked at top-level. If \fInumber\fR is -specified, then the result is a dictionary containing the location -information for the command at the \fInumber\fRed level on the stack. +Returns the depth of the call to \fBinfo frame\fR itself. Otherwise, returns a +dictionary describing the active command at the \fIdepth\fR, which counts all +commands visible to \fBinfo level\fR, plus commands that don't create a new +level, such as \fBeval\fR, \fBsource\fR, or \fIuplevel\fR. The frame depth is +always greater than the current level. .RS .PP -If \fInumber\fR is positive (> 0) then it selects a particular stack -level (1 refers to the outer-most active command, 2 to the command it -called, and so on, up to the current frame level which refers to -\fBinfo frame\fR itself); otherwise it gives a level relative to the -current command (0 refers to the current command, i.e., \fBinfo -frame\fR itself, -1 to its caller, and so on). -.PP -This is similar to how \fBinfo level\fR works, except that this -subcommand reports all frames, like \fBsource\fRd scripts, -\fBeval\fRs, \fBuplevel\fRs, etc. +If \fIdepth\fR is greater than \fB0\fR it is the frame at that depth. Otherwise +it is the number of frames up from the current frame. .PP -Note that for nested commands, like +As with \fBinfo level\fR and error traces, for nested commands like .QW "foo [bar [x]]" , only .QW x -will be seen by an \fBinfo frame\fR invoked within +is seen by \fBinfo frame\fR invoked within .QW x . -This is the same as for \fBinfo level\fR and error stack traces. .PP -The result dictionary may contain the keys listed below, with the -specified meanings for their values: +The dictionary may contain the following keys: .TP \fBtype\fR . -This entry is always present and describes the nature of the location -for the command. The recognized values are \fBsource\fR, \fBproc\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 . -means that the command is found in a script loaded by the \fBsource\fR +A script loaded via the \fBsource\fR command. .TP \fBproc\fR\0\0\0\0\0\0\0\0 . -means that the command is found in dynamically created procedure body. +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 . -means that the command is executed by \fBeval\fR or \fBuplevel\fR. +The body of a script provided to \fBeval\fR or \fBuplevel\fR. .TP \fBprecompiled\fR\0\0\0\0\0\0\0\0 . -means that the command is found in a pre-compiled script (loadable by -the package \fBtbcload\fR), and no further information will be -available. +A pre-compiled script (loadable by the package +\fBtbcload\fR), and no further information is available. .RE .TP \fBline\fR . -This entry provides the number of the line the command is at inside of -the script it is a part of. This information is not present for type -\fBprecompiled\fR. For type \fBsource\fR this information is counted -relative to the beginning of the file, whereas for the last two types -the line is counted relative to the start of the script. +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 . -This entry is present only for type \fBsource\fR. It provides the -normalized path of the file the command is in. +For type \fBsource\fR, provides the normalized path of the file that contains +the command. .TP \fBcmd\fR . -This entry provides the string representation of the command. This is -usually the unsubstituted form, however for commands which are a -canonically-constructed list (e.g., as produced by the \fBlist\fR command) -executed by \fBeval\fR it is the substituted form as they have no other -string representation. Care is taken that the canonicality property of -the latter is not spoiled. +The command before substitutions were performed. .TP \fBproc\fR . -This entry is present only if the command is found in the body of a -regular Tcl procedure. It then provides the name of that procedure. +For type \fBprod\fR, the name of the procedure containing the command. .TP \fBlambda\fR . -This entry is present only if the command is found in the body of an -anonymous Tcl procedure, i.e. a lambda. It then provides the entire -definition of the lambda in question. +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 . -This entry is present only if the queried frame has a corresponding -frame returned by \fBinfo level\fR. It provides the index of this -frame, relative to the current level (0 and negative numbers). +For a frame that corresponds to a level, (to be determined). .PP -A thing of note is that for procedures statically defined in files the -locations of commands in their bodies will be reported with type -\fBsource\fR and absolute line numbers, and not as type -\fBproc\fR. The same is true for procedures nested in statically -defined procedures, and literal eval scripts in files or statically -defined procedures. +When a command can be traced to its literal definition in some script, e.g. +procedures nested in statically defined procedures, and literal eval scripts in +files or statically defined procedures, its type is \fBsource\fR and its +location is the absolute line number in the script. Otherwise, its type is +\fBproc\fR and its location is its line number within the body of the +procedure. .PP In contrast, procedure definitions and \fBeval\fR within a dynamically \fBeval\fRuated environment count line numbers relative to the start of @@ -237,7 +220,7 @@ their script, even if they would be able to count relative to the start of the outer dynamic script. That type of number usually makes more sense. .PP -A different way of describing this behaviour is that file based +A different way of describing this behaviour is that file-based locations are tracked as deeply as possible, and where this is not possible the lines are counted based on the smallest possible \fBeval\fR or procedure body, as that scope is usually easier to find @@ -251,167 +234,129 @@ counted relative to the start of each word (smallest scope) .TP \fBinfo functions \fR?\fIpattern\fR? . -If \fIpattern\fR is not specified, returns a list of all the math +If \fIpattern\fR is not given, returns a list of all the math functions currently defined. -If \fIpattern\fR is specified, only those functions whose name matches -\fIpattern\fR are returned. Matching is determined using the same -rules as for \fBstring match\fR. +If \fIpattern\fR is given, returns only those names that match +\fIpattern\fR according to \fBstring match\fR. .TP \fBinfo globals \fR?\fIpattern\fR? . -If \fIpattern\fR is not specified, returns a list of all the names +If \fIpattern\fR is not given, returns a list of all the names of currently-defined global variables. Global variables are variables in the global namespace. -If \fIpattern\fR is specified, only those names matching \fIpattern\fR +If \fIpattern\fR is given, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. .TP \fBinfo hostname\fR . -Returns the name of the computer on which this invocation is being -executed. -Note that this name is not guaranteed to be the fully qualified domain -name of the host. Where machines have several different names (as is +Returns the name of the current host. + +This name is not guaranteed to be the fully-qualified domain +name of the host. Where machines have several different names, as is common on systems with both TCP/IP (DNS) and NetBIOS-based networking -installed,) it is the name that is suitable for TCP/IP networking that +installed, it is the name that is suitable for TCP/IP networking that is returned. .TP -\fBinfo level\fR ?\fInumber\fR? +\fBinfo level\fR ?\fIlevel\fR? . -If \fInumber\fR is not specified, this command returns a number -giving the stack level of the invoking procedure, or 0 if the -command is invoked at top-level. If \fInumber\fR is specified, -then the result is a list consisting of the name and arguments for the -procedure call at level \fInumber\fR on the stack. If \fInumber\fR -is positive then it selects a particular stack level (1 refers -to the top-most active procedure, 2 to the procedure it called, and -so on); otherwise it gives a level relative to the current level -(0 refers to the current procedure, -1 to its caller, and so on). -See the \fBuplevel\fR command for more information on what stack -levels mean. +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 +list. See \fBuplevel\fR for more information on levels. .TP \fBinfo library\fR . -Returns the name of the library directory in which standard Tcl -scripts are stored. -This is actually the value of the \fBtcl_library\fR -variable and may be changed by setting \fBtcl_library\fR. +Returns the value of \fBtcl_library\fR, which is the name of the library +directory in which the scripts distributed with Tcl scripts are stored. .TP -\fBinfo loaded \fR?\fIinterp\fR? +\fBinfo loaded \fR?\fIinterp\fR? ?\fIpackage\fR? . -Returns a list describing all of the packages that have been loaded into -\fIinterp\fR with the \fBload\fR command. -Each list element is a sub-list with two elements consisting of the -name of the file from which the package was loaded and the name of -the package. -For statically-loaded packages the file name will be an empty string. -If \fIinterp\fR is omitted then information is returned for all packages -loaded in any interpreter in the process. -To get a list of just the packages in the current interpreter, specify -an empty string for the \fIinterp\fR argument. +Returns the name of each file loaded in \fIinterp\fR va \fBload\fR as part of +\fIpackage\fR . If \fIpackage\fR is not given, returns a list where each item +is the name of the loaded file and the name of the package for which the file +was loaded. For a statically-loaded package the name of the file is the empty +string. For \fInterp\fR, the empty string is the current interpreter. .TP \fBinfo locals \fR?\fIpattern\fR? . -If \fIpattern\fR is not specified, returns a list of all the names -of currently-defined local variables, including arguments to the -current procedure, if any. -Variables defined with the \fBglobal\fR, \fBupvar\fR and -\fBvariable\fR commands will not be returned. -If \fIpattern\fR is specified, only those names matching \fIpattern\fR -are returned. Matching is determined using the same rules as for -\fBstring match\fR. +If \fIpattern\fR is given, returns the name of each local variable matching +\fIpattern\fR according to \fBstring match\fR. Otherwise, returns the name of +each local variable. A variables defined with the \fBglobal\fR, \fBupvar\fR or +\fBvariable\fR is not local. + .TP \fBinfo nameofexecutable\fR . -Returns the full path name of the binary file from which the application -was invoked. If Tcl was unable to identify the file, then an empty -string is returned. +Returns the absolute pathname of the program for the current interpreter. If +such a file can not be identified an empty string is returned. .TP \fBinfo object\fI subcommand object\fR ?\fIarg ...\fR -.VS 8.6 -Returns information about the object, \fIobject\fR. The \fIsubcommand\fRs are -described in \fBOBJECT INTROSPECTION\fR below. -.VE 8.6 +. +Returns information about the object named \fIobject\fR. \fIsubcommand\fR is +described \fBOBJECT INTROSPECTION\fR below. .TP \fBinfo patchlevel\fR . -Returns the value of the global variable \fBtcl_patchLevel\fR, which holds -the exact version of the Tcl library by default. +Returns the value of the global variable \fBtcl_patchLevel\fR, in which the +exact version of the Tcl library initially stored. .TP \fBinfo procs \fR?\fIpattern\fR? . -If \fIpattern\fR is not specified, returns a list of all the -names of Tcl command procedures in the current namespace. -If \fIpattern\fR is specified, -only those procedure names in the current namespace -matching \fIpattern\fR are returned. -Matching is determined using the same rules as for -\fBstring match\fR. -If \fIpattern\fR contains any namespace separators, they are used to -select a namespace relative to the current namespace (or relative to -the global namespace if \fIpattern\fR starts with \fB::\fR) to match -within; the matching pattern is taken to be the part after the last -namespace separator. +Returns the names of all visible procedures. If \fIpattern\fR is given, returns +only those names that match according to \fBstring match\fR. Only the final +component in \fIpattern\fR is actually considered a pattern. Any qualifying +components simply select a namespace. See \fBNAMESPACE RESOLUTION\fR in the +\fBnamespace\fR(n) documentation. .TP \fBinfo script\fR ?\fIfilename\fR? . -If a Tcl script file is currently being evaluated (i.e. there is a -call to \fBTcl_EvalFile\fR active or there is an active invocation -of the \fBsource\fR command), then this command returns the name -of the innermost file being processed. If \fIfilename\fR is specified, -then the return value of this command will be modified for the -duration of the active invocation to return that name. This is -useful in virtual file system applications. -Otherwise the command returns an empty string. +Returns the pathname of the innermost script currently being evaluated, or the +empty string if no pathname can be determined. If \fIfilename\fR is given, +sets the return value of any future calls to \fBinfo script\fR for the duration +of the innermost active script. This is useful in virtual file system +applications. .TP \fBinfo sharedlibextension\fR . -Returns the extension used on this platform for the names of files -containing shared libraries (for example, \fB.so\fR under Solaris). -If shared libraries are not supported on this platform then an empty -string is returned. +Returns the extension used on this platform for names of shared libraries, e.g. +\fB.so\fR under Solaris. Returns the empty string if shared libraries are not +supported on this platform. .TP \fBinfo tclversion\fR . -Returns the value of the global variable \fBtcl_version\fR, which holds the -major and minor version of the Tcl library by default. +Returns the value of the global variable \fBtcl_version\fR, in which the +major and minor version of the Tcl library are stored. .TP \fBinfo vars\fR ?\fIpattern\fR? . -If \fIpattern\fR is not specified, -returns a list of all the names of currently-visible variables. -This includes locals and currently-visible globals. -If \fIpattern\fR is specified, only those names matching \fIpattern\fR -are returned. Matching is determined using the same rules as for -\fBstring match\fR. -\fIpattern\fR can be a qualified name like \fBFoo::option*\fR. -That is, it may specify a particular namespace -using a sequence of namespace names separated by double colons (\fB::\fR), -and may have pattern matching special characters -at the end to specify a set of variables in that namespace. -If \fIpattern\fR is a qualified name, -the resulting list of variable names -has each matching namespace variable qualified with the name -of its namespace. -Note that a currently-visible variable may not yet -.QW exist -if it has not -been set (e.g. a variable declared but not set by \fBvariable\fR). +If \fIpattern\fR is not given, returns the names of all visible variables. If +\fIpattern\fR is given, returns only those names that match according to +\fBstring match\fR. Only the last component of \fIpattern\fR is a pattern. +Other components identify a namespace. See \fBNAMESPACE RESOLUTION\fR in the +\fBnamespace\fR(n) documentation. When \fIpattern\fR is a qualified name, +results are fully qualified. + +A variable that has declared but not yet defined is included in the results. .SS "CLASS INTROSPECTION" -.VS 8.6 .PP The following \fIsubcommand\fR values are supported by \fBinfo class\fR: -.VE 8.6 .TP \fBinfo class call\fI class method\fR -.VS +. Returns a description of the method implementations that are used to provide a stereotypical instance of \fIclass\fR's implementation of \fImethod\fR (stereotypical instances being objects instantiated by a class without having any object-specific definitions added). This consists of a list of lists of four elements, where each sublist consists of a word that describes the general type of method implementation (being one of \fBmethod\fR for an -ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a +ordinary method, \fBfilter\fR for an applied filter, +.VS TIP500 +\fBprivate\fR for a private method, +.VE TIP500 +and \fBunknown\fR for a method that is invoked as part of unknown method handling), a word giving the name of the particular method invoked (which is always the same as \fImethod\fR for the \fBmethod\fR type, and @@ -422,122 +367,167 @@ implementation (see \fBinfo class methodtype\fR). .RS .PP Note that there is no inspection of whether the method implementations -actually use \fBnext\fR to transfer control along the call chain. +actually use \fBnext\fR to transfer control along the call chain, +.VS TIP500 +and the call chains that this command files do not actually contain private +methods. +.VE TIP500 .RE -.VE 8.6 .TP \fBinfo class constructor\fI class\fR -.VS 8.6 +. This subcommand returns a description of the definition of the constructor of class \fIclass\fR. The definition is described as a two element list; the first element is the list of arguments to the constructor in a form suitable for passing to another call to \fBproc\fR or a method definition, and the second element is the body of the constructor. If no constructor is present, this returns the empty list. -.VE 8.6 .TP \fBinfo class definition\fI class method\fR -.VS 8.6 +. This subcommand returns a description of the definition of the method named \fImethod\fR of class \fIclass\fR. The definition is described as a two element list; the first element is the list of arguments to the method in a form suitable for passing to another call to \fBproc\fR or a method definition, and the second element is the body of the method. -.VE 8.6 +.TP +\fBinfo class definitionnamespace\fI class\fR ?\fIkind\fR? +.VS TIP524 +This subcommand returns the definition namespace for \fIkind\fR definitions of +the class \fIclass\fR; the definition namespace only affects the instances of +\fIclass\fR, not \fIclass\fR itself. The \fIkind\fR can be either +\fB\-class\fR to return the definition namespace used for \fBoo::define\fR, or +\fB\-instance\fR to return the definition namespace used for +\fBoo::objdefine\fR; the \fB\-class\fR kind is default (though this is only +actually useful on classes that are subclasses of \fBoo::class\fR). +.RS +.PP +If \fIclass\fR does not provide a definition namespace of the given kind, +this command returns the empty string. In those circumstances, the +\fBoo::define\fR and \fBoo::objdefine\fR commands look up which definition +namespace to use using the class inheritance hierarchy. +.RE +.VE TIP524 .TP \fBinfo class destructor\fI class\fR -.VS 8.6 +. This subcommand returns the body of the destructor of class \fIclass\fR. If no destructor is present, this returns the empty string. -.VE 8.6 .TP \fBinfo class filters\fI class\fR -.VS 8.6 +. This subcommand returns the list of filter methods set on the class. -.VE 8.6 .TP \fBinfo class forward\fI class method\fR -.VS 8.6 +. This subcommand returns the argument list for the method forwarding called \fImethod\fR that is set on the class called \fIclass\fR. -.VE 8.6 .TP \fBinfo class instances\fI class\fR ?\fIpattern\fR? -.VS 8.6 +. This subcommand returns a list of instances of class \fIclass\fR. If the optional \fIpattern\fR argument is present, it constrains the list of returned instances to those that match it according to the rules of \fBstring match\fR. -.VE 8.6 .TP \fBinfo class methods\fI class\fR ?\fIoptions...\fR? -.VS 8.6 +. 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 -specified, controlling exactly which method names are returned: +given, controlling exactly which method names are returned: .RS -.VE 8.6 .TP \fB\-all\fR -.VS 8.6 -If the \fB\-all\fR flag is given, the list of methods will include those +. +If the \fB\-all\fR flag is given, +.VS TIP500 +and the \fB\-scope\fR flag is not given, +.VE TIP500 +the list of methods will include those methods defined not just by the class, but also by the class's superclasses and mixins. -.VE 8.6 .TP \fB\-private\fR -.VS 8.6 -If the \fB\-private\fR flag is given, the list of methods will also include -the private (i.e. non-exported) methods of the class (and superclasses and +. +If the \fB\-private\fR flag is given, +.VS TIP500 +and the \fB\-scope\fR flag is not given, +.VE TIP500 +the list of methods will also include +the non-exported methods of the class (and superclasses and mixins, if \fB\-all\fR is also given). +.VS TIP500 +Note that this naming is an unfortunate clash with true private methods; this +option name is retained for backward compatibility. +.VE TIP500 +.TP +\fB\-scope\fI scope\fR +.VS TIP500 +Returns a list of all methods on \fIclass\fR that have the given visibility +\fIscope\fR. When this option is supplied, both the \fB\-all\fR and +\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. +.IP \fBunexported\fR 3 +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. +.RE +.VE TIP500 .RE -.VE 8.6 .TP \fBinfo class methodtype\fI class method\fR -.VS 8.6 +. This subcommand returns a description of the type of implementation used for the method named \fImethod\fR of class \fIclass\fR. When the result is \fBmethod\fR, further information can be discovered with \fBinfo class definition\fR, and when the result is \fBforward\fR, further information can be discovered with \fBinfo class forward\fR. -.VE 8.6 .TP \fBinfo class mixins\fI class\fR -.VS 8.6 +. This subcommand returns a list of all classes that have been mixed into the class named \fIclass\fR. -.VE 8.6 .TP \fBinfo class subclasses\fI class\fR ?\fIpattern\fR? -.VS 8.6 +. This subcommand returns a list of direct subclasses of class \fIclass\fR. If the optional \fIpattern\fR argument is present, it constrains the list of returned classes to those that match it according to the rules of \fBstring match\fR. -.VE 8.6 .TP \fBinfo class superclasses\fI class\fR -.VS 8.6 +. This subcommand returns a list of direct superclasses of class \fIclass\fR in inheritance precedence order. -.VE 8.6 .TP -\fBinfo class variables\fI class\fR -.VS 8.6 +\fBinfo class variables\fI class\fR ?\fB\-private\fR? +. This subcommand returns a list of all variables that have been declared for the class named \fIclass\fR (i.e. that are automatically present in the class's methods, constructor and destructor). +.VS TIP500 +If the \fB\-private\fR option is given, this lists the private variables +declared instead. +.VE TIP500 .SS "OBJECT INTROSPECTION" .PP The following \fIsubcommand\fR values are supported by \fBinfo object\fR: -.VE 8.6 .TP \fBinfo object call\fI object method\fR -.VS 8.6 +. Returns a description of the method implementations that are used to provide \fIobject\fR's implementation of \fImethod\fR. This consists of a list of lists of four elements, where each sublist consists of a word that describes the general type of method implementation (being one of \fBmethod\fR for an -ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a +ordinary method, \fBfilter\fR for an applied filter, +.VS TIP500 +\fBprivate\fR for a private method, +.VE TIP500 +and \fBunknown\fR for a method that is invoked as part of unknown method handling), a word giving the name of the particular method invoked (which is always the same as \fImethod\fR for the \fBmethod\fR type, and @@ -549,128 +539,160 @@ implementation (see \fBinfo object methodtype\fR). .RS .PP Note that there is no inspection of whether the method implementations -actually use \fBnext\fR to transfer control along the call chain. +actually use \fBnext\fR to transfer control along the call chain, +.VS TIP500 +and the call chains that this command files do not actually contain private +methods. +.VE TIP500 .RE -.VE 8.6 .TP \fBinfo object class\fI object\fR ?\fIclassName\fR? -.VS 8.6 -If \fIclassName\fR is unspecified, this subcommand returns class of the +. +If \fIclassName\fR is not given, this subcommand returns class of the \fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a boolean value indicating whether the \fIobject\fR is of that class. -.VE 8.6 +.TP +\fBinfo object creationid\fI object\fR +.VS TIP500 +Returns the unique creation identifier for the \fIobject\fR object. This +creation identifier is unique to the object (within a Tcl interpreter) and +cannot be controlled at object creation time or altered afterwards. +.RS +.PP +\fIImplementation note:\fR the creation identifier is used to generate unique +identifiers associated with the object, especially for private variables. +.RE +.VE TIP500 .TP \fBinfo object definition\fI object method\fR -.VS 8.6 +. This subcommand returns a description of the definition of the method named \fImethod\fR of object \fIobject\fR. The definition is described as a two element list; the first element is the list of arguments to the method in a form suitable for passing to another call to \fBproc\fR or a method definition, and the second element is the body of the method. -.VE 8.6 .TP \fBinfo object filters\fI object\fR -.VS 8.6 +. This subcommand returns the list of filter methods set on the object. -.VE 8.6 .TP \fBinfo object forward\fI object method\fR -.VS 8.6 +. This subcommand returns the argument list for the method forwarding called \fImethod\fR that is set on the object called \fIobject\fR. -.VE 8.6 .TP \fBinfo object isa\fI category object\fR ?\fIarg\fR? -.VS 8.6 +. This subcommand tests whether an object belongs to a particular category, returning a boolean value that indicates whether the \fIobject\fR argument meets the criteria for the category. The supported categories are: -.VE 8.6 .RS .TP \fBinfo object isa class\fI object\fR -.VS 8.6 +. This returns whether \fIobject\fR is a class (i.e. an instance of \fBoo::class\fR or one of its subclasses). -.VE 8.6 .TP \fBinfo object isa metaclass\fI object\fR -.VS 8.6 +. This returns whether \fIobject\fR is a class that can manufacture classes (i.e. is \fBoo::class\fR or a subclass of it). -.VE 8.6 .TP \fBinfo object isa mixin\fI object class\fR -.VS 8.6 +. This returns whether \fIclass\fR is directly mixed into \fIobject\fR. -.VE 8.6 .TP \fBinfo object isa object\fI object\fR -.VS 8.6 +. This returns whether \fIobject\fR really is an object. -.VE 8.6 .TP \fBinfo object isa typeof\fI object class\fR -.VS 8.6 +. This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether \fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether direct or indirect). .RE -.VE 8.6 .TP \fBinfo object methods\fI object\fR ?\fIoption...\fR? -.VS 8.6 +. 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 -specified, controlling exactly which method names are returned: +given, controlling exactly which method names are returned: .RS -.VE 8.6 .TP \fB\-all\fR -.VS 8.6 -If the \fB\-all\fR flag is given, the list of methods will include those +. +If the \fB\-all\fR flag is given, +.VS TIP500 +and the \fB\-scope\fR flag is not given, +.VE TIP500 +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. -.VE 8.6 .TP \fB\-private\fR -.VS 8.6 -If the \fB\-private\fR flag is given, the list of methods will also include -the private (i.e. non-exported) methods of the object (and classes, if +. +If the \fB\-private\fR flag is given, +.VS TIP500 +and the \fB\-scope\fR flag is not given, +.VE TIP500 +the list of methods will also include +the non-exported methods of the object (and classes, if \fB\-all\fR is also given). +.VS TIP500 +Note that this naming is an unfortunate clash with true private methods; this +option name is retained for backward compatibility. +.VE TIP500 +.TP +\fB\-scope\fI scope\fR +.VS TIP500 +Returns a list of all methods on \fIobject\fR that have the given visibility +\fIscope\fR. When this option is supplied, both the \fB\-all\fR and +\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) 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. +.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. +.RE +.VE TIP500 .RE -.VE 8.6 .TP \fBinfo object methodtype\fI object method\fR -.VS 8.6 +. This subcommand returns a description of the type of implementation used for the method named \fImethod\fR of object \fIobject\fR. When the result is \fBmethod\fR, further information can be discovered with \fBinfo object definition\fR, and when the result is \fBforward\fR, further information can be discovered with \fBinfo object forward\fR. -.VE 8.6 .TP \fBinfo object mixins\fI object\fR -.VS 8.6 +. This subcommand returns a list of all classes that have been mixed into the object named \fIobject\fR. -.VE 8.6 .TP \fBinfo object namespace\fI object\fR -.VS 8.6 +. This subcommand returns the name of the internal namespace of the object named \fIobject\fR. -.VE 8.6 .TP -\fBinfo object variables\fI object\fR -.VS 8.6 +\fBinfo object variables\fI object\fRR ?\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 object's methods). -.VE 8.6 +.VS TIP500 +If the \fB\-private\fR option is given, this lists the private variables +declared instead. +.VE TIP500 .TP \fBinfo object vars\fI object\fR ?\fIpattern\fR? -.VS 8.6 +. This subcommand returns a list of all variables in the private namespace of the object named \fIobject\fR. If the optional \fIpattern\fR argument is given, it is a filter (in the syntax of a \fBstring match\fR glob pattern) @@ -679,7 +701,6 @@ from the list returned by \fBinfo object variables\fR; that can include variables that are currently unset, whereas this can include variables that are not automatically included by any of \fIobject\fR's methods (or those of its class, superclasses or mixins). -.VE 8.6 .SH EXAMPLES .PP This command prints out a procedure suitable for saving in a Tcl @@ -702,7 +723,6 @@ proc printProc {procName} { } .CE .SS "EXAMPLES WITH OBJECTS" -.VS 8.6 .PP Every object necessarily knows what its class is; this information is trivially extractable through introspection: @@ -723,8 +743,10 @@ method and get how it is defined. This procedure illustrates how: proc getDef {obj method} { foreach inf [\fBinfo object call\fR $obj $method] { lassign $inf calltype name locus methodtype + # Assume no forwards or filters, and hence no $calltype # or $methodtype checks... + if {$locus eq "object"} { return [\fBinfo object definition\fR $obj $name] } else { @@ -747,7 +769,9 @@ proc getDef {obj method} { # Assume no forwards return [\fBinfo object definition\fR $obj $method] } + set cls [\fBinfo object class\fR $obj] + while {$method ni [\fBinfo class methods\fR $cls]} { # Assume the simple case set cls [lindex [\fBinfo class superclass\fR $cls] 0] @@ -755,22 +779,17 @@ proc getDef {obj method} { error "no definition for $method" } } + # Assume no forwards return [\fBinfo class definition\fR $cls $method] } .CE -.VE 8.6 .SH "SEE ALSO" -.VS 8.6 global(n), oo::class(n), oo::define(n), oo::object(n), proc(n), self(n), -.VE 8.6 tcl_library(n), tcl_patchLevel(n), tcl_version(n) .SH KEYWORDS command, information, interpreter, introspection, level, namespace, -.VS 8.6 -object, -.VE 8.6 -procedure, variable +object, procedure, variable '\" Local Variables: '\" mode: nroff '\" fill-column: 78 diff --git a/doc/interp.n b/doc/interp.n index 9fcd055..54555e3 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -154,7 +154,6 @@ what to set the interpreter's background exception handler to. See the \fBBACKGROUND EXCEPTION HANDLING\fR section for more details. .TP \fBinterp\fR \fBcancel \fR?\fB\-unwind\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? ?\fIresult\fR? -.VS 8.6 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 @@ -167,7 +166,6 @@ 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. -.VE 8.6 .TP \fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? . @@ -236,7 +234,7 @@ attempts are silently ignored. This is needed to maintain the consistency of the underlying interpreter's state. .RE .TP -\fBinterp\fR \fBdelete \fR?\fIpath ...?\fR +\fBinterp\fR \fBdelete \fR?\fIpath ...\fR? . Deletes zero or more interpreters given by the optional \fIpath\fR arguments, and for each interpreter, it also deletes its slaves. The @@ -42,3 +42,7 @@ set data {1 {2 3} 4 {5 {6 7} 8}} list(n), lappend(n), split(n) .SH KEYWORDS element, join, list, separator +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/lappend.n b/doc/lappend.n index 80d075a..89b6909 100644 --- a/doc/lappend.n +++ b/doc/lappend.n @@ -22,6 +22,12 @@ and appends each of the \fIvalue\fR arguments to that list as a separate element, with spaces between elements. If \fIvarName\fR does not exist, it is created as a list with elements given by the \fIvalue\fR arguments. +.VS TIP508 +If \fIvarName\fR indicate an element that does not exist of an array that has +a default value set, list that is comprised of the default value with all the +\fIvalue\fR arguments appended as elements will be stored in the array +element. +.VE TIP508 \fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs are appended as list elements rather than raw text. This command provides a relatively efficient way to build up @@ -43,7 +49,12 @@ Using \fBlappend\fR to build up a list of numbers. 1 2 3 4 5 .CE .SH "SEE ALSO" -list(n), lindex(n), linsert(n), llength(n), lset(n), -lsort(n), lrange(n) +list(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lset(n), lsort(n) .SH KEYWORDS append, element, list, variable +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/lassign.n b/doc/lassign.n index 5620de6..67048ba 100644 --- a/doc/lassign.n +++ b/doc/lassign.n @@ -52,7 +52,9 @@ command in many shell languages like this: set ::argv [\fBlassign\fR $::argv argumentToReadOff] .CE .SH "SEE ALSO" -lindex(n), list(n), lrange(n), lset(n), set(n) +list(n), lappend(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lset(n), lsort(n) .SH KEYWORDS assign, element, list, multiple, set, variable '\"Local Variables: diff --git a/doc/library.n b/doc/library.n index 6f8f265..4dcd598 100644 --- a/doc/library.n +++ b/doc/library.n @@ -299,18 +299,13 @@ These variables are only used in the \fBtcl_endOfWord\fR, This variable contains a regular expression that is used by routines like \fBtcl_endOfWord\fR to identify whether a character is part of a word or not. If the pattern matches a character, the character is -considered to be a non-word character. On Windows platforms, spaces, -tabs, and newlines are considered non-word characters. Under Unix, -everything but numbers, letters and underscores are considered -non-word characters. +considered to be a non-word character. The default is "\\W". .TP \fBtcl_wordchars\fR This variable contains a regular expression that is used by routines like \fBtcl_endOfWord\fR to identify whether a character is part of a word or not. If the pattern matches a character, the character is -considered to be a word character. On Windows platforms, words are -comprised of any character that is not a space, tab, or newline. Under -Unix, words are comprised of numbers, letters or underscores. +considered to be a word character. The default is "\\w". .SH "SEE ALSO" env(n), info(n), re_syntax(n) .SH KEYWORDS diff --git a/doc/lindex.n b/doc/lindex.n index d5605bc..01e0d8b 100644 --- a/doc/lindex.n +++ b/doc/lindex.n @@ -13,7 +13,7 @@ .SH NAME lindex \- Retrieve an element from a list .SH SYNOPSIS -\fBlindex \fIlist ?index ...?\fR +\fBlindex \fIlist\fR ?\fIindex ...\fR? .BE .SH DESCRIPTION .PP @@ -115,8 +115,9 @@ set idx 3 \fI\(-> f\fR .CE .SH "SEE ALSO" -list(n), lappend(n), linsert(n), llength(n), lsearch(n), -lset(n), lsort(n), lrange(n), lreplace(n), +list(n), lappend(n), lassign(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lset(n), lsort(n), string(n) .SH KEYWORDS element, index, list diff --git a/doc/link.n b/doc/link.n new file mode 100644 index 0000000..7219342 --- /dev/null +++ b/doc/link.n @@ -0,0 +1,124 @@ +'\" +'\" Copyright (c) 2011-2015 Andreas Kupries +'\" Copyright (c) 2018 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH link n 0.3 TclOO "TclOO Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +link \- create link from command to method of object +.SH SYNOPSIS +.nf +package require TclOO + +\fBlink\fR \fImethodName\fR ?\fI...\fR? +\fBlink\fR \fB{\fIcommandName methodName\fB}\fR ?\fI...\fR? +.fi +.BE +.SH DESCRIPTION +The \fBlink\fR command is available within methods. It takes a series of one +or more method names (\fImethodName ...\fR) and/or pairs of command- and +method-name (\fB{\fIcommandName methodName\fB}\fR) and makes the named methods +available as commands without requiring the explicit use of the name of the +object or the \fBmy\fR command. The method does not need to exist at the time +that the link is made; if the link command is invoked when the method does not +exist, the standard \fBunknown\fR method handling system is used. +.PP +The command name under which the method becomes available defaults to the +method name, except where explicitly specified through an alias/method pair. +Formally, every argument must be a list; if the list has two elements, the +first element is the name of the command to create and the second element is +the name of the method of the current object to which the command links; +otherwise, the name of the command and the name of the method are the same +string (the first element of the list). +.PP +If the name of the command is not a fully-qualified command name, it will be +resolved with respect to the current namespace (i.e., the object namespace). +.SH EXAMPLES +This demonstrates linking a single method in various ways. First it makes a +simple link, then a renamed link, then an external link. Note that the method +itself is unexported, but that it can still be called directly from outside +the class. +.PP +.CS +oo::class create ABC { + method Foo {} { + puts "This is Foo in [self]" + } + + constructor {} { + \fBlink\fR Foo + # The method foo is now directly accessible as foo here + \fBlink\fR {bar Foo} + # The method foo is now directly accessible as bar + \fBlink\fR {::ExternalCall Foo} + # The method foo is now directly accessible in the global + # namespace as ExternalCall + } + + method grill {} { + puts "Step 1:" + Foo + puts "Step 2:" + bar + } +} + +ABC create abc +abc grill + \fI\(-> Step 1:\fR + \fI\(-> This is foo in ::abc\fR + \fI\(-> Step 2:\fR + \fI\(-> This is foo in ::abc\fR +# Direct access via the linked command +puts "Step 3:"; ExternalCall + \fI\(-> Step 3:\fR + \fI\(-> This is foo in ::abc\fR +.CE +.PP +This example shows that multiple linked commands can be made in a call to +\fBlink\fR, and that they can handle arguments. +.PP +.CS +oo::class create Ex { + constructor {} { + \fBlink\fR a b c + # The methods a, b, and c (defined below) are all now + # directly acessible within methods under their own names. + } + + method a {} { + puts "This is a" + } + method b {x} { + puts "This is b($x)" + } + method c {y z} { + puts "This is c($y,$z)" + } + + method call {p q r} { + a + b $p + c $q $r + } +} + +set o [Ex new] +$o 3 5 7 + \fI\(-> This is a\fR + \fI\(-> This is b(3)\fR + \fI\(-> This is c(5,7)\fR +.CE +.SH "SEE ALSO" +interp(n), my(n), oo::class(n), oo::define(n) +.SH KEYWORDS +command, method, object +.\" Local Variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/linsert.n b/doc/linsert.n index 91db726..3179256 100644 --- a/doc/linsert.n +++ b/doc/linsert.n @@ -45,8 +45,9 @@ set newList [\fBlinsert\fR $midList end-1 lazy] set newerList [\fBlinsert\fR [\fBlinsert\fR $oldList end-1 quick] 1 lazy] .CE .SH "SEE ALSO" -list(n), lappend(n), lindex(n), llength(n), lsearch(n), -lset(n), lsort(n), lrange(n), lreplace(n), +list(n), lappend(n), lassign(n), lindex(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lset(n), lsort(n), string(n) .SH KEYWORDS element, insert, list @@ -46,9 +46,9 @@ while \fBconcat\fR with the same arguments will return \fBa b c d e f {g h}\fR .CE .SH "SEE ALSO" -lappend(n), lindex(n), linsert(n), llength(n), lrange(n), -lrepeat(n), -lreplace(n), lsearch(n), lset(n), lsort(n) +lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lset(n), lsort(n) .SH KEYWORDS element, list, quoting '\"Local Variables: diff --git a/doc/llength.n b/doc/llength.n index 79f93c0..26824a0 100644 --- a/doc/llength.n +++ b/doc/llength.n @@ -49,7 +49,12 @@ An empty list is not necessarily an empty string: 1,0 .CE .SH "SEE ALSO" -list(n), lappend(n), lindex(n), linsert(n), lsearch(n), -lset(n), lsort(n), lrange(n), lreplace(n) +list(n), lappend(n), lassign(n), lindex(n), linsert(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lset(n), lsort(n) .SH KEYWORDS element, list, length +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: @@ -77,7 +77,10 @@ set prefix [\fBlmap\fR x $values {expr { # The value of prefix is "8 7 6 5 4" .CE .SH "SEE ALSO" -break(n), continue(n), for(n), foreach(n), while(n) +break(n), continue(n), for(n), foreach(n), while(n), +list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lset(n), lsort(n) .SH KEYWORDS foreach, iteration, list, loop, map '\" Local Variables: diff --git a/doc/lpop.n b/doc/lpop.n new file mode 100644 index 0000000..631bc58 --- /dev/null +++ b/doc/lpop.n @@ -0,0 +1,97 @@ +'\" +'\" Copyright (c) 2018 by Peter Spjuth. All rights reserved. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH lpop n 8.7 Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +lpop \- Get and remove an element in a list +.SH SYNOPSIS +\fBlpop \fIvarName ?index ...?\fR +.BE +.SH DESCRIPTION +.PP +The \fBlpop\fR command accepts a parameter, \fIvarName\fR, which +it interprets as the name of a variable containing a Tcl list. +It also accepts one or more \fIindices\fR into +the list. If no indices are presented, it defaults to "end". +.PP +When presented with a single index, the \fBlpop\fR command +addresses the \fIindex\fR'th element in it, removes if from the list +and returns the element. +.PP +If \fIindex\fR is negative or greater or equal than the number +of elements in \fI$varName\fR, then an error occurs. +.PP +The interpretation of each simple \fIindex\fR value is the same as +for the command \fBstring index\fR, supporting simple index +arithmetic and indices relative to the end of the list. +.PP +If additional \fIindex\fR arguments are supplied, then each argument is +used in turn to address an element within a sublist designated +by the previous indexing operation, +allowing the script to remove elements in sublists. +The command, +.PP +.CS +\fBlpop\fR a 1 2 +.CE +.PP +gets and removes element 2 of sublist 1. +.PP +.SH EXAMPLES +.PP +In each of these examples, the initial value of \fIx\fR is: +.PP +.CS +set x [list [list a b c] [list d e f] [list g h i]] + \fI\(-> {a b c} {d e f} {g h i}\fR +.CE +.PP +The indicated value becomes the new value of \fIx\fR +(except in the last case, which is an error which leaves the value of +\fIx\fR unchanged.) +.PP +.CS +\fBlpop\fR x 0 + \fI\(-> {d e f} {g h i}\fR +\fBlpop\fR x 2 + \fI\(-> {a b c} {d e f}\fR +\fBlpop\fR x end + \fI\(-> {a b c} {d e f}\fR +\fBlpop\fR x end-1 + \fI\(-> {a b c} {g h i}\fR +\fBlpop\fR x 2 1 + \fI\(-> {a b c} {d e f} {g i}\fR +\fBlpop\fR x 2 3 j + \fI\(-> list index out of range\fR +.CE +.PP +In the following examples, the initial value of \fIx\fR is: +.PP +.CS +set x [list [list [list a b] [list c d]] \e + [list [list e f] [list g h]]] + \fI\(-> {{a b} {c d}} {{e f} {g h}}\fR +.CE +.PP +The indicated value becomes the new value of \fIx\fR. +.PP +.CS +\fBlpop\fR x 1 1 0 + \fI\(-> {{a b} {c d}} {{e f} h}\fR +.CE +.SH "SEE ALSO" +list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lset(n), lsort(n), +string(n) +.SH KEYWORDS +element, index, list, remove, pop, stack, queue +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/lrange.n b/doc/lrange.n index ffa6dba..0d4b261 100644 --- a/doc/lrange.n +++ b/doc/lrange.n @@ -71,8 +71,13 @@ elements to {elements to} .CE .SH "SEE ALSO" -list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), -lset(n), lreplace(n), lsort(n), +list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lset(n), lsort(n), string(n) .SH KEYWORDS element, list, range, sublist +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/lremove.n b/doc/lremove.n new file mode 100644 index 0000000..59d261b --- /dev/null +++ b/doc/lremove.n @@ -0,0 +1,57 @@ +'\" +'\" Copyright (c) 2019 Donal K. Fellows. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH lremove n 8.7 Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +lremove \- Remove elements from a list by index +.SH SYNOPSIS +\fBlremove \fIlist\fR ?\fIindex ...\fR? +.BE +.SH DESCRIPTION +.PP +\fBlremove\fR returns a new list formed by simultaneously removing zero or +more elements of \fIlist\fR at each of the indices given by an arbirary number +of \fIindex\fR arguments. The indices may be in any order and may be repeated; +the element at index will only be removed once. The index values are +interpreted the same as index values for the command \fBstring index\fR, +supporting simple index arithmetic and indices relative to the end of the +list. 0 refers to the first element of the list, and \fBend\fR refers to the +last element of the list. +.SH EXAMPLES +.PP +Removing the third element of a list: +.PP +.CS +% \fBlremove\fR {a b c d e} 2 +a b d e +.CE +.PP +Removing two elements from a list: +.PP +.CS +% \fBlremove\fR {a b c d e} end-1 1 +a c e +.CE +.PP +Removing the same element indicated in two different ways: +.PP +.CS +% \fBlremove\fR {a b c d e} 2 end-2 +a b d e +.CE +.SH "SEE ALSO" +list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lset(n), lsort(n) +.SH KEYWORDS +element, list, remove +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/lrepeat.n b/doc/lrepeat.n index f92792e..2e17f9c 100644 --- a/doc/lrepeat.n +++ b/doc/lrepeat.n @@ -32,7 +32,12 @@ is identical to \fBlist element ...\fR. \fI\(-> {a a} b c {a a} b c {a a} b c\fR .CE .SH "SEE ALSO" -list(n), lappend(n), linsert(n), llength(n), lset(n) - +list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lreplace(n), +lreverse(n), lsearch(n), lset(n), lsort(n) .SH KEYWORDS element, index, list +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/lreplace.n b/doc/lreplace.n index 32b7356..bc9d7ca 100644 --- a/doc/lreplace.n +++ b/doc/lreplace.n @@ -95,8 +95,9 @@ a b c d e f g h i .CE .VE TIP505 .SH "SEE ALSO" -list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), -lset(n), lrange(n), lsort(n), +list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), +lreverse(n), lsearch(n), lset(n), lsort(n), string(n) .SH KEYWORDS element, list, replace diff --git a/doc/lreverse.n b/doc/lreverse.n index 4c2f762..2ed496a 100644 --- a/doc/lreverse.n +++ b/doc/lreverse.n @@ -25,8 +25,9 @@ input list, \fIlist\fR, except with the elements in the reverse order. \fI\(-> f e {c d} b a\fR .CE .SH "SEE ALSO" -list(n), lsearch(n), lsort(n) - +list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lsearch(n), lset(n), lsort(n) .SH KEYWORDS element, list, reverse '\" Local Variables: diff --git a/doc/lsearch.n b/doc/lsearch.n index efe1792..c5dc98f 100644 --- a/doc/lsearch.n +++ b/doc/lsearch.n @@ -135,7 +135,6 @@ The list elements are sorted in increasing order. This option is only meaningful when used with \fB\-sorted\fR. .TP \fB\-bisect\fR -.VS 8.6 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 @@ -143,12 +142,24 @@ than or equal to the pattern is returned. If the pattern is before the first element or the list is empty, -1 is returned. This option implies \fB\-sorted\fR and cannot be used with either \fB\-all\fR or \fB\-not\fR. -.VE 8.6 .SS "NESTED LIST OPTIONS" .PP These options are used to search lists of lists. They may be used with any other options. .TP +\fB\-stride\0\fIstrideLength\fR +. +If this option is specified, the list is treated as consisting of +groups of \fIstrideLength\fR elements and the groups are searched by +either their first element or, if the \fB\-index\fR option is used, +by the element within each group given by the first index passed to +\fB\-index\fR (which is then ignored by \fB\-index\fR). The resulting +index always points to the first element in a group. +.PP +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. +.TP \fB\-index\fR\0\fIindexList\fR . This option is designed for use when searching within nested lists. @@ -209,9 +220,18 @@ It is also possible to search inside elements: \fBlsearch\fR -index 1 -all -inline {{a abc} {b bcd} {c cde}} *bc* \fI\(-> {a abc} {b bcd}\fR .CE +.PP +The same thing for a flattened list: +.PP +.CS +\fBlsearch\fR -stride 2 -index 1 -all -inline {a abc b bcd c cde} *bc* + \fI\(-> {a abc b bcd}\fR +.CE .SH "SEE ALSO" -foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n), -lset(n), lsort(n), lrange(n), lreplace(n), +foreach(n), +list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lset(n), lsort(n), string(n) .SH KEYWORDS binary search, linear search, @@ -136,8 +136,9 @@ The indicated return value also becomes the new value of \fIx\fR. \fI\(-> {{a b} {c d}} {{e f} {j h}}\fR .CE .SH "SEE ALSO" -list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), -lsort(n), lrange(n), lreplace(n), +list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lsort(n) string(n) .SH KEYWORDS element, index, list, replace, set diff --git a/doc/lsort.n b/doc/lsort.n index c3245b2..2018e30 100644 --- a/doc/lsort.n +++ b/doc/lsort.n @@ -221,7 +221,6 @@ Sorting using indices: {e 1} {d 2} { c 3} {b 4} {a 5} .CE .PP -.VS 8.6 Sorting a dictionary: .PP .CS @@ -239,7 +238,6 @@ Sorting using striding and multiple indices: {{Bob Smith} 25 Audi {Jane Doe} 40 Ford} {{Jane Doe} 40 Ford {Bob Smith} 25 Audi} .CE -.VE 8.6 .PP Stripping duplicate values using sorting: .PP @@ -266,8 +264,9 @@ More complex sorting using a comparison function: {1 dingo} {2 banana} {0x2 carrot} {3 apple} .CE .SH "SEE ALSO" -list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), -lset(n), lrange(n), lreplace(n) +list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lset(n) .SH KEYWORDS element, list, order, sort '\" Local Variables: diff --git a/doc/mathfunc.n b/doc/mathfunc.n index 7233d46..375d867 100644 --- a/doc/mathfunc.n +++ b/doc/mathfunc.n @@ -47,8 +47,24 @@ package require \fBTcl 8.5\fR .br \fB::tcl::mathfunc::int\fR \fIarg\fR .br +.VS "8.7, TIP 521" +\fB::tcl::mathfunc::isfinite\fR \fIarg\fR +.br +\fB::tcl::mathfunc::isinf\fR \fIarg\fR +.br +\fB::tcl::mathfunc::isnan\fR \fIarg\fR +.br +\fB::tcl::mathfunc::isnormal\fR \fIarg\fR +.VE "8.7, TIP 521" +.br \fB::tcl::mathfunc::isqrt\fR \fIarg\fR .br +.VS "8.7, TIP 521" +\fB::tcl::mathfunc::issubnormal\fR \fIarg\fR +.br +\fB::tcl::mathfunc::isunordered\fR \fIx y\fR +.VE "8.7, TIP 521" +.br \fB::tcl::mathfunc::log\fR \fIarg\fR .br \fB::tcl::mathfunc::log10\fR \fIarg\fR @@ -92,15 +108,17 @@ directly. Tcl supports the following mathematical functions in expressions, all of which work solely with floating-point numbers unless otherwise noted: .DS -.ta 3c 6c 9c +.ta 3.2c 6.4c 9.6c \fBabs\fR \fBacos\fR \fBasin\fR \fBatan\fR \fBatan2\fR \fBbool\fR \fBceil\fR \fBcos\fR \fBcosh\fR \fBdouble\fR \fBentier\fR \fBexp\fR \fBfloor\fR \fBfmod\fR \fBhypot\fR \fBint\fR -\fBisqrt\fR \fBlog\fR \fBlog10\fR \fBmax\fR -\fBmin\fR \fBpow\fR \fBrand\fR \fBround\fR -\fBsin\fR \fBsinh\fR \fBsqrt\fR \fBsrand\fR -\fBtan\fR \fBtanh\fR \fBwide\fR +\fBisfinite\fR \fBisinf\fR \fBisnan\fR \fBisnormal\fR +\fBisqrt\fR \fBissubnormal\fR \fBisunordered\fR \fBlog\fR +\fBlog10\fR \fBmax\fR \fBmin\fR \fBpow\fR +\fBrand\fR \fBround\fR \fBsin\fR \fBsinh\fR +\fBsqrt\fR \fBsrand\fR \fBtan\fR \fBtanh\fR +\fBwide\fR .DE .PP In addition to these predefined functions, applications may @@ -209,6 +227,34 @@ to the machine word size are returned as an integer value. For reference, the number of bytes in the machine word are stored in the \fBwordSize\fR element of the \fBtcl_platform\fR array. .TP +\fBisfinite \fIarg\fR +.VS "8.7, TIP 521" +Returns 1 if the floating-point number \fIarg\fR is finite. That is, if it is +zero, subnormal, or normal. Returns 0 if the number is infinite or NaN. Throws +an error if \fIarg\fR cannot be promoted to a floating-point value. +.VE "8.7, TIP 521" +.TP +\fBisinf \fIarg\fR +.VS "8.7, TIP 521" +Returns 1 if the floating-point number \fIarg\fR is infinite. Returns 0 if the +number is finite or NaN. Throws an error if \fIarg\fR cannot be promoted to a +floating-point value. +.VE "8.7, TIP 521" +.TP +\fBisnan \fIarg\fR +.VS "8.7, TIP 521" +Returns 1 if the floating-point number \fIarg\fR is Not-a-Number. Returns 0 if +the number is finite or infinite. Throws an error if \fIarg\fR cannot be +promoted to a floating-point value. +.VE "8.7, TIP 521" +.TP +\fBisnormal \fIarg\fR +.VS "8.7, TIP 521" +Returns 1 if the floating-point number \fIarg\fR is normal. Returns 0 if the +number is zero, subnormal, infinite or NaN. Throws an error if \fIarg\fR +cannot be promoted to a floating-point value. +.VE "8.7, TIP 521" +.TP \fBisqrt \fIarg\fR . Computes the integer part of the square root of \fIarg\fR. \fIArg\fR must be @@ -216,6 +262,23 @@ a positive value, either an integer or a floating point number. Unlike \fBsqrt\fR, which is limited to the precision of a floating point number, \fIisqrt\fR will return a result of arbitrary precision. .TP +\fBissubnormal \fIarg\fR +.VS "8.7, TIP 521" +Returns 1 if the floating-point number \fIarg\fR is subnormal, i.e., the +result of gradual underflow. Returns 0 if the number is zero, normal, infinite +or NaN. Throws an error if \fIarg\fR cannot be promoted to a floating-point +value. +.VE "8.7, TIP 521" +.TP +\fBisunordered \fIx y\fR +.VS "8.7, TIP 521" +Returns 1 if \fIx\fR and \fIy\fR cannot be compared for ordering, that is, if +either one is NaN. Returns 0 if both values can be ordered, that is, if they +are both chosen from among the set of zero, subnormal, normal and infinite +values. Throws an error if either \fIx\fR or \fIy\fR cannot be promoted to a +floating-point value. +.VE "8.7, TIP 521" +.TP \fBlog \fIarg\fR . Returns the natural logarithm of \fIarg\fR. \fIArg\fR must be a @@ -292,12 +355,12 @@ The argument may be any numeric value. The integer part of \fIarg\fR is determined, and then the low order 64 bits of that integer value are returned as an integer value. .SH "SEE ALSO" -expr(n), mathop(n), namespace(n) +expr(n), fpclassify(n), mathop(n), namespace(n) .SH "COPYRIGHT" .nf -Copyright (c) 1993 The Regents of the University of California. -Copyright (c) 1994-2000 Sun Microsystems Incorporated. -Copyright (c) 2005, 2006 by Kevin B. Kenny <kennykb@acm.org>. +Copyright \(co 1993 The Regents of the University of California. +Copyright \(co 1994-2000 Sun Microsystems Incorporated. +Copyright \(co 2005, 2006 by Kevin B. Kenny <kennykb@acm.org>. .fi '\" Local Variables: '\" mode: nroff diff --git a/doc/mathop.n b/doc/mathop.n index 84cf308..1c70e95 100644 --- a/doc/mathop.n +++ b/doc/mathop.n @@ -55,6 +55,16 @@ package require \fBTcl 8.5\fR .br \fB::tcl::mathop::ne\fR \fIarg arg\fR .br +.VS "8.7, TIP461" +\fB::tcl::mathop::lt\fR ?\fIarg\fR ...? +.br +\fB::tcl::mathop::le\fR ?\fIarg\fR ...? +.br +\fB::tcl::mathop::gt\fR ?\fIarg\fR ...? +.br +\fB::tcl::mathop::ge\fR ?\fIarg\fR ...? +.VE "8.7, TIP461" +.br \fB::tcl::mathop::in\fR \fIarg list\fR .br \fB::tcl::mathop::ni\fR \fIarg list\fR @@ -76,7 +86,8 @@ The following operator commands are supported: \fB/\fR \fB%\fR \fB**\fR \fB&\fR \fB|\fR \fB^\fR \fB>>\fR \fB<<\fR \fB==\fR \fBeq\fR \fB!=\fR \fBne\fR \fB<\fR \fB<=\fR \fB>\fR -\fB>=\fR \fBin\fR \fBni\fR +\fB>=\fR \fBin\fR \fBni\fR \fBlt\fR \fBle\fR +\fBgt\fR \fBge\fR .DE .SS "MATHEMATICAL OPERATORS" .PP @@ -192,8 +203,8 @@ after the first having to be strictly more than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the -arguments are numeric but should be compared as strings, the \fBstring -compare\fR command should be used instead. +arguments are numeric but should be compared as strings, the \fBlt\fR +operator or the \fBstring compare\fR command should be used instead. .TP \fB<=\fR ?\fIarg\fR ...? . @@ -202,8 +213,8 @@ after the first having to be equal to or more than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the -arguments are numeric but should be compared as strings, the \fBstring -compare\fR command should be used instead. +arguments are numeric but should be compared as strings, the \fBle\fR +operator or the \fBstring compare\fR command should be used instead. .TP \fB>\fR ?\fIarg\fR ...? . @@ -212,8 +223,8 @@ after the first having to be strictly less than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the -arguments are numeric but should be compared as strings, the \fBstring -compare\fR command should be used instead. +arguments are numeric but should be compared as strings, the \fBgt\fR +operator or the \fBstring compare\fR command should be used instead. .TP \fB>=\fR ?\fIarg\fR ...? . @@ -222,8 +233,40 @@ after the first having to be equal to or less than the one preceding it. Comparisons are performed preferentially on the numeric values, and are otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the -arguments are numeric but should be compared as strings, the \fBstring -compare\fR command should be used instead. +arguments are numeric but should be compared as strings, the \fBge\fR +operator or the \fBstring compare\fR command should be used instead. +.TP +\fBlt\fR ?\fIarg\fR ...? +.VS "8.7, TIP461" +Returns whether the arbitrarily-many arguments are ordered, with each argument +after the first having to be strictly more than the one preceding it. +Comparisons are performed using UNICODE string comparison. If fewer than two +arguments are present, this operation always returns a true value. +.VE "8.7, TIP461" +.TP +\fBle\fR ?\fIarg\fR ...? +.VS "8.7, TIP461" +Returns whether the arbitrarily-many arguments are ordered, with each argument +after the first having to be equal to or strictly more than the one preceding it. +Comparisons are performed using UNICODE string comparison. If fewer than two +arguments are present, this operation always returns a true value. +.VE "8.7, TIP461" +.TP +\fBgt\fR ?\fIarg\fR ...? +.VS "8.7, TIP461" +Returns whether the arbitrarily-many arguments are ordered, with each argument +after the first having to be strictly less than the one preceding it. +Comparisons are performed using UNICODE string comparison. If fewer than two +arguments are present, this operation always returns a true value. +.VE "8.7, TIP461" +.TP +\fBge\fR ?\fIarg\fR ...? +.VS "8.7, TIP461" +Returns whether the arbitrarily-many arguments are ordered, with each argument +after the first having to be equal to or strictly less than the one preceding it. +Comparisons are performed using UNICODE string comparison. If fewer than two +arguments are present, this operation always returns a true value. +.VE "8.7, TIP461" .SS "BIT-WISE OPERATORS" .PP The behaviors of the bit-wise operator commands (all of which only operate on @@ -299,8 +342,12 @@ set gotIt [\fBin\fR 3 $list] \fI# Test to see if a value is within some defined range\fR set inRange [\fB<=\fR 1 $x 5] -\fI# Test to see if a list is sorted\fR +\fI# Test to see if a list is numerically sorted\fR set sorted [\fB<=\fR {*}$list] + +\fI# Test to see if a list is lexically sorted\fR +set alphaList {a b c d e f} +set sorted [\fBle\fR {*}$alphaList] .CE .SH "SEE ALSO" expr(n), mathfunc(n), namespace(n) diff --git a/doc/msgcat.n b/doc/msgcat.n index 2fc1eee..3d87ffd 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -11,9 +11,9 @@ .SH NAME msgcat \- Tcl message catalog .SH SYNOPSIS -\fBpackage require Tcl 8.5\fR +\fBpackage require Tcl 8.7\fR .sp -\fBpackage require msgcat 1.6\fR +\fBpackage require msgcat 1.7\fR .sp \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? .sp @@ -23,9 +23,15 @@ msgcat \- Tcl message catalog \fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? \fIsrc-string\fR .VE "TIP 412" .sp +.VS "TIP 490" +\fB::msgcat::mcpackagenamespaceget\fR +.VE "TIP 490" +.sp \fB::msgcat::mclocale \fR?\fInewLocale\fR? .sp -\fB::msgcat::mcpreferences\fR +.VS "TIP 499" +\fB::msgcat::mcpreferences\fR ?\fIlocale preference\fR? ... +.VE "TIP 499" .sp .VS "TIP 412" \fB::msgcat::mcloadedlocales subcommand\fR ?\fIlocale\fR? @@ -50,6 +56,10 @@ msgcat \- Tcl message catalog .sp \fB::msgcat::mcforgetpackage\fR .VE "TIP 412" +.sp +.VS "TIP 499" +\fB::msgcat::mcutil subcommand\fR ?\fIlocale\fR? +.VS "TIP 499" .BE .SH DESCRIPTION .PP @@ -71,6 +81,11 @@ In \fBmsgcat\fR, there is a global locale initialized by the system locale of th 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. +.PP +.VS tip490 +Object oriented programming is supported by the use of a package namespace. +.VE tip490 +.PP .SH COMMANDS .TP \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? @@ -95,6 +110,17 @@ 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" +.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. +.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. +.RE +.PP .TP \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR? . @@ -102,29 +128,69 @@ 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" .TP -\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? \fIsrc-string\fR +\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? ?\fB-namespace\fR \fInamespace\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. .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). -.RE +.PP .VE "TIP 412" +.VS "TIP 490" +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" +.TP +\fB::msgcat::mcpackagenamespaceget\fR +. +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: +.CS +proc ::tooltip::tooltip {widget message} { + ... + set messagenamespace [uplevel 1 {::msgcat::mcpackagenamespaceget}] + ... + bind $widget [list ::tooltip::show $widget $messagenamespace $message] +} + +proc ::tooltip::show {widget messagenamespace message} { + ... + set message [::msgcat::mcn $messagenamespace $message] + ... +} +.CE +.RE +.PP +.VE "TIP 490" .TP \fB::msgcat::mclocale \fR?\fInewLocale\fR? . -This function sets the locale to \fInewLocale\fR. If \fInewLocale\fR -is omitted, the current locale is returned, otherwise the current locale -is set to \fInewLocale\fR. msgcat stores and compares the locale in a +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. +.PP +The same result may be acheved by \fB::msgcat::mcpreferences\fR {*}[\fB::msgcat::mcutil getpreferences\fR \fInewLocale\fR]. +.PP +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. The initial locale is determined by the locale specified in the user's environment. See \fBLOCALE SPECIFICATION\fR below for a description of the locale string format. -.RS .PP .VS "TIP 412" If the locale is set, the preference list of locales is evaluated. @@ -132,16 +198,26 @@ Locales in this list are loaded now, if not jet loaded. .VE "TIP 412" .RE .TP -\fB::msgcat::mcpreferences\fR +\fB::msgcat::mcpreferences\fR ?\fIlocale preference\fR? ... . -Returns an ordered list of the locales preferred by -the user, based on the user's language specification. -The list is ordered from most specific to least -preference. The list is derived from the current -locale set in msgcat by \fB::msgcat::mclocale\fR, and -cannot be set independently. For example, if the -current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR -returns \fB{en_us_funky en_us en {}}\fR. +Without arguments, returns an ordered list of the locales preferred by +the user. +The list is ordered from most specific to least preference. +.PP +.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. +.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: +.CS +::msgcat::mcpreferences fr en {} +.CE +.RE +.PP +.VS "TIP 499" .TP \fB::msgcat:mcloadedlocales subcommand\fR ?\fIlocale\fR? . @@ -232,6 +308,22 @@ Note that this routine is only called if the concerned package did not set a pac The calling package clears all its state within the \fBmsgcat\fR package including all settings and translations. .VE "TIP 412" .PP +.VS "TIP 499" +.TP +\fB::msgcat::mcutil getpreferences\fR \fIlocale\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: +.CS +% concat [lrange [msgcat::mcutil getpreferences fr_CH] 0 end-1] [msgcat::mcutil getpreferences de_CH] +fr_ch fr de_ch de {} +.CE +.TP +\fB::msgcat::mcutil getsystemlocale\fR +. +The system locale is returned as described by the section \fBLOCALE SPECIFICATION\fR. +.VE "TIP 499" +.PP .SH "LOCALE SPECIFICATION" .PP The locale is specified to \fBmsgcat\fR by a locale string @@ -437,7 +529,7 @@ formatting substitution is done directly. # human-oriented versions by \fBmsgcat::mcset\fR .CE .VS "TIP 412" -.SH Package private locale +.SH "PACKAGE PRIVATE LOCALE" .PP 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 @@ -461,10 +553,22 @@ This command may cause the load of locales. . Return the package private locale or the global locale, if no package private locale is set. .TP -\fB::msgcat::mcpackagelocale preferences\fR +\fB::msgcat::mcpackagelocale preferences\fR ?\fIlocale preference\fR? ... . -Return the package private preferences or the global preferences, +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. +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 .TP \fB::msgcat::mcpackagelocale loaded\fR . @@ -488,7 +592,7 @@ Returns true, if the given locale is loaded for the package. . Clear any loaded locales of the package not present in the package preferences. .PP -.SH Changing package options +.SH "CHANGING PACKAGE OPTIONS" .PP Each package using msgcat has a set of options within \fBmsgcat\fR. The package options are described in the next sectionPackage options. @@ -563,7 +667,7 @@ A generic unknown handler is used if set to the empty string. This consists in r See section \fBcallback invocation\fR below. The appended arguments are identical to \fB::msgcat::mcunknown\fR. .RE -.SS Callback invocation +.SH "Callback invocation" A package may decide to register one or multiple callbacks, as described above. .PP Callbacks are invoked, if: @@ -577,7 +681,54 @@ Callbacks are invoked, if: 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 -.SS Examples +.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: +.PP +.TP +\fB1) In class definition script\fR +. +\fBmsgcat\fR command is called within a class definition script. +.CS +namespace eval ::N2 { + mcload $dir/msgs + oo::class create C1 {puts [mc Hi!]} +} +.CE +.PP +.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. +.CS +namespace eval ::N3Class { + mcload $dir/msgs + oo::class create C1 + oo::define C1 method m1 { + puts [mc Hi!] + } +} +.CE +.PP +.TP +\fB3) method defined in a classless object\fR +. +\fBmsgcat\fR command is called from a method of a classless object. +.CS +namespace eval ::N4 { + mcload $dir/msgs + oo::object create O1 + oo::objdefine O1 method m1 {} { + puts [mc Hi!] + } +} +.CE +.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: .CS @@ -643,9 +794,9 @@ proc ::tcl::clock::LocalizeFormat { locale format } { .PP The message catalog code was developed by Mark Harrison. .SH "SEE ALSO" -format(n), scan(n), namespace(n), package(n) +format(n), scan(n), namespace(n), package(n), oo::class(n), oo::object .SH KEYWORDS -internationalization, i18n, localization, l10n, message, text, translation +internationalization, i18n, localization, l10n, message, text, translation, class, object .\" Local Variables: .\" mode: nroff .\" End: @@ -9,25 +9,45 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -my \- invoke any method of current object +my, myclass \- invoke any method of current object or its class .SH SYNOPSIS .nf package require TclOO \fBmy\fI methodName\fR ?\fIarg ...\fR? +\fBmyclass\fI methodName\fR ?\fIarg ...\fR? .fi .BE .SH DESCRIPTION .PP -The \fBmy\fR command is used to allow methods of objects to invoke any method -of the object (or its class). In particular, the set of valid values for +The \fBmy\fR command is used to allow methods of objects to invoke methods +of the object (or its class), +.VS TIP478 +and the \fBmyclass\fR command is used to allow methods of objects to invoke +methods of the current class of the object \fIas an object\fR. +.VE TIP478 +In particular, the set of valid values for \fImethodName\fR is the set of all methods supported by an object and its -superclasses, including those that are not exported. The object upon which the -method is invoked is always the one that is the current context of the method -(i.e. the object that is returned by \fBself object\fR) from which the -\fBmy\fR command is invoked. +superclasses, including those that are not exported +.VS TIP500 +and private methods of the object or class when used within another method +defined by that object or class. +.VE TIP500 .PP -Each object has its own \fBmy\fR command, contained in its instance namespace. +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. +.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 +the \fBmyclass\fR command is contained in initially. As with \fBmy\fR, the +link remains even if the command is renamed into another namespace, and +defaults to being the manufacturing class of the current object. +.VE TIP478 +.PP +Each object has its own \fBmy\fR and \fBmyclass\fR commands, contained in its +instance namespace. .SH EXAMPLES .PP This example shows basic use of \fBmy\fR to use the \fBvariables\fR method of @@ -40,16 +60,71 @@ oo::class create c { puts [incr counter] } } + c create o o count \fI\(-> prints "1"\fR o count \fI\(-> prints "2"\fR o count \fI\(-> prints "3"\fR .CE +.PP +This example shows how you can use \fBmy\fR to make callbacks to private +methods from outside the object (from a \fBtrace\fR), using +\fBnamespace code\fR to enter the correct context. (See the \fBcallback\fR +command for the recommended way of doing this.) +.PP +.CS +oo::class create HasCallback { + method makeCallback {} { + return [namespace code { + \fBmy\fR Callback + }] + } + + method Callback {args} { + puts "callback: $args" + } +} + +set o [HasCallback new] +trace add variable xyz write [$o makeCallback] +set xyz "called" \fI\(-> prints "callback: xyz {} write"\fR +.CE +.PP +.VS TIP478 +This example shows how to access a private method of a class from an instance +of that class. (See the \fBclassmethod\fR declaration in \fBoo::define\fR for +a higher level interface for doing this.) +.PP +.CS +oo::class create CountedSteps { + self { + variable count + method Count {} { + return [incr count] + } + } + method advanceTwice {} { + puts "in [self] step A: [\fBmyclass\fR Count]" + puts "in [self] step B: [\fBmyclass\fR Count]" + } +} + +CountedSteps create x +CountedSteps create y +x advanceTwice \fI\(-> prints "in ::x step A: 1"\fR + \fI\(-> prints "in ::x step B: 2"\fR +y advanceTwice \fI\(-> prints "in ::y step A: 3"\fR + \fI\(-> prints "in ::y step B: 4"\fR +x advanceTwice \fI\(-> prints "in ::x step A: 5"\fR + \fI\(-> prints "in ::x step B: 6"\fR +y advanceTwice \fI\(-> prints "in ::y step A: 7"\fR + \fI\(-> prints "in ::y step B: 8"\fR +.CE +.VE TIP478 .SH "SEE ALSO" next(n), oo::object(n), self(n) .SH KEYWORDS method, method visibility, object, private method, public method - .\" Local variables: .\" mode: nroff .\" fill-column: 78 diff --git a/doc/namespace.n b/doc/namespace.n index b0b6e25..3196cac 100644 --- a/doc/namespace.n +++ b/doc/namespace.n @@ -788,12 +788,10 @@ name. Note that when this option is non-empty and the will be exactly those words that have mappings in the dictionary. .TP \fB\-parameters\fR -.VS 8.6 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. -.VE 8.6 .TP \fB\-prefixes\fR . @@ -943,7 +941,6 @@ Remove all imported commands from the current namespace: namespace forget {*}[namespace import] .CE .PP -.VS 8.6 Create an ensemble for simple working with numbers, using the \fB\-parameters\fR option to allow the operator to be put between the first and second arguments. @@ -959,7 +956,6 @@ and second arguments. # In use, the ensemble works like this: puts [do 1 plus [do 9 minus 7]] .CE -.VE 8.6 .SH "SEE ALSO" interp(n), upvar(n), variable(n) .SH KEYWORDS @@ -112,6 +112,7 @@ oo::class create theSuperclass { puts "in the superclass, args = $args" } } + oo::class create theSubclass { superclass theSuperclass method example {args} { @@ -121,6 +122,7 @@ oo::class create theSubclass { puts "after chaining from subclass" } } + theSubclass create obj oo::objdefine obj method example args { puts "per-object method, args = $args" @@ -167,6 +169,7 @@ oo::class create cache { \fI# Compute value, insert into cache, and return it\fR return [set ValueCache($key) [\fBnext\fR {*}$args]] } + method flushCache {} { my variable ValueCache unset ValueCache @@ -178,10 +181,12 @@ oo::class create cache { oo::object create demo oo::objdefine demo { mixin cache + method compute {a b c} { after 3000 \fI;# Simulate deep thought\fR return [expr {$a + $b * $c}] } + method compute2 {a b c} { after 3000 \fI;# Simulate deep thought\fR return [expr {$a * $b + $c}] @@ -166,8 +166,9 @@ is opened and initialized in a platform-dependent manner. Acceptable values for the \fIfileName\fR to use to open a serial port are described in the PORTABILITY ISSUES section. .PP -The \fBfconfigure\fR command can be used to query and set additional -configuration options specific to serial ports (where supported): +The \fBchan configure\fR and \fBfconfigure\fR commands can be used to query +and set additional configuration options specific to serial ports (where +supported): .TP \fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR . @@ -249,6 +250,75 @@ handshake characters. Normally the operating system default should be DC1 (0x11) and DC3 (0x13) representing the ASCII standard XON and XOFF characters. .TP +\fB\-closemode\fR \fIcloseMode\fR +.VS "8.7, TIP 160" +(Windows and Unix). This option is used to query or change the close mode of +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 +. +indicates that a system default operation should be used; all serial channels +default to this. +.TP +\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 +. +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" +.TP +\fB\-inputmode\fR \fIinputMode\fR +.VS "8.7, TIP 160" +(Unix only; Windows has the equivalent option on console channels). This +option is used to query or change the input mode of the serial channel under +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 +. +indicates that normal line-oriented input should be used, with standard +terminal editing capabilities enabled. +.TP +\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 +. +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) +. +indicates that the terminal should be reset to what state it was in when the +terminal was opened. +.PP +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 +.TP +\fB\-winsize\fR +. +(Unix only; Windows has the equivalent option on console channels). This +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" +.TP \fB\-pollinterval\fR \fImsec\fR . (Windows only). This option is used to set the maximum time between @@ -275,7 +345,7 @@ In case of a serial communication error, \fBread\fR or \fBputs\fR returns a general Tcl file I/O error. \fBfconfigure\fR \fB\-lasterror\fR can be called to get a list of error details. See below for an explanation of the various error codes. -.SH "SERIAL PORT SIGNALS" +.SS "SERIAL PORT SIGNALS" .PP RS-232 is the most commonly used standard electrical interface for serial communications. A negative voltage (-3V..-12V) define a mark (on=1) bit and @@ -316,7 +386,7 @@ milliseconds. Normally a receive or transmit data signal stays at the mark (on=1) voltage until the next character is transferred. A BREAK is sometimes used to reset the communications line or change the operating mode of communications hardware. -.SH "ERROR CODES (Windows only)" +.SS "ERROR CODES (Windows only)" .PP A lot of different errors may occur during serial read operations or during event polling in background. The external device may have been switched @@ -359,7 +429,7 @@ may cause this error. \fBBREAK\fR . A BREAK condition has been detected by your UART (see above). -.SH "PORTABILITY ISSUES" +.SS "PORTABILITY ISSUES" .TP \fBWindows \fR . @@ -408,7 +478,55 @@ input, but is redirected from a file, then the above problem does not occur. See the \fBPORTABILITY ISSUES\fR section of the \fBexec\fR command for additional information not specific to command pipelines about executing applications on the various platforms -.SH "EXAMPLE" +.SH "CONSOLE CHANNELS" +.VS "8.7, TIP 160" +On Windows only, console channels (usually \fBstdin\fR or \fBstdout\fR) +support the following options: +.TP +\fB\-inputmode\fR \fIinputMode\fR +. +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 +. +indicates that normal line-oriented input should be used, with standard +console editing capabilities enabled. +.TP +\fBpassword\fR +. +indicates that non-echoing input should be used, with standard console +editing capabilitied enabled but no writing of typed characters to the +terminal (except for newlines). +.TP +\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. +.TP +\fBreset\fR (set only) +. +indicates that the console should be reset to what state it was in when the +console channel was opened. +.PP +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 +.TP +\fB\-winsize\fR +. +This option is query only. +It retrieves a two-element list with the 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 +type. +.VE "8.7, TIP 160" +.SH "EXAMPLES" .PP Open a command pipeline and catch any errors: .PP @@ -419,6 +537,22 @@ if {[catch {close $fl} err]} { puts "ls command failed: $err" } .CE +.PP +.VS "8.7, TIP 160" +Read a password securely from the user (assuming that the script is being run +interactively): +.PP +.CS +chan configure stdin \fB-inputmode password\fR +try { + chan puts -nonewline "Password: " + chan flush stdout + set thePassword [chan gets stdin] +} finally { + chan configure stdin \fB-inputmode reset\fR +} +.CE +.VE "8.7, TIP 160" .SH "SEE ALSO" file(n), close(n), filename(n), fconfigure(n), gets(n), read(n), puts(n), exec(n), pid(n), fopen(3) diff --git a/doc/package.n b/doc/package.n index a6a972f..5687480 100644 --- a/doc/package.n +++ b/doc/package.n @@ -12,6 +12,7 @@ package \- Facilities for package loading and version control .SH SYNOPSIS .nf +\fBpackage files\fR \fIpackage\fR \fBpackage forget\fR ?\fIpackage package ...\fR? \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR? \fBpackage names\fR @@ -43,6 +44,13 @@ primarily by system scripts that maintain the package database. The behavior of the \fBpackage\fR command is determined by its first argument. The following forms are permitted: .TP +\fBpackage files\fR \fIpackage\fR +. +Lists all files forming part of \fIpackage\fR. Auto-loaded files are not +included in this list, only files which were directly sourced during package +initialization. The list order corresponds with the order in which the +files were sourced. +.TP \fBpackage forget\fR ?\fIpackage package ...\fR? . Removes all information about each specified package from this interpreter, @@ -283,8 +291,8 @@ error. .PP When an interpreter is created, its initial selection mode value is set to .QW stable -unless the environment variable \fBTCL_PKG_PREFER_LATEST\fR -is set. If that environment variable is defined (with any value) then +unless the environment variable \fBTCL_PKG_PREFER_LATEST\fR is set +(to any value) or the Tcl package itself is unstable. Otherwise the initial (and permanent) selection mode value is set to .QW latest . .RE diff --git a/doc/packagens.n b/doc/packagens.n index 5bd2e67..a6eee1e 100644 --- a/doc/packagens.n +++ b/doc/packagens.n @@ -48,3 +48,7 @@ At least one \fB\-load\fR or \fB\-source\fR parameter must be given. package(n) .SH KEYWORDS auto-load, index, package, version +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: @@ -43,6 +43,9 @@ close $pipeline .SH "SEE ALSO" exec(n), open(n) - .SH KEYWORDS file, pipeline, process identifier +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/platform.n b/doc/platform.n index 5380ff4..7cb685d 100644 --- a/doc/platform.n +++ b/doc/platform.n @@ -12,7 +12,7 @@ platform \- System identification support code and utilities .SH SYNOPSIS .nf -\fBpackage require platform ?1.0.10?\fR +\fBpackage require platform\fR ?\fB1.0.10\fR? .sp \fBplatform::generic\fR \fBplatform::identify\fR diff --git a/doc/platform_shell.n b/doc/platform_shell.n index 330afa9..a9e14d0 100644 --- a/doc/platform_shell.n +++ b/doc/platform_shell.n @@ -12,7 +12,7 @@ platform::shell \- System identification support code and utilities .SH SYNOPSIS .nf -\fBpackage require platform::shell ?1.1.4?\fR +\fBpackage require platform::shell\fR ?\fB1.1.4\fR? .sp \fBplatform::shell::generic \fIshell\fR \fBplatform::shell::identify \fIshell\fR @@ -55,3 +55,7 @@ This command returns the contents of \fBtcl_platform(platform)\fR for the specified Tcl shell. .SH KEYWORDS operating system, cpu architecture, platform, architecture +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/prefix.n b/doc/prefix.n index 50aa2fb..d327a78 100644 --- a/doc/prefix.n +++ b/doc/prefix.n @@ -12,9 +12,9 @@ tcl::prefix \- facilities for prefix matching .SH SYNOPSIS .nf -\fB::tcl::prefix all\fR \fItable\fR \fIstring\fR -\fB::tcl::prefix longest\fR \fItable\fR \fIstring\fR -\fB::tcl::prefix match\fR \fI?option ...?\fR \fItable\fR \fIstring\fR +\fB::tcl::prefix all\fR \fItable string\fR +\fB::tcl::prefix longest\fR \fItable string\fR +\fB::tcl::prefix match\fR ?\fIoption ...\fR? \fItable string\fR .fi .BE .SH DESCRIPTION @@ -22,17 +22,17 @@ tcl::prefix \- facilities for prefix matching This document describes commands looking up a prefix in a list of strings. The following commands are supported: .TP -\fB::tcl::prefix all\fR \fItable\fR \fIstring\fR +\fB::tcl::prefix all\fR \fItable string\fR . Returns a list of all elements in \fItable\fR that begin with the prefix \fIstring\fR. .TP -\fB::tcl::prefix longest\fR \fItable\fR \fIstring\fR +\fB::tcl::prefix longest\fR \fItable string\fR . Returns the longest common prefix of all elements in \fItable\fR that begin with the prefix \fIstring\fR. .TP -\fB::tcl::prefix match\fR ?\fIoptions\fR? \fItable\fR \fIstring\fR +\fB::tcl::prefix match\fR ?\fIoptions\fR? \fItable string\fR . If \fIstring\fR equals one element in \fItable\fR or is a prefix to exactly one element, the matched element is returned. If not, the result depends diff --git a/doc/process.n b/doc/process.n new file mode 100644 index 0000000..165e413 --- /dev/null +++ b/doc/process.n @@ -0,0 +1,150 @@ +'\" +'\" Copyright (c) 2017 Frederic Bonnet. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH process n 8.7 Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tcl::process \- Subprocess management +.SH SYNOPSIS +\fB::tcl::process \fIoption \fR?\fIarg arg ...\fR? +.BE +.SH DESCRIPTION +.PP +This command provides a way to manage subprocesses created by the \fBopen\fR +and \fBexec\fR commands, as identified by the process identifiers (PIDs) of +those subprocesses. The legal \fIoptions\fR (which may be abbreviated) are: +.TP +\fB::tcl::process autopurge\fR ?\fIflag\fR? +. +Automatic purge facility. If \fIflag\fR is specified as a boolean value then +it activates or deactivate autopurge. In all cases it returns the current +status as a boolean value. When autopurge is active, +\fBTcl_ReapDetachedProcs\fR is called each time the \fBexec\fR command is +executed or a pipe channel created by \fBopen\fR is closed. When autopurge is +inactive, \fB::tcl::process\fR purge must be called explicitly. By default +autopurge is active. +.TP +\fB::tcl::process list\fR +. +Returns the list of subprocess PIDs. This includes all currently executing +subprocesses and all terminated subprocesses that have not yet had their +corresponding process table entries purged. +.TP +\fB::tcl::process purge\fR ?\fIpids\fR? +. +Cleans up all data associated with terminated subprocesses. If \fIpids\fR is +specified as a list of PIDs then the command only cleanup data for the matching +subprocesses if they exist, and raises an error otherwise. If a process listed is +still active, this command does nothing to that process. +.TP +\fB::tcl::process status\fR ?\fIswitches\fR? ?\fIpids\fR? +. +Returns a dictionary mapping subprocess PIDs to their respective status. If +\fIpids\fR is specified as a list of PIDs then the command only returns the +status of the matching subprocesses if they exist, and raises an error +otherwise. For active processes, the status is an empty value. For terminated +processes, the status is a list with the following format: +.QW "\fB{\fIcode\fR ?\fImsg errorCode\fR?\fB}\fR" , +where: +.RS +.TP +\fIcode\fR\0 +. +is a standard Tcl return code, i.e., \fB0\fR for TCL_OK and \fB1\fR +for TCL_ERROR, +.TP +\fImsg\fR\0 +. +is the human-readable error message, +.TP +\fIerrorCode\fR\0 +. +uses the same format as the \fBerrorCode\fR global variable +.PP +Note that \fBmsg\fR and \fBerrorCode\fR are only present for abnormally +terminated processes (i.e. those where the \fIcode\fR is nonzero). Under the +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: +.TP +\fB\-wait\fR\0 +. +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. +.TP +\fB\-\|\-\fR +. +Marks the end of switches. The argument following this one will +be treated as the first \fIarg\fR even if it starts with a \fB\-\fR. +.RE +.SH "EXAMPLES" +.PP +These show the use of \fB::tcl::process\fR. Some of the results from +\fB::tcl::process status\fR are split over multiple lines for readability. +.PP +.CS +\fB::tcl::process autopurge\fR + \fI\(-> true\fR +\fB::tcl::process autopurge\fR false + \fI\(-> false\fR + +set pid1 [exec command1 a b c | command2 d e f &] + \fI\(-> 123 456\fR +set chan [open "|command1 a b c | command2 d e f"] + \fI\(-> file123\fR +set pid2 [pid $chan] + \fI\(-> 789 1011\fR + +\fB::tcl::process list\fR + \fI\(-> 123 456 789 1011\fR + +\fB::tcl::process status\fR + \fI\(-> 123 0 + 456 {1 "child killed: write on pipe with no readers" { + CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}} + 789 {1 "child suspended: background tty read" { + CHILDSUSP 789 SIGTTIN "background tty read"}} + 1011 {}\fR + +\fB::tcl::process status\fR 123 + \fI\(-> 123 0\fR + +\fB::tcl::process status\fR 1011 + \fI\(-> 1011 {}\fR + +\fB::tcl::process status\fR -wait + \fI\(-> 123 0 + 456 {1 "child killed: write on pipe with no readers" { + CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}} + 789 {1 "child suspended: background tty read" { + CHILDSUSP 789 SIGTTIN "background tty read"}} + 1011 {1 "child process exited abnormally" { + CHILDSTATUS 1011 -1}}\fR + +\fB::tcl::process status\fR 1011 + \fI\(-> 1011 {1 "child process exited abnormally" { + CHILDSTATUS 1011 -1}}\fR + +\fB::tcl::process purge\fR +exec command1 1 2 3 & + \fI\(-> 1213\fR +\fB::tcl::process list\fR + \fI\(-> 1213\fR +.CE +.SH "SEE ALSO" +exec(n), open(n), pid(n), +Tcl_DetachPids(3), Tcl_WaitPid(3), Tcl_ReapDetachedProcs(3) +.SH "KEYWORDS" +background, child, detach, process, wait +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -96,3 +96,7 @@ close $chan file(n), fileevent(n), Tcl_StandardChannels(3) .SH KEYWORDS channel, newline, output, write +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: @@ -37,3 +37,7 @@ cd $savedDir file(n), cd(n), glob(n), filename(n) .SH KEYWORDS working directory +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/re_syntax.n b/doc/re_syntax.n index 7988071..8d732ed 100644 --- a/doc/re_syntax.n +++ b/doc/re_syntax.n @@ -293,12 +293,12 @@ treatment is as if the enclosing delimiters were .QW \fB[.\fR \& and .QW \fB.]\fR .) -For example, if \fBo\fR and \fB\*(qo\fR are the members of an +For example, if \fBo\fR and \fB\[^o]\fR are the members of an equivalence class, then .QW \fB[[=o=]]\fR , -.QW \fB[[=\*(qo=]]\fR , +.QW \fB[[=\[^o]=]]\fR , and -.QW \fB[o\*(qo]\fR \& +.QW \fB[o\[^o]]\fR \& are all synonymous. An equivalence class may not be an endpoint of a range. .RS .PP diff --git a/doc/registry.n b/doc/registry.n index ec5910c..66b2dd9 100644 --- a/doc/registry.n +++ b/doc/registry.n @@ -44,13 +44,11 @@ one of \fBHKEY_LOCAL_MACHINE\fR, \fBHKEY_USERS\fR, \fBHKEY_DYN_DATA\fR. The \fIkeypath\fR can be one or more registry key names separated by backslash (\fB\e\fR) characters. .PP -.VS 8.6 The optional \fI\-mode\fR argument indicates which registry to work with; when it is \fB\-32bit\fR the 32-bit registry will be used, and when it is \fB\-64bit\fR the 64-bit registry will be used. If this argument is omitted, the system's default registry will be the subject of the requested operation. -.VE 8.6 .PP \fIOption\fR indicates what to do with the registry key name. Any unique abbreviation for \fIoption\fR is acceptable. The valid options diff --git a/doc/regsub.n b/doc/regsub.n index a5b79de..29c118a 100644 --- a/doc/regsub.n +++ b/doc/regsub.n @@ -68,6 +68,33 @@ and sequences are handled for each substitution using the information from the corresponding match. .TP +\fB\-command\fR +.VS 8.7 +Changes the handling of \fIsubSpec\fR so that it is not treated +as a template for a substitution string and the substrings +.QW & +and +.QW \e\fIn\fR +no longer have special meaning. Instead \fIsubSpec\fR must be a +command prefix, that is, a non-empty list. The substring of \fIstring\fR +that matches \fIexp\fR, and then each substring that matches each +capturing sub-RE within \fIexp\fR are appended as additional elements +to that list. (The items appended to the list are much like what +\fBregexp\fR \fB-inline\fR would return). The completed list is then +evaluated as a Tcl command, and the result of that command is the +substitution string. Any error or exception from command evaluation +becomes an error or exception from the \fBregsub\fR command. +.RS +.PP +If \fB\-all\fR is not also given, the command callback will be invoked at most +once (exactly when the regular expression matches). If \fB\-all\fR is given, +the command callback will be invoked for each matched location, in sequence. +The exact location indices that matched are not made available to the script. +.PP +See \fBEXAMPLES\fR below for illustrative cases. +.RE +.VE 8.7 +.TP \fB\-expanded\fR . Enables use of the expanded regular expression syntax where @@ -183,6 +210,53 @@ set substitution {[format \e\e\e\eu%04x [scan "\e\e&" %c]]} set quoted [subst [string map {\en {\e\eu000a}} \e [\fBregsub\fR -all $RE $string $substitution]]] .CE +.PP +.VS 8.7 +The above operation can be done using \fBregsub \-command\fR instead, which is +often faster. (A full pre-computed \fBstring map\fR would be faster still, but +the cost of computing the map for a transformation as complex as this can be +quite large.) +.PP +.CS +# This RE is just a character class for everything "bad" +set RE {[][{};#\e\e\e$\es\eu0080-\euffff]} + +# This encodes what the RE described above matches +proc encodeChar {ch} { + # newline is handled specially since backslash-newline is a + # special sequence. + if {$ch eq "\en"} { + return "\e\eu000a" + } + # No point in writing this as a one-liner + scan $ch %c charNumber + format "\e\eu%04x" $charNumber +} + +set quoted [\fBregsub\fR -all -command $RE $string encodeChar] +.CE +.PP +Decoding a URL-encoded string using \fBregsub \-command\fR, a lambda term and +the \fBapply\fR command. +.PP +.CS +# Match one of the sequences in a URL-encoded string that needs +# fixing, converting + to space and %XX to the right character +# (e.g., %7e becomes ~) +set RE {(\e+)|%([0-9A-Fa-f]{2})} + +# Note that -command uses a command prefix, not a command name +set decoded [\fBregsub\fR -all -command $RE $string {apply {{- p h} { + # + is a special case; handle directly + if {$p eq "+"} { + return " " + } + # convert hex to a char + scan $h %x charNumber + format %c $charNumber +}}}] +.CE +.VE 8.7 .SH "SEE ALSO" regexp(n), re_syntax(n), subst(n), string(n) .SH KEYWORDS diff --git a/doc/rename.n b/doc/rename.n index f74db5f..b064f66 100644 --- a/doc/rename.n +++ b/doc/rename.n @@ -43,3 +43,7 @@ proc ::source args { namespace(n), proc(n) .SH KEYWORDS command, delete, namespace, rename +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/return.n b/doc/return.n index ea590ea..e3d7c06 100644 --- a/doc/return.n +++ b/doc/return.n @@ -137,7 +137,6 @@ by the \fBcatch\fR command (or from the copy of that information stored in the global variable \fBerrorInfo\fR). .TP \fB\-errorstack \fIlist\fR -.VS 8.6 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 @@ -152,7 +151,6 @@ 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). -.VE 8.6 .TP \fB\-level \fIlevel\fR . @@ -32,7 +32,12 @@ implement the current call chain. The first element is the same as would be reported by \fBinfo object\fR \fBcall\fR for the current method (except that this also reports useful values from within constructors and destructors, whose names are reported as \fB<constructor>\fR and \fB<destructor>\fR -respectively), and the second element is an index into the first element's +respectively, +.VS TIP500 +and for private methods, which are described as being \fBprivate\fR instead of +being a \fBmethod\fR), +.VE TIP500 +and the second element is an index into the first element's list that indicates which actual implementation is currently executing (the first implementation to execute is always at index 0). .TP @@ -73,3 +73,7 @@ practice instead of doing double-dereferencing): expr(n), global(n), namespace(n), proc(n), trace(n), unset(n), upvar(n), variable(n) .SH KEYWORDS read, write, variable +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/singleton.n b/doc/singleton.n new file mode 100644 index 0000000..568a8bd --- /dev/null +++ b/doc/singleton.n @@ -0,0 +1,99 @@ +'\" +'\" Copyright (c) 2018 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH singleton n 0.3 TclOO "TclOO Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +oo::singleton \- a class that does only allows one instance of itself +.SH SYNOPSIS +.nf +package require TclOO + +\fBoo::singleton\fI method \fR?\fIarg ...\fR? +.fi +.SH "CLASS HIERARCHY" +.nf +\fBoo::object\fR + \(-> \fBoo::class\fR + \(-> \fBoo::singleton\fR +.fi +.BE +.SH DESCRIPTION +Singleton classes are classes that only permit at most one instance of +themselves to exist. They unexport the \fBcreate\fR and +\fBcreateWithNamespace\fR methods entirely, and override the \fBnew\fR method +so that it only makes a new instance if there is no existing instance. It is +not recommended to inherit from a singleton class; singleton-ness is \fInot\fR +inherited. It is not recommended that a singleton class's constructor take any +arguments. +.PP +Instances have their\fB destroy\fR method overridden with a method that always +returns an error in order to discourage destruction of the object, but +destruction remains possible if strictly necessary (e.g., by destroying the +class or using \fBrename\fR to delete it). They also have a (non-exported) +\fB<cloned>\fR method defined on them that similarly always returns errors to +make attempts to use the singleton instance with \fBoo::copy\fR fail. +.SS CONSTRUCTOR +The \fBoo::singleton\fR class does not define an explicit constructor; this +means that it is effectively the same as the constructor of the +\fBoo::class\fR class. +.SS DESTRUCTOR +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" +.TP +\fIcls \fBnew \fR?\fIarg ...\fR? +. +This returns the current instance of the singleton class, if one exists, and +creates a new instance only if there is no existing instance. The additional +arguments, \fIarg ...\fR, are only used if a new instance is actually +manufactured; that construction is via the \fBoo::class\fR class's \fBnew\fR +method. +.RS +.PP +This is an override of the behaviour of a superclass's method with an +identical call signature to the superclass's implementation. +.RE +.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. +.SH EXAMPLE +.PP +This example demonstrates that there is only one instance even though the +\fBnew\fR method is called three times. +.PP +.CS +\fBoo::singleton\fR create Highlander { + method say {} { + puts "there can be only one" + } +} + +set h1 [Highlander new] +set h2 [Highlander new] +if {$h1 eq $h2} { + puts "equal objects" \fI\(-> prints "equal objects"\fR +} +set h3 [Highlander new] +if {$h1 eq $h3} { + puts "equal objects" \fI\(-> prints "equal objects"\fR +} +.CE +.PP +Note that the name of the instance of the singleton is not guaranteed to be +anything in particular. +.SH "SEE ALSO" +oo::class(n) +.SH KEYWORDS +class, metaclass, object, single instance +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/socket.n b/doc/socket.n index 3efdb37..823dbd5 100644 --- a/doc/socket.n +++ b/doc/socket.n @@ -131,6 +131,16 @@ 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. +.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. +.TP +\fB\-reuseport\fI boolean\fR +. +Tells the kernel whether to allow the binding of multiple sockets to the same +address and port. .PP Server channels cannot be used for input or output; their sole use is to accept new client connections. The channels created for each incoming diff --git a/doc/source.n b/doc/source.n index 82fefa6..353b8fb 100644 --- a/doc/source.n +++ b/doc/source.n @@ -43,7 +43,7 @@ or 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, unicode). +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 @@ -69,3 +69,7 @@ foreach scriptFile {foo.tcl bar.tcl} { file(n), cd(n), encoding(n), info(n) .SH KEYWORDS file, script +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/string.n b/doc/string.n index 8d8be3d..7cd53ca 100644 --- a/doc/string.n +++ b/doc/string.n @@ -12,7 +12,7 @@ .SH NAME string \- Manipulate strings .SH SYNOPSIS -\fBstring \fIoption arg \fR?\fIarg ...?\fR +\fBstring \fIoption arg \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP @@ -20,7 +20,7 @@ Performs one of several string operations, depending on \fIoption\fR. The legal \fIoption\fRs (which may be abbreviated) are: .TP \fBstring cat\fR ?\fIstring1\fR? ?\fIstring2...\fR? -.VS 8.6.2 +. Concatenate the given \fIstring\fRs just like placing them directly next to each other and return the resulting compound string. If no \fIstring\fRs are present, the result is an empty string. @@ -32,7 +32,6 @@ 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 -.VE .TP \fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length\fI length\fR? \fIstring1 string2\fR . @@ -89,6 +88,24 @@ 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 .TP +\fBstring insert \fIstring index insertString\fR +.VS "TIP 504" +Returns a copy of \fIstring\fR with \fIinsertString\fR inserted at the +\fIindex\fR'th character. The \fIindex\fR may be specified as described in the +\fBSTRING INDICES\fR section. +.RS +.PP +If \fIindex\fR is start-relative, the first character inserted in the returned +string will be at the specified index. If \fIindex\fR is end-relative, the last +character inserted in the returned string will be at the specified index. +.PP +If \fIindex\fR is at or before the start of \fIstring\fR (e.g., \fIindex\fR is +\fB0\fR), \fIinsertString\fR is prepended to \fIstring\fR. If \fIindex\fR is at +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" +.TP \fBstring is \fIclass\fR ?\fB\-strict\fR? ?\fB\-failindex \fIvarname\fR? \fIstring\fR . Returns 1 if \fIstring\fR is a valid member of the specified character @@ -111,17 +128,24 @@ Any character with a value less than \eu0080 (those that are in the Any of the forms allowed to \fBTcl_GetBoolean\fR. .IP \fBcontrol\fR 12 Any Unicode control character. +.IP \fBdict\fR 12 +.VS TIP501 +Any proper dict structure, with optional surrounding whitespace. In +case of improper dict structure, 0 is returned and the \fIvarname\fR +will contain the index of the +.QW element +where the dict parsing fails, or \-1 if this cannot be determined. +.VE TIP501 .IP \fBdigit\fR 12 Any Unicode digit character. Note that this includes characters outside of the [0\-9] range. .IP \fBdouble\fR 12 Any of the forms allowed to \fBTcl_GetDoubleFromObj\fR. .IP \fBentier\fR 12 -.VS 8.6 +. Any of the valid string formats for an integer value of arbitrary size in Tcl, with optional surrounding whitespace. The formats accepted are exactly those accepted by the C routine \fBTcl_GetBignumFromObj\fR. -.VE .IP \fBfalse\fR 12 Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is false. @@ -268,7 +292,9 @@ the special interpretation of the characters \fB*?[]\e\fR in . Returns a range of consecutive characters from \fIstring\fR, starting with the character whose index is \fIfirst\fR and ending with the -character whose index is \fIlast\fR. An index of 0 refers to the first +character whose index is \fIlast\fR (using the forms described in +\fBSTRING INDICES\fR). An index of \fB0\fR refers to the first +character of the string; an index of \fBend\fR refers to last character of the string. \fIfirst\fR and \fIlast\fR may be specified as for the \fBindex\fR method. If \fIfirst\fR is less than zero then it is treated as if it were zero, and if \fIlast\fR is greater than or @@ -278,13 +304,16 @@ string is returned. .TP \fBstring repeat \fIstring count\fR . -Returns \fIstring\fR repeated \fIcount\fR number of times. +Returns a string consisting of \fIstring\fR concatenated with itself +\fIcount\fR times. If \fIcount\fR is 0, the empty string will be +returned. .TP \fBstring replace \fIstring first last\fR ?\fInewstring\fR? . Removes a range of consecutive characters from \fIstring\fR, starting with the character whose index is \fIfirst\fR and ending with the -character whose index is \fIlast\fR. An index of 0 refers to the +character whose index is \fIlast\fR (using the forms described in +\fBSTRING INDICES\fR). An index of 0 refers to the first character of the string. \fIFirst\fR and \fIlast\fR may be specified as for the \fBindex\fR method. If \fInewstring\fR is specified, then it is placed in the removed character range. If @@ -476,7 +505,7 @@ if {$length == 0} { .SH "SEE ALSO" expr(n), list(n) .SH KEYWORDS -case conversion, compare, index, match, pattern, string, word, equal, +case conversion, compare, index, integer value, match, pattern, string, word, equal, ctype, character, reverse .\" Local Variables: .\" mode: nroff diff --git a/doc/tclsh.1 b/doc/tclsh.1 index 0e59b4f..c37eb81 100644 --- a/doc/tclsh.1 +++ b/doc/tclsh.1 @@ -143,6 +143,15 @@ incomplete commands. .SH "STANDARD CHANNELS" .PP See \fBTcl_StandardChannels\fR for more explanations. +.SH ZIPVFS +.PP +When a zipfile is concatenated to the end of a \fBtclsh\fR, on +startup the contents of the zip archive will be mounted as the +virtual file system /zvfs. If a top level directory tcl8.6 is +present in the zip archive, it will become the directory loaded +as env(TCL_LIBRARY). If a file named \fBmain.tcl\fR is present +in the top level directory of the zip archive, it will be sourced +instead of the shell's normal command line handing. .SH "SEE ALSO" auto_path(n), encoding(n), env(n), fconfigure(n) .SH KEYWORDS diff --git a/doc/tclvars.n b/doc/tclvars.n index adefe40..4d1413c 100644 --- a/doc/tclvars.n +++ b/doc/tclvars.n @@ -322,11 +322,9 @@ 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 -.VS 8.6 '\" Defined by TIP #315 The character that should be used to \fBsplit\fR PATH-like environment variables into their corresponding list of directory names. -.VE 8.6 .TP \fBplatform\fR . @@ -16,7 +16,7 @@ tell \- Return current access position for an open channel .BE .SH DESCRIPTION .PP -Returns an integer string giving the current access position in +Returns an integer giving the current access position in \fIchannelId\fR. This value returned is a byte offset that can be passed to \fBseek\fR in order to set the channel to a particular position. Note that this value is in terms of bytes, not characters like \fBread\fR. @@ -46,3 +46,7 @@ if {[read $chan 6] eq "foobar"} { file(n), open(n), close(n), gets(n), seek(n), Tcl_StandardChannels(3) .SH KEYWORDS access position, channel, seeking +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/trace.n b/doc/trace.n index 5482e59..570b263 100644 --- a/doc/trace.n +++ b/doc/trace.n @@ -20,7 +20,8 @@ trace \- Monitor variable accesses, command usages and command executions This command causes Tcl commands to be executed whenever certain operations are invoked. The legal \fIoption\fRs (which may be abbreviated) are: .TP -\fBtrace add \fItype name ops ?args?\fR +\fBtrace add \fItype name ops\fR ?\fIargs\fR? +. Where \fItype\fR is \fBcommand\fR, \fBexecution\fR, or \fBvariable\fR. .RS .TP diff --git a/doc/unknown.n b/doc/unknown.n index 82dcefc..ee8a5be 100644 --- a/doc/unknown.n +++ b/doc/unknown.n @@ -89,3 +89,7 @@ proc \fBunknown\fR args { info(n), proc(n), interp(n), library(n), namespace(n) .SH KEYWORDS error, non-existent command, unknown +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/update.n b/doc/update.n index ce0fb25..a85faac 100644 --- a/doc/update.n +++ b/doc/update.n @@ -63,3 +63,7 @@ while {!$done} { after(n), interp(n) .SH KEYWORDS asynchronous I/O, event, flush, handler, idle, update +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/uplevel.n b/doc/uplevel.n index 4decc6d..cda1652 100644 --- a/doc/uplevel.n +++ b/doc/uplevel.n @@ -24,9 +24,9 @@ the result of that evaluation. If \fIlevel\fR is an integer then 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 number then the number gives an absolute level number. If \fIlevel\fR +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 starts with a digit or \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/while.n b/doc/while.n index 961260c..6acc909 100644 --- a/doc/while.n +++ b/doc/while.n @@ -63,3 +63,7 @@ set lineCount 0 break(n), continue(n), for(n), foreach(n) .SH KEYWORDS boolean, loop, test, while +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/zipfs.3 b/doc/zipfs.3 new file mode 100644 index 0000000..348557f --- /dev/null +++ b/doc/zipfs.3 @@ -0,0 +1,120 @@ +'\" +'\" Copyright (c) 2015 Jan Nijtmans <jan.nijtmans@gmail.com> +'\" Copyright (c) 2015 Christian Werner <chw@ch-werner.de> +'\" Copyright (c) 2017 Sean Woods <yoda@etoyoc.com> +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tclzipfs 3 8.7 Tcl "Tcl Library Procedures" +.so man.macros +.BS +.SH NAME +TclZipfs_AppHook, Tclzipfs_Mount, TclZipfs_MountBuffer, Tclzipfs_Unmount \- handle ZIP files as Tcl virtual filesystems +.SH SYNOPSIS +.nf +int +\fBTclZipfs_AppHook(\fIargcPtr, argvPtr\fR) +.sp +int +\fBTclzipfs_Mount\fR(\fIinterp, mountpoint, zipname, password\fR) +.sp +int +\fBTclZipfs_MountBuffer\fR(\fIinterp, mountpoint, data, dataLen, copy\fR) +.sp +int +\fBTclzipfs_Unmount\fR(\fIinterp, mountpoint\fR) +.fi +.SH ARGUMENTS +.AS Tcl_Interp *mountpoint in +.AP "int" *argcPtr in +Pointer to a variable holding the number of command line arguments from +\fBmain\fR(). +.AP "char" ***argvPtr in +Pointer to an array of strings containing the command line arguments to +\fBmain\fR(). +.AP Tcl_Interp *interp in +Interpreter in which the ZIP file system is mounted. The interpreter's result is +modified to hold the result or error message from the script. +.AP "const char" *zipname in +Name of a ZIP file. Must not be NULL when either mounting or unmounting a ZIP. +.AP "const char" *mountpoint in +Name of a mount point, which must be a legal Tcl file or directory name. May +be NULL to query current mount points. +.AP "const char" *password in +An (optional) password. Use NULL if no password is wanted to read the file. +.AP "unsigned char" *data in +A data buffer to mount. The data buffer must hold the contents of a ZIP +archive, and must not be NULL. +.AP size_t dataLen in +The number of bytes in the supplied data buffer argument, \fIdata\fR. +.AP int copy in +If non-zero, the ZIP archive in the data buffer will be internally copied +before mounting, allowing the data buffer to be disposed once +\fBTclZipfs_MountBuffer\fR returns. If zero, the caller guarantees that the +buffer will be valid to read from for the duration of the mount. +.BE +.SH DESCRIPTION +\fBTclZipfs_AppHook\fR is a utility function to perform standard application +initialization procedures, taking into account available ZIP archives as +follows: +.IP [1] +If the current application has a mountable ZIP archive, that archive is +mounted under \fIZIPFS_VOLUME\fB/app\fR as a read-only Tcl virtual file +system. \fIZIPFS_VOLUME\fR is usually \fB//zipfs:\fR on all platforms, but +\fBzipfs:\fR may also be used on Windows (due to differences in the +platform's filename parsing). +.IP [2] +If a file named \fBmain.tcl\fR is located in the root directory of that file +system (i.e., at \fIZIPROOT\fB/app/main.tcl\fR after the ZIP archive is +mounted as described above) it is treated as the startup script for the +process. +.IP [3] +If the file \fIZIPROOT\fB/app/tcl_library/init.tcl\fR is present, the +\fBtcl_library\fR global variable in the initial Tcl interpreter is set to +\fIZIPROOT\fB/app/tcl_library\fR. +.IP [4] +If the directory \fBtcl_library\fR was not found in the main application +mount, the system will then search for it as either a VFS attached to the +application dynamic library, or as a zip archive named +\fBlibtcl_\fImajor\fB_\fIminor\fB_\fIpatchlevel\fB.zip\fR either in the +present working directory or in the standard Tcl install location. (For +example, the Tcl 8.7.2 release would be searched for in a file +\fBlibtcl_8_7_2.zip\fR.) That archive, if located, is also mounted read-only. +.PP +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). +.PP +The result of \fBTclZipfs_AppHook\fR is a Tcl result code (e.g., \fBTCL_OK\fR +when the function is successful). The function \fImay\fR modify the variables +pointed to by \fIargcPtr\fR and \fIargvPtr\fR to remove arguments; the +current implementation does not do so, but callers \fIshould not\fR assume +that this will be true in the future. +.PP +\fBTclzipfs_Mount\fR mounts the ZIP archive \fIzipname\fR on the mount point +given in \fImountpoint\fR using the optional ZIP password \fIpassword\fR. +Errors during that process are reported in the interpreter \fIinterp\fR. If +\fImountpoint\fR is a NULL pointer, information on all currently mounted ZIP +file systems is written into \fIinterp\fR's result as a sequence of mount +points and ZIP file names. The result of this call is a standard Tcl result +code. +.PP +\fBTclzipfs_MountBuffer\fR mounts the ZIP archive in the buffer pointed to by +\fIdata\fR on the mount point given in \fImountpoint\fR. The ZIP archive is +assumed to be not password protected. Errors during that process are reported +in the interpreter \fIinterp\fR. The \fIcopy\fR argument determines whether +the buffer is internally copied before mounting or not. The result of this +call is a standard Tcl result code. +.PP +\fBTclzipfs_Unmount\fR undoes the effect of \fBTclzipfs_Mount\fR, i.e., it +unmounts the mounted ZIP file system that was mounted from \fIzipname\fR (at +\fImountpoint\fR). Errors are reported in the interpreter \fIinterp\fR. The +result of this call is a standard Tcl result code. +.PP +\fBTclZipfs_AppHook\fR can not be used in stub-enabled extensions. +.SH "SEE ALSO" +zipfs(n) +.SH KEYWORDS +compress, filesystem, zip diff --git a/doc/zipfs.n b/doc/zipfs.n new file mode 100644 index 0000000..2d84173 --- /dev/null +++ b/doc/zipfs.n @@ -0,0 +1,254 @@ +'\" +'\" Copyright (c) 2015 Jan Nijtmans <jan.nijtmans@gmail.com> +'\" Copyright (c) 2015 Christian Werner <chw@ch-werner.de> +'\" Copyright (c) 2015 Sean Woods <yoda@etoyoc.com> +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH zipfs n 1.0 Zipfs "zipfs Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +zipfs \- Mount and work with ZIP files within Tcl +.SH SYNOPSIS +.nf +\fBpackage require zipfs \fR?\fB1.0\fR? +.sp +\fBzipfs canonical\fR ?\fImntpnt\fR? \fIfilename\fR ?\fIZIPFS\fR? +\fBzipfs exists\fR \fIfilename\fR +\fBzipfs find\fR \fIdirectoryName\fR +\fBzipfs info\fR \fIfilename\fR +\fBzipfs list\fR ?(\fB\-glob\fR|\fB\-regexp\fR)? ?\fIpattern\fR? +\fBzipfs lmkimg\fR \fIoutfile inlist\fR ?\fIpassword infile\fR? +\fBzipfs lmkzip\fR \fIoutfile inlist\fR ?\fIpassword\fR? +\fBzipfs mkimg\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR? +\fBzipfs mkkey\fR \fIpassword\fR +\fBzipfs mkzip\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? +\fBzipfs mount\fR ?\fImountpoint\fR? ?\fIzipfile\fR? ?\fIpassword\fR? +\fBzipfs root\fR +\fBzipfs unmount\fR \fImountpoint\fR +.fi +'\" The following subcommand is *UNDOCUMENTED* +'\" \fBzipfs mount_data\fR ?\fImountpoint\fR? ?\fIdata\fR? +.BE +.SH DESCRIPTION +.PP +The \fBzipfs\fR command (the sole public command provided by the built-in +package with the same name) provides Tcl with the ability to mount the +contents of a ZIP archive file as a virtual file system. ZIP archives support +simple encryption, sufficient to prevent casual inspection of their contents +but not able to prevent access by even a moderately determined attacker. +.TP +\fBzipfs canonical\fR ?\fImountpoint\fR? \fIfilename\fR ?\fIinZipfs\fR? +. +This takes the name of a file, \fIfilename\fR, and produces where it would be +mapped into a zipfs mount as its result. If specified, \fImountpoint\fR says +within which mount the mapping will be done; if omitted, the main root of the +zipfs system is used. The \fIinZipfs\fR argument is a an optional boolean +which controls whether to fully canonicalise the name; it defaults to true. +.TP +\fBzipfs exists\fR \fIfilename\fR +. +Return 1 if the given filename exists in the mounted zipfs and 0 if it does not. +.TP +\fBzipfs find\fR \fIdirectoryName\fR +. +Recursively lists files including and below the directory \fIdirectoryName\fR. +The result list consists of relative path names starting from the given +directory. This command is also used by the \fBzipfs mkzip\fR and \fBzipfs +mkimg\fR commands. +.TP +\fBzipfs info\fR \fIfile\fR +. +Return information about the given \fIfile\fR in the mounted zipfs. The +information consists of: +.RS +.IP (1) +the name of the ZIP archive file that contains the file, +.IP (2) +the size of the file after decompressions, +.IP (3) +the compressed size of the file, and +.IP (4) +the offset of the compressed data in the ZIP archive file. +.PP +Note: 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. +.RE +.TP +\fBzipfs list\fR ?(\fB\-glob\fR|\fB\-regexp\fR)? ?\fIpattern\fR? +. +Return a list of all files in the mounted zipfs, or just those matching +\fIpattern\fR (optionally controlled by the option parameters). The order of +the names in the list is arbitrary. +.TP +\fBzipfs mount ?\fImountpoint\fR? ?\fIzipfile\fR? ?\fIpassword\fR? +. +The \fBzipfs mount\fR command mounts a ZIP archive file 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. +.RS +.PP +With no \fIzipfile\fR, returns the zipfile mounted at \fImountpoint\fR. With +no \fImountpoint\fR, return all zipfile/mount pairs. If \fImountpoint\fR is +specified as an empty string, mount on file path. +.PP +\fBNB:\fR because the current working directory is a concept maintained by the +operating system, using \fBcd\fR into a mounted archive will only work in the +current process, and then not entirely consistently (e.g., if a shared library +uses direct access to the OS rather than through Tcl's filesystem API, it will +not see the current directory as being inside the mount and will not be able +to access the files inside the mount). +.RE +.TP +\fBzipfs root\fR +. +Returns a constant string which indicates the mount point for zipfs volumes +for the current platform. On Windows, this value is +.QW \fBzipfs:/\fR . +On Unix, this value is +.QW \fB//zipfs:/\fR . +.TP +\fBzipfs unmount \fImountpoint\fR +. +Unmounts a previously mounted ZIP archive mounted to \fImountpoint\fR. +.SS "ZIP CREATION COMMANDS" +This package also provides several commands to aid the creation of ZIP +archives as Tcl applications. +.TP +\fBzipfs mkzip\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? +. +Creates a ZIP archive file named \fIoutfile\fR from the contents of the input +directory \fIindir\fR (contained regular files only) with optional ZIP +password \fIpassword\fR. While processing the files below \fIindir\fR the +optional file name prefix given in \fIstrip\fR is stripped off the beginning +of the respective file name. When stripping, it is common to remove either +the whole source directory name or the name of its parent directory. +.RS +.PP +\fBCaution:\fR the choice of the \fIindir\fR parameter (less the optional +stripped prefix) determines the later root name of the archive's content. +.RE +.TP +\fBzipfs mkimg\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR? +. +Creates an image (potentially a new executable file) similar to \fBzipfs +mkzip\fR; see that command for a description of most parameters to this +command, as they behave identically here. +.RS +.PP +If the \fIinfile\fR parameter is specified, this file is prepended in front of +the ZIP archive, otherwise the file returned by \fBinfo nameofexecutable\fR +(i.e., the executable file of the running process) is used. If the +\fIpassword\fR parameter is not empty, an obfuscated version of that password +(see \fBzipfs mkkey\fR) is placed between the image and ZIP chunks of the +output file and the contents of the ZIP chunk are protected with that +password. +.PP +If there is a file, \fBmain.tcl\fR, in the root directory of the resulting +archive and the image file that the archive is attached to is a \fBtclsh\fR +(or \fBwish\fR) instance (true by default, but depends on your configuration), +then the resulting image is an executable that will \fBsource\fR the script in +that \fBmain.tcl\fR after mounting the ZIP archive, and will \fBexit\fR once +that script has been executed. +.PP +\fBCaution:\fR highly experimental, not usable on Android, only partially +tested on Linux and Windows. +.RE +.TP +\fBzipfs mkkey\fR \fIpassword\fR +. +Given the clear text \fIpassword\fR argument, an obfuscated string version is +returned with the same format used in the \fBzipfs mkimg\fR command. +.TP +\fBzipfs lmkimg\fR \fIoutfile inlist\fR ?\fIpassword infile\fR? +. +This command is like \fBzipfs mkimg\fR, but instead of an input directory, +\fIinlist\fR must be a Tcl list where the odd elements are the names of files +to be copied into the archive in the image, and the even elements are their +respective names within that archive. +.TP +\fBzipfs lmkzip\fR \fIoutfile inlist\fR ?\fIpassword\fR? +. +This command is like \fBzipfs mkzip\fR, but instead of an input directory, +\fIinlist\fR must be a Tcl list where the odd elements are the names of files +to be copied into the archive, and the even elements are their respective +names within that archive. +.SH "EXAMPLES" +.PP +Mounting an ZIP archive as an application directory and running code out of it +before unmounting it again: +.PP +.CS +set zip myApp.zip +set base [file join [\fBzipfs root\fR] myApp] + +\fBzipfs mount\fR $base $zip +# $base now has the contents of myApp.zip + +source [file join $base app.tcl] +# use the contents, load libraries from it, etc... + +\fBzipfs unmount\fR $zip +.CE +.PP +Creating a ZIP archive, given that a directory exists containing the content +to put in the archive. Note that the source directory is given twice, in order +to strip the exterior directory name from each filename in the archive. +.PP +.CS +set sourceDirectory [file normalize myApp] +set targetZip myApp.zip + +\fBzipfs mkzip\fR $targetZip $sourceDirectory $sourceDirectory +.CE +.PP +Encryption can be applied to ZIP archives by providing a password when +building the ZIP and when mounting it. +.PP +.CS +set zip myApp.zip +set sourceDir [file normalize myApp] +set password "hunter2" +set base [file join [\fBzipfs root\fR] myApp] + +# Create with password +\fBzipfs mkzip\fR $targetZip $sourceDir $sourceDir $password + +# Mount with password +\fBzipfs mount\fR $base $zip $password +.CE +.PP +When creating an executable image with a password, the password is placed +within the executable in a shrouded form so that the application can read +files inside the embedded ZIP archive yet casual inspection cannot read it. +.PP +.CS +set appDir [file normalize myApp] +set img "myApp.bin" +set password "hunter2" + +# Create some simple content to define a basic application +file mkdir $appDir +set f [open $appDir/main.tcl] +puts $f { + puts "Hi. This is [info script]" +} +close $f + +# Create the executable +\fBzipfs mkimg\fR $img $appDir $appDir $password + +# Launch the executable, printing its output to stdout +exec $img >@stdout +# prints: \fIHi. This is //zipfs:/app/main.tcl\fR +.CE +.SH "SEE ALSO" +tclsh(1), file(n), zipfs(3), zlib(n) +.SH "KEYWORDS" +compress, filesystem, zip +'\" Local Variables: +'\" mode: nroff +'\" End: |