diff options
Diffstat (limited to 'doc/SplitList.3')
| -rw-r--r-- | doc/SplitList.3 | 24 |
1 files changed, 19 insertions, 5 deletions
diff --git a/doc/SplitList.3 b/doc/SplitList.3 index b1a298d..fd6ec8b 100644 --- a/doc/SplitList.3 +++ b/doc/SplitList.3 @@ -32,7 +32,7 @@ int int \fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR) .SH ARGUMENTS -.AS "CONST char * CONST" ***argvPtr +.AS "const char *const" ***argvPtr out .AP Tcl_Interp *interp out Interpreter to use for error reporting. If NULL, then no error message is left. @@ -40,17 +40,17 @@ is left. Pointer to a string with proper list structure. .AP int *argcPtr out Filled in with number of elements in \fIlist\fR. -.AP "CONST char" ***argvPtr out +.AP "const char" ***argvPtr out \fI*argvPtr\fR will be filled in with the address of an array of pointers to the strings that are the extracted elements of \fIlist\fR. There will be \fI*argcPtr\fR valid entries in the array, followed by a NULL entry. .AP int argc in Number of elements in \fIargv\fR. -.AP "CONST char * CONST" *argv in +.AP "const char *const" *argv in Array of strings to merge together into a single list. Each string will become a separate element of the list. -.AP "CONST char" *src in +.AP "const char" *src in String that is to become an element of a list. .AP int *flagsPtr in Pointer to word to fill in with information about \fIsrc\fR. @@ -151,7 +151,7 @@ include spaces between adjacent list elements. \fBTcl_ConvertElement\fR uses one of two different approaches to handle the special characters in \fIsrc\fR. Wherever possible, it handles special characters by surrounding the string with braces. -This produces clean-looking output, but can't be used in some situations, +This produces clean-looking output, but cannot be used in some situations, such as when \fIsrc\fR contains unmatched braces. In these situations, \fBTcl_ConvertElement\fR handles special characters by generating backslash sequences for them. @@ -164,6 +164,20 @@ used to generate a portion of an argument for a Tcl command. In this case, surrounding \fIsrc\fR with curly braces would cause the command not to be parsed correctly. .PP +.VS 8.5 +By default, \fBTcl_ConvertElement\fR will use quoting in its output +to be sure the first character of an element is not the hash +character +.PQ # . +This is to be sure the first element of any list +passed to \fBeval\fR is not mis-parsed as the beginning of a comment. +When a list element is not the first element of a list, this quoting +is not necessary. When the caller can be sure that the element is +not the first element of a list, it can disable quoting of the leading +hash character by OR-ing the flag value returned by \fBTcl_ScanElement\fR +with \fBTCL_DONT_QUOTE_HASH\fR. +.VE 8.5 +.PP \fBTcl_ScanCountedElement\fR and \fBTcl_ConvertCountedElement\fR are the same as \fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR, except the length of string \fIsrc\fR is specified by the \fIlength\fR |