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:
-
@@ -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
+
+-
+
+regsub
now fully supports \A
+
+
+-
+
+Add socket
pty
to create a pseudo-tty pair
+
+
+-
+
+Null characters (\x00) are now supported in variable and proc names
+
+
+-
+
+dictionaries and arrays now preserve insertion order, matching Tcl and the documentation
+
+
+-
+
+Add dict
getwithdefault
(and the alias dict
getdef
) per TIP 342
+
+
+-
+
+Add string comparison operators (lt, gt, le, ge) per TIP 461
+
+
+-
+
+Implement 0d radix prefix for decimal per TIP 472
+
+
+
+
+
Changes between 0.78 and 0.79
-
@@ -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:]
,
-
-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
-
@@ -2346,11 +2398,6 @@ Backslash escapes may be used within regular expressions, such as
\n
-
-Partially supported constraint escapes: \A
= start of string, \Z
= end of string
-
-
-
-
-
Support for the ?
non-greedy quantifier. e.g. *?
@@ -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
+
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
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
-
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:
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.
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.
+
+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
+
+
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