

*** COMMAND LINE ***


Formic <format_file> -i <input_file> -a <lexex_file> [-D <defined>=<definer>]
       -F <source_file_name>

format_file         formic script
input_file          C++ source
lexex_file          lexical extensions
defined/definer     ant containing defined is repalced by definer
source_file_name    provides value for $(FNAME) & $(CAPFNAME) (see below)


*** COMMENTS ETC. ***


$/   <text>          The remainder of the line is ignored by formic

$//  <text>          The remainder of the line and the followng \n is ignored

$/// <text>          The remainder of the line, the followng \n and all
                     following whitespace is ignored.

$LEX <key>:<inst>    inst is added to the list of lexical extensions
                     as in instance of key e.g. FUNCTION_SPEC:LEAF.  This
                     mechanism superceeds the 'lexex' file, though it remains
                     for compatibility.  $LEX formats like $//  [1]

$DEF <def_d>=<def_r> equivalent to '-D def_d=def_r' on the command line 
                     (and overrides it.)  $DEF formats like $// [1]

<key>                :=  PROTECTION_TYPE
                     |   STORAGE_CLASS
                     |   FUNCTION_SPEC
                     |   TYPE_NAME
                     |   CLASS_ATTRIBUTE
                     |   PRE_INSTANCE_ATTRIBUTE
                     |   POST_INSTANCE_ATTRIBUTE
                     |   PRE_METHOD_ATTRIBUTE
                     |   POST_METHOD_ATTRIBUTE

------------------------------------------------------------------------------

[1]  $LEX $DEF take effect when the format file is parsed, BEFORE the source
     file is parsed; therefore the position in the format file is irrelvant.



*** OUTPUT ANTS ***


output_ant  := $( <output_idx> <output_predicate> )
            |  $( <output_idx> <output_predicate> <comp_string> )

output_idx  :=   CLASS    current class      in a FOR CLASSES            loop
            |    SCLASS     "     superclass  " "  "  SUPERCLASSES        "
            |    FUNC       "     function    " "  "  FUNCS or SUPERFUNCS "
            |    VAR        "     variable    " "  "  VARS                "
            |    ARG        "     argument    " "  "  ARGS                "
            |    N         iteration count of the immediately enclosing loop
            |    FNAME     file name root [2]
            |    CAPFNAME  file name root capitalized [3]
            |    <other>

other       :=  any identifier not equal to or beginning with any formic key.
                If the identifier was passed to formic as a definition
                (see COMMAND LINE) the definition will be substituted
                for the identifier, otherwise it will be output literally.

comp_string :=  a string terminated with a '+'.  The portion of the string 
                preceeding the '+' must match an initial substring of the
                string to be output.  If it does, then the remainder of the
                string is output.  If it does not formic terminates with a
                fatal error.


output_predicate (see next page)



------------------------------------------------------------------------------

[2]  The input filename is stripped of all path information and any 
     '.'-preceeded extension: e.g. /foo/bar/baz.cxx => baz .  The filename
     can be passed to formic on the command line with the -F option (see
     COMMAND LINE).  If there is no -F then the input filename is used
     (or "input" if the input is from stdin.)

[3]  The filename is derived as with FNAME, then all original lowercase
     letters are replaced with uppercase, and all original uppercase 
     prefixed with '_': e.g. FooBar => _FOO_BAR




*** OUTPUT ANTS (cont.) ***


Output Predicates for output_idx's CLASS and SCLASS

(NULL)      (same as name:)
name:       class name
base:       name of parent class
comment:    comment on class [4]


Output Predicates for output_idx FUNC

(NULL)       (same as name:)
name:        function name
m_name:      mangled name
m_name28:    mangled name abbreviated to 28 characters [5]
type:        function return type [6]
root:        the type with any indirection removed
ult_type:    type with typedefs restored to original type
ult_root:    root with typedefs restored to original type
comment:     comment on function [7]


Output Predicates for output_idx VAR

(NULL)       (same as name:)
name:        variable name
type:        variable type
root:        type with any indirection removed
ult_type:    type with typedefs restored to original type
ult_root:    root with typedefs restored to original type


Output Predicates for output_idx ARG

(NULL)       (same as name:)
name:        argument name
type:        argument type
root:        type with any indirection removed
ult_type:    type with typedefs restored to original type
ult_root:    root with typedefs restored to original type

------------------------------------------------------------------------------

[4] This comment is constructed by concatenating
    all comments between the last preceeding '{' , '}' or ';'
    (or the beginning of the file if there is none) and
    the 'class' or 'CLASS' keyword.

[5] The length of the full mangled name is prepended to a
    shortened name produced by deleting alternate characters.
    (not quite guranteeed to be unique, but collisions should
    be rare.)

[6] 'int' is supplied if it was implicit in the source

[7] This comment is constructed by concatenating
    all comments between the last preceeding '{' , '}' or ';'
    (or the beginning of the file if there is none) and
    the beginning of the function definition or declaration.



*** SELECTION ANTS ***
    
selection_ant := $( <key> <selection_idx> <test> )

key           := FOR            takes plural selection_idx's only

              |  IF             takes any selection_idx plurals are TRUE
                                iff the corresponding list is not empty

selection_idx := CLASSES        all satifying test

              |  CLASS          current class in FOR CLASSES loop

              |  SUPERCLASSES   superclasses of current class

              |  SCLASS         current class in FOR SUPERCLASSES loop

              |  FUNCS          member function of current class  [8]

              |  SUPERFUNCS     member functions all current class and
                                its ancestors   [9]

              |  FUNC           current function in FOR CLASSES or
                                FOR SUPERCLASSES loop

              |  VARS           instance variables of the currenct class

              |  VAR            current variable in FOR VARS loop

              |  ARGS           arguments of the current function

              |  ARG            curent arguments in FOR ARGS loop

              |  MORE           takes no selection_idx or test.  TRUE
                                if the immediately enclosing loop is NOT
                                on it final iteration

test          := <simple_test>
              |  <not> <test>
              |  <either_of> <test> <test>
              |  <both_of> <test> <test>

not           := '!'

either_of     := '|'

both_of       := '&'

simple_test   := <selection_predicate>
              |  <selection_predicate> <test_string>
              |  <selection_predicate> <test_string> <test_string>

test_string   := any string. If the string is terminated with a '+' then
                 it matches any string that contains the preceeding portion
                 as an initial substring (i.e. '+' works like '*' in UNIX
                 regular expressions.)

selection_predicate (see next page)

-----------------------------------------------------------------------------

[8] or independent functions if not in a FOR CLASSES or FOR SUPERCLASSES loop

[9] In the case of overridden function the one selected is the lowest
     in the class hierarchy.


*** SELECTION ANTS (cont.) ***

Selection_predicates for selection_idx's CLASS CLASSES SCLASS SUPERCLASSES

name:      TRUE if test_string is absent or matches class name

kind:      TRUE if test_string is absent or matches the name of the class or
           any of its superclasses

memf:      if the test_string is absent TRUE if the class has any member
           functions, otherwise TRUE if the test_string matches the name
           of any member function.

memv:      if the test_string is absent TRUE if the class has any instance
           variables, otherwise TRUE if the test_string matches the name
           of any instance variable.

pro:       TRUE if test_string is absent or matches the name of any section
           heading ("protection") in the class

attr:      TRUE if test_string is absent or matches any class attribute
           of the class i.e. attr: LOCKED_CLASS

basepro:   TRUE if test_string is absent or matches the name of any section
           heading in the immediate parent class of the current class
    
superpro:  TRUE if test_string is absent or matches the name of any section
           heading in any superclass of the current class

baseattr:  TRUE if test_string is absent or matches the name of any class
           attribute of the immediate parent class of the current class
    
superattr: TRUE if test_string is absent or matches the name of any class
           attribute of any superclass of the current class

promf:     TRUE if there are two test_strings, the first matches the
           name of a section heading in the class, and the second matches
           the name of a member function in that section. FALSE otherwise.

promv:     TRUE if there are two test_strings, the first matches the
           name of a section heading in the class, and the second matches
           the name of an instance variable in that section. FALSE otherwise.



*** SELECTION ANTS (cont.) ***

Selection_predicates for selection_idx's FUNC FUNCS SUPERFUNCS

name:      TRUE if test_string is absent or matches function name

type:      TRUE if test_string is absent or matches the return type
    
root:      TRUE if test_string is absent or matches the return type
           with its indirection removed

ult_type:  TRUE if test_string is absent or matches the return type
           with typedefs restored to the original type

ult_root:  TRUE if test_string is absent or matches the return type
           with typedefs restored to the original type and indirection
           removed

ptr:       if test_strings is absent, TRUE if the return type is a pointer
           otherwise TRUE if return type is a pointer to a type matched
           by test_string

pro:       TRUE if test_string is absent or if function is a member
           of a class in a section whose heading matches test_string

spec:      TRUE if the test_string is absent or matches an item in the
           function specifier list (e.g. "virtual", "static")

attr:      TRUE if the test_string is absent or matches a method attribute
           of the function.

const:     TRUE of a member function defined as "const"



Selection_predicates for selection_idx's VAR VARS

name:      TRUE if test_string is absent or matches variable name

type:      TRUE if test_string is absent or matches the variable type

root:      TRUE if test_string is absent or matches the variable type
           with its indirection removed

ult_type:  TRUE if test_string is absent or matches the variable type
           with typedefs restored to the original type

ult_root:  TRUE if test_string is absent or matches the variable type
           with typedefs restored to the original type and indirection
           removed

ptr:       if test_strings is absent, TRUE if the variable type is a pointer
           otherwise TRUE if variable type is a pointer to a type matched
           by test_string

pro:       TRUE if test_string is absent or if variable is a member
           of a class in a section whose heading matches test_string

kind:      TRUE if test_string is absent or if the variable is a pointer
           to a class and the test_string matches the name of that class
           or any superclass of that class

attr:      TRUE if the test_string is absent or matches an instance attribute
           of the variable.



*** SELECTION ANTS (cont.) ***


Selection_predicates for selection_idx's ARG ARGS

name:      TRUE if test_string is absent or matches argument name

type:      TRUE if test_string is absent or matches the argument type

root:      TRUE if test_string is absent or matches the argument type
           with its indirection removed

ult_type:  TRUE if test_string is absent or matches the argument type
           with typedefs restored to the original type

ult_root:  TRUE if test_string is absent or matches the argument type
           with typedefs restored to the original type and indirection
           removed

ptr:       if test_strings is absent, TRUE if the argument type is a pointer
           otherwise TRUE if argument type is a pointer to a type matched
           by test_string

out:       TRUE if the argument is flagged as an output argument by being
           preceeded by the dummy argument OUT in the parameter list

in:        TRUE if out: is FALSE (redundant)
            
