./doc/langRef.xotcl
./doc/langRef.xotcl
| Description: | XOTcl language reference. Describes predefined objects and classes. |
| Predefined primitives: |
XOTcl contains the following predefined primitives (Tcl commands):
|
| 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:
For more details, consult the tutorial. |
| Description: |
Attribute slots are used to manage the setting and querying
of instance variables.
Parameters:
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. |
| 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 an uninitialized XOTcl object or class. Alloc is used by the method create to allocate the object. Note that create also calls as well configure and init to initialized the object. Only in seldom cases the programmer may want to suppress the create mechanism and just allocate uninitiaized objects via alloc. |
| Return: | new class name |
| Description: | Compute all immediate and indirect instances of a class |
| Return: | fully qualified list of instances |
| 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.
The method create is responsible for allocating and
initializing objects. The method can be overloaded e.g. in a
metaclass if other initialization behavior is wanted.
The standard behavior of create is 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). Finally the constructor init is called on the object with all arguments up to the first '-' arg. The create method is often 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 |
| Return: | name of the created instance (result of alloc) |
| 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: | 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?: instfilter specification |
| Description: | 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. |
| Return: | if $args return empty current instfilters, otherwise empty |
| Arguments: | filterName: filter name of a registered filter |
| guard: set of conditions to execute the filter | |
| 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. |
| Return: | empty string |
| Arguments: | methodName: name of forwarder method |
| ?options?: -objscope, -methodprefix string, -default names, -earlybinding, -verbose | |
| ?callee?: named of the called command or object | |
| ?args?: arguments | |
| Description: |
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:
|
| Return: | empty |
| 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: | ?args?: instmixin specification |
| Description: | 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. |
| Return: | if $args empty return current instmixins, otherwise empty |
| Arguments: | name: variable to be provided with getter/setter method |
| Description: |
Add a getter/setter command for an instance variable with the
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]
|
| Return: | empty string |
| Arguments: | name: instance method name |
| ?non-pos-args?": optional non-positional arguments | |
| 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 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. |
| Return: | empty string |
| Arguments: | ?-childof obj? ?args?: args passed to create |
| Description: |
Convenience method to create an autonamed object. E.g.:
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. |
| Return: | new object name |
| Arguments: | parameterList: list of parameter definitions |
| Description: |
Specify parameters automatically created for each instance.
Parameters denote instance 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.
Example:
Class Car -parameter {{doors 4} color}
Car herby -doors 2 -color green
|
| 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: | obj: obj to be recreated |
| ?args?: arbitrary arguments | |
| Description: | Methods called upon recreation of an object. Recreate is called, when an object/class is created, but a same-named object/class exists already. "recreate" is not called, when an object is trying to be recreated as a class or vice versa. In these cases, recreating is realized via destroy+create. The Methods "recreate" 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. |
| Return: | obj name |
| Arguments: | classList: ?list of classes? |
| Description: | Specify super-classes for a class. "superclass" changes the list of superclasses dynamically to classList. The method returns the current value of superclass, when it is called without arguments. |
| Return: | if classList is not specified return superclass(es), otherwise empty |
| Arguments: | ?args?: arbitrary arguments |
| Description: |
Standard unknown mechanism. This mechanism 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-mechanism 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: | name: name of class to be created |
| Description: |
This method is called, whenever XOTcl references a class,
which is not defined yet. In the following example:
Class C -superclass D
D is not defined. Therefore, Class __unknown D
is called. This callback can be used to perform auto-loading
of classes. After this call, XOTcl tries again to
resolve D. If it succeeds, XOTcl will continue; otherwise,
an error is generated.
This method is called on mixin/instmixin definition calls, istype, ismixin, class, superclass and parameterclass |
| 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: | methtype: instproc or proc |
| methodName: 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: | 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: | 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: |
?<-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 assertions
|
| Return: | empty string |
| Arguments: | newClass: ?new class? |
| Description: | Changes the class of an object dynamically to newClass. The method returns the current value of class, when it is called without arguments. |
| Return: | if newClass is not specified return class, otherwise empty |
| Arguments: | ?args?: Arbitrary arguments passed to cleanup |
| Description: | Resets an object or class into an initial state, as after construction. Called during recreation process by the method 'recreate' |
| Return: | empty string |
| Arguments: | ?args?: '-' method calls |
| Description: |
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
before the constructor init during initialization and recreation.
In the following example, the variable set is called via
configure before init:
Object o -set x 4The method configure can be called with the dash-notation at arbitrary times: o configure -set x 4Note 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"). See also create. |
| Return: | number of the skipped first arguments |
| Arguments: | ?-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. 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 | |
| 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
creating new objects in the specified scope can be turned off.
The following command creates a three rectangles, containing some
points.
Class Point -parameter {{x 100} {y 300}}
Class Rectangle -parameter {color}
Rectangle r0 -color pink -contains {
Rectangle r1 -color red -contains {
Point x1 -x 1 -y 2
Point x2 -x 1 -y 2
}
Rectangle r2 -color green -contains {
Point x1
Point x2
}
}
The resulting object structure looks like in the following
example (simplified).
::r0 ::r0::r1 ::r0::r1::x1 ::r0::r1::x2 ::r0::r2 ::r0::r2::x1 ::r0::r2::x2 |
| Return: | number of the skipped first arguments |
| 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: | ?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 {
[my info class] instdestroy [self]
}
|
| Return: | empty string |
| Arguments: | args: cmds to eval |
| Description: | Eval args in the scope of the object. That is local variables are directly accessible as Tcl vars. |
| Return: | result of cmds evaled |
| Arguments: | al: Argument List Name |
| name: Name of the configure argument to be extracted (should start with '-') | |
| ?cutTheArg?: if cutTheArg not 0, it cut from upvar argsList, default is 0 | |
| Description: | Check an argument list separated with '-' args, as for instance configure arguments, and extract the argument's values. Optionally, cut the whole argument. |
| Return: | value list of the argument |
| Arguments: | var: variable name |
| Description: | Check for existence of the named instance variable on the object. |
| Return: | 1 if variable exists, 0 if not |
| Arguments: | ?args?: filter specification |
| Description: | If $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 $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. |
| Return: | if $args return empty current filters, otherwise empty |
| Arguments: | filterName: filter name of a registered filter |
| guard: set of conditions to execute the filter | |
| 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. |
| Return: | an empty string |
| Arguments: | methodName: filter method name |
| Description: | 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'. |
| Return: | full qualified name, if filter is found, otherwise an empty string |
| Arguments: | methodName: name of forwarder method |
| ?options?: -objscope, -methodprefix string, -default names, -earlybinding, -verbose | |
| ?callee?: named of the called command or object | |
| ?args?: arguments | |
| 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:
|
| Return: | empty |
| Arguments: | ?className?: name of a class to be tested |
| Description: | Test whether the argument is either a mixin or instmixin of the object or if it is on the class hierarchy of the object. This method combines the functionalities of istype and ismixin. |
| Return: | 1 or 0 |
| 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: | args: info options |
| Description: |
Introspection of objects. The following options can be specified:
|
| Return: | Value of introspected option as a string. |
| Arguments: | v1: name of instance variable |
| ?v2...vn?: optional other names for instance variables | |
| Description: |
Binds a variable of the object to the current method's scope.
Example:
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} . 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: | ?className?: name of a class to be tested |
| Description: | Test whether the argument is a mixin or instmixin of the object. |
| 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: | 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: | ?args?: mixin specification |
| Description: | 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. |
| Return: | if $args empty return current mixins, otherwise empty |
| Arguments: | newName: destination of move operation |
| Description: | 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. |
| Return: | empty string |
| Arguments: | name: variable to be provided with getter/setter method |
| Description: |
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]
|
| Return: | empty string |
| Description: |
flag that constructor (method init) should
not be called.
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
it in some other context in its last state.
|
| Return: | empty string |
| Arguments: | name: method name |
| ?non-pos-args?: optional non-positional arguments | |
| 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 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. |
| Return: | empty string |
| Arguments: | procName: simple proc name |
| Description: |
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|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 setreturns ::xotcl::Object instcmd set. |
| Return: | fully qualified name of the searched method or empty string if not found |
| Description: | The method requireNamespace can be used to ensure that the object has a namespace. Namespaces are created automatically by XOTcl, when e.g. an object has child objects (aggregated objects) or procs. The namespace will be used to keep instance variables, procs and child objects. To check, whether an object currently has a namespace, info hasNamespace can be used. Hint: In versions prior to XOTcl 0.9 all XOTcl objects had their own namespaces; it was made on demand to save memory when 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 ...). |
| 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: | 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 |
| Arguments: | varName: name of variable |
| Description: | Trace an object variable (see documentation of Tcl command with the same name for details). |
| Return: | empty string |
| Arguments: | ?-nocomplain?: possible error messages are suppressed |
| v1: Variable to unset | |
| ?v2...vn?: Optional more vars to unset | |
| Description: | The unset operation deletes one or optionally a set of variables from an object. |
| Return: | empty string |
| Arguments: | ?level?: Level |
| command ?args?: command and arguments to be called | |
| Description: |
When this method is used without the optional level, it is a short form
of the Tcl command
uplevel [self callinglevel] command ?args?When it is called with the level, it is compatible with the original Tcl command. |
| Return: | result of the command |
| Arguments: | ?level?: Level |
| otherVar localVar: referenced variable and variable in the local scope | |
| ?otherVar localVar?: optional pairs of referenced and local variable names | |
| Description: |
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. |
| Return: | result of the command |
| 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: | : |
| 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 |
| 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.