In our first example, we define a class named Stack with the methods push and pop. When an instance of the stack is created (e.g. a concrete stack s1) the stack will contain an instance variable named things, initialized with the an empty list.

Typically, classes are defined in NX via nx::Class create, followed by the name of the new class (here: Stack). The definition of the stack placed between curly braces and contains here just the method definitions. Methods of the class are defined via :method followed by the name of the method, an argument list and the body of the method, consisting of Tcl and NX statements.

When an instance of Stack is created, it will contain an instance variable named things. If several Stack instances are created, each of the instances will have their own (same-named but different) instance variable. The instance variable things is used in our example as a list for the internal representation of the stack. We define in a next step the methods to access and modify this list structure. A user of the stack using the provided methods does not have to have any knowledge about the name or the structure of the internal representation (the instance variable things).

The method push receives an argument thing which should be placed on the stack. Note that we do not have to specify the type of the element on the stack, so we can push strings as well as numbers or other kind of things. When an element is pushed, we add this element as the first element to the list things. We insert the element using the Tcl command linsert which receives the list as first element, the position where the element should be added as second and the new element as third argument. To access the value of the instance variable we use Tcl’s dollar operator followed by the name. The names of instance variables are preceded with a colon :. Since the name contains a non-plain character, Tcl requires us to put braces around the name. The command linsert and its arguments are placed between square brackets. This means that the function linsert is called and a new list is returned, where the new element is inserted at the first position (index 0) in the list things. The result of the linsert function is assigned again to the instance variable things, which is updated this way. Finally the method push returns the pushed thing using the return statement.

The method pop returns the most recently stacked element and removes it from the stack. Therefore, it takes the first element from the list (using the Tcl command lindex), assigns it to the method-scoped variable top, removes the element from the instance variable things (by using the Tcl command lrange) and returns the value popped element top.

This finishes our first implementation of the stack, more enhanced versions will follow. Note that the methods push and pop are defined as public; this means that these methods can be used from all other objects in the system. Therefore, these methods provide an interface to the stack implementation.

Now we want to use the stack. The code snippet in Listing 3 shows how to use the class Stack in a script. Since NX is based on Tcl, the script will be called with the Tcl shell tclsh. In the Tcl shell we have to require package nx to use the Next Scripting Framework and NX. The next lines contain the definition of the stack as presented before. Of course, it is as well possible to make the definition of the stack an own package, such we could simple say package require stack, or to save the definition of a stack simply in a file and load it via source.

In line 12 we create an instance of the stack, namely the stack object s1. The object s1 is an instance of Stack and has therefore access to its methods. The methods like push or pop can be invoked via a command starting with the object name followed by the method name. In lines 13-15 we push on the stack the values a, then b, and c. In line 16 we output the result of the pop method using the Tcl command puts. We will see on standard output the value+c+ (the last stacked item). The output of the line 17 is the value b (the previously stacked item). Finally, in line 18 we destroy the object. This is not necessary here, but shows the life cycle of an object. In some respects, destroy is the counterpart of create from line 12.

Figure 4 shows the actual class and object structure of the first Stack example. Note that the common root class is nx::Object that contains methods for all objects. Since classes are as well objects in NX, nx::Class is a specialization of nx::Object. nx::Class provides methods for creating objects, such as the method create which is used to create objects (and classes as well).

The definition of the stack in Listing 2 follows the traditional object oriented approach, found in practically every object oriented programming language: Define a class with some methods, create instances from this class, and use the methods defined in the class in the instances of the class.

In our next example, we introduce generic objects and object specific methods. With NX, we can define generic objects, which are instances of the most generic class nx::Object (sometimes called common root class). nx::Object is predefined and contains a minimal set of methods applicable to all NX objects. In this example, we define a generic object named stack and provide methods for this object. The methods defined above were methods provided by a class for objects. Now we define object specific methods, which are methods applicable only to the object for which they are defined.

The example in Listing 5 defines the object stack in a very similar way as the class Stack. But the following points are different.

In order to use the stack, we can use directly the object stack in the same way as we have used the object s1 in Listing 3 the class diagram for this the object stack.

A reader might wonder when to use a class Stack or rather an object stack. A big difference is certainly that one can define easily multiple instances of a class, while the object is actually a single, tailored entity. The concept of the object stack is similar to a module, providing a certain functionality via a common interface, without providing the functionality to create multiple instances. The reuse of methods provided by the class to objects is as well a difference. If the methods of the class are updated, all instances of the class will immediately get the modified behavior. However, this does not mean that the reuse for the methods of stack is not possible. NX allows for example to copy objects (similar to prototype based languages) or to reuse methods via e.g. aliases (more about this later).

Note that we use capitalized names for classes and lowercase names for instances. This is not required and a pure convention making it easier to understand scripts without much analysis.

So far, the definition of the stack methods was pretty minimal. Suppose, we want to define "safe stacks" that protect e.g. against stack under-runs (a stack under-run happens, when more pop than push operations are issued on a stack). Safety checking can be implemented mostly independent from the implementation details of the stack (usage of internal data structures). There are as well different ways of checking the safety. Therefore we say that safety checking is orthogonal to the stack core implementation.

With NX we can define stack-safety as a separate class using methods with the same names as the implementations before, and "mix" this behavior into classes or objects. The implementation of Safety in stack under-runs and to issue error messages, when this happens.

Note that all the methods of the class Safety end with next. This command is a primitive command of NX, which calls the same-named method with the same argument list as the current invocation.

Assume we save the definition of the class Stack in a file named Stack.tcl and the definition of the class Safety in a file named Safety.tcl in the current directory. When we load the classes Stack and Safety into the same script (see the terminal dialog in e.g. a certain stack s2 as a safe stack, while all other stacks (such as s1) might be still "unsafe". This can be achieved via the option -mixin at the object creation time (see line 9 in option -mixin mixes the class Safety into the new instance s2.

When the method push of s2 is called, first the method of the mixin class Safety will be invoked that increments the counter and continues with next to call the shadowed method, here the method push of the Stack implementation that actually pushes the item. The same happens, when s2 pop is invoked, first the method of Safety is called, then the method of the Stack. When the stack is empty (the value of count reaches 0), and pop is invoked, the mixin class Safety generates an error message (raises an exception), and does not invoke the method of the Stack.

The last two commands in Listing 8 use introspection to query for the objects s1 and s2 in which order the involved classes are processed. This order is called the precedence order and is obtained via info precedence. We see that the mixin class Safety is only in use for s2, and takes there precedence over Stack. The common root class nx::Object is for both s1 and s2 the base class.

Note that in Listing 8, the class Safety is only mixed into a single object (here s2), therefore we refer to this case as a per-object mixin. Figure 9 shows the class diagram, where the class Safety is used as a per-object mixin for s2.

The mixin class Safety can be used as well in other ways, such as e.g. for defining classes of safe stacks:

The difference of a per-class mixin and a per-object mixin is that the per-class mixin is applicable to all instances of the class. Therefore, we call these mixins also sometimes instance mixins. In our example in Listing 10, Safety is mixed into the definition of SafeStack. Therefore, all instances of the class SafeStack (here the instance s3) will be using the safety definitions.

Figure 11 shows the class diagram for this definition. Note that we could use Safety as well as a per-class mixin on Stack. In this case, all stacks would be safe stacks and we could not provide a selective feature selection (which might be perfectly fine).

The definition of Stack is generic and allows all kind of elements to be stacked. Suppose, we want to use the generic stack definition, but a certain stack (say, stack s4) should be a stack for integers only. This behavior can be achieved by the same means as introduced already in Listing 5, namely object-specific methods.

The program snippet in Listing 12 defines an instance s4 of the class Stack and provides an object specific method for push to implement an integer stack. The method pull is the same for the integer stack as for all other stacks, so it will be reused as usual from the class Stack. The object-specific method push of s4 has a value constraint in its argument list (thing:integer) that makes sure that only integers can be stacked. In case the argument is not an integer, an exception will be raised. Of course, one could perform the value constraint checking as well in the body of the method proc by accepting an generic argument and by performing the test for the value in the body of the method. In the case, the passed value is an integer, the push method of Listing 12 calls next, and therefore calls the shadowed generic definition of push as provided by Stack.

An alternative approach is shown in Listing 13, where the class IntegerStack is defined, using the same method definition as s4, this time on the class level.

In our previous examples we defined methods provided by classes (applicable for their instances) and object-specific methods (methods defined on objects, which are only applicable for these objects). In this section, we introduce methods that are defined on the class objects. Such methods are sometimes called class methods or static methods.

In NX classes are objects, they are specialized objects with additional methods. Methods for classes are often used for managing the life-cycles of the instances of the classes (we will come to this point in later sections in more detail). Since classes are objects, we can use exactly the same notation as above to define class methods by using object method. The methods defined on the class object are in all respects identical with object specific methods shown in the examples above.

The class Stack2 in Listing 14 consists of the earlier definition of the class Stack and is extended by the class-specific method available_stacks, which returns the current number of instances of the stack. The final command puts (line 26) prints 2 to the console.

The class diagram in Figure 15 shows the diagrammatic representation of the class object-specific method available_stacks. Since every class is a specialization of the common root class nx::Object, the common root class is often omitted from the class diagrams, so it was omitted here as well in the diagram.

In general, NX does not need variable declarations. It allows one to create or modify variables on the fly by using for example the Tcl commands set and unset. Depending on the variable name (or more precisely, depending on the variable name’s prefix consisting of colons ":") a variable is either local to a method, or it is an instance variable, or a global variable. The rules are:

Listing 16 shows a method foo of some class Foo referring to differently scoped variables.

The basic building blocks of an object oriented program are object and classes, which contain named pieces of code, the methods.

Plain Tcl provides subroutines, which are not associated with objects or classes. Tcl distinguishes between +proc+s (scripted subroutines) and commands (system-languages implemented subroutines).

Methods might have different scopes, defining, on which kind of objects these methods are applicable to. These are described in more detail later on. For the time being, we deal here with methods defined on classes, which are applicable for the instance of these classes.

All kinds of methods might have different kind of protections in NX. The call-protection defines from which calling context methods might be called. The Next Scripting Framework supports as well redefinition protection for methods.

NX distinguishes between public, protected and private methods, where the default call-protection is protected.

All kind of method protections are applicable for all kind of methods, either scripted or C-implemented.

The distinction between public and protected leads to interfaces for classes and objects. Public methods are intended for consumers of these entities. Public methods define the intended ways of providing methods for external usages (usages, from other objects or classes). Protected methods are intended for the implementor of the class or subclasses and not for public usage. The distinction between protected and public reduces the coupling between consumers and the implementation, and offers more flexibility to the developer.

The example above uses :protected method helper …. We could have used here as well :method helper …, since the default method call-protection is already protected.

The method call-protection of private goes one step further and helps to hide implementation details also for implementors of subclasses. Private methods are a means for avoiding unanticipated name clashes. Consider the following example:

The base class implements a public method foo using the helper method named helper. The derived class implements a as well a public method bar, which is also using a helper method named helper. When an instance s1 is created from the derived class, the method foo is invoked which uses in turn the private method of the base class. Therefore, the invocation s1 foo 3 4 returns its sum. If the local flag had not beed used in helper, s1 would have tried to call the helper of Sub, which would be 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 the -local flag at the call site it is possible to invoke only the local definition of the method. If we would call the method without this flag, the resolution order would be the standard resolution order, starting with filters, mixins, object methods and the full intrinsic class hierarchy.

NX supports the modifier private for methods and properties. In all cases private is an instrument to avoid unanticipated interactions and means actually "accessible for methods defined on the same entity (object or class)". The main usage for private is to improve locality of the code e.g. for compositional operations.

In order to improve locality for properties, a private property defines therefore internally a variable with a different name to avoid unintended interactions. The variable should be accessed via the private accessor, which can be invoked with the -local flag. In the following example class D introduces a private property with the same name as a property in the superclass.

Without the private definition of the property, the definition of property x in class D would shadow the definition of the property in the superclass C for its instances (d1 x or set :x would return d instead of c).

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.

NX provides ensemble methods as a means to structure the method name space and to group related methods. Ensemble methods are similar in concept to Tcl’s ensemble commands.

Ensemble methods provide a means to group related commands together, and they are extensible in various ways. It is possible to add sub-methods at any time to existing ensembles. Furthermore, it is possible to extend ensemble methods via mixin classes.

The following example defines an ensemble method for string. An ensemble method is defined when the provide method name contains a space.

When a method is invoked, the applicable method is searched in the following order:

In the case, no mixins are involved, first the object is searched for an object method with the given name, and then the class hierarchy of the object. The method can be defined multiple times on the search path, so some of these method definitions might be shadowed by the more specific definitions.

Consider the example in Listing 32. When the method foo is invoked on object d1, the object method has the highest precedence and is therefore invoked. The object methods shadows the same-named methods in the class hierarchy, namely the method foo of class D and the method foo of class C. The shadowed methods can be still invoked, either via the primitive next or via method handles (we used already method handles in the section about method aliases). In the example above, next calls the shadowed method and add their results to the results of every method. So, the final result contains parts from d1, D and C. Note that the topmost next in method foo of class C shadows no method foo and simply returns empty (and not an error message).

The introspection method info precedence provides information about the order, in which classes processed during method resolution.

The example in Listing 33 is an extension of the previous example. We define here two additional classes M1 and M2 which are used as per-object and per-class mixins. Both classes define the method foo, these methods shadow the definitions of the intrinsic class hierarchy. Therefore an invocation of foo on object d1 causes first an invocation of method in the per-object mixin.

In the first line of the body of method bar, the method foo is called as usual with an implicit receiver, which defaults to the current object (therefore, the call is equivalent to d1 foo). The next three calls show how to provide flags that influence the method resolution. The flags can be provided between the colon and the method name. These flags are used rather seldom but can be helpful in some situations.

The invocation flag -local means that the method has to be resolved from the same place, where the current method is defined. Since the current method is defined as a object method, foo is resolved as a object method. The effect is that the mixin definitions are ignored. The invocation flag -local was already introduced int the section about method protection, where it was used to call private methods.

The invocation flag -intrinsic means that the method has to be resolved from the intrinsic definitions, meaning simply without mixins. The effect is here the same as with the invocation flag -local.

The invocation flag -system means that the method has to be resolved from basic - typically predefined - classes of the object system. This can be useful, when script overloads system methods, but still want to call the shadowed methods from the base classes. In our case, we have no definitions of foo on the base clases, therefore an error message is returned.

The output of Listing 34 is:

NX provides a generalized mechanism for passing values to either methods (we refer to these as method parameters) or to objects (these are called configure 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 configure parameters in more detail, we describe the parameter features in the subsequent sections based on method parameters.

…

…

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

We refer to the first two as method parameters and the last one as configure parameters. The examples in the previous sections all parameter specification were specifications of method parameters.

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.

Syntactically, configure 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.

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 44). The class diagram below visualizes these definitions.

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 configure parameters of Person augmented with the object parameters from Student (namely matnr and oncampus). Based on these configure 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, instance variables name, matnr and oncampus (the latter is initialized with the default value).

…

NX provides two kinds of unknown handlers: