Declaration syntax
==================


Comments and spaces
-------------------

Lines beggining with "//" are comments.
White lines do not harm.


Includes
--------

#include xxxxxxx


Constants
---------

const type constname [value]

Valid types for constants are: int, float, char*, string, and any predefined class.

If value is not present, value=constname, useful to declare C++ macros or constants.


Typedefs
--------

typedef newtype oldtype

Note its the opposite as in C/C++


Symbols (to do)
-------

symbol symbolname [symbolname]

Symbols are references to predefined C++ objects.


Classes
-------

[abstract] class ClassName [ParentName]

abstract: Do not generate a create() Pike function for this class,
as it is a C++ abstract class.

A class definition can appear more than once, to allow forward references.


Class functions
---------------

[directive...] returntype functionname[#pikename]([ parameter... ])

where parameter is:

[addref|subref] type[=default value]

Directives:

extern: Declare it in module initialization, but do not provide an implementation. An external, possibly handwritten implementation must be provided. extern functions do not need parameter directives as the implementation is not generated by bindgen, but however can be present for informational purposes.

virtual: Generate a C++ proxy class able to call Pike overloaded versions of the function when C++ code requires it.

addrefthis/subrefthis: See memory management section.

To be implemented:

sideffect: The function does side effects, so don't optimize it out the execution (just as OPT_SIDE_EFFECT in the Pike C API). (Not implemented)

extdep: The function result depends on something besides its arguments, so don't optimize it out the execution (just as OPT_EXTERNAL_DEPEND in the Pike C API). (Not implemented)

addrefvalue: Add a reference to the return value. Necessary? (Not impl)

In case of polymorphic names, add a hash and a different name, e.g:

void Append int wxString& wxString& wxItemKind
void Append#AppendMenu int wxString& wxMenu* wxString&
void Append#AppendItem wxMenuItem*

Parameter directives:

addref/subref: See memory management section.

About types: Object types carry a "&" or "*" suffix if the parameter is a reference or a pointer respectively.

The class functions are attached to the last class declaration found, as there are no brackets delimiting classes.


Class constructors
------------------

[directive...] [void] create([ parameter... ])

Create is always void, so it is optional.

The special directives for create are (to be implemented):

destroywrapped: Destroy the wrapped C++ object with the Pike object (default).

nodestroywrapped: Do not destroy the wrapped C++ object with the Pike object.


Module functions
----------------

[extern] function returntype functionname([ parameter... ])


Memory management issues
------------------------

C++ usually requires explicit object deletion, but Pike don't, it has a garbage collector that does it automatically when the object reference count reaches zero. Howerver, Pike wrappers should be able to destroy its C++ objects with them to avoid memory leaks. Also, calling of virtual functions reimplemented in Pike requires the wrapper to be available for the C++ object. Also, eventually a Pike object could leaked, marked as in use when its C++ object was deleted. So synchronization between Pike and C++ sides is crucial. The way to handle it is using hints to keep Pike object counters with a proper value along the different binding calls.

At the function level there are two directives:

addrefthis: Increment the wrapper reference count, as the wrapped C++ function adds a reference to the C++ object somewhere. This is to avoid the eventual garbage collection of the Pike object wrapper, and then, the C++ object. Typical use is in create() for certain wxWidgets classes like those in wxWindow hierarchy, that are managed by the framework automatically when created.

subrefthis: Function removes a reference to this object somewhere.

Those do not apply to efuns, only to "method" functions.

Also, at the parameter level there are two directives:

addref: Works in the same way as addrefthis, but applies to the parameter, and not to this_object(). 

subref: Works in the same way as subrefthis, but applies to the parameter, and not to this_object().

Along those, nodestroywrapped allows to avoid the C++ object destruction. This is useful, for aggregation/composition relationships, where a master object owns it child objects and cares about their destruction. wxWidgets controls are a case.
