COMMAND_NAME | X | NeoSoft, Inc. |
ABORT_PAGE - Neowebscript Aborts execution immediately Synopsis:
ACCESS_DATA_FILE | 2 | NeoSoft, Inc. |
APPEND | 3 | NeoSoft, Inc. |
Keywords: append, variable
ARRAY | 4 | NeoSoft, Inc. |
array anymore arrayName searchId
Returns 1 if there are any more elements left to be processed in an array search, 0 if all elements have already been returned. SearchId 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 searchId
This command terminates an array search and destroys all the state associated with that search. SearchId indicates which search on arrayName to destroy, and must have been the return value from a previous invocation of array startsearch. Returns an empty string.
array exists arrayName
Returns 1 if arrayName is an array variable, 0 if there is no variable by that name or if it is a scalar variable.
array get arrayName ?pattern?
Returns a list containing pairs of elements. The first element in each pair is the name of an element in arrayName and the second element of each pair is the value of the array element. The order of the pairs is undefined. If pattern is not specified, then all of the elements of the array are included in the result. If pattern is specified, then only those elements whose names match pattern (using the glob-style matching rules of string match) are included. If arrayName isn´t the name of an array variable, or if the array contains no elements, then an empty list is returned.
array names arrayName ?pattern?
Returns a list containing the names of all of the elements in the array that match pattern (using the glob-style matching rules of string match). If pattern 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 arrayName isn´t the name of an array variable, then an empty string is returned.
array nextelement arrayName searchId
Returns the name of the next element in arrayName, or an empty string if all elements of arrayName have already been returned in this search. The searchId argument identifies the search, and must have been the return value of an array startsearch command. Warning: if elements are added to or deleted from the array, then all searches are automatically terminated just as if array donesearch had been invoked; this will cause array nextelement operations to fail for those searches.
array set arrayName list
Sets the values of one or more elements in arrayName. list must have a form like that returned by array get, consisting of an even number of elements. Each odd-numbered element in list is treated as an element name within arrayName, and the following element in list is used as a new value for that array element.
array size arrayName
Returns a decimal string giving the number of elements in the array. If arrayName isn´t the name of an array then 0 is returned.
array startsearch arrayName
This command initializes an element-by-element search through the array given by arrayName, such that invocations of the array nextelement command will return the names of the individual elements in the array. When the search has been completed, the array donesearch command should be invoked. The return value is a search identifier that must be used in array nextelement and array donesearch commands; it allows multiple searches to be underway simultaneously for the same array.
See Also: bgerror Keywords: array, element names, search
BACKLINK | 5 | NeoSoft, Inc. |
See Also: bgerror Keywords: array, element names, search
BREAK | 6 | NeoSoft, Inc. |
See Also: bgerror Keywords: abort, break, loop
BSEARCH | 7 | NeoSoft, Inc. |
By default, the key is matched against the first white-space separated field in each line. The field is treated as an ASCII string. If compare_proc is specified, then it defines the name of a Tcl procedure to evaluate against each line read from the sorted file during the execution of the bsearch command. Compare_proc takes two arguments, the key and a line extracted from the file. The compare routine should return a number less than zero if the key is less than the line, zero if the key matches the line, or greater than zero if the key is greater than the line. The file must be sorted in ascending order according to the same criteria compare_proc uses to compare the key with the line, or erroneous results will occur.
See Also: bgerror Keywords: abort, break, loop
CASE | 8 | NeoSoft, Inc. |
The case command matches string 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 string 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. If a patList argument is default, the corresponding body will be evaluated if no patList matches string. If no patList argument matches string 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.
See Also: bgerror Keywords: case, match, regular expression
CATCH | 9 | NeoSoft, Inc. |
Note that catch catches all exceptions, including those generated by break and continue as well as errors.
See Also: bgerror Keywords: catch, error
CCOLLATE | 10 | NeoSoft, Inc. |
If -local is specified, the strings are compared according to the collation environment of the cur- rent locale.
See Also: bgerror Keywords: catch, error
CEQUAL | 11 | NeoSoft, Inc. |
See Also: bgerror Keywords: catch, error
CINDEX | 12 | NeoSoft, Inc. |
If the expression indexExpr starts with the string end, then end is replaced with the index of the last character in the string. If the expression starts with len, then len is replaced with the length of the string.
See Also: bgerror Keywords: catch, error
CLENGTH | 13 | NeoSoft, Inc. |
string length string
See Also: bgerror Keywords: catch, error
CLOCK | 14 | NeoSoft, Inc. |
clock clicks
Return a high-resolution time value as a systemdependent 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. This value should only be used for the relative measurement of elapsed time.
clock format clockValue ?-format string? ?-gmt boolean? Converts an integer time value, typically returned by clock seconds, clock scan, or the atime, mtime, or ctime options of the file command, to humanreadable form. If the -format 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 % followed by a field descriptor character. All other characters are copied into the result. Valid field descriptors are:
clock scan dateString ?-base clockVal? ?-gmt boolean? Convert dateString to an integer clock value (see clock seconds). 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 -gmt argument is true, in which case the clock value is calculated assuming that the specified time is relative to Greenwich Mean Time.
If the -base 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.
The dateString consists of zero or more specifications of the following form:
time A time of day, which is of the form: hh?:mm?:ss?? ?meridian? ?zone? or hhmm ?meridian? ?zone?. If no meridian is specified, hh is interpreted on a 24-hour clock.
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.
clock seconds
Return the current date and time as a systemdependent 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.
See Also: bgerror Keywords: clock, date, time
CLOSE | 15 | NeoSoft, Inc. |
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.
If channelId is a blocking channel for a command pipeline then close waits for the child processes to complete.
If the channel is shared between interpreters, then close makes channelId 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 close, the cleanup actions described above occur. See the interp command for a description of channel sharing.
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.
The command returns an empty string, and may generate an error if an error occurs while flushing output.
See Also: bgerror Keywords: blocking, channel, close, nonblocking
CMDTRACE | 16 | NeoSoft, Inc. |
See Also: bgerror Keywords: blocking, channel, close, nonblocking
CONCAT | 17 | NeoSoft, Inc. |
If no args are supplied, the result is an empty string.
See Also: bgerror Keywords: concatenate, join, lists
CONTINUE | 18 | NeoSoft, Inc. |
See Also: bgerror Keywords: continue, iteration, loop
CRANGE | 19 | NeoSoft, Inc. |
If the expression firstExpr or lastExpr starts with the string end, then end is replaced with the index of the last character in the string. If the expression starts with len, then len is replaced with the length of the string.
See Also: bgerror Keywords: continue, iteration, loop
CSUBSTR | 20 | NeoSoft, Inc. |
If the expression firstExpr or lengthExpr starts with the string end, then end is replaced with the index of the last character in the string. If the expression starts with len, then len is replaced with the length of the string.
See Also: bgerror Keywords: continue, iteration, loop
CTOKEN | 21 | NeoSoft, Inc. |
See Also: bgerror Keywords: continue, iteration, loop
CTYPE | 22 | NeoSoft, Inc. |
ctype ?-failindex var? alnum string Tests that all characters are alphabetic or numeric characters as defined by the character set.
ctype ?-failindex var? alpha string Tests that all characters are alphabetic char- acters as defined by the character set.
ctype ?-failindex var? ascii string Tests that all characters are an ASCII charac- ter (a non-negative number less than 0200).
ctype char number Converts the numeric value, string, to an ASCII character. Number must be in the range 0 through 255.
ctype ?-failindex var? cntrl string Tests that all characters are "control char- acters" as defined by the character set.
ctype ?-failindex var? digit string Tests that all characters are valid decimal digits, i.e. 0 through 9.
ctype ?-failindex var? graph string Tests that all characters within are any char- acter for which ctype print is true, except for space characters.
ctype ?-failindex var? lower string Tests that all characters are lowercase let- ters as defined by the character set.
ctype ord character Convert a character into its decimal numeric value. The first character of the string is converted.
ctype ?-failindex var? space string Tests that all characters are either a space, horizontal-tab, carriage return, newline, ver- tical-tab, or form-feed.
ctype ?-failindex var? print string Tests that all characters are a space or any character for which ctype alnum or ctype punct is true or other "printing character" as defined by the character set.
ctype ?-failindex var? punct string Tests that all characters are made up of any of the characters other than the ones for which alnum, cntrl, or space is true.
ctype ?-failindex var? upper string Tests that all characters are uppercase let- ters as defined by the character set.
ctype ?-failindex var? xdigit string Tests that all characters are valid hexadeci- mal digits, that is 0 through 9, a through f or A through F.
If -failindex is specified, then the index into string of the first character that did not match the class is returned in var.
See Also: bgerror Keywords: continue, iteration, loop
DBDELKEY | 23 | NeoSoft, Inc. |
See Also: bgerror Keywords: continue, iteration, loop
DBEXISTS | 24 | NeoSoft, Inc. |
See Also: bgerror Keywords: continue, iteration, loop
DBFETCH | 25 | NeoSoft, Inc. |
If -singleVar is specified, then arrayName will be treated as the name of a variable to store the results of the lookup. This should be used with dbstore, when -singleVar is used.
See Also: bgerror Keywords: continue, iteration, loop
DBFILES | 26 | NeoSoft, Inc. |
See Also: bgerror Keywords: continue, iteration, loop
DBKEYS | 27 | NeoSoft, Inc. |
See Also: bgerror Keywords: continue, iteration, loop
DBSTORE | 28 | NeoSoft, Inc. |
If -singleVar is specified, then arrayName will be treated as a single value, and that value will be stored under the key given.
See Also: bgerror Keywords: continue, iteration, loop
DELETE_DATA_FILE | 29 | NeoSoft, Inc. |
See Also: bgerror Keywords: continue, iteration, loop
DIRECTORY_LISTING | 30 | NeoSoft, Inc. |
See Also: bgerror Keywords: continue, iteration, loop
DUMP_ENVIRONMENT | 31 | NeoSoft, Inc. |
See Also: bgerror Keywords: continue, iteration, loop
EMIT_STANDARD_ MAGELLAN_SEARCH_LINK | 32 | NeoSoft, Inc. |
See Also: bgerror Keywords: continue, iteration, loop
EMIT_STANDARD_ YAHOO_LINK | 33 | NeoSoft, Inc. |
See Also: bgerror Keywords: continue, iteration, loop
EOF | 34 | NeoSoft, Inc. |
See Also: bgerror Keywords: channel, end of file
ERROR | 35 | NeoSoft, Inc. |
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 the tclvars manual page 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.
See Also: bgerror Keywords: error, errorCode, errorInfo
ESTIMATE_HITS_PER_HOUR | 36 | NeoSoft, Inc. |
See Also: bgerror Keywords: error, errorCode, errorInfo
EVAL | 37 | NeoSoft, Inc. |
See Also: bgerror Keywords: concatenate, evaluate, script
EXPR | 38 | NeoSoft, Inc. |
OPERANDS
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. 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 floatingpoint number if that is possible. Floating-point numbers may be specified in any of the ways accepted by an ANSIcompliant 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:
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:
+ - Add and subtract. Valid for any numeric operands.
<< >> Left and right shift. Valid for integer operands only. A right shift always propogates the sign bit.
< > <= >= 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.
== != Boolean equal and not equal. Each operator produces a zero/one result. Valid for all operand types.
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.
MATH FUNCTIONS
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 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)
Returns the absolute value of arg. Arg may be either integer or floating-point, and the result is returned in the same form.
double(arg)
If arg is a floating value, returns arg, otherwise converts arg to floating and returns the converted value.
int(arg)
If arg is an integer value, returns arg, otherwise converts arg to integer by truncation and returns the converted value.
round(arg)
If arg is an integer value, returns arg, otherwise converts arg to integer by rounding and returns the converted value.
In addition to these predefined functions, applications may define additional functions using Tcl_CreateMathFunc().
TYPES, OVERFLOW, AND PRECISION
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 OPERATIONS
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". Because of Tcl´s tendency to treat values as numbers whenever possible, it isn´t generally a good idea to use operators like == when you really want string comparison and the values of the operands could be arbi
See Also: bgerror Keywords: arithmetic, boolean, compare, expression
FCONFIGURE | 39 | NeoSoft, Inc. |
The options described below are supported for all channels. In addition, each channel type may add options that only it supports.
platform
nel according to the platform on which the application is executing; for sockets on all platforms Tcl chooses crlf, for all Unix flavors, it chooses lf, for the Macintosh platform it chooses cr and for the various flavors of Windows it chooses crlf.
auto In this mode Tcl sets the translation mode based on the first valid end-of-line sequence it sees during input on the channel. If output is generated for the channel before an end-of-line sequence has appeared on input, then Tcl uses platform mode for the channel. The default setting for -translation is auto.
See Also: close, flush, gets, puts, read Keywords: blocking, buffering, carriage return, end of line, flushing, linemode, newline, nonblocking, platform, translation
FILEMV | 40 | NeoSoft, Inc. |
See Also: close, flush, gets, puts, read Keywords: blocking, buffering, carriage return, end of line, flushing, linemode, newline, nonblocking, platform, translation
FILERM | 41 | NeoSoft, Inc. |
See Also: close, flush, gets, puts, read Keywords: blocking, buffering, carriage return, end of line, flushing, linemode, newline, nonblocking, platform, translation
FLOCK | 42 | NeoSoft, Inc. |
The following options are recognized:
-read - Place a read lock on the file. Multiple processes may be accessing the file with read- locks.
-write - Place a write lock on the file. Only one process may be accessing a file if there is a write lock.
-nowait - If specified, then the process will not block if the lock can not be obtained. With this option, the command returns 1 if the lock is obtained and 0 if it is not.
See your system´s fcntl system call documentation for full details of the behavior of file locking. If locking is being done on ranges of a file, it is best to use unbuffered file access (see the fcntl command).
See Also: close, flush, gets, puts, read Keywords: blocking, buffering, carriage return, end of line, flushing, linemode, newline, nonblocking, platform, translation
FLUSH | 43 | NeoSoft, Inc. |
See Also: open, socket Keywords: blocking, buffer, channel, flush, nonblocking, output
FOR | 44 | NeoSoft, Inc. |
See Also: open, socket Keywords: for, iteration, looping
FOREACH | 45 | NeoSoft, Inc. |
In the general case there can be more than one value list (e.g., list1 and list2), and each value list can be associated with a list of loop variables (e.g., varlist1 and varlist2). During each iteration of the loop the variables of each varlist are assigned consecutive values from the corresponding list. Values in each list 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.
The break and continue statements may be invoked inside body, with the same effect as in the for command. Foreach returns an empty string.
EXAMPLES
The following loop uses i and j as loop variables to iterate over pairs of elements of a single list.
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.
The next loop uses i and j to iterate over two lists in parallel.
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.
The two forms are combined in the following example.
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.
See Also: open, socket Keywords: foreach, iteration, list, looping
FORMAT | 46 | NeoSoft, Inc. |
DETAILS ON FORMATTING
The command operates by scanning formatString 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 formatString.
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.
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 formatString 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:
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 minimum 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 fifth 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:
DIFFERENCES FROM ANSI SPRINTF
The behavior of the format command is the same as the ANSI C sprintf procedure except for the following differences:
[1]
%p and %n specifiers are not currently supported.
See Also: open, socket Keywords: conversion specifier, format, sprintf, string, substitution
FSTAT | 47 | NeoSoft, Inc. |
The following keys are used to identify data items:
If stat arrayvar is specified, then the information is returned in the array arrrayvar. Each of the above keys indexes an element of the array contain- ing the data.
If only fileId is specified, the command returns the data as a keyed list.
The following values may be returned only if explicitly asked for, it will not be returned with the array or keyed list forms:
See Also: open, socket Keywords: conversion specifier, format, sprintf, string, substitution
FUNLOCK | 48 | NeoSoft, Inc. |
See Also: open, socket Keywords: conversion specifier, format, sprintf, string, substitution
GET_AVG_NC | 49 | NeoSoft, Inc. |
See Also: open, socket Keywords: conversion specifier, format, sprintf, string, substitution
GET_INIT_NC | 50 | NeoSoft, Inc. |
See Also: open, socket Keywords: conversion specifier, format, sprintf, string, substitution
GET_NC | 51 | NeoSoft, Inc. |
See Also: open, socket Keywords: conversion specifier, format, sprintf, string, substitution
GET_REAL_NC | 52 | NeoSoft, Inc. |
See Also: open, socket Keywords: conversion specifier, format, sprintf, string, substitution
GETS | 53 | NeoSoft, Inc. |
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 channelId 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 varName is specified and an empty string is returned in varName because of end-of-file or because of insufficient data in nonblocking mode, then the return count is -1. Note that if varName 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 eof and fblocked commands can be used to distinguish these three cases.
See Also: eof, fblocked Keywords: blocking, channel, end of file, end of line, line, nonblocking, read
GLOBAL | 54 | NeoSoft, Inc. |
See Also: eof, fblocked Keywords: global, procedure, variable
GM_TIMESTR_822 | 55 | NeoSoft, Inc. |
See Also: eof, fblocked Keywords: global, procedure, variable
HISTORY | 56 | NeoSoft, Inc. |
history
Same as history info, described below.
history add command ?exec?
Adds the command argument to the history list as a new event. If 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 newValue ?event?
Replaces the value recorded for an event with newValue. Event specifies the event to replace, and defaults to the current event (not 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?
Returns the value of the event given by event. Event defaults to -1. This command causes history revision to occur: see below for details.
history info ?count?
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 count is specified then only the most recent count events are returned.
history keep count
This command may be used to change the size of the history list to count events. Initially, 20 events are retained in the history list. This command returns an empty string.
history nextid
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.
history redo ?event?
Re-executes the command indicated by event and return its result. Event defaults to -1. This command results in history revision: see below for details.
history substitute old new ?event?
Retrieves the command given by event (-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 below for details.
history words selector ?event?
Retrieves from the command given by event (-1 by default) the words given by selector, and return those words in a string separated by spaces. The selector 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 selector 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 format {%s is %d years old} Alice [expr $ageInMonths/12]
Below are some history commands and the results they would produce:
History words results in history revision: see below for details.
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.
Command_Typed Command_Recorded
See Also: eof, fblocked Keywords: event, history, record, revision
HTML | 57 | NeoSoft, Inc. |
See Also: eof, fblocked Keywords: event, history, record, revision
ID | 58 | NeoSoft, Inc. |
id user ?name?
id userid ?uid? Set the real and effective user ID to name or uid, if the name (or uid) is valid and permis- sions allow it. If the name (or uid) is not specified, the current name (or uid) is returned.
id convert userid uid
id convert user name Convert a user ID number to a user name, or vice versa.
id group ?name?
id groupid ?gid? Set the real and effective group ID to name or gid, if the name (or gid) is valid and permis- sions allow it. If the group name (or gid) is not specified, the current group name (or gid) is returned.
id groups
id groupids Return the current group access list of the process. The option groups returns group names and groupids returns id numbers.
id convert groupid gid
id convert group name Convert a group ID number to a group name, or vice versa.
id effective user
id effective userid Return the effective user name, or effective user ID number, respectively.
id effective group
id effective groupid Return the effective group name, or effective group ID number, respectively. id effective groupids Return all of the groupids the user is a mem- ber of.
id host Return the hostname of the system the program is running on.
id process Return the process ID of the current process.
id process parent Return the process ID of the parent of the current process.
id process group Return the process group ID of the current process.
id process group set Set the process group ID of the current pro- cess to its process ID.
id host Returns the standard host name of the machine the process is executing on.
See Also: eof, fblocked Keywords: event, history, record, revision
IF | 59 | NeoSoft, Inc. |
See Also: eof, fblocked Keywords: boolean, conditional, else, false, if, true
IMAGE_CREATE | 60 | NeoSoft, Inc. |
Returns a file handle which writes to the cache for the given name. Name must be a file name relative to the current directory. The user should close the file when finished with it using the \"close\" command. The old image, if any, is already destroyed when this call returns.
Expire-seconds defines the number of seconds the image may be delivered from the server cache before it becomes invalid.
For further info, see the Gd command set
See Also: eof, fblocked Keywords: boolean, conditional, else, false, if, true
IMAGE_EXPIRE | 61 | NeoSoft, Inc. |
Turns on server-side caching for the current image being generated, and sets an expiration time on the cache to seconds. (0 is a valid value for seconds, and will cause it to always be expired.) Cached files are served out obeying the \"If-modified-since\" header, allowing for client-side caching as well.
For further info, see the Gd command set
See Also: eof, fblocked Keywords: boolean, conditional, else, false, if, true
IMAGE_OPEN | 62 | NeoSoft, Inc. |
Return a file handle for image name. Name refers to a file in the current directory, including the extension (usually .gd). Makes it possible to access previously generated images. If name is empty, then a handle to the previsouly cached image for the current URI is returned. The user should close the file when finished with it using the \"close\" command. The implementation takes special care not to destroy the old copy of the current image until the current image has been generated.
For further info, see the Gd command set
See Also: eof, fblocked Keywords: boolean, conditional, else, false, if, true
IMPORT_KEYVALUE_PAIRS | 63 | NeoSoft, Inc. |
Example: import_keyvalue_pairs foo "-action paint -customer fred"
Will set element action of array foo to paint and element customer to fred.
The normal usage would be to get optional key-value pairs as arguments to a proc, as in:
proc sell_item {customer item args} {
import_keyvalue_pairs options $args
.
.
}
This will pull an arbitrary number of optional key-value pairs, read into the args list when the proc began execution (because of the special meaning Tcl attaches to this keyword in argument lists), and store the key-value pairs into the options array.
See Also: eof, fblocked Keywords: boolean, conditional, else, false, if, true
INCLUDE_FILE | 64 | NeoSoft, Inc. |
Description Copy the contents of the specified file into the webpage being generated. File must be in the same directory or somewhere beneath the current directory. If the filename matches the MIME type for a server side include, the server side include is still performed. If it also contains embedded NeoWebScript, the NeoWebScript is executed. If the owner of the current page and the page being included are the same, the code is executed within the same safe interpreter that´s handling the current page. If the file is owned by someone else, it gets its own interpreter for its neoscript.
See Also: eof, fblocked Keywords: boolean, conditional, else, false, if, true
INCLUDE_VIRTUAL | 65 | NeoSoft, Inc. |
Description Copy the contents of the file named by the specified virtual path (rooted from the htdocs directory) into the webpage currently being generated.
Matching MIME types and processing embedded requests proceeds as for include_file above.
See Also: eof, fblocked Keywords: boolean, conditional, else, false, if, true
INCR | 66 | NeoSoft, Inc. |
See Also: eof, fblocked Keywords: add, increment, variable, value
INCR_NC | 67 | NeoSoft, Inc. |
On the first incr_nc call of a new day, a new daily-count record is created automatically.
See Also: eof, fblocked Keywords: add, increment, variable, value
INCR_PAGE_COUNTER | 68 | NeoSoft, Inc. |
See Also: eof, fblocked Keywords: add, increment, variable, value
INFO | 69 | NeoSoft, Inc. |
info args procname
Returns a list containing the names of the arguments to procedure procname, in order. Procname must be the name of a Tcl command procedure.
info body procname
Returns the body of procedure procname. Procname must be the name of a Tcl command procedure.
info cmdcount
Returns a count of the total number of commands that have been invoked in this interpreter.
info commands ?pattern?
If pattern isn´t specified, returns a list of names of all the Tcl commands, including both the builtin commands written in C and the command procedures defined using the proc command. If pattern is specified, only those names matching pattern are returned. Matching is determined using the same rules as for string match.
info complete command
Returns 1 if command 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
Procname must be the name of a Tcl command procedure and arg must be the name of an argument to that procedure. If arg doesn´t have a default value then the command returns 0. Otherwise it returns 1 and places the default value of arg into variable varname.
info exists varName
Returns 1 if the variable named varName exists in the current context (either as a global or local variable), returns 0 otherwise.
info globals ?pattern?
If pattern isn´t specified, returns a list of all the names of currently-defined global variables. If pattern is specified, only those names matching pattern are returned. Matching is determined using the same rules as for string match.
info hostname
Returns the name of the computer on which this invocation is being executed.
info level ?number?
If number is not specified, this command returns a number giving the stack level of the invoking procedure, or 0 if the command is invoked at toplevel. If number is specified, then the result is a list consisting of the name and arguments for the procedure call at level number on the stack. If number 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 uplevel command for more information on what stack levels mean.
info library
Returns the name of the library directory in which standard Tcl scripts are stored. This is actually the value of the tcl_library variable and may be changed by setting tcl_library. See the tclvars manual entry for more information.
info loaded
?interp?
Returns a list describing all of the packages that have been loaded into interp with the load 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. Interp defaults to the current interpreter.
info locals ?pattern?
If pattern 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 global and upvar commands will not be returned. If pattern is specified, only those names matching pattern are returned. Matching is determined using the same rules as for string match.
info
nameofexecutable
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.
info
patchlevel
Returns the value of the global variable tcl_patchLevel; see the tclvars manual entry for more information.
info procs ?pattern?
If pattern isn´t specified, returns a list of all the names of Tcl command procedures. If pattern is specified, only those names matching pattern are returned. Matching is determined using the same rules as for string match.
info script
If a Tcl script file is currently being evaluated (i.e. there is a call to Tcl_EvalFile active or there is an active invocation of the source command), then this command returns the name of the innermost file being processed. Otherwise the command returns an empty string.
info
sharedlibextension
Returns the extension used on this platform for the names of files containing shared libraries (for example, .so under Solaris). If shared libraries aren´t supported on this platform then an empty string is returned.
info
tclversion
Returns the value of the global variable tcl_version; see the tclvars manual entry for more information.
info vars ?pattern?
If pattern isn´t specified, returns a list of all the names of currently-visible variables, including both locals and currently-visible globals. If pattern is specified, only those names matching pattern are returned. Matching is determined using the same rules as for string match.
See Also: eof, fblocked Keywords: command, information, interpreter, level, procedure, variable
INFOX | 70 | NeoSoft, Inc. |
version Return the version number of Extended Tcl. The version number for Extended Tcl is gener- ated by combining the base version of the standard Tcl code with a letter indicating the version of Extended Tcl being used. This is the documentation for version 7.4a.
patchlevel Return the patchlevel for Extended Tcl.
have_fchown Return 1 if the fchown system call is avail- able. This supports the -fileid option on the chown and chgrp commands.
have_fchmod Return 1 if the fchmod system call is avail- able. This supports the -fileid option on the chmod command.
have_flock Return 1 if the flock command defined, 0 if it is not available.
have_fsync Return 1 if the fsync system call is available and the sync command will sync individual files. 0 if it is not available and the sync command will always sync all file buffers.
have_ftruncate Return 1 if the ftruncate or chsize system call is available. If it is, the ftruncate command -fileid option maybe used.
have_msgcats Return 1 if XPG message catalogs are avail- able, 0 if they are not. The catgets is designed to continue to function without mes- sage catalogs, always returning the default string.
have_posix_signals Return 1 if Posix signals are available (block and unblock options available for the signal command). 0 is returned if Posix signals are not available. have_truncate Return 1 if the truncate system call is avail- able. If it is, the ftruncate command may truncate by file path.
have_waitpid Return 1 if the waitpid system call is avail- able and the wait command has full functional- ity. 0 if the wait command has limited func- tionality.
appname Return the symbolic application name of the current application linked with the Extended Tcl library. The C variable tclAppName must be set by the application to return an appli- cation specific value for this variable.
applongname Return a natural language name for the current application. The C variable tclLongAppName must be set by the application to return an application specific value for this variable.
appversion Return the version number for the current application. The C variable tclAppVersion must be set by the application to return an application-specific value for this variable.
apppatchlevel Return the patchlevel for the current applica- tion. The C variable tclAppPatchlevel must be set by the application to return an applica- tion-specific value for this variable.
See Also: eof, fblocked Keywords: command, information, interpreter, level, procedure, variable
INTERP | 71 | NeoSoft, Inc. |
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 alias. An alias 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 env 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 open 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.
The interp command also provides support for safe 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 removed from safe interpreters. See SAFE INTERPRETERS below for more information on what features are present in a safe interpreter. The alias mechanism can be used for protected communication (analogous to a kernel call) between a slave interpreter and its master.
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 a is a slave of the current interpreter and it has a slave a1, which in turn has a slave a11, the qualified name of a11 in a is the list {a1 a11}.
The interp command, described below, accepts qualified interpreter names as arguments; the interpreter in which the command is being evaluated can always be referred to as {} (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.
The interp command is used to create, delete, and manipulate slave interpreters. It can have any of several forms, depending on the option argument:
interp alias srcPath srcCmd
Returns a Tcl list whose elements are the targetCmd and args associated with the alias named srcCmd (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 srcCmd if it was renamed).
interp alias srcPath srcCmd {}
Deletes the alias for srcCmd in the slave interpreter identified by srcPath. srcCmd refers to the name under which the alias was created; if the source command has been renamed, the renamed command will be deleted.
interp alias srcPath srcCmd targetPath targetCmd ?arg arg ...?
This command creates an alias between one slave and another (see the alias 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. SrcPath and srcCmd identify the source of the alias. SrcPath is a Tcl list whose elements select a particular interpreter. For example, "a b" identifies an interpreter b, which is a slave of interpreter a, which is a slave of the invoking interpreter. An empty list specifies the interpreter invoking the command. srcCmd gives the name of a new command, which will be created in the source interpreter. TargetPath and targetCmd specify a target interpreter and command, and the arg arguments, if any, specify additional arguments to targetCmd which are prepended to any arguments specified in the invocation of srcCmd. TargetCmd 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.
interp aliases ?path?
This command returns a Tcl list of the names of all the source commands for aliases defined in the interpreter identified by path.
interp create ?-safe? ?--? ?path?
Creates a slave interpreter identified by path and a new command, called a slave command. The name of the slave command is the last component of path. The new slave interpreter and the slave command are created in the interpreter identified by the path obtained by removing the last component from path. For example, if path is "a b c" then a new slave interpreter and slave command named "c" are created in the interpreter identified by the path "a b". The slave command may be used to manipulate the new interpreter as described below. If path is omitted, Tcl creates a unique name of the form interpx, where x is an integer, and uses it for the interpreter and the slave command. If the -safe 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 -- switch can be used to mark the end of switches; it may be needed if path is an unusual value such as -safe. 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.
interp delete ?path ...?
Deletes zero or more interpreters given by the optional path arguments, and for each interpreter, it also deletes its slaves. The command also deletes the slave command for each interpreter deleted. For each path argument, if no interpreter by that name exists, the command raises an error.
interp eval path arg ?arg ...?
This command concatenates all of the arg arguments in the same fashion as the concat command, then evaluates the resulting string as a Tcl script in the slave interpreter identified by path. The result of this evaluation (including error information such as the errorInfo and errorCode variables, if an error occurs) is returned to the invoking interpreter.
interp exists path
interp share srcPath channelId destPath Causes the IO channel identified by channelId to become shared between the interpreter identified by srcPath and the interpreter identified by destPath. 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.
interp slaves ?path?
Returns a Tcl list of the names of all the slave interpreters associated with the interpreter identified by path. If path is omitted, the invoking interpreter is used.
interp target path alias
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 interp alias 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.
interp transfer srcPath channelId destPath Causes the IO channel identified by channelId to become available in the interpreter identified by destPath and unavailable in the interpreter identified by srcPath.
SLAVE COMMAND
For each slave interpreter created with the interp 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: slave command ?arg arg ...?
Slave is the name of the interpreter, and command and the args determine the exact behavior of the command. The valid forms of this command are:
slave aliases
Returns a Tcl list whose elements are the names of all the aliases in slave. The names returned are the srcCmd 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).
slave alias srcCmd
Returns a Tcl list whose elements are the targetCmd and args associated with the alias named srcCmd (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 srcCmd if it was renamed).
slave alias srcCmd {}
Deletes the alias for srcCmd in the slave interpreter. srcCmd refers to the name under which the alias was created; if the source command has been renamed, the renamed command will be deleted.
slave alias srcCmd targetCmd ?arg ..?
Creates an alias such that whenever srcCmd is invoked in slave, targetCmd is invoked in the master. The arg arguments will be passed to targetCmd as additional arguments, prepended before any arguments passed in the invocation of srcCmd. See ALIAS INVOCATION below for details.
slave eval arg ?arg ..?
This command concatenates all of the arg arguments in the same fashion as the concat command, then evaluates the resulting string as a Tcl script in slave. The result of this evaluation (including error information such as the errorInfo and errorCode variables, if an error occurs) is returned to the invoking interpreter.
slave issafe
Returns 1 if the slave interpreter is safe, 0 otherwise.
ALIAS INVOCATION
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.
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 targetCmd and args for the alias to create a new array of arguments. If the words of srcCmd were "srcCmd arg1 arg2 ... argN", the new set of words will be "targetCmd arg arg ... arg arg1 arg2 ... argN", where targetCmd and args are the values supplied when the alias was created. TargetCmd 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 targetCmd 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: targetCmd and args were substituted when parsing the command that created the alias, and arg1 - argN are substituted when the alias´s source command is parsed in the source interpreter.
When writing the targetCmds 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.
SAFE INTERPRETERS
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 exec 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.
A safe interpreter is created by specifying the -safe switch to the interp create command. Furthermore, any slave created by a safe interpreter will also be safe.
A safe interpreter is created with exactly the following set of built-in commands:
append array break case catch clock close concat continue eof error eval
In addition, the env variable is not present in a safe interpreter, so it cannot share environment variables with other interpreters. The env 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 PGPPASS. Making this variable available to untrusted code executing in a safe interpreter would incur a security risk.
If extensions are loaded into a safe interpreter, they may also restrict their own functionality to eliminate unsafe commands. The management of extensions for safety will be explained in the manual entries for the package and load Tcl commands.
See Also: load, package, Tcl_CreateSlave Keywords: alias, master interpreter, safe interpreter, slave interpreter
JOIN | 72 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, join, list, separator
KEYLDEL | 73 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, join, list, separator
KEYLGET | 74 | NeoSoft, Inc. |
If retvar is specified and key is in the list, then the value is returned in the variable retvar and the command returns 1 if the key was present within the list. If key isn´t in the list, the command will return 0, and retvar will be left unchanged. If {} is specified for retvar, the value is not returned, allowing the Tcl programmer to determine if a key is present in a keyed list without setting a variable as a side-effect.
If key is omitted, then a list of all the keys in the keyed list is returned.
See Also: load, package, Tcl_CreateSlave Keywords: element, join, list, separator
KEYLKEYS | 75 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, join, list, separator
KEYLSET | 76 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, join, list, separator
LAPPEND | 77 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: append, element, list, variable
LASSIGN | 78 | NeoSoft, Inc. |
For example,
lassign {dave 100 200 {Dave Foo}} name uid gid longName
Assigns name to "dave", uid to "100", gid to "200", and longName to "Dave Foo".
See Also: load, package, Tcl_CreateSlave Keywords: append, element, list, variable
LEMPTY | 79 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: append, element, list, variable
LINDEX | 80 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, index, list
LINSERT | 81 | NeoSoft, Inc. |
Description This command produces a new list from list by inserting all of the element arguments just before the indexth element of list. Each element argument will become a separate element of the new list. If index is less than or equal to zero, then the new elements are inserted at the beginning of the list. If index has the value end, 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.
See Also: load, package, Tcl_CreateSlave Keywords: element, insert, list
LIST | 82 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list
LIST_DATA_FILES | 83 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list
LLENGTH | 84 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, length
LMATCH | 85 | NeoSoft, Inc. |
The mode argument indicates how the elements of the list are to be matched against pattern and it must have one of the following values:
-exact The list element must contain exactly the same string as pattern.
-glob Pattern is a glob-style pattern which is matched against each list element using the same rules as the string match command.
-regexp Pattern is treated as a regular expression and matched against each list element using the same rules as the regexp command.
If mode is omitted then it defaults to -glob.
See Also: load, package, Tcl_CreateSlave Keywords: element, list, length
LOAD_COOKIES | 86 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, length
LOAD_FILE | 87 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, length
LOAD_MIME_RESPONSE | 88 | NeoSoft, Inc. |
uploadedDataVar is the name of an array, indexed by field name, in which to place information about the files uploaded. The information stored in the array is a list as follows:
The return value of load_mime_response is a list of field names (or else an empty string) which may be used as arguments to open_mime_file.
Note that an additional program, webunpack must be compiled to support file uploads. Webunpack is derived munpack, (C) Copyright 1993,1994 by Carnegie Mellon University, All Rights Reserved, ftp.andrew.cmu.edu:pub/mpack/
See Also: load, package, Tcl_CreateSlave Keywords: element, list, length
LOAD_RESPONSE | 89 | NeoSoft, Inc. |
If the same name is repeated in the post or query,
response(__name) is set, and response(name) is converted
to a list. Use
[info exists response(__name)]
to check if the
array member is a straight value or a list.
If multiple response is expected (as in <select multiple>), use multiList to force the array members of the response array to always be a list.
See Also: load, package, Tcl_CreateSlave Keywords: element, list, length
LOAD_VIRTUAL | 90 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, length
LOG_MESSAGE | 91 | NeoSoft, Inc. |
MINIMAL_DNS
selected) fetching the
page.
If you need something fancier you can always roll your own with access_data_file.
See Also: load, package, Tcl_CreateSlave Keywords: element, list, length
LOOP | 92 | NeoSoft, Inc. |
The var argument is the name of a Tcl variable that will contain the loop index. The loop index is set to the value specified by first. The Tcl interpreter is invoked upon body zero or more times, where var is incremented by increment every time through the loop, or by one if increment is not specified. Increment can be negative in which case the loop will count downwards.
When var reaches limit, the loop terminates without a subsequent execution of body. For instance, if the original loop parameters would cause loop to terminate, say first was one, limit was zero and increment was not specified or was non-negative, body is not executed at all and loop returns.
The first, limit and increment are integer expres- sions. They are only evaulated once at the begin- ning of the loop.
If a continue command is invoked within body then any remaining commands in the current execution of body are skipped, as in the for command. If a break command is invoked within body then the loop command will return immediately. Loop returns an empty string.
See Also: load, package, Tcl_CreateSlave Keywords: element, list, length
LRANGE | 93 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, range, sublist
LREPLACE | 94 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, replace
LSEARCH | 95 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: list, match, pattern, regular expression, search, string
LSORT | 96 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
LVARCAT | 97 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
LVARPOP | 98 | NeoSoft, Inc. |
If the expression indexExpr starts with the string end, then end is replaced with the index of the last element in the list. If the expression starts with len, then len is replaced with the length of the list.
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
LVARPUSH | 99 | NeoSoft, Inc. |
If the expression indexExpr starts with the string end, then end is replaced with the index of the last element in the list. If the expression starts with len, then len is replaced with the length of the list. Note the a value of end means insert the string before the last element.
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
MAKE_NC_REGISTRY | 100 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
MAX | 101 | NeoSoft, Inc. |
This functionality is also available as a math function max in the Tcl expr command.
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
MD5 | 102 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
MIN | 103 | NeoSoft, Inc. |
This functionality is also available as a math function min in the Tcl expr command.
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
NEO_CLOCK_TO_RFC850_GMT | 104 | NeoSoft, Inc. |
Description Returns the passed integer-since-1970 time formatted according to RFC-850, with the additional proviso that it be specified in GMT timezone only. (Because that´s the way Netscape wanted it.)
For example, neo_clock_to_rfc850_gmt 84236782
should produce "Fri, 01-Sep-72 18:06:22 GMT".
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
NEO_MAKE_COOKIE | 105 | NeoSoft, Inc. |
Example: neo_make_cookie email karl@neosoft.com -days 30 -path /myApp
Create a cookie named email containing karl@neosoft.com that will be included in all HTTP requests from the browser we´re responding to, for a period of 30 days, when the requests are underneath/myApp on this server, and the browser is cookie-enabled.
For more information, see Persistent Client State HTTP Cookies at Netscape, and also Which Browsers Support Cookies at Digital.
This only works with Netscape if it´s emitted before any other HTML. It uses <meta http-equiv> to set the cookie, and won´t work with browsers that don´t support this.
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
NEOTRACK | 106 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
NEOTRACK_REPORT | 107 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
OPEN_OUTBOUND_MAIL | 108 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
OPEN_POST_NEWS | 109 | NeoSoft, Inc. |
When done writing the body of the news article, write a single line to the filehandle consisting only of a single period, then close the file.
Note that for this to work you must have a news server within your domain named or aliased as news. For example, within neosoft.com, open_post_news will try to contact the news server at news.neosoft.com.
This is an experimental capability that obviously needs work.
See Also: load, package, Tcl_CreateSlave Keywords: element, list, order, sort
PACKAGE | 110 | NeoSoft, Inc. |
The behavior of the package command is determined by its first argument. The following forms are permitted:
package forget package
Removes all information about package from this interpreter, including information provided by both package ifneeded and package provide.
package ifneeded package version ?script? 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 script. The script is saved in a database for
package provide package ?version?
This command is invoked to indicate that version version of package package is now present in the interpreter. It is typically invoked once as part of an ifneeded script, and again by the package itself when it is finally loaded. An error occurs if a different version of package has been provided by a previous package provide command. If the version argument is omitted, then the command returns the version number that is currently provided, or an empty string if no package provide command has been invoked for package in this interpreter.
package require ?-exact? package ?version? 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 -exact switch and the version argument are specified then only the given version is acceptable. If -exact is omitted but version is specified, then versions later than version are also acceptable as long as they have the same major version number as version. If both -exact and version are omitted then any version whatsoever is acceptable. If a version of package has already been provided (by invoking the package provide command), then its version number must satisfy the criteria given by -exact and version and the command returns immediately. Otherwise, the command searches the database of information provided by previous package ifneeded 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 package provide for the package. If the package ifneeded database does not contain an acceptable version of the package and a package unknown 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 package ifneeded script for it. If all of these steps fail to provide an acceptable version of the package, then the command returns an error.
package unknown ?command?
This command supplies a "last resort" command to invoke during package require if no suitable version of a package can be found in the package ifneeded database. If the command argument is supplied, it contains the first part of a command; when the command is invoked during a package require command, Tcl appends two additional arguments giving the desired package name and version. For example, if command is foo bar and later the command package require test 2.4 is invoked, then Tcl will execute the command foo bar test 2.4 to load the package. If no version number is supplied to the package require command, then the version argument for the invoked command will be an empty string. If the package unknown command is invoked without a command argument, then the current package unknown script is returned, or an empty string if there is none. If command is specified as an empty string, then the current package unknown script is removed, if there is one.
package vcompare version1 version2
Compares the two version numbers given by version1 and version2. Returns -1 if version1 is an earlier version than version2, 0 if they are equal, and 1 if version1 is later than version2.
package versions package
Returns a list of all the version numbers of package for which information has been provided by package ifneeded commands.
package vsatisfies version1 version2
Returns 1 if scripts written for version2 will work unchanged with version1 (i.e. version1 is equal to or greater than version2 and they both have the same major version number), 0 otherwise.
VERSION NUMBERS
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.
PACKAGE INDICES
The recommended way to use packages in Tcl is to invoke package require and package provide commands in scripts, and use the procedure pkg_mkIndex to create package index files. Once you´ve done this, packages will be loaded automatically in response to package require commands. See the documentation for pkg_mkIndex for details.
See Also: load, package, Tcl_CreateSlave Keywords: package, version
PARRAY | 111 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: package, version
PID | 112 | NeoSoft, Inc. |
See Also: load, package, Tcl_CreateSlave Keywords: file, pipeline, process identifier
PROC | 113 | NeoSoft, Inc. |
When name 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 return value is the value specified in a return command. If the procedure doesn´t execute an explicit return, 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.
See Also: load, package, Tcl_CreateSlave Keywords: argument, procedure
PROFILE | 114 | NeoSoft, Inc. |
The on option enables profile data collection. If the -commands option is specifed, data on all com- mands within a procedure is collected as well a procedures. Multiple occurrences of a command within a procedure are not distinguished, but this data may still be useful for analysis.
The off option turns off profiling and moves the data collected to the array arrayVar. The array is address by a list containing the procedure call stack. Element zero is the top of the stack, the procedure that the data is for. The data in each entry is a list consisting of the procedure call count and the real time and CPU time in millisec- onds spent in the procedure (and all procedures it called). The list is in the form {count real cpu}. A Tcl procedure profrep is supplied for reducing the data and producing a report
See Also: load, package, Tcl_CreateSlave Keywords: argument, procedure
PUTS | 115 | NeoSoft, Inc. |
Newline characters in the output are translated by puts to platform-specific end-of-line sequences according to the current value of the -translation 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 fconfigure manual entry for a discussion of end-ofline translations.
Tcl buffers output internally, so characters written with puts 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 flush command.
When the output buffer fills up, the puts command will normally block until all the buffered data has been accepted for output by the operating system. If channelId is in nonblocking mode then the puts 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 fileevent command (don´t invoke puts unless you have recently been notified via a file event that the channel is ready for more output data).
See Also: fileevent Keywords: channel, newline, output, write
REPLICATE | 116 | NeoSoft, Inc. |
See Also: fileevent Keywords: channel, newline, output, write
RANDOM_PICK_HTML | 117 | NeoSoft, Inc. |
See Also: fileevent Keywords: channel, newline, output, write
READ | 118 | NeoSoft, Inc. |
If channelId is in nonblocking mode, the command may not read as many bytes as requested: once all available input has been read, the command will return the data that is available rather than blocking for more input. The -nonewline switch is ignored if the command returns before reaching the end of the file.
Read translates end-of-line sequences in the input into newline characters according to the -translation option for the channel. See the manual entry for fconfigure for details on the -translation option.
See Also: eof, fblocked, fconfigure Keywords: blocking, channel, end of line, end of file, nonblocking, read, translation
REGEXP | 119 | NeoSoft, Inc. |
If additional arguments are specified after string then they are treated as the names of variables in which to return information about which part(s) of string matched exp. MatchVar will be set to the range of string that matched all of exp. The first subMatchVar will contain the characters in string that matched the leftmost parenthesized subexpression within exp, the next subMatchVar will contain the characters that matched the next parenthesized subexpression to the right in exp, and so on.
If the initial arguments to regexp start with - then they are treated as switches. The following switches are currently supported:
REGULAR EXPRESSIONS
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 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 null 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 null string at the beginning of the input string), "$" (matching the null 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.
CHOOSING AMONG ALTERNATIVE MATCHES
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 considers 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:
See Also: eof, fblocked, fconfigure Keywords: match, regular expression, string
REGISTER_NC | 120 | NeoSoft, Inc. |
See Also: eof, fblocked, fconfigure Keywords: match, regular expression, string
REGSUB | 121 | NeoSoft, Inc. |
If the initial arguments to regexp start with - then they are treated as switches. The following switches are currently supported:
See Also: eof, fblocked, fconfigure Keywords: match, pattern, regular expression, substitute
REMOTE_HOSTNAME | 122 | NeoSoft, Inc. |
If ip-address is provided, then it attempts to resolve the given IP. Warning: resolution failures can take a long time and make a page callup slow.
See Also: eof, fblocked, fconfigure Keywords: match, pattern, regular expression, substitute
RENAME | 123 | NeoSoft, Inc. |
See Also: eof, fblocked, fconfigure Keywords: command, delete, rename
REPLICATE | 124 | NeoSoft, Inc. |
See Also: eof, fblocked, fconfigure Keywords: command, delete, rename
RETURN | 125 | NeoSoft, Inc. |
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 option may be used to generate an exceptional return from the procedure. Code may have any of the following values:
ok
Normal return: same as if the option is omitted.
error
Error return: same as if the error command were used to terminate the procedure, except for handling of errorInfo and errorCode variables (see below).
return
The current procedure will return with a completion code of TCL_RETURN, so that the procedure that invoked it will return also.
break
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.
continue
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.
value
Value must be an integer; it will be returned as the completion code for the current procedure.
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 code is error.
The -errorinfo 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 info value is supplied from the value left in errorInfo after a catch command trapped an error within the procedure.
If the -errorcode option is specified then code provides a value for the errorCode variable. If the option is not specified then errorCode will default to NONE.
See Also: eof, fblocked, fconfigure Keywords: break, continue, error, procedure, return
SAVE_MIME_FILE | 126 | NeoSoft, Inc. |
See Also: eof, fblocked, fconfigure Keywords: break, continue, error, procedure, return
SCAN | 127 | NeoSoft, Inc. |
When scan finds a conversion specifier in formatString, it first skips any white-space characters in string. 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:
[chars] The input field consists of any number of characters in chars. The matching string is stored in the variable. If the first character between the brackets is a ] then it is treated as part of chars rather than the closing bracket for the set.
[^chars] The input field consists of any number of characters not in chars. The matching string is stored in the variable. If the character immediately following the ^ is a ] then it is treated as part of the set rather than the closing bracket for the set.
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 %d, as many octal digits as possible for %o, 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 * is present in the conversion specifier then no variable is assigned and the next scan argument is not consumed.
DIFFERENCES FROM ANSI SSCANF
The behavior of the scan command is the same as the behavior of the ANSI C sscanf procedure except for the following differences:
See Also: eof, fblocked, fconfigure Keywords: conversion specifier, parse, scan
SCANCONTEXT | 128 | NeoSoft, Inc. |
scancontext create Create a new scan context. The scanmatch command is used to define patterns in the context. A con- texthandle is returned, which the Tcl programmer uses to refer to the newly created scan context in calls to the Tcl file scanning commands.
scancontext delete contexthandle Delete the scan context identified by contex- thandle, and free all of the match statements and compiled regular expressions associated with the specified context.
scancontext copyfile contexthandle ?filehandle? Set or return the file handle that unmatched lines are copied to. (See scanfile). If filehandle is omitted, the copy file handle is returned. If no copy file is associated with the context, {} is returned. If a file handle is specified, it becomes the copy file for this context. If file- handle is {}, then it removes any copy file speci- fication for the context.
See Also: eof, fblocked, fconfigure Keywords: conversion specifier, parse, scan
SCANFILE | 129 | NeoSoft, Inc. |
If the optional -copyfile argument is specified, the next argument is a file ID to which all lines not matched by any pattern (excluding the default pattern) are to be written. If the copy file is specified with this flag, instead of using the scancontext copyfile command, the file is disasso- ciated from the scan context at the end of the scan.
See Also: eof, fblocked, fconfigure Keywords: conversion specifier, parse, scan
SCANMATCH | 130 | NeoSoft, Inc. |
If regexp is not specified, then a default match is specified for the scan context. The default match will be executed when a line of the file does not match any of the regular expressions in the current scancontext.
The array matchInfo is available to the Tcl code that is executed when an expression matches (or defaults). It contans information about the file being scanned and where within it the expression was matched.
matchInfo is local to the top level of the match command unless declared global at that level by the Tcl global command. If it is to be used as a global, it must be declared global before scanfile is called (since scanfile sets the matchInfo before the match code is executed, a subsequent global will override the local variable). The following array entries are available:
matchInfo(line) Contains the text of the line of the file that was matched.
matchInfo(offset) The byte offset into the file of the first character of the line that was matched.
matchInfo(linenum) The line number of the line that was matched. This is relative to the first line scanned, which is usually, but not necessarily, the first line of the file. The first line is line number one.
matchInfo(context) The context handle of the context that this scan is associated with.
matchInfo(handle) The file id (handle) of the file currently being scanned.
matchInfo(copyHandle) The file id (handle) of the file specified by the -copyfile option. The element does not exist if -copyfile was not specified.
matchInfo(submatch0) Will contain the characters matching the first parenthesized subexpression. The second will be contained in submatch1, etc.
matchInfo(subindex0) Will contain the a list of the starting and ending indices of the string matching the first parenthesized subexpression. The second will be contained in subindex1, etc.
All scanmatch patterns that match a line will be processed in the order in which their specifications were added to the scan context. The remainder of the scanmatch pattern- command pairs may be skipped for a file line if a continue is executed by the Tcl code of a preceding, matched pat- tern.
If a return is executed in the body of the match command, the scanfile command currently in progress returns, with the value passed to return as its return value.
See Also: eof, fblocked, fconfigure Keywords: conversion specifier, parse, scan
SEEK | 131 | NeoSoft, Inc. |
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.
See Also: eof, fblocked, fconfigure Keywords: access position, file, seek
SELECT | 132 | NeoSoft, Inc. |
The files specified by the readFileIds list are checked to see if data is available for reading. The writeFileIds are checked if the specified files are clear for writing. The exceptFileIds are checked to see if an exceptional condition has occured (typically, an error). The write and exception checking is most useful on devices, how- ever, the read checking is very useful when commu- nicating with multiple processes through pipes. Select considers data pending in the stdio input buffer for read files as being ready for reading, the files do. not have to be unbuffered.
Timeout is a floating point timeout value, in sec- onds. If an empty list is supplied (or the parame- ter is omitted), then no timeout is set. If the value is zero, then the select command functions as a poll of the files, returning immediately even if none are ready.
If the timeout period expires with none of the files becomming ready, then the command returns an empty list. Otherwise the command returns a list of three elements, each of those elements is a list of the fileIds that are ready in the read, write and exception classes. If none are ready in a class, then that element will be the null list. For example:
select {file3 file4 file5} {file6 file7} {} 10.5
could return
{file3 file4} {file6} {}
or perhaps
file3 {} {}
See Also: eof, fblocked, fconfigure Keywords: access position, file, seek
SET | 133 | NeoSoft, Inc. |
See Also: eof, fblocked, fconfigure Keywords: read, write, variable
SET_HEADER | 134 | NeoSoft, Inc. |
See Also: eof, fblocked, fconfigure Keywords: read, write, variable
SPLIT | 135 | NeoSoft, Inc. |
See Also: eof, fblocked, fconfigure Keywords: list, split, string
STRING | 136 | NeoSoft, Inc. |
string compare string1 string2
Perform a character-by-character comparison of strings string1 and string2 in the same way as the C strcmp procedure. Return -1, 0, or 1, depending on whether string1 is lexicographically less than, equal to, or greater than string2.
string first string1 string2
Search string2 for a sequence of characters that exactly match the characters in string1. If found, return the index of the first character in the first such match within string2. If not found, return -1.
string index string charIndex
Returns the charIndex´th character of the string argument. A charIndex of 0 corresponds to the first character of the string. If charIndex is less than 0 or greater than or equal to the length of the string then an empty string is returned.
string last string1 string2
Search string2 for a sequence of characters that exactly match the characters in string1. If found, return the index of the first character in the last such match within string2. If there is no match, then return -1.
string length string
Returns a decimal string giving the number of characters in string.
string match pattern string
See if pattern matches string; return 1 if it does, 0 if it doesn´t. Matching is done in a fashion similar to that used by the C-shell. For the two strings to match, their contents must be identical except that the following special sequences may appear in pattern:
string tolower string
Returns a value equal to string except that all upper case letters have been converted to lower case.
string toupper string
Returns a value equal to string except that all lower case letters have been converted to upper case.
string trim string ?chars?
Returns a value equal to string except that any leading or trailing characters from the set given by chars are removed. If chars is not specified then white space is removed (spaces, tabs, newlines, and carriage returns).
string trimleft string ?chars?
Returns a value equal to string except that any leading characters from the set given by chars are removed. If chars is not specified then white space is removed (spaces, tabs, newlines, and carriage returns).
string trimright string ?chars?
Returns a value equal to string except that any trailing characters from the set given by chars are removed. If chars is not specified then white space is removed (spaces, tabs, newlines, and carriage returns).
string wordend string index
Returns the index of the character just after the last one in the word containing character index of string. A word is considered to be any contiguous range of alphanumeric or underscore characters, or any single character other than these.
string wordstart string
See Also: eof, fblocked, fconfigure Keywords: case conversion, compare, index, match, pattern, string, word
SWITCH | 137 | NeoSoft, Inc. |
If the initial arguments to switch start with - then they are treated as options. The following options are currently supported:
If a body is specified as "-" it means that the body for the next pattern should also be used as the body for this pattern (if the next pattern also has a body of "-" then the body after that is used, and so on). This feature makes it possible to share a single body among several patterns.
Below are some examples of switch commands: switch abc a - b {format 1} abc {format 2} default {format 3} will return 2,
switch -regexp aaab {
^a.*b$
b {format 1}
a* {format 2}
default {format 3}
}
will return 1, and
switch xyz {
a
b
{format 1}
a*
{format 2}
default
{format 3}
}
will return 3.
See Also: eof, fblocked, fconfigure Keywords: switch, match, regular expression
TELL | 138 | NeoSoft, Inc. |
See Also: eof, fblocked, fconfigure Keywords: access position, channel, seeking
TRACE | 139 | NeoSoft, Inc. |
trace variable name ops command
Arrange for command to be executed whenever variable name is accessed in one of the ways given by ops. Name may refer to a normal variable, an element of an array, or to an array as a whole (i.e. name may be just the name of an array, with no parenthesized index). If name refers to a whole array, then command is invoked whenever any element of the array is manipulated.
Ops indicates which operations are of interest, and consists of one or more of the following letters:
Command 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 command 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 command invokes a procedure (which it normally does) then the procedure will have to use upvar or uplevel if it wishes to access the traced variable. Note also that name1 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 upvar command.
For read and write traces, command can modify the variable to affect the result of the traced operation. If command 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 command 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, command 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, command will have to restore the old value of the variable.
While command is executing during a read or write trace, traces on the variable are temporarily disabled. This means that reads and writes invoked by command will occur directly, without invoking command (or any other traces) again. However, if command unsets the variable then unset traces will be invoked.
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.
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.
Once created, the trace remains in effect either until the trace is removed with the trace vdelete 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.
This command returns an empty string.
trace vdelete name ops command
If there is a trace set on variable name with the operations and command given by ops and command, then the trace is removed, so that command will never again be invoked. Returns an empty string.
trace vinfo name
Returns a list containing one element for each trace currently set on variable name. Each element of the list is itself a list containing two elements, which are the ops and command associated with the trace. If name doesn´t exist or doesn´t have any traces set, then the result of the command will be an empty string.
See Also: eof, fblocked, fconfigure Keywords: read, variable, write, trace, unset
TRANSLIT | 140 | NeoSoft, Inc. |
See Also: eof, fblocked, fconfigure Keywords: read, variable, write, trace, unset
UNSET | 141 | NeoSoft, Inc. |
See Also: eof, fblocked, fconfigure Keywords: remove, variable
UPDATE | 142 | NeoSoft, Inc. |
If the idletasks 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.
The update idletasks 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 update idletasks 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 update idletasks.
The update 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 update then user input will be processed during the next call to update.
See Also: eof, fblocked, fconfigure Keywords: event, flush, handler, idle, update
UPLEVEL | 143 | NeoSoft, Inc. |
If level is an integer then it gives a distance (up the procedure calling stack) to move before executing the command. If level consists of # followed by a number then the number gives an absolute level number. If level is omitted then it defaults to 1. Level cannot be defaulted if the first command argument starts with a digit or #.
For example, suppose that procedure a was invoked from top-level, and that it called b, and that b called c. Suppose that c invokes the uplevel command. If level is 1 or #2 or omitted, then the command will be executed in the variable context of b. If level is 2 or #1 then the command will be executed in the variable context of a. If level is 3 or #0 then the command will be executed at toplevel (only global variables will be visible).
The uplevel command causes the invoking procedure to disappear from the procedure calling stack while the command is being executed. In the above example, suppose c invokes the command
uplevel 1 {set x 43; d}
where d is another Tcl procedure. The set command will modify the variable x in b´s context, and d will execute at level 3, as if called from b. If it in turn executes the command
uplevel {set x 42}
then the set command will modify the same variable x in b´s context: the procedure c does not appear to be on the call stack when d is executing. The command "info level" may be used to obtain the level of the current procedure.
Uplevel makes it possible to implement new control constructs as Tcl procedures (for example, uplevel could be used to implement the while construct as a Tcl procedure).
See Also: eof, fblocked, fconfigure Keywords: context, stack frame, variables
UPVAR | 144 | NeoSoft, Inc. |
The upvar command simplifies the implementation of callby-name procedure calling and also makes it easier to build new control constructs as Tcl procedures. For example, consider the following procedure:
proc add2 name {
upvar $name x
set x [expr $x+2]
}
Add2 is invoked with an argument giving the name of a variable, and it adds two to the value of that variable. Although add2 could have been implemented using uplevel instead of upvar, upvar makes it simpler for add2 to access the variable in the caller´s procedure frame.
If an upvar variable is unset (e.g. x in add2 above), the unset 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 upvar command.
BUGS
If otherVar refers to an element of an array, then variable traces set for the entire array will not be invoked when myVar is accessed (but traces on the particular element will still be invoked). In particular, if the array is env, then changes made to myVar will not be passed to subprocesses correctly.
See Also: eof, fblocked, fconfigure Keywords: context, frame, global, level, procedure, variable
VWAIT | 145 | NeoSoft, Inc. |
In some cases the vwait command may not return immediately after varName is set. This can happen if the event handler that sets varName does not complete immediately. For example, if an event handler sets varName and then itself calls vwait to wait for a different variable, then it may not return for a long time. During this time the toplevel vwait is blocked waiting for the event handler to complete, so it cannot return either.
See Also: eof, fblocked, fconfigure Keywords: event, variable, wait
WHILE | 146 | NeoSoft, Inc. |
See Also: eof, fblocked, fconfigure Keywords: boolean value, loop, test, while
WRAP | 147 | NeoSoft, Inc. |
wrap normally performs hard wrapping by inserting newline characters. But using the -html switch, newlines can be replaced with <BR> tags to reproduce the effect of hard wrapping of text in an HTML document without relying on the <PRE></PRE> elements.
See Also: eof, fblocked, fconfigure Keywords: boolean value, loop, test, while