frink.parser

Class Frink

java.lang.Object

frink.parser.Frink

public class Frink
extends java.lang.Object

This class is the interface to all of Frink's functionality. It is an interpreter for the Frink language, and contains methods to integrate this interpreter with Java programs.

Embedding a Frink parser in a Java program can be quite simple. First, make sure that frink.jar is in your classpath. Then, all you need to do is create a Frink interpreter and then communicate with it via strings:

String results;
Frink interp = new Frink();

// Enable security here? Currently commented-out.
// interp.setRestrictiveSecurity(true);

try
{
results = interp.parseString("2+2");
}
catch (frink.errors.FrinkEvaluationException fee)
{
// Do whatever you want with the exception
}


This evaluates the expression 2+2 and returns the results as a string. Of course, the 2+2 could be any Frink program of any length, even spanning multiple lines. The Frink interpreter can be re-used; that is, you can call its parseString(java.lang.String) method multiple times, and each invocation will change the state of the Frink parser. When you're through with the interpreter, you can simply create a new one.

The other getter and setter methods allow variables to be set directly in the Frink interpreter, converting to and from native Java types. Since conversion to and from Frink types can potentially lose information, these methods throw exceptions if the types cannot be properly converted. All of the exceptions thrown are subclasses of FrinkConversionException, so you can catch that single exception type or the more specific sub-exceptions.

Warning: Frink is a Turing-complete programming language, and parseString() evaluates a string as a complete program. A Frink interpreter normally has the ability to read your filesystem, call arbitrary Java code, execute infinite loops, allocate infinite amounts of memory, write large amounts of output, and do other things which may compromise your security. Thus, if you're taking input from untrusted users, it's critical to call:

interp.setRestrictiveSecurity(true);

before parsing any untrusted user input. See setRestrictiveSecurity(boolean) This will enable the highest level of security, prohibiting all untrusted actions.

The other way of communicating between Frink and Java is to call Java methods from a Frink program using the Java Introspection features of Frink. (Link opens in new window.)

Author:

Alan Eliasen, eliasen@mindspring.com

Constructor Summary

Constructors

Constructor and Description
Frink() Construct a new interpreter with default configuration.

Method Summary

Modifier and Type	Method and Description
frink.expr.Environment	getEnvironment() Returns the Environment contained in this parser.
double	getVariableAsDouble(java.lang.String variable, java.lang.String units) Gets the value of a variable as a double.
frink.expr.Expression	getVariableAsExpression(java.lang.String variable) Gets the variable as an Expression.
frink.units.Unit	getVariableAsUnit(java.lang.String variable) Gets the variable as a unit.
static void	main(java.lang.String[] args) Create a new Frink interpreter and parse arguments.
java.lang.String[]	parseArguments(java.lang.String[] args) Parses command-line arguments and removes them from the list.
void	parseCodeSource(frink.parser.CodeSource cs) Parse (and execute) a CodeSource.
void	parseFilename(java.lang.String filename) Parse (and execute) a filename.
java.lang.String	parseString(java.lang.String str) Parse a string and execute it.
void	parseStrings(java.lang.String[] args) Parse a series of strings in immediate mode.
frink.expr.Expression	parseStringToExpression(java.lang.String str) Parse a string to an Expression without evaluating it.
void	setRestrictiveSecurity(boolean flag) This is a convenience method to enable strictest security.
void	setUnitsFile(java.lang.String filename) Set units file to the specified filename, null to use standard units.
void	setVariable(java.lang.String variable, java.math.BigInteger scale, java.lang.String unit) Set a variable with the specified scale and units.
void	setVariable(java.lang.String variable, boolean value) Set a boolean variable.
void	setVariable(java.lang.String variable, java.util.Calendar value) Set a variable from a Calendar object.
void	setVariable(java.lang.String variable, java.util.Date value) Set a variable from a Date object.
void	setVariable(java.lang.String variable, double scale, java.lang.String unit) Set a variable with the specified scale and units.
void	setVariable(java.lang.String variable, int scale, java.lang.String unit) Set a variable with the specified scale and units.
void	setVariable(java.lang.String variable, long scale, java.lang.String unit) Set a variable with the specified scale and units.
void	setVariable(java.lang.String variable, java.lang.Object value) Sets a variable as a Java Object.
void	setVariable(java.lang.String variable, java.lang.String value) Set a string variable.
void	setVariableMapped(java.lang.String variable, java.lang.Object value) Sets a variable, attempting to convert the Object into an appropriate internal Frink type.

Methods inherited from class java.lang.Object

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

Constructor Detail

Frink

public Frink()

Construct a new interpreter with default configuration. After construction, the interpreter is ready to use.

Method Detail

parseString

public java.lang.String parseString(java.lang.String str)
                             throws FrinkEvaluationException

Parse a string and execute it. The string can contain any Frink expression on one line or multiple lines. The return value is

Parameters:

str - The string to parse

Returns:

A String representing the result of executing the string passed in. If the string passed in is null, this returns null.

Throws:

FrinkEvaluationException - If an error occurs in parsing or evaluating the exception.

parseStringToExpression

public frink.expr.Expression parseStringToExpression(java.lang.String str)

Parse a string to an Expression without evaluating it. The string can be any Frink expression on one line or multiple lines. This method does not execute the string, but rather returns an Expression object that can later be evaluated.

Parameters:

str - The string to parse.

Returns:

An Expression corresponding to the parsed string.

parseStrings

public void parseStrings(java.lang.String[] args)
                  throws FrinkEvaluationException

Parse a series of strings in immediate mode.

Parameters:

args - An array of strings to be parsed in order.

Throws:

FrinkEvaluationException - Thrown if any error occurs in parsing or evaluating the strings.

parseFilename

public void parseFilename(java.lang.String filename)

Parse (and execute) a filename.

Parameters:

filename - The filename to execute. This may be an absolute or relative pathname.

parseCodeSource

public void parseCodeSource(frink.parser.CodeSource cs)

Parse (and execute) a CodeSource.

Parameters:

cs - The CodeSource to execute. This may be an absolute or relative pathname.

parseArguments

public java.lang.String[] parseArguments(java.lang.String[] args)

Parses command-line arguments and removes them from the list. This returns any command-line arguments not intended for it.

Parameters:

args - An array of arguments to parse.

Returns:

An array of arguments, with parsed arguments removed from the list. If the arguments passed in are null, this will be null.

setUnitsFile

public void setUnitsFile(java.lang.String filename)

Set units file to the specified filename, null to use standard units. You don't need to call this method, (Frink will use the standard data file if you don't,) but if you do call it, it must be called before parsing anything else.

THINK ABOUT: Should this throw an exception if the units have already been initialized?

Parameters:

filename - An absolute or relative filename to read.

setRestrictiveSecurity

public void setRestrictiveSecurity(boolean flag)

This is a convenience method to enable strictest security. It sets the most restrictive security level for running programs when set to true, and clears all security, enabling all programs, when set to false. This can be turned on and off, but of course it's a good idea to enable it before parsing any code from untrusted users!

Parameters:

flag - Setting this value to true enables restrictive security, and false sets to no security.

getEnvironment

public frink.expr.Environment getEnvironment()

Returns the Environment contained in this parser. Be careful if you're messing around with this. You shouldn't have to unless you're doing some odd integration work with an external environment.

setVariable

public void setVariable(java.lang.String variable,
                        java.lang.String value)

Set a string variable.

Parameters:

variable - The name of the variable to be set.

value - The value of the string variable.

setVariable

public void setVariable(java.lang.String variable,
                        boolean value)

Set a boolean variable.

Parameters:

variable - The name of the variable to be set.

value - The value of the boolean variable.

setVariable

public void setVariable(java.lang.String variable,
                        java.util.Calendar value)

Set a variable from a Calendar object.

Parameters:

variable - The name of the variable to be set.

value - A variable indicating the date. This will be cloned.

setVariable

public void setVariable(java.lang.String variable,
                        java.util.Date value)
                 throws UnknownUnitException

Set a variable from a Date object.

Parameters:

variable - The name of the variable to be set.

value - A variable indicating the date. This will be cloned.

Throws:

UnknownUnitException

setVariable

public void setVariable(java.lang.String variable,
                        double scale,
                        java.lang.String unit)
                 throws UnknownUnitException,
                        UnexpectedTypeException

Set a variable with the specified scale and units.

Parameters:

variable - The name of the variable to be set.

scale - The size of the variable as a multiple of unit.

unit - A string indicating the name of the unit. If this is null or the empty string, the value is dimensionless.

Throws:

UnknownUnitException

UnexpectedTypeException

setVariable

public void setVariable(java.lang.String variable,
                        int scale,
                        java.lang.String unit)
                 throws UnknownUnitException,
                        UnexpectedTypeException

Set a variable with the specified scale and units.

Parameters:

variable - The name of the variable to be set.

scale - The size of the variable as a multiple of unit.

unit - A string indicating the name of the unit. If this is null or the empty string, the value is dimensionless.

Throws:

UnknownUnitException

UnexpectedTypeException

setVariable

public void setVariable(java.lang.String variable,
                        long scale,
                        java.lang.String unit)
                 throws UnknownUnitException,
                        UnexpectedTypeException

Set a variable with the specified scale and units.

Parameters:

variable - The name of the variable to be set.

scale - The size of the variable as a multiple of unit.

unit - A string indicating the name of the unit. If this is null or the empty string, the value is dimensionless.

Throws:

UnknownUnitException

UnexpectedTypeException

setVariable

public void setVariable(java.lang.String variable,
                        java.math.BigInteger scale,
                        java.lang.String unit)
                 throws UnknownUnitException,
                        UnexpectedTypeException

Set a variable with the specified scale and units.

Parameters:

variable - The name of the variable to be set.

scale - The size of the variable as a multiple of unit.

unit - A string indicating the name of the unit. If this is null or the empty string, the value is dimensionless.

Throws:

UnknownUnitException

UnexpectedTypeException

setVariable

public void setVariable(java.lang.String variable,
                        java.lang.Object value)

Sets a variable as a Java Object. This will not try to map to a Frink type, but rather set as the object type itself using Frink's Java introspection layer. If you want Frink to attempt to convert the value to one of its internal types, use the setVariableMapped(java.lang.String, java.lang.Object) method.

Parameters:

variable - The name of the variable to be set.

value - The object to be turned into a JavaObject.

setVariableMapped

public void setVariableMapped(java.lang.String variable,
                              java.lang.Object value)

Sets a variable, attempting to convert the Object into an appropriate internal Frink type.

Parameters:

variable - The name of the variable to be set.

value - The vlaue to be turned into Frink type.

getVariableAsDouble

public double getVariableAsDouble(java.lang.String variable,
                                  java.lang.String units)
                           throws UnknownVariableException,
                                  UnexpectedTypeException,
                                  UnknownUnitException

Gets the value of a variable as a double.

Parameters:

variable - The name of the variable

units - A string indicating the units that the value is returned in. This essentially divides by the size of the unit. If this is null or the empty string, the value of the variable is expected to be a dimensionless variable.

Throws:

UnknownVariableException

UnexpectedTypeException

UnknownUnitException

getVariableAsUnit

public frink.units.Unit getVariableAsUnit(java.lang.String variable)
                                   throws UnexpectedTypeException

Gets the variable as a unit. If there is no variable with this name, this returns null.

Throws:

UnexpectedTypeException

getVariableAsExpression

public frink.expr.Expression getVariableAsExpression(java.lang.String variable)

Gets the variable as an Expression. If there is no variable with this name, this returns null.

main

public static void main(java.lang.String[] args)

Create a new Frink interpreter and parse arguments. If no files to parse, begin an interactive session.