===============================================================================
MMXX Header Macro Guide:
===============================================================================

MMXX Header File Structure
--------------------------
The following structure is merely indicative. The most peculiar requirements
for MMXX-compatible header files are that:

    1. They must be conditionalized on the value of the _MMXX_BREWING_ macro.
        Whenever _MMXX_BREWING_ is set to 1, they must:
            a. Be repeatedly includeable
            b. Not expose any content but a correctly structured set of MMXX_*
                macro expansions.

    2. The contents of class declarations not enveloped in macros (in
        particular, private method and private instance variable declarations)
        should be conditionalized on whether the class in question is being
        compiled as a shadow or as a real class. The most sensible way of doing
        this is to rely on the same flag macros that MMXX uses, namely
        _MMXX_SHADOW_<CLASSNAME>. The catch is that the flag macros themselves
        must be already available by the time the header is included. This is
        generally done by using one or more prefix files (prefixed to all
        compilation within the unit, such as by using gcc's -include option, or
        by MMXX's "artificial" include file, available by setting the
        _MMXX_prefix_ macro by a compiler command-line switch.) This is
        necessary to eliminate potential compiler and linker errors, to drop
        the space overhead for instance variables in shadow classes, and most
        importantly to avoid compile-time and runtime errors related to the
        presence of member objects.

Example:

/* "foo.h" BEFORE CONVERSION TO MMXX: -------------------------------------- */

    #ifndef __FOO__
    #define __FOO__ 1
    
    #ifndef __BAR__    /* header dependency */
    #include "bar.h"
    #endif

    class foo : public bar {
    public:
                            foo(int num);
        virtual             ~foo();

        void                SetNumber(int num);
        int                 GetNumber() const;
        virtual void        Recalculate();
        static const char * GetText();
        virtual int         GetCustomCode() = 0;
        /* This is a pure virtual method, which in C++ makes the class
           abstract. In MMXX, pure virtual methods appear to be regular virtual
           methods, because base classes can never be abstract as far as the
           compiler is concerned: since they can be subclassed in modules, the
           host must still be able to instantiate the base class. However, the
           methods are still "pure virtual" in that the runtime linker will
           refuse to instantiate a derived class if any required pure virtual
           methods in any of its base classes are not overridden. Note that
           pure virtual methods are very useful in MMXX because a design based
           on pure virtual methods can be faster than one based on regular
           virtual methods.
               Note that if a pure virtual method is not overridden in a
               derived class and it is NOT marked as required, instantiation
               will be possible. Calling the method will result in a no-op. If
               the method returns a result, 0 will be returned. Because of
               this, all result types returned by pure virtual methods must be
               castable from "0". The GetCustomCode() above satisfies this
               requirement since it returns "int". */ 
    protected:
        virtual void        PerformAction();
    private:
        /* in MMXX, all member variables are private - classes with protected
           or public member variables need reworking beforehand. Class "foo"
           in this example was already conforming. */
        int                 number;
        void                MyPrivateMethod();
        
        static const char * text;
    };
    
    #endif

/* "foo.h" AFTER CONVERSION TO MMXX: --------------------------------------- */
    
    #if !defined(__FOO__) || defined(_MMXX_BREWING_)
       /* make sure it can be included multiple times if _MMXX_BREWING_ is 1 */
    #define __FOO__ 1
    
    #ifndef _MMXX_BREWING_
        /* make sure we don't output anything but MMXX_* macros, or recurse to
           any other header, if we're brewing */
    
    #ifndef __BAR__     /* header dependency */
    #include "bar.h"
    #endif /* #ifndef __BAR__ */
    
    #include "mmxxapi.h"
        /* get the MMXX macro definitions that generate C++ declarations */
    
    #endif /* #ifndef _MMXX_BREWING_ */
    
    MMXX_CLASS_1_0(foo,public,bar)
        /* a base class must itself be declared with MMXX if it's public or
           protected, here we're assuming that bar.h is an MMXX header as
           well */
    
    MMXX_CONS_1(    Pub,    foo,Req,            1,(bar),            int,num)
    /* public: foo(int num);
       Note that constructors take the number and list of nonprivate
       superclasses in lieu of the method name, or 1,(bar) in this case */

    /* public: virtual ~foo();
       a virtual destructor is always automatically declared by MMXX */

    MMXX_METHOD_1(  Pub,    foo,Req,            SetNumber,          int,num)
    /* public: void SetNumber(int number); */

    MMXX_METHOD_0RC(Pub,    foo,Req,int,        GetNumber           )
    /* public: int GetNumber() const; */

    MMXX_METHOD_0(  PubV,   foo,Req,            Recalculate         )
    /* public: virtual void Recalculate(); 
       it's virtual, so it must be implemented as void foo::_I_Recalculate() */

    MMXX_STATIC_0R( Pub,    foo,Req,const char*,GetText             )
    /* public: static const char *GetText(); */
        
    MMXX_METHOD_0R( PubPV,  foo,Req,int,        GetCustomCode       )
    /* public: virtual int GetCustomCode() = 0;
       (note: pure virtual requires no _I_ prefix for the implementation) */
    
    MMXX_METHOD_0(  ProtV,  foo,Req,            PerformAction       )
    /* protected: virtual void PerformAction();
       it's virtual, it must be implemented as void foo::_I_PerformAction() */
    
    #if !defined(_MMXX_BREWING_) && defined(_MMXX_SHADOW_foo) && _MMXX_SHADOW_foo==0
    /* make sure we don't output any private declarations if we're brewing
       or if this is a shadow class */
    private:
        int                 number;
        void                MyPrivateMethod();

        static const char * text;
    #endif /* #if !defined(_MMXX_BREWING_) && defined(_MMXX_SHADOW_foo) &&
              _MMXX_SHADOW_foo==0 */
    
    MMXX_CLASS_END(foo)
    
    #endif /* #if !defined(__FOO__) || defined(_MMXX_BREWING_) */


Header Grammar v.1.0:
---------------------
In the following, a literal sequence of characters is enclosed in double
quotes, e.g. "identifier" (if the literal sequence contains double quotes, \ is
used to escape them.) If two tokens should be concatenated into one, they are
presented with no intervening whitespace in the grammar, (e.g.
'_MMXX_SHADOW_'<class_name> becomes _MMXX_SHADOW_foo in the case of class
"foo".) NL stands for the newline token. A token marked with a * suffix can be
repeated zero or more times (though the exact number of times it must be
repeated might be specified by its context.) If a line is not marked with a |
prefix, it represents a continuation of the rule on the previous line, whereas
if it is marked with a | prefix it represents an alternative to the previous
rule (the choice among alternatives might be specified by the context of the
token.) A token surrounded by square brackets is optional (its presence might
also be specified by its context.)

/* the following are simply indicative: */
<mmxx_header_file>          ::= <header_prelude>
                                <preparation_section>
                                <declaration_section>
                                <header_epilog>

<header_prelude>            ::= "#if !defined("<header_macro>") || defined(_MMXX_BREWING_)" NL
                                "#define "<header_macro>" 1" NL

<preparation_section>       ::= "#ifndef _MMXX_BREWING_" NL
                                <subinclusion_and_extras>
                                "#include \"mmxxapi.h\"" NL
                                "#endif" NL

<subinclusion_and_extras>   ::= header file preparation, including all needed
                                subinclusions of other headers and any other
                                declarations not otherwise supposed to be
                                enveloped in MMXX macros.

<header_macro>              ::= the convention is to translate the header file
                                name into a macro name by replacing all
                                punctuation marks into underscores, dropping
                                the .h suffix, converting to upper case, then
                                to prefix the result by two underscores and
                                to suffix it with two more, e.g. "Foo.h"
                                becomes __FOO__. At present this is only a
                                convention, but it might later become a
                                requirement.

<declaration_section>       ::= <declaration>*

<header_epilog>             ::= NL "#endif" NL

<conditionalized_class_section>
                            ::= "#if !defined(_MMXX_BREWING_) && defined(_MMXX_SHADOW_"<class_name>") && _MMXX_SHADOW_"<class_name>"==0" NL
                                    /* redundant <class_name>s */
                                <private_ivars_and_methods>
                                NL "#endif" NL

/* these are strictly required rather than merely indicative: */
<declaration>               ::=   <class_declaration>
                                | <forward_declaration>

<class_declaration>         ::= <begin_class_declaration>
                                <class_declaration_fragment>*
                                <end_class_declaration>

<class_declaration_fragment>::=   <class_declaration_item>
                                | <conditionalized_class_section>

<class_declaration_item>    ::=   <method_declaration>
                                | <constructor_declaration>
                                | <static_method_declaration>
                                | <member_enumeration_declaration>
                                | <member_structure_declaration>
                                | <static_initializer_declaration>

<forward_declaration>       ::=   <forward_class_declaration>

/* Class Declaration */

<begin_class_declaration>   ::= "MMXX_CLASS_"<num_nonprivate_supers>"_"<num_private_supers>
                                  "("
                                    <class_name>
                                    <nonprivate_super_spec>*
                                      /* quantity given by <num_nonprivate_supers> */
                                    <private_super_spec>*
                                      /* quantity given by <num_private_supers> */
                                  ")"
<num_nonprivate_supers>     ::= "0" .. "5"
<num_private_supers>        ::= "0" .. "5"
<nonprivate_super_spec>     ::= "," <class_access_spec> "," <superclass_name>
<class_access_spec>         ::=   "public"
                                | "protected"
<private_super_spec>        ::= "," <superclass_name>
<class_name>                ::= <identifier>
<superclass_name>           ::= <identifier>
<end_class_declaration>     ::= "MMXX_CLASS_END"<cct_marker><as_marker><exc_marker>
                                  "("
                                    <class_name>
                                    [ "," <op_access_spec> ] /* iff <cct_marker> is "_CCT" */
                                    [ "," <op_access_spec> ]  /* iff <as_marker> is "_AS" */
                                  ")"
<cct_marker>                ::=          /* empty iff copy constructor not provided */
                                | "_CCT" /* iff copy constructor provided */
<as_marker>                 ::=          /* empty iff copy assignment oper not provided */
                                | "_AS"  /* iff copy assignment operator provided */
<exc_marker>                ::=          /* empty iff class is not an exception class */
                                | "_EXC" /* iff class is an exception class */
                                         /* (must publicly derive from MMXXException) */
<op_access_spec>           ::=    "public"
                                | "protected"
                                | "private"

/* Method Declaration */

<method_declaration>        ::= <method_or_oper><num_method_parameters><result_decl><const_decl><throw_decl>
                                  "("
                                    <method_type_spec>
                                    "," <class_name>
                                      /* redundant, must match name of class being declared */
                                    "," <extra_flags>
                                    [ "," <result_type> ]
                                      /* iff <result_decl> is "R" */
                                    "," <method_name_spec>
                                    <method_parameter_spec>*
                                      /* quantity given by <num_method_parameters> */
                                  ")"
<method_or_oper>            ::=   "MMXX_METHOD_"
                                | "MMXX_OPER_"
<num_method_parameters>     ::= "0" .. "10"
<result_decl>               ::=            /* empty iff method returns void */
                                | "R"      /* "R" iff method returns a result */
<const_decl>                ::=            /* empty iff method is not "const" */
                                | "C"      /* "C" iff method is "const" */
<throw_decl>                ::=            /* empty iff method can throw exceptions */
                                | "N"      /* "N" iff method can't throw exceptions */
<method_type_spec>          ::=   "Pub"    /* public non-virtual method */
                                | "Prot"   /* protected non-virtual method */
                                | "PubV"   /* public virtual method */
                                | "ProtV"  /* protected virtual method */
                                | "PubPV"  /* public pure virtual method */
                                | "ProtPV" /* protected pure virtual method */
<extra_flags>               ::=   "None"   /* no flags */
                                | "Req"    /* iff method/ctor/static is required */
<method_name_spec>          ::=   <method_name>         /* iff a regular method */
                                | <alphabetized_oper>   /* iff an operator */
<method_name>               ::= <identifier>
<alphabetized_oper>         ::=   "eq" | "ne" | "add" | "sub" | "mult" | "div" | "l" | "g" | "le" | "ge"
                                | "and" | "or" | "not" | "bit_and" | "bit_or" | "bit_not" | "xor"
                                | "ls" | "rs" | "mod" | "add_a" | "sub_a" | "mult_a" | "div_a"
                                | "bit_and_a" | "bit_or_a" | "xor_a" | "ls_a" | "rs_a" | "mod_a"
                                | "subscript" | "function" | "pointer" | "member"
                                | "inc" | "dec" | "comma" | "nw" | "del" | "nw_arr" | "del_arr" | "as"
<result_type>               ::= <type_spec>
<method_parameter_spec>     ::= "," <type_spec> "," <parameter_name>
<parameter_name>            ::= <identifier>
<type_spec>                 ::= restricted C++ type (see notes on parameter types for what's allowed)
<access_spec>               ::=   "Pub"    /* iff public */
                                | "Prot"   /* iff protected */

/* Constructor Declaration */

<constructor_declaration>   ::= "MMXX_CONS_"<num_constructor_parameters>
                                  "("
                                    <access_spec>
                                    "," <class_name>
                                      /* redundant, must match name of class being declared */
                                    "," <extra_flags>
                                    "," <num_nonprivate_supers>
                                      /* redundant from MMXX_CLASS_*() declaration, must
                                         match quantity of non-private superclasses given there */
                                    "," "("
                                          <constructor_nonprivate_super_spec>*
                                            /* quantity given by <num_nonprivate_supers> */
                                        ")"
                                    <constructor_parameter_spec>*
                                      /* quantity given by <num_constructor_parameters> */
                                  ")"
<num_constructor_parameters>
                            ::= "0" .. "10"
<class_name>                ::= <identifier>
                                  /* redundant, must match name of class being declared */
<constructor_nonprivate_super_spec>
                            ::= [ "," ]
                                  /* iff this is not the first non-private superclass */ 
                                <superclass_name>
                                  /* redundant from MMXX_CLASS_*() declaration, must
                                     match non-private superclasses given there */
<constructor_parameter_spec>
                            ::= "," <type_spec> "," <parameter_name>

/* Static Method Declaration */

<static_method_declaration> ::= "MMXX_STATIC_"<num_method_parameters><result_decl><throw_decl>
                                  "("
                                    <access_spec>
                                    "," <class_name>
                                      /* redundant, must match name of class being declared */
                                    "," <extra_flags>
                                    [ "," <result_type> ]
                                      /* iff <result_decl> is "R" */
                                    "," <method_name>
                                    <method_parameter_spec>*
                                      /* quantity given by <num_method_parameters> */
                                  ")"

/* Enumeration Declaration */

<member_enumeration_declaration>
                            ::= <begin_member_enumeration>
                                <member_enumeration_tuple>*
                                <end_member_enumeration>

<begin_member_enumeration>  ::= "MMXX_ENUM_START"
                                  "("
                                    <class_name>
                                      /* redundant, must match name of class being declared */
                                    "," <enum_name>
                                    "," <number_match_flag>
                                    "," <all_required_in_peer_flag>
                                    "," <all_required_in_shadow_flag>
                                  ")"

<enum_name>                 ::= <identifier> /* name of enumeration, may not be empty */

<number_match_flag>         ::=   "0" /* iff linker should allow numbers to differ */
                                | "1" /* iff linker should require numbers to match */

<all_required_in_peer_flag> ::=   "0" /* iff linker should allow peer not to contain all tuples */
                                | "1" /* iff linker should require peer to contain all tuples */

<all_required_in_shadow_flag>
                            ::=   "0" /* iff linker should allow shadow not to contain all tuples */
                                | "1" /* iff linker should require shadow to contain all tuples */

<member_enumeration_tuple>  ::= "MMXX_ENUM_TUPLE"
                                  "("
                                    <class_name>
                                      /* redundant, must match name of class being declared */
                                    "," <enum_name>
                                      /* redundant, must match name of enumeration being declared */
                                    "," <enum_label>
                                    "," <enum_value_expr>
                                  ")"

<enum_label>                ::= <identifier>

<enum_value_expr>           ::= <C++_expr>   /* valid C++ enumeration expression */
                                    /* (use literals if at all possible in MMXX 1.0) */

/* Member Struct Declaration */

<member_structure_declaration>
                            ::= <begin_member_structure>
                                <member_structure_field>*
                                <end_member_structure>

<begin_member_structure>    ::= "MMXX_STRUCT_START"
                                  "("
                                    <class_name>
                                      /* redundant, must match name of class being declared */
                                    "," <structure_name>
                                  ")"

<structure_name>            ::= <identifier>

<member_structure_field>    ::= "MMXX_STRUCT_FIELD"
                                  "("
                                    <class_name>
                                      /* redundant, must match name of class being declared */
                                    "," <structure_name>
                                      /* redundant, must match name of structure being declared */
                                    "," <type_spec>
                                    "," <structure_field_name>
                                  ")"

<structure_field_name>      ::= <identifier>

/* Static Initializer Declaration */

<static_initializer_declaration>
                            ::= "MMXX_STATICINIT"
                                  "("
                                    <class_name>
                                      /* redundant, must match name of class being declared */
                                    "," <static_init_method_name>
                                    "," <static_init_execution_spec>
                                  ")"

<static_init_method_name>   ::= <identifier>
                                  /* name of (static) class method to execute upon static */
                                  /* initialization, automatically declared with signature */
                                  /* void (*)(int). These staticinits execute in
                                     class derivation order as MMXX units are linked in. */

<static_init_execution_spec>::=   "REAL"    /* iff to execute for real classes only */
                                | "SHADOW"  /* iff to execute for shadow classes only */
                                | "BOTH"    /* iff to execute for both real and shadow */