PDOH - Directives
The directive is the first attribute of a // %% DYNOBJ tagged line. It is one of:
Whenever an option is specified from both (1) inside a file and from
(2) the command-line, the commandline has the last say.
- // %% DYNOBJ options
- // %% DYNOBJ section
- // %% DYNOBJ class
- // %% DYNOBJ library
The PDOH tool generates up to three different named file sections:
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.
- 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.
The options directive
Can be close to the beginning of a file to set preprocessor options per-file. Values:
There can also be the generate and tofile attributes on an option line:
- 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.
- 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.
// %% 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:
The name attribute (optional):
- 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 bases attribute (optional):
- UserClassNameHere - The string name of the class when exposed by the plugin.
The flags attribute (optional):
- BaseName1,BaseName2,... - A list of names of the base classes or interfaces implemented which the plugin class implements.
- 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.
// %% 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:
- 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.
// %% DYNOBJ library types(PersonImpl2:PersonI)