This appendix presents the same information available in the Tool
Command Language (Tcl) reference-manual entries ("man pages"); we
include it in the DejaGnu manual for convenient reference. The author
of Tcl, and of the reference-manual entries where this information
originally appeared, is John Ousterhout, of the University of California
at Berkeley (ouster@sprite.berkeley.edu).
The following copyright terms apply to the documentation in this Appendix:
Copyright (C) 1993 The Regents of the University of California. All rights reserved.
Permission is hereby granted, without written agreement and without license or royalty fees, to use, copy, modify, and distribute this documentation for any purpose, provided that the above copyright notice and the following two paragraphs appear in all copies.
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
The following rules define the syntax and semantics of the Tcl language:
") then the
word is terminated by the next double-quote character. If semicolons,
close brackets, or whitespace 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.
{) 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 semicolons, newlines, close brackets, or
whitespace have any special interpretation. The word will consist of
exactly the characters between the outer braces, not including the
braces themselves.
[) then Tcl performs command
substitution. 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.
$) then Tcl performs variable
substitution: the dollar-sign and the following characters are replaced
in the word by the value of a variable. Variable substition may take
any of the following forms:
$name
$name(index)
${name}
\) appears within a word then backslash substitution
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.
\a
0x7).
\b
0x8).
\f
0xc).
\n
0xa).
\r
0xd).
\t
0x9).
\v
0xb).
\newline whitespace
\\
\).
\ooo
\xhh
\newline as described above.
#) 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.
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 processor.
The command expr evaluates expressions with no further effect.
See section Evaluate an expression: expr. The conditional command
if, and two of the looping commands (for and while)
also evaluate Tcl expressions to test conditions.
For some examples of simple expressions, suppose the variable a
has the value 3 and the variable 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:
expr 3.1 + $a 6.1
expr 2 + "$a.$b" 5.6
expr 4*[llength "6 2"] 8
expr {{word one} < "word $a"} 0
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 `0'), or in hexadecimal (if the first two characters of the operand are `0x'). 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 `f', `F', `l', and `L' 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).
Operands may be specified in any of the following ways:
"). The expression parser
will perform backslash, variable, and command substitutions on the
information between the quotes, and use the resulting value as the
operand.
Where substitutions occur above (e.g. inside quoted strings), they are performed by the expression processor. 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.
The operators Tcl recognizes in expressions are listed below, grouped in decreasing order of precedence:
- ~ !
* / %
+ -
<< >>
< > <= >=
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.
== !=
&
^
|
&&
1 result if both operands are
non-zero, 0 otherwise. Valid for numeric operands only (integers
or floating-point).
||
0 result if both operands are zero,
1 otherwise. Valid for numeric operands only (integers or
floating-point).
x ? y : z
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
expr 4*2 < 7
returns 0.
The &&, ||, and ?: 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
expr {$v ? [a] : [b]}
only one of `[a]' or `[b]' will actually be evaluated,
depending on the value of `$v'. Note, however, that this is only
true if the entire expression is enclosed in braces; otherwise the Tcl
parser will evaluate both `[a]' and `[b]' before invoking the
expr command.
Tcl supports the following mathematical functions in expressions:
acos cos hypot sinh asin cosh log sqrt atan exp log10 tan atan2 floor pow tanh ceil fmod sin
Each of these functions invokes the C math library function of the same name; see the manual entries for the library functions for details on what they do. Tcl also implements the following functions for conversion between integers and floating-point numbers:
abs(arg)
double(arg)
int(arg)
round(arg)
All internal computations involving integers are done with the C type
long, and all internal computations involving floating-point are
done with the C type double. 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.
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,
expr 5 / 4
returns 1, while
expr 5 / 4.0 expr 5 / ( [string length "abcd"] + 0.0 )
both return 1.25. Floating-point values are always returned with
a `.' or an `e' so that they will not look like integer
values. For example,
expr 20.0/5.0
returns `4.0', not `4'. The global variable
tcl_precision determines the the number of significant digits
that are retained when floating values are converted to strings (except
that trailing zeroes are omitted). If tcl_precision is unset
then 6 digits of precision are used. To retain all of the significant
bits of an IEEE floating-point number set tcl_precision to
17; if a value is converted to string with 17 digits of precision
and then converted back to binary for some later calculation, the
resulting binary value is guaranteed to be identical to the original
one.
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 sprintf format specifier
`%d' for integers and `%g' for floating-point values. For
example, the commands
expr {"0x03" > "2"}
expr {"0y" < "0x12"}
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 `18'.
Here are descriptions of all the commands built into the Tcl language itself.
append@begingroup @let@nonarrowing=@comment
append varname value [ value ... ]
@endgroup
Append all of the value arguments to the current value of variable
varname. If varname doesn't exist, it is given a value
equal to the concatenation of all the value arguments. This
command provides an efficient way to build up long variables
incrementally. For example, `append a $b' is much more efficient
than `set a $a$b' if $a is long.
array@begingroup @let@nonarrowing=@comment
array option arrayname [ arg ... ]
@endgroup
This command performs one of several operations on the variable given by arrayname. arrayname must be the name of an existing array variable. The option argument determines what action is carried out by the command. The options (which may be abbreviated) are:
array names arrayname
array size arrayname
array startsearch arrayname
array nextelement arrayname srchid
array anymore arrayname srchid
1 if there are any more elements left to be processed in
an array search, 0 if all elements have already been returned.
srchid indicates which search on arrayname to check, and
must have been the return value from a previous invocation of
`array startsearch'. This option is particularly useful if an
array has an element with an empty name, since the return value from
`array nextelement' won't indicate whether the search has been
completed.
array donesearch arrayname srchid
break@begingroup @let@nonarrowing=@comment
break
@endgroup
This command may be invoked only inside the body of a looping command
such as for or foreach or while. It returns a
TCL_BREAK code to signal the innermost containing loop command to
return immediately.
case
case str [ in] patlist body [ patlist body ...]
case str [ in] {patlist body [ patlist body ...]}
Warning: the
casecommand is obsolete, and is supported only for backward compatibility. At some point in the future it may be removed entirely. You should use theswitchcommand instead.
The case command matches str against each of the
patlist arguments in order. Each patlist argument is a list
of one or more patterns. If any of these patterns matches str
then case evaluates the following body argument by passing
it recursively to the Tcl interpreter and returns the result of that
evaluation. Each patlist argument consists of a single pattern or
list of patterns. Each pattern may contain any of the wild-cards
described under `string match' (see section Manipulate strings: string). If a patlist argument is the word default,
the corresponding body will be evaluated if no patlist
matches str. If no patlist argument matches str and
no default is given, then the case command returns an empty
string.
Two syntaxes are provided for the patlist and body
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 case commands, since the braces around the whole list
make it unnecessary to include a backslash at the end of each line.
Since the patlist 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.
catch@begingroup @let@nonarrowing=@comment
catch script [ varname ]
@endgroup
The catch command may be used to prevent errors from aborting
command interpretation. catch calls the Tcl interpreter
recursively to execute script, and always returns a TCL_OK
code, regardless of any errors that might occur while executing
script. The return value from catch is a decimal string
giving the code returned by the Tcl interpreter after executing
script. This will be 0 (TCL_OK) if there were no errors in
script; otherwise it will have a non-zero value corresponding to
one of the exceptional return codes (see section Return from a procedure: return, for descriptions of exception code values).
If the varname argument is given, then it gives the name of a
variable; catch will set the variable to the string returned from
script (either a result or an error message).
cd@begingroup @let@nonarrowing=@comment
cd [ dirname ]
@endgroup
Change the current working directory to dirname, or to the home
directory (as specified in the HOME environment variable) if
dirname is not given. Returns an empty string.
If dirname starts with a tilde, then tilde-expansion is done: the
first element of dirname is replaced with the location of the home
directory for the given user. The substitution is carried out in the
same way that it would be done by csh. If the tilde is followed
immediately by a slash, then the HOME environment variable is
substituted. Otherwise the characters between the tilde and the next
slash are taken as a user name, which is looked up in the password file;
the user's home directory is retrieved from the password file and
substituted.
close@begingroup @let@nonarrowing=@comment
close fileid
@endgroup
Closes the file given by fileid. fileid must be the return
value from a previous invocation of the open command; after this
command, it should not be used anymore. If fileid refers to a
command pipeline instead of a file, then close waits for the children to
complete. The normal result of this command is an empty string, but
errors are returned if there are problems in closing the file or waiting
for children to complete.
concat@begingroup @let@nonarrowing=@comment
concat [ arg ... ]
@endgroup
This command treats each argument as a list and concatenates them into a single list. It also eliminates leading and trailing spaces in each arg and adds a single separator space between each arg. It permits any number of arguments. For example, the command
concat a b {c d e} {f {g h}}
will return as its result
a b c d e f {g h}
If no arg is supplied, the result is an empty string.
continue@begingroup @let@nonarrowing=@comment
continue
@endgroup
This command may be invoked only inside the body of a looping command
such as for or foreach or while. It returns a
TCL_CONTINUE code to signal the innermost containing loop command
to skip the remainder of the loop's body but continue with the next
iteration of the loop.
eof@begingroup @let@nonarrowing=@comment
eof fileid
@endgroup
Returns 1 if an end-of-file condition has occurred on fileid, 0
otherwise. fileid must be the return value from a previous call
to open, or it may be stdin, stdout, or
stderr to refer to one of the standard I/O channels.
error@begingroup @let@nonarrowing=@comment
error message [ info ] [ code ]
@endgroup
Returns a TCL_ERROR code, which causes command interpretation to
be unwound. message is a string that is returned to the
application to indicate what went wrong.
If the info argument is provided and is non-empty, it is used to
initialize the global variable errorInfo. errorInfo 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 errorInfo. If the info argument is present,
it is used to initialize errorInfo and the first increment of
unwind information will not be added by the Tcl interpreter. In other
words, the command containing the error command will not appear in
errorInfo; in its place will be info. This feature is most
useful in conjunction with the catch command. If a caught error
cannot be handled successfully, info can be used to return a stack
trace reflecting the original point of occurrence of the error:
catch { ... } errMsg
set savedInfo $errorInfo
...
error $errMsg $savedInfo
If the code argument is present, then its value is stored in the
errorCode global variable. This variable is intended to hold a
machine-readable description of the error in cases where such
information is available; see section Variables built into Tcl, for information on the proper format for the variable. If the
code argument is not present, then errorCode is
automatically reset to `NONE' by the Tcl interpreter as part of
processing the error generated by the command.
eval@begingroup @let@nonarrowing=@comment
eval arg [ arg ... ]
@endgroup
eval takes one or more arguments, which together comprise a Tcl
script containing one or more commands. eval concatenates all
its arguments in the same fashion as the concat command, passes
the concatenated string to the Tcl interpreter recursively, and returns
the result of that evaluation (or any error generated by it).
exec@begingroup @let@nonarrowing=@comment
exec [ opts ] arg [ arg ... ]
@endgroup
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 arg becomes one word of a command, and each distinct command becomes a subprocess.
If the initial arguments to exec start with `-' then they
are treated as command-line options and are not part of the pipeline
specification. The following options are currently supported:
-keepnewline
--
If an arg (or pair of arg strings) has one of the forms
described below then it is used by exec 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 `< fname'
fname may either be in a separate argument from `<' or in the
same argument with no intervening space (i.e. `<fname').
|
|&
< fname
<@ fileid
open. It is used as the standard
input for the first command in the pipeline. fileid must have
been opened for reading.
<< value
> fname
2> fname
>& fname
>> fname
2>> fname
>>& fname
> fileid
open. Standard output from the
last command is redirected to the corresponding file, which must have
been opened for writing.
2> fileid
open. Standard error from all
commands in the pipeline is redirected to the corresponding file. The
file must have been opened for writing.
>& fileid
open. Both standard output from
the last command and standard error from all commands are redirected to
the corresponding file. The file must have been opened for writing.
If standard output has not been redirected then the exec 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 exec will return an error and the error message
will include the pipeline's output followed by error messages describing
the abnormal terminations; the errorCode 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 exec 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.
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 `-keepnewline' is specified then the trailing newline is retained.
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.
If the last arg is `&' then the pipeline will be executed in
background. In this case the exec 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.
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 wildcard ("glob") expansion or other shell-like
substitutions are performed on the arguments to commands.
exit@begingroup @let@nonarrowing=@comment
exit [ returncode ]
@endgroup
Terminate the process, returning returncode to the system as the exit status. If returncode isn't specified then it defaults to 0.
expr@begingroup @let@nonarrowing=@comment
expr arg ?arg arg ...?
@endgroup
Concatenates arg'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
expr 8.2 + 6
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.
file@begingroup @let@nonarrowing=@comment
file opt fname [ arg ... ]
@endgroup
This command provides several operations on a file's name or attributes.
fname is the name of a file; if it starts with a tilde, then tilde
substitution is done before executing the command (as for cd;
see section Change working directory: cd). opt indicates
what to do with the file name. Any unique abbreviation for opt is
acceptable. The options currently implemented are:
file atime fname
file dirname fname
file executable fname
1 if file fname is executable by the current
user, 0 otherwise.
file exists fname
1 if file fname exists and the current user has
search privileges for the directories leading to it, 0 otherwise.
file extension fname
file isdirectory fname
1 if file fname is a directory, 0 otherwise.
file isfile fname
1 if file fname is a regular file, 0 otherwise.
file lstat fname varname
lstat kernel
call instead of stat. This means that if fname refers to a
symbolic link the information returned in varname 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 stat
option.
file mtime fname
file owned fname
1 if file fname is owned by the current user,
0 otherwise.
file readable fname
1 if file fname is readable by the current user,
0 otherwise.
file readlink fname
file rootname fname
file size fname
file stat fname varname
atime, ctime,
dev, gid, ino, mode, mtime,
nlink, size, type, uid. Each element except
type is a decimal string with the value of the corresponding
field from the stat return structure; see the operating system
reference manual entry for stat for details on the meanings of
the values. The type element gives the type of the file in the
same form returned by the command `file type'. This command
returns an empty string.
file tail fname
file type fname
file writable fname
1 if file fname is writable by the current user,
0 otherwise.
flush@begingroup @let@nonarrowing=@comment
flush fileid
@endgroup
Flushes any output that has been buffered for fileid.
fileid must be the return value from a previous call to
open, or it may be stdout or stderr to access one
of the standard I/O streams; it must refer to a file that was opened for
writing. The command returns an empty string.
for@begingroup @let@nonarrowing=@comment
for start tst nxt body
@endgroup
for is a looping command, similar in structure to the C
for statement. The start, nxt, and body
arguments must be Tcl command strings, and tst is an expression
string. The for command first invokes the Tcl interpreter to
execute start. Then it repeatedly evaluates tst as an
expression; if the result is non-zero it invokes the Tcl interpreter on
body, then invokes the Tcl interpreter on nxt, then repeats
the loop. The command terminates when tst evaluates to 0.
If a continue command is invoked within body then any
remaining commands in the current execution of body are skipped;
processing continues by invoking the Tcl interpreter on nxt, then
evaluating tst, and so on. If a break command is invoked
within body or nxt, then the for command will return
immediately. The operation of break and continue are
similar to the corresponding statements in C. for returns an
empty string.
foreach@begingroup @let@nonarrowing=@comment
foreach varname list body
@endgroup
In this command varname is the name of a variable, list is a
list of values to assign to varname, and body is a Tcl
script. For each element of list (in order from left to right),
foreach assigns the contents of the field to varname as if
the lindex command had been used to extract the field, then calls
the Tcl interpreter to execute body. The break and
continue statements may be invoked inside body, with the
same effect as in the for command. foreach returns an
empty string.
sprintf: format@begingroup @let@nonarrowing=@comment
format fstr [ arg ... ]
@endgroup
This command generates a formatted string in the same way as the
ANSI C sprintf procedure (it uses sprintf in its
implementation). fstr indicates how to format the result, using
`%' conversion specifiers as in sprintf, and the additional
arguments, if any, provide values to be substituted into the result.
The return value from format is the formatted string.
Details on formatting. The command operates by scanning
fstr 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 `%' then it is not copied to the result string.
Instead, the characters following the `%' character are treated as
a conversion specifier. The conversion specifier controls the
conversion of the next successive arg 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
arg. The format command must be given enough args to
meet the needs of all of the conversion specifiers in fstr.
Each conversion specifier may contain up to six different parts: an XPG3(6) 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.
If the `%' is followed by a decimal number and a `$', as in
`%2$d', 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 arg. If
the conversion specifier requires multiple arguments because of *
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 fstr, then all of the specifiers
must be positional.
The second portion of a conversion specifier may contain any of the following flag characters, in any order:
-
+
space
0
#
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
`0' and `-' 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 `*' rather than a number, then the next
argument to the format command determines the minimum field
width; it must be a numeric string.
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 `e', `E', and
`f' conversions it specifies the number of digits to appear to the
right of the decimal point. For `g' and `G' 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 # flag has been specified). For
integer conversions, it specifies a mimimum number of digits to print
(leading zeroes will be added if necessary). For s 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 `*' rather than a number then the
next argument to the format command determines the precision; it
must be a numeric string.
The fourth part of a conversion specifier is a length modifier, which must be `h' or `l'. If it is `h' it specifies that the numeric value should be truncated to a 16-bit value before converting. This option is rarely useful. The `l' modifier is ignored.
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:
d
u
i
o
x
X
c
s
f
e
E
g
G
%
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.
Differences from ANSI sprintf. The behavior of the
format command is the same as the ANSI C sprintf procedure
except for these differences:
double is
used for the internal representation). If the `h' modifier is
specified then integer values are truncated to short before
conversion.
gets@begingroup @let@nonarrowing=@comment
gets fileid [ varname ]
@endgroup
This command reads the next line from the file given by fileid and
discards the terminating newline character. If varname 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 read (not including
the newline). If the end of the file is reached before reading any
characters then `-1' is returned and varname is set to an
empty string. If varname is not specified then the return value
will be the line (minus the newline character) or an empty string if the
end of the file is reached before reading any characters. An empty
string will also be returned if a line contains no characters except the
newline, so eof may have to be used to determine what really
happened. If the last character in the file is not a newline character
then gets behaves as if there were an additional newline
character at the end of the file. fileid must be stdin or
the return value from a previous call to open; it must refer to a
file that was opened for reading. Any existing end-of-file or error
condition on the file is cleared at the beginning of the gets
command.
glob@begingroup @let@nonarrowing=@comment
glob [ opts ] ptrn [ ptrn ... ]
@endgroup
This command performs file name wildcard expansion ("globbing") in a
fashion similar to the csh shell. It returns a list of the files
whose names match any of the patterns specified as ptrn arguments.
If the initial arguments to glob start with `-' then they are treated as options. The following options are currently supported:
-nocomplain
--
The ptrn arguments may contain any of the following special characters:
?
*
[chars]
\x
{a,b,...}
As with csh, a `.' at the beginning of a filename or just
after a `/' must be matched explicitly or with a {...}
construct. In addition, all `/' characters must be matched
explicitly.
If the first character in a pattern 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.
The glob command differs from csh wildcard expansion in
two ways. First, it does not sort its result list (use the lsort
command if you want the list sorted). Second, glob only returns
the names of files that actually exist; in csh no check for
existence is made unless a pattern contains a `?', `*', or
`[...]' construct.
global@begingroup @let@nonarrowing=@comment
global varname [ varname ... ]
@endgroup
This command is ignored unless a Tcl procedure is being interpreted. If so then it declares each given varname listed to be a global variable, rather than a local one. For the duration of the current procedure (and only while executing in the current procedure), any reference to any varname will refer to the global variable by the same name.
history@begingroup @let@nonarrowing=@comment
history [ operation ] [ arg ... ]
@endgroup
The history 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 event. When specifying an event to the history command, the following forms may be used:
-1 refers to the
previous event, -2 to the one before that, and so on).
The history command can take any of the following forms:
history
history add command [ exec ]
exec is specified (or abbreviated) then the command is also
executed and its result is returned. If exec isn't specified
then an empty string is returned as result.
history change newval [ event ]
-1). 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.
history event [ event ]
-1. This command causes history revision to occur.
See section History revision, for details.
history info [ n ]
history keep n
history nextid
history redo [ evt ]
-1. This command results in history
revision. See section History revision, for details.
history substitute old new [ evt ]
-1 by default), replace
any occurrences of old by new in the command (only simple
character equality is supported; no wild cards), execute the resulting
command, and return the result of that execution. This command results
in history revision. See section History revision, for details.
history words sel [ evt ]
-1 by default) the
words given by sel, and return those words in a string separated
by spaces. The sel argument has three forms. If it is a single
number then it selects the word given by that number (0 for the
command name, 1 for its first argument, and so on). If it
consists of two numbers separated by a dash, then it selects all the
arguments between those two. Otherwise sel is treated as a
pattern; all words matching that pattern (in the sense of `string
match') are returned. In the numeric forms `$' may be used to
select the last word of a command. For example, suppose the most recent
command in the history list is
@begingroup
@let@nonarrowing=@comment
format {%s is %d years old} Alice [expr $ageInMonths/12]
@endgroup
Here are some history commands and the results they would produce (the
result of each command is shown indented below it):
history words $
[expr $ageInMonths/12]
history words 1-2
{%s is %d years old} Alice
history words *a*o*
{%s is %d years old} [expr $ageInMonths/12]
`history words' results in history revision.
The history options event, redo, substitute,
and words result in history revision. When one of these
options is invoked then the current event is modified to eliminate the
history command and replace it with the result of the
history command. For example, suppose that the most recent
command in the history list is
set a [expr $b+2]
and suppose that the next command invoked is one of the ones on the left side of the table below. The command actually recorded in the history event will be the corresponding one on the right side of the table.
history redo set a [expr $b+2] history s a b set b [expr $b+2] set c [history w 2] set c [expr $b+2]
History revision is needed because event specifiers like -1 are
only valid at a particular time: once more events have been added to the
history list a different event specifier would be needed. History
revision occurs even when history is invoked indirectly from the
current event (e.g. a user types a command that invokes a Tcl procedure
that invokes history): the top-level command whose execution
eventually resulted in a history command is replaced. If you
wish to invoke commands like `history words' without history
revision, you can use `history event' to save the current history
event and then use `history change' to restore it later.
if@begingroup @let@nonarrowing=@comment
if expr1 [ then ] body1 elseif expr2 [ then ] body2 elseif ... [ else ] [ bodyN ]
@endgroup
The if command evaluates expr1 as an expression (in the
same way that expr 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 `true' or `yes'
for true, and `false' or `no' for false); if it is true then
body1 is executed by passing it to the Tcl interpreter. Otherwise
expr2 is evaluated as an expression and if it is true then
body2 is executed, and so on. If none of the expressions
evaluates to true then bodyN is executed. The then and
else arguments are optional "noise words" to make the command
easier to read. There may be any number of elseif clauses,
including zero. bodyN may also be omitted as long as else
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 bodyN.
incr@begingroup @let@nonarrowing=@comment
incr varname [ n ]
@endgroup
Increments the value stored in the variable whose name is varname. The value of the variable must be an integer. If n is supplied then its value (which must also be an integer) is added to the value of variable varname; otherwise 1 is added to varname. The new value is stored as a decimal string in variable varname and also returned as result.
info@begingroup @let@nonarrowing=@comment
info op [ arg ... ]
@endgroup
This command provides information about various internals of the Tcl interpreter. Recognized values for op (which may be abbreviated) are:
info args procname
info body procname
info cmdcount
info commands [ ptn ]
proc command. If ptn
is specified, only those names matching ptn are returned.
Matching is determined using the same rules as for `string match'.
info complete cmd
1 if cmd 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.
info default procname arg varname
0. Otherwise it
returns 1 and places the default value of arg into variable
varname.
info exists varname
1 if the variable named varname exists in the
current context (either as a global or local variable); returns 0
otherwise.
info globals [ ptn ]
info level [ n ]
0 if the command is
invoked at top-level. If n (a number) is specified, then the
result is a list consisting of the name and arguments for the procedure
call at level n on the stack. If n 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 section Execute in another stack frame: uplevel, for more information on what
stack levels mean.
info library
TCL_LIBRARY environment
variable. If there is no TCL_LIBRARY variable and no compiled-in
value then an error is generated. See section Tcl standard library, for details of the facilities provided by the Tcl script
library. Normally each application will have its own
application-specific script library in addition to the Tcl script
library; I suggest that each application set a global variable with a
name like app_library (where app is the application's
name) to hold the location of that application's library directory.
info locals [ ptn ]
global and
upvar commands will not be returned. If ptn is specified,
only those names matching ptn are returned. Matching is
determined using the same rules as for `string match'.
info patchlevel
info procs [ ptn ]
proc; not built-in
commands). If ptn is specified, only those names matching
ptn are returned. Matching is determined using the same rules as
for `string match'.
info script
info tclversion
info vars [ ptn ]
join@begingroup @let@nonarrowing=@comment
join lst [ delim ]
@endgroup
The lst argument must be a valid Tcl list. This command returns the string formed by joining all of the elements of lst together with the string delim separating each adjacent pair of elements. The delim argument defaults to a space character.
lappend@begingroup @let@nonarrowing=@comment
lappend varname val [ val ... ]
@endgroup
This command treats the variable given by varname as a list and
appends each of the val arguments to that list as a separate
element, with spaces between elements. If varname doesn't exist,
it is created as a list with elements given by the val arguments.
lappend is similar to append except that the values are
appended as list elements rather than raw text. This command provides a
relatively efficient way to build up large lists. For example,
`lappend a $b' is much more efficient than `set a [concat $a
[list $b]]' when `$a' is long.
lindex@begingroup @let@nonarrowing=@comment
lindex lst ix
@endgroup
This command treats lst as a Tcl list and returns the element
indexed by ix from it (0 refers to the first element of the
list). In extracting the element, lindex 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 ix is negative or greater than or equal to the
number of elements in lst, then an empty string is returned.
linsert@begingroup @let@nonarrowing=@comment
linsert lst ix elt [ elt ... ]
@endgroup
This command produces a new list from lst by inserting all of the elt arguments just before the element at position ix of lst. Each elt argument will become a separate element of the new list. If ix is less than or equal to zero, then the new elements are inserted at the beginning of the list. If ix is greater than or equal to the number of elements in lst, then the new elements are appended to the list.
list@begingroup @let@nonarrowing=@comment
list [ arg ... ]
@endgroup
This command returns a list composed of all the arg values, or an
empty string if no arg is specified. Braces and backslashes get
added as necessary, so that the index command may be used on the
result to re-extract the original arguments, and also so that
eval may be used to execute the resulting list, with the first
arg comprising the command's name and the other args comprising
its arguments. list produces slightly different results than
concat: concat removes one level of grouping before
forming the list, while list works directly from the original
arguments. For example, the command
list a b {c d e} {f {g h}}
will return
a b {c d e} {f {g h}}
while concat with the same arguments will return
a b c d e f {g h}
llength@begingroup @let@nonarrowing=@comment
llength lst
@endgroup
Treats lst as a list and returns a decimal string giving the number of elements in it.
lrange@begingroup @let@nonarrowing=@comment
lrange lst first last
@endgroup
lst must be a valid Tcl list. This command will return a new list consisting of elements first through last, inclusive. last may be `end' (or any abbreviation of it) to refer to the last element of the list. If first is less than zero, it is treated as if it were zero. If last is greater than or equal to the number of elements in the list, then it is treated as if it were `end'. If first is greater than last then an empty string is returned. Note: `lrange lst first first' does not always produce the same result as `lindex lst first' (although it often does for simple fields that aren't enclosed in braces); it does, however, produce exactly the same results as `list [lindex lst first]'.
lreplace@begingroup @let@nonarrowing=@comment
lreplace lst first last [ elt ... ]
@endgroup
lreplace returns a new list formed by replacing one or more
elements of lst with the elt arguments. first gives
the index in lst of the first element to be replaced. If
first is less than zero then it refers to the first element of
lst; the element indicated by first must exist in the list.
last gives the index in lst of the last element to be
replaced; it must be greater than or equal to first. last
may be end (or any abbreviation of it) to indicate that all elements
between first and the end of the list should be replaced. The
elt arguments specify zero or more new arguments to be added to
the list in place of those that were deleted. Each elt argument
will become a separate element of the list. If no elt arguments
are specified, then the elements between first and last are
simply deleted.
lsearch@begingroup @let@nonarrowing=@comment
lsearch [ mode ] lst ptn
@endgroup
This command searches the elements of the list lst to see if one
of them matches ptn. If so, the command returns the index of the
first matching element. If not, the command returns -1. The
mode argument indicates how the elements of the list are to be
matched against ptn and it must have one of the following values:
-exact
-glob
-regexp
regexp command.
If mode is omitted then it defaults to `-glob'.
lsort@begingroup @let@nonarrowing=@comment
lsort [ opts ] lst
@endgroup
This command sorts the elements of a list lst, returning a new list in sorted order. By default ASCII sorting is used with the result returned in increasing order. However, any of the following options may be specified before lst to control the sorting process (unique abbreviations are accepted):
-ascii
-integer
-real
-command cmd
-increasing
-decreasing
open@begingroup @let@nonarrowing=@comment
open fname [ access ] [ perm ]
@endgroup
This command opens a file and returns an identifier that may be used in
future invocations of commands like read, puts, and
close. fname gives the name of the file to open; if it
starts with a tilde then tilde substitution is performed (see section Change working directory: cd). If the first character of
fname is `|' then the remaining characters of fname are
treated as a command pipeline to invoke, in the same style as for
exec. In this case, the identifier returned by open may
be used to write to the command's input pipe or read from its output
pipe.
The access argument indicates the way in which the file (or
command pipeline) is to be accessed. It may take two forms, either a
string in the form that would be passed to the fopen library
procedure or a list of POSIX access flags. It defaults to
`r'. In the first form access may have any of the following
values:
r
r+
w
w+
a
a+
In the second form, access 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 RDONLY, WRONLY or
RDWR.
RDONLY
WRONLY
RDWR
APPEND
CREAT
EXCL
CREAT is specified also, an error is returned if the file
already exists.
NOCTTY
NONBLOCK
open system call
O_NONBLOCK flag.
TRUNC
If a new file is created as part of opening it, perm (an integer)
is used to set the permissions for the new file in conjunction with the
process's file mode creation mask. perm defaults to 0666.
If a file is opened for both reading and writing then seek must be
invoked between a read and a write, or vice versa (this restriction does
not apply to command pipelines opened with open). When fname
specifies a command pipeline and a write-only access is used, then
standard output from the pipeline is directed to the current standard
output unless overridden by the command. When fname specifies a
command pipeline and a read-only access is used, then standard input
from the pipeline is taken from the current standard input unless
overridden by the command.
pid@begingroup @let@nonarrowing=@comment
pid [ fileid ]
@endgroup
If the fileid argument is given then it should normally refer to a
process pipeline created with the open command. In this case the
pid 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 fileid refers to an open file that isn't a
process pipeline. If no fileid argument is given then pid
returns the process identifier of the current process. All process
identifiers are returned as decimal strings.
proc@begingroup @let@nonarrowing=@comment
proc pname arglist body
@endgroup
The proc command creates a new Tcl procedure named pname,
replacing any existing command or procedure there may have been by that
name. Whenever the new command is invoked, the contents of body will be
executed by the Tcl interpreter. arglist 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.
When pname 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 args, 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
args are combined into a list (as if the list command had been used);
this combined value is assigned to the local variable args.
When body 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 global command or the upvar command.
The proc command returns an empty string. When a procedure is
invoked, the procedure's result is the value specified in a
return command. If the procedure doesn't execute an explicit
return, then its result 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.
puts@begingroup @let@nonarrowing=@comment
puts [ -nonewline ] [ fileid ] str
@endgroup
Writes the characters given by str to the file given by
fileid. fileid must have been the return value from a
previous call to open, or it may be stdout or
stderr to refer to one of the standard I/O channels; it must
refer to a file that was opened for writing. If no fileid is
specified then it defaults to stdout. puts normally
outputs a newline character after str, but this feature may be
suppressed by specifying the `-nonewline' switch. Output to files
is buffered internally by Tcl; the flush command may be used to
force buffered characters to be output.
pwd@begingroup @let@nonarrowing=@comment
pwd
@endgroup
Returns the path name of the current working directory.
read@begingroup @let@nonarrowing=@comment
read [ -nonewline ] fileid read fileid numbytes
@endgroup
In the first form, all of the remaining bytes are read from the file
given by fileid; they are returned as the result of the command.
If the `-nonewline' option 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 bytes to read; exactly this many bytes will
be read and returned, unless there are fewer than numbytes bytes
left in the file; in this case, all the remaining bytes are returned.
fileid must be stdin or the return value from a previous
call to open; it must refer to a file that was opened for
reading. Any existing end-of-file or error condition on the file is
cleared at the beginning of the read command.
regexp@begingroup @let@nonarrowing=@comment
regexp [ opts ] rexp str [ mvar ] [ subvar ... ]
@endgroup
Determines whether the regular expression rexp matches part or all
of the string str and returns 1 if it does, 0 if it
doesn't.
If additional arguments are specified after str then they are treated as the names of variables in which to return information about which parts of str matched rexp. mvar will be set to the range of str that matched all of rexp. The first subvar will contain the characters in str that matched the leftmost parenthesized subexpression within rexp, the next subvar will contain the characters that matched the next parenthesized subexpression to the right in rexp, and so on.
If the initial arguments to regexp start with `-' then they
are treated as options. The following options are currently supported:
-nocase
-indices
--
If there are more names in the subvar list than there are parenthesized subexpressions within rexp, or if a particular subexpression in rexp doesn't match the string (e.g. because it was in a portion of the expression that wasn't matched), then the corresponding subvar will be set to `-1 -1' if `-indices' has been specified or to an empty string otherwise.
Regular expressions are implemented using Henry Spencer's package (thanks, Henry!), and much of the description of regular expressions below is copied verbatim from his reference manual entry.
A regular expression is zero or more branches, separated by `|'. It matches anything that matches one of the branches.
A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc.
A piece is an atom possibly followed by `*', `+', or `?'. An atom followed by `*' matches a sequence of 0 or more matches of the atom. An atom followed by `+' matches a sequence of 1 or more matches of the atom. An atom followed by `?' matches a match of the atom, or the empty string.
An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), `.' (matching any single character), `^' (matching the empty string at the beginning of the input string), `$' (matching the empty string at the end of the input string), a `\' followed by a single character (matching that character), or a single character with no other significance (matching that character).
A range is a sequence of characters enclosed in `[]'. It normally matches any single character from the sequence. If the sequence begins with `^', it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by `-', this is shorthand for the full list of ASCII characters between them (e.g. `[0-9]' matches any decimal digit). To include a literal `]' in the sequence, make it the first character (following a possible `^'). To include a literal `-', make it the first or last character.
In general there may be more than one way to match a regular expression to an input string. For example, consider the command
regexp (a*)b* aabaaabb x y
Considering only the rules given so far, x and y could end
up with the values `aabb' and `aa', `aaab' and
`aaa', `ab' and `a', or any of several other
combinations. To resolve this potential ambiguity regexp chooses among
alternatives using the rule "first then longest". In other words, it
consders the possible matches in order working from left to right across
the input string and the pattern, and it attempts to match longer pieces
of the input string before shorter ones. More specifically, the
following rules apply in decreasing order of priority:
In the example above, `(a*)b*' matches `aab': the `(a*)' portion of the pattern is matched first and it consumes the leading `aa'; then the `b*' portion of the pattern consumes the next `b'. Or consider the following example:
regexp (ab|a)(b*)c abc x y z
After this command x will be `abc', y will be
`ab', and z will be an empty string. Rule 4 specifies that
`(ab|a)' gets first shot at the input string and Rule 2 specifies
that the `ab' subexpression is checked before the `a'
sub-expression. Thus the `b' has already been claimed before the
`(b*)' component is checked and `(b*)' must match an empty
string.
regsub@begingroup @let@nonarrowing=@comment
regsub [ opts ] rexp str repl varname
@endgroup
This command matches the regular expression rexp against
str, and it copies str to the variable whose name is given
by varname. The command returns 1 if there is a match and
0 if there isn't. If there is a match, then while copying
str to varname the portion of str that matched
rexp is replaced with repl. If repl contains a
`&' or `\0', that character or string is replaced in the
substitution with the portion of str that matched rexp. If
repl contains a `\n', where n is a digit between
1 and 9, then it is replaced in the substitution with the portion of
str that matched the nth parenthesized subexpression of
rexp. Additional backslashes may be used in repl to prevent
special interpretation of `&' or `\0' or `\n' or
backslash. The use of backslashes in repl tends to interact badly
with the Tcl parser's use of backslashes, so it's generally safest to
enclose repl in braces if it includes backslashes.
If the initial arguments to regsub start with `-' then they
are treated as options. The following options are currently supported:
-all
-nocase
--
See section Match a regular expression: regexp, for details on
the interpretation of regular expressions.
rename@begingroup @let@nonarrowing=@comment
rename oldname newname
@endgroup
Rename the command that used to be called oldname so that it is
now called newname. If newname is an empty string then
oldname is deleted. The rename command returns an empty
string as result.
return@begingroup @let@nonarrowing=@comment
return [ -code c ] [ -errorinfo i ] [ -errorcode e ] [ str ]
@endgroup
Return immediately from the current procedure (or top-level command or source command), with str as the return value. If str is not specified then an empty string will be returned as result.
Exceptional returns. In the usual case where the `-code'
option isn't specified the procedure will return normally (its
completion code will be TCL_OK). However, the `-code
c' option may be used to generate an exceptional return from the
procedure. c may have any of the following values:
ok
error
error command were used to terminate
the procedure, except for handling of errorInfo and
errorCode variables (see below).
return
TCL_RETURN, so that the procedure that invoked it will return
also.
break
TCL_BREAK, which will terminate the innermost nested loop in the
code that invoked the current procedure.
continue
TCL_CONTINUE, which will terminate the current iteration of the
innermost nested loop in the code that invoked the current procedure.
val
The `-code' option is rarely used. It is provided so that procedures that implement new control structures can reflect exceptional conditions back to their callers.
Two additional options, `-errorinfo' and `-errorcode', may be used to provide additional information during error returns. These options are ignored unless you specify `-code error'.
The `-errorinfo i' option specifies an initial stack trace
for the errorInfo variable; if it is not specified then the stack
trace left in errorInfo 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 value is supplied from the value left in errorInfo after
a catch command trapped an error within the procedure.
If the `-errorcode e' option is specified then e
provides a value for the errorCode variable. If the option is
not specified then errorCode will default to `NONE'.
sscanf: scan@begingroup @let@nonarrowing=@comment
scan str fmt varname [ varname ... ]
@endgroup
This command parses fields from an input string in the same fashion as
the ANSI C sscanf procedure and returns a count of the
number of fields sucessfully parsed. str gives the input to be
parsed and fmt indicates how to parse it, using `%'
conversion specifiers as in sscanf. Each varname gives the
name of a variable; when a field is scanned from str the result is
converted back into a string and assigned to the corresponding variable.
Details on scanning. scan operates by scanning str
and fmt together. If the next character in fmt is a blank
or tab then it is ignored. Otherwise, if it isn't a `%' character
then it must match the next non-white-space character of str.
When a `%' is encountered in fmt, it indicates the start of a
conversion specifier. A conversion specifier contains up to three
fields after the `%': a `*', which indicates that the
converted value is to be discarded instead of assigned to a variable; a
number indicating a maximum field width; and a conversion character.
All of these fields are optional except for the conversion character.
When scan finds a conversion specifier in fmt, it first skips any
white-space characters in str. 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 scan. The
following conversion characters are supported:
d
o
x
c
s
e
f
g
[chars]