public class Frink
extends java.lang.Object
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.)
Constructor and Description |
---|
Frink()
Construct a new interpreter with default configuration.
|
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.
|
public Frink()
public java.lang.String parseString(java.lang.String str) throws FrinkEvaluationException
str
- The string to parseFrinkEvaluationException
- If an error occurs in parsing or
evaluating the exception.public frink.expr.Expression parseStringToExpression(java.lang.String str)
str
- The string to parse.public void parseStrings(java.lang.String[] args) throws FrinkEvaluationException
args
- An array of strings to be parsed in order.FrinkEvaluationException
- Thrown if any error occurs in parsing
or evaluating the strings.public void parseFilename(java.lang.String filename)
filename
- The filename to execute. This may be an absolute or
relative pathname.public void parseCodeSource(frink.parser.CodeSource cs)
cs
- The CodeSource to execute. This may be an absolute or
relative pathname.public java.lang.String[] parseArguments(java.lang.String[] args)
args
- An array of arguments to parse.public void setUnitsFile(java.lang.String filename)
THINK ABOUT: Should this throw an exception if the units have already been initialized?
filename
- An absolute or relative filename to read.public void setRestrictiveSecurity(boolean flag)
flag
- Setting this value to true enables restrictive security,
and false sets to no security.public frink.expr.Environment getEnvironment()
public void setVariable(java.lang.String variable, java.lang.String value)
variable
- The name of the variable to be set.value
- The value of the string variable.public void setVariable(java.lang.String variable, boolean value)
variable
- The name of the variable to be set.value
- The value of the boolean variable.public void setVariable(java.lang.String variable, java.util.Calendar value)
variable
- The name of the variable to be set.value
- A variable indicating the date. This will be cloned.public void setVariable(java.lang.String variable, java.util.Date value) throws UnknownUnitException
variable
- The name of the variable to be set.value
- A variable indicating the date. This will be cloned.UnknownUnitException
public void setVariable(java.lang.String variable, double scale, java.lang.String unit) throws UnknownUnitException, UnexpectedTypeException
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.UnknownUnitException
UnexpectedTypeException
public void setVariable(java.lang.String variable, int scale, java.lang.String unit) throws UnknownUnitException, UnexpectedTypeException
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.UnknownUnitException
UnexpectedTypeException
public void setVariable(java.lang.String variable, long scale, java.lang.String unit) throws UnknownUnitException, UnexpectedTypeException
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.UnknownUnitException
UnexpectedTypeException
public void setVariable(java.lang.String variable, java.math.BigInteger scale, java.lang.String unit) throws UnknownUnitException, UnexpectedTypeException
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.UnknownUnitException
UnexpectedTypeException
public void setVariable(java.lang.String variable, java.lang.Object value)
setVariableMapped(java.lang.String, java.lang.Object)
method.variable
- The name of the variable to be set.value
- The object to be turned into a JavaObject.public void setVariableMapped(java.lang.String variable, java.lang.Object value)
variable
- The name of the variable to be set.value
- The vlaue to be turned into Frink type.public double getVariableAsDouble(java.lang.String variable, java.lang.String units) throws UnknownVariableException, UnexpectedTypeException, UnknownUnitException
variable
- The name of the variableunits
- 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.UnknownVariableException
UnexpectedTypeException
UnknownUnitException
public frink.units.Unit getVariableAsUnit(java.lang.String variable) throws UnexpectedTypeException
UnexpectedTypeException
public frink.expr.Expression getVariableAsExpression(java.lang.String variable)
public static void main(java.lang.String[] args)