diff options
| -rw-r--r-- | Tcl_shipped.html | 205 | ||||
| -rw-r--r-- | jim_tcl.txt | 60 |
2 files changed, 175 insertions, 90 deletions
diff --git a/Tcl_shipped.html b/Tcl_shipped.html index 9168e7c..da333b4 100644 --- a/Tcl_shipped.html +++ b/Tcl_shipped.html @@ -554,7 +554,7 @@ Jim Tcl(n) Manual Page </h1>
<h2>NAME</h2>
<div class="sectionbody">
-<p>Jim Tcl v0.71 -
+<p>Jim Tcl v0.72 -
overview of the Jim tool command language facilities
</p>
</div>
@@ -683,6 +683,36 @@ Expression shorthand syntax: <tt>$(…)</tt> <h2 id="_recent_changes">RECENT CHANGES</h2>
<div class="sectionbody">
<div class="sect2">
+<h3 id="_changes_between_0_71_and_0_72">Changes between 0.71 and 0.72</h3>
+<div class="olist arabic"><ol class="arabic">
+<li>
+<p>
+procs now allow <em>args</em> and optional parameters in any position
+</p>
+</li>
+<li>
+<p>
+Add Tcl-compatible expr functions, <em>rand()</em> and <em>srand()</em>
+</p>
+</li>
+<li>
+<p>
+Add support for the <em>-force</em> option to <em>file delete</em>
+</p>
+</li>
+<li>
+<p>
+Better diagnostics when <em>source</em> fails to load a script with a missing quote or bracket
+</p>
+</li>
+<li>
+<p>
+New <tt>tcl_platform(pathSeparator)</tt>
+</p>
+</li>
+</ol></div>
+</div>
+<div class="sect2">
<h3 id="_changes_between_0_70_and_0_71">Changes between 0.70 and 0.71</h3>
<div class="olist arabic"><ol class="arabic">
<li>
@@ -1606,15 +1636,18 @@ on the right side of the line:</p></div> of precedence:</p></div>
<div class="dlist" id="OperatorPrecedence"><dl>
<dt class="hdlist1">
-<tt>int() double() round() abs()</tt>
+<tt>int() double() round() abs(), rand(), srand()</tt>
</dt>
<dd>
<p>
- Unary functions.
+ Unary functions (except rand() which takes no arguments)
int() converts the numeric argument to an integer by truncating down.
double() converts the numeric argument to floating point.
round() converts the numeric argument to the closest integer value.
abs() takes the absolute value of the numeric argument.
+ rand() takes the absolute value of the numeric argument.
+ rand() returns a pseudo-random floating-point value in the range (0,1).
+ srand() takes an integer argument to (re)seed the random number generator. Returns the first random number from that seed.
</p>
</dd>
<dt class="hdlist1">
@@ -2111,12 +2144,12 @@ The only difference is that its body isn’t a piece of C code linked into the program; it is a string containing one or more other
Tcl commands.</p></div>
<div class="paragraph"><p>The <em>proc</em> command is used to create a new Tcl command procedure:</p></div>
-<div class="paragraph"><p><tt><strong>proc</strong> <em>name args ?statics? body</em></tt></p></div>
+<div class="paragraph"><p><tt><strong>proc</strong> <em>name arglist ?statics? body</em></tt></p></div>
<div class="paragraph"><p>The new command is name <strong>name</strong>, and it replaces any existing command
there may have been by that name. Whenever the new command is
invoked, the contents of <strong>body</strong> will be executed by the Tcl
interpreter.</p></div>
-<div class="paragraph"><p><strong>args</strong> specifies the formal arguments to the procedure.
+<div class="paragraph"><p><strong>arglist</strong> specifies the formal arguments to the procedure.
It consists of a list, possibly empty, of the following
argument specifiers:</p></div>
<div class="dlist"><dl>
@@ -2154,7 +2187,7 @@ argument specifiers:</p></div> <dd>
<p>
Variable Argument - The special name <strong>args</strong>, which is
- assigned all remaining arguments (including none). The
+ assigned all remaining arguments (including none) as a list. The
variable argument may only be specified once. Note that
the syntax <tt>args newname</tt> may be used to retain the special
behaviour of <strong>args</strong> with a different local name. In this case,
@@ -2162,30 +2195,6 @@ argument specifiers:</p></div> </p>
</dd>
</dl></div>
-<div class="paragraph"><p>Arguments must be provided in the following order, any of which
-may be omitted:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Required Arguments (Left)
-</p>
-</li>
-<li>
-<p>
-Optional Arguments
-</p>
-</li>
-<li>
-<p>
-Variable Argument
-</p>
-</li>
-<li>
-<p>
-Required Arguments (Right)
-</p>
-</li>
-</ol></div>
<div class="paragraph"><p>When the command is invoked, a local variable will be created for each of
the formal arguments to the procedure; its value will be the value
of corresponding argument in the invoking command or the argument’s
@@ -2194,31 +2203,98 @@ default value.</p></div> invocation. However, there must be enough actual arguments for all
required arguments, and there must not be any extra actual arguments
(unless the Variable Argument is specified).</p></div>
-<div class="paragraph"><p>Actual arguments are assigned to formal arguments as follows:</p></div>
+<div class="paragraph"><p>Actual arguments are assigned to formal arguments as in left-to-right
+order with the following precedence.</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
-Left Required Arguments are assigned from the left
+Required Arguments (including Reference Arguments)
</p>
</li>
<li>
<p>
-Right Required Arguments are assigned from the right
-</p>
-</li>
-<li>
-<p>
-Default Arguments are assigned from the left, following the Left Required Arguments.
+Optional Arguments
</p>
</li>
<li>
<p>
-A list is formed from any remaining arguments, which are then
- are assigned to the <em>args</em> Variable Argument (if specified). The list will be empty
- if there are no remaining arguments.
+Variable Argument
</p>
</li>
</ol></div>
+<div class="paragraph"><p>The following example illustrates precedence. Assume a procedure declaration:</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><tt>proc p {{a A} args b {c C} d} {...}</tt></pre>
+</div></div>
+<div class="paragraph"><p>This procedure requires at least two arguments, but can accept an unlimited number.
+The following table shows how various numbers of arguments are assigned.
+Values marked as <em>-</em> are assigned the default value.</p></div>
+<div class="tableblock">
+<table rules="all"
+width="40%"
+frame="hsides"
+cellspacing="0" cellpadding="4">
+<col width="16%" />
+<col width="16%" />
+<col width="16%" />
+<col width="16%" />
+<col width="16%" />
+<col width="16%" />
+<thead>
+<tr>
+<th align="left" valign="top">Number of arguments</th>
+<th align="left" valign="top">a</th>
+<th align="left" valign="top">args</th>
+<th align="left" valign="top">b</th>
+<th align="left" valign="top">c</th>
+<th align="left" valign="top">d</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="left" valign="top"><p class="table">2</p></td>
+<td align="left" valign="top"><p class="table">-</p></td>
+<td align="left" valign="top"><p class="table">-</p></td>
+<td align="left" valign="top"><p class="table">1</p></td>
+<td align="left" valign="top"><p class="table">-</p></td>
+<td align="left" valign="top"><p class="table">2</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">3</p></td>
+<td align="left" valign="top"><p class="table">1</p></td>
+<td align="left" valign="top"><p class="table">-</p></td>
+<td align="left" valign="top"><p class="table">2</p></td>
+<td align="left" valign="top"><p class="table">-</p></td>
+<td align="left" valign="top"><p class="table">3</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">4</p></td>
+<td align="left" valign="top"><p class="table">1</p></td>
+<td align="left" valign="top"><p class="table">-</p></td>
+<td align="left" valign="top"><p class="table">2</p></td>
+<td align="left" valign="top"><p class="table">3</p></td>
+<td align="left" valign="top"><p class="table">4</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">5</p></td>
+<td align="left" valign="top"><p class="table">1</p></td>
+<td align="left" valign="top"><p class="table">2</p></td>
+<td align="left" valign="top"><p class="table">3</p></td>
+<td align="left" valign="top"><p class="table">4</p></td>
+<td align="left" valign="top"><p class="table">5</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">6</p></td>
+<td align="left" valign="top"><p class="table">1</p></td>
+<td align="left" valign="top"><p class="table">2,3</p></td>
+<td align="left" valign="top"><p class="table">4</p></td>
+<td align="left" valign="top"><p class="table">5</p></td>
+<td align="left" valign="top"><p class="table">6</p></td>
+</tr>
+</tbody>
+</table>
+</div>
<div class="paragraph"><p>When <strong>body</strong> is being executed, variable names normally refer to local
variables, which are created automatically when referenced and deleted
when the procedure returns. One local variable is automatically created
@@ -3111,7 +3187,7 @@ if {[$e var]} { command. The legal <strong>options</strong> are:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<strong>dict create</strong> <em>?key value …?</em>+
+<tt><strong>dict create</strong> <em>?key value …?</em></tt>
</dt>
<dd>
<p>
@@ -3122,7 +3198,7 @@ command. The legal <strong>options</strong> are:</p></div> </p>
</dd>
<dt class="hdlist1">
-<strong>dict exists</strong> <em>dictionary key ?key …?</em>+
+<tt><strong>dict exists</strong> <em>dictionary key ?key …?</em></tt>
</dt>
<dd>
<p>
@@ -3133,7 +3209,7 @@ command. The legal <strong>options</strong> are:</p></div> </p>
</dd>
<dt class="hdlist1">
-<strong>dict get</strong> <em>dictionary ?key …?</em>+
+<tt><strong>dict get</strong> <em>dictionary ?key …?</em></tt>
</dt>
<dd>
<p>
@@ -3151,7 +3227,7 @@ command. The legal <strong>options</strong> are:</p></div> </p>
</dd>
<dt class="hdlist1">
-<strong>dict keys</strong> <em>dictionary ?pattern?</em>+
+<tt><strong>dict keys</strong> <em>dictionary ?pattern?</em></tt>
</dt>
<dd>
<p>
@@ -3162,7 +3238,7 @@ command. The legal <strong>options</strong> are:</p></div> </p>
</dd>
<dt class="hdlist1">
-<strong>dict keys</strong> <em>dictionary ?pattern?</em>+
+<tt><strong>dict keys</strong> <em>dictionary ?pattern?</em></tt>
</dt>
<dd>
<p>
@@ -3173,7 +3249,7 @@ command. The legal <strong>options</strong> are:</p></div> </p>
</dd>
<dt class="hdlist1">
-<strong>dict set</strong> <em>dictionaryName key ?key …? value</em>+
+<tt><strong>dict set</strong> <em>dictionaryName key ?key …? value</em></tt>
</dt>
<dd>
<p>
@@ -3185,7 +3261,7 @@ command. The legal <strong>options</strong> are:</p></div> </p>
</dd>
<dt class="hdlist1">
-<strong>dict unset</strong> <em>dictionaryName key ?key …? value</em>+
+<tt><strong>dict unset</strong> <em>dictionaryName key ?key …? value</em></tt>
</dt>
<dd>
<p>
@@ -3530,12 +3606,14 @@ abbreviation for <strong>option</strong> is acceptable. The valid options are:< </p>
</dd>
<dt class="hdlist1">
-<tt><strong>file delete</strong> <em>name …</em></tt>
+<tt><strong>file delete ?-force?</strong> <em>name …</em></tt>
</dt>
<dd>
<p>
Deletes file or directory <strong>name</strong>. If the file or directory doesn’t exist, nothing happens.
- If it can’t be deleted, an error is generated. Non-empty directories will not be deleted.
+ If it can’t be deleted, an error is generated. Non-empty directories will not be deleted
+ unless the <em>-force</em> options is given. In this case no errors will be generated, even
+ if the file/directory can’t be deleted.
</p>
</dd>
<dt class="hdlist1">
@@ -4095,10 +4173,8 @@ The legal <strong>option</strong>'s (which may be abbreviated) are: <dd>
<p>
Returns the name of the binary file from which the application
- was invoked, either
- as a path relative to the current directory or as a full
- path. If the path can’t be determined, returns the empty
- string.
+ was invoked. A full path will be returned, unless the path
+ can’t be determined, in which case the empty string will be returned.
</p>
</dd>
<dt class="hdlist1">
@@ -5306,7 +5382,7 @@ same form as produced by <em>catch</em> and <em>info stacktrace</em></p></div> The legal options (which may be abbreviated) are:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>*string bytelength <em>string</em></tt>
+<tt><strong>string bytelength</strong> <em>string</em></tt>
</dt>
<dd>
<p>
@@ -6471,11 +6547,11 @@ to prevent infinite errors. (A time event handler is always removed after execut </p>
</dd>
<dt class="hdlist1">
-<tt>*socket ?-ipv6? stream.server <em>?addr:?port</em></tt>
+<tt><strong>socket ?-ipv6? stream.server</strong> <em>?addr:?port</em></tt>
</dt>
<dd>
<p>
- A TCP socket server (<strong>addr</strong> defaults to 0.0.0.0 for IPv4 or [::] for IPv6).
+ A TCP socket server (<strong>addr</strong> defaults to <tt>0.0.0.0</tt> for IPv4 or <tt>[::]</tt> for IPv6).
</p>
</dd>
<dt class="hdlist1">
@@ -6706,12 +6782,13 @@ by the Tcl library.</p></div> </p>
<div class="literalblock">
<div class="content">
-<pre><tt>tcl_platform(byteOrder) = littleEndian
-tcl_platform(os) = Darwin
-tcl_platform(platform) = unix
-tcl_platform(pointerSize) = 8
-tcl_platform(threaded) = 0
-tcl_platform(wordSize) = 8</tt></pre>
+<pre><tt>tcl_platform(byteOrder) = littleEndian
+tcl_platform(os) = Darwin
+tcl_platform(platform) = unix
+tcl_platform(pointerSize) = 8
+tcl_platform(threaded) = 0
+tcl_platform(wordSize) = 8
+tcl_platform(pathSeparator) = :</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
@@ -7025,7 +7102,7 @@ official policies, either expressed or implied, of the Jim Tcl Project.</tt></pr <div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
-Last updated 2011-06-10 14:47:19 EST
+Last updated 2011-07-18 16:09:46 EST
</div>
</div>
</body>
diff --git a/jim_tcl.txt b/jim_tcl.txt index dbcb34a..e62d8af 100644 --- a/jim_tcl.txt +++ b/jim_tcl.txt @@ -3,7 +3,7 @@ Jim Tcl(n) NAME ---- -Jim Tcl v0.71 - overview of the Jim tool command language facilities +Jim Tcl v0.72 - overview of the Jim tool command language facilities SYNOPSIS -------- @@ -57,7 +57,11 @@ RECENT CHANGES Changes between 0.71 and 0.72 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. Allow 'args' and optional parameters in any position +1. procs now allow 'args' and optional parameters in any position +2. Add Tcl-compatible expr functions, 'rand()' and 'srand()' +3. Add support for the '-force' option to 'file delete' +4. Better diagnostics when 'source' fails to load a script with a missing quote or bracket +5. New +tcl_platform(pathSeparator)+ Changes between 0.70 and 0.71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -703,12 +707,15 @@ on the right side of the line: The valid operators are listed below, grouped in decreasing order of precedence: [[OperatorPrecedence]] -`int() double() round() abs()`:: - Unary functions. +`int() double() round() abs(), rand(), srand()`:: + Unary functions (except rand() which takes no arguments) int() converts the numeric argument to an integer by truncating down. double() converts the numeric argument to floating point. round() converts the numeric argument to the closest integer value. abs() takes the absolute value of the numeric argument. + rand() takes the absolute value of the numeric argument. + rand() returns a pseudo-random floating-point value in the range (0,1). + srand() takes an integer argument to (re)seed the random number generator. Returns the first random number from that seed. `sin() cos() tan() asin() acos() atan() sinh() cosh() tanh() ceil() floor() exp() log() log10() sqrt()`:: Unary math functions. @@ -1835,19 +1842,19 @@ Performs one of several operations on dictionary values. The *option* argument determines what action is carried out by the command. The legal *options* are: -*dict create* '?key value ...?'+:: ++*dict create* '?key value ...?'+:: Create and return a new dictionary value that contains each of the key/value mappings listed as arguments (keys and values alternating, with each key being followed by its associated value.) -*dict exists* 'dictionary key ?key ...?'+:: ++*dict exists* 'dictionary key ?key ...?'+:: Returns a boolean value indicating whether the given key (or path of keys through a set of nested dictionaries) exists in the given dictionary value. This returns a true value exactly when 'dict get' on that path will succeed. -*dict get* 'dictionary ?key ...?'+:: ++*dict get* 'dictionary ?key ...?'+:: Given a dictionary value (first argument) and a key (second argument), this will retrieve the value for that key. Where several keys are supplied, the behaviour of the command shall be as if the result @@ -1860,26 +1867,26 @@ command. The legal *options* are: be the value for that key. It is an error to attempt to retrieve a value for a key that is not present in the dictionary. -*dict keys* 'dictionary ?pattern?'+:: ++*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. -*dict keys* 'dictionary ?pattern?'+:: ++*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. -*dict set* 'dictionaryName key ?key ...? value'+:: ++*dict set* 'dictionaryName key ?key ...? value'+:: This operation takes the *name* of a variable containing a dictionary value and places an updated dictionary value in that variable containing a mapping from the given key to the given value. When multiple keys are present, this operation creates or updates a chain of nested dictionaries. -*dict unset* 'dictionaryName key ?key ...? value'+:: ++*dict unset* 'dictionaryName key ?key ...? value'+:: This operation (the companion to 'dict set') takes the name of a variable containing a dictionary value and places an updated dictionary value in that variable that does not contain a mapping @@ -2157,9 +2164,11 @@ abbreviation for *option* is acceptable. The valid options are: Copies file *source* to file *target*. The source file must exist. The target file must not exist, unless *-force* is specified. -+*file delete* 'name ...'+:: ++*file delete ?-force?* 'name ...'+:: Deletes file or directory *name*. If the file or directory doesn't exist, nothing happens. - If it can't be deleted, an error is generated. Non-empty directories will not be deleted. + If it can't be deleted, an error is generated. Non-empty directories will not be deleted + unless the '-force' options is given. In this case no errors will be generated, even + if the file/directory can't be deleted. +*file dirname* 'name'+:: Return all of the characters in *name* up to but not including @@ -2592,10 +2601,8 @@ The legal *option*'s (which may be abbreviated) are: +*info nameofexecutable*+:: Returns the name of the binary file from which the application - was invoked, either - as a path relative to the current directory or as a full - path. If the path can't be determined, returns the empty - string. + was invoked. A full path will be returned, unless the path + can't be determined, in which case the empty string will be returned. +*info procs* ?'pattern'?+:: If *pattern* isn't specified, returns a list of all the @@ -3680,7 +3687,7 @@ string Perform one of several string operations, depending on *option*. The legal options (which may be abbreviated) are: -+*string bytelength 'string'+:: ++*string bytelength* 'string'+:: Returns the length of the string in bytes. This will return the same value as 'string length' if UTF-8 support is not enabled, or if the string is composed entirely of ASCII characters. @@ -4404,8 +4411,8 @@ Various socket types may be created. +*socket ?-ipv6? stream* 'addr:port'+:: A TCP socket client. -+*socket ?-ipv6? stream.server '?addr:?port'+:: - A TCP socket server (*addr* defaults to 0.0.0.0 for IPv4 or [::] for IPv6). ++*socket ?-ipv6? stream.server* '?addr:?port'+:: + A TCP socket server (*addr* defaults to +0.0.0.0+ for IPv4 or +[::]+ for IPv6). +*socket ?-ipv6? dgram* ?'addr:port'?+:: A UDP socket client. If the address is not specified, @@ -4551,12 +4558,13 @@ The following global variables are set by jimsh. about the platform upon which Jim was built. The following is an example of the contents of this array. - tcl_platform(byteOrder) = littleEndian - tcl_platform(os) = Darwin - tcl_platform(platform) = unix - tcl_platform(pointerSize) = 8 - tcl_platform(threaded) = 0 - tcl_platform(wordSize) = 8 + tcl_platform(byteOrder) = littleEndian + tcl_platform(os) = Darwin + tcl_platform(platform) = unix + tcl_platform(pointerSize) = 8 + tcl_platform(threaded) = 0 + tcl_platform(wordSize) = 8 + tcl_platform(pathSeparator) = : +*argv0*+:: If jimsh is invoked to run a script, this variable contains the name |