1 /*
2 * Copyright (C) 1997-2004, Michael Jennings
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a copy
5 * of this software and associated documentation files (the "Software"), to
6 * deal in the Software without restriction, including without limitation the
7 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8 * sell copies of the Software, and to permit persons to whom the Software is
9 * furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies of the Software, its documentation and marketing & publicity
13 * materials, and acknowledgment shall be given in the documentation, materials
14 * and software packages that this Software was used.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
20 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 */
23
24 #ifndef _LIBAST_OBJ_H_
25 #define _LIBAST_OBJ_H_
26
27
28 /**
29 * @file obj.h
30 * LibAST Object Infrastructure -- Generic Objects
31 *
32 * This file contains macros and type definitions for creating and
33 * manipulating basic generic objects.
34 *
35 * @author Michael Jennings <mej@eterm.org>
36 * $Revision: 1.30 $
37 * $Date: 2004/12/15 00:00:21 $
38 */
39
40 /*@{*/
41 /**
42 * @name Object Definition and Declaration Macros
43 * ---
44 *
45 * This set of macros is intended to abstract certain details about
46 * the internal workings of objects and greatly simplify their
47 * definition. The results have been known to cause non-cpp-compliant
48 * parsers to have the occasional fit, but they work. :-)
49 *
50 * @ingroup DOXGRP_OBJ
51 */
52
53 /**
54 * Declare an object structure.
55 *
56 * This macro abstracts the actual name of the object structure to
57 * help prevent its direct use. Obviously the translation is plainly
58 * visible, so those sufficiently determined to do it the Wrong Way
59 * still can. This macro is not used directly, but rather as part of
60 * the SPIF_DECL_OBJ() macro (see below), which is in turn used to
61 * define object types.
62 *
63 * @param t The object type as a non-quoted string (e.g., obj).
64 * @return The @c struct keyword followed by the structure name for
65 * the specified object type.
66 *
67 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DECL_OBJ(), SPIF_DECL_TYPE()
68 */
69 #define SPIF_DECL_OBJ_STRUCT(t) struct spif_ ## t ## _t_struct
70
71 /**
72 * Declare an object type based on the structure definition immediately
73 * following.
74 *
75 * This macro simplifies the creation of a new class by adding the
76 * appropriate @c typedef along with introducing the structure
77 * definition. Although use of this macro presents a bit of an
78 * unnatural parsing problem for non-cpp-aware tools (e.g., indent),
79 * its use is recommended for encapsulation purposes. Invocation of
80 * this macro should be immediately followed by an open brace ('{')
81 * and a normal C-style structure definition.
82 *
83 * @param t The object type as a non-quoted string (e.g., obj).
84 * @return An appropriate @c typedef and @c struct introducer.
85 *
86 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DECL_TYPE(), SPIF_DECL_OBJ_STRUCT()
87 */
88 #define SPIF_DECL_OBJ(t) SPIF_DECL_TYPE(t, SPIF_DECL_OBJ_STRUCT(t)); SPIF_DECL_OBJ_STRUCT(t)
89 /**
90 * Declare the parent type of an object being defined.
91 *
92 * This macro is used to declare that a particular object type (e.g.,
93 * obj) is the parent type of an object which is being defined via
94 * SPIF_DECL_OBJ(). The call to this macro should @em immediately
95 * follow the opening brace (which, in turn, immediately follows the
96 * call to SPIF_DECL_OBJ()). Declaring the parent type allows for
97 * safe typecasting of any object of the current type to its parent
98 * type (or any parent type in its "family tree"). At minimum, any
99 * true object must at @em least be derived from the @c obj type so
100 * that it can be safely cast to a generic object.
101 *
102 * @param t The object type as a non-quoted string (e.g., obj).
103 *
104 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_CONST_TYPE()
105 */
106 #define SPIF_DECL_PARENT_TYPE(t) SPIF_CONST_TYPE(t) parent
107
108 /**
109 * Declare the class variable for objects of a given type.
110 *
111 * Every object type has a class variable which is declared using this
112 * macro. Any instance of that type of object contains a pointer to
113 * this same class variable. This class variable is both declared and
114 * referenced using this macro so that its actual name is abstracted.
115 *
116 * @param type The object type as a non-quoted string (e.g., obj).
117 * @return The class variable for the given type.
118 *
119 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink
120 */
121 #define SPIF_CLASS_VAR(type) spif_ ## type ## _class
122
123 /**
124 * Declare a "property" of an object.
125 *
126 * This macro is used when declaring a class to specify that a
127 * particular class object is a "property." A "property" is an object
128 * member which has public get/set methods of the same name.
129 *
130 * @param type The type of the property variable.
131 * @param name The name of the property.
132 *
133 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink
134 */
135 #define SPIF_DECL_PROPERTY(type, name) SPIF_TYPE(type) name
136
137 /**
138 * Declare a "property" of an object.
139 *
140 * This macro is identical to SPIF_DECL_PROPERTY(), except that a
141 * native C type is used.
142 *
143 * @param type The C type of the property variable.
144 * @param name The name of the property.
145 *
146 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DECL_PROPERTY()
147 */
148 #define SPIF_DECL_PROPERTY_C(type, name) type name
149
150 /**
151 * Declare the get/set methods of a "property" of an object.
152 *
153 * This macro is used to prototype the get/set methods of an object
154 * property.
155 *
156 * @param otype The type of the object.
157 * @param vtype The type of the property variable.
158 * @param name The name of the property.
159 *
160 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink
161 */
162 #define SPIF_DECL_PROPERTY_FUNC(otype, vtype, name) \
163 SPIF_TYPE(vtype) spif_ ## otype ## _get_ ## name (SPIF_TYPE(otype)); \
164 SPIF_TYPE(bool) spif_ ## otype ## _set_ ## name (SPIF_TYPE(otype), SPIF_TYPE(vtype))
165
166 /**
167 * Declare the get/set methods of a "property" of an object.
168 *
169 * This macro is identical to SPIF_DECL_PROPERTY_FUNC(), except that a
170 * native C type is used.
171 *
172 * @param otype The type of the object.
173 * @param vtype The C type of the property variable.
174 * @param name The name of the property.
175 *
176 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DECL_PROPERTY_FUNC()
177 */
178 #define SPIF_DECL_PROPERTY_FUNC_C(otype, vtype, name) \
179 vtype spif_ ## otype ## _get_ ## name (SPIF_TYPE(otype)); \
180 SPIF_TYPE(bool) spif_ ## otype ## _set_ ## name (SPIF_TYPE(otype), vtype)
181
182 /**
183 * Define the get/set methods of a "property" of an object.
184 *
185 * This macro is used to define (i.e., create, i.e. insert the code
186 * for) the get/set methods of an object property.
187 *
188 * @param otype The type of the object.
189 * @param vtype The type of the property variable.
190 * @param name The name of the property.
191 *
192 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink
193 */
194 #define SPIF_DEFINE_PROPERTY_FUNC(otype, vtype, name) \
195 SPIF_TYPE(vtype) spif_ ## otype ## _get_ ## name (SPIF_TYPE(otype) self) \
196 { return (self->name); } \
197 SPIF_TYPE(bool) spif_ ## otype ## _set_ ## name (SPIF_TYPE(otype) self, SPIF_TYPE(vtype) new_ ## name) \
198 { \
199 if (!SPIF_OBJ_ISNULL(self->name)) { \
200 SPIF_OBJ_DEL(self->name); \
201 } \
202 self->name = new_ ## name; \
203 return TRUE; \
204 }
205
206 /**
207 * Define the get/set methods of a "property" of an object.
208 *
209 * This macro is identical to SPIF_DEFINE_PROPERTY_FUNC(), except that
210 * the property is treated as a non-object (i.e., its current value is
211 * not checked, so no destructor is called for the current value).
212 * Use this for spif_*_t types that are not objects, such as
213 * spif_int32_t and spif_sockport_t.
214 *
215 * @param otype The type of the object.
216 * @param vtype The type of the property variable.
217 * @param name The name of the property.
218 *
219 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DEFINE_PROPERTY_FUNC()
220 */
221 #define SPIF_DEFINE_PROPERTY_FUNC_NONOBJ(otype, vtype, name) \
222 SPIF_TYPE(vtype) spif_ ## otype ## _get_ ## name (SPIF_TYPE(otype) self) \
223 { return (self->name); } \
224 SPIF_TYPE(bool) spif_ ## otype ## _set_ ## name (SPIF_TYPE(otype) self, SPIF_TYPE(vtype) new_ ## name) \
225 { \
226 self->name = new_ ## name; \
227 return TRUE; \
228 }
229
230 /**
231 * Define the get/set methods of a "property" of an object.
232 *
233 * This macro is identical to SPIF_DEFINE_PROPERTY_FUNC(), except that
234 * a native C type is used.
235 *
236 * @param otype The type of the object.
237 * @param vtype The C type of the property variable.
238 * @param name The name of the property.
239 *
240 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_DEFINE_PROPERTY_FUNC()
241 */
242 #define SPIF_DEFINE_PROPERTY_FUNC_C(otype, vtype, name) \
243 vtype spif_ ## otype ## _get_ ## name (SPIF_TYPE(otype) self) \
244 { return (self->name); } \
245 SPIF_TYPE(bool) spif_ ## otype ## _set_ ## name (SPIF_TYPE(otype) self, vtype new_ ## name) \
246 { \
247 self->name = new_ ## name; \
248 return TRUE; \
249 }
250 /*@}*/
251
252 /*@{*/
253 /**
254 * @name Generic Object/Class Casting Macros
255 * ---
256 *
257 * This set of macros allows objects of any type (i.e., any object
258 * descended from the basic "obj" or "class" type) to be treated as
259 * generic object/class variables. In other words, as long as an
260 * object is properly defined (i.e., properly descended from its basic
261 * type), it can be treated as that basic type via use of these
262 * macros. The end result is that any operation which is defined for
263 * all objects can be executed on an object of any type without the
264 * need to know its exact type.
265 *
266 * @ingroup DOXGRP_OBJ
267 */
268
269 /**
270 * Cast an arbitrary class object to the generic class type.
271 *
272 * Most non-interface classes use the generic obj-style class
273 * variable, containing only the basic methods (create, delete,
274 * compare, etc.) that every object needs. However, interface classes
275 * require the use of more specific class objects with support for
276 * additional object methods. This macro allows an arbitrary class
277 * object, be it the generic class type or a decendent thereof, to be
278 * cast to the generic class type. This allows basic method calls to
279 * be performed on complex types by treating them as simple objects.
280 *
281 * @param cls An arbitrary class object.
282 * @return The class object cast to the generic type.
283 *
284 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_CLASS(), SPIF_CAST()
285 */
286 #define SPIF_CLASS(cls) (SPIF_CAST(class) (cls))
287
288 /**
289 * Cast an arbitrary class object to a const generic class type.
290 *
291 * This macro is equivalent to SPIF_CLASS(), except that the resulting
292 * object is a @c const object.
293 *
294 * @param cls An arbitrary class object.
295 * @return The class object cast to the generic type.
296 *
297 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_CLASS(), SPIF_CONST_CAST()
298 */
299 #define SPIF_CONST_CLASS(cls) (SPIF_CONST_CAST(class) (cls))
300
301 /**
302 * Cast an arbitrary object to an obj.
303 *
304 * This macro allows an arbitrary object of any valid object type
305 * (i.e., anything derived from spif_obj_t) to be treated as a generic
306 * object (the spif_obj_t type). Any method defined for generic
307 * objects (i.e., all objects) can be called on any object using a
308 * typecast such as this, and any function or macro which needs an
309 * arbitrary object can be passed any object using this macro.
310 *
311 * @param o An object of any valid type.
312 * @return A generic object reference to that object.
313 *
314 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_CAST()
315 */
316 #define SPIF_OBJ(o) (SPIF_CAST(obj) (o))
317 /*@}*/
318
319 /*@{*/
320 /**
321 * @name Generic Object Type Safety Macros
322 * ---
323 *
324 * Macros in this group are used to verify the validity of an object
325 * instance and its type.
326 *
327 * @ingroup DOXGRP_OBJ
328 */
329
330 /**
331 * Determine if an arbitrary object is of type "obj."
332 *
333 * This macro returns a boolean value based on whether or not the
334 * object passed to it is of type "obj." Obviously, this will almost
335 * never been the case, since the actual obj type is too generic to be
336 * useful for anything other than a parent class. However, each
337 * object type needs to define a macro like this named
338 * SPIF_OBJ_IS_xxx() (where xxx is the object type), so this macro
339 * serves as a template for how those should be written.
340 *
341 * This type-verification class for each object type should always be
342 * defined as this one is -- simply a wrapper around
343 * SPIF_OBJ_IS_TYPE().
344 *
345 * @param o The object to test.
346 * @return Whether or not the object is of type "obj."
347 *
348 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_IS_TYPE()
349 */
350 #define SPIF_OBJ_IS_OBJ(o) (SPIF_OBJ_IS_TYPE(o, obj))
351
352 /**
353 * Determine if an object of type "obj" is NULL.
354 *
355 * This macro returns a boolean value based on whether or not the
356 * object passed to it is NULL. The object is cast to type "obj"
357 * before the comparison, so it should work for any valid object.
358 * This macro will not often be used by user code. However, each
359 * object type needs to define a macro like this named
360 * SPIF_xxx_ISNULL() (where xxx is the object type), so this macro
361 * serves as a template for how those should be written.
362 *
363 * @param o The object to test.
364 * @return Whether or not the object is NULL.
365 *
366 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ(), SPIF_NULL_TYPE()
367 */
368 #define SPIF_OBJ_ISNULL(o) (SPIF_OBJ(o) == SPIF_NULL_TYPE(obj))
369
370 /**
371 * Determine if an object is of a given type.
372 *
373 * This macro returns a boolean value based on whether or not the
374 * given object, @a o, is of type @a type. It provides the driving
375 * force behind all SPIF_OBJ_IS_xxx()-style macros. Unlike the
376 * SPIF_OBJ_CHECK_TYPE() macro, this macro will @em always verify the
377 * object type. If you need a debugging assertion instead, use
378 * SPIF_OBJ_CHECK_TYPE(), as it will resolve to @c (1) in
379 * non-debugging code.
380 *
381 * @param o The object to test.
382 * @param type The type to check for.
383 * @return Whether or not @a o is of type @a type.
384 *
385 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_ISNULL(), SPIF_OBJ_CLASS(),
386 * SPIF_CLASS_VAR(), SPIF_OBJ_CHECK_TYPE()
387 */
388 #define SPIF_OBJ_IS_TYPE(o, type) ((!SPIF_OBJ_ISNULL(o)) && (SPIF_OBJ_CLASS(o) == SPIF_CLASS(SPIF_CLASS_VAR(type))))
389
390 /**
391 * Provide debugging assertion that an object is of a given type.
392 *
393 * This macro returns a boolean value based on whether or not the
394 * given object, @a o, is of type @a type. It is intended for
395 * situations where the test only needs to be performed in debugging
396 * code. If DEBUG is 0, it will resolve to @c (1). If DEBUG is
397 * between 1 and 4 inclusive, it will simply be a NULL check. Higher
398 * debug levels will treat it just like SPIF_OBJ_IS_TYPE().
399 *
400 * @param o The object to test.
401 * @param type The type to check for.
402 * @return Whether or not @a o is of type @a type.
403 *
404 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_ISNULL(), SPIF_OBJ_IS_TYPE()
405 */
406 #if DEBUG == 0
407 # define SPIF_OBJ_CHECK_TYPE(o, type) (1)
408 #elif DEBUG <= 4
409 # define SPIF_OBJ_CHECK_TYPE(o, type) (!SPIF_OBJ_ISNULL(o))
410 #else
411 # define SPIF_OBJ_CHECK_TYPE(o, type) SPIF_OBJ_IS_TYPE(o, type)
412 #endif
413 /*@}*/
414
415 /*@{*/
416 /**
417 * @name Generic Object Instance Macros
418 * ---
419 *
420 * This set of macros manipulates actual object instances in various
421 * ways. They can be used on any object.
422 *
423 * @ingroup DOXGRP_OBJ
424 */
425
426 /**
427 * Access the class for a given object.
428 *
429 * Every object has a member variable that references its class.
430 * There is a single class object for each individual object type, and
431 * all instances of that type reference the same class object. If you
432 * know the type of an object, you can use SPIF_CLASS_VAR() to access
433 * its class object (i.e., the class object for that type). However,
434 * this macro can be used to access the class object of @em any
435 * object, regardless of whether or not you know its type.
436 *
437 * @note This macro returns an object of type spif_class_t, so only
438 * methods common to all objects can be called using this macro.
439 * Other class types should define their own SPIF_xxx_CLASS() macro to
440 * access methods specific to that class.
441 *
442 * @param obj An object of arbitrary/unknown type.
443 * @return The class object for the given object.
444 *
445 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_CLASS(), SPIF_OBJ()
446 */
447 #define SPIF_OBJ_CLASS(obj) (SPIF_CLASS(SPIF_OBJ(obj)->cls))
448
449 /**
450 * Obtain the string representation of an object's class name.
451 *
452 * This macro will access the classname for an object. The classname
453 * will be enclosed in exclamation marks ('!') so as to help identify
454 * its origin. It is most often used as the return value for the
455 * @c type method of a given object type.
456 *
457 * @param obj An object of arbitrary/unknown type.
458 * @return The class name (as a spif_classname_t) for the given
459 * object.
460 *
461 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_CLASS()
462 */
463 #define SPIF_OBJ_CLASSNAME(obj) (SPIF_CAST(classname) SPIF_OBJ_CLASS(obj))
464
465 /**
466 * Call the named method for a given object.
467 *
468 * The methods which can be called on a given object are defined by
469 * that object's class. Since all objects are derived from
470 * spif_obj_t, and all classes are derived from spif_class_t (the
471 * class type for "obj"), the methods defined by spif_class_t can be
472 * called on any arbitrary object, regardless of its actual
473 * object/class types. This macro provides the mechanism by which
474 * this is done.
475 *
476 * @note This macro should not be called directly. It is used by the
477 * SPIF_OBJ_*() macros and as a template for interface classes.
478 *
479 * @param obj An object of arbitrary/unknown type.
480 * @param meth The name of the method to call.
481 * @return A pointer to the specified method for that object.
482 *
483 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_CLASS()
484 */
485 #define SPIF_OBJ_CALL_METHOD(obj, meth) SPIF_OBJ_CLASS(obj)->meth
486
487 /**
488 * Create an instance of a generic object.
489 *
490 * This macro allocates and returns an object of type "obj." Almost
491 * never used, but it's here for demonstration purposes anyway.
492 *
493 * @return An allocated object of type "obj."
494 *
495 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_new()
496 */
497 #define SPIF_OBJ_NEW() SPIF_CAST(obj) (SPIF_CLASS(SPIF_CLASS_VAR(obj)))->(noo)()
498
499 /**
500 * Initialize an object.
501 *
502 * This macro calls the @c init method of an object in order to
503 * initialize it.
504 *
505 * @param o An already-allocated object.
506 * @return #TRUE if successful, #FALSE otherwise.
507 *
508 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_init()
509 */
510 #define SPIF_OBJ_INIT(o) SPIF_CAST(bool) (SPIF_OBJ_CALL_METHOD((o), init)(o))
511
512 /**
513 * Clean up an object.
514 *
515 * This macro calls the @c done method of an object. This basically
516 * restores it to its original allocated-and-initialized state.
517 *
518 * @param o An object.
519 * @return #TRUE if successful, #FALSE otherwise.
520 *
521 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_done()
522 */
523 #define SPIF_OBJ_DONE(o) SPIF_CAST(bool) (SPIF_OBJ_CALL_METHOD((o), done)(o))
524
525 /**
526 * Delete an object.
527 *
528 * This macro calls the @c del method of an object, destroying it and
529 * freeing its memory.
530 *
531 * @param o An object. It will cease to exist after this call.
532 * @return #TRUE if successful, #FALSE otherwise.
533 *
534 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_del()
535 */
536 #define SPIF_OBJ_DEL(o) SPIF_CAST(bool) (SPIF_OBJ_CALL_METHOD((o), del)(o))
537
538 /**
539 * Convert the contents of an object to a string.
540 *
541 * This macro calls the @c show method of an object, returning a
542 * spif_str_t object containing its string representation.
543 *
544 * @param o The object to display.
545 * @param b An existing spif_str_t buffer to use. If NULL, a new str
546 * object will be created and returned.
547 * @param i Number of leading spaces to indent.
548 * @return A str object containing the string representation of @a o.
549 *
550 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_show(), SPIF_SHOW()
551 */
552 #define SPIF_OBJ_SHOW(o, b, i) SPIF_CAST(str) (SPIF_OBJ_CALL_METHOD((o), show)(o, #o, b, i))
553
554 /**
555 * Compare two objects.
556 *
557 * This macro calls the @c comp method of object #1 to compare the two
558 * objects.
559 *
560 * @param o1 Object #1.
561 * @param o2 Object #2.
562 * @return A spif_cmp_t value containing the comparison result.
563 *
564 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_comp(), spif_comp_t
565 */
566 #define SPIF_OBJ_COMP(o1, o2) SPIF_CAST(cmp) (SPIF_OBJ_CALL_METHOD((o1), comp)(o1, o2))
567
568 /**
569 * Duplicate an object.
570 *
571 * This macro calls the @c dup method of an object. A copy of the
572 * object is returned.
573 *
574 * @param o An object.
575 * @return A duplicate of that object.
576 *
577 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_dup()
578 */
579 #define SPIF_OBJ_DUP(o) SPIF_CAST(obj) (SPIF_OBJ_CALL_METHOD((o), dup)(o))
580
581 /**
582 * Obtain the type of the object.
583 *
584 * This macro calls the @c type method of an object to obtain its
585 * classname.
586 *
587 * @param o An object.
588 * @return The classname of that object.
589 *
590 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_type(), SPIF_OBJ_CLASSNAME()
591 */
592 #define SPIF_OBJ_TYPE(o) SPIF_CAST(classname) (SPIF_OBJ_CALL_METHOD((o), type)(o))
593 /*@}*/
594
595
596 /*@{*/
597 /**
598 * @name Object Display Convenience Macros
599 * ---
600 *
601 * This set of macros simplifies the process of displaying (as a
602 * string) the contents of an object. They can be used on any object.
603 *
604 * @ingroup DOXGRP_OBJ
605 */
606
607 /**
608 * Convenience macro for displaying an object.
609 *
610 * This macro provides an easy way to output the string
611 * representation of an object to a given file descriptor. The macro
612 * itself handles the creation and deletion of the temporary @c str
613 * object required (hence the "convenience").
614 *
615 * @param o The object to display.
616 * @param fd The file descriptor to display it on.
617 *
618 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_show()
619 */
620 #define SPIF_SHOW(o, fd) do { \
621 spif_str_t tmp__; \
622 tmp__ = SPIF_OBJ_SHOW(o, SPIF_NULL_TYPE(str), 0); \
623 fprintf(fd, "%s", SPIF_STR_STR(tmp__)); \
624 spif_str_del(tmp__); \
625 } while (0)
626
627 /**
628 * Convenience macro for displaying a NULL value for an object.
629 *
630 * Obviously, one cannot invoke the @c show method of a NULL object.
631 * This macro exists to provide a uniform way for object @c show
632 * methods to easily (and uniformly) display NULL objects.
633 *
634 * @param t The type of the NULL object.
635 * @param n The name of the NULL object (variable name).
636 * @param b A str object to which to assign the result.
637 * @param i Number of spaces to indent.
638 * @param tmp A char[] buffer of fixed size used for temporary
639 * storage.
640 *
641 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_show()
642 */
643 #define SPIF_OBJ_SHOW_NULL(t, n, b, i, tmp) do { \
644 memset(tmp, ' ', (i)); \
645 snprintf(SPIF_CAST_C(char *) tmp + (i), sizeof(tmp) - (i), \
646 "(spif_" #t "_t) %s: " SPIF_NULLSTR_TYPE(t) "\n", \
647 NONULL(n)); \
648 if (SPIF_STR_ISNULL(b)) { \
649 (b) = spif_str_new_from_ptr(SPIF_CAST(charptr) tmp); \
650 } else { \
651 spif_str_append_from_ptr((b), SPIF_CAST(charptr) tmp); \
652 } \
653 } while (0)
654
655 /**
656 * Convenience macro for handling NULL objects in a comparison.
657 *
658 * This macro exists because I got tired of typing the same thing over
659 * and over again to handle comparisons where either object may be
660 * NULL. You should have this at the start of all of your *_comp()
661 * functions.
662 *
663 * @param s The "self" (first) object.
664 * @param o The "other" (second) object.
665 *
666 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, spif_obj_comp()
667 */
668 #define SPIF_OBJ_COMP_CHECK_NULL(s, o) do { \
669 if (SPIF_OBJ_ISNULL((s)) && SPIF_OBJ_ISNULL((o))) { \
670 return SPIF_CMP_EQUAL; \
671 } else if (SPIF_OBJ_ISNULL((s))) { \
672 return SPIF_CMP_LESS; \
673 } else if (SPIF_OBJ_ISNULL((o))) { \
674 return SPIF_CMP_GREATER; \
675 } \
676 } while (0)
677 /*@}*/
678
679
680 /*@{*/
681 /**
682 * @name Basic Object Class Definitions
683 * ---
684 *
685 * These types form the foundation of the LibAST object hierarchy.
686 *
687 * @ingroup DOXGRP_OBJ
688 */
689
690 /**
691 * Object class structure.
692 *
693 * This class contains the object class structure. It contains the
694 * string representation of the class name followed by a series of
695 * function pointers to the member functions for the class. The basic
696 * class type contains methods that all objects require. The
697 * structure members should not be accessed directly, but rather via
698 * the appropriate macros.
699 *
700 * @note Doxygen doesn't understand how to handle the macro-based
701 * class definition for this structure, so it thinks it's a function.
702 * It's actually a struct definition (spif_const_class_t) and a
703 * pointer definition (spif_class_t) as provided by the
704 * SPIF_DEFINE_OBJ() macro.
705 *
706 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink, SPIF_OBJ_CALL_METHOD()
707 */
SPIF_DECL_OBJ(class)708 SPIF_DECL_OBJ(class) {
709 /** Text representation of class name. */
710 spif_classname_t classname;
711
712 spif_func_t noo;
713 spif_func_t init;
714 spif_func_t done;
715 spif_func_t del;
716 spif_func_t show;
717 spif_func_t comp;
718 spif_func_t dup;
719 spif_func_t type;
720 };
721
722 /* An obj is the most basic object type. It contains simply a pointer to
723 the class name (a const char * so you can test it with ==). */
724
725 /**
726 * Generic object structure.
727 *
728 * The @c obj type is the parent of all other object types. Since it
729 * doesn't actually store any data, the only member of the @c obj
730 * type is its spif_class_t
731 *
732 * @note Doxygen doesn't understand how to handle the macro-based
733 * class definition for this structure, so it thinks it's a function.
734 * It's actually a struct definition (spif_const_obj_t) and a pointer
735 * definition (spif_obj_t) as provided by the SPIF_DEFINE_OBJ()
736 * macro.
737 *
738 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink
739 */
SPIF_DECL_OBJ(obj)740 SPIF_DECL_OBJ(obj) {
741 spif_class_t cls;
742 };
743 /*@}*/
744
745
746
747 /* We need typedef's from here... */
748 #include <libast/str.h>
749
750 extern spif_class_t SPIF_CLASS_VAR(obj);
751 extern spif_obj_t spif_obj_new(void);
752 extern spif_bool_t spif_obj_del(spif_obj_t);
753 extern spif_bool_t spif_obj_init(spif_obj_t);
754 extern spif_bool_t spif_obj_done(spif_obj_t);
755 extern spif_class_t spif_obj_get_class(spif_obj_t);
756 extern spif_bool_t spif_obj_set_class(spif_obj_t, spif_class_t);
757 extern spif_str_t spif_obj_show(spif_obj_t, spif_charptr_t, spif_str_t, size_t);
758 extern spif_cmp_t spif_obj_comp(spif_obj_t, spif_obj_t);
759 extern spif_obj_t spif_obj_dup(spif_obj_t);
760 extern spif_classname_t spif_obj_type(spif_obj_t);
761
762 #endif /* _LIBAST_OBJ_H_ */
763