# -*- Tcl -*- # @package nx # # The <<@glossary nx>> is an object oriented scripting language based # on the Next Scripting Framework (TODO: passende Referenz <<@package # nsf>>). # The Next Scripting Language (NX) is a successor of XOTcl 1 and is # based on 10 years of experience with XOTcl in projects containing # several hundert thousand lines of code. While XOTcl was the first # language designed to provide language support for design patterns, the # focus of the Next Scripting Framework and NX are on combining this # with Language Oriented Programming. In many respects, NX was designed # to ease the learning of the language by novices (by using a more # mainstream terminology, higher orthogonality of the methods, less # predefined methods), to improve maintainability (remove sources of # common errors) and to encourage developer to write better structured # programs (to provide interfaces) especially for large projects, where # many developers are involved. # # NX is implemented as an object-oriented language extension for # <<@Gls tcl>>. The object system model is highly influenced by # <<@glossary clos>>, where classes are certain kind of objects and # objects might have their own properties (variables and methods) not # induced by the classes. The object system of NX is fully dynamic, # all object-class (e.g. instance-of relationship) and class-class # relationships (e.g. superclass relationship) can change at any time # at runtime. This way, object can change classes at runtime, or # objects might obtain different properties, etc. # # The language and object system of NX is implemeted by the package # nx. It defines the basic language entities <<@class ::nx::Object>> # and <<@class ::nx::Class>>, as well as essential language primitives # (in particular, <<@command ::nx::next>> and <<@command # ::nx::current>>). # # @require nsf # @version 1.0.0a # @namespace ::nx ######################################################################## # ::nx::Object ######################################################################## # @class Object # # ::nx::Object is the <<@gls baseclass>> of the <<@glossary nx>> # object system. All objects defined in NX are (direct or indirect) # instances of this base class. The methods provided by the Object # base class are available to all objects and to all classes defined # in NX. ######################################################################## # Attributes of ::nx::Object ######################################################################## # @class.property {Object class} # # Specifies the class of the object under construction as an object # parameter. This is equivalent to creating the object from this # class directly. # @class.property {Object filter} # # Register the specified methods as per-object <<@glspl # filter>>. Every name in the <<@gls filterspec>> must resolve to an # existing method in the scope of the object. # @class.property {Object mixin} # # Register the specified classes as per-object <<@glspl mixin_class>>. # Every name in the <<@gls mixinspec>> must correspond an existing # class. # # @spec object,type=::nx::Class # @class.property {Object noinit} # # Omit object initialization. When this flag is provided, the # constructor method '''init''' will not be called during object # construction. Consider, for example, reifying a previously # serialized object with its persisted state. Running the constructor # methods would risk altering the serialized state, e.g., by resetting # the object variables. # @class.property {Object properties} # # A shortcut notation for specifying a bulk of object properties, # including their parameter type specifications and default # values. For example: # ''' # nx::Object create o -properties { # {a:integer 0} # {b:boolean false} # c:object,type=::C # } # ''' # @class.property {Object volatile} # # Render the object created volatile. A volatile object is destroyed # automatically upon leaving the variable scope for which the object # construction was triggered. Examples of such variable scopes are # methods, Tcl procs, and <<@glspl initcmd>>. ######################################################################## # Methods of ::nx::Object ######################################################################## # @class.method {Object alias} # # Define an <<@gls alias>> as per-object method. This method is used # for defining a method with the specified name by binding a # pre-existing implementation. This alias target is provided as the # last argument. # # @parameter methodName Name of the new method # @parameter -returns Parameter specification to check the result of # the alias method (e.g. '''integer'''). # @parameter -frame Optional scoping information. If the provided # value is '''object''' then variable references of the # command are created as instance variables. If the value # is '''method''', then a method frame is pushed (the # method can resolve '''self'' or can call '''next'''). # @parameter cmd A reference to an implementation. If the # implementation is a method, the value should be a # <<@gls methodhandle>>, if it is a Tcl command, it should # be a fully qualified name. # @class.method {Object contains} # # A builder for nested object structures. Object and class # construction statements passed to this method as its last argument # are evaluated in a way so that the receiver object becomes the # parent of the newly constructed objects and classes. This is # realized by setting explicitly the namespace for constructing # relatively named objects. Fully qualified object names evade the # nesting. # ''' # nx::Class create Window { # :contains { # \# # \# Become children of Window, implicitly # \# # nx::Class create Header # nx::Object create Panel # } # \# # \# Explicitly declared a child of Window # \# # nx::Class create [self]::Slider # } # ''' # # @parameter -withnew:boolean Provides for re-scoping # automatically named objects so that they become # nested. If turned off, objects constructed using # <<@class.method {Class new}>> do not becomes children # of the receiver object. # @parameter -object An optional, fully-qualified object # name. If provided, this object will become the parent # object instead of the receiver object. # @parameter {-class:class ::nx::Object} An optional, # fully-qualified class name. If set jointly with the # '''object''' parameter, and the specified object does # not exist, the parent object is created from this # class. # @parameter cmds The construction statements for the objects # and classes to nest, as a script block. # @class.method {Object copy} # # Creates a full and deep copy of a given object. The object's copy # features all structural and behavioral properties of the source # object, including nested objects, the slots, namespaces, filters, # and mixins. # # @parameter newName The name of the copy target to be # created and populated with the strucural and # behavioral features of the source object. # @class.method {Object delete} # # Removes various structural and behavioral features of an object by # specifying their name: properties, variables, and methods. # @class.method {Object "delete property"} # # @parameter name The name of the property to delete # @class.method {Object "delete variable"} # # @parameter name The name of the variable to delete # @class.method {Object "delete method"} # # @parameter name The name of the method to delete # @class.method {Object property} # # Defines a per-object <<@gls property>>. For every property, a <<@gls # slotobject>> is created. A property also provides for a pair of # getter and setter methods, automatically. # # @parameter -class:class Allows for specifying a class for the # managing <<@gls slotobject>> other than the default # slot class, i.e., <<@class VariableSlot>> # @parameter -nocomplain:switch If this flag is provided, an # existing object variable by the property name will not # be overwritten. Instead, an error exception is thrown. # @parameter spec The propery specification can be a list of, at # least, one or two elements, maximum. The first element # specifies the property name, optionally followed by # parameter types after a colon delimiter. If provided, # the second element sets the default value for this # property. # @parameter initblock:optional A Tcl script which is # evaluated for the scope of the property's <<@gls # slotobject>> during its initialization. # @class.method {Object variable} # # Defines a per-object variable. Per default, no getter and setter # methods for this object variable are created, unless requested # explicitly. A defaul value can be specified. # # @parameter -accessor:switch If provided, a pair of getter # and setter methods, named after the variable, are # created on the fly. # @parameter -class Allows for specifying a class for the # managing <<@gls slotobject>> other than the default # slot class, i.e., <<@class VariableSlot>>. Note that a # slot object is not necessarily created by # '''variable''', only if needed (i.e., accessors are # requested, an init script is provided) # @parameter -initblock An optional Tcl script which is evaluated # for the scope of the variable-managing <<@gls # slotobject>> during its initialization. # @parameter -nocomplain:switch If this flag is provided, an # existing object variable by the property name will not # be overwritten. Instead, an error exception is thrown. # @parameter spec The variable specification is a single element # which specifies the variable name, optionally followed by # parameter types after a colon delimiter. # @parameter defaultValue If provided, sets the default value for this # object variable. # @class.method {Object "filter guard"} # # Attaches a guard expression to a previously defined per-object # filter; or returns the currently defined guards, if the last # argument is not provided. # # @parameter filter Name of the per-object filter to be guarded or queried for guards # @parameter guard:optional A guard expression applying to the per-object filter # @class.method {Object "mixin guard"} # # Attaches a guard expression to a previously defined per-object mixin; or # returns the currently defined guards, if the last argument is not # provided. # # @parameter mixin Name of the per-object mixin to be guarded or queried for guards # @parameter guard:optional A guard expression to shield the per-object mixin ######################################################################## # ::nx::Class ######################################################################## # @class Class # # ::nx::Class is the <<@gls basemetaclass>> of the <<@glossary nx>>. # All application classes are created as (direct or indirect) # instances from this class using, e.g., its <<@class.method "Class # create">> method: # # ''' # nx::Class create Window { # \# properties # :property size:object,type=::Area # :property {visibility:boolean true} # \# methods # :public method display {} {;} # :public method hide {} {;} # } # ''' ######################################################################## # Attributes of ::nx::Class ######################################################################## # @class.property {Class filter} # # Register the specified methods as per-class <<@glspl # filter>>. Every filter must be an existing method for the # scope of the class. # @class.property {Class mixin} # # Register the specified classes as per-class <<@glspl mixin_class>>. # Every mixin must be an existing class at the time of setting the # mixin relation. # @class.property {Class object-filter} # # Register the specified methods as per-object <<@glspl filter>> for # the class. Every filter must be an existing method for the scope of # the class object. # @class.property {Class object-mixin} # # Register the specified classes as per-object <<@glspl mixin_class>> # for the class object. Every mixin must be an existing class at the # time of setting the mixin relation. # @class.property {Class superclass} # # Set the superclasses for this class. The argument might contain a # list of classes to specify multiple inheritance. The order of the # superclasses is significant. At the time of specifying the class, # these superclasses must exist in the interpreter. ######################################################################## # Methods of ::nx::Class ######################################################################## # @class.hook {Class alloc} # # Creates an uninitialized object. The method '''alloc''' is used by # <<@class.method "::nx::Class create">> to allocate an object and to # invoke <<@class.method "::nx::Object configure">> and '''init''' in # subsequent steps to fully initialize the object. Only in rare # situations, an application developer may consider bypassing the # overall '''create''' mechanism to create uninitialized objects. # # @parameter objectName The designated object identifier assigned to the # object storage to be allocated. # @return The fully qualified name of the allocated, uninitialized object # @class.method {Class alias} # # Define an <<@gls alias>> as class-wide method. This helper method is # used for defining a method with the specified name by binding a # pre-existing implementation. This alias target is provided as the # last argument. # # @parameter methodName Name of the new method # @parameter -returns Parameter specification to check the result of # the alias method (e.g. '''integer'''). # @parameter -frame Optional scoping information. If the provided # value is '''object''', then variable references of the # command are created as instance variables. If the value # is '''method''', then a method frame is pushed. Thus, the # method can resolve <<@command current>> and can call # <<@command next>>. # @parameter cmd A reference to an implementation. If the # implementation is a method, the value should be a # <<@gls methodhandle>>. If it is a Tcl command, it should # be a fully qualified command name. # @class.method {Class class} # # The '''class''' modifier can be applied to a variety of methods to # perform their operations for the scope of a class object, rather # than for their instances. # @class.method {Class "class delete"} # @class.method {Class "class delete property"} # # @parameter name The name of the property to delete # @class.method {Class "class delete variable"} # # @parameter name The name of the variable to delete # @class.method {Class "class delete method"} # # @parameter name The name of the method to delete # @class.method {Class "class alias"} # # @use class.method {Object alias} # @class.method {Class "class forward"} # # @use class.method {Object forward} # @class.method {Class "class info"} # # Provides introspection on class objects. A variety of introspection # options exists. '''info''' is implemented as an <<@gls # ensemble>>. Hence, the introspection options turn into proper # submethods. See <<@class.method "Object info">> for details. # @class.method {Class "class method"} # # Defines a method for a class object, similarly to creating <<@Gls tcl>> # '''procs'''. Optionally, pre- and post-conditions may be specified # by passing two additional arguments. Therefore, to specify only # post-assertions an empty pre-assertion list must be given. All # assertions are a list of ordinary <<@acr tcl>> '''expr''' # statements. When '''method''' is called with an empty argument list # and an empty body, the specified method is deleted. # ''' # Class create C { # :public class method foo args {;} # :public class method bar args {;} # } # # C foo; # invokes "foo" # # C class method foo {} {}; # deletes "foo" # C class delete method bar; # deletes "bar" # ''' # # @parameter name The method name # @parameter arguments:parameter,0..* A list specifying # non-positional and positional method parameters, plus # their parameter types/options. # @parameter -returns Provide an out parameter # specification, used to check the # return value of the method dispatch. # @parameter body The script which forms the method body # @parameter -precondition Optional assertions that must hold before # the proc executes # @parameter -postcondition Optional assertions that must hold after # the proc executes # @class.method {Class "class filterguard"} # # Attaches a guard expression to a previously defined filter on the # class object; or returns the currently defined guards, if the last # argument is not provided. # # @parameter filter Name of the per-object filter to be guarded or queried for guards # @parameter guard:optional A guard expression applying to the per-object filter # @class.method {Class "class mixinguard"} # # Attaches a guard expression to a previously defined mixin on the # class object; or returns the currently defined guards, if the last # argument is not provided. # # @parameter mixin Name of the per-object mixin to be guarded or queried for guards # @parameter guard:optional A guard expression to shield the per-object mixin # @class.method {Class "class variable"} # # @use class.method {Object variable} # @class.method {Class "class filter"} # # Register the specified methods as <<@glspl filter>> with the class # object. Every name in the <<@gls filterspec>> must resolve to an # existing method in the scope of the class object. # # @parameter args One or more <<@glspl filterspec>> # @class.method {Class "class mixin"} # # Register the specified classes as <<@glspl mixin_class>> with the # class object. Every mixin must be an existing class at the time of # setting the mixin relation. # # @parameter args One or more <<@glspl mixin_class>> specifications # @class.method {Class "class property"} # # @use class.method {Object property} # @class.method {Class delete} # # Removes various structural and behavioral features (i.e., # properties, variables, and methods) of a class based on the feature # names. # @class.method {Class "delete property"} # # @parameter name The name of the property to delete # @class.method {Class "delete variable"} # # @parameter name The name of the variable to delete # @class.method {Class "delete method"} # # @parameter name The name of the method to delete # @class.method {Class "filter guard"} # # Attaches a guard expression to a previously defined class-wide # filter; or returns the currently defined guards, if the last # argument is not provided. # # @parameter filter Name of the per-class filter to be guarded or queried for guards # @parameter guard:optional A guard expression applying to the class-wide filter # @class.method {Class "mixin guard"} # # Attaches a guard expression to a previously defined per-class mixin; or # returns the currently defined guards, if the last argument is not # provided. # # @parameter mixin Name of the per-class mixin to be guarded or queried for guards # @parameter guard:optional A guard expression to shield the per-class mixin # @class.method {Class info} # # Provides introspection on classes. A variety of introspection # options exists. '''info''' is implemented as an <<@gls # ensemble>>. Hence, the introspection options appear as proper # submethods. Introspective features, if not documented below, are # inherited from <<@class.method "Object info">>. # # @sub-method filter # @sub-method mixin # @sub-method slot # @sub-method parameter # @class.method {Class "info filter guard"} # # Returns the guards for filter identified by the name of a <<@gls filter>> # # @parameter filter Registration name of the filter # @class.method {Class "info filter methods"} # # Returns a list of methods registered as <<@glspl filter>>. # # @parameter -guards The filter guards are also returned # @parameter pattern Return only method for filter names # matching the given pattern (like # '''string match''') # @class.method {Class "info properties"} # # Report all properties defined for a class. The properties are # printed in their property-defining notation: '''name:paramtype # ?default?'''. # # @parameter {-type:class ::nx::Slot} Select the kind of # slot objects to be # returned by specifying # a class (e.g., # <<@class # VariableSlot>>). # @parameter -closure:switch Include the slots managing this # class over the transitive # relationships of the class, with # its superclasses and transitive # mixin classes. # @parameter -source Restrict the search to either # '''application''' classes or # '''baseclasses'''. If omitted, the # search includes '''all''' classes. # @parameter pattern:optional Restrict the lookup to slot objects # matching the given pattern string # in the sense of '''string match''' # @class.method {Class "info methods"} # # Allows you to query the methods defined on the object. Note the # difference to <<@class.method "Object {info lookup methods}">> which # covers all methods actually callable upon the class object itself. # # @parameter -callprotection Restrict to the methods of a specific # call protection level: '''public''', '''protected''', # '''private''', or '''all''' (the latter is the default). # @parameter -closure:switch Include the methods defined over # the transitive relationships of the # class, i.e., by its superclasses # and transitive mixin classes. # @parameter -type Restrict the search by certain method # kinds: '''scripted''', '''builtin''', '''alias''', # '''forwarder''', '''object''', and '''setter'''. If # omitted, '''all''' method sorts are considered. # @parameter -path The pattern is expressed over the method paths, # rather than the method names. This allows for matching # <<@glspl ensemble>>. # @parameter -source Restrict the search to either # '''application''' classes or # '''baseclasses'''. If omitted, the # search includes '''all''' classes. # @parameter pattern The pattern string in the style of '''string match''' # @class.method {Class "info heritage"} # # Returns the ordered list of superclasses of a class. # # @parameter pattern A pattern string in the sense of # '''string match''' to be matched with # the candidate class names. # @class.method {Class "info instances"} # # Gives the list of instances, i.e., the member objects of the class. # # @parameter -closure:switch Include the instances defined over # the transitive subclass relationships of the # class. # @parameter pattern A pattern string in the sense of # '''string match''' to be matched with # the candidate class names. # @class.method {Class "info mixin guard"} # # Retrieves the <<@glspl guard>> applied to the mixin class # idenitified by the mixin class name # # @parameter mixin The name of the mixin whose guards are requested # @class.method {Class "info mixin classes"} # # The list of per-object <<@glspl mixin_class>> currently registered for the # class is returned. # # @parameter -closure Extend the pattern search to the # indirect mixin classes, by traversing # all direct and indirect per-class # mixin relations. # @parameter -guards Add the guard expressions of the mixin # classes to the output # @parameter -heritage Ascertain that the mixin context of # the object is valid # @parameter pattern Restrict the lookup to class names # matching the given pattern string, in # the sense of '''string match''' # @class.method {Class "info mixinof"} # # Identifies the classes for which the receiver class is registered as # a mixin. # # @parameter -closure:switch Include the instances defined over # the transitive mixin relationships # of the class. If set, all # per-object and per-class mixin axes # are traversed. # @parameter -scope Restrict the registration scope to # either per-class ('''class''') or # per-object mixins ('''object'''). By # default, '''all''' mixin registrations # are reported. # @parameter pattern A pattern string in the sense of # '''string match''' to be matched with # the candidate class names. # @class.method {Class "info subclass"} # # The list of subclasses derived from the class is returned. # # @parameter -closure:switch Include the classes down # the transitive subclass # relationships of the class. If set, # all consecutive subclass # relations are traversed. If # omitted, only direct subclasses # are reported. # @parameter pattern A pattern string in the sense of # '''string match''' to be matched with # the candidate subclass names. # @class.method {Class "info superclass"} # # Returns the list of superclasses specified for the given class. # # @parameter -closure:switch Include the classes along # the transitive superclass # relationships of the class. If set, # all consecutive superclass # relations are traversed. If # omitted, only direct superclasses # are reported. # @parameter pattern A pattern string in the sense of # '''string match''' to be matched with # the candidate superclass names. # @class.method {Class "info slot definition"} # # Report all <<@glspl slot>> defined for a class. The slots owned by # the given slot are reported in the property-defining notation: # '''name:paramtype ?default?'''. Do not confuse this introspector # with <<@class.method "Object {info lookup slots}">> which gives all # slots managing the current class object. # # @parameter {-type:class ::nx::Slot} Select the kind of # slot objects to be # returned by specifying # a class (e.g., # <<@class # VariableSlot>>). # @parameter -closure:switch Include the classes along the # transitive mixin and superclass # relationships of the class. If set, # all indirect superclass and # transitive mixins are covered. If # omitted, only direct superclasses # are reported. # @parameter -source Restrict the search to either # '''application''' classes or # '''baseclasses'''. If omitted, the # search includes '''all''' classes. # @parameter pattern:optional Restrict the lookup to slot objects # matching the given pattern string in # the sense of '''string match''' # @class.method {Class "info slot names"} # # Report the names of all <<@glspl slot>> defined for the class. Do # not confuse this introspector with <<@class.method "Object {info # lookup slots}">> which gives all slots managing the instances of the # current class. # # @parameter {-type:class ::nx::Slot} Select the kind of # slot objects to be # returned by specifying # a class (e.g., # <<@class # VariableSlot>>). # @parameter -closure:switch Include the classes along the # transitive mixin and superclass # relationships of the class. If set, # all indirect superclass and # transitive mixins are covered. If # omitted, only direct superclasses # are reported. # @parameter -source Restrict the search to either # '''application''' classes or # '''baseclasses'''. If omitted, the # search includes '''all''' classes. # @parameter pattern:optional Restrict the lookup to slot objects # matching the given pattern string in # the sense of '''string match''' # @class.method {Class "info slot objects"} # # Report the fully qualified command names of all <<@glspl slot>> # defined for a class. Do not confuse this introspector with # <<@class.method "Object {info lookup slots}">> which gives all slots # managing the receiver class. # # @parameter {-type:class ::nx::Slot} Select the kind of # slot objects to be # returned by specifying # a class (e.g., # <<@class # VariableSlot>>). # @parameter -closure:switch Include the classes along the # transitive mixin and superclass # relationships of the class. If set, # all indirect superclass and # transitive mixins are covered. If # omitted, only direct superclasses # are reported. # @parameter -source Restrict the search to either # '''application''' classes or # '''baseclasses'''. If omitted, the # search includes '''all''' classes. # @parameter pattern:optional Restrict the lookup to slot # objects matching the given # pattern string in the sense of # '''string match''' # @class.method {Class "info parameter definitions"} # # Returns all parameters, or the selected one, as object parameter # specifications # # @parameter name:optional If provided, the result is limited to # the parameter identified by this name # value # @class.method {Class "info parameter list"} # # Returns all parameters, or the selected one, as a list of dashed # parameter name(s) # # @parameter name:optional If provided, the result is limited to # the parameter identified by this name # value # @class.method {Class "info parameter names"} # # Returns the bare names of all parameters, or the selected one # # @parameter name:optional If provided, the result is limited to # the parameter identified by this name # value # @class.method {Class "info parameter syntax"} # # Returns an annotated representation of all object parameters, or the # selected one. The representation resembles the Tcl command call # listings (e.g., as featured in the man pages). # # @parameter name:optional If provided, the result is limited to # the parameter identified by this name # value # @class.method {Class create} # # Provides for creating application-level classes and objects. If # the method receiver is a <<@gls metaclass>>, a <<@gls class>> will be # created. Otherwise, '''create''' yields an object. '''create''' # is responsible a multi-phase object creation scheme. This # creation scheme involves three major steps: # ''' # [Object create anObject] (1) # ---------------. .--------------. # -------------->|Class->create()|-->|Class->alloc()| # `---------------' `--------------' # | | (2) .-------------------. # | .----->|Object->configure()| # | `-------------------' # | (3) .------. # .........>|init()| # `------' # ''' # (1) A call to <<@class.method "::nx::Class alloc">> to create a raw, # uninitalized object. # # (2) The newly allocated object receives a method call upon # <<@class.method "::nx::Object configure">>. This will establish the # object's initial state, by applying <<@gls objparam>> values # provided at object creation time and default values defined at # object definition time. # # (3) Finally, '''create''' emits a call to the initialization method # '''init''', if available. An '''init''' method can be defined by a # class on behalf of its objects, to lay out class-specific # initialisation behaviour. Alternatively, each single object may # define an '''init''' method on its own. # # By overloading the method in a <<@gls metaclass>>, you can refine or # replace this default object creation scheme (e.g., for applying # application-specific naming schemes). # # For creating an object or a class, you must name '''create''' # explicitly, i.e.: # ''' # ::nx::Object create anObject # ::nx::Class create AClass # \# This fails: "Method 'AnotherClass' unknown for ::nx::Class." # ::nx::Class AnotherClass # ''' # Note that this method is also invoked internally when executing # <<@class.method {Class new}>>. # # @parameter name The designated identifier on the class or the object to be created. # @parameter args arguments to be passed down to the object creation # procedure used to initialize the object. # @return The fully qualified name of the created object. # @class.hook {Class dealloc} # # Marks objects for physical deletion in memory. Beware the fact # that calling '''dealloc''' does not necessarily cause the object # to be deleted immediately. Depending on the lifecycle of the # object's environment (e.g., the '''interp''', the containing # namespace) and on call references down the callstack, the actual # memory freeing operation may occur time-shifted (that is, # later). While '''dealloc''' itself cannot be redefined for # '''::nx::Class''', you may consider refining it in a subclass or # <<@gls mixin_class>> for customizing the destruction process. # # @parameter object The name of the object to be scheduled for deletion. # @class.hook {Class recreate} # # This method is called upon recreating an object. Recreation is the # scheme for resolving object naming conflicts in the dynamic and # scripted programming environment of <<@Gls nx>>: An object or class is # created while an object or class with an identical object identifier # already exists. The method '''recreate''' performs standard object # initialization, per default, after re-setting the state and # relationships of the object under recreation. # ''' # Object create Bar # \# ... # Object create Bar; # calls Object->recreate(::Bar, ...) # ''' # By refining '''recreate''' in an application-level subclass or mixin # class, you can intercept the recreation process. In the pre-part the # refined '''recreate''' method, the recreated object has its old # state, after calling <<@command ::nx::next>> it has been cleaned up. # # If the name conflict occurs between an existing class and a newly # created object (or vice versa), '''recreate''' is not # performed. Rather, a sequence of <<@class.method "::nx::Object # destroy">> and <<@class.method "::nx::Class create">> is triggered: # ''' # Object create Bar # \# ... # \# calls Bar->destroy() -> Class->create(::Bar, ...) # Class create Bar; # ''' # # @parameter name The name (identifier) of the object under recreation # @parameter args Arbitrary vector of arguments # @return The name of the recreated object # @class.hook {Object unknown} # # A hook implementation of the abstracted '''unknown''' hook, called # from within the '''interp''' when the method argument could not # be resolved to a callable method receiver on the given object. # # @parameter m Indicates the unresolvable method name # @parameter args Contains the remainder of the original # argument vector of the indirected method # invocation # @command next # # @use ::nsf::next # @command current # # @use ::nsf::current # @class.hook {Object configure} # # This method participates in the object construction process. It is # automatically invoked after having produced a new object in # <<@class.method "::nx::Class create">>. Upon its invocation, the # variable argument vector '''args''' contains a list of parameters # and parameter values passed in from the call site of the object # construction. They are matched against an <<@gls objparam>> # definition. This definition, and so the actual method parameter # definition of this method, is assembled from configuration values of # the classes along the precedence order (see also <<@class.method # "::nx::Object objectparameter">>). The method '''configure''' # can be called at arbitrary times to "re-set" an object. # # @parameter args The variable argument vector delivers the # object parameters and their values, used to # initialize the object under construction # @class.hook {Object defaultmethod} # # An abstracted hook method which is invoked upon calls to an object # without providing a method name to identify the receiver. In <<@Gls # nx>>, the defaultmethod hook implementation returns the object name, # i.e., the result of <<@command current>>. # ''' # Object create ::foo # ::foo defaultmethod; # returns '::foo' # ::foo; # returns '::foo' # ''' # This hook is a versatile extension mechanism to alter the standalone # use of Tcl commands representing objects. # @class.hook {Object init} # # An abstracted hook method which participates in the object # construction process controlled by <<@class.method {Class # create}>>. It is invoked as the last step during object construction # upon the newly created object to provide an intial state. It # resembles the notion of an application-level constructor. The hook # is meant to be provided by application developers for initialising # their application classes and objects. Note that a custom # implemented '''init''' constructor must not contain a parameter # specification. Your init must not expect or does not receive any # arguments from the NX object construction machinery. # # @parameter args Note: In NX, this will be an empty list (i.e., # '''[list]''' or {}) # @class.method {Object destroy} # # The standard shutdown handler ("destructor") for all # objects. Destruction, finally, commands the physical deletion of the # object. The method '''destroy''' can be refined by subclasses or # <<@glspl mixin_class>> to add additional, class-specific shutdown # behaviour. Note that, in most cases, the class-specific # '''destroy''' methods are expected to call <<@command ::nx::next>> # to request the physical destruction, ultimately. # ''' # nx::Class create Foo { # :method destroy {} { # puts "destroying [self]" # next # } # } # Foo create f1 # f1 destroy # ''' # Some background details: The method <<@class.method "::nx::Object destroy">> # delegates the actual destruction to <<@class.method "::nx::Class # dealloc">> which clears the memory object storage. Essentially, this # behaviour could be scripted as: # ''' # Object method destroy {} { # [:info class] dealloc [self] # } # ''' # Note, however, that '''destroy''' is protected against # application-level redefinition. You must refine it in a subclass # or a <<@gls mixin_class>>. # @class.method {Object uplevel} # # This helper allows you to evaluate a script in the context of # another callstack level (i.e., callstack frame). # # @parameter level:optional The starting callstack level (defaults to the # value of '''[current callinglevel]''') # @parameter script:list The script to be evaluated in the targeted # callstack level # @class.method {Object eval} # # Evaluate a special Tcl script for the scope of the receiver # object. In this script, you may use the colon-prefix notation to # dispatch to methods and access variables of the eval-receiving # object. Also, you can maintain script-local variables to store # intermediate results. # ''' # nx::Object create a { # :property {bar 1} # :public method foo {x} { return $x } # } # # set script { # set y [:foo ${:bar}] # } # # a eval $script # ''' # # @parameter args An argument vector concatenated to a string # and then evaluated as a script # @class.method {Object upvar} # # This helper allows you to bind a local variable to a variable # residing at a different callstack level (frame). # # @parameter level:optional The starting callstack level (defaults to the # value of '''[current callinglevel]''') # # @parameter sourceVar A variable which should be linked to a ... # @parameter targetVar ... which is a local variable in a method scope # @see ... # @class.method {Object volatile} # # By calling on this method, the object is bound in its lifetime to # the one of the active call site (e.g., the given <<@acr tcl>> proc or method # scope): # ''' # proc foo {} { # info vars; # shows "" # set x [Object create Bar -volatile] # info vars; # shows "x Bar" # } # ''' # Behind the scenes, '''volatile''' registers a C-level variable trace # ('''Tcl_TraceVar()''') on the hiddenly created local variable (e.g., # '''Bar'''), firing upon unset events and deleting the referenced # object ('''Bar'''). That is, once the callframe context of '''foo''' # is left, the local variable '''Bar''' is unset and so the bound # object destruction is triggered. # @class.method {Class new} # # A convenience method to create auto-named objects and <<@glspl # class>>. It is a frontend to <<@class.method "::nx::Class # create">>. For instance: # ''' # set obj [nx::Object new] # set cls [nx::Class new] # set w [Window new] # ''' # This will provide object identifiers of the form # e.g. '''::nsf::__#0'''. The uniqueness of auto-generated identifiers # is guaranteed for the scope of the current '''interp'''. # # @parameter -childof If provided, the new object is created as a child of # the specified object. # @parameter args The variable arguments passed down to <<@class.method # "::nx::Class create">>. # @class.method {Class property} # # Defines a <<@gls property>> for an entire class. For every property, # a <<@gls slotobject>> is created. A property also provides for a # pair of getter and setter methods, automatically. The getter and # setter are available for instances of the class. # # @parameter -class:class Allows for specifying a class for the # managing <<@gls slotobject>> other than the default # slot class, i.e., <<@class VariableSlot>> # @parameter spec The propery specification can be a list of, at # least, one or two elements, maximum. The first element # specifies the property name, optionally followed by # parameter types after a colon delimiter. If provided, # the second element sets the default value for this # property. # @parameter initblock:optional A Tcl script which is # evaluated for the scope of the property's <<@gls # slotobject>> during its initialization. # @class.hook {Class unknown} # # A hook implementation of the abstracted '''unknown''' hook, called # from within the '''interp''' when the method argument could not # be resolved to a callable method on the receiving object. # # @parameter methodName Indicates the unresolvable method name # @parameter args Contains the remainder of the original # argument vector of the indirected method # invocation # @class.method {Class variable} # # Defines a variable for the scope of a class. Per default, no getter # and setter methods for this object variable are created, unless # requested explicitly. Also, a variable does not become an object # parameter automatically. A defaul value can be specified. # # @parameter -accessor:switch If provided, a pair of getter # and setter methods, named after the variable, are # created on the fly. # @parameter -class Allows for specifying a class for the # managing <<@gls slotobject>> other than the default # slot class, i.e., <<@class VariableSlot>>. Note that a # slot object is not necessarily created by # '''variable''', only if needed (i.e., accessors are # requested, an init script is provided) # @parameter -config:switch Make the variable an object parameter, # rendering the variable accessible during instance # construction # @parameter -initblock An optional Tcl script which is evaluated # for the scope of the variable-managing <<@gls # slotobject>> during its initialization. # @parameter spec The variable specification is a single element # which specifies the variable name, optionally followed by # parameter types after a colon delimiter. # @parameter defaultValue If provided, sets the default value for this # object variable. # @class.method {Class method} # # Defines a class-wide method available to all instances of the class, # similarly to Tcl specifying '''procs'''. Optionally, pre- and # post-conditions 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 <<@Gls tcl>> '''expr''' statements. When '''method''' is # called with an empty argument list and an empty body, the specified # method, if existing, is deleted. # ''' # Class create AClass { # :public method foo args {;} # :public method bar args {;} # } # # AClass create anInstance # anInstance foo; # invokes "foo" # # AClass method foo {} {}; # deletes "foo" # AClass delete method bar; # deletes "bar" # ''' # # @parameter name The method name # @parameter arguments:parameter,0..* A list specifying # non-positional and positional method parameters, plus # their parameter types/options. # @parameter -returns Provide an out parameter # specification, used to check the # return value of the method dispatch. # @parameter body The script which forms the method body # @parameter -precondition Optional assertions that must hold before # the proc executes # @parameter -postcondition Optional assertions that must hold after # the proc executes # @class.method {Object method} # # Defines a per-object method, similarly to creating <<@gls tcl>> # '''procs'''. Optionally, pre- and post-conditions may be specified # by passing two additional arguments. Therefore, to specify only # post-assertions an empty pre-assertion list must be given. All # assertions are a list of ordinary <<@acr tcl>> '''expr''' # statements. When '''method''' is called with an empty argument list # and an empty body, the specified method is deleted. # ''' # Object create anObject { # :public method foo args {;} # :public method bar args {;} # } # # anObject foo; # invokes "foo" # # anObject method foo {} {}; # deletes "foo" # anObject delete method bar; # deletes "bar" # ''' # # @parameter name The method name # @parameter arguments:parameter,0..* A list specifying # non-positional and positional method parameters, plus # their parameter types/options. # @parameter -returns Provide an out parameter # specification, used to check the # return value of the method dispatch. # @parameter body The script which forms the method body # @parameter -precondition Optional assertions that must hold before # the proc executes # @parameter -postcondition Optional assertions that must hold after # the proc executes # @class.method {Object forward} # # Register a special-purpose per-object method (similar to a # '''proc'''), referred to as a <<@gls forwarder>>, for # forward-delegating calls to a callee (a <<@acr tcl>> command, a method owned # by another object). When the <<@gls forwarder>> method is called, # the actual arguments of the invocation are appended to the specified # arguments. Certain manipulations can be applied on the # forward-passed argument vector: # # '''%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''' The command to be executed; the result of the # command evaluation is substituted for the placeholding statement. # # 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. # # @parameter method The name of the delegating or forwarder method # @parameter -default Is used for default method names (only # in connection with %1) # @parameter -methodprefix Prepends the specified prefix to the second # argument of the invocation. # @parameter -objframe Causes the target to be evaluated in # the scope of the object. # @parameter -onerror Register an error handler # @parameter -returns Provide an out parameter # specification, used to check the # return value of the forward dispatch. # @parameter -verbose Print the substituted command string to stderr # before performing the command # execution. For debugging purposes. # @parameter target Possibly the name of the delegatee (a # Tcl proc, method, object, ...), or an # argument mutator/accessor (e.g., # '''%self''', '''%proc''') # @parameter args The specified argument vector, # consisting of literal values and/or # argument accessors/mutators # @class.method {Object move} # # Effectively renames an object. First, the source object is copied # using <<@class.method {Object copy}>>. Second, the source object is # destroyed by invoking <<@class.method {Object destroy}>> on it. This # method is also called internally when '''rename''' is performed for # a Tcl command representing an object. # # @parameter newName The name of the target object # @class.method {Object private} # # The modifier method sets the '''private''' property of the method # under definition. # ''' # nx::Class create A { # :private method foo {} {;} # :private property bar # :private alias baz -frame object ::incr # :private class method baf {} {;} # } # ''' # # @parameter args Argument vector which details a # method-defining operation (e.g., # <<@class.method {Object method}>>, # <<@class.method {Object alias}>>) # @class.method {Object protected} # # The modifier method sets the '''protected''' property of the method # under definition. # ''' # nx::Class create A { # :protected method foo {} {;} # :protected property bar # :protected alias baz -frame object ::incr # :protected class method baf {} {;} # } # ''' # # @parameter args Argument vector which details a # method-defining operation (e.g., # <<@class.method {Object method}>>, # <<@class.method {Object alias}>>) # @class.method {Object public} # # The modifier method sets the '''public''' property of the method # under definition. # ''' # nx::Class create A { # :public method foo {} {;} # :public property bar # :public alias baz -frame object ::incr # :public class method baf {} {;} # } # ''' # # @parameter args Argument vector which details a # method-defining operation (e.g., # <<@class.method {Object method}>>, # <<@class.method {Object alias}>>) # @class.method {Class forward} # # @use class.method {Object forward} # @class.method {Object info} # # Provides introspection on objects. A variety of introspection # options exists. '''info''' is implemented as an <<@gls # ensemble>>. Hence, the introspection options turn into proper # submethods. # # @sub-method lookup # @sub-method has # @sub-method filter # @sub-method mixin # @sub-method slot # @class.method {Object "info is"} # # Verifies whether a given object acts as an application class (i.e., # an instance of <<@class Class>>), as a metaclass (i.e., an instance of # <<@class Class>> which also subclasses <<@class Class>>), or an # object-system class. # # @parameter objectkind Specifies the class test: '''class''', # '''baseclass''', '''metaclass''' # @class.method {Object "info lookup filter"} # # Search for a method which is currently registered as a filter (in # the invocation scope of the given object). If found, the # corresponding <<@gls methodhandle>> is returned. # @class.method {Object "info lookup method"} # # Verifies whether there is a method under a given name available for # invocation upon the object. In case, the introspective call returns # the corresponding <<@gls methodhandle>>. If there is no so-named # method available, an empty string is returned. # @class.method {Object "info lookup methods"} # # Retrieves the methods which are available for dispatch (which are # therefore callable) on the given object. The result set can be # constraint by a match pattern. If the answer set is empty, an empty # string is returned. The answer set can be restricted not only via # match pattern, but also via the following parameters: # # @parameter -callprotection Restrict to the methods of a specific # call protection level: '''public''', '''protected''', # '''private''', or '''all''' (the latter is the default). # @parameter -incontext The search will consider the full # dispatch context, i.e., mixin guards # are incorporated when selecting the # method population. This filter assumes # that mixin-provided methods should be # covered (see also '''-nomixins'''). # @parameter -type Restrict the search by certain method # kinds: '''scripted''', '''builtin''', '''alias''', # '''forwarder''', '''object''', and '''setter'''. If # omitted, '''all''' method sorts are considered. # @parameter -nomixins If set, exclude methods provided by # <<@glspl mixin_class>> # @parameter -path The pattern is expressed over the method paths, # rather than the method names. This allows for matching # <<@glspl ensemble>>. # @parameter -source Restrict the search to either # '''application''' classes or '''baseclasses'''. If # omitted, the search includes '''all''' classes. # @parameter pattern The pattern string in the style of '''string match''' # @class.method {Object "info lookup slots"} # # Returns the list of <<@glspl slot>> which manage the state of the # given object. They are resolved by following the class <<@gls # precedence>> upward and coercing the lists of slots provided by # all classes. # # @parameter {-type:class ::nx::Slot} Select the kind of # slot objects to be # returned by specifying # their class (e.g., # <<@class # VariableSlot>>). # @parameter -source Find either slot objects responsible # for '''application''' classes or '''baseclasses'''. If # omitted, '''all''' classes are considered. # @parameter pattern:optional Restrict the lookup to slot objects # matching the given pattern string in # the sense of '''string match''' # @class.method {Object "info children"} # # Computes the list of aggregated (or nested) objects. The resulting # list reports the fully qualified object names. If a <<@gls # namepattern>> was specified, all child objects, whose names are # matched by the pattern, are returned. Otherwise, all children are # reported. # # @parameter -type Filter children by their class membership. # @parameter pattern A filter string applying to the command names # of the children (like a '''string match''' # pattern). # @class.method {Object "info class"} # # Returns the name of the object's class. # @class.method {Object "info filter guard"} # # Returns the guards for filter identified by the name of a <<@gls filter>> # # @parameter name Registration name of the filter # @class.method {Object "info filter methods"} # # Returns a list of methods registered as <<@glspl filter>>. # # @parameter -guards The filter guards are also returned # @parameter -order Request that the filters are reported # in valid order # @parameter patterns Return only method for filter names # matching the given pattern (like # '''string match''') # @class.method {Object "info has mixin"} # # Verifies in a boolean test whether the object has a given <<@gls # mixin_class>>. # # @parameter class The class which is tested for its property as mixin # of the given object # @class.method {Object "info has namespace"} # # Tells you whether the object has a companion, per-object <<@acr # tcl>> namespace. Note that the results do not necessarily correspond # to those yielded by '''[namespace exists /obj/]'''. See also # <<@class.method "Object {require namespace}">>. # @class.method {Object "info has type"} # # Tests whether the class passed as the argument is a type of the # object, i.e., whether the object is an instance of the given class # or of one of the class's superclasses. # # @parameter class The class name to be tested against the object. # @class.method {Object "info methods"} # # Allows you to query the methods defined on the object. Note the # difference to <<@class.method "Object {info lookup methods}">> which # covers all methods actually callable upon the object. # # @parameter -callprotection Restrict to the methods of a specific # call protection level: '''public''', '''protected''', # '''private''', or '''all'' (the latter is the default). # @parameter -type Restrict the search by certain method # kinds: '''scripted''', '''builtin''', '''alias''', # '''forwarder''', '''object''', and '''setter'''. If # omitted, '''all''' method sorts are considered. # @parameter -path The pattern is expressed over the method paths, # rather than the method names. This allows for matching # <<@glspl ensemble>>. # @parameter pattern The pattern string in the style of '''string match''' # @class.method {Object "info name"} # # Returns the name of an object without the namespace qualifiers. # @class.method {Object "info slot definition"} # # Report all <<@glspl slot>> defined for an object. The slots owned by # the given object are reported in the property-defining notation: # '''name:paramtype ?default?'''. Do not confuse this introspector # with <<@class.method "Object {info lookup slots}">> which gives all # slots managing the current object. # # @parameter {-type:class ::nx::Slot} Select the kind of # slot objects to be # returned by specifying # a class (e.g., # <<@class # VariableSlot>>). # @parameter pattern:optional Restrict the lookup to slot objects # matching the given pattern string in # the sense of '''string match''' # @class.method {Object "info slot names"} # # Report the names of all <<@glspl slot>> defined for an object. Do not # confuse this introspector with <<@class.method "Object {info lookup # slots}">> which gives all slots managing the current object. # # @parameter {-type:class ::nx::Slot} Select the kind of # slot objects to be # returned by specifying # a class (e.g., # <<@class # VariableSlot>>). # @parameter pattern:optional Restrict the lookup to slot objects # matching the given pattern string in # the sense of '''string match''' # @class.method {Object "info slot objects"} # # Report the fully qualified command names of all <<@glspl slot>> # defined for an object. Do not confuse this introspector with # <<@class.method "Object {info lookup slots}">> which gives all slots # managing the current object. # # @parameter {-type:class ::nx::Slot} Select the kind of # slot objects to be # returned by specifying # a class (e.g., # <<@class # VariableSlot>>). # @parameter pattern:optional Restrict the lookup to slot # objects matching the given # pattern string in the sense of # '''string match''' # @class.method {Object "info properties"} # # Report all properties defined for an object. The properties are # printed in their property-defining notation: '''name:paramtype # ?default?'''. # # @parameter {-type:class ::nx::Slot} Select the kind of # slot objects to be # returned by specifying # a class (e.g., # <<@class # VariableSlot>>). # @parameter pattern:optional Restrict the lookup to slot objects # matching the given pattern string in # the sense of '''string match''' # Should be: # \@use class.method {Object "info slot definition"} # @class.method {Object "info mixin guard"} # # Retrieves the <<@glspl guard>> applied to the mixin class # idenitified by the mixin class name # # @parameter mixin The name of the mixin whose guards are requested # @class.method {Object "info mixin classes"} # # The list of per-object <<@glspl mixin_class>> currently registered for the # object is returned. # # @parameter -guards Add the guard expressions of the mixin # classes to the output # @parameter -heritage Ascertain that the mixin context of # the object is valid # @parameter pattern:optional Restrict the lookup to class names # matching the given pattern string, in # the sense of '''string match''' # @class.method {Object "info parent"} # # Returns the fully qualified name of the parent object; or the name # of the global Tcl namespace "::" if there is no parent object. # @class.method {Object "info precedence"} # # Presents to you the list of classes the object is inheriting # properties and methods from, ordered according to their <<@gls # precedence>>. # # @parameter -intrinsic Limit the reported linearization list # to the intrinsic class # hierarchy. Excludes <<@glspl # mixin_class>> explicitly. # @parameter pattern A pattern string in the sense of # '''string match''' to be matched with # the candidate class names. # @class.method {Object "info unknown"} # # The unknown handler for the '''info''' method ensemble. It is called # upon messages to undefined info sub-methods. It provides for # generating a list of valid sub-methods to recover from the error # condition (see <<@class.method "Object {info info}">>). Unlike other # unknown handlers, the self-context of the unknown method is the # definition object and not the receiver. Therefore, the receiver # object is provided as the second argument. # # @parameter method The name of the undefined '''info''' sub-method # @parameter obj:object The receiver of the '''info''' call # which is the registration object # @parameter args The remainder of the original argument vector # @class.method {Object "info info"} # # Lists the valid sub-methods selectors of the '''info''' method ensemble. # @class.method {Object "info method"} # # Returns varios definitional details of a method implementation, # identified by its method name. Examples include the method parameter # specification and the method body. # # @parameter infomethodsubcmd Specify the implementation # detail to retrieve (or the query to perform). One of # '''body''', '''definition''', # '''registrationhandle''', '''definitionhandle''', # '''handle''', '''origin''', '''parameter''', # '''parametersyntax''', '''type''', '''precondition''', # '''postcondition''', '''submethods''' # @parameter name The method name for which to look up # the selected detail # @class.method {Object "info vars"} # # Yields a list of variable names created and defined on the object. # # @parameter pattern A pattern string in the sense of # '''string match''' the resulting # variable names must match. # @class.method {Object "info methods"} # # Allows you to query the methods defined on the object. Note the # difference to <<@class.method "Object {info lookup methods}">> which # covers all methods actually callable upon the object. # # @parameter -callprotection Restrict to the methods of a specific # call protection level: '''public''', '''protected''', # '''private''', or '''all''' (the latter is the default). # @parameter -type Restrict the search by certain method # kinds: '''scripted''', '''builtin''', '''alias''', # '''forwarder''', '''object''', and '''setter'''. If # omitted, '''all''' method sorts are considered. # @parameter -path The pattern is expressed over the method paths, # rather than the method names. This allows for matching # <<@glspl ensemble>>. # @parameter pattern The pattern string in the style of '''string match''' # @class.method {Object require} # # An object can register additional structural and behavioral features # lazily, upon demand. To make features available for lazy # registration, use '''::nsf::method::provide'''. # # @sub-method namespace Attach a Tcl namespace to the object, # with the namespace becoming named # after the object. All object variables # become so available as # namespace-scoped variables. # @sub-method class # @sub-method public # @sub-method protected # @sub-method private # @class.method {Object "require method"} # # Attempts to register a method as identified by a name. The # registered method is subjected to default method call protection (in # NX, '''protected'''). # # @parameter methodName The name of the method requested. # @class.method {Object "require class method"} # # For a class object, attempts to register a method, as identified by # a name, for the scope of the object only; and not for the class. The # registered method is subjected to default method call protection (in # NX, '''protected'''). # # @parameter methodName The name of the class method requested. # @class.method {Object "require public method"} # # Attempts to register a method as identified by a name. The # registered method becomes '''public'''. # # @parameter methodName The name of the method requested. # @class.method {Object "require public class"} # @class.method {Object "require public class method"} # # Attempts to register a class method as identified by a name. The # registered class method becomes '''public'''. # # @parameter methodName The name of the class method requested. # @class.method {Object "require protected method"} # # Attempts to register a method as identified by a name. The # registered method becomes '''protected'''. # # @parameter methodName The name of the method requested. # @class.method {Object "require protected class"} # @class.method {Object "require protected class method"} # # Attempts to register a class method as identified by a name. The # registered class method becomes '''protected'''. # # @parameter methodName The name of the class method requested. # @class.method {Object "require private method"} # # Attempts to register a method as identified by a name. The # registered method becomes '''private'''. # # @parameter methodName The name of the method requested. # @class.method {Object "require private class"} # @class.method {Object "require private class method"} # # Attempts to register a class method as identified by a name. The # registered class method becomes '''private'''. # # @parameter methodName The name of the class method requested. # @class Slot # # A <<@gls slot>> is a meta-object that manages property changes of # objects. A property is either an attribute or a role taken by an # object in an inter-object relation (e.g., in system slots). The # predefined system slots are '''class''', '''superclass''', # '''mixin''', and '''filter'''. These slots appear as methods of # <<@class ::nx::Object>> or <<@class ::nx::Class>>. The slots # provide a common getter and setter interface. Every multivalued # slot provides e.g. a method '''add''' to append a value to the # list of values, and a method '''delete''' which removes it. # # @superclass ::nx::doc::entities::class::nx::Object # @class ObjectParameterSlot # # ... # # @superclass ::nx::doc::entities::class::nx::Slot # @class.property {Slot name:string} # # Name of the <<@gls slot>> which can be used to access the <<@gls # slot>> data from an object # @class.property {Slot multivalued} # # Boolean value for specifying single or multiple values (lists) # @class.property {Slot required} # # Denotes whether a value must be provided # @class.property {Slot default} # # Allows you to define a default value (to be set upon object creation) # @class.property {Slot type} # # You may specify a type constraint on the value range to managed by # the <<@gls slot>> # @class.property {ObjectParameterSlot name} # # Name of the <<@gls slot>> which can be used to access the <<@gls # slot>> data of an object. It defaults to unqualified name of an # instance. # @class.property {ObjectParameterSlot methodname} # # The name of the accessor methods to be registed on behalf of the # <<@gls slot>> object with its domains can vary from the slot name. # @class.property {ObjectParameterSlot domain} # # The domain (object or class) of a <<@gls slot>> on which it can be used # @class.property {ObjectParameterSlot defaultmethods} # # A list of two elements for specifying which methods are called per # default, when no slot method is explicitly specified in a call. # @class.property {ObjectParameterSlot manager} # # The manager object of the <<@gls slot>> (per default, the slot object takes # this role, i.e. '''[self]''') # @class.property {ObjectParameterSlot per-object} # # If set to '''true''', the accessor methods are registered with the # domain object scope only. It defaults to '''false'''. # @class.hook {Class objectparameter} # # An abstracted hook method which is primarily used from within the # object creation process, that is, the object configuration step # performed by <<@class.method {Object configure}>>. The actual # implementation of this hook is called to generate the object # parameter definition and so specifies the object parameter # processing for a given object under construction. For instance, the # <<@gls initcmd>> feature in <<@Gls nx>> is implemented this # way. By providing custom hook implementations (by overloading), # developers can define their own object parametrisation scheme. # @class VariableSlot # # VariableSlot <<@glspl slot>> are used to manage the access, mutation, # and querying of instance variables. One defines variable slots for # objects and classes usually via the helper method <<@class.method # "::nx::Object property">> The following example defines a class # with three variable slots. The property '''salary''' has a default # of '''0''', the property '''projects''' has the empty list as # default and is defined as multivalued and incremental. # ''' # Class create Person { # :property name # :property {salary:integer 0} # :property {projects:multivalued,incremental ""} # } # ''' # # @parameter incremental A boolean value, only useful for multivalued # slots. When set, one can add/delete incrementally values to the # multivalued set (e.g., through an incremental '''add''') # @parameter valuecmd A <<@acr tcl>> command to be executed whenever the managed # object variable is read # @parameter valuechangedcmd A <<@acr tcl>> command to be executed whenever the # value of the managed object variable changes # @parameter arg # @superclass ::nx::doc::entities::class::nx::ObjectParameterSlot # @glossary tcl # # @acronym Tcl # @pretty_name Tool Command Language # @glossary clos # # @pretty_name Common Lisp Object System # @acronym CLOS # @glossary flavors # # @pretty_name Flavors # @glossary nx # # The Next Scripting Language (NX) is one of the languages hosted by # and implemented on top of the Next Scripting Framework (NSF). # # @pretty_name Next Scripting Language # @acronym NX # @glossary objtype # # The type of an object is given by its signature interface. While <<@acr tcl>> # and so NSF object systems are mono-typed (i.e., everything has a # string representation to the interpreter), object-types are lately # checked and verified (e.g., upon method lookup). # # @pretty_name Object-type # @pretty_plural Object-types # @glossary objparam # # @pretty_name Object parameter # @pretty_plural Object parameters # @glossary ensemble # # An ensemble is an auxiliary object which acts as a single method of # another object. The ensemble's per-object methods (the so-called # ensemble methods), however, so appear as submethods of this # top-level method. This ressembles the ideas of subcommands and # namespace ensembles in <<@acr tcl>>. When sending a message to an # object, methods are identified as message receivers by name. This # name can be simple (i.e., a single <<@acr tcl>> word) or composite # (i.e., multiple <<@acr tcl>> words) in the case of # submethods. Submethods are identified by their composite method # names. # # @pretty_name Ensemble # @pretty_plural Ensembles # @glossary namepattern # # @pretty_name Name pattern # @pretty_plural Name patterns # @glossary guard # # A guard acts as ... # # @pretty_name Guard # @pretty_plural Guards # @glossary precedence # # ... # # @pretty_name Precedence order # @pretty_plural Precedence orders # @glossary slot # # ... # # @pretty_name Slot # @pretty_plural Slots # @glossary cim # # In Tcl/XOTcl/NSF, methods can either be scripted or implemented as a # C language extension ... # # @acronym CIM # @pretty_name C-implemented method # @pretty_plural C-implemented methods # @glossary initcmd # # ... # # @acronym initcmd # @pretty_name object initialization script # @pretty_plural object initialization scripts # @glossary filterspec # # ... # # @acronym filterspec # @pretty_name filter specification # @pretty_plural filter specification # @glossary mixinspec # # ... # # @acronym mixinspec # @pretty_name mixin specification # @pretty_plural mixin specification # @glossary property # # ... # # @acronym property # @pretty_name property # @pretty_plural properties # @object configure