Index: doc/langRef-xotcl.html =================================================================== diff -u -rc72f9f638677608fab1502cd696c8f2d6b2952f9 -r4dd2595d98574faaac87f5dd33b542516fdff5df --- doc/langRef-xotcl.html (.../langRef-xotcl.html) (revision c72f9f638677608fab1502cd696c8f2d6b2952f9) +++ doc/langRef-xotcl.html (.../langRef-xotcl.html) (revision 4dd2595d98574faaac87f5dd33b542516fdff5df) @@ -3,6 +3,7 @@ XOTcl - Documentation -- ./doc/langRef.xotcl + @@ -12,25 +13,37 @@

Package/File Information

- Package provided: XOTcl-langRef 1.2 + No package provided/required
- Package required: Tcl
-
Defined Objects/Classes: @@ -58,9 +71,10 @@ - XOTcl contains three predefined primitives: -

- self computes callstack related information. + XOTcl contains the following predefined primitives (Tcl commands): +

+
self
+
computes callstack related information. It can be used in the following ways: -

- my someMethod is a short form for [self] someMethod and can only be +

+
+ +
my methodName
+
is a short form for [self] methodName and can only be called in a context of an instproc or an method specific proc. It allows certain optimizations and shorter to write.

- next executes the "next" method on the precedence - order and return with the result. -

+ next
invokes the next shadowed (same-named) method on the + precedence path and returns its result. If next is + called without arguments, the arguments of the current method + are passed through the called method. If next is + invoked with the flag --noArgs, the shadowed method + is called without arguments. If other arguments are specified + for next, these will be used for the call. +
+
myvar varName
+
returns the fully qualified variable name of the specified + variable.

+

+
myproc methodName ?args?
+
calls the specified XOTcl method without the need + of using "[list [self] methodName ...]".

+

+ +
::xotcl::alias class|obj methodName ?-objscope? ?-per-object? cmdName
+
can be used to register a predefined C-implemented Tcl command as + method methodName. + The option -objscope has the same meaning as for forwarder + (instance variables of the calling object appear in the local scope of + the Tcl command), -per-object has the same meaning as for + the method 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?
+
allows 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 is needed for the serializer that is intended + to serialize the objects classes independent of filter settings.

+

+ + +
::xotcl::configure softrecreate ?on|off?
+
allows 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 + objects/classes are destroyed as well. If softrecreate is + set, the object is reseted, but not destroyed, the relations + are kept. This is important, when e.g. reloading a file + with class definitions (e.g. when used in OpenACS with file watching and + reloading). With softrecreate set, + it is not necessary to recreate dependent subclasses etc. +
+ Example: e.g. there is a class hierarchy A <- B <- C + Without softrecreate set, a reload of B means + first a destroy of B, leading to A <- C, and instances + of B are re-classed to ::xotcl::Object. When softrecreate is + set, the structure remains unchanged. +
+ +
+ @@ -121,13 +195,116 @@ Date: - $Date: 2004/07/02 11:22:31 $ + $Date: 2006/10/04 20:40:23 $

+ + + +

Class: ::xotcl::Slot

+ Class: Class +
+ Heritage: Object +
+ + + + + + + +
+ Description: + + + A slot is a meta-object that manages property-changes of + objects. A property is either an attribute or a role of an + relation (e.g. in system slots). + The predefined system slots are class, + superclass, mixin, instmixin, + filter, instfilter. These slots appear + as methods of Object or Class. + +

The slots provide a common query and setting interface. + Every multivalued slot provides e.g. a method add + to add a value to the list of values, and a method delete + which removes it. See for example the documentation of the slot + mixin.

+ + Parameters:

+ + + + + + + +
-name Name of the slot to access from an object the slot
-domain domain (object or class) of a slot on which it can be used
-multivalued boolean value for specifying single or multiple values (lists)
-defaultmethods list of two elements for specifying which methods are called + per default, when no slot method is explicitly specified
-manager the manager object of the slot (per default [self])
-per-object specify whether a slot should be used per class or per object; note that there is a restricted usage if applied per class, since defaults etc, work per initialization
+ +

For more details, consult the + tutorial.

+ +
+

+
+

+ + + +

Class: Attribute

+ Class: Class +
+ Heritage: ::xotcl::Slot +
+ + + + + + + +
+ Description: + + + Attribute slots are used to manage the setting and querying + of instance variables. + + Parameters:

+ + + + + + +
-default specify a default value
-type specify the type of a slot
-initcmd specify a Tcl command to be executed when the value of the + associated variable is read the first time; allows lazy initialization
-valuecmd specify a Tcl command to be executed whenever the variable is read
-valuechangedcmd specify a Tcl command to be executed whenever the variable is changed
+ +

Example of a class definition with three attribute slots:

+
+  Class Person -slots {
+    Attribute name
+    Attribute salary -default 0
+    Attribute projects -default {} -multivalued true
+  }
+  Person p1 -name "John Doe"
+
+ +

The slot parameters default, initcmd and + valuecmd have to be used mutually exclusively. + For more details, consult the + tutorial. +

+ +
+

+
+

@@ -137,7 +314,7 @@ Heritage: Object
Procs/Instprocs: - __unknown, alloc, create, info, instdestroy, instfilter, instfilterappend, instfilterguard, instinvar, instmixin, instmixinappend, instparametercmd, instproc, insttclcmd, new, parameter, parameterclass, recreate, superclass, unknown, volatile. + __unknown, allinstances, alloc, create, info, instdestroy, instfilter, instfilterguard, instforward, instinvar, instmixin, instparametercmd, instproc, new, parameter, parameterclass, recreate, superclass, unknown. @@ -184,13 +361,13 @@ @@ -199,12 +376,39 @@ Return:
@@ -174,7 +351,7 @@ - ?args?: arguments passed to the new class after creation + ?args?: arguments passed during creation
- Allocate memory for a new XOTcl object or class. create uses - alloc to allocate memory. But create also - calls init and evaluates '-' arguments as method calls. - In seldom cases the programmer may want to suppress the - create - mechanism and just allocate memory. Then alloc can - be used. + Allocate (create) an uninitialized object or class. Typically, alloc + is called automatically by create + to allocate an uninitialized object or class. + In contrast to alloc, create also + initializes and configures the object. + The method alloc can be used by a programmer who may want to + create uninitialized objects/classes.
- new class name + fully qualified name of created instance

  • + + + + allinstances + + + + + + + + + + +
    + Description: + + + Compute all immediate and indirect instances of a class + +
    + Return: + + fully qualified list of instances +
    +
    • +
  • @@ -237,32 +441,38 @@ Create user-defined classes or objects. If the class is a meta-class, a class is created, otherwise an object. + The object creation protocol implemened by create works as follows: + - Create firstly calls alloc in order to allocate memory for the - new object. Then default values for parameters are searched on - superclasses (an set if found). Then args is searched for args - starting with '-' followed by an alpha character. These arguments - are called as methods. '-' followed by a numerical is interpreted - as a negative number (and not as a method). If a value of a method - called this way starts with a "a", the call can be placed safely - into a list (e.g. "Class c [-strangearg -a-] -simplearg 2"). +

    In the default XOTcl definition, the create method + is called implicitly by the unknown method of the metaclass + Class, when a class (meta-class) is called with an unknown + method. E.g. the following two commands are equivalent - Finally the constructor init is called on the object - with all arguments up to the first '-' arg.

    + 

    +    Car herby -color red 
+    Car create herby -color red
    - The create method is called implicitly through the - unknown - mechanism when a class (meta-class) is called with an unknown - method. E.g. the following two commands are equivalent - - 
     Car herby -color red 
-           Car create herby -color red
    - When a users may want to call the constructor init before other '-' methods, one can specify '-init' explicitly in the left to right order of the '-' method. Init is called always only once. - e.g.: 
     Class Car -init -superclass Vehicle
    + e.g.: + + 
       Class Car -init -superclass Vehicle
    + + See also: recreate @@ -271,7 +481,7 @@ Return: - name of the created instance (result of alloc) + fully qualified name of the created instance (result of alloc) @@ -303,6 +513,7 @@ for classes. The following options can be specified: @@ -448,14 +674,14 @@ instfilter - filterList + ?args? @@ -465,13 +691,15 @@ @@ -480,34 +708,45 @@ Return:
    Arguments: - filterList: list of methods that should be registered as filters + ?args?: instfilter specification
    - Specifies the list of filters registered for the class. - instfilter overwrites all previous setting. - Filters must be available on the class or its heritage - order. Filters may also reside on the meta-class of the class. - - Filter list may contain filter guards. Then the - filter is composed of two list elements: {filtername filterguard}. + If $args is one argument, it specifies a list of + instfilters to + be set. Every filter must be an XOTcl proc/instproc within + the object scope. + If $args it has more argument, the first one specifies the + action. Possible values are assign, get, + add or delete, it modifies the current + settings as indicated. For more details, check the + tutorial.
    - empty string + if $args return empty current instfilters, otherwise empty
  • - + - instfilterappend - filterList + instfilterguard + filterName + guard + + + + @@ -522,48 +761,104 @@
    Arguments: - filterList: name of the new instfilter + filterName: filter name of a registered filter
    + + + guard: set of conditions to execute the filter +
    Description: - Convenience method that appends an instfilter to the existing filters of the class. + 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.
  • - + - instfilterguard - filtername - guard + instforward + methodName + ?options? + ?callee? + ?args? + + + + + + + +
    Arguments: - filtername: filter name of a registered filter + methodName: name of forwarder method
    - guard: set of conditions to execute the filter + ?options?: -objscope, -methodprefix string, -default names, -earlybinding, -verbose
    + + + ?callee?: named of the called command or object +
    + + + ?args?: arguments +
    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. - + Register a method for the instances of a class (similar to an instproc) + 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: +
    • %proc: substituted by name of the forwarder method
      • +
    • %self: substitute by name of the object
      • +
    • %1: substitute by first argument of the invocation
      • +
    • {%@POS value}: substitute the specified value in the argument list + on position POS, where POS can be a positive or negative integer + or end. Positive integers specify the position from the begin + of the list, while negative integer specify the position from the end. +
    • {%argclindex LIST}: take the nth argument of the specified list as + substitution value, where n is the number of arguments from the + invocation. +
    • %%: a single percent.
      • +
    • %Tcl-command: command to be executed; substituted by result.
      • +
    + 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 + right and should be used in ascending order. valid Options are: +
    • -objscope causes the target to be evaluated in the scope + of the object,
      • +
    • -methodprefix string inserts the specified prefix + in front of the second argument of the invocation,
      • +
    • -default is used for default method names (only + in connection with %1)
      • +
    • -earlybinding: look up the function + pointer of the called Tcl command at + definition time of the forwarder instead of invocation time. + This option should only be used + for calling C-implemented Tcl commands, no procs etc.);
      • +
    • -verbose
      • : print the substituted command to stderr + before executing +
    + See tutorial + for detailed examples. + +
    Return: - empty string + empty
    @@ -611,14 +906,14 @@ instmixin - instmixinList + ?args? @@ -628,10 +923,13 @@ @@ -640,48 +938,12 @@ Return:
    Arguments: - instmixinList: list of classes that should be registered as instmixins + ?args?: instmixin specification
    - Specifies the list of instmixins (per-class mixins) for the class. - Note that the registration of a per-mixin-class does not invoke - automatically the constructors of the registered class. - The method instmixin overwrites any previous settings. + If $args is one argument, it specifies a list of instmixins to + be set. Every instmixin must be a defined class. + If $args has more argument, the first one specifies the + action. Possible values are assign, get, + add or delete, it modifies the current + settings as indicated. For more details, check the + tutorial.
    - empty string + if $args empty return current instmixins, otherwise empty
  • - - - - instmixinappend - mixinList - - - - - - - - - - - - - - -
    - Arguments: - - mixinList: name of the new instmixin -
    - Description: - - - Convenience method that appends an instmixin to the existing mixins of the class. - -
    - Return: - - empty string -
    -
    • -
  • @@ -707,10 +969,11 @@ specified name. This method is used for example by the parameter method. Example:
    - Class C
    - C instparametercmd x
    - C c1 -x 100
    - puts [c1 x]
    + 
    +    Class C
+    C instparametercmd x
+    C c1 -x 100
+    puts [c1 x]
    @@ -730,6 +993,7 @@ instproc name + ?non-pos-args? args body ?preAssertion? @@ -748,6 +1012,14 @@ + ?non-pos-args?: optional non-positional arguments + + + + + + + args: instance method arguments @@ -783,11 +1055,14 @@ Specify an instance method in the same style as Tcl specifies procs. - - Optionally assertions may be given. The number of args is either 3 or 5. +
    + Optionally assertions may be given by two additional arguments. Therefore, to specify only post-assertions an empty pre-assertion list must be given. All assertions are a list of ordinary Tcl conditions. +
    + When instproc is called with an empty argument list and an empty + body, the specified instproc is deleted. @@ -802,47 +1077,6 @@
  • - - - - insttclcmd - name - - - - - - - - - - - - - - -
    - Arguments: - - name: cmd to be execute in obj scope -
    - Description: - - - Create a method 'name' that is evaluated as a tcl command in the - scope of the object. E.g. 'Object insttclcmd vwait' creates - an instproc vwait on Object that executes Tcl's vwait in the - scope of the object. That is local vars of the object are accessible - to that vwait. (Used to circumvent, for instance, the TCL_GLOBAL_ONLY - flag of vwait in Tcl.) - -
    - Return: - - empty string -
    -
    • -
  • @@ -865,7 +1099,8 @@ Convenience method to create an autonamed object. E.g.: - 
     Http new
    + 
    +    HTTP new
    creates ::xotcl::__#0, a subsequent call creates ::xotcl::__#1, ...
    If -childof obj is specified, the new object is created as a child of the specified object. @@ -877,7 +1112,7 @@ Return: - new object name + fully qualified name of the created instance @@ -918,12 +1153,11 @@ parameter. It gets and returns the parameter, if no argument is specified. With one argument, the parameter is set to the argument value. - +
    Example: - 
    +    
         Class Car -parameter {{doors 4} color}
-    Car herby -doors 2 -color green
-    
    
+    Car herby -doors 2 -color green
    @@ -962,26 +1196,20 @@ Set the parameter class. The parameter class specifies how parameters are stored and maintained internally. Per default, a method "default" is called, - to set the parameter with a default value. - - I.e., - 
    +    to set the parameter with a default value. I.e., 
+    
         Class Car -parameter {
       {doors 4}
-    }
-    
    
+    }
    is a short form for - 
    +    
         Class Car -parameter {
       {doors -default 4}
-    }
-    
    
+    }
    For specialized parameter classes other methods can be called, e.g.
    - 
     
-    {doors -default 3 -updateWidget car}
-
    + 
       {doors -default 3 -updateWidget car}
    @@ -1026,11 +1254,27 @@ - Hook called upon recreation of an object. Performs standard object - initialization, per default. May be overloaded/-written. It calls - another method cleanup which handles actual cleanup of the object - during next. That means, if you overload recreate, in the pre-part - the object still contains its old state, after next it is cleaned up. + Hook called upon recreation of an object in cases where the user wants to distinguish + between creation and recreation of objects. A recreation occurs, when an Object is created + with a name that exists already. + A typical use-case is the redefinition + of classes in and IDE, where the relations between classes/classes and object/classes + should be preserved (this is different to a destroy of the object). + +

    The method recreate does not need to call alloc + but calls instead cleanup + to reset to the object (or class) to its initial state (e.g. remove variables, child objects, + for classes remove instaces, etc.). Then it performs the standard initialization + for the object or class. + +

    If recreate is overloaded and the default recreate method is called via next, + the pre-part + (before next) contains its old state of the object, + while during the part after next the + object is cleaned up. +

    To ease recreation of classes, see ::xotcl::configure softrecreate. + + See also: create @@ -1039,7 +1283,7 @@ Return: - obj name + fully qualified name of instance @@ -1056,7 +1300,7 @@ Arguments: - classList: list of classes + classList: ?list of classes? @@ -1067,7 +1311,9 @@ Specify super-classes for a class. "superclass" changes the list - of superclasses dynamically to classList. + of superclasses dynamically to classList. + The method returns the current value of superclass, + when it is called without arguments. @@ -1076,7 +1322,7 @@ Return: - empty string + if classList is not specified return superclass(es), otherwise empty @@ -1109,9 +1355,9 @@ "unknown" (which is found on the Class Object) and executes it. The standard unknown-mechanism of XOTcl calls create with all arguments stepping one step to the right; in the general case: + 

    +    ClassName create ClassName ?args?
    - 
    ClassName create ClassName ?args?
    - Unknown can be overloaded in user-defined subclasses of class. @@ -1126,45 +1372,6 @@
    • -
  • - - - - volatile - - - - - - - - - - - - - - - -
    - Arguments: - - : -
    - Description: - - - This method is used to specify that the object - should be deleted automatically, when the current - tcl-proc/object-proc/instproc is left. Example - set x [Object new -volatile] - -
    - Return: - - empty string -
    -

    • Procs

    @@ -2206,15 +2641,15 @@ Arguments: - v1: instvar variable + v1: name of instance variable - ?v2...vn?: optional other instvar variables + ?v2...vn?: optional other names for instance variables @@ -2226,12 +2661,11 @@ Binds an variable of the object to the current method's scope. Example: - 
    -      kitchen proc enter {name} {
-        my instvar persons
-        set persons($name) [clock seconds]
-      }
-
    + 
    +    kitchen proc enter {name} {
+      my instvar persons
+      set persons($name) [clock seconds]
+    }
    Now persons can be accessed as a local variable of the method.
    A special syntax is: {varName aliasName} . @@ -2528,14 +2962,14 @@ mixin - mixinList + ?args? @@ -2545,8 +2979,13 @@ @@ -2555,48 +2994,12 @@ Return:
    Arguments: - mixinList: list of classes that should be registered as mixins + ?args?: mixin specification
    - Specifies the list of mixins registered for the object. - The method mixin overwrites all previous settings. + If $args is one argument, it specifies a list of mixins to + be set. Every mixin must be a defined class. + If $args has more argument, the first one specifies the + action. Possible values are assign, get, + add or delete, it modifies the current + settings as indicated. For more details, check the + tutorial.
    - empty string + if $args empty return current mixins, otherwise empty
  • - - - - mixinappend - mixinList - - - - - - - - - - - - - - -
    - Arguments: - - mixinList: name of the new mixin -
    - Description: - - - Convenience method that appends a mixin to the existing mixins of the object. - -
    - Return: - - empty string -
    -
    • -
  • @@ -2621,6 +3024,8 @@ Perform a deep move of the object/class (with all information, like class, parameter, filter, ...) to "newName". + Note that move is currently implemented as a copy plus + subsequent destroy operation. @@ -2658,11 +3063,12 @@ Add a getter/setter for an instance variable with the specified name as a command for the obj. - Example:
    - Object o
    - o parametercmd x
    - o x 100
    - puts [o x]
    + Example: + 
    +    Object o
+    o parametercmd x
+    o x 100
+    puts [o x]
    @@ -2691,10 +3097,11 @@ flag that constructor (method init) should not be called. - Example:
    - Class C
    - C instproc init {} {puts hu}
    - C c1 -noinit
    + Example: + 
    +    Class C
+    C instproc init {} {puts hu}
+    C c1 -noinit
    The object c1 will be created without calling the constructor. This can be used to draw a snapshot of an existing object (using the serializer) and to recreate @@ -2718,6 +3125,7 @@ proc name + ?non-pos-args? args body ?preAssertion? @@ -2736,6 +3144,14 @@ + ?non-pos-args?: optional non-positional arguments + + + + + + + args: method arguments @@ -2771,12 +3187,15 @@ Specify a method in the same style as Tcl specifies procs. - - Optionally assertions may be given. The number of args is either - 3 or 5. +
    + Optionally assertions may be specified by two additional arguments. Therefore, to specify only post-assertions an empty pre-assertion list must be given. All assertions are a list of ordinary Tcl conditions. +
    + When instproc is called with an empty argument list and an empty + body, the specified instproc is deleted. + @@ -2795,14 +3214,14 @@ procsearch - procname + procName @@ -2812,12 +3231,15 @@ @@ -2857,7 +3279,7 @@ e.g. huge numbers of objects are created. requireNamespace is often needed when e.g. using Tk widgets when variables are to be referenced via the namespace - (with ... -variable [self]::varname ...). + (with ... -variable [self]::varName ...). @@ -2876,15 +3298,15 @@ set - varname + varName?value?
    Arguments: - procname: simple proc name + procName: simple proc name
    - Search for a proc or instproc on an object and return the fully + Search which method should be invoked for an object and return the fully qualified name of the method as a list in proc qualifier format: - 'objName|classname proc|instproc methodName'. E.g., - 
     o procsearch set
    - returns 
    ::xotcl::Object instproc set
    . + 'objName|className proc|instproc|forward|instforward|parametercmd|instparametercmd|cmd|instcmd methodName'. + The proc qualifier format reports the command used to create the method. The + only exception is instcmd and cmd, which refer to commands implemented in C. + E.g., + 
        o procsearch set
    + returns 
    ::xotcl::Object instcmd set
    .
    @@ -2920,6 +3342,53 @@
    Arguments: - varname: name of the instance variable + varName: name of the instance variable
  • + + + + subst + options + string + + + + + + + + + + + + + + + + + + +
    + Arguments: + + options: ?-nobackslashes? ?-nocommands? ?-novariables? +
    + + + string: string to be substituted +
    + Description: + + + Perform backslash, command, and variable substitutions + in the scope of the given object + (see documentation of Tcl command with the same name for details). + +
    + Return: + + substituted string +
    +
    • +
  • @@ -2961,6 +3430,7 @@ unset + ?-nocomplain? v1 ?v2...vn? @@ -2969,6 +3439,14 @@ Arguments: + + + + @@ -3033,9 +3511,9 @@ @@ -3055,8 +3533,8 @@ upvar ?level? - othervar localvar - ?othervar localvar? + otherVar localVar + ?otherVar localVar?
    + ?-nocomplain?: possible error messages are suppressed +
    + + v1: Variable to unset
    When this method is used without the optional level, it is a short form - of the Tcl command
    - upevel [self callinglevel] command ?args?. - When it is called with the level, it is compatible with the original tcl command. + of the Tcl command + 
        uplevel [self callinglevel] command ?args?
    + When it is called with the level, it is compatible with the original Tcl command.
    @@ -3090,9 +3568,9 @@ @@ -3143,6 +3621,45 @@
    @@ -3071,15 +3549,15 @@ - othervar localvar: referenced variable and variale in the local scope + otherVar localVar: referenced variable and variable in the local scope
    - ?othervar localvar?: optional pairs of referenced and local variable names + ?otherVar localVar?: optional pairs of referenced and local variable names
    When this method is used without the optional level, it is a short form - of the Tcl command
    - upvar [self callinglevel] othervar localvar ?...?. - When it is called with the level, it is compatible with the original tcl command. + of the Tcl command + 
        upvar [self callinglevel] otherVar localVar ?...?
    . + When it is called with the level, it is compatible with the original Tcl command.
    • +
  • + + + + volatile + + + + + + + + + + + + + + + +
    + Arguments: + + : +
    + Description: + + + This method is used to specify that the object + should be deleted automatically, when the current + Tcl-proc/object-proc/instproc is left. Example: + 
        set x [Object new -volatile]
    + +
    + Return: + + empty string +
    +

    • Procs