3
<title>critcl::class - C Runtime In Tcl (CriTcl)</title>
4
<style type="text/css"><!--
17
DIV.doctools H1,DIV.doctools H2 {
22
font-family: sans-serif;
25
background: transparent;
45
UL.toc,UL.toc UL, UL.toc UL UL {
46
font: normal 12pt/14pt sans-serif;
49
LI.section, LI.subsection {
57
font-family: monospace;
61
padding-bottom: 0.5ex;
69
border: 1px solid black;
71
UL.requirements LI, UL.syntax LI {
80
border: 1px solid black;
87
border-top: 1px solid black;
91
border-bottom: 1px solid black;
95
<! -- Generated from file '/home/aku/Projects/Packages/Critcl/dev-master/embedded/www/files/critcl_class.html' by tcllib/doctools with format 'html'
97
<! -- Copyright © 2011-2012 Andreas Kupries
99
<! -- CVS: $Id$ critcl::class.n
101
<body><div class="doctools">
103
<a href="../toc.html">Table Of Contents</a>
104
| <a href="../index.html">Keyword Index</a>
106
<h1 class="title">critcl::class(n) 1.0.6 doc "C Runtime In Tcl (CriTcl)"</h1>
107
<div id="name" class="section"><h2><a name="name">Name</a></h2>
108
<p>critcl::class - CriTcl Utilities: C Classes</p>
110
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
112
<li class="section"><a href="#toc">Table Of Contents</a></li>
113
<li class="section"><a href="#synopsis">Synopsis</a></li>
114
<li class="section"><a href="#section1">Description</a></li>
115
<li class="section"><a href="#section2">API</a></li>
116
<li class="section"><a href="#section3">Class Specification API</a>
118
<li class="subsection"><a href="#subsection1">General configuration</a></li>
119
<li class="subsection"><a href="#subsection2">Class lifetime management</a></li>
120
<li class="subsection"><a href="#subsection3">Instance lifetime management</a></li>
121
<li class="subsection"><a href="#subsection4">Class variables and methods</a></li>
122
<li class="subsection"><a href="#subsection5">Instance variables and methods</a></li>
123
<li class="subsection"><a href="#subsection6">Context dependent interactions</a></li>
126
<li class="section"><a href="#section4">Example</a></li>
127
<li class="section"><a href="#section5">Authors</a></li>
128
<li class="section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
129
<li class="section"><a href="#keywords">Keywords</a></li>
130
<li class="section"><a href="#category">Category</a></li>
131
<li class="section"><a href="#copyright">Copyright</a></li>
134
<div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
135
<div class="synopsis">
136
<ul class="requirements">
137
<li>package require <b class="pkgname">Tcl 8.4</b></li>
138
<li>package require <b class="pkgname">critcl <span class="opt">?3.1.6?</span></b></li>
139
<li>package require <b class="pkgname">critcl::class <span class="opt">?1.0.6?</span></b></li>
142
<li><a href="#1"><b class="cmd">::critcl::class::define</b> <i class="arg">name</i> <i class="arg">script</i></a></li>
143
<li><a href="#2"><b class="cmd">include</b> <i class="arg">path</i></a></li>
144
<li><a href="#3"><b class="cmd">support</b> <i class="arg">code</i></a></li>
145
<li><a href="#4"><b class="cmd">type</b> <i class="arg">name</i></a></li>
146
<li><a href="#5"><b class="cmd">classconstructor</b> <i class="arg">body</i></a></li>
147
<li><a href="#6"><b class="cmd">classdestructor</b> <i class="arg">body</i></a></li>
148
<li><a href="#7"><b class="cmd">constructor</b> <i class="arg">body</i> <span class="opt">?<i class="arg">postbody</i>?</span></a></li>
149
<li><a href="#8"><b class="cmd">destructor</b> <i class="arg">body</i></a></li>
150
<li><a href="#9"><b class="cmd">classvariable</b> <i class="arg">ctype</i> <i class="arg">name</i> <span class="opt">?<i class="arg">comment</i>?</span> <span class="opt">?<i class="arg">constructor</i>?</span> <span class="opt">?<i class="arg">destructor</i>?</span></a></li>
151
<li><a href="#10"><b class="cmd">classmethod</b> <i class="arg">name</i> <b class="method">command</b> <i class="arg">arguments</i> <i class="arg">body</i></a></li>
152
<li><a href="#11"><b class="cmd">classmethod</b> <i class="arg">name</i> <b class="method">proc</b> <i class="arg">arguments</i> <i class="arg">resulttype</i> <i class="arg">body</i></a></li>
153
<li><a href="#12"><b class="cmd">classmethod</b> <i class="arg">name</i> <b class="method">as</b> <i class="arg">funname</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
154
<li><a href="#13"><b class="cmd">insvariable</b> <i class="arg">ctype</i> <i class="arg">name</i> <span class="opt">?<i class="arg">comment</i>?</span> <span class="opt">?<i class="arg">constructor</i>?</span> <span class="opt">?<i class="arg">destructor</i>?</span></a></li>
155
<li><a href="#14"><b class="cmd">method</b> <i class="arg">name</i> <b class="method">command</b> <i class="arg">arguments</i> <i class="arg">body</i></a></li>
156
<li><a href="#15"><b class="cmd">method</b> <i class="arg">name</i> <b class="method">proc</b> <i class="arg">arguments</i> <i class="arg">resulttype</i> <i class="arg">body</i></a></li>
157
<li><a href="#16"><b class="cmd">method</b> <i class="arg">name</i> <b class="method">as</b> <i class="arg">funname</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
158
<li><a href="#17"><b class="cmd">method_introspection</b></a></li>
162
<div id="section1" class="section"><h2><a name="section1">Description</a></h2>
163
<p>Welcome to the <i class="term">C Runtime In Tcl</i>, <i class="term"><a href="critcl_pkg.html">CriTcl</a></i> for short, a
164
system to build C extension packages for Tcl on the fly, from C code
165
embedded within Tcl scripts, for all who wish to make their code go
167
<p>This document is the reference manpage for the <b class="package">critcl::class</b>
168
package. This package provides convenience commands for advanced
169
functionality built on top of the core.</p>
170
<p>With it a user wishing to create a C level object with class
171
and instance commands can concentrate on specifying the class- and
172
instance-variables and -methods in a manner similar to a TclOO class,
173
while all the necessary boilerplate around it is managed by this
175
<p>Its intended audience are mainly developers wishing to write
176
Tcl packages with embedded C code.</p>
177
<p>This package resides in the Core Package Layer of CriTcl.</p>
178
<p><img alt="arch_core" src="../image/arch_core.png"></p>
180
<div id="section2" class="section"><h2><a name="section2">API</a></h2>
181
<dl class="definitions">
182
<dt><a name="1"><b class="cmd">::critcl::class::define</b> <i class="arg">name</i> <i class="arg">script</i></a></dt>
183
<dd><p>This is the main command to define a new class <i class="arg">name</i>, where
184
<i class="arg">name</i> is the name of the Tcl command representing the class,
185
i.e. the <i class="term">class command</i>. The <i class="arg">script</i> provides the
186
specification of the class, i.e. information about included headers,
187
class- and instance variables, class- and instance-methods, etc.
188
See the section <span class="sectref"><a href="#section3">Class Specification API</a></span> below for the
189
detailed list of the available commands and their semantics.</p></dd>
192
<div id="section3" class="section"><h2><a name="section3">Class Specification API</a></h2>
193
<p>Here we documents all class specification commands available inside of
194
the class definition script argument of <b class="cmd">::critcl::class::define</b>.</p>
195
<div id="subsection1" class="subsection"><h3><a name="subsection1">General configuration</a></h3>
196
<dl class="definitions">
197
<dt><a name="2"><b class="cmd">include</b> <i class="arg">path</i></a></dt>
198
<dd><p>This command specifies the path of a header file to include within the
199
code generated for the class. This is separate from the <b class="cmd">support</b>
200
because the generated include directives will be put at the very
201
beginning of the generated code. This is done to allow the use of the
202
imported declarations within the instance type, and elsewhere.</p>
203
<p>The command can be used multiple times, each adding a header to
204
include. It is of course possible to not use this command at all, for
205
classing not making use of external definitions.</p>
206
<p>The result of the command is the empty string.</p></dd>
207
<dt><a name="3"><b class="cmd">support</b> <i class="arg">code</i></a></dt>
208
<dd><p>This command specifies supporting C code, i.e. any definitions (types,
209
functions, etc.) needed by the <em>whole</em> class and not fitting into
210
class- and instance-methods. The code is embedded at global level,
211
outside of any function or other definition.</p>
212
<p>The command can be used multiple times, each adding another
213
segment of C code to insert. It is of course possible to not use this
214
command at all, for classes not requiring swupporting code.</p>
215
<p>The result of the command is the empty string.</p></dd>
216
<dt><a name="4"><b class="cmd">type</b> <i class="arg">name</i></a></dt>
217
<dd><p>This command specifies the name of an external C type to be used as
218
the type of the instance structure.</p>
219
<p>Initialization and release of the structure with the given type
220
are the responsibility of the user, through <b class="cmd">constructor</b> and
221
<b class="cmd">destructor</b> code fragments.</p>
222
<p><em>Attention:</em> Using this command precludes the use of
223
regular class- and instance variables. It further precludes the use of
224
<b class="cmd">method-introspection</b> as well, as this make use of generated
225
instance-variables.</p>
226
<p>If class- and/or instance-variable have to be used in
227
conjunction with an external C type, simply create and use a class- or
228
instance-variable with that type.</p>
229
<p>The result of the command is the empty string.</p></dd>
232
<div id="subsection2" class="subsection"><h3><a name="subsection2">Class lifetime management</a></h3>
233
<dl class="definitions">
234
<dt><a name="5"><b class="cmd">classconstructor</b> <i class="arg">body</i></a></dt>
235
<dd><p>This command specifies a C code block surrounding the initialization
236
of the class variables, i.e. the fields of the class structure.
237
<em>Note</em> that allocation and release of the class structure itself
238
is done by the system andf not the responsibility of the user.</p>
239
<p>For the initialization (and release) of a class variable it is
240
recommended to use the <i class="arg">constructor</i> and <i class="arg">destructor</i>
241
arguments of the variable's definition (See command
242
<b class="cmd">classvariable</b>) for this instead of using a separate
243
<b class="cmd">classconstructor</b>.</p>
244
<p>This is an optional command. Using it more than once is allowed
245
too and each use will add another C code fragment to use during
246
construction. I.e. multiple calls aggregate.</p>
247
<p>The C code blocks of multiple calls (including the constructors
248
of classvariable definitions) are executed in order of specification.</p>
249
<p>The result of the command is the empty string.</p>
250
<p>The C code in <i class="arg">body</i> has access to the following
252
<dl class="definitions">
253
<dt><b class="variable">interp</b></dt>
254
<dd><p>Pointer to the Tcl interpreter (Tcl_Interp*) the
255
class structure will be associated with. It enables the generation
256
of a Tcl error message should construction fail.</p></dd>
257
<dt><b class="variable">class</b></dt>
258
<dd><p>Pointer to the class structure to initialize.</p></dd>
260
<dd><p>A C code label the constructor can jump to should it have
261
to signal a construction failure. It is the responsibility of the
262
constructor to release any variables already initialized before
263
jumping to this label. This also why the 'execution in order of
264
specification' is documented and can be relied on. It gives us the
265
knowledge which other constructors have already been run and
266
initialized what other fields.</p></dd>
268
<dt><a name="6"><b class="cmd">classdestructor</b> <i class="arg">body</i></a></dt>
269
<dd><p>This command specifies a C code block surrounding the release of the
270
class variables, i.e. the fields of the class structure.
271
<em>Note</em> that allocation and release of the class structure itself
272
is done by the system and not the responsibility of the user.</p>
273
<p>For the initialization (and release) of a class variable it is
274
recommended to use the <i class="arg">constructor</i> and <i class="arg">destructor</i>
275
arguments of the variable's definition (See command
276
<b class="cmd">classvariable</b>) for this instead of using a separate
277
<b class="cmd">classconstructor</b>.</p>
278
<p>This is an optional command. Using it more than once is allowed
279
too and each use will add another C code fragment to use during
280
construction. I.e. multiple calls aggregate.</p>
281
<p>The C code blocks of multiple calls (including the constructors
282
of class variable definitions) are executed in order of specification.</p>
283
<p>The result of the command is the empty string.</p>
284
<p>The C code in <i class="arg">body</i> has access to the same
285
environment as the class constructor code blocks.</p></dd>
288
<div id="subsection3" class="subsection"><h3><a name="subsection3">Instance lifetime management</a></h3>
289
<dl class="definitions">
290
<dt><a name="7"><b class="cmd">constructor</b> <i class="arg">body</i> <span class="opt">?<i class="arg">postbody</i>?</span></a></dt>
291
<dd><p>This command specifies a C code block surrounding the initialization
292
of the instance variables, i.e. the fields of the instance structure.
293
<em>Note</em> that allocation and release of the instance structure
294
itself is done by the system and not the responsibility of the user.
295
<em>On the other hand</em>, if an external <b class="cmd">type</b> was specified
296
for the instance structure, then instance variables are not possible,
297
and the system has no knowledge of the type's structure. In that case
298
it is the responsibility of the <i class="arg">body</i> to allocate and free the
299
structure itself too.</p>
300
<p>For the initialization (and release) of an instance variable it
301
is recommended to use the <i class="arg">constructor</i> and <i class="arg">destructor</i>
302
arguments of the variable's definition (See command <b class="cmd">insvariable</b>)
303
for this instead of using a separate <b class="cmd">constructor</b>.</p>
304
<p>This is an optional command. Using it more than once is allowed
305
too and each use will add another C code fragment to use during
306
construction. I.e. multiple calls aggregate.</p>
307
<p>The C code blocks of multiple calls (including the constructors
308
of instance variable definitions) are executed in order of specification.</p>
309
<p>The result of the command is the empty string.</p>
310
<p>The C code in <i class="arg">body</i> has access to the following
312
<dl class="definitions">
313
<dt><b class="variable">interp</b></dt>
314
<dd><p>Pointer to the Tcl interpreter (Tcl_Interp*) the
315
instance structure will be associated with. It enables the generation
316
of a Tcl error message should construction fail.</p></dd>
317
<dt><b class="variable">instance</b></dt>
318
<dd><p>Pointer to the instance structure to initialize.</p></dd>
320
<dd><p>A C code label the constructor can jump to should it have
321
to signal a construction failure. It is the responsibility of the
322
constructor to release any variables already initialized before
323
jumping to this label. This also why the 'execution in order of
324
specification' is documented and can be relied on. It gives us the
325
knowledge which other constructors have already been run and
326
initialized what other fields.</p></dd>
328
<p>The C code in <i class="arg">postbody</i> is responsible construction action
329
to be done after the primary construction was done and the Tcl-level
330
instance command was successfully created. It has access to a slightly
331
different environment:</p>
332
<dl class="definitions">
333
<dt><b class="variable">interp</b></dt>
334
<dd><p>Pointer to the Tcl interpreter (Tcl_Interp*) the
335
instance structure will be associated with. It enables the generation
336
of a Tcl error message should construction fail.</p></dd>
337
<dt><b class="variable">instance</b></dt>
338
<dd><p>Pointer to the instance structure to initialize.</p></dd>
339
<dt><b class="variable">cmd</b></dt>
340
<dd><p>The Tcl_Command token of the Tcl-level instance
342
<dt><b class="variable">fqn</b></dt>
343
<dd><p>The fully qualified name of the instance command,
344
stored in a Tcl_Obj*.</p></dd>
346
<dt><a name="8"><b class="cmd">destructor</b> <i class="arg">body</i></a></dt>
347
<dd><p>This command specifies a C code block surrounding the release of the
348
instance variables, i.e. the fields of the instance structure.
349
<em>Note</em> that allocation and release of the instance structure
350
itself is done by the system and not the responsibility of the user.
351
<em>On the other hand</em>, if an external <b class="cmd">type</b> was specified
352
for the instance structure, then instance variables are not possible,
353
and the system has no knowledge of the type's structure. In that case
354
it is the responsibility of the <i class="arg">body</i> to allocate and free the
355
structure itself too.</p>
356
<p>For the initialization (and release) of an instance variable it
357
is recommended to use the <i class="arg">constructor</i> and <i class="arg">destructor</i>
358
arguments of the variable's definition (See command <b class="cmd">insvariable</b>)
359
for this instead of using a separate <b class="cmd">constructor</b>.</p>
360
<p>This is an optional command. Using it more than once is allowed
361
too and each use will add another C code fragment to use during
362
construction. I.e. multiple calls aggregate.</p>
363
<p>The C code blocks of multiple calls (including the constructors
364
of instance variable definitions) are executed in order of specification.</p>
365
<p>The result of the command is the empty string.</p>
366
<p>The C code in <i class="arg">body</i> has access to the following
368
<dl class="definitions">
369
<dt><b class="variable">instance</b></dt>
370
<dd><p>Pointer to the instance structure to release.</p></dd>
374
<div id="subsection4" class="subsection"><h3><a name="subsection4">Class variables and methods</a></h3>
375
<dl class="definitions">
376
<dt><a name="9"><b class="cmd">classvariable</b> <i class="arg">ctype</i> <i class="arg">name</i> <span class="opt">?<i class="arg">comment</i>?</span> <span class="opt">?<i class="arg">constructor</i>?</span> <span class="opt">?<i class="arg">destructor</i>?</span></a></dt>
377
<dd><p>This command specifies a field in the class structure of the class.
378
Multiple fields can be specified, and are saved in the order
380
<p><em>Attention:</em> Specification of a class variable precludes
381
the use of an external C <b class="cmd">type</b> for the instance structure.</p>
382
<p><em>Attention:</em> Specification of a class variable
383
automatically causes the definition of an instance variable named
384
<b class="const">class</b>, pointing to the class structure.</p>
385
<p>Beyond the basic <i class="arg">name</i> and C type of the new variable the
386
definition may also contain a <i class="arg">comment</i> describing it, and C code
387
blocks to initialize and release the variable.
388
These are effectively local forms of the commands
389
<b class="cmd">classconstructor</b> and <b class="cmd">classdestructor</b>. Please read their
390
descriptions for details regarding the C environment available to the
392
<p>The comment, if specified will be embedded into the generated C
393
code for easier cross-referencing from generated "<b class="file">.c</b>" file to
394
class specification.</p></dd>
395
<dt><a name="10"><b class="cmd">classmethod</b> <i class="arg">name</i> <b class="method">command</b> <i class="arg">arguments</i> <i class="arg">body</i></a></dt>
396
<dd><p>This command specifies a class method and the C code block
397
implementing its functionality. This is the first of three forms. The
398
method is specified like a <b class="cmd">critcl::ccommand</b>, with a fixed set of
399
C-level arguments. The <i class="arg">body</i> has to perform everything
400
(i.e. argument extraction, checking, result return, and of course the
401
actual functionality) by itself.</p>
402
<p>For this the <i class="arg">body</i> has access to</p>
403
<dl class="definitions">
404
<dt><b class="variable">class</b></dt>
405
<dd><p>Pointer to the class structure.</p></dd>
406
<dt><b class="variable">interp</b></dt>
407
<dd><p>Pointer to the Tcl interpreter (Tcl_Interp*) the
408
class structure is associated with</p></dd>
409
<dt><b class="variable">objc</b></dt>
410
<dd><p>The number of method arguments.</p></dd>
411
<dt><b class="variable">objv</b></dt>
412
<dd><p>The method arguments, as C array of Tcl_Obj pointers.</p></dd>
414
<p>The <i class="arg">arguments</i> of the definition are only a human readable form
415
of the method arguments and syntax and are not used in the C code,
416
except as comments put into the generated code. Again, it is the
417
responsibility of the <i class="arg">body</i> to check the number of arguments,
418
extract them, check their types, etc.</p></dd>
419
<dt><a name="11"><b class="cmd">classmethod</b> <i class="arg">name</i> <b class="method">proc</b> <i class="arg">arguments</i> <i class="arg">resulttype</i> <i class="arg">body</i></a></dt>
420
<dd><p>This command specifies a class method and the C code block
421
implementing its functionality. This is the second of three forms. The
422
method is specified like a <b class="cmd">critcl::cproc</b>.
423
Contrary to the first variant here the <i class="arg">arguments</i> are computer
424
readable, expected to be in the same format as the <i class="arg">arguments</i> of
425
<b class="cmd">critcl::cproc</b>. The same is true for the <i class="arg">resulttype</i>.
426
The system automatically generates a wrapper doing argument checking
427
and conversion, and result conversion, like for <b class="cmd">critcl::cproc</b>.</p>
428
<p>The <i class="arg">body</i> has access to</p>
429
<dl class="definitions">
430
<dt><b class="variable">class</b></dt>
431
<dd><p>Pointer to the class structure.</p></dd>
432
<dt><b class="variable">interp</b></dt>
433
<dd><p>Pointer to the Tcl interpreter (Tcl_Interp*) the
434
class structure is associated with</p></dd>
436
<dd><p>All <i class="arg">arguments</i> under their specified names and C types
437
as per their definition.</p></dd>
439
<dt><a name="12"><b class="cmd">classmethod</b> <i class="arg">name</i> <b class="method">as</b> <i class="arg">funname</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
440
<dd><p>This command specifies a class method and the C code block
441
implementing its functionality. This is the third and last of three
443
<p>The class method is implemented by the external function
444
<i class="arg">funname</i>, i.e. a function which is declared outside of the class
445
code itself, or in a <b class="cmd">support</b> block.</p>
446
<p>It is assumed that the first four arguments of that function
447
represent the parameters</p>
448
<dl class="definitions">
449
<dt><b class="variable">class</b></dt>
450
<dd><p>Pointer to the class structure.</p></dd>
451
<dt><b class="variable">interp</b></dt>
452
<dd><p>Pointer to the Tcl interpreter (Tcl_Interp*) the
453
class structure is associated with</p></dd>
454
<dt><b class="variable">objc</b></dt>
455
<dd><p>The number of method arguments.</p></dd>
456
<dt><b class="variable">objv</b></dt>
457
<dd><p>The method arguments, as C array of Tcl_Obj pointers.</p></dd>
459
<p>Any additional arguments specified will be added after these and are
460
passed into the C code as is, i.e. are considered to be C expressions.</p></dd>
463
<div id="subsection5" class="subsection"><h3><a name="subsection5">Instance variables and methods</a></h3>
464
<dl class="definitions">
465
<dt><a name="13"><b class="cmd">insvariable</b> <i class="arg">ctype</i> <i class="arg">name</i> <span class="opt">?<i class="arg">comment</i>?</span> <span class="opt">?<i class="arg">constructor</i>?</span> <span class="opt">?<i class="arg">destructor</i>?</span></a></dt>
466
<dd><p>This command specifies a field in the instance structure of the class.
467
Multiple fields can be specified, and are saved in the order
469
<p><em>Attention:</em> Specification of an instance variable
470
precludes the use of an external C <b class="cmd">type</b> for the instance
472
<p><em>Attention:</em> Specification of an instance variable
473
automatically causes the definition of an instance variable of type
474
<b class="const">Tcl_Command</b>, and named <b class="const">cmd</b>, holding the token of the
475
instance command, and the definition of an instance method named
476
<b class="const">destroy</b>. This implicit instance variable is managed by the
478
<p>Beyond the basic <i class="arg">name</i> and C type of the new variable the
479
definition may also contain a <i class="arg">comment</i> describing it, and C code
480
blocks to initialize and release the variable.
481
These are effectively local forms of the commands <b class="cmd">constructor</b>
482
and <b class="cmd">destructor</b>. Please read their descriptions for details
483
regarding the C environment available to the code.</p>
484
<p>The comment, if specified will be embedded into the generated C
485
code for easier cross-referencing from generated "<b class="file">.c</b>" file to
486
class specification.</p></dd>
487
<dt><a name="14"><b class="cmd">method</b> <i class="arg">name</i> <b class="method">command</b> <i class="arg">arguments</i> <i class="arg">body</i></a></dt>
488
<dd><p>This command specifies an instance method and the C code block
489
implementing its functionality. This is the first of three forms. The
490
method is specified like a <b class="cmd">critcl::ccommand</b>, with a fixed set of
491
C-level arguments. The <i class="arg">body</i> has to perform everything
492
(i.e. argument extraction, checking, result return, and of course the
493
actual functionality) by itself.</p>
494
<p>For this the <i class="arg">body</i> has access to</p>
495
<dl class="definitions">
496
<dt><b class="variable">instance</b></dt>
497
<dd><p>Pointer to the instance structure.</p></dd>
498
<dt><b class="variable">interp</b></dt>
499
<dd><p>Pointer to the Tcl interpreter (Tcl_Interp*) the
500
instance structure is associated with</p></dd>
501
<dt><b class="variable">objc</b></dt>
502
<dd><p>The number of method arguments.</p></dd>
503
<dt><b class="variable">objv</b></dt>
504
<dd><p>The method arguments, as C array of Tcl_Obj pointers.</p></dd>
506
<p>The <i class="arg">arguments</i> of the definition are only a human readable form
507
of the method arguments and syntax and are not used in the C code,
508
except as comments put into the generated code. Again, it is the
509
responsibility of the <i class="arg">body</i> to check the number of arguments,
510
extract them, check their types, etc.</p></dd>
511
<dt><a name="15"><b class="cmd">method</b> <i class="arg">name</i> <b class="method">proc</b> <i class="arg">arguments</i> <i class="arg">resulttype</i> <i class="arg">body</i></a></dt>
512
<dd><p>This command specifies an instance method and the C code block
513
implementing its functionality. This is the second of three
514
forms. The method is specified like a <b class="cmd">critcl::cproc</b>.
515
Contrary to the first variant here the <i class="arg">arguments</i> are computer
516
readable, expected to be in the same format as the <i class="arg">arguments</i> of
517
<b class="cmd">critcl::cproc</b>. The same is true for the <i class="arg">resulttype</i>.
518
The system automatically generates a wrapper doing argument checking
519
and conversion, and result conversion, like for <b class="cmd">critcl::cproc</b>.</p>
520
<p>The <i class="arg">body</i> has access to</p>
521
<dl class="definitions">
522
<dt><b class="variable">instance</b></dt>
523
<dd><p>Pointer to the instance structure.</p></dd>
524
<dt><b class="variable">interp</b></dt>
525
<dd><p>Pointer to the Tcl interpreter (Tcl_Interp*) the
526
instance structure is associated with</p></dd>
528
<dd><p>All <i class="arg">arguments</i> under their specified names and C types
529
as per their definition.</p></dd>
531
<dt><a name="16"><b class="cmd">method</b> <i class="arg">name</i> <b class="method">as</b> <i class="arg">funname</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
532
<dd><p>This command specifies an instance method and the C code block
533
implementing its functionality. This is the third and last of three
535
<p>The instance method is implemented by the external function
536
<i class="arg">funname</i>, i.e. a function which is declared outside of the instance
537
code itself, or in a <b class="cmd">support</b> block.</p>
538
<p>It is assumed that the first four arguments of that function
539
represent the parameters</p>
540
<dl class="definitions">
541
<dt><b class="variable">instance</b></dt>
542
<dd><p>Pointer to the instance structure.</p></dd>
543
<dt><b class="variable">interp</b></dt>
544
<dd><p>Pointer to the Tcl interpreter (Tcl_Interp*) the
545
instance structure is associated with</p></dd>
546
<dt><b class="variable">objc</b></dt>
547
<dd><p>The number of method arguments.</p></dd>
548
<dt><b class="variable">objv</b></dt>
549
<dd><p>The method arguments, as C array of Tcl_Obj pointers.</p></dd>
551
<p>Any additional arguments specified will be added after these and are
552
passed into the C code as is, i.e. are considered to be C expressions.</p></dd>
553
<dt><a name="17"><b class="cmd">method_introspection</b></a></dt>
554
<dd><p>This command generates one class- and one instance-method both of
555
which will return a list of the instance methods of the class, and
556
supporting structures, like the function to compute the information,
557
and a class variable caching it.</p>
558
<p>The two methods and the class variable are all named
559
<b class="const">methods</b>.</p></dd>
562
<div id="subsection6" class="subsection"><h3><a name="subsection6">Context dependent interactions</a></h3>
563
<p>This section documents the various interactions between the
564
specification commands. While these are are all documented with the
565
individual commands here they are pulled together to see at a glance.</p>
566
<ol class="enumerated">
567
<li><p>If you are using the command <b class="cmd">type</b> to specify an external
568
C type to use for the instance structure you are subject to
569
the following constraints and rules:</p>
570
<ol class="enumerated">
571
<li><p>You cannot define your own instance variables.</p></li>
572
<li><p>You cannot define your own class variables.</p></li>
573
<li><p>You cannot use <b class="cmd">method_introspection</b>.</p></li>
574
<li><p>You have to allocate and release the instance structure on your
575
own, through <b class="cmd">constructor</b> and <b class="cmd">destructor</b> code blocks.</p></li>
578
<li><p>If you declare class variables you are subject to the
579
following constraints and rules:</p>
580
<ol class="enumerated">
581
<li><p>You cannot use <b class="cmd">type</b>.</p></li>
582
<li><p>The system generates an instance variable <b class="const">class</b> for
583
you, which points from instance to class structure. This makes
584
you also subject to the rules below, for instance variables.</p></li>
587
<li><p>If you declare instance variables (possibly automatic, see
588
above) you are subject to following constraints and rules:</p>
589
<ol class="enumerated">
590
<li><p>You cannot use <b class="cmd">type</b>.</p></li>
591
<li><p>The system generates and manages an instance variable
592
<b class="const">cmd</b> for you, which holds the Tcl_Command token
593
of the instance command.</p></li>
594
<li><p>The system generates an instance method <b class="const">destroy</b> for
596
<li><p>The system manages allocation and release of the instance
597
structure for you. You have to care only about the instance
598
variables themselves.</p></li>
604
<div id="section4" class="section"><h2><a name="section4">Example</a></h2>
605
<p>The example shown below is the specification of queue data structure,
606
with most of the method implementations and support code omitted to
607
keep the size down.</p>
608
<p>The full implementation can be found in the directory
609
"<b class="file">examples/queue</b>" of the critcl source distribution/repository.</p>
610
<pre class="example">
611
package require Tcl 8.4
612
package require critcl 3.1
613
critcl::buildrequirement {
614
package require critcl::class ; # DSL, easy spec of Tcl class/object commands.
616
critcl::cheaders util.h
617
critcl::class::define ::queuec {
619
insvariable Tcl_Obj* unget {
620
List object unget elements
622
instance->unget = Tcl_NewListObj (0,NULL);
623
Tcl_IncrRefCount (instance->unget);
625
Tcl_DecrRefCount (instance->unget);
627
insvariable Tcl_Obj* queue {
628
List object holding the main queue
630
instance->queue = Tcl_NewListObj (0,NULL);
631
Tcl_IncrRefCount (instance->queue);
633
Tcl_DecrRefCount (instance->queue);
635
insvariable Tcl_Obj* append {
636
List object holding new elements
638
instance->append = Tcl_NewListObj (0,NULL);
639
Tcl_IncrRefCount (instance->append);
641
Tcl_DecrRefCount (instance->append);
644
Index of next element to return from the main queue
648
support {... queue_peekget, queue_size, etc.}
649
method clear {} {...}
651
method get as queue_peekget 1
652
method peek as queue_peekget 0
653
method put {item ...}
656
Tcl_WrongNumArgs (interp, 2, objv, NULL);
659
Tcl_SetObjResult (interp, Tcl_NewIntObj (queue_size (instance, NULL, NULL, NULL)));
662
method unget {item} {...}
664
package provide queuec 1
667
<div id="section5" class="section"><h2><a name="section5">Authors</a></h2>
668
<p>Andreas Kupries</p>
670
<div id="section6" class="section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
671
<p>This document, and the package it describes, will undoubtedly contain
672
bugs and other problems.
673
Please report such at <a href="https://github.com/andreas-kupries/critcl">https://github.com/andreas-kupries/critcl</a>.
674
Please also report any ideas for enhancements you may have for either
675
package and/or documentation.</p>
677
<div id="keywords" class="section"><h2><a name="keywords">Keywords</a></h2>
678
<p><a href="../index.html#key12">C class</a>, <a href="../index.html#key8">C code</a>, <a href="../index.html#key11">C instance</a>, <a href="../index.html#key13">C object</a>, <a href="../index.html#key3">Embedded C Code</a>, <a href="../index.html#key6">code generator</a>, <a href="../index.html#key0">compile & run</a>, <a href="../index.html#key10">compiler</a>, <a href="../index.html#key1">dynamic code generation</a>, <a href="../index.html#key2">dynamic compilation</a>, <a href="../index.html#key9">generate package</a>, <a href="../index.html#key4">linker</a>, <a href="../index.html#key5">on demand compilation</a>, <a href="../index.html#key7">on-the-fly compilation</a></p>
680
<div id="category" class="section"><h2><a name="category">Category</a></h2>
681
<p>Glueing/Embedded C code</p>
683
<div id="copyright" class="section"><h2><a name="copyright">Copyright</a></h2>
684
<p>Copyright © 2011-2012 Andreas Kupries</p>
added
removed
embedded/www/files/critcl_class.html
