From c23f18c0ab0d6bbec0e6d0c7afaeb801e2b25917 Mon Sep 17 00:00:00 2001 From: Steve Bennett Date: Mon, 5 Oct 2020 09:47:01 +1000 Subject: bump version to 0.80 Update documentation to indicate v0.80 and update Tcl_shipped.html Signed-off-by: Steve Bennett --- Tcl_shipped.html | 369 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 231 insertions(+), 138 deletions(-) (limited to 'Tcl_shipped.html') diff --git a/Tcl_shipped.html b/Tcl_shipped.html index e27ed2f..7852fc1 100644 --- a/Tcl_shipped.html +++ b/Tcl_shipped.html @@ -739,7 +739,7 @@ Jim Tcl(n) Manual Page

NAME

-

Jim Tcl v0.79 - +

Jim Tcl v0.80 - reference manual for the Jim Tcl scripting language

@@ -791,7 +791,7 @@ jimsh --help The core language engine is compatible with Tcl 8.5+, while implementing a significant subset of the Tcl 8.6 command set, plus additional features available only in Jim Tcl.

-

Some notable differences with Tcl 8.5/8.6 are:

+

Some notable differences with Tcl 8.5/8.6/8.7 are:

  1. @@ -880,6 +880,46 @@ Support for UDP, IPv6, Unix-Domain sockets in addition to TCP sockets

    RECENT CHANGES

    +

    Changes between 0.79 and 0.80

    +
      +
    1. +

      +regsub now fully supports \A +

      +
      2. +
    2. +

      +Add socket pty to create a pseudo-tty pair +

      +
      3. +
    3. +

      +Null characters (\x00) are now supported in variable and proc names +

      +
      4. +
    4. +

      +dictionaries and arrays now preserve insertion order, matching Tcl and the documentation +

      +
      5. +
    5. +

      +Add dict getwithdefault (and the alias dict getdef) per TIP 342 +

      +
      6. +
    6. +

      +Add string comparison operators (lt, gt, le, ge) per TIP 461 +

      +
      7. +
    7. +

      +Implement 0d radix prefix for decimal per TIP 472 +

      +
      8. +
    +
    +

    Changes between 0.78 and 0.79

    1. @@ -1842,9 +1882,10 @@ and parentheses.

    White space may be used between the operands and operators and parentheses; it is ignored by the expression processor. Where possible, operands are interpreted as integer values.

    -

    Integer values may be specified in decimal (the normal case) or in -hexadecimal (if the first two characters of the operand are 0x). -Note that Jim Tcl does not treat numbers with leading zeros as octal.

    +

    Integer values are interpreted as decimal, binary, octal or +hexadecimal if prepended with 0d, 0b, 0o or 0x +respectively. Otherwise they are interpreted as decimal by default. +(Jim Tcl does not interpret numbers with leading zeros as octal.)

    If an operand does not have one of the integer formats given above, then it is treated as a floating-point number if that is possible. Floating-point numbers may be specified in any of the @@ -2032,6 +2073,17 @@ of precedence:

    +lt gt le ge +
    +
    +

    + Boolean less, greater, less than or equal, and greater than or equal. + Each operator produces 1 if the condition is true, 0 otherwise. + These operators differ from the above in that they use string comparison + for all operands, including numeric. +

    +
    +
    == !=
    @@ -2288,7 +2340,7 @@ for backward compatibility with experimental versions of this feature.

    REGULAR EXPRESSIONS

    -

    Tcl provides two commands that support string matching using regular +

    Jim Tcl provides two commands that support string matching using regular expressions, regexp and regsub, as well as switch -regexp and lsearch -regexp.

    Regular expressions may be implemented one of two ways. Either using the system’s C library @@ -2336,7 +2388,7 @@ Supported shorthand character classes: \w = [:alnum:],

  2. -Supported constraint escapes: \m = \< = start of word, \M = \> = end of word +Supported constraint escapes: \m = \< = start of word, \M = \> = end of word, \A = start of string, \Z = end of string

  3. @@ -2346,11 +2398,6 @@ Backslash escapes may be used within regular expressions, such as \n

  4. -Partially supported constraint escapes: \A = start of string, \Z = end of string -

    -
    5. -
  5. -

    Support for the ? non-greedy quantifier. e.g. *?

    6. @@ -2369,6 +2416,56 @@ Jim Tcl considers that both patterns and strings end at a null character (
+

STRING MATCHING

+
+

A number of commands in Jim support C-shell style "glob matching", including +string match, switch -glob, array names and others. This form of string matching +works as follows:

+

A test occurs where a string is matched against a pattern. The match is considered +successful if the contents of string and pattern are identical except that the +following special sequences may appear in pattern:

+
+
+* +
+
+

+ Matches any sequence of characters in string, including an empty string. +

+
+
+? +
+
+

+ Matches any single character in string. +

+
+
+[chars] +
+
+

+ Matches any character in the set given by chars. + If a sequence of the form x-y appears in chars, + then any character between x and y, inclusive, + will match. +

+
+
+\x +
+
+

+ Matches the single character x. This provides a way of + avoiding the special interpretation of the characters \*?[] + in pattern. +

+
+
+
+
+

COMMAND RESULTS

Each command produces two results: a code and a string. The @@ -2936,9 +3033,9 @@ and string bytelength is still available to embed UTF-8 sequences.

Jim Tcl supports all currently defined unicode codepoints. That is 21 bits, up to +U+1FFFFF.

-

String Matching

-

Commands such as string match, lsearch -glob, array names and others use string -pattern matching rules. These commands support UTF-8. For example:

+

String Matching

+

Commands such as string match, lsearch -glob, array names and others use +STRING MATCHING rules. These commands support UTF-8. For example:

  string match a\[\ua0-\ubf\]b "a\u00a3b"
@@ -3244,10 +3341,10 @@ For example, "append

apply

apply lambdaExpr ?arg1 arg2 ...?

The command apply provides for anonymous procedure calls, -similar to lambda, but without command name being created, even temporarily.

-

The function lambdaExpr is a two element list {args body} -or a three element list {args body namespace}. The first element -args specifies the formal arguments, in the same form as the proc and lambda commands.

+similar to lambda, but without a command name being created, even temporarily.

+

The function lambdaExpr is a two element list, {args body} +or a three element list, {args body namespace}. The first element +args specifies the formal arguments in the same form as the proc and lambda commands.

array

@@ -3264,7 +3361,7 @@ command. The legal options (which may be abbreviated) are

- Returns 1 if arrayName is an array variable, 0 if there is + Returns 1 if arrayName is an array variable, 0 if there is no variable by that name.

@@ -3274,13 +3371,13 @@ command. The legal options (which may be abbreviated) are

Returns a list containing pairs of elements. The first - element in each pair is the name of an element in arrayName + element in each pair is the name of an element in arrayName and the second element of each pair is the value of the array element. The order of the pairs is undefined. If - pattern is not specified, then all of the elements of the - array are included in the result. If pattern is specified, - then only those elements whose names match pattern (using - the matching rules of string match) are included. If arrayName + pattern is not specified, then all of the elements of the + array are included in the result. If pattern is specified, + then only those elements whose names match pattern (using + STRING MATCHING rules) are included. If arrayName isn’t the name of an array variable, or if the array contains no elements, then an empty list is returned.

@@ -3291,12 +3388,12 @@ command. The legal options (which may be abbreviated) are

Returns a list containing the names of all of the elements - in the array that match pattern. If pattern is omitted then + in the array that match pattern. If pattern is omitted then the command returns all of the element names in the array. - If pattern is specified, then only those elements whose - names match pattern (using the matching rules of string - match) are included. If there are no (matching) elements - in the array, or if arrayName isn’t the name of an array + If pattern is specified, then only those elements whose + names match pattern (using STRING MATCHING rules) + are included. If there are no (matching) elements + in the array, or if arrayName isn’t the name of an array variable, then an empty string is returned.

@@ -3305,13 +3402,13 @@ command. The legal options (which may be abbreviated) are

- Sets the values of one or more elements in arrayName. list + Sets the values of one or more elements in arrayName. list must have a form like that returned by array get, consisting of an even number of elements. Each odd-numbered element in list is treated as an element name within arrayName, and the following element in list is used as a new value for - that array element. If the variable arrayName does not - already exist and list is empty, arrayName is created with + that array element. If the variable arrayName does not + already exist and list is empty, arrayName is created with an empty array value.

@@ -3320,7 +3417,7 @@ command. The legal options (which may be abbreviated) are

- Returns the number of elements in the array. If arrayName + Returns the number of elements in the array. If arrayName isn’t the name of an array then 0 is returned.

@@ -3329,11 +3426,11 @@ command. The legal options (which may be abbreviated) are

- Unsets all of the elements in the array that match pattern - (using the matching rules of string match). If arrayName + Unsets all of the elements in the array that match pattern + (using STRING MATCHING rules). If arrayName isn’t the name of an array variable or there are no matching - elements in the array, no error will be raised. If pattern - is omitted and arrayName is an array variable, then the + elements in the array, no error will be raised. If pattern + is omitted and arrayName is an array variable, then the command unsets the entire array. The command always returns an empty string.

@@ -3459,7 +3556,7 @@ be removed in some applications.

If boolean is true, processing is performed in UTC. - If boolean is false (the default), processing is performeed in the local time zone. + If boolean is false (the default), processing is performed in the local time zone.

@@ -3473,6 +3570,8 @@ be removed in some applications.

+

NOTE Some systems such as 32-bit Linux have only a 32-bit time_t, and are therefore not year 2038 +compliant.

close

@@ -3579,14 +3678,31 @@ command. The legal options are:

+dict getdef dictionary ?key ...? key default +
+
+

+ Alias for dict getwithdefault. +

+
+
+dict getwithdefault dictionary ?key ...? key default +
+
+

+ Similar to dict get except if no value exists in the dictionary for the + give key(s), returns default instead. +

+
+
dict keys dictionary ?pattern?

Returns a list of the keys in the dictionary. - If pattern is specified, then only those keys whose - names match pattern (using the matching rules of string - match) are included. + If pattern is specified, then only those keys whose + names match pattern (using STRING MATCHING rules) + are included.

@@ -4511,8 +4627,7 @@ The legal option's (which may be abbreviated) are: Tcl commands, including both the built-in commands written in C and the command procedures defined using the proc command. If pattern is specified, only those names matching pattern - are returned. Matching is determined using the same rules as for - string match. + (using STRING MATCHING rules) are returned.

@@ -4564,8 +4679,7 @@ The legal option's (which may be abbreviated) are: If pattern isn’t specified, returns a list of all the names of currently-defined global variables. If pattern is specified, only those names matching pattern - are returned. Matching is determined using the same rules as for - string match. + (using STRING MATCHING rules) are returned.

@@ -4603,8 +4717,8 @@ The legal option's (which may be abbreviated) are: of currently-defined local variables, including arguments to the current procedure, if any. Variables defined with the global and upvar commands will not be returned. If pattern is - specified, only those names matching pattern are returned. - Matching is determined using the same rules as for string match. + specified, only those names matching pattern + (using STRING MATCHING rules) are returned.

@@ -4625,8 +4739,7 @@ The legal option's (which may be abbreviated) are: If pattern isn’t specified, returns a list of all the names of Tcl command procedures. If pattern is specified, only those names matching pattern - are returned. Matching is determined using the same rules as for - string match. + (using STRING MATCHING rules) are returned.

@@ -4709,8 +4822,7 @@ The legal option's (which may be abbreviated) are: returns a list of all the names of currently-visible variables, including both locals and currently-visible globals. If pattern is specified, only those names matching pattern - are returned. Matching is determined using the same rules as for - string match. + (using STRING MATCHING rules) are returned.

@@ -4808,12 +4920,12 @@ than variables, a list of unassigned elements is returned.

local

local cmd ?arg...?

First, local evaluates cmd with the given arguments. The return value must -be the name of an existing command, which is marked as having local scope. +be the name of an existing command, which is then marked as having local scope. This means that when the current procedure exits, the specified command is deleted. This can be useful with lambda, local procedures or to automatically close a filehandle.

-

In addition, if a command already exists with the same name, -the existing command will be kept rather than deleted, and may be called +

In addition, if a the command already exists with the same name, +the existing command will be kept rather than being deleted, and may be called via upcall. The previous command will be restored when the current procedure exits. See upcall for more details.

In this example, a local procedure is created. Note that the procedure @@ -4845,16 +4957,18 @@ than waiting until garbage collection.

... }
+

Also see defer as another mechanism for cleaning up at the end of a procedure.

loop

loop var first limit ?incr? body

Similar to for except simpler and possibly more efficient. -With a positive increment, equivalent to:

+If incr is positive, the effect is, equivalent to:

    for {set var $first} {$var < $limit} {incr var $incr} $body
+

While if incr is negative, the count is downwards.

If incr is not specified, 1 is used. Note that setting the loop variable inside the loop does not affect the loop count.

@@ -4918,8 +5032,7 @@ For example, the command

llength

llength list

-

Treats list as a list and returns a decimal string giving -the number of elements in it.

+

Treats list as a list and returns the number of elements in that list.

lset

@@ -4928,26 +5041,26 @@ the number of elements in it.

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 +for an element of varName. If no indices are presented, the command takes the form:

    lset varName newValue

In this case, newValue replaces the old value of the variable -varName.

+varName.

When presented with a single index, the lset command -treats the content of the varName variable as a Tcl list. It addresses +treats the content of the varName variable as a Tcl list. It addresses the index’th element in it (0 refers to the first element of the list). When interpreting the list, lset observes the same rules concerning braces and quotes and backslashes as the Tcl command interpreter; however, variable substitution and command substitution do not occur. The command constructs a new list in which the designated element is replaced with newValue. This new list is -stored in the variable varName, and is also the return value from +stored in the variable varName, and is also the return value from the lset command.

If index is negative or greater than or equal to the number of -elements in $varName, then an error occurs.

+elements in $varName, then an error occurs.

See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for index.

If additional index arguments are supplied, then each argument is used in turn to address an element within a sublist designated by @@ -5068,8 +5181,8 @@ the list are to be matched against pattern and must have one of the values below

- pattern is a glob-style pattern which is matched against each list element using the same - rules as the string match command. + pattern is a glob-style pattern which is matched against each list element using + STRING MATCHING rules.

@@ -5078,7 +5191,7 @@ the list are to be matched against pattern and must have one of the values below

pattern is treated as a regular expression and matched against each list element using - the rules described by regexp. + REGULAR EXPRESSIONS rules.

@@ -5269,10 +5382,11 @@ forming the command pipeline.

package

package provide name ?version?

Indicates that the current script provides the package named name. -If no version is specified, 1.0 is used.

-

Any script which provides a package may include this statement +Note: The supplied version is ignored. All packages are registered as version 1.0 +(it is simply accepted for compatibility purposes).

+

Any script that provides a package may include this statement as the first statement, although it is not required.

-

package require name ?version?*

+

package require name ?version?

Searches for the package with the given name by examining each path in $::auto_path and trying to load $path/$name.so as a dynamic extension, or $path/$name.tcl as a script package.

@@ -5282,6 +5396,8 @@ or $path/$name.tcl as a script package.

otherwise if $name.tcl exists it is loaded with the source command.

If load or source fails, package require will fail immediately. No further attempt will be made to locate the file.

+

package names

+

Returns a list of all known/loaded packages, including internal packages.

pid

@@ -5377,6 +5493,8 @@ and ranging up to but not including end in steps of

fileId read ?-nonewline?

read fileId numBytes

fileId read numBytes

+

read ?-pending? fileId

+

fileId read ?-pending?

In the first form, all of the remaining bytes are read from the file given by fileId; they are returned as the result of the command. If the -nonewline switch is specified then the last @@ -5385,6 +5503,19 @@ character of the file is discarded if it is a newline.

exactly this many bytes will be read and returned, unless there are fewer than numBytes bytes left in the file; in this case, all the remaining bytes are returned.

+

The third form is currently only useful with SSL sockets. It reads at least 1 byte +and then any additional data that is buffered. This allows for use in an event handler. +e.g.

+
+
+
    $sock readable {
+        set buf [$sock read -pending]
+    }
+
+

This is necessary because otherwise pending data may be buffered, but +the underlying socket will not be marked readable. This featured is not +currently supported for regular sockets, and so these sockets must be +set to unbufferred ($sock buffering false) to work in an event loop.

fileId must be stdin or the return value from a previous call to open; it must refer to a file that was opened for reading.

@@ -5432,9 +5563,9 @@ string otherwise.

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, an anchor matches the null + and . never match newline, an anchor matches the empty string after any newline in the string in addition to its normal - function, and the $ anchor matches the null string before any + function, and the $ anchor matches the empty string before any newline in the string in addition to its normal function.

@@ -5559,9 +5690,9 @@ backslashes.

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, an anchor matches the null + and . never match newline, an anchor matches the empty string after any newline in the string in addition to its normal - function, and the $ anchor matches the null string before any + function, and the $ anchor matches the empty string before any newline in the string in addition to its normal function.

@@ -6233,59 +6364,10 @@ Any hexadecimal digit character ([0-9A-Fa-f]).

- See if pattern matches string; return 1 if it does, 0 - if it doesn’t. Matching is done in a fashion similar to that - used by the C-shell. For the two strings to match, their contents - must be identical except that the following special sequences - may appear in pattern: -

-
-
-* -
-
-

- Matches any sequence of characters in string, - including a null string. -

-
-
-? -
-
-

- Matches any single character in string. -

-
-
-[chars] -
-
-

- Matches any character in the set given by chars. - If a sequence of the form x-y appears in chars, - then any character between x and y, inclusive, - will match. -

-
-
-\x -
-
-

- Matches the single character x. This provides a way of - avoiding the special interpretation of the characters \*?[] - in pattern. -

-
-
-
-
- -
-
-

- Performs a case-insensitive comparison if -nocase is specified. + See if pattern matches string according to + STRING MATCHING rules + ; return 1 if it does, 0 + if it doesn’t. The match is performed in a case-insensitive manner if -nocase is specified.

@@ -6469,8 +6551,7 @@ as options. The following options are currently supported:

When matching string to the patterns, use glob-style - matching (i.e. the same as implemented by the string - match command). + STRING MATCHING rules.

@@ -6478,9 +6559,8 @@ as options. The following options are currently supported:

- When matching string to the patterns, use regular - expression matching (i.e. the same as implemented - by the regexp command). + When matching string to the patterns, use + REGULAR EXPRESSIONS rules.

@@ -6987,11 +7067,11 @@ what options were selected when Jim Tcl was built.

-$handle read ?-nonewline? ?len? +$handle read ?-nonewline|-pending|len?'

- Read and return bytes from the stream. To eof if no len. + Read and return bytes from the stream. To eof if no len. See read.

@@ -7068,7 +7148,7 @@ what options were selected when Jim Tcl was built.

If no arguments are given, returns a dictionary containing the tty settings for the stream. If arguments are given, they must either be a dictionary, or setting value ... - Abbrevations are supported for both settings and values, so the following is acceptable: + Abbreviations are supported for both settings and values, so the following is acceptable: $f tty parity e input c out raw. Only available on platforms that support termios(3). Supported settings are:

@@ -7158,11 +7238,15 @@ what options were selected when Jim Tcl was built.

-$handle ssl ?-server cert priv? +$handle ssl ?-server cert ?key?|-sni servername?

Upgrades the stream to a SSL/TLS session and returns the handle. + If -server is specified, either both the certificate and private key files + must be specified, or a single file must be specified containing both. + If -server is not specified, the connection is a client connection. In this case + -sni may be specified if required to set the Server Name Indication.

@@ -7439,6 +7523,15 @@ to prevent infinite errors. (A time event handler is always removed after execut a list of two channels: {s1 s2}. These channels are both readable and writable.

+
+socket pty +
+
+

+ A pseudo-tty pair (see openpty(3)). Like pipe, this command returns + a list of two channels: {master slave}. These channels are both readable and writable. +

+

This command creates a socket connected (client) or bound (server) to the given address.

@@ -7606,7 +7699,7 @@ uucp, local0-local7

Decompresses a raw, Deflate-compressed stream. When the uncompressed data size is known and specified, memory - allocation is more efficient. Otherwise, decomperssion is chunked and therefore slower. + allocation is more efficient. Otherwise, decompression is chunked and therefore slower.

@@ -8037,7 +8130,7 @@ independently (but synchronously) of the main interpreter.

Creates and returns a new interpreter object (command). - The created interpeter contains any built-in commands along with static extensions, + The created interpreter contains any built-in commands along with static extensions, but does not include any dynamically loaded commands (package require, load). These must be reloaded in the child interpreter if required.

@@ -8047,7 +8140,7 @@ independently (but synchronously) of the main interpreter.

- Deletes the interpeter object. + Deletes the interpreter object.

-- cgit v1.1