Index: xotcl/doc/tutorial.html
===================================================================
diff -u -rf7894d9be99a8da3a04218abcdb9bd46b6d625c8 -r225b8b992e16760eca2a7fa7bf51533499c7cc84
--- xotcl/doc/tutorial.html	(.../tutorial.html)	(revision f7894d9be99a8da3a04218abcdb9bd46b6d625c8)
+++ xotcl/doc/tutorial.html	(.../tutorial.html)	(revision 225b8b992e16760eca2a7fa7bf51533499c7cc84)
@@ -1,10 +1,10 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
-<!-- $Id: tutorial.html,v 1.1 2004/05/23 22:50:39 neumann Exp $ -->
+<!-- $Id: tutorial.html,v 1.2 2004/07/20 12:57:59 neumann Exp $ -->
 <HTML>
 <HEAD>
 	<TITLE>XOTcl - Tutorial</TITLE>
 	<META NAME="AUTHOR" CONTENT="Gustaf Neumann and Uwe Zdun">
-	<META NAME="DOCNUMBER" CONTENT="1.2.0">
+	<META NAME="DOCNUMBER" CONTENT="1.2.1">
 	<META NAME="CHANGEDBY" CONTENT="Gustaf ">
 <STYLE>
 BODY	{
@@ -98,6 +98,7 @@
 	      Relationships</A> 
 		<LI><A HREF="#meta-classes">Meta-Classes</A>
                 <LI><A HREF="#destroy-logic">Create, Destroy, and Recreate Methods</A>
+	        <LI><A HREF="#non-pos-args">Non-positional Arguments</A>
 	</UL>
         </P>
 	<LI><P STYLE="margin-bottom: 0in"><A HREF="#interceptors">Message
@@ -1650,6 +1651,7 @@
 </pre>
 </p>
 
+
 <H2>
 <A NAME="destroy-logic"></A>Create, Destroy, and Recreate Methods
 </H2>
@@ -1758,8 +1760,150 @@
   <tt>puts</tt> class=[c2 <tt>info</tt> class]
 </pre>
 
+<H2>
+<A NAME="non-pos-args"></A>Non-positional Arguments
+</H2>
+<P>
+<P>
+So far we have introduces methods only with positional arguments: that
+is, the position of an argument in the argument list determines to
+which local variable the argument is bound, when the method is
+invoked. Sometimes non-positional arguments -- arguments that carry
+both a name and a value when the method is invoked -- are
+useful. Before a non-positional argument can be used, it must be
+defined in the method definition using the following syntax:
+</P>
+<pre CLASS="code">
+ <em>className</em> <tt>instproc</tt> methodName <em>?non-pos-args?</em> args body ?assertions
+ <em>objName</em> <tt>proc</tt> methodName <em>?non-pos-args?</em> args body ?assertions
+</pre>
+<P>
+The non-positional arguments are defined with the following syntax:
+</P>
+<pre CLASS="code">
+ {-name?:checkoption1, checkoption2, ...? default value} {-name?:checkoption1, checkoption2, ...? ?default value?} ...
+</pre>
+<p>
+Only the name of the non-positional argument is really required, all
+other parts of this syntax are optional.
+</p>
+<p>
+Let's consider a simple example, where a method with two
+non-positional args is defined; one has only a name ("a"), and one has
+a name and a default value (b):
+</p>
+<pre CLASS="code">
+ <tt>Object</tt> o
+ o <tt>proc</tt> y {-a {-b {1 2 3}}} {x y} {
+     puts "$a $b $x $y"
+ }
+</pre><P>
+We can invoke this method as follows:
+</p>
+<pre CLASS="code">
+ o y -b 4 5 -a 1 3 4
+</pre><P>
 
+Here, the order of "a" and "b" can be changed; hence the name
+non-positional arguments.  As "b" has a default value, we do not need
+to provide a value for it. In the following invocation "b" has the
+value "1 2 3":
+</p>
+<pre CLASS="code">
+ o y -a 1 3 4
+</pre><P>
 
+The ordinary arguments start after the last non-positional argument
+(here: "3 4").  We can explicitly end the non-positional arguments by
+using "--". This is useful if we want to provide arguments that contain dashes ("-"), e.g.:
+</p>
+<pre CLASS="code">
+ o y -a 1 -- -b -c
+</pre><P>
+
+Sometimes we want to check or control the non-positional
+arguments. For instance, in the above invocation, we might want to
+check that "a" is not forgotten, because otherwise the method cannot
+execute properly. This is the role of the checkoptions. There are two
+predefined checkoptions: "required" and "boolean". "required" checks
+whether a non-positional argument is given, "boolean" checks that a
+non-positional argument is of boolean type. For instance:
+</p>
+<pre CLASS="code">
+<tt>Class</tt> P
+ P <tt>instproc</tt> y {-a:required {-b:boolean {true}}} {} {
+     puts "$a $b"
+ }
+ P p
+</pre><P>
+
+This method requires "a", and "b" needs to be of type boolean (is has
+the default value "true"). This invocation is valid:
+</p>
+<pre CLASS="code">
+ p y -a 1 -b 0
+</pre><P>
+
+This invocation is invalid, because "a" is missing, and "b" is not a
+Tcl boolean type:
+</p>
+<pre CLASS="code">
+ p y -b " a b v"
+</pre><P>
+
+The checkoptions are extensible. In fact, they are defined in an
+object "xotcl::nonPosArgs". We can extend this object with new
+methods and we can provide other checkobjects. A check option method
+has the following syntax:
+</P>
+<pre CLASS="code">
+ <em>object|class</em> <tt>proc|instproc</tt> methodName {?optional arguments argName args} {
+  ...
+ }
+</pre>
+<p>
+
+"argName" is here used to denote the name of the argument, and "args"
+get the argument's current value after all non-positional arguments
+have been applied. If the argument it is not given and has no default
+value, "args" is empty.
+
+</p>
+
+<p>
+In seldom cases, more flexiblity might be required. Using the
+checkoption "checkobj" we can switch the object that is used for
+checking the options. This can be done at any place in the checkoption
+list. The following example defines new checkoptions in a separate
+object and switches to this object for checking. Then the check is
+switched back to "xotcl::nonPosArgs" to invoke the predefined option
+"required":
+
+</P>
+<pre CLASS="code">
+Object colorchecker
+colorchecker proc color {a b c argName args} {
+    puts "$a $b $c"
+}
+colorchecker proc reddish {argName args} {
+    puts "reddish"
+}
+o proc color {{{-color:checkobj colorchecker,color must be red,reddish,checkobj xotcl::nonPosArgs, required} red}} {} {
+    puts "$b $arg"
+}
+</pre></p>
+
+Of course, the non-positional arguments can also be introspected. The
+following "info" options return the non-positional arguments of a
+method:
+
+</P>
+<pre CLASS="code">
+ <em>objName</em> <tt>info</tt> <em>nonposargs</em> methodName
+ <em>className</em> <tt>info</tt> <em>instnonposargs</em> methodName
+</pre></p>
+
+
 <!-- PAGE BREAK -->
 
 <TABLE COLS=2 WIDTH=100% BORDER=0 CELLPADDING=2 CELLSPACING=0 BGCOLOR="#000055">
