Copyright © 2019 Advanced Media Workflow Association. All rights reserved.

Dodo Reference Manual

Dodo .DOD source files are simply a set of macros

These macros are expanded differently depending on the macro file used, so the same DOD file can produce both a COM API header and a COM wrapper for the related Impl function with a similar name.

In some Macro files a lot of the macros are simply null.

 

Macro Arguments

 

The arguments passed to Macros can be several lines long (especially in the case of comments).

Occurrences of ( ) parentheses and , commas in the arguments passed to macro have to be escaped with a backslash.

Some macros such as AD_METHOD1 are nested because AD_METHOD1 with 6 arguments invokes AD_XMETHOD1 with an extra argument in the base.mac file, as a result of this, escaped characters in AD_METHOD1 have to be escaped twice, an open parentheses in a comment has to be preceded by three back slashes \\\(.

 

A \ (backslash) character immediately before a newline, indicates a continuation line escaped so that it will not appear in the output.

 

Usage: dodo -f macro_file

Expects input .dod file on standard input, writes the expanded output to standard out.

 

The macro files also include the base.mac file which contains common definitions.

 

Some of the macro files are only used once to generate an initial framework for an implementation file, for instance once you have a constructed a .dod file for your interface you can generate a empty implementation with the command:

 

dodo -m macros/cpp.mac < AAFMyInterface.dod

 

Comments

The comments for methods and interfaces follow a pretty repetitive format, since they are extracted from the IDL file by the DocJet tool to generate the COMAPI manual it is best to follow the existing style of indentation and line breaks.

 

The macros subdirectory contains the following different variants:

All Dodo directives in the macro file start at the beginning of a line, and start with the '#' character.

 

Macro Arguments

 

The arguments passed to a macro are substituted in the body with the notation %n, where n is a digit starting at 1 for the first argument.

 

Comments

 

Dodo comment lines begin with #c

 

Directives

 

the #import directive will include another macro file

 

Macro definitions are delimited with

 

#startm <macro_name> <num_args>
<macro expansion specification line 1>
<macro expansion specification line 2>
...
<macro expansion specification line n>
#endm

 

Whenever the macro_name(<args>) is encountered in the source file, it will be replaced with the multi-line macro expansion in the output file.

 

Special Macros

 

conventionally defined at the top of each dod file

 

.this-module

 

expanded to the class or interface name such as C.this-module and Impl.this-module

.parent-module

 

the parent class for public inheritance at the implementation level, used to aggregate the interfaces at the COM API level by importing the methods of the parent.

 

Special Rules

  • Any arguments specified within a macro expansion specification using the %n syntax must have numbers that are 1 or greater, and are less than or equal to the num_args value for that macro.

  • Any macro invocation in the input file must be given precisely the number of arguments given in the num_args field of the macro's definition.