Description: | XOTcl language reference. Describes predefined objects and classes. |
Predefined primitives: |
XOTcl contains two predefined primitives:
self computes callstack related information. It can be used in the following ways:
next executes the "next" method on the precendence order and return with the result. |
Date: | $Date: 2001/03/09 13:21:13 $ |
Description: | This meta-class holds the pre-defined methods available for all XOTcl classes. |
Arguments: | obj: new obj/class name |
?args?: arguments passed to the new class after creation | |
Description: | 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. |
Return: | new class name |
Arguments: | obj: obj/class name |
?args?: arguments passed to the destructor | |
Description: |
Standard destructor. Destroys XOTcl object physically from the memory.
Can be overloaded for customized destruction process.
In XOTcl objects are not directly destroyed, when a destroy is encountered in a method. Beforehand, the interpreter looks up whether the object is still referenced on the method callstack or not. If not, the object is directly destroyed. Otherwise every occurrence of the object on the callstack is marked as destroyed. During popping of the callstack, for each object marked as destroyed, the reference count is decremented by one. When no more references to the object are on the callstack the object is physically destroyed. This way we can assure that objects are not accessed with [self] in running methods after they are physically destroyed. |
Return: | empty string |
Arguments: | args: info options |
Description: |
Introspection of classes. All options available for objects
(see info object) is also available
for classes.
The following options can be specified:
|
Return: | Value of introspected option as a string. |
Arguments: | instmixinList: list of classes that should be registered as instmixins |
Description: | 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. |
Return: | empty string |
Arguments: | classList: list of classes |
Description: | Specify super-classes for a class. "superclass" changes the list of superclasses dynamically to classList. |
Return: | empty string |
Arguments: | parameterList: list of parameter definitions |
Description: | Specify parameters automatically created for each instance. Parameters are variables which are available on each class instance and that have a getter/setter method with their own name. Parameters are specified in a parameter list of the form {p1 p2 ... pn}. p1 ... pn may either be parameter names or definitions of the form {parameterName defaultValue}. If a default value is given, that parameter is created during creation process of the instance object, otherwise only the getter/setter method is created (and the parameter does not exist). The getter/setter method has the same name as the parameter. It gets and returns the parameter, if no argument is specified. With one argument, the parameter is set to the argument value. |
Return: | empty string |
Arguments: | class: parameter class name |
Description: |
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.,
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} |
Return: | empty string |
Arguments: | objName: name of a new class or object |
?args?: arguments passed to the constructor | |
Description: |
Create user-defined classes or objects. If the class is a meta-class,
a class is created, otherwise an object.
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). Finally the
constructor "init" is called on the object with all arguments up
to the first '-' arg. 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 redWhen 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 |
Return: | name of the created instance (result of alloc) |
Arguments: | invariantList: Body of invariants for the class |
Description: | Specify invariants for the class. These are inherited by sub-classes. The invariants must hold for all instances. All assertions are a list of ordinary Tcl conditions. |
Return: | empty string |
Arguments: | filterList: list of methods that should be registered as filters |
Description: | Specifies the list of filters registered for the class. filter 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. |
Return: | empty string |
Arguments: | methodName: filter method name |
Description: | Search a full qualified method name that is currently registered as a filter. |
Return: | full qualified name, if filter is found, otherwise an empty string |
Arguments: | ?args?: arbitrary arguments |
Description: |
Standard unknown mechanism. This mechnism is always triggered when
XOTcl does not know a method called on an object. Supposed that
there is no method with the called name, XOTcl looks up the method
"unknown" (which is found on the Class Object) and executes it.
The standard unknown-mechnism of XOTcl calls create with all
arguments stepping one step to the right; in the general case:
ClassName create ClassName ?args?Unknown can be overloaded in user-defined subclasses of class. |
Return: | Standard unknown mechanism returns result of create |
Arguments: | ?args?: args passed to create |
Description: |
Convenience method to create a child of the calling object. The
child name is an instance autoname of the Class name.
E.g.:
Http newChildcalled from methods of Object o creates new instances of the HTTP class as childobjects of o (such as o::http1 or o::http2, ...). |
Return: | new object name |
Arguments: | ?args?: args passed to create |
Description: |
Convenience method to create a global autonamed object. E.g.:
Http newcreates ::http1, ::http2, ... |
Return: | new object name |
Arguments: | filterList: name of the new filter |
Description: | Convenience method that appends a filter to the existing filters of the class. |
Return: | empty string |
Description: | This class holds the pre-defined methods available for all XOTcl objects. All these methods are also available on classes. |
Arguments: |
?<-instance>|<-reset>?: Optional modifiers: '-instance' makes the autoname start with a small letter. '-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.:
$obj autoname aproduces a0, a1, a2, ... Autonames may have format strings as in the Tcl 'format' command. E.g.: $obj autoname a%06dproduces a000000, a000001, a000002, ... |
Return: | newly constructed autoname value |
Arguments: | options: none, one or more of: (?all? ?pre? ?post? ?invar? ?instinvar?) |
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
off. Examples:
o check {}; # turn off assertion checking on object o o check all; # turn on all assertion checks on object o o check {pre post}; # only check pre/post assertionsinfo check introspects check options. |
Return: | empty string |
Arguments: | newClass: new class name |
Description: | Changes the class of an object dynamically to newClass. |
Return: | empty string |
Arguments: | ?args?: Arbitrary arguments passed to the destructor |
Description: |
Standard destructor.
Can be overloaded for customized destruction process. Actual destruction
is done by instdestroy. "destroy" in principal does:
Object instproc destroy args { [[self] info class] instdestroy [self] } |
Return: | empty string |
Arguments: | ?args?: Arbitrary arguments passed to cleanup |
Description: | Resets an object or class into an initial state, as after construction. Called during recreation process. |
Return: | empty string |
Arguments: | ?args?: '-' method calls |
Description: | Calls the '-' 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 intepreted as a method argument. applymethods is called before the constructor during initialization and recreation. |
Return: | value of last '-' method |
Arguments: | var: variable name of the instance variable that should be tested for existence |
?varNameOut?: local variable - is set to the value of var, if it exists | |
Description: | Check for existance of instance variable "var" on the object. |
Return: | 1 for existance, 0 for not |
Arguments: | args: info options |
Description: |
Introspection of objects. The following options can be specified:
|
Return: | Value of introspected option as a string. |
Arguments: | v1: instvar variable |
??v2?:optional other instvar variables Default: "...". | |
Description: |
Binds an variable of the object to the current method's scope.
Example:
kitchen proc enter {name} { [self] 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} . This gives the variable with the name varName the alias aliasName. This way the variables can be linked to the methods scope, even if a variable with that name already exists in the scope. |
Return: | empty string |
Arguments: | invariantList: Body of invariants for the object |
Description: | Specify invariants for the objects. All assertions are a list of ordinary Tcl conditions. |
Return: | empty string |
Arguments: | ?className?: name of a class to be tested |
Description: | Test whether the argument (or the Object, if no argument is specified) is an existing class or not. |
Return: | 1 or 0 |
Arguments: | ?metaClassName?: name of a metaclass to be tested |
Description: | Test whether the argument (or the Object, if no argument is specified) is an existing metaclass or not. |
Return: | 1 or 0 |
Arguments: | objName: string that should be tested, whether it is a name of an object or not |
Description: | Test whether the argument is an existing object or not. Every XOTcl object has the capability to check the object system. |
Return: | 1 or 0 |
Arguments: | className: type name |
Description: | Test whether the argument is a type of the object. I.e., 1 is returned if className is either the class of the object or one of its superclasses. |
Return: | 1 or 0 |
Arguments: | name: method name |
args: method arguments | |
body: method body | |
?preAssertion?: optional assertions that must hold before the proc executes | |
?postAssertion?: optional assertions that must hold after the proc executes | |
Description: | 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. Therefore, to specify only post-assertions an empty pre-assertion list must be given. All assertions are a list of ordinary Tcl conditions. |
Return: | empty string |
Arguments: | varname: name of the instance variable |
?value?: optional new value | |
Description: | Set an instance variable in the same style as Tcl sets a variable. With one argument, we retrieve the current value, with two arguments, we set the instance variable to the new value. |
Return: | Value of the instance variable |
Arguments: | v1: Variable to unset |
??v2?:Optional more vars to unset Default: "...". | |
Description: | The unset operation deletes one or optionally a set of variables from an object. |
Return: | empty string |
Arguments: | ?(add|remove)?: add adds a new metadata option, remove removes it |
metaDataList: metadata definition list | |
Description: |
Note, that metadata is deprecated. Use the @ object for
integrated metadata and documentation instead.
Simple metadata facility. Metadata can be provided as atomic
or structured values. First metadata options have to be specified with
add/remove e.g.:
obj metadata add authorNow metadata can be set, like: obj metadata author "Uwe"It can be retrieved by leaving the a value away: obj metadata author ;# returns "Uwe"Metadata on classes is inherited and can be used on the instance. |
Return: | metadata value |
Arguments: | mixinList: list of classes that should be registered as mixins |
Description: | Specifies the list of mixins registered for the object. The method mixin overwrites all previous settings. |
Return: | empty string |
Arguments: | procname: simple proc name |
Description: |
Search for a proc or instproc on an object and return the fully
qualified name of the method. E.g.,
o procsearch setreturns ::XOTclClasses::Object::set. |
Return: | fully qualified name of the searched method or empty string if not found |
Arguments: | varName: variable name |
?increment?: value to increment | |
Description: | Increments the value stored in the variable whose name is varName. The new value is stored as a decimal string in variable varName and also returned as result. Wrapper to the same named Tcl command (see documentation of Tcl command with the same name for details). |
Return: | new value of varName |
Arguments: | opt: array option |
array: array name | |
?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 (see documentation of Tcl command with the same name for details). |
Return: | diverse results |
Arguments: | varName: name of variable |
args: arguments to append | |
Description: | 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). |
Return: | empty string |
Arguments: | varName: name of variable |
args: elements to append | |
Description: | Append all the specified arguments to the list specified by varName as separated elements (typically separated by blanks). If varName doesn't exist, it creates a list with the specified values (see documentation of Tcl command with the same name for details). |
Return: | empty string |
Arguments: | varName: name of variable |
Description: | Enter event loop until the specified variable is set (see documentation of Tcl command with the same name for details). |
Return: | empty string |
Arguments: | varName: name of variable |
value: new value | |
Description: | Conditional set. Same as "set", but instance variable is only set, if it does not exists before. |
Return: | empty string |
Arguments: | methtype: instproc or proc |
methname: name of abstract method | |
arglist: arguments | |
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. |
Return: | error |
Arguments: | newName: destination of copy operation |
Description: | Perform a deep copy of the object/class (with all information, like class, parameter, filter,...) to "newName". |
Return: | empty string |
Arguments: | newName: destination of move operation |
Description: | Perform a deep move of the object/class (with all information, like class, parameter, filter,...) to "newName". |
Return: | empty string |
Arguments: | name: instance method name |
args: instance method arguments | |
body: instance method body | |
?preAssertion?: optional assertions that must hold before the proc executes | |
?postAssertion?: optional assertions that must hold after the proc executes | |
Description: | 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. Therefore, to specify only post-assertions an empty pre-assertion list must be given. All assertions are a list of ordinary Tcl conditions. |
Return: | empty string |
Arguments: | mixin: name of a class that should be registered as mixin |
Description: | Convenience method that appends a mixin to the existing mixins of the object. |
Return: | empty string |
Description: | Retrieve the current exit handler procedure body as a string. |
Return: | exit handler proc body |
Arguments: | body: procedure body |
Description: | Set body for the exit handler procedure. The exit handler is executed when XOTcl is existed or aborted. Can be used to call cleanups that are not associated with objects (otherwise use destructor). On exit the object destructors are called after the user-defined exit-handler. |
Return: | exit handler proc body |
Back to index page.