com.tplan.robot.scripting.interpret

Interface EditorFriendlyInterpret

public interface EditorFriendlyInterpret

Interface declaring auxiliary methods that a test script interpret may implement to support advanced editor functions such as context menus, break points etc.

T-Plan Robot Enterprise, (C) 2009-2022 T-Plan Limited. All rights reserved.

Field Summary

Fields

Modifier and Type	Field and Description
static String	LINE_ACTION_FLAG Name of an optional flag identifying whether an action returned by the getPopUpMenuActions(java.awt.Point, int) method is specific for the specified offset (flag=true) or whether it is a global action applying to the whole script (flag=false; default).

Method Summary

Modifier and Type	Method and Description
boolean	areNestedInterpretsSupported() Declare whether the interpret supports nested interprets (code of a different type embedded into the interpret's native code, such as for example Java code block).
boolean	canCollapseCode() Find out whether the interpret is capable of identifying of areas which may be collapsed (hidden) in order to make a custom or simpler script code view.
boolean	canInsertCommandTo(int offset) Find out if it is legal to insert a command or a method call to the given offset.
boolean	canReport() Indicate if the interpret is capable of producing a report.
boolean	canSetBreakPoint(int offset) Define if a break point can be set on the given element (line of code).
CharSequence	create(int offset, String command, LinkedHashMap<String,Object> parameters) Create a new method or a command call using the specified parameter map and return it.
int	createNewScript(PreferenceContainer preferences) Create a new script instance based on the specified preferences.
String	createVariableCall(String variableName, Class returnType) Create a piece of code that returns value of the specified variable.
LinkedHashMap<String,int[]>	getCollapsibleAreas() Get coordinates of the collapsible areas.
CommandHandler	getCommandHandlerForElement(int offset, LinkedHashMap<String,Object> parameters) Get the command handler associated with the code contained in the particular document element.
String[]	getHelpKeyForOffset(int offset) Return a help key for the specified offset.
TestScriptInterpret	getInterpret() Get the interpret.
int	getLastCodeLineOffset() Get offset (document position) of the last script code line.
Configurable	getNewScriptPreferences(PreferenceContainer preferences) Get the specification of preferences applicable to a new script.Interprets which do not populate a new test script with a configurable template may simply return null.
CharSequence	getOutputPath(int offset, boolean reportDefaultPathAsNull, boolean resolveVariables) Get the output (report) path valid for the code at the given offset.The method is supposed to return the file path (as String) or the expression the path is set to (as a StringBuilder or StringBuffer).
List<Action>	getPopUpMenuActions(Point p, int offset) Get the list of interpret specific actions for the given point and offset.
LinkedHashMap<String,Object>	getReport(int offset) Get report properties (parameters) from the report producing command at the specified offset.
CharSequence	getTemplatePath(int offset, boolean reportDefaultPathAsNull, boolean resolveVariables) Get the template path valid for the code at the given offset.The method is supposed to return the file path (as String) or the expression the path is set to (as a StringBuilder or StringBuffer).
Map<File,List<ScriptReferenceLocation>>	getUsedImages() Get the list of images used by the script for image comparison.
Map<String,Object>	getUsedVariables(int offset) Get the map of variables existing at the given script position.
int[]	isBlockStartOrEnd(int offset) Find out if the argument offset is near to the block start or end, typically close to the opening or closing curly brace ('{' or '}'), and get the start/end coordinates.
boolean	isCodeInsertionSupported() Test if the interpret is capable of generating the script code.
boolean	isComment(int offset) Define whether the specified offset in the code is inside a comment or not.
boolean	isGradualCommandBuildingSupported() This method defines whether the interpret allows gradual building of a command in the test script editor.
int	modifyOrInsert(int offset, boolean replace, String command, LinkedHashMap<String,Object> parameters, int[] outCoords) Create a new method or a command call using the specified parameter map and insert it to the specified offset (position).If the offset corresponds to an already existing call of the same command, handle the insertion as replacement.
void	refreshStyle() Refresh document styles.
int	replace(int offset, int length, String command, LinkedHashMap<String,Object> parameters, int[] outCoords) Replace the text at the specified coordinates with a new method or a command call created from the specified command name and parameter map.
int	setOutputPath(CharSequence path, int offset) Update the script output path at the selected offset of the editor.
int	setReport(int offset, LinkedHashMap<String,Object> parameters) Create or update the report producing command at the specified offset.
int	setTemplatePath(CharSequence path, int offset) Update the template path at the selected offset of the editor.
void	toggleComment(int offset, boolean commentOut) Comment out or uncomment the command at the specified index.

Field Detail

LINE_ACTION_FLAG

static final String LINE_ACTION_FLAG

Name of an optional flag identifying whether an action returned by the getPopUpMenuActions(java.awt.Point, int) method is specific for the specified offset (flag=true) or whether it is a global action applying to the whole script (flag=false; default). This makes the calling editor put the action into the appropriate menu group (line actions | script actions | editor actions). The flag can be only put to a class extending AbstractAction through its AbstractAction.putValue(java.lang.String, java.lang.Object) method.

See Also:

Constant Field Values

Method Detail

getInterpret

TestScriptInterpret getInterpret()

Get the interpret. This method is intended to allow creation of interpret wrappers which implement this interface but they are not implementing the TestScriptInterpret one. Those interprets which implement both interfaces may simply return themselves.

Returns:

test script interpret behind this interface.

getCommandHandlerForElement

CommandHandler getCommandHandlerForElement(int offset,
                                           LinkedHashMap<String,Object> parameters)

Get the command handler associated with the code contained in the particular document element. This is typically called on the right mouse click by the editor to populate command specific actions declared through the CommandHandler.getStablePopupMenuItems() method.

Parameters:

offset - position in the document to parse for the data..

parameters - optional output map for parameters parsed by the interpret at the specified position. If the map is null, parameters will not be read.

Returns:

command handler or null if the code does not correspond to a call of a known command handler.

modifyOrInsert

int modifyOrInsert(int offset,
                   boolean replace,
                   String command,
                   LinkedHashMap<String,Object> parameters,
                   int[] outCoords)

Create a new method or a command call using the specified parameter map and insert it to the specified offset (position).If the offset corresponds to an already existing call of the same command, handle the insertion as replacement. If the offset refers to a position of another incompatible command/call, insert it after the other command/call.

Parameters:

offset - offset (position) in the test script source code document.

replace - true to replace, false to insert anew.

command - name as is specified by the CommandHandler.getCommandNames() method of the command handler (usually in lower case).

parameters - command parameters.

outCoords - optional output array of the minimum length of 2 to store the start offset and the length of the created/modified command to. It may be null where the calling class is not interested in it.

Returns:

recommended new caret position for the editor.

create

CharSequence create(int offset,
                    String command,
                    LinkedHashMap<String,Object> parameters)

Create a new method or a command call using the specified parameter map and return it.

Parameters:

offset - offset (position) in the test script source code document. It is here just for a reference because the command is not being inserted into the editor. The interpret however may decide to return different commands depending on the current editor offset. For example, a TPR script may contain Java code in form of Java code blocks and a Java command may be required instead of a TPR one if the offset is inside such a block.

command - name as is specified by the CommandHandler.getCommandNames() method of the command handler (usually in lower case).

parameters - command parameters.

Returns:

the command line.

replace

int replace(int offset,
            int length,
            String command,
            LinkedHashMap<String,Object> parameters,
            int[] outCoords)

Replace the text at the specified coordinates with a new method or a command call created from the specified command name and parameter map. This method should perform the same operation as a call of the modifyOrInsert(int, boolean, java.lang.String, java.util.LinkedHashMap, int[]) method with the replace parameter set to true save that no analysis of the replaced command is required. This allows to optimize performance where the calling class (typically the script recorder) needs to replace a call that is previously created and thus its coordinates are well known.

Parameters:

offset - offset (position) in the test script source code document.

length - length of the text to be replaced.

command - name as is specified by the CommandHandler.getCommandNames() method of the command handler (usually in lower case).

parameters - command parameters.

outCoords - optional output array of the minimum length of 2 to store the start offset and the length of the created/modified command to. It may be null where the calling class is not interested in it.

Returns:

recommended new caret position for the editor.

areNestedInterpretsSupported

boolean areNestedInterpretsSupported()

Declare whether the interpret supports nested interprets (code of a different type embedded into the interpret's native code, such as for example Java code block). If nesting is supported and the method returns true, the editor makes an attempt to retrieve properties from the nested interpret instance to get additional interpret-specific menu actions and GUI features.

Returns:

true if nested interprets are supported, false if not.

canSetBreakPoint

boolean canSetBreakPoint(int offset)

Define if a break point can be set on the given element (line of code).

Parameters:

offset - a document element offset.

Returns:

true if a break point can be created at the given line or false otherwise.

getTemplatePath

CharSequence getTemplatePath(int offset,
                             boolean reportDefaultPathAsNull,
                             boolean resolveVariables)

Get the template path valid for the code at the given offset.The method is supposed to return the file path (as String) or the expression the path is set to (as a StringBuilder or StringBuffer). If the path is not explicitly set the method returns either the default output path (reportDefaultPathAsNull=false) or null (reportDefaultPathAsNull=true).

Parameters:

resolveVariables - true to make the method resolve variables in the returned value.

offset - the script offset to start from. To search for the very first path setting use the offset of -1.

reportDefaultPathAsNull - true makes the method return null instead of the default path if the given script doesn't explicitly set the path.

Returns:

template path at the specified code position.

getOutputPath

CharSequence getOutputPath(int offset,
                           boolean reportDefaultPathAsNull,
                           boolean resolveVariables)

Get the output (report) path valid for the code at the given offset.The method is supposed to return the file path (as String) or the expression the path is set to (as a StringBuilder or StringBuffer). If the path is not explicitly set the method returns either the default output path (reportDefaultPathAsNull=false) or null (reportDefaultPathAsNull=true).

Parameters:

resolveVariables - true to make the method resolve variables in the returned value.

offset - the script offset to start from. To search for the very first path setting use the offset of -1.

reportDefaultPathAsNull - true makes the method return null instead of the default path if the given script doesn't explicitly set the path.

Returns:

output (report) path at the specified code position.

setOutputPath

int setOutputPath(CharSequence path,
                  int offset)

Update the script output path at the selected offset of the editor.

The output path is a directory where all output data such as screenshots and reports are being saved to when the script gets executed. Setting of the path is script specific. For example, the TPR interpret sets the path through the variable call like "Var _REPORT_DIR=[path]". When this method is called it simply creates the call at the specified offset or updates the existing one with the new path.

Parameters:

path - a new output path.

offset - an offset (location) in the editor.

Returns:

the start offset of the created/updated call.

setTemplatePath

int setTemplatePath(CharSequence path,
                    int offset)

Update the template path at the selected offset of the editor.

The template path is a directory where comparison commands such as Compareto or Click look for template (component) images. Setting of the path is script specific. For example, the TPR interpret sets the path through the variable call like "Var _TEMPLATE_DIR=[path]". When this method is called it simply creates the call at the specified offset or updates the existing one with the new path.

Parameters:

path - a new template path.

offset - an offset (location) in the editor.

Returns:

the start offset of the created/updated call.

createVariableCall

String createVariableCall(String variableName,
                          Class returnType)

Create a piece of code that returns value of the specified variable.

Parameters:

variableName - the variable name.

returnType - may be used to indicate the desired return value type. The method should presume a string value by default.

Returns:

a call to retrieve the variable name. For example, the TPR interpret returns a call like "{variableName}" while the Java one produces "getVariableAsString(\"variableName\")".

canReport

boolean canReport()

Indicate if the interpret is capable of producing a report. The value is used by the GUI component that allows to edit the report attributes.

Returns:

true/false if reporting is supported/not supported.

getReport

LinkedHashMap<String,Object> getReport(int offset)

Get report properties (parameters) from the report producing command at the specified offset. The value is used by the GUI component that allows to edit the report attributes.

Parameters:

offset - an offset (location) in the editor.

Returns:

an ordered map with the report parameters.

setReport

int setReport(int offset,
              LinkedHashMap<String,Object> parameters)

Create or update the report producing command at the specified offset. The value is used by the GUI component that allows to edit the report attributes.

Parameters:

offset - an offset (location) in the editor.

parameters - an ordered map with the report parameters.

Returns:

the start offset of the created/updated command.

getNewScriptPreferences

Configurable getNewScriptPreferences(PreferenceContainer preferences)

Get the specification of preferences applicable to a new script.Interprets which do not populate a new test script with a configurable template may simply return null.

If a valid Configurable instance is returned and its Configurable.getPreferences() methods returns a list of one or more preferences is returned, they will be displayed to by the GUI whenever the user selects to create a new script of the type associated with this interpret. After the user populates the preferences, the values are passed to the interpret through createNewScript(com.tplan.robot.preferences.PreferenceContainer) to create the initial content and after that the script is opened in the editor.

Parameters:

preferences - a preference container.

Returns:

an object implementing the Configurable interface.

createNewScript

int createNewScript(PreferenceContainer preferences)

Create a new script instance based on the specified preferences. See the getNewScriptPreferences(com.tplan.robot.preferences.PreferenceContainer) method for more.

Parameters:

preferences - script preferences. Interprets which do not populate a new test script with a configurable template may simply return 0 to specify that the caret should be placed to the beginning of the document.

Returns:

recommended caret position.

canCollapseCode

boolean canCollapseCode()

Find out whether the interpret is capable of identifying of areas which may be collapsed (hidden) in order to make a custom or simpler script code view.

Returns:

true if the interpret supports collapsing, false if not.

getCollapsibleAreas

LinkedHashMap<String,int[]> getCollapsibleAreas()

Get coordinates of the collapsible areas. This method will be called only if the canCollapseCode() method returns true.

Returns:

array of collapsible areas identified by the [startPosition, endPosition] offset pairs.

refreshStyle

void refreshStyle()

Refresh document styles. This is an auxiliary method allowing editors to let the interpret know that code changes have been applied and the view should be refreshed. Though the interpret is attached to the document listener interface and typically refreshes the view on any change, this method may help where the nature of code changes makes the interpret miss it.

getPopUpMenuActions

List<Action> getPopUpMenuActions(Point p,
                                 int offset)

Get the list of interpret specific actions for the given point and offset. The actions are typically displayed in a pop up (context) menu displayed on right mouse click over the editor.

Parameters:

offset - document offset associated with the given click point.

p - the click point.

Returns:

list of interpret specific actions.

isComment

boolean isComment(int offset)

Define whether the specified offset in the code is inside a comment or not.

Parameters:

offset - an offset.

Returns:

true if it is a comment, false if not.

toggleComment

void toggleComment(int offset,
                   boolean commentOut)

Comment out or uncomment the command at the specified index.

Parameters:

offset - an offset.

commentOut - true will comment out (turn the command into a comment), false uncomments.

isGradualCommandBuildingSupported

boolean isGradualCommandBuildingSupported()

This method defines whether the interpret allows gradual building of a command in the test script editor. If the method returns true the Command Wizard GUI component will insert selected items directly to the editor after every completed step. This is typical for example for scripting language interprets where the user first selects the command name and then the argument and/or parameters.

If the method returns false the GUI does not insert anything into the editor and passes the selected command elements to the interpret which is responsible for creating the call once all parameters have been specified. This is typical for programming languages such as Java where selection of a Java method should not insert anything into the editor until all parameters of the method call are specified and the underlying mapper is able to identify the particular method to be used.

.

Returns:

true if gradual command building is supported, false otherwise.

getUsedImages

Map<File,List<ScriptReferenceLocation>> getUsedImages()

Get the list of images used by the script for image comparison.

Returns:

map of used image files and their locations.

getUsedVariables

Map<String,Object> getUsedVariables(int offset)

Get the map of variables existing at the given script position. This method is called by the code generators to avoid using of already reserved variable names.

Parameters:

offset - a position in the script.

Returns:

map of variable names

getLastCodeLineOffset

int getLastCodeLineOffset()

Get offset (document position) of the last script code line. This is typically used by components that need to append some code to the end of the script. For a TPR test script the method typically returns the start position of the last document line. Java test scripts on the other hand return start position of the last code line within the try-catch block inside the test() method.

Returns:

the last command offset.

getHelpKeyForOffset

String[] getHelpKeyForOffset(int offset)

Return a help key for the specified offset. It is used to inject references to the Robot documentation to the editor context menus.

Parameters:

offset - an offset.

Returns:

null or an array of two items, the key and the label (name).

isBlockStartOrEnd

int[] isBlockStartOrEnd(int offset)

Find out if the argument offset is near to the block start or end, typically close to the opening or closing curly brace ('{' or '}'), and get the start/end coordinates. This information is typically used by the GUI (script editor) to highlight the start and end of the code block. Implementing classes that wish to skip this feature may return null.

Parameters:

offset - an offset

Returns:

null or an array of 4 values of [blockStart, length, blockEnd, length] which determine the start and end offsets and lengths of the block.

canInsertCommandTo

boolean canInsertCommandTo(int offset)

Find out if it is legal to insert a command or a method call to the given offset.

Parameters:

offset - a document offset.

Returns:

true if the position can be updated or false if not.

Since:

4.0

isCodeInsertionSupported

boolean isCodeInsertionSupported()

Test if the interpret is capable of generating the script code. It is more general than canInsertCommandTo(int). The method is typically used for enabling or disabling of menu items working with the script editor.

Returns:

true if the test script editor can generate code through the modifyOrInsert(int, boolean, java.lang.String, java.util.LinkedHashMap, int[]) method or false otherwise.

Since:

4.0