Index: doc/next-tutorial.html =================================================================== diff -u -r457985fc87cb99f06989c8c5b4d415500e7d11d1 -r90ecfc116b3f569cea63dbce061a301497a5746b --- doc/next-tutorial.html (.../next-tutorial.html) (revision 457985fc87cb99f06989c8c5b4d415500e7d11d1) +++ doc/next-tutorial.html (.../next-tutorial.html) (revision 90ecfc116b3f569cea63dbce061a301497a5746b) @@ -2222,77 +2222,28 @@ incorrect. For all other purposes, the private methods are "invisible" in all situations, e.g. when mixins are used, or within the next-path, etc.

-

By using my -local for the invocaton it is possible to call just the +

By using my -local for the invocation it is possible to call just the local definition of the method. If we would call the method as usual, -the resoultion order would be the same as usual, starting with +the resolution order would be the same as usual, starting with filters, mixins, per-object methods and the full intrinsic class hierarchy.

-

3.4. Method Scopes

+

3.4. Applicability of Methods

+

As defined above, a method is a subroutine defined on an object or +class. This object (or class) contains the method. If the object (or +class) is deleted, the contained methods will be deleted as well.

3.4.1. Inherited Methods

-
-
-

3.4.2. Class Methods

-
-
-

3.4.3. Object Methods

-
-
-
-

3.5. Ensemble Methods

-

…

-
-
-

3.6. Parameters

-

NX provides a generalized mechanism for passing values to either -methods (we refer to these as method parameters) or to objects -(these are called object parameters). Both kind of parameters -might have different features, such as:

-
-

TODO: complete list above and provide a short summary of the section

-

Before we discuss method and object parameters in more detail, we -describe the parameter features in the subsequent sections based on -method parameters.

-
-

3.6.1. Positional and Non-Positional Parameters

-

If the position of a parameter in the list of formal arguments -(e.g. passed to a function) is significant for its meaning, this is a -positional parameter. If the meaning of the parameter is independent -of its postion, this is a non-positional parameter. When we call a -method with positional parameters, the meaning of the parameters (the -association with the argument in the argument list of the method) is -determined by its position. When we call a method with non-positional -parameters, their meaning is determined via a name passed with the -argument during invocation.

-
Listing 26: Positional and Non-Positional Method Parameters

+
+
+

Typically, methods are defined on a class and these methods are +applicable to the instances (direct or indirect) of this class. These +methods are inherited methods.

+
+

In the following example method foo is an inherited method defined +on class C.

+
Listing 26: Methods applicable for instances

-
  1
-  2
-  3
-  4
-  5
-  6
-  7
-  8
-  9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
-
nx::Object create o4 {
+constraints.
 
-  #
-  # Positional parameter with value constraints:
-  #
-  :public method foo {x:integer o:object,optional} {
-    puts "x=$x o? [info exists o]"
+[[xmp-value-check]]
+.Listing {counter:figure-number}: Method Parameters with Value Constraints
+{set:xmp-value-check:Listing {figure-number}}
+[source,tcl,numbers]
+--------------------------------------------------
+nx::Object create o4 {
+
+  #
+  # Positional parameter with value constraints:
+  #
+  :public method foo {x:integer o:object,optional} {
+    puts "x=$x o? [info exists o]"
   }
 
-  #
-  # Non-positional parameter with value constraints:
-  #
-  :public method bar {{-x:integer 10} {-verbose:boolean false}} {
-    puts "x=$x y=$y"
+  #
+  # Non-positional parameter with value constraints:
+  #
+  :public method bar {{-x:integer 10} {-verbose:boolean false}} {
+    puts "x=$x y=$y"
   }
 }
 
-# The following invocation raises an exception
-o4 foo a
-

Value contraints are specified as parameter options in the parameter -specifications. The parameter specification x:integer defines x as +# The following invocation raises an exception +o4 foo a +-------------------------------------------------- + +Value contraints are specified as parameter options in the parameter +specifications. The parameter specification +x:integer+ defines +x+ as a required positional parmeter which value is constraint to an -integer. The parameter specification o:object,optional shows how to -combine multiple parameter options. The parameter o is an optional +integer. The parameter specification +o:object,optional+ shows how to +combine multiple parameter options. The parameter +o+ is an optional positional parameter, its value must be an object (see -Listing 30). Value constraints are +<<xmp-value-check,{xmp-value-check}>>). Value constraints are specified exactly the same way for non-positional parameters (see -method bar in Listing 30).

-
Listing 31: Parameterized Value Constraints

-
-
-
  1
-  2
-  3
-  4
-  5
-  6
-  7
-  8
-  9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
-
#
-# Create classes for Person and Project
-#
-Class create Person
-Class create Project
+method +bar+ in <<xmp-value-check,{xmp-value-check}>>).
 
-nx::Object create o5 {
-  #
-  # Parameterized value constraints
-  #
-  :public method work {
+[[xmp-check-parameterized]]
+.Listing {counter:figure-number}: Parameterized Value Constraints
+{set:xmp-check-parameterized:Listing {figure-number}}
+[source,tcl,numbers]
+--------------------------------------------------
+#
+# Create classes for Person and Project
+#
+Class create Person
+Class create Project
+
+nx::Object create o5 {
+  #
+  # Parameterized value constraints
+  #
+  :public method work {
      -person:object,type=Person
      -project:object,type=Project
    } {
-    # ...
-  }
+    # ...
+  }
 }
 
-#
-# Create a Person and a Project instance
-#
-Person create gustaf
-Project create nx
+#
+# Create a Person and a Project instance
+#
+Person create gustaf
+Project create nx
 
-#
-# Use method with value constraints
-#
-o5 work -person gustaf -project nx
-

The native checkers object, class, metaclass and baseclass can -be further specialized with the parameter option type to restrict +# +# Use method with value constraints +# +o5 work -person gustaf -project nx +-------------------------------------------------- + +The native checkers +object+, +class+, +metaclass+ and +baseclass+ can +be further specialized with the parameter option +type+ to restrict the permissible values to instances of certain classes. We can use for -example the native value constraint object either for testing +example the native value constraint +object+ either for testing whether an argument is some object (without further constraints, as in -Listing 28, method foo), or we can +<<xmp-default-value, {xmp-default-value}>>, method +foo+), or we can constrain the value further to some type (direct or indirect instance -of a class). This is shown by method work in -Listing 31 which requires -the parameter -person to be an instance of class Person and the -parameter -project to be an instance of class Project.

-
-
-
Scripted Value Constraints
-

The set of predefined value checkers can be extended by application +of a class). This is shown by method +work+ in +<<xmp-check-parameterized, {xmp-check-parameterized}>> which requires +the parameter +-person+ to be an instance of class +Person+ and the +parameter +-project+ to be an instance of class +Project+. + +===== Scripted Value Constraints + +The set of predefined value checkers can be extended by application programs via defining methods following certain conventions. The user -defined value checkers are defined as methods of the class nx::Slot +defined value checkers are defined as methods of the class +nx::Slot+ or of one of its subclasses or instances. We will address such cases in the next sections. In the following example we define two new -value checkers on class nx::Slot. The first value checker is called -groupsize, the second one is called choice.

-
Listing 32: Scripted Value Checker for Method Parameters

-
-
-
  1
-  2
-  3
-  4
-  5
-  6
-  7
-  8
-  9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
-
#
-# Value checker named "groupsize"
-#
-::nx::Slot method type=groupsize {name value} {
-  if {$value < 1 || $value > 6} {
-    error "Value '$value' of parameter $name is not between 1 and 6"
+value checkers on class +nx::Slot+. The first value checker is called
++groupsize+, the second one is called +choice+.
+
+[[xmp-user-types]]
+.Listing {counter:figure-number}: Scripted Value Checker for Method Parameters
+{set:xmp-user-types:Listing {figure-number}}
+[source,tcl,numbers]
+--------------------------------------------------
+#
+# Value checker named "groupsize"
+#
+::nx::Slot method type=groupsize {name value} {
+  if {$value < 1 || $value > 6} {
+    error "Value '$value' of parameter $name is not between 1 and 6"
   }
 }
 
-#
-# Value checker named "choice" with extra argument
-#
-::nx::Slot method type=choice {name value arg} {
-  if {$value ni [split $arg |]} {
-    error "Value '$value' of parameter $name not in permissible values $arg"
+#
+# Value checker named "choice" with extra argument
+#
+::nx::Slot method type=choice {name value arg} {
+  if {$value ni [split $arg |]} {
+    error "Value '$value' of parameter $name not in permissible values $arg"
   }
 }
 
-#
-# Create an application class D
-# using the new value checkers
-#
-Class create D {
-  :public method foo {a:groupsize} {
-    # ...
-  }
-  :public method bar {a:choice,arg=red|yellow|green b:choice,arg=good|bad} {
-    # ...
-  }
+#
+# Create an application class D
+# using the new value checkers
+#
+Class create D {
+  :public method foo {a:groupsize} {
+    # ...
+  }
+  :public method bar {a:choice,arg=red|yellow|green b:choice,arg=good|bad} {
+    # ...
+  }
 }
 
-D create d1
+D create d1
 
-# testing "groupsize"
-d1 foo 2
+# testing "groupsize"
+d1 foo 2
 d1 foo 10
 
-# testing "choice"
-d1 bar green good
-d1 bar pink bad
-

In order to define a checker groupsize a method of the name -type=groupsize is defined. This method receives two arguments, -name and value. The first argument is the name of the parameter +# testing "choice" +d1 bar green good +d1 bar pink bad +-------------------------------------------------- + +In order to define a checker +groupsize+ a method of the name ++type=groupsize+ is defined. This method receives two arguments, ++name+ and +value+. The first argument is the name of the parameter (mostly used for the error message) and the second parameter is provided value. The value checker simply tests whether the provided value is between 1 and 3 and raises an exception if this is not the -case (invocation in line 36 in Listing 32).

-

The checker groupsize has the permissible values defined in its -method’s body. It is as well possible to define more generic checkers +case (invocation in line 36 in <<xmp-user-types, {xmp-user-types}>>). + +The checker +groupsize+ has the permissible values defined in its +method's body. It is as well possible to define more generic checkers that can be parameterized. For this parameterization, one can pass an -argument to the checker method (last argument). The checker choice +argument to the checker method (last argument). The checker +choice+ can be used for restricting the values to a set of predefined constants. This set is defined in the parameter specification. The -parameter a of method bar in Listing 32 -is restricted to the values red, yellow or green, and the -parameter b is restricted to good or bad. Note that the syntax +parameter +a+ of method +bar+ in <<xmp-user-types, {xmp-user-types}>> +is restricted to the values +red+, +yellow+ or +green+, and the +parameter +b+ is restricted to +good+ or +bad+. Note that the syntax of the permissible values is solely defined by the definition of the value checker in lines 13 to 17. The invocation in line 39 will be ok, -the invocation in line 40 will raise an exception, since pink is not -allowed.

-

If the same checks are used in many places in the program, +the invocation in line 40 will raise an exception, since +pink+ is not +allowed. + +If the same checks are used in many places in the program, defining names for the value checker will be the better choice since it improves maintainability. For seldomly used kind of checks, the -parameterized value checkers might be more convenient.

-
-
-
-

3.6.5. Multiplicity

-
-
-

Multiplicity is used to define whether a parameter should receive -single or multiple values.

-
-

A multiplicity specification has a lower and an upper bound. A lower -bound of 0 means that the value might be empty. A lower bound of 1 +parameterized value checkers might be more convenient. + +==== Multiplicity + +***************************************************************************** +*Multiplicity* is used to define whether a parameter should receive +single or multiple values. +***************************************************************************** + +A multiplicity specification has a lower and an upper bound. A lower +bound of +0+ means that the value might be empty. A lower bound of +1+ means that the the parameter needs at least one value. The upper bound -might be 1 or n (or synonymously *). While the upper bound of -1 states that at most one value has to be passed, the upper bound of -n says that multiple values are permitted. Other kinds of -multiplicity are currently not allowed.

-

The multiplicity is written as parameter option in the parameter -specification in the form lower-bound..upper-bound. If no -multiplicity is defined the default multiplicity is 1..1, which +might be +1+ or +n+ (or synonymously +*+). While the upper bound of ++1+ states that at most one value has to be passed, the upper bound of ++n+ says that multiple values are permitted. Other kinds of +multiplicity are currently not allowed. + +The multiplicity is written as parameter option in the parameter +specification in the form _lower-bound_.._upper-bound_. If no +multiplicity is defined the default multiplicity is +1..1+, which means: provide exactly one (atomic) value (this was the case in the -previous examples).

-
Listing 33: Method Parameters with Explicit Multiplicity

-
-
-
  1
-  2
-  3
-  4
-  5
-  6
-  7
-  8
-  9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
-
nx::Object create o6 {
+previous examples).
 
-  #
-  # Positional parameter with an possibly empty
-  # single value
-  #
-  :public method foo {x:integer,0..1} {
-    puts "x=$x"
+[[xmp-multiplicity]]
+.Listing {counter:figure-number}: Method Parameters with Explicit Multiplicity
+{set:xmp-multiplicity:Listing {figure-number}}
+[source,tcl,numbers]
+--------------------------------------------------
+nx::Object create o6 {
+
+  #
+  # Positional parameter with an possibly empty
+  # single value
+  #
+  :public method foo {x:integer,0..1} {
+    puts "x=$x"
   }
 
-  #
-  # Positional parameter with an possibly empty
-  # list of values value
-  #
-  :public method bar {x:integer,0..n} {
-    puts "x=$x"
+  #
+  # Positional parameter with an possibly empty
+  # list of values value
+  #
+  :public method bar {x:integer,0..n} {
+    puts "x=$x"
   }
 
-  #
-  # Positional parameter with a non-empty
-  # list of values
-  #
-  :public method baz {x:integer,1..n} {
-    puts "x=$x"
+  #
+  # Positional parameter with a non-empty
+  # list of values
+  #
+  :public method baz {x:integer,1..n} {
+    puts "x=$x"
   }
-}
-

Listing 33 contains three examples for +} +-------------------------------------------------- + +<<xmp-multiplicity, {xmp-multiplicity}>> contains three examples for positional parameters with different multiplicities. Multiplicity is often combined with value constraints. A parameter specification of -the form x:integer,0..n means that the parameter x receives a list +the form +x:integer,0..n+ means that the parameter +x+ receives a list of integers, which might be empty. Note that the value constraints are -applied to every single element of the list.

-

The parameter specification x:integer,0..1 means that x might be +applied to every single element of the list. + +The parameter specification +x:integer,0..1+ means that +x+ might be an integer or it might be empty. This is one style of specifying that no explicit value is passed for a certain parameter. Another style is to use required or optional parameters. NX does not enforce any -particular style for handling unspecified values.

-

All the examples in Listing 33 are for +particular style for handling unspecified values. + +All the examples in <<xmp-multiplicity, {xmp-multiplicity}>> are for single positional parameters. Certainly, multiplicity is fully orthogonal with the other parameter features and can be used as well for multiple parameters, non-positional parameter, default values, -etc.

-
- - - -
-

4. Advanced Language Features

-
-

…

-
-

4.1. Objects, Classes and Meta-Classes

-

…

-
-
-

4.2. Resolution Order and Next-Path

-

…

-
-
-

4.3. Details on Method and Object Parameters

-

The parameter specifications are used in NX for the following -purposes. They are used for

-
    -
  • -

    -the specification of input arguments of methods and commands, for -

    -
    • -
  • -

    -the specification of return values of methods and commands, and for -

    -
    • -
  • -

    -the specification for the initialization of objects. -

    -
    • -
-

We refer to the first two as method parameters and the last one as +etc. + +== Advanced Language Features + +... + +=== Objects, Classes and Meta-Classes + +... + +=== Resolution Order and Next-Path + +... + +=== Details on Method and Object Parameters + +The parameter specifications are used in NX for the following +purposes. They are used for + +- the specification of input arguments of methods and commands, for +- the specification of return values of methods and commands, and for +- the specification for the initialization of objects. + +We refer to the first two as method parameters and the last one as object parameters. The examples in the previous sections all parameter -specification were specifications of method parameters.

-
-
-

Method parameters specify properties about permissible values passed -to methods.

-
-

The method parameter specify how methods are invoked, how the +specification were specifications of method parameters. + +***************************************************************************** +*Method parameters* specify properties about permissible values passed +to methods. +***************************************************************************** + +The method parameter specify how methods are invoked, how the actual arguments are passed to local variables of the invoked method -and what kind of checks should be performed on these.

-
-
-

Object parameters are parameters that specify, with what values +and what kind of checks should be performed on these. + +***************************************************************************** +*Object parameters* are parameters that specify, with what values instance variables of objects are initialized and how these objects -could be parameterized.

-
-

Syntactically, object parameters and method parameters are the same, +could be parameterized. +***************************************************************************** + +Syntactically, object parameters and method parameters are the same, although there are certain differences (e.g. some parameter options are only applicable for objects parameters, the list of object parameters is computed dynamically from the class structures, object parameters are often used in combination with special setter methods, etc.). Consider the following example, where we define the two -application classes Person and Student with a few properties.

-
Listing 34: Object Parameters

-
-
-
  1
-  2
-  3
-  4
-  5
-  6
-  7
-  8
-  9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
-
#
-# Define a class Person with properties "name"
-# and "birthday"
-#
-nx::Class create Person {
-  :property name:required
-  :property birthday
+application classes +Person+ and +Student+ with a few properties.
+
+[[xmp-object-parameters]]
+.Listing {counter:figure-number}: Object Parameters
+{set:xmp-object-parameters:Listing {figure-number}}
+[source,tcl,numbers]
+--------------------------------------------------
+#
+# Define a class Person with properties "name"
+# and "birthday"
+#
+nx::Class create Person {
+  :property name:required
+  :property birthday
 }
 
-#
-# Define a class Student as specialization of Person
-# with and additional property
-#
-nx::Class create Student -superclass Person {
-  :property matnr:required
-  :property {oncampus:boolean true}
+#
+# Define a class Student as specialization of Person
+# with and additional property
+#
+nx::Class create Student -superclass Person {
+  :property matnr:required
+  :property {oncampus:boolean true}
 }
 
-#
-# Create instances using object parameters
-# for the initialization
-#
-Person create p1 -name Bob
-Student create s1 -name Susan -matnr 4711
+#
+# Create instances using object parameters
+# for the initialization
+#
+Person create p1 -name Bob
+Student create s1 -name Susan -matnr 4711
 
-# Access property value via accessor method
-puts "The name of s1 is [s1 name]"
-

The class Person has two properties name and birthday, where the -property name is required, the property birthday is not. The -class Student is a subclass of Person with the additional required -property matnr and an optional property oncampus with the -default value true (see Listing 34). The class diagram below visualizes these -definitions.

-
-
-object-parameter.png -
-
Figure 35. System and Application Classes
-
-

-

In NX, these definitions imply that instances of the class of Person -have the properties name and birthday as non-positional object -parameters. Furthermore it implies that instances of Student will -have the object parameters of Person augmented with the object -parameters from Student (namely matnr and oncampus). Based on -these object parameters, we can create a Person named Bob and a -Student named Susan with the matriculation number 4711 (see line -23 and 24 in Listing 34). After the object s1 is created it has the -instance variables name, matnr and oncampus (the latter is -initialized with the default value).

-
-

4.3.1. Object Parameters for all NX Objects

-

The object parameters are not limited to the application defined +# Access property value via accessor method +puts "The name of s1 is [s1 name]" +-------------------------------------------------- + +The class +Person+ has two properties +name+ and +birthday+, where the +property +name+ is required, the property +birthday+ is not. The +class +Student+ is a subclass of +Person+ with the additional required +property +matnr+ and an optional property +oncampus+ with the +default value +true+ (see <<xmp-object-parameters, +{xmp-object-parameters}>>). The class diagram below visualizes these +definitions. + +[[img-object-parameters]] +image::object-parameter.png[align="center",title="System and Application Classes"] +{set:img-object-parameters:Figure {figure-number}} + +In NX, these definitions imply that instances of the class of +Person+ +have the properties +name+ and +birthday+ as _non-positional object +parameters_. Furthermore it implies that instances of +Student+ will +have the object parameters of +Person+ augmented with the object +parameters from +Student+ (namely +matnr+ and +oncampus+). Based on +these object parameters, we can create a +Person+ named +Bob+ and a ++Student+ named +Susan+ with the matriculation number +4711+ (see line +23 and 24 in <<xmp-object-parameters, +{xmp-object-parameters}>>). After the object +s1+ is created it has the +instance variables +name+, +matnr+ and +oncampus+ (the latter is +initialized with the default value). + +==== Object Parameters for all NX Objects + +The object parameters are not limited to the application defined properties, also NX provides some predefined definitions. Since -Person is a subclass of nx::Object also the object parameters of -nx::Object are inherited. In the introductory stack example, we used --mixin applied to an object to denote per-object mixins (see -Listing 8). Since mixin -is defined as a parameter on nx::Object it can be used as an object -parameter -mixin for all objects in NX. To put it in other words, ++Person+ is a subclass of +nx::Object+ also the object parameters of ++nx::Object+ are inherited. In the introductory stack example, we used ++-mixin+ applied to an object to denote per-object mixins (see +<<xmp-using-class-safety, {xmp-using-class-safety}>>). Since +mixin+ +is defined as a parameter on +nx::Object+ it can be used as an object +parameter +-mixin+ for all objects in NX. To put it in other words, every object can be configured to have per-object mixins. If we would -remove this definition, this feature would be removed as well.

-

As shown in the introductory examples, every object can be configured +remove this definition, this feature would be removed as well. + +As shown in the introductory examples, every object can be configured via a scripted initialization block (the optional scripted block specified at object creation as last argument; see -Listing 5 or -Listing 12). The +<<xmp-object-stack, {xmp-object-stack}>> or +<<xmp-object-integer-stack, {xmp-object-integer-stack}>>). The scripted block and its meaning are as well defined by the means of object parameters. However, this object parameter is positional (last argument) and optional (it can be omitted). The following listing shows -(simplified) the object parameters of Person p1 and Student s1.

-
Listing 36: Computed Actual Object Parameter (simplified)

-
-
-
  1
-  2
-  3
-  4
-  5
-  6
-  7
-  8
-
Object parameter for Person p1:
+(simplified) the object parameters of +Person p1+ and +Student s1+.
+
+[[xmp-object-parameter-list]]
+.Listing {counter:figure-number}: Computed Actual Object Parameter (simplified)
+{set:xmp-object-parameter-list:Listing {figure-number}}
+[source,tcl,numbers]
+--------------------------------------------------
+Object parameter for Person p1:
    -name:required -birthday ...
-   -mixin:mixinreg,alias,1..n -filter:filterreg,alias,1..n _:initcmd,optional
+   -mixin:mixinreg,alias,1..n -filter:filterreg,alias,1..n _:initcmd,optional
 
-Object parameter for Student s1:
+Object parameter for Student s1:
    -matnr:required {-oncampus:boolean true}
    -name:required -birthday ...
-   -mixin:mixinreg,alias,1..n -filter:filterreg,alias,1..n _:initcmd,optional
-

The actual values can be optained via introspection via Person info -parameter definition. The object parameter types mixinreg and -filterreg are for converting definitions of filters and mixins. The -object parameter type initcmd says that the content of this variable + -mixin:mixinreg,alias,1..n -filter:filterreg,alias,1..n _:initcmd,optional +-------------------------------------------------- + +The actual values can be optained via introspection via +Person info +parameter definition+. The object parameter types +mixinreg+ and ++filterreg+ are for converting definitions of filters and mixins. The +object parameter type +initcmd+ says that the content of this variable will be executed in the context of the object being created (before -the constructor init is called). More about the object parameter -types later.

-
-
-

4.3.2. Object Parameters for all NX Classes

-

Since classes are certain kind of objects, classes are parameterized +the constructor +init+ is called). More about the object parameter +types later. + +==== Object Parameters for all NX Classes + +Since classes are certain kind of objects, classes are parameterized in the same way as objects. A typical parameter for a class definition is the relation of the class to its superclass.In our example, we have -specified, that Student has Person as superclass via the -non-positional object parameter -superclass. If no superclass is +specified, that +Student+ has +Person+ as superclass via the +non-positional object parameter +-superclass+. If no superclass is specified for a class, the default superclass is -nx::Object. Therefore nx::Object is the default value for the -parameter superclass.

-

Another frequently used parameter for classes is -mixin to denote ++nx::Object+. Therefore +nx::Object+ is the default value for the +parameter +superclass+. + +Another frequently used parameter for classes is +-mixin+ to denote per-class mixins (see e.g. the introductory Stack example in -Listing 10), which is defined in -the same way.

-

Since Student is an instance of the meta-class nx::Class it -inherits the object parameters from nx::Class (see class diagram -Figure 35). Therefore, one can -use e.g. -superclass in the definition of classes.

-

Since nx::Class is a subclass of nx::Object, the meta-class -nx::Class inherits the parameter definitions from the most general -class nx::Object. Therefore, every class might as well be configured +<<xmp-class-safestack,{xmp-class-safestack}>>), which is defined in +the same way. + +Since +Student+ is an instance of the meta-class +nx::Class+ it +inherits the object parameters from +nx::Class+ (see class diagram +<<img-object-parameters,{img-object-parameters}>>). Therefore, one can +use e.g. +-superclass+ in the definition of classes. + +Since +nx::Class+ is a subclass of +nx::Object+, the meta-class ++nx::Class+ inherits the parameter definitions from the most general +class +nx::Object+. Therefore, every class might as well be configured with a scripted initialization block the same way as objects can be configured. We used actually this scripted initialization block in most examples for defining the methods of the class. The following -listing shows (simplified) the parameters applicable for Class -Student.

-
Listing 37: Computed Parameters for a Class (simplified)

-
-
-
  1
-  2
-  3
-
Object parameter for Class Student:
-   -mixin:mixinreg,alias,1..n -filter:filterreg,alias,1..n ...
-   {-superclass:class,alias,1..n ::nx::Object} ...
-

The actual values can be obtained via introspection via nx::Class info -parameter definition.

-
-
-

4.3.3. User defined Parameter Types

-

More detailed definition of the object parameter types comes here.

-
-
-

4.3.4. Slot Classes and Slot Objects

-

In one of the previous sections, we defined scripted (application -defined) checker methods on a class named nx::Slot. In general NX +listing shows (simplified) the parameters applicable for +Class +Student+. + +[[xmp-class-parameter-list]] +.Listing {counter:figure-number}: Computed Parameters for a Class (simplified) +{set:xmp-class-parameter-list:Listing {figure-number}} +[source,tcl,numbers] +-------------------------------------------------- +Object parameter for Class Student: + -mixin:mixinreg,alias,1..n -filter:filterreg,alias,1..n ... + {-superclass:class,alias,1..n ::nx::Object} ... +-------------------------------------------------- + +The actual values can be obtained via introspection via +nx::Class info +parameter definition+. + + +==== User defined Parameter Types + +More detailed definition of the object parameter types comes here. + +==== Slot Classes and Slot Objects + +In one of the previous sections, we defined scripted (application +defined) checker methods on a class named +nx::Slot+. In general NX offers the possibility to define value checkers not only for all usages of parameters but as well differently for method parameters or -object parameters

-
-
-slots.png -
-
Figure 38. Slot Classes and Objects
-
-

-
-
-

4.3.5. Attribute Slots

-

Still Missing

-
    -
  • -

    -return value checking -

    -
    • -
  • -

    -switch -

    -
    • -
  • -

    -initcmd … -

    -
    • -
  • -

    -subst rules -

    -
    • -
  • -

    -converter -

    -
    • -
  • -

    -incremental slots -

    -
    • -
-
-
-
-
-
-

5. Miscellaneous

-
-
-

5.1. Profiling

-
-
-

5.2. Unknown Handlers

-

NX provides two kinds of unknown handlers:

-
    -
  • -

    -Unknown handlers for methods -

    -
    • -
  • -

    -Unknown handlers for objects and classes -

    -
    • -
-
-

5.2.1. Unknown Handlers for Methods

-

Object and classes might be equipped -with a method unknown which is called in cases, where an unknown +object parameters + +[[img-slots]] +image::slots.png[align="center",title="Slot Classes and Objects"] +{set:img-slots:Figure {figure-number}} + + +==== Attribute Slots + + +Still Missing + +- return value checking +- switch +- initcmd ... +- subst rules +- converter +- incremental slots + +== Miscellaneous + +=== Profiling + +=== Unknown Handlers + +NX provides two kinds of unknown handlers: + +- Unknown handlers for methods +- Unknown handlers for objects and classes + +==== Unknown Handlers for Methods + +Object and classes might be equipped +with a method +unknown+ which is called in cases, where an unknown method is called. The method unknown receives as first argument the -called method followed by the provided arguments

-
Listing 39: Unknown Method Handler

-
-
-
  1
-  2
-  3
-  4
-  5
-  6
-  7
-  8
-  9
- 10
-
::nx::Object create o {
-  :method unknown {called_method args} {
-    puts "Unknown method '$called_method' called"
+called method followed by the provided arguments
+
+[[xmp-unknown-method]]
+.Listing {counter:figure-number}: Unknown Method Handler
+{set:xmp-unknown-method:Listing {figure-number}}
+[source,tcl,numbers]
+--------------------------------------------------
+::nx::Object create o {
+  :method unknown {called_method args} {
+    puts "Unknown method '$called_method' called"
   }
 }
 
-# Invoke an unknown method for object o:
-o foo 1 2 3
+# Invoke an unknown method for object o:
+o foo 1 2 3
 
-# Output will be: "Unknown method 'foo' called"
-

Without any provision of an unknown method handler, an error will be -raised, when an unknown method is called.

-
-
-

5.2.2. Unknown Handlers for Objects and Classes

-

The next scripting framework provides in addition to unknown method +# Output will be: "Unknown method 'foo' called" +-------------------------------------------------- + +Without any provision of an unknown method handler, an error will be +raised, when an unknown method is called. + +==== Unknown Handlers for Objects and Classes + +The next scripting framework provides in addition to unknown method handlers also a means to dynamically create objects and classes, when these are referenced. This happens e.g. when superclasses, mixins, or parent objects are referenced. This mechanism can be used to implement e.g. lazy loading of these classes. Nsf allows to register multiple unknown handlers, each identified by a key (a unique name, different -from the keys of other unknown handlers).

-
Listing 40: Unknown Class Handler

-
-
-
  1
-  2
-  3
-  4
-  5
-  6
-  7
-  8
-  9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
-
::nx::Class public class method __unknown {name} {
-  # A very simple unknown handler, showing just how
-  # the mechanism works.
-  puts "***** __unknown called with <$name>"
-  ::nx::Class create $name
+from the keys of other unknown handlers).
+
+[[xmp-unknown-class]]
+.Listing {counter:figure-number}: Unknown Class Handler
+{set:xmp-unknown-class:Listing {figure-number}}
+[source,tcl,numbers]
+--------------------------------------------------
+::nx::Class public class method __unknown {name} {
+  # A very simple unknown handler, showing just how
+  # the mechanism works.
+  puts "***** __unknown called with <$name>"
+  ::nx::Class create $name
 }
 
-# Register an unknown handler as a method of ::nx::Class
-::nsf::object::unknown::add nx {::nx::Class __unknown}
+# Register an unknown handler as a method of ::nx::Class
+::nsf::object::unknown::add nx {::nx::Class __unknown}
 
-::nx::Object create o {
-  # The class M is unknown at this point
-
-  :mixin add M
-  # The line above has triggered the unknown class handler,
-  # class M is now defined
-
-  puts [:info mixin classes]
-  # The output will be:
-  #     ***** __unknown called with <::M>
-  #     ::M
-}
-

The Next Scripting Framework allows to add, query, delete and list unknown handlers.

-
Listing 41: Unknown Handler registration

-
-
-
  1
-  2
-  3
-  4
-  5
-
# Interface for unknown handlers:
-# nsf::object::unknown::add /key/ /handler/
-# nsf::object::unknown::get /key/
-# nsf::object::unknown::delete /key/
-# nsf::object::unknown::keys
-
References
    -
  • -

    - U. Zdun, M. Strembeck, G. Neumann: +::nx::Object create o { + # The class M is unknown at this point + + :mixin add M + # The line above has triggered the unknown class handler, + # class M is now defined + + puts [:info mixin classes] + # The output will be: + # ***** __unknown called with <::M> + # ::M +} +-------------------------------------------------- + +The Next Scripting Framework allows to add, query, delete and list unknown handlers. + +[[xmp-unknown-registgration]] +.Listing {counter:figure-number}: Unknown Handler registration +{set:xmp-unknown-registgration:Listing {figure-number}} +[source,tcl,numbers] +-------------------------------------------------- +# Interface for unknown handlers: +# nsf::object::unknown::add /key/ /handler/ +# nsf::object::unknown::get /key/ +# nsf::object::unknown::delete /key/ +# nsf::object::unknown::keys +-------------------------------------------------- + + +[bibliography] +.References + +- [[Zdun, Strembeck, Neumann 2007]] U. Zdun, M. Strembeck, G. Neumann: Object-Based and Class-Based Composition of Transitive Mixins, Information and Software Technology, 49(8) 2007 . -

    -
    • -
  • -

    - G. Neumann and U. Zdun: Filters as a + +- [[Neumann and Zdun 1999a]] G. Neumann and U. Zdun: Filters as a language support for design patterns in object-oriented scripting - languages. In Proceedings of COOTS’99, 5th Conference on + languages. In Proceedings of COOTS'99, 5th Conference on Object-Oriented Technologies and Systems, San Diego, May 1999. -

    -
    • -
  • -

    - G. Neumann and U. Zdun: Implementing + +- [[Neumann and Zdun 1999b]] G. Neumann and U. Zdun: Implementing object-specific design patterns using per-object mixins. In Proc. of NOSA`99, Second Nordic Workshop on Software Architecture, Ronneby, Sweden, August 1999. -

    -
    • -
  • -

    - G. Neumann and U. Zdun: Enhancing + +- [[Neumann and Zdun 1999c]] G. Neumann and U. Zdun: Enhancing object-based system composition through per-object mixins. In Proceedings of Asia-Pacific Software Engineering Conference (APSEC), Takamatsu, Japan, December 1999. -

    -
    • -
  • -

    - G. Neumann and U. Zdun: XOTCL, an + +- [[Neumann and Zdun 2000a]] G. Neumann and U. Zdun: XOTCL, an object-oriented scripting language. In Proceedings of Tcl2k: The 7th USENIX Tcl/Tk Conference, Austin, Texas, February 2000. -

    -
    • -
  • -

    - G. Neumann and U. Zdun: Towards the Usage + +- [[Neumann and Zdun 2000b]] G. Neumann and U. Zdun: Towards the Usage of Dynamic Object Aggregations as a Form of Composition In: - Proceedings of Symposium of Applied Computing (SAC’00), Como, + Proceedings of Symposium of Applied Computing (SAC'00), Como, Italy, Mar 19-21, 2000. -

    -
    • -
  • -

    - G. Neumann, S. Sobernig: XOTcl 2.0 - A + +- [[Neumann and Sobernig 2009]] G. Neumann, S. Sobernig: XOTcl 2.0 - A Ten-Year Retrospective and Outlook, in: Proceedings of the Sixteenth Annual Tcl/Tk Conference, Portland, Oregon, October, 2009. -

    -
    • -
  • -

    - J. K. Ousterhout: Tcl: An embeddable command + +- [[Ousterhout 1990]] J. K. Ousterhout: Tcl: An embeddable command language. In Proc. of the 1990 Winter USENIX Conference, January 1990. -

    -
    • -
  • -

    - J. K. Ousterhout: Scripting: Higher Level + +- [[Ousterhout 1998]] J. K. Ousterhout: Scripting: Higher Level Programming for the 21st Century, IEEE Computer 31(3), March 1998. -

    -
    • -
  • -

    - D. Wetherall and C. J. Lindblad: Extending Tcl for + +- [[Wetherall and Lindblad 1995]] D. Wetherall and C. J. Lindblad: Extending Tcl for Dynamic Object-Oriented Programming. Proc. of the Tcl/Tk Workshop '95, - July 1995. -

    -
    • -
+ July 1995. +
-
Index: doc/next-tutorial.txt =================================================================== diff -u -r457985fc87cb99f06989c8c5b4d415500e7d11d1 -r90ecfc116b3f569cea63dbce061a301497a5746b --- doc/next-tutorial.txt (.../next-tutorial.txt) (revision 457985fc87cb99f06989c8c5b4d415500e7d11d1) +++ doc/next-tutorial.txt (.../next-tutorial.txt) (revision 90ecfc116b3f569cea63dbce061a301497a5746b) @@ -807,7 +807,7 @@ =========================================== *Methods* are subroutines (pieces of code) associated with objects and/or classes. Every method has a name, it receives arguments and -returns a value. +returns a value. =========================================== There are as well other program units, which are not associated with @@ -1107,21 +1107,130 @@ in all situations, e.g. when mixins are used, or within the +next+-path, etc. -By using +my -local+ for the invocaton it is possible to call just the +By using +my -local+ for the invocation it is possible to call just the local definition of the method. If we would call the method as usual, -the resoultion order would be the same as usual, starting with +the resolution order would be the same as usual, starting with filters, mixins, per-object methods and the full intrinsic class hierarchy. -=== Method Scopes +=== Applicability of Methods + +As defined above, a method is a subroutine defined on an object or +class. This object (or class) contains the method. If the object (or +class) is deleted, the contained methods will be deleted as well. + ==== Inherited Methods -==== Class Methods + +=========================================== +Typically, methods are defined on a class and these methods are +applicable to the instances (direct or indirect) of this class. These +methods are *inherited methods*. +=========================================== + +In the following example method +foo+ is an inherited method defined +on class +C+. + +[[xmp-instance-applicable]] +.Listing {counter:figure-number}: Methods applicable for instances +{set:xmp-instance-applicable:Listing {figure-number}} +[source,tcl,numbers] +-------------------------------------------------- +nx::Class create C { + :public method foo {} {return 1} + :create c1 +} + +# Method "foo" is defined on class "C" +# and applicable to the instances of "C" +c1 foo +-------------------------------------------------- + +There are many programming languages that allow only this type of methods. +However, NX allows as well to define methods on objects. + ==== Object Methods +=========================================== +Methods contained in objects are *per-object methods*, which are only +applicable on the object, on which they are defined. +=========================================== + +The following example defines a object specific method +bar+ on the +instance +c1+ of class +C+, and as well the object specific method ++baz+ defined on the object +o1+. Note that we can define a per-object +method that shadows (redefines) for this object an inherited method. + +[[xmp-object-applicable1]] +.Listing {counter:figure-number}: Per-object Method +{set:xmp-object-applicable1:Listing {figure-number}} +[source,tcl,numbers] +-------------------------------------------------- +nx::Class create C { + :public method foo {} {return 1} + :create c1 { + :public method foo {} {return 2} + :public method bar {} {return 3} + } +} + +# Method "bar" is on object specific method of "c1" +c1 bar + +# object-specific method "foo" returns 2 +c1 foo + +# Method "baz" is on object specific method of "o1" +nx::Object create o1 { + :public method baz {} {return 4} +} +o1 baz +-------------------------------------------------- + +==== Class Methods + +========================================= +A *class method* is a method defined on a class, which is only +applicable to the class itself. +========================================= + +In NX, all classes are objects as well. Classes are certainly special +kind of objects, that have the ability to e.g. create instances and to +provide methods to the instances. Classes manage their instances. + +[[xmp-object-applicable2]] +.Listing {counter:figure-number}: Per-object Method +{set:xmp-object-applicable2:Listing {figure-number}} +[source,tcl,numbers] +-------------------------------------------------- +nx::Class create C { + :public class method bar {} {return 2} + :public method foo {} {return 1} + :create c1 +} + +# Method "bar" is a class method of class "C" +C bar + +# Method "foo" is an inherited method of "C" +c1 foo + +# When trying to invoke the class method on the +# instance, an error will be raised. +c1 bar +-------------------------------------------------- + +In several other object oriented programming languages, class methods +are called "static methods". + + === Ensemble Methods ... +=== Method Resolution + +.... + === Parameters NX provides a generalized mechanism for passing values to either