diff options
Diffstat (limited to 'doc/jim_tcl.txt')
-rw-r--r-- | doc/jim_tcl.txt | 154 |
1 files changed, 96 insertions, 58 deletions
diff --git a/doc/jim_tcl.txt b/doc/jim_tcl.txt index 7ac6e3f..8212779 100644 --- a/doc/jim_tcl.txt +++ b/doc/jim_tcl.txt @@ -74,6 +74,7 @@ Since v0.61: 12. Add 'info nameofexecutable' and 'info returncodes' 13. Allow 'catch' to determine what return codes are caught 14. Allow 'incr' to increment an unset variable by first setting to 0 +15. Allow 'args' and optional arguments to the left or required arguments in 'proc' TCL INTRODUCTION ----------------- @@ -953,7 +954,96 @@ procedures. A Tcl procedure can be invoked just like any other Tcl command (it has a name and it receives one or more arguments). The only difference is that its body isn't a piece of C code linked into the program; it is a string containing one or more other -Tcl commands. See the 'proc' command for information on +Tcl commands. + +The 'proc' command is used to create a new Tcl command procedure: + + +*proc* 'name args ?statics? body'+ + +The new command is name *name*, and it replaces any existing command +there may have been by that name. Whenever the new command is +invoked, the contents of *body* will be executed by the Tcl +interpreter. + +*args* specifies the formal arguments to the procedure. +It consists of a list, possibly empty, of the following +argument specifiers: + ++name+:: + Required Argument - A simple argument name. + ++name default+:: + Optional Argument - A two-element list consisting of the + argument name, followed by the default value, which will + be used if the corresponding argument is not supplied. + ++*args*+:: + Variable Argument - The special name 'args', which is + assigned all remaining arguments (including none). The + variable argument may only be specified once. + +Arguments must be provided in the following order, any of which +may be omitted: + +1. Required Arguments (Left) +2. Optional Arguments +3. Variable Argument +4. Required Arguments (Right) + +When the command is invoked, a local variable will be created for each of +the formal arguments to the procedure; its value will be the value +of corresponding argument in the invoking command or the argument's +default value. + +Arguments with default values need not be specified in a procedure +invocation. However, there must be enough actual arguments for all +required arguments, and there must not be any extra actual arguments +(unless the Variable Argument is specified). + +Actual arguments are assigned to formal arguments as follows: +1. Left Required Arguments are assigned from the left +2. Right Required Arguments are assigned from the right +3. Default Arguments are assigned from the left, following the Left Required Arguments. +4. A list is formed from any remaining arguments, which are then + are assigned to the 'args' Variable Argument (if specified). The list will be empty + if there are no remaining arguments. + +When *body* is being executed, variable names normally refer to local +variables, which are created automatically when referenced and deleted +when the procedure returns. One local variable is automatically created +for each of the procedure's arguments. Global variables can be +accessed by invoking the 'global' command or via the '::' prefix. + +*New in Jim* + +In addition to procedure arguments, Jim procedures may declare static variables. +These variables scoped to the procedure and initialised at procedure definition. +Either from the static variable definition, or from the enclosing scope. + +Consider the following example: + + set a 1 + proc a {} {a {b 2}} { + set c 1 + puts "$a $b $c" + incr a + incr b + incr c + } + . a + 1 2 1 + . a + 2 3 1 + +The static variable *a* has no initialiser, so it is initialised from +the enclosing scope with the value 1. (Note that it is an error if there +is no variable with the same name in the enclosing scope). However *b* +has an initialiser, so it is initialised to 2. + +Unlike a local variable, the value of a static variable is retained across +invocations of the procedure. + +See the 'proc' command for information on how to define procedures and what happens when they are invoked. VARIABLES - SCALARS AND ARRAYS @@ -2565,36 +2655,13 @@ proc ~~~~ +*proc* 'name args ?statics? body'+ -The 'proc' command creates a new Tcl command procedure, *name*, replacing -any existing command there may have been by that name. Whenever the -new command is invoked, the contents of *body* will be executed by the +The 'proc' command creates a new Tcl command procedure, *name*. +When the new command is invoked, the contents of *body* will be executed. Tcl interpreter. *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. braces and backslashes -may be used in the usual way to specify complex default values. - -When *name* is invoked, a local variable will be created for each of -the formal arguments to the procedure; its value will be the value -of corresponding argument in the invoking command or the argument's -default value. Arguments with default values need not be specified in -a procedure invocation. However, there must be enough actual arguments -for all the formal arguments that don't have defaults, and there must -not be any extra actual arguments. There is one special case to permit -procedures with variable numbers of arguments. If the last formal -argument has the name 'args', then a call to the procedure may contain -more actual arguments than the procedure has formals. In this case, -all of the actual arguments starting at the one that would be assigned to -'args' are combined into a list (as if the 'list' command had been used); -this combined value is assigned to the local variable 'args'. +If specified, *static*, declares static variables which are bound to the +procedure. -When *body* is being executed, variable names normally refer to local -variables, which are created automatically when referenced and deleted -when the procedure returns. One local variable is automatically created -for each of the procedure's arguments. Global variables can be -accessed by invoking the 'global' command or via the '::' prefix. +See PROCEDURES for detailed information about Tcl procedures. The 'proc' command returns the null string. When a procedure is invoked, the procedure's return value is the value specified in a 'return' command. @@ -2604,35 +2671,6 @@ 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. -*New in Jim* - -In addition to procedure arguments, Jim procedures may declare static variables. -These variables scoped to the procedure and initialised at procedure definition. -Either from the static variable definition, or from the enclosing scope. - -Consider the following example: - - set a 1 - proc a {} {a {b 2}} { - set c 1 - puts "$a $b $c" - incr a - incr b - incr c - } - . a - 1 2 1 - . a - 2 3 1 - -The static variable *a* has no initialiser, so it is initialised from -the enclosing scope with the value 1. (Note that it is an error if there -is no variable with the same name in the enclosing scope). However *b* -has an initialiser, so it is initialised to 2. - -Unlike a local variable, the value of a static variable is retained across -invocations of the procedure. - puts ~~~~ +*puts* ?*-nonewline*? '?fileId? string'+ |