Driving FScript

Using FScript in your code

A number of methods exist to enable your application to load FScript code into FScript, and have FScript execute it. These are:

load

The load method is used to load a complete FScript source from a Reader. This is the technique used by FSTest.java.

loadLine

loadLine loads one line (as a String) at a time into FScript. This is the technique used by theDocProc.java example.

run

This method executes the loaded FScript code (from the start of the code to the end). If any errors are encountered it will throw a FSException. The method getError could then be called to gain more error information if necessary

If there is a return statement in the top level of the executed FScript, run will return the value specified in the return statement (either an Integer, String or Double).

reset

This method resets FScript - removing any previously loaded code.

cont

This method continues execution of fscript from the current code position to the end of the script

This is useful for document processing applications where code such as :

	fscript.loadLine(line[1]);
	fscript.loadLine(line[2]);
	...
	fscript.run();
	fscript.loadLine(line[19]);
	fscript.loadLine(line[20]);
	...
	fscript.cont();

In the above example the call to cont simply restarts execution at the end of the previous run, and continues to the (current) end of the script. It is safe to use cont as your first call to execute code, so in the above example the first run could just have well have been a cont .

If there is a return statement in the top level of the executed FScript, cont will return the value specified in the return statement (either an Integer, String or Double).

evaluateExpression

This method returns the result of evaluating the FScript expression passed as a string. If a script has previously been loaded and run, this expression is evaluated in the context of the previous script, so variables and functions defined in the script will be available.

For example if no previous script had been run and

fs.evaluateExpression("1+2+3")

However if a previous script had defined int variables 'a' and 'b' with values 4 and 3 then

fs.evaluateExpression("a+b-2")

getError

See the JavaDoc for full details of get error. This method returns more information about a FSException condition - this is the same information available in the message of an FSException but structured to make it easy to process programatically.

Accessing Script Variables/Functions

As of FScript version 1.0 it is possible for the host application to access FScript level variables and functions. There is an example showing this in the examples directory. Note that these functions will only work after the script has been executed (via run orcont ). In in some cases it may make sense to have a script only containing functions and global variable declarations, and then manipulate these via the methods described below.

There are three methods provided to allow access:

• callScriptFunction
• setScriptVar
• getScriptVar

callScriptFunction

callScript function executes a FSCript function, it takes two parameters, the name of the function (a String) and a list of parameters (an ArrayList). In order for the call to succeed the function with the name (case sensitive) must exist and there must be the correct number and type of parameters (in the same order they were defined). The return value is the returned Object (if any).

set/getScriptVar

These functions allow access to script level variables. getScriptVar returns the Object which is associated with the script level variable with the name that is passed as a parameter. setScriptVar sets the script level variable with the name passed as a parameter to the given Object.

Notes

As with all FScript methods the Object parameters are restricted to the subset supported by FScript itself (currently String, Integer and Double). It is also important to note that if a call is made to any of these methods with the name of a variable/function that is not defined by the script, FScript will behave exactly as it would if that call had been made from within a script and make calls to getVar/setVar/callFunction. This could be especially problematic if the script access calls are made from within one of the handler methods (getVar/setVar/callFunction).