Index: library/xotcl/doc/langRef.xotcl =================================================================== diff -u -r2a955681817e4db4776d7ae904babe8053c5ad74 -rb9fcdec2a4d614ee624d548218df4719cdb27049 --- library/xotcl/doc/langRef.xotcl (.../langRef.xotcl) (revision 2a955681817e4db4776d7ae904babe8053c5ad74) +++ library/xotcl/doc/langRef.xotcl (.../langRef.xotcl) (revision b9fcdec2a4d614ee624d548218df4719cdb27049) @@ -27,103 +27,103 @@ XOTcl contains the following predefined primitives (Tcl commands):
<@tt>self<@/tt>
-
computes callstack related information. +
computes callstack related information. It can be used in the following ways: <@UL> <@LI><@TT>self - returns the name - of the object, which is currently in execution. If it is - called from outside of a proc, it returns the - error message ``<@TT>Can't find self''. + of the object, which is currently in execution. If it is + called from outside of a proc, it returns the + error message ``<@TT>Can't find self''. <@LI><@TT>self class - the self command with a given argument <@TT>class returns the name of the - class, which holds the currently executing instproc. Note, that this + class, which holds the currently executing instproc. Note that this may be different to the class of the current object. If it is called - from a proc it returns an empty string. + from a proc it returns an empty string. <@LI><@TT>self proc - the self command with a given argument <@TT>proc returns the name of the currently executing proc or - instproc. - <@li><@TT>self callingclass: Returns class name of the - class that has called the executing method. - <@li><@TT>self callingobject: Returns object name of - the object that has called the executing method. - <@li><@TT>self callingproc: Returns proc name of - the method that has called the executing method. - <@li><@TT>self calledclass: Returns class name of the - class that holds the target proc (in mixins and filters). - <@li><@TT>self calledproc: Returns method - name of the target proc (only applicable - in a filter). - <@li><@TT>self isnextcall: Return 1 if this method - was invoked via next, otherwise 0 - <@li><@TT>self next: Return the - "next" method on the precedence path as a string. - <@li><@TT>self filterreg: In a filter: returns the name - of the object/class on which the filter is registered. Returns either - 'objName filter filterName' or 'className instfilter filterName'. + instproc. + <@li><@TT>self callingclass: Returns class name of the + class that has called the executing method. + <@li><@TT>self callingobject: Returns object name of + the object that has called the executing method. + <@li><@TT>self callingproc: Returns proc name of + the method that has called the executing method. + <@li><@TT>self calledclass: Returns class name of the + class that holds the target proc (in mixins and filters). + <@li><@TT>self calledproc: Returns method + name of the target proc (only applicable + in a filter). + <@li><@TT>self isnextcall: Return 1 if this method + was invoked via next, otherwise 0 + <@li><@TT>self next: Return the + "next" method on the precedence path as a string. + <@li><@TT>self filterreg: In a filter: returns the name + of the object/class on which the filter is registered. Returns either + 'objName filter filterName' or 'className instfilter filterName'. - <@li><@TT>self callinglevel: Returns the calling level, from where - the actual proc was called from. Intermediary next calls are ignored - in this computation. The level is returned in a form - it can be used as first argument in <@TT>uplevel or <@TT>upvar. + <@li><@TT>self callinglevel: Returns the calling level, from where + the actual proc was called from. Intermediary next calls are ignored + in this computation. The level is returned in a form + it can be used as first argument in <@TT>uplevel or <@TT>upvar. - <@li><@TT>self activelevel: Returns the level, from where - the actual proc was invoked from. This might be the calling level or a next - call, whatever is higher in the stack. The level is returned in a form - it can be used as first argument in <@TT>uplevel or <@TT>upvar. + <@li><@TT>self activelevel: Returns the level, from where + the actual proc was invoked from. This might be the calling level or a next + call, whatever is higher in the stack. The level is returned in a form + it can be used as first argument in <@TT>uplevel or <@TT>upvar. <@/UL> <@/p>
<@tt>my methodName<@/tt>
-
is a short form for <@tt>[self] methodName and can only be - called in a context of an instproc or an method specific proc. It allows certain +
is a short form for <@tt>[self] methodName and can only be + called in a context of an instproc or a method specific proc. It allows certain optimizations and shorter to write. <@/p><@p> <@tt>next <@/tt>
invokes the next shadowed (same-named) method on the precedence path and returns its result. If <@tt>next is called without arguments, the arguments of the current method - are passed through the called method. If <@tt>next is + are passed through the called method. If <@tt>next is invoked with the flag <@tt>--noArgs, the shadowed method - is called without arguments. If other arguments are specified + is called without arguments. If other arguments are specified for next, these will be used for the call. <@/dd>
<@tt>myvar varName
returns the fully qualified variable name of the specified - variable.

+ variable.

<@tt>myproc methodName ?args?
-
calls the specified XOTcl method without the need - of using "<@tt>[list [self] methodName ...]".

+

calls the specified XOTcl method without the need + of using "<@tt>[list [self] methodName ...]".

<@tt>::xotcl::alias class|obj methodName ?-objscope? ?-per-object? cmdName
can be used to register a predefined C-implemented Tcl command as - method <@tt>methodName. - The option <@tt>-objscope has the same meaning as for forwarder - (instance variables of the calling object appear in the local scope of - the Tcl command), <@tt>-per-object has the same meaning as for - the method <@tt>method (when used on a class, the method is registered for the - class object only, but not for the instances). This command - can be used to bootstrap xotcl (when e.g. no methods are available).

+ method <@tt>methodName. + The option <@tt>-objscope has the same meaning as for forwarder + (instance variables of the calling object appear in the local scope of + the Tcl command), <@tt>-per-object has the same meaning as for + the method <@tt>method (when used on a class, the method is registered for the + class object only, but not for the instances). This command + can be used to bootstrap xotcl (when e.g. no methods are available).

- -
::xotcl::configure filter ?on|off?<@/tt>
+ +
::xotcl::configure filter ?on|off?<@/tt>
allows one to turn on or off filters globally for the current interpreter. By default, the filter state is turned off. - This function returns the old filter state. + This function returns the old filter state. This function is needed for the serializer that is intended to serialize the objects classes independent of filter settings.

-
<@tt>::xotcl::configure softrecreate ?on|off?<@/tt>
+
<@tt>::xotcl::configure softrecreate ?on|off?<@/tt>
allows one to control what should happen, when an object / a class is recreated. Per default it is set off, which means that the object/class is destroyed - and all relations (e.g. subclass/superclass) to other + and all relations (e.g. subclass/superclass) to other objects/classes are destroyed as well. If <@tt>softrecreate is set, the object is reseted, but not destroyed, the relations are kept. This is important, when e.g. reloading a file @@ -138,11 +138,11 @@ set, the structure remains unchanged.
-
<@tt>::xotcl::finalize<@/tt>
+
<@tt>::xotcl::finalize<@/tt>
Delete all XOTcl objects and classes and free all associated memory.

This command has the only purpose to delete all objects and classes - of an interpreter in a multi-threaded environment at a safe time. + of an interpreter in a multi-threaded environment at a safe time.

Background: when XOTcl is used in a threaded environment such as for example in AOLserver, one has to take care that the deletion @@ -157,7 +157,7 @@ call ::xotcl::finalize in the "delete trace" in AOLserver (as it happens in OpenACS).

- Note, that ::xotcl::finalize is not intended for application programs. + Note that ::xotcl::finalize is not intended for application programs.

@@ -170,7 +170,7 @@ ## @ Class Object { description { - This class holds the pre-defined methods available for all XOTcl + This class holds the pre-defined methods available for all XOTcl objects. All these methods are also available on classes. } } @@ -182,7 +182,7 @@ } { Description { Specify an abstract method for class/object with arguments. - + An abstract method specifies an interface and returns an error, if it is invoked directly. Sub-classes or mixins have to override it. @@ -195,7 +195,7 @@ args "arguments to append" } { Description { - Append all of the value arguments to the current value of variable + Append all of the value arguments to the current value of variable varName. Wrapper to the same named Tcl command (see documentation of Tcl command with the same name for details). } @@ -208,8 +208,8 @@ ?args? "args of the option" } { Description { - This method performs one of several operations on the variable - given by arrayName. It is a wrapper to the same named Tcl command + This method performs one of several operations on the variable + given by arrayName. It is a wrapper to the same named Tcl command (see documentation of Tcl command with the same name for details). } return "diverse results" @@ -218,17 +218,17 @@ @ Object instproc autoname { ?<-instance>|<-reset>? "Optional modifiers: <@br> '-instance' makes the autoname start with a small letter.<@br> - '-reset' resets the autoname index to 0." + '-reset' resets the autoname index to 0." name "base name of the autoname"} { Description { - autoname creates an automatically assigned name. It is - constructed from the base name plus an index, that is - incremented for each usage. E.g.: + autoname creates an automatically assigned name. It is + constructed from the base name plus an index, that is + incremented for each usage. E.g.: <@pre class='code'> $obj autoname a produces a0, a1, a2, ... - Autonames may have format strings - as in the Tcl 'format' command. - E.g.: + Autonames may have format strings + as in the Tcl 'format' command. + E.g.: <@pre class='code'> $obj autoname a%06d produces a000000, a000001, a000002, ... } @@ -240,13 +240,13 @@ } { Description { Turn on/off assertion checking. Options argument is the list - of assertions, that should be checked on the object automatically. - Per default assertion checking is turned + of assertions, that should be checked on the object automatically. + Per default assertion checking is turned off.
Examples:
<@pre CLASS="code"> - o check {}; <@i># turn off assertion checking on object o - o check all; <@i># turn on all assertion checks on object o + o check {}; <@i># turn off assertion checking on object o + o check all; <@i># turn on all assertion checks on object o o check {pre post}; <@i># only check pre/post assertions } @@ -258,7 +258,7 @@ } { Description { Changes the class of an object dynamically to <@tt>newClass. - The method returns the current value of class, + The method returns the current value of class, when it is called without arguments. } return "if <@tt>newClass is not specified return class, otherwise empty" @@ -278,45 +278,45 @@ ?args? "'-' method calls" } { Description { - Calls the '-' (dash) methods. I.e. evaluates arguments and calls - everything starting with '-' (and not having a digit a + Calls the '-' (dash) methods. I.e. evaluates arguments and calls + everything starting with '-' (and not having a digit a second char) as a method. Every list element until the next '-' - is interpreted as a method argument. configure is called + is interpreted as a method argument. configure is called before the constructor init during initialization and recreation. - In the following example, the variable set is called via + In the following example, the variable set is called via configure before init: <@pre class='code'> Object o -set x 4 The method configure can be called with the dash-notation at arbitrary times: <@pre class='code'> o configure -set x 4 - Note, that if '-' is followed by a numerical, the arument is + Note that if '-' is followed by a numerical, the arument is interpreted as a negative number (and not as a method). If a value of a method called this way starts with a "-", the call can be placed safely into a list (e.g. "Class c [list -strangearg -a-] - -simplearg 2"). + -simplearg 2").

See also create. - } + } return "number of the skipped first arguments" } @ Object instproc contains { "?-withnew?" "Option to overload new to create new objects within the specified object. Per default, this option is turned on." - "?-object?" "object, in which the new objects should be created. + "?-object?" "object, in which the new objects should be created. The default is the object, for which contains>/tt> was called." - "?-class?" "In combination with option -object: If the specified - object does not exist, create it from the specified class. The default - is ::xotcl::Object" + "?-class?" "In combination with option -object: If the specified + object does not exist, create it from the specified class. The default + is ::xotcl::Object" cmd "Tcl command to create multiple objects" } { Description { This method can be used to create nested object structures - with little syntactic overhead. The method changes the namespace - to the specified object and creates objects there. - Optionally, a different object scope can be specified and + with little syntactic overhead. The method changes the namespace + to the specified object and creates objects there. + Optionally, a different object scope can be specified and creating new objects in the specified scope can be turned off. - The following command creates a three rectangles, containing some + The following command creates a three rectangles, containing some points. 

   Class Point -parameter {{x 100} {y 300}}
@@ -354,7 +354,7 @@
   newName "destination of copy operation"
 } {
   Description {
-    Perform a deep copy of the object/class (with all information, like 
+    Perform a deep copy of the object/class (with all information, like
 			 class, parameter, filter, ...)
     to "newName".
   }
@@ -365,7 +365,7 @@
     ?args? "Arbitrary arguments passed to the destructor"
 } {
     Description {
-      Standard destructor.  
+      Standard destructor.
       Can be overloaded for customized destruction process. Actual destruction
       is done by instdestroy. "destroy" in principal does:
     <@pre class='code'>
@@ -381,7 +381,7 @@
 } {
     Description {
       Eval args in the scope of the object. That is local variables
-      are directly accessible as Tcl vars. 
+      are directly accessible as Tcl vars.
     }
     return "result of cmds evaled"
 }
@@ -393,8 +393,8 @@
 } {
   Description {
       Check an argument list separated with '-' args, as for instance
-      configure 
-      arguments, and extract the argument's values. Optionally, cut the 
+      configure
+      arguments, and extract the argument's values. Optionally, cut the
       whole argument.
   }
   return "value list of the argument"
@@ -413,13 +413,13 @@
   ?args? "filter specification"
 } {
     Description {
-      If <@tt>$args is one argument, it specifies a list of filters to 
+      If <@tt>$args is one argument, it specifies a list of filters to
       be set. Every filter must be an XOTcl proc/instproc within
       the object scope.
       If <@tt>$args it has more argument, the first one specifies the
-      action. Possible values are <@tt>assign, <@tt>get, 
+      action. Possible values are <@tt>assign, <@tt>get,
       <@tt>add or <@tt>delete, it modifies the current
-      settings as indicated. For more details, check the 
+      settings as indicated. For more details, check the
       tutorial.
     }
     return "if <@tt>$args return empty current filters, otherwise empty"
@@ -431,17 +431,17 @@
 } {
   description {
     Add conditions to guard a filter registration point. The filter
-    is only executed, if the guards are true. Otherwise we ignore the 
-    filter. If no guards are given, we always execute the filter.  
+    is only executed, if the guards are true. Otherwise we ignore the
+    filter. If no guards are given, we always execute the filter.
   }
   return "an empty string"
 }
 
 @ Object instproc filtersearch {
-  methodName "filter method name" 
+  methodName "filter method name"
 } {
   description {
-    Search a full qualified method name that 
+    Search a full qualified method name that
     is currently registered as a filter. Return a list of the
     proc qualifier format:
 	    'objName|className proc|instproc methodName'.
@@ -458,44 +458,44 @@
 
 } {
     Description {
-      Register an object specific method (similar to a proc) for forwarding calls to 
-      a callee (target Tcl command, other object). 
-      When the forwarder method is called, the actual arguments 
-      of the invocation are appended to the specified arguments. In callee an 
-      arguments certain substitutions can take place: 
+      Register an object specific method (similar to a proc) for forwarding calls to
+      a callee (target Tcl command, other object).
+      When the forwarder method is called, the actual arguments
+      of the invocation are appended to the specified arguments. In callee an
+      arguments certain substitutions can take place:
       
       Additionally each argument can be prefixed by the positional prefix %@POS 
-      (note the delimiting space at the end) that can be used to specify an 
-      explicit position. POS can be a positive or negative integer or the word 
-      end. The positional arguments are evaluated from left to 
+      (note the delimiting space at the end) that can be used to specify an
+      explicit position. POS can be a positive or negative integer or the word
+      end. The positional arguments are evaluated from left to
       right and should be used in ascending order. valid Options are:
-