1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin stooop n 4.4.1] 3[moddesc {Simple Tcl Only Object Oriented Programming}] 4[titledesc {Object oriented extension.}] 5[category {Programming tools}] 6[require Tcl 8.3] 7[require stooop [opt 4.4.1]] 8[description] 9[para] 10 11This package provides commands to extend Tcl in an object oriented 12manner, using a familiar C++ like syntax and behaviour. Stooop only 13introduces a few new commands: [cmd class], [cmd new], [cmd delete], 14[cmd virtual] and [cmd classof]. Along with a few coding conventions, 15that is basically all you need to know to use stooop. Stooop is meant 16to be as simple to use as possible. 17 18[para] 19 20This manual is very succinct and is to be used as a quick reminder for 21the programmer, who should have read the thorough [uri stooop_man.html] 22HTML documentation at this point. 23 24[list_begin definitions] 25 26 27[call [cmd ::stooop::class] [arg {name body}]] 28 29This command creates a class. The body, similar in contents to a Tcl 30namespace (which a class actually also is), contains member procedure 31definitions. Member procedures can also be defined outside the class 32body, by prefixing their name with [const class::], as you would 33proceed with namespace procedures. 34 35[list_begin definitions] 36 37[def "[cmd proc] [arg class] \{[const this] [opt [arg {arg arg ...}]]\} [opt "[arg base] \{[opt [arg {arg arg ...}]]\} ..."] [arg body]"] 38 39This is the constructor procedure for the class. It is invoked 40following a [cmd new] invocation on the class. It must have the same 41name as the class and a first argument named [const this]. Any number 42of base classes specifications, including arguments to be passed to 43their constructor, are allowed before the actual body of the 44procedure. 45 46[def "[cmd proc] ~[arg class] \{[const this]\} [arg body]"] 47 48This is the destructor procedure for the class. It is invoked 49following a [cmd delete] invocation. Its name must be the 50concatenation of a single [const ~] character followed by the class 51name (as in C++). It must have a single argument named [const this]. 52 53[def "[cmd proc] [arg name] \{[const this] [opt [arg {arg arg ...}]]\} [arg body]"] 54 55This is a member procedure of the class, as its first argument is 56named [const this]. It allows a simple access of member data for the 57object referenced by [const this] inside the procedure. For example: 58 59[example { 60 set ($this,data) 0 61}] 62 63[def "[cmd proc] [arg name] \{[opt [arg {arg arg ...}]]\} [arg body]"] 64 65This is a static (as in C++) member procedure of the class, as its 66first argument is not named [const this]. Static (global) class data 67can be accessed as in: 68 69[example { 70 set (data) 0 71}] 72 73[def "[cmd proc] [arg class] \{[const {this copy}]\} [arg body]"] 74 75This is the optional copy procedure for the class. It must have the 76same name as the class and exactly 2 arguments named [const this] and 77[const copy]. It is invoked following a [cmd new] invocation on an 78existing object of the class. 79 80[list_end] 81 82 83[call [cmd ::stooop::new] [arg class] [opt [arg {arg arg ...}]]] 84 85This command is used to create an object. The first argument is the 86class name and is followed by the arguments needed by the 87corresponding class constructor. A unique identifier for the object 88just created is returned. 89 90[call [cmd ::stooop::delete] [arg object] [opt [arg {object ...}]]] 91 92This command is used to delete one or several objects. It takes one or 93more object identifiers as argument(s). 94 95[call [cmd ::stooop::virtual] [const proc] [arg name] \{[const this] [opt [arg {arg arg ...}]]\} [opt [arg {body}]]] 96 97The [cmd virtual] specifier may be used on member procedures to 98achieve dynamic binding. A procedure in a base class can then be 99redefined (overloaded) in the derived class(es). If the base class 100procedure is invoked on an object, it is actually the derived class 101procedure which is invoked, if it exists. If the base class procedure 102has no body, then it is considered to be a pure virtual and the 103derived class procedure is always invoked. 104 105[call [cmd ::stooop::classof] [arg object]] 106 107This command returns the class of the existing object passed as single 108parameter. 109 110[call [cmd ::stooop::new] [arg object]] 111 112This command is used to create an object by copying an existing 113object. The copy constructor of the corresponding class is invoked if 114it exists, otherwise a simple copy of the copied object data members 115is performed. 116 117[list_end] 118 119[section DEBUGGING] 120 121[list_begin definitions] 122 123[def {Environment variables}] 124 125 126[list_begin definitions] 127 128[def [var STOOOPCHECKDATA]] 129 130Setting this variable to any true value will cause stooop to check for 131invalid member or class data access. 132 133[def [var STOOOPCHECKPROCEDURES]] 134 135Setting this variable to any true value will cause stooop to check for 136invalid member procedure arguments and pure interface classes 137instanciation. 138 139[def [var STOOOPCHECKALL]] 140 141Setting this variable to any true value will cause stooop to activate 142both procedure and data member checking. 143 144[def [var STOOOPCHECKOBJECTS]] 145 146Setting this variable to any true value will cause stooop to activate 147object checking. The following stooop namespace procedures then become 148available for debugging: [cmd printObjects], [cmd record] and 149[cmd report]. 150 151[def [var STOOOPTRACEPROCEDURES]] 152 153Setting this environment variable to either [const stdout], 154 155[const stderr] or a file name, activates procedure tracing. The 156stooop library will then output to the specified channel 1 line of 157informational text for each member procedure invocation. 158 159[def [var STOOOPTRACEPROCEDURESFORMAT]] 160 161Defines the trace procedures output format. Defaults to 162[const {"class: %C, procedure: %p, object: %O, arguments: %a"}]. 163 164[def [var STOOOPTRACEDATA]] 165 166Setting this environment variable to either [const stdout], 167 168[const stderr] or a file name, activates data tracing. The stooop 169library will then output to the specified channel 1 line of 170informational text for each member data access. 171 172[def [var STOOOPTRACEDATAFORMAT]] 173 174Defines the trace data output format. Defaults to 175[const {"class: %C, procedure: %p, array: %A, object: %O, member: %m, operation: %o, value: %v"}]. 176 177[def [var STOOOPTRACEDATAOPERATIONS]] 178 179When tracing data output, by default, all read, write and unsetting 180accesses are reported, but the user can set this variable to any 181combination of the letters [const r], [const w], and [const u] for 182more specific tracing (please refer to the [cmd trace] Tcl manual page 183for more information). 184 185[def [var STOOOPTRACEALL]] 186 187Setting this environment variable to either [const stdout], 188 189[const stderr] or a file name, enables both procedure and data 190tracing. 191 192[list_end] 193 194 195[call [cmd ::stooop::printObjects] [opt [arg pattern]]] 196 197Prints an ordered list of existing objects, in creation order, oldest 198first. Each output line contains the class name, object identifier and 199the procedure within which the creation occurred. The optional pattern 200argument (as in the Tcl [cmd {string match}] command) can be used to 201limit the output to matching class names. 202 203[call [cmd ::stooop::record]] 204 205When invoked, a snapshot of all existing stooop objects is 206taken. Reporting can then be used at a later time to see which objects 207were created or deleted in the interval. 208 209[call [cmd ::stooop::report] [opt [arg pattern]]] 210 211Prints the created and deleted objects since the [cmd ::stooop::record] 212procedure was invoked last. If present, the pattern argument limits 213the output to matching class names. 214 215[list_end] 216 217[section EXAMPLES] 218 219Please see the full HTML documentation in [uri stooop_man.html]. 220 221[section {BUGS, IDEAS, FEEDBACK}] 222 223This document, and the package it describes, will undoubtedly contain 224bugs and other problems. 225 226Please report such in the category [emph stooop] of the 227[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 228 229Please also report any ideas for enhancements you may have for either 230package and/or documentation. 231 232 233[keywords class {object oriented} object C++] 234[manpage_end] 235