org.prorefactor.refactor
Class Refactor

java.lang.Object
  org.prorefactor.refactor.Refactor

public class Refactor
extends java.lang.Object

A collection of functions to help with refactoring. Mostly these are for working together with both an AST as well as a scanner's token list. See also ScanLib for functions that operate only on scanner token lists.

Integer return values

Integer return values are not like traditional C return values where 0 is success and any other number is an error number. Instead, these are consistent with Proparse's return values: For many of these functions, where the return value is an int, if the integer return value does not already have another meaning, the function could be viewed as a logical "YES we got it / NO it doesn't exist"
1 "success"
0 "failure"
-1 "warning"
-2 "error"

Method Summary

int	consecComments() Test if we have consecutive comments.
void	cutToChain(int node, int scanNum, LooseChain theChain) Uses getSectionWithComments to find a token list segment from an AST node, copyAndMark the segment so it can be removed later with sweep(), put the copy of the segment onto a LooseChain.
boolean	findLeadingWhitespace(int astHandle, int tokenHandle) Find comments before the node which are not separated from the node by any blank lines.
boolean	findTrailingWhitespace(int astHandle, int tokenHandle) Find comments on the same line as the end of the AST branch, as well as one newline.
boolean	getInsertPointInFile(int astHandle, java.lang.String filename, int scanNum, int tokenHandle, ListingParser listingParser) Find an "insert point" in a specific source file, to come in front of a given AST node.
static Refactor	getInstance() This class implements the "Singleton" design pattern.
int	getSectionWithComments(int ast, int begin, int end) Get a scanner section, based on an AST node/branch, with leading comments and whitespace, and any trailing comments before the line break.
int	hiddenBeforeSync(int h1, int h2) Attempt to change scan nodes so they match AST hidden tokens.
void	markToBeCut(int node, int scanNum) Uses getSectionWithComments to find a token list segment from an AST node, markToBeCut the segment so it can be removed later with sweep().
int	msyncBranch(int inParseHandle, int inScanHandle1, int inScanHandle2) Multinode Sync (Branch) - synchronize an entire AST branch with a scanner list.
int	nsync(int h1, int h2) Node Sync - Synchronize a scanner node to a parser node.
void	replaceScannerSection(int scanHandle1, int scanHandle2, int parseHandle) Replace Scanner Section Input scan number, scanner start handle, scanner end handle, and a handle to an AST branch to replace it with.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static Refactor getInstance()

This class implements the "Singleton" design pattern.

consecComments

public int consecComments()

Test if we have consecutive comments. We don't want to split two comments if they are one line after the other, because it is common for Progress programmers to slash-star and star-slash every line of a multi-line comment. When called, the current hidden token should be the first of the two being checked.

Returns:

0 if not consec, 1 if two comments in a row, 2 if two comments seperated by whitespace with <2 '\n' characters.

cutToChain

public void cutToChain(int node,
                       int scanNum,
                       LooseChain theChain)
                throws RefactorException

Uses getSectionWithComments to find a token list segment from an AST node, copyAndMark the segment so it can be removed later with sweep(), put the copy of the segment onto a LooseChain.

Parameters:

node - The AST node.

scanNum - The scanner reference number.

theChain - The chain that we append the copied segment onto the end of.

Throws:

RefactorException

findLeadingWhitespace

public boolean findLeadingWhitespace(int astHandle,
                                     int tokenHandle)

Find comments before the node which are not separated from the node by any blank lines. We also carry leading blank lines.

Parameters:

astHandle - Must be a handle to a natural node.

tokenHandle - Must be a valid handle to an early token in the scanner. On success, this handle is repositioned to the desired token. On fail, there is no guarantee as to where the handle points.

Returns:

True on success.

findTrailingWhitespace

public boolean findTrailingWhitespace(int astHandle,
                                      int tokenHandle)

Find comments on the same line as the end of the AST branch, as well as one newline.

Parameters:

astHandle - A handle to the top of the AST branch. This function deals with finding the end of the branch.

tokenHandle - Must be a valid handle to an early token in the scan list. On success, this handle is repositioned to the desired token. On fail, there is no guarantee as to where the handle points.

Returns:

True on success.

getInsertPointInFile

public boolean getInsertPointInFile(int astHandle,
                                    java.lang.String filename,
                                    int scanNum,
                                    int tokenHandle,
                                    ListingParser listingParser)

Find an "insert point" in a specific source file, to come in front of a given AST node. (Node does not have to be natural.) Assumes we want a newline (i.e. Use for inserting between statements/blocks.) Makes assumptions about include files, only safe for DEFINE STATEMENTS, see TODO in source comments.

Parameters:

astHandle - The handle to find the insert point in front of.

filename - The file name that we want an insertion point for. (Currently no support for file index numbers with hidden tokens)

scanNum - A number for an existing scan for the file we want.

tokenHandle - The token handle to be repositioned. Does not have to be pre-positioned.

Returns:

True on success. It's very possible for this to fail to find an insert point - the client should be prepared for a return value of false.

getSectionWithComments

public int getSectionWithComments(int ast,
                                  int begin,
                                  int end)

Get a scanner section, based on an AST node/branch, with leading comments and whitespace, and any trailing comments before the line break. This does not attempt to do scanner/AST synchronization. All you get is a segment of text. This finds the first natural node for the starting point, but it does not (currently) try to find the last natural node. If the last node is not natural, it fails. Returns -1 if the AST branch begins and ends in different files, etc.

Parameters:

ast - The node handle from the syntax tree

begin - A scanner handle, on success will point at beginning of section

end - A scanner handle, on success will point at end of section

Returns:

Positive int on success

hiddenBeforeSync

public int hiddenBeforeSync(int h1,
                            int h2)

Attempt to change scan nodes so they match AST hidden tokens. Synchronize the hidden tokens in front of h1 with a scanner node h2 This cannot (and should not) be used as a test to see if there are hidden tokens. Requires that h2 is a handle in a scan of h1's file, and h2 must be positioned at or before a node in the scan with same line/column as h1. If no hidden tokens: returns 1, h2 is unchanged. If there are hidden tokens: - Returns 1 on success: h2 is set to match hiddenGetFirst(h1). - Returns 0 on fail, and h2 is unchanged.

markToBeCut

public void markToBeCut(int node,
                        int scanNum)
                 throws RefactorException

Uses getSectionWithComments to find a token list segment from an AST node, markToBeCut the segment so it can be removed later with sweep().

Parameters:

node - The AST node

scanNum - The scanner for the branch's code.

Throws:

RefactorException

msyncBranch

public int msyncBranch(int inParseHandle,
                       int inScanHandle1,
                       int inScanHandle2)

Multinode Sync (Branch) - synchronize an entire AST branch with a scanner list.

Parameters:

inParseHandle - is positioned at the first node we want in the parse tree

inScanHandle1 - is positioned in the scanner list *before* the expected node, probably just at the head of the scanner list.

inScanHandle2 - is positioned anywhere.

Returns:

1 if the sync was successful, otherwise returns zero.

On success, inScanHandle1 is sync'd with the first natural node, and inScanHandle2 is at the end of the section of synchronized scan nodes. Does NOT attempt to synchronize whitespace until after the first natural node, because those may have nothing to do with this branch. Note that this will synchronize as far as it can before failing - so it may actually get some, but not all, of the relevent scan nodes changed so that they directly reflect the parse nodes. The two input scanHandles DO get moved around - don't count on their position for anything if the synchronization failed.

See Also:

nsync(int, int)

nsync

public int nsync(int h1,
                 int h2)

Node Sync - Synchronize a scanner node to a parser node.

Parameters:

int - h1 handle positioned at the node in the parse tree which we are interested in.

int - h2 handle positioned in the scanner list, somewhere *before* the expected node.

Returns:

1 if h2 was successfully repositioned to a matching node, otherwise, returns 0, and leaves h2 unchanged.

Causes one or more tokens in the scanner list to be changed in order for them to be synchronised with a token in the AST.

replaceScannerSection

public void replaceScannerSection(int scanHandle1,
                                  int scanHandle2,
                                  int parseHandle)

Replace Scanner Section Input scan number, scanner start handle, scanner end handle, and a handle to an AST branch to replace it with. Copies the nodes from the AST branch. Copying starts at the first node (not at the hidden tokens in front of the first node).