Update autosetup to latest version
[jimtcl.git] / README.oo
blobfc59fafd4b01e83aa6995a620a040d124ca15b52
1 OO Package for Jim Tcl
2 ======================
4 Author: Steve Bennett <steveb@workware.net.au>
5 Date: 1 Nov 2010 09:18:40
7 OVERVIEW
8 --------
9 The pure-Tcl oo package leverages Jim's unique strengths
10 to provide support for Object Oriented programming.
12 The oo package can be statically linked with Jim or installed
13 as a separate Tcl package and loaded with:
15   package require oo
17 DECLARING CLASSES
18 -----------------
19 A class is declared with the 'class' proc as follows.
21   class myclass ?baseclasses? classvars
23 This declares a class named 'myclass' with the given dictionary,
24 'classvars', providing the initial state of all new objects.
25 It is important to list all class variables in 'classvars', even
26 if initialised only to the empty string, since the class makes
27 these variables available in methods and via [myclass vars].
29 A list of zero or more base classes may also be specified from
30 which methods and class variables are imported. See INHERITANCE
31 below for more details.
33 Declaring a class creates a procedure with the class name along
34 with some related procedures. For example:
36   . class Account {balance 0}
37   Account
38   . info procs Account*
39   {Account get} {Account methods} {Account eval} Account {Account new} {Account destroy}
40   {Account vars} {Account classname} {Account classvars} {Account method}
42 Notice that apart from the main 'Account' procedure, all the remaining procedures (methods)
43 are prefixed with 'Account' and a space.
45 PREDEFINED CLASS METHODS
46 ------------------------
47 Decaring a class pre-defines a number of "class" methods. i.e. those which don't
48 require an object and simply return or manipulate properties of the class. These are:
50   new ?instancevars?::
51     Creates and returns new object, optionally overriding the default class variable values.
52         Note that the class name is an alias for 'classname new {}' and can be used as a shorthand
53         for creating new objects with default values.
55   method name arglist body::
56     Creates or redefines a method for the class with the given name, argument list and body.
58   methods::
59     Returns a list of the methods supported by this class, including both class methods
60         and instance methods. Also includes base class methods.
62   vars::
63         Returns a list of the class variables for this class (names
64         only). Also includes base class variables.
66   classvars::
67         Returns a dictionary the class variables, including initial values, for this class.
68         Also includes base class variables.
70   classname::
71     Returns the classname. This can be useful as [$self classname].
73 Class methods may be invoked either via the class name or via an object of the class.
74 For example:
76   . class Account {balance 0}
77   Account
78   . Account methods
79   classname classvars destroy eval get method methods new vars
80   . set a [Account]
81   <reference.<Account>.00000000000000000001>
82   . $a methods
83   classname classvars destroy eval get method methods new vars
85 PREDEFINED OBJECT METHODS
86 -------------------------
87 Decaring a class pre-defines a number of "object" methods. i.e. those which operate
88 on a specific object.
90   destroy::
91     Destroys the object. This method may be overridden, but note that it should
92         delete the object with {rename $self ""}. This method will also be called
93         if the object is reaped during garbage collection.
95   get varname::
96     Returns the value of the given instance variable.
98   eval ?locals? body::
99     Makes any given local variables available to the body, along with
100         the instance variables, and evaluate the body in that context.
101         This can be used for one-off evaluation to avoid declaring a method.
103 CREATING OBJECTS
104 ----------------
105 An object is created with the 'new' method, or simply by using the classname shortcut.
106 If the 'new' method is used, the variables for the newly created object (instance variables)
107 may be initialised. Otherwise they are set to the default values specified when the
108 class was declared.
110 For example:
112   . class Account {balance 0}
113   Account
114   . set a [Account]
115   <reference.<Account>.00000000000000000001>
116   . set b [Account new {balance 1000}]
117   <reference.<Account>.00000000000000000002>
118   . $a get balance
119   0
120   . $b get balance
121   1000
123 DECLARING METHODS
124 -----------------
125 In addition to the predefined methods, new methods may be decared, or existing
126 methods redefined with the class method, method.
128 Declaring a method is very similar to defining a proc, and the arglist
129 has identical syntax. For example:
131   . Account method show {{channel stdout}} { $channel puts "Balance of account is $balance" }
132   . $b show
133   Balance of account is 1000
135 All instance variables are available within the method and any
136 changes to these variables are maintained by the object.
138 In addition, the $self variables is defined and refers to the current object.
139 This may be used to invoke further methods on the object. For example:
141   . Account method show {} { puts "Balance of account is [$self get balance]" }
142   . $b show
143   Balance of account is 1000
145 Notes:
146 * It is a bad idea to unset an instance variable.
147 * In general, you should avoid redefining any of the pre-defined methods, except for 'destroy'.
148 * When accessing the caller's scope with upvar or uplevel, note that there
149   are two frame levels between the caller and the method. Thus it is necessary
150   to use 'upvar 2' or 'uplevel 2'
152 INHERITANCE
153 -----------
154 For each base class given in a new class declaration, the methods
155 and variables of those classes are imported into the new class being
156 defined. Base classes are imported in left to right order, so that if a
157 method is defined in more than one base class, the later definition
158 is selected. This applies similarly to class variables.
160 Within a method, 'super' may be used to explicitly invoke a
161 base class method on the object. This applies only to the *last*
162 base class given. For example:
164   # Assumes the existence of classes Account and Client
165   . Account method debit {amount} { incr balance -$amount }
166   . class CreditAccount {Client Account} {type visa}
167   CreditAccount
168   . CreditAccount method debit {amount} {
169     puts "Debit $type card"
170         super debit $amount
171   }
172   . set a [CreditAccount]
173   <reference.<Account>.00000000000000000001>
174   . $a debit 20
175   Debit visa card
176   . $a balance
177   -20
179 In the CreditAccount debit method, the call to 'super debit' invokes
180 the method 'Account debit' since Account is the last base class listed.
182 OBJECT LIFETIME/GARBAGE COLLECTION
183 ----------------------------------
184 Objects are implemented as lambdas. That is, they are procedures with state
185 and are named as references. This means that when an object is no longer
186 reachable by any name and garbage collection runs, the object will be
187 discarded and the destructor will be invoked. Note that the garbage collector
188 can be invoked manually with 'collect' if required.
190   . class Account {}
191   Account
192   . Account method destroy {} { puts dying...; rename $self "" }
193   Account destroy
194   . proc a {} { set b [Account]; return "" }
195   a
196   . a
197   . collect
198   dying...
199   1
201 CLASS METHODS/CLASS STATIC VARIABLES
202 ------------------------------------
203 All methods defined with 'method' operate on objects (instances).
204 If a class method is required, it is possible to simply declare one with 'proc'.
205 The method dispatcher will automatically be able to dispatch to this method.
206 Using this approach, it is also possible to add class static variables by
207 defining static variables to the proc. Although strictly these variables
208 are accessible only to that proc, not the class as a whole.
210 For example:
212   . class Account {}
213   Account
214   . proc {Account nextid} {} {{id 0}} { incr id }
215   Account nextid
216   . Account nextid
217   1
218   . Account nextid
219   2
220   . set a [Account]
221   <reference.<Account>.00000000000000000001>
222   . $a nextid
223   3
224   . $a eval { $self nextid }
225   4
227 HOW METHOD DISPATCH WORKS
228 -------------------------
229 All class and object methods are name "classname methodname".
231 The class method dispatcher is named "classname". When invoked with a methodname,
232 it simply invokes the method "classname methodname".
234 The method dispatch is via a two step process. Firstly the object procedure is invoked
235 with the method name. This procedure then invokes "classname method" which sets up
236 the appropriate access to the object variables, and then invokes the method body.
238 EXAMPLES
239 --------
240 tree.tcl
241 ~~~~~~~~
242 The 'tree' package is implemented using the 'oo' package.
243 See the source code in tree.tcl and a usage example in tests/tree.test
245 Of particular note is how callbacks and recursive invocation is used in the 'walk' method.
247 examples/ootest.tcl
248 ~~~~~~~~~~~~~~~~~~~
249 A comprehensive OO example is provided in examples/ootest.tcl.
251 It can be run simply as:
253   ./jimsh examples/ootest.tcl