Module dev.civl.abc
Package dev.civl.abc.transform.IF

Interface Transformer

All Known Subinterfaces:
NameTransformer
All Known Implementing Classes:
BaseTransformer
public interface Transformer
A Transformer is a tool used to transform an AST in some way, or, more precisely, it provides a method transform(AST) which takes an AST and returns the transformed AST.

The AST returned may or may not be the same object as the given AST: some transformers might modify the given AST in place, while others might return an entirely new AST with or without modifying the original one. This choice is entirely up to the individual Transformer, but should be clearly documented in the Transformer's javadoc.

Every Transformer should be reusable, i.e., it should be possible to use a single transformer object to transform multiple ASTs, as in 

 newAST1 = transformer.transform(ast1);
 newAST2 = transformer.transform(ast2); // using same transformer
 ...
The easiest way to ensure this is to have the transformer instantiate a new object each time transform(AST) is invoked. The new object is responsible for carrying out the transformation for that specific invocation, it maintains all the state that is needed for that invocation, and it goes away when the invocation completes.

  • Method Details

    • getCode

      String getCode()
      Returns the short name of this transformer, e.g., "mpi", or "prune".
      Returns:
      the short name ("code") of this transformer

    • getShortDescription

      String getShortDescription()
      A brief (one line) description of what this transformer does, suitable for appearing in a help message.
      Returns:
      a short description of what this transformer does

    • toString

      String toString()
      Returns the long name of this transformer, e.g., "MPI Transformer" or "Pruner". The name is suitable for human consumption.
      Overrides:
      toString in class Object
      Returns:
      long name of this transformer

    • transform

      AST transform(AST ast) throws SyntaxException
      Apply a transformation to a translation unit. This may or may not result in modifications to the given AST, and may or may not return a new AST instance (as opposed to the given one).
      Parameters:
      ast - The abstract syntax tree being transformed
      Returns:
      the transformed AST, which may or may not be the same object that was given
      Throws:
      SyntaxException - If it encounters an error in the AST or an some case which it cannot handle

    • newStringLiteralNode

      StringLiteralNode newStringLiteralNode(String method, String representation) throws SyntaxException
      Produces a new StringLiteralNode.
      Parameters:
      method - name of transformer method responsible for producing the new token; used to form the Formation that will ultimately be used in diagnostic message
      representation - the text of the string literal exactly as it would appear in a program source; this must include the surrounding (single or double) quotes
      Returns:
      new string literal node
      Throws:
      SyntaxException - if the representation does not conform to the C11 specification of string literals