diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/jim_tcl.txt | 118 |
1 files changed, 81 insertions, 37 deletions
diff --git a/doc/jim_tcl.txt b/doc/jim_tcl.txt index 185acc8..9c17aa7 100644 --- a/doc/jim_tcl.txt +++ b/doc/jim_tcl.txt @@ -2381,7 +2381,7 @@ the *value* arguments to that list as a separate element, with spaces between elements. If *varName* doesn't exist, it is created as a list with elements given -by the *value* arguments. 'Lappend' is similar to 'append' except that +by the *value* arguments. 'lappend' is similar to 'append' except that each *value* is appended as a list element rather than raw text. This command provides a relatively efficient way to build up large lists. @@ -2425,10 +2425,10 @@ linsert This command produces a new list from *list* by inserting all of the *element* arguments just before the element *index* -of *list*. Each *element* argument will become -a separate element of the new list. If *index* is less than +of *list*. Each *element* argument will become +a separate element of the new list. If *index* is less than or equal to zero, then the new elements are inserted at the -beginning of the list. If *index* is greater than or equal +beginning of the list. If *index* is greater than or equal to the number of elements in the list, then the new elements are appended to the list. @@ -2439,12 +2439,12 @@ list +*list* 'arg ?arg ...?'+ -This command returns a list comprised of all the arguments, *arg*. Braces +This command returns a list comprised of all the arguments, *arg*. Braces and backslashes get added as necessary, so that the 'index' command may be used on the result to re-extract the original arguments, and also so that 'eval' may be used to execute the resulting list, with *arg1* comprising the command's name and the other args comprising -its arguments. 'List' produces slightly different results than +its arguments. 'List' produces slightly different results than 'concat': 'concat' removes one level of grouping before forming the list, while 'list' works directly from the original arguments. For example, the command @@ -2474,8 +2474,8 @@ Sets an element in a list. The 'lset' command accepts a parameter, *varName*, which it interprets as the name of a variable containing a Tcl list. It also accepts -zero or more indices into the list. Finally, it accepts a new value -for an element of varName. If no indices are presented, the command +zero or more indices into the list. Finally, it accepts a new value +for an element of varName. If no indices are presented, the command takes the form: lset varName newValue @@ -2537,9 +2537,8 @@ lrange ~~~~~~ +*lrange* 'list first last'+ -*List* must be a valid Tcl list. This command will -return a new list consisting of elements -*first* through *last*, inclusive. +*List* must be a valid Tcl list. This command will return a new +list consisting of elements *first* through *last*, inclusive. See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *first* and *last*. @@ -2645,7 +2644,7 @@ the list are to be matched against pattern and must have one of the values below This negates the sense of the match, returning the index (or value if '-inline' is specified) of the first non-matching value in the list. If '-bool' is also specified, the '0' will be returned if a - match is found, or '1' otherwise. If '-all' is also specified, + match is found, or '1' otherwise. If '-all' is also specified, non-matches will be returned rather than matches. +'-nocase'+:: @@ -2688,19 +2687,19 @@ It may have any of the following values: already exist. +w+:: - Open the file for writing only. Truncate it if it exists. If it doesn't + Open the file for writing only. Truncate it if it exists. If it doesn't exist, create a new file. +w++:: - Open the file for reading and writing. Truncate it if it exists. + Open the file for reading and writing. Truncate it if it exists. If it doesn't exist, create a new file. +a+:: - Open the file for writing only. The file must already exist, and the file + Open the file for writing only. The file must already exist, and the file is positioned so that new data is appended to the file. +a++:: - Open the file for reading and writing. If the file doesn't + Open the file for reading and writing. If the file doesn't exist, create a new empty file. Set the initial access position to the end of the file. @@ -2742,13 +2741,13 @@ proc The 'proc' command creates a new Tcl command procedure, *name*. When the new command is invoked, the contents of *body* will be executed. -Tcl interpreter. *args* specifies the formal arguments to the procedure. +Tcl interpreter. *args* specifies the formal arguments to the procedure. If specified, *static*, declares static variables which are bound to the procedure. See PROCEDURES for detailed information about Tcl procedures. -The 'proc' command returns the null string. When a procedure is invoked, +The 'proc' command returns the null string. When a procedure is invoked, the procedure's return value is the value specified in a 'return' command. If the procedure doesn't execute an explicit 'return', then its return value is the value of the last command executed in the procedure's body. @@ -2763,7 +2762,7 @@ puts +'fileId' *puts* ?*-nonewline*? 'string'+ Writes the characters given by *string* to the file given -by *fileId*. *fileId* must have been the return +by *fileId*. *fileId* must have been the return value from a previous call to 'open', or it may be 'stdout' or 'stderr' to refer to one of the standard I/O channels; it must refer to a file that was opened for @@ -2834,7 +2833,7 @@ to 'open'; it must refer to a file that was opened for reading. regexp ~~~~~~ -+*regexp ?-indices? ?-nocase?* ?*-start* 'offset'? 'exp string ?matchVar? ?subMatchVar subMatchVar ...?'+ ++*regexp ?-nocase? ?-line? ?-indices? ?-start* 'offset'? *?-all? ?-inline? ?--?* 'exp string ?matchVar? ?subMatchVar subMatchVar ...?'+ Determines whether the regular expression *exp* matches part or all of *string* and returns 1 if it does, 0 if it doesn't. @@ -2846,14 +2845,15 @@ If additional arguments are specified after *string* then they are treated as the names of variables to use to return information about which part(s) of *string* matched *exp*. *matchVar* will be set to the range of *string* that -matched all of *exp*. The first *subMatchVar* will contain +matched all of *exp*. The first *subMatchVar* will contain the characters in *string* that matched the leftmost parenthesized subexpression within *exp*, the next *subMatchVar* will contain the characters that matched the next parenthesized subexpression to the right in *exp*, and so on. -Normally, *matchVar* and the each *subMatchVar* are set to hold -the matching characters from 'string', however see '-indices' below. +Normally, *matchVar* and the each *subMatchVar* are set to hold the +matching characters from 'string', however see '-indices' and +'-inline' below. If there are more values for *subMatchVar* than parenthesized subexpressions within *exp*, or if a particular subexpression in *exp* doesn't @@ -2865,9 +2865,17 @@ string otherwise. The following switches modify the behaviour of *regexp* +*-nocase*+:: - Causes upper-case characters in string to be treated as - lower case during the - matching process. + Causes upper-case and lower-case characters to be treated as + identical during the matching process. + ++*-line*+:: + Use newline-sensitive matching. By default, newline + is a completely ordinary character with no special meaning in + either REs or strings. With this flag, '[^' bracket expressions + and '.' never match newline, a '^' anchor matches the null + string after any newline in the string in addition to its normal + function, and the '$' anchor matches the null string before any + newline in the string in addition to its normal function. +*-indices*+:: Changes what is stored in the subMatchVars. Instead of @@ -2876,16 +2884,35 @@ The following switches modify the behaviour of *regexp* in string of the first and last characters in the matching range of characters. -+*-start* 'index'+:: - Specifies a character index offset into the string to start - matching the regular expression at. If '-indices' is ++*-start* 'offset'+:: + Specifies a character index offset into the string at which to start + matching the regular expression. If '-indices' is specified, the indices will be indexed starting from the - absolute beginning of the input string. index will be + absolute beginning of the input string. *offset* will be constrained to the bounds of the input string. ++*-all*+:: + Causes the regular expression to be matched as many times as possible + in the string, returning the total number of matches found. If this + is specified with match variables, they will contain information + for the last match only. + ++*-inline*+:: + Causes the command to return, as a list, the data that would otherwise + be placed in match variables. When using '-inline', match variables + may not be specified. If used with '-all', the list will be concatenated + at each iteration, such that a flat list is always returned. For + each match iteration, the command will append the overall match + data, plus one element for each subexpression in the regular + expression. + ++*--*+:: + Marks the end of switches. The argument following this one will be + treated as *exp* even if it starts with a +-+. + regsub ~~~~~~ -+*regsub ?-all? ?-nocase?* 'exp string subSpec ?varName?'+ ++*regsub ?-nocase? ?-all? ?-line? ?-start* 'offset'? ?*--*? 'exp string subSpec ?varName?'+ This command matches the regular expression *exp* against *string* using the rules described in REGULAR EXPRESSIONS @@ -2927,12 +2954,29 @@ The following switches modify the behaviour of *regsub* of *string*. +*-all*+:: - All ranges in - *string* that match *exp* are found and substitution is - performed for each of these ranges, rather than only the first. - The '&' and '{backslash}*n*' - sequences are handled for each substitution using the information - from the corresponding match. + All ranges in *string* that match *exp* are found and substitution + is performed for each of these ranges, rather than only the + first. The '&' and '{backslash}*n*' sequences are handled for + each substitution using the information from the corresponding + match. + ++*-line*+:: + Use newline-sensitive matching. By default, newline + is a completely ordinary character with no special meaning in + either REs or strings. With this flag, '[^' bracket expressions + and '.' never match newline, a '^' anchor matches the null + string after any newline in the string in addition to its normal + function, and the '$' anchor matches the null string before any + newline in the string in addition to its normal function. + ++*-start* 'offset'+:: + Specifies a character index offset into the string at which to + start matching the regular expression. *offset* will be + constrained to the bounds of the input string. + ++*--*+:: + Marks the end of switches. The argument following this one will be + treated as *exp* even if it starts with a +-+. ref ~~~ |