diff options
author | Steve Bennett <steveb@workware.net.au> | 2011-04-23 15:57:08 +1000 |
---|---|---|
committer | Steve Bennett <steveb@workware.net.au> | 2011-05-31 15:45:55 +1000 |
commit | c09f838395bcc33cae854be44a2be5020fb45f87 (patch) | |
tree | 956e877eb05e6177f1d1e4829da0862b528daaf9 | |
parent | a73c44be97e43cc8b724c41d3550ba9e46c91ae8 (diff) | |
download | jimtcl-c09f838395bcc33cae854be44a2be5020fb45f87.zip jimtcl-c09f838395bcc33cae854be44a2be5020fb45f87.tar.gz jimtcl-c09f838395bcc33cae854be44a2be5020fb45f87.tar.bz2 |
Document recent features
jimsh --version
tcl_platform()
proc &var
proc rename args
expr sugar $(...)
Also add documentation for jimsh, including interactive mode
Signed-off-by: Steve Bennett <steveb@workware.net.au>
-rw-r--r-- | Tcl_shipped.html | 163 | ||||
-rw-r--r-- | jim_tcl.txt | 121 |
2 files changed, 250 insertions, 34 deletions
diff --git a/Tcl_shipped.html b/Tcl_shipped.html index 864aa0a..bb3bd90 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.70 -
+<p>Jim Tcl v0.71 -
overview of the Jim tool command language facilities
</p>
</div>
@@ -570,7 +570,9 @@ Jim Tcl(n) Manual Page <div class="paragraph"><p>or</p></div>
<div class="literalblock">
<div class="content">
-<pre><tt>jimsh <script></tt></pre>
+<pre><tt>jimsh [<scriptfile>]
+jimsh -e '<immediate-script>'
+jimsh --version</tt></pre>
</div></div>
<div class="ulist"><div class="title">Quick Index</div><ul>
<li>
@@ -666,19 +668,61 @@ Variable traces are not supported </li>
<li>
<p>
-The history command is not supported
+Direct command line editing rather than the <em>history</em> command
+</p>
+</li>
+<li>
+<p>
+Expression shorthand syntax: <tt>$(…)</tt>
+</p>
+</li>
+<li>
+<p>
+The <em>binary</em> command is not supported
</p>
</li>
</ol></div>
</div>
</div>
<div class="sect1">
-<h2 id="_changes_in_this_release">CHANGES IN THIS RELEASE</h2>
+<h2 id="_recent_changes">RECENT CHANGES</h2>
<div class="sectionbody">
+<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>
+<p>
+Allow <em>args</em> to be renamed in procs
+</p>
+</li>
+<li>
+<p>
+Add <tt>$(…)</tt> shorthand syntax for expressions
+</p>
+</li>
+<li>
+<p>
+Add automatic reference variables in procs with <tt>&var</tt> syntax
+</p>
+</li>
+<li>
+<p>
+Support <tt>jimsh --version</tt>
+</p>
+</li>
+<li>
+<p>
+Additional variables in <tt>tcl_platform()</tt>
+</p>
+</li>
+</ol></div>
+</div>
+<div class="sect2">
+<h3 id="_changes_between_0_63_and_0_70">Changes between 0.63 and 0.70</h3>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
-$::platform_tcl() settings are now automatically determined
+<tt>platform_tcl()</tt> settings are now automatically determined
</p>
</li>
<li>
@@ -734,6 +778,7 @@ Command line editing in interactive mode, e.g. <em>jimsh</em> </ol></div>
</div>
</div>
+</div>
<div class="sect1">
<h2 id="_tcl_introduction">TCL INTRODUCTION</h2>
<div class="sectionbody">
@@ -773,6 +818,8 @@ Tcl core described here, but various add-on libraries, such as the Tk toolkit, allow applications to issue commands to each other. This makes
it possible for applications to work together in much more powerful ways
than was previously possible.</p></div>
+<div class="paragraph"><p>Fourth, Jim Tcl includes a command processor, <tt>jimsh</tt>, which can be
+used to run standalone Tcl scripts, or to run Tcl commands interactively.</p></div>
<div class="paragraph"><p>This manual page focuses primarily on the Tcl language. It describes
the language syntax and the built-in commands that will be available
in any application based on Tcl. The individual library procedures are
@@ -780,6 +827,58 @@ described in more detail in separate manual pages, one per procedure.</p></div> </div>
</div>
<div class="sect1">
+<h2 id="_jimsh_command_interpreter">JIMSH COMMAND INTERPRETER</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>A simple, but powerful command processor, <tt>jimsh</tt>, is part of Jim Tcl.
+It may be invoked in interactive mode as:</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><tt>jimsh</tt></pre>
+</div></div>
+<div class="paragraph"><p>or to process the Tcl script in a file with:</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><tt>jimsh filename</tt></pre>
+</div></div>
+<div class="paragraph"><p>It may also be invoked to execute an immediate script with:</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><tt>jimsh -e "script"</tt></pre>
+</div></div>
+<div class="sect2">
+<h3 id="_interactive_mode">Interactive Mode</h3>
+<div class="paragraph"><p>Interactive mode reads Tcl commands from standard input, evaluates
+those commands and prints the results.</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><tt>$ jimsh
+Welcome to Jim version 0.71, Copyright (c) 2005-8 Salvatore Sanfilippo
+. info version
+0.71
+. lsort [info commands p*]
+package parray pid popen proc puts pwd
+. foreach i {a b c} {
+{> puts $i
+{> }
+a
+b
+c
+. bad
+invalid command name "bad"
+[error] . exit
+$</tt></pre>
+</div></div>
+<div class="paragraph"><p>If <tt>jimsh</tt> is configured with line editing (it is by default) and a VT-100-compatible
+terminal is detected, Emacs-style line editing commands are available, including:
+arrow keys, <tt>^W</tt> to erase a word, <tt>^U</tt> to erase the line, <tt>^R</tt> for reverse incremental search
+in history. Additionally, the <tt>h</tt> command may be used to display the command history.</p></div>
+<div class="paragraph"><p>Command line history is automatically saved and loaded from <tt>~/.jim_history</tt></p></div>
+<div class="paragraph"><p>In interactive mode, <tt>jimsh</tt> automatically runs the script <tt>~/.jimrc</tt> at startup
+if it exists.</p></div>
+</div>
+</div>
+</div>
+<div class="sect1">
<h2 id="_interpreters">INTERPRETERS</h2>
<div class="sectionbody">
<div class="paragraph"><p>The central data structure in Tcl is an interpreter (C type <em>Jim_Interp</em>).
@@ -1218,7 +1317,7 @@ sequence is replaced by the given character:</p></div> <dd>
<p>
The hex digits <strong>nnnn</strong> (between one and four of them) give a unicode codepoint.
- The UTF-8 encoding of the codepoint is inserted.
+ The UTF-8 encoding of the codepoint is inserted.
</p>
</dd>
</dl></div>
@@ -2010,13 +2109,26 @@ argument specifiers:</p></div> </p>
</dd>
<dt class="hdlist1">
+<tt>&name</tt>
+</dt>
+<dd>
+<p>
+ Reference Argument - The caller is expected to pass the name of
+ an existing variable. An implicit <tt>upvar 1 <strong>origname</strong> <strong>name</strong></tt> is done
+ to make the variable available in the proc scope.
+</p>
+</dd>
+<dt class="hdlist1">
<tt><strong>args</strong></tt>
</dt>
<dd>
<p>
- Variable Argument - The special name <em>args</em>, which is
+ Variable Argument - The special name <strong>args</strong>, which is
assigned all remaining arguments (including none). The
- variable argument may only be specified once.
+ 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,
+ the variable is named <strong>newname</strong> rather than <strong>args</strong>.
</p>
</dd>
</dl></div>
@@ -3351,6 +3463,13 @@ to 0.</p></div> <div class="paragraph"><p><tt><strong>expr</strong> <em>arg</em></tt></p></div>
<div class="paragraph"><p>Calls the expression processor to evaluate <strong>arg</strong>, and returns
the result as a string. See the section EXPRESSIONS above.</p></div>
+<div class="paragraph"><p>Note that Jim supports a shorthand syntax for <em>expr</em> as <tt>$(…)</tt>
+The following two are identical.</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><tt>set x [expr {3 * 2 + 1}]
+set x $(3 * 2 + 1)</tt></pre>
+</div></div>
</div>
<div class="sect2">
<h3 id="_file">file</h3>
@@ -5152,9 +5271,9 @@ The legal options (which may be abbreviated) are:</p></div> <dd>
<p>
Returns the length of the string in bytes. This will return
- the same value as <em>string length</em> if UTF-8 support is not enabled,
- or if the string is composed entirely of ASCII characters.
- See UTF-8 AND UNICODE.
+ the same value as <em>string length</em> if UTF-8 support is not enabled,
+ or if the string is composed entirely of ASCII characters.
+ See UTF-8 AND UNICODE.
</p>
</dd>
<dt class="hdlist1">
@@ -5380,8 +5499,8 @@ Any hexadecimal digit character ([0-9A-Fa-f]). <dd>
<p>
Returns a decimal string giving the number of characters in <strong>string</strong>.
- If UTF-8 support is enabled, this may be different than the number of bytes.
- See UTF-8 AND UNICODE
+ If UTF-8 support is enabled, this may be different than the number of bytes.
+ See UTF-8 AND UNICODE
</p>
</dd>
<dt class="hdlist1">
@@ -6085,8 +6204,8 @@ uid 1000 euid 1000 gid 100 egid 100</tt></pre> <dd>
<p>
Returns the original filename used when opening the file.
- If the handle was returned from <em>socket</em>, the type of the
- handle is returned instead.
+ If the handle was returned from <em>socket</em>, the type of the
+ handle is returned instead.
</p>
</dd>
<dt class="hdlist1">
@@ -6518,8 +6637,18 @@ by the Tcl library.</p></div> <dd>
<p>
This variable is set by Jim as an array containing information
- about the platform upon which Jim was built.
+ about the platform upon which Jim was built. The following is an
+ example of the contents of this array.
</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>
+</div></div>
</dd>
<dt class="hdlist1">
<tt><strong>argv0</strong></tt>
@@ -6832,7 +6961,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-05-28 07:46:46 EST
+Last updated 2011-05-31 15:45:18 EST
</div>
</div>
</body>
diff --git a/jim_tcl.txt b/jim_tcl.txt index 2ef4cc8..dae6622 100644 --- a/jim_tcl.txt +++ b/jim_tcl.txt @@ -3,7 +3,7 @@ Jim Tcl(n) NAME ---- -Jim Tcl v0.70 - overview of the Jim tool command language facilities +Jim Tcl v0.71 - overview of the Jim tool command language facilities SYNOPSIS -------- @@ -12,7 +12,10 @@ SYNOPSIS or - jimsh <script> + jimsh [<scriptfile>] + jimsh -e '<immediate-script>' + jimsh --version + .Quick Index * <<CommandIndex,Command Reference>> @@ -46,12 +49,24 @@ The major differences with Tcl 8.5/8.6 are: 9. Support for "static" variables in procedures 10. Namespaces are not support 11. Variable traces are not supported -12. The history command is not supported +12. Direct command line editing rather than the 'history' command +13. Expression shorthand syntax: +$(...)+ +14. The 'binary' command is not supported -CHANGES IN THIS RELEASE ------------------------ +RECENT CHANGES +-------------- -1. $::platform_tcl() settings are now automatically determined +Changes between 0.70 and 0.71 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +1. Allow 'args' to be renamed in procs +2. Add +$(...)+ shorthand syntax for expressions +3. Add automatic reference variables in procs with +&var+ syntax +4. Support +jimsh --version+ +5. Additional variables in +tcl_platform()+ + +Changes between 0.63 and 0.70 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +1. +platform_tcl()+ settings are now automatically determined 2. Add aio '$handle filename' 3. Add 'info channels' 4. The 'bio' extension is gone. Now 'aio' supports 'copyto'. @@ -107,11 +122,61 @@ toolkit, allow applications to issue commands to each other. This makes it possible for applications to work together in much more powerful ways than was previously possible. +Fourth, Jim Tcl includes a command processor, +jimsh+, which can be +used to run standalone Tcl scripts, or to run Tcl commands interactively. + This manual page focuses primarily on the Tcl language. It describes the language syntax and the built-in commands that will be available in any application based on Tcl. The individual library procedures are described in more detail in separate manual pages, one per procedure. +JIMSH COMMAND INTERPRETER +------------------------- +A simple, but powerful command processor, +jimsh+, is part of Jim Tcl. +It may be invoked in interactive mode as: + + jimsh + +or to process the Tcl script in a file with: + + jimsh filename + +It may also be invoked to execute an immediate script with: + + jimsh -e "script" + +Interactive Mode +~~~~~~~~~~~~~~~~ +Interactive mode reads Tcl commands from standard input, evaluates +those commands and prints the results. + + $ jimsh + Welcome to Jim version 0.71, Copyright (c) 2005-8 Salvatore Sanfilippo + . info version + 0.71 + . lsort [info commands p*] + package parray pid popen proc puts pwd + . foreach i {a b c} { + {> puts $i + {> } + a + b + c + . bad + invalid command name "bad" + [error] . exit + $ + +If +jimsh+ is configured with line editing (it is by default) and a VT-100-compatible +terminal is detected, Emacs-style line editing commands are available, including: +arrow keys, +\^W+ to erase a word, +\^U+ to erase the line, +^R+ for reverse incremental search +in history. Additionally, the +h+ command may be used to display the command history. + +Command line history is automatically saved and loaded from +~/.jim_history+ + +In interactive mode, +jimsh+ automatically runs the script +~/.jimrc+ at startup +if it exists. + INTERPRETERS ------------ The central data structure in Tcl is an interpreter (C type 'Jim_Interp'). @@ -446,7 +511,7 @@ sequence is replaced by the given character: +{backslash}*unnnn*+:: The hex digits *nnnn* (between one and four of them) give a unicode codepoint. - The UTF-8 encoding of the codepoint is inserted. + The UTF-8 encoding of the codepoint is inserted. For example, in the command @@ -1000,10 +1065,18 @@ argument specifiers: argument name, followed by the default value, which will be used if the corresponding argument is not supplied. ++&name+:: + Reference Argument - The caller is expected to pass the name of + an existing variable. An implicit +upvar 1 *origname* *name*+ is done + to make the variable available in the proc scope. + +*args*+:: - Variable Argument - The special name 'args', which is + Variable Argument - The special name *args*, which is assigned all remaining arguments (including none). The - variable argument may only be specified once. + variable argument may only be specified once. Note that + the syntax +args newname+ may be used to retain the special + behaviour of *args* with a different local name. In this case, + the variable is named *newname* rather than *args*. Arguments must be provided in the following order, any of which may be omitted: @@ -2040,6 +2113,12 @@ expr Calls the expression processor to evaluate *arg*, and returns the result as a string. See the section EXPRESSIONS above. +Note that Jim supports a shorthand syntax for 'expr' as +$(...)+ +The following two are identical. + + set x [expr {3 * 2 + 1}] + set x $(3 * 2 + 1) + file ~~~~ +*file* 'option name ?arg arg ...?'+ @@ -3569,9 +3648,9 @@ The legal options (which may be abbreviated) are: +*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. - See UTF-8 AND UNICODE. + the same value as 'string length' if UTF-8 support is not enabled, + or if the string is composed entirely of ASCII characters. + See UTF-8 AND UNICODE. +*string compare ?-nocase?* 'string1 string2'+:: Perform a character-by-character comparison of strings *string1* and @@ -3638,8 +3717,8 @@ The legal options (which may be abbreviated) are: +*string length* 'string'+:: Returns a decimal string giving the number of characters in *string*. - If UTF-8 support is enabled, this may be different than the number of bytes. - See UTF-8 AND UNICODE + If UTF-8 support is enabled, this may be different than the number of bytes. + See UTF-8 AND UNICODE +*string match ?-nocase?* 'pattern string'+:: See if *pattern* matches *string*; return 1 if it does, 0 @@ -4169,8 +4248,8 @@ aio +$handle *filename*+:: Returns the original filename used when opening the file. - If the handle was returned from 'socket', the type of the - handle is returned instead. + If the handle was returned from 'socket', the type of the + handle is returned instead. +$handle *ndelay ?0|1?*+:: Set O_NDELAY (if arg). Returns current/new setting. @@ -4419,7 +4498,15 @@ The following global variables are set by jimsh. +*tcl_platform*+:: This variable is set by Jim as an array containing information - about the platform upon which Jim was built. + 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 +*argv0*+:: If jimsh is invoked to run a script, this variable contains the name |