gov.llnl.babel.backend

Class 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 String
S_HEADER
static String
S_SOURCE

Constructor Summary

CodeSplicer(SymbolID id, BufferedReader reader, String vpath, String path, boolean isSource, boolean prependFullName, Context context)
Create a new instance of the code splicer class.
CodeSplicer(SymbolID id, boolean isSource, boolean prependFullName, Context context)
Create a CodeSplicer that does not contain contents obtained from a file.

Method Summary

static String
getBeginString(String symbol)
Return the code splicer start string for the beginning of a code splice region.
String
getEditString(String symbol)
Retrieve the edit string associated with the specified symbol.
static String
getEndString(String symbol)
Return the code splicer end string for the closing of a code splice region.
Set
getSymbols()
Retrieve a Set of the symbols in the symbol edit database.
String
getVPath()
query the current vpath setting "." indicates no vpath
boolean
hasSymbol(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(String symbol, LanguageWriter writer)
Output symbol information to the specified output print writer.
void
outputUnusedSymbolEdits(PrintWriter writer)
Output the unused edits in the symbol edit database.
void
outputUnusedSymbolEdits(LanguageWriter writer)
Output the unused edits in the symbol edit database.
void
renameSymbol(String oldName, String newName)
If a symbol by the name oldName exists, rename it to newName.
void
setLineRedirector(LineRedirector lr)
void
setVPath(String vpath)
explicitly set the vpath.
void
splice(String symbol, LanguageWriter writer, String alt_msg)
The easiest method to envoke to create a spliced region during code generation.
void
splice(String symbol, LanguageWriter writer, String alt_msg, String alt_code)
The easiest method to envoke to create a spliced region during code generation.
void
splice(String symbol, LanguageWriter writer, String alt_msg, String[] comment_code)
The initial code is an array of lines.
void
splice(String symbol, LanguageWriter writer, String alt_msg, String[] comment_code, String[] live_code)
The initial code is an array of lines.

Field Details

S_HEADER

public static final String S_HEADER

S_SOURCE

public static final String S_SOURCE

Constructor Details

CodeSplicer

public CodeSplicer(SymbolID id,
                   BufferedReader reader,
                   String vpath,
                   String path,
                   boolean isSource,
                   boolean prependFullName,
                   Context context)
            throws 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.

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 Details

getBeginString

public static String getBeginString(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.

getEditString

public String getEditString(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.

getEndString

public static String getEndString(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.

getSymbols

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

getVPath

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

hasSymbol

public boolean hasSymbol(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.

hasUnusedSymbolEdits

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

outputSymbolEdits

public void outputSymbolEdits(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.

outputUnusedSymbolEdits

public void outputUnusedSymbolEdits(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.

renameSymbol

public void renameSymbol(String oldName,
                         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.

setLineRedirector

public void setLineRedirector(LineRedirector lr)

setVPath

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

splice

public void splice(String symbol,
                   LanguageWriter writer,
                   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(String symbol,
                   LanguageWriter writer,
                   String alt_msg,
                   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(String symbol,
                   LanguageWriter writer,
                   String alt_msg,
                   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(String symbol,
                   LanguageWriter writer,
                   String alt_msg,
                   String[] comment_code,
                   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.