mingw/gettext/libtextstyle/gnulib-local/lib/moo.h - kiwivm - Git at Google

 /* Minimal object-oriented facilities for C.
    Copyright (C) 2006 Free Software Foundation, Inc.
    Written by Bruno Haible <bruno@clisp.org>, 2006.

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation; either version 2.1 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */

 /* This file defines minimal facilities for object-oriented programming
    style in ANSI C.

    The facilities allow to define classes with single inheritance and
    "virtual" methods.

    Strict type checking is provided in combination with a C++ compiler:
    The code compiles in ANSI C with less strict type checking; when
    compiled with a C++ compiler, strict type checking is done.

    In contrast to [OOC] and [OOPC], this implementation concentrates on the
    bare essentials of an object-oriented programming style.  It does not
    provide features that are "sometimes useful", but not essential.

    Features:
      - Combination of fields and methods into a single object.      YES
      - Description of objects of same shape and same behaviour
        by a class.                                                  YES
      - Single inheritance.                                          YES
      - Multiple inheritance.                                        NO
      - Operator overloading (compile-time polymorphism).            NO
      - Virtual methods (run-time polymorphism).                     YES
      - Information hiding: private/protected/public.         private fields
      - Static fields and methods.                                   NO
      - Constructors, destructors.                                   NO
      - 'new', 'delete'.                                             NO
      - Exception handling.                                          NO
      - Garbage collection.                                          NO
      - Templates / Generic classes with parameters.                 NO
      - Namespaces.                                                  NO
      - Hidden 'this' pointer in methods.                            NO
      - Declaring or implementing several classes in the same file.  NO

    Rationale for NO:
      - Multiple inheritance is not supported because programming languages
        like Java and C# prove that they are not necessary. Modern design
        patterns use delegation more often than composition; this reduces
        the pressure to use multiple inheritance.
        Multiple inheritance of "interfaces" (classes without fields) might
        be considered, though.
      - Operator overloading is not essential: The programmer can rename
        methods so that they carry unambiguous method names. This also makes
        the code more readable.
      - Virtual methods are supported. Non-virtual methods are not: they
        constitute an assumption about the possible subclasses which is more
        often wrong than right. In other words, non-virtual methods are a
        premature optimization - "the root of all evil", according to
        Donald E. Knuth.
      - Information hiding: 'protected' is not supported because it is always
        inappropriate: it prohibits the use of the delegation design pattern.
        'private' is implemented on fields. There are no 'public' fields,
        since the use of getters/setters allows for overriding in subclasses
        and is more maintainable (ability to set breakpoints). On the other
        hand, all methods are 'public'. 'private` methods are not supported
        because methods with static linkage can be used instead.
      - Static fields and methods are not supported because normal variables
        and functions with static or extern linkage can be used instead.
      - Constructors and destructors are not supported.  The programmer can
        define 'init' and 'do_free' methods himself.
      - 'new', 'delete' are not supported because they only provide the
        grouping of two lines of code into a single line of code.
      - Exception handling is not supported because conventions with a return
        code can be used instead.
      - Garbage collection is not supported. Without it the programmer's life
        is harder, but not impossible. The programmer has to think about
        ownership of objects.
      - Templates / Generic classes with parameters are not supported because
        they are mostly used for container classes, and container classes can
        be implemented in a simpler object-oriented way that requires only a
        very limited form of class inheritance.
      - Namespaces are not implemented, because they can be simulated by a
        consistent naming convention.
      - A hidden 'this' pointer in methods is not implemented. It reduces the
        transparency of the code (because what looks like a variable access can
        be an access through 'this') and is simply not needed.
      - Declaring or implementing several classes in the same file is not
        supported, because it is anyway good practice to define each class in
        its own .oo.h / .oo.c file.

    Syntax:

    The syntax resembles C++, but deviates from C++ where the C++ syntax is
    just too braindead.

    A root class is declared in a .oo.h file:

      struct rootfoo
      {
      methods:
        int method1 (rootfoo_t x, ...); ...
      };

    and in the corresponding .oo.c file:

      struct rootfoo
      {
      fields:
        int field1; ...
      };

    A subclass is declared in a .oo.h file as well:

      struct subclass : struct rootfoo
      {
      methods:
        int method2 (subclass_t x, ...); ...
      };

    and in the corresponding .oo.c file:

      struct subclass : struct rootfoo
      {
      fields:
        int field2; ...
      };

    This defines:
      - An incomplete type 'struct any_rootfoo_representation' or
        'struct subclass_representation', respectively. It denotes the memory
        occupied by an object of the respective class. The prefix 'any_' is
        present only for a root class.
      - A type 'rootfoo_t' or 'subclass_t' that is equivalent to a pointer
        'struct any_rootfoo_representation *' or
        'struct subclass_representation *', respectively.
      - A type 'struct rootfoo_implementation' or
        'struct subclass_implementation', respectively. It contains a virtual
        function table for the corresponding type.
      - A type 'struct rootfoo_representation_header' or
        'struct subclass_representation_header', respectively, that defines
        the part of the memory representation containing the virtual function
        table pointer.
      - Functions 'rootfoo_method1 (rootfoo_t x, ...);' ...
                  'subclass_method1 (subclass_t x, ...);' ...
                  'subclass_method2 (subclass_t x, ...);' ...
        that invoke the corresponding methods. They are realized as inline
        functions if possible.
      - A declaration of 'rootfoo_typeinfo' or 'subclass_typeinfo', respectively,
        each being a typeinfo_t instance.
      - A declaration of 'ROOTFOO_SUPERCLASSES' or 'SUBCLASS_SUPERCLASSES',
        respectively, each being an initializer for an array of typeinfo_t.
      - A declaration of 'ROOTFOO_SUPERCLASSES_LENGTH' or
        'SUBCLASS_SUPERCLASSES_LENGTH', respectively, each denoting the length
        of that initializer.
      - A declaration of 'rootfoo_vtable' or 'subclass_vtable', respectively,
        being an instance of 'struct rootfoo_implementation' or
        'struct subclass_implementation', respectively.
      - A header file "rootfoo.priv.h" or "subclass.priv.h" that defines the
        private fields of 'struct rootfoo_representation' or
        'struct subclass_representation', respectively.

    A class implementation looks like this, in a .oo.c file:

      struct subclass : struct rootfoo
      {
      fields:
        int field2; ...
      };

      int subclass::method1 (subclass_t x, ...) { ... } [optional]
      int subclass::method2 (subclass_t x, ...) { ... }
      ...

    At the place of the second "struct subclass" definition, the type
    'struct subclass_representation' is expanded, and the macro 'super' is
    defined, referring to the vtable of the superclass. For root classes,
    'super' is not defined. Also, 'subclass_typeinfo' is defined.

    Each method subclass::method_i defines the implementation of a method
    for the particular class. Its C name is subclass__method_i (not to be
    confused with subclass_method_i, which is the externally visible function
    that invokes this method).

    Methods that are not defined implicitly inherited from the superclass.

    At the end of the file, 'subclass_vtable' is defined, as well as
      'subclass_method1 (subclass_t x, ...);' ...
      'subclass_method2 (subclass_t x, ...);' ...
    if they were not already defined as inline functions in the header file.

    Object representation in memory:
      - Objects have as their first field, called 'vtable', a pointer to a table
        to data and function pointers that depend only on the class, not on the
        object instance.
      - One of the first fields of the vtable is a pointer to the
        'superclasses'; this is a NULL-terminated array of pointers to
        typeinfo_t objects, starting with the class itself, then its
        superclass etc.


    [OOC] Axel-Tobias Schreiner: Object-oriented programming with ANSI-C. 1993.

    [OOPC] Laurent Deniau: Object Oriented Programming in C. 2001.

  */

 #ifndef _MOO_H
 #define _MOO_H

 /* Get size_t, abort().  */
 #include <stdlib.h>

 /* An object of this type is defined for each class.  */
 typedef struct
 {
   const char *classname;
 } typeinfo_t;

 /* IS_INSTANCE (OBJ, ROOTCLASSNAME, CLASSNAME)
    tests whether an object is instance of a given class, given as lower case
    class name.  */
 #define IS_INSTANCE(obj,rootclassname,classname) \
   (((const struct rootclassname##_representation_header *)(const struct any_##rootclassname##_representation *)(obj))->vtable->superclasses_length \
    >= classname##_SUPERCLASSES_LENGTH \
    && ((const struct rootclassname##_representation_header *)(const struct any_##rootclassname##_representation *)(obj))->vtable->superclasses \
       [((const struct rootclassname##_representation_header *)(const struct any_##rootclassname##_representation *)(obj))->vtable->superclasses_length \
        - classname##_SUPERCLASSES_LENGTH] \
       == & classname##_typeinfo)
 /* This instance test consists of two comparisons.  One could even optimize
    this to a single comparison, by limiting the inheritance depth to a fixed
    limit, for example, say, depth <= 10.  The superclasses list would then
    need to be stored in reverse order, from the root down to the class itself,
    and be filled up with NULLs so that the array has length 10.  The instance
    test would look like this:
      #define IS_INSTANCE(obj,rootclassname,classname) \
        (((const struct rootclassname##_representation_header *)(const struct any_##rootclassname##_representation *)(obj))->vtable->superclasses \
         [classname##_SUPERCLASSES_LENGTH - 1] \
         == & classname##_typeinfo)
    but the classname##_superclasses_length would no longer be available as a
    simple sizeof expression.  */

 #endif /* _MOO_H */
	/* Minimal object-oriented facilities for C.
	Copyright (C) 2006 Free Software Foundation, Inc.
	Written by Bruno Haible <bruno@clisp.org>, 2006.

	This program is free software: you can redistribute it and/or modify
	it under the terms of the GNU Lesser General Public License as published by
	the Free Software Foundation; either version 2.1 of the License, or
	(at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	GNU Lesser General Public License for more details.

	You should have received a copy of the GNU Lesser General Public License
	along with this program. If not, see <https://www.gnu.org/licenses/>. */

	/* This file defines minimal facilities for object-oriented programming
	style in ANSI C.

	The facilities allow to define classes with single inheritance and
	"virtual" methods.

	Strict type checking is provided in combination with a C++ compiler:
	The code compiles in ANSI C with less strict type checking; when
	compiled with a C++ compiler, strict type checking is done.

	In contrast to [OOC] and [OOPC], this implementation concentrates on the
	bare essentials of an object-oriented programming style. It does not
	provide features that are "sometimes useful", but not essential.

	Features:
	- Combination of fields and methods into a single object. YES
	- Description of objects of same shape and same behaviour
	by a class. YES
	- Single inheritance. YES
	- Multiple inheritance. NO
	- Operator overloading (compile-time polymorphism). NO
	- Virtual methods (run-time polymorphism). YES
	- Information hiding: private/protected/public. private fields
	- Static fields and methods. NO
	- Constructors, destructors. NO
	- 'new', 'delete'. NO
	- Exception handling. NO
	- Garbage collection. NO
	- Templates / Generic classes with parameters. NO
	- Namespaces. NO
	- Hidden 'this' pointer in methods. NO
	- Declaring or implementing several classes in the same file. NO

	Rationale for NO:
	- Multiple inheritance is not supported because programming languages
	like Java and C# prove that they are not necessary. Modern design
	patterns use delegation more often than composition; this reduces
	the pressure to use multiple inheritance.
	Multiple inheritance of "interfaces" (classes without fields) might
	be considered, though.
	- Operator overloading is not essential: The programmer can rename
	methods so that they carry unambiguous method names. This also makes
	the code more readable.
	- Virtual methods are supported. Non-virtual methods are not: they
	constitute an assumption about the possible subclasses which is more
	often wrong than right. In other words, non-virtual methods are a
	premature optimization - "the root of all evil", according to
	Donald E. Knuth.
	- Information hiding: 'protected' is not supported because it is always
	inappropriate: it prohibits the use of the delegation design pattern.
	'private' is implemented on fields. There are no 'public' fields,
	since the use of getters/setters allows for overriding in subclasses
	and is more maintainable (ability to set breakpoints). On the other
	hand, all methods are 'public'. 'private` methods are not supported
	because methods with static linkage can be used instead.
	- Static fields and methods are not supported because normal variables
	and functions with static or extern linkage can be used instead.
	- Constructors and destructors are not supported. The programmer can
	define 'init' and 'do_free' methods himself.
	- 'new', 'delete' are not supported because they only provide the
	grouping of two lines of code into a single line of code.
	- Exception handling is not supported because conventions with a return
	code can be used instead.
	- Garbage collection is not supported. Without it the programmer's life
	is harder, but not impossible. The programmer has to think about
	ownership of objects.
	- Templates / Generic classes with parameters are not supported because
	they are mostly used for container classes, and container classes can
	be implemented in a simpler object-oriented way that requires only a
	very limited form of class inheritance.
	- Namespaces are not implemented, because they can be simulated by a
	consistent naming convention.
	- A hidden 'this' pointer in methods is not implemented. It reduces the
	transparency of the code (because what looks like a variable access can
	be an access through 'this') and is simply not needed.
	- Declaring or implementing several classes in the same file is not
	supported, because it is anyway good practice to define each class in
	its own .oo.h / .oo.c file.

	Syntax:

	The syntax resembles C++, but deviates from C++ where the C++ syntax is
	just too braindead.

	A root class is declared in a .oo.h file:

	struct rootfoo
	{
	methods:
	int method1 (rootfoo_t x, ...); ...
	};

	and in the corresponding .oo.c file:

	struct rootfoo
	{
	fields:
	int field1; ...
	};

	A subclass is declared in a .oo.h file as well:

	struct subclass : struct rootfoo
	{
	methods:
	int method2 (subclass_t x, ...); ...
	};

	and in the corresponding .oo.c file:

	struct subclass : struct rootfoo
	{
	fields:
	int field2; ...
	};

	This defines:
	- An incomplete type 'struct any_rootfoo_representation' or
	'struct subclass_representation', respectively. It denotes the memory
	occupied by an object of the respective class. The prefix 'any_' is
	present only for a root class.
	- A type 'rootfoo_t' or 'subclass_t' that is equivalent to a pointer
	'struct any_rootfoo_representation *' or
	'struct subclass_representation *', respectively.
	- A type 'struct rootfoo_implementation' or
	'struct subclass_implementation', respectively. It contains a virtual
	function table for the corresponding type.
	- A type 'struct rootfoo_representation_header' or
	'struct subclass_representation_header', respectively, that defines
	the part of the memory representation containing the virtual function
	table pointer.
	- Functions 'rootfoo_method1 (rootfoo_t x, ...);' ...
	'subclass_method1 (subclass_t x, ...);' ...
	'subclass_method2 (subclass_t x, ...);' ...
	that invoke the corresponding methods. They are realized as inline
	functions if possible.
	- A declaration of 'rootfoo_typeinfo' or 'subclass_typeinfo', respectively,
	each being a typeinfo_t instance.
	- A declaration of 'ROOTFOO_SUPERCLASSES' or 'SUBCLASS_SUPERCLASSES',
	respectively, each being an initializer for an array of typeinfo_t.
	- A declaration of 'ROOTFOO_SUPERCLASSES_LENGTH' or
	'SUBCLASS_SUPERCLASSES_LENGTH', respectively, each denoting the length
	of that initializer.
	- A declaration of 'rootfoo_vtable' or 'subclass_vtable', respectively,
	being an instance of 'struct rootfoo_implementation' or
	'struct subclass_implementation', respectively.
	- A header file "rootfoo.priv.h" or "subclass.priv.h" that defines the
	private fields of 'struct rootfoo_representation' or
	'struct subclass_representation', respectively.

	A class implementation looks like this, in a .oo.c file:

	struct subclass : struct rootfoo
	{
	fields:
	int field2; ...
	};

	int subclass::method1 (subclass_t x, ...) { ... } [optional]
	int subclass::method2 (subclass_t x, ...) { ... }
	...

	At the place of the second "struct subclass" definition, the type
	'struct subclass_representation' is expanded, and the macro 'super' is
	defined, referring to the vtable of the superclass. For root classes,
	'super' is not defined. Also, 'subclass_typeinfo' is defined.

	Each method subclass::method_i defines the implementation of a method
	for the particular class. Its C name is subclass__method_i (not to be
	confused with subclass_method_i, which is the externally visible function
	that invokes this method).

	Methods that are not defined implicitly inherited from the superclass.

	At the end of the file, 'subclass_vtable' is defined, as well as
	'subclass_method1 (subclass_t x, ...);' ...
	'subclass_method2 (subclass_t x, ...);' ...
	if they were not already defined as inline functions in the header file.

	Object representation in memory:
	- Objects have as their first field, called 'vtable', a pointer to a table
	to data and function pointers that depend only on the class, not on the
	object instance.
	- One of the first fields of the vtable is a pointer to the
	'superclasses'; this is a NULL-terminated array of pointers to
	typeinfo_t objects, starting with the class itself, then its
	superclass etc.


	[OOC] Axel-Tobias Schreiner: Object-oriented programming with ANSI-C. 1993.

	[OOPC] Laurent Deniau: Object Oriented Programming in C. 2001.

	*/

	#ifndef _MOO_H
	#define _MOO_H

	/* Get size_t, abort(). */
	#include <stdlib.h>

	/* An object of this type is defined for each class. */
	typedef struct
	{
	const char *classname;
	} typeinfo_t;

	/* IS_INSTANCE (OBJ, ROOTCLASSNAME, CLASSNAME)
	tests whether an object is instance of a given class, given as lower case
	class name. */
	#define IS_INSTANCE(obj,rootclassname,classname) \
	(((const struct rootclassname##_representation_header )(const struct any_##rootclassname##_representation )(obj))->vtable->superclasses_length \
	>= classname##_SUPERCLASSES_LENGTH \
	&& ((const struct rootclassname##_representation_header )(const struct any_##rootclassname##_representation )(obj))->vtable->superclasses \
	[((const struct rootclassname##_representation_header )(const struct any_##rootclassname##_representation )(obj))->vtable->superclasses_length \
	- classname##_SUPERCLASSES_LENGTH] \
	== & classname##_typeinfo)
	/* This instance test consists of two comparisons. One could even optimize
	this to a single comparison, by limiting the inheritance depth to a fixed
	limit, for example, say, depth <= 10. The superclasses list would then
	need to be stored in reverse order, from the root down to the class itself,
	and be filled up with NULLs so that the array has length 10. The instance
	test would look like this:
	#define IS_INSTANCE(obj,rootclassname,classname) \
	(((const struct rootclassname##_representation_header )(const struct any_##rootclassname##_representation )(obj))->vtable->superclasses \
	[classname##_SUPERCLASSES_LENGTH - 1] \
	== & classname##_typeinfo)
	but the classname##_superclasses_length would no longer be available as a
	simple sizeof expression. */

	#endif /* _MOO_H */