From a45b0c478600b710ed69fccefc3d3f06014cebc6 Mon Sep 17 00:00:00 2001 From: dgp Date: Fri, 7 Dec 2007 19:15:58 +0000 Subject: * doc/AddErrInfo.3: Documentation for the new routines in TIP 270. * doc/Interp.3: * doc/StringObj.3: --- ChangeLog | 6 +++ doc/AddErrInfo.3 | 20 +++++++++- doc/Interp.3 | 9 +++-- doc/StringObj.3 | 120 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 4 files changed, 143 insertions(+), 12 deletions(-) diff --git a/ChangeLog b/ChangeLog index 40f09cb..cf5c5e3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,11 @@ 2007-12-06 Don Porter + * doc/AddErrInfo.3: Documentation for the new routines in TIP 270. + * doc/Interp.3: + * doc/StringObj.3: + +2007-12-06 Don Porter + * doc/namespace.n: Documentation for zero-argument form of [namespace import] (TIP 261) [Bug 1596416] diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index 6fa5851..0594e21 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -5,13 +5,13 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: AddErrInfo.3,v 1.18 2007/10/29 11:28:49 dkf Exp $ +'\" RCS: @(#) $Id: AddErrInfo.3,v 1.19 2007/12/07 19:15:59 dgp Exp $ '\" .so man.macros .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options +Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options .SH SYNOPSIS .nf \fB#include \fR @@ -25,6 +25,10 @@ int .VE 8.5 .sp \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR) +.VS 8.5 +.sp +\fBTcl_AppendObjToErrorInfo\fR(\fIinterp, objPtr\fR) +.VE 8.5 .sp \fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR) .sp @@ -55,6 +59,11 @@ this points to the first byte of an array of \fIlength\fR bytes containing a string to append to the \fB\-errorinfo\fR return option. This byte array may contain embedded null bytes unless \fIlength\fR is negative. +.VS 8.5 +.AP Tcl_Obj *objPtr in +A message to be appended to the \fB\-errorinfo\fR return option +in the form of a Tcl_Obj value. +.VE 8.5 .AP int length in The number of bytes to copy from \fImessage\fR when appending to the \fB\-errorinfo\fR return option. @@ -200,6 +209,13 @@ The value of the \fB\-errorline\fR return option (retrieved via a call to \fBTcl_GetReturnOptions\fR) often makes up a useful part of the \fImessage\fR passed to \fBTcl_AddErrorInfo\fR. .PP +.VS 8.5 +\fBTcl_AppendObjToErrorInfo\fR is an alternative interface to the +same functionality as \fBTcl_AddErrorInfo\fR. \fBTcl_AppendObjToErrorInfo\fR +is called when the string value to be appended to the \fB\-errorinfo\fR option +is available as a \fBTcl_Obj\fR instead of as a \fBchar\fR array. +.VE 8.5 +.PP \fBTcl_AddObjErrorInfo\fR is nearly identical to \fBTcl_AddErrorInfo\fR, except that it has an additional \fIlength\fR argument. This allows the \fImessage\fR string to contain diff --git a/doc/Interp.3 b/doc/Interp.3 index 2b7d48a..b8cef9d 100644 --- a/doc/Interp.3 +++ b/doc/Interp.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Interp.3,v 1.11 2007/10/29 17:17:54 dgp Exp $ +'\" RCS: @(#) $Id: Interp.3,v 1.12 2007/12/07 19:15:59 dgp Exp $ '\" .so man.macros .TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures" @@ -34,8 +34,11 @@ on the interpreter. Interpreter structures contain many fields that are used by Tcl, but only three that may be accessed by clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR. .PP -\fBNote that access to the \fIresult\fB and \fIfreeProc\fB fields is\fR -\fBdeprecated.\fR Use \fBTcl_SetResult\fR and \fBTcl_GetResult\fR instead. +.VS 8.5 +\fBNote that access to all three fields, \fIresult\fB, \fIfreeProc\fB and +\fIerrorLine\fB is deprecated.\fR Use \fBTcl_SetResult\fR, +\fBTcl_GetResult\fR, and \fBTcl_GetReturnOptions\fR instead. +.VE 8.5 .PP The \fIresult\fR and \fIfreeProc\fR fields are used to return results or error messages from commands. diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 8b80b2a..9c22037 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -4,13 +4,13 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: StringObj.3,v 1.22 2007/10/29 17:17:54 dgp Exp $ +'\" RCS: @(#) $Id: StringObj.3,v 1.23 2007/12/07 19:15:59 dgp Exp $ '\" .so man.macros .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings +Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendObjToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl objects as strings .SH SYNOPSIS .nf \fB#include \fR @@ -62,6 +62,23 @@ void .sp void \fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR) +.VS 8.5 +.sp +void +\fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR) +.sp +Tcl_Obj * +\fBTcl_Format\fR(\fIinterp, format, objc, objv\fR) +.sp +int +\fBTcl_AppendFormatToObj\fR(\fIinterp, objPtr, format, objc, objv\fR) +.sp +Tcl_Obj * +\fBTcl_ObjPrintf\fR(\fIformat, ...\fR) +.sp +int +\fBTcl_AppendPrintfToObj\fR(\fIobjPtr, format, ...) +.VE 8.5 .sp void \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR) @@ -114,13 +131,20 @@ Null-terminated string value to append to \fIobjPtr\fR. .AP va_list argList in An argument list which must have been initialised using \fBva_start\fR, and cleared using \fBva_end\fR. +.AP int limit in +Maximum number of bytes to be appended. +.AP "const char" *ellipsis in +Suffix to append when the limit leads to string truncation. +If NULL is passed then the suffix "..." is used. +.AP "const char" *format in +Format control string including % conversion specifiers. +.AP int objc in +The number of elements to format or concatenate. +.AP Tcl_Obj *objv[] in +The array of objects to format or concatenate. .AP int newLength in New length for the string value of \fIobjPtr\fR, not including the final null character. -.AP int objc in -The number of elements to concatenate. -.AP Tcl_Obj *objv[] in -The array of objects to concatenate. .BE .SH DESCRIPTION @@ -229,6 +253,88 @@ must be a NULL pointer to indicate the end of the list. except that instead of taking a variable number of arguments it takes an argument list. .PP +.VS 8.5 +\fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR +except that it imposes a limit on how many bytes are appended. +This can be handy when the string to be appended might be +very large, but the value being constructed should not be allowed to grow +without bound. A common usage is when constructing an error message, where the +end result should be kept short enough to be read. +Bytes from \fIbytes\fR are appended to \fIobjPtr\fR, but no more +than \fIlimit\fR bytes total are to be appended. If the limit prevents +all \fIlength\fR bytes that are available from being appended, then the +appending is done so that the last bytes appended are from the +string \fIellipsis\fR. This allows for an indication of the truncation +to be left in the string. +When \fIlength\fR is \fB-1\fR, all bytes up to the first zero byte are appended, +subject to the limit. When \fIellipsis\fR is NULL, the default +string \fB...\fR is used. When \fIellipsis\fR is non-NULL, it must point +to a zero-byte-terminated string in Tcl's internal UTF encoding. +The number of bytes appended can be less than the lesser +of \fIlength\fR and \fIlimit\fR when appending fewer +bytes is necessary to append only whole multi-byte characters. +.PP +\fBTcl_Format\fR is the C-level interface to the engine of the \fBformat\fR +command. The actual command procedure for \fBformat\fR is little more +than +.CS +Tcl_Format(interp, Tcl_GetString(objv[1]), objc-2, objv+2); +.CE +The \fIobjc\fR Tcl_Obj values in \fIobjv\fR are formatted into a string +according to the conversion specification in \fIformat\fR argument, following +the documentation for the \fBformat\fR command. The resulting formatted +string is converted to a new Tcl_Obj with refcount of zero and returned. +If some error happens during production of the formatted string, NULL is +returned, and an error message is recorded in \fIinterp\fR, if \fIinterp\fR +is non-NULL. +.PP +\fBTcl_AppendFormatToObj\fR is an appending alternative form +of \fBTcl_Format\fR with functionality equivalent to +.CS +Tcl_Obj *newPtr = Tcl_Format(interp, format, objc, objv); +if (newPtr == NULL) return TCL_ERROR; +Tcl_AppendObjToObj(objPtr, newPtr); +return TCL_OK; +.CE +but with greater convenience and efficiency when the appending +functionality is needed. +.PP +\fBTcl_ObjPrintf\fR serves as a replacement for the common sequence +.CS +char buf[SOME_SUITABLE_LENGTH]; +sprintf(buf, format, ...); +Tcl_NewStringObj(buf, -1); +.CE +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 +not that of the \fBsprintf\fR routine where the two sets differ. When a +conversion specifier passed to \fBTcl_ObjPrintf\fR includes a precision, +the value is taken as a number of bytes, as \fBsprintf\fR does, and not +as a number of characters, as \fBformat\fR does. This is done on the +assumption that C code is more likely to know how many bytes it is +passing around than the number of encoded characters those bytes happen +to represent. The variable number of arguments passed in should be of +the types that would be suitable for passing to \fBsprintf\fR. Note in +this example usage, \fIx\fR is of type \fBlong\fR. +.CS +long x = 5; +Tcl_Obj *objPtr = Tcl_ObjPrintf("Value is %d", x); +.CE +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. +.PP +\fBTcl_AppendPrintfToObj\fR is an appending alternative form +of \fBTcl_ObjPrintf\fR with functionality equivalent to +.CS +Tcl_AppendObjToObj(objPtr, Tcl_ObjPrintf(format, ...)); +.CE +but with greater convenience and efficiency when the appending +functionality is needed. +.VE 8.5 +.PP The \fBTcl_SetObjLength\fR procedure changes the length of the string value of its \fIobjPtr\fR argument. If the \fInewLength\fR argument is greater than the space allocated for the object's @@ -265,7 +371,7 @@ cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a newly-created object whose ref count is zero. .SH "SEE ALSO" -Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount +Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount, format, sprintf .SH KEYWORDS append, internal representation, object, object type, string object, -- cgit v0.12