diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/AddErrInfo.3 | 21 | ||||
| -rw-r--r-- | doc/Async.3 | 33 | ||||
| -rw-r--r-- | doc/BoolObj.3 | 41 | ||||
| -rw-r--r-- | doc/ByteArrObj.3 | 202 | ||||
| -rw-r--r-- | doc/Cancel.3 | 8 | ||||
| -rw-r--r-- | doc/Class.3 | 38 | ||||
| -rw-r--r-- | doc/CrtAlias.3 | 53 | ||||
| -rw-r--r-- | doc/CrtChannel.3 | 21 | ||||
| -rw-r--r-- | doc/CrtInterp.3 | 6 | ||||
| -rw-r--r-- | doc/CrtMathFnc.3 | 4 | ||||
| -rw-r--r-- | doc/CrtObjCmd.3 | 39 | ||||
| -rw-r--r-- | doc/CrtTrace.3 | 43 | ||||
| -rw-r--r-- | doc/DString.3 | 19 | ||||
| -rw-r--r-- | doc/DictObj.3 | 67 | ||||
| -rw-r--r-- | doc/DoubleObj.3 | 12 | ||||
| -rw-r--r-- | doc/Encoding.3 | 128 | ||||
| -rw-r--r-- | doc/Ensemble.3 | 25 | ||||
| -rw-r--r-- | doc/Eval.3 | 25 | ||||
| -rw-r--r-- | doc/Exit.3 | 3 | ||||
| -rw-r--r-- | doc/ExprLongObj.3 | 9 | ||||
| -rw-r--r-- | doc/FileSystem.3 | 200 | ||||
| -rw-r--r-- | doc/FindExec.3 | 9 | ||||
| -rw-r--r-- | doc/GetIndex.3 | 39 | ||||
| -rw-r--r-- | doc/GetInt.3 | 20 | ||||
| -rw-r--r-- | doc/Hash.3 | 16 | ||||
| -rw-r--r-- | doc/Init.3 | 14 | ||||
| -rw-r--r-- | doc/InitStubs.3 | 6 | ||||
| -rw-r--r-- | doc/InitSubSyst.3 | 34 | ||||
| -rw-r--r-- | doc/IntObj.3 | 45 | ||||
| -rw-r--r-- | doc/Interp.3 | 121 | ||||
| -rw-r--r-- | doc/LinkVar.3 | 150 | ||||
| -rw-r--r-- | doc/ListObj.3 | 25 | ||||
| -rw-r--r-- | doc/Load.3 | 4 | ||||
| -rw-r--r-- | doc/Method.3 | 70 | ||||
| -rw-r--r-- | doc/NRE.3 | 38 | ||||
| -rw-r--r-- | doc/Namespace.3 | 12 | ||||
| -rw-r--r-- | doc/Notifier.3 | 49 | ||||
| -rw-r--r-- | doc/Number.3 | 123 | ||||
| -rw-r--r-- | doc/Object.3 | 7 | ||||
| -rw-r--r-- | doc/ObjectType.3 | 85 | ||||
| -rw-r--r-- | doc/OpenFileChnl.3 | 60 | ||||
| -rw-r--r-- | doc/OpenTcp.3 | 23 | ||||
| -rw-r--r-- | doc/Panic.3 | 25 | ||||
| -rw-r--r-- | doc/ParseArgs.3 | 6 | ||||
| -rw-r--r-- | doc/ParseCmd.3 | 8 | ||||
| -rw-r--r-- | doc/PkgRequire.3 | 6 | ||||
| -rw-r--r-- | doc/RecEvalObj.3 | 8 | ||||
| -rw-r--r-- | doc/RegConfig.3 | 8 | ||||
| -rw-r--r-- | doc/RegExp.3 | 16 | ||||
| -rw-r--r-- | doc/SaveInterpState.3 | 85 | ||||
| -rw-r--r-- | doc/SaveResult.3 | 120 | ||||
| -rw-r--r-- | doc/SetChanErr.3 | 15 | ||||
| -rw-r--r-- | doc/SetResult.3 | 48 | ||||
| -rw-r--r-- | doc/SetVar.3 | 21 | ||||
| -rw-r--r-- | doc/StaticLibrary.3 | 78 | ||||
| -rw-r--r-- | doc/StaticPkg.3 | 70 | ||||
| -rw-r--r-- | doc/StringObj.3 | 55 | ||||
| -rw-r--r-- | doc/SubstObj.3 | 7 | ||||
| -rw-r--r-- | doc/Tcl.n | 319 | ||||
| -rw-r--r-- | doc/TclZlib.3 | 27 | ||||
| -rw-r--r-- | doc/Tcl_Main.3 | 17 | ||||
| -rw-r--r-- | doc/Thread.3 | 14 | ||||
| -rw-r--r-- | doc/ToUpper.3 | 13 | ||||
| -rw-r--r-- | doc/TraceVar.3 | 39 | ||||
| -rw-r--r-- | doc/UniCharIsAlpha.3 | 2 | ||||
| -rw-r--r-- | doc/Utf.3 | 172 | ||||
| -rw-r--r-- | doc/WrongNumArgs.3 | 6 | ||||
| -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 | 393 | ||||
| -rw-r--r-- | doc/callback.n | 88 | ||||
| -rw-r--r-- | doc/case.n | 60 | ||||
| -rw-r--r-- | doc/catch.n | 6 | ||||
| -rw-r--r-- | doc/cd.n | 6 | ||||
| -rw-r--r-- | doc/chan.n | 1146 | ||||
| -rw-r--r-- | doc/class.n | 2 | ||||
| -rw-r--r-- | doc/classvariable.n | 78 | ||||
| -rw-r--r-- | doc/clock.n | 114 | ||||
| -rw-r--r-- | doc/close.n | 25 | ||||
| -rw-r--r-- | doc/configurable.n | 333 | ||||
| -rw-r--r-- | doc/continue.n | 2 | ||||
| -rw-r--r-- | doc/cookiejar.n | 217 | ||||
| -rw-r--r-- | doc/copy.n | 2 | ||||
| -rw-r--r-- | doc/coroutine.n | 111 | ||||
| -rw-r--r-- | doc/dde.n | 6 | ||||
| -rw-r--r-- | doc/define.n | 605 | ||||
| -rw-r--r-- | doc/dict.n | 55 | ||||
| -rw-r--r-- | doc/encoding.n | 211 | ||||
| -rw-r--r-- | doc/eof.n | 4 | ||||
| -rw-r--r-- | doc/eval.n | 15 | ||||
| -rw-r--r-- | doc/exec.n | 10 | ||||
| -rw-r--r-- | doc/exit.n | 4 | ||||
| -rw-r--r-- | doc/expr.n | 486 | ||||
| -rw-r--r-- | doc/fblocked.n | 4 | ||||
| -rw-r--r-- | doc/fconfigure.n | 20 | ||||
| -rw-r--r-- | doc/fcopy.n | 56 | ||||
| -rw-r--r-- | doc/file.n | 119 | ||||
| -rw-r--r-- | doc/fileevent.n | 4 | ||||
| -rw-r--r-- | doc/filename.n | 16 | ||||
| -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/gets.n | 37 | ||||
| -rw-r--r-- | doc/global.n | 4 | ||||
| -rw-r--r-- | doc/history.n | 4 | ||||
| -rw-r--r-- | doc/http.n | 1218 | ||||
| -rw-r--r-- | doc/idna.n | 88 | ||||
| -rw-r--r-- | doc/incr.n | 9 | ||||
| -rw-r--r-- | doc/info.n | 696 | ||||
| -rw-r--r-- | doc/interp.n | 36 | ||||
| -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/ledit.n | 91 | ||||
| -rw-r--r-- | doc/library.n | 159 | ||||
| -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/load.n | 11 | ||||
| -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/lseq.n | 99 | ||||
| -rw-r--r-- | doc/lset.n | 5 | ||||
| -rw-r--r-- | doc/lsort.n | 7 | ||||
| -rw-r--r-- | doc/mathfunc.n | 79 | ||||
| -rw-r--r-- | doc/mathop.n | 69 | ||||
| -rw-r--r-- | doc/msgcat.n | 213 | ||||
| -rw-r--r-- | doc/my.n | 95 | ||||
| -rw-r--r-- | doc/namespace.n | 4 | ||||
| -rw-r--r-- | doc/next.n | 7 | ||||
| -rw-r--r-- | doc/object.n | 2 | ||||
| -rw-r--r-- | doc/open.n | 167 | ||||
| -rw-r--r-- | doc/package.n | 12 | ||||
| -rw-r--r-- | doc/packagens.n | 6 | ||||
| -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 | 10 | ||||
| -rw-r--r-- | doc/pwd.n | 4 | ||||
| -rw-r--r-- | doc/read.n | 73 | ||||
| -rw-r--r-- | doc/refchan.n | 28 | ||||
| -rw-r--r-- | doc/registry.n | 2 | ||||
| -rw-r--r-- | doc/regsub.n | 94 | ||||
| -rw-r--r-- | doc/rename.n | 4 | ||||
| -rw-r--r-- | doc/return.n | 2 | ||||
| -rw-r--r-- | doc/safe.n | 168 | ||||
| -rw-r--r-- | doc/self.n | 9 | ||||
| -rw-r--r-- | doc/set.n | 4 | ||||
| -rw-r--r-- | doc/singleton.n | 99 | ||||
| -rw-r--r-- | doc/socket.n | 23 | ||||
| -rw-r--r-- | doc/source.n | 12 | ||||
| -rw-r--r-- | doc/string.n | 57 | ||||
| -rw-r--r-- | doc/tclsh.1 | 17 | ||||
| -rw-r--r-- | doc/tcltest.n | 1 | ||||
| -rw-r--r-- | doc/tclvars.n | 2 | ||||
| -rw-r--r-- | doc/tell.n | 6 | ||||
| -rw-r--r-- | doc/timerate.n | 6 | ||||
| -rw-r--r-- | doc/trace.n | 5 | ||||
| -rw-r--r-- | doc/transchan.n | 13 | ||||
| -rw-r--r-- | doc/unknown.n | 4 | ||||
| -rw-r--r-- | doc/unload.n | 5 | ||||
| -rw-r--r-- | doc/update.n | 4 | ||||
| -rw-r--r-- | doc/uplevel.n | 4 | ||||
| -rw-r--r-- | doc/upvar.n | 2 | ||||
| -rw-r--r-- | doc/vwait.n | 71 | ||||
| -rw-r--r-- | doc/while.n | 4 | ||||
| -rw-r--r-- | doc/zipfs.3 | 130 | ||||
| -rw-r--r-- | doc/zipfs.n | 293 |
180 files changed, 9426 insertions, 3013 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index 99ec904..357b3eb 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 @@ -305,6 +308,22 @@ The global variables \fBerrorInfo\fR and \fBerrorCode\fR are not modified by \fBTcl_ResetResult\fR so they continue to hold a record of information about the most recent error seen in an interpreter. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The result of \fBTcl_GetReturnOptions\fR will have at least one +reference to it from the Tcl interpreter. If not using it immediately, +you should use \fBTcl_IncrRefCount\fR to add your own reference. +.PP +The \fIoptions\fR argument to \fBTcl_SetReturnOptions\fR will have a +reference added by the Tcl interpreter; it may safely be called with a +zero-reference value. +.PP +\fBTcl_AppendObjToErrorInfo\fR only reads its \fIobjPtr\fR argument; +it does not modify its reference count at all. +.PP +The \fIerrorObjPtr\fR argument to \fBTcl_SetObjErrorCode\fR will have a +reference added by the Tcl interpreter; it may safely be called with a +zero-reference value. .SH "SEE ALSO" Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetResult(3), Tcl_SetErrno(3), errorCode(n), errorInfo(n) diff --git a/doc/Async.3 b/doc/Async.3 index a8896af..e6ec5f8 100644 --- a/doc/Async.3 +++ b/doc/Async.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events +Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncMarkFromSignal, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -21,6 +21,9 @@ void \fBTcl_AsyncMark\fR(\fIasync\fR) .sp int +\fBTcl_AsyncMarkFromSignal\fR(\fIasync\fR, \fIsigNumber\fR) +.sp +int \fBTcl_AsyncInvoke\fR(\fIinterp, code\fR) .sp void @@ -36,6 +39,8 @@ Procedure to invoke to handle an asynchronous event. One-word value to pass to \fIproc\fR. .AP Tcl_AsyncHandler async in Token for asynchronous event handler. +.AP int sigNumber in +POSIX signal number, when used in a signal context. .AP Tcl_Interp *interp in Tcl interpreter in which command was being evaluated when handler was invoked, or NULL if handler was invoked when there was no interpreter @@ -62,10 +67,11 @@ to a clean state, such as after the current Tcl command completes. .PP \fBTcl_AsyncCreate\fR, \fBTcl_AsyncDelete\fR, and \fBTcl_AsyncReady\fR are thread sensitive. They access and/or set a thread-specific data -structure in the event of a core built with \fI\-\-enable\-threads\fR. The token -created by \fBTcl_AsyncCreate\fR contains the needed thread information it -was called from so that calling \fBTcl_AsyncMark\fR(\fItoken\fR) will only yield -the origin thread into the asynchronous handler. +structure in the event of a core built with \fI\-\-enable\-threads\fR. +The token created by \fBTcl_AsyncCreate\fR contains the needed thread +information it was called from so that calling \fBTcl_AsyncMarkFromSignal\fR +or \fBTcl_AsyncMark\fR with this token will only yield the origin +thread into the asynchronous handler. .PP \fBTcl_AsyncCreate\fR creates an asynchronous handler and returns a token for it. @@ -74,13 +80,16 @@ any occurrences of the asynchronous event that it is intended to handle (it is not safe to create a handler at the time of an event). When an asynchronous event occurs the code that detects the event -(such as a signal handler) should call \fBTcl_AsyncMark\fR with the -token for the handler. -\fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it -will not invoke the handler immediately. -Tcl will call the \fIproc\fR associated with the handler later, when -the world is in a safe state, and \fIproc\fR can then carry out -the actions associated with the asynchronous event. +(such as a POSIX signal handler) should call \fBTcl_AsyncMarkFromSignal\fR +with the token for the handler and the POSIX signal number. The +return value of this function is true, when the handler will be +marked, false otherwise. +For non-signal contexts, \fBTcl_AsyncMark\fR serves the same purpose. +\fBTcl_AsyncMarkFromSignal\fR and \fBTcl_AsyncMark\fR will mark +the handler as ready to execute, but will not invoke the handler +immediately. Tcl will call the \fIproc\fR associated with the +handler later, when the world is in a safe state, and \fIproc\fR +can then carry out the actions associated with the asynchronous event. \fIProc\fR should have arguments and result that match the type \fBTcl_AsyncProc\fR: .PP diff --git a/doc/BoolObj.3 b/doc/BoolObj.3 index 795c08a..71580af 100644 --- a/doc/BoolObj.3 +++ b/doc/BoolObj.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- store/retrieve boolean value in a Tcl_Obj +Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj, Tcl_GetBoolFromObj \- store/retrieve boolean value in a Tcl_Obj .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -20,7 +20,10 @@ Tcl_Obj * \fBTcl_SetBooleanObj\fR(\fIobjPtr, intValue\fR) .sp int -\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, intPtr\fR) +\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR) +.sp +int +\fBTcl_GetBoolFromObj\fR(\fIinterp, objPtr, flags. charPtr\fR) .SH ARGUMENTS .AS Tcl_Interp intValue in/out .AP int intValue in @@ -32,9 +35,16 @@ retrieve a boolean value. If a boolean value cannot be retrieved, an error message is left in the interpreter's result value unless \fIinterp\fR is NULL. -.AP int *intPtr out +.AP "bool \&| int" *boolPtr out Points to place where \fBTcl_GetBooleanFromObj\fR stores the boolean value (0 or 1) obtained from \fIobjPtr\fR. +.AP char *charPtr out +Points to place where \fBTcl_GetBoolFromObj\fR +stores the boolean value (0 or 1) obtained from \fIobjPtr\fR. +.AP int flags in +0 or TCL_NULL_OK. If TCL_NULL_OK +is used, then the empty string or NULL will result in \fBTcl_GetBoolFromObj\fR +return TCL_OK, the *charPtr filled with the value \fB'\exFF'\fR; .BE .SH DESCRIPTION @@ -61,13 +71,13 @@ any former value stored in \fI*objPtr\fR. from the value stored in \fI*objPtr\fR. If \fIobjPtr\fR holds a string value recognized by \fBTcl_GetBoolean\fR, then the recognized boolean value is written at the address given -by \fIintPtr\fR. +by \fIboolPtr\fR. If \fIobjPtr\fR holds any value recognized as a number by Tcl, then if that value is zero a 0 is written at -the address given by \fIintPtr\fR and if that -value is non-zero a 1 is written at the address given by \fIintPtr\fR. +the address given by \fIboolPtr\fR and if that +value is non-zero a 1 is written at the address given by \fIboolPtr\fR. In all cases where a value is written at the address given -by \fIintPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR. +by \fIboolPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR. If the value of \fIobjPtr\fR does not meet any of the conditions above, then \fBTCL_ERROR\fR is returned and an error message is left in the interpreter's result unless \fIinterp\fR is NULL. @@ -76,6 +86,11 @@ fields of \fI*objPtr\fR so that future calls to \fBTcl_GetBooleanFromObj\fR on the same \fIobjPtr\fR can be performed more efficiently. .PP +\fBTcl_GetBoolFromObj\fR functions almost the same as +\fBTcl_GetBooleanFromObj\fR, but it has an additional parameter +\fBflags\fR, which can be used to specify whether the empty +string or NULL is accepted as valid. +.PP Note that the routines \fBTcl_GetBooleanFromObj\fR and \fBTcl_GetBoolean\fR are not functional equivalents. The set of values for which \fBTcl_GetBooleanFromObj\fR @@ -88,6 +103,18 @@ will lead to a \fBTCL_OK\fR return (and the boolean value 1), while the same value passed to \fBTcl_GetBoolean\fR will lead to a \fBTCL_ERROR\fR return. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewBooleanObj\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_SetBooleanObj\fR does not modify the reference count of its +\fIobjPtr\fR argument, but does require that the object be unshared. +.PP +\fBTcl_GetBooleanFromObj\fR does not modify the reference count of its +\fIobjPtr\fR argument; it only reads. Note however that this function +may set the interpreter result; if that is the only place that +is holding a reference to the object, it will be deleted. .SH "SEE ALSO" Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3 index ff0b4e1..8ddc28c 100644 --- a/doc/ByteArrObj.3 +++ b/doc/ByteArrObj.3 @@ -8,84 +8,180 @@ .so man.macros .BS .SH NAME -Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl values as a arrays of bytes +Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetBytesFromObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate a Tcl value as an array of bytes .SH SYNOPSIS .nf \fB#include <tcl.h>\fR .sp Tcl_Obj * -\fBTcl_NewByteArrayObj\fR(\fIbytes, length\fR) +\fBTcl_NewByteArrayObj\fR(\fIbytes, numBytes\fR) .sp void -\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, length\fR) +\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, numBytes\fR) .sp +.VS TIP568 unsigned char * -\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, lengthPtr\fR) +\fBTcl_GetBytesFromObj\fR(\fIinterp, objPtr, numBytesPtr\fR) +.VE TIP568 .sp unsigned char * -\fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR) +\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, numBytesPtr\fR) +.sp +unsigned char * +\fBTcl_SetByteArrayLength\fR(\fIobjPtr, numBytes\fR) .SH ARGUMENTS -.AS "const unsigned char" *lengthPtr in/out +.AS "const unsigned char" *numBytesPtr in/out .AP "const unsigned char" *bytes in The array of bytes used to initialize or set a byte-array value. May be NULL -even if \fIlength\fR is non-zero. -.AP int length in -The length of the array of bytes. It must be >= 0. +even if \fInumBytes\fR is non-zero. +.AP int numBytes in +The number of bytes in the array. It must be >= 0. .AP Tcl_Obj *objPtr in/out -For \fBTcl_SetByteArrayObj\fR, this points to the value to be converted to -byte-array type. For \fBTcl_GetByteArrayFromObj\fR and -\fBTcl_SetByteArrayLength\fR, this points to the value from which to get -the byte-array value; if \fIobjPtr\fR does not already point to a byte-array -value, it will be converted to one. -.AP int *lengthPtr out -If non-NULL, filled with the length of the array of bytes in the value. +For \fBTcl_SetByteArrayObj\fR, this points to an unshared value to be +overwritten by a byte-array value. For \fBTcl_GetBytesFromObj\fR, +\fBTcl_GetByteArrayFromObj\fR and \fBTcl_SetByteArrayLength\fR, this points +to the value from which to extract an array of bytes. +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP int *numBytesPtr out +Points to space where the number of bytes in the array may be written. +Caller may pass NULL when it does not need this information. .BE .SH DESCRIPTION .PP -These procedures are used to create, modify, and read Tcl byte-array values -from C code. Byte-array values are typically used to hold the -results of binary IO operations or data structures created with the -\fBbinary\fR command. In Tcl, an array of bytes is not equivalent to a -string. Conceptually, a string is an array of Unicode characters, while a -byte-array is an array of 8-bit quantities with no implicit meaning. -Accessor functions are provided to get the string representation of a -byte-array or to convert an arbitrary value to a byte-array. Obtaining the +These routines are used to create, modify, store, transfer, and retrieve +arbitrary binary data in Tcl values. Specifically, data that can be +represented as a sequence of arbitrary byte values is supported. +This includes data read from binary channels, values created by the +\fBbinary\fR command, encrypted data, or other information representable as +a finite byte sequence. +.PP +A byte is an 8-bit quantity with no inherent meaning. When the 8 bits are +interpreted as an integer value, the range of possible values is (0-255). +The C type best suited to store a byte is the \fBunsigned char\fR. +An \fBunsigned char\fR array of size \fIN\fR stores an aribtrary binary +value of size \fIN\fR bytes. We call this representation a byte-array. +Here we document the routines that allow us to operate on Tcl values as +byte-arrays. +.PP +All Tcl values must correspond to a string representation. +When a byte-array value must be processed as a string, the sequence +of \fIN\fR bytes is transformed into the corresponding sequence +of \fIN\fR characters, where each byte value transforms to the same +character codepoint value in the range (U+0000 - U+00FF). Obtaining the string representation of a byte-array value (by calling -\fBTcl_GetStringFromObj\fR) produces a properly formed UTF-8 sequence with a -one-to-one mapping between the bytes in the internal representation and the -UTF-8 characters in the string representation. +\fBTcl_GetStringFromObj\fR) produces this string in Tcl's usual +Modified UTF-8 encoding. +.PP +\fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR +create a new value or overwrite an existing unshared value, respectively, +to hold a byte-array value of \fInumBytes\fR bytes. When a caller +passes a non-NULL value of \fIbytes\fR, it must point to memory from +which \fInumBytes\fR bytes can be read. These routines +allocate \fInumBytes\fR bytes of memory, copy \fInumBytes\fR +bytes from \fIbytes\fR into it, and keep the result in the internal +representation of the new or overwritten value. +When the caller passes a NULL value of \fIbytes\fR, the data copying +step is skipped, and the bytes stored in the value are undefined. +A \fIbytes\fR value of NULL is useful only when the caller will arrange +to write known contents into the byte-array through a pointer retrieved +by a call to one of the routines explained below. \fBTcl_NewByteArrayObj\fR +returns a pointer to the created value with a reference count of zero. +\fBTcl_SetByteArrayObj\fR overwrites and invalidates any old contents +of the unshared \fIobjPtr\fR as appropriate, and keeps its reference +count (0 or 1) unchanged. The value produced by these routines has no +string representation. Any memory allocation failure may cause a panic. +Note that the type of the \fInumBytes\fR argument is \fBint\fR; consequently +the largest byte-array value that can be produced by these routines is one +holding \fBINT_MAX\fR bytes. Note also that the string representation of +any Tcl value is limited to \fBINT_MAX\fR bytes, so caution should be +taken with any byte-array of more than \fBINT_MAX / 2\fR bytes. +.PP +\fBTcl_GetBytesFromObj\fR performs the opposite function of +\fBTcl_SetByteArrayObj\fR, providing access to read a byte-array from +a Tcl value that was previously written into it. When \fIobjPtr\fR +is a value previously produced by \fBTcl_NewByteArrayObj\fR or +\fBTcl_SetByteArrayObj\fR, then \fBTcl_GetBytesFromObj\fR returns +a pointer to the byte-array kept in the value's internal representation. +If the caller provides a non-NULL value for \fInumBytesPtr\fR, it must +point to memory where \fBTcl_GetBytesFromObj\fR can write the number +of bytes in the value's internal byte-array. With both pieces of +information, the caller is able to retrieve any information about the +contents of that byte-array that it seeks. When \fIobjPtr\fR does +not already contain an internal byte-array, \fBTcl_GetBytesFromObj\fR +will try to create one from the value's string representation. Any +string value that does not include any character codepoints outside +the range (U+0000 - U+00FF) will successfully translate to a unique +byte-array value. With the created byte-array, the routine returns +as before. For any string representation which does contain +a forbidden character codepoint, the conversion fails, and +\fBTcl_GetBytesFromObj\fR returns NULL to signal that failure. On +failure, nothing will be written to \fInumBytesPtr\fR, and if +the \fIinterp\fR argument is non-NULL, then error messages and +codes are left in it recording the error. +.PP +\fBTcl_GetByteArrayFromObj\fR performs nearly the same function as +\fBTcl_GetBytesFromObj\fR. They differ only in the circumstance when +a byte-array internal value must be created by transformation of +a string representation, and that string representation contains a +character with codepoint greater than U+00FF. Instead of failing +the conversion, \fBTcl_GetByteArrayFromObj\fR will use the 8 least +significant bits of each codepoint to produce a valid byte value +from any character codepoint value. In any other circumstance, +\fBTcl_GetByteArrayFromObj\fR performs just as \fBTcl_GetBytesFromObj\fR +does. Since the conversion cannot fail, \fBTcl_GetByteArrayFromObj\fR +has no need for an \fIinterp\fR argument to record any errors and +the caller can assume \fBTcl_GetByteArrayFromObj\fR does not return NULL. +.PP +\fBTcl_GetByteArrayFromObj\fR must be used with caution. Because of the +truncation on conversion, the byte-array made available to the caller +cannot reliably complete a round-trip back to the original string +representation. This creates opportunities for bugs due to blindness +to differences in values. This routine exists in this form primarily +for compatibility with codebases written for earlier releases of Tcl. +It is expected this routine will incompatibly change in Tcl 9 so that +it also signals failed conversions with a NULL return. +.PP +On success, both \fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR +return a pointer into the internal representation of a \fBTcl_Obj\fR. +That pointer must not be freed by the caller, and should not be retained +for use beyond the known time the internal representation of the value +has not been disturbed. The pointer may be used to overwrite the byte +contents of the internal representation, so long as the value is unshared +and any string representation is invalidated. +.PP +On success, both \fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR +write the number of bytes in the byte-array value of \fIobjPtr\fR +to the space pointed to by \fInumBytesPtr\fR. +.PP +\fBTcl_SetByteArrayLength\fR enables a caller to change the size of a +byte-array in the internal representation of an unshared \fIobjPtr\fR to +become \fInumBytes\fR bytes. This is most often useful after the +bytes of the internal byte-array have been directly overwritten and it +has been discovered that the required size differs from the first +estimate used in the allocation. \fBTcl_SetByteArrayLength\fR returns +a pointer to the resized byte-array. Because resizing the byte-array +changes the internal representation, \fBTcl_SetByteArrayLength\fR +also invalidates any string representation in \fIobjPtr\fR. If resizing +grows the byte-array, the new byte values are undefined. If \fIobjPtr\fR +does not already possess an internal byte-array, one is produced in the +same way that \fBTcl_GetByteArrayFromObj\fR does, with all the cautions +that go along with that. +.SH "REFERENCE COUNT MANAGEMENT" .PP -\fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR will -create a new value of byte-array type or modify an existing value to have a -byte-array type. Both of these procedures set the value's type to be -byte-array and set the value's internal representation to a copy of the -array of bytes given by \fIbytes\fR. \fBTcl_NewByteArrayObj\fR returns a -pointer to a newly allocated value with a reference count of zero. -\fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if -the value is not already a byte-array value, frees any old internal -representation. If \fIbytes\fR is NULL then the new byte array contains -arbitrary values. +\fBTcl_NewByteArrayObj\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. .PP -\fBTcl_GetByteArrayFromObj\fR converts a Tcl value to byte-array type and -returns a pointer to the value's new internal representation as an array of -bytes. The length of this array is stored in \fIlengthPtr\fR if -\fIlengthPtr\fR is non-NULL. The storage for the array of bytes is owned by -the value and should not be freed. The contents of the array may be -modified by the caller only if the value is not shared and the caller -invalidates the string representation. +\fBTcl_SetByteArrayObj\fR and \fBTcl_SetByteArrayLength\fR do not modify the +reference count of their \fIobjPtr\fR arguments, but do require that the +object be unshared. .PP -\fBTcl_SetByteArrayLength\fR converts the Tcl value to byte-array type -and changes the length of the value's internal representation as an -array of bytes. If \fIlength\fR is greater than the space currently -allocated for the array, the array is reallocated to the new length; the -newly allocated bytes at the end of the array have arbitrary values. If -\fIlength\fR is less than the space currently allocated for the array, -the length of array is reduced to the new length. The return value is a -pointer to the value's new array of bytes. +\fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR do not modify +the reference count of \fIobjPtr\fR; they only read. .SH "SEE ALSO" Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount .SH KEYWORDS -value, binary data, byte array, utf, unicode, internationalization +value, binary data, byte array, utf, unicode diff --git a/doc/Cancel.3 b/doc/Cancel.3 index ff2a9b4..027fb09 100644 --- a/doc/Cancel.3 +++ b/doc/Cancel.3 @@ -67,6 +67,14 @@ other procedures. If an error is returned and this bit is set in result, where it can be retrieved with \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR. If this flag bit is not set then no error message is left and the interpreter's result will not be modified. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_CancelEval\fR always decrements the reference count of its +\fIresultObjPtr\fR argument (if that is non-NULL). It is expected to +be usually called with an object with zero reference count. If the +object is shared with some other location (including the Tcl +evaluation stack) it should have its reference count incremented +before calling this function. .SH "SEE ALSO" interp(n), Tcl_Eval(3), TIP 285 diff --git a/doc/Class.3 b/doc/Class.3 index 57203d5..c89c5f4 100644 --- a/doc/Class.3 +++ b/doc/Class.3 @@ -55,6 +55,14 @@ Tcl_ObjectMapMethodNameProc \fBTcl_ObjectGetMethodNameMapper\fR(\fIobject\fR) .sp \fBTcl_ObjectSetMethodNameMapper\fR(\fIobject\fR, \fImethodNameMapper\fR) +.sp +.VS "TIP 605" +Tcl_Class +\fBTcl_GetClassOfObject\fR(\fIobject\fR) +.sp +Tcl_Obj * +\fBTcl_GetObjectClassName\fR(\fIinterp\fR, \fIobject\fR) +.VE "TIP 605" .SH ARGUMENTS .AS ClientData metadata in/out .AP Tcl_Interp *interp in/out @@ -114,6 +122,13 @@ function. Note that the Tcl_Obj reference returned by \fBTcl_GetObjectName\fR is a shared reference. You can also get whether the object has been marked for deletion with \fBTcl_ObjectDeleted\fR (it returns true if deletion of the object has begun); this can be useful during the processing of methods. +.VS "TIP 605" +The class of an object can be retrieved with \fBTcl_GetClassOfObject\fR, and +the name of the class of an object with \fBTcl_GetObjectClassName\fR; note +that these two \fImay\fR return NULL during deletion of an object (this is +transient, and only occurs when the object is a long way through being +deleted). +.VE "TIP 605" .PP Instances of classes are created using \fBTcl_NewObjectInstance\fR, which creates an object from any class (and which is internally called by both @@ -241,6 +256,29 @@ NULL if the whole chain is to be processed (the argument itself is never NULL); this variable may be updated by the callback. The \fImethodNameObj\fR parameter gives an unshared object containing the name of the method being invoked, as provided by the user; this object may be updated by the callback. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIobjPtr\fR argument to \fBTcl_GetObjectFromObj\fR will not have its +reference count manipulated, but this function may modify the interpreter +result (to report any error) so interpreter results should not be fed into +this without an additional reference being used. +.PP +The result of \fBTcl_GetObjectName\fR is a value that is owned by the object +that is regenerated when this function is first called after the object is +renamed. If the value is to be retained at all, the caller should increment +the reference count. +.PP +The first \fIobjc\fR values in the \fIobjv\fR argument to +\fBTcl_NewObjectInstance\fR are the arguments to pass to the constructor. They +must have a reference count of at least 1, and may have their reference counts +changed during the running of the constructor. Constructors may modify the +interpreter result, which consequently means that interpreter results should +not be used as arguments without an additional reference being taken. +.PP +The \fImethodNameObj\fR argument to a Tcl_ObjectMapMethodNameProc +implementation will be a value with a reference count of at least 1 where at +least one reference is not held by the interpreter result. It is expected that +method name mappers will only read their \fImethodNameObj\fR arguments. .SH "SEE ALSO" Method(3), oo::class(n), oo::copy(n), oo::define(n), oo::object(n) .SH KEYWORDS diff --git a/doc/CrtAlias.3 b/doc/CrtAlias.3 index a642d08..77a3bc2 100644 --- a/doc/CrtAlias.3 +++ b/doc/CrtAlias.3 @@ -19,30 +19,24 @@ int int \fBTcl_MakeSafe\fR(\fIinterp\fR) .sp -.VS "TIP 581" Tcl_Interp * \fBTcl_CreateChild\fR(\fIinterp, name, isSafe\fR) -.VE "TIP 581" .sp Tcl_Interp * \fBTcl_CreateSlave\fR(\fIinterp, name, isSafe\fR) .sp -.VS "TIP 581" -Tcl_Interp * -\fBTcl_GetChild\fR(\fIinterp, name\fR) -.VE "TIP 581" -.sp Tcl_Interp * \fBTcl_GetSlave\fR(\fIinterp, name\fR) .sp -.VS "TIP 581" Tcl_Interp * -\fBTcl_GetParent\fR(\fIinterp\fR) -.VE "TIP 581" +\fBTcl_GetChild\fR(\fIinterp, name\fR) .sp Tcl_Interp * \fBTcl_GetMaster\fR(\fIinterp\fR) .sp +Tcl_Interp * +\fBTcl_GetParent\fR(\fIinterp\fR) +.sp int \fBTcl_GetInterpPath\fR(\fIinterp, childInterp\fR) .sp @@ -136,8 +130,8 @@ interpreter. The return value for those procedures that return an \fBint\fR is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned then the interpreter's result contains an error message. .PP -\fBTcl_CreateSlave\fR creates a new interpreter as a child of \fIinterp\fR. -It also creates a child command named \fIchildName\fR in \fIinterp\fR which +\fBTcl_CreateChild\fR creates a new interpreter as a child of \fIinterp\fR. +It also creates a child command named \fIname\fR in \fIinterp\fR which allows \fIinterp\fR to manipulate the new child. If \fIisSafe\fR is zero, the command creates a trusted child in which Tcl code has access to all the Tcl commands. @@ -148,9 +142,7 @@ child in which Tcl code has access only to set of Tcl commands defined as see the manual entry for the Tcl \fBinterp\fR command for details. If the creation of the new child interpreter failed, \fBNULL\fR is returned. .PP -.VS "TIP 581" -\fBTcl_CreateChild\fR is a synonym for \fBTcl_CreateSlave\fR. -.VE "TIP 581" +\fBTcl_CreateSlave\fR is a synonym for \fBTcl_CreateChild\fR. .PP \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is .QW safe @@ -166,24 +158,21 @@ from \fIinterp\fR. However, it cannot know what parts of an extension or application are safe and does not make any attempt to remove those parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR. Callers will want to take care with their use of \fBTcl_MakeSafe\fR -to avoid false claims of safety. For many situations, \fBTcl_CreateSlave\fR +to avoid false claims of safety. For many situations, \fBTcl_CreateChild\fR may be a better choice, since it creates interpreters in a known-safe state. +\fBTcl_MakeSafe\fR is deprecated and will be removed in Tcl 9.0. .PP -\fBTcl_GetSlave\fR returns a pointer to a child interpreter of -\fIinterp\fR. The child interpreter is identified by \fIchildName\fR. +\fBTcl_GetChild\fR returns a pointer to a child interpreter of +\fIinterp\fR. The child interpreter is identified by \fIname\fR. If no such child interpreter exists, \fBNULL\fR is returned. .PP -.VS "TIP 581" -\fBTcl_GetChild\fR is a synonym for \fBTcl_GetSlave\fR. -.VE "TIP 581" +\fBTcl_GetSlave\fR is a synonym for \fBTcl_GetChild\fR. .PP -\fBTcl_GetMaster\fR returns a pointer to the master interpreter of -\fIinterp\fR. If \fIinterp\fR has no master (it is a +\fBTcl_GetParent\fR returns a pointer to the parent interpreter of +\fIinterp\fR. If \fIinterp\fR has no parent (it is a top-level interpreter) then \fBNULL\fR is returned. .PP -.VS "TIP 581" -\fBTcl_GetParent\fR is a synonym for \fBTcl_GetMaster\fR. -.VE "TIP 581" +\fBTcl_GetMaster\fR is a synonym for \fBTcl_GetParent\fR. .PP \fBTcl_GetInterpPath\fR stores in the result of \fIinterp\fR the relative path between \fIinterp\fR and \fIchildInterp\fR; @@ -201,7 +190,7 @@ This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if it fails; in that case, an error message is left in the value result of \fIchildInterp\fR. Note that there are no restrictions on the ancestry relationship (as -created by \fBTcl_CreateSlave\fR) between \fIchildInterp\fR and +created by \fBTcl_CreateChild\fR) between \fIchildInterp\fR and \fItargetInterp\fR. Any two interpreters can be used, without any restrictions on how they are related. .PP @@ -255,8 +244,16 @@ any script evaluation mechanism will fail. .PP For a description of the Tcl interface to multiple interpreters, see \fIinterp(n)\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_CreateAliasObj\fR increments the reference counts of the values +in its \fIobjv\fR argument. (That reference lasts the same length of +time as the owning alias.) +.PP +\fBTcl_GetAliasObj\fR returns (via its \fIobjvPtr\fR argument) a +pointer to values that it holds a reference to. .SH "SEE ALSO" -interp +interp(n) .SH KEYWORDS alias, command, exposed commands, hidden commands, interpreter, invoke, diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index 0092cfb..1496631 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -35,6 +35,11 @@ Tcl_ThreadId int \fBTcl_GetChannelMode\fR(\fIchannel\fR) .sp +.VS 8.7 +int +\fBTcl_RemoveChannelMode\fR(\fIinterp, channel, mode\fR) +.VE 8.7 +.sp int \fBTcl_GetChannelBufferSize\fR(\fIchannel\fR) .sp @@ -243,6 +248,16 @@ events to the correct event queue even for a multi-threaded core. and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input and output. .PP +.VS 8.7 +.PP +\fBTcl_RemoveChannelMode\fR removes an access privilege from the +channel, either \fBTCL_READABLE\fR or \fBTCL_WRITABLE\fR, and returns +a regular Tcl result code, \fBTCL_OK\fR, or \fBTCL_ERROR\fR. The +function throws an error if either an invalid mode is specified or the +result of the removal would be an inaccessible channel. In that case +an error message is left in the interp argument, if not NULL. +.VE 8.7 +.PP \fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers allocated to store input or output in \fIchannel\fR. If the value was not set by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then @@ -600,9 +615,9 @@ in preference to the \fIseekProc\fR, but both must be defined if the following prototype: .PP .CS -typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR( +typedef long long \fBTcl_DriverWideSeekProc\fR( ClientData \fIinstanceData\fR, - Tcl_WideInt \fIoffset\fR, + long long \fIoffset\fR, int \fIseekMode\fR, int *\fIerrorCodePtr\fR); .CE @@ -824,7 +839,7 @@ length. It can be NULL. .CS typedef int \fBTcl_DriverTruncateProc\fR( ClientData \fIinstanceData\fR, - Tcl_WideInt \fIlength\fR); + long long \fIlength\fR); .CE .PP \fIInstanceData\fR is the same as the value passed to 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/CrtMathFnc.3 b/doc/CrtMathFnc.3 index acceb5b..bb96fc9 100644 --- a/doc/CrtMathFnc.3 +++ b/doc/CrtMathFnc.3 @@ -156,6 +156,10 @@ pointed to by \fIargTypesPointer\fR. \fBTcl_ListMathFuncs\fR returns a Tcl value containing a list of all the math functions defined in the interpreter whose name matches \fIpattern\fR. The returned value has a reference count of zero. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_ListMathFuncs\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. .SH "SEE ALSO" expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3) .SH KEYWORDS diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 index 6025c68..bb63937 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_CreateObjCommand2, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj \- implement new commands in C .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -16,6 +16,9 @@ Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetComm Tcl_Command \fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR) .sp +Tcl_Command +\fBTcl_CreateObjCommand2\fR(\fIinterp, cmdName, proc2, clientData, deleteProc\fR) +.sp int \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR) .sp @@ -42,6 +45,7 @@ void .sp Tcl_Command \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR) +.sp .SH ARGUMENTS .AS Tcl_CmdDeleteProc *deleteProc in/out .AP Tcl_Interp *interp in @@ -51,6 +55,9 @@ Name of command. .AP Tcl_ObjCmdProc *proc in Implementation of the new command: \fIproc\fR will be called whenever \fIcmdName\fR is invoked as a command. +.AP Tcl_ObjCmdProc2 *proc2 in +Implementation of the new command: \fIproc2\fR will be called whenever +\fIcmdName\fR is invoked as a command. .AP ClientData clientData in Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR. .AP Tcl_CmdDeleteProc *deleteProc in @@ -65,6 +72,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 @@ -170,6 +180,17 @@ typedef void \fBTcl_CmdDeleteProc\fR( The \fIclientData\fR argument will be the same as the \fIclientData\fR argument passed to \fBTcl_CreateObjCommand\fR. .PP +\fBTcl_CreateObjCommand2\fR does the same as \fBTcl_CreateObjCommand\fR, +except its \fIproc2\fR argument is of type \fBTcl_ObjCmdProc2\fR. +.PP +.CS +typedef int \fBTcl_ObjCmdProc2\fR( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + Tcl_Size \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[]); +.CE +.PP \fBTcl_DeleteCommand\fR deletes a command from a command interpreter. Once the call completes, attempts to invoke \fIcmdName\fR in \fIinterp\fR will result in errors. @@ -296,6 +317,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 +.SH "REFERENCE COUNT MANAGEMENT" +.PP +When the \fIproc\fR passed to \fBTcl_CreateObjCommand\fR is called, +the values in its \fIobjv\fR argument will have a reference count of +at least 1, with that guaranteed reference being from the Tcl +evaluation stack. You should not call \fBTcl_DecrRefCount\fR on any of +those values unless you call \fBTcl_IncrRefCount\fR on them first. +Also, when the \fIproc\fR is called, the interpreter result is +guaranteed to be an empty string value with a reference count of 1. +.PP +\fBTcl_GetCommandFullName\fR does not modify the reference count of its +\fIobjPtr\fR argument, but does require that the object be unshared. +.PP +\fBTcl_GetCommandFromObj\fR does not modify the reference count of its +\fIobjPtr\fR argument; it only reads. .SH "SEE ALSO" Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3) .SH KEYWORDS diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3 index f1f1d30..519f348 100644 --- a/doc/CrtTrace.3 +++ b/doc/CrtTrace.3 @@ -10,7 +10,7 @@ .so man.macros .BS .SH NAME -Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced +Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_CreateObjTrace2, Tcl_DeleteTrace \- arrange for command execution to be traced .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -21,6 +21,9 @@ Tcl_Trace Tcl_Trace \fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR) .sp +Tcl_Trace +\fBTcl_CreateObjTrace2\fR(\fIinterp, level, flags, objProc2, clientData, deleteProc\fR) +.sp \fBTcl_DeleteTrace\fR(\fIinterp, trace\fR) .SH ARGUMENTS .AS Tcl_CmdObjTraceDeleteProc *deleteProc @@ -38,11 +41,14 @@ Flags governing the trace execution. See below for details. .AP Tcl_CmdObjTraceProc *objProc in Procedure to call for each command that is executed. See below for details of the calling sequence. +.AP Tcl_CmdObjTraceProc2 *objProc2 in +Procedure to call for each command that is executed. See below for +details of the calling sequence. .AP Tcl_CmdTraceProc *proc in Procedure to call for each command that is executed. See below for details on the calling sequence. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR. +.AP void *clientData in +Arbitrary one-word value to pass to \fIobjProc\fR, \fIobjProc2\fR or \fIproc\fR. .AP Tcl_CmdObjTraceDeleteProc *deleteProc in Procedure to call when the trace is deleted. See below for details of the calling sequence. A NULL pointer is permissible and results in no @@ -66,7 +72,7 @@ interpreter. .PP .CS typedef int \fBTcl_CmdObjTraceProc\fR( - \fBClientData\fR \fIclientData\fR, + \fBvoid *\fR \fIclientData\fR, \fBTcl_Interp\fR* \fIinterp\fR, int \fIlevel\fR, const char *\fIcommand\fR, @@ -75,6 +81,20 @@ typedef int \fBTcl_CmdObjTraceProc\fR( \fBTcl_Obj\fR *const \fIobjv\fR[]); .CE .PP +\fIobjProc2\fR should have arguments and result that match the type, +\fBTcl_CmdObjTraceProc2\fR: +.PP +.CS +typedef int \fBTcl_CmdObjTraceProc2\fR( + \fBvoid *\fR \fIclientData\fR, + \fBTcl_Interp\fR* \fIinterp\fR, + Tcl_Size \fIlevel\fR, + const char *\fIcommand\fR, + \fBTcl_Command\fR \fIcommandToken\fR, + Tcl_Size \fIobjc\fR, + \fBTcl_Obj\fR *const \fIobjv\fR[]); +.CE +.PP The \fIclientData\fR and \fIinterp\fR parameters are copies of the corresponding arguments given to \fBTcl_CreateTrace\fR. \fIClientData\fR typically points to an application-specific data @@ -140,7 +160,7 @@ When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the .PP .CS typedef void \fBTcl_CmdObjTraceDeleteProc\fR( - \fBClientData\fR \fIclientData\fR); + \fBvoid *\fR \fIclientData\fR); .CE .PP The \fIclientData\fR parameter will be the same as the @@ -156,12 +176,12 @@ match the type \fBTcl_CmdTraceProc\fR: .PP .CS typedef void \fBTcl_CmdTraceProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIlevel\fR, char *\fIcommand\fR, Tcl_CmdProc *\fIcmdProc\fR, - ClientData \fIcmdClientData\fR, + void *\fIcmdClientData\fR, int \fIargc\fR, const char *\fIargv\fR[]); .CE @@ -183,5 +203,14 @@ There is no way to be notified when the trace created by \fBTcl_CreateTrace\fR is deleted. There is no way for the \fIproc\fR associated with a call to \fBTcl_CreateTrace\fR to abort execution of \fIcommand\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +When the \fIproc\fR passed to \fBTcl_CreateObjTrace\fR is called, +the values in its \fIobjv\fR argument will have a reference count of +at least 1, with that guaranteed reference being from the Tcl +evaluation stack. You should not call \fBTcl_DecrRefCount\fR on any of +those values unless you call \fBTcl_IncrRefCount\fR on them first. +.SH "SEE ALSO" +trace(n) .SH KEYWORDS command, create, delete, interpreter, trace diff --git a/doc/DString.3 b/doc/DString.3 index 00f1b8a..33dd297 100644 --- a/doc/DString.3 +++ b/doc/DString.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings +Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult, Tcl_DStringToObj \- manipulate dynamic strings .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -41,6 +41,10 @@ char * \fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR) .sp \fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR) +.sp +Tcl_Obj * +\fBTcl_DStringToObj\fR(\fIdsPtr\fR) +.sp .SH ARGUMENTS .AS Tcl_DString newLength in/out .AP Tcl_DString *dsPtr in/out @@ -142,12 +146,25 @@ a pointer from \fIdsPtr\fR to the interpreter's result. This saves the cost of allocating new memory and copying the string. \fBTcl_DStringResult\fR also reinitializes the dynamic string to an empty string. +Since the dynamic string is reinitialized, there is no need to +further call \fBTcl_DStringFree\fR on it and it can be reused without +calling \fBTcl_DStringInit\fR. .PP \fBTcl_DStringGetResult\fR does the opposite of \fBTcl_DStringResult\fR. It sets the value of \fIdsPtr\fR to the result of \fIinterp\fR and it clears \fIinterp\fR's result. If possible it does this by moving a pointer rather than by copying the string. +.PP +\fBTcl_DStringToObj\fR returns a \fBTcl_Obj\fR containing the value of +the dynamic string given by \fIdsPtr\fR. It does this by moving +a pointer from \fIdsPtr\fR to a newly allocated \fBTcl_Obj\fR +and reinitializing to dynamic string to an empty string. +This saves the cost of allocating new memory and copying the string. +Since the dynamic string is reinitialized, there is no need to +further call \fBTcl_DStringFree\fR on it and it can be reused without +calling \fBTcl_DStringInit\fR. +The returned \fBTcl_Obj\fR has a reference count of 0. .SH KEYWORDS append, dynamic string, free, result diff --git a/doc/DictObj.3 b/doc/DictObj.3 index 2c111c4..0b4c1ca 100644 --- a/doc/DictObj.3 +++ b/doc/DictObj.3 @@ -190,6 +190,73 @@ path as this is easy to construct from repeated use of dictionaries are created for non-terminal keys where they do not already exist. With \fBTcl_DictObjRemoveKeyList\fR, all non-terminal keys must exist and have dictionaries as their values. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewDictObj\fR always returns a zero-reference object, much like +\fBTcl_NewObj\fR. +.PP +\fBTcl_DictObjPut\fR does not modify the reference count of its \fIdictPtr\fR +argument, but does require that the object be unshared. If +\fBTcl_DictObjPut\fR returns \fBTCL_ERROR\fR it does not manipulate any +reference counts; but if it returns \fBTCL_OK\fR then it definitely increments +the reference count of \fIvaluePtr\fR and may increment the reference count of +\fIkeyPtr\fR; the latter case happens exactly when the key did not previously +exist in the dictionary. Note however that this function may set the +interpreter result; if that is the only place that is holding a reference to +an object, it will be deleted. +.PP +\fBTcl_DictObjGet\fR only reads from its \fIdictPtr\fR and \fIkeyPtr\fR +arguments, and does not manipulate their reference counts at all. If the +\fIvaluePtrPtr\fR argument is not set to NULL (and the function doesn't return +\fBTCL_ERROR\fR), it will be set to a value with a reference count of at least +1, with a reference owned by the dictionary. Note however that this function +may set the interpreter result; if that is the only place that is holding a +reference to an object, it will be deleted. +.PP +\fBTcl_DictObjRemove\fR does not modify the reference count of its +\fIdictPtr\fR argument, but does require that the object be unshared. It does +not manipulate the reference count of its \fIkeyPtr\fR argument at all. Note +however that this function may set the interpreter result; if that is the only +place that is holding a reference to an object, it will be deleted. +.PP +\fBTcl_DictObjSize\fR does not modify the reference count of its \fIdictPtr\fR +argument; it only reads. Note however that this function may set the +interpreter result; if that is the only place that is holding a reference to +the dictionary object, it will be deleted. +.PP +\fBTcl_DictObjFirst\fR does not modify the reference count of its +\fIdictPtr\fR argument; it only reads. The variables given by the +\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated +to contain references to the relevant values in the dictionary; their +reference counts will be at least 1 (due to the dictionary holding a reference +to them). It may also manipulate internal references; these are not exposed to +user code, but require a matching \fBTcl_DictObjDone\fR call. Note however +that this function may set the interpreter result; if that is the only place +that is holding a reference to the dictionary object, it will be deleted. +.PP +Similarly for \fBTcl_DictObjNext\fR; the variables given by the +\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated +to contain references to the relevant values in the dictionary; their +reference counts will be at least 1 (due to the dictionary holding a reference +to them). +.PP +\fBTcl_DictObjDone\fR does not manipulate (user-visible) reference counts. +.PP +\fBTcl_DictObjPutKeyList\fR is similar to \fBTcl_DictObjPut\fR; it does not +modify the reference count of its \fIdictPtr\fR argument, but does require +that the object be unshared. It may increment the reference count of any value +passed in the \fIkeyv\fR argument, and will increment the reference count of +the \fIvaluePtr\fR argument on success. It is recommended that values passed +via \fIkeyv\fR and \fIvaluePtr\fR do not have zero reference counts. Note +however that this function may set the interpreter result; if that is the only +place that is holding a reference to an object, it will be deleted. +.PP +\fBTcl_DictObjRemoveKeyList\fR is similar to \fBTcl_DictObjRemove\fR; it does +not modify the reference count of its \fIdictPtr\fR argument, but does require +that the object be unshared, and does not modify the reference counts of any +of the values passed in the \fIkeyv\fR argument. Note however that this +function may set the interpreter result; if that is the only place that is +holding a reference to an object, it will be deleted. .SH EXAMPLE Using the dictionary iteration interface to search determine if there is a key that maps to itself: diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3 index 85e4de5..c70f5d1 100644 --- a/doc/DoubleObj.3 +++ b/doc/DoubleObj.3 @@ -58,6 +58,18 @@ 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 \fBTcl_GetDoubleFromObj\fR more efficient. '\" TODO: add discussion of treatment of NaN value +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewDoubleObj\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_SetDoubleObj\fR does not modify the reference count of its +\fIobjPtr\fR argument, but does require that the object be unshared. +.PP +\fBTcl_GetDoubleFromObj\fR does not modify the reference count of its +\fIobjPtr\fR argument; it only reads. Note however that this function +may set the interpreter result; if that is the only place that +is holding a reference to the object, it will be deleted. .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult .SH KEYWORDS diff --git a/doc/Encoding.3 b/doc/Encoding.3 index 79fca0f..c357ecd 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_ExternalToUtfDStringEx, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternalDStringEx, 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 @@ -25,10 +25,16 @@ int char * \fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR) .sp +int +\fBTcl_ExternalToUtfDStringEx\fR(\fIinterp, encoding, src, srcLen, flags, dstPtr, errorIdxPtr\fR) +.sp char * \fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR) .sp int +\fBTcl_UtfToExternalDStringEx\fR(\fIinterp, encoding, src, srcLen, flags, dstPtr, errorIdxPtr\fR) +.sp +int \fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR) .sp @@ -46,6 +52,9 @@ const char * \fBTcl_GetEncodingName\fR(\fIencoding\fR) .sp int +\fBTcl_GetEncodingNulLength\fR(\fIencoding\fR) +.sp +int \fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR) .sp const char * @@ -96,7 +105,7 @@ encoding-specific length of the string is used. Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted result will be stored. .AP int flags in -Various flag bits OR-ed together. +This is a bit mask passed in to control the operation of the encoding functions. \fBTCL_ENCODING_START\fR signifies that the source buffer is the first block in a (potentially multi-block) input stream, telling the conversion routine to reset to an initial state and @@ -104,11 +113,15 @@ perform any initialization that needs to occur before the first byte is converted. \fBTCL_ENCODING_END\fR signifies that the source buffer is the last block in a (potentially multi-block) input stream, telling the conversion routine to perform any finalization that needs to occur after the last -byte is converted and then to reset to an initial state. -\fBTCL_ENCODING_STOPONERROR\fR signifies that the conversion routine should -return immediately upon reading a source character that does not exist in -the target encoding; otherwise a default fallback character will -automatically be substituted. +byte is converted and then to reset to an initial state. The +\fBTCL_PROFILE_*\fR bits defined in the \fBPROFILES\fR section below +control the encoding profile to be used for dealing with invalid data or +other errors in the encoding transform. +\fBTCL_ENCODING_STOPONERROR\fR is present for backward compatibility with +Tcl 8.6 and forces the encoding profile to \fBstrict\fR. + +Some flags bits may not be usable with some functions as noted in the +function descriptions below. .AP Tcl_EncodingState *statePtr in/out Used when converting a (generally long or indefinite length) byte stream in a piece-by-piece fashion. The conversion routine stores its current @@ -134,6 +147,9 @@ buffer as a result of the conversion. May be NULL. .AP int *dstCharsPtr out Filled with the number of characters that correspond to the number of bytes stored in the output buffer. May be NULL. +.AP int *errorIdxPtr out +Filled with the index of the byte or character that caused the encoding transform +to fail. May be NULL. .AP Tcl_DString *bufPtr out Storage for the prescribed system encoding name. .AP "const Tcl_EncodingType" *typePtr in @@ -208,6 +224,27 @@ When converting, if any of the characters in the source buffer cannot be represented in the target encoding, a default fallback character will be used. The return value is a pointer to the value stored in the DString. .PP +\fBTcl_ExternalToUtfDStringEx\fR is a more flexible version of older +\fBTcl_ExternalToUtfDString\fR function. It takes three additional parameters, +\fBinterp\fR, \fBflags\fR and \fBerrorIdxPtr\fR. The \fBflags\fR parameter may +be used to specify the profile to be used for the transform. The +\fBTCL_ENCODING_START\fR and \fBTCL_ENCODING_END\fR bits in \fBflags\fR are +ignored as the function assumes the entire source string to be decoded is passed +into the function. On success, the function returns \fBTCL_OK\fR with the +converted string stored in \fB*dstPtr\fR. For errors \fIother than conversion +errors\fR, such as invalid flags, the function returns \fBTCL_ERROR\fR with an error +message in \fBinterp\fR if it is not NULL. +For conversion errors, \fBTcl_ExternalToUtfDStringEx\fR returns one +of the \fBTCL_CONVERT_*\fR errors listed below for \fBTcl_ExternalToUtf\fR. +When one of these conversion errors is returned, an error message is +stored in \fBinterp\fR only if \fBerrorIdxPtr\fR is NULL. Otherwise, no error message +is stored as the function expects the caller is interested the decoded data +up to that point and not treating this as an immediate error condition. +The index of the error location is stored in \fB*errorIdxPtr\fR. +.PP +The caller must call \fBTcl_DStringFree\fR to free up the \fB*dstPtr\fR resources +irrespective of the return value from the function. +.PP \fBTcl_ExternalToUtf\fR converts a source buffer \fIsrc\fR from the specified \fIencoding\fR into UTF-8. Up to \fIsrcLen\fR bytes are converted from the source buffer and up to \fIdstLen\fR converted bytes are stored in \fIdst\fR. @@ -229,12 +266,12 @@ the unconverted bytes that remained in \fIsrc\fR plus some further bytes from the source stream to properly convert the formerly split-up multibyte sequence. .IP \fBTCL_CONVERT_SYNTAX\fR 29 -The source buffer contained an invalid character sequence. This may occur +The source buffer contained an invalid byte or character sequence. This may occur if the input stream has been damaged or if the input encoding method was misidentified. .IP \fBTCL_CONVERT_UNKNOWN\fR 29 The source buffer contained a character that could not be represented in -the target encoding and \fBTCL_ENCODING_STOPONERROR\fR was specified. +the target encoding. .RE .LP \fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8 @@ -246,6 +283,15 @@ characters in the source buffer cannot be represented in the target encoding, a default fallback character will be used. The return value is a pointer to the value stored in the DString. .PP +\fBTcl_UtfToExternalDStringEx\fR is an enhanced version of +\fBTcl_UtfToExternalDString\fR that transforms UTF-8 encoded source data to a specified +\fIencoding\fR. Except for the direction of the transform, the parameters and +return values are identical to those of \fBTcl_ExternalToUtfDStringEx\fR. See +that function above for details about the same. + +Irrespective of the return code from the function, the caller must free +resources associated with \fB*dstPtr\fR when the function returns. +.PP \fBTcl_UtfToExternal\fR converts a source buffer \fIsrc\fR from UTF-8 into the specified \fIencoding\fR. Up to \fIsrcLen\fR bytes are converted from the source buffer and up to \fIdstLen\fR converted bytes are stored in @@ -255,11 +301,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 @@ -267,6 +319,9 @@ was used to create the encoding. The string returned by \fBTcl_GetEncodingName\fR is only guaranteed to persist until the \fIencoding\fR is deleted. The caller must not modify this string. .PP +\fBTcl_GetEncodingNulLength\fR returns the length of the terminating +nul byte sequence for strings in the specified encoding. +.PP \fBTcl_SetSystemEncoding\fR sets the default encoding that should be used whenever the user passes a NULL value for the \fIencoding\fR argument to any of the other encoding functions. If \fIname\fR is NULL, the system @@ -314,7 +369,7 @@ typedef struct Tcl_EncodingType { Tcl_EncodingConvertProc *\fItoUtfProc\fR; Tcl_EncodingConvertProc *\fIfromUtfProc\fR; Tcl_EncodingFreeProc *\fIfreeProc\fR; - ClientData \fIclientData\fR; + void *\fIclientData\fR; int \fInullSize\fR; } \fBTcl_EncodingType\fR; .CE @@ -345,7 +400,7 @@ type \fBTcl_EncodingConvertProc\fR: .PP .CS typedef int \fBTcl_EncodingConvertProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, const char *\fIsrc\fR, int \fIsrcLen\fR, int \fIflags\fR, @@ -377,7 +432,7 @@ The callback procedure \fIfreeProc\fR, if non-NULL, should match the type .PP .CS typedef void \fBTcl_EncodingFreeProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP This \fIfreeProc\fR function is called when the encoding is deleted. The @@ -524,13 +579,13 @@ encoding: E init {} final {} -iso8859-1 \ex1b(B -jis0201 \ex1b(J -jis0208 \ex1b$@ -jis0208 \ex1b$B -jis0212 \ex1b$(D -gb2312 \ex1b$A -ksc5601 \ex1b$(C +iso8859-1 \ex1B(B +jis0201 \ex1B(J +jis0208 \ex1B$@ +jis0208 \ex1B$B +jis0212 \ex1B$(D +gb2312 \ex1B$A +ksc5601 \ex1B$(C .CE .PP In the file, the first column represents an option and the second column @@ -542,7 +597,7 @@ marks that encoding. Tcl syntax is used for the values; in the above example, for instance, .QW \fB{}\fR represents the empty string and -.QW \fB\ex1b\fR +.QW \fB\ex1B\fR represents character 27. .PP When \fBTcl_GetEncoding\fR encounters an encoding \fIname\fR that has not @@ -550,5 +605,28 @@ been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR from the \fBencoding\fR subdirectory of each directory that Tcl searches for its script library. If the encoding file exists, but is malformed, an error message will be left in \fIinterp\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_GetEncodingFromObj\fR does not modify the reference count of its +\fIobjPtr\fR argument; it only reads. Note however that this function may set +the interpreter result; if that is the only place that is holding a reference +to the object, it will be deleted. +.PP +\fBTcl_GetEncodingSearchPath\fR returns an object with a reference count of at +least 1. +.SH "PROFILES" +Encoding profiles define the manner in which errors in the encoding transforms +are handled by the encoding functions. An application can specify the profile +to be used by OR-ing the \fBflags\fR parameter passed to the function +with at most one of \fBTCL_ENCODING_PROFILE_TCL8\fR, +\fBTCL_ENCODING_PROFILE_STRICT\fR or \fBTCL_ENCODING_PROFILE_REPLACE\fR. +These correspond to the \fBtcl8\fR, \fBstrict\fR and \fBreplace\fR profiles +respectively. If none are specified, a version-dependent default profile is used. +For Tcl 8.7, the default profile is \fBtcl8\fR. +.PP +For details about profiles, see the \fBPROFILES\fR section in +the documentation of the \fBencoding\fR command. +.SH "SEE ALSO" +encoding(n) .SH KEYWORDS utf, encoding, convert diff --git a/doc/Ensemble.3 b/doc/Ensemble.3 index 93aa458..71a53ac 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) . @@ -213,6 +209,27 @@ namespace whose list of exported commands is used if both the mapping dictionary and the subcommand list properties are NULL. May be read using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an ensemble). +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_FindEnsemble\fR does not modify the reference count of its +\fIcmdNameObj\fR argument; it only reads. Note however that this function may +set the interpreter result; if that is the only place that is holding a +reference to the object, it will be deleted. +.PP +The ensemble property getters (\fBTcl_GetEnsembleMappingDict\fR, +\fBTcl_GetEnsembleParameterList\fR, \fBTcl_GetEnsembleSubcommandList\fR, and +\fBTcl_GetEnsembleUnknownHandler\fR) do not manipulate the reference count of +the values they provide out; if those are non-NULL, they will have a reference +count of at least 1. Note that these functions may set the interpreter +result. +.PP +The ensemble property setters (\fBTcl_SetEnsembleMappingDict\fR, +\fBTcl_SetEnsembleParameterList\fR, \fBTcl_SetEnsembleSubcommandList\fR, and +\fBTcl_SetEnsembleUnknownHandler\fR) will increment the reference count of the +new value of the property they are given if they succeed (and decrement the +reference count of the old value of the property, if relevant). If the +property setters return \fBTCL_ERROR\fR, the reference count of the Tcl_Obj +argument is left unchanged. .SH "SEE ALSO" namespace(n), Tcl_DeleteCommandFromToken(3) .SH KEYWORDS @@ -99,13 +99,11 @@ its contents as a Tcl script. It returns the same information as If the file could not be read then a Tcl error is returned to describe why the file could not be read. The eofchar for files is -.QW \e32 +.QW \ex1A (^Z) for all platforms. If you require a .QW ^Z in code for string comparison, you can use -.QW \e032 -or -.QW \eu001a , +.QW \ex1A , which will be safely substituted by the Tcl interpreter into .QW ^Z . .PP @@ -150,13 +148,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. .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. \fBTcl_VarEvalVA\fR is now 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 @@ -206,6 +205,20 @@ the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was invoked in an inappropriate place. This means that top-level applications should never see a return code from \fBTcl_EvalObjEx\fR other than \fBTCL_OK\fR or \fBTCL_ERROR\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_EvalObjEx\fR and \fBTcl_GlobalEvalObj\fR both increment and +decrement the reference count of their \fIobjPtr\fR argument; you must +not pass them any value with a reference count of zero. They also +manipulate the interpreter result; you must not count on the +interpreter result to hold the reference count of any value over +these calls. +.PP +\fBTcl_EvalObjv\fR may increment and decrement the reference count of +any value passed via its \fIobjv\fR argument; you must not pass any +value with a reference count of zero. This function also manipulates +the interpreter result; you must not count on the interpreter result +to hold the reference count of any value over this call. .SH KEYWORDS execute, file, global, result, script, value @@ -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/ExprLongObj.3 b/doc/ExprLongObj.3 index 837e0a8..59413e1 100644 --- a/doc/ExprLongObj.3 +++ b/doc/ExprLongObj.3 @@ -98,6 +98,15 @@ containing the expression's value at \fI*resultPtrPtr\fR. In this case, the caller is responsible for calling \fBTcl_DecrRefCount\fR to decrement the value's reference count when it is finished with the value. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR, +\fBTcl_ExprBooleanObj\fR, and \fBTcl_ExprObj\fR all increment and +decrement the reference count of their \fIobjPtr\fR arguments; you +must not pass them any value with a reference count of zero. They also +manipulate the interpreter result; you must not count on the +interpreter result to hold the reference count of any value over these +calls. .SH "SEE ALSO" Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index 2db2485..f36a574 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.3 @@ -45,7 +45,7 @@ int \fBTcl_FSDeleteFile\fR(\fIpathPtr\fR) .sp int -\fBTcl_FSRemoveDirectory\fR(\fIpathPtr, int recursive, errorPtr\fR) +\fBTcl_FSRemoveDirectory\fR(\fIpathPtr, recursive, errorPtr\fR) .sp int \fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR) @@ -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) @@ -81,10 +79,10 @@ int \fBTcl_FSUtime\fR(\fIpathPtr, tval\fR) .sp int -\fBTcl_FSFileAttrsGet\fR(\fIinterp, int index, pathPtr, objPtrRef\fR) +\fBTcl_FSFileAttrsGet\fR(\fIinterp, index, pathPtr, objPtrRef\fR) .sp int -\fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR) +\fBTcl_FSFileAttrsSet\fR(\fIinterp, index, pathPtr, objPtr\fR) .sp const char *const * \fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR) @@ -146,17 +144,16 @@ Tcl_Obj * Tcl_StatBuf * \fBTcl_AllocStatBuf\fR() .sp -.VS 8.6 -Tcl_WideInt +long long \fBTcl_GetAccessTimeFromStat\fR(\fIstatPtr\fR) .sp unsigned \fBTcl_GetBlockSizeFromStat\fR(\fIstatPtr\fR) .sp -Tcl_WideUInt +unsigned long long \fBTcl_GetBlocksFromStat\fR(\fIstatPtr\fR) .sp -Tcl_WideInt +long long \fBTcl_GetChangeTimeFromStat\fR(\fIstatPtr\fR) .sp int @@ -177,15 +174,14 @@ int unsigned \fBTcl_GetModeFromStat\fR(\fIstatPtr\fR) .sp -Tcl_WideInt +long long \fBTcl_GetModificationTimeFromStat\fR(\fIstatPtr\fR) .sp -Tcl_WideUInt +unsigned long long \fBTcl_GetSizeFromStat\fR(\fIstatPtr\fR) .sp int \fBTcl_GetUserIdFromStat\fR(\fIstatPtr\fR) -.VE 8.6 .SH ARGUMENTS .AS Tcl_GlobTypeData **srcPathPtr out .AP "const Tcl_Filesystem" *fsPtr in @@ -201,6 +197,8 @@ rename operation. .AP Tcl_Obj *destPathPtr in As for \fIpathPtr\fR, but used for the destination filename for a copy or rename operation. +.AP int recursive in +Whether to remove subdirectories and their contents as well. .AP "const char" *encoding in The encoding of the data stored in the file identified by \fIpathPtr\fR and to be evaluated. @@ -228,6 +226,10 @@ be joined together. If negative, then all elements are joined. .AP Tcl_Obj **errorPtr out In the case of an error, filled with a value containing the name of the file which caused an error in the various copy/rename operations. +.AP int index in +The index of the attribute in question. +.AP Tcl_Obj *objPtr in +The value to set in the operation. .AP Tcl_Obj **objPtrRef out Filled with a value containing the result of the operation. .AP Tcl_Obj *resultPtr out @@ -245,9 +247,9 @@ The structure that contains the result of a stat or lstat operation. Name of a procedure to look up in the file's symbol table .AP "const char" *sym2 in Name of a procedure to look up in the file's symbol table -.AP Tcl_PackageInitProc **proc1Ptr out +.AP Tcl_LibraryInitProc **proc1Ptr out Filled with the init function for this code. -.AP Tcl_PackageInitProc **proc2Ptr out +.AP Tcl_LibraryInitProc **proc2Ptr out Filled with the safe-init function for this code. .AP ClientData *clientDataPtr out Filled with the clientData value to pass to this code's unload @@ -418,23 +420,21 @@ caller (with a reference count of 0). the encoding identified by \fIencoding\fR and evaluates its contents as a Tcl script. It returns the same information as \fBTcl_EvalObjEx\fR. -If \fIencoding\fR is NULL, the system encoding is used for +If \fIencoding\fR is NULL, the utf-8 encoding is used for reading the file contents. If the file could not be read then a Tcl error is returned to describe why the file could not be read. The eofchar for files is -.QW \e32 +.QW \ex1A (^Z) for all platforms. If you require a .QW ^Z in code for string comparison, you can use -.QW \e032 -or -.QW \eu001a , +.QW \ex1A , which will be safely substituted by the Tcl interpreter into .QW ^Z . \fBTcl_FSEvalFile\fR is a simpler version of -\fBTcl_FSEvalFileEx\fR that always uses the system encoding +\fBTcl_FSEvalFileEx\fR that always uses the utf-8 encoding when reading the file. .PP \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and @@ -444,20 +444,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 @@ -653,7 +649,7 @@ filesystem object. It returns 1 if the paths are equal, and 0 if they are different. If either path is NULL, 0 is always returned. .PP -\fBTcl_FSGetNormalizedPath\fR this important function attempts to extract +\fBTcl_FSGetNormalizedPath\fR attempts to extract from the given Tcl_Obj a unique normalized path representation, whose string value can be used as a unique identifier for the file. .PP @@ -795,7 +791,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 +814,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 @@ -1638,6 +1632,158 @@ typedef int \fBTcl_FSChdirProc\fR( The \fBTcl_FSChdirProc\fR changes the applications current working directory to the value specified in \fIpathPtr\fR. The function returns -1 on error or 0 on success. +.SH "REFERENCE COUNT MANAGEMENT" +.SS "PUBLIC API CALLS" +.PP +For all of these functions, \fIpathPtr\fR (including the \fIsrcPathPtr\fR and +\fIdestPathPtr\fR arguments to \fBTcl_FSCopyFile\fR, +\fBTcl_FSCopyDirectory\fR, and \fBTcl_FSRenameFile\fR, the \fIfirstPtr\fR and +\fIsecondPtr\fR arguments to \fBTcl_FSEqualPaths\fR, and the \fIlinkNamePtr\fR +and \fItoPtr\fR arguments to \fBTcl_FSLink\fR) must not be a zero reference +count value; references may be retained in internal caches even for +theoretically read-only operations. These functions may also manipulate the +interpreter result (if they take and are given a non-NULL \fIinterp\fR +argument); you must not count on the interpreter result to hold the reference +count of any argument value over these calls and should manage your own +references there. However, references held by the arguments to a Tcl command +\fIare\fR suitable for reference count management purposes for the duration of +the implementation of that command. +.PP +The \fIerrorPtr\fR argument to \fBTcl_FSCopyDirectory\fR and +\fBTcl_FSRemoveDirectory\fR is, when an object is set into it at all, set to +an object with a non-zero reference count that should be passed to +\fBTcl_DecrRefCount\fR when no longer needed. +.PP +\fBTcl_FSListVolumes\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_FSLink\fR always returns a non-zero-reference object when it is +asked to read; you must call \fBTcl_DecrRefCount\fR on the object +once you no longer need it. +.PP +\fBTcl_FSGetCwd\fR always returns a non-zero-reference object; you +must call \fBTcl_DecrRefCount\fR on the object once you no longer need +it. +.PP +\fBTcl_FSPathSeparator\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_FSJoinPath\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. Its \fIlistObj\fR argument can have any reference +count; it is only read by this function. +.PP +\fBTcl_FSSplitPath\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_FSGetNormalizedPath\fR returns an object with a non-zero +reference count where Tcl is the owner. You should increment its +reference count if you want to retain it, but do not need to if you +are just using the value immediately. +.PP +\fBTcl_FSJoinToPath\fR always returns a zero-reference object, much like +\fBTcl_NewObj\fR. Its \fIbasePtr\fR argument follows the rules above for +\fIpathPtr\fR, as do the values in the \fIobjv\fR argument. +.PP +\fBTcl_FSGetTranslatedPath\fR returns a non-zero-reference object (or +NULL in the error case); you must call \fBTcl_DecrRefCount\fR on the +object once you no longer need it. +.PP +\fBTcl_FSNewNativePath\fR always returns a zero-reference object (or +NULL), much like \fBTcl_NewObj\fR. +.PP +\fBTcl_FSFileSystemInfo\fR always returns a zero-reference object (or +NULL), much like \fBTcl_NewObj\fR. +.PP +The \fIobjPtr\fR and \fIobjPtrRef\fR arguments to \fBTcl_FSFileAttrsGet\fR, +\fBTcl_FSFileAttrsSet\fR and \fBTcl_FSFileAttrStrings\fR are conventional Tcl +values; the \fIobjPtr\fR argument will be read but not retained, and the +\fIobjPtrRef\fR argument will have (on success) a zero-reference value written +into it (as with \fBTcl_NewObj\fR). \fBTcl_FSFileAttrsGet\fR and +\fBTcl_FSFileAttrsSet\fR may also manipulate the interpreter result. +.PP +The \fIresultPtr\fR argument to \fBTcl_FSMatchInDirectory\fR will not have its +reference count manipulated, but it should have a reference count of no more +than 1, and should not be the current interpreter result (as the function may +overwrite that on error). +.SS "VIRTUAL FILESYSTEM INTERFACE" +.PP +For all virtual filesystem implementation functions, any \fIpathPtr\fR +arguments should not have their reference counts manipulated. If they take an +\fIinterp\fR argument, they may set an error message in that, but must not +manipulate the \fIpathPtr\fR afterwards. Aside from that: +.TP +\fIinternalToNormalizedProc\fR +. +This should return a zero-reference count value, as if allocated with +\fBTcl_NewObj\fR. +.TP +\fInormalizePathProc\fR +. +Unlike with other API implementation functions, the \fIpathPtr\fR argument +here is guaranteed to be an unshared object that should be updated. Its +reference count should not be modified. +.TP +\fIfilesystemPathTypeProc\fR +. +The return value (if non-NULL) either has a reference count of zero or needs +to be maintained (on a per-thread basis) by the filesystem. Tcl will increment +the reference count of the value if it wishes to retain it. +.TP +\fIfilesystemSeparatorProc\fR +. +The return value should be a value with reference count of zero. +.TP +\fImatchInDirectoryProc\fR +. +The \fIresultPtr\fR argument should be assumed to hold a list that can be +appended to (i.e., that has a reference count no greater than 1). No reference +to it should be retained. +.TP +\fIlinkProc\fR +. +If \fItoPtr\fR is NULL, this should return a value with reference count 1 that +has just been allocated and passed to \fBTcl_IncrRefCount\fR. If \fItoPtr\fR +is not NULL, it should be returned on success. +.TP +\fIlistVolumesProc\fR +. +The result value should be a list (if non-NULL); it will have its reference +count decremented once (with \fBTcl_DecrRefCount\fR) by Tcl once done. +.TP +\fIfileAttrStringsProc\fR +. +If the result is NULL, the \fIobjPtrRef\fR should have a list value written to +it; that list will have its reference count both incremented (with +\fBTcl_IncrRefCount\fR) and decremented (with \fBTcl_DecrRefCount\fR). +.TP +\fIfileAttrsGetProc\fR +. +The \fIobjPtrRef\fR argument should have (on non-error return) a zero +reference count value written to it (allocated as if with \fBTcl_NewObj\fR). +.TP +\fIfileAttrsSetProc\fR +. +The \fIobjPtr\fR argument should either just be read or its reference count +incremented to retain it. +.TP +\fIremoveDirectoryProc\fR +. +If an error is being reported, the problem filename reported via +\fIerrorPtr\fR should be newly allocated (as if with \fBTcl_NewObj\fR) and +have a reference count of 1 (i.e., have been passed to +\fBTcl_IncrRefCount\fR). +.TP +\fIcopyDirectoryProc\fR +. +If an error is being reported, the problem filename reported via +\fIerrorPtr\fR should be newly allocated (as if with \fBTcl_NewObj\fR) and +have a reference count of 1 (i.e., have been passed to +\fBTcl_IncrRefCount\fR). +.TP +\fIgetCwdProc\fR +. +The result will be passed to \fBTcl_DecrRefCount\fR by the implementation of +\fBTcl_FSGetCwd\fR after it has been normalized. .SH "SEE ALSO" cd(n), file(n), filename(n), load(n), open(n), pwd(n), source(n), unload(n) .SH KEYWORDS diff --git a/doc/FindExec.3 b/doc/FindExec.3 index 1fd57db..6156382 100644 --- a/doc/FindExec.3 +++ b/doc/FindExec.3 @@ -13,7 +13,7 @@ Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of th .nf \fB#include <tcl.h>\fR .sp -void +const char * \fBTcl_FindExecutable\fR(\fIargv0\fR) .sp const char * @@ -35,6 +35,9 @@ Tcl. For example, it is needed on some platforms in the implementation of the \fBload\fR command. It is also returned by the \fBinfo nameofexecutable\fR command. .PP +The result of \fBTcl_FindExecutable\fR is the full Tcl version with build +information (e.g., \fB8.7.0+abcdef...abcdef.gcc-1002\fR). +.PP On UNIX platforms this procedure is typically invoked as the very first thing in the application's main program; it must be passed \fIargv[0]\fR as its argument. It is important not to change the @@ -58,6 +61,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/GetIndex.3 b/doc/GetIndex.3 index 17a31d4..176b0b2 100644 --- a/doc/GetIndex.3 +++ b/doc/GetIndex.3 @@ -27,19 +27,22 @@ Interpreter to use for error reporting; if NULL, then no message is provided on errors. .AP Tcl_Obj *objPtr in/out The string value of this value is used to search through \fItablePtr\fR. -The internal representation is modified to hold the index of the matching +If the \fBTCL_INDEX_TEMP_TABLE\fR flag is not specified, +the internal representation is modified to hold the index of the matching table entry. .AP "const char *const" *tablePtr in An array of null-terminated strings. The end of the array is marked by a NULL string pointer. -Note that references to the \fItablePtr\fR may be retained in the +Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified, +references to the \fItablePtr\fR may be retained in the internal representation of \fIobjPtr\fR, so this should represent the address of a statically-allocated array. .AP "const void" *structTablePtr in An array of arbitrary type, typically some \fBstruct\fR type. The first member of the structure must be a null-terminated string. The size of the structure is given by \fIoffset\fR. -Note that references to the \fIstructTablePtr\fR may be retained in the +Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified, +references to the \fIstructTablePtr\fR may be retained in the internal representation of \fIobjPtr\fR, so this should represent the address of a statically-allocated array of structures. .AP int offset in @@ -50,10 +53,13 @@ Null-terminated string describing what is being looked up, such as \fBoption\fR. This string is included in error messages. .AP int flags in OR-ed combination of bits providing additional information for -operation. The only bit that is currently defined is \fBTCL_EXACT\fR. -.AP int *indexPtr out -The index of the string in \fItablePtr\fR that matches the value of -\fIobjPtr\fR is returned here. +operation. The only bits that are currently defined are \fBTCL_EXACT\fR +, \fBTCL_INDEX_TEMP_TABLE\fR, and \fBTCL_NULL_OK\fR. +.AP enum|char|short|int|long *indexPtr out +If not (int *)NULL, the index of the string in \fItablePtr\fR that +matches the value of \fIobjPtr\fR is returned here. The variable can +be any integer type, signed or unsigned, char, short, long or +long long. It can also be an enum. .BE .SH DESCRIPTION .PP @@ -66,8 +72,8 @@ the strings in \fItablePtr\fR to find a match. A match occurs if \fItablePtr\fR, or if it is a non-empty unique abbreviation for exactly one of the strings in \fItablePtr\fR and the \fBTCL_EXACT\fR flag was not specified; in either case -the index of the matching entry is stored at \fI*indexPtr\fR -and \fBTCL_OK\fR is returned. +\fBTCL_OK\fR is returned. If \fIindexPtr\fR is not NULL the index +of the matching entry is stored at \fI*indexPtr\fR. .PP If there is no matching entry, \fBTCL_ERROR\fR is returned and an error message is left in \fIinterp\fR's @@ -76,7 +82,8 @@ error message to indicate what was being looked up. For example, if \fImsg\fR is \fBoption\fR the error message will have a form like .QW "\fBbad option \N'34'firt\N'34': must be first, second, or third\fR" . .PP -If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the +If the \fBTCL_INDEX_TEMP_TABLE\fR was not specified, when +\fBTcl_GetIndexFromObj\fR completes successfully it modifies the internal representation of \fIobjPtr\fR to hold the address of the table and the index of the matching entry. If \fBTcl_GetIndexFromObj\fR is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR @@ -84,7 +91,11 @@ arguments (e.g. during a reinvocation of a Tcl command), it returns the matching index immediately without having to redo the lookup operation. Note: \fBTcl_GetIndexFromObj\fR assumes that the entries in \fItablePtr\fR are static: they must not change between -invocations. If the value of \fIobjPtr\fR is the empty string, +invocations. This caching mechanism can be disallowed by specifying +the \fBTCL_INDEX_TEMP_TABLE\fR flag. +If the \fBTCL_NULL_OK\fR flag was specified, objPtr is allowed +to be NULL or the empty string. The resulting index is -1. +Otherwise, if the value of \fIobjPtr\fR is the empty string, \fBTcl_GetIndexFromObj\fR will treat it as a non-matching value and return \fBTCL_ERROR\fR. .PP @@ -98,6 +109,12 @@ array of characters at \fItablePtr\fR+\fIoffset\fR bytes, etc.) This is particularly useful when processing things like \fBTk_ConfigurationSpec\fR, whose string keys are in the same place in each of several array elements. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_GetIndexFromObj\fR and \fBTcl_GetIndexFromObjStruct\fR do not modify +the reference count of their \fIobjPtr\fR arguments; they only read. Note +however that these functions may set the interpreter result; if that is the +only place that is holding a reference to the object, it will be deleted. .SH "SEE ALSO" prefix(n), Tcl_WrongNumArgs(3) .SH KEYWORDS diff --git a/doc/GetInt.3 b/doc/GetInt.3 index 1e49528..f15c12d 100644 --- a/doc/GetInt.3 +++ b/doc/GetInt.3 @@ -22,6 +22,9 @@ int .sp int \fBTcl_GetBoolean\fR(\fIinterp, src, intPtr\fR) +.sp +int +\fBTcl_GetBool\fR(\fIinterp, src, flags, charPtr\fR) .SH ARGUMENTS .AS Tcl_Interp *doublePtr out .AP Tcl_Interp *interp in @@ -33,6 +36,12 @@ Points to place to store integer value converted from \fIsrc\fR. .AP double *doublePtr out Points to place to store double-precision floating-point value converted from \fIsrc\fR. +.AP char *charPtr out +Points to place to store boolean value (0 or 1) value converted from \fIsrc\fR. +.AP int flags in +0 or TCL_NULL_OK. If TCL_NULL_OK +is used, then the empty string or NULL will result in \fBTcl_GetBool\fR +return TCL_OK, the *charPtr filled with the value \fB'\exFF'\fR; .BE .SH DESCRIPTION @@ -55,6 +64,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 @@ -63,8 +75,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 @@ -94,6 +106,10 @@ If \fIsrc\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR, then 1 is stored at \fI*intPtr\fR. Any of these values may be abbreviated, and upper-case spellings are also acceptable. +.PP +\fBTcl_GetBool\fR functions almost the same as \fBTcl_GetBoolean\fR, +but it has an additional parameter \fBflags\fR, which can be used +to specify whether the empty string or NULL is accepted as valid. .SH KEYWORDS boolean, conversion, double, floating-point, integer @@ -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 @@ -330,5 +330,19 @@ typedef void \fBTcl_FreeHashEntryProc\fR( If this is NULL then \fBTcl_Free\fR is used to free the space for the entry. Tcl_Obj* keys use this function to decrement the reference count on the value. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +When a hash table is created with \fBTcl_InitCustomHashTable\fR, the +\fBTcl_CreateHashEntry\fR function will increment the reference count of its +\fIkey\fR argument when it creates a key (but not if there is an existing +matching key). The reference count of the key will be decremented when the +corresponding hash entry is deleted, whether with \fBTcl_DeleteHashEntry\fR or +with \fBTcl_DeleteHashTable\fR. The \fBTcl_GetHashKey\fR function will return +the key without further modifying its reference count. +.PP +Custom hash tables that use a Tcl_Obj* as key will generally need to do +something similar in their \fIallocEntryProc\fR. +.SH "SEE ALSO" +Dict(3) .SH KEYWORDS hash table, key, lookup, search, value @@ -2,7 +2,7 @@ '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" -.TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures" +.TH Tcl_Init 3 8.7 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -13,10 +13,15 @@ Tcl_Init \- find and source initialization script .sp int \fBTcl_Init\fR(\fIinterp\fR) +.sp +const char * +\fBTcl_SetPreInitScript\fR(\fIscriptPtr\fR) .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in Interpreter to initialize. +.AP "const char" *scriptPtr in +Address of the initialization script. .BE .SH DESCRIPTION @@ -26,6 +31,13 @@ Interpreter to initialize. path. .PP \fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures. +.PP +\fBTcl_SetPreInitScript\fR registers the pre-initialization script and +returns the former (now replaced) script pointer. +A value of \fINULL\fR may be passed to not register any script. +The pre-initialization script is executed by \fBTcl_Init\fR before accessing +the file system. The purpose is to typically prepare a custom file system +(like an embedded zip-file) to be activated before the search. .SH "SEE ALSO" Tcl_AppInit, Tcl_Main 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..0d09a41 --- /dev/null +++ b/doc/InitSubSyst.3 @@ -0,0 +1,34 @@ +'\" +'\" 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 +const char * +\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 +The result of \fBTcl_InitSubsystems\fR is the full Tcl version with build +information (e.g., \fB8.7.0+abcdef...abcdef.gcc-1002\fR). +.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 utf-16 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..18d867e 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_GetWideUIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -32,11 +32,17 @@ 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 \fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR) .sp +int +\fBTcl_GetWideUIntFromObj\fR(\fIinterp, objPtr, uwidePtr\fR) +.sp .sp \fB#include <tclTomMath.h>\fR .sp @@ -55,6 +61,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 @@ -77,6 +85,8 @@ Points to place to store the integer value retrieved from \fIobjPtr\fR. Points to place to store the long integer value retrieved from \fIobjPtr\fR. .AP Tcl_WideInt *widePtr out Points to place to store the wide integer value retrieved from \fIobjPtr\fR. +.AP Tcl_WideUInt *uwidePtr out +Points to place to store the unsigned wide integer value retrieved from \fIobjPtr\fR. .AP mp_int *bigValue in/out Points to a multi-precision integer structure declared by the LibTomMath library. @@ -97,7 +107,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, 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 +125,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 @@ -145,6 +165,27 @@ If anything later in the caller requires The \fBTcl_InitBignumFromDouble\fR routine is a utility procedure that extracts the integer part of \fIdoubleValue\fR and stores that integer value in the \fBmp_int\fR value \fIbigValue\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR, and +\fBTcl_NewBignumObj\fR always return a zero-reference object, much like +\fBTcl_NewObj\fR. +.PP +\fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR, and +\fBTcl_SetBignumObj\fR do not modify the reference count of their \fIobjPtr\fR +arguments, but do require that the object be unshared. +.PP +\fBTcl_GetIntFromObj\fR, \fBTcl_GetIntForIndex\fR, \fBTcl_GetLongFromObj\fR, +\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and +\fBTcl_TakeBignumFromObj\fR do not modify the reference count of their +\fIobjPtr\fR arguments; they only read. Note however that this function may +set the interpreter result; if that is the only place that is holding a +reference to the object, it will be deleted. Also note that if +\fBTcl_TakeBignumFromObj\fR is given an unshared value, the value of that +object may be modified; it is intended to be used when the value is +.QW consumed +by the operation at this point. + .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult .SH KEYWORDS 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..f5e97b4 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_BINARY\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,177 @@ 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_BINARY\fR instead. +.VE "TIP 312" +.RE +.TP +\fBTCL_LINK_BINARY\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. +wideinteger form acceptable to \fBTcl_GetWideUIntFromObj\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 +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 +260,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 +270,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/ListObj.3 b/doc/ListObj.3 index f282039..c5c1dc7 100644 --- a/doc/ListObj.3 +++ b/doc/ListObj.3 @@ -246,6 +246,31 @@ with a NULL \fIobjvPtr\fR: result = \fBTcl_ListObjReplace\fR(interp, listPtr, first, count, 0, NULL); .CE +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewListObj\fR always returns a zero-reference object, much like +\fBTcl_NewObj\fR. If a non-NULL \fIobjv\fR argument is given, the reference +counts of the first \fIobjc\fR values in that array are incremented. +.PP +\fBTcl_SetListObj\fR does not modify the reference count of its \fIobjPtr\fR +argument, but does require that the object be unshared. The reference counts +of the first \fIobjc\fR values in the \fIobjv\fR array are incremented. +.PP +\fBTcl_ListObjGetElements\fR, \fBTcl_ListObjIndex\fR, and +\fBTcl_ListObjLength\fR do not modify the reference count of their +\fIlistPtr\fR arguments; they only read. Note however that these three +functions may set the interpreter result; if that is the only place that is +holding a reference to the object, it will be deleted. +.PP +\fBTcl_ListObjAppendList\fR, \fBTcl_ListObjAppendElement\fR, and +\fBTcl_ListObjReplace\fR require an unshared \fIlistPtr\fR argument. +\fBTcl_ListObjAppendList\fR only reads its \fIelemListPtr\fR argument. +\fBTcl_ListObjAppendElement\fR increments the reference count of its +\fIobjPtr\fR on success. \fBTcl_ListObjReplace\fR increments the reference +count of the first \fIobjc\fR values in the \fIobjv\fR array on success. Note +however that all these three functions may set the interpreter result on +failure; if that is the only place that is holding a reference to the object, +it will be deleted. .SH "SEE ALSO" Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_GetObjResult(3) .SH KEYWORDS @@ -60,6 +60,10 @@ be unloaded with \fBTcl_FSUnloadFile\fR. the symbol cannot be found, it returns NULL and sets an error message in the given \fIinterp\fR (if that is non-NULL). Note that it is unsafe to use this operation on a handle that has been passed to \fBTcl_FSUnloadFile\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The reference count of the \fIpathPtr\fR argument to \fBTcl_LoadFile\fR may be +incremented. As such, it should not be given a zero reference count value. .SH "SEE ALSO" Tcl_FSLoadFile(3), Tcl_FSUnloadFile(3), load(n), unload(n) .SH KEYWORDS diff --git a/doc/Method.3 b/doc/Method.3 index 225da00..577cd54 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. @@ -240,8 +258,32 @@ also return TCL_ERROR; it should return TCL_OK otherwise. The \fIoldClientData\fR field to a Tcl_CloneProc gives the value from the method being copied from, and the \fInewClientDataPtr\fR field will point to a variable in which to write the value for the method being copied to. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fInameObj\fR argument to \fBTcl_NewMethod\fR and +\fBTcl_NewInstanceMethod\fR (when non-NULL) will have its reference count +incremented if there is no existing method with that name in that +class/object. +.PP +The result of \fBTcl_MethodName\fR is a value with a reference count of at +least one. It should not be modified without first duplicating it (with +\fBTcl_DuplicateObj\fR). +.PP +The values in the first \fIobjc\fR values of the \fIobjv\fR argument to +\fBTcl_ObjectContextInvokeNext\fR are assumed to have a reference count of at +least 1; the containing array is assumed to endure until the next method +implementation (see \fBnext\fR) returns. Be aware that methods may +\fByield\fR; if any post-call actions are desired (e.g., decrementing the +reference count of values passed in here), they must be scheduled with +\fBTcl_NRAddCallback\fR. +.PP +The \fIcallProc\fR of the \fBTcl_MethodType\fR structure takes values of at +least reference count 1 in its \fIobjv\fR argument. It may add its own +references, but must not decrement the reference count below that level; the +caller of the method will decrement the reference count once the method +returns properly (and the reference will be held if the method \fByield\fRs). .SH "SEE ALSO" -Class(3), oo::class(n), oo::define(n), oo::object(n) +Class(3), NRE(3), oo::class(n), oo::define(n), oo::object(n) .SH KEYWORDS constructor, method, object @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback \- Non-Recursive (stackless) evaluation of Tcl scripts. +Tcl_NRCreateCommand, Tcl_NRCreateCommand2, Tcl_NRCallObjProc, Tcl_NRCallObjProc2, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback \- Non-Recursive (stackless) evaluation of Tcl scripts. .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -18,10 +18,17 @@ Tcl_Command \fBTcl_NRCreateCommand\fR(\fIinterp, cmdName, proc, nreProc, clientData, deleteProc\fR) .sp +Tcl_Command +\fBTcl_NRCreateCommand2\fR(\fIinterp, cmdName, proc2, nreProc2, clientData, + deleteProc\fR) +.sp int \fBTcl_NRCallObjProc\fR(\fIinterp, nreProc, clientData, objc, objv\fR) .sp int +\fBTcl_NRCallObjProc2\fR(\fIinterp, nreProc2, clientData, objc, objv\fR) +.sp +int \fBTcl_NREvalObj\fR(\fIinterp, objPtr, flags\fR) .sp int @@ -47,8 +54,15 @@ Called in order to evaluate a command. Is often just a small wrapper that uses \fBTcl_NRCallObjProc\fR to call \fInreProc\fR using a new trampoline. Behaves in the same way as the \fIproc\fR argument to \fBTcl_CreateObjCommand\fR(3) (\fIq.v.\fR). +.AP Tcl_ObjCmdProc2 *proc2 in +Called in order to evaluate a command. Is often just a small wrapper that uses +\fBTcl_NRCallObjProc2\fR to call \fInreProc2\fR using a new trampoline. Behaves +in the same way as the \fIproc2\fR argument to \fBTcl_CreateObjCommand2\fR(3) +(\fIq.v.\fR). .AP Tcl_ObjCmdProc *nreProc in Called instead of \fIproc\fR when a trampoline is already in use. +.AP Tcl_ObjCmdProc2 *nreProc2 in +Called instead of \fIproc2\fR when a trampoline is already in use. .AP ClientData clientData in Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR and \fIobjProc\fR. @@ -104,6 +118,9 @@ first deleted. If \fIinterp\fR is in the process of being deleted \fBTcl_NRCreateCommand\fR does not create any command, does not delete any command, and returns NULL. .PP +\fBTcl_NRCreateCommand2\fR, is an alternative to \fBTcl_NRCreateCommand\fR +in the same way as \fBTcl_CreateObjCommand2\fR. +.PP \fBTcl_NREvalObj\fR pushes a function that is like \fBTcl_EvalObjEx\fR but consumes no space on the C stack. .PP @@ -227,6 +244,25 @@ int Any function comprising a routine can push other functions, making it possible implement looping and sequencing constructs using the function stack. .PP +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The first \fIobjc\fR values in the \fIobjv\fR array passed to the functions +\fBTcl_NRCallObjProc\fR, \fBTcl_NREvalObjv\fR, and \fBTcl_NRCmdSwap\fR should +have a reference count of at least 1; they may have additional references +taken during the execution. +.PP +The \fIobjPtr\fR argument to \fBTcl_NREvalObj\fR and \fBTcl_NRExprObj\fR +should have a reference count of at least 1, and may have additional +references taken to it during execution. +.PP +The \fIresultObj\fR argument to \fBTcl_NRExprObj\fR should be an unshared +object. +.PP +Use \fBTcl_NRAddCallback\fR to schedule any required final decrementing of the +reference counts of arguments to any of the other functions on this page, as +with any other post-processing step in the non-recursive execution engine. +.PP +The .SH "SEE ALSO" Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3) .SH KEYWORDS diff --git a/doc/Namespace.3 b/doc/Namespace.3 index a971ddb..a7e8502 100644 --- a/doc/Namespace.3 +++ b/doc/Namespace.3 @@ -159,6 +159,18 @@ for the namespace, or NULL if none is set. \fBTcl_SetNamespaceUnknownHandler\fR sets the unknown command handler for the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to its default. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIobjPtr\fR argument to \fBTcl_AppendExportList\fR should be an +unshared object, as it will be modified by this function. The +reference count of \fIobjPtr\fR will not be altered. +.PP +\fBTcl_GetNamespaceUnknownHandler\fR returns a possibly shared value. +Its reference count should be incremented if the value is to be +retained. +.PP +The \fIhandlerPtr\fR argument to \fBTcl_SetNamespaceUnknownHandler\fR +will have its reference count incremented if it is a non-empty list. .SH "SEE ALSO" Tcl_CreateCommand(3), Tcl_ListObjAppendList(3), Tcl_SetVar(3) .SH KEYWORDS diff --git a/doc/Notifier.3 b/doc/Notifier.3 index 16f9f8d..7cb02f6 100644 --- a/doc/Notifier.3 +++ b/doc/Notifier.3 @@ -90,9 +90,10 @@ necessary. .AP Tcl_Event *evPtr in An event to add to the event queue. The storage for the event must have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR. -.AP Tcl_QueuePosition position in +.AP int position in Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR, -\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR. +\fBTCL_QUEUE_HEAD\fR, \fBTCL_QUEUE_MARK\fR, and whether to do +an alert if the queue is empty: \fBTCL_QUEUE_ALERT_IF_EMPTY\fR. .AP Tcl_ThreadId threadId in A unique identifier for a thread. .AP Tcl_EventDeleteProc *deleteProc in @@ -103,7 +104,7 @@ passed to \fBTcl_DoOneEvent\fR. .AP int mode in Indicates whether events should be serviced by \fBTcl_ServiceAll\fR. Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR. -.AP Tcl_NotifierProcs* notifierProcPtr in +.AP const Tcl_NotifierProcs* notifierProcPtr in Structure of function pointers describing notifier procedures that are to replace the ones installed in the executable. See \fBREPLACING THE NOTIFIER\fR for details. @@ -132,22 +133,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 @@ -345,14 +341,14 @@ and should not be modified by the event source. .PP An event may be added to the queue at any of three positions, depending on the \fIposition\fR argument to \fBTcl_QueueEvent\fR: -.IP \fBTCL_QUEUE_TAIL\fR 24 +.IP \fBTCL_QUEUE_TAIL\fR 32 Add the event at the back of the queue, so that all other pending events will be serviced first. This is almost always the right place for new events. -.IP \fBTCL_QUEUE_HEAD\fR 24 +.IP \fBTCL_QUEUE_HEAD\fR 32 Add the event at the front of the queue, so that it will be serviced before all other queued events. -.IP \fBTCL_QUEUE_MARK\fR 24 +.IP \fBTCL_QUEUE_MARK\fR 32 Add the event at the front of the queue, unless there are other events at the front whose position is \fBTCL_QUEUE_MARK\fR; if so, add the new event just after all other \fBTCL_QUEUE_MARK\fR events. @@ -360,6 +356,10 @@ This value of \fIposition\fR is used to insert an ordered sequence of events at the front of the queue, such as a series of Enter and Leave events synthesized during a grab or ungrab operation in Tk. +.IP \fBTCL_QUEUE_ALERT_IF_EMPTY\fR 32 +When used in \fBTcl_ThreadQueueEvent\fR +arranges for an automatic call of \fBTcl_ThreadAlert\fR when the queue was +empty. .PP When it is time to handle an event from the queue (steps 1 and 4 above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified @@ -403,11 +403,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 +494,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/Number.3 b/doc/Number.3 new file mode 100644 index 0000000..4642c10 --- /dev/null +++ b/doc/Number.3 @@ -0,0 +1,123 @@ +'\" +'\" Contribution from Don Porter, NIST, 2022. (not subject to US copyright) +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tcl_GetNumber 3 8.7 Tcl "Tcl Library Procedures" +.so man.macros +.BS +.SH NAME +Tcl_GetNumber, Tcl_GetNumberFromObj \- get numeric value from Tcl value +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +\fB#include <tclTomMath.h>\fR +.sp +int +\fBTcl_GetNumber\fR(\fIinterp, bytes, numBytes, clientDataPtr, typePtr\fR) +.sp +int +\fBTcl_GetNumberFromObj\fR(\fIinterp, objPtr, clientDataPtr, typePtr\fR) +.SH ARGUMENTS +.AS Tcl_Interp clientDataPtr out +.AP Tcl_Interp *interp out +When non-NULL, error information is recorded here when the value is not +in any of the numeric formats recognized by Tcl. +.AP "const char" *bytes in +Points to first byte of the string value to be examined. +.AP int numBytes in +The number of bytes, starting at \fIbytes\fR, that should be examined. +If the value \fBTCL_INDEX_NONE\fR is provided, then all bytes should +be examined until the first \fBNUL\fR byte terminates examination. +.AP "void *" *clientDataPtr out +Points to space where a pointer value may be written through which a numeric +value is available to read. +.AP int *typePtr out +Points to space where a value may be written reporting what type of +numeric storage is available to read. +.AP Tcl_Obj *objPtr in +A Tcl value to be examined. +.BE +.SH DESCRIPTION +.PP +These procedures enable callers to retrieve a numeric value from a +Tcl value in a numeric format recognized by Tcl. +.PP +Tcl recognizes many values as numbers. Several examples include: +\fB"0"\fR, \fB" +1"\fR, \fB"-2 "\fR, \fB" 3 "\fR, \fB"0xdad1"\fR, \fB"0d09"\fR, +\fB"1_000_000"\fR, \fB"4.0"\fR, \fB"1e-7"\fR, \fB"NaN"\fR, or \fB"Inf"\fR. +When built-in Tcl commands act on these values as numbers, they are converted +to a numeric representation for efficient handling in C code. Tcl makes +use of three C types to store these representations: \fBdouble\fR, +\fBTcl_WideInt\fR, and \fBmp_int\fR. The \fBdouble\fR type is provided by the +C language standard. The \fBTcl_WideInt\fR type is declared in the Tcl +header file, \fBtcl.h\fR, and is equivalent to the C standard type +\fBlong long\fR on most platforms. The \fBmp_int\fR type is declared in the +header file \fBtclTomMath.h\fR, and implemented by the LibTomMath +multiple-precision integer library, included with Tcl. +.PP +The routines \fBTcl_GetNumber\fR and \fBTcl_GetNumberFromObj\fR perform +the same function. They differ only in how the arguments present the Tcl +value to be examined. \fBTcl_GetNumber\fR accepts a counted string +value in the arguments \fIbytes\fR and \fInumBytes\fR (or a +\fBNUL\fR-terminated string value when \fInumBytes\fR is +\fBTCL_INDEX_NONE\fR). \fBTcl_GetNumberFromObj\fR accepts the Tcl value +in \fIobjPtr\fR. +.PP +Both routines examine the Tcl value and determine whether Tcl recognizes +it as a number. If not, both routines return \fBTCL_ERROR\fR and (when +\fIinterp\fR is not NULL) record an error message and error code +in \fIinterp\fR. +.PP +If Tcl does recognize the examined value as a number, both routines return +\fBTCL_OK\fR, and use the pointer arguments \fIclientDataPtr\fR +and \fItypePtr\fR (which may not be NULL) to report information the +caller can use to retrieve the numeric representation. Both routines +write to *\fIclientDataPtr\fR a pointer to the internal storage location +where Tcl holds the converted numeric value. +.PP +When the converted numeric value is stored as a \fBdouble\fR, +a call to math library routine \fBisnan\fR determines whether that +value is not a number (NaN). If so, both \fBTcl_GetNumber\fR and +\fBTcl_GetNumberFromObj\fR write the value \fBTCL_NUMBER_NAN\fR +to *\fItypePtr\fR. If not, both routines write the value +\fBTCL_NUMBER_DOUBLE\fR to *\fItypePtr\fR. These routines report +different type values in these cases because \fBTcl_GetDoubleFromObj\fR +raises an error on NaN values. For both reported type values, +the storage pointer may be cast to type \fBconst double *\fR and +the \fBdouble\fR numeric value may be read through it. +.PP +When the converted numeric value is stored as a \fBTcl_WideInt\fR, +both \fBTcl_GetNumber\fR and \fBTcl_GetNumberFromObj\fR write the +value \fBTCL_NUMBER_INT\fR to *\fItypePtr\fR. +The storage pointer may be cast to type \fBconst Tcl_WideInt *\fR and +the \fBTcl_WideInt\fR numeric value may be read through it. +.PP +When the converted numeric value is stored as an \fBmp_int\fR, +both \fBTcl_GetNumber\fR and \fBTcl_GetNumberFromObj\fR write the +value \fBTCL_NUMBER_BIG\fR to *\fItypePtr\fR. +The storage pointer may be cast to type \fBconst mp_int *\fR and +the \fBmp_int\fR numeric value may be read through it. +.PP +Future releases of Tcl might expand or revise the recognition of +values as numbers. If additional storage representations are +adopted, these routines will add new values to be written to +*\fItypePtr\fR to identify them. Callers should consider how +they should react to unknown values written to *\fItypePtr\fR. +.PP +When callers of these routines read numeric values through the +reported storage pointer, they are accessing memory that belongs +to the Tcl library. The Tcl library has the power to overwrite +or free this memory. The storage pointer reported by a call to +\fBTcl_GetNumber\fR or \fBTcl_GetNumberFromObj\fR should not be +used after the same thread has possibly returned control to the +Tcl library. If longer term access to the numeric value is needed, +it should be copied into memory controlled by the caller. Callers +must not attempt to write through or free the storage pointer. +.SH "SEE ALSO" +Tcl_GetDouble, Tcl_GetDoubleFromObj, Tcl_GetWideIntFromObj +.SH KEYWORDS +double, double value, double type, integer, integer value, integer type, +internal representation, value, value type, string representation diff --git a/doc/Object.3 b/doc/Object.3 index eadd041..2099552 100644 --- a/doc/Object.3 +++ b/doc/Object.3 @@ -283,7 +283,12 @@ to reduce storage requirements. Reference counting is used to determine when a value is no longer needed and can safely be freed. A value just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR -has \fIrefCount\fR 0. +has \fIrefCount\fR 0, meaning that the object can often be given to a function +like \fBTcl_SetObjResult\fR, \fBTcl_ListObjAppendElement\fR, or +\fBTcl_DictObjPut\fR (as a value) without explicit reference management, all +of which are common use cases. (The latter two require that the the target +list or dictionary be well-formed, but that is often easy to arrange when the +value is being initially constructed.) The macro \fBTcl_IncrRefCount\fR increments the reference count when a new reference to the value is created. The macro \fBTcl_DecrRefCount\fR decrements the count diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 index 67f5174..4a4ca13 100644 --- a/doc/ObjectType.3 +++ b/doc/ObjectType.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType \- manipulate Tcl value types +Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType, Tcl_FreeInternalRep, Tcl_InitStringRep, Tcl_HasStringRep, Tcl_StoreInternalRep, Tcl_FetchInternalRep \- manipulate Tcl value types .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -23,6 +23,22 @@ int .sp int \fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR) +.sp +void +\fBTcl_FreeInternalRep\fR(\fIobjPtr\fR) +.sp +char * +\fBTcl_InitStringRep\fR(\fIobjPtr, bytes, numBytes\fR) +.sp +int +\fBTcl_HasStringRep\fR(\fIobjPtr\fR) +.sp +void +\fBTcl_StoreInternalRep\fR(\fIobjPtr, typePtr, irPtr\fR) +.sp +Tcl_ObjInternalRep * +\fBTcl_FetchInternalRep\fR(\fIobjPtr, typePtr\fR) +.fi .SH ARGUMENTS .AS "const char" *typeName .AP "const Tcl_ObjType" *typePtr in @@ -38,6 +54,14 @@ For \fBTcl_AppendAllObjTypes\fR, this points to the value onto which it appends the name of each value type as a list element. For \fBTcl_ConvertToType\fR, this points to a value that must have been the result of a previous call to \fBTcl_NewObj\fR. +.AP "const char*" bytes in +String representation. +.AP "unsigned int" numBytes in +Length of the string representation in bytes. +.AP "const Tcl_ObjInternalRep*" irPtr in +Internal object representation. +.AP "const Tcl_ObjType*" typePtr in +Requested internal representation type. .BE .SH DESCRIPTION @@ -91,6 +115,43 @@ set \fIobjPtr->typePtr\fR to the argument value \fItypePtr\fR, but that is no longer guaranteed. The \fIsetFromAnyProc\fR is free to set the internal representation for \fIobjPtr\fR to make use of another related Tcl_ObjType, if it sees fit. +.PP +\fBTcl_FreeInternalRep\fR performs the function of the existing internal +macro \fBTclInitStringRep\fR, but is extended to return a pointer to the +string rep, and to accept \fINULL\fR as a value for bytes. +When bytes is \fINULL\fR and \fIobjPtr\fR has no string rep, an uninitialzed +buffer of \fInumBytes\fR bytes is created for filling by the caller. +When \fIbytes\fR is \fINULL\fR and \fIobjPtr\fR has a string rep, +the string rep will be truncated to a length of \fInumBytes\fR bytes. +When \fInumBytes\fR is greater than zero, and the returned pointer is +\fINULL\fR, that indicates a failure to allocate memory for the string +representation. +The caller may then choose whether to raise an error or panic. +.PP +\fBTcl_HasStringRep\fR returns a boolean indicating whether or not a string +rep is currently stored in \fIobjPtr\fR. +This is used when the caller wants to act on \fIobjPtr\fR differently +depending on whether or not it is a pure value. +Typically this only makes sense in an extension if it is already known that +\fIobjPtr\fR possesses an internal type that is managed by the extension. +.PP +\fBTcl_StoreInternalRep\fR stores in \fIobjPtr\fR a copy of the internal +representation pointed to by \fIirPtr\fR and sets its type to \fItypePtr\fR. +When \fIirPtr\fR is \fINULL\fR, this leaves \fIobjPtr\fR without a +representation for type \fItypePtr\fR. +.PP +\fBTcl_FetchInternalRep\fR returns a pointer to the internal representation +stored in \fIobjPtr\fR that matches the requested type \fItypePtr\fR. +If no such internal representation is in \fIobjPtr\fR, return \fINULL\fR. +.PP +This returns a public type +.CS +typedef union Tcl_ObjInternalRep {...} Tcl_ObjInternalRep +.CE +where the contents are exactly the existing contents of the union in the +\fIinternalRep\fR field of the \fITcl_Obj\fR struct. +This definition permits us to pass internal representations and pointers to +them as arguments and results in public routines. .SH "THE TCL_OBJTYPE STRUCTURE" .PP Extension writers can define new value types by defining four @@ -248,6 +309,28 @@ The \fIfreeIntRepProc\fR implementation must not access the uses of that field during value deletion. The defined tasks for the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR member. +.PP +Note that if a subsidiary value has its reference count reduced to zero +during the running of a \fIfreeIntRepProc\fR, that value may be not freed +immediately, in order to limit stack usage. However, the value will be freed +before the outermost current \fBTcl_DecrRefCount\fR returns. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIobjPtr\fR argument to \fBTcl_AppendAllObjTypes\fR should be an unshared +value; this function will not modify the reference count of that value, but +will modify its contents. If \fIobjPtr\fR is not (interpretable as) a list, +this function will set the interpreter result and produce an error; using an +unshared empty value is strongly recommended. +.PP +The \fIobjPtr\fR argument to \fBTcl_ConvertToType\fR can have any non-zero +reference count; this function will not modify the reference count, but may +write to the interpreter result on error so values that originate from there +should have an additional reference made before calling this. +.PP +None of the callback functions in the \fBTcl_ObjType\fR structure should +modify the reference count of their arguments, but if the values contain +subsidiary values (e.g., the elements of a list or the keys of a dictionary) +then those subsidiary values may have their reference counts modified. .SH "SEE ALSO" Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3) .SH KEYWORDS diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index cff2210..85100fc 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -92,10 +92,10 @@ int int \fBTcl_OutputBuffered\fR(\fIchannel\fR) .sp -Tcl_WideInt +long long \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR) .sp -Tcl_WideInt +long long \fBTcl_Tell\fR(\fIchannel\fR) .sp int @@ -190,7 +190,7 @@ A buffer containing the bytes to output to the channel. .AP int bytesToWrite in The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and output to the channel. -.AP Tcl_WideInt offset in +.AP "long long" offset in How far to move the access point in the channel at which the next input or output operation will be applied, measured in bytes from the position given by \fIseekMode\fR. May be either positive or negative. @@ -198,7 +198,7 @@ given by \fIseekMode\fR. May be either positive or negative. Relative to which point to seek; used with \fIoffset\fR to calculate the new access point for the channel. Legal values are \fBSEEK_SET\fR, \fBSEEK_CUR\fR, and \fBSEEK_END\fR. -.AP Tcl_WideInt length in +.AP "long long" length in The (non-negative) length to truncate the channel the channel to. .AP "const char" *optionName in The name of an option applicable to this channel, such as \fB\-blocking\fR. @@ -406,19 +406,21 @@ to UTF-8 based on the channel's encoding and storing the produced data in \fIreadObjPtr\fR's string representation. The return value of \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR, that were stored in \fIreadObjPtr\fR. If an error occurs while reading, the -return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that -can be retrieved with \fBTcl_GetErrno\fR. +return value is TCL_INDEX_NONE and \fBTcl_ReadChars\fR records a POSIX error +code that can be retrieved with \fBTcl_GetErrno\fR. If an encoding error happens +while the channel is in blocking mode with -profile strict, the characters +retrieved until the encoding error happened will be stored in \fIreadObjPtr\fR. .PP -Setting \fIcharsToRead\fR to \fB\-1\fR will cause the command to read +Setting \fIcharsToRead\fR to TCL_INDEX_NONE will cause the command to read all characters currently available (non-blocking) or everything until eof (blocking mode). .PP The return value may be smaller than the value to read, indicating that less data than requested was available. This is called a \fIshort read\fR. In blocking mode, this can only happen on an end-of-file. In nonblocking mode, -a short read can also occur if there is not enough input currently -available: \fBTcl_ReadChars\fR returns a short count rather than waiting -for more data. +a short read can also occur if an encoding error is encountered (with -profile +strict) or if there is not enough input currently available: +\fBTcl_ReadChars\fR returns a short count rather than waiting for more data. .PP If the channel is in blocking mode, a return value of zero indicates an end-of-file condition. If the channel is in nonblocking mode, a return @@ -471,14 +473,14 @@ character(s) are read and discarded. .PP If a line was successfully read, the return value is greater than or equal to zero and indicates the number of bytes stored in \fIlineObjPtr\fR. If an -error occurs, \fBTcl_GetsObj\fR returns \-1 and records a POSIX error code +error occurs, \fBTcl_GetsObj\fR returns TCL_INDEX_NONE and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. \fBTcl_GetsObj\fR also -returns \-1 if the end of the file is reached; the \fBTcl_Eof\fR procedure +returns TCL_INDEX_NONE if the end of the file is reached; the \fBTcl_Eof\fR procedure can be used to distinguish an error from an end-of-file condition. .PP -If the channel is in nonblocking mode, the return value can also be \-1 if -no data was available or the data that was available did not contain an -end-of-line character. When \-1 is returned, the \fBTcl_InputBlocked\fR +If the channel is in nonblocking mode, the return value can also be TCL_INDEX_NONE +if no data was available or the data that was available did not contain an +end-of-line character. When TCL_INDEX_NONE is returned, the \fBTcl_InputBlocked\fR procedure may be invoked to determine if the channel is blocked because of input unavailability. .PP @@ -496,7 +498,7 @@ head of the queue. If \fIchannel\fR has a .QW sticky EOF set, no data will be added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or -\-1 if an error occurs. +TCL_INDEX_NONE if an error occurs. .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE" .PP \fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at @@ -513,10 +515,10 @@ to appear as soon as a complete line is accepted for output, set the \fB\-buffering\fR option on the channel to \fBline\fR mode. .PP The return value of \fBTcl_WriteChars\fR is a count of how many bytes were -accepted for output to the channel. This is either greater than zero to -indicate success or \-1 to indicate that an error occurred. If an error -occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be -retrieved with \fBTcl_GetErrno\fR. +accepted for output to the channel. This is either TCL_INDEX_NONE to +indicate that an error occurred or another number greater than +zero to indicate success. If an error occurs, \fBTcl_WriteChars\fR records +a POSIX error code that may be retrieved with \fBTcl_GetErrno\fR. .PP Newline characters in the output data are translated to platform-specific end-of-line sequences according to the \fB\-translation\fR option for the @@ -641,6 +643,24 @@ the channel was created with \fBTcl_OpenFileChannel\fR, \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other channel types may return a different type of handle on Windows platforms. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIreadObjPtr\fR argument to \fBTcl_ReadChars\fR must be an unshared +value; it will be modified by this function. Using the interpreter result for +this purpose is \fIstrongly\fR not recommended; the preferred pattern is to +use a new value from \fBTcl_NewObj\fR to receive the data and only to pass it +to \fBTcl_SetObjResult\fR if this function succeeds. +.PP +The \fIlineObjPtr\fR argument to \fBTcl_GetsObj\fR must be an unshared value; +it will be modified by this function. Using the interpreter result for this +purpose is \fIstrongly\fR not recommended; the preferred pattern is to use a +new value from \fBTcl_NewObj\fR to receive the data and only to pass it to +\fBTcl_SetObjResult\fR if this function succeeds. +.PP +The \fIwriteObjPtr\fR argument to \fBTcl_WriteObj\fR should be a value with +any reference count. This function will not modify the reference count. Using +the interpreter result without adding an additional reference to it is not +recommended. .SH "SEE ALSO" DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3) .SH KEYWORDS diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3 index 4a7dc1e..e72556a 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, backlog, 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,11 @@ 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 int backlog in +Length of OS listen backlog queue. Use -1 for default value. +.AP "unsigned int" flags in +ORed combination of \fBTCL_TCPSERVER_*\fR flags that specify additional +informations about the socket being created. .AP ClientData sock in Platform-specific handle for client TCP socket. .AP Tcl_TcpAcceptProc *proc in @@ -158,6 +169,14 @@ 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. Available +flags (dependent on platform) are +\fITCL_TCPSERVER_REUSEADDR\fR +\fITCL_TCPSERVER_REUSEPORT\fR .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..5abe1dd 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 @@ -18,9 +18,12 @@ void void \fBTcl_PanicVA\fR(\fIformat\fR, \fIargList\fR) .sp -void +const char * \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: @@ -71,10 +82,16 @@ making calls into the Tcl library, or into other libraries that may call the Tcl library, since the original call to \fBTcl_Panic\fR indicates the Tcl library is not in a state of reliable operation. .PP +The result of \fBTcl_SetPanicProc\fR is the full Tcl version with build +information (e.g., \fB8.7.0+abcdef...abcdef.gcc-1002\fR). +.PP 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 +99,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/ParseArgs.3 b/doc/ParseArgs.3 index def55de..f29f161 100644 --- a/doc/ParseArgs.3 +++ b/doc/ParseArgs.3 @@ -189,6 +189,12 @@ will be stored at \fIdstPtr\fR; the string inside will have a lifetime linked to the lifetime of the string representation of the argument value that it came from, and so should be copied if it needs to be retained. The \fIsrcPtr\fR and \fIclientData\fR fields are ignored. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The values in the \fIobjv\fR argument to \fBTcl_ParseArgsObjv\fR will not have +their reference counts modified by this function. The interpreter result may +be modified on error; the values passed should not be the interpreter result +with no further reference added. .SH "SEE ALSO" Tcl_GetIndexFromObj(3), Tcl_Main(3), Tcl_CreateObjCommand(3) .SH KEYWORDS diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 index 3b80d2a..d413315 100644 --- a/doc/ParseCmd.3 +++ b/doc/ParseCmd.3 @@ -191,6 +191,7 @@ code with one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR, some other integer value originating in an extension. In addition, a result value or error message is left in \fIinterp\fR's result; it can be retrieved using \fBTcl_GetObjResult\fR. +.SS "DEPRECATED FUNCTIONS" .PP \fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in the return convention used: it returns the result in a new Tcl_Obj. @@ -463,5 +464,12 @@ There are additional fields in the Tcl_Parse structure after the \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be referenced by code outside of these procedures. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The result of \fBTcl_EvalTokens\fR is an unshared value with a reference count +of 1; the caller of that function should call \fBTcl_DecrRefCount\fR on the +result value to dispose of it. (The equivalent with +\fBTcl_EvalTokenStandard\fR is just the interpreter result, which can be +retrieved with \fBTcl_GetObjResult\fR.) .SH KEYWORDS backslash substitution, braces, command, expression, parse, token, variable substitution diff --git a/doc/PkgRequire.3 b/doc/PkgRequire.3 index a85d43f..bdf6103 100644 --- a/doc/PkgRequire.3 +++ b/doc/PkgRequire.3 @@ -90,7 +90,11 @@ functions. \fBTcl_PkgRequireProc\fR is the form of \fBpackage require\fR handling multiple requirements. The other forms are present for backward compatibility and translate their invocations to this form. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The requirements values given (in the \fIobjv\fR argument) to +\fBTcl_PkgRequireProc\fR must have non-zero reference counts. .SH KEYWORDS package, present, provide, require, version .SH "SEE ALSO" -package(n), Tcl_StaticPackage(3) +package(n), Tcl_StaticLibrary(3) diff --git a/doc/RecEvalObj.3 b/doc/RecEvalObj.3 index 1b0f292..e68f4b5 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) @@ -46,6 +44,12 @@ allow the user to re-issue recently invoked commands. If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then the command is recorded without being evaluated. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The reference count of the \fIcmdPtr\fR argument to \fBTcl_RecordAndEvalObj\fR +must be at least 1. This function will modify the interpreter result; do not +use an existing result as \fIcmdPtr\fR directly without incrementing its +reference count. .SH "SEE ALSO" Tcl_EvalObjEx, Tcl_GetObjResult diff --git a/doc/RegConfig.3 b/doc/RegConfig.3 index d73e3d7..ef46ba5 100644 --- a/doc/RegConfig.3 +++ b/doc/RegConfig.3 @@ -28,7 +28,7 @@ configuration as ASCII string. This means that this information is in UTF-8 too. Must not be NULL. .AP "const Tcl_Config" *configuration in Refers to an array of Tcl_Config entries containing the information -embedded in the binary library. Must not be NULL. The end of the array +embedded in the library. Must not be NULL. The end of the array is signaled by either a key identical to NULL, or a key referring to the empty string. .AP "const char" *valEncoding in @@ -40,10 +40,10 @@ too. Must not be NULL. .PP The function described here has its base in TIP 59 and provides extensions with support for the embedding of configuration -information into their binary library and the generation of a +information into their library and the generation of a Tcl-level interface for querying this information. .PP -To embed configuration information into their binary library an +To embed configuration information into their library an extension has to define a non-volatile array of Tcl_Config entries in one if its source files and then call \fBTcl_RegisterConfig\fR to register that information. @@ -108,4 +108,4 @@ typedef struct Tcl_Config { .\" No cross references yet. .\" .SH "SEE ALSO" .SH KEYWORDS -embedding, configuration, binary library +embedding, configuration, library diff --git a/doc/RegExp.3 b/doc/RegExp.3 index 1d578bb..40429c9 100644 --- a/doc/RegExp.3 +++ b/doc/RegExp.3 @@ -377,6 +377,22 @@ If no match was found, then it indicates the earliest point at which a match might occur if additional text is appended to the string. If it is no match is possible even with further text, this field will be set to \-1. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fItextObj\fR and \fIpatObj\fR arguments to \fBTcl_RegExpMatchObj\fR must +have reference counts of at least 1. Note however that this function may set +the interpreter result; neither argument should be the direct interpreter +result without an additional reference being taken. +.PP +The \fIpatObj\fR argument to \fBTcl_GetRegExpFromObj\fR must have a reference +count of at least 1. Note however that this function may set the interpreter +result; the argument should not be the direct interpreter result without an +additional reference being taken. +.PP +The \fItextObj\fR argument to \fBTcl_RegExpExecObj\fR must have a reference +count of at least 1. Note however that this function may set the interpreter +result; the argument should not be the direct interpreter result without an +additional reference being taken. .SH "SEE ALSO" re_syntax(n) .SH KEYWORDS diff --git a/doc/SaveInterpState.3 b/doc/SaveInterpState.3 new file mode 100644 index 0000000..804f9ec --- /dev/null +++ b/doc/SaveInterpState.3 @@ -0,0 +1,85 @@ +'\" +'\" Copyright (c) 1997 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. +'\" +.TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures" +.so man.macros +.BS +.SH NAME +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 +.sp +Tcl_InterpState +\fBTcl_SaveInterpState\fR(\fIinterp, status\fR) +.sp +int +\fBTcl_RestoreInterpState\fR(\fIinterp, state\fR) +.sp +\fBTcl_DiscardInterpState\fR(\fIstate\fR) +.sp +\fBTcl_SaveResult\fR(\fIinterp, savedPtr\fR) +.sp +\fBTcl_RestoreResult\fR(\fIinterp, savedPtr\fR) +.sp +\fBTcl_DiscardResult\fR(\fIsavedPtr\fR) +.SH ARGUMENTS +.AS Tcl_InterpState savedPtr +.AP Tcl_Interp *interp in +The interpreter for the operation. +.AP int status in +The return code for the state. +.AP Tcl_InterpState state in +A token for saved state. +.AP Tcl_SavedResult *savedPtr in +A pointer to storage for saved state. +.BE +.SH DESCRIPTION +.PP +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 +\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 +\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 +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_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_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_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 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 +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/SaveResult.3 b/doc/SaveResult.3 deleted file mode 100644 index 918941e..0000000 --- a/doc/SaveResult.3 +++ /dev/null @@ -1,120 +0,0 @@ -'\" -'\" Copyright (c) 1997 Sun Microsystems, Inc. -'\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright) -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures" -.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 -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_InterpState -\fBTcl_SaveInterpState\fR(\fIinterp, status\fR) -.sp -int -\fBTcl_RestoreInterpState\fR(\fIinterp, state\fR) -.sp -\fBTcl_DiscardInterpState\fR(\fIstate\fR) -.sp -\fBTcl_SaveResult\fR(\fIinterp, savedPtr\fR) -.sp -\fBTcl_RestoreResult\fR(\fIinterp, savedPtr\fR) -.sp -\fBTcl_DiscardResult\fR(\fIsavedPtr\fR) -.SH ARGUMENTS -.AS Tcl_InterpState savedPtr -.AP Tcl_Interp *interp in -Interpreter for which state should be saved. -.AP int status in -Return code value to save as part of interpreter state. -.AP Tcl_InterpState state in -Saved state token to be restored or discarded. -.AP Tcl_SavedResult *savedPtr in -Pointer to location where interpreter result should be saved or restored. -.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. -.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. -.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). -.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. -.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. -.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. -.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_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_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. -.SH KEYWORDS -result, state, interp diff --git a/doc/SetChanErr.3 b/doc/SetChanErr.3 index 5bb86be..473b61c 100644 --- a/doc/SetChanErr.3 +++ b/doc/SetChanErr.3 @@ -35,20 +35,20 @@ Refers to the Tcl interpreter whose bypass area is accessed. .AP Tcl_Obj* msg in Error message put into a bypass area. A list of return options and values, followed by a string message. Both message and the option/value information -are optional. +are optional. This \fImust\fR be a well-formed list. .AP Tcl_Obj** msgPtr out Reference to a place where the message stored in the accessed bypass area can be stored in. .BE .SH DESCRIPTION .PP -The current definition of a Tcl channel driver does not permit the direct +The standard definition of a Tcl channel driver does not permit the direct return of arbitrary error messages, except for the setting and retrieval of channel options. All other functions are restricted to POSIX error codes. .PP The functions described here overcome this limitation. Channel drivers are allowed to use \fBTcl_SetChannelError\fR and \fBTcl_SetChannelErrorInterp\fR -to place arbitrary error messages in \fBbypass areas\fR defined for channels +to place arbitrary error messages in \fIbypass areas\fR defined for channels and interpreters. And the generic I/O layer uses \fBTcl_GetChannelError\fR and \fBTcl_GetChannelErrorInterp\fR to look for messages in the bypass areas and arrange for their return as errors. The POSIX error codes set by a driver are @@ -134,6 +134,15 @@ leave all their error information in the interpreter result. .ta 1.9i 4i \fBTcl_Close\fR \fBTcl_UnstackChannel\fR \fBTcl_UnregisterChannel\fR .DE +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fImsg\fR argument to \fBTcl_SetChannelError\fR and +\fBTcl_SetChannelErrorInterp\fR, if not NULL, may have any reference count; +these functions will copy. +.PP +\fBTcl_GetChannelError\fR and \fBTcl_GetChannelErrorInterp\fR write a value +reference into their \fImsgPtr\fR, but do not manipulate its reference count. +The reference count will be at least 1 (unless the reference is NULL). .SH "SEE ALSO" Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3) .SH KEYWORDS diff --git a/doc/SetResult.3 b/doc/SetResult.3 index 0b0697a..c9ff84c 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 @@ -252,6 +239,33 @@ typedef void \fBTcl_FreeProc\fR( .PP When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to the value of \fIresult\fR passed to \fBTcl_SetResult\fR. + +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The interpreter result is one of the main places that owns references to +values, along with the bytecode execution stack, argument lists, variables, +and the list and dictionary collection values. +.PP +\fBTcl_SetObjResult\fR takes a value with an arbitrary reference count +\fI(specifically including zero)\fR and guarantees to increment the reference +count. If code wishes to continue using the value after setting it as the +result, it should add its own reference to it with \fBTcl_IncrRefCount\fR. +.PP +\fBTcl_GetObjResult\fR returns the current interpreter result value. This will +have a reference count of at least 1. If the caller wishes to keep the +interpreter result value, it should increment its reference count. +.PP +\fBTcl_GetStringResult\fR does not manipulate reference counts, but the string +it returns is owned by (and has a lifetime controlled by) the current +interpreter result value; it should be copied instead of being relied upon to +persist after the next Tcl API call, as most Tcl operations can modify the +interpreter result. +.PP +\fBTcl_SetResult\fR, \fBTcl_AppendResult\fR, \fBTcl_AppendResultVA\fR, +\fBTcl_AppendElement\fR, and \fBTcl_ResetResult\fR all modify the interpreter +result. They may cause the old interpreter result to have its reference count +decremented and a new interpreter result to be allocated. After they have been +called, the reference count of the interpreter result is guaranteed to be 1. .SH "SEE ALSO" Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp, Tcl_GetReturnOptions diff --git a/doc/SetVar.3 b/doc/SetVar.3 index 4aa671a..9d8e0b7 100644 --- a/doc/SetVar.3 +++ b/doc/SetVar.3 @@ -242,6 +242,27 @@ but the array remains. If an array name is specified without an index, then the entire array is removed. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The result of \fBTcl_SetVar2Ex\fR, \fBTcl_ObjSetVar2\fR, \fBTcl_GetVar2Ex\fR, +and \fBTcl_ObjGetVar2\fR is (if non-NULL) a value with a reference of at least +1, where that reference is held by the variable that the function has just +operated upon. +.PP +The \fInewValuePtr\fR argument to \fBTcl_SetVar2Ex\fR and \fBTcl_ObjSetVar2\fR +may be an arbitrary reference count value. Its reference count is +incremented on success. On failure, if its reference count is zero, it is +decremented and freed so the caller need do nothing with it. +.PP +The \fIpart1Ptr\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR can +have any reference count. These functions never modify it. +.PP +The \fIpart2Ptr\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR, if +non-NULL, should not have a zero reference count as these functions may +retain a reference to it, particularly when it is used to create an array +element that did not previously exist, and decrementing the reference count +later would leave them pointing to a freed Tcl_Obj. + .SH "SEE ALSO" Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar diff --git a/doc/StaticLibrary.3 b/doc/StaticLibrary.3 new file mode 100644 index 0000000..9a77ab7 --- /dev/null +++ b/doc/StaticLibrary.3 @@ -0,0 +1,78 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tcl_StaticLibrary 3 7.5 Tcl "Tcl Library Procedures" +.so man.macros +.BS +.SH NAME +Tcl_StaticLibrary, Tcl_StaticPackage \- make a statically linked library available via the 'load' command +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +\fBTcl_StaticLibrary\fR(\fIinterp, prefix, initProc, safeInitProc\fR) +.sp +\fBTcl_StaticPackage\fR(\fIinterp, prefix, initProc, safeInitProc\fR) +.SH ARGUMENTS +.AS Tcl_LibraryInitProc *safeInitProc +.AP Tcl_Interp *interp in +If not NULL, points to an interpreter into which the library has +already been incorporated (i.e., the caller has already invoked the +appropriate initialization procedure). NULL means the library +has not yet been incorporated into any interpreter. +.AP "const char" *prefix in +Prefix for library initialization function; should be properly +capitalized (first letter upper-case, all others lower-case). +.AP Tcl_LibraryInitProc *initProc in +Procedure to invoke to incorporate this library into a trusted +interpreter. +.AP Tcl_LibraryInitProc *safeInitProc in +Procedure to call to incorporate this library into a safe interpreter +(one that will execute untrusted scripts). NULL means the library +cannot be used in safe interpreters. +.BE +.SH DESCRIPTION +.PP +This procedure may be invoked to announce that a library has been +linked statically with a Tcl application and, optionally, that it +has already been incorporated into an interpreter. +Once \fBTcl_StaticLibrary\fR has been invoked for a library, it +may be incorporated into interpreters using the \fBload\fR command. +\fBTcl_StaticLibrary\fR is normally invoked only by the \fBTcl_AppInit\fR +procedure for the application, not by libraries for themselves +(\fBTcl_StaticLibrary\fR should only be invoked for statically +linked libraries, and code in the library itself should not need +to know whether the library is dynamically loaded or statically linked). +.PP +When the \fBload\fR command is used later to incorporate the library into +an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will +be invoked, depending on whether the target interpreter is safe +or not. +\fIinitProc\fR and \fIsafeInitProc\fR must both match the +following prototype: +.PP +.CS +typedef int \fBTcl_LibraryInitProc\fR( + Tcl_Interp *\fIinterp\fR); +.CE +.PP +The \fIinterp\fR argument identifies the interpreter in which the library +is to be incorporated. The initialization procedure must return \fBTCL_OK\fR or +\fBTCL_ERROR\fR to indicate whether or not it completed successfully; in +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_StaticLibrary\fR was named \fBTcl_StaticPackage\fR in Tcl 8.6 and +earlier, but the old name is deprecated now. +.PP +\fBTcl_StaticLibrary\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" +load(n), package(n), Tcl_PkgRequire(3) diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3 deleted file mode 100644 index bd00ab7..0000000 --- a/doc/StaticPkg.3 +++ /dev/null @@ -1,70 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures" -.so man.macros -.BS -.SH NAME -Tcl_StaticPackage \- make a statically linked package available via the 'load' command -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_StaticPackage\fR(\fIinterp, prefix, initProc, safeInitProc\fR) -.SH ARGUMENTS -.AS Tcl_PackageInitProc *safeInitProc -.AP Tcl_Interp *interp in -If not NULL, points to an interpreter into which the package has -already been loaded (i.e., the caller has already invoked the -appropriate initialization procedure). NULL means the package -has not yet been incorporated into any interpreter. -.AP "const char" *prefix in -Prefix for library initialization function; should be properly -capitalized (first letter upper-case, all others lower-case). -.AP Tcl_PackageInitProc *initProc in -Procedure to invoke to incorporate this package into a trusted -interpreter. -.AP Tcl_PackageInitProc *safeInitProc in -Procedure to call to incorporate this package into a safe interpreter -(one that will execute untrusted scripts). NULL means the package -cannot be used in safe interpreters. -.BE -.SH DESCRIPTION -.PP -This procedure may be invoked to announce that a package has been -linked statically with a Tcl application and, optionally, that it -has already been loaded into an interpreter. -Once \fBTcl_StaticPackage\fR has been invoked for a package, it -may be loaded into interpreters using the \fBload\fR command. -\fBTcl_StaticPackage\fR is normally invoked only by the \fBTcl_AppInit\fR -procedure for the application, not by packages for themselves -(\fBTcl_StaticPackage\fR should only be invoked for statically -loaded packages, and code in the package itself should not need -to know whether the package is dynamically or statically loaded). -.PP -When the \fBload\fR command is used later to load the package into -an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will -be invoked, depending on whether the target interpreter is safe -or not. -\fIinitProc\fR and \fIsafeInitProc\fR must both match the -following prototype: -.PP -.CS -typedef int \fBTcl_PackageInitProc\fR( - Tcl_Interp *\fIinterp\fR); -.CE -.PP -The \fIinterp\fR argument identifies the interpreter in which the package -is to be loaded. The initialization procedure must return \fBTCL_OK\fR or -\fBTCL_ERROR\fR to indicate whether or not it completed successfully; in -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. -.SH KEYWORDS -initialization procedure, package, static linking -.SH "SEE ALSO" -load(n), package(n), Tcl_PkgRequire(3) diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 9ce4d16..02fda8b 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 @@ -111,17 +111,19 @@ If negative, all characters up to the first null character are used. The index of the Unicode character to return. .AP int first in The index of the first Unicode character in the Unicode range to be -returned as a new value. +returned as a new value. If negative, behave the same as if the +value was 0. .AP int last in The index of the last Unicode character in the Unicode range to be -returned as a new value. +returned as a new value. If negative, take all characters up to +the last one available. .AP Tcl_Obj *objPtr in/out Points to a value to manipulate. .AP Tcl_Obj *appendObjPtr in The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. .AP int *lengthPtr out -If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store -the length of a value's string representation. +The location where \fBTcl_GetStringFromObj\fR will store the length +of a value's string representation. May be (int *)NULL when not used. .AP "const char" *string in Null-terminated string value to append to \fIobjPtr\fR. .AP va_list argList in @@ -204,8 +206,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 @@ -253,7 +255,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. @@ -317,9 +321,11 @@ but with greater convenience and no need to determine \fBSOME_SUITABLE_LENGTH\fR. The formatting is done with the same core formatting engine used by \fBTcl_Format\fR. This means the set of supported conversion specifiers is that of the \fBformat\fR command but -the behavior is as similar as possible to \fBsprintf\fR. Format specifiers -which were added by C99 (like "hh", "ll", "j", "z", "t", "L") are not supported. -When a conversion specifier passed to \fBTcl_ObjPrintf\fR includes a precision, +the behavior is as similar as possible to \fBsprintf\fR. The "hh" and +(Microsoft-specific) "w" format specifiers are not supported. The "L" +format specifier means that an "mp_int *" argument is expected (or a +"long double" in combination with \fB[aAeEgGaA]\fR). When a +conversion specifier passed to \fBTcl_ObjPrintf\fR includes a precision, the value is taken as a number of bytes, as \fBsprintf\fR does, and not as a number of characters, as \fBformat\fR does. This is done on the assumption that C code is more likely to know how many bytes it is @@ -386,6 +392,33 @@ white space, then that value is ignored entirely. This white-space removal was added to make the output of the \fBconcat\fR command cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a newly-created value whose ref count is zero. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewStringObj\fR, \fBTcl_NewUnicodeObj\fR, \fBTcl_Format\fR, +\fBTcl_ObjPrintf\fR, and \fBTcl_ConcatObj\fR always return a zero-reference +object, much like \fBTcl_NewObj\fR. +.PP +\fBTcl_GetStringFromObj\fR, \fBTcl_GetString\fR, \fBTcl_GetUnicodeFromObj\fR, +\fBTcl_GetUnicode\fR, \fBTcl_GetUniChar\fR, \fBTcl_GetCharLength\fR, and +\fBTcl_GetRange\fR all only work with an existing value; they do not +manipulate its reference count in any way. +.PP +\fBTcl_SetStringObj\fR, \fBTcl_SetUnicodeObj\fR, \fBTcl_AppendToObj\fR, +\fBTcl_AppendUnicodeToObj\fR, \fBTcl_AppendObjToObj\fR, +\fBTcl_AppendStringsToObj\fR, \fBTcl_AppendStringsToObjVA\fR, +\fBTcl_AppendLimitedToObj\fR, \fBTcl_AppendFormatToObj\fR, +\fBTcl_AppendPrintfToObj\fR, \fBTcl_SetObjLength\fR, and +\fBTcl_AttemptSetObjLength\fR and require their \fIobjPtr\fR to be an unshared +value (i.e, a reference count no more than 1) as they will modify it. +.PP +Additional arguments to the above functions (the \fIappendObjPtr\fR argument +to \fBTcl_AppendObjToObj\fR, values in the \fIobjv\fR argument to +\fBTcl_Format\fR, \fBTcl_AppendFormatToObj\fR, and \fBTcl_ConcatObj\fR) can +have any reference count, but reference counts of zero are not recommended. +.PP +\fBTcl_Format\fR and \fBTcl_AppendFormatToObj\fR may modify the interpreter +result, which involves changing the reference count of a value. + .SH "SEE ALSO" Tcl_NewObj(3), Tcl_IncrRefCount(3), Tcl_DecrRefCount(3), format(n), sprintf(3) .SH KEYWORDS diff --git a/doc/SubstObj.3 b/doc/SubstObj.3 index ca6822b..f10e01d 100644 --- a/doc/SubstObj.3 +++ b/doc/SubstObj.3 @@ -62,6 +62,13 @@ result of the whole substitution on \fIobjPtr\fR will be truncated at the point immediately before the start of the command substitution, and no characters will be added to the result or substitutions performed after that point. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIobjPtr\fR argument to \fBTcl_SubstObj\fR must not have a reference +count of zero. This function modifies the interpreter result, both on success +and on failure; the result of this function on success is exactly the current +interpreter result. Successful results should have their reference count +incremented if they are to be retained. .SH "SEE ALSO" subst(n) .SH KEYWORDS @@ -1,6 +1,7 @@ '\" '\" Copyright (c) 1993 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 2023 Nathan Coulter '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -16,176 +17,152 @@ Summary of Tcl language syntax. .SH DESCRIPTION .PP The following rules define the syntax and semantics of the Tcl language: -.IP "[1] \fBCommands.\fR" -A Tcl script is a string containing one or more commands. -Semi-colons and newlines are command separators unless quoted as -described below. -Close brackets are command terminators during command substitution -(see below) unless quoted. -.IP "[2] \fBEvaluation.\fR" -A command is evaluated in two steps. -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 -in any way it likes, such as an integer, variable name, list, -or Tcl script. -Different commands interpret their words differently. -.IP "[3] \fBWords.\fR" -Words of a command are separated by white space (except for -newlines, which are command separators). -.IP "[4] \fBDouble quotes.\fR" -If the first character of a word is double-quote +. +.IP "[1] \fBScript.\fR" +A script is composed of zero or more commands delimited by semi-colons or +newlines. +.IP "[2] \fBCommand.\fR" +A command is composed of zero or more words delimited by whitespace. The +replacement for a substitution is included verbatim in the word. For example, a +space in the replacement is included in the word rather than becoming a +delimiter, and \fI\\\\\fR becomes a single backslash in the word. Each word is +processed from left to right and each substitution is performed as soon as it +is complete. +For example, the command +.RS +.PP +.CS +set y [set x 0][incr x][incr x] +.CE +.PP +is composed of three words, and sets the value of \fIy\fR to \fI012\fR. +.PP +If hash +.PQ # +is the first character of what would otherwise be the first word of a command, +all characters up to the next newline are ignored. +.RE +. +.IP "[3] \fBBraced word.\fR" +If a word is enclosed in braces +.PQ { +and +.PQ } "" +, the braces are removed and the enclosed characters become the word. No +substitutions are performed. Nested pairs of braces may occur within the word. +A brace preceded by an odd number of backslashes is not considered part of a +pair, and neither brace nor the backslashes are removed from the word. +. +.IP "[4] \fBQuoted word.\fR" +If a word is enclosed in double quotes .PQ \N'34' -then the word is terminated by the next double-quote character. -If semi-colons, close brackets, or white space characters -(including newlines) appear between the quotes then they are treated -as ordinary characters and included in the word. -Command substitution, variable substitution, and backslash substitution -are performed on the characters between the quotes as described below. -The double-quotes are not retained as part of the word. -.IP "[5] \fBArgument expansion.\fR" -If a word starts with the string -.QW {*} -followed by a non-whitespace character, then the leading +, the double quotes are removed and the enclosed characters become the word. +Substitutions are performed. +. +.IP "[5] \fBList.\fR" +A list has the form of a single command. Newline is whitespace, and semicolon +has no special interpretation. There is no script evaluation so there is no +argument expansion, variable substitution, or command substitution: Dollar-sign +and open bracket have no special interpretation, and what would be argument +expansion in a script is invalid in a list. +. +.IP "[6] \fBArgument expansion.\fR" +If .QW {*} -is removed and the rest of the word is parsed and substituted as any other -word. After substitution, the word is parsed as a list (without command or -variable substitutions; backslash substitutions are performed as is normal for -a list and individual internal words may be surrounded by either braces or -double-quote characters), and its words are added to the command being -substituted. For instance, -.QW "cmd a {*}{b [c]} d {*}{$e f {g h}}" +prefixes a word, it is removed. After any remaining enclosing braces or quotes +are processed and applicable substitutions performed, the word, which must +be a list, is removed from the command, and in its place each word in the +list becomes an additional word in the command. For example, +.CS +cmd a {*}{b [c]} d {*}{$e f {g h}} +.CE is equivalent to -.QW "cmd a b {[c]} d {$e} f {g h}" . -.IP "[6] \fBBraces.\fR" -If the first character of a word is an open brace -.PQ { -and rule [5] does not apply, then -the word is terminated by the matching close brace -.PQ } "" . -Braces nest within the word: for each additional open -brace there must be an additional close brace (however, -if an open brace or close brace within the word is -quoted with a backslash then it is not counted in locating the -matching close brace). -No substitutions are performed on the characters between the -braces except for backslash-newline substitutions described -below, nor do semi-colons, newlines, close brackets, -or white space receive any special interpretation. -The word will consist of exactly the characters between the -outer braces, not including the braces themselves. -.IP "[7] \fBCommand substitution.\fR" -If a word contains an open bracket +.CS +cmd a b {[c]} d {$e} f {g h} . +.CE +. +.IP "[7] \fBEvaluation.\fR" +To evaluate a script, an interpreter evaluates each successive command. The +first word identifies a procedure, and the remaining words are passed to that +procedure for further evaluation. The procedure interprets each argument in +its own way, e.g. as an integer, variable name, list, mathematical expression, +script, or in some other arbitrary way. The result of the last command is the +result of the script. +. +.IP "[8] \fBCommand substitution.\fR" +Each pair of brackets .PQ [ -then Tcl performs \fIcommand substitution\fR. -To do this it invokes the Tcl interpreter recursively to process -the characters following the open bracket as a Tcl script. -The script may contain any number of commands and must be terminated -by a close bracket -.PQ ] "" . -The result of the script (i.e. the result of its last command) is -substituted into the word in place of the brackets and all of the -characters between them. -There may be any number of command substitutions in a single word. -Command substitution is not performed on words enclosed in braces. -.IP "[8] \fBVariable substitution.\fR" -If a word contains a dollar-sign +and +.PQ ] "" +encloses a script and is replaced by the result of that script. +.IP "[9] \fBVariable substitution.\fR" +Each of the following forms begins with dollar sign .PQ $ -followed by one of the forms -described below, then Tcl performs \fIvariable -substitution\fR: the dollar-sign and the following characters are -replaced in the word by the value of a variable. -Variable substitution may take any of the following forms: +and is replaced by the value of the identified variable. \fIname\fR names the +variable and is composed of ASCII letters (\fBA\fR\(en\fBZ\fR and +\fBa\fR\(en\fBz\fR), digits (\fB0\fR\(en\fB9\fR), underscores, or namespace +delimiters (two or more colons). \fIindex\fR is the name of an individual +variable within an array variable, and may be empty. .RS .TP 15 \fB$\fIname\fR . -\fIName\fR is the name of a scalar variable; the name is a sequence -of one or more characters that are a letter, digit, underscore, -or namespace separators (two or more colons). -Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\(en\fB9\fR, -\fBA\fR\(en\fBZ\fR and \fBa\fR\(en\fBz\fR). +\fIname\fR may not be empty. + .TP 15 \fB$\fIname\fB(\fIindex\fB)\fR . -\fIName\fR gives the name of an array variable and \fIindex\fR gives -the name of an element within that array. -\fIName\fR must contain only letters, digits, underscores, and -namespace separators, and may be an empty string. -Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\(en\fB9\fR, -\fBA\fR\(en\fBZ\fR and \fBa\fR\(en\fBz\fR). -Command substitutions, variable substitutions, and backslash -substitutions are performed on the characters of \fIindex\fR. +\fIname\fR may be empty. Substitutions are performed on \fIindex\fR. .TP 15 \fB${\fIname\fB}\fR +\fIname\fR may be empty. +.TP 15 +\fB${\fIname(index)\fB}\fR . -\fIName\fR is the name of a scalar variable or array element. It may contain -any characters whatsoever except for close braces. It indicates an array -element if \fIname\fR is in the form -.QW \fIarrayName\fB(\fIindex\fB)\fR -where \fIarrayName\fR does not contain any open parenthesis characters, -.QW \fB(\fR , -or close brace characters, -.QW \fB}\fR , -and \fIindex\fR can be any sequence of characters except for close brace -characters. No further -substitutions are performed during the parsing of \fIname\fR. -.PP -There may be any number of variable substitutions in a single word. -Variable substitution is not performed on words enclosed in braces. -.PP -Note that variables may contain character sequences other than those listed -above, but in that case other mechanisms must be used to access them (e.g., -via the \fBset\fR command's single-argument form). +\fIname\fR may be empty. No substitutions are performed. .RE -.IP "[9] \fBBackslash substitution.\fR" -If a backslash +Variables that are not accessible through one of the forms above may be +accessed through other mechanisms, e.g. the \fBset\fR command. +.IP "[10] \fBBackslash substitution.\fR" +Each backslash .PQ \e -appears within a word then \fIbackslash substitution\fR occurs. -In all cases but those described below the backslash is dropped and -the following character is treated as an ordinary -character and included in the word. -This allows characters such as double quotes, close brackets, -and dollar signs to be included in words without triggering -special processing. -The following table lists the backslash sequences that are -handled specially, along with the value that replaces each sequence. +that is not part of one of the forms listed below is removed, and the next +character is included in the word verbatim, which allows the inclusion of +characters that would normally be interpreted, namely whitespace, braces, +brackets, double quote, dollar sign, and backslash. The following sequences +are replaced as described: +.RS +.RS .RS .TP 7 \e\fBa\fR -Audible alert (bell) (Unicode U+000007). +Audible alert (bell) (U+7). .TP 7 \e\fBb\fR -Backspace (Unicode U+000008). +Backspace (U+8). .TP 7 \e\fBf\fR -Form feed (Unicode U+00000C). +Form feed (U+C). .TP 7 \e\fBn\fR -Newline (Unicode U+00000A). +Newline (U+A). .TP 7 \e\fBr\fR -Carriage-return (Unicode U+00000D). +Carriage-return (U+D). .TP 7 \e\fBt\fR -Tab (Unicode U+000009). +Tab (U+9). .TP 7 \e\fBv\fR -Vertical tab (Unicode U+00000B). +Vertical tab (U+B). .TP 7 \e\fB<newline>\fIwhiteSpace\fR . -A single space character replaces the backslash, newline, and all spaces -and tabs after the newline. This backslash sequence is unique in that it -is replaced in a separate prepass before the command is actually parsed. -This means that it will be replaced even when it occurs between braces, -and the resulting space will be treated as a word separator if it is not -in braces or quotes. +Newline preceded by an odd number of backslashes, along with the consecutive +spaces and tabs that immediately follow it, is replaced by a single space. +Because this happens before the command is split into words, it occurs even +within braced words, and if the resulting space may subsequently be treated as +a word delimiter. .TP 7 \e\e Backslash @@ -193,80 +170,30 @@ Backslash .TP 7 \e\fIooo\fR . -The digits \fIooo\fR (one, two, or three of them) give a eight-bit octal -value for the Unicode character that will be inserted, in the range -\fI000\fR\(en\fI377\fR (i.e., the range U+000000\(enU+0000FF). -The parser will stop just before this range overflows, or when -the maximum of three digits is reached. The upper bits of the Unicode -character will be 0. +Up to three octal digits form an eight-bit value for a Unicode character in the +range \fI0\fR\(en\fI377\fR, i.e. U+0\(enU+FF. Only the digits that result in a +number in this range are consumed. .TP 7 \e\fBx\fIhh\fR . -The hexadecimal digits \fIhh\fR (one or two of them) give an eight-bit -hexadecimal value for the Unicode character that will be inserted. The upper -bits of the Unicode character will be 0 (i.e., the character will be in the -range U+000000\(enU+0000FF). +Up to two hexadecimal digits form an eight-bit value for a Unicode character in +the range \fI0\fR\(en\fIFF\fR. .TP 7 \e\fBu\fIhhhh\fR . -The hexadecimal digits \fIhhhh\fR (one, two, three, or four of them) give a -sixteen-bit hexadecimal value for the Unicode character that will be -inserted. The upper bits of the Unicode character will be 0 (i.e., the -character will be in the range U+000000\(enU+00FFFF). +Up to four hexadecimal digits form a 16-bit value for a Unicode character in +the range \fI0\fR\(en\fIFFFF\fR. .TP 7 \e\fBU\fIhhhhhhhh\fR . -The hexadecimal digits \fIhhhhhhhh\fR (one up to eight of them) give a -twenty-one-bit hexadecimal value for the Unicode character that will be -inserted, in the range U+000000\(enU+10FFFF. The parser will stop just -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. +Up to eight hexadecimal digits form a 21-bit value for a Unicode character in +the range \fI0\fR\(en\fI10FFFF\fR. Only the digits that result in a number in +this range are consumed. .RE -.PP -Backslash substitution is not performed on words enclosed in braces, -except for backslash-newline as described above. .RE -.IP "[10] \fBComments.\fR" -If a hash character -.PQ # -appears at a point where Tcl is -expecting the first character of the first word of a command, -then the hash character and the characters that follow it, up -through the next newline, are treated as a comment and ignored. -The comment character only has significance when it appears -at the beginning of a command. -.IP "[11] \fBOrder of substitution.\fR" -Each character is processed exactly once by the Tcl interpreter -as part of creating the words of a command. -For example, if variable substitution occurs then no further -substitutions are performed on the value of the variable; the -value is inserted into the word verbatim. -If command substitution occurs then the nested command is -processed entirely by the recursive call to the Tcl interpreter; -no substitutions are performed before making the recursive -call and no additional substitutions are performed on the result -of the nested script. -.RS .PP -Substitutions take place from left to right, and each substitution is -evaluated completely before attempting to evaluate the next. Thus, a -sequence like -.PP -.CS -set y [set x 0][incr x][incr x] -.CE -.PP -will always set the variable \fIy\fR to the value, \fI012\fR. .RE -.IP "[12] \fBSubstitution and word boundaries.\fR" -Substitutions do not affect the word boundaries of a command, -except for argument expansion as specified in rule [5]. -For example, during variable substitution the entire value of -the variable becomes part of a single word, even if the variable's -value contains spaces. +. .SH KEYWORDS backslash, command, comment, script, substitution, variable '\" Local Variables: diff --git a/doc/TclZlib.3 b/doc/TclZlib.3 index 4a5df89..c2d7f6d 100644 --- a/doc/TclZlib.3 +++ b/doc/TclZlib.3 @@ -188,7 +188,7 @@ is used to initialize the compression engine rather than leaving it to create it on the fly from the data being compressed. Setting a compression dictionary allows for more efficient compression in the case where the start of the data is highly regular, but it does require both the compressor and the -decompressor to agreee on the value to use. Compression dictionaries are only +decompressor to agree on the value to use. Compression dictionaries are only fully supported for zlib-format data; on compression, they must be set before any data is sent in with \fBTcl_ZlibStreamPut\fR, and on decompression they should be set when \fBTcl_ZlibStreamGet\fR produces an \fBerror\fR with its @@ -262,6 +262,31 @@ file named by the \fBfilename\fR field was modified. Suitable for use with . The type of the uncompressed data (either \fBbinary\fR or \fBtext\fR) if known. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_ZlibDeflate\fR and \fBTcl_ZlibInflate\fR take a value with arbitrary +reference count for their \fIdataObj\fR and \fIdictObj\fR arguments (the +latter often being NULL instead), and set the interpreter result with their +output value (or an error). The existing interpreter result should not be +passed as any argument value unless an additional reference is held. +.PP +\fBTcl_ZlibStreamInit\fR takes a value with arbitrary reference count for its +\fIdictObj\fR argument; it only reads from it. The existing interpreter result +should not be passed unless an additional reference is held. +.PP +\fBTcl_ZlibStreamGetCommandName\fR returns a zero reference count value, much +like \fBTcl_NewObj\fR. +.PP +The \fIdataObj\fR argument to \fBTcl_ZlibStreamPut\fR is a value with +arbitrary reference count; it is only ever read from. +.PP +The \fIdataObj\fR argument to \fBTcl_ZlibStreamGet\fR is an unshared value +(see \fBTcl_IsShared\fR) that will be updated by the function. +.PP +The \fIcompDict\fR argument to \fBTcl_ZlibStreamSetCompressionDictionary\fR, +if non-NULL, may be duplicated or may have its reference count incremented. +Using a zero reference count value is not recommended. + .SH "PORTABILITY NOTES" These functions will fail gracefully if Tcl is not linked with the zlib library. diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3 index 8104ece..6a37cda 100644 --- a/doc/Tcl_Main.3 +++ b/doc/Tcl_Main.3 @@ -85,8 +85,10 @@ that does nothing but invoke \fBTcl_Main\fR. .PP \fBTcl_Main\fR is not provided by the public interface of Tcl's stub library. Programs that call \fBTcl_Main\fR must be linked -against the standard Tcl library. Extensions (stub-enabled or -not) are not intended to call \fBTcl_Main\fR. +against the standard Tcl library. If the standard Tcl library is +a dll (so, not a static .lib/.a) , then the program must be linked +against the stub library as well. Extensions +(stub-enabled or not) are not intended to call \fBTcl_Main\fR. .PP \fBTcl_Main\fR is not thread-safe. It should only be called by a single main thread of a multi-threaded application. This @@ -199,6 +201,17 @@ 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 "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_SetStartupScript\fR takes a value (or NULL) for its \fIpath\fR +argument, and will increment the reference count of it. +.PP +\fBTcl_GetStartupScript\fR returns a value with reference count at least 1, or +NULL. It's \fIencodingPtr\fR is also used (if non-NULL) to return a value with +a reference count at least 1, or NULL. In both cases, the owner of the values +is the current thread. .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..ac60230 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. @@ -67,7 +69,7 @@ This procedure will act as the \fBmain()\fR of the newly created thread. The specified \fIclientData\fR will be its sole argument. .AP ClientData clientData in Arbitrary information. Passed as sole argument to the \fIproc\fR. -.AP int stackSize in +.AP unsigned stackSize in The size of the stack given to the new thread. .AP int flags in Bitmask containing flags allowing the caller to modify behavior of @@ -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 a281e2c..37ebd2b 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 3d506b3..5de6a44 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,16 @@ 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" +.SH "REFERENCE COUNT MANAGEMENT" .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. +When a \fIproc\fR callback is invoked, and that callback was installed with +the \fBTCL_TRACE_RESULT_OBJECT\fR flag, the result of the callback is a +Tcl_Obj reference when there is an error. The result will have its reference +count decremented once when no longer needed, or may have additional +references made to it (e.g., by setting it as the interpreter result with +\fBTcl_SetObjResult\fR). .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_WCharToUtfDString, Tcl_WCharLen, Tcl_Char16Len, 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,11 +21,35 @@ 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, numUniChars, dsPtr\fR) +.sp +char * +\fBTcl_Char16ToUtfDString\fR(\fIutf16, numUtf16, dsPtr\fR) +.sp char * -\fBTcl_UniCharToUtfDString\fR(\fIuniStr, uniLength, dsPtr\fR) +\fBTcl_WCharToUtfDString\fR(\fIwcharStr, numWChars, dsPtr\fR) .sp Tcl_UniChar * -\fBTcl_UtfToUniCharDString\fR(\fIsrc, length, dsPtr\fR) +\fBTcl_UtfToUniCharDString\fR(\fIsrc, numBytes, dsPtr\fR) +.sp +unsigned short * +\fBTcl_UtfToChar16DString\fR(\fIsrc, numBytes, dsPtr\fR) +.sp +wchar_t * +\fBTcl_UtfToWCharDString\fR(\fIsrc, numBytes, dsPtr\fR) +.sp +int +\fBTcl_Char16Len\fR(\fIutf16\fR) +.sp +int +\fBTcl_WCharLen\fR(\fIwcharStr\fR) .sp int \fBTcl_UniCharLen\fR(\fIuniStr\fR) @@ -46,10 +70,10 @@ int \fBTcl_UtfNcasecmp\fR(\fIcs, ct, numChars\fR) .sp int -\fBTcl_UtfCharComplete\fR(\fIsrc, length\fR) +\fBTcl_UtfCharComplete\fR(\fIsrc, numBytes\fR) .sp int -\fBTcl_NumUtfChars\fR(\fIsrc, length\fR) +\fBTcl_NumUtfChars\fR(\fIsrc, numBytes\fR) .sp const char * \fBTcl_UtfFindFirst\fR(\fIsrc, ch\fR) @@ -63,7 +87,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 +99,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 @@ -87,19 +115,32 @@ Pointer to a UTF-8 string. .AP "const char" *ct in Pointer to a UTF-8 string. .AP "const Tcl_UniChar" *uniStr in -A null-terminated Unicode string. +A sequence of \fBTcl_UniChar\fR units with null-termination optional +depending on function. .AP "const Tcl_UniChar" *ucs in -A null-terminated Unicode string. +A null-terminated sequence of \fBTcl_UniChar\fR. .AP "const Tcl_UniChar" *uct in -A null-terminated Unicode string. +A null-terminated sequence of \fBTcl_UniChar\fR. .AP "const Tcl_UniChar" *uniPattern in -A null-terminated Unicode 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. +A null-terminated sequence of \fBTcl_UniChar\fR. +.AP "const unsigned short" *utf16 in +A sequence of UTF-16 units with null-termination optional +depending on function. +.AP "const wchar_t" *wcharStr in +A sequence of \fBwchar_t\fR units with null-termination optional +depending on function. +.AP int numBytes in +The length of the UTF-8 input in bytes. If +negative, the length includes all bytes until the first null byte. +.AP int numUtf16 in +The length of the input in UTF-16 units. +If negative, the length includes all bytes until the first null. +.AP int numUniChars in +The length of the input in Tcl_UniChar units. +If negative, the length includes all bytes until the first null. +.AP int numWChars in +The length of the input in wchar_t units. +If negative, the length includes all bytes until the first null. .AP "Tcl_DString" *dsPtr in/out A pointer to a previously initialized \fBTcl_DString\fR. .AP "unsigned long" numChars in @@ -113,7 +154,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 +162,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,27 +184,39 @@ 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 0x80 and -0xFF and return 1. +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 input in the form of a +sequence of \fBTcl_UniChar\fR code points to UTF-8, appending the result to the +previously initialized output \fBTcl_DString\fR. The return value is a pointer +to the UTF-8 representation of the \fBappended\fR string. +.PP +\fBTcl_UtfToUniCharDString\fR converts the input in the form of +a UTF-8 encoded string to a \fBTcl_UniChar\fR sequence +appending the result in the previously initialized \fBTcl_DString\fR. +The return value is a pointer to the appended result which is also +terminated with a \fBTcl_UniChar\fR null character. +.PP +\fBTcl_WCharToUtfDString\fR and \fBTcl_UtfToWCharDString\fR are similar to +\fBTcl_UniCharToUtfDString\fR and \fBTcl_UtfToUniCharDString\fR except they +operate on sequences of \fBwchar_t\fR instead of \fBTcl_UniChar\fR. +.PP +\fBTcl_Char16ToUtfDString\fR and \fBTcl_UtfToChar16DString\fR are similar to +\fBTcl_UniCharToUtfDString\fR and \fBTcl_UtfToUniCharDString\fR except they +operate on sequences of \fBUTF-16\fR units instead of \fBTcl_UniChar\fR. .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. +\fBTcl_Char16Len\fR corresponds to \fBstrlen\fR for UTF-16 +characters. It accepts a null-terminated UTF-16 sequence and returns +the number of UTF-16 units until the null. .PP -\fBTcl_UtfToUniCharDString\fR converts the given UTF-8 string to Unicode, -storing the result in the previously initialized \fBTcl_DString\fR. -In the argument \fIlength\fR, you may either specify the length of -the given UTF-8 string in bytes or -.QW \-1 , -in which case \fBTcl_UtfToUniCharDString\fR uses \fBstrlen\fR to -calculate the length. The return value is a pointer to the Unicode -representation of the UTF-8 string. Storage for the return value -is appended to the end of the \fBTcl_DString\fR. The Unicode string -is terminated with a Unicode null character. +\fBTcl_WCharLen\fR corresponds to \fBstrlen\fR for wchar_t +characters. It accepts a null-terminated \fBwchar_t\fR sequence and returns +the number of \fBwchar_t\fR units until the null. .PP \fBTcl_UniCharLen\fR corresponds to \fBstrlen\fR for Unicode characters. It accepts a null-terminated Unicode string and returns @@ -196,11 +252,11 @@ differences in case when comparing upper, lower or title case characters. .PP \fBTcl_UtfCharComplete\fR returns 1 if the source UTF-8 string \fIsrc\fR -of \fIlength\fR bytes is long enough to be decoded by +of \fInumBytes\fR bytes is long enough to be decoded by \fBTcl_UtfToUniChar\fR/\fBTcl_UtfNext\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. +know if a 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 +264,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 @@ -239,29 +295,33 @@ always a pointer to a location in the string. It always returns a pointer to a byte that begins a character when scanning for characters beginning from \fIstart\fR. When \fIsrc\fR is greater than \fIstart\fR, it always returns a pointer less than \fIsrc\fR and greater than or -equal to (\fIsrc\fR - \fBTCL_UTF_MAX\fR). The character that begins +equal to (\fIsrc\fR - 4). The character that begins at the returned pointer is the first one that either includes the byte \fIsrc[-1]\fR, or might include it if the right trail bytes are present at \fIsrc\fR and greater. \fBTcl_UtfPrev\fR never reads the byte \fIsrc[0]\fR nor the byte \fIstart[-1]\fR nor the byte -\fIsrc[-\fBTCL_UTF_MAX\fI-1]\fR. +\fIsrc[-5]\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/WrongNumArgs.3 b/doc/WrongNumArgs.3 index 93e2ebb..533cb4f 100644 --- a/doc/WrongNumArgs.3 +++ b/doc/WrongNumArgs.3 @@ -73,6 +73,12 @@ is now an \fIindexObject\fR because it was passed to .CS wrong # args: should be "foo barfly fileName count" .CE +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIobjv\fR argument to \fBTcl_WrongNumArgs\fR should be the exact +arguments passed to the command or method implementation function that is +calling \fBTcl_WrongNumArgs\fR. As such, all values referenced in it should +have reference counts greater than zero; this is usually a non-issue. .SH "SEE ALSO" Tcl_GetIndexFromObj(3) .SH KEYWORDS diff --git a/doc/abstract.n b/doc/abstract.n new file mode 100644 index 0000000..c58abd8 --- /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 tcl::oo + +\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 d39fd11..7968d77 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 @@ -137,7 +132,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 @@ -152,7 +146,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 @@ -160,6 +156,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 @@ -187,29 +184,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 @@ -217,42 +248,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 @@ -260,43 +311,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 @@ -306,22 +380,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 @@ -336,22 +420,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 -\fB\ex03\ex00\ex00\ex00\exfd\exff\exff\exff\ex00\ex00\ex01\ex00\fR +.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 -\fB\ex00\ex00\ex00\ex03\exff\exff\exff\exfd\ex00\ex01\ex00\ex00\fR +.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 @@ -367,20 +461,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 @@ -403,11 +501,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 @@ -424,11 +527,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 @@ -441,26 +549,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 @@ -469,14 +588,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 @@ -498,8 +625,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 @@ -513,6 +641,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 @@ -524,12 +653,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 @@ -541,14 +673,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 @@ -559,8 +694,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 @@ -569,24 +705,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 @@ -597,13 +739,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 @@ -611,12 +756,23 @@ 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 +.IP \fBC\fR 5 +This form is similar to \fBA\fR, except that it scans the data from start +and terminates at the first null (C string semantics). For example, +.RS +.CS +\fBbinary scan\fR "abc\e000efghi" C* var1 +.CE +will return \fB1\fR with \fBabc\fR stored in \fIvar1\fR. +.RE .IP \fBH\fR 5 The data is turned into a string of \fIcount\fR hexadecimal digits in high-to-low order represented as a sequence of characters in the set @@ -624,13 +780,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 +\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 @@ -638,9 +797,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 @@ -649,135 +810,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 +\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 +\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 +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 +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 +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 +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 @@ -786,9 +963,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 +\fBbinary scan\fR \ex3F\exCC\exCC\exCD f var1 .CE +.PP will return \fB1\fR with \fB1.6000000238418579\fR stored in \fIvar1\fR. .RE @@ -808,9 +987,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 +\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 @@ -826,28 +1007,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 @@ -858,9 +1047,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..3ab81ac --- /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 tcl::oo + +\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/case.n b/doc/case.n deleted file mode 100644 index c48d634..0000000 --- a/doc/case.n +++ /dev/null @@ -1,60 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH case n 7.0 Tcl "Tcl Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -case \- Evaluate one of several scripts, depending on a given value -.SH SYNOPSIS -\fBcase\fI string \fR?\fBin\fR? \fIpatList body \fR?\fIpatList body \fR...? -.sp -\fBcase\fI string \fR?\fBin\fR? {\fIpatList body \fR?\fIpatList body \fR...?} -.BE - -.SH DESCRIPTION -.PP -\fINote: the \fBcase\fI command is obsolete and is supported only -for backward compatibility. At some point in the future it may be -removed entirely. You should use the \fBswitch\fI command instead.\fR -.PP -The \fBcase\fR command matches \fIstring\fR against each of -the \fIpatList\fR arguments in order. -Each \fIpatList\fR argument is a list of one or -more patterns. If any of these patterns matches \fIstring\fR then -\fBcase\fR evaluates the following \fIbody\fR argument -by passing it recursively to the Tcl interpreter and returns the result -of that evaluation. -Each \fIpatList\fR argument consists of a single -pattern or list of patterns. Each pattern may contain any of the wild-cards -described under \fBstring match\fR. If a \fIpatList\fR -argument is \fBdefault\fR, the corresponding body will be evaluated -if no \fIpatList\fR matches \fIstring\fR. If no \fIpatList\fR argument -matches \fIstring\fR and no default is given, then the \fBcase\fR -command returns an empty string. -.PP -Two syntaxes are provided for the \fIpatList\fR and \fIbody\fR arguments. -The first uses a separate argument for each of the patterns and commands; -this form is convenient if substitutions are desired on some of the -patterns or commands. -The second form places all of the patterns and commands together into -a single argument; the argument must have proper list structure, with -the elements of the list being the patterns and commands. -The second form makes it easy to construct multi-line case commands, -since the braces around the whole list make it unnecessary to include a -backslash at the end of each line. -Since the \fIpatList\fR arguments are in braces in the second form, -no command or variable substitutions are performed on them; this makes -the behavior of the second form different than the first form in some -cases. - -.SH "SEE ALSO" -switch(n) - -.SH KEYWORDS -case, match, regular expression 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: @@ -1,5 +1,6 @@ '\" '\" Copyright (c) 2005-2006 Donal K. Fellows +'\" Copyright (c) 2021 Nathan Coulter '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -8,771 +9,608 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -chan \- Read, write and manipulate channels +chan \- Reads, writes and manipulates channels. .SH SYNOPSIS -\fBchan \fIoption\fR ?\fIarg arg ...\fR? +\fBchan \fIoperation\fR ?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP -This command provides several operations for reading from, writing to -and otherwise manipulating open channels (such as have been created -with the \fBopen\fR and \fBsocket\fR commands, or the default named -channels \fBstdin\fR, \fBstdout\fR or \fBstderr\fR which correspond to -the process's standard input, output and error streams respectively). -\fIOption\fR indicates what to do with the channel; any unique -abbreviation for \fIoption\fR is acceptable. Valid options are: -.TP -\fBchan blocked \fIchannelId\fR -. -This tests whether the last input operation on the channel called -\fIchannelId\fR failed because it would have otherwise caused the -process to block, and returns 1 if that was the case. It returns 0 -otherwise. Note that this only ever returns 1 when the channel has -been configured to be non-blocking; all Tcl channels have blocking -turned on by default. -.TP -\fBchan close \fIchannelId\fR ?\fIdirection\fR? -. -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 -read-only respectively. If a read-only channel is closed for reading, it is -the same as if the channel is fully closed, and respectively similar for -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 +\fBchan\fR provides several operations for reading from, writing to, and +otherwise manipulating channels, e.g. those created by \fBopen\fR and +\fBsocket\fR, or the default channels \fBstdin\fR, \fBstdout\fR or \fBstderr\fR +which correspond respectively to the standard input, output, and error streams +of the process. Any unique abbreviation for \fIoperation\fR is acceptable. +Available operations are: +.TP +\fBchan blocked \fIchannelName\fR +. +Returns 1 when the channel is in non-blocking mode and the last input operation +on the channel failed because it would have otherwise caused the process to +block, and 0 otherwise. Each Tcl channel is in blocking mode unless configured +otherwise. +.TP +\fBchan close \fIchannelName\fR ?\fIdirection\fR? +. +Closes and destroys the named channel, deleting any existing event handlers +established for the channel, and returns the empty string. If \fIdirection\fR is +given, it is +.QW\fBread\fR +or +.QW\fBwrite\fR +or any unique abbreviation of those words, and only that side of the channel is +closed. I.e. a read-write channel may become read-only or write-only. +Closing a read-only channel for reading, or closing a write-only channel for +writing is the same as simply closing the channel. It is an error to close a +read-only channel for writing or to close a write-only channel for reading. .RS .PP -As part of closing the channel, all buffered output is flushed to the -channel's output device (only if the channel is ceasing to be writable), any -buffered input is discarded (only if the channel is ceasing to be readable), -the underlying operating system resource is closed and \fIchannelId\fR becomes -unavailable for future use (both only if the channel is being completely -closed). -.PP -If the channel is blocking and the channel is ceasing to be writable, the -command does not return until all output is flushed. If the channel is -non-blocking and there is unflushed output, the channel remains open and the -command returns immediately; output will be flushed in the background and the -channel will be closed when all the flushing is complete. -.PP -If \fIchannelId\fR is a blocking channel for a command pipeline then -\fBchan close\fR waits for the child processes to complete. -.PP -If the channel is shared between interpreters, then \fBchan close\fR -makes \fIchannelId\fR unavailable in the invoking interpreter but has -no other effect until all of the sharing interpreters have closed the -channel. When the last interpreter in which the channel is registered -invokes \fBchan close\fR (or \fBclose\fR), the cleanup actions -described above occur. With half-closing, the half-close of the channel only -applies to the current interpreter's view of the channel until all channels -have closed it in that direction (or completely). -See the \fBinterp\fR command for a description of channel sharing. -.PP -Channels are automatically fully closed when an interpreter is destroyed and -when the process exits. Channels are switched to blocking mode, to -ensure that all output is correctly flushed before the process exits. -.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, \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 +When a channel is closed for writing, any buffered output on the channel is +flushed. When a channel is closed for reading, any buffered input is discarded. +When a channel is destroyed the underlying resource is closed and the channel +is thereafter unavailable. +.PP +\fBchan close\fR fully flushes any output before closing the write side of a +channel unless it is non-blocking mode, where it returns immediately and the +channel is flushed in the background before finally being closed. +.PP +\fBchan close\fR may return an error if an error occurs while flushing +output. If a process in a command pipeline created by \fBopen\fR returns an +error (either by returning a non-zero exit code or writing to its standard +error file descriptor), \fBchan close\fR generates an error in the same +manner as \fBexec\fR. +.PP +Closing one side of a socket or command pipeline may lead to the shutdown() or +close() of the underlying system resource, leading to a reaction from whatever +is on the other side of the pipeline or socket. +.PP +If the channel for a command pipeline is in blocking mode, \fBchan close\fR +waits for the connected processes to complete. +.PP +\fBchan close\fR only affects the current interpreter. If the channel is open +in any other interpreter, its state is unchanged there. See \fBinterp\fR for a +description of channel sharing. +.PP +When the last interpreter sharing a channel is destroyed, the channel is +switched to blocking mode and fully flushed and then closed. +.PP +Channels are automatically closed when an interpreter is destroyed and +when the process exits. +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 +\fBTCL_FLUSH_NONBLOCKING_ON_EXIT\fR, which when set and not equal to +.QW \fB0\fR +restores the previous behavior. .RE .TP -\fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... +\fBchan configure \fIchannelName\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... . -Query or set the configuration options of the channel named -\fIchannelId\fR. +Configures or reports the configuration of \fIchannelName\fR. .RS .PP -If no \fIoptionName\fR or \fIvalue\fR arguments are supplied, the -command returns a list containing alternating option names and values -for the channel. If \fIoptionName\fR is supplied but no \fIvalue\fR -then the command returns the current value of the given option. If -one or more pairs of \fIoptionName\fR and \fIvalue\fR are supplied, -the command sets each of the named options to the corresponding -\fIvalue\fR; in this case the return value is an empty string. -.PP -The options described below are supported for all channels. In -addition, each channel type may add options that only it supports. See -the manual entry for the command that creates each type of channel -for the options supported by that specific type of channel. For -example, see the manual entry for the \fBsocket\fR command for additional -options for sockets, and the \fBopen\fR command for additional options for -serial devices. +If no \fIoptionName\fR or \fIvalue\fR arguments are given, +\fBchan configure\fR returns a dictionary of option names and +values for the channel. If \fIoptionName\fR is supplied without a \fIvalue\fR, +\fBchan configure\fR returns the current value of the named option. If one or +more pairs of \fIoptionName\fR and \fIvalue\fR are supplied, +\fBchan configure\fR sets each of the named options to the corresponding +\fIvalue\fR and returns the empty string. +.PP +The options described below are supported for all channels. Each type of +channel may provide additional options. Those options are described in the +relevant documentation. For example, additional options are documented for +\fBsocket\fR, and also for serial devices at \fBopen\fR. .TP \fB\-blocking\fR \fIboolean\fR . -The \fB\-blocking\fR option determines whether I/O operations on the -channel can cause the process to block indefinitely. The value of the -option must be a proper boolean value. Channels are normally in -blocking mode; if a channel is placed into non-blocking mode it will -affect the operation of the \fBchan gets\fR, \fBchan read\fR, \fBchan -puts\fR, \fBchan flush\fR, and \fBchan close\fR commands; see the -documentation for those commands for details. For non-blocking mode to -work correctly, the application must be using the Tcl event loop -(e.g. by calling \fBTcl_DoOneEvent\fR or invoking the \fBvwait\fR -command). +If \fB\-blocking\fR is set to \fBtrue\fR, which is the default, reading from or +writing to the channel may cause the process to block indefinitely. Otherwise, +operations such as \fBchan gets\fR, \fBchan read\fR, \fBchan puts\fR, \fBchan +flush\fR, and \fBchan close\fR take care not to block. Non-blocking mode in +generally requires that the event loop is entered, e.g. by calling +\fBTcl_DoOneEvent\fR or \fBvwait\fR or by using Tk, to give Tcl a chance to +process events on the channel. .TP \fB\-buffering\fR \fInewValue\fR . -If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output -until its internal buffer is full or until the \fBchan flush\fR -command is invoked. If \fInewValue\fR is \fBline\fR, then the I/O -system will automatically flush output for the channel whenever a -newline character is output. If \fInewValue\fR is \fBnone\fR, the I/O -system will flush automatically after every output operation. The -default is for \fB\-buffering\fR to be set to \fBfull\fR except for -channels that connect to terminal-like devices; for these channels the -initial setting is \fBline\fR. Additionally, \fBstdin\fR and -\fBstdout\fR are initially set to \fBline\fR, and \fBstderr\fR is set -to \fBnone\fR. +If \fInewValue\fR is \fBfull\fR, which is the default, output is buffered +until the internal buffer is full or until \fBchan flush\fR is called. If +\fInewValue\fR is \fBline\fR, output is flushed each time a end-of-line +character is written. If \fInewValue\fR is \fBnone\fR, output is flushed after +every output operation. For \fBstdin\fR, \fBstdout\fR, and channels that +connect to terminal-like devices, the default value is \fBline\fR. For +\fBstderr\fR the default value is \fBnone\fR. .TP \fB\-buffersize\fR \fInewSize\fR . -\fINewvalue\fR must be an integer; its value is used to set the size -of buffers, in bytes, subsequently allocated for this channel to store -input or output. \fINewvalue\fR must be a number of no more than one -million, allowing buffers of up to one million bytes in size. -.TP -\fB\-encoding\fR \fIname\fR -. -This option is used to specify the encoding of the channel as one of -the named encodings returned by \fBencoding names\fR or the special -value \fBbinary\fR, so that the data can be converted to and from -Unicode for use in Tcl. For instance, in order for Tcl to read -characters from a Japanese file in \fBshiftjis\fR and properly process -and display the contents, the encoding would be set to \fBshiftjis\fR. -Thereafter, when reading from the channel, the bytes in the Japanese -file would be converted to Unicode as they are read. Writing is also -supported \- as Tcl strings are written to the channel they will -automatically be converted to the specified encoding on output. +\fInewSize\fR, an integer no greater than one million, is the size in bytes of +any input or output buffers subsequently allocated for this channel. +.TP +\fB\-encoding\fR ?\fIname\fR? +. +Sets the encoding of the channel. \fIname\fR is either one of the names +returned by \fBencoding names\fR, or +.QW \fBbinary\fR +\&. Input is converted from the encoding into Unicode, and output is converted +from Unicode to the encoding. .RS .PP -If a file contains pure binary data (for instance, a JPEG image), the -encoding for the channel should be configured to be \fBbinary\fR. Tcl -will then assign no interpretation to the data in the file and simply -read or write raw bytes. The Tcl \fBbinary\fR command can be used to -manipulate this byte-oriented data. It is usually better to set the -\fB\-translation\fR option to \fBbinary\fR when you want to transfer -binary data, as this turns off the other automatic interpretations of -the bytes in the stream as well. -.PP -The default encoding for newly opened channels is the same platform- -and locale-dependent system encoding used for interfacing with the -operating system, as returned by \fBencoding system\fR. +\fBbinary\fR is an alias for \fBiso8859-1\fR: Each byte read from the +channel becomes the Unicode character having the same value as that byte, and +each character written to the channel becomes a single byte in the output, +allowing Tcl to work seamlessly with binary data as long as each "character" in +the data remains in the range of 0 to 255 so that there is no distinction between +binary data and text. For example, A JPEG image can be read from a +\fBbinary\fR channel, manipulated, and then written back to a \fBbinary\fR +channel. + +For working with binary data \fB\-translation binary\fR is usually used +instead, as it sets the encoding to \fBbinary\fR and also disables other +translations on the channel. +.PP +The encoding of a new channel is the value of \fBencoding system\fR, +which returns the platform- and locale-dependent system encoding used to +interface with the operating system, .RE .TP \fB\-eofchar\fR \fIchar\fR .TP -\fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR -. -This option supports DOS file systems that use Control-z (\ex1A) as an -end of file marker. If \fIchar\fR is not an empty string, then this -character signals end-of-file when it is encountered during input. -For output, the end-of-file character is output when the channel is -closed. If \fIchar\fR is the empty string, then there is no special -end of file character marker. For read-write channels, a two-element -list specifies the end of file marker for input and output, -respectively. As a convenience, when setting the end-of-file -character for a read-write channel you can specify a single value that -will apply to both reading and writing. When querying the end-of-file -character of a read-write channel, a two-element list will always be -returned. The default value for \fB\-eofchar\fR is the empty string -in all cases except for files under Windows. In that case the -\fB\-eofchar\fR is Control-z (\ex1A) for reading and the empty string -for writing. -The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7f; -attempting to set \fB\-eofchar\fR to a value outside of this range will -generate an error. -.TP -\fB\-translation\fR \fImode\fR -.TP -\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR -. -In Tcl scripts the end of a line is always represented using a single -newline character (\en). However, in actual files and devices the end -of a line may be represented differently on different platforms, or -even for different devices on the same platform. For example, under -UNIX newlines are used in files, whereas carriage-return-linefeed -sequences are normally used in network connections. On input (i.e., -with \fBchan gets\fR and \fBchan read\fR) the Tcl I/O system -automatically translates the external end-of-line representation into -newline characters. Upon output (i.e., with \fBchan puts\fR), the I/O -system translates newlines to the external end-of-line representation. -The default translation mode, \fBauto\fR, handles all the common cases -automatically, but the \fB\-translation\fR option provides explicit -control over the end of line translations. +\fB\-eofchar\fR \fB{\fIchar outChar\fB}\fR +. +\fIchar\fR signals the end of the data when it is encountered in the input. +For output, \fIoutChar\fR is added when the channel is closed. If \fIchar\fR +is the empty string, there is no special character that marks the end of the +data. For read-write channels, one end-of-file character for input and another +for output may be given. When only one end-of-file character is given it is +applied to input only. + +The default value is the empty string, except that under Windows the default +value for reading is Control-z (\ex1A). The acceptable range is \ex01 - +\ex7F. A value outside this range results in an error. +.VS "TCL8.7 TIP656" +.TP +\fB\-profile\fR \fIprofile\fR +. +Specifies the encoding profile to be used on the channel. The encoding +transforms in use for the channel's input and output will then be subject to the +rules of that profile. Any failures will result in a channel error. See +\fBPROFILES\fR in the \fBencoding(n)\fR documentation for details about encoding +profiles. +.VE "TCL8.7 TIP656" +.TP +\fB\-translation\fR \fItranslation\fR +.TP +\fB\-translation\fR \fB{\fIinTranslation outTranslation\fB}\fR +. +In Tcl a single line feed (\en) represents the end of a line. However, +at the destination the end of a line may be represented differently on +different platforms, or even for different devices on the same platform. For +example, under UNIX line feed is used in files and a +carriage-return-linefeed sequence is normally used in network connections. +Therefore, on input, e.g. with \fBchan gets\fR and \fBchan read\fR, each +external end-of-line character is translated into a line feed. On +output, e.g. with \fBchan puts\fR, each line feed is translated to the external +end-of-line character. The default translation, \fBauto\fR, handles all the common +cases, and \fB\-translation\fR provides explicit control over the end-of-line +character. .RS .PP -The value associated with \fB\-translation\fR is a single item for -read-only and write-only channels. The value is a two-element list for -read-write channels; the read translation mode is the first element of -the list, and the write translation mode is the second element. As a -convenience, when setting the translation mode for a read-write channel -you can specify a single value that will apply to both reading and -writing. When querying the translation mode of a read-write channel, a -two-element list will always be returned. The following values are -currently supported: +Returns the input translation for a read-only channel, the output translation +for a write-only channel, and both the input translation and the the output +translation for a read-write channel. When two translations are given, they +are the input and output translation, respectively. When only one translation +is given for a read-write channel, it is the translation for both input and +output. The following values are currently supported: .TP \fBauto\fR . -As the input translation mode, \fBauto\fR treats any of newline -(\fBlf\fR), carriage return (\fBcr\fR), or carriage return followed by -a newline (\fBcrlf\fR) as the end of line representation. The end of -line representation can even change from line-to-line, and all cases -are translated to a newline. As the output translation mode, -\fBauto\fR chooses a platform specific representation; for sockets on -all platforms Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses -\fBlf\fR, and for the various flavors of Windows it chooses -\fBcrlf\fR. The default setting for \fB\-translation\fR is \fBauto\fR -for both input and output. +The default. For input each occurrence of a line feed (\fBlf\fR), carriage +return (\fBcr\fR), or carriage return followed by a line feed (\fBcrlf\fR) is +translated into a line feed. For output, each line feed is translated into a +platform-specific representation: For all Unix variants it is \fBlf\fR, and +for all Windows variants it is \fBcrlf\fR, except that for sockets on all +platforms it is \fBcrlf\fR for both input and output. .TP \fBbinary\fR . -No end-of-line translations are performed. This is nearly identical -to \fBlf\fR mode, except that in addition \fBbinary\fR mode also sets -the end-of-file character to the empty string (which disables it) and -sets the encoding to \fBbinary\fR (which disables encoding filtering). -See the description of \fB\-eofchar\fR and \fB\-encoding\fR for more -information. +Like \fBlf\fR, no end-of-line translation is performed, but in addition, +\fB\-eofchar\fR is set to the empty string to disable it, and \fB\-encoding\fR +is set to \fBbinary\fR. With this one setting, a channel is fully configured +for binary input and output. .TP \fBcr\fR . -The end of a line in the underlying file or device is represented by a -single carriage return character. As the input translation mode, -\fBcr\fR mode converts carriage returns to newline characters. As the -output translation mode, \fBcr\fR mode translates newline characters -to carriage returns. +The end of a line is represented in the external data by a single carriage +return character. For input, each carriage return is translated to a line +feed, and for output each line feed character is translated to a carriage +return. .TP \fBcrlf\fR . -The end of a line in the underlying file or device is represented by a -carriage return character followed by a linefeed character. As the -input translation mode, \fBcrlf\fR mode converts -carriage-return-linefeed sequences to newline characters. As the -output translation mode, \fBcrlf\fR mode translates newline characters -to carriage-return-linefeed sequences. This mode is typically used on -Windows platforms and for network connections. +The end of a line is represented in the external data by a carriage return +character followed by a line feed. For input, each carriage-return-linefeed +sequence is translated to a line feed. For output, each line feed is +translated to a carriage-return-linefeed sequence. This translation is +typically used for network connections, and also on Windows systems. .TP \fBlf\fR . -The end of a line in the underlying file or device is represented by a -single newline (linefeed) character. In this mode no translations -occur during either input or output. This mode is typically used on -UNIX platforms. +The end of a line in the external data is represented by a line feed so no +translations occur during either input or output. This translation is +typically used on UNIX platforms, .RE .RE .TP \fBchan copy \fIinputChan outputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? . -Copy data from the channel \fIinputChan\fR, which must have been -opened for reading, to the channel \fIoutputChan\fR, which must have -been opened for writing. The \fBchan copy\fR command leverages the -buffering in the Tcl I/O system to avoid extra copies and to avoid -buffering too much data in main memory when copying large files to -slow destinations like network sockets. +Copies data from \fIinputChan\fR to \fIoutputChan\fR, leveraging internal +buffers to avoid extra copies and to avoid buffering too much data in main +memory when copying large files to slow destinations like network sockets. .RS .PP -The \fBchan copy\fR command transfers data from \fIinputChan\fR until -end of file or \fIsize\fR bytes or characters have been transferred; -\fIsize\fR is in bytes if the two channels are using the same encoding, -and is in characters otherwise. If no \fB\-size\fR argument is given, -then the copy goes until end of file. All the data read from -\fIinputChan\fR is copied to \fIoutputChan\fR. Without the -\fB\-command\fR option, \fBchan copy\fR blocks until the copy is -complete and returns the number of bytes or characters (using the same -rules as for the \fB\-size\fR option) written to \fIoutputChan\fR. -.PP -The \fB\-command\fR argument makes \fBchan copy\fR work in the -background. In this case it returns immediately and the -\fIcallback\fR is invoked later when the copy completes. The -\fIcallback\fR is called with one or two additional arguments that -indicates how many bytes were written to \fIoutputChan\fR. If an -error occurred during the background copy, the second argument is the -error string associated with the error. With a background copy, it is -not necessary to put \fIinputChan\fR or \fIoutputChan\fR into -non-blocking mode; the \fBchan copy\fR command takes care of that -automatically. However, it is necessary to enter the event loop by -using the \fBvwait\fR command or by using Tk. -.PP -You are not allowed to do other I/O operations with \fIinputChan\fR or -\fIoutputChan\fR during a background \fBchan copy\fR. If either -\fIinputChan\fR or \fIoutputChan\fR get closed while the copy is in -progress, the current copy is stopped and the command callback is -\fInot\fR made. If \fIinputChan\fR is closed, then all data already -queued for \fIoutputChan\fR is written out. -.PP -Note that \fIinputChan\fR can become readable during a background -copy. You should turn off any \fBchan event\fR or \fBfileevent\fR -handlers during a background copy so those handlers do not interfere -with the copy. Any I/O attempted by a \fBchan event\fR or -\fBfileevent\fR handler will get a -.QW "channel busy" -error. -.PP -\fBChan copy\fR translates end-of-line sequences in \fIinputChan\fR -and \fIoutputChan\fR according to the \fB\-translation\fR option for -these channels (see \fBchan configure\fR above). The translations -mean that the number of bytes read from \fIinputChan\fR can be -different than the number of bytes written to \fIoutputChan\fR. Only -the number of bytes written to \fIoutputChan\fR is reported, either as -the return value of a synchronous \fBchan copy\fR or as the argument -to the callback for an asynchronous \fBchan copy\fR. -.PP -\fBChan copy\fR obeys the encodings and character translations -configured for the channels. This means that the incoming characters -are converted internally first UTF-8 and then into the encoding of the -channel \fBchan copy\fR writes to (see \fBchan configure\fR above for -details on the \fB\-encoding\fR and \fB\-translation\fR options). No -conversion is done if both channels are set to encoding \fBbinary\fR -and have matching translations. If only the output channel is set to -encoding \fBbinary\fR the system will write the internal UTF-8 -representation of the incoming characters. If only the input channel -is set to encoding \fBbinary\fR the system will assume that the -incoming bytes are valid UTF-8 characters and convert them according -to the output encoding. The behaviour of the system for bytes which -are not valid UTF-8 characters is undefined in this case. +If \fB\-size\fR is given, the size is in bytes if the two channels have the +same encoding and in characters otherwise, and only that amount is copied. +Otherwise, all data until the end of the file is copied. + +\fBchan copy\fR blocks until the copy is complete and returns the number of +bytes or characters written to \fIoutputChan\fR. +.PP +If \fB\-command\fR is given, \fBchan copy\fR returns immediately, the copy is +carried out in the background, and then \fIcallback\fR is called with the +number of bytes written to \fIoutputChan\fR as its first argument, and the +error message for any error that occurred as its second argument. +\fIinputChan\fR and \fIoutputChan\fR are automatically configured for +non-blocking mode if needed. Background copying only works correctly if the +event loop is active, e.g. via \fBvwait\fR or Tk. +.PP +During a background copy no other read or write operation may be performed on +\fIinputChan\fR or \fIoutputChan\fR. If either \fIinputChan\fR or +\fIoutputChan\fR is closed while the copy is in progress copying ceases and +\fBno\fR callback is made. If \fIinputChan\fR is closed all data already queued +is written to \fIoutputChan\fR. +.PP +The should be no event handler established for \fIinputChan\fR because it may +become readable during a background copy. An attempt to read or write +from within an event handler results result in the error, "channel busy". +.PP +Due to end-of-line translation the number of bytes read from \fIinputChan\fR +may be different than the number of bytes written to \fIoutputChan\fR. Only +the number of bytes written to \fIoutputChan\fR is reported. +.PP +\fBChan copy\fR reads the data according to the \fB\-encoding\fR, +\fB\-translation\fR, and \fB\-eofchar\fR of the source and writes to the +destination according to the configuration for that channel. If the encoding +and translation of both channels is \fBbinary\fR and the \fB\-eofchar\fR of +both channels is the empty string, an identical copy is made. If only the +encoding of the destination is \fBbinary\fR, Tcl's internal modified UTF-8 +representation of the characters read from the source is written to the +destination. If only the encoding of the source is \fBbinary\fR, each byte read +becomes one Unicode character in the range of 0 to 255, and that character is +subject to the encoding and translation of the destination as it is written. .RE .TP \fBchan create \fImode cmdPrefix\fR . -This subcommand creates a new script level channel using the command -prefix \fIcmdPrefix\fR as its handler. Any such channel is called a -\fBreflected\fR channel. The specified command prefix, \fBcmdPrefix\fR, -must be a non-empty list, and should provide the API described in the -\fBrefchan\fR manual page. The handle of the new channel is -returned as the result of the \fBchan create\fR command, and the -channel is open. Use either \fBclose\fR or \fBchan close\fR to remove -the channel. +Creates a new channel, called a \fBreflected\fR channel, with \fIcmdPrefix\fR +as its handler, and returns the name of the channel. \fBcmdPrefix\fR is the +first words of a command that provides the interface for a \fBrefchan\fR. .RS .PP -The argument \fImode\fR specifies if the new channel is opened for -reading, writing, or both. It has to be a list containing any of the -strings +\fBImode\fR is a list of one or more of the strings .QW \fBread\fR or -.QW \fBwrite\fR . -The list must have at least one -element, as a channel you can neither write to nor read from makes no -sense. The handler command for the new channel must support the chosen -mode, or an error is thrown. -.PP -The command prefix is executed in the global namespace, at the top of -call stack, following the appending of arguments as described in the -\fBrefchan\fR manual page. Command resolution happens at the -time of the call. Renaming the command, or destroying it means that -the next call of a handler method may fail, causing the channel -command invoking the handler to fail as well. Depending on the -subcommand being invoked, the error message may not be able to explain -the reason for that failure. -.PP -Every channel created with this subcommand knows which interpreter it -was created in, and only ever executes its handler command in that -interpreter, even if the channel was shared with and/or was moved into -a different interpreter. Each reflected channel also knows the thread -it was created in, and executes its handler command only in that -thread, even if the channel was moved into a different thread. To this -end all invocations of the handler are forwarded to the original -thread by posting special events to it. This means that the original -thread (i.e. the thread that executed the \fBchan create\fR command) -must have an active event loop, i.e. it must be able to process such -events. Otherwise the thread sending them will \fIblock -indefinitely\fR. Deadlock may occur. -.PP -Note that this permits the creation of a channel whose two endpoints -live in two different threads, providing a stream-oriented bridge -between these threads. In other words, we can provide a way for -regular stream communication between threads instead of having to send -commands. -.PP -When a thread or interpreter is deleted, all channels created with -this subcommand and using this thread/interpreter as their computing -base are deleted as well, in all interpreters they have been shared -with or moved into, and in whatever thread they have been transferred -to. While this pulls the rug out under the other thread(s) and/or -interpreter(s), this cannot be avoided. Trying to use such a channel -will cause the generation of a regular error about unknown channel -handles. -.PP -This subcommand is \fBsafe\fR and made accessible to safe -interpreters. While it arranges for the execution of arbitrary Tcl -code the system also makes sure that the code is always executed -within the safe interpreter. +.QW \fBwrite\fR , +indicating whether the channel is a read channel, a write channel, or both. +It is an error if the handler does not support the chosen mode. +.PP +The handler is called as needed from the global namespace at the top level, and +command resolution happens there at the time of the call. If the handler is +renamed or deleted any subsequent attempt to call it is an error, which may +not be able to describe the failure. +.PP +The handler is always called in the interpreter and thread it was created in, +even if the channel was shared with or moved into a different interpreter in a +different thread. This is achieved through event dispatch, so if the event +loop is not entered, e.g. by calling \fBTcl_DoOneEvent\fR or \fBvwait\fR or +using Tk, the thread performing the channel operation \fIblocks +indefinitely\fR, resulting in deadlock. +.PP +One side of a channel may be in one thread while the other side is in a +different thread, providing a stream-oriented bridge between the threads. This +provides a method for regular stream communication between threads as an +alternative to sending commands. +.PP +When the interpreter the handler is in is deleted each channel associated with +the handler is deleted as well, regardless of which interpreter or thread it +is currently in or shared with. +.PP +\fBchan create\fR is \fBsafe\fR and is accessible to safe interpreters. The +handler is always called in the safe interpreter it was created in. .RE .TP -\fBchan eof \fIchannelId\fR -. -Test whether the last input operation on the channel called -\fIchannelId\fR failed because the end of the data stream was reached, -returning 1 if end-of-file was reached, and 0 otherwise. -.TP -\fBchan event \fIchannelId event\fR ?\fIscript\fR? -. -Arrange for the Tcl script \fIscript\fR to be installed as a \fIfile -event handler\fR to be called whenever the channel called -\fIchannelId\fR enters the state described by \fIevent\fR (which must -be either \fBreadable\fR or \fBwritable\fR); only one such handler may -be installed per event per channel at a time. If \fIscript\fR is the -empty string, the current handler is deleted (this also happens if the -channel is closed or the interpreter deleted). If \fIscript\fR is -omitted, the currently installed script is returned (or an empty -string if no such handler is installed). The callback is only -performed if the event loop is being serviced (e.g. via \fBvwait\fR or -\fBupdate\fR). -.RS -.PP -A file event handler is a binding between a channel and a script, such -that the script is evaluated whenever the channel becomes readable or -writable. File event handlers are most commonly used to allow data to -be received from another process on an event-driven basis, so that the -receiver can continue to interact with the user or with other channels -while waiting for the data to arrive. If an application invokes -\fBchan gets\fR or \fBchan read\fR on a blocking channel when there is -no input data available, the process will block; until the input data -arrives, it will not be able to service other events, so it will -appear to the user to -.QW "freeze up" . -With \fBchan event\fR, the -process can tell when data is present and only invoke \fBchan gets\fR -or \fBchan read\fR when they will not block. -.PP -A channel is considered to be readable if there is unread data -available on the underlying device. A channel is also considered to -be readable if there is unread data in an input buffer, except in the -special case where the most recent attempt to read from the channel -was a \fBchan gets\fR call that could not find a complete line in the -input buffer. This feature allows a file to be read a line at a time -in non-blocking mode using events. A channel is also considered to be -readable if an end of file or error condition is present on the -underlying file or device. It is important for \fIscript\fR to check -for these conditions and handle them appropriately; for example, if -there is no special check for end of file, an infinite loop may occur -where \fIscript\fR reads no data, returns, and is immediately invoked -again. -.PP -A channel is considered to be writable if at least one byte of data -can be written to the underlying file or device without blocking, or -if an error condition is present on the underlying file or device. -Note that client sockets opened in asynchronous mode become writable -when they become connected or if the connection fails. -.PP -Event-driven I/O works best for channels that have been placed into -non-blocking mode with the \fBchan configure\fR command. In blocking -mode, a \fBchan puts\fR command may block if you give it more data -than the underlying file or device can accept, and a \fBchan gets\fR -or \fBchan read\fR command will block if you attempt to read more data -than is ready; no events will be processed while the commands block. -In non-blocking mode \fBchan puts\fR, \fBchan read\fR, and \fBchan -gets\fR never block. -.PP -The script for a file event is executed at global level (outside the -context of any Tcl procedure) in the interpreter in which the \fBchan -event\fR command was invoked. If an error occurs while executing the -script then the command registered with \fBinterp bgerror\fR is used -to report the error. In addition, the file event handler is deleted -if it ever returns an error; this is done in order to prevent infinite -loops due to buggy handlers. -.RE +\fBchan eof \fIchannelName\fR +. +Returns 1 if the last read on the channel failed because the end of the data +was already reached, and 0 otherwise. .TP -\fBchan flush \fIchannelId\fR +\fBchan event \fIchannelName event\fR ?\fIscript\fR? . -Ensures that all pending output for the channel called \fIchannelId\fR -is written. +Arranges for the given script, called a \fBchannel event handler\fR, to be +called whenever the given event, one of +.QW \fBreadable\fR +or +.QW \fBwritable\fR +occurs on the given channel, replacing any script that was previously set. If +\fIscript\fR is the empty string the current handler is deleted. It is also +deleted when the channel is closed. If \fIscript\fR is omitted, either the +existing script or the empty string is returned. The event loop must be +entered, e.g. via \fBvwait\fR or \fBupdate\fR, or by using Tk, for handlers to +be evaluated. + .RS .PP -If the channel is in blocking mode the command does not return until -all the buffered output has been flushed to the channel. If the -channel is in non-blocking mode, the command may return before all -buffered output has been flushed; the remainder will be flushed in the -background as fast as the underlying file or device is able to absorb -it. +\fIscript\fR is evaluated at the global level in the interpreter it was +established in. Any resulting error is handled in the background, i.e. via +\fBinterp bgerror\fR. In order to prevent an endless loop due to a buggy +handler, the handler is deleted if \fIscript\fR returns an error so that it is +not evaluated again. + +.PP +Without an event handler, \fBchan gets\fR or \fBchan read\fR on a channel in +blocking mode may block until data becomes available, become during which the +thread is unable to perform other work or respond to events on other channels. +This could cause the application to appear to +.QW "freeze up" +\&. +Channel event handlers allow events on the channel to direct channel handling +so that the reader or writer can continue to perform other processing while +waiting for a channel to become available and then handle channel operations +when the channel is ready for the operation. +.PP +A +.QW readable +event occurs when there is data that can be read from the channel and also when +there is an error on the channel. The handler must check for these conditions +and handle them appropriately. For example, a handler that does not check +whether the end of the data has been reached may be repeatedly evaluated in a +busy loop until the channel is closed. +.PP +A +.QW writable +event occurs when at least one byte of data can be written, or if there is an +error on the channel. A client socket opened in non-blocking mode becomes +writable when it becomes connected or if the connection fails. +.PP +Event-driven channel handling works best for channels in non-blocking mode. A +channel in blocking mode blocks when \fBchan puts\fR writes more data than the +channel can accept at the moment, and when \fBchan gets\fR or \fBchan read\fR +requests more data than is currently available. When a channel blocks, the +thread can not do any other processing or service any other events. A channel +in non-blocking mode allows a thread to carry on with other work and get back +to the channel at the right time. .RE .TP -\fBchan gets \fIchannelId\fR ?\fIvarName\fR? -. -Reads the next line from the channel called \fIchannelId\fR. If -\fIvarName\fR is not specified, the result of the command will be the -line that has been read (without a trailing newline character) or an -empty string upon end-of-file or, in non-blocking mode, if the data -available is exhausted. If \fIvarName\fR is specified, the line that -has been read will be written to the variable called \fIvarName\fR and -result will be the number of characters that have been read or -1 if -end-of-file was reached or, in non-blocking mode, if the data -available is exhausted. +\fBchan flush \fIchannelName\fR +. +For a channel in blocking mode, flushes all buffered output to the destination, +and then returns. For a channel in non-blocking mode, returns immediately +while all buffered output is flushed in the background as soon as possible. +.TP +\fBchan gets \fIchannelName\fR ?\fIvarName\fR? +. +Returns the next line from the channel, removing the trailing line feed, or if +\fIvarName\fR is given, assigns the line to that variable and returns the +number of characters read. +the line that was read, removing the trailing line feed, or returns the +empty string if there is no data to return and the end of the file has been +reached, or in non-blocking mode, if no complete line is currently available. +If \fIvarName\fR is given, assigns the line that was read to variable named +\fIvarName\fR and returns the number of characters that were read, or -1 if +there no data available and the end of the channel was reached or the channel +is in non-blocking mode. .RS .PP -If an end-of-file occurs while part way through reading a line, the -partial line will be returned (or written into \fIvarName\fR). When -\fIvarName\fR is not specified, the end-of-file case can be -distinguished from an empty line using the \fBchan eof\fR command, and -the partial-line-but-non-blocking case can be distinguished with the -\fBchan blocked\fR command. +If the end of the channel is reached the data read so far is returned or +assigned to \fIvarName\fR. When \fIvarName\fR is not given, \fBchan eof\fR may +indicate that the empty string means that the end of the data has been reached, +and \fBchan blocked\fR may indicate that that the empty string means there +isn't currently enough data do return the next line. .RE .TP \fBchan names\fR ?\fIpattern\fR? . -Produces a list of all channel names. If \fIpattern\fR is specified, -only those channel names that match it (according to the rules of -\fBstring match\fR) will be returned. +Returns a list of all channel names, or if \fIpattern\fR is given, only those +names that match according to the rules of \fBstring match\fR. .TP -\fBchan pending \fImode channelId\fR +\fBchan pending \fImode channelName\fR . -Depending on whether \fImode\fR is \fBinput\fR or \fBoutput\fR, -returns the number of -bytes of input or output (respectively) currently buffered -internally for \fIchannelId\fR (especially useful in a readable event -callback to impose application-specific limits on input line lengths to avoid -a potential denial-of-service attack where a hostile user crafts -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. +Returns the number of bytes of input +when \fImode\fR is +.QW\fBinput\fR +, or output when \fImode\fR is +.QW\fBoutput\fR +, that are currently internally buffered for the channel. Useful in a readable +event callback to impose limits on input line length to avoid a potential +denial-of-service attack where an extremely long line 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 -separately \fBstderr\fR and \fBstdout\fR from a subprocess. To do -this, spawn with "2>@" or -">@" redirection operators onto the write side of a pipe, and then -immediately close it in the parent. This is necessary to get an EOF on -the read side once the child has exited or otherwise closed its output. +Creates a pipe, i.e. a readable channel and a writable channel, and returns the +names of the readable channel and the writable channel. Data written to the +writable channel can be read from the readable channel. Because the pipe is a +real system-level pipe, it can be connected to other processes using +redirection. For example, to redirect \fBstderr\fR from a subprocess into one +channel, and \fBstdout\fR into another, \fBexec\fR with "2>@" and ">@", each +onto the writable side of a pipe, closing the writable side immediately +thereafter so that EOF is signaled on the read side once the subprocess has +closed its output, typically on exit. .RS .PP -Note that the pipe buffering semantics can vary at the operating system level -substantially; it is not safe to assume that a write performed on the output -side of the pipe will appear instantly to the input side. This is a -fundamental difference and Tcl cannot conceal it. The overall stream semantics -\fIare\fR compatible, so blocking reads and writes will not see most of the -differences, but the details of what exactly gets written when are not. This -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. +Due to buffering, data written to one side of a pipe might not immediately +become available on the other side. Tcl's own buffers can be configured via +\fBchan configure -buffering\fR, but overall behaviour still depends on +operating system buffers outside of Tcl's control. Once the write side of the +channel is closed, any data remaining in the buffers is flushed through to the +read side. It may be useful to arrange for the connected process to flush at +some point after writing to the channel or to have it use some system-provided +mechanism to configure buffering. When two pipes are connected to the same +process, one to send data to the process, and one to read data from the +process, a deadlock may occur if the channels are in blocking mode: If +reading, the channel may block waiting for data that can never come because +buffers are only flushed on subsequent writes, and if writing, the channel may +block while waiting for the buffers to become free, which can never happen +because the reader can not read while the writer is blocking. To avoid this +issue, either put the channels into non-blocking mode and use event handlers, +or place the read channel and the write channel in separate interpreters in +separate threads. .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 -. -This subcommand is used by command handlers specified with \fBchan -create\fR. It notifies the channel represented by the handle -\fIchannelId\fR that the event(s) listed in the \fIeventSpec\fR have -occurred. The argument has to be a list containing any of the strings -\fBread\fR and \fBwrite\fR. The list must contain at least one -element as it does not make sense to invoke the command if there are -no events to post. +.TP +\fBchan pop \fIchannelName\fR +Removes the topmost transformation handler from the channel if there is one, +and closes the channel otherwise. The result is normally the empty string, but +may be an error in some situations, e.g. when closing the underlying resource +results in an error. +.TP +\fBchan postevent \fIchannelName eventSpec\fR +. +For use by handlers established with \fBchan create\fR. Notifies Tcl that +that one or more event(s) listed in \fIeventSpec\fR, each of which is either +.QW\fBread\fR +or +.QW\fBwrite\fR. +, have occurred. .RS .PP -Note that this subcommand can only be used with channel handles that -were created/opened by \fBchan create\fR. All other channels will -cause this subcommand to report an error. -.PP -As only the Tcl level of a channel, i.e. its command handler, should -post events to it we also restrict the usage of this command to the -interpreter that created the channel. In other words, posting events -to a reflected channel from an interpreter that does not contain it's -implementation is not allowed. Attempting to post an event from any -other interpreter will cause this subcommand to report an error. -.PP -Another restriction is that it is not possible to post events that the -I/O core has not registered an interest in. Trying to do so will cause -the method to throw an error. See the command handler method -\fBwatch\fR described in \fBrefchan\fR, the document specifying -the API of command handlers for reflected channels. -.PP -This command is \fBsafe\fR and made accessible to safe interpreters. -It can trigger the execution of \fBchan event\fR handlers, whether in the -current interpreter or in other interpreters or other threads, even -where the event is posted from a safe interpreter and listened for by -a trusted interpreter. \fBChan event\fR handlers are \fIalways\fR -executed in the interpreter that set them up. +For use only by handlers for a channel created by \fBchan create\fR. It is an +error to post an event for any other channel. +.PP +Since only the handler for a reflected channel channel should post events it is +an error to post an event from any interpreter other than the interpreter that +created the channel. +.PP +It is an error to post an event that the channel has no interest in. See +\fBwatch\fR in the \fBrefchan\fR documentation for more information +.PP +\fBchan postevent\fR is available in safe interpreters, as any handler for a +reflected channel would have been created, and will be evaluated in that +interpreter as well. .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 -prefix must provide the API described in the \fBtranschan\fR manual page. -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 -. -Writes \fIstring\fR to the channel named \fIchannelId\fR followed by a -newline character. A trailing newline character is written unless the -optional flag \fB\-nonewline\fR is given. If \fIchannelId\fR is -omitted, the string is written to the standard output channel, +\fBchan push \fIchannelName cmdPrefix\fR +Adds a new transformation handler on top of the channel and returns a handle +for the transformation. \fIcmdPrefix\fR is the first words of a command that +provides the interface documented for \fBtranschan\fR, and transforms data on +the channel, It is an error if handler does not support the mode(s) the channel +is in. +.TP +\fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelName\fR? \fIstring\fR +. +Writes \fIstring\fR and a line feed to the channel. If \fB\-nonewline\fR is +given, the trailing line feed is not written. The default channel is \fBstdout\fR. .RS .PP -Newline characters in the output are translated by \fBchan puts\fR to -platform-specific end-of-line sequences according to the currently -configured value of the \fB\-translation\fR option for the channel -(for example, on PCs newlines are normally replaced with -carriage-return-linefeed sequences; see \fBchan configure\fR above for -details). -.PP -Tcl buffers output internally, so characters written with \fBchan -puts\fR may not appear immediately on the output file or device; Tcl -will normally delay output until the buffer is full or the channel is -closed. You can force output to appear immediately with the \fBchan -flush\fR command. -.PP -When the output buffer fills up, the \fBchan puts\fR command will -normally block until all the buffered data has been accepted for -output by the operating system. If \fIchannelId\fR is in non-blocking -mode then the \fBchan puts\fR command will not block even if the -operating system cannot accept the data. Instead, Tcl continues to -buffer the data and writes it in the background as fast as the -underlying file or device can accept it. The application must use the -Tcl event loop for non-blocking output to work; otherwise Tcl never -finds out that the file or device is ready for more output data. It -is possible for an arbitrarily large amount of data to be buffered for -a channel in non-blocking mode, which could consume a large amount of -memory. To avoid wasting memory, non-blocking I/O should normally be -used in an event-driven fashion with the \fBchan event\fR command -(do not invoke \fBchan puts\fR unless you have recently been notified -via a file event that the channel is ready for more output data). +Each line feed in the output is translated according to the configuration of +\fB\-translation\fR. +.PP +Because Tcl internally buffers output, characters written to a channel may not +immediately be available at the destination. Tcl normally delays output until +the buffer is full or the channel is closed. \fBchan flush\fR forces output in +the direction of the destination. +.PP +When the output for a channel in blocking mode fills up, \fBchan puts\fR blocks +until space in the buffer is available again, but for a channel in non-blocking +mode, it returns immediately and the data is written in the background as fast +possible, constrained by the speed at which as the destination accepts it. +Output to a channel in non-blocking mode only works properly when the +application enters the event loop, giving Tcl a chance to find out that the +destination is ready to accept more data. When a channel is in non-blocking +mode, Tcl's internal buffers can hold an arbitrary amount of data, possibly +consuming a large amount of memory. To avoid wasting memory, channels in +non-blocking mode should normally be handled using \fBchan event\fR, where the +application only invokes \fBchan puts\fR after being recently notified through +a file event handler that the channel is ready for more output data. .RE .TP -\fBchan read \fIchannelId\fR ?\fInumChars\fR? +\fBchan read \fIchannelName\fR ?\fInumChars\fR? .TP -\fBchan read \fR?\fB\-nonewline\fR? \fIchannelId\fR +\fBchan read \fR?\fB\-nonewline\fR? \fIchannelName\fR . -In the first form, the result will be the next \fInumChars\fR -characters read from the channel named \fIchannelId\fR; if -\fInumChars\fR is omitted, all characters up to the point when the -channel would signal a failure (whether an end-of-file, blocked or -other error condition) are read. In the second form (i.e. when -\fInumChars\fR has been omitted) the flag \fB\-nonewline\fR may be -given to indicate that any trailing newline in the string that has -been read should be trimmed. +Reads and returns the next \fInumChars\fR characters from the channel. If +\fInumChars\fR is omitted, all available characters up to the end of the file +are read, or if the channel is in non-blocking mode, all currently-available +characters are read. If there is an error on the channel, reading ceases and +an error is returned. If \fInumChars\fR is not given, \fB\-nonewline\fR +may be given, causing any any trailing line feed to be trimmed. .RS .PP -If \fIchannelId\fR is in non-blocking mode, \fBchan read\fR may not -read as many characters as requested: once all available input has -been read, the command will return the data that is available rather -than blocking for more input. If the channel is configured to use a -multi-byte encoding, then there may actually be some bytes remaining -in the internal buffers that do not form a complete character. These -bytes will not be returned until a complete character is available or -end-of-file is reached. The \fB\-nonewline\fR switch is ignored if -the command returns before reaching the end of the file. -.PP -\fBChan read\fR translates end-of-line sequences in the input into -newline characters according to the \fB\-translation\fR option for the -channel (see \fBchan configure\fR above for a discussion on the ways -in which \fBchan configure\fR will alter input). -.PP -When reading from a serial port, most applications should configure -the serial port channel to be non-blocking, like this: -.PP -.CS -\fBchan configure \fIchannelId \fB\-blocking \fI0\fR. -.CE -.PP -Then \fBchan read\fR behaves much like described above. Note that -most serial ports are comparatively slow; it is entirely possible to -get a \fBreadable\fR event for each character read from them. Care -must be taken when using \fBchan read\fR on blocking serial ports: -.TP -\fBchan read \fIchannelId numChars\fR -. -In this form \fBchan read\fR blocks until \fInumChars\fR have been -received from the serial port. -.TP -\fBchan read \fIchannelId\fR -. -In this form \fBchan read\fR blocks until the reception of the -end-of-file character, see \fBchan configure -eofchar\fR. If there no -end-of-file character has been configured for the channel, then -\fBchan read\fR will block forever. +If the channel is in non-blocking mode, fewer characters than requested may be +returned. If the channel is configured to use a multi-byte encoding, bytes +that do not form a complete character are retained in the buffers until enough +bytes to complete the character accumulate, or the end of the data is reached. +\fB\-nonewline\fR is ignored if characters are returned before reaching the end +of the file. +.PP +Each end-of-line sequence according to the value of \fB\-translation\fR is +translated into a line feed. +.PP +When reading from a serial port, most applications should configure the serial +port channel to be in non-blocking mode, but not necessarily use an event +handler since most serial ports are comparatively slow. It is entirely +possible to get a \fBreadable\fR event for each individual character. In +blocking mode, \fBchan read\fR blocks forever when reading to the end of the +data if there is no \fBchan configure -eofchar\fR configured for the channel. .RE .TP -\fBchan seek \fIchannelId offset\fR ?\fIorigin\fR? +\fBchan seek \fIchannelName offset\fR ?\fIorigin\fR? . -Sets the current access position within the underlying data stream for -the channel named \fIchannelId\fR to be \fIoffset\fR bytes relative to -\fIorigin\fR. \fIOffset\fR must be an integer (which may be negative) -and \fIorigin\fR must be one of the following: +Sets the current position for the data in the channel to integer \fIoffset\fR +bytes relative to \fIorigin\fR. A negative offset moves the current position +backwards from the origin. \fIorigin\fR is one of the +following: .RS +.PP .TP 10 \fBstart\fR . -The new access position will be \fIoffset\fR bytes from the start -of the underlying file or device. +The origin is the start of the data. This is the default. .TP 10 \fBcurrent\fR . -The new access position will be \fIoffset\fR bytes from the current -access position; a negative \fIoffset\fR moves the access position -backwards in the underlying file or device. +The origin is the current position. .TP 10 \fBend\fR . -The new access position will be \fIoffset\fR bytes from the end of the -file or device. A negative \fIoffset\fR places the access position -before the end of file, and a positive \fIoffset\fR places the access -position after the end of file. -.PP -The \fIorigin\fR argument defaults to \fBstart\fR. +The origin is the end of the data. .PP -\fBChan seek\fR flushes all buffered output for the channel before the -command returns, even if the channel is in non-blocking mode. It also -discards any buffered and unread input. This command returns an empty -string. An error occurs if this command is applied to channels whose -underlying file or device does not support seeking. +\fBChan seek\fR flushes all buffered output even if the channel is in +non-blocking mode, discards any buffered and unread input, and returns the +empty string or an error if the channel does not support seeking. .PP -Note that \fIoffset\fR values are byte offsets, not character offsets. -Both \fBchan seek\fR and \fBchan tell\fR operate in terms of bytes, -not characters, unlike \fBchan read\fR. +\fIoffset\fR values are byte offsets, not character offsets. Unlike \fBchan +read\fR, both \fBchan seek\fR and \fBchan tell\fR operate in terms of bytes, +not characters, .RE .TP -\fBchan tell \fIchannelId\fR +\fBchan tell \fIchannelName\fR . -Returns a number giving the current access position within the -underlying data stream for the channel named \fIchannelId\fR. This -value returned is a byte offset that can be passed to \fBchan seek\fR -in order to set the channel to a particular position. Note that this -value is in terms of bytes, not characters like \fBchan read\fR. The -value returned is -1 for channels that do not support seeking. +Returns the offset in bytes of the current position in the underlying data, or +-1 if the channel does not suport seeking. The value can be passed to \fBchan +seek\fR to set current position to that offset. .TP -\fBchan truncate \fIchannelId\fR ?\fIlength\fR? +\fBchan truncate \fIchannelName\fR ?\fIlength\fR? . -Sets the byte length of the underlying data stream for the channel -named \fIchannelId\fR to be \fIlength\fR (or to the current byte -offset within the underlying data stream if \fIlength\fR is -omitted). The channel is flushed before truncation. +Flushes the channel and truncates the data in the channel to \fIlength\fR +bytes, or to the current position in bytes if \fIlength\fR is omitted. . .SH EXAMPLES .PP -This opens a file using a known encoding (CP1252, a very common encoding -on Windows), searches for a string, rewrites that part, and truncates the -file after a further two lines. +In the following example a file is opened using the encoding CP1252, which is +common on Windows, searches for a string, rewrites that part, and truncates the +file two lines later. .PP .CS set f [open somefile.txt r+] @@ -782,7 +620,7 @@ set offset 0 \fI# Search for string "FOOBAR" in the file\fR while {[\fBchan gets\fR $f line] >= 0} { set idx [string first FOOBAR $line] - if {$idx > -1} { + if {$idx >= 0} { \fI# Found it; rewrite line\fR \fBchan seek\fR $f [expr {$offset + $idx}] @@ -803,12 +641,12 @@ while {[\fBchan gets\fR $f line] >= 0} { \fBchan close\fR $f .CE .PP -A network server that does echoing of its input line-by-line without -preventing servicing of other connections at the same time. +A network server that echoes its input line-by-line without +preventing servicing of other connections at the same time: .PP .CS # This is a very simple logger... -proc log {message} { +proc log message { \fBchan puts\fR stdout $message } diff --git a/doc/class.n b/doc/class.n index 198ae41..c48f52d 100644 --- a/doc/class.n +++ b/doc/class.n @@ -12,7 +12,7 @@ oo::class \- class of all classes .SH SYNOPSIS .nf -package require TclOO +package require tcl::oo \fBoo::class\fI method \fR?\fIarg ...\fR? .fi diff --git a/doc/classvariable.n b/doc/classvariable.n new file mode 100644 index 0000000..70d9f13 --- /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 tcl::oo + +\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 3580798..f1fbf89 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -8,7 +8,7 @@ .SH NAME clock \- Obtain and manipulate dates and times .SH "SYNOPSIS" -package require \fBTcl 8.5\fR +package require \fBTcl 8.5-\fR .sp \fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? .sp @@ -87,12 +87,20 @@ slowing its clock by a tiny fraction for some minutes until it is back in sync with UTC; its data model does not represent minutes that have 59 or 61 seconds. .TP +\fI\-now\fR +Instead of \fItimeVal\fR a non-integer option \fI\-now\fR can be used as +replacement for today, which is simply interpolated to the runt-time as value +of \fBclock seconds\fR. For example: +.sp +\fBclock format -now -f %a; # current day of the week\fR +.sp +\fBclock add -now 1 month; # next month\fR +.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 +183,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 +220,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) @@ -389,8 +397,12 @@ preprocessed format string. In order of preference: If the string contains a \fB%s\fR format group, representing seconds from the epoch, that group is used to determine the date. .IP [2] -If the string contains a \fB%J\fR format group, representing -the Julian Day Number, that group is used to determine the date. +If the string contains a \fB%J\fR, \fB%EJ\fR or \fB%Ej\fR format groups, +representing the Calendar or Astronomical Julian Day Number, that groups +are used to determine the date. +Note, that in case of \fB%EJ\fR or \fB%Ej\fR format groups, representing +the Julian Date with time fraction, this groups may be used to determine +the date and time. .IP [3] If the string contains a complete set of format groups specifying century, year, month, and day of month; century, year, and day of year; @@ -541,6 +553,36 @@ abbreviation appropriate to the current locale, and uses it to fix whether \fB%Y\fR refers to years before or after Year 1 of the Common Era. .TP +\fB%Ej\fR +On output, produces a string of digits giving the Astronomical Julian Date or +Astronomical Julian Day Number (JDN/JD). In opposite to calendar julian day +\fB%J\fR, it starts the day at noon. +On input, accepts a string of digits (or floating point with the time fraction) +and interprets it as an Astronomical Julian Day Number (JDN/JD). +The Astronomical Julian Date is a count of the number of calendar days +that have elapsed since 1 January, 4713 BCE of the proleptic +Julian calendar, which contains also the time fraction (after floating point). +The epoch time of 1 January 1970 corresponds to Astronomical JDN 2440587.5. +This value corresponds the julian day used in sqlite-database, and is the same +as result of \fBselect julianday(:seconds, 'unixepoch')\fR. +.TP +\fB%EJ\fR +On output, produces a string of digits giving the Calendar Julian Date. +In opposite to julian day \fB%J\fR format group, it produces float number. +In opposite to astronomical julian day \fB%Ej\fR group, it starts at midnight. +On input, accepts a string of digits (or floating point with the time fraction) +and interprets it as a Calendar Julian Day Number. +The Calendar Julian Date is a count of the number of calendar days +that have elapsed since 1 January, 4713 BCE of the proleptic +Julian calendar, which contains also the time fraction (after floating point). +The epoch time of 1 January 1970 corresponds to Astronomical JDN 2440588. +.TP +\fB%Es\fR +This affects similar to \fB%s\fR, but in opposition to \fB%s\fR it parses +or formats local seconds (not the posix seconds). +Because \fB%s\fR has the same precedence as \fB%s\fR (uniquely determines +a point in time), it overrides all other input formats. +.TP \fB%Ex\fR On output, produces a locale-dependent representation of the date in the locale's alternative calendar. On input, matches @@ -590,7 +632,7 @@ On output, produces a three-digit number giving the day of the year (001-366). On input, accepts such a number. .TP \fB%J\fR -On output, produces a string of digits giving the Julian Day Number. +On output, produces a string of digits giving the calendar Julian Day Number. On input, accepts a string of digits and interprets it as a Julian Day Number. The Julian Day Number is a count of the number of calendar days that have elapsed since 1 January, 4713 BCE of the proleptic @@ -735,13 +777,15 @@ week number \fB%V\fR; programs should use \fB%G\fR for that purpose. On output, produces the current time zone, expressed in hours and minutes east (+hhmm) or west (\-hhmm) of Greenwich. On input, accepts a time zone specifier (see \fBTIME ZONES\fR below) that will be used to -determine the time zone. +determine the time zone (this token is optionally applicable on input, +so the value is not mandatory and can be missing in input). .TP \fB%Z\fR On output, produces the current time zone's name, possibly translated to the given locale. On input, accepts a time zone specifier (see \fBTIME ZONES\fR below) that will be used to determine the -time zone. This option should, in general, be used on input only when +time zone (token is also like \fB%z\fR optionally applicable on input). +This option should, in general, be used on input only when parsing RFC822 dates. Other uses are fraught with ambiguity; for instance, the string \fBBST\fR may represent British Summer Time or Brazilian Standard Time. It is recommended that date/time strings for @@ -887,33 +931,38 @@ 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" , 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" . Note that only these four formats are accepted. @@ -922,6 +971,7 @@ 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, @@ -941,6 +991,24 @@ used. Finally, a correction is applied so that the correct hour of the day is produced after allowing for daylight savings time differences and the correct date is given when going from the end of a long month to a short month. +.PP +The precedence of the applying of single tokens resp. which sequence will be +used by calculating of the time is complex, e. g. heavily dependent on the +precision of type of the token. +.sp +In example below the second date-string contains "next January", therefore +it results in next year but in January. And third date-string besides "January" +contains also additionally "Fri", so it results in the nearest Friday. +Thus both win before "385 days" resp. make it more precise, because of higher +precision of this token types. +.CS +% clock format [clock scan "5 years 18 months 385 days" -base 0 -gmt 1] -gmt 1 +Thu Jul 21 00:00:00 GMT 1977 +% clock format [clock scan "5 years 18 months 385 days next January" -base 0 -gmt 1] -gmt 1 +Sat Jan 21 00:00:00 GMT 1978 +% clock format [clock scan "5 years 18 months 385 days next January Fri" -base 0 -gmt 1] -gmt 1 +Fri Jan 27 00:00:00 GMT 1978 +.CE .SH "SEE ALSO" msgcat(n) .SH KEYWORDS diff --git a/doc/close.n b/doc/close.n index 5daf3e2..2066583 100644 --- a/doc/close.n +++ b/doc/close.n @@ -12,11 +12,12 @@ .SH NAME close \- Close an open channel .SH SYNOPSIS -\fBclose \fIchannelId\fR ?r(ead)|w(rite)? +\fBclose \fIchannelId\fR ?\fBr\fR(\fBead\fR)|\fBw\fR(\fBrite\fR)? .BE .SH DESCRIPTION .PP -Closes or half-closes the channel given by \fIchannelId\fR. +Closes or half-closes the channel given by \fIchannelId\fR. \fBchan close\fR +is another name for this command. .PP \fIChannelId\fR must be an identifier for an open channel such as a Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), @@ -49,16 +50,21 @@ 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 +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 +\fBTCL_FLUSH_NONBLOCKING_ON_EXIT\fR, which when set and not equal to +.QW \fB0\fR +restores the previous behavior. .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.) +pipeline created with \fBopen\fR returns an error (either by returning a +non-zero exit code or writing to its standard error file descriptor), +\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 +86,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 @@ -99,7 +104,7 @@ proc withOpenFile {filename channelVar script} { } .CE .SH "SEE ALSO" -file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3) +chan(n), file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3) .SH KEYWORDS blocking, channel, close, nonblocking, half-close '\" Local Variables: diff --git a/doc/configurable.n b/doc/configurable.n new file mode 100644 index 0000000..0102f8c --- /dev/null +++ b/doc/configurable.n @@ -0,0 +1,333 @@ +'\" +'\" Copyright © 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 configurable n 0.4 TclOO "TclOO Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +oo::configurable, configure, property \- class that makes configurable classes and objects, and supports making configurable properties +.SH SYNOPSIS +.nf +package require TclOO + +\fBoo::configurable create \fIclass\fR ?\fIdefinitionScript\fR? + +\fBoo::define \fIclass\fB {\fR + \fBproperty \fIpropName\fR ?\fIoptions...\fR? ?\fIpropName\fR ?\fIoptions...\fR?...? +\fB}\fR + +\fBoo::objdefine \fIobject\fB {\fR + \fBproperty \fIpropName\fR ?\fIoptions...\fR? ?\fIpropName\fR ?\fIoptions...\fR?...? +\fB}\fR + +\fIobjectName \fBconfigure\fR +\fIobjectName \fBconfigure\fR \fI\-prop\fR +\fIobjectName \fBconfigure\fR \fI\-prop value\fR ?\fI\-prop value\fR... +.fi +.SH "CLASS HIERARCHY" +.nf +\fBoo::object\fR + \(-> \fBoo::class\fR + \(-> \fBoo::configurable\fR + +\fBoo::object\fR + \(-> \fBoo::class\fR + \(-> \fBoo::configurablesupport::configurable\fR +.fi +.BE +.SH DESCRIPTION +.PP +Configurable objects are objects that support being configured with a +\fBconfigure\fR method. Each of the configurable entities of the object is +known as a property of the object. Properties may be defined on classes or +instances; when configuring an object, any of the properties defined by its +classes (direct or indirect) or by the instance itself may be configured. +.PP +The \fBoo::configurable\fR metaclass installs basic support for making +configurable objects into a class. This consists of making a \fBproperty\fR +definition command available in definition scripts for the class and instances +(e.g., from the class's constructor, within \fBoo::define\fR and within +\fBoo::objdefine\fR) and making a \fBconfigure\fR method available within the +instances. +.SS "CONFIGURE METHOD" +.PP +The behavior of the \fBconfigure\fR method is modelled after the +\fBfconfigure\fR/\fBchan configure\fR command. +.PP +If passed no additional arguments, the \fBconfigure\fR method returns an +alphabetically sorted dictionary of all \fIreadable\fR and \fIread-write\fR +properties and their current values. +.PP +If passed a single additional argument, that argument to the \fBconfigure\fR +method must be the name of a property to read (or an unambiguous prefix +thereof); its value is returned. +.PP +Otherwise, if passed an even number of arguments then each pair of arguments +specifies a property name (or an unambiguous prefix thereof) and the value to +set it to. The properties will be set in the order specified, including +duplicates. If the setting of any property fails, the overall \fBconfigure\fR +method fails, the preceding pairs (if any) will continue to have been applied, +and the succeeding pairs (if any) will be not applied. On success, the result +of the \fBconfigure\fR method in this mode operation will be an empty string. +.SS "PROPERTY DEFINITIONS" +.PP +When a class has been manufactured by the \fBoo::configurable\fR metaclass (or +one of its subclasses), it gains an extra definition, \fBproperty\fR. The +\fBproperty\fR definition defines one or more properties that will be exposed +by the class's instances. +.PP +The \fBproperty\fR command takes the name of a property to define first, +\fIwithout a leading hyphen\fR, followed by a number of option-value pairs +that modify the basic behavior of the property. This can then be followed by +an arbitrary number of other property definitions. The supported options are: +.TP +\fB\-get \fIgetterScript\fR +. +This defines the implementation of how to read from the property; the +\fIgetterScript\fR will become the body of a method (taking no arguments) +defined on the class, if the kind of the property is such that the property +can be read from. The method will be named +\fB<ReadProp-\fIpropertyName\fB>\fR, and will default to being a simple read +of the instance variable with the same name as the property (e.g., +.QW "\fBproperty\fR xyz" +will result in a method +.QW <ReadProp-xyz> +being created). +.TP +\fB\-kind \fIpropertyKind\fR +. +This defines what sort of property is being created. The \fIpropertyKind\fR +must be exactly one of \fBreadable\fR, \fBwritable\fR, or \fBreadwrite\fR +(which is the default) which will make the property read-only, write-only or +read-write, respectively. Read-only properties can only ever be read from, +write-only properties can only ever be written to, and read-write properties +can be both read and written. +.RS +.PP +Note that write-only properties are not particularly discoverable as they are +never reported by the \fBconfigure\fR method other than by error messages when +attempting to write to a property that does not exist. +.RE +.TP +\fB\-set \fIsetterScript\fR +. +This defines the implementation of how to write to the property; the +\fIsetterScript\fR will become the body of a method taking a single argument, +\fIvalue\fR, defined on the class, if the kind of the property is such that +the property can be written to. The method will be named +\fB<WriteProp-\fIpropertyName\fB>\fR, and will default to being a simple write +of the instance variable with the same name as the property (e.g., +.QW "\fBproperty\fR xyz" +will result in a method +.QW <WriteProp-xyz> +being created). +.PP +Instances of the class that was created by \fBoo::configurable\fR will also +support \fBproperty\fR definitions; the semantics will be exactly as above +except that the properties will be defined on the instance alone. +.PP +Note that the property implementation methods that \fBproperty\fR defines +should not be private, as this makes them inaccessible from the implementation +of \fBconfigure\fR (by design; the property configuration mechanism is +intended for use mainly from outside a class, whereas a class may access +variables directly). The variables accessed by the default implementations of +the properties \fImay\fR be private, if so declared. +.SH "ADVANCED USAGE" +.PP +The configurable class system is comprised of several pieces. The +\fBoo::configurable\fR metaclass works by mixing in a class and setting +definition namespaces during object creation that provide the other bits and +pieces of machinery. The key pieces of the implementation are enumerated here +so that they can be used by other code: +.TP +\fBoo::configuresupport::configurable\fR +. +This is a class that provides the implementation of the \fBconfigure\fR method +(described above in \fBCONFIGURE METHOD\fR). +.TP +\fBoo::configuresupport::configurableclass\fR +. +This is a namespace that contains the definition dialect that provides the +\fBproperty\fR declaration for use in classes (i.e., via \fBoo::define\fR, and +class constructors under normal circumstances), as described above in +\fBPROPERTY DEFINITIONS\fR. It \fBnamespace export\fRs its \fBproperty\fR +command so that it may be used easily in user definition dialects. +.TP +\fBoo::configuresupport::configurableobject\fR +. +This is a namespace that contains the definition dialect that provides the +\fBproperty\fR declaration for use in instance objects (i.e., via +\fBoo::objdefine\fR, and the \fBself\fR declaration in \fBoo::define\fR), as +described above in \fBPROPERTY DEFINITIONS\fR. It \fBnamespace export\fRs its +\fBproperty\fR command so that it may be used easily in user definition +dialects. +.PP +The underlying property discovery mechanism relies on four slots (see +\fBoo::define\fR for what that implies) that list the properties that can be +configured. These slots do not themselves impose any semantics on what the +slots mean other than that they have unique names, no important order, can be +inherited and discovered on classes and instances. +.PP +These slots, and their intended semantics, are: +.TP +\fBoo::configuresupport::readableproperties\fR +. +The set of properties of a class (not including those from its superclasses) +that may be read from when configuring an instance of the class. This slot can +also be read with the \fBinfo class properties\fR command. +.TP +\fBoo::configuresupport::writableproperties\fR +. +The set of properties of a class (not including those from its superclasses) +that may be written to when configuring an instance of the class. This slot +can also be read with the \fBinfo class properties\fR command. +.TP +\fBoo::configuresupport::objreadableproperties\fR +. +The set of properties of an object instance (not including those from its +classes) that may be read from when configuring the object. This slot can +also be read with the \fBinfo object properties\fR command. +.TP +\fBoo::configuresupport::objwritableproperties\fR +. +The set of properties of an object instance (not including those from its +classes) that may be written to when configuring the object. This slot can +also be read with the \fBinfo object properties\fR command. +.PP +Note that though these are slots, they are \fInot\fR in the standard +\fBoo::define\fR or \fBoo::objdefine\fR namespaces; in order to use them +inside a definition script, they need to be referred to by full name. This is +because they are intended to be building bricks of configurable property +system, and not directly used by normal user code. +.SS "IMPLEMENTATION NOTE" +.PP +The implementation of the \fBconfigure\fR method uses +\fBinfo object properties\fR with the \fB\-all\fR option to discover what +properties it may manipulate. +.SH EXAMPLES +.PP +Here we create a simple configurable class and demonstrate how it can be +configured: +.PP +.CS +\fBoo::configurable\fR create Point { + \fBproperty\fR x y + constructor args { + my \fBconfigure\fR -x 0 -y 0 {*}$args + } + variable x y + method print {} { + puts "x=$x, y=$y" + } +} + +set pt [Point new -x 27] +$pt print; \fI# x=27, y=0\fR +$pt \fBconfigure\fR -y 42 +$pt print; \fI# x=27, y=42\fR +puts "distance from origin: [expr { + hypot([$pt \fBconfigure\fR -x], [$pt \fBconfigure\fR -y]) +}]"; \fI# distance from origin: 49.92995093127971\fR +puts [$pt \fBconfigure\fR] + \fI# -x 27 -y 42\fR +.CE +.PP +Such a configurable class can be extended by subclassing, though the subclass +needs to also be created by \fBoo::configurable\fR if it will use the +\fBproperty\fR definition: +.PP +.CS +\fBoo::configurable\fR create Point3D { + superclass Point + \fBproperty\fR z + constructor args { + next -z 0 {*}$args + } +} + +set pt2 [Point3D new -x 2 -y 3 -z 4] +puts [$pt2 \fBconfigure\fR] + \fI# -x 2 -y 3 -z 4\fR +.CE +.PP +Once you have a configurable class, you can also add instance properties to +it. (The backing variables for all properties start unset.) Note below that we +are using an unambiguous prefix of a property name when setting it; this is +supported for all properties though full names are normally recommended +because subclasses will not make an unambiguous prefix become ambiguous in +that case. +.PP +.CS +oo::objdefine $pt { + \fBproperty\fR color +} +$pt \fBconfigure\fR -c bisque +puts [$pt \fBconfigure\fR] + \fI# -color bisque -x 27 -y 42\fR +.CE +.PP +You can also do derived properties by making them read-only and supplying a +script that computes them. +.PP +.CS +\fBoo::configurable\fR create PointMk2 { + \fBproperty\fR x y + \fBproperty\fR distance -kind readable -get { + return [expr {hypot($x, $y)}] + } + variable x y + constructor args { + my \fBconfigure\fR -x 0 -y 0 {*}$args + } +} + +set pt3 [PointMk2 new -x 3 -y 4] +puts [$pt3 \fBconfigure\fR -distance] + \fI# 5.0\fR +$pt3 \fBconfigure\fR -distance 10 + \fI# ERROR: bad property "-distance": must be -x or -y\fR +.CE +.PP +Setters are used to validate the type of a property: +.PP +.CS +\fBoo::configurable\fR create PointMk3 { + \fBproperty\fR x -set { + if {![string is double -strict $value]} { + error "-x property must be a number" + } + set x $value + } + \fBproperty\fR y -set { + if {![string is double -strict $value]} { + error "-y property must be a number" + } + set y $value + } + variable x y + constructor args { + my \fBconfigure\fR -x 0 -y 0 {*}$args + } +} + +set pt4 [PointMk3 new] +puts [$pt4 \fBconfigure\fR] + \fI# -x 0 -y 0\fR +$pt4 \fBconfigure\fR -x 3 -y 4 +puts [$pt4 \fBconfigure\fR] + \fI# -x 3 -y 4\fR +$pt4 \fBconfigure\fR -x "obviously not a number" + \fI# ERROR: -x property must be a number\fR +.CE +.SH "SEE ALSO" +info(n), oo::class(n), oo::define(n) +.SH KEYWORDS +class, object, properties, configuration +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: 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..7d2f46b --- /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-lang.org/] +.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-lang.org/] +.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: @@ -12,7 +12,7 @@ oo::copy \- create copies of objects and classes .SH SYNOPSIS .nf -package require TclOO +package require tcl::oo \fBoo::copy\fI sourceObject \fR?\fItargetObject\fR? ?\fItargetNamespace\fR? .fi diff --git a/doc/coroutine.n b/doc/coroutine.n index 52775ef..8110628 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,54 @@ 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 coroutines that are suspended. (If a +coroutine is running then any introspection code would be merely inspecting +the state of where it is currently running; \fBcoroinject\fR/\fBcoroprobe\fR +are unnecessary in that case.) +.VE "8.7, TIP383" .SH EXAMPLES .PP This example shows a coroutine that will produce an infinite sequence of @@ -138,7 +187,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 +198,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..c1c3049 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. @@ -12,7 +12,7 @@ oo::define, oo::objdefine \- define and configure classes and objects .SH SYNOPSIS .nf -package require TclOO +package require tcl::oo \fBoo::define\fI class defScript\fR \fBoo::define\fI class subcommand arg\fR ?\fIarg ...\fR? @@ -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,120 @@ 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\-appendifnew\fR ?\fImember ...\fR? +.VS TIP558 +This appends the given \fImember\fR elements to the slot definition if they +do not already exist. +.VE TIP558 .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 +527,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 +583,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 +647,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; diff --git a/doc/encoding.n b/doc/encoding.n index e78a8e7..c881d26 100644 --- a/doc/encoding.n +++ b/doc/encoding.n @@ -8,90 +8,199 @@ .so man.macros .BS .SH NAME -encoding \- Manipulate encodings +encoding \- Work with encodings .SH SYNOPSIS -\fBencoding \fIoption\fR ?\fIarg arg ...\fR? +\fBencoding \fIoperation\fR ?\fIarg arg ...\fR? .BE .SH INTRODUCTION .PP -Strings in Tcl are logically a sequence of 16-bit Unicode characters. -These strings are represented in memory as a sequence of bytes that -may be in one of several encodings: modified UTF\-8 (which uses 1 to 3 -bytes per character), 16-bit -.QW Unicode -(which uses 2 bytes per character, with an endianness that is -dependent on the host architecture), and binary (which uses a single -byte per character but only handles a restricted range of characters). -Tcl does not guarantee to always use the same encoding for the same -string. -.PP -Different operating system interfaces or applications may generate -strings in other encodings such as Shift\-JIS. The \fBencoding\fR -command helps to bridge the gap between Unicode and these other -formats. +In Tcl every string is composed of Unicode values. Text may be encoded into an +encoding such as cp1252, iso8859-1, Shitf\-JIS, utf-8, utf-16, etc. Not every +Unicode vealue is encodable in every encoding, and some encodings can encode +values that are not available in Unicode. +.PP +Even though Unicode is for encoding the written texts of human languages, any +sequence of bytes can be encoded as the first 255 Unicode values. iso8859-1 an +encoding for a subset of Unicode in which each byte is a Unicode value of 255 +or less. Thus, any sequence of bytes can be considered to be a Unicode string +encoded in iso8859-1. To work with binary data in Tcl, decode it from +iso8859-1 when reading it in, and encode it into iso8859-1 when writing it out, +ensuring that each character in the string has a value of 255 or less. +Decoding such a string does nothing, and encoding encoding such a string also +does nothing. +.PP +For example, the following is true: +.CS +set text {In Tcl binary data is treated as Unicode text and it just works.} +set encoded [encoding convertto iso8859-1 $text] +expr {$text eq $encoded}; #-> 1 +.CE +The following is also true: +.CS +set decoded [encoding convertfrom iso8859-1 $text] +expr {$text eq $decoded}; #-> 1 +.CE .SH DESCRIPTION .PP -Performs one of several encoding related operations, depending on -\fIoption\fR. The legal \fIoption\fRs are: +Performs one of the following encoding \fIoperations\fR: .TP \fBencoding convertfrom\fR ?\fIencoding\fR? \fIdata\fR +.TP +\fBencoding convertfrom\fR ?\fB-profile \fIprofile\fR? ?\fB-failindex var\fR? \fIencoding\fR \fIdata\fR . -Convert \fIdata\fR to Unicode from the specified \fIencoding\fR. The -characters in \fIdata\fR are treated as binary data where the lower -8-bits of each character is taken as a single byte. The resulting -sequence of bytes is treated as a string in the specified -\fIencoding\fR. If \fIencoding\fR is not specified, the current -system encoding is used. +Decodes \fIdata\fR encoded in \fIencoding\fR. If \fIencoding\fR is not +specified the current system encoding is used. + +.VS "TCL8.7 TIP607, TIP656" +\fB-profile\fR determines how invalid data for the encoding are handled. See +the \fBPROFILES\fR section below for details. Returns an error if decoding +fails. However, if \fB-failindex\fR given, returns the result of the +conversion up to the point of termination, and stores in \fBvar\fR the index of +the character that could not be converted. If no errors are encountered the +entire result of the conversion is returned and the value \fB-1\fR is stored in +\fBvar\fR. +.VE "TCL8.7 TIP607, TIP656" .TP -\fBencoding convertto\fR ?\fIencoding\fR? \fIstring\fR +\fBencoding convertto\fR ?\fIencoding\fR? \fIdata\fR +.TP +\fBencoding convertto\fR ?\fB-profile \fIprofile\fR? ?\fB-failindex var\fR? \fIencoding\fR \fIdata\fR . -Convert \fIstring\fR from Unicode to the specified \fIencoding\fR. -The result is a sequence of bytes that represents the converted -string. Each byte is stored in the lower 8-bits of a Unicode -character (indeed, the resulting string is a binary string as far as -Tcl is concerned, at least initially). If \fIencoding\fR is not -specified, the current system encoding is used. +Converts \fIstring\fR to \fIencoding\fR. If \fIencoding\fR is not given, the +current system encoding is used. + +.VS "TCL8.7 TIP607, TIP656" +See \fBencoding convertfrom\fR for the meaning of \fB-profile\fR and \fB-failindex\fR. +.VE "TCL8.7 TIP607, TIP656" .TP \fBencoding dirs\fR ?\fIdirectoryList\fR? . -Tcl can load encoding data files from the file system that describe -additional encodings for it to work with. This command sets the search -path for \fB*.enc\fR encoding data files to the list of directories -\fIdirectoryList\fR. If \fIdirectoryList\fR is omitted then the -command returns the current list of directories that make up the -search path. It is an error for \fIdirectoryList\fR to not be a valid -list. If, when a search for an encoding data file is happening, an -element in \fIdirectoryList\fR does not refer to a readable, -searchable directory, that element is ignored. +Sets the search path for \fB*.enc\fR encoding data files to the list of +directories given by \fIdirectoryList\fR. If \fIdirectoryList\fR is not given, +returns the current list of directories that make up the search path. It is +not an error for an item in \fIdirectoryList\fR to not refer to a readable, +searchable directory. .TP \fBencoding names\fR . -Returns a list containing the names of all of the encodings that are -currently available. +Returns a list of the names of available encodings. The encodings .QW utf-8 and .QW iso8859-1 are guaranteed to be present in the list. +.VS "TCL8.7 TIP656" +.TP +\fBencoding profiles\fR +Returns a list of names of available encoding profiles. See \fBPROFILES\fR +below. +.VE "TCL8.7 TIP656" .TP \fBencoding system\fR ?\fIencoding\fR? . -Set the system encoding to \fIencoding\fR. If \fIencoding\fR is -omitted then the command returns the current system encoding. The -system encoding is used whenever Tcl passes strings to system calls. -.SH EXAMPLE +Sets the system encoding to \fIencoding\fR. If \fIencoding\fR is not given, +returns the current system encoding. The system encoding is used to pass +strings to system calls. +.\" Do not put .VS on whole section as that messes up the bullet list alignment +.SH PROFILES .PP -The following example converts a byte sequence in Japanese euc-jp encoding to a TCL string: +.VS "TCL8.7 TIP656" +Each \fIprofile\fR is a distinct strategy for dealing with invalid data for an +encoding. +.PP +The following profiles are currently implemented. +.VS "TCL8.7 TIP656" +.TP +\fBtcl8\fR +. +The default profile. Provides for behaviour identical to that of Tcl 8.6: When +decoding, for encodings \fBother than utf-8\fR, each invalid byte is interpreted +as the Unicode value given by that one byte. For example, the byte 0x80, which +is invalid in the ASCII encoding would be mapped to the Unicode value U+0080. +For \fButf-8\fR, each invalid byte that is a valid CP1252 character is +interpreted as the Unicode value for that character, while each byte that is +not is treated as the Unicode value given by that one byte. For example, byte +0x80 is defined by CP1252 and is therefore mapped to its Unicode equivalent +U+20AC while byte 0x81 which is not defined by CP1252 is mapped to U+0081. As +an additional special case, the sequence 0xC0 0x80 is mapped to U+0000. + +When encoding, each character that cannot be represented in the encoding is +replaced by an encoding-dependent character, usually the question mark \fB?\fR. +.TP +\fBstrict\fR +. +The operation fails when invalid data for the encoding are encountered. +.TP +\fBreplace\fR +. +When decoding, invalid bytes are replaced by U+FFFD, the Unicode REPLACEMENT +CHARACTER. + +When encoding, Unicode values that cannot be represented in the target encoding +are transformed to an encoding-specific fallback character, U+FFFD REPLACEMENT +CHARACTER for UTF targets, and generally `?` for other encodings. +.VE "TCL8.7 TIP656" +.SH EXAMPLES +.PP +These examples use the utility proc below that prints the Unicode value for +each character in a string. .PP .CS -set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"] +proc codepoints s {join [lmap c [split $s {}] { + string cat U+ [format %.6X [scan $c %c]]}] +} .CE .PP -The result is the unicode codepoint: +Example 1: Convert from euc-jp: +.PP +.CS +% codepoints [\fBencoding convertfrom\fR euc-jp \exA4\exCF] +U+00306F +.CE +.PP +The result is the Unicode value .QW "\eu306F" , which is the Hiragana letter HA. +.VS "TCL8.7 TIP607, TIP656" +.PP +Example 2: Error handling based on profiles: +.PP +The letter \fBA\fR is Unicode character U+0041 and the byte "\ex80" is invalid +in ASCII encoding. +.PP +.CS +% codepoints [encoding convertfrom -profile tcl8 ascii A\ex80] +U+000041 U+000080 +% codepoints [encoding convertfrom -profile replace ascii A\ex80] +U+000041 U+00FFFD +% codepoints [encoding convertfrom -profile strict ascii A\ex80] +unexpected byte sequence starting at index 1: '\ex80' +.CE +.PP +Example 3: Get partial data and the error location: +.PP +.CS +% codepoints [encoding convertfrom -profile strict -failindex idx ascii AB\ex80] +U+000041 U+000042 +% set idx +2 +.CE +.PP +Example 4: Encode a character that is not representable in ISO8859-1: +.PP +.CS +% encoding convertto iso8859-1 A\eu0141 +A? +% encoding convertto -profile strict iso8859-1 A\eu0141 +unexpected character at index 1: 'U+000141' +% encoding convertto -profile strict -failindex idx iso8859-1 A\eu0141 +A +% set idx +1 +.CE +.VE "TCL8.7 TIP607, TIP656" +.PP .SH "SEE ALSO" -Tcl_GetEncoding(3) +Tcl_GetEncoding(3), fconfigure(n) .SH KEYWORDS encoding, unicode .\" Local Variables: @@ -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: @@ -23,7 +23,14 @@ fashion as the \fBconcat\fR command, passes the concatenated string to the Tcl interpreter recursively, and returns the result of that evaluation (or any error generated by it). Note that the \fBlist\fR command quotes sequences of words in such a -way that they are not further expanded by the \fBeval\fR command. +way that they are not further expanded by the \fBeval\fR command; +for \fIany\fR values, $a, $b, and $c, these two lines are effectively +equivalent: +.PP +.CS +\fBeval\fR [list $a $b $c] +$a $b $c +.CE .SH EXAMPLES .PP Often, it is useful to store a fragment of a script in a variable and @@ -74,6 +81,12 @@ However, the last line would now normally be written without .CS set var [linsert $var 0 {*}$args] .CE +.PP +or indeed like this: +.PP +.CS +set var [list {*}$args {*}$var] +.CE .SH "SEE ALSO" catch(n), concat(n), error(n), errorCode(n), errorInfo(n), interp(n), list(n), namespace(n), subst(n), uplevel(n) @@ -262,14 +262,6 @@ insertion of backslash characters. .PP The automatic resolving of environment variables using "\fB%var%\fR" is critical, but has more use than danger and is not escaped. -.PP -TCL 8.6.10 refined this quoting by adding quoting for data quotes and individual -quoting of "\fB%\fR". -This may break present scripts which rely on the replacement functionality of -environment variables. -Thus, the individual quoting of "\fB%\fR" was removed in TCL 8.6.14, as environment -variables are seen more helpful than a problem. -A solution with command parameters is envisaged for a future release of TCL. .RE .PP The Tk console text widget does not provide real standard IO capabilities. @@ -369,7 +361,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 @@ -383,7 +374,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 +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,117 +32,150 @@ 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 the result of expression is an integer, it is in decimal form, and when +the result is a floating-point number, it is in the form produced by the +\fB%g\fR format specifier of \fBformat\fR. +.PP +.VS "TIP 582" +At any point in the expression except within double quotes or braces, \fB#\fR +is the beginning of a comment, which lasts to the end of the line or +the end of the expression, whichever comes first. +.VE "TIP 582" .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: -.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 +An expression consists of a combination of operands, operators, parentheses and +commas, possibly with whitespace between any of these elements, which is +ignored. Each operand is interpreted as a numeric value if at all possible. +.PP +Each operand has one of the following forms: +.RS +.PP +.TP +A \fBnumeric value\fR +.PP +.RS +. +Either integer or floating-point. The first two characters of an integer may +also be \fB0d\fR for decimal, \fB0b\fR for binary, \fB0o\fR for octal or +\fB0x\fR for hexadicimal. For compatibility with older Tcl releases, an +operand that begins with \fB0\fR is interpreted as an octal integer even if the +second character is not \fBo\fR. +.PP +A floating-point number may be take 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 +Digits in any numeric value may be separated with one or more underscore +characters, "\fB_\fR". A separator may only +appear between digits, 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 +\fBexpr\fR 3_141_592_653_589e-1_2 \fI3.141592653589\fR +.CE +.RE + +.TP +A \fBboolean value\fR +. +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. -.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 -.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. -.IP [6] -As a Tcl command enclosed in brackets. -The command will be executed and its result will be used as -the operand. -.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 +.TP +A \fBvariable\fR +. +Using standard \fB$\fR notation. +The value of the variable is the value of the operand. +.TP +A string enclosed in \fBdouble-quotes\fR +. +Backslash, variable, and command substitution are performed according to the +rules for \fBTcl\fR. +.TP +A string enclosed in \fBbraces\fR. +The operand is treated as a braced value according to the rule for braces in +\fBTcl\fR. +.TP +A Tcl command enclosed in \fBbrackets\fR +. +Command substitution is performed as according to the command substitution rule +for \fBTcl\fR. +.TP +A mathematical function such as \fBsin($x)\fR, whose arguments have any of the above +forms for operands. See \fBMATH FUNCTIONS\fR below for a discussion of how mathematical functions are handled. +.RE .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 \fBexpr\fR {3.1 + $a} \fI6.1\fR \fBexpr\fR {2 + "$a.$b"} \fI5.6\fR -\fBexpr\fR {4*[llength "6 2"]} \fI8\fR +\fBexpr\fR {4*[llength {6 2}]} \fI8\fR \fBexpr\fR {{word one} < "word $a"} \fI0\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 +185,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 +367,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 +403,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 +430,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,12 +490,14 @@ 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 { + # Does the environment variable exist, and... [info exists ::env(SOME_ENV_VAR)] && + # ...does it contain a proper true value? [string is true -strict $::env(SOME_ENV_VAR)] }] .CE @@ -487,7 +511,7 @@ 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 \(co 1993 The Regents of the University of California. 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: diff --git a/doc/fconfigure.n b/doc/fconfigure.n index 2926777..3de22eb 100644 --- a/doc/fconfigure.n +++ b/doc/fconfigure.n @@ -103,7 +103,7 @@ system, as returned by \fBencoding system\fR. .TP \fB\-eofchar\fR \fIchar\fR .TP -\fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR +\fB\-eofchar\fR \fB{\fIchar outChar\fB}\fR . This option supports DOS file systems that use Control-z (\ex1A) as an end of file marker. If \fIchar\fR is not an empty string, then this @@ -113,8 +113,8 @@ If \fIchar\fR is the empty string, then there is no special end of file character marker. For read-write channels, a two-element list specifies the end of file marker for input and output, respectively. As a convenience, when setting the end-of-file character for a read-write -channel you can specify a single value that will apply to both reading -and writing. When querying the end-of-file character of a read-write +channel you can specify a single value that will apply to reading +only. When querying the end-of-file character of a read-write channel, a two-element list will always be returned. The default value for \fB\-eofchar\fR is the empty string in all cases except for files under Windows. In that case the \fB\-eofchar\fR is Control-z (\ex1A) for @@ -122,6 +122,16 @@ reading and the empty string for writing. The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7F; attempting to set \fB\-eofchar\fR to a value outside of this range will generate an error. +.VS "TCL8.7 TIP656" +.TP +\fB\-profile\fR \fIprofile\fR +. +Specifies the encoding profile to be used on the channel. The encoding +transforms in use for the channel's input and output will then be subject to the +rules of that profile. Any failures will result in a channel error. See +\fBPROFILES\fR in the \fBencoding(n)\fR documentation for details about encoding +profiles. +.VE "TCL8.7 TIP656" .TP \fB\-translation\fR \fImode\fR .TP @@ -278,11 +288,11 @@ set data [read $f $numDataBytes] close $f .CE .SH "SEE ALSO" -close(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n), +close(n), encoding(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n), Tcl_StandardChannels(3) .SH KEYWORDS blocking, buffering, carriage return, end of line, flushing, linemode, -newline, nonblocking, platform, translation, encoding, filter, byte array, +newline, nonblocking, platform, profile, translation, encoding, filter, byte array, binary '\" Local Variables: '\" mode: nroff diff --git a/doc/fcopy.n b/doc/fcopy.n index d39c803..dc6d8ea 100644 --- a/doc/fcopy.n +++ b/doc/fcopy.n @@ -12,7 +12,7 @@ .SH NAME fcopy \- Copy data from one channel to another .SH SYNOPSIS -\fBfcopy \fIinchan\fR \fIoutchan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? +\fBfcopy \fIinputChan\fR \fIoutputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? .BE .SH DESCRIPTION @@ -20,21 +20,29 @@ fcopy \- Copy data from one channel to another The \fBfcopy\fR command copies data from one I/O channel, \fIinchan\fR to another I/O channel, \fIoutchan\fR. The \fBfcopy\fR command leverages the buffering in the Tcl I/O system to avoid extra copies and to avoid buffering too much data in -main memory when copying large files to slow destinations like +main memory when copying large files to destinations like network sockets. -.PP -The \fBfcopy\fR -command transfers data from \fIinchan\fR until end of file -or \fIsize\fR bytes or characters have been -transferred; \fIsize\fR is in bytes if the two channels are using the -same encoding, and is in characters otherwise. -If no \fB\-size\fR argument is given, -then the copy goes until end of file. -All the data read from \fIinchan\fR is copied to \fIoutchan\fR. +. +.SS "DATA QUANTITY" +All data until \fIEOF\fR is copied. +In addition, the quantity of copied data may be specified by the option \fB-size\fR. +The given size is in bytes, if the input channel is in binary mode. +Otherwise, it is in characters. +.PP +The transfer is treated as a binary transfer, if the encoding +profile is set to +.QW tcl8 +and the input encoding matches the output encoding. +In this case, eventual encoding errors are not handled. +An eventually given size is in bytes in this case. +This feature is depreciated in TCL 9. +. +.SS "BLOCKING OPERATION MODE" Without the \fB\-command\fR option, \fBfcopy\fR blocks until the copy is complete and returns the number of bytes or characters (using the same rules as for the \fB\-size\fR option) written to \fIoutchan\fR. -.PP +. +.SS "BACKGROUND OPERATION MODE" The \fB\-command\fR argument makes \fBfcopy\fR work in the background. In this case it returns immediately and the \fIcallback\fR is invoked later when the copy completes. @@ -66,7 +74,8 @@ copy so those handlers do not interfere with the copy. Any wrong-sided I/O attempted (by a \fBfileevent\fR handler or otherwise) will get a .QW "channel busy" error. -.PP +. +.SS "CHANNEL TRANSLATION OPTIONS" \fBFcopy\fR translates end-of-line sequences in \fIinchan\fR and \fIoutchan\fR according to the \fB\-translation\fR option for these channels. @@ -77,13 +86,13 @@ can be different than the number of bytes written to \fIoutchan\fR. Only the number of bytes written to \fIoutchan\fR is reported, either as the return value of a synchronous \fBfcopy\fR or as the argument to the callback for an asynchronous \fBfcopy\fR. -.PP -\fBFcopy\fR obeys the encodings and character translations configured +.SS "CHANNEL ENCODING OPTIONS" +\fBFcopy\fR obeys the encodings, profiles and character translations configured for the channels. This means that the incoming characters are converted internally first UTF-8 and then into the encoding of the channel \fBfcopy\fR writes to. See the manual entry for \fBfconfigure\fR for details on the -\fB\-encoding\fR and \fB\-translation\fR options. No conversion is +\fB\-encoding\fR and \fB\-profile\fR options. No conversion is done if both channels are set to encoding .QW binary @@ -96,6 +105,21 @@ the system will assume that the incoming bytes are valid UTF-8 characters and convert them according to the output encoding. The behaviour of the system for bytes which are not valid UTF-8 characters is undefined in this case. +.PP +\fBFcopy\fR may throw encoding errors (error code \fBEILSEQ\fR), if input or output +channel is configured to the +.QW strict +encoding profile. +.PP +If an encoding error arises on the input channel, any data before the error byte is +written to the output channel. The input file pointer is located just before the +values causing the encoding error. +Error inspection or recovery is possible by changing the encoding parameters and +invoking a file command (\fBread\fR, \fBfcopy\fR). +.PP +If an encoding error arises on the output channel, the errorneous data is lost. +To make the difference between the input error case and the output error case, only the +error message may be inspected (read or write), as both throw the error code \fIEILSEQ\fR. .SH EXAMPLES .PP The first example transfers the contents of one channel exactly to @@ -31,6 +31,8 @@ for the file. The time is measured in the standard POSIX fashion as seconds from a fixed starting time (often January 1, 1970). If the file does not exist or its access time cannot be queried or set then an error is generated. On Windows, FAT file systems do not support access time. +On \fBzipfs\fR file systems, access time is mapped to the modification +time. .TP \fBfile attributes \fIname\fR .TP @@ -83,6 +85,19 @@ clears the readonly attribute of the file. \fB\-rsrclength\fR gives the length of the resource fork of the file, this attribute can only be set to the value 0, which results in the resource fork being stripped off the file. +.PP +On all platforms, files in \fBzipfs\fR mounted archives return the following +attributes. These are all read-only and cannot be directly set. +\fB-archive\fR gives the path of the mounted ZIP archive containing the file. +\fB-compsize\fR gives the compressed size of the file within the archive. +This is \fB0\fR for directories. +\fB-crc\fR gives the CRC of the file if present, else \fB0\fR. +\fB-mount\fR gives the path where the containing archive is mounted. +\fB-offset\fR gives the offset of the file within the archive. +\fB-uncompsize\fR gives the uncompressed size of the file. +This is \fB0\fR for directories. +Other attributes may be present in the returned list. These should +be ignored. .RE .TP \fBfile channels\fR ?\fIpattern\fR? @@ -182,6 +197,24 @@ Returns all of the characters in \fIname\fR after and including the last dot in the last element of \fIname\fR. If there is no dot in the last element of \fIname\fR then returns the empty string. .TP +\fBfile home ?\fIusername\fR? +.VS "8.7, TIP 602" +If no argument is specified, the command returns the home directory +of the current user. This is generally the value of the \fB$HOME\fR +environment variable except that on Windows platforms backslashes +in the path are replaced by forward slashes. An error is raised if +the \fB$HOME\fR environment variable is not set. +.RS +.PP +If \fIusername\fR is specified, the command returns the home directory +configured in the system for the specified user. Note this may be +different than the value of the \fB$HOME\fR environment variable +even when \fIusername\fR corresponds to the current user. An error is +raised if the \fIusername\fR does not correspond to a user account +on the system. +.RE +.VE "8.7, TIP 602" +.TP \fBfile isdirectory \fIname\fR . Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise. @@ -253,14 +286,14 @@ symbolic and hard links (the latter for files only). Windows supports symbolic directory links and hard file links on NTFS drives. .RE .TP -\fBfile lstat \fIname varName\fR +\fBfile lstat \fIname ?varName?\fR . Same as \fBstat\fR option (see below) except uses the \fIlstat\fR kernel call instead of \fIstat\fR. This means that if \fIname\fR -refers to a symbolic link the information returned in \fIvarName\fR -is for the link rather than the file it refers to. On systems that -do not support symbolic links this option behaves exactly the same -as the \fBstat\fR option. +refers to a symbolic link the information returned is for the link +rather than the file it refers to. On systems that do not support +symbolic links this option behaves exactly the same as the +\fBstat\fR option. .TP \fBfile mkdir\fR ?\fIdir\fR ...? . @@ -279,6 +312,7 @@ the file (equivalent to Unix \fBtouch\fR). The time is measured in the standard POSIX fashion as seconds from a fixed starting time (often January 1, 1970). If the file does not exist or its modified time cannot be queried or set then an error is generated. +On \fBzipfs\fR file systems, modification time cannot be explicitly set. .TP \fBfile nativename \fIname\fR . @@ -395,19 +429,20 @@ that use the third component do not attempt to perform tilde substitution. .RE .TP -\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. -\fIVarName\fR is treated as an array variable, and the following elements -of that variable are set: \fBatime\fR, \fBctime\fR, \fBdev\fR, \fBgid\fR, -\fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR, \fBsize\fR, \fBtype\fR, -\fBuid\fR. Each element except \fBtype\fR is a decimal string with the -value of the corresponding field from the \fBstat\fR return structure; -see the manual entry for \fBstat\fR for details on the meanings of the -values. The \fBtype\fR element gives the type of the file in the same -form returned by the command \fBfile type\fR. This command returns an -empty string. +\fBfile stat \fIname ?varName?\fR +. +Invokes the \fBstat\fR kernel call on \fIname\fR, and returns a +dictionary with the information returned from the kernel call. If +\fIvarName\fR is given, it uses the variable to hold the information. +\fIVarName\fR is treated as an array variable, and in such case the +command returns the empty string. The following elements are set: +\fBatime\fR, \fBctime\fR, \fBdev\fR, \fBgid\fR, \fBino\fR, \fBmode\fR, +\fBmtime\fR, \fBnlink\fR, \fBsize\fR, \fBtype\fR, \fBuid\fR. Each element +except \fBtype\fR is a decimal string with the value of the corresponding +field from the \fBstat\fR return structure; see the manual entry for +\fBstat\fR for details on the meanings of the values. The \fBtype\fR +element gives the type of the file in the same form returned by the +command \fBfile type\fR. .TP \fBfile system \fIname\fR . @@ -438,9 +473,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 @@ -455,7 +519,22 @@ 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 tildeexpand \fIname\fR +.VS "8.7, TIP 602" +Returns the result of performing tilde substitution on \fIname\fR. If the name +begins with a tilde, then the file name will be interpreted as if the first +element is replaced with the location of the home directory for the given user. +If the tilde is followed immediately by a path separator, the \fBHOME\fR +environment variable is substituted. Otherwise the characters between the +tilde and the next separator are taken as a user name, which is used to +retrieve the user's home directory for substitution. An error is raised if the +\fBHOME\fR environment variable or user does not exist. +.RS +.PP +If the file name does not begin with a tilde, it is returned unmodified. +.RE +.VE "8.7, TIP 602" .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 31d4fe0..d8a3364 100644 --- a/doc/filename.n +++ b/doc/filename.n @@ -47,7 +47,8 @@ absolute, and file names may contain any character other than slash. The file names \fB\&.\fR and \fB\&..\fR are special and refer to the current directory and the parent of the current directory respectively. Multiple adjacent slash characters are interpreted as a single -separator. Any number of trailing slash characters at the end of a +separator, except for the first double slash \fB//\fR in absolute paths. +Any number of trailing slash characters at the end of a path are simply ignored, so the paths \fBfoo\fR, \fBfoo/\fR and \fBfoo//\fR are all identical, and in particular \fBfoo/\fR does not necessarily mean a directory is being referred. @@ -118,6 +119,13 @@ Volume-relative path to a file \fBfoo\fR in the root directory of the current volume. This is not a valid UNC path, so the assumption is that the extra backslashes are superfluous. .RE +.TP +\fBZipfs\fR +.RS +On all platforms where \fBzipfs\fR support is enabled, paths within mounted +ZIP archives begin with the string returned by the \fBzipfs root\fR command. +Zipfs paths are case-sensitive on all platforms. +.RE .SH "TILDE SUBSTITUTION" .PP In addition to the file name rules described above, Tcl also supports @@ -170,7 +178,11 @@ or dots with trailing characters .QW .....abc is illegal. .SH "SEE ALSO" -file(n), glob(n) +file(n), glob(n), zipfs(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..22d365e --- /dev/null +++ b/doc/fpclassify.n @@ -0,0 +1,83 @@ +'\" +'\" Copyright (c) 2018 Kevin B. Kenny <kennykb@acm.org>. All rights reserved +'\" Copyright (c) 2019 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: @@ -47,6 +47,43 @@ produce the same results as if there were an input line consisting only of the end-of-line character(s). The \fBeof\fR and \fBfblocked\fR commands can be used to distinguish these three cases. +.SH "ENCODING ERRORS" +.PP +Encoding errors may exist, if the encoding profile \fBstrict\fR is used. +Encoding errors are special, as an eventual introspection or recovery is +possible by changing to an encoding which accepts the data. +An encoding error is reported by the POSIX error code \fBEILSEQ\fR. +The file pointer is unchanged in the error case. +.PP +Here is an example with an encoding error in UTF-8 encoding, which is then +introspected by a switch to the binary encoding. The test file contains a not +continued multi-byte sequence at position 1 (\fBA \\xC3 B\fR): +.PP +File creation for example +.CS +% set f [open test_A_195_B.txt wb]; puts -nonewline $f A\\xC3B; close $f +.CE +Encoding error example +.CS +% set f [open test_A_195_B.txt r] +file384b6a8 +% fconfigure $f -encoding utf-8 -profile strict +% catch {gets $f} e d +1 +% set d +-code 1 -level 0 +-errorstack {INNER {invokeStk1 gets file384b6a8}} +-errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}} +-errorinfo {...} -errorline 1 +% tell $f +0 +% fconfigure $f -encoding binary -profile strict +% gets $f +AÃB +.CE +Compared to \fBread\fR, any already decoded data is not consumed. +The file position is still at 0 and the recovery \fBgets\fR returns also the +already well decoded leading data. .SH "EXAMPLE" This example reads a file one line at a time and prints it out with the current line number attached to the start of each line. 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: @@ -6,17 +6,17 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH "http" n 2.9 http "Tcl Bundled Packages" +.TH "http" n 2.10 http "Tcl Bundled Packages" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME http \- Client-side implementation of the HTTP/1.1 protocol .SH SYNOPSIS -\fBpackage require http ?2.9?\fR +\fBpackage require http\fR ?\fB2.10\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 @@ -32,36 +32,67 @@ http \- Client-side implementation of the HTTP/1.1 protocol .sp \fB::http::size \fItoken\fR .sp -\fB::http::code \fItoken\fR +\fB::http::error \fItoken\fR .sp -\fB::http::ncode \fItoken\fR +\fB::http::postError \fItoken\fR .sp -\fB::http::meta \fItoken\fR +\fB::http::cleanup \fItoken\fR .sp -\fB::http::data \fItoken\fR +\fB::http::requestLine\fR \fItoken\fR .sp -\fB::http::error \fItoken\fR +\fB::http::requestHeaders\fR \fItoken\fR ?\fIheaderName\fR? .sp -\fB::http::cleanup \fItoken\fR +\fB::http::requestHeaderValue\fR \fItoken\fR \fIheaderName\fR +.sp +\fB::http::responseLine\fR \fItoken\fR +.sp +\fB::http::responseCode\fR \fItoken\fR +.sp +\fB::http::reasonPhrase\fR \fIcode\fR .sp -\fB::http::register \fIproto port command\fR +\fB::http::responseHeaders\fR \fItoken\fR ?\fIheaderName\fR? .sp -\fB::http::registerError \fIport\fR ?\fImessage\fR? +\fB::http::responseHeaderValue\fR \fItoken\fR \fIheaderName\fR +.sp +\fB::http::responseInfo\fR \fItoken\fR +.sp +\fB::http::responseBody\fR \fItoken\fR +.sp +\fB::http::register \fIproto port command\fR ?\fIsocketCmdVarName\fR? ?\fIuseSockThread\fR? ?\fIendToEndProxy\fR? +.sp +\fB::http::registerError \fIsock\fR ?\fImessage\fR? .sp \fB::http::unregister \fIproto\fR +.sp +\fB::http::code \fItoken\fR +.sp +\fB::http::data \fItoken\fR +.sp +\fB::http::meta \fItoken\fR ?\fIheaderName\fR? +.sp +\fB::http::metaValue\fR \fItoken\fR \fIheaderName\fR +.sp +\fB::http::ncode \fItoken\fR .SH "EXPORTED COMMANDS" .PP Namespace \fBhttp\fR exports the commands \fBconfig\fR, \fBformatQuery\fR, -\fBgeturl\fR, \fBquoteString\fR, \fBregister\fR, \fBregisterError\fR, +\fBgeturl\fR, \fBpostError\fR, \fBquoteString\fR, \fBreasonPhrase\fR, +\fBregister\fR, +\fBregisterError\fR, \fBrequestHeaders\fR, \fBrequestHeaderValue\fR, +\fBrequestLine\fR, \fBresponseBody\fR, \fBresponseCode\fR, +\fBresponseHeaders\fR, \fBresponseHeaderValue\fR, \fBresponseInfo\fR, +\fBresponseLine\fR, \fBreset\fR, \fBunregister\fR, and \fBwait\fR. .PP It does not export the commands \fBcleanup\fR, \fBcode\fR, \fBdata\fR, -\fBerror\fR, \fBmeta\fR, \fBncode\fR, \fBsize\fR, or \fBstatus\fR. +\fBerror\fR, \fBmeta\fR, \fBmetaValue\fR, \fBncode\fR, +\fBsize\fR, or \fBstatus\fR. .BE .SH DESCRIPTION .PP The \fBhttp\fR package provides the client side of the HTTP/1.1 -protocol, as defined in RFC 7230 to RFC 7235, which supersede RFC 2616. +protocol, as defined in RFC 9110 to 9112, which supersede RFC 7230 +to RFC 7235, which in turn supersede RFC 2616. The package implements the GET, POST, and HEAD operations of HTTP/1.1. It allows configuration of a proxy host to get through firewalls. The package is compatible with the \fBSafesock\fR security @@ -74,14 +105,13 @@ The \fB::http::geturl\fR procedure does a HTTP transaction. Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction is performed. The return value of \fB::http::geturl\fR is a token for the transaction. -The value is also the name of an array in the ::http namespace -that contains state information about the transaction. The elements -of this array are described in the \fBSTATE ARRAY\fR section. +The token can be supplied as an argument to other commands, to manage the +transaction and examine its results. .PP If the \fB\-command\fR option is specified, then the HTTP operation is done in the background. \fB::http::geturl\fR returns immediately after generating the -HTTP request and the callback is invoked +HTTP request and the \fB\-command\fR callback is invoked when the transaction completes. For this to work, the Tcl event loop must be active. In Tk applications this is always true. For pure-Tcl applications, the caller can use \fB::http::wait\fR after calling @@ -90,6 +120,15 @@ applications, the caller can use \fB::http::wait\fR after calling \fBNote:\fR The event queue is even used without the \fB\-command\fR option. As a side effect, arbitrary commands may be processed while \fBhttp::geturl\fR is running. +.PP +When the HTTP server has replied to the request, call the command +\fB::http::responseInfo\fR, which +returns a \fBdict\fR of metadata that is essential for identifying a +successful transaction and making use of the response. See +section \fBMETADATA\fR for details of the information returned. +The response itself is returned by command \fB::http::responseBody\fR, +unless it has been redirected to a file by the \fI\-channel\fR option +of \fB::http::geturl\fR. .SH COMMANDS .TP \fB::http::config\fR ?\fIoptions\fR? @@ -111,6 +150,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 @@ -124,14 +172,15 @@ fresh socket, overriding the \fB\-keepalive\fR option of command \fBhttp::geturl\fR. See the \fBPERSISTENT SOCKETS\fR section for details. The default is 0. .TP -\fB\-proxyhost\fR \fIhostname\fR -. -The name of the proxy host, if any. If this value is the -empty string, the URL host is contacted directly. -.TP -\fB\-proxyport\fR \fInumber\fR +\fB\-proxyauth\fR \fIstring\fR . -The proxy port number. +If non-empty, the string is supplied to the proxy server as the value of the +request header Proxy-Authorization. This option can be used for HTTP Basic +Authentication. If the proxy server requires authentication by another +technique, e.g. Digest Authentication, the \fB\-proxyauth\fR option is not +useful. In that case the caller must expect a 407 response from the proxy, +compute the authentication value to be supplied, and use the \fB\-headers\fR +option to supply it as the value of the Proxy-Authorization header. .TP \fB\-proxyfilter\fR \fIcommand\fR . @@ -140,18 +189,46 @@ The command is a callback that is made during to determine if a proxy is required for a given host. One argument, a host name, is added to \fIcommand\fR when it is invoked. If a proxy is required, the callback should return a two-element list containing -the proxy server and proxy port. Otherwise the filter should return -an empty list. The default filter returns the values of the -\fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are -non-empty. +the proxy server and proxy port. Otherwise the filter command should return +an empty list. .RS .PP +The default value of \fB\-proxyfilter\fR is \fBhttp::ProxyRequired\fR, and +this command returns the values of the \fB\-proxyhost\fR and +\fB\-proxyport\fR settings if they are non-empty. The options +\fB\-proxyhost\fR, \fB\-proxyport\fR, and \fB\-proxynot\fR are used only +by \fBhttp::ProxyRequired\fR, and nowhere else in \fB::http::geturl\fR. +A user-supplied \fB\-proxyfilter\fR command may use these options, or +alternatively it may obtain values from elsewhere in the calling script. +In the latter case, any values provided for \fB\-proxyhost\fR, +\fB\-proxyport\fR, and \fB\-proxynot\fR are unused. +.PP The \fB::http::geturl\fR command runs the \fB\-proxyfilter\fR callback inside a \fBcatch\fR command. Therefore an error in the callback command does not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for details. .RE .TP +\fB\-proxyhost\fR \fIhostname\fR +. +The host name or IP address of the proxy server, if any. If this value is +the empty string, the URL host is contacted directly. See +\fB\-proxyfilter\fR for how the value is used. +.TP +\fB\-proxynot\fR \fIlist\fR +. +A Tcl list of domain names and IP addresses that should be accessed directly, +not through the proxy server. The target hostname is compared with each list +element using a case-insensitive \fBstring match\fR. It is often convenient +to use the wildcard "*" at the start of a domain name (e.g. *.example.com) or +at the end of an IP address (e.g. 192.168.0.*). See \fB\-proxyfilter\fR for +how the value is used. +.TP +\fB\-proxyport\fR \fInumber\fR +. +The port number of the proxy server. See \fB\-proxyfilter\fR for how the +value is used. +.TP \fB\-repost\fR \fIboolean\fR . Specifies what to do if a POST request over a persistent connection fails @@ -164,16 +241,29 @@ retrying the POST. The value \fBtrue\fR should be used only under certain conditions. See the \fBPERSISTENT SOCKETS\fR section for details. The default is 0. .TP +\fB\-threadlevel\fR \fIlevel\fR +. +Specifies whether and how to use the \fBThread\fR package. Possible values +of \fIlevel\fR are 0, 1 or 2. +.RS +.PP +.DS +0 - (the default) do not use Thread +1 - use Thread if it is available, do not use it if it is unavailable +2 - use Thread if it is available, raise an error if it is unavailable +.DE +The Tcl \fBsocket -async\fR command can block in adverse cases (e.g. a slow +DNS lookup). Using the Thread package works around this problem, for both +HTTP and HTTPS transactions. Values of \fIlevel\fR other than 0 are +available only to the main interpreter in each thread. See +section \fBTHREADS\fR for more information. +.RE +.TP \fB\-urlencoding\fR \fIencoding\fR . The \fIencoding\fR used for creating the x-url-encoded URLs with \fB::http::formatQuery\fR and \fB::http::quoteString\fR. -The default is \fButf-8\fR, as specified by RFC -2718. Prior to http 2.5 this was unspecified, and that behavior can be -returned by specifying the empty string (\fB{}\fR), although -\fIiso8859-1\fR is recommended to restore similar behavior but without the -\fB::http::formatQuery\fR or \fB::http::quoteString\fR -throwing an error processing non-latin-1 characters. +The default is \fButf-8\fR, as specified by RFC 2718. .TP \fB\-useragent\fR \fIstring\fR . @@ -188,21 +278,22 @@ numbers of \fBhttp\fR and \fBTcl\fR. \fB\-zip\fR \fIboolean\fR . If the value is boolean \fBtrue\fR, then by default requests will send a header -.QW "\fBAccept-Encoding: gzip,deflate,compress\fR" . -If the value is boolean \fBfalse\fR, then by default this header will not be -sent. In either case the default can be overridden for an individual request by +.QW "\fBAccept-Encoding: gzip,deflate\fR" . +If the value is boolean \fBfalse\fR, then by default requests will send a header +.QW "\fBAccept-Encoding: identity\fR" . +In either case the default can be overridden for an individual request by supplying a custom \fBAccept-Encoding\fR header in the \fB\-headers\fR option -of \fBhttp::geturl\fR. The default is 1. +of \fBhttp::geturl\fR. The default value is 1. .RE .TP \fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR? . The \fB::http::geturl\fR command is the main procedure in the package. -The \fB\-query\fR option causes a POST operation and +The \fB\-query\fR or \fB\-querychannel\fR option causes a POST operation and the \fB\-validate\fR option causes a HEAD operation; otherwise, a GET operation is performed. The \fB::http::geturl\fR command -returns a \fItoken\fR value that can be used to get -information about the transaction. See the \fBSTATE ARRAY\fR and +returns a \fItoken\fR value that can be passed as an argument to other commands +to get information about the transaction. See the \fBMETADATA\fR and \fBERRORS\fR section for details. The \fB::http::geturl\fR command blocks until the operation completes, unless the \fB\-command\fR option specifies a callback @@ -214,7 +305,7 @@ that is invoked when the HTTP transaction completes. . Specifies whether to force interpreting the URL data as binary. Normally this is auto-detected (anything not beginning with a \fBtext\fR content -type or whose content encoding is \fBgzip\fR or \fBcompress\fR is +type or whose content encoding is \fBgzip\fR or \fBdeflate\fR is considered binary data). .TP \fB\-blocksize\fR \fIsize\fR @@ -226,13 +317,14 @@ At most \fIsize\fR bytes are read at once. After each block, a call to the \fB\-channel\fR \fIname\fR . Copy the URL contents to channel \fIname\fR instead of saving it in -\fBstate(body)\fR. +a Tcl variable for retrieval by \fB::http::responseBody\fR. .TP \fB\-command\fR \fIcallback\fR . -Invoke \fIcallback\fR after the HTTP transaction completes. -This option causes \fB::http::geturl\fR to return immediately. -The \fIcallback\fR gets an additional argument that is the \fItoken\fR returned +The presence of this option causes \fB::http::geturl\fR to return immediately. +After the HTTP transaction completes, the value of \fIcallback\fR is expanded, +an additional argument is added, and the resulting command is evaluated. +The additional argument is the \fItoken\fR returned from \fB::http::geturl\fR. This token is the name of an array that is described in the \fBSTATE ARRAY\fR section. Here is a template for the callback: @@ -240,8 +332,10 @@ callback: .PP .CS proc httpCallback {token} { - upvar #0 $token state - # Access state as a Tcl array + upvar 0 $token state + # Access state as a Tcl array defined in this proc + ... + return } .CE .PP @@ -251,11 +345,30 @@ not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for details. .RE .TP +\fB\-guesstype\fR \fIboolean\fR +. +Attempt to guess the \fBContent-Type\fR and character set when a misconfigured +server provides no information. The default value is \fIfalse\fR (do +nothing). If boolean \fItrue\fR then, if the server does not send a +\fBContent-Type\fR header, or if it sends the value "application/octet-stream", +\fBhttp::geturl\fR will attempt to guess appropriate values. This is not +intended to become a general-purpose tool, and currently it is limited to +detecting XML documents that begin with an XML declaration. In this case +the \fBContent-Type\fR is changed to "application/xml", the binary flag +state(binary) is changed to 0, and the character set is changed to +the one specified by the "encoding" tag of the XML line, or to utf-8 if no +encoding is specified. Not used if a \fI\-channel\fR is specified. +.TP \fB\-handler\fR \fIcallback\fR . -Invoke \fIcallback\fR whenever HTTP data is available; if present, nothing -else will be done with the HTTP data. This procedure gets two additional -arguments: the socket for the HTTP data and the \fItoken\fR returned from +If this option is absent, \fBhttp::geturl\fR processes incoming data itself, +either appending it to the state(body) variable or writing it to the -channel. +But if the \fB\-handler\fR option is present, \fBhttp::geturl\fR does not do +this processing and instead calls \fIcallback\fR. +Whenever HTTP data is available, the value of \fIcallback\fR is expanded, an +additional two arguments are added, and the resulting command is evaluated. +The two additional +arguments are: the socket for the HTTP data and the \fItoken\fR returned from \fB::http::geturl\fR. The token is the name of a global array that is described in the \fBSTATE ARRAY\fR section. The procedure is expected to return the number of bytes read from the socket. Here is a @@ -264,8 +377,8 @@ template for the callback: .PP .CS proc httpHandlerCallback {socket token} { - upvar #0 $token state - # Access socket, and state as a Tcl array + upvar 0 $token state + # Access socket, and state as a Tcl array defined in this proc # For example... ... set data [read $socket 1000] @@ -278,8 +391,9 @@ proc httpHandlerCallback {socket token} { The \fBhttp::geturl\fR code for the \fB\-handler\fR option is not compatible with either compression or chunked transfer-encoding. If \fB\-handler\fR is specified, then to work around these issues \fBhttp::geturl\fR will reduce the -HTTP protocol to 1.0, and override the \fB\-zip\fR option (i.e. it will not -send the header "\fBAccept-Encoding: gzip,deflate,compress\fR"). +HTTP protocol to 1.0, and override the \fB\-zip\fR option (i.e. it will +send the header \fBAccept-Encoding: identity\fR instead +of \fBAccept-Encoding: gzip,deflate\fR). .PP If options \fB\-handler\fR and \fB\-channel\fR are used together, the handler is responsible for copying the data from the HTTP socket to the specified @@ -325,7 +439,10 @@ It is the caller's responsibility to ensure that the headers and request body (if any) conform to the requirements of the request method. For example, if using \fB\-method\fR \fIPOST\fR to send a POST with an empty request body, the caller must also supply the option -.QW "\-headers {Content-Length 0}" . +.PP +.CS +\-headers {Content-Length 0} +.CE .RE .TP \fB\-myaddr\fR \fIaddress\fR @@ -335,18 +452,26 @@ multiple interfaces are available. .TP \fB\-progress\fR \fIcallback\fR . -The \fIcallback\fR is made after each transfer of data from the URL. -The callback gets three additional arguments: the \fItoken\fR from +If the \fB\-progress\fR option is present, +then the \fIcallback\fR is made after each transfer of data from the URL. +The value of \fIcallback\fR is expanded, an additional three arguments are +added, and the resulting command is evaluated. +The three additional arguments are: the \fItoken\fR returned from \fB::http::geturl\fR, the expected total size of the contents from the -\fBContent-Length\fR meta-data, and the current number of bytes -transferred so far. The expected total size may be unknown, in which +\fBContent-Length\fR response header, and the current number of bytes +transferred so far. The token is the name of a global array that is +described in the \fBSTATE ARRAY\fR section. The expected total size may +be unknown, in which case zero is passed to the callback. Here is a template for the progress callback: .RS .PP .CS proc httpProgress {token total current} { - upvar #0 $token state + upvar 0 $token state + # Access state as a Tcl array defined in this proc + ... + return } .CE .RE @@ -390,20 +515,24 @@ This flag causes \fB::http::geturl\fR to do a POST request that passes the data contained in \fIchannelID\fR to the server. The data contained in \fIchannelID\fR must be an x-url-encoding formatted query unless the \fB\-type\fR option below is used. -If a Content-Length header is not specified via the \fB\-headers\fR options, -\fB::http::geturl\fR attempts to determine the size of the post data +If a \fBContent-Length\fR header is not specified via the \fB\-headers\fR +options, \fB::http::geturl\fR attempts to determine the size of the post data in order to create that header. If it is unable to determine the size, it returns an error. .TP \fB\-queryprogress\fR \fIcallback\fR . -The \fIcallback\fR is made after each transfer of data to the URL -(i.e. POST) and acts exactly like the \fB\-progress\fR option (the -callback format is the same). +If the \fB\-queryprogress\fR option is present, +then the \fIcallback\fR is made after each transfer of data to the URL +in a POST request (i.e. a call to \fB::http::geturl\fR with +option \fB\-query\fR or \fB\-querychannel\fR) and acts exactly like +the \fB\-progress\fR option (the callback format is the same). .TP \fB\-strict\fR \fIboolean\fR . -Whether to enforce RFC 3986 URL validation on the request. Default is 1. +If true then the command will test that the URL complies with RFC 3986, i.e. +that it has no characters that should be "x-url-encoded" (e.g. a space should +be encoded to "%20"). Default value is 1. .TP \fB\-timeout\fR \fImilliseconds\fR . @@ -411,7 +540,8 @@ If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout to occur after the specified number of milliseconds. A timeout results in a call to \fB::http::reset\fR and to the \fB\-command\fR callback, if specified. -The return value of \fB::http::status\fR is \fBtimeout\fR +The return value of \fB::http::status\fR (and the value of the \fIstatus\fR key +in the dictionary returned by \fB::http::responseInfo\fR) is \fBtimeout\fR after a timeout has occurred. .TP \fB\-type\fR \fImime-type\fR @@ -423,10 +553,11 @@ POST operation. \fB\-validate\fR \fIboolean\fR . If \fIboolean\fR is non-zero, then \fB::http::geturl\fR does an HTTP HEAD -request. This request returns meta information about the URL, but the -contents are not returned. The meta information is available in the -\fBstate(meta) \fR variable after the transaction. See the -\fBSTATE ARRAY\fR section for details. +request. This server returns the same status line and response headers as it +would for a HTTP GET request, but omits the response entity +(the URL "contents"). The response headers are available after the +transaction using command \fB::http::responseHeaders\fR or, for selected +information, \fB::http::responseInfo\fR. .RE .TP \fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...? @@ -450,7 +581,7 @@ This sets the \fBstate(status)\fR value to \fIwhy\fR, which defaults to .TP \fB::http::wait\fR \fItoken\fR . -This is a convenience procedure that blocks and waits for the +This command blocks and waits for the transaction to complete. This only works in trusted code because it uses \fBvwait\fR. Also, it is not useful for the case where \fB::http::geturl\fR is called \fIwithout\fR the \fB\-command\fR option @@ -458,72 +589,253 @@ because in this case the \fB::http::geturl\fR call does not return until the HTTP transaction is complete, and thus there is nothing to wait for. .TP -\fB::http::data\fR \fItoken\fR -. -This is a convenience procedure that returns the \fBbody\fR element -(i.e., the URL data) of the state array. -.TP -\fB::http::error\fR \fItoken\fR -. -This is a convenience procedure that returns the \fBerror\fR element -of the state array. -.TP \fB::http::status\fR \fItoken\fR . -This is a convenience procedure that returns the \fBstatus\fR element of -the state array. -.TP -\fB::http::code\fR \fItoken\fR -. -This is a convenience procedure that returns the \fBhttp\fR element of the -state array. +This command returns a description of the status of the HTTP transaction. +The return value is the empty string until the HTTP transaction is +completed; after completion it has one of the values ok, eof, error, +timeout, and reset. The meaning of these values is described in the +section \fBERRORS\fR (below). +.PP +.RS +The name "status" is not related to the terms "status line" and +"status code" that are defined for a HTTP response. +.RE .TP -\fB::http::ncode\fR \fItoken\fR +\fB::http::size\fR \fItoken\fR . -This is a convenience procedure that returns just the numeric return -code (200, 404, etc.) from the \fBhttp\fR element of the state array. +This command returns the number of bytes +received so far from the URL in the \fB::http::geturl\fR call. .TP -\fB::http::size\fR \fItoken\fR +\fB::http::error\fR \fItoken\fR . -This is a convenience procedure that returns the \fBcurrentsize\fR -element of the state array, which represents the number of bytes -received from the URL in the \fB::http::geturl\fR call. +This command returns the error information if the HTTP transaction failed, +or the empty string if there was no error. The information is a Tcl list of +the error message, stack trace, and error code. .TP -\fB::http::meta\fR \fItoken\fR +\fB::http::postError\fR \fItoken\fR . -This is a convenience procedure that returns the \fBmeta\fR -element of the state array which contains the HTTP response -headers. See below for an explanation of this element. +A POST request is a call to \fB::http::geturl\fR with either +the \fB\-query\fR or \fB\-querychannel\fR option. +The \fB::http::postError\fR command returns the error information generated +when a HTTP POST request sends its request-body to the server; or the empty +string if there was no error. The information is a Tcl list of the error +message, stack trace, and error code. When this type of error occurs, +the \fB::http::geturl\fR command continues the transaction and attempts to +receive a response from the server. .TP \fB::http::cleanup\fR \fItoken\fR . This procedure cleans up the state associated with the connection identified by \fItoken\fR. After this call, the procedures -like \fB::http::data\fR cannot be used to get information +like \fB::http::responseBody\fR cannot be used to get information about the operation. It is \fIstrongly\fR recommended that you call this function after you are done with a given HTTP request. Not doing so will result in memory not being freed, and if your app calls \fB::http::geturl\fR enough times, the memory leak could cause a performance hit...or worse. .TP -\fB::http::register\fR \fIproto port command\fR +\fB::http::requestLine\fR \fItoken\fR +. +This command returns the "request line" sent to the server. +The "request line" is the first line of a HTTP client request, and has three +elements separated by spaces: the HTTP method, the URL relative to the server, +and the HTTP version. Examples: +.PP +.RS +GET / HTTP/1.1 +GET /introduction.html?subject=plumbing HTTP/1.1 +POST /forms/order.html HTTP/1.1 +.RE +.TP +\fB::http::requestHeaders\fR \fItoken\fR ?\fIheaderName\fR? +. +This command returns the HTTP request header names and values, in the +order that they were sent to the server, as a Tcl list of the form +?name value ...? Header names are case-insensitive and are converted to lower +case. The return value is not a \fBdict\fR because some header names may occur +more than once. If one argument is supplied, all request headers +are returned. If two arguments are supplied, the +second provides the value of a header name. Only headers with the requested +name (converted to lower case) are returned. If no such headers are found, +an empty list is returned. +.TP +\fB::http::requestHeaderValue\fR \fItoken\fR \fIheaderName\fR +. +This command returns the value of the HTTP request header named +\fIheaderName\fR. Header names are case-insensitive and are converted to +lower case. If no such header exists, the return value is the empty string. +If there are multiple headers named \fIheaderName\fR, the result is obtained +by joining the individual values with the string ", " (comma and space), +preserving their order. +.TP +\fB::http::responseLine\fR \fItoken\fR +. +This command returns the first line of the server response: the +HTTP "status line". The "status line" has three +elements separated by spaces: the HTTP version, a three-digit numerical +"status code", and a "reason phrase". Only the reason phrase may contain +spaces. Examples: +.PP +.RS +HTTP/1.1 200 OK +HTTP/1.0 404 Not Found +.RE +.RS +The "status code" is a three-digit number in the range 100 to 599. +A value of 200 is the normal return from a GET request, and its matching +"reason phrase" is "OK". Codes beginning with 4 or 5 indicate errors. +Codes beginning with 3 are redirection errors. In this case the +\fBLocation\fR response header specifies a new URL that contains the +requested information. +.PP +The "reason phrase" is a textual description of the "status code": it may +vary from server to server, +and can be changed without affecting the HTTP protocol. The recommended +values (RFC 7231 and IANA assignments) for each code are provided by the +command \fB::http::reasonPhrase\fR. +.RE +.TP +\fB::http::responseCode\fR \fItoken\fR +. +This command returns the "status code" (200, 404, etc.) of the server +"status line". If a three-digit code cannot be found, the full status +line is returned. See command \fB::http::responseLine\fR for more information +on the "status line". +.TP +\fB::http::reasonPhrase\fR \fIcode\fR +. +This command returns the IANA recommended "reason phrase" for a particular +"status code" returned by a HTTP server. The argument \fIcode\fR is a valid +status code, and therefore is an integer in the range 100 to 599 inclusive. +For numbers in this range with no assigned meaning, the command returns the +value "Unassigned". Several status codes are used only in response to the +methods defined by HTTP extensions such as WebDAV, and not in response to a +HEAD, GET, or POST request method. +.PP +.RS +The "reason phrase" returned by a HTTP server may differ from the recommended +value, without affecting the HTTP protocol. The value returned by +\fB::http::geturl\fR can be obtained by calling either command +\fB::http::responseLine\fR (which returns the full status line) or command +\fB::http::responseInfo\fR (which returns a dictionary, with +the "reason phrase" stored in key \fIreasonPhrase\fR). +.PP +A registry of valid status codes is maintained at +https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml +.RE +.TP +\fB::http::responseHeaders\fR \fItoken\fR ?\fIheaderName\fR? +. +The response from a HTTP server includes metadata headers that describe the +response body and the transaction itself. +This command returns the HTTP response header names and values, in the +order that they were received from the server, as a Tcl list of the form +?name value ...? Header names are case-insensitive and are converted to lower +case. The return value is not a \fBdict\fR because some header names may occur +more than once, notably \fBSet-Cookie\fR. If the second argument is not +supplied, all response headers are returned. If the second argument is +supplied, it provides the value of a header name. Only headers with the +requested name (converted to lower case) are returned. If no such headers +are found, an empty list is returned. See section \fBMETADATA\fR for more +information. +.TP +\fB::http::responseHeaderValue\fR \fItoken\fR \fIheaderName\fR +. +This command returns the value of the HTTP response header named +\fIheaderName\fR. Header names are case-insensitive and are converted to +lower case. If no such header exists, the return value is the empty string. +If there are multiple headers named \fIheaderName\fR, the result is obtained +by joining the individual values with the string ", " (comma and space), +preserving their order. Multiple headers with the same name may be processed +in this manner, except \fBSet-Cookie\fR which does not conform to the +comma-separated-list syntax and cannot be combined into a single value. +Each \fBSet-Cookie\fR header must be treated individually, e.g. by processing +the return value of \fB::http::responseHeaders\fR \fItoken\fR \fBSet-Cookie\fR. +.TP +\fB::http::responseInfo\fR \fItoken\fR +. +This command returns a \fBdict\fR of selected response metadata that are +essential for identifying a successful transaction and making use of the +response, along with other metadata that are informational. The keys of +the \fBdict\fR are \fIstage\fR, \fIstatus\fR, \fIresponseCode\fR, +\fIreasonPhrase\fR, \fIcontentType\fR, \fIbinary\fR, \fIredirection\fR, +\fIupgrade\fR, \fIerror\fR, \fIpostError\fR, \fImethod\fR, \fIcharset\fR, +\fIcompression\fR, \fIhttpRequest\fR, \fIhttpResponse\fR, \fIurl\fR, +\fIconnectionRequest\fR, \fIconnectionResponse\fR, \fIconnectionActual\fR, +\fItransferEncoding\fR, \fItotalPost\fR, \fIcurrentPost\fR, \fItotalSize\fR, +and \fIcurrentSize\fR. The meaning of these keys is described in the +section \fBMETADATA\fR below. +.RS +.PP +It is always worth checking the value of \fIbinary\fR after a HTTP transaction, +to determine whether a misconfigured server has caused http to interpret a +text resource as a binary, or vice versa. +.PP +After a POST transaction, check the value of \fIpostError\fR to verify that +the request body was uploaded without error. +.RE +.TP +\fB::http::responseBody\fR \fItoken\fR +. +This command returns the entity sent by the HTTP server (unless +\fI-channel\fR was used, in which case the entity was delivered to the +channel, and the command returns the empty string). +.RS +.PP +Other terms for +"entity", with varying precision, include "representation of resource", +"resource", "response body after decoding", "payload", +"message body after decoding", "content(s)", and "file". +.RE +.TP +\fB::http::register\fR \fIproto port command\fR ?\fIsocketCmdVarName\fR? ?\fIuseSockThread\fR? ?\fIendToEndProxy\fR? . This procedure allows one to provide custom HTTP transport types such as HTTPS, by registering a prefix, the default port, and the -command to execute to create the Tcl \fBchannel\fR. E.g.: +command to execute to create the Tcl \fBchannel\fR. The optional +arguments configure how \fBhttp\fR uses the custom transport, and have +default values that are compatible with older versions of \fBhttp\fR +in which \fB::http::register\fR has no optional arguments. +.RS +.PP +Argument \fIsocketCmdVarName\fR is the name of a variable provided by +the transport, whose value is the command used by the transport to open +a socket. Its default value is set by the transport and is "::socket", +but if the name of the variable is supplied to \fB::http::register\fR, +then \fBhttp\fR will set a new value in order to make optional +facilities available. These facilities are enabled by the optional +arguments \fIuseSockThread\fR, \fIendToEndProxy\fR, which take boolean +values with default value \fIfalse\fR. +.PP +Iff argument \fIuseSockThread\fR is supplied and is boolean \fItrue\fR, +then iff permitted by the value [\fBhttp::config\fR \fI-threadlevel\fR] +and by the availability of package \fBThread\fR, sockets created for +the transport will be opened in a different thread so that a slow DNS +lookup will not cause the script to block. +.PP +Iff argument \fIendToEndProxy\fR is supplied and is boolean \fItrue\fR, +then when \fBhttp::geturl\fR accesses a server via a proxy, it will +open a channel by sending a CONNECT request to the proxy, and it will +then make its request over this channel. This allows end-to-end +encryption for HTTPS requests made through a proxy. +.PP +For example, .RS .PP .CS package require http + package require tls -::http::register https 443 ::tls::socket +::http::register https 443 ::tls::socket ::tls::socketCmd 1 1 set token [::http::geturl https://my.secure.site/] .CE .RE +.RE .TP -\fB::http::registerError\fR \fIport\fR ?\fImessage\fR? +\fB::http::registerError\fR \fIsock\fR ?\fImessage\fR? . This procedure allows a registered protocol handler to deliver an error message for use by \fBhttp\fR. Calling this command does not raise an @@ -537,22 +849,37 @@ string if no such call has been made. \fB::http::unregister\fR \fIproto\fR . This procedure unregisters a protocol handler that was previously -registered via \fB::http::register\fR, returning a two-item list of -the default port and handler command that was previously installed -(via \fB::http::register\fR) if there was such a handler, and an error if -there was no such handler. +registered via \fB::http::register\fR, returning a six-item list of +the values that were previously supplied to \fB::http::register\fR +if there was such a handler, and an error if there was no such handler. +.TP +\fB::http::code\fR \fItoken\fR +. +An alternative name for the command \fB::http::responseLine\fR +.TP +\fB::http::data\fR \fItoken\fR +. +An alternative name for the command \fB::http::responseBody\fR. +.TP +\fB::http::meta\fR \fItoken\fR ?\fIheaderName\fR? +. +An alternative name for the command \fB::http::responseHeaders\fR +.TP +\fB::http::ncode\fR \fItoken\fR +. +An alternative name for the command \fB::http::responseCode\fR .SH ERRORS The \fB::http::geturl\fR procedure will raise errors in the following cases: invalid command line options, -an invalid URL, -a URL on a non-existent host, -or a URL at a bad port on an existing host. +or an invalid URL. These errors mean that it cannot even start the network transaction. -It will also raise an error if it gets an I/O error while -writing out the HTTP request header. For synchronous \fB::http::geturl\fR calls (where \fB\-command\fR is -not specified), it will raise an error if it gets an I/O error while +not specified), it will raise an error if +the URL is on a non-existent host +or at a bad port on an existing host. +It will also raise an error for any I/O errors while +writing out the HTTP request line and headers, or reading the HTTP reply headers or data. Because \fB::http::geturl\fR does not return a token in these cases, it does all the required cleanup and there is no issue of your app having to call @@ -564,13 +891,12 @@ HTTP reply headers or data, no exception is thrown. This is because after writing the HTTP headers, \fB::http::geturl\fR returns, and the rest of the HTTP transaction occurs in the background. The command callback can check if any error occurred during the read by calling -\fB::http::status\fR to check the status and if its \fIerror\fR, -calling \fB::http::error\fR to get the error message. +\fB::http::responseInfo\fR to check the transaction status. .PP Alternatively, if the main program flow reaches a point where it needs to know the result of the asynchronous HTTP request, it can call \fB::http::wait\fR and then check status and error, just as the -callback does. +synchronous call does. .PP The \fB::http::geturl\fR command runs the \fB\-command\fR, \fB\-handler\fR, and \fB\-proxyfilter\fR callbacks inside a \fBcatch\fR command. Therefore @@ -584,15 +910,17 @@ In any case, you must still call \fB::http::cleanup\fR to delete the state array when you are done. .PP There are other possible results of the HTTP transaction -determined by examining the status from \fB::http::status\fR. +determined by examining the status from \fB::http::status\fR (or the value +of the \fIstatus\fR key in the dictionary returned +by \fB::http::responseInfo\fR). These are described below. .TP \fBok\fR . If the HTTP transaction completes entirely, then status will be \fBok\fR. -However, you should still check the \fB::http::code\fR value to get -the HTTP status. The \fB::http::ncode\fR procedure provides just -the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fR +However, you should still check the \fB::http::responseLine\fR value to get +the HTTP status. The \fB::http::responseCode\fR procedure provides just +the numeric error (e.g., 200, 404 or 500) while the \fB::http::responseLine\fR procedure returns a value like .QW "HTTP 404 File not found" . .TP @@ -603,147 +931,447 @@ is raised, but the status of the transaction will be \fBeof\fR. .TP \fBerror\fR . -The error message will also be stored in the \fBerror\fR status -array element, accessible via \fB::http::error\fR. +The error message, stack trace, and error code are accessible +via \fB::http::error\fR. The error message is also provided by the value of +the \fIerror\fR key in the dictionary returned by \fB::http::responseInfo\fR. .TP \fBtimeout\fR . -A timeout occurred before the transaction could complete +A timeout occurred before the transaction could complete. .TP \fBreset\fR . -user-reset -.PP -Another error possibility is that \fB::http::geturl\fR is unable to -write all the post query data to the server before the server -responds and closes the socket. -The error message is saved in the \fBposterror\fR status array -element and then \fB::http::geturl\fR attempts to complete the -transaction. -If it can read the server's response -it will end up with an \fBok\fR status, otherwise it will have -an \fBeof\fR status. +The user has called \fB::http::reset\fR. +.TP +\fB""\fR +. +(empty string) The transaction has not yet finished. +.PP +Another error possibility is that \fB::http::geturl\fR failed to +write the whole of the POST request body (\fB-query\fR or \fB-querychannel\fR +data) to the server. \fB::http::geturl\fR stores the error message for later +retrieval by the \fB::http::postError\fR or \fB::http::responseInfo\fR +commands, and then attempts to complete the transaction. +If it can read the server's response the status will be \fBok\fR, but it is +important to call \fB::http::postError\fR or \fB::http::responseInfo\fR after +every POST to check that the data was sent in full. +If the server has closed the connection the status will be \fBeof\fR. +.SH "METADATA" +.PP +.SS "MOST USEFUL METADATA" +When a HTTP server responds to a request, it supplies not only the entity +requested, but also metadata. This is provided by the first line (the +"status line") of the response, and by a number of HTTP headers. Further +metadata relates to how \fB::http::geturl\fR has processed the response +from the server. +.PP +The most important metadata can be accessed with the command +\fB::http::responseInfo\fR. +This command returns a \fBdict\fR of metadata that are essential for +identifying a successful transaction and making use of the response, +along with other metadata that are informational. The keys of +the \fBdict\fR are: +.PP +.RS +.RS +\fB===== Essential Values =====\fR +.RE +.RE +.TP +\fBstage\fR +. +This value, set by \fB::http::geturl\fR, describes the stage that the +transaction has reached. Values, in order of the transaction lifecycle, +are: "created", "connecting", "header", "body", and "complete". The +other \fBdict\fR keys will not be available until the value of \fBstage\fR +is "body" or "complete". The key \fBcurrentSize\fR has its final value only +when \fBstage\fR is "complete". +.TP +\fBstatus\fR +. +This value, set by \fB::http::geturl\fR, is "ok" for a successful transaction; +"eof", "error", "timeout", or "reset" for an unsuccessful transaction; or "" +if the transaction is still in progress. The value is the same as that +returned by command \fB::http::status\fR. The meaning of these values is +described in the section \fBERRORS\fR (above). +.TP +\fBresponseCode\fR +. +The "HTTP status code" sent by the server in the first line (the "status line") +of the response. If the value cannot be extracted from the status line, the +full status line is returned. +.TP +\fBreasonPhrase\fR +. +The "reason phrase" sent by the server as a description of the HTTP status code. +If the value cannot be extracted from the status line, the full status +line is returned. +.TP +\fBcontentType\fR +. +The value of the \fBContent-Type\fR response header or, if the header was not +supplied, the default value "application/octet-stream". +.TP +\fBbinary\fR +. +This boolean value, set by \fB::http::geturl\fR, describes how the command +has interpreted the entity returned by the server (after decoding any +compression specified by the \fBContent-Encoding\fR response header). +This decoded entity is accessible as the return value of the +command \fB::http::responseBody\fR. +.PP +.RS +The value is \fBtrue\fR if http has interpreted the decoded entity as binary. +The value returned by \fB::http::responseBody\fR is a Tcl binary string. +This is a suitable format for image data, zip files, etc. +\fB::http::geturl\fR chooses this value if the user has requested a binary +interpretation by passing the option \fI\-binary\fR to the command, or if the +server has supplied a binary content type in a \fBContent-Type\fR response +header, or if the server has not supplied any \fBContent-Type\fR header. +.PP +The value is \fBfalse\fR in other cases, and this means that http has +interpreted the decoded entity as text. The text has been converted, from the +character set notified by the server, into Tcl's internal Unicode format; +the value returned by \fB::http::responseBody\fR is an ordinary Tcl string. +.PP +It is always worth checking the value of "binary" after a HTTP transaction, +to determine whether a misconfigured server has caused http to interpret a +text resource as a binary, or vice versa. +.RE +.TP +\fBredirection\fR +. +The URL that is the redirection target. The value is that of the \fBLocation\fR +response header. This header is sent when a response has status code +3XX (redirection). +.TP +\fBupgrade\fR +. +If not empty, the value indicates the protocol(s) to which the server will +switch after completion of this transaction, while continuing to use the +same connection. When the server intends to switch protocols, it will also +send the value "101" as the status code (the \fBresponseCode\fR key), and the +word "upgrade" as an element of the \fBConnection\fR response header (the +\fBconnectionResponse\fR key), and it will not send a response body. +See the section \fBPROTOCOL UPGRADES\fR for more information. +.TP +\fBerror\fR +. +The error message, if there is one. Further information, including a stack +trace and error code, are available from command \fB::http::error\fR. +.TP +\fBpostError\fR +. +The error message (if any) generated when a HTTP POST request sends its +request-body to the server. Further information, including a stack trace +and error code, are available from command \fB::http::postError\fR. A POST +transaction may appear complete, according to the +keys \fBstage\fR, \fBstatus\fR, and \fBresponseCode\fR, but it is important +to check this \fBpostError\fR key in case an error occurred when uploading +the request-body. +.PP +.RS +.RS +\fB===== Informational Values =====\fR +.RE +.RE +.TP +\fBmethod\fR +. +The HTTP method used in the request. +.TP +\fBcharset\fR +. +The value of the charset attribute of the \fBContent-Type\fR response header. +The charset value is used only for a text resource. If the server did not +specify a charset, the value defaults to that of the +variable \fB::http::defaultCharset\fR, which unless it has been deliberately +modified by the caller is \fBiso8859-1\fR. Incoming text data is automatically +converted from the character set defined by \fBcharset\fR to Tcl's internal +Unicode representation, i.e. to a Tcl string. +.TP +\fBcompression\fR +. +A copy of the \fBContent-Encoding\fR response-header value. +.TP +\fBhttpRequest\fR +. +The version of HTTP specified in the request (i.e. sent in the request line). +The value is that of the option \fB\-protocol\fR supplied +to \fB::http::geturl\fR (default value "1.1"), unless the command reduced the +value to "1.0" because it was passed the \fB\-handler\fR option. +.TP +\fBhttpResponse\fR +. +The version of HTTP used by the server (obtained from the response +"status line"). The server uses this version of HTTP in its response, but +ensures that this response is compatible with the HTTP version specified in the +client's request. If the value cannot be extracted from the status line, the +full status line is returned. +.TP +\fBurl\fR +. +The requested URL, typically the URL supplied as an argument +to \fB::http::geturl\fR but without its "fragment" (the final part of the URL +beginning with "#"). +.TP +\fBconnectionRequest\fR +. +The value, if any, sent to the server in \fBConnection\fR request header(s). +.TP +\fBconnectionResponse\fR +. +The value, if any, received from the server in \fBConnection\fR response +header(s). +.TP +\fBconnectionActual\fR +. +This value, set by \fB::http::geturl\fR, reports whether the connection was +closed after the transaction (value "close"), or left open (value "keep-alive"). +.TP +\fBtransferEncoding\fR +. +The value of the Transfer-Encoding response header, if it is present. +The value is either "chunked" (indicating HTTP/1.1 "chunked encoding") or +the empty string. +.TP +\fBtotalPost\fR +. +The total length of the request body in a POST request. +.TP +\fBcurrentPost\fR +. +The number of bytes of the POST request body sent to the server so far. +The value is the same as that returned by command \fB::http::size\fR. +.TP +\fBtotalSize\fR +. +A copy of the \fBContent-Length\fR response-header value. +The number of bytes specified in a \fBContent-Length\fR header, if one +was sent. If none was sent, the value is 0. A correctly configured server +omits this header if the transfer-encoding is "chunked", or (for older +servers) if the server closes the connection when it reaches the end of +the resource. +.TP +\fBcurrentSize\fR +. +The number of bytes fetched from the server so far. +.PP +.SS "MORE METADATA" +The dictionary returned by \fB::http::responseInfo\fR is the most useful +subset of the available metadata. Other metadata include: +.PP +1. The full "status line" of the response, available as the return value +of command \fB::http::responseLine\fR. +.PP +2. The full response headers, available as the return value of +command \fB::http::responseHeaders\fR. This return value is a list of the +response-header names and values, in the order that they were received from +the server. +.PP +The return value is not a \fBdict\fR because some header names may +occur more than once, notably \fBSet-Cookie\fR. If the value is read +into a \fBdict\fR or into an array (using array set), only the last header +with each name will be preserved. +.PP +.RS +Some of the header names (metadata keys) are listed below, but the HTTP +standard defines several more, and servers are free to add their own. +When a dictionary key is mentioned below, this refers to the \fBdict\fR +value returned by command \fB::http::responseInfo\fR. +.TP +\fBContent-Type\fR +. +The content type of the URL contents. Examples include \fBtext/html\fR, +\fBimage/gif,\fR \fBapplication/postscript\fR and +\fBapplication/x-tcl\fR. Text values typically specify a character set, e.g. +\fBtext/html; charset=UTF-8\fR. Dictionary key \fIcontentType\fR. +.TP +\fBContent-Length\fR +. +The advertised size in bytes of the contents, available as dictionary +key \fItotalSize\fR. The actual number of bytes read by \fB::http::geturl\fR +so far is available as dictionary key \fBcurrentSize\fR. +.TP +\fBContent-Encoding\fR +. +The compression algorithm used for the contents. +Examples include \fBgzip\fR, \fBdeflate\fR. +Dictionary key \fIcontent\fR. +.TP +\fBLocation\fR +. +This header is sent when a response has status code 3XX (redirection). +It provides the URL that is the redirection target. +Dictionary key \fIredirection\fR. +.TP +\fBSet-Cookie\fR +. +This header is sent to offer a cookie to the client. Cookie management is +done by the \fB::http::config\fR option \fI\-cookiejar\fR, and so +the \fBSet-Cookie\fR headers need not be parsed by user scripts. +See section \fBCOOKIE JAR PROTOCOL\fR. +.TP +\fBConnection\fR +. +The value can be supplied as a comma-separated list, or by multiple headers. +The list often has only one element, either "close" or "keep-alive". +The value "upgrade" indicates a successful upgrade request and is typically +combined with the status code 101, an \fBUpgrade\fR response header, and no +response body. Dictionary key \fIconnectionResponse\fR. +.TP +\fBUpgrade\fR +. +The value indicates the protocol(s) to which the server will switch +immediately after the empty line that terminates the 101 response headers. +Dictionary key \fIupgrade\fR. +.RE +.PP +.SS "EVEN MORE METADATA" +.PP +1. Details of the HTTP request. The request is determined by the options +supplied to \fB::http::geturl\fR and \fB::http::config\fR. However, it is +sometimes helpful to examine what \fB::http::geturl\fR actually sent to the +server, and this information is available through +commands \fB::http::requestHeaders\fR and \fB::http::requestLine\fR. +.PP +2. The state array: the internal variables of \fB::http::geturl\fR. +It may sometimes be helpful to examine this array. +Details are given in the next section. .SH "STATE ARRAY" -The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to -get to the state of the HTTP transaction in the form of a Tcl array. -Use this construct to create an easy-to-use array variable: +The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used +as an argument to other \fB::http::*\fR commands, which examine and manage +the state of the HTTP transaction. For most purposes these commands are +sufficient. The \fItoken\fR can also be used to access +the internal state of the transaction, which is stored in a Tcl array. +This facility is most useful when writing callback commands for the +options \fB\-command\fR, \fB\-handler\fR, \fB\-progress\fR, +or \fB\-queryprogress\fR. +Use the following command inside the proc to define an easy-to-use +array \fIstate\fR as a local variable within the proc .PP .CS -upvar #0 $token state +upvar 0 $token state .CE .PP Once the data associated with the URL is no longer needed, the state array should be unset to free up storage. The \fB::http::cleanup\fR procedure is provided for that purpose. -The following elements of -the array are supported: +.PP +The following elements of the array are supported, and are the origin of the +values returned by commands as described below. When a dictionary key is +mentioned below, this refers to the \fBdict\fR value returned by +command \fB::http::responseInfo\fR. .RS .TP \fBbinary\fR . -This is boolean \fBtrue\fR if (after decoding any compression specified -by the -.QW "Content-Encoding" -response header) the HTTP response is binary. It is boolean \fBfalse\fR -if the HTTP response is text. +For dictionary key \fIbinary\fR. .TP \fBbody\fR . -The contents of the URL. This will be empty if the \fB\-channel\fR -option has been specified. This value is returned by the \fB::http::data\fR -command. +For command \fB::http::responseBody\fR. .TP \fBcharset\fR . -The value of the charset attribute from the \fBContent-Type\fR meta-data -value. If none was specified, this defaults to the RFC standard -\fBiso8859-1\fR, or the value of \fB$::http::defaultCharset\fR. Incoming -text data will be automatically converted from this charset to utf-8. +For dictionary key \fIcharset\fR. .TP \fBcoding\fR . -A copy of the \fBContent-Encoding\fR meta-data value. +For dictionary key \fIcompression\fR. +.TP +\fBconnection\fR +. +For dictionary key \fIconnectionActual\fR. .TP \fBcurrentsize\fR . -The current number of bytes fetched from the URL. -This value is returned by the \fB::http::size\fR command. +For command \fB::http::size\fR; and for dictionary key \fIcurrentSize\fR. .TP \fBerror\fR . -If defined, this is the error string seen when the HTTP transaction -was aborted. +For command \fB::http::error\fR; part is used in dictionary key \fIerror\fR. .TP \fBhttp\fR . -The HTTP status reply from the server. This value -is returned by the \fB::http::code\fR command. The format of this value is: -.RS -.PP -.CS -\fIHTTP/1.1 code string\fR -.CE -.PP -The \fIcode\fR is a three-digit number defined in the HTTP standard. -A code of 200 is OK. Codes beginning with 4 or 5 indicate errors. -Codes beginning with 3 are redirection errors. In this case the -\fBLocation\fR meta-data specifies a new URL that contains the -requested information. -.RE +For command \fB::http::responseLine\fR. +.TP +\fBhttpResponse\fR +. +For dictionary key \fIhttpResponse\fR. .TP \fBmeta\fR . -The HTTP protocol returns meta-data that describes the URL contents. -The \fBmeta\fR element of the state array is a list of the keys and -values of the meta-data. This is in a format useful for initializing -an array that just contains the meta-data: -.RS -.PP -.CS -array set meta $state(meta) -.CE -.PP -Some of the meta-data keys are listed below, but the HTTP standard defines -more, and servers are free to add their own. +For command \fB::http::responseHeaders\fR. Further discussion above in the +section \fBMORE METADATA\fR. .TP -\fBContent-Type\fR +\fBmethod\fR . -The type of the URL contents. Examples include \fBtext/html\fR, -\fBimage/gif,\fR \fBapplication/postscript\fR and -\fBapplication/x-tcl\fR. +For dictionary key \fImethod\fR. .TP -\fBContent-Length\fR +\fBposterror\fR . -The advertised size of the contents. The actual size obtained by -\fB::http::geturl\fR is available as \fBstate(currentsize)\fR. +For dictionary key \fIpostError\fR. .TP -\fBLocation\fR +\fBpostErrorFull\fR . -An alternate URL that contains the requested data. -.RE +For command \fB::http::postError\fR. .TP -\fBposterror\fR +\fB\-protocol\fR . -The error, if any, that occurred while writing -the post query data to the server. +For dictionary key \fIhttpRequest\fR. +.TP +\fBquerylength\fR +. +For dictionary key \fItotalPost\fR. +.TP +\fBqueryoffset\fR +. +For dictionary key \fIcurrentPost\fR. +.TP +\fBreasonPhrase\fR +. +For dictionary key \fIreasonPhrase\fR. +.TP +\fBrequestHeaders\fR +. +For command \fB::http::requestHeaders\fR. +.TP +\fBrequestLine\fR +. +For command \fB::http::requestLine\fR. +.TP +\fBresponseCode\fR +. +For dictionary key \fIresponseCode\fR. +.TP +\fBstate\fR +. +For dictionary key \fIstage\fR. .TP \fBstatus\fR . -See description in the chapter \fBERRORS\fR above for a -list and description of \fBstatus\fR. -During the transaction this value is the empty string. +For command \fB::http::status\fR; and for dictionary key \fIstatus\fR. .TP \fBtotalsize\fR . -A copy of the \fBContent-Length\fR meta-data value. +For dictionary key \fItotalSize\fR. +.TP +\fBtransfer\fR +. +For dictionary key \fItransferEncoding\fR. .TP \fBtype\fR . -A copy of the \fBContent-Type\fR meta-data value. +For dictionary key \fIcontentType\fR. +.TP +\fBupgrade\fR +. +For dictionary key \fIupgrade\fR. .TP \fBurl\fR . -The requested URL. +For dictionary key \fIurl\fR. .RE .SH "PERSISTENT CONNECTIONS" .PP @@ -842,28 +1470,133 @@ that fails because it uses a persistent connection that the server has half-closed (an .QW "asynchronous close event" ). Subsequent GET and HEAD requests in a failed pipeline will also be retried. -\fIThe \-repost option should be used only if the application understands +\fIThe \fB\-repost\fI option should be used only if the application understands 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 "PROTOCOL UPGRADES" .PP -The HTTP/1.1 \fBConnection\fR and \fBUpgrade\fR client headers inform the server -that the client wishes to change the protocol used over the existing connection -(RFC 7230). This mechanism can be used to request a WebSocket (RFC 6455), a +The HTTP/1.1 \fBConnection\fR and \fBUpgrade\fR request headers inform the +server that the client wishes to change the protocol used over the existing +connection (RFC 7230). +This mechanism can be used to request a WebSocket (RFC 6455), a higher version of the HTTP protocol (HTTP 2), or TLS encryption. If the server accepts the upgrade request, its response code will be 101. .PP -To request a protocol upgrade when calling \fBhttp::geturl\fR, the \fB\-headers\fR -option must supply appropriate values for \fBConnection\fR and \fBUpgrade\fR, and +To request a protocol upgrade when calling \fBhttp::geturl\fR, +the \fB\-headers\fR option must supply appropriate values for \fBConnection\fR +and \fBUpgrade\fR, and the \fB\-command\fR option must supply a command that implements the requested protocol and can also handle the server response if the server refuses the protocol upgrade. For upgrade requests \fBhttp::geturl\fR ignores the value of option \fB\-keepalive\fR, and always uses the value \fB0\fR so that the upgrade -request is not made over a connection that is intended for multiple HTTP requests. +request is not made over a connection that is intended for multiple HTTP +requests. .PP -The Tcllib library \fBwebsocket\fR implements WebSockets, and makes the necessary -calls to commands in the \fBhttp\fR package. +The Tcllib library \fBwebsocket\fR implements WebSockets, and makes the +necessary calls to commands in the \fBhttp\fR package. .PP There is currently no native Tcl client library for HTTP/2. .PP @@ -874,16 +1607,59 @@ protocols such as Internet Printing Protocol (IPP) that are built on top of traffic. .PP In browsers, opportunistic encryption is instead implemented by the -\fBUpgrade-Insecure-Requests\fR client header. If a secure service is available, -the server response code is a 307 redirect, and the response header -\fBLocation\fR specifies the target URL. The browser must call \fBhttp::geturl\fR -again in order to fetch this URL. +\fBUpgrade-Insecure-Requests\fR client header. If a secure service is +available, the server response code is a 307 redirect, and the response header +\fBLocation\fR specifies the target URL. The browser must +call \fBhttp::geturl\fR again in order to fetch this URL. See https://w3c.github.io/webappsec-upgrade-insecure-requests/ .PP +.SH THREADS +.PP +.SS "PURPOSE" +.PP +Command \fB::http::geturl\fR uses the Tcl \fB::socket\fR command with +the \fI\-async\fR option to connect to a remote server, but the return from +this command can be delayed in adverse cases (e.g. a slow DNS lookup), +preventing the event loop from processing other events. +This delay is avoided if the \fB::socket\fR command is evaluated in another +thread. The Thread package is not part of Tcl but is provided in +"Batteries Included" distributions. Instead of the \fB::socket\fR command, +the http package uses \fB::http::socket\fR which makes connections in the +manner specified by the value of \fI\-threadlevel\fR and the availability +of package Thread. +.PP +.SS "WITH TLS (HTTPS)" +.PP +The same \fI\-threadlevel\fR configuration applies to both HTTP and HTTPS +connections. +HTTPS is enabled by using the \fBhttp::register\fR command, typically by +specifying the \fB::tls::socket\fR command of the tls package to handle TLS +cryptography. The \fB::tls::socket\fR command connects to the remote server by +using the command specified by the value of variable \fB::tls::socketCmd\fR, and +this value defaults to "::socket". If http::geturl finds +that \fB::tls::socketCmd\fR has this value, it replaces it with the value +"::http::socket". If \fB::tls::socketCmd\fR has a value other than "::socket", +i.e. if the script or the Tcl installation has replaced the value "::socket" +with the name of a different command, then http does not change the value. +The script or installation that modified \fB::tls::socketCmd\fR is responsible +for integrating \fB::http::socket\fR into its own replacement command. +.PP +.SS "WITH A CHILD INTERPRETER" +.PP +The peer thread can transfer the socket only to the main interpreter of the +script's thread. Therefore the thread-based \fB::http::socket\fR works with +non-zero \fI\-threadlevel\fR values only if the script runs in the main +interpreter. A child interpreter must use \fI\-threadlevel 0\fR unless the +parent interpreter has provided alternative facilities. The main parent +interpreter may grant full \fI\-threadlevel\fR facilities to a child +interpreter, for example by aliasing, to \fB::http::socket\fR in the child, +a command that runs \fBhttp::socket\fR in the parent, and then transfers +the socket to the child. +.PP .SH EXAMPLE .PP This example creates a procedure to copy a URL to a file while printing a -progress meter, and prints the meta-data associated with the URL. +progress meter, and prints the response headers associated with the URL. .PP .CS proc httpcopy { url file {chunk 4096} } { @@ -895,7 +1671,7 @@ proc httpcopy { url file {chunk 4096} } { # This ends the line started by httpCopyProgress puts stderr "" - upvar #0 $token state + upvar 0 $token state set max 0 foreach {name value} $state(meta) { if {[string length $name] > $max} { 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,100 @@ .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 \fBinterp\fR +\fIcommandName\fR was created by \fBinterp create\fR. +.IP \fBzlibStream\fR +\fIcommandName\fR was created by \fBzlib stream\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 +114,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 precompiled script (loadable by -the package \fBtbcload\fR), and no further information will be -available. +A precompiled 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 +218,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 +232,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 \fIinterp\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 +365,190 @@ 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 properties\fI class\fR ?\fIoptions...\fR +.VS "TIP 558" +This subcommand returns a sorted list of properties defined on the class named +\fIclass\fR. The \fIoptions\fR define exactly which properties are returned: +.RS +.TP +\fB\-all\fR +. +With this option, the properties from the superclasses and mixins of the class +are also returned. +.TP +\fB\-readable\fR +. +This option (the default behavior) asks for the readable properties to be +returned. Only readable or writable properties are returned, not both. +.TP +\fB\-writable\fR +. +This option asks for the writable properties to be returned. Only readable or +writable properties are returned, not both. +.RE +.VE "TIP 558" .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 +560,184 @@ 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 properties\fI object\fR ?\fIoptions...\fR +.VS "TIP 558" +This subcommand returns a sorted list of properties defined on the object +named \fIobject\fR. The \fIoptions\fR define exactly which properties are +returned: +.RS +.TP +\fB\-all\fR +. +With this option, the properties from the class, superclasses and mixins of +the object are also returned. +.TP +\fB\-readable\fR +. +This option (the default behavior) asks for the readable properties to be +returned. Only readable or writable properties are returned, not both. +.TP +\fB\-writable\fR +. +This option asks for the writable properties to be returned. Only readable or +writable properties are returned, not both. +.RE +.VE "TIP 558" +.TP +\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 +746,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 +768,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 +788,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 +814,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 +824,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 1127632..08bed1c 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 children. The @@ -371,17 +369,15 @@ Both interpreters must close it to close the underlying IO channel; IO channels accessible in an interpreter are automatically closed when an interpreter is destroyed. .TP -\fBinterp\fR \fBslaves\fR ?\fIpath\fR? +\fBinterp\fR \fBchildren\fR ?\fIpath\fR? . Returns a Tcl list of the names of all the child interpreters associated with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted, the invoking interpreter is used. -.VS "TIP 581" .TP -\fBinterp\fR \fBchildren\fR ?\fIpath\fR? +\fBinterp\fR \fBslaves\fR ?\fIpath\fR? . -Synonym for . \fBinterp\fR \fBslaves\fR ?\fIpath\fR? -.VE "TIP 581" +Synonym for . \fBinterp\fR \fBchildren\fR ?\fIpath\fR? .TP \fBinterp\fR \fBtarget\fR \fIpath alias\fR . @@ -399,7 +395,7 @@ The target command does not have to be defined at the time of this invocation. Causes the IO channel identified by \fIchannelId\fR to become available in the interpreter identified by \fIdestPath\fR and unavailable in the interpreter identified by \fIsrcPath\fR. -.SH "child COMMAND" +.SH "CHILD COMMAND" .PP For each child interpreter created with the \fBinterp\fR command, a new Tcl command is created in the parent interpreter with the same @@ -411,7 +407,7 @@ general form: \fIchild command \fR?\fIarg arg ...\fR? .CE .PP -\fIchild\fR is the name of the interpreter, and \fIcommand\fR +\fIChild\fR is the name of the interpreter, and \fIcommand\fR and the \fIarg\fRs determine the exact behavior of the command. The valid forms of this command are: .TP @@ -595,16 +591,16 @@ built-in commands: \fBflush\fR \fBfor\fR \fBforeach\fR \fBformat\fR \fBgets\fR \fBglobal\fR \fBif\fR \fBincr\fR \fBinfo\fR \fBinterp\fR \fBjoin\fR \fBlappend\fR -\fBlassign\fR \fBlindex\fR \fBlinsert\fR \fBlist\fR -\fBllength\fR \fBlrange\fR \fBlrepeat\fR \fBlreplace\fR -\fBlsearch\fR \fBlset\fR \fBlsort\fR \fBnamespace\fR -\fBpackage\fR \fBpid\fR \fBproc\fR \fBputs\fR -\fBread\fR \fBregexp\fR \fBregsub\fR \fBrename\fR -\fBreturn\fR \fBscan\fR \fBseek\fR \fBset\fR -\fBsplit\fR \fBstring\fR \fBsubst\fR \fBswitch\fR -\fBtell\fR \fBtime\fR \fBtrace\fR \fBunset\fR -\fBupdate\fR \fBuplevel\fR \fBupvar\fR \fBvariable\fR -\fBvwait\fR \fBwhile\fR +\fBlassign\fR \fBledit\fR \fBlindex\fR \fBlinsert\fR +\fBlist\fR \fBllength\fR \fBlrange\fR \fBlrepeat\fR +\fBlreplace\fR \fBlsearch\fR \fBlseq\fR \fBlset\fR +\fBlsort\fR \fBnamespace\fR \fBpackage\fR \fBpid\fR +\fBproc\fR \fBputs\fR \fBread\fR \fBregexp\fR +\fBregsub\fR \fBrename\fR \fBreturn\fR \fBscan\fR +\fBseek\fR \fBset\fR \fBsplit\fR \fBstring\fR +\fBsubst\fR \fBswitch\fR \fBtell\fR \fBtime\fR +\fBtrace\fR \fBunset\fR \fBupdate\fR \fBuplevel\fR +\fBupvar\fR \fBvariable\fR \fBvwait\fR \fBwhile\fR .DE The following commands are hidden by \fBinterp create\fR when it creates a safe interpreter: @@ -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..3fbda79 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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(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..d23509a 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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(n), lset(n), lsort(n) .SH KEYWORDS assign, element, list, multiple, set, variable '\"Local Variables: diff --git a/doc/ledit.n b/doc/ledit.n new file mode 100644 index 0000000..48bc608 --- /dev/null +++ b/doc/ledit.n @@ -0,0 +1,91 @@ +'\" +'\" Copyright (c) 2022 Ashok P. Nadkarni <apnmbx-public@yahoo.com>. 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 ledit n 8.7 Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +ledit \- Replace elements of a list stored in variable +.SH SYNOPSIS +\fBledit \fIlistVar first last \fR?\fIvalue value ...\fR? +.BE +.SH DESCRIPTION +.PP +The command fetches the list value in variable \fIlistVar\fR and replaces the +elements in the range given by indices \fIfirst\fR to \fIlast\fR (inclusive) +with the \fIvalue\fR arguments. The resulting list is then stored back in +\fIlistVar\fR and returned as the result of the command. +.PP +Arguments \fIfirst\fR and \fIlast\fR are index values specifying the first and +last elements of the range to replace. They 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. The index \fB0\fR refers to the first element of the +list, and \fBend\fR refers to the last element of the list. +.PP +If either \fIfirst\fR or \fIlast\fR is less than zero, it is considered to +refer to the position before the first element of the list. This allows +elements to be prepended. +.PP +If either \fIfirst\fR or \fIlast\fR indicates a position greater than the +index of the last element of the list, it is treated as if it is an +index one greater than the last element. This allows elements to be appended. +.PP +If \fIlast\fR is less than \fIfirst\fR, then any specified elements +will be inserted into the list before the element specified by \fIfirst\fR +with no elements being deleted. +.PP +The \fIvalue\fR arguments specify zero or more new elements to +be added to the list in place of those that were deleted. +Each \fIvalue\fR argument will become a separate element of +the list. If no \fIvalue\fR arguments are specified, then the elements +between \fIfirst\fR and \fIlast\fR are simply deleted. +.SH EXAMPLES +.PP +Prepend to a list. +.PP +.CS +set lst {c d e f g} + \fI\(-> c d e f g\fR +\fBledit\fR lst -1 -1 a b + \fI\(-> a b c d e f g\fR +.CE +.PP +Append to the list. +.PP +.CS +\fBledit\fR lst end+1 end+1 h i + \fI\(-> a b c d e f g h i\fR +.CE +.PP +Delete third and fourth elements. +.PP +.CS +\fBledit\fR lst 2 3 + \fI\(-> a b e f g h i\fR +.CE +.PP +Replace two elements with three. +.PP +.CS +\fBledit\fR lst 2 3 x y z + \fI\(-> a b x y z g h i\fR +set lst + \fI\(-> a b x y z g h i\fR +.CE +.PP +.SH "SEE ALSO" +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), lseq(n), lset(n), lsort(n), +string(n) +.SH KEYWORDS +element, list, replace +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/library.n b/doc/library.n index f14e8e0..0342cbe 100644 --- a/doc/library.n +++ b/doc/library.n @@ -25,6 +25,11 @@ auto_execok, auto_import, auto_load, auto_mkindex, auto_qualify, auto_reset, tcl \fBtcl_startOfPreviousWord \fIstr start\fR \fBtcl_wordBreakAfter \fIstr start\fR \fBtcl_wordBreakBefore \fIstr start\fR +.VS "Tcl 8.7, TIP 670" +\fBforeachLine \fIfilename varName body\fR +\fBreadFile \fIfilename\fR ?\fBtext\fR|\fBbinary\fR? +\fBwriteFile \fIfilename\fR ?\fBtext\fR|\fBbinary\fR? \fIcontents\fR +.VE "Tcl 8.7, TIP 670" .BE .SH INTRODUCTION .PP @@ -58,6 +63,7 @@ the auto-load mechanism defined below. The following procedures are provided in the Tcl library: .TP \fBauto_execok \fIcmd\fR +. Determines whether there is an executable file or shell builtin by the name \fIcmd\fR. If so, it returns a list of arguments to be passed to \fBexec\fR to execute the executable file or shell builtin @@ -70,8 +76,30 @@ remembers information about previous searches in an array named \fBauto_execs\fR; this avoids the path search in future calls for the same \fIcmd\fR. The command \fBauto_reset\fR may be used to force \fBauto_execok\fR to forget its cached information. +.RS +.PP +For example, to run the \fIumask\fR shell builtin on Linux, you would do: +.PP +.CS +exec {*}[\fBauto_execok\fR umask] +.CE +.PP +To run the \fIDIR\fR shell builtin on Windows, you would do: +.PP +.CS +exec {*}[\fBauto_execok\fR dir] +.CE +.PP +To discover if there is a \fIfrobnicate\fR binary on the user's PATH, +you would do: +.PP +.CS +set mayFrob [expr {[llength [\fBauto_execok\fR frobnicate]] > 0}] +.CE +.RE .TP \fBauto_import \fIpattern\fR +. \fBAuto_import\fR is invoked during \fBnamespace import\fR to see if the imported commands specified by \fIpattern\fR reside in an autoloaded library. If so, the commands are loaded so that they will @@ -79,13 +107,18 @@ be available to the interpreter for creating the import links. If the commands do not reside in an autoloaded library, \fBauto_import\fR does nothing. The pattern matching is performed according to the matching rules of \fBnamespace import\fR. +.RS +.PP +It is not normally necessary to call this command directly. +.RE .TP \fBauto_load \fIcmd\fR +. This command attempts to load the definition for a Tcl command named \fIcmd\fR. To do this, it searches an \fIauto-load path\fR, which is a list of one or more directories. The auto-load path is given by the global variable \fBauto_path\fR if it exists. If there is no -\fBauto_path\fR variable, then the TCLLIBPATH environment variable is +\fBauto_path\fR variable, then the \fBTCLLIBPATH\fR environment variable is used, if it exists. Otherwise the auto-load path consists of just the Tcl library directory. Within each directory in the auto-load path there must be a file \fBtclIndex\fR that describes one or more @@ -104,6 +137,11 @@ the array \fBauto_index\fR; future calls to \fBauto_load\fR check for cached index information may be deleted with the command \fBauto_reset\fR. This will force the next \fBauto_load\fR command to reload the index database from disk. +.RS +.PP +It is not normally necessary to call this command directly; the +default \fBunknown\fR handler will do so. +.RE .TP \fBauto_mkindex \fIdir pattern pattern ...\fR . @@ -156,6 +194,7 @@ listed in the auto-load index, so that fresh copies of them will be loaded the next time that they are used. .TP \fBauto_qualify \fIcommand namespace\fR +. Computes a list of fully qualified names for \fIcommand\fR. This list mirrors the path a standard Tcl interpreter follows for command lookups: first it looks for the command in the current namespace, and @@ -175,6 +214,7 @@ performing the actual auto-loading of functions at runtime. .RE .TP \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR +. This is a standard search procedure for use by extensions during their initialization. They call this procedure to look for their script library in several standard directories. @@ -197,17 +237,28 @@ relative to the executable file in the current build tree; relative to the executable file in a parallel build tree. .TP \fBparray \fIarrayName\fR ?\fIpattern\fR? +. Prints on standard output the names and values of all the elements in the array \fIarrayName\fR, or just the names that match \fIpattern\fR (using the matching rules of \fBstring match\fR) and their values if \fIpattern\fR is given. \fIArrayName\fR must be an array accessible to the caller of \fBparray\fR. It may be either local or global. +The result of this command is the empty string. +.RS +.PP +For example, to print the contents of the \fBtcl_platform\fR array, do: +.PP +.CS +\fBparray\fR tcl_platform +.CE +.RE .SS "WORD BOUNDARY HELPERS" .PP These procedures are mainly used internally by Tk. .TP \fBtcl_endOfWord \fIstr start\fR +. Returns the index of the first end-of-word location that occurs after a starting index \fIstart\fR in the string \fIstr\fR. An end-of-word location is defined to be the first non-word character following the @@ -218,19 +269,35 @@ for more details on how Tcl determines which characters are word characters. .TP \fBtcl_startOfNextWord \fIstr start\fR +. Returns the index of the first start-of-word location that occurs after a starting index \fIstart\fR in the string \fIstr\fR. A start-of-word location is defined to be the first word character following a non-word character. Returns \-1 if there are no more start-of-word locations after the starting point. +.RS +.PP +For example, to print the indices of the starts of each word in a +string according to platform rules: +.PP +.CS +set theString "The quick brown fox" +for {set idx 0} {$idx >= 0} { + set idx [\fBtcl_startOfNextWord\fR $theString $idx]} { + puts "Word start index: $idx" +} +.CE +.RE .TP \fBtcl_startOfPreviousWord \fIstr start\fR +. Returns the index of the first start-of-word location that occurs before a starting index \fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more start-of-word locations before the starting point. .TP \fBtcl_wordBreakAfter \fIstr start\fR +. Returns the index of the first word boundary after the starting index \fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more boundaries after the starting point in the given string. The index @@ -238,11 +305,47 @@ returned refers to the second character of the pair that comprises a boundary. .TP \fBtcl_wordBreakBefore \fIstr start\fR +. Returns the index of the first word boundary before the starting index \fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more boundaries before the starting point in the given string. The index returned refers to the second character of the pair that comprises a boundary. +.TP +\fBforeachLine \fIvarName filename body\fR +.VS "Tcl 8.7, TIP 670" +This reads in the text file named \fIfilename\fR one line at a time +(using system defaults for reading text files). It writes that line to the +variable named by \fIvarName\fR and then executes \fIbody\fR for that line. +The result value of \fIbody\fR is ignored, but \fBerror\fR, \fBreturn\fR, +\fBbreak\fR and \fBcontinue\fR may be used within it to produce an error, +return from the calling context, stop the loop, or go to the next line +respectively. +The overall result of \fBforeachLine\fR is the empty string (assuming no +errors from I/O or from evaluating the body of the loop); the file will be +closed prior to the procedure returning. +.VE "Tcl 8.7, TIP 670" +.TP +\fBreadFile \fIfilename\fR ?\fBtext\fR|\fBbinary\fR? +.VS "Tcl 8.7, TIP 670" +Reads in the file named in \fIfilename\fR and returns its contents. +The second argument says how to read in the file, either as \fBtext\fR +(using the system defaults for reading text files) or as \fBbinary\fR +(as uninterpreted bytes). The default is \fBtext\fR. When read as text, this +will include any trailing newline. +The file will be closed prior to the procedure returning. +.VE "Tcl 8.7, TIP 670" +.TP +\fBwriteFile \fIfilename\fR ?\fBtext\fR|\fBbinary\fR? \fIcontents\fR +.VS "Tcl 8.7, TIP 670" +Writes the \fIcontents\fR to the file named in \fIfilename\fR. +The optional second argument says how to write to the file, either as +\fBtext\fR (using the system defaults for writing text files) or as +\fBbinary\fR (as uninterpreted bytes). The default is \fBtext\fR. +If a trailing newline is required, it will need to be provided in +\fIcontents\fR. The result of this command is the empty string; the file will +be closed prior to the procedure returning. +.VE "Tcl 8.7, TIP 670" .SH "VARIABLES" .PP The following global variables are defined or used by the procedures in @@ -251,18 +354,30 @@ commands and packages, and determining what are words. .SS "AUTOLOADING AND PACKAGE MANAGEMENT VARIABLES" .TP \fBauto_execs\fR +. Used by \fBauto_execok\fR to record information about whether particular commands exist as executable files. +.RS +.PP +Not normally usefully accessed directly by user code. +.RE .TP \fBauto_index\fR +. Used by \fBauto_load\fR to save the index information read from disk. +.RS +.PP +Not normally usefully accessed directly by user code. +.RE .TP \fBauto_noexec\fR +. If set to any value, then \fBunknown\fR will not attempt to auto-exec any commands. .TP \fBauto_noload\fR +. If set to any value, then \fBunknown\fR will not attempt to auto-load any commands. .TP @@ -278,42 +393,70 @@ the parent directory of \fBtcl_library\fR, the directories listed in the \fBtcl_pkgPath\fR variable. Additional locations to look for files and package indices should normally be added to this variable using \fBlappend\fR. +.RS +.PP +For example, to add the \fIlib\fR directory next to the running +script, you would do: +.PP +.CS +lappend \fBauto_path\fR [file dirname [info script]]/lib +.CE +.PP +Note that if the script uses \fBcd\fR, it is advisable to ensure that +entries on the \fBauto_path\fR are \fBfile normalize\fRd. +.RE .TP \fBenv(TCL_LIBRARY)\fR +. If set, then it specifies the location of the directory containing library scripts (the value of this variable will be assigned to the \fBtcl_library\fR variable and therefore returned by the command \fBinfo library\fR). If this variable is not set then a default value is used. +.RS +.PP +Use of this environment variable is not recommended outside of testing. +Tcl installations should already know where to find their own script +files, as the value is baked in during the build or installation. +.RE .TP \fBenv(TCLLIBPATH)\fR +. If set, then it must contain a valid Tcl list giving directories to search during auto-load operations. Directories must be specified in Tcl format, using .QW / as the path separator, regardless of platform. This variable is only used when initializing the \fBauto_path\fR variable. +.RS +.PP +A key consequence of this variable is that it gives a way to let the user +of a script specify the list of places where that script may use +\fBpackage require\fR to read packages from. It is not normally usefully +settable within a Tcl script itself \fIexcept\fR to influence where other +interpreters load from (whether made with \fBinterp create\fR or launched +as their own threads or subprocesses). +.RE .SS "WORD BOUNDARY DETERMINATION VARIABLES" These variables are only used in the \fBtcl_endOfWord\fR, \fBtcl_startOfNextWord\fR, \fBtcl_startOfPreviousWord\fR, \fBtcl_wordBreakAfter\fR, and \fBtcl_wordBreakBefore\fR commands. .TP \fBtcl_nonwordchars\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 value is +.QW "\\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 value is +.QW "\\w" . .SH "SEE ALSO" env(n), info(n), re_syntax(n) .SH KEYWORDS diff --git a/doc/lindex.n b/doc/lindex.n index 5b04b26..d4d845d 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), ledit(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(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..a11c261 --- /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 tcl::oo + +\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 accessible 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..014f9cd 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), ledit(n), lindex(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(n), lset(n), lsort(n) .SH KEYWORDS element, list, quoting '\"Local Variables: diff --git a/doc/llength.n b/doc/llength.n index 79f93c0..574834f 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), ledit(n), lindex(n), linsert(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(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), ledit(n), lindex(n), linsert(n), llength(n), +lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(n), lset(n), lsort(n) .SH KEYWORDS foreach, iteration, list, loop, map '\" Local Variables: @@ -56,7 +56,7 @@ on Safe\-Tcl, see the \fBsafe\fR manual entry. The initialization procedure must match the following prototype: .PP .CS -typedef int \fBTcl_PackageInitProc\fR( +typedef int \fBTcl_LibraryInitProc\fR( Tcl_Interp *\fIinterp\fR); .CE .PP @@ -79,7 +79,7 @@ Tcl's unloading mechanism. .PP The \fBload\fR command also supports libraries that are statically linked with the application, if those libraries have been registered -by calling the \fBTcl_StaticPackage\fR procedure. +by calling the \fBTcl_StaticLibrary\fR procedure. If \fIfileName\fR is an empty string, then \fIprefix\fR must be specified. .PP @@ -88,7 +88,8 @@ Tcl tries to guess the prefix. This may be done differently on different platforms. The default guess, which is used on most UNIX platforms, is to take the last element of \fIfileName\fR, strip off the first three characters if they -are \fBlib\fR, and use any following alphabetic and +are \fBlib\fR, then strip off the next three characters if they +are \fBtcl\fR, and use any following alphabetic and underline characters, converted to titlecase as the prefix. For example, the command \fBload libxyz4.2.so\fR uses the prefix \fBXyz\fR and the command \fBload bin/last.so {}\fR uses the @@ -97,7 +98,7 @@ prefix \fBLast\fR. If \fIfileName\fR is an empty string, then \fIprefix\fR must be specified. The \fBload\fR command first searches for a statically loaded library -(one that has been registered by calling the \fBTcl_StaticPackage\fR +(one that has been registered by calling the \fBTcl_StaticLibrary\fR procedure) by that name; if one is found, it is used. Otherwise, the \fBload\fR command searches for a dynamically loaded library by that name, and uses it if it is found. If several @@ -187,7 +188,7 @@ switch $tcl_platform(platform) { foo .CE .SH "SEE ALSO" -info sharedlibextension, package(n), Tcl_StaticPackage(3), safe(n) +info sharedlibextension, package(n), Tcl_StaticLibrary(3), safe(n) .SH KEYWORDS binary code, dynamic library, load, safe interpreter, shared library '\"Local Variables: diff --git a/doc/lpop.n b/doc/lpop.n new file mode 100644 index 0000000..2a464eb --- /dev/null +++ b/doc/lpop.n @@ -0,0 +1,97 @@ +'\" +'\" Copyright (c) 2018 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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(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..38c4abf 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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(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..bd4a5eb --- /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 arbitrary 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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(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 52a17f0..cd672db 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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lreplace(n), +lreverse(n), lsearch(n), lseq(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..47d33f9 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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), +lreverse(n), lsearch(n), lseq(n), lset(n), lsort(n), string(n) .SH KEYWORDS element, list, replace diff --git a/doc/lreverse.n b/doc/lreverse.n index a2a02a5..bb0703d 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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lsearch(n), lseq(n), lset(n), lsort(n) .SH KEYWORDS element, list, reverse '\" Local Variables: diff --git a/doc/lsearch.n b/doc/lsearch.n index efe1792..dc6d1f7 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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lseq(n), lset(n), lsort(n), string(n) .SH KEYWORDS binary search, linear search, diff --git a/doc/lseq.n b/doc/lseq.n new file mode 100644 index 0000000..08be86f --- /dev/null +++ b/doc/lseq.n @@ -0,0 +1,99 @@ +'\" +'\" Copyright (c) 2022 Eric Taylor. 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 lseq n 8.7 Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +lseq \- Build a numeric sequence returned as a list +.SH SYNOPSIS +\fBlseq \fIstart \fR?(\fB..\fR|\fBto\fR)? \fIend\fR ??\fBby\fR? \fIstep\fR? + +\fBlseq \fIstart \fBcount\fR \fIcount\fR ??\fBby\fR? \fIstep\fR? + +\fBlseq \fIcount\fR ?\fBby \fIstep\fR? +.BE +.SH DESCRIPTION +.PP +The \fBlseq\fR command creates a sequence of numeric values using the given +parameters \fIstart\fR, \fIend\fR, and \fIstep\fR. +The \fIoperation\fR argument +.QW \fB..\fR +or +.QW \fBto\fR +defines an inclusive range; if it is omitted, the range is exclusive. +The \fBcount\fR option is used to define a count of the number of elements in +the list. +The \fIstep\fR (which may be preceded by \fBby\fR) is 1 if not provided. +The short form with a +single \fIcount\fR value will create a range from 0 to \fIcount\fR-1 (i.e., +\fIcount\fR values). +.PP +The numeric arguments, \fIstart\fR, \fIend\fR, \fIstep\fR, and \fIcount\fR, +can also be a valid expression. the \fBlseq\fR command will evaluate the +expression (as if with \fBexpr\fR) +and use the numeric result, or return an error as with any invalid argument +value; a non-numeric expression result will result in an error. + +.SH EXAMPLES +.CS +.\" +\fBlseq\fR 3 + \fI\(-> 0 1 2\fR + +\fBlseq\fR 3 0 + \fI\(-> 3 2 1 0\fR + +\fBlseq\fR 10 .. 1 by -2 + \fI\(-> 10 8 6 4 2\fR + +set l [\fBlseq\fR 0 -5] + \fI\(-> 0 -1 -2 -3 -4 -5\fR + +foreach i [\fBlseq\fR [llength $l]] { + puts l($i)=[lindex $l $i] +} + \fI\(-> l(0)=0\fR + \fI\(-> l(1)=-1\fR + \fI\(-> l(2)=-2\fR + \fI\(-> l(3)=-3\fR + \fI\(-> l(4)=-4\fR + \fI\(-> l(5)=-5\fR + +foreach i [\fBlseq\fR {[llength $l]-1} 0] { + puts l($i)=[lindex $l $i] +} + \fI\(-> l(5)=-5\fR + \fI\(-> l(4)=-4\fR + \fI\(-> l(3)=-3\fR + \fI\(-> l(2)=-2\fR + \fI\(-> l(1)=-1\fR + \fI\(-> l(0)=0\fR + +set i 17 + \fI\(-> 17\fR +if {$i in [\fBlseq\fR 0 50]} { # equivalent to: (0 <= $i && $i < 50) + puts "Ok" +} else { + puts "outside :(" +} + \fI\(-> Ok\fR + +set sqrs [lmap i [\fBlseq\fR 1 10] { expr {$i*$i} }] + \fI\(-> 1 4 9 16 25 36 49 64 81 100\fR +.\" +.CE +.SH "SEE ALSO" +foreach(n), list(n), lappend(n), lassign(n), ledit(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: @@ -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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(n), lsort(n) string(n) .SH KEYWORDS element, index, list, replace, set diff --git a/doc/lsort.n b/doc/lsort.n index c3245b2..1695ea8 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), ledit(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n), +lreverse(n), lsearch(n), lseq(n), lset(n) .SH KEYWORDS element, list, order, sort '\" Local Variables: diff --git a/doc/mathfunc.n b/doc/mathfunc.n index 7a16961..004b7e3 100644 --- a/doc/mathfunc.n +++ b/doc/mathfunc.n @@ -13,7 +13,7 @@ .SH NAME mathfunc \- Mathematical functions for Tcl expressions .SH SYNOPSIS -package require \fBTcl 8.5\fR +package require \fBTcl 8.5-\fR .sp \fB::tcl::mathfunc::abs\fR \fIarg\fR .br @@ -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 \(co 1993 The Regents of the University of California. Copyright \(co 1994-2000 Sun Microsystems Incorporated. -Copyright \(co 2005, 2006 Kevin B. Kenny <kennykb@acm.org>. +Copyright \(co 2005-2006 Kevin B. Kenny <kennykb@acm.org>. .fi '\" Local Variables: '\" mode: nroff diff --git a/doc/mathop.n b/doc/mathop.n index 84cf308..3a13456 100644 --- a/doc/mathop.n +++ b/doc/mathop.n @@ -11,7 +11,7 @@ .SH NAME mathop \- Mathematical operators as Tcl commands .SH SYNOPSIS -package require \fBTcl 8.5\fR +package require \fBTcl 8.5-\fR .sp \fB::tcl::mathop::!\fR \fInumber\fR .br @@ -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 9d7291a..c39dc87 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 @@ -63,7 +73,7 @@ the application source code. New languages or locales may be provided by adding a new file to the message catalog. .PP -\fBmsgcat\fR distinguises packages by its namespace. +\fBmsgcat\fR distinguishes packages by its namespace. Each package has its own message catalog and configuration settings in \fBmsgcat\fR. .PP A \fIlocale\fR is a specification string describing a user language like \fBde_ch\fR for Swiss German. @@ -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,25 +198,33 @@ 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? . This group of commands manage the list of loaded locales for packages not setting a package locale. .PP .RS -The subcommand \fBget\fR returns the list of currently loaded locales. -.PP -The subcommand \fBpresent\fR requires the argument \fIlocale\fR and returns true, if this locale is loaded. +The subcommand \fBloaded\fR returns the list of currently loaded locales. .PP The subcommand \fBclear\fR removes all locales and their data, which are not in the current preference list. .RE @@ -159,7 +233,7 @@ The subcommand \fBclear\fR removes all locales and their data, which are not in . .VS "TIP 412" Searches the specified directory for files that match -the language specifications returned by \fB::msgcat::mcloadedlocales get\fR +the language specifications returned by \fB::msgcat::mcloadedlocales loaded\fR (or \fBmsgcat::mcpackagelocale preferences\fR if a package locale is set) (note that these are all lowercase), extended by the file extension .QW .msg . Each matching file is @@ -232,6 +306,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 +527,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 +551,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 +590,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 +665,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 +679,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 +792,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 +package require tcl::oo \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 120c0a3..4be0a3a 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 @@ -12,7 +12,7 @@ next, nextto \- invoke superclass method implementations .SH SYNOPSIS .nf -package require TclOO +package require tcl::oo \fBnext\fR ?\fIarg ...\fR? \fBnextto\fI class\fR ?\fIarg ...\fR? @@ -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}] diff --git a/doc/object.n b/doc/object.n index df657a9..98679d1 100644 --- a/doc/object.n +++ b/doc/object.n @@ -12,7 +12,7 @@ oo::object \- root class of the class hierarchy .SH SYNOPSIS .nf -package require TclOO +package require tcl::oo \fBoo::object\fI method \fR?\fIarg ...\fR? .fi @@ -128,6 +128,28 @@ If a new file is created as part of opening it, \fIpermissions\fR (an integer) is used to set the permissions for the new file in conjunction with the process's file mode creation mask. \fIPermissions\fR defaults to 0666. +.PP +.VS "8.7, TIP 603" +When the file opened is an ordinary disk file, the \fBchan configure\fR and +\fBfconfigure\fR commands can be used to query this additional configuration +option: +.TP +\fB\-stat\fR +. +This option, when read, returns a dictionary of values much as is obtained +from the \fBfile stat\fR command, where that stat information relates to the +real opened file. Keys in the dictionary may include \fBatime\fR, \fBctime\fR, +\fBdev\fR, \fBgid\fR, \fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR, +\fBsize\fR, \fBtype\fR, and \fBuid\fR among others; the \fBmtime\fR, +\fBsize\fR and \fBtype\fR fields are guaranteed to be present and meaningful +on all platforms; other keys may be present too. +.RS +.PP +\fIImplementation note:\fR This option maps to a call to \fBfstat()\fR on +POSIX platforms, and to a call to \fBGetFileInformationByHandle()\fR on +Windows; the information reported is what those system calls produce. +.RE +.VE "8.7, TIP 603" .SH "COMMAND PIPELINES" .PP If the first character of \fIfileName\fR is @@ -166,8 +188,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 +272,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 +367,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 +408,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 +451,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 . @@ -414,6 +506,54 @@ 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 "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" Open a file for writing, forcing it to be created and raising an error if it already exists. @@ -429,7 +569,6 @@ set myLogFile [\fBopen\fR filename.log "a"] fconfigure $myLogFile -buffering line .CE .PP -.PP Open a command pipeline and catch any errors: .PP .CS @@ -451,6 +590,22 @@ set fl [\fBopen\fR |[list create_image_data $input] "rb"] set binData [read $fl] close $fl .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 bce22fe..d55151f 100644 --- a/doc/packagens.n +++ b/doc/packagens.n @@ -29,7 +29,7 @@ This parameter specifies the name of the package. It is required. This parameter specifies the version of the package. It is required. .TP \fB\-load \fIfilespec\fR -This parameter specifies a binary library that must be loaded with the +This parameter specifies a library that must be loaded with the \fBload\fR command. \fIfilespec\fR is a list with two elements. The first element is the name of the file to load. The second, optional element is a list of commands supplied by loading that file. If the @@ -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: @@ -62,6 +62,12 @@ To avoid wasting memory, nonblocking I/O should normally be used in an event-driven fashion with the \fBfileevent\fR command (do not invoke \fBputs\fR unless you have recently been notified via a file event that the channel is ready for more output data). +.SH "ENCODING ERRORS" +.PP +Encoding errors may exist, if the encoding profile \fBstrict\fR is used. +\fBputs\fR writes out data until an encoding error occurs and fails with +POSIX error code \fBEILSEQ\fR. + .SH EXAMPLES .PP Write a short message to the console (or wherever \fBstdout\fR is @@ -96,3 +102,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: @@ -50,6 +50,79 @@ newline characters according to the \fB\-translation\fR option for the channel. See the \fBfconfigure\fR manual entry for a discussion on ways in which \fBfconfigure\fR will alter input. +.SH "ENCODING ERRORS" +.PP +Encoding errors may exist, if the encoding profile \fBstrict\fR is used. +Encoding errors are special, as an eventual introspection or recovery is +possible by changing to an encoding (or encoding profile), which accepts +the data. +An encoding error is reported by the POSIX error code \fBEILSEQ\fR. +.PP +In blocking mode, the error is directly thrown, even, if there is a +leading decodable data portion. +The file pointer is advanced just before the encoding error. +An eventual well decoded data chunk before the encoding error is returned +in the error option dictionary key \fB-data\fR. +The value of the key contains the empty string, if the error arises at the +first data position. +.PP +In non blocking mode, first, any data without encoding error is returned +(without error state). +In the next call, no data is returned and the \fBEILSEQ\fR error state is set. +The key \fB-data\fR is not present. +.PP +Here is an example with an encoding error in UTF-8 encoding, which is then +introspected by a switch to the binary encoding. The test file contains a not +continued multi-byte sequence at position 1 (\fBA \\xC3 B\fR): +.PP +File creation for examples +. +.CS +% set f [open test_A_195_B.txt wb]; puts -nonewline $f A\\xC3B; close $f +.CE +Blocking example +. +.CS +% set f [open test_A_195_B.txt r] +file35a65a0 +% fconfigure $f -encoding utf-8 -profile strict -blocking 1 +% catch {read $f} e d +1 +% set d +-data A -code 1 -level 0 +-errorstack {INNER {invokeStk1 read file35a65a0}} +-errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}} +-errorinfo {...} -errorline 1 +% tell $f +1 +% fconfigure $f -encoding binary -profile strict +% read $f +ÃB +% close $f +.CE +The already decoded data "A" is returned in the error options dictionary key +\fB-data\fR. +The file position is advanced on the encoding error position 1. +The data at the error position is thus recovered by the next \fBread\fR command. +.PP +Non blocking example +. +.CS +% set f [open test_A_195_B.txt r] +file35a65a0 +% fconfigure $f -encoding utf-8 -profile strict -blocking 0 +% read $f +A +% tell $f +1 +% catch {read $f} e d +1 +% set d +-code 1 -level 0 +-errorstack {INNER {invokeStk1 read file384b228}} +-errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}} +-errorinfo {...} -errorline 1 +.CE .SH "USE WITH SERIAL PORTS" '\" Note: this advice actually applies to many versions of Tcl .PP diff --git a/doc/refchan.n b/doc/refchan.n index edc9974..94823c5 100644 --- a/doc/refchan.n +++ b/doc/refchan.n @@ -11,7 +11,20 @@ .SH NAME refchan \- command handler API of reflected channels .SH SYNOPSIS -\fBcmdPrefix \fIoption\fR ?\fIarg arg ...\fR? +.nf +\fBchan create \fImode cmdPrefix\fR + +\fIcmdPrefix \fBblocking\fR \fIchannelId mode\fR +\fIcmdPrefix \fBcget\fR \fIchannelId option\fR +\fIcmdPrefix \fBcgetall\fR \fIchannelId\fR +\fIcmdPrefix \fBconfigure\fR \fIchannelId option value\fR +\fIcmdPrefix \fBfinalize\fR \fIchannelId\fR +\fIcmdPrefix \fBinitialize\fR \fIchannelId mode\fR +\fIcmdPrefix \fBread\fR \fIchannelId count\fR +\fIcmdPrefix \fBseek\fR \fIchannelId offset base\fR +\fIcmdPrefix \fBwatch\fR \fIchannelId eventspec\fR +\fIcmdPrefix \fBwrite\fR \fIchannelId data\fR +.fi .BE .SH DESCRIPTION .PP @@ -322,6 +335,19 @@ invocation (usually \fBfconfigure\fR or \fBchan configure\fR) will appear to have thrown this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.TP +\fIcmdPrefix \fBtruncate\fR \fIchannelId length\fR +. +This \fIoptional\fR subcommand handles changing the length of the +underlying data stream for the channel \fIchannelId\fR. Its length +gets set to \fIlength\fR. +.RS +.PP +If the subcommand throws an error the command which caused its +invocation (usually \fBchan truncate\fR) will appear to have thrown +this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, +etc.) is treated as and converted to an error. +.RE .SH NOTES Some of the functions supported in channels defined in Tcl's C interface are not available to channels reflected to the Tcl level. 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..cb8c2d4 100644 --- a/doc/regsub.n +++ b/doc/regsub.n @@ -54,6 +54,7 @@ backslashes. If the initial arguments to \fBregsub\fR start with \fB\-\fR then they are treated as switches. The following switches are currently supported: +.\" OPTION: -all .TP \fB\-all\fR . @@ -67,12 +68,42 @@ and .QW \e\fIn\fR sequences are handled for each substitution using the information from the corresponding match. +.\" OPTION: -command +.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 +.\" OPTION: -expanded .TP \fB\-expanded\fR . Enables use of the expanded regular expression syntax where whitespace and comments are ignored. This is the same as specifying the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page). +.\" OPTION: -line .TP \fB\-line\fR . @@ -90,6 +121,7 @@ matches an empty string before any newline in addition to its normal function. This flag is equivalent to specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page). +.\" OPTION: -linestop .TP \fB\-linestop\fR . @@ -100,6 +132,7 @@ bracket expressions and so that they stop at newlines. This is the same as specifying the \fB(?p)\fR embedded option (see the \fBre_syntax\fR manual page). +.\" OPTION: -lineanchor .TP \fB\-lineanchor\fR . @@ -113,14 +146,16 @@ so they match the beginning and end of a line respectively. This is the same as specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR manual page). +.\" OPTION: -nocase .TP \fB\-nocase\fR . Upper-case characters in \fIstring\fR will be converted to lower-case before matching against \fIexp\fR; however, substitutions specified by \fIsubSpec\fR use the original unconverted form of \fIstring\fR. +.\" OPTION: -start .TP -\fB\-start\fR \fIindex\fR +\fB\-start\fI index\fR . Specifies a character index offset into the string to start matching the regular expression at. @@ -131,6 +166,7 @@ When using this switch, will not match the beginning of the line, and \eA will still match the start of the string at \fIindex\fR. \fIindex\fR will be constrained to the bounds of the input string. +.\" OPTION: -- .TP \fB\-\|\-\fR . @@ -183,6 +219,62 @@ 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 +.PP +The \fB\-command\fR option can also be useful for restricting the range of +commands such as \fBstring totitle\fR: +.PP +.CS +set message "the quIck broWn fOX JUmped oVer the laZy dogS..." +puts [\fBregsub\fR -all -command {\ew+} $message {string totitle}] +# \(-> \fIThe Quick Brown Fox Jumped Over The Lazy Dogs..\fR +.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 . @@ -23,10 +23,13 @@ safe \- Creating and manipulating safe interpreters .sp \fB::safe::interpFindInAccessPath\fR \fIchild\fR \fIdirectory\fR .sp +\fB::safe::setSyncMode\fR ?\fInewValue\fR? +.sp \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? .SS OPTIONS .PP ?\fB\-accessPath\fR \fIpathList\fR? +?\fB\-autoPath\fR \fIpathList\fR? ?\fB\-statics\fR \fIboolean\fR? ?\fB\-noStatics\fR? ?\fB\-nested\fR \fIboolean\fR? ?\fB\-nestedLoadOk\fR? ?\fB\-deleteHook\fR \fIscript\fR? @@ -148,6 +151,15 @@ $child eval [list set tk_library \e .CE .RE .TP +\fB::safe::setSyncMode\fR ?\fInewValue\fR? +This command is used to get or set the "Sync Mode" of the Safe Base. +When an argument is supplied, the command returns an error if the argument +is not a boolean value, or if any Safe Base interpreters exist. Typically +the value will be set as part of initialization - boolean true for +"Sync Mode" on (the default), false for "Sync Mode" off. With "Sync Mode" +on, the Safe Base keeps each child interpreter's ::auto_path synchronized +with its access path. See the section \fBSYNC MODE\fR below for details. +.TP \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? This command installs a script that will be called when interesting life cycle events occur for a safe interpreter. @@ -199,6 +211,13 @@ parent for auto-loading. See the section \fBSECURITY\fR below for more detail about virtual paths, tokens and access control. .TP +\fB\-autoPath\fR \fIdirectoryList\fR +This option sets the list of directories in the safe interpreter's +::auto_path. The option is undefined if the Safe Base has "Sync Mode" on +- in that case the safe interpreter's ::auto_path is managed by the Safe +Base and is a tokenized form of its access path. +See the section \fBSYNC MODE\fR below for details. +.TP \fB\-statics\fR \fIboolean\fR This option specifies if the safe interpreter will be allowed to load statically linked packages (like \fBload {} Tk\fR). @@ -331,7 +350,8 @@ list will be assigned a token that will be set in the child \fBauto_path\fR and the first element of that list will be set as the \fBtcl_library\fR for that child. .PP -If the access path argument is not given or is the empty list, +If the access path argument is not given to \fB::safe::interpCreate\fR or +\fB::safe::interpInit\fR or is the empty list, the default behavior is to let the child access the same packages as the parent has access to (Or to be more precise: only packages written in Tcl (which by definition cannot be dangerous @@ -357,8 +377,152 @@ When the \fIaccessPath\fR is changed after the first creation or initialization (i.e. through \fBinterpConfigure -accessPath \fR\fIlist\fR), an \fBauto_reset\fR is automatically evaluated in the safe interpreter to synchronize its \fBauto_index\fR with the new token list. +.SH TYPICAL USE +In many cases, the properties of a Safe Base interpreter can be specified +when the interpreter is created, and then left unchanged for the lifetime +of the interpreter. +.PP +If you wish to use Safe Base interpreters with "Sync Mode" off, evaluate +the command +.RS +.PP +.CS + safe::setSyncMode 0 +.CE +.RE +.PP +Use \fB::safe::interpCreate\fR or \fB::safe::interpInit\fR to create an +interpreter with the properties that you require. The simplest way is not +to specify \fB\-accessPath\fR or \fB\-autoPath\fR, which means the safe +interpreter will use the same paths as the parent interpreter. However, +if \fB\-accessPath\fR is specified, then \fB\-autoPath\fR must also be +specified, or else it will be set to {}. +.PP +The value of \fB\-autoPath\fR will be that required to access tclIndex +and pkgIndex.tcl files according to the same rules as an unsafe +interpreter (see pkg_mkIndex(n) and library(n)). +.PP +With "Sync Mode" on, the option \fB\-autoPath\fR is undefined, and +the Safe Base sets the child's ::auto_path to a tokenized form of the +access path. In addition to the directories present if "Safe Mode" is off, +the ::auto_path includes the numerous subdirectories and module paths +that belong to the access path. +.SH SYNC MODE +Before Tcl version 8.7, the Safe Base kept each safe interpreter's +::auto_path synchronized with a tokenized form of its access path. +Limitations of Tcl 8.4 and earlier made this feature necessary. This +definition of ::auto_path did not conform its specification in library(n) +and pkg_mkIndex(n), but nevertheless worked perfectly well for the discovery +and loading of packages. The introduction of Tcl modules in Tcl 8.5 added a +large number of directories to the access path, and it is inconvenient to +have these additional directories unnecessarily appended to the ::auto_path. +.PP +In order to preserve compatibility with existing code, this synchronization +of the ::auto_path and access path ("Sync Mode" on) is still the default. +However, the Safe Base offers the option of limiting the safe interpreter's +::auto_path to the much shorter list of directories that is necessary for +it to perform its function ("Sync Mode" off). Use the command +\fB::safe::setSyncMode\fR to choose the mode before creating any Safe +Base interpreters. +.PP +In either mode, the most convenient way to initialize a safe interpreter is +to call \fB::safe::interpCreate\fR or \fB::safe::interpInit\fR without the +\fB\-accessPath\fR or \fB\-autoPath\fR options (or with the \fB\-accessPath\fR +option set to the +empty list), which will give the safe interpreter the same access as the +parent interpreter to packages, modules, and autoloader files. With +"Sync Mode" off, the Safe Base will set the value of \fB\-autoPath\fR to the +parent's ::auto_path, and will set the child's ::auto_path to a tokenized form +of the parent's ::auto_path. +.PP +With "Sync Mode" off, if a value is specified for \fB\-autoPath\fR, even the empty +list, in a call to \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, or +\fB::safe::interpConfigure\fR, it will be tokenized and used as the safe +interpreter's ::auto_path. Any directories that do not also belong to the +access path cannot be tokenized and will be silently ignored. However, the +value of \fB\-autoPath\fR will remain as specified, and will be used to +re-tokenize the child's ::auto_path if \fB::safe::interpConfigure\fR is called +to change the value of \fB\-accessPath\fR. +.PP +With "Sync Mode" off, if the access path is reset to the values in the +parent interpreter by calling \fB::safe::interpConfigure\fR with arguments +\fB\-accessPath\fR {}, then the ::auto_path will also be reset unless the argument +\fB\-autoPath\fR is supplied to specify a different value. +.PP +With "Sync Mode" off, if a non-empty value of \fB\-accessPath\fR is supplied, the +safe interpreter's ::auto_path will be set to {} (by +\fB::safe::interpCreate\fR, \fB::safe::interpInit\fR) or left unchanged +(by \fB::safe::interpConfigure\fR). If the same command specifies a new +value for \fB\-autoPath\fR, it will be applied after the \fB\-accessPath\fR argument has +been processed. + +Examples of use with "Sync Mode" off: any of these commands will set the +::auto_path to a tokenized form of its value in the parent interpreter: +.RS +.PP +.CS + safe::interpCreate foo + safe::interpCreate foo -accessPath {} + safe::interpInit bar + safe::interpInit bar -accessPath {} + safe::interpConfigure foo -accessPath {} +.CE +.RE +.PP +Example of use with "Sync Mode" off: when initializing a safe interpreter +with a non-empty access path, the ::auto_path will be set to {} unless its +own value is also specified: +.RS +.PP +.CS + safe::interpCreate foo -accessPath { + /usr/local/TclHome/lib/tcl8.6 + /usr/local/TclHome/lib/tcl8.6/http1.0 + /usr/local/TclHome/lib/tcl8.6/opt0.4 + /usr/local/TclHome/lib/tcl8.6/msgs + /usr/local/TclHome/lib/tcl8.6/encoding + /usr/local/TclHome/lib + } + + # The child's ::auto_path must be given a suitable value: + + safe::interpConfigure foo -autoPath { + /usr/local/TclHome/lib/tcl8.6 + /usr/local/TclHome/lib + } + + # The two commands can be combined: + + safe::interpCreate foo -accessPath { + /usr/local/TclHome/lib/tcl8.6 + /usr/local/TclHome/lib/tcl8.6/http1.0 + /usr/local/TclHome/lib/tcl8.6/opt0.4 + /usr/local/TclHome/lib/tcl8.6/msgs + /usr/local/TclHome/lib/tcl8.6/encoding + /usr/local/TclHome/lib + } -autoPath { + /usr/local/TclHome/lib/tcl8.6 + /usr/local/TclHome/lib + } +.CE +.RE +.PP +Example of use with "Sync Mode" off: the command +\fBsafe::interpAddToAccessPath\fR does not change the safe interpreter's +::auto_path, and so any necessary change must be made by the script: +.RS +.PP +.CS + safe::interpAddToAccessPath foo /usr/local/TclHome/lib/extras/Img1.4.11 + + lassign [safe::interpConfigure foo -autoPath] DUM childAutoPath + lappend childAutoPath /usr/local/TclHome/lib/extras/Img1.4.11 + safe::interpConfigure foo -autoPath $childAutoPath +.CE +.RE .SH "SEE ALSO" -interp(n), library(n), load(n), package(n), source(n), unknown(n) +interp(n), library(n), load(n), package(n), pkg_mkIndex(n), source(n), +tm(n), unknown(n) .SH KEYWORDS alias, auto\-loading, auto_mkindex, load, parent interpreter, safe interpreter, child interpreter, source @@ -12,7 +12,7 @@ self \- method call internal introspection .SH SYNOPSIS .nf -package require TclOO +package require tcl::oo \fBself\fR ?\fIsubcommand\fR? .fi @@ -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..3ccbdd3 --- /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 tcl::oo + +\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 aa25bd4..b7b3228 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 @@ -152,7 +162,8 @@ described below. .SH "CONFIGURATION OPTIONS" .PP The \fBchan configure\fR command can be used to query several readonly -configuration options for socket channels: +configuration options for socket channels or in some cases to set +alternative properties on socket channels: .TP \fB\-error\fR . @@ -194,6 +205,16 @@ list is identical to the address, its first element. \fB\-connecting\fR . This option is not supported by server sockets. For client sockets, this option returns 1 if an asyncroneous connect is still in progress, 0 otherwise. +.TP +\fB\-keepalive\fR +. +This option sets or queries the TCP keepalive option on the socket as 1 if +keepalive is turned on, 0 otherwise. +.TP +\fB\-nodelay\fR +. +This option sets or queries the TCP nodelay option on the socket as 1 if +nodelay is turned on, 0 otherwise. .PP .SH "EXAMPLES" .PP diff --git a/doc/source.n b/doc/source.n index d306765..0364c41 100644 --- a/doc/source.n +++ b/doc/source.n @@ -37,17 +37,15 @@ allowing for files containing code and data segments (scripted documents). If you require a .QW ^Z in code for string comparison, you can use -.QW \e032 -or -.QW \eu001a , +.QW \ex1A , 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 -is omitted, the system encoding is assumed. +is omitted, the utf-8 encoding is assumed. .SH EXAMPLE .PP Run the script in the file \fBfoo.tcl\fR and then the script in the @@ -69,3 +67,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 2d53a98..aefe485 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 @@ -376,7 +405,7 @@ Formally, the \fBstring bytelength\fR operation returns the content of the \fIlength\fR field of the \fBTcl_Obj\fR structure, after calling \fBTcl_GetString\fR to ensure that the \fIbytes\fR field is populated. This is highly unlikely to be useful to Tcl scripts, as Tcl's internal -encoding is not strict UTF\-8, but rather a modified CESU\-8 with a +encoding is not strict UTF\-8, but rather a modified WTF\-8 with a denormalized NUL (identical to that used in a number of places by Java's serialization mechanism) to enable basic processing with non-Unicode-aware C functions. As this representation should only @@ -385,10 +414,10 @@ store the representation is of very low value (except to C extension code, which has direct access for the purpose of memory management, etc.) .PP -\fICompatibility note:\fR it is likely that this subcommand will be -withdrawn in a future version of Tcl. It is better to use the -\fBencoding convertto\fR command to convert a string to a known -encoding and then apply \fBstring length\fR to that. +\fICompatibility note:\fR This subcommand is deprecated and will +be removed in Tcl 9.0. It is better to use the \fBencoding convertto\fR +command to convert a string to a known encoding (e.g. "utf-8" or "cesu-8") +and then apply \fBstring length\fR to that. .PP .CS \fBstring length\fR [encoding convertto utf-8 $theString] @@ -477,7 +506,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 fa0ecc2..3a78737 100644 --- a/doc/tclsh.1 +++ b/doc/tclsh.1 @@ -38,15 +38,11 @@ read Tcl commands from the named file; \fBtclsh\fR will exit when it reaches the end of the file. The end of the file may be marked either by the physical end of the medium, or by the character, -.QW \e032 -.PQ \eu001a ", control-Z" . +.PQ \ex1A ", control-Z" . If this character is present in the file, the \fBtclsh\fR application will read text up to but not including the character. An application that requires this character in the file may safely encode it as -.QW \e032 , -.QW \ex1A , -or -.QW \eu001a ; +.QW \ex1A ; or may generate it by use of commands such as \fBformat\fR or \fBbinary\fR. There is no automatic evaluation of \fB.tclshrc\fR when the name of a script file is presented on the \fBtclsh\fR command @@ -143,6 +139,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/tcltest.n b/doc/tcltest.n index 1a5151a..965ed64 100644 --- a/doc/tcltest.n +++ b/doc/tcltest.n @@ -1179,7 +1179,6 @@ Here is a sketch of a sample test suite main script: .RS .PP .CS -package require Tcl 8.6 package require tcltest 2.5 package require example \fB::tcltest::configure\fR -testdir \e 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/timerate.n b/doc/timerate.n index c5fdf30..5d49c86 100644 --- a/doc/timerate.n +++ b/doc/timerate.n @@ -35,10 +35,10 @@ if \fItime\fR is not specified. .sp The parameter \fImax-count\fR could additionally impose a further restriction by the maximal number of iterations to evaluate the script. -If \fImax-count\fR is specified, the evalution will stop either this count of +If \fImax-count\fR is specified, the evaluation will stop either this count of iterations is reached or the time is exceeded. .sp -It will then return a canonical tcl-list of the form: +It will then return a canonical Tcl-list of the form: .PP .CS \fB0.095977 \(mcs/# 52095836 # 10419167 #/sec 5000.000 net-ms\fR @@ -85,7 +85,7 @@ used to measure the cost of \fBTcl_EvalObjEx\fR, of the invocation of canonical lists, and of the uncompiled versions of bytecoded commands. .PP As opposed to the \fBtime\fR commmand, which runs the tested script for a fixed -number of iterations, the timerate command runs it for a fixed time. +number of iterations, the \fBtimerate\fR command runs it for a fixed time. Additionally, the compiled variant of the script will be used during the entire measurement, as if the script were part of a compiled procedure, if the \fB\-direct\fR option is not specified. The fixed time period and possibility of compilation allow diff --git a/doc/trace.n b/doc/trace.n index 5482e59..9b8fd57 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 @@ -237,7 +238,7 @@ if an entire array is being deleted and the trace was registered on the overall array, rather than a single element, then \fIname1\fR gives the array name and \fIname2\fR is an empty string. \fIName1\fR and \fIname2\fR are not necessarily the same as the -name used in the \fBtrace variable\fR command: the \fBupvar\fR +name used in the \fBtrace add variable\fR command: the \fBupvar\fR command allows a procedure to reference a variable under a different name. \fIOp\fR indicates what operation is being performed on the diff --git a/doc/transchan.n b/doc/transchan.n index 4da74f2..b9a0f21 100644 --- a/doc/transchan.n +++ b/doc/transchan.n @@ -11,7 +11,18 @@ .SH NAME transchan \- command handler API of channel transforms .SH SYNOPSIS -\fBcmdPrefix \fIoption\fR ?\fIarg arg ...\fR? +.nf +\fBchan push \fIchannelName cmdPrefix\fR + +\fIcmdPrefix \fBclear \fIhandle\fR +\fIcmdPrefix \fBdrain \fIhandle\fR +\fIcmdPrefix \fBfinalize \fIhandle\fR +\fIcmdPrefix \fBflush \fIhandle\fR +\fIcmdPrefix \fBinitialize \fIhandle mode\fR +\fIcmdPrefix \fBlimit? \fIhandle\fR +\fIcmdPrefix \fBread \fIhandle buffer\fR +\fIcmdPrefix \fBwrite \fIhandle buffer\fR +.fi .BE .SH DESCRIPTION .PP 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/unload.n b/doc/unload.n index 61caca1..00b709b 100644 --- a/doc/unload.n +++ b/doc/unload.n @@ -90,7 +90,7 @@ detached from the process. The unload procedure must match the following prototype: .PP .CS -typedef int \fBTcl_PackageUnloadProc\fR( +typedef int \fBTcl_LibraryUnloadProc\fR( Tcl_Interp *\fIinterp\fR, int \fIflags\fR); .CE @@ -122,7 +122,8 @@ Tcl tries to guess the prefix. This may be done differently on different platforms. The default guess, which is used on most UNIX platforms, is to take the last element of \fIfileName\fR, strip off the first three characters if they -are \fBlib\fR, and use any following alphabetic and +are \fBlib\fR, then strip off the next three characters if they +are \fBtcl\fR, and use any following alphabetic and underline characters, converted to titlecase as the prefix. For example, the command \fBunload libxyz4.2.so\fR uses the prefix \fBXyz\fR and the command \fBunload bin/last.so {}\fR uses the 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/upvar.n b/doc/upvar.n index 91defe6..5d697dd 100644 --- a/doc/upvar.n +++ b/doc/upvar.n @@ -94,7 +94,7 @@ proc \fIsetByUpvar\fR { name value } { set localVar $value } set originalVar 1 -trace variable originalVar w \fItraceproc\fR +trace add variable originalVar write \fItraceproc\fR \fIsetByUpvar\fR originalVar 2 .CE .PP diff --git a/doc/vwait.n b/doc/vwait.n index f64d39c..e595a74 100644 --- a/doc/vwait.n +++ b/doc/vwait.n @@ -12,6 +12,8 @@ vwait \- Process events until a variable is written .SH SYNOPSIS \fBvwait\fR \fIvarName\fR +.sp +\fBvwait\fR ?\fIoptions\fR? ?\fIvarName ...\fR? .BE .SH DESCRIPTION .PP @@ -24,8 +26,75 @@ command will return as soon as the event handler that modified a variable name with respect to the global namespace, but can refer to any namespace's variables if the fully-qualified name is given. .PP +In the second more complex command form \fIoptions\fR allow for finer +control of the wait operation and to deal with multiple event sources. +\fIOptions\fR can be made up of +.TP +\fB\-\-\fR +. +Marks the end of options. All following arguments are handled as +variable names. +.TP +\fB\-all\fR +. +All conditions for the wait operation must be met to complete the +wait operation. Otherwise (the default) the first event completes +the wait. +.TP +\fB\-extended\fR +. +An extended result in list form is returned, see below for explanation. +.TP +\fB\-nofileevents\fR +. +File events are not handled in the wait operation. +.TP +\fB\-noidleevents\fR +. +Idle handlers are not invoked during the wait operation. +.TP +\fB\-notimerevents\fR +. +Timer handlers are not serviced during the wait operation. +.TP +\fB\-nowindowevents\fR +. +Events of the windowing system are not handled during the wait operation. +.TP +\fB\-readable\fR \fIchannel\fR +. +\fIChannel\fR must name a Tcl channel open for reading. If \fIchannel\fR +is or becomes readable the wait operation completes. +.TP +\fB\-timeout\fR \fImilliseconds\fR +. +The wait operation is constrained to \fImilliseconds\fR. +.TP +\fB\-variable\fR \fIvarName\fR +. +\fIVarName\fR must be the name of a global variable. Writing or +unsetting this variable completes the wait operation. +.TP +\fB\-writable\fR \fIchannel\fR +. +\fIChannel\fR must name a Tcl channel open for writing. If \fIchannel\fR +is or becomes writable the wait operation completes. +.PP +The result returned by \fBvwait\fR is for the simple form an empty +string. If the \fI\-timeout\fR option is specified, the result is the +number of milliseconds remaining when the wait condition has been +met, or -1 if the wait operation timed out. +.PP +If the \fI\-extended\fR option is specified, the result is made up +of a Tcl list with an even number of elements. Odd elements +take the values \fBreadable\fR, \fBtimeleft\fR, \fBvariable\fR, +and \fBwritable\fR. Even elements are the corresponding variable +and channel names or the remaining number of milliseconds. +The list is ordered by the occurrences of the event(s) with the +exception of \fBtimeleft\fR which always comes last. +.PP In some cases the \fBvwait\fR command may not return immediately -after \fIvarName\fR is set. This happens if the event handler +after \fIvarName\fR et.al. is set. This happens if the event handler that sets \fIvarName\fR does not complete immediately. For example, if an event handler sets \fIvarName\fR and then itself calls \fBvwait\fR to wait for a different variable, then it may not return 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..571647f --- /dev/null +++ b/doc/zipfs.3 @@ -0,0 +1,130 @@ +'\" +'\" 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 +const char * +\fBTclZipfs_AppHook(\fIargcPtr, argvPtr\fR) +.sp +int +\fBTclZipfs_Mount\fR(\fIinterp, zipname, mountpoint, password\fR) +.sp +int +\fBTclZipfs_MountBuffer\fR(\fIinterp, data, dataLen, mountpoint, 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 "const void" *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\fBapp\fR as a read-only Tcl virtual file +system. \fIZIPFS_VOLUME\fR is \fB//zipfs:/\fR on all platforms. +.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 the full Tcl version with build +information (e.g., \fB8.7.0+abcdef...abcdef.gcc-1002\fR). +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 is used to mount ZIP archives and to retrieve information +about currently mounted archives. If \fImountpoint\fR and \fIzipname\fR are both +specified (i.e. non-NULL), the function mounts the ZIP archive \fIzipname\fR on +the mount point given in \fImountpoint\fR. If \fIpassword\fR is not NULL, it +should point to the NUL terminated password protecting the archive. If not under +the zipfs file system root, \fImountpoint\fR is normalized with respect to it. +For example, a mount point passed as either \fBmt\fR \fB/mt\fR would be +normalized to \fB//zipfs:/mt\fR. An error is raised if the mount point includes +a drive or UNC volume. On success, \fIinterp\fR's result is set to the +normalized mount point path. +.PP +If \fImountpoint\fR is a NULL pointer, information on all currently mounted ZIP +file systems is stored in \fIinterp\fR's result as a sequence of mount +points and ZIP file names. +.PP +If \fImountpoint\fR is not NULL but \fIzipfile\fR +is NULL, the path to the archive mounted at that mount point is stored +as \fIinterp\fR's result. The function returns a standard Tcl result +code. +.PP +\fBTclZipfs_MountBuffer\fR mounts the ZIP archive content \fIdata\fR on the +mount point given in \fImountpoint\fR. Both \fImountpoint\fR and \fIdata\fR must +be specified as non-NULL. The \fIcopy\fR argument determines whether the buffer +is internally copied before mounting or not. The ZIP archive is assumed to be +not password protected. On success, \fIinterp\fR's result is set to the +normalized mount point path. +.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..0a05078 --- /dev/null +++ b/doc/zipfs.n @@ -0,0 +1,293 @@ +'\" +'\" 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 tcl::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 ?\fIzipfile\fR? ?\fImountpoint\fR? ?\fIpassword\fR? +\fBzipfs root\fR +\fBzipfs unmount\fR \fImountpoint\fR +.fi +'\" The following subcommand is *UNDOCUMENTED* +'\" \fBzipfs mount_data\fR ?\fIdata\fR ?\fImountpoint\fR?? +.BE +.SH DESCRIPTION +.PP +The \fBzipfs\fR command provides Tcl with the ability to mount the +contents of a ZIP archive file as a virtual file system. Tcl's ZIP +archive support is limited to basic features and options. +Supported storage methods include only STORE and DEFLATE with optional +simple encryption, sufficient to prevent casual inspection of their contents +but not able to prevent access by even a moderately determined attacker. +Strong encryption, multi-part archives, platform metadata, +zip64 formats and other compression methods like bzip2 are not supported. +.PP +Files within mounted archives can be written to but new files or directories +cannot be created. Further, modifications to files are limited to the +mounted archive in memory and are not persisted to disk. +.PP +Paths in mounted archives are case-sensitive on all platforms. +.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 +. +Returns the list of paths under directory \fIdirectoryName\fR which need not be +within a zipfs mounted archive. The paths are prefixed with \fIdirectoryName\fR. +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 +As a special case, querying the mount point gives the start of the zip data as the offset +in (4), which can be used to truncate the zip information from an executable. +Querying an ancestor of a mount point will raise an error. +.RE +.TP +\fBzipfs list\fR ?(\fB\-glob\fR|\fB\-regexp\fR)? ?\fIpattern\fR? +. +If \fIpattern\fR is not specified, the command returns a list of files across +all zipfs mounted archives. If \fIpattern\fR is specified, only those paths +matching the pattern are returned. By default, or with the \fB-glob\fR option, +the pattern is treated as a glob pattern and matching is done as described for +the \fBstring match\fR command. Alternatively, the \fB-regexp\fR option may be +used to specify matching \fBpattern\fR as a regular expression. The file names +are returned in arbitrary order. Note that path separators are treated as +ordinary characters in the matching. Thus forward slashes should be used +as path separators in the pattern. The returned paths only include those +actually in the archive and does not include intermediate directories in +mount paths. +.TP +\fBzipfs mount\fR +.TP +\fBzipfs mount\fR \fImountpoint\fR +.TP +\fBzipfs mount\fR \fIzipfile\fR \fImountpoint\fR ?\fIpassword\fR? +.RS +.PP +The \fBzipfs mount\fR command mounts ZIP archives as Tcl virtual file systems +and returns information about current mounts. +.PP +With no arguments, the command returns a dictionary mapping +mount points to the path of the corresponding ZIP archive. +.PP +In the single argument form, the command returns the file path +of the ZIP archive mounted at the specified mount point. +.PP +In the third form, the command mounts the ZIP archive \fIzipfile\fR as a Tcl virtual +filesystem at \fImountpoint\fR. After this command executes, files contained +in \fIzipfile\fR will appear to Tcl to be regular files at the mount point. +If \fImountpoint\fR is +specified as an empty string, it is defaulted to the \fB[zipfs root]\fR. +The command returns the normalized mount point path. +.PP +If not under the zipfs file system root, \fImountpoint\fR is normalized with +respect to it. For example, a mount point passed as either \fBmt\fR \fB/mt\fR +would be normalized to \fB//zipfs:/mt\fR. An error is raised if the mount point +includes a drive or UNC volume. +.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. +This value is +.QW \fB//zipfs:/\fR +on most platforms. +.TP +\fBzipfs unmount \fImountpoint\fR +. +Unmounts a previously mounted ZIP archive mounted to \fImountpoint\fR. +The command will fail with an error exception if +there are any files within the mounted archive are open. +.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. +If the starting image has a ZIP archive already attached to it, it is removed +from the copy in \fIoutfile\fR before the new ZIP archive is added. +.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 $zip $base +# $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 $base +.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 $zip $base $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: |