parserAttrGet
RETURNS CHARACTER (theHandle AS INTEGER, theKey AS CHARACTER)
Returns the string value of a node attribute.
Returns an empty string "" if the node does not have that attribute.
parserAttrGetI
RETURNS INTEGER (theHandle AS INTEGER, theKey AS INTEGER)
Returns the integer value of a node attribute.
Requires the integer representation of the attribute key.
Returns zero if the node does not have that attribute.
parserAttrSet
RETURNS LOGICAL (theHandle AS INTEGER, theKey AS INTEGER, theValue AS INTEGER)
Sets a node's attribute. You must use the integer values for the
attribute key and the attribute value.
Returns true on success.
parserAttrStringGet
RETURNS CHARACTER (theHandle AS INTEGER, theKey AS INTEGER)
Returns the string value of an integer-keyed node attribute.
Returns an empty string "" if the node does not have that attribute.
This function doesn't use the same internal table as the parserAttrGet
and parserAttrGetI functions, and there is no cross reference
between the two tables.
See also parserAttrStringSet.
parserAttrStringSet
RETURNS LOGICAL (theHandle AS INTEGER, theKey AS INTEGER, theValue AS CHARACTER)
Sets a string attribute on a node. The attribute key must be an integer
and the attribute value must be a string. Returns true on success.
This function doesn't use the same internal table as the parserAttrSet
function, and there is no cross reference between the two tables.
See also parserAttrStringGet.
parserConfigGet
RETURNS CHARACTER (theFlag AS CHARACTER)
Returns a configuration value.
If an invalid configuration flag parameter is used, then an
empty string "" is returned and a Proparse error condition is raised.
parserConfigSet
RETURNS LOGICAL (theFlag AS CHARACTER, theValue AS CHARACTER)
Sets a configuration value. Returns true on success.
parserCopyHandle
RETURNS LOGICAL (fromHandle AS INTEGER, toHandle AS INTEGER)
Copies a pointer to a node, the result being that toHandle
now points to the same node as fromHandle.
parserDictAdd
RETURNS LOGICAL (theText AS CHARACTER, theType AS CHARACTER)
Adds a user string literal to the user node types dictionary.
For example, parserDictAdd("define_const", "DEFINE")
would add "define_const" as a string literal to be treated the same
as "def" or "DEFINE".
The second parameter must be a valid Proparse node type.
Returns false on failure.
parserDictDelete
RETURNS LOGICAL (theText AS CHARACTER)
Removes a string literal from the user node types dictionary.
Returns true even if theText did not exist as an
entry in the user node types dictionary.
(Would only return false if there was a Proparse internal error.)
parserDiff
RETURNS CHARACTER (file1 AS CHARACTER, file2 AS CHARACTER)
Trivially finds differences between two files.
Returns an empty string "" if no differences were found.
See the source code in the "opencpp" directory.
Used by Joanju for testing the scanner.
parserErrorClear
RETURNS LOGICAL
Resets Proparse's error status to zero
and clears out the warning/error text.
parserErrorGetIsCurrent
RETURNS LOGICAL
Use this function to find out if the current error status is current.
If subsequent API function calls have been made since the call which raised
the error status, then this function returns FALSE.
parserErrorGetStatus
RETURNS INTEGER
Returns zero if there is no error or warning.
Returns -1 if there has been a warning.
Returns -2 if there has been an error.
If an API function call raises a warning or an error status,
that warning or error status remains in effect until
parserErrorClear is called.
parserErrorGetText
RETURNS CHARACTER
If there is an error condition in Proparse, then this returns the
error message. Returns an empty string "" if there is no current
error condition. Use this function to get the text of warnings as well as
errors. (i.e. Use this function whether the error status is -1 or -2.)
If an API function call raises a warning or an error status,
that warning or error message remains available until
parserErrorClear is called.
parserGetHandle
RETURNS INTEGER
Returns an integer reference to a pointer to a node.
To use node handles, define an INTEGER variable and use
parserGetHandle to set its value. That variable can now
be used in places where the parser's API requires a node handle.
If there is a free node pointer (one that has been released by
parserReleaseHandle), then the DLL will reuse it, rather than
create a new pointer.
parserGetIndexFilename
RETURNS CHARACTER (fileIndex AS INTEGER)
Get the file name for a given file index.
Not commonly used. Normally, you would want to just use getNodeFilename.
File name indexes, rather than the entire filename, are stored in the syntax
tree in Proparse. You can use this index number for efficient external
storage of the syntax tree.
Input the file index number, returns the file name.
Raises a warning condition if an invalid index was accessed.
Use the warning condition
parserErrorGetStatus
if iterating through index numbers to get all filenames.
Do not check for a blank filename return - there is no
guarantee that there will not be a blank entry in the filename list.
See also parserGetNodeFileIndex
and parserGetNodeFilename.
parserGetNodeColumn
RETURNS INTEGER (ofHandle AS INTEGER)
If the node represents an actual source code token, then this function
returns the column position within the source file where the token was found.
A tab character counts as a single column.
parserGetNodeFileIndex
RETURNS INTEGER (ofHandle AS INTEGER)
Get the file index for a given node.
File name indexes, rather than the entire filename, are stored in the syntax
tree in Proparse. You can use this index number for efficient external
storage of the syntax tree.
The file at index zero is always the compile unit.
The others are include files.
See also parserGetIndexFilename
and parserGetNodeFilename.
parserGetNodeFilename
RETURNS CHARACTER (ofHandle AS INTEGER)
If the node represents an actual source code token, then this function
returns the name of the source file where the token was found.
parserGetNodeLine
RETURNS INTEGER (ofHandle AS INTEGER)
If the node represents an actual source code token, then this function
returns the line number within the source file where the token was found.
parserGetNodeText
RETURNS CHARACTER (ofHandle AS INTEGER)
Returns the original source code for the given node's token.
For example, if the node type is "SUBSTRING", the original source
code that the node's token is related to may have been "substr".
parserGetNodeType
RETURNS CHARACTER (ofHandle AS INTEGER)
Returns the type of the given node's token.
For example, if the original source code token was "substr",
the node type is "SUBSTRING".
Note Regarding the Proparse Tree Specification
In Proparse's Tree Specification, you will see some token types that end
with "_KW". That suffix was added internally in Proparse
due to symbol name conflicts in some compilers.
However, to avoid breaking existing applications
like Prolint, that suffix is dropped when referring to token types via
Proparse's API.
For example, the tree parser uses DELETE_KW as the symbol for referring
to a DELETE node. However, parserGetNodeType() would return
"DELETE" rather than "DELETE_KW".
parserGetNodeTypeI
RETURNS INTEGER (ofHandle AS INTEGER)
Returns the integer type of the given node's token.
For example, if the original source code token was "substr", the node
type would be "SUBSTRING" and the integer node type might be 766.
See also parserSetNodeTypeI.
parserGetTokenTypeName
RETURNS CHARACTER (tokenTypeNumber AS INTEGER)
Returns the token type name of the given token type number.
Returns an empty string "" if the tokenTypeNumber is not valid.
For example, Proparse's internal representation of token type number 766
is the SUBSTRING token type.
See also parserGetTokenTypeNumber.
parserGetTokenTypeNumber
RETURNS INTEGER (tokenTypeName AS CHARACTER)
Returns the token type number of the given token type name. For example,
Proparse's internal representation of the SUBSTRING token type is 766.
Differs from the
parserGetNodeTypeI
function in that a specific node does not need to be supplied.
See also parserGetTokenTypeName.
parserGetVersion
RETURNS CHARACTER
Returns the version of proparse.dll.
parserHiddenAddToFront
RETURNS LOGICAL (theHandle AS INTEGER, newType AS CHARACTER, newText AS CHARACTER)
Creates a new hidden token with type newType and text newText,
and makes this token the first hidden token of theHandle.
It also becomes the current hidden token. Returns true on success.
See also Modifying Hidden Tokens.
parserHiddenDelete
RETURNS LOGICAL (theHandle AS INTEGER)
Deletes the current hidden token of theHandle.
If there is a "next" hidden token, it becomes the current hidden token.
Otherwise, if there is a "previous" hidden token,
it becomes the current hidden token.
If this was the last hidden token of theHandle,
there is no current hidden token. Returns true on success.
See also Modifying Hidden Tokens.
parserHiddenGetBefore
RETURNS LOGICAL (handle AS INTEGER)
Sets the current hidden token to be the hidden token that comes before
the node referred to by the input handle.
Returns false if no hidden token is found.
parserHiddenGetColumn
RETURNS INTEGER
This function returns the column position within the source file
where the current hidden token was found.
A tab character counts as a single column.
parserHiddenGetFilename
RETURNS CHARACTER
Returns the name of the source file where the current hidden token came from.
parserHiddenGetFirst
RETURNS LOGICAL (handle AS INTEGER)
Sets the current hidden token to be the first hidden token that comes before
the node referred to by the input handle.
Returns false if no hidden token is found.
See Hidden Tokens
in the User's Guide for a description of what "first hidden token" means.
parserHiddenGetLine
RETURNS INTEGER
Returns the line number within the source file
where the current hidden token came from.
parserHiddenGetNext
RETURNS LOGICAL
Finds the next hidden token after the current hidden token,
then sets the current hidden token to be that newly found one.
Returns false if no hidden token is found.
parserHiddenGetPrevious
RETURNS LOGICAL
Finds the hidden token previous to the current hidden token,
then sets the current hidden token to be that newly found one.
Returns false if no hidden token is found.
parserHiddenGetText
RETURNS CHARACTER
Returns the text of the current hidden token.
parserHiddenGetType
RETURNS CHARACTER
Returns the type of the current hidden token, for example
"WS" for whitespace, or "COMMENT".
parserHiddenInsertAfter
RETURNS LOGICAL (newType AS CHARACTER, newText AS CHARACTER)
Creates a new hidden token of the given type and text and inserts it after the
current hidden token.
The new token then becomes the current hidden token.
Returns true on success.
See also Modifying Hidden Tokens.
parserHiddenSetText
RETURNS LOGICAL (newText AS CHARACTER)
Sets the text of the current hidden token to newText.
Returns true on success.
See also Modifying Hidden Tokens.
parserHiddenSetType
RETURNS LOGICAL (newType AS CHARACTER)
Sets the type of the current hidden token to newType.
Valid values are "WS" for whitespace, or "COMMENT". Returns true on success.
See also parserHiddenGetType
and Modifying Hidden Tokens.
parserInit
RETURNS LOGICAL
Not currently used. Always returns TRUE.
parserIsSameNode
RETURNS LOGICAL (handle1 AS INTEGER, handle2 AS INTEGER)
Compares the node for handle1 with the node for handle2,
and returns true if the handles refer to the same node or returns false if they don't.
parserIsValidNode
RETURNS LOGICAL (theHandle AS INTEGER)
Checks the node for theHandle, and returns true if the handle refers
to a valid node or returns false if the node isn't valid.
parserIwdiff
RETURNS CHARACTER (file1 AS CHARACTER, file2 AS CHARACTER)
The source for this function is in
opencpp/iwdiff.cpp.
Used by testrun2.p to check that the output from compile with
preprocess is the same as the output from the parser.
Originally named as "Ignore Whitespace diff",
it does less ignoring whitespace now,
and does much more to compensate for the way that Progress's preprocessor
writes out preprocessed code.
file1 must be the COMPILE..PREPROCESS output,
file2 must be the output from Proparse (usually just from
the writenode function).
parserNodeCreate
RETURNS LOGICAL (intoHandle AS INTEGER, newType AS CHARACTER, newText AS CHARACTER)
Creates a new node of type newType, with text newText,
and places the handle of this new node into the intoHandle.
Returns true on success.
See also Tree Manipulation and Code Refactoring
and its subsection
Creating Nodes
for further information, including how to find valid node types for this function.
parserNodeCreateI
RETURNS LOGICAL (intoHandle AS INTEGER, newType AS INTEGER, newText AS CHARACTER)
Creates a new node of integer type newType (which does not have to
be a valid node type), with text newText, and places the handle
of this new node into the intoHandle. Returns true on success.
See also Tree Manipulation and Code Refactoring
and its subsection
Creating Nodes
for further information, including how to find valid node types for this function.
parserNodeFirstChild
RETURNS CHARACTER (ofHandle AS INTEGER, intoHandle AS INTEGER)
A handle to the first child of ofHandle is stored in
intoHandle. Returns "" if ofHandle
has no first child, otherwise, the found node's type is returned.
If there is no first child, intoHandle is not changed.
The same handle may be used for
both ofHandle and intoHandle, with the effect
of moving the handle from one node to the next.
parserNodeFirstChildI
RETURNS INTEGER (ofHandle AS INTEGER, intoHandle AS INTEGER)
A handle to the first child of ofHandle is stored in
intoHandle. Returns 0 if ofHandle
has no first child, otherwise, the found node's integer node type is returned.
If there is no first child, intoHandle is not changed.
The same handle may be used for both ofHandle and
intoHandle, with the effect of moving the handle from one node to the next.
parserNodeNextSibling
RETURNS CHARACTER (ofHandle AS INTEGER, intoHandle AS INTEGER)
A handle to the next sibling of ofHandle is stored in
intoHandle. Returns "" if ofHandle
has no next sibling, otherwise, the found node's type is returned.
If there is no next sibling, intoHandle is not changed.
The same handle may be used for
both ofHandle and intoHandle, with the effect
of moving the handle from one node to the next.
parserNodeNextSiblingI
RETURNS INTEGER (ofHandle AS INTEGER, intoHandle AS INTEGER)
A handle to the next sibling of ofHandle is stored in
intoHandle. Returns 0 if ofHandle
has no next sibling, otherwise, the found node's integer node type is returned.
If there is no next sibling, intoHandle is not changed.
The same handle may be used for both ofHandle and
intoHandle, with the effect of moving the handle from one node to the next.
parserNodeParent
RETURNS CHARACTER (ofHandle AS INTEGER, intoHandle AS INTEGER)
A handle to the parent of ofHandle is stored in
intoHandle. Returns "" if ofHandle
has no parent, otherwise, the found node's type is returned.
If there is no parent, intoHandle is not changed.
The same handle may be used for
both ofHandle and intoHandle, with the effect
of moving the handle from one node to the next.
parserNodePrevSibling
RETURNS CHARACTER (ofHandle AS INTEGER, intoHandle AS INTEGER)
A handle to the previous sibling of ofHandle is stored in
intoHandle. Returns "" if ofHandle
has no previous sibling, otherwise, the found node's type is returned.
If there is no previous sibling, intoHandle is not changed.
The same handle may be used for
both ofHandle and intoHandle, with the effect
of moving the handle from one node to the next.
parserNodeStateHead
RETURNS CHARACTER (ofHandle AS INTEGER, intoHandle AS INTEGER)
A handle to the statement head node of ofHandle is stored in
intoHandle. Returns "" if ofHandle
has no statement head node, otherwise, the found node's type is returned.
If there is no statement head node, intoHandle is not changed.
The same handle may be used for
both ofHandle and intoHandle, with the effect
of moving the handle from one node to the next.
A "statement head node" is a node with the attribute "statehead".
See statehead.
parserNodeStateHead may be used iteratively to move up/out through
nested blocks, all the way up to the outermost block.
For example, given the program
DO: DISPLAY "Hi!". END. and starting at the QSTRING "Hi!" node,
the first call to parserNodeStateHead would find the DISPLAY node.
The second call would find the DO node. A third call would not find another
statement head - blank would be returned, and intoHandle would
not be changed.
parserNodeTop
RETURNS CHARACTER (intoHandle AS INTEGER)
Stores a reference to the topmost node in the node handle
intoHandle. Returns "Program_root" on success, or
"" on failure (i.e. if there is no syntax tree).
The topmost node is always a special node of type Program_root.
Unlike most nodes, the Program_root node does not represent any
actual token from your program's source code.
parserParse
RETURNS LOGICAL (filename AS CHARACTER)
Parses the program file specified by filename.
The return value is FALSE if the parse failed.
If the parse failed, there will not be any syntax tree available to work with.
Your application is responsible for getting and dealing with the text of the
error message.
parserParseCreate
RETURNS INTEGER (parseType AS CHARACTER, filename AS CHARACTER)
The only valid value for parseType is "scan"".
Causes Proparse to scan filename and create a scanner result set.
Returns an integer "parse number", which is used as a handle to other
functions like parserParseGetTop and parserParseDelete.
parserParseDelete
RETURNS LOGICAL (parseNum AS INTEGER)
Deletes the parse number parseNum created by
parserParseCreate.
Returns FALSE only if there was an error.
Also deletes all queries related to that scan result,
as well as all handles to nodes in that scan result.
parserParseGetTop
RETURNS LOGICAL (parseNum AS INTEGER, intoHandle AS INTEGER)
Finds the top (first) node from parse (or scan) result parseNum
and causes handle intoHandle to refer to that node.
Returns FALSE only if there was an error.
parserQueryClear
RETURNS LOGICAL (queryName AS CHARACTER)
Clears the named query. Pass an empty string "" to clear all queries.
parserQueryCreate
RETURNS INTEGER (fromNode AS INTEGER, queryName AS CHARACTER, nodeType AS CHARACTER)
Creates a named query. Any number of queries can be created, and referred to
by name. The query starts at the fromNode node handle, evaluating
that node and all of its child nodes. A list of node references is created within
Proparse, one node reference for each node that is of the input
nodeType. This function returns the number of results (the number
of node references that were added to the list). You reference this result
list with the function parserQueryGetResult.
If a previous query of the same name exists, it is cleared out first.
You can pass an empty string "" as the node type to build an "unfiltered
query". All nodes are added to the result set. This has the effect of
flattening the tree down into a one dimensional vector of nodes. Operator
nodes are placed in between their operands, so that this feature is especially
useful for printing out code.
In order to make it possible to quickly find the first node of a given
line number in a scan result, a built-in function was added,
and it is accessed via the existing queries API. For example:
parserQueryCreate(topNode, "myQuery", "first_where_line=" + STRING(myLine)).
...where topNode is the first node in a scan result,
and myLine is an integer line number.
Queries with option first_where_line= are only sensible and only
supported for scanner results.
parserQueryGetResult
RETURNS LOGICAL (queryName AS CHARACTER, resultNum AS INTEGER, intoHandle AS INTEGER)
intoHandle must be a valid node handle, created with the function
parserGetHandle. queryName must be the name of a
query created with the function parserQueryCreate.
resultNum must be an integer between one and the number of results.
Sets the handle intoHandle to point to the node referred to
by result number resultNum in the query queryName.
Example: see examples/query_length.p.
Returns FALSE if the function failed.
parserReleaseHandle
RETURNS LOGICAL (theHandle AS INTEGER)
Releases a node handle for re-use.
See Releasing Node Handles.
Returns FALSE if the function failed.
parserSchemaAddDb
RETURNS LOGICAL (name AS CHARACTER)
Used by
proparse/api/proparse.p
to add to Proparse's list of database
names.
Returns FALSE if the function failed.
parserSchemaAddTable
RETURNS LOGICAL (name AS CHARACTER)
Used by
proparse/api/proparse.p
to add to Proparse's list of table names.
Returns FALSE if the function failed.
parserSchemaAliasCreate
RETURNS LOGICAL (aliasname AS CHARACTER, dbasename AS CHARACTER)
If your program requires a database alias to exist before it will compile,
then you must use this function to tell Proparse about your database
alias before that program can be parsed. If the alias already exists, then
it is replaced with the new value.
parserSchemaAliasDelete
RETURNS LOGICAL (aliasname AS CHARACTER)
Use this function to delete an alias that you created with
parserSchemaAliasCreate.
To delete all aliases, use an empty string as this function's argument (i.e.
parserSchemaAliasDelete("") ).
parserSchemaClear
RETURNS LOGICAL
Use this function if you want to clear the old schema names out of Proparse
and load a new list of schema names into Proparse. For example, you might
use this after making schema changes or after changing from one working
environment to another.
Returns FALSE if the function failed.
parserSetNodeFirstChild
RETURNS LOGICAL (parentHandle AS INTEGER, childHandle AS INTEGER)
Sets the childHandle node to be the first child node
of the parentHandle, displacing the former
first child node. Returns true on success.
Use 0 for childHandle to indicate that there are no children.
This function doesn't change the relationships between the child
node and its own children, its siblings, or its
hidden nodes.
See also Tree Manipulation and Code Refactoring
subsection Moving Nodes.
parserSetNodeNextSibling
RETURNS LOGICAL (ofHandle AS INTEGER, sibHandle AS INTEGER)
Sets the sibHandle node to be the next sibling node
of the ofHandle, displacing the former next sibling node.
Returns true on success.
Use 0 for sibHandle to indicate that there is no next sibling.
This function doesn't change the relationships between the sibling
node and its own children, its own siblings, or its
hidden nodes.
See also Tree Manipulation and Code Refactoring
subsection Moving Nodes.
parserSetNodeText
RETURNS LOGICAL (ofHandle AS INTEGER, newText AS CHARACTER)
Sets the ofHandle node's text in the tree to the newText.
Returns true on success. For example, if the node type is "SUBSTRING", the
original source code that the node is related to may have been "substr".
Use of this function allows the value in the original source code
to be modified (when Proparse's tree is written out), for example to "SUBSTR".
See also parserGetNodeText.
parserSetNodeType
RETURNS LOGICAL (ofHandle AS INTEGER, newType AS CHARACTER)
Sets the ofHandle node's type in the tree to the newType.
Returns true on success. For example, if the node type is "FIRST",
the node type may be changed to "LAST".
See also parserGetNodeType,
and Tree Manipulation and Code Refactoring
subsection Modifying Nodes
for further information, including how to find valid node types for this function.
parserSetNodeTypeI
RETURNS LOGICAL (ofHandle AS INTEGER, newType AS INTEGER)
Sets the ofHandle node's integer type in the tree to the newType.
Returns true on success. For example, if the node type for a user-defined node is 10201,
this node type may be changed to 10203, even though these are not valid node types.
See also parserGetNodeTypeI
and Tree Manipulation and Code Refactoring
subsection Modifying Nodes
for further information, including how to find valid node types for this function.
parserWriteNode
RETURNS LOGICAL (theHandle AS INTEGER, filename AS CHARACTER)
Given an input node handle, parserWriteNode
writes the text from that node and all of its
child nodes, out to the text file filename.
parserWriteNode takes care of ensuring that operators
are written out with infix notation
rather than the operator prefix notation that you would normally see when
walking a tree. (i.e.: displays: 1 + 2 instead of: + 1 2).
See Syntax Trees for more
information about operator prefix notation from syntax trees.
Also, parserWriteNode writes code that looks similar to the
original source code by displaying the whitespace (hidden token) prior to
each node. See
Hidden Tokens.
This function is mostly used by Joanju as a very fast function
to write out the results of
a parse to a text file, which can then be compared to the output of
a COMPILE...PREPROCESS. This allows us to test that programs are parsing
correctly.
Additionally, parserWriteNode is a handy way to write out
nodes found in ad hoc queries.
For example, see
examples/query_length.p.