Commands
after
after - delay code?
This command is used to delay execution of the program or to execute a command in background sometime in the future. It has several forms, depending on the first argument to the command:
after ms Ms must be an integer giving a time in milliseconds. The command sleeps for ms milliseconds and then returns. While the command is sleeping the application does not respond to events.
after ms ?script script script ...? In this form the command returns immediately, but it arranges for a Tcl command to be executed ms milliseconds later as an event handler. The command will be executed exactly once, at the given time. The delayed command is formed by concatenating all the script arguments in the same fashion as the concat command. The command will be executed at global level (outside the context of any Tcl procedure). If an error occurs while executing the delayed command then the background error will be reported by the command registered with interp bgerror. The after command returns an identifier that can be used to cancel the delayed command using after cancel.
after cancel id Cancels the execution of a delayed command that was previously scheduled. Id indicates which command should be canceled; it must have been the return value from a previous after command. If the command given by id has already been executed then the after cancel command has no effect.
after cancel script script ... This command also cancels the execution of a delayed command. The script arguments are concatenated together with space separators (just as in the concat command). If there is a pending command that matches the string, it is canceled and will never be executed; if no such command is currently pending then the after cancel command has no effect.
after idle script ?script script ...? Concatenates the script arguments together with space separators (just as in the concat command), and arranges for the resulting script to be evaluated later as an idle callback. The script will be run exactly once, the next time the event loop is entered and there are no events to process. The command returns an identifier that can be used to cancel the delayed command using after cancel. If an error occurs while executing the script then the background error will be reported by the command registered with interp bgerror.
after info ?id? This command returns information about existing event handlers. If no id argument is supplied, the command returns a list of the identifiers for all existing event handlers created by the after command for this interpreter. If id is supplied, it specifies an existing handler; id must have been the return value from some previous call to after and it must not have triggered yet or been canceled. In this case the command returns a list with two elements. The first element of the list is the script associated with id, and the second element is either idle or timer to indicate what kind of event handler it is.
The after ms and after idle forms of the command assume that the application is event driven: the delayed commands will not be executed unless the application enters the event loop. In applications that are not normally event-driven, such as tclsh, the event loop can be entered with the vwait and update commands.
append
append - varName args
Append all of the value arguments to the current value of variable varName. If varName does not exist, it is given a value equal to the concatenation of all the value arguments. The result of this command is the new value stored in variable varName. This command provides an efficient way to build up long variables incrementally. For example, “append a $b” is much more efficient than “set a $a$b” if $a is long.
bind
bind - trigger procedure
To be written....
block
block - args
To be written....
- block target? up
Return the block above this block.
- block target? material material1
Change the type of target block to a new type.
- block target? down
Return the block below this block.
- block target? west
Return the block west of this block.
- block target? east
Return the block east of this block.
- block target? south
Return the block south of this block.
- block target? north
Return the block north of this block.
- block target? fall
Change target block into a falling block. Return the new entity.
- block target? growtree string1
Grow a tree of the given type on top of this block. Returns 1 uppon success, 0 otherwise.
- block target? data integer1
Undocumented
- block target? power
Undocumented
- block target? break
Break target block as if broken by a player.
- block target? typeNoPhysics material1
Undocumented
break
break -
This command is typically invoked inside the body of a looping command such as for or foreach or while. It returns a 3 (TCL_BREAK) result code, which causes a break exception to occur. The exception causes the current script to be aborted out to the innermost containing loop command, which then aborts its execution and returns normally. Break exceptions are also handled in a few other situations, such as the catch command, Tk event bindings, and the outermost scripts of procedure bodies.
catch
catch - script messageVarName?
The catch command may be used to prevent errors from aborting command interpretation. The catch command calls the Tcl interpreter recursively to execute script, and always returns without raising an error, regardless of any errors that might occur while executing script.
If script raises an error, catch will return a non-zero integer value corresponding to the exceptional return code returned by evaluation of script. Tcl defines the normal return code from script evaluation to be zero (0), or TCL_OK. Tcl also defines four exceptional return codes: 1 (TCL_ERROR), 2 (TCL_RETURN), 3 (TCL_BREAK), and 4 (TCL_CONTINUE). Errors during evaluation of a script are indicated by a return code of TCL_ERROR. The other exceptional return codes are returned by the return, break, and continue commands and in other special situations as documented. Tcl packages can define new commands that return other integer values as return codes as well, and scripts that make use of the return -code command can also have return codes other than the five defined by Tcl.
If the resultVarName argument is given, then the variable it names is set to the result of the script evaluation. When the return code from the script is 1 (TCL_ERROR), the value stored in resultVarName is an error message. When the return code from the script is 0 (TCL_OK), the value stored in resultVarName is the value returned from script.
If the optionsVarName argument is given, then the variable it names is set to a dictionary of return options returned by evaluation of script. Tcl specifies two entries that are always defined in the dictionary: -code and -level. When the return code from evaluation of script is not TCL_RETURN, the value of the -level entry will be 0, and the value of the -code entry will be the same as the return code. Only when the return code is TCL_RETURN will the values of the -level and -code entries be something else, as further described in the documentation for the return command.
When the return code from evaluation of script is TCL_ERROR, four additional entries are defined in the dictionary of return options stored in optionsVarName: -errorinfo, -errorcode, -errorline, and -errorstack. The value of the -errorinfo entry is a formatted stack trace containing more information about the context in which the error happened. The formatted stack trace is meant to be read by a person. The value of the -errorcode entry is additional information about the error stored as a list. The -errorcode value is meant to be further processed by programs, and may not be particularly readable by people. The value of the -errorline entry is an integer indicating which line of script was being evaluated when the error occurred. The value of the -errorstack entry is an even-sized list made of token-parameter pairs accumulated while unwinding the stack. The token may be “CALL”, in which case the parameter is a list made of the proc name and arguments at the corresponding level; or it may be “UP”, in which case the parameter is the relative level (as in uplevel) of the previous CALL. The salient differences with respect to -errorinfo are that:
it is a machine-readable form that is amenable to processing with [foreach {tok prm} ...],
it contains the true (substituted) values passed to the functions, instead of the static text of the calling sites, and
it is coarser-grained, with only one element per stack frame (like procs; no separate elements for foreach constructs for example).
The values of the -errorinfo and -errorcode entries of the most recent error are also available as values of the global variables ::errorInfo and ::errorCode respectively. The value of the -errorstack entry surfaces as info errorstack.
Tcl packages may provide commands that set other entries in the dictionary of return options, and the return command may be used by scripts to set return options in addition to those defined above.
color
color - color
To be written....
concat
concat - args
This command joins each of its arguments together with spaces after trimming leading and trailing white-space from each of them. If all of the arguments are lists, this has the same effect as concatenating them into a single list. It permits any number of arguments; if no args are supplied, the result is an empty string.
entity
entity - args
To be written....
- entity target? name
Return target entity's name.
- entity target? addpotion string1 double2 integer3
Undocumented
- entity target? still
Set target entity's velocity to zero and reset fall distance.
- entity target? target entity1
Undocumented
- entity target? pickupdelay integer1
Undocumented
- entity target? onground
Undocumented
- entity target? remove
Undocumented
- entity target? teleport arg1
Teleport target entity's to given location. Return the new loaction.
- entity target? clearpotions
Undocumented
- entity target? ignight
Undocumented
error
error - info?
Returns a TCL_ERROR code, which causes command interpretation to be unwound. Message is a string that is returned to the application to indicate what went wrong.
The -errorinfo return option of an interpreter 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 the -errorinfo return option. If the info argument is present, it is used to initialize the -errorinfo return options 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 the stack trace; in its place will be info. Historically, this feature had been 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
When working with Tcl 8.5 or later, the following code should be used instead:
catch {...} errMsg options ... return -options $options $errMsg
If the code argument is present, then its value is stored in the -errorcode return option. The -errorcode return option is intended to hold a machine-readable description of the error in cases where such information is available; see the return manual page for information on the proper format for this option's value.
et
et - args
To be written....
eval
eval - args
Eval takes one or more arguments, which together comprise a Tcl script containing one or more commands. Eval concatenates all its arguments in the same fashion as the concat command, passes the concatenated string to the Tcl interpreter recursively, and returns the result of that evaluation (or any error generated by it). Note that the list command quotes sequences of words in such a way that they are not further expanded by the eval command.
expand
expand - args
To be written....
explode
explode - -nobreak -nofire power?
To be written....
expr
expr - args
Concatenates args (adding separator spaces between them), evaluates the result as a Tcl expression, and returns the value. The operators permitted in Tcl expressions include a subset of the operators permitted in C expressions. For those operators common to both Tcl and C, Tcl applies the same meaning and precedence as the corresponding C operators. Expressions almost always yield numeric results (integer or floating-point values). For example, the expression
expr 8.2 + 6
evaluates to 14.2. Tcl expressions differ from C expressions in the way that operands are specified. Also, Tcl expressions support non-numeric operands and string comparisons, as well as some additional operators not found in C. OPERANDS A Tcl expression consists of a combination of operands, operators, parentheses and commas. White space may be used between the operands and operators and parentheses (or commas); it is ignored by the expression's instructions. Where possible, operands are interpreted as integer values. Integer values may be specified in decimal (the normal case), in binary (if the first two characters of the operand are 0b), in octal (if the first two characters of the operand are 0o), or in hexadecimal (if the first two characters of the operand are 0x). For compatibility with older Tcl releases, an octal integer value is also indicated simply when the first character of the operand is 0, whether or not the second character is also o. If an operand does not have one of the integer formats given above, then it is treated as a floating-point number if that is possible. Floating-point numbers may be specified in any of several common formats making use of the decimal digits, the decimal point ., the characters e or E indicating scientific notation, and the sign characters + or -. For example, all of the following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. Also recognized as floating point values are the strings Inf and NaN making use of any case for each character. If no numeric interpretation is possible (note that all literal operands that are not numeric or boolean must be quoted with either braces or with double quotes), 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:
As a numeric value, either integer or floating-point.
As a boolean value, using any form understood by string is boolean.
As a Tcl variable, using standard $ notation. The variable's value will be used as the operand.
As a string enclosed in double-quotes. The expression parser will perform backslash, variable, and command substitutions on the information between the quotes, and use the resulting value as the operand
As a string enclosed in braces. The characters between the open brace and matching close brace will be used as the operand without any substitutions.
As a Tcl command enclosed in brackets. The command will be executed and its result will be used as the operand.
As a mathematical function whose arguments have any of the above forms for operands, such as sin($x). See MATH FUNCTIONS below for a discussion of how mathematical functions are handled.
Where the above substitutions occur (e.g. inside quoted strings), they are performed by the expression's instructions. However, the command parser may already have performed one round of substitution before the expression processor was called. As discussed below, it is usually best to enclose expressions in braces to prevent the command parser from performing substitutions on the contents.
For some examples of simple expressions, suppose the variable a has the value 3 and the variable b has the value 6. Then the command on the left side of each of the lines below will produce the value on the right side of the line:
expr 3.1 + $a 6.1 expr 2 + "$a.$b" 5.6 expr 4*[llength "6 2"] 8 expr {{word one} < "word $a"} 0 OPERATORS The valid operators (most of which are also available as commands in the tcl::mathop namespace; see the mathop(n) manual page for details) are listed below, grouped in decreasing order of precedence:
- + ~ ! Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operators may be applied to string operands, and bit-wise NOT may be applied only to integers.
Exponentiation. Valid for any numeric operands.
- / % Multiply, divide, remainder. None of these operators may be applied to string operands, and remainder may be applied only to integers. The remainder will always have the same sign as the divisor and an absolute value smaller than the absolute value of the divisor.
When applied to integers, the division and remainder operators can be considered to partition the number line into a sequence of equal-sized adjacent non-overlapping pieces where each piece is the size of the divisor; the division result identifies which piece the divisor lay within, and the remainder result identifies where within that piece the divisor lay. A consequence of this is that the result of “-57 / 10” is always -6, and the result of “-57 % 10” is always 3.
+ - Add and subtract. Valid for any numeric operands.
Left and right shift. Valid for integer operands only. A right shift always propagates 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.
eq ne Boolean string equal and string not equal. Each operator produces a zero/one result. The operand types are interpreted only as strings.
in ni List containment and negated list containment. Each operator produces a zero/one result and treats its first argument as a string and its second argument as a Tcl list. The in operator indicates whether the first argument is a member of the second argument list; the ni operator inverts the sense of the result.
& Bit-wise AND. Valid for integer operands only.
^ Bit-wise exclusive OR. Valid for integer operands only.
| Bit-wise OR. Valid for integer operands only. |
&& Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise. Valid for boolean and numeric (integers or floating-point) operands only.
| Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. Valid for boolean and numeric (integers or floating-point) operands only. |
x?y:z If-then-else, as in C. If x evaluates to non-zero, then the result is the value of y. Otherwise the result is the value of z. The x operand must have a boolean or numeric value.
See the C manual for more details on the results produced by each operator. The exponentiation operator promotes types like the multiply and divide operators, and produces a result that is the same as the output of the pow function (after any type conversions.) All of the binary operators but exponentiation group left-to-right within the same precedence level; exponentiation groups right-to-left. For example, the command
expr {4*2 < 7}
returns 0, while
expr {232}
returns 512.
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 When the expression parser encounters a mathematical function such as sin($x), it replaces it with a call to an ordinary Tcl function in the tcl::mathfunc namespace. The processing of an expression such as:
expr {sin($x+$y)}
is the same in every way as the processing of:
expr {[tcl::mathfunc::sin [expr {$x+$y}]]}
which in turn is the same as the processing of:
tcl::mathfunc::sin [expr {$x+$y}]
The executor will search for tcl::mathfunc::sin using the usual rules for resolving functions in namespaces. Either ::tcl::mathfunc::sin or [namespace current]::tcl::mathfunc::sin will satisfy the request, and others may as well (depending on the current namespace path setting).
Some mathematical functions have several arguments, separated by commas like in C. Thus:
expr {hypot($x,$y)}
ends up as
tcl::mathfunc::hypot $x $y
See the mathfunc(n) manual page for the math functions that are available by default. TYPES, OVERFLOW, AND PRECISION All internal computations involving integers are done calling on the LibTomMath multiple precision integer library as required so that all integer calculations are performed exactly. Note that in Tcl releases prior to 8.5, integer calculations were performed with one of the C types long int or Tcl_WideInt, causing implicit range truncation in those calculations where values overflowed the range of those types. Any code that relied on these implicit truncations will need to explicitly add int() or wide() function calls to expressions at the points where such truncation is required to take place.
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 the double value of Inf or -Inf as appropriate. 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. 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, i.e., when all arguments to the operator allow numeric interpretations, except in the case of the eq and ne operators. If one of the operands of a comparison is a string and the other has a numeric value, a canonical string representation of the numeric operand value is generated to compare with the string operand. Canonical string representation for integer values is a decimal string format. Canonical string representation for floating-point values is that produced by the %g format specifier of Tcl's format command. 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. Because of Tcl's tendency to treat values as numbers whenever possible, it is not generally a good idea to use operators like == when you really want string comparison and the values of the operands could be arbitrary; it is better in these cases to use the eq or ne operators, or the string command instead.
for
for - start test next body
For is a looping command, similar in structure to the C for statement. The start, next, and body arguments must be Tcl command strings, and test is an expression string. The for command first invokes the Tcl interpreter to execute start. Then it repeatedly evaluates test as an expression; if the result is non-zero it invokes the Tcl interpreter on body, then invokes the Tcl interpreter on next, then repeats the loop. The command terminates when test evaluates to 0. If a continue command is invoked within body then any remaining commands in the current execution of body are skipped; processing continues by invoking the Tcl interpreter on next, then evaluating test, and so on. If a break command is invoked within body or next, then the for command will return immediately. The operation of break and continue are similar to the corresponding statements in C. For returns an empty string.
Note: test should almost always be enclosed in braces. If not, variable substitutions will be made before the for command starts executing, which means that variable changes made by the loop body will not be considered in the expression. This is likely to result in an infinite loop. If test is enclosed in braces, variable substitutions are delayed until the expression is evaluated (before each loop iteration), so changes in the variables will be visible. See below for an example:
format
format - formatString args
global
global - args
This command has no effect unless executed in the context of a proc body. If the global command is executed in the context of a proc body, it creates local variables linked to the corresponding global variables (though these linked variables, like those created by upvar, are not included in the list returned by info locals).
If varname contains namespace qualifiers, the local variable's name is the unqualified name of the global variable, as determined by the namespace tail command.
varname is always treated as the name of a variable, not an array element. An error is returned if the name looks like an array element, such as a(b).
hash
hash - type data
To be written....
heal
heal - amount?
To be written....
if
if - expr 'then'? body 'else'? elseCode?
The if command evaluates expr1 as an expression (in the same way that expr evaluates its argument). The value of the expression must be a boolean (a numeric value, where 0 is false and anything is true, or a string value such as true or yes for true and false or no for false); if it is true then body1 is executed by passing it to the Tcl interpreter. Otherwise expr2 is evaluated as an expression and if it is true then body2 is executed, and so on. If none of the expressions evaluates to true then bodyN is executed. The then and else arguments are optional “noise words” to make the command easier to read. There may be any number of elseif clauses, including zero. BodyN may also be omitted as long as else is omitted too. The return value from the command is the result of the body script that was executed, or an empty string if none of the expressions was non-zero and there was no bodyN.
import
import - from
To be written....
incr
incr - varName increment?
Increments the value stored in the variable whose name is varName. The value of the variable must be an integer. If increment is supplied then its value (which must be an integer) is added to the value of variable varName; otherwise 1 is added to varName. The new value is stored as a decimal string in variable varName and also returned as result.
Starting with the Tcl 8.5 release, the variable varName passed to incr may be unset, and in that case, it will be set to the value increment or to the default increment value of 1.
info
info - args
This command provides information about various internals of the Tcl interpreter. The legal options (which may be abbreviated) are:
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 class subcommand class ?arg ... Returns information about the class, class. The subcommands are described in CLASS INTROSPECTION below.
info cmdcount Returns a count of the total number of commands that have been invoked in this interpreter.
info commands ?pattern? If pattern is not specified, returns a list of names of all the Tcl commands visible (i.e. executable without using a qualified name) to the current namespace, including both the built-in 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. pattern can be a qualified name like Foo::print*. That is, it may specify a particular namespace using a sequence of namespace names separated by double colons (::), and may have pattern matching special characters at the end to specify a set of commands in that namespace. If pattern is a qualified name, the resulting list of command names has each one qualified with the name of the specified namespace, and only the commands defined in the named namespace are returned.
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 does not 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 is not complete, the script can delay evaluating it until additional lines have been typed to complete the command.
info coroutine Returns the name of the currently executing coroutine, or the empty string if either no coroutine is currently executing, or the current coroutine has been deleted (but has not yet returned or yielded since deletion).
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 does not have a default value then the command returns 0. Otherwise it returns 1 and places the default value of arg into variable varname.
info errorstack ?interp? Returns, in a form that is programmatically easy to parse, the function names and arguments at each level from the call stack of the last error in the given interp, or in the current one if not specified.
This form is an even-sized list alternating tokens and parameters. Tokens are currently either CALL, UP, or INNER, but other values may be introduced in the future. CALL indicates a procedure call, and its parameter is the corresponding info level 0. UP indicates a shift in variable frames generated by uplevel or similar, and applies to the previous CALL item. Its parameter is the level offset. INNER identifies the “inner context”, which is the innermost atomic command or bytecode instruction that raised the error, along with its arguments when available. While CALL and UP allow to follow complex call paths, INNER homes in on the offending operation in the innermost procedure call, even going to sub-expression granularity.
This information is also present in the -errorstack entry of the options dictionary returned by 3-argument catch; info errorstack is a convenient way of retrieving it for uncaught errors at top-level in an interactive tclsh.
info exists varName Returns 1 if the variable named varName exists in the current context (either as a global or local variable) and has been defined by being given a value, returns 0 otherwise.
info frame ?number? This command provides access to all frames on the stack, even those hidden from info level. If number is not specified, this command returns a number giving the frame level of the command. This is 1 if the command is invoked at top-level. If number is specified, then the result is a dictionary containing the location information for the command at the numbered level on the stack.
If number is positive (> 0) then it selects a particular stack level (1 refers to the outer-most active command, 2 to the command it called, and so on, up to the current frame level which refers to info frame itself); otherwise it gives a level relative to the current command (0 refers to the current command, i.e., info frame itself, -1 to its caller, and so on).
This is similar to how info level works, except that this subcommand reports all frames, like sourced scripts, evals, uplevels, etc.
Note that for nested commands, like “foo [bar [x]]”, only “x” will be seen by an info frame invoked within “x”. This is the same as for info level and error stack traces.
The result dictionary may contain the keys listed below, with the specified meanings for their values:
type This entry is always present and describes the nature of the location for the command. The recognized values are source, proc, eval, and precompiled.
source means that the command is found in a script loaded by the source command.
proc means that the command is found in dynamically created procedure body.
eval means that the command is executed by eval or uplevel.
precompiled means that the command is found in a pre-compiled script (loadable by the package tbcload), and no further information will be available.
line This entry provides the number of the line the command is at inside of the script it is a part of. This information is not present for type precompiled. For type source this information is counted relative to the beginning of the file, whereas for the last two types the line is counted relative to the start of the script.
file This entry is present only for type source. It provides the normalized path of the file the command is in.
cmd This entry provides the string representation of the command. This is usually the unsubstituted form, however for commands which are a canonically-constructed list (e.g., as produced by the list command) executed by eval it is the substituted form as they have no other string representation. Care is taken that the canonicality property of the latter is not spoiled.
proc This entry is present only if the command is found in the body of a regular Tcl procedure. It then provides the name of that procedure.
lambda This entry is present only if the command is found in the body of an anonymous Tcl procedure, i.e. a lambda. It then provides the entire definition of the lambda in question.
level This entry is present only if the queried frame has a corresponding frame returned by info level. It provides the index of this frame, relative to the current level (0 and negative numbers).
A thing of note is that for procedures statically defined in files the locations of commands in their bodies will be reported with type source and absolute line numbers, and not as type proc. The same is true for procedures nested in statically defined procedures, and literal eval scripts in files or statically defined procedures.
In contrast, procedure definitions and eval within a dynamically evaluated environment count line numbers relative to the start of their script, even if they would be able to count relative to the start of the outer dynamic script. That type of number usually makes more sense.
A different way of describing this behaviour is that file based locations are tracked as deeply as possible, and where this is not possible the lines are counted based on the smallest possible eval or procedure body, as that scope is usually easier to find than any dynamic outer scope.
The syntactic form {*} is handled like eval. I.e. if it is given a literal list argument the system tracks the line number within the list words as well, and otherwise all line numbers are counted relative to the start of each word (smallest scope)
info functions ?pattern? If pattern is not specified, returns a list of all the math functions currently defined. If pattern is specified, only those functions whose name matches pattern are returned. Matching is determined using the same rules as for string match.
info globals ?pattern? If pattern is not specified, returns a list of all the names of currently-defined global variables. Global variables are variables in the global namespace. 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. Note that this name is not guaranteed to be the fully qualified domain name of the host. Where machines have several different names (as is common on systems with both TCP/IP (DNS) and NetBIOS-based networking installed,) it is the name that is suitable for TCP/IP networking that is returned.
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 top-level. 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. If interp is omitted then information is returned for all packages loaded in any interpreter in the process. To get a list of just the packages in the current interpreter, specify an empty string for the interp argument.
info locals ?pattern? If pattern is not 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, upvar and variable 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 object subcommand object ?arg ... Returns information about the object, object. The subcommands are described in OBJECT INTROSPECTION below.
info patchlevel Returns the value of the global variable tcl_patchLevel; see the tclvars manual entry for more information.
info procs ?pattern? If pattern is not specified, returns a list of all the names of Tcl command procedures in the current namespace. If pattern is specified, only those procedure names in the current namespace matching pattern are returned. Matching is determined using the same rules as for string match. If pattern contains any namespace separators, they are used to select a namespace relative to the current namespace (or relative to the global namespace if pattern starts with ::) to match within; the matching pattern is taken to be the part after the last namespace separator.
info script ?filename? 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. If filename is specified, then the return value of this command will be modified for the duration of the active invocation to return that name. This is useful in virtual file system applications. 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 are not 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 is not specified, returns a list of all the names of currently-visible variables. This includes 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. pattern can be a qualified name like Foo::option*. That is, it may specify a particular namespace using a sequence of namespace names separated by double colons (::), and may have pattern matching special characters at the end to specify a set of variables in that namespace. If pattern is a qualified name, the resulting list of variable names has each matching namespace variable qualified with the name of its namespace. Note that a currently-visible variable may not yet “exist” if it has not been set (e.g. a variable declared but not set by variable).
CLASS INTROSPECTION The following subcommand values are supported by info class:
info class call class method Returns a description of the method implementations that are used to provide a stereotypical instance of class's implementation of method (stereotypical instances being objects instantiated by a class without having any object-specific definitions added). This consists of a list of lists of four elements, where each sublist consists of a word that describes the general type of method implementation (being one of method for an ordinary method, filter for an applied filter, and unknown for a method that is invoked as part of unknown method handling), a word giving the name of the particular method invoked (which is always the same as method for the method type, and “unknown” for the unknown type), a word giving the fully qualified name of the class that defined the method, and a word describing the type of method implementation (see info class methodtype).
Note that there is no inspection of whether the method implementations actually use next to transfer control along the call chain.
info class constructor class This subcommand returns a description of the definition of the constructor of class class. The definition is described as a two element list; the first element is the list of arguments to the constructor in a form suitable for passing to another call to proc or a method definition, and the second element is the body of the constructor. If no constructor is present, this returns the empty list.
info class definition class method This subcommand returns a description of the definition of the method named method of class class. The definition is described as a two element list; the first element is the list of arguments to the method in a form suitable for passing to another call to proc or a method definition, and the second element is the body of the method.
info class destructor class This subcommand returns the body of the destructor of class class. If no destructor is present, this returns the empty string.
info class filters class This subcommand returns the list of filter methods set on the class.
info class forward class method This subcommand returns the argument list for the method forwarding called method that is set on the class called class.
info class instances class ?pattern? This subcommand returns a list of instances of class class. If the optional pattern argument is present, it constrains the list of returned instances to those that match it according to the rules of string match.
info class methods class ?options...? This subcommand returns a list of all public (i.e. exported) methods of the class called class. Any of the following options may be specified, controlling exactly which method names are returned:
-all If the -all flag is given, the list of methods will include those methods defined not just by the class, but also by the class's superclasses and mixins.
-private If the -private flag is given, the list of methods will also include the private (i.e. non-exported) methods of the class (and superclasses and mixins, if -all is also given).
info class methodtype class method This subcommand returns a description of the type of implementation used for the method named method of class class. When the result is method, further information can be discovered with info class definition, and when the result is forward, further information can be discovered with info class forward.
info class mixins class This subcommand returns a list of all classes that have been mixed into the class named class.
info class subclasses class ?pattern? This subcommand returns a list of direct subclasses of class class. If the optional pattern argument is present, it constrains the list of returned classes to those that match it according to the rules of string match.
info class superclasses class This subcommand returns a list of direct superclasses of class class in inheritance precedence order.
info class variables class This subcommand returns a list of all variables that have been declared for the class named class (i.e. that are automatically present in the class's methods, constructor and destructor).
OBJECT INTROSPECTION The following subcommand values are supported by info object:
info object call object method Returns a description of the method implementations that are used to provide object's implementation of method. This consists of a list of lists of four elements, where each sublist consists of a word that describes the general type of method implementation (being one of method for an ordinary method, filter for an applied filter, and unknown for a method that is invoked as part of unknown method handling), a word giving the name of the particular method invoked (which is always the same as method for the method type, and “unknown” for the unknown type), a word giving what defined the method (the fully qualified name of the class, or the literal string object if the method implementation is on an instance), and a word describing the type of method implementation (see info object methodtype).
Note that there is no inspection of whether the method implementations actually use next to transfer control along the call chain.
info object class object ?className? If className is unspecified, this subcommand returns class of the object object. If className is present, this subcommand returns a boolean value indicating whether the object is of that class.
info object definition object method This subcommand returns a description of the definition of the method named method of object object. The definition is described as a two element list; the first element is the list of arguments to the method in a form suitable for passing to another call to proc or a method definition, and the second element is the body of the method.
info object filters object This subcommand returns the list of filter methods set on the object.
info object forward object method This subcommand returns the argument list for the method forwarding called method that is set on the object called object.
info object isa category object ?arg? This subcommand tests whether an object belongs to a particular category, returning a boolean value that indicates whether the object argument meets the criteria for the category. The supported categories are:
info object isa class object This returns whether object is a class (i.e. an instance of oo::class or one of its subclasses).
info object isa metaclass object This returns whether object is a class that can manufacture classes (i.e. is oo::class or a subclass of it).
info object isa mixin object class This returns whether class is directly mixed into object.
info object isa object object This returns whether object really is an object.
info object isa typeof object class This returns whether class is the type of object (i.e. whether object is an instance of class or one of its subclasses, whether direct or indirect).
info object methods object ?option...? This subcommand returns a list of all public (i.e. exported) methods of the object called object. Any of the following options may be specified, controlling exactly which method names are returned:
-all If the -all flag is given, the list of methods will include those methods defined not just by the object, but also by the object's class and mixins, plus the superclasses of those classes.
-private If the -private flag is given, the list of methods will also include the private (i.e. non-exported) methods of the object (and classes, if -all is also given).
info object methodtype object method This subcommand returns a description of the type of implementation used for the method named method of object object. When the result is method, further information can be discovered with info object definition, and when the result is forward, further information can be discovered with info object forward.
info object mixins object This subcommand returns a list of all classes that have been mixed into the object named object.
info object namespace object This subcommand returns the name of the internal namespace of the object named object.
info object variables object This subcommand returns a list of all variables that have been declared for the object named object (i.e. that are automatically present in the object's methods).
info object vars object ?pattern? This subcommand returns a list of all variables in the private namespace of the object named object. If the optional pattern argument is given, it is a filter (in the syntax of a string match glob pattern) that constrains the list of variables returned. Note that this is different from the list returned by info object variables; that can include variables that are currently unset, whereas this can include variables that are not automatically included by any of object's methods (or those of its class, superclasses or mixins).
item
item - args
To be written....
- item target? create material0
Undocumented
- item target? fix
Fully repair target item by setting its durability to 0.
- item target? offer player1
Offer a copy of target item(s) to given player by showing them the chest UI.
- item target? give player1
Put the target item(s) into the given players inventory. Defaults to caster if no player given.
- item target? enchant string1 arg2
Enchant the target item(s) with given enchantment name and level. If no level is specified, the maximum is used. Unnatural enchantments are okay.
- item target? safeEnchant string1 arg2
Enchant the target item(s) with given enchantment name and level. If no level is specified, the maximum is used. Unnatural enchantments will return an error.
- item target? place arg1
Place the target item(s) into the world at the given location. Returns the resulting entity.
- item target? amount integer1
If given an argument, set the number of items in the target stack. Returns current ammount.
- item target? bind string1
Designate some spell to handel events generated by target item(s). Returns curent binding.
- item target? more
Set the ammount of items in the target stack to the maximum value.
- item target? name string1
If given an argument, set the display name of the target item(s). Returns the current name.
- item target? drop arg1
Drop the target item(s) into the world at the given location. Returns the resulting entity.
- item target? lore string1
Undocumented
- item target? material material1
If given an argument, set the type of the target item. Returns the current type.
- item target? damage integer1
If given an argument, set the durability of the item. Returns the current durability.
- item target? forceInv player1 integer2
Put a copy of target itemstack into a player's inventory at in the given slot.
- item target? equip arg1
Equip a copy of target itemstack onto a player in its natural slot.
- item target? equipex player1 string2
Equip a copy of target itemstack onto a player in the specified slot.
- item target? test string1
Undocumented
join
join - list joinstring?
The list argument must be a valid Tcl list. This command returns the string formed by joining all of the elements of list together with joinString separating each adjacent pair of elements. The joinString argument defaults to a space character.
lappend
lappend - varName args
This command treats the variable given by varName as a list and appends each of the value arguments to that list as a separate element, with spaces between elements. If varName does not exist, it is created as a list with elements given by the value arguments. Lappend is similar to append except that the values are appended as list elements rather than raw text. This command provides a relatively efficient way to build up large lists. For example, “lappend a $b” is much more efficient than “set a [concat $a [list $b]]” when $a is long.
lentity
lentity - args
To be written....
- lentity target? addpotion string1 double2 integer3
Undocumented
- lentity target? target entity1
Undocumented
- lentity target? hold arg1
Undocumented
- lentity target? clearpotions
Undocumented
- lentity target? health integer1
lindex
lindex - list args
The lindex command accepts a parameter, list, which it treats as a Tcl list. It also accepts zero or more indices into the list. The indices may be presented either consecutively on the command line, or grouped in a Tcl list and presented as a single argument.
If no indices are presented, the command takes the form:
lindex list
or
lindex list {}
In this case, the return value of lindex is simply the value of the list parameter.
When presented with a single index, the lindex command treats list as a Tcl list and returns the index'th element from it (0 refers to the first element of the list). In extracting the element, lindex observes the same rules concerning braces and quotes and backslashes as the Tcl command interpreter; however, variable substitution and command substitution do not occur. If index is negative or greater than or equal to the number of elements in value, then an empty string is returned. The interpretation of each simple index value is the same as for the command string index, supporting simple index arithmetic and indices relative to the end of the list.
If additional index arguments are supplied, then each argument is used in turn to select an element from the previous indexing operation, allowing the script to select elements from sublists. The command,
lindex $a 1 2 3
or
lindex $a {1 2 3}
is synonymous with
lindex [lindex [lindex $a 1] 2] 3
list
list - args
This command returns a list comprised of all the args, or an empty string if no args are specified. Braces and backslashes get added as necessary, so that the lindex command may be used on the result to re-extract the original arguments, and also so that eval may be used to execute the resulting list, with arg1 comprising the command's name and the other args comprising its arguments. List produces slightly different results than concat: concat removes one level of grouping before forming the list, while list works directly from the original arguments.
llength
llength - list
Treats list as a list and returns a decimal string giving the number of elements in it.
pcommand
pcommand - command
To be written....
player
player - args
To be written....
- player target? chat arg1
Force a player to say something.
- player target? flySpeed double1
Undocumented
- player target? giveExp integer1
- player target? walkSpeed double1
Undocumented
- player target? closeInventory
Undocumented
- player target? gameMode arg1
Undocumented
- player target? hasPermission string1
Undocumented
- player target? op boolean1
Undocumented
- player target? exp integer1
- player target? offer arg1
Undocumented
- player target? clear
Empties the players inventory.
- player target? inventorylist
Undocumented
- player target? flight boolean1
- player target? giveMoney double1
- player target? texturpack string1
Undocumented
- player target? listname string1
Undocumented
- player target? money
Returns the amount of money a player has from vault.
- player target? permissions
Undocumented
- player target? takeMoney double1
- player target? level integer1
Undocumented
- player target? giveLevel integer1
Undocumented
- player target? team string1
Undocumented
- player target? feed
Restore target player's hunger, saturation, and exaustion.
- player target? puts arg1
Displays text to that player.
proc
proc - name argNames body
The proc command creates a new Tcl procedure named name, replacing any existing command or procedure there may have been by that name. Whenever the new command is invoked, the contents of body will be executed by the Tcl interpreter. Normally, name is unqualified (does not include the names of any containing namespaces), and the new procedure is created in the current namespace. If name includes any namespace qualifiers, the procedure is created in the specified namespace. Args specifies the formal arguments to the procedure. It consists of a list, possibly empty, each of whose elements specifies one argument. Each argument specifier is also a list with either one or two fields. If there is only a single field in the specifier then it is the name of the argument; if there are two fields, then the first is the argument name and the second is its default value. Arguments with default values that are followed by non-defaulted arguments become required arguments. In 8.6 this will be considered an error.
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. Actual arguments are assigned to formal arguments strictly in order. 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 do not have defaults, and there must not be any extra actual arguments. Arguments with default values that are followed by non-defaulted arguments become required arguments (in 8.6 it will be considered an error). 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 formal arguments. 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. Other variables can only be accessed by invoking one of the global, variable, upvar or namespace upvar commands. The current namespace when body is executed will be the namespace that the procedure's name exists in, which will be the namespace that it was created in unless it has been changed with rename.
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 does not 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.
puts
puts - string
Writes the characters given by string to the channel given by channelId.
ChannelId must be an identifier for an open channel such as a Tcl standard channel (stdout or stderr), the return value from an invocation of open or socket, or the result of a channel creation command provided by a Tcl extension. The channel must have been opened for output.
If no channelId is specified then it defaults to stdout. Puts normally outputs a newline character after string, but this feature may be suppressed by specifying the -nonewline switch.
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. See the fconfigure manual entry for a discussion on ways in which fconfigure will alter output.
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 (do not invoke puts unless you have recently been notified via a file event that the channel is ready for more output data).
return
return - result?
In its simplest usage, the return command is used without options in the body of a procedure to immediately return control to the caller of the procedure. If a result argument is provided, its value becomes the result of the procedure passed back to the caller. If result is not specified then an empty string will be returned to the caller as the result of the procedure.
The return command serves a similar function within script files that are evaluated by the source command. When source evaluates the contents of a file as a script, an invocation of the return command will cause script evaluation to immediately cease, and the value result (or an empty string) will be returned as the result of the source command.
scommand
scommand - command
To be written....
server
server - args
To be written....
- server name
Returns the current server name.
- server motd
Returns the current server MOTD.
- server players
Undocumented
- server broadcast string1
Send some string to all connected players.
- server reload
Tell bukkit to reload. Same as the /reload command.
- server shutdown
Shutdown the server.
set
set - varName newValue?
Returns the value of variable varName. If value is specified, then set the value of varName to value, creating a new variable if one does not already exist, and return its value. If varName contains an open parenthesis and ends with a close parenthesis, then it refers to an array element: the characters before the first open parenthesis are the name of the array, and the characters between the parentheses are the index within the array. Otherwise varName refers to a scalar variable.
If varName includes namespace qualifiers (in the array name if it refers to an array element), or if varName is unqualified (does not include the names of any containing namespaces) but no procedure is active, varName refers to a namespace variable resolved according to the rules described under NAME RESOLUTION in the namespace manual page.
If a procedure is active and varName is unqualified, then varName refers to a parameter or local variable of the procedure, unless varName was declared to resolve differently through one of the global, variable or upvar commands.
shoot
shoot - args
To be written....
static
static - args
To be written....
string
string - args
Performs one of several string operations, depending on option. The legal options (which may be abbreviated) are:
string bytelength string Returns a decimal string giving the number of bytes used to represent string in memory. Because UTF-8 uses one to three bytes to represent Unicode characters, the byte length will not be the same as the character length in general. The cases where a script cares about the byte length are rare.
In almost all cases, you should use the string length operation (including determining the length of a Tcl byte array value). Refer to the Tcl_NumUtfChars manual entry for more details on the UTF-8 representation.
Compatibility note: it is likely that this subcommand will be withdrawn in a future version of Tcl. It is better to use the encoding convertto command to convert a string to a known encoding and then apply string length to that.
string compare ?-nocase? ?-length int? string1 string2 Perform a character-by-character comparison of strings string1 and string2. Returns -1, 0, or 1, depending on whether string1 is lexicographically less than, equal to, or greater than string2. If -length is specified, then only the first length characters are used in the comparison. If -length is negative, it is ignored. If -nocase is specified, then the strings are compared in a case-insensitive manner.
string equal ?-nocase? ?-length int? string1 string2 Perform a character-by-character comparison of strings string1 and string2. Returns 1 if string1 and string2 are identical, or 0 when not. If -length is specified, then only the first length characters are used in the comparison. If -length is negative, it is ignored. If -nocase is specified, then the strings are compared in a case-insensitive manner.
string first needleString haystackString ?startIndex? Search haystackString for a sequence of characters that exactly match the characters in needleString. If found, return the index of the first character in the first such match within haystackString. If not found, return -1. If startIndex is specified (in any of the forms described in STRING INDICES), then the search is constrained to start with the character in haystackString specified by the index. For example,
string first a 0a23456789abcdef 5
will return 10, but
string first a 0123456789abcdef 11
will 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. charIndex may be specified as described in the STRING INDICES section.
If charIndex is less than 0 or greater than or equal to the length of the string then this command returns an empty string.
string is class ?-strict? ?-failindex varname? string Returns 1 if string is a valid member of the specified character class, otherwise returns 0. If -strict is specified, then an empty string returns 0, otherwise an empty string will return 1 on any class. If -failindex is specified, then if the function returns 0, the index in the string where the class was no longer valid will be stored in the variable named varname. The varname will not be set if string is returns 1. The following character classes are recognized (the class name can be abbreviated):
alnum Any Unicode alphabet or digit character.
alpha Any Unicode alphabet character.
ascii Any character with a value less than \u0080 (those that are in the 7-bit ascii range).
boolean Any of the forms allowed to Tcl_GetBoolean.
control Any Unicode control character.
digit Any Unicode digit character. Note that this includes characters outside of the [0-9] range.
double Any of the valid forms for a double in Tcl, with optional surrounding whitespace. In case of under/overflow in the value, 0 is returned and the varname will contain -1.
entier Any of the valid string formats for an integer value of arbitrary size in Tcl, with optional surrounding whitespace. The formats accepted are exactly those accepted by the C routine Tcl_GetBignumFromObj.
false Any of the forms allowed to Tcl_GetBoolean where the value is false.
graph Any Unicode printing character, except space.
integer Any of the valid string formats for a 32-bit integer value in Tcl, with optional surrounding whitespace. In case of under/overflow in the value, 0 is returned and the varname will contain -1.
list Any proper list structure, with optional surrounding whitespace. In case of improper list structure, 0 is returned and the varname will contain the index of the “element” where the list parsing fails, or -1 if this cannot be determined.
lower Any Unicode lower case alphabet character.
print Any Unicode printing character, including space.
punct Any Unicode punctuation character.
space Any Unicode whitespace character, zero width space (U+200b), word joiner (U+2060) and zero width no-break space (U+feff) (=BOM).
true Any of the forms allowed to Tcl_GetBoolean where the value is true.
upper Any upper case alphabet character in the Unicode character set.
wideinteger Any of the valid forms for a wide integer in Tcl, with optional surrounding whitespace. In case of under/overflow in the value, 0 is returned and the varname will contain -1.
wordchar Any Unicode word character. That is any alphanumeric character, and any Unicode connector punctuation characters (e.g. underscore).
xdigit Any hexadecimal digit character ([0-9A-Fa-f]).
In the case of boolean, true and false, if the function will return 0, then the varname will always be set to 0, due to the varied nature of a valid boolean value.
string last needleString haystackString ?lastIndex? Search haystackString for a sequence of characters that exactly match the characters in needleString. If found, return the index of the first character in the last such match within haystackString. If there is no match, then return -1. If lastIndex is specified (in any of the forms described in STRING INDICES), then only the characters in haystackString at or before the specified lastIndex will be considered by the search. For example,
string last a 0a23456789abcdef 15
will return 10, but
string last a 0a23456789abcdef 9
will return 1.
string length string Returns a decimal string giving the number of characters in string. Note that this is not necessarily the same as the number of bytes used to store the string. If the value is a byte array value (such as those returned from reading a binary encoded channel), then this will return the actual byte length of the value.
string map ?-nocase? mapping string Replaces substrings in string based on the key-value pairs in mapping. mapping is a list of key value key value ... as in the form returned by array get. Each instance of a key in the string will be replaced with its corresponding value. If -nocase is specified, then matching is done without regard to case differences. Both key and value may be multiple characters. Replacement is done in an ordered manner, so the key appearing first in the list will be checked first, and so on. string is only iterated over once, so earlier key replacements will have no affect for later key matches. For example,
string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc
will return the string 01321221.
Note that if an earlier key is a prefix of a later one, it will completely mask the later one. So if the previous example is reordered like this,
string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc
it will return the string 02c322c222c.
string match ?-nocase? pattern string See if pattern matches string; return 1 if it does, 0 if it does not. If -nocase is specified, then the pattern attempts to match against the string in a case insensitive manner. For the two strings to match, their contents must be identical except that the following special sequences may appear in pattern:
- Matches any sequence of characters in string, including a null string.
? Matches any single character in string.
[chars] Matches any character in the set given by chars. If a sequence of the form x-y appears in chars, then any character between x and y, inclusive, will match. When used with -nocase, the end points of the range are converted to lower case first. Whereas {[A-z]} matches “_” when matching case-sensitively (since “_” falls between the “Z” and “a”), with -nocase this is considered like {[A-Za-z]} (and probably what was meant in the first place).
\x Matches the single character x. This provides a way of avoiding the special interpretation of the characters *?[]\ in pattern.
string range string first last Returns a range of consecutive characters from string, starting with the character whose index is first and ending with the character whose index is last. An index of 0 refers to the first character of the string. first and last may be specified as for the index method. If first is less than zero then it is treated as if it were zero, and if last is greater than or equal to the length of the string then it is treated as if it were end. If first is greater than last then an empty string is returned.
string repeat string count Returns string repeated count number of times.
string replace string first last ?newstring? Removes a range of consecutive characters from string, starting with the character whose index is first and ending with the character whose index is last. An index of 0 refers to the first character of the string. First and last may be specified as for the index method. If newstring is specified, then it is placed in the removed character range. If first is less than zero then it is treated as if it were zero, and if last is greater than or equal to the length of the string then it is treated as if it were end. If first is greater than last or the length of the initial string, or last is less than 0, then the initial string is returned untouched.
string reverse string Returns a string that is the same length as string but with its characters in the reverse order.
string tolower string ?first? ?last? Returns a value equal to string except that all upper (or title) case letters have been converted to lower case. If first is specified, it refers to the first char index in the string to start modifying. If last is specified, it refers to the char index in the string to stop at (inclusive). first and last may be specified using the forms described in STRING INDICES.
string totitle string ?first? ?last? Returns a value equal to string except that the first character in string is converted to its Unicode title case variant (or upper case if there is no title case variant) and the rest of the string is converted to lower case. If first is specified, it refers to the first char index in the string to start modifying. If last is specified, it refers to the char index in the string to stop at (inclusive). first and last may be specified using the forms described in STRING INDICES.
string toupper string ?first? ?last? Returns a value equal to string except that all lower (or title) case letters have been converted to upper case. If first is specified, it refers to the first char index in the string to start modifying. If last is specified, it refers to the char index in the string to stop at (inclusive). first and last may be specified using the forms described in STRING INDICES.
string trim string ?chars? Returns a value equal to string except that any leading or trailing characters present in the string given by chars are removed. If chars is not specified then white space is removed (any character for which string is space returns 1, and " ").
string trimleft string ?chars? Returns a value equal to string except that any leading characters present in the string given by chars are removed. If chars is not specified then white space is removed (any character for which string is space returns 1, and " ").
string trimright string ?chars? Returns a value equal to string except that any trailing characters present in the string given by chars are removed. If chars is not specified then white space is removed (any character for which string is space returns 1, and " ").
string wordend string charIndex Returns the index of the character just after the last one in the word containing character charIndex of string. charIndex may be specified using the forms in STRING INDICES. A word is considered to be any contiguous range of alphanumeric (Unicode letters or decimal digits) or underscore (Unicode connector punctuation) characters, or any single character other than these.
string wordstart string charIndex Returns the index of the first character in the word containing character charIndex of string. charIndex may be specified using the forms in STRING INDICES. A word is considered to be any contiguous range of alphanumeric (Unicode letters or decimal digits) or underscore (Unicode connector punctuation) characters, or any single character other than these.
test
test - name description args
To be written....
type
type - what type?
To be written....
unset
unset - -nocomplain? args
This command removes one or more variables. Each name is a variable name, specified in any of the ways acceptable to the set command. If a name refers to an element of an array then that element is removed without affecting the rest of the array. If a name consists of an array name with no parenthesized index, then the entire array is deleted. The unset command returns an empty string as result. If -nocomplain is specified as the first argument, any possible errors are suppressed. The option may not be abbreviated, in order to disambiguate it from possible variable names. The option indicates the end of the options, and should be used if you wish to remove a variable with the same name as any of the options. If an error occurs during variable deletion, any variables after the named one causing the error are not deleted. An error can occur when the named variable does not exist, or the name refers to an array element but the variable is a scalar, or the name refers to a variable in a non-existent namespace.
uplevel
uplevel - level code
All of the arg arguments are concatenated as if they had been passed to concat; the result is then evaluated in the variable context indicated by level. Uplevel returns the result of that evaluation.
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 top-level (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 info level command 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).
The namespace eval and apply commands offer other ways (besides procedure calls) that the Tcl naming context can change. They add a call frame to the stack to represent the namespace context. This means each namespace eval command counts as another call level for uplevel and upvar commands. For example, info level 1 will return a list describing a command that is either the outermost procedure call or the outermost namespace eval command. Also, uplevel #0 evaluates a script at top-level in the outermost namespace (the global namespace).
upvar
upvar - level args
This command arranges for one or more local variables in the current procedure to refer to variables in an enclosing procedure call or to global variables. Level may have any of the forms permitted for the uplevel command, and may be omitted (it defaults to 1). For each otherVar argument, upvar makes the variable by that name in the procedure frame given by level (or at global level, if level is #0) accessible in the current procedure by the name given in the corresponding myVar argument. The variable named by otherVar need not exist at the time of the call; it will be created the first time myVar is referenced, just like an ordinary variable. There must not exist a variable by the name myVar at the time upvar is invoked. MyVar is always treated as the name of a variable, not an array element. An error is returned if the name looks like an array element, such as a(b). OtherVar may refer to a scalar variable, an array, or an array element. Upvar returns an empty string.
The upvar command simplifies the implementation of call-by-name procedure calling and also makes it easier to build new control constructs as Tcl procedures. For example, consider the following procedure:
proc add2 name { upvar $name x set x [expr {$x + 2}] }
If add2 is invoked with an argument giving the name of a variable, 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.
namespace eval is another way (besides procedure calls) that the Tcl naming context can change. It adds a call frame to the stack to represent the namespace context. This means each namespace eval command counts as another call level for uplevel and upvar commands. For example, info level 1 will return a list describing a command that is either the outermost procedure call or the outermost namespace eval command. Also, uplevel #0 evaluates a script at top-level in the outermost namespace (the global namespace).
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.
while
while - test body
The while command evaluates test as an expression (in the same way that expr evaluates its argument). The value of the expression must a proper boolean value; if it is a true value then body is executed by passing it to the Tcl interpreter. Once body has been executed then test is evaluated again, and the process repeats until eventually test evaluates to a false boolean value. Continue commands may be executed inside body to terminate the current iteration of the loop, and break commands may be executed inside body to cause immediate termination of the while command. The while command always returns an empty string.
Note: test should almost always be enclosed in braces. If not, variable substitutions will be made before the while command starts executing, which means that variable changes made by the loop body will not be considered in the expression. This is likely to result in an infinite loop. If test is enclosed in braces, variable substitutions are delayed until the expression is evaluated (before each loop iteration), so changes in the variables will be visible. For an example, try the following script with and without the braces around $x
with
with - -each newtarget code
To be written....
world
world - args
To be written....
- world target? pvp boolean1
Undocumented
- world target? spawn string1 location2
Spawn an enitity of the given type at some location. Returns the entity.
- world target? growtree location1 string2
Undocumented
- world target? effect string1 location2 integer3 integer4
Undocumented
- world target? players
Undocumented
- world target? sound string1 location2 double3 double4
Undocumented