public class PreprocessorHints extends java.lang.Object implements HintsTags
Once constructed, the hints file has been loaded into memory and the
contents are available via simple 'getter' method calls such as
getArguments(boolean)
. This class hides the storage mechanism and the
file format from the callers. It also handles any conversion from the
string oriented XML format to the proper data type of the value in
question. Generally, if the hints file doesn't exist or if the value
being queried doesn't exist in that hints file, the result from a
lookup will be null
.
The following is the structure of the XML file:
Modifier and Type | Field and Description |
---|---|
private static java.lang.String |
HINTS_SUFFIX
The standard suffix appended to a source code filename to create a
unique filename for storing hints.
|
private HintsTreeNode |
hintsRoot
The hints tree built from the XML file
|
private java.lang.String |
source
Normalized source filename
|
ATTR_TAG_ARG_NAME, ATTR_TAG_ARG_POS, ATTR_TAG_ARG_USED, ATTR_TAG_ARG_VAL, ATTR_TAG_END_COL, ATTR_TAG_END_LINE, ATTR_TAG_FILE, ATTR_TAG_REF_COL, ATTR_TAG_REF_LINE, ATTR_TAG_REF_NAME, ATTR_TAG_REF_TYPE, ATTR_TAG_REF_VAL, ATTR_TAG_START_COL, ATTR_TAG_START_LINE, ATTR_TAG_SYM_NAME, ATTR_TAG_SYM_TYPE, ATTR_TAG_SYM_VAL, ELEM_TAG_ARG, ELEM_TAG_INCL, ELEM_TAG_REF, ELEM_TAG_ROOT, ELEM_TAG_SUBROOT, ELEM_TAG_SYM
Constructor and Description |
---|
PreprocessorHints(java.lang.String sourceName)
Constructs an instance, loads the associated hints file if it exists
and parses the contents.
|
Modifier and Type | Method and Description |
---|---|
private ArgumentHint |
createArgument(org.w3c.dom.Element elem)
Creates an
ArgumentHint instance from the information
in the passed DOM node. |
private HintsTreeNode |
createHintsNode(IncludeHint top,
org.w3c.dom.Element elem)
Creates a hints tree node from the information in the passed DOM node.
|
private HintsTreeNode |
createInclude(org.w3c.dom.Element elem)
Creates an
ArgumentHint instance from the information
in the passed DOM node and then creates a HintsTreeNode from it. |
private ReferenceHint |
createReference(org.w3c.dom.Element elem)
Creates a
ReferenceHint instance from the information
in the passed DOM node. |
private SymbolHint |
createSymbol(org.w3c.dom.Element elem)
Creates a
SymbolHint instance from the information in the passed DOM node. |
void |
dumpHintsTree()
Dumps the tree.
|
java.util.List |
getAllIncludes()
Returns the array of names of all included files.
|
java.util.List |
getArguments(boolean deep)
Gets the array of argument hints for the top level file.
|
int |
getMaxIncludeDepth()
Returns the maximum nesting level of includes for this instance.
|
int |
getNumAllIncludes()
Returns the total number of included files.
|
int |
getNumRefArgument(boolean deep)
Gets the number of references to arguments in this file.
|
int |
getNumRefBuiltin(boolean deep)
Gets the number of references to builtin variables in this file.
|
int |
getNumReferenced(java.lang.String var,
boolean deep)
Gets the number of references to the specified variable in
this file.
|
int |
getNumRefGlobal(boolean deep)
Gets the number of references to global variables in this file.
|
private int |
getNumRefs(java.lang.String type,
boolean deep)
Gets the number of references to the specified type variables in this
file.
|
int |
getNumRefScoped(boolean deep)
Gets the number of references to scoped variables in this file.
|
int |
getNumRefUndefined(boolean deep)
Gets the number of references to undefined variables in this file.
|
int |
getNumUniqueIncludes()
Returns the number of unique include files.
|
private HintsTreeNode |
getPathFor(HintsTreeNode node,
int line,
int column)
Locates all include files where specific line and column of the output
came from.
|
java.util.List |
getReferences(boolean deep)
Gets the array of reference hints for the top level file.
|
HintsTreeNode |
getRoot()
Get the root of this preprocessor hints tree.
|
java.lang.String |
getSource()
Get the
source filename. |
java.lang.String |
getSourceFor(int line,
int column)
Locates the include file where specific line and column of the output
came from.
|
java.util.List |
getSourcesFor(int line,
int column)
Locates all include files where specific line and column of the output
came from.
|
java.lang.String |
getSymbolValue(java.lang.String name)
Get the symbol value at the root level.
|
java.util.Set |
getUniqueIncludes()
Returns the array of names of unique include files.
|
boolean |
isIncluded(int line,
int column)
Checks whether the specified location in the file was included from
an include file or not.
|
boolean |
isIncluded(java.lang.String filename)
Checks whether the specified file was included or not.
|
boolean |
isReferenced(java.lang.String var,
boolean deep)
Checks whether the specified variable was referenced or not in
this file.
|
boolean |
isUnused(boolean deep)
Checks whether there are unused arguments to this file.
|
boolean |
isUnused(int posArgNum,
boolean deep)
Checks whether the specified positional argument is used or not in
this file.
|
boolean |
isUnused(java.lang.String namedArg,
boolean deep)
Checks whether the specified named argument is used or not in
this file.
|
private void |
loadHints(java.io.File hintsFile)
Load preprocessor hints from an XML document associated with the
specified filename.
|
static void |
main(java.lang.String[] cargs)
Command line driver used for testing.
|
private static final java.lang.String HINTS_SUFFIX
private java.lang.String source
private HintsTreeNode hintsRoot
public PreprocessorHints(java.lang.String sourceName) throws PreprocessorException
sourceName
- The Progress 4GL source program's filename with which this
hints file is associated.PreprocessorException
- An unknown or unexpected failure.public java.lang.String getSource()
source
filename.public HintsTreeNode getRoot()
public void dumpHintsTree()
public java.lang.String getSymbolValue(java.lang.String name)
name
- The symbol name.public java.util.List getArguments(boolean deep)
deep
- tells to get only this node's hints (false
) or
everythingpublic java.util.List getReferences(boolean deep)
deep
- tells to get only this node's hints (false
) or
everythingpublic java.lang.String getSourceFor(int line, int column)
line
- line of the output file under considerationcolumn
- column of the output file under consideration. line and column
together refer to the position in the output file that is under
considerationpublic java.util.List getSourcesFor(int line, int column)
line
- line of the output file under considerationcolumn
- column of the output file under consideration. line and column
together refer to the position in the output file that is under
considerationpublic int getNumAllIncludes()
public int getNumUniqueIncludes()
public java.util.List getAllIncludes()
public java.util.Set getUniqueIncludes()
public int getMaxIncludeDepth()
public boolean isIncluded(java.lang.String filename) throws ConfigurationException, java.io.IOException
filename
- include file to check for inclusion fromtrue
if the file was included.ConfigurationException
java.io.IOException
public boolean isIncluded(int line, int column)
line
- line number within the source filecolumn
- column number within the source file; line and column specify
the location within the file to check for inclusiontrue
if the location was included.public boolean isUnused(boolean deep)
deep
- tells to look only at this node's hints (false
) or
everythingtrue
if there are unused arguments.public boolean isUnused(int posArgNum, boolean deep)
posArgNum
- positional argument to testdeep
- tells to look only at this node's hints (false
) or
everythingtrue
if the specified argument was not used.public boolean isUnused(java.lang.String namedArg, boolean deep)
namedArg
- named argument to test; case does not matterdeep
- tells to look only at this node's hints (false
) or
everythingtrue
if the specified argument was not used.public boolean isReferenced(java.lang.String var, boolean deep)
var
- variable to test; case does not matterdeep
- tells to look only at this node's hints (false
) or
everythingtrue
if the specified variable was referenced.public int getNumReferenced(java.lang.String var, boolean deep)
var
- variable to test; case does not matterdeep
- tells to look only at this node's hints (false
) or
everythingpublic int getNumRefGlobal(boolean deep)
deep
- tells to look only at this node's hints (false
) or
everythingpublic int getNumRefScoped(boolean deep)
deep
- tells to look only at this node's hints (false
) or
everythingpublic int getNumRefBuiltin(boolean deep)
deep
- tells to look only at this node's hints (false
) or
everythingpublic int getNumRefArgument(boolean deep)
deep
- tells to look only at this node's hints (false
) or
everythingpublic int getNumRefUndefined(boolean deep)
deep
- tells to look only at this node's hints (false
) or
everythingprivate void loadHints(java.io.File hintsFile) throws PreprocessorException
hintsFile
- The hints file to read.PreprocessorException
- An unknown or unexpected failure.private HintsTreeNode createHintsNode(IncludeHint top, org.w3c.dom.Element elem) throws PreprocessorException
top
- the top level include hint for the subtree being createdelem
- the DOM element to analyzeHintsTreeNode
representing the specified DOM nodePreprocessorException
- when the original XML document contains invalid nodesprivate ReferenceHint createReference(org.w3c.dom.Element elem) throws PreprocessorException
ReferenceHint
instance from the information
in the passed DOM node.elem
- the DOM element to analyzeReferenceHint
representing the specified DOM nodePreprocessorException
- when the original XML document contains invalid nodesprivate SymbolHint createSymbol(org.w3c.dom.Element elem) throws PreprocessorException
SymbolHint
instance from the information in the passed DOM node.elem
- the DOM element to analyzeSymbolHint
representing the specified DOM nodePreprocessorException
- when the original XML document contains invalid nodesprivate ArgumentHint createArgument(org.w3c.dom.Element elem) throws PreprocessorException
ArgumentHint
instance from the information
in the passed DOM node.elem
- the DOM element to analyzeArgumentHint
representing the specified DOM nodePreprocessorException
- when the original XML document contains invalid nodesprivate HintsTreeNode createInclude(org.w3c.dom.Element elem) throws PreprocessorException
ArgumentHint
instance from the information
in the passed DOM node and then creates a HintsTreeNode from it.elem
- the DOM element to analyzeHintsTreeNode
representing the specified DOM nodePreprocessorException
- when the original XML document contains invalid nodesprivate HintsTreeNode getPathFor(HintsTreeNode node, int line, int column)
node
- starting node for this searchline
- line of the output file under considerationcolumn
- column of the output file under consideration. line and column
together refer to the position in the output file that is under
considerationprivate int getNumRefs(java.lang.String type, boolean deep)
type
- type of reference to checkdeep
- tells to look only at this node's hints (false
) or
everythingpublic static void main(java.lang.String[] cargs) throws ConfigurationException, java.io.IOException
cargs
- command line parameters.
Only one parameter is used and it is the base filename.ConfigurationException
java.io.IOException