diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Class.3 | 2 | ||||
| -rw-r--r-- | doc/CrtChannel.3 | 2 | ||||
| -rw-r--r-- | doc/DictObj.3 | 2 | ||||
| -rw-r--r-- | doc/Ensemble.3 | 2 | ||||
| -rw-r--r-- | doc/FileSystem.3 | 5 | ||||
| -rw-r--r-- | doc/FindExec.3 | 2 | ||||
| -rw-r--r-- | doc/GetStdChan.3 | 2 | ||||
| -rw-r--r-- | doc/GetTime.3 | 24 | ||||
| -rw-r--r-- | doc/Hash.3 | 2 | ||||
| -rw-r--r-- | doc/InitStubs.3 | 6 | ||||
| -rw-r--r-- | doc/OpenFileChnl.3 | 2 | ||||
| -rw-r--r-- | doc/RegConfig.3 | 2 | ||||
| -rw-r--r-- | doc/SetChanErr.3 | 2 | ||||
| -rw-r--r-- | doc/SplitPath.3 | 2 | ||||
| -rw-r--r-- | doc/StringObj.3 | 4 | ||||
| -rw-r--r-- | doc/Tcl.n | 2 | ||||
| -rw-r--r-- | doc/Thread.3 | 12 | ||||
| -rw-r--r-- | doc/binary.n | 4 | ||||
| -rw-r--r-- | doc/catch.n | 2 | ||||
| -rw-r--r-- | doc/chan.n | 36 | ||||
| -rw-r--r-- | doc/close.n | 17 | ||||
| -rw-r--r-- | doc/copy.n | 21 | ||||
| -rw-r--r-- | doc/define.n | 191 | ||||
| -rw-r--r-- | doc/gets.n | 10 | ||||
| -rw-r--r-- | doc/info.n | 82 | ||||
| -rw-r--r-- | doc/mathfunc.n | 4 | ||||
| -rw-r--r-- | doc/my.n | 2 | ||||
| -rw-r--r-- | doc/next.n | 8 | ||||
| -rw-r--r-- | doc/object.n | 27 | ||||
| -rw-r--r-- | doc/proc.n | 4 | ||||
| -rw-r--r-- | doc/re_syntax.n | 5 | ||||
| -rw-r--r-- | doc/seek.n | 6 | ||||
| -rw-r--r-- | doc/self.n | 2 | ||||
| -rw-r--r-- | doc/socket.n | 22 | ||||
| -rw-r--r-- | doc/string.n | 6 |
35 files changed, 344 insertions, 180 deletions
diff --git a/doc/Class.3 b/doc/Class.3 index dbb5b99..28cea9b 100644 --- a/doc/Class.3 +++ b/doc/Class.3 @@ -125,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/CrtChannel.3 b/doc/CrtChannel.3 index 9aadba2..478ef0b 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -211,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 diff --git a/doc/DictObj.3 b/doc/DictObj.3 index 74b8dd1..a5dc9e5 100644 --- a/doc/DictObj.3 +++ b/doc/DictObj.3 @@ -62,7 +62,7 @@ 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 +Points to the value for the key/value pair being manipulated within the dictionary object (or sub-object, in the case of \fBTcl_DictObjPutKeyList\fR.) .AP Tcl_Obj **valuePtrPtr out diff --git a/doc/Ensemble.3 b/doc/Ensemble.3 index 19c6099..8a8c74e 100644 --- a/doc/Ensemble.3 +++ b/doc/Ensemble.3 @@ -95,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 diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index e3870c3..cf785ae 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.3 @@ -649,8 +649,7 @@ 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 @@ -1005,7 +1004,7 @@ The \fIpathInFilesystemProc\fR field contains the address of a function which is called to determine whether a given path object 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, diff --git a/doc/FindExec.3 b/doc/FindExec.3 index 66cc1f1..e4b4ed0 100644 --- a/doc/FindExec.3 +++ b/doc/FindExec.3 @@ -47,7 +47,7 @@ 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 wheter the executable has a stderr +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. diff --git a/doc/GetStdChan.3 b/doc/GetStdChan.3 index 7bc2e1b..e76ad66 100644 --- a/doc/GetStdChan.3 +++ b/doc/GetStdChan.3 @@ -77,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 d902f90..f4da364 100644 --- a/doc/GetTime.3 +++ b/doc/GetTime.3 @@ -90,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 @@ -57,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. diff --git a/doc/InitStubs.3 b/doc/InitStubs.3 index 318c564..5f56278 100644 --- a/doc/InitStubs.3 +++ b/doc/InitStubs.3 @@ -63,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/OpenFileChnl.3 b/doc/OpenFileChnl.3 index 337a9a9..2368492 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -332,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 diff --git a/doc/RegConfig.3 b/doc/RegConfig.3 index 7c41350..063cc85 100644 --- a/doc/RegConfig.3 +++ b/doc/RegConfig.3 @@ -80,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/SetChanErr.3 b/doc/SetChanErr.3 index b6c1975..0a62dac 100644 --- a/doc/SetChanErr.3 +++ b/doc/SetChanErr.3 @@ -51,7 +51,7 @@ 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 diff --git a/doc/SplitPath.3 b/doc/SplitPath.3 index ec8f96b..7fdfce6 100644 --- a/doc/SplitPath.3 +++ b/doc/SplitPath.3 @@ -43,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 objectified 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/StringObj.3 b/doc/StringObj.3 index 371cdff..412ab78 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -125,7 +125,7 @@ the length of an object'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. @@ -230,7 +230,7 @@ object's new string representation. \fIobjPtr\fR. If the object 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 +repeated appends relatively efficiently (it over-allocates the string or Unicode space to avoid repeated reallocations and copies of object's string value). .PP @@ -214,7 +214,7 @@ inserted. The upper bits of the Unicode character will be 0. \e\fBU\fIhhhhhhhh\fR . The hexadecimal digits \fIhhhhhhhh\fR (one up to eight of them) give a -twentiy-one-bit hexadecimal value for the Unicode character that will be +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. diff --git a/doc/Thread.3 b/doc/Thread.3 index 4b5e7c3..ca135ee 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -70,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 @@ -91,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/binary.n b/doc/binary.n index 8133829..68bf9cc 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -92,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: @@ -135,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/catch.n b/doc/catch.n index 1da163d..a05ca71 100644 --- a/doc/catch.n +++ b/doc/catch.n @@ -77,7 +77,7 @@ 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: +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} ...], @@ -57,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 @@ -107,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. @@ -118,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). @@ -399,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 @@ -453,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 @@ -468,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 @@ -493,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. @@ -516,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 @@ -630,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). @@ -659,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 @@ -675,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. @@ -728,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/close.n b/doc/close.n index 2577cc5..4490f6a 100644 --- a/doc/close.n +++ b/doc/close.n @@ -23,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. @@ -56,16 +57,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 @@ -26,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/define.n b/doc/define.n index 58bc4cd..6bdd9c5 100644 --- a/doc/define.n +++ b/doc/define.n @@ -81,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? . @@ -114,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 . @@ -144,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\fI ?\fI\-slotOperation\fR? \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? . @@ -160,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 @@ -198,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? . @@ -227,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 . @@ -250,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 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 -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. +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 @@ -286,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 @@ -35,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 @@ -64,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: @@ -3,7 +3,7 @@ '\" 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. @@ -79,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 @@ -97,23 +97,27 @@ into variable \fIvarname\fR. 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 [info level 0]. \fBUP\fR indicates a shift in -variable frames generated by uplevel or similar, and applies to the previous -CALL item. Its parameter is the level offset. \fBINNER\fR identifies the -"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 proc call, even going to -sub-expr granularity. - -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. +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 @@ -176,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 @@ -197,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 @@ -226,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. @@ -239,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 @@ -425,9 +430,9 @@ actually use \fBnext\fR to transfer control along the call chain. \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 @@ -435,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 @@ -559,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 @@ -671,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). @@ -731,10 +736,11 @@ proc getDef {obj method} { } .CE .PP -This is an alternate way of implementing the definition lookup is 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: +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} { @@ -746,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/mathfunc.n b/doc/mathfunc.n index 3da6d5a..14b448e 100644 --- a/doc/mathfunc.n +++ b/doc/mathfunc.n @@ -299,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: @@ -31,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 { @@ -82,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 @@ -93,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 @@ -135,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 @@ -165,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 0640580..6737e7e 100644 --- a/doc/object.n +++ b/doc/object.n @@ -40,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. @@ -65,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? . @@ -86,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. @@ -53,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. @@ -66,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. diff --git a/doc/re_syntax.n b/doc/re_syntax.n index dacc41f..46a180d 100644 --- a/doc/re_syntax.n +++ b/doc/re_syntax.n @@ -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 @@ -49,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 @@ -86,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: @@ -91,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 diff --git a/doc/socket.n b/doc/socket.n index e3087c9..0a60457 100644 --- a/doc/socket.n +++ b/doc/socket.n @@ -72,7 +72,8 @@ 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 @@ -82,22 +83,20 @@ 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: -.RS .PP .CS \fBchan configure \fIchan \fB\-blocking 0\fR .CE .PP 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. Runnig the event loop also allows you to set up a +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 -asyncronous connection has succeeded or failed. See the \fBvwait\fR -and the \fBchan\fR comands for more details on the event loop and +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 @@ -157,9 +156,11 @@ 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 . @@ -168,14 +169,15 @@ 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 . diff --git a/doc/string.n b/doc/string.n index d960b71..1cbea16 100644 --- a/doc/string.n +++ b/doc/string.n @@ -121,6 +121,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. |