gov.llnl.babel.backend
Class CodeSplicer

java.lang.Object
  extended by gov.llnl.babel.backend.CodeSplicer

public class CodeSplicer
extends java.lang.Object

Class CodeSplicer splices code segments from an existing user file into a new automatically generated file. The intended use of the code splicer is to preserve user edits to generated code. The new file replaces the original one; however, the code splicer preserves areas delineated with the pair of strings: DO-NOT-DELETE splicer.begin(symbol) DO-NOT-DELETE splicer.end(symbol) embedded in comments in both the edited and generated files. The code splicer also tracks which symbols were not used in the newly generated file, and these symbols may be output at the end of the new file to preserve code for the user. IMPORTANT: After introduction of splicer blocks into the AST and Symbol Table, the rules for processing changed. The precedence, from highest to least, is now as follows: 1) Legacy file splicer contents (if _any_ are populated); 2) AST contents (which are assumed to have been transferred to the symbol table; then 3) Default contents.


Field Summary
static java.lang.String S_HEADER
           
static java.lang.String S_SOURCE
           
 
Constructor Summary
CodeSplicer(SymbolID id, boolean isSource, boolean prependFullName, Context context)
          Create a CodeSplicer that does not contain contents obtained from a file.
CodeSplicer(SymbolID id, java.io.BufferedReader reader, java.lang.String vpath, java.lang.String path, boolean isSource, boolean prependFullName, Context context)
          Create a new instance of the code splicer class.
 
Method Summary
static java.lang.String getBeginString(java.lang.String symbol)
          Return the code splicer start string for the beginning of a code splice region.
 java.lang.String getEditString(java.lang.String symbol)
          Retrieve the edit string associated with the specified symbol.
static java.lang.String getEndString(java.lang.String symbol)
          Return the code splicer end string for the closing of a code splice region.
 java.util.Set getSymbols()
          Retrieve a Set of the symbols in the symbol edit database.
 java.lang.String getVPath()
          query the current vpath setting "." indicates no vpath
 boolean hasSymbol(java.lang.String symbol)
          Query whether the specified symbol exists in the symbol database.
 boolean hasUnusedSymbolEdits()
          Returns TRUE if there is at least one unused edit in the symbol edit database.
 void outputSymbolEdits(java.lang.String symbol, LanguageWriter writer)
          Output symbol information to the specified output print writer.
 void outputUnusedSymbolEdits(LanguageWriter writer)
          Output the unused edits in the symbol edit database.
 void outputUnusedSymbolEdits(java.io.PrintWriter writer)
          Output the unused edits in the symbol edit database.
 void renameSymbol(java.lang.String oldName, java.lang.String newName)
          If a symbol by the name oldName exists, rename it to newName.
 void setLineRedirector(LineRedirector lr)
           
 void setVPath(java.lang.String vpath)
          explicitly set the vpath.
 void splice(java.lang.String symbol, LanguageWriter writer, java.lang.String alt_msg)
          The easiest method to envoke to create a spliced region during code generation.
 void splice(java.lang.String symbol, LanguageWriter writer, java.lang.String alt_msg, java.lang.String alt_code)
          The easiest method to envoke to create a spliced region during code generation.
 void splice(java.lang.String symbol, LanguageWriter writer, java.lang.String alt_msg, java.lang.String[] comment_code)
          The initial code is an array of lines.
 void splice(java.lang.String symbol, LanguageWriter writer, java.lang.String alt_msg, java.lang.String[] comment_code, java.lang.String[] live_code)
          The initial code is an array of lines.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

S_HEADER

public static final java.lang.String S_HEADER
See Also:
Constant Field Values

S_SOURCE

public static final java.lang.String S_SOURCE
See Also:
Constant Field Values
Constructor Detail

CodeSplicer

public CodeSplicer(SymbolID id,
                   java.io.BufferedReader reader,
                   java.lang.String vpath,
                   java.lang.String path,
                   boolean isSource,
                   boolean prependFullName,
                   Context context)
            throws java.io.IOException
Create a new instance of the code splicer class. The constructor will read data from the buffered reader stream and throw an IO exception if any error condition is encountered while reading from the file. The code splices are stored in a map with keyvalues that are the region symbols and corresponding symbols that are the lines of code retrieved from the file.

Throws:
java.io.IOException

CodeSplicer

public CodeSplicer(SymbolID id,
                   boolean isSource,
                   boolean prependFullName,
                   Context context)
Create a CodeSplicer that does not contain contents obtained from a file. (See "IMPORTANT" under class comments for CodeSplicer population rules.) Note that an empty CodeSplicer does not have any stored symbols.

Method Detail

getBeginString

public static java.lang.String getBeginString(java.lang.String symbol)
Return the code splicer start string for the beginning of a code splice region. The symbol string must be unique within this file. The symbol may not contain a close parenthesis.


getEndString

public static java.lang.String getEndString(java.lang.String symbol)
Return the code splicer end string for the closing of a code splice region. The symbol string must be unique within this file and must match the string used to open the splice region. The symbol may not contain a close parenthesis.


setLineRedirector

public void setLineRedirector(LineRedirector lr)

getVPath

public java.lang.String getVPath()
query the current vpath setting "." indicates no vpath


setVPath

public void setVPath(java.lang.String vpath)
explicitly set the vpath. Note that vpath=null, "" or "." are all handled internally as "."


hasSymbol

public boolean hasSymbol(java.lang.String symbol)
Query whether the specified symbol exists in the symbol database. The symbol may not contain a close parenthesis and it may not start or end with white space.


outputSymbolEdits

public void outputSymbolEdits(java.lang.String symbol,
                              LanguageWriter writer)
Output symbol information to the specified output print writer. If the symbol does not exist in the database, then nothing is output to the print stream. If the symbol exists, then the symbol begin and end comments are output as well as any text between those comments. The symbol may not contain a close parenthesis and it may not start or end with white space.


getEditString

public java.lang.String getEditString(java.lang.String symbol)
Retrieve the edit string associated with the specified symbol. If no symbol exists in the database, then return null. The symbol may not contain a close parenthesis and it may not start or end with white space.


hasUnusedSymbolEdits

public boolean hasUnusedSymbolEdits()
Returns TRUE if there is at least one unused edit in the symbol edit database. See outputUnusedSymbolEdits() for more information.


outputUnusedSymbolEdits

public void outputUnusedSymbolEdits(java.io.PrintWriter writer)
Output the unused edits in the symbol edit database. These symbols were read from the input file but were not used in the output file. The symbols will be output to the specified output print writer in no particular order. WARNING: This version outputs raw splicer block tag lines (i.e., without conversion to language-specific!


outputUnusedSymbolEdits

public void outputUnusedSymbolEdits(LanguageWriter writer)
Output the unused edits in the symbol edit database. These symbols were read from the input file but were not used in the output file. The symbols will be output to the specified output print writer in no particular order. NOTE: This version relies on the writer to generate the proper, language-specific splicer block name and comment line.


getSymbols

public java.util.Set getSymbols()
Retrieve a Set of the symbols in the symbol edit database. Each entry in the set is a string representing a symbol.


splice

public void splice(java.lang.String symbol,
                   LanguageWriter writer,
                   java.lang.String alt_msg)
The easiest method to envoke to create a spliced region during code generation.

Parameters:
symbol - The string symbol to match. Should be unique in a file
writer - The LanguageWriter to embed the symbols in appropriate comments
alt_msg - An alternate message to embed in comments only if no information was found by the splicer.

splice

public void splice(java.lang.String symbol,
                   LanguageWriter writer,
                   java.lang.String alt_msg,
                   java.lang.String alt_code)
The easiest method to envoke to create a spliced region during code generation.

Parameters:
symbol - The string symbol to match. Should be unique in a file
writer - The LanguageWriter to embed the symbols in appropriate comments
alt_msg - An alternate message to embed in comments only if no
alt_code - A default code chunk (used for languages that REQUIRE a return value (or some such) information was found by the splicer.

splice

public void splice(java.lang.String symbol,
                   LanguageWriter writer,
                   java.lang.String alt_msg,
                   java.lang.String[] comment_code)
The initial code is an array of lines. Each line will be written inside a block comment

Parameters:
symbol - The string symbol to match. Should be unique in a file
writer - The LanguageWriter to embed the symbols in appropriate comments
alt_msg - An alternate message to embed in comments only if no
comment_code - A default code chunk that will be included in a block comment. information was found by the splicer.

splice

public void splice(java.lang.String symbol,
                   LanguageWriter writer,
                   java.lang.String alt_msg,
                   java.lang.String[] comment_code,
                   java.lang.String[] live_code)
The initial code is an array of lines. Each line will be written inside a block comment

Parameters:
symbol - The string symbol to match. Should be unique in a file
writer - The LanguageWriter to embed the symbols in appropriate comments
alt_msg - An alternate message to embed in comments only if no information was found by the splicer.
comment_code - A default code chunk that will be included in a comment block only if no information was found by the splicer.
live_code - A default code chunk that will be included only if no information was found by the splicer.

renameSymbol

public void renameSymbol(java.lang.String oldName,
                         java.lang.String newName)
If a symbol by the name oldName exists, rename it to newName. If the oldName doesn't appear, nothing happens.

Parameters:
oldName - the name of symbol to rename
newName - this is the new name if the old one exists.