Welcome to ABC, the ANTLR-Based C front-end. ABC is a Java program for parsing and manipulating programs written in C and possibly some languages extending C, such as CIVL-C. It can be used to perform a number of tasks, including the following:

  1. preprocess the source file(s)
  2. parse the preprocessed source to form an Abstract Syntax Tree representation of a translation unit
  3. analyze an AST to determine the type of every expression, the entity associated to every identifier, the scope of every node, and so on
  4. merge multiple ASTs into one large AST
  5. transform ASTs, by, for example, removing expressions with side-effects, renaming entities, pruning unreachable code, etc.
In addition, it provides a framework for developing your own analyses or transformations on ASTs.

There is a simple command-line interface for ABC (see {@link dev.civl.abc.ABC ABC}), but most users will want to use ABC through its API. To use the API, it is helpful to have some understanding of the modular structure of ABC. The ABC source code is decomposed into modules, each with a well-defined interface and set of responsibilities. Some of these modules are decomposed further into sub-modules. The top-level modules are:
  1. util
    1. responsibilities: simple general-purpose utility classes that do not use other parts of ABC
    2. uses: nothing
    3. interface: {@link dev.civl.abc.util.IF}
    4. entry point: none
  2. config
    1. responsibilities: representation of configuration parameters for ABC
    2. uses: nothing
    3. interface: {@link dev.civl.abc.config.IF}
    4. entry point: {@link dev.civl.abc.config.IF.Configurations Configurations}
  3. token
    1. responsibilities: representing tokens; keeping track of the origin and history of each token through macro expansion and inclusion; representing characters and strings
    2. uses: util
    3. interface: {@link dev.civl.abc.token.IF}
    4. entry point: {@link dev.civl.abc.token.IF.Tokens Tokens}
  4. front
    1. responsibilities: preprocessing and parsing a file to produce an ANTLR tree representation of a translation unit
    2. uses: util, config, token
    3. interface: {@link dev.civl.abc.front.IF},
    4. entry point:
    5. submodules
      1. preproc
        1. responsibilities: preprocessing a file to generate a post-preprocessor token stream
        2. uses: util, config, token
        3. interface: {@link dev.civl.abc.front.c.preproc.IF}, {@link dev.civl.abc.front.fortran.preproc.IF}
        4. entry point: {@link dev.civl.abc.front.c.preproc.IF.Preprocess Preprocess}, {@link dev.civl.abc.front.fortran.preproc.IF.Preprocess Preprocess}
      2. parse
        1. responsibilities: parsing a token stream to produce an ANTLR tree representation of a translation unit
        2. uses: util, config, token
        3. interface: {@link dev.civl.abc.front.c.parse.IF}, {@link dev.civl.abc.front.fortran.parse.IF}
        4. entry point: {@link dev.civl.abc.front.c.parse.IF.Parse Parse}, {@link dev.civl.abc.front.fortran.parse.IF.Parse Parse}
      3. ptree
  5. ast
    1. responsibilities: representation and manipulation of an Abstract Syntax Tree and associated entities
    2. uses: util, token
    3. interface: {@link dev.civl.abc.ast.IF}
    4. entry point: {@link dev.civl.abc.ast.IF.ASTs ASTs}
    5. submodules
      1. value
        1. responsibilities: representation of concrete value, such as characters, integers, floating point values
        2. interface: {@link dev.civl.abc.ast.value.IF}
        3. entry point: {@link dev.civl.abc.ast.value.IF.Values Values}
      2. type
        1. responsibilities: representation of types
        2. interface: {@link dev.civl.abc.ast.type.IF}
        3. entry point: {@link dev.civl.abc.ast.type.IF.Types Types}
      3. entity
        1. responsibilities: representation of abstract program entities which can be named by an identifier, including variables, functions, labels, scopes, structures, unions, enumerations, enumerators, and typedefs
        2. interface: {@link dev.civl.abc.ast.entity.IF}
        3. entry point: {@link dev.civl.abc.ast.entity.IF.Entities Entities}
      4. conversion
        1. responsibilities: representation of C's implicit conversions, such as the conversion of an array to a pointer to the first element of the array, and so on
        2. interface: {@link dev.civl.abc.ast.conversion.IF}
        3. entry point: {@link dev.civl.abc.ast.conversion.IF.Conversions Conversions}
      5. node
        1. responsibilities: representation of AST nodes
        2. interface: {@link dev.civl.abc.ast.node.IF}
        3. entry point: {@link dev.civl.abc.ast.node.IF.Nodes Nodes}
  6. astgen
    1. responsibilities: translation of ANTLR tree to AST
    2. uses: util, token, front, ast
    3. interface: {@link dev.civl.abc.astgen.IF}, {@link dev.civl.abc.astgen.c.IF}, {@link dev.civl.abc.astgen.fortran.IF}
    4. entry point: {@link dev.civl.abc.astgen.IF.ASTGenerator}
  7. analysis
    1. responsibilities: analyzing AST, creation of entities, resolution of all identifiers, determination of all scopes, types, and entities
    2. uses: config, token, ast
    3. interface: {@link dev.civl.abc.analysis.IF}
    4. entry point: {@link dev.civl.abc.analysis.IF.Analysis Analysis}
  8. transform
    1. responsibilities: transformations of an AST
    2. uses: token, ast
    3. interface: {@link dev.civl.abc.transform.IF}
    4. entry point: {@link dev.civl.abc.transform.IF.Transform Transform}
  9. program
    1. responsibilities: mutable representation of a program
    2. uses: token, ast, analysis, transform
    3. interface: {@link dev.civl.abc.program.IF}
    4. entry point: {@link dev.civl.abc.program.IF.Programs Programs}
  10. main
    1. responsibilities: command line interface, Activator class for marshaling of tools in tool chain
    2. uses: util, token, front, ast, astgen, analysis, transform, program
    3. interface: {@link dev.civl.abc}
    4. entry point: {@link dev.civl.abc.ABC ABC}