Parts:

PDOH - Directives

The directive is the first attribute of a // %% DYNOBJ tagged line. It is one of:
  • // %% DYNOBJ options
  • // %% DYNOBJ section
  • // %% DYNOBJ class
  • // %% DYNOBJ library
Whenever an option is specified from both (1) inside a file and from (2) the command-line, the commandline has the last say.

Named sections

The PDOH tool generates up to three different named file sections:
  • general - This is the section at the top of a header file. It is used by both plugin and host.
  • implement - This section is generated at the end of a header file. It is only used by the plugin, to setup type information.
  • library - This section is usually generated inside a C++ source file. It generates a library skeleton, interfaced by plugin users.
All auto-generated output from PDOH is written into these sections so that other parts of the file are left untouched. Once generated into a file, one may move the sections arbitrarily, and any subsequent refresh will be done at the new location.

The options directive

Can be close to the beginning of a file to set preprocessor options per-file. Values:
  • brief - Ask preprocessor to be less verbose in output.
  • vtabcorr - Instructs preprocessor to output code that supports VTable correction. NOTE: This is an experimental feature.
There can also be the generate and tofile attributes on an option line:
  • generate - Instructs preprocesssor which sections to output:
    • general | implement | library - One or more of these

  • tofile - Tells the preprocessor to write output to file as opposed to stdout.
    • general | implement | library - One or more of these.
Example:

// %% DYNOBJ options(brief) generate(implement)


The sections directive

The section tags are usually auto-generated by the processor and we don't modify them manually. Example:

// %% DYNOBJ section implement


The class directive

This declares a plugin class to the preprocessor. The preprocessor will scan the next non-comment C++ source line for a valid class/struct declaration. It will use the name and base classes found in the source, unless a name and basel classes have been explicitely specified.

Explicitely stating base classes allows for only exposing a sub-set of them, or for skipping steps in the inheritance chain. Also, when using both name and bases attributes, a class tag can be used from another file location than the C++ class declaration.

Values for the class directive:
  • vobj - The declared class is a independent of the DynI class hierarchy (arbitrary C++ class with virtual methods).
  • dyni - The declared object derives (directly or indirectly) from DynI.
The name attribute (optional):
  • UserClassNameHere - The string name of the class when exposed by the plugin.
The bases attribute (optional):
  • BaseName1,BaseName2,... - A list of names of the base classes or interfaces implemented which the plugin class implements.
The flags attribute (optional):
  • notypeid - Do not generate an integer type ID for this class in this file. [Use when the type ID is defined in some other file.]
  • usertype - This is an instantiable class (as opposed to an interface/abstract class).
  • novcorr - Disable VTable correction for this class, even if it would be suitable (VTable correction is disabled globally by default).
  • static - Objects of this type can all be treated like static globals, i.e. they don't go out of scope until the plugin is unloaded. NOTE: Only valid from the main/host program!
  • noproto - Don't declare any prototype for this class.
  • template - The class is a template specialization.
Example:

// %% DYNOBJ class(dyni) name(DynArrC) bases(DynArrChar) flags(usertype,noproto)


The library directive

This directive instructs PDOH where to output library skeleton code. It is used from inside a C++ source file usually.

The library code contains the code needed to recognize the types requested from outside and instantiate the right objects and to forward data to the constructors.

It also contains function bodies for library init and exit. They can be customized for library specific needs.

Attributes for the library directive:
  • types - The value of this attribute is a list of types implemented by the library (in addition to class tags in the same file). It has the format:
    • DerType1:BaseType1,DerType2,BaseType2,...
    • The derived type is not necessary exposed externally. So even if asked for the base type, we instantiate the derived type (the base type is usually an interface we implement)

  • advanced - This instructs the preprocessor to generate a library that uses in-place new. Objects can then be instantiated in memory provided by the host. NOTE: This feature is currently not used.
Example:

// %% DYNOBJ   library   types(PersonImpl2:PersonI)