stooop

Contents

• About this document
• Introduction
• Simple example
• Coding conventions
  • Class definition
  • Member procedures
    • Constructor
    • Destructor
    • Non static
    • Static
    • Copy constructor
  • Member data
    • Non static
    • Static
• Commands
  • class
  • new
  • delete
  • virtual
  • classof
• Package
  • Installation
  • Creation
• Examples
  • Parallel with C++
  • Graphical demonstration
  • Widget class
  • Member array
• Utility classes
  • switched
• Debugging
  • member check
    • procedure
    • data
  • member trace
    • procedure
    • data
  • objects
    • printing
    • recording
    • reporting
• Notes
  • On design choices
  • On implementation
• Miscellaneous information

About this document

A working knowledge of object oriented programming techniques and a related programming language (C++, Java, ...) significantly helps understand this document.

Introduction

Great care was taken so that this extension would no adverse impact on performance. Furthermore, designing your code in an object oriented should improve its performance, by focusing on well written pieces of reusable code.

Stooop only introduces a few new commands: class, new, delete, virtual and classof. Along with a few coding conventions, that is basically all you need to know to use stooop. Stooop is meant to be as simple to use as possible.

Starting with stooop version 3.2, nested classes are supported (see class), whereas version 3.3 and above support procedure and data members checking as well as tracing (see debugging).

Tcl version 8.2 and above supports the empty name array syntax, as in:

set (m) 0 ;# set member m of array {} to 0
set n $(m) ;# which actually sets n to 0

Simple example

package require stooop 4                                  ;# load stooop package
namespace import stooop::*                ;# and import class, new, ... commands

class shape {                                           ;# base class definition
    proc shape {this x y} {                            ;# base class constructor
        set ($this,x) $x                           ;# data member initialization
        set ($this,y) $y
    }
    proc ~shape {this} {}                               ;# base class destructor
    # pure virtual draw: must be implemented in derived classes
    virtual proc draw {this}
    virtual proc rotate {this angle} {}                 ;# do nothing by default
}
proc shape::move {this x y} {            ;# external member procedure definition
    set ($this,x) $x
    set ($this,y) $y
    draw $this               ;# shape::draw invokes derived class implementation
}

class triangle {                                             ;# class definition
    proc triangle {this x y} shape {$x $y} {               ;# derived from shape
        # triangle constructor implementation
    }
    proc ~triangle {this} {}
    proc draw {this} {
        # triangle specific implementation
    }
    proc rotate {this angle} {
        # triangle specific implementation
    }
}

class circle {}        ;# empty class definition, procedures are defined outside
proc circle::circle {this x y} shape {$x $y} {             ;# derived from shape
    # circle constructor implementation
}
proc circle::~circle {this} {}
proc circle::draw {this} {
    # circle specific implementation
}
# circle::rotate procedure is a noop, no need to overload

lappend shapes [new circle 20 20] [new triangle 80 20]
foreach object $shapes {
    shape::draw $object
    shape::rotate $object 45
}
eval delete $shapes

Coding conventions

Class definition

class className { ...

The member procedures are then defined, inside or outside the class definition (see below). Note that the base classes if any are defined within the constructor declaration where they are required for eventually passing constructor parameters, not in the actual class declaration where they would then be redundant.

As a class is a namespace, it is just as easy to nest classes as it is namespaces.

Member procedures

Member procedures are named as in C++ (for example, the rotate procedure of the class shape is referred to as shape::rotate in the global namespace). They are defined using the Tcl proc command, which is redefined by stooop in order to do some specific additional processing. Of course, global level and other namespaces procedures are not affected by stooop.

Constructor

The constructor always takes the object identifier (a unique value generated by the command new) as the first parameter, plus eventually additional parameters as in the normal Tcl proc command. Arguments with default values are allowed, and so are variable number of arguments (see below). In all cases, the first parameter must be named this.

Note: the object identifier is a unique integer value which is internally incremented by stooop each time a new object is created. Consequently, the greater the object identifier, the younger the object.

Sample code of a constructor of a simple class with no base class:

class shape {
    proc shape {this x y} {
        # implementation here
    }
}

Note: base classes are not defined at the class command level, because it would be redundant with the constructor definition, which is mandatory.

The derived class constructor parameters are followed by "base class names / constructor arguments" pairs. For each base class, there must be a corresponding list of constructor arguments to be used when the object is constructed when the new operator is invoked with the derived class name as argument.

Sample code for a class constructor with a single base class:

class circle {}
proc circle::circle {this x y} shape {$x $y} {
    # circle constructor implementation
}

class hydroplane {
    proc hydroplane {this wingspan length} plane {
        $wingspan $length
    } boat {
        $length
    {
        # constructor implementation
    }
}

Sample code for a derived class constructor with base class constructor arguments processing:

class circle {
    proc circle {this x y} shape {
        [expr round($x)] [expr round($y)]
    } {
        # constructor implementation
    }
}

Variable length arguments are a special case and depend on both the derived class constructor arguments and those of the base class.

If both derived and base class constructors take a variable number of arguments (through the args special argument (see Tcl proc manual page)), the base class constructor will also see the variable arguments part as separate arguments. In other words, the following works as expected:

class base {}
proc base::base {this parameter args} {
    array set options $args
}
class derived {}
proc derived::derived {this parameter args} base {
    $parameter $args
} {}
new derived someData -option value -otherOption otherValue

class base {
    proc base {this parameter args} {
        array set options $args
    }
}
class derived {
    proc derived {this parameter args} base {
        $parameter [process $args]
    } {}
    proc process {arguments} {
        # do some processing on arguments list
        return $arguments
    }
}
new derived someData -option value -otherOption otherValue

Destructor

The destructor always takes the object identifier (a unique value previously generated and returned by the operator new) as the only parameter, which must be named this.

The base class(es) destructor(s) is(are) invoked at the end of the derived class destructor body. Thus layered object destruction occurs in the same order as in C++.

Sample code of a class destructor:

class shape {
    proc ~shape {this} {
        # implementation here
    }
}

Non static

The member procedure always takes the object identifier (a unique value generated and returned by the operator new) as the first parameter, plus eventually additional parameters as in the normal Tcl proc command. Arguments with default values are allowed, and so are variable number of arguments. In all cases, the first parameter must be named this.

Sample code of a member procedure:

proc shape::move {this x y} {
    set ($this,x) $x
    set ($this,y) $y
    draw $this       ;# invoke another member procedure
}

Static

However, with stooop, there is no static specifier: a member procedure is considered static if its first parameter is not named this. Arguments to the procedure are allowed as in the normal Tcl proc command. Arguments with default values are also allowed, and so are variable number of arguments.

Sample code of a static member procedure:

proc shape::add {newShape} {
    # append new shape to global list of shape
    lappend ($shapes) $newShape
}

A static member procedure may not be a virtual procedure.

Copy constructor

Let us start by making it clear that stooop generates a default copy constructor whenever a class main constructor is defined. This default copy constructor just performs a simple per data member copy, as does C++.

The user defined class copy constructor is optional as in C++. If it exists, it will be invoked (instead of the default copy constructor) when the operator new is invoked on an object of the class or a derived class.

The copy constructor takes 2 arguments: the this object identifier used to initialize the data members of the object to be copied to, and the copy identifier of the object to be copied from, as in:

proc plane::plane {this copy} {
    set ($this,wingspan) $($copy,wingspan)
    set ($this,length) $($copy,length)
    set ($this,engine) [new $($copy,engine)]
}

The copy constructor must be defined when the default behavior (straightforward data members copy) (see the new operator) is not sufficient, as in the example above. It is most often used when the class object contains sub objects. As in C++ when sub objects are referenced through pointers, only the sub object identifiers (see them as pointers) are copied when an object is copied, not the objects they point to. It is then necessary to define a copy procedure that will actually create new sub objects instead of just defaulting to copying identifiers.

If the class has one or more base classes, then the copy constructor must pass arguments to the base class(es) constructor(s), just as the main constructor does, as in the following example:

class ship {
    proc ship {this length} {}
}
class carrier {}
proc carrier::carrier {this length} ship {$length} {}
proc carrier::carrier {this copy} ship {
    $ship::($copy,length)
} {
    set ship::($this,planes) {}
    foreach plane $ship($copy,planes) {                   ;# copy all the planes
        lappend ship($this,planes) [new $plane]
    }
}

If you use member arrays, you must copy them within the copy constructor, as they are not automatically handled by stooop, which only knows member data in the automatically generated default copy constructor.

Member data

Sample code:

class shape {}
proc shape::shape {this x y} {
    # set a few members of the class namespace empty named array
    set ($this,x) $x
    set ($this,y) $y
    # now read them
    puts "coordinates: $($this,x), $($this,y)"
}

Sample code:

proc circle::circle {this x y diameter} shape {$x $y} {
    set ($this,diameter) $diameter
    puts "coordinates: $shape::($this,x), $shape::($this,y)"
}

Non static

Much as an object pointer in C++ is unique, the object identifier in stooop is also unique. Access to any base class data is thus possible by directly indexing the base class array.

Sample code:

proc shape::shape {this x y} {
    set ($this,x) $x
    set ($this,y) $y
}
proc circle::circle {this x y diameter} shape {$x $y} {
    set ($this,diameter) $diameter
}
proc circle::print {this} {
    puts "circle $this data:"
    puts "diameter: $($this,diameter)"
    puts "coordinates: $shape::($this,x), $shape::($this,y)"
}

Static

proc shape::register {newShape} {
    lappend (list) $newShape ;# append new shape to global list of shapes
}

Commands

class

A class is also a namespace although you do not need to worry about it, but it does have some nice side effects. The following code works as expected:

class shape {
    set (list) {} ;# initialize list of shapes, a static data member
    proc shape {this x y} {
        lappend (list) $this             ;# keep track of new shapes
    }
    ...
}

Starting with version 3.2, nested classes are allowed, which makes the following code possible:

class car {
    proc car {this manufacturer type} {
        set ($this,wheels) [list\
            [new wheel 18] [new wheel 18] [new wheel 18] [new wheel 18]\
        ]
        ...
    }
    ...
    class part {
        ...
    }
    class wheel {
        proc wheel {this diameter} car::part {} {
            set ($this,diameter) $diameter
            ...
        }
        proc print {this} {
            puts "wheel of $($this,diameter) diameter"
        }
        ...
    }
}

First, why would I use a nested class? Because it is cleaner that creating carPart and carWheel classes and saves on global namespace pollution.

Second, why does "new wheel" work from inside the car constructor? Because it invokes the wheel::wheel constructor, visible from the car namespace.

Third, why can't I simply derive wheel from part instead of car::part? Well, you must fully qualify the class that you derive from because the part::part constructor is not visible from within the wheel namespace.

Whenever you have a problem with nested classes, think in terms of namespaces, as classes are indeed namespaces (it should be clear to you by now :-).

new

When explicitly creating an object, the first argument is the class name and is followed by the arguments needed by the class constructor. New when invoked generates a unique identifier for the object to be created. This identifier is the value of the this parameter, first argument to the class constructor, which is invoked by new.

Sample code:

proc shape::shape {this x y} {
    set ($this,x) $x
    set ($this,y) $y
}
set object [new shape 100 50]

shape::shape 1234 100 50

proc hydroplane::hydroplane {this wingspan length} plane {
    $wingspan $length
} boat {
    $length
} {}
set object [new hydroplane 10 7]

plane::plane 1234 10 7

boat::boat 1234 7

finally hydroplane constructor is called, as in:

hydroplane::hydroplane 1234 10 7

The new operator can also be used to copy objects when an object identifier is its only argument. A new object of the same class is then created, copy of the original object.

An object is copied by copying all its data members (but not including member arrays) starting from the base class layers. If the copy constructor procedure exists for any class layer, it is invoked by the new operator instead of the default data member copy procedure (see the copy constructor section for examples).

Sample code:

set plane [new plane 100 57 RollsRoyce]
set planes [list $plane [new $plane] [new $plane]]

delete operator

Sample code:

proc shape::shape {this x y} {}
proc shape::~shape {this} {

proc triangle::triangle {this x y} shape {$x $y} {}
proc triangle::~triangle {this} {}

proc circle::circle {this x y} shape {$x $y} {}
proc circle::~circle {this} {}

set circle [new circle 100 50]
set triangle [new triangle 200 50]
delete $circle $triangle

circle::~circle 1234

shape::~shape 1234

then delete triangle object...

For each object class, if it is derived from one or more base classes, the base class(es) destructor(s) are automatically called in reverse order of the construction order for base class(es) constructor(s), as in C++.

If an error occurs during the deletion process, an error is returned and the remaining delete argument objects are left undeleted.

virtual specifier

If the base class procedure is invoked on an object, it is actually the derived class procedure which is invoked, if it exists*. If the base class procedure has no body, then it is considered to be a pure virtual and the derived class procedure is always invoked.

* as in C++, virtual procedures invoked from the base class constructor result in the base class procedure being invoked, not the derived class procedure. In stooop, an error always occurs when pure virtual procedures are invoked from the base class constructor (whereas in C++, behavior is undefined).
* but there is a small difference with C++ behavior: for a virtual procedure to keep his nature down the derived classes hierarchy, it must be defined at each derivation level. That is, the virtual nature may be lost, for example in indirectly derived classes (see example below). Fixing this difference would have a non negligible impact on performance for a small gain in usefulness.

Sample code:

class shape {
    proc shape {this x y} {}
    # pure virtual draw: must be implemented in derived classes
    virtual proc draw {this}
    virtual proc transform {this x y} {
        # base implementation
    }
}
class circle {}
proc circle::circle {this x y} shape {$x $y} {}
proc circle::draw {this} {
    # circle specific implementation
}
proc circle::transform {this} {
    shape::_transform $this ;# use base class implementation
    # add circle specific implementation here...
}

lappend shapes [new circle 100 50]
foreach object $shapes {
    # draw and move each shape
    shape::draw $object
    shape::move $object 20 10
}

Constructors, destructors and static member procedures cannot be virtual.

Sample code highlighting small difference with C++:

class A {
    proc A {this} {}
    proc ~A {this} {}
    virtual proc p {this} {puts A}
}
class B {
    proc B {this} A {} {}
    proc ~B {this} {}
}
class C {
    proc C {this} B {}{}
    proc ~C {this} {}
    virtual proc p {this} {puts C}
}

set object [new C]
A::p $object ;# prints "A" instead of "C"

virtual proc B::p {this} {puts B}

A::p $object ;# now prints "C"

classof operator

proc shape::shape {this x y} {}
set id [new shape 100 50]
puts "object $id class name is [classof $id]"

Package

Installation

Creation

If you have created an object oriented library which uses stooop, you may want to make a package out of it. Unfortunately, using the default Tcl pkg_mkIndex procedure (see the corresponding manual page) will not work.

Stooop checks that a base class constructor is defined before any of its derived classes constructors. Thus, the first time a derived class object is created, the base class definition file must be sourced to avoid an error. The specific mkpkgidx.tcl utility handles such cases and must be used to create stooop compatible package index files.

Let us suppose that you created a library with different classes spread in different source files: lib1.tcl, lib2.tcl, ..., libn.tcl. Of course, some of these files may contain base classes for derived classes in other files. As recommended in the pkg_mkIndex Tcl manual page, each source file should contain a package provide command (although it seems to be needed only in the first source file). For example, if your package name is foo and the version 1.2, the following line should appear around the beginning of each of the libn.tcl files:

package provide foo 1.2

interpreter mkpkgidx.tcl packageName file [file ...]

Enter the following command in the directory where the libn.tcl files reside:

$ tclsh mkpkgidx.tcl foo lib1.tcl lib2.tcl ... libn.tcl

$ wish mkpkgidx.tcl foo lib1.tcl lib2.tcl ... libn.tcl

If your package requires other packages and you do not wish to add the corresponding "package require" to your package source files, use the -p option, as in:

$ wish mkpkgidx.tcl -p ppp.1 -p qqq -p rrr.3.2 foo lib1.tcl lib2.tcl ... libn.tcl

Once this is done, a pkgIndex.tcl file will have been created in the current directory. To install the package, enter for example:

$ mkdir /usr/local/lib/foo
$ cp pkgIndex.tcl lib1.tcl lib2.tcl ... libn.tcl /usr/local/lib/foo/

Now in order to use your newly created packaged library in your application, just insert the following 3 lines at the beginning of the application source file:

package require stooop
namespace import stooop::*
package require foo 1.2

Examples

Parallel with C++

C++:

    class className {
    public:
        someType someMember;
        className(someType parameter)
        {
            someMember = parameter;
        }
        className(className &object)
        {
            ...
        }
        doSomething(someType parameter);
        ~className(void) {
            ...
        }
    };
    someType className::doSomething(someType parameter)
    {
        ...
    }
    someType someValue;
    className *someObject = new className(someValue);
    someType a = someObject->doSomething(someValue);
    someType b = someObject->someMember;
    className *otherObject = new className(*someObject);
    delete someObject;

    class className {
        proc className {this parameter} {
            # new keeps track of object identifiers and passes a unique one
            # to the constructor
            set ($this,someMember) $parameter
        }
        proc className {this copy} {
            # copy constructor
            ...
        }
        proc ~className {this} {
            # delete invokes this procedure then takes care of deallocating
            # className array data members for this object identifier
            ...
        }
    }
    proc className::doSomething {this parameter} {
        ...
    }
    set someObject [new className $someValue]
    # invokes className::className
    set a [className::doSomething $someObject $someValue]
    set b $className::($someObject,someMember)
    # copy object, className copy constructor is invoked
    set otherObject [new $someObject]
    delete $someObject
    # invokes className::~className then frees members data

C++:

    class baseClassName {
    public:
        virtual void doSomething(someType) {}
        baseClassName(void) {}
        virtual ~baseClassName(void) {}
    };
    class derivedClassName: public baseClassName {
    public:
        void doSomething(someType);
        derivedClassName(void) {}
        ~derivedClassName(void) {}
    };
    void derivedClassName::doSomething(someType parameter)
    {
        ...
    }
    derivedClassName *someObject = new derivedClassName();
    someObject->doSomething(someValue);      // derived function actually called
    cout << typeid(*someObject).name() << endl;       // print object class name
    delete someObject;                        // derived destructor called first

    class baseClassName {
        proc baseClassName {this} {
            # sub-class is remembered so that virtual procedures may be used
            ...
        }
        proc ~baseClassName {this} {
            # cleanup at base level here...
        }
        virtual proc doSomething {this parameter} {
            # derived class procedure with the same name may be invoked
            # any code that follows is not executed if this procedure is
            # overloaded in derived class
            ...
        }
    }
    class derivedClassName {
        proc derivedClassName {this} baseClassName {} {
            # base class constructor is automatically invoked
            ...
        }
        proc ~derivedClassName {this} {
            # cleanup at derived level here...
            # base class destructor is automatically invoked
        }
    }
    proc derivedClassName::doSomething {this parameter} {
        # code that follows is executed when base class procedure is called
        ...
    }
    set someObject [new derivedClassName]
    # access object as base object, derived class procedure is actually invoked
    baseClassName::doSomething $someObject $someValue
    puts [classof $someObject]                        ;# print object class name
    delete $someObject                                          ;# delete object

Graphical demonstration

The pattern is used to define a class hierarchy of the graphic base class, picture, oval and rectangle derived classes. A picture object can contain any number of other graphic objects, thus allowing graphical composition.

The following paragraphs drawn from the book best describe what the Composite pattern does:

Compose objects into tree structures to represent part-whole hierarchies. Composite lets clients treat individual objects and compositions of objects uniformly.

The key to the Composite pattern is an abstract class that represents both primitives and their containers. For the graphic system, this class is Graphic. Graphic declares operations like Draw that are specific to graphical objects. It also declares operations that all composite objects share, such as operations for accessing and managing its children.

Gamma/Helm/Johnson/Vlissides, DESIGN PATTERNS, ELEMENTS OF REUSABLE OBJECT-ORIENTED SOFTWARE, (c) 1995 by Addison-Wesley Publishing Company, Reprinted by permission of Addison-Wesley Publishing Company, Inc.

Run gdemo as in:

$ wish gdemo

A Picture object can contain any number of Graphic objects, such as other Picture objects, Rectangle objects, ...

For each Graphic object, the point used for moving and for the object coordinates is the upper left corner of the object.

First create a Picture object by clicking on the Picture button. Move the red rectangle that appears by drag clicking on any of its edges. Then create a Rectangle object by clicking on the Rectangle button. Drag the Rectangle object in the Picture object, it is then a child of the Picture object.

Move the Picture object to verify that its Rectangle child moves along.

Create another Picture object and place an Oval object within.

Move that Picture object to verify that its Oval child moves along.

Now move the upper left corner of that last Picture within the first Picture area.

Then move that Picture to verify that all the Graphic objects move along.

Widget class

Sample code (without error checking):

class widget {
    proc widget {this parent args} {
        # create Tk widget(s)
        # set widget options default in an array
        array set options {-background white -width 10}
        array set options $args              ;# then overwrite with user options
        eval configure $this [array get options]               ;# then configure
    }
    virtual proc configure {this args} {
        foreach {option value} $args {
            switch -- $option {
                -background {             ;# filter widget specific options here
                    set ($this,background) $value
                    # configure Tk widget(s)
                }
                ...
            }
        }
    }
}

class gizmo {}
proc gizmo::gizmo {this parent args} widget {$parent $args} {
    # create more Tk widget(s)
    # set gizmo options default in an array
    array set options {-spacetimecoordinates {0 0 0 now}}
    array set options $args                  ;# then overwrite with user options
    eval ownConfigure $this [array get options]                ;# then configure
}
proc gizmo::ownConfigure {this args} {
    foreach {option value} $args {
        switch -- $option {                ;# filter gizmo specific options here
            -spacetimecoordinates {
                set ($this,location) $value
                # configure Tk widget(s)
            }
            ...
        }
    }
}
proc gizmo::configure {this args} {
    eval ownConfigure $this $args                    ;# configure at gizmo level
    eval widget::_configure $this $args             ;# configure at widget level
}

new gizmo . -width 20 -spacetimecoordinates {1p 10ly 2p 24.2y}

Member array

• embed the array and its index in member data
• use a namespace array for possibly better performance

For example, when embedding in member data:

class container {
    proc container {this} {}
    proc ~container {this} {}
    proc container::add {this index value} {
        set ($this,array,$index) $value
    }
}

With a namespace array, use a name specific to the object, including the object identifier, and do not forget to delete the array in the destructor, as the following example shows:

class container {
    proc container {this} {}
    proc ~container {this} {
        variable ${this}array
        unset ${this}array
    }
    proc container::add {this index value} {
        variable ${this}array
        set ${this}array($index) $value
    }
}

class container {
    proc container {this} {                                  ;# main constructor
        ...
    }               ;# default copy constructor has been generated at this point
    proc container {this copy} {      ;# copy constructor (replaces default one)
        variable ${this}array
        variable ${copy}array
        array set ${this}array [array get ${copy}array]     ;# copy member array
    }
    ...
}

Utility classes

switched

Find the complete documentation here.

Debugging

Starting from version 3.3, debugging aids were added to the stooop library (still held in a single file). Member checking insures that basic object oriented concepts and rules are applied. Tracing provides means for member procedures and data access logging to a file or to the screen.

The above features are triggered and configured using environment variables. When not in use, they have absolutely no impact on stooop's performance (however, if you are really picky, you could say that since the stooop.tcl file has grown larger, load time got longer :).

Please note that any stooop debugging environment variable must be set prior to the stooop library being loaded:

$ STOOOPTRACEDATA=stdout
$ export STOOOPTRACEDATA
$ tclsh myfile.tcl

...
set env(STOOOPCHECKPROCEDURES) 1
source stooop.tcl
namespace import stooop::*
set env(STOOOPCHECKDATA) 1
...

Member check

Note: if you have an idea about any other thing that could be checked in the following sections, please share it with me.

Procedure

• an invalid this parameter (a non existing object identifier) is passed as argument to a non static member procedure
• the object identified by the this parameter passed as argument to a class non static member procedure is neither an instance of the procedure class nor an instance of a derived class (at any level of derivation) of the procedure class.
• a pure interface class (a class with at least 1 pure virtual member procedure) is instanciated

Data

• in a class namespace but outside a member procedure, a data member of another class is written or unset
• in a class member procedure (static or not), a data member of another class is written or unset
• in a non static member procedure, a data member of an object different from the object identified by the this parameter passed as argument is written or unset

Member trace

Procedure

The user can define the output format by redefining the STOOOPTRACEPROCEDURESFORMAT (look at the beginning of the stooop.tcl file for the default format). The following substitutions will be performed prior to the output:

• %C by the fully qualified class name
• %c by the class name (tail of the fully qualified class name)
• %P by the fully qualified procedure name
• %p by the procedure name (tail of the fully qualified procedure name)
• %O by the object identifier (this value)
• %a by the remaining procedure arguments (not including this)

class: %C, procedure: %p, object: %O, arguments: %a

class: picture, procedure: constructor, object: 1, arguments: .canvas
class: graphic, procedure: constructor, object: 1, arguments: .canvas 1
class: rectangle, procedure: constructor, object: 2, arguments: .canvas
class: graphic, procedure: constructor, object: 2, arguments: .canvas 2
class: graphic, procedure: moveTo, object: 2, arguments: 13 4
class: graphic, procedure: _moveTo, object: 2, arguments: 13 4
class: graphic, procedure: moveTo, object: 2, arguments: 18 9
class: graphic, procedure: add, object: 1, arguments: 2
class: picture, procedure: add, object: 1, arguments: 2
class: graphic, procedure: add, object: 2, arguments: 2
class: rectangle, procedure: add, object: 2, arguments: 2
class: picture, procedure: destructor, object: 1, arguments:
class: graphic, procedure: destructor, object: 1, arguments:
class: rectangle, procedure: destructor, object: 2, arguments:
class: graphic, procedure: destructor, object: 2, arguments:

Data

Note that operations internal to the stooop library, such as automatic unsetting of data members during objects destruction do not appear in the trace.

The user can define the output format by redefining the STOOOPTRACEDATAFORMAT (look at the beginning of the stooop.tcl file for the default format). The following substitutions will be performed prior to the output:

• %C by the fully qualified class name
• %c by the class name (tail of the fully qualified class name)
• %P by the fully qualified procedure name
• %p by the procedure name (tail of the fully qualified procedure name)
• %A by the fully qualified array name
• %m by the data member name (right after the this, array name part for a non static data member)
• %O by the object identifier (this value or empty for a static procedure)
• %o by the access operation (read, write or unset)
• %v by the new or current value (empty for an unset operation)

class: %C, procedure: %p, array: %A, object: %O, member: %m, operation: %o, value: %v

class: graphic, procedure: constructor, array: graphic::, object: 1, member: canvas, operation: write, value: .canvas
class: graphic, procedure: constructor, array: graphic::, object: 1, member: item, operation: write, value: 1
class: picture, procedure: constructor, array: picture::, object: 1, member: graphics, operation: write, value: 
class: picture, procedure: moveTo, array: graphic::, object: 1, member: canvas, operation: read, value: .canvas
class: picture, procedure: moveTo, array: graphic::, object: 1, member: item, operation: read, value: 1
class: picture, procedure: moveBy, array: picture::, object: 1, member: graphics, operation: read, value: 
class: graphic, procedure: _moveBy, array: graphic::, object: 1, member: canvas, operation: read, value: .canvas
class: graphic, procedure: _moveBy, array: graphic::, object: 1, member: item, operation: read, value: 1
class: graphic, procedure: constructor, array: graphic::, object: 2, member: canvas, operation: write, value: .canvas
class: graphic, procedure: constructor, array: graphic::, object: 2, member: item, operation: write, value: 2
class: graphic, procedure: _moveTo, array: graphic::, object: 2, member: canvas, operation: read, value: .canvas
class: graphic, procedure: _moveTo, array: graphic::, object: 2, member: item, operation: read, value: 2
class: graphic, procedure: _moveTo, array: graphic::, object: 2, member: canvas, operation: read, value: .canvas
class: graphic, procedure: _moveTo, array: graphic::, object: 2, member: item, operation: read, value: 2
class: graphic, procedure: _moveTo, array: graphic::, object: 2, member: canvas, operation: read, value: .canvas
class: graphic, procedure: _moveTo, array: graphic::, object: 2, member: item, operation: read, value: 2
class: graphic, procedure: _moveTo, array: graphic::, object: 2, member: canvas, operation: read, value: .canvas
class: graphic, procedure: _moveTo, array: graphic::, object: 2, member: item, operation: read, value: 2
class: picture, procedure: add, array: graphic::, object: 1, member: canvas, operation: read, value: .canvas
class: picture, procedure: add, array: graphic::, object: 1, member: item, operation: read, value: 2
class: picture, procedure: add, array: graphic::, object: 1, member: canvas, operation: read, value: .canvas
class: picture, procedure: add, array: graphic::, object: 1, member: item, operation: read, value: 1
class: graphic, procedure: destructor, array: graphic::, object: 1, member: canvas, operation: read, value: .canvas
class: graphic, procedure: destructor, array: graphic::, object: 1, member: item, operation: read, value: 1
class: graphic, procedure: destructor, array: graphic::, object: 2, member: canvas, operation: read, value: .canvas
class: graphic, procedure: destructor, array: graphic::, object: 2, member: item, operation: read, value: 2

Objects

Before outputting any data, all the object checking procedures print which procedure they were invoked from, or the namespace name if invoked from a namespace body or "top level" if invoked outside any procedure or namespace.

Printing

% new foo
1
% stooop::printObjects
stooop::printObjects invoked from top level:
::foo(1) + top level
% new bar
2
% stooop::printObjects
stooop::printObjects invoked from top level:
::foo(1) + top level
::bar(2) + top level
% new Foo
3
% stooop::printObjects ::?oo
stooop::printObjects invoked from top level:
::foo(1) + top level
::Foo(3) + top level
% new barmaid
4
% stooop::printObjects ::bar*
stooop::printObjects invoked from top level:
::bar(2) + top level
::barmaid(4) + top level

Recording

The record procedure does not take any arguments and it only prints its context of invocation.

Reporting

Reporting is typically used between 2 spots in the debugged application code: the first spot where a bunch of objects (which can include sub objects) are created, the second spot where all or most of these objects are supposed to be deleted. On the first spot, stooop::record is invoked whereas on the second spot, the stooop::report invocation will print the created and/or deleted objects, in other words the "object difference" between the 2 spots. In most cases, the programmer would expect a difference of 0 objects, sign of a well behaved application, memory wise.

Consider the following example:

class foo {
    proc foo {this} {}
    proc ~foo {this} {}
}
class bar {
    proc bar {this} {
        new foo
    }
    proc ~bar {this} {}
}
stooop::record
delete [new bar]
stooop::report
stooop::record
delete 2
stooop::report

stooop::record invoked from top level
stooop::report invoked from top level:
+ ::foo(2) + ::bar::bar
stooop::record invoked from top level
stooop::report invoked from top level:
- ::foo(2) - top level + ::bar::bar

Notes

On design choices

A familiar C++ syntax should serve as a model (not all, though, I didn't feel like writing 700 pages of documentation :-).

Tcl being a non declarative language (which I really enjoy), stooop would have to try to comply with that approach.

Error checking would have to be strong with little impact on performance.

On implementation

The delete operation was greatly simplified, especially for classes that would require a virtual destructor in C++, by storing in an array the class of each object. It then became trivial to delete any object from its identifier only. This approach has an impact on memory use, though, but I consider that one is not very likely to create a huge number of objects in a Tcl application. Furthermore, a classof RTTI operator was then added with no effort.

Stooop learns class hierarchies through the constructor definition whichserves as an implementation as well, thus (kind of) better fitting the non declarative nature of Tcl.

All member data is public but access control is somewhat enforced by having to explicitly name the class layer of external data being accessed.

Since, for performance reasons, the stooop library performs very little checking during run-time (after all classes and their procedures were defined), debugging aids are provided starting from version 3.3. They attempt to insure that your code is well written in an object oriented sense. They also provide means for tracing data access and procedures.

Miscellaneous information

Send your comments, complaints, ... to Jean-Luc Fontaine.