Initial release
This commit is contained in:
unknown
194
hlp/en/tcl/Tcl.htm
Normal file
194
hlp/en/tcl/Tcl.htm
Normal file
@@ -0,0 +1,194 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - Tcl manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="Tcl.htm#M2" NAME="L2">NAME</A>
|
||||
<DL><DD>Tcl - Summary of Tcl language syntax.</DL>
|
||||
<DD><A HREF="Tcl.htm#M3" NAME="L3">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DL>
|
||||
<DD><A HREF="Tcl.htm#M4" NAME="L4"><B>$</B><I>name</I></A>
|
||||
<DD><A HREF="Tcl.htm#M5" NAME="L5"><B>$</B><I>name</I><B>(</B><I>index</I><B>)</B></A>
|
||||
<DD><A HREF="Tcl.htm#M6" NAME="L6"><B>${</B><I>name</I><B>}</B></A>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="Tcl.htm#M7" NAME="L7">\<B>a</B></A>
|
||||
<DD><A HREF="Tcl.htm#M8" NAME="L8">\<B>b</B></A>
|
||||
<DD><A HREF="Tcl.htm#M9" NAME="L9">\<B>f</B></A>
|
||||
<DD><A HREF="Tcl.htm#M10" NAME="L10">\<B>n</B></A>
|
||||
<DD><A HREF="Tcl.htm#M11" NAME="L11">\<B>r</B></A>
|
||||
<DD><A HREF="Tcl.htm#M12" NAME="L12">\<B>t</B></A>
|
||||
<DD><A HREF="Tcl.htm#M13" NAME="L13">\<B>v</B></A>
|
||||
<DD><A HREF="Tcl.htm#M14" NAME="L14">\<B><newline></B><I>whiteSpace</I></A>
|
||||
<DD><A HREF="Tcl.htm#M15" NAME="L15">\\</A>
|
||||
<DD><A HREF="Tcl.htm#M16" NAME="L16">\<I>ooo</I></A>
|
||||
<DD><A HREF="Tcl.htm#M17" NAME="L17">\<B>x</B><I>hh</I></A>
|
||||
<DD><A HREF="Tcl.htm#M18" NAME="L18">\<B>u</B><I>hhhh</I></A>
|
||||
</DL>
|
||||
</DL>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
Tcl - Summary of Tcl language syntax.
|
||||
<H3><A NAME="M3">DESCRIPTION</A></H3>
|
||||
The following rules define the syntax and semantics of the Tcl language:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT>[1]<DD>
|
||||
A Tcl script is a string containing one or more commands.
|
||||
Semi-colons and newlines are command separators unless quoted as
|
||||
described below.
|
||||
Close brackets are command terminators during command substitution
|
||||
(see below) unless quoted.
|
||||
<P><DT>[2]<DD>
|
||||
A command is evaluated in two steps.
|
||||
First, the Tcl interpreter breaks the command into <I>words</I>
|
||||
and performs substitutions as described below.
|
||||
These substitutions are performed in the same way for all
|
||||
commands.
|
||||
The first word is used to locate a command procedure to
|
||||
carry out the command, then all of the words of the command are
|
||||
passed to the command procedure.
|
||||
The command procedure is free to interpret each of its words
|
||||
in any way it likes, such as an integer, variable name, list,
|
||||
or Tcl script.
|
||||
Different commands interpret their words differently.
|
||||
<P><DT>[3]<DD>
|
||||
Words of a command are separated by white space (except for
|
||||
newlines, which are command separators).
|
||||
<P><DT>[4]<DD>
|
||||
If the first character of a word is double-quote (``"'') then
|
||||
the word is terminated by the next double-quote character.
|
||||
If semi-colons, close brackets, or white space characters
|
||||
(including newlines) appear between the quotes then they are treated
|
||||
as ordinary characters and included in the word.
|
||||
Command substitution, variable substitution, and backslash substitution
|
||||
are performed on the characters between the quotes as described below.
|
||||
The double-quotes are not retained as part of the word.
|
||||
<P><DT>[5]<DD>
|
||||
If the first character of a word is an open brace (``{'') then
|
||||
the word is terminated by the matching close brace (``}'').
|
||||
Braces nest within the word: for each additional open
|
||||
brace there must be an additional close brace (however,
|
||||
if an open brace or close brace within the word is
|
||||
quoted with a backslash then it is not counted in locating the
|
||||
matching close brace).
|
||||
No substitutions are performed on the characters between the
|
||||
braces except for backslash-newline substitutions described
|
||||
below, nor do semi-colons, newlines, close brackets,
|
||||
or white space receive any special interpretation.
|
||||
The word will consist of exactly the characters between the
|
||||
outer braces, not including the braces themselves.
|
||||
<P><DT>[6]<DD>
|
||||
If a word contains an open bracket (``['') then Tcl performs
|
||||
<I>command substitution</I>.
|
||||
To do this it invokes the Tcl interpreter recursively to process
|
||||
the characters following the open bracket as a Tcl script.
|
||||
The script may contain any number of commands and must be terminated
|
||||
by a close bracket (``]'').
|
||||
The result of the script (i.e. the result of its last command) is
|
||||
substituted into the word in place of the brackets and all of the
|
||||
characters between them.
|
||||
There may be any number of command substitutions in a single word.
|
||||
Command substitution is not performed on words enclosed in braces.
|
||||
<P><DT>[7]<DD>
|
||||
If a word contains a dollar-sign (``$'') then Tcl performs <I>variable
|
||||
substitution</I>: the dollar-sign and the following characters are
|
||||
replaced in the word by the value of a variable.
|
||||
Variable substitution may take any of the following forms:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M4"><B>$</B><I>name</I></A><DD>
|
||||
<I>Name</I> is the name of a scalar variable; the name is terminated
|
||||
by any character that isn't a letter, digit, or underscore.
|
||||
<P><DT><A NAME="M5"><B>$</B><I>name</I><B>(</B><I>index</I><B>)</B></A><DD>
|
||||
<I>Name</I> gives the name of an array variable and <I>index</I> gives
|
||||
the name of an element within that array.
|
||||
<I>Name</I> must contain only letters, digits, and underscores.
|
||||
Command substitutions, variable substitutions, and backslash
|
||||
substitutions are performed on the characters of <I>index</I>.
|
||||
<P><DT><A NAME="M6"><B>${</B><I>name</I><B>}</B></A><DD>
|
||||
<I>Name</I> is the name of a scalar variable. It may contain any
|
||||
characters whatsoever except for close braces.
|
||||
</DL><P>There may be any number of variable substitutions in a single word.
|
||||
Variable substitution is not performed on words enclosed in braces.<DL>
|
||||
<P></DL>
|
||||
<P><DT>[8]<DD>
|
||||
If a backslash (``\'') appears within a word then
|
||||
<I>backslash substitution</I> occurs.
|
||||
In all cases but those described below the backslash is dropped and
|
||||
the following character is treated as an ordinary
|
||||
character and included in the word.
|
||||
This allows characters such as double quotes, close brackets,
|
||||
and dollar signs to be included in words without triggering
|
||||
special processing.
|
||||
The following table lists the backslash sequences that are
|
||||
handled specially, along with the value that replaces each sequence.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M7">\<B>a</B></A><DD>
|
||||
Audible alert (bell) (0x7).
|
||||
<P><DT><A NAME="M8">\<B>b</B></A><DD>
|
||||
Backspace (0x8).
|
||||
<P><DT><A NAME="M9">\<B>f</B></A><DD>
|
||||
Form feed (0xc).
|
||||
<P><DT><A NAME="M10">\<B>n</B></A><DD>
|
||||
Newline (0xa).
|
||||
<P><DT><A NAME="M11">\<B>r</B></A><DD>
|
||||
Carriage-return (0xd).
|
||||
<P><DT><A NAME="M12">\<B>t</B></A><DD>
|
||||
Tab (0x9).
|
||||
<P><DT><A NAME="M13">\<B>v</B></A><DD>
|
||||
Vertical tab (0xb).
|
||||
<P><DT><A NAME="M14">\<B><newline></B><I>whiteSpace</I></A><DD>
|
||||
A single space character replaces the backslash, newline, and all spaces
|
||||
and tabs after the newline. This backslash sequence is unique in that it
|
||||
is replaced in a separate pre-pass before the command is actually parsed.
|
||||
This means that it will be replaced even when it occurs between braces,
|
||||
and the resulting space will be treated as a word separator if it isn't
|
||||
in braces or quotes.
|
||||
<P><DT><A NAME="M15">\\</A><DD>
|
||||
Backslash (``\'').
|
||||
<P><DT><A NAME="M16">\<I>ooo</I></A><DD>
|
||||
The digits <I>ooo</I> (one, two, or three of them) give an eight-bit octal
|
||||
value for the Unicode character that will be inserted. The upper bits of the
|
||||
Unicode character will be 0.
|
||||
<P><DT><A NAME="M17">\<B>x</B><I>hh</I></A><DD>
|
||||
The hexadecimal digits <I>hh</I> give an eight-bit hexadecimal value for the
|
||||
Unicode character that will be inserted. Any number of hexadecimal digits
|
||||
may be present; however, all but the last two are ignored (the result is
|
||||
always a one-byte quantity). The upper bits of the Unicode character will
|
||||
be 0.
|
||||
<P><DT><A NAME="M18">\<B>u</B><I>hhhh</I></A><DD>
|
||||
The hexadecimal digits <I>hhhh</I> (one, two, three, or four of them) give a
|
||||
sixteen-bit hexadecimal value for the Unicode character that will be
|
||||
inserted.
|
||||
</DL><P>Backslash substitution is not performed on words enclosed in braces,
|
||||
except for backslash-newline as described above.<DL>
|
||||
<P></DL>
|
||||
<P><DT>[9]<DD>
|
||||
If a hash character (``#'') appears at a point where Tcl is
|
||||
expecting the first character of the first word of a command,
|
||||
then the hash character and the characters that follow it, up
|
||||
through the next newline, are treated as a comment and ignored.
|
||||
The comment character only has significance when it appears
|
||||
at the beginning of a command.
|
||||
<P><DT>[10]<DD>
|
||||
Each character is processed exactly once by the Tcl interpreter
|
||||
as part of creating the words of a command.
|
||||
For example, if variable substitution occurs then no further
|
||||
substitutions are performed on the value of the variable; the
|
||||
value is inserted into the word verbatim.
|
||||
If command substitution occurs then the nested command is
|
||||
processed entirely by the recursive call to the Tcl interpreter;
|
||||
no substitutions are performed before making the recursive
|
||||
call and no additional substitutions are performed on the result
|
||||
of the nested script.
|
||||
<P><DT>[11]<DD>
|
||||
Substitutions do not affect the word boundaries of a command.
|
||||
For example, during variable substitution the entire value of
|
||||
the variable becomes part of a single word, even if the variable's
|
||||
value contains spaces.
|
||||
<P></DL>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
114
hlp/en/tcl/after.htm
Normal file
114
hlp/en/tcl/after.htm
Normal file
@@ -0,0 +1,114 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - after manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="after.htm#M2" NAME="L19">NAME</A>
|
||||
<DL><DD>after - Execute a command after a time delay</DL>
|
||||
<DD><A HREF="after.htm#M3" NAME="L20">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>after </B><I>ms</I>
|
||||
<DD><B>after </B><I>ms </I>?<I>script script script ...</I>?
|
||||
<DD><B>after cancel </B><I>id</I>
|
||||
<DD><B>after cancel </B><I>script script script ...</I>
|
||||
<DD><B>after idle </B>?<I>script script script ...</I>?
|
||||
<DD><B>after info </B>?<I>id</I>?
|
||||
</DL>
|
||||
<DD><A HREF="after.htm#M4" NAME="L21">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="after.htm#M5" NAME="L22"><B>after </B><I>ms</I></A>
|
||||
<DD><A HREF="after.htm#M6" NAME="L23"><B>after </B><I>ms </I>?<I>script script script ...</I>?</A>
|
||||
<DD><A HREF="after.htm#M7" NAME="L24"><B>after cancel </B><I>id</I></A>
|
||||
<DD><A HREF="after.htm#M8" NAME="L25"><B>after cancel </B><I>script script ...</I></A>
|
||||
<DD><A HREF="after.htm#M9" NAME="L26"><B>after idle </B><I>script </I>?<I>script script ...</I>?</A>
|
||||
<DD><A HREF="after.htm#M10" NAME="L27"><B>after info </B>?<I>id</I>?</A>
|
||||
</DL>
|
||||
<DD><A HREF="after.htm#M11" NAME="L28">SEE ALSO</A>
|
||||
<DD><A HREF="after.htm#M12" NAME="L29">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
after - Execute a command after a time delay
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>after </B><I>ms</I><BR>
|
||||
<B>after </B><I>ms </I>?<I>script script script ...</I>?<BR>
|
||||
<B>after cancel </B><I>id</I><BR>
|
||||
<B>after cancel </B><I>script script script ...</I><BR>
|
||||
<B>after idle </B>?<I>script script script ...</I>?<BR>
|
||||
<B>after info </B>?<I>id</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command is used to delay execution of the program or to execute
|
||||
a command in background sometime in the future. It has several forms,
|
||||
depending on the first argument to the command:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>after </B><I>ms</I></A><DD>
|
||||
<I>Ms</I> must be an integer giving a time in milliseconds.
|
||||
The command sleeps for <I>ms</I> milliseconds and then returns.
|
||||
While the command is sleeping the application does not respond to
|
||||
events.
|
||||
<P><DT><A NAME="M6"><B>after </B><I>ms </I>?<I>script script script ...</I>?</A><DD>
|
||||
In this form the command returns immediately, but it arranges
|
||||
for a Tcl command to be executed <I>ms</I> milliseconds later as an
|
||||
event handler.
|
||||
The command will be executed exactly once, at the given time.
|
||||
The delayed command is formed by concatenating all the <I>script</I>
|
||||
arguments in the same fashion as the <B><A HREF="../TkCmd/concat.htm">concat</A></B> command.
|
||||
The command will be executed at global level (outside the context
|
||||
of any Tcl procedure).
|
||||
If an error occurs while executing the delayed command then the
|
||||
<B><A HREF="../TkCmd/bgerror.htm">bgerror</A></B> mechanism is used to report the error.
|
||||
The <B>after</B> command returns an identifier that can be used
|
||||
to cancel the delayed command using <B>after cancel</B>.
|
||||
<P><DT><A NAME="M7"><B>after cancel </B><I>id</I></A><DD>
|
||||
Cancels the execution of a delayed command that
|
||||
was previously scheduled.
|
||||
<I>Id</I> indicates which command should be canceled; it must have
|
||||
been the return value from a previous <B>after</B> command.
|
||||
If the command given by <I>id</I> has already been executed then
|
||||
the <B>after cancel</B> command has no effect.
|
||||
<P><DT><A NAME="M8"><B>after cancel </B><I>script script ...</I></A><DD>
|
||||
This command also cancels the execution of a delayed command.
|
||||
The <I>script</I> arguments are concatenated together with space
|
||||
separators (just as in the <B><A HREF="../TkCmd/concat.htm">concat</A></B> command).
|
||||
If there is a pending command that matches the string, it is
|
||||
cancelled and will never be executed; if no such command is
|
||||
currently pending then the <B>after cancel</B> command has no effect.
|
||||
<P><DT><A NAME="M9"><B>after idle </B><I>script </I>?<I>script script ...</I>?</A><DD>
|
||||
Concatenates the <I>script</I> arguments together with space
|
||||
separators (just as in the <B><A HREF="../TkCmd/concat.htm">concat</A></B> command), and arranges
|
||||
for the resulting script to be evaluated later as an idle callback.
|
||||
The script will be run exactly once, the next time the event
|
||||
loop is entered and there are no events to process.
|
||||
The command returns an identifier that can be used
|
||||
to cancel the delayed command using <B>after cancel</B>.
|
||||
If an error occurs while executing the script then the
|
||||
<B><A HREF="../TkCmd/bgerror.htm">bgerror</A></B> mechanism is used to report the error.
|
||||
<P><DT><A NAME="M10"><B>after info </B>?<I>id</I>?</A><DD>
|
||||
This command returns information about existing event handlers.
|
||||
If no <I>id</I> argument is supplied, the command returns
|
||||
a list of the identifiers for all existing
|
||||
event handlers created by the <B>after</B> command for this
|
||||
interpreter.
|
||||
If <I>id</I> is supplied, it specifies an existing handler;
|
||||
<I>id</I> must have been the return value from some previous call
|
||||
to <B>after</B> and it must not have triggered yet or been cancelled.
|
||||
In this case the command returns a list with two elements.
|
||||
The first element of the list is the script associated
|
||||
with <I>id</I>, and the second element is either
|
||||
<B>idle</B> or <B>timer</B> to indicate what kind of event
|
||||
handler it is.
|
||||
<P></DL>
|
||||
<P>
|
||||
The <B>after </B><I>ms</I> and <B>after idle</B> forms of the command
|
||||
assume that the application is event driven: the delayed commands
|
||||
will not be executed unless the application enters the event loop.
|
||||
In applications that are not normally event-driven, such as
|
||||
<B><A HREF="../UserCmd/tclsh.htm">tclsh</A></B>, the event loop can be entered with the <B><A HREF="../TkCmd/vwait.htm">vwait</A></B>
|
||||
and <B><A HREF="../TkCmd/update.htm">update</A></B> commands.
|
||||
|
||||
<H3><A NAME="M11">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/bgerror.htm">bgerror</A></B>, <B><A HREF="../TkCmd/concat.htm">concat</A></B>, <B><A HREF="../TkCmd/update.htm">update</A></B>, <B><A HREF="../TkCmd/vwait.htm">vwait</A></B>
|
||||
<H3><A NAME="M12">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#cancel">cancel</A>, <A href="../Keywords/D.htm#delay">delay</A>, <A href="../Keywords/I.htm#idle callback">idle callback</A>, <A href="../Keywords/S.htm#sleep">sleep</A>, <A href="../Keywords/T.htm#time">time</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1990-1994 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
24
hlp/en/tcl/append.htm
Normal file
24
hlp/en/tcl/append.htm
Normal file
@@ -0,0 +1,24 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - append manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
append - Append to variable
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>append </B><I>varName </I>?<I>value value value ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Append all of the <I>value</I> arguments to the current value
|
||||
of variable <I>varName</I>. If <I>varName</I> doesn't exist,
|
||||
it is given a value equal to the concatenation of all the
|
||||
<I>value</I> arguments.
|
||||
This command provides an efficient way to build up long
|
||||
variables incrementally.
|
||||
For example, ``<B>append a $b</B>'' is much more efficient than
|
||||
``<B>set a $a$b</B>'' if <B>$a</B> is long.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/concat.htm">concat</A></B>, <B><A HREF="../TkCmd/lappend.htm">lappend</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#append">append</A>, <A href="../Keywords/V.htm#variable">variable</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
128
hlp/en/tcl/array.htm
Normal file
128
hlp/en/tcl/array.htm
Normal file
@@ -0,0 +1,128 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - array manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="array.htm#M2" NAME="L35">NAME</A>
|
||||
<DL><DD>array - Manipulate array variables</DL>
|
||||
<DD><A HREF="array.htm#M3" NAME="L36">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>array </B><I>option arrayName</I> ?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="array.htm#M4" NAME="L37">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="array.htm#M5" NAME="L38"><B>array anymore </B><I>arrayName searchId</I></A>
|
||||
<DD><A HREF="array.htm#M6" NAME="L39"><B>array donesearch </B><I>arrayName searchId</I></A>
|
||||
<DD><A HREF="array.htm#M7" NAME="L40"><B>array exists </B><I>arrayName</I></A>
|
||||
<DD><A HREF="array.htm#M8" NAME="L41"><B>array get </B><I>arrayName</I> ?<I>pattern</I>?</A>
|
||||
<DD><A HREF="array.htm#M9" NAME="L42"><B>array names </B><I>arrayName</I> ?<I>pattern</I>?</A>
|
||||
<DD><A HREF="array.htm#M10" NAME="L43"><B>array nextelement </B><I>arrayName searchId</I></A>
|
||||
<DD><A HREF="array.htm#M11" NAME="L44"><B>array set </B><I>arrayName list</I></A>
|
||||
<DD><A HREF="array.htm#M12" NAME="L45"><B>array size </B><I>arrayName</I></A>
|
||||
<DD><A HREF="array.htm#M13" NAME="L46"><B>array startsearch </B><I>arrayName</I></A>
|
||||
<DD><A HREF="array.htm#M14" NAME="L47"><B>array unset </B><I>arrayName</I> ?<I>pattern</I>?</A>
|
||||
</DL>
|
||||
<DD><A HREF="array.htm#M15" NAME="L48">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
array - Manipulate array variables
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>array </B><I>option arrayName</I> ?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command performs one of several operations on the
|
||||
variable given by <I>arrayName</I>.
|
||||
Unless otherwise specified for individual commands below,
|
||||
<I>arrayName</I> must be the name of an existing array variable.
|
||||
The <I>option</I> argument determines what action is carried
|
||||
out by the command.
|
||||
The legal <I>options</I> (which may be abbreviated) are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>array anymore </B><I>arrayName searchId</I></A><DD>
|
||||
Returns 1 if there are any more elements left to be processed
|
||||
in an array search, 0 if all elements have already been
|
||||
returned.
|
||||
<I>SearchId</I> indicates which search on <I>arrayName</I> to
|
||||
check, and must have been the return value from a previous
|
||||
invocation of <B>array startsearch</B>.
|
||||
This option is particularly useful if an array has an element
|
||||
with an empty name, since the return value from
|
||||
<B>array nextelement</B> won't indicate whether the search
|
||||
has been completed.
|
||||
<P><DT><A NAME="M6"><B>array donesearch </B><I>arrayName searchId</I></A><DD>
|
||||
This command terminates an array search and destroys all the
|
||||
state associated with that search. <I>SearchId</I> indicates
|
||||
which search on <I>arrayName</I> to destroy, and must have
|
||||
been the return value from a previous invocation of
|
||||
<B>array startsearch</B>. Returns an empty string.
|
||||
<P><DT><A NAME="M7"><B>array exists </B><I>arrayName</I></A><DD>
|
||||
Returns 1 if <I>arrayName</I> is an array variable, 0 if there
|
||||
is no variable by that name or if it is a scalar variable.
|
||||
<P><DT><A NAME="M8"><B>array get </B><I>arrayName</I> ?<I>pattern</I>?</A><DD>
|
||||
Returns a list containing pairs of elements. The first
|
||||
element in each pair is the name of an element in <I>arrayName</I>
|
||||
and the second element of each pair is the value of the
|
||||
array element. The order of the pairs is undefined.
|
||||
If <I>pattern</I> is not specified, then all of the elements of the
|
||||
array are included in the result.
|
||||
If <I>pattern</I> is specified, then only those elements whose names
|
||||
match <I>pattern</I> (using the matching rules of
|
||||
<B><A HREF="../TkCmd/string.htm">string match</A></B>) are included.
|
||||
If <I>arrayName</I> isn't the name of an array variable, or if
|
||||
the array contains no elements, then an empty list is returned.
|
||||
<P><DT><A NAME="M9"><B>array names </B><I>arrayName</I> ?<I>pattern</I>?</A><DD>
|
||||
Returns a list containing the names of all of the elements in
|
||||
the array that match <I>pattern</I> (using the matching
|
||||
rules of <B><A HREF="../TkCmd/string.htm">string match</A></B>).
|
||||
If <I>pattern</I> is omitted then the command returns all of
|
||||
the element names in the array.
|
||||
If there are no (matching) elements in the array, or if <I>arrayName</I>
|
||||
isn't the name of an array variable, then an empty string is
|
||||
returned.
|
||||
<P><DT><A NAME="M10"><B>array nextelement </B><I>arrayName searchId</I></A><DD>
|
||||
Returns the name of the next element in <I>arrayName</I>, or
|
||||
an empty string if all elements of <I>arrayName</I> have
|
||||
already been returned in this search. The <I>searchId</I>
|
||||
argument identifies the search, and must have
|
||||
been the return value of an <B>array startsearch</B> command.
|
||||
Warning: if elements are added to or deleted from the array,
|
||||
then all searches are automatically terminated just as if
|
||||
<B>array donesearch</B> had been invoked; this will cause
|
||||
<B>array nextelement</B> operations to fail for those searches.
|
||||
<P><DT><A NAME="M11"><B>array set </B><I>arrayName list</I></A><DD>
|
||||
Sets the values of one or more elements in <I>arrayName</I>.
|
||||
<I>list</I> must have a form like that returned by <B>array get</B>,
|
||||
consisting of an even number of elements.
|
||||
Each odd-numbered element in <I>list</I> is treated as an element
|
||||
name within <I>arrayName</I>, and the following element in <I>list</I>
|
||||
is used as a new value for that array element.
|
||||
If the variable <I>arrayName</I> does not already exist
|
||||
and <I>list</I> is empty,
|
||||
<I>arrayName</I> is created with an empty array value.
|
||||
<P><DT><A NAME="M12"><B>array size </B><I>arrayName</I></A><DD>
|
||||
Returns a decimal string giving the number of elements in the
|
||||
array.
|
||||
If <I>arrayName</I> isn't the name of an array then 0 is returned.
|
||||
<P><DT><A NAME="M13"><B>array startsearch </B><I>arrayName</I></A><DD>
|
||||
This command initializes an element-by-element search through the
|
||||
array given by <I>arrayName</I>, such that invocations of the
|
||||
<B>array nextelement</B> command will return the names of the
|
||||
individual elements in the array.
|
||||
When the search has been completed, the <B>array donesearch</B>
|
||||
command should be invoked.
|
||||
The return value is a
|
||||
search identifier that must be used in <B>array nextelement</B>
|
||||
and <B>array donesearch</B> commands; it allows multiple
|
||||
searches to be underway simultaneously for the same array.
|
||||
<P><DT><A NAME="M14"><B>array unset </B><I>arrayName</I> ?<I>pattern</I>?</A><DD>
|
||||
Unsets all of the elements in the array that match <I>pattern</I> (using the
|
||||
matching rules of <B><A HREF="../TkCmd/string.htm">string match</A></B>). If <I>arrayName</I> isn't the name
|
||||
of an array variable or there are no matching elements in the array, then
|
||||
an empty string is returned. If <I>pattern</I> is omitted and is it an
|
||||
array variable, then the command unsets the entire array.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M15">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#array">array</A>, <A href="../Keywords/E.htm#element names">element names</A>, <A href="../Keywords/S.htm#search">search</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993-1994 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
68
hlp/en/tcl/bgerror.htm
Normal file
68
hlp/en/tcl/bgerror.htm
Normal file
@@ -0,0 +1,68 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - bgerror manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
bgerror - Command invoked to process background errors
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>bgerror </B><I>message</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>bgerror</B> command doesn't exist as built-in part of Tcl. Instead,
|
||||
individual applications or users can define a <B>bgerror</B>
|
||||
command (e.g. as a Tcl procedure) if they wish to handle background
|
||||
errors.
|
||||
<P>
|
||||
A background error is one that occurs in an event handler or some
|
||||
other command that didn't originate with the application.
|
||||
For example, if an error occurs while executing a command specified
|
||||
with the <B><A HREF="../TkCmd/after.htm">after</A></B> command, then it is a background error.
|
||||
For a non-background error, the error can simply be returned up
|
||||
through nested Tcl command evaluations until it reaches the top-level
|
||||
code in the application; then the application can report the error
|
||||
in whatever way it wishes. When a background error occurs, the
|
||||
unwinding ends in the Tcl library and there is no obvious way for Tcl
|
||||
to report the error.
|
||||
<P>
|
||||
When Tcl detects a background error, it saves information about the
|
||||
error and invokes the <B>bgerror</B> command later as an idle event
|
||||
handler. Before invoking <B>bgerror</B>, Tcl restores the
|
||||
<B>errorInfo</B> and <B>errorCode</B> variables to their values at the
|
||||
time the error occurred, then it invokes <B>bgerror</B> with the error
|
||||
message as its only argument. Tcl assumes that the application has
|
||||
implemented the <B>bgerror</B> command, and that the command will
|
||||
report the error in a way that makes sense for the application. Tcl
|
||||
will ignore any result returned by the <B>bgerror</B> command as long
|
||||
as no error is generated.
|
||||
<P>
|
||||
If another Tcl error occurs within the <B>bgerror</B> command (for
|
||||
example, because no <B>bgerror</B> command has been defined) then Tcl
|
||||
reports the error itself by writing a message to stderr.
|
||||
<P>
|
||||
If several background errors accumulate before <B>bgerror</B> is
|
||||
invoked to process them, <B>bgerror</B> will be invoked once for each
|
||||
error, in the order they occurred. However, if <B>bgerror</B> returns
|
||||
with a break exception, then any remaining errors are skipped without
|
||||
calling <B>bgerror</B>.
|
||||
<P>
|
||||
Tcl has no default implementation for <B>bgerror</B>. However, in
|
||||
applications using Tk there is a default <B>bgerror</B> procedure which
|
||||
posts a dialog box containing the error message and offers the user a
|
||||
chance to see a stack trace showing where the error occurred. In
|
||||
addition to allowing the user to view the stack trace, the dialog
|
||||
provides an additional application configurable button which may be
|
||||
used, for example, to save the stack trace to a file. By default,
|
||||
this is the behavior associated with that button. This behavior can
|
||||
be redefined by setting the option database values
|
||||
<B>*ErrorDialog.function.text</B>, to specify the caption for the
|
||||
function button, and <B>*ErrorDialog.function.command</B>, to specify
|
||||
the command to be run. The text of the stack trace is appended to the
|
||||
command when it is evaluated. If either of these options is set to
|
||||
the empty string, then the additional button will not be displayed in
|
||||
the dialog.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/after.htm">after</A></B>, <B><A HREF="../TkCmd/tclvars.htm">tclvars</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#background error">background error</A>, <A href="../Keywords/R.htm#reporting">reporting</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1990-1994 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
451
hlp/en/tcl/binary.htm
Normal file
451
hlp/en/tcl/binary.htm
Normal file
@@ -0,0 +1,451 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - binary manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="binary.htm#M2" NAME="L54">NAME</A>
|
||||
<DL><DD>binary - Insert and extract fields from binary strings</DL>
|
||||
<DD><A HREF="binary.htm#M3" NAME="L55">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>binary format </B><I>formatString </I>?<I>arg arg ...</I>?
|
||||
<DD><B>binary scan </B><I>string formatString </I>?<I>varName varName ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="binary.htm#M4" NAME="L56">DESCRIPTION</A>
|
||||
<DD><A HREF="binary.htm#M5" NAME="L57">BINARY FORMAT</A>
|
||||
<DL>
|
||||
<DD><A HREF="binary.htm#M6" NAME="L58"><B>a</B></A>
|
||||
<DD><A HREF="binary.htm#M7" NAME="L59"><B>A</B></A>
|
||||
<DD><A HREF="binary.htm#M8" NAME="L60"><B>b</B></A>
|
||||
<DD><A HREF="binary.htm#M9" NAME="L61"><B>B</B></A>
|
||||
<DD><A HREF="binary.htm#M10" NAME="L62"><B>h</B></A>
|
||||
<DD><A HREF="binary.htm#M11" NAME="L63"><B>H</B></A>
|
||||
<DD><A HREF="binary.htm#M12" NAME="L64"><B>c</B></A>
|
||||
<DD><A HREF="binary.htm#M13" NAME="L65"><B>s</B></A>
|
||||
<DD><A HREF="binary.htm#M14" NAME="L66"><B>S</B></A>
|
||||
<DD><A HREF="binary.htm#M15" NAME="L67"><B>i</B></A>
|
||||
<DD><A HREF="binary.htm#M16" NAME="L68"><B>I</B></A>
|
||||
<DD><A HREF="binary.htm#M17" NAME="L69"><B>f</B></A>
|
||||
<DD><A HREF="binary.htm#M18" NAME="L70"><B>d</B></A>
|
||||
<DD><A HREF="binary.htm#M19" NAME="L71"><B>x</B></A>
|
||||
<DD><A HREF="binary.htm#M20" NAME="L72"><B>X</B></A>
|
||||
<DD><A HREF="binary.htm#M21" NAME="L73"><B>@</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="binary.htm#M22" NAME="L74">BINARY SCAN</A>
|
||||
<DL>
|
||||
<DD><A HREF="binary.htm#M23" NAME="L75"><B>a</B></A>
|
||||
<DD><A HREF="binary.htm#M24" NAME="L76"><B>A</B></A>
|
||||
<DD><A HREF="binary.htm#M25" NAME="L77"><B>b</B></A>
|
||||
<DD><A HREF="binary.htm#M26" NAME="L78"><B>B</B></A>
|
||||
<DD><A HREF="binary.htm#M27" NAME="L79"><B>h</B></A>
|
||||
<DD><A HREF="binary.htm#M28" NAME="L80"><B>H</B></A>
|
||||
<DD><A HREF="binary.htm#M29" NAME="L81"><B>c</B></A>
|
||||
<DD><A HREF="binary.htm#M30" NAME="L82"><B>s</B></A>
|
||||
<DD><A HREF="binary.htm#M31" NAME="L83"><B>S</B></A>
|
||||
<DD><A HREF="binary.htm#M32" NAME="L84"><B>i</B></A>
|
||||
<DD><A HREF="binary.htm#M33" NAME="L85"><B>I</B></A>
|
||||
<DD><A HREF="binary.htm#M34" NAME="L86"><B>f</B></A>
|
||||
<DD><A HREF="binary.htm#M35" NAME="L87"><B>d</B></A>
|
||||
<DD><A HREF="binary.htm#M36" NAME="L88"><B>x</B></A>
|
||||
<DD><A HREF="binary.htm#M37" NAME="L89"><B>X</B></A>
|
||||
<DD><A HREF="binary.htm#M38" NAME="L90"><B>@</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="binary.htm#M39" NAME="L91">PLATFORM ISSUES</A>
|
||||
<DD><A HREF="binary.htm#M40" NAME="L92">SEE ALSO</A>
|
||||
<DD><A HREF="binary.htm#M41" NAME="L93">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
binary - Insert and extract fields from binary strings
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>binary format </B><I>formatString </I>?<I>arg arg ...</I>?<BR>
|
||||
<B>binary scan </B><I>string formatString </I>?<I>varName varName ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command provides facilities for manipulating binary data. The
|
||||
first form, <B>binary format</B>, creates a binary string from normal
|
||||
Tcl values. For example, given the values 16 and 22, on a 32 bit
|
||||
architecture, it might produce an 8-byte binary string consisting of
|
||||
two 4-byte integers, one for each of the numbers. The second form of
|
||||
the command, <B>binary scan</B>, does the opposite: it extracts data
|
||||
from a binary string and returns it as ordinary Tcl string values.
|
||||
|
||||
<H3><A NAME="M5">BINARY FORMAT</A></H3>
|
||||
The <B>binary format</B> command generates a binary string whose layout
|
||||
is specified by the <I>formatString</I> and whose contents come from
|
||||
the additional arguments. The resulting binary value is returned.
|
||||
<P>
|
||||
The <I>formatString</I> consists of a sequence of zero or more field
|
||||
specifiers separated by zero or more spaces. Each field specifier is
|
||||
a single type character followed by an optional numeric <I>count</I>.
|
||||
Most field specifiers consume one argument to obtain the value to be
|
||||
formatted. The type character specifies how the value is to be
|
||||
formatted. The <I>count</I> typically indicates how many items of the
|
||||
specified type are taken from the value. If present, the <I>count</I>
|
||||
is a non-negative decimal integer or <B>*</B>, which normally indicates
|
||||
that all of the items in the value are to be used. If the number of
|
||||
arguments does not match the number of fields in the format string
|
||||
that consume arguments, then an error is generated.
|
||||
<P>
|
||||
Each type-count pair moves an imaginary cursor through the binary
|
||||
data, storing bytes at the current position and advancing the cursor
|
||||
to just after the last byte stored. The cursor is initially at
|
||||
position 0 at the beginning of the data. The type may be any one of
|
||||
the following characters:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>a</B></A><DD>
|
||||
Stores a character string of length <I>count</I> in the output string.
|
||||
If <I>arg</I> has fewer than <I>count</I> bytes, then additional zero
|
||||
bytes are used to pad out the field. If <I>arg</I> is longer than the
|
||||
specified length, the extra characters will be ignored. If
|
||||
<I>count</I> is <B>*</B>, then all of the bytes in <I>arg</I> will be
|
||||
formatted. If <I>count</I> is omitted, then one character will be
|
||||
formatted. For example,
|
||||
<PRE><B>binary format a7a*a alpha bravo charlie</B></PRE>
|
||||
will return a string equivalent to <B>alpha\000\000bravoc</B>.
|
||||
<P><DT><A NAME="M7"><B>A</B></A><DD>
|
||||
This form is the same as <B>a</B> except that spaces are used for
|
||||
padding instead of nulls. For example,
|
||||
<PRE><B>binary format A6A*A alpha bravo charlie</B></PRE>
|
||||
will return <B>alpha bravoc</B>.
|
||||
<P><DT><A NAME="M8"><B>b</B></A><DD>
|
||||
Stores a string of <I>count</I> binary digits in low-to-high order
|
||||
within each byte in the output string. <I>Arg</I> must contain a
|
||||
sequence of <B>1</B> and <B>0</B> characters. The resulting bytes are
|
||||
emitted in first to last order with the bits being formatted in
|
||||
low-to-high order within each byte. If <I>arg</I> has fewer than
|
||||
<I>count</I> digits, then zeros will be used for the remaining bits.
|
||||
If <I>arg</I> has more than the specified number of digits, the extra
|
||||
digits will be ignored. If <I>count</I> is <B>*</B>, then all of the
|
||||
digits in <I>arg</I> will be formatted. If <I>count</I> is omitted,
|
||||
then one digit will be formatted. If the number of bits formatted
|
||||
does not end at a byte boundary, the remaining bits of the last byte
|
||||
will be zeros. For example,
|
||||
<PRE><B>binary format b5b* 11100 111000011010</B></PRE>
|
||||
will return a string equivalent to <B>\x07\x87\x05</B>.
|
||||
<P><DT><A NAME="M9"><B>B</B></A><DD>
|
||||
This form is the same as <B>b</B> except that the bits are stored in
|
||||
high-to-low order within each byte. For example,
|
||||
<PRE><B>binary format B5B* 11100 111000011010</B></PRE>
|
||||
will return a string equivalent to <B>\xe0\xe1\xa0</B>.
|
||||
<P><DT><A NAME="M10"><B>h</B></A><DD>
|
||||
Stores a string of <I>count</I> hexadecimal digits in low-to-high
|
||||
within each byte in the output string. <I>Arg</I> must contain a
|
||||
sequence of characters in the set ``0123456789abcdefABCDEF''. The
|
||||
resulting bytes are emitted in first to last order with the hex digits
|
||||
being formatted in low-to-high order within each byte. If <I>arg</I>
|
||||
has fewer than <I>count</I> digits, then zeros will be used for the
|
||||
remaining digits. If <I>arg</I> has more than the specified number of
|
||||
digits, the extra digits will be ignored. If <I>count</I> is
|
||||
<B>*</B>, then all of the digits in <I>arg</I> will be formatted. If
|
||||
<I>count</I> is omitted, then one digit will be formatted. If the
|
||||
number of digits formatted does not end at a byte boundary, the
|
||||
remaining bits of the last byte will be zeros. For example,
|
||||
<PRE><B>binary format h3h* AB def</B></PRE>
|
||||
will return a string equivalent to <B>\xba\x00\xed\x0f</B>.
|
||||
<P><DT><A NAME="M11"><B>H</B></A><DD>
|
||||
This form is the same as <B>h</B> except that the digits are stored in
|
||||
high-to-low order within each byte. For example,
|
||||
<PRE><B>binary format H3H* ab DEF</B></PRE>
|
||||
will return a string equivalent to <B>\xab\x00\xde\xf0</B>.
|
||||
<P><DT><A NAME="M12"><B>c</B></A><DD>
|
||||
Stores one or more 8-bit integer values in the output string. If no
|
||||
<I>count</I> is specified, then <I>arg</I> must consist of an integer
|
||||
value; otherwise <I>arg</I> must consist of a list containing at least
|
||||
<I>count</I> integer elements. The low-order 8 bits of each integer
|
||||
are stored as a one-byte value at the cursor position. If <I>count</I>
|
||||
is <B>*</B>, then all of the integers in the list are formatted. If
|
||||
the number of elements in the list is fewer than <I>count</I>, then an
|
||||
error is generated. If the number of elements in the list is greater
|
||||
than <I>count</I>, then the extra elements are ignored. For example,
|
||||
<PRE><B>binary format c3cc* {3 -3 128 1} 260 {2 5}</B></PRE>
|
||||
will return a string equivalent to
|
||||
<B>\x03\xfd\x80\x04\x02\x05</B>, whereas
|
||||
<PRE><B>binary format c {2 5}</B></PRE>
|
||||
will generate an error.
|
||||
<P><DT><A NAME="M13"><B>s</B></A><DD>
|
||||
This form is the same as <B>c</B> except that it stores one or more
|
||||
16-bit integers in little-endian byte order in the output string. The
|
||||
low-order 16-bits of each integer are stored as a two-byte value at
|
||||
the cursor position with the least significant byte stored first. For
|
||||
example,
|
||||
<PRE><B>binary format s3 {3 -3 258 1}</B></PRE>
|
||||
will return a string equivalent to
|
||||
<B>\x03\x00\xfd\xff\x02\x01</B>.
|
||||
<P><DT><A NAME="M14"><B>S</B></A><DD>
|
||||
This form is the same as <B>s</B> except that it stores one or more
|
||||
16-bit integers in big-endian byte order in the output string. For
|
||||
example,
|
||||
<PRE><B>binary format S3 {3 -3 258 1}</B></PRE>
|
||||
will return a string equivalent to
|
||||
<B>\x00\x03\xff\xfd\x01\x02</B>.
|
||||
<P><DT><A NAME="M15"><B>i</B></A><DD>
|
||||
This form is the same as <B>c</B> except that it stores one or more
|
||||
32-bit integers in little-endian byte order in the output string. The
|
||||
low-order 32-bits of each integer are stored as a four-byte value at
|
||||
the cursor position with the least significant byte stored first. For
|
||||
example,
|
||||
<PRE><B>binary format i3 {3 -3 65536 1}</B></PRE>
|
||||
will return a string equivalent to
|
||||
<B>\x03\x00\x00\x00\xfd\xff\xff\xff\x00\x00\x01\x00</B>
|
||||
<P><DT><A NAME="M16"><B>I</B></A><DD>
|
||||
This form is the same as <B>i</B> except that it stores one or more one
|
||||
or more 32-bit integers in big-endian byte order in the output string.
|
||||
For example,
|
||||
<PRE><B>binary format I3 {3 -3 65536 1}</B></PRE>
|
||||
will return a string equivalent to
|
||||
<B>\x00\x00\x00\x03\xff\xff\xff\xfd\x00\x01\x00\x00</B>
|
||||
<P><DT><A NAME="M17"><B>f</B></A><DD>
|
||||
This form is the same as <B>c</B> except that it stores one or more one
|
||||
or more single-precision floating in the machine's native
|
||||
representation in the output string. This representation is not
|
||||
portable across architectures, so it should not be used to communicate
|
||||
floating point numbers across the network. The size of a floating
|
||||
point number may vary across architectures, so the number of bytes
|
||||
that are generated may vary. If the value overflows the
|
||||
machine's native representation, then the value of FLT_MAX
|
||||
as defined by the system will be used instead. Because Tcl uses
|
||||
double-precision floating-point numbers internally, there may be some
|
||||
loss of precision in the conversion to single-precision. For example,
|
||||
on a Windows system running on an Intel Pentium processor,
|
||||
<PRE><B>binary format f2 {1.6 3.4}</B></PRE>
|
||||
will return a string equivalent to
|
||||
<B>\xcd\xcc\xcc\x3f\x9a\x99\x59\x40</B>.
|
||||
<P><DT><A NAME="M18"><B>d</B></A><DD>
|
||||
This form is the same as <B>f</B> except that it stores one or more one
|
||||
or more double-precision floating in the machine's native
|
||||
representation in the output string. For example, on a
|
||||
Windows system running on an Intel Pentium processor,
|
||||
<PRE><B>binary format d1 {1.6}</B></PRE>
|
||||
will return a string equivalent to
|
||||
<B>\x9a\x99\x99\x99\x99\x99\xf9\x3f</B>.
|
||||
<P><DT><A NAME="M19"><B>x</B></A><DD>
|
||||
Stores <I>count</I> null bytes in the output string. If <I>count</I> is
|
||||
not specified, stores one null byte. If <I>count</I> is <B>*</B>,
|
||||
generates an error. This type does not consume an argument. For
|
||||
example,
|
||||
<PRE><B>binary format a3xa3x2a3 abc def ghi</B></PRE>
|
||||
will return a string equivalent to <B>abc\000def\000\000ghi</B>.
|
||||
<P><DT><A NAME="M20"><B>X</B></A><DD>
|
||||
Moves the cursor back <I>count</I> bytes in the output string. If
|
||||
<I>count</I> is <B>*</B> or is larger than the current cursor position,
|
||||
then the cursor is positioned at location 0 so that the next byte
|
||||
stored will be the first byte in the result string. If <I>count</I> is
|
||||
omitted then the cursor is moved back one byte. This type does not
|
||||
consume an argument. For example,
|
||||
<PRE><B>binary format a3X*a3X2a3 abc def ghi</B></PRE>
|
||||
will return <B>dghi</B>.
|
||||
<P><DT><A NAME="M21"><B>@</B></A><DD>
|
||||
Moves the cursor to the absolute location in the output string
|
||||
specified by <I>count</I>. Position 0 refers to the first byte in the
|
||||
output string. If <I>count</I> refers to a position beyond the last
|
||||
byte stored so far, then null bytes will be placed in the unitialized
|
||||
locations and the cursor will be placed at the specified location. If
|
||||
<I>count</I> is <B>*</B>, then the cursor is moved to the current end of
|
||||
the output string. If <I>count</I> is omitted, then an error will be
|
||||
generated. This type does not consume an argument. For example,
|
||||
<PRE><B>binary format a5@2a1@*a3@10a1 abcde f ghi j</B></PRE>
|
||||
will return <B>abfdeghi\000\000j</B>.
|
||||
<P></DL>
|
||||
<H3><A NAME="M22">BINARY SCAN</A></H3>
|
||||
The <B>binary scan</B> command parses fields from a binary string,
|
||||
returning the number of conversions performed. <I>String</I> gives the
|
||||
input to be parsed and <I>formatString</I> indicates how to parse it.
|
||||
Each <I>varName</I> gives the name of a variable; when a field is
|
||||
scanned from <I>string</I> the result is assigned to the corresponding
|
||||
variable.
|
||||
<P>
|
||||
As with <B>binary format</B>, the <I>formatString</I> consists of a
|
||||
sequence of zero or more field specifiers separated by zero or more
|
||||
spaces. Each field specifier is a single type character followed by
|
||||
an optional numeric <I>count</I>. Most field specifiers consume one
|
||||
argument to obtain the variable into which the scanned values should
|
||||
be placed. The type character specifies how the binary data is to be
|
||||
interpreted. The <I>count</I> typically indicates how many items of
|
||||
the specified type are taken from the data. If present, the
|
||||
<I>count</I> is a non-negative decimal integer or <B>*</B>, which
|
||||
normally indicates that all of the remaining items in the data are to
|
||||
be used. If there are not enough bytes left after the current cursor
|
||||
position to satisfy the current field specifier, then the
|
||||
corresponding variable is left untouched and <B>binary scan</B> returns
|
||||
immediately with the number of variables that were set. If there are
|
||||
not enough arguments for all of the fields in the format string that
|
||||
consume arguments, then an error is generated.
|
||||
<P>
|
||||
It is <B>important</B> to note that the <B>c</B>, <B>s</B>, and <B>S</B>
|
||||
(and <B>i</B> and <B>I</B> on 64bit systems) will be scanned into
|
||||
long data size values. In doing this, values that have their high
|
||||
bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints),
|
||||
will be sign extended. Thus the following will occur:
|
||||
<PRE><B>set signShort [binary format s1 0x8000]</B>
|
||||
<B>binary scan $signShort s1 val; </B><I># val == 0xFFFF8000</I></PRE>
|
||||
If you want to produce an unsigned value, then you can mask the return
|
||||
value to the desired size. For example, to produce an unsigned short
|
||||
value:
|
||||
<PRE><B>set val [expr {$val & 0xFFFF}]; </B><I># val == 0x8000</I></PRE>
|
||||
<P>
|
||||
Each type-count pair moves an imaginary cursor through the binary data,
|
||||
reading bytes from the current position. The cursor is initially
|
||||
at position 0 at the beginning of the data. The type may be any one of
|
||||
the following characters:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M23"><B>a</B></A><DD>
|
||||
The data is a character string of length <I>count</I>. If <I>count</I>
|
||||
is <B>*</B>, then all of the remaining bytes in <I>string</I> will be
|
||||
scanned into the variable. If <I>count</I> is omitted, then one
|
||||
character will be scanned. For example,
|
||||
<PRE><B>binary scan abcde\000fghi a6a10 var1 var2</B></PRE>
|
||||
will return <B>1</B> with the string equivalent to <B>abcde\000</B>
|
||||
stored in <B>var1</B> and <B>var2</B> left unmodified.
|
||||
<P><DT><A NAME="M24"><B>A</B></A><DD>
|
||||
This form is the same as <B>a</B>, except trailing blanks and nulls are stripped from
|
||||
the scanned value before it is stored in the variable. For example,
|
||||
<PRE><B>binary scan "abc efghi \000" A* var1</B></PRE>
|
||||
will return <B>1</B> with <B>abc efghi</B> stored in <B>var1</B>.
|
||||
<P><DT><A NAME="M25"><B>b</B></A><DD>
|
||||
The data is turned into a string of <I>count</I> binary digits in
|
||||
low-to-high order represented as a sequence of ``1'' and ``0''
|
||||
characters. The data bytes are scanned in first to last order with
|
||||
the bits being taken in low-to-high order within each byte. Any extra
|
||||
bits in the last byte are ignored. If <I>count</I> is <B>*</B>, then
|
||||
all of the remaining bits in <B><A HREF="../TkCmd/string.htm">string</A></B> will be scanned. If
|
||||
<I>count</I> is omitted, then one bit will be scanned. For example,
|
||||
<PRE><B>binary scan \x07\x87\x05 b5b* var1 var2</B></PRE>
|
||||
will return <B>2</B> with <B>11100</B> stored in <B>var1</B> and
|
||||
<B>1110000110100000</B> stored in <B>var2</B>.
|
||||
<P><DT><A NAME="M26"><B>B</B></A><DD>
|
||||
This form is the same as <B>b</B>, except the bits are taken in
|
||||
high-to-low order within each byte. For example,
|
||||
<PRE><B>binary scan \x70\x87\x05 B5B* var1 var2</B></PRE>
|
||||
will return <B>2</B> with <B>01110</B> stored in <B>var1</B> and
|
||||
<B>1000011100000101</B> stored in <B>var2</B>.
|
||||
<P><DT><A NAME="M27"><B>h</B></A><DD>
|
||||
The data is turned into a string of <I>count</I> hexadecimal digits in
|
||||
low-to-high order represented as a sequence of characters in the set
|
||||
``0123456789abcdef''. The data bytes are scanned in first to last
|
||||
order with the hex digits being taken in low-to-high order within each
|
||||
byte. Any extra bits in the last byte are ignored. If <I>count</I>
|
||||
is <B>*</B>, then all of the remaining hex digits in <B><A HREF="../TkCmd/string.htm">string</A></B> will be
|
||||
scanned. If <I>count</I> is omitted, then one hex digit will be
|
||||
scanned. For example,
|
||||
<PRE><B>binary scan \x07\x86\x05 h3h* var1 var2</B></PRE>
|
||||
will return <B>2</B> with <B>706</B> stored in <B>var1</B> and
|
||||
<B>50</B> stored in <B>var2</B>.
|
||||
<P><DT><A NAME="M28"><B>H</B></A><DD>
|
||||
This form is the same as <B>h</B>, except the digits are taken in
|
||||
high-to-low order within each byte. For example,
|
||||
<PRE><B>binary scan \x07\x86\x05 H3H* var1 var2</B></PRE>
|
||||
will return <B>2</B> with <B>078</B> stored in <B>var1</B> and
|
||||
<B>05</B> stored in <B>var2</B>.
|
||||
<P><DT><A NAME="M29"><B>c</B></A><DD>
|
||||
The data is turned into <I>count</I> 8-bit signed integers and stored
|
||||
in the corresponding variable as a list. If <I>count</I> is <B>*</B>,
|
||||
then all of the remaining bytes in <B><A HREF="../TkCmd/string.htm">string</A></B> will be scanned. If
|
||||
<I>count</I> is omitted, then one 8-bit integer will be scanned. For
|
||||
example,
|
||||
<PRE><B>binary scan \x07\x86\x05 c2c* var1 var2</B></PRE>
|
||||
will return <B>2</B> with <B>7 -122</B> stored in <B>var1</B> and <B>5</B>
|
||||
stored in <B>var2</B>. Note that the integers returned are signed, but
|
||||
they can be converted to unsigned 8-bit quantities using an expression
|
||||
like:
|
||||
<PRE><B>expr ( $num + 0x100 ) % 0x100</B></PRE>
|
||||
<P><DT><A NAME="M30"><B>s</B></A><DD>
|
||||
The data is interpreted as <I>count</I> 16-bit signed integers
|
||||
represented in little-endian byte order. The integers are stored in
|
||||
the corresponding variable as a list. If <I>count</I> is <B>*</B>, then
|
||||
all of the remaining bytes in <B><A HREF="../TkCmd/string.htm">string</A></B> will be scanned. If
|
||||
<I>count</I> is omitted, then one 16-bit integer will be scanned. For
|
||||
example,
|
||||
<PRE><B>binary scan \x05\x00\x07\x00\xf0\xff s2s* var1 var2</B></PRE>
|
||||
will return <B>2</B> with <B>5 7</B> stored in <B>var1</B> and <B>-16</B>
|
||||
stored in <B>var2</B>. Note that the integers returned are signed, but
|
||||
they can be converted to unsigned 16-bit quantities using an expression
|
||||
like:
|
||||
<PRE><B>expr ( $num + 0x10000 ) % 0x10000</B></PRE>
|
||||
<P><DT><A NAME="M31"><B>S</B></A><DD>
|
||||
This form is the same as <B>s</B> except that the data is interpreted
|
||||
as <I>count</I> 16-bit signed integers represented in big-endian byte
|
||||
order. For example,
|
||||
<PRE><B>binary scan \x00\x05\x00\x07\xff\xf0 S2S* var1 var2</B></PRE>
|
||||
will return <B>2</B> with <B>5 7</B> stored in <B>var1</B> and <B>-16</B>
|
||||
stored in <B>var2</B>.
|
||||
<P><DT><A NAME="M32"><B>i</B></A><DD>
|
||||
The data is interpreted as <I>count</I> 32-bit signed integers
|
||||
represented in little-endian byte order. The integers are stored in
|
||||
the corresponding variable as a list. If <I>count</I> is <B>*</B>, then
|
||||
all of the remaining bytes in <B><A HREF="../TkCmd/string.htm">string</A></B> will be scanned. If
|
||||
<I>count</I> is omitted, then one 32-bit integer will be scanned. For
|
||||
example,
|
||||
<PRE><B>binary scan \x05\x00\x00\x00\x07\x00\x00\x00\xf0\xff\xff\xff i2i* var1 var2</B></PRE>
|
||||
will return <B>2</B> with <B>5 7</B> stored in <B>var1</B> and <B>-16</B>
|
||||
stored in <B>var2</B>. Note that the integers returned are signed and
|
||||
cannot be represented by Tcl as unsigned values.
|
||||
<P><DT><A NAME="M33"><B>I</B></A><DD>
|
||||
This form is the same as <B>I</B> except that the data is interpreted
|
||||
as <I>count</I> 32-bit signed integers represented in big-endian byte
|
||||
order. For example,
|
||||
<PRE><B>binary \x00\x00\x00\x05\x00\x00\x00\x07\xff\xff\xff\xf0 I2I* var1 var2</B></PRE>
|
||||
will return <B>2</B> with <B>5 7</B> stored in <B>var1</B> and <B>-16</B>
|
||||
stored in <B>var2</B>.
|
||||
<P><DT><A NAME="M34"><B>f</B></A><DD>
|
||||
The data is interpreted as <I>count</I> single-precision floating point
|
||||
numbers in the machine's native representation. The floating point
|
||||
numbers are stored in the corresponding variable as a list. If
|
||||
<I>count</I> is <B>*</B>, then all of the remaining bytes in
|
||||
<B><A HREF="../TkCmd/string.htm">string</A></B> will be scanned. If <I>count</I> is omitted, then one
|
||||
single-precision floating point number will be scanned. The size of a
|
||||
floating point number may vary across architectures, so the number of
|
||||
bytes that are scanned may vary. If the data does not represent a
|
||||
valid floating point number, the resulting value is undefined and
|
||||
compiler dependent. For example, on a Windows system running on an
|
||||
Intel Pentium processor,
|
||||
<PRE><B>binary scan \x3f\xcc\xcc\xcd f var1</B></PRE>
|
||||
will return <B>1</B> with <B>1.6000000238418579</B> stored in
|
||||
<B>var1</B>.
|
||||
<P><DT><A NAME="M35"><B>d</B></A><DD>
|
||||
This form is the same as <B>f</B> except that the data is interpreted
|
||||
as <I>count</I> double-precision floating point numbers in the
|
||||
machine's native representation. For example, on a Windows system
|
||||
running on an Intel Pentium processor,
|
||||
<PRE><B>binary scan \x9a\x99\x99\x99\x99\x99\xf9\x3f d var1</B></PRE>
|
||||
will return <B>1</B> with <B>1.6000000000000001</B>
|
||||
stored in <B>var1</B>.
|
||||
<P><DT><A NAME="M36"><B>x</B></A><DD>
|
||||
Moves the cursor forward <I>count</I> bytes in <I>string</I>. If
|
||||
<I>count</I> is <B>*</B> or is larger than the number of bytes after the
|
||||
current cursor cursor position, then the cursor is positioned after
|
||||
the last byte in <I>string</I>. If <I>count</I> is omitted, then the
|
||||
cursor is moved forward one byte. Note that this type does not
|
||||
consume an argument. For example,
|
||||
<PRE><B>binary scan \x01\x02\x03\x04 x2H* var1</B></PRE>
|
||||
will return <B>1</B> with <B>0304</B> stored in <B>var1</B>.
|
||||
<P><DT><A NAME="M37"><B>X</B></A><DD>
|
||||
Moves the cursor back <I>count</I> bytes in <I>string</I>. If
|
||||
<I>count</I> is <B>*</B> or is larger than the current cursor position,
|
||||
then the cursor is positioned at location 0 so that the next byte
|
||||
scanned will be the first byte in <I>string</I>. If <I>count</I>
|
||||
is omitted then the cursor is moved back one byte. Note that this
|
||||
type does not consume an argument. For example,
|
||||
<PRE><B>binary scan \x01\x02\x03\x04 c2XH* var1 var2</B></PRE>
|
||||
will return <B>2</B> with <B>1 2</B> stored in <B>var1</B> and <B>020304</B>
|
||||
stored in <B>var2</B>.
|
||||
<P><DT><A NAME="M38"><B>@</B></A><DD>
|
||||
Moves the cursor to the absolute location in the data string specified
|
||||
by <I>count</I>. Note that position 0 refers to the first byte in
|
||||
<I>string</I>. If <I>count</I> refers to a position beyond the end of
|
||||
<I>string</I>, then the cursor is positioned after the last byte. If
|
||||
<I>count</I> is omitted, then an error will be generated. For example,
|
||||
<PRE><B>binary scan \x01\x02\x03\x04 c2@1H* var1 var2</B></PRE>
|
||||
will return <B>2</B> with <B>1 2</B> stored in <B>var1</B> and <B>020304</B>
|
||||
stored in <B>var2</B>.
|
||||
<P></DL>
|
||||
<H3><A NAME="M39">PLATFORM ISSUES</A></H3>
|
||||
Sometimes it is desirable to format or scan integer values in the
|
||||
native byte order for the machine. Refer to the <B>byteOrder</B>
|
||||
element of the <B>tcl_platform</B> array to decide which type character
|
||||
to use when formatting or scanning integers.
|
||||
|
||||
<H3><A NAME="M40">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/format.htm">format</A></B>, <B><A HREF="../TkCmd/scan.htm">scan</A></B>, <B><A HREF="../TkCmd/tclvars.htm">tclvars</A></B>
|
||||
<H3><A NAME="M41">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#binary">binary</A>, <A href="../Keywords/F.htm#format">format</A>, <A href="../Keywords/S.htm#scan">scan</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1997 by Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
26
hlp/en/tcl/break.htm
Normal file
26
hlp/en/tcl/break.htm
Normal file
@@ -0,0 +1,26 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - break manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
break - Abort looping command
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>break</B><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command is typically invoked inside the body of a looping command
|
||||
such as <B><A HREF="../TkCmd/for.htm">for</A></B> or <B><A HREF="../TkCmd/foreach.htm">foreach</A></B> or <B><A HREF="../TkCmd/while.htm">while</A></B>.
|
||||
It returns a TCL_BREAK code, which causes a break exception
|
||||
to occur.
|
||||
The exception causes the current script to be aborted
|
||||
out to the innermost containing loop command, which then
|
||||
aborts its execution and returns normally.
|
||||
Break exceptions are also handled in a few other situations, such
|
||||
as the <B><A HREF="../TkCmd/catch.htm">catch</A></B> command, Tk event bindings, and the outermost
|
||||
scripts of procedure bodies.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/catch.htm">catch</A></B>, <B><A HREF="../TkCmd/continue.htm">continue</A></B>, <B><A HREF="../TkCmd/for.htm">for</A></B>, <B><A HREF="../TkCmd/foreach.htm">foreach</A></B>, <B><A HREF="../TkCmd/while.htm">while</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#abort">abort</A>, <A href="../Keywords/B.htm#break">break</A>, <A href="../Keywords/L.htm#loop">loop</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993-1994 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
50
hlp/en/tcl/catch.htm
Normal file
50
hlp/en/tcl/catch.htm
Normal file
@@ -0,0 +1,50 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - catch manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
catch - Evaluate script and trap exceptional returns
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>catch</B><I> script </I>?<I>varName</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>catch</B> command may be used to prevent errors from aborting command
|
||||
interpretation. <B>Catch</B> calls the Tcl interpreter recursively to
|
||||
execute <I>script</I>, and always returns without raising an error,
|
||||
regardless of any errors that might occur while executing <I>script</I>.
|
||||
<P>
|
||||
If <I>script</I> raises an error, <B>catch</B> will return a non-zero integer
|
||||
value corresponding to one of the exceptional return codes (see tcl.h
|
||||
for the definitions of code values). If the <I>varName</I> argument is
|
||||
given, then the variable it names is set to the error message from
|
||||
interpreting <I>script</I>.
|
||||
<P>
|
||||
If <I>script</I> does not raise an error, <B>catch</B> will return 0
|
||||
(TCL_OK) and set the variable to the value returned from <I>script</I>.
|
||||
<P>
|
||||
Note that <B>catch</B> catches all exceptions, including those
|
||||
generated by <B><A HREF="../TkCmd/break.htm">break</A></B> and <B><A HREF="../TkCmd/continue.htm">continue</A></B> as well as errors. The
|
||||
only errors that are not caught are syntax errors found when the
|
||||
script is compiled. This is because the catch command only catches
|
||||
errors during runtime. When the catch statement is compiled, the
|
||||
script is compiled as well and any syntax errors will generate a Tcl
|
||||
error.
|
||||
|
||||
<H3><A NAME="M5">EXAMPLES</A></H3>
|
||||
The <B>catch</B> command may be used in an <B><A HREF="../TkCmd/if.htm">if</A></B> to branch based on
|
||||
the success of a script.
|
||||
|
||||
<PRE>if { [catch {open $someFile w} fid] } {
|
||||
puts stderr "Could not open $someFile for writing\n$fid"
|
||||
exit 1
|
||||
}</PRE>
|
||||
The <B>catch</B> command will not catch compiled syntax errors. The
|
||||
first time proc <B>foo</B> is called, the body will be compiled and a
|
||||
Tcl error will be generated.
|
||||
|
||||
<PRE>proc foo {} {
|
||||
catch {expr {1 +- }}
|
||||
}</PRE>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#catch">catch</A>, <A href="../Keywords/E.htm#error">error</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993-1994 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
20
hlp/en/tcl/cd.htm
Normal file
20
hlp/en/tcl/cd.htm
Normal file
@@ -0,0 +1,20 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - cd manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
cd - Change working directory
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>cd </B>?<I>dirName</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Change the current working directory to <I>dirName</I>, or to the
|
||||
home directory (as specified in the HOME environment variable) if
|
||||
<I>dirName</I> is not given.
|
||||
Returns an empty string.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/filename.htm">filename</A></B>, <B><A HREF="../TkCmd/glob.htm">glob</A></B>, <B><A HREF="../TkCmd/pwd.htm">pwd</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/W.htm#working directory">working directory</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
251
hlp/en/tcl/clock.htm
Normal file
251
hlp/en/tcl/clock.htm
Normal file
@@ -0,0 +1,251 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - clock manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="clock.htm#M2" NAME="L109">NAME</A>
|
||||
<DL><DD>clock - Obtain and manipulate time</DL>
|
||||
<DD><A HREF="clock.htm#M3" NAME="L110">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>clock </B><I>option</I> ?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="clock.htm#M4" NAME="L111">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="clock.htm#M5" NAME="L112">.VS 8.3</A>
|
||||
<DD><A HREF="clock.htm#M6" NAME="L113"><B>clock format </B><I>clockValue</I> ?<B>-format </B><I>string</I>? ?<B>-gmt </B><I>boolean</I>?</A>
|
||||
<DL>
|
||||
<DD><A HREF="clock.htm#M7" NAME="L114"><B>%%</B></A>
|
||||
<DD><A HREF="clock.htm#M8" NAME="L115"><B>%a</B></A>
|
||||
<DD><A HREF="clock.htm#M9" NAME="L116"><B>%A</B></A>
|
||||
<DD><A HREF="clock.htm#M10" NAME="L117"><B>%b</B></A>
|
||||
<DD><A HREF="clock.htm#M11" NAME="L118"><B>%B</B></A>
|
||||
<DD><A HREF="clock.htm#M12" NAME="L119"><B>%c</B></A>
|
||||
<DD><A HREF="clock.htm#M13" NAME="L120"><B>%d</B></A>
|
||||
<DD><A HREF="clock.htm#M14" NAME="L121"><B>%H</B></A>
|
||||
<DD><A HREF="clock.htm#M15" NAME="L122"><B>%I</B></A>
|
||||
<DD><A HREF="clock.htm#M16" NAME="L123"><B>%j</B></A>
|
||||
<DD><A HREF="clock.htm#M17" NAME="L124"><B>%m</B></A>
|
||||
<DD><A HREF="clock.htm#M18" NAME="L125"><B>%M</B></A>
|
||||
<DD><A HREF="clock.htm#M19" NAME="L126"><B>%p</B></A>
|
||||
<DD><A HREF="clock.htm#M20" NAME="L127"><B>%S</B></A>
|
||||
<DD><A HREF="clock.htm#M21" NAME="L128"><B>%U</B></A>
|
||||
<DD><A HREF="clock.htm#M22" NAME="L129"><B>%w</B></A>
|
||||
<DD><A HREF="clock.htm#M23" NAME="L130"><B>%W</B></A>
|
||||
<DD><A HREF="clock.htm#M24" NAME="L131"><B>%x</B></A>
|
||||
<DD><A HREF="clock.htm#M25" NAME="L132"><B>%X</B></A>
|
||||
<DD><A HREF="clock.htm#M26" NAME="L133"><B>%y</B></A>
|
||||
<DD><A HREF="clock.htm#M27" NAME="L134"><B>%Y</B></A>
|
||||
<DD><A HREF="clock.htm#M28" NAME="L135"><B>%Z</B></A>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="clock.htm#M29" NAME="L136"><B>%D</B></A>
|
||||
<DD><A HREF="clock.htm#M30" NAME="L137"><B>%e</B></A>
|
||||
<DD><A HREF="clock.htm#M31" NAME="L138"><B>%h</B></A>
|
||||
<DD><A HREF="clock.htm#M32" NAME="L139"><B>%n</B></A>
|
||||
<DD><A HREF="clock.htm#M33" NAME="L140"><B>%r</B></A>
|
||||
<DD><A HREF="clock.htm#M34" NAME="L141"><B>%R</B></A>
|
||||
<DD><A HREF="clock.htm#M35" NAME="L142"><B>%t</B></A>
|
||||
<DD><A HREF="clock.htm#M36" NAME="L143"><B>%T</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="clock.htm#M37" NAME="L144"><B>clock scan </B><I>dateString</I> ?<B>-base </B><I>clockVal</I>? ?<B>-gmt </B><I>boolean</I>?</A>
|
||||
<DL>
|
||||
<DD><A HREF="clock.htm#M38" NAME="L145"><I>time</I></A>
|
||||
<DD><A HREF="clock.htm#M39" NAME="L146"><I>date</I></A>
|
||||
<DD><A HREF="clock.htm#M40" NAME="L147"><I>ISO 8601 point-in-time</I></A>
|
||||
<DD><A HREF="clock.htm#M41" NAME="L148"><I>relative time</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="clock.htm#M42" NAME="L149"><B>clock seconds</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="clock.htm#M43" NAME="L150">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
clock - Obtain and manipulate time
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>clock </B><I>option</I> ?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command performs one of several operations that may obtain
|
||||
or manipulate strings or values that represent some notion of
|
||||
time. The <I>option</I> argument determines what action is carried
|
||||
out by the command. The legal <I>options</I> (which may be
|
||||
abbreviated) are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5">.VS 8.3</A><DD>
|
||||
<B>clock clicks</B> ?<B>-milliseconds</B>?
|
||||
Return a high-resolution time value as a system-dependent integer
|
||||
value. The unit of the value is system-dependent but should be the
|
||||
highest resolution clock available on the system such as a CPU cycle
|
||||
counter. If <B>-milliseconds</B> is specified, then the value is
|
||||
guaranteed to be of millisecond granularity.
|
||||
This value should only be used for the relative measurement
|
||||
of elapsed time.
|
||||
<P><DT><A NAME="M6"><B>clock format </B><I>clockValue</I> ?<B>-format </B><I>string</I>? ?<B>-gmt </B><I>boolean</I>?</A><DD>
|
||||
Converts an integer time value, typically returned by
|
||||
<B>clock seconds</B>, <B>clock scan</B>, or the <B>atime</B>, <B>mtime</B>,
|
||||
or <B>ctime</B> options of the <B><A HREF="../TkCmd/file.htm">file</A></B> command, to human-readable
|
||||
form. If the <B>-format</B> argument is present the next argument is a
|
||||
string that describes how the date and time are to be formatted.
|
||||
Field descriptors consist of a <B>%</B> followed by a field
|
||||
descriptor character. All other characters are copied into the result.
|
||||
Valid field descriptors are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M7"><B>%%</B></A><DD>
|
||||
Insert a %.
|
||||
<P><DT><A NAME="M8"><B>%a</B></A><DD>
|
||||
Abbreviated weekday name (Mon, Tue, etc.).
|
||||
<P><DT><A NAME="M9"><B>%A</B></A><DD>
|
||||
Full weekday name (Monday, Tuesday, etc.).
|
||||
<P><DT><A NAME="M10"><B>%b</B></A><DD>
|
||||
Abbreviated month name (Jan, Feb, etc.).
|
||||
<P><DT><A NAME="M11"><B>%B</B></A><DD>
|
||||
Full month name.
|
||||
<P><DT><A NAME="M12"><B>%c</B></A><DD>
|
||||
Locale specific date and time.
|
||||
<P><DT><A NAME="M13"><B>%d</B></A><DD>
|
||||
Day of month (01 - 31).
|
||||
<P><DT><A NAME="M14"><B>%H</B></A><DD>
|
||||
Hour in 24-hour format (00 - 23).
|
||||
<P><DT><A NAME="M15"><B>%I</B></A><DD>
|
||||
Hour in 12-hour format (00 - 12).
|
||||
<P><DT><A NAME="M16"><B>%j</B></A><DD>
|
||||
Day of year (001 - 366).
|
||||
<P><DT><A NAME="M17"><B>%m</B></A><DD>
|
||||
Month number (01 - 12).
|
||||
<P><DT><A NAME="M18"><B>%M</B></A><DD>
|
||||
Minute (00 - 59).
|
||||
<P><DT><A NAME="M19"><B>%p</B></A><DD>
|
||||
AM/PM indicator.
|
||||
<P><DT><A NAME="M20"><B>%S</B></A><DD>
|
||||
Seconds (00 - 59).
|
||||
<P><DT><A NAME="M21"><B>%U</B></A><DD>
|
||||
Week of year (00 - 52), Sunday is the first day of the week.
|
||||
<P><DT><A NAME="M22"><B>%w</B></A><DD>
|
||||
Weekday number (Sunday = 0).
|
||||
<P><DT><A NAME="M23"><B>%W</B></A><DD>
|
||||
Week of year (00 - 52), Monday is the first day of the week.
|
||||
<P><DT><A NAME="M24"><B>%x</B></A><DD>
|
||||
Locale specific date format.
|
||||
<P><DT><A NAME="M25"><B>%X</B></A><DD>
|
||||
Locale specific time format.
|
||||
<P><DT><A NAME="M26"><B>%y</B></A><DD>
|
||||
Year without century (00 - 99).
|
||||
<P><DT><A NAME="M27"><B>%Y</B></A><DD>
|
||||
Year with century (e.g. 1990)
|
||||
<P><DT><A NAME="M28"><B>%Z</B></A><DD>
|
||||
Time zone name.
|
||||
<P></DL>
|
||||
<P>
|
||||
<DL><P><DD>
|
||||
In addition, the following field descriptors may be supported on some
|
||||
systems (e.g. Unix but not Windows):
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M29"><B>%D</B></A><DD>
|
||||
Date as %m/%d/%y.
|
||||
<P><DT><A NAME="M30"><B>%e</B></A><DD>
|
||||
Day of month (1 - 31), no leading zeros.
|
||||
<P><DT><A NAME="M31"><B>%h</B></A><DD>
|
||||
Abbreviated month name.
|
||||
<P><DT><A NAME="M32"><B>%n</B></A><DD>
|
||||
Insert a newline.
|
||||
<P><DT><A NAME="M33"><B>%r</B></A><DD>
|
||||
Time as %I:%M:%S %p.
|
||||
<P><DT><A NAME="M34"><B>%R</B></A><DD>
|
||||
Time as %H:%M.
|
||||
<P><DT><A NAME="M35"><B>%t</B></A><DD>
|
||||
Insert a tab.
|
||||
<P><DT><A NAME="M36"><B>%T</B></A><DD>
|
||||
Time as %H:%M:%S.
|
||||
<P></DL>
|
||||
</DL>
|
||||
<P>
|
||||
<DL><P><DD>
|
||||
If the <B>-format</B> argument is not specified, the format string
|
||||
"<B>%a %b %d %H:%M:%S %Z %Y</B>" is used. If the <B>-gmt</B> argument
|
||||
is present the next argument must be a boolean which if true specifies
|
||||
that the time will be formatted as Greenwich Mean Time. If false
|
||||
then the local timezone will be used as defined by the operating
|
||||
environment.
|
||||
</DL>
|
||||
<P><DT><A NAME="M37"><B>clock scan </B><I>dateString</I> ?<B>-base </B><I>clockVal</I>? ?<B>-gmt </B><I>boolean</I>?</A><DD>
|
||||
Convert <I>dateString</I> to an integer clock value (see <B>clock seconds</B>).
|
||||
This command can parse and convert virtually any standard date and/or time
|
||||
string, which can include standard time zone mnemonics. If only a time is
|
||||
specified, the current date is assumed. If the string does not contain a
|
||||
time zone mnemonic, the local time zone is assumed, unless the <B>-gmt</B>
|
||||
argument is true, in which case the clock value is calculated assuming
|
||||
that the specified time is relative to Greenwich Mean Time.
|
||||
<B>-gmt</B>, if specified, affects only the computed time value; it does not
|
||||
impact the interpretation of <B>-base</B>.
|
||||
<P>
|
||||
If the <B>-base</B> flag is specified, the next argument should contain
|
||||
an integer clock value. Only the date in this value is used, not the
|
||||
time. This is useful for determining the time on a specific day or
|
||||
doing other date-relative conversions.
|
||||
<P>
|
||||
The <I>dateString</I> consists of zero or more specifications of the
|
||||
following form:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M38"><I>time</I></A><DD>
|
||||
A time of day, which is of the form: <I>hh</I>?<I>:mm</I>?<I>:ss</I>??
|
||||
?<I>meridian</I>? ?<I>zone</I>? or <I>hhmm </I>?<I>meridian</I>?
|
||||
?<I>zone</I>?. If no meridian is specified, <I>hh</I> is interpreted on
|
||||
a 24-hour clock.
|
||||
<P><DT><A NAME="M39"><I>date</I></A><DD>
|
||||
A specific month and day with optional year. The
|
||||
acceptable formats are <I>mm/dd</I>?<I>/yy</I>?, <I>monthname dd</I>
|
||||
?, <I>yy</I>?, <I>dd monthname </I>?<I>yy</I>?, <I>day, dd monthname
|
||||
yy</I>, <I>?CC?yymmdd</I>, <I>?CC?yy-mm-dd</I>, <I>dd-monthname-?CC?yy</I>.
|
||||
The default year is the current year. If the year is less
|
||||
than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
|
||||
as 1969-1999. Not all platforms can represent the years 38-70, so
|
||||
an error may result if these years are used.
|
||||
<P><DT><A NAME="M40"><I>ISO 8601 point-in-time</I></A><DD>
|
||||
An ISO 8601 point-in-time specification, such as <I>CCyymmddThhmmss</I>, where
|
||||
T is the literal T, <I>CCyymmdd hhmmss</I>, or
|
||||
<I>CCyymmddThh:mm:ss</I>.
|
||||
<P><DT><A NAME="M41"><I>relative time</I></A><DD>
|
||||
A specification relative to the current time. The format is <I>number
|
||||
unit</I> acceptable units are <B>year</B>, <B>fortnight</B>, <B>month</B>, <B>week</B>, <B>day</B>,
|
||||
<B>hour</B>, <B>minute</B> (or <B>min</B>), and <B>second</B> (or <B>sec</B>). The
|
||||
unit can be specified as a singular or plural, as in <B>3 weeks</B>.
|
||||
These modifiers may also be specified:
|
||||
<B>tomorrow</B>, <B>yesterday</B>, <B>today</B>, <B>now</B>,
|
||||
<B>last</B>, <B>this</B>, <B>next</B>, <B>ago</B>.
|
||||
<P></DL>
|
||||
<P>
|
||||
<DL><P><DD>
|
||||
The actual date is calculated according to the following steps.
|
||||
First, any absolute date and/or time is processed and converted.
|
||||
Using that time as the base, day-of-week specifications are added.
|
||||
Next, relative specifications are used. If a date or day is
|
||||
specified, and no absolute or relative time is given, midnight is
|
||||
used. Finally, a correction is applied so that the correct hour of
|
||||
the day is produced after allowing for daylight savings time
|
||||
differences and the correct date is given when going from the end
|
||||
of a long month to a short month.
|
||||
<P>
|
||||
Daylight savings time correction is applied only when the relative time
|
||||
is specified in units of days or more, ie, days, weeks, fortnights, months or
|
||||
years. This means that when crossing the daylight savings time boundary,
|
||||
different results will be given for <B>clock scan "1 day"</B> and
|
||||
<B>clock scan "24 hours"</B>:
|
||||
<PRE><B>% clock scan "1 day" -base [clock scan 1999-10-31]
|
||||
941443200
|
||||
% clock scan "24 hours" -base [clock scan 1999-10-31]
|
||||
941439600</B></PRE>
|
||||
</DL>
|
||||
<P><DT><A NAME="M42"><B>clock seconds</B></A><DD>
|
||||
Return the current date and time as a system-dependent integer value. The
|
||||
unit of the value is seconds, allowing it to be used for relative time
|
||||
calculations. The value is usually defined as total elapsed time from
|
||||
an ``epoch''. You shouldn't assume the value of the epoch.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M43">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#clock">clock</A>, <A href="../Keywords/D.htm#date">date</A>, <A href="../Keywords/T.htm#time">time</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1992-1995 Karl Lehenbauer and Mark Diekhans.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1998-1999 Scriptics Corporation
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
47
hlp/en/tcl/close.htm
Normal file
47
hlp/en/tcl/close.htm
Normal file
@@ -0,0 +1,47 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - close manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
close - Close an open channel.
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>close </B><I>channelId</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Closes the channel given by <I>channelId</I>. <I>ChannelId</I> must be a
|
||||
channel identifier such as the return value from a previous <B><A HREF="../TkCmd/open.htm">open</A></B>
|
||||
or <B><A HREF="../TkCmd/socket.htm">socket</A></B> command.
|
||||
All buffered output is flushed to the channel's output device,
|
||||
any buffered input is discarded, the underlying file or device is closed,
|
||||
and <I>channelId</I> becomes unavailable for use.
|
||||
<P>
|
||||
If the channel is blocking, the command does not return until all output
|
||||
is flushed.
|
||||
If the channel is nonblocking and there is unflushed output, the
|
||||
channel remains open and the command
|
||||
returns immediately; output will be flushed in the background and the
|
||||
channel will be closed when all the flushing is complete.
|
||||
<P>
|
||||
If <I>channelId</I> is a blocking channel for a command pipeline then
|
||||
<B>close</B> waits for the child processes to complete.
|
||||
<P>
|
||||
If the channel is shared between interpreters, then <B>close</B>
|
||||
makes <I>channelId</I> unavailable in the invoking interpreter but has no
|
||||
other effect until all of the sharing interpreters have closed the
|
||||
channel.
|
||||
When the last interpreter in which the channel is registered invokes
|
||||
<B>close</B>, the cleanup actions described above occur. See the
|
||||
<B><A HREF="../TkCmd/interp.htm">interp</A></B> command for a description of channel sharing.
|
||||
<P>
|
||||
Channels are automatically closed when an interpreter is destroyed and
|
||||
when the process exits. Channels are switched to blocking mode, to ensure
|
||||
that all output is correctly flushed before the process exits.
|
||||
<P>
|
||||
The command returns an empty string, and may generate an error if
|
||||
an error occurs while flushing output.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/open.htm">open</A></B>, <B><A HREF="../TkCmd/socket.htm">socket</A></B>, <B><A HREF="../TkCmd/eof.htm">eof</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/C.htm#close">close</A>, <A href="../Keywords/N.htm#nonblocking">nonblocking</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
28
hlp/en/tcl/concat.htm
Normal file
28
hlp/en/tcl/concat.htm
Normal file
@@ -0,0 +1,28 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - concat manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
concat - Join lists together
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>concat</B><I> </I>?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command treats each argument as a list and concatenates them
|
||||
into a single list.
|
||||
It also eliminates leading and trailing spaces in the <I>arg</I>'s
|
||||
and adds a single separator space between <I>arg</I>'s.
|
||||
It permits any number of arguments. For example,
|
||||
the command
|
||||
<PRE><B>concat a b {c d e} {f {g h}}</B></PRE>
|
||||
will return
|
||||
<PRE><B>a b c d e f {g h}</B></PRE>
|
||||
as its result.
|
||||
<P>
|
||||
If no <I>arg</I>s are supplied, the result is an empty string.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/append.htm">append</A></B>, <B><A HREF="../TkCmd/eval.htm">eval</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#concatenate">concatenate</A>, <A href="../Keywords/J.htm#join">join</A>, <A href="../Keywords/L.htm#lists">lists</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
26
hlp/en/tcl/continue.htm
Normal file
26
hlp/en/tcl/continue.htm
Normal file
@@ -0,0 +1,26 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - continue manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
continue - Skip to the next iteration of a loop
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>continue</B><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command is typically invoked inside the body of a looping command
|
||||
such as <B><A HREF="../TkCmd/for.htm">for</A></B> or <B><A HREF="../TkCmd/foreach.htm">foreach</A></B> or <B><A HREF="../TkCmd/while.htm">while</A></B>.
|
||||
It returns a TCL_CONTINUE code, which causes a continue exception
|
||||
to occur.
|
||||
The exception causes the current script to be aborted
|
||||
out to the innermost containing loop command, which then
|
||||
continues with the next iteration of the loop.
|
||||
Catch exceptions are also handled in a few other situations, such
|
||||
as the <B><A HREF="../TkCmd/catch.htm">catch</A></B> command and the outermost scripts of procedure
|
||||
bodies.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/break.htm">break</A></B>, <B><A HREF="../TkCmd/for.htm">for</A></B>, <B><A HREF="../TkCmd/foreach.htm">foreach</A></B>, <B><A HREF="../TkCmd/while.htm">while</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#continue">continue</A>, <A href="../Keywords/I.htm#iteration">iteration</A>, <A href="../Keywords/L.htm#loop">loop</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993-1994 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
146
hlp/en/tcl/dde.htm
Normal file
146
hlp/en/tcl/dde.htm
Normal file
@@ -0,0 +1,146 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - dde manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="dde.htm#M2" NAME="L166">NAME</A>
|
||||
<DL><DD>dde - Execute a Dynamic Data Exchange command</DL>
|
||||
<DD><A HREF="dde.htm#M3" NAME="L167">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>package require dde 1.1</B>
|
||||
<DD><B>dde </B><I>servername </I>?<I>topic</I>?
|
||||
<DD><B>dde ?-async?</B> <I>command service topic </I>?<I>data</I>?
|
||||
</DL>
|
||||
<DD><A HREF="dde.htm#M4" NAME="L168">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="dde.htm#M5" NAME="L169"><B>-async</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="dde.htm#M6" NAME="L170">DDE COMMANDS</A>
|
||||
<DL>
|
||||
<DD><A HREF="dde.htm#M7" NAME="L171"><B>dde servername </B>?<I>topic</I>?</A>
|
||||
<DD><A HREF="dde.htm#M8" NAME="L172"><B>dde execute </B><I>service topic data</I></A>
|
||||
<DD><A HREF="dde.htm#M9" NAME="L173"><B>dde poke </B><I>service topic item data</I></A>
|
||||
<DD><A HREF="dde.htm#M10" NAME="L174"><B>dde request </B><I>service topic item</I></A>
|
||||
<DD><A HREF="dde.htm#M11" NAME="L175"><B>dde services </B><I>service topic</I></A>
|
||||
<DD><A HREF="dde.htm#M12" NAME="L176"><B>dde eval </B><I>topic cmd </I>?<I>arg arg ...</I>?</A>
|
||||
</DL>
|
||||
<DD><A HREF="dde.htm#M13" NAME="L177">DDE AND TCL</A>
|
||||
<DD><A HREF="dde.htm#M14" NAME="L178">SEE ALSO</A>
|
||||
<DD><A HREF="dde.htm#M15" NAME="L179">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
dde - Execute a Dynamic Data Exchange command
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>package require dde 1.1</B><BR>
|
||||
<B>dde </B><I>servername </I>?<I>topic</I>?<BR>
|
||||
<B>dde ?-async?</B> <I>command service topic </I>?<I>data</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command allows an application to send Dynamic Data Exchange (DDE)
|
||||
command when running under Microsoft Windows. Dynamic Data Exchange is
|
||||
a mechanism where applications can exchange raw data. Each DDE
|
||||
transaction needs a <I>service name</I> and a <I>topic</I>. Both the
|
||||
<I>service name</I> and <I>topic</I> are application defined; Tcl uses
|
||||
the service name <B>TclEval</B>, while the topic name is the name of the
|
||||
interpreter given by <B>dde servername</B>. Other applications have their
|
||||
own <I>service names</I> and <I>topics</I>. For instance, Microsoft Excel
|
||||
has the service name <B>Excel</B>.
|
||||
<P>
|
||||
The only option to the <B>dde</B> command is:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>-async</B></A><DD>
|
||||
Requests asynchronous invocation. This is valid only for the
|
||||
<B>execute</B> subcommand. Normally, the <B>dde execute</B> subcommand
|
||||
waits until the command completes, returning appropriate error
|
||||
messages. When the <B>-async</B> option is used, the command returns
|
||||
immediately, and no error information is available.
|
||||
<P></DL>
|
||||
<H3><A NAME="M6">DDE COMMANDS</A></H3>
|
||||
The following commands are a subset of the full Dynamic Data Exchange
|
||||
set of commands.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M7"><B>dde servername </B>?<I>topic</I>?</A><DD>
|
||||
<B>dde servername</B> registers the interpreter as a DDE server with
|
||||
the service name <B>TclEval</B> and the topic name specified by <I>topic</I>.
|
||||
If no <I>topic</I> is given, <B>dde servername</B> returns the name
|
||||
of the current topic or the empty string if it is not registered as a service.
|
||||
<P><DT><A NAME="M8"><B>dde execute </B><I>service topic data</I></A><DD>
|
||||
<B>dde execute</B> takes the <I>data</I> and sends it to the server
|
||||
indicated by <I>service</I> with the topic indicated by
|
||||
<I>topic</I>. Typically, <I>service</I> is the name of an application,
|
||||
and <I>topic</I> is a file to work on. The <I>data</I> field is given
|
||||
to the remote application. Typically, the application treats the
|
||||
<I>data</I> field as a script, and the script is run in the
|
||||
application. The command returns an error if the script did not
|
||||
run. If the <B>-async</B> flag was used, the command
|
||||
returns immediately with no error.
|
||||
<P><DT><A NAME="M9"><B>dde poke </B><I>service topic item data</I></A><DD>
|
||||
<B>dde poke</B> passes the <I>data</I> to the server indicated by
|
||||
<I>service</I> using the <I>topic</I> and <I>item</I> specified. Typically,
|
||||
<I>service</I> is the name of an application. <I>topic</I> is application
|
||||
specific but can be a command to the server or the name of a file to work
|
||||
on. The <I>item</I> is also application specific and is often not used, but
|
||||
it must always be non-null. The <I>data</I> field is given to the remote
|
||||
application.
|
||||
<P><DT><A NAME="M10"><B>dde request </B><I>service topic item</I></A><DD>
|
||||
<B>dde request</B> is typically used to get the value of something; the
|
||||
value of a cell in Microsoft Excel or the text of a selection in
|
||||
Microsoft Word. <I>service</I> is typically the name of an application,
|
||||
<I>topic</I> is typically the name of the file, and <I>item</I> is
|
||||
application-specific. The command returns the value of <I>item</I> as
|
||||
defined in the application.
|
||||
<P><DT><A NAME="M11"><B>dde services </B><I>service topic</I></A><DD>
|
||||
<B>dde services</B> returns a list of service-topic pairs that
|
||||
currently exist on the machine. If <I>service</I> and <I>topic</I> are
|
||||
both null strings ({}), then all service-topic pairs currently
|
||||
available on the system are returned. If <I>service</I> is null and
|
||||
<I>topic</I> is not, then all services with the specified topic are
|
||||
returned. If <I>service</I> is not null and <I>topic</I> is, all topics
|
||||
for a given service are returned. If both are not null, if that
|
||||
service-topic pair currently exists, it is returned; otherwise, null
|
||||
is returned.
|
||||
<P><DT><A NAME="M12"><B>dde eval </B><I>topic cmd </I>?<I>arg arg ...</I>?</A><DD>
|
||||
<B>dde eval</B> evaluates a command and its arguments using the
|
||||
interpreter specified by <I>topic</I>. The DDE service must be the
|
||||
<B>TclEval</B> service. This command can be used to replace send on
|
||||
Windows.
|
||||
<P></DL>
|
||||
<H3><A NAME="M13">DDE AND TCL</A></H3>
|
||||
A Tcl interpreter always has a service name of <B>TclEval</B>. Each
|
||||
different interpreter of all running Tcl applications must be
|
||||
given a unique
|
||||
name specified by <B>dde servername</B>. Each interp is available as a
|
||||
DDE topic only if the <B>dde servername</B> command was used to set the
|
||||
name of the topic for each interp. So a <B>dde services TclEval {}</B>
|
||||
command will return a list of service-topic pairs, where each of the
|
||||
currently running interps will be a topic.
|
||||
<P>
|
||||
When Tcl processes a <B>dde execute</B> command, the data for the
|
||||
execute is run as a script in the interp named by the topic of the
|
||||
<B>dde execute</B> command.
|
||||
<P>
|
||||
When Tcl processes a <B>dde request</B> command, it returns the value of the
|
||||
variable given in the dde command in the context of the interp named by the
|
||||
dde topic. Tcl reserves the variable <B>$TCLEVAL$EXECUTE$RESULT</B> for
|
||||
internal use, and <B>dde request</B> commands for that variable will give
|
||||
unpredictable results.
|
||||
<P>
|
||||
An external application which wishes to run a script in Tcl should have
|
||||
that script store its result in a variable, run the <B>dde execute</B>
|
||||
command, and the run <B>dde request</B> to get the value of the
|
||||
variable.
|
||||
<P>
|
||||
When using DDE, be careful to ensure that the event queue is flushed
|
||||
using either <B><A HREF="../TkCmd/update.htm">update</A></B> or <B><A HREF="../TkCmd/vwait.htm">vwait</A></B>. This happens by default
|
||||
when using <B><A HREF="../UserCmd/wish.htm">wish</A></B> unless a blocking command is called (such as <B><A HREF="../TkCmd/exec.htm">exec</A></B>
|
||||
without adding the <B>&</B> to place the process in the background).
|
||||
If for any reason the event queue is not flushed, DDE commands may
|
||||
hang until the event queue is flushed. This can create a deadlock
|
||||
situation.
|
||||
|
||||
<H3><A NAME="M14">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TclCmd/tk.htm">tk</A></B>, <B><A HREF="../TclCmd/winfo.htm">winfo</A></B>, <B><A HREF="../TclCmd/send.htm">send</A></B>
|
||||
<H3><A NAME="M15">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#application">application</A>, <A href="../Keywords/D.htm#dde">dde</A>, <A href="../Keywords/N.htm#name">name</A>, <A href="../Keywords/R.htm#remote execution">remote execution</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
83
hlp/en/tcl/encoding.htm
Normal file
83
hlp/en/tcl/encoding.htm
Normal file
@@ -0,0 +1,83 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - encoding manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="encoding.htm#M2" NAME="L180">NAME</A>
|
||||
<DL><DD>encoding - Manipulate encodings</DL>
|
||||
<DD><A HREF="encoding.htm#M3" NAME="L181">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>encoding </B><I>option</I> ?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="encoding.htm#M4" NAME="L182">INTRODUCTION</A>
|
||||
<DD><A HREF="encoding.htm#M5" NAME="L183">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="encoding.htm#M6" NAME="L184"><B>encoding convertfrom ?</B><I>encoding</I>? <I>data</I></A>
|
||||
<DD><A HREF="encoding.htm#M7" NAME="L185"><B>encoding convertto ?</B><I>encoding</I>? <I>string</I></A>
|
||||
<DD><A HREF="encoding.htm#M8" NAME="L186"><B>encoding names</B></A>
|
||||
<DD><A HREF="encoding.htm#M9" NAME="L187"><B>encoding system</B> ?<I>encoding</I>?</A>
|
||||
</DL>
|
||||
<DD><A HREF="encoding.htm#M10" NAME="L188">EXAMPLE</A>
|
||||
<DD><A HREF="encoding.htm#M11" NAME="L189">SEE ALSO</A>
|
||||
<DD><A HREF="encoding.htm#M12" NAME="L190">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
encoding - Manipulate encodings
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>encoding </B><I>option</I> ?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">INTRODUCTION</A></H3>
|
||||
Strings in Tcl are encoded using 16-bit Unicode characters. Different
|
||||
operating system interfaces or applications may generate strings in
|
||||
other encodings such as Shift-JIS. The <B>encoding</B> command helps
|
||||
to bridge the gap between Unicode and these other formats.
|
||||
|
||||
<H3><A NAME="M5">DESCRIPTION</A></H3>
|
||||
Performs one of several encoding related operations, depending on
|
||||
<I>option</I>. The legal <I>option</I>s are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>encoding convertfrom ?</B><I>encoding</I>? <I>data</I></A><DD>
|
||||
Convert <I>data</I> to Unicode from the specified <I>encoding</I>. The
|
||||
characters in <I>data</I> are treated as binary data where the lower
|
||||
8-bits of each character is taken as a single byte. The resulting
|
||||
sequence of bytes is treated as a string in the specified
|
||||
<I>encoding</I>. If <I>encoding</I> is not specified, the current
|
||||
system encoding is used.
|
||||
<P><DT><A NAME="M7"><B>encoding convertto ?</B><I>encoding</I>? <I>string</I></A><DD>
|
||||
Convert <I>string</I> from Unicode to the specified <I>encoding</I>.
|
||||
The result is a sequence of bytes that represents the converted
|
||||
string. Each byte is stored in the lower 8-bits of a Unicode
|
||||
character. If <I>encoding</I> is not specified, the current
|
||||
system encoding is used.
|
||||
<P><DT><A NAME="M8"><B>encoding names</B></A><DD>
|
||||
Returns a list containing the names of all of the encodings that are
|
||||
currently available.
|
||||
<P><DT><A NAME="M9"><B>encoding system</B> ?<I>encoding</I>?</A><DD>
|
||||
Set the system encoding to <I>encoding</I>. If <I>encoding</I> is
|
||||
omitted then the command returns the current system encoding. The
|
||||
system encoding is used whenever Tcl passes strings to system calls.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M10">EXAMPLE</A></H3>
|
||||
It is common practice to write script files using a text editor that
|
||||
produces output in the euc-jp encoding, which represents the ASCII
|
||||
characters as singe bytes and Japanese characters as two bytes. This
|
||||
makes it easy to embed literal strings that correspond to non-ASCII
|
||||
characters by simply typing the strings in place in the script.
|
||||
However, because the <B><A HREF="../TkCmd/source.htm">source</A></B> command always reads files using the
|
||||
ISO8859-1 encoding, Tcl will treat each byte in the file as a separate
|
||||
character that maps to the 00 page in Unicode. The
|
||||
resulting Tcl strings will not contain the expected Japanese
|
||||
characters. Instead, they will contain a sequence of Latin-1
|
||||
characters that correspond to the bytes of the original string. The
|
||||
<B>encoding</B> command can be used to convert this string to the
|
||||
expected Japanese Unicode characters. For example,
|
||||
<PRE>set s [encoding convertfrom euc-jp "\xA4\xCF"]</PRE>
|
||||
would return the Unicode string "\u306F", which is the Hiragana
|
||||
letter HA.
|
||||
|
||||
<H3><A NAME="M11">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkLib/Encoding.htm">Tcl_GetEncoding</A></B>
|
||||
<H3><A NAME="M12">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#encoding">encoding</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1998 by Scriptics Corporation.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
19
hlp/en/tcl/eof.htm
Normal file
19
hlp/en/tcl/eof.htm
Normal file
@@ -0,0 +1,19 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - eof manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
eof - Check for end of file condition on channel
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>eof </B><I>channelId</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Returns 1 if an end of file condition occurred during the most
|
||||
recent input operation on <I>channelId</I> (such as <B><A HREF="../TkCmd/gets.htm">gets</A></B>),
|
||||
0 otherwise.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/open.htm">open</A></B>, <B><A HREF="../TkCmd/close.htm">close</A></B>, <B><A HREF="../TkCmd/fblocked.htm">fblocked</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/E.htm#end of file">end of file</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
48
hlp/en/tcl/error.htm
Normal file
48
hlp/en/tcl/error.htm
Normal file
@@ -0,0 +1,48 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - error manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
error - Generate an error
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>error </B><I>message</I> ?<I>info</I>? ?<I>code</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Returns a TCL_ERROR code, which causes command interpretation to be
|
||||
unwound. <I>Message</I> is a string that is returned to the application
|
||||
to indicate what went wrong.
|
||||
<P>
|
||||
If the <I>info</I> argument is provided and is non-empty,
|
||||
it is used to initialize the global variable <B>errorInfo</B>.
|
||||
<B>errorInfo</B> is used to accumulate a stack trace of what
|
||||
was in progress when an error occurred; as nested commands unwind,
|
||||
the Tcl interpreter adds information to <B>errorInfo</B>. If the
|
||||
<I>info</I> argument is present, it is used to initialize
|
||||
<B>errorInfo</B> and the first increment of unwind information
|
||||
will not be added by the Tcl interpreter. In other
|
||||
words, the command containing the <B>error</B> command will not appear
|
||||
in <B>errorInfo</B>; in its place will be <I>info</I>.
|
||||
This feature is most useful in conjunction with the <B><A HREF="../TkCmd/catch.htm">catch</A></B> command:
|
||||
if a caught error cannot be handled successfully, <I>info</I> can be used
|
||||
to return a stack trace reflecting the original point of occurrence
|
||||
of the error:
|
||||
<PRE><B>catch {...} errMsg
|
||||
set savedInfo $errorInfo
|
||||
...
|
||||
error $errMsg $savedInfo</B></PRE>
|
||||
<P>
|
||||
If the <I>code</I> argument is present, then its value is stored
|
||||
in the <B>errorCode</B> global variable. This variable is intended
|
||||
to hold a machine-readable description of the error in cases where
|
||||
such information is available; see the <B><A HREF="../TkCmd/tclvars.htm">tclvars</A></B> manual
|
||||
page for information on the proper format for the variable.
|
||||
If the <I>code</I> argument is not
|
||||
present, then <B>errorCode</B> is automatically reset to
|
||||
``NONE'' by the Tcl interpreter as part of processing the
|
||||
error generated by the command.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/catch.htm">catch</A></B>, <B><A HREF="../TkCmd/tclvars.htm">tclvars</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#error">error</A>, <A href="../Keywords/E.htm#errorCode">errorCode</A>, <A href="../Keywords/E.htm#errorInfo">errorInfo</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
22
hlp/en/tcl/eval.htm
Normal file
22
hlp/en/tcl/eval.htm
Normal file
@@ -0,0 +1,22 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - eval manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
eval - Evaluate a Tcl script
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>eval </B><I>arg </I>?<I>arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
<B>Eval</B> takes one or more arguments, which together comprise a Tcl
|
||||
script containing one or more commands.
|
||||
<B>Eval</B> concatenates all its arguments in the same
|
||||
fashion as the <B><A HREF="../TkCmd/concat.htm">concat</A></B> command, passes the concatenated string to the
|
||||
Tcl interpreter recursively, and returns the result of that
|
||||
evaluation (or any error generated by it).
|
||||
|
||||
<H3><A NAME="M5">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#concatenate">concatenate</A>, <A href="../Keywords/E.htm#evaluate">evaluate</A>, <A href="../Keywords/S.htm#script">script</A>
|
||||
<H3><A NAME="M6">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/catch.htm">catch</A></B>, <B><A HREF="../TkCmd/concat.htm">concat</A></B>, <B><A HREF="../TkCmd/error.htm">error</A></B>, <B>subs</B>, <B><A HREF="../TkCmd/tclvars.htm">tclvars</A></B>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
314
hlp/en/tcl/exec.htm
Normal file
314
hlp/en/tcl/exec.htm
Normal file
@@ -0,0 +1,314 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - exec manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="exec.htm#M2" NAME="L206">NAME</A>
|
||||
<DL><DD>exec - Invoke subprocess(es)</DL>
|
||||
<DD><A HREF="exec.htm#M3" NAME="L207">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>exec </B>?<I>switches</I>? <I>arg </I>?<I>arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="exec.htm#M4" NAME="L208">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="exec.htm#M5" NAME="L209"><B>-keepnewline</B></A>
|
||||
<DD><A HREF="exec.htm#M6" NAME="L210"><B>- -</B></A>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="exec.htm#M7" NAME="L211">|</A>
|
||||
<DD><A HREF="exec.htm#M8" NAME="L212">|&</A>
|
||||
<DD><A HREF="exec.htm#M9" NAME="L213">< <I>fileName</I></A>
|
||||
<DD><A HREF="exec.htm#M10" NAME="L214"><@ <I>fileId</I></A>
|
||||
<DD><A HREF="exec.htm#M11" NAME="L215"><< <I>value</I></A>
|
||||
<DD><A HREF="exec.htm#M12" NAME="L216">> <I>fileName</I></A>
|
||||
<DD><A HREF="exec.htm#M13" NAME="L217">2> <I>fileName</I></A>
|
||||
<DD><A HREF="exec.htm#M14" NAME="L218">>& <I>fileName</I></A>
|
||||
<DD><A HREF="exec.htm#M15" NAME="L219">>> <I>fileName</I></A>
|
||||
<DD><A HREF="exec.htm#M16" NAME="L220">2>> <I>fileName</I></A>
|
||||
<DD><A HREF="exec.htm#M17" NAME="L221">>>& <I>fileName</I></A>
|
||||
<DD><A HREF="exec.htm#M18" NAME="L222">>@ <I>fileId</I></A>
|
||||
<DD><A HREF="exec.htm#M19" NAME="L223">2>@ <I>fileId</I></A>
|
||||
<DD><A HREF="exec.htm#M20" NAME="L224">>&@ <I>fileId</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="exec.htm#M21" NAME="L225">PORTABILITY ISSUES</A>
|
||||
<DL>
|
||||
<DD><A HREF="exec.htm#M22" NAME="L226"><B>Windows</B> (all versions)</A>
|
||||
<DD><A HREF="exec.htm#M23" NAME="L227"><B>Windows NT</B></A>
|
||||
<DD><A HREF="exec.htm#M24" NAME="L228"><B>Windows 95</B></A>
|
||||
<DD><A HREF="exec.htm#M25" NAME="L229"><B>Macintosh</B></A>
|
||||
<DD><A HREF="exec.htm#M26" NAME="L230"><B>Unix</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="exec.htm#M27" NAME="L231">SEE ALSO</A>
|
||||
<DD><A HREF="exec.htm#M28" NAME="L232">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
exec - Invoke subprocess(es)
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>exec </B>?<I>switches</I>? <I>arg </I>?<I>arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command treats its arguments as the specification
|
||||
of one or more subprocesses to execute.
|
||||
The arguments take the form of a standard shell pipeline
|
||||
where each <I>arg</I> becomes one word of a command, and
|
||||
each distinct command becomes a subprocess.
|
||||
<P>
|
||||
If the initial arguments to <B>exec</B> start with <B>-</B> then
|
||||
they are treated as command-line switches and are not part
|
||||
of the pipeline specification. The following switches are
|
||||
currently supported:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>-keepnewline</B></A><DD>
|
||||
Retains a trailing newline in the pipeline's output.
|
||||
Normally a trailing newline will be deleted.
|
||||
<P><DT><A NAME="M6"><B>- -</B></A><DD>
|
||||
Marks the end of switches. The argument following this one will
|
||||
be treated as the first <I>arg</I> even if it starts with a <B>-</B>.
|
||||
<P></DL>
|
||||
<P>
|
||||
If an <I>arg</I> (or pair of <I>arg</I>'s) has one of the forms
|
||||
described below then it is used by <B>exec</B> to control the
|
||||
flow of input and output among the subprocess(es).
|
||||
Such arguments will not be passed to the subprocess(es). In forms
|
||||
such as ``< <I>fileName</I>'' <I>fileName</I> may either be in a
|
||||
separate argument from ``<'' or in the same argument with no
|
||||
intervening space (i.e. ``<<I>fileName</I>'').
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M7">|</A><DD>
|
||||
Separates distinct commands in the pipeline. The standard output
|
||||
of the preceding command will be piped into the standard input
|
||||
of the next command.
|
||||
<P><DT><A NAME="M8">|&</A><DD>
|
||||
Separates distinct commands in the pipeline. Both standard output
|
||||
and standard error of the preceding command will be piped into
|
||||
the standard input of the next command.
|
||||
This form of redirection overrides forms such as 2> and >&.
|
||||
<P><DT><A NAME="M9">< <I>fileName</I></A><DD>
|
||||
The file named by <I>fileName</I> is opened and used as the standard
|
||||
input for the first command in the pipeline.
|
||||
<P><DT><A NAME="M10"><@ <I>fileId</I></A><DD>
|
||||
<I>FileId</I> must be the identifier for an open file, such as the return
|
||||
value from a previous call to <B><A HREF="../TkCmd/open.htm">open</A></B>.
|
||||
It is used as the standard input for the first command in the pipeline.
|
||||
<I>FileId</I> must have been opened for reading.
|
||||
<P><DT><A NAME="M11"><< <I>value</I></A><DD>
|
||||
<I>Value</I> is passed to the first command as its standard input.
|
||||
<P><DT><A NAME="M12">> <I>fileName</I></A><DD>
|
||||
Standard output from the last command is redirected to the file named
|
||||
<I>fileName</I>, overwriting its previous contents.
|
||||
<P><DT><A NAME="M13">2> <I>fileName</I></A><DD>
|
||||
Standard error from all commands in the pipeline is redirected to the
|
||||
file named <I>fileName</I>, overwriting its previous contents.
|
||||
<P><DT><A NAME="M14">>& <I>fileName</I></A><DD>
|
||||
Both standard output from the last command and standard error from all
|
||||
commands are redirected to the file named <I>fileName</I>, overwriting
|
||||
its previous contents.
|
||||
<P><DT><A NAME="M15">>> <I>fileName</I></A><DD>
|
||||
Standard output from the last command is
|
||||
redirected to the file named <I>fileName</I>, appending to it rather
|
||||
than overwriting it.
|
||||
<P><DT><A NAME="M16">2>> <I>fileName</I></A><DD>
|
||||
Standard error from all commands in the pipeline is
|
||||
redirected to the file named <I>fileName</I>, appending to it rather
|
||||
than overwriting it.
|
||||
<P><DT><A NAME="M17">>>& <I>fileName</I></A><DD>
|
||||
Both standard output from the last command and standard error from
|
||||
all commands are redirected to the file named <I>fileName</I>,
|
||||
appending to it rather than overwriting it.
|
||||
<P><DT><A NAME="M18">>@ <I>fileId</I></A><DD>
|
||||
<I>FileId</I> must be the identifier for an open file, such as the return
|
||||
value from a previous call to <B><A HREF="../TkCmd/open.htm">open</A></B>.
|
||||
Standard output from the last command is redirected to <I>fileId</I>'s
|
||||
file, which must have been opened for writing.
|
||||
<P><DT><A NAME="M19">2>@ <I>fileId</I></A><DD>
|
||||
<I>FileId</I> must be the identifier for an open file, such as the return
|
||||
value from a previous call to <B><A HREF="../TkCmd/open.htm">open</A></B>.
|
||||
Standard error from all commands in the pipeline is
|
||||
redirected to <I>fileId</I>'s file.
|
||||
The file must have been opened for writing.
|
||||
<P><DT><A NAME="M20">>&@ <I>fileId</I></A><DD>
|
||||
<I>FileId</I> must be the identifier for an open file, such as the return
|
||||
value from a previous call to <B><A HREF="../TkCmd/open.htm">open</A></B>.
|
||||
Both standard output from the last command and standard error from
|
||||
all commands are redirected to <I>fileId</I>'s file.
|
||||
The file must have been opened for writing.
|
||||
<P></DL>
|
||||
<P>
|
||||
If standard output has not been redirected then the <B>exec</B>
|
||||
command returns the standard output from the last command
|
||||
in the pipeline.
|
||||
If any of the commands in the pipeline exit abnormally or
|
||||
are killed or suspended, then <B>exec</B> will return an error
|
||||
and the error message will include the pipeline's output followed by
|
||||
error messages describing the abnormal terminations; the
|
||||
<B>errorCode</B> variable will contain additional information
|
||||
about the last abnormal termination encountered.
|
||||
If any of the commands writes to its standard error file and that
|
||||
standard error isn't redirected,
|
||||
then <B>exec</B> will return an error; the error message
|
||||
will include the pipeline's standard output, followed by messages
|
||||
about abnormal terminations (if any), followed by the standard error
|
||||
output.
|
||||
<P>
|
||||
If the last character of the result or error message
|
||||
is a newline then that character is normally deleted
|
||||
from the result or error message.
|
||||
This is consistent with other Tcl return values, which don't
|
||||
normally end with newlines.
|
||||
However, if <B>-keepnewline</B> is specified then the trailing
|
||||
newline is retained.
|
||||
<P>
|
||||
If standard input isn't redirected with ``<'' or ``<<''
|
||||
or ``<@'' then the standard input for the first command in the
|
||||
pipeline is taken from the application's current standard input.
|
||||
<P>
|
||||
If the last <I>arg</I> is ``&'' then the pipeline will be
|
||||
executed in background.
|
||||
In this case the <B>exec</B> command will return a list whose
|
||||
elements are the process identifiers for all of the subprocesses
|
||||
in the pipeline.
|
||||
The standard output from the last command in the pipeline will
|
||||
go to the application's standard output if it hasn't been
|
||||
redirected, and error output from all of
|
||||
the commands in the pipeline will go to the application's
|
||||
standard error file unless redirected.
|
||||
<P>
|
||||
The first word in each command is taken as the command name;
|
||||
tilde-substitution is performed on it, and if the result contains
|
||||
no slashes then the directories
|
||||
in the PATH environment variable are searched for
|
||||
an executable by the given name.
|
||||
If the name contains a slash then it must refer to an executable
|
||||
reachable from the current directory.
|
||||
No ``<A HREF="../TkCmd/glob.htm">glob</A>'' expansion or other shell-like substitutions
|
||||
are performed on the arguments to commands.
|
||||
|
||||
<H3><A NAME="M21">PORTABILITY ISSUES</A></H3>
|
||||
<DL>
|
||||
<P><DT><A NAME="M22"><B>Windows</B> (all versions)</A><DD>
|
||||
Reading from or writing to a socket, using the ``<B>@ </B><I>fileId</I>''
|
||||
notation, does not work. When reading from a socket, a 16-bit DOS
|
||||
application will hang and a 32-bit application will return immediately with
|
||||
end-of-file. When either type of application writes to a socket, the
|
||||
information is instead sent to the console, if one is present, or is
|
||||
discarded.
|
||||
<P>
|
||||
The Tk console text widget does not provide real standard IO capabilities.
|
||||
Under Tk, when redirecting from standard input, all applications will see an
|
||||
immediate end-of-file; information redirected to standard output or standard
|
||||
error will be discarded.
|
||||
<P>
|
||||
Either forward or backward slashes are accepted as path separators for
|
||||
arguments to Tcl commands. When executing an application, the path name
|
||||
specified for the application may also contain forward or backward slashes
|
||||
as path separators. Bear in mind, however, that most Windows applications
|
||||
accept arguments with forward slashes only as option delimiters and
|
||||
backslashes only in paths. Any arguments to an application that specify a
|
||||
path name with forward slashes will not automatically be converted to use
|
||||
the backslash character. If an argument contains forward slashes as the
|
||||
path separator, it may or may not be recognized as a path name, depending on
|
||||
the program.
|
||||
<P>
|
||||
Additionally, when calling a 16-bit DOS or Windows 3.X application, all path
|
||||
names must use the short, cryptic, path format (e.g., using ``applba~1.def''
|
||||
instead of ``applbakery.default'').
|
||||
<P>
|
||||
Two or more forward or backward slashes in a row in a path refer to a
|
||||
network path. For example, a simple concatenation of the root directory
|
||||
<B>c:/</B> with a subdirectory <B>/windows/system</B> will yield
|
||||
<B>c://windows/system</B> (two slashes together), which refers to the mount
|
||||
point called <B>system</B> on the machine called <B>windows</B> (and the
|
||||
<B>c:/</B> is ignored), and is not equivalent to <B>c:/windows/system</B>,
|
||||
which describes a directory on the current computer. The <B><A HREF="../TkCmd/file.htm">file join</A></B>
|
||||
command should be used to concatenate path components.
|
||||
<P><DT><A NAME="M23"><B>Windows NT</B></A><DD>
|
||||
When attempting to execute an application, <B>exec</B> first searches for the
|
||||
name as it was specified. Then, in order, <B>.com</B>, <B>.exe</B>, and <B>.bat</B>
|
||||
are appended to the end of the specified name and it searches for
|
||||
the longer name. If a directory name was not specified as part of the
|
||||
application name, the following directories are automatically searched in
|
||||
order when attempting to locate the application:
|
||||
<P>
|
||||
<DL><P><DD>
|
||||
The directory from which the Tcl executable was loaded.
|
||||
<BR>
|
||||
The current directory.
|
||||
<BR>
|
||||
The Windows NT 32-bit system directory.
|
||||
<BR>
|
||||
The Windows NT 16-bit system directory.
|
||||
<BR>
|
||||
The Windows NT home directory.
|
||||
<BR>
|
||||
The directories listed in the path.
|
||||
</DL>
|
||||
<P>
|
||||
In order to execute the shell builtin commands like <B>dir</B> and <B>copy</B>,
|
||||
the caller must prepend ``<B>cmd.exe /c </B>'' to the desired command.
|
||||
<P>
|
||||
<P><DT><A NAME="M24"><B>Windows 95</B></A><DD>
|
||||
When attempting to execute an application, <B>exec</B> first searches for the
|
||||
name as it was specified. Then, in order, <B>.com</B>, <B>.exe</B>, and <B>.bat</B>
|
||||
are appended to the end of the specified name and it searches for
|
||||
the longer name. If a directory name was not specified as part of the
|
||||
application name, the following directories are automatically searched in
|
||||
order when attempting to locate the application:
|
||||
<P>
|
||||
<DL><P><DD>
|
||||
The directory from which the Tcl executable was loaded.
|
||||
<BR>
|
||||
The current directory.
|
||||
<BR>
|
||||
The Windows 95 system directory.
|
||||
<BR>
|
||||
The Windows 95 home directory.
|
||||
<BR>
|
||||
The directories listed in the path.
|
||||
</DL>
|
||||
<P>
|
||||
In order to execute the shell builtin commands like <B>dir</B> and <B>copy</B>,
|
||||
the caller must prepend ``<B>command.com /c </B>'' to the desired command.
|
||||
<P>
|
||||
Once a 16-bit DOS application has read standard input from a console and
|
||||
then quit, all subsequently run 16-bit DOS applications will see the
|
||||
standard input as already closed. 32-bit applications do not have this
|
||||
problem and will run correctly, even after a 16-bit DOS application thinks
|
||||
that standard input is closed. There is no known workaround for this bug
|
||||
at this time.
|
||||
<P>
|
||||
Redirection between the <B>NUL:</B> device and a 16-bit application does not
|
||||
always work. When redirecting from <B>NUL:</B>, some applications may hang,
|
||||
others will get an infinite stream of ``0x01'' bytes, and some will actually
|
||||
correctly get an immediate end-of-file; the behavior seems to depend upon
|
||||
something compiled into the application itself. When redirecting greater than
|
||||
4K or so to <B>NUL:</B>, some applications will hang. The above problems do not
|
||||
happen with 32-bit applications.
|
||||
<P>
|
||||
All DOS 16-bit applications are run synchronously. All standard input from
|
||||
a pipe to a 16-bit DOS application is collected into a temporary file; the
|
||||
other end of the pipe must be closed before the 16-bit DOS application
|
||||
begins executing. All standard output or error from a 16-bit DOS
|
||||
application to a pipe is collected into temporary files; the application
|
||||
must terminate before the temporary files are redirected to the next stage
|
||||
of the pipeline. This is due to a workaround for a Windows 95 bug in the
|
||||
implementation of pipes, and is how the standard Windows 95 DOS shell
|
||||
handles pipes itself.
|
||||
<P>
|
||||
Certain applications, such as <B>command.com</B>, should not be executed
|
||||
interactively. Applications which directly access the console window,
|
||||
rather than reading from their standard input and writing to their standard
|
||||
output may fail, hang Tcl, or even hang the system if their own private
|
||||
console window is not available to them.
|
||||
<P><DT><A NAME="M25"><B>Macintosh</B></A><DD>
|
||||
The <B>exec</B> command is not implemented and does not exist under Macintosh.
|
||||
<P><DT><A NAME="M26"><B>Unix</B></A><DD>
|
||||
The <B>exec</B> command is fully functional and works as described.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M27">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/error.htm">error</A></B>, <B><A HREF="../TkCmd/open.htm">open</A></B>
|
||||
<H3><A NAME="M28">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#execute">execute</A>, <A href="../Keywords/P.htm#pipeline">pipeline</A>, <A href="../Keywords/R.htm#redirection">redirection</A>, <A href="../Keywords/S.htm#subprocess">subprocess</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
20
hlp/en/tcl/exit.htm
Normal file
20
hlp/en/tcl/exit.htm
Normal file
@@ -0,0 +1,20 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - exit manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
exit - End the application
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>exit </B>?<I>returnCode</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Terminate the process, returning <I>returnCode</I> to the
|
||||
system as the exit status.
|
||||
If <I>returnCode</I> isn't specified then it defaults
|
||||
to 0.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/exec.htm">exec</A></B>, <B><A HREF="../TkCmd/tclvars.htm">tclvars</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#exit">exit</A>, <A href="../Keywords/P.htm#process">process</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
380
hlp/en/tcl/expr.htm
Normal file
380
hlp/en/tcl/expr.htm
Normal file
@@ -0,0 +1,380 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - expr manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="expr.htm#M2" NAME="L238">NAME</A>
|
||||
<DL><DD>expr - Evaluate an expression</DL>
|
||||
<DD><A HREF="expr.htm#M3" NAME="L239">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>expr </B><I>arg </I>?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="expr.htm#M4" NAME="L240">DESCRIPTION</A>
|
||||
<DD><A HREF="expr.htm#M5" NAME="L241">OPERANDS</A>
|
||||
<DL>
|
||||
</DL>
|
||||
<DD><A HREF="expr.htm#M6" NAME="L242">OPERATORS</A>
|
||||
<DL>
|
||||
<DD><A HREF="expr.htm#M7" NAME="L243"><B>- + ~ !</B></A>
|
||||
<DD><A HREF="expr.htm#M8" NAME="L244"><B>* / %</B></A>
|
||||
<DD><A HREF="expr.htm#M9" NAME="L245"><B>+ -</B></A>
|
||||
<DD><A HREF="expr.htm#M10" NAME="L246"><B><< >></B></A>
|
||||
<DD><A HREF="expr.htm#M11" NAME="L247"><B>< > <= >=</B></A>
|
||||
<DD><A HREF="expr.htm#M12" NAME="L248"><B>== !=</B></A>
|
||||
<DD><A HREF="expr.htm#M13" NAME="L249"><B>&</B></A>
|
||||
<DD><A HREF="expr.htm#M14" NAME="L250"><B>^</B></A>
|
||||
<DD><A HREF="expr.htm#M15" NAME="L251"><B>|</B></A>
|
||||
<DD><A HREF="expr.htm#M16" NAME="L252"><B>&&</B></A>
|
||||
<DD><A HREF="expr.htm#M17" NAME="L253"><B>||</B></A>
|
||||
<DD><A HREF="expr.htm#M18" NAME="L254"><I>x</I><B>?</B><I>y</I><B>:</B><I>z</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="expr.htm#M19" NAME="L255">MATH FUNCTIONS</A>
|
||||
<DL>
|
||||
<DD><A HREF="expr.htm#M20" NAME="L256"><B>abs(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M21" NAME="L257"><B>acos(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M22" NAME="L258"><B>asin(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M23" NAME="L259"><B>atan(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M24" NAME="L260"><B>atan2(</B><I>x, y</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M25" NAME="L261"><B>ceil(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M26" NAME="L262"><B>cos(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M27" NAME="L263"><B>cosh(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M28" NAME="L264"><B>double(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M29" NAME="L265"><B>exp(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M30" NAME="L266"><B>floor(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M31" NAME="L267"><B>fmod(</B><I>x, y</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M32" NAME="L268"><B>hypot(</B><I>x, y</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M33" NAME="L269"><B>int(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M34" NAME="L270"><B>log(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M35" NAME="L271"><B>log10(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M36" NAME="L272"><B>pow(</B><I>x, y</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M37" NAME="L273"><B>rand()</B></A>
|
||||
<DD><A HREF="expr.htm#M38" NAME="L274"><B>round(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M39" NAME="L275"><B>sin(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M40" NAME="L276"><B>sinh(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M41" NAME="L277"><B>sqrt(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M42" NAME="L278"><B>srand(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M43" NAME="L279"><B>tan(</B><I>arg</I><B>)</B></A>
|
||||
<DD><A HREF="expr.htm#M44" NAME="L280"><B>tanh(</B><I>arg</I><B>)</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="expr.htm#M45" NAME="L281">TYPES, OVERFLOW, AND PRECISION</A>
|
||||
<DD><A HREF="expr.htm#M46" NAME="L282">STRING OPERATIONS</A>
|
||||
<DD><A HREF="expr.htm#M47" NAME="L283">PERFORMANCE CONSIDERATIONS</A>
|
||||
<DD><A HREF="expr.htm#M48" NAME="L284">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
expr - Evaluate an expression
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>expr </B><I>arg </I>?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Concatenates <I>arg</I>'s (adding separator spaces between them),
|
||||
evaluates the result as a Tcl expression, and returns the value.
|
||||
The operators permitted in Tcl expressions are a subset of
|
||||
the operators permitted in C expressions, and they have the
|
||||
same meaning and precedence as the corresponding C operators.
|
||||
Expressions almost always yield numeric results
|
||||
(integer or floating-point values).
|
||||
For example, the expression
|
||||
<PRE><B>expr 8.2 + 6</B></PRE>
|
||||
evaluates to 14.2.
|
||||
Tcl expressions differ from C expressions in the way that
|
||||
operands are specified. Also, Tcl expressions support
|
||||
non-numeric operands and string comparisons.
|
||||
<H3><A NAME="M5">OPERANDS</A></H3>
|
||||
A Tcl expression consists of a combination of operands, operators,
|
||||
and parentheses.
|
||||
White space may be used between the operands and operators and
|
||||
parentheses; it is ignored by the expression's instructions.
|
||||
Where possible, operands are interpreted as integer values.
|
||||
Integer values may be specified in decimal (the normal case), in octal (if the
|
||||
first character of the operand is <B>0</B>), or in hexadecimal (if the first
|
||||
two characters of the operand are <B>0x</B>).
|
||||
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
|
||||
ways accepted by an ANSI-compliant C compiler (except that the
|
||||
<B>f</B>, <B>F</B>, <B>l</B>, and <B>L</B> suffixes will not be permitted in
|
||||
most installations). For example, all of the
|
||||
following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16.
|
||||
If no numeric interpretation is possible, then an operand is left
|
||||
as a string (and only a limited set of operators may be applied to
|
||||
it).
|
||||
<P>
|
||||
Operands may be specified in any of the following ways:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT>[1]<DD>
|
||||
As an numeric value, either integer or floating-point.
|
||||
<P><DT>[2]<DD>
|
||||
As a Tcl variable, using standard <B>$</B> notation.
|
||||
The variable's value will be used as the operand.
|
||||
<P><DT>[3]<DD>
|
||||
As a string enclosed in double-quotes.
|
||||
The expression parser will perform backslash, variable, and
|
||||
command substitutions on the information between the quotes,
|
||||
and use the resulting value as the operand
|
||||
<P><DT>[4]<DD>
|
||||
As a string enclosed in braces.
|
||||
The characters between the open brace and matching close brace
|
||||
will be used as the operand without any substitutions.
|
||||
<P><DT>[5]<DD>
|
||||
As a Tcl command enclosed in brackets.
|
||||
The command will be executed and its result will be used as
|
||||
the operand.
|
||||
<P><DT>[6]<DD>
|
||||
As a mathematical function whose arguments have any of the above
|
||||
forms for operands, such as <B>sin($x)</B>. See below for a list of defined
|
||||
functions.
|
||||
<P></DL>
|
||||
<P>
|
||||
Where substitutions occur above (e.g. inside quoted strings), they
|
||||
are performed by the expression's instructions.
|
||||
However, an additional layer of substitution may already have
|
||||
been performed by the command parser before the expression
|
||||
processor was called.
|
||||
As discussed below, it is usually best to enclose expressions
|
||||
in braces to prevent the command parser from performing substitutions
|
||||
on the contents.
|
||||
<P>
|
||||
For some examples of simple expressions, suppose the variable
|
||||
<B>a</B> has the value 3 and
|
||||
the variable <B>b</B> has the value 6.
|
||||
Then the command on the left side of each of the lines below
|
||||
will produce the value on the right side of the line:
|
||||
<PRE><B>expr 3.1 + $a 6.1
|
||||
expr 2 + "$a.$b" 5.6
|
||||
expr 4*[llength "6 2"] 8
|
||||
expr {{word one} < "word $a"} 0</B></PRE>
|
||||
<H3><A NAME="M6">OPERATORS</A></H3>
|
||||
The valid operators are listed below, grouped in decreasing order
|
||||
of precedence:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M7"><B>- + ~ !</B></A><DD>
|
||||
Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands
|
||||
may be applied to string operands, and bit-wise NOT may be
|
||||
applied only to integers.
|
||||
<P><DT><A NAME="M8"><B>* / %</B></A><DD>
|
||||
Multiply, divide, remainder. None of these operands may be
|
||||
applied to string operands, and remainder may be applied only
|
||||
to integers.
|
||||
The remainder will always have the same sign as the divisor and
|
||||
an absolute value smaller than the divisor.
|
||||
<P><DT><A NAME="M9"><B>+ -</B></A><DD>
|
||||
Add and subtract. Valid for any numeric operands.
|
||||
<P><DT><A NAME="M10"><B><< >></B></A><DD>
|
||||
Left and right shift. Valid for integer operands only.
|
||||
A right shift always propagates the sign bit.
|
||||
<P><DT><A NAME="M11"><B>< > <= >=</B></A><DD>
|
||||
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 may be applied to strings as well as numeric operands,
|
||||
in which case string comparison is used.
|
||||
<P><DT><A NAME="M12"><B>== !=</B></A><DD>
|
||||
Boolean equal and not equal. Each operator produces a zero/one result.
|
||||
Valid for all operand types.
|
||||
<P><DT><A NAME="M13"><B>&</B></A><DD>
|
||||
Bit-wise AND. Valid for integer operands only.
|
||||
<P><DT><A NAME="M14"><B>^</B></A><DD>
|
||||
Bit-wise exclusive OR. Valid for integer operands only.
|
||||
<P><DT><A NAME="M15"><B>|</B></A><DD>
|
||||
Bit-wise OR. Valid for integer operands only.
|
||||
<P><DT><A NAME="M16"><B>&&</B></A><DD>
|
||||
Logical AND. Produces a 1 result if both operands are non-zero,
|
||||
0 otherwise.
|
||||
Valid for boolean and numeric (integers or floating-point) operands only.
|
||||
<P><DT><A NAME="M17"><B>||</B></A><DD>
|
||||
Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.
|
||||
Valid for boolean and numeric (integers or floating-point) operands only.
|
||||
<P><DT><A NAME="M18"><I>x</I><B>?</B><I>y</I><B>:</B><I>z</I></A><DD>
|
||||
If-then-else, as in C. If <I>x</I>
|
||||
evaluates to non-zero, then the result is the value of <I>y</I>.
|
||||
Otherwise the result is the value of <I>z</I>.
|
||||
The <I>x</I> operand must have a numeric value.
|
||||
<P></DL>
|
||||
<P>
|
||||
See the C manual for more details on the results
|
||||
produced by each operator.
|
||||
All of the binary operators group left-to-right within the same
|
||||
precedence level. For example, the command
|
||||
<PRE><B>expr 4*2 < 7</B></PRE>
|
||||
returns 0.
|
||||
<P>
|
||||
The <B>&&</B>, <B>||</B>, and <B>?:</B> operators have ``lazy
|
||||
evaluation'', just as in C,
|
||||
which means that operands are not evaluated if they are
|
||||
not needed to determine the outcome. For example, in the command
|
||||
<PRE><B>expr {$v ? [a] : [b]}</B></PRE>
|
||||
only one of <B>[a]</B> or <B>[b]</B> will actually be evaluated,
|
||||
depending on the value of <B>$v</B>. Note, however, that this is
|
||||
only true if the entire expression is enclosed in braces; otherwise
|
||||
the Tcl parser will evaluate both <B>[a]</B> and <B>[b]</B> before
|
||||
invoking the <B>expr</B> command.
|
||||
<H3><A NAME="M19">MATH FUNCTIONS</A></H3>
|
||||
Tcl supports the following mathematical functions in expressions:
|
||||
<PRE><B>abs</B> <B>cosh</B> <B>log</B> <B>sqrt</B>
|
||||
<B>acos</B> <B>double</B> <B>log10</B> <B>srand</B>
|
||||
<B>asin</B> <B>exp</B> <B>pow</B> <B>tan</B>
|
||||
<B>atan</B> <B>floor</B> <B>rand</B> <B>tanh</B>
|
||||
<B>atan2</B> <B>fmod</B> <B>round</B>
|
||||
<B>ceil</B> <B>hypot</B> <B>sin</B>
|
||||
<B>cos</B> <B>int</B> <B>sinh</B></PRE>
|
||||
<P>
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M20"><B>abs(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the absolute value of <I>arg</I>. <I>Arg</I> may be either
|
||||
integer or floating-point, and the result is returned in the same form.
|
||||
<P><DT><A NAME="M21"><B>acos(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the arc cosine of <I>arg</I>, in the range [0,pi]
|
||||
radians. <I>Arg</I> should be in the range [-1,1].
|
||||
<P><DT><A NAME="M22"><B>asin(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the arc sine of <I>arg</I>, in the range [-pi/2,pi/2] radians.
|
||||
<I>Arg</I> should be in the range [-1,1].
|
||||
<P><DT><A NAME="M23"><B>atan(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the arc tangent of <I>arg</I>, in the range [-pi/2,pi/2] radians.
|
||||
<P><DT><A NAME="M24"><B>atan2(</B><I>x, y</I><B>)</B></A><DD>
|
||||
Returns the arc tangent of <I>y</I>/<I>x</I>, in the range [-pi,pi]
|
||||
radians. <I>x</I> and <I>y</I> cannot both be 0.
|
||||
<P><DT><A NAME="M25"><B>ceil(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the smallest integer value not less than <I>arg</I>.
|
||||
<P><DT><A NAME="M26"><B>cos(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the cosine of <I>arg</I>, measured in radians.
|
||||
<P><DT><A NAME="M27"><B>cosh(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the hyperbolic cosine of <I>arg</I>. If the result would cause
|
||||
an overflow, an error is returned.
|
||||
<P><DT><A NAME="M28"><B>double(</B><I>arg</I><B>)</B></A><DD>
|
||||
If <I>arg</I> is a floating value, returns <I>arg</I>, otherwise converts
|
||||
<I>arg</I> to floating and returns the converted value.
|
||||
<P><DT><A NAME="M29"><B>exp(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the exponential of <I>arg</I>, defined as e**<I>arg</I>. If the
|
||||
result would cause an overflow, an error is returned.
|
||||
<P><DT><A NAME="M30"><B>floor(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the largest integral value not greater than <I>arg</I>.
|
||||
<P><DT><A NAME="M31"><B>fmod(</B><I>x, y</I><B>)</B></A><DD>
|
||||
Returns the floating-point remainder of the division of <I>x</I> by
|
||||
<I>y</I>. If <I>y</I> is 0, an error is returned.
|
||||
<P><DT><A NAME="M32"><B>hypot(</B><I>x, y</I><B>)</B></A><DD>
|
||||
Computes the length of the hypotenuse of a right-angled triangle
|
||||
(<I>x</I>*<I>x</I>+<I>y</I>*<I>y</I>).
|
||||
<P><DT><A NAME="M33"><B>int(</B><I>arg</I><B>)</B></A><DD>
|
||||
If <I>arg</I> is an integer value, returns <I>arg</I>, otherwise converts
|
||||
<I>arg</I> to integer by truncation and returns the converted value.
|
||||
<P><DT><A NAME="M34"><B>log(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the natural logarithm of <I>arg</I>. <I>Arg</I> must be a
|
||||
positive value.
|
||||
<P><DT><A NAME="M35"><B>log10(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the base 10 logarithm of <I>arg</I>. <I>Arg</I> must be a
|
||||
positive value.
|
||||
<P><DT><A NAME="M36"><B>pow(</B><I>x, y</I><B>)</B></A><DD>
|
||||
Computes the value of <I>x</I> raised to the power <I>y</I>. If <I>x</I>
|
||||
is negative, <I>y</I> must be an integer value.
|
||||
<P><DT><A NAME="M37"><B>rand()</B></A><DD>
|
||||
Returns a floating point number from zero to just less than one or,
|
||||
in mathematical terms, the range [0,1). The seed comes from the
|
||||
internal clock of the machine or may be set manual with the srand
|
||||
function.
|
||||
<P><DT><A NAME="M38"><B>round(</B><I>arg</I><B>)</B></A><DD>
|
||||
If <I>arg</I> is an integer value, returns <I>arg</I>, otherwise converts
|
||||
<I>arg</I> to integer by rounding and returns the converted value.
|
||||
<P><DT><A NAME="M39"><B>sin(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the sine of <I>arg</I>, measured in radians.
|
||||
<P><DT><A NAME="M40"><B>sinh(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the hyperbolic sine of <I>arg</I>. If the result would cause
|
||||
an overflow, an error is returned.
|
||||
<P><DT><A NAME="M41"><B>sqrt(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the square root of <I>arg</I>. <I>Arg</I> must be non-negative.
|
||||
<P><DT><A NAME="M42"><B>srand(</B><I>arg</I><B>)</B></A><DD>
|
||||
The <I>arg</I>, which must be an integer, is used to reset the seed for
|
||||
the random number generator. Returns the first random number from
|
||||
that seed. Each interpreter has it's own seed.
|
||||
<P><DT><A NAME="M43"><B>tan(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the tangent of <I>arg</I>, measured in radians.
|
||||
<P><DT><A NAME="M44"><B>tanh(</B><I>arg</I><B>)</B></A><DD>
|
||||
Returns the hyperbolic tangent of <I>arg</I>.
|
||||
<P></DL>
|
||||
<P>
|
||||
In addition to these predefined functions, applications may
|
||||
define additional functions using <B><A HREF="../TkLib/CrtMathFnc.htm">Tcl_CreateMathFunc</A></B>().
|
||||
<H3><A NAME="M45">TYPES, OVERFLOW, AND PRECISION</A></H3>
|
||||
All internal computations involving integers are done with the C type
|
||||
<I>long</I>, and all internal computations involving floating-point are
|
||||
done with the C type <I>double</I>.
|
||||
When converting a string to floating-point, exponent overflow is
|
||||
detected and results in a Tcl error.
|
||||
For conversion to integer from string, detection of overflow depends
|
||||
on the behavior of some routines in the local C library, so it should
|
||||
be regarded as unreliable.
|
||||
In any case, integer overflow and underflow are generally not detected
|
||||
reliably for intermediate results. Floating-point overflow and underflow
|
||||
are detected to the degree supported by the hardware, which is generally
|
||||
pretty reliable.
|
||||
<P>
|
||||
Conversion among internal representations for integer, floating-point,
|
||||
and string operands is done automatically as needed.
|
||||
For arithmetic computations, integers are used until some
|
||||
floating-point number is introduced, after which floating-point is used.
|
||||
For example,
|
||||
<PRE><B>expr 5 / 4</B></PRE>
|
||||
returns 1, while
|
||||
<PRE><B>expr 5 / 4.0</B>
|
||||
<B>expr 5 / ( [string length "abcd"] + 0.0 )</B></PRE>
|
||||
both return 1.25.
|
||||
Floating-point values are always returned with a ``<B>.</B>''
|
||||
or an <B>e</B> so that they will not look like integer values. For
|
||||
example,
|
||||
<PRE><B>expr 20.0/5.0</B></PRE>
|
||||
returns <B>4.0</B>, not <B>4</B>.
|
||||
|
||||
<H3><A NAME="M46">STRING OPERATIONS</A></H3>
|
||||
String values may be used as operands of the comparison operators,
|
||||
although the expression evaluator tries to do comparisons as integer
|
||||
or floating-point when it can.
|
||||
If one of the operands of a comparison is a string and the other
|
||||
has a numeric value, the numeric operand is converted back to
|
||||
a string using the C <I>sprintf</I> format specifier
|
||||
<B>%d</B> for integers and <B>%g</B> for floating-point values.
|
||||
For example, the commands
|
||||
<PRE><B>expr {"0x03" > "2"}</B>
|
||||
<B>expr {"0y" < "0x12"}</B></PRE>
|
||||
both return 1. The first comparison is done using integer
|
||||
comparison, and the second is done using string comparison after
|
||||
the second operand is converted to the string <B>18</B>.
|
||||
Because of Tcl's tendency to treat values as numbers whenever
|
||||
possible, it isn't generally a good idea to use operators like <B>==</B>
|
||||
when you really want string comparison and the values of the
|
||||
operands could be arbitrary; it's better in these cases to use
|
||||
the <B><A HREF="../TkCmd/string.htm">string</A></B> command instead.
|
||||
|
||||
<H3><A NAME="M47">PERFORMANCE CONSIDERATIONS</A></H3>
|
||||
Enclose expressions in braces for the best speed and the smallest
|
||||
storage requirements.
|
||||
This allows the Tcl bytecode compiler to generate the best code.
|
||||
<P>
|
||||
As mentioned above, expressions are substituted twice:
|
||||
once by the Tcl parser and once by the <B>expr</B> command.
|
||||
For example, the commands
|
||||
<PRE><B>set a 3</B>
|
||||
<B>set b {$a + 2}</B>
|
||||
<B>expr $b*4</B></PRE>
|
||||
return 11, not a multiple of 4.
|
||||
This is because the Tcl parser will first substitute <B>$a + 2</B> for
|
||||
the variable <B>b</B>,
|
||||
then the <B>expr</B> command will evaluate the expression <B>$a + 2*4</B>.
|
||||
<P>
|
||||
Most expressions do not require a second round of substitutions.
|
||||
Either they are enclosed in braces or, if not,
|
||||
their variable and command substitutions yield numbers or strings
|
||||
that don't themselves require substitutions.
|
||||
However, because a few unbraced expressions
|
||||
need two rounds of substitutions,
|
||||
the bytecode compiler must emit
|
||||
additional instructions to handle this situation.
|
||||
The most expensive code is required for
|
||||
unbraced expressions that contain command substitutions.
|
||||
These expressions must be implemented by generating new code
|
||||
each time the expression is executed.
|
||||
|
||||
<H3><A NAME="M48">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#arithmetic">arithmetic</A>, <A href="../Keywords/B.htm#boolean">boolean</A>, <A href="../Keywords/C.htm#compare">compare</A>, <A href="../Keywords/E.htm#expression">expression</A>, <A href="../Keywords/F.htm#fuzzy comparison">fuzzy comparison</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-2000 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
22
hlp/en/tcl/fblocked.htm
Normal file
22
hlp/en/tcl/fblocked.htm
Normal file
@@ -0,0 +1,22 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - fblocked manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
fblocked - Test whether the last input operation exhausted all available input
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>fblocked </B><I>channelId</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>fblocked</B> command returns 1 if the most recent input operation
|
||||
on <I>channelId</I> returned less information than requested because all
|
||||
available input was exhausted.
|
||||
For example, if <B><A HREF="../TkCmd/gets.htm">gets</A></B> is invoked when there are only three
|
||||
characters available for input and no end-of-line sequence, <B><A HREF="../TkCmd/gets.htm">gets</A></B>
|
||||
returns an empty string and a subsequent call to <B>fblocked</B> will
|
||||
return 1.
|
||||
<P>
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/gets.htm">gets</A></B>, <B><A HREF="../TkCmd/open.htm">open</A></B>, <B><A HREF="../TkCmd/read.htm">read</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/N.htm#nonblocking">nonblocking</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
189
hlp/en/tcl/fconfigure.htm
Normal file
189
hlp/en/tcl/fconfigure.htm
Normal file
@@ -0,0 +1,189 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - fconfigure manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="fconfigure.htm#M2" NAME="L290">NAME</A>
|
||||
<DL><DD>fconfigure - Set and get options on a channel</DL>
|
||||
<DD><A HREF="fconfigure.htm#M3" NAME="L291">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>fconfigure </B><I>channelId</I>
|
||||
<DD><B>fconfigure </B><I>channelId</I> <I>name</I>
|
||||
<DD><B>fconfigure </B><I>channelId</I> <I>name value </I>?<I>name value ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="fconfigure.htm#M4" NAME="L292">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="fconfigure.htm#M5" NAME="L293"><B>-blocking</B> <I>boolean</I></A>
|
||||
<DD><A HREF="fconfigure.htm#M6" NAME="L294"><B>-buffering</B> <I>newValue</I></A>
|
||||
<DD><A HREF="fconfigure.htm#M7" NAME="L295"><B>-buffersize</B> <I>newSize</I></A>
|
||||
<DD><A HREF="fconfigure.htm#M8" NAME="L296"><B>-encoding</B> <I>name</I></A>
|
||||
<DD><A HREF="fconfigure.htm#M9" NAME="L297"><B>-eofchar</B> <I>char</I></A>
|
||||
<DD><A HREF="fconfigure.htm#M10" NAME="L298"><B>-eofchar</B> <B>{</B><I>inChar outChar</I><B>}</B></A>
|
||||
<DD><A HREF="fconfigure.htm#M11" NAME="L299"><B>-translation</B> <I>mode</I></A>
|
||||
<DD><A HREF="fconfigure.htm#M12" NAME="L300"><B>-translation</B> <B>{</B><I>inMode outMode</I><B>}</B></A>
|
||||
<DL>
|
||||
<DD><A HREF="fconfigure.htm#M13" NAME="L301"><B>auto</B></A>
|
||||
<DD><A HREF="fconfigure.htm#M14" NAME="L302"><B>binary</B></A>
|
||||
<DD><A HREF="fconfigure.htm#M15" NAME="L303"><B>cr</B></A>
|
||||
<DD><A HREF="fconfigure.htm#M16" NAME="L304"><B>crlf</B></A>
|
||||
<DD><A HREF="fconfigure.htm#M17" NAME="L305"><B>lf</B></A>
|
||||
</DL>
|
||||
</DL>
|
||||
<DD><A HREF="fconfigure.htm#M18" NAME="L306">SEE ALSO</A>
|
||||
<DD><A HREF="fconfigure.htm#M19" NAME="L307">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
fconfigure - Set and get options on a channel
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>fconfigure </B><I>channelId</I><BR>
|
||||
<B>fconfigure </B><I>channelId</I> <I>name</I><BR>
|
||||
<B>fconfigure </B><I>channelId</I> <I>name value </I>?<I>name value ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>fconfigure</B> command sets and retrieves options for channels.
|
||||
<I>ChannelId</I> identifies the channel for which to set or query an option.
|
||||
If no <I>name</I> or <I>value</I> arguments are supplied, the command
|
||||
returns a list containing alternating option names and values for the channel.
|
||||
If <I>name</I> is supplied but no <I>value</I> then the command returns
|
||||
the current value of the given option.
|
||||
If one or more pairs of <I>name</I> and <I>value</I> are supplied, the
|
||||
command sets each of the named options to the corresponding <I>value</I>;
|
||||
in this case the return value is an empty string.
|
||||
<P>
|
||||
The options described below are supported for all channels. In addition,
|
||||
each channel type may add options that only it supports. See the manual
|
||||
entry for the command that creates each type of channels for the options
|
||||
that that specific type of channel supports. For example, see the manual
|
||||
entry for the <B><A HREF="../TkCmd/socket.htm">socket</A></B> command for its additional options.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>-blocking</B> <I>boolean</I></A><DD>
|
||||
The <B>-blocking</B> option determines whether I/O operations on the
|
||||
channel can cause the process to block indefinitely.
|
||||
The value of the option must be a proper boolean value.
|
||||
Channels are normally in blocking mode; if a channel is placed into
|
||||
nonblocking mode it will affect the operation of the <B><A HREF="../TkCmd/gets.htm">gets</A></B>,
|
||||
<B><A HREF="../TkCmd/read.htm">read</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B>, <B><A HREF="../TkCmd/flush.htm">flush</A></B>, and <B><A HREF="../TkCmd/close.htm">close</A></B> commands;
|
||||
see the documentation for those commands for details.
|
||||
For nonblocking mode to work correctly, the application must be
|
||||
using the Tcl event loop (e.g. by calling <B><A HREF="../TkLib/DoOneEvent.htm">Tcl_DoOneEvent</A></B> or
|
||||
invoking the <B><A HREF="../TkCmd/vwait.htm">vwait</A></B> command).
|
||||
<P><DT><A NAME="M6"><B>-buffering</B> <I>newValue</I></A><DD>
|
||||
If <I>newValue</I> is <B>full</B> then the I/O system will buffer output
|
||||
until its internal buffer is full or until the <B><A HREF="../TkCmd/flush.htm">flush</A></B> command is
|
||||
invoked. If <I>newValue</I> is <B>line</B>, then the I/O system will
|
||||
automatically flush output for the channel whenever a newline character
|
||||
is output. If <I>newValue</I> is <B>none</B>, the I/O system will flush
|
||||
automatically after every output operation. The default is for
|
||||
<B>-buffering</B> to be set to <B>full</B> except for channels that
|
||||
connect to terminal-like devices; for these channels the initial setting
|
||||
is <B>line</B>. Additionally, <B>stdin</B> and <B>stdout</B> are
|
||||
intially set to <B>line</B>, and <B>stderr</B> is set to <B>none</B>.
|
||||
<P><DT><A NAME="M7"><B>-buffersize</B> <I>newSize</I></A><DD>
|
||||
<I>Newvalue</I> must be an integer; its value is used to set the size of
|
||||
buffers, in bytes, subsequently allocated for this channel to store input
|
||||
or output. <I>Newvalue</I> must be between ten and one million, allowing
|
||||
buffers of ten to one million bytes in size.
|
||||
<P><DT><A NAME="M8"><B>-encoding</B> <I>name</I></A><DD>
|
||||
This option is used to specify the encoding of the channel, so that the data
|
||||
can be converted to and from Unicode for use in Tcl. For instance, in
|
||||
order for Tcl to read characters from a Japanese file in <B>shiftjis</B>
|
||||
and properly process and display the contents, the encoding would be set
|
||||
to <B>shiftjis</B>. Thereafter, when reading from the channel, the bytes in
|
||||
the Japanese file would be converted to Unicode as they are read.
|
||||
Writing is also supported - as Tcl strings are written to the channel they
|
||||
will automatically be converted to the specified encoding on output.
|
||||
<P>
|
||||
If a file contains pure binary data (for instance, a JPEG image), the
|
||||
encoding for the channel should be configured to be <B><A HREF="../TkCmd/binary.htm">binary</A></B>. Tcl
|
||||
will then assign no interpretation to the data in the file and simply read or
|
||||
write raw bytes. The Tcl <B><A HREF="../TkCmd/binary.htm">binary</A></B> command can be used to manipulate this
|
||||
byte-oriented data.
|
||||
<P>The default encoding for newly opened channels is the same platform- and
|
||||
locale-dependent system encoding used for interfacing with the operating
|
||||
system.
|
||||
<P><DT><A NAME="M9"><B>-eofchar</B> <I>char</I></A><DD>
|
||||
<P><DT><A NAME="M10"><B>-eofchar</B> <B>{</B><I>inChar outChar</I><B>}</B></A><DD>
|
||||
This option supports DOS file systems that use Control-z (\x1a) as an
|
||||
end of file marker. If <I>char</I> is not an empty string, then this
|
||||
character signals end-of-file when it is encountered during input. For
|
||||
output, the end-of-file character is output when the channel is closed.
|
||||
If <I>char</I> is the empty string, then there is no special end of file
|
||||
character marker. For read-write channels, a two-element list specifies
|
||||
the end of file marker for input and output, respectively. As a
|
||||
convenience, when setting the end-of-file character for a read-write
|
||||
channel you can specify a single value that will apply to both reading
|
||||
and writing. When querying the end-of-file character of a read-write
|
||||
channel, a two-element list will always be returned. The default value
|
||||
for <B>-eofchar</B> is the empty string in all cases except for files
|
||||
under Windows. In that case the <B>-eofchar</B> is Control-z (\x1a) for
|
||||
reading and the empty string for writing.
|
||||
<P><DT><A NAME="M11"><B>-translation</B> <I>mode</I></A><DD>
|
||||
<P><DT><A NAME="M12"><B>-translation</B> <B>{</B><I>inMode outMode</I><B>}</B></A><DD>
|
||||
In Tcl scripts the end of a line is always represented using a single
|
||||
newline character (\n). However, in actual files and devices the end of
|
||||
a line may be represented differently on different platforms, or even for
|
||||
different devices on the same platform. For example, under UNIX newlines
|
||||
are used in files, whereas carriage-return-linefeed sequences are
|
||||
normally used in network connections. On input (i.e., with <B><A HREF="../TkCmd/gets.htm">gets</A></B>
|
||||
and <B><A HREF="../TkCmd/read.htm">read</A></B>) the Tcl I/O system automatically translates the external
|
||||
end-of-line representation into newline characters. Upon output (i.e.,
|
||||
with <B><A HREF="../TkCmd/puts.htm">puts</A></B>), the I/O system translates newlines to the external
|
||||
end-of-line representation. The default translation mode, <B>auto</B>,
|
||||
handles all the common cases automatically, but the <B>-translation</B>
|
||||
option provides explicit control over the end of line translations.
|
||||
<P>
|
||||
The value associated with <B>-translation</B> is a single item for
|
||||
read-only and write-only channels. The value is a two-element list for
|
||||
read-write channels; the read translation mode is the first element of
|
||||
the list, and the write translation mode is the second element. As a
|
||||
convenience, when setting the translation mode for a read-write channel
|
||||
you can specify a single value that will apply to both reading and
|
||||
writing. When querying the translation mode of a read-write channel, a
|
||||
two-element list will always be returned. The following values are
|
||||
currently supported:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M13"><B>auto</B></A><DD>
|
||||
As the input translation mode, <B>auto</B> treats any of newline
|
||||
(<B>lf</B>), carriage return (<B>cr</B>), or carriage return followed by a
|
||||
newline (<B>crlf</B>) as the end of line representation. The end of line
|
||||
representation can even change from line-to-line, and all cases are
|
||||
translated to a newline. As the output translation mode, <B>auto</B>
|
||||
chooses a platform specific representation; for sockets on all platforms
|
||||
Tcl chooses <B>crlf</B>, for all Unix flavors, it chooses <B>lf</B>, for the
|
||||
Macintosh platform it chooses <B>cr</B> and for the various flavors of
|
||||
Windows it chooses <B>crlf</B>. The default setting for
|
||||
<B>-translation</B> is <B>auto</B> for both input and output.
|
||||
<P><DT><A NAME="M14"><B>binary</B></A><DD>
|
||||
No end-of-line translations are performed. This is nearly identical to
|
||||
<B>lf</B> mode, except that in addition <B><A HREF="../TkCmd/binary.htm">binary</A></B> mode also sets the
|
||||
end-of-file character to the empty string (which disables it) and sets the
|
||||
encoding to <B><A HREF="../TkCmd/binary.htm">binary</A></B> (which disables encoding filtering). See the
|
||||
description of <B>-eofchar</B> and <B>-encoding</B> for more information.
|
||||
<P><DT><A NAME="M15"><B>cr</B></A><DD>
|
||||
The end of a line in the underlying file or device is represented by a
|
||||
single carriage return character. As the input translation mode,
|
||||
<B>cr</B> mode converts carriage returns to newline characters. As the
|
||||
output translation mode, <B>cr</B> mode translates newline characters to
|
||||
carriage returns. This mode is typically used on Macintosh platforms.
|
||||
<P><DT><A NAME="M16"><B>crlf</B></A><DD>
|
||||
The end of a line in the underlying file or device is represented by a
|
||||
carriage return character followed by a linefeed character. As the input
|
||||
translation mode, <B>crlf</B> mode converts carriage-return-linefeed
|
||||
sequences to newline characters. As the output translation mode,
|
||||
<B>crlf</B> mode translates newline characters to carriage-return-linefeed
|
||||
sequences. This mode is typically used on Windows platforms and for
|
||||
network connections.
|
||||
<P><DT><A NAME="M17"><B>lf</B></A><DD>
|
||||
The end of a line in the underlying file or device is represented by a
|
||||
single newline (linefeed) character. In this mode no translations occur
|
||||
during either input or output. This mode is typically used on UNIX
|
||||
platforms.
|
||||
<P></DL>
|
||||
<P></DL>
|
||||
<P>
|
||||
<H3><A NAME="M18">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/close.htm">close</A></B>, <B><A HREF="../TkCmd/flush.htm">flush</A></B>, <B><A HREF="../TkCmd/gets.htm">gets</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B>, <B><A HREF="../TkCmd/read.htm">read</A></B>, <B><A HREF="../TkCmd/socket.htm">socket</A></B>
|
||||
<H3><A NAME="M19">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/B.htm#buffering">buffering</A>, <A href="../Keywords/C.htm#carriage return">carriage return</A>, <A href="../Keywords/E.htm#end of line">end of line</A>, <A href="../Keywords/F.htm#flushing">flushing</A>, <A href="../Keywords/L.htm#linemode">linemode</A>, <A href="../Keywords/N.htm#newline">newline</A>, <A href="../Keywords/N.htm#nonblocking">nonblocking</A>, <A href="../Keywords/P.htm#platform">platform</A>, <A href="../Keywords/T.htm#translation">translation</A>, <A href="../Keywords/E.htm#encoding">encoding</A>, <A href="../Keywords/F.htm#filter">filter</A>, <A href="../Keywords/B.htm#byte array">byte array</A>, <A href="../Keywords/B.htm#binary">binary</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
108
hlp/en/tcl/fcopy.htm
Normal file
108
hlp/en/tcl/fcopy.htm
Normal file
@@ -0,0 +1,108 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - fcopy manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
fcopy - Copy data from one channel to another.
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>fcopy </B><I>inchan</I> <I>outchan</I> ?<B>-size </B><I>size</I>? ?<B>-command </B><I>callback</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>fcopy</B> command copies data from one I/O channel, <I>inchan</I> to another I/O channel, <I>outchan</I>.
|
||||
The <B>fcopy</B> command leverages the buffering in the Tcl I/O system to
|
||||
avoid extra copies and to avoid buffering too much data in
|
||||
main memory when copying large files to slow destinations like
|
||||
network sockets.
|
||||
<P>
|
||||
The <B>fcopy</B>
|
||||
command transfers data from <I>inchan</I> until end of file
|
||||
or <I>size</I> bytes have been
|
||||
transferred. If no <B>-size</B> argument is given,
|
||||
then the copy goes until end of file.
|
||||
All the data read from <I>inchan</I> is copied to <I>outchan</I>.
|
||||
Without the <B>-command</B> option, <B>fcopy</B> blocks until the copy is complete
|
||||
and returns the number of bytes written to <I>outchan</I>.
|
||||
<P>
|
||||
The <B>-command</B> argument makes <B>fcopy</B> work in the background.
|
||||
In this case it returns immediately and the <I>callback</I> is invoked
|
||||
later when the copy completes.
|
||||
The <I>callback</I> is called with
|
||||
one or two additional
|
||||
arguments that indicates how many bytes were written to <I>outchan</I>.
|
||||
If an error occurred during the background copy, the second argument is the
|
||||
error string associated with the error.
|
||||
With a background copy,
|
||||
it is not necessary to put <I>inchan</I> or <I>outchan</I> into
|
||||
non-blocking mode; the <B>fcopy</B> command takes care of that automatically.
|
||||
However, it is necessary to enter the event loop by using
|
||||
the <B><A HREF="../TkCmd/vwait.htm">vwait</A></B> command or by using Tk.
|
||||
<P>
|
||||
You are not allowed to do other I/O operations with
|
||||
<I>inchan</I> or <I>outchan</I> during a background fcopy.
|
||||
If either <I>inchan</I> or <I>outchan</I> get closed
|
||||
while the copy is in progress, the current copy is stopped
|
||||
and the command callback is <I>not</I> made.
|
||||
If <I>inchan</I> is closed,
|
||||
then all data already queued for <I>outchan</I> is written out.
|
||||
<P>
|
||||
Note that <I>inchan</I> can become readable during a background copy.
|
||||
You should turn off any <B><A HREF="../TkCmd/fileevent.htm">fileevent</A></B> handlers during a background
|
||||
copy so those handlers do not interfere with the copy.
|
||||
Any I/O attempted by a <B><A HREF="../TkCmd/fileevent.htm">fileevent</A></B> handler will get a "channel busy" error.
|
||||
<P>
|
||||
<B>Fcopy</B> translates end-of-line sequences in <I>inchan</I> and <I>outchan</I>
|
||||
according to the <B>-translation</B> option
|
||||
for these channels.
|
||||
See the manual entry for <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> for details on the
|
||||
<B>-translation</B> option.
|
||||
The translations mean that the number of bytes read from <I>inchan</I>
|
||||
can be different than the number of bytes written to <I>outchan</I>.
|
||||
Only the number of bytes written to <I>outchan</I> is reported,
|
||||
either as the return value of a synchronous <B>fcopy</B> or
|
||||
as the argument to the callback for an asynchronous <B>fcopy</B>.
|
||||
|
||||
<H3><A NAME="M5">EXAMPLE</A></H3>
|
||||
This first example shows how the callback gets
|
||||
passed the number of bytes transferred.
|
||||
It also uses vwait to put the application into the event loop.
|
||||
Of course, this simplified example could be done without the command
|
||||
callback.
|
||||
<PRE>proc Cleanup {in out bytes {error {}}} {
|
||||
global total
|
||||
set total $bytes
|
||||
close $in
|
||||
close $out
|
||||
if {[string length $error] != 0} {
|
||||
# error occurred during the copy
|
||||
}
|
||||
}
|
||||
set in [open $file1]
|
||||
set out [socket $server $port]
|
||||
fcopy $in $out -command [list Cleanup $in $out]
|
||||
vwait total</PRE>
|
||||
<P>
|
||||
The second example copies in chunks and tests for end of file
|
||||
in the command callback
|
||||
<PRE>proc CopyMore {in out chunk bytes {error {}}} {
|
||||
global total done
|
||||
incr total $bytes
|
||||
if {([string length $error] != 0) || [eof $in] {
|
||||
set done $total
|
||||
close $in
|
||||
close $out
|
||||
} else {
|
||||
fcopy $in $out -command [list CopyMore $in $out $chunk] \
|
||||
-size $chunk
|
||||
}
|
||||
}
|
||||
set in [open $file1]
|
||||
set out [socket $server $port]
|
||||
set chunk 1024
|
||||
set total 0
|
||||
fcopy $in $out -command [list CopyMore $in $out $chunk] -size $chunk
|
||||
vwait done</PRE>
|
||||
<H3><A NAME="M6">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/eof.htm">eof</A></B>, <B><A HREF="../TkCmd/fblocked.htm">fblocked</A></B>, <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B>
|
||||
<H3><A NAME="M7">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/E.htm#end of line">end of line</A>, <A href="../Keywords/E.htm#end of file">end of file</A>, <A href="../Keywords/N.htm#nonblocking">nonblocking</A>, <A href="../Keywords/R.htm#read">read</A>, <A href="../Keywords/T.htm#translation">translation</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
307
hlp/en/tcl/file.htm
Normal file
307
hlp/en/tcl/file.htm
Normal file
@@ -0,0 +1,307 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - file manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="file.htm#M2" NAME="L314">NAME</A>
|
||||
<DL><DD>file - Manipulate file names and attributes</DL>
|
||||
<DD><A HREF="file.htm#M3" NAME="L315">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>file </B><I>option</I> <I>name</I> ?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="file.htm#M4" NAME="L316">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="file.htm#M5" NAME="L317"><B>file atime </B><I>name</I> ?<B>time</B>?</A>
|
||||
<DD><A HREF="file.htm#M6" NAME="L318"><B>file attributes </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M7" NAME="L319"><B>file channels ?</B><I>pattern</I>?</A>
|
||||
<DD><A HREF="file.htm#M8" NAME="L320"><B>file copy </B>?<B>-force</B>? ?<B>- -</B>? <I>source</I> <I>target</I></A>
|
||||
<DD><A HREF="file.htm#M9" NAME="L321"><B>file delete </B>?<B>-force</B>? ?<B>- -</B>? <I>pathname</I> ?<I>pathname</I> ... ?</A>
|
||||
<DD><A HREF="file.htm#M10" NAME="L322"><B>file dirname </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M11" NAME="L323"><B>file executable </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M12" NAME="L324"><B>file exists </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M13" NAME="L325"><B>file extension </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M14" NAME="L326"><B>file isdirectory </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M15" NAME="L327"><B>file isfile </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M16" NAME="L328"><B>file join </B><I>name</I> ?<I>name ...</I>?</A>
|
||||
<DD><A HREF="file.htm#M17" NAME="L329"><B>file lstat </B><I>name varName</I></A>
|
||||
<DD><A HREF="file.htm#M18" NAME="L330"><B>file mkdir </B><I>dir</I> ?<I>dir</I> ...?</A>
|
||||
<DD><A HREF="file.htm#M19" NAME="L331"><B>file mtime </B><I>name</I> ?<I>time</I>?</A>
|
||||
<DD><A HREF="file.htm#M20" NAME="L332"><B>file nativename </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M21" NAME="L333"><B>file owned </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M22" NAME="L334"><B>file pathtype </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M23" NAME="L335"><B>file readable </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M24" NAME="L336"><B>file readlink </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M25" NAME="L337"><B>file rename </B>?<B>-force</B>? ?<B>- -</B>? <I>source</I> <I>target</I></A>
|
||||
<DD><A HREF="file.htm#M26" NAME="L338"><B>file rename </B>?<B>-force</B>? ?<B>- -</B>? <I>source</I> ?<I>source</I> ...? <I>targetDir</I></A>
|
||||
<DD><A HREF="file.htm#M27" NAME="L339"><B>file rootname </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M28" NAME="L340"><B>file size </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M29" NAME="L341"><B>file split </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M30" NAME="L342"><B>file stat </B><I>name varName</I></A>
|
||||
<DD><A HREF="file.htm#M31" NAME="L343"><B>file tail </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M32" NAME="L344"><B>file type </B><I>name</I></A>
|
||||
<DD><A HREF="file.htm#M33" NAME="L345"><B>file volume</B></A>
|
||||
<DD><A HREF="file.htm#M34" NAME="L346"><B>file writable </B><I>name</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="file.htm#M35" NAME="L347">PORTABILITY ISSUES</A>
|
||||
<DL>
|
||||
<DD><A HREF="file.htm#M36" NAME="L348"><B>Unix</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="file.htm#M37" NAME="L349">SEE ALSO</A>
|
||||
<DD><A HREF="file.htm#M38" NAME="L350">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
file - Manipulate file names and attributes
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>file </B><I>option</I> <I>name</I> ?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command provides several operations on a file's name or attributes.
|
||||
<I>Name</I> is the name of a file; if it starts with a tilde, then tilde
|
||||
substitution is done before executing the command (see the manual entry for
|
||||
<B><A HREF="../TkCmd/filename.htm">filename</A></B> for details). <I>Option</I> indicates what to do with the
|
||||
file name. Any unique abbreviation for <I>option</I> is acceptable. The
|
||||
valid options are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>file atime </B><I>name</I> ?<B>time</B>?</A><DD>
|
||||
Returns a decimal string giving the time at which file <I>name</I> was last
|
||||
accessed. If <I>time</I> is specified, it is an access time to set
|
||||
for the file. The time is measured in the standard POSIX fashion as
|
||||
seconds from a fixed starting time (often January 1, 1970). If the file
|
||||
doesn't exist or its access time cannot be queried or set then an error is
|
||||
generated. On Windows, FAT file systems do not support access time.
|
||||
<P><DT><A NAME="M6"><B>file attributes </B><I>name</I></A><DD>
|
||||
<BR>
|
||||
<B>file attributes </B><I>name</I> ?<B><A HREF="../TclCmd/option.htm">option</A></B>?
|
||||
<BR>
|
||||
<B>file attributes </B><I>name</I> ?<B>option value option value...</B>?
|
||||
<DL><P><DD>
|
||||
This subcommand returns or sets platform specific values associated
|
||||
with a file. The first form returns a list of the platform specific
|
||||
flags and their values. The second form returns the value for the
|
||||
specific option. The third form sets one or more of the values. The
|
||||
values are as follows:
|
||||
<P>
|
||||
On Unix, <B>-group</B> gets or sets the group name for the file. A group id
|
||||
can be given to the command, but it returns a group name. <B>-owner</B> gets
|
||||
or sets the user name of the owner of the file. The command returns the
|
||||
owner name, but the numerical id can be passed when setting the
|
||||
owner. <B>-permissions</B> sets or retrieves the octal code that chmod(1)
|
||||
uses. This command does also has limited support for setting using the
|
||||
symbolic attributes for chmod(1), of the form [ugo]?[[+-=][rwxst],[...]],
|
||||
where multiple symbolic attributes can be separated by commas (example:
|
||||
<B>u+s,go-rw</B> add sticky bit for user, remove read and write
|
||||
permissions for group and other). A simplified <B>ls</B> style string,
|
||||
of the form rwxrwxrwx (must be 9 characters), is also supported
|
||||
(example: <B>rwxr-xr-t</B> is equivalent to 01755).
|
||||
<P>
|
||||
On Windows, <B>-archive</B> gives the value or sets or clears the
|
||||
archive attribute of the file. <B>-hidden</B> gives the value or sets
|
||||
or clears the hidden attribute of the file. <B>-longname</B> will
|
||||
expand each path element to its long version. This attribute cannot be
|
||||
set. <B>-readonly</B> gives the value or sets or clears the readonly
|
||||
attribute of the file. <B>-shortname</B> gives a string where every
|
||||
path element is replaced with its short (8.3) version of the
|
||||
name. This attribute cannot be set. <B>-system</B> gives or sets or
|
||||
clears the value of the system attribute of the file.
|
||||
<P>
|
||||
On Macintosh, <B>-creator</B> gives or sets the Finder creator type of
|
||||
the file. <B>-hidden</B> gives or sets or clears the hidden attribute
|
||||
of the file. <B>-readonly</B> gives or sets or clears the readonly
|
||||
attribute of the file. Note that directories can only be locked if
|
||||
File Sharing is turned on. <B>-type</B> gives or sets the Finder file
|
||||
type for the file.
|
||||
</DL>
|
||||
<P><DT><A NAME="M7"><B>file channels ?</B><I>pattern</I>?</A><DD>
|
||||
If <I>pattern</I> isn't specified, returns a list of names of all
|
||||
registered open channels in this interpreter. If <I>pattern</I> is
|
||||
specified, only those names matching <I>pattern</I> are returned. Matching
|
||||
is determined using the same rules as for <B><A HREF="../TkCmd/string.htm">string match</A></B>.
|
||||
<P><DT><A NAME="M8"><B>file copy </B>?<B>-force</B>? ?<B>- -</B>? <I>source</I> <I>target</I></A><DD>
|
||||
<BR>
|
||||
<B>file copy </B>?<B>-force</B>? ?<B>- -</B>? <I>source</I> ?<I>source</I> ...? <I>targetDir</I>
|
||||
<DL><P><DD>
|
||||
The first form makes a copy of the file or directory <I>source</I> under
|
||||
the pathname <I>target</I>. If <I>target</I> is an existing directory,
|
||||
then the second form is used. The second form makes a copy inside
|
||||
<I>targetDir</I> of each <I>source</I> file listed. If a directory is
|
||||
specified as a <I>source</I>, then the contents of the directory will be
|
||||
recursively copied into <I>targetDir</I>. Existing files will not be
|
||||
overwritten unless the <B>-force</B> option is specified. Trying to
|
||||
overwrite a non-empty directory, overwrite a directory with a file, or a
|
||||
file with a directory will all result in errors even if <I>-force</I> was
|
||||
specified. Arguments are processed in the order specified, halting at the
|
||||
first error, if any. A <B>- -</B> marks the end of switches; the argument
|
||||
following the <B>- -</B> will be treated as a <I>source</I> even if it
|
||||
starts with a <B>-</B>.
|
||||
</DL>
|
||||
<P><DT><A NAME="M9"><B>file delete </B>?<B>-force</B>? ?<B>- -</B>? <I>pathname</I> ?<I>pathname</I> ... ?</A><DD>
|
||||
Removes the file or directory specified by each <I>pathname</I> argument.
|
||||
Non-empty directories will be removed only if the <B>-force</B> option is
|
||||
specified. Trying to delete a non-existant file is not considered an
|
||||
error. Trying to delete a read-only file will cause the file to be deleted,
|
||||
even if the <B>-force</B> flags is not specified. Arguments are processed
|
||||
in the order specified, halting at the first error, if any. A <B>- -</B>
|
||||
marks the end of switches; the argument following the <B>- -</B> will be
|
||||
treated as a <I>pathname</I> even if it starts with a <B>-</B>.
|
||||
<P><DT><A NAME="M10"><B>file dirname </B><I>name</I></A><DD>
|
||||
Returns a name comprised of all of the path components in <I>name</I>
|
||||
excluding the last element. If <I>name</I> is a relative file name and
|
||||
only contains one path element, then returns ``<B>.</B>'' (or ``<B>:</B>''
|
||||
on the Macintosh). If <I>name</I> refers to a root directory, then the
|
||||
root directory is returned. For example,
|
||||
<PRE><B>file dirname c:/</B></PRE>
|
||||
returns <B>c:/</B>.
|
||||
<P>
|
||||
Note that tilde substitution will only be
|
||||
performed if it is necessary to complete the command. For example,
|
||||
<PRE><B>file dirname ~/src/foo.c</B></PRE>
|
||||
returns <B>~/src</B>, whereas
|
||||
<PRE><B>file dirname ~</B></PRE>
|
||||
returns <B>/home</B> (or something similar).
|
||||
<P><DT><A NAME="M11"><B>file executable </B><I>name</I></A><DD>
|
||||
Returns <B>1</B> if file <I>name</I> is executable by the current user,
|
||||
<B>0</B> otherwise.
|
||||
<P><DT><A NAME="M12"><B>file exists </B><I>name</I></A><DD>
|
||||
Returns <B>1</B> if file <I>name</I> exists and the current user has
|
||||
search privileges for the directories leading to it, <B>0</B> otherwise.
|
||||
<P><DT><A NAME="M13"><B>file extension </B><I>name</I></A><DD>
|
||||
Returns all of the characters in <I>name</I> after and including the last
|
||||
dot in the last element of <I>name</I>. If there is no dot in the last
|
||||
element of <I>name</I> then returns the empty string.
|
||||
<P><DT><A NAME="M14"><B>file isdirectory </B><I>name</I></A><DD>
|
||||
Returns <B>1</B> if file <I>name</I> is a directory, <B>0</B> otherwise.
|
||||
<P><DT><A NAME="M15"><B>file isfile </B><I>name</I></A><DD>
|
||||
Returns <B>1</B> if file <I>name</I> is a regular file, <B>0</B> otherwise.
|
||||
<P><DT><A NAME="M16"><B>file join </B><I>name</I> ?<I>name ...</I>?</A><DD>
|
||||
Takes one or more file names and combines them, using the correct path
|
||||
separator for the current platform. If a particular <I>name</I> is
|
||||
relative, then it will be joined to the previous file name argument.
|
||||
Otherwise, any earlier arguments will be discarded, and joining will
|
||||
proceed from the current argument. For example,
|
||||
<PRE><B>file join a b /foo bar</B></PRE>
|
||||
returns <B>/foo/bar</B>.
|
||||
<P>Note that any of the names can contain separators, and that the result
|
||||
is always canonical for the current platform: <B>/</B> for Unix and
|
||||
Windows, and <B>:</B> for Macintosh.
|
||||
<P><DT><A NAME="M17"><B>file lstat </B><I>name varName</I></A><DD>
|
||||
Same as <B>stat</B> option (see below) except uses the <I>lstat</I>
|
||||
kernel call instead of <I>stat</I>. This means that if <I>name</I>
|
||||
refers to a symbolic link the information returned in <I>varName</I>
|
||||
is for the link rather than the file it refers to. On systems that
|
||||
don't support symbolic links this option behaves exactly the same
|
||||
as the <B>stat</B> option.
|
||||
<P><DT><A NAME="M18"><B>file mkdir </B><I>dir</I> ?<I>dir</I> ...?</A><DD>
|
||||
Creates each directory specified. For each pathname <I>dir</I> specified,
|
||||
this command will create all non-existing parent directories as
|
||||
well as <I>dir</I> itself. If an existing directory is specified, then
|
||||
no action is taken and no error is returned. Trying to overwrite an existing
|
||||
file with a directory will result in an error. Arguments are processed in
|
||||
the order specified, halting at the first error, if any.
|
||||
<P><DT><A NAME="M19"><B>file mtime </B><I>name</I> ?<I>time</I>?</A><DD>
|
||||
Returns a decimal string giving the time at which file <I>name</I> was last
|
||||
modified. If <I>time</I> is specified, it is a modification time to set for
|
||||
the file (equivalent to Unix <B>touch</B>). The time is measured in the
|
||||
standard POSIX fashion as seconds from a fixed starting time (often January
|
||||
1, 1970). If the file doesn't exist or its modified time cannot be queried
|
||||
or set then an error is generated.
|
||||
<P><DT><A NAME="M20"><B>file nativename </B><I>name</I></A><DD>
|
||||
Returns the platform-specific name of the file. This is useful if the
|
||||
filename is needed to pass to a platform-specific call, such as exec
|
||||
under Windows or AppleScript on the Macintosh.
|
||||
<P><DT><A NAME="M21"><B>file owned </B><I>name</I></A><DD>
|
||||
Returns <B>1</B> if file <I>name</I> is owned by the current user, <B>0</B>
|
||||
otherwise.
|
||||
<P><DT><A NAME="M22"><B>file pathtype </B><I>name</I></A><DD>
|
||||
Returns one of <B>absolute</B>, <B>relative</B>, <B>volumerelative</B>. If
|
||||
<I>name</I> refers to a specific file on a specific volume, the path type
|
||||
will be <B>absolute</B>. If <I>name</I> refers to a file relative to the
|
||||
current working directory, then the path type will be <B>relative</B>. If
|
||||
<I>name</I> refers to a file relative to the current working directory on
|
||||
a specified volume, or to a specific file on the current working volume, then
|
||||
the file type is <B>volumerelative</B>.
|
||||
<P><DT><A NAME="M23"><B>file readable </B><I>name</I></A><DD>
|
||||
Returns <B>1</B> if file <I>name</I> is readable by the current user,
|
||||
<B>0</B> otherwise.
|
||||
<P><DT><A NAME="M24"><B>file readlink </B><I>name</I></A><DD>
|
||||
Returns the value of the symbolic link given by <I>name</I> (i.e. the name
|
||||
of the file it points to). If <I>name</I> isn't a symbolic link or its
|
||||
value cannot be read, then an error is returned. On systems that don't
|
||||
support symbolic links this option is undefined.
|
||||
<P><DT><A NAME="M25"><B>file rename </B>?<B>-force</B>? ?<B>- -</B>? <I>source</I> <I>target</I></A>
|
||||
<DT><A NAME="M26"><B>file rename </B>?<B>-force</B>? ?<B>- -</B>? <I>source</I> ?<I>source</I> ...? <I>targetDir</I></A><DD>
|
||||
The first form takes the file or directory specified by pathname
|
||||
<I>source</I> and renames it to <I>target</I>, moving the file if the
|
||||
pathname <I>target</I> specifies a name in a different directory. If
|
||||
<I>target</I> is an existing directory, then the second form is used. The
|
||||
second form moves each <I>source</I> file or directory into the directory
|
||||
<I>targetDir</I>. Existing files will not be overwritten unless the
|
||||
<B>-force</B> option is specified. Trying to overwrite a non-empty
|
||||
directory, overwrite a directory with a file, or a file with a directory
|
||||
will all result in errors. Arguments are processed in the order specified,
|
||||
halting at the first error, if any. A <B>- -</B> marks the end of
|
||||
switches; the argument following the <B>- -</B> will be treated as a
|
||||
<I>source</I> even if it starts with a <B>-</B>.
|
||||
<P><DT><A NAME="M27"><B>file rootname </B><I>name</I></A><DD>
|
||||
Returns all of the characters in <I>name</I> up to but not including the
|
||||
last ``.'' character in the last component of name. If the last
|
||||
component of <I>name</I> doesn't contain a dot, then returns <I>name</I>.
|
||||
<P><DT><A NAME="M28"><B>file size </B><I>name</I></A><DD>
|
||||
Returns a decimal string giving the size of file <I>name</I> in bytes. If
|
||||
the file doesn't exist or its size cannot be queried then an error is
|
||||
generated.
|
||||
<P><DT><A NAME="M29"><B>file split </B><I>name</I></A><DD>
|
||||
Returns a list whose elements are the path components in <I>name</I>. The
|
||||
first element of the list will have the same path type as <I>name</I>.
|
||||
All other elements will be relative. Path separators will be discarded
|
||||
unless they are needed ensure that an element is unambiguously relative.
|
||||
For example, under Unix
|
||||
<PRE><B>file split /foo/~bar/baz</B></PRE>
|
||||
returns <B>/ foo ./~bar baz</B> to ensure that later commands
|
||||
that use the third component do not attempt to perform tilde
|
||||
substitution.
|
||||
<P><DT><A NAME="M30"><B>file stat </B><I>name varName</I></A><DD>
|
||||
Invokes the <B>stat</B> kernel call on <I>name</I>, and uses the variable
|
||||
given by <I>varName</I> to hold information returned from the kernel call.
|
||||
<I>VarName</I> is treated as an array variable, and the following elements
|
||||
of that variable are set: <B>atime</B>, <B>ctime</B>, <B>dev</B>, <B>gid</B>,
|
||||
<B>ino</B>, <B>mode</B>, <B>mtime</B>, <B>nlink</B>, <B>size</B>, <B>type</B>,
|
||||
<B>uid</B>. Each element except <B>type</B> is a decimal string with the
|
||||
value of the corresponding field from the <B>stat</B> return structure;
|
||||
see the manual entry for <B>stat</B> for details on the meanings of the
|
||||
values. The <B>type</B> element gives the type of the file in the same
|
||||
form returned by the command <B>file type</B>. This command returns an
|
||||
empty string.
|
||||
<P><DT><A NAME="M31"><B>file tail </B><I>name</I></A><DD>
|
||||
Returns all of the characters in <I>name</I> after the last directory
|
||||
separator. If <I>name</I> contains no separators then returns
|
||||
<I>name</I>.
|
||||
<P><DT><A NAME="M32"><B>file type </B><I>name</I></A><DD>
|
||||
Returns a string giving the type of file <I>name</I>, which will be one of
|
||||
<B>file</B>, <B>directory</B>, <B>characterSpecial</B>, <B>blockSpecial</B>,
|
||||
<B>fifo</B>, <B>link</B>, or <B><A HREF="../TkCmd/socket.htm">socket</A></B>.
|
||||
<P><DT><A NAME="M33"><B>file volume</B></A><DD>
|
||||
Returns the absolute paths to the volumes mounted on the system, as a
|
||||
proper Tcl list. On the Macintosh, this will be a list of the mounted
|
||||
drives, both local and network. N.B. if two drives have the same name,
|
||||
they will both appear on the volume list, but there is currently no way,
|
||||
from Tcl, to access any but the first of these drives. On UNIX, the
|
||||
command will always return "/", since all filesystems are locally mounted.
|
||||
On Windows, it will return a list of the available local drives
|
||||
(e.g. {a:/ c:/}).
|
||||
<P><DT><A NAME="M34"><B>file writable </B><I>name</I></A><DD>
|
||||
Returns <B>1</B> if file <I>name</I> is writable by the current user,
|
||||
<B>0</B> otherwise.
|
||||
<P></DL>
|
||||
<H3><A NAME="M35">PORTABILITY ISSUES</A></H3>
|
||||
<DL>
|
||||
<P><DT><A NAME="M36"><B>Unix</B></A><DD>
|
||||
These commands always operate using the real user and group identifiers,
|
||||
not the effective ones.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M37">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/filename.htm">filename</A></B>
|
||||
<H3><A NAME="M38">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#attributes">attributes</A>, <A href="../Keywords/C.htm#copy files">copy files</A>, <A href="../Keywords/D.htm#delete files">delete files</A>, <A href="../Keywords/D.htm#directory">directory</A>, <A href="../Keywords/F.htm#file">file</A>, <A href="../Keywords/M.htm#move files">move files</A>, <A href="../Keywords/N.htm#name">name</A>, <A href="../Keywords/R.htm#rename files">rename files</A>, <A href="../Keywords/S.htm#stat">stat</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
95
hlp/en/tcl/fileevent.htm
Normal file
95
hlp/en/tcl/fileevent.htm
Normal file
@@ -0,0 +1,95 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - fileevent manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
fileevent - Execute a script when a channel becomes readable or writable
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>fileevent </B><I>channelId </I><B>readable </B>?<I>script</I>?<BR>
|
||||
<B>fileevent </B><I>channelId </I><B>writable </B>?<I>script</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command is used to create <I>file event handlers</I>. A file event
|
||||
handler is a binding between a channel and a script, such that the script
|
||||
is evaluated whenever the channel becomes readable or writable. File event
|
||||
handlers are most commonly used to allow data to be received from another
|
||||
process on an event-driven basis, so that the receiver can continue to
|
||||
interact with the user while waiting for the data to arrive. If an
|
||||
application invokes <B><A HREF="../TkCmd/gets.htm">gets</A></B> or <B><A HREF="../TkCmd/read.htm">read</A></B> on a blocking channel when
|
||||
there is no input data available, the process will block; until the input
|
||||
data arrives, it will not be able to service other events, so it will
|
||||
appear to the user to ``freeze up''. With <B>fileevent</B>, the process can
|
||||
tell when data is present and only invoke <B><A HREF="../TkCmd/gets.htm">gets</A></B> or <B><A HREF="../TkCmd/read.htm">read</A></B> when
|
||||
they won't block.
|
||||
<P>
|
||||
The <I>channelId</I> argument to <B>fileevent</B> refers to an open channel,
|
||||
such as the return value from a previous <B><A HREF="../TkCmd/open.htm">open</A></B> or <B><A HREF="../TkCmd/socket.htm">socket</A></B>
|
||||
command.
|
||||
If the <I>script</I> argument is specified, then <B>fileevent</B>
|
||||
creates a new event handler: <I>script</I> will be evaluated
|
||||
whenever the channel becomes readable or writable (depending on the
|
||||
second argument to <B>fileevent</B>).
|
||||
In this case <B>fileevent</B> returns an empty string.
|
||||
The <B>readable</B> and <B>writable</B> event handlers for a file
|
||||
are independent, and may be created and deleted separately.
|
||||
However, there may be at most one <B>readable</B> and one <B>writable</B>
|
||||
handler for a file at a given time in a given interpreter.
|
||||
If <B>fileevent</B> is called when the specified handler already
|
||||
exists in the invoking interpreter, the new script replaces the old one.
|
||||
<P>
|
||||
If the <I>script</I> argument is not specified, <B>fileevent</B>
|
||||
returns the current script for <I>channelId</I>, or an empty string
|
||||
if there is none.
|
||||
If the <I>script</I> argument is specified as an empty string
|
||||
then the event handler is deleted, so that no script will be invoked.
|
||||
A file event handler is also deleted automatically whenever
|
||||
its channel is closed or its interpreter is deleted.
|
||||
<P>
|
||||
A channel is considered to be readable if there is unread data
|
||||
available on the underlying device.
|
||||
A channel is also considered to be readable if there is unread
|
||||
data in an input buffer, except in the special case where the
|
||||
most recent attempt to read from the channel was a <B><A HREF="../TkCmd/gets.htm">gets</A></B>
|
||||
call that could not find a complete line in the input buffer.
|
||||
This feature allows a file to be read a line at a time in nonblocking mode
|
||||
using events.
|
||||
A channel is also considered to be readable if an end of file or
|
||||
error condition is present on the underlying file or device.
|
||||
It is important for <I>script</I> to check for these conditions
|
||||
and handle them appropriately; for example, if there is no special
|
||||
check for end of file, an infinite loop may occur where <I>script</I>
|
||||
reads no data, returns, and is immediately invoked again.
|
||||
<P>
|
||||
A channel is considered to be writable if at least one byte of data
|
||||
can be written to the underlying file or device without blocking,
|
||||
or if an error condition is present on the underlying file or device.
|
||||
<P>
|
||||
Event-driven I/O works best for channels that have been
|
||||
placed into nonblocking mode with the <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> command.
|
||||
In blocking mode, a <B><A HREF="../TkCmd/puts.htm">puts</A></B> command may block if you give it
|
||||
more data than the underlying file or device can accept, and a
|
||||
<B><A HREF="../TkCmd/gets.htm">gets</A></B> or <B><A HREF="../TkCmd/read.htm">read</A></B> command will block if you attempt to read
|
||||
more data than is ready; no events will be processed while the
|
||||
commands block.
|
||||
In nonblocking mode <B><A HREF="../TkCmd/puts.htm">puts</A></B>, <B><A HREF="../TkCmd/read.htm">read</A></B>, and <B><A HREF="../TkCmd/gets.htm">gets</A></B> never block.
|
||||
See the documentation for the individual commands for information
|
||||
on how they handle blocking and nonblocking channels.
|
||||
<P>
|
||||
The script for a file event is executed at global level (outside the
|
||||
context of any Tcl procedure) in the interpreter in which the
|
||||
<B>fileevent</B> command was invoked.
|
||||
If an error occurs while executing the script then the
|
||||
<B><A HREF="../TkCmd/bgerror.htm">bgerror</A></B> mechanism is used to report the error.
|
||||
In addition, the file event handler is deleted if it ever returns
|
||||
an error; this is done in order to prevent infinite loops due to
|
||||
buggy handlers.
|
||||
|
||||
<H3><A NAME="M5">CREDITS</A></H3>
|
||||
<B>fileevent</B> is based on the <B>addinput</B> command created
|
||||
by Mark Diekhans.
|
||||
|
||||
<H3><A NAME="M6">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/bgerror.htm">bgerror</A></B>, <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B>, <B><A HREF="../TkCmd/gets.htm">gets</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B>, <B><A HREF="../TkCmd/read.htm">read</A></B>
|
||||
<H3><A NAME="M7">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#asynchronous I/O">asynchronous I/O</A>, <A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/E.htm#event handler">event handler</A>, <A href="../Keywords/N.htm#nonblocking">nonblocking</A>, <A href="../Keywords/R.htm#readable">readable</A>, <A href="../Keywords/S.htm#script">script</A>, <A href="../Keywords/W.htm#writable.">writable.</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
209
hlp/en/tcl/filename.htm
Normal file
209
hlp/en/tcl/filename.htm
Normal file
@@ -0,0 +1,209 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - filename manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="filename.htm#M2" NAME="L357">NAME</A>
|
||||
<DL><DD>filename - File name conventions supported by Tcl commands</DL>
|
||||
<DD><A HREF="filename.htm#M3" NAME="L358">INTRODUCTION</A>
|
||||
<DD><A HREF="filename.htm#M4" NAME="L359">PATH TYPES</A>
|
||||
<DD><A HREF="filename.htm#M5" NAME="L360">PATH SYNTAX</A>
|
||||
<DL>
|
||||
<DD><A HREF="filename.htm#M6" NAME="L361"><B>mac</B></A>
|
||||
<DL>
|
||||
<DD><A HREF="filename.htm#M7" NAME="L362"><B>:</B></A>
|
||||
<DD><A HREF="filename.htm#M8" NAME="L363"><B>MyFile</B></A>
|
||||
<DD><A HREF="filename.htm#M9" NAME="L364"><B>MyDisk:MyFile</B></A>
|
||||
<DD><A HREF="filename.htm#M10" NAME="L365"><B>:MyDir:MyFile</B></A>
|
||||
<DD><A HREF="filename.htm#M11" NAME="L366"><B>::MyFile</B></A>
|
||||
<DD><A HREF="filename.htm#M12" NAME="L367"><B>:::MyFile</B></A>
|
||||
<DD><A HREF="filename.htm#M13" NAME="L368"><B>/MyDisk/MyFile</B></A>
|
||||
<DD><A HREF="filename.htm#M14" NAME="L369"><B> ../MyFile</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="filename.htm#M15" NAME="L370"><B>unix</B></A>
|
||||
<DL>
|
||||
<DD><A HREF="filename.htm#M16" NAME="L371"><B>/</B></A>
|
||||
<DD><A HREF="filename.htm#M17" NAME="L372"><B>/etc/passwd</B></A>
|
||||
<DD><A HREF="filename.htm#M18" NAME="L373"><B> .</B></A>
|
||||
<DD><A HREF="filename.htm#M19" NAME="L374"><B>foo</B></A>
|
||||
<DD><A HREF="filename.htm#M20" NAME="L375"><B>foo/bar</B></A>
|
||||
<DD><A HREF="filename.htm#M21" NAME="L376"><B> ../foo</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="filename.htm#M22" NAME="L377"><B>windows</B></A>
|
||||
<DL>
|
||||
<DD><A HREF="filename.htm#M23" NAME="L378"><B> \\Host\share/file</B></A>
|
||||
<DD><A HREF="filename.htm#M24" NAME="L379"><B>c:foo</B></A>
|
||||
<DD><A HREF="filename.htm#M25" NAME="L380"><B>c:/foo</B></A>
|
||||
<DD><A HREF="filename.htm#M26" NAME="L381"><B>foo\bar</B></A>
|
||||
<DD><A HREF="filename.htm#M27" NAME="L382"><B> \foo</B></A>
|
||||
</DL>
|
||||
</DL>
|
||||
<DD><A HREF="filename.htm#M28" NAME="L383">TILDE SUBSTITUTION</A>
|
||||
<DD><A HREF="filename.htm#M29" NAME="L384">PORTABILITY ISSUES</A>
|
||||
<DD><A HREF="filename.htm#M30" NAME="L385">KEYWORDS</A>
|
||||
<DD><A HREF="filename.htm#M31" NAME="L386">SEE ALSO</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
filename - File name conventions supported by Tcl commands
|
||||
<H3><A NAME="M3">INTRODUCTION</A></H3>
|
||||
All Tcl commands and C procedures that take file names as arguments
|
||||
expect the file names to be in one of three forms, depending on the
|
||||
current platform. On each platform, Tcl supports file names in the
|
||||
standard forms(s) for that platform. In addition, on all platforms,
|
||||
Tcl supports a Unix-like syntax intended to provide a convenient way
|
||||
of constructing simple file names. However, scripts that are intended
|
||||
to be portable should not assume a particular form for file names.
|
||||
Instead, portable scripts must use the <B><A HREF="../TkCmd/file.htm">file split</A></B> and <B>file
|
||||
join</B> commands to manipulate file names (see the <B><A HREF="../TkCmd/file.htm">file</A></B> manual
|
||||
entry for more details).
|
||||
|
||||
<H3><A NAME="M4">PATH TYPES</A></H3>
|
||||
File names are grouped into three general types based on the starting point
|
||||
for the path used to specify the file: absolute, relative, and
|
||||
volume-relative. Absolute names are completely qualified, giving a path to
|
||||
the file relative to a particular volume and the root directory on that
|
||||
volume. Relative names are unqualified, giving a path to the file relative
|
||||
to the current working directory. Volume-relative names are partially
|
||||
qualified, either giving the path relative to the root directory on the
|
||||
current volume, or relative to the current directory of the specified
|
||||
volume. The <B><A HREF="../TkCmd/file.htm">file pathtype</A></B> command can be used to determine the
|
||||
type of a given path.
|
||||
|
||||
<H3><A NAME="M5">PATH SYNTAX</A></H3>
|
||||
The rules for native names depend on the value reported in the Tcl
|
||||
array element <B>tcl_platform(platform)</B>:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>mac</B></A><DD>
|
||||
On Apple Macintosh systems, Tcl supports two forms of path names. The
|
||||
normal Mac style names use colons as path separators. Paths may be
|
||||
relative or absolute, and file names may contain any character other
|
||||
than colon. A leading colon causes the rest of the path to be
|
||||
interpreted relative to the current directory. If a path contains a
|
||||
colon that is not at the beginning, then the path is interpreted as an
|
||||
absolute path. Sequences of two or more colons anywhere in the path
|
||||
are used to construct relative paths where <B>::</B> refers to the
|
||||
parent of the current directory, <B>:::</B> refers to the parent of the
|
||||
parent, and so forth.
|
||||
<P>
|
||||
In addition to Macintosh style names, Tcl also supports a subset of
|
||||
Unix-like names. If a path contains no colons, then it is interpreted
|
||||
like a Unix path. Slash is used as the path separator. The file name
|
||||
<B> .</B> refers to the current directory, and <B> ..</B> refers to the
|
||||
parent of the current directory. However, some names like <B>/</B> or
|
||||
<B>/..</B> have no mapping, and are interpreted as Macintosh names. In
|
||||
general, commands that generate file names will return Macintosh style
|
||||
names, but commands that accept file names will take both Macintosh
|
||||
and Unix-style names.
|
||||
<P>
|
||||
The following examples illustrate various forms of path names:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M7"><B>:</B></A><DD>
|
||||
Relative path to the current folder.
|
||||
<P><DT><A NAME="M8"><B>MyFile</B></A><DD>
|
||||
Relative path to a file named <B>MyFile</B> in the current folder.
|
||||
<P><DT><A NAME="M9"><B>MyDisk:MyFile</B></A><DD>
|
||||
Absolute path to a file named <B>MyFile</B> on the device named <B>MyDisk</B>.
|
||||
<P><DT><A NAME="M10"><B>:MyDir:MyFile</B></A><DD>
|
||||
Relative path to a file name <B>MyFile</B> in a folder named
|
||||
<B>MyDir</B> in the current folder.
|
||||
<P><DT><A NAME="M11"><B>::MyFile</B></A><DD>
|
||||
Relative path to a file named <B>MyFile</B> in the folder above the
|
||||
current folder.
|
||||
<P><DT><A NAME="M12"><B>:::MyFile</B></A><DD>
|
||||
Relative path to a file named <B>MyFile</B> in the folder two levels above the
|
||||
current folder.
|
||||
<P><DT><A NAME="M13"><B>/MyDisk/MyFile</B></A><DD>
|
||||
Absolute path to a file named <B>MyFile</B> on the device named
|
||||
<B>MyDisk</B>.
|
||||
<P><DT><A NAME="M14"><B> ../MyFile</B></A><DD>
|
||||
Relative path to a file named <B>MyFile</B> in the folder above the
|
||||
current folder.
|
||||
<P></DL>
|
||||
<P><DT><A NAME="M15"><B>unix</B></A><DD>
|
||||
On Unix platforms, Tcl uses path names where the components are
|
||||
separated by slashes. Path names may be relative or absolute, and
|
||||
file names may contain any character other than slash. The file names
|
||||
<B> .</B> and <B> ..</B> are special and refer to the current directory
|
||||
and the parent of the current directory respectively. Multiple
|
||||
adjacent slash characters are interpreted as a single separator.
|
||||
The following examples illustrate various forms of path names:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M16"><B>/</B></A><DD>
|
||||
Absolute path to the root directory.
|
||||
<P><DT><A NAME="M17"><B>/etc/passwd</B></A><DD>
|
||||
Absolute path to the file named <B>passwd</B> in the directory
|
||||
<B>etc</B> in the root directory.
|
||||
<P><DT><A NAME="M18"><B> .</B></A><DD>
|
||||
Relative path to the current directory.
|
||||
<P><DT><A NAME="M19"><B>foo</B></A><DD>
|
||||
Relative path to the file <B>foo</B> in the current directory.
|
||||
<P><DT><A NAME="M20"><B>foo/bar</B></A><DD>
|
||||
Relative path to the file <B>bar</B> in the directory <B>foo</B> in the
|
||||
current directory.
|
||||
<P><DT><A NAME="M21"><B> ../foo</B></A><DD>
|
||||
Relative path to the file <B>foo</B> in the directory above the current
|
||||
directory.
|
||||
<P></DL>
|
||||
<P><DT><A NAME="M22"><B>windows</B></A><DD>
|
||||
On Microsoft Windows platforms, Tcl supports both drive-relative and UNC
|
||||
style names. Both <B>/</B> and <B>\</B> may be used as directory separators
|
||||
in either type of name. Drive-relative names consist of an optional drive
|
||||
specifier followed by an absolute or relative path. UNC paths follow the
|
||||
general form <B>\\servername\sharename\path\file</B>. In both forms,
|
||||
the file names <B>.</B> and <B>..</B> are special and refer to the current
|
||||
directory and the parent of the current directory respectively. The
|
||||
following examples illustrate various forms of path names:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M23"><B> \\Host\share/file</B></A><DD>
|
||||
Absolute UNC path to a file called <B><A HREF="../TkCmd/file.htm">file</A></B> in the root directory of
|
||||
the export point <B>share</B> on the host <B>Host</B>.
|
||||
<P><DT><A NAME="M24"><B>c:foo</B></A><DD>
|
||||
Volume-relative path to a file <B>foo</B> in the current directory on drive
|
||||
<B>c</B>.
|
||||
<P><DT><A NAME="M25"><B>c:/foo</B></A><DD>
|
||||
Absolute path to a file <B>foo</B> in the root directory of drive
|
||||
<B>c</B>.
|
||||
<P><DT><A NAME="M26"><B>foo\bar</B></A><DD>
|
||||
Relative path to a file <B>bar</B> in the <B>foo</B> directory in the current
|
||||
directory on the current volume.
|
||||
<P><DT><A NAME="M27"><B> \foo</B></A><DD>
|
||||
Volume-relative path to a file <B>foo</B> in the root directory of the current
|
||||
volume.
|
||||
<P></DL>
|
||||
<P></DL>
|
||||
<H3><A NAME="M28">TILDE SUBSTITUTION</A></H3>
|
||||
In addition to the file name rules described above, Tcl also supports
|
||||
<I>csh</I>-style tilde substitution. If a file name starts with a
|
||||
tilde, then the file name will be interpreted as if the first element
|
||||
is replaced with the location of the home directory for the given
|
||||
user. If the tilde is followed immediately by a separator, then the
|
||||
<B>$HOME</B> environment variable is substituted. Otherwise the
|
||||
characters between the tilde and the next separator are taken as a
|
||||
user name, which is used to retrieve the user's home directory for
|
||||
substitution.
|
||||
<P>
|
||||
The Macintosh and Windows platforms do not support tilde substitution
|
||||
when a user name follows the tilde. On these platforms, attempts to
|
||||
use a tilde followed by a user name will generate an error. File
|
||||
names that have a tilde without a user name will be substituted using
|
||||
the <B>$HOME</B> environment variable, just like for Unix.
|
||||
|
||||
<H3><A NAME="M29">PORTABILITY ISSUES</A></H3>
|
||||
Not all file systems are case sensitive, so scripts should avoid code
|
||||
that depends on the case of characters in a file name. In addition,
|
||||
the character sets allowed on different devices may differ, so scripts
|
||||
should choose file names that do not contain special characters like:
|
||||
<B><>:"/\|</B>. The safest approach is to use names consisting of
|
||||
alphanumeric characters only. Also Windows 3.1 only supports file
|
||||
names with a root of no more than 8 characters and an extension of no
|
||||
more than 3 characters.
|
||||
|
||||
<H3><A NAME="M30">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#current directory">current directory</A>, <A href="../Keywords/A.htm#absolute file name">absolute file name</A>, <A href="../Keywords/R.htm#relative file name">relative file name</A>, <A href="../Keywords/V.htm#volume-relative file name">volume-relative file name</A>, <A href="../Keywords/P.htm#portability">portability</A>
|
||||
<H3><A NAME="M31">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/glob.htm">glob</A></B>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
24
hlp/en/tcl/flush.htm
Normal file
24
hlp/en/tcl/flush.htm
Normal file
@@ -0,0 +1,24 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - flush manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
flush - Flush buffered output for a channel
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>flush </B><I>channelId</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Flushes any output that has been buffered for <I>channelId</I>.
|
||||
<I>ChannelId</I> must be a channel identifier such as returned by a previous
|
||||
<B><A HREF="../TkCmd/open.htm">open</A></B> or <B><A HREF="../TkCmd/socket.htm">socket</A></B> command, and it must have been opened for writing.
|
||||
If the channel is in blocking mode the command does not return until all the
|
||||
buffered output has been flushed to the channel. If the channel is in
|
||||
nonblocking mode, the command may return before all buffered output has been
|
||||
flushed; the remainder will be flushed in the background as fast as the
|
||||
underlying file or device is able to absorb it.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/open.htm">open</A></B>, <B><A HREF="../TkCmd/socket.htm">socket</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/B.htm#buffer">buffer</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/F.htm#flush">flush</A>, <A href="../Keywords/N.htm#nonblocking">nonblocking</A>, <A href="../Keywords/O.htm#output">output</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
49
hlp/en/tcl/for.htm
Normal file
49
hlp/en/tcl/for.htm
Normal file
@@ -0,0 +1,49 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - for manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
for - ``For'' loop
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>for </B><I>start test next body</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
<B>For</B> is a looping command, similar in structure to the C
|
||||
<B>for</B> statement. The <I>start</I>, <I>next</I>, and
|
||||
<I>body</I> arguments must be Tcl command strings, and <I>test</I>
|
||||
is an expression string.
|
||||
The <B>for</B> command first invokes the Tcl interpreter to
|
||||
execute <I>start</I>. Then it repeatedly evaluates <I>test</I> as
|
||||
an expression; if the result is non-zero it invokes the Tcl
|
||||
interpreter on <I>body</I>, then invokes the Tcl interpreter on <I>next</I>,
|
||||
then repeats the loop. The command terminates when <I>test</I> evaluates
|
||||
to 0. If a <B><A HREF="../TkCmd/continue.htm">continue</A></B> command is invoked within <I>body</I> then
|
||||
any remaining commands in the current execution of <I>body</I> are skipped;
|
||||
processing continues by invoking the Tcl interpreter on <I>next</I>, then
|
||||
evaluating <I>test</I>, and so on. If a <B><A HREF="../TkCmd/break.htm">break</A></B> command is invoked
|
||||
within <I>body</I>
|
||||
or <I>next</I>,
|
||||
then the <B>for</B> command will
|
||||
return immediately.
|
||||
The operation of <B><A HREF="../TkCmd/break.htm">break</A></B> and <B><A HREF="../TkCmd/continue.htm">continue</A></B> are similar to the
|
||||
corresponding statements in C.
|
||||
<B>For</B> returns an empty string.
|
||||
<P>
|
||||
Note: <I>test</I> should almost always be enclosed in braces. If not,
|
||||
variable substitutions will be made before the <B>for</B>
|
||||
command starts executing, which means that variable changes
|
||||
made by the loop body will not be considered in the expression.
|
||||
This is likely to result in an infinite loop. If <I>test</I> is
|
||||
enclosed in braces, variable substitutions are delayed until the
|
||||
expression is evaluated (before
|
||||
each loop iteration), so changes in the variables will be visible.
|
||||
For an example, try the following script with and without the braces
|
||||
around <B>$x<10</B>:
|
||||
<PRE>for {set x 0} {$x<10} {incr x} {
|
||||
puts "x is $x"
|
||||
}</PRE>
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/break.htm">break</A></B>, <B><A HREF="../TkCmd/continue.htm">continue</A></B>, <B><A HREF="../TkCmd/foreach.htm">foreach</A></B>, <B><A HREF="../TkCmd/while.htm">while</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/F.htm#for">for</A>, <A href="../Keywords/I.htm#iteration">iteration</A>, <A href="../Keywords/L.htm#looping">looping</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
70
hlp/en/tcl/foreach.htm
Normal file
70
hlp/en/tcl/foreach.htm
Normal file
@@ -0,0 +1,70 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - foreach manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
foreach - Iterate over all elements in one or more lists
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>foreach </B><I>varname list body</I><BR>
|
||||
<B>foreach </B><I>varlist1 list1</I> ?<I>varlist2 list2 ...</I>? <I>body</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>foreach</B> command implements a loop where the loop
|
||||
variable(s) take on values from one or more lists.
|
||||
In the simplest case there is one loop variable, <I>varname</I>,
|
||||
and one list, <I>list</I>, that is a list of values to assign to <I>varname</I>.
|
||||
The <I>body</I> argument is a Tcl script.
|
||||
For each element of <I>list</I> (in order
|
||||
from first to last), <B>foreach</B> assigns the contents of the
|
||||
element to <I>varname</I> as if the <B><A HREF="../TkCmd/lindex.htm">lindex</A></B> command had been used
|
||||
to extract the element, then calls the Tcl interpreter to execute
|
||||
<I>body</I>.
|
||||
<P>
|
||||
In the general case there can be more than one value list
|
||||
(e.g., <I>list1</I> and <I>list2</I>),
|
||||
and each value list can be associated with a list of loop variables
|
||||
(e.g., <I>varlist1</I> and <I>varlist2</I>).
|
||||
During each iteration of the loop
|
||||
the variables of each <I>varlist</I> are assigned
|
||||
consecutive values from the corresponding <I>list</I>.
|
||||
Values in each <I>list</I> are used in order from first to last,
|
||||
and each value is used exactly once.
|
||||
The total number of loop iterations is large enough to use
|
||||
up all the values from all the value lists.
|
||||
If a value list does not contain enough
|
||||
elements for each of its loop variables in each iteration,
|
||||
empty values are used for the missing elements.
|
||||
<P>
|
||||
The <B><A HREF="../TkCmd/break.htm">break</A></B> and <B><A HREF="../TkCmd/continue.htm">continue</A></B> statements may be
|
||||
invoked inside <I>body</I>, with the same effect as in the <B><A HREF="../TkCmd/for.htm">for</A></B>
|
||||
command. <B>Foreach</B> returns an empty string.
|
||||
<H3><A NAME="M5">EXAMPLES</A></H3>
|
||||
The following loop uses i and j as loop variables to iterate over
|
||||
pairs of elements of a single list.
|
||||
<PRE>set x {}
|
||||
foreach {i j} {a b c d e f} {
|
||||
lappend x $j $i
|
||||
}
|
||||
# The value of x is "b a d c f e"
|
||||
# There are 3 iterations of the loop.</PRE>
|
||||
<P>
|
||||
The next loop uses i and j to iterate over two lists in parallel.
|
||||
<PRE>set x {}
|
||||
foreach i {a b c} j {d e f g} {
|
||||
lappend x $i $j
|
||||
}
|
||||
# The value of x is "a d b e c f {} g"
|
||||
# There are 4 iterations of the loop.</PRE>
|
||||
<P>
|
||||
The two forms are combined in the following example.
|
||||
<PRE>set x {}
|
||||
foreach i {a b c} {j k} {d e f g} {
|
||||
lappend x $i $j $k
|
||||
}
|
||||
# The value of x is "a d e b f g c {} {}"
|
||||
# There are 3 iterations of the loop.</PRE>
|
||||
<H3><A NAME="M6">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/for.htm">for</A></B>, <B><A HREF="../TkCmd/while.htm">while</A></B>, <B><A HREF="../TkCmd/break.htm">break</A></B>, <B><A HREF="../TkCmd/continue.htm">continue</A></B>
|
||||
<H3><A NAME="M7">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/F.htm#foreach">foreach</A>, <A href="../Keywords/I.htm#iteration">iteration</A>, <A href="../Keywords/L.htm#list">list</A>, <A href="../Keywords/L.htm#looping">looping</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
230
hlp/en/tcl/format.htm
Normal file
230
hlp/en/tcl/format.htm
Normal file
@@ -0,0 +1,230 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - format manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="format.htm#M2" NAME="L403">NAME</A>
|
||||
<DL><DD>format - Format a string in the style of sprintf</DL>
|
||||
<DD><A HREF="format.htm#M3" NAME="L404">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>format </B><I>formatString </I>?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="format.htm#M4" NAME="L405">INTRODUCTION</A>
|
||||
<DD><A HREF="format.htm#M5" NAME="L406">DETAILS ON FORMATTING</A>
|
||||
<DL>
|
||||
<DD><A HREF="format.htm#M6" NAME="L407"><B>-</B></A>
|
||||
<DD><A HREF="format.htm#M7" NAME="L408"><B>+</B></A>
|
||||
<DD><A HREF="format.htm#M8" NAME="L409"><I>space</I></A>
|
||||
<DD><A HREF="format.htm#M9" NAME="L410"><B>0</B></A>
|
||||
<DD><A HREF="format.htm#M10" NAME="L411"><B>#</B></A>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="format.htm#M11" NAME="L412"><B>d</B></A>
|
||||
<DD><A HREF="format.htm#M12" NAME="L413"><B>u</B></A>
|
||||
<DD><A HREF="format.htm#M13" NAME="L414"><B>i</B></A>
|
||||
<DD><A HREF="format.htm#M14" NAME="L415"><B>o</B></A>
|
||||
<DD><A HREF="format.htm#M15" NAME="L416"><B>x</B> or <B>X</B></A>
|
||||
<DD><A HREF="format.htm#M16" NAME="L417"><B>c</B></A>
|
||||
<DD><A HREF="format.htm#M17" NAME="L418"><B>s</B></A>
|
||||
<DD><A HREF="format.htm#M18" NAME="L419"><B>f</B></A>
|
||||
<DD><A HREF="format.htm#M19" NAME="L420"><B>e</B> or <B>e</B></A>
|
||||
<DD><A HREF="format.htm#M20" NAME="L421"><B>g</B> or <B>G</B></A>
|
||||
<DD><A HREF="format.htm#M21" NAME="L422"><B>%</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="format.htm#M22" NAME="L423">DIFFERENCES FROM ANSI SPRINTF</A>
|
||||
<DL>
|
||||
</DL>
|
||||
<DD><A HREF="format.htm#M23" NAME="L424">SEE ALSO</A>
|
||||
<DD><A HREF="format.htm#M24" NAME="L425">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
format - Format a string in the style of sprintf
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>format </B><I>formatString </I>?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">INTRODUCTION</A></H3>
|
||||
This command generates a formatted string in the same way as the
|
||||
ANSI C <B>sprintf</B> procedure (it uses <B>sprintf</B> in its
|
||||
implementation).
|
||||
<I>FormatString</I> indicates how to format the result, using
|
||||
<B>%</B> conversion specifiers as in <B>sprintf</B>, and the additional
|
||||
arguments, if any, provide values to be substituted into the result.
|
||||
The return value from <B>format</B> is the formatted string.
|
||||
|
||||
<H3><A NAME="M5">DETAILS ON FORMATTING</A></H3>
|
||||
The command operates by scanning <I>formatString</I> from left to right.
|
||||
Each character from the format string is appended to the result
|
||||
string unless it is a percent sign.
|
||||
If the character is a <B>%</B> then it is not copied to the result string.
|
||||
Instead, the characters following the <B>%</B> character are treated as
|
||||
a conversion specifier.
|
||||
The conversion specifier controls the conversion of the next successive
|
||||
<I>arg</I> to a particular format and the result is appended to
|
||||
the result string in place of the conversion specifier.
|
||||
If there are multiple conversion specifiers in the format string,
|
||||
then each one controls the conversion of one additional <I>arg</I>.
|
||||
The <B>format</B> command must be given enough <I>arg</I>s to meet the needs
|
||||
of all of the conversion specifiers in <I>formatString</I>.
|
||||
<P>
|
||||
Each conversion specifier may contain up to six different parts:
|
||||
an XPG3 position specifier,
|
||||
a set of flags, a minimum field width, a precision, a length modifier,
|
||||
and a conversion character.
|
||||
Any of these fields may be omitted except for the conversion character.
|
||||
The fields that are present must appear in the order given above.
|
||||
The paragraphs below discuss each of these fields in turn.
|
||||
<P>
|
||||
If the <B>%</B> is followed by a decimal number and a <B>$</B>, as in
|
||||
``<B>%2$d</B>'', then the value to convert is not taken from the
|
||||
next sequential argument.
|
||||
Instead, it is taken from the argument indicated by the number,
|
||||
where 1 corresponds to the first <I>arg</I>.
|
||||
If the conversion specifier requires multiple arguments because
|
||||
of <B>*</B> characters in the specifier then
|
||||
successive arguments are used, starting with the argument
|
||||
given by the number.
|
||||
This follows the XPG3 conventions for positional specifiers.
|
||||
If there are any positional specifiers in <I>formatString</I>
|
||||
then all of the specifiers must be positional.
|
||||
<P>
|
||||
The second portion of a conversion specifier may contain any of the
|
||||
following flag characters, in any order:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>-</B></A><DD>
|
||||
Specifies that the converted argument should be left-justified
|
||||
in its field (numbers are normally right-justified with leading
|
||||
spaces if needed).
|
||||
<P><DT><A NAME="M7"><B>+</B></A><DD>
|
||||
Specifies that a number should always be printed with a sign,
|
||||
even if positive.
|
||||
<P><DT><A NAME="M8"><I>space</I></A><DD>
|
||||
Specifies that a space should be added to the beginning of the
|
||||
number if the first character isn't a sign.
|
||||
<P><DT><A NAME="M9"><B>0</B></A><DD>
|
||||
Specifies that the number should be padded on the left with
|
||||
zeroes instead of spaces.
|
||||
<P><DT><A NAME="M10"><B>#</B></A><DD>
|
||||
Requests an alternate output form. For <B>o</B> and <B>O</B>
|
||||
conversions it guarantees that the first digit is always <B>0</B>.
|
||||
For <B>x</B> or <B>X</B> conversions, <B>0x</B> or <B>0X</B> (respectively)
|
||||
will be added to the beginning of the result unless it is zero.
|
||||
For all floating-point conversions (<B>e</B>, <B>E</B>, <B>f</B>,
|
||||
<B>g</B>, and <B>G</B>) it guarantees that the result always
|
||||
has a decimal point.
|
||||
For <B>g</B> and <B>G</B> conversions it specifies that
|
||||
trailing zeroes should not be removed.
|
||||
<P></DL>
|
||||
<P>
|
||||
The third portion of a conversion specifier is a number giving a
|
||||
minimum field width for this conversion.
|
||||
It is typically used to make columns line up in tabular printouts.
|
||||
If the converted argument contains fewer characters than the
|
||||
minimum field width then it will be padded so that it is as wide
|
||||
as the minimum field width.
|
||||
Padding normally occurs by adding extra spaces on the left of the
|
||||
converted argument, but the <B>0</B> and <B>-</B> flags
|
||||
may be used to specify padding with zeroes on the left or with
|
||||
spaces on the right, respectively.
|
||||
If the minimum field width is specified as <B>*</B> rather than
|
||||
a number, then the next argument to the <B>format</B> command
|
||||
determines the minimum field width; it must be a numeric string.
|
||||
<P>
|
||||
The fourth portion of a conversion specifier is a precision,
|
||||
which consists of a period followed by a number.
|
||||
The number is used in different ways for different conversions.
|
||||
For <B>e</B>, <B>E</B>, and <B>f</B> conversions it specifies the number
|
||||
of digits to appear to the right of the decimal point.
|
||||
For <B>g</B> and <B>G</B> conversions it specifies the total number
|
||||
of digits to appear, including those on both sides of the decimal
|
||||
point (however, trailing zeroes after the decimal point will still
|
||||
be omitted unless the <B>#</B> flag has been specified).
|
||||
For integer conversions, it specifies a minimum number of digits
|
||||
to print (leading zeroes will be added if necessary).
|
||||
For <B>s</B> conversions it specifies the maximum number of characters to be
|
||||
printed; if the string is longer than this then the trailing characters will be dropped.
|
||||
If the precision is specified with <B>*</B> rather than a number
|
||||
then the next argument to the <B>format</B> command determines the precision;
|
||||
it must be a numeric string.
|
||||
<P>
|
||||
The fifth part of a conversion specifier is a length modifier,
|
||||
which must be <B>h</B> or <B>l</B>.
|
||||
If it is <B>h</B> it specifies that the numeric value should be
|
||||
truncated to a 16-bit value before converting.
|
||||
This option is rarely useful.
|
||||
The <B>l</B> modifier is ignored.
|
||||
<P>
|
||||
The last thing in a conversion specifier is an alphabetic character
|
||||
that determines what kind of conversion to perform.
|
||||
The following conversion characters are currently supported:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M11"><B>d</B></A><DD>
|
||||
Convert integer to signed decimal string.
|
||||
<P><DT><A NAME="M12"><B>u</B></A><DD>
|
||||
Convert integer to unsigned decimal string.
|
||||
<P><DT><A NAME="M13"><B>i</B></A><DD>
|
||||
Convert integer to signed decimal string; the integer may either be
|
||||
in decimal, in octal (with a leading <B>0</B>) or in hexadecimal
|
||||
(with a leading <B>0x</B>).
|
||||
<P><DT><A NAME="M14"><B>o</B></A><DD>
|
||||
Convert integer to unsigned octal string.
|
||||
<P><DT><A NAME="M15"><B>x</B> or <B>X</B></A><DD>
|
||||
Convert integer to unsigned hexadecimal string, using digits
|
||||
``0123456789abcdef'' for <B>x</B> and ``0123456789ABCDEF'' for <B>X</B>).
|
||||
<P><DT><A NAME="M16"><B>c</B></A><DD>
|
||||
Convert integer to the Unicode character it represents.
|
||||
<P><DT><A NAME="M17"><B>s</B></A><DD>
|
||||
No conversion; just insert string.
|
||||
<P><DT><A NAME="M18"><B>f</B></A><DD>
|
||||
Convert floating-point number to signed decimal string of
|
||||
the form <I>xx.yyy</I>, where the number of <I>y</I>'s is determined by
|
||||
the precision (default: 6).
|
||||
If the precision is 0 then no decimal point is output.
|
||||
<P><DT><A NAME="M19"><B>e</B> or <B>e</B></A><DD>
|
||||
Convert floating-point number to scientific notation in the
|
||||
form <I>x.yyy</I><B>e±</B><I>zz</I>, where the number of <I>y</I>'s is determined
|
||||
by the precision (default: 6).
|
||||
If the precision is 0 then no decimal point is output.
|
||||
If the <B>E</B> form is used then <B>E</B> is
|
||||
printed instead of <B>e</B>.
|
||||
<P><DT><A NAME="M20"><B>g</B> or <B>G</B></A><DD>
|
||||
If the exponent is less than -4 or greater than or equal to the
|
||||
precision, then convert floating-point number as for <B>%e</B> or
|
||||
<B>%E</B>.
|
||||
Otherwise convert as for <B>%f</B>.
|
||||
Trailing zeroes and a trailing decimal point are omitted.
|
||||
<P><DT><A NAME="M21"><B>%</B></A><DD>
|
||||
No conversion: just insert <B>%</B>.
|
||||
<P></DL>
|
||||
<P>
|
||||
For the numerical conversions the argument being converted must
|
||||
be an integer or floating-point string; format converts the argument
|
||||
to binary and then converts it back to a string according to
|
||||
the conversion specifier.
|
||||
|
||||
<H3><A NAME="M22">DIFFERENCES FROM ANSI SPRINTF</A></H3>
|
||||
The behavior of the format command is the same as the
|
||||
ANSI C <B>sprintf</B> procedure except for the following
|
||||
differences:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT>[1]<DD>
|
||||
<B>%p</B> and <B>%n</B> specifiers are not currently supported.
|
||||
<P><DT>[2]<DD>
|
||||
For <B>%c</B> conversions the argument must be a decimal string,
|
||||
which will then be converted to the corresponding character value.
|
||||
<P><DT>[3]<DD>
|
||||
The <B>l</B> modifier is ignored; integer values are always converted
|
||||
as if there were no modifier present and real values are always
|
||||
converted as if the <B>l</B> modifier were present (i.e. type
|
||||
<B>double</B> is used for the internal representation).
|
||||
If the <B>h</B> modifier is specified then integer values are truncated
|
||||
to <B>short</B> before conversion.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M23">SEE ALSO</A></H3>
|
||||
<B>sprintf</B>, <B><A HREF="../TkCmd/string.htm">string</A></B>
|
||||
<H3><A NAME="M24">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#conversion specifier">conversion specifier</A>, <A href="../Keywords/F.htm#format">format</A>, <A href="../Keywords/S.htm#sprintf">sprintf</A>, <A href="../Keywords/S.htm#string">string</A>, <A href="../Keywords/S.htm#substitution">substitution</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
39
hlp/en/tcl/gets.htm
Normal file
39
hlp/en/tcl/gets.htm
Normal file
@@ -0,0 +1,39 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - gets manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
gets - Read a line from a channel
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>gets </B><I>channelId</I> ?<I>varName</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command reads the next line from <I>channelId</I>, returns everything
|
||||
in the line up to (but not including) the end-of-line character(s), and
|
||||
discards the end-of-line character(s).
|
||||
If <I>varName</I> is omitted the line is returned as the result of the
|
||||
command.
|
||||
If <I>varName</I> is specified then the line is placed in the variable by
|
||||
that name and the return value is a count of the number of characters
|
||||
returned.
|
||||
<P>
|
||||
If end of file occurs while scanning for an end of
|
||||
line, the command returns whatever input is available up to the end of file.
|
||||
If <I>channelId</I> is in nonblocking mode and there is not a full
|
||||
line of input available, the command returns an empty string and
|
||||
does not consume any input.
|
||||
If <I>varName</I> is specified and an empty string is returned in
|
||||
<I>varName</I> because of end-of-file or because of insufficient
|
||||
data in nonblocking mode, then the return count is -1.
|
||||
Note that if <I>varName</I> is not specified then the end-of-file
|
||||
and no-full-line-available cases can
|
||||
produce the same results as if there were an input line consisting
|
||||
only of the end-of-line character(s).
|
||||
The <B><A HREF="../TkCmd/eof.htm">eof</A></B> and <B><A HREF="../TkCmd/fblocked.htm">fblocked</A></B> commands can be used to distinguish
|
||||
these three cases.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/eof.htm">eof</A></B>, <B><A HREF="../TkCmd/fblocked.htm">fblocked</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/E.htm#end of file">end of file</A>, <A href="../Keywords/E.htm#end of line">end of line</A>, <A href="../Keywords/L.htm#line">line</A>, <A href="../Keywords/N.htm#nonblocking">nonblocking</A>, <A href="../Keywords/R.htm#read">read</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
164
hlp/en/tcl/glob.htm
Normal file
164
hlp/en/tcl/glob.htm
Normal file
@@ -0,0 +1,164 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - glob manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="glob.htm#M2" NAME="L431">NAME</A>
|
||||
<DL><DD>glob - Return names of files that match patterns</DL>
|
||||
<DD><A HREF="glob.htm#M3" NAME="L432">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>glob </B>?<I>switches</I>? <I>pattern </I>?<I>pattern ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="glob.htm#M4" NAME="L433">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="glob.htm#M5" NAME="L434"><B>-directory</B> <I>directory</I></A>
|
||||
<DD><A HREF="glob.htm#M6" NAME="L435"><B>-join</B></A>
|
||||
<DD><A HREF="glob.htm#M7" NAME="L436"><B>-nocomplain</B></A>
|
||||
<DD><A HREF="glob.htm#M8" NAME="L437"><B>-path</B> <I>pathPrefix</I></A>
|
||||
<DD><A HREF="glob.htm#M9" NAME="L438"><B>-types</B> <I>typeList</I></A>
|
||||
<DD><A HREF="glob.htm#M10" NAME="L439"><B>- -</B></A>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="glob.htm#M11" NAME="L440"><B>?</B></A>
|
||||
<DD><A HREF="glob.htm#M12" NAME="L441"><B>*</B></A>
|
||||
<DD><A HREF="glob.htm#M13" NAME="L442"><B>[</B><I>chars</I><B>]</B></A>
|
||||
<DD><A HREF="glob.htm#M14" NAME="L443"><B>\</B><I>x</I></A>
|
||||
<DD><A HREF="glob.htm#M15" NAME="L444"><B>{</B><I>a</I><B>,</B><I>b</I><B>,</B><I>...</I>}</A>
|
||||
</DL>
|
||||
<DD><A HREF="glob.htm#M16" NAME="L445">PORTABILITY ISSUES</A>
|
||||
<DL>
|
||||
<DD><A HREF="glob.htm#M17" NAME="L446"><B>Windows</B></A>
|
||||
<DD><A HREF="glob.htm#M18" NAME="L447"><B>Macintosh</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="glob.htm#M19" NAME="L448">SEE ALSO</A>
|
||||
<DD><A HREF="glob.htm#M20" NAME="L449">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
glob - Return names of files that match patterns
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>glob </B>?<I>switches</I>? <I>pattern </I>?<I>pattern ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command performs file name ``globbing'' in a fashion similar to
|
||||
the csh shell. It returns a list of the files whose names match any
|
||||
of the <I>pattern</I> arguments.
|
||||
<P>
|
||||
If the initial arguments to <B>glob</B> start with <B>-</B> then
|
||||
they are treated as switches. The following switches are
|
||||
currently supported:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>-directory</B> <I>directory</I></A><DD>
|
||||
Search for files which match the given patterns starting in the given
|
||||
<I>directory</I>. This allows searching of directories whose name
|
||||
contains glob-sensitive characters without the need to quote such
|
||||
characters explicitly. This option may not be used in conjunction with
|
||||
<B>-path</B>.
|
||||
<P><DT><A NAME="M6"><B>-join</B></A><DD>
|
||||
The remaining pattern arguments are treated as a single pattern
|
||||
obtained by joining the arguments with directory separators.
|
||||
<P><DT><A NAME="M7"><B>-nocomplain</B></A><DD>
|
||||
Allows an empty list to be returned without error; without this
|
||||
switch an error is returned if the result list would be empty.
|
||||
<P><DT><A NAME="M8"><B>-path</B> <I>pathPrefix</I></A><DD>
|
||||
Search for files with the given <I>pathPrefix</I> where the rest of the name
|
||||
matches the given patterns. This allows searching for files with names
|
||||
similar to a given file even when the names contain glob-sensitive
|
||||
characters. This option may not be used in conjunction with
|
||||
<B>-directory</B>.
|
||||
<P><DT><A NAME="M9"><B>-types</B> <I>typeList</I></A><DD>
|
||||
Only list files or directories which match <I>typeList</I>, where the items
|
||||
in the list have two forms. The first form is like the -type option of
|
||||
the Unix find command:
|
||||
<I>b</I> (block special file),
|
||||
<I>c</I> (character special file),
|
||||
<I>d</I> (directory),
|
||||
<I>f</I> (plain file),
|
||||
<I>l</I> (symbolic link),
|
||||
<I>p</I> (named pipe),
|
||||
or <I>s</I> (socket), where multiple types may be specified in the list.
|
||||
<B>Glob</B> will return all files which match at least one of the types given.
|
||||
<P>
|
||||
The second form specifies types where all the types given must match.
|
||||
These are <I>r</I>, <I>w</I>, <I>x</I> as file permissions, and
|
||||
<I>readonly</I>, <I>hidden</I> as special permission cases. On the
|
||||
Macintosh, MacOS types and creators are also supported, where any item
|
||||
which is four characters long is assumed to be a MacOS type
|
||||
(e.g. <B><A HREF="../TclCmd/text.htm">TEXT</A></B>). Items which are of the form <I>{macintosh type XXXX}</I>
|
||||
or <I>{macintosh creator XXXX}</I> will match types or creators
|
||||
respectively. Unrecognised types, or specifications of multiple MacOS
|
||||
types/creators will signal an error.
|
||||
<P>
|
||||
The two forms may be mixed, so <B>-types {d f r w}</B> will find all
|
||||
regular files OR directories that have both read AND write permissions.
|
||||
The following are equivalent:
|
||||
<PRE><B>glob -type d *</B>
|
||||
<B>glob */</B></PRE>
|
||||
except that the first case doesn't return the trailing ``/'' and
|
||||
is more platform independent.
|
||||
<P><DT><A NAME="M10"><B>- -</B></A><DD>
|
||||
Marks the end of switches. The argument following this one will
|
||||
be treated as a <I>pattern</I> even if it starts with a <B>-</B>.
|
||||
<P></DL>
|
||||
<P>
|
||||
The <I>pattern</I> arguments may contain any of the following
|
||||
special characters:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M11"><B>?</B></A><DD>
|
||||
Matches any single character.
|
||||
<P><DT><A NAME="M12"><B>*</B></A><DD>
|
||||
Matches any sequence of zero or more characters.
|
||||
<P><DT><A NAME="M13"><B>[</B><I>chars</I><B>]</B></A><DD>
|
||||
Matches any single character in <I>chars</I>. If <I>chars</I>
|
||||
contains a sequence of the form <I>a</I><B>-</B><I>b</I> then any
|
||||
character between <I>a</I> and <I>b</I> (inclusive) will match.
|
||||
<P><DT><A NAME="M14"><B>\</B><I>x</I></A><DD>
|
||||
Matches the character <I>x</I>.
|
||||
<P><DT><A NAME="M15"><B>{</B><I>a</I><B>,</B><I>b</I><B>,</B><I>...</I>}</A><DD>
|
||||
Matches any of the strings <I>a</I>, <I>b</I>, etc.
|
||||
<P></DL>
|
||||
<P>
|
||||
As with csh, a ``.'' at the beginning of a file's name or just
|
||||
after a ``/'' must be matched explicitly or with a {} construct.
|
||||
In addition, all ``/'' characters must be matched explicitly.
|
||||
<P>
|
||||
If the first character in a <I>pattern</I> is ``~'' then it refers
|
||||
to the home directory for the user whose name follows the ``~''.
|
||||
If the ``~'' is followed immediately by ``/'' then the value of
|
||||
the HOME environment variable is used.
|
||||
<P>
|
||||
The <B>glob</B> command differs from csh globbing in two ways.
|
||||
First, it does not sort its result list (use the <B><A HREF="../TkCmd/lsort.htm">lsort</A></B>
|
||||
command if you want the list sorted).
|
||||
Second, <B>glob</B> only returns the names of files that actually
|
||||
exist; in csh no check for existence is made unless a pattern
|
||||
contains a ?, *, or [] construct.
|
||||
|
||||
<H3><A NAME="M16">PORTABILITY ISSUES</A></H3>
|
||||
Unlike other Tcl commands that will accept both network and native
|
||||
style names (see the <B><A HREF="../TkCmd/filename.htm">filename</A></B> manual entry for details on how
|
||||
native and network names are specified), the <B>glob</B> command only
|
||||
accepts native names.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M17"><B>Windows</B></A><DD>
|
||||
For Windows UNC names, the servername and sharename components of the path
|
||||
may not contain ?, *, or [] constructs. On Windows NT, if <I>pattern</I> is
|
||||
of the form ``<B>~</B><I>username</I><B>@</B><I>domain</I>'' it refers to the home
|
||||
directory of the user whose account information resides on the specified NT
|
||||
domain server. Otherwise, user account information is obtained from
|
||||
the local computer. On Windows 95 and 98, <B>glob</B> accepts patterns
|
||||
like ``.../'' and ``..../'' for successively higher up parent directories.
|
||||
<P><DT><A NAME="M18"><B>Macintosh</B></A><DD>
|
||||
When using the options, <B>-dir</B>, <B>-join</B> or <B>-path</B>, glob
|
||||
assumes the directory separator for the entire pattern is the standard
|
||||
``:''. When not using these options, glob examines each pattern argument
|
||||
and uses ``/'' unless the pattern contains a ``:''.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M19">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>
|
||||
<H3><A NAME="M20">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#exist">exist</A>, <A href="../Keywords/F.htm#file">file</A>, <A href="../Keywords/G.htm#glob">glob</A>, <A href="../Keywords/P.htm#pattern">pattern</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
28
hlp/en/tcl/global.htm
Normal file
28
hlp/en/tcl/global.htm
Normal file
@@ -0,0 +1,28 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - global manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
global - Access global variables
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>global </B><I>varname </I>?<I>varname ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command is ignored unless a Tcl procedure is being interpreted.
|
||||
If so then it declares the given <I>varname</I>'s to be global variables
|
||||
rather than local ones.
|
||||
Global variables are variables in the global namespace.
|
||||
For the duration of the current procedure
|
||||
(and only while executing in the current procedure),
|
||||
any reference to any of the <I>varname</I>s
|
||||
will refer to the global variable by the same name.
|
||||
<P>
|
||||
Please note that this is done by creating local variables that are
|
||||
linked to the global variables, and therefore that these variables
|
||||
will be listed by <B><A HREF="../TkCmd/info.htm">info locals</A></B> like all other local variables.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/namespace.htm">namespace</A></B>, <B><A HREF="../TkCmd/upvar.htm">upvar</A></B>, <B><A HREF="../TkCmd/variable.htm">variable</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/G.htm#global">global</A>, <A href="../Keywords/N.htm#namespace">namespace</A>, <A href="../Keywords/P.htm#procedure">procedure</A>, <A href="../Keywords/V.htm#variable">variable</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
114
hlp/en/tcl/history.htm
Normal file
114
hlp/en/tcl/history.htm
Normal file
@@ -0,0 +1,114 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - history manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="history.htm#M2" NAME="L455">NAME</A>
|
||||
<DL><DD>history - Manipulate the history list</DL>
|
||||
<DD><A HREF="history.htm#M3" NAME="L456">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>history </B>?<I>option</I>? ?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="history.htm#M4" NAME="L457">DESCRIPTION</A>
|
||||
<DL>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="history.htm#M5" NAME="L458"><B>history</B></A>
|
||||
<DD><A HREF="history.htm#M6" NAME="L459"><B>history add</B><I> command </I>?<B>exec</B>?</A>
|
||||
<DD><A HREF="history.htm#M7" NAME="L460"><B>history change</B><I> newValue</I> ?<I>event</I>?</A>
|
||||
<DD><A HREF="history.htm#M8" NAME="L461"><B>history clear</B></A>
|
||||
<DD><A HREF="history.htm#M9" NAME="L462"><B>history event</B> ?<I>event</I>?</A>
|
||||
<DD><A HREF="history.htm#M10" NAME="L463"><B>history info </B>?<I>count</I>?</A>
|
||||
<DD><A HREF="history.htm#M11" NAME="L464"><B>history keep </B>?<I>count</I>?</A>
|
||||
<DD><A HREF="history.htm#M12" NAME="L465"><B>history nextid</B></A>
|
||||
<DD><A HREF="history.htm#M13" NAME="L466"><B>history redo </B>?<I>event</I>?</A>
|
||||
</DL>
|
||||
<DD><A HREF="history.htm#M14" NAME="L467">HISTORY REVISION</A>
|
||||
<DD><A HREF="history.htm#M15" NAME="L468">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
history - Manipulate the history list
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>history </B>?<I>option</I>? ?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>history</B> command performs one of several operations related to
|
||||
recently-executed commands recorded in a history list. Each of
|
||||
these recorded commands is referred to as an ``<A HREF="../TclCmd/event.htm">event</A>''. When
|
||||
specifying an event to the <B>history</B> command, the following
|
||||
forms may be used:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT>[1]<DD>
|
||||
A number: if positive, it refers to the event with
|
||||
that number (all events are numbered starting at 1). If the number
|
||||
is negative, it selects an event relative to the current event
|
||||
(<B>-1</B> refers to the previous event, <B>-2</B> to the one before that, and
|
||||
so on). Event <B>0</B> refers to the current event.
|
||||
<P><DT>[2]<DD>
|
||||
A string: selects the most recent event that matches the string.
|
||||
An event is considered to match the string either if the string is
|
||||
the same as the first characters of the event, or if the string
|
||||
matches the event in the sense of the <B><A HREF="../TkCmd/string.htm">string match</A></B> command.
|
||||
<P></DL>
|
||||
<P>
|
||||
The <B>history</B> command can take any of the following forms:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>history</B></A><DD>
|
||||
Same
|
||||
as <B>history info</B>, described below.
|
||||
<P><DT><A NAME="M6"><B>history add</B><I> command </I>?<B>exec</B>?</A><DD>
|
||||
Adds the <I>command</I> argument to the history list as a new event. If
|
||||
<B>exec</B> is specified (or abbreviated) then the command is also
|
||||
executed and its result is returned. If <B>exec</B> isn't specified
|
||||
then an empty string is returned as result.
|
||||
<P><DT><A NAME="M7"><B>history change</B><I> newValue</I> ?<I>event</I>?</A><DD>
|
||||
Replaces the value recorded for an event with <I>newValue</I>. <I>Event</I>
|
||||
specifies the event to replace, and
|
||||
defaults to the <I>current</I> event (not event <B>-1</B>). This command
|
||||
is intended for use in commands that implement new forms of history
|
||||
substitution and wish to replace the current event (which invokes the
|
||||
substitution) with the command created through substitution. The return
|
||||
value is an empty string.
|
||||
<P><DT><A NAME="M8"><B>history clear</B></A><DD>
|
||||
Erase the history list. The current keep limit is retained.
|
||||
The history event numbers are reset.
|
||||
<P><DT><A NAME="M9"><B>history event</B> ?<I>event</I>?</A><DD>
|
||||
Returns the value of the event given by <I>event</I>. <I>Event</I>
|
||||
defaults to <B>-1</B>.
|
||||
<P><DT><A NAME="M10"><B>history info </B>?<I>count</I>?</A><DD>
|
||||
Returns a formatted string (intended for humans to read) giving
|
||||
the event number and contents for each of the events in the history
|
||||
list except the current event. If <I>count</I> is specified
|
||||
then only the most recent <I>count</I> events are returned.
|
||||
<P><DT><A NAME="M11"><B>history keep </B>?<I>count</I>?</A><DD>
|
||||
This command may be used to change the size of the history list to
|
||||
<I>count</I> events. Initially, 20 events are retained in the history
|
||||
list. If <I>count</I> is not specified, the current keep limit is returned.
|
||||
<P><DT><A NAME="M12"><B>history nextid</B></A><DD>
|
||||
Returns the number of the next event to be recorded
|
||||
in the history list. It is useful for things like printing the
|
||||
event number in command-line prompts.
|
||||
<P><DT><A NAME="M13"><B>history redo </B>?<I>event</I>?</A><DD>
|
||||
Re-executes the command indicated by <I>event</I> and return its result.
|
||||
<I>Event</I> defaults to <B>-1</B>. This command results in history
|
||||
revision: see below for details.
|
||||
<P></DL>
|
||||
<H3><A NAME="M14">HISTORY REVISION</A></H3>
|
||||
Pre-8.0 Tcl had a complex history revision mechanism.
|
||||
The current mechanism is more limited, and the old
|
||||
history operations <B>substitute</B> and <B>words</B> have been removed.
|
||||
(As a consolation, the <B>clear</B> operation was added.)
|
||||
<P>
|
||||
The history option <B>redo</B> results in much simpler ``history revision''.
|
||||
When this option is invoked then the most recent event
|
||||
is modified to eliminate the history command and replace it with
|
||||
the result of the history command.
|
||||
If you want to redo an event without modifying history, then use
|
||||
the <B><A HREF="../TclCmd/event.htm">event</A></B> operation to retrieve some event,
|
||||
and the <B>add</B> operation to add it to history and execute it.
|
||||
|
||||
<H3><A NAME="M15">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#event">event</A>, <A href="../Keywords/H.htm#history">history</A>, <A href="../Keywords/R.htm#record">record</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
522
hlp/en/tcl/http.htm
Normal file
522
hlp/en/tcl/http.htm
Normal file
@@ -0,0 +1,522 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - Http manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="http.htm#M2" NAME="L469">NAME</A>
|
||||
<DL><DD>Http - Client-side implementation of the HTTP/1.0 protocol.</DL>
|
||||
<DD><A HREF="http.htm#M3" NAME="L470">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>package require http ?2.4?</B>
|
||||
<DD><B>::http::config </B><I>?options?</I>
|
||||
<DD><B>::http::geturl </B><I>url ?options?</I>
|
||||
<DD><B>::http::formatQuery </B><I>list</I>
|
||||
<DD><B>::http::reset </B><I>token</I>
|
||||
<DD><B>::http::wait </B><I>token</I>
|
||||
<DD><B>::http::status </B><I>token</I>
|
||||
<DD><B>::http::size </B><I>token</I>
|
||||
<DD><B>::http::code </B><I>token</I>
|
||||
<DD><B>::http::ncode </B><I>token</I>
|
||||
<DD><B>::http::data </B><I>token</I>
|
||||
<DD><B>::http::error </B><I>token</I>
|
||||
<DD><B>::http::cleanup </B><I>token</I>
|
||||
<DD><B>::http::register </B><I>proto port command</I>
|
||||
<DD><B>::http::unregister </B><I>proto</I>
|
||||
</DL>
|
||||
<DD><A HREF="http.htm#M4" NAME="L471">DESCRIPTION</A>
|
||||
<DD><A HREF="http.htm#M5" NAME="L472">COMMANDS</A>
|
||||
<DL>
|
||||
<DD><A HREF="http.htm#M6" NAME="L473"><B>::http::config</B> ?<I>options</I>?</A>
|
||||
<DL>
|
||||
<DD><A HREF="http.htm#M7" NAME="L474"><B>-accept</B> <I>mimetypes</I></A>
|
||||
<DD><A HREF="http.htm#M8" NAME="L475"><B>-proxyhost</B> <I>hostname</I></A>
|
||||
<DD><A HREF="http.htm#M9" NAME="L476"><B>-proxyport</B> <I>number</I></A>
|
||||
<DD><A HREF="http.htm#M10" NAME="L477"><B>-proxyfilter</B> <I>command</I></A>
|
||||
<DD><A HREF="http.htm#M11" NAME="L478"><B>-useragent</B> <I>string</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="http.htm#M12" NAME="L479"><B>::http::geturl</B> <I>url</I> ?<I>options</I>?</A>
|
||||
<DL>
|
||||
<DD><A HREF="http.htm#M13" NAME="L480"><B>-binary</B> <I>boolean</I></A>
|
||||
<DD><A HREF="http.htm#M14" NAME="L481"><B>-blocksize</B> <I>size</I></A>
|
||||
<DD><A HREF="http.htm#M15" NAME="L482"><B>-channel</B> <I>name</I></A>
|
||||
<DD><A HREF="http.htm#M16" NAME="L483"><B>-command</B> <I>callback</I></A>
|
||||
<DD><A HREF="http.htm#M17" NAME="L484"><B>-handler</B> <I>callback</I></A>
|
||||
<DD><A HREF="http.htm#M18" NAME="L485"><B>-headers</B> <I>keyvaluelist</I></A>
|
||||
<DD><A HREF="http.htm#M19" NAME="L486"><B>-progress</B> <I>callback</I></A>
|
||||
<DD><A HREF="http.htm#M20" NAME="L487"><B>-query</B> <I>query</I></A>
|
||||
<DD><A HREF="http.htm#M21" NAME="L488"><B>-queryblocksize</B> <I>size</I></A>
|
||||
<DD><A HREF="http.htm#M22" NAME="L489"><B>-querychannel</B> <I>channelID</I></A>
|
||||
<DD><A HREF="http.htm#M23" NAME="L490"><B>-queryprogress</B> <I>callback</I></A>
|
||||
<DD><A HREF="http.htm#M24" NAME="L491"><B>-timeout</B> <I>milliseconds</I></A>
|
||||
<DD><A HREF="http.htm#M25" NAME="L492"><B>-type</B> <I>mime-type</I></A>
|
||||
<DD><A HREF="http.htm#M26" NAME="L493"><B>-validate</B> <I>boolean</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="http.htm#M27" NAME="L494"><B>::http::formatQuery</B> <I>key value</I> ?<I>key value</I> ...?</A>
|
||||
<DD><A HREF="http.htm#M28" NAME="L495"><B>::http::reset</B> <I>token</I> ?<I>why</I>?</A>
|
||||
<DD><A HREF="http.htm#M29" NAME="L496"><B>::http::wait</B> <I>token</I></A>
|
||||
<DD><A HREF="http.htm#M30" NAME="L497"><B>::http::data</B> <I>token</I></A>
|
||||
<DD><A HREF="http.htm#M31" NAME="L498"><B>::http::error</B> <I>token</I></A>
|
||||
<DD><A HREF="http.htm#M32" NAME="L499"><B>::http::status</B> <I>token</I></A>
|
||||
<DD><A HREF="http.htm#M33" NAME="L500"><B>::http::code</B> <I>token</I></A>
|
||||
<DD><A HREF="http.htm#M34" NAME="L501"><B>::http::ncode</B> <I>token</I></A>
|
||||
<DD><A HREF="http.htm#M35" NAME="L502"><B>::http::size</B> <I>token</I></A>
|
||||
<DD><A HREF="http.htm#M36" NAME="L503"><B>::http::cleanup</B> <I>token</I></A>
|
||||
<DD><A HREF="http.htm#M37" NAME="L504"><B>::http::register</B> <I>proto port command</I></A>
|
||||
<DD><A HREF="http.htm#M38" NAME="L505"><B>::http::unregister</B> <I>proto</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="http.htm#M39" NAME="L506">ERRORS</A>
|
||||
<DL>
|
||||
<DD><A HREF="http.htm#M40" NAME="L507">ok</A>
|
||||
<DD><A HREF="http.htm#M41" NAME="L508">eof</A>
|
||||
<DD><A HREF="http.htm#M42" NAME="L509">error</A>
|
||||
</DL>
|
||||
<DD><A HREF="http.htm#M43" NAME="L510">STATE ARRAY</A>
|
||||
<DL>
|
||||
<DD><A HREF="http.htm#M44" NAME="L511"><B>body</B></A>
|
||||
<DD><A HREF="http.htm#M45" NAME="L512"><B>charset</B></A>
|
||||
<DD><A HREF="http.htm#M46" NAME="L513"><B>coding</B></A>
|
||||
<DD><A HREF="http.htm#M47" NAME="L514"><B>currentsize</B></A>
|
||||
<DD><A HREF="http.htm#M48" NAME="L515"><B>error</B></A>
|
||||
<DD><A HREF="http.htm#M49" NAME="L516"><B>http</B></A>
|
||||
<DD><A HREF="http.htm#M50" NAME="L517"><B>meta</B></A>
|
||||
<DL>
|
||||
<DD><A HREF="http.htm#M51" NAME="L518"><B>Content-Type</B></A>
|
||||
<DD><A HREF="http.htm#M52" NAME="L519"><B>Content-Length</B></A>
|
||||
<DD><A HREF="http.htm#M53" NAME="L520"><B>Location</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="http.htm#M54" NAME="L521"><B>posterror</B></A>
|
||||
<DD><A HREF="http.htm#M55" NAME="L522"><B>status</B></A>
|
||||
<DD><A HREF="http.htm#M56" NAME="L523"><B>totalsize</B></A>
|
||||
<DD><A HREF="http.htm#M57" NAME="L524"><B>type</B></A>
|
||||
<DD><A HREF="http.htm#M58" NAME="L525"><B>url</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="http.htm#M59" NAME="L526">EXAMPLE</A>
|
||||
<DD><A HREF="http.htm#M60" NAME="L527">SEE ALSO</A>
|
||||
<DD><A HREF="http.htm#M61" NAME="L528">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
Http - Client-side implementation of the HTTP/1.0 protocol.
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>package require http ?2.4?</B><BR>
|
||||
<B>::http::config </B><I>?options?</I><BR>
|
||||
<B>::http::geturl </B><I>url ?options?</I><BR>
|
||||
<B>::http::formatQuery </B><I>list</I><BR>
|
||||
<B>::http::reset </B><I>token</I><BR>
|
||||
<B>::http::wait </B><I>token</I><BR>
|
||||
<B>::http::status </B><I>token</I><BR>
|
||||
<B>::http::size </B><I>token</I><BR>
|
||||
<B>::http::code </B><I>token</I><BR>
|
||||
<B>::http::ncode </B><I>token</I><BR>
|
||||
<B>::http::data </B><I>token</I><BR>
|
||||
<B>::http::error </B><I>token</I><BR>
|
||||
<B>::http::cleanup </B><I>token</I><BR>
|
||||
<B>::http::register </B><I>proto port command</I><BR>
|
||||
<B>::http::unregister </B><I>proto</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>http</B> package provides the client side of the HTTP/1.0
|
||||
protocol. The package implements the GET, POST, and HEAD operations
|
||||
of HTTP/1.0. It allows configuration of a proxy host to get through
|
||||
firewalls. The package is compatible with the <B>Safesock</B> security
|
||||
policy, so it can be used by untrusted applets to do URL fetching from
|
||||
a restricted set of hosts. This package can be extened to support
|
||||
additional HTTP transport protocols, such as HTTPS, by providing
|
||||
a custom <B><A HREF="../TkCmd/socket.htm">socket</A></B> command, via <B>http::register</B>.
|
||||
<P>
|
||||
The <B>::http::geturl</B> procedure does a HTTP transaction.
|
||||
Its <I>options </I> determine whether a GET, POST, or HEAD transaction
|
||||
is performed.
|
||||
The return value of <B>::http::geturl</B> is a token for the transaction.
|
||||
The value is also the name of an array in the ::http namespace
|
||||
that contains state information about the transaction. The elements
|
||||
of this array are described in the STATE ARRAY section.
|
||||
<P>
|
||||
If the <B>-command</B> option is specified, then
|
||||
the HTTP operation is done in the background.
|
||||
<B>::http::geturl</B> returns immediately after generating the
|
||||
HTTP request and the callback is invoked
|
||||
when the transaction completes. For this to work, the Tcl event loop
|
||||
must be active. In Tk applications this is always true. For pure-Tcl
|
||||
applications, the caller can use <B>::http::wait</B> after calling
|
||||
<B>::http::geturl</B> to start the event loop.
|
||||
<H3><A NAME="M5">COMMANDS</A></H3>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>::http::config</B> ?<I>options</I>?</A><DD>
|
||||
The <B>::http::config</B> command is used to set and query the name of the
|
||||
proxy server and port, and the User-Agent name used in the HTTP
|
||||
requests. If no options are specified, then the current configuration
|
||||
is returned. If a single argument is specified, then it should be one
|
||||
of the flags described below. In this case the current value of
|
||||
that setting is returned. Otherwise, the options should be a set of
|
||||
flags and values that define the configuration:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M7"><B>-accept</B> <I>mimetypes</I></A><DD>
|
||||
The Accept header of the request. The default is */*, which means that
|
||||
all types of documents are accepted. Otherwise you can supply a
|
||||
comma separated list of mime type patterns that you are
|
||||
willing to receive. For example, "image/gif, image/jpeg, text/*".
|
||||
<P><DT><A NAME="M8"><B>-proxyhost</B> <I>hostname</I></A><DD>
|
||||
The name of the proxy host, if any. If this value is the
|
||||
empty string, the URL host is contacted directly.
|
||||
<P><DT><A NAME="M9"><B>-proxyport</B> <I>number</I></A><DD>
|
||||
The proxy port number.
|
||||
<P><DT><A NAME="M10"><B>-proxyfilter</B> <I>command</I></A><DD>
|
||||
The command is a callback that is made during
|
||||
<B>::http::geturl</B>
|
||||
to determine if a proxy is required for a given host. One argument, a
|
||||
host name, is added to <I>command</I> when it is invoked. If a proxy
|
||||
is required, the callback should return a two element list containing
|
||||
the proxy server and proxy port. Otherwise the filter should return
|
||||
an empty list. The default filter returns the values of the
|
||||
<B>-proxyhost</B> and <B>-proxyport</B> settings if they are
|
||||
non-empty.
|
||||
<P><DT><A NAME="M11"><B>-useragent</B> <I>string</I></A><DD>
|
||||
The value of the User-Agent header in the HTTP request. The default
|
||||
is <B>"Tcl http client package 2.2."</B>
|
||||
<P></DL>
|
||||
<P><DT><A NAME="M12"><B>::http::geturl</B> <I>url</I> ?<I>options</I>?</A><DD>
|
||||
The <B>::http::geturl</B> command is the main procedure in the package.
|
||||
The <B>-query</B> option causes a POST operation and
|
||||
the <B>-validate</B> option causes a HEAD operation;
|
||||
otherwise, a GET operation is performed. The <B>::http::geturl</B> command
|
||||
returns a <I>token</I> value that can be used to get
|
||||
information about the transaction. See the STATE ARRAY and ERRORS section for
|
||||
details. The <B>::http::geturl</B> command blocks until the operation
|
||||
completes, unless the <B>-command</B> option specifies a callback
|
||||
that is invoked when the HTTP transaction completes.
|
||||
<B>::http::geturl</B> takes several options:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M13"><B>-binary</B> <I>boolean</I></A><DD>
|
||||
Specifies whether to force interpreting the url data as binary. Normally
|
||||
this is auto-detected (anything not beginning with a <B><A HREF="../TclCmd/text.htm">text</A></B> content
|
||||
type or whose content encoding is <B>gzip</B> or <B>compress</B> is
|
||||
considered binary data).
|
||||
<P><DT><A NAME="M14"><B>-blocksize</B> <I>size</I></A><DD>
|
||||
The blocksize used when reading the URL.
|
||||
At most <I>size</I> bytes are read at once. After each block, a call to the
|
||||
<B>-progress</B> callback is made (if that option is specified).
|
||||
<P><DT><A NAME="M15"><B>-channel</B> <I>name</I></A><DD>
|
||||
Copy the URL contents to channel <I>name</I> instead of saving it in
|
||||
<B>state(body)</B>.
|
||||
<P><DT><A NAME="M16"><B>-command</B> <I>callback</I></A><DD>
|
||||
Invoke <I>callback</I> after the HTTP transaction completes.
|
||||
This option causes <B>::http::geturl</B> to return immediately.
|
||||
The <I>callback</I> gets an additional argument that is the <I>token</I> returned
|
||||
from <B>::http::geturl</B>. This token is the name of an array that is
|
||||
described in the STATE ARRAY section. Here is a template for the
|
||||
callback:
|
||||
<PRE>proc httpCallback {token} {
|
||||
upvar #0 $token state
|
||||
# Access state as a Tcl array
|
||||
}</PRE>
|
||||
<P><DT><A NAME="M17"><B>-handler</B> <I>callback</I></A><DD>
|
||||
Invoke <I>callback</I> whenever HTTP data is available; if present, nothing
|
||||
else will be done with the HTTP data. This procedure gets two additional
|
||||
arguments: the socket for the HTTP data and the <I>token</I> returned from
|
||||
<B>::http::geturl</B>. The token is the name of a global array that is described
|
||||
in the STATE ARRAY section. The procedure is expected to return the number
|
||||
of bytes read from the socket. Here is a template for the callback:
|
||||
<PRE>proc httpHandlerCallback {socket token} {
|
||||
upvar #0 $token state
|
||||
# Access socket, and state as a Tcl array
|
||||
...
|
||||
(example: set data [read $socket 1000];set nbytes [string length $data])
|
||||
...
|
||||
return nbytes
|
||||
}</PRE>
|
||||
<P><DT><A NAME="M18"><B>-headers</B> <I>keyvaluelist</I></A><DD>
|
||||
This option is used to add extra headers to the HTTP request. The
|
||||
<I>keyvaluelist</I> argument must be a list with an even number of
|
||||
elements that alternate between keys and values. The keys become
|
||||
header field names. Newlines are stripped from the values so the
|
||||
header cannot be corrupted. For example, if <I>keyvaluelist</I> is
|
||||
<B>Pragma no-cache</B> then the following header is included in the
|
||||
HTTP request:
|
||||
<PRE>Pragma: no-cache</PRE>
|
||||
<P><DT><A NAME="M19"><B>-progress</B> <I>callback</I></A><DD>
|
||||
The <I>callback</I> is made after each transfer of data from the URL.
|
||||
The callback gets three additional arguments: the <I>token</I> from
|
||||
<B>::http::geturl</B>, the expected total size of the contents from the
|
||||
<B>Content-Length</B> meta-data, and the current number of bytes
|
||||
transferred so far. The expected total size may be unknown, in which
|
||||
case zero is passed to the callback. Here is a template for the
|
||||
progress callback:
|
||||
<PRE>proc httpProgress {token total current} {
|
||||
upvar #0 $token state
|
||||
}</PRE>
|
||||
<P><DT><A NAME="M20"><B>-query</B> <I>query</I></A><DD>
|
||||
This flag causes <B>::http::geturl</B> to do a POST request that passes the
|
||||
<I>query</I> to the server. The <I>query</I> must be a x-url-encoding
|
||||
formatted query. The <B>::http::formatQuery</B> procedure can be used to
|
||||
do the formatting.
|
||||
<P><DT><A NAME="M21"><B>-queryblocksize</B> <I>size</I></A><DD>
|
||||
The blocksize used when posting query data to the URL.
|
||||
At most
|
||||
<I>size</I>
|
||||
bytes are written at once. After each block, a call to the
|
||||
<B>-queryprogress</B>
|
||||
callback is made (if that option is specified).
|
||||
<P><DT><A NAME="M22"><B>-querychannel</B> <I>channelID</I></A><DD>
|
||||
This flag causes <B>::http::geturl</B> to do a POST request that passes the
|
||||
data contained in <I>channelID</I> to the server. The data contained in <I>channelID</I> must be a x-url-encoding
|
||||
formatted query unless the <B>-type</B> option below is used.
|
||||
If a Content-Length header is not specified via the <B>-headers</B> options,
|
||||
<B>::http::geturl</B> attempts to determine the size of the post data
|
||||
in order to create that header. If it is
|
||||
unable to determine the size, it returns an error.
|
||||
<P><DT><A NAME="M23"><B>-queryprogress</B> <I>callback</I></A><DD>
|
||||
The <I>callback</I> is made after each transfer of data to the URL
|
||||
(i.e. POST) and acts exactly like the <B>-progress</B> option (the
|
||||
callback format is the same).
|
||||
<P><DT><A NAME="M24"><B>-timeout</B> <I>milliseconds</I></A><DD>
|
||||
If <I>milliseconds</I> is non-zero, then <B>::http::geturl</B> sets up a timeout
|
||||
to occur after the specified number of milliseconds.
|
||||
A timeout results in a call to <B>::http::reset</B> and to
|
||||
the <B>-command</B> callback, if specified.
|
||||
The return value of <B>::http::status</B> is <B>timeout</B>
|
||||
after a timeout has occurred.
|
||||
<P><DT><A NAME="M25"><B>-type</B> <I>mime-type</I></A><DD>
|
||||
Use <I>mime-type</I> as the <B>Content-Type</B> value, instead of the
|
||||
default value (<B>application/x-www-form-urlencoded</B>) during a
|
||||
POST operation.
|
||||
<P><DT><A NAME="M26"><B>-validate</B> <I>boolean</I></A><DD>
|
||||
If <I>boolean</I> is non-zero, then <B>::http::geturl</B> does an HTTP HEAD
|
||||
request. This request returns meta information about the URL, but the
|
||||
contents are not returned. The meta information is available in the
|
||||
<B>state(meta) </B> variable after the transaction. See the STATE
|
||||
ARRAY section for details.
|
||||
<P></DL>
|
||||
<P><DT><A NAME="M27"><B>::http::formatQuery</B> <I>key value</I> ?<I>key value</I> ...?</A><DD>
|
||||
This procedure does x-url-encoding of query data. It takes an even
|
||||
number of arguments that are the keys and values of the query. It
|
||||
encodes the keys and values, and generates one string that has the
|
||||
proper & and = separators. The result is suitable for the
|
||||
<B>-query</B> value passed to <B>::http::geturl</B>.
|
||||
<P><DT><A NAME="M28"><B>::http::reset</B> <I>token</I> ?<I>why</I>?</A><DD>
|
||||
This command resets the HTTP transaction identified by <I>token</I>, if
|
||||
any. This sets the <B>state(status)</B> value to <I>why</I>, which defaults to <B>reset</B>, and then calls the registered <B>-command</B> callback.
|
||||
<P><DT><A NAME="M29"><B>::http::wait</B> <I>token</I></A><DD>
|
||||
This is a convenience procedure that blocks and waits for the
|
||||
transaction to complete. This only works in trusted code because it
|
||||
uses <B><A HREF="../TkCmd/vwait.htm">vwait</A></B>. Also, it's not useful for the case where
|
||||
<B>::http::geturl</B> is called <I>without</I> the <B>-command</B> option
|
||||
because in this case the <B>::http::geturl</B> call doesn't return
|
||||
until the HTTP transaction is complete, and thus there's nothing to
|
||||
wait for.
|
||||
<P><DT><A NAME="M30"><B>::http::data</B> <I>token</I></A><DD>
|
||||
This is a convenience procedure that returns the <B>body</B> element
|
||||
(i.e., the URL data) of the state array.
|
||||
<P><DT><A NAME="M31"><B>::http::error</B> <I>token</I></A><DD>
|
||||
This is a convenience procedure that returns the <B><A HREF="../TkCmd/error.htm">error</A></B> element
|
||||
of the state array.
|
||||
<P><DT><A NAME="M32"><B>::http::status</B> <I>token</I></A><DD>
|
||||
This is a convenience procedure that returns the <B>status</B> element of
|
||||
the state array.
|
||||
<P><DT><A NAME="M33"><B>::http::code</B> <I>token</I></A><DD>
|
||||
This is a convenience procedure that returns the <B>http</B> element of the
|
||||
state array.
|
||||
<P><DT><A NAME="M34"><B>::http::ncode</B> <I>token</I></A><DD>
|
||||
This is a convenience procedure that returns just the numeric return
|
||||
code (200, 404, etc.) from the <B>http</B> element of the state array.
|
||||
<P><DT><A NAME="M35"><B>::http::size</B> <I>token</I></A><DD>
|
||||
This is a convenience procedure that returns the <B>currentsize</B>
|
||||
element of the state array, which represents the number of bytes
|
||||
received from the URL in the <B>::http::geturl</B> call.
|
||||
<P><DT><A NAME="M36"><B>::http::cleanup</B> <I>token</I></A><DD>
|
||||
This procedure cleans up the state associated with the connection
|
||||
identified by <I>token</I>. After this call, the procedures
|
||||
like <B>::http::data</B> cannot be used to get information
|
||||
about the operation. It is <I>strongly</I> recommended that you call
|
||||
this function after you're done with a given HTTP request. Not doing
|
||||
so will result in memory not being freed, and if your app calls
|
||||
<B>::http::geturl</B> enough times, the memory leak could cause a
|
||||
performance hit...or worse.
|
||||
<P><DT><A NAME="M37"><B>::http::register</B> <I>proto port command</I></A><DD>
|
||||
This procedure allows one to provide custom HTTP transport types
|
||||
such as HTTPS, by registering a prefix, the default port, and the
|
||||
command to execute to create the Tcl <B>channel</B>. E.g.:
|
||||
<PRE>package require http
|
||||
package require tls
|
||||
|
||||
http::register https 443 ::tls::socket
|
||||
|
||||
set token [http::geturl https://my.secure.site/]</PRE>
|
||||
<P><DT><A NAME="M38"><B>::http::unregister</B> <I>proto</I></A><DD>
|
||||
This procedure unregisters a protocol handler that was previously
|
||||
registered via <B>http::register</B>.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M39">ERRORS</A></H3>
|
||||
The <B>http::geturl</B> procedure will raise errors in the following cases:
|
||||
invalid command line options,
|
||||
an invalid URL,
|
||||
a URL on a non-existent host,
|
||||
or a URL at a bad port on an existing host.
|
||||
These errors mean that it
|
||||
cannot even start the network transaction.
|
||||
It will also raise an error if it gets an I/O error while
|
||||
writing out the HTTP request header.
|
||||
For synchronous <B>::http::geturl</B> calls (where <B>-command</B> is
|
||||
not specified), it will raise an error if it gets an I/O error while
|
||||
reading the HTTP reply headers or data. Because <B>::http::geturl</B>
|
||||
doesn't return a token in these cases, it does all the required
|
||||
cleanup and there's no issue of your app having to call
|
||||
<B>::http::cleanup</B>.
|
||||
<P>
|
||||
For asynchronous <B>::http::geturl</B> calls, all of the above error
|
||||
situations apply, except that if there's any error while
|
||||
reading the
|
||||
HTTP reply headers or data, no exception is thrown. This is because
|
||||
after writing the HTTP headers, <B>::http::geturl</B> returns, and the
|
||||
rest of the HTTP transaction occurs in the background. The command
|
||||
callback can check if any error occurred during the read by calling
|
||||
<B>::http::status</B> to check the status and if it's <I>error</I>,
|
||||
calling <B>::http::error</B> to get the error message.
|
||||
<P>
|
||||
Alternatively, if the main program flow reaches a point where it needs
|
||||
to know the result of the asynchronous HTTP request, it can call
|
||||
<B>::http::wait</B> and then check status and error, just as the
|
||||
callback does.
|
||||
<P>
|
||||
In any case, you must still call
|
||||
<B>http::cleanup</B> to delete the state array when you're done.
|
||||
<P>
|
||||
There are other possible results of the HTTP transaction
|
||||
determined by examining the status from <B>http::status</B>.
|
||||
These are described below.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M40">ok</A><DD>
|
||||
If the HTTP transaction completes entirely, then status will be <B>ok</B>.
|
||||
However, you should still check the <B>http::code</B> value to get
|
||||
the HTTP status. The <B>http::ncode</B> procedure provides just
|
||||
the numeric error (e.g., 200, 404 or 500) while the <B>http::code</B>
|
||||
procedure returns a value like "HTTP 404 File not found".
|
||||
<P><DT><A NAME="M41">eof</A><DD>
|
||||
If the server closes the socket without replying, then no error
|
||||
is raised, but the status of the transaction will be <B><A HREF="../TkCmd/eof.htm">eof</A></B>.
|
||||
<P><DT><A NAME="M42">error</A><DD>
|
||||
The error message will also be stored in the <B><A HREF="../TkCmd/error.htm">error</A></B> status
|
||||
array element, accessible via <B>::http::error</B>.
|
||||
<P></DL>
|
||||
<P>
|
||||
Another error possibility is that <B>http::geturl</B> is unable to
|
||||
write all the post query data to the server before the server
|
||||
responds and closes the socket.
|
||||
The error message is saved in the <B>posterror</B> status array
|
||||
element and then <B>http::geturl</B> attempts to complete the
|
||||
transaction.
|
||||
If it can read the server's response
|
||||
it will end up with an <B>ok</B> status, otherwise it will have
|
||||
an <B><A HREF="../TkCmd/eof.htm">eof</A></B> status.
|
||||
|
||||
<H3><A NAME="M43">STATE ARRAY</A></H3>
|
||||
The <B>::http::geturl</B> procedure returns a <I>token</I> that can be used to
|
||||
get to the state of the HTTP transaction in the form of a Tcl array.
|
||||
Use this construct to create an easy-to-use array variable:
|
||||
<PRE>upvar #0 $token state</PRE>
|
||||
Once the data associated with the url is no longer needed, the state
|
||||
array should be unset to free up storage.
|
||||
The <B>http::cleanup</B> procedure is provided for that purpose.
|
||||
The following elements of
|
||||
the array are supported:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M44"><B>body</B></A><DD>
|
||||
The contents of the URL. This will be empty if the <B>-channel</B>
|
||||
option has been specified. This value is returned by the <B>::http::data</B> command.
|
||||
<P><DT><A NAME="M45"><B>charset</B></A><DD>
|
||||
The value of the charset attribute from the <B>Content-Type</B> meta-data
|
||||
value. If none was specified, this defaults to the RFC standard
|
||||
<B>iso8859-1</B>, or the value of <B>$::http::defaultCharset</B>. Incoming
|
||||
text data will be automatically converted from this charset to utf-8.
|
||||
<P><DT><A NAME="M46"><B>coding</B></A><DD>
|
||||
A copy of the <B>Content-Encoding</B> meta-data value.
|
||||
<P><DT><A NAME="M47"><B>currentsize</B></A><DD>
|
||||
The current number of bytes fetched from the URL.
|
||||
This value is returned by the <B>::http::size</B> command.
|
||||
<P><DT><A NAME="M48"><B>error</B></A><DD>
|
||||
If defined, this is the error string seen when the HTTP transaction
|
||||
was aborted.
|
||||
<P><DT><A NAME="M49"><B>http</B></A><DD>
|
||||
The HTTP status reply from the server. This value
|
||||
is returned by the <B>::http::code</B> command. The format of this value is:
|
||||
<PRE><I>HTTP/1.0 code string</I></PRE>
|
||||
The <I>code</I> is a three-digit number defined in the HTTP standard.
|
||||
A code of 200 is OK. Codes beginning with 4 or 5 indicate errors.
|
||||
Codes beginning with 3 are redirection errors. In this case the
|
||||
<B>Location</B> meta-data specifies a new URL that contains the
|
||||
requested information.
|
||||
<P><DT><A NAME="M50"><B>meta</B></A><DD>
|
||||
The HTTP protocol returns meta-data that describes the URL contents.
|
||||
The <B>meta</B> element of the state array is a list of the keys and
|
||||
values of the meta-data. This is in a format useful for initializing
|
||||
an array that just contains the meta-data:
|
||||
<PRE>array set meta $state(meta)</PRE>
|
||||
Some of the meta-data keys are listed below, but the HTTP standard defines
|
||||
more, and servers are free to add their own.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M51"><B>Content-Type</B></A><DD>
|
||||
The type of the URL contents. Examples include <B>text/html</B>,
|
||||
<B>image/gif,</B> <B>application/postscript</B> and
|
||||
<B>application/x-tcl</B>.
|
||||
<P><DT><A NAME="M52"><B>Content-Length</B></A><DD>
|
||||
The advertised size of the contents. The actual size obtained by
|
||||
<B>::http::geturl</B> is available as <B>state(size)</B>.
|
||||
<P><DT><A NAME="M53"><B>Location</B></A><DD>
|
||||
An alternate URL that contains the requested data.
|
||||
<P></DL>
|
||||
<P><DT><A NAME="M54"><B>posterror</B></A><DD>
|
||||
The error, if any, that occurred while writing
|
||||
the post query data to the server.
|
||||
<P><DT><A NAME="M55"><B>status</B></A><DD>
|
||||
Either <B>ok</B>, for successful completion, <B>reset</B> for
|
||||
user-reset, <B>timeout</B> if a timeout occurred before the transaction
|
||||
could complete, or <B><A HREF="../TkCmd/error.htm">error</A></B> for an error condition. During the
|
||||
transaction this value is the empty string.
|
||||
<P><DT><A NAME="M56"><B>totalsize</B></A><DD>
|
||||
A copy of the <B>Content-Length</B> meta-data value.
|
||||
<P><DT><A NAME="M57"><B>type</B></A><DD>
|
||||
A copy of the <B>Content-Type</B> meta-data value.
|
||||
<P><DT><A NAME="M58"><B>url</B></A><DD>
|
||||
The requested URL.
|
||||
<P></DL>
|
||||
<H3><A NAME="M59">EXAMPLE</A></H3>
|
||||
<PRE># Copy a URL to a file and print meta-data
|
||||
proc ::http::copy { url file {chunk 4096} } {
|
||||
set out [open $file w]
|
||||
set token [geturl $url -channel $out -progress ::http::Progress \
|
||||
-blocksize $chunk]
|
||||
close $out
|
||||
# This ends the line started by http::Progress
|
||||
puts stderr ""
|
||||
upvar #0 $token state
|
||||
set max 0
|
||||
foreach {name value} $state(meta) {
|
||||
if {[string length $name] > $max} {
|
||||
set max [string length $name]
|
||||
}
|
||||
if {[regexp -nocase ^location$ $name]} {
|
||||
# Handle URL redirects
|
||||
puts stderr "Location:$value"
|
||||
return [copy [string trim $value] $file $chunk]
|
||||
}
|
||||
}
|
||||
incr max
|
||||
foreach {name value} $state(meta) {
|
||||
puts [format "%-*s %s" $max $name: $value]
|
||||
}
|
||||
|
||||
return $token
|
||||
}
|
||||
proc ::http::Progress {args} {
|
||||
puts -nonewline stderr . ; flush stderr
|
||||
}</PRE>
|
||||
<H3><A NAME="M60">SEE ALSO</A></H3>
|
||||
<B>safe</B>, <B><A HREF="../TkCmd/socket.htm">socket</A></B>, <B>safesock</B>
|
||||
<H3><A NAME="M61">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/S.htm#security policy">security policy</A>, <A href="../Keywords/S.htm#socket">socket</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1998-2000 by Ajuba Solutions.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
35
hlp/en/tcl/if.htm
Normal file
35
hlp/en/tcl/if.htm
Normal file
@@ -0,0 +1,35 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - if manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
if - Execute scripts conditionally
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>if </B><I>expr1 </I>?<B>then</B>? <I>body1 </I><B>elseif </B><I>expr2 </I>?<B>then</B>? <I>body2</I> <B>elseif</B> ... ?<B>else</B>? ?<I>bodyN</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <I>if</I> command evaluates <I>expr1</I> as an expression (in the
|
||||
same way that <B><A HREF="../TkCmd/expr.htm">expr</A></B> evaluates its argument). The value of the
|
||||
expression must be a boolean
|
||||
(a numeric value, where 0 is false and
|
||||
anything is true, or a string value such as <B>true</B> or <B>yes</B>
|
||||
for true and <B>false</B> or <B>no</B> for false);
|
||||
if it is true then <I>body1</I> is executed by passing it to the
|
||||
Tcl interpreter.
|
||||
Otherwise <I>expr2</I> is evaluated as an expression and if it is true
|
||||
then <B>body2</B> is executed, and so on.
|
||||
If none of the expressions evaluates to true then <I>bodyN</I> is
|
||||
executed.
|
||||
The <B>then</B> and <B>else</B> arguments are optional
|
||||
``noise words'' to make the command easier to read.
|
||||
There may be any number of <B>elseif</B> clauses, including zero.
|
||||
<I>BodyN</I> may also be omitted as long as <B>else</B> is omitted too.
|
||||
The return value from the command is the result of the body script
|
||||
that was executed, or an empty string
|
||||
if none of the expressions was non-zero and there was no <I>bodyN</I>.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/expr.htm">expr</A></B>, <B><A HREF="../TkCmd/for.htm">for</A></B>, <B><A HREF="../TkCmd/foreach.htm">foreach</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#boolean">boolean</A>, <A href="../Keywords/C.htm#conditional">conditional</A>, <A href="../Keywords/E.htm#else">else</A>, <A href="../Keywords/F.htm#false">false</A>, <A href="../Keywords/I.htm#if">if</A>, <A href="../Keywords/T.htm#true">true</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
23
hlp/en/tcl/incr.htm
Normal file
23
hlp/en/tcl/incr.htm
Normal file
@@ -0,0 +1,23 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - incr manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
incr - Increment the value of a variable
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>incr </B><I>varName </I>?<I>increment</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Increments the value stored in the variable whose name is <I>varName</I>.
|
||||
The value of the variable must be an integer.
|
||||
If <I>increment</I> is supplied then its value (which must be an
|
||||
integer) is added to the value of variable <I>varName</I>; otherwise
|
||||
1 is added to <I>varName</I>.
|
||||
The new value is stored as a decimal string in variable <I>varName</I>
|
||||
and also returned as result.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/expr.htm">expr</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#add">add</A>, <A href="../Keywords/I.htm#increment">increment</A>, <A href="../Keywords/V.htm#variable">variable</A>, <A href="../Keywords/V.htm#value">value</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
190
hlp/en/tcl/info.htm
Normal file
190
hlp/en/tcl/info.htm
Normal file
@@ -0,0 +1,190 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - info manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="info.htm#M2" NAME="L539">NAME</A>
|
||||
<DL><DD>info - Return information about the state of the Tcl interpreter</DL>
|
||||
<DD><A HREF="info.htm#M3" NAME="L540">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>info </B><I>option </I>?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="info.htm#M4" NAME="L541">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="info.htm#M5" NAME="L542"><B>info args </B><I>procname</I></A>
|
||||
<DD><A HREF="info.htm#M6" NAME="L543"><B>info body </B><I>procname</I></A>
|
||||
<DD><A HREF="info.htm#M7" NAME="L544"><B>info cmdcount</B></A>
|
||||
<DD><A HREF="info.htm#M8" NAME="L545"><B>info commands </B>?<I>pattern</I>?</A>
|
||||
<DD><A HREF="info.htm#M9" NAME="L546"><B>info complete </B><I>command</I></A>
|
||||
<DD><A HREF="info.htm#M10" NAME="L547"><B>info default </B><I>procname arg varname</I></A>
|
||||
<DD><A HREF="info.htm#M11" NAME="L548"><B>info exists </B><I>varName</I></A>
|
||||
<DD><A HREF="info.htm#M12" NAME="L549"><B>info globals </B>?<I>pattern</I>?</A>
|
||||
<DD><A HREF="info.htm#M13" NAME="L550"><B>info hostname</B></A>
|
||||
<DD><A HREF="info.htm#M14" NAME="L551"><B>info level</B> ?<I>number</I>?</A>
|
||||
<DD><A HREF="info.htm#M15" NAME="L552"><B>info library</B></A>
|
||||
<DD><A HREF="info.htm#M16" NAME="L553"><B>info loaded </B>?<I>interp</I>?</A>
|
||||
<DD><A HREF="info.htm#M17" NAME="L554"><B>info locals </B>?<I>pattern</I>?</A>
|
||||
<DD><A HREF="info.htm#M18" NAME="L555"><B>info nameofexecutable</B></A>
|
||||
<DD><A HREF="info.htm#M19" NAME="L556"><B>info patchlevel</B></A>
|
||||
<DD><A HREF="info.htm#M20" NAME="L557"><B>info procs </B>?<I>pattern</I>?</A>
|
||||
<DD><A HREF="info.htm#M21" NAME="L558"><B>info script</B></A>
|
||||
<DD><A HREF="info.htm#M22" NAME="L559"><B>info sharedlibextension</B></A>
|
||||
<DD><A HREF="info.htm#M23" NAME="L560"><B>info tclversion</B></A>
|
||||
<DD><A HREF="info.htm#M24" NAME="L561"><B>info vars</B> ?<I>pattern</I>?</A>
|
||||
</DL>
|
||||
<DD><A HREF="info.htm#M25" NAME="L562">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
info - Return information about the state of the Tcl interpreter
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>info </B><I>option </I>?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command provides information about various internals of the Tcl
|
||||
interpreter.
|
||||
The legal <I>option</I>'s (which may be abbreviated) are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>info args </B><I>procname</I></A><DD>
|
||||
Returns a list containing the names of the arguments to procedure
|
||||
<I>procname</I>, in order. <I>Procname</I> must be the name of a
|
||||
Tcl command procedure.
|
||||
<P><DT><A NAME="M6"><B>info body </B><I>procname</I></A><DD>
|
||||
Returns the body of procedure <I>procname</I>. <I>Procname</I> must be
|
||||
the name of a Tcl command procedure.
|
||||
<P><DT><A NAME="M7"><B>info cmdcount</B></A><DD>
|
||||
Returns a count of the total number of commands that have been invoked
|
||||
in this interpreter.
|
||||
<P><DT><A NAME="M8"><B>info commands </B>?<I>pattern</I>?</A><DD>
|
||||
If <I>pattern</I> isn't specified,
|
||||
returns a list of names of all the Tcl commands in the current namespace,
|
||||
including both the built-in commands written in C and
|
||||
the command procedures defined using the <B><A HREF="../TkCmd/proc.htm">proc</A></B> command.
|
||||
If <I>pattern</I> is specified,
|
||||
only those names matching <I>pattern</I> are returned.
|
||||
Matching is determined using the same rules as for <B><A HREF="../TkCmd/string.htm">string match</A></B>.
|
||||
<I>pattern</I> can be a qualified name like <B>Foo::print*</B>.
|
||||
That is, it may specify a particular namespace
|
||||
using a sequence of namespace names separated by <B>::</B>s,
|
||||
and may have pattern matching special characters
|
||||
at the end to specify a set of commands in that namespace.
|
||||
If <I>pattern</I> is a qualified name,
|
||||
the resulting list of command names has each one qualified with the name
|
||||
of the specified namespace.
|
||||
<P><DT><A NAME="M9"><B>info complete </B><I>command</I></A><DD>
|
||||
Returns 1 if <I>command</I> is a complete Tcl command in the sense of
|
||||
having no unclosed quotes, braces, brackets or array element names,
|
||||
If the command doesn't appear to be complete then 0 is returned.
|
||||
This command is typically used in line-oriented input environments
|
||||
to allow users to type in commands that span multiple lines; if the
|
||||
command isn't complete, the script can delay evaluating it until additional
|
||||
lines have been typed to complete the command.
|
||||
<P><DT><A NAME="M10"><B>info default </B><I>procname arg varname</I></A><DD>
|
||||
<I>Procname</I> must be the name of a Tcl command procedure and <I>arg</I>
|
||||
must be the name of an argument to that procedure. If <I>arg</I>
|
||||
doesn't have a default value then the command returns <B>0</B>.
|
||||
Otherwise it returns <B>1</B> and places the default value of <I>arg</I>
|
||||
into variable <I>varname</I>.
|
||||
<P><DT><A NAME="M11"><B>info exists </B><I>varName</I></A><DD>
|
||||
Returns <B>1</B> if the variable named <I>varName</I> exists in the
|
||||
current context (either as a global or local variable) and has been
|
||||
defined by being given a value, returns <B>0</B> otherwise.
|
||||
<P><DT><A NAME="M12"><B>info globals </B>?<I>pattern</I>?</A><DD>
|
||||
If <I>pattern</I> isn't specified, returns a list of all the names
|
||||
of currently-defined global variables.
|
||||
Global variables are variables in the global namespace.
|
||||
If <I>pattern</I> is specified, only those names matching <I>pattern</I>
|
||||
are returned. Matching is determined using the same rules as for
|
||||
<B><A HREF="../TkCmd/string.htm">string match</A></B>.
|
||||
<P><DT><A NAME="M13"><B>info hostname</B></A><DD>
|
||||
Returns the name of the computer on which this invocation is being
|
||||
executed.
|
||||
<P><DT><A NAME="M14"><B>info level</B> ?<I>number</I>?</A><DD>
|
||||
If <I>number</I> is not specified, this command returns a number
|
||||
giving the stack level of the invoking procedure, or 0 if the
|
||||
command is invoked at top-level. If <I>number</I> is specified,
|
||||
then the result is a list consisting of the name and arguments for the
|
||||
procedure call at level <I>number</I> on the stack. If <I>number</I>
|
||||
is positive then it selects a particular stack level (1 refers
|
||||
to the top-most active procedure, 2 to the procedure it called, and
|
||||
so on); otherwise it gives a level relative to the current level
|
||||
(0 refers to the current procedure, -1 to its caller, and so on).
|
||||
See the <B><A HREF="../TkCmd/uplevel.htm">uplevel</A></B> command for more information on what stack
|
||||
levels mean.
|
||||
<P><DT><A NAME="M15"><B>info library</B></A><DD>
|
||||
Returns the name of the library directory in which standard Tcl
|
||||
scripts are stored.
|
||||
This is actually the value of the <B>tcl_library</B>
|
||||
variable and may be changed by setting <B>tcl_library</B>.
|
||||
See the <B><A HREF="../TkCmd/tclvars.htm">tclvars</A></B> manual entry for more information.
|
||||
<P><DT><A NAME="M16"><B>info loaded </B>?<I>interp</I>?</A><DD>
|
||||
Returns a list describing all of the packages that have been loaded into
|
||||
<I>interp</I> with the <B><A HREF="../TkCmd/load.htm">load</A></B> command.
|
||||
Each list element is a sub-list with two elements consisting of the
|
||||
name of the file from which the package was loaded and the name of
|
||||
the package.
|
||||
For statically-loaded packages the file name will be an empty string.
|
||||
If <I>interp</I> is omitted then information is returned for all packages
|
||||
loaded in any interpreter in the process.
|
||||
To get a list of just the packages in the current interpreter, specify
|
||||
an empty string for the <I>interp</I> argument.
|
||||
<P><DT><A NAME="M17"><B>info locals </B>?<I>pattern</I>?</A><DD>
|
||||
If <I>pattern</I> isn't specified, returns a list of all the names
|
||||
of currently-defined local variables, including arguments to the
|
||||
current procedure, if any.
|
||||
Variables defined with the <B><A HREF="../TkCmd/global.htm">global</A></B> and <B><A HREF="../TkCmd/upvar.htm">upvar</A></B> commands
|
||||
will not be returned.
|
||||
If <I>pattern</I> is specified, only those names matching <I>pattern</I>
|
||||
are returned. Matching is determined using the same rules as for
|
||||
<B><A HREF="../TkCmd/string.htm">string match</A></B>.
|
||||
<P><DT><A NAME="M18"><B>info nameofexecutable</B></A><DD>
|
||||
Returns the full path name of the binary file from which the application
|
||||
was invoked. If Tcl was unable to identify the file, then an empty
|
||||
string is returned.
|
||||
<P><DT><A NAME="M19"><B>info patchlevel</B></A><DD>
|
||||
Returns the value of the global variable <B>tcl_patchLevel</B>; see
|
||||
the <B><A HREF="../TkCmd/tclvars.htm">tclvars</A></B> manual entry for more information.
|
||||
<P><DT><A NAME="M20"><B>info procs </B>?<I>pattern</I>?</A><DD>
|
||||
If <I>pattern</I> isn't specified, returns a list of all the
|
||||
names of Tcl command procedures in the current namespace.
|
||||
If <I>pattern</I> is specified,
|
||||
only those procedure names in the current namespace
|
||||
matching <I>pattern</I> are returned.
|
||||
Matching is determined using the same rules as for
|
||||
<B><A HREF="../TkCmd/string.htm">string match</A></B>.
|
||||
<P><DT><A NAME="M21"><B>info script</B></A><DD>
|
||||
If a Tcl script file is currently being evaluated (i.e. there is a
|
||||
call to <B><A HREF="../TkLib/Eval.htm">Tcl_EvalFile</A></B> active or there is an active invocation
|
||||
of the <B><A HREF="../TkCmd/source.htm">source</A></B> command), then this command returns the name
|
||||
of the innermost file being processed. Otherwise the command returns an
|
||||
empty string.
|
||||
<P><DT><A NAME="M22"><B>info sharedlibextension</B></A><DD>
|
||||
Returns the extension used on this platform for the names of files
|
||||
containing shared libraries (for example, <B>.so</B> under Solaris).
|
||||
If shared libraries aren't supported on this platform then an empty
|
||||
string is returned.
|
||||
<P><DT><A NAME="M23"><B>info tclversion</B></A><DD>
|
||||
Returns the value of the global variable <B>tcl_version</B>; see
|
||||
the <B><A HREF="../TkCmd/tclvars.htm">tclvars</A></B> manual entry for more information.
|
||||
<P><DT><A NAME="M24"><B>info vars</B> ?<I>pattern</I>?</A><DD>
|
||||
If <I>pattern</I> isn't specified,
|
||||
returns a list of all the names of currently-visible variables.
|
||||
This includes locals and currently-visible globals.
|
||||
If <I>pattern</I> is specified, only those names matching <I>pattern</I>
|
||||
are returned. Matching is determined using the same rules as for
|
||||
<B><A HREF="../TkCmd/string.htm">string match</A></B>.
|
||||
<I>pattern</I> can be a qualified name like <B>Foo::option*</B>.
|
||||
That is, it may specify a particular namespace
|
||||
using a sequence of namespace names separated by <B>::</B>s,
|
||||
and may have pattern matching special characters
|
||||
at the end to specify a set of variables in that namespace.
|
||||
If <I>pattern</I> is a qualified name,
|
||||
the resulting list of variable names
|
||||
has each matching namespace variable qualified with the name
|
||||
of its namespace.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M25">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#command">command</A>, <A href="../Keywords/I.htm#information">information</A>, <A href="../Keywords/I.htm#interpreter">interpreter</A>, <A href="../Keywords/L.htm#level">level</A>, <A href="../Keywords/N.htm#namespace">namespace</A>, <A href="../Keywords/P.htm#procedure">procedure</A>, <A href="../Keywords/V.htm#variable">variable</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993-1997 Bell Labs Innovations for Lucent Technologies
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
528
hlp/en/tcl/interp.htm
Normal file
528
hlp/en/tcl/interp.htm
Normal file
@@ -0,0 +1,528 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - interp manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="interp.htm#M2" NAME="L563">NAME</A>
|
||||
<DL><DD>interp - Create and manipulate Tcl interpreters</DL>
|
||||
<DD><A HREF="interp.htm#M3" NAME="L564">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>interp </B><I>option </I>?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="interp.htm#M4" NAME="L565">DESCRIPTION</A>
|
||||
<DD><A HREF="interp.htm#M5" NAME="L566">THE INTERP COMMAND</A>
|
||||
<DL>
|
||||
<DD><A HREF="interp.htm#M6" NAME="L567"><B>interp</B> <B>alias</B> <I>srcPath</I> <I>srcCmd</I></A>
|
||||
<DD><A HREF="interp.htm#M7" NAME="L568"><B>interp</B> <B>alias</B> <I>srcPath</I> <I>srcCmd</I> <B>{}</B></A>
|
||||
<DD><A HREF="interp.htm#M8" NAME="L569"><B>interp</B> <B>alias</B> <I>srcPath</I> <I>srcCmd</I> <I>targetPath</I> <I>targetCmd </I>?<I>arg arg ...</I>?</A>
|
||||
<DD><A HREF="interp.htm#M9" NAME="L570"><B>interp</B> <B>aliases </B>?<I>path</I>?</A>
|
||||
<DD><A HREF="interp.htm#M10" NAME="L571"><B>interp</B> <B>create </B>?<B>-safe</B>? ?<B>- -</B>? ?<I>path</I>?</A>
|
||||
<DD><A HREF="interp.htm#M11" NAME="L572"><B>interp</B> <B>delete </B>?<I>path ...?</I></A>
|
||||
<DD><A HREF="interp.htm#M12" NAME="L573"><B>interp</B> <B>eval</B> <I>path arg </I>?<I>arg ...</I>?</A>
|
||||
<DD><A HREF="interp.htm#M13" NAME="L574"><B>interp exists </B><I>path</I></A>
|
||||
<DD><A HREF="interp.htm#M14" NAME="L575"><B>interp expose </B><I>path</I> <I>hiddenName</I> ?<I>exposedCmdName</I>?</A>
|
||||
<DD><A HREF="interp.htm#M15" NAME="L576"><B>interp</B> <B>hide</B> <I>path</I> <I>exposedCmdName</I> ?<I>hiddenCmdName</I>?</A>
|
||||
<DD><A HREF="interp.htm#M16" NAME="L577"><B>interp</B> <B>hidden</B> <I>path</I></A>
|
||||
<DD><A HREF="interp.htm#M17" NAME="L578"><B>interp</B> <B>invokehidden</B> <I>path</I> ?<B>-global</B>? <I>hiddenCmdName</I> ?<I>arg ...</I>?</A>
|
||||
<DD><A HREF="interp.htm#M18" NAME="L579"><B>interp issafe</B> ?<I>path</I>?</A>
|
||||
<DD><A HREF="interp.htm#M19" NAME="L580"><B>interp marktrusted</B> <I>path</I></A>
|
||||
<DD><A HREF="interp.htm#M20" NAME="L581"><B>interp</B> <B>share</B> <I>srcPath channelId destPath</I></A>
|
||||
<DD><A HREF="interp.htm#M21" NAME="L582"><B>interp</B> <B>slaves</B> ?<I>path</I>?</A>
|
||||
<DD><A HREF="interp.htm#M22" NAME="L583"><B>interp</B> <B>target</B> <I>path alias</I></A>
|
||||
<DD><A HREF="interp.htm#M23" NAME="L584"><B>interp</B> <B>transfer</B> <I>srcPath channelId destPath</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="interp.htm#M24" NAME="L585">SLAVE COMMAND</A>
|
||||
<DL>
|
||||
<DD><A HREF="interp.htm#M25" NAME="L586"><I>slave </I><B>aliases</B></A>
|
||||
<DD><A HREF="interp.htm#M26" NAME="L587"><I>slave </I><B>alias </B><I>srcCmd</I></A>
|
||||
<DD><A HREF="interp.htm#M27" NAME="L588"><I>slave </I><B>alias </B><I>srcCmd </I><B>{}</B></A>
|
||||
<DD><A HREF="interp.htm#M28" NAME="L589"><I>slave </I><B>alias </B><I>srcCmd targetCmd </I>?<I>arg ..</I>?</A>
|
||||
<DD><A HREF="interp.htm#M29" NAME="L590"><I>slave </I><B>eval </B><I>arg </I>?<I>arg ..</I>?</A>
|
||||
<DD><A HREF="interp.htm#M30" NAME="L591"><I>slave </I><B>expose </B><I>hiddenName </I>?<I>exposedCmdName</I>?</A>
|
||||
<DD><A HREF="interp.htm#M31" NAME="L592"><I>slave </I><B>hide </B><I>exposedCmdName</I> ?<I>hiddenCmdName</I>?</A>
|
||||
<DD><A HREF="interp.htm#M32" NAME="L593"><I>slave </I><B>hidden</B></A>
|
||||
<DD><A HREF="interp.htm#M33" NAME="L594"><I>slave </I><B>invokehidden</B> ?<B>-global</B> <I>hiddenName </I>?<I>arg ..</I>?</A>
|
||||
<DD><A HREF="interp.htm#M34" NAME="L595"><I>slave </I><B>issafe</B></A>
|
||||
<DD><A HREF="interp.htm#M35" NAME="L596"><I>slave </I><B>marktrusted</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="interp.htm#M36" NAME="L597">SAFE INTERPRETERS</A>
|
||||
<DD><A HREF="interp.htm#M37" NAME="L598">ALIAS INVOCATION</A>
|
||||
<DD><A HREF="interp.htm#M38" NAME="L599">HIDDEN COMMANDS</A>
|
||||
<DD><A HREF="interp.htm#M39" NAME="L600">CREDITS</A>
|
||||
<DD><A HREF="interp.htm#M40" NAME="L601">SEE ALSO</A>
|
||||
<DD><A HREF="interp.htm#M41" NAME="L602">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
interp - Create and manipulate Tcl interpreters
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>interp </B><I>option </I>?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command makes it possible to create one or more new Tcl
|
||||
interpreters that co-exist with the creating interpreter in the
|
||||
same application. The creating interpreter is called the <I>master</I>
|
||||
and the new interpreter is called a <I>slave</I>.
|
||||
A master can create any number of slaves, and each slave can
|
||||
itself create additional slaves for which it is master, resulting
|
||||
in a hierarchy of interpreters.
|
||||
<P>
|
||||
Each interpreter is independent from the others: it has its own name
|
||||
space for commands, procedures, and global variables.
|
||||
A master interpreter may create connections between its slaves and
|
||||
itself using a mechanism called an <I>alias</I>. An <I>alias</I> is
|
||||
a command in a slave interpreter which, when invoked, causes a
|
||||
command to be invoked in its master interpreter or in another slave
|
||||
interpreter. The only other connections between interpreters are
|
||||
through environment variables (the <B>env</B> variable), which are
|
||||
normally shared among all interpreters in the application. Note that the
|
||||
name space for files (such as the names returned by the <B><A HREF="../TkCmd/open.htm">open</A></B> command)
|
||||
is no longer shared between interpreters. Explicit commands are provided to
|
||||
share files and to transfer references to open files from one interpreter
|
||||
to another.
|
||||
<P>
|
||||
The <B>interp</B> command also provides support for <I>safe</I>
|
||||
interpreters. A safe interpreter is a slave whose functions have
|
||||
been greatly restricted, so that it is safe to execute untrusted
|
||||
scripts without fear of them damaging other interpreters or the
|
||||
application's environment. For example, all IO channel creation
|
||||
commands and subprocess creation commands are made inaccessible to safe
|
||||
interpreters.
|
||||
See SAFE INTERPRETERS below for more information on
|
||||
what features are present in a safe interpreter.
|
||||
The dangerous functionality is not removed from the safe interpreter;
|
||||
instead, it is <I>hidden</I>, so that only trusted interpreters can obtain
|
||||
access to it. For a detailed explanation of hidden commands, see
|
||||
HIDDEN COMMANDS, below.
|
||||
The alias mechanism can be used for protected communication (analogous to a
|
||||
kernel call) between a slave interpreter and its master. See ALIAS
|
||||
INVOCATION, below, for more details on how the alias mechanism works.
|
||||
<P>
|
||||
A qualified interpreter name is a proper Tcl lists containing a subset of its
|
||||
ancestors in the interpreter hierarchy, terminated by the string naming the
|
||||
interpreter in its immediate master. Interpreter names are relative to the
|
||||
interpreter in which they are used. For example, if <B>a</B> is a slave of
|
||||
the current interpreter and it has a slave <B>a1</B>, which in turn has a
|
||||
slave <B>a11</B>, the qualified name of <B>a11</B> in <B>a</B> is the list
|
||||
<B>a1 a11</B>.
|
||||
<P>
|
||||
The <B>interp</B> command, described below, accepts qualified interpreter
|
||||
names as arguments; the interpreter in which the command is being evaluated
|
||||
can always be referred to as <B>{}</B> (the empty list or string). Note that
|
||||
it is impossible to refer to a master (ancestor) interpreter by name in a
|
||||
slave interpreter except through aliases. Also, there is no global name by
|
||||
which one can refer to the first interpreter created in an application.
|
||||
Both restrictions are motivated by safety concerns.
|
||||
|
||||
<H3><A NAME="M5">THE INTERP COMMAND</A></H3>
|
||||
The <B>interp</B> command is used to create, delete, and manipulate
|
||||
slave interpreters, and to share or transfer
|
||||
channels between interpreters. It can have any of several forms, depending
|
||||
on the <I>option</I> argument:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>interp</B> <B>alias</B> <I>srcPath</I> <I>srcCmd</I></A><DD>
|
||||
Returns a Tcl list whose elements are the <I>targetCmd</I> and
|
||||
<I>arg</I>s associated with the alias named <I>srcCmd</I>
|
||||
(all of these are the values specified when the alias was
|
||||
created; it is possible that the actual source command in the
|
||||
slave is different from <I>srcCmd</I> if it was renamed).
|
||||
<P><DT><A NAME="M7"><B>interp</B> <B>alias</B> <I>srcPath</I> <I>srcCmd</I> <B>{}</B></A><DD>
|
||||
Deletes the alias for <I>srcCmd</I> in the slave interpreter identified by
|
||||
<I>srcPath</I>.
|
||||
<I>srcCmd</I> refers to the name under which the alias
|
||||
was created; if the source command has been renamed, the renamed
|
||||
command will be deleted.
|
||||
<P><DT><A NAME="M8"><B>interp</B> <B>alias</B> <I>srcPath</I> <I>srcCmd</I> <I>targetPath</I> <I>targetCmd </I>?<I>arg arg ...</I>?</A><DD>
|
||||
This command creates an alias between one slave and another (see the
|
||||
<B>alias</B> slave command below for creating aliases between a slave
|
||||
and its master). In this command, either of the slave interpreters
|
||||
may be anywhere in the hierarchy of interpreters under the interpreter
|
||||
invoking the command.
|
||||
<I>SrcPath</I> and <I>srcCmd</I> identify the source of the alias.
|
||||
<I>SrcPath</I> is a Tcl list whose elements select a particular
|
||||
interpreter. For example, ``<B>a b</B>'' identifies an interpreter
|
||||
<B>b</B>, which is a slave of interpreter <B>a</B>, which is a slave
|
||||
of the invoking interpreter. An empty list specifies the interpreter
|
||||
invoking the command. <I>srcCmd</I> gives the name of a new
|
||||
command, which will be created in the source interpreter.
|
||||
<I>TargetPath</I> and <I>targetCmd</I> specify a target interpreter
|
||||
and command, and the <I>arg</I> arguments, if any, specify additional
|
||||
arguments to <I>targetCmd</I> which are prepended to any arguments specified
|
||||
in the invocation of <I>srcCmd</I>.
|
||||
<I>TargetCmd</I> may be undefined at the time of this call, or it may
|
||||
already exist; it is not created by this command.
|
||||
The alias arranges for the given target command to be invoked
|
||||
in the target interpreter whenever the given source command is
|
||||
invoked in the source interpreter. See ALIAS INVOCATION below for
|
||||
more details.
|
||||
<P><DT><A NAME="M9"><B>interp</B> <B>aliases </B>?<I>path</I>?</A><DD>
|
||||
This command returns a Tcl list of the names of all the source commands for
|
||||
aliases defined in the interpreter identified by <I>path</I>.
|
||||
<P><DT><A NAME="M10"><B>interp</B> <B>create </B>?<B>-safe</B>? ?<B>- -</B>? ?<I>path</I>?</A><DD>
|
||||
Creates a slave interpreter identified by <I>path</I> and a new command,
|
||||
called a <I>slave command</I>. The name of the slave command is the last
|
||||
component of <I>path</I>. The new slave interpreter and the slave command
|
||||
are created in the interpreter identified by the path obtained by removing
|
||||
the last component from <I>path</I>. For example, if <I>path is </I><B>a b
|
||||
c</B> then a new slave interpreter and slave command named <B>c</B> are
|
||||
created in the interpreter identified by the path <B>a b</B>.
|
||||
The slave command may be used to manipulate the new interpreter as
|
||||
described below. If <I>path</I> is omitted, Tcl creates a unique name of the
|
||||
form <B>interp</B><I>x</I>, where <I>x</I> is an integer, and uses it for the
|
||||
interpreter and the slave command. If the <B>-safe</B> switch is specified
|
||||
(or if the master interpreter is a safe interpreter), the new slave
|
||||
interpreter will be created as a safe interpreter with limited
|
||||
functionality; otherwise the slave will include the full set of Tcl
|
||||
built-in commands and variables. The <B>- -</B> switch can be used to
|
||||
mark the end of switches; it may be needed if <I>path</I> is an unusual
|
||||
value such as <B>-safe</B>. The result of the command is the name of the
|
||||
new interpreter. The name of a slave interpreter must be unique among all
|
||||
the slaves for its master; an error occurs if a slave interpreter by the
|
||||
given name already exists in this master.
|
||||
<P><DT><A NAME="M11"><B>interp</B> <B>delete </B>?<I>path ...?</I></A><DD>
|
||||
Deletes zero or more interpreters given by the optional <I>path</I>
|
||||
arguments, and for each interpreter, it also deletes its slaves. The
|
||||
command also deletes the slave command for each interpreter deleted.
|
||||
For each <I>path</I> argument, if no interpreter by that name
|
||||
exists, the command raises an error.
|
||||
<P><DT><A NAME="M12"><B>interp</B> <B>eval</B> <I>path arg </I>?<I>arg ...</I>?</A><DD>
|
||||
This command concatenates all of the <I>arg</I> arguments in the same
|
||||
fashion as the <B><A HREF="../TkCmd/concat.htm">concat</A></B> command, then evaluates the resulting string as
|
||||
a Tcl script in the slave interpreter identified by <I>path</I>. The result
|
||||
of this evaluation (including error information such as the <B>errorInfo</B>
|
||||
and <B>errorCode</B> variables, if an error occurs) is returned to the
|
||||
invoking interpreter.
|
||||
<P><DT><A NAME="M13"><B>interp exists </B><I>path</I></A><DD>
|
||||
Returns <B>1</B> if a slave interpreter by the specified <I>path</I>
|
||||
exists in this master, <B>0</B> otherwise. If <I>path</I> is omitted, the
|
||||
invoking interpreter is used.
|
||||
<P><DT><A NAME="M14"><B>interp expose </B><I>path</I> <I>hiddenName</I> ?<I>exposedCmdName</I>?</A><DD>
|
||||
Makes the hidden command <I>hiddenName</I> exposed, eventually bringing
|
||||
it back under a new <I>exposedCmdName</I> name (this name is currently
|
||||
accepted only if it is a valid global name space name without any ::),
|
||||
in the interpreter
|
||||
denoted by <I>path</I>.
|
||||
If an exposed command with the targetted name already exists, this command
|
||||
fails.
|
||||
Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
|
||||
<P><DT><A NAME="M15"><B>interp</B> <B>hide</B> <I>path</I> <I>exposedCmdName</I> ?<I>hiddenCmdName</I>?</A><DD>
|
||||
Makes the exposed command <I>exposedCmdName</I> hidden, renaming
|
||||
it to the hidden command <I>hiddenCmdName</I>, or keeping the same name if
|
||||
<I>hiddenCmdName</I> is not given, in the interpreter denoted
|
||||
by <I>path</I>.
|
||||
If a hidden command with the targetted name already exists, this command
|
||||
fails.
|
||||
Currently both <I>exposedCmdName</I> and <I>hiddenCmdName</I> can
|
||||
not contain namespace qualifiers, or an error is raised.
|
||||
Commands to be hidden by <B>interp hide</B> are looked up in the global
|
||||
namespace even if the current namespace is not the global one. This
|
||||
prevents slaves from fooling a master interpreter into hiding the wrong
|
||||
command, by making the current namespace be different from the global one.
|
||||
Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
|
||||
<P><DT><A NAME="M16"><B>interp</B> <B>hidden</B> <I>path</I></A><DD>
|
||||
Returns a list of the names of all hidden commands in the interpreter
|
||||
identified by <I>path</I>.
|
||||
<P><DT><A NAME="M17"><B>interp</B> <B>invokehidden</B> <I>path</I> ?<B>-global</B>? <I>hiddenCmdName</I> ?<I>arg ...</I>?</A><DD>
|
||||
Invokes the hidden command <I>hiddenCmdName</I> with the arguments supplied
|
||||
in the interpreter denoted by <I>path</I>. No substitutions or evaluation
|
||||
are applied to the arguments.
|
||||
If the <B>-global</B> flag is present, the hidden command is invoked at the
|
||||
global level in the target interpreter; otherwise it is invoked at the
|
||||
current call frame and can access local variables in that and outer call
|
||||
frames.
|
||||
Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
|
||||
<P><DT><A NAME="M18"><B>interp issafe</B> ?<I>path</I>?</A><DD>
|
||||
Returns <B>1</B> if the interpreter identified by the specified <I>path</I>
|
||||
is safe, <B>0</B> otherwise.
|
||||
<P><DT><A NAME="M19"><B>interp marktrusted</B> <I>path</I></A><DD>
|
||||
Marks the interpreter identified by <I>path</I> as trusted. Does
|
||||
not expose the hidden commands. This command can only be invoked from a
|
||||
trusted interpreter.
|
||||
The command has no effect if the interpreter identified by <I>path</I> is
|
||||
already trusted.
|
||||
<P><DT><A NAME="M20"><B>interp</B> <B>share</B> <I>srcPath channelId destPath</I></A><DD>
|
||||
Causes the IO channel identified by <I>channelId</I> to become shared
|
||||
between the interpreter identified by <I>srcPath</I> and the interpreter
|
||||
identified by <I>destPath</I>. Both interpreters have the same permissions
|
||||
on the IO channel.
|
||||
Both interpreters must close it to close the underlying IO channel; IO
|
||||
channels accessible in an interpreter are automatically closed when an
|
||||
interpreter is destroyed.
|
||||
<P><DT><A NAME="M21"><B>interp</B> <B>slaves</B> ?<I>path</I>?</A><DD>
|
||||
Returns a Tcl list of the names of all the slave interpreters associated
|
||||
with the interpreter identified by <I>path</I>. If <I>path</I> is omitted,
|
||||
the invoking interpreter is used.
|
||||
<P><DT><A NAME="M22"><B>interp</B> <B>target</B> <I>path alias</I></A><DD>
|
||||
Returns a Tcl list describing the target interpreter for an alias. The
|
||||
alias is specified with an interpreter path and source command name, just
|
||||
as in <B>interp alias</B> above. The name of the target interpreter is
|
||||
returned as an interpreter path, relative to the invoking interpreter.
|
||||
If the target interpreter for the alias is the invoking interpreter then an
|
||||
empty list is returned. If the target interpreter for the alias is not the
|
||||
invoking interpreter or one of its descendants then an error is generated.
|
||||
The target command does not have to be defined at the time of this invocation.
|
||||
<P><DT><A NAME="M23"><B>interp</B> <B>transfer</B> <I>srcPath channelId destPath</I></A><DD>
|
||||
Causes the IO channel identified by <I>channelId</I> to become available in
|
||||
the interpreter identified by <I>destPath</I> and unavailable in the
|
||||
interpreter identified by <I>srcPath</I>.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M24">SLAVE COMMAND</A></H3>
|
||||
For each slave interpreter created with the <B>interp</B> command, a
|
||||
new Tcl command is created in the master interpreter with the same
|
||||
name as the new interpreter. This command may be used to invoke
|
||||
various operations on the interpreter. It has the following
|
||||
general form:
|
||||
<PRE><I>slave command </I>?<I>arg arg ...</I>?</PRE>
|
||||
<I>Slave</I> is the name of the interpreter, and <I>command</I>
|
||||
and the <I>arg</I>s determine the exact behavior of the command.
|
||||
The valid forms of this command are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M25"><I>slave </I><B>aliases</B></A><DD>
|
||||
Returns a Tcl list whose elements are the names of all the
|
||||
aliases in <I>slave</I>. The names returned are the <I>srcCmd</I>
|
||||
values used when the aliases were created (which may not be the same
|
||||
as the current names of the commands, if they have been
|
||||
renamed).
|
||||
<P><DT><A NAME="M26"><I>slave </I><B>alias </B><I>srcCmd</I></A><DD>
|
||||
Returns a Tcl list whose elements are the <I>targetCmd</I> and
|
||||
<I>arg</I>s associated with the alias named <I>srcCmd</I>
|
||||
(all of these are the values specified when the alias was
|
||||
created; it is possible that the actual source command in the
|
||||
slave is different from <I>srcCmd</I> if it was renamed).
|
||||
<P><DT><A NAME="M27"><I>slave </I><B>alias </B><I>srcCmd </I><B>{}</B></A><DD>
|
||||
Deletes the alias for <I>srcCmd</I> in the slave interpreter.
|
||||
<I>srcCmd</I> refers to the name under which the alias
|
||||
was created; if the source command has been renamed, the renamed
|
||||
command will be deleted.
|
||||
<P><DT><A NAME="M28"><I>slave </I><B>alias </B><I>srcCmd targetCmd </I>?<I>arg ..</I>?</A><DD>
|
||||
Creates an alias such that whenever <I>srcCmd</I> is invoked
|
||||
in <I>slave</I>, <I>targetCmd</I> is invoked in the master.
|
||||
The <I>arg</I> arguments will be passed to <I>targetCmd</I> as additional
|
||||
arguments, prepended before any arguments passed in the invocation of
|
||||
<I>srcCmd</I>.
|
||||
See ALIAS INVOCATION below for details.
|
||||
<P><DT><A NAME="M29"><I>slave </I><B>eval </B><I>arg </I>?<I>arg ..</I>?</A><DD>
|
||||
This command concatenates all of the <I>arg</I> arguments in
|
||||
the same fashion as the <B><A HREF="../TkCmd/concat.htm">concat</A></B> command, then evaluates
|
||||
the resulting string as a Tcl script in <I>slave</I>.
|
||||
The result of this evaluation (including error information
|
||||
such as the <B>errorInfo</B> and <B>errorCode</B> variables, if an
|
||||
error occurs) is returned to the invoking interpreter.
|
||||
<P><DT><A NAME="M30"><I>slave </I><B>expose </B><I>hiddenName </I>?<I>exposedCmdName</I>?</A><DD>
|
||||
This command exposes the hidden command <I>hiddenName</I>, eventually bringing
|
||||
it back under a new <I>exposedCmdName</I> name (this name is currently
|
||||
accepted only if it is a valid global name space name without any ::),
|
||||
in <I>slave</I>.
|
||||
If an exposed command with the targetted name already exists, this command
|
||||
fails.
|
||||
For more details on hidden commands, see HIDDEN COMMANDS, below.
|
||||
<P><DT><A NAME="M31"><I>slave </I><B>hide </B><I>exposedCmdName</I> ?<I>hiddenCmdName</I>?</A><DD>
|
||||
This command hides the exposed command <I>exposedCmdName</I>, renaming it to
|
||||
the hidden command <I>hiddenCmdName</I>, or keeping the same name if the
|
||||
the argument is not given, in the <I>slave</I> interpreter.
|
||||
If a hidden command with the targetted name already exists, this command
|
||||
fails.
|
||||
Currently both <I>exposedCmdName</I> and <I>hiddenCmdName</I> can
|
||||
not contain namespace qualifiers, or an error is raised.
|
||||
Commands to be hidden are looked up in the global
|
||||
namespace even if the current namespace is not the global one. This
|
||||
prevents slaves from fooling a master interpreter into hiding the wrong
|
||||
command, by making the current namespace be different from the global one.
|
||||
For more details on hidden commands, see HIDDEN COMMANDS, below.
|
||||
<P><DT><A NAME="M32"><I>slave </I><B>hidden</B></A><DD>
|
||||
Returns a list of the names of all hidden commands in <I>slave</I>.
|
||||
<P><DT><A NAME="M33"><I>slave </I><B>invokehidden</B> ?<B>-global</B> <I>hiddenName </I>?<I>arg ..</I>?</A><DD>
|
||||
This command invokes the hidden command <I>hiddenName</I> with the
|
||||
supplied arguments, in <I>slave</I>. No substitutions or evaluations are
|
||||
applied to the arguments.
|
||||
If the <B>-global</B> flag is given, the command is invoked at the global
|
||||
level in the slave; otherwise it is invoked at the current call frame and
|
||||
can access local variables in that or outer call frames.
|
||||
For more details on hidden commands, see HIDDEN
|
||||
COMMANDS, below.
|
||||
<P><DT><A NAME="M34"><I>slave </I><B>issafe</B></A><DD>
|
||||
Returns <B>1</B> if the slave interpreter is safe, <B>0</B> otherwise.
|
||||
<P><DT><A NAME="M35"><I>slave </I><B>marktrusted</B></A><DD>
|
||||
Marks the slave interpreter as trusted. Can only be invoked by a
|
||||
trusted interpreter. This command does not expose any hidden
|
||||
commands in the slave interpreter. The command has no effect if the slave
|
||||
is already trusted.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M36">SAFE INTERPRETERS</A></H3>
|
||||
A safe interpreter is one with restricted functionality, so that
|
||||
is safe to execute an arbitrary script from your worst enemy without
|
||||
fear of that script damaging the enclosing application or the rest
|
||||
of your computing environment. In order to make an interpreter
|
||||
safe, certain commands and variables are removed from the interpreter.
|
||||
For example, commands to create files on disk are removed, and the
|
||||
<B><A HREF="../TkCmd/exec.htm">exec</A></B> command is removed, since it could be used to cause damage
|
||||
through subprocesses.
|
||||
Limited access to these facilities can be provided, by creating
|
||||
aliases to the master interpreter which check their arguments carefully
|
||||
and provide restricted access to a safe subset of facilities.
|
||||
For example, file creation might be allowed in a particular subdirectory
|
||||
and subprocess invocation might be allowed for a carefully selected and
|
||||
fixed set of programs.
|
||||
<P>
|
||||
A safe interpreter is created by specifying the <B>-safe</B> switch
|
||||
to the <B>interp create</B> command. Furthermore, any slave created
|
||||
by a safe interpreter will also be safe.
|
||||
<P>
|
||||
A safe interpreter is created with exactly the following set of
|
||||
built-in commands:
|
||||
<PRE><B>after append array binary
|
||||
break case catch clock
|
||||
close concat continue eof
|
||||
error eval expr fblocked
|
||||
fcopy fileevent flush for
|
||||
foreach format gets global
|
||||
history if incr info
|
||||
interp join lappend lindex
|
||||
linsert list llength lrange
|
||||
lreplace lsearch lsort namespace
|
||||
package pid proc puts
|
||||
read regexp regsub rename
|
||||
return scan seek set
|
||||
split string subst switch
|
||||
tell trace unset update
|
||||
uplevel upvar variable vwait
|
||||
while</B></PRE>
|
||||
The following commands are hidden by <B>interp create</B> when it
|
||||
creates a safe interpreter:
|
||||
<PRE><B>cd exec exit fconfigure
|
||||
file glob load open
|
||||
pwd socket source vwait</B></PRE>
|
||||
These commands can be recreated later as Tcl procedures or aliases, or
|
||||
re-exposed by <B>interp expose</B>.
|
||||
<P>
|
||||
In addition, the <B>env</B> variable is not present in a safe interpreter,
|
||||
so it cannot share environment variables with other interpreters. The
|
||||
<B>env</B> variable poses a security risk, because users can store
|
||||
sensitive information in an environment variable. For example, the PGP
|
||||
manual recommends storing the PGP private key protection password in
|
||||
the environment variable <I>PGPPASS</I>. Making this variable available
|
||||
to untrusted code executing in a safe interpreter would incur a
|
||||
security risk.
|
||||
<P>
|
||||
If extensions are loaded into a safe interpreter, they may also restrict
|
||||
their own functionality to eliminate unsafe commands. For a discussion of
|
||||
management of extensions for safety see the manual entries for
|
||||
<B>Safe-Tcl</B> and the <B><A HREF="../TkCmd/load.htm">load</A></B> Tcl command.
|
||||
|
||||
<H3><A NAME="M37">ALIAS INVOCATION</A></H3>
|
||||
The alias mechanism has been carefully designed so that it can
|
||||
be used safely when an untrusted script is executing
|
||||
in a safe slave and the target of the alias is a trusted
|
||||
master. The most important thing in guaranteeing safety is to
|
||||
ensure that information passed from the slave to the master is
|
||||
never evaluated or substituted in the master; if this were to
|
||||
occur, it would enable an evil script in the slave to invoke
|
||||
arbitrary functions in the master, which would compromise security.
|
||||
<P>
|
||||
When the source for an alias is invoked in the slave interpreter, the
|
||||
usual Tcl substitutions are performed when parsing that command.
|
||||
These substitutions are carried out in the source interpreter just
|
||||
as they would be for any other command invoked in that interpreter.
|
||||
The command procedure for the source command takes its arguments
|
||||
and merges them with the <I>targetCmd</I> and <I>arg</I>s for the
|
||||
alias to create a new array of arguments. If the words
|
||||
of <I>srcCmd</I> were ``<I>srcCmd arg1 arg2 ... argN</I>'',
|
||||
the new set of words will be
|
||||
``<I>targetCmd arg arg ... arg arg1 arg2 ... argN</I>'',
|
||||
where <I>targetCmd</I> and <I>arg</I>s are the values supplied when the
|
||||
alias was created. <I>TargetCmd</I> is then used to locate a command
|
||||
procedure in the target interpreter, and that command procedure
|
||||
is invoked with the new set of arguments. An error occurs if
|
||||
there is no command named <I>targetCmd</I> in the target interpreter.
|
||||
No additional substitutions are performed on the words: the
|
||||
target command procedure is invoked directly, without
|
||||
going through the normal Tcl evaluation mechanism.
|
||||
Substitutions are thus performed on each word exactly once:
|
||||
<I>targetCmd</I> and <I>args</I> were substituted when parsing the command
|
||||
that created the alias, and <I>arg1 - argN</I> are substituted when
|
||||
the alias's source command is parsed in the source interpreter.
|
||||
<P>
|
||||
When writing the <I>targetCmd</I>s for aliases in safe interpreters,
|
||||
it is very important that the arguments to that command never be
|
||||
evaluated or substituted, since this would provide an escape
|
||||
mechanism whereby the slave interpreter could execute arbitrary
|
||||
code in the master. This in turn would compromise the security
|
||||
of the system.
|
||||
|
||||
<H3><A NAME="M38">HIDDEN COMMANDS</A></H3>
|
||||
Safe interpreters greatly restrict the functionality available to Tcl
|
||||
programs executing within them.
|
||||
Allowing the untrusted Tcl program to have direct access to this
|
||||
functionality is unsafe, because it can be used for a variety of
|
||||
attacks on the environment.
|
||||
However, there are times when there is a legitimate need to use the
|
||||
dangerous functionality in the context of the safe interpreter. For
|
||||
example, sometimes a program must be <B><A HREF="../TkCmd/source.htm">source</A></B>d into the interpreter.
|
||||
Another example is Tk, where windows are bound to the hierarchy of windows
|
||||
for a specific interpreter; some potentially dangerous functions, e.g.
|
||||
window management, must be performed on these windows within the
|
||||
interpreter context.
|
||||
<P>
|
||||
The <B>interp</B> command provides a solution to this problem in the form of
|
||||
<I>hidden commands</I>. Instead of removing the dangerous commands entirely
|
||||
from a safe interpreter, these commands are hidden so they become
|
||||
unavailable to Tcl scripts executing in the interpreter. However, such
|
||||
hidden commands can be invoked by any trusted ancestor of the safe
|
||||
interpreter, in the context of the safe interpreter, using <B>interp
|
||||
invoke</B>. Hidden commands and exposed commands reside in separate name
|
||||
spaces. It is possible to define a hidden command and an exposed command by
|
||||
the same name within one interpreter.
|
||||
<P>
|
||||
Hidden commands in a slave interpreter can be invoked in the body of
|
||||
procedures called in the master during alias invocation. For example, an
|
||||
alias for <B><A HREF="../TkCmd/source.htm">source</A></B> could be created in a slave interpreter. When it is
|
||||
invoked in the slave interpreter, a procedure is called in the master
|
||||
interpreter to check that the operation is allowable (e.g. it asks to
|
||||
source a file that the slave interpreter is allowed to access). The
|
||||
procedure then it invokes the hidden <B><A HREF="../TkCmd/source.htm">source</A></B> command in the slave
|
||||
interpreter to actually source in the contents of the file. Note that two
|
||||
commands named <B><A HREF="../TkCmd/source.htm">source</A></B> exist in the slave interpreter: the alias, and
|
||||
the hidden command.
|
||||
<P>
|
||||
Because a master interpreter may invoke a hidden command as part of
|
||||
handling an alias invocation, great care must be taken to avoid evaluating
|
||||
any arguments passed in through the alias invocation.
|
||||
Otherwise, malicious slave interpreters could cause a trusted master
|
||||
interpreter to execute dangerous commands on their behalf. See the section
|
||||
on ALIAS INVOCATION for a more complete discussion of this topic.
|
||||
To help avoid this problem, no substitutions or evaluations are
|
||||
applied to arguments of <B>interp invokehidden</B>.
|
||||
<P>
|
||||
Safe interpreters are not allowed to invoke hidden commands in themselves
|
||||
or in their descendants. This prevents safe slaves from gaining access to
|
||||
hidden functionality in themselves or their descendants.
|
||||
<P>
|
||||
The set of hidden commands in an interpreter can be manipulated by a trusted
|
||||
interpreter using <B>interp expose</B> and <B>interp hide</B>. The <B>interp
|
||||
expose</B> command moves a hidden command to the
|
||||
set of exposed commands in the interpreter identified by <I>path</I>,
|
||||
potentially renaming the command in the process. If an exposed command by
|
||||
the targetted name already exists, the operation fails. Similarly,
|
||||
<B>interp hide</B> moves an exposed command to the set of hidden commands in
|
||||
that interpreter. Safe interpreters are not allowed to move commands
|
||||
between the set of hidden and exposed commands, in either themselves or
|
||||
their descendants.
|
||||
<P>
|
||||
Currently, the names of hidden commands cannot contain namespace
|
||||
qualifiers, and you must first rename a command in a namespace to the
|
||||
global namespace before you can hide it.
|
||||
Commands to be hidden by <B>interp hide</B> are looked up in the global
|
||||
namespace even if the current namespace is not the global one. This
|
||||
prevents slaves from fooling a master interpreter into hiding the wrong
|
||||
command, by making the current namespace be different from the global one.
|
||||
<H3><A NAME="M39">CREDITS</A></H3>
|
||||
This mechanism is based on the Safe-Tcl prototype implemented
|
||||
by Nathaniel Borenstein and Marshall Rose.
|
||||
|
||||
<H3><A NAME="M40">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/load.htm">load</A></B>, <B>safe</B>, <B><A HREF="../TkLib/CrtSlave.htm">Tcl_CreateSlave</A></B>
|
||||
<H3><A NAME="M41">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#alias">alias</A>, <A href="../Keywords/M.htm#master interpreter">master interpreter</A>, <A href="../Keywords/S.htm#safe interpreter">safe interpreter</A>, <A href="../Keywords/S.htm#slave interpreter">slave interpreter</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
21
hlp/en/tcl/join.htm
Normal file
21
hlp/en/tcl/join.htm
Normal file
@@ -0,0 +1,21 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - join manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
join - Create a string by joining together list elements
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>join </B><I>list </I>?<I>joinString</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <I>list</I> argument must be a valid Tcl list.
|
||||
This command returns the string
|
||||
formed by joining all of the elements of <I>list</I> together with
|
||||
<I>joinString</I> separating each adjacent pair of elements.
|
||||
The <I>joinString</I> argument defaults to a space character.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/list.htm">list</A></B>, <B><A HREF="../TkCmd/lappend.htm">lappend</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#element">element</A>, <A href="../Keywords/J.htm#join">join</A>, <A href="../Keywords/L.htm#list">list</A>, <A href="../Keywords/S.htm#separator">separator</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
27
hlp/en/tcl/lappend.htm
Normal file
27
hlp/en/tcl/lappend.htm
Normal file
@@ -0,0 +1,27 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - lappend manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
lappend - Append list elements onto a variable
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>lappend </B><I>varName </I>?<I>value value value ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command treats the variable given by <I>varName</I> as a list
|
||||
and appends each of the <I>value</I> arguments to that list as a separate
|
||||
element, with spaces between elements.
|
||||
If <I>varName</I> doesn't exist, it is created as a list with elements
|
||||
given by the <I>value</I> arguments.
|
||||
<B>Lappend</B> is similar to <B><A HREF="../TkCmd/append.htm">append</A></B> except that the <I>value</I>s
|
||||
are appended as list elements rather than raw text.
|
||||
This command provides a relatively efficient way to build up
|
||||
large lists. For example, ``<B>lappend a $b</B>'' is much
|
||||
more efficient than ``<B>set a [concat $a [list $b]]</B>'' when
|
||||
<B>$a</B> is long.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/list.htm">list</A></B>, <B><A HREF="../TkCmd/lindex.htm">lindex</A></B>, <B><A HREF="../TkCmd/linsert.htm">linsert</A></B>, <B><A HREF="../TkCmd/llength.htm">llength</A></B>, <B><A HREF="../TkCmd/lsort.htm">lsort</A></B>, <B><A HREF="../TkCmd/lrange.htm">lrange</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#append">append</A>, <A href="../Keywords/E.htm#element">element</A>, <A href="../Keywords/L.htm#list">list</A>, <A href="../Keywords/V.htm#variable">variable</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
320
hlp/en/tcl/library.htm
Normal file
320
hlp/en/tcl/library.htm
Normal file
@@ -0,0 +1,320 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - library manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="library.htm#M2" NAME="L613">NAME</A>
|
||||
<DL><DD>auto_execok, auto_import, auto_load, auto_mkindex, auto_mkindex_old, auto_qualify, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore - standard library of Tcl procedures</DL>
|
||||
<DD><A HREF="library.htm#M3" NAME="L614">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>auto_execok </B><I>cmd</I>
|
||||
<DD><B>auto_import </B><I>pattern</I>
|
||||
<DD><B>auto_load </B><I>cmd</I>
|
||||
<DD><B>auto_mkindex </B><I>dir pattern pattern ...</I>
|
||||
<DD><B>auto_mkindex_old </B><I>dir pattern pattern ...</I>
|
||||
<DD><B>auto_qualify </B><I>command namespace</I>
|
||||
<DD><B>auto_reset</B>
|
||||
<DD><B>tcl_findLibrary </B><I>basename version patch initScript enVarName varName</I>
|
||||
<DD><B>parray </B><I>arrayName</I>
|
||||
<DD><B>tcl_endOfWord </B><I>str start</I>
|
||||
<DD><B>tcl_startOfNextWord </B><I>str start</I>
|
||||
<DD><B>tcl_startOfPreviousWord </B><I>str start</I>
|
||||
<DD><B>tcl_wordBreakAfter </B><I>str start</I>
|
||||
<DD><B>tcl_wordBreakBefore </B><I>str start</I>
|
||||
</DL>
|
||||
<DD><A HREF="library.htm#M4" NAME="L615">INTRODUCTION</A>
|
||||
<DD><A HREF="library.htm#M5" NAME="L616">COMMAND PROCEDURES</A>
|
||||
<DL>
|
||||
<DD><A HREF="library.htm#M6" NAME="L617"><B>auto_execok </B><I>cmd</I></A>
|
||||
<DD><A HREF="library.htm#M7" NAME="L618"><B>auto_import </B><I>pattern</I></A>
|
||||
<DD><A HREF="library.htm#M8" NAME="L619"><B>auto_load </B><I>cmd</I></A>
|
||||
<DD><A HREF="library.htm#M9" NAME="L620"><B>auto_mkindex </B><I>dir pattern pattern ...</I></A>
|
||||
<DD><A HREF="library.htm#M10" NAME="L621"><B>auto_reset</B></A>
|
||||
<DD><A HREF="library.htm#M11" NAME="L622"><B>auto_qualify </B><I>command namespace</I></A>
|
||||
<DD><A HREF="library.htm#M12" NAME="L623"><B>tcl_findLibrary </B><I>basename version patch initScript enVarName varName</I></A>
|
||||
<DD><A HREF="library.htm#M13" NAME="L624"><B>parray </B><I>arrayName</I></A>
|
||||
<DD><A HREF="library.htm#M14" NAME="L625"><B>tcl_endOfWord </B><I>str start</I></A>
|
||||
<DD><A HREF="library.htm#M15" NAME="L626"><B>tcl_startOfNextWord </B><I>str start</I></A>
|
||||
<DD><A HREF="library.htm#M16" NAME="L627"><B>tcl_startOfPreviousWord </B><I>str start</I></A>
|
||||
<DD><A HREF="library.htm#M17" NAME="L628"><B>tcl_wordBreakAfter </B><I>str start</I></A>
|
||||
<DD><A HREF="library.htm#M18" NAME="L629"><B>tcl_wordBreakBefore </B><I>str start</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="library.htm#M19" NAME="L630">VARIABLES</A>
|
||||
<DL>
|
||||
<DD><A HREF="library.htm#M20" NAME="L631"><B>auto_execs</B></A>
|
||||
<DD><A HREF="library.htm#M21" NAME="L632"><B>auto_index</B></A>
|
||||
<DD><A HREF="library.htm#M22" NAME="L633"><B>auto_noexec</B></A>
|
||||
<DD><A HREF="library.htm#M23" NAME="L634"><B>auto_noload</B></A>
|
||||
<DD><A HREF="library.htm#M24" NAME="L635"><B>auto_path</B></A>
|
||||
<DD><A HREF="library.htm#M25" NAME="L636"><B>env(TCL_LIBRARY)</B></A>
|
||||
<DD><A HREF="library.htm#M26" NAME="L637"><B>env(TCLLIBPATH)</B></A>
|
||||
<DD><A HREF="library.htm#M27" NAME="L638"><B>tcl_nonwordchars</B></A>
|
||||
<DD><A HREF="library.htm#M28" NAME="L639"><B>tcl_wordchars</B></A>
|
||||
<DD><A HREF="library.htm#M29" NAME="L640"><B>unknown_pending</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="library.htm#M30" NAME="L641">SEE ALSO</A>
|
||||
<DD><A HREF="library.htm#M31" NAME="L642">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
auto_execok, auto_import, auto_load, auto_mkindex, auto_mkindex_old, auto_qualify, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore - standard library of Tcl procedures
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>auto_execok </B><I>cmd</I><BR>
|
||||
<B>auto_import </B><I>pattern</I><BR>
|
||||
<B>auto_load </B><I>cmd</I><BR>
|
||||
<B>auto_mkindex </B><I>dir pattern pattern ...</I><BR>
|
||||
<B>auto_mkindex_old </B><I>dir pattern pattern ...</I><BR>
|
||||
<B>auto_qualify </B><I>command namespace</I><BR>
|
||||
<B>auto_reset</B><BR>
|
||||
<B>tcl_findLibrary </B><I>basename version patch initScript enVarName varName</I><BR>
|
||||
<B>parray </B><I>arrayName</I><BR>
|
||||
<B>tcl_endOfWord </B><I>str start</I><BR>
|
||||
<B>tcl_startOfNextWord </B><I>str start</I><BR>
|
||||
<B>tcl_startOfPreviousWord </B><I>str start</I><BR>
|
||||
<B>tcl_wordBreakAfter </B><I>str start</I><BR>
|
||||
<B>tcl_wordBreakBefore </B><I>str start</I><BR>
|
||||
<H3><A NAME="M4">INTRODUCTION</A></H3>
|
||||
Tcl includes a library of Tcl procedures for commonly-needed functions.
|
||||
The procedures defined in the Tcl library are generic ones suitable
|
||||
for use by many different applications.
|
||||
The location of the Tcl library is returned by the <B><A HREF="../TkCmd/info.htm">info library</A></B>
|
||||
command.
|
||||
In addition to the Tcl library, each application will normally have
|
||||
its own library of support procedures as well; the location of this
|
||||
library is normally given by the value of the <B>$</B><I>app</I><B>_library</B>
|
||||
global variable, where <I>app</I> is the name of the application.
|
||||
For example, the location of the Tk library is kept in the variable
|
||||
<B>$tk_library</B>.
|
||||
<P>
|
||||
To access the procedures in the Tcl library, an application should
|
||||
source the file <B>init.tcl</B> in the library, for example with
|
||||
the Tcl command
|
||||
<PRE><B>source [file join [info library] init.tcl]</B></PRE>
|
||||
If the library procedure <B><A HREF="../TkLib/Init.htm">Tcl_Init</A></B> is invoked from an application's
|
||||
<B><A HREF="../TkLib/AppInit.htm">Tcl_AppInit</A></B> procedure, this happens automatically.
|
||||
The code in <B>init.tcl</B> will define the <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> procedure
|
||||
and arrange for the other procedures to be loaded on-demand using
|
||||
the auto-load mechanism defined below.
|
||||
|
||||
<H3><A NAME="M5">COMMAND PROCEDURES</A></H3>
|
||||
The following procedures are provided in the Tcl library:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>auto_execok </B><I>cmd</I></A><DD>
|
||||
Determines whether there is an executable file or shell builtin
|
||||
by the name <I>cmd</I>. If so, it returns a list of arguments to be
|
||||
passed to <B><A HREF="../TkCmd/exec.htm">exec</A></B> to execute the executable file or shell builtin
|
||||
named by <I>cmd</I>. If not, it returns an empty string. This command
|
||||
examines the directories in the current search path (given by the PATH
|
||||
environment variable) in its search for an executable file named
|
||||
<I>cmd</I>. On Windows platforms, the search is expanded with the same
|
||||
directories and file extensions as used by <B><A HREF="../TkCmd/exec.htm">exec</A></B>. <B>Auto_exec</B>
|
||||
remembers information about previous searches in an array named
|
||||
<B>auto_execs</B>; this avoids the path search in future calls for the
|
||||
same <I>cmd</I>. The command <B>auto_reset</B> may be used to force
|
||||
<B>auto_execok</B> to forget its cached information.
|
||||
<P><DT><A NAME="M7"><B>auto_import </B><I>pattern</I></A><DD>
|
||||
<B>Auto_import</B> is invoked during <B>namespace import</B> to see if
|
||||
the imported commands specified by <I>pattern</I> reside in an
|
||||
autoloaded library. If so, the commands are loaded so that they will
|
||||
be available to the interpreter for creating the import links. If the
|
||||
commands do not reside in an autoloaded library, <B>auto_import</B>
|
||||
does nothing. The pattern matching is performed according to the
|
||||
matching rules of <B>namespace import</B>.
|
||||
<P><DT><A NAME="M8"><B>auto_load </B><I>cmd</I></A><DD>
|
||||
This command attempts to load the definition for a Tcl command named
|
||||
<I>cmd</I>. To do this, it searches an <I>auto-load path</I>, which is
|
||||
a list of one or more directories. The auto-load path is given by the
|
||||
global variable <B>$auto_path</B> if it exists. If there is no
|
||||
<B>$auto_path</B> variable, then the TCLLIBPATH environment variable is
|
||||
used, if it exists. Otherwise the auto-load path consists of just the
|
||||
Tcl library directory. Within each directory in the auto-load path
|
||||
there must be a file <B>tclIndex</B> that describes one or more
|
||||
commands defined in that directory and a script to evaluate to load
|
||||
each of the commands. The <B>tclIndex</B> file should be generated
|
||||
with the <B>auto_mkindex</B> command. If <I>cmd</I> is found in an
|
||||
index file, then the appropriate script is evaluated to create the
|
||||
command. The <B>auto_load</B> command returns 1 if <I>cmd</I> was
|
||||
successfully created. The command returns 0 if there was no index
|
||||
entry for <I>cmd</I> or if the script didn't actually define <I>cmd</I>
|
||||
(e.g. because index information is out of date). If an error occurs
|
||||
while processing the script, then that error is returned.
|
||||
<B>Auto_load</B> only reads the index information once and saves it in
|
||||
the array <B>auto_index</B>; future calls to <B>auto_load</B> check for
|
||||
<I>cmd</I> in the array rather than re-reading the index files. The
|
||||
cached index information may be deleted with the command
|
||||
<B>auto_reset</B>. This will force the next <B>auto_load</B> command to
|
||||
reload the index database from disk.
|
||||
<P><DT><A NAME="M9"><B>auto_mkindex </B><I>dir pattern pattern ...</I></A><DD>
|
||||
Generates an index suitable for use by <B>auto_load</B>. The command
|
||||
searches <I>dir</I> for all files whose names match any of the
|
||||
<I>pattern</I> arguments (matching is done with the <B><A HREF="../TkCmd/glob.htm">glob</A></B>
|
||||
command), generates an index of all the Tcl command procedures defined
|
||||
in all the matching files, and stores the index information in a file
|
||||
named <B>tclIndex</B> in <I>dir</I>. If no pattern is given a pattern of
|
||||
<B>*.tcl</B> will be assumed. For example, the command
|
||||
<PRE><B>auto_mkindex foo *.tcl</B></PRE>
|
||||
<P>
|
||||
will read all the <B>.tcl</B> files in subdirectory <B>foo</B> and
|
||||
generate a new index file <B>foo/tclIndex</B>.
|
||||
<P>
|
||||
<B>Auto_mkindex</B> parses the Tcl scripts by sourcing them into a
|
||||
slave interpreter and monitoring the proc and namespace commands that
|
||||
are executed. Extensions can use the (undocumented)
|
||||
auto_mkindex_parser package to register other commands that can
|
||||
contribute to the auto_load index. You will have to read through
|
||||
auto.tcl to see how this works.
|
||||
<P><B>Auto_mkindex_old</B> parses the Tcl scripts in a relatively
|
||||
unsophisticated way: if any line contains the word <B><A HREF="../TkCmd/proc.htm">proc</A></B>
|
||||
as its first characters then it is assumed to be a procedure
|
||||
definition and the next word of the line is taken as the
|
||||
procedure's name.
|
||||
Procedure definitions that don't appear in this way (e.g. they
|
||||
have spaces before the <B><A HREF="../TkCmd/proc.htm">proc</A></B>) will not be indexed. If your
|
||||
script contains "dangerous" code, such as global initialization
|
||||
code or procedure names with special characters like <B>$</B>,
|
||||
<B>*</B>, <B>[</B> or <B>]</B>, you are safer using auto_mkindex_old.
|
||||
<P><DT><A NAME="M10"><B>auto_reset</B></A><DD>
|
||||
Destroys all the information cached by <B>auto_execok</B> and
|
||||
<B>auto_load</B>. This information will be re-read from disk the next
|
||||
time it is needed. <B>Auto_reset</B> also deletes any procedures
|
||||
listed in the auto-load index, so that fresh copies of them will be
|
||||
loaded the next time that they're used.
|
||||
<P><DT><A NAME="M11"><B>auto_qualify </B><I>command namespace</I></A><DD>
|
||||
Computes a list of fully qualified names for <I>command</I>. This list
|
||||
mirrors the path a standard Tcl interpreter follows for command
|
||||
lookups: first it looks for the command in the current namespace, and
|
||||
then in the global namespace. Accordingly, if <I>command</I> is
|
||||
relative and <I>namespace</I> is not <B>::</B>, the list returned has
|
||||
two elements: <I>command</I> scoped by <I>namespace</I>, as if it were
|
||||
a command in the <I>namespace</I> namespace; and <I>command</I> as if it
|
||||
were a command in the global namespace. Otherwise, if either
|
||||
<I>command</I> is absolute (it begins with <B>::</B>), or
|
||||
<I>namespace</I> is <B>::</B>, the list contains only <I>command</I> as
|
||||
if it were a command in the global namespace.
|
||||
<P>
|
||||
<B>Auto_qualify</B> is used by the auto-loading facilities in Tcl, both
|
||||
for producing auto-loading indexes such as <I>pkgIndex.tcl</I>, and for
|
||||
performing the actual auto-loading of functions at runtime.
|
||||
<P><DT><A NAME="M12"><B>tcl_findLibrary </B><I>basename version patch initScript enVarName varName</I></A><DD>
|
||||
This is a standard search procedure for use by extensions during
|
||||
their initialization. They call this procedure to look for their
|
||||
script library in several standard directories.
|
||||
The last component of the name of the library directory is
|
||||
normally <I>basenameversion</I>
|
||||
(e.g., tk8.0), but it might be "library" when in the build hierarchies.
|
||||
The <I>initScript</I> file will be sourced into the interpreter
|
||||
once it is found. The directory in which this file is found is
|
||||
stored into the global variable <I>varName</I>.
|
||||
If this variable is already defined (e.g., by C code during
|
||||
application initialization) then no searching is done.
|
||||
Otherwise the search looks in these directories:
|
||||
the directory named by the environment variable <I>enVarName</I>;
|
||||
relative to the Tcl library directory;
|
||||
relative to the executable file in the standard installation
|
||||
bin or bin/<I>arch</I> directory;
|
||||
relative to the executable file in the current build tree;
|
||||
relative to the executable file in a parallel build tree.
|
||||
<P><DT><A NAME="M13"><B>parray </B><I>arrayName</I></A><DD>
|
||||
Prints on standard output the names and values of all the elements
|
||||
in the array <I>arrayName</I>.
|
||||
<B>ArrayName</B> must be an array accessible to the caller of <B>parray</B>.
|
||||
It may be either local or global.
|
||||
<P><DT><A NAME="M14"><B>tcl_endOfWord </B><I>str start</I></A><DD>
|
||||
Returns the index of the first end-of-word location that occurs after
|
||||
a starting index <I>start</I> in the string <I>str</I>. An end-of-word
|
||||
location is defined to be the first non-word character following the
|
||||
first word character after the starting point. Returns -1 if there
|
||||
are no more end-of-word locations after the starting point. See the
|
||||
description of <B>tcl_wordchars</B> and <B>tcl_nonwordchars</B> below
|
||||
for more details on how Tcl determines which characters are word
|
||||
characters.
|
||||
<P><DT><A NAME="M15"><B>tcl_startOfNextWord </B><I>str start</I></A><DD>
|
||||
Returns the index of the first start-of-word location that occurs
|
||||
after a starting index <I>start</I> in the string <I>str</I>. A
|
||||
start-of-word location is defined to be the first word character
|
||||
following a non-word character. Returns -1 if there are no more
|
||||
start-of-word locations after the starting point.
|
||||
<P><DT><A NAME="M16"><B>tcl_startOfPreviousWord </B><I>str start</I></A><DD>
|
||||
Returns the index of the first start-of-word location that occurs
|
||||
before a starting index <I>start</I> in the string <I>str</I>. Returns
|
||||
-1 if there are no more start-of-word locations before the starting
|
||||
point.
|
||||
<P><DT><A NAME="M17"><B>tcl_wordBreakAfter </B><I>str start</I></A><DD>
|
||||
Returns the index of the first word boundary after the starting index
|
||||
<I>start</I> in the string <I>str</I>. Returns -1 if there are no more
|
||||
boundaries after the starting point in the given string. The index
|
||||
returned refers to the second character of the pair that comprises a
|
||||
boundary.
|
||||
<P><DT><A NAME="M18"><B>tcl_wordBreakBefore </B><I>str start</I></A><DD>
|
||||
Returns the index of the first word boundary before the starting index
|
||||
<I>start</I> in the string <I>str</I>. Returns -1 if there are no more
|
||||
boundaries before the starting point in the given string. The index
|
||||
returned refers to the second character of the pair that comprises a
|
||||
boundary.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M19">VARIABLES</A></H3>
|
||||
The following global variables are defined or used by the procedures in
|
||||
the Tcl library:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M20"><B>auto_execs</B></A><DD>
|
||||
Used by <B>auto_execok</B> to record information about whether
|
||||
particular commands exist as executable files.
|
||||
<P><DT><A NAME="M21"><B>auto_index</B></A><DD>
|
||||
Used by <B>auto_load</B> to save the index information read from
|
||||
disk.
|
||||
<P><DT><A NAME="M22"><B>auto_noexec</B></A><DD>
|
||||
If set to any value, then <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> will not attempt to auto-exec
|
||||
any commands.
|
||||
<P><DT><A NAME="M23"><B>auto_noload</B></A><DD>
|
||||
If set to any value, then <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> will not attempt to auto-load
|
||||
any commands.
|
||||
<P><DT><A NAME="M24"><B>auto_path</B></A><DD>
|
||||
If set, then it must contain a valid Tcl list giving directories to
|
||||
search during auto-load operations.
|
||||
This variable is initialized during startup to contain, in order:
|
||||
the directories listed in the TCLLIBPATH environment variable,
|
||||
the directory named by the $tcl_library variable,
|
||||
the parent directory of $tcl_library,
|
||||
the directories listed in the $tcl_pkgPath variable.
|
||||
<P><DT><A NAME="M25"><B>env(TCL_LIBRARY)</B></A><DD>
|
||||
If set, then it specifies the location of the directory containing
|
||||
library scripts (the value of this variable will be
|
||||
assigned to the <B>tcl_library</B> variable and therefore returned by
|
||||
the command <B><A HREF="../TkCmd/info.htm">info library</A></B>). If this variable isn't set then
|
||||
a default value is used.
|
||||
<P><DT><A NAME="M26"><B>env(TCLLIBPATH)</B></A><DD>
|
||||
If set, then it must contain a valid Tcl list giving directories to
|
||||
search during auto-load operations. Directories must be specified in
|
||||
Tcl format, using "/" as the path separator, regardless of platform.
|
||||
This variable is only used when initializing the <B>auto_path</B> variable.
|
||||
<P><DT><A NAME="M27"><B>tcl_nonwordchars</B></A><DD>
|
||||
This variable contains a regular expression that is used by routines
|
||||
like <B>tcl_endOfWord</B> to identify whether a character is part of a
|
||||
word or not. If the pattern matches a character, the character is
|
||||
considered to be a non-word character. On Windows platforms, spaces,
|
||||
tabs, and newlines are considered non-word characters. Under Unix,
|
||||
everything but numbers, letters and underscores are considered
|
||||
non-word characters.
|
||||
<P><DT><A NAME="M28"><B>tcl_wordchars</B></A><DD>
|
||||
This variable contains a regular expression that is used by routines
|
||||
like <B>tcl_endOfWord</B> to identify whether a character is part of a
|
||||
word or not. If the pattern matches a character, the character is
|
||||
considered to be a word character. On Windows platforms, words are
|
||||
comprised of any character that is not a space, tab, or newline. Under
|
||||
Unix, words are comprised of numbers, letters or underscores.
|
||||
<P><DT><A NAME="M29"><B>unknown_pending</B></A><DD>
|
||||
Used by <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> to record the command(s) for which it is
|
||||
searching.
|
||||
It is used to detect errors where <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> recurses on itself
|
||||
infinitely.
|
||||
The variable is unset before <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> returns.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M30">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/info.htm">info</A></B>, <B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B>
|
||||
<H3><A NAME="M31">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#auto-exec">auto-exec</A>, <A href="../Keywords/A.htm#auto-load">auto-load</A>, <A href="../Keywords/L.htm#library">library</A>, <A href="../Keywords/U.htm#unknown">unknown</A>, <A href="../Keywords/W.htm#word">word</A>, <A href="../Keywords/W.htm#whitespace">whitespace</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1991-1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
28
hlp/en/tcl/lindex.htm
Normal file
28
hlp/en/tcl/lindex.htm
Normal file
@@ -0,0 +1,28 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - lindex manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
lindex - Retrieve an element from a list
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>lindex </B><I>list index</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command treats <I>list</I> as a Tcl list and returns the
|
||||
<I>index</I>'th element from it (0 refers to the first element of the list).
|
||||
In extracting the element, <I>lindex</I> observes the same rules
|
||||
concerning braces and quotes and backslashes as the Tcl command
|
||||
interpreter; however, variable
|
||||
substitution and command substitution do not occur.
|
||||
If <I>index</I> is negative or greater than or equal to the number
|
||||
of elements in <I>value</I>, then an empty
|
||||
string is returned.
|
||||
If <I>index</I> has the value <B>end</B>, it refers to the last element
|
||||
in the list, and <B>end-</B><I>integer</I> refers to the last element in
|
||||
the list minus the specified integer offset.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/list.htm">list</A></B>, <B><A HREF="../TkCmd/lappend.htm">lappend</A></B>, <B><A HREF="../TkCmd/linsert.htm">linsert</A></B>, <B><A HREF="../TkCmd/llength.htm">llength</A></B>, <B><A HREF="../TkCmd/lsearch.htm">lsearch</A></B>, <B><A HREF="../TkCmd/lsort.htm">lsort</A></B>, <B><A HREF="../TkCmd/lrange.htm">lrange</A></B>, <B><A HREF="../TkCmd/lreplace.htm">lreplace</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#element">element</A>, <A href="../Keywords/I.htm#index">index</A>, <A href="../Keywords/L.htm#list">list</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
25
hlp/en/tcl/linsert.htm
Normal file
25
hlp/en/tcl/linsert.htm
Normal file
@@ -0,0 +1,25 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - linsert manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
linsert - Insert elements into a list
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>linsert </B><I>list index element </I>?<I>element element ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command produces a new list from <I>list</I> by inserting all of the
|
||||
<I>element</I> arguments just before the <I>index</I>th element of
|
||||
<I>list</I>. Each <I>element</I> argument will become a separate element of
|
||||
the new list. If <I>index</I> is less than or equal to zero, then the new
|
||||
elements are inserted at the beginning of the list. If <I>index</I> has the
|
||||
value <B>end</B>, or if it is greater than or equal to the number of
|
||||
elements in the list, then the new elements are appended to the list.
|
||||
<B>end-</B><I>integer</I> refers to the last element in the list minus the
|
||||
specified integer offset.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/list.htm">list</A></B>, <B><A HREF="../TkCmd/lappend.htm">lappend</A></B>, <B><A HREF="../TkCmd/llength.htm">llength</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#element">element</A>, <A href="../Keywords/I.htm#insert">insert</A>, <A href="../Keywords/L.htm#list">list</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
30
hlp/en/tcl/list.htm
Normal file
30
hlp/en/tcl/list.htm
Normal file
@@ -0,0 +1,30 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - list manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
list - Create a list
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>list </B>?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command returns a list comprised of all the <I>arg</I>s,
|
||||
or an empty string if no <I>arg</I>s are specified.
|
||||
Braces and backslashes get added as necessary, so that the <B>index</B> command
|
||||
may be used on the result to re-extract the original arguments, and also
|
||||
so that <B><A HREF="../TkCmd/eval.htm">eval</A></B> may be used to execute the resulting list, with
|
||||
<I>arg1</I> comprising the command's name and the other <I>arg</I>s comprising
|
||||
its arguments. <B>List</B> produces slightly different results than
|
||||
<B><A HREF="../TkCmd/concat.htm">concat</A></B>: <B><A HREF="../TkCmd/concat.htm">concat</A></B> removes one level of grouping before forming
|
||||
the list, while <B>list</B> works directly from the original arguments.
|
||||
For example, the command
|
||||
<PRE><B>list a b {c d e} {f {g h}}</B></PRE>
|
||||
will return
|
||||
<PRE><B>a b {c d e} {f {g h}}</B></PRE>
|
||||
while <B><A HREF="../TkCmd/concat.htm">concat</A></B> with the same arguments will return
|
||||
<PRE><B>a b c d e f {g h}</B></PRE>
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/lappend.htm">lappend</A></B>, <B><A HREF="../TkCmd/lindex.htm">lindex</A></B>, <B><A HREF="../TkCmd/linsert.htm">linsert</A></B>, <B><A HREF="../TkCmd/llength.htm">llength</A></B>, <B><A HREF="../TkCmd/lsearch.htm">lsearch</A></B>, <B><A HREF="../TkCmd/lsort.htm">lsort</A></B>, <B><A HREF="../TkCmd/lrange.htm">lrange</A></B>, <B><A HREF="../TkCmd/lreplace.htm">lreplace</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#element">element</A>, <A href="../Keywords/L.htm#list">list</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
18
hlp/en/tcl/llength.htm
Normal file
18
hlp/en/tcl/llength.htm
Normal file
@@ -0,0 +1,18 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - llength manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
llength - Count the number of elements in a list
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>llength </B><I>list</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Treats <I>list</I> as a list and returns a decimal string giving
|
||||
the number of elements in it.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/list.htm">list</A></B>, <B><A HREF="../TkCmd/lindex.htm">lindex</A></B>, <B><A HREF="../TkCmd/lrange.htm">lrange</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#element">element</A>, <A href="../Keywords/L.htm#list">list</A>, <A href="../Keywords/L.htm#length">length</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
130
hlp/en/tcl/load.htm
Normal file
130
hlp/en/tcl/load.htm
Normal file
@@ -0,0 +1,130 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - load manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="load.htm#M2" NAME="L663">NAME</A>
|
||||
<DL><DD>load - Load machine code and initialize new commands.</DL>
|
||||
<DD><A HREF="load.htm#M3" NAME="L664">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>load </B><I>fileName</I>
|
||||
<DD><B>load </B><I>fileName packageName</I>
|
||||
<DD><B>load </B><I>fileName packageName interp</I>
|
||||
</DL>
|
||||
<DD><A HREF="load.htm#M4" NAME="L665">DESCRIPTION</A>
|
||||
<DD><A HREF="load.htm#M5" NAME="L666">PORTABILITY ISSUES</A>
|
||||
<DL>
|
||||
<DD><A HREF="load.htm#M6" NAME="L667"><B>Windows</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="load.htm#M7" NAME="L668">BUGS</A>
|
||||
<DD><A HREF="load.htm#M8" NAME="L669">SEE ALSO</A>
|
||||
<DD><A HREF="load.htm#M9" NAME="L670">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
load - Load machine code and initialize new commands.
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>load </B><I>fileName</I><BR>
|
||||
<B>load </B><I>fileName packageName</I><BR>
|
||||
<B>load </B><I>fileName packageName interp</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command loads binary code from a file into the
|
||||
application's address space and calls an initialization procedure
|
||||
in the package to incorporate it into an interpreter. <I>fileName</I>
|
||||
is the name of the file containing the code; its exact form varies
|
||||
from system to system but on most systems it is a shared library,
|
||||
such as a <B>.so</B> file under Solaris or a DLL under Windows.
|
||||
<I>packageName</I> is the name of the package, and is used to
|
||||
compute the name of an initialization procedure.
|
||||
<I>interp</I> is the path name of the interpreter into which to load
|
||||
the package (see the <B><A HREF="../TkCmd/interp.htm">interp</A></B> manual entry for details);
|
||||
if <I>interp</I> is omitted, it defaults to the
|
||||
interpreter in which the <B>load</B> command was invoked.
|
||||
<P>
|
||||
Once the file has been loaded into the application's address space,
|
||||
one of two initialization procedures will be invoked in the new code.
|
||||
Typically the initialization procedure will add new commands to a
|
||||
Tcl interpreter.
|
||||
The name of the initialization procedure is determined by
|
||||
<I>packageName</I> and whether or not the target interpreter
|
||||
is a safe one. For normal interpreters the name of the initialization
|
||||
procedure will have the form <I>pkg</I><B>_Init</B>, where <I>pkg</I>
|
||||
is the same as <I>packageName</I> except that the first letter is
|
||||
converted to upper case and all other letters
|
||||
are converted to lower case. For example, if <I>packageName</I> is
|
||||
<B>foo</B> or <B>FOo</B>, the initialization procedure's name will
|
||||
be <B>Foo_Init</B>.
|
||||
<P>
|
||||
If the target interpreter is a safe interpreter, then the name
|
||||
of the initialization procedure will be <I>pkg</I><B>_SafeInit</B>
|
||||
instead of <I>pkg</I><B>_Init</B>.
|
||||
The <I>pkg</I><B>_SafeInit</B> function should be written carefully, so that it
|
||||
initializes the safe interpreter only with partial functionality provided
|
||||
by the package that is safe for use by untrusted code. For more information
|
||||
on Safe-Tcl, see the <B>safe</B> manual entry.
|
||||
<P>
|
||||
The initialization procedure must match the following prototype:
|
||||
<PRE>typedef int Tcl_PackageInitProc(<A HREF="../TkLib/Interp.htm">Tcl_Interp</A> *<I>interp</I>);</PRE>
|
||||
The <I>interp</I> argument identifies the interpreter in which the
|
||||
package is to be loaded. The initialization procedure must return
|
||||
<B>TCL_OK</B> or <B>TCL_ERROR</B> to indicate whether or not it completed
|
||||
successfully; in the event of an error it should set the interpreter's result
|
||||
to point to an error message. The result of the <B>load</B> command
|
||||
will be the result returned by the initialization procedure.
|
||||
<P>
|
||||
The actual loading of a file will only be done once for each <I>fileName</I>
|
||||
in an application. If a given <I>fileName</I> is loaded into multiple
|
||||
interpreters, then the first <B>load</B> will load the code and
|
||||
call the initialization procedure; subsequent <B>load</B>s will
|
||||
call the initialization procedure without loading the code again.
|
||||
It is not possible to unload or reload a package.
|
||||
<P>
|
||||
The <B>load</B> command also supports packages that are statically
|
||||
linked with the application, if those packages have been registered
|
||||
by calling the <B><A HREF="../TkLib/StaticPkg.htm">Tcl_StaticPackage</A></B> procedure.
|
||||
If <I>fileName</I> is an empty string, then <I>packageName</I> must
|
||||
be specified.
|
||||
<P>
|
||||
If <I>packageName</I> is omitted or specified as an empty string,
|
||||
Tcl tries to guess the name of the package.
|
||||
This may be done differently on different platforms.
|
||||
The default guess, which is used on most UNIX platforms, is to
|
||||
take the last element of <I>fileName</I>, strip off the first
|
||||
three characters if they are <B>lib</B>, and use any following
|
||||
alphabetic and underline characters as the module name.
|
||||
For example, the command <B>load libxyz4.2.so</B> uses the module
|
||||
name <B>xyz</B> and the command <B>load bin/last.so {}</B> uses the
|
||||
module name <B>last</B>.
|
||||
<P>
|
||||
If <I>fileName</I> is an empty string, then <I>packageName</I> must
|
||||
be specified.
|
||||
The <B>load</B> command first searches for a statically loaded package
|
||||
(one that has been registered by calling the <B><A HREF="../TkLib/StaticPkg.htm">Tcl_StaticPackage</A></B>
|
||||
procedure) by that name; if one is found, it is used.
|
||||
Otherwise, the <B>load</B> command searches for a dynamically loaded
|
||||
package by that name, and uses it if it is found. If several
|
||||
different files have been <B>load</B>ed with different versions of
|
||||
the package, Tcl picks the file that was loaded first.
|
||||
|
||||
<H3><A NAME="M5">PORTABILITY ISSUES</A></H3>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>Windows</B></A><DD>
|
||||
When a load fails with "library not found" error, it is also possible
|
||||
that a dependent library was not found. To see the dependent libraries,
|
||||
type ``dumpbin -imports <dllname>'' in a DOS console to see what the
|
||||
library must import.
|
||||
When loading a DLL in the current directory, Windows will ignore ``./'' as
|
||||
a path specifier and use a search heuristic to find the DLL instead.
|
||||
To avoid this, load the DLL with
|
||||
<PRE>load [file join [pwd] mylib.DLL]</PRE>
|
||||
<P></DL>
|
||||
<H3><A NAME="M7">BUGS</A></H3>
|
||||
If the same file is <B>load</B>ed by different <I>fileName</I>s, it will
|
||||
be loaded into the process's address space multiple times. The
|
||||
behavior of this varies from system to system (some systems may
|
||||
detect the redundant loads, others may not).
|
||||
|
||||
<H3><A NAME="M8">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/info.htm">info sharedlibextension</A></B>, <B><A HREF="../TkLib/StaticPkg.htm">Tcl_StaticPackage</A></B>, <B>safe</B>
|
||||
<H3><A NAME="M9">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#binary code">binary code</A>, <A href="../Keywords/L.htm#loading">loading</A>, <A href="../Keywords/S.htm#safe interpreter">safe interpreter</A>, <A href="../Keywords/S.htm#shared library">shared library</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
31
hlp/en/tcl/lrange.htm
Normal file
31
hlp/en/tcl/lrange.htm
Normal file
@@ -0,0 +1,31 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - lrange manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
lrange - Return one or more adjacent elements from a list
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>lrange </B><I>list first last</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
<I>List</I> must be a valid Tcl list. This command will
|
||||
return a new list consisting of elements
|
||||
<I>first</I> through <I>last</I>, inclusive.
|
||||
<I>First</I> or <I>last</I>
|
||||
may be <B>end</B> (or any abbreviation of it) to refer to the last
|
||||
element of the list.
|
||||
If <I>first</I> is less than zero, it is treated as if it were zero.
|
||||
If <I>last</I> is greater than or equal to the number of elements
|
||||
in the list, then it is treated as if it were <B>end</B>.
|
||||
If <I>first</I> is greater than <I>last</I> then an empty string
|
||||
is returned.
|
||||
Note: ``<B>lrange </B><I>list first first</I>'' does not always produce the
|
||||
same result as ``<B>lindex </B><I>list first</I>'' (although it often does
|
||||
for simple fields that aren't enclosed in braces); it does, however,
|
||||
produce exactly the same results as ``<B>list [lindex </B><I>list first</I><B>]</B>''
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/lappend.htm">lappend</A></B>, <B><A HREF="../TkCmd/lindex.htm">lindex</A></B>, <B><A HREF="../TkCmd/linsert.htm">linsert</A></B>, <B><A HREF="../TkCmd/list.htm">list</A></B>, <B><A HREF="../TkCmd/llength.htm">llength</A></B>, <B><A HREF="../TkCmd/lreplace.htm">lreplace</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#element">element</A>, <A href="../Keywords/L.htm#list">list</A>, <A href="../Keywords/R.htm#range">range</A>, <A href="../Keywords/S.htm#sublist">sublist</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
39
hlp/en/tcl/lreplace.htm
Normal file
39
hlp/en/tcl/lreplace.htm
Normal file
@@ -0,0 +1,39 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - lreplace manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
lreplace - Replace elements in a list with new elements
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>lreplace </B><I>list first last </I>?<I>element element ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
<B>lreplace</B> returns a new list formed by replacing one or more elements of
|
||||
<I>list</I> with the <I>element</I> arguments.
|
||||
<I>first</I> and <I>last</I> specify the first and last index of the
|
||||
range of elements to replace. 0 refers to the first element of the
|
||||
list, and <B>end</B> (or any abbreviation of it) may be used to refer
|
||||
to the last element of the list. If <I>list</I> is empty, then
|
||||
<I>first</I> and <I>last</I> are ignored.
|
||||
|
||||
If <I>first</I> is less than zero, it is considered to refer to the
|
||||
first element of the list. For non-empty lists, the element indicated
|
||||
by <I>first</I> must exist.
|
||||
|
||||
If <I>last</I> is less than zero but greater than <I>first</I>, then any
|
||||
specified elements will be prepended to the list. If <I>last</I> is
|
||||
less than <I>first</I> then no elements are deleted; the new elements
|
||||
are simply inserted before <I>first</I>.
|
||||
|
||||
The <I>element</I> arguments specify zero or more new arguments to
|
||||
be added to the list in place of those that were deleted.
|
||||
Each <I>element</I> argument will become a separate element of
|
||||
the list. If no <I>element</I> arguments are specified, then the elements
|
||||
between <I>first</I> and <I>last</I> are simply deleted. If <I>list</I>
|
||||
is empty, any <I>element</I> arguments are added to the end of the list.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/lappend.htm">lappend</A></B>, <B><A HREF="../TkCmd/lindex.htm">lindex</A></B>, <B><A HREF="../TkCmd/linsert.htm">linsert</A></B>, <B><A HREF="../TkCmd/list.htm">list</A></B>, <B><A HREF="../TkCmd/llength.htm">llength</A></B>, <B><A HREF="../TkCmd/lrange.htm">lrange</A></B>, <B><A HREF="../TkCmd/lsearch.htm">lsearch</A></B>, <B><A HREF="../TkCmd/lsort.htm">lsort</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#element">element</A>, <A href="../Keywords/L.htm#list">list</A>, <A href="../Keywords/R.htm#replace">replace</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
36
hlp/en/tcl/lsearch.htm
Normal file
36
hlp/en/tcl/lsearch.htm
Normal file
@@ -0,0 +1,36 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - lsearch manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
lsearch - See if a list contains a particular element
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>lsearch </B>?<I>mode</I>? <I>list pattern</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command searches the elements of <I>list</I> to see if one
|
||||
of them matches <I>pattern</I>.
|
||||
If so, the command returns the index of the first matching
|
||||
element.
|
||||
If not, the command returns <B>-1</B>.
|
||||
The <I>mode</I> argument indicates how the elements of the list are to
|
||||
be matched against <I>pattern</I> and it must have one of the following
|
||||
values:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>-exact</B></A><DD>
|
||||
The list element must contain exactly the same string as <I>pattern</I>.
|
||||
<P><DT><A NAME="M6"><B>-glob</B></A><DD>
|
||||
<I>Pattern</I> is a glob-style pattern which is matched against each list
|
||||
element using the same rules as the <B><A HREF="../TkCmd/string.htm">string match</A></B> command.
|
||||
<P><DT><A NAME="M7"><B>-regexp</B></A><DD>
|
||||
<I>Pattern</I> is treated as a regular expression and matched against
|
||||
each list element using the rules described in the <B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B>
|
||||
reference page.
|
||||
<P></DL>
|
||||
<P>
|
||||
If <I>mode</I> is omitted then it defaults to <B>-glob</B>.
|
||||
|
||||
<H3><A NAME="M8">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/L.htm#list">list</A>, <A href="../Keywords/M.htm#match">match</A>, <A href="../Keywords/P.htm#pattern">pattern</A>, <A href="../Keywords/R.htm#regular expression">regular expression</A>, <A href="../Keywords/S.htm#search">search</A>, <A href="../Keywords/S.htm#string">string</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
160
hlp/en/tcl/lsort.htm
Normal file
160
hlp/en/tcl/lsort.htm
Normal file
@@ -0,0 +1,160 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - lsort manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="lsort.htm#M2" NAME="L688">NAME</A>
|
||||
<DL><DD>lsort - Sort the elements of a list</DL>
|
||||
<DD><A HREF="lsort.htm#M3" NAME="L689">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>lsort </B>?<I>options</I>? <I>list</I>
|
||||
</DL>
|
||||
<DD><A HREF="lsort.htm#M4" NAME="L690">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="lsort.htm#M5" NAME="L691"><B>-ascii</B></A>
|
||||
<DD><A HREF="lsort.htm#M6" NAME="L692"><B>-dictionary</B></A>
|
||||
<DD><A HREF="lsort.htm#M7" NAME="L693"><B>-integer</B></A>
|
||||
<DD><A HREF="lsort.htm#M8" NAME="L694"><B>-real</B></A>
|
||||
<DD><A HREF="lsort.htm#M9" NAME="L695"><B>-command </B><I>command</I></A>
|
||||
<DD><A HREF="lsort.htm#M10" NAME="L696"><B>-increasing</B></A>
|
||||
<DD><A HREF="lsort.htm#M11" NAME="L697"><B>-decreasing</B></A>
|
||||
<DD><A HREF="lsort.htm#M12" NAME="L698"><B>-index </B><I>index</I></A>
|
||||
<DD><A HREF="lsort.htm#M13" NAME="L699"><B>-unique</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="lsort.htm#M14" NAME="L700">NOTES</A>
|
||||
<DD><A HREF="lsort.htm#M15" NAME="L701">EXAMPLES</A>
|
||||
<DD><A HREF="lsort.htm#M16" NAME="L702">SEE ALSO</A>
|
||||
<DD><A HREF="lsort.htm#M17" NAME="L703">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
lsort - Sort the elements of a list
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>lsort </B>?<I>options</I>? <I>list</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command sorts the elements of <I>list</I>, returning a new
|
||||
list in sorted order. The implementation of the <B>lsort</B> command
|
||||
uses the merge-sort algorithm which is a stable sort that has O(n log
|
||||
n) performance characteristics.
|
||||
<P>
|
||||
By default ASCII sorting is used with the result returned in
|
||||
increasing order. However, any of the following options may be
|
||||
specified before <I>list</I> to control the sorting process (unique
|
||||
abbreviations are accepted):
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>-ascii</B></A><DD>
|
||||
Use string comparison with ASCII collation order. This is the default.
|
||||
<P><DT><A NAME="M6"><B>-dictionary</B></A><DD>
|
||||
Use dictionary-style comparison. This is the same as <B>-ascii</B>
|
||||
except (a) case is ignored except as a tie-breaker and (b) if two
|
||||
strings contain embedded numbers, the numbers compare as integers,
|
||||
not characters. For example, in <B>-dictionary</B> mode, <B>bigBoy</B>
|
||||
sorts between <B>bigbang</B> and <B>bigboy</B>, and <B>x10y</B>
|
||||
sorts between <B>x9y</B> and <B>x11y</B>.
|
||||
<P><DT><A NAME="M7"><B>-integer</B></A><DD>
|
||||
Convert list elements to integers and use integer comparison.
|
||||
<P><DT><A NAME="M8"><B>-real</B></A><DD>
|
||||
Convert list elements to floating-point values and use floating comparison.
|
||||
<P><DT><A NAME="M9"><B>-command </B><I>command</I></A><DD>
|
||||
Use <I>command</I> as a comparison command.
|
||||
To compare two elements, evaluate a Tcl script consisting of
|
||||
<I>command</I> with the two elements appended as additional
|
||||
arguments. The script should return an integer less than,
|
||||
equal to, or greater than zero if the first element is to
|
||||
be considered less than, equal to, or greater than the second,
|
||||
respectively.
|
||||
<P><DT><A NAME="M10"><B>-increasing</B></A><DD>
|
||||
Sort the list in increasing order (``smallest'' items first).
|
||||
This is the default.
|
||||
<P><DT><A NAME="M11"><B>-decreasing</B></A><DD>
|
||||
Sort the list in decreasing order (``largest'' items first).
|
||||
<P><DT><A NAME="M12"><B>-index </B><I>index</I></A><DD>
|
||||
If this option is specified, each of the elements of <I>list</I> must
|
||||
itself be a proper Tcl sublist. Instead of sorting based on whole
|
||||
sublists, <B>lsort</B> will extract the <I>index</I>'th element from
|
||||
each sublist and sort based on the given element. The keyword
|
||||
<B>end</B> is allowed for the <I>index</I> to sort on the last sublist
|
||||
element,
|
||||
and <B>end-</B><I>index</I> sorts on a sublist element offset from
|
||||
the end.
|
||||
For example,
|
||||
<PRE>lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}</PRE>
|
||||
returns <B>{Second 18} {First 24} {Third 30}</B>, and
|
||||
<PRE>lsort -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}</PRE>
|
||||
returns <B>{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}</B>.
|
||||
This option is much more efficient than using <B>-command</B>
|
||||
to achieve the same effect.
|
||||
<P><DT><A NAME="M13"><B>-unique</B></A><DD>
|
||||
If this option is specified, then only the last set of duplicate
|
||||
elements found in the list will be retained. Note that duplicates are
|
||||
determined relative to the comparison used in the sort. Thus if
|
||||
<I>-index 0</I> is used, <B>{1 a}</B> and <B>{1 b}</B> would be
|
||||
considered duplicates and only the second element, <B>{1 b}</B>, would
|
||||
be retained.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M14">NOTES</A></H3>
|
||||
The options to <B>lsort</B> only control what sort of comparison is
|
||||
used, and do not necessarily constrain what the values themselves
|
||||
actually are. This distinction is only noticeable when the list to be
|
||||
sorted has fewer than two elements.
|
||||
<P>
|
||||
The <B>lsort</B> command is reentrant, meaning it is safe to use as
|
||||
part of the implementation of a command used in the <B>-command</B>
|
||||
option.
|
||||
|
||||
<H3><A NAME="M15">EXAMPLES</A></H3>
|
||||
Sorting a list using ASCII sorting:
|
||||
<PRE>% lsort {a10 B2 b1 a1 a2}
|
||||
B2 a1 a10 a2 b1</PRE>
|
||||
<P>
|
||||
Sorting a list using Dictionary sorting:
|
||||
<PRE>% lsort -dictionary {a10 B2 b1 a1 a2}
|
||||
a1 a2 a10 b1 B2</PRE>
|
||||
<P>
|
||||
Sorting lists of integers:
|
||||
<PRE>% lsort -integer {5 3 1 2 11 4}
|
||||
1 2 3 4 5 11
|
||||
% lsort -integer {1 2 0x5 7 0 4 -1}
|
||||
-1 0 1 2 4 0x5 7</PRE>
|
||||
<P>
|
||||
Sorting lists of floating-point numbers:
|
||||
<PRE>% lsort -real {5 3 1 2 11 4}
|
||||
1 2 3 4 5 11
|
||||
% lsort -real {.5 0.07e1 0.4 6e-1}
|
||||
0.4 .5 6e-1 0.07e1</PRE>
|
||||
<P>
|
||||
Sorting using indices:
|
||||
<PRE>% # Note the space character before the c
|
||||
% lsort {{a 5} { c 3} {b 4} {e 1} {d 2}}
|
||||
{ c 3} {a 5} {b 4} {d 2} {e 1}
|
||||
% lsort -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
|
||||
{a 5} {b 4} { c 3} {d 2} {e 1}
|
||||
% lsort -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
|
||||
{e 1} {d 2} { c 3} {b 4} {a 5}</PRE>
|
||||
<P>
|
||||
Stripping duplicate values using sorting:
|
||||
<PRE>% lsort -unique {a b c a b c a b c}
|
||||
a b c</PRE>
|
||||
<P>
|
||||
More complex sorting using a comparison function:
|
||||
<PRE>% proc compare {a b} {
|
||||
set a0 [lindex $a 0]
|
||||
set b0 [lindex $b 0]
|
||||
if {$a0 < $b0} {
|
||||
return -1
|
||||
} elseif {$a0 > $b0} {
|
||||
return 1
|
||||
}
|
||||
return [string compare [lindex $a 1] [lindex $b 1]]
|
||||
}
|
||||
% lsort -command compare \
|
||||
{{3 apple} {0x2 carrot} {1 dingo} {2 banana}}
|
||||
{1 dingo} {2 banana} {0x2 carrot} {3 apple}</PRE>
|
||||
<H3><A NAME="M16">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/lappend.htm">lappend</A></B>, <B><A HREF="../TkCmd/lindex.htm">lindex</A></B>, <B><A HREF="../TkCmd/linsert.htm">linsert</A></B>, <B><A HREF="../TkCmd/list.htm">list</A></B>, <B><A HREF="../TkCmd/llength.htm">llength</A></B>, <B><A HREF="../TkCmd/lrange.htm">lrange</A></B>, <B><A HREF="../TkCmd/lreplace.htm">lreplace</A></B>, <B><A HREF="../TkCmd/lsearch.htm">lsearch</A></B>
|
||||
<H3><A NAME="M17">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#element">element</A>, <A href="../Keywords/L.htm#list">list</A>, <A href="../Keywords/O.htm#order">order</A>, <A href="../Keywords/S.htm#sort">sort</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1999 Scriptics Corporation
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
89
hlp/en/tcl/memory.htm
Normal file
89
hlp/en/tcl/memory.htm
Normal file
@@ -0,0 +1,89 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - memory manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="memory.htm#M2" NAME="L704">NAME</A>
|
||||
<DL><DD>memory - Control Tcl memory debugging capabilities.</DL>
|
||||
<DD><A HREF="memory.htm#M3" NAME="L705">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>memory </B><I>option </I>?<I>arg arg ...</I>?
|
||||
<DD>
|
||||
</DL>
|
||||
<DD><A HREF="memory.htm#M4" NAME="L706">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="memory.htm#M5" NAME="L707"><B>memory info</B></A>
|
||||
<DD><A HREF="memory.htm#M6" NAME="L708"><B>memory trace [on|off]</B></A>
|
||||
<DD><A HREF="memory.htm#M7" NAME="L709"><B>memory validate [on|off]</B></A>
|
||||
<DD><A HREF="memory.htm#M8" NAME="L710"><B>memory trace_on_at_malloc</B> <I>count</I></A>
|
||||
<DD><A HREF="memory.htm#M9" NAME="L711"><B>memory break_on_malloc</B> <I>count</I></A>
|
||||
<DD><A HREF="memory.htm#M10" NAME="L712"><B> memory display</B> <I>file</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="memory.htm#M11" NAME="L713">SEE ALSO</A>
|
||||
<DD><A HREF="memory.htm#M12" NAME="L714">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
memory - Control Tcl memory debugging capabilities.
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>memory </B><I>option </I>?<I>arg arg ...</I>?<BR>
|
||||
<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>memory</B> command gives the Tcl developer control of Tcl's memory
|
||||
debugging capabilities. The memory command has several suboptions, which are
|
||||
described below. It is only available when Tcl has been compiled with
|
||||
memory debugging enabled (when <B>TCL_MEM_DEBUG</B> is defined at
|
||||
compile time).
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>memory info</B></A><DD>
|
||||
Produces a report containing the total allocations and frees since
|
||||
Tcl began, the current packets allocated (the current
|
||||
number of calls to <B>ckalloc</B> not met by a corresponding call
|
||||
to <B>ckfree</B>), the current bytes allocated, and the maximum number
|
||||
of packets and bytes allocated.
|
||||
<P><DT><A NAME="M6"><B>memory trace [on|off]</B></A><DD>
|
||||
<BR>
|
||||
Turns memory tracing on or off. When memory tracing is on, every call
|
||||
to <B>ckalloc</B> causes a line of trace information to be written to
|
||||
<I>stderr</I>, consisting of the word <I>ckalloc</I>, followed by the
|
||||
address returned, the amount of memory allocated, and the C filename
|
||||
and line number of the code performing the allocation. For example:
|
||||
<PRE>ckalloc 40e478 98 tclProc.c 1406</PRE>
|
||||
Calls to <B>ckfree</B> are traced in the same manner.
|
||||
<P><DT><A NAME="M7"><B>memory validate [on|off]</B></A><DD>
|
||||
Turns memory validation on or off. When memory validation is enabled,
|
||||
on every call to <B>ckalloc</B> or <B>ckfree</B>, the guard zones are
|
||||
checked for every piece of memory currently in existence that was
|
||||
allocated by <B>ckalloc</B>. This has a large performance impact and
|
||||
should only be used when overwrite problems are strongly suspected.
|
||||
The advantage of enabling memory validation is that a guard zone
|
||||
overwrite can be detected on the first call to <B>ckalloc</B> or
|
||||
<B>ckfree</B> after the overwrite occurred, rather than when the
|
||||
specific memory with the overwritten guard zone(s) is freed, which may
|
||||
occur long after the overwrite occurred.
|
||||
<P><DT><A NAME="M8"><B>memory trace_on_at_malloc</B> <I>count</I></A><DD>
|
||||
Enable memory tracing after <I>count</I> <B>ckalloc</B>'s have been performed.
|
||||
For example, if you enter <B>memory trace_on_at_malloc 100</B>,
|
||||
after the 100th call to <B>ckalloc</B>, memory trace information will begin
|
||||
being displayed for all allocations and frees. Since there can be a lot
|
||||
of memory activity before a problem occurs, judicious use of this option
|
||||
can reduce the slowdown caused by tracing (and the amount of trace information
|
||||
produced), if you can identify a number of allocations that occur before
|
||||
the problem sets in. The current number of memory allocations that have
|
||||
occurred since Tcl started is printed on a guard zone failure.
|
||||
<P><DT><A NAME="M9"><B>memory break_on_malloc</B> <I>count</I></A><DD>
|
||||
After the <B>count</B> allocations have been performed, <B>ckalloc</B>'s
|
||||
output a message to this effect and that it is now attempting to enter
|
||||
the C debugger. Tcl will then issue a <I>SIGINT</I> signal against itself.
|
||||
If you are running Tcl under a C debugger, it should then enter the debugger
|
||||
command mode.
|
||||
<P><DT><A NAME="M10"><B> memory display</B> <I>file</I></A><DD>
|
||||
Write a list of all currently allocated memory to the specified file.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M11">SEE ALSO</A></H3>
|
||||
<B>ckalloc</B>, <B>ckfree</B>, <B><A HREF="../TkLib/DumpActiveMemory.htm">Tcl_ValidateAllMemory</A></B>, <B><A HREF="../TkLib/DumpActiveMemory.htm">Tcl_DumpActiveMemory</A></B>, <B>TCL_MEM_DEBUG</B>
|
||||
<H3><A NAME="M12">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/M.htm#memory">memory</A>, <A href="../Keywords/D.htm#debug">debug</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1992-1999 by Karl Lehenbauer and Mark Diekhans
|
||||
<A HREF="../copyright.htm">Copyright</A> © 2000 by Scriptics Corporation.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
244
hlp/en/tcl/msgcat.htm
Normal file
244
hlp/en/tcl/msgcat.htm
Normal file
@@ -0,0 +1,244 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - msgcat manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="msgcat.htm#M2" NAME="L715">NAME</A>
|
||||
<DL><DD>msgcat - Tcl message catalog</DL>
|
||||
<DD><A HREF="msgcat.htm#M3" NAME="L716">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>::msgcat::mc </B><I>src-string</I>
|
||||
<DD><B>::msgcat::mclocale </B>?<I>newLocale</I>?
|
||||
<DD><B>::msgcat::mcpreferences</B>
|
||||
<DD><B>::msgcat::mcload </B><I>dirname</I>
|
||||
<DD><B>::msgcat::mcset </B><I>locale src-string </I>?<I>translate-string</I>?
|
||||
<DD><B>::msgcat::mcunknown </B><I>locale src-string</I>
|
||||
</DL>
|
||||
<DD><A HREF="msgcat.htm#M4" NAME="L717">DESCRIPTION</A>
|
||||
<DD><A HREF="msgcat.htm#M5" NAME="L718">COMMANDS</A>
|
||||
<DL>
|
||||
<DD><A HREF="msgcat.htm#M6" NAME="L719"><B>::msgcat::mc </B><I>src-string</I> ?<I>arg arg ...</I>?</A>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="msgcat.htm#M7" NAME="L720"><B>::msgcat::mclocale </B>?<I>newLocale</I>?</A>
|
||||
<DD><A HREF="msgcat.htm#M8" NAME="L721"><B>::msgcat::mcpreferences</B></A>
|
||||
<DD><A HREF="msgcat.htm#M9" NAME="L722"><B>::msgcat::mcload </B><I>dirname</I></A>
|
||||
<DD><A HREF="msgcat.htm#M10" NAME="L723"><B>::msgcat::mcset </B><I>locale src-string </I>?<I>translate-string</I>?</A>
|
||||
<DD><A HREF="msgcat.htm#M11" NAME="L724"><B>::msgcat::mcunknown </B><I>locale src-string</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="msgcat.htm#M12" NAME="L725">LOCALE AND SUBLOCALE SPECIFICATION</A>
|
||||
<DD><A HREF="msgcat.htm#M13" NAME="L726">NAMESPACES AND MESSAGE CATALOGS</A>
|
||||
<DD><A HREF="msgcat.htm#M14" NAME="L727">LOCATION AND FORMAT OF MESSAGE FILES</A>
|
||||
<DL>
|
||||
</DL>
|
||||
<DD><A HREF="msgcat.htm#M15" NAME="L728">RECOMMENDED MESSAGE SETUP FOR PACKAGES</A>
|
||||
<DL>
|
||||
</DL>
|
||||
<DD><A HREF="msgcat.htm#M16" NAME="L729">POSTITIONAL CODES FOR FORMAT AND SCAN COMMANDS</A>
|
||||
<DD><A HREF="msgcat.htm#M17" NAME="L730">CREDITS</A>
|
||||
<DD><A HREF="msgcat.htm#M18" NAME="L731">SEE ALSO</A>
|
||||
<DD><A HREF="msgcat.htm#M19" NAME="L732">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
msgcat - Tcl message catalog
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>::msgcat::mc </B><I>src-string</I><BR>
|
||||
<B>::msgcat::mclocale </B>?<I>newLocale</I>?<BR>
|
||||
<B>::msgcat::mcpreferences</B><BR>
|
||||
<B>::msgcat::mcload </B><I>dirname</I><BR>
|
||||
<B>::msgcat::mcset </B><I>locale src-string </I>?<I>translate-string</I>?<BR>
|
||||
<B>::msgcat::mcunknown </B><I>locale src-string</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>msgcat</B> package provides a set of functions
|
||||
that can be used to manage multi-lingual user interfaces.
|
||||
Text strings are defined in a ``message catalog'' which
|
||||
is independent from the application, and
|
||||
which can be edited or localized without modifying
|
||||
the application source code. New languages
|
||||
or locales are provided by adding a new file to
|
||||
the message catalog.
|
||||
<P>
|
||||
Use of the message catalog is optional by any application
|
||||
or package, but is encouraged if the application or package
|
||||
wishes to be enabled for multi-lingual applications.
|
||||
|
||||
<H3><A NAME="M5">COMMANDS</A></H3>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>::msgcat::mc </B><I>src-string</I> ?<I>arg arg ...</I>?</A><DD>
|
||||
Returns a translation of <I>src-string</I> according to the
|
||||
user's current locale. If additional arguments past <I>src-string</I>
|
||||
are given, the <B><A HREF="../TkCmd/format.htm">format</A></B> command is used to substitute the
|
||||
additional arguments in the translation of <I>src-string</I>.
|
||||
|
||||
<B>::msgcat::mc</B> will search the messages defined
|
||||
in the current namespace for a translation of <I>src-string</I>; if
|
||||
none is found, it will search in the parent of the current namespace,
|
||||
and so on until it reaches the global namespace. If no translation
|
||||
string exists, <B>::msgcat::mcunknown</B> is called and the string
|
||||
returned from <B>::msgcat::mcunknown</B> is returned.
|
||||
<P></DL>
|
||||
<P>
|
||||
<B>::msgcat::mc</B> is the main function used to localize an
|
||||
application. Instead of using an English string directly, an
|
||||
applicaton can pass the English string through <B>::msgcat::mc</B> and
|
||||
use the result. If an application is written for a single language in
|
||||
this fashion, then it is easy to add support for additional languages
|
||||
later simply by defining new message catalog entries.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M7"><B>::msgcat::mclocale </B>?<I>newLocale</I>?</A><DD>
|
||||
This function sets the locale to <I>newLocale</I>. If <I>newLocale</I>
|
||||
is omitted, the current locale is returned, otherwise the current locale
|
||||
is set to <I>newLocale</I>.
|
||||
The initial locale defaults to the locale specified in
|
||||
the user's environment. See <B>LOCALE AND SUBLOCALE SPECIFICATION</B>
|
||||
below for a description of the locale string format.
|
||||
<P><DT><A NAME="M8"><B>::msgcat::mcpreferences</B></A><DD>
|
||||
Returns an ordered list of the locales preferred by
|
||||
the user, based on the user's language specification.
|
||||
The list is ordered from most specific to least
|
||||
preference. If the user has specified LANG=en_US_funky,
|
||||
this procedure would return {en_US_funky en_US en}.
|
||||
<P><DT><A NAME="M9"><B>::msgcat::mcload </B><I>dirname</I></A><DD>
|
||||
Searches the specified directory for files that match
|
||||
the language specifications returned by <B>::msgcat::mcpreferences</B>.
|
||||
Each file located is sourced. The file extension is ``.msg''.
|
||||
The number of message files which matched the specification
|
||||
and were loaded is returned.
|
||||
<P><DT><A NAME="M10"><B>::msgcat::mcset </B><I>locale src-string </I>?<I>translate-string</I>?</A><DD>
|
||||
Sets the translation for <I>src-string</I> to <I>translate-string</I>
|
||||
in the specified <I>locale</I>. If <I>translate-string</I> is not
|
||||
specified, <I>src-string</I> is used for both. The function
|
||||
returns <I>translate-string</I>.
|
||||
<P><DT><A NAME="M11"><B>::msgcat::mcunknown </B><I>locale src-string</I></A><DD>
|
||||
This routine is called by <B>::msgcat::mc</B> in the case when
|
||||
a translation for <I>src-string</I> is not defined in the
|
||||
current locale. The default action is to return
|
||||
<I>src-string</I>. This procedure can be redefined by the
|
||||
application, for example to log error messages for each unknown
|
||||
string. The <B>::msgcat::mcunknown</B> procedure is invoked at the
|
||||
same stack context as the call to <B>::msgcat::mc</B>. The return vaue
|
||||
of <B>::msgcat::mcunknown</B> is used as the return vaue for the call
|
||||
to <B>::msgcat::mc</B>.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M12">LOCALE AND SUBLOCALE SPECIFICATION</A></H3>
|
||||
The locale is specified by a locale string.
|
||||
The locale string consists of
|
||||
a language code, an optional country code, and an optional
|
||||
system-specific code, each separated by ``_''. The country and language
|
||||
codes are specified in standards ISO-639 and ISO-3166.
|
||||
For example, the locale ``en'' specifies English and
|
||||
``en_US'' specifes U.S. English.
|
||||
<P>
|
||||
The locale defaults to the value in <B>env(LANG)</B> at the time the
|
||||
<B>msgcat</B> package is loaded. If <B>env(LANG)</B> is not defined, then the
|
||||
locale defaults to ``C''.
|
||||
<P>
|
||||
When a locale is specified by the user, a ``best match'' search is
|
||||
performed during string translation. For example, if a user specifies
|
||||
en_UK_Funky, the locales ``en_UK_Funky'', ``en_UK'', and ``en'' are
|
||||
searched in order until a matching translation string is found. If no
|
||||
translation string is available, then <B>::msgcat::unknown</B> is
|
||||
called.
|
||||
|
||||
<H3><A NAME="M13">NAMESPACES AND MESSAGE CATALOGS</A></H3>
|
||||
Strings stored in the message catalog are stored relative
|
||||
to the namespace from which they were added. This allows
|
||||
multiple packages to use the same strings without fear
|
||||
of collisions with other packages. It also allows the
|
||||
source string to be shorter and less prone to typographical
|
||||
error.
|
||||
<P>
|
||||
For example, executing the code
|
||||
<PRE>mcset en hello "hello from ::"
|
||||
namespace eval foo {mcset en hello "hello from ::foo"}
|
||||
puts [mc hello]
|
||||
namespace eval foo {puts [mc hello]}</PRE>
|
||||
will print
|
||||
<PRE>hello from ::
|
||||
hello from ::foo</PRE>
|
||||
<P>
|
||||
When searching for a translation of a message, the
|
||||
message catalog will search first the current namespace,
|
||||
then the parent of the current namespace, and so on until
|
||||
the global namespace is reached. This allows child namespaces
|
||||
to "inherit" messages from their parent namespace.
|
||||
<P>
|
||||
For example, executing the code
|
||||
<PRE>mcset en m1 ":: message1"
|
||||
mcset en m2 ":: message2"
|
||||
mcset en m3 ":: message3"
|
||||
namespace eval ::foo {
|
||||
mcset en m2 "::foo message2"
|
||||
mcset en m3 "::foo message3"
|
||||
}
|
||||
namespace eval ::foo::bar {
|
||||
mcset en m3 "::foo::bar message3"
|
||||
}
|
||||
puts "[mc m1]; [mc m2]; [mc m3]"
|
||||
namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc m3]"}
|
||||
namespace eval ::foo::bar {puts "[mc m1]; [mc m2]; [mc m3]"}</PRE>
|
||||
will print
|
||||
<PRE>:: message1; :: message2; :: message3
|
||||
:: message1; ::foo message2; ::foo message3
|
||||
:: message1; ::foo message2; ::foo::bar message3</PRE>
|
||||
<H3><A NAME="M14">LOCATION AND FORMAT OF MESSAGE FILES</A></H3>
|
||||
Message files can be located in any directory, subject
|
||||
to the following conditions:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT>[1]<DD>
|
||||
All message files for a package are in the same directory.
|
||||
<P><DT>[2]<DD>
|
||||
The message file name is a locale specifier followed
|
||||
by ``.msg''. For example:
|
||||
<PRE>es.msg -- spanish
|
||||
en_UK.msg -- UK English</PRE>
|
||||
<P><DT>[3]<DD>
|
||||
The file contains a series of calls to mcset, setting the
|
||||
necessary translation strings for the language. For example:
|
||||
<PRE>::msgcat::mcset es "Free Beer!" "Cerveza Gracias!"</PRE>
|
||||
<P></DL>
|
||||
<H3><A NAME="M15">RECOMMENDED MESSAGE SETUP FOR PACKAGES</A></H3>
|
||||
If a package is installed into a subdirectory of the
|
||||
<B>tcl_pkgPath</B> and loaded via <B>package require</B>, the
|
||||
following procedure is recommended.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT>[1]<DD>
|
||||
During package installation, create a subdirectory
|
||||
<B>msgs</B> under your package directory.
|
||||
<P><DT>[2]<DD>
|
||||
Copy your *.msg files into that directory.
|
||||
<P><DT>[3]<DD>
|
||||
Add the following command to your package
|
||||
initialization script:
|
||||
<PRE># load language files, stored in msgs subdirectory
|
||||
::msgcat::mcload [file join [file dirname [info script]] msgs]</PRE>
|
||||
<P></DL>
|
||||
<H3><A NAME="M16">POSTITIONAL CODES FOR FORMAT AND SCAN COMMANDS</A></H3>
|
||||
It is possible that a message string used as an argument
|
||||
to <B><A HREF="../TkCmd/format.htm">format</A></B> might have positionally dependent parameters that
|
||||
might need to be repositioned. For example, it might be
|
||||
syntactically desirable to rearrange the sentence structure
|
||||
while translating.
|
||||
<PRE>format "We produced %d units in location %s" $num $city
|
||||
format "In location %s we produced %d units" $city $num</PRE>
|
||||
<P>
|
||||
This can be handled by using the positional
|
||||
parameters:
|
||||
<PRE>format "We produced %1\$d units in location %2\$s" $num $city
|
||||
format "In location %2\$s we produced %1\$d units" $num $city</PRE>
|
||||
<P>
|
||||
Similarly, positional parameters can be used with <B><A HREF="../TkCmd/scan.htm">scan</A></B> to
|
||||
extract values from internationalized strings.
|
||||
|
||||
<H3><A NAME="M17">CREDITS</A></H3>
|
||||
The message catalog code was developed by Mark Harrison.
|
||||
|
||||
<H3><A NAME="M18">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/format.htm">format</A></B>, <B><A HREF="../TkCmd/scan.htm">scan</A></B>, <B><A HREF="../TkCmd/namespace.htm">namespace</A></B>, <B><A HREF="../TkCmd/package.htm">package</A></B>
|
||||
<H3><A NAME="M19">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/I.htm#internationalization">internationalization</A>, <A href="../Keywords/I.htm#i18n">i18n</A>, <A href="../Keywords/L.htm#localization">localization</A>, <A href="../Keywords/L.htm#l10n">l10n</A>, <A href="../Keywords/M.htm#message">message</A>, <A href="../Keywords/T.htm#text">text</A>, <A href="../Keywords/T.htm#translation">translation</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1998 Mark Harrison.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
532
hlp/en/tcl/namespace.htm
Normal file
532
hlp/en/tcl/namespace.htm
Normal file
@@ -0,0 +1,532 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - namespace manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="namespace.htm#M2" NAME="L733">NAME</A>
|
||||
<DL><DD>namespace - create and manipulate contexts for commands and variables</DL>
|
||||
<DD><A HREF="namespace.htm#M3" NAME="L734">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>namespace </B>?<I>option</I>? ?<I>arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="namespace.htm#M4" NAME="L735">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="namespace.htm#M5" NAME="L736"><B>namespace children </B>?<I>namespace</I>? ?<I>pattern</I>?</A>
|
||||
<DD><A HREF="namespace.htm#M6" NAME="L737"><B>namespace code </B><I>script</I></A>
|
||||
<DD><A HREF="namespace.htm#M7" NAME="L738"><B>namespace current</B></A>
|
||||
<DD><A HREF="namespace.htm#M8" NAME="L739"><B>namespace delete </B>?<I>namespace namespace ...</I>?</A>
|
||||
<DD><A HREF="namespace.htm#M9" NAME="L740"><B>namespace eval</B> <I>namespace arg</I> ?<I>arg ...</I>?</A>
|
||||
<DD><A HREF="namespace.htm#M10" NAME="L741"><B>namespace export </B>?-<B>clear</B>? ?<I>pattern pattern ...</I>?</A>
|
||||
<DD><A HREF="namespace.htm#M11" NAME="L742"><B>namespace forget </B>?<I>pattern pattern ...</I>?</A>
|
||||
<DD><A HREF="namespace.htm#M12" NAME="L743"><B>namespace import </B>?<B>-force</B>? ?<I>pattern</I> <I>pattern ...</I>?</A>
|
||||
<DD><A HREF="namespace.htm#M13" NAME="L744"><B>namespace inscope</B> <I>namespace arg</I> ?<I>arg ...</I>?</A>
|
||||
<DD><A HREF="namespace.htm#M14" NAME="L745"><B>namespace origin </B><I>command</I></A>
|
||||
<DD><A HREF="namespace.htm#M15" NAME="L746"><B>namespace parent</B> ?<I>namespace</I>?</A>
|
||||
<DD><A HREF="namespace.htm#M16" NAME="L747"><B>namespace qualifiers</B> <I>string</I></A>
|
||||
<DD><A HREF="namespace.htm#M17" NAME="L748"><B>namespace tail</B> <I>string</I></A>
|
||||
<DD><A HREF="namespace.htm#M18" NAME="L749"><B>namespace which</B> ?-<B>command</B>? ?-<B>variable</B>? <I>name</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="namespace.htm#M19" NAME="L750">WHAT IS A NAMESPACE?</A>
|
||||
<DD><A HREF="namespace.htm#M20" NAME="L751">QUALIFIED NAMES</A>
|
||||
<DD><A HREF="namespace.htm#M21" NAME="L752">NAME RESOLUTION</A>
|
||||
<DD><A HREF="namespace.htm#M22" NAME="L753">IMPORTING COMMANDS</A>
|
||||
<DD><A HREF="namespace.htm#M23" NAME="L754">EXPORTING COMMANDS</A>
|
||||
<DD><A HREF="namespace.htm#M24" NAME="L755">SEE ALSO</A>
|
||||
<DD><A HREF="namespace.htm#M25" NAME="L756">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
namespace - create and manipulate contexts for commands and variables
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>namespace </B>?<I>option</I>? ?<I>arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>namespace</B> command lets you create, access, and destroy
|
||||
separate contexts for commands and variables.
|
||||
See the section <B>WHAT IS A NAMESPACE?</B> below
|
||||
for a brief overview of namespaces.
|
||||
The legal <I>option</I>'s are listed below.
|
||||
Note that you can abbreviate the <I>option</I>'s.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>namespace children </B>?<I>namespace</I>? ?<I>pattern</I>?</A><DD>
|
||||
Returns a list of all child namespaces that belong to the
|
||||
namespace <I>namespace</I>.
|
||||
If <I>namespace</I> is not specified,
|
||||
then the children are returned for the current namespace.
|
||||
This command returns fully-qualified names,
|
||||
which start with <B>::</B>.
|
||||
If the optional <I>pattern</I> is given,
|
||||
then this command returns only the names that match the glob-style pattern.
|
||||
The actual pattern used is determined as follows:
|
||||
a pattern that starts with <B>::</B> is used directly,
|
||||
otherwise the namespace <I>namespace</I>
|
||||
(or the fully-qualified name of the current namespace)
|
||||
is prepended onto the the pattern.
|
||||
<P><DT><A NAME="M6"><B>namespace code </B><I>script</I></A><DD>
|
||||
Captures the current namespace context for later execution
|
||||
of the script <I>script</I>.
|
||||
It returns a new script in which <I>script</I> has been wrapped
|
||||
in a <B>namespace code</B> command.
|
||||
The new script has two important properties.
|
||||
First, it can be evaluated in any namespace and will cause
|
||||
<I>script</I> to be evaluated in the current namespace
|
||||
(the one where the <B>namespace code</B> command was invoked).
|
||||
Second, additional arguments can be appended to the resulting script
|
||||
and they will be passed to <I>script</I> as additional arguments.
|
||||
For example, suppose the command
|
||||
<B>set script [namespace code {foo bar}]</B>
|
||||
is invoked in namespace <B>::a::b</B>.
|
||||
Then <B>eval "$script x y"</B>
|
||||
can be executed in any namespace (assuming the value of
|
||||
<B>script</B> has been passed in properly)
|
||||
and will have the same effect as the command
|
||||
<B>namespace eval ::a::b {foo bar x y}</B>.
|
||||
This command is needed because
|
||||
extensions like Tk normally execute callback scripts
|
||||
in the global namespace.
|
||||
A scoped command captures a command together with its namespace context
|
||||
in a way that allows it to be executed properly later.
|
||||
See the section <B>SCOPED VALUES</B> for some examples
|
||||
of how this is used to create callback scripts.
|
||||
<P><DT><A NAME="M7"><B>namespace current</B></A><DD>
|
||||
Returns the fully-qualified name for the current namespace.
|
||||
The actual name of the global namespace is ``<A HREF="../TkLib/CrtChannel.htm"></A>''
|
||||
(i.e., an empty string),
|
||||
but this command returns <B>::</B> for the global namespace
|
||||
as a convenience to programmers.
|
||||
<P><DT><A NAME="M8"><B>namespace delete </B>?<I>namespace namespace ...</I>?</A><DD>
|
||||
Each namespace <I>namespace</I> is deleted
|
||||
and all variables, procedures, and child namespaces
|
||||
contained in the namespace are deleted.
|
||||
If a procedure is currently executing inside the namespace,
|
||||
the namespace will be kept alive until the procedure returns;
|
||||
however, the namespace is marked to prevent other code from
|
||||
looking it up by name.
|
||||
If a namespace doesn't exist, this command returns an error.
|
||||
If no namespace names are given, this command does nothing.
|
||||
<P><DT><A NAME="M9"><B>namespace eval</B> <I>namespace arg</I> ?<I>arg ...</I>?</A><DD>
|
||||
Activates a namespace called <I>namespace</I> and evaluates some code
|
||||
in that context.
|
||||
If the namespace does not already exist, it is created.
|
||||
If more than one <I>arg</I> argument is specified,
|
||||
the arguments are concatenated together with a space between each one
|
||||
in the same fashion as the <B><A HREF="../TkCmd/eval.htm">eval</A></B> command,
|
||||
and the result is evaluated.
|
||||
<BR>
|
||||
<P>
|
||||
If <I>namespace</I> has leading namespace qualifiers
|
||||
and any leading namespaces do not exist,
|
||||
they are automatically created.
|
||||
<P><DT><A NAME="M10"><B>namespace export </B>?-<B>clear</B>? ?<I>pattern pattern ...</I>?</A><DD>
|
||||
Specifies which commands are exported from a namespace.
|
||||
The exported commands are those that can be later imported
|
||||
into another namespace using a <B>namespace import</B> command.
|
||||
Both commands defined in a namespace and
|
||||
commands the namespace has previously imported
|
||||
can be exported by a namespace.
|
||||
The commands do not have to be defined
|
||||
at the time the <B>namespace export</B> command is executed.
|
||||
Each <I>pattern</I> may contain glob-style special characters,
|
||||
but it may not include any namespace qualifiers.
|
||||
That is, the pattern can only specify commands
|
||||
in the current (exporting) namespace.
|
||||
Each <I>pattern</I> is appended onto the namespace's list of export patterns.
|
||||
If the -<B>clear</B> flag is given,
|
||||
the namespace's export pattern list is reset to empty before any
|
||||
<I>pattern</I> arguments are appended.
|
||||
If no <I>pattern</I>s are given and the -<B>clear</B> flag isn't given,
|
||||
this command returns the namespace's current export list.
|
||||
<P><DT><A NAME="M11"><B>namespace forget </B>?<I>pattern pattern ...</I>?</A><DD>
|
||||
Removes previously imported commands from a namespace.
|
||||
Each <I>pattern</I> is a qualified name such as
|
||||
<B>foo::x</B> or <B>a::b::p*</B>.
|
||||
Qualified names contain <B>::</B>s and qualify a name
|
||||
with the name of one or more namespaces.
|
||||
Each <I>pattern</I> is qualified with the name of an exporting namespace
|
||||
and may have glob-style special characters in the command name
|
||||
at the end of the qualified name.
|
||||
Glob characters may not appear in a namespace name.
|
||||
This command first finds the matching exported commands.
|
||||
It then checks whether any of those those commands
|
||||
were previously imported by the current namespace.
|
||||
If so, this command deletes the corresponding imported commands.
|
||||
In effect, this un-does the action of a <B>namespace import</B> command.
|
||||
<P><DT><A NAME="M12"><B>namespace import </B>?<B>-force</B>? ?<I>pattern</I> <I>pattern ...</I>?</A><DD>
|
||||
Imports commands into a namespace.
|
||||
Each <I>pattern</I> is a qualified name like
|
||||
<B>foo::x</B> or <B>a::p*</B>.
|
||||
That is, it includes the name of an exporting namespace
|
||||
and may have glob-style special characters in the command name
|
||||
at the end of the qualified name.
|
||||
Glob characters may not appear in a namespace name.
|
||||
All the commands that match a <I>pattern</I> string
|
||||
and which are currently exported from their namespace
|
||||
are added to the current namespace.
|
||||
This is done by creating a new command in the current namespace
|
||||
that points to the exported command in its original namespace;
|
||||
when the new imported command is called, it invokes the exported command.
|
||||
This command normally returns an error
|
||||
if an imported command conflicts with an existing command.
|
||||
However, if the -<B>force</B> option is given,
|
||||
imported commands will silently replace existing commands.
|
||||
The <B>namespace import</B> command has snapshot semantics:
|
||||
that is, only requested commands that are currently defined
|
||||
in the exporting namespace are imported.
|
||||
In other words, you can import only the commands that are in a namespace
|
||||
at the time when the <B>namespace import</B> command is executed.
|
||||
If another command is defined and exported in this namespace later on,
|
||||
it will not be imported.
|
||||
<P><DT><A NAME="M13"><B>namespace inscope</B> <I>namespace arg</I> ?<I>arg ...</I>?</A><DD>
|
||||
Executes a script in the context of a particular namespace.
|
||||
This command is not expected to be used directly by programmers;
|
||||
calls to it are generated implicitly when applications
|
||||
use <B>namespace code</B> commands to create callback scripts
|
||||
that the applications then register with, e.g., Tk widgets.
|
||||
The <B>namespace inscope</B> command is much like the <B>namespace eval</B>
|
||||
command except that it has <B><A HREF="../TkCmd/lappend.htm">lappend</A></B> semantics
|
||||
and the namespace must already exist.
|
||||
It treats the first argument as a list,
|
||||
and appends any arguments after the first
|
||||
onto the end as proper list elements.
|
||||
<B>namespace inscope ::foo a x y z</B>
|
||||
is equivalent to
|
||||
<B>namespace eval ::foo [concat a [list x y z]]</B>
|
||||
This <B><A HREF="../TkCmd/lappend.htm">lappend</A></B> semantics is important because many callback scripts
|
||||
are actually prefixes.
|
||||
<P><DT><A NAME="M14"><B>namespace origin </B><I>command</I></A><DD>
|
||||
Returns the fully-qualified name of the original command
|
||||
to which the imported command <I>command</I> refers.
|
||||
When a command is imported into a namespace,
|
||||
a new command is created in that namespace
|
||||
that points to the actual command in the exporting namespace.
|
||||
If a command is imported into a sequence of namespaces
|
||||
<I>a, b,...,n</I> where each successive namespace
|
||||
just imports the command from the previous namespace,
|
||||
this command returns the fully-qualified name of the original command
|
||||
in the first namespace, <I>a</I>.
|
||||
If <I>command</I> does not refer to an imported command,
|
||||
the command's own fully-qualified name is returned.
|
||||
<P><DT><A NAME="M15"><B>namespace parent</B> ?<I>namespace</I>?</A><DD>
|
||||
Returns the fully-qualified name of the parent namespace
|
||||
for namespace <I>namespace</I>.
|
||||
If <I>namespace</I> is not specified,
|
||||
the fully-qualified name of the current namespace's parent is returned.
|
||||
<P><DT><A NAME="M16"><B>namespace qualifiers</B> <I>string</I></A><DD>
|
||||
Returns any leading namespace qualifiers for <I>string</I>.
|
||||
Qualifiers are namespace names separated by <B>::</B>s.
|
||||
For the <I>string</I> <B>::foo::bar::x</B>,
|
||||
this command returns <B>::foo::bar</B>,
|
||||
and for <B>::</B> it returns an empty string.
|
||||
This command is the complement of the <B>namespace tail</B> command.
|
||||
Note that it does not check whether the
|
||||
namespace names are, in fact,
|
||||
the names of currently defined namespaces.
|
||||
<P><DT><A NAME="M17"><B>namespace tail</B> <I>string</I></A><DD>
|
||||
Returns the simple name at the end of a qualified string.
|
||||
Qualifiers are namespace names separated by <B>::</B>s.
|
||||
For the <I>string</I> <B>::foo::bar::x</B>,
|
||||
this command returns <B>x</B>,
|
||||
and for <B>::</B> it returns an empty string.
|
||||
This command is the complement of the <B>namespace qualifiers</B> command.
|
||||
It does not check whether the namespace names are, in fact,
|
||||
the names of currently defined namespaces.
|
||||
<P><DT><A NAME="M18"><B>namespace which</B> ?-<B>command</B>? ?-<B>variable</B>? <I>name</I></A><DD>
|
||||
Looks up <I>name</I> as either a command or variable
|
||||
and returns its fully-qualified name.
|
||||
For example, if <I>name</I> does not exist in the current namespace
|
||||
but does exist in the global namespace,
|
||||
this command returns a fully-qualified name in the global namespace.
|
||||
If the command or variable does not exist,
|
||||
this command returns an empty string. If the variable has been
|
||||
created but not defined, such as with the <B><A HREF="../TkCmd/variable.htm">variable</A></B> command
|
||||
or through a <B><A HREF="../TkCmd/trace.htm">trace</A></B> on the variable, this command will return the
|
||||
fully-qualified name of the variable.
|
||||
If no flag is given, <I>name</I> is treated as a command name.
|
||||
See the section <B>NAME RESOLUTION</B> below for an explanation of
|
||||
the rules regarding name resolution.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M19">WHAT IS A NAMESPACE?</A></H3>
|
||||
A namespace is a collection of commands and variables.
|
||||
It encapsulates the commands and variables to ensure that they
|
||||
won't interfere with the commands and variables of other namespaces.
|
||||
Tcl has always had one such collection,
|
||||
which we refer to as the <I>global namespace</I>.
|
||||
The global namespace holds all global variables and commands.
|
||||
The <B>namespace eval</B> command lets you create new namespaces.
|
||||
For example,
|
||||
<PRE><B>namespace eval Counter {
|
||||
namespace export bump
|
||||
variable num 0
|
||||
|
||||
proc bump {} {
|
||||
variable num
|
||||
incr num
|
||||
}
|
||||
}</B></PRE>
|
||||
creates a new namespace containing the variable <B>num</B> and
|
||||
the procedure <B>bump</B>.
|
||||
The commands and variables in this namespace are separate from
|
||||
other commands and variables in the same program.
|
||||
If there is a command named <B>bump</B> in the global namespace,
|
||||
for example, it will be different from the command <B>bump</B>
|
||||
in the <B>Counter</B> namespace.
|
||||
<P>
|
||||
Namespace variables resemble global variables in Tcl.
|
||||
They exist outside of the procedures in a namespace
|
||||
but can be accessed in a procedure via the <B><A HREF="../TkCmd/variable.htm">variable</A></B> command,
|
||||
as shown in the example above.
|
||||
<P>
|
||||
Namespaces are dynamic.
|
||||
You can add and delete commands and variables at any time,
|
||||
so you can build up the contents of a
|
||||
namespace over time using a series of <B>namespace eval</B> commands.
|
||||
For example, the following series of commands has the same effect
|
||||
as the namespace definition shown above:
|
||||
<PRE><B>namespace eval Counter {
|
||||
variable num 0
|
||||
proc bump {} {
|
||||
variable num
|
||||
return [incr num]
|
||||
}
|
||||
}
|
||||
namespace eval Counter {
|
||||
proc test {args} {
|
||||
return $args
|
||||
}
|
||||
}
|
||||
namespace eval Counter {
|
||||
rename test ""
|
||||
}</B></PRE>
|
||||
Note that the <B>test</B> procedure is added to the <B>Counter</B> namespace,
|
||||
and later removed via the <B><A HREF="../TkCmd/rename.htm">rename</A></B> command.
|
||||
<P>
|
||||
Namespaces can have other namespaces within them,
|
||||
so they nest hierarchically.
|
||||
A nested namespace is encapsulated inside its parent namespace
|
||||
and can not interfere with other namespaces.
|
||||
|
||||
<H3><A NAME="M20">QUALIFIED NAMES</A></H3>
|
||||
Each namespace has a textual name such as
|
||||
<B><A HREF="../TkCmd/history.htm">history</A></B> or <B>::safe::interp</B>.
|
||||
Since namespaces may nest,
|
||||
qualified names are used to refer to
|
||||
commands, variables, and child namespaces contained inside namespaces.
|
||||
Qualified names are similar to the hierarchical path names for
|
||||
Unix files or Tk widgets,
|
||||
except that <B>::</B> is used as the separator
|
||||
instead of <B>/</B> or <B>.</B>.
|
||||
The topmost or global namespace has the name ``<A HREF="../TkLib/CrtChannel.htm"></A>'' (i.e., an empty string),
|
||||
although <B>::</B> is a synonym.
|
||||
As an example, the name <B>::safe::interp::create</B>
|
||||
refers to the command <B>create</B> in the namespace <B><A HREF="../TkCmd/interp.htm">interp</A></B>
|
||||
that is a child of of namespace <B>::safe</B>,
|
||||
which in turn is a child of the global namespace <B>::</B>.
|
||||
<P>
|
||||
If you want to access commands and variables from another namespace,
|
||||
you must use some extra syntax.
|
||||
Names must be qualified by the namespace that contains them.
|
||||
From the global namespace,
|
||||
we might access the <B>Counter</B> procedures like this:
|
||||
<PRE><B>Counter::bump 5
|
||||
Counter::Reset</B></PRE>
|
||||
We could access the current count like this:
|
||||
<PRE><B>puts "count = $Counter::num"</B></PRE>
|
||||
When one namespace contains another, you may need more than one
|
||||
qualifier to reach its elements.
|
||||
If we had a namespace <B>Foo</B> that contained the namespace <B>Counter</B>,
|
||||
you could invoke its <B>bump</B> procedure
|
||||
from the global namespace like this:
|
||||
<PRE><B>Foo::Counter::bump 3</B></PRE>
|
||||
<P>
|
||||
You can also use qualified names when you create and rename commands.
|
||||
For example, you could add a procedure to the <B>Foo</B>
|
||||
namespace like this:
|
||||
<PRE><B>proc Foo::Test {args} {return $args}</B></PRE>
|
||||
And you could move the same procedure to another namespace like this:
|
||||
<PRE><B>rename Foo::Test Bar::Test</B></PRE>
|
||||
<P>
|
||||
There are a few remaining points about qualified names
|
||||
that we should cover.
|
||||
Namespaces have nonempty names except for the global namespace.
|
||||
<B>::</B> is disallowed in simple command, variable, and namespace names
|
||||
except as a namespace separator.
|
||||
Extra <B>:</B>s in a qualified name are ignored;
|
||||
that is, two or more <B>:</B>s are treated as a namespace separator.
|
||||
A trailing <B>::</B> in a qualified variable or command name
|
||||
refers to the variable or command named {}.
|
||||
However, a trailing <B>::</B> in a qualified namespace name is ignored.
|
||||
|
||||
<H3><A NAME="M21">NAME RESOLUTION</A></H3>
|
||||
In general, all Tcl commands that take variable and command names
|
||||
support qualified names.
|
||||
This means you can give qualified names to such commands as
|
||||
<B><A HREF="../TkCmd/set.htm">set</A></B>, <B><A HREF="../TkCmd/proc.htm">proc</A></B>, <B><A HREF="../TkCmd/rename.htm">rename</A></B>, and <B><A HREF="../TkCmd/interp.htm">interp alias</A></B>.
|
||||
If you provide a fully-qualified name that starts with a <B>::</B>,
|
||||
there is no question about what command, variable, or namespace
|
||||
you mean.
|
||||
However, if the name does not start with a <B>::</B>
|
||||
(i.e., is <I>relative</I>),
|
||||
Tcl follows a fixed rule for looking it up:
|
||||
Command and variable names are always resolved
|
||||
by looking first in the current namespace,
|
||||
and then in the global namespace.
|
||||
Namespace names, on the other hand, are always resolved
|
||||
by looking in only the current namespace.
|
||||
<P>
|
||||
In the following example,
|
||||
<PRE><B>set traceLevel 0
|
||||
namespace eval Debug {
|
||||
printTrace $traceLevel
|
||||
}</B></PRE>
|
||||
Tcl looks for <B>traceLevel</B> in the namespace <B>Debug</B>
|
||||
and then in the global namespace.
|
||||
It looks up the command <B>printTrace</B> in the same way.
|
||||
If a variable or command name is not found in either context,
|
||||
the name is undefined.
|
||||
To make this point absolutely clear, consider the following example:
|
||||
<PRE><B>set traceLevel 0
|
||||
namespace eval Foo {
|
||||
variable traceLevel 3
|
||||
|
||||
namespace eval Debug {
|
||||
printTrace $traceLevel
|
||||
}
|
||||
}</B></PRE>
|
||||
Here Tcl looks for <B>traceLevel</B> first in the namespace <B>Foo::Debug</B>.
|
||||
Since it is not found there, Tcl then looks for it
|
||||
in the global namespace.
|
||||
The variable <B>Foo::traceLevel</B> is completely ignored
|
||||
during the name resolution process.
|
||||
<P>
|
||||
You can use the <B>namespace which</B> command to clear up any question
|
||||
about name resolution.
|
||||
For example, the command:
|
||||
<PRE><B>namespace eval Foo::Debug {namespace which -variable traceLevel}</B></PRE>
|
||||
returns <B>::traceLevel</B>.
|
||||
On the other hand, the command,
|
||||
<PRE><B>namespace eval Foo {namespace which -variable traceLevel}</B></PRE>
|
||||
returns <B>::Foo::traceLevel</B>.
|
||||
<P>
|
||||
As mentioned above,
|
||||
namespace names are looked up differently
|
||||
than the names of variables and commands.
|
||||
Namespace names are always resolved in the current namespace.
|
||||
This means, for example,
|
||||
that a <B>namespace eval</B> command that creates a new namespace
|
||||
always creates a child of the current namespace
|
||||
unless the new namespace name begins with a <B>::</B>.
|
||||
<P>
|
||||
Tcl has no access control to limit what variables, commands,
|
||||
or namespaces you can reference.
|
||||
If you provide a qualified name that resolves to an element
|
||||
by the name resolution rule above,
|
||||
you can access the element.
|
||||
<P>
|
||||
You can access a namespace variable
|
||||
from a procedure in the same namespace
|
||||
by using the <B><A HREF="../TkCmd/variable.htm">variable</A></B> command.
|
||||
Much like the <B><A HREF="../TkCmd/global.htm">global</A></B> command,
|
||||
this creates a local link to the namespace variable.
|
||||
If necessary, it also creates the variable in the current namespace
|
||||
and initializes it.
|
||||
Note that the <B><A HREF="../TkCmd/global.htm">global</A></B> command only creates links
|
||||
to variables in the global namespace.
|
||||
It is not necessary to use a <B><A HREF="../TkCmd/variable.htm">variable</A></B> command
|
||||
if you always refer to the namespace variable using an
|
||||
appropriate qualified name.
|
||||
|
||||
<H3><A NAME="M22">IMPORTING COMMANDS</A></H3>
|
||||
Namespaces are often used to represent libraries.
|
||||
Some library commands are used so frequently
|
||||
that it is a nuisance to type their qualified names.
|
||||
For example, suppose that all of the commands in a package
|
||||
like BLT are contained in a namespace called <B>Blt</B>.
|
||||
Then you might access these commands like this:
|
||||
<PRE><B>Blt::graph .g -background red
|
||||
Blt::table . .g 0,0</B></PRE>
|
||||
If you use the <B>graph</B> and <B>table</B> commands frequently,
|
||||
you may want to access them without the <B>Blt::</B> prefix.
|
||||
You can do this by importing the commands into the current namespace,
|
||||
like this:
|
||||
<PRE><B>namespace import Blt::*</B></PRE>
|
||||
This adds all exported commands from the <B>Blt</B> namespace
|
||||
into the current namespace context, so you can write code like this:
|
||||
<PRE><B>graph .g -background red
|
||||
table . .g 0,0</B></PRE>
|
||||
The <B>namespace import</B> command only imports commands
|
||||
from a namespace that that namespace exported
|
||||
with a <B>namespace export</B> command.
|
||||
<P>
|
||||
Importing <I>every</I> command from a namespace is generally
|
||||
a bad idea since you don't know what you will get.
|
||||
It is better to import just the specific commands you need.
|
||||
For example, the command
|
||||
<PRE><B>namespace import Blt::graph Blt::table</B></PRE>
|
||||
imports only the <B>graph</B> and <B>table</B> commands into the
|
||||
current context.
|
||||
<P>
|
||||
If you try to import a command that already exists, you will get an
|
||||
error. This prevents you from importing the same command from two
|
||||
different packages. But from time to time (perhaps when debugging),
|
||||
you may want to get around this restriction. You may want to
|
||||
reissue the <B>namespace import</B> command to pick up new commands
|
||||
that have appeared in a namespace. In that case, you can use the
|
||||
<B>-force</B> option, and existing commands will be silently overwritten:
|
||||
<PRE><B>namespace import -force Blt::graph Blt::table</B></PRE>
|
||||
If for some reason, you want to stop using the imported commands,
|
||||
you can remove them with an <B>namespace forget</B> command, like this:
|
||||
<PRE><B>namespace forget Blt::*</B></PRE>
|
||||
This searches the current namespace for any commands imported from <B>Blt</B>.
|
||||
If it finds any, it removes them. Otherwise, it does nothing.
|
||||
After this, the <B>Blt</B> commands must be accessed with the <B>Blt::</B>
|
||||
prefix.
|
||||
<P>
|
||||
When you delete a command from the exporting namespace like this:
|
||||
<PRE><B>rename Blt::graph ""</B></PRE>
|
||||
the command is automatically removed from all namespaces that import it.
|
||||
|
||||
<H3><A NAME="M23">EXPORTING COMMANDS</A></H3>
|
||||
You can export commands from a namespace like this:
|
||||
<PRE><B>namespace eval Counter {
|
||||
namespace export bump reset
|
||||
variable Num 0
|
||||
variable Max 100
|
||||
|
||||
proc bump {{by 1}} {
|
||||
variable Num
|
||||
incr Num $by
|
||||
Check
|
||||
return $Num
|
||||
}
|
||||
proc reset {} {
|
||||
variable Num
|
||||
set Num 0
|
||||
}
|
||||
proc Check {} {
|
||||
variable Num
|
||||
variable Max
|
||||
if {$Num > $Max} {
|
||||
error "too high!"
|
||||
}
|
||||
}
|
||||
}</B></PRE>
|
||||
The procedures <B>bump</B> and <B>reset</B> are exported,
|
||||
so they are included when you import from the <B>Counter</B> namespace,
|
||||
like this:
|
||||
<PRE><B>namespace import Counter::*</B></PRE>
|
||||
However, the <B>Check</B> procedure is not exported,
|
||||
so it is ignored by the import operation.
|
||||
<P>
|
||||
The <B>namespace import</B> command only imports commands
|
||||
that were declared as exported by their namespace.
|
||||
The <B>namespace export</B> command specifies what commands
|
||||
may be imported by other namespaces.
|
||||
If a <B>namespace import</B> command specifies a command
|
||||
that is not exported, the command is not imported.
|
||||
|
||||
<H3><A NAME="M24">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/variable.htm">variable</A></B>
|
||||
<H3><A NAME="M25">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#exported">exported</A>, <A href="../Keywords/I.htm#internal">internal</A>, <A href="../Keywords/V.htm#variable">variable</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993-1997 Bell Labs Innovations for Lucent Technologies
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
275
hlp/en/tcl/open.htm
Normal file
275
hlp/en/tcl/open.htm
Normal file
@@ -0,0 +1,275 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - open manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="open.htm#M2" NAME="L757">NAME</A>
|
||||
<DL><DD>open - Open a file-based or command pipeline channel</DL>
|
||||
<DD><A HREF="open.htm#M3" NAME="L758">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>open </B><I>fileName</I>
|
||||
<DD><B>open </B><I>fileName access</I>
|
||||
<DD><B>open </B><I>fileName access permissions</I>
|
||||
</DL>
|
||||
<DD><A HREF="open.htm#M4" NAME="L759">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="open.htm#M5" NAME="L760"><B>r</B></A>
|
||||
<DD><A HREF="open.htm#M6" NAME="L761"><B>r+</B></A>
|
||||
<DD><A HREF="open.htm#M7" NAME="L762"><B>w</B></A>
|
||||
<DD><A HREF="open.htm#M8" NAME="L763"><B>w+</B></A>
|
||||
<DD><A HREF="open.htm#M9" NAME="L764"><B>a</B></A>
|
||||
<DD><A HREF="open.htm#M10" NAME="L765"><B>a+</B></A>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="open.htm#M11" NAME="L766"><B>RDONLY</B></A>
|
||||
<DD><A HREF="open.htm#M12" NAME="L767"><B>WRONLY</B></A>
|
||||
<DD><A HREF="open.htm#M13" NAME="L768"><B>RDWR</B></A>
|
||||
<DD><A HREF="open.htm#M14" NAME="L769"><B>APPEND</B></A>
|
||||
<DD><A HREF="open.htm#M15" NAME="L770"><B>CREAT</B></A>
|
||||
<DD><A HREF="open.htm#M16" NAME="L771"><B>EXCL</B></A>
|
||||
<DD><A HREF="open.htm#M17" NAME="L772"><B>NOCTTY</B></A>
|
||||
<DD><A HREF="open.htm#M18" NAME="L773"><B>NONBLOCK</B></A>
|
||||
<DD><A HREF="open.htm#M19" NAME="L774"><B>TRUNC</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="open.htm#M20" NAME="L775">COMMAND PIPELINES</A>
|
||||
<DD><A HREF="open.htm#M21" NAME="L776">SERIAL COMMUNICATIONS</A>
|
||||
<DD><A HREF="open.htm#M22" NAME="L777">CONFIGURATION OPTIONS</A>
|
||||
<DL>
|
||||
<DD><A HREF="open.htm#M23" NAME="L778"><B>-mode </B><I>baud</I><B>,</B><I>parity</I><B>,</B><I>data</I><B>,</B><I>stop</I></A>
|
||||
<DD><A HREF="open.htm#M24" NAME="L779"><B>-pollinterval </B><I>msec</I></A>
|
||||
<DD><A HREF="open.htm#M25" NAME="L780"><B>-lasterror</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="open.htm#M26" NAME="L781">PORTABILITY ISSUES</A>
|
||||
<DL>
|
||||
<DD><A HREF="open.htm#M27" NAME="L782"><B>Windows </B>(all versions)</A>
|
||||
<DD><A HREF="open.htm#M28" NAME="L783"><B>Windows NT</B></A>
|
||||
<DD><A HREF="open.htm#M29" NAME="L784"><B>Windows 95</B></A>
|
||||
<DD><A HREF="open.htm#M30" NAME="L785"><B>Macintosh</B></A>
|
||||
<DD><A HREF="open.htm#M31" NAME="L786"><B>Unix</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="open.htm#M32" NAME="L787">SEE ALSO</A>
|
||||
<DD><A HREF="open.htm#M33" NAME="L788">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
open - Open a file-based or command pipeline channel
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>open </B><I>fileName</I><BR>
|
||||
<B>open </B><I>fileName access</I><BR>
|
||||
<B>open </B><I>fileName access permissions</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command opens a file, serial port, or command pipeline and returns a
|
||||
channel identifier that may be used in future invocations of commands like
|
||||
<B><A HREF="../TkCmd/read.htm">read</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B>, and <B><A HREF="../TkCmd/close.htm">close</A></B>.
|
||||
If the first character of <I>fileName</I> is not <B>|</B> then
|
||||
the command opens a file:
|
||||
<I>fileName</I> gives the name of the file to open, and it must conform to the
|
||||
conventions described in the <B><A HREF="../TkCmd/filename.htm">filename</A></B> manual entry.
|
||||
<P>
|
||||
The <I>access</I> argument, if present, indicates the way in which the file
|
||||
(or command pipeline) is to be accessed.
|
||||
In the first form <I>access</I> may have any of the following values:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>r</B></A><DD>
|
||||
Open the file for reading only; the file must already exist. This is the
|
||||
default value if <I>access</I> is not specified.
|
||||
<P><DT><A NAME="M6"><B>r+</B></A><DD>
|
||||
Open the file for both reading and writing; the file must
|
||||
already exist.
|
||||
<P><DT><A NAME="M7"><B>w</B></A><DD>
|
||||
Open the file for writing only. Truncate it if it exists. If it doesn't
|
||||
exist, create a new file.
|
||||
<P><DT><A NAME="M8"><B>w+</B></A><DD>
|
||||
Open the file for reading and writing. Truncate it if it exists.
|
||||
If it doesn't exist, create a new file.
|
||||
<P><DT><A NAME="M9"><B>a</B></A><DD>
|
||||
Open the file for writing only. If the file doesn't exist,
|
||||
create a new empty file.
|
||||
Set the initial access position to the end of the file.
|
||||
<P><DT><A NAME="M10"><B>a+</B></A><DD>
|
||||
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.
|
||||
<P></DL>
|
||||
<P>
|
||||
In the second form, <I>access</I> consists of a list of any of the
|
||||
following flags, all of which have the standard POSIX meanings.
|
||||
One of the flags must be either <B>RDONLY</B>, <B>WRONLY</B> or <B>RDWR</B>.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M11"><B>RDONLY</B></A><DD>
|
||||
Open the file for reading only.
|
||||
<P><DT><A NAME="M12"><B>WRONLY</B></A><DD>
|
||||
Open the file for writing only.
|
||||
<P><DT><A NAME="M13"><B>RDWR</B></A><DD>
|
||||
Open the file for both reading and writing.
|
||||
<P><DT><A NAME="M14"><B>APPEND</B></A><DD>
|
||||
Set the file pointer to the end of the file prior to each write.
|
||||
<P><DT><A NAME="M15"><B>CREAT</B></A><DD>
|
||||
Create the file if it doesn't already exist (without this flag it
|
||||
is an error for the file not to exist).
|
||||
<P><DT><A NAME="M16"><B>EXCL</B></A><DD>
|
||||
If <B>CREAT</B> is also specified, an error is returned if the
|
||||
file already exists.
|
||||
<P><DT><A NAME="M17"><B>NOCTTY</B></A><DD>
|
||||
If the file is a terminal device, this flag prevents the file from
|
||||
becoming the controlling terminal of the process.
|
||||
<P><DT><A NAME="M18"><B>NONBLOCK</B></A><DD>
|
||||
Prevents the process from blocking while opening the file, and
|
||||
possibly in subsequent I/O operations. The exact behavior of
|
||||
this flag is system- and device-dependent; its use is discouraged
|
||||
(it is better to use the <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> command to put a file
|
||||
in nonblocking mode).
|
||||
For details refer to your system documentation on the <B>open</B> system
|
||||
call's <B>O_NONBLOCK</B> flag.
|
||||
<P><DT><A NAME="M19"><B>TRUNC</B></A><DD>
|
||||
If the file exists it is truncated to zero length.
|
||||
<P></DL>
|
||||
<P>
|
||||
If a new file is created as part of opening it, <I>permissions</I>
|
||||
(an integer) is used to set the permissions for the new file in
|
||||
conjunction with the process's file mode creation mask.
|
||||
<I>Permissions</I> defaults to 0666.
|
||||
<P>
|
||||
Note that if you are going to be reading or writing binary data from
|
||||
the channel created by this command, you should use the
|
||||
<B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> command to change the <B>-translation</B> option of
|
||||
the channel to <B><A HREF="../TkCmd/binary.htm">binary</A></B> before transferring any binary data. This
|
||||
is in contrast to the ``b'' character passed as part of the equivalent
|
||||
of the <I>access</I> parameter to some versions of the C library
|
||||
<I>fopen()</I> function.
|
||||
<H3><A NAME="M20">COMMAND PIPELINES</A></H3>
|
||||
If the first character of <I>fileName</I> is ``|'' then the
|
||||
remaining characters of <I>fileName</I> are treated as a list of arguments
|
||||
that describe a command pipeline to invoke, in the same style as the
|
||||
arguments for <B><A HREF="../TkCmd/exec.htm">exec</A></B>.
|
||||
In this case, the channel identifier returned by <B>open</B> may be used
|
||||
to write to the command's input pipe or read from its output pipe,
|
||||
depending on the value of <I>access</I>.
|
||||
If write-only access is used (e.g. <I>access</I> is <B>w</B>), then
|
||||
standard output for the pipeline is directed to the current standard
|
||||
output unless overridden by the command.
|
||||
If read-only access is used (e.g. <I>access</I> is <B>r</B>),
|
||||
standard input for the pipeline is taken from the current standard
|
||||
input unless overridden by the command.
|
||||
<H3><A NAME="M21">SERIAL COMMUNICATIONS</A></H3>
|
||||
If <I>fileName</I> refers to a serial port, then the specified serial port
|
||||
is opened and initialized in a platform-dependent manner. Acceptable
|
||||
values for the <I>fileName</I> to use to open a serial port are described in
|
||||
the PORTABILITY ISSUES section.
|
||||
|
||||
<H3><A NAME="M22">CONFIGURATION OPTIONS</A></H3>
|
||||
The <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> command can be used to query and set the following
|
||||
configuration option for open serial ports:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M23"><B>-mode </B><I>baud</I><B>,</B><I>parity</I><B>,</B><I>data</I><B>,</B><I>stop</I></A><DD>
|
||||
This option is a set of 4 comma-separated values: the baud rate, parity,
|
||||
number of data bits, and number of stop bits for this serial port. The
|
||||
<I>baud</I> rate is a simple integer that specifies the connection speed.
|
||||
<I>Parity</I> is one of the following letters: <B>n</B>, <B>o</B>, <B>e</B>,
|
||||
<B>m</B>, <B>s</B>; respectively signifying the parity options of ``none'',
|
||||
``odd'', ``even'', ``mark'', or ``space''. <I>Data</I> is the number of
|
||||
data bits and should be an integer from 5 to 8, while <I>stop</I> is the
|
||||
number of stop bits and should be the integer 1 or 2.
|
||||
<P><DT><A NAME="M24"><B>-pollinterval </B><I>msec</I></A><DD>
|
||||
This option, available only on Windows for serial ports, is used to
|
||||
set the maximum time between polling for fileevents. This affects the
|
||||
time interval between checking for events throughout the Tcl
|
||||
interpreter (the smallest value always wins). Use this option only if
|
||||
you want to poll the serial port more often than 10 msec (the default).
|
||||
<P><DT><A NAME="M25"><B>-lasterror</B></A><DD>
|
||||
This option is available only on Windows for serial ports, and is
|
||||
query only (will only be reported when directly requested).
|
||||
In case of a serial communication error, <B><A HREF="../TkCmd/read.htm">read</A></B> or <B><A HREF="../TkCmd/puts.htm">puts</A></B>
|
||||
returns a general Tcl file I/O error.
|
||||
<B>fconfigure -lasterror</B> can be called to get a list
|
||||
of error details (e.g. FRAME RXOVER).
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M26">PORTABILITY ISSUES</A></H3>
|
||||
<P>
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M27"><B>Windows </B>(all versions)</A><DD>
|
||||
Valid values for <I>fileName</I> to open a serial port are of the form
|
||||
<B>com</B><I>X</I><B>:</B>, where <I>X</I> is a number, generally from 1 to 4.
|
||||
This notation only works for serial ports from 1 to 9, if the system
|
||||
happens to have more than four. An attempt to open a serial port that
|
||||
does not exist or has a number greater than 9 will fail. An alternate
|
||||
form of opening serial ports is to use the filename <B>\\.\comX</B>,
|
||||
where X is any number that corresponds to a serial port; please note
|
||||
that this method is considerably slower on Windows 95 and Windows 98.
|
||||
<P><DT><A NAME="M28"><B>Windows NT</B></A><DD>
|
||||
When running Tcl interactively, there may be some strange interactions
|
||||
between the real console, if one is present, and a command pipeline that uses
|
||||
standard input or output. If a command pipeline is opened for reading, some
|
||||
of the lines entered at the console will be sent to the command pipeline and
|
||||
some will be sent to the Tcl evaluator. If a command pipeline is opened for
|
||||
writing, keystrokes entered into the console are not visible until the the
|
||||
pipe is closed. This behavior occurs whether the command pipeline is
|
||||
executing 16-bit or 32-bit applications. These problems only occur because
|
||||
both Tcl and the child application are competing for the console at
|
||||
the same time. If the command pipeline is started from a script, so that Tcl
|
||||
is not accessing the console, or if the command pipeline does not use
|
||||
standard input or output, but is redirected from or to a file, then the
|
||||
above problems do not occur.
|
||||
<P><DT><A NAME="M29"><B>Windows 95</B></A><DD>
|
||||
A command pipeline that executes a 16-bit DOS application cannot be opened
|
||||
for both reading and writing, since 16-bit DOS applications that receive
|
||||
standard input from a pipe and send standard output to a pipe run
|
||||
synchronously. Command pipelines that do not execute 16-bit DOS
|
||||
applications run asynchronously and can be opened for both reading and
|
||||
writing.
|
||||
<P>
|
||||
When running Tcl interactively, there may be some strange interactions
|
||||
between the real console, if one is present, and a command pipeline that uses
|
||||
standard input or output. If a command pipeline is opened for reading from
|
||||
a 32-bit application, some of the keystrokes entered at the console will be
|
||||
sent to the command pipeline and some will be sent to the Tcl evaluator. If
|
||||
a command pipeline is opened for writing to a 32-bit application, no output
|
||||
is visible on the console until the the pipe is closed. These problems only
|
||||
occur because both Tcl and the child application are competing for the
|
||||
console at the same time. If the command pipeline is started from a script,
|
||||
so that Tcl is not accessing the console, or if the command pipeline does
|
||||
not use standard input or output, but is redirected from or to a file, then
|
||||
the above problems do not occur.
|
||||
<P>
|
||||
Whether or not Tcl is running interactively, if a command pipeline is opened
|
||||
for reading from a 16-bit DOS application, the call to <B>open</B> will not
|
||||
return until end-of-file has been received from the command pipeline's
|
||||
standard output. If a command pipeline is opened for writing to a 16-bit DOS
|
||||
application, no data will be sent to the command pipeline's standard output
|
||||
until the pipe is actually closed. This problem occurs because 16-bit DOS
|
||||
applications are run synchronously, as described above.
|
||||
<P><DT><A NAME="M30"><B>Macintosh</B></A><DD>
|
||||
Opening a serial port is not currently implemented under Macintosh.
|
||||
<P>
|
||||
Opening a command pipeline is not supported under Macintosh, since
|
||||
applications do not support the concept of standard input or output.
|
||||
<P><DT><A NAME="M31"><B>Unix</B></A><DD>
|
||||
Valid values for <I>fileName</I> to open a serial port are generally of the
|
||||
form <B>/dev/tty</B><I>X</I>, where <I>X</I> is <B>a</B> or <B>b</B>, but the name
|
||||
of any pseudo-file that maps to a serial port may be used.
|
||||
<P>
|
||||
When running Tcl interactively, there may be some strange interactions
|
||||
between the console, if one is present, and a command pipeline that uses
|
||||
standard input. If a command pipeline is opened for reading, some
|
||||
of the lines entered at the console will be sent to the command pipeline and
|
||||
some will be sent to the Tcl evaluator. This problem only occurs because
|
||||
both Tcl and the child application are competing for the console at the
|
||||
same time. If the command pipeline is started from a script, so that Tcl is
|
||||
not accessing the console, or if the command pipeline does not use standard
|
||||
input, but is redirected from a file, then the above problem does not occur.
|
||||
<P></DL>
|
||||
<P>
|
||||
See the PORTABILITY ISSUES section of the <B><A HREF="../TkCmd/exec.htm">exec</A></B> command for additional
|
||||
information not specific to command pipelines about executing
|
||||
applications on the various platforms
|
||||
|
||||
<H3><A NAME="M32">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/close.htm">close</A></B>, <B><A HREF="../TkCmd/filename.htm">filename</A></B>, <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B>, <B><A HREF="../TkCmd/gets.htm">gets</A></B>, <B><A HREF="../TkCmd/read.htm">read</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B>, <B><A HREF="../TkCmd/exec.htm">exec</A></B>, <B>fopen</B>
|
||||
<H3><A NAME="M33">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#access mode">access mode</A>, <A href="../Keywords/A.htm#append">append</A>, <A href="../Keywords/C.htm#create">create</A>, <A href="../Keywords/F.htm#file">file</A>, <A href="../Keywords/N.htm#non-blocking">non-blocking</A>, <A href="../Keywords/O.htm#open">open</A>, <A href="../Keywords/P.htm#permissions">permissions</A>, <A href="../Keywords/P.htm#pipeline">pipeline</A>, <A href="../Keywords/P.htm#process">process</A>, <A href="../Keywords/S.htm#serial">serial</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
208
hlp/en/tcl/package.htm
Normal file
208
hlp/en/tcl/package.htm
Normal file
@@ -0,0 +1,208 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - package manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="package.htm#M2" NAME="L789">NAME</A>
|
||||
<DL><DD>package - Facilities for package loading and version control</DL>
|
||||
<DD><A HREF="package.htm#M3" NAME="L790">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>package forget ?</B><I>package package ...</I>?
|
||||
<DD><B>package ifneeded </B><I>package version</I> ?<I>script</I>?
|
||||
<DD><B>package names</B>
|
||||
<DD><B>package present </B>?<B>-exact</B>? <I>package </I>?<I>version</I>?
|
||||
<DD><B>package provide </B><I>package </I>?<I>version</I>?
|
||||
<DD><B>package require </B>?<B>-exact</B>? <I>package </I>?<I>version</I>?
|
||||
<DD><B>package unknown </B>?<I>command</I>?
|
||||
<DD><B>package vcompare </B><I>version1 version2</I>
|
||||
<DD><B>package versions </B><I>package</I>
|
||||
<DD><B>package vsatisfies </B><I>version1 version2</I>
|
||||
</DL>
|
||||
<DD><A HREF="package.htm#M4" NAME="L791">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="package.htm#M5" NAME="L792"><B>package forget ?</B><I>package package ...</I>?</A>
|
||||
<DD><A HREF="package.htm#M6" NAME="L793"><B>package ifneeded </B><I>package version</I> ?<I>script</I>?</A>
|
||||
<DD><A HREF="package.htm#M7" NAME="L794"><B>package names</B></A>
|
||||
<DD><A HREF="package.htm#M8" NAME="L795"><B>package present </B>?<B>-exact</B>? <I>package </I>?<I>version</I>?</A>
|
||||
<DD><A HREF="package.htm#M9" NAME="L796"><B>package provide </B><I>package </I>?<I>version</I>?</A>
|
||||
<DD><A HREF="package.htm#M10" NAME="L797"><B>package require </B>?<B>-exact</B>? <I>package </I>?<I>version</I>?</A>
|
||||
<DD><A HREF="package.htm#M11" NAME="L798"><B>package unknown </B>?<I>command</I>?</A>
|
||||
<DD><A HREF="package.htm#M12" NAME="L799"><B>package vcompare </B><I>version1 version2</I></A>
|
||||
<DD><A HREF="package.htm#M13" NAME="L800"><B>package versions </B><I>package</I></A>
|
||||
<DD><A HREF="package.htm#M14" NAME="L801"><B>package vsatisfies </B><I>version1 version2</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="package.htm#M15" NAME="L802">VERSION NUMBERS</A>
|
||||
<DD><A HREF="package.htm#M16" NAME="L803">PACKAGE INDICES</A>
|
||||
<DD><A HREF="package.htm#M17" NAME="L804">SEE ALSO</A>
|
||||
<DD><A HREF="package.htm#M18" NAME="L805">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
package - Facilities for package loading and version control
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>package forget ?</B><I>package package ...</I>?<BR>
|
||||
<B>package ifneeded </B><I>package version</I> ?<I>script</I>?<BR>
|
||||
<B>package names</B><BR>
|
||||
<B>package present </B>?<B>-exact</B>? <I>package </I>?<I>version</I>?<BR>
|
||||
<B>package provide </B><I>package </I>?<I>version</I>?<BR>
|
||||
<B>package require </B>?<B>-exact</B>? <I>package </I>?<I>version</I>?<BR>
|
||||
<B>package unknown </B>?<I>command</I>?<BR>
|
||||
<B>package vcompare </B><I>version1 version2</I><BR>
|
||||
<B>package versions </B><I>package</I><BR>
|
||||
<B>package vsatisfies </B><I>version1 version2</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command keeps a simple database of the packages available for
|
||||
use by the current interpreter and how to load them into the
|
||||
interpreter.
|
||||
It supports multiple versions of each package and arranges
|
||||
for the correct version of a package to be loaded based on what
|
||||
is needed by the application.
|
||||
This command also detects and reports version clashes.
|
||||
Typically, only the <B>package require</B> and <B>package provide</B>
|
||||
commands are invoked in normal Tcl scripts; the other commands are used
|
||||
primarily by system scripts that maintain the package database.
|
||||
<P>
|
||||
The behavior of the <B>package</B> command is determined by its first argument.
|
||||
The following forms are permitted:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>package forget ?</B><I>package package ...</I>?</A><DD>
|
||||
Removes all information about each specified package from this interpreter,
|
||||
including information provided by both <B>package ifneeded</B> and
|
||||
<B>package provide</B>.
|
||||
<P><DT><A NAME="M6"><B>package ifneeded </B><I>package version</I> ?<I>script</I>?</A><DD>
|
||||
This command typically appears only in system configuration
|
||||
scripts to set up the package database.
|
||||
It indicates that a particular version of
|
||||
a particular package is available if needed, and that the package
|
||||
can be added to the interpreter by executing <I>script</I>.
|
||||
The script is saved in a database for use by subsequent
|
||||
<B>package require</B> commands; typically, <I>script</I>
|
||||
sets up auto-loading for the commands in the package (or calls
|
||||
<B><A HREF="../TkCmd/load.htm">load</A></B> and/or <B><A HREF="../TkCmd/source.htm">source</A></B> directly), then invokes
|
||||
<B>package provide</B> to indicate that the package is present.
|
||||
There may be information in the database for several different
|
||||
versions of a single package.
|
||||
If the database already contains information for <I>package</I>
|
||||
and <I>version</I>, the new <I>script</I> replaces the existing
|
||||
one.
|
||||
If the <I>script</I> argument is omitted, the current script for
|
||||
version <I>version</I> of package <I>package</I> is returned,
|
||||
or an empty string if no <B>package ifneeded</B> command has
|
||||
been invoked for this <I>package</I> and <I>version</I>.
|
||||
<P><DT><A NAME="M7"><B>package names</B></A><DD>
|
||||
Returns a list of the names of all packages in the
|
||||
interpreter for which a version has been provided (via
|
||||
<B>package provide</B>) or for which a <B>package ifneeded</B>
|
||||
script is available.
|
||||
The order of elements in the list is arbitrary.
|
||||
<P><DT><A NAME="M8"><B>package present </B>?<B>-exact</B>? <I>package </I>?<I>version</I>?</A><DD>
|
||||
This command is equivalent to <B>package require</B> except that it
|
||||
does not try and load the package if it is not already loaded.
|
||||
<P><DT><A NAME="M9"><B>package provide </B><I>package </I>?<I>version</I>?</A><DD>
|
||||
This command is invoked to indicate that version <I>version</I>
|
||||
of package <I>package</I> is now present in the interpreter.
|
||||
It is typically invoked once as part of an <B>ifneeded</B> script,
|
||||
and again by the package itself when it is finally loaded.
|
||||
An error occurs if a different version of <I>package</I> has been
|
||||
provided by a previous <B>package provide</B> command.
|
||||
If the <I>version</I> argument is omitted, then the command
|
||||
returns the version number that is currently provided, or an
|
||||
empty string if no <B>package provide</B> command has been
|
||||
invoked for <I>package</I> in this interpreter.
|
||||
<P><DT><A NAME="M10"><B>package require </B>?<B>-exact</B>? <I>package </I>?<I>version</I>?</A><DD>
|
||||
This command is typically invoked by Tcl code that wishes to use
|
||||
a particular version of a particular package. The arguments
|
||||
indicate which package is wanted, and the command ensures that
|
||||
a suitable version of the package is loaded into the interpreter.
|
||||
If the command succeeds, it returns the version number that is
|
||||
loaded; otherwise it generates an error.
|
||||
If both the <B>-exact</B>
|
||||
switch and the <I>version</I> argument are specified then only the
|
||||
given version is acceptable. If <B>-exact</B> is omitted but
|
||||
<I>version</I> is specified, then versions later than <I>version</I>
|
||||
are also acceptable as long as they have the same major version
|
||||
number as <I>version</I>.
|
||||
If both <B>-exact</B> and <I>version</I> are omitted then any
|
||||
version whatsoever is acceptable.
|
||||
If a version of <I>package</I> has already been provided (by invoking
|
||||
the <B>package provide</B> command), then its version number must
|
||||
satisfy the criteria given by <B>-exact</B> and <I>version</I> and
|
||||
the command returns immediately.
|
||||
Otherwise, the command searches the database of information provided by
|
||||
previous <B>package ifneeded</B> commands to see if an acceptable
|
||||
version of the package is available.
|
||||
If so, the script for the highest acceptable version number is invoked;
|
||||
it must do whatever is necessary to load the package,
|
||||
including calling <B>package provide</B> for the package.
|
||||
If the <B>package ifneeded</B> database does not contain an acceptable
|
||||
version of the package and a <B>package unknown</B> command has been
|
||||
specified for the interpreter then that command is invoked; when
|
||||
it completes, Tcl checks again to see if the package is now provided
|
||||
or if there is a <B>package ifneeded</B> script for it.
|
||||
If all of these steps fail to provide an acceptable version of the
|
||||
package, then the command returns an error.
|
||||
<P><DT><A NAME="M11"><B>package unknown </B>?<I>command</I>?</A><DD>
|
||||
This command supplies a ``last resort'' command to invoke during
|
||||
<B>package require</B> if no suitable version of a package can be found
|
||||
in the <B>package ifneeded</B> database.
|
||||
If the <I>command</I> argument is supplied, it contains the first part
|
||||
of a command; when the command is invoked during a <B>package require</B>
|
||||
command, Tcl appends two additional arguments giving the desired package
|
||||
name and version.
|
||||
For example, if <I>command</I> is <B>foo bar</B> and later the command
|
||||
<B>package require test 2.4</B> is invoked, then Tcl will execute
|
||||
the command <B>foo bar test 2.4</B> to load the package.
|
||||
If no version number is supplied to the <B>package require</B> command,
|
||||
then the version argument for the invoked command will be an empty string.
|
||||
If the <B>package unknown</B> command is invoked without a <I>command</I>
|
||||
argument, then the current <B>package unknown</B> script is returned,
|
||||
or an empty string if there is none.
|
||||
If <I>command</I> is specified as an empty string, then the current
|
||||
<B>package unknown</B> script is removed, if there is one.
|
||||
<P><DT><A NAME="M12"><B>package vcompare </B><I>version1 version2</I></A><DD>
|
||||
Compares the two version numbers given by <I>version1</I> and <I>version2</I>.
|
||||
Returns -1 if <I>version1</I> is an earlier version than <I>version2</I>,
|
||||
0 if they are equal, and 1 if <I>version1</I> is later than <B>version2</B>.
|
||||
<P><DT><A NAME="M13"><B>package versions </B><I>package</I></A><DD>
|
||||
Returns a list of all the version numbers of <I>package</I>
|
||||
for which information has been provided by <B>package ifneeded</B>
|
||||
commands.
|
||||
<P><DT><A NAME="M14"><B>package vsatisfies </B><I>version1 version2</I></A><DD>
|
||||
Returns 1 if scripts written for <I>version2</I> will work unchanged
|
||||
with <I>version1</I> (i.e. <I>version1</I> is equal to or greater
|
||||
than <I>version2</I> and they both have the same major version
|
||||
number), 0 otherwise.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M15">VERSION NUMBERS</A></H3>
|
||||
Version numbers consist of one or more decimal numbers separated
|
||||
by dots, such as 2 or 1.162 or 3.1.13.1.
|
||||
The first number is called the major version number.
|
||||
Larger numbers correspond to later versions of a package, with
|
||||
leftmost numbers having greater significance.
|
||||
For example, version 2.1 is later than 1.3 and version
|
||||
3.4.6 is later than 3.3.5.
|
||||
Missing fields are equivalent to zeroes: version 1.3 is the
|
||||
same as version 1.3.0 and 1.3.0.0, so it is earlier than 1.3.1 or 1.3.0.2.
|
||||
A later version number is assumed to be upwards compatible with
|
||||
an earlier version number as long as both versions have the same
|
||||
major version number.
|
||||
For example, Tcl scripts written for version 2.3 of a package should
|
||||
work unchanged under versions 2.3.2, 2.4, and 2.5.1.
|
||||
Changes in the major version number signify incompatible changes:
|
||||
if code is written to use version 2.1 of a package, it is not guaranteed
|
||||
to work unmodified with either version 1.7.3 or version 3.1.
|
||||
|
||||
<H3><A NAME="M16">PACKAGE INDICES</A></H3>
|
||||
The recommended way to use packages in Tcl is to invoke <B>package require</B>
|
||||
and <B>package provide</B> commands in scripts, and use the procedure
|
||||
<B>pkg_mkIndex</B> to create package index files.
|
||||
Once you've done this, packages will be loaded automatically
|
||||
in response to <B>package require</B> commands.
|
||||
See the documentation for <B>pkg_mkIndex</B> for details.
|
||||
|
||||
<H3><A NAME="M17">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/msgcat.htm">msgcat</A></B>, <B>packagens</B>, <B>pkgMkIndex</B>
|
||||
<H3><A NAME="M18">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/P.htm#package">package</A>, <A href="../Keywords/V.htm#version">version</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
64
hlp/en/tcl/packagens.htm
Normal file
64
hlp/en/tcl/packagens.htm
Normal file
@@ -0,0 +1,64 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - pkg::create manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="packagens.htm#M2" NAME="L806">NAME</A>
|
||||
<DL><DD>pkg::create - Construct an appropriate <B>package ifneeded</B>
|
||||
command for a given package specification</DL>
|
||||
<DD><A HREF="packagens.htm#M3" NAME="L807">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>::pkg::create </B><I>-name packageName</I> <I>-version packageVersion</I> ?<I>-load filespec</I>? ... ?<I>-source filespec</I>? ...
|
||||
</DL>
|
||||
<DD><A HREF="packagens.htm#M4" NAME="L808">DESCRIPTION</A>
|
||||
<DD><A HREF="packagens.htm#M5" NAME="L809">OPTIONS</A>
|
||||
<DL>
|
||||
<DD><A HREF="packagens.htm#M6" NAME="L810"><B>-name</B> <I>packageName</I></A>
|
||||
<DD><A HREF="packagens.htm#M7" NAME="L811"><B>-version</B> <I>packageVersion</I></A>
|
||||
<DD><A HREF="packagens.htm#M8" NAME="L812"><B>-load</B> <I>filespec</I></A>
|
||||
<DD><A HREF="packagens.htm#M9" NAME="L813"><B>-source</B> <I>filespec</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="packagens.htm#M10" NAME="L814">SEE ALSO</A>
|
||||
<DD><A HREF="packagens.htm#M11" NAME="L815">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
pkg::create - Construct an appropriate <B>package ifneeded</B>
|
||||
command for a given package specification
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>::pkg::create </B><I>-name packageName</I> <I>-version packageVersion</I> ?<I>-load filespec</I>? ... ?<I>-source filespec</I>? ...<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
<B>::pkg::create</B> is a utility procedure that is part of the standard Tcl
|
||||
library. It is used to create an appropriate <B>package ifneeded</B>
|
||||
command for a given package specification. It can be used to construct a
|
||||
<B>pkgIndex.tcl</B> file for use with the <B><A HREF="../TkCmd/package.htm">package</A></B> mechanism.
|
||||
|
||||
<H3><A NAME="M5">OPTIONS</A></H3>
|
||||
The parameters supported are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>-name</B> <I>packageName</I></A><DD>
|
||||
This parameter specifies the name of the package. It is required.
|
||||
<P><DT><A NAME="M7"><B>-version</B> <I>packageVersion</I></A><DD>
|
||||
This parameter specifies the version of the package. It is required.
|
||||
<P><DT><A NAME="M8"><B>-load</B> <I>filespec</I></A><DD>
|
||||
This parameter specifies a binary library that must be loaded with the
|
||||
<B><A HREF="../TkCmd/load.htm">load</A></B> command. <I>filespec</I> is a list with two elements. The
|
||||
first element is the name of the file to load. The second, optional
|
||||
element is a list of commands supplied by loading that file. If the
|
||||
list of procedures is empty or omitted, <B>::pkg::create</B> will
|
||||
set up the library for direct loading (see <B>pkg_mkIndex</B>). Any
|
||||
number of <B>-load</B> parameters may be specified.
|
||||
<P><DT><A NAME="M9"><B>-source</B> <I>filespec</I></A><DD>
|
||||
This parameter is similar to the <B>-load</B> parameter, except that it
|
||||
specifies a Tcl library that must be loaded with the
|
||||
<B><A HREF="../TkCmd/source.htm">source</A></B> command. Any number of <B>-source</B> parameters may be
|
||||
specified.
|
||||
<P></DL>
|
||||
<P>
|
||||
At least one <B>-load</B> or <B>-source</B> paramter must be given.
|
||||
|
||||
<H3><A NAME="M10">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/package.htm">package</A></B>
|
||||
<H3><A NAME="M11">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#auto-load">auto-load</A>, <A href="../Keywords/I.htm#index">index</A>, <A href="../Keywords/P.htm#package">package</A>, <A href="../Keywords/V.htm#version">version</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1998-2000 by Scriptics Corporation.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
26
hlp/en/tcl/pid.htm
Normal file
26
hlp/en/tcl/pid.htm
Normal file
@@ -0,0 +1,26 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - pid manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
pid - Retrieve process id(s)
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>pid </B>?<I>fileId</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
If the <I>fileId</I> argument is given then it should normally
|
||||
refer to a process pipeline created with the <B><A HREF="../TkCmd/open.htm">open</A></B> command.
|
||||
In this case the <B>pid</B> command will return a list whose elements
|
||||
are the process identifiers of all the processes in the pipeline,
|
||||
in order.
|
||||
The list will be empty if <I>fileId</I> refers to an open file
|
||||
that isn't a process pipeline.
|
||||
If no <I>fileId</I> argument is given then <B>pid</B> returns the process
|
||||
identifier of the current process.
|
||||
All process identifiers are returned as decimal strings.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/exec.htm">exec</A></B>, <B><A HREF="../TkCmd/open.htm">open</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/F.htm#file">file</A>, <A href="../Keywords/P.htm#pipeline">pipeline</A>, <A href="../Keywords/P.htm#process identifier">process identifier</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
245
hlp/en/tcl/pkgMkIndex.htm
Normal file
245
hlp/en/tcl/pkgMkIndex.htm
Normal file
@@ -0,0 +1,245 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - pkg_mkIndex manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="pkgMkIndex.htm#M2" NAME="L821">NAME</A>
|
||||
<DL><DD>pkg_mkIndex - Build an index for automatic loading of packages</DL>
|
||||
<DD><A HREF="pkgMkIndex.htm#M3" NAME="L822">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>pkg_mkIndex ?</B><I>-direct</I>? ?<I>-lazy</I>? ?<I>-load pkgPat</I>? ?<I>-verbose</I>? <I>dir</I> ?<I>pattern pattern ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="pkgMkIndex.htm#M4" NAME="L823">DESCRIPTION</A>
|
||||
<DL>
|
||||
</DL>
|
||||
<DD><A HREF="pkgMkIndex.htm#M5" NAME="L824">OPTIONS</A>
|
||||
<DL>
|
||||
<DD><A HREF="pkgMkIndex.htm#M6" NAME="L825"><B>-direct</B></A>
|
||||
<DD><A HREF="pkgMkIndex.htm#M7" NAME="L826"><B>-lazy</B></A>
|
||||
<DD><A HREF="pkgMkIndex.htm#M8" NAME="L827"><B>-load </B><I>pkgPat</I></A>
|
||||
<DD><A HREF="pkgMkIndex.htm#M9" NAME="L828"><B>-verbose</B></A>
|
||||
<DD><A HREF="pkgMkIndex.htm#M10" NAME="L829"><B>--</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="pkgMkIndex.htm#M11" NAME="L830">PACKAGES AND THE AUTO-LOADER</A>
|
||||
<DD><A HREF="pkgMkIndex.htm#M12" NAME="L831">HOW IT WORKS</A>
|
||||
<DD><A HREF="pkgMkIndex.htm#M13" NAME="L832">DIRECT LOADING</A>
|
||||
<DD><A HREF="pkgMkIndex.htm#M14" NAME="L833">COMPLEX CASES</A>
|
||||
<DD><A HREF="pkgMkIndex.htm#M15" NAME="L834">SEE ALSO</A>
|
||||
<DD><A HREF="pkgMkIndex.htm#M16" NAME="L835">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
pkg_mkIndex - Build an index for automatic loading of packages
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>pkg_mkIndex ?</B><I>-direct</I>? ?<I>-lazy</I>? ?<I>-load pkgPat</I>? ?<I>-verbose</I>? <I>dir</I> ?<I>pattern pattern ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
<B>Pkg_mkIndex</B> is a utility procedure that is part of the standard
|
||||
Tcl library.
|
||||
It is used to create index files that allow packages to be loaded
|
||||
automatically when <B>package require</B> commands are executed.
|
||||
To use <B>pkg_mkIndex</B>, follow these steps:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT>[1]<DD>
|
||||
Create the package(s).
|
||||
Each package may consist of one or more Tcl script files or binary files.
|
||||
Binary files must be suitable for loading with the <B><A HREF="../TkCmd/load.htm">load</A></B> command
|
||||
with a single argument; for example, if the file is <B>test.so</B> it must
|
||||
be possible to load this file with the command <B>load test.so</B>.
|
||||
Each script file must contain a <B>package provide</B> command to declare
|
||||
the package and version number, and each binary file must contain
|
||||
a call to <B><A HREF="../TkLib/PkgRequire.htm">Tcl_PkgProvide</A></B>.
|
||||
<P><DT>[2]<DD>
|
||||
Create the index by invoking <B>pkg_mkIndex</B>.
|
||||
The <I>dir</I> argument gives the name of a directory and each
|
||||
<I>pattern</I> argument is a <B><A HREF="../TkCmd/glob.htm">glob</A></B>-style pattern that selects
|
||||
script or binary files in <I>dir</I>.
|
||||
The default pattern is <B>*.tcl</B> and <B>*.[info sharedlibextension]</B>.
|
||||
<BR>
|
||||
<B>Pkg_mkIndex</B> will create a file <B>pkgIndex.tcl</B> in <I>dir</I>
|
||||
with package information about all the files given by the <I>pattern</I>
|
||||
arguments.
|
||||
It does this by loading each file into a slave
|
||||
interpreter and seeing what packages
|
||||
and new commands appear (this is why it is essential to have
|
||||
<B>package provide</B> commands or <B><A HREF="../TkLib/PkgRequire.htm">Tcl_PkgProvide</A></B> calls
|
||||
in the files, as described above).
|
||||
If you have a package split among scripts and binary files,
|
||||
or if you have dependencies among files,
|
||||
you may have to use the <B>-load</B> option
|
||||
or adjust the order in which <B>pkg_mkIndex</B> processes
|
||||
the files. See COMPLEX CASES below.
|
||||
|
||||
<P><DT>[3]<DD>
|
||||
Install the package as a subdirectory of one of the directories given by
|
||||
the <B>tcl_pkgPath</B> variable. If <B>$tcl_pkgPath</B> contains more
|
||||
than one directory, machine-dependent packages (e.g., those that
|
||||
contain binary shared libraries) should normally be installed
|
||||
under the first directory and machine-independent packages (e.g.,
|
||||
those that contain only Tcl scripts) should be installed under the
|
||||
second directory.
|
||||
The subdirectory should include
|
||||
the package's script and/or binary files as well as the <B>pkgIndex.tcl</B>
|
||||
file. As long as the package is installed as a subdirectory of a
|
||||
directory in <B>$tcl_pkgPath</B> it will automatically be found during
|
||||
<B>package require</B> commands.
|
||||
<BR>
|
||||
If you install the package anywhere else, then you must ensure that
|
||||
the directory containing the package is in the <B>auto_path</B> global variable
|
||||
or an immediate subdirectory of one of the directories in <B>auto_path</B>.
|
||||
<B>Auto_path</B> contains a list of directories that are searched
|
||||
by both the auto-loader and the package loader; by default it
|
||||
includes <B>$tcl_pkgPath</B>.
|
||||
The package loader also checks all of the subdirectories of the
|
||||
directories in <B>auto_path</B>.
|
||||
You can add a directory to <B>auto_path</B> explicitly in your
|
||||
application, or you can add the directory to your <B>TCLLIBPATH</B>
|
||||
environment variable: if this environment variable is present,
|
||||
Tcl initializes <B>auto_path</B> from it during application startup.
|
||||
<P><DT>[4]<DD>
|
||||
Once the above steps have been taken, all you need to do to use a
|
||||
package is to invoke <B>package require</B>.
|
||||
For example, if versions 2.1, 2.3, and 3.1 of package <B>Test</B>
|
||||
have been indexed by <B>pkg_mkIndex</B>, the command
|
||||
<B>package require Test</B> will make version 3.1 available
|
||||
and the command <B>package require -exact Test 2.1</B> will
|
||||
make version 2.1 available.
|
||||
There may be many versions of a package in the various index files
|
||||
in <B>auto_path</B>, but only one will actually be loaded in a given
|
||||
interpreter, based on the first call to <B>package require</B>.
|
||||
Different versions of a package may be loaded in different
|
||||
interpreters.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M5">OPTIONS</A></H3>
|
||||
The optional switches are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>-direct</B></A><DD>
|
||||
The generated index will implement direct loading of the package
|
||||
upon <B>package require</B>. This is the default.
|
||||
<P><DT><A NAME="M7"><B>-lazy</B></A><DD>
|
||||
The generated index will manage to delay loading the package until the
|
||||
use of one of the commands provided by the package, instead of loading
|
||||
it immediately upon <B>package require</B>.
|
||||
<P><DT><A NAME="M8"><B>-load </B><I>pkgPat</I></A><DD>
|
||||
The index process will pre-load any packages that exist in the
|
||||
current interpreter and match <I>pkgPat</I> into the slave interpreter used to
|
||||
generate the index. The pattern match uses string match rules.
|
||||
See COMPLEX CASES below.
|
||||
<P><DT><A NAME="M9"><B>-verbose</B></A><DD>
|
||||
Generate output during the indexing process. Output is via
|
||||
the <B>tclLog</B> procedure, which by default prints to stderr.
|
||||
<P><DT><A NAME="M10"><B>--</B></A><DD>
|
||||
End of the flags, in case <I>dir</I> begins with a dash.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M11">PACKAGES AND THE AUTO-LOADER</A></H3>
|
||||
The package management facilities overlap somewhat with the auto-loader,
|
||||
in that both arrange for files to be loaded on-demand.
|
||||
However, package management is a higher-level mechanism that uses
|
||||
the auto-loader for the last step in the loading process.
|
||||
It is generally better to index a package with <B>pkg_mkIndex</B>
|
||||
rather than <B><A HREF="../TkCmd/library.htm">auto_mkindex</A></B> because the package mechanism provides
|
||||
version control: several versions of a package can be made available
|
||||
in the index files, with different applications using different
|
||||
versions based on <B>package require</B> commands.
|
||||
In contrast, <B><A HREF="../TkCmd/library.htm">auto_mkindex</A></B> does not understand versions so
|
||||
it can only handle a single version of each package.
|
||||
It is probably not a good idea to index a given package with both
|
||||
<B>pkg_mkIndex</B> and <B><A HREF="../TkCmd/library.htm">auto_mkindex</A></B>.
|
||||
If you use <B>pkg_mkIndex</B> to index a package, its commands cannot
|
||||
be invoked until <B>package require</B> has been used to select a
|
||||
version; in contrast, packages indexed with <B><A HREF="../TkCmd/library.htm">auto_mkindex</A></B>
|
||||
can be used immediately since there is no version control.
|
||||
|
||||
<H3><A NAME="M12">HOW IT WORKS</A></H3>
|
||||
<B>Pkg_mkIndex</B> depends on the <B>package unknown</B> command,
|
||||
the <B>package ifneeded</B> command, and the auto-loader.
|
||||
The first time a <B>package require</B> command is invoked,
|
||||
the <B>package unknown</B> script is invoked.
|
||||
This is set by Tcl initialization to a script that
|
||||
evaluates all of the <B>pkgIndex.tcl</B> files in the
|
||||
<B>auto_path</B>.
|
||||
The <B>pkgIndex.tcl</B> files contain <B>package ifneeded</B>
|
||||
commands for each version of each available package; these commands
|
||||
invoke <B>package provide</B> commands to announce the
|
||||
availability of the package, and they setup auto-loader
|
||||
information to load the files of the package.
|
||||
If the <I>-lazy</I> flag was provided when the <B>pkgIndex.tcl</B>
|
||||
was generated,
|
||||
a given file of a given version of a given package isn't
|
||||
actually loaded until the first time one of its commands
|
||||
is invoked.
|
||||
Thus, after invoking <B>package require</B> you may
|
||||
not see the package's commands in the interpreter, but you will be able
|
||||
to invoke the commands and they will be auto-loaded.
|
||||
|
||||
<H3><A NAME="M13">DIRECT LOADING</A></H3>
|
||||
Some packages, for instance packages which use namespaces and export
|
||||
commands or those which require special initialization, might select
|
||||
that their package files be loaded immediately upon <B>package require</B>
|
||||
instead of delaying the actual loading to the first use of one of the
|
||||
package's command. This is the default mode when generating the package
|
||||
index. It can be overridden by specifying the <I>-lazy</I> argument.
|
||||
|
||||
<H3><A NAME="M14">COMPLEX CASES</A></H3>
|
||||
Most complex cases of dependencies among scripts
|
||||
and binary files, and packages being split among scripts and
|
||||
binary files are handled OK. However, you may have to adjust
|
||||
the order in which files are processed by <B>pkg_mkIndex</B>.
|
||||
These issues are described in detail below.
|
||||
<P>
|
||||
If each script or file contains one package, and packages
|
||||
are only contained in one file, then things are easy.
|
||||
You simply specify all files to be indexed in any order
|
||||
with some glob patterns.
|
||||
<P>
|
||||
In general, it is OK for scripts to have dependencies on other
|
||||
packages.
|
||||
If scripts contain <B>package require</B> commands, these are
|
||||
stubbed out in the interpreter used to process the scripts,
|
||||
so these do not cause problems.
|
||||
If scripts call into other packages in global code,
|
||||
these calls are handled by a stub <B><A HREF="../TkCmd/unknown.htm">unknown</A></B> command.
|
||||
However, if scripts make variable references to other package's
|
||||
variables in global code, these will cause errors. That is
|
||||
also bad coding style.
|
||||
<P>
|
||||
If binary files have dependencies on other packages, things
|
||||
can become tricky because it is not possible to stub out
|
||||
C-level API's such as <B><A HREF="../TkLib/PkgRequire.htm">Tcl_PkgRequire</A></B> API
|
||||
when loading a binary file.
|
||||
For example, suppose the BLT package requires Tk, and expresses
|
||||
this with a call to <B><A HREF="../TkLib/PkgRequire.htm">Tcl_PkgRequire</A></B> in its <B>Blt_Init</B> routine.
|
||||
To support this, you must run <B>pkg_mkIndex</B> in an interpreter that
|
||||
has Tk loaded. You can achieve this with the
|
||||
<B>-load </B><I>pkgPat</I> option. If you specify this option,
|
||||
<B>pkg_mkIndex</B> will load any packages listed by
|
||||
<B><A HREF="../TkCmd/info.htm">info loaded</A></B> and that match <I>pkgPat</I>
|
||||
into the interpreter used to process files.
|
||||
In most cases this will satisfy the <B><A HREF="../TkLib/PkgRequire.htm">Tcl_PkgRequire</A></B> calls
|
||||
made by binary files.
|
||||
<P>
|
||||
If you are indexing two binary files and one depends on the other,
|
||||
you should specify the one that has dependencies last.
|
||||
This way the one without dependencies will get loaded and indexed,
|
||||
and then the package it provides
|
||||
will be available when the second file is processed.
|
||||
You may also need to load the first package into the
|
||||
temporary interpreter used to create the index by using
|
||||
the <B>-load</B> flag;
|
||||
it won't hurt to specify package patterns that are not yet loaded.
|
||||
<P>
|
||||
If you have a package that is split across scripts and a binary file,
|
||||
then you should avoid the <B>-load</B> flag. The problem is that
|
||||
if you load a package before computing the index it masks any
|
||||
other files that provide part of the same package.
|
||||
If you must use <B>-load</B>,
|
||||
then you must specify the scripts first; otherwise the package loaded from
|
||||
the binary file may mask the package defined by the scripts.
|
||||
|
||||
<H3><A NAME="M15">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/package.htm">package</A></B>
|
||||
<H3><A NAME="M16">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#auto-load">auto-load</A>, <A href="../Keywords/I.htm#index">index</A>, <A href="../Keywords/P.htm#package">package</A>, <A href="../Keywords/V.htm#version">version</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
66
hlp/en/tcl/proc.htm
Normal file
66
hlp/en/tcl/proc.htm
Normal file
@@ -0,0 +1,66 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - proc manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
proc - Create a Tcl procedure
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>proc </B><I>name args body</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>proc</B> command creates a new Tcl procedure named
|
||||
<I>name</I>, replacing
|
||||
any existing command or procedure there may have been by that name.
|
||||
Whenever the new command is invoked, the contents of <I>body</I> will
|
||||
be executed by the Tcl interpreter.
|
||||
Normally, <I>name</I> is unqualified
|
||||
(does not include the names of any containing namespaces),
|
||||
and the new procedure is created in the current namespace.
|
||||
If <I>name</I> includes any namespace qualifiers,
|
||||
the procedure is created in the specified namespace.
|
||||
<I>Args</I> specifies the formal arguments to the
|
||||
procedure. It consists of a list, possibly empty, each of whose
|
||||
elements specifies
|
||||
one argument. Each argument specifier is also a list with either
|
||||
one or two fields. If there is only a single field in the specifier
|
||||
then it is the name of the argument; if there are two fields, then
|
||||
the first is the argument name and the second is its default value.
|
||||
<P>
|
||||
When <I>name</I> 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 default value.
|
||||
Arguments with default values need not be
|
||||
specified in a procedure invocation. However, there must be enough
|
||||
actual arguments for all the
|
||||
formal arguments that don't have defaults, and there must not be any extra
|
||||
actual arguments. There is one special case to permit procedures with
|
||||
variable numbers of arguments. If the last formal argument has the name
|
||||
<B>args</B>, then a call to the procedure may contain more actual arguments
|
||||
than the procedure has formals. In this case, all of the actual arguments
|
||||
starting at the one that would be assigned to <B>args</B> are combined into
|
||||
a list (as if the <B><A HREF="../TkCmd/list.htm">list</A></B> command had been used); this combined value
|
||||
is assigned to the local variable <B>args</B>.
|
||||
<P>
|
||||
When <I>body</I> 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 for each of the procedure's arguments.
|
||||
Global variables can only be accessed by invoking
|
||||
the <B><A HREF="../TkCmd/global.htm">global</A></B> command or the <B><A HREF="../TkCmd/upvar.htm">upvar</A></B> command.
|
||||
Namespace variables can only be accessed by invoking
|
||||
the <B><A HREF="../TkCmd/variable.htm">variable</A></B> command or the <B><A HREF="../TkCmd/upvar.htm">upvar</A></B> command.
|
||||
<P>
|
||||
The <B>proc</B> command returns an empty string. When a procedure is
|
||||
invoked, the procedure's return value is the value specified in a
|
||||
<B><A HREF="../TkCmd/return.htm">return</A></B> command. If the procedure doesn't execute an explicit
|
||||
<B><A HREF="../TkCmd/return.htm">return</A></B>, then its return value is the value of the last command
|
||||
executed in the procedure's body.
|
||||
If an error occurs while executing the procedure
|
||||
body, then the procedure-as-a-whole will return that same error.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/info.htm">info</A></B>, <B><A HREF="../TkCmd/unknown.htm">unknown</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#argument">argument</A>, <A href="../Keywords/P.htm#procedure">procedure</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
58
hlp/en/tcl/puts.htm
Normal file
58
hlp/en/tcl/puts.htm
Normal file
@@ -0,0 +1,58 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - puts manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
puts - Write to a channel
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>puts </B>?<B>-nonewline</B>? ?<I>channelId</I>? <I>string</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Writes the characters given by <I>string</I> to the channel given
|
||||
by <I>channelId</I>.
|
||||
<I>ChannelId</I> must be a channel identifier such as returned from a
|
||||
previous invocation of <B><A HREF="../TkCmd/open.htm">open</A></B> or <B><A HREF="../TkCmd/socket.htm">socket</A></B>. It must have been opened
|
||||
for output. If no <I>channelId</I> is specified then it defaults to
|
||||
<B>stdout</B>. <B>Puts</B> normally outputs a newline character after
|
||||
<I>string</I>, but this feature may be suppressed by specifying the
|
||||
<B>-nonewline</B> switch.
|
||||
<P>
|
||||
Newline characters in the output are translated by <B>puts</B> to
|
||||
platform-specific end-of-line sequences according to the current
|
||||
value of the <B>-translation</B> option for the channel (for example,
|
||||
on PCs newlines are normally replaced with carriage-return-linefeed
|
||||
sequences; on Macintoshes newlines are normally replaced with
|
||||
carriage-returns).
|
||||
See the <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> manual entry for a discussion on ways in
|
||||
which <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> will alter output.
|
||||
<P>
|
||||
Tcl buffers output internally, so characters written with <B>puts</B>
|
||||
may not appear immediately on the output file or device; Tcl will
|
||||
normally delay output until the buffer is full or the channel is
|
||||
closed.
|
||||
You can force output to appear immediately with the <B><A HREF="../TkCmd/flush.htm">flush</A></B>
|
||||
command.
|
||||
<P>
|
||||
When the output buffer fills up, the <B>puts</B> command will normally
|
||||
block until all the buffered data has been accepted for output by the
|
||||
operating system.
|
||||
If <I>channelId</I> is in nonblocking mode then the <B>puts</B> command
|
||||
will not block even if the operating system cannot accept the data.
|
||||
Instead, Tcl continues to buffer the data and writes it in the
|
||||
background as fast as the underlying file or device can accept it.
|
||||
The application must use the Tcl event loop for nonblocking output
|
||||
to work; otherwise Tcl never finds out that the file or device is
|
||||
ready for more output data.
|
||||
It is possible for an arbitrarily large amount of data to be
|
||||
buffered for a channel in nonblocking mode, which could consume a
|
||||
large amount of memory.
|
||||
To avoid wasting memory, nonblocking I/O should normally
|
||||
be used in an event-driven fashion with the <B><A HREF="../TkCmd/fileevent.htm">fileevent</A></B> command
|
||||
(don't invoke <B>puts</B> unless you have recently been notified
|
||||
via a file event that the channel is ready for more output data).
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/fileevent.htm">fileevent</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/N.htm#newline">newline</A>, <A href="../Keywords/O.htm#output">output</A>, <A href="../Keywords/W.htm#write">write</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
17
hlp/en/tcl/pwd.htm
Normal file
17
hlp/en/tcl/pwd.htm
Normal file
@@ -0,0 +1,17 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - pwd manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
pwd - Return the current working directory
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>pwd</B><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Returns the path name of the current working directory.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/cd.htm">cd</A></B>, <B><A HREF="../TkCmd/glob.htm">glob</A></B>, <B><A HREF="../TkCmd/filename.htm">filename</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/W.htm#working directory">working directory</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
941
hlp/en/tcl/re_syntax.htm
Normal file
941
hlp/en/tcl/re_syntax.htm
Normal file
@@ -0,0 +1,941 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - re_syntax manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="re_syntax.htm#M2" NAME="L851">NAME</A>
|
||||
<DL><DD>re_syntax - Syntax of Tcl regular expressions.</DL>
|
||||
<DD><A HREF="re_syntax.htm#M3" NAME="L852">DESCRIPTION</A>
|
||||
<DD><A HREF="re_syntax.htm#M4" NAME="L853">DIFFERENT FLAVORS OF REs</A>
|
||||
<DD><A HREF="re_syntax.htm#M5" NAME="L854">REGULAR EXPRESSION SYNTAX</A>
|
||||
<DL>
|
||||
<DD><A HREF="re_syntax.htm#M6" NAME="L855"><B>*</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M7" NAME="L856"><B>+</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M8" NAME="L857"><B>?</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M9" NAME="L858"><B>{</B><I>m</I><B>}</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M10" NAME="L859"><B>{</B><I>m</I><B>,}</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M11" NAME="L860"><B>{</B><I>m</I><B>,</B><I>n</I><B>}</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M12" NAME="L861"><B>*? +? ?? {</B><I>m</I><B>}? {</B><I>m</I><B>,}? {</B><I>m</I><B>,</B><I>n</I><B>}?</B></A>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="re_syntax.htm#M13" NAME="L862"><B>(</B><I>re</I><B>)</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M14" NAME="L863"><B>(?:</B><I>re</I><B>)</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M15" NAME="L864"><B>()</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M16" NAME="L865"><B>(?:)</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M17" NAME="L866"><B>[</B><I>chars</I><B>]</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M18" NAME="L867"><B>.</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M19" NAME="L868"><B>\</B><I>k</I></A>
|
||||
<DD><A HREF="re_syntax.htm#M20" NAME="L869"><B>\</B><I>c</I></A>
|
||||
<DD><A HREF="re_syntax.htm#M21" NAME="L870"><B>{</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M22" NAME="L871"><I>x</I></A>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="re_syntax.htm#M23" NAME="L872"><B>^</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M24" NAME="L873"><B>$</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M25" NAME="L874"><B>(?=</B><I>re</I><B>)</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M26" NAME="L875"><B>(?!</B><I>re</I><B>)</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="re_syntax.htm#M27" NAME="L876">BRACKET EXPRESSIONS</A>
|
||||
<DD><A HREF="re_syntax.htm#M28" NAME="L877">ESCAPES</A>
|
||||
<DL>
|
||||
<DD><A HREF="re_syntax.htm#M29" NAME="L878"><B>\a</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M30" NAME="L879"><B>\b</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M31" NAME="L880"><B>\B</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M32" NAME="L881"><B>\c</B><I>X</I></A>
|
||||
<DD><A HREF="re_syntax.htm#M33" NAME="L882"><B>\e</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M34" NAME="L883"><B>\f</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M35" NAME="L884"><B>\n</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M36" NAME="L885"><B>\r</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M37" NAME="L886"><B>\t</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M38" NAME="L887"><B>\u</B><I>wxyz</I></A>
|
||||
<DD><A HREF="re_syntax.htm#M39" NAME="L888"><B>\U</B><I>stuvwxyz</I></A>
|
||||
<DD><A HREF="re_syntax.htm#M40" NAME="L889"><B>\v</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M41" NAME="L890"><B>\x</B><I>hhh</I></A>
|
||||
<DD><A HREF="re_syntax.htm#M42" NAME="L891"><B>\0</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M43" NAME="L892"><B>\</B><I>xy</I></A>
|
||||
<DD><A HREF="re_syntax.htm#M44" NAME="L893"><B>\</B><I>xyz</I></A>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="re_syntax.htm#M45" NAME="L894"><B>\d</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M46" NAME="L895"><B>\s</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M47" NAME="L896"><B>\w</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M48" NAME="L897"><B>\D</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M49" NAME="L898"><B>\S</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M50" NAME="L899"><B>\W</B></A>
|
||||
</DL>
|
||||
<DL>
|
||||
<DD><A HREF="re_syntax.htm#M51" NAME="L900"><B>\A</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M52" NAME="L901"><B>\m</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M53" NAME="L902"><B>\M</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M54" NAME="L903"><B>\y</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M55" NAME="L904"><B>\Y</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M56" NAME="L905"><B>\Z</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M57" NAME="L906"><B>\</B><I>m</I></A>
|
||||
<DD><A HREF="re_syntax.htm#M58" NAME="L907"><B>\</B><I>mnn</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="re_syntax.htm#M59" NAME="L908">METASYNTAX</A>
|
||||
<DL>
|
||||
<DD><A HREF="re_syntax.htm#M60" NAME="L909"><B>b</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M61" NAME="L910"><B>c</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M62" NAME="L911"><B>e</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M63" NAME="L912"><B>i</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M64" NAME="L913"><B>m</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M65" NAME="L914"><B>n</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M66" NAME="L915"><B>p</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M67" NAME="L916"><B>q</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M68" NAME="L917"><B>s</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M69" NAME="L918"><B>t</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M70" NAME="L919"><B>w</B></A>
|
||||
<DD><A HREF="re_syntax.htm#M71" NAME="L920"><B>x</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="re_syntax.htm#M72" NAME="L921">MATCHING</A>
|
||||
<DD><A HREF="re_syntax.htm#M73" NAME="L922">LIMITS AND COMPATIBILITY</A>
|
||||
<DD><A HREF="re_syntax.htm#M74" NAME="L923">BASIC REGULAR EXPRESSIONS</A>
|
||||
<DD><A HREF="re_syntax.htm#M75" NAME="L924">SEE ALSO</A>
|
||||
<DD><A HREF="re_syntax.htm#M76" NAME="L925">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
re_syntax - Syntax of Tcl regular expressions.
|
||||
<H3><A NAME="M3">DESCRIPTION</A></H3>
|
||||
A <I>regular expression</I> describes strings of characters.
|
||||
It's a pattern that matches certain strings and doesn't match others.
|
||||
|
||||
<H3><A NAME="M4">DIFFERENT FLAVORS OF REs</A></H3>
|
||||
Regular expressions (``RE''s), as defined by POSIX, come in two
|
||||
flavors: <I>extended</I> REs (``EREs'') and <I>basic</I> REs (``BREs'').
|
||||
EREs are roughly those of the traditional <I>egrep</I>, while BREs are
|
||||
roughly those of the traditional <I>ed</I>. This implementation adds
|
||||
a third flavor, <I>advanced</I> REs (``AREs''), basically EREs with
|
||||
some significant extensions.
|
||||
<P>
|
||||
This manual page primarily describes AREs. BREs mostly exist for
|
||||
backward compatibility in some old programs; they will be discussed at
|
||||
the end. POSIX EREs are almost an exact subset of AREs. Features of
|
||||
AREs that are not present in EREs will be indicated.
|
||||
|
||||
<H3><A NAME="M5">REGULAR EXPRESSION SYNTAX</A></H3>
|
||||
Tcl regular expressions are implemented using the package written by
|
||||
Henry Spencer, based on the 1003.2 spec and some (not quite all) of
|
||||
the Perl5 extensions (thanks, Henry!). Much of the description of
|
||||
regular expressions below is copied verbatim from his manual entry.
|
||||
<P>
|
||||
An ARE is one or more <I>branches</I>,
|
||||
separated by `<B>|</B>',
|
||||
matching anything that matches any of the branches.
|
||||
<P>
|
||||
A branch is zero or more <I>constraints</I> or <I>quantified atoms</I>,
|
||||
concatenated.
|
||||
It matches a match for the first, followed by a match for the second, etc;
|
||||
an empty branch matches the empty string.
|
||||
<P>
|
||||
A quantified atom is an <I>atom</I> possibly followed
|
||||
by a single <I>quantifier</I>.
|
||||
Without a quantifier, it matches a match for the atom.
|
||||
The quantifiers,
|
||||
and what a so-quantified atom matches, are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>*</B></A><DD>
|
||||
a sequence of 0 or more matches of the atom
|
||||
<P><DT><A NAME="M7"><B>+</B></A><DD>
|
||||
a sequence of 1 or more matches of the atom
|
||||
<P><DT><A NAME="M8"><B>?</B></A><DD>
|
||||
a sequence of 0 or 1 matches of the atom
|
||||
<P><DT><A NAME="M9"><B>{</B><I>m</I><B>}</B></A><DD>
|
||||
a sequence of exactly <I>m</I> matches of the atom
|
||||
<P><DT><A NAME="M10"><B>{</B><I>m</I><B>,}</B></A><DD>
|
||||
a sequence of <I>m</I> or more matches of the atom
|
||||
<P><DT><A NAME="M11"><B>{</B><I>m</I><B>,</B><I>n</I><B>}</B></A><DD>
|
||||
a sequence of <I>m</I> through <I>n</I> (inclusive) matches of the atom;
|
||||
<I>m</I> may not exceed <I>n</I>
|
||||
<P><DT><A NAME="M12"><B>*? +? ?? {</B><I>m</I><B>}? {</B><I>m</I><B>,}? {</B><I>m</I><B>,</B><I>n</I><B>}?</B></A><DD>
|
||||
<I>non-greedy</I> quantifiers,
|
||||
which match the same possibilities,
|
||||
but prefer the smallest number rather than the largest number
|
||||
of matches (see MATCHING)
|
||||
<P></DL>
|
||||
<P>
|
||||
The forms using
|
||||
<B>{</B> and <B>}</B>
|
||||
are known as <I>bound</I>s.
|
||||
The numbers
|
||||
<I>m</I> and <I>n</I> are unsigned decimal integers
|
||||
with permissible values from 0 to 255 inclusive.
|
||||
<P>
|
||||
An atom is one of:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M13"><B>(</B><I>re</I><B>)</B></A><DD>
|
||||
(where <I>re</I> is any regular expression)
|
||||
matches a match for
|
||||
<I>re</I>, with the match noted for possible reporting
|
||||
<P><DT><A NAME="M14"><B>(?:</B><I>re</I><B>)</B></A><DD>
|
||||
as previous,
|
||||
but does no reporting
|
||||
(a ``non-capturing'' set of parentheses)
|
||||
<P><DT><A NAME="M15"><B>()</B></A><DD>
|
||||
matches an empty string,
|
||||
noted for possible reporting
|
||||
<P><DT><A NAME="M16"><B>(?:)</B></A><DD>
|
||||
matches an empty string,
|
||||
without reporting
|
||||
<P><DT><A NAME="M17"><B>[</B><I>chars</I><B>]</B></A><DD>
|
||||
a <I>bracket expression</I>,
|
||||
matching any one of the <I>chars</I> (see BRACKET EXPRESSIONS for more detail)
|
||||
<P><DT><A NAME="M18"><B>.</B></A><DD>
|
||||
matches any single character
|
||||
<P><DT><A NAME="M19"><B>\</B><I>k</I></A><DD>
|
||||
(where <I>k</I> is a non-alphanumeric character)
|
||||
matches that character taken as an ordinary character,
|
||||
e.g. \\ matches a backslash character
|
||||
<P><DT><A NAME="M20"><B>\</B><I>c</I></A><DD>
|
||||
where <I>c</I> is alphanumeric
|
||||
(possibly followed by other characters),
|
||||
an <I>escape</I> (AREs only),
|
||||
see ESCAPES below
|
||||
<P><DT><A NAME="M21"><B>{</B></A><DD>
|
||||
when followed by a character other than a digit,
|
||||
matches the left-brace character `<B>{</B>';
|
||||
when followed by a digit, it is the beginning of a
|
||||
<I>bound</I> (see above)
|
||||
<P><DT><A NAME="M22"><I>x</I></A><DD>
|
||||
where <I>x</I> is
|
||||
a single character with no other significance, matches that character.
|
||||
<P></DL>
|
||||
<P>
|
||||
A <I>constraint</I> matches an empty string when specific conditions
|
||||
are met.
|
||||
A constraint may not be followed by a quantifier.
|
||||
The simple constraints are as follows; some more constraints are
|
||||
described later, under ESCAPES.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M23"><B>^</B></A><DD>
|
||||
matches at the beginning of a line
|
||||
<P><DT><A NAME="M24"><B>$</B></A><DD>
|
||||
matches at the end of a line
|
||||
<P><DT><A NAME="M25"><B>(?=</B><I>re</I><B>)</B></A><DD>
|
||||
<I>positive lookahead</I> (AREs only), matches at any point
|
||||
where a substring matching <I>re</I> begins
|
||||
<P><DT><A NAME="M26"><B>(?!</B><I>re</I><B>)</B></A><DD>
|
||||
<I>negative lookahead</I> (AREs only), matches at any point
|
||||
where no substring matching <I>re</I> begins
|
||||
<P></DL>
|
||||
<P>
|
||||
The lookahead constraints may not contain back references (see later),
|
||||
and all parentheses within them are considered non-capturing.
|
||||
<P>
|
||||
An RE may not end with `<B>\</B>'.
|
||||
|
||||
<H3><A NAME="M27">BRACKET EXPRESSIONS</A></H3>
|
||||
A <I>bracket expression</I> is a list of characters enclosed in `<B>[ ]</B>'.
|
||||
It normally matches any single character from the list (but see below).
|
||||
If the list begins with `<B>^</B>',
|
||||
it matches any single character
|
||||
(but see below) <I>not</I> from the rest of the list.
|
||||
<P>
|
||||
If two characters in the list are separated by `<B>-</B>',
|
||||
this is shorthand
|
||||
for the full <I>range</I> of characters between those two (inclusive) in the
|
||||
collating sequence,
|
||||
e.g.
|
||||
<B>[0-9]</B>
|
||||
in ASCII matches any decimal digit.
|
||||
Two ranges may not share an
|
||||
endpoint, so e.g.
|
||||
<B>a-c-e</B>
|
||||
is illegal.
|
||||
Ranges are very collating-sequence-dependent,
|
||||
and portable programs should avoid relying on them.
|
||||
<P>
|
||||
To include a literal
|
||||
<B>]</B>
|
||||
or
|
||||
<B>-</B>
|
||||
in the list,
|
||||
the simplest method is to
|
||||
enclose it in
|
||||
<B>[.</B> and <B>.]</B>
|
||||
to make it a collating element (see below).
|
||||
Alternatively,
|
||||
make it the first character
|
||||
(following a possible `<B>^</B>'),
|
||||
or (AREs only) precede it with `<B>\</B>'.
|
||||
Alternatively, for `<B>-</B>',
|
||||
make it the last character,
|
||||
or the second endpoint of a range.
|
||||
To use a literal
|
||||
<B>-</B>
|
||||
as the first endpoint of a range,
|
||||
make it a collating element
|
||||
or (AREs only) precede it with `<B>\</B>'.
|
||||
With the exception of these, some combinations using
|
||||
<B>[</B>
|
||||
(see next
|
||||
paragraphs), and escapes,
|
||||
all other special characters lose their
|
||||
special significance within a bracket expression.
|
||||
<P>
|
||||
Within a bracket expression, a collating element (a character,
|
||||
a multi-character sequence that collates as if it were a single character,
|
||||
or a collating-sequence name for either)
|
||||
enclosed in
|
||||
<B>[.</B> and <B>.]</B>
|
||||
stands for the
|
||||
sequence of characters of that collating element.
|
||||
The sequence is a single element of the bracket expression's list.
|
||||
A bracket expression in a locale that has
|
||||
multi-character collating elements
|
||||
can thus match more than one character.
|
||||
So (insidiously), a bracket expression that starts with <B>^</B>
|
||||
can match multi-character collating elements even if none of them
|
||||
appear in the bracket expression!
|
||||
(<I>Note:</I> Tcl currently has no multi-character collating elements.
|
||||
This information is only for illustration.)
|
||||
<P>
|
||||
For example, assume the collating sequence includes a <B>ch</B>
|
||||
multi-character collating element.
|
||||
Then the RE <B>[[.ch.]]*c</B> (zero or more <B>ch</B>'s followed by <B>c</B>)
|
||||
matches the first five characters of `<B>chchcc</B>'.
|
||||
Also, the RE <B>[^c]b</B> matches all of `<B>chb</B>'
|
||||
(because <B>[^c]</B> matches the multi-character <B>ch</B>).
|
||||
<P>
|
||||
Within a bracket expression, a collating element enclosed in
|
||||
<B>[=</B>
|
||||
and
|
||||
<B>=]</B>
|
||||
is an equivalence class, standing for the sequences of characters
|
||||
of all collating elements equivalent to that one, including itself.
|
||||
(If there are no other equivalent collating elements,
|
||||
the treatment is as if the enclosing delimiters were `<B>[.</B>'
|
||||
and `<B>.]</B>'.)
|
||||
For example, if
|
||||
<B>o</B>
|
||||
and
|
||||
<B>ô</B>
|
||||
are the members of an equivalence class,
|
||||
then `<B>[[=o=]]</B>', `<B>[[=ô=]]</B>',
|
||||
and `<B>[oô]</B>'
|
||||
are all synonymous.
|
||||
An equivalence class may not be an endpoint
|
||||
of a range.
|
||||
(<I>Note:</I>
|
||||
Tcl currently implements only the Unicode locale.
|
||||
It doesn't define any equivalence classes.
|
||||
The examples above are just illustrations.)
|
||||
<P>
|
||||
Within a bracket expression, the name of a <I>character class</I> enclosed
|
||||
in
|
||||
<B>[:</B>
|
||||
and
|
||||
<B>:]</B>
|
||||
stands for the list of all characters
|
||||
(not all collating elements!)
|
||||
belonging to that
|
||||
class.
|
||||
Standard character classes are:
|
||||
<P>
|
||||
<DL><P><DD>
|
||||
<B>alpha</B> A letter.
|
||||
<B>upper</B> An upper-case letter.
|
||||
<B><A HREF="../TclCmd/lower.htm">lower</A></B> A lower-case letter.
|
||||
<B>digit</B> A decimal digit.
|
||||
<B>xdigit</B> A hexadecimal digit.
|
||||
<B>alnum</B> An alphanumeric (letter or digit).
|
||||
<B>print</B> An alphanumeric (same as alnum).
|
||||
<B>blank</B> A space or tab character.
|
||||
<B>space</B> A character producing white space in displayed text.
|
||||
<B>punct</B> A punctuation character.
|
||||
<B>graph</B> A character with a visible representation.
|
||||
<B>cntrl</B> A control character.
|
||||
</DL>
|
||||
<P>
|
||||
A locale may provide others.
|
||||
(Note that the current Tcl implementation has only one locale:
|
||||
the Unicode locale.)
|
||||
A character class may not be used as an endpoint of a range.
|
||||
<P>
|
||||
There are two special cases of bracket expressions:
|
||||
the bracket expressions
|
||||
<B>[[:<:]]</B>
|
||||
and
|
||||
<B>[[:>:]]</B>
|
||||
are constraints, matching empty strings at
|
||||
the beginning and end of a word respectively.
|
||||
A word is defined as a sequence of
|
||||
word characters
|
||||
that is neither preceded nor followed by
|
||||
word characters.
|
||||
A word character is an
|
||||
<I>alnum</I>
|
||||
character
|
||||
or an underscore
|
||||
(<B>_</B>).
|
||||
These special bracket expressions are deprecated;
|
||||
users of AREs should use constraint escapes instead (see below).
|
||||
<H3><A NAME="M28">ESCAPES</A></H3>
|
||||
Escapes (AREs only), which begin with a
|
||||
<B>\</B>
|
||||
followed by an alphanumeric character,
|
||||
come in several varieties:
|
||||
character entry, class shorthands, constraint escapes, and back references.
|
||||
A
|
||||
<B>\</B>
|
||||
followed by an alphanumeric character but not constituting
|
||||
a valid escape is illegal in AREs.
|
||||
In EREs, there are no escapes:
|
||||
outside a bracket expression,
|
||||
a
|
||||
<B>\</B>
|
||||
followed by an alphanumeric character merely stands for that
|
||||
character as an ordinary character,
|
||||
and inside a bracket expression,
|
||||
<B>\</B>
|
||||
is an ordinary character.
|
||||
(The latter is the one actual incompatibility between EREs and AREs.)
|
||||
<P>
|
||||
Character-entry escapes (AREs only) exist to make it easier to specify
|
||||
non-printing and otherwise inconvenient characters in REs:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M29"><B>\a</B></A><DD>
|
||||
alert (bell) character, as in C
|
||||
<P><DT><A NAME="M30"><B>\b</B></A><DD>
|
||||
backspace, as in C
|
||||
<P><DT><A NAME="M31"><B>\B</B></A><DD>
|
||||
synonym for
|
||||
<B>\</B>
|
||||
to help reduce backslash doubling in some
|
||||
applications where there are multiple levels of backslash processing
|
||||
<P><DT><A NAME="M32"><B>\c</B><I>X</I></A><DD>
|
||||
(where X is any character) the character whose
|
||||
low-order 5 bits are the same as those of
|
||||
<I>X</I>,
|
||||
and whose other bits are all zero
|
||||
<P><DT><A NAME="M33"><B>\e</B></A><DD>
|
||||
the character whose collating-sequence name
|
||||
is `<B>ESC</B>',
|
||||
or failing that, the character with octal value 033
|
||||
<P><DT><A NAME="M34"><B>\f</B></A><DD>
|
||||
formfeed, as in C
|
||||
<P><DT><A NAME="M35"><B>\n</B></A><DD>
|
||||
newline, as in C
|
||||
<P><DT><A NAME="M36"><B>\r</B></A><DD>
|
||||
carriage return, as in C
|
||||
<P><DT><A NAME="M37"><B>\t</B></A><DD>
|
||||
horizontal tab, as in C
|
||||
<P><DT><A NAME="M38"><B>\u</B><I>wxyz</I></A><DD>
|
||||
(where
|
||||
<I>wxyz</I>
|
||||
is exactly four hexadecimal digits)
|
||||
the Unicode character
|
||||
<B>U+</B><I>wxyz</I>
|
||||
in the local byte ordering
|
||||
<P><DT><A NAME="M39"><B>\U</B><I>stuvwxyz</I></A><DD>
|
||||
(where
|
||||
<I>stuvwxyz</I>
|
||||
is exactly eight hexadecimal digits)
|
||||
reserved for a somewhat-hypothetical Unicode extension to 32 bits
|
||||
<P><DT><A NAME="M40"><B>\v</B></A><DD>
|
||||
vertical tab, as in C
|
||||
are all available.
|
||||
<P><DT><A NAME="M41"><B>\x</B><I>hhh</I></A><DD>
|
||||
(where
|
||||
<I>hhh</I>
|
||||
is any sequence of hexadecimal digits)
|
||||
the character whose hexadecimal value is
|
||||
<B>0x</B><I>hhh</I>
|
||||
(a single character no matter how many hexadecimal digits are used).
|
||||
<P><DT><A NAME="M42"><B>\0</B></A><DD>
|
||||
the character whose value is
|
||||
<B>0</B>
|
||||
<P><DT><A NAME="M43"><B>\</B><I>xy</I></A><DD>
|
||||
(where
|
||||
<I>xy</I>
|
||||
is exactly two octal digits,
|
||||
and is not a
|
||||
<I>back reference</I> (see below))
|
||||
the character whose octal value is
|
||||
<B>0</B><I>xy</I>
|
||||
<P><DT><A NAME="M44"><B>\</B><I>xyz</I></A><DD>
|
||||
(where
|
||||
<I>xyz</I>
|
||||
is exactly three octal digits,
|
||||
and is not a
|
||||
back reference (see below))
|
||||
the character whose octal value is
|
||||
<B>0</B><I>xyz</I>
|
||||
<P></DL>
|
||||
<P>
|
||||
Hexadecimal digits are `<B>0</B>'-`<B>9</B>', `<B>a</B>'-`<B>f</B>',
|
||||
and `<B>A</B>'-`<B>F</B>'.
|
||||
Octal digits are `<B>0</B>'-`<B>7</B>'.
|
||||
<P>
|
||||
The character-entry escapes are always taken as ordinary characters.
|
||||
For example,
|
||||
<B>\135</B>
|
||||
is
|
||||
<B>]</B>
|
||||
in ASCII,
|
||||
but
|
||||
<B>\135</B>
|
||||
does not terminate a bracket expression.
|
||||
Beware, however, that some applications (e.g., C compilers) interpret
|
||||
such sequences themselves before the regular-expression package
|
||||
gets to see them, which may require doubling (quadrupling, etc.) the `<B>\</B>'.
|
||||
<P>
|
||||
Class-shorthand escapes (AREs only) provide shorthands for certain commonly-used
|
||||
character classes:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M45"><B>\d</B></A><DD>
|
||||
<B>[[:digit:]]</B>
|
||||
<P><DT><A NAME="M46"><B>\s</B></A><DD>
|
||||
<B>[[:space:]]</B>
|
||||
<P><DT><A NAME="M47"><B>\w</B></A><DD>
|
||||
<B>[[:alnum:]_]</B>
|
||||
(note underscore)
|
||||
<P><DT><A NAME="M48"><B>\D</B></A><DD>
|
||||
<B>[^[:digit:]]</B>
|
||||
<P><DT><A NAME="M49"><B>\S</B></A><DD>
|
||||
<B>[^[:space:]]</B>
|
||||
<P><DT><A NAME="M50"><B>\W</B></A><DD>
|
||||
<B>[^[:alnum:]_]</B>
|
||||
(note underscore)
|
||||
<P></DL>
|
||||
<P>
|
||||
Within bracket expressions, `<B>\d</B>', `<B>\s</B>',
|
||||
and `<B>\w</B>'
|
||||
lose their outer brackets,
|
||||
and `<B>\D</B>', `<B>\S</B>',
|
||||
and `<B>\W</B>'
|
||||
are illegal.
|
||||
(So, for example, <B>[a-c\d]</B> is equivalent to <B>[a-c[:digit:]]</B>.
|
||||
Also, <B>[a-c\D]</B>, which is equivalent to <B>[a-c^[:digit:]]</B>, is illegal.)
|
||||
<P>
|
||||
A constraint escape (AREs only) is a constraint,
|
||||
matching the empty string if specific conditions are met,
|
||||
written as an escape:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M51"><B>\A</B></A><DD>
|
||||
matches only at the beginning of the string
|
||||
(see MATCHING, below, for how this differs from `<B>^</B>')
|
||||
<P><DT><A NAME="M52"><B>\m</B></A><DD>
|
||||
matches only at the beginning of a word
|
||||
<P><DT><A NAME="M53"><B>\M</B></A><DD>
|
||||
matches only at the end of a word
|
||||
<P><DT><A NAME="M54"><B>\y</B></A><DD>
|
||||
matches only at the beginning or end of a word
|
||||
<P><DT><A NAME="M55"><B>\Y</B></A><DD>
|
||||
matches only at a point that is not the beginning or end of a word
|
||||
<P><DT><A NAME="M56"><B>\Z</B></A><DD>
|
||||
matches only at the end of the string
|
||||
(see MATCHING, below, for how this differs from `<B>$</B>')
|
||||
<P><DT><A NAME="M57"><B>\</B><I>m</I></A><DD>
|
||||
(where
|
||||
<I>m</I>
|
||||
is a nonzero digit) a <I>back reference</I>, see below
|
||||
<P><DT><A NAME="M58"><B>\</B><I>mnn</I></A><DD>
|
||||
(where
|
||||
<I>m</I>
|
||||
is a nonzero digit, and
|
||||
<I>nn</I>
|
||||
is some more digits,
|
||||
and the decimal value
|
||||
<I>mnn</I>
|
||||
is not greater than the number of closing capturing parentheses seen so far)
|
||||
a <I>back reference</I>, see below
|
||||
<P></DL>
|
||||
<P>
|
||||
A word is defined as in the specification of
|
||||
<B>[[:<:]]</B>
|
||||
and
|
||||
<B>[[:>:]]</B>
|
||||
above.
|
||||
Constraint escapes are illegal within bracket expressions.
|
||||
<P>
|
||||
A back reference (AREs only) matches the same string matched by the parenthesized
|
||||
subexpression specified by the number,
|
||||
so that (e.g.)
|
||||
<B>([bc])\1</B>
|
||||
matches
|
||||
<B>bb</B>
|
||||
or
|
||||
<B>cc</B>
|
||||
but not `<B>bc</B>'.
|
||||
The subexpression must entirely precede the back reference in the RE.
|
||||
Subexpressions are numbered in the order of their leading parentheses.
|
||||
Non-capturing parentheses do not define subexpressions.
|
||||
<P>
|
||||
There is an inherent historical ambiguity between octal character-entry
|
||||
escapes and back references, which is resolved by heuristics,
|
||||
as hinted at above.
|
||||
A leading zero always indicates an octal escape.
|
||||
A single non-zero digit, not followed by another digit,
|
||||
is always taken as a back reference.
|
||||
A multi-digit sequence not starting with a zero is taken as a back
|
||||
reference if it comes after a suitable subexpression
|
||||
(i.e. the number is in the legal range for a back reference),
|
||||
and otherwise is taken as octal.
|
||||
<H3><A NAME="M59">METASYNTAX</A></H3>
|
||||
In addition to the main syntax described above, there are some special
|
||||
forms and miscellaneous syntactic facilities available.
|
||||
<P>
|
||||
Normally the flavor of RE being used is specified by
|
||||
application-dependent means.
|
||||
However, this can be overridden by a <I>director</I>.
|
||||
If an RE of any flavor begins with `<B>***:</B>',
|
||||
the rest of the RE is an ARE.
|
||||
If an RE of any flavor begins with `<B>***=</B>',
|
||||
the rest of the RE is taken to be a literal string,
|
||||
with all characters considered ordinary characters.
|
||||
<P>
|
||||
An ARE may begin with <I>embedded options</I>:
|
||||
a sequence
|
||||
<B>(?</B><I>xyz</I><B>)</B>
|
||||
(where
|
||||
<I>xyz</I>
|
||||
is one or more alphabetic characters)
|
||||
specifies options affecting the rest of the RE.
|
||||
These supplement, and can override,
|
||||
any options specified by the application.
|
||||
The available option letters are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M60"><B>b</B></A><DD>
|
||||
rest of RE is a BRE
|
||||
<P><DT><A NAME="M61"><B>c</B></A><DD>
|
||||
case-sensitive matching (usual default)
|
||||
<P><DT><A NAME="M62"><B>e</B></A><DD>
|
||||
rest of RE is an ERE
|
||||
<P><DT><A NAME="M63"><B>i</B></A><DD>
|
||||
case-insensitive matching (see MATCHING, below)
|
||||
<P><DT><A NAME="M64"><B>m</B></A><DD>
|
||||
historical synonym for
|
||||
<B>n</B>
|
||||
<P><DT><A NAME="M65"><B>n</B></A><DD>
|
||||
newline-sensitive matching (see MATCHING, below)
|
||||
<P><DT><A NAME="M66"><B>p</B></A><DD>
|
||||
partial newline-sensitive matching (see MATCHING, below)
|
||||
<P><DT><A NAME="M67"><B>q</B></A><DD>
|
||||
rest of RE is a literal (``quoted'') string, all ordinary characters
|
||||
<P><DT><A NAME="M68"><B>s</B></A><DD>
|
||||
non-newline-sensitive matching (usual default)
|
||||
<P><DT><A NAME="M69"><B>t</B></A><DD>
|
||||
tight syntax (usual default; see below)
|
||||
<P><DT><A NAME="M70"><B>w</B></A><DD>
|
||||
inverse partial newline-sensitive (``weird'') matching (see MATCHING, below)
|
||||
<P><DT><A NAME="M71"><B>x</B></A><DD>
|
||||
expanded syntax (see below)
|
||||
<P></DL>
|
||||
<P>
|
||||
Embedded options take effect at the
|
||||
<B>)</B>
|
||||
terminating the sequence.
|
||||
They are available only at the start of an ARE,
|
||||
and may not be used later within it.
|
||||
<P>
|
||||
In addition to the usual (<I>tight</I>) RE syntax, in which all characters are
|
||||
significant, there is an <I>expanded</I> syntax,
|
||||
available in all flavors of RE
|
||||
with the <B>-expanded</B> switch, or in AREs with the embedded x option.
|
||||
In the expanded syntax,
|
||||
white-space characters are ignored
|
||||
and all characters between a
|
||||
<B>#</B>
|
||||
and the following newline (or the end of the RE) are ignored,
|
||||
permitting paragraphing and commenting a complex RE.
|
||||
There are three exceptions to that basic rule:
|
||||
<DL><P><DD>
|
||||
<P>
|
||||
a white-space character or `<B>#</B>' preceded by `<B>\</B>' is retained
|
||||
<P>
|
||||
white space or `<B>#</B>' within a bracket expression is retained
|
||||
<P>
|
||||
white space and comments are illegal within multi-character symbols
|
||||
like the ARE `<B>(?:</B>' or the BRE `<B>\(</B>'
|
||||
</DL>
|
||||
<P>
|
||||
Expanded-syntax white-space characters are blank, tab, newline, and
|
||||
any character that belongs to the <I>space</I> character class.
|
||||
<P>
|
||||
Finally, in an ARE,
|
||||
outside bracket expressions, the sequence `<B>(?#</B><I>ttt</I><B>)</B>'
|
||||
(where
|
||||
<I>ttt</I>
|
||||
is any text not containing a `<B>)</B>')
|
||||
is a comment,
|
||||
completely ignored.
|
||||
Again, this is not allowed between the characters of
|
||||
multi-character symbols like `<B>(?:</B>'.
|
||||
Such comments are more a historical artifact than a useful facility,
|
||||
and their use is deprecated;
|
||||
use the expanded syntax instead.
|
||||
<P>
|
||||
<I>None</I> of these metasyntax extensions is available if the application
|
||||
(or an initial
|
||||
<B>***=</B>
|
||||
director)
|
||||
has specified that the user's input be treated as a literal string
|
||||
rather than as an RE.
|
||||
<H3><A NAME="M72">MATCHING</A></H3>
|
||||
In the event that an RE could match more than one substring of a given
|
||||
string,
|
||||
the RE matches the one starting earliest in the string.
|
||||
If the RE could match more than one substring starting at that point,
|
||||
its choice is determined by its <I>preference</I>:
|
||||
either the longest substring, or the shortest.
|
||||
<P>
|
||||
Most atoms, and all constraints, have no preference.
|
||||
A parenthesized RE has the same preference (possibly none) as the RE.
|
||||
A quantified atom with quantifier
|
||||
<B>{</B><I>m</I><B>}</B>
|
||||
or
|
||||
<B>{</B><I>m</I><B>}?</B>
|
||||
has the same preference (possibly none) as the atom itself.
|
||||
A quantified atom with other normal quantifiers (including
|
||||
<B>{</B><I>m</I><B>,</B><I>n</I><B>}</B>
|
||||
with
|
||||
<I>m</I>
|
||||
equal to
|
||||
<I>n</I>)
|
||||
prefers longest match.
|
||||
A quantified atom with other non-greedy quantifiers (including
|
||||
<B>{</B><I>m</I><B>,</B><I>n</I><B>}?</B>
|
||||
with
|
||||
<I>m</I>
|
||||
equal to
|
||||
<I>n</I>)
|
||||
prefers shortest match.
|
||||
A branch has the same preference as the first quantified atom in it
|
||||
which has a preference.
|
||||
An RE consisting of two or more branches connected by the
|
||||
<B>|</B>
|
||||
operator prefers longest match.
|
||||
<P>
|
||||
Subject to the constraints imposed by the rules for matching the whole RE,
|
||||
subexpressions also match the longest or shortest possible substrings,
|
||||
based on their preferences,
|
||||
with subexpressions starting earlier in the RE taking priority over
|
||||
ones starting later.
|
||||
Note that outer subexpressions thus take priority over
|
||||
their component subexpressions.
|
||||
<P>
|
||||
Note that the quantifiers
|
||||
<B>{1,1}</B>
|
||||
and
|
||||
<B>{1,1}?</B>
|
||||
can be used to force longest and shortest preference, respectively,
|
||||
on a subexpression or a whole RE.
|
||||
<P>
|
||||
Match lengths are measured in characters, not collating elements.
|
||||
An empty string is considered longer than no match at all.
|
||||
For example,
|
||||
<B>bb*</B>
|
||||
matches the three middle characters of `<B>abbbc</B>',
|
||||
<B>(week|wee)(night|knights)</B>
|
||||
matches all ten characters of `<B>weeknights</B>',
|
||||
when
|
||||
<B>(.*).*</B>
|
||||
is matched against
|
||||
<B>abc</B>
|
||||
the parenthesized subexpression
|
||||
matches all three characters, and
|
||||
when
|
||||
<B>(a*)*</B>
|
||||
is matched against
|
||||
<B>bc</B>
|
||||
both the whole RE and the parenthesized
|
||||
subexpression match an empty string.
|
||||
<P>
|
||||
If case-independent matching is specified,
|
||||
the effect is much as if all case distinctions had vanished from the
|
||||
alphabet.
|
||||
When an alphabetic that exists in multiple cases appears as an
|
||||
ordinary character outside a bracket expression, it is effectively
|
||||
transformed into a bracket expression containing both cases,
|
||||
so that
|
||||
<B>x</B>
|
||||
becomes `<B>[xX]</B>'.
|
||||
When it appears inside a bracket expression, all case counterparts
|
||||
of it are added to the bracket expression, so that
|
||||
<B>[x]</B>
|
||||
becomes
|
||||
<B>[xX]</B>
|
||||
and
|
||||
<B>[^x]</B>
|
||||
becomes `<B>[^xX]</B>'.
|
||||
<P>
|
||||
If newline-sensitive matching is specified, <B>.</B>
|
||||
and bracket expressions using
|
||||
<B>^</B>
|
||||
will never match the newline character
|
||||
(so that matches will never cross newlines unless the RE
|
||||
explicitly arranges it)
|
||||
and
|
||||
<B>^</B>
|
||||
and
|
||||
<B>$</B>
|
||||
will match the empty string after and before a newline
|
||||
respectively, in addition to matching at beginning and end of string
|
||||
respectively.
|
||||
ARE
|
||||
<B>\A</B>
|
||||
and
|
||||
<B>\Z</B>
|
||||
continue to match beginning or end of string <I>only</I>.
|
||||
<P>
|
||||
If partial newline-sensitive matching is specified,
|
||||
this affects <B>.</B>
|
||||
and bracket expressions
|
||||
as with newline-sensitive matching, but not
|
||||
<B>^</B>
|
||||
and `<B>$</B>'.
|
||||
<P>
|
||||
If inverse partial newline-sensitive matching is specified,
|
||||
this affects
|
||||
<B>^</B>
|
||||
and
|
||||
<B>$</B>
|
||||
as with
|
||||
newline-sensitive matching,
|
||||
but not <B>.</B>
|
||||
and bracket expressions.
|
||||
This isn't very useful but is provided for symmetry.
|
||||
<H3><A NAME="M73">LIMITS AND COMPATIBILITY</A></H3>
|
||||
No particular limit is imposed on the length of REs.
|
||||
Programs intended to be highly portable should not employ REs longer
|
||||
than 256 bytes,
|
||||
as a POSIX-compliant implementation can refuse to accept such REs.
|
||||
<P>
|
||||
The only feature of AREs that is actually incompatible with
|
||||
POSIX EREs is that
|
||||
<B>\</B>
|
||||
does not lose its special
|
||||
significance inside bracket expressions.
|
||||
All other ARE features use syntax which is illegal or has
|
||||
undefined or unspecified effects in POSIX EREs;
|
||||
the
|
||||
<B>***</B>
|
||||
syntax of directors likewise is outside the POSIX
|
||||
syntax for both BREs and EREs.
|
||||
<P>
|
||||
Many of the ARE extensions are borrowed from Perl, but some have
|
||||
been changed to clean them up, and a few Perl extensions are not present.
|
||||
Incompatibilities of note include `<B>\b</B>', `<B>\B</B>',
|
||||
the lack of special treatment for a trailing newline,
|
||||
the addition of complemented bracket expressions to the things
|
||||
affected by newline-sensitive matching,
|
||||
the restrictions on parentheses and back references in lookahead constraints,
|
||||
and the longest/shortest-match (rather than first-match) matching semantics.
|
||||
<P>
|
||||
The matching rules for REs containing both normal and non-greedy quantifiers
|
||||
have changed since early beta-test versions of this package.
|
||||
(The new rules are much simpler and cleaner,
|
||||
but don't work as hard at guessing the user's real intentions.)
|
||||
<P>
|
||||
Henry Spencer's original 1986 <I>regexp</I> package,
|
||||
still in widespread use (e.g., in pre-8.1 releases of Tcl),
|
||||
implemented an early version of today's EREs.
|
||||
There are four incompatibilities between <I>regexp</I>'s near-EREs
|
||||
(`RREs' for short) and AREs.
|
||||
In roughly increasing order of significance:
|
||||
<P>
|
||||
<DL><P><DD>
|
||||
In AREs,
|
||||
<B>\</B>
|
||||
followed by an alphanumeric character is either an
|
||||
escape or an error,
|
||||
while in RREs, it was just another way of writing the
|
||||
alphanumeric.
|
||||
This should not be a problem because there was no reason to write
|
||||
such a sequence in RREs.
|
||||
<P>
|
||||
<B>{</B>
|
||||
followed by a digit in an ARE is the beginning of a bound,
|
||||
while in RREs,
|
||||
<B>{</B>
|
||||
was always an ordinary character.
|
||||
Such sequences should be rare,
|
||||
and will often result in an error because following characters
|
||||
will not look like a valid bound.
|
||||
<P>
|
||||
In AREs,
|
||||
<B>\</B>
|
||||
remains a special character within `<B>[ ]</B>',
|
||||
so a literal
|
||||
<B>\</B>
|
||||
within
|
||||
<B>[ ]</B>
|
||||
must be written `<B>\\</B>'.
|
||||
<B>\\</B>
|
||||
also gives a literal
|
||||
<B>\</B>
|
||||
within
|
||||
<B>[ ]</B>
|
||||
in RREs,
|
||||
but only truly paranoid programmers routinely doubled the backslash.
|
||||
<P>
|
||||
AREs report the longest/shortest match for the RE,
|
||||
rather than the first found in a specified search order.
|
||||
This may affect some RREs which were written in the expectation that
|
||||
the first match would be reported.
|
||||
(The careful crafting of RREs to optimize the search order for fast
|
||||
matching is obsolete (AREs examine all possible matches
|
||||
in parallel, and their performance is largely insensitive to their
|
||||
complexity) but cases where the search order was exploited to deliberately
|
||||
find a match which was <I>not</I> the longest/shortest will need rewriting.)
|
||||
</DL>
|
||||
<H3><A NAME="M74">BASIC REGULAR EXPRESSIONS</A></H3>
|
||||
BREs differ from EREs in several respects. `<B>|</B>', `<B>+</B>',
|
||||
and
|
||||
<B>?</B>
|
||||
are ordinary characters and there is no equivalent
|
||||
for their functionality.
|
||||
The delimiters for bounds are
|
||||
<B>\{</B>
|
||||
and `<B>\}</B>',
|
||||
with
|
||||
<B>{</B>
|
||||
and
|
||||
<B>}</B>
|
||||
by themselves ordinary characters.
|
||||
The parentheses for nested subexpressions are
|
||||
<B>\(</B>
|
||||
and `<B>\)</B>',
|
||||
with
|
||||
<B>(</B>
|
||||
and
|
||||
<B>)</B>
|
||||
by themselves ordinary characters.
|
||||
<B>^</B>
|
||||
is an ordinary character except at the beginning of the
|
||||
RE or the beginning of a parenthesized subexpression,
|
||||
<B>$</B>
|
||||
is an ordinary character except at the end of the
|
||||
RE or the end of a parenthesized subexpression,
|
||||
and
|
||||
<B>*</B>
|
||||
is an ordinary character if it appears at the beginning of the
|
||||
RE or the beginning of a parenthesized subexpression
|
||||
(after a possible leading `<B>^</B>').
|
||||
Finally,
|
||||
single-digit back references are available,
|
||||
and
|
||||
<B>\<</B>
|
||||
and
|
||||
<B>\></B>
|
||||
are synonyms for
|
||||
<B>[[:<:]]</B>
|
||||
and
|
||||
<B>[[:>:]]</B>
|
||||
respectively;
|
||||
no other escapes are available.
|
||||
|
||||
<H3><A NAME="M75">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/regexp.htm">RegExp</A></B>, <B><A HREF="../TkCmd/regexp.htm">regexp</A></B>, <B><A HREF="../TkCmd/regsub.htm">regsub</A></B>, <B><A HREF="../TkCmd/lsearch.htm">lsearch</A></B>, <B><A HREF="../TkCmd/switch.htm">switch</A></B>, <B><A HREF="../TclCmd/text.htm">text</A></B>
|
||||
<H3><A NAME="M76">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/M.htm#match">match</A>, <A href="../Keywords/R.htm#regular expression">regular expression</A>, <A href="../Keywords/S.htm#string">string</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1998 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1999 Scriptics Corporation
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
44
hlp/en/tcl/read.htm
Normal file
44
hlp/en/tcl/read.htm
Normal file
@@ -0,0 +1,44 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - read manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
read - Read from a channel
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>read </B>?<B>-nonewline</B>? <I>channelId</I><BR>
|
||||
<B>read </B><I>channelId numChars</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
In the first form, the <B>read</B> command reads all of the data from
|
||||
<I>channelId</I> up to the end of the file.
|
||||
If the <B>-nonewline</B> switch is specified then the last character
|
||||
of the file is discarded if it is a newline.
|
||||
In the second form, the extra argument specifies how many characters to
|
||||
read. Exactly that many characters will be read and returned, unless
|
||||
there are fewer than <I>numChars</I> left in the file; in this case
|
||||
all the remaining characters are returned. If the channel is
|
||||
configured to use a multi-byte encoding, then the number of characters
|
||||
read may not be the same as the number of bytes read.
|
||||
<P>
|
||||
If <I>channelId</I> is in nonblocking mode, the command may not read as
|
||||
many characters as requested: once all available input has been read,
|
||||
the command will return the data that is available rather than
|
||||
blocking for more input. If the channel is configured to use a
|
||||
multi-byte encoding, then there may actually be some bytes remaining
|
||||
in the internal buffers that do not form a complete character. These
|
||||
bytes will not be returned until a complete character is available or
|
||||
end-of-file is reached.
|
||||
The <B>-nonewline</B> switch is ignored if the command returns
|
||||
before reaching the end of the file.
|
||||
<P>
|
||||
<B>Read</B> translates end-of-line sequences in the input into
|
||||
newline characters according to the <B>-translation</B> option
|
||||
for the channel.
|
||||
See the <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> manual entry for a discussion on ways in
|
||||
which <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> will alter input.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/eof.htm">eof</A></B>, <B><A HREF="../TkCmd/fblocked.htm">fblocked</A></B>, <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/E.htm#end of line">end of line</A>, <A href="../Keywords/E.htm#end of file">end of file</A>, <A href="../Keywords/N.htm#nonblocking">nonblocking</A>, <A href="../Keywords/R.htm#read">read</A>, <A href="../Keywords/T.htm#translation">translation</A>, <A href="../Keywords/E.htm#encoding">encoding</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
133
hlp/en/tcl/regexp.htm
Normal file
133
hlp/en/tcl/regexp.htm
Normal file
@@ -0,0 +1,133 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - regexp manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="regexp.htm#M2" NAME="L931">NAME</A>
|
||||
<DL><DD>regexp - Match a regular expression against a string</DL>
|
||||
<DD><A HREF="regexp.htm#M3" NAME="L932">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>regexp </B>?<I>switches</I>? <I>exp string </I>?<I>matchVar</I>? ?<I>subMatchVar subMatchVar ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="regexp.htm#M4" NAME="L933">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="regexp.htm#M5" NAME="L934"><B>-about</B></A>
|
||||
<DD><A HREF="regexp.htm#M6" NAME="L935"><B>-expanded</B></A>
|
||||
<DD><A HREF="regexp.htm#M7" NAME="L936"><B>-indices</B></A>
|
||||
<DD><A HREF="regexp.htm#M8" NAME="L937"><B>-line</B></A>
|
||||
<DD><A HREF="regexp.htm#M9" NAME="L938"><B>-linestop</B></A>
|
||||
<DD><A HREF="regexp.htm#M10" NAME="L939"><B>-lineanchor</B></A>
|
||||
<DD><A HREF="regexp.htm#M11" NAME="L940"><B>-nocase</B></A>
|
||||
<DD><A HREF="regexp.htm#M12" NAME="L941"><B>-all</B></A>
|
||||
<DD><A HREF="regexp.htm#M13" NAME="L942"><B>-inline</B></A>
|
||||
<DD><A HREF="regexp.htm#M14" NAME="L943"><B>-start</B> <I>index</I></A>
|
||||
<DD><A HREF="regexp.htm#M15" NAME="L944"><B>- -</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="regexp.htm#M16" NAME="L945">SEE ALSO</A>
|
||||
<DD><A HREF="regexp.htm#M17" NAME="L946">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
regexp - Match a regular expression against a string
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>regexp </B>?<I>switches</I>? <I>exp string </I>?<I>matchVar</I>? ?<I>subMatchVar subMatchVar ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Determines whether the regular expression <I>exp</I> matches part or
|
||||
all of <I>string</I> and returns 1 if it does, 0 if it doesn't, unless
|
||||
<B>-inline</B> is specified (see below).
|
||||
(Regular expression matching is described in the <B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B>
|
||||
reference page.)
|
||||
<P>
|
||||
If additional arguments are specified after <I>string</I> then they
|
||||
are treated as the names of variables in which to return
|
||||
information about which part(s) of <I>string</I> matched <I>exp</I>.
|
||||
<I>MatchVar</I> will be set to the range of <I>string</I> that
|
||||
matched all of <I>exp</I>. The first <I>subMatchVar</I> will contain
|
||||
the characters in <I>string</I> that matched the leftmost parenthesized
|
||||
subexpression within <I>exp</I>, the next <I>subMatchVar</I> will
|
||||
contain the characters that matched the next parenthesized
|
||||
subexpression to the right in <I>exp</I>, and so on.
|
||||
<P>
|
||||
If the initial arguments to <B>regexp</B> start with <B>-</B> then
|
||||
they are treated as switches. The following switches are
|
||||
currently supported:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>-about</B></A><DD>
|
||||
Instead of attempting to match the regular expression, returns a list
|
||||
containing information about the regular expression. The first
|
||||
element of the list is a subexpression count. The second element is a
|
||||
list of property names that describe various attributes of the regular
|
||||
expression. This switch is primarily intended for debugging purposes.
|
||||
<P><DT><A NAME="M6"><B>-expanded</B></A><DD>
|
||||
Enables use of the expanded regular expression syntax where
|
||||
whitespace and comments are ignored. This is the same as specifying
|
||||
the <B>(?x)</B> embedded option (see METASYNTAX, below).
|
||||
<P><DT><A NAME="M7"><B>-indices</B></A><DD>
|
||||
Changes what is stored in the <I>subMatchVar</I>s.
|
||||
Instead of storing the matching characters from <I>string</I>,
|
||||
each variable
|
||||
will contain a list of two decimal strings giving the indices
|
||||
in <I>string</I> of the first and last characters in the matching
|
||||
range of characters.
|
||||
<P><DT><A NAME="M8"><B>-line</B></A><DD>
|
||||
Enables newline-sensitive matching. By default, newline is a
|
||||
completely ordinary character with no special meaning. With this
|
||||
flag, `[^' bracket expressions and `.' never match newline, `^'
|
||||
matches an empty string after any newline in addition to its normal
|
||||
function, and `$' matches an empty string before any newline in
|
||||
addition to its normal function. This flag is equivalent to
|
||||
specifying both <B>-linestop</B> and <B>-lineanchor</B>, or the
|
||||
<B>(?n)</B> embedded option (see METASYNTAX, below).
|
||||
<P><DT><A NAME="M9"><B>-linestop</B></A><DD>
|
||||
Changes the behavior of `[^' bracket expressions and `.' so that they
|
||||
stop at newlines. This is the same as specifying the <B>(?p)</B>
|
||||
embedded option (see METASYNTAX, below).
|
||||
<P><DT><A NAME="M10"><B>-lineanchor</B></A><DD>
|
||||
Changes the behavior of `^' and `$' (the ``anchors'') so they match the
|
||||
beginning and end of a line respectively. This is the same as
|
||||
specifying the <B>(?w)</B> embedded option (see METASYNTAX, below).
|
||||
<P><DT><A NAME="M11"><B>-nocase</B></A><DD>
|
||||
Causes upper-case characters in <I>string</I> to be treated as
|
||||
lower case during the matching process.
|
||||
<P><DT><A NAME="M12"><B>-all</B></A><DD>
|
||||
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 continue information for
|
||||
the last match only.
|
||||
<P><DT><A NAME="M13"><B>-inline</B></A><DD>
|
||||
Causes the command to return, as a list, the data that would otherwise
|
||||
be placed in match variables. When using <B>-inline</B>,
|
||||
match variables may not be specified. If used with <B>-all</B>, 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. Examples are:
|
||||
<PRE>regexp -inline -- {\w(\w)} " inlined "
|
||||
=> {in n}
|
||||
regexp -all -inline -- {\w(\w)} " inlined "
|
||||
=> {in n li i ne e}</PRE>
|
||||
<P><DT><A NAME="M14"><B>-start</B> <I>index</I></A><DD>
|
||||
Specifies a character index offset into the string to start
|
||||
matching the regular expression at. When using this switch, `^'
|
||||
will not match the beginning of the line, and \A will still
|
||||
match the start of the string at <I>index</I>. If <B>-indices</B>
|
||||
is specified, the indices will be indexed starting from the
|
||||
absolute beginning of the input string.
|
||||
<I>index</I> will be constrained to the bounds of the input string.
|
||||
<P><DT><A NAME="M15"><B>- -</B></A><DD>
|
||||
Marks the end of switches. The argument following this one will
|
||||
be treated as <I>exp</I> even if it starts with a <B>-</B>.
|
||||
<P></DL>
|
||||
<P>
|
||||
If there are more <I>subMatchVar</I>'s than parenthesized
|
||||
subexpressions within <I>exp</I>, or if a particular subexpression
|
||||
in <I>exp</I> doesn't match the string (e.g. because it was in a
|
||||
portion of the expression that wasn't matched), then the corresponding
|
||||
<I>subMatchVar</I> will be set to ``<B>-1 -1</B>'' if <B>-indices</B>
|
||||
has been specified or to an empty string otherwise.
|
||||
|
||||
<H3><A NAME="M16">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B>, <B><A HREF="../TkCmd/regsub.htm">regsub</A></B>
|
||||
<H3><A NAME="M17">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/M.htm#match">match</A>, <A href="../Keywords/R.htm#regular expression">regular expression</A>, <A href="../Keywords/S.htm#string">string</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1998 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
163
hlp/en/tcl/registry.htm
Normal file
163
hlp/en/tcl/registry.htm
Normal file
@@ -0,0 +1,163 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - registry manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="registry.htm#M2" NAME="L947">NAME</A>
|
||||
<DL><DD>registry - Manipulate the Windows registry</DL>
|
||||
<DD><A HREF="registry.htm#M3" NAME="L948">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>package require registry 1.0</B>
|
||||
<DD><B>registry </B><I>option</I> <I>keyName</I> ?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="registry.htm#M4" NAME="L949">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="registry.htm#M5" NAME="L950"><B>registry delete </B><I>keyName</I> ?<I>valueName</I>?</A>
|
||||
<DD><A HREF="registry.htm#M6" NAME="L951"><B>registry get </B><I>keyName valueName</I></A>
|
||||
<DD><A HREF="registry.htm#M7" NAME="L952"><B>registry keys </B><I>keyName</I> ?<I>pattern</I>?</A>
|
||||
<DD><A HREF="registry.htm#M8" NAME="L953"><B>registry set </B><I>keyName</I> ?<I>valueName data </I>?<I>type</I>??</A>
|
||||
<DD><A HREF="registry.htm#M9" NAME="L954"><B>registry type </B><I>keyName valueName</I></A>
|
||||
<DD><A HREF="registry.htm#M10" NAME="L955"><B>registry values </B><I>keyName</I> ?<I>pattern</I>?</A>
|
||||
</DL>
|
||||
<DD><A HREF="registry.htm#M11" NAME="L956">SUPPORTED TYPES</A>
|
||||
<DL>
|
||||
<DD><A HREF="registry.htm#M12" NAME="L957"><B>binary</B></A>
|
||||
<DD><A HREF="registry.htm#M13" NAME="L958"><B>none</B></A>
|
||||
<DD><A HREF="registry.htm#M14" NAME="L959"><B>sz</B></A>
|
||||
<DD><A HREF="registry.htm#M15" NAME="L960"><B>expand_sz</B></A>
|
||||
<DD><A HREF="registry.htm#M16" NAME="L961"><B>dword</B></A>
|
||||
<DD><A HREF="registry.htm#M17" NAME="L962"><B>dword_big_endian</B></A>
|
||||
<DD><A HREF="registry.htm#M18" NAME="L963"><B>link</B></A>
|
||||
<DD><A HREF="registry.htm#M19" NAME="L964"><B>multi_sz</B></A>
|
||||
<DD><A HREF="registry.htm#M20" NAME="L965"><B>resource_list</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="registry.htm#M21" NAME="L966">PORTABILITY ISSUES</A>
|
||||
<DD><A HREF="registry.htm#M22" NAME="L967">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
registry - Manipulate the Windows registry
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>package require registry 1.0</B><BR>
|
||||
<B>registry </B><I>option</I> <I>keyName</I> ?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>registry</B> package provides a general set of operations for
|
||||
manipulating the Windows registry. The package implements the
|
||||
<B>registry</B> Tcl command. This command is only supported on the
|
||||
Windows platform. Warning: this command should be used with caution
|
||||
as a corrupted registry can leave your system in an unusable state.
|
||||
<P>
|
||||
<I>KeyName</I> is the name of a registry key. Registry keys must be
|
||||
one of the following forms:
|
||||
<DL><P><DD>
|
||||
<B>\\</B><I>hostname</I><B>\</B><I>rootname</I><B>\</B><I>keypath</I>
|
||||
<P>
|
||||
<I>rootname</I><B>\</B><I>keypath</I>
|
||||
<P>
|
||||
<I>rootname</I>
|
||||
</DL>
|
||||
<P>
|
||||
<I>Hostname</I> specifies the name of any valid Windows
|
||||
host that exports its registry. The <I>rootname</I> component must be
|
||||
one of <B>HKEY_LOCAL_MACHINE</B>, <B>HKEY_USERS</B>,
|
||||
<B>HKEY_CLASSES_ROOT</B>, <B>HKEY_CURRENT_USER</B>,
|
||||
<B>HKEY_CURRENT_CONFIG</B>, <B>HKEY_PERFORMANCE_DATA</B>, or
|
||||
<B>HKEY_DYN_DATA</B>. The <I>keypath</I> can be one or more
|
||||
registry key names separated by backslash (<B>\</B>) characters.
|
||||
<P>
|
||||
<I>Option</I> indicates what to do with the registry key name. Any
|
||||
unique abbreviation for <I>option</I> is acceptable. The valid options
|
||||
are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>registry delete </B><I>keyName</I> ?<I>valueName</I>?</A><DD>
|
||||
If the optional <I>valueName</I> argument is present, the specified
|
||||
value under <I>keyName</I> will be deleted from the registry. If the
|
||||
optional <I>valueName</I> is omitted, the specified key and any subkeys
|
||||
or values beneath it in the registry heirarchy will be deleted. If
|
||||
the key could not be deleted then an error is generated. If the key
|
||||
did not exist, the command has no effect.
|
||||
<P><DT><A NAME="M6"><B>registry get </B><I>keyName valueName</I></A><DD>
|
||||
Returns the data associated with the value <I>valueName</I> under the key
|
||||
<I>keyName</I>. If either the key or the value does not exist, then an
|
||||
error is generated. For more details on the format of the returned
|
||||
data, see SUPPORTED TYPES, below.
|
||||
<P><DT><A NAME="M7"><B>registry keys </B><I>keyName</I> ?<I>pattern</I>?</A><DD>
|
||||
If <I>pattern</I> isn't specified, returns a list of names of all the
|
||||
subkeys of <I>keyName</I>. If <I>pattern</I> is specified, only those
|
||||
names matching <I>pattern</I> are returned. Matching is determined
|
||||
using the same rules as for <B><A HREF="../TkCmd/string.htm">string</A></B> <B>match</B>. If the
|
||||
specified <I>keyName</I> does not exist, then an error is generated.
|
||||
<P><DT><A NAME="M8"><B>registry set </B><I>keyName</I> ?<I>valueName data </I>?<I>type</I>??</A><DD>
|
||||
If <I>valueName</I> isn't specified, creates the key <I>keyName</I> if
|
||||
it doesn't already exist. If <I>valueName</I> is specified, creates
|
||||
the key <I>keyName</I> and value <I>valueName</I> if necessary. The
|
||||
contents of <I>valueName</I> are set to <I>data</I> with the type
|
||||
indicated by <I>type</I>. If <I>type</I> isn't specified, the type
|
||||
<B>sz</B> is assumed. For more details on the data and type arguments,
|
||||
see SUPPORTED TYPES below.
|
||||
<P><DT><A NAME="M9"><B>registry type </B><I>keyName valueName</I></A><DD>
|
||||
Returns the type of the value <I>valueName</I> in the key
|
||||
<I>keyName</I>. For more information on the possible types, see
|
||||
SUPPORTED TYPES, below.
|
||||
<P><DT><A NAME="M10"><B>registry values </B><I>keyName</I> ?<I>pattern</I>?</A><DD>
|
||||
If <I>pattern</I> isn't specified, returns a list of names of all the
|
||||
values of <I>keyName</I>. If <I>pattern</I> is specified, only those
|
||||
names matching <I>pattern</I> are returned. Matching is determined
|
||||
using the same rules as for <B><A HREF="../TkCmd/string.htm">string</A></B> <B>match</B>.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M11">SUPPORTED TYPES</A></H3>
|
||||
Each value under a key in the registry contains some data of a
|
||||
particular type in a type-specific representation. The <B>registry</B>
|
||||
command converts between this internal representation and one that can
|
||||
be manipulated by Tcl scripts. In most cases, the data is simply
|
||||
returned as a Tcl string. The type indicates the intended use for the
|
||||
data, but does not actually change the representation. For some
|
||||
types, the <B>registry</B> command returns the data in a different form to
|
||||
make it easier to manipulate. The following types are recognized by the
|
||||
registry command:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M12"><B>binary</B></A><DD>
|
||||
The registry value contains arbitrary binary data. The data is represented
|
||||
exactly in Tcl, including any embedded nulls.
|
||||
<P><DT><A NAME="M13"><B>none</B></A><DD>
|
||||
The registry value contains arbitrary binary data with no defined
|
||||
type. The data is represented exactly in Tcl, including any embedded
|
||||
nulls.
|
||||
<P><DT><A NAME="M14"><B>sz</B></A><DD>
|
||||
The registry value contains a null-terminated string. The data is
|
||||
represented in Tcl as a string.
|
||||
<P><DT><A NAME="M15"><B>expand_sz</B></A><DD>
|
||||
The registry value contains a null-terminated string that contains
|
||||
unexpanded references to environment variables in the normal Windows
|
||||
style (for example, "%PATH%"). The data is represented in Tcl as a
|
||||
string.
|
||||
<P><DT><A NAME="M16"><B>dword</B></A><DD>
|
||||
The registry value contains a little-endian 32-bit number. The data is
|
||||
represented in Tcl as a decimal string.
|
||||
<P><DT><A NAME="M17"><B>dword_big_endian</B></A><DD>
|
||||
The registry value contains a big-endian 32-bit number. The data is
|
||||
represented in Tcl as a decimal string.
|
||||
<P><DT><A NAME="M18"><B>link</B></A><DD>
|
||||
The registry value contains a symbolic link. The data is represented
|
||||
exactly in Tcl, including any embedded nulls.
|
||||
<P><DT><A NAME="M19"><B>multi_sz</B></A><DD>
|
||||
The registry value contains an array of null-terminated strings. The
|
||||
data is represented in Tcl as a list of strings.
|
||||
<P><DT><A NAME="M20"><B>resource_list</B></A><DD>
|
||||
The registry value contains a device-driver resource list. The data
|
||||
is represented exactly in Tcl, including any embedded nulls.
|
||||
<P></DL>
|
||||
<P>
|
||||
In addition to the symbolically named types listed above, unknown
|
||||
types are identified using a 32-bit integer that corresponds to the
|
||||
type code returned by the system interfaces. In this case, the data
|
||||
is represented exactly in Tcl, including any embedded nulls.
|
||||
|
||||
<H3><A NAME="M21">PORTABILITY ISSUES</A></H3>
|
||||
The registry command is only available on Windows.
|
||||
|
||||
<H3><A NAME="M22">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/R.htm#registry">registry</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
115
hlp/en/tcl/regsub.htm
Normal file
115
hlp/en/tcl/regsub.htm
Normal file
@@ -0,0 +1,115 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - regsub manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="regsub.htm#M2" NAME="L968">NAME</A>
|
||||
<DL><DD>regsub - Perform substitutions based on regular expression pattern matching</DL>
|
||||
<DD><A HREF="regsub.htm#M3" NAME="L969">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>regsub </B>?<I>switches</I>? <I>exp string subSpec varName</I>
|
||||
</DL>
|
||||
<DD><A HREF="regsub.htm#M4" NAME="L970">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="regsub.htm#M5" NAME="L971"><B>-all</B></A>
|
||||
<DD><A HREF="regsub.htm#M6" NAME="L972"><B>-expanded</B></A>
|
||||
<DD><A HREF="regsub.htm#M7" NAME="L973"><B>-line</B></A>
|
||||
<DD><A HREF="regsub.htm#M8" NAME="L974"><B>-linestop</B></A>
|
||||
<DD><A HREF="regsub.htm#M9" NAME="L975"><B>-lineanchor</B></A>
|
||||
<DD><A HREF="regsub.htm#M10" NAME="L976"><B>-nocase</B></A>
|
||||
<DD><A HREF="regsub.htm#M11" NAME="L977"><B>-start</B> <I>index</I></A>
|
||||
<DD><A HREF="regsub.htm#M12" NAME="L978"><B>- -</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="regsub.htm#M13" NAME="L979">SEE ALSO</A>
|
||||
<DD><A HREF="regsub.htm#M14" NAME="L980">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
regsub - Perform substitutions based on regular expression pattern matching
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>regsub </B>?<I>switches</I>? <I>exp string subSpec varName</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command matches the regular expression <I>exp</I> against
|
||||
<I>string</I>,
|
||||
and it copies <I>string</I> to the variable whose name is
|
||||
given by <I>varName</I>.
|
||||
(Regular expression matching is described in the <B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B>
|
||||
reference page.)
|
||||
If there is a match, then while copying <I>string</I> to <I>varName</I>
|
||||
the portion of <I>string</I> that
|
||||
matched <I>exp</I> is replaced with <I>subSpec</I>.
|
||||
If <I>subSpec</I> contains a ``&'' or ``\0'', then it is replaced
|
||||
in the substitution with the portion of <I>string</I> that
|
||||
matched <I>exp</I>.
|
||||
If <I>subSpec</I> contains a ``\<I>n</I>'', where <I>n</I> is a digit
|
||||
between 1 and 9, then it is replaced in the substitution with
|
||||
the portion of <I>string</I> that matched the <I>n</I>-th
|
||||
parenthesized subexpression of <I>exp</I>.
|
||||
Additional backslashes may be used in <I>subSpec</I> to prevent special
|
||||
interpretation of ``&'' or ``\0'' or ``\<I>n</I>'' or
|
||||
backslash.
|
||||
The use of backslashes in <I>subSpec</I> tends to interact badly
|
||||
with the Tcl parser's use of backslashes, so it's generally
|
||||
safest to enclose <I>subSpec</I> in braces if it includes
|
||||
backslashes.
|
||||
<P>
|
||||
If the initial arguments to <B><A HREF="../TkCmd/regexp.htm">regexp</A></B> start with <B>-</B> then
|
||||
they are treated as switches. The following switches are
|
||||
currently supported:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>-all</B></A><DD>
|
||||
All ranges in <I>string</I> that match <I>exp</I> are found and
|
||||
substitution is performed for each of these ranges.
|
||||
Without this switch only the first
|
||||
matching range is found and substituted.
|
||||
If <B>-all</B> is specified, then ``&'' and ``\<I>n</I>''
|
||||
sequences are handled for each substitution using the information
|
||||
from the corresponding match.
|
||||
<P><DT><A NAME="M6"><B>-expanded</B></A><DD>
|
||||
Enables use of the expanded regular expression syntax where
|
||||
whitespace and comments are ignored. This is the same as specifying
|
||||
the <B>(?x)</B> embedded option (see METASYNTAX, below).
|
||||
<P><DT><A NAME="M7"><B>-line</B></A><DD>
|
||||
Enables newline-sensitive matching. By default, newline is a
|
||||
completely ordinary character with no special meaning. With this
|
||||
flag, `[^' bracket expressions and `.' never match newline, `^'
|
||||
matches an empty string after any newline in addition to its normal
|
||||
function, and `$' matches an empty string before any newline in
|
||||
addition to its normal function. This flag is equivalent to
|
||||
specifying both <B>-linestop</B> and <B>-lineanchor</B>, or the
|
||||
<B>(?n)</B> embedded option (see METASYNTAX, below).
|
||||
<P><DT><A NAME="M8"><B>-linestop</B></A><DD>
|
||||
Changes the behavior of `[^' bracket expressions and `.' so that they
|
||||
stop at newlines. This is the same as specifying the <B>(?p)</B>
|
||||
embedded option (see METASYNTAX, below).
|
||||
<P><DT><A NAME="M9"><B>-lineanchor</B></A><DD>
|
||||
Changes the behavior of `^' and `$' (the ``anchors'') so they match the
|
||||
beginning and end of a line respectively. This is the same as
|
||||
specifying the <B>(?w)</B> embedded option (see METASYNTAX, below).
|
||||
<P><DT><A NAME="M10"><B>-nocase</B></A><DD>
|
||||
Upper-case characters in <I>string</I> will be converted to lower-case
|
||||
before matching against <I>exp</I>; however, substitutions specified
|
||||
by <I>subSpec</I> use the original unconverted form of <I>string</I>.
|
||||
<P><DT><A NAME="M11"><B>-start</B> <I>index</I></A><DD>
|
||||
Specifies a character index offset into the string to start
|
||||
matching the regular expression at. When using this switch, `^'
|
||||
will not match the beginning of the line, and \A will still
|
||||
match the start of the string at <I>index</I>.
|
||||
<I>index</I> will be constrained to the bounds of the input string.
|
||||
<P><DT><A NAME="M12"><B>- -</B></A><DD>
|
||||
Marks the end of switches. The argument following this one will
|
||||
be treated as <I>exp</I> even if it starts with a <B>-</B>.
|
||||
<P></DL>
|
||||
<P>
|
||||
The command returns a count of the number of matching ranges that
|
||||
were found and replaced.
|
||||
See the manual entry for <B><A HREF="../TkCmd/regexp.htm">regexp</A></B> for details on the interpretation
|
||||
of regular expressions.
|
||||
|
||||
<H3><A NAME="M13">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/regexp.htm">regexp</A></B>, <B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B>
|
||||
<H3><A NAME="M14">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/M.htm#match">match</A>, <A href="../Keywords/P.htm#pattern">pattern</A>, <A href="../Keywords/R.htm#regular expression">regular expression</A>, <A href="../Keywords/S.htm#substitute">substitute</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 2000 Scriptics Corporation.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
24
hlp/en/tcl/rename.htm
Normal file
24
hlp/en/tcl/rename.htm
Normal file
@@ -0,0 +1,24 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - rename manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
rename - Rename or delete a command
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>rename </B><I>oldName newName</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Rename the command that used to be called <I>oldName</I> so that it
|
||||
is now called <I>newName</I>.
|
||||
If <I>newName</I> is an empty string then <I>oldName</I> is deleted.
|
||||
<I>oldName</I> and <I>newName</I> may include namespace qualifiers
|
||||
(names of containing namespaces).
|
||||
If a command is renamed into a different namespace,
|
||||
future invocations of it will execute in the new namespace.
|
||||
The <B>rename</B> command returns an empty string as result.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/namespace.htm">namespace</A></B>, <B><A HREF="../TkCmd/proc.htm">proc</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#command">command</A>, <A href="../Keywords/D.htm#delete">delete</A>, <A href="../Keywords/N.htm#namespace">namespace</A>, <A href="../Keywords/R.htm#rename">rename</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
169
hlp/en/tcl/resource.htm
Normal file
169
hlp/en/tcl/resource.htm
Normal file
@@ -0,0 +1,169 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - resource manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="resource.htm#M2" NAME="L986">NAME</A>
|
||||
<DL><DD>resource - Manipulate Macintosh resources</DL>
|
||||
<DD><A HREF="resource.htm#M3" NAME="L987">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>resource </B><I>option</I> ?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="resource.htm#M4" NAME="L988">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="resource.htm#M5" NAME="L989"><B>resource close </B><I>rsrcRef</I></A>
|
||||
<DD><A HREF="resource.htm#M6" NAME="L990"><B>resource delete</B> ?<I>options</I>? <I>resourceType</I></A>
|
||||
<DL>
|
||||
<DD><A HREF="resource.htm#M7" NAME="L991"><B>-id</B> <I>resourceId</I></A>
|
||||
<DD><A HREF="resource.htm#M8" NAME="L992"><B>-name</B> <I>resourceName</I></A>
|
||||
<DD><A HREF="resource.htm#M9" NAME="L993"><B>-file</B> <I>resourceRef</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="resource.htm#M10" NAME="L994"><B>resource files ?</B><I>resourceRef</I>?</A>
|
||||
<DD><A HREF="resource.htm#M11" NAME="L995"><B>resource list </B><I>resourceType</I> ?<I>resourceRef</I>?</A>
|
||||
<DD><A HREF="resource.htm#M12" NAME="L996"><B>resource open </B><I>fileName</I> ?<I>access</I>?</A>
|
||||
<DD><A HREF="resource.htm#M13" NAME="L997"><B>resource read </B><I>resourceType</I> <I>resourceId</I> ?<I>resourceRef</I>?</A>
|
||||
<DD><A HREF="resource.htm#M14" NAME="L998"><B>resource types ?</B><I>resourceRef</I>?</A>
|
||||
<DD><A HREF="resource.htm#M15" NAME="L999"><B>resource write</B> ?<I>options</I>? <I>resourceType</I> <I>data</I></A>
|
||||
<DL>
|
||||
<DD><A HREF="resource.htm#M16" NAME="L1000"><B>-id</B> <I>resourceId</I></A>
|
||||
<DD><A HREF="resource.htm#M17" NAME="L1001"><B>-name</B> <I>resourceName</I></A>
|
||||
<DD><A HREF="resource.htm#M18" NAME="L1002"><B>-file</B> <I>resourceRef</I></A>
|
||||
<DD><A HREF="resource.htm#M19" NAME="L1003"><B>-force</B></A>
|
||||
</DL>
|
||||
</DL>
|
||||
<DD><A HREF="resource.htm#M20" NAME="L1004">RESOURCE TYPES</A>
|
||||
<DD><A HREF="resource.htm#M21" NAME="L1005">RESOURCE IDS</A>
|
||||
<DD><A HREF="resource.htm#M22" NAME="L1006">PORTABILITY ISSUES</A>
|
||||
<DD><A HREF="resource.htm#M23" NAME="L1007">SEE ALSO</A>
|
||||
<DD><A HREF="resource.htm#M24" NAME="L1008">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
resource - Manipulate Macintosh resources
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>resource </B><I>option</I> ?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>resource</B> command provides some generic operations for
|
||||
dealing with Macintosh resources. This command is only supported on
|
||||
the Macintosh platform. Each Macintosh file consists of two
|
||||
<I>forks</I>: a <I>data</I> fork and a <I>resource</I> fork. You use the
|
||||
normal open, puts, close, etc. commands to manipulate the data fork.
|
||||
You must use this command, however, to interact with the resource
|
||||
fork. <I>Option</I> indicates what resource command to perform. Any
|
||||
unique abbreviation for <I>option</I> is acceptable. The valid options
|
||||
are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>resource close </B><I>rsrcRef</I></A><DD>
|
||||
Closes the given resource reference (obtained from <B>resource
|
||||
open</B>). Resources from that resource file will no longer be
|
||||
available.
|
||||
<P><DT><A NAME="M6"><B>resource delete</B> ?<I>options</I>? <I>resourceType</I></A><DD>
|
||||
This command will delete the resource specified by <I>options</I> and
|
||||
type <I>resourceType</I> (see RESOURCE TYPES below). The options
|
||||
give you several ways to specify the resource to be deleted.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M7"><B>-id</B> <I>resourceId</I></A><DD>
|
||||
If the <B>-id</B> option is given the id <I>resourceId</I> (see RESOURCE
|
||||
IDS below) is used to specify the resource to be deleted. The id must
|
||||
be a number - to specify a name use the <B>-name</B> option.
|
||||
<P><DT><A NAME="M8"><B>-name</B> <I>resourceName</I></A><DD>
|
||||
If <B>-name</B> is specified, the resource named
|
||||
<I>resourceName</I> will be deleted. If the <B>-id</B> is also
|
||||
provided, then there must be a resource with BOTH this name and
|
||||
this id. If no name is provided, then the id will be used regardless
|
||||
of the name of the actual resource.
|
||||
<P><DT><A NAME="M9"><B>-file</B> <I>resourceRef</I></A><DD>
|
||||
If the <B>-file</B> option is specified then the resource will be
|
||||
deleted from the file pointed to by <I>resourceRef</I>. Otherwise the
|
||||
first resource with the given <I>resourceName</I> and or
|
||||
<I>resourceId</I> which is found on the resource file path will be
|
||||
deleted. To inspect the file path, use the <I>resource files</I> command.
|
||||
<P></DL>
|
||||
<P><DT><A NAME="M10"><B>resource files ?</B><I>resourceRef</I>?</A><DD>
|
||||
If <I>resourceRef</I>is not provided, this command returns a Tcl list
|
||||
of the resource references for all the currently open resource files.
|
||||
The list is in the normal Macintosh search order for resources. If
|
||||
<I>resourceRef</I> is specified, the command will
|
||||
return the path to the file whose resource fork is represented by that
|
||||
token.
|
||||
<P><DT><A NAME="M11"><B>resource list </B><I>resourceType</I> ?<I>resourceRef</I>?</A><DD>
|
||||
List all of the resources ids of type <I>resourceType</I> (see RESOURCE
|
||||
TYPES below). If <I>resourceRef</I> is specified then the command will
|
||||
limit the search to that particular resource file. Otherwise, all
|
||||
resource files currently opened by the application will be searched.
|
||||
A Tcl list of either the resource name's or resource id's of the found
|
||||
resources will be returned. See the RESOURCE IDS section below for
|
||||
more details about what a resource id is.
|
||||
<P><DT><A NAME="M12"><B>resource open </B><I>fileName</I> ?<I>access</I>?</A><DD>
|
||||
Open the resource for the file <I>fileName</I>. Standard file access
|
||||
permissions may also be specified (see the manual entry for <B><A HREF="../TkCmd/open.htm">open</A></B>
|
||||
for details). A resource reference (<I>resourceRef</I>) is returned
|
||||
that can be used by the other resource commands. An error can occur
|
||||
if the file doesn't exist or the file does not have a resource fork.
|
||||
However, if you open the file with write permissions the file and/or
|
||||
resource fork will be created instead of generating an error.
|
||||
<P><DT><A NAME="M13"><B>resource read </B><I>resourceType</I> <I>resourceId</I> ?<I>resourceRef</I>?</A><DD>
|
||||
Read the entire resource of type <I>resourceType</I> (see RESOURCE
|
||||
TYPES below) and the name or id of <I>resourceId</I> (see RESOURCE IDS
|
||||
below) into memory and return the result. If <I>resourceRef</I> is
|
||||
specified we limit our search to that resource file, otherwise we
|
||||
search all open resource forks in the application. It is important to
|
||||
note that most Macintosh resource use a binary format and the data
|
||||
returned from this command may have embedded NULLs or other non-ASCII
|
||||
data.
|
||||
<P><DT><A NAME="M14"><B>resource types ?</B><I>resourceRef</I>?</A><DD>
|
||||
This command returns a Tcl list of all resource types (see RESOURCE
|
||||
TYPES below) found in the resource file pointed to by
|
||||
<I>resourceRef</I>. If <I>resourceRef</I> is not specified it will
|
||||
return all the resource types found in every resource file currently
|
||||
opened by the application.
|
||||
<P><DT><A NAME="M15"><B>resource write</B> ?<I>options</I>? <I>resourceType</I> <I>data</I></A><DD>
|
||||
This command will write the passed in <I>data</I> as a new resource of
|
||||
type <I>resourceType</I> (see RESOURCE TYPES below). Several options
|
||||
are available that describe where and how the resource is stored.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M16"><B>-id</B> <I>resourceId</I></A><DD>
|
||||
If the <B>-id</B> option is given the id <I>resourceId</I> (see RESOURCE
|
||||
IDS below) is used for the new resource, otherwise a unique id will be
|
||||
generated that will not conflict with any existing resource. However,
|
||||
the id must be a number - to specify a name use the <B>-name</B> option.
|
||||
<P><DT><A NAME="M17"><B>-name</B> <I>resourceName</I></A><DD>
|
||||
If <B>-name</B> is specified the resource will be named
|
||||
<I>resourceName</I>, otherwise it will have the empty string as the
|
||||
name.
|
||||
<P><DT><A NAME="M18"><B>-file</B> <I>resourceRef</I></A><DD>
|
||||
If the <B>-file</B> option is specified then the resource will be
|
||||
written in the file pointed to by <I>resourceRef</I>, otherwise the
|
||||
most resently open resource will be used.
|
||||
<P><DT><A NAME="M19"><B>-force</B></A><DD>
|
||||
If the target resource already exists, then by default Tcl will not
|
||||
overwrite it, but raise an error instead. Use the -force flag to
|
||||
force overwriting the extant resource.
|
||||
<P></DL>
|
||||
<P></DL>
|
||||
<H3><A NAME="M20">RESOURCE TYPES</A></H3>
|
||||
Resource types are defined as a four character string that is then
|
||||
mapped to an underlying id. For example, <B><A HREF="../TclCmd/text.htm">TEXT</A></B> refers to the
|
||||
Macintosh resource type for text. The type <B>STR#</B> is a list of
|
||||
counted strings. All Macintosh resources must be of some type. See
|
||||
Macintosh documentation for a more complete list of resource types
|
||||
that are commonly used.
|
||||
|
||||
<H3><A NAME="M21">RESOURCE IDS</A></H3>
|
||||
For this command the notion of a resource id actually refers to two
|
||||
ideas in Macintosh resources. Every place you can use a resource Id
|
||||
you can use either the resource name or a resource number. Names are
|
||||
always searched or returned in preference to numbers. For example,
|
||||
the <B>resource list</B> command will return names if they exist or
|
||||
numbers if the name is NULL.
|
||||
|
||||
<H3><A NAME="M22">PORTABILITY ISSUES</A></H3>
|
||||
The resource command is only available on Macintosh.
|
||||
|
||||
<H3><A NAME="M23">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/open.htm">open</A></B>
|
||||
<H3><A NAME="M24">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/O.htm#open">open</A>, <A href="../Keywords/R.htm#resource">resource</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
97
hlp/en/tcl/return.htm
Normal file
97
hlp/en/tcl/return.htm
Normal file
@@ -0,0 +1,97 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - return manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="return.htm#M2" NAME="L1009">NAME</A>
|
||||
<DL><DD>return - Return from a procedure</DL>
|
||||
<DD><A HREF="return.htm#M3" NAME="L1010">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>return </B>?<B>-code </B><I>code</I>? ?<B>-errorinfo </B><I>info</I>? ?<B>-errorcode</B><I> code</I>? ?<I>string</I>?
|
||||
</DL>
|
||||
<DD><A HREF="return.htm#M4" NAME="L1011">DESCRIPTION</A>
|
||||
<DD><A HREF="return.htm#M5" NAME="L1012">EXCEPTIONAL RETURNS</A>
|
||||
<DL>
|
||||
<DD><A HREF="return.htm#M6" NAME="L1013"><B>ok</B></A>
|
||||
<DD><A HREF="return.htm#M7" NAME="L1014"><B>error</B></A>
|
||||
<DD><A HREF="return.htm#M8" NAME="L1015"><B>return</B></A>
|
||||
<DD><A HREF="return.htm#M9" NAME="L1016"><B>break</B></A>
|
||||
<DD><A HREF="return.htm#M10" NAME="L1017"><B>continue</B></A>
|
||||
<DD><A HREF="return.htm#M11" NAME="L1018"><I>value</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="return.htm#M12" NAME="L1019">SEE ALSO</A>
|
||||
<DD><A HREF="return.htm#M13" NAME="L1020">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
return - Return from a procedure
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>return </B>?<B>-code </B><I>code</I>? ?<B>-errorinfo </B><I>info</I>? ?<B>-errorcode</B><I> code</I>? ?<I>string</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Return immediately from the current procedure
|
||||
(or top-level command or <B><A HREF="../TkCmd/source.htm">source</A></B> command),
|
||||
with <I>string</I> as the return value. If <I>string</I> is not specified then
|
||||
an empty string will be returned as result.
|
||||
|
||||
<H3><A NAME="M5">EXCEPTIONAL RETURNS</A></H3>
|
||||
In the usual case where the <B>-code</B> option isn't
|
||||
specified the procedure will return normally (its completion
|
||||
code will be TCL_OK).
|
||||
However, the <B>-code</B> option may be used to generate an
|
||||
exceptional return from the procedure.
|
||||
<I>Code</I> may have any of the following values:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>ok</B></A><DD>
|
||||
Normal return: same as if the option is omitted.
|
||||
<P><DT><A NAME="M7"><B>error</B></A><DD>
|
||||
Error return: same as if the <B>error</B> command were used to
|
||||
terminate the procedure, except for handling of <B>errorInfo</B>
|
||||
and <B>errorCode</B> variables (see below).
|
||||
<P><DT><A NAME="M8"><B>return</B></A><DD>
|
||||
The current procedure will return with a completion code of
|
||||
TCL_RETURN, so that the procedure that invoked it will return
|
||||
also.
|
||||
<P><DT><A NAME="M9"><B>break</B></A><DD>
|
||||
The current procedure will return with a completion code of
|
||||
TCL_BREAK, which will terminate the innermost nested loop in
|
||||
the code that invoked the current procedure.
|
||||
<P><DT><A NAME="M10"><B>continue</B></A><DD>
|
||||
The current procedure will return with a completion code of
|
||||
TCL_CONTINUE, which will terminate the current iteration of
|
||||
the innermost nested loop in the code that invoked the current
|
||||
procedure.
|
||||
<P><DT><A NAME="M11"><I>value</I></A><DD>
|
||||
<I>Value</I> must be an integer; it will be returned as the
|
||||
completion code for the current procedure.
|
||||
<P></DL>
|
||||
<P>
|
||||
The <B>-code</B> option is rarely used.
|
||||
It is provided so that procedures that implement
|
||||
new control structures can reflect exceptional conditions back to
|
||||
their callers.
|
||||
<P>
|
||||
Two additional options, <B>-errorinfo</B> and <B>-errorcode</B>,
|
||||
may be used to provide additional information during error
|
||||
returns.
|
||||
These options are ignored unless <I>code</I> is <B>error</B>.
|
||||
<P>
|
||||
The <B>-errorinfo</B> option specifies an initial stack
|
||||
trace for the <B>errorInfo</B> variable; if it is not specified then
|
||||
the stack trace left in <B>errorInfo</B> will include the call to
|
||||
the procedure and higher levels on the stack but it will not include
|
||||
any information about the context of the error within the procedure.
|
||||
Typically the <I>info</I> value is supplied from the value left
|
||||
in <B>errorInfo</B> after a <B><A HREF="../TkCmd/catch.htm">catch</A></B> command trapped an error within
|
||||
the procedure.
|
||||
<P>
|
||||
If the <B>-errorcode</B> option is specified then <I>code</I> provides
|
||||
a value for the <B>errorCode</B> variable.
|
||||
If the option is not specified then <B>errorCode</B> will
|
||||
default to <B>NONE</B>.
|
||||
|
||||
<H3><A NAME="M12">SEE ALSO</A></H3>
|
||||
<B>break</B>, <B>continue</B>, <B>error</B>, <B><A HREF="../TkCmd/proc.htm">proc</A></B>
|
||||
<H3><A NAME="M13">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#break">break</A>, <A href="../Keywords/C.htm#continue">continue</A>, <A href="../Keywords/E.htm#error">error</A>, <A href="../Keywords/P.htm#procedure">procedure</A>, <A href="../Keywords/R.htm#return">return</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
354
hlp/en/tcl/safe.htm
Normal file
354
hlp/en/tcl/safe.htm
Normal file
@@ -0,0 +1,354 @@
|
||||
<HTML><HEAD><TITLE>Tcl Tcl Built-In Commands - Safe manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="safe.htm#M2" NAME="L1021">NAME</A>
|
||||
<DL><DD>Safe Base - A mechanism for creating and manipulating safe interpreters.</DL>
|
||||
<DD><A HREF="safe.htm#M3" NAME="L1022">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>::safe::interpCreate</B> ?<I>slave</I>? ?<I>options...</I>?
|
||||
<DD><B>::safe::interpInit</B> <I>slave</I> ?<I>options...</I>?
|
||||
<DD><B>::safe::interpConfigure</B> <I>slave</I> ?<I>options...</I>?
|
||||
<DD><B>::safe::interpDelete</B> <I>slave</I>
|
||||
<DD><B>::safe::interpAddToAccessPath</B> <I>slave</I> <I>directory</I>
|
||||
<DD><B>::safe::interpFindInAccessPath</B> <I>slave</I> <I>directory</I>
|
||||
<DD><B>::safe::setLogCmd</B> ?<I>cmd arg...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="safe.htm#M4" NAME="L1023">OPTIONS</A>
|
||||
<DD><A HREF="safe.htm#M5" NAME="L1024">DESCRIPTION</A>
|
||||
<DD><A HREF="safe.htm#M6" NAME="L1025">COMMANDS</A>
|
||||
<DL>
|
||||
<DD><A HREF="safe.htm#M7" NAME="L1026"><B>::safe::interpCreate</B> ?<I>slave</I>? ?<I>options...</I>?</A>
|
||||
<DD><A HREF="safe.htm#M8" NAME="L1027"><B>::safe::interpInit</B> <I>slave</I> ?<I>options...</I>?</A>
|
||||
<DD><A HREF="safe.htm#M9" NAME="L1028"><B>::safe::interpConfigure</B> <I>slave</I> ?<I>options...</I>?</A>
|
||||
<DD><A HREF="safe.htm#M10" NAME="L1029"><B>::safe::interpDelete</B> <I>slave</I></A>
|
||||
<DD><A HREF="safe.htm#M11" NAME="L1030"><B>::safe::interpFindInAccessPath</B> <I>slave</I> <I>directory</I></A>
|
||||
<DD><A HREF="safe.htm#M12" NAME="L1031"><B>::safe::interpAddToAccessPath</B> <I>slave</I> <I>directory</I></A>
|
||||
<DD><A HREF="safe.htm#M13" NAME="L1032"><B>::safe::setLogCmd</B> ?<I>cmd arg...</I>?</A>
|
||||
</DL>
|
||||
<DD><A HREF="safe.htm#M14" NAME="L1033">OPTIONS</A>
|
||||
<DL>
|
||||
<DD><A HREF="safe.htm#M15" NAME="L1034"><B>-accessPath</B> <I>directoryList</I></A>
|
||||
<DD><A HREF="safe.htm#M16" NAME="L1035"><B>-statics</B> <I>boolean</I></A>
|
||||
<DD><A HREF="safe.htm#M17" NAME="L1036"><B>-noStatics</B></A>
|
||||
<DD><A HREF="safe.htm#M18" NAME="L1037"><B>-nested</B> <I>boolean</I></A>
|
||||
<DD><A HREF="safe.htm#M19" NAME="L1038"><B>-nestedLoadOk</B></A>
|
||||
<DD><A HREF="safe.htm#M20" NAME="L1039"><B>-deleteHook</B> <I>script</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="safe.htm#M21" NAME="L1040">ALIASES</A>
|
||||
<DL>
|
||||
<DD><A HREF="safe.htm#M22" NAME="L1041"><B>source</B> <I>fileName</I></A>
|
||||
<DD><A HREF="safe.htm#M23" NAME="L1042"><B>load</B> <I>fileName</I></A>
|
||||
<DD><A HREF="safe.htm#M24" NAME="L1043"><B>file</B> ?<I>subCmd args...</I>?</A>
|
||||
<DD><A HREF="safe.htm#M25" NAME="L1044"><B>encoding</B> ?<I>subCmd args...</I>?</A>
|
||||
<DD><A HREF="safe.htm#M26" NAME="L1045"><B>exit</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="safe.htm#M27" NAME="L1046">SECURITY</A>
|
||||
<DD><A HREF="safe.htm#M28" NAME="L1047">SEE ALSO</A>
|
||||
<DD><A HREF="safe.htm#M29" NAME="L1048">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
Safe Base - A mechanism for creating and manipulating safe interpreters.
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>::safe::interpCreate</B> ?<I>slave</I>? ?<I>options...</I>?<BR>
|
||||
<B>::safe::interpInit</B> <I>slave</I> ?<I>options...</I>?<BR>
|
||||
<B>::safe::interpConfigure</B> <I>slave</I> ?<I>options...</I>?<BR>
|
||||
<B>::safe::interpDelete</B> <I>slave</I><BR>
|
||||
<B>::safe::interpAddToAccessPath</B> <I>slave</I> <I>directory</I><BR>
|
||||
<B>::safe::interpFindInAccessPath</B> <I>slave</I> <I>directory</I><BR>
|
||||
<B>::safe::setLogCmd</B> ?<I>cmd arg...</I>?<BR>
|
||||
<H3><A NAME="M4">OPTIONS</A></H3>
|
||||
?<B>-accessPath</B> <I>pathList</I>?
|
||||
?<B>-statics</B> <I>boolean</I>? ?<B>-noStatics</B>?
|
||||
?<B>-nested</B> <I>boolean</I>? ?<B>-nestedLoadOk</B>?
|
||||
?<B>-deleteHook</B> <I>script</I>?
|
||||
<H3><A NAME="M5">DESCRIPTION</A></H3>
|
||||
Safe Tcl is a mechanism for executing untrusted Tcl scripts
|
||||
safely and for providing mediated access by such scripts to
|
||||
potentially dangerous functionality.
|
||||
<P>
|
||||
The Safe Base ensures that untrusted Tcl scripts cannot harm the
|
||||
hosting application.
|
||||
The Safe Base prevents integrity and privacy attacks. Untrusted Tcl
|
||||
scripts are prevented from corrupting the state of the hosting
|
||||
application or computer. Untrusted scripts are also prevented from
|
||||
disclosing information stored on the hosting computer or in the
|
||||
hosting application to any party.
|
||||
<P>
|
||||
The Safe Base allows a master interpreter to create safe, restricted
|
||||
interpreters that contain a set of predefined aliases for the <B><A HREF="../TkCmd/source.htm">source</A></B>,
|
||||
<B><A HREF="../TkCmd/load.htm">load</A></B>, <B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/encoding.htm">encoding</A></B>, and <B><A HREF="../TkCmd/exit.htm">exit</A></B> commands and
|
||||
are able to use the auto-loading and package mechanisms.
|
||||
<P>
|
||||
No knowledge of the file system structure is leaked to the
|
||||
safe interpreter, because it has access only to a virtualized path
|
||||
containing tokens. When the safe interpreter requests to source a file, it
|
||||
uses the token in the virtual path as part of the file name to source; the
|
||||
master interpreter transparently
|
||||
translates the token into a real directory name and executes the
|
||||
requested operation (see the section <B>SECURITY</B> below for details).
|
||||
Different levels of security can be selected by using the optional flags
|
||||
of the commands described below.
|
||||
<P>
|
||||
All commands provided in the master interpreter by the Safe Base reside in
|
||||
the <B>safe</B> namespace:
|
||||
|
||||
<H3><A NAME="M6">COMMANDS</A></H3>
|
||||
The following commands are provided in the master interpreter:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M7"><B>::safe::interpCreate</B> ?<I>slave</I>? ?<I>options...</I>?</A><DD>
|
||||
Creates a safe interpreter, installs the aliases described in the section
|
||||
<B>ALIASES</B> and initializes the auto-loading and package mechanism as
|
||||
specified by the supplied <B><A HREF="../TclCmd/options.htm">options</A></B>.
|
||||
See the <B><A HREF="../TclCmd/options.htm">OPTIONS</A></B> section below for a description of the
|
||||
optional arguments.
|
||||
If the <I>slave</I> argument is omitted, a name will be generated.
|
||||
<B>::safe::interpCreate</B> always returns the interpreter name.
|
||||
<P><DT><A NAME="M8"><B>::safe::interpInit</B> <I>slave</I> ?<I>options...</I>?</A><DD>
|
||||
This command is similar to <B>interpCreate</B> except it that does not
|
||||
create the safe interpreter. <I>slave</I> must have been created by some
|
||||
other means, like <B>interp create -safe</B>.
|
||||
<P><DT><A NAME="M9"><B>::safe::interpConfigure</B> <I>slave</I> ?<I>options...</I>?</A><DD>
|
||||
If no <I>options</I> are given, returns the settings for all options for the
|
||||
named safe interpreter as a list of options and their current values
|
||||
for that <I>slave</I>.
|
||||
If a single additional argument is provided,
|
||||
it will return a list of 2 elements <I>name</I> and <I>value</I> where
|
||||
<I>name</I> is the full name of that option and <I>value</I> the current value
|
||||
for that option and the <I>slave</I>.
|
||||
If more than two additional arguments are provided, it will reconfigure the
|
||||
safe interpreter and change each and only the provided options.
|
||||
See the section on <B><A HREF="../TclCmd/options.htm">OPTIONS</A></B> below for options description.
|
||||
Example of use:
|
||||
<PRE># Create a new interp with the same configuration as "$i0" :
|
||||
set i1 [eval safe::interpCreate [safe::interpConfigure $i0]]
|
||||
# Get the current deleteHook
|
||||
set dh [safe::interpConfigure $i0 -del]
|
||||
# Change (only) the statics loading ok attribute of an interp
|
||||
# and its deleteHook (leaving the rest unchanged) :
|
||||
safe::interpConfigure $i0 -delete {foo bar} -statics 0 ;</PRE>
|
||||
<P><DT><A NAME="M10"><B>::safe::interpDelete</B> <I>slave</I></A><DD>
|
||||
Deletes the safe interpreter and cleans up the corresponding
|
||||
master interpreter data structures.
|
||||
If a <I>deleteHook</I> script was specified for this interpreter it is
|
||||
evaluated before the interpreter is deleted, with the name of the
|
||||
interpreter as an additional argument.
|
||||
<P><DT><A NAME="M11"><B>::safe::interpFindInAccessPath</B> <I>slave</I> <I>directory</I></A><DD>
|
||||
This command finds and returns the token for the real directory
|
||||
<I>directory</I> in the safe interpreter's current virtual access path.
|
||||
It generates an error if the directory is not found.
|
||||
Example of use:
|
||||
<PRE>$slave eval [list set tk_library [::safe::interpFindInAccessPath $name $tk_library]]</PRE>
|
||||
<P><DT><A NAME="M12"><B>::safe::interpAddToAccessPath</B> <I>slave</I> <I>directory</I></A><DD>
|
||||
This command adds <I>directory</I> to the virtual path maintained for the
|
||||
safe interpreter in the master, and returns the token that can be used in
|
||||
the safe interpreter to obtain access to files in that directory.
|
||||
If the directory is already in the virtual path, it only returns the token
|
||||
without adding the directory to the virtual path again.
|
||||
Example of use:
|
||||
<PRE>$slave eval [list set tk_library [::safe::interpAddToAccessPath $name $tk_library]]</PRE>
|
||||
<P><DT><A NAME="M13"><B>::safe::setLogCmd</B> ?<I>cmd arg...</I>?</A><DD>
|
||||
This command installs a script that will be called when interesting
|
||||
life cycle events occur for a safe interpreter.
|
||||
When called with no arguments, it returns the currently installed script.
|
||||
When called with one argument, an empty string, the currently installed
|
||||
script is removed and logging is turned off.
|
||||
The script will be invoked with one additional argument, a string
|
||||
describing the event of interest.
|
||||
The main purpose is to help in debugging safe interpreters.
|
||||
Using this facility you can get complete error messages while the safe
|
||||
interpreter gets only generic error messages.
|
||||
This prevents a safe interpreter from seeing messages about failures
|
||||
and other events that might contain sensitive information such as real
|
||||
directory names.
|
||||
<DL><P><DD>
|
||||
Example of use:
|
||||
<PRE>::safe::setLogCmd puts stderr</PRE>
|
||||
Below is the output of a sample session in which a safe interpreter
|
||||
attempted to source a file not found in its virtual access path.
|
||||
Note that the safe interpreter only received an error message saying that
|
||||
the file was not found:
|
||||
<PRE>NOTICE for slave interp10 : Created
|
||||
NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
|
||||
NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)}
|
||||
ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory</PRE>
|
||||
</DL>
|
||||
<P></DL>
|
||||
<H3><A NAME="M14">OPTIONS</A></H3>
|
||||
The following options are common to
|
||||
<B>::safe::interpCreate</B>, <B>::safe::interpInit</B>,
|
||||
and <B>::safe::interpConfigure</B>.
|
||||
Any option name can be abbreviated to its minimal
|
||||
non-ambiguous name.
|
||||
Option names are not case sensitive.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M15"><B>-accessPath</B> <I>directoryList</I></A><DD>
|
||||
This option sets the list of directories from which the safe interpreter
|
||||
can <B><A HREF="../TkCmd/source.htm">source</A></B> and <B><A HREF="../TkCmd/load.htm">load</A></B> files.
|
||||
If this option is not specified, or if it is given as the
|
||||
empty list, the safe interpreter will use the same directories as its
|
||||
master for auto-loading.
|
||||
See the section <B>SECURITY</B> below for more detail about virtual paths,
|
||||
tokens and access control.
|
||||
<P><DT><A NAME="M16"><B>-statics</B> <I>boolean</I></A><DD>
|
||||
This option specifies if the safe interpreter will be allowed
|
||||
to load statically linked packages (like <B>load {} Tk</B>).
|
||||
The default value is <B>true</B> :
|
||||
safe interpreters are allowed to load statically linked packages.
|
||||
<P><DT><A NAME="M17"><B>-noStatics</B></A><DD>
|
||||
This option is a convenience shortcut for <B>-statics false</B> and
|
||||
thus specifies that the safe interpreter will not be allowed
|
||||
to load statically linked packages.
|
||||
<P><DT><A NAME="M18"><B>-nested</B> <I>boolean</I></A><DD>
|
||||
This option specifies if the safe interpreter will be allowed
|
||||
to load packages into its own sub-interpreters.
|
||||
The default value is <B>false</B> :
|
||||
safe interpreters are not allowed to load packages into
|
||||
their own sub-interpreters.
|
||||
<P><DT><A NAME="M19"><B>-nestedLoadOk</B></A><DD>
|
||||
This option is a convenience shortcut for <B>-nested true</B> and
|
||||
thus specifies the safe interpreter will be allowed
|
||||
to load packages into its own sub-interpreters.
|
||||
<P><DT><A NAME="M20"><B>-deleteHook</B> <I>script</I></A><DD>
|
||||
When this option is given an non empty <I>script</I>, it will be
|
||||
evaluated in the master with the name of
|
||||
the safe interpreter as an additional argument
|
||||
just before actually deleting the safe interpreter.
|
||||
Giving an empty value removes any currently installed deletion hook
|
||||
script for that safe interpreter.
|
||||
The default value (<B>{}</B>) is not to have any deletion call back.
|
||||
<P></DL>
|
||||
<H3><A NAME="M21">ALIASES</A></H3>
|
||||
The following aliases are provided in a safe interpreter:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M22"><B>source</B> <I>fileName</I></A><DD>
|
||||
The requested file, a Tcl source file, is sourced into the safe interpreter
|
||||
if it is found.
|
||||
The <B><A HREF="../TkCmd/source.htm">source</A></B> alias can only source files from directories in
|
||||
the virtual path for the safe interpreter. The <B><A HREF="../TkCmd/source.htm">source</A></B> alias requires
|
||||
the safe interpreter to
|
||||
use one of the token names in its virtual path to denote the directory in
|
||||
which the file to be sourced can be found.
|
||||
See the section on <B>SECURITY</B> for more discussion of restrictions on
|
||||
valid filenames.
|
||||
<P><DT><A NAME="M23"><B>load</B> <I>fileName</I></A><DD>
|
||||
The requested file, a shared object file, is dynamically loaded into the
|
||||
safe interpreter if it is found.
|
||||
The filename must contain a token name mentioned in the virtual path for
|
||||
the safe interpreter for it to be found successfully.
|
||||
Additionally, the shared object file must contain a safe entry point; see
|
||||
the manual page for the <B><A HREF="../TkCmd/load.htm">load</A></B> command for more details.
|
||||
<P><DT><A NAME="M24"><B>file</B> ?<I>subCmd args...</I>?</A><DD>
|
||||
The <B><A HREF="../TkCmd/file.htm">file</A></B> alias provides access to a safe subset of the subcommands of
|
||||
the <B><A HREF="../TkCmd/file.htm">file</A></B> command; it allows only <B>dirname</B>, <B><A HREF="../TkCmd/join.htm">join</A></B>,
|
||||
<B>extension</B>, <B>root</B>, <B>tail</B>, <B>pathname</B> and <B><A HREF="../TkCmd/split.htm">split</A></B>
|
||||
subcommands. For more details on what these subcommands do see the manual
|
||||
page for the <B><A HREF="../TkCmd/file.htm">file</A></B> command.
|
||||
<P><DT><A NAME="M25"><B>encoding</B> ?<I>subCmd args...</I>?</A><DD>
|
||||
The <B>enconding</B> alias provides access to a safe subset of the
|
||||
subcommands of the <B><A HREF="../TkCmd/encoding.htm">encoding</A></B> command; it disallows setting of
|
||||
the system encoding, but allows all other subcommands including
|
||||
<B>system</B> to check the current encoding.
|
||||
<P><DT><A NAME="M26"><B>exit</B></A><DD>
|
||||
The calling interpreter is deleted and its computation is stopped, but the
|
||||
Tcl process in which this interpreter exists is not terminated.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M27">SECURITY</A></H3>
|
||||
The Safe Base does not attempt to completely prevent annoyance and
|
||||
denial of service attacks. These forms of attack prevent the
|
||||
application or user from temporarily using the computer to perform
|
||||
useful work, for example by consuming all available CPU time or
|
||||
all available screen real estate.
|
||||
These attacks, while aggravating, are deemed to be of lesser importance
|
||||
in general than integrity and privacy attacks that the Safe Base
|
||||
is to prevent.
|
||||
<P>
|
||||
The commands available in a safe interpreter, in addition to
|
||||
the safe set as defined in <B><A HREF="../TkCmd/interp.htm">interp</A></B> manual page, are mediated aliases
|
||||
for <B><A HREF="../TkCmd/source.htm">source</A></B>, <B><A HREF="../TkCmd/load.htm">load</A></B>, <B><A HREF="../TkCmd/exit.htm">exit</A></B>, and safe subsets of
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B> and <B><A HREF="../TkCmd/encoding.htm">encoding</A></B>. The safe interpreter can also auto-load
|
||||
code and it can request that packages be loaded.
|
||||
<P>
|
||||
Because some of these commands access the local file system, there is a
|
||||
potential for information leakage about its directory structure.
|
||||
To prevent this, commands that take file names as arguments in a safe
|
||||
interpreter use tokens instead of the real directory names.
|
||||
These tokens are translated to the real directory name while a request to,
|
||||
e.g., source a file is mediated by the master interpreter.
|
||||
This virtual path system is maintained in the master interpreter for each safe
|
||||
interpreter created by <B>::safe::interpCreate</B> or initialized by
|
||||
<B>::safe::interpInit</B> and
|
||||
the path maps tokens accessible in the safe interpreter into real path
|
||||
names on the local file system thus preventing safe interpreters
|
||||
from gaining knowledge about the
|
||||
structure of the file system of the host on which the interpreter is
|
||||
executing.
|
||||
The only valid file names arguments
|
||||
for the <B><A HREF="../TkCmd/source.htm">source</A></B> and <B><A HREF="../TkCmd/load.htm">load</A></B> aliases provided to the slave
|
||||
are path in the form of
|
||||
<B>[file join </B><I>token filename</I><B>]</B> (ie, when using the
|
||||
native file path formats: <I>token</I><B>/</B><I>filename</I>
|
||||
on Unix, <I>token</I><B>\</B><I>filename</I> on Windows,
|
||||
and <I>token</I><B>:</B><I>filename</I> on the Mac),
|
||||
where <I>token</I> is representing one of the directories
|
||||
of the <I>accessPath</I> list and <I>filename</I> is
|
||||
one file in that directory (no sub directories access are allowed).
|
||||
<P>
|
||||
When a token is used in a safe interpreter in a request to source or
|
||||
load a file, the token is checked and
|
||||
translated to a real path name and the file to be
|
||||
sourced or loaded is located on the file system.
|
||||
The safe interpreter never gains knowledge of the actual path name under
|
||||
which the file is stored on the file system.
|
||||
<P>
|
||||
To further prevent potential information leakage from sensitive files that
|
||||
are accidentally included in the set of files that can be sourced by a safe
|
||||
interpreter, the <B><A HREF="../TkCmd/source.htm">source</A></B> alias restricts access to files
|
||||
meeting the following constraints: the file name must
|
||||
fourteen characters or shorter, must not contain more than one dot ("<B>.</B>"),
|
||||
must end up with the extension <B>.tcl</B> or be called <B>tclIndex</B>.
|
||||
<P>
|
||||
Each element of the initial access path
|
||||
list will be assigned a token that will be set in
|
||||
the slave <B>auto_path</B> and the first element of that list will be set as
|
||||
the <B>tcl_library</B> for that slave.
|
||||
<P>
|
||||
If the access path argument is not given or is the empty list,
|
||||
the default behavior is to let the slave access the same packages
|
||||
as the master has access to (Or to be more precise:
|
||||
only packages written in Tcl (which by definition can't be dangerous
|
||||
as they run in the slave interpreter) and C extensions that
|
||||
provides a Safe_Init entry point). For that purpose, the master's
|
||||
<B>auto_path</B> will be used to construct the slave access path.
|
||||
In order that the slave successfully loads the Tcl library files
|
||||
(which includes the auto-loading mechanism itself) the <B>tcl_library</B> will be
|
||||
added or moved to the first position if necessary, in the
|
||||
slave access path, so the slave
|
||||
<B>tcl_library</B> will be the same as the master's (its real
|
||||
path will still be invisible to the slave though).
|
||||
In order that auto-loading works the same for the slave and
|
||||
the master in this by default case, the first-level
|
||||
sub directories of each directory in the master <B>auto_path</B> will
|
||||
also be added (if not already included) to the slave access path.
|
||||
You can always specify a more
|
||||
restrictive path for which sub directories will never be searched by
|
||||
explicitly specifying your directory list with the <B>-accessPath</B> flag
|
||||
instead of relying on this default mechanism.
|
||||
<P>
|
||||
When the <I>accessPath</I> is changed after the first creation or
|
||||
initialization (ie through <B>interpConfigure -accessPath </B><I>list</I>),
|
||||
an <B><A HREF="../TkCmd/library.htm">auto_reset</A></B> is automatically evaluated in the safe interpreter
|
||||
to synchronize its <B>auto_index</B> with the new token list.
|
||||
|
||||
<H3><A NAME="M28">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/interp.htm">interp</A></B>, <B>library</B>, <B><A HREF="../TkCmd/load.htm">load</A></B>, <B><A HREF="../TkCmd/package.htm">package</A></B>, <B><A HREF="../TkCmd/source.htm">source</A></B>, <B><A HREF="../TkCmd/unknown.htm">unknown</A></B>
|
||||
<H3><A NAME="M29">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#alias">alias</A>, <A href="../Keywords/A.htm#auto-loading">auto-loading</A>, <A href="../Keywords/A.htm#auto_mkindex">auto_mkindex</A>, <A href="../Keywords/L.htm#load">load</A>, <A href="../Keywords/M.htm#master interpreter">master interpreter</A>, <A href="../Keywords/S.htm#safe
|
||||
interpreter">safe
|
||||
interpreter</A>, <A href="../Keywords/S.htm#slave interpreter">slave interpreter</A>, <A href="../Keywords/S.htm#source">source</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
197
hlp/en/tcl/scan.htm
Normal file
197
hlp/en/tcl/scan.htm
Normal file
@@ -0,0 +1,197 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - scan manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="scan.htm#M2" NAME="L1049">NAME</A>
|
||||
<DL><DD>scan - Parse string using conversion specifiers in the style of sscanf</DL>
|
||||
<DD><A HREF="scan.htm#M3" NAME="L1050">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>scan </B><I>string format </I>?<I>varName varName ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="scan.htm#M4" NAME="L1051">INTRODUCTION</A>
|
||||
<DD><A HREF="scan.htm#M5" NAME="L1052">DETAILS ON SCANNING</A>
|
||||
<DL>
|
||||
<DD><A HREF="scan.htm#M6" NAME="L1053"><B>d</B></A>
|
||||
<DD><A HREF="scan.htm#M7" NAME="L1054"><B>o</B></A>
|
||||
<DD><A HREF="scan.htm#M8" NAME="L1055"><B>x</B></A>
|
||||
<DD><A HREF="scan.htm#M9" NAME="L1056"><B>u</B></A>
|
||||
<DD><A HREF="scan.htm#M10" NAME="L1057"><B>i</B></A>
|
||||
<DD><A HREF="scan.htm#M11" NAME="L1058"><B>c</B></A>
|
||||
<DD><A HREF="scan.htm#M12" NAME="L1059"><B>s</B></A>
|
||||
<DD><A HREF="scan.htm#M13" NAME="L1060"><B>e</B> or <B>f</B> or <B>g</B></A>
|
||||
<DD><A HREF="scan.htm#M14" NAME="L1061"><B>[</B><I>chars</I><B>]</B></A>
|
||||
<DD><A HREF="scan.htm#M15" NAME="L1062"><B>[^</B><I>chars</I><B>]</B></A>
|
||||
<DD><A HREF="scan.htm#M16" NAME="L1063"><B>n</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="scan.htm#M17" NAME="L1064">DIFFERENCES FROM ANSI SSCANF</A>
|
||||
<DL>
|
||||
</DL>
|
||||
<DD><A HREF="scan.htm#M18" NAME="L1065">SEE ALSO</A>
|
||||
<DD><A HREF="scan.htm#M19" NAME="L1066">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
scan - Parse string using conversion specifiers in the style of sscanf
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>scan </B><I>string format </I>?<I>varName varName ...</I>?<BR>
|
||||
<H3><A NAME="M4">INTRODUCTION</A></H3>
|
||||
This command parses fields from an input string in the same fashion as the
|
||||
ANSI C <B>sscanf</B> procedure and returns a count of the number of
|
||||
conversions performed, or -1 if the end of the input string is reached
|
||||
before any conversions have been performed. <I>String</I> gives the input
|
||||
to be parsed and <I>format</I> indicates how to parse it, using <B>%</B>
|
||||
conversion specifiers as in <B>sscanf</B>. Each <I>varName</I> gives the
|
||||
name of a variable; when a field is scanned from <I>string</I> the result is
|
||||
converted back into a string and assigned to the corresponding variable.
|
||||
If no <I>varName</I> variables are specified, then <B>scan</B> works in an
|
||||
inline manner, returning the data that would otherwise be stored in the
|
||||
variables as a list. In the inline case, an empty string is returned when
|
||||
the end of the input string is reached before any conversions have been
|
||||
performed.
|
||||
|
||||
<H3><A NAME="M5">DETAILS ON SCANNING</A></H3>
|
||||
<B>Scan</B> operates by scanning <I>string</I> and <I>format</I> together.
|
||||
If the next character in <I>format</I> is a blank or tab then it
|
||||
matches any number of white space characters in <I>string</I> (including
|
||||
zero).
|
||||
Otherwise, if it isn't a <B>%</B> character then it
|
||||
must match the next character of <I>string</I>.
|
||||
When a <B>%</B> is encountered in <I>format</I>, it indicates
|
||||
the start of a conversion specifier.
|
||||
A conversion specifier contains up to four fields after the <B>%</B>:
|
||||
a <B>*</B>, which indicates that the converted value is to be discarded
|
||||
instead of assigned to a variable; a XPG3 position specifier; a number
|
||||
indicating a maximum field width; and a conversion character.
|
||||
All of these fields are optional except for the conversion character.
|
||||
The fields that are present must appear in the order given above.
|
||||
<P>
|
||||
When <B>scan</B> finds a conversion specifier in <I>format</I>, it
|
||||
first skips any white-space characters in <I>string</I> (unless the
|
||||
specifier is <B>[</B> or <B>c</B>).
|
||||
Then it converts the next input characters according to the
|
||||
conversion specifier and stores the result in the variable given
|
||||
by the next argument to <B>scan</B>.
|
||||
<P>
|
||||
If the <B>%</B> is followed by a decimal number and a <B>$</B>, as in
|
||||
``<B>%2$d</B>'', then the variable to use is not taken from the next
|
||||
sequential argument. Instead, it is taken from the argument indicated
|
||||
by the number, where 1 corresponds to the first <I>varName</I>. If
|
||||
there are any positional specifiers in <I>format</I> then all of the
|
||||
specifiers must be positional. Every <I>varName</I> on the argument
|
||||
list must correspond to exactly one conversion specifier or an error
|
||||
is generated, or in the inline case, any position can be specified
|
||||
at most once and the empty positions will be filled in with empty strings.
|
||||
<P>
|
||||
The following conversion characters are supported:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>d</B></A><DD>
|
||||
The input field must be a decimal integer.
|
||||
It is read in and the value is stored in the variable as a decimal string.
|
||||
<P><DT><A NAME="M7"><B>o</B></A><DD>
|
||||
The input field must be an octal integer. It is read in and the
|
||||
value is stored in the variable as a decimal string.
|
||||
If the value exceeds MAX_INT (017777777777 on platforms using 32-bit
|
||||
integers), it will be truncated to a signed integer. Hence, 037777777777
|
||||
will appear as -1 on a 32-bit machine.
|
||||
<P><DT><A NAME="M8"><B>x</B></A><DD>
|
||||
The input field must be a hexadecimal integer. It is read in
|
||||
and the value is stored in the variable as a decimal string.
|
||||
If the value exceeds MAX_INT (0x7FFFFFFF on platforms using 32-bit
|
||||
integers), it will be truncated to a signed integer. Hence, 0xFFFFFFFF
|
||||
will appear as -1 on a 32-bit machine.
|
||||
<P><DT><A NAME="M9"><B>u</B></A><DD>
|
||||
The input field must be a decimal integer. The value is stored in the
|
||||
variable as an unsigned decimal integer string.
|
||||
<P><DT><A NAME="M10"><B>i</B></A><DD>
|
||||
The input field must be an integer. The base (i.e. decimal, octal, or
|
||||
hexadecimal) is determined in the same fashion as described in
|
||||
<B><A HREF="../TkCmd/expr.htm">expr</A></B>. The value is stored in the variable as a decimal string.
|
||||
<P><DT><A NAME="M11"><B>c</B></A><DD>
|
||||
A single character is read in and its binary value is stored in
|
||||
the variable as a decimal string.
|
||||
Initial white space is not skipped in this case, so the input
|
||||
field may be a white-space character.
|
||||
This conversion is different from the ANSI standard in that the
|
||||
input field always consists of a single character and no field
|
||||
width may be specified.
|
||||
<P><DT><A NAME="M12"><B>s</B></A><DD>
|
||||
The input field consists of all the characters up to the next
|
||||
white-space character; the characters are copied to the variable.
|
||||
<P><DT><A NAME="M13"><B>e</B> or <B>f</B> or <B>g</B></A><DD>
|
||||
The input field must be a floating-point number consisting
|
||||
of an optional sign, a string of decimal digits possibly
|
||||
containing a decimal point, and an optional exponent consisting
|
||||
of an <B>e</B> or <B>E</B> followed by an optional sign and a string of
|
||||
decimal digits.
|
||||
It is read in and stored in the variable as a floating-point string.
|
||||
<P><DT><A NAME="M14"><B>[</B><I>chars</I><B>]</B></A><DD>
|
||||
The input field consists of any number of characters in
|
||||
<I>chars</I>.
|
||||
The matching string is stored in the variable.
|
||||
If the first character between the brackets is a <B>]</B> then
|
||||
it is treated as part of <I>chars</I> rather than the closing
|
||||
bracket for the set.
|
||||
If <I>chars</I>
|
||||
contains a sequence of the form <I>a</I><B>-</B><I>b</I> then any
|
||||
character between <I>a</I> and <I>b</I> (inclusive) will match.
|
||||
If the first or last character between the brackets is a <B>-</B>, then
|
||||
it is treated as part of <I>chars</I> rather than indicating a range.
|
||||
<P><DT><A NAME="M15"><B>[^</B><I>chars</I><B>]</B></A><DD>
|
||||
The input field consists of any number of characters not in
|
||||
<I>chars</I>.
|
||||
The matching string is stored in the variable.
|
||||
If the character immediately following the <B>^</B> is a <B>]</B> then it is
|
||||
treated as part of the set rather than the closing bracket for
|
||||
the set.
|
||||
If <I>chars</I>
|
||||
contains a sequence of the form <I>a</I><B>-</B><I>b</I> then any
|
||||
character between <I>a</I> and <I>b</I> (inclusive) will be excluded
|
||||
from the set.
|
||||
If the first or last character between the brackets is a <B>-</B>, then
|
||||
it is treated as part of <I>chars</I> rather than indicating a range.
|
||||
<P><DT><A NAME="M16"><B>n</B></A><DD>
|
||||
No input is consumed from the input string. Instead, the total number
|
||||
of chacters scanned from the input string so far is stored in the variable.
|
||||
<P></DL>
|
||||
<P>
|
||||
The number of characters read from the input for a conversion is the
|
||||
largest number that makes sense for that particular conversion (e.g.
|
||||
as many decimal digits as possible for <B>%d</B>, as
|
||||
many octal digits as possible for <B>%o</B>, and so on).
|
||||
The input field for a given conversion terminates either when a
|
||||
white-space character is encountered or when the maximum field
|
||||
width has been reached, whichever comes first.
|
||||
If a <B>*</B> is present in the conversion specifier
|
||||
then no variable is assigned and the next scan argument is not consumed.
|
||||
|
||||
<H3><A NAME="M17">DIFFERENCES FROM ANSI SSCANF</A></H3>
|
||||
The behavior of the <B>scan</B> command is the same as the behavior of
|
||||
the ANSI C <B>sscanf</B> procedure except for the following differences:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT>[1]<DD>
|
||||
<B>%p</B> conversion specifier is not currently supported.
|
||||
<P><DT>[2]<DD>
|
||||
For <B>%c</B> conversions a single character value is
|
||||
converted to a decimal string, which is then assigned to the
|
||||
corresponding <I>varName</I>;
|
||||
no field width may be specified for this conversion.
|
||||
<P><DT>[3]<DD>
|
||||
The <B>l</B>, <B>h</B>, and <B>L</B> modifiers are ignored; integer
|
||||
values are always converted as if there were no modifier present
|
||||
and real values are always converted as if the <B>l</B> modifier
|
||||
were present (i.e. type <B>double</B> is used for the internal
|
||||
representation).
|
||||
<P><DT>[4]<DD>
|
||||
If the end of the input string is reached before any conversions have been
|
||||
performed and no variables are given, and empty string is returned.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M18">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/format.htm">format</A></B>, <B>sscanf</B>
|
||||
<H3><A NAME="M19">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#conversion specifier">conversion specifier</A>, <A href="../Keywords/P.htm#parse">parse</A>, <A href="../Keywords/S.htm#scan">scan</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 2000 Scriptics Corporation.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
51
hlp/en/tcl/seek.htm
Normal file
51
hlp/en/tcl/seek.htm
Normal file
@@ -0,0 +1,51 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - seek manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
seek - Change the access position for an open channel
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>seek </B><I>channelId offset </I>?<I>origin</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Changes the current access position for <I>channelId</I>.
|
||||
<I>ChannelId</I> must be a channel identifier such as returned from a
|
||||
previous invocation of <B><A HREF="../TkCmd/open.htm">open</A></B> or <B><A HREF="../TkCmd/socket.htm">socket</A></B>.
|
||||
The <I>offset</I> and <I>origin</I>
|
||||
arguments specify the position at which the next read or write will occur
|
||||
for <I>channelId</I>. <I>Offset</I> must be an integer (which may be
|
||||
negative) and <I>origin</I> must be one of the following:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>start</B></A><DD>
|
||||
The new access position will be <I>offset</I> bytes from the start
|
||||
of the underlying file or device.
|
||||
<P><DT><A NAME="M6"><B>current</B></A><DD>
|
||||
The new access position will be <I>offset</I> bytes from the current
|
||||
access position; a negative <I>offset</I> moves the access position
|
||||
backwards in the underlying file or device.
|
||||
<P><DT><A NAME="M7"><B>end</B></A><DD>
|
||||
The new access position will be <I>offset</I> bytes from the end of
|
||||
the file or device. A negative <I>offset</I> places the access position
|
||||
before the end of file, and a positive <I>offset</I> places the access
|
||||
position after the end of file.
|
||||
<P></DL>
|
||||
<P>
|
||||
The <I>origin</I> argument defaults to <B>start</B>.
|
||||
<P>
|
||||
The command flushes all buffered output for the channel before the command
|
||||
returns, even if the channel is in nonblocking mode.
|
||||
It also discards any buffered and unread input.
|
||||
This command returns an empty string.
|
||||
An error occurs if this command is applied to channels whose underlying
|
||||
file or device does not support seeking.
|
||||
<P>
|
||||
Note that <I>offset</I> values are byte offsets, not character
|
||||
offsets. Both <B>seek</B> and <B><A HREF="../TkCmd/tell.htm">tell</A></B> operate in terms of bytes,
|
||||
not characters, unlike <B><A HREF="../TkCmd/read.htm">read</A></B>.
|
||||
|
||||
<H3><A NAME="M8">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/open.htm">open</A></B>, <B><A HREF="../TkCmd/close.htm">close</A></B>, <B><A HREF="../TkCmd/gets.htm">gets</A></B>, <B><A HREF="../TkCmd/tell.htm">tell</A></B>
|
||||
<H3><A NAME="M9">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#access position">access position</A>, <A href="../Keywords/F.htm#file">file</A>, <A href="../Keywords/S.htm#seek">seek</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
40
hlp/en/tcl/set.htm
Normal file
40
hlp/en/tcl/set.htm
Normal file
@@ -0,0 +1,40 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - set manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
set - Read and write variables
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>set </B><I>varName </I>?<I>value</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Returns the value of variable <I>varName</I>.
|
||||
If <I>value</I> is specified, then set
|
||||
the value of <I>varName</I> to <I>value</I>, creating a new variable
|
||||
if one doesn't already exist, and return its value.
|
||||
If <I>varName</I> contains an open parenthesis and ends with a
|
||||
close parenthesis, then it refers to an array element: the characters
|
||||
before the first open parenthesis are the name of the array,
|
||||
and the characters between the parentheses are the index within the array.
|
||||
Otherwise <I>varName</I> refers to a scalar variable.
|
||||
Normally, <I>varName</I> is unqualified
|
||||
(does not include the names of any containing namespaces),
|
||||
and the variable of that name in the current namespace is read or written.
|
||||
If <I>varName</I> includes namespace qualifiers
|
||||
(in the array name if it refers to an array element),
|
||||
the variable in the specified namespace is read or written.
|
||||
<P>
|
||||
If no procedure is active,
|
||||
then <I>varName</I> refers to a namespace variable
|
||||
(global variable if the current namespace is the global namespace).
|
||||
If a procedure is active, then <I>varName</I> refers to a parameter
|
||||
or local variable of the procedure unless the <B><A HREF="../TkCmd/global.htm">global</A></B> command
|
||||
was invoked to declare <I>varName</I> to be global,
|
||||
or unless a <B><A HREF="../TkCmd/variable.htm">variable</A></B> command
|
||||
was invoked to declare <I>varName</I> to be a namespace variable.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/expr.htm">expr</A></B>, <B><A HREF="../TkCmd/proc.htm">proc</A></B>, <B><A HREF="../TkCmd/trace.htm">trace</A></B>, <B><A HREF="../TkCmd/unset.htm">unset</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/R.htm#read">read</A>, <A href="../Keywords/W.htm#write">write</A>, <A href="../Keywords/V.htm#variable">variable</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
147
hlp/en/tcl/socket.htm
Normal file
147
hlp/en/tcl/socket.htm
Normal file
@@ -0,0 +1,147 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - socket manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="socket.htm#M2" NAME="L1080">NAME</A>
|
||||
<DL><DD>socket - Open a TCP network connection</DL>
|
||||
<DD><A HREF="socket.htm#M3" NAME="L1081">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>socket </B>?<I>options</I>? <I>host port</I>
|
||||
<DD><B>socket</B> <B>-server </B><I>command</I> ?<I>options</I>? <I>port</I>
|
||||
</DL>
|
||||
<DD><A HREF="socket.htm#M4" NAME="L1082">DESCRIPTION</A>
|
||||
<DD><A HREF="socket.htm#M5" NAME="L1083">CLIENT SOCKETS</A>
|
||||
<DL>
|
||||
<DD><A HREF="socket.htm#M6" NAME="L1084"><B>-myaddr</B><I> addr</I></A>
|
||||
<DD><A HREF="socket.htm#M7" NAME="L1085"><B>-myport</B><I> port</I></A>
|
||||
<DD><A HREF="socket.htm#M8" NAME="L1086"><B>-async</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="socket.htm#M9" NAME="L1087">SERVER SOCKETS</A>
|
||||
<DL>
|
||||
<DD><A HREF="socket.htm#M10" NAME="L1088"><B>-myaddr</B><I> addr</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="socket.htm#M11" NAME="L1089">CONFIGURATION OPTIONS</A>
|
||||
<DL>
|
||||
<DD><A HREF="socket.htm#M12" NAME="L1090"><B>-error</B></A>
|
||||
<DD><A HREF="socket.htm#M13" NAME="L1091"><B>-sockname</B></A>
|
||||
<DD><A HREF="socket.htm#M14" NAME="L1092"><B>-peername</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="socket.htm#M15" NAME="L1093">SEE ALSO</A>
|
||||
<DD><A HREF="socket.htm#M16" NAME="L1094">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
socket - Open a TCP network connection
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>socket </B>?<I>options</I>? <I>host port</I><BR>
|
||||
<B>socket</B> <B>-server </B><I>command</I> ?<I>options</I>? <I>port</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command opens a network socket and returns a channel
|
||||
identifier that may be used in future invocations of commands like
|
||||
<B><A HREF="../TkCmd/read.htm">read</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B> and <B><A HREF="../TkCmd/flush.htm">flush</A></B>.
|
||||
At present only the TCP network protocol is supported; future
|
||||
releases may include support for additional protocols.
|
||||
The <B>socket</B> command may be used to open either the client or
|
||||
server side of a connection, depending on whether the <B>-server</B>
|
||||
switch is specified.
|
||||
|
||||
<H3><A NAME="M5">CLIENT SOCKETS</A></H3>
|
||||
If the <B>-server</B> option is not specified, then the client side of a
|
||||
connection is opened and the command returns a channel identifier
|
||||
that can be used for both reading and writing.
|
||||
<I>Port</I> and <I>host</I> specify a port
|
||||
to connect to; there must be a server accepting connections on
|
||||
this port. <I>Port</I> is an integer port number and <I>host</I>
|
||||
is either a domain-style name such as <B>www.sunlabs.com</B> or
|
||||
a numerical IP address such as <B>127.0.0.1</B>.
|
||||
Use <I>localhost</I> to refer to the host on which the command is invoked.
|
||||
<P>
|
||||
The following options may also be present before <I>host</I>
|
||||
to specify additional information about the connection:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>-myaddr</B><I> addr</I></A><DD>
|
||||
<I>Addr</I> gives the domain-style name or numerical IP address of
|
||||
the client-side network interface to use for the connection.
|
||||
This option may be useful if the client machine has multiple network
|
||||
interfaces. If the option is omitted then the client-side interface
|
||||
will be chosen by the system software.
|
||||
<P><DT><A NAME="M7"><B>-myport</B><I> port</I></A><DD>
|
||||
<I>Port</I> specifies an integer port number to use for the client's
|
||||
side of the connection. If this option is omitted, the client's
|
||||
port number will be chosen at random by the system software.
|
||||
<P><DT><A NAME="M8"><B>-async</B></A><DD>
|
||||
The <B>-async</B> option will cause the client socket to be connected
|
||||
asynchronously. This means that the socket will be created immediately but
|
||||
may not yet be connected to the server, when the call to <B>socket</B>
|
||||
returns. When a <B><A HREF="../TkCmd/gets.htm">gets</A></B> or <B><A HREF="../TkCmd/flush.htm">flush</A></B> is done on the socket before the
|
||||
connection attempt succeeds or fails, if the socket is in blocking mode, the
|
||||
operation will wait until the connection is completed or fails. If the
|
||||
socket is in nonblocking mode and a <B><A HREF="../TkCmd/gets.htm">gets</A></B> or <B><A HREF="../TkCmd/flush.htm">flush</A></B> is done on
|
||||
the socket before the connection attempt succeeds or fails, the operation
|
||||
returns immediately and <B><A HREF="../TkCmd/fblocked.htm">fblocked</A></B> on the socket returns 1.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M9">SERVER SOCKETS</A></H3>
|
||||
If the <B>-server</B> option is specified then the new socket
|
||||
will be a server for the port given by <I>port</I>.
|
||||
Tcl will automatically accept connections to the given port.
|
||||
For each connection Tcl will create a new channel that may be used to
|
||||
communicate with the client. Tcl then invokes <I>command</I>
|
||||
with three additional arguments: the name of the new channel, the
|
||||
address, in network address notation, of the client's host, and
|
||||
the client's port number.
|
||||
<P>
|
||||
The following additional option may also be specified before <I>host</I>:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M10"><B>-myaddr</B><I> addr</I></A><DD>
|
||||
<I>Addr</I> gives the domain-style name or numerical IP address of
|
||||
the server-side network interface to use for the connection.
|
||||
This option may be useful if the server machine has multiple network
|
||||
interfaces. If the option is omitted then the server socket is bound
|
||||
to the special address INADDR_ANY so that it can accept connections from
|
||||
any interface.
|
||||
<P></DL>
|
||||
<P>
|
||||
Server channels cannot be used for input or output; their sole use is to
|
||||
accept new client connections. The channels created for each incoming
|
||||
client connection are opened for input and output. Closing the server
|
||||
channel shuts down the server so that no new connections will be
|
||||
accepted; however, existing connections will be unaffected.
|
||||
<P>
|
||||
Server sockets depend on the Tcl event mechanism to find out when
|
||||
new connections are opened. If the application doesn't enter the
|
||||
event loop, for example by invoking the <B><A HREF="../TkCmd/vwait.htm">vwait</A></B> command or
|
||||
calling the C procedure <B><A HREF="../TkLib/DoOneEvent.htm">Tcl_DoOneEvent</A></B>, then no connections
|
||||
will be accepted.
|
||||
|
||||
<H3><A NAME="M11">CONFIGURATION OPTIONS</A></H3>
|
||||
The <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> command can be used to query several readonly
|
||||
configuration options for socket channels:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M12"><B>-error</B></A><DD>
|
||||
This option gets the current error status of the given socket. This
|
||||
is useful when you need to determine if an asynchronous connect
|
||||
operation succeeded. If there was an error, the error message is
|
||||
returned. If there was no error, an empty string is returned.
|
||||
<P><DT><A NAME="M13"><B>-sockname</B></A><DD>
|
||||
This option returns a list of three elements, the address, the host name
|
||||
and the port number for the socket. If the host name cannot be computed,
|
||||
the second element is identical to the address, the first element of the
|
||||
list.
|
||||
<P><DT><A NAME="M14"><B>-peername</B></A><DD>
|
||||
This option is not supported by server sockets. For client and accepted
|
||||
sockets, this option returns a list of three elements; these are the
|
||||
address, the host name and the port to which the peer socket is connected
|
||||
or bound. If the host name cannot be computed, the second element of the
|
||||
list is identical to the address, its first element.
|
||||
<P></DL>
|
||||
<P>
|
||||
<H3><A NAME="M15">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/flush.htm">flush</A></B>, <B><A HREF="../TkCmd/open.htm">open</A></B>, <B><A HREF="../TkCmd/read.htm">read</A></B>
|
||||
<H3><A NAME="M16">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#bind">bind</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/C.htm#connection">connection</A>, <A href="../Keywords/D.htm#domain name">domain name</A>, <A href="../Keywords/H.htm#host">host</A>, <A href="../Keywords/N.htm#network address">network address</A>, <A href="../Keywords/S.htm#socket">socket</A>, <A href="../Keywords/T.htm#tcp">tcp</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1998-1999 by Scriptics Corporation.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
32
hlp/en/tcl/source.htm
Normal file
32
hlp/en/tcl/source.htm
Normal file
@@ -0,0 +1,32 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - source manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
source - Evaluate a file or resource as a Tcl script
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>source </B><I>fileName</I><BR>
|
||||
<B>source</B> <B>-rsrc </B><I>resourceName </I>?<I>fileName</I>?<BR>
|
||||
<B>source</B> <B>-rsrcid </B><I>resourceId </I>?<I>fileName</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command takes the contents of the specified file or resource
|
||||
and passes it to the Tcl interpreter as a text script. The return
|
||||
value from <B>source</B> is the return value of the last command
|
||||
executed in the script. If an error occurs in evaluating the contents
|
||||
of the script then the <B>source</B> command will return that error.
|
||||
If a <B><A HREF="../TkCmd/return.htm">return</A></B> command is invoked from within the script then the
|
||||
remainder of the file will be skipped and the <B>source</B> command
|
||||
will return normally with the result from the <B><A HREF="../TkCmd/return.htm">return</A></B> command.
|
||||
|
||||
The <I>-rsrc</I> and <I>-rsrcid</I> forms of this command are only
|
||||
available on Macintosh computers. These versions of the command
|
||||
allow you to source a script from a <B>TEXT</B> resource. You may specify
|
||||
what <B>TEXT</B> resource to source by either name or id. By default Tcl
|
||||
searches all open resource files, which include the current
|
||||
application and any loaded C extensions. Alternatively, you may
|
||||
specify the <I>fileName</I> where the <B>TEXT</B> resource can be found.
|
||||
|
||||
<H3><A NAME="M5">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/F.htm#file">file</A>, <A href="../Keywords/S.htm#script">script</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
32
hlp/en/tcl/split.htm
Normal file
32
hlp/en/tcl/split.htm
Normal file
@@ -0,0 +1,32 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - split manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
split - Split a string into a proper Tcl list
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>split </B><I>string </I>?<I>splitChars</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Returns a list created by splitting <I>string</I> at each character
|
||||
that is in the <I>splitChars</I> argument.
|
||||
Each element of the result list will consist of the
|
||||
characters from <I>string</I> that lie between instances of the
|
||||
characters in <I>splitChars</I>.
|
||||
Empty list elements will be generated if <I>string</I> contains
|
||||
adjacent characters in <I>splitChars</I>, or if the first or last
|
||||
character of <I>string</I> is in <I>splitChars</I>.
|
||||
If <I>splitChars</I> is an empty string then each character of
|
||||
<I>string</I> becomes a separate element of the result list.
|
||||
<I>SplitChars</I> defaults to the standard white-space characters.
|
||||
For example,
|
||||
<PRE><B>split "comp.unix.misc" .</B></PRE>
|
||||
returns <B>"comp unix misc"</B> and
|
||||
<PRE><B>split "Hello world" {}</B></PRE>
|
||||
returns <B>"H e l l o { } w o r l d"</B>.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/join.htm">join</A></B>, <B><A HREF="../TkCmd/list.htm">list</A></B>, <B><A HREF="../TkCmd/string.htm">string</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/L.htm#list">list</A>, <A href="../Keywords/S.htm#split">split</A>, <A href="../Keywords/S.htm#string">string</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
338
hlp/en/tcl/string.htm
Normal file
338
hlp/en/tcl/string.htm
Normal file
@@ -0,0 +1,338 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - string manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="string.htm#M2" NAME="L1104">NAME</A>
|
||||
<DL><DD>string - Manipulate strings</DL>
|
||||
<DD><A HREF="string.htm#M3" NAME="L1105">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>string </B><I>option arg </I>?<I>arg ...?</I>
|
||||
</DL>
|
||||
<DD><A HREF="string.htm#M4" NAME="L1106">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="string.htm#M5" NAME="L1107"><B>string bytelength </B><I>string</I></A>
|
||||
<DD><A HREF="string.htm#M6" NAME="L1108"><B>string compare</B> ?<B>-nocase</B>? ?<B>-length int</B>? <I>string1 string2</I></A>
|
||||
<DD><A HREF="string.htm#M7" NAME="L1109"><B>string equal</B> ?<B>-nocase</B>? ?<B>-length int</B>? <I>string1 string2</I></A>
|
||||
<DD><A HREF="string.htm#M8" NAME="L1110"><B>string first </B><I>string1 string2</I> ?<I>startIndex</I>?</A>
|
||||
<DD><A HREF="string.htm#M9" NAME="L1111"><B>string index </B><I>string charIndex</I></A>
|
||||
<DL>
|
||||
<DD><A HREF="string.htm#M10" NAME="L1112"><I>integer</I></A>
|
||||
<DD><A HREF="string.htm#M11" NAME="L1113"><B>end</B></A>
|
||||
<DD><A HREF="string.htm#M12" NAME="L1114"><B>end-</B><I>integer</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="string.htm#M13" NAME="L1115"><B>string is </B><I>class</I> ?<B>-strict</B>? ?<B>-failindex </B><I>varname</I>? <I>string</I></A>
|
||||
<DL>
|
||||
<DD><A HREF="string.htm#M14" NAME="L1116"><B>alnum</B></A>
|
||||
<DD><A HREF="string.htm#M15" NAME="L1117"><B>alpha</B></A>
|
||||
<DD><A HREF="string.htm#M16" NAME="L1118"><B>ascii</B></A>
|
||||
<DD><A HREF="string.htm#M17" NAME="L1119"><B>boolean</B></A>
|
||||
<DD><A HREF="string.htm#M18" NAME="L1120"><B>control</B></A>
|
||||
<DD><A HREF="string.htm#M19" NAME="L1121"><B>digit</B></A>
|
||||
<DD><A HREF="string.htm#M20" NAME="L1122"><B>double</B></A>
|
||||
<DD><A HREF="string.htm#M21" NAME="L1123"><B>false</B></A>
|
||||
<DD><A HREF="string.htm#M22" NAME="L1124"><B>graph</B></A>
|
||||
<DD><A HREF="string.htm#M23" NAME="L1125"><B>integer</B></A>
|
||||
<DD><A HREF="string.htm#M24" NAME="L1126"><B>lower</B></A>
|
||||
<DD><A HREF="string.htm#M25" NAME="L1127"><B>print</B></A>
|
||||
<DD><A HREF="string.htm#M26" NAME="L1128"><B>punct</B></A>
|
||||
<DD><A HREF="string.htm#M27" NAME="L1129"><B>space</B></A>
|
||||
<DD><A HREF="string.htm#M28" NAME="L1130"><B>true</B></A>
|
||||
<DD><A HREF="string.htm#M29" NAME="L1131"><B>upper</B></A>
|
||||
<DD><A HREF="string.htm#M30" NAME="L1132"><B>wordchar</B></A>
|
||||
<DD><A HREF="string.htm#M31" NAME="L1133"><B>xdigit</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="string.htm#M32" NAME="L1134"><B>string last </B><I>string1 string2</I> ?<I>startIndex</I>?</A>
|
||||
<DD><A HREF="string.htm#M33" NAME="L1135"><B>string length </B><I>string</I></A>
|
||||
<DD><A HREF="string.htm#M34" NAME="L1136"><B>string map</B> ?<B>-nocase</B>? <I>charMap string</I></A>
|
||||
<DD><A HREF="string.htm#M35" NAME="L1137"><B>string match</B> ?<B>-nocase</B>? <I>pattern</I> <I>string</I></A>
|
||||
<DL>
|
||||
<DD><A HREF="string.htm#M36" NAME="L1138"><B>*</B></A>
|
||||
<DD><A HREF="string.htm#M37" NAME="L1139"><B>?</B></A>
|
||||
<DD><A HREF="string.htm#M38" NAME="L1140"><B>[</B><I>chars</I><B>]</B></A>
|
||||
<DD><A HREF="string.htm#M39" NAME="L1141"><B>\</B><I>x</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="string.htm#M40" NAME="L1142"><B>string range </B><I>string first last</I></A>
|
||||
<DD><A HREF="string.htm#M41" NAME="L1143"><B>string repeat </B><I>string count</I></A>
|
||||
<DD><A HREF="string.htm#M42" NAME="L1144"><B>string replace </B><I>string first last</I> ?<I>newstring</I>?</A>
|
||||
<DD><A HREF="string.htm#M43" NAME="L1145"><B>string tolower </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A>
|
||||
<DD><A HREF="string.htm#M44" NAME="L1146"><B>string totitle </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A>
|
||||
<DD><A HREF="string.htm#M45" NAME="L1147"><B>string toupper </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A>
|
||||
<DD><A HREF="string.htm#M46" NAME="L1148"><B>string trim </B><I>string</I> ?<I>chars</I>?</A>
|
||||
<DD><A HREF="string.htm#M47" NAME="L1149"><B>string trimleft </B><I>string</I> ?<I>chars</I>?</A>
|
||||
<DD><A HREF="string.htm#M48" NAME="L1150"><B>string trimright </B><I>string</I> ?<I>chars</I>?</A>
|
||||
<DD><A HREF="string.htm#M49" NAME="L1151"><B>string wordend </B><I>string charIndex</I></A>
|
||||
<DD><A HREF="string.htm#M50" NAME="L1152"><B>string wordstart </B><I>string charIndex</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="string.htm#M51" NAME="L1153">SEE ALSO</A>
|
||||
<DD><A HREF="string.htm#M52" NAME="L1154">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
string - Manipulate strings
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>string </B><I>option arg </I>?<I>arg ...?</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Performs one of several string operations, depending on <I>option</I>.
|
||||
The legal <I>option</I>s (which may be abbreviated) are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>string bytelength </B><I>string</I></A><DD>
|
||||
Returns a decimal string giving the number of bytes used to represent
|
||||
<I>string</I> in memory. Because UTF-8 uses one to three bytes to
|
||||
represent Unicode characters, the byte length will not be the same as
|
||||
the character length in general. The cases where a script cares about
|
||||
the byte length are rare. In almost all cases, you should use the
|
||||
<B>string length</B> operation. Refer to the <B><A HREF="../TkLib/Utf.htm">Tcl_NumUtfChars</A></B>
|
||||
manual entry for more details on the UTF-8 representation.
|
||||
<P><DT><A NAME="M6"><B>string compare</B> ?<B>-nocase</B>? ?<B>-length int</B>? <I>string1 string2</I></A><DD>
|
||||
Perform a character-by-character comparison of strings <I>string1</I> and
|
||||
<I>string2</I>. Returns
|
||||
-1, 0, or 1, depending on whether <I>string1</I> is lexicographically
|
||||
less than, equal to, or greater than <I>string2</I>.
|
||||
If <B>-length</B> is specified, then only the first <I>length</I> characters
|
||||
are used in the comparison. If <B>-length</B> is negative, it is
|
||||
ignored. If <B>-nocase</B> is specified, then the strings are
|
||||
compared in a case-insensitive manner.
|
||||
<P><DT><A NAME="M7"><B>string equal</B> ?<B>-nocase</B>? ?<B>-length int</B>? <I>string1 string2</I></A><DD>
|
||||
Perform a character-by-character comparison of strings
|
||||
<I>string1</I> and <I>string2</I>. Returns 1 if <I>string1</I> and
|
||||
<I>string2</I> are identical, or 0 when not. If <B>-length</B> is
|
||||
specified, then only the first <I>length</I> characters are used in the
|
||||
comparison. If <B>-length</B> is negative, it is ignored. If
|
||||
<B>-nocase</B> is specified, then the strings are compared in a
|
||||
case-insensitive manner.
|
||||
<P><DT><A NAME="M8"><B>string first </B><I>string1 string2</I> ?<I>startIndex</I>?</A><DD>
|
||||
Search <I>string2</I> for a sequence of characters that exactly match
|
||||
the characters in <I>string1</I>. If found, return the index of the
|
||||
first character in the first such match within <I>string2</I>. If not
|
||||
found, return -1.
|
||||
If <I>startIndex</I> is specified (in any of the forms accepted by the
|
||||
<B>index</B> method), then the search is constrained to start with the
|
||||
character in <I>string2</I> specified by the index. For example,
|
||||
<PRE><B>string first a 0a23456789abcdef 5</B></PRE>
|
||||
will return <B>10</B>, but
|
||||
<PRE><B>string first a 0123456789abcdef 11</B></PRE>
|
||||
will return <B>-1</B>.
|
||||
<P><DT><A NAME="M9"><B>string index </B><I>string charIndex</I></A><DD>
|
||||
Returns the <I>charIndex</I>'th character of the <I>string</I>
|
||||
argument. A <I>charIndex</I> of 0 corresponds to the first
|
||||
character of the string.
|
||||
<I>charIndex</I> may be specified as
|
||||
follows:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M10"><I>integer</I></A><DD>
|
||||
The char specified at this integral index
|
||||
<P><DT><A NAME="M11"><B>end</B></A><DD>
|
||||
The last char of the string.
|
||||
<P><DT><A NAME="M12"><B>end-</B><I>integer</I></A><DD>
|
||||
The last char of the string minus the specified integer
|
||||
offset (e.g. <B>end-1</B> would refer to the "c" in "abcd").
|
||||
</DL><P>If <I>charIndex</I> is less than 0 or greater than
|
||||
or equal to the length of the string then an empty string is
|
||||
returned.<DL>
|
||||
<P></DL>
|
||||
<P><DT><A NAME="M13"><B>string is </B><I>class</I> ?<B>-strict</B>? ?<B>-failindex </B><I>varname</I>? <I>string</I></A><DD>
|
||||
Returns 1 if <I>string</I> is a valid member of the specified character
|
||||
class, otherwise returns 0. If <B>-strict</B> is specified, then an
|
||||
empty string returns 0, otherwise and empty string will return 1 on
|
||||
any class. If <B>-failindex</B> is specified, then if the function
|
||||
returns 0, the index in the string where the class was no longer valid
|
||||
will be stored in the variable named <I>varname</I>. The <I>varname</I>
|
||||
will not be set if the function returns 1. The following character classes
|
||||
are recognized (the class name can be abbreviated):
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M14"><B>alnum</B></A><DD>
|
||||
Any Unicode alphabet or digit character.
|
||||
<P><DT><A NAME="M15"><B>alpha</B></A><DD>
|
||||
Any Unicode alphabet character.
|
||||
<P><DT><A NAME="M16"><B>ascii</B></A><DD>
|
||||
Any character with a value less than \u0080 (those that
|
||||
are in the 7-bit ascii range).
|
||||
<P><DT><A NAME="M17"><B>boolean</B></A><DD>
|
||||
Any of the forms allowed to <B><A HREF="../TkLib/GetInt.htm">Tcl_GetBoolean</A></B>.
|
||||
<P><DT><A NAME="M18"><B>control</B></A><DD>
|
||||
Any Unicode control character.
|
||||
<P><DT><A NAME="M19"><B>digit</B></A><DD>
|
||||
Any Unicode digit character. Note that this includes characters
|
||||
outside of the [0-9] range.
|
||||
<P><DT><A NAME="M20"><B>double</B></A><DD>
|
||||
Any of the valid forms for a double in Tcl, with optional surrounding
|
||||
whitespace. In case of under/overflow in the value, 0 is returned
|
||||
and the <I>varname</I> will contain -1.
|
||||
<P><DT><A NAME="M21"><B>false</B></A><DD>
|
||||
Any of the forms allowed to <B><A HREF="../TkLib/GetInt.htm">Tcl_GetBoolean</A></B> where the value is false.
|
||||
<P><DT><A NAME="M22"><B>graph</B></A><DD>
|
||||
Any Unicode printing character, except space.
|
||||
<P><DT><A NAME="M23"><B>integer</B></A><DD>
|
||||
Any of the valid forms for an integer in Tcl, with optional surrounding
|
||||
whitespace. In case of under/overflow in the value, 0 is returned
|
||||
and the <I>varname</I> will contain -1.
|
||||
<P><DT><A NAME="M24"><B>lower</B></A><DD>
|
||||
Any Unicode lower case alphabet character.
|
||||
<P><DT><A NAME="M25"><B>print</B></A><DD>
|
||||
Any Unicode printing character, including space.
|
||||
<P><DT><A NAME="M26"><B>punct</B></A><DD>
|
||||
Any Unicode punctuation character.
|
||||
<P><DT><A NAME="M27"><B>space</B></A><DD>
|
||||
Any Unicode space character.
|
||||
<P><DT><A NAME="M28"><B>true</B></A><DD>
|
||||
Any of the forms allowed to <B><A HREF="../TkLib/GetInt.htm">Tcl_GetBoolean</A></B> where the value is true.
|
||||
<P><DT><A NAME="M29"><B>upper</B></A><DD>
|
||||
Any upper case alphabet character in the Unicode character set.
|
||||
<P><DT><A NAME="M30"><B>wordchar</B></A><DD>
|
||||
Any Unicode word character. That is any alphanumeric character,
|
||||
and any Unicode connector punctuation characters (e.g. underscore).
|
||||
<P><DT><A NAME="M31"><B>xdigit</B></A><DD>
|
||||
Any hexadecimal digit character ([0-9A-Fa-f]).
|
||||
</DL><P>In the case of <B>boolean</B>, <B>true</B> and <B>false</B>, if the
|
||||
function will return 0, then the <I>varname</I> will always be set to 0,
|
||||
due to the varied nature of a valid boolean value.<DL>
|
||||
<P></DL>
|
||||
<P><DT><A NAME="M32"><B>string last </B><I>string1 string2</I> ?<I>startIndex</I>?</A><DD>
|
||||
Search <I>string2</I> for a sequence of characters that exactly match
|
||||
the characters in <I>string1</I>. If found, return the index of the
|
||||
first character in the last such match within <I>string2</I>. If there
|
||||
is no match, then return -1.
|
||||
If <I>startIndex</I> is specified (in any of the forms accepted by the
|
||||
<B>index</B> method), then only the characters in <I>string2</I> at or before the
|
||||
specified <I>startIndex</I> will be considered by the search. For example,
|
||||
<PRE><B>string last a 0a23456789abcdef 15</B></PRE>
|
||||
will return <B>10</B>, but
|
||||
<PRE><B>string last a 0a23456789abcdef 9</B></PRE>
|
||||
will return <B>1</B>.
|
||||
<P><DT><A NAME="M33"><B>string length </B><I>string</I></A><DD>
|
||||
Returns a decimal string giving the number of characters in
|
||||
<I>string</I>. Note that this is not necessarily the same as the
|
||||
number of bytes used to store the string.
|
||||
<P><DT><A NAME="M34"><B>string map</B> ?<B>-nocase</B>? <I>charMap string</I></A><DD>
|
||||
Replaces characters in <I>string</I> based on the key-value pairs in
|
||||
<I>charMap</I>. <I>charMap</I> is a list of <I>key value key value</I> ...
|
||||
as in the form returned by <B><A HREF="../TkCmd/array.htm">array get</A></B>. Each instance of a
|
||||
key in the string will be replaced with its corresponding value. If
|
||||
<B>-nocase</B> is specified, then matching is done without regard to
|
||||
case differences. Both <I>key</I> and <I>value</I> may be multiple
|
||||
characters. Replacement is done in an ordered manner, so the key appearing
|
||||
first in the list will be checked first, and so on. <I>string</I> is
|
||||
only iterated over once, so earlier key replacements will have no
|
||||
affect for later key matches. For example,
|
||||
<PRE><B>string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc</B></PRE>
|
||||
will return the string <B>01321221</B>.
|
||||
<P><DT><A NAME="M35"><B>string match</B> ?<B>-nocase</B>? <I>pattern</I> <I>string</I></A><DD>
|
||||
See if <I>pattern</I> matches <I>string</I>; return 1 if it does, 0
|
||||
if it doesn't.
|
||||
If <B>-nocase</B> is specified, then the pattern attempts to match
|
||||
against the string in a case insensitive manner.
|
||||
For the two strings to match, their contents
|
||||
must be identical except that the following special sequences
|
||||
may appear in <I>pattern</I>:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M36"><B>*</B></A><DD>
|
||||
Matches any sequence of characters in <I>string</I>,
|
||||
including a null string.
|
||||
<P><DT><A NAME="M37"><B>?</B></A><DD>
|
||||
Matches any single character in <I>string</I>.
|
||||
<P><DT><A NAME="M38"><B>[</B><I>chars</I><B>]</B></A><DD>
|
||||
Matches any character in the set given by <I>chars</I>. If a sequence
|
||||
of the form
|
||||
<I>x</I><B>-</B><I>y</I> appears in <I>chars</I>, then any character
|
||||
between <I>x</I> and <I>y</I>, inclusive, will match.
|
||||
When used with <B>-nocase</B>, the end points of the range are converted
|
||||
to lower case first. Whereas {[A-z]} matches '_' when matching
|
||||
case-sensitively ('_' falls between the 'Z' and 'a'), with <B>-nocase</B>
|
||||
this is considered like {[A-Za-z]} (and probably what was meant in the
|
||||
first place).
|
||||
<P><DT><A NAME="M39"><B>\</B><I>x</I></A><DD>
|
||||
Matches the single character <I>x</I>. This provides a way of
|
||||
avoiding the special interpretation of the characters
|
||||
<B>*?[]\</B> in <I>pattern</I>.
|
||||
<P></DL>
|
||||
<P><DT><A NAME="M40"><B>string range </B><I>string first last</I></A><DD>
|
||||
Returns a range of consecutive characters from <I>string</I>, starting
|
||||
with the character whose index is <I>first</I> and ending with the
|
||||
character whose index is <I>last</I>. An index of 0 refers to the
|
||||
first character of the string. <I>first</I> and <I>last</I> may be
|
||||
specified as for the <B>index</B> method.
|
||||
If <I>first</I> is less than zero then it is treated as if it were zero, and
|
||||
if <I>last</I> is greater than or equal to the length of the string then
|
||||
it is treated as if it were <B>end</B>. If <I>first</I> is greater than
|
||||
<I>last</I> then an empty string is returned.
|
||||
<P><DT><A NAME="M41"><B>string repeat </B><I>string count</I></A><DD>
|
||||
Returns <I>string</I> repeated <I>count</I> number of times.
|
||||
<P><DT><A NAME="M42"><B>string replace </B><I>string first last</I> ?<I>newstring</I>?</A><DD>
|
||||
Removes a range of consecutive characters from <I>string</I>, starting
|
||||
with the character whose index is <I>first</I> and ending with the
|
||||
character whose index is <I>last</I>. An index of 0 refers to the
|
||||
first character of the string. <I>First</I> and <I>last</I> may be
|
||||
specified as for the <B>index</B> method. If <I>newstring</I> is
|
||||
specified, then it is placed in the removed character range.
|
||||
If <I>first</I> is less than zero then it is treated as if it were zero, and
|
||||
if <I>last</I> is greater than or equal to the length of the string then
|
||||
it is treated as if it were <B>end</B>. If <I>first</I> is greater than
|
||||
<I>last</I> or the length of the initial string, or <I>last</I> is less
|
||||
than 0, then the initial string is returned untouched.
|
||||
<P><DT><A NAME="M43"><B>string tolower </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A><DD>
|
||||
Returns a value equal to <I>string</I> except that all upper (or title) case
|
||||
letters have been converted to lower case. If <I>first</I> is specified, it
|
||||
refers to the first char index in the string to start modifying. If
|
||||
<I>last</I> is specified, it refers to the char index in the string to stop
|
||||
at (inclusive). <I>first</I> and <I>last</I> may be
|
||||
specified as for the <B>index</B> method.
|
||||
<P><DT><A NAME="M44"><B>string totitle </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A><DD>
|
||||
Returns a value equal to <I>string</I> except that the first character
|
||||
in <I>string</I> is converted to its Unicode title case variant (or upper
|
||||
case if there is no title case variant) and the rest of the string is
|
||||
converted to lower case. If <I>first</I> is specified, it
|
||||
refers to the first char index in the string to start modifying. If
|
||||
<I>last</I> is specified, it refers to the char index in the string to stop
|
||||
at (inclusive). <I>first</I> and <I>last</I> may be
|
||||
specified as for the <B>index</B> method.
|
||||
<P><DT><A NAME="M45"><B>string toupper </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A><DD>
|
||||
Returns a value equal to <I>string</I> except that all lower (or title) case
|
||||
letters have been converted to upper case. If <I>first</I> is specified, it
|
||||
refers to the first char index in the string to start modifying. If
|
||||
<I>last</I> is specified, it refers to the char index in the string to stop
|
||||
at (inclusive). <I>first</I> and <I>last</I> may be specified as for the
|
||||
<B>index</B> method.
|
||||
<P><DT><A NAME="M46"><B>string trim </B><I>string</I> ?<I>chars</I>?</A><DD>
|
||||
Returns a value equal to <I>string</I> except that any leading
|
||||
or trailing characters from the set given by <I>chars</I> are
|
||||
removed.
|
||||
If <I>chars</I> is not specified then white space is removed
|
||||
(spaces, tabs, newlines, and carriage returns).
|
||||
<P><DT><A NAME="M47"><B>string trimleft </B><I>string</I> ?<I>chars</I>?</A><DD>
|
||||
Returns a value equal to <I>string</I> except that any
|
||||
leading characters from the set given by <I>chars</I> are
|
||||
removed.
|
||||
If <I>chars</I> is not specified then white space is removed
|
||||
(spaces, tabs, newlines, and carriage returns).
|
||||
<P><DT><A NAME="M48"><B>string trimright </B><I>string</I> ?<I>chars</I>?</A><DD>
|
||||
Returns a value equal to <I>string</I> except that any
|
||||
trailing characters from the set given by <I>chars</I> are
|
||||
removed.
|
||||
If <I>chars</I> is not specified then white space is removed
|
||||
(spaces, tabs, newlines, and carriage returns).
|
||||
<P><DT><A NAME="M49"><B>string wordend </B><I>string charIndex</I></A><DD>
|
||||
Returns the index of the character just after the last one in the word
|
||||
containing character <I>charIndex</I> of <I>string</I>. <I>charIndex</I>
|
||||
may be specified as for the <B>index</B> method. A word is
|
||||
considered to be any contiguous range of alphanumeric (Unicode letters
|
||||
or decimal digits) or underscore (Unicode connector punctuation)
|
||||
characters, or any single character other than these.
|
||||
<P><DT><A NAME="M50"><B>string wordstart </B><I>string charIndex</I></A><DD>
|
||||
Returns the index of the first character in the word containing
|
||||
character <I>charIndex</I> of <I>string</I>. <I>charIndex</I> may be
|
||||
specified as for the <B>index</B> method. A word is considered to be any
|
||||
contiguous range of alphanumeric (Unicode letters or decimal digits)
|
||||
or underscore (Unicode connector punctuation) characters, or any
|
||||
single character other than these.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M51">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/expr.htm">expr</A></B>, <B><A HREF="../TkCmd/list.htm">list</A></B>
|
||||
<H3><A NAME="M52">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#case conversion">case conversion</A>, <A href="../Keywords/C.htm#compare">compare</A>, <A href="../Keywords/I.htm#index">index</A>, <A href="../Keywords/M.htm#match">match</A>, <A href="../Keywords/P.htm#pattern">pattern</A>, <A href="../Keywords/S.htm#string">string</A>, <A href="../Keywords/W.htm#word">word</A>, <A href="../Keywords/E.htm#equal">equal</A>, <A href="../Keywords/C.htm#ctype">ctype</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
38
hlp/en/tcl/subst.htm
Normal file
38
hlp/en/tcl/subst.htm
Normal file
@@ -0,0 +1,38 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - subst manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
subst - Perform backslash, command, and variable substitutions
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>subst </B>?<B>-nobackslashes</B>? ?<B>-nocommands</B>? ?<B>-novariables</B>? <I>string</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command performs variable substitutions, command substitutions,
|
||||
and backslash substitutions on its <I>string</I> argument and
|
||||
returns the fully-substituted result.
|
||||
The substitutions are performed in exactly the same way as for
|
||||
Tcl commands.
|
||||
As a result, the <I>string</I> argument is actually substituted twice,
|
||||
once by the Tcl parser in the usual fashion for Tcl commands, and
|
||||
again by the <I>subst</I> command.
|
||||
<P>
|
||||
If any of the <B>-nobackslashes</B>, <B>-nocommands</B>, or
|
||||
<B>-novariables</B> are specified, then the corresponding substitutions
|
||||
are not performed.
|
||||
For example, if <B>-nocommands</B> is specified, no command substitution
|
||||
is performed: open and close brackets are treated as ordinary characters
|
||||
with no special interpretation.
|
||||
<P>
|
||||
Note: when it performs its substitutions, <I>subst</I> does not
|
||||
give any special treatment to double quotes or curly braces. For
|
||||
example, the script
|
||||
<PRE><B>set a 44
|
||||
subst {xyz {$a}}</B></PRE>
|
||||
returns ``<B>xyz {44}</B>'', not ``<B>xyz {$a}</B>''.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/eval.htm">eval</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#backslash substitution">backslash substitution</A>, <A href="../Keywords/C.htm#command substitution">command substitution</A>, <A href="../Keywords/V.htm#variable substitution">variable substitution</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
116
hlp/en/tcl/switch.htm
Normal file
116
hlp/en/tcl/switch.htm
Normal file
@@ -0,0 +1,116 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - switch manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="switch.htm#M2" NAME="L1160">NAME</A>
|
||||
<DL><DD>switch - Evaluate one of several scripts, depending on a given value</DL>
|
||||
<DD><A HREF="switch.htm#M3" NAME="L1161">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>switch </B>?<I>options</I>?<I> string pattern body </I>?<I>pattern body </I>...?
|
||||
<DD><B>switch </B>?<I>options</I>?<I> string </I>{<I>pattern body </I>?<I>pattern body </I>...?}
|
||||
</DL>
|
||||
<DD><A HREF="switch.htm#M4" NAME="L1162">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="switch.htm#M5" NAME="L1163"><B>-exact</B></A>
|
||||
<DD><A HREF="switch.htm#M6" NAME="L1164"><B>-glob</B></A>
|
||||
<DD><A HREF="switch.htm#M7" NAME="L1165"><B>-regexp</B></A>
|
||||
<DD><A HREF="switch.htm#M8" NAME="L1166"><B>- -</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="switch.htm#M9" NAME="L1167">SEE ALSO</A>
|
||||
<DD><A HREF="switch.htm#M10" NAME="L1168">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
switch - Evaluate one of several scripts, depending on a given value
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>switch </B>?<I>options</I>?<I> string pattern body </I>?<I>pattern body </I>...?<BR>
|
||||
<B>switch </B>?<I>options</I>?<I> string </I>{<I>pattern body </I>?<I>pattern body </I>...?}<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>switch</B> command matches its <I>string</I> argument against each of
|
||||
the <I>pattern</I> arguments in order.
|
||||
As soon as it finds a <I>pattern</I> that matches <I>string</I> it
|
||||
evaluates the following <I>body</I> argument by passing it recursively
|
||||
to the Tcl interpreter and returns the result of that evaluation.
|
||||
If the last <I>pattern</I> argument is <B>default</B> then it matches
|
||||
anything.
|
||||
If no <I>pattern</I> argument
|
||||
matches <I>string</I> and no default is given, then the <B>switch</B>
|
||||
command returns an empty string.
|
||||
<P>
|
||||
If the initial arguments to <B>switch</B> start with <B>-</B> then
|
||||
they are treated as options. The following options are
|
||||
currently supported:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>-exact</B></A><DD>
|
||||
Use exact matching when comparing <I>string</I> to a pattern. This
|
||||
is the default.
|
||||
<P><DT><A NAME="M6"><B>-glob</B></A><DD>
|
||||
When matching <I>string</I> to the patterns, use glob-style matching
|
||||
(i.e. the same as implemented by the <B><A HREF="../TkCmd/string.htm">string match</A></B> command).
|
||||
<P><DT><A NAME="M7"><B>-regexp</B></A><DD>
|
||||
When matching <I>string</I> to the patterns, use regular
|
||||
expression matching
|
||||
(as described in the <B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B> reference page).
|
||||
<P><DT><A NAME="M8"><B>- -</B></A><DD>
|
||||
Marks the end of options. The argument following this one will
|
||||
be treated as <I>string</I> even if it starts with a <B>-</B>.
|
||||
<P></DL>
|
||||
<P>
|
||||
Two syntaxes are provided for the <I>pattern</I> and <I>body</I> arguments.
|
||||
The first uses a separate argument for each of the patterns and commands;
|
||||
this form is convenient if substitutions are desired on some of the
|
||||
patterns or commands.
|
||||
The second form places all of the patterns and commands together into
|
||||
a single argument; the argument must have proper list structure, with
|
||||
the elements of the list being the patterns and commands.
|
||||
The second form makes it easy to construct multi-line switch commands,
|
||||
since the braces around the whole list make it unnecessary to include a
|
||||
backslash at the end of each line.
|
||||
Since the <I>pattern</I> arguments are in braces in the second form,
|
||||
no command or variable substitutions are performed on them; this makes
|
||||
the behavior of the second form different than the first form in some
|
||||
cases.
|
||||
<P>
|
||||
If a <I>body</I> is specified as ``<B>-</B>'' it means that the <I>body</I>
|
||||
for the next pattern should also be used as the body for this
|
||||
pattern (if the next pattern also has a body of ``<B>-</B>''
|
||||
then the body after that is used, and so on).
|
||||
This feature makes it possible to share a single <I>body</I> among
|
||||
several patterns.
|
||||
<P>
|
||||
Beware of how you place comments in <B>switch</B> commands. Comments
|
||||
should only be placed <B>inside</B> the execution body of one of the
|
||||
patterns, and not intermingled with the patterns.
|
||||
<P>
|
||||
Below are some examples of <B>switch</B> commands:
|
||||
<PRE><B>switch abc a - b {format 1} abc {format 2} default {format 3}</B></PRE>
|
||||
will return <B>2</B>,
|
||||
<PRE><B>switch -regexp aaab {
|
||||
^a.*b$ -
|
||||
b {format 1}
|
||||
a* {format 2}
|
||||
default {format 3}
|
||||
}</B></PRE>
|
||||
will return <B>1</B>, and
|
||||
<PRE><B>switch xyz {
|
||||
a
|
||||
-
|
||||
b
|
||||
{
|
||||
# Correct Comment Placement
|
||||
format 1
|
||||
}
|
||||
a*
|
||||
{format 2}
|
||||
default
|
||||
{format 3}
|
||||
}</B></PRE>
|
||||
will return <B>3</B>.
|
||||
|
||||
<H3><A NAME="M9">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/for.htm">for</A></B>, <B><A HREF="../TkCmd/if.htm">if</A></B>, <B><A HREF="../TkCmd/regexp.htm">regexp</A></B>
|
||||
<H3><A NAME="M10">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/S.htm#switch">switch</A>, <A href="../Keywords/M.htm#match">match</A>, <A href="../Keywords/R.htm#regular expression">regular expression</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
110
hlp/en/tcl/tcl.toc.html
Normal file
110
hlp/en/tcl/tcl.toc.html
Normal file
@@ -0,0 +1,110 @@
|
||||
<TITLE>Tk Commands</TITLE>
|
||||
<a href="http.htm">Http</a><br>
|
||||
<a href="continue.htm">continue</a><br>
|
||||
<a href="history.htm">history</a><br>
|
||||
<a href="pid.htm">pid</a><br>
|
||||
<a href="switch.htm">switch</a><br>
|
||||
<a href="safe.htm">Safe Base</a><br>
|
||||
<a href="dde.htm">dde</a><br>
|
||||
<a href="if.htm">if</a><br>
|
||||
<a href="packagens.htm">pkg::create</a><br>
|
||||
<a href="library.htm">tcl_endOfWord</a><br>
|
||||
<a href="Tcl.htm">Tcl</a><br>
|
||||
<a href="encoding.htm">encoding</a><br>
|
||||
<a href="incr.htm">incr</a><br>
|
||||
<a href="pkgMkIndex.htm">pkg_mkIndex</a><br>
|
||||
<a href="library.htm">tcl_findLibrary</a><br>
|
||||
<a href="tcltest.htm">Tcltest</a><br>
|
||||
<a href="eof.htm">eof</a><br>
|
||||
<a href="info.htm">info</a><br>
|
||||
<a href="proc.htm">proc</a><br>
|
||||
<a href="library.htm">tcl_startOfNextWord</a><br>
|
||||
<a href="after.htm">after</a><br>
|
||||
<a href="error.htm">error</a><br>
|
||||
<a href="interp.htm">interp</a><br>
|
||||
<a href="puts.htm">puts</a><br>
|
||||
<a href="library.htm">tcl_startOfPreviousWord</a><br>
|
||||
<a href="append.htm">append</a><br>
|
||||
<a href="eval.htm">eval</a><br>
|
||||
<a href="join.htm">join</a><br>
|
||||
<a href="pwd.htm">pwd</a><br>
|
||||
<a href="library.htm">tcl_wordBreakAfter</a><br>
|
||||
<a href="array.htm">array</a><br>
|
||||
<a href="exec.htm">exec</a><br>
|
||||
<a href="lappend.htm">lappend</a><br>
|
||||
<a href="re_syntax.htm">re_syntax</a><br>
|
||||
<a href="library.htm">tcl_wordBreakBefore</a><br>
|
||||
<a href="library.htm">auto_execok</a><br>
|
||||
<a href="exit.htm">exit</a><br>
|
||||
<a href="lindex.htm">lindex</a><br>
|
||||
<a href="read.htm">read</a><br>
|
||||
<a href="tclvars.htm">tclvars</a><br>
|
||||
<a href="library.htm">auto_import</a><br>
|
||||
<a href="expr.htm">expr</a><br>
|
||||
<a href="linsert.htm">linsert</a><br>
|
||||
<a href="regexp.htm">regexp</a><br>
|
||||
<a href="tell.htm">tell</a><br>
|
||||
<a href="library.htm">auto_load</a><br>
|
||||
<a href="fblocked.htm">fblocked</a><br>
|
||||
<a href="list.htm">list</a><br>
|
||||
<a href="registry.htm">registry</a><br>
|
||||
<a href="time.htm">time</a><br>
|
||||
<a href="library.htm">auto_mkindex</a><br>
|
||||
<a href="fconfigure.htm">fconfigure</a><br>
|
||||
<a href="llength.htm">llength</a><br>
|
||||
<a href="regsub.htm">regsub</a><br>
|
||||
<a href="trace.htm">trace</a><br>
|
||||
<a href="library.htm">auto_mkindex_old</a><br>
|
||||
<a href="fcopy.htm">fcopy</a><br>
|
||||
<a href="load.htm">load</a><br>
|
||||
<a href="rename.htm">rename</a><br>
|
||||
<a href="unknown.htm">unknown</a><br>
|
||||
<a href="library.htm">auto_qualify</a><br>
|
||||
<a href="file.htm">file</a><br>
|
||||
<a href="lrange.htm">lrange</a><br>
|
||||
<a href="resource.htm">resource</a><br>
|
||||
<a href="unset.htm">unset</a><br>
|
||||
<a href="library.htm">auto_reset</a><br>
|
||||
<a href="fileevent.htm">fileevent</a><br>
|
||||
<a href="lreplace.htm">lreplace</a><br>
|
||||
<a href="return.htm">return</a><br>
|
||||
<a href="update.htm">update</a><br>
|
||||
<a href="bgerror.htm">bgerror</a><br>
|
||||
<a href="filename.htm">filename</a><br>
|
||||
<a href="lsearch.htm">lsearch</a><br>
|
||||
<a href="scan.htm">scan</a><br>
|
||||
<a href="uplevel.htm">uplevel</a><br>
|
||||
<a href="binary.htm">binary</a><br>
|
||||
<a href="flush.htm">flush</a><br>
|
||||
<a href="lsort.htm">lsort</a><br>
|
||||
<a href="seek.htm">seek</a><br>
|
||||
<a href="upvar.htm">upvar</a><br>
|
||||
<a href="break.htm">break</a><br>
|
||||
<a href="for.htm">for</a><br>
|
||||
<a href="memory.htm">memory</a><br>
|
||||
<a href="set.htm">set</a><br>
|
||||
<a href="variable.htm">variable</a><br>
|
||||
<a href="catch.htm">catch</a><br>
|
||||
<a href="foreach.htm">foreach</a><br>
|
||||
<a href="msgcat.htm">msgcat</a><br>
|
||||
<a href="socket.htm">socket</a><br>
|
||||
<a href="vwait.htm">vwait</a><br>
|
||||
<a href="cd.htm">cd</a><br>
|
||||
<a href="format.htm">format</a><br>
|
||||
<a href="namespace.htm">namespace</a><br>
|
||||
<a href="source.htm">source</a><br>
|
||||
<a href="while.htm">while</a><br>
|
||||
<a href="clock.htm">clock</a><br>
|
||||
<a href="gets.htm">gets</a><br>
|
||||
<a href="open.htm">open</a><br>
|
||||
<a href="split.htm">split</a><br>
|
||||
<a href="close.htm">close</a><br>
|
||||
<a href="glob.htm">glob</a><br>
|
||||
<a href="package.htm">package</a><br>
|
||||
<a href="string.htm">string</a><br>
|
||||
<a href="concat.htm">concat</a><br>
|
||||
<a href="global.htm">global</a><br>
|
||||
<a href="library.htm">parray</a><br>
|
||||
<a href="subst.htm">subst</a><br>
|
||||
|
||||
|
||||
126
hlp/en/tcl/tclsh.htm
Normal file
126
hlp/en/tcl/tclsh.htm
Normal file
@@ -0,0 +1,126 @@
|
||||
<HTML><HEAD><TITLE>Applications - tclsh manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="tclsh.htm#M2" NAME="L2">NAME</A>
|
||||
<DL><DD>tclsh - Simple shell containing Tcl interpreter</DL>
|
||||
<DD><A HREF="tclsh.htm#M3" NAME="L3">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>tclsh</B> ?<I>fileName arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="tclsh.htm#M4" NAME="L4">DESCRIPTION</A>
|
||||
<DD><A HREF="tclsh.htm#M5" NAME="L5">SCRIPT FILES</A>
|
||||
<DD><A HREF="tclsh.htm#M6" NAME="L6">VARIABLES</A>
|
||||
<DL>
|
||||
<DD><A HREF="tclsh.htm#M7" NAME="L7"><B>argc</B></A>
|
||||
<DD><A HREF="tclsh.htm#M8" NAME="L8"><B>argv</B></A>
|
||||
<DD><A HREF="tclsh.htm#M9" NAME="L9"><B>argv0</B></A>
|
||||
<DD><A HREF="tclsh.htm#M10" NAME="L10"><B>tcl_interactive</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="tclsh.htm#M11" NAME="L11">PROMPTS</A>
|
||||
<DD><A HREF="tclsh.htm#M12" NAME="L12">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
tclsh - Simple shell containing Tcl interpreter
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>tclsh</B> ?<I>fileName arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
<B>Tclsh</B> is a shell-like application that reads Tcl commands
|
||||
from its standard input or from a file and evaluates them.
|
||||
If invoked with no arguments then it runs interactively, reading
|
||||
Tcl commands from standard input and printing command results and
|
||||
error messages to standard output.
|
||||
It runs until the <B><A HREF="../TkCmd/exit.htm">exit</A></B> command is invoked or until it
|
||||
reaches end-of-file on its standard input.
|
||||
If there exists a file <B>.tclshrc</B> (or <B>tclshrc.tcl</B> on
|
||||
the Windows platforms) in the home directory of
|
||||
the user, <B>tclsh</B> evaluates the file as a Tcl script
|
||||
just before reading the first command from standard input.
|
||||
|
||||
<H3><A NAME="M5">SCRIPT FILES</A></H3>
|
||||
If <B>tclsh</B> is invoked with arguments then the first argument
|
||||
is the name of a script file and any additional arguments
|
||||
are made available to the script as variables (see below).
|
||||
Instead of reading commands from standard input <B>tclsh</B> will
|
||||
read Tcl commands from the named file; <B>tclsh</B> will exit
|
||||
when it reaches the end of the file.
|
||||
There is no automatic evaluation of <B>.tclshrc</B> in this
|
||||
case, but the script file can always <B><A HREF="../TkCmd/source.htm">source</A></B> it if desired.
|
||||
<P>
|
||||
If you create a Tcl script in a file whose first line is
|
||||
<PRE><B>#!/usr/local/bin/tclsh</B></PRE>
|
||||
then you can invoke the script file directly from your shell if
|
||||
you mark the file as executable.
|
||||
This assumes that <B>tclsh</B> has been installed in the default
|
||||
location in /usr/local/bin; if it's installed somewhere else
|
||||
then you'll have to modify the above line to match.
|
||||
Many UNIX systems do not allow the <B>#!</B> line to exceed about
|
||||
30 characters in length, so be sure that the <B>tclsh</B>
|
||||
executable can be accessed with a short file name.
|
||||
<P>
|
||||
An even better approach is to start your script files with the
|
||||
following three lines:
|
||||
<PRE><B>#!/bin/sh
|
||||
# the next line restarts using tclsh \
|
||||
exec tclsh "$0" "$@"</B></PRE>
|
||||
This approach has three advantages over the approach in the previous
|
||||
paragraph. First, the location of the <B>tclsh</B> binary doesn't have
|
||||
to be hard-wired into the script: it can be anywhere in your shell
|
||||
search path. Second, it gets around the 30-character file name limit
|
||||
in the previous approach.
|
||||
Third, this approach will work even if <B>tclsh</B> is
|
||||
itself a shell script (this is done on some systems in order to
|
||||
handle multiple architectures or operating systems: the <B>tclsh</B>
|
||||
script selects one of several binaries to run). The three lines
|
||||
cause both <B>sh</B> and <B>tclsh</B> to process the script, but the
|
||||
<B><A HREF="../TkCmd/exec.htm">exec</A></B> is only executed by <B>sh</B>.
|
||||
<B>sh</B> processes the script first; it treats the second
|
||||
line as a comment and executes the third line.
|
||||
The <B><A HREF="../TkCmd/exec.htm">exec</A></B> statement cause the shell to stop processing and
|
||||
instead to start up <B>tclsh</B> to reprocess the entire script.
|
||||
When <B>tclsh</B> starts up, it treats all three lines as comments,
|
||||
since the backslash at the end of the second line causes the third
|
||||
line to be treated as part of the comment on the second line.
|
||||
<P>
|
||||
You should note that it is also common practise to install tclsh with
|
||||
its version number as part of the name. This has the advantage of
|
||||
allowing multiple versions of Tcl to exist on the same system at once,
|
||||
but also the disadvantage of making it harder to write scripts that
|
||||
start up uniformly across different versions of Tcl.
|
||||
|
||||
<H3><A NAME="M6">VARIABLES</A></H3>
|
||||
<B>Tclsh</B> sets the following Tcl variables:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M7"><B>argc</B></A><DD>
|
||||
Contains a count of the number of <I>arg</I> arguments (0 if none),
|
||||
not including the name of the script file.
|
||||
<P><DT><A NAME="M8"><B>argv</B></A><DD>
|
||||
Contains a Tcl list whose elements are the <I>arg</I> arguments,
|
||||
in order, or an empty string if there are no <I>arg</I> arguments.
|
||||
<P><DT><A NAME="M9"><B>argv0</B></A><DD>
|
||||
Contains <I>fileName</I> if it was specified.
|
||||
Otherwise, contains the name by which <B>tclsh</B> was invoked.
|
||||
<P><DT><A NAME="M10"><B>tcl_interactive</B></A><DD>
|
||||
Contains 1 if <B>tclsh</B> is running interactively (no
|
||||
<I>fileName</I> was specified and standard input is a terminal-like
|
||||
device), 0 otherwise.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M11">PROMPTS</A></H3>
|
||||
When <B>tclsh</B> is invoked interactively it normally prompts for each
|
||||
command with ``<B>% </B>''. You can change the prompt by setting the
|
||||
variables <B>tcl_prompt1</B> and <B>tcl_prompt2</B>. If variable
|
||||
<B>tcl_prompt1</B> exists then it must consist of a Tcl script
|
||||
to output a prompt; instead of outputting a prompt <B>tclsh</B>
|
||||
will evaluate the script in <B>tcl_prompt1</B>.
|
||||
The variable <B>tcl_prompt2</B> is used in a similar way when
|
||||
a newline is typed but the current command isn't yet complete;
|
||||
if <B>tcl_prompt2</B> isn't set then no prompt is output for
|
||||
incomplete commands.
|
||||
|
||||
<H3><A NAME="M12">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#argument">argument</A>, <A href="../Keywords/I.htm#interpreter">interpreter</A>, <A href="../Keywords/P.htm#prompt">prompt</A>, <A href="../Keywords/S.htm#script file">script file</A>, <A href="../Keywords/S.htm#shell">shell</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
776
hlp/en/tcl/tcltest.htm
Normal file
776
hlp/en/tcl/tcltest.htm
Normal file
@@ -0,0 +1,776 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - Tcltest manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="tcltest.htm#M2" NAME="L1169">NAME</A>
|
||||
<DL><DD>Tcltest - Test harness support code and utilities</DL>
|
||||
<DD><A HREF="tcltest.htm#M3" NAME="L1170">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>package require tcltest ?1.0?</B>
|
||||
<DD><B>::tcltest::test </B><I>name desc ?constraint? script expectedAnswer</I>
|
||||
<DD><B>::tcltest::cleanupTests </B><I>?runningMultipleTests?</I>
|
||||
<DD><B>::tcltest::getMatchingTestFiles</B>
|
||||
<DD><B>::tcltest::loadTestedCommands</B>
|
||||
<DD><B>::tcltest::makeFile </B><I>contents name</I>
|
||||
<DD><B>::tcltest::removeFile </B><I>name</I>
|
||||
<DD><B>::tcltest::makeDirectory </B><I>name</I>
|
||||
<DD><B>::tcltest::removeDirectory </B><I>name</I>
|
||||
<DD><B>::tcltest::viewFile </B><I>name</I>
|
||||
<DD><B>::tcltest::normalizeMsg </B><I>msg</I>
|
||||
<DD><B>::tcltest::bytestring </B><I>string</I>
|
||||
<DD><B>::tcltest::saveState</B>
|
||||
<DD><B>::tcltest::restoreState</B>
|
||||
<DD><B>::tcltest::threadReap</B>
|
||||
</DL>
|
||||
<DD><A HREF="tcltest.htm#M4" NAME="L1171">DESCRIPTION</A>
|
||||
<DD><A HREF="tcltest.htm#M5" NAME="L1172">COMMANDS</A>
|
||||
<DL>
|
||||
<DD><A HREF="tcltest.htm#M6" NAME="L1173"><B>::tcltest::test</B> <I>name desc ?constraints? script expectedAnswer</I></A>
|
||||
<DD><A HREF="tcltest.htm#M7" NAME="L1174"><B>::tcltest::cleanupTests</B> <I>?runningMultipleTests?</I></A>
|
||||
<DD><A HREF="tcltest.htm#M8" NAME="L1175"><B>::tcltest::getMatchingTestFiles</B></A>
|
||||
<DD><A HREF="tcltest.htm#M9" NAME="L1176"><B>::tcltest::loadTestedCommands</B></A>
|
||||
<DD><A HREF="tcltest.htm#M10" NAME="L1177"><B>::tcltest::makeFile</B> <I>contents name</I></A>
|
||||
<DD><A HREF="tcltest.htm#M11" NAME="L1178"><B>::tcltest::removeFile</B> <I>name</I></A>
|
||||
<DD><A HREF="tcltest.htm#M12" NAME="L1179"><B>::tcltest::makeDirectory</B> <I>name</I></A>
|
||||
<DD><A HREF="tcltest.htm#M13" NAME="L1180"><B>::tcltest::removeDirectory</B> <I>name</I></A>
|
||||
<DD><A HREF="tcltest.htm#M14" NAME="L1181"><B>::tcltest::viewFile</B> <I>file</I></A>
|
||||
<DD><A HREF="tcltest.htm#M15" NAME="L1182"><B>::tcltest::normalizeMsg</B> <I>msg</I></A>
|
||||
<DD><A HREF="tcltest.htm#M16" NAME="L1183"><B>::tcltest::bytestring</B> <I>string</I></A>
|
||||
<DD><A HREF="tcltest.htm#M17" NAME="L1184"><B>::tcltest::saveState</B></A>
|
||||
<DD><A HREF="tcltest.htm#M18" NAME="L1185"><B>::tcltest::threadReap</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="tcltest.htm#M19" NAME="L1186">TESTS</A>
|
||||
<DD><A HREF="tcltest.htm#M20" NAME="L1187">TCLTEST NAMEPSACE VARIABLES</A>
|
||||
<DL>
|
||||
<DD><A HREF="tcltest.htm#M21" NAME="L1188"><B>::tcltest::outputChannel</B></A>
|
||||
<DD><A HREF="tcltest.htm#M22" NAME="L1189"><B>::tcltest::errorChannel</B></A>
|
||||
<DD><A HREF="tcltest.htm#M23" NAME="L1190"><B>::tcltest::mainThread</B></A>
|
||||
<DD><A HREF="tcltest.htm#M24" NAME="L1191"><B>::tcltest::originalEnv</B></A>
|
||||
<DD><A HREF="tcltest.htm#M25" NAME="L1192"><B>::tcltest::workingDirectory</B></A>
|
||||
<DD><A HREF="tcltest.htm#M26" NAME="L1193"><B>::tcltest::temporaryDirectory</B></A>
|
||||
<DD><A HREF="tcltest.htm#M27" NAME="L1194"><B>::tcltest::testsDirectory</B></A>
|
||||
<DD><A HREF="tcltest.htm#M28" NAME="L1195"><B>::tcltest::tcltest</B></A>
|
||||
<DD><A HREF="tcltest.htm#M29" NAME="L1196"><B>::tcltest::loadScript</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="tcltest.htm#M30" NAME="L1197">TEST CONSTRAINTS</A>
|
||||
<DL>
|
||||
<DD><A HREF="tcltest.htm#M31" NAME="L1198"><I>unix</I></A>
|
||||
<DD><A HREF="tcltest.htm#M32" NAME="L1199"><I>pc</I></A>
|
||||
<DD><A HREF="tcltest.htm#M33" NAME="L1200"><I>nt</I></A>
|
||||
<DD><A HREF="tcltest.htm#M34" NAME="L1201"><I>95</I></A>
|
||||
<DD><A HREF="tcltest.htm#M35" NAME="L1202"><I>98</I></A>
|
||||
<DD><A HREF="tcltest.htm#M36" NAME="L1203"><I>mac</I></A>
|
||||
<DD><A HREF="tcltest.htm#M37" NAME="L1204"><I>unixOrPc</I></A>
|
||||
<DD><A HREF="tcltest.htm#M38" NAME="L1205"><I>macOrPc</I></A>
|
||||
<DD><A HREF="tcltest.htm#M39" NAME="L1206"><I>macOrUnix</I></A>
|
||||
<DD><A HREF="tcltest.htm#M40" NAME="L1207"><I>tempNotPc</I></A>
|
||||
<DD><A HREF="tcltest.htm#M41" NAME="L1208"><I>tempNotMac</I></A>
|
||||
<DD><A HREF="tcltest.htm#M42" NAME="L1209"><I>unixCrash</I></A>
|
||||
<DD><A HREF="tcltest.htm#M43" NAME="L1210"><I>pcCrash</I></A>
|
||||
<DD><A HREF="tcltest.htm#M44" NAME="L1211"><I>macCrash</I></A>
|
||||
<DD><A HREF="tcltest.htm#M45" NAME="L1212"><I>emptyTest</I></A>
|
||||
<DD><A HREF="tcltest.htm#M46" NAME="L1213"><I>knownBug</I></A>
|
||||
<DD><A HREF="tcltest.htm#M47" NAME="L1214"><I>nonPortable</I></A>
|
||||
<DD><A HREF="tcltest.htm#M48" NAME="L1215"><I>userInteraction</I></A>
|
||||
<DD><A HREF="tcltest.htm#M49" NAME="L1216"><I>interactive</I></A>
|
||||
<DD><A HREF="tcltest.htm#M50" NAME="L1217"><I>nonBlockFiles</I></A>
|
||||
<DD><A HREF="tcltest.htm#M51" NAME="L1218"><I>asyncPipeClose</I></A>
|
||||
<DD><A HREF="tcltest.htm#M52" NAME="L1219"><I>unixExecs</I></A>
|
||||
<DD><A HREF="tcltest.htm#M53" NAME="L1220"><I>hasIsoLocale</I></A>
|
||||
<DD><A HREF="tcltest.htm#M54" NAME="L1221"><I>root</I></A>
|
||||
<DD><A HREF="tcltest.htm#M55" NAME="L1222"><I>notRoot</I></A>
|
||||
<DD><A HREF="tcltest.htm#M56" NAME="L1223"><I>eformat</I></A>
|
||||
<DD><A HREF="tcltest.htm#M57" NAME="L1224"><I>stdio</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="tcltest.htm#M58" NAME="L1225">RUNNING TEST FILES</A>
|
||||
<DL>
|
||||
<DD><A HREF="tcltest.htm#M59" NAME="L1226"><B>-help</B></A>
|
||||
<DD><A HREF="tcltest.htm#M60" NAME="L1227"><B>-verbose <level></B></A>
|
||||
<DD><A HREF="tcltest.htm#M61" NAME="L1228"><B>-match <matchList></B></A>
|
||||
<DD><A HREF="tcltest.htm#M62" NAME="L1229"><B>-skip <skipList></B></A>
|
||||
<DD><A HREF="tcltest.htm#M63" NAME="L1230"><B>-file <globPatternList></B></A>
|
||||
<DD><A HREF="tcltest.htm#M64" NAME="L1231"><B>-notfile <globPatternList></B></A>
|
||||
<DD><A HREF="tcltest.htm#M65" NAME="L1232"><B>-constraints <list></B></A>
|
||||
<DD><A HREF="tcltest.htm#M66" NAME="L1233"><B>-limitconstraints <bool></B></A>
|
||||
<DD><A HREF="tcltest.htm#M67" NAME="L1234"><B>-load <script></B></A>
|
||||
<DD><A HREF="tcltest.htm#M68" NAME="L1235"><B>-loadfile <scriptfile></B></A>
|
||||
<DD><A HREF="tcltest.htm#M69" NAME="L1236"><B>-tmpdir <directoryName></B></A>
|
||||
<DD><A HREF="tcltest.htm#M70" NAME="L1237"><B>-testdir <directoryName></B></A>
|
||||
<DD><A HREF="tcltest.htm#M71" NAME="L1238"><B>-preservecore <level></B></A>
|
||||
<DL>
|
||||
<DD><A HREF="tcltest.htm#M72" NAME="L1239">0</A>
|
||||
<DD><A HREF="tcltest.htm#M73" NAME="L1240">1</A>
|
||||
<DD><A HREF="tcltest.htm#M74" NAME="L1241">2</A>
|
||||
</DL>
|
||||
<DD><A HREF="tcltest.htm#M75" NAME="L1242"><B>-debug <debugLevel></B></A>
|
||||
<DL>
|
||||
<DD><A HREF="tcltest.htm#M76" NAME="L1243">0</A>
|
||||
<DD><A HREF="tcltest.htm#M77" NAME="L1244">1</A>
|
||||
<DD><A HREF="tcltest.htm#M78" NAME="L1245">2</A>
|
||||
<DD><A HREF="tcltest.htm#M79" NAME="L1246">3</A>
|
||||
</DL>
|
||||
<DD><A HREF="tcltest.htm#M80" NAME="L1247"><B>-outfile <filename></B></A>
|
||||
<DD><A HREF="tcltest.htm#M81" NAME="L1248"><B>-errfile <filename></B></A>
|
||||
</DL>
|
||||
<DD><A HREF="tcltest.htm#M82" NAME="L1249">TEST OUTPUT</A>
|
||||
<DD><A HREF="tcltest.htm#M83" NAME="L1250">CONTENTS OF A TEST FILE</A>
|
||||
<DD><A HREF="tcltest.htm#M84" NAME="L1251">SELECTING TESTS FOR EXECUTION WITHIN A FILE</A>
|
||||
<DL>
|
||||
</DL>
|
||||
<DD><A HREF="tcltest.htm#M85" NAME="L1252">HOW TO CUSTOMIZE THE TEST HARNESS</A>
|
||||
<DL>
|
||||
<DD><A HREF="tcltest.htm#M86" NAME="L1253"><B>::tcltest::PrintUsageInfoHook</B></A>
|
||||
<DD><A HREF="tcltest.htm#M87" NAME="L1254"><B>::tcltest::processCmdLineArgsFlagHook</B></A>
|
||||
<DD><A HREF="tcltest.htm#M88" NAME="L1255"><B>::tcltest::processCmdLineArgsHook</B> <I>flags</I></A>
|
||||
<DD><A HREF="tcltest.htm#M89" NAME="L1256"><B>::tcltest::initConstraintsHook</B></A>
|
||||
<DD><A HREF="tcltest.htm#M90" NAME="L1257"><B>::tcltest::cleanupTestsHook</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="tcltest.htm#M91" NAME="L1258">EXAMPLES</A>
|
||||
<DL>
|
||||
</DL>
|
||||
<DD><A HREF="tcltest.htm#M92" NAME="L1259">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
Tcltest - Test harness support code and utilities
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>package require tcltest ?1.0?</B><BR>
|
||||
<B>::tcltest::test </B><I>name desc ?constraint? script expectedAnswer</I><BR>
|
||||
<B>::tcltest::cleanupTests </B><I>?runningMultipleTests?</I><BR>
|
||||
<B>::tcltest::getMatchingTestFiles</B><BR>
|
||||
<B>::tcltest::loadTestedCommands</B><BR>
|
||||
<B>::tcltest::makeFile </B><I>contents name</I><BR>
|
||||
<B>::tcltest::removeFile </B><I>name</I><BR>
|
||||
<B>::tcltest::makeDirectory </B><I>name</I><BR>
|
||||
<B>::tcltest::removeDirectory </B><I>name</I><BR>
|
||||
<B>::tcltest::viewFile </B><I>name</I><BR>
|
||||
<B>::tcltest::normalizeMsg </B><I>msg</I><BR>
|
||||
<B>::tcltest::bytestring </B><I>string</I><BR>
|
||||
<B>::tcltest::saveState</B><BR>
|
||||
<B>::tcltest::restoreState</B><BR>
|
||||
<B>::tcltest::threadReap</B><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>tcltest</B> package provides the user with utility tools for
|
||||
writing and running tests in the Tcl test suite. It can also be used
|
||||
to create a customized test harness for an extension.
|
||||
<P>
|
||||
The Tcl test suite consists of multiple .test files, each of which
|
||||
contains multiple test cases. Each test case consists of a call to
|
||||
the test command, which specifies the name of test, a short
|
||||
description, any constraints that apply to the test case, the script
|
||||
to be run, and expected results. See the sections <I>"Tests,"</I>
|
||||
<I>"Test Constraints,"</I> and <I>"Test Files and How to Run Them"</I>
|
||||
for more details.
|
||||
<P>
|
||||
It is also possible to add to this test harness to create your own
|
||||
customized test harness implementation. For more defails, see the
|
||||
section <I>"How to Customize the Test Harness"</I>.
|
||||
<P>
|
||||
This approach to testing was designed and initially implemented by
|
||||
Mary Ann May-Pumphrey of Sun Microsystems in the early 1990's. Many
|
||||
thanks to her for donating her work back to the public Tcl release.
|
||||
<H3><A NAME="M5">COMMANDS</A></H3>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>::tcltest::test</B> <I>name desc ?constraints? script expectedAnswer</I></A><DD>
|
||||
The <B>::tcltest::test</B> command runs<I>script</I> and compares
|
||||
its result to <I>expectedAnswer</I>. It prints an error message if the two do
|
||||
not match. If <B>::tcltest::verbose</B> contains "p" or "s", it also prints
|
||||
out a message if the test passed or was skipped. The test will be
|
||||
skipped if it doesn't match the <B>::tcltest::match</B> variable, if it
|
||||
matches an element in <B>::tcltest::skip</B>, or if one of the elements
|
||||
of <I>constraint</I> turns out not to be true. The
|
||||
<B>::tcltest::test</B> command has no defined return values. See the
|
||||
<I>"Writing a new test"</I> section for more details on this command.
|
||||
<P><DT><A NAME="M7"><B>::tcltest::cleanupTests</B> <I>?runningMultipleTests?</I></A><DD>
|
||||
This command should be called at the end of a test file. It prints
|
||||
statistics about the tests run and removes files that were created by
|
||||
<B>::tcltest::makeDirectory</B> and <B>::tcltest::makeFile</B>. Names
|
||||
of files and directories created outside of
|
||||
<B>::tcltest::makeFile</B> and <B>::tcltest::makeDirectory</B> and
|
||||
never deleted are printed to <B>::tcltest::outputChannel</B>. This command
|
||||
also restores the original shell environment, as described by the ::env
|
||||
array. <I>calledFromAll</I> should be specified when
|
||||
<B>::tcltest::cleanupTests</B> is called from an "all.tcl" file. Tcl files
|
||||
files are generally used to run multiple tests. For more details on how to
|
||||
run multiple tests, please see the section <I>"Running test files"</I>.
|
||||
This proc has no defined return value.
|
||||
<P><DT><A NAME="M8"><B>::tcltest::getMatchingTestFiles</B></A><DD>
|
||||
This command is used when you want to run multiple test files. It returns
|
||||
the list of tests that should be sourced in an 'all.tcl' file. See the
|
||||
section <I>"Running test files"</I> for more information.
|
||||
<P><DT><A NAME="M9"><B>::tcltest::loadTestedCommands</B></A><DD>
|
||||
This command uses the script specified via the <I>-load</I> or
|
||||
<I>-loadfile</I> to load the commands checked by the test suite.
|
||||
Allowed to be empty, as the tested commands could have been compiled
|
||||
into the interpreter running the test suite.
|
||||
<P><DT><A NAME="M10"><B>::tcltest::makeFile</B> <I>contents name</I></A><DD>
|
||||
Create a file that will be automatically be removed by
|
||||
<B>::tcltest::cleanupTests</B> at the end of a test file.
|
||||
This proc has no defined return value.
|
||||
<P><DT><A NAME="M11"><B>::tcltest::removeFile</B> <I>name</I></A><DD>
|
||||
Force the file referenced by <I>name</I> to be removed. This file name
|
||||
should be relative to <I>::tcltest::temporaryDirectory</I>. This proc has no
|
||||
defined return values.
|
||||
<P><DT><A NAME="M12"><B>::tcltest::makeDirectory</B> <I>name</I></A><DD>
|
||||
Create a directory named <I>name</I> that will automatically be removed
|
||||
by <B>::tcltest::cleanupTests</B> at the end of a test file. This proc
|
||||
has no defined return value.
|
||||
<P><DT><A NAME="M13"><B>::tcltest::removeDirectory</B> <I>name</I></A><DD>
|
||||
Force the directory referenced by <I>name</I> to be removed. This proc
|
||||
has no defined return value.
|
||||
<P><DT><A NAME="M14"><B>::tcltest::viewFile</B> <I>file</I></A><DD>
|
||||
Returns the contents of <I>file</I>.
|
||||
<P><DT><A NAME="M15"><B>::tcltest::normalizeMsg</B> <I>msg</I></A><DD>
|
||||
Remove extra newlines from <I>msg</I>.
|
||||
<P><DT><A NAME="M16"><B>::tcltest::bytestring</B> <I>string</I></A><DD>
|
||||
Construct a string that consists of the requested sequence of bytes,
|
||||
as opposed to a string of properly formed UTF-8 characters using the
|
||||
value supplied in <I>string</I>. This allows the tester to create
|
||||
denormalized or improperly formed strings to pass to C procedures that
|
||||
are supposed to accept strings with embedded NULL types and confirm
|
||||
that a string result has a certain pattern of bytes.
|
||||
<P><DT><A NAME="M17"><B>::tcltest::saveState</B></A><DD>
|
||||
<B>::tcltest::restoreState</B>
|
||||
Save and restore the procedure and global variable names.
|
||||
A test file might contain calls to <B>::tcltest::saveState</B> and
|
||||
<B>::tcltest:restoreState</B> if it creates or deletes global variables
|
||||
or procs.
|
||||
<P><DT><A NAME="M18"><B>::tcltest::threadReap</B></A><DD>
|
||||
<B>::tcltest::threadReap</B> only works if <I>testthread</I> is
|
||||
defined, generally by compiling tcltest. If <I>testthread</I> is
|
||||
defined, <B>::tcltest::threadReap</B> kills all threads except for the
|
||||
main thread. It gets the ID of the main thread by calling
|
||||
<I>testthread names</I> during initialization. This value is stored in
|
||||
<I>::tcltest::mainThread</I>. <B>::tcltest::threadReap</B> returns the
|
||||
number of existing threads at completion.
|
||||
<P></DL>
|
||||
<H3><A NAME="M19">TESTS</A></H3>
|
||||
The <B>test</B> procedure runs a test script and prints an error
|
||||
message if the script's result does not match the expected result.
|
||||
The following is the spec for the <B>test</B> command:
|
||||
<PRE>test <name> <description> ?<constraint>? <script> <expectedAnswer></PRE>
|
||||
The <name> argument should follow the pattern:
|
||||
<PRE><target>-<majorNum>.<minorNum></PRE>
|
||||
For white-box (regression) tests, the target should be the name of the
|
||||
C function or Tcl procedure being tested. For black-box tests, the
|
||||
target should be the name of the feature being tested. Related tests
|
||||
should share a major number.
|
||||
<P>
|
||||
The <description> argument is a short textual description of the test,
|
||||
to help humans understand what it tests. The name of a Tcl or C
|
||||
function being tested should be included for regression tests. If the
|
||||
test case exists to reproduce a bug, include the bug ID in the
|
||||
description.
|
||||
<P>
|
||||
The optional <constraints> argument can be list of one or more
|
||||
keywords or an expression. If the <constraints> argument consists of
|
||||
keywords, each of these keywords must be the name of an element in the array
|
||||
<I>::tcltest::testConstraints</I>. If any of these elements is false or does
|
||||
not exist, the test is skipped. If the <constraints> argument
|
||||
consists of an expression, that expression is evaluated. If the
|
||||
expression evaluates to true, then the test is run.
|
||||
<P>
|
||||
Add appropriate constraints (e.g.,
|
||||
unixOnly) to any tests that should not always be run. For example, a
|
||||
test that should only be run on Unix should look like the following:
|
||||
<P>
|
||||
<PRE>test getAttribute-1.1 {testing file permissions} {unixOnly} {
|
||||
lindex [file attributes foo.tcl] 5
|
||||
} {00644}</PRE>
|
||||
<P>
|
||||
An example of a test that contains an expression:
|
||||
<P>
|
||||
<PRE>test unixNotfy-1.1 {<A HREF="../TkLib/CrtFileHdlr.htm">Tcl_DeleteFileHandler</A>} {unixOnly && !testthread} {
|
||||
catch {vwait x}
|
||||
set f [open foo w]
|
||||
fileevent $f writable {set x 1}
|
||||
vwait x
|
||||
close $f
|
||||
list [catch {vwait x} msg] $msg
|
||||
} {1 {can't wait for variable "x": would wait forever}}</PRE>
|
||||
<P>
|
||||
See the "Test Constraints" section for a list of built-in
|
||||
constraints and information on how to add your own constraints.
|
||||
<P>
|
||||
The <script> argument contains the script to run to carry out the
|
||||
test. It must return a result that can be checked for correctness.
|
||||
If your script requires that a file be created on the fly, please use
|
||||
the ::tcltest::makeFile procedure. If your test requires that a small
|
||||
file (<50 lines) be checked in, please consider creating the file on
|
||||
the fly using the ::tcltest::makeFile procedure. Files created by the
|
||||
::tcltest::makeFile procedure will automatically be removed by the
|
||||
::tcltest::cleanupTests call at the end of each test file.
|
||||
<P>
|
||||
The <expectedAnswer> argument will be compared against the result of
|
||||
evaluating the <script> argument. If they match, the test passes,
|
||||
otherwise the test fails.
|
||||
<H3><A NAME="M20">TCLTEST NAMEPSACE VARIABLES</A></H3>
|
||||
The following variables are also defined in the <B>tcltest</B> namespace and
|
||||
can be used by tests:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M21"><B>::tcltest::outputChannel</B></A><DD>
|
||||
output file ID - defaults to stdout and can be specified using
|
||||
-outfile on the command line.
|
||||
Any test that prints test related output should send
|
||||
that output to <I>::tcltest::outputChannel</I> rather than letting
|
||||
that output default to stdout.
|
||||
<P><DT><A NAME="M22"><B>::tcltest::errorChannel</B></A><DD>
|
||||
error file ID - defaults to stderr and can be specified using -errfile
|
||||
on the command line.
|
||||
Any test that prints error messages should send
|
||||
that output to <I>::tcltest::errorChannel</I> rather than printing
|
||||
directly to stderr.
|
||||
<P><DT><A NAME="M23"><B>::tcltest::mainThread</B></A><DD>
|
||||
main thread ID - defaults to 1. This is the only thread that is not
|
||||
killed by ::tcltest::threadReap and is set according to the return
|
||||
value of <I>testthread names</I> at initialization.
|
||||
<P><DT><A NAME="M24"><B>::tcltest::originalEnv</B></A><DD>
|
||||
copy of the global "env" array at the beginning of the test run. This
|
||||
array is used to restore the "env" array to its original state when
|
||||
<I>::tcltest::cleanupTests</I> is called.
|
||||
<P><DT><A NAME="M25"><B>::tcltest::workingDirectory</B></A><DD>
|
||||
the directory in which the test suite was launched.
|
||||
<P><DT><A NAME="M26"><B>::tcltest::temporaryDirectory</B></A><DD>
|
||||
the output directory - defaults to <I>::tcltest::workingDirectory</I> and can be
|
||||
specified using -tmpdir on the command line.
|
||||
<P><DT><A NAME="M27"><B>::tcltest::testsDirectory</B></A><DD>
|
||||
where the tests reside - defaults to <I>::tcltest::workingDirectory</I>
|
||||
if the script cannot determine where the <I>tests</I> directory is
|
||||
located. It is possible to change the default by specifying
|
||||
<I>-testdir</I> on the commandline. This variable should be
|
||||
explicitly set if tests are being run from an all.tcl file.
|
||||
<P><DT><A NAME="M28"><B>::tcltest::tcltest</B></A><DD>
|
||||
the name of the executable used to invoke the test suite.
|
||||
<P><DT><A NAME="M29"><B>::tcltest::loadScript</B></A><DD>
|
||||
The script executed <B>loadTestedCommands</B>. Specified either by
|
||||
<I>-load</I> or <I>-loadfile</I>.
|
||||
<P></DL>
|
||||
<H3><A NAME="M30">TEST CONSTRAINTS</A></H3>
|
||||
Constraints are used to determine whether a test should be skipped.
|
||||
Each constraint is stored as an index in the array
|
||||
<I>::tcltest::testConstraints</I>. For example, the unixOnly constraint is
|
||||
defined as the following:
|
||||
<PRE>set ::tcltest::testConstraints(unixOnly) \
|
||||
[string equal $tcl_platform(platform) "unix"]</PRE>
|
||||
If a test is constrained by "unixOnly", then it will only be run if
|
||||
the value of ::tcltest::testConstraints(unixOnly) is true. Several
|
||||
constraints are defined in the <B>tcltest</B> package. To add file- or
|
||||
test-specific constraints, you can set the desired index of the
|
||||
::tcltest::testsConstraints array in your own test file.
|
||||
<P>
|
||||
The following is a list of constraints defined in the <B>tcltest</B> package:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M31"><I>unix</I></A><DD>
|
||||
test can only be run on any UNIX platform
|
||||
<P><DT><A NAME="M32"><I>pc</I></A><DD>
|
||||
test can only be run on any Windows platform
|
||||
<P><DT><A NAME="M33"><I>nt</I></A><DD>
|
||||
test can only be run on any Windows NT platform
|
||||
<P><DT><A NAME="M34"><I>95</I></A><DD>
|
||||
test can only be run on any Windows 95 platform
|
||||
<P><DT><A NAME="M35"><I>98</I></A><DD>
|
||||
test can only be run on any Windows 98 platform
|
||||
<P><DT><A NAME="M36"><I>mac</I></A><DD>
|
||||
test can only be run on any Mac platform
|
||||
<P><DT><A NAME="M37"><I>unixOrPc</I></A><DD>
|
||||
test can only be run on a UNIX or PC platform
|
||||
<P><DT><A NAME="M38"><I>macOrPc</I></A><DD>
|
||||
test can only be run on a Mac or PC platform
|
||||
<P><DT><A NAME="M39"><I>macOrUnix</I></A><DD>
|
||||
test can only be run on a Mac or UNIX platform
|
||||
<P><DT><A NAME="M40"><I>tempNotPc</I></A><DD>
|
||||
test can not be run on Windows. This flag is used to temporarily
|
||||
disable a test.
|
||||
<P><DT><A NAME="M41"><I>tempNotMac</I></A><DD>
|
||||
test can not be run on a Mac. This flag is used
|
||||
to temporarily disable a test.
|
||||
<P><DT><A NAME="M42"><I>unixCrash</I></A><DD>
|
||||
test crashes if it's run on UNIX. This flag is used to temporarily
|
||||
disable a test.
|
||||
<P><DT><A NAME="M43"><I>pcCrash</I></A><DD>
|
||||
test crashes if it's run on Windows. This flag is used to temporarily
|
||||
disable a test.
|
||||
<P><DT><A NAME="M44"><I>macCrash</I></A><DD>
|
||||
test crashes if it's run on a Mac. This flag is used to temporarily
|
||||
disable a test.
|
||||
<P><DT><A NAME="M45"><I>emptyTest</I></A><DD>
|
||||
test is empty, and so not worth running, but it remains as a
|
||||
place-holder for a test to be written in the future. This constraint
|
||||
always causes tests to be skipped.
|
||||
<P><DT><A NAME="M46"><I>knownBug</I></A><DD>
|
||||
test is known to fail and the bug is not yet fixed. This constraint
|
||||
always causes tests to be skipped unless the user specifies otherwise.
|
||||
See the "Introduction" section for more details.
|
||||
<P><DT><A NAME="M47"><I>nonPortable</I></A><DD>
|
||||
test can only be run in the master Tcl/Tk development environment.
|
||||
Some tests are inherently non-portable because they depend on things
|
||||
like word length, file system configuration, window manager, etc.
|
||||
These tests are only run in the main Tcl development directory where
|
||||
the configuration is well known. This constraint always causes tests
|
||||
to be skipped unless the user specifies otherwise.
|
||||
<P><DT><A NAME="M48"><I>userInteraction</I></A><DD>
|
||||
test requires interaction from the user. This constraint always
|
||||
causes tests to be skipped unless the user specifies otherwise.
|
||||
<P><DT><A NAME="M49"><I>interactive</I></A><DD>
|
||||
test can only be run in if the interpreter is in interactive mode,
|
||||
that is the global tcl_interactive variable is set to 1.
|
||||
<P><DT><A NAME="M50"><I>nonBlockFiles</I></A><DD>
|
||||
test can only be run if platform supports setting files into
|
||||
nonblocking mode
|
||||
<P><DT><A NAME="M51"><I>asyncPipeClose</I></A><DD>
|
||||
test can only be run if platform supports async flush and async close
|
||||
on a pipe
|
||||
<P><DT><A NAME="M52"><I>unixExecs</I></A><DD>
|
||||
test can only be run if this machine has commands such as 'cat', 'echo',
|
||||
etc. available.
|
||||
<P><DT><A NAME="M53"><I>hasIsoLocale</I></A><DD>
|
||||
test can only be run if can switch to an ISO locale
|
||||
<P><DT><A NAME="M54"><I>root</I></A><DD>
|
||||
test can only run if Unix user is root
|
||||
<P><DT><A NAME="M55"><I>notRoot</I></A><DD>
|
||||
test can only run if Unix user is not root
|
||||
<P><DT><A NAME="M56"><I>eformat</I></A><DD>
|
||||
test can only run if app has a working version of sprintf with respect
|
||||
to the "e" format of floating-point numbers.
|
||||
<P><DT><A NAME="M57"><I>stdio</I></A><DD>
|
||||
test can only be run if the current app can be spawned via a pipe
|
||||
<P></DL>
|
||||
<H3><A NAME="M58">RUNNING TEST FILES</A></H3>
|
||||
Use the following command to run a test file that uses package
|
||||
tcltest:
|
||||
<PRE><shell> <testFile> ?<option> ?<value>?? ...</PRE>
|
||||
Command line options include (tcltest namespace variables that
|
||||
correspond to each flag are listed at the end of each flag description
|
||||
in parenthesis):
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M59"><B>-help</B></A><DD>
|
||||
display usage information.
|
||||
<P><DT><A NAME="M60"><B>-verbose <level></B></A><DD>
|
||||
set the level of verbosity to a substring of "bps". See the "Test
|
||||
output" section for an explanation of this option. (::tcltest::verbose)
|
||||
<P><DT><A NAME="M61"><B>-match <matchList></B></A><DD>
|
||||
only run tests that match one or more of the glob patterns in
|
||||
<matchList>. (::tcltest::match)
|
||||
<P><DT><A NAME="M62"><B>-skip <skipList></B></A><DD>
|
||||
do not run tests that match one or more of the glob patterns in
|
||||
<skipList>. (::tcltest::skip)
|
||||
<P><DT><A NAME="M63"><B>-file <globPatternList></B></A><DD>
|
||||
only source test files that match any of the items in
|
||||
<globPatternList> relative to ::tcltest::testsDirectory.
|
||||
This option
|
||||
only makes sense if you are running tests using "all.tcl" as the
|
||||
<testFile> instead of running single test files directly.
|
||||
(::tcltest::matchFiles)
|
||||
<P><DT><A NAME="M64"><B>-notfile <globPatternList></B></A><DD>
|
||||
source files except for those that match any of the items in
|
||||
<globPatternList> relative to ::tcltest::testsDirectory.
|
||||
This option
|
||||
only makes sense if you are running tests using "all.tcl" as the
|
||||
<testFile> instead of running single test files directly.
|
||||
(::tcltest::skipFiles)
|
||||
<P><DT><A NAME="M65"><B>-constraints <list></B></A><DD>
|
||||
tests with any constraints in <list> will not be skipped. Note that
|
||||
elements of <list> must exactly match the existing constraints. This
|
||||
is useful if you want to make sure that tests with a particular
|
||||
constraint are run (for example, if the tester wants to run all tests
|
||||
with the knownBug constraint).
|
||||
(::tcltest::testConstraints(<I>constraintName</I>))
|
||||
<P><DT><A NAME="M66"><B>-limitconstraints <bool></B></A><DD>
|
||||
If the argument to this flag is 1, the test harness limits test runs
|
||||
to those tests that match the constraints listed by the -constraints
|
||||
flag. Use of this flag requires use of the -constraints flag. The
|
||||
default value for this flag is 0 (false). This is useful if you want
|
||||
to run <B>only</B> those tests that match the constraints listed using
|
||||
the -constraints option. A tester might want to do this if he were
|
||||
interested in running only those tests that are constrained to be
|
||||
unixOnly and no other tests.
|
||||
(::tcltest::limitConstraints)
|
||||
<P><DT><A NAME="M67"><B>-load <script></B></A><DD>
|
||||
will use the specified script to load the commands under test
|
||||
(::tcltest::loadTestedCommands). The default is the empty
|
||||
script. See -loadfile below too. (::tcltest::loadScript)
|
||||
<P><DT><A NAME="M68"><B>-loadfile <scriptfile></B></A><DD>
|
||||
will use the contents of the named file to load the commands under
|
||||
test (::tcltest::loadTestedCommands). See -load above too. The default
|
||||
is the empty script. (::tcltest::loadScript)
|
||||
<P><DT><A NAME="M69"><B>-tmpdir <directoryName></B></A><DD>
|
||||
put any temporary files (created with ::tcltest::makeFile and
|
||||
::tcltest::makeDirectory) into the named directory. The default
|
||||
location is ::tcltest::workingDirectory. (::tcltest::temporaryDirectory)
|
||||
<P><DT><A NAME="M70"><B>-testdir <directoryName></B></A><DD>
|
||||
search the test suite to execute in the named directory. The default
|
||||
location is ::tcltest::workingDirectory. (::tcltest::testsDirectory)
|
||||
<P><DT><A NAME="M71"><B>-preservecore <level></B></A><DD>
|
||||
check for core files. This flag is used to determine how much
|
||||
checking should be done for core files. The default value for
|
||||
<I>level</I> is 0. Levels are defined as:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M72">0</A><DD>
|
||||
No checking - do not check for core files at the end of each test
|
||||
command, but do check for them whenever ::tcltest::cleanupTests is
|
||||
called from an all.tcl file.
|
||||
<P><DT><A NAME="M73">1</A><DD>
|
||||
Check for core files at the end of each test command and whenever
|
||||
::tcltest::cleanupTests is called from all.tcl.
|
||||
<P><DT><A NAME="M74">2</A><DD>
|
||||
Check for core files at the end of all test commands and whenever
|
||||
::tcltest::cleanupTests is called from all.tcl. Save any core files
|
||||
produced in ::tcltest::temporaryDirectory.
|
||||
<P></DL>
|
||||
<P>
|
||||
(::tcltest::preserveCore)
|
||||
<P><DT><A NAME="M75"><B>-debug <debugLevel></B></A><DD>
|
||||
print debug information to stdout. This is used to debug code in the
|
||||
test harness. The default debug level is 0. Levels are defined as:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M76">0</A><DD>
|
||||
Do not display any debug information.
|
||||
<P><DT><A NAME="M77">1</A><DD>
|
||||
Display information regarding whether a test is skipped because it
|
||||
doesn't match any of the tests that were specified using -match or
|
||||
::tcltest::match (userSpecifiedNonMatch) or matches any of the tests
|
||||
specified by -skip or ::tcltest::skip (userSpecifiedSkip).
|
||||
<P><DT><A NAME="M78">2</A><DD>
|
||||
Display the flag array parsed by the command line processor, the
|
||||
contents of the ::env array, and all user-defined variables that exist
|
||||
in the current namespace as they are used.
|
||||
<P><DT><A NAME="M79">3</A><DD>
|
||||
Display information regarding what individual procs in the test
|
||||
harness are doing.
|
||||
<P></DL>
|
||||
<P>
|
||||
(::tcltest::debug)
|
||||
<P><DT><A NAME="M80"><B>-outfile <filename></B></A><DD>
|
||||
print output generated by the tcltest package to the named file. This
|
||||
defaults to stdout. Note that debug output always goes to stdout,
|
||||
regardless of this flag's setting. (::tcltest::outputChannel)
|
||||
<P><DT><A NAME="M81"><B>-errfile <filename></B></A><DD>
|
||||
print errors generated by the tcltest package to the named file. This
|
||||
defaults to stderr. (::tcltest::errorChannel)
|
||||
<P></DL>
|
||||
<P>
|
||||
A second way to run tets is to start up a shell, load the
|
||||
<B>tcltest</B> package, and then source an appropriate test file or use
|
||||
the test command. To use the options in interactive mode, set
|
||||
their corresponding tcltest namespace variables after loading the
|
||||
package.
|
||||
<P>
|
||||
See <I>"Test Constraints"</I> for all built-in constraint names
|
||||
that can be used in the <B>::tcltest::testConstraints</B> array.
|
||||
See <I>"Tcltest namespace variables"</I> for details on other variables
|
||||
defined in the <B>tcltest</B> namespace.
|
||||
<P>
|
||||
A final way to run tests would be to specify which test files to run
|
||||
within an <I>all.tcl</I> (or otherwise named) file. This is the
|
||||
approach used by the Tcl test suite. This file loads the tcltest
|
||||
package, sets the location of
|
||||
the test directory (::tcltest::testsDirectory), determines which test
|
||||
files to run, sources each of these files, calls
|
||||
::tcltest::cleanupTests and then exits.
|
||||
<P>
|
||||
A more elaborate <I>all.tcl</I> file might do some pre- and
|
||||
post-processing before sourcing
|
||||
each .test file, use separate interpreters for each file, or handle
|
||||
complex directory structures.
|
||||
For an example of an all.tcl file,
|
||||
please see the "Examples" section of this document.
|
||||
<H3><A NAME="M82">TEST OUTPUT</A></H3>
|
||||
After all specified test files are run, the number of tests
|
||||
passed, skipped, and failed is printed to
|
||||
<B>::tcltest::outputChannel</B>. Aside from this
|
||||
statistical information, output can be controlled on a per-test basis
|
||||
by the <B>::tcltest::verbose</B> variable.
|
||||
<P>
|
||||
<B>::tcltest::verbose</B> can be set to any substring or permutation
|
||||
of "bps". In the string "bps", the 'b' stands for a test's "body",
|
||||
the 'p' stands for "passed" tests, and the 's' stands for "skipped"
|
||||
tests. The default value of <B>::tcltest::verbose</B> is "b". If 'b'
|
||||
is present, then the entire body of the test is printed for each
|
||||
failed test, otherwise only the test's name, desired output, and
|
||||
actual output, are printed for each failed test. If 'p' is present,
|
||||
then a line is printed for each passed test, otherwise no line is
|
||||
printed for passed tests. If 's' is present, then a line (containing
|
||||
the consraints that cause the test to be skipped) is printed for each
|
||||
skipped test, otherwise no line is printed for skipped tests.
|
||||
<P>
|
||||
You can set <B>::tcltest::verbose</B> either interactively (after the
|
||||
<B>tcltest</B> package has been loaded) or by using the command line
|
||||
argument <B>-verbose</B>, for example:
|
||||
<PRE>tclsh socket.test -verbose bps</PRE>
|
||||
<H3><A NAME="M83">CONTENTS OF A TEST FILE</A></H3>
|
||||
Test files should begin by loading the <B>tcltest</B> package:
|
||||
<PRE>if {[lsearch [namespace children] ::tcltest] == -1} {
|
||||
package require tcltest
|
||||
namespace import ::tcltest::*
|
||||
}</PRE>
|
||||
Test files should end by cleaning up after themselves and calling
|
||||
<B>::tcltest::cleanupTests</B>. The <B>::tcltest::cleanupTests</B>
|
||||
procedure prints statistics about the number of tests that passed,
|
||||
skipped, and failed, and removes all files that were created using the
|
||||
<B>::tcltest::makeFile</B> and <B>::tcltest::makeDirectory</B> procedures.
|
||||
<PRE># Remove files created by these tests
|
||||
# Change to original working directory
|
||||
# Unset global arrays
|
||||
::tcltest::cleanupTests
|
||||
return</PRE>
|
||||
When naming test files, file names should end with a .test extension.
|
||||
The names of test files that contain regression (or glass-box) tests
|
||||
should correspond to the Tcl or C code file that they are testing.
|
||||
For example, the test file for the C file "tclCmdAH.c" is "cmdAH.test".
|
||||
Test files that contain black-box tests should match the pattern "*_bb.test".
|
||||
<H3><A NAME="M84">SELECTING TESTS FOR EXECUTION WITHIN A FILE</A></H3>
|
||||
Normally, all the tests in a file are run whenever the file is
|
||||
sourced. An individual test will be skipped if one of the following
|
||||
conditions is met:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT>[1]<DD>
|
||||
the <I>name</I> of the tests does not match (using glob style matching)
|
||||
one or more elements in the <B>::tcltest::match</B> variable
|
||||
<P><DT>[2]<DD>
|
||||
the <I>name</I> of the tests matches (using glob style matching) one or
|
||||
more elements in the <B>::tcltest::skip</B> variable
|
||||
<P><DT>[3]<DD>
|
||||
the <I>constraints</I> argument to the <B>::tcltest::test</B> call, if
|
||||
given, contains one or more false elements.
|
||||
<P></DL>
|
||||
<P>
|
||||
You can set <B>::tcltest::match</B> and/or <B>::tcltest::skip</B>
|
||||
either interactively (after the <B>tcltest</B> package has been
|
||||
sourced), or by using the command line arguments <B>-match</B> and
|
||||
<B>-skip</B>, for example:
|
||||
<P>
|
||||
<PRE>tclsh info.test -match '*-5.* *-7.*' -skip '*-7.1*'</PRE>
|
||||
<P>
|
||||
Be sure to use the proper quoting convention so that your shell does
|
||||
not perform the glob substitution on the match or skip patterns you
|
||||
specify.
|
||||
<P>
|
||||
Predefined constraints (e.g. <I>knownBug</I> and <I>nonPortable</I>) can be
|
||||
overridden either interactively (after the <B>tcltest</B> package has been
|
||||
sourced) by setting the proper
|
||||
<B>::tcltest::testConstraints(</B><I>constraint</I><B>)</B> variable
|
||||
or by using the <B>-constraints</B> command line option with the name of the
|
||||
constraint in the argument. The following example shows how to run
|
||||
tests that are constrained by the <I>knownBug</I> and <I>nonPortable</I>
|
||||
restrictions:
|
||||
<P>
|
||||
<PRE>tclsh all.tcl -constraints "knownBug nonPortable"</PRE>
|
||||
<P>
|
||||
See the <I>"Constraints"</I> package for information about using
|
||||
built-in constraints and adding new ones.
|
||||
<H3><A NAME="M85">HOW TO CUSTOMIZE THE TEST HARNESS</A></H3>
|
||||
To create your own custom test harness, create a .tcl file that contains your
|
||||
namespace. Within this file, require package <B>tcltest</B>. Commands
|
||||
that can be redefined to customize the test harness include:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M86"><B>::tcltest::PrintUsageInfoHook</B></A><DD>
|
||||
print additional usage information specific to your situation.
|
||||
<P><DT><A NAME="M87"><B>::tcltest::processCmdLineArgsFlagHook</B></A><DD>
|
||||
tell the test harness about additional flags that you want it to understand.
|
||||
<P><DT><A NAME="M88"><B>::tcltest::processCmdLineArgsHook</B> <I>flags</I></A><DD>
|
||||
process the additional flags that you told the harness about in
|
||||
::tcltest::processCmdLineArgsFlagHook.
|
||||
<P><DT><A NAME="M89"><B>::tcltest::initConstraintsHook</B></A><DD>
|
||||
used to add additional built-in constraints to those already defined
|
||||
by <B>tcltest</B>.
|
||||
<P><DT><A NAME="M90"><B>::tcltest::cleanupTestsHook</B></A><DD>
|
||||
do additional cleanup
|
||||
<P></DL>
|
||||
<P>
|
||||
<P>
|
||||
To add new flags to your customized test harness, redefine
|
||||
<B>::tcltest::processCmdLineArgsAddFlagHook</B> to define additional flags to be
|
||||
parsed and <B>::tcltest::processCmdLineArgsHook</B> to actually process them.
|
||||
For example:
|
||||
<PRE>proc ::tcltest::processCmdLineArgsAddFlagHook {} {
|
||||
return [list -flag1 -flag2]
|
||||
}
|
||||
|
||||
proc ::tcltest::processCmdLineArgsHook {flagArray} {
|
||||
array set flag $flagArray
|
||||
|
||||
if {[info exists flag(-flag1)]} {
|
||||
# Handle flag1
|
||||
}
|
||||
|
||||
if {[info exists flag(-flag2)]} {
|
||||
# Handle flag2
|
||||
}
|
||||
|
||||
return
|
||||
}</PRE>
|
||||
You may also want to add usage information for these flags. This
|
||||
information would be displayed whenever the user specifies -help. To
|
||||
define additional usage information, define your own
|
||||
::tcltest::PrintUsageInfoHook proc. Within this proc, you should
|
||||
print out additional usage information for any flags that you've
|
||||
implemented.
|
||||
<P>
|
||||
To add new built-in
|
||||
constraints to the test harness, define your own version of
|
||||
<B>::tcltest::initConstraintsHook</B>.
|
||||
Within your proc, you can add to the <B>::tcltest::testConstraints</B> array.
|
||||
For example:
|
||||
<PRE>proc ::tcltest::initConstraintsHook {} {
|
||||
set ::tcltest::testConstraints(win95Or98) \
|
||||
[expr {$::tcltest::testConstraints(95) || \
|
||||
$::tcltest::testConstraints(98)}]
|
||||
}</PRE>
|
||||
<P>
|
||||
Finally, if you want to add additional cleanup code to your harness
|
||||
you can define your own <B>::tcltest::cleanupTestsHook</B>. For example:
|
||||
<PRE>proc ::tcltest::cleanupTestsHook {} {
|
||||
# Add your cleanup code here
|
||||
}</PRE>
|
||||
<H3><A NAME="M91">EXAMPLES</A></H3>
|
||||
<DL>
|
||||
<P><DT>[1]<DD>
|
||||
A simple test file (foo.test)
|
||||
<PRE>if {[lsearch [namespace children] ::tcltest] == -1} {
|
||||
package require tcltest
|
||||
namespace import ::tcltest::*
|
||||
}
|
||||
|
||||
test foo-1.1 {save 1 in variable name foo} {} {
|
||||
set foo 1
|
||||
} {1}
|
||||
|
||||
::tcltest::cleanupTests
|
||||
return</PRE>
|
||||
<P><DT>[2]<DD>
|
||||
A simple all.tcl
|
||||
<PRE>if {[lsearch [namespace children] ::tcltest] == -1} {
|
||||
package require tcltest
|
||||
namespace import ::tcltest::*
|
||||
}
|
||||
|
||||
set ::tcltest::testSingleFile false
|
||||
set ::tcltest::testsDirectory [file dir [info script]]
|
||||
|
||||
foreach file [::tcltest::getMatchingTestFiles] {
|
||||
if {[catch {source $file} msg]} {
|
||||
puts stdout $msg
|
||||
}
|
||||
}
|
||||
|
||||
::tclttest::cleanupTests 1
|
||||
return</PRE>
|
||||
<P><DT>[3]<DD>
|
||||
Running a single test
|
||||
<PRE>tclsh foo.test</PRE>
|
||||
<P><DT>[4]<DD>
|
||||
Running multiple tests
|
||||
<PRE>tclsh all.tcl -file 'foo*.test' -notfile 'foo2.test'</PRE>
|
||||
<P></DL>
|
||||
<H3><A NAME="M92">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/T.htm#test">test</A>, <A href="../Keywords/T.htm#test harness">test harness</A>, <A href="../Keywords/T.htm#test suite">test suite</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1990-1994 The Regents of the University of California
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1998-1999 Scriptics Corporation
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
404
hlp/en/tcl/tclvars.htm
Normal file
404
hlp/en/tcl/tclvars.htm
Normal file
@@ -0,0 +1,404 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - tclvars manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="tclvars.htm#M2" NAME="L1260">NAME</A>
|
||||
<DL><DD>tclvars - Variables used by Tcl</DL>
|
||||
<DD><A HREF="tclvars.htm#M3" NAME="L1261">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="tclvars.htm#M4" NAME="L1262"><B>env</B></A>
|
||||
<DL>
|
||||
<DD><A HREF="tclvars.htm#M5" NAME="L1263"><B>LOGIN</B></A>
|
||||
<DD><A HREF="tclvars.htm#M6" NAME="L1264"><B>USER</B></A>
|
||||
<DD><A HREF="tclvars.htm#M7" NAME="L1265"><B>SYS_FOLDER</B></A>
|
||||
<DD><A HREF="tclvars.htm#M8" NAME="L1266"><B>APPLE_M_FOLDER</B></A>
|
||||
<DD><A HREF="tclvars.htm#M9" NAME="L1267"><B>CP_FOLDER</B></A>
|
||||
<DD><A HREF="tclvars.htm#M10" NAME="L1268"><B>DESK_FOLDER</B></A>
|
||||
<DD><A HREF="tclvars.htm#M11" NAME="L1269"><B>EXT_FOLDER</B></A>
|
||||
<DD><A HREF="tclvars.htm#M12" NAME="L1270"><B>PREF_FOLDER</B></A>
|
||||
<DD><A HREF="tclvars.htm#M13" NAME="L1271"><B>PRINT_MON_FOLDER</B></A>
|
||||
<DD><A HREF="tclvars.htm#M14" NAME="L1272"><B>SHARED_TRASH_FOLDER</B></A>
|
||||
<DD><A HREF="tclvars.htm#M15" NAME="L1273"><B>TRASH_FOLDER</B></A>
|
||||
<DD><A HREF="tclvars.htm#M16" NAME="L1274"><B>START_UP_FOLDER</B></A>
|
||||
<DD><A HREF="tclvars.htm#M17" NAME="L1275"><B>HOME</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="tclvars.htm#M18" NAME="L1276"><B>errorCode</B></A>
|
||||
<DL>
|
||||
<DD><A HREF="tclvars.htm#M19" NAME="L1277"><B>ARITH</B><I> code msg</I></A>
|
||||
<DD><A HREF="tclvars.htm#M20" NAME="L1278"><B>CHILDKILLED</B><I> pid sigName msg</I></A>
|
||||
<DD><A HREF="tclvars.htm#M21" NAME="L1279"><B>CHILDSTATUS</B><I> pid code</I></A>
|
||||
<DD><A HREF="tclvars.htm#M22" NAME="L1280"><B>CHILDSUSP</B><I> pid sigName msg</I></A>
|
||||
<DD><A HREF="tclvars.htm#M23" NAME="L1281"><B>NONE</B></A>
|
||||
<DD><A HREF="tclvars.htm#M24" NAME="L1282"><B>POSIX </B><I>errName msg</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="tclvars.htm#M25" NAME="L1283"><B>errorInfo</B></A>
|
||||
<DD><A HREF="tclvars.htm#M26" NAME="L1284"><B>tcl_library</B></A>
|
||||
<DD><A HREF="tclvars.htm#M27" NAME="L1285"><B>tcl_patchLevel</B></A>
|
||||
<DD><A HREF="tclvars.htm#M28" NAME="L1286"><B>tcl_pkgPath</B></A>
|
||||
<DD><A HREF="tclvars.htm#M29" NAME="L1287"><B>tcl_platform</B></A>
|
||||
<DL>
|
||||
<DD><A HREF="tclvars.htm#M30" NAME="L1288"><B>byteOrder</B></A>
|
||||
<DD><A HREF="tclvars.htm#M31" NAME="L1289"><B>debug</B></A>
|
||||
<DD><A HREF="tclvars.htm#M32" NAME="L1290"><B>machine</B></A>
|
||||
<DD><A HREF="tclvars.htm#M33" NAME="L1291"><B>os</B></A>
|
||||
<DD><A HREF="tclvars.htm#M34" NAME="L1292"><B>osVersion</B></A>
|
||||
<DD><A HREF="tclvars.htm#M35" NAME="L1293"><B>platform</B></A>
|
||||
<DD><A HREF="tclvars.htm#M36" NAME="L1294"><B>threaded</B></A>
|
||||
<DD><A HREF="tclvars.htm#M37" NAME="L1295"><B>user</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="tclvars.htm#M38" NAME="L1296"><B>tcl_precision</B></A>
|
||||
<DD><A HREF="tclvars.htm#M39" NAME="L1297"><B>tcl_rcFileName</B></A>
|
||||
<DD><A HREF="tclvars.htm#M40" NAME="L1298"><B>tcl_rcRsrcName</B></A>
|
||||
<DD><A HREF="tclvars.htm#M41" NAME="L1299"><B>tcl_traceCompile</B></A>
|
||||
<DD><A HREF="tclvars.htm#M42" NAME="L1300"><B>tcl_traceExec</B></A>
|
||||
<DD><A HREF="tclvars.htm#M43" NAME="L1301"><B>tcl_wordchars</B></A>
|
||||
<DD><A HREF="tclvars.htm#M44" NAME="L1302"><B>tcl_nonwordchars</B></A>
|
||||
<DD><A HREF="tclvars.htm#M45" NAME="L1303"><B>tcl_version</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="tclvars.htm#M46" NAME="L1304">SEE ALSO</A>
|
||||
<DD><A HREF="tclvars.htm#M47" NAME="L1305">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
tclvars - Variables used by Tcl
|
||||
<H3><A NAME="M3">DESCRIPTION</A></H3>
|
||||
The following global variables are created and managed automatically
|
||||
by the Tcl library. Except where noted below, these variables should
|
||||
normally be treated as read-only by application-specific code and by users.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M4"><B>env</B></A><DD>
|
||||
This variable is maintained by Tcl as an array
|
||||
whose elements are the environment variables for the process.
|
||||
Reading an element will return the value of the corresponding
|
||||
environment variable.
|
||||
Setting an element of the array will modify the corresponding
|
||||
environment variable or create a new one if it doesn't already
|
||||
exist.
|
||||
Unsetting an element of <B>env</B> will remove the corresponding
|
||||
environment variable.
|
||||
Changes to the <B>env</B> array will affect the environment
|
||||
passed to children by commands like <B><A HREF="../TkCmd/exec.htm">exec</A></B>.
|
||||
If the entire <B>env</B> array is unset then Tcl will stop
|
||||
monitoring <B>env</B> accesses and will not update environment
|
||||
variables.
|
||||
<DL><P><DD>
|
||||
Under Windows, the environment variables PATH and COMSPEC in any
|
||||
capitalization are converted automatically to upper case. For instance, the
|
||||
PATH variable could be exported by the operating system as ``path'',
|
||||
``Path'', ``PaTh'', etc., causing otherwise simple Tcl code to have to
|
||||
support many special cases. All other environment variables inherited by
|
||||
Tcl are left unmodified.
|
||||
</DL>
|
||||
<DL><P><DD>
|
||||
On the Macintosh, the environment variable is constructed by Tcl as no
|
||||
global environment variable exists. The environment variables that
|
||||
are created for Tcl include:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>LOGIN</B></A><DD>
|
||||
This holds the Chooser name of the Macintosh.
|
||||
<P><DT><A NAME="M6"><B>USER</B></A><DD>
|
||||
This also holds the Chooser name of the Macintosh.
|
||||
<P><DT><A NAME="M7"><B>SYS_FOLDER</B></A><DD>
|
||||
The path to the system directory.
|
||||
<P><DT><A NAME="M8"><B>APPLE_M_FOLDER</B></A><DD>
|
||||
The path to the Apple Menu directory.
|
||||
<P><DT><A NAME="M9"><B>CP_FOLDER</B></A><DD>
|
||||
The path to the control panels directory.
|
||||
<P><DT><A NAME="M10"><B>DESK_FOLDER</B></A><DD>
|
||||
The path to the desk top directory.
|
||||
<P><DT><A NAME="M11"><B>EXT_FOLDER</B></A><DD>
|
||||
The path to the system extensions directory.
|
||||
<P><DT><A NAME="M12"><B>PREF_FOLDER</B></A><DD>
|
||||
The path to the preferences directory.
|
||||
<P><DT><A NAME="M13"><B>PRINT_MON_FOLDER</B></A><DD>
|
||||
The path to the print monitor directory.
|
||||
<P><DT><A NAME="M14"><B>SHARED_TRASH_FOLDER</B></A><DD>
|
||||
The path to the network trash directory.
|
||||
<P><DT><A NAME="M15"><B>TRASH_FOLDER</B></A><DD>
|
||||
The path to the trash directory.
|
||||
<P><DT><A NAME="M16"><B>START_UP_FOLDER</B></A><DD>
|
||||
The path to the start up directory.
|
||||
<P><DT><A NAME="M17"><B>HOME</B></A><DD>
|
||||
The path to the application's default directory.
|
||||
<P></DL>
|
||||
<P>
|
||||
You can also create your own environment variables for the Macintosh.
|
||||
A file named <I>Tcl Environment Variables</I> may be placed in the
|
||||
preferences folder in the Mac system folder. Each line of this file
|
||||
should be of the form <I>VAR_NAME=var_data</I>.
|
||||
<P>
|
||||
The last alternative is to place environment variables in a 'STR#'
|
||||
resource named <I>Tcl Environment Variables</I> of the application. This
|
||||
is considered a little more ``Mac like'' than a Unix style Environment
|
||||
Variable file. Each entry in the 'STR#' resource has the same format
|
||||
as above. The source code file <I>tclMacEnv.c</I> contains the
|
||||
implementation of the env mechanisms. This file contains many
|
||||
#define's that allow customization of the env mechanisms to fit your
|
||||
applications needs.
|
||||
</DL>
|
||||
<P><DT><A NAME="M18"><B>errorCode</B></A><DD>
|
||||
After an error has occurred, this variable will be set to hold
|
||||
additional information about the error in a form that is easy
|
||||
to process with programs.
|
||||
<B>errorCode</B> consists of a Tcl list with one or more elements.
|
||||
The first element of the list identifies a general class of
|
||||
errors, and determines the format of the rest of the list.
|
||||
The following formats for <B>errorCode</B> are used by the
|
||||
Tcl core; individual applications may define additional formats.
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M19"><B>ARITH</B><I> code msg</I></A><DD>
|
||||
This format is used when an arithmetic error occurs (e.g. an attempt
|
||||
to divide by zero in the <B><A HREF="../TkCmd/expr.htm">expr</A></B> command).
|
||||
<I>Code</I> identifies the precise error and <I>msg</I> provides a
|
||||
human-readable description of the error. <I>Code</I> will be either
|
||||
DIVZERO (for an attempt to divide by zero),
|
||||
DOMAIN (if an argument is outside the domain of a function, such as acos(-3)),
|
||||
IOVERFLOW (for integer overflow),
|
||||
OVERFLOW (for a floating-point overflow),
|
||||
or UNKNOWN (if the cause of the error cannot be determined).
|
||||
<P><DT><A NAME="M20"><B>CHILDKILLED</B><I> pid sigName msg</I></A><DD>
|
||||
This format is used when a child process has been killed because of
|
||||
a signal. The second element of <B>errorCode</B> will be the
|
||||
process's identifier (in decimal).
|
||||
The third element will be the symbolic name of the signal that caused
|
||||
the process to terminate; it will be one of the names from the
|
||||
include file signal.h, such as <B>SIGPIPE</B>.
|
||||
The fourth element will be a short human-readable message
|
||||
describing the signal, such as ``write on pipe with no readers''
|
||||
for <B>SIGPIPE</B>.
|
||||
<P><DT><A NAME="M21"><B>CHILDSTATUS</B><I> pid code</I></A><DD>
|
||||
This format is used when a child process has exited with a non-zero
|
||||
exit status. The second element of <B>errorCode</B> will be the
|
||||
process's identifier (in decimal) and the third element will be the exit
|
||||
code returned by the process (also in decimal).
|
||||
<P><DT><A NAME="M22"><B>CHILDSUSP</B><I> pid sigName msg</I></A><DD>
|
||||
This format is used when a child process has been suspended because
|
||||
of a signal.
|
||||
The second element of <B>errorCode</B> will be the process's identifier,
|
||||
in decimal.
|
||||
The third element will be the symbolic name of the signal that caused
|
||||
the process to suspend; this will be one of the names from the
|
||||
include file signal.h, such as <B>SIGTTIN</B>.
|
||||
The fourth element will be a short human-readable message
|
||||
describing the signal, such as ``background tty read''
|
||||
for <B>SIGTTIN</B>.
|
||||
<P><DT><A NAME="M23"><B>NONE</B></A><DD>
|
||||
This format is used for errors where no additional information is
|
||||
available for an error besides the message returned with the
|
||||
error. In these cases <B>errorCode</B> will consist of a list
|
||||
containing a single element whose contents are <B>NONE</B>.
|
||||
<P><DT><A NAME="M24"><B>POSIX </B><I>errName msg</I></A><DD>
|
||||
If the first element of <B>errorCode</B> is <B>POSIX</B>, then
|
||||
the error occurred during a POSIX kernel call.
|
||||
The second element of the list will contain the symbolic name
|
||||
of the error that occurred, such as <B>ENOENT</B>; this will
|
||||
be one of the values defined in the include file errno.h.
|
||||
The third element of the list will be a human-readable
|
||||
message corresponding to <I>errName</I>, such as
|
||||
``no such file or directory'' for the <B>ENOENT</B> case.
|
||||
</DL><P>To set <B>errorCode</B>, applications should use library
|
||||
procedures such as <B><A HREF="../TkLib/AddErrInfo.htm">Tcl_SetErrorCode</A></B> and <B><A HREF="../TkLib/AddErrInfo.htm">Tcl_PosixError</A></B>,
|
||||
or they may invoke the <B><A HREF="../TkCmd/error.htm">error</A></B> command.
|
||||
If one of these methods hasn't been used, then the Tcl
|
||||
interpreter will reset the variable to <B>NONE</B> after
|
||||
the next error.<DL>
|
||||
<P></DL>
|
||||
<P><DT><A NAME="M25"><B>errorInfo</B></A><DD>
|
||||
After an error has occurred, this string will contain one or more lines
|
||||
identifying the Tcl commands and procedures that were being executed
|
||||
when the most recent error occurred.
|
||||
Its contents take the form of a stack trace showing the various
|
||||
nested Tcl commands that had been invoked at the time of the error.
|
||||
<P><DT><A NAME="M26"><B>tcl_library</B></A><DD>
|
||||
This variable holds the name of a directory containing the
|
||||
system library of Tcl scripts, such as those used for auto-loading.
|
||||
The value of this variable is returned by the <B><A HREF="../TkCmd/info.htm">info library</A></B> command.
|
||||
See the <B>library</B> manual entry for details of the facilities
|
||||
provided by the Tcl script library.
|
||||
Normally each application or package will have its own application-specific
|
||||
script library in addition to the Tcl script library;
|
||||
each application should set a global variable with a name like
|
||||
<B>$</B><I>app</I><B>_library</B> (where <I>app</I> is the application's name)
|
||||
to hold the network file name for that application's library directory.
|
||||
The initial value of <B>tcl_library</B> is set when an interpreter
|
||||
is created by searching several different directories until one is
|
||||
found that contains an appropriate Tcl startup script.
|
||||
If the <B>TCL_LIBRARY</B> environment variable exists, then
|
||||
the directory it names is checked first.
|
||||
If <B>TCL_LIBRARY</B> isn't set or doesn't refer to an appropriate
|
||||
directory, then Tcl checks several other directories based on a
|
||||
compiled-in default location, the location of the binary containing
|
||||
the application, and the current working directory.
|
||||
<P><DT><A NAME="M27"><B>tcl_patchLevel</B></A><DD>
|
||||
When an interpreter is created Tcl initializes this variable to
|
||||
hold a string giving the current patch level for Tcl, such as
|
||||
<B>7.3p2</B> for Tcl 7.3 with the first two official patches, or
|
||||
<B>7.4b4</B> for the fourth beta release of Tcl 7.4.
|
||||
The value of this variable is returned by the <B><A HREF="../TkCmd/info.htm">info patchlevel</A></B>
|
||||
command.
|
||||
<P><DT><A NAME="M28"><B>tcl_pkgPath</B></A><DD>
|
||||
This variable holds a list of directories indicating where packages are
|
||||
normally installed. It is not used on Windows. It typically contains
|
||||
either one or two entries; if it contains two entries, the first is
|
||||
normally a directory for platform-dependent packages (e.g., shared library
|
||||
binaries) and the second is normally a directory for platform-independent
|
||||
packages (e.g., script files). Typically a package is installed as a
|
||||
subdirectory of one of the entries in <B>$tcl_pkgPath</B>. The directories
|
||||
in <B>$tcl_pkgPath</B> are included by default in the <B>auto_path</B>
|
||||
variable, so they and their immediate subdirectories are automatically
|
||||
searched for packages during <B>package require</B> commands. Note:
|
||||
<B>tcl_pkgPath</B> it not intended to be modified by the application. Its
|
||||
value is added to <B>auto_path</B> at startup; changes to <B>tcl_pkgPath</B>
|
||||
are not reflected in <B>auto_path</B>. If you want Tcl to search additional
|
||||
directories for packages you should add the names of those directories to
|
||||
<B>auto_path</B>, not <B>tcl_pkgPath</B>.
|
||||
<P><DT><A NAME="M29"><B>tcl_platform</B></A><DD>
|
||||
This is an associative array whose elements contain information about
|
||||
the platform on which the application is running, such as the name of
|
||||
the operating system, its current release number, and the machine's
|
||||
instruction set. The elements listed below will always
|
||||
be defined, but they may have empty strings as values if Tcl couldn't
|
||||
retrieve any relevant information. In addition, extensions
|
||||
and applications may add additional values to the array. The
|
||||
predefined elements are:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M30"><B>byteOrder</B></A><DD>
|
||||
The native byte order of this machine: either <B>littleEndian</B> or
|
||||
<B>bigEndian</B>.
|
||||
<P><DT><A NAME="M31"><B>debug</B></A><DD>
|
||||
If this variable exists, then the interpreter
|
||||
was compiled with debugging symbols enabled. This varible will only
|
||||
exist on Windows so extension writers can specify which package to load
|
||||
depending on the C run-time library that is loaded.
|
||||
<P><DT><A NAME="M32"><B>machine</B></A><DD>
|
||||
The instruction set executed by this machine, such as
|
||||
<B>intel</B>, <B>PPC</B>, <B>68k</B>, or <B>sun4m</B>. On UNIX machines, this
|
||||
is the value returned by <B>uname -m</B>.
|
||||
<P><DT><A NAME="M33"><B>os</B></A><DD>
|
||||
The name of the operating system running on this machine,
|
||||
such as <B>Windows 95</B>, <B>Windows NT</B>, <B>MacOS</B>, or <B>SunOS</B>.
|
||||
On UNIX machines, this is the value returned by <B>uname -s</B>.
|
||||
On Windows 95 and Windows 98, the value returned will be <B>Windows
|
||||
95</B> to provide better backwards compatibility to Windows 95; to
|
||||
distinguish between the two, check the <B>osVersion</B>.
|
||||
<P><DT><A NAME="M34"><B>osVersion</B></A><DD>
|
||||
The version number for the operating system running on this machine.
|
||||
On UNIX machines, this is the value returned by <B>uname -r</B>. On
|
||||
Windows 95, the version will be 4.0; on Windows 98, the version will
|
||||
be 4.10.
|
||||
<P><DT><A NAME="M35"><B>platform</B></A><DD>
|
||||
Either <B>windows</B>, <B>macintosh</B>, or <B>unix</B>. This identifies the
|
||||
general operating environment of the machine.
|
||||
<P><DT><A NAME="M36"><B>threaded</B></A><DD>
|
||||
If this variable exists, then the interpreter
|
||||
was compiled with threads enabled.
|
||||
<P><DT><A NAME="M37"><B>user</B></A><DD>
|
||||
This identifies the
|
||||
current user based on the login information available on the platform.
|
||||
This comes from the USER or LOGNAME environment variable on Unix,
|
||||
and the value from GetUserName on Windows and Macintosh.
|
||||
<P></DL>
|
||||
<P><DT><A NAME="M38"><B>tcl_precision</B></A><DD>
|
||||
This variable controls the number of digits to generate
|
||||
when converting floating-point values to strings. It defaults
|
||||
to 12.
|
||||
17 digits is ``perfect'' for IEEE floating-point in that it allows
|
||||
double-precision values to be converted to strings and back to
|
||||
binary with no loss of information. However, using 17 digits prevents
|
||||
any rounding, which produces longer, less intuitive results. For example,
|
||||
<B>expr 1.4</B> returns 1.3999999999999999 with <B>tcl_precision</B>
|
||||
set to 17, vs. 1.4 if <B>tcl_precision</B> is 12.
|
||||
<DL><P><DD>
|
||||
All interpreters in a process share a single <B>tcl_precision</B> value:
|
||||
changing it in one interpreter will affect all other interpreters as
|
||||
well. However, safe interpreters are not allowed to modify the
|
||||
variable.
|
||||
</DL>
|
||||
<P><DT><A NAME="M39"><B>tcl_rcFileName</B></A><DD>
|
||||
This variable is used during initialization to indicate the name of a
|
||||
user-specific startup file. If it is set by application-specific
|
||||
initialization, then the Tcl startup code will check for the existence
|
||||
of this file and <B><A HREF="../TkCmd/source.htm">source</A></B> it if it exists. For example, for <B><A HREF="../UserCmd/wish.htm">wish</A></B>
|
||||
the variable is set to <B>~/.wishrc</B> for Unix and <B>~/wishrc.tcl</B>
|
||||
for Windows.
|
||||
<P><DT><A NAME="M40"><B>tcl_rcRsrcName</B></A><DD>
|
||||
This variable is only used on Macintosh systems. The variable is used
|
||||
during initialization to indicate the name of a user-specific
|
||||
<B><A HREF="../TclCmd/text.htm">TEXT</A></B> resource located in the application or extension resource
|
||||
forks. If it is set by application-specific initialization, then the
|
||||
Tcl startup code will check for the existence of this resource and
|
||||
<B><A HREF="../TkCmd/source.htm">source</A></B> it if it exists. For example, the Macintosh <B><A HREF="../UserCmd/wish.htm">wish</A></B>
|
||||
application has the variable is set to <B>tclshrc</B>.
|
||||
<P><DT><A NAME="M41"><B>tcl_traceCompile</B></A><DD>
|
||||
The value of this variable can be set to control
|
||||
how much tracing information
|
||||
is displayed during bytecode compilation.
|
||||
By default, tcl_traceCompile is zero and no information is displayed.
|
||||
Setting tcl_traceCompile to 1 generates a one line summary in stdout
|
||||
whenever a procedure or top level command is compiled.
|
||||
Setting it to 2 generates a detailed listing in stdout of the
|
||||
bytecode instructions emitted during every compilation.
|
||||
This variable is useful in
|
||||
tracking down suspected problems with the Tcl compiler.
|
||||
It is also occasionally useful when converting
|
||||
existing code to use Tcl8.0.
|
||||
<P><DT><A NAME="M42"><B>tcl_traceExec</B></A><DD>
|
||||
The value of this variable can be set to control
|
||||
how much tracing information
|
||||
is displayed during bytecode execution.
|
||||
By default, tcl_traceExec is zero and no information is displayed.
|
||||
Setting tcl_traceExec to 1 generates a one line trace in stdout
|
||||
on each call to a Tcl procedure.
|
||||
Setting it to 2 generates a line of output
|
||||
whenever any Tcl command is invoked
|
||||
that contains the name of the command and its arguments.
|
||||
Setting it to 3 produces a detailed trace showing the result of
|
||||
executing each bytecode instruction.
|
||||
Note that when tcl_traceExec is 2 or 3,
|
||||
commands such as set and incr
|
||||
that have been entirely replaced by a sequence
|
||||
of bytecode instructions are not shown.
|
||||
Setting this variable is useful in
|
||||
tracking down suspected problems with the bytecode compiler
|
||||
and interpreter.
|
||||
It is also occasionally useful when converting
|
||||
code to use Tcl8.0.
|
||||
<P><DT><A NAME="M43"><B>tcl_wordchars</B></A><DD>
|
||||
The value of this variable is a regular expression that can be set to
|
||||
control what are considered ``word'' characters, for instances like
|
||||
selecting a word by double-clicking in text in Tk. It is platform
|
||||
dependent. On Windows, it defaults to <B>\S</B>, meaning anything
|
||||
but a Unicode space character. Otherwise it defaults to <B>\w</B>,
|
||||
which is any Unicode word character (number, letter, or underscore).
|
||||
<P><DT><A NAME="M44"><B>tcl_nonwordchars</B></A><DD>
|
||||
The value of this variable is a regular expression that can be set to
|
||||
control what are considered ``non-word'' characters, for instances like
|
||||
selecting a word by double-clicking in text in Tk. It is platform
|
||||
dependent. On Windows, it defaults to <B>\s</B>, meaning any Unicode space
|
||||
character. Otherwise it defaults to <B>\W</B>, which is anything but a
|
||||
Unicode word character (number, letter, or underscore).
|
||||
<P><DT><A NAME="M45"><B>tcl_version</B></A><DD>
|
||||
When an interpreter is created Tcl initializes this variable to
|
||||
hold the version number for this version of Tcl in the form <I>x.y</I>.
|
||||
Changes to <I>x</I> represent major changes with probable
|
||||
incompatibilities and changes to <I>y</I> represent small enhancements and
|
||||
bug fixes that retain backward compatibility.
|
||||
The value of this variable is returned by the <B><A HREF="../TkCmd/info.htm">info tclversion</A></B>
|
||||
command.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M46">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/eval.htm">eval</A></B>
|
||||
<H3><A NAME="M47">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#arithmetic">arithmetic</A>, <A href="../Keywords/B.htm#bytecode">bytecode</A>, <A href="../Keywords/C.htm#compiler">compiler</A>, <A href="../Keywords/E.htm#error">error</A>, <A href="../Keywords/E.htm#environment">environment</A>, <A href="../Keywords/P.htm#POSIX">POSIX</A>, <A href="../Keywords/P.htm#precision">precision</A>, <A href="../Keywords/S.htm#subprocess">subprocess</A>, <A href="../Keywords/V.htm#variables">variables</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
22
hlp/en/tcl/tell.htm
Normal file
22
hlp/en/tcl/tell.htm
Normal file
@@ -0,0 +1,22 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - tell manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
tell - Return current access position for an open channel
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>tell </B><I>channelId</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
Returns an integer string giving the current access position in
|
||||
<I>channelId</I>. This value returned is a byte offset that can be passed to
|
||||
<B><A HREF="../TkCmd/seek.htm">seek</A></B> in order to set the channel to a particular position. Note
|
||||
that this value is in terms of bytes, not characters like <B><A HREF="../TkCmd/read.htm">read</A></B>.
|
||||
The value returned is -1 for channels that do not support
|
||||
seeking.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/open.htm">open</A></B>, <B><A HREF="../TkCmd/close.htm">close</A></B>, <B><A HREF="../TkCmd/gets.htm">gets</A></B>, <B><A HREF="../TkCmd/seek.htm">seek</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/A.htm#access position">access position</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/S.htm#seeking">seeking</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
23
hlp/en/tcl/time.htm
Normal file
23
hlp/en/tcl/time.htm
Normal file
@@ -0,0 +1,23 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - time manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
time - Time the execution of a script
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>time </B><I>script</I> ?<I>count</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command will call the Tcl interpreter <I>count</I>
|
||||
times to evaluate <I>script</I> (or once if <I>count</I> isn't
|
||||
specified). It will then return a string of the form
|
||||
<PRE><B>503 microseconds per iteration</B></PRE>
|
||||
which indicates the average amount of time required per iteration,
|
||||
in microseconds.
|
||||
Time is measured in elapsed time, not CPU time.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/clock.htm">clock</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/S.htm#script">script</A>, <A href="../Keywords/T.htm#time">time</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
165
hlp/en/tcl/trace.htm
Normal file
165
hlp/en/tcl/trace.htm
Normal file
@@ -0,0 +1,165 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - trace manual page</TITLE></HEAD><BODY>
|
||||
<DL>
|
||||
<DD><A HREF="trace.htm#M2" NAME="L1316">NAME</A>
|
||||
<DL><DD>trace - Monitor variable accesses</DL>
|
||||
<DD><A HREF="trace.htm#M3" NAME="L1317">SYNOPSIS</A>
|
||||
<DL>
|
||||
<DD><B>trace </B><I>option</I> ?<I>arg arg ...</I>?
|
||||
</DL>
|
||||
<DD><A HREF="trace.htm#M4" NAME="L1318">DESCRIPTION</A>
|
||||
<DL>
|
||||
<DD><A HREF="trace.htm#M5" NAME="L1319"><B>trace variable </B><I>name ops command</I></A>
|
||||
<DL>
|
||||
<DD><A HREF="trace.htm#M6" NAME="L1320"><B>r</B></A>
|
||||
<DD><A HREF="trace.htm#M7" NAME="L1321"><B>w</B></A>
|
||||
<DD><A HREF="trace.htm#M8" NAME="L1322"><B>u</B></A>
|
||||
</DL>
|
||||
<DD><A HREF="trace.htm#M9" NAME="L1323"><B>trace vdelete </B><I>name ops command</I></A>
|
||||
<DD><A HREF="trace.htm#M10" NAME="L1324"><B>trace vinfo </B><I>name</I></A>
|
||||
</DL>
|
||||
<DD><A HREF="trace.htm#M11" NAME="L1325">KEYWORDS</A>
|
||||
</DL><HR>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
trace - Monitor variable accesses
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>trace </B><I>option</I> ?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command causes Tcl commands to be executed whenever certain operations are
|
||||
invoked. At present, only variable tracing is implemented. The
|
||||
legal <I>option</I>'s (which may be abbreviated) are:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M5"><B>trace variable </B><I>name ops command</I></A><DD>
|
||||
Arrange for <I>command</I> to be executed whenever variable <I>name</I>
|
||||
is accessed in one of the ways given by <I>ops</I>. <I>Name</I> may
|
||||
refer to a normal variable, an element of an array, or to an array
|
||||
as a whole (i.e. <I>name</I> may be just the name of an array, with no
|
||||
parenthesized index). If <I>name</I> refers to a whole array, then
|
||||
<I>command</I> is invoked whenever any element of the array is
|
||||
manipulated. If the variable does not exist, it will be created but
|
||||
will not be given a value, so it will be visible to <B>namespace which</B>
|
||||
queries, but not to <B><A HREF="../TkCmd/info.htm">info exists</A></B> queries.
|
||||
<P>
|
||||
<I>Ops</I> indicates which operations are of interest, and consists of
|
||||
one or more of the following letters:
|
||||
<P>
|
||||
<DL>
|
||||
<P><DT><A NAME="M6"><B>r</B></A><DD>
|
||||
Invoke <I>command</I> whenever the variable is read.
|
||||
<P><DT><A NAME="M7"><B>w</B></A><DD>
|
||||
Invoke <I>command</I> whenever the variable is written.
|
||||
<P><DT><A NAME="M8"><B>u</B></A><DD>
|
||||
Invoke <I>command</I> whenever the variable is unset. Variables
|
||||
can be unset explicitly with the <B><A HREF="../TkCmd/unset.htm">unset</A></B> command, or
|
||||
implicitly when procedures return (all of their local variables
|
||||
are unset). Variables are also unset when interpreters are
|
||||
deleted, but traces will not be invoked because there is no
|
||||
interpreter in which to execute them.
|
||||
<P></DL>
|
||||
<P>
|
||||
When the trace triggers, three arguments are appended to
|
||||
<I>command</I> so that the actual command is as follows:
|
||||
<PRE><I>command name1 name2 op</I></PRE>
|
||||
<I>Name1</I> and <I>name2</I> give the name(s) for the variable
|
||||
being accessed: if the variable is a scalar then <I>name1</I>
|
||||
gives the variable's name and <I>name2</I> is an empty string;
|
||||
if the variable is an array element then <I>name1</I> gives the
|
||||
name of the array and name2 gives the index into the array;
|
||||
if an entire array is being deleted and the trace was registered
|
||||
on the overall array, rather than a single element, then <I>name1</I>
|
||||
gives the array name and <I>name2</I> is an empty string.
|
||||
<I>Name1</I> and <I>name2</I> are not necessarily the same as the
|
||||
name used in the <B>trace variable</B> command: the <B><A HREF="../TkCmd/upvar.htm">upvar</A></B>
|
||||
command allows a procedure to reference a variable under a
|
||||
different name.
|
||||
<I>Op</I> indicates what operation is being performed on the
|
||||
variable, and is one of <B>r</B>, <B>w</B>, or <B>u</B> as
|
||||
defined above.
|
||||
<P>
|
||||
<I>Command</I> executes in the same context as the code that invoked
|
||||
the traced operation: if the variable was accessed as part of a
|
||||
Tcl procedure, then <I>command</I> will have access to the same
|
||||
local variables as code in the procedure. This context may be
|
||||
different than the context in which the trace was created.
|
||||
If <I>command</I> invokes a procedure (which it normally does) then
|
||||
the procedure will have to use <B><A HREF="../TkCmd/upvar.htm">upvar</A></B> or <B><A HREF="../TkCmd/uplevel.htm">uplevel</A></B> if it
|
||||
wishes to access the traced variable.
|
||||
Note also that <I>name1</I> may not necessarily be the same as the name
|
||||
used to set the trace on the variable; differences can occur if
|
||||
the access is made through a variable defined with the <B><A HREF="../TkCmd/upvar.htm">upvar</A></B>
|
||||
command.
|
||||
<P>
|
||||
For read and write traces, <I>command</I> can modify
|
||||
the variable to affect the result of the traced operation.
|
||||
If <I>command</I> modifies the value of a variable during a
|
||||
read or write trace, then the new value will be returned as the
|
||||
result of the traced operation.
|
||||
The return value from <I>command</I> is ignored except that
|
||||
if it returns an error of any sort then the traced operation
|
||||
also returns an error with
|
||||
the same error message returned by the trace command
|
||||
(this mechanism can be used to implement read-only variables, for
|
||||
example).
|
||||
For write traces, <I>command</I> is invoked after the variable's
|
||||
value has been changed; it can write a new value into the variable
|
||||
to override the original value specified in the write operation.
|
||||
To implement read-only variables, <I>command</I> will have to restore
|
||||
the old value of the variable.
|
||||
<P>
|
||||
While <I>command</I> is executing during a read or write trace, traces
|
||||
on the variable are temporarily disabled.
|
||||
This means that reads and writes invoked by
|
||||
<I>command</I> will occur directly, without invoking <I>command</I>
|
||||
(or any other traces) again.
|
||||
However, if <I>command</I> unsets the variable then unset traces
|
||||
will be invoked.
|
||||
<P>
|
||||
When an unset trace is invoked, the variable has already been
|
||||
deleted: it will appear to be undefined with no traces.
|
||||
If an unset occurs because of a procedure return, then the
|
||||
trace will be invoked in the variable context of the procedure
|
||||
being returned to: the stack frame of the returning procedure
|
||||
will no longer exist.
|
||||
Traces are not disabled during unset traces, so if an unset trace
|
||||
command creates a new trace and accesses the variable, the
|
||||
trace will be invoked.
|
||||
Any errors in unset traces are ignored.
|
||||
<P>
|
||||
If there are multiple traces on a variable they are invoked
|
||||
in order of creation, most-recent first.
|
||||
If one trace returns an error, then no further traces are
|
||||
invoked for the variable.
|
||||
If an array element has a trace set, and there is also a trace
|
||||
set on the array as a whole, the trace on the overall array
|
||||
is invoked before the one on the element.
|
||||
<P>
|
||||
Once created, the trace remains in effect either until the
|
||||
trace is removed with the <B>trace vdelete</B> command described
|
||||
below, until the variable is unset, or until the interpreter
|
||||
is deleted.
|
||||
Unsetting an element of array will remove any traces on that
|
||||
element, but will not remove traces on the overall array.
|
||||
<P>This command returns an empty string.
|
||||
<P><DT><A NAME="M9"><B>trace vdelete </B><I>name ops command</I></A><DD>
|
||||
If there is a trace set on variable <I>name</I> with the
|
||||
operations and command given by <I>ops</I> and <I>command</I>,
|
||||
then the trace is removed, so that <I>command</I> will never
|
||||
again be invoked.
|
||||
Returns an empty string.
|
||||
<P><DT><A NAME="M10"><B>trace vinfo </B><I>name</I></A><DD>
|
||||
Returns a list containing one element for each trace
|
||||
currently set on variable <I>name</I>.
|
||||
Each element of the list is itself a list containing two
|
||||
elements, which are the <I>ops</I> and <I>command</I> associated
|
||||
with the trace.
|
||||
If <I>name</I> doesn't exist or doesn't have any traces set, then
|
||||
the result of the command will be an empty string.
|
||||
|
||||
<P></DL>
|
||||
<H3><A NAME="M11">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/R.htm#read">read</A>, <A href="../Keywords/V.htm#variable">variable</A>, <A href="../Keywords/W.htm#write">write</A>, <A href="../Keywords/T.htm#trace">trace</A>, <A href="../Keywords/U.htm#unset">unset</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
67
hlp/en/tcl/unknown.htm
Normal file
67
hlp/en/tcl/unknown.htm
Normal file
@@ -0,0 +1,67 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - unknown manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
unknown - Handle attempts to use non-existent commands
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>unknown </B><I>cmdName </I>?<I>arg arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command is invoked by the Tcl interpreter whenever a script
|
||||
tries to invoke a command that doesn't exist. The implementation
|
||||
of <B>unknown</B> isn't part of the Tcl core; instead, it is a
|
||||
library procedure defined by default when Tcl starts up. You
|
||||
can override the default <B>unknown</B> to change its functionality.
|
||||
<P>
|
||||
If the Tcl interpreter encounters a command name for which there
|
||||
is not a defined command, then Tcl checks for the existence of
|
||||
a command named <B>unknown</B>.
|
||||
If there is no such command, then the interpreter returns an
|
||||
error.
|
||||
If the <B>unknown</B> command exists, then it is invoked with
|
||||
arguments consisting of the fully-substituted name and arguments
|
||||
for the original non-existent command.
|
||||
The <B>unknown</B> command typically does things like searching
|
||||
through library directories for a command procedure with the name
|
||||
<I>cmdName</I>, or expanding abbreviated command names to full-length,
|
||||
or automatically executing unknown commands as sub-processes.
|
||||
In some cases (such as expanding abbreviations) <B>unknown</B> will
|
||||
change the original command slightly and then (re-)execute it.
|
||||
The result of the <B>unknown</B> command is used as the result for
|
||||
the original non-existent command.
|
||||
<P>
|
||||
The default implementation of <B>unknown</B> behaves as follows.
|
||||
It first calls the <B><A HREF="../TkCmd/library.htm">auto_load</A></B> library procedure to load the command.
|
||||
If this succeeds, then it executes the original command with its
|
||||
original arguments.
|
||||
If the auto-load fails then <B>unknown</B> calls <B><A HREF="../TkCmd/library.htm">auto_execok</A></B>
|
||||
to see if there is an executable file by the name <I>cmd</I>.
|
||||
If so, it invokes the Tcl <B><A HREF="../TkCmd/exec.htm">exec</A></B> command
|
||||
with <I>cmd</I> and all the <I>args</I> as arguments.
|
||||
If <I>cmd</I> can't be auto-executed, <B>unknown</B> checks to
|
||||
see if the command was invoked at top-level and outside of any
|
||||
script. If so, then <B>unknown</B> takes two additional steps.
|
||||
First, it sees if <I>cmd</I> has one of the following three forms:
|
||||
<B>!!</B>, <B>!</B><I>event</I>, or <B>^</B><I>old</I><B>^</B><I>new</I>?<B>^</B>?.
|
||||
If so, then <B>unknown</B> carries out history substitution
|
||||
in the same way that <B>csh</B> would for these constructs.
|
||||
Finally, <B>unknown</B> checks to see if <I>cmd</I> is
|
||||
a unique abbreviation for an existing Tcl command.
|
||||
If so, it expands the command name and executes the command with
|
||||
the original arguments.
|
||||
If none of the above efforts has been able to execute
|
||||
the command, <B>unknown</B> generates an error return.
|
||||
If the global variable <B>auto_noload</B> is defined, then the auto-load
|
||||
step is skipped.
|
||||
If the global variable <B>auto_noexec</B> is defined then the
|
||||
auto-exec step is skipped.
|
||||
Under normal circumstances the return value from <B>unknown</B>
|
||||
is the return value from the command that was eventually
|
||||
executed.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/info.htm">info</A></B>, <B><A HREF="../TkCmd/proc.htm">proc</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#error">error</A>, <A href="../Keywords/N.htm#non-existent command">non-existent command</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
24
hlp/en/tcl/unset.htm
Normal file
24
hlp/en/tcl/unset.htm
Normal file
@@ -0,0 +1,24 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - unset manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
unset - Delete variables
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>unset </B><I>name </I>?<I>name name ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command removes one or more variables.
|
||||
Each <I>name</I> is a variable name, specified in any of the
|
||||
ways acceptable to the <B><A HREF="../TkCmd/set.htm">set</A></B> command.
|
||||
If a <I>name</I> refers to an element of an array then that
|
||||
element is removed without affecting the rest of the array.
|
||||
If a <I>name</I> consists of an array name with no parenthesized
|
||||
index, then the entire array is deleted.
|
||||
The <B>unset</B> command returns an empty string as result.
|
||||
An error occurs if any of the variables doesn't exist, and any variables
|
||||
after the non-existent one are not deleted.
|
||||
|
||||
<H3><A NAME="M5">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/R.htm#remove">remove</A>, <A href="../Keywords/V.htm#variable">variable</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
40
hlp/en/tcl/update.htm
Normal file
40
hlp/en/tcl/update.htm
Normal file
@@ -0,0 +1,40 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - update manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
update - Process pending events and idle callbacks
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>update</B> ?<B>idletasks</B>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command is used to bring the application ``up to date''
|
||||
by entering the event loop repeatedly until all pending events
|
||||
(including idle callbacks) have been processed.
|
||||
<P>
|
||||
If the <B>idletasks</B> keyword is specified as an argument to the
|
||||
command, then no new events or errors are processed; only idle
|
||||
callbacks are invoked.
|
||||
This causes operations that are normally deferred, such as display
|
||||
updates and window layout calculations, to be performed immediately.
|
||||
<P>
|
||||
The <B>update idletasks</B> command is useful in scripts where
|
||||
changes have been made to the application's state and you want those
|
||||
changes to appear on the display immediately, rather than waiting
|
||||
for the script to complete. Most display updates are performed as
|
||||
idle callbacks, so <B>update idletasks</B> will cause them to run.
|
||||
However, there are some kinds of updates that only happen in
|
||||
response to events, such as those triggered by window size changes;
|
||||
these updates will not occur in <B>update idletasks</B>.
|
||||
<P>
|
||||
The <B>update</B> command with no options is useful in scripts where
|
||||
you are performing a long-running computation but you still want
|
||||
the application to respond to events such as user interactions; if
|
||||
you occasionally call <B>update</B> then user input will be processed
|
||||
during the next call to <B>update</B>.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/after.htm">after</A></B>, <B><A HREF="../TkCmd/bgerror.htm">bgerror</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#event">event</A>, <A href="../Keywords/F.htm#flush">flush</A>, <A href="../Keywords/H.htm#handler">handler</A>, <A href="../Keywords/I.htm#idle">idle</A>, <A href="../Keywords/U.htm#update">update</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1990-1992 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
65
hlp/en/tcl/uplevel.htm
Normal file
65
hlp/en/tcl/uplevel.htm
Normal file
@@ -0,0 +1,65 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - uplevel manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
uplevel - Execute a script in a different stack frame
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>uplevel </B>?<I>level</I>?<I> arg </I>?<I>arg ...</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
All of the <I>arg</I> arguments are concatenated as if they had
|
||||
been passed to <B><A HREF="../TkCmd/concat.htm">concat</A></B>; the result is then evaluated in the
|
||||
variable context indicated by <I>level</I>. <B>Uplevel</B> returns
|
||||
the result of that evaluation.
|
||||
<P>
|
||||
If <I>level</I> is an integer then
|
||||
it gives a distance (up the procedure calling stack) to move before
|
||||
executing the command. If <I>level</I> consists of <B>#</B> followed by
|
||||
a number then the number gives an absolute level number. If <I>level</I>
|
||||
is omitted then it defaults to <B>1</B>. <I>Level</I> cannot be
|
||||
defaulted if the first <I>command</I> argument starts with a digit or <B>#</B>.
|
||||
<P>
|
||||
For example, suppose that procedure <B>a</B> was invoked
|
||||
from top-level, and that it called <B>b</B>, and that <B>b</B> called <B>c</B>.
|
||||
Suppose that <B>c</B> invokes the <B>uplevel</B> command. If <I>level</I>
|
||||
is <B>1</B> or <B>#2</B> or omitted, then the command will be executed
|
||||
in the variable context of <B>b</B>. If <I>level</I> is <B>2</B> or <B>#1</B>
|
||||
then the command will be executed in the variable context of <B>a</B>.
|
||||
If <I>level</I> is <B>3</B> or <B>#0</B> then the command will be executed
|
||||
at top-level (only global variables will be visible).
|
||||
<P>
|
||||
The <B>uplevel</B> command causes the invoking procedure to disappear
|
||||
from the procedure calling stack while the command is being executed.
|
||||
In the above example, suppose <B>c</B> invokes the command
|
||||
<PRE><B>uplevel 1 {set x 43; d}</B></PRE>
|
||||
where <B>d</B> is another Tcl procedure. The <B><A HREF="../TkCmd/set.htm">set</A></B> command will
|
||||
modify the variable <B>x</B> in <B>b</B>'s context, and <B>d</B> will execute
|
||||
at level 3, as if called from <B>b</B>. If it in turn executes
|
||||
the command
|
||||
<PRE><B>uplevel {set x 42}</B></PRE>
|
||||
then the <B><A HREF="../TkCmd/set.htm">set</A></B> command will modify the same variable <B>x</B> in <B>b</B>'s
|
||||
context: the procedure <B>c</B> does not appear to be on the call stack
|
||||
when <B>d</B> is executing. The command ``<B>info level</B>'' may
|
||||
be used to obtain the level of the current procedure.
|
||||
<P>
|
||||
<B>Uplevel</B> makes it possible to implement new control
|
||||
constructs as Tcl procedures (for example, <B>uplevel</B> could
|
||||
be used to implement the <B><A HREF="../TkCmd/while.htm">while</A></B> construct as a Tcl procedure).
|
||||
<P>
|
||||
<B>namespace eval</B> is another way (besides procedure calls)
|
||||
that the Tcl naming context can change.
|
||||
It adds a call frame to the stack to represent the namespace context.
|
||||
This means each <B>namespace eval</B> command
|
||||
counts as another call level for <B>uplevel</B> and <B><A HREF="../TkCmd/upvar.htm">upvar</A></B> commands.
|
||||
For example, <B>info level 1</B> will return a list
|
||||
describing a command that is either
|
||||
the outermost procedure call or the outermost <B>namespace eval</B> command.
|
||||
Also, <B>uplevel #0</B> evaluates a script
|
||||
at top-level in the outermost namespace (the global namespace).
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/namespace.htm">namespace</A></B>, <B><A HREF="../TkCmd/upvar.htm">upvar</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#context">context</A>, <A href="../Keywords/L.htm#level">level</A>, <A href="../Keywords/N.htm#namespace">namespace</A>, <A href="../Keywords/S.htm#stack frame">stack frame</A>, <A href="../Keywords/V.htm#variables">variables</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
93
hlp/en/tcl/upvar.htm
Normal file
93
hlp/en/tcl/upvar.htm
Normal file
@@ -0,0 +1,93 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - upvar manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
upvar - Create link to variable in a different stack frame
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>upvar </B>?<I>level</I>? <I>otherVar myVar </I>?<I>otherVar myVar </I>...?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command arranges for one or more local variables in the current
|
||||
procedure to refer to variables in an enclosing procedure call or
|
||||
to global variables.
|
||||
<I>Level</I> may have any of the forms permitted for the <B><A HREF="../TkCmd/uplevel.htm">uplevel</A></B>
|
||||
command, and may be omitted if the first letter of the first <I>otherVar</I>
|
||||
isn't <B>#</B> or a digit (it defaults to <B>1</B>).
|
||||
For each <I>otherVar</I> argument, <B>upvar</B> makes the variable
|
||||
by that name in the procedure frame given by <I>level</I> (or at
|
||||
global level, if <I>level</I> is <B>#0</B>) accessible
|
||||
in the current procedure by the name given in the corresponding
|
||||
<I>myVar</I> argument.
|
||||
The variable named by <I>otherVar</I> need not exist at the time of the
|
||||
call; it will be created the first time <I>myVar</I> is referenced, just like
|
||||
an ordinary variable. There must not exist a variable by the
|
||||
name <I>myVar</I> at the time <B>upvar</B> is invoked.
|
||||
<I>MyVar</I> is always treated as the name of a variable, not an
|
||||
array element. Even if the name looks like an array element,
|
||||
such as <B>a(b)</B>, a regular variable is created.
|
||||
<I>OtherVar</I> may refer to a scalar variable, an array,
|
||||
or an array element.
|
||||
<B>Upvar</B> returns an empty string.
|
||||
<P>
|
||||
The <B>upvar</B> command simplifies the implementation of call-by-name
|
||||
procedure calling and also makes it easier to build new control constructs
|
||||
as Tcl procedures.
|
||||
For example, consider the following procedure:
|
||||
<PRE><B>proc add2 name {
|
||||
upvar $name x
|
||||
set x [expr $x+2]
|
||||
}</B></PRE>
|
||||
<B>Add2</B> is invoked with an argument giving the name of a variable,
|
||||
and it adds two to the value of that variable.
|
||||
Although <B>add2</B> could have been implemented using <B><A HREF="../TkCmd/uplevel.htm">uplevel</A></B>
|
||||
instead of <B>upvar</B>, <B>upvar</B> makes it simpler for <B>add2</B>
|
||||
to access the variable in the caller's procedure frame.
|
||||
<P>
|
||||
<B>namespace eval</B> is another way (besides procedure calls)
|
||||
that the Tcl naming context can change.
|
||||
It adds a call frame to the stack to represent the namespace context.
|
||||
This means each <B>namespace eval</B> command
|
||||
counts as another call level for <B><A HREF="../TkCmd/uplevel.htm">uplevel</A></B> and <B>upvar</B> commands.
|
||||
For example, <B>info level 1</B> will return a list
|
||||
describing a command that is either
|
||||
the outermost procedure call or the outermost <B>namespace eval</B> command.
|
||||
Also, <B>uplevel #0</B> evaluates a script
|
||||
at top-level in the outermost namespace (the global namespace).
|
||||
<P>
|
||||
If an upvar variable is unset (e.g. <B>x</B> in <B>add2</B> above), the
|
||||
<B><A HREF="../TkCmd/unset.htm">unset</A></B> operation affects the variable it is linked to, not the
|
||||
upvar variable. There is no way to unset an upvar variable except
|
||||
by exiting the procedure in which it is defined. However, it is
|
||||
possible to retarget an upvar variable by executing another <B>upvar</B>
|
||||
command.
|
||||
|
||||
<H3><A NAME="M5">Traces and upvar</A></H3>
|
||||
Upvar interacts with traces in a straightforward but possibly
|
||||
unexpected manner. If a variable trace is defined on <I>otherVar</I>, that
|
||||
trace will be triggered by actions involving <I>myVar</I>. However,
|
||||
the trace procedure will be passed the name of <I>myVar</I>, rather
|
||||
than the name of <I>otherVar</I>. Thus, the output of the following code
|
||||
will be <B>localVar</B> rather than <B>originalVar</B>:
|
||||
<PRE><B>proc traceproc { name index op } {
|
||||
puts $name
|
||||
}
|
||||
proc setByUpvar { name value } {
|
||||
upvar $name localVar
|
||||
set localVar $value
|
||||
}
|
||||
set originalVar 1
|
||||
trace variable originalVar w traceproc
|
||||
setByUpvar originalVar 2
|
||||
}</B></PRE>
|
||||
If <I>otherVar</I> refers to an element of an array, then variable
|
||||
traces set for the entire array will not be invoked when <I>myVar</I>
|
||||
is accessed (but traces on the particular element will still be
|
||||
invoked). In particular, if the array is <B>env</B>, then changes
|
||||
made to <I>myVar</I> will not be passed to subprocesses correctly.
|
||||
|
||||
<H3><A NAME="M6">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/global.htm">global</A></B>, <B><A HREF="../TkCmd/namespace.htm">namespace</A></B>, <B><A HREF="../TkCmd/uplevel.htm">uplevel</A></B>, <B><A HREF="../TkCmd/variable.htm">variable</A></B>
|
||||
<H3><A NAME="M7">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/C.htm#context">context</A>, <A href="../Keywords/F.htm#frame">frame</A>, <A href="../Keywords/G.htm#global">global</A>, <A href="../Keywords/L.htm#level">level</A>, <A href="../Keywords/N.htm#namespace">namespace</A>, <A href="../Keywords/P.htm#procedure">procedure</A>, <A href="../Keywords/V.htm#variable">variable</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
55
hlp/en/tcl/variable.htm
Normal file
55
hlp/en/tcl/variable.htm
Normal file
@@ -0,0 +1,55 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - variable manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
variable - create and initialize a namespace variable
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>variable </B>?<I>name value...</I>? <I>name </I>?<I>value</I>?<BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command is normally used within a
|
||||
<B>namespace eval</B> command to create one or more variables
|
||||
within a namespace.
|
||||
Each variable <I>name</I> is initialized with <I>value</I>.
|
||||
The <I>value</I> for the last variable is optional.
|
||||
<P>
|
||||
If a variable <I>name</I> does not exist, it is created.
|
||||
In this case, if <I>value</I> is specified,
|
||||
it is assigned to the newly created variable.
|
||||
If no <I>value</I> is specified, the new variable is left undefined.
|
||||
If the variable already exists,
|
||||
it is set to <I>value</I> if <I>value</I> is specified
|
||||
or left unchanged if no <I>value</I> is given.
|
||||
Normally, <I>name</I> is unqualified
|
||||
(does not include the names of any containing namespaces),
|
||||
and the variable is created in the current namespace.
|
||||
If <I>name</I> includes any namespace qualifiers,
|
||||
the variable is created in the specified namespace. If the variable
|
||||
is not defined, it will be visible to the <B>namespace which</B>
|
||||
command, but not to the <B><A HREF="../TkCmd/info.htm">info exists</A></B> command.
|
||||
<P>
|
||||
If the <B>variable</B> command is executed inside a Tcl procedure,
|
||||
it creates local variables
|
||||
linked to the corresponding namespace variables (and therefore these
|
||||
variables are listed by <B><A HREF="../TkCmd/info.htm">info locals</A></B>.)
|
||||
In this way the <B>variable</B> command resembles the <B><A HREF="../TkCmd/global.htm">global</A></B> command,
|
||||
although the <B><A HREF="../TkCmd/global.htm">global</A></B> command
|
||||
only links to variables in the global namespace.
|
||||
If any <I>value</I>s are given,
|
||||
they are used to modify the values of the associated namespace variables.
|
||||
If a namespace variable does not exist,
|
||||
it is created and optionally initialized.
|
||||
<P>
|
||||
A <I>name</I> argument cannot reference an element within an array.
|
||||
Instead, <I>name</I> should reference the entire array,
|
||||
and the initialization <I>value</I> should be left off.
|
||||
After the variable has been declared,
|
||||
elements within the array can be set using ordinary
|
||||
<B><A HREF="../TkCmd/set.htm">set</A></B> or <B><A HREF="../TkCmd/array.htm">array</A></B> commands.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/global.htm">global</A></B>, <B><A HREF="../TkCmd/namespace.htm">namespace</A></B>, <B><A HREF="../TkCmd/upvar.htm">upvar</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/G.htm#global">global</A>, <A href="../Keywords/N.htm#namespace">namespace</A>, <A href="../Keywords/P.htm#procedure">procedure</A>, <A href="../Keywords/V.htm#variable">variable</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993-1997 Bell Labs Innovations for Lucent Technologies
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
32
hlp/en/tcl/vwait.htm
Normal file
32
hlp/en/tcl/vwait.htm
Normal file
@@ -0,0 +1,32 @@
|
||||
<HTML><HEAD><TITLE>Tcl Built-In Commands - vwait manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
vwait - Process events until a variable is written
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>vwait</B> <I>varName</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
This command enters the Tcl event loop to process events, blocking
|
||||
the application if no events are ready. It continues processing
|
||||
events until some event handler sets the value of variable
|
||||
<I>varName</I>. Once <I>varName</I> has been set, the <B>vwait</B>
|
||||
command will return as soon as the event handler that modified
|
||||
<I>varName</I> completes. <I>varName</I> must globally scoped
|
||||
(either with a call to <B><A HREF="../TkCmd/global.htm">global</A></B> for the <I>varName</I>, or with
|
||||
the full namespace path specification).
|
||||
<P>
|
||||
In some cases the <B>vwait</B> command may not return immediately
|
||||
after <I>varName</I> is set. This can happen if the event handler
|
||||
that sets <I>varName</I> does not complete immediately. For example,
|
||||
if an event handler sets <I>varName</I> and then itself calls
|
||||
<B>vwait</B> to wait for a different variable, then it may not return
|
||||
for a long time. During this time the top-level <B>vwait</B> is
|
||||
blocked waiting for the event handler to complete, so it cannot
|
||||
return either.
|
||||
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/global.htm">global</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/E.htm#event">event</A>, <A href="../Keywords/V.htm#variable">variable</A>, <A href="../Keywords/W.htm#wait">wait</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1996 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
44
hlp/en/tcl/while.htm
Normal file
44
hlp/en/tcl/while.htm
Normal file
@@ -0,0 +1,44 @@
|
||||
<HTML><HEAD><TITLE>Built-In Commands - while manual page</TITLE></HEAD><BODY>
|
||||
<H3><A NAME="M2">NAME</A></H3>
|
||||
while - Execute script repeatedly as long as a condition is met
|
||||
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||||
<B>while </B><I>test body</I><BR>
|
||||
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||||
The <B>while</B> command evaluates <I>test</I> as an expression
|
||||
(in the same way that <B><A HREF="../TkCmd/expr.htm">expr</A></B> evaluates its argument).
|
||||
The value of the expression must a proper boolean
|
||||
value; if it is a true value
|
||||
then <I>body</I> is executed by passing it to the Tcl interpreter.
|
||||
Once <I>body</I> has been executed then <I>test</I> is evaluated
|
||||
again, and the process repeats until eventually <I>test</I>
|
||||
evaluates to a false boolean value. <B><A HREF="../TkCmd/continue.htm">Continue</A></B>
|
||||
commands may be executed inside <I>body</I> to terminate the current
|
||||
iteration of the loop, and <B><A HREF="../TkCmd/break.htm">break</A></B>
|
||||
commands may be executed inside <I>body</I> to cause immediate
|
||||
termination of the <B>while</B> command. The <B>while</B> command
|
||||
always returns an empty string.
|
||||
<P>
|
||||
Note: <I>test</I> should almost always be enclosed in braces. If not,
|
||||
variable substitutions will be made before the <B>while</B>
|
||||
command starts executing, which means that variable changes
|
||||
made by the loop body will not be considered in the expression.
|
||||
This is likely to result in an infinite loop. If <I>test</I> is
|
||||
enclosed in braces, variable substitutions are delayed until the
|
||||
expression is evaluated (before
|
||||
each loop iteration), so changes in the variables will be visible.
|
||||
For an example, try the following script with and without the braces
|
||||
around <B>$x<10</B>:
|
||||
<PRE>set x 0
|
||||
while {$x<10} {
|
||||
puts "x is $x"
|
||||
incr x
|
||||
}</PRE>
|
||||
<H3><A NAME="M5">SEE ALSO</A></H3>
|
||||
<B><A HREF="../TkCmd/break.htm">break</A></B>, <B><A HREF="../TkCmd/continue.htm">continue</A></B>, <B><A HREF="../TkCmd/for.htm">for</A></B>, <B><A HREF="../TkCmd/foreach.htm">foreach</A></B>
|
||||
<H3><A NAME="M6">KEYWORDS</A></H3>
|
||||
<A href="../Keywords/B.htm#boolean value">boolean value</A>, <A href="../Keywords/L.htm#loop">loop</A>, <A href="../Keywords/T.htm#test">test</A>, <A href="../Keywords/W.htm#while">while</A>
|
||||
<HR><PRE>
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||||
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||||
</BODY></HTML>
|
||||
Reference in New Issue
Block a user