Index: xotcl/doc/langRef.xotcl
===================================================================
diff -u -rbb3c756fb47517596b9dbcb4e580aa1212827b41 -r2846921e448d4d4aeb3245ebbfe4381182f0e286
--- xotcl/doc/langRef.xotcl (.../langRef.xotcl) (revision bb3c756fb47517596b9dbcb4e580aa1212827b41)
+++ xotcl/doc/langRef.xotcl (.../langRef.xotcl) (revision 2846921e448d4d4aeb3245ebbfe4381182f0e286)
@@ -1,16 +1,15 @@
-# $Id: langRef.xotcl,v 1.11 2006/09/14 06:36:02 neumann Exp $
-package provide XOTcl-langRef 1.5.0
+# $Id: langRef.xotcl,v 1.12 2006/09/25 08:29:04 neumann Exp $
+package provide XOTcl-langRef 1.4.0
package require XOTcl
@ @File {
description {
XOTcl language reference. Describes predefined objects and classes.
}
"predefined primitives" {
- XOTcl contains the following predefined primitives (Tcl commands):
-
- - <@tt>self<@/tt>
- - computes callstack related information.
+ XOTcl contains three predefined primitives:
+ <@p>
+ <@tt>self<@/tt> computes callstack related information.
It can be used in the following ways:
<@UL>
<@LI><@TT>self - returns the name
@@ -51,63 +50,38 @@
<@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
+ call, whatsever 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
+ <@/p><@p>
+ <@tt>my someMethod<@/tt> is a short form for <@tt>[self] someMethod and can only be
called in a context of an instproc or an 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
+ <@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
invoked with the flag <@tt>--noArgs, the shadowed method
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.
-
-
- - <@tt>myproc methodName ?args?
- - calls the specified XOTcl method without the need
- of using "<@tt>[list [self] methodName ...]".
-
-
- - <@tt>::xotcl::alias class|obj ?-objscope? ?-per-object? cmdName
- - can be used to register predefined C-implemented Tcl commands as
- methods. 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>
-
-
- allows to
+ <@/p>
+ <@/p><@p>
+ <@tt>::xotcl::configure filter ?on|off?<@/tt> 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.
-
-
-
- - <@tt>::xotcl::configure softrecreate ?on|off?<@/tt>
- - allows to control
+ to serialize the objects classes independent of filter settings.
+ <@/p>
+ <@p>
+ <@tt>::xotcl::configure softrecreate ?on|off?<@/tt> 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 <@tt>softrecreate is
- set, the object is reseted, but not destroyed, the relations
+ set, the object is resetted, 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 <@tt>softrecreate set,
@@ -116,14 +90,12 @@
Example: e.g. there is a class hierarchy A <- B <- C
Without <@tt>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 <@tt>softrecreate is
- set, the structure remains unchanged.
-
-
+ of B are reclassed to ::xotcl::Object. When <@tt>softrecreate is
+ set, the structure remeans unchanged.
+ <@/p>
-
-
}
- date { $Date: 2006/09/14 06:36:02 $ }
+ date { $Date: 2006/09/25 08:29:04 $ }
}
##
@@ -138,7 +110,7 @@
@ Object instproc abstract {
methtype "instproc or proc"
- methodName "name of abstract method"
+ methname "name of abstract method"
arglist "arguments"
} {
Description {
@@ -214,14 +186,12 @@
}
@ Object instproc class {
- newClass "?new class?"
+ newClass "new class name"
} {
- Description {
- Changes the class of an object dynamically to <@tt>newClass.
- 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"
+ Description {
+ Changes the class of an object dynamically to <@tt>newClass.
+ }
+ return "empty string"
}
@ Object instproc cleanup {
@@ -238,71 +208,21 @@
?args? "'-' method calls"
} {
Description {
- Calls the '-' (dash) methods. I.e. evaluates arguments and calls
+ 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 interpreted as a method argument. configure/tt> is called
+ is interpreted as a method argument. configure is called
before the constructor during initialization and recreation.
- In the following example, the variable set is called via
- configure before init:
+ E.g.
<@pre class='code'> Object o -set x 4
- The method configure can be called with the
- dash-notation at arbitrary times:
+ here:
<@pre class='code'> o configure -set x 4
- }
- return "number of the skipped first arguments"
-}
+ is executed.
-@ 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.
- 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 folloing
- 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"
}
-
-
@ Object instproc copy {
newName "destination of copy operation"
} {
@@ -341,7 +261,7 @@
@ Object instproc extractConfigureArg {
al "Argument List Name"
- name "Name of the configure argument to be extracted (should start with '-')"
+ 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 {
@@ -363,23 +283,22 @@
}
@ Object instproc filter {
- ?args? "filter specification"
+ args "filter specification"
} {
Description {
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>set, <@tt>get,
<@tt>add or <@tt>delete, it modifies the current
- settings as indicated. For more details, check the
- tutorial.
+ settings as indicated. For more details, check the tutorial.
}
return "if <@tt>$args return empty current filters, otherwise empty"
}
@ Object instproc filterguard {
- filterName "filter name of a registered filter"
+ filtername "filter name of a registered filter"
guard "set of conditions to execute the filter"
} {
description {
@@ -397,37 +316,30 @@
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'.
+ 'objName|classname proc|instproc methodName'.
}
return "full qualified name, if filter is found, otherwise an empty string"
}
@ Object instproc forward {
- methodName "name of forwarder method"
- ?options? "-objscope, -methodprefix string, -default names, -earlybinding, -verbose"
+ name "name of forwarder method"
+ ?options? "-objscope, -methodprefix string, -default names"
?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
+ Register a method (similar to a proc) for forwarding calls to
+ a callee (target tcl command,
+ other object). If 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.
+ arguments certain substituions can take place:
+
- %proc: subsituted by name of the forwarder method
+ - %self: subsituted by name of the object
+ - %1: subsituted by first argument of the invocation
- %%: a single percent.
- - %Tcl-command: command to be executed; substituted by result.
+ - %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
@@ -440,17 +352,8 @@
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.
+ See tutorial for detailed examples.
}
return "empty"
}
@@ -496,8 +399,8 @@
Returns the body of the specified proc (object specific method).
<@li><@TT>objName info class ?classname?:
- Returns the name of the class of the current object, if className was
- not specified, otherwise it returns 1 if className matches the
+ Returns the name of the class of the current object, if classname was
+ not specified, otherwise it returns 1 if classname matches the
object's class and 0 if not.
<@li><@TT>objName info children ?pattern?: Returns the
@@ -535,6 +438,9 @@
<@li><@TT>objName info invar: Returns object invariants.
+ <@li><@TT>objName info metadata ?pattern?:
+ Returns available metadata options.
+
<@li><@TT>objName info methods: Returns the list of all methods
currently reachable for objName. Includes procs, instprocs, cmds,
instcommands on object, class hierarchy and mixins.
@@ -580,8 +486,8 @@
}
@ Object instproc instvar {
- v1 "name of instance variable"
- "?v2...vn?" "optional other names for instance variables"
+ v1 "instvar variable"
+ "?v2...vn?" "optional other instvar variables"
} {
Description {
Binds an variable of the object to the current method's scope.
@@ -676,19 +582,16 @@
return "empty string"
}
-
-
@ Object instproc mixin {
- ?args? "mixin specification"
+ args "mixin specification"
} {
Description {
If <@tt>$args is one argument, it specifies a list of mixins to
be set. Every mixin must be a defined class.
If <@tt>$args has more argument, the first one specifies the
- action. Possible values are <@tt>assign, <@tt>get,
+ action. Possible values are <@tt>set, <@tt>get,
<@tt>add or <@tt>delete, it modifies the current
- settings as indicated. For more details, check the
- tutorial.
+ settings as indicated. For more details, check the tutorial.
}
return "if <@tt>$args empty return current mixins, otherwise empty"
}
@@ -700,8 +603,6 @@
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"
}
@@ -743,7 +644,7 @@
@ Object instproc proc {
name "method name"
- ?non-pos-args? "optional non-positional arguments"
+ ?non-pos-args? "optinal non-positional arguments"
args "method arguments"
body "method body"
"?preAssertion?" "optional assertions that must hold before the proc executes"
@@ -765,18 +666,15 @@
}
@ Object instproc procsearch {
- procName "simple proc name"
+ procname "simple proc name"
} {
Description {
- Search which method should be invoked for an object and return the fully
+ Search for a proc or instproc on 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.,
+ 'objName|classname proc|instproc methodName'. E.g.,
<@pre class='code'> o procsearch set
- returns <@pre>::xotcl::Object instcmd set.
+ returns <@pre>::xotcl::Object instproc set.
}
return "fully qualified name of the searched method or empty string if not found"
}
@@ -797,13 +695,13 @@
e.g. huge numbers of objects are created.
<@TT>requireNamespace is often needed when e.g. using Tk widgets
when variables are to be referenced via the namespace
- (with <@TT>... -variable [self]::varName ...).
+ (with <@TT>... -variable [self]::varname ...).
}
return "empty string"
}
@ Object instproc set {
- varName "name of the instance variable"
+ varname "name of the instance variable"
?value? "optional new value"
} {
Description {
@@ -815,18 +713,6 @@
return "Value of the instance variable"
}
-@ Object instproc subst {
- 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"
-}
-
@ Object instproc trace {
varName "name of variable"
} {
@@ -838,7 +724,6 @@
}
@ Object instproc unset {
- "?-nocomplain?" "possible error messages are suppressed"
v1 "Variable to unset"
"?v2...vn?" "Optional more vars to unset"
} {
@@ -855,21 +740,21 @@
Description {
When this method is used without the optional level, it is a short form
of the Tcl command
- <@pre class='code'> uplevel [self callinglevel] command ?args?<@/pre>
- When it is called with the level, it is compatible with the original Tcl command.
+ <@pre class='code'> upevel [self callinglevel] command ?args?<@/pre>
+ When it is called with the level, it is compatible with the original tcl command.
}
return "result of the command"
}
@ Object instproc upvar {
?level? "Level"
- otherVar localVar "referenced variable and variable in the local scope"
- ?otherVar localVar? "optional pairs of referenced and local variable names"
+ othervar localvar "referenced variable and variale 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
- <@pre class='code'> upvar [self callinglevel] otherVar localVar ?...?<@/pre>.
- When it is called with the level, it is compatible with the original Tcl command.
+ <@pre class='code'> upvar [self callinglevel] othervar localvar ?...?<@/pre>.
+ When it is called with the level, it is compatible with the original tcl command.
}
return "result of the command"
}
@@ -1084,26 +969,25 @@
}
@ Class instproc instfilter {
- ?args? "instfilter specification"
+ args "instfilter specification"
} {
Description {
If <@tt>$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 <@tt>$args it has more argument, the first one specifies the
- action. Possible values are <@tt>assign, <@tt>get,
+ action. Possible values are <@tt>set, <@tt>get,
<@tt>add or <@tt>delete, it modifies the current
- settings as indicated. For more details, check the
- tutorial.
+ settings as indicated. For more details, check the tutorial.
}
return "if <@tt>$args return empty current instfilters, otherwise empty"
}
@ Class instproc instfilterguard {
- filterName "filter name of a registered filter"
+ filtername "filter name of a registered filter"
guard "set of conditions to execute the filter"
} {
description {
@@ -1116,31 +1000,23 @@
@ Class instproc instforward {
- methodName "name of forwarder method"
- ?options? "-objscope, -methodprefix string, -default names, -earlybinding, -verbose"
+ name "name of forwarder method"
+ ?options? "-objscope, -methodprefix string, -default names"
?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
+ Register a method (similar to an instproc) for forwarding calls to
+ a callee (target tcl command,
+ other object). If 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.
+ arguments certain substituions can take place:
+
- %proc: subsituted by name of the forwarder method
+ - %self: subsituted by name of the object
+ - %1: subsituted by first argument of the invocation
- %%: a single percent.
- - %Tcl-command: command to be executed; substituted by result.
+ - %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
@@ -1150,20 +1026,11 @@
- -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
+ in front of the second argument of the invocation,-
+
- -default is used for default method names (only in
+ connection with %1).
- See tutorial
- for detailed examples.
-
+ See tutorial for detailed examples.
}
return "empty"
}
@@ -1181,16 +1048,15 @@
}
@ Class instproc instmixin {
- ?args? "instmixin specification"
+ args "instmixin specification"
} {
Description {
If <@tt>$args is one argument, it specifies a list of instmixins to
be set. Every instmixin must be a defined class.
If <@tt>$args has more argument, the first one specifies the
- action. Possible values are <@tt>assign, <@tt>get,
+ action. Possible values are <@tt>set, <@tt>get,
<@tt>add or <@tt>delete, it modifies the current
- settings as indicated. For more details, check the
- tutorial.
+ settings as indicated. For more details, check the tutorial.
}
return "if <@tt>$args empty return current instmixins, otherwise empty"
}
@@ -1215,7 +1081,7 @@
@ Class instproc instproc {
name "instance method name"
- ?non-pos-args?" "optional non-positional arguments"
+ ?non-pos-args?" "optinal non-positional arguments"
args "instance method arguments"
body "instance method body"
"?preAssertion?" "optional assertions that must hold before the proc executes"
@@ -1242,7 +1108,7 @@
description {
Convenience method to create an autonamed object. E.g.:
<@pre class='code'>
- HTTP new
+ Http new
creates ::xotcl::__#0, a subsequent call creates ::xotcl::__#1, ...<@br>
If <@tt>-childof obj is specified, the new object is
created as a child of the specified object.
@@ -1316,15 +1182,13 @@
}
@ Class instproc superclass {
- classList "?list of classes?"
+ classList "list of classes"
} {
description {
Specify super-classes for a class. "superclass" changes the list
- of superclasses dynamically to <@tt>classList.
- The method returns the current value of superclass,
- when it is called without arguments.
+ of superclasses dynamically to <@tt>classList.
}
- return "if <@tt>classList is not specified return superclass(es), otherwise empty"
+ return "empty string"
}
@ Class instproc unknown {
@@ -1345,13 +1209,13 @@
return "Standard unknown mechanism returns result of create"
}
-@ Object instproc volatile {
+@ Class instproc volatile {
"" ""
} {
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:
+ tcl-proc/object-proc/instproc is left. Example:
<@pre class='code'> set x [Object new -volatile]
}
return "empty string"
@@ -1376,73 +1240,6 @@
return "empty string"
}
-@ Class ::xotcl::Slot -superclass 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 -superclass ::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:
-
- <@tt>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::Parameter instproc values {param args}
#proc xotcl_mkindex