native tcl functions commonly used in Nuke

The following is a list of native tcl functions. More...

Functions

 parray name) toggle(knob) start(url) append(variable value...
 Print all the values in a tcl "array" variable.
 array option arrayName arg...
 This command performs one of several operations on the variable given by arrayName.
 break
 Exit a 'while' of 'foreach' loop.
 catch command varName
 The catch command may be used to prevent errors from aborting command interpretation.
 cd directory
 Change the current working directory to dirName.
 close fieldId
 Closes the file given by fileId.
 concat ...
 This command treats each argument as a list and concatenates them into a single list.
 continue
 Continue at the end of a loop.
 eof channelId
 Returns 1 if an end-of-file condition has occurred on fileId, 0 otherwise.
 error message errorInfo errorCode
 Returns a TCL_ERROR code, which causes command interpretation to be unwound.
 eval arg...
 Evaluate a list of tcl functions.
 exec switches arg...
 execute tcl commands
 exit returnCode
 Terminate the process, returning returnCode to the system as the exit status.
 expr expression
 Evaluate an expression.
 fblocked channelId
 Checks, if a tcl stream would block if read now.
 fconfigure channelId optionName value optionName value...
 Additional configuration of tcl streams.
 file option name arg...
 This command provides several operations on a file's name or attributes.
 flush channelId
 Flushes any output that has been buffered for fileId.
 for start test next command
 For is a looping command, similar in structure to the C language for statement.
 foreach varList list varList list...command
 Loop through all elements in a list.
 format formatString arg...
 Generate a formatted text string.
 gets channelId varName
 Read a line of data from a tcl stream.
 glob switches name...
 Filename pattern matching.
 global varName...
 declare global variables while in procedure.
 if expression command elseif command2 else commandn
 Conditional execution of commands.
 incr varName increment
 Increment a numeric variable by one.
 info option arg...
 This command provides information about various internals of the Tcl interpreter.
 join list joinString
 join elements of a list using string a as a seperator.
 lappend varName value...
 Append values to the left of a variable.
 lindex list index
 Return the n'th list of a tcl list.
 linsert list index element...
 Insert elements before the indexed element in a list.
 list word...
 This command returns a list comprised of all the args, or an empty string if no arguments are specified.
 llength list
 Returns the number of elements in a list.
 lrange list first last
 This command will return a new list consisting of elements first through last, inclusive.
 lreplace list first last element...
 lreplace returns a new list formed by replacing one or more elements of list
 lsearch mode list pattern
 This command searches the elements of list to see if one of them matches pattern.
 lsort mode list
 This command sorts the elements of list, returning a new list in sorted order.
 open fileName access permissions
 This command opens a file and returns an identifier.
 pid fieldID
 Return the ID of the current process.
 proc name args body
 Create a new tcl Procedure.
 puts -nonewline channelId string
 Writes the characters given by string to the file given by fileId.
 pwd
 Return the current working directory.
 read -nonewline channelId numBytes
 read a number of bytes from a tcl stream
 regexp switches exp string matchVar subMatchVar...
 Determines whether the regular expression exp matches part or all of string and returns 1 if it does, 0 if it doesn't.
 regsub switches exp string subSpec varName
 This command matches the regular expression exp against string.
 rename oldName newName
 Rename a command.
 return value
 Return immediately from the current procedure.
 scan string format varName...
 Parse an input string.
 seek channelId offset origin
 Change the current access position for fileId.
 set varName newValue
 Returns the value of variable varName.
 socket -server command-myaddr addr-myport myport-async host port
 Open a tcl network channel.
 source filename
 Interprete the contents of a file as a tcl script.
 split string splitChars
 Split a string into a list.
 string option arg...
 Performs one of several string operations, depending on option.
 subst option string
 Evaluate elements of a string.
 switch switches string pattern body...default body
 The switch command matches its string argument against each of the pattern arguments in order.
 tell channelId
 Returns a decimal string giving the current access position in fileId.
 time command count
 This command will call the Tcl interpreter count times to evaluate script.
 trace option arg...
 trace access to a variable.
 unset varName...
 This command removes one or more variables.
 while expression command
 Repeatedly execute a command while expression is true.

Detailed Description

The following is a list of native tcl functions.

This list is meant as a quick reference to commomnly used tcl functions. Nuke's builtin tcl interpreter suports all commands listed below.


Function Documentation

parray ( name 

Print all the values in a tcl "array" variable.

  • name: name of variable

Prints every entry in a variable accessed using $name(index) syntax, such as env. This is similar to the parray provided in many tcl implementations but has been modified to to not print the equal sign and produce legal syntax.

Flip a true/false knob on all selected nodes

  • knob: name of knob

For all selected nodes, the given knob (if it exists) is set to the same value, so they all match. The value is chosen by taking the current value from the first node and inverting it.

Open a URL or file in system's browser

  • url: what to open

Run the system's browser and open the named URL with it. Depending on how your system is setup you may be able to launch other programs and open other types of files with this.

Windows version cannot handle spaces in the url.

You can override how it does this by setting $env(BROWSER) to the program and arguments you want to run, the URL is added as another argument. The default value on Windows is "rundll32.exe url.dll,FileProtocolHandler" and the default value on Unix is "konqueror".

Append values to a variable

  • variable
  • values

Append all of the value arguments to the current value of variable varName. If varName doesn't exist, it is given a value equal to the concatenation of all the value arguments. This command provides an efficient way to build up long variables incrementally. For example, ``append a $b'' is much more efficient than ``set a $a$b'' if $a is long.

array ( option arrayName  arg...

This command performs one of several operations on the variable given by arrayName.

  • option (see below)
  • array
  • ...

ArrayName must be the name of an existing array variable.

  • array anymore arrayName searchId: Returns 1 if there are any more elements left to be processed in an array search
  • array donesearch arrayName searchId: This command terminates an array search and destroys all the state associated with that search.
  • array names arrayName: Returns a list containing the names of all of the elements in the array.
  • 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.
  • array size arrayName: Returns a decimal string giving the number of elements in the array.
  • array startsearch arrayName: This command initializes an element-by-element search through the array given by arrayName.
break (

Exit a 'while' of 'foreach' loop.

This command may be invoked only inside the body of a looping command such as for or foreach or while. It returns a TCL_BREAK code to signal the innermost containing loop command to return immediately.

See also:
while, foreach
catch ( command  varName

The catch command may be used to prevent errors from aborting command interpretation.

  • command
  • optional varname

Catch calls the Tcl interpreter recursively to execute script, and always returns a TCL_OK code, regardless of any errors that might occur while executing script.

See also:
error
cd ( directory 

Change the current working directory to dirName.

  • optional directory

Change the current working directory to dirName, or to the home directory if dirName is not given. If dirName starts with a tilde, then tilde-expansion is done as described for Tcl_TildeSubst. Returns an empty string.

See also:
close ( fieldId 

Closes the file given by fileId.

  • fieldId

FileId must be the return value from a previous invocation of the open command; after this command, it should not be used anymore. If fileId refers to a command pipeline instead of a file, then close waits for the children to complete.

See also:
open
concat (   ...

This command treats each argument as a list and concatenates them into a single list.

  • arglist

It also eliminates leading and trailing spaces in the arg's and adds a single separator space between arg's. It permits any number of arguments.

See also:
join, lists
continue (

Continue at the end of a loop.

This command may be invoked only inside the body of a looping command such as for or foreach or while. It returns a TCL_CONTINUE code to signal the innermost containing loop command to skip the remainder of the loop's body but continue with the next iteration of the loop.

See also:
foreach, while, break
eof ( channelId 

Returns 1 if an end-of-file condition has occurred on fileId, 0 otherwise.

  • channelId

FileId must have been the return value from a previous call to open, or it may be stdin, stdout, or stderr to refer to one of the standard I/O channels.

See also:
open, close
error ( message errorInfo  errorCode

Returns a TCL_ERROR code, which causes command interpretation to be unwound.

  • message
  • optional errorInfo
  • optional errorCode

Message is a string that is returned to the application to indicate what went wrong. If the info argument is provided and is non-empty, it is used to initialize the global variable errorInfo. If the code argument is present, then its value is stored in the errorCode global variable.

See also:
exit
eval ( arg... 

Evaluate a list of tcl functions.

  • arg

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).

See also:
exec, expr
exec ( switches  arg...

execute tcl commands

  • switches
  • arg_list

This command treats its arguments as the specification of one or more subprocesses to execute. The arguments take the form of a standard shell pipeline where each arg becomes one word of a command, and each distinct command becomes a subprocess.

See also:
eval
exit ( returnCode 

Terminate the process, returning returnCode to the system as the exit status.

  • returnCode

If returnCode isn't specified then it defaults to 0.

See also:
catch, exec
expr ( expression 

Evaluate an expression.

  • expression

Concatenates arg's, evaluates the result as a Tcl expression, and returns the value. The operators permitted in Tcl expressions are a subset of the operators permitted in C expressions, and they have the same meaning and precedence as the corresponding C operators.

Nuke adds many application specific expressions to tcl.

See also:
eval, exec
fblocked ( channelId 

Checks, if a tcl stream would block if read now.

  • channelId
See also:
open, close, eof
fconfigure ( channelId optionName value optionName  value...

Additional configuration of tcl streams.

  • channleId
  • option parameters
See also:
open, close
file ( option name  arg...

This command provides several operations on a file's name or attributes.

  • option
  • name
  • arguments depending on option

Name is the name of a file; if it starts with a tilde, then tilde substitution is done before executing the command.

Option can be one of atime, dirname, executable, exists, extension, isdirectory, isfile, lstat, mtime, owned, readable, readlink, rootname, size, stat, tail, type, writable

See also:
open, close, eof
flush ( channelId 

Flushes any output that has been buffered for fileId.

  • channelId

FileId must have been the return value from a previous call to open, or it may be stdout or stderr to access one of the standard I/O streams; it must refer to a file that was opened for writing. The command returns an empty string.

See also:
open, file
for ( start test next  command

For is a looping command, similar in structure to the C language for statement.

  • start
  • test
  • next
  • command

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.

See also:
foreach, while, continue, break
foreach ( varList list varList list...  command

Loop through all elements in a list.

  • varlist list, can be repeated

In this command varname is the name of a variable, list is a list of values to assign to varname, and body is a Tcl script. For each element of list, foreach assigns the contents of the field to varname, then calls the Tcl interpreter to execute body.

See also:
for, continue, break
format ( formatString  arg...

Generate a formatted text string.

  • formatString
  • arg_list

This command generates a formatted string in the same way as the ANSI C sprintf procedure. FormatString indicates how to format the result, using % conversion specifiers as in sprintf, and the additional arguments provide values to be substituted.

The most commonly used format descriptor in Nuke is 04d to describe four-digit frame number.

See also:
puts, scan
gets ( channelId  varName

Read a line of data from a tcl stream.

  • channelId
  • optional varName

This command reads the next line from the file given by fileId and discards the terminating newline character. If varName is specified then the line is placed in the variable by that name and the return value is a count of the number of characters read.

See also:
open, file, eof
glob ( switches  name...

Filename pattern matching.

  • optional switches
  • name_list

This command performs file name "globbing" in a fashion similar to the csh shell. It returns a list of the files whose names match any of the pattern arguments.

See also:
file, open
global ( varName... 

declare global variables while in procedure.

  • varName_list

This command is ignored unless a Tcl procedure is being interpreted. If so then it declares the given varname's to be global variables rather than local ones. For the duration of the current procedure, any reference to any of the varnames will refer to the global variable by the same name.

See also:
proc
if ( expression command elseif command2 else  commandn

Conditional execution of commands.

  • expr1
  • command1
  • optional: elseif expr2 command2
  • optional: else commandn

The if command evaluates expression. The value of the expression must be a boolean (0 is false and anything is true); if it is true then command1 is executed. Otherwise expr2 is evaluated and if true, command2 is is executed, and so on.

See also:
for, foreach
incr ( varName  increment

Increment a numeric variable by one.

  • variable
  • optional increment
See also:
puts
info ( option  arg...

This command provides information about various internals of the Tcl interpreter.

  • option
  • arg_list

Valid options are args, body, cmdcount, commands, complete, default, exists, globals, level, library, locals, patchlevel, procs, script, tclversion, vars

join ( list  joinString

join elements of a list using string a as a seperator.

  • list
  • optional: string

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.

See also:
append, split
lappend ( varName  value...

Append values to the left of a variable.

  • varName
  • argList
See also:
append
lindex ( list  index

Return the n'th list of a tcl list.

  • list
  • index

This command treats list as a Tcl list and returns the index'th element from it (0 refers to the first element of the list).

linsert ( list index  element...

Insert elements before the indexed element in a list.

  • list
  • index
  • element_list

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.

See also:
append, lappend, lindex
list ( word... 

This command returns a list comprised of all the args, or an empty string if no arguments are specified.

  • words

Braces and backslashes get added as necessary, so that the index command may be used on the result to re-extract the original arguments, and also so that eval may be used to execute the resulting list, with arg1 comprising the command's name and the other args comprising its arguments.

See also:
lindex
llength ( list 

Returns the number of elements in a list.

  • list
See also:
list
lrange ( list first  last

This command will return a new list consisting of elements first through last, inclusive.

  • list
  • first
  • last

Last may be end to refer to the last element of the list. If first is less than zero, it is treated as if it were zero. If last is greater than or equal to the number of elements in the list, then it is treated as if it were end.

lreplace ( list first last  element...

lreplace returns a new list formed by replacing one or more elements of list

  • list
  • first
  • last
  • element_list
lsearch ( mode list  pattern

This command searches the elements of list to see if one of them matches pattern.

  • mode, optional: -exact, -glob, -regexp
  • list
  • pattern

If so, the command returns the index of the first matching element. If not, the command returns -1

lsort ( mode  list

This command sorts the elements of list, returning a new list in sorted order.

  • mode, optional: -ascii, -integer, -real, -command, -increasing, -decreasing
  • list

By default ASCII sorting is used with the result returned in increasing order. However, any of the switches may be specified before list to control the sorting process.

See also:
open ( fileName access  permissions

This command opens a file and returns an identifier.

  • filename
  • optional access
  • optional permissions

Possible values for access are r, r+, w, w+, a, a+. Permission can be set in octal notation. The default it 0666.

See also:
read, put, close, eof
pid ( fieldID 

Return the ID of the current process.

  • optional fieldId

If the fileId argument is given then the pid command will return a list whose elements are the process identifiers of all the processes in the pipeline, in order.

proc ( name args  body

Create a new tcl Procedure.

  • name
  • args
  • body
puts ( -nonewline channelId  string

Writes the characters given by string to the file given by fileId.

  • optional -nonewline
  • optional channelId
  • string

FileId must have been the return value from a previous call to open, or it may be stdout or stderr to refer to one of the standard I/O channels.

See also:
open, file, flush
read ( -nonewline channelId  numBytes

read a number of bytes from a tcl stream

  • optional -nonewline
  • channelId
  • optional bytes: number of bytes to read, default reads to end of file
See also:
open, close, eof
regexp ( switches exp string matchVar  subMatchVar...

Determines whether the regular expression exp matches part or all of string and returns 1 if it does, 0 if it doesn't.

  • optional switches: -nocase or -indices
  • expression
  • string
  • optional matchVar
  • optional subMatchVar_list

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.

regsub ( switches exp string subSpec  varName

This command matches the regular expression exp against string.

  • swicthes: -all or -nocase
  • exp: regular expression
  • string
  • subSpec
  • varName

It copies string to the variable whose name is given by varName. The command returns 1 if there is a match and 0 if there isn't. If there is a match, then while copying string to varName the portion of string that matched exp is replaced with subSpec.

See also:
regexp
rename ( oldName  newName

Rename a command.

  • oldName
  • newName

Rename the command that used to be called oldName so that it is now called newName. If newName is an empty string then oldName is deleted. The rename command returns an empty string as result.

return ( value 

Return immediately from the current procedure.

  • optional value

Return immediately from the current procedure or top-level command or source command, with string as the return value.

See also:
exit, proc
scan ( string format  varName...

Parse an input string.

  • string
  • format
  • variable_list

This command parses fields from an input string in the same fashion as the ANSI C sscanf procedure and returns a count of the number of fields sucessfully parsed.

Nuke uses the format 04d to read image number in a four digit format.

See also:
format
seek ( channelId offset  origin

Change the current access position for fileId.

  • channelId
  • offset
  • origin, optional: start, current or end

The offset and origin arguments specify the position at which the next read or write will occur for fileId. Offset must be an integer and origin must be one of the above.

See also:
open, file, gets, read
set ( varName  newValue

Returns the value of variable varName.

  • varName
  • optional newValue

If value is specified, then set the value of varName to value, creating a new variable if one doesn't already exist, and return its value.

See also:
puts
socket ( -server command-myaddr addr-myport myport-async host  port

Open a tcl network channel.

Format: socket ?-myaddr addr? ?-myport myport? ?-async? host port or socket -server command ?-myaddr addr? port

See also:
open
source ( filename 

Interprete the contents of a file as a tcl script.

  • filename

Read file fileName and pass the contents to the Tcl interpreter as a script to evaluate in the normal fashion. The return value from source is the return value of the last command executed from the file.

See also:
exec
split ( string  splitChars

Split a string into a list.

  • list
  • optional splitChars

Returns a list created by splitting string at each character that is in the splitChars argument. Each element of the result list will consist of the characters from string that lie between instances of the characters in splitChars.

See also:
append, join
string ( option  arg...

Performs one of several string operations, depending on option.

  • option
  • arglist

Valid options are: compare, first, index, last, length, match, range, tolower, toupper, trim, trimleft, trimright.

subst ( option  string

Evaluate elements of a string.

  • options: -nobackslashes, -nocommands, or -novariables
  • string

Replaces tcl variables, commands, and quoting in a string (such as one read from a file) with the correct expansions.

switch ( switches string pattern body...default  body

The switch command matches its string argument against each of the pattern arguments in order.

  • switches: -exact, -glob, -regexp

As soon as it finds a pattern that matches string it evaluates the following body argument by passing it recursively to the Tcl interpreter and returns the result of that evaluation. If the last pattern argument is default then it matches anything.

See also:
if
tell ( channelId 

Returns a decimal string giving the current access position in fileId.

  • channelId
See also:
open, file, seek
time ( command  count

This command will call the Tcl interpreter count times to evaluate script.

  • command
  • optional count

It will then return a string of the form 503 microseconds per iteration which indicates the average amount of time required per iteration, in microseconds. Time is measured in elapsed time, not CPU time.

trace ( option  arg...

trace access to a variable.

  • option
  • variableList

This command causes Tcl commands to be executed whenever certain operations are invoked. At present, only variable tracing is implemented. The legal option's are:

  • r: Invoke command whenever the variable is read.
  • w: Invoke command whenever the variable is written.
  • u: Invoke command whenever the variable is unset.
unset ( varName... 

This command removes one or more variables.

  • varaiableList

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.

See also:
set, puts
while ( expression  command

Repeatedly execute a command while expression is true.

  • expression
  • command

The while command evaluates expression. If expression is a true value then body is executed by passing it to the Tcl interpreter.

See also:
for, foreach, break, continue