./doc/langRef.xotcl ./doc/langRef.xotcl

Package/File Information

No package provided/required

Defined Objects/Classes:
Filename: ./doc/langRef.xotcl

Description: XOTcl language reference. Describes predefined objects and classes.
Predefined primitives: XOTcl contains the following predefined primitives (Tcl commands):
computes callstack related information. It can be used in the following ways:
  • 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 ``Can't find self''.
  • self class - the self command with a given argument class returns the name of the 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.
  • self proc - the self command with a given argument proc returns the name of the currently executing proc or instproc.
  • self callingclass: Returns class name of the class that has called the executing method.
  • self callingobject: Returns object name of the object that has called the executing method.
  • self callingproc: Returns proc name of the method that has called the executing method.
  • self calledclass: Returns class name of the class that holds the target proc (in mixins and filters).
  • self calledproc: Returns method name of the target proc (only applicable in a filter).
  • self isnextcall: Return 1 if this method was invoked via next, otherwise 0
  • self next: Return the "next" method on the precedence path as a string.
  • 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'.
  • 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 uplevel or upvar.
  • 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 uplevel or upvar.

my methodName
is a short form for [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.

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 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 is needed for the serializer that is intended to serialize the objects classes independent of filter settings.

::xotcl::configure softrecreate ?on|off?
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 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.

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.

Background: when XOTcl is used in a threaded environment such as for example in AOLserver, one has to take care that the deletion of objects and classes happens in a safe environment, where the XOTcl destructors (destroy methods) are still able to run. Without ::xotcl::finalize the deletion happens in Tcl_FinalizeThread(), after thread cleanup (where e.g. the thread local storage is freed). This can lead to memory leaks in AOLserver, which allocates e.g. some structures on demand, but since this happens after cleanup, it will leak. A simple ns_log in a destructor might lead to this problem. The solution is to call ::xotcl::finalize in the "delete trace" in AOLserver (as it happens in OpenACS).

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

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.


-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.

Class: Class

Class: Class
Heritage: Object
Procs/Instprocs: __unknown, allinstances, alloc, create, info, instdestroy, instfilter, instfilterguard, instforward, instinvar, instmixin, instparametercmd, instproc, new, parameter, parameterclass, recreate, superclass, unknown.
Description: This meta-class holds the pre-defined methods available for all XOTcl classes.



Class: Object

Class: Class
Procs/Instprocs: abstract, append, array, autoname, check, class, cleanup, configure, contains, copy, destroy, eval, exists, extractConfigureArg, filter, filterguard, filtersearch, forward, getExitHandler, hasclass, incr, info, instvar, invar, isclass, ismetaclass, ismixin, isobject, istype, lappend, mixin, move, noinit, parametercmd, proc, procsearch, requireNamespace, set, setExitHandler, subst, trace, unset, uplevel, upvar, volatile, vwait.
Description: This class holds the pre-defined methods available for all XOTcl objects. All these methods are also available on classes.



Back to index page.