sprut.sgml.in

<!doctype linuxdoc system>
<article>

<!-- Title information -->

<title>SPRUT (internal representation description translator)
<author>Vladimir Makarov, <tt>vmakarov@gcc.gnu.org</tt>
<date>Apr 5, 2001
<abstract>
This document describes SPRUT (translator of a compiler internal
representation into standard procedural interface).
</abstract>
<toc>

<sect>Introduction
<p>
SPRUT is a translator of a compiler internal representation
description (IRD) into Standard Procedural Interface (SPI).  The most
convenient form of the internal representation is a directed graph.
IRD defines structure of the graph.  SPI provides general graph
manipulating functions.  The defined graph nodes can be decorated with
attributes of arbitrary types.

IRD declares types of nodes of the graph.  Nodes contains fields, part
of them represents links between nodes, and another part of them
stores attributes of arbitrary types.  To make easy describing
internal representation the IRD supports explicitly single inheritance
in node types and also can model multiple inheritance.  There can be
several levels of internal representation description in separate
files.  The nodes of one level refer to the nodes of previous levels.
Therefore each next level enriches source program internal
representation.  For example, the zero level representation may be
internal representation for scanner, the first level may be internal
representation for parser, and so on.

SPI can contains functions to construct and destroy graphs and graph
nodes, to copy graphs or graph nodes, to read and write graphs or
graph nodes from (to) files, to print graphs or graph nodes, to check
up constraints on graph, to traverse graphs, and to transform acyclic
graphs in some commonly used manners.  SPI can also check up the most
important constraints on internal representation during work with node
fields.  SPI can automatically maintain back links between internal
representation nodes.

Using SPRUT has the following advantages:
     <enum>
     <item>brief and concise notation for internal representation

     <item>improving maintainability and as consequence reliability of
        the compiler

     <item>user is freed from the task of writing large amounts of
        relatively simple code
     </enum>

The following sections define the internal representation description
language, explain SPI, and present some examples.


<sect>Internal representation description language
<p>
IRD declares types of nodes of the graph.  Nodes contains fields, part
of them represents links between nodes, and another part of them
stores attributes of arbitrary types.  To make easy describing
internal representation the IRD supports explicitly single inheritance
in node types and also can model multiple inheritance.  There can be
several levels of internal representation description in separate
files.  The nodes of one level refer to the nodes of previous levels.
Therefore each next level enriches source program internal
representation.


<sect1>Layout of internal representation description
<p>
To describe internal representation a special language is used.  An
internal representation description structure has the following layout
which is similar to one of YACC file.
<tscreen><verb>
     DECLARATIONS
     %%
     TYPES OF NODES
     %%
     ADDITIONAL C/C++ CODE
</verb></tscreen>
The `%%' serves to separate the sections of description.  All sections
are optional.  The first `%%' starts section of description of types
of internal representation nodes and is obligatory even if the section
is empty, the second `%%' may be absent if section of additional C/C++
code is absent too.

The section of declarations may contain names of predefined types of
fields of internal representation nodes and names of types of double
linked nodes.  The section also contains name of original internal
representation description if given file contains extension of an
internal representation description.  And finally the section may
contains sections of code on C/C++.

The next section contains description of types of internal
representation nodes.

The additional C/C++ code can contain any C/C++ code you want to use.
Often functions which are not generated by the translator but are
needed to work with internal representation go here.  This code
without changes is placed at the end of file generated by the
translator.


<sect1>Declarations
<p>
The section of declarations may contain the following construction.
<tscreen><verb>
     %type IDENTIFIER ...
</verb></tscreen>
All predefined types must be defined in constructions of such kind.
The same name can be defined repeatedly.  All references to node whose
type is a sub-type of type with name present in the following
construction will be double linked.
<tscreen><verb>
     %double IDENTIFIER ...
</verb></tscreen>
It means that SPI will generates functions (macros) which permit to
examine all fields (may be in other nodes) described as of given node
type (or its subtype) which refer to node of given type (or its
sub-type), i.e. fields which are described as of given node type (or
its subtype) will be double linked (see below).  SPI will
automatically maintain such double links.  The simplest way to
describe double linked graph is to insert construction
<tscreen><verb>
     %double %root
</verb></tscreen>
Last construction in the section of declarations of kind
<tscreen><verb>
     %extend IDENTIFIER
</verb></tscreen>
defines name (without suffix) of file containing source internal
representation which is extended by given file.  The file contains
original internal representation if there is no one such construction.
The original specification file has level 0, the extensions have level
1, 2, and so on.  This feature permits sequentially to develop an
internal representation and to save and restore any its level (see
SPI) to additional tools, e.g.  browsers.  For example, there may be
three levels of source program internal representation.  The zero
level representation may be internal representation for semantic
analysis, the first level may be a low level machine-dependent
internal representation, and the second level may be used to generate
object code.  Only first such construction in one file is essential.
All subsequent such constructions are ignored.

There may be also the following constructions in the declaration
section
<tscreen><verb>
     %local {
        C/C++ DECLARATIONS
     }

     %import {
        C/C++ DECLARATION
     }

         and

     %export {
        C/C++ DECLARATION
     }
</verb></tscreen>
which contain any C/C++ declarations (types, variables, macros, and so
on) used in the description sections.

The local C/C++ declarations are inserted at the begin of generated
implementation file (see SPI description) but after include-directive
of interface file.

C/C++ declarations which start with `%import' are inserted at the
begin of generated interface file.  For example, such C/C++ code may
contain C/C++ definitions of predefined types which are used in field
declarations of node types.

C/C++ declarations which start with `%export' are inserted at the end
of generated interface file.  For example, such C/C++ code may contain
definitions of external variables and functions which refer to node
type representation (see type `IR_node_t' in SPI description).

All C/C++ declarations can redefine all type specific and internal
macros (see SPI) because they are placed in implementation file.  All
C/C++ declarations are placed in the same order as in the section of
declarations.  C/C++ declarations from IRD file with smaller level
number (see construction `%extend') are placed in interface or
implementation files firstly.


<sect1>Types of nodes
<p>
The section of declarations is followed by section defining internal
representation node types.  An internal node type is described by the
following construction
<tscreen><verb>
     %abstract
     IDENTIFIER :: IDENTIFIER (or %root)
     CLASS FIELDS
     SKELETON FIELDS
     OTHER FIELDS
</verb></tscreen>
Keywords `%abstract' is optional.  Node type description which starts
with this keyword denotes abstract node type, i.e.  node of such type
does not exist in internal representation of any source program.
Abstract nodes types serve only to description of common fields of
several node types.

The first identifier defines name of internal representation node
type, the second defines name of node type all declarations of fields
of which are inherited into the given node type.  In this construction
the first node type is so called immediate super type, the second is
immediate sub-type.

Node type A is a super-type of node type B (and node type B is a
sub-type of node type A) iff node type A is immediate super-type of
super-type of node type B.  All node types are sub-types of implicitly
declared node type with name `%root'.  There are also nodes of special
type (error nodes).  Type of these nodes are believed to be sub-type
of all declared node types.  The definition of type of error nodes are
absent in any internal representation description.

The identifier of immediate super-type (with `::') can be absent.  In
this case the construction is continuation of given type node
declaration.  There can be only the single main node type declaration
and many its continuations.  The order of main node type declaration
and its continuations can be arbitrary.  The continuations can not
start with keyword `%abstract'.

Construction of the following kind
<tscreen><verb>
     A, B, ... :: C
     DECLARATIONS OF FIELDS
</verb></tscreen>
is abbreviation of the following constructions
<tscreen><verb>
     A :: C
     DECLARATIONS OF FIELDS
     B :: C
     DECLARATIONS OF FIELDS
     ...
</verb></tscreen>
The fields are sub-divided on kinds.  There are three kinds of fields.
     <enum>
     <item>Class fields.  There is the single instance of a class field
        for all nodes of given type.

     <item>Skeleton fields.  There is the single instance of a skeleton
        fields for each node of given type.  The value of skeleton
        field is to be given by user at the node creation moment (see
        SPI description).

     <item>Other fields.  This kind of fields is analogous to one of
        skeleton fields but value of such field is not given by user
        at the node creation moment.
     </enum>
Optional sections of declarations of class fields, skeleton fields,
and other fields start correspondingly with keywords `%class',
`%skeleton', and `%other'.
<tscreen><verb>
     %class LIST OF DECLARATIONS OF FIELDS

     %skeleton LIST OF DECLARATIONS OF FIELDS

     %other LIST OF DECLARATIONS OF FIELDS
</verb></tscreen>
These keywords are followed by may be empty list of declarations of
fields.  The list elements are field declaration or target code.
Field declaration is described by the following construction:
<tscreen><verb>
     IDENTIFIER : FIELD  %double  TYPE  CONSTRAINTS  ACTIONS
</verb></tscreen>
Identifier is name of given field.  All declarations of fields of a
node type must have unique names.  But declarations of fields of
different node types can have the same names if the types of such
fields are the same, the fields are simultaneously described as double
linked or not, and all such fields are class or any non-class fields.
Owing to the feature it is possible to model multiple inheritance.
Semicolon `:' is followed by the field type.  There are the following
types of nodes fields:
     <enum>
     <item>identifier from a clause `%type'.  The identifier represents
        predefined type and must be declared anywhere by the
        construction `typedef' of C/C++.

     <item>node name.  This type represents arc to a node of given type
        or its subtypes and is implemented by pointer of C/C++.
     </enum>
These constructions can have optional clause `%double'.  Its sense is
slightly different from the one in the declarations section.  This
clause means that SPI will generate functions (macros) which permits
to examine all nodes of the declared type (or its sub-type) which
refer through given field to a node of the field type (or its
sub-type).  The clause `%double' can not be given for class fields.

The field type may be followed by constraints and actions in any
order.  The constraint is usually present for non-null value node
reference.  The constraint is a boolean expression on C/C++ in
brackets `[' and `]'.  The constraints are tested with the aid of some
generated functions in the same order as they are present in
corresponding type node declaration.  The actions can contain any
statements on C/C++ in figure brackets `{' and `}' (the brackets are
also output therefore C/C++ declarations can be in actions).  The
actions for skeleton and other fields are fulfilled at the node
creation time in the same order as they are present in corresponding
type node declaration.  The actions for class fields are fulfilled at
the internal representation initiation time.

Constructions `$$', `$' in the constraints and the actions represent
correspondingly current node and previous field.  But `$' is not
changed by the previous field if the previous field in given node type
declaration is of other kind than the constraint or action (e.g. the
field of skeleton kind and the constraint of class kind) or such field
does not exist in the current node type declaration.  Also it should
be remembered that `$' can not be used in left hand side of assignment
if the construction represent double linked fields.

The construction `IDENTIFIER : FIELD TYPE' may be absent.  This case
is convenient for definition of additional constraints and actions for
fields which declared in a super-type of given node type.

Construction of kind
<tscreen><verb>
     A, B, ... : C ...
</verb></tscreen>
is abbreviation of the following constructions
<tscreen><verb>
     A : C ...
     B : C ...
</verb></tscreen>
Full YACC syntax of internal representation description language is
placed in Appendix 1.


<sect>Standard Procedural Interface
<p>
An internal representation description is translated by SPRUT
(internal representation definition translator) into a standard
procedural interface (SPI).  If the specification file is an extension
(see the language description) of another specification file the later
is also used to SPI generation and so on.  SPI consists of interface
and implementation files having the same names as one of the
specification file and correspondingly suffixes `.h' and `.c' (C code)
or `.cpp' (C++ code).

<sect1>C SPI
<p>
By default (when option `-c++' is not present on the command line)
SPRUT generates C SPI.  The following subsections describe C SPI.

<sect2>C SPI types, variables, macros
<p>
Interface file of SPI consists of C declarations of the following
types, variables and macros.
     <enum>
     <item>Type `IR_node_mode_t' is represented by enumeration
        definition.  There is enumeration constant with node type name
        and prefix `IR_NM_' for each node type declaration even for
        abstract node type.  Also there are enumeration constants with
        names `IR_NM__root' and `IR_NM__error' for and predefined type
        `%root' and for error nodes.  `IR_NM' is abbreviation of
        internal representation node mode.  There is also the
        enumeration name `IR_node_mode_enum' which is convenient to
        use in imported section for forward definition of pointer to
        this enumeration.

     <item>Type `IR_node_t' represents a node (more correctly pointer to
        a structure representing node).  There are the type value
        `NULL' reserved to represent none node.
        <p>
        The structure of this type is opaque and all work with nodes
        are to be fulfilled through macros (or/and functions).  But to
        show efficacy of types implementation it should be said that
        every node type is turned into a structure declaration.  All
        these structures have first member of type `IR_node_mode_t'.
        Other members represent the node fields except for class
        field.  Depending on SPRUT command line option
        `-flat-structure' (see SPRUT usage) this structure can contain
        also members corresponding to fields declared in super types
        of given node type or member which type is structure
        corresponding to immediate super type of given node type.
        Class fields for each non-abstract node type are represented
        by only one separate structure.
        <p>
        The fields in different node types with the same name (when it
        is consequence of existing common super type with this field)
        have the same displacement from the structure begin because
        types of previous fields is guaranteed to be the same in these
        structures.  The fields in different node types with the same
        name (when it is not consequence of existing common super type
        with this field) may have the different displacement from the
        structure begin therefore access to such fields requires
        additional indirect addressing.
        <p>
        Double linked field (see internal representation description
        language) requires more memory (about in five times) for its
        implementation.  Speed of SPI work with double linked fields
        is sightly slower.  Because additional work is needed only to
        setting up the field value and my experience shows that
        usually number of setting up fields value is less than number
        of their fetching about in ten times.
        <p>
        Type `IR_node_t' is simply pointer to struct representing node
        type `%root'.  The name of this structure is `IR_node'.
        This name can be used in imported section for forward
        reference for nodes (instead of `IR_node_t').
        
     <item>Optional variable `IR_node_name' is array mapping values of type
        `IR_node_mode_t' to names (strings) in C. (see also
        option -no-node-name in SPRUT usage).
        
     <item>Variable `IR_node_size' is array mapping values of type
        `IR_node_mode_t' to size of corresponding structures on C.

     <item>Macro `IR_IS_TYPE(type, supertype)' is evaluated as nonzero if
        the first argument of type `IR_node_mode_t' is equal to the
        second argument or node type represented by the first argument
        is a sub-type of node type represented by the second argument.
        Otherwise the macro returns zero.  But this macro returns
        always zero for any error node, i.e.  this macro can be used
        to define that the node of the first mode has fields of the
        node of the second mode.
        
     <item>Macro `IR_NODE_MODE(node)' returns node mode represented by
        value of type `IR_node_mode_t' for node given as the macro
        argument of type `IR_node_t'.

     <item>Macro `IR_IS_OF_TYPE(node, supertype)' is abbreviation of
        frequently used `IR_IS_TYPE (IR_NODE_MODE (node), supertype)'.

     <item>Macro `IR_NODE_LEVEL(node)' has value which is internal
        representation description level in which declaration of given
        node type starts.
     </enum>

<sect2>C Functions
<p>
SPI interface file also contains definitions of generated functions to
creation, deletion, modification, comparison, copy, check, print, and
binary input/output of internal representation nodes and functions for
access to values of internal representation node fields.

These functions do not permit to work with abstract nodes.  Only one
graph function can be active, e.g.  call of function `IR_check_graph'
is not permitted during work of any traverse or transformation
function.

Macros can be generated with or instead of the functions for access to
internal representation node fields.  This feature should be used if
used C preprocessor has not rigid constraints on number of defined
macros.  Because macros arguments may be evaluated many times no
side-effects should be in the arguments.
     <enum>
     <item>Access functions (or/and macros).  These functions are
        generated when option `-access' is present in the SPRUT command
        line.  If option `-macro' is used the access functions and
        macros are generated.  If option `-only-macro' is used only
        access macros are generated.  Only option `-macro' or
        `-only-macro' can be on the command line of SPRUT.  There is
        one function for each field with unique name.  Access function
        has name formed from prefix `IR_' and corresponding field
        name.  There is one exception.  When access functions and
        macros are generated, macros have names starting with prefix
        `IR_' and the functions have names starting with prefix
        `IR_F_'.  Access function has one argument of type `IR_node_t'.
        The argument represents node which must have such field.  Type
        of returned value is predefined type (if the field is of such
        type) or `IR_node_t' (if the field is of a node type).
        <p>
        Functions
<tscreen><verb>
        `IR_double_link_t IR__first_double_link (IR_node_t node)',

        `IR_double_link_t IR__next_double_link
               (IR_double_link_t prev_double_link)',

        `IR_double_link_t IR__previous_double_link
               (IR_double_link_t next_double_link)'
</verb></tscreen>
        return references to fields which have double links to given
        node.  Functions `IR__first_double_link' is always implemented
        by function.  The node itself which contains such links can be
        determined by function
<tscreen><verb>
        `IR_node_t IR__owner (IR_double_link_t link)'.
</verb></tscreen>
        Here type `IR_double_link_t' represents pointer to double
        fields.  The functions may also check up that the node has
        given field (see SPRUT options).

     <item>Modification functions.  These functions are generated when
        option `-set' is present in the SPRUT command line.  There is
        one functions for each field with unique name.  Modification
        function has name formed from prefix `IR_set_' and
        corresponding field name.
        <p>
        Modification function has two arguments. The first argument of
        type `IR_node_t' represents node which must have such field.
        The second argument of predefined type (if the field is of
        such type) or of type `IR_node_t' (if the field is of a node
        type) represents new value of the field.
        <p>
        The function may check up constraint if the field represents
        arc to node of a node type or its sub-types (see SPRUT
        options).  The functions may also check up that the node has
        given field.
        <p>
        There is also function for modification of double links
<tscreen><verb>
        `void IR__set_double_link (IR_double_link_t double_link,
                                   IR_node_t value)'
</verb></tscreen>
        Remember that values of `IR__next_double_link' and
        `IR__previous_double_link' are changed after calling this
        function.

     <item>Function 
<tscreen><verb>
        `IR_node_t IR_create_node (IR_node_mode_t node_mode)'
</verb></tscreen>
        is generated in any case.  This function allocates storage for
        node of any type (except for abstract) represented by the
        argument (it can be also `IRNM__error), sets up node mode and
        node level, fulfills fields assignments (except for class
        fields) in the same order as the fields are declared.  The
        field assignment is fulfilled according to type specific
        operation (see section `Type specific macros') and actions
        which are defined after given field in sections of skeleton
        and other fields of corresponding node type.  After that the
        function returns the created node.  The single way to create
        error nodes is to use this function with argument
        `IRNM__error'.

     <item>Node type specific creation functions.  These functions are
        generated when option `-new' is present in the SPRUT command
        line.  There is one function for each node type (except for
        abstract).  Names of functions are formed from prefix
        `IR_new_' and corresponding node type name.  The number of
        parameters of a function is equal to one of skeleton fields of
        corresponding node type.  The parameters of these functions
        have to be given in the order of the skeleton fields in the
        specification.  Fields of the super-type (recursively) precede
        the ones of the sub-type.
        <p>
        These functions may check up constraints on skeleton fields
        which represent arc to node of a node type or its sub-types
        (see SPRUT options).  These functions call node creation
        function and after that assign parameters values to
        corresponding skeleton fields.  After that the functions
        return the created node.  These functions provide a mechanism
        similar to record aggregates.  Nested calls of such functions
        allow programming with terms as in LISP.

     <item>Function
<tscreen><verb>
        `void IR_free_node (IR_node_t node)'
</verb></tscreen>
        is generated when option `-free' or `-free-graph' is present
        in the SPRUT command line.  This function deletes given node.
        The deletion consists of evaluation of finalization macros for
        node fields (see field type specific macros) in reverse order
        and all node space deallocation.  The function also delete
        double linked fields of given node from the corresponding
        lists of double linked fields.  But the user should know that
        there may be dangling references to given node itself after
        the function call.  The function does nothing if the parameter
        value is equal to NULL.

     <item>Function
<tscreen><verb>
        `void IR_free_graph (IR_node_t graph)'
</verb></tscreen>
        is generated when option `-free-graph' is present in the SPRUT
        command line.  This function deletes given node and all nodes
        accessible from given node `graph'.  The nodes are deleted in
        depth first order.  The function does nothing if the parameter
        value is equal to NULL.

     <item>Function
<tscreen><verb>
        `void IR_conditional_free_graph
                 (IR_node_t graph,
                  int (*guard) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-free-graph' is present in the SPRUT
        command line.  This function deletes given node and all nodes
        accessible from given node `graph'.  The nodes are deleted in
        depth first order.  The function does nothing if the parameter
        value is equal to NULL.  The processing (traversing and
        deleting) children of node which is passed to the
        parameter-function is not fulfilled if the parameter-function
        returns zero.  All graph is deleted when the returned value is
        always nonzero.

     <item>Function
<tscreen><verb>
        `IR_node_t IR_copy_node (IR_node_t node)'
</verb></tscreen>
        is generated when option `-copy' or `-copy-graph' is present
        in the SPRUT command line.  This function makes copy of given
        node.  Field type specific macros are used (see section `Type
        specific macros') to make this.  The function only returns
        NULL if the parameter value is equal to NULL.

     <item>Function
<tscreen><verb>
        `IR_node_t IR_copy_graph (IR_node_t graph)'
</verb></tscreen>
        is generated when option `-copy-graph' is present in the
        command line.  This function makes copy of graph given by its
        node `graph'.  The function only returns NULL if the parameter
        value is equal to NULL.

    <item>Function
<tscreen><verb>
        `IR_node_t IR_conditional_copy_graph
                     (IR_node_t graph,
                      int (*guard) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-copy-graph' is present in the
        command line.  This function makes copy of graph given by its
        node `graph'.  The function only returns NULL if the parameter
        value is equal to NULL.  The processing (traversing and
        copying) children of node which is passed to the
        parameter-function is not fulfilled if the parameter-function
        returns zero.  All nodes of graph are copied when the returned
        value is always nonzero.

    <item>Function
<tscreen><verb>
        `int IR_is_equal_node (IR_node_t node_1,
                               IR_node_t node_2)'.
</verb></tscreen>
        is generated when option `-equal' or `-equal-graph' is present
        in the SPRUT command line.  This function returns nonzero iff
        `node_1' is equal to `node_2', i.e.  node_1 and node_2 have
        the same type and all fields of `node_1' are equal to the
        corresponding fields of `node_2'.  Field type specific macros
        are used (see section `Type specific macros') to make this.
        The function return nonzero if parameter values are equal to
        NULL.

    <item>Function
<tscreen><verb>
        `int IR_is_equal_graph (IR_node_t graph_1,
                                IR_node_t graph_2)'
</verb></tscreen>
        is generated when option `-equal-graph' is present in the SPRUT
        command line.  This function returns nonzero iff graph
        starting with node `graph_1' is equal to graph starting with
        node `graph_2', i.e.  the graphs have the same structure and
        all predefined type fields of `graph_1' are equal to the
        corresponding fields of `graph_2'.  The function returns TRUE
        if parameter values are equal to NULL.

    <item>Function
<tscreen><verb>
        `int IR_is_conditional_equal_graph
               (IR_node_t graph_1, IR_node_t graph_2,
                int (*guard) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-equal-graph' is present in the SPRUT
        command line.  This function returns nonzero iff graph
        starting with node `graph_1' is equal to graph starting with
        node `graph_2', i.e.  the graphs have the same structure and
        all predefined type fields of `graph_1' are equal to the
        corresponding fields of `graph_2'.  The function returns TRUE
        if parameter values are equal to NULL.  The processing
        (traversing and comparing) children of node which is passed to
        the parameter-function is not fulfilled if the
        parameter-function returns zero.  All nodes of the graphs are
        compared when the returned value is always nonzero.
        Unprocessed graph nodes are believed to be equal.

    <item>Function
<tscreen><verb>
        `int IR_check_node (IR_node_t node,
                            int class_field_flag)'
</verb></tscreen>
        This function is generated when option `-check' or
        `-check-graph' is present in the SPRUT command line.  By
        default the most of generated functions (and macros) which
        work with internal representation nodes do not check up
        constraints which described in the specification.
        <p>
        There are two kinds of constraints.  The first is constraint
        on field which represents arc to node of given type or its
        sub-types.  The second is constraint which defined by target
        code (see the internal representation definition language).
        The user is responsible to adhere to the constraints.
        Function `IR_check_node' can be used to check all constraints
        corresponding to given node.  The function does nothing if the
        parameter value is equal to null.  In case of a constraint
        violation the involved node and all child nodes are printed on
        standard error and the function returns nonzero (error flag).
        If the second parameter value is zero then class fields of
        given node are not checked up.

    <item>Function
<tscreen><verb>
        `int IR_check_graph (IR_node_t graph,
                             int class_field_flag)'
</verb></tscreen>
        is generated when option `-check-graph' is present in the sprut
        command line.  This function checks given node `graph' and all
        nodes accessible from given node.  It should be known that a
        class field is processed only when the second parameter value
        is nonzero.  The function does nothing if the parameter value
        is equal to null.  In case of fixing any constraint violation
        returns nonzero (error flag).

    <item>Function
<tscreen><verb>
        `int IR_conditional_check_graph
               (IR_node_t graph, int class_field_flag,
                int (*guard) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-check-graph' is present in the sprut
        command line.  This function checks given node `graph' and all
        nodes accessible from given node.  It should be known that a
        class field is processed only when the second parameter value
        is nonzero.  The function does nothing if the parameter value
        is equal to null.  In case of fixing any constraint violation
        returns nonzero (error flag).  The processing (traversing and
        checking) children of node which is passed to the
        parameter-function is not fulfilled if the parameter-function
        returns zero.  All nodes of graph are checked when the
        returned value is always nonzero.  It is better to free
        changed nodes which are not used after transformation
        especially when there are double links to the nodes (otherwise
        the nodes can be accessible with the aid of functions for work
        with double links).

    <item>Function
<tscreen><verb>
        `void IR_print_node (IR_node_t node,
                             int class_field_flag)'
</verb></tscreen>
        is generated when option `-print' is present in the sprut
        command line or options `-check' or `check-graph' is present
        because check functions use this print function.  The function
        outputs values of node fields with their names to standard
        output in readable form.  To make this the function outputs
        sequentially all the node fields (including class fields if
        the second parameter value is nonzero) with the aid of field
        type specific macros (see below).  The function does nothing
        if the parameter value is equal to null.

    <item>Functions
<tscreen><verb>
        `int IR_output_node (FILE *output_file, IR_node_t node,
                             int level)',

        `IR_node_t IR_input_node (FILE *input_file,
                                  IR_node_t *original_address)'
</verb></tscreen>
        are   generated    when   option correspondingly `-output'  or
        `-input' is present in the SPRUT command line.
        <p>
        Function `IR_output_node' writes node to given file.  To make
        this the function outputs the second parameter value, node
        address and after that sequentially all the node fields
        (except for class fields) whose declarations are present in
        internal representation description of `level' or less than
        the one (see internal representation description language).
        The node type must be also declared in internal representation
        description of `level' or less than the one.  The function
        does nothing if the value of parameter `node' is equal to
        NULL.  A nonzero function result code means fixing an error
        during output.
        <p>
        Function `IR_input_node' reads node from given file, allocates
        space for the node, initiates its fields and changes the node
        fields output early.  To make this the function uses function
        `create_node'.  The output level of input node must be less or
        equal to the internal representation level of given SPI.  Null
        value returned by the function means fixing an error during
        input.  The function returns original address of input node
        through the second parameter.  The output and input of fields
        is fulfilled with the aid of field type specific macros (see
        section `Type specific macros').

    <item>Function
<tscreen><verb>
        `void IR_traverse_depth_first
              (IR_node_t graph, int class_field_flag,
               void (*function) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-traverse' is present in the SPRUT
        command line.  This function traverses graph given by its node
        `graph' depth first (it means bottom up for tree).  Arcs
        represented by class fields are included in this graph if the
        second parameter value is nonzero.  At every node a function
        given as parameter is executed.  Arcs implementing lists of
        double linked fields are not traversed.  The function does
        nothing if the `graph' parameter value is equal to NULL.

    <item>Function
<tscreen><verb>
        `void IR_traverse_reverse_depth_first
              (IR_node_t graph, int class_field_flag,
               int (*function) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-reverse-traverse' is present in the
        SPRUT command line.  This function is analogous to the previous
        but the graph is traversed in reverse depth first order (it
        means top down order for tree).  The traverse of children of
        node which is passed to the parameter-function is not
        fulfilled if the parameter-function returns zero.  All graph
        is traversed when the returned value is always nonzero.

    <item>Function
<tscreen><verb>
        `IR_node_t IR_transform_dag
           (IR_node_t graph, int class_field_flag,
            int (*guard_function) (IR_node_t node),
            IR_node_t (*transformation_function) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-transform' is present in the SPRUT
        command line.  This function is used for transformation of
        directed acyclic graphs.  This is needed for various goals,
        e.g. for constant folding optimization.  At first the function
        calls guard function.  If the guard function returns zero, the
        function return the first parameter.  Otherwise when the guard
        function returns nonzero, all fields (including class fields
        if parameter `class_field_flag' is nonzero) of given node are
        also processed, i.e.  the fields values are changed.  And
        finally the node itself is processed by the transformation
        function (remember that the transformation function is never
        called for nodes which are parts of a graph cycle), and the
        result of transformation function is the result of given
        function.

    <item>Function
<tscreen><verb>
        `void IR_start (void)'
</verb></tscreen>
        is generated in any case.  This function is to be called
        before any work with internal representation.  The function
        initiates internal representation storage management (see next
        section), fulfills class field type specific initializations,
        evaluates actions bound to class fields, and make some other
        initiations.

    <item>Function
<tscreen><verb>
        `void IR_stop (void)'
</verb></tscreen>
        is generated in any case.  The call of this function is to be
        last.  The function fulfills class field type specific
        finalizations and finishes internal representation storage
        management.
     </enum>

<sect1>C++ SPI
<p>
SPRUT generates C++ SPI only when option `-c++' is present on the
command line.  Mainly C++ SPI is analogous to one on C.  Major
difference is that `IR_node_t' and `IR_double_link_t' are pointer to
classes not to structures.  As the consequence, the most of functions
are public or friend functions of the classes.

<sect2>C++ SPI types, variables, macros
<p>
C++ interface file of SPI consists of C++ declarations of the following
types, variables.
     <enum>
     <item>Type `IR_node_mode_t' is represented by enumeration
        definition.  There is enumeration constant with node type name
        and prefix `IR_NM_' for each node type declaration even for
        abstract node type.  Also there are enumeration constants with
        names `IR_NM__root' and `IR_NM__error' for and predefined type
        `%root' and for error nodes.  `IR_NM' is abbreviation of
        internal representation node mode.  There is also the
        enumeration name `IR_node_mode_enum' which is convenient to
        use in imported section for forward definition of pointer to
        this enumeration.

     <item>Type `IR_node_t' represents a node (more correctly pointer to
        a class representing node).  There are the type value
        `NULL' reserved to represent none node.
        <p>
        The class of this type is opaque (i.e. there are not public
        variables in the class) and all work with nodes are to be
        fulfilled through public or friend functions.  But to show
        efficacy of types implementation it should be said that every
        node type is turned into a structure declaration.  All these
        structures have first member of type `IR_node_mode_t'.  Other
        members represent the node fields except for SPRUT class
        field.  Depending on SPRUT command line option
        `-flat-structure' (see SPRUT usage) this structure can contain
        also members corresponding to fields declared in super types
        of given node type or member which type is structure
        corresponding to immediate super type of given node type.
        SPRUT class fields for each non-abstract node type are
        represented by only one separate structure.
        <p>
        The fields in different node types with the same name (when it
        is consequence of existing common super type with this field)
        have the same displacement from the structure begin because
        types of previous fields is guaranteed to be the same in these
        structures.  The fields in different node types with the same
        name (when it is not consequence of existing common super type
        with this field) may have the different displacement from the
        structure begin therefore access to such fields requires
        additional indirect addressing.
        <p>
        Double linked field (see internal representation description
        language) requires more memory (about in five times) for its
        implementation.  Speed of SPI work with double linked fields
        is sightly slower.  Because additional work is needed only to
        setting up the field value and my experience shows that
        usually number of setting up fields value is less than number
        of their fetching about in ten times.
        <p>
        Type `IR_node_t' is simply pointer to class representing node
        type `%root'.  The name of this class is `IR_node'.
        This name can be used in imported section for forward
        reference for nodes (instead of `IR_node_t').
        
     <item>Optional variable `IR_node_name' is array mapping values of
        type `IR_node_mode_t' to names (strings) in C++ (see also
        option -no-node-name in SPRUT usage).
        
     <item>Variable `IR_node_size' is array mapping values of type
        `IR_node_mode_t' to size of corresponding structures on C++.
     </enum>

<sect2>C++ Functions
<p>
C++ SPI interface file also contains definitions of generated
functions to quering characteritics of nodes, creation, deletion,
modification, comparison, copy, check, print, and binary input/output
of internal representation nodes and functions for access to values of
internal representation node fields.

These functions do not permit to work with abstract nodes.  Only one
graph function can be active, e.g.  call of function `IR_check_graph'
is not permitted during work of any traverse or transformation
function.

For sake of efficacy, the part of functions (access to internal
representation node fields and quering charateristics of the nodes) is
generated as inline.
     <enum>
     <item>Function `IR_is_type (IR_node_mode_t type, IR_node_mode_t
        super)' which is public static (i.e. which is relative to
        class not to a object of the class) function of class
        `IR_node' is evaluated as nonzero if the first argument of
        type `IR_node_mode_t' is equal to the second argument or node
        type represented by the first argument is a sub-type of node
        type represented by the second argument.  Otherwise the
        function returns zero.  But this function returns always zero
        for any error node, i.e.  this function can be used to define
        that the node of the first mode has fields of the node of the
        second mode.
        
     <item>Function `IR_node_mode (void)' declared as public in the class
        `IR_node' returns node mode represented by value of type
        `IR_node_mode_t' for given node.

     <item>Function `IR_is_of_type (IR_node_mode_t super)' declared as
        public in the class `IR_node' is abbreviation of frequently
        used `IR_is_type (node->IR_node_mode (), super)'.

     <item>Function `IR_node_level (void)' declared as public in the
        class `IR_node' has value which is internal representation
        description level in which declaration of given node type
        starts.

     <item>Access functions.  These functions declared as public in the
        class `IR_node' are generated when option `-access' is present
        in the SPRUT command line.  There is one function for each
        field with unique name.  Access function has name formed from
        prefix `IR_' and corresponding field name.  Access function
        has no arguments.  Type of returned value is predefined type
        (if the field is of such type) or `IR_node_t' (if the field is
        of a node type).
        <p>
        Function declared as public in the class `IR_node'
<tscreen><verb>
        `IR_double_link_t IR__first_double_link (void)'
</verb></tscreen>
        and functions declared as public in the class for which
        pointer of type `IR_double_link_t' refers
<tscreen><verb>
        `IR_double_link_t IR__next_double_link (void)',

        `IR_double_link_t IR__previous_double_link (void)'
</verb></tscreen>
        return pointer to fields which have double links to given
        node.  The node itself which contains such links can be
        determined by function declared as public in the class for
        which pointer of type `IR_double_link_t' refers
<tscreen><verb>
        `IR_node_t IR__owner (void)'.
</verb></tscreen>
        Here type `IR_double_link_t' represents pointer to class
        representing double fields.  The functions may also check up
        that the node has given field (see SPRUT options).

     <item>Modification functions.  These functions declared as public in
        the class `IR_node' are generated when option `-set' is
        present in the SPRUT command line.  There is one functions for
        each field with unique name.  Modification function has name
        formed from prefix `IR_set_' and corresponding field name.
        <p>
        Modification function has one argument is of predefined type
        (if the field is of such type) or of type `IR_node_t' (if the
        field is of a node type).  Argument represents new value of
        the field.
        <p>
        The function may check up constraint if the field represents
        arc to node of a node type or its sub-types (see SPRUT
        options).  The functions may also check up that the node has
        given field.
        <p>
        There is also function declared as public in the class for
        which pointer of type `IR_double_link_t' refers for
        modification of double links
<tscreen><verb>
        `void IR__set_double_link (IR_node_t value)'
</verb></tscreen>
        Remember that values of `IR__next_double_link' and
        `IR__previous_double_link' are changed after calling this
        function.

     <item>Function declared as friend of class `IR_node'
<tscreen><verb>
        `IR_node_t IR_create_node (IR_node_mode_t node_mode)'
</verb></tscreen>
        is generated in any case.  This function allocates storage for
        node of any type (except for abstract) represented by the
        argument (it can be also `IRNM__error), sets up node mode and
        node level, fulfills fields assignments (except for class
        fields) in the same order as the fields are declared.  The
        field assignment is fulfilled according to type specific
        operation (see section `Type specific macros') and actions
        which are defined after given field in sections of skeleton
        and other fields of corresponding node type.  After that the
        function returns the created node.  The single way to create
        error nodes is to use this function with argument
        `IRNM__error'.  Remember that class `IR_node' has no public
        constructors and destructors.

     <item>Node type specific creation functions declared as friend of
        class `IR_node'.  These functions are generated when option
        `-new' is present in the SPRUT command line.  There is one
        function for each node type (except for abstract).  Names of
        functions are formed from prefix `IR_new_' and corresponding
        node type name.  The number of parameters of a function is
        equal to one of skeleton fields of corresponding node type.
        The parameters of these functions have to be given in the
        order of the skeleton fields in the specification.  Fields of
        the super-type (recursively) precede the ones of the sub-type.
        <p>
        These functions may check up constraints on skeleton fields
        which represent arc to node of a node type or its sub-types
        (see SPRUT options).  These functions call node creation
        function and after that assign parameters values to
        corresponding skeleton fields.  After that the functions
        return the created node.  These functions provide a mechanism
        similar to record aggregates.  Nested calls of such functions
        allow programming with terms as in LISP.

     <item>Function declared as friend of class `IR_node'
<tscreen><verb>
        `void IR_free_node (IR_node_t node)'
</verb></tscreen>
        is generated when option `-free' or `-free-graph' is present
        in the SPRUT command line.  This function deletes given node.
        The deletion consists of evaluation of finalization macros for
        node fields (see field type specific macros) in reverse order
        and all node space deallocation.  The function also delete
        double linked fields of given node from the corresponding
        lists of double linked fields.  But the user should know that
        there may be dangling references to given node itself after
        the function call.  Remember also that class `IR_node' has no
        public constructors and destructors.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `void IR_free_graph (void)'
</verb></tscreen>
        is generated when option `-free-graph' is present in the SPRUT
        command line.  This function deletes given node and all nodes
        accessible from given node.  The nodes are deleted in depth
        first order.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `void IR_conditional_free_graph
                (int (*guard) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-free-graph' is present in the SPRUT
        command line.  This function deletes given node and all nodes
        accessible from given node.  The nodes are deleted in depth
        first order.  The processing (traversing and deleting)
        children of node which is passed to the parameter-function is
        not fulfilled if the parameter-function returns zero.  All
        graph is deleted when the returned value is always nonzero.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `IR_node_t IR_copy_node (void)'
</verb></tscreen>
        is generated when option `-copy' or `-copy-graph' is present
        in the SPRUT command line.  This function makes copy of given
        node.  Field type specific macros are used (see section `Type
        specific macros') to make this.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `IR_node_t IR_copy_graph (void)'
</verb></tscreen>
        is generated when option `-copy-graph' is present in the
        command line.  This function makes copy of graph given by its
        node.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `IR_node_t IR_conditional_copy_graph
                          (int (*guard) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-copy-graph' is present in the
        command line.  This function makes copy of graph given by its
        node.  The processing (traversing and copying) children of
        node which is passed to the parameter-function is not
        fulfilled if the parameter-function returns zero.  All nodes
        of graph are copied when the returned value is always nonzero.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `int IR_is_equal_node (IR_node_t node_2)'.
</verb></tscreen>
        is generated when option `-equal' or `-equal-graph' is present
        in the SPRUT command line.  This function returns nonzero iff
        given node is equal to `node_2', i.e.  given node and node_2
        have the same type and all fields of given node are equal to
        the corresponding fields of `node_2'.  Field type specific
        macros are used (see section `Type specific macros') to make
        this.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `int IR_is_equal_graph (IR_node_t graph_2)'
</verb></tscreen>
        is generated when option `-equal-graph' is present in the SPRUT
        command line.  This function returns nonzero iff graph
        starting with given node is equal to graph starting with
        node `graph_2', i.e.  the graphs have the same structure and
        all predefined type fields of given node are equal to the
        corresponding fields of `graph_2'.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `int IR_is_conditional_equal_graph
               (IR_node_t graph_2, int (*guard) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-equal-graph' is present in the
        SPRUT command line.  This function returns nonzero iff graph
        starting with given node is equal to graph starting with node
        `graph_2', i.e. the graphs have the same structure and all
        predefined type fields of given node are equal to the
        corresponding fields of `graph_2'.  The processing (traversing
        and comparing) children of node which is passed to the
        parameter-function is not fulfilled if the parameter-function
        returns zero.  All nodes of the graphs are compared when the
        returned value is always nonzero.  Unprocessed graph nodes are
        believed to be equal.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `int IR_check_node (int class_field_flag)'
</verb></tscreen>
        This function is generated when option `-check' or
        `-check-graph' is present in the SPRUT command line.  By
        default the most of generated functions which work with
        internal representation nodes do not check up constraints
        which described in the specification.
        <p>
        There are two kinds of constraints.  The first is constraint
        on field which represents arc to node of given type or its
        sub-types.  The second is constraint which defined by target
        code (see the internal representation definition language).
        The user is responsible to adhere to the constraints.
        Function `IR_check_node' can be used to check all constraints
        corresponding to given node.  In case of a constraint
        violation the involved node and all child nodes are printed on
        standard error and the function returns nonzero (error flag).
        If the parameter value is zero then class fields of given node
        are not checked up.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `int IR_check_graph (int class_field_flag)'
</verb></tscreen>
        is generated when option `-check-graph' is present in the
        SPRUT command line.  This function checks given node and all
        nodes accessible from given node.  It should be known that a
        class field is processed only when the parameter value is
        nonzero.  In case of fixing any constraint violation returns
        nonzero (error flag).

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `int IR_conditional_check_graph
               (int class_field_flag,
                int (*guard) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-check-graph' is present in the
        SPRUT command line.  This function checks given node and all
        nodes accessible from given node.  It should be known that a
        class field is processed only when the first parameter value
        is nonzero.  In case of fixing any constraint violation
        returns nonzero (error flag).  The processing (traversing and
        checking) children of node which is passed to the
        parameter-function is not fulfilled if the parameter-function
        returns zero.  All nodes of the graph are checked when the
        returned value is always nonzero.  It is better to free
        changed nodes which are not used after transformation
        especially when there are double links to the nodes (otherwise
        the nodes can be accessible with the aid of functions for work
        with double links).

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `void IR_print_node (int class_field_flag)'
</verb></tscreen>
        is generated when option `-print' is present in the SPRUT
        command line or options `-check' or `check-graph' is present
        because check functions use this print function.  The function
        outputs values of node fields with their names to standard
        output in readable form.  To make this the function outputs
        sequentially all the node fields (including class fields if
        the parameter value is nonzero) with the aid of field
        type specific macros (see below).

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `int IR_output_node (FILE *output_file, int level)',
</verb></tscreen>
        and function declared as friend of class `IR_node'
<tscreen><verb>
        `IR_node_t IR_input_node (FILE *input_file,
                                  IR_node_t *original_address)'
</verb></tscreen>
        are generated when option correspondingly `-output' or
        `-input' is present in the SPRUT command line.
        <p>
        Function `IR_output_node' writes node to given file.  To make
        this the function outputs given node address and after that
        sequentially all the node fields (except for class fields)
        whose declarations are present in internal representation
        description of `level' or less than the one (see internal
        representation description language).  The node type must be
        also declared in internal representation description of
        `level' or less than the one.  A nonzero function result code
        means fixing an error during output.
        <p>
        Function `IR_input_node' reads node from given file, allocates
        space for the node, initiates its fields and changes the node
        fields output early.  To make this the function uses function
        `create_node'.  The output level of input node must be less or
        equal to the internal representation level of given SPI.  Null
        value returned by the function means fixing an error during
        input.  The function returns original address of input node
        through the second parameter.  The output and input of fields
        is fulfilled with the aid of field type specific macros (see
        section `Type specific macros').

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `void IR_traverse_depth_first
              (int class_field_flag,
               void (*function) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-traverse' is present in the SPRUT
        command line.  This function traverses graph given by its node
        in depth first order (it means bottom up for tree).  Arcs
        represented by class fields are included in this graph if the
        first parameter value is nonzero.  At every node a function
        given as parameter is executed.  Arcs implementing lists of
        double linked fields are not traversed.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `void IR_traverse_reverse_depth_first
              (int class_field_flag,
               int (*function) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-reverse-traverse' is present in the
        SPRUT command line.  This function is analogous to the previous
        but the graph is traversed in reverse depth first order (it
        means top down order for tree).  The traverse of children of
        node which is passed to the parameter-function is not
        fulfilled if the parameter-function returns zero.  All the graph
        is traversed when the returned value is always nonzero.

    <item>Function declared as public in the class `IR_node'
<tscreen><verb>
        `IR_node_t IR_transform_dag
           (int class_field_flag,
            int (*guard_function) (IR_node_t node),
            IR_node_t (*transformation_function) (IR_node_t node))'
</verb></tscreen>
        is generated when option `-transform' is present in the SPRUT
        command line.  This function is used for transformation of
        directed acyclic graphs.  This is needed for various goals,
        e.g. for constant folding optimization.  At first the function
        calls guard function.  If the guard function returns zero, the
        function return given node.  Otherwise when the guard
        function returns nonzero, all fields (including class fields
        if parameter `class_field_flag' is nonzero) of given node are
        also processed, i.e.  the fields values are changed.  And
        finally the node itself is processed by the transformation
        function (remember that the transformation function is never
        called for nodes which are parts of a graph cycle), and the
        result of transformation function is the result of given
        function.

    <item>Function
<tscreen><verb>
        `void IR_start (void)'
</verb></tscreen>
        is generated in any case.  This function is to be called
        before any work with internal representation.  The function
        initiates internal representation storage management (see next
        section), fulfills class field type specific initializations,
        evaluates actions bound to class fields, and make some other
        initiations.

    <item>Function
<tscreen><verb>
        `void IR_stop (void)'
</verb></tscreen>
        is generated in any case.  The call of this function is to be
        last.  The function fulfills class field type specific
        finalizations and finishes internal representation storage
        management.
     </enum>

<sect1>Type specific macros
<p>
C and C++ SPI uses some macros which work with node fields.  These
macros are field type specific and are generated by SPRUT for each
predefined types and type `IR_node_t'.  All these macros can be
redefined.  There are the following field type specific macros.
     <enum>
     <item>Initialization and finalization macros.  These macros can
        assign an initial value to field or/and even construct complex
        data structures.

        Finalization is performed immediately before the node is
        deleted.  For example finalization macro can release memory
        space dynamically allocated by initialization macro.  These
        macros have names formed from prefixes correspondingly
        `IR_BEGIN_' and `IR_END_' and name of the field type, e.g.

        `IR_BEGIN_integer'
        or `IR_END_IR_node_t'.

        By default initialization macros have definition
<tscreen><verb>
           `bzero (& (a), sizeof (a))'
</verb></tscreen>
        where `a' is the macros argument.  Finalization macros do
        nothing.  It is very important for correct work of double
        linked fields that initialization macro for `IR_node_t'
        initiates a pointer by NULL value.

     <item>Copy macros.  The operation copy is used by copy functions
        generated by SPRUT.  These macros have names formed from prefix
        `IR_COPY_' and name of the field type.  The default macros
        definitions are
<tscreen><verb>
           `((a) = (b))'
</verb></tscreen>
        where `a' and `b' are the macro parameters representing fields
        of given type.  Therefore, pointer semantics is assumed for
        fields of a pointer type.  The user has to take care about the
        macros redefinition if value semantics is needed.

     <item>Equality macros.  These macros check whether two fields are
        equal.  They are used in functions which test the equality of
        nodes.  These macros have names formed from prefix `IR_EQUAL_'
        and name of the type.  The default macros definitions are
<tscreen><verb>
           `((a) == (b))'
</verb></tscreen>
        where `a' and `b' are the macro parameters representing fields
        of given type.

     <item>Print macros.  These macros are used by print function
        generated by SPRUT.  These macros have names formed from prefix
        `IR_PRINT_' and name of the type.  By default the macros for
        `IR_node_t' is defined as
<tscreen><verb>
           `printf ("%lx", (unsigned long) (a))'
</verb></tscreen>
        where `a' is macro parameter.  The macros for other types do
        nothing.

     <item>Input/output macros.  These macros are used by input/output
        functions generated by SPRUT.  These macros have names formed
        from prefixes `IR_INPUT_' and `IR_OUTPUT_' and name of the
        type.  By default the macros have definitions
<tscreen><verb>
        `(fwrite (& (field), sizeof (field), 1, (file))
                          != sizeof (field))'

        and `(fread (& (field), sizeof (field), 1, (file))
                          != sizeof (field))'
</verb></tscreen>
        where `file' and `field' are the macros parameters.  The
        definitions may be more complicated for predefined types.
     </enum>
It should be repeated that it is possible to redefine the operations
by including new macro definitions in the C/C++ declaration section.  For
example
<tscreen><verb>
    %import{
    typedef int PT_line, PT_position;
    }
    %local{
    #define IR_BEGIN_PT_line(l) (l) = ...
    #define IR_BEGIN_PT_position(p) (p) = ...
    #define IR_BEGIN_IR_node_t (n) (n) = ...
    }
    %type PT_line PT_position PT_boolean

    %%
    %abstract
    node :: %root
      line : PT_line
      position : PT_position
    ...
</verb></tscreen>

<sect1>Storage management macros
<p>
SPRUT completely automatically generates macros of storage management
for the nodes.  Usually, the user does not have to care about it.  The
predefined storage management uses C/C++ standard functions for global
storage with free lists.  The default macro definitions are placed
before default field type specific macro definitions but after all
code insertions.  The user can create own storage manager by
redefinition of one or more the following macros and placing them in a
C/C++ declaration section.  But the user should know that all
functions generated by SPRUT believe that the storage can not change
its place after the allocation.
     <enum>
     <item>Macros `IR_START_ALLOC()', `IR_STOP_ALLOC()' are evaluated in
        functions correspondingly `IR_start' and `IR_stop' and are to
        be used to start and finish work with the storage manager.

     <item>Macros `IR_ALLOC(ptr, size, ptr_type)', `IR_FREE(ptr, size)'
        allocate and free storage whose size is given as the second
        parameter.  The first parameter serves to return pointer to
        memory being allocated or to point to memory being freed.  The
        third parameter is type of `ptr'.
     </enum>
By default these macros are defined as follows:
<tscreen><verb>
    #define IR_START_ALLOC()
    #define IR_STOP_ALLOC()
    #define IR_ALLOC(ptr, size, ptr_type)\
                                 ((ptr) = (ptr_type) malloc (size))
    #define IR_FREE(ptr, size)   free (ptr)
</verb></tscreen>

<sect>SPRUT Usage
<p>
<tscreen><verb>
%%%
</verb></tscreen>

<sect>Appendix 1 - Syntax of internal representation description language
<p>
YACC notation is used to describe full syntax of internal
representation description language.
<tscreen><verb>

  %token PERCENTS COMMA COLON DOUBLE_COLON SEMICOLON
         IDENTIFIER CODE_INSERTION EXPRESSION ADDITIONAL_C_CODE

  %token DOUBLE EXTEND LOCAL IMPORT EXPORT TYPE ROOT ABSTRACT CLASS
         SKELETON OTHER 

  %start description

  %%

  description : declaration_part PERCENTS node_type_definition_list
                ADDITIONAL_C_CODE
              ;

  declaration_part :
                   | declaration_part DOUBLE any_node_type_name
                   | declaration_part EXTEND IDENTIFIER
                   | declaration_part predefined_types_declaration
                   | declaration_part LOCAL CODE_INSERTION
                   | declaration_part IMPORT  CODE_INSERTION
                   | declaration_part EXPORT  CODE_INSERTION
                   ;

  predefined_types_declaration : TYPE 
                               | predefined_types_declaration IDENTIFIER
                               ;

  node_type_definition_list : node_type_definition
                            | node_type_definition_list
                                 SEMICOLON  node_type_definition
                            ;

  node_type_definition :
                       | abstract_node_flag type_nodes_identifier_list
                            optional_immediate_super_type_list
                            class_field_definition_part
                            skeleton_field_definition_part
                            other_field_definition_part
                       ;

  abstract_node_flag :
                     | ABSTRACT
                     ;

  type_nodes_identifier_list : identifier_list
                             ;

  optional_immediate_super_type_list :
                                     | immediate_super_type_list
                                     ;

  immediate_super_type_list : DOUBLE_COLON any_node_type_name
                            | DOUBLE_COLON COMMA any_node_type_name
                            | immediate_super_type_list COMMA
                                any_node_type_name
                            ;

  any_node_type : ROOT
                | IDENTIFIER
                ;

  class_field_definition_part :
                              | CLASS field_definition_list
                              ;

  skeleton_field_definition_part :
                                 | SKELETON field_definition_list
                                 ;

  other_field_definition_part :
                              | OTHER field_definition_list
                              ;

  field_definition_list :
                        | field_definition_list field_definition
                        | field_definition_list constraint
                        | field_definition_list action
                        ;

  field_definition : field_identifier_list  COLON  optional_double
                       any_node_type_name
                   ;

  optional_double :
                  | DOUBLE
                  ;

  constraint : EXPRESSION
             ;

  action : CODE_INSERTION
         ;

  field_identifier_list : identifier_list
                        ;

  identifier_list : IDENTIFIER
                  | identifier_list  COMMA  IDENTIFIER
                  ;
</verb></tscreen>

</article>