# -*- 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	-methodtype	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 definition"}
#
# 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	-methodtype	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	-methodtype	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	-methodtype	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