diff options
Diffstat (limited to 'doc')
231 files changed, 1949 insertions, 1470 deletions
diff --git a/doc/Access.3 b/doc/Access.3 index 6ee1f26..1e82e07 100644 --- a/doc/Access.3 +++ b/doc/Access.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Access.3,v 1.10 2008/12/18 21:23:47 dkf Exp $ -'\" .so man.macros .TH Tcl_Access 3 8.1 Tcl "Tcl Library Procedures" .BS diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index 783a1e0..b9c6a63 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: AddErrInfo.3,v 1.26 2010/01/14 11:47:07 dkf Exp $ -'\" .so man.macros .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures" .BS @@ -109,7 +107,12 @@ with the value of \fIcode\fR. The \fB(Tcl_Obj *)\fR returned by \fBTcl_GetReturnOptions\fR points to an unshared \fBTcl_Obj\fR with reference count of zero. The dictionary may be written to, either adding, removing, or overwriting -any entries in it, with the need to check for a shared object. +any entries in it, without the need to check for a shared value. +As with any \fBTcl_Obj\fR with reference count of zero, it is up to +the caller to arrange for its disposal with \fBTcl_DecrRefCount\fR or +to a reference to it via \fBTcl_IncrRefCount\fR (or one of the many +functions that call that, notably including \fBTcl_SetObjResult\fR and +\fBTcl_SetVar2Ex\fR). .PP A typical usage for \fBTcl_GetReturnOptions\fR is to retrieve the stack trace when script evaluation returns @@ -125,6 +128,7 @@ if (code == TCL_ERROR) { Tcl_DictObjGet(NULL, options, key, &stackTrace); Tcl_DecrRefCount(key); /* Do something with stackTrace */ + Tcl_DecrRefCount(options); } .CE .PP @@ -228,7 +232,7 @@ the need for a null byte. If the \fBTcl_AddObjErrorInfo\fR interface is used at all, it should be with a negative \fIlength\fR value. .PP The procedure \fBTcl_SetObjErrorCode\fR is used to set the -\fB\-errorcode\fR return option to the list object \fIerrorObjPtr\fR +\fB\-errorcode\fR return option to the list value \fIerrorObjPtr\fR built up by the caller. \fBTcl_SetObjErrorCode\fR is typically invoked just before returning an error. If an error is @@ -238,7 +242,7 @@ the \fB\-errorcode\fR return option to \fBNONE\fR. .PP The procedure \fBTcl_SetErrorCode\fR is also used to set the \fB\-errorcode\fR return option. However, it takes one or more strings to -record instead of an object. Otherwise, it is similar to +record instead of a value. Otherwise, it is similar to \fBTcl_SetObjErrorCode\fR in behavior. .PP \fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that @@ -305,4 +309,4 @@ most recent error seen in an interpreter. Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetResult(3), Tcl_SetErrno(3), tclvars(n) .SH KEYWORDS -error, object, object result, stack, trace, variable +error, value, value result, stack, trace, variable diff --git a/doc/Alloc.3 b/doc/Alloc.3 index 3204026..ca4f949 100644 --- a/doc/Alloc.3 +++ b/doc/Alloc.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Alloc.3,v 1.11 2009/03/30 18:49:12 dgp Exp $ -'\" .so man.macros .TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/AllowExc.3 b/doc/AllowExc.3 index 4e6be72..ae595f1 100644 --- a/doc/AllowExc.3 +++ b/doc/AllowExc.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: AllowExc.3,v 1.5 2004/10/07 14:44:31 dkf Exp $ -'\" .so man.macros .TH Tcl_AllowExceptions 3 7.4 Tcl "Tcl Library Procedures" .BS diff --git a/doc/AppInit.3 b/doc/AppInit.3 index bd3c665..e4ae971 100644 --- a/doc/AppInit.3 +++ b/doc/AppInit.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: AppInit.3,v 1.11 2008/12/15 15:48:33 dgp Exp $ -'\" .so man.macros .TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures" .BS diff --git a/doc/AssocData.3 b/doc/AssocData.3 index 6366cdf..59c26a4 100644 --- a/doc/AssocData.3 +++ b/doc/AssocData.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" -'\" RCS: @(#) $Id: AssocData.3,v 1.9 2008/10/15 10:43:37 dkf Exp $ .so man.macros .TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/Async.3 b/doc/Async.3 index dba4400..d02f76d 100644 --- a/doc/Async.3 +++ b/doc/Async.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Async.3,v 1.14 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures" .BS diff --git a/doc/BackgdErr.3 b/doc/BackgdErr.3 index ba53dc6..3116671 100644 --- a/doc/BackgdErr.3 +++ b/doc/BackgdErr.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: BackgdErr.3,v 1.9 2008/12/09 20:16:29 dgp Exp $ -'\" .so man.macros .TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/Backslash.3 b/doc/Backslash.3 index e48bcce..8b399fc 100644 --- a/doc/Backslash.3 +++ b/doc/Backslash.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Backslash.3,v 1.10 2007/12/13 15:22:30 dgp Exp $ -'\" .so man.macros .TH Tcl_Backslash 3 "8.1" Tcl "Tcl Library Procedures" .BS diff --git a/doc/BoolObj.3 b/doc/BoolObj.3 index e8563d3..6691140 100644 --- a/doc/BoolObj.3 +++ b/doc/BoolObj.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: BoolObj.3,v 1.12 2009/11/27 14:35:10 dkf Exp $ -'\" .so man.macros .TH Tcl_BooleanObj 3 8.5 Tcl "Tcl Library Procedures" .BS @@ -32,7 +30,7 @@ Points to the Tcl_Obj in which to store, or from which to retrieve a boolean value. .AP Tcl_Interp *interp in/out If a boolean value cannot be retrieved, -an error message is left in the interpreter's result object +an error message is left in the interpreter's result value unless \fIinterp\fR is NULL. .AP int *boolPtr out Points to place where \fBTcl_GetBooleanFromObj\fR @@ -94,4 +92,4 @@ a \fBTCL_ERROR\fR return. Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean .SH KEYWORDS -boolean, object +boolean, value diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3 index 6d0822d..2921f68 100644 --- a/doc/ByteArrObj.3 +++ b/doc/ByteArrObj.3 @@ -4,13 +4,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ByteArrObj.3,v 1.7 2008/11/07 20:10:19 patthoyts Exp $ -'\" .so man.macros .TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl objects as a arrays of bytes +Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl values as a arrays of bytes .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -29,65 +27,65 @@ unsigned char * .SH ARGUMENTS .AS "const unsigned char" *lengthPtr in/out .AP "const unsigned char" *bytes in -The array of bytes used to initialize or set a byte-array object. May be NULL +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. .AP Tcl_Obj *objPtr in/out -For \fBTcl_SetByteArrayObj\fR, this points to the object to be converted to +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 object from which to get +\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 -object, it will be converted to one. +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 object. +If non-NULL, filled with the length of the array of bytes in the value. .BE .SH DESCRIPTION .PP -These procedures are used to create, modify, and read Tcl byte-array objects -from C code. Byte-array objects are typically used to hold the +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 object to a byte-array. Obtaining the -string representation of a byte-array object (by calling +byte-array or to convert an arbitrary value to a byte-array. 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. .PP \fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR will -create a new object of byte-array type or modify an existing object to have a -byte-array type. Both of these procedures set the object's type to be -byte-array and set the object's internal representation to a copy of the +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 object with a reference count of zero. +pointer to a newly allocated value with a reference count of zero. \fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if -the object is not already a byte-array object, frees any old internal +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. .PP -\fBTcl_GetByteArrayFromObj\fR converts a Tcl object to byte-array type and -returns a pointer to the object's new internal representation as an array of +\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 object and should not be freed. The contents of the array may be -modified by the caller only if the object is not shared and the caller +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. .PP -\fBTcl_SetByteArrayLength\fR converts the Tcl object to byte-array type -and changes the length of the object's internal representation as an +\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 object's new array of bytes. +pointer to the value's new array of bytes. .SH "SEE ALSO" Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount .SH KEYWORDS -object, byte array, utf, unicode, internationalization +value, binary data, byte array, utf, unicode, internationalization diff --git a/doc/CallDel.3 b/doc/CallDel.3 index 0dbed27..dec4392 100644 --- a/doc/CallDel.3 +++ b/doc/CallDel.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CallDel.3,v 1.8 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures" .BS diff --git a/doc/Cancel.3 b/doc/Cancel.3 index 506b0fe..80db3a3 100644 --- a/doc/Cancel.3 +++ b/doc/Cancel.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Cancel.3,v 1.2 2009/11/02 00:04:48 mistachkin Exp $ -'\" .so man.macros .TH Tcl_Cancel 3 8.6 Tcl "Tcl Library Procedures" .BS diff --git a/doc/ChnlStack.3 b/doc/ChnlStack.3 index be22a88..9ec38b4 100644 --- a/doc/ChnlStack.3 +++ b/doc/ChnlStack.3 @@ -3,8 +3,6 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: ChnlStack.3,v 1.9 2008/10/04 12:33:34 nijtmans Exp $ .so man.macros .TH Tcl_StackChannel 3 8.3 Tcl "Tcl Library Procedures" .BS diff --git a/doc/Class.3 b/doc/Class.3 index 0dea97f..28cea9b 100644 --- a/doc/Class.3 +++ b/doc/Class.3 @@ -4,14 +4,12 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Class.3,v 1.6 2010/06/16 14:49:51 nijtmans Exp $ -'\" .so man.macros .TH Tcl_Class 3 0.1 TclOO "TclOO Library Functions" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Tcl_ClassGetMetadata, Tcl_ClassSetMetadata, Tcl_CopyObjectInstance, Tcl_GetClassAsObject, Tcl_GetObjectAsClass, Tcl_GetObjectCommand, Tcl_GetObjectNamespace, Tcl_NewObjectInstance, Tcl_ObjectDeleted, Tcl_ObjectGetMetadata, Tcl_ObjectGetMethodNameMapper, Tcl_ObjectSetMetadata, Tcl_ObjectSetMethodNameMapper \- manipulate objects and classes +Tcl_ClassGetMetadata, Tcl_ClassSetMetadata, Tcl_CopyObjectInstance, Tcl_GetClassAsObject, Tcl_GetObjectAsClass, Tcl_GetObjectCommand, Tcl_GetObjectFromObj, Tcl_GetObjectName, Tcl_GetObjectNamespace, Tcl_NewObjectInstance, Tcl_ObjectDeleted, Tcl_ObjectGetMetadata, Tcl_ObjectGetMethodNameMapper, Tcl_ObjectSetMetadata, Tcl_ObjectSetMethodNameMapper \- manipulate objects and classes .SH SYNOPSIS .nf \fB#include <tclOO.h>\fR @@ -127,7 +125,7 @@ any constructors. Every object and every class may have arbitrary amounts of metadata attached to it, which the object or class attaches no meaning to beyond what is described in a Tcl_ObjectMetadataType structure instance. Metadata to be -attached is described by the the type of the metadata (given in the +attached is described by the type of the metadata (given in the \fImetaTypePtr\fR argument) and an arbitrary pointer (the \fImetadata\fR argument) that are given to \fBTcl_ObjectSetMetadata\fR and \fBTcl_ClassSetMetadata\fR, and a particular piece of metadata can be diff --git a/doc/CmdCmplt.3 b/doc/CmdCmplt.3 index 152655a..eeae039 100644 --- a/doc/CmdCmplt.3 +++ b/doc/CmdCmplt.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CmdCmplt.3,v 1.4 2004/10/07 15:15:35 dkf Exp $ -'\" .so man.macros .TH Tcl_CommandComplete 3 "" Tcl "Tcl Library Procedures" .BS diff --git a/doc/Concat.3 b/doc/Concat.3 index d4ba689..c38bf82 100644 --- a/doc/Concat.3 +++ b/doc/Concat.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Concat.3,v 1.9 2005/05/10 18:33:54 kennykb Exp $ -'\" .so man.macros .TH Tcl_Concat 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index d306d64..55a4024 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -4,8 +4,6 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: CrtChannel.3,v 1.46 2010/01/14 11:47:07 dkf Exp $ .so man.macros .TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures" .BS @@ -213,7 +211,7 @@ call to \fBTcl_GetStdChannel\fR or a call to \fBTcl_SetStdChannel\fR closing this standard channel will cause the next call to \fBTcl_CreateChannel\fR to make the new channel the new standard channel too. See \fBTcl_StandardChannels\fR for a general treatise -about standard channels and the behaviour of the Tcl library with +about standard channels and the behavior of the Tcl library with regard to them. .PP \fBTcl_GetChannelInstanceData\fR returns the instance data associated with @@ -848,7 +846,7 @@ the generic options error message string. .PP It always returns \fBTCL_ERROR\fR .PP -An error message is generated in \fIinterp\fR's result object to +An error message is generated in \fIinterp\fR's result value to indicate that a command was invoked with a bad option. The message has the form .CS diff --git a/doc/CrtChnlHdlr.3 b/doc/CrtChnlHdlr.3 index 08f419e..1451e30 100644 --- a/doc/CrtChnlHdlr.3 +++ b/doc/CrtChnlHdlr.3 @@ -4,7 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtChnlHdlr.3,v 1.8 2008/10/17 10:22:25 dkf Exp $ .so man.macros .TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/CrtCloseHdlr.3 b/doc/CrtCloseHdlr.3 index 4fe6c5c..a114f9c 100644 --- a/doc/CrtCloseHdlr.3 +++ b/doc/CrtCloseHdlr.3 @@ -4,7 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtCloseHdlr.3,v 1.4 2008/06/29 22:28:23 dkf Exp $ .so man.macros .TH Tcl_CreateCloseHandler 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3 index 4e8daaf..c921999 100644 --- a/doc/CrtCommand.3 +++ b/doc/CrtCommand.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtCommand.3,v 1.17 2008/12/15 18:33:25 dgp Exp $ -'\" .so man.macros .TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures" .BS @@ -43,18 +41,18 @@ will call \fIproc\fR to process the command. It differs from \fBTcl_CreateObjCommand\fR in that a new string-based command is defined; that is, a command procedure is defined that takes an array of -argument strings instead of objects. -The object-based command procedures registered by \fBTcl_CreateObjCommand\fR +argument strings instead of values. +The value-based command procedures registered by \fBTcl_CreateObjCommand\fR can execute significantly faster than the string-based command procedures defined by \fBTcl_CreateCommand\fR. -This is because they take Tcl objects as arguments -and those objects can retain an internal representation that +This is because they take Tcl values as arguments +and those values can retain an internal representation that can be manipulated more efficiently. -Also, Tcl's interpreter now uses objects internally. +Also, Tcl's interpreter now uses values internally. In order to invoke a string-based command procedure registered by \fBTcl_CreateCommand\fR, it must generate and fetch a string representation -from each argument object before the call. +from each argument value before the call. New commands should be defined using \fBTcl_CreateObjCommand\fR. We support \fBTcl_CreateCommand\fR for backwards compatibility. .PP diff --git a/doc/CrtFileHdlr.3 b/doc/CrtFileHdlr.3 index 00a6a48..cbc5e9f 100644 --- a/doc/CrtFileHdlr.3 +++ b/doc/CrtFileHdlr.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtFileHdlr.3,v 1.10 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures" .BS diff --git a/doc/CrtInterp.3 b/doc/CrtInterp.3 index 6f4176b..a248cf4 100644 --- a/doc/CrtInterp.3 +++ b/doc/CrtInterp.3 @@ -5,13 +5,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtInterp.3,v 1.11 2010/01/14 11:47:07 dkf Exp $ -'\" .so man.macros .TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted \- create and delete Tcl command interpreters +Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, Tcl_InterpDeleted \- create and delete Tcl command interpreters .SH SYNOPSIS .nf \fB#include <tcl.h>\fR diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3 index 3f4f7c0..cdde20b 100644 --- a/doc/CrtMathFnc.3 +++ b/doc/CrtMathFnc.3 @@ -5,13 +5,18 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtMathFnc.3,v 1.19 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures" .BS .SH NAME Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and enumerate math functions for expressions +.SH "NOTICE OF EVENTUAL DEPRECATION" +.PP +The \fBTcl_CreateMathFunc\fR and \fBTcl_GetMathFuncInfo\fR functions +are rendered somewhat obsolete by the ability to create functions for +expressions by placing commands in the \fBtcl::mathfunc\fR namespace, +as described in the \fBmathfunc\fR manual page; the API described on +this page is not expected to be maintained indefinitely. .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -148,9 +153,9 @@ will not be modified. The variable pointed to by \fInumArgsPointer\fR will contain -1, and no argument types will be stored in the variable pointed to by \fIargTypesPointer\fR. .PP -\fBTcl_ListMathFuncs\fR returns a Tcl object containing a list of all +\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 object has a reference count of zero. +\fIpattern\fR. The returned value has a reference count of zero. .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 43a855b..faf8b74 100644 --- a/doc/CrtObjCmd.3 +++ b/doc/CrtObjCmd.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.19 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures" .BS @@ -66,7 +64,7 @@ The command must not have been deleted. Pointer to structure containing various information about a Tcl command. .AP Tcl_Obj *objPtr in -Object containing the name of a Tcl command. +Value containing the name of a Tcl command. .BE .SH DESCRIPTION .PP @@ -104,10 +102,10 @@ will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to \fBTcl_CreateObjCommand\fR. Typically, \fIclientData\fR points to an application-specific data structure that describes what to do when the command procedure is invoked. \fIObjc\fR and \fIobjv\fR describe the -arguments to the command, \fIobjc\fR giving the number of argument objects +arguments to the command, \fIobjc\fR giving the number of argument values (including the command name) and \fIobjv\fR giving the values of the arguments. The \fIobjv\fR array will contain \fIobjc\fR values, pointing to -the argument objects. Unlike \fIargv\fR[\fIargv\fR] used in a +the argument values. Unlike \fIargv\fR[\fIargv\fR] used in a string-based command procedure, \fIobjv\fR[\fIobjc\fR] will not contain NULL. .PP Additionally, when \fIproc\fR is invoked, it must not modify the contents @@ -117,9 +115,9 @@ cause memory to be lost and the runtime stack to be corrupted. The \fBconst\fR in the declaration of \fIobjv\fR will cause ANSI-compliant compilers to report any such attempted assignment as an error. However, it is acceptable to modify the internal representation of any individual -object argument. For instance, the user may call +value argument. For instance, the user may call \fBTcl_GetIntFromObj\fR on \fIobjv\fR[\fB2\fR] to obtain the integer -representation of that object; that call may change the type of the object +representation of that value; that call may change the type of the value that \fIobjv\fR[\fB2\fR] points at, but will not change where \fIobjv\fR[\fB2\fR] points. .PP @@ -135,7 +133,7 @@ of the command, and in the case of \fBTCL_ERROR\fR this gives an error message. Before invoking a command procedure, \fBTcl_EvalObjEx\fR sets interpreter's result to -point to an object representing an empty string, so simple +point to a value representing an empty string, so simple commands can return an empty result by doing nothing at all. .PP The contents of the \fIobjv\fR array belong to Tcl and are not @@ -227,7 +225,7 @@ if \fIisNativeObjectProc\fR has the value 1. The fields \fIobjProc\fR and \fIobjClientData\fR have the same meaning as the \fIproc\fR and \fIclientData\fR arguments to \fBTcl_CreateObjCommand\fR; -they hold information about the object-based command procedure +they hold information about the value-based command procedure that the Tcl interpreter calls to implement the command. The fields \fIproc\fR and \fIclientData\fR hold information about the string-based command procedure @@ -237,7 +235,7 @@ this is the procedure passed to it; otherwise, this is a compatibility procedure registered by \fBTcl_CreateObjCommand\fR that simply calls the command's -object-based procedure after converting its string arguments to Tcl objects. +value-based procedure after converting its string arguments to Tcl values. The field \fIdeleteData\fR is the ClientData value to pass to \fIdeleteProc\fR; it is normally the same as \fIclientData\fR but may be set independently using the @@ -292,7 +290,7 @@ they need to keep it for a long time. \fBTcl_GetCommandFullName\fR produces the fully qualified name of a command from a command token. The name, including all namespace prefixes, -is appended to the object specified by \fIobjPtr\fR. +is appended to the value specified by \fIobjPtr\fR. .PP \fBTcl_GetCommandFromObj\fR returns a token for the command specified by the name in a \fBTcl_Obj\fR. @@ -301,4 +299,4 @@ Returns NULL if the command is not found. .SH "SEE ALSO" Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3) .SH KEYWORDS -bind, command, create, delete, namespace, object +bind, command, create, delete, namespace, value diff --git a/doc/CrtSlave.3 b/doc/CrtSlave.3 index 9727740..000ae58 100644 --- a/doc/CrtSlave.3 +++ b/doc/CrtSlave.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtSlave.3,v 1.20 2007/12/13 15:22:30 dgp Exp $ -'\" .so man.macros .TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures" .BS @@ -80,10 +78,10 @@ Count of additional arguments to pass to the alias command. Vector of strings, the additional arguments to pass to the alias command. This storage is owned by the caller. .AP int objc in -Count of additional object arguments to pass to the alias object command. +Count of additional value arguments to pass to the aliased command. .AP Tcl_Obj **objv in -Vector of Tcl_Obj structures, the additional object arguments to pass to -the alias object command. +Vector of Tcl_Obj structures, the additional value arguments to pass to +the aliased command. This storage is owned by the caller. .AP Tcl_Interp **targetInterpPtr in Pointer to location to store the address of the interpreter where a target @@ -99,11 +97,11 @@ Pointer to location to store a vector of strings, the additional arguments to pass to an alias. The location is in storage owned by the caller, the vector of strings is owned by the called function. .AP int *objcPtr out -Pointer to location to store count of additional object arguments to be +Pointer to location to store count of additional value arguments to be passed to the alias. The location is in storage owned by the caller. .AP Tcl_Obj ***objvPtr out Pointer to location to store a vector of Tcl_Obj structures, the additional -arguments to pass to an object alias command. The location is in storage +arguments to pass to an alias command. The location is in storage owned by the caller, the vector of Tcl_Obj structures is owned by the called function. .AP "const char" *cmdName in @@ -167,13 +165,13 @@ of the relative path succeeds, \fBTCL_OK\fR is returned, else \fBTCL_ERROR\fR is returned and the \fIresult\fR field in \fIaskingInterp\fR contains the error message. .PP -\fBTcl_CreateAlias\fR creates an object command named \fIslaveCmd\fR in +\fBTcl_CreateAlias\fR creates a command named \fIslaveCmd\fR in \fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR to be invoked in \fItargetInterp\fR. The arguments specified by the strings contained in \fIargv\fR are always prepended to any arguments supplied in the invocation of \fIslaveCmd\fR and passed to \fItargetCmd\fR. 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 object result +it fails; in that case, an error message is left in the value result of \fIslaveInterp\fR. Note that there are no restrictions on the ancestry relationship (as created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and @@ -181,7 +179,7 @@ created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and restrictions on how they are related. .PP \fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except -that it takes a vector of objects to pass as additional arguments instead +that it takes a vector of values to pass as additional arguments instead of a vector of strings. .PP \fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR @@ -204,7 +202,7 @@ command, or the operation will return \fBTCL_ERROR\fR and leave an error message in the \fIresult\fR field in \fIinterp\fR. If an exposed command named \fIcmdName\fR already exists, the operation returns \fBTCL_ERROR\fR and leaves an error message in the -object result of \fIinterp\fR. +value result of \fIinterp\fR. If the operation succeeds, it returns \fBTCL_OK\fR. After executing this command, attempts to use \fIcmdName\fR in a call to \fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed. @@ -214,10 +212,10 @@ exposed commands to the set of hidden commands, under the name \fIhiddenCmdName\fR. \fICmdName\fR must be the name of an existing exposed command, or the operation will return \fBTCL_ERROR\fR and leave an error -message in the object result of \fIinterp\fR. +message in the value result of \fIinterp\fR. Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and -leave an error message in the object result of \fIinterp\fR. +leave an error message in the value result of \fIinterp\fR. The \fICmdName\fR will be looked up in the global namespace, and not relative to the current namespace, even if the current namespace is not the global one. diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3 index 841b465..2c9f90a 100644 --- a/doc/CrtTimerHdlr.3 +++ b/doc/CrtTimerHdlr.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.8 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3 index b56a878..3689add 100644 --- a/doc/CrtTrace.3 +++ b/doc/CrtTrace.3 @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtTrace.3,v 1.17 2009/01/14 14:14:03 dgp Exp $ -'\" .so man.macros .TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures" .BS diff --git a/doc/DString.3 b/doc/DString.3 index db0c4dd..a85b1cf 100644 --- a/doc/DString.3 +++ b/doc/DString.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: DString.3,v 1.17 2007/12/13 15:22:31 dgp Exp $ -'\" .so man.macros .TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures" .BS diff --git a/doc/DetachPids.3 b/doc/DetachPids.3 index f992f43..0535cd8 100644 --- a/doc/DetachPids.3 +++ b/doc/DetachPids.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: DetachPids.3,v 1.7 2007/12/13 15:22:31 dgp Exp $ -'\" .so man.macros .TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures" .BS diff --git a/doc/DictObj.3 b/doc/DictObj.3 index b54ee20..db8f39a 100644 --- a/doc/DictObj.3 +++ b/doc/DictObj.3 @@ -4,14 +4,12 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: DictObj.3,v 1.13 2009/11/27 14:35:10 dkf Exp $ -'\" .so man.macros .TH Tcl_DictObj 3 8.5 Tcl "Tcl Library Procedures" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList \- manipulate Tcl objects as dictionaries +Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList \- manipulate Tcl values as dictionaries .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -49,23 +47,23 @@ int .SH ARGUMENTS .AS Tcl_DictSearch "**valuePtrPtr" in/out .AP Tcl_Interp *interp in -If an error occurs while converting an object to be a dictionary object, -an error message is left in the interpreter's result object +If an error occurs while converting a value to be a dictionary value, +an error message is left in the interpreter's result value unless \fIinterp\fR is NULL. .AP Tcl_Obj *dictPtr in/out -Points to the dictionary object to be manipulated. -If \fIdictPtr\fR does not already point to a dictionary object, +Points to the dictionary value to be manipulated. +If \fIdictPtr\fR does not already point to a dictionary value, an attempt will be made to convert it to one. .AP Tcl_Obj *keyPtr in Points to the key for the key/value pair being manipulated within the -dictionary object. +dictionary value. .AP Tcl_Obj **keyPtrPtr out Points to a variable that will have the key from a key/value pair placed within it. May be NULL to indicate that the caller is not interested in the key. .AP Tcl_Obj *valuePtr in -Points to the value for the key/value pair being manipulate within the -dictionary object (or sub-object, in the case of +Points to the value for the key/value pair being manipulated within the +dictionary value (or sub-value, in the case of \fBTcl_DictObjPutKeyList\fR.) .AP Tcl_Obj **valuePtrPtr out Points to a variable that will have the value from a key/value pair @@ -90,15 +88,15 @@ completed, and a zero otherwise. Indicates the number of keys that will be supplied in the \fIkeyv\fR array. .AP "Tcl_Obj *const" *keyv in -Array of \fIkeyc\fR pointers to objects that +Array of \fIkeyc\fR pointers to values that \fBTcl_DictObjPutKeyList\fR and \fBTcl_DictObjRemoveKeyList\fR will use to locate the key/value pair to manipulate within the -sub-dictionaries of the main dictionary object passed to them. +sub-dictionaries of the main dictionary value passed to them. .BE .SH DESCRIPTION .PP -Tcl dictionary objects have an internal representation that supports +Tcl dictionary values have an internal representation that supports efficient mapping from keys to values and which guarantees that the particular ordering of keys within the dictionary remains the same modulo any keys being deleted (which removes them from the order) or @@ -108,11 +106,11 @@ keys of the dictionary, and each will be followed (in the odd-valued index) by the value associated with that key. .PP The procedures described in this man page are used to -create, modify, index, and iterate over dictionary objects from C code. +create, modify, index, and iterate over dictionary values from C code. .PP -\fBTcl_NewDictObj\fR creates a new, empty dictionary object. The -string representation of the object will be invalid, and the reference -count of the object will be zero. +\fBTcl_NewDictObj\fR creates a new, empty dictionary value. The +string representation of the value will be invalid, and the reference +count of the value will be zero. .PP \fBTcl_DictObjGet\fR looks up the given key within the given dictionary and writes a pointer to the value associated with that key @@ -219,7 +217,7 @@ if (\fBTcl_DictObjFirst\fR(interp, objPtr, &search, for (; !done ; \fBTcl_DictObjNext\fR(&search, &key, &value, &done)) { /* * Note that strcmp() is not a good way of comparing - * objects and is just used here for demonstration + * values and is just used here for demonstration * purposes. */ if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) { @@ -233,4 +231,4 @@ return TCL_OK; .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable .SH KEYWORDS -dict, dict object, dictionary, dictionary object, hash table, iteration, object +dict, dict value, dictionary, dictionary value, hash table, iteration, value diff --git a/doc/DoOneEvent.3 b/doc/DoOneEvent.3 index 2243a1b..9bdf926 100644 --- a/doc/DoOneEvent.3 +++ b/doc/DoOneEvent.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: DoOneEvent.3,v 1.6 2007/12/13 15:22:31 dgp Exp $ -'\" .so man.macros .TH Tcl_DoOneEvent 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3 index 37b4cec..27a4b8c 100644 --- a/doc/DoWhenIdle.3 +++ b/doc/DoWhenIdle.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.7 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3 index 3fd6730..f811c89 100644 --- a/doc/DoubleObj.3 +++ b/doc/DoubleObj.3 @@ -4,13 +4,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: DoubleObj.3,v 1.5 2009/11/27 14:35:10 dkf Exp $ -'\" .so man.macros .TH Tcl_DoubleObj 3 8.0 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl objects as floating-point values +Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl values as floating-point values .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -25,11 +23,11 @@ int .SH ARGUMENTS .AS Tcl_Interp doubleValue in/out .AP double doubleValue in -A double-precision floating-point value used to initialize or set a Tcl object. +A double-precision floating-point value used to initialize or set a Tcl value. .AP Tcl_Obj *objPtr in/out -For \fBTcl_SetDoubleObj\fR, this points to the object in which to store a +For \fBTcl_SetDoubleObj\fR, this points to the value in which to store a double value. -For \fBTcl_GetDoubleFromObj\fR, this refers to the object +For \fBTcl_GetDoubleFromObj\fR, this refers to the value from which to retrieve a double value. .AP Tcl_Interp *interp in/out When non-NULL, an error message is left here when double value retrieval fails. @@ -39,21 +37,21 @@ Points to place to store the double value obtained from \fIobjPtr\fR. .SH DESCRIPTION .PP -These procedures are used to create, modify, and read Tcl objects that +These procedures are used to create, modify, and read Tcl values that hold double-precision floating-point values. .PP -\fBTcl_NewDoubleObj\fR creates and returns a new Tcl object initialized to -the double value \fIdoubleValue\fR. The returned Tcl object is unshared. +\fBTcl_NewDoubleObj\fR creates and returns a new Tcl value initialized to +the double value \fIdoubleValue\fR. The returned Tcl value is unshared. .PP -\fBTcl_SetDoubleObj\fR sets the value of an existing Tcl object pointed to +\fBTcl_SetDoubleObj\fR sets the value of an existing Tcl value pointed to by \fIobjPtr\fR to the double value \fIdoubleValue\fR. The \fIobjPtr\fR -argument must point to an unshared Tcl object. Any attempt to set the value -of a shared Tcl object violates Tcl's copy-on-write policy. Any existing -string representation or internal representation in the unshared Tcl object +argument must point to an unshared Tcl value. Any attempt to set the value +of a shared Tcl value 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 \fBTcl_GetDoubleFromObj\fR attempts to retrieve a double value from the -Tcl object \fIobjPtr\fR. If the attempt succeeds, then \fBTCL_OK\fR is +Tcl value \fIobjPtr\fR. If the attempt succeeds, then \fBTCL_OK\fR is returned, and the double value is written to the storage pointed to by \fIdoublePtr\fR. 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. @@ -63,4 +61,4 @@ calls to \fBTcl_GetDoubleFromObj\fR more efficient. .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult .SH KEYWORDS -double, double object, double type, internal representation, object, object type, string representation +double, double value, double type, internal representation, value, value type, string representation diff --git a/doc/DumpActiveMemory.3 b/doc/DumpActiveMemory.3 index bdab746..1f6cb46 100644 --- a/doc/DumpActiveMemory.3 +++ b/doc/DumpActiveMemory.3 @@ -3,8 +3,6 @@ '\" Copyright (c) 2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: DumpActiveMemory.3,v 1.8 2004/10/07 15:15:36 dkf Exp $ -'\" .so man.macros .TH "Tcl_DumpActiveMemory" 3 8.1 Tcl "Tcl Library Procedures" .BS diff --git a/doc/Encoding.3 b/doc/Encoding.3 index 1545c21..7bcb285 100644 --- a/doc/Encoding.3 +++ b/doc/Encoding.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Encoding.3,v 1.32 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures" .BS diff --git a/doc/Ensemble.3 b/doc/Ensemble.3 index 34a7a85..cd69bbd 100644 --- a/doc/Ensemble.3 +++ b/doc/Ensemble.3 @@ -4,15 +4,13 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Ensemble.3,v 1.9 2010/01/10 20:36:49 dkf Exp $ -'\" '\" This documents the C API introduced in TIP#235 '\" .so man.macros .TH Tcl_Ensemble 3 8.5 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler \- manipulate ensemble commands +Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleParameterList, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleParameterList, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler \- manipulate ensemble commands .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -97,7 +95,7 @@ Pointer to a variable into which to write the current ensemble mapping dictionary. .AP Tcl_Obj *listObj in A list value to use for the list of formal pre-subcommand parameters, the -defined list of subcommands in the dictionary or the unknown subcommmand +defined list of subcommands in the dictionary or the unknown subcommand handler command prefix. May be NULL if the subcommand list or unknown handler are to be removed. .AP Tcl_Obj **listObjPtr out @@ -161,6 +159,8 @@ code (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an ensemble) and the dictionary obtained from \fBTcl_GetEnsembleMappingDict\fR should always be treated as immutable even if it is unshared. +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 diff --git a/doc/Environment.3 b/doc/Environment.3 index 5a7c059..3753f43 100644 --- a/doc/Environment.3 +++ b/doc/Environment.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Environment.3,v 1.7 2009/11/27 14:35:10 dkf Exp $ -'\" .so man.macros .TH Tcl_PutEnv 3 "7.5" Tcl "Tcl Library Procedures" .BS @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Eval.3,v 1.29 2009/11/01 18:15:40 jenglish Exp $ -'\" .so man.macros .TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures" .BS @@ -49,17 +47,17 @@ int Interpreter in which to execute the script. The interpreter's result is modified to hold the result or error message from the script. .AP Tcl_Obj *objPtr in -A Tcl object containing the script to execute. +A Tcl value containing the script to execute. .AP int flags in ORed combination of flag bits that specify additional options. \fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported. .AP "const char" *fileName in Name of a file containing a Tcl script. .AP int objc in -The number of objects in the array pointed to by \fIobjPtr\fR; +The number of values in the array pointed to by \fIobjPtr\fR; this is also the number of words in the command. .AP Tcl_Obj **objv in -Points to an array of pointers to objects; each object holds the +Points to an array of pointers to values; each value holds the value of a single word in the command to execute. .AP int numBytes in The number of bytes in \fIscript\fR, not including any @@ -85,7 +83,7 @@ If this is the first time \fIobjPtr\fR has been executed, its commands are compiled into bytecode instructions which are then executed. The bytecodes are saved in \fIobjPtr\fR so that the compilation step -can be skipped if the object is evaluated again in the future. +can be skipped if the value is evaluated again in the future. .PP The return value from \fBTcl_EvalObjEx\fR (and all the other procedures described here) is a Tcl completion code with @@ -113,15 +111,15 @@ which will be safely substituted by the Tcl interpreter into .PP \fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a script. The \fIobjc\fR and \fIobjv\fR arguments contain the values -of the words for the Tcl command, one word in each object in +of the words for the Tcl command, one word in each value in \fIobjv\fR. \fBTcl_EvalObjv\fR evaluates the command and returns a completion code and result just like \fBTcl_EvalObjEx\fR. The caller of \fBTcl_EvalObjv\fR has to manage the reference count of the -elements of \fIobjv\fR, insuring that the objects are valid until +elements of \fIobjv\fR, insuring that the values are valid until \fBTcl_EvalObjv\fR returns. .PP \fBTcl_Eval\fR is similar to \fBTcl_EvalObjEx\fR except that the script to -be executed is supplied as a string instead of an object and no compilation +be executed is supplied as a string instead of a value and no compilation occurs. The string should be a proper UTF-8 string as converted by \fBTcl_ExternalToUtfDString\fR or \fBTcl_ExternalToUtf\fR when it is known to possibly contain upper ASCII characters whose possible combinations @@ -131,7 +129,7 @@ bytecodes. In situations where it is known that the script will never be executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR. \fBTcl_Eval\fR returns a completion code and result just like \fBTcl_EvalObjEx\fR. Note: for backward compatibility with versions before -Tcl 8.0, \fBTcl_Eval\fR copies the object result in \fIinterp\fR to +Tcl 8.0, \fBTcl_Eval\fR copies the value result in \fIinterp\fR to \fIinterp->result\fR (use is deprecated) where it can be accessed directly. This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which does not do the copy. @@ -161,24 +159,27 @@ instead of taking a variable number of arguments it takes an argument list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated. .SH "FLAG BITS" +.PP Any ORed combination of the following values may be used for the \fIflags\fR argument to procedures such as \fBTcl_EvalObjEx\fR: .TP 23 \fBTCL_EVAL_DIRECT\fR +. This flag is only used by \fBTcl_EvalObjEx\fR; it is ignored by other procedures. If this flag bit is set, the script is not compiled to bytecodes; instead it is executed directly as is done by \fBTcl_EvalEx\fR. The \fBTCL_EVAL_DIRECT\fR flag is useful in situations where the -contents of an object are going to change immediately, so the +contents of a value are going to change immediately, so the bytecodes will not be reused in a future execution. In this case, it is faster to execute the script directly. .TP 23 \fBTCL_EVAL_GLOBAL\fR +. If this flag is set, the script is processed at global level. This means that it is evaluated in the global namespace and its variable context consists of global variables only (it ignores any Tcl -procedures at are active). +procedures that are active). .SH "MISCELLANEOUS DETAILS" .PP @@ -207,4 +208,4 @@ This means that top-level applications should never see a return code from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR. .SH KEYWORDS -execute, file, global, object, result, script +execute, file, global, result, script, value @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Exit.3,v 1.10 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH Tcl_Exit 3 8.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/ExprLong.3 b/doc/ExprLong.3 index 66f39ac..4fa972e 100644 --- a/doc/ExprLong.3 +++ b/doc/ExprLong.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ExprLong.3,v 1.15 2007/12/13 15:22:31 dgp Exp $ -'\" .so man.macros .TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures" .BS @@ -51,11 +49,11 @@ given by the \fIexpr\fR argument and return the result in one of four different forms. The expression can have any of the forms accepted by the \fBexpr\fR command. Note that these procedures have been largely replaced by the -object-based procedures \fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR, +value-based procedures \fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR, \fBTcl_ExprBooleanObj\fR, and \fBTcl_ExprObj\fR. -Those object-based procedures evaluate an expression held in a Tcl object +Those value-based procedures evaluate an expression held in a Tcl value instead of a string. -The object argument can retain an internal representation +The value argument can retain an internal representation that is more efficient to execute. .PP The \fIinterp\fR argument refers to an interpreter used to @@ -105,4 +103,4 @@ string stored in the interpreter's result. Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj .SH KEYWORDS -boolean, double, evaluate, expression, integer, object, string +boolean, double, evaluate, expression, integer, value, string diff --git a/doc/ExprLongObj.3 b/doc/ExprLongObj.3 index cf57921..686c1cb 100644 --- a/doc/ExprLongObj.3 +++ b/doc/ExprLongObj.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ExprLongObj.3,v 1.9 2007/12/13 15:22:31 dgp Exp $ -'\" .so man.macros .TH Tcl_ExprLongObj 3 8.0 Tcl "Tcl Library Procedures" .BS @@ -31,7 +29,7 @@ int .AP Tcl_Interp *interp in Interpreter in whose context to evaluate \fIobjPtr\fR. .AP Tcl_Obj *objPtr in -Pointer to an object containing the expression to evaluate. +Pointer to a value containing the expression to evaluate. .AP long *longPtr out Pointer to location in which to store the integer value of the expression. @@ -42,7 +40,7 @@ expression. Pointer to location in which to store the 0/1 boolean value of the expression. .AP Tcl_Obj **resultPtrPtr out -Pointer to location in which to store a pointer to the object +Pointer to location in which to store a pointer to the value that is the result of the expression. .BE @@ -95,14 +93,14 @@ or or else an error occurs. .PP If \fBTcl_ExprObj\fR successfully evaluates the expression, -it stores a pointer to the Tcl object +it stores a pointer to the Tcl value containing the expression's value at \fI*resultPtrPtr\fR. In this case, the caller is responsible for calling -\fBTcl_DecrRefCount\fR to decrement the object's reference count -when it is finished with the object. +\fBTcl_DecrRefCount\fR to decrement the value's reference count +when it is finished with the value. .SH "SEE ALSO" Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult .SH KEYWORDS -boolean, double, evaluate, expression, integer, object, string +boolean, double, evaluate, expression, integer, value, string diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index d53fccc..dd9eb77 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: FileSystem.3,v 1.72 2010/08/14 17:13:02 nijtmans Exp $ -'\" .so man.macros .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures" .BS @@ -88,7 +86,7 @@ int int \fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR) .sp -const char ** +const char *const * \fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR) .sp int @@ -194,8 +192,8 @@ int Points to a structure containing the addresses of procedures that can be called to perform the various filesystem operations. .AP Tcl_Obj *pathPtr in -The path represented by this object is used for the operation in -question. If the object does not already have an internal \fBpath\fR +The path represented by this value is used for the operation in +question. If the value does not already have an internal \fBpath\fR representation, it will be converted to have one. .AP Tcl_Obj *srcPathPtr in As for \fIpathPtr\fR, but used for the source file for a copy or @@ -215,12 +213,12 @@ this structure will be returned. This parameter may be NULL. Interpreter to use either for results, evaluation, or reporting error messages. .AP ClientData clientData in -The native description of the path object to create. +The native description of the path value to create. .AP Tcl_Obj *firstPtr in -The first of two path objects to compare. The object may be converted +The first of two path values to compare. The value may be converted to \fBpath\fR type. .AP Tcl_Obj *secondPtr in -The second of two path objects to compare. The object may be converted +The second of two path values to compare. The value may be converted to \fBpath\fR type. .AP Tcl_Obj *listObj in The list of path elements to operate on with a \fBjoin\fR operation. @@ -228,12 +226,12 @@ The list of path elements to operate on with a \fBjoin\fR operation. If non-negative, the number of elements in the \fIlistObj\fR which should be joined together. If negative, then all elements are joined. .AP Tcl_Obj **errorPtr out -In the case of an error, filled with an object containing the name of +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 Tcl_Obj **objPtrRef out -Filled with an object containing the result of the operation. +Filled with a value containing the result of the operation. .AP Tcl_Obj *resultPtr out -Pre-allocated object in which to store (using +Pre-allocated value in which to store (using \fBTcl_ListObjAppendElement\fR) the list of files or directories which are successfully matched. .AP int mode in @@ -333,17 +331,17 @@ buffer is actually declared to be, allowing the same code to be used both on systems with and systems without support for files larger than 2GB in size. .PP -The \fBTcl_FS\fR API is objectified and may cache internal +The \fBTcl_FS\fR API is \fBTcl_Obj\fR-ified and may cache internal representations and other path-related strings (e.g.\ the current working -directory). One side-effect of this is that one must not pass in objects +directory). One side-effect of this is that one must not pass in values with a reference count of zero to any of these functions. If such calls were handled, they might result in memory leaks (under some circumstances, the filesystem code may wish -to retain a reference to the passed in object, and so one must not assume -that after any of these calls return, the object still has a reference count of +to retain a reference to the passed in value, and so one must not assume +that after any of these calls return, the value still has a reference count of zero - it may have been incremented) or in a direct segmentation fault (or other memory access error) -due to the object being freed part way through the complex object +due to the value being freed part way through the complex value manipulation required to ensure that the path is fully normalized and absolute for filesystem determination. The practical lesson to learn from this is that @@ -356,9 +354,9 @@ Tcl_DecrRefCount(path); .PP is wrong, and may cause memory errors. The \fIpath\fR must have its reference count incremented before passing it in, or -decrementing it. For this reason, objects with a reference count of zero are +decrementing it. For this reason, values with a reference count of zero are considered not to be valid filesystem paths and calling any Tcl_FS API -function with such an object will result in no action being taken. +function with such a value will result in no action being taken. .SS "FS API FUNCTIONS" \fBTcl_FSCopyFile\fR attempts to copy the file given by \fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR. If the two paths given lie in the same @@ -486,7 +484,7 @@ If the \fItoPtr\fR is NULL, a action is performed. The result is a Tcl_Obj specifying the contents of the symbolic link given by \fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned -by the caller, which should call Tcl_DecrRefCount when the result is no +by the caller, which should call \fBTcl_DecrRefCount\fR when the result is no longer needed. If the \fItoPtr\fR is not NULL, Tcl should create a link of one of the types passed in in the \fIlinkAction\fR flag. This flag is an ORed combination of \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR. @@ -502,8 +500,9 @@ directories named in the path leading to the file. The \fITcl_StatBuf\fR structure includes info regarding device, inode (always 0 on Windows), privilege mode, nlink (always 1 on Windows), user id (always 0 on Windows), group id (always 0 on Windows), rdev (same as device on -Windows), size, last access time, last modification time, and creation -time. See \fBPORTABLE STAT RESULT API\fR for a description of how to write +Windows), size, last access time, last modification time, and +last metadata change time. +See \fBPORTABLE STAT RESULT API\fR for a description of how to write portable code to allocate and access the \fITcl_StatBuf\fR structure. .PP If \fIpath\fR exists, \fBTcl_FSLstat\fR returns 0 and the stat structure @@ -524,7 +523,7 @@ values of the file given. attributes\fR subcommand. The appropriate function for the filesystem to which \fIpathPtr\fR belongs will be called. .PP -If the result is \fBTCL_OK\fR, then an object was placed in +If the result is \fBTCL_OK\fR, then a value was placed in \fIobjPtrRef\fR, which will only be temporarily valid (unless \fBTcl_IncrRefCount\fR is called). .PP @@ -542,7 +541,7 @@ will take that list and first increment its reference count before using it. On completion of that use, Tcl will decrement its reference count. Hence if the list should be disposed of by Tcl when done, it should have a reference count of zero, and if the list should not be disposed of, the -filesystem should ensure it retains a reference count to the object. +filesystem should ensure it retains a reference count to the value. .PP \fBTcl_FSAccess\fR checks whether the process would be allowed to read, write or test for existence of the file (or other filesystem object) @@ -561,8 +560,9 @@ directories named in the path leading to the file. The \fITcl_StatBuf\fR structure includes info regarding device, inode (always 0 on Windows), privilege mode, nlink (always 1 on Windows), user id (always 0 on Windows), group id (always 0 on Windows), rdev (same as device on -Windows), size, last access time, last modification time, and creation -time. See \fBPORTABLE STAT RESULT API\fR for a description of how to write +Windows), size, last access time, last modification time, and +last metadata change time. +See \fBPORTABLE STAT RESULT API\fR for a description of how to write portable code to allocate and access the \fITcl_StatBuf\fR structure. .PP If \fIpath\fR exists, \fBTcl_FSStat\fR returns 0 and the stat structure @@ -582,7 +582,7 @@ In addition, if \fIinterp\fR is non-NULL, \fBTcl_FSOpenFileChannel\fR leaves an error message in \fIinterp\fR's result after any error. .PP The newly created channel is not registered in the supplied interpreter; to -register it, use \fBTcl_RegisterChannel\fR, described below. +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. @@ -622,35 +622,34 @@ The separator is returned as a Tcl_Obj containing a string of length .PP \fBTcl_FSJoinPath\fR takes the given Tcl_Obj, which must be a valid list (which is allowed to have a reference count of zero), and returns the path -object given by considering the first \fIelements\fR elements as valid path +value given by considering the first \fIelements\fR elements as valid path segments (each path segment may be a complete path, a partial path or just a single possible directory or file name). If any path segment is actually an absolute path, then all prior path segments are discarded. If \fIelements\fR is less than 0, we use the entire list. .PP -It is possible that the returned object is actually an element +It is possible that the returned value is actually an element of the given list, so the caller should be careful to increment the reference count of the result before freeing the list. .PP -The returned object, typically with a reference count of zero (but it +The returned value, typically with a reference count of zero (but it could be shared under some conditions), contains the joined path. The caller must -add a reference count to the object before using it. In particular, the -returned object could be an element of the given list, so freeing the -list might free the object prematurely if no reference count has been taken. -If the number of elements is zero, then the returned object will be +add a reference count to the value before using it. In particular, the +returned value could be an element of the given list, so freeing the +list might free the value prematurely if no reference count has been taken. +If the number of elements is zero, then the returned value will be an empty-string Tcl_Obj. .PP \fBTcl_FSSplitPath\fR takes the given Tcl_Obj, which should be a valid path, -and returns a Tcl list object containing each segment of that path as +and returns a Tcl list value containing each segment of that path as an element. -It returns a list object with a reference count of zero. If the +It returns a list value with a reference count of zero. If the passed in \fIlenPtr\fR is non-NULL, the variable it points to will be updated to contain the number of elements in the returned list. .PP \fBTcl_FSEqualPaths\fR tests whether the two paths given represent the same -filesystem object -.PP +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 @@ -658,7 +657,7 @@ either path is NULL, 0 is always returned. from the given Tcl_Obj a unique normalized path representation, whose string value can be used as a unique identifier for the file. .PP -It returns the normalized path object, owned by Tcl, or NULL if the path +It returns the normalized path value, owned by Tcl, or NULL if the path was invalid or could otherwise not be successfully converted. Extraction of absolute, normalized paths is very efficient (because the filesystem operates on these representations internally), although the @@ -666,35 +665,36 @@ result when the filesystem contains numerous symbolic links may not be the most user-friendly version of a path. The return value is owned by Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR passed in (unless that is a relative path, in which case the normalized path -object may be freed any time the cwd changes) - the caller can of -course increment the refCount if it wishes to maintain a copy for longer. +value may be freed any time the cwd changes) - the caller can of +course increment the reference count if it wishes to maintain a copy for longer. .PP -\fBTcl_FSJoinToPath\fR takes the given object, which should usually be a +\fBTcl_FSJoinToPath\fR takes the given value, which should usually be a valid path or NULL, and joins onto it the array of paths segments given. .PP -Returns object, typically with refCount of zero (but it could be shared +Returns a value, typically with reference count of zero (but it could be shared under some conditions), containing the joined path. The caller must -add a refCount to the object before using it. If any of the objects -passed into this function (pathPtr or path elements) have a refCount +add a reference count to the value before using it. If any of the values +passed into this function (\fIpathPtr\fR or \fIpath\fR elements) have +a reference count of zero, they will be freed when this function returns. .PP \fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid Tcl path type, taking account of the fact that the cwd may have changed -even if this object is already supposedly of the correct type. +even if this value is already supposedly of the correct type. The filename may begin with .QW ~ (to indicate current user's home directory) or .QW ~<user> (to indicate any user's home directory). .PP -If the conversion succeeds (i.e.\ the object is a valid path in one of +If the conversion succeeds (i.e.\ the value is a valid path in one of the current filesystems), then \fBTCL_OK\fR is returned. Otherwise \fBTCL_ERROR\fR is returned, and an error message may be left in the interpreter. .PP \fBTcl_FSGetInternalRep\fR extracts the internal representation of a given -path object, in the given filesystem. If the path object belongs to a +path value, in the given filesystem. If the path value belongs to a different filesystem, we return NULL. If the internal representation is currently NULL, we attempt to generate it, by calling the filesystem's \fBTcl_FSCreateInternalRepProc\fR. @@ -706,7 +706,7 @@ not require additional conversions. \fBTcl_FSGetTranslatedPath\fR attempts to extract the translated path from the given Tcl_Obj. .PP -If the translation succeeds (i.e.\ the object is a valid path), then it is +If the translation succeeds (i.e.\ the value is a valid path), then it is returned. Otherwise NULL will be returned, and an error message may be left in the interpreter. A .QW translated @@ -715,28 +715,28 @@ path is one which contains no or .QW ~user sequences (these have been expanded to their current -representation in the filesystem). The object returned is owned by the -caller, which must store it or call Tcl_DecrRefCount to ensure memory is +representation in the filesystem). The value returned is owned by the +caller, which must store it or call \fBTcl_DecrRefCount\fR to ensure memory is freed. This function is of little practical use, and -\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually +\fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually better functions to use for most purposes. .PP \fBTcl_FSGetTranslatedStringPath\fR does the same as \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL. The string returned is dynamically allocated and owned by the caller, which must store it or call \fBckfree\fR to ensure it is freed. Again, -\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually +\fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually better functions to use for most purposes. .PP \fBTcl_FSNewNativePath\fR performs something like the reverse of the usual obj->path->nativerep conversions. If some code retrieves a path in native form (from, e.g.\ \fBreadlink\fR or a native dialog), and that path is to be used at the Tcl level, then calling this function is an -efficient way of creating the appropriate path object type. +efficient way of creating the appropriate path value type. .PP -The resulting object is a pure +The resulting value is a pure .QW path -object, which will only receive +value, which will only receive a UTF-8 string representation if that is required by some Tcl code. .PP \fBTcl_FSGetNativePath\fR is for use by the Win/Unix native @@ -774,7 +774,7 @@ given path within that filesystem (which is filesystem dependent). The second element may be empty if the filesystem does not provide a further categorization of files. .PP -A valid list object is returned, unless the path object is not +A valid list value is returned, unless the path value is not recognized, when NULL will be returned. .PP \fBTcl_FSGetFileSystemForPath\fR returns a pointer to the @@ -792,7 +792,7 @@ It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or .PP \fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system heap (which 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 +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 @@ -1002,14 +1002,14 @@ The \fIversion\fR field should be set to \fBTCL_FILESYSTEM_VERSION_1\fR. .SS PATHINFILESYSTEMPROC .PP The \fIpathInFilesystemProc\fR field contains the address of a function -which is called to determine whether a given path object belongs to this +which is called to determine whether a given path value belongs to this filesystem or not. Tcl will only call the rest of the filesystem functions with a path for which this function has returned \fBTCL_OK\fR. -If the path does not belong, -1 should be returned (the behaviour of Tcl +If the path does not belong, -1 should be returned (the behavior of Tcl for any other return value is not defined). If \fBTCL_OK\fR is returned, then the optional \fIclientDataPtr\fR output parameter can be used to return an internal (filesystem specific) representation of the path, -which will be cached inside the path object, and may be retrieved +which will be cached inside the path value, and may be retrieved efficiently by the other filesystem functions. Tcl will simultaneously cache the fact that this path belongs to this filesystem. Such caches are invalidated when filesystem structures are added or removed from @@ -1023,7 +1023,7 @@ typedef int \fBTcl_FSPathInFilesystemProc\fR( .SS DUPINTERNALREPPROC .PP This function makes a copy of a path's internal representation, and is -called when Tcl needs to duplicate a path object. If NULL, Tcl will +called when Tcl needs to duplicate a path value. If NULL, Tcl will simply not copy the internal representation, which may then need to be regenerated later. .PP @@ -1043,8 +1043,8 @@ typedef void \fBTcl_FSFreeInternalRepProc\fR( .SS INTERNALTONORMALIZEDPROC .PP Function to convert internal representation to a normalized path. Only -required if the filesystem creates pure path objects with no string/path -representation. The return value is a Tcl object whose string +required if the filesystem creates pure path values with no string/path +representation. The return value is a Tcl value whose string representation is the normalized path. .PP .CS @@ -1053,9 +1053,9 @@ typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR( .CE .SS CREATEINTERNALREPPROC .PP -Function to take a path object, and calculate an internal +Function to take a path value, and calculate an internal representation for it, and store that native representation in the -object. May be NULL if paths have no internal representation, or if +value. May be NULL if paths have no internal representation, or if the \fITcl_FSPathInFilesystemProc\fR for this filesystem always immediately creates an internal representation for paths it accepts. .PP @@ -1067,7 +1067,7 @@ typedef ClientData \fBTcl_FSCreateInternalRepProc\fR( .PP Function to normalize a path. Should be implemented for all filesystems which can have multiple string representations for the same -path object. In Tcl, every +path value. In Tcl, every .QW path must have a single unique .QW normalized @@ -1079,7 +1079,7 @@ reference to a home directory such as .QW ~ , a path containing symbolic links, etc). If the very last component in the path is a symbolic -link, it should not be converted into the object it points to (but +link, it should not be converted into the value it points to (but its case or other aspects should be made unique). All other path components should be converted from symbolic links. This one exception is required to agree with Tcl's semantics with \fBfile @@ -1123,7 +1123,7 @@ which is returned. A typical return value might be or .QW ftp . The Tcl_Obj result is owned by the filesystem and so Tcl will -increment the refCount of that object if it wishes to retain a reference +increment the reference count of that value if it wishes to retain a reference to it. .PP .CS @@ -1138,7 +1138,7 @@ different separator than the standard string .QW / . Amongst other uses, it is returned by the \fBfile separator\fR command. The -return value should be an object with refCount of zero. +return value should be a value with reference count of zero. .PP .CS typedef Tcl_Obj *\fBTcl_FSFilesystemSeparatorProc\fR( @@ -1164,8 +1164,8 @@ to all directories named in the path leading to the file. The stat structure includes info regarding device, inode (always 0 on Windows), privilege mode, nlink (always 1 on Windows), user id (always 0 on Windows), group id (always 0 on Windows), rdev (same as device on -Windows), size, last access time, last modification time, and creation -time. +Windows), size, last access time, last modification time, and +last metadata change time. .PP If the file represented by \fIpathPtr\fR exists, the \fBTcl_FSStatProc\fR returns 0 and the stat structure is filled with @@ -1219,8 +1219,9 @@ In addition, if \fIinterp\fR is non-NULL, the \fBTcl_FSOpenFileChannelProc\fR leaves an error message in \fIinterp\fR's result after any error. .PP -The newly created channel is not registered in the supplied -interpreter; to register it, use \fBTcl_RegisterChannel\fR. If one of +The newly created channel must not be registered in the supplied interpreter +by a \fBTcl_FSOpenFileChannelProc\fR; that task is up to the caller of +\fBTcl_FSOpenFileChannel\fR (if necessary). 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. @@ -1256,7 +1257,7 @@ The return value is a standard Tcl result indicating whether an error occurred in the matching process. Error messages are placed in \fIinterp\fR, unless \fIinterp\fR in NULL in which case no error message need be generated; on a \fBTCL_OK\fR result, results should be -added to the \fIresultPtr\fR object given (which can be assumed to be a +added to the \fIresultPtr\fR value given (which can be assumed to be a valid unshared Tcl list). The matches added to \fIresultPtr\fR should include any path prefix given in \fIpathPtr\fR (this usually means they will be absolute path specifications). @@ -1326,7 +1327,7 @@ contents of a link. The result is a Tcl_Obj specifying the contents of the link given by \fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned by the caller (and should therefore have its ref count incremented before being returned). Any callers -should call Tcl_DecrRefCount on this result when it is no longer needed. +should call \fBTcl_DecrRefCount\fR on this result when it is no longer needed. If \fItoPtr\fR is not NULL, the function should attempt to create a link. The result in this case should be \fItoPtr\fR if the link was successful and NULL otherwise. In this case the result is not owned by the caller @@ -1344,16 +1345,16 @@ typedef Tcl_Obj *\fBTcl_FSListVolumesProc\fR(void); .CE .PP The result should be a list of volumes added by this filesystem, or -NULL (or an empty list) if no volumes are provided. The result object +NULL (or an empty list) if no volumes are provided. The result value is considered to be owned by the filesystem (not by Tcl's core), but -should be given a refCount for Tcl. Tcl will use the contents of the -list and then decrement that refCount. This allows filesystems to +should be given a reference count for Tcl. Tcl will use the contents of the +list and then decrement that reference count. This allows filesystems to choose whether they actually want to retain a .QW "master list" of volumes or not (if not, they generate the list on the fly and pass it to Tcl -with a refCount of 1 and then forget about the list, if yes, then -they simply increment the refCount of their master list and pass it +with a reference count of 1 and then forget about the list, if yes, then +they simply increment the reference count of their master list and pass it to Tcl which will copy the contents and then decrement the count back to where it was). .PP @@ -1379,7 +1380,7 @@ will take that list and first increment its reference count before using it. On completion of that use, Tcl will decrement its reference count. Hence if the list should be disposed of by Tcl when done, it should have a reference count of zero, and if the list should not be disposed of, the -filesystem should ensure it returns an object with a reference count +filesystem should ensure it returns a value with a reference count of at least one. .SS FILEATTRSGETPROC .PP diff --git a/doc/FindExec.3 b/doc/FindExec.3 index 10a3c72..e4b4ed0 100644 --- a/doc/FindExec.3 +++ b/doc/FindExec.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: FindExec.3,v 1.7 2004/10/07 15:15:38 dkf Exp $ -'\" .so man.macros .TH Tcl_FindExecutable 3 8.1 Tcl "Tcl Library Procedures" .BS @@ -47,6 +45,13 @@ application's executable, if possible. If it fails to find the binary, then future calls to \fBinfo nameofexecutable\fR will return an empty string. .PP +On Windows platforms this procedure is typically invoked as the very +first thing in the application's main program as well; Its \fIargv[0]\fR +argument is only used to indicate whether the executable has a stderr +channel (any non-null value) or not (the value null). If \fBTcl_SetPanicProc\fR +is never called and no debugger is running, this determines whether +the panic message is sent to stderr or to a standard system dialog. +.PP \fBTcl_GetNameOfExecutable\fR simply returns a pointer to the internal full path name of the executable file as computed by \fBTcl_FindExecutable\fR. This procedure call is the C API diff --git a/doc/GetCwd.3 b/doc/GetCwd.3 index d333fca..964e237 100755 --- a/doc/GetCwd.3 +++ b/doc/GetCwd.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: GetCwd.3,v 1.9 2007/12/13 15:22:31 dgp Exp $ -'\" .so man.macros .TH Tcl_GetCwd 3 8.1 Tcl "Tcl Library Procedures" .BS diff --git a/doc/GetHostName.3 b/doc/GetHostName.3 index 37252dc..28f3a4f 100644 --- a/doc/GetHostName.3 +++ b/doc/GetHostName.3 @@ -2,8 +2,6 @@ '\" Copyright (c) 1998-2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: GetHostName.3,v 1.4 2004/10/07 15:15:38 dkf Exp $ -'\" .so man.macros .TH Tcl_GetHostName 3 8.3 Tcl "Tcl Library Procedures" .BS diff --git a/doc/GetIndex.3 b/doc/GetIndex.3 index 7d138eb..d32561a 100644 --- a/doc/GetIndex.3 +++ b/doc/GetIndex.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: GetIndex.3,v 1.24 2008/10/19 16:22:20 dkf Exp $ -'\" .so man.macros .TH Tcl_GetIndexFromObj 3 8.1 Tcl "Tcl Library Procedures" .BS @@ -28,16 +26,22 @@ int 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 object is used to search through \fItablePtr\fR. +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 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 +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 +internal representation of \fIobjPtr\fR, so this should represent the +address of a statically-allocated array of structures. .AP int offset in The offset to add to structTablePtr to get to the next entry. The end of the array is marked by a NULL string pointer. @@ -53,10 +57,10 @@ The index of the string in \fItablePtr\fR that matches the value of .BE .SH DESCRIPTION .PP -This procedure provides an efficient way for looking up keywords, -switch names, option names, and similar things where the value of -an object must be one of a predefined set of values. -\fIObjPtr\fR is compared against each of +These procedures provide an efficient way for looking up keywords, +switch names, option names, and similar things where the literal value of +a Tcl value must be chosen from a predefined set. +\fBTcl_GetIndexFromObj\fR compares \fIobjPtr\fR against each of the strings in \fItablePtr\fR to find a match. A match occurs if \fIobjPtr\fR's string value is identical to one of the strings in \fItablePtr\fR, or if it is a non-empty unique abbreviation @@ -97,4 +101,4 @@ each of several array elements. .SH "SEE ALSO" prefix(n), Tcl_WrongNumArgs(3) .SH KEYWORDS -index, object, table lookup +index, option, value, table lookup diff --git a/doc/GetInt.3 b/doc/GetInt.3 index 00ce1c9..f77d337 100644 --- a/doc/GetInt.3 +++ b/doc/GetInt.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: GetInt.3,v 1.14 2007/12/13 15:22:31 dgp Exp $ -'\" .so man.macros .TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures" .BS diff --git a/doc/GetOpnFl.3 b/doc/GetOpnFl.3 index 45271ad..38aa976 100644 --- a/doc/GetOpnFl.3 +++ b/doc/GetOpnFl.3 @@ -4,7 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: GetOpnFl.3,v 1.14 2007/12/13 15:22:31 dgp Exp $ .so man.macros .TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures" .BS diff --git a/doc/GetStdChan.3 b/doc/GetStdChan.3 index fb91517..e76ad66 100644 --- a/doc/GetStdChan.3 +++ b/doc/GetStdChan.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: GetStdChan.3,v 1.9 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures" .BS @@ -79,7 +77,7 @@ assigned starting with standard input, followed by standard output, with standard error being last. .PP See \fBTcl_StandardChannels\fR for a general treatise about standard -channels and the behaviour of the Tcl library with regard to them. +channels and the behavior of the Tcl library with regard to them. .SH "SEE ALSO" Tcl_Close(3), Tcl_CreateChannel(3), Tcl_Main(3), tclsh(1) diff --git a/doc/GetTime.3 b/doc/GetTime.3 index be6c1ba..f4da364 100644 --- a/doc/GetTime.3 +++ b/doc/GetTime.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id$ -'\" .so man.macros .TH Tcl_GetTime 3 8.4 Tcl "Tcl Library Procedures" .BS @@ -92,21 +90,19 @@ typedef void \fBTcl_ScaleTimeProc\fR( .CE .PP The \fItimebuf\fR fields contain the time to manipulate, and the -\fIclientData\fR fields contain a pointer supplied at the time the -handler functions were registered. +\fIclientData\fR fields contain a pointer supplied at the time the handler +functions were registered. .PP -Any handler pair specified has to return data which is consistent -between them. In other words, setting one handler of the pair to -something assuming a 10-times slowdown, and the other handler of the -pair to something assuming a two-times slowdown is wrong and not -allowed. +Any handler pair specified has to return data which is consistent between +them. In other words, setting one handler of the pair to something assuming a +10-times slowdown, and the other handler of the pair to something assuming a +two-times slowdown is wrong and not allowed. .PP -The set handler functions are allowed to run the delivered time -backwards, however this should be avoided. We have to allow it as the -native time can run backwards as the user can fiddle with the system -time one way or other. Note that the insertion of the hooks will not -change the behaviour of the Tcl core with regard to this situation, -i.e. the existing behaviour is retained. +The set handler functions are allowed to run the delivered time backwards, +however this should be avoided. We have to allow it as the native time can run +backwards as the user can fiddle with the system time one way or other. Note +that the insertion of the hooks will not change the behavior of the Tcl core +with regard to this situation, i.e. the existing behavior is retained. .SH "SEE ALSO" clock(n) .SH KEYWORDS diff --git a/doc/GetVersion.3 b/doc/GetVersion.3 index 8082425..47034d0 100755 --- a/doc/GetVersion.3 +++ b/doc/GetVersion.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: GetVersion.3,v 1.4 2004/10/07 14:44:32 dkf Exp $ -'\" .so man.macros .TH Tcl_GetVersion 3 7.5 Tcl "Tcl Library Procedures" .BS @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Hash.3,v 1.34 2010/08/14 20:58:30 nijtmans Exp $ -'\" .so man.macros .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" .BS @@ -59,7 +57,7 @@ Kind of keys to use for new hash table. Must be either \fBTCL_STRING_KEYS\fR, \fBTCL_ONE_WORD_KEYS\fR, \fBTCL_CUSTOM_TYPE_KEYS\fR, \fBTCL_CUSTOM_PTR_KEYS\fR, or an integer value greater than 1. .AP Tcl_HashKeyType *typePtr in -Address of structure which defines the behaviour of the hash table. +Address of structure which defines the behavior of the hash table. .AP "const void" *key in Key to use for probe into table. Exact form depends on \fIkeyType\fR used to create table. @@ -312,14 +310,14 @@ typedef Tcl_HashEntry *\fBTcl_AllocHashEntryProc\fR( void *\fIkeyPtr\fR); .CE .PP -If this is NULL then Tcl_Alloc is used to allocate enough space for a +If this is NULL then \fBTcl_Alloc\fR is used to allocate enough space for a Tcl_HashEntry, the key pointer is assigned to key.oneWordValue and the clientData is set to NULL. String keys and array keys use this function to allocate enough space for the entry and the key in one block, rather than doing it in two blocks. This saves space for a pointer to the key from the entry and another memory allocation. Tcl_Obj* keys use this function to allocate enough space for an entry and increment the reference count on the -object. +value. .PP The \fIfreeEntryProc\fR member contains the address of a function called to free space for an entry. @@ -329,8 +327,8 @@ typedef void \fBTcl_FreeHashEntryProc\fR( Tcl_HashEntry *\fIhPtr\fR); .CE .PP -If this is NULL then Tcl_Free is used to free the space for the entry. +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 -object. +value. .SH KEYWORDS hash table, key, lookup, search, value @@ -2,8 +2,6 @@ '\" Copyright (c) 1998-2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: Init.3,v 1.6 2007/12/13 15:22:31 dgp Exp $ -'\" .so man.macros .TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures" .BS diff --git a/doc/InitStubs.3 b/doc/InitStubs.3 index 0c42814..5f56278 100644 --- a/doc/InitStubs.3 +++ b/doc/InitStubs.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: InitStubs.3,v 1.11 2004/10/07 15:15:38 dkf Exp $ -'\" .so man.macros .TH Tcl_InitStubs 3 8.1 Tcl "Tcl Library Procedures" .BS @@ -65,9 +63,9 @@ Define the \fBUSE_TCL_STUBS\fR symbol. Typically, you would include the \fB\-DUSE_TCL_STUBS\fR flag when compiling the extension. .IP 3) 5 Link the extension with the Tcl stubs library instead of the standard -Tcl library. On Unix platforms, the library name is -\fIlibtclstub8.1.a\fR; on Windows platforms, the library name is -\fItclstub81.lib\fR. +Tcl library. For example, to use the Tcl 8.1 ABI on Unix platforms, +the library name is \fIlibtclstub8.1.a\fR; on Windows platforms, the +library name is \fItclstub81.lib\fR. .PP If the extension also requires the Tk API, it must also call \fBTk_InitStubs\fR to initialize the Tk stubs interface and link diff --git a/doc/IntObj.3 b/doc/IntObj.3 index 99e6ab6..4b7b8a6 100644 --- a/doc/IntObj.3 +++ b/doc/IntObj.3 @@ -4,13 +4,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: IntObj.3,v 1.17 2009/11/27 14:35:10 dkf Exp $ -'\" .so man.macros .TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures" .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 objects as integer values +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 .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -58,17 +56,17 @@ int .SH ARGUMENTS .AS Tcl_WideInt doubleValue in/out .AP int intValue in -Integer value used to initialize or set a Tcl object. +Integer value used to initialize or set a Tcl value. .AP long longValue in -Long integer value used to initialize or set a Tcl object. +Long integer value used to initialize or set a Tcl value. .AP Tcl_WideInt wideValue in -Wide integer value used to initialize or set a Tcl object. +Wide integer value used to initialize or set a Tcl value. .AP Tcl_Obj *objPtr in/out For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR, -and \fBTcl_SetBignumObj\fR, this points to the object in which to store an +and \fBTcl_SetBignumObj\fR, this points to the value in which to store an integral value. For \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR, \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and -\fBTcl_TakeBignumFromObj\fR, this refers to the object from which +\fBTcl_TakeBignumFromObj\fR, this refers to the value from which to retrieve an integral value. .AP Tcl_Interp *interp in/out When non-NULL, an error message is left here when integral value @@ -88,7 +86,7 @@ used to initialize a multi-precision integer value. .BE .SH DESCRIPTION .PP -These procedures are used to create, modify, and read Tcl objects +These procedures are used to create, modify, and read Tcl values that hold integral values. .PP The different routines exist to accommodate different integral types in C @@ -105,22 +103,22 @@ by the LibTomMath multiple-precision integer library. .PP The \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR, and \fBTcl_NewBignumObj\fR routines each create and return a new -Tcl object initialized to the integral value of the argument. The -returned Tcl object is unshared. +Tcl value initialized to the integral value of the argument. The +returned Tcl value is unshared. .PP The \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR, and \fBTcl_SetBignumObj\fR routines each set the value of an existing -Tcl object pointed to by \fIobjPtr\fR to the integral value provided +Tcl value pointed to by \fIobjPtr\fR to the integral value provided by the other argument. The \fIobjPtr\fR argument must point to an -unshared Tcl object. Any attempt to set the value of a shared Tcl object +unshared Tcl value. Any attempt to set the value of a shared Tcl value violates Tcl's copy-on-write policy. Any existing string representation -or internal representation in the unshared Tcl object will be freed +or internal representation in the unshared Tcl value will be freed as a consequence of setting the new value. .PP The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR, \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral -value of the appropriate type from the Tcl object \fIobjPtr\fR. If the +value of the appropriate type 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 integral value, or if the @@ -129,7 +127,7 @@ 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. Unlike the other functions, -\fBTcl_TakeBignumFromObj\fR may set the content of the Tcl object +\fBTcl_TakeBignumFromObj\fR may set the content of the Tcl value \fIobjPtr\fR to an empty string in the process of retrieving the multiple-precision integer value. .PP @@ -150,4 +148,5 @@ integer value in the \fBmp_int\fR value \fIbigValue\fR. .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult .SH KEYWORDS -integer, integer object, integer type, internal representation, object, object type, string representation +integer, integer value, integer type, internal representation, value, +value type, string representation diff --git a/doc/Interp.3 b/doc/Interp.3 index 4f0a250..d908057 100644 --- a/doc/Interp.3 +++ b/doc/Interp.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Interp.3,v 1.15 2008/12/15 18:33:25 dgp Exp $ -'\" .so man.macros .TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/Limit.3 b/doc/Limit.3 index be4373d..2941ee8 100644 --- a/doc/Limit.3 +++ b/doc/Limit.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Limit.3,v 1.9 2009/11/27 14:35:10 dkf Exp $ -'\" .so man.macros .TH Tcl_LimitCheck 3 8.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/LinkVar.3 b/doc/LinkVar.3 index 3801026..dc71a45 100644 --- a/doc/LinkVar.3 +++ b/doc/LinkVar.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: LinkVar.3,v 1.19 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/ListObj.3 b/doc/ListObj.3 index 6215fc2..bc6917d 100644 --- a/doc/ListObj.3 +++ b/doc/ListObj.3 @@ -4,13 +4,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ListObj.3,v 1.13 2008/12/18 21:23:47 dkf Exp $ -'\" .so man.macros .TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace \- manipulate Tcl objects as lists +Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace \- manipulate Tcl values as lists .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -40,44 +38,44 @@ int .SH ARGUMENTS .AS "Tcl_Obj *const" *elemListPtr in/out .AP Tcl_Interp *interp in -If an error occurs while converting an object to be a list object, -an error message is left in the interpreter's result object +If an error occurs while converting a value to be a list value, +an error message is left in the interpreter's result value unless \fIinterp\fR is NULL. .AP Tcl_Obj *listPtr in/out -Points to the list object to be manipulated. -If \fIlistPtr\fR does not already point to a list object, +Points to the list value to be manipulated. +If \fIlistPtr\fR does not already point to a list value, an attempt will be made to convert it to one. .AP Tcl_Obj *elemListPtr in/out -For \fBTcl_ListObjAppendList\fR, this points to a list object +For \fBTcl_ListObjAppendList\fR, this points to a list value containing elements to be appended onto \fIlistPtr\fR. Each element of *\fIelemListPtr\fR will become a new element of \fIlistPtr\fR. If *\fIelemListPtr\fR is not NULL and -does not already point to a list object, +does not already point to a list value, an attempt will be made to convert it to one. .AP Tcl_Obj *objPtr in For \fBTcl_ListObjAppendElement\fR, -points to the Tcl object that will be appended to \fIlistPtr\fR. +points to the Tcl value that will be appended to \fIlistPtr\fR. For \fBTcl_SetListObj\fR, -this points to the Tcl object that will be converted to a list object +this points to the Tcl value that will be converted to a list value containing the \fIobjc\fR elements of the array referenced by \fIobjv\fR. .AP int *objcPtr in Points to location where \fBTcl_ListObjGetElements\fR -stores the number of element objects in \fIlistPtr\fR. +stores the number of element values in \fIlistPtr\fR. .AP Tcl_Obj ***objvPtr out A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array -of pointers to the element objects of \fIlistPtr\fR. +of pointers to the element values of \fIlistPtr\fR. .AP int objc in -The number of Tcl objects that \fBTcl_NewListObj\fR -will insert into a new list object, +The number of Tcl values that \fBTcl_NewListObj\fR +will insert into a new list value, and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR. For \fBTcl_SetListObj\fR, -the number of Tcl objects to insert into \fIobjPtr\fR. +the number of Tcl values to insert into \fIobjPtr\fR. .AP "Tcl_Obj *const" objv[] in -An array of pointers to objects. -\fBTcl_NewListObj\fR will insert these objects into a new list object +An array of pointers to values. +\fBTcl_NewListObj\fR will insert these values into a new list value and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR. -Each object will become a separate list element. +Each value will become a separate list element. .AP int *intPtr out Points to location where \fBTcl_ListObjLength\fR stores the length of the list. @@ -87,7 +85,7 @@ is to return. The first element has index 0. .AP Tcl_Obj **objPtrPtr out Points to place where \fBTcl_ListObjIndex\fR is to store -a pointer to the resulting list element object. +a pointer to the resulting list element value. .AP int first in Index of the starting list element that \fBTcl_ListObjReplace\fR is to replace. @@ -99,85 +97,85 @@ is to replace. .SH DESCRIPTION .PP -Tcl list objects have an internal representation that supports +Tcl list values have an internal representation that supports the efficient indexing and appending. The procedures described in this man page are used to -create, modify, index, and append to Tcl list objects from C code. +create, modify, index, and append to Tcl list values from C code. .PP \fBTcl_ListObjAppendList\fR and \fBTcl_ListObjAppendElement\fR -both add one or more objects -to the end of the list object referenced by \fIlistPtr\fR. -\fBTcl_ListObjAppendList\fR appends each element of the list object +both add one or more values +to the end of the list value referenced by \fIlistPtr\fR. +\fBTcl_ListObjAppendList\fR appends each element of the list value referenced by \fIelemListPtr\fR while -\fBTcl_ListObjAppendElement\fR appends the single object +\fBTcl_ListObjAppendElement\fR appends the single value referenced by \fIobjPtr\fR. -Both procedures will convert the object referenced by \fIlistPtr\fR -to a list object if necessary. +Both procedures will convert the value referenced by \fIlistPtr\fR +to a list value if necessary. If an error occurs during conversion, both procedures return \fBTCL_ERROR\fR and leave an error message -in the interpreter's result object if \fIinterp\fR is not NULL. -Similarly, if \fIelemListPtr\fR does not already refer to a list object, +in the interpreter's result value if \fIinterp\fR is not NULL. +Similarly, if \fIelemListPtr\fR does not already refer to a list value, \fBTcl_ListObjAppendList\fR will attempt to convert it to one and if an error occurs during conversion, will return \fBTCL_ERROR\fR -and leave an error message in the interpreter's result object +and leave an error message in the interpreter's result value if interp is not NULL. Both procedures invalidate any old string representation of \fIlistPtr\fR -and, if it was converted to a list object, +and, if it was converted to a list value, free any old internal representation. Similarly, \fBTcl_ListObjAppendList\fR frees any old internal representation -of \fIelemListPtr\fR if it converts it to a list object. +of \fIelemListPtr\fR if it converts it to a list value. After appending each element in \fIelemListPtr\fR, \fBTcl_ListObjAppendList\fR increments the element's reference count since \fIlistPtr\fR now also refers to it. For the same reason, \fBTcl_ListObjAppendElement\fR increments \fIobjPtr\fR's reference count. If no error occurs, -the two procedures return \fBTCL_OK\fR after appending the objects. +the two procedures return \fBTCL_OK\fR after appending the values. .PP \fBTcl_NewListObj\fR and \fBTcl_SetListObj\fR -create a new object or modify an existing object to hold +create a new value or modify an existing value to hold the \fIobjc\fR elements of the array referenced by \fIobjv\fR -where each element is a pointer to a Tcl object. +where each element is a pointer to a Tcl value. If \fIobjc\fR is less than or equal to zero, -they return an empty object. -The new object's string representation is left invalid. +they return an empty value. +The new value's string representation is left invalid. The two procedures increment the reference counts -of the elements in \fIobjc\fR since the list object now refers to them. -The new list object returned by \fBTcl_NewListObj\fR +of the elements in \fIobjc\fR since the list value now refers to them. +The new list value returned by \fBTcl_NewListObj\fR has reference count zero. .PP \fBTcl_ListObjGetElements\fR returns a count and a pointer to an array of -the elements in a list object. It returns the count by storing it in the +the elements in a list value. It returns the count by storing it in the address \fIobjcPtr\fR. Similarly, it returns the array pointer by storing it in the address \fIobjvPtr\fR. The memory pointed to is managed by Tcl and should not be freed or written to by the caller. If the list is empty, 0 is stored at \fIobjcPtr\fR and NULL at \fIobjvPtr\fR. -If \fIlistPtr\fR is not already a list object, \fBTcl_ListObjGetElements\fR +If \fIlistPtr\fR is not already a list value, \fBTcl_ListObjGetElements\fR will attempt to convert it to one; if the conversion fails, it returns \fBTCL_ERROR\fR and leaves an error message in the interpreter's result -object if \fIinterp\fR is not NULL. +value if \fIinterp\fR is not NULL. Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer. .PP -\fBTcl_ListObjLength\fR returns the number of elements in the list object +\fBTcl_ListObjLength\fR returns the number of elements in the list value referenced by \fIlistPtr\fR. It returns this count by storing an integer in the address \fIintPtr\fR. -If the object is not already a list object, +If the value is not already a list value, \fBTcl_ListObjLength\fR will attempt to convert it to one; if the conversion fails, it returns \fBTCL_ERROR\fR -and leaves an error message in the interpreter's result object +and leaves an error message in the interpreter's result value if \fIinterp\fR is not NULL. Otherwise it returns \fBTCL_OK\fR after storing the list's length. .PP -The procedure \fBTcl_ListObjIndex\fR returns a pointer to the object +The procedure \fBTcl_ListObjIndex\fR returns a pointer to the value at element \fIindex\fR in the list referenced by \fIlistPtr\fR. -It returns this object by storing a pointer to it +It returns this value by storing a pointer to it in the address \fIobjPtrPtr\fR. -If \fIlistPtr\fR does not already refer to a list object, +If \fIlistPtr\fR does not already refer to a list value, \fBTcl_ListObjIndex\fR will attempt to convert it to one; if the conversion fails, it returns \fBTCL_ERROR\fR -and leaves an error message in the interpreter's result object +and leaves an error message in the interpreter's result value if \fIinterp\fR is not NULL. If the index is out of range, that is, \fIindex\fR is negative or @@ -185,19 +183,19 @@ greater than or equal to the number of elements in the list, \fBTcl_ListObjIndex\fR stores a NULL in \fIobjPtrPtr\fR and returns \fBTCL_OK\fR. Otherwise it returns \fBTCL_OK\fR after storing the element's -object pointer. +value pointer. The reference count for the list element is not incremented; the caller must do that if it needs to retain a pointer to the element. .PP \fBTcl_ListObjReplace\fR replaces zero or more elements of the list referenced by \fIlistPtr\fR -with the \fIobjc\fR objects in the array referenced by \fIobjv\fR. -If \fIlistPtr\fR does not point to a list object, +with the \fIobjc\fR values in the array referenced by \fIobjv\fR. +If \fIlistPtr\fR does not point to a list value, \fBTcl_ListObjReplace\fR will attempt to convert it to one; if the conversion fails, it returns \fBTCL_ERROR\fR -and leaves an error message in the interpreter's result object +and leaves an error message in the interpreter's result value if \fIinterp\fR is not NULL. -Otherwise, it returns \fBTCL_OK\fR after replacing the objects. +Otherwise, it returns \fBTCL_OK\fR after replacing the values. If \fIobjv\fR is NULL, no new elements are added. If the argument \fIfirst\fR is zero or negative, it refers to the first element. @@ -212,13 +210,13 @@ designated by \fIfirst\fR. old string representation. The reference counts of any elements inserted from \fIobjv\fR are incremented since the resulting list now refers to them. -Similarly, the reference counts for any replaced objects are decremented. +Similarly, the reference counts for any replaced values are decremented. .PP Because \fBTcl_ListObjReplace\fR combines both element insertion and deletion, it can be used to implement a number of list operations. -For example, the following code inserts the \fIobjc\fR objects -referenced by the array of object pointers \fIobjv\fR +For example, the following code inserts the \fIobjc\fR values +referenced by the array of value pointers \fIobjv\fR just before the element \fIindex\fR of the list referenced by \fIlistPtr\fR: .PP .CS @@ -226,7 +224,7 @@ result = \fBTcl_ListObjReplace\fR(interp, listPtr, index, 0, objc, objv); .CE .PP -Similarly, the following code appends the \fIobjc\fR objects +Similarly, the following code appends the \fIobjc\fR values referenced by the array \fIobjv\fR to the end of the list \fIlistPtr\fR: .PP @@ -249,4 +247,5 @@ result = \fBTcl_ListObjReplace\fR(interp, listPtr, first, count, .SH "SEE ALSO" Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_GetObjResult(3) .SH KEYWORDS -append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation +append, index, insert, internal representation, length, list, list value, +list type, value, value type, replace, string representation @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Load.3,v 1.3 2010/04/06 12:51:44 dkf Exp $ -'\" .so man.macros .TH Load 3 8.6 Tcl "Tcl Library Procedures" .BS @@ -33,7 +31,8 @@ Array of names of symbols to be resolved during the load of the library, or NULL if no symbols are to be resolved. If an array is given, the last entry in the array must be NULL. .AP int flags in -Reserved for future expansion. Must be 0. +The value should normally be 0, but \fITCL_LOAD_GLOBAL\fR or \fITCL_LOAD_LAZY\fR +or a combination of those two is allowed as well. .AP void *procPtrs out Points to an array that will hold the addresses of the functions described in the \fIsymbols\fR argument. Should be NULL if no symbols are to be resolved. diff --git a/doc/Method.3 b/doc/Method.3 index 79e9b9f..43b3609 100644 --- a/doc/Method.3 +++ b/doc/Method.3 @@ -4,14 +4,12 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Method.3,v 1.5 2010/08/20 23:01:27 nijtmans Exp $ -'\" .so man.macros .TH Tcl_Method 3 0.1 TclOO "TclOO Library Functions" .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_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts +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 .SH SYNOPSIS .nf \fB#include <tclOO.h>\fR @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: NRE.3,v 1.8 2010/01/10 12:32:51 dkf Exp $ -'\" .so man.macros .TH NRE 3 8.6 Tcl "Tcl Library Procedures" .BS @@ -59,7 +57,7 @@ is \fBNULL\fR, then no procedure is called before the command is deleted. .AP int objc in Count of parameters provided to the implementation of a command. .AP Tcl_Obj **objv in -Pointer to an array of Tcl objects. Each object holds the value of a +Pointer to an array of Tcl values. Each value holds the value of a single word in the command to execute. .AP Tcl_Obj *objPtr in Pointer to a Tcl_Obj whose value is a script or expression to execute. @@ -143,7 +141,7 @@ trampoline. .PP \fBTcl_NRCmdSwap\fR allows for trampoline evaluation of a command whose resolution is already known. The \fIcmd\fR parameter gives a -\fBTcl_Command\fR object (returned from \fBTcl_CreateObjCmd\fR or +\fBTcl_Command\fR token (returned from \fBTcl_CreateObjCommand\fR or \fBTcl_GetCommandFromObj\fR) identifying the command to be invoked in the trampoline; this command must match the word in \fIobjv[0]\fR. The remaining arguments are as for \fBTcl_NREvalObj\fR. @@ -297,7 +295,7 @@ int int result) { /* \fIdata[0] .. data[3]\fR are the four words of data - * passed to \fBTcl_NREvalObj\fR */ + * passed to \fBTcl_NRAddCallback\fR */ \fI... postprocessing ...\fR @@ -325,6 +323,6 @@ and the second is for use when there is already a trampoline in place. .SH "SEE ALSO" Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3) .SH KEYWORDS -stackless, nonrecursive, execute, command, global, object, result, script +stackless, nonrecursive, execute, command, global, value, result, script .SH COPYRIGHT Copyright (c) 2008 by Kevin B. Kenny diff --git a/doc/Namespace.3 b/doc/Namespace.3 index 629eba9..2b47128 100644 --- a/doc/Namespace.3 +++ b/doc/Namespace.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Namespace.3,v 1.11 2008/10/17 10:22:25 dkf Exp $ -'\" '\" Note that some of these functions do not seem to belong, but they '\" were all introduced with the same TIP (#139) '\" @@ -69,7 +67,7 @@ if no such callback is to be performed. The namespace to be manipulated, or NULL (for other than \fBTcl_DeleteNamespace\fR) to manipulate the current namespace. .AP Tcl_Obj *objPtr out -A reference to an unshared object to which the function output will be +A reference to an unshared value to which the function output will be written. .AP "const char" *pattern in The glob-style pattern (see \fBTcl_StringMatch\fR) that describes the @@ -162,6 +160,6 @@ for the namespace, or NULL if none is set. the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to its default. .SH "SEE ALSO" -Tcl_CreateCommand(3), Tcl_ListObjAppendElements(3), Tcl_SetVar(3) +Tcl_CreateCommand(3), Tcl_ListObjAppendList(3), Tcl_SetVar(3) .SH KEYWORDS namespace, command diff --git a/doc/Notifier.3 b/doc/Notifier.3 index 8239d8d..f65d580 100644 --- a/doc/Notifier.3 +++ b/doc/Notifier.3 @@ -5,13 +5,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Notifier.3,v 1.25 2008/12/18 21:23:47 dkf Exp $ -'\" .so man.macros .TH Notifier 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces +Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode, Tcl_ServiceModeHook, Tcl_SetNotifier \- the event queue and notifier interfaces .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -413,7 +411,7 @@ 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 -Tcl_ThreadID for the current thread, use the \fBTcl_GetCurrentThread\fR +Tcl_ThreadId for the current thread, use the \fBTcl_GetCurrentThread\fR procedure. (A thread would then need to pass this identifier to other threads for those threads to be able to add events to its queue.) After adding an event to another thread's queue, you then typically diff --git a/doc/Object.3 b/doc/Object.3 index 9992653..3d52f61 100644 --- a/doc/Object.3 +++ b/doc/Object.3 @@ -4,13 +4,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Object.3,v 1.23 2008/12/18 21:23:47 dkf Exp $ -'\" .so man.macros .TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl objects +Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl values .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -32,35 +30,36 @@ int .SH ARGUMENTS .AS Tcl_Obj *objPtr .AP Tcl_Obj *objPtr in -Points to an object; +Points to a value; must have been the result of a previous call to \fBTcl_NewObj\fR. .BE .SH INTRODUCTION .PP -This man page presents an overview of Tcl objects and how they are used. -It also describes generic procedures for managing Tcl objects. -These procedures are used to create and copy objects, -and increment and decrement the count of references (pointers) to objects. +This man page presents an overview of Tcl values (called \fBTcl_Obj\fRs for +historical reasons) and how they are used. +It also describes generic procedures for managing Tcl values. +These procedures are used to create and copy values, +and increment and decrement the count of references (pointers) to values. The procedures are used in conjunction with ones -that operate on specific types of objects such as +that operate on specific types of values such as \fBTcl_GetIntFromObj\fR and \fBTcl_ListObjAppendElement\fR. The individual procedures are described along with the data structures they manipulate. .PP -Tcl's \fIdual-ported\fR objects provide a general-purpose mechanism +Tcl's \fIdual-ported\fR values provide a general-purpose mechanism for storing and exchanging Tcl values. They largely replace the use of strings in Tcl. For example, they are used to store variable values, command arguments, command results, and scripts. -Tcl objects behave like strings but also hold an internal representation +Tcl values behave like strings but also hold an internal representation that can be manipulated more efficiently. -For example, a Tcl list is now represented as an object +For example, a Tcl list is now represented as a value that holds the list's string representation -as well as an array of pointers to the objects for each list element. -Dual-ported objects avoid most runtime type conversions. +as well as an array of pointers to the values for each list element. +Dual-ported values avoid most runtime type conversions. They also improve the speed of many operations since an appropriate representation is immediately available. -The compiler itself uses Tcl objects to +The compiler itself uses Tcl values to cache the instruction bytecodes resulting from compiling scripts. .PP The two representations are a cache of each other and are computed lazily. @@ -75,39 +74,39 @@ between integers and strings. Only when it needs a string representing the variable's value, say to print it, will the program regenerate the string representation from the integer. -Although objects contain an internal representation, +Although values contain an internal representation, their semantics are defined in terms of strings: an up-to-date string can always be obtained, -and any change to the object will be reflected in that string -when the object's string representation is fetched. +and any change to the value will be reflected in that string +when the value's string representation is fetched. Because of this representation invalidation and regeneration, it is dangerous for extension writers to access \fBTcl_Obj\fR fields directly. It is better to access Tcl_Obj information using procedures like \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR. .PP -Objects are allocated on the heap +Values are allocated on the heap and are referenced using a pointer to their \fBTcl_Obj\fR structure. -Objects are shared as much as possible. +Values are shared as much as possible. This significantly reduces storage requirements -because some objects such as long lists are very large. +because some values such as long lists are very large. Also, most Tcl values are only read and never modified. This is especially true for procedure arguments, which can be shared between the caller and the called procedure. Assignment and argument binding is done by simply assigning a pointer to the value. Reference counting is used to determine when it is safe to -reclaim an object's storage. +reclaim a value's storage. .PP -Tcl objects are typed. -An object's internal representation is controlled by its type. +Tcl values are typed. +A value's internal representation is controlled by its type. Several types are predefined in the Tcl core including integer, double, list, and bytecode. Extension writers can extend the set of types by defining their own \fBTcl_ObjType\fR structs. .SH "THE TCL_OBJ STRUCTURE" .PP -Each Tcl object is represented by a \fBTcl_Obj\fR structure +Each Tcl value is represented by a \fBTcl_Obj\fR structure which is defined as follows. .PP .CS @@ -134,7 +133,7 @@ typedef struct Tcl_Obj { .CE .PP The \fIbytes\fR and the \fIlength\fR members together hold -an object's UTF-8 string representation, +a value's UTF-8 string representation, which is a \fIcounted string\fR not containing null bytes (UTF-8 null characters should be encoded as a two byte sequence: 192, 128.) \fIbytes\fR points to the first byte of the string representation. @@ -144,31 +143,31 @@ at offset \fIlength\fR; this allows string representations to be treated as conventional null-terminated C strings. C programs use \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR to get -an object's string representation. +a value's string representation. If \fIbytes\fR is NULL, the string representation is invalid. .PP -An object's type manages its internal representation. +A value's type manages its internal representation. The member \fItypePtr\fR points to the Tcl_ObjType structure that describes the type. If \fItypePtr\fR is NULL, the internal representation is invalid. .PP The \fIinternalRep\fR union member holds -an object's internal representation. +a value's internal representation. This is either a (long) integer, a double-precision floating-point number, a pointer to a value containing additional information -needed by the object's type to represent the object, a Tcl_WideInt +needed by the value's type to represent the value, a Tcl_WideInt integer, two arbitrary pointers, or a pair made up of an unsigned long integer and a pointer. .PP The \fIrefCount\fR member is used to tell when it is safe to free -an object's storage. -It holds the count of active references to the object. +a value's storage. +It holds the count of active references to the value. Maintaining the correct reference count is a key responsibility of extension writers. Reference counting is discussed below -in the section \fBSTORAGE MANAGEMENT OF OBJECTS\fR. +in the section \fBSTORAGE MANAGEMENT OF VALUES\fR. .PP Although extension writers can directly access the members of a Tcl_Obj structure, @@ -178,21 +177,21 @@ read or update \fIrefCount\fR directly; they should use macros such as \fBTcl_IncrRefCount\fR and \fBTcl_IsShared\fR instead. .PP -A key property of Tcl objects is that they hold two representations. -An object typically starts out containing only a string representation: +A key property of Tcl values is that they hold two representations. +A value typically starts out containing only a string representation: it is untyped and has a NULL \fItypePtr\fR. -An object containing an empty string or a copy of a specified string +A value containing an empty string or a copy of a specified string is created using \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR respectively. -An object's string value is gotten with +A value's string value is gotten with \fBTcl_GetStringFromObj\fR or \fBTcl_GetString\fR and changed with \fBTcl_SetStringObj\fR. -If the object is later passed to a procedure like \fBTcl_GetIntFromObj\fR +If the value is later passed to a procedure like \fBTcl_GetIntFromObj\fR that requires a specific internal representation, -the procedure will create one and set the object's \fItypePtr\fR. +the procedure will create one and set the value's \fItypePtr\fR. The internal representation is computed from the string representation. -An object's two representations are duals of each other: +A value's two representations are duals of each other: changes made to one are reflected in the other. -For example, \fBTcl_ListObjReplace\fR will modify an object's +For example, \fBTcl_ListObjReplace\fR will modify a value's internal representation and the next call to \fBTcl_GetStringFromObj\fR or \fBTcl_GetString\fR will reflect that change. .PP @@ -205,43 +204,43 @@ so that it is only regenerated if it is needed later. Most C programmers never have to be concerned with how this is done and simply use procedures such as \fBTcl_GetBooleanFromObj\fR or \fBTcl_ListObjIndex\fR. -Programmers that implement their own object types +Programmers that implement their own value types must check for invalid representations and mark representations invalid when necessary. The procedure \fBTcl_InvalidateStringRep\fR is used -to mark an object's string representation invalid and to +to mark a value's string representation invalid and to free any storage associated with the old string representation. .PP -Objects usually remain one type over their life, -but occasionally an object must be converted from one type to another. -For example, a C program might build up a string in an object +Values usually remain one type over their life, +but occasionally a value must be converted from one type to another. +For example, a C program might build up a string in a value with repeated calls to \fBTcl_AppendToObj\fR, and then call \fBTcl_ListObjIndex\fR to extract a list element from -the object. -The same object holding the same string value +the value. +The same value holding the same string value can have several different internal representations at different times. -Extension writers can also force an object to be converted from one type +Extension writers can also force a value to be converted from one type to another using the \fBTcl_ConvertToType\fR procedure. -Only programmers that create new object types need to be concerned +Only programmers that create new value types need to be concerned about how this is done. -A procedure defined as part of the object type's implementation -creates a new internal representation for an object +A procedure defined as part of the value type's implementation +creates a new internal representation for a value and changes its \fItypePtr\fR. See the man page for \fBTcl_RegisterObjType\fR -to see how to create a new object type. -.SH "EXAMPLE OF THE LIFETIME OF AN OBJECT" +to see how to create a new value type. +.SH "EXAMPLE OF THE LIFETIME OF A VALUE" .PP -As an example of the lifetime of an object, +As an example of the lifetime of a value, consider the following sequence of commands: .PP .CS \fBset x 123\fR .CE .PP -This assigns to \fIx\fR an untyped object whose +This assigns to \fIx\fR an untyped value whose \fIbytes\fR member points to \fB123\fR and \fIlength\fR member contains 3. -The object's \fItypePtr\fR member is NULL. +The value's \fItypePtr\fR member is NULL. .PP .CS \fBputs "x is $x"\fR @@ -254,16 +253,16 @@ and is fetched for the command. \fBincr x\fR .CE .PP -The \fBincr\fR command first gets an integer from \fIx\fR's object +The \fBincr\fR command first gets an integer from \fIx\fR's value by calling \fBTcl_GetIntFromObj\fR. -This procedure checks whether the object is already an integer object. -Since it is not, it converts the object -by setting the object's \fIinternalRep.longValue\fR member +This procedure checks whether the value is already an integer value. +Since it is not, it converts the value +by setting the value's \fIinternalRep.longValue\fR member to the integer \fB123\fR -and setting the object's \fItypePtr\fR +and setting the value's \fItypePtr\fR to point to the integer Tcl_ObjType structure. Both representations are now valid. -\fBincr\fR increments the object's integer internal representation +\fBincr\fR increments the value's integer internal representation then invalidates its string representation (by calling \fBTcl_InvalidateStringRep\fR) since the string representation @@ -273,31 +272,31 @@ no longer corresponds to the internal representation. \fBputs "x is now $x"\fR .CE .PP -The string representation of \fIx\fR's object is needed +The string representation of \fIx\fR's value is needed and is recomputed. The string representation is now \fB124\fR and both representations are again valid. -.SH "STORAGE MANAGEMENT OF OBJECTS" +.SH "STORAGE MANAGEMENT OF VALUES" .PP -Tcl objects are allocated on the heap and are shared as much as possible +Tcl values are allocated on the heap and are shared as much as possible to reduce storage requirements. -Reference counting is used to determine when an object is +Reference counting is used to determine when a value is no longer needed and can safely be freed. -An object just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR +A value just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR has \fIrefCount\fR 0. The macro \fBTcl_IncrRefCount\fR increments the reference count -when a new reference to the object is created. +when a new reference to the value is created. The macro \fBTcl_DecrRefCount\fR decrements the count when a reference is no longer needed and, -if the object's reference count drops to zero, frees its storage. -An object shared by different code or data structures has +if the value's reference count drops to zero, frees its storage. +A value shared by different code or data structures has \fIrefCount\fR greater than 1. -Incrementing an object's reference count ensures that +Incrementing a value's reference count ensures that it will not be freed too early or have its value change accidentally. .PP -As an example, the bytecode interpreter shares argument objects -between calling and called Tcl procedures to avoid having to copy objects. -It assigns the call's argument objects to the procedure's +As an example, the bytecode interpreter shares argument values +between calling and called Tcl procedures to avoid having to copy values. +It assigns the call's argument values to the procedure's formal parameter variables. In doing so, it calls \fBTcl_IncrRefCount\fR to increment the reference count of each argument since there is now a new @@ -305,31 +304,31 @@ reference to it from the formal parameter. When the called procedure returns, the interpreter calls \fBTcl_DecrRefCount\fR to decrement each argument's reference count. -When an object's reference count drops less than or equal to zero, +When a value's reference count drops less than or equal to zero, \fBTcl_DecrRefCount\fR reclaims its storage. Most command procedures do not have to be concerned about -reference counting since they use an object's value immediately -and do not retain a pointer to the object after they return. -However, if they do retain a pointer to an object in a data structure, +reference counting since they use a value's value immediately +and do not retain a pointer to the value after they return. +However, if they do retain a pointer to a value in a data structure, they must be careful to increment its reference count since the retained pointer is a new reference. .PP -Command procedures that directly modify objects +Command procedures that directly modify values such as those for \fBlappend\fR and \fBlinsert\fR must be careful to -copy a shared object before changing it. -They must first check whether the object is shared +copy a shared value before changing it. +They must first check whether the value is shared by calling \fBTcl_IsShared\fR. -If the object is shared they must copy the object +If the value is shared they must copy the value by using \fBTcl_DuplicateObj\fR; -this returns a new duplicate of the original object +this returns a new duplicate of the original value that has \fIrefCount\fR 0. -If the object is not shared, +If the value is not shared, the command procedure .QW "owns" -the object and can safely modify it directly. +the value and can safely modify it directly. For example, the following code appears in the command procedure that implements \fBlinsert\fR. -This procedure modifies the list object passed to it in \fIobjv[1]\fR +This procedure modifies the list value passed to it in \fIobjv[1]\fR by inserting \fIobjc-3\fR new elements before \fIindex\fR. .PP .CS @@ -342,11 +341,12 @@ result = Tcl_ListObjReplace(interp, listPtr, index, 0, .CE .PP As another example, \fBincr\fR's command procedure -must check whether the variable's object is shared before +must check whether the variable's value is shared before incrementing the integer in its internal representation. -If it is shared, it needs to duplicate the object +If it is shared, it needs to duplicate the value in order to avoid accidentally changing values in other data structures. .SH "SEE ALSO" Tcl_ConvertToType(3), Tcl_GetIntFromObj(3), Tcl_ListObjAppendElement(3), Tcl_ListObjIndex(3), Tcl_ListObjReplace(3), Tcl_RegisterObjType(3) .SH KEYWORDS -internal representation, object, object creation, object type, reference counting, string representation, type conversion +internal representation, value, value creation, value type, +reference counting, string representation, type conversion diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 index 47ed451..ca2c7a0 100644 --- a/doc/ObjectType.3 +++ b/doc/ObjectType.3 @@ -4,13 +4,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ObjectType.3,v 1.22 2009/11/27 14:35:10 dkf Exp $ -'\" .so man.macros .TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType \- manipulate Tcl object types +Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType \- manipulate Tcl value types .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -28,31 +26,32 @@ int .SH ARGUMENTS .AS "const char" *typeName .AP "const Tcl_ObjType" *typePtr in -Points to the structure containing information about the Tcl object type. +Points to the structure containing information about the Tcl value type. This storage must live forever, typically by being statically allocated. .AP "const char" *typeName in -The name of a Tcl object type that \fBTcl_GetObjType\fR should look up. +The name of a Tcl value type that \fBTcl_GetObjType\fR should look up. .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tcl_Obj *objPtr in -For \fBTcl_AppendAllObjTypes\fR, this points to the object onto which -it appends the name of each object type as a list element. -For \fBTcl_ConvertToType\fR, this points to an object that +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. .BE .SH DESCRIPTION .PP -The procedures in this man page manage Tcl object types. -They are used to register new object types, look up types, +The procedures in this man page manage Tcl value types (sometimes +referred to as object types or \fBTcl_ObjType\fRs for historical reasons). +They are used to register new value types, look up types, and force conversions from one type to another. .PP -\fBTcl_RegisterObjType\fR registers a new Tcl object type -in the table of all object types that \fBTcl_GetObjType\fR -can look up by name. There are other object types supported by Tcl +\fBTcl_RegisterObjType\fR registers a new Tcl value type +in the table of all value types that \fBTcl_GetObjType\fR +can look up by name. There are other value types supported by Tcl as well, which Tcl chooses not to register. Extensions can likewise -choose to register the object types they create or not. +choose to register the value types they create or not. The argument \fItypePtr\fR points to a Tcl_ObjType structure that describes the new type by giving its name and by supplying pointers to four procedures @@ -67,13 +66,13 @@ in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below. with name \fItypeName\fR. It returns NULL if no type with that name is registered. .PP -\fBTcl_AppendAllObjTypes\fR appends the name of each registered object type -as a list element onto the Tcl object referenced by \fIobjPtr\fR. +\fBTcl_AppendAllObjTypes\fR appends the name of each registered value type +as a list element onto the Tcl value referenced by \fIobjPtr\fR. The return value is \fBTCL_OK\fR unless there was an error -converting \fIobjPtr\fR to a list object; +converting \fIobjPtr\fR to a list value; in that case \fBTCL_ERROR\fR is returned. .PP -\fBTcl_ConvertToType\fR converts an object from one type to another +\fBTcl_ConvertToType\fR converts a value from one type to another if possible. It creates a new internal representation for \fIobjPtr\fR appropriate for the target type \fItypePtr\fR @@ -81,7 +80,7 @@ and sets its \fItypePtr\fR member as determined by calling the \fItypePtr->setFromAnyProc\fR routine. Any internal representation for \fIobjPtr\fR's old type is freed. If an error occurs during conversion, it returns \fBTCL_ERROR\fR -and leaves an error message in the result object for \fIinterp\fR +and leaves an error message in the result value for \fIinterp\fR unless \fIinterp\fR is NULL. Otherwise, it returns \fBTCL_OK\fR. Passing a NULL \fIinterp\fR allows this procedure to be used @@ -96,7 +95,7 @@ use of another related Tcl_ObjType, if it sees fit. .VE 8.5 .SH "THE TCL_OBJTYPE STRUCTURE" .PP -Extension writers can define new object types by defining four +Extension writers can define new value types by defining four procedures and initializing a Tcl_ObjType structure to describe the type. Extension writers may also pass a pointer to their Tcl_ObjType @@ -121,12 +120,12 @@ When a type is registered, this is the name used by callers of \fBTcl_GetObjType\fR to lookup the type. For unregistered types, the \fIname\fR field is primarily of value for debugging. The remaining four members are pointers to procedures -called by the generic Tcl object code: +called by the generic Tcl value code: .SS "THE SETFROMANYPROC FIELD" .PP The \fIsetFromAnyProc\fR member contains the address of a function called to create a valid internal representation -from an object's string representation. +from a value's string representation. .PP .CS typedef int \fBTcl_SetFromAnyProc\fR( @@ -136,7 +135,7 @@ typedef int \fBTcl_SetFromAnyProc\fR( .PP If an internal representation cannot be created from the string, it returns \fBTCL_ERROR\fR and puts a message -describing the error in the result object for \fIinterp\fR +describing the error in the result value for \fIinterp\fR unless \fIinterp\fR is NULL. If \fIsetFromAnyProc\fR is successful, it stores the new internal representation, @@ -171,7 +170,7 @@ should \fInot\fR be registered. .PP The \fIupdateStringProc\fR member contains the address of a function called to create a valid string representation -from an object's internal representation. +from a value's internal representation. .PP .CS typedef void \fBTcl_UpdateStringProc\fR( @@ -205,7 +204,7 @@ or other similar routines ask for the string representation. .SS "THE DUPINTREPPROC FIELD" .PP The \fIdupIntRepProc\fR member contains the address of a function -called to copy an internal representation from one object to another. +called to copy an internal representation from one value to another. .PP .CS typedef void \fBTcl_DupInternalRepProc\fR( @@ -217,7 +216,7 @@ typedef void \fBTcl_DupInternalRepProc\fR( internal representation. Before the call, \fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not. -\fIsrcPtr\fR's object type determines what +\fIsrcPtr\fR's value type determines what copying its internal representation means. .PP For example, the \fIdupIntRepProc\fR for the Tcl integer type @@ -228,7 +227,7 @@ reasonably can. .SS "THE FREEINTREPPROC FIELD" .PP The \fIfreeIntRepProc\fR member contains the address of a function -that is called when an object is freed. +that is called when a value is freed. .PP .CS typedef void \fBTcl_FreeInternalRepProc\fR( @@ -236,22 +235,22 @@ typedef void \fBTcl_FreeInternalRepProc\fR( .CE .PP The \fIfreeIntRepProc\fR function can deallocate the storage -for the object's internal representation -and do other type-specific processing necessary when an object is freed. +for the value's internal representation +and do other type-specific processing necessary when a value is freed. .PP For example, the list type's \fIfreeIntRepProc\fR respects the storage sharing scheme established by the \fIdupIntRepProc\fR -so that it only frees storage when the last object sharing it +so that it only frees storage when the last value sharing it is being freed. .PP The \fIfreeIntRepProc\fR member can be set to NULL to indicate that the internal representation does not require freeing. The \fIfreeIntRepProc\fR implementation must not access the -\fIbytes\fR member of the object, since Tcl makes its own internal -uses of that field during object deletion. The defined tasks for +\fIbytes\fR member of the value, since Tcl makes its own internal +uses of that field during value deletion. The defined tasks for the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR member. .SH "SEE ALSO" Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3) .SH KEYWORDS -internal representation, object, object type, string representation, type conversion +internal representation, value, value type, string representation, type conversion diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index e5083a2..82f51ce 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -4,7 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.38 2010/01/14 11:47:08 dkf Exp $ .so man.macros .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures" .BS @@ -153,24 +152,24 @@ The pattern to match on, passed to Tcl_StringMatch, or NULL. A Tcl channel for input or output. Must have been the return value from a procedure such as \fBTcl_OpenFileChannel\fR. .AP Tcl_Obj *readObjPtr in/out -A pointer to a Tcl Object in which to store the characters read from the +A pointer to a Tcl value in which to store the characters read from the channel. .AP int charsToRead in The number of characters to read from the channel. If the channel's encoding is \fBbinary\fR, this is equivalent to the number of bytes to read from the channel. .AP int appendFlag in -If non-zero, data read from the channel will be appended to the object. -Otherwise, the data will replace the existing contents of the object. +If non-zero, data read from the channel will be appended to the value. +Otherwise, the data will replace the existing contents of the value. .AP char *readBuf out A buffer in which to store the bytes read from the channel. .AP int bytesToRead in The number of bytes to read from the channel. The buffer \fIreadBuf\fR must be large enough to hold this many bytes. .AP Tcl_Obj *lineObjPtr in/out -A pointer to a Tcl object in which to store the line read from the +A pointer to a Tcl value in which to store the line read from the channel. The line read will be appended to the current value of the -object. +value. .AP Tcl_DString *lineRead in/out A pointer to a Tcl dynamic string in which to store the line read from the channel. Must have been initialized by the caller. The line read will be @@ -183,7 +182,7 @@ Length of the input Flag indicating whether the input should be added to the end or beginning of the channel buffer. .AP Tcl_Obj *writeObjPtr in -A pointer to a Tcl Object whose contents will be output to the channel. +A pointer to a Tcl value whose contents will be output to the channel. .AP "const char" *charBuf in A buffer containing the characters to output to the channel. .AP "const char" *byteBuf in @@ -240,7 +239,7 @@ returns NULL and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR leaves an error message in \fIinterp\fR's result after any error. -As of Tcl 8.4, the object-based API \fBTcl_FSOpenFileChannel\fR should +As of Tcl 8.4, the value-based API \fBTcl_FSOpenFileChannel\fR should be used in preference to \fBTcl_OpenFileChannel\fR wherever possible. .PP The newly created channel is not registered in the supplied interpreter; to @@ -306,7 +305,7 @@ open for reading and writing. .PP \fBTcl_GetChannelNames\fR and \fBTcl_GetChannelNamesEx\fR write the names of the registered channels to the interpreter's result as a -list object. \fBTcl_GetChannelNamesEx\fR will filter these names +list value. \fBTcl_GetChannelNamesEx\fR will filter these names according to the \fIpattern\fR. If \fIpattern\fR is NULL, then it will not do any filtering. The return value is \fBTCL_OK\fR if no errors occurred writing to the result, otherwise it is \fBTCL_ERROR\fR, @@ -333,7 +332,7 @@ This procedure interacts with the code managing the standard channels. If no standard channels were initialized before the first call to \fBTcl_RegisterChannel\fR, they will get initialized by that call. See \fBTcl_StandardChannels\fR for a general treatise about -standard channels and the behaviour of the Tcl library with regard to +standard channels and the behavior of the Tcl library with regard to them. .SH TCL_UNREGISTERCHANNEL .PP @@ -436,7 +435,7 @@ platform-specific modes are described in the manual entry for the Tcl As a performance optimization, when reading from a channel with the encoding \fBbinary\fR, the bytes are not converted to UTF-8 as they are read. Instead, they are stored in \fIreadObjPtr\fR's internal representation as a -byte-array object. The string representation of this object will only be +byte-array value. The string representation of this value will only be constructed if it is needed (e.g., because of a call to \fBTcl_GetStringFromObj\fR). In this way, byte-oriented data can be read from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and @@ -485,7 +484,7 @@ of input unavailability. .PP \fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting characters are appended to the dynamic string given by -\fIlineRead\fR rather than a Tcl object. +\fIlineRead\fR rather than a Tcl value. .SH "TCL_UNGETS" .PP \fBTcl_Ungets\fR is used to add data to the input queue of a channel, @@ -524,14 +523,14 @@ end-of-line sequences according to the \fB\-translation\fR option for the channel. This is done even if the channel has no encoding. .PP \fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it -accepts a Tcl object whose contents will be output to the channel. The +accepts a Tcl value whose contents will be output to the channel. The UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted to the channel's encoding and queued for output to \fIchannel\fR. As a performance optimization, when writing to a channel with the encoding \fBbinary\fR, UTF-8 characters are not converted as they are written. Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a -byte-array object are written to the channel. The byte-array representation -of the object will be constructed if it is needed. In this way, +byte-array value are written to the channel. The byte-array representation +of the value will be constructed if it is needed. In this way, byte-oriented data can be read from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a channel without the expense of ever converting to or from UTF-8. diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3 index 0dff4c4..78ac70b 100644 --- a/doc/OpenTcp.3 +++ b/doc/OpenTcp.3 @@ -4,7 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: OpenTcp.3,v 1.14 2010/01/14 11:47:08 dkf Exp $ .so man.macros .TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures" .BS diff --git a/doc/Panic.3 b/doc/Panic.3 index 00187ff..48aed2b 100644 --- a/doc/Panic.3 +++ b/doc/Panic.3 @@ -2,8 +2,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Panic.3,v 1.9 2008/06/29 22:28:24 dkf Exp $ -'\" .so man.macros .TH Tcl_Panic 3 8.4 Tcl "Tcl Library Procedures" .BS @@ -51,7 +49,10 @@ same formatting rules are also used by the built-in Tcl command In a freshly loaded Tcl library, \fBTcl_Panic\fR prints the formatted error message to the standard error file of the process, and then calls \fBabort\fR to terminate the process. \fBTcl_Panic\fR does not -return. +return. On Windows, when a debugger is running, the formatted error +message is sent to the debugger in stead. 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 \fBTcl_SetPanicProc\fR may be used to modify the behavior of \fBTcl_Panic\fR. The \fIpanicProc\fR argument should match the @@ -65,19 +66,14 @@ typedef void \fBTcl_PanicProc\fR( .PP After \fBTcl_SetPanicProc\fR returns, any future calls to \fBTcl_Panic\fR will call \fIpanicProc\fR, passing along the -\fIformat\fR and \fIarg\fR arguments. To maintain consistency with the -callers of \fBTcl_Panic\fR, \fIpanicProc\fR must not return; it must -call \fBabort\fR. \fIpanicProc\fR should avoid 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. +\fIformat\fR and \fIarg\fR arguments. \fIpanicProc\fR should avoid +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 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. As an example, the Windows implementation -of \fBwish\fR calls \fBTcl_SetPanicProc\fR to force all panic messages -to be displayed in a system dialog box, rather than to be printed to the -standard error file (usually not visible under Windows). +application or the platform. .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 diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3 index 1711b8c..1ceafe5 100644 --- a/doc/ParseArgs.3 +++ b/doc/ParseArgs.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ParseArgs.3,v 1.2 2010/01/29 16:17:21 nijtmans Exp $ -'\" .so man.macros .TH Tcl_ParseArgsObjv 3 8.6 Tcl "Tcl Library Procedures" .BS @@ -136,7 +134,7 @@ typedef int (\fBTcl_ArgvFuncProc\fR)( .PP The result is a boolean value indicating whether to consume the following argument. The \fIclientData\fR is the value from the table entry, the -\fIobjPtr\fR is the object that represents the following argument or NULL if +\fIobjPtr\fR is the value that represents the following argument or NULL if there are no following arguments at all, and the \fIdstPtr\fR argument to the \fBTcl_ArgvFuncProc\fR is the location to write the parsed value to. .RE @@ -188,7 +186,7 @@ marks all following arguments to be left unprocessed. The \fIsrcPtr\fR, . This argument takes a following string value argument. A pointer to the string will be stored at \fIdstPtr\fR; the string inside will have a lifetime linked -to the lifetime of the string representation of the argument object that it +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 "SEE ALSO" diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 index b134a1e..5fd9b9c 100644 --- a/doc/ParseCmd.3 +++ b/doc/ParseCmd.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ParseCmd.3,v 1.29 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures" .BS @@ -196,9 +194,9 @@ result; it can be retrieved using \fBTcl_GetObjResult\fR. .PP \fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in the return convention used: it returns the result in a new Tcl_Obj. -The reference count of the object returned as result has been +The reference count of the value returned as result has been incremented, so the caller must -invoke \fBTcl_DecrRefCount\fR when it is finished with the object. +invoke \fBTcl_DecrRefCount\fR when it is finished with the value. If an error or other exception occurs while evaluating the tokens (such as a reference to a non-existent variable) then the return value is NULL and an error message is left in \fIinterp\fR's result. The use diff --git a/doc/PkgRequire.3 b/doc/PkgRequire.3 index 7581bed..d54d7af 100644 --- a/doc/PkgRequire.3 +++ b/doc/PkgRequire.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: PkgRequire.3,v 1.15 2010/08/31 20:53:17 nijtmans Exp $ -'\" .so man.macros .TH Tcl_PkgRequire 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/Preserve.3 b/doc/Preserve.3 index 1a48a56..905a31d 100644 --- a/doc/Preserve.3 +++ b/doc/Preserve.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Preserve.3,v 1.8 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/PrintDbl.3 b/doc/PrintDbl.3 index d0d2307..99b0113 100644 --- a/doc/PrintDbl.3 +++ b/doc/PrintDbl.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: PrintDbl.3,v 1.12 2008/06/29 22:28:24 dkf Exp $ -'\" .so man.macros .TH Tcl_PrintDouble 3 8.0 Tcl "Tcl Library Procedures" .BS diff --git a/doc/RecEvalObj.3 b/doc/RecEvalObj.3 index 98c3149..44888f6 100644 --- a/doc/RecEvalObj.3 +++ b/doc/RecEvalObj.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: RecEvalObj.3,v 1.8 2007/12/13 15:22:31 dgp Exp $ -'\" .so man.macros .TH Tcl_RecordAndEvalObj 3 8.0 Tcl "Tcl Library Procedures" .BS @@ -22,7 +20,7 @@ int .AP Tcl_Interp *interp in Tcl interpreter in which to evaluate command. .AP Tcl_Obj *cmdPtr in -Points to a Tcl object containing a command (or sequence of commands) +Points to a Tcl value containing a command (or sequence of commands) to execute. .AP int flags in An OR'ed combination of flag bits. \fBTCL_NO_EVAL\fR means record the @@ -37,7 +35,7 @@ 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 object containing additional information +as well as a result value containing additional information (a result value or error message) that can be retrieved using \fBTcl_GetObjResult\fR. If you do not want the command recorded on the history list then @@ -52,4 +50,4 @@ the command is recorded without being evaluated. Tcl_EvalObjEx, Tcl_GetObjResult .SH KEYWORDS -command, event, execute, history, interpreter, object, record +command, event, execute, history, interpreter, value, record diff --git a/doc/RecordEval.3 b/doc/RecordEval.3 index 003f1f2..a29f974 100644 --- a/doc/RecordEval.3 +++ b/doc/RecordEval.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: RecordEval.3,v 1.10 2007/12/13 15:22:31 dgp Exp $ -'\" .so man.macros .TH Tcl_RecordAndEval 3 7.4 Tcl "Tcl Library Procedures" .BS @@ -46,9 +44,9 @@ If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then the command is recorded without being evaluated. .PP Note that \fBTcl_RecordAndEval\fR has been largely replaced by the -object-based procedure \fBTcl_RecordAndEvalObj\fR. -That object-based procedure records and optionally executes -a command held in a Tcl object instead of a string. +value-based procedure \fBTcl_RecordAndEvalObj\fR. +That value-based procedure records and optionally executes +a command held in a Tcl value instead of a string. .SH "SEE ALSO" Tcl_RecordAndEvalObj diff --git a/doc/RegConfig.3 b/doc/RegConfig.3 index 19a7c7a..063cc85 100644 --- a/doc/RegConfig.3 +++ b/doc/RegConfig.3 @@ -4,7 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: RegConfig.3,v 1.11 2008/10/04 11:34:19 nijtmans Exp $ .so man.macros .TH Tcl_RegisterConfig 3 8.4 Tcl "Tcl Library Procedures" .BS @@ -81,7 +80,7 @@ create a namespace having the provided \fIpkgName\fR, if not yet existing. .IP (2) create the command \fBpkgconfig\fR in that namespace and link it to -the provided information so that the keys from _configuration_ and +the provided information so that the keys from \fIconfiguration\fR and their associated values can be retrieved through calls to \fBpkgconfig\fR. .PP diff --git a/doc/RegExp.3 b/doc/RegExp.3 index 2c999ea..882976c 100644 --- a/doc/RegExp.3 +++ b/doc/RegExp.3 @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: RegExp.3,v 1.29 2008/06/29 22:28:24 dkf Exp $ -'\" .so man.macros .TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures" .BS @@ -47,12 +45,12 @@ void Tcl interpreter to use for error reporting. The interpreter may be NULL if no error reporting is desired. .AP Tcl_Obj *textObj in/out -Refers to the object from which to get the text to search. The -internal representation of the object may be converted to a form that +Refers to the value from which to get the text to search. The +internal representation of the value may be converted to a form that can be efficiently searched. .AP Tcl_Obj *patObj in/out -Refers to the object from which to get a regular expression. The -compiled regular expression is cached in the object. +Refers to the value from which to get a regular expression. The +compiled regular expression is cached in the value. .AP char *text in Text to search for a match with a regular expression. .AP "const char" *pattern in @@ -112,7 +110,7 @@ If an error occurs in the matching process (e.g. \fIpattern\fR is not a valid regular expression) then \fBTcl_RegExpMatch\fR returns \-1 and leaves an error message in the interpreter result. \fBTcl_RegExpMatchObj\fR is similar to \fBTcl_RegExpMatch\fR except it -operates on the Tcl objects \fItextObj\fR and \fIpatObj\fR instead of +operates on the Tcl values \fItextObj\fR and \fIpatObj\fR instead of UTF strings. \fBTcl_RegExpMatchObj\fR is generally more efficient than \fBTcl_RegExpMatch\fR, so it is the preferred interface. @@ -166,18 +164,18 @@ If there is no range corresponding to \fIindex\fR then NULL is stored in \fI*startPtr\fR and \fI*endPtr\fR. .PP \fBTcl_GetRegExpFromObj\fR, \fBTcl_RegExpExecObj\fR, and -\fBTcl_RegExpGetInfo\fR are object interfaces that provide the most +\fBTcl_RegExpGetInfo\fR are value interfaces that provide the most direct control of Henry Spencer's regular expression library. For users that need to modify compilation and execution options directly, it is recommended that you use these interfaces instead of calling the internal regexp functions. These interfaces handle the details of UTF to Unicode translations as well as providing improved performance -through caching in the pattern and string objects. +through caching in the pattern and string values. .PP \fBTcl_GetRegExpFromObj\fR attempts to return a compiled regular -expression from the \fIpatObj\fR. If the object does not already +expression from the \fIpatObj\fR. If the value does not already contain a compiled regular expression it will attempt to create one -from the string in the object and assign it to the internal +from the string in the value and assign it to the internal representation of the \fIpatObj\fR. The return value of this function is of type \fBTcl_RegExp\fR. The return value is a token for this compiled form, which can be used in subsequent calls to @@ -348,7 +346,7 @@ typedef struct Tcl_RegExpInfo { The \fInsubs\fR field contains a count of the number of parenthesized subexpressions within the regular expression. If the \fBTCL_REG_NOSUB\fR was used, then this value will be zero. The \fImatches\fR field -points to an array of \fInsubs\fR values that indicate the bounds of each +points to an array of \fInsubs\fR+1 values that indicate the bounds of each subexpression matched. The first element in the array refers to the range matched by the entire regular expression, and subsequent elements refer to the parenthesized subexpressions in the order that they diff --git a/doc/SaveResult.3 b/doc/SaveResult.3 index f2ed536..8eaf38f 100644 --- a/doc/SaveResult.3 +++ b/doc/SaveResult.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SaveResult.3,v 1.10 2008/06/29 22:28:24 dkf Exp $ -'\" .so man.macros .TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures" .BS @@ -98,12 +96,12 @@ 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 object results +\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 object results from +\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 diff --git a/doc/SetChanErr.3 b/doc/SetChanErr.3 index e4066e8..3d37f59 100644 --- a/doc/SetChanErr.3 +++ b/doc/SetChanErr.3 @@ -4,7 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SetChanErr.3,v 1.6 2009/11/27 14:35:10 dkf Exp $ .so man.macros .TH Tcl_SetChannelError 3 8.5 Tcl "Tcl Library Procedures" .BS @@ -52,16 +51,16 @@ allowed to use \fBTcl_SetChannelError\fR and \fBTcl_SetChannelErrorInterp\fR to place arbitrary error messages in \fBbypass 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 +arrange for their return as errors. The POSIX error codes set by a driver are used now if and only if no messages are present. .PP \fBTcl_SetChannelError\fR stores error information in the bypass area of the -specified channel. The number of references to the \fBmsg\fR object goes up by +specified channel. The number of references to the \fBmsg\fR value goes up by one. Previously stored information will be discarded, by releasing the reference held by the channel. The channel reference must not be NULL. .PP \fBTcl_SetChannelErrorInterp\fR stores error information in the bypass area of -the specified interpreter. The number of references to the \fBmsg\fR object +the specified interpreter. The number of references to the \fBmsg\fR value goes up by one. Previously stored information will be discarded, by releasing the reference held by the interpreter. The interpreter reference must not be NULL. @@ -73,7 +72,7 @@ NULL, until an intervening invocation of \fBTcl_SetChannelError\fR with a non-NULL message. The \fImsgPtr\fR must not be NULL. The reference count of the message is not touched. The reference previously held by the channel is now held by the caller of the function and it is its responsibility to release -that reference when it is done with the object. +that reference when it is done with the value. .PP \fBTcl_GetChannelErrorInterp\fR places either the error message held in the bypass area of the specified interpreter into \fImsgPtr\fR, or NULL; and @@ -83,7 +82,7 @@ return NULL, until an intervening invocation of not be NULL. The reference count of the message is not touched. The reference previously held by the interpreter is now held by the caller of the function and it is its responsibility to release that reference when it is done with -the object. +the value. .PP Which functions of a channel driver are allowed to use which bypass function is listed below, as is which functions of the public channel API may leave a diff --git a/doc/SetErrno.3 b/doc/SetErrno.3 index 469bd37..1735952 100644 --- a/doc/SetErrno.3 +++ b/doc/SetErrno.3 @@ -4,7 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SetErrno.3,v 1.9 2007/12/13 15:22:31 dgp Exp $ .so man.macros .TH Tcl_SetErrno 3 8.3 Tcl "Tcl Library Procedures" .BS diff --git a/doc/SetRecLmt.3 b/doc/SetRecLmt.3 index 599e46f..e38ba2f 100644 --- a/doc/SetRecLmt.3 +++ b/doc/SetRecLmt.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SetRecLmt.3,v 1.3 1999/04/16 00:46:33 stanton Exp $ -'\" .so man.macros .TH Tcl_SetRecursionLimit 3 7.0 Tcl "Tcl Library Procedures" .BS diff --git a/doc/SetResult.3 b/doc/SetResult.3 index edd74c6..bbeedf1 100644 --- a/doc/SetResult.3 +++ b/doc/SetResult.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SetResult.3,v 1.25 2009/11/27 14:35:10 dkf Exp $ -'\" .so man.macros .TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures" .BS @@ -44,7 +42,7 @@ const char * .AP Tcl_Interp *interp out Interpreter whose result is to be modified or read. .AP Tcl_Obj *objPtr in -Object value to become result for \fIinterp\fR. +Tcl value to become result for \fIinterp\fR. .AP char *result in String value to become result for \fIinterp\fR or to be appended to the existing result. @@ -76,32 +74,32 @@ information as well. .PP The procedures described here are utilities for manipulating the result value in a Tcl interpreter. -The interpreter result may be either a Tcl object or a string. +The interpreter result may be either a Tcl value or a string. For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR -set the interpreter result to, respectively, an object and a string. +set the interpreter result to, respectively, a value and a string. Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR -return the interpreter result as an object and as a string. -The procedures always keep the string and object forms +return the interpreter result as a value and as a string. +The procedures always keep the string and value forms of the interpreter result consistent. For example, if \fBTcl_SetObjResult\fR is called to set -the result to an object, +the result to a value, then \fBTcl_GetStringResult\fR is called, -it will return the object's string value. +it will return the value's string representation. .PP \fBTcl_SetObjResult\fR arranges for \fIobjPtr\fR to be the result for \fIinterp\fR, replacing any existing result. -The result is left pointing to the object +The result is left pointing to the value referenced by \fIobjPtr\fR. \fIobjPtr\fR's reference count is incremented since there is now a new reference to it from \fIinterp\fR. -The reference count for any old result object -is decremented and the old result object is freed if no +The reference count for any old result value +is decremented and the old result value is freed if no references to it remain. .PP -\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as an object. -The object's reference count is not incremented; -if the caller needs to retain a long-term pointer to the object +\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as a value. +The value's reference count is not incremented; +if the caller needs to retain a long-term pointer to the value they should use \fBTcl_IncrRefCount\fR to increment its reference count in order to keep it from being freed too early or accidentally changed. .PP @@ -117,19 +115,19 @@ and \fBTcl_SetResult\fR re-initializes \fIinterp\fR's result to point to an empty string. .PP \fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string. -If the result was set to an object by a \fBTcl_SetObjResult\fR call, -the object form will be converted to a string and returned. -If the object's string representation contains null bytes, +If the result was set to a value by a \fBTcl_SetObjResult\fR call, +the value form will be converted to a string and returned. +If the value's string representation contains null bytes, this conversion will lose information. For this reason, programmers are encouraged to -write their code to use the new object API procedures +write their code to use the new value API procedures and to call \fBTcl_GetObjResult\fR instead. .PP \fBTcl_ResetResult\fR clears the result for \fIinterp\fR and leaves the result in its normal empty initialized state. -If the result is an object, +If the result is a value, its reference count is decremented and the result is left -pointing to an unshared object representing an empty string. +pointing to an unshared value representing an empty string. If the result is a dynamically allocated string, its memory is free*d and the result is left as a empty string. \fBTcl_ResetResult\fR also clears the error state managed by @@ -169,7 +167,7 @@ The source interpreter will have its result reset by this operation. Use of the following procedures (is deprecated since they manipulate the Tcl result as a string. Procedures such as \fBTcl_SetObjResult\fR -that manipulate the result as an object +that manipulate the result as a value can be significantly more efficient. .PP \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in @@ -254,4 +252,4 @@ the value of \fIresult\fR passed to \fBTcl_SetResult\fR. .SH "SEE ALSO" Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp .SH KEYWORDS -append, command, element, list, object, result, return value, interpreter +append, command, element, list, value, result, return value, interpreter diff --git a/doc/SetVar.3 b/doc/SetVar.3 index 7f5e234..0605ff2 100644 --- a/doc/SetVar.3 +++ b/doc/SetVar.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SetVar.3,v 1.16 2007/12/13 15:22:32 dgp Exp $ -'\" .so man.macros .TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures" .BS @@ -59,7 +57,7 @@ to specify a variable in a particular namespace. If non-NULL, gives name of element within array; in this case \fIname1\fR must refer to an array variable. .AP Tcl_Obj *newValuePtr in -Points to a Tcl object containing the new value for the variable. +Points to a Tcl value containing the new value for the variable. .AP int flags in OR-ed combination of bits providing additional information. See below for valid values. @@ -73,12 +71,12 @@ an array. New value for variable, specified as a null-terminated string. A copy of this value is stored in the variable. .AP Tcl_Obj *part1Ptr in -Points to a Tcl object containing the variable's name. +Points to a Tcl value containing the variable's name. The name may include a series of \fB::\fR namespace qualifiers to specify a variable in a particular namespace. May refer to a scalar variable or an element of an array variable. .AP Tcl_Obj *part2Ptr in -If non-NULL, points to an object containing the name of an element +If non-NULL, points to a value containing the name of an element within an array and \fIpart1Ptr\fR must refer to an array variable. .BE @@ -248,4 +246,4 @@ array is removed. Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar .SH KEYWORDS -array, get variable, interpreter, object, scalar, set, unset, variable +array, get variable, interpreter, scalar, set, unset, value, variable diff --git a/doc/Signal.3 b/doc/Signal.3 index 801c4f5..5b12654 100644 --- a/doc/Signal.3 +++ b/doc/Signal.3 @@ -4,7 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Signal.3,v 1.6 2007/12/13 15:22:32 dgp Exp $ .so man.macros .TH Tcl_SignalId 3 8.3 Tcl "Tcl Library Procedures" .BS diff --git a/doc/Sleep.3 b/doc/Sleep.3 index 340d3ec..2423ba1 100644 --- a/doc/Sleep.3 +++ b/doc/Sleep.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Sleep.3,v 1.6 2007/12/13 15:22:32 dgp Exp $ -'\" .so man.macros .TH Tcl_Sleep 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/SourceRCFile.3 b/doc/SourceRCFile.3 index f003a8c..eabc47c 100644 --- a/doc/SourceRCFile.3 +++ b/doc/SourceRCFile.3 @@ -1,9 +1,6 @@ '\" '\" Copyright (c) 1998-2000 by Scriptics Corporation. '\" All rights reserved. -'\" -'\" RCS: @(#) $Id: SourceRCFile.3,v 1.4 2004/10/07 15:37:44 dkf Exp $ -'\" '\" .so man.macros .TH Tcl_SourceRCFile 3 8.3 Tcl "Tcl Library Procedures" diff --git a/doc/SplitList.3 b/doc/SplitList.3 index b57911b..219dfc7 100644 --- a/doc/SplitList.3 +++ b/doc/SplitList.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SplitList.3,v 1.17 2008/12/18 21:23:47 dkf Exp $ -'\" .so man.macros .TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures" .BS @@ -184,7 +182,7 @@ with \fBTCL_DONT_QUOTE_HASH\fR. the same as \fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR, except the length of string \fIsrc\fR is specified by the \fIlength\fR argument, and the string may contain embedded nulls. +.SH "SEE ALSO" +Tcl_ListObjGetElements(3) .SH KEYWORDS backslash, convert, element, list, merge, split, strings -.SH "SEE ALSO" -Tcl_GetListFromObj(3) diff --git a/doc/SplitPath.3 b/doc/SplitPath.3 index e992db4..3fd92ac 100644 --- a/doc/SplitPath.3 +++ b/doc/SplitPath.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SplitPath.3,v 1.10 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures" .BS @@ -45,7 +43,7 @@ A pointer to an initialized \fBTcl_DString\fR to which the result of .SH DESCRIPTION .PP -These procedures have been superceded by the objectified procedures in +These procedures have been superseded by the Tcl-value-aware procedures in the \fBFileSystem\fR man page, which are more efficient. .PP These procedures may be used to disassemble and reassemble file diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3 index 4a194dc..fa6c32f 100644 --- a/doc/StaticPkg.3 +++ b/doc/StaticPkg.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: StaticPkg.3,v 1.12 2008/12/18 21:23:47 dkf Exp $ -'\" .so man.macros .TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/StdChannels.3 b/doc/StdChannels.3 index 85247b5..b5b020e 100644 --- a/doc/StdChannels.3 +++ b/doc/StdChannels.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: StdChannels.3,v 1.14 2007/12/13 15:22:32 dgp Exp $ -'\" .so man.macros .TH "Standard Channels" 3 7.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/StrMatch.3 b/doc/StrMatch.3 index dede549..5adaf6e 100644 --- a/doc/StrMatch.3 +++ b/doc/StrMatch.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: StrMatch.3,v 1.14 2007/12/13 15:22:32 dgp Exp $ -'\" .so man.macros .TH Tcl_StringMatch 3 8.5 Tcl "Tcl Library Procedures" .BS diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 8091e2b..e6f9d32 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -4,13 +4,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: StringObj.3,v 1.31 2009/04/10 13:14:38 dkf Exp $ -'\" .so man.macros .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl objects as strings +Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl values as strings .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -90,7 +88,7 @@ Tcl_Obj * .AS "const Tcl_UniChar" *appendObjPtr in/out .AP "const char" *bytes in Points to the first byte of an array of UTF-8-encoded bytes -used to set or append to a string object. +used to set or append to a string value. This byte array may contain embedded null characters unless \fInumChars\fR is negative. (Applications needing null bytes should represent them as the two-byte sequence \fI\e700\e600\fR, use @@ -98,36 +96,36 @@ should represent them as the two-byte sequence \fI\e700\e600\fR, use the string is a collection of uninterpreted bytes.) .AP int length in The number of bytes to copy from \fIbytes\fR when -initializing, setting, or appending to a string object. +initializing, setting, or appending to a string value. If negative, all bytes up to the first null are used. .AP "const Tcl_UniChar" *unicode in Points to the first byte of an array of Unicode characters -used to set or append to a string object. +used to set or append to a string value. This byte array may contain embedded null characters unless \fInumChars\fR is negative. .AP int numChars in The number of Unicode characters to copy from \fIunicode\fR when -initializing, setting, or appending to a string object. +initializing, setting, or appending to a string value. If negative, all characters up to the first null character are used. .AP int index in 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 object. +returned as a new value. .AP int last in The index of the last Unicode character in the Unicode range to be -returned as a new object. +returned as a new value. .AP Tcl_Obj *objPtr in/out -Points to an object to manipulate. +Points to a value to manipulate. .AP Tcl_Obj *appendObjPtr in -The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. +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 an object's string representation. +the length of a value's string representation. .AP "const char" *string in Null-terminated string value to append to \fIobjPtr\fR. .AP va_list argList in -An argument list which must have been initialised using +An argument list which must have been initialized using \fBva_start\fR, and cleared using \fBva_end\fR. .AP int limit in Maximum number of bytes to be appended. @@ -141,46 +139,46 @@ Format control string including % conversion specifiers. .AP int objc in The number of elements to format or concatenate. .AP Tcl_Obj *objv[] in -The array of objects to format or concatenate. +The array of values to format or concatenate. .AP int newLength in New length for the string value of \fIobjPtr\fR, not including the final null character. .BE .SH DESCRIPTION .PP -The procedures described in this manual entry allow Tcl objects to +The procedures described in this manual entry allow Tcl values to be manipulated as string values. They use the internal representation -of the object to store additional information to make the string +of the value to store additional information to make the string manipulations more efficient. In particular, they make a series of append operations efficient by allocating extra storage space for the string so that it does not have to be copied for each append. Also, indexing and length computations are optimized because the Unicode string representation is calculated and cached as needed. When using the \fBTcl_Append*\fR family of functions where the -interpreter's result is the object being appended to, it is important +interpreter's result is the value being appended to, it is important to call Tcl_ResetResult first to ensure you are not unintentionally -appending to existing data in the result object. +appending to existing data in the result value. .PP -\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object -or modify an existing object to hold a copy of the string given by +\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new value +or modify an existing value to hold a copy of the string given by \fIbytes\fR and \fIlength\fR. \fBTcl_NewUnicodeObj\fR and -\fBTcl_SetUnicodeObj\fR create a new object or modify an existing -object to hold a copy of the Unicode string given by \fIunicode\fR and +\fBTcl_SetUnicodeObj\fR create a new value or modify an existing +value to hold a copy of the Unicode string given by \fIunicode\fR and \fInumChars\fR. \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR -return a pointer to a newly created object with reference count zero. -All four procedures set the object to hold a copy of the specified +return a pointer to a newly created value with reference count zero. +All four procedures set the value to hold a copy of the specified string. \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free any old string representation as well as any old internal representation -of the object. +of the value. .PP -\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return an object's +\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return a value's string representation. This is given by the returned byte pointer and (for \fBTcl_GetStringFromObj\fR) length, which is stored in -\fIlengthPtr\fR if it is non-NULL. If the object's UTF string +\fIlengthPtr\fR if it is non-NULL. If the value's UTF string representation is invalid (its byte pointer is NULL), the string -representation is regenerated from the object's internal +representation is regenerated from the value's internal representation. The storage referenced by the returned byte pointer -is owned by the object manager. It is passed back as a writable +is owned by the value manager. It is passed back as a writable pointer so that extension author creating their own \fBTcl_ObjType\fR will be able to modify the string representation within the \fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR. Except for that @@ -196,45 +194,45 @@ The procedure \fBTcl_GetString\fR is used in the common case where the caller does not need the length of the string representation. .PP -\fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return an object's +\fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return a value's value as a Unicode string. This is given by the returned pointer and (for \fBTcl_GetUnicodeFromObj\fR) length, which is stored in \fIlengthPtr\fR if it is non-NULL. The storage referenced by the returned -byte pointer is owned by the object manager and should not be modified by +byte pointer is owned by the value manager and should not be modified by the caller. The procedure \fBTcl_GetUnicode\fR is used in the common case 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 -object's Unicode representation. +value's Unicode representation. .PP -\fBTcl_GetRange\fR returns a newly created object comprised of the +\fBTcl_GetRange\fR returns a newly created value comprised of the characters between \fIfirst\fR and \fIlast\fR (inclusive) in the -object's Unicode representation. If the object's Unicode +value's Unicode representation. If the value's Unicode representation is invalid, the Unicode representation is regenerated -from the object's string representation. +from the value's string representation. .PP \fBTcl_GetCharLength\fR returns the number of characters (as opposed -to bytes) in the string object. +to bytes) in the string value. .PP \fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and -\fIlength\fR to the string representation of the object specified by -\fIobjPtr\fR. If the object has an invalid string representation, +\fIlength\fR to the string representation of the value specified by +\fIobjPtr\fR. If the value has an invalid string representation, then an attempt is made to convert \fIbytes\fR is to the Unicode format. If the conversion is successful, then the converted form of -\fIbytes\fR is appended to the object's Unicode representation. -Otherwise, the object's Unicode representation is invalidated and +\fIbytes\fR is appended to the value's Unicode representation. +Otherwise, the value's Unicode representation is invalidated and converted to the UTF format, and \fIbytes\fR is appended to the -object's new string representation. +value's new string representation. .PP \fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by -\fIunicode\fR and \fInumChars\fR to the object specified by -\fIobjPtr\fR. If the object has an invalid Unicode representation, +\fIunicode\fR and \fInumChars\fR to the value specified by +\fIobjPtr\fR. If the value has an invalid Unicode representation, then \fIunicode\fR is converted to the UTF format and appended to the -object's string representation. Appends are optimized to handle -repeated appends relatively efficiently (it overallocates the string +value's string representation. Appends are optimized to handle +repeated appends relatively efficiently (it over-allocates the string or Unicode space to avoid repeated reallocations and copies of -object's string value). +value's string value). .PP \fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it appends the string or Unicode value (whichever exists and is best @@ -330,7 +328,10 @@ Tcl_Obj *objPtr = \fBTcl_ObjPrintf\fR("Value is %d", x); .PP If the value of \fIformat\fR contains internal inconsistencies or invalid specifier formats, the formatted string result produced by -\fBTcl_ObjPrintf\fR will be an error message describing the error. +\fBTcl_ObjPrintf\fR will be an error message describing the error. +It is impossible however to provide runtime protection against +mismatches between the format and any subsequent arguments. +Compile-time protection may be provided by some compilers. .PP \fBTcl_AppendPrintfToObj\fR is an appending alternative form of \fBTcl_ObjPrintf\fR with functionality equivalent to @@ -344,14 +345,14 @@ functionality is needed. .PP The \fBTcl_SetObjLength\fR procedure changes the length of the string value of its \fIobjPtr\fR argument. If the \fInewLength\fR -argument is greater than the space allocated for the object's +argument is greater than the space allocated for the value's string, then the string space is reallocated and the old value is copied to the new space; the bytes between the old length of the string and the new length may have arbitrary values. If the \fInewLength\fR argument is less than the current length -of the object's string, with \fIobjPtr->length\fR is reduced without +of the value's string, with \fIobjPtr->length\fR is reduced without reallocating the string space; the original allocated size for the -string is recorded in the object, so that the string length can be +string is recorded in the value, so that the string length can be enlarged in a subsequent call to \fBTcl_SetObjLength\fR without reallocating storage. In all cases \fBTcl_SetObjLength\fR leaves a null character at \fIobjPtr->bytes[newLength]\fR. @@ -360,24 +361,24 @@ a null character at \fIobjPtr->bytes[newLength]\fR. \fBTcl_SetObjLength\fR except that if sufficient memory to satisfy the request cannot be allocated, it does not cause the Tcl interpreter to \fBpanic\fR. Thus, if \fInewLength\fR is greater than the space -allocated for the object's string, and there is not enough memory +allocated for the value's string, and there is not enough memory available to satisfy the request, \fBTcl_AttemptSetObjLength\fR will take no action and return 0 to indicate failure. If there is enough memory to satisfy the request, \fBTcl_AttemptSetObjLength\fR behaves just like \fBTcl_SetObjLength\fR and returns 1 to indicate success. .PP -The \fBTcl_ConcatObj\fR function returns a new string object whose +The \fBTcl_ConcatObj\fR function returns a new string value whose value is the space-separated concatenation of the string -representations of all of the objects in the \fIobjv\fR +representations of all of the values in the \fIobjv\fR array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space as it copies the string representations of the \fIobjv\fR array to the result. If an element of the \fIobjv\fR array consists of nothing but -white space, then that object is ignored entirely. This white-space +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 object whose ref count is zero. +newly-created value whose ref count is zero. .SH "SEE ALSO" Tcl_NewObj(3), Tcl_IncrRefCount(3), Tcl_DecrRefCount(3), format(n), sprintf(3) .SH KEYWORDS -append, internal representation, object, object type, string object, +append, internal representation, value, value type, string value, string type, string representation, concat, concatenate, unicode diff --git a/doc/SubstObj.3 b/doc/SubstObj.3 index de38723..d5a52c3 100644 --- a/doc/SubstObj.3 +++ b/doc/SubstObj.3 @@ -4,13 +4,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SubstObj.3,v 1.7 2007/12/13 15:22:32 dgp Exp $ -'\" .so man.macros .TH Tcl_SubstObj 3 8.4 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_SubstObj \- perform substitutions on Tcl objects +Tcl_SubstObj \- perform substitutions on Tcl values .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -24,7 +22,7 @@ Interpreter in which to execute Tcl scripts and lookup variables. If an error occurs, the interpreter's result is modified to hold an error message. .AP Tcl_Obj *objPtr in -A Tcl object containing the string to perform substitutions on. +A Tcl value containing the string to perform substitutions on. .AP int flags in ORed combination of flag bits that specify which substitutions to perform. The flags \fBTCL_SUBST_COMMANDS\fR, @@ -38,7 +36,7 @@ The \fBTcl_SubstObj\fR function is used to perform substitutions on strings in the fashion of the \fBsubst\fR command. It gets the value of the string contained in \fIobjPtr\fR and scans it, copying characters and performing the chosen substitutions as it goes to an -output object which is returned as the result of the function. In the +output value which is returned as the result of the function. In the event of an error occurring during the execution of a command or variable substitution, the function returns NULL and an error message is left in \fIinterp\fR's result. diff --git a/doc/TCL_MEM_DEBUG.3 b/doc/TCL_MEM_DEBUG.3 index ca9acd3..5a3e08a 100644 --- a/doc/TCL_MEM_DEBUG.3 +++ b/doc/TCL_MEM_DEBUG.3 @@ -3,8 +3,6 @@ '\" Copyright (c) 2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.11 2007/12/13 15:22:32 dgp Exp $ -'\" .so man.macros .TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures" .BS @@ -28,7 +26,7 @@ version of \fBTcl_InitMemory\fR to add the \fBmemory\fR command to Tcl. \fBTCL_MEM_DEBUG\fR must be either left defined for all modules or undefined for all modules that are going to be linked together. If they are not, link errors will occur, with either \fBTcl_DbCkfree\fR and \fBTcl_DbCkalloc\fR or -\fBTcl_Ckalloc\fR and \fBTcl_Ckfree\fR being undefined. +\fBTcl_Alloc\fR and \fBTcl_Free\fR being undefined. .PP Once memory debugging support has been compiled into Tcl, the C functions \fBTcl_ValidateAllMemory\fR, and \fBTcl_DumpActiveMemory\fR, @@ -4,11 +4,9 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: Tcl.n,v 1.24 2010/01/13 12:08:30 dkf Exp $ '\" .so man.macros -.TH Tcl n "8.5" Tcl "Tcl Built-In Commands" +.TH Tcl n "8.6" Tcl "Tcl Built-In Commands" .BS .SH NAME Tcl \- Tool Command Language @@ -110,6 +108,8 @@ Variable substitution may take any of the following forms: \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\-\fB9\fR, +\fBA\fR\-\fBZ\fR and \fBa\fR\-\fBz\fR). .TP 15 \fB$\fIname\fB(\fIindex\fB)\fR . @@ -117,6 +117,8 @@ or namespace separators (two or more colons). 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\-\fB9\fR, +\fBA\fR\-\fBZ\fR and \fBa\fR\-\fBz\fR). Command substitutions, variable substitutions, and backslash substitutions are performed on the characters of \fIindex\fR. .TP 15 @@ -136,6 +138,10 @@ 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). .RE .IP "[9] \fBBackslash substitution.\fR" If a backslash @@ -187,23 +193,33 @@ Backslash .TP 7 \e\fIooo\fR . -The digits \fIooo\fR (one, two, or three of them) give an eight-bit octal -value for the Unicode character that will be inserted. The upper bits of the -Unicode character will be 0. +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 +- \fI377\fR. 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. .TP 7 \e\fBx\fIhh\fR . -The hexadecimal digits \fIhh\fR give an eight-bit hexadecimal value for the -Unicode character that will be inserted. Any number of hexadecimal digits -may be present; however, all but the last two are ignored (the result is -always a one-byte quantity). The upper bits of the Unicode character will -be 0. +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. .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. +inserted. The upper bits of the Unicode character will be 0. +.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+0000..U+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. +.PP +The range U+010000..U+10FFFD is reserved for the future. .PP Backslash substitution is not performed on words enclosed in braces, except for backslash-newline as described above. diff --git a/doc/TclZlib.3 b/doc/TclZlib.3 index 6d5ec7f..854a525 100644 --- a/doc/TclZlib.3 +++ b/doc/TclZlib.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: TclZlib.3,v 1.6 2010/02/10 23:17:06 dkf Exp $ -'\" .so man.macros .TH TclZlib 3 8.6 Tcl "Tcl Library Procedures" .BS @@ -51,9 +49,11 @@ int .sp int \fBTcl_ZlibStreamGet\fR(\fIzshandle, dataObj, count\fR) +.sp +\fBTcl_ZlibStreamSetCompressionDictionary\fR(\fIzshandle, compDict\fR) .fi .SH ARGUMENTS -.AS Tcl_ZlibStream *zshandlePtr out +.AS Tcl_ZlibStream zshandle in .AP Tcl_Interp *interp in The interpreter to store resulting compressed or uncompressed data in. Also where any error messages are written. For \fBTcl_ZlibStreamInit\fR, this can @@ -66,7 +66,7 @@ addition, for decompression only, \fBTCL_ZLIB_FORMAT_AUTO\fR may also be chosen which can automatically detect whether the compressed data was in zlib or gzip format. .AP Tcl_Obj *dataObj in/out -A byte-array object containing the data to be compressed or decompressed, or +A byte-array value containing the data to be compressed or decompressed, or to which the data extracted from the stream is appended when passed to \fBTcl_ZlibStreamGet\fR. .AP int level in @@ -110,6 +110,13 @@ trailer demanded by the format is written. .AP int count in The maximum number of bytes to get from the stream, or -1 to get all remaining bytes from the stream's buffers. +.AP Tcl_Obj *compDict in +A byte array value that is the compression dictionary to use with the stream. +Note that this is \fInot a Tcl dictionary\fR, and it is recommended that this +only ever be used with streams that were created with their \fIformat\fR set +to \fBTCL_ZLIB_FORMAT_ZLIB\fR because the other formats have no mechanism to +indicate whether a compression dictionary was present other than to fail on +decompression. .BE .SH DESCRIPTION These functions form the interface from the Tcl library to the Zlib @@ -124,7 +131,7 @@ the dictionary is only used when the \fIformat\fR parameter is \fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. For details of the contents of the dictionary, see the \fBGZIP OPTIONS DICTIONARY\fR section below. Upon success, both functions leave the resulting compressed or -decompressed data in a byte-array object that is the Tcl interpreter's result; +decompressed data in a byte-array value that is the Tcl interpreter's result; the returned value is a standard Tcl result code. .PP \fBTcl_ZlibAdler32\fR and \fBTcl_ZlibCRC32\fR compute checksums on arrays of @@ -156,7 +163,7 @@ the \fBGZIP OPTIONS DICTIONARY\fR section below) can be given via the headers, and on decompression allows discovery of the existing headers. Note that the dictionary will be written to on decompression once sufficient data has been read to have a complete header. This means that the dictionary must -be an unshared object in that case; a blank object created with +be an unshared value in that case; a blank value created with \fBTcl_NewObj\fR is suggested. .PP Once a stream has been constructed, \fBTcl_ZlibStreamPut\fR is used to add @@ -164,8 +171,8 @@ data to the stream and \fBTcl_ZlibStreamGet\fR is used to retrieve data from the stream after processing. Both return normal Tcl result codes and leave an error message in the result of the interpreter that the stream is registered with in the error case (if such a registration has been performed). With -\fBTcl_ZlibStreamPut\fR, the data buffer object passed to it should not be -modified afterwards. With \fBTcl_ZlibStreamGet\fR, the data buffer object +\fBTcl_ZlibStreamPut\fR, the data buffer value passed to it should not be +modified afterwards. With \fBTcl_ZlibStreamGet\fR, the data buffer value passed to it will have the data bytes appended to it. Internally to the stream, data is kept compressed so as to minimize the cost of buffer space. .PP @@ -174,6 +181,25 @@ uncompressed data according to the format, and \fBTcl_ZlibStreamEof\fR returns a boolean value indicating whether the end of the uncompressed data has been reached. .PP +\fBTcl_ZlibStreamSetCompressionDictionary\fR is used to control the +compression dictionary used with the stream, a compression dictionary being an +array of bytes (such as might be created with \fBTcl_NewByteArrayObj\fR) that +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 +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 +\fB\-errorcode\fR set to +.QW "\fBZLIB NEED_DICT\fI code\fR" ; +the \fIcode\fR will be the Adler-32 checksum (see \fBTcl_ZlibAdler32\fR) of +the compression dictionary sought. (Note that this is only true for +zlib-format streams; gzip streams ignore compression dictionaries as the +format specification doesn't permit them, and raw streams just produce a data +error if the compression dictionary is missing or incorrect.) +.PP If you wish to clear a stream and reuse it for a new compression or decompression action, \fBTcl_ZlibStreamReset\fR will do this and return a normal Tcl result code to indicate whether it was successful; if the stream is @@ -189,9 +215,9 @@ and \fBTcl_ZlibStreamInit\fR is used to pass a dictionary of options about that is used to describe the gzip header in the compressed data. When creating compressed data, the dictionary is read and when unpacking compressed data the dictionary is written (in which case the \fIdictObj\fR parameter must refer to -an unshared dictionary object). +an unshared dictionary value). .PP -The following fields in the dictionary object are understood. All other fields +The following fields in the dictionary value are understood. All other fields are ignored. No field is required when creating a gzip-format stream. .TP \fBcomment\fR diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3 index e37ffe4..0a69835 100644 --- a/doc/Tcl_Main.3 +++ b/doc/Tcl_Main.3 @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Tcl_Main.3,v 1.20 2008/12/19 18:23:04 dgp Exp $ -'\" .so man.macros .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures" .BS @@ -30,7 +28,8 @@ Tcl_Obj * .AP int argc in Number of elements in \fIargv\fR. .AP char *argv[] in -Array of strings containing command-line arguments. +Array of strings containing command-line arguments. On Windows, when +using -DUNICODE, the parameter type changes to wchar_t *. .AP Tcl_AppInitProc *appInitProc in Address of an application-specific initialization procedure. The value for this argument is usually \fBTcl_AppInit\fR. diff --git a/doc/Thread.3 b/doc/Thread.3 index 9b9912e..ca135ee 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Thread.3,v 1.32 2010/06/16 14:49:51 nijtmans Exp $ -'\" .so man.macros .TH Threads 3 "8.1" Tcl "Tcl Library Procedures" .BS @@ -72,7 +70,7 @@ Arbitrary information. Passed as sole argument to the \fIproc\fR. .AP int stackSize in The size of the stack given to the new thread. .AP int flags in -Bitmask containing flags allowing the caller to modify behaviour of +Bitmask containing flags allowing the caller to modify behavior of the new thread. .AP int *result out The referred storage is used to place the exit code of the thread @@ -93,15 +91,15 @@ and use multiple interpreters.) .SH DESCRIPTION Tcl provides \fBTcl_CreateThread\fR for creating threads. The caller can determine the size of the stack given to the new thread and -modify the behaviour through the supplied \fIflags\fR. The value +modify the behavior through the supplied \fIflags\fR. The value \fBTCL_THREAD_STACK_DEFAULT\fR for the \fIstackSize\fR indicates that the default size as specified by the operating system is to be used for the new thread. As for the flags, currently only the values \fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are defined. The -first of them invokes the default behaviour with no -specialties. Using the second value marks the new thread as -\fIjoinable\fR. This means that another thread can wait for the such -marked thread to exit and join it. +first of them invokes the default behavior with no special settings. +Using the second value marks the new thread as \fIjoinable\fR. This +means that another thread can wait for the such marked thread to exit +and join it. .PP Restrictions: On some UNIX systems the pthread-library does not contain the functionality to specify the stack size of a thread. The diff --git a/doc/ToUpper.3 b/doc/ToUpper.3 index 15539ad..d6b3006 100644 --- a/doc/ToUpper.3 +++ b/doc/ToUpper.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ToUpper.3,v 1.3 2004/09/06 09:44:57 dkf Exp $ -'\" .so man.macros .TH Tcl_UtfToUpper 3 "8.1" Tcl "Tcl Library Procedures" .BS diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3 index ee8198f..5cc1337 100644 --- a/doc/TraceCmd.3 +++ b/doc/TraceCmd.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" CVS: @(#) $Id: TraceCmd.3,v 1.13 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures" .BS diff --git a/doc/TraceVar.3 b/doc/TraceVar.3 index 7ba525d..6201a4f 100644 --- a/doc/TraceVar.3 +++ b/doc/TraceVar.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: TraceVar.3,v 1.22 2009/09/03 08:01:22 dkf Exp $ -'\" .so man.macros .TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures" .BS diff --git a/doc/Translate.3 b/doc/Translate.3 index c6e6217..55233c3 100644 --- a/doc/Translate.3 +++ b/doc/Translate.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Translate.3,v 1.13 2007/12/13 15:22:32 dgp Exp $ -'\" .so man.macros .TH Tcl_TranslateFileName 3 8.1 Tcl "Tcl Library Procedures" .BS @@ -31,7 +29,6 @@ At the time of the call it should be uninitialized or free. The caller must eventually call \fBTcl_DStringFree\fR to free up anything stored here. .BE - .SH DESCRIPTION .PP This utility procedure translates a file name to a platform-specific form @@ -40,11 +37,11 @@ passing to the local operating system. In particular, it converts network names into native form and does tilde substitution. .PP However, with the advent of the newer \fBTcl_FSGetNormalizedPath\fR and -\fBTcl_GetNativePath\fR, there is no longer any need to use this -procedure. In particular, \fBTcl_GetNativePath\fR performs all the +\fBTcl_FSGetNativePath\fR, there is no longer any need to use this +procedure. In particular, \fBTcl_FSGetNativePath\fR performs all the necessary translation and encoding conversion, is virtual-filesystem aware, and caches the native result for faster repeated calls. -Finally \fBTcl_GetNativePath\fR does not require you to free anything +Finally \fBTcl_FSGetNativePath\fR does not require you to free anything afterwards. .PP If @@ -68,9 +65,7 @@ frees the dynamic string itself so that the caller need not call .PP The caller is responsible for making sure that the interpreter's result has its default empty value when \fBTcl_TranslateFileName\fR is invoked. - .SH "SEE ALSO" -filename - +filename(n) .SH KEYWORDS file name, home directory, tilde, translate, user diff --git a/doc/UniCharIsAlpha.3 b/doc/UniCharIsAlpha.3 index 26d9eb3..6029b2d 100644 --- a/doc/UniCharIsAlpha.3 +++ b/doc/UniCharIsAlpha.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: UniCharIsAlpha.3,v 1.5 2007/12/13 15:22:32 dgp Exp $ -'\" .so man.macros .TH Tcl_UniCharIsAlpha 3 "8.1" Tcl "Tcl Library Procedures" .BS diff --git a/doc/UpVar.3 b/doc/UpVar.3 index 01b0221..f1e6fe4 100644 --- a/doc/UpVar.3 +++ b/doc/UpVar.3 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: UpVar.3,v 1.11 2006/10/09 23:38:56 msofer Exp $ -'\" .so man.macros .TH Tcl_UpVar 3 7.4 Tcl "Tcl Library Procedures" .BS @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Utf.3,v 1.26 2008/06/29 22:28:24 dkf Exp $ -'\" .so man.macros .TH Utf 3 "8.1" Tcl "Tcl Library Procedures" .BS diff --git a/doc/WrongNumArgs.3 b/doc/WrongNumArgs.3 index 323ad40..15d5caf 100644 --- a/doc/WrongNumArgs.3 +++ b/doc/WrongNumArgs.3 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: WrongNumArgs.3,v 1.13 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures" .BS @@ -20,7 +18,7 @@ Tcl_WrongNumArgs \- generate standard error message for wrong number of argument .AS "Tcl_Obj *const" *message .AP Tcl_Interp interp in Interpreter in which error will be reported: error message gets stored -in its result object. +in its result value. .AP int objc in Number of leading arguments from \fIobjv\fR to include in error message. @@ -36,13 +34,13 @@ of the command. This argument may be NULL. \fBTcl_WrongNumArgs\fR is a utility procedure that is invoked by command procedures when they discover that they have received the wrong number of arguments. \fBTcl_WrongNumArgs\fR generates a -standard error message and stores it in the result object of +standard error message and stores it in the result value of \fIinterp\fR. The message includes the \fIobjc\fR initial elements of \fIobjv\fR plus \fImessage\fR. For example, if \fIobjv\fR consists of the values \fBfoo\fR and \fBbar\fR, \fIobjc\fR is 1, and \fImessage\fR is .QW "\fBfileName count\fR" -then \fIinterp\fR's result object will be set to the following +then \fIinterp\fR's result value will be set to the following string: .PP .CS @@ -59,17 +57,17 @@ wrong # args: should be "foo bar fileName count" \fBstring\fR and the Tk widget commands, which use the first argument as a subcommand. .PP -Some of the objects in the \fIobjv\fR array may be abbreviations for +Some of the values in the \fIobjv\fR array may be abbreviations for a subcommand. The command -\fBTcl_GetIndexFromObj\fR will convert the abbreviated string object +\fBTcl_GetIndexFromObj\fR will convert the abbreviated string value into an \fIindexObject\fR. If an error occurs in the parsing of the subcommand we would like to use the full subcommand name rather than the abbreviation. If the \fBTcl_WrongNumArgs\fR command finds any \fIindexObjects\fR in the \fIobjv\fR array it will use the full subcommand name in the error message instead of the abbreviated name that was originally passed in. Using the above example, let us assume that -\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the object -is now an indexObject because it was passed to +\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the value +is now an \fIindexObject\fR because it was passed to \fBTcl_GetIndexFromObj\fR. In this case the error message would be: .PP .CS diff --git a/doc/after.n b/doc/after.n index 8ccada1..d6181c6 100644 --- a/doc/after.n +++ b/doc/after.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: after.n,v 1.13 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH after n 7.5 Tcl "Tcl Built-In Commands" .BS @@ -51,7 +49,7 @@ The command will be executed at global level (outside the context of any Tcl procedure). If an error occurs while executing the delayed command then the background error will be reported by the command -registered with \fB interp bgerror\fR. +registered with \fBinterp bgerror\fR. The \fBafter\fR command returns an identifier that can be used to cancel the delayed command using \fBafter cancel\fR. .TP @@ -84,7 +82,7 @@ The command returns an identifier that can be used to cancel the delayed command using \fBafter cancel\fR. If an error occurs while executing the script then the background error will be reported by the command -registered with \fB interp bgerror\fR. +registered with \fBinterp bgerror\fR. .TP \fBafter info \fR?\fIid\fR? . diff --git a/doc/append.n b/doc/append.n index 6217b80..034068d 100644 --- a/doc/append.n +++ b/doc/append.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: append.n,v 1.12 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH append n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/array.n b/doc/array.n index 49bc0e6..47f9624 100644 --- a/doc/array.n +++ b/doc/array.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: array.n,v 1.22 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH array n 8.3 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/bgerror.n b/doc/bgerror.n index b71ed3d..ac53eca 100644 --- a/doc/bgerror.n +++ b/doc/bgerror.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: bgerror.n,v 1.15 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH bgerror n 7.5 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/binary.n b/doc/binary.n index e038fb5..68bf9cc 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: binary.n,v 1.44 2008/12/15 17:11:33 ferrieux Exp $ -'\" .so man.macros .TH binary n 8.0 Tcl "Tcl Built-In Commands" .BS @@ -15,9 +13,9 @@ binary \- Insert and extract fields from binary strings .SH SYNOPSIS .VS 8.6 -\fBbinary decode \fIformat\fR ?\fI-option value ...\fR? \fIdata\fR +\fBbinary decode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR .br -\fBbinary encode \fIformat\fR ?\fI-option value ...\fR? \fIdata\fR +\fBbinary encode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR .br .VE 8.6 \fBbinary format \fIformatString \fR?\fIarg arg ...\fR? @@ -94,7 +92,7 @@ Instructs the decoder to throw an error if it encounters whitespace characters. . The \fBuuencode\fR binary encoding used to be common for transfer of data between Unix systems and on USENET, but is less common these days, having been -largely superceded by the \fBbase64\fR binary encoding. +largely superseded by the \fBbase64\fR binary encoding. .RS .PP During encoding, the following options are supported: @@ -137,7 +135,7 @@ is a non-negative decimal integer or \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 -is ignored for for \fBbinary format\fR. +is ignored for \fBbinary format\fR. .PP Here is a small example to clarify the relation between the field specifiers and the arguments: diff --git a/doc/break.n b/doc/break.n index 4d758a4..cef37c6 100644 --- a/doc/break.n +++ b/doc/break.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: break.n,v 1.12 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH break n "" Tcl "Tcl Built-In Commands" .BS @@ -20,7 +18,7 @@ break \- Abort looping command .PP This command is typically invoked inside the body of a looping command such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR. -It returns a \fBTCL_BREAK\fR code, which causes a break exception +It returns a 3 (\fBTCL_BREAK\fR) result code, which causes a break exception to occur. The exception causes the current script to be aborted out to the innermost containing loop command, which then @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: case.n,v 1.3 2000/09/07 14:27:46 poenitz Exp $ -'\" .so man.macros .TH case n 7.0 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/catch.n b/doc/catch.n index 691b0c7..a05ca71 100644 --- a/doc/catch.n +++ b/doc/catch.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: catch.n,v 1.25 2010/04/07 09:51:31 dkf Exp $ -'\" .so man.macros .TH catch n "8.5" Tcl "Tcl Built-In Commands" .BS @@ -79,14 +77,14 @@ the corresponding level; or it may be .QW \fBUP\fR , in which case the parameter is the relative level (as in \fBuplevel\fR) of the previous \fBCALL\fR. The -salient differences wrt \fB\-errorinfo\fR are that: -.IP (1) +salient differences with respect to \fB\-errorinfo\fR are that: +.IP [1] it is a machine-readable form that is amenable to processing with [\fBforeach\fR {tok prm} ...], -.IP (2) +.IP [2] it contains the true (substituted) values passed to the functions, instead of the static text of the calling sites, and -.IP (3) +.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 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: cd.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH cd n "" Tcl "Tcl Built-In Commands" .BS @@ -3,8 +3,6 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: chan.n,v 1.26 2010/01/20 13:42:17 dkf Exp $ .so man.macros .TH chan n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -59,7 +57,7 @@ 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 -nonblocking and there is unflushed output, the channel remains open and the +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 @@ -109,8 +107,8 @@ the command sets each of the named options to the corresponding .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 channels -for the options that that specific type of channel supports. For +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. @@ -120,10 +118,10 @@ serial devices. 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 nonblocking mode it will +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 nonblocking mode to +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). @@ -401,7 +399,7 @@ commands. 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 transfered +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 @@ -455,7 +453,7 @@ 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 nonblocking mode using events. A channel is also considered to be +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 @@ -470,12 +468,12 @@ 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 -nonblocking mode with the \fBchan configure\fR command. In blocking +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 nonblocking mode \fBchan puts\fR, \fBchan read\fR, and \fBchan +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 @@ -495,7 +493,7 @@ is written. .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 nonblocking mode, the command may return before all +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. @@ -518,7 +516,7 @@ 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-nonblocking case can be distinguished with the +the partial-line-but-non-blocking case can be distinguished with the \fBchan blocked\fR command. .RE .TP @@ -632,16 +630,16 @@ 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 nonblocking +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 nonblocking output to work; otherwise Tcl never +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 nonblocking mode, which could consume a large amount of -memory. To avoid wasting memory, nonblocking I/O should normally be +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). @@ -661,7 +659,7 @@ given to indicate that any trailing newline in the string that has been read should be trimmed. .RS .PP -If \fIchannelId\fR is in nonblocking mode, \fBchan read\fR may not +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 @@ -677,7 +675,7 @@ 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 nonblocking, like this: +the serial port channel to be non-blocking, like this: .PP .CS \fBchan configure \fIchannelId \fB\-blocking \fI0\fR. @@ -730,7 +728,7 @@ position after the end of file. The \fIorigin\fR argument defaults to \fBstart\fR. .PP \fBChan seek\fR flushes all buffered output for the channel before the -command returns, even if the channel is in nonblocking mode. It also +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. diff --git a/doc/class.n b/doc/class.n index 0d29076..88d1b44 100644 --- a/doc/class.n +++ b/doc/class.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: class.n,v 1.4 2009/11/05 17:56:45 dkf Exp $ -'\" .so man.macros .TH class n 0.1 TclOO "TclOO Commands" .BS diff --git a/doc/clock.n b/doc/clock.n index 56a139e..8708029 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -42,12 +42,12 @@ is system-dependent but should be the highest resolution clock available on the system such as a CPU cycle counter. See \fBHIGH RESOLUTION TIMERS\fR for a full description. .RS .PP -If the \fI\-option\fR argument is \fI\-milliseconds\fR, then the command +If the \fI\-option\fR argument is \fB\-milliseconds\fR, then the command is synonymous with \fBclock milliseconds\fR (see below). This usage is obsolete, and \fBclock milliseconds\fR is to be considered the preferred way of obtaining a count of milliseconds. .PP -If the \fI\-option\fR argument is \fI\-microseconds\fR, then the command +If the \fI\-option\fR argument is \fB\-microseconds\fR, then the command is synonymous with \fBclock microseconds\fR (see below). This usage is obsolete, and \fBclock microseconds\fR is to be considered the preferred way of obtaining a count of microseconds. @@ -116,7 +116,7 @@ On \fBclock format\fR, the default format is %a %b %d %H:%M:%S %z %Y .CE .PP -On \fBclock scan\fR, the lack of a \fI\-format\fR option indicates that a +On \fBclock scan\fR, the lack of a \fB\-format\fR option indicates that a .QW "free format scan" is requested; see \fBFREE FORM SCAN\fR for a description of what happens. .RE @@ -904,7 +904,7 @@ or Note that only these three formats are accepted. The command does \fInot\fR accept the full range of point-in-time specifications specified in ISO8601. Other formats can be recognized by -giving an explicit \fI\-format\fR option to the \fBclock scan\fR command. +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 diff --git a/doc/close.n b/doc/close.n index 60a8b97..2826d82 100644 --- a/doc/close.n +++ b/doc/close.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: close.n,v 1.16 2009/04/15 12:31:24 dkf Exp $ -'\" .so man.macros .TH close n 7.5 Tcl "Tcl Built-In Commands" .BS @@ -25,7 +23,8 @@ Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), the return value from an invocation of \fBopen\fR or \fBsocket\fR, or the result of a channel creation command provided by a Tcl extension. .PP -The single-argument form is a simple "full-close": +The single-argument form is a simple +.QW "full-close" : all buffered output is flushed to the channel's output device, any buffered input is discarded, the underlying file or device is closed, and \fIchannelId\fR becomes unavailable for use. @@ -49,8 +48,10 @@ When the last interpreter in which the channel is registered invokes \fBinterp\fR command for a description of channel sharing. .PP Channels are automatically 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. +when the process exits. +.VS 8.6 +From 8.6 on (TIP#398), nonblocking channels are no longer switched to blocking mode when exiting; this guarantees a timely exit even when the peer or a communication channel is stalled. To ensure proper flushing of stalled nonblocking channels on exit, one must now either (a) actively switch them back to blocking or (b) use the environment variable TCL_FLUSH_NONBLOCKING_ON_EXIT, which when set and not equal to "0" restores the previous behavior. +.VE 8.6 .PP The command returns an empty string, and may generate an error if an error occurs while flushing output. If a command in a command @@ -58,16 +59,20 @@ pipeline created with \fBopen\fR returns an error, \fBclose\fR generates an error (similar to the \fBexec\fR command.) .PP .VS 8.6 -The two-argument form is a "half-close": given a bidirectional channel like a +The two-argument form is a +.QW "half-close" : +given a bidirectional channel like a socket or command pipeline and a (possibly abbreviated) direction, it closes -only the substream going in that direction. This means a shutdown() on a +only the sub-stream going in that direction. This means a shutdown() on a socket, and a close() of one end of a pipe for a command pipeline. Then, the Tcl-level channel data structure is either kept or freed depending on whether the other direction is still open. .PP -A single-argument close on an already half-closed bi-channel is defined to -just "finish the job. A half-close on an already closed half, or on a -wrong-sided unidirectional channel, raises an error. +A single-argument close on an already half-closed bidirectional channel is +defined to just +.QW "finish the job" . +A half-close on an already closed half, or on a wrong-sided unidirectional +channel, raises an error. .PP In the case of a command pipeline, the child-reaping duty falls upon the shoulders of the last close or half-close, which is thus allowed to report an diff --git a/doc/concat.n b/doc/concat.n index 7cda15c..b079b30 100644 --- a/doc/concat.n +++ b/doc/concat.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: concat.n,v 1.14 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH concat n 8.3 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/continue.n b/doc/continue.n index beb29b7..de2f07c 100644 --- a/doc/continue.n +++ b/doc/continue.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: continue.n,v 1.12 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH continue n "" Tcl "Tcl Built-In Commands" .BS @@ -20,8 +18,8 @@ continue \- Skip to the next iteration of a loop .PP This command is typically invoked inside the body of a looping command such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR. -It returns a \fBTCL_CONTINUE\fR code, which causes a continue exception -to occur. +It returns a 4 (\fBTCL_CONTINUE\fR) result code, which causes a continue +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. @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: copy.n,v 1.3 2009/06/07 23:33:23 dkf Exp $ -'\" .so man.macros .TH copy n 0.1 TclOO "TclOO Commands" .BS @@ -28,10 +26,23 @@ resolved relative to the current namespace if not an absolute qualified name. If \fItargetObject\fR is omitted, a new name is chosen. The copied object will be of the same class as the source object, and will have all its per-object methods copied. If it is a class, it will also have all the class methods in -the class copied, but it will not have any of its instances copied. The -contents of the source object's private namespace \fIwill not\fR be copied; it -is up to the caller to do this. The result of this command will be the -fully-qualified name of the new object or class. +the class copied, but it will not have any of its instances copied. +.PP +.VS +After the \fItargetObject\fR has been created and all definitions of its +configuration (e.g., methods, filters, mixins) copied, the \fB<cloned>\fR +method of \fItargetObject\fR will be invoked, to allow for customization of +the created object such as installing related variable traces. The only +argument given will be \fIsourceObject\fR. The default implementation of this +method (in \fBoo::object\fR) just copies the procedures and variables in the +namespace of \fIsourceObject\fR to the namespace of \fItargetObject\fR. If +this method call does not return a result that is successful (i.e., an error +or other kind of exception) then the \fItargetObject\fR will be deleted and an +error returned. +.VE +.PP +The result of the \fBoo::copy\fR command will be the fully-qualified name of +the new object or class. .SH EXAMPLES .PP This example creates an object, copies it, modifies the source object, and diff --git a/doc/coroutine.n b/doc/coroutine.n index 4a7d799..035d58a 100644 --- a/doc/coroutine.n +++ b/doc/coroutine.n @@ -4,19 +4,20 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: coroutine.n,v 1.5 2010/01/13 09:10:10 dkf Exp $ -'\" .so man.macros .TH coroutine n 8.6 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -coroutine, yield \- Create and produce values from coroutines +coroutine, yield, yieldto \- Create and produce values from coroutines .SH SYNOPSIS .nf \fBcoroutine \fIname command\fR ?\fIarg...\fR? \fByield\fR ?\fIvalue\fR? -\fIname\fR ?\fIvalue\fR? +.VS TIP396 +\fByieldto\fR \fIcommand\fR ?\fIarg...\fR? +\fIname\fR ?\fIvalue...\fR? +.VE TIP396 .fi .BE .SH DESCRIPTION @@ -32,11 +33,37 @@ Within the context, values may be generated as results by using the When that is called, the context will suspend execution and the \fBcoroutine\fR command will return the argument to \fByield\fR. The execution of the context can then be resumed by calling the context command, optionally -passing in the value to use as the result of the \fByield\fR call that caused +passing in the \fIsingle\fR value to use as the result of the \fByield\fR call +that caused 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 +number\fR of arguments may be passed. Since every coroutine has a context +command, \fByieldto\fR can be used to transfer control directly from one +coroutine to another (this is only advisable if the two coroutines are +expecting this to happen) but \fIany\fR command may be the target. If a +coroutine is suspended by this mechanism, the coroutine processing can be +resumed by calling the context command optionally passing in an arbitrary +number of arguments. The return value of the \fByieldto\fR call will be the +list of arguments passed to the context command; it is up to the caller to +decide what to do with those values. +.PP +The recommended way of writing a version of \fByield\fR that allows resumption +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 +} +.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 \fBinfo coroutine\fR. @@ -110,10 +137,31 @@ for {set i 1} {$i <= 20} {incr i} { puts "prime#$i = [\fIeratosthenes\fR]" } .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 +.CS +proc juggler {name target {value ""}} { + if {$value eq ""} { + set value [\fByield\fR [info coroutine]] + } + while {$value ne ""} { + puts "$name : $value" + set value [string range $value 0 end-1] + lassign [\fByieldto\fR $target $value] value + } +} +\fBcoroutine\fR j1 juggler Larry [ + \fBcoroutine\fR j2 juggler Curly [ + \fBcoroutine\fR j3 juggler Moe j1]] "Nyuck!Nyuck!Nyuck!" +.CE +.VE TIP396 .SS "DETAILED SEMANTICS" .PP This example demonstrates that coroutines start from the global namespace, and -that\fIcommand\fR resolution happens before the coroutine stack is created. +that \fIcommand\fR resolution happens before the coroutine stack is created. .PP .CS proc report {where level} { @@ -5,23 +5,23 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: dde.n,v 1.25 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros -.TH dde n 1.3 dde "Tcl Bundled Packages" +.TH dde n 1.4 dde "Tcl Bundled Packages" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME dde \- Execute a Dynamic Data Exchange command .SH SYNOPSIS .sp -\fBpackage require dde 1.3\fR +\fBpackage require dde 1.4\fR .sp \fBdde servername\fR ?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR? .sp -\fBdde execute\fR ?\fB\-async\fR? \fIservice topic data\fR +.VS 8.6 +\fBdde execute\fR ?\fB\-async\fR? ?\fB\-binary\fR? \fIservice topic data\fR .sp -\fBdde poke\fR \fIservice topic item data\fR +\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 @@ -71,7 +71,7 @@ procedure is called with all the arguments provided by the remote call. .RE .TP -\fBdde execute\fR ?\fB\-async\fR? \fIservice topic data\fR +\fBdde execute\fR ?\fB\-async\fR? ?\fB\-binary\fR? \fIservice topic data\fR . \fBdde execute\fR takes the \fIdata\fR and sends it to the server indicated by \fIservice\fR with the topic indicated by \fItopic\fR. Typically, @@ -82,8 +82,15 @@ 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 \fIservice topic item data\fR +\fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR . \fBdde poke\fR passes the \fIdata\fR to the server indicated by \fIservice\fR using the \fItopic\fR and \fIitem\fR specified. Typically, @@ -92,6 +99,13 @@ 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 . @@ -147,7 +161,7 @@ unpredictable results. .PP An external application which wishes to run a script in Tcl should have that script store its result in a variable, run the \fBdde execute\fR -command, and the run \fBdde request\fR to get the value of the +command, and then run \fBdde request\fR to get the value of the variable. .PP When using DDE, be careful to ensure that the event queue is flushed @@ -164,9 +178,12 @@ particularly important website: .PP .CS package require dde -\fBdde execute\fR iexplore WWW_OpenURL http://www.tcl.tk/ +\fBdde execute\fR -async iexplore WWW_OpenURL http://www.tcl.tk/ .CE .SH "SEE ALSO" tk(n), winfo(n), send(n) .SH KEYWORDS application, dde, name, remote execution +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/define.n b/doc/define.n index e3f2e39..1c36ca3 100644 --- a/doc/define.n +++ b/doc/define.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: define.n,v 1.3 2009/04/11 11:18:51 dkf Exp $ -'\" .so man.macros .TH define n 0.3 TclOO "TclOO Commands" .BS @@ -83,14 +81,18 @@ 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 ?\fImethodName ...\fR? -. -This sets or updates the list of method names that are used to guard whether a +\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. If no \fImethodName\fR -arguments are present, the list of filter names is set to empty. +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? . @@ -116,12 +118,16 @@ 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. .TP -\fBmixin\fR ?\fIclassName ...\fR? -. -This sets or updates the list of additional classes that are to be mixed into +\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; if no classes are present, the -list of mixed-in classes is set to be empty. +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 . @@ -146,12 +152,19 @@ and operates identically to .QW "\fBoo::objdefine \fIcls subcommand ...\fR" . .TP -\fBsuperclass\fI className \fR?\fIclassName ...\fR? -. -This allows the alteration of the superclasses of the class being defined. +\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. +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? . @@ -162,18 +175,18 @@ context) by the class being defined. Note that the methods themselves may be actually defined by a superclass; subclass unexports override superclass visibility, and may be overridden by instance unexports. .TP -\fBvariable\fR ?\fIname ...\fR? +\fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR? .VS -This arranges for each of the named variables to be automatically made +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. Note that the list of variable names is the whole list of -variable names for the class. Each variable name must not have any namespace +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 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. +class. By default, this slot works by appending. .VE .SS "CONFIGURING OBJECTS" .PP @@ -200,15 +213,19 @@ 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 ?\fImethodName ...\fR? -. -This sets or updates the list of method names that are used to guard whether a +\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. If no -\fImethodName\fR arguments are present, the list of filter names is set to -empty. Note that the actual list of filters also depends on the filters set -upon any classes that the object is an instance of. +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? . @@ -229,12 +246,16 @@ 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. .TP -\fBmixin\fR ?\fIclassName ...\fR? -. -This sets or updates a per-object list of additional classes that are to be +\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; if no classes are present, the list of mixed-in -classes is set to be empty. +that is to be mixed in. +.VS +By default, this slot works by replacement. +.VE .TP \fBrenamemethod\fI fromName toName\fR . @@ -252,16 +273,70 @@ just through the \fBmy\fR command visible in the object's context) by the object being defined. Note that the methods themselves may be actually defined by a class; instance unexports override class visibility. .TP -\fBvariable\fR ?\fIname ...\fR? +\fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR? .VS -This arranges for each of the named variables to be automatically made -available in the methods declared by the object being defined. Note that the -list of variable names is the whole list of variable names for the object. -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 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. +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 +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. +.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: +.VE +.TP +\fIslot\fR \fB\-append\fR ?\fImember ...\fR? +.VS +This appends the given \fImember\fR elements to the slot definition. +.VE +.TP +\fIslot\fR \fB\-clear\fR +.VS +This sets the slot definition to the empty list. +.VE +.TP +\fIslot\fR \fB\-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 +first member argument begins with a hyphen will be an error. One of the above +operations should be used explicitly in those circumstances. +.SS "SLOT IMPLEMENTATION" +Internally, slot objects also define a method \fB\-\-default\-operation\fR +which is forwarded to the default operation of the slot (thus, for the class +.QW \fBvariable\fR +slot, this is forwarded to +.QW "\fBmy \-append\fR" ), +and these methods which provide the implementation interface: +.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 +.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. +.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 +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 .SH EXAMPLES This example demonstrates how to use both forms of the \fBoo::define\fR and @@ -288,11 +363,41 @@ o Foo Bar \fI\(-> error "unknown method Foo"\fR \fBoo::objdefine\fR o \fBrenamemethod\fR bar lollipop o lollipop \fI\(-> prints "hello world"\fR .CE +.PP +This example shows how additional classes can be mixed into an object. It also +shows how \fBmixin\fR is a slot that supports appending: +.PP +.CS +oo::object create inst +inst m1 \fI\(-> error "unknown method m1"\fR +inst m2 \fI\(-> error "unknown method m2"\fR + +oo::class create A { + \fBmethod\fR m1 {} { + puts "red brick" + } +} +\fBoo::objdefine\fR inst { + \fBmixin\fR A +} +inst m1 \fI\(-> prints "red brick"\fR +inst m2 \fI\(-> error "unknown method m2"\fR + +oo::class create B { + \fBmethod\fR m2 {} { + puts "blue brick" + } +} +\fBoo::objdefine\fR inst { + \fBmixin -append\fR B +} +inst m1 \fI\(-> prints "red brick"\fR +inst m2 \fI\(-> prints "blue brick"\fR +.CE .SH "SEE ALSO" next(n), oo::class(n), oo::object(n) .SH KEYWORDS -class, definition, method, object - +class, definition, method, object, slot .\" Local variables: .\" mode: nroff .\" fill-column: 78 @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: dict.n,v 1.24 2010/08/29 15:37:42 dkf Exp $ -'\" .so man.macros .TH dict n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -69,7 +67,7 @@ dictionary, and a condition of \fBTCL_CONTINUE\fR is equivalent to a false result. The key/value pairs are tested in the order in which the keys were inserted into the dictionary. .TP -\fBdict filter \fIdictionaryValue \fBvalue \fIglobPattern\fR +\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.) @@ -149,6 +147,31 @@ 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. .TP +\fBdict map \fR{\fIkeyVar valueVar\fR} \fIdictionaryValue body\fR +. +This command applies a transformation to each element of a dictionary, +returning a new dictionary. It takes three arguments: the first is a +two-element list of variable names (for the key and value respectively of each +mapping in the dictionary), the second the dictionary value to iterate across, +and the third a script to be evaluated for each mapping with the key and value +variables set appropriately (in the manner of \fBlmap\fR). In an iteration +where the evaluated script completes normally (\fBTCL_OK\fR, as opposed to an +\fBerror\fR, etc.) the result of the script is put into an accumulator +dictionary using the key that is the current contents of the \fIkeyVar\fR +variable at that point. The result of the \fBdict map\fR command is the +accumulator dictionary after all keys have been iterated over. +.RS +.PP +If the evaluation of the body for any particular step generates a \fBbreak\fR, +no further pairs from the dictionary will be iterated over and the \fBdict +map\fR command will terminate successfully immediately. If the evaluation of +the body for a particular step generates a \fBcontinue\fR result, the current +iteration is aborted and the accumulator dictionary is not modified. The order +of iteration is the natural order of the dictionary (typically the order in +which the keys were added to the dictionary; the order is the same as that +used in \fBdict for\fR). +.RE +.TP \fBdict merge \fR?\fIdictionaryValue ...\fR? . Return a dictionary that contains the contents of each of the @@ -253,6 +276,15 @@ exist after the command finishes (unless explicitly \fBunset\fR). Note that the mapping of values to variables does not use traces; changes to the \fIdictionaryVariable\fR's contents only happen when \fIbody\fR terminates. +.PP +If the \fIdictionaryVariable\fR contains a value that is not a dictionary at +the point when the \fIbody\fR terminates (which can easily happen if the name +is the same as any of the keys in dictionary) then an error occurs at that +point. This command is thus not recommended for use when the keys in the +dictionary are expected to clash with the \fIdictionaryVariable\fR name +itself. Where the contained key does map to a dictionary, the net effect is to +combine that inner dictionary into the outer dictionary; see the +\fBEXAMPLES\fR below for an illustration of this. .RE .SH "DICTIONARY VALUES" .PP @@ -390,10 +422,20 @@ sumDictionary myDict puts "dictionary is now \\"$myDict\\"" # prints: \fIdictionary is now "a {total 6} b {total 15}"\fR .CE +.PP +When \fBdict with\fR is used with a key that clashes with the name of the +dictionary variable: +.PP +.CS +set foo {foo {a b} bar 2 baz 3} +\fBdict with\fR foo {} +puts $foo +# prints: \fIa b foo {a b} bar 2 baz 3\fR +.CE .SH "SEE ALSO" -append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n) +append(n), array(n), foreach(n), mapeach(n), incr(n), list(n), lappend(n), set(n) .SH KEYWORDS -dictionary, create, update, lookup, iterate, filter +dictionary, create, update, lookup, iterate, filter, map '\" Local Variables: '\" mode: nroff '\" End: diff --git a/doc/encoding.n b/doc/encoding.n index 4e31bff..5269a18 100644 --- a/doc/encoding.n +++ b/doc/encoding.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: encoding.n,v 1.18 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH encoding n "8.1" Tcl "Tcl Built-In Commands" .BS @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: eof.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH eof n 7.5 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/error.n b/doc/error.n index d3cf694..d61bd7b 100644 --- a/doc/error.n +++ b/doc/error.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: error.n,v 1.14 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH error n "" Tcl "Tcl Built-In Commands" .BS @@ -41,19 +39,19 @@ to return a stack trace reflecting the original point of occurrence of the error: .PP .CS -\fBcatch {...} errMsg +catch {...} errMsg set savedInfo $::errorInfo \&... -error $errMsg $savedInfo\fR +\fBerror\fR $errMsg $savedInfo .CE .PP When working with Tcl 8.5 or later, the following code should be used instead: .PP .CS -\fBcatch {...} errMsg options +catch {...} errMsg options \&... -return -options $options $errMsg\fR +return -options $options $errMsg .CE .PP If the \fIcode\fR argument is present, then its value is stored @@ -75,3 +73,6 @@ if {1+2 != 3} { catch(n), return(n) .SH KEYWORDS error, exception +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: eval.n,v 1.14 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH eval n "" Tcl "Tcl Built-In Commands" .BS @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: exec.n,v 1.27 2010/03/20 21:26:39 dkf Exp $ -'\" .so man.macros .TH exec n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -241,7 +239,7 @@ names must use the short, cryptic, path format (e.g., using instead of .QW applbakery.default ), which can be obtained with the -.QW "\fBfile attributes \fIfileName \fB\-shortname\fR" +.QW "\fBfile attributes\fI fileName \fB\-shortname\fR" command. .PP Two or more forward or backward slashes in a row in a path refer to a @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: exit.n,v 1.11 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH exit n "" Tcl "Tcl Built-In Commands" .BS @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: expr.n,v 1.38 2009/05/26 09:08:05 ferrieux Exp $ -'\" .so man.macros .TH expr n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -30,7 +28,7 @@ Expressions almost always yield numeric results For example, the expression .PP .CS -\fBexpr 8.2 + 6\fR +\fBexpr\fR 8.2 + 6 .CE .PP evaluates to 14.2. @@ -41,9 +39,9 @@ additional operators not found in C. .SS OPERANDS .PP A Tcl expression consists of a combination of operands, operators, -and parentheses. +parentheses and commas. White space may be used between the operands and operators and -parentheses; it is ignored by the expression's instructions. +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 @@ -70,7 +68,8 @@ 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 boolean\fR. +As a boolean value, using any form understood by \fBstring is\fR +\fBboolean\fR. .IP [3] As a Tcl variable, using standard \fB$\fR notation. The variable's value will be used as the operand. @@ -135,7 +134,20 @@ 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 divisor. +an absolute value smaller than the absolute value of 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 +consequence of this is that the result of +.QW "-57 \fB/\fR 10" +is always -6, and the result of +.QW "-57 \fB%\fR 10" +is always 3. +.RE .TP 20 \fB+\0\0\-\fR . @@ -227,7 +239,7 @@ 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 .PP .CS -\fBexpr {$v ? [a] : [b]}\fR +\fBexpr\fR {$v ? [a] : [b]} .CE .PP only one of @@ -250,19 +262,19 @@ Tcl function in the \fBtcl::mathfunc\fR namespace. The processing of an expression such as: .PP .CS -\fBexpr {sin($x+$y)}\fR +\fBexpr\fR {sin($x+$y)} .CE .PP is the same in every way as the processing of: .PP .CS -\fBexpr {[tcl::mathfunc::sin [expr {$x+$y}]]}\fR +\fBexpr\fR {[tcl::mathfunc::sin [\fBexpr\fR {$x+$y}]]} .CE .PP which in turn is the same as the processing of: .PP .CS -\fBtcl::mathfunc::sin [expr {$x+$y}]\fR +tcl::mathfunc::sin [\fBexpr\fR {$x+$y}] .CE .PP The executor will search for \fBtcl::mathfunc::sin\fR using the usual @@ -271,6 +283,18 @@ rules for resolving functions in namespaces. Either current]::tcl::mathfunc::sin\fR will satisfy the request, and others may as well (depending on the current \fBnamespace path\fR setting). .PP +Some mathematical functions have several arguments, separated by commas like in C. Thus: +.PP +.CS +\fBexpr\fR {hypot($x,$y)} +.CE +.PP +ends up as +.PP +.CS +tcl::mathfunc::hypot $x $y +.CE +.PP See the \fBmathfunc\fR(n) manual page for the math functions that are available by default. .SS "TYPES, OVERFLOW, AND PRECISION" @@ -327,6 +351,7 @@ returns \fB4.0\fR, not \fB4\fR. 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 @@ -337,13 +362,12 @@ is that produced by the \fB%g\fR format specifier of Tcl's \fBformat\fR command. For example, the commands .PP .CS -\fBexpr {"0x03" > "2"}\fR -\fBexpr {"0y" < "0x12"}\fR +\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 after -the second operand is converted to the string \fB18\fR. +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 @@ -360,9 +384,9 @@ once by the Tcl parser and once by the \fBexpr\fR command. For example, the commands .PP .CS -\fBset a 3\fR -\fBset b {$a + 2}\fR -\fBexpr $b*4\fR +set a 3 +set b {$a + 2} +\fBexpr\fR $b*4 .CE .PP return 11, not a multiple of 4. @@ -446,3 +470,6 @@ Copyright (c) 1993 The Regents of the University of California. Copyright (c) 1994-2000 Sun Microsystems Incorporated. Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. .fi +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/fblocked.n b/doc/fblocked.n index a426b27..2841aee 100644 --- a/doc/fblocked.n +++ b/doc/fblocked.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: fblocked.n,v 1.9 2009/02/24 21:04:58 dkf Exp $ -.so man.macros .TH fblocked n 7.5 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! diff --git a/doc/fconfigure.n b/doc/fconfigure.n index d2b8ee1..ac0366c 100644 --- a/doc/fconfigure.n +++ b/doc/fconfigure.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: fconfigure.n,v 1.23 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH fconfigure n 8.3 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/fcopy.n b/doc/fcopy.n index 1178093..6a4bf1a 100644 --- a/doc/fcopy.n +++ b/doc/fcopy.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: fcopy.n,v 1.19 2009/01/05 14:04:51 dkf Exp $ -'\" .so man.macros .TH fcopy n 8.0 Tcl "Tcl Built-In Commands" .BS @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: file.n,v 1.60 2010/09/18 23:14:19 dkf Exp $ -'\" .so man.macros .TH file n 8.3 Tcl "Tcl Built-In Commands" .BS @@ -106,7 +104,7 @@ within a single filesystem, \fIfile copy\fR will copy soft links (i.e. the links themselves are copied, not the things they point to). Trying to overwrite a non-empty directory, overwrite a directory with a file, or overwrite a file with a directory will all result in errors even if -\fI\-force\fR was specified. Arguments are processed in the order +\fB\-force\fR was specified. Arguments are processed in the order specified, halting at the first error, if any. A \fB\-\|\-\fR marks the end of switches; the argument following the \fB\-\|\-\fR will be treated as a \fIsource\fR even if it starts with a \fB\-\fR. @@ -140,7 +138,7 @@ returned. For example, .RS .PP .CS -\fBfile dirname c:/\fR +\fBfile dirname\fR c:/ .CE .PP returns \fBc:/\fR. @@ -149,13 +147,13 @@ Note that tilde substitution will only be performed if it is necessary to complete the command. For example, .PP .CS -\fBfile dirname ~/src/foo.c\fR +\fBfile dirname\fR ~/src/foo.c .CE .PP returns \fB~/src\fR, whereas .PP .CS -\fBfile dirname ~\fR +\fBfile dirname\fR ~ .CE .PP returns \fB/home\fR (or something similar). @@ -195,7 +193,7 @@ proceed from the current argument. For example, .RS .PP .CS -\fBfile join a b /foo bar\fR +\fBfile join\fR a b /foo bar .CE .PP returns \fB/foo/bar\fR. @@ -229,9 +227,9 @@ If the user wishes to make a link of a specific type only, (and signal an error if for some reason that is not possible), then the optional \fI\-linktype\fR argument should be given. Accepted values for \fI\-linktype\fR are -.QW \-symbolic +.QW \fB\-symbolic\fR and -.QW \-hard . +.QW \fB\-hard\fR . .PP On Unix, symbolic links can be made to relative paths, and those paths must be relative to the actual \fIlinkName\fR's location (not to the @@ -377,12 +375,12 @@ generated. Returns a list whose elements are the path components in \fIname\fR. The first element of the list will have the same path type as \fIname\fR. All other elements will be relative. Path separators will be discarded -unless they are needed ensure that an element is unambiguously relative. +unless they are needed to ensure that an element is unambiguously relative. For example, under Unix .RS .PP .CS -file split /foo/~bar/baz +\fBfile split\fR /foo/~bar/baz .CE .PP returns diff --git a/doc/fileevent.n b/doc/fileevent.n index 05d68f3..df48d2a 100644 --- a/doc/fileevent.n +++ b/doc/fileevent.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: fileevent.n,v 1.15 2008/10/15 10:43:37 dkf Exp $ -'\" .so man.macros .TH fileevent n 7.5 Tcl "Tcl Built-In Commands" .BS @@ -125,7 +123,7 @@ proc GetData {chan} { } fconfigure $chan -blocking 0 -encoding binary -fileevent $chan readable [list GetData $chan] +\fBfileevent\fR $chan readable [list GetData $chan] .CE .PP The next example demonstrates use of \fBgets\fR to read line-oriented @@ -142,7 +140,7 @@ proc GetData {chan} { } fconfigure $chan -blocking 0 -buffering line -translation crlf -fileevent $chan readable [list GetData $chan] +\fBfileevent\fR $chan readable [list GetData $chan] .CE .SH CREDITS .PP diff --git a/doc/filename.n b/doc/filename.n index 5b41d76..d481fc9 100644 --- a/doc/filename.n +++ b/doc/filename.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: filename.n,v 1.20 2007/12/13 15:22:32 dgp Exp $ -'\" .so man.macros .TH filename n 7.5 Tcl "Tcl Built-In Commands" .BS @@ -40,7 +38,7 @@ type of a given path. .SH "PATH SYNTAX" .PP The rules for native names depend on the value reported in the Tcl -array element \fBtcl_platform(platform)\fR: +\fBplatform\fR element of the \fBtcl_platform\fR array: .TP 10 \fBUnix\fR On Unix and Apple MacOS X platforms, Tcl uses path names where the diff --git a/doc/flush.n b/doc/flush.n index 288b8fc..b8bf3e9 100644 --- a/doc/flush.n +++ b/doc/flush.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: flush.n,v 1.9 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH flush n 7.5 Tcl "Tcl Built-In Commands" .BS @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: for.n,v 1.13 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH for n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/foreach.n b/doc/foreach.n index 37bb455..fb075d3 100644 --- a/doc/foreach.n +++ b/doc/foreach.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: foreach.n,v 1.12 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH foreach n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/format.n b/doc/format.n index 242ebfd..23dfe60 100644 --- a/doc/format.n +++ b/doc/format.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: format.n,v 1.24 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH format n 8.1 Tcl "Tcl Built-In Commands" .BS @@ -143,7 +141,8 @@ 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 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 \fBtcl_platform(wordSize)\fR). +determined by the value of the \fBwordSize\fR element of the +\fBtcl_platform\fR array). .SS "MANDATORY CONVERSION TYPE" .PP The last thing in a conversion specifier is an alphabetic character @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: gets.n,v 1.8 2005/05/10 18:34:00 kennykb Exp $ -'\" .so man.macros .TH gets n 7.5 Tcl "Tcl Built-In Commands" .BS @@ -37,12 +35,12 @@ returned. .PP If end of file occurs while scanning for an end of line, the command returns whatever input is available up to the end of file. -If \fIchannelId\fR is in nonblocking mode and there is not a full +If \fIchannelId\fR is in non-blocking mode and there is not a full line of input available, the command returns an empty string and does not consume any input. If \fIvarName\fR is specified and an empty string is returned in \fIvarName\fR because of end-of-file or because of insufficient -data in nonblocking mode, then the return count is -1. +data in non-blocking mode, then the return count is -1. Note that if \fIvarName\fR is not specified then the end-of-file and no-full-line-available cases can produce the same results as if there were an input line consisting @@ -66,4 +64,8 @@ close $chan file(n), eof(n), fblocked(n), Tcl_StandardChannels(3) .SH KEYWORDS -blocking, channel, end of file, end of line, line, nonblocking, read +blocking, channel, end of file, end of line, line, non-blocking, read +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: @@ -4,9 +4,6 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: glob.n,v 1.26 2010/09/02 19:50:55 andreas_kupries Exp $ -'\" .so man.macros .TH glob n 8.3 Tcl "Tcl Built-In Commands" .BS @@ -233,9 +230,9 @@ and will not be interpreted as a wildcard character. One solution to this problem is to use the Unix style forward slash as a path separator. Windows style paths can be converted to Unix style paths with the command -.QW "\fBfile join $path\fR" +.QW "\fBfile join\fR \fB$path\fR" or -.QW "\fBfile normalize $path\fR" . +.QW "\fBfile normalize\fR \fB$path\fR" . .SH EXAMPLES .PP Find all the Tcl files in the current directory: diff --git a/doc/global.n b/doc/global.n index 5ccf587..c17c370 100644 --- a/doc/global.n +++ b/doc/global.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: global.n,v 1.14 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH global n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/history.n b/doc/history.n index cd3704f..ba507b4 100644 --- a/doc/history.n +++ b/doc/history.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: history.n,v 1.8 2007/12/13 15:22:32 dgp Exp $ -'\" .so man.macros .TH history n "" Tcl "Tcl Built-In Commands" .BS @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: http.n,v 1.40 2010/07/25 16:08:13 dkf Exp $ -'\" .so man.macros .TH "http" n 2.7 http "Tcl Bundled Packages" .BS @@ -18,9 +16,9 @@ http \- Client-side implementation of the HTTP/1.1 protocol \fBpackage require http ?2.7?\fR .\" See Also -useragent option documentation in body! .sp -\fB::http::config ?\fI-option value\fR ...? +\fB::http::config ?\fI\-option value\fR ...? .sp -\fB::http::geturl \fIurl\fR ?\fI-option value\fR ...? +\fB::http::geturl \fIurl\fR ?\fI\-option value\fR ...? .sp \fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...? .sp @@ -51,7 +49,8 @@ http \- Client-side implementation of the HTTP/1.1 protocol .SH DESCRIPTION .PP The \fBhttp\fR package provides the client side of the HTTP/1.1 -protocol. The package implements the GET, POST, and HEAD operations +protocol, as defined in 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 policy, so it can be used by untrusted applets to do URL fetching from @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: if.n,v 1.11 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH if n "" Tcl "Tcl Built-In Commands" .BS @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: incr.n,v 1.8 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH incr n "" Tcl "Tcl Built-In Commands" .BS @@ -3,13 +3,11 @@ '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies '\" Copyright (c) 1998-2000 Ajuba Solutions -'\" Copyright (c) 2007-2008 Donal K. Fellows +'\" Copyright (c) 2007-2012 Donal K. Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: info.n,v 1.38 2010/04/07 09:51:31 dkf Exp $ -'\" .so man.macros .TH info n 8.4 Tcl "Tcl Built-In Commands" .BS @@ -81,9 +79,9 @@ lines have been typed to complete the command. .TP \fBinfo coroutine\fR .VS 8.6 -Returns the name of the currently executing coroutine, 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). +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 .TP \fBinfo default \fIprocname arg varname\fR @@ -96,12 +94,30 @@ into variable \fIvarname\fR. .TP \fBinfo errorstack \fR?\fIinterp\fR? .VS 8.6 -Returns a list of lists made of 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. 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 toplevel in an interactive tclsh. +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. +.RS +.PP +This form is an even-sized list alternating 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 +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 +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 +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. +.RE .VE 8.6 .TP \fBinfo exists \fIvarName\fR @@ -164,7 +180,7 @@ means that the command is executed by \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 +means that the command is found in a pre-compiled script (loadable by the package \fBtbcload\fR), and no further information will be available. .RE @@ -185,9 +201,10 @@ normalized path of the file the command is in. \fBcmd\fR . This entry provides the string representation of the command. This is -usually the unsubstituted form, however for commands which are a pure -list executed by eval it is the substituted form as they have no other -string representation. Care is taken that the pure-List property of +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. .TP \fBproc\fR @@ -214,8 +231,8 @@ locations of commands in their bodies will be reported with type defined procedures, and literal eval scripts in files or statically defined procedures. .PP -In contrast, a procedure definition or \fBeval\fR within a dynamically -\fBeval\fRuated environment count linenumbers relative to the start of +In contrast, procedure definitions and \fBeval\fR within a dynamically +\fBeval\fRuated environment count line numbers relative to the start of 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. @@ -227,8 +244,8 @@ possible the lines are counted based on the smallest possible than any dynamic outer scope. .PP The syntactic form \fB{*}\fR is handled like \fBeval\fR. I.e. if it -is given a literal list argument the system tracks the linenumber -within the list words as well, and otherwise all linenumbers are +is given a literal list argument the system tracks the line number +within the list words as well, and otherwise all line numbers are counted relative to the start of each word (smallest scope) .RE .TP @@ -387,12 +404,35 @@ been set (e.g. a variable declared but not set by \fBvariable\fR). 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 +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 +.QW \fBunknown\fR +for the \fBunknown\fR type), a word giving the fully qualified name of the +class that defined the method, and a word describing the type of method +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. +.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 defintion is described as a two element list; the first +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 defintion, and the second +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 @@ -400,9 +440,9 @@ returns the empty list. \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 defintion is described as a two element +\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 defintion, and +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 @@ -472,8 +512,8 @@ class named \fIclass\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. +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 @@ -492,6 +532,28 @@ class's methods, constructor and destructor). 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 +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 +.QW \fBunknown\fR +for the \fBunknown\fR type), a word giving what defined the method (the fully +qualified name of the class, or the literal string \fBobject\fR if the method +implementation is on an instance), and a word describing the type of method +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. +.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 @@ -502,9 +564,9 @@ boolean value indicating whether the \fIobject\fR is of that class. \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 defintion is described as a two +\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 defintion, +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 @@ -614,7 +676,7 @@ 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) that constrains the list of variables returned. Note that this is different -from the lit returned by \fBinfo object variables\fR; that can include +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). @@ -660,6 +722,28 @@ method and get how it is defined. This procedure illustrates how: .PP .CS 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 { + return [\fBinfo class definition\fR $locus $name] + } + } + error "no definition for $method" +} +.CE +.PP +This is an alternate way of looking up the definition; it is implemented by +manually scanning the list of methods up the inheritance tree. This code +assumes that only single inheritance is in use, and that there is no complex +use of mixed-in classes (in such cases, using \fBinfo object call\fR as above +is the simplest way of doing this by far): +.PP +.CS +proc getDef {obj method} { if {$method in [\fBinfo object methods\fR $obj]} { # Assume no forwards return [\fBinfo object definition\fR $obj $method] @@ -668,7 +752,7 @@ proc getDef {obj method} { while {$method ni [\fBinfo class methods\fR $cls]} { # Assume the simple case set cls [lindex [\fBinfo class superclass\fR $cls] 0] - if {$cls eq {}} { + if {$cls eq ""} { error "no definition for $method" } } diff --git a/doc/interp.n b/doc/interp.n index 2d2330b..6ce10ee 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: interp.n,v 1.44 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH interp n 8.6 Tcl "Tcl Built-In Commands" .BS @@ -63,10 +61,18 @@ on how the alias mechanism works. A qualified interpreter name is a proper Tcl lists containing a subset of its ancestors in the interpreter hierarchy, terminated by the string naming the interpreter in its immediate master. Interpreter names are relative to the -interpreter in which they are used. For example, if \fBa\fR is a slave of -the current interpreter and it has a slave \fBa1\fR, which in turn has a -slave \fBa11\fR, the qualified name of \fBa11\fR in \fBa\fR is the list -\fBa1 a11\fR. +interpreter in which they are used. For example, if +.QW \fBa\fR +is a slave of the current interpreter and it has a slave +.QW \fBa1\fR , +which in turn has a slave +.QW \fBa11\fR , +the qualified name of +.QW \fBa11\fR +in +.QW \fBa\fR +is the list +.QW "\fBa1 a11\fR" . .PP The \fBinterp\fR command, described below, accepts qualified interpreter names as arguments; the interpreter in which the command is being evaluated @@ -110,10 +116,12 @@ invoking the command. interpreter. For example, .QW "\fBa b\fR" identifies an interpreter -\fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave -of the invoking interpreter. An empty list specifies the interpreter -invoking the command. \fIsrcCmd\fR gives the name of a new -command, which will be created in the source interpreter. +.QW \fBb\fR , +which is a slave of interpreter +.QW \fBa\fR , +which is a slave of the invoking interpreter. An empty list specifies +the interpreter invoking the command. \fIsrcCmd\fR gives the name of +a new command, which will be created in the source interpreter. \fITargetPath\fR and \fItargetCmd\fR specify a target interpreter and command, and the \fIarg\fR arguments, if any, specify additional arguments to \fItargetCmd\fR which are prepended to any arguments specified @@ -186,6 +194,48 @@ given name already exists in this master. The initial recursion limit of the slave interpreter is set to the current recursion limit of its parent interpreter. .TP +\fBinterp\fR \fBdebug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR?? +. +Controls whether frame-level stack information is captured in the +slave interpreter identified by \fIpath\fR. If no arguments are +given, option and current setting are returned. If \fB\-frame\fR +is given, the debug setting is set to the given boolean if provided +and the current setting is returned. +This only effects the output of \fBinfo frame\fR, in that exact +frame-level information for command invocation at the bytecode level +is only captured with this setting on. +.RS +.PP +For example, with code like +.PP +.CS +\fBproc\fR mycontrol {... script} { + ... + \fBuplevel\fR 1 $script + ... +} + +\fBproc\fR dosomething {...} { + ... + mycontrol { + somecode + } +} +.CE +.PP +the standard setting will provide a relative line number for the +command \fBsomecode\fR and the relevant frame will be of type +\fBeval\fR. With frame-debug active on the other hand the tracking +extends so far that the system will be able to determine the file and +absolute line number of this command, and return a frame of type +\fBsource\fR. This more exact information is paid for with slower +execution of all commands. +.PP +Note that once it is on, this flag cannot be switched back off: such +attempts are silently ignored. This is needed to maintain the +consistency of the underlying interpreter's state. +.RE +.TP \fBinterp\fR \fBdelete \fR?\fIpath ...?\fR . Deletes zero or more interpreters given by the optional \fIpath\fR @@ -296,7 +346,7 @@ already trusted. Returns the maximum allowable nesting depth for the interpreter specified by \fIpath\fR. If \fInewlimit\fR is specified, the interpreter recursion limit will be set so that nesting -of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR +of more than \fInewlimit\fR calls to \fBTcl_Eval\fR and related procedures in that interpreter will return an error. The \fInewlimit\fR value is also returned. The \fInewlimit\fR value must be a positive integer between 1 and the @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: join.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH join n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/lappend.n b/doc/lappend.n index 3a31a57..9bfab72 100644 --- a/doc/lappend.n +++ b/doc/lappend.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lappend.n,v 1.17 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH lappend n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/lassign.n b/doc/lassign.n index f2bfcda..6f5042b 100644 --- a/doc/lassign.n +++ b/doc/lassign.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lassign.n,v 1.7 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH lassign n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -30,17 +28,17 @@ An illustration of how multiple assignment works, and what happens when there are either too few or too many elements. .PP .CS -lassign {a b c} x y z ;# Empty return +\fBlassign\fR {a b c} x y z ;# Empty return puts $x ;# Prints "a" puts $y ;# Prints "b" puts $z ;# Prints "c" -lassign {d e} x y z ;# Empty return +\fBlassign\fR {d e} x y z ;# Empty return puts $x ;# Prints "d" puts $y ;# Prints "e" puts $z ;# Prints "" -lassign {f g h i} x y ;# Returns "h i" +\fBlassign\fR {f g h i} x y ;# Returns "h i" puts $x ;# Prints "f" puts $y ;# Prints "g" .CE @@ -51,10 +49,10 @@ the analogue of the command in many shell languages like this: .PP .CS -set ::argv [lassign $::argv argumentToReadOff] +set ::argv [\fBlassign\fR $::argv argumentToReadOff] .CE .SH "SEE ALSO" -lindex(n), list(n), lset(n), set(n) +lindex(n), list(n), lrange(n), lset(n), set(n) .SH KEYWORDS assign, element, list, multiple, set, variable '\"Local Variables: diff --git a/doc/library.n b/doc/library.n index 29b3045..2413692 100644 --- a/doc/library.n +++ b/doc/library.n @@ -5,7 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: library.n,v 1.27 2010/01/14 11:47:08 dkf Exp $ .so man.macros .TH library n "8.0" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/lindex.n b/doc/lindex.n index 4eac53a..bb272a6 100644 --- a/doc/lindex.n +++ b/doc/lindex.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lindex.n,v 1.21 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH lindex n 8.4 Tcl "Tcl Built-In Commands" .BS @@ -28,13 +26,13 @@ Tcl list and presented as a single argument. If no indices are presented, the command takes the form: .PP .CS -lindex list +\fBlindex \fIlist\fR .CE .PP or .PP .CS -lindex list {} +\fBlindex \fIlist\fR {} .CE .PP In this case, the return value of \fBlindex\fR is simply the value of the @@ -59,19 +57,19 @@ used in turn to select an element from the previous indexing operation, allowing the script to select elements from sublists. The command, .PP .CS -lindex $a 1 2 3 +\fBlindex\fR $a 1 2 3 .CE .PP or .PP .CS -lindex $a {1 2 3} +\fBlindex\fR $a {1 2 3} .CE .PP is synonymous with .PP .CS -lindex [lindex [lindex $a 1] 2] 3 +\fBlindex\fR [\fBlindex\fR [\fBlindex\fR $a 1] 2] 3 .CE .SH EXAMPLES .PP diff --git a/doc/linsert.n b/doc/linsert.n index 9cccab5..c722e4f 100644 --- a/doc/linsert.n +++ b/doc/linsert.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: linsert.n,v 1.18 2010/08/21 16:58:08 dkf Exp $ -'\" .so man.macros .TH linsert n 8.2 Tcl "Tcl Built-In Commands" .BS @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: list.n,v 1.14 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH list n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/llength.n b/doc/llength.n index e050ed9..b0ee4d9 100644 --- a/doc/llength.n +++ b/doc/llength.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: llength.n,v 1.15 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH llength n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/lmap.n b/doc/lmap.n new file mode 100644 index 0000000..880b05a --- /dev/null +++ b/doc/lmap.n @@ -0,0 +1,85 @@ +'\" +'\" Copyright (c) 2012 Trevor Davel +'\" +'\" 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 lmap n "" Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +lmap \- Iterate over all elements in one or more lists and collect results +.SH SYNOPSIS +\fBlmap \fIvarname list body\fR +.br +\fBlmap \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR +.BE +.SH DESCRIPTION +.PP +The \fBlmap\fR command implements a loop where the loop variable(s) take on +values from one or more lists, and the loop returns a list of results +collected from each iteration. +.PP +In the simplest case there is one loop variable, \fIvarname\fR, and one list, +\fIlist\fR, that is a list of values to assign to \fIvarname\fR. The +\fIbody\fR argument is a Tcl script. For each element of \fIlist\fR (in order +from first to last), \fBlmap\fR assigns the contents of the element to +\fIvarname\fR as if the \fBlindex\fR command had been used to extract the +element, then calls the Tcl interpreter to execute \fIbody\fR. If execution of +the body completes normally then the result of the body is appended to an +accumulator list. \fBlmap\fR returns the accumulator list. +.PP +In the general case there can be more than one value list (e.g., \fIlist1\fR +and \fIlist2\fR), and each value list can be associated with a list of loop +variables (e.g., \fIvarlist1\fR and \fIvarlist2\fR). During each iteration of +the loop the variables of each \fIvarlist\fR are assigned consecutive values +from the corresponding \fIlist\fR. Values in each \fIlist\fR are used in order +from first to last, and each value is used exactly once. The total number of +loop iterations is large enough to use up all the values from all the value +lists. If a value list does not contain enough elements for each of its loop +variables in each iteration, empty values are used for the missing elements. +.PP +The \fBbreak\fR and \fBcontinue\fR statements may be invoked inside +\fIbody\fR, with the same effect as in the \fBfor\fR and \fBforeach\fR +commands. In these cases the body does not complete normally and the result is +not appended to the accumulator list. +.SH EXAMPLES +.PP +Zip lists together: +.PP +.CS +set list1 {a b c d} +set list2 {1 2 3 4} +set zipped [\fBlmap\fR a $list1 b $list2 {list $a $b}] +# The value of zipped is "{a 1} {b 2} {c 3} {d 4}" +.CE +.PP +Filter a list to remove odd values: +.PP +.CS +set values {1 2 3 4 5 6 7 8} +proc isEven {n} {expr {($n % 2) == 0}} +set goodOnes [\fBlmap\fR x $values {expr { + [isEven $x] ? $x : [continue] +}}] +# The value of goodOnes is "2 4 6 8" +.CE +.PP +Take a prefix from a list based on the contents of the list: +.PP +.CS +set values {8 7 6 5 4 3 2 1} +proc isGood {counter} {expr {$n > 3}} +set prefix [\fBlmap\fR x $values {expr { + [isGood $x] ? $x : [break] +}}] +# The value of prefix is "8 7 6 5 4" +.CE +.SH "SEE ALSO" +break(n), continue(n), for(n), foreach(n), while(n) +.SH KEYWORDS +foreach, iteration, list, loop, map +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: load.n,v 1.26 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH load n 7.5 Tcl "Tcl Built-In Commands" .BS @@ -13,11 +11,11 @@ .SH NAME load \- Load machine code and initialize new commands .SH SYNOPSIS -\fBload \fIfileName\fR +\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName\fR .br -\fBload \fIfileName packageName\fR +\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName\fR .br -\fBload \fIfileName packageName interp\fR +\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName interp\fR .BE .SH DESCRIPTION .PP @@ -106,6 +104,22 @@ Otherwise, the \fBload\fR command searches for a dynamically loaded package by that name, and uses it if it is found. If several different files have been \fBload\fRed with different versions of the package, Tcl picks the file that was loaded first. +.PP +If \fB\-global\fR is specified preceding the filename, all symbols +found in the shared library are exported for global use by other +libraries. The option \fB\-lazy\fR delays the actual loading of +symbols until their first actual use. The options may be abbreviated. +The option \fB\-\-\fR indicates the end of the options, and should +be used if you wish to use a filename which starts with \fB\-\fR +and you provide a packageName to the \fBload\fR command. +.PP +On platforms which do not support the \fB\-global\fR or \fB\-lazy\fR +options, the options still exist but have no effect. Note that use +of the \fB\-global\fR or \fB\-lazy\fR option may lead to crashes +in your application later (in case of symbol conflicts resp. missing +symbols), which cannot be detected during the \fBload\fR. So, only +use this when you know what you are doing, you will not get a nice +error message when something is wrong with the loaded library. .SH "PORTABILITY ISSUES" .TP \fBWindows\fR\0\0\0\0\0 diff --git a/doc/lrange.n b/doc/lrange.n index bf67022..4f4816a 100644 --- a/doc/lrange.n +++ b/doc/lrange.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lrange.n,v 1.19 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH lrange n 7.4 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/lrepeat.n b/doc/lrepeat.n index a8141e0..59a1edf 100644 --- a/doc/lrepeat.n +++ b/doc/lrepeat.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lrepeat.n,v 1.7 2008/09/26 21:05:57 dgp Exp $ -'\" .so man.macros .TH lrepeat n 8.5 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/lreplace.n b/doc/lreplace.n index 5509367..6e6c3ea 100644 --- a/doc/lreplace.n +++ b/doc/lreplace.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lreplace.n,v 1.21 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH lreplace n 7.4 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/lreverse.n b/doc/lreverse.n index efda2a5..f52db9b 100644 --- a/doc/lreverse.n +++ b/doc/lreverse.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lreverse.n,v 1.7 2008/09/23 13:22:16 dkf Exp $ -'\" .so man.macros .TH lreverse n 8.5 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/lsearch.n b/doc/lsearch.n index 1caf479..7835352 100644 --- a/doc/lsearch.n +++ b/doc/lsearch.n @@ -7,8 +7,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lsearch.n,v 1.37 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH lsearch n 8.6 Tcl "Tcl Built-In Commands" .BS @@ -163,7 +161,7 @@ If this option is given, the index result from this command (or every index result when \fB\-all\fR is also specified) will be a complete path (suitable for use with \fBlindex\fR or \fBlset\fR) within the overall list to the term found. This option has no effect unless the -\fI\-index\fR is also specified, and is just a convenience short-cut. +\fB\-index\fR is also specified, and is just a convenience short-cut. .SH EXAMPLES .PP Basic searching: @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lset.n,v 1.20 2009/10/21 15:13:15 dkf Exp $ -'\" .so man.macros .TH lset n 8.4 Tcl "Tcl Built-In Commands" .BS @@ -28,13 +26,13 @@ Finally, it accepts a new value for an element of \fIvarName\fR. If no indices are presented, the command takes the form: .PP .CS -lset varName newValue +\fBlset\fR varName newValue .CE .PP or .PP .CS -lset varName {} newValue +\fBlset\fR varName {} newValue .CE .PP In this case, \fInewValue\fR replaces the old value of the variable @@ -70,13 +68,13 @@ allowing the script to alter elements in sublists (or append elements to sublists). The command, .PP .CS -lset a 1 2 newValue +\fBlset\fR a 1 2 newValue .CE .PP or .PP .CS -lset a {1 2} newValue +\fBlset\fR a {1 2} newValue .CE .PP replaces element 2 of sublist 1 with \fInewValue\fR. diff --git a/doc/lsort.n b/doc/lsort.n index 7b9d6a6..312048e 100644 --- a/doc/lsort.n +++ b/doc/lsort.n @@ -7,8 +7,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lsort.n,v 1.34 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH lsort n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -81,7 +79,7 @@ the values themselves. \fB\-index\0\fIindexList\fR . If this option is specified, each of the elements of \fIlist\fR must -itself be a proper Tcl sublist (unless \fB-stride\fR is used). +itself be a proper Tcl sublist (unless \fB\-stride\fR is used). Instead of sorting based on whole sublists, \fBlsort\fR will extract the \fIindexList\fR'th element from each sublist (as if the overall element and the \fIindexList\fR were passed to \fBlindex\fR) and sort @@ -90,7 +88,7 @@ For example, .RS .PP .CS -lsort -integer -index 1 \e +\fBlsort\fR -integer -index 1 \e {{First 24} {Second 18} {Third 30}} .CE .PP @@ -100,7 +98,7 @@ returns \fB{Second 18} {First 24} {Third 30}\fR, '\" This example is from the test suite! '\" .CS -lsort -index end-1 \e +\fBlsort\fR -index end-1 \e {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}} .CE .PP @@ -108,7 +106,7 @@ returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR, and .PP .CS -lsort -index {0 1} { +\fBlsort\fR -index {0 1} { {{b i g} 12345} {{d e m o} 34512} {{c o d e} 54321} @@ -137,7 +135,7 @@ in turn must be at least 2. For example, .PP .CS -lsort \-stride 2 {carrot 10 apple 50 banana 25} +\fBlsort\fR \-stride 2 {carrot 10 apple 50 banana 25} .CE .PP returns @@ -145,7 +143,7 @@ returns and .PP .CS -lsort \-stride 2 \-index 1 \-integer {carrot 10 apple 50 banana 25} +\fBlsort\fR \-stride 2 \-index 1 \-integer {carrot 10 apple 50 banana 25} .CE .PP returns @@ -163,7 +161,7 @@ effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or If this option is specified, then only the last set of duplicate elements found in the list will be retained. Note that duplicates are determined relative to the comparison used in the sort. Thus if -\fI\-index 0\fR is used, \fB{1 a}\fR and \fB{1 b}\fR would be +\fB\-index 0\fR is used, \fB{1 a}\fR and \fB{1 b}\fR would be considered duplicates and only the second element, \fB{1 b}\fR, would be retained. .SH "NOTES" diff --git a/doc/man.macros b/doc/man.macros index bd35803..ddd073d 100644 --- a/doc/man.macros +++ b/doc/man.macros @@ -67,8 +67,6 @@ .\" Print an open parenthesis, arg1 in quotes, then arg2 normally .\" (for trailing punctuation) and then a closing parenthesis. .\" -.\" RCS: @(#) $Id: man.macros,v 1.9 2008/01/29 15:32:33 dkf Exp $ -.\" .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. .if t .wh -1.3i ^B .nr ^l \n(.l diff --git a/doc/mathfunc.n b/doc/mathfunc.n index dd89a4c..14b448e 100644 --- a/doc/mathfunc.n +++ b/doc/mathfunc.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: mathfunc.n,v 1.22 2008/06/29 22:28:24 dkf Exp $ -'\" .so man.macros .TH mathfunc n 8.5 Tcl "Tcl Mathematical Functions" .BS @@ -197,16 +195,19 @@ Returns the floating-point remainder of the division of \fIx\fR by .TP \fBhypot \fIx y\fR . -Computes the length of the hypotenuse of a right-angled triangle -.QW "\fBsqrt\fR [\fBexpr\fR {\fIx\fB*\fIx\fB+\fIy\fB*\fIy\fR}]". +Computes the length of the hypotenuse of a right-angled triangle, +approximately +.QW "\fBsqrt\fR [\fBexpr\fR {\fIx\fB*\fIx\fB+\fIy\fB*\fIy\fR}]" +except for being more numerically stable when the two arguments have +substantially different magnitudes. .TP \fBint \fIarg\fR . The argument may be any numeric value. The integer part of \fIarg\fR is determined, and then the low order bits of that integer value up to the machine word size are returned as an integer value. For reference, -the number of bytes in the machine word are stored in -\fBtcl_platform(wordSize)\fR. +the number of bytes in the machine word are stored in the \fBwordSize\fR +element of the \fBtcl_platform\fR array. .TP \fBisqrt \fIarg\fR . @@ -298,3 +299,7 @@ Copyright (c) 1993 The Regents of the University of California. Copyright (c) 1994-2000 Sun Microsystems Incorporated. Copyright (c) 2005, 2006 by Kevin B. Kenny <kennykb@acm.org>. .fi +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: diff --git a/doc/mathop.n b/doc/mathop.n index 6ac7b8e..ac2ebc1 100644 --- a/doc/mathop.n +++ b/doc/mathop.n @@ -4,8 +4,6 @@ .\" See the file "license.terms" for information on usage and redistribution .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. .\" -.\" RCS: @(#) $Id: mathop.n,v 1.13 2010/06/30 23:29:26 dkf Exp $ -.\" .so man.macros .TH mathop n 8.5 Tcl "Tcl Mathematical Operator Commands" .BS @@ -128,14 +126,19 @@ will be an integer. .TP \fB%\fR \fInumber number\fR . -Returns the integral modulus of the first argument with respect to the second. -Each \fInumber\fR must have an integral value. Note that Tcl defines this -operation exactly even for negative numbers, so that the following equality -holds true: +Returns the integral modulus (i.e., remainder) of the first argument +with respect to the second. +Each \fInumber\fR must have an integral value. +Also, the sign of the result will be the same as the sign of the second +\fInumber\fR, which must not be zero. .RS .PP +Note that Tcl defines this operation exactly even for negative numbers, so +that the following command returns a true value (omitting the namespace for +clarity): +.PP .CS -(\fIx \fB/ \fIy\fR) \fB* \fIy \fB== \fIx \fB-\fR (\fIx \fB% \fIy\fR) +\fB==\fR [\fB*\fR [\fB/\fI x y\fR] \fIy\fR] [\fB\-\fI x\fR [\fB%\fI x y\fR]] .CE .RE .TP diff --git a/doc/memory.n b/doc/memory.n index b269d7a..f82c5b4 100644 --- a/doc/memory.n +++ b/doc/memory.n @@ -3,8 +3,6 @@ '\" Copyright (c) 2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: memory.n,v 1.14 2009/06/18 09:41:30 dkf Exp $ -'\" .so man.macros .TH memory n 8.1 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/msgcat.n b/doc/msgcat.n index 17cffcb..57fbb78 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -4,10 +4,8 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" SCCS: @(#) msgcat.n -'\" .so man.macros -.TH "msgcat" n 1.4 msgcat "Tcl Bundled Packages" +.TH "msgcat" n 1.5 msgcat "Tcl Bundled Packages" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -15,7 +13,7 @@ msgcat \- Tcl message catalog .SH SYNOPSIS \fBpackage require Tcl 8.5\fR .sp -\fBpackage require msgcat 1.4.2\fR +\fBpackage require msgcat 1.5.0\fR .sp \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? .sp @@ -31,6 +29,12 @@ msgcat \- Tcl message catalog .sp \fB::msgcat::mcmset \fIlocale src-trans-list\fR .sp +.VS "TIP 404" +\fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR? +.sp +\fB::msgcat::mcflmset \fIsrc-trans-list\fR +.VE "TIP 404" +.sp \fB::msgcat::mcunknown \fIlocale src-string\fR .BE .SH DESCRIPTION @@ -133,6 +137,26 @@ translate-string ...\fR?} \fB::msgcat::mcmset\fR can be significantly faster than multiple invocations of \fB::msgcat::mcset\fR. The function returns the number of translations set. .TP +\fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR? +.VS "TIP 404" +Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the +current namespace for the locale implied by the name of the message catalog +being loaded via \fB::msgcat::mcload\fR. If \fItranslate-string\fR is not +specified, \fIsrc-string\fR is used for both. The function returns +\fItranslate-string\fR. +.VE "TIP 404" +.TP +\fB::msgcat::mcflmset \fIsrc-trans-list\fR +.VS "TIP 404" +Sets the translation for multiple source strings in \fIsrc-trans-list\fR in +the current namespace for the locale implied by the name of the message +catalog being loaded via \fB::msgcat::mcload\fR. \fIsrc-trans-list\fR must +have an even number of elements and is in the form {\fIsrc-string +translate-string\fR ?\fIsrc-string translate-string ...\fR?} +\fB::msgcat::mcflmset\fR can be significantly faster than multiple invocations +of \fB::msgcat::mcflset\fR. The function returns the number of translations set. +.VE "TIP 404" +.TP \fB::msgcat::mcunknown \fIlocale src-string\fR . This routine is called by \fB::msgcat::mc\fR in the case when @@ -177,11 +201,14 @@ to extract its parts. The initial locale is then set by calling language[_country][_modifier] .CE .PP -On Windows, if none of those environment variables is set, msgcat will -attempt to extract locale information from the -registry. If all these attempts to discover an initial locale -from the user's environment fail, msgcat defaults to an initial -locale of +On Windows and Cygwin, if none of those environment variables is set, +msgcat will attempt to extract locale information from the registry. +From Windows Vista on, the RFC4747 locale name "lang-script-country-options" +is transformed to the locale as "lang_country_script" (Example: +sr-Latn-CS -> sr_cs_latin). For Windows XP, the language id is +transformed analoguously (Example: 0c1a -> sr_yu_cyrillic). +If all these attempts to discover an initial locale from the user's +environment fail, msgcat defaults to an initial locale of .QW C . .PP When a locale is specified by the user, a @@ -285,15 +312,15 @@ cause peculiar behavior, such as marking the message file as .QW hidden on Unix file systems. .IP [3] -The file contains a series of calls to \fBmcset\fR and -\fBmcmset\fR, setting the necessary translation strings +The file contains a series of calls to \fBmcflset\fR and +\fBmcflmset\fR, setting the necessary translation strings for the language, likely enclosed in a \fBnamespace eval\fR so that all source strings are tied to the namespace of the package. For example, a short \fBes.msg\fR might contain: .PP .CS namespace eval ::mypackage { - \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!" + \fB::msgcat::mcflset\fR "Free Beer!" "Cerveza Gracias!" } .CE .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES" @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: my.n,v 1.3 2009/11/02 10:03:12 dkf Exp $ -'\" .so man.macros .TH my n 0.1 TclOO "TclOO Commands" .BS @@ -33,7 +31,7 @@ Each object has its own \fBmy\fR command, contained in its instance namespace. .SH EXAMPLES .PP This example shows basic use of \fBmy\fR to use the \fBvariables\fR method of -the \fBoo::object\fR class, which is not publically visible by default: +the \fBoo::object\fR class, which is not publicly visible by default: .PP .CS oo::class create c { diff --git a/doc/namespace.n b/doc/namespace.n index f89ec91..b06d27a 100644 --- a/doc/namespace.n +++ b/doc/namespace.n @@ -7,8 +7,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: namespace.n,v 1.39 2009/12/27 22:06:12 dkf Exp $ -'\" .so man.macros .TH namespace n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -780,7 +778,10 @@ When non-empty, this option supplies a dictionary that provides a mapping from subcommand names to a list of prefix words to substitute in place of the ensemble command and subcommand words (in a manner similar to an alias created with \fBinterp alias\fR; the words are not -reparsed after substitution). When this option is empty, the mapping +reparsed after substitution); if the first word of any target is not +fully qualified when set, it is assumed to be relative to the +\fIcurrent\fR namespace and changed to be exactly that (that is, it is +always fully qualified when read). When this option is empty, the mapping will be from the local name of the subcommand to its fully-qualified name. Note that when this option is non-empty and the \fB\-subcommands\fR option is empty, the ensemble subcommand names @@ -4,19 +4,18 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: next.n,v 1.3 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH next n 0.1 TclOO "TclOO Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -next \- invoke superclass method implementations +next, nextto \- invoke superclass method implementations .SH SYNOPSIS .nf package require TclOO \fBnext\fR ?\fIarg ...\fR? +\fBnextto\fI class\fR ?\fIarg ...\fR? .fi .BE @@ -32,6 +31,13 @@ of the next method in the method chain; if there are no further methods in the method chain, the result of \fBnext\fR will be an error. The arguments, \fIarg\fR, to \fBnext\fR are the arguments to pass to the next method in the chain. +.PP +The \fBnextto\fR command is the same as the \fBnext\fR command, except that it +takes an additional \fIclass\fR argument that identifies a class whose +implementation of the current method chain (see \fBinfo object\fR \fBcall\fR) should +be used; the method implementation selected will be the one provided by the +given class, and it must refer to an existing non-filter invocation that lies +further along the chain than the current implementation. .SH "THE METHOD CHAIN" .PP When a method of an object is invoked, things happen in several stages: @@ -76,7 +82,7 @@ resulting list of implementations as possible. .PP When an object has a list of filter names set upon it, or is an instance of a class (or has mixed in a class) that has a list of filter names set upon it, -before every invokation of any method the filters are processed. Filter +before every invocation of any method the filters are processed. Filter implementations are found in class traversal order, as are the lists of filter names (each of which is traversed in natural list order). Explicitly invoking a method used as a filter will cause that method to be invoked twice, once as @@ -87,7 +93,7 @@ forward to the proper implementation of the method (which it does by invoking the \fBnext\fR command as filters are inserted into the front of the method call chain) and is responsible for returning the result of \fBnext\fR. .PP -Filters are not invoked when processing an invokation of the \fBunknown\fR +Filters are not invoked when processing an invocation of the \fBunknown\fR method because of a failure to locate a method implementation, or when invoking either constructors or destructors. .SH EXAMPLES @@ -129,7 +135,7 @@ in the superclass, args = pureSynthesis after chaining from subclass before chaining from subclass, args = in the superclass, args = a b -in the superclassm args = pureSynthesis +in the superclass, args = pureSynthesis after chaining from subclass .CE .PP @@ -159,7 +165,7 @@ oo::class create cache { method flushCache {} { my variable ValueCache unset ValueCache - \fI# Skip the cacheing\fR + \fI# Skip the caching\fR return -level 2 "" } } diff --git a/doc/object.n b/doc/object.n index 68d642b..6737e7e 100644 --- a/doc/object.n +++ b/doc/object.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: object.n,v 1.5 2009/11/02 09:54:45 dkf Exp $ -'\" .so man.macros .TH object n 0.1 TclOO "TclOO Commands" .BS @@ -42,7 +40,7 @@ current namespace whenever a method of the object is invoked (including a method of the class of the object). When the object is destroyed, its instance namespace is deleted. The instance namespace contains the object's \fBmy\fR command, which may be used to invoke non-exported methods of the object or to -create a reference to the object for the purpose of invokation which persists +create a reference to the object for the purpose of invocation which persists across renamings of the object. .SS CONSTRUCTOR The \fBoo::object\fR class does not define an explicit constructor. @@ -67,14 +65,19 @@ This method concatenates the arguments, \fIarg\fR, as if with \fBconcat\fR, and then evaluates the resulting script in the namespace that is uniquely associated with \fIobj\fR, returning the result of the evaluation. .TP -\fIobj \fBunknown \fImethodName\fR ?\fIarg ...\fR? +\fIobj \fBunknown ?\fImethodName\fR? ?\fIarg ...\fR? . This method is called when an attempt to invoke the method \fImethodName\fR on object \fIobj\fR fails. The arguments that the user supplied to the method are -given as \fIarg\fR argments. The default implementation (i.e. the one defined -by the \fBoo::object\fR class) generates a suitable error, detailing what -methods the object supports given whether the object was invoked by its public -name or through the \fBmy\fR command. +given as \fIarg\fR arguments. +.VS +If \fImethodName\fR is absent, the object was invoked with no method name at +all (or any other arguments). +.VE +The default implementation (i.e., the one defined by the \fBoo::object\fR +class) generates a suitable error, detailing what methods the object supports +given whether the object was invoked by its public name or through the +\fBmy\fR command. .TP \fIobj \fBvariable \fR?\fIvarName ...\fR? . @@ -88,6 +91,16 @@ must not have any namespace separators in it. The result is the empty string. . This method returns the globally qualified name of the variable \fIvarName\fR in the unique namespace for the object \fIobj\fR. +.TP +\fIobj \fB<cloned> \fIsourceObjectName\fR +.VS +This method is used by the \fBoo::object\fR command to copy the state of one +object to another. It is responsible for copying the procedures and variables +of the namespace of the source object (\fIsourceObjectName\fR) to the current +object. It does not copy any other types of commands or any traces on the +variables; that can be added if desired by overriding this method in a +subclass. +.VE .SH EXAMPLES .PP This example demonstrates basic use of an object. @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: open.n,v 1.36 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH open n 8.3 Tcl "Tcl Built-In Commands" .BS @@ -69,8 +67,8 @@ Set the initial access position to the end of the file. .PP All of the legal \fIaccess\fR values above may have the character \fBb\fR added as the second or third character in the value to -indicate that the opened channel should be configured with the -\fB\-translation binary\fR option, making the channel suitable for +indicate that the opened channel should be configured as if with the +\fBfconfigure\fR \fB\-translation binary\fR option, making the channel suitable for reading or writing of binary data. .PP In the second form, \fIaccess\fR consists of a list of any of the @@ -133,7 +131,7 @@ conjunction with the process's file mode creation mask. .SH "COMMAND PIPELINES" .PP If the first character of \fIfileName\fR is -.QW | +.QW \fB|\fR then the remaining characters of \fIfileName\fR are treated as a list of arguments that describe a command pipeline to invoke, in the same style as the @@ -141,10 +139,12 @@ arguments for \fBexec\fR. In this case, the channel identifier returned by \fBopen\fR may be used to write to the command's input pipe or read from its output pipe, depending on the value of \fIaccess\fR. -If write-only access is used (e.g. \fIaccess\fR is \fBw\fR), then -standard output for the pipeline is directed to the current standard +If write-only access is used (e.g. \fIaccess\fR is +.QW \fBw\fR ), +then standard output for the pipeline is directed to the current standard output unless overridden by the command. -If read-only access is used (e.g. \fIaccess\fR is \fBr\fR), +If read-only access is used (e.g. \fIaccess\fR is +.QW \fBr\fR ), standard input for the pipeline is taken from the current standard input unless overridden by the command. The id of the spawned process is accessible through the \fBpid\fR @@ -273,7 +273,7 @@ in the second form both input and output buffers are defined. (Windows only). This option is query only. In case of a serial communication error, \fBread\fR or \fBputs\fR returns a general Tcl file I/O error. -\fBfconfigure -lasterror\fR can be called to get a list of error details. +\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" .PP @@ -285,29 +285,29 @@ lines and handshaking. Here we are using the terms \fIworkstation\fR for your computer and \fImodem\fR for the external device, because some signal names (DCD, RI) come from modems. Of course your external device may use these signal lines for other purposes. -.IP \fBTXD(output)\fR +.IP \fBTXD\fR(output) \fBTransmitted Data:\fR Outgoing serial data. -.IP \fBRXD(input)\fR +.IP \fBRXD\fR(input) \fBReceived Data:\fRIncoming serial data. -.IP \fBRTS(output)\fR +.IP \fBRTS\fR(output) \fBRequest To Send:\fR This hardware handshake line informs the modem that your workstation is ready to receive data. Your workstation may automatically reset this signal to indicate that the input buffer is full. -.IP \fBCTS(input)\fR +.IP \fBCTS\fR(input) \fBClear To Send:\fR The complement to RTS. Indicates that the modem is ready to receive data. -.IP \fBDTR(output)\fR +.IP \fBDTR\fR(output) \fBData Terminal Ready:\fR This signal tells the modem that the workstation is ready to establish a link. DTR is often enabled automatically whenever a serial port is opened. -.IP \fBDSR(input)\fR +.IP \fBDSR\fR(input) \fBData Set Ready:\fR The complement to DTR. Tells the workstation that the modem is ready to establish a link. -.IP \fBDCD(input)\fR +.IP \fBDCD\fR(input) \fBData Carrier Detect:\fR This line becomes active when a modem detects a .QW Carrier signal. -.IP \fBRI(input)\fR +.IP \fBRI\fR(input) \fBRing Indicator:\fR Goes active when the modem detects an incoming call. .IP \fBBREAK\fR A BREAK condition is not a hardware signal line, but a logical zero on the @@ -323,13 +323,13 @@ event polling in background. The external device may have been switched off, the data lines may be noisy, system buffers may overrun or your mode settings may be wrong. That is why a reliable software should always \fBcatch\fR serial read operations. In cases of an error Tcl returns a -general file I/O error. Then \fBfconfigure -lasterror\fR may help to +general file I/O error. Then \fBfconfigure\fR \fB\-lasterror\fR may help to locate the problem. The following error codes may be returned. .TP 10 \fBRXOVER\fR . Windows input buffer overrun. The data comes faster than your scripts reads -it or your system is overloaded. Use \fBfconfigure -sysbuffer\fR to avoid a +it or your system is overloaded. Use \fBfconfigure\fR \fB\-sysbuffer\fR to avoid a temporary bottleneck and/or make your script faster. .TP 10 \fBTXFULL\fR @@ -347,13 +347,13 @@ and/or setup a lower(1) interrupt threshold value. \fBRXPARITY\fR . A parity error has been detected by your UART. -Wrong parity settings with \fBfconfigure -mode\fR or a noisy data line (RXD) +Wrong parity settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line (RXD) may cause this error. .TP 10 \fBFRAME\fR . A stop-bit error has been detected by your UART. -Wrong mode settings with \fBfconfigure -mode\fR or a noisy data line (RXD) +Wrong mode settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line (RXD) may cause this error. .TP 10 \fBBREAK\fR @@ -460,3 +460,6 @@ puts(n), exec(n), pid(n), fopen(3) .SH KEYWORDS access mode, append, create, file, non-blocking, open, permissions, pipeline, process, serial +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/package.n b/doc/package.n index 034cc18..6cf8991 100644 --- a/doc/package.n +++ b/doc/package.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: package.n,v 1.25 2010/03/31 20:55:52 dkf Exp $ -'\" .so man.macros .TH package n 7.5 Tcl "Tcl Built-In Commands" .BS @@ -14,7 +12,7 @@ package \- Facilities for package loading and version control .SH SYNOPSIS .nf -\fBpackage forget ?\fIpackage package ...\fR? +\fBpackage forget\fR ?\fIpackage package ...\fR? \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR? \fBpackage names\fR \fBpackage present \fIpackage \fR?\fIrequirement...\fR? @@ -45,7 +43,7 @@ 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 forget ?\fIpackage package ...\fR? +\fBpackage forget\fR ?\fIpackage package ...\fR? . Removes all information about each specified package from this interpreter, including information provided by both \fBpackage ifneeded\fR and @@ -177,7 +175,7 @@ If \fIcommand\fR is specified as an empty string, then the current . Compares the two version numbers given by \fIversion1\fR and \fIversion2\fR. Returns -1 if \fIversion1\fR is an earlier version than \fIversion2\fR, -0 if they are equal, and 1 if \fIversion1\fR is later than \fBversion2\fR. +0 if they are equal, and 1 if \fIversion1\fR is later than \fIversion2\fR. .TP \fBpackage versions \fIpackage\fR . diff --git a/doc/packagens.n b/doc/packagens.n index 150dff5..30617a3 100644 --- a/doc/packagens.n +++ b/doc/packagens.n @@ -2,8 +2,6 @@ '\" Copyright (c) 1998-2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: packagens.n,v 1.9 2007/12/13 15:22:33 dgp Exp $ -'\" .so man.macros .TH pkg::create n 8.3 Tcl "Tcl Built-In Commands" .BS @@ -11,7 +9,7 @@ .SH NAME pkg::create \- Construct an appropriate 'package ifneeded' command for a given package specification .SH SYNOPSIS -\fB::pkg::create \fI\-name packageName\fR \fI\-version packageVersion\fR ?\fI\-load filespec\fR? ... ?\fI\-source filespec\fR? ... +\fB::pkg::create\fR \fB\-name \fIpackageName \fB\-version \fIpackageVersion\fR ?\fB\-load \fIfilespec\fR? ... ?\fB\-source \fIfilespec\fR? ... .BE .SH DESCRIPTION @@ -24,13 +22,13 @@ command for a given package specification. It can be used to construct a .SH OPTIONS The parameters supported are: .TP -\fB\-name\fR\0\fIpackageName\fR +\fB\-name \fIpackageName\fR This parameter specifies the name of the package. It is required. .TP -\fB\-version\fR\0\fIpackageVersion\fR +\fB\-version \fIpackageVersion\fR This parameter specifies the version of the package. It is required. .TP -\fB\-load\fR\0\fIfilespec\fR +\fB\-load \fIfilespec\fR This parameter specifies a binary 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 @@ -39,7 +37,7 @@ list of procedures is empty or omitted, \fB::pkg::create\fR will set up the library for direct loading (see \fBpkg_mkIndex\fR). Any number of \fB\-load\fR parameters may be specified. .TP -\fB\-source\fR\0\fIfilespec\fR +\fB\-source \fIfilespec\fR This parameter is similar to the \fB\-load\fR parameter, except that it specifies a Tcl library that must be loaded with the \fBsource\fR command. Any number of \fB\-source\fR parameters may be @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: pid.n,v 1.9 2007/12/13 15:22:33 dgp Exp $ -'\" .so man.macros .TH pid n 7.0 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n index 90d87b1..2753208 100644 --- a/doc/pkgMkIndex.n +++ b/doc/pkgMkIndex.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.24 2009/02/24 21:04:58 dkf Exp $ -'\" .so man.macros .TH pkg_mkIndex n 8.3 Tcl "Tcl Built-In Commands" .BS @@ -14,7 +12,7 @@ pkg_mkIndex \- Build an index for automatic loading of packages .SH SYNOPSIS .nf -\fBpkg_mkIndex ?\fIoptions...\fR? \fIdir\fR ?\fIpattern pattern ...\fR? +\fBpkg_mkIndex\fR ?\fIoptions...\fR? \fIdir\fR ?\fIpattern pattern ...\fR? .fi .BE .SH DESCRIPTION @@ -155,7 +153,7 @@ commands for each version of each available package; these commands invoke \fBpackage provide\fR commands to announce the availability of the package, and they setup auto-loader information to load the files of the package. -If the \fI\-lazy\fR flag was provided when the \fBpkgIndex.tcl\fR +If the \fB\-lazy\fR flag was provided when the \fBpkgIndex.tcl\fR was generated, a given file of a given version of a given package is not actually loaded until the first time one of its commands @@ -170,7 +168,7 @@ commands or those which require special initialization, might select that their package files be loaded immediately upon \fBpackage require\fR instead of delaying the actual loading to the first use of one of the package's command. This is the default mode when generating the package -index. It can be overridden by specifying the \fI\-lazy\fR argument. +index. It can be overridden by specifying the \fB\-lazy\fR argument. .SH "COMPLEX CASES" Most complex cases of dependencies among scripts and binary files, and packages being split among scripts and @@ -230,3 +228,6 @@ the binary file may mask the package defined by the scripts. package(n) .SH KEYWORDS auto-load, index, package, version +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/platform.n b/doc/platform.n index c73c730..1553698 100644 --- a/doc/platform.n +++ b/doc/platform.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: platform.n,v 1.6 2009/04/08 19:17:45 andreas_kupries Exp $ -'\" .so man.macros .TH "platform" n 1.0.4 platform "Tcl Bundled Packages" .BS @@ -14,7 +12,7 @@ platform \- System identification support code and utilities .SH SYNOPSIS .nf -\fBpackage require platform ?1.0.4?\fR +\fBpackage require platform ?1.0.10?\fR .sp \fBplatform::generic\fR \fBplatform::identify\fR @@ -47,6 +45,7 @@ architecture a Tcl program is running on. .SH COMMANDS .TP \fBplatform::identify\fR +. This command returns an identifier describing the platform the Tcl core is running on. The returned identifier has the general format \fIOS\fR-\fICPU\fR. The \fIOS\fR part of the identifier may contain @@ -55,14 +54,33 @@ may contain dashes as well. The \fICPU\fR part will not contain dashes, making the preceding dash the last dash in the result. .TP \fBplatform::generic\fR +. This command returns a simplified identifier describing the platform the Tcl core is running on. In contrast to \fBplatform::identify\fR it leaves out details like kernel version, libc version, etc. The returned identifier has the general format \fIOS\fR-\fICPU\fR. .TP -\fBplatform::patterns \fIidentifier\fR +\fBplatform::patterns \fIidentifier\fR +. This command takes an identifier as returned by \fBplatform::identify\fR and returns a list of identifiers describing compatible architectures. +.SH EXAMPLE +.PP +This can be used to allow an application to be shipped with multiple builds of +a shared library, so that the same package works on many versions of an +operating system. For example: +.PP +.CS +\fBpackage require platform\fR +# Assume that app script is .../theapp/bin/theapp.tcl +set binDir [file dirname [file normalize [info script]]] +set libDir [file join $binDir .. lib] +set platLibDir [file join $libDir [\fBplatform::identify\fR]] +load [file join $platLibDir support[info sharedlibextension]] +.CE .SH KEYWORDS operating system, cpu architecture, platform, architecture +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/platform_shell.n b/doc/platform_shell.n index 16fa364..eef4d4e 100644 --- a/doc/platform_shell.n +++ b/doc/platform_shell.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: platform_shell.n,v 1.7 2008/11/10 17:57:30 andreas_kupries Exp $ -'\" .so man.macros .TH "platform::shell" n 1.1.4 platform::shell "Tcl Bundled Packages" .BS diff --git a/doc/prefix.n b/doc/prefix.n index 0ce3052..eb79996 100644 --- a/doc/prefix.n +++ b/doc/prefix.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: prefix.n,v 1.5 2010/01/13 09:13:35 dkf Exp $ -'\" .so man.macros .TH prefix n 8.6 Tcl "Tcl Built-In Commands" .BS @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: proc.n,v 1.13 2010/01/22 23:38:21 dkf Exp $ -'\" .so man.macros .TH proc n "" Tcl "Tcl Built-In Commands" .BS @@ -55,7 +53,7 @@ error). There is one special case to permit procedures with variable numbers of arguments. If the last formal argument has the name \fBargs\fR, then a call to the procedure may contain more actual arguments -than the procedure has formals. In this case, all of the actual arguments +than the procedure has formal arguments. In this case, all of the actual arguments starting at the one that would be assigned to \fBargs\fR are combined into a list (as if the \fBlist\fR command had been used); this combined value is assigned to the local variable \fBargs\fR. @@ -68,7 +66,7 @@ Other variables can only be accessed by invoking one of the \fBglobal\fR, \fBvariable\fR, \fBupvar\fR or \fBnamespace upvar\fR commands. The current namespace when \fIbody\fR is executed will be the namespace that the procedure's name exists in, which will be the -namespace that itwas created in unless it has been changed with +namespace that it was created in unless it has been changed with \fBrename\fR. '\" We may change this! It makes [variable] unstable when renamed and is '\" frankly pretty crazy, but doing it right is harder than it looks. @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: puts.n,v 1.14 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH puts n 7.5 Tcl "Tcl Built-In Commands" .BS @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: pwd.n,v 1.8 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH pwd n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/re_syntax.n b/doc/re_syntax.n index fec37fd..46a180d 100644 --- a/doc/re_syntax.n +++ b/doc/re_syntax.n @@ -4,10 +4,10 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: re_syntax.n,v 1.18 2007/12/13 15:22:33 dgp Exp $ '\" .so man.macros +.ie '\w'o''\w'\C'^o''' .ds qo \C'^o' +.el .ds qo u .TH re_syntax n "8.1" Tcl "Tcl Built-In Commands" .BS .SH NAME @@ -178,7 +178,7 @@ endpoint, so e.g. .QW \fBa\-c\-e\fR is illegal. Ranges in Tcl always use the Unicode collating sequence, but other programs may use other collating -sequences and this can be a source of incompatability between programs. +sequences and this can be a source of incompatibility between programs. .PP To include a literal \fB]\fR or \fB\-\fR in the list, the simplest method is to enclose it in \fB[.\fR and \fB.]\fR to make it a @@ -223,7 +223,8 @@ A character producing white space in displayed text. .IP \fBpunct\fR 8 A punctuation character. .IP \fBgraph\fR 8 -A character with a visible representation (includes both alnum and punct). +A character with a visible representation (includes both \fBalnum\fR +and \fBpunct\fR). .IP \fBcntrl\fR 8 A control character. .PP @@ -292,12 +293,12 @@ treatment is as if the enclosing delimiters were .QW \fB[.\fR \& and .QW \fB.]\fR .) -For example, if \fBo\fR and \fB\N'244'\fR are the members of an +For example, if \fBo\fR and \fB\*(qo\fR are the members of an equivalence class, then .QW \fB[[=o=]]\fR , -.QW \fB[[=\N'244'=]]\fR , +.QW \fB[[=\*(qo=]]\fR , and -.QW \fB[o\N'244']\fR \& +.QW \fB[o\*(qo]\fR \& are all synonymous. An equivalence class may not be an endpoint of a range. .RS .PP @@ -361,39 +362,42 @@ horizontal tab, as in C .TP \fB\eu\fIwxyz\fR . -(where \fIwxyz\fR is exactly four hexadecimal digits) the Unicode +(where \fIwxyz\fR is one up to four hexadecimal digits) the Unicode character \fBU+\fIwxyz\fR in the local byte ordering .TP \fB\eU\fIstuvwxyz\fR . -(where \fIstuvwxyz\fR is exactly eight hexadecimal digits) reserved -for a somewhat-hypothetical Unicode extension to 32 bits +(where \fIstuvwxyz\fR is one up to eight hexadecimal digits) reserved +for a Unicode extension up to 21 bits. The digits are parsed until the +first non-hexadecimal character is encountered, the maximun of eight +hexadecimal digits are reached, or an overflow would occur in the maximum +value of \fBU+\fI10ffff\fR. .TP \fB\ev\fR . vertical tab, as in C are all available. .TP -\fB\ex\fIhhh\fR +\fB\ex\fIhh\fR . -(where \fIhhh\fR is any sequence of hexadecimal digits) the character -whose hexadecimal value is \fB0x\fIhhh\fR (a single character no -matter how many hexadecimal digits are used). +(where \fIhh\fR is one or two hexadecimal digits) the character +whose hexadecimal value is \fB0x\fIhh\fR. .TP \fB\e0\fR . the character whose value is \fB0\fR .TP +\fB\e\fIxyz\fR +. +(where \fIxyz\fR is exactly three octal digits, and is not a \fIback +reference\fR (see below)) the character whose octal value is +\fB0\fIxyz\fR. The first digit must be in the range 0-3, otherwise +the two-digit form is assumed. +.TP \fB\e\fIxy\fR . (where \fIxy\fR is exactly two octal digits, and is not a \fIback reference\fR (see below)) the character whose octal value is \fB0\fIxy\fR -.TP -\fB\e\fIxyz\fR -. -(where \fIxyz\fR is exactly three octal digits, and is not a back -reference (see below)) the character whose octal value is -\fB0\fIxyz\fR .RE .PP Hexadecimal digits are @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: read.n,v 1.16 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH read n 8.1 Tcl "Tcl Built-In Commands" .BS @@ -56,7 +54,7 @@ which \fBfconfigure\fR will alter input. '\" Note: this advice actually applies to many versions of Tcl .PP For most applications a channel connected to a serial port should be -configured to be nonblocking: \fBfconfigure \fIchannelId \fB\-blocking +configured to be nonblocking: \fBfconfigure\fI channelId \fB\-blocking \fI0\fR. Then \fBread\fR behaves much like described above. Care must be taken when using \fBread\fR on blocking serial ports: .TP @@ -68,7 +66,7 @@ from the serial port. \fBread \fIchannelId\fR . In this form \fBread\fR blocks until the reception of the end-of-file -character, see \fBfconfigure -eofchar\fR. If there no end-of-file +character, see \fBfconfigure\fR \fB\-eofchar\fR. If there no end-of-file character has been configured for the channel, then \fBread\fR will block forever. .SH "EXAMPLE" @@ -86,3 +84,6 @@ set lines [split $data \en] file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3) .SH KEYWORDS blocking, channel, end of line, end of file, nonblocking, read, translation, encoding +'\"Local Variables: +'\"mode: nroff +'\"End: diff --git a/doc/refchan.n b/doc/refchan.n index 5007a09..a51c3d7 100644 --- a/doc/refchan.n +++ b/doc/refchan.n @@ -4,7 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: refchan.n,v 1.20 2010/03/09 21:15:19 andreas_kupries Exp $ .so man.macros .TH refchan n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -18,10 +17,10 @@ refchan \- command handler API of reflected channels .PP The Tcl-level handler for a reflected channel has to be a command with subcommands (termed an \fIensemble\fR, as it is a command such as that -created by \fBnamespace ensemble create\fR, though the implementation +created by \fBnamespace ensemble\fR \fBcreate\fR, though the implementation of handlers for reflected channel \fIis not\fR tied to \fBnamespace -ensemble\fRs in any way; see \fBEXAMPLE\fR below for how to build a -\fBclass\fR that supports the API). Note that \fIcmdPrefix\fR is whatever was +ensemble\fRs in any way; see \fBEXAMPLE\fR below for how to build an +\fBoo::class\fR that supports the API). Note that \fIcmdPrefix\fR is whatever was specified in the call to \fBchan create\fR, and may consist of multiple arguments; this will be expanded to multiple words in place of the prefix. diff --git a/doc/regexp.n b/doc/regexp.n index 4bdf467..5e857f8 100644 --- a/doc/regexp.n +++ b/doc/regexp.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: regexp.n,v 1.32 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH regexp n 8.3 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/registry.n b/doc/registry.n index 18e8ae0..2e69b1e 100644 --- a/doc/registry.n +++ b/doc/registry.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: registry.n,v 1.23 2010/03/31 22:12:26 dkf Exp $ -'\" .so man.macros .TH registry n 1.1 registry "Tcl Bundled Packages" .BS @@ -105,7 +103,7 @@ data, see \fBSUPPORTED TYPES\fR, below. If \fIpattern\fR is not specified, returns a list of names of all the subkeys of \fIkeyName\fR. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined -using the same rules as for \fBstring\fR \fBmatch\fR. If the +using the same rules as for \fBstring match\fR. If the specified \fIkeyName\fR does not exist, then an error is generated. .TP \fBregistry set \fIkeyName\fR ?\fIvalueName data \fR?\fItype\fR?? @@ -129,7 +127,7 @@ Returns the type of the value \fIvalueName\fR in the key If \fIpattern\fR is not specified, returns a list of names of all the values of \fIkeyName\fR. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined -using the same rules as for \fBstring\fR \fBmatch\fR. +using the same rules as for \fBstring match\fR. .SH "SUPPORTED TYPES" Each value under a key in the registry contains some data of a particular type in a type-specific representation. The \fBregistry\fR diff --git a/doc/regsub.n b/doc/regsub.n index 280692e..fe473d9 100644 --- a/doc/regsub.n +++ b/doc/regsub.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: regsub.n,v 1.29 2010/09/10 12:59:01 dkf Exp $ -'\" .so man.macros .TH regsub n 8.3 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/rename.n b/doc/rename.n index 7852937..77dc095 100644 --- a/doc/rename.n +++ b/doc/rename.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: rename.n,v 1.6 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH rename n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/return.n b/doc/return.n index 9a44ff6..b59a93d 100644 --- a/doc/return.n +++ b/doc/return.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: return.n,v 1.27 2010/04/07 09:51:31 dkf Exp $ -'\" .so man.macros .TH return n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -319,7 +317,8 @@ proc myReturn {args} { } .CE .SH "SEE ALSO" -break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n) +break(n), catch(n), continue(n), dict(n), error(n), proc(n), +source(n), tclvars(n), throw(n), try(n) .SH KEYWORDS break, catch, continue, error, exception, procedure, result, return .\" Local Variables: @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: safe.n,v 1.14 2010/02/26 10:32:40 rmax Exp $ -'\" .so man.macros .TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands" .BS @@ -69,7 +67,7 @@ The following commands are provided in the master interpreter: \fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR? Creates a safe interpreter, installs the aliases described in the section \fBALIASES\fR and initializes the auto-loading and package mechanism as -specified by the supplied \fBoptions\fR. +specified by the supplied \fIoptions\fR. See the \fBOPTIONS\fR section below for a description of the optional arguments. If the \fIslave\fR argument is omitted, a name will be generated. @@ -78,7 +76,7 @@ If the \fIslave\fR argument is omitted, a name will be generated. \fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR? This command is similar to \fBinterpCreate\fR except it that does not create the safe interpreter. \fIslave\fR must have been created by some -other means, like \fBinterp create \-safe\fR. +other means, like \fBinterp create\fR \fB\-safe\fR. .TP \fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR? If no \fIoptions\fR are given, returns the settings for all options for the @@ -295,9 +293,9 @@ executing. The only valid file names arguments for the \fBsource\fR and \fBload\fR aliases provided to the slave are path in the form of -\fB[file join \fR\fItoken filename\fR\fB]\fR (i.e. when using the -native file path formats: \fItoken\fR\fB/\fR\fIfilename\fR -on Unix and \fItoken\fR\fB\e\fIfilename\fR on Windows), +\fB[file join \fItoken filename\fB]\fR (i.e. when using the +native file path formats: \fItoken\fB/\fIfilename\fR +on Unix and \fItoken\fB\e\fIfilename\fR on Windows), where \fItoken\fR is representing one of the directories of the \fIaccessPath\fR list and \fIfilename\fR is one file in that directory (no sub directories access are allowed). @@ -356,3 +354,6 @@ interp(n), library(n), load(n), package(n), source(n), unknown(n) .SH KEYWORDS alias, auto\-loading, auto_mkindex, load, master interpreter, safe interpreter, slave interpreter, source +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: scan.n,v 1.29 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH scan n 8.4 Tcl "Tcl Built-In Commands" .BS @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: seek.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH seek n 8.1 Tcl "Tcl Built-In Commands" .BS @@ -51,7 +49,7 @@ position after the end of file. The \fIorigin\fR argument defaults to \fBstart\fR. .PP The command flushes all buffered output for the channel before the command -returns, even if the channel is in nonblocking mode. +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 @@ -88,3 +86,7 @@ close $f file(n), open(n), close(n), gets(n), tell(n), Tcl_StandardChannels(3) .SH KEYWORDS access position, file, seek +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: self.n,v 1.4 2009/07/24 08:23:00 dkf Exp $ -'\" .so man.macros .TH self n 0.1 TclOO "TclOO Commands" .BS @@ -27,6 +25,17 @@ takes an argument, \fIsubcommand\fR, that tells it what sort of information is actually desired; if omitted the result will be the same as if \fBself object\fR was invoked. The supported subcommands are: .TP +\fBself call\fR +. +This returns a two-element list describing the method implementations used to +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 +list that indicates which actual implementation is currently executing (the +first implementation to execute is always at index 0). +.TP \fBself caller\fR . When the method was invoked from inside another object method, this subcommand @@ -82,7 +91,7 @@ method call chain; the first element is the name of the class or object that declares the next part of the call chain, and the second element is the name of the method (with the strings \fB<constructor>\fR and \fB<destructor>\fR indicating constructors and destructors respectively). If invoked from a -method that is at the end of a call chain, this subcommand returns the emtpy +method that is at the end of a call chain, this subcommand returns the empty string. .TP \fBself object\fR @@ -111,6 +120,28 @@ c create b a foo \fI\(-> prints "this is the ::a object"\fR b foo \fI\(-> prints "this is the ::b object"\fR .CE +.PP +This demonstrates what a method call chain looks like, and how traversing +along it changes the index into it: +.PP +.CS +oo::class create c { + method x {} { + puts "Cls: [\fBself call\fR]" + } +} +c create a +oo::objdefine a { + method x {} { + puts "Obj: [\fBself call\fR]" + next + puts "Obj: [\fBself call\fR]" + } +} +a x \fI\(-> Obj: {{method x object method} {method x ::c method}} 0\fR + \fI\(-> Cls: {{method x object method} {method x ::c method}} 1\fR + \fI\(-> Obj: {{method x object method} {method x ::c method}} 0\fR +.CE .SH "SEE ALSO" info(n), next(n) .SH KEYWORDS @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: set.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH set n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/socket.n b/doc/socket.n index 7596abb..0a60457 100644 --- a/doc/socket.n +++ b/doc/socket.n @@ -5,9 +5,8 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: socket.n,v 1.20 2010/02/24 10:11:46 dkf Exp $ .so man.macros -.TH socket n 8.0 Tcl "Tcl Built-In Commands" +.TH socket n 8.6 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -20,18 +19,17 @@ socket \- Open a TCP network connection .BE .SH DESCRIPTION .PP -This command opens a network socket and returns a channel -identifier that may be used in future invocations of commands like -\fBread\fR, \fBputs\fR and \fBflush\fR. -At present only the TCP network protocol is supported; future -releases may include support for additional protocols. -The \fBsocket\fR command may be used to open either the client or -server side of a connection, depending on whether the \fB\-server\fR -switch is specified. +This command opens a network socket and returns a channel identifier +that may be used in future invocations of commands like \fBread\fR, +\fBputs\fR and \fBflush\fR. At present only the TCP network protocol +is supported over IPv4 and IPv6; future releases may include support +for additional protocols. The \fBsocket\fR command may be used to +open either the client or server side of a connection, depending on +whether the \fB\-server\fR switch is specified. .PP Note that the default encoding for \fIall\fR sockets is the system encoding, as returned by \fBencoding system\fR. Most of the time, you -will need to use \fBfconfigure\fR to alter this to something else, +will need to use \fBchan configure\fR to alter this to something else, such as \fIutf\-8\fR (ideal for communicating with other Tcl processes) or \fIiso8859\-1\fR (useful for many network protocols, especially the older ones). @@ -46,7 +44,7 @@ this port. \fIPort\fR is an integer port number (or service name, where supported and understood by the host operating system) and \fIhost\fR is either a domain-style name such as \fBwww.tcl.tk\fR or -a numerical IP address such as \fB127.0.0.1\fR. +a numerical IPv4 or IPv6 address such as \fB127.0.0.1\fR or \fB2001:DB8::1\fR. Use \fIlocalhost\fR to refer to the host on which the command is invoked. .PP The following options may also be present before \fIhost\fR @@ -70,51 +68,65 @@ port number will be chosen at random by the system software. .TP \fB\-async\fR . -The \fB\-async\fR option will cause the client socket to be connected -asynchronously. This means that the socket will be created immediately but -may not yet be connected to the server, when the call to \fBsocket\fR -returns. When a \fBgets\fR or \fBflush\fR is done on the socket before the -connection attempt succeeds or fails, if the socket is in blocking mode, the -operation will wait until the connection is completed or fails. If the -socket is in nonblocking mode and a \fBgets\fR or \fBflush\fR is done on -the socket before the connection attempt succeeds or fails, the operation -returns immediately and \fBfblocked\fR on the socket returns 1. Synchronous -client sockets may be switched (after they have connected) to operating in -asynchronous mode using: +This option will cause the client socket to be connected +asynchronously. This means that the socket will be created immediately +but may not yet be connected to the server, when the call to +\fBsocket\fR returns. .RS .PP +When a \fBgets\fR or \fBflush\fR is done on the socket before the +connection attempt succeeds or fails, if the socket is in blocking +mode, the operation will wait until the connection is completed or +fails. If the socket is in nonblocking mode and a \fBgets\fR or +\fBflush\fR is done on the socket before the connection attempt +succeeds or fails, the operation returns immediately and +\fBfblocked\fR on the socket returns 1. Synchronous client sockets may +be switched (after they have connected) to operating in asynchronous +mode using: +.PP .CS -\fBfconfigure \fIchan \fB\-blocking 0\fR +\fBchan configure \fIchan \fB\-blocking 0\fR .CE .PP -See the \fBfconfigure\fR command for more details. +See the \fBchan configure\fR command for more details. +.PP +The Tcl event loop should be running while an asynchronous connection +is in progress, because it may have to do several connection attempts +in the background. Running the event loop also allows you to set up a +writable channel event on the socket to get notified when the +asynchronous connection has succeeded or failed. See the \fBvwait\fR +and the \fBchan\fR commands for more details on the event loop and +channel events. .RE .SH "SERVER SOCKETS" .PP -If the \fB\-server\fR option is specified then the new socket -will be a server for the port given by \fIport\fR (either an integer -or a service name, where supported and understood by the host -operating system; if \fIport\fR is zero, the operating system will -allocate a free port to the server socket which may be discovered by -using \fBfconfigure\fR to read the \fB\-sockname\fR option). -Tcl will automatically accept connections to the given port. +If the \fB\-server\fR option is specified then the new socket will be +a server that listens on the given \fIport\fR (either an integer or a +service name, where supported and understood by the host operating +system; if \fIport\fR is zero, the operating system will allocate a +free port to the server socket which may be discovered by using +\fBchan configure\fR to read the \fB\-sockname\fR option). If the host +supports both, IPv4 and IPv6, the socket will listen on both address +families. Tcl will automatically accept connections to the given port. For each connection Tcl will create a new channel that may be used to -communicate with the client. Tcl then invokes \fIcommand\fR -(properly a command prefix list, see the \fBEXAMPLES\fR below) -with three additional arguments: the name of the new channel, the -address, in network address notation, of the client's host, and -the client's port number. +communicate with the client. Tcl then invokes \fIcommand\fR (properly +a command prefix list, see the \fBEXAMPLES\fR below) with three +additional arguments: the name of the new channel, the address, in +network address notation, of the client's host, and the client's port +number. .PP The following additional option may also be specified before \fIport\fR: .TP \fB\-myaddr\fI addr\fR . -\fIAddr\fR gives the domain-style name or numerical IP address of -the server-side network interface to use for the connection. -This option may be useful if the server machine has multiple network -interfaces. If the option is omitted then the server socket is bound -to the special address INADDR_ANY so that it can accept connections from -any interface. +\fIAddr\fR gives the domain-style name or numerical IP address of the +server-side network interface to use for the connection. This option +may be useful if the server machine has multiple network interfaces. +If the option is omitted then the server socket is bound to the +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. .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 @@ -131,11 +143,11 @@ will be accepted. If \fIport\fR is specified as zero, the operating system will allocate an unused port for use as a server socket. The port number actually allocated may be retrieved from the created server socket using the -\fBfconfigure\fR command to retrieve the \fB\-sockname\fR option as +\fBchan configure\fR command to retrieve the \fB\-sockname\fR option as described below. .SH "CONFIGURATION OPTIONS" .PP -The \fBfconfigure\fR command can be used to query several readonly +The \fBchan configure\fR command can be used to query several readonly configuration options for socket channels: .TP \fB\-error\fR @@ -144,13 +156,28 @@ This option gets the current error status of the given socket. This is useful when you need to determine if an asynchronous connect operation succeeded. If there was an error, the error message is returned. If there was no error, an empty string is returned. +.RS +.PP +Note that the error status is reset by the read operation; this mimics +the underlying getsockopt(SO_ERROR) call. +.RE .TP \fB\-sockname\fR . -This option returns a list of three elements, the address, the host name -and the port number for the socket. If the host name cannot be computed, -the second element is identical to the address, the first element of the -list. +For client sockets (including the channels that get created when a +client connects to a server socket) this option returns a list of +three elements, the address, the host name and the port number for the +socket. If the host name cannot be computed, the second element is +identical to the address, the first element of the list. +.RS +.PP +For server sockets this option returns a list of a multiple of three +elements each group of which have the same meaning as described +above. The list contains more than one group when the server socket +was created without \fB\-myaddr\fR or with the argument to +\fB\-myaddr\fR being a domain name that resolves multiple IP addresses +that are local to the invoking host. +.RE .TP \fB\-peername\fR . @@ -189,8 +216,10 @@ close $sockChan puts "The time on $server is $line1" puts "That is [lindex $line2 0]s since the server started" .CE +.SH "HISTORY" +Support for IPv6 was added in Tcl 8.6. .SH "SEE ALSO" -fconfigure(n), flush(n), open(n), read(n) +chan(n), flush(n), open(n), read(n) .SH KEYWORDS asynchronous I/O, bind, channel, connection, domain name, host, network address, socket, tcp '\" Local Variables: diff --git a/doc/source.n b/doc/source.n index d035f72..57a9fa2 100644 --- a/doc/source.n +++ b/doc/source.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: source.n,v 1.21 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH source n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/split.n b/doc/split.n index d68aaf3..e3259df 100644 --- a/doc/split.n +++ b/doc/split.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: split.n,v 1.12 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH split n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/string.n b/doc/string.n index 50fdeeb..6b3cc59 100644 --- a/doc/string.n +++ b/doc/string.n @@ -5,8 +5,6 @@ .\" See the file "license.terms" for information on usage and redistribution .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. .\" -.\" RCS: @(#) $Id: string.n,v 1.46 2009/11/08 20:01:18 dkf Exp $ -.\" .so man.macros .TH string n 8.1 Tcl "Tcl Built-In Commands" .BS @@ -27,11 +25,13 @@ Returns a decimal string giving the number of bytes used to represent \fIstring\fR in memory. Because UTF\-8 uses one to three bytes to represent Unicode characters, the byte length will not be the same as the character length in general. The cases where a script cares about -the byte length are rare. In almost all cases, you should use the +the byte length are rare. +.RS +.PP +In almost all cases, you should use the \fBstring length\fR operation (including determining the length of a -Tcl ByteArray object). Refer to the \fBTcl_NumUtfChars\fR manual +Tcl byte array value). Refer to the \fBTcl_NumUtfChars\fR manual entry for more details on the UTF\-8 representation. -.RS .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 @@ -123,6 +123,12 @@ outside of the [0\-9] range. Any of the valid forms for a double in Tcl, with optional surrounding whitespace. In case of under/overflow in the value, 0 is returned and the \fIvarname\fR will contain \-1. +.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. @@ -145,7 +151,8 @@ Any Unicode printing character, including space. .IP \fBpunct\fR 12 Any Unicode punctuation character. .IP \fBspace\fR 12 -Any Unicode space character. +Any Unicode whitespace character, zero width space (U+200b), +word joiner (U+2060) and zero width no-break space (U+feff) (=BOM). .IP \fBtrue\fR 12 Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is true. @@ -194,9 +201,9 @@ will return \fB1\fR. . Returns a decimal string giving the number of characters in \fIstring\fR. Note that this is not necessarily the same as the -number of bytes used to store the string. If the object is a -ByteArray object (such as those returned from reading a binary encoded -channel), then this will return the actual byte length of the object. +number of bytes used to store the string. If the value is a +byte array value (such as those returned from reading a binary encoded +channel), then this will return the actual byte length of the value. .TP \fBstring map\fR ?\fB\-nocase\fR? \fImapping string\fR . @@ -331,22 +338,22 @@ specified using the forms described in \fBSTRING INDICES\fR. . Returns a value equal to \fIstring\fR except that any leading or trailing characters present in the string given by \fIchars\fR are removed. If -\fIchars\fR is not specified then white space is removed (spaces, -tabs, newlines, and carriage returns). +\fIchars\fR is not specified then white space is removed (any character +for which \fBstring is space\fR returns 1, and "\0"). .TP \fBstring trimleft \fIstring\fR ?\fIchars\fR? . Returns a value equal to \fIstring\fR except that any leading characters present in the string given by \fIchars\fR are removed. If -\fIchars\fR is not specified then white space is removed (spaces, -tabs, newlines, and carriage returns). +\fIchars\fR is not specified then white space is removed (any character +for which \fBstring is space\fR returns 1, and "\0"). .TP \fBstring trimright \fIstring\fR ?\fIchars\fR? . Returns a value equal to \fIstring\fR except that any trailing characters present in the string given by \fIchars\fR are removed. If -\fIchars\fR is not specified then white space is removed (spaces, -tabs, newlines, and carriage returns). +\fIchars\fR is not specified then white space is removed (any character +for which \fBstring is space\fR returns 1, and "\0"). .TP \fBstring wordend \fIstring charIndex\fR . diff --git a/doc/subst.n b/doc/subst.n index e4a4f2d..aba2bc9 100644 --- a/doc/subst.n +++ b/doc/subst.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: subst.n,v 1.18 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH subst n 7.4 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/switch.n b/doc/switch.n index ea83c0a..acde6cb 100644 --- a/doc/switch.n +++ b/doc/switch.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: switch.n,v 1.21 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH switch n 8.5 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/tailcall.n b/doc/tailcall.n index 93af2b5..6a88aca 100644 --- a/doc/tailcall.n +++ b/doc/tailcall.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tailcall.n,v 1.2 2010/01/20 09:41:14 dkf Exp $ -'\" .so man.macros .TH tailcall n 8.6 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/tclsh.1 b/doc/tclsh.1 index f9f3780..8e7fb9e 100644 --- a/doc/tclsh.1 +++ b/doc/tclsh.1 @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tclsh.1,v 1.18 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH tclsh 1 "" Tcl "Tcl Applications" .BS @@ -14,7 +12,7 @@ .SH NAME tclsh \- Simple shell containing Tcl interpreter .SH SYNOPSIS -\fBtclsh\fR ?-encoding \fIname\fR? ?\fIfileName arg arg ...\fR? +\fBtclsh\fR ?\fB\-encoding \fIname\fR? ?\fIfileName arg arg ...\fR? .BE .SH DESCRIPTION .PP diff --git a/doc/tcltest.n b/doc/tcltest.n index ceb05a3..731bed7 100644 --- a/doc/tcltest.n +++ b/doc/tcltest.n @@ -8,8 +8,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tcltest.n,v 1.59 2010/01/14 11:47:09 dkf Exp $ -'\" .so man.macros .TH "tcltest" n 2.3 tcltest "Tcl Bundled Packages" .BS @@ -34,7 +32,7 @@ tcltest \- Test harness support code and utilities \fBtcltest::configure\fR \fBtcltest::configure \fI\-option\fR -\fBtcltest::configure \fI\-option value\fR ?\fI-option value ...\fR? +\fBtcltest::configure \fI\-option value\fR ?\fI\-option value ...\fR? \fBtcltest::customMatch \fImode command\fR \fBtcltest::testConstraint \fIconstraint\fR ?\fIvalue\fR? \fBtcltest::outputChannel \fR?\fIchannelID\fR? @@ -92,7 +90,7 @@ of how to use the commands of \fBtcltest\fR to produce test suites for your Tcl-enabled code. .SH COMMANDS .TP -\fBtest\fR \fIname description\fR ?\fI-option value ...\fR? +\fBtest\fR \fIname description\fR ?\fI\-option value ...\fR? . Defines and possibly runs a test with the name \fIname\fR and description \fIdescription\fR. The name and description of a test diff --git a/doc/tclvars.n b/doc/tclvars.n index 792d5c8..44a8e11 100644 --- a/doc/tclvars.n +++ b/doc/tclvars.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tclvars.n,v 1.42 2010/01/14 11:47:09 dkf Exp $ -'\" .so man.macros .TH tclvars n 8.0 Tcl "Tcl Built-In Commands" .BS @@ -101,6 +99,23 @@ Tcl format, using .QW / as the path separator, regardless of platform. This variable is only used when initializing the \fBauto_path\fR variable. +.TP +\fBenv(TCL_TZ)\fR, \fBenv(TZ)\fR +. +These specify the default timezone used for parsing and formatting times and +dates in the \fBclock\fR command. On many platforms, the TZ environment +variable is set up by the operating system. +.TP +\fBenv(LC_ALL)\fR, \fBenv(LC_MESSAGES)\fR, \fBenv(LANG)\fR +. +These environment variables are used by the \fBmsgcat\fR package to +determine what locale to format messages using. +.TP +\fBenv(TCL_INTERP_DEBUG_FRAME)\fR +. +If existing, it has the same effect as running \fBinterp debug\fR +\fB{} -frame 1\fR +as the very first command of each new Tcl interpreter. .RE .TP \fBerrorCode\fR @@ -360,22 +375,41 @@ binary number. .RE .PP .RS -17 digits is +If \fBtcl_precision\fR is not zero, then when Tcl converts a floating +point number, it creates a decimal representation of at most +\fBtcl_precision\fR significant digits; the result may be shorter if +the shorter result represents the original number exactly. If no +result of at most \fBtcl_precision\fR digits is an exact representation +of the original number, the one that is closest to the original +number is chosen. +If the original number lies precisely between two equally accurate +decimal representations, then the one with an even value for the least +significant digit is chosen; for instance, if \fBtcl_precision\fR is 3, then +0.3125 will convert to 0.312, not 0.313, while 0.6875 will convert to +0.688, not 0.687. Any string of trailing zeroes that remains is trimmed. +.RE +.PP +.RS +a \fBtcl_precision\fR value of 17 digits is .QW perfect for IEEE floating-point in that it allows double-precision values to be converted to strings and back to -binary with no loss of information. However, using 17 digits prevents -any rounding, which produces longer, less intuitive results. For example, -\fBexpr {1.4}\fR returns 1.3999999999999999 with \fBtcl_precision\fR -set to 17, vs. 1.4 if \fBtcl_precision\fR is 12. +binary with no loss of information. For this reason, you will often +see it as a value in legacy code that must run on Tcl versions before +8.5. It is no longer recommended; as noted above, a zero value is the +preferred method. .RE .PP .RS All interpreters in a thread share a single \fBtcl_precision\fR value: changing it in one interpreter will affect all other interpreters as -well. However, safe interpreters are not allowed to modify the +well. Safe interpreters are not allowed to modify the variable. .RE +.PP +.RS +Valid values for \fBtcl_precision\fR range from 0 to 17. +.RE .TP \fBtcl_rcFileName\fR . @@ -462,6 +496,7 @@ bug fixes that retain backward compatibility. The value of this variable is returned by the \fBinfo tclversion\fR command. .SH "OTHER GLOBAL VARIABLES" +.PP The following variables are only guaranteed to exist in \fBtclsh\fR and \fBwish\fR executables; the Tcl library does not define them itself but many Tcl environments do. @@ -485,6 +520,42 @@ was invoked. Contains 1 if \fBtclsh\fR or \fBwish\fR is running interactively (no script was specified and standard input is a terminal-like device), 0 otherwise. +.SH EXAMPLES +.PP +To add a directory to the collection of locations searched by +\fBpackage require\fR, e.g., because of some application-specific +packages that are used, the \fBauto_path\fR variable needs to be +updated: +.PP +.CS +lappend ::\fBauto_path\fR [file join [pwd] "theLibDir"] +.CE +.PP +A simple though not very robust way to handle command line arguments +of the form +.QW "\-foo 1 \-bar 2" +is to load them into an array having first loaded in the default settings: +.CS +array set arguments {-foo 0 -bar 0 -grill 0} +array set arguments $::\fBargv\fR +puts "foo is $arguments(-foo)" +puts "bar is $arguments(-bar)" +puts "grill is $arguments(-grill)" +.CE +.PP +The \fBargv0\fR global variable can be used (in conjunction with the +\fBinfo script\fR command) to determine whether the current script is +being executed as the main script or loaded as a library. This is +useful because it allows a single script to be used as both a library +and a demonstration of that library: +.PP +.CS +if {$::\fBargv0\fR eq [info script]} { + # running as: tclsh example.tcl +} else { + package provide Example 1.0 +} +.CE .SH "SEE ALSO" eval(n), library(n), tclsh(1), tkvars(n), wish(1) .SH KEYWORDS @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tell.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH tell n 8.1 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/throw.n b/doc/throw.n index 2c69df8..d49fb24 100644 --- a/doc/throw.n +++ b/doc/throw.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: throw.n,v 1.1 2008/12/16 21:29:10 dkf Exp $ -'\" .so man.macros .TH throw n 8.6 Tcl "Tcl Built-In Commands" .BS @@ -42,7 +40,7 @@ The following produces an error that is identical to that produced by \fBthrow\fR {ARITH DIVZERO {divide by zero}} {divide by zero} .CE .SH "SEE ALSO" -catch(n), error(n), return(n), try(n) +catch(n), error(n), return(n), tclvars(n), try(n) .SH "KEYWORDS" error, exception '\" Local Variables: @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: time.n,v 1.10 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH time n "" Tcl "Tcl Built-In Commands" .BS @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tm.n,v 1.20 2010/09/08 16:53:20 andreas_kupries Exp $ -'\" .so man.macros .TH tm n 8.5 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/trace.n b/doc/trace.n index 37e5532..63ed1cb 100644 --- a/doc/trace.n +++ b/doc/trace.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: trace.n,v 1.27 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH trace n "8.4" Tcl "Tcl Built-In Commands" .BS @@ -145,7 +143,7 @@ error will occur. For \fBleave\fR and \fBleavestep\fR operations: .PP .CS -\fIcommand command-string code result op\fR +\fIcommandPrefix command-string code result op\fR .CE .PP \fICommand-string\fR gives the complete current command being diff --git a/doc/transchan.n b/doc/transchan.n index 0716591..e308e13 100644 --- a/doc/transchan.n +++ b/doc/transchan.n @@ -4,7 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: transchan.n,v 1.2 2008/10/07 15:00:10 dkf Exp $ .so man.macros .TH transchan n 8.6 Tcl "Tcl Built-In Commands" .BS @@ -55,7 +54,7 @@ if the interpreter is deleted. This mandatory subcommand is called first, and then never again (for the given \fIhandle\fR). Its responsibility is to initialize all parts of the transformation at the Tcl level. The \fImode\fR is a list containing any of -\fBread\fR and \fBwrite\fR. +\fBread \fRand \fBwrite\fR. .RS .TP \fBwrite\fR @@ -74,7 +73,7 @@ as error thrown by \fBchan push\fR. .SS "READ-RELATED SUBCOMMANDS" .PP These subcommands are used for handling transformations applied to readable -channels; though strictly \fBread\fR is optional, it must be supported if any +channels; though strictly \fBread \fRis optional, it must be supported if any of the others is or the channel will be made non-readable. .TP \fIcmdPrefix \fBdrain \fIhandle\fR @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: try.n,v 1.3 2010/04/15 08:52:55 dkf Exp $ -'\" .so man.macros .TH try n 8.6 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/unknown.n b/doc/unknown.n index 1b13c81..fc2a5a1 100644 --- a/doc/unknown.n +++ b/doc/unknown.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: unknown.n,v 1.10 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH unknown n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/unload.n b/doc/unload.n index 965149a..4c0b292 100644 --- a/doc/unload.n +++ b/doc/unload.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: unload.n,v 1.13 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH unload n 8.5 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/unset.n b/doc/unset.n index 52d82a5..64b334d 100644 --- a/doc/unset.n +++ b/doc/unset.n @@ -6,8 +6,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: unset.n,v 1.15 2010/04/18 11:51:43 dkf Exp $ -'\" .so man.macros .TH unset n 8.4 Tcl "Tcl Built-In Commands" .BS @@ -15,7 +13,7 @@ .SH NAME unset \- Delete variables .SH SYNOPSIS -\fBunset \fR?\fI\-nocomplain\fR? ?\fI\-\-\fR? ?\fIname name name ...\fR? +\fBunset \fR?\fB\-nocomplain\fR? ?\fB\-\-\fR? ?\fIname name name ...\fR? .BE .SH DESCRIPTION .PP @@ -27,9 +25,9 @@ element is removed without affecting the rest of the array. If a \fIname\fR consists of an array name with no parenthesized index, then the entire array is deleted. The \fBunset\fR command returns an empty string as result. -If \fI\-nocomplain\fR is specified as the first argument, any possible +If \fB\-nocomplain\fR is specified as the first argument, any possible errors are suppressed. The option may not be abbreviated, in order to -disambiguate it from possible variable names. The option \fI\-\-\fR +disambiguate it from possible variable names. The option \fB\-\-\fR indicates the end of the options, and should be used if you wish to remove a variable with the same name as any of the options. If an error occurs during variable deletion, any variables after the named one diff --git a/doc/update.n b/doc/update.n index 64adf34..0c77c5f 100644 --- a/doc/update.n +++ b/doc/update.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: update.n,v 1.12 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH update n 7.5 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/uplevel.n b/doc/uplevel.n index 016848b..6c8a957 100644 --- a/doc/uplevel.n +++ b/doc/uplevel.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: uplevel.n,v 1.12 2010/01/13 12:08:30 dkf Exp $ -'\" .so man.macros .TH uplevel n "" Tcl "Tcl Built-In Commands" .BS diff --git a/doc/upvar.n b/doc/upvar.n index 02a475d..60e5324 100644 --- a/doc/upvar.n +++ b/doc/upvar.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: upvar.n,v 1.21 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH upvar n "" Tcl "Tcl Built-In Commands" .BS @@ -23,8 +21,7 @@ This command arranges for one or more local variables in the current procedure to refer to variables in an enclosing procedure call or to global variables. \fILevel\fR may have any of the forms permitted for the \fBuplevel\fR -command, and may be omitted if the first letter of the first \fIotherVar\fR -is not \fB#\fR or a digit (it defaults to \fB1\fR). +command, and may be omitted (it defaults to \fB1\fR). For each \fIotherVar\fR argument, \fBupvar\fR makes the variable by that name in the procedure frame given by \fIlevel\fR (or at global level, if \fIlevel\fR is \fB#0\fR) accessible diff --git a/doc/variable.n b/doc/variable.n index 5497977..96263b6 100644 --- a/doc/variable.n +++ b/doc/variable.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: variable.n,v 1.12 2008/10/17 10:22:25 dkf Exp $ -'\" .so man.macros .TH variable n 8.0 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/vwait.n b/doc/vwait.n index d3c62ae..38a8081 100644 --- a/doc/vwait.n +++ b/doc/vwait.n @@ -4,8 +4,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: vwait.n,v 1.14 2010/01/20 13:42:17 dkf Exp $ -'\" .so man.macros .TH vwait n 8.0 Tcl "Tcl Built-In Commands" .BS diff --git a/doc/while.n b/doc/while.n index 03ae3cf..5416e25 100644 --- a/doc/while.n +++ b/doc/while.n @@ -5,8 +5,6 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: while.n,v 1.7 2010/01/14 14:52:17 dkf Exp $ -'\" .so man.macros .TH while n "" Tcl "Tcl Built-In Commands" .BS @@ -1,11 +1,9 @@ '\" -'\" Copyright (c) 2008 Donal K. Fellows +'\" Copyright (c) 2008-2012 Donal K. Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: zlib.n,v 1.9 2010/02/10 23:17:06 dkf Exp $ -'\" .so man.macros .TH zlib n 8.6 Tcl "Tcl Built-In Commands" .BS @@ -172,6 +170,13 @@ the .QW "\fIoptions ...\fR" to the \fBzlib push\fR command: .TP +\fB\-dictionary\fI binData\fR +.VS "TIP 400" +Sets the compression dictionary to use when working with compressing or +decompressing the data to be \fIbinData\fR. Not valid for transformations that +work with gzip-format data. +.VE +.TP \fB\-header\fI dictionary\fR . Passes a description of the gzip header to create, in the same format that @@ -181,15 +186,33 @@ Passes a description of the gzip header to create, in the same format that . How hard to compress the data. Must be an integer from 0 (uncompressed) to 9 (maximally compressed). -'\".TP -'\"\fB\-limit\fI readaheadLimit\fR -'\". -'\"The maximum number of bytes ahead to read. -'\"\fITODO: not yet implemented!\fR +.TP +\fB\-limit\fI readaheadLimit\fR +. +The maximum number of bytes ahead to read when decompressing. This defaults to +1, which ensures that data is always decompressed correctly, but may be +increased to improve performance. This is more useful when the channel is +non-blocking. .PP Both compressing and decompressing channel transformations add extra -configuration options that may be accessed through \fBchan configure\fR. Each -option is either a read-only or a write-only option. The options are: +configuration options that may be accessed through \fBchan configure\fR. The +options are: +.TP +\fB\-checksum\fI checksum\fR +. +This read-only option gets the current checksum for the uncompressed data that +the compression engine has seen so far. It is valid for both compressing and +decompressing transforms, but not for the raw inflate and deflate formats. The +compression algorithm depends on what format is being produced or consumed. +.TP +\fB\-dictionary\fI binData\fR +.VS "TIP 400" +This read-write options gets or sets the compression dictionary to use when +working with compressing or decompressing the data to be \fIbinData\fR. It is +not valid for transformations that work with gzip-format data, and should not +normally be set on compressing transformations other than at the point where +the transformation is stacked. +.VE .TP \fB\-flush\fI type\fR . @@ -200,62 +223,80 @@ expensive flush respectively. Flushing degrades the compression ratio, but makes it easier for a decompressor to recover more of the file in the case of data corruption. .TP -\fB\-checksum\fR -. -This read-only option, valid for both compressing and decompressing -transforms, gets the current checksum for the uncompressed data that the -compression engine has seen so far. The compression algorithm depends on what -format is being produced or consumed. -.TP -\fB\-header\fR +\fB\-header\fI dictionary\fR . This read-only option, only valid for decompressing transforms that are processing gzip-format data, returns the dictionary describing the header read off the data stream. +.TP +\fB\-limit\fI readaheadLimit\fR +. +This read-write option is used by decompressing channels to control the +maximum number of bytes ahead to read from the underlying data source. This +defaults to 1, which ensures that data is always decompressed correctly, but +may be increased to improve performance. This is more useful when the channel +is non-blocking. .RE .SS "STREAMING SUBCOMMAND" .TP -\fBzlib stream\fI mode\fR ?\fIlevel\fR? +\fBzlib stream\fI mode\fR ?\fIoptions\fR? . Creates a streaming compression or decompression command based on the \fImode\fR, and return the name of the command. For a description of how that command works, see \fBSTREAMING INSTANCE COMMAND\fR below. The following modes -are supported: +and \fIoptions\fR are supported: .RS .TP -\fBzlib stream compress\fR ?\fIlevel\fR? +\fBzlib stream compress\fR ?\fB\-dictionary \fIbindata\fR? ?\fB\-level \fIlevel\fR? . The stream will be a compressing stream that produces zlib-format output, using compression level \fIlevel\fR (if specified) which will be an integer -from 0 to 9. +from 0 to 9, +.VS "TIP 400" +and the compression dictionary \fIbindata\fR (if specified). +.VE .TP -\fBzlib stream decompress\fR +\fBzlib stream decompress\fR ?\fB\-dictionary \fIbindata\fR? . The stream will be a decompressing stream that takes zlib-format input and produces uncompressed output. +.VS "TIP 400" +If \fIbindata\fR is supplied, it is a compression dictionary to use if +required. +.VE .TP -\fBzlib stream deflate\fR ?\fIlevel\fR? +\fBzlib stream deflate\fR ?\fB\-dictionary \fIbindata\fR? ?\fB\-level \fIlevel\fR? . The stream will be a compressing stream that produces raw output, using compression level \fIlevel\fR (if specified) which will be an integer from 0 -to 9. +to 9, +.VS "TIP 400" +and the compression dictionary \fIbindata\fR (if specified). Note that +the raw compressed data includes no metadata about what compression +dictionary was used, if any; that is a feature of the zlib-format data. +.VE .TP \fBzlib stream gunzip\fR . The stream will be a decompressing stream that takes gzip-format input and produces uncompressed output. .TP -\fBzlib stream gzip\fR ?\fIlevel\fR? +\fBzlib stream gzip\fR ?\fB\-header \fIheader\fR? ?\fB\-level \fIlevel\fR? . The stream will be a compressing stream that produces gzip-format output, using compression level \fIlevel\fR (if specified) which will be an integer -from 0 to 9. -'\" TODO: Header dictionary! +from 0 to 9, and the header descriptor dictionary \fIheader\fR (if specified; +for keys see \fBzlib gzip\fR). .TP -\fBzlib stream inflate\fR +\fBzlib stream inflate\fR ?\fB\-dictionary \fIbindata\fR? . The stream will be a decompressing stream that takes raw compressed input and produces uncompressed output. +.VS "TIP 400" +If \fIbindata\fR is supplied, it is a compression dictionary to use. Note that +there are no checks in place to determine whether the compression dictionary +is correct. +.VE .RE .SS "CHECKSUMMING SUBCOMMANDS" .TP @@ -278,10 +319,10 @@ the transformed data. The full set of subcommands supported by a streaming instance command, \fIstream\fR, is as follows: .TP -\fIstream \fBadd\fR ?\fIoption\fR? \fIdata\fR +\fIstream \fBadd\fR ?\fIoption...\fR? \fIdata\fR . A short-cut for -.QW "\fIstream \fBput \fIoption data\fR" +.QW "\fIstream \fBput \fR?\fIoption...\fR? \fIdata\fR" followed by .QW "\fIstream \fBget\fR" . .TP @@ -319,15 +360,27 @@ A short-cut for Return up to \fIcount\fR bytes from \fIstream\fR's internal buffers with the transformation applied. If \fIcount\fR is omitted, the entire contents of the buffers are returned. +. +\fIstream \fBheader\fR +. +Return the gzip header description dictionary extracted from the stream. Only +supported for streams created with their \fImode\fR parameter set to +\fBgunzip\fR. .TP -\fIstream \fBput\fR ?\fIoption\fR? \fIdata\fR +\fIstream \fBput\fR ?\fIoption...\fR? \fIdata\fR . Append the contents of the binary string \fIdata\fR to \fIstream\fR's internal -buffers while applying the transformation. If present, \fIoption\fR must be -one of the following (or an unambiguous prefix) which are used to modify the +buffers while applying the transformation. The following \fIoption\fRs are +supported (or an unambiguous prefix of them), which are used to modify the way in which the transformation is applied: .RS .TP +\fB\-dictionary\fI binData\fR +.VS "TIP 400" +Sets the compression dictionary to use when working with compressing or +decompressing the data to be \fIbinData\fR. +.VE +.TP \fB\-finalize\fR . Mark the stream as finished, ensuring that all bytes have been wholly @@ -335,12 +388,22 @@ compressed or decompressed. For gzip streams, this also ensures that the footer is written to the stream. The stream will need to be reset before having more data written to it after this, though data can still be read out of the stream with the \fBget\fR subcommand. +.RS +.PP +This option is mutually exclusive with the \fB\-flush\fR and \fB\-fullflush\fR +options. +.RE .TP \fB\-flush\fR . Ensure that a decompressor consuming the bytes that the current (compressing) stream is producing will be able to produce all the bytes that have been compressed so far, at some performance penalty. +.RS +.PP +This option is mutually exclusive with the \fB\-finalize\fR and +\fB\-fullflush\fR options. +.RE .TP \fB\-fullflush\fR . @@ -348,6 +411,11 @@ Ensure that not only can a decompressor handle all the bytes produced so far (as with \fB\-flush\fR above) but also that it can restart from this point if it detects that the stream is partially corrupt. This incurs a substantial performance penalty. +.RS +.PP +This option is mutually exclusive with the \fB\-finalize\fR and \fB\-flush\fR +options. +.RE .RE .TP \fIstream \fBreset\fR @@ -386,7 +454,7 @@ $\fIstrm \fBclose\fR .SH "SEE ALSO" binary(n), chan(n), encoding(n), Tcl_ZlibDeflate(3), RFC1950 \- RFC1952 .SH "KEYWORDS" -compress, decompress, deflate, gzip, inflate +compress, decompress, deflate, gzip, inflate, zlib '\" Local Variables: '\" mode: nroff '\" End: |