diff options
author | Kevin B Kenny <kennykb@acm.org> | 2005-07-12 20:35:39 (GMT) |
---|---|---|
committer | Kevin B Kenny <kennykb@acm.org> | 2005-07-12 20:35:39 (GMT) |
commit | c334d140e0e4e5ba9413a61342b706835242c2b2 (patch) | |
tree | cdaa1e132838631227d718df83e3fd0feebcb2d9 /doc | |
parent | 4d52de5e84c39cb72b2dbeb0666d44882bc13142 (diff) | |
download | tcl-c334d140e0e4e5ba9413a61342b706835242c2b2.zip tcl-c334d140e0e4e5ba9413a61342b706835242c2b2.tar.gz tcl-c334d140e0e4e5ba9413a61342b706835242c2b2.tar.bz2 |
merged changes from HEAD
Diffstat (limited to 'doc')
-rw-r--r-- | doc/CrtChannel.3 | 82 | ||||
-rw-r--r-- | doc/OpenFileChnl.3 | 19 | ||||
-rw-r--r-- | doc/chan.n | 588 | ||||
-rw-r--r-- | doc/expr.n | 19 | ||||
-rw-r--r-- | doc/glob.n | 11 | ||||
-rw-r--r-- | doc/info.n | 13 | ||||
-rw-r--r-- | doc/lsearch.n | 12 | ||||
-rw-r--r-- | doc/lsort.n | 11 | ||||
-rw-r--r-- | doc/mathfunc.n | 27 | ||||
-rw-r--r-- | doc/namespace.n | 36 | ||||
-rw-r--r-- | doc/string.n | 14 | ||||
-rw-r--r-- | doc/switch.n | 7 |
12 files changed, 769 insertions, 70 deletions
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index 5398854..8e9cb60 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -5,13 +5,13 @@ '\" 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.24.2.3 2005/04/10 23:14:39 kennykb Exp $ +'\" RCS: @(#) $Id: CrtChannel.3,v 1.24.2.4 2005/07/12 20:36:14 kennykb Exp $ .so man.macros .TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels +Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -98,6 +98,11 @@ Tcl_DriverWideSeekProc * Tcl_DriverThreadActionProc * \fBTcl_ChannelThreadActionProc\fR(\fItypePtr\fR) .sp +.VS 8.5 +Tcl_DriverTruncateProc * +\fBTcl_ChannelTruncateProc\fR(\fItypePtr\fR) +.VE 8.5 +.sp Tcl_DriverSetOptionProc * \fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR) .sp @@ -314,22 +319,25 @@ details about the old structure. The \fBTcl_ChannelType\fR structure contains the following fields: .CS typedef struct Tcl_ChannelType { - char *\fItypeName\fR; - Tcl_ChannelTypeVersion \fIversion\fR; - Tcl_DriverCloseProc *\fIcloseProc\fR; - Tcl_DriverInputProc *\fIinputProc\fR; - Tcl_DriverOutputProc *\fIoutputProc\fR; - Tcl_DriverSeekProc *\fIseekProc\fR; - Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; - Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; - Tcl_DriverWatchProc *\fIwatchProc\fR; - Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; - Tcl_DriverClose2Proc *\fIclose2Proc\fR; - Tcl_DriverBlockModeProc *\fIblockModeProc\fR; - Tcl_DriverFlushProc *\fIflushProc\fR; - Tcl_DriverHandlerProc *\fIhandlerProc\fR; - Tcl_DriverWideSeekProc *\fIwideSeekProc\fR; - Tcl_DriverThreadActionProc *\fIthreadActionProc\fR; + char *\fItypeName\fR; + Tcl_ChannelTypeVersion \fIversion\fR; + Tcl_DriverCloseProc *\fIcloseProc\fR; + Tcl_DriverInputProc *\fIinputProc\fR; + Tcl_DriverOutputProc *\fIoutputProc\fR; + Tcl_DriverSeekProc *\fIseekProc\fR; + Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; + Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; + Tcl_DriverWatchProc *\fIwatchProc\fR; + Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; + Tcl_DriverClose2Proc *\fIclose2Proc\fR; + Tcl_DriverBlockModeProc *\fIblockModeProc\fR; + Tcl_DriverFlushProc *\fIflushProc\fR; + Tcl_DriverHandlerProc *\fIhandlerProc\fR; + Tcl_DriverWideSeekProc *\fIwideSeekProc\fR; +.VS 8.5 + Tcl_DriverThreadActionProc *\fIthreadActionProc\fR; + Tcl_DriverTruncateProc *\fItruncateProc\fR; +.VE 8.5 } Tcl_ChannelType; .CE .PP @@ -349,6 +357,9 @@ structure, the following functions should be used to obtain the values: \fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR, \fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR, \fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR, +.VS 8.5 +\fBTcl_ChannelTruncateProc\fR, +.VE 8.5 \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR, \fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR, \fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR. @@ -373,7 +384,8 @@ that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended. \fBTCL_CHANNEL_VERSION_3\fR must be set to specifiy the \fIwideSeekProc\fR member. .VS 8.5 \fBTCL_CHANNEL_VERSION_4\fR must be set to specifiy the -\fIthreadActionProc\fR member (includes \fIwideSeekProc\fR). +\fIthreadActionProc\fR and \fItruncateProc\fR members (includes +\fIwideSeekProc\fR). .VE 8.5 If it is not set to any of these, then this \fBTcl_ChannelType\fR is assumed to have the original structure. See @@ -382,7 +394,11 @@ and function with either structures, stacked channels must be of at least \fBTCL_CHANNEL_VERSION_2\fR to function correctly. .PP This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns -one of \fBTCL_CHANNEL_VERSION_4\fR, \fBTCL_CHANNEL_VERSION_3\fR, +one of +.VS 8.5 +\fBTCL_CHANNEL_VERSION_4\fR, +.VE 8.5 +\fBTCL_CHANNEL_VERSION_3\fR, \fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR. .SS BLOCKMODEPROC .PP @@ -798,8 +814,8 @@ might be maintaining using the calling thread as the associate. See .PP .CS typedef void Tcl_DriverThreadActionProc( - ClientData \fIinstanceData\fR, - int \fIaction\fR); + ClientData \fIinstanceData\fR, + int \fIaction\fR); .CE .PP \fIInstanceData\fR is the same as the value passed to @@ -807,7 +823,26 @@ typedef void Tcl_DriverThreadActionProc( .PP These values can be retrieved with \fBTcl_ChannelThreadActionProc\fR, which returns a pointer to the function. - +.SS "TRUNCATEPROC" +.PP +The \fItruncateProc\fR field contains the address of the function +called by the generic layer when a channel is truncated to some +length. It can be NULL. +.PP +.CS +typedef int Tcl_DriverTruncateProc( + ClientData \fIinstanceData\fR, + Tcl_WideInt \fIlength\fR); +.CE +.PP +\fIInstanceData\fR is the same as the value passed to +\fBTcl_CreateChannel\fR when this channel was created, and +\fIlength\fR is the new length of the underlying file, which should +not be negative. The result should be 0 on success or an errno code +(suitable for use with \fBTcl_SetErrno\fR) on failure. +.PP +These values can be retrieved with \fBTcl_ChannelTruncateProc\fR, +which returns a pointer to the function. .SH TCL_BADCHANNELOPTION .PP This procedure generates a "bad option" error message in an @@ -883,6 +918,7 @@ typedef struct Tcl_ChannelType { Tcl_DriverBlockModeProc *\fIblockModeProc\fR; Tcl_DriverFlushProc *\fIflushProc\fR; Tcl_DriverHandlerProc *\fIhandlerProc\fR; + Tcl_DriverTruncateProc *\fItruncateProc\fR; } Tcl_ChannelType; .CE .PP diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index 30f633a..0c96c8b 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -4,13 +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: OpenFileChnl.3,v 1.29.2.1 2005/04/10 23:14:42 kennykb Exp $ +'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.29.2.2 2005/07/12 20:36:15 kennykb Exp $ .so man.macros .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels +Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_TruncateChannel, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -99,6 +99,11 @@ Tcl_WideInt Tcl_WideInt \fBTcl_Tell\fR(\fIchannel\fR) .sp +.VS 8.5 +int +\fBTcl_TruncateChannel\fR(\fIchannel, length\fR) +.VE 8.5 +.sp int \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR) .sp @@ -196,6 +201,8 @@ given by \fIseekMode\fR. May be either positive or negative. Relative to which point to seek; used with \fIoffset\fR to calculate the new access point for the channel. Legal values are \fBSEEK_SET\fR, \fBSEEK_CUR\fR, and \fBSEEK_END\fR. +.AP Tcl_WideInt length in +The (non-negative) length to truncate the channel the channel to. .AP "const char" *optionName in The name of an option applicable to this channel, such as \fB\-blocking\fR. May have any of the values accepted by the \fBfconfigure\fR command. @@ -592,6 +599,14 @@ After an error, the access point may or may not have been moved. \fBTcl_Tell\fR returns the current access point for a channel. The returned value is \-1 if the channel does not support seeking. +.SH TCL_TRUNCATECHANNEL +.PP +.VS 8.5 +\fBTcl_TruncateChannel\fR truncates the file underlying \fIchannel\fR +to a given \fIlength\fR of bytes. It returns \fBTCL_OK\fR if the +operation succeeded, and \fBTCL_ERROR\fR otherwise. +.VE 8.5 + .SH TCL_GETCHANNELOPTION .PP \fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of diff --git a/doc/chan.n b/doc/chan.n new file mode 100644 index 0000000..261389c --- /dev/null +++ b/doc/chan.n @@ -0,0 +1,588 @@ +'\" +'\" Copyright (c) 2005 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: chan.n,v 1.2.6.2 2005/07/12 20:36:15 kennykb Exp $ +.so man.macros +.TH chan n 8.5 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +chan \- Read, write and manipulate channels +.SH SYNOPSIS +\fBchan \fIoption\fR ?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +This command provides several operations for reading from, writing to +and otherwise manipulating open channels (such as have been created +with the \fBopen\fR and \fBsocket\fR commands, or the default named +channels \fBstdin\fR, \fBstdout\fR or \fBstderr\fR which correspond to +the process's standard input, output and error streams respectively). +\fIOption\fR indicates what to do with the channel; any unique +abbreviation for \fIoption\fR is acceptable. Valid options are: +.TP +\fBchan blocked \fIchannelId\fR +. +This tests whether the last input operation on the channel called +\fIchannelId\fR failed because it would have otherwise caused the +process to block, and returns 1 if that was the case. It returns 0 +otherwise. Note that this only ever returns 1 when the channel has +been configured to be non-blocking; all Tcl channels have blocking +turned on by default. +.TP +\fBchan close \fIchannelId\fR +. +Close and destroy the channel called \fIchannelId\fR. Note that this +deletes all existing file-events registered on the channel. +.RS +.PP +As part of closing the channel, all buffered output is flushed to the +channel's outpuot device, any buffered input is discarded, the +underlying operating system resource is closed and \fIchannelId\fR +becomes unavailable for future use. +.PP +If the channel is blocking, 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 command returns +immediately; output will be flushed in the background and the channel +will be closed when all the flushing is complete. +.PP +If \fIchannelId\fR is a blocking channel for a command pipeline then +\fBchan close\fR waits for the child processes to complete. +.PP +If the channel is shared between interpreters, then \fBchan close\fR +makes \fIchannelId\fR unavailable in the invoking interpreter but has +no other effect until all of the sharing interpreters have closed the +channel. When the last interpreter in which the channel is registered +invokes \fBchan close\fR (or \fBclose\fR), the cleanup actions +described above occur. See the \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. +.PP +The command returns an empty string, and may generate an error if +an error occurs while flushing output. If a command in a command +pipeline created with \fBopen\fR returns an error, \fBchan close\fR +generates an error (similar to the \fBexec\fR command.) +.RE +.TP +\fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... +. +Query or set the configuration options of the channel named +\fIchannelId\fR. +.RS +.PP +If no \fIoptionName\fR or \fIvalue\fR arguments are supplied, the +command returns a list containing alternating option names and values +for the channel. If \fIoptionName\fR is supplied but no \fIvalue\fR +then the command returns the current value of the given option. If +one or more pairs of \fIoptionName\fR and \fIvalue\fR are supplied, +the command sets each of the named options to the corresponding +\fIvalue\fR; in this case the return value is an empty string. +.PP +The options described below are supported for all channels. In +addition, each channel type may add options that only it supports. See +the manual entry for the command that creates each type of channels +for the options that that specific type of channel supports. For +example, see the manual entry for the \fBsocket\fR command for its +additional options. +.TP +\fB\-blocking\fR \fIboolean\fR +. +The \fB\-blocking\fR option determines whether I/O operations on the +channel can cause the process to block indefinitely. The value of the +option must be a proper boolean value. Channels are normally in +blocking mode; if a channel is placed into nonblocking 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 +work correctly, the application must be using the Tcl event loop +(e.g. by calling \fBTcl_DoOneEvent\fR or invoking the \fBvwait\fR +command). +.TP +\fB\-buffering\fR \fInewValue\fR +. +If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output +until its internal buffer is full or until the \fBchan flush\fR +command is invoked. If \fInewValue\fR is \fBline\fR, then the I/O +system will automatically flush output for the channel whenever a +newline character is output. If \fInewValue\fR is \fBnone\fR, the I/O +system will flush automatically after every output operation. The +default is for \fB\-buffering\fR to be set to \fBfull\fR except for +channels that connect to terminal-like devices; for these channels the +initial setting is \fBline\fR. Additionally, \fBstdin\fR and +\fBstdout\fR are initially set to \fBline\fR, and \fBstderr\fR is set +to \fBnone\fR. +.TP +\fB\-buffersize\fR \fInewSize\fR +. +\fINewvalue\fR must be an integer; its value is used to set the size +of buffers, in bytes, subsequently allocated for this channel to store +input or output. \fINewvalue\fR must be a number of no more than one +million, allowing buffers of up to one million bytes in size. +.TP +\fB\-encoding\fR \fIname\fR +. +This option is used to specify the encoding of the channel as one of +the named encodings returned by \fBencoding names\fR or the special +value \fBbinary\fR, so that the data can be converted to and from +Unicode for use in Tcl. For instance, in order for Tcl to read +characters from a Japanese file in \fBshiftjis\fR and properly process +and display the contents, the encoding would be set to \fBshiftjis\fR. +Thereafter, when reading from the channel, the bytes in the Japanese +file would be converted to Unicode as they are read. Writing is also +supported \- as Tcl strings are written to the channel they will +automatically be converted to the specified encoding on output. +.RS +.PP +If a file contains pure binary data (for instance, a JPEG image), the +encoding for the channel should be configured to be \fBbinary\fR. Tcl +will then assign no interpretation to the data in the file and simply +read or write raw bytes. The Tcl \fBbinary\fR command can be used to +manipulate this byte-oriented data. It is usually better to set the +\fB\-translation\fR option to \fBbinary\fR when you want to transfer +binary data, as this turns off the other automatic interpretations of +the bytes in the stream as well. +.PP +The default encoding for newly opened channels is the same platform- +and locale-dependent system encoding used for interfacing with the +operating system, as returned by \fBencoding system\fR. +.RE +.TP +\fB\-eofchar\fR \fIchar\fR +.TP +\fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR +. +This option supports DOS file systems that use Control-z (\ex1a) as an +end of file marker. If \fIchar\fR is not an empty string, then this +character signals end-of-file when it is encountered during input. +For output, the end-of-file character is output when the channel is +closed. If \fIchar\fR is the empty string, then there is no special +end of file character marker. For read-write channels, a two-element +list specifies the end of file marker for input and output, +respectively. As a convenience, when setting the end-of-file +character for a read-write channel you can specify a single value that +will apply to both reading and writing. When querying the end-of-file +character of a read-write channel, a two-element list will always be +returned. The default value for \fB\-eofchar\fR is the empty string +in all cases except for files under Windows. In that case the +\fB\-eofchar\fR is Control-z (\ex1a) for reading and the empty string +for writing. +.TP +\fB\-translation\fR \fImode\fR +.TP +\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR +. +In Tcl scripts the end of a line is always represented using a single +newline character (\en). However, in actual files and devices the end +of a line may be represented differently on different platforms, or +even for different devices on the same platform. For example, under +UNIX newlines are used in files, whereas carriage-return-linefeed +sequences are normally used in network connections. On input (i.e., +with \fBchan gets\fP and \fBchan read\fP) the Tcl I/O system +automatically translates the external end-of-line representation into +newline characters. Upon output (i.e., with \fBchan puts\fP), the I/O +system translates newlines to the external end-of-line representation. +The default translation mode, \fBauto\fP, handles all the common cases +automatically, but the \fB\-translation\fR option provides explicit +control over the end of line translations. +.RS +.PP +The value associated with \fB\-translation\fR is a single item for +read-only and write-only channels. The value is a two-element list for +read-write channels; the read translation mode is the first element of +the list, and the write translation mode is the second element. As a +convenience, when setting the translation mode for a read-write channel +you can specify a single value that will apply to both reading and +writing. When querying the translation mode of a read-write channel, a +two-element list will always be returned. The following values are +currently supported: +.TP +\fBauto\fR +. +As the input translation mode, \fBauto\fR treats any of newline +(\fBlf\fP), carriage return (\fBcr\fP), or carriage return followed by +a newline (\fBcrlf\fP) as the end of line representation. The end of +line representation can even change from line-to-line, and all cases +are translated to a newline. As the output translation mode, +\fBauto\fR chooses a platform specific representation; for sockets on +all platforms Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses +\fBlf\fR, and for the various flavors of Windows it chooses +\fBcrlf\fR. The default setting for \fB\-translation\fR is \fBauto\fR +for both input and output. +.TP +\fBbinary\fR +. +No end-of-line translations are performed. This is nearly identical +to \fBlf\fP mode, except that in addition \fBbinary\fP mode also sets +the end-of-file character to the empty string (which disables it) and +sets the encoding to \fBbinary\fR (which disables encoding filtering). +See the description of \fB\-eofchar\fR and \fB\-encoding\fR for more +information. +.TP +\fBcr\fR +. +The end of a line in the underlying file or device is represented by a +single carriage return character. As the input translation mode, +\fBcr\fP mode converts carriage returns to newline characters. As the +output translation mode, \fBcr\fP mode translates newline characters +to carriage returns. +.TP +\fBcrlf\fR +. +The end of a line in the underlying file or device is represented by a +carriage return character followed by a linefeed character. As the +input translation mode, \fBcrlf\fP mode converts +carriage-return-linefeed sequences to newline characters. As the +output translation mode, \fBcrlf\fP mode translates newline characters +to carriage-return-linefeed sequences. This mode is typically used on +Windows platforms and for network connections. +.TP +\fBlf\fR +. +The end of a line in the underlying file or device is represented by a +single newline (linefeed) character. In this mode no translations +occur during either input or output. This mode is typically used on +UNIX platforms. +.RE +.RE +.TP +\fBchan copy \fIinputChan outputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? +. +Copy data from the channel \fIinputChan\fR, which must have been +opened for reading, to the channel \fIoutputChan\fR, which must have +been opened for writing. The \fBchan copy\fR command leverages the +buffering in the Tcl I/O system to avoid extra copies and to avoid +buffering too much data in main memory when copying large files to +slow destinations like network sockets. +.RS +.PP +The \fBchan copy\fP command transfers data from \fIinputChan\fR until +end of file or \fIsize\fP bytes have been transferred. If no +\fB\-size\fP argument is given, then the copy goes until end of file. +All the data read from \fIinputChan\fR is copied to \fIoutputChan\fR. +Without the \fB\-command\fP option, \fBchan copy\fP blocks until the +copy is complete and returns the number of bytes written to +\fIoutputChan\fR. +.PP +The \fB\-command\fP argument makes \fBchan copy\fP work in the +background. In this case it returns immediately and the +\fIcallback\fP is invoked later when the copy completes. The +\fIcallback\fP is called with one or two additional arguments that +indicates how many bytes were written to \fIoutputChan\fR. If an +error occurred during the background copy, the second argument is the +error string associated with the error. With a background copy, it is +not necessary to put \fIinputChan\fR or \fIoutputChan\fR into +non-blocking mode; the \fBchan copy\fP command takes care of that +automatically. However, it is necessary to enter the event loop by +using the \fBvwait\fP command or by using Tk. +.PP +You are not allowed to do other I/O operations with \fIinputChan\fR or +\fIoutputChan\fR during a background \fBchan copy\fR. If either +\fIinputChan\fR or \fIoutputChan\fR get closed while the copy is in +progress, the current copy is stopped and the command callback is +\fInot\fP made. If \fIinputChan\fR is closed, then all data already +queued for \fIoutputChan\fR is written out. +.PP +Note that \fIinputChan\fR can become readable during a background +copy. You should turn off any \fBchan event\fP or \fBfileevent\fR +handlers during a background copy so those handlers do not interfere +with the copy. Any I/O attempted by a \fBchan event\fR or +\fBfileevent\fP handler will get a "channel busy" error. +.PP +\fBChan copy\fR translates end-of-line sequences in \fIinputChan\fR +and \fIoutputChan\fR according to the \fB\-translation\fR option for +these channels (see \fBchan configure\fR above). The translations +mean that the number of bytes read from \fIinputChan\fR can be +different than the number of bytes written to \fIoutputChan\fR. Only +the number of bytes written to \fIoutputChan\fR is reported, either as +the return value of a synchronous \fBchan copy\fP or as the argument +to the callback for an asynchronous \fBchan copy\fP. +.PP +\fBChan copy\fR obeys the encodings and character translations +configured for the channels. This means that the incoming characters +are converted internally first UTF-8 and then into the encoding of the +channel \fBchan copy\fR writes to (see \fBchan configure\fR above for +details on the \fB\-encoding\fR and \fB\-translation\fR options). No +conversion is done if both channels are set to encoding \fBbinary\fR +and have matching translations. If only the output channel is set to +encoding \fBbinary\fR the system will write the internal UTF-8 +representation of the incoming characters. If only the input channel +is set to encoding \fBbinary\fR the system will assume that the +incoming bytes are valid UTF-8 characters and convert them according +to the output encoding. The behaviour of the system for bytes which +are not valid UTF-8 characters is undefined in this case. +.RE +.TP +\fBchan eof \fIchannelId\fR +. +Test whether the last input operation on the channel called +\fIchannelId\fR failed because the end of the data stream was reached, +returning 1 if end-fo-file was reached, and 0 otherwise. +.TP +\fBchan event \fIchannelId event\fR ?\fIscript\fR? +. +Arrange for the Tcl script \fIscript\fR to be installed as a \fIfile +event handler\fR to be called whenever the channel called +\fIchannelId\fR enters the state described by \fIevent\fR (which must +be either \fBreadable\fR or \fBwritable\fR); only one such handler may +be installed per event per channel at a time. If \fIscript\fR is the +empty string, the current handler is deleted (this also happens if the +channel is closed or the interpreter deleted). If \fIscript\fR is +omitted, the currently installed script is returned (or an empty +string if no such handler is installed). The callback is only +performed if the event loop is being serviced (e.g. via \fBvwait\fR or +\fBupdate\fR). +.RS +.PP +A file event handler is a binding between a channel and a script, such +that the script is evaluated whenever the channel becomes readable or +writable. File event handlers are most commonly used to allow data to +be received from another process on an event-driven basis, so that the +receiver can continue to interact with the user or with other channels +while waiting for the data to arrive. If an application invokes +\fBchan gets\fR or \fBchan read\fR on a blocking channel when there is +no input data available, the process will block; until the input data +arrives, it will not be able to service other events, so it will +appear to the user to ``freeze up''. With \fBchan event\fR, the +process can tell when data is present and only invoke \fBchan gets\fR +or \fBchan read\fR when they won't block. +.PP +A channel is considered to be readable if there is unread data +available on the underlying device. A channel is also considered to +be readable if there is unread data in an input buffer, except in the +special case where the most recent attempt to read from the channel +was a \fBchan gets\fR call that could not find a complete line in the +input buffer. This feature allows a file to be read a line at a time +in nonblocking mode using events. A channel is also considered to be +readable if an end of file or error condition is present on the +underlying file or device. It is important for \fIscript\fR to check +for these conditions and handle them appropriately; for example, if +there is no special check for end of file, an infinite loop may occur +where \fIscript\fR reads no data, returns, and is immediately invoked +again. +.PP +A channel is considered to be writable if at least one byte of data +can be written to the underlying file or device without blocking, or +if an error condition is present on the underlying file or device. +Note that client sockets opened in asynchronous mode become writable +when they become connected or if the connection fails. +.PP +Event-driven I/O works best for channels that have been placed into +nonblocking 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 +gets\fR never block. +.PP +The script for a file event is executed at global level (outside the +context of any Tcl procedure) in the interpreter in which the \fBchan +event\fR command was invoked. If an error occurs while executing the +script then the command registered with \fBinterp bgerror\fR is used +to report the error. In addition, the file event handler is deleted +if it ever returns an error; this is done in order to prevent infinite +loops due to buggy handlers. +.RE +.TP +\fBchan flush \fIchannelId\fR +. +Ensures that all pending output for the channel called \fIchannelId\fR +is written. +.RS +.PP +If the channel is in blocking mode the command does not return until +all the buffered output has been flushed to the channel. If the +channel is in nonblocking 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. +.RE +.TP +\fBchan gets \fIchannelId\fR ?\fIvarName\fR? +. +Reads the next line from the channel called \fIchannelId\fR. If +\fIvarName\fR is not specified, the result of the command will be the +line that has been read (without a trailing newline character) or an +empty string upon end-of-file or, in non-blocking mode, if the data +available is exhausted. If \fIvarName\fR is specified, the line that +has been read will be written to the variable called \fIvarName\fR and +result will be the number of characters that have been read or -1 if +end-of-file was reached or, in non-blocking mode, if the data +available is exhausted. +.RS +.PP +If an end-of-file occurs while part way through reading a line, the +partial line will be returned (or written into \fIvarName\fR). When +\fIvarName\fR is not specified, the end-of-file case can be +distinguished from an empty line using the \fBchan eof\fR command, and +the partial-line-but-nonblocking case can be distinguished with the +\fBchan blocked\fR command. +.RE +.TP +\fBchan names\fR ?\fIpattern\fR? +. +Produces a list of all channel names. If \fIpattern\fR is specified, +only those channel names that match it (according to the rules of +\fBstring match\fR) will be returned. +.TP +\fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR +. +Writes \fIstring\fR to the channel named \fIchannelId\fR followed by a +newline character. A trailing newline character is written unless the +optional flag \fB\-nonewline\fR is given. If \fIchannelId\fR is +omitted, the string is written to the standard output channel, +\fBstdout\fR. +.RS +.PP +Newline characters in the output are translated by \fBchan puts\fR to +platform-specific end-of-line sequences according to the currently +configured value of the \fB\-translation\fR option for the channel +(for example, on PCs newlines are normally replaced with +carriage-return-linefeed sequences; see \fBchan configure\fR above for +details). +.PP +Tcl buffers output internally, so characters written with \fBchan +puts\fR may not appear immediately on the output file or device; Tcl +will normally delay output until the buffer is full or the channel is +closed. You can force output to appear immediately with the \fBchan +flush\fR command. +.PP +When the output buffer fills up, the \fBchan puts\fR command will +normally block until all the buffered data has been accepted for +output by the operating system. If \fIchannelId\fR is in nonblocking +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 +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 +used in an event-driven fashion with the \fBchan event\fR command +(don't invoke \fBchan puts\fR unless you have recently been notified +via a file event that the channel is ready for more output data). +.RE +.TP +\fBchan read \fIchannelId\fR ?\fInumChars\fR? +.TP +\fBchan read \fR?\fB\-nonewline\fR? \fIchannelId\fR +. +In the first form, the result will be the next \fInumChars\fR +characters read from the channel named \fIchannelId\fR; if +\fInumChars\fR is omitted, all characters up to the point when the +channel would signal a failure (whether an end-of-file, blocked or +other error condition) are read. In the second form (i.e. when +\fInumChars\fR has been omitted) the flag \fB\-nonewline\fR may be +given to indicate that any trailing newline in the string that has +been read should be trimmed. +.RS +.PP +If \fIchannelId\fR is in nonblocking mode, \fBchan read\fR may not +read as many characters as requested: once all available input has +been read, the command will return the data that is available rather +than blocking for more input. If the channel is configured to use a +multi-byte encoding, then there may actually be some bytes remaining +in the internal buffers that do not form a complete character. These +bytes will not be returned until a complete character is available or +end-of-file is reached. The \fB\-nonewline\fR switch is ignored if +the command returns before reaching the end of the file. +.PP +\fBChan read\fR translates end-of-line sequences in the input into +newline characters according to the \fB\-translation\fR option for the +channel (see \fBchan configure\fR above for a discussion on the ways +in which \fBchan configure\fR will alter input). +.PP +When reading from a serial port, most applications should configure +the serial port channel to be nonblocking, like this: +.CS +\fBchan configure \fIchannelId \fB\-blocking \fI0\fR. +.CE +Then \fBchan read\fR behaves much like described above. Note that +most serial ports are comparatively slow; it is entirely possible to +get a \fBreadable\fR event for each character read from them. Care +must be taken when using \fBchan read\fR on blocking serial ports: +.TP +\fBchan read \fIchannelId numChars\fR +. +In this form \fBchan read\fR blocks until \fInumChars\fR have been +received from the serial port. +.TP +\fBchan read \fIchannelId\fR +. +In this form \fBchan read\fR blocks until the reception of the +end-of-file character, see \fBchan configure -eofchar\fR. If there no +end-of-file character has been configured for the channel, then +\fBchan read\fR will block forever. +.RE +.TP +\fBchan seek \fIchannelId offset\fR ?\fIorigin\fR? +. +Sets the current access position within the underlying data stream for +the channel named \fIchannelId\fR to be \fIoffset\fR bytes relative to +\fIorigin\fR. \fIOffset\fR must be an integer (which may be negative) +and \fIorigin\fR must be one of the following: +.RS +.TP 10 +\fBstart\fR +. +The new access position will be \fIoffset\fR bytes from the start +of the underlying file or device. +.TP 10 +\fBcurrent\fR +. +The new access position will be \fIoffset\fR bytes from the current +access position; a negative \fIoffset\fR moves the access position +backwards in the underlying file or device. +.TP 10 +\fBend\fR +. +The new access position will be \fIoffset\fR bytes from the end of the +file or device. A negative \fIoffset\fR places the access position +before the end of file, and a positive \fIoffset\fR places the access +position after the end of file. +.PP +The \fIorigin\fR argument defaults to \fBstart\fR. +.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 +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. +.PP +Note that \fIoffset\fR values are byte offsets, not character offsets. +Both \fBchan seek\fR and \fBchan tell\fR operate in terms of bytes, +not characters, unlike \fBchan read\fR. +.RE +.TP +\fBchan tell \fIchannelId\fR +. +Returns a number giving the current access position within the +underlying data stream for the channel named \fIchannelId\fR. This +value returned is a byte offset that can be passed to \fBchan seek\fR +in order to set the channel to a particular position. Note that this +value is in terms of bytes, not characters like \fBchan read\fR. The +value returned is -1 for channels that do not support seeking. +.TP +\fBchan truncate \fIchannelId\fR ?\fIlength\fR? +. +Sets the byte length of the underlying data stream for the channel +named \fIchannelId\fR to be \fIlength\fR (or to the current byte +offset within the underlying data stream if \fIlength\fR is +omitted). The channel is flushed before truncation. + +.SH "SEE ALSO" +close(n), eof(n), fblocked(n), fconfigure(n), fcopy(n), file(n), +fileevent(n), flush(n), gets(n), open(n), puts(n), read(n), seek(n), +socket(n), tell(n) + +.SH KEYWORDS +channel, input, output, events, offset @@ -1,12 +1,12 @@ '\" '\" Copyright (c) 1993 The Regents of the University of California. '\" Copyright (c) 1994-2000 Sun Microsystems, Inc. -.\" Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved +'\" Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved '\" '\" 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.18.2.1 2005/04/20 19:47:16 kennykb Exp $ +'\" RCS: @(#) $Id: expr.n,v 1.18.2.2 2005/07/12 20:36:15 kennykb Exp $ '\" .so man.macros .TH expr n 8.5 Tcl "Tcl Built-In Commands" @@ -212,6 +212,7 @@ the Tcl parser will evaluate both \fB[a]\fR and \fB[b]\fR before invoking the \fBexpr\fR command. .SS "MATH FUNCTIONS" .PP +.VS 8.5 When the expression parser encounters a mathematical function such as \fBsin($x)\fR, it replaces it with a call to an ordinary Tcl function in the \fBtcl::mathfunc\fR namespace. The processing @@ -221,15 +222,17 @@ of an expression such as: .CE is the same in every way as the processing of: .CS -\fBexpr {[tcl::mathfunc::sin [expr {$x+$y}]]} +\fBexpr {[tcl::mathfunc::sin [expr {$x+$y}]]}\fR .CE -The executor will search for \fBtcl::mathfunc::sin\fR using the -usual rules for resolving functions in namespaces. Either -\fB::tcl::mathfunc::sin\fR or \fB[namespace current]::tcl::mathfunc::sin\fR -will satisfy the request. +The executor will search for \fBtcl::mathfunc::sin\fR using the usual +rules for resolving functions in namespaces. Either +\fB::tcl::mathfunc::sin\fR or \fB[namespace +current]::tcl::mathfunc::sin\fR will satisfy the request, and others +may as well (depending on the current \fBnamespace path\fR setting). .PP -See the \fBmathfunc(n)\fR manual page for the math functions that are +See the \fBmathfunc\fR(n) manual page for the math functions that are available by default. +.VE 8.5 .SS "TYPES, OVERFLOW, AND PRECISION" .PP All internal computations involving integers are done with the C type @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: glob.n,v 1.17 2004/10/27 12:53:22 dkf Exp $ +'\" RCS: @(#) $Id: glob.n,v 1.17.2.1 2005/07/12 20:36:15 kennykb Exp $ '\" .so man.macros .TH glob n 8.3 Tcl "Tcl Built-In Commands" @@ -21,7 +21,9 @@ glob \- Return names of files that match patterns .PP This command performs file name ``globbing'' in a fashion similar to the csh shell. It returns a list of the files whose names match any -of the \fIpattern\fR arguments. +of the \fIpattern\fR arguments. No particular order is guaranteed +in the list, so if a sorted list is required the caller should use +\fBlsort\fR. .LP If the initial arguments to \fBglob\fR start with \fB\-\fR then they are treated as switches. The following switches are @@ -157,11 +159,6 @@ be used with \fBfile join\fR, to avoid them being interpreted as absolute paths pointing to a given user's home directory. .SH "PORTABILITY ISSUES" .PP -Unlike other Tcl commands that will accept both network and native -style names (see the \fBfilename\fR manual entry for details on how -native and network names are specified), the \fBglob\fR command only -accepts native names. -.TP \fBWindows\fR . For Windows UNC names, the servername and sharename components of the path @@ -7,7 +7,7 @@ '\" 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.14.2.1 2005/04/10 23:14:43 kennykb Exp $ +'\" RCS: @(#) $Id: info.n,v 1.14.2.2 2005/07/12 20:36:15 kennykb Exp $ '\" .so man.macros .TH info n 8.4 Tcl "Tcl Built-In Commands" @@ -40,7 +40,10 @@ in this interpreter. .TP \fBinfo commands \fR?\fIpattern\fR? If \fIpattern\fR isn't specified, -returns a list of names of all the Tcl commands in the current namespace, +'\" Do not move this .VS above the .TP +.VS 8.5 +returns a list of names of all the Tcl commands visible +(i.e. executable without using a qualified name) to the current namespace, including both the built-in commands written in C and the command procedures defined using the \fBproc\fR command. If \fIpattern\fR is specified, @@ -53,7 +56,11 @@ and may have pattern matching special characters at the end to specify a set of commands in that namespace. If \fIpattern\fR is a qualified name, the resulting list of command names has each one qualified with the name -of the specified namespace. +of the specified namespace, and only the commands defined in the named +namespace are returned. +'\" Technically, most of this hasn't changed; that's mostly just the +'\" way it always worked. Hardly anyone knew that though. +.VE 8.5 .TP \fBinfo complete \fIcommand\fR Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of diff --git a/doc/lsearch.n b/doc/lsearch.n index 4fd2c0a..a51a78a 100644 --- a/doc/lsearch.n +++ b/doc/lsearch.n @@ -7,7 +7,7 @@ '\" 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.21.2.2 2005/05/05 17:55:25 kennykb Exp $ +'\" RCS: @(#) $Id: lsearch.n,v 1.21.2.3 2005/07/12 20:36:15 kennykb Exp $ '\" .so man.macros .TH lsearch n 8.5 Tcl "Tcl Built-In Commands" @@ -34,7 +34,8 @@ is \fB\-glob\fR. If more than one matching style is specified, the last matching style given takes precedence. .TP \fB\-exact\fR -The list element must contain exactly the same string as \fIpattern\fR. +\fIPattern\fR is a literal string that is compared for exact equality +against each list element. .TP \fB\-glob\fR \fIPattern\fR is a glob-style pattern which is matched against each list @@ -95,6 +96,13 @@ dictionary-equal when exactly equal. .TP \fB\-integer\fR The list elements are to be compared as integers. +.VS 8.5 +.TP +\fB\-nocase\fR +Causes comparisons to be handled in a case-insensitive manner. Has no +effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or +\fB\-real\fR options. +.VE 8.5 .TP \fB\-real\fR The list elements are to be compared as floating-point values. diff --git a/doc/lsort.n b/doc/lsort.n index 27bf90c..ecb47a2 100644 --- a/doc/lsort.n +++ b/doc/lsort.n @@ -7,10 +7,10 @@ '\" 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.18.2.1 2005/05/05 17:55:27 kennykb Exp $ +'\" RCS: @(#) $Id: lsort.n,v 1.18.2.2 2005/07/12 20:36:16 kennykb Exp $ '\" .so man.macros -.TH lsort n 8.3 Tcl "Tcl Built-In Commands" +.TH lsort n 8.5 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -104,6 +104,13 @@ returns \fB{{d e m o} 34512} {{b i g} 12345} {{c o d e} 54321}\fR This option is much more efficient than using \fB\-command\fR to achieve the same effect. .RE +.VS 8.5 +.TP 20 +\fB\-nocase\fR +Causes comparisons to be handled in a case-insensitive manner. Has no +effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or +\fB\-real\fR options. +.VE 8.5 .TP 20 \fB\-unique\fR If this option is specified, then only the last set of duplicate diff --git a/doc/mathfunc.n b/doc/mathfunc.n index d3a4804..9910f03 100644 --- a/doc/mathfunc.n +++ b/doc/mathfunc.n @@ -1,4 +1,4 @@ -.\" +'\" '\" Copyright (c) 1993 The Regents of the University of California. '\" Copyright (c) 1994-2000 Sun Microsystems, Inc. '\" Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved @@ -6,7 +6,7 @@ '\" 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.1.2.2 2005/05/21 15:10:25 kennykb Exp $ +'\" RCS: @(#) $Id: mathfunc.n,v 1.1.2.3 2005/07/12 20:36:16 kennykb Exp $ '\" .so man.macros .TH mathfunc n 8.5 Tcl "Tcl Mathematical Functions" @@ -27,6 +27,8 @@ package require \fBTcl 8.5\fR .br \fB::tcl::mathfunc::atan2\fR \fIy\fR \fIx\fR .br +\fB::tcl::mathfunc::bool\fR \fIarg\fR +.br \fB::tcl::mathfunc::ceil\fR \fIarg\fR .br \fB::tcl::mathfunc::cos\fR \fIarg\fR @@ -85,13 +87,13 @@ Tcl supports the following mathematical functions in expressions, all of which work solely with floating-point numbers unless otherwise noted: .DS .ta 3c 6c 9c -\fBabs\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR -\fBacos\fR \fBdouble\fR \fBlog10\fR \fBsrand\fR -\fBasin\fR \fBexp\fR \fBpow\fR \fBtan\fR -\fBatan\fR \fBfloor\fR \fBrand\fR \fBtanh\fR -\fBatan2\fR \fBfmod\fR \fBround\fR \fBwide\fR +\fBabs\fR \fBcos\fR \fBint\fR \fBsinh\fR +\fBacos\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR +\fBasin\fR \fBdouble\fR \fBlog10\fR \fBsrand\fR +\fBatan\fR \fBexp\fR \fBpow\fR \fBtan\fR +\fBatan2\fR \fBfloor\fR \fBrand\fR \fBtanh\fR +\fBbool\fR \fBfmod\fR \fBround\fR \fBwide\fR \fBceil\fR \fBhypot\fR \fBsin\fR -\fBcos\fR \fBint\fR \fBsinh\fR .DE .PP .TP @@ -116,6 +118,13 @@ Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI-pi\fR,\fIpi\fR] radians. \fIx\fR and \fIy\fR cannot both be 0. If \fIx\fR is greater than \fI0\fR, this is equivalent to \fBatan(\fIy/x\fB)\fR. .TP +\fBbool(\fIarg\fB)\fR +Accepts any numerical value, or any string acceptable to +\fBstring is boolean\fR, and returns the corresponding +boolean value \fB0\fR or \fB1\fR. Non-zero numbers are true. +Other numbers are false. Non-numeric strings produce boolean value in +agreement with \fBstring is true\fR and \fBstring is false\fR. +.TP \fBceil(\fIarg\fB)\fR Returns the smallest integral floating-point value (i.e. with a zero fractional part) not less than \fIarg\fR. @@ -218,4 +227,4 @@ Copyright (c) 1993 The Regents of the University of California. .br Copyright (c) 1994-2000 Sun Microsystems Incorporated. .br -Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
\ No newline at end of file +Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. diff --git a/doc/namespace.n b/doc/namespace.n index 1799a2f..e7e28c1 100644 --- a/doc/namespace.n +++ b/doc/namespace.n @@ -2,11 +2,12 @@ '\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies '\" Copyright (c) 1997 Sun Microsystems, Inc. '\" Copyright (c) 2000 Scriptics Corporation. +'\" Copyright (c) 2004-2005 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: namespace.n,v 1.16.2.1 2005/05/21 15:10:25 kennykb Exp $ +'\" RCS: @(#) $Id: namespace.n,v 1.16.2.2 2005/07/12 20:36:16 kennykb Exp $ '\" .so man.macros .TH namespace n 8.5 Tcl "Tcl Built-In Commands" @@ -216,6 +217,17 @@ for namespace \fInamespace\fR. If \fInamespace\fR is not specified, the fully-qualified name of the current namespace's parent is returned. .TP +\fBnamespace path\fR ?\fInamespaceList\fR? +'\" Should really have the .TP inside the .VS, but that triggers a groff bug +.VS 8.5 +Returns the command resolution path of the current namespace. If +\fInamespaceList\fR is specified as a list of named namespaces, the +current namespace's command resolution path is set to those namespaces +and returns the empty list. The default command resolution path is +always empty. See the section \fBNAME RESOLUTION\fR below for an +explanation of the rules regarding name resolution. +.VE 8.5 +.TP \fBnamespace qualifiers\fR \fIstring\fR Returns any leading namespace qualifiers for \fIstring\fR. Qualifiers are namespace names separated by double colons (\fB::\fR). @@ -387,10 +399,18 @@ there is no question about what command, variable, or namespace you mean. However, if the name does not start with a \fB::\fR (i.e., is \fIrelative\fR), -Tcl follows a fixed rule for looking it up: -Command and variable names are always resolved +Tcl follows basic rules for looking it up: +Variable names are always resolved by looking first in the current namespace, and then in the global namespace. +.VS 8.5 +Command names are also always resolved by looking in the current +namespace first. If not found there, they are searched for in every +namespace on the current namespace's command path (which is empty by +default). If not found there, command names are looked up in the +global namespace (or, failing that, are processed by the \fBunknown\fR +command.) +.VE 8.5 Namespace names, on the other hand, are always resolved by looking in only the current namespace. .PP @@ -764,10 +784,16 @@ Create a namespace containing a variable and an exported command: Call the command defined in the previous example in various ways. .CS # Direct call -foo::grill +::foo::grill + +# Use the command resolution path to find the name +\fBnamespace eval\fR boo { + \fBnamespace path\fR ::foo + grill +} # Import into current namespace, then call local alias -namespace import foo::grill +\fBnamespace import\fR foo::grill grill # Create two ensembles, one with the default name and one with a diff --git a/doc/string.n b/doc/string.n index 64013dc..1bc2655 100644 --- a/doc/string.n +++ b/doc/string.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: string.n,v 1.24.2.3 2005/05/05 17:55:28 kennykb Exp $ +'\" RCS: @(#) $Id: string.n,v 1.24.2.4 2005/07/12 20:36:16 kennykb Exp $ '\" .so man.macros .TH string n 8.1 Tcl "Tcl Built-In Commands" @@ -81,16 +81,16 @@ the char specified at this integral index .IP \fBend\fR 10 The last char of the string (e.g. \fBend\fR would refer to the "d" in "abcd"). -.IP \fBend\-\fIN\fR 10 +.IP \fBend\fR\-\fIN\fR 10 The last char of the string minus the specified integer offset \fIN\fR -(e.g. \fBend\-1\fR would refer to the "c" in "abcd"). -.IP \fBend\+\fIN\fR 10 +(e.g. \fBend\fR\-1 would refer to the "c" in "abcd"). +.IP \fBend\fR+\fIN\fR 10 The last char of the string plus the specified integer offset \fIN\fR -(e.g. \fBend\+\-1\fR would refer to the "c" in "abcd"). -.IP \fIM\fR\+\fIN\fR 10 +(e.g. \fBend\fR+\-1 would refer to the "c" in "abcd"). +.IP \fIM\fR+\fIN\fR 10 The char specified at the integral index that is the sum of integer values \fIM\fR and \fIN\fR -(e.g. \fB1\+1\fR would refer to the "c" in "abcd"). +(e.g. \fB1+1\fR would refer to the "c" in "abcd"). .IP \fIM\fR\-\fIN\fR 10 The char specified at the integral index that is the difference of integer values \fIM\fR and \fIN\fR diff --git a/doc/switch.n b/doc/switch.n index c508262..a19b30c 100644 --- a/doc/switch.n +++ b/doc/switch.n @@ -5,10 +5,10 @@ '\" 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.8 2004/10/27 14:24:37 dkf Exp $ +'\" RCS: @(#) $Id: switch.n,v 1.8.2.1 2005/07/12 20:36:16 kennykb Exp $ '\" .so man.macros -.TH switch n 7.0 Tcl "Tcl Built-In Commands" +.TH switch n 8.5 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -51,6 +51,9 @@ expression matching '\" Options defined by TIP#75 .VS 8.5 .TP 10 +\fB\-nocase\fR +Causes comparisons to be handled in a case-insensitive manner. +.TP 10 \fB\-matchvar\fR \fIvarName\fR This option (only legal when \fB\-regexp\fR is also specified) specifies the name of a variable into which the list of matches |