diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/AddErrInfo.3 | 2 | ||||
| -rw-r--r-- | doc/CrtChannel.3 | 2 | ||||
| -rw-r--r-- | doc/DString.3 | 2 | ||||
| -rw-r--r-- | doc/Encoding.3 | 114 | ||||
| -rw-r--r-- | doc/Method.3 | 4 | ||||
| -rw-r--r-- | doc/Object.3 | 4 | ||||
| -rw-r--r-- | doc/OpenFileChnl.3 | 26 | ||||
| -rw-r--r-- | doc/ParseCmd.3 | 18 | ||||
| -rw-r--r-- | doc/StringObj.3 | 13 | ||||
| -rw-r--r-- | doc/Tcl.n | 41 | ||||
| -rw-r--r-- | doc/Thread.3 | 11 | ||||
| -rw-r--r-- | doc/ToUpper.3 | 2 | ||||
| -rw-r--r-- | doc/TraceCmd.3 | 35 | ||||
| -rw-r--r-- | doc/Utf.3 | 16 | ||||
| -rw-r--r-- | doc/clock.n | 5 | ||||
| -rw-r--r-- | doc/dict.n | 26 | ||||
| -rw-r--r-- | doc/encoding.n | 34 | ||||
| -rw-r--r-- | doc/exec.n | 67 | ||||
| -rw-r--r-- | doc/exit.n | 2 | ||||
| -rw-r--r-- | doc/fcopy.n | 27 | ||||
| -rw-r--r-- | doc/file.n | 8 | ||||
| -rw-r--r-- | doc/glob.n | 8 | ||||
| -rw-r--r-- | doc/http.n | 3 | ||||
| -rw-r--r-- | doc/library.n | 20 | ||||
| -rw-r--r-- | doc/lreplace.n | 2 | ||||
| -rw-r--r-- | doc/msgcat.n | 304 | ||||
| -rw-r--r-- | doc/my.n | 2 | ||||
| -rw-r--r-- | doc/next.n | 12 | ||||
| -rw-r--r-- | doc/open.n | 61 | ||||
| -rw-r--r-- | doc/re_syntax.n | 26 | ||||
| -rw-r--r-- | doc/regexp.n | 2 | ||||
| -rw-r--r-- | doc/socket.n | 8 | ||||
| -rw-r--r-- | doc/source.n | 2 | ||||
| -rw-r--r-- | doc/string.n | 48 | ||||
| -rw-r--r-- | doc/tcltest.n | 8 | ||||
| -rw-r--r-- | doc/tclvars.n | 15 |
36 files changed, 605 insertions, 375 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index d4bf7d5..e6563a0 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -4,7 +4,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures" .so man.macros .BS diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index 1c5c665..2335de1 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -336,7 +336,7 @@ typedef struct Tcl_ChannelType { It is not necessary to provide implementations for all channel operations. Those which are not necessary may be set to NULL in the struct: \fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, -\fIgetOptionProc\fR, and \fIclose2Proc\fR, in addition to +\fIgetOptionProc\fR, \fIgetHandleProc\fR, and \fIclose2Proc\fR, in addition to \fIflushProc\fR, \fIhandlerProc\fR, \fIthreadActionProc\fR, and \fItruncateProc\fR. Other functions that cannot be implemented in a meaningful way should return \fBEINVAL\fR when called, to indicate diff --git a/doc/DString.3 b/doc/DString.3 index 0e571d2..00f1b8a 100644 --- a/doc/DString.3 +++ b/doc/DString.3 @@ -4,7 +4,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures" .so man.macros .BS diff --git a/doc/Encoding.3 b/doc/Encoding.3 index 1478c35..81ef508 100644 --- a/doc/Encoding.3 +++ b/doc/Encoding.3 @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures" .so man.macros .BS @@ -76,7 +76,7 @@ desired. .AP "const char" *name in Name of encoding to load. .AP Tcl_Encoding encoding in -The encoding to query, free, or use for converting text. If \fIencoding\fR is +The encoding to query, free, or use for converting text. If \fIencoding\fR is NULL, the current system encoding is used. .AP Tcl_Obj *objPtr in Name of encoding to get token for. @@ -86,17 +86,17 @@ Points to storage where encoding token is to be written. For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the specified encoding that are to be converted to UTF-8. For the \fBTcl_UtfToExternal\fR and \fBTcl_WinUtfToTChar\fR functions, an array of -UTF-8 characters to be converted to the specified encoding. +UTF-8 characters to be converted to the specified encoding. .AP "const TCHAR" *tsrc in An array of Windows TCHAR characters to convert to UTF-8. -.AP int srcLen in -Length of \fIsrc\fR or \fItsrc\fR in bytes. If the length is negative, the +.AP int srcLen in +Length of \fIsrc\fR or \fItsrc\fR in bytes. If the length is negative, the encoding-specific length of the string is used. .AP Tcl_DString *dstPtr out Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted result will be stored. .AP int flags in -Various flag bits OR-ed together. +Various flag bits OR-ed together. \fBTCL_ENCODING_START\fR signifies that the source buffer is the first block in a (potentially multi-block) input stream, telling the conversion routine to reset to an initial state and @@ -108,7 +108,7 @@ byte is converted and then to reset to an initial state. \fBTCL_ENCODING_STOPONERROR\fR signifies that the conversion routine should return immediately upon reading a source character that does not exist in the target encoding; otherwise a default fallback character will -automatically be substituted. +automatically be substituted. .AP Tcl_EncodingState *statePtr in/out Used when converting a (generally long or indefinite length) byte stream in a piece-by-piece fashion. The conversion routine stores its current @@ -116,7 +116,7 @@ state in \fI*statePtr\fR after \fIsrc\fR (the buffer containing the current piece) has been converted; that state information must be passed back when converting the next piece of the stream so the conversion routine knows what state it was in when it left off at the end of the -last piece. May be NULL, in which case the value specified for \fIflags\fR +last piece. May be NULL, in which case the value specified for \fIflags\fR is ignored and the source buffer is assumed to contain the complete string to convert. .AP char *dst out @@ -137,11 +137,11 @@ stored in the output buffer. May be NULL. .AP Tcl_DString *bufPtr out Storage for the prescribed system encoding name. .AP "const Tcl_EncodingType" *typePtr in -Structure that defines a new type of encoding. +Structure that defines a new type of encoding. .AP Tcl_Obj *searchPath in List of filesystem directories in which to search for encoding data files. .AP "const char" *path in -A path to the location of the encoding file. +A path to the location of the encoding file. .BE .SH INTRODUCTION .PP @@ -180,13 +180,13 @@ The first time \fIname\fR is seen, \fBTcl_GetEncoding\fR returns an encoding with a reference count of 1. If the same \fIname\fR is requested further times, then the reference count for that encoding is incremented without the overhead of allocating a new encoding and all its associated -data structures. +data structures. .PP When an \fIencoding\fR is no longer needed, \fBTcl_FreeEncoding\fR should be called to release it. When an \fIencoding\fR is no longer in use anywhere (i.e., it has been freed as many times as it has been gotten) \fBTcl_FreeEncoding\fR will release all storage the encoding was using -and delete it from the database. +and delete it from the database. .PP \fBTcl_GetEncodingFromObj\fR treats the string representation of \fIobjPtr\fR as an encoding name, and finds an encoding with that @@ -201,7 +201,7 @@ on the resulting encoding token when that token will no longer be used. .PP \fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the -specified \fIencoding\fR into UTF-8. The converted bytes are stored in +specified \fIencoding\fR into UTF-8. The converted bytes are stored in \fIdstPtr\fR, which is then null-terminated. The caller should eventually call \fBTcl_DStringFree\fR to free any information stored in \fIdstPtr\fR. When converting, if any of the characters in the source buffer cannot be @@ -227,17 +227,17 @@ sequence, but more bytes were needed to complete this sequence. A subsequent call to the conversion routine should pass a buffer containing the unconverted bytes that remained in \fIsrc\fR plus some further bytes from the source stream to properly convert the formerly split-up multibyte -sequence. +sequence. .IP \fBTCL_CONVERT_SYNTAX\fR 29 The source buffer contained an invalid character sequence. This may occur if the input stream has been damaged or if the input encoding method was misidentified. .IP \fBTCL_CONVERT_UNKNOWN\fR 29 The source buffer contained a character that could not be represented in -the target encoding and \fBTCL_ENCODING_STOPONERROR\fR was specified. +the target encoding and \fBTCL_ENCODING_STOPONERROR\fR was specified. .RE .LP -\fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8 +\fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8 into the specified \fIencoding\fR. The converted bytes are stored in \fIdstPtr\fR, which is then terminated with the appropriate encoding-specific null. The caller should eventually call \fBTcl_DStringFree\fR to free any @@ -257,51 +257,17 @@ is filled with the corresponding number of bytes that were stored in .PP \fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are Windows-only convenience -functions for converting between UTF-8 and Windows strings. On Windows 95 -(as with the Unix operating system), -all strings exchanged between Tcl and the operating system are -.QW "char" -based. On Windows NT, some strings exchanged between Tcl and the -operating system are -.QW "char" -oriented while others are in Unicode. By -convention, in Windows a TCHAR is a character in the ANSI code page -on Windows 95 and a Unicode character on Windows NT. -.PP -If you planned to use the same -.QW "char" -based interfaces on both Windows -95 and Windows NT, you could use \fBTcl_UtfToExternal\fR and -\fBTcl_ExternalToUtf\fR (or their \fBTcl_DString\fR equivalents) with an -encoding of NULL (the current system encoding). On the other hand, -if you planned to use the Unicode interface when running on Windows NT -and the -.QW "char" -interfaces when running on Windows 95, you would have -to perform the following type of test over and over in your program -(as represented in pseudo-code): -.PP -.CS -if (running NT) { - encoding <- Tcl_GetEncoding("unicode"); - nativeBuffer <- Tcl_UtfToExternal(encoding, utfBuffer); - Tcl_FreeEncoding(encoding); -} else { - nativeBuffer <- Tcl_UtfToExternal(NULL, utfBuffer); -} -.CE -.PP -\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR automatically -handle this test and use the proper encoding based on the current -operating system. \fBTcl_WinUtfToTChar\fR returns a pointer to -a TCHAR string, and \fBTcl_WinTCharToUtf\fR expects a TCHAR string -pointer as the \fIsrc\fR string. Otherwise, these functions -behave identically to \fBTcl_UtfToExternalDString\fR and -\fBTcl_ExternalToUtfDString\fR. +functions for converting between UTF-8 and Windows strings +based on the TCHAR type which is by convention +a Unicode character on Windows NT. +These functions are essentially wrappers around +\fBTcl_UtfToExternalDString\fR and +\fBTcl_ExternalToUtfDString\fR that convert to and from the +Unicode encoding. .PP \fBTcl_GetEncodingName\fR is roughly the inverse of \fBTcl_GetEncoding\fR. Given an \fIencoding\fR, the return value is the \fIname\fR argument that -was used to create the encoding. The string returned by +was used to create the encoding. The string returned by \fBTcl_GetEncodingName\fR is only guaranteed to persist until the \fIencoding\fR is deleted. The caller must not modify this string. .PP @@ -340,9 +306,9 @@ reference count of 1. If an encoding with the specified \fIname\fR already exists, then its entry in the database is replaced with the new encoding; the token for the old encoding will remain valid and continue to behave as before, but users of the new token will now call the new -encoding procedures. +encoding procedures. .PP -The \fItypePtr\fR argument to \fBTcl_CreateEncoding\fR contains information +The \fItypePtr\fR argument to \fBTcl_CreateEncoding\fR contains information about the name of the encoding and the procedures that will be called to convert between this encoding and UTF-8. It is defined as follows: .PP @@ -354,7 +320,7 @@ typedef struct Tcl_EncodingType { Tcl_EncodingFreeProc *\fIfreeProc\fR; ClientData \fIclientData\fR; int \fInullSize\fR; -} \fBTcl_EncodingType\fR; +} \fBTcl_EncodingType\fR; .CE .PP The \fIencodingName\fR provides a string name for the encoding, by @@ -384,12 +350,12 @@ type \fBTcl_EncodingConvertProc\fR: .CS typedef int \fBTcl_EncodingConvertProc\fR( ClientData \fIclientData\fR, - const char *\fIsrc\fR, - int \fIsrcLen\fR, - int \fIflags\fR, + const char *\fIsrc\fR, + int \fIsrcLen\fR, + int \fIflags\fR, Tcl_EncodingState *\fIstatePtr\fR, - char *\fIdst\fR, - int \fIdstLen\fR, + char *\fIdst\fR, + int \fIdstLen\fR, int *\fIsrcReadPtr\fR, int *\fIdstWrotePtr\fR, int *\fIdstCharsPtr\fR); @@ -405,12 +371,12 @@ documented at the top, to \fBTcl_ExternalToUtf\fR or \fBTcl_UtfToExternal\fR, with the following exceptions. If the \fIsrcLen\fR argument to one of those high-level functions is negative, the value passed to the callback procedure will be the appropriate -encoding-specific string length of \fIsrc\fR. If any of the \fIsrcReadPtr\fR, +encoding-specific string length of \fIsrc\fR. If any of the \fIsrcReadPtr\fR, \fIdstWrotePtr\fR, or \fIdstCharsPtr\fR arguments to one of the high-level functions is NULL, the corresponding value passed to the callback procedure will be a non-NULL location. .PP -The callback procedure \fIfreeProc\fR, if non-NULL, should match the type +The callback procedure \fIfreeProc\fR, if non-NULL, should match the type \fBTcl_EncodingFreeProc\fR: .PP .CS @@ -420,11 +386,11 @@ typedef void \fBTcl_EncodingFreeProc\fR( .PP This \fIfreeProc\fR function is called when the encoding is deleted. The \fIclientData\fR parameter is the same as the \fIclientData\fR field -specified to \fBTcl_CreateEncoding\fR when the encoding was created. +specified to \fBTcl_CreateEncoding\fR when the encoding was created. .PP \fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR are called to access and set the list of filesystem directories searched -for encoding data files. +for encoding data files. .PP The value returned by \fBTcl_GetEncodingSearchPath\fR is the value stored by the last successful call to @@ -457,7 +423,7 @@ encoding files that can be loaded using the same mechanism. These encoding files contain information about the tables and/or escape sequences used to map between an external encoding and Unicode. The external encoding may consist of single-byte, multi-byte, or double-byte -characters. +characters. .PP Each dynamically-loadable encoding is represented as a text file. The initial line of the file, beginning with a @@ -481,9 +447,9 @@ many Japanese computers. .IP "[4] \fBE\fR" An escape-sequence encoding, specifying that certain sequences of bytes do not represent characters, but commands that describe how following bytes -should be interpreted. +should be interpreted. .PP -The rest of the lines in the file depend on the type. +The rest of the lines in the file depend on the type. .PP Cases [1], [2], and [3] are collectively referred to as table-based encoding files. The lines in a table-based encoding file are in the same @@ -534,7 +500,7 @@ The third line of the file is three numbers. The first number is the fallback character (in base 16) to use when converting from UTF-8 to this encoding. The second number is a \fB1\fR if this file represents the encoding for a symbol font, or \fB0\fR otherwise. The last number (in base -10) is how many pages of data follow. +10) is how many pages of data follow. .PP Subsequent lines in the example above are pages that describe how to map from the encoding into 2-byte Unicode. The first line in a page identifies diff --git a/doc/Method.3 b/doc/Method.3 index 550b64a..225da00 100644 --- a/doc/Method.3 +++ b/doc/Method.3 @@ -67,7 +67,9 @@ The class to create the method in. The name of the method to create. Should not be NULL unless creating constructors or destructors. .AP int isPublic in -A boolean flag saying whether the method is to be exported. +A flag saying what the visibility of the method is. The only supported public +values of this flag are 0 for a non-exported method, and 1 for an exported +method. .AP Tcl_MethodType *methodTypePtr in A description of the type of the method to create, or the type of method to compare against. diff --git a/doc/Object.3 b/doc/Object.3 index 55451ab..bf80fe2 100644 --- a/doc/Object.3 +++ b/doc/Object.3 @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures" .so man.macros .BS @@ -94,7 +94,7 @@ Also, most Tcl values are only read and never modified. This is especially true for procedure arguments, which can be shared between the caller and the called procedure. Assignment and argument binding is done by -simply assigning a pointer to the value. +simply assigning a pointer to the value. Reference counting is used to determine when it is safe to reclaim a value's storage. .PP diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index cca76c2..582ff4b 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -115,7 +115,7 @@ Used for error reporting and to look up a channel registered in it. The name of a local or network file. .AP "const char" *mode in Specifies how the file is to be accessed. May have any of the values -allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. +allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. .AP int permissions in POSIX-style permission flags such as 0644. If a new file is created, these permissions will be set on the created file. @@ -141,7 +141,7 @@ file descriptor, for Windows it is a HANDLE. OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate what operations are valid on \fIhandle\fR. .AP "const char" *channelName in -The name of the channel. +The name of the channel. .AP int *modePtr out Points at an integer variable that will receive an OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is @@ -155,8 +155,8 @@ from a procedure such as \fBTcl_OpenFileChannel\fR. A pointer to a Tcl value in which to store the characters read from the channel. .AP int charsToRead in -The number of characters to read from the channel. If the channel's encoding -is \fBbinary\fR, this is equivalent to the number of bytes to read from the +The number of characters to read from the channel. If the channel's encoding +is \fBbinary\fR, this is equivalent to the number of bytes to read from the channel. .AP int appendFlag in If non-zero, data read from the channel will be appended to the value. @@ -169,7 +169,7 @@ be large enough to hold this many bytes. .AP Tcl_Obj *lineObjPtr in/out A pointer to a Tcl value in which to store the line read from the channel. The line read will be appended to the current value of the -value. +value. .AP Tcl_DString *lineRead in/out A pointer to a Tcl dynamic string in which to store the line read from the channel. Must have been initialized by the caller. The line read will be @@ -238,8 +238,8 @@ If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR returns NULL and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR -leaves an error message in \fIinterp\fR's result after any error. -As of Tcl 8.4, the value-based API \fBTcl_FSOpenFileChannel\fR should +leaves an error message in \fIinterp\fR's result after any error. +As of Tcl 8.4, the value-based API \fBTcl_FSOpenFileChannel\fR should be used in preference to \fBTcl_OpenFileChannel\fR wherever possible. .PP The newly created channel is not registered in the supplied interpreter; to @@ -360,7 +360,7 @@ the standard channels (\fBstdout\fR, \fBstderr\fR, \fBstdin\fR), and will return Code not associated with a Tcl interpreter can call \fBTcl_DetachChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl that it no longer holds a reference to that channel. If this is the last -reference to the channel, unlike \fBTcl_UnregisterChannel\fR, +reference to the channel, unlike \fBTcl_UnregisterChannel\fR, it will not be closed. .SH TCL_ISSTANDARDCHANNEL .PP @@ -368,7 +368,7 @@ it will not be closed. three standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR. If so, it returns 1, otherwise 0. .PP -No attempt is made to check whether the given channel or the standard +No attempt is made to check whether the given channel or the standard channels are initialized or otherwise valid. .SH TCL_CLOSE .PP @@ -402,7 +402,7 @@ corresponding calls to \fBTcl_UnregisterChannel\fR. .SH "TCL_READCHARS AND TCL_READ" .PP \fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes -to UTF-8 based on the channel's encoding and storing the produced data in +to UTF-8 based on the channel's encoding and storing the produced data in \fIreadObjPtr\fR's string representation. The return value of \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR, that were stored in \fIreadObjPtr\fR. If an error occurs while reading, the @@ -450,7 +450,7 @@ extensions. It consumes bytes from \fIchannel\fR and stores them in of \fBTcl_Read\fR is the number of bytes, up to \fIbytesToRead\fR, written in \fIreadBuf\fR. The buffer produced by \fBTcl_Read\fR is not null-terminated. Its contents are valid from the zeroth position up to and excluding the -position indicated by the return value. +position indicated by the return value. .PP \fBTcl_ReadRaw\fR is the same as \fBTcl_Read\fR but does not compensate for stacking. While \fBTcl_Read\fR (and the other functions @@ -507,7 +507,7 @@ to be null-terminated and it outputs everything up to the null. .PP Data queued for output may not appear on the output device immediately, due to internal buffering. If the data should appear immediately, call -\fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the +\fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the \fB\-buffering\fR option on the channel to \fBnone\fR. If you wish the data to appear as soon as a complete line is accepted for output, set the \fB\-buffering\fR option on the channel to \fBline\fR mode. @@ -525,7 +525,7 @@ channel. This is done even if the channel has no encoding. \fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it accepts a Tcl value whose contents will be output to the channel. The UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted -to the channel's encoding and queued for output to \fIchannel\fR. +to the channel's encoding and queued for output to \fIchannel\fR. As a performance optimization, when writing to a channel with the encoding \fBbinary\fR, UTF-8 characters are not converted as they are written. Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 index 7090dd3..667d697 100644 --- a/doc/ParseCmd.3 +++ b/doc/ParseCmd.3 @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures" .so man.macros .BS @@ -56,7 +56,7 @@ following \fIstart\fR up to the first null character. .AP int nested in Non-zero means that the script is part of a command substitution so an unquoted close bracket should be treated as a command terminator. If zero, -close brackets have no special meaning. +close brackets have no special meaning. .AP int append in Non-zero means that \fI*parsePtr\fR already contains valid tokens; the new tokens should be appended to those already present. Zero means that @@ -118,7 +118,7 @@ result, and no information is left at \fI*parsePtr\fR. enclosed in braces such as \fB{hello}\fR or \fB{string \et with \et tabs}\fR from the beginning of its argument \fIstart\fR. -The first character of \fIstart\fR must be \fB{\fR. +The first character of \fIstart\fR must be \fB{\fR. If the braced string was parsed successfully, \fBTcl_ParseBraces\fR returns \fBTCL_OK\fR, fills in the structure pointed to by \fIparsePtr\fR @@ -134,7 +134,7 @@ and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR. \fBTcl_ParseQuotedString\fR parses a double-quoted string such as \fB"sum is [expr {$a+$b}]"\fR from the beginning of the argument \fIstart\fR. -The first character of \fIstart\fR must be \fB\N'34'\fR. +The first character of \fIstart\fR must be \fB\N'34'\fR. If the double-quoted string was parsed successfully, \fBTcl_ParseQuotedString\fR returns \fBTCL_OK\fR, fills in the structure pointed to by \fIparsePtr\fR @@ -150,7 +150,7 @@ and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR. \fBTcl_ParseVarName\fR parses a Tcl variable reference such as \fB$abc\fR or \fB$x([expr {$index + 1}])\fR from the beginning of its \fIstart\fR argument. -The first character of \fIstart\fR must be \fB$\fR. +The first character of \fIstart\fR must be \fB$\fR. If a variable name was parsed successfully, \fBTcl_ParseVarName\fR returns \fBTCL_OK\fR and fills in the structure pointed to by \fIparsePtr\fR with information about the structure of the variable name @@ -184,7 +184,7 @@ a Tcl_Parse structure. The tokens typically consist of all the tokens in a word or all the tokens that make up the index for a reference to an array variable. \fBTcl_EvalTokensStandard\fR performs the substitutions requested by the tokens and concatenates the -resulting values. +resulting values. The return value from \fBTcl_EvalTokensStandard\fR is a Tcl completion code with one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR, or possibly @@ -242,7 +242,7 @@ character that terminates the last comment. If the command is not preceded by any comments, \fIcommentSize\fR is 0. \fBTcl_ParseCommand\fR also sets the \fIcommandStart\fR field to point to the first character of the first -word in the command (skipping any comments and leading space) and +word in the command (skipping any comments and leading space) and \fIcommandSize\fR gives the total number of bytes in the command, including the character pointed to by \fIcommandStart\fR up to and including the newline, close bracket, or semicolon character that @@ -350,7 +350,7 @@ just the \fBTCL_TOKEN_OPERATOR\fR token. Each operand is described by a \fBTCL_TOKEN_SUB_EXPR\fR token. Otherwise, the subexpression is a value described by one of the token types \fBTCL_TOKEN_WORD\fR, \fBTCL_TOKEN_TEXT\fR, -\fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, +\fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, \fBTCL_TOKEN_VARIABLE\fR, and \fBTCL_TOKEN_SUB_EXPR\fR. The \fInumComponents\fR field counts the total number of sub-tokens that make up the subexpression; @@ -389,7 +389,7 @@ is always 0. After \fBTcl_ParseCommand\fR returns, the first token pointed to by the \fItokenPtr\fR field of the Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or -\fBTCL_TOKEN_SIMPLE_WORD\fR or \fBTCL_TOKEN_EXPAND_WORD\fR. +\fBTCL_TOKEN_SIMPLE_WORD\fR or \fBTCL_TOKEN_EXPAND_WORD\fR. It is followed by the sub-tokens that must be concatenated to produce the value of that word. The next token is the \fBTCL_TOKEN_WORD\fR or \fBTCL_TOKEN_SIMPLE_WORD\fR diff --git a/doc/StringObj.3 b/doc/StringObj.3 index d81f23d..7042cc8 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" .so man.macros .BS @@ -293,6 +293,7 @@ of \fBTcl_Format\fR with functionality equivalent to: Tcl_Obj *newPtr = \fBTcl_Format\fR(interp, format, objc, objv); if (newPtr == NULL) return TCL_ERROR; \fBTcl_AppendObjToObj\fR(objPtr, newPtr); +\fBTcl_DecrRefCount\fR(newPtr); return TCL_OK; .CE .PP @@ -307,7 +308,7 @@ sprintf(buf, format, ...); \fBTcl_NewStringObj\fR(buf, -1); .CE .PP -but with greater convenience and no need to +but with greater convenience and no need to determine \fBSOME_SUITABLE_LENGTH\fR. The formatting is done with the same core formatting engine used by \fBTcl_Format\fR. This means the set of supported conversion specifiers is that of the \fBformat\fR command and @@ -328,8 +329,8 @@ Tcl_Obj *objPtr = \fBTcl_ObjPrintf\fR("Value is %d", x); .PP If the value of \fIformat\fR contains internal inconsistencies or invalid specifier formats, the formatted string result produced by -\fBTcl_ObjPrintf\fR will be an error message describing the error. -It is impossible however to provide runtime protection against +\fBTcl_ObjPrintf\fR will be an error message describing the error. +It is impossible however to provide runtime protection against mismatches between the format and any subsequent arguments. Compile-time protection may be provided by some compilers. .PP @@ -337,7 +338,9 @@ Compile-time protection may be provided by some compilers. of \fBTcl_ObjPrintf\fR with functionality equivalent to .PP .CS -\fBTcl_AppendObjToObj\fR(objPtr, \fBTcl_ObjPrintf\fR(format, ...)); +Tcl_Obj *newPtr = \fBTcl_ObjPrintf\fR(format, ...); +\fBTcl_AppendObjToObj\fR(objPtr, newPtr); +\fBTcl_DecrRefCount\fR(newPtr); .CE .PP but with greater convenience and efficiency when the appending @@ -28,7 +28,7 @@ First, the Tcl interpreter breaks the command into \fIwords\fR and performs substitutions as described below. These substitutions are performed in the same way for all commands. -The first word is used to locate a command procedure to +Secondly, the first word is used to locate a command procedure to carry out the command, then all of the words of the command are passed to the command procedure. The command procedure is free to interpret each of its words @@ -108,8 +108,8 @@ Variable substitution may take any of the following forms: \fIName\fR is the name of a scalar variable; the name is a sequence of one or more characters that are a letter, digit, underscore, or namespace separators (two or more colons). -Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\-\fB9\fR, -\fBA\fR\-\fBZ\fR and \fBa\fR\-\fBz\fR). +Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\(en\fB9\fR, +\fBA\fR\(en\fBZ\fR and \fBa\fR\(en\fBz\fR). .TP 15 \fB$\fIname\fB(\fIindex\fB)\fR . @@ -117,8 +117,8 @@ Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\-\fB9\fR, the name of an element within that array. \fIName\fR must contain only letters, digits, underscores, and namespace separators, and may be an empty string. -Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\-\fB9\fR, -\fBA\fR\-\fBZ\fR and \fBa\fR\-\fBz\fR). +Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\(en\fB9\fR, +\fBA\fR\(en\fBZ\fR and \fBa\fR\(en\fBz\fR). Command substitutions, variable substitutions, and backslash substitutions are performed on the characters of \fIindex\fR. .TP 15 @@ -158,25 +158,25 @@ handled specially, along with the value that replaces each sequence. .RS .TP 7 \e\fBa\fR -Audible alert (bell) (0x7). +Audible alert (bell) (Unicode U+000007). .TP 7 \e\fBb\fR -Backspace (0x8). +Backspace (Unicode U+000008). .TP 7 \e\fBf\fR -Form feed (0xc). +Form feed (Unicode U+00000C). .TP 7 \e\fBn\fR -Newline (0xa). +Newline (Unicode U+00000A). .TP 7 \e\fBr\fR -Carriage-return (0xd). +Carriage-return (Unicode U+00000D). .TP 7 \e\fBt\fR -Tab (0x9). +Tab (Unicode U+000009). .TP 7 \e\fBv\fR -Vertical tab (0xb). +Vertical tab (Unicode U+00000B). .TP 7 \e\fB<newline>\fIwhiteSpace\fR . @@ -194,8 +194,9 @@ Backslash \e\fIooo\fR . The digits \fIooo\fR (one, two, or three of them) give a eight-bit octal -value for the Unicode character that will be inserted, in the range \fI000\fR -- \fI377\fR. The parser will stop just before this range overflows, or when +value for the Unicode character that will be inserted, in the range +\fI000\fR\(en\fI377\fR (i.e., the range U+000000\(enU+0000FF). +The parser will stop just before this range overflows, or when the maximum of three digits is reached. The upper bits of the Unicode character will be 0. .TP 7 @@ -203,23 +204,27 @@ character will be 0. . The hexadecimal digits \fIhh\fR (one or two of them) give an eight-bit hexadecimal value for the Unicode character that will be inserted. The upper -bits of the Unicode character will be 0. +bits of the Unicode character will be 0 (i.e., the character will be in the +range U+000000\(enU+0000FF). .TP 7 \e\fBu\fIhhhh\fR . The hexadecimal digits \fIhhhh\fR (one, two, three, or four of them) give a sixteen-bit hexadecimal value for the Unicode character that will be -inserted. The upper bits of the Unicode character will be 0. +inserted. The upper bits of the Unicode character will be 0 (i.e., the +character will be in the range U+000000\(enU+00FFFF). .TP 7 \e\fBU\fIhhhhhhhh\fR . The hexadecimal digits \fIhhhhhhhh\fR (one up to eight of them) give a twenty-one-bit hexadecimal value for the Unicode character that will be -inserted, in the range U+0000..U+10FFFF. The parser will stop just +inserted, in the range U+000000\(enU+10FFFF. The parser will stop just before this range overflows, or when the maximum of eight digits is reached. The upper bits of the Unicode character will be 0. +.RS .PP -The range U+010000..U+10FFFD is reserved for the future. +The range U+010000\(enU+10FFFD is reserved for the future. +.RE .PP Backslash substitution is not performed on words enclosed in braces, except for backslash-newline as described above. diff --git a/doc/Thread.3 b/doc/Thread.3 index ac5f2ba..5966a71 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -4,7 +4,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Threads 3 "8.1" Tcl "Tcl Library Procedures" .so man.macros .BS @@ -79,9 +79,10 @@ waited upon into it. .SH INTRODUCTION Beginning with the 8.1 release, the Tcl core is thread safe, which allows you to incorporate Tcl into multithreaded applications without -customizing the Tcl core. To enable Tcl multithreading support, -you must include the \fB\-\|\-enable-threads\fR option to \fBconfigure\fR -when you configure and compile your Tcl core. +customizing the Tcl core. Starting with the 8.6 release, Tcl +multithreading support is on by default. To disable Tcl multithreading +support, you must include the \fB\-\|\-disable-threads\fR option to +\fBconfigure\fR when you configure and compile your Tcl core. .PP An important constraint of the Tcl threads implementation is that \fIonly the thread that created a Tcl interpreter can use that @@ -126,7 +127,7 @@ will cause a memory leak. .PP The \fBTcl_GetThreadData\fR call returns a pointer to a block of thread-private data. Its argument is a key that is shared by all threads -and a size for the block of storage. The storage is automatically +and a size for the block of storage. The storage is automatically allocated and initialized to all zeros the first time each thread asks for it. The storage is automatically deallocated by \fBTcl_FinalizeThread\fR. .SS "SYNCHRONIZATION AND COMMUNICATION" diff --git a/doc/ToUpper.3 b/doc/ToUpper.3 index 587e76b..b933e9c 100644 --- a/doc/ToUpper.3 +++ b/doc/ToUpper.3 @@ -3,7 +3,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tcl_UtfToUpper 3 "8.1" Tcl "Tcl Library Procedures" .so man.macros .BS diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3 index 1244576..fccc0c6 100644 --- a/doc/TraceCmd.3 +++ b/doc/TraceCmd.3 @@ -78,7 +78,7 @@ created. \fIClientData\fR typically points to an application-specific data structure that describes what to do when \fIproc\fR is invoked. \fIOldName\fR gives the name of the command being renamed, and \fInewName\fR gives the name that the command is being renamed to (or -an empty string or NULL when the command is being deleted.) +NULL when the command is being deleted.) \fIFlags\fR is an OR'ed combination of bits potentially providing several pieces of information. One of the bits \fBTCL_TRACE_RENAME\fR and \fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which @@ -86,11 +86,14 @@ operation is being performed on the command. The bit \fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about to be destroyed; this information may be useful to \fIproc\fR so that it can clean up its own internal data structures (see the section -\fBTCL_TRACE_DESTROYED\fR below for more details). Lastly, the bit -\fBTCL_INTERP_DESTROYED\fR will be set if the entire interpreter is being -destroyed. When this bit is set, \fIproc\fR must be especially -careful in the things it does (see the section \fBTCL_INTERP_DESTROYED\fR -below). +\fBTCL_TRACE_DESTROYED\fR below for more details). Because the +deletion of commands can take place as part of the deletion of the interp +that contains them, \fIproc\fR must be careful about checking what +the passed in \fIinterp\fR value can be called upon to do. +The routine \fBTcl_InterpDeleted\fR is an important tool for this. +When \fBTcl_InterpDeleted\fR returns 1, \fIproc\fR will not be able +to invoke any scripts in \fIinterp\fR. The function of \fIproc\fR +in that circumstance is limited to the cleanup of its own data structures. .PP \fBTcl_UntraceCommand\fR may be used to remove a trace. If the command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has @@ -123,7 +126,8 @@ traces for a given command that have the same \fIproc\fR. .PP During rename traces, the command being renamed is visible with both names simultaneously, and the command still exists during delete -traces (if \fBTCL_INTERP_DESTROYED\fR is not set). However, there is no +traces, unless the interp that contains it is being deleted. +However, there is no mechanism for signaling that an error occurred in a trace procedure, so great care should be taken that errors do not get silently lost. .SH "MULTIPLE TRACES" @@ -142,22 +146,5 @@ rename the command, the last renaming takes precedence. In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit is set in \fIflags\fR. .\" Perhaps need some more comments here? - DKF -.SH "TCL_INTERP_DESTROYED" -.PP -When an interpreter is destroyed, unset traces are called for -all of its commands. -The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR -argument passed to the trace procedures. -Trace procedures must be extremely careful in what they do if -the \fBTCL_INTERP_DESTROYED\fR bit is set. -It is not safe for the procedures to invoke any Tcl procedures -on the interpreter, since its state is partially deleted. -All that trace procedures should do under these circumstances is -to clean up and free their own internal data structures. -.SH BUGS -.PP -Tcl does not do any error checking to prevent trace procedures -from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR -set. .SH KEYWORDS clientData, trace, command @@ -3,12 +3,12 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Utf 3 "8.1" Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME -Tcl_UniChar, Tcl_UniCharCaseMatch, Tcl_UniCharNcasecmp, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings +Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UniCharNcasecmp, Tcl_UniCharCaseMatch, Tcl_UtfNcmp, Tcl_UtfNcasecmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -48,7 +48,7 @@ int int \fBTcl_UtfCharComplete\fR(\fIsrc, length\fR) .sp -int +int \fBTcl_NumUtfChars\fR(\fIsrc, length\fR) .sp const char * @@ -109,7 +109,7 @@ Pointer to the beginning of a UTF-8 string. .AP int index in The index of a character (not byte) in the UTF-8 string. .AP int *readPtr out -If non-NULL, filled with the number of bytes in the backslash sequence, +If non-NULL, filled with the number of bytes in the backslash sequence, including the backslash character. .AP char *dst out Buffer in which the bytes represented by the backslash sequence are stored. @@ -142,7 +142,7 @@ end and dereference non-existent or random memory; if the source buffer is known to be null-terminated, this will not happen. If the input is not in proper UTF-8 format, \fBTcl_UtfToUniChar\fR will store the first byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x0000 and -0x00ff and return 1. +0x00ff and return 1. .PP \fBTcl_UniCharToUtfDString\fR converts the given Unicode string to UTF-8, storing the result in a previously initialized \fBTcl_DString\fR. @@ -210,12 +210,12 @@ length is negative, all bytes up to the first null byte are used. \fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings. It returns a pointer to the first occurrence of the Tcl_UniChar \fIch\fR in the null-terminated UTF-8 string \fIsrc\fR. The null terminator is -considered part of the UTF-8 string. +considered part of the UTF-8 string. .PP \fBTcl_UtfFindLast\fR corresponds to \fBstrrchr\fR for UTF-8 strings. It returns a pointer to the last occurrence of the Tcl_UniChar \fIch\fR in the null-terminated UTF-8 string \fIsrc\fR. The null terminator is -considered part of the UTF-8 string. +considered part of the UTF-8 string. .PP Given \fIsrc\fR, a pointer to some location in a UTF-8 string, \fBTcl_UtfNext\fR returns a pointer to the next UTF-8 character in the @@ -239,7 +239,7 @@ characters. Behavior is undefined if a negative \fIindex\fR is given. .PP \fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not byte) \fIindex\fR in the UTF-8 string \fIsrc\fR. The source string must -contain at least \fIindex\fR characters. This is equivalent to calling +contain at least \fIindex\fR characters. This is equivalent to calling \fBTcl_UtfNext\fR \fIindex\fR times. If a negative \fIindex\fR is given, the return pointer points to the first character in the source string. .PP diff --git a/doc/clock.n b/doc/clock.n index 42dca80..910ebb8 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -637,8 +637,9 @@ On output, produces a locale-dependent time of day representation on a 12-hour clock. On input, accepts whatever \fB%r\fR produces. .TP \fB%R\fR -On output, produces a locale-dependent time of day representation on a -24-hour clock. On input, accepts whatever \fB%R\fR produces. +On output, the time in 24-hour notation (%H:%M). For a version +including the seconds, see \fB%T\fR below. On input, accepts whatever +\fB%R\fR produces. .TP \fB%s\fR On output, simply formats the \fItimeVal\fR argument as a decimal @@ -25,11 +25,12 @@ below for a description), depending on \fIoption\fR. The legal This appends the given string (or strings) to the value that the given key maps to in the dictionary value contained in the given variable, writing the resulting dictionary value back to that variable. -Non-existent keys are treated as if they map to an empty string. +Non-existent keys are treated as if they map to an empty string. The +updated dictionary value is returned. .TP \fBdict create \fR?\fIkey value ...\fR? . -Create a new dictionary that contains each of the key/value mappings +Return a new dictionary that contains each of the key/value mappings listed as arguments (keys and values alternating, with each key being followed by its associated value.) .TP @@ -53,10 +54,10 @@ The key rule only matches those key/value pairs whose keys match any of the given patterns (in the style of \fBstring match\fR.) .VE 8.6 .TP -\fBdict filter \fIdictionaryValue \fBscript {\fIkeyVar valueVar\fB} \fIscript\fR +\fBdict filter \fIdictionaryValue \fBscript {\fIkeyVariable valueVariable\fB} \fIscript\fR . The script rule tests for matching by assigning the key to the -\fIkeyVar\fR and the value to the \fIvalueVar\fR, and then evaluating +\fIkeyVariable\fR and the value to the \fIvalueVariable\fR, and then evaluating the given script which should return a boolean value (with the key/value pair only being included in the result of the \fBdict filter\fR when a true value is returned.) Note that the first @@ -74,7 +75,7 @@ of the given patterns (in the style of \fBstring match\fR.) .VE 8.6 .RE .TP -\fBdict for {\fIkeyVar valueVar\fB} \fIdictionaryValue body\fR +\fBdict for {\fIkeyVariable valueVariable\fB} \fIdictionaryValue body\fR . This command takes three arguments, the first a two-element list of variable names (for the key and value respectively of each mapping in @@ -121,7 +122,8 @@ not specified) to the value that the given key maps to in the dictionary value contained in the given variable, writing the resulting dictionary value back to that variable. Non-existent keys are treated as if they map to 0. It is an error to increment a value -for an existing key if that value is not an integer. +for an existing key if that value is not an integer. The updated +dictionary value is returned. .TP \fBdict info \fIdictionaryValue\fR . @@ -145,9 +147,10 @@ to in the dictionary value contained in the given variable, writing the resulting dictionary value back to that variable. Non-existent keys are treated as if they map to an empty list, and it is legal for there to be no items to append to the list. It is an error for the -value that the key maps to to not be representable as a list. +value that the key maps to to not be representable as a list. The +updated dictionary value is returned. .TP -\fBdict map \fR{\fIkeyVar valueVar\fR} \fIdictionaryValue body\fR +\fBdict map \fR{\fIkeyVariable valueVariable\fR} \fIdictionaryValue body\fR . This command applies a transformation to each element of a dictionary, returning a new dictionary. It takes three arguments: the first is a @@ -157,7 +160,7 @@ and the third a script to be evaluated for each mapping with the key and value variables set appropriately (in the manner of \fBlmap\fR). In an iteration where the evaluated script completes normally (\fBTCL_OK\fR, as opposed to an \fBerror\fR, etc.) the result of the script is put into an accumulator -dictionary using the key that is the current contents of the \fIkeyVar\fR +dictionary using the key that is the current contents of the \fIkeyVariable\fR variable at that point. The result of the \fBdict map\fR command is the accumulator dictionary after all keys have been iterated over. .RS @@ -202,7 +205,7 @@ This operation takes the name of a variable containing a dictionary value and places an updated dictionary value in that variable containing a mapping from the given key to the given value. When multiple keys are present, this operation creates or updates a chain -of nested dictionaries. +of nested dictionaries. The updated dictionary value is returned. .TP \fBdict size \fIdictionaryValue\fR . @@ -216,7 +219,8 @@ dictionary value in that variable that does not contain a mapping for the given key. Where multiple keys are present, this describes a path through nested dictionaries to the mapping to remove. At least one key must be specified, but the last key on the key-path need not exist. -All other components on the path must exist. +All other components on the path must exist. The updated dictionary +value is returned. .TP \fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR . diff --git a/doc/encoding.n b/doc/encoding.n index be1dc3f..5782199 100644 --- a/doc/encoding.n +++ b/doc/encoding.n @@ -14,10 +14,21 @@ encoding \- Manipulate encodings .BE .SH INTRODUCTION .PP -Strings in Tcl are encoded using 16-bit Unicode characters. Different -operating system interfaces or applications may generate strings in -other encodings such as Shift-JIS. The \fBencoding\fR command helps -to bridge the gap between Unicode and these other formats. +Strings in Tcl are logically a sequence of 16-bit Unicode characters. +These strings are represented in memory as a sequence of bytes that +may be in one of several encodings: modified UTF\-8 (which uses 1 to 3 +bytes per character), 16-bit +.QW Unicode +(which uses 2 bytes per character, with an endianness that is +dependent on the host architecture), and binary (which uses a single +byte per character but only handles a restricted range of characters). +Tcl does not guarantee to always use the same encoding for the same +string. +.PP +Different operating system interfaces or applications may generate +strings in other encodings such as Shift\-JIS. The \fBencoding\fR +command helps to bridge the gap between Unicode and these other +formats. .SH DESCRIPTION .PP Performs one of several encoding related operations, depending on @@ -37,8 +48,9 @@ system encoding is used. Convert \fIstring\fR from Unicode to the specified \fIencoding\fR. The result is a sequence of bytes that represents the converted string. Each byte is stored in the lower 8-bits of a Unicode -character. If \fIencoding\fR is not specified, the current -system encoding is used. +character (indeed, the resulting string is a binary string as far as +Tcl is concerned, at least initially). If \fIencoding\fR is not +specified, the current system encoding is used. .TP \fBencoding dirs\fR ?\fIdirectoryList\fR? . @@ -56,6 +68,11 @@ searchable directory, that element is ignored. . Returns a list containing the names of all of the encodings that are currently available. +The encodings +.QW utf-8 +and +.QW iso8859-1 +are guaranteed to be present in the list. .TP \fBencoding system\fR ?\fIencoding\fR? . @@ -73,7 +90,7 @@ However, because the \fBsource\fR command always reads files using the current system encoding, Tcl will only source such files correctly when the encoding used to write the file is the same. This tends not to be true in an internationalized setting. For example, if such a -file was sourced in North America (where the ISO8859-1 is normally +file was sourced in North America (where the ISO8859\-1 is normally used), each byte in the file would be treated as a separate character that maps to the 00 page in Unicode. The resulting Tcl strings will not contain the expected Japanese characters. Instead, they will @@ -93,3 +110,6 @@ which is the Hiragana letter HA. Tcl_GetEncoding(3) .SH KEYWORDS encoding, unicode +.\" Local Variables: +.\" mode: nroff +.\" End: @@ -269,17 +269,13 @@ present, as is done when launching applications under wish. It is desirable to have console applications hidden and detached. This is a designed-in limitation as \fBexec\fR wants to communicate over pipes. The Expect extension addresses this issue when communicating with a TUI application. -.RE -.TP -\fBWindows NT\fR -. +.PP When attempting to execute an application, \fBexec\fR first searches for the name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR are appended to the end of the specified name and it searches for the longer name. If a directory name was not specified as part of the application name, the following directories are automatically searched in order when attempting to locate the application: -.RS .IP \(bu 3 The directory from which the Tcl executable was loaded. .IP \(bu 3 @@ -299,67 +295,6 @@ the caller must prepend the desired command with because built-in commands are not implemented using executables. .RE .TP -\fBWindows 9x\fR -. -When attempting to execute an application, \fBexec\fR first searches for -the name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and -\fB.bat\fR are appended to the end of the specified name and it searches -for the longer name. If a directory name was not specified as part of the -application name, the following directories are automatically searched in -order when attempting to locate the application: -.RS -.IP \(bu 3 -The directory from which the Tcl executable was loaded. -.IP \(bu 3 -The current directory. -.IP \(bu 3 -The Windows 9x system directory. -.IP \(bu 3 -The Windows 9x home directory. -.IP \(bu 3 -The directories listed in the path. -.RE -.RS -.PP -In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR, -the caller must prepend the desired command with -.QW "\fBcommand.com /c\0\fR" -because built-in commands are not implemented using executables. -.PP -Once a 16-bit DOS application has read standard input from a console and -then quit, all subsequently run 16-bit DOS applications will see the -standard input as already closed. 32-bit applications do not have this -problem and will run correctly, even after a 16-bit DOS application thinks -that standard input is closed. There is no known workaround for this bug -at this time. -.PP -Redirection between the \fBNUL:\fR device and a 16-bit application does not -always work. When redirecting from \fBNUL:\fR, some applications may hang, -others will get an infinite stream of -.QW 0x01 -bytes, and some will actually -correctly get an immediate end-of-file; the behavior seems to depend upon -something compiled into the application itself. When redirecting greater than -4K or so to \fBNUL:\fR, some applications will hang. The above problems do not -happen with 32-bit applications. -.PP -All DOS 16-bit applications are run synchronously. All standard input from -a pipe to a 16-bit DOS application is collected into a temporary file; the -other end of the pipe must be closed before the 16-bit DOS application -begins executing. All standard output or error from a 16-bit DOS -application to a pipe is collected into temporary files; the application -must terminate before the temporary files are redirected to the next stage -of the pipeline. This is due to a workaround for a Windows 95 bug in the -implementation of pipes, and is how the standard Windows 95 DOS shell -handles pipes itself. -.PP -Certain applications, such as \fBcommand.com\fR, should not be executed -interactively. Applications which directly access the console window, -rather than reading from their standard input and writing to their standard -output may fail, hang Tcl, or even hang the system if their own private -console window is not available to them. -.RE -.TP \fBUnix\fR (including Mac OS X) . The \fBexec\fR command is fully functional and works as described. @@ -35,7 +35,7 @@ proc main {} { if {[catch {main} msg options]} { puts stderr "unexpected script error: $msg" - if {[info exist env(DEBUG)]} { + if {[info exists env(DEBUG)]} { puts stderr "---- BEGIN TRACE ----" puts stderr [dict get $options -errorinfo] puts stderr "---- END TRACE ----" diff --git a/doc/fcopy.n b/doc/fcopy.n index ec3d5c6..071896c 100644 --- a/doc/fcopy.n +++ b/doc/fcopy.n @@ -46,8 +46,11 @@ non-blocking mode; the \fBfcopy\fR command takes care of that automatically. However, it is necessary to enter the event loop by using the \fBvwait\fR command or by using Tk. .PP -You are not allowed to do other I/O operations with -\fIinchan\fR or \fIoutchan\fR during a background \fBfcopy\fR. +You are not allowed to do other input operations with \fIinchan\fR, or +output operations with \fIoutchan\fR, during a background +\fBfcopy\fR. The converse is entirely legitimate, as exhibited by the +bidirectional fcopy example below. +.PP If either \fIinchan\fR or \fIoutchan\fR get closed while the copy is in progress, the current copy is stopped and the command callback is \fInot\fR made. @@ -57,7 +60,7 @@ then all data already queued for \fIoutchan\fR is written out. Note that \fIinchan\fR can become readable during a background copy. You should turn off any \fBfileevent\fR handlers during a background copy so those handlers do not interfere with the copy. -Any I/O attempted by a \fBfileevent\fR handler will get a +Any wrong-sided I/O attempted (by a \fBfileevent\fR handler or otherwise) will get a .QW "channel busy" error. .PP @@ -149,6 +152,24 @@ set total 0 -command [list CopyMore $in $out $chunk] vwait done .CE +.PP +The fourth example starts an asynchronous, bidirectional fcopy between +two sockets. Those could also be pipes from two [open "|hal 9000" r+] +(though their conversation would remain secret to the script, since +all four fileevent slots are busy). +.PP +.CS +set flows 2 +proc Done {dir args} { + global flows done + puts "$dir is over." + incr flows -1 + if {$flows<=0} {set done 1} +} +\fBfcopy\fR $sok1 $sok2 -command [list Done UP] +\fBfcopy\fR $sok2 $sok1 -command [list Done DOWN] +vwait done +.CE .SH "SEE ALSO" eof(n), fblocked(n), fconfigure(n), file(n) .SH KEYWORDS @@ -241,11 +241,9 @@ as relative to the cwd). Furthermore, paths are always expanded to absolute form. When creating links on filesystems that either do not support any links, or do not support the specific type requested, an -error message will be returned. In particular Windows 95, 98 and ME do -not support any links at present, but most Unix platforms support both -symbolic and hard links (the latter for files only) and Windows -NT/2000/XP (on NTFS drives) support symbolic -directory links and hard file links. +error message will be returned. Most Unix platforms support both +symbolic and hard links (the latter for files only). Windows +supports symbolic directory links and hard file links on NTFS drives. .RE .TP \fBfile lstat \fIname varName\fR @@ -204,13 +204,7 @@ of the form it refers to the home directory of the user whose account information resides on the specified NT domain server. Otherwise, user account information is obtained from -the local computer. On Windows 95 and 98, \fBglob\fR accepted patterns -like -.QW .../ -and -.QW ..../ -for successively higher up parent directories, but later versions of -Windows do not accept these forms. +the local computer. .PP Since the backslash character has a special meaning to the glob command, glob patterns containing Windows style path separators need @@ -210,7 +210,8 @@ proc httpHandlerCallback {socket token} { .TP \fB\-headers\fR \fIkeyvaluelist\fR . -This option is used to add extra headers to the HTTP request. The +This option is used to add headers not already specified +by \fB::http::config\fR to the HTTP request. The \fIkeyvaluelist\fR argument must be a list with an even number of elements that alternate between keys and values. The keys become header field names. Newlines are stripped from the values so the diff --git a/doc/library.n b/doc/library.n index 775b7d9..6f8f265 100644 --- a/doc/library.n +++ b/doc/library.n @@ -4,7 +4,7 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH library n "8.0" Tcl "Tcl Built-In Commands" .so man.macros .BS @@ -19,7 +19,7 @@ auto_execok, auto_import, auto_load, auto_mkindex, auto_qualify, auto_reset, tcl \fBauto_qualify \fIcommand namespace\fR \fBauto_reset\fR \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR -\fBparray \fIarrayName\fR +\fBparray \fIarrayName\fR ?\fIpattern\fR? \fBtcl_endOfWord \fIstr start\fR \fBtcl_startOfNextWord \fIstr start\fR \fBtcl_startOfPreviousWord \fIstr start\fR @@ -139,7 +139,7 @@ as its first characters then it is assumed to be a procedure definition and the next word of the line is taken as the procedure's name. Procedure definitions that do not appear in this way (e.g.\ they -have spaces before the \fBproc\fR) will not be indexed. If your +have spaces before the \fBproc\fR) will not be indexed. If your script contains .QW dangerous code, such as global initialization @@ -178,7 +178,7 @@ performing the actual auto-loading of functions at runtime. This is a standard search procedure for use by extensions during their initialization. They call this procedure to look for their script library in several standard directories. -The last component of the name of the library directory is +The last component of the name of the library directory is normally \fIbasenameversion\fR (e.g., tk8.0), but it might be .QW library @@ -196,9 +196,11 @@ bin or bin/\fIarch\fR directory; relative to the executable file in the current build tree; relative to the executable file in a parallel build tree. .TP -\fBparray \fIarrayName\fR -Prints on standard output the names and values of all the elements -in the array \fIarrayName\fR. +\fBparray \fIarrayName\fR ?\fIpattern\fR? +Prints on standard output the names and values of all the elements in the +array \fIarrayName\fR, or just the names that match \fIpattern\fR (using the +matching rules of \fBstring match\fR) and their values if \fIpattern\fR is +given. \fIArrayName\fR must be an array accessible to the caller of \fBparray\fR. It may be either local or global. .TP @@ -283,7 +285,7 @@ a default value is used. .TP \fBenv(TCLLIBPATH)\fR If set, then it must contain a valid Tcl list giving directories to -search during auto-load operations. Directories must be specified in +search during auto-load operations. Directories must be specified in Tcl format, using .QW / as the path separator, regardless of platform. @@ -312,7 +314,7 @@ Unix, words are comprised of numbers, letters or underscores. .SH "SEE ALSO" env(n), info(n), re_syntax(n) .SH KEYWORDS -auto-exec, auto-load, library, unknown, word, whitespace +auto-exec, auto-load, library, unknown, word, whitespace '\"Local Variables: '\"mode: nroff '\"End: diff --git a/doc/lreplace.n b/doc/lreplace.n index 7bba543..d19f0cd 100644 --- a/doc/lreplace.n +++ b/doc/lreplace.n @@ -35,7 +35,7 @@ by \fIfirst\fR must exist or \fIfirst\fR must indicate before the start of the list. .PP If \fIlast\fR is less than \fIfirst\fR, then any specified elements -will be inserted into the list at the point specified by \fIfirst\fR +will be inserted into the list before the point specified by \fIfirst\fR with no elements being deleted. .PP The \fIelement\fR arguments specify zero or more new arguments to diff --git a/doc/msgcat.n b/doc/msgcat.n index bae6dbe..7e46528 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -13,29 +13,43 @@ msgcat \- Tcl message catalog .SH SYNOPSIS \fBpackage require Tcl 8.5\fR .sp -\fBpackage require msgcat 1.5\fR +\fBpackage require msgcat 1.6\fR .sp \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? .sp \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR? .sp +.VS "TIP 412" +\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? \fIsrc-string\fR +.VE "TIP 412" +.sp \fB::msgcat::mclocale \fR?\fInewLocale\fR? .sp \fB::msgcat::mcpreferences\fR .sp +.VS "TIP 412" +\fB::msgcat::mcloadedlocales subcommand\fR ?\fIlocale\fR? +.VE "TIP 412" +.sp \fB::msgcat::mcload \fIdirname\fR .sp \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? .sp \fB::msgcat::mcmset \fIlocale src-trans-list\fR .sp -.VS "TIP 404" \fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR? .sp \fB::msgcat::mcflmset \fIsrc-trans-list\fR -.VE "TIP 404" .sp \fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR? +.sp +.VS "TIP 412" +\fB::msgcat::mcpackagelocale subcommand\fR ?\fIlocale\fR? +.sp +\fB::msgcat::mcpackageconfig subcommand\fR \fIoption\fR ?\fIvalue\fR? +.sp +\fB::msgcat::mcforgetpackage\fR +.VE "TIP 412" .BE .SH DESCRIPTION .PP @@ -46,18 +60,23 @@ Text strings are defined in a which is independent from the application, and which can be edited or localized without modifying the application source code. New languages -or locales are provided by adding a new file to +or locales may be provided by adding a new file to the message catalog. .PP -Use of the message catalog is optional by any application -or package, but is encouraged if the application or package -wishes to be enabled for multi-lingual applications. +\fBmsgcat\fR distinguises packages by its namespace. +Each package has its own message catalog and configuration settings in \fBmsgcat\fR. +.PP +A \fIlocale\fR is a specification string describing a user language like \fBde_ch\fR for Swiss German. +In \fBmsgcat\fR, there is a global locale initialized by the system locale of the current system. +Each package may decide to use the global locale or to use a package specific locale. +.PP +The global locale may be changed on demand, for example by a user initiated language change or within a multi user application like a web server. .SH COMMANDS .TP \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? . Returns a translation of \fIsrc-string\fR according to the -user's current locale. If additional arguments past \fIsrc-string\fR +current locale. If additional arguments past \fIsrc-string\fR are given, the \fBformat\fR command is used to substitute the additional arguments in the translation of \fIsrc-string\fR. .RS @@ -84,6 +103,18 @@ of the longest translated string. This is useful when designing localized GUIs, which may require that all buttons, for example, be a fixed width (which will be the width of the widest button). .TP +\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? \fIsrc-string\fR +. +.VS "TIP 412" +Return true, if there is a translation for the given \fIsrc-string\fR. +.PP +.RS +The search may be limited by the option \fB\-exactnamespace\fR to only check the current namespace and not any parent namespaces. +.PP +It may also be limited by the option \fB\-exactlocale\fR to only check the first prefered locale (e.g. first element returned by \fB::msgcat::mcpreferences\fR if global locale is used). +.RE +.VE "TIP 412" +.TP \fB::msgcat::mclocale \fR?\fInewLocale\fR? . This function sets the locale to \fInewLocale\fR. If \fInewLocale\fR @@ -93,6 +124,13 @@ case-insensitive manner, and returns locales in lowercase. The initial locale is determined by the locale specified in the user's environment. See \fBLOCALE SPECIFICATION\fR below for a description of the locale string format. +.RS +.PP +.VS "TIP 412" +If the locale is set, the preference list of locales is evaluated. +Locales in this list are loaded now, if not jet loaded. +.VE "TIP 412" +.RE .TP \fB::msgcat::mcpreferences\fR . @@ -103,13 +141,26 @@ preference. The list is derived from the current locale set in msgcat by \fB::msgcat::mclocale\fR, and cannot be set independently. For example, if the current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR -returns \fB{en_US_funky en_US en {}}\fR. +returns \fB{en_us_funky en_us en {}}\fR. +.TP +\fB::msgcat:mcloadedlocales subcommand\fR ?\fIlocale\fR? +. +This group of commands manage the list of loaded locales for packages not setting a package locale. +.PP +.RS +The subcommand \fBget\fR returns the list of currently loaded locales. +.PP +The subcommand \fBpresent\fR requires the argument \fIlocale\fR and returns true, if this locale is loaded. +.PP +The subcommand \fBclear\fR removes all locales and their data, which are not in the current preference list. +.RE .TP \fB::msgcat::mcload \fIdirname\fR . +.VS "TIP 412" Searches the specified directory for files that match -the language specifications returned by \fB::msgcat::mcpreferences\fR -(note that these are all lowercase), extended by the file extension +the language specifications returned by \fB::msgcat::mcloadedlocales get\fR +(or \fBmsgcat::mcpackagelocale preferences\fR if a package locale is set) (note that these are all lowercase), extended by the file extension .QW .msg . Each matching file is read in order, assuming a UTF-8 encoding. The file contents are @@ -118,6 +169,11 @@ may be present in the message file either directly in their UTF-8 encoded form, or by use of the backslash-u quoting recognized by Tcl evaluation. The number of message files which matched the specification and were loaded is returned. +.RS +.PP +In addition, the given folder is stored in the \fBmsgcat\fR package configuration option \fImcfolder\fR to eventually load message catalog files required by a locale change. +.VE "TIP 412" +.RE .TP \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? . @@ -138,16 +194,13 @@ faster than multiple invocations of \fB::msgcat::mcset\fR. The function returns the number of translations set. .TP \fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR? -.VS "TIP 404" Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the current namespace for the locale implied by the name of the message catalog being loaded via \fB::msgcat::mcload\fR. If \fItranslate-string\fR is not specified, \fIsrc-string\fR is used for both. The function returns \fItranslate-string\fR. -.VE "TIP 404" .TP \fB::msgcat::mcflmset \fIsrc-trans-list\fR -.VS "TIP 404" Sets the translation for multiple source strings in \fIsrc-trans-list\fR in the current namespace for the locale implied by the name of the message catalog being loaded via \fB::msgcat::mcload\fR. \fIsrc-trans-list\fR must @@ -155,7 +208,6 @@ have an even number of elements and is in the form {\fIsrc-string translate-string\fR ?\fIsrc-string translate-string ...\fR?} \fB::msgcat::mcflmset\fR can be significantly faster than multiple invocations of \fB::msgcat::mcflset\fR. The function returns the number of translations set. -.VE "TIP 404" .TP \fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR? . @@ -168,7 +220,18 @@ application, for example to log error messages for each unknown string. The \fB::msgcat::mcunknown\fR procedure is invoked at the same stack context as the call to \fB::msgcat::mc\fR. The return value of \fB::msgcat::mcunknown\fR is used as the return value for the call -to \fB::msgcat::mc\fR. +to \fB::msgcat::mc\fR. +.VS "TIP 412" +.RS +.PP +Note that this routine is only called if the concerned package did not set a package locale unknown command name. +.RE +.TP +\fB::msgcat::mcforgetpackage\fR +. +The calling package clears all its state within the \fBmsgcat\fR package including all settings and translations. +.VE "TIP 412" +.PP .SH "LOCALE SPECIFICATION" .PP The locale is specified to \fBmsgcat\fR by a locale string @@ -217,15 +280,15 @@ When a locale is specified by the user, a search is performed during string translation. For example, if a user specifies en_GB_Funky, the locales -.QW en_GB_Funky , -.QW en_GB , +.QW en_gb_funky , +.QW en_gb , .QW en and .MT (the empty string) are searched in order until a matching translation string is found. If no translation string is available, then -\fB::msgcat::mcunknown\fR is called. +the unknown handler is called. .SH "NAMESPACES AND MESSAGE CATALOGS" .PP Strings stored in the message catalog are stored relative @@ -373,6 +436,209 @@ formatting substitution is done directly. # ... where that key is mapped to one of the # human-oriented versions by \fBmsgcat::mcset\fR .CE +.VS "TIP 412" +.SH Package private locale +.PP +A package using \fBmsgcat\fR may choose to use its own package private +locale and its own set of loaded locales, independent to the global +locale set by \fB::msgcat::mclocale\fR. +.PP +This allows a package to change its locale without causing any locales load or removal in other packages and not to invoke the global locale change callback (see below). +.PP +This action is controled by the following ensemble: +.TP +\fB::msgcat::mcpackagelocale set\fR ?\fIlocale\fR? +. +Set or change a package private locale. +The package private locale is set to the given \fIlocale\fR if the \fIlocale\fR is given. +If the option \fIlocale\fR is not given, the package is set to package private locale mode, but no locale is changed (e.g. if the global locale was valid for the package before, it is copied to the package private locale). +.PP +.RS +This command may cause the load of locales. +.RE +.TP +\fB::msgcat::mcpackagelocale get\fR +. +Return the package private locale or the global locale, if no package private locale is set. +.TP +\fB::msgcat::mcpackagelocale preferences\fR +. +Return the package private preferences or the global preferences, +if no package private locale is set. +.TP +\fB::msgcat::mcpackagelocale loaded\fR +. +Return the list of locales loaded for this package. +.TP +\fB::msgcat::mcpackagelocale isset\fR +. +Returns true, if a package private locale is set. +.TP +\fB::msgcat::mcpackagelocale unset\fR +. +Unset the package private locale and use the globale locale. +Load and remove locales to adjust the list of loaded locales for the +package to the global loaded locales list. +.TP +\fB::msgcat::mcpackagelocale present\fR \fIlocale\fR +. +Returns true, if the given locale is loaded for the package. +.TP +\fB::msgcat::mcpackagelocale clear\fR +. +Clear any loaded locales of the package not present in the package preferences. +.PP +.SH Changing package options +.PP +Each package using msgcat has a set of options within \fBmsgcat\fR. +The package options are described in the next sectionPackage options. +Each package option may be set or unset individually using the following ensemble: +.TP +\fB::msgcat::mcpackageconfig get\fR \fIoption\fR +. +Return the current value of the given \fIoption\fR. +This call returns an error if the option is not set for the package. +.TP +\fB::msgcat::mcpackageconfig isset\fR \fIoption\fR +. +Returns 1, if the given \fIoption\fR is set for the package, 0 otherwise. +.TP +\fB::msgcat::mcpackageconfig set\fR \fIoption\fR \fIvalue\fR +. +Set the given \fIoption\fR to the given \fIvalue\fR. +This may invoke additional actions in dependency of the \fIoption\fR. +The return value is 0 or the number of loaded packages for the option \fBmcfolder\fR. +.TP +\fB::msgcat::mcpackageconfig unset\fR \fIoption\fR +. +Unsets the given \fIoption\fR for the package. +No action is taken if the \fIoption\fR is not set for the package. +The empty string is returned. +.SS Package options +.PP +The following package options are available for each package: +.TP +\fBmcfolder\fR +. +This is the message folder of the package. This option is set by mcload and by the subcommand set. Both are identical and both return the number of loaded message catalog files. +.RS +.PP +Setting or changing this value will load all locales contained in the preferences valid for the package. This implies also to invoke any set loadcmd (see below). +.PP +Unsetting this value will disable message file load for the package. +.RE +.TP +\fBloadcmd\fR +. +This callback is invoked before a set of message catalog files are loaded for the package which has this property set. +.PP +.RS +This callback may be used to do any preparation work for message file load or to get the message data from another source like a data base. In this case, no message files are used (mcfolder is unset). +.PP +See section \fBcallback invocation\fR below. +The parameter list appended to this callback is the list of locales to load. +.PP +If this callback is changed, it is called with the preferences valid for the package. +.RE +.TP +\fBchangecmd\fR +. +This callback is invoked when a default local change was performed. Its purpose is to allow a package to update any dependency on the default locale like showing the GUI in another language. +.PP +.RS +See the callback invocation section below. +The parameter list appended to this callback is \fBmcpreferences\fR. +The registered callbacks are invoked in no particular order. +.RE +.TP +\fBunknowncmd\fR +. +Use a package locale mcunknown procedure instead of the standard version supplied by the msgcat package (msgcat::mcunknown). +.PP +.RS +The called procedure must return the formatted message which will finally be returned by msgcat::mc. +.PP +A generic unknown handler is used if set to the empty string. This consists in returning the key if no arguments are given. With given arguments, format is used to process the arguments. +.PP +See section \fBcallback invocation\fR below. +The appended arguments are identical to \fB::msgcat::mcunknown\fR. +.RE +.SS Callback invocation +A package may decide to register one or multiple callbacks, as described above. +.PP +Callbacks are invoked, if: +.PP +1. the callback command is set, +.PP +2. the command is not the empty string, +.PP +3. the registering namespace exists. +.PP +If a called routine fails with an error, the \fBbgerror\fR routine for the interpreter is invoked after command completion. +Only exception is the callback \fBunknowncmd\fR, where an error causes the invoking \fBmc\fR-command to fail with that error. +.PP +.SS Examples +Packages which display a GUI may update their widgets when the global locale changes. +To register to a callback, use: +.CS +namespace eval gui { + msgcat::mcpackageconfig changecmd updateGUI + + proc updateGui args { + puts "New locale is '[lindex $args 0]'." + } +} +% msgcat::mclocale fr +fr +% New locale is 'fr'. +.CE +.PP +If locales (or additional locales) are contained in another source like a data base, a package may use the load callback and not mcload: +.CS +namespace eval db { + msgcat::mcpackageconfig loadcmd loadMessages + + proc loadMessages args { + foreach locale $args { + if {[LocaleInDB $locale]} { + msgcat::mcmset $locale [GetLocaleList $locale] + } + } + } +} +.CE +.PP +The \fBclock\fR command implementation uses \fBmsgcat\fR with a package locale to implement the command line parameter \fB-locale\fR. +Here are some sketches of the implementation: +.PP +First, a package locale is initialized and the generic unknown function is desactivated: +.CS +msgcat::mcpackagelocale set +msgcat::mcpackageconfig unknowncmd "" +.CE +As an example, the user requires the week day in a certain locale as follows: +.CS +clock format clock seconds -format %A -locale fr +.CE +\fBclock\fR sets the package locale to \fBfr\fR and looks for the day name as follows: +.CS +msgcat::mcpackagelocale set $locale +return [lindex [msgcat::mc DAYS_OF_WEEK_FULL] $day] +### Returns "mercredi" +.CE +Within \fBclock\fR, some message-catalog items are heavy in computation and thus are dynamically cached using: +.CS +proc ::tcl::clock::LocalizeFormat { locale format } { + set key FORMAT_$format + if { [::msgcat::mcexists -exactlocale -exactnamespace $key] } { + return [mc $key] + } + #...expensive computation of format clipped... + mcset $locale $key $format + return $format +} +.CE +.VE "TIP 412" .SH CREDITS .PP The message catalog code was developed by Mark Harrison. @@ -37,7 +37,7 @@ the \fBoo::object\fR class, which is not publicly visible by default: oo::class create c { method count {} { \fBmy\fR variable counter - print [incr counter] + puts [incr counter] } } c create o @@ -96,9 +96,11 @@ 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 invocation of the \fBunknown\fR -method because of a failure to locate a method implementation, or when -invoking either constructors or destructors. +Filters are invoked when processing an invokation of the \fBunknown\fR +method because of a failure to locate a method implementation, but \fInot\fR +when invoking either constructors or destructors. (Note however that the +\fBdestroy\fR method is a conventional method, and filters are invoked as +normal when it is called.) .SH EXAMPLES .PP This example demonstrates how to use the \fBnext\fR command to call the @@ -120,7 +122,7 @@ oo::class create theSubclass { } } theSubclass create obj -oo::define obj method example args { +oo::objdefine obj method example args { puts "per-object method, args = $args" \fBnext\fR x {*}$args y \fBnext\fR @@ -174,7 +176,7 @@ oo::class create cache { } oo::object create demo -oo::define demo { +oo::objdefine demo { mixin cache method compute {a b c} { after 3000 \fI;# Simulate deep thought\fR @@ -361,63 +361,28 @@ may cause this error. A BREAK condition has been detected by your UART (see above). .SH "PORTABILITY ISSUES" .TP -\fBWindows \fR(all versions) +\fBWindows \fR . Valid values for \fIfileName\fR to open a serial port are of the form -\fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4. -This notation only works for serial ports from 1 to 9, if the system -happens to have more than four. An attempt to open a serial port that +\fBcom\fIX\fB\fR, where \fIX\fR is a number, generally from 1 to 9. +A legacy form accepted as well is \fBcom\fIX\fB:\fR. This notation only +works for serial ports from 1 to 9. An attempt to open a serial port that does not exist or has a number greater than 9 will fail. An alternate -form of opening serial ports is to use the filename \fB\e\e.\ecomX\fR, -where X is any number that corresponds to a serial port; please note -that this method is considerably slower on Windows 95 and Windows 98. -.TP -\fBWindows NT\fR -. +form of opening serial ports is to use the filename \fB//./comX\fR, +where X is any number that corresponds to a serial port. +.PP +.RS When running Tcl interactively, there may be some strange interactions between the real console, if one is present, and a command pipeline that uses standard input or output. If a command pipeline is opened for reading, some of the lines entered at the console will be sent to the command pipeline and some will be sent to the Tcl evaluator. If a command pipeline is opened for writing, keystrokes entered into the console are not visible until the -pipe is closed. This behavior occurs whether the command pipeline is -executing 16-bit or 32-bit applications. These problems only occur because -both Tcl and the child application are competing for the console at -the same time. If the command pipeline is started from a script, so that Tcl -is not accessing the console, or if the command pipeline does not use -standard input or output, but is redirected from or to a file, then the -above problems do not occur. -.TP -\fBWindows 95\fR -. -A command pipeline that executes a 16-bit DOS application cannot be opened -for both reading and writing, since 16-bit DOS applications that receive -standard input from a pipe and send standard output to a pipe run -synchronously. Command pipelines that do not execute 16-bit DOS -applications run asynchronously and can be opened for both reading and -writing. -.RS -.PP -When running Tcl interactively, there may be some strange interactions -between the real console, if one is present, and a command pipeline that uses -standard input or output. If a command pipeline is opened for reading from -a 32-bit application, some of the keystrokes entered at the console will be -sent to the command pipeline and some will be sent to the Tcl evaluator. If -a command pipeline is opened for writing to a 32-bit application, no output -is visible on the console until the pipe is closed. These problems only -occur because both Tcl and the child application are competing for the -console at the same time. If the command pipeline is started from a script, -so that Tcl is not accessing the console, or if the command pipeline does -not use standard input or output, but is redirected from or to a file, then -the above problems do not occur. -.PP -Whether or not Tcl is running interactively, if a command pipeline is opened -for reading from a 16-bit DOS application, the call to \fBopen\fR will not -return until end-of-file has been received from the command pipeline's -standard output. If a command pipeline is opened for writing to a 16-bit DOS -application, no data will be sent to the command pipeline's standard output -until the pipe is actually closed. This problem occurs because 16-bit DOS -applications are run synchronously, as described above. +pipe is closed. These problems only occur because both Tcl and the child +application are competing for the console at the same time. If the command +pipeline is started from a script, so that Tcl is not accessing the console, +or if the command pipeline does not use standard input or output, but is +redirected from or to a file, then the above problems do not occur. .RE .TP \fBUnix\fR\0\0\0\0\0\0\0 diff --git a/doc/re_syntax.n b/doc/re_syntax.n index 46a180d..7988071 100644 --- a/doc/re_syntax.n +++ b/doc/re_syntax.n @@ -683,9 +683,33 @@ earlier in the RE taking priority over ones starting later. Note that outer subexpressions thus take priority over their component subexpressions. .PP -Note that the quantifiers \fB{1,1}\fR and \fB{1,1}?\fR can be used to +The quantifiers \fB{1,1}\fR and \fB{1,1}?\fR can be used to force longest and shortest preference, respectively, on a subexpression or a whole RE. +.RS +.PP +\fBNOTE:\fR This means that you can usually make a RE be non-greedy overall by +putting \fB{1,1}?\fR after one of the first non-constraint atoms or +parenthesized sub-expressions in it. \fIIt pays to experiment\fR with the +placing of this non-greediness override on a suitable range of input texts +when you are writing a RE if you are using this level of complexity. +.PP +For example, this regular expression is non-greedy, and will match the +shortest substring possible given that +.QW \fBabc\fR +will be matched as early as possible (the quantifier does not change that): +.PP +.CS +ab{1,1}?c.*x.*cba +.CE +.PP +The atom +.QW \fBa\fR +has no greediness preference, we explicitly give one for +.QW \fBb\fR , +and the remaining quantifiers are overridden to be non-greedy by the preceding +non-greedy quantifier. +.RE .PP Match lengths are measured in characters, not collating elements. An empty string is considered longer than no match at all. For example, diff --git a/doc/regexp.n b/doc/regexp.n index 17bf564..5fc2895 100644 --- a/doc/regexp.n +++ b/doc/regexp.n @@ -51,7 +51,7 @@ the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page). .TP 15 \fB\-indices\fR . -Changes what is stored in the \fIsubMatchVar\fRs. +Changes what is stored in the \fImatchVar\fR and \fIsubMatchVar\fRs. Instead of storing the matching characters from \fIstring\fR, each variable will contain a list of two decimal strings giving the indices diff --git a/doc/socket.n b/doc/socket.n index b7a4a45..275771d 100644 --- a/doc/socket.n +++ b/doc/socket.n @@ -97,6 +97,10 @@ writable channel event on the socket to get notified when the asynchronous connection has succeeded or failed. See the \fBvwait\fR and the \fBchan\fR commands for more details on the event loop and channel events. +.PP +The \fBchan configure\fR option \fB-connecting\fR may be used to check if the connect is still running. To verify a successful connect, the option \fB-error\fR may be checked when \fB-connecting\fR returned 0. +.PP +Operation without the event queue requires at the moment calls to \fBchan configure\fR to advance the internal state machine. .RE .SH "SERVER SOCKETS" .PP @@ -186,6 +190,10 @@ sockets, this option returns a list of three elements; these are the address, the host name and the port to which the peer socket is connected or bound. If the host name cannot be computed, the second element of the list is identical to the address, its first element. +.TP +\fB\-connecting\fR +. +This option is not supported by server sockets. For client sockets, this option returns 1 if an asyncroneous connect is still in progress, 0 otherwise. .PP .SH "EXAMPLES" .PP diff --git a/doc/source.n b/doc/source.n index 9f488c5..67d4b6b 100644 --- a/doc/source.n +++ b/doc/source.n @@ -43,6 +43,8 @@ or which will be safely substituted by the Tcl interpreter into .QW ^Z . .PP +A leading BOM (Byte order mark) contained in the file is ignored for unicode encodings (utf-8, unicode). +.PP The \fB\-encoding\fR option is used to specify the encoding of the data stored in \fIfileName\fR. When the \fB\-encoding\fR option is omitted, the system encoding is assumed. diff --git a/doc/string.n b/doc/string.n index 76005fc..33780ff 100644 --- a/doc/string.n +++ b/doc/string.n @@ -19,6 +19,21 @@ string \- Manipulate strings Performs one of several string operations, depending on \fIoption\fR. The legal \fIoption\fRs (which may be abbreviated) are: .TP +\fBstring cat\fR ?\fIstring1\fR? ?\fIstring2...\fR? +.VS 8.6.2 +Concatenate the given \fIstring\fRs just like placing them directly +next to each other and return the resulting compound string. If no +\fIstring\fRs are present, the result is an empty string. +.RS +.PP +This primitive is occasionally handier than juxtaposition of strings +when mixed quoting is wanted, or when the aim is to return the result +of a concatenation without resorting to \fBreturn\fR \fB\-level 0\fR, +and is more efficient than building a list of arguments and using +\fBjoin\fR with an empty join string. +.RE +.VE +.TP \fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length\fI length\fR? \fIstring1 string2\fR . Perform a character-by-character comparison of strings \fIstring1\fR @@ -131,8 +146,9 @@ Any Unicode printing character, including space. .IP \fBpunct\fR 12 Any Unicode punctuation character. .IP \fBspace\fR 12 -Any Unicode whitespace character, zero width space (U+200b), -word joiner (U+2060) and zero width no-break space (U+feff) (=BOM). +Any Unicode whitespace character, mongolian vowel separator +(U+180e), zero width space (U+200b), word joiner (U+2060) or +zero width no-break space (U+feff) (=BOM). .IP \fBtrue\fR 12 Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is true. @@ -343,10 +359,13 @@ misleading. \fBstring bytelength \fIstring\fR . Returns a decimal string giving the number of bytes used to represent -\fIstring\fR in memory. Because UTF\-8 uses one to three bytes to -represent Unicode characters, the byte length will not be the same as -the character length in general. The cases where a script cares about -the byte length are rare. +\fIstring\fR in memory when encoded as Tcl's internal modified UTF\-8; +Tcl may use other encodings for \fIstring\fR as well, and does not +guarantee to only use a single encoding for a particular \fIstring\fR. +Because UTF\-8 uses a variable number of bytes to represent Unicode +characters, the byte length will not be the same as the character +length in general. The cases where a script cares about the byte +length are rare. .RS .PP In almost all cases, you should use the @@ -354,10 +373,27 @@ In almost all cases, you should use the Tcl byte array value). Refer to the \fBTcl_NumUtfChars\fR manual entry for more details on the UTF\-8 representation. .PP +Formally, the \fBstring bytelength\fR operation returns the content of +the \fIlength\fR field of the \fBTcl_Obj\fR structure, after calling +\fBTcl_GetString\fR to ensure that the \fIbytes\fR field is populated. +This is highly unlikely to be useful to Tcl scripts, as Tcl's internal +encoding is not strict UTF\-8, but rather a modified CESU\-8 with a +denormalized NUL (identical to that used in a number of places by +Java's serialization mechanism) to enable basic processing with +non-Unicode-aware C functions. As this representation should only +ever be used by Tcl's implementation, the number of bytes used to +store the representation is of very low value (except to C extension +code, which has direct access for the purpose of memory management, +etc.) +.PP \fICompatibility note:\fR it is likely that this subcommand will be withdrawn in a future version of Tcl. It is better to use the \fBencoding convertto\fR command to convert a string to a known encoding and then apply \fBstring length\fR to that. +.PP +.CS +\fBstring length\fR [encoding convertto utf-8 $theString] +.CE .RE .TP \fBstring wordend \fIstring charIndex\fR diff --git a/doc/tcltest.n b/doc/tcltest.n index 8d2398b..29265be 100644 --- a/doc/tcltest.n +++ b/doc/tcltest.n @@ -642,14 +642,6 @@ This test can only be run on any Windows platform. . This test can only be run on any Windows NT platform. .TP -\fI95\fR -. -This test can only be run on any Windows 95 platform. -.TP -\fI98\fR -. -This test can only be run on any Windows 98 platform. -.TP \fImac\fR . This test can only be run on any Mac platform. diff --git a/doc/tclvars.n b/doc/tclvars.n index 2fec222..a8fba47 100644 --- a/doc/tclvars.n +++ b/doc/tclvars.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_library, tcl_nonwordchars, tcl_patchLevel, tcl_pkgPath, tcl_platform, tcl_precision, tcl_rcFileName, tcl_traceCompile, tcl_traceEval, tcl_wordchars, tcl_version \- Variables used by Tcl +argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_library, tcl_nonwordchars, tcl_patchLevel, tcl_pkgPath, tcl_platform, tcl_precision, tcl_rcFileName, tcl_traceCompile, tcl_traceExec, tcl_wordchars, tcl_version \- Variables used by Tcl .BE .SH DESCRIPTION .PP @@ -308,18 +308,13 @@ is the value returned by \fBuname -m\fR. \fBos\fR . The name of the operating system running on this machine, -such as \fBWindows 95\fR, \fBWindows NT\fR, or \fBSunOS\fR. +such as \fBWindows NT\fR or \fBSunOS\fR. On UNIX machines, this is the value returned by \fBuname -s\fR. -On Windows 95 and Windows 98, the value returned will be \fBWindows -95\fR to provide better backwards compatibility to Windows 95; to -distinguish between the two, check the \fBosVersion\fR. .TP \fBosVersion\fR . The version number for the operating system running on this machine. -On UNIX machines, this is the value returned by \fBuname -r\fR. On -Windows 95, the version will be 4.0; on Windows 98, the version will -be 4.10. +On UNIX machines, this is the value returned by \fBuname -r\fR. .TP \fBpathSeparator\fR .VS 8.6 @@ -347,8 +342,8 @@ was compiled with threads enabled. . This identifies the current user based on the login information available on the platform. -This comes from the USER or LOGNAME environment variable on Unix, -and the value from GetUserName on Windows. +This value comes from the getuid() and getpwuid() system calls on Unix, +and the value from the GetUserName() system call on Windows. .TP \fBwordSize\fR . |