Implement TIP #288

See http://www.tcl.tk/cgi-bin/tct/tip/288.html
Args and optional args may be to the left of required args

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'+