prefuse.data.expression.parser

Class ExpressionParser

java.lang.Object

prefuse.data.expression.parser.ExpressionParser

All Implemented Interfaces:

ExpressionParserConstants

public class ExpressionParser
extends java.lang.Object
implements ExpressionParserConstants

Parser for statements written in the prefuse expression language. Text expression are parsed into Expression instances, and can be used as predicates or to create derived table columns. This parser is implemented using the JavaCC package. To parse a text String to an Expression, use the parse(String) method. If a parse error occurs, the method will fail silently and return null. Any generated exception can be later retrieved using the getError() method. One can also use the parse(String, boolean) with a true boolean argument to request that Exceptions be thrown when errors occur.

Prefuse Expression Language Reference

The prefuse expression language provides a convenient way of creating manipulable statements over data in a prefuse data structure. For example, the expression language can be used to write Predicate instances for querying and filtering a table or graph, or to create arbitrary expressions over a data set to generate new, derived data fields that can in turn be subject to additional processing or visualization. For example, the TupleSet.tuples(prefuse.data.expression.Predicate) method uses a Predicate to filter the requested set of tuples, and the Table.addColumn(java.lang.String,prefuse.data.expression.Expression) method creates a new table column whose values are generated by the provided Expression. The expression machinery is used throughout the toolkit -- it underlies the filtering and query optimization features, is a key component of dynamic query bindings, and is used to create the rule chains evaluated by the DefaultRendererFactory, ColorAction, ShapeAction, FontAction, and SizeAction classes.

The Expression interface is quite simple: given a single Tuple, compute and return a value. The returned value could be an Object, a boolean, an int, or other primitive type. Individual methods for each type are available, and which ones are legal to call for any given Expression depends on the type of Expression.

Expressions can be created directly in Java, by instantiating and chaining together the desired Expression instances. This process, however, can be somewhat tedious, so prefuse also provides a built-in parser/compiler for generating these chains of Expression instances from a textual language. The language is based on a subset of SQL, the standard language for database queries. If you have ever written a "WHERE" clause in a SQL "SELECT" query, you probably know most of the language already. To parse an expression, simply pass a text string containing an expression statement to the parse(java.lang.String) method. If the string parses successfully, the parsed Expression instance will be returned.

Below is the reference for the language, including literal types, data field references, basic operators, and included functions. If need be, you can also introduce a new function by creating a new instance of the Function interface and registering it with the FunctionTable class.

All keywords and functions in the prefuse expression language can be written in either uppercase or lowercase. Writing in mixed-case, however, will likely result in parse errors.

Literal Values and Data Field References

The fundamental building blocks of the expression language, representing data values or referencing the contents of a Tuple data field.

• Boolean literals (TRUE, FALSE)
  The boolean literals representing true and false conditions, parsed to type boolean
• Integer literals (1, -5, 12340)
  Undecorated, non-decimal numbers are parsed as numbers of type int
• Long literals (1L, -5L, 12340L)
  Integer values decorated with the suffix "L" are parsed as numbers of type long
• Double literals (1.0, 3.1415, 1e-35, 2.3e6)
  Numbers with decimals or exponents in scientific notation are parsed as numbers of type double
• Float literals (1.0f, 3.1415f, 1e-35f, 2.3e6f)
  Floating-point values decorated with the suffix "f" are parsed as numbers of type float
• String literals ("some text", 'a label')
  Text strings placed in double (") or single (') quotations are parsed as String literals
• Null literal (null)
  The string null is parsed as an ObjectLiteral of type null.
• Data field references (_strokeColor, [a data field])
  Free-standing strings or those placed within brackets are parsed as a reference to the data field of that name. Brackets are required for any fields that include spaces or other unusual characters in their name (e.g., characters like +, -, *, etc), or conflict with an existing keyword For example, true parses to a boolean literal while [true] parses to a reference to a data field named 'true'.

Operators and Control Flow

Basic operators and control flow structures for the expression language.

• x + y (addition)
  Add x and y
• x - y (subtraction)
  Subtract y from x
• x * y (multiplication)
  Multiply x and y
• x / y (division)
  Divide x by y
• x ^ y (exponentiation, pow)
  Raise x to the exponent y
• x % y (modulo)
  Return the remainder of x divided by y
• x = y, x == y (equality)
  Indicates if x and y are equal
• x != y, x <> y (inequality)
  Indicates if x and y are not equal
• x > y (greater than)
  Indicates if x is greater than y
• x >= y (greater than or equal to)
  Indicates if x is greater than or equal to y
• x < y (less than)
  Indicates if x is less than y
• x <= y (less than or equal to)
  Indicates if x is less than or equal to y
• x AND y, x && y (and)
  Indicates if both x and y are true
• x OR y, x || y (or)
  Indicates if either x or y is true
• NOT x, !x (not)
  Indicates if the negation of x is true
• x XOR y (exclusive or)
  Indicates if one, but not both, of x or y is true
• IF test THEN x ELSE y (if-then-else)
  Evaluates the predicate test, and if true evaluates and returns the expression x, and if false evaluates and returns the expression y
• () (parentheses)
  Groups expressions together to enforce a particular order of evaluation. For example, 1+2*3 evaluates to 7, while (1+2)*3 evaluates to 9.

General Functions

General purpose functions.

• ROW()
  Returns the table row number (or -1 if none) of the current Tuple.
• ISNODE()
  Returns true if the current Tuple is a graph Node.
• ISEDGE()
  Returns true if the current Tuple is a graph Edge.
• DEGREE()
  If the current Tuple is graph Node, returns the Node degree (the total number of incident edges). Otherwise returns 0.
• INDEGREE()
  If the current Tuple is graph Node, returns the Node indegree (the number of incident edges pointing towards this node). Otherwise returns 0.
• OUTDEGREE()
  If the current Tuple is graph Node, returns the Node outdegree (the number of incident edges pointing away from the node). Otherwise returns 0.
• CHILDCOUNT()
  If the current Tuple is graph Node, returns the number of tree children nodes. If the Tuple is not a Node, this method returns 0. If the Node is part of a Graph (not a Tree), the number of children nodes in the current spanning tree is returned. If no spanning tree has been computed, a new spanning tree will be computed using the default method. See Graph.getSpanningTree() for more.
• TREEDEPTH()
  If the current Tuple is graph Node, returns the depth of this Node in its Tree or SpanningTree. If the Tuple is not a Node, this method returns 0. If the Node is part of a Graph (not a Tree), the tree depth of the node in the current spanning tree is returned. If no spanning tree has been computed, a new spanning tree will be computed using the default method. See Graph.getSpanningTree() for more.

Mathematical Functions

Functions for performing mathematical calculations.

• ABS(x)
  Returns the absolute value of x
• ACOS(x)
  Returns the inverse cosine (arc cosine) of a x
• ASIN(x)
  Returns the inverse sine (arc sine) of a x
• ATAN(x)
  Returns the inverse tangent (arc tangent) of a x
• ATAN2(y, x)
  For the Cartesian coordinates x, y return the polar coordinate angle theta
• CEIL(x), CEILING(x)
  Returns the nearest integer value greater than or equal to x.
• COS(x)
  Returns the cosine of x
• COT(x)
  Returns the cotangent of x
• DEGREES(x)
  Converts x from radians to degrees
• EXP(x)
  Returns the value of e (the base of natural logarithms) raised to the x power
• FLOOR(x)
  Returns the nearest integer value less than or equal to x.
• LOG(x), LOG(b, x)
  With one argument, returns the natural logarithm (logarithm base e) of x
  With two arguments, returns the logarithm of x for the provided base b
• LOG2(x)
  Returns the logarithm base 2 of x
• LOG10(x)
  Returns the logarithm base 10 of x
• MAX(a, b, c, ...)
  Returns the maximum value among the provided arguments
• MIN(a, b, c, ...)
  Returns the minimum value among the provided arguments
• MOD(x, y)
  Returns x modulo y (the remainder of x divided by y)
• PI()
  Returns the constant π (= 3.1415926535...), the ratio between the circumference and diameter of a circle
• POW(x, y), POWER(x, y)
  Return the value of x raised to the exponent y
• RADIANS(x)
  Converts x from degrees to radians
• RAND()
  Returns a random floating-point value between 0 and 1
• ROUND(x)
  Returns the value of x rounded to the nearest integer
• SIGN(x)
  Returns the sign of x: 1 for positive, -1 for negative
• SIN(x)
  Returns the sine of x
• SQRT(x)
  Returns the square root of x
• SUM(a, b, c, ...)
  Returns the sum of the provided input value
• TAN(x)
  Returns the tangent of x
• SAFELOG10(x)
  Returns a "negative safe" logarithm base 10 of x, equivalent to SIGN(x) * LOG10(ABS(x))
• SAFESQRT(x)
  Returns a "negative safe" square root of x, equivalent to SIGN(x) * SQRT(ABS(x))

String Functions

Functions for processing text strings.

• CAP(str)
  Capitalize words in the string str. Individual words/names will be given uppercase first letters, with all other letters in lowercase.
• CONCAT(a, b, c, ...)
  Concatenate the input strings into one resulting string.
• CONCAT_WS(sep, a, b, c, ...)
  Concatenate with separator. Concatenates the input strings into one resulting string, placing the string sep between each of the other arguments
• FORMAT(x, d)
  Format the number x as a string of the type "#,###.##", showing d decimal places
• INSERT(str, pos, len, newstr)
  Replaces the substring of length len starting at position pos in input string str with the string newstr
• LEFT(str, len)
  Returns the leftmost len characters of string str
• LENGTH(str)
  Returns the length, in characters, of the input string str
• LOWER(str), LCASE(str)
  Returns the string str mapped to lowercase letters
• LPAD(str, len, pad)
  Pad the left side of string str with copies of string pad, up to a total padding of len characters
• MID(str, pos, len)
  Return a substring of str of length len, starting at position pos
• POSITION(substr, str)
  Returns the starting position of the first occurrence of substring substr in the string str. Returns -1 if the substring is not found.
• REVERSE(str)
  Returns a reversed copy of the input string str
• REPEAT(str, count)
  Returns a string consisting of str repeated count times
• REPLACE(str, orig, replace)
  Returns a copy of str in which all occurrences of orig have been replaced by replace
• RIGHT(str, len)
  Returns the len rightmost characters of string str
• RPAD(x)
  Pad the right side of string str with copies of string pad, up to a total padding of len characters
• SPACE(n)
  Returns a string consisting of n whitespace characters
• SUBSTRING(str,pos), SUBSTRING(str,pos,len)
  For two arguments, returns the substring of str starting at position pos and continuing to the end of the string.
  For three arguments, returns the substring of str of length len, beginning at position pos
• UPPER(str), UCASE(str
  Returns the string str mapped to uppercase letters

Color Functions

Functions for generating, translating, and interpolating color values.

• RGB(r, g, b)
  Returns an integer representing a fully opaque RGB (red, green, blue) color value
• RGBA(r, g, b, a)
  Returns an integer representing an RGBA (red, green, blue, alpha/transparency) color value
• GRAY(v)
  Returns an integer representing a grayscale color value of intensity v
• HEX(hex)
  Returns an integer representing the RGB color value encoded by the hexadecimal number hex
• HSB(h, s, b)
  Maps the given hue (hue), saturation (s), and brightness (b) color space values (as floating point numbers between 0 and 1) to an integer representing an RGB color value
• HSBA(h, s, b, a)
  Maps the given hue (hue), saturation (s), brightness (b), and alpha (a) color space values (as floating point numbers between 0 and 1) to an integer representing an RGBA color value
• COLORINTERP(c1, c2, f)
  Returns an interpolated color value between the input colors c1 and c2 determined by the mixing proportion f, a value between 0 and 1

Visualization Functions

These functions can only be used when the Tuple being evaluated is a VisualItem, and provide access to data group information of the VisualItem's Visualization. Individual visual data fields can be accessed directly using a data field reference. For example, _x, _y, _hover, _highlight, _fillColor would evaluate to references for the x-coordinate, y-coordinate, mouse hover status, highlight status, and fill color, respectively.

• GROUPSIZE(group)
  Returns the number of members in the data group group
• INGROUP(group)
  Returns true if the current VisualItem is a member of data group group
• MATCH(group, includeAll)
  Returns true if the current VisualItem is currently a search match. This is similar to INGROUP(group), but also includes a possible special case when no query has been issued and all items should be counted as "matches" (indicated by includeAll being true).
• QUERY(group)
  Returns the current search query string in a search group of name group
• VISIBLE()
  Returns true if the current VisualItem is visible, equivalent to _visible
• VALIDATED()
  Returns true if the current VisualItem's bounds have been validated, equivalent to _validated

Field Summary

Fields

Modifier and Type	Field and Description
static Token	jj_nt
static Token	token
static ExpressionParserTokenManager	token_source

Fields inherited from interface prefuse.data.expression.parser.ExpressionParserConstants

ADD, AND, DECIMAL_LITERAL, DEFAULT, DIGIT, DIV, DOUBLE, ELSE, EOF, EQ, EXPONENT, FALSE, FLOAT, GE, GT, HEX_LITERAL, IDENTIFIER, IF, INT, LE, LETTER, LONG, LPAREN, LT, MOD, MUL, NE, NOT, NULL, OCTAL_LITERAL, OR, POW, QUOTED, RPAREN, STRING, SUB, THEN, tokenImage, TRUE, XOR

Constructor Summary

Constructors

Constructor and Description
ExpressionParser(ExpressionParserTokenManager tm)
ExpressionParser(java.io.InputStream stream)
ExpressionParser(java.io.Reader stream)

Method Summary

Modifier and Type	Method and Description
static Expression	AdditiveExpression()
static Expression	AndExpression()
static void	disable_tracing()
static void	enable_tracing()
static Expression	EqualityExpression()
static Expression	Expression()
static ParseException	generateParseException()
static java.lang.Throwable	getError() Get the last error, if any, generated by a parse operation.
static Token	getNextToken()
static Token	getToken(int index)
static Expression	Identifier()
static Expression	IfStatement()
static Expression	Literal()
static Expression	MultiplicativeExpression()
static java.lang.String	Name()
static Expression	OrExpression()
static Expression	Parse()
static Expression	parse(java.lang.String expr) Parse an expression.
static Expression	parse(java.lang.String expr, boolean throwsException) Parse an expression.
static Predicate	predicate(java.lang.String expr) Parse an expression as a predicate.
static Expression	PrimaryExpression()
static java.lang.String	Quoted()
void	ReInit(ExpressionParserTokenManager tm)
static void	ReInit(java.io.InputStream stream)
static void	ReInit(java.io.Reader stream)
static Expression	RelationalExpression()
static Expression	UnaryExpression()
static Expression	UnaryExpressionNotPlusMinus()
static Expression	XorExpression()

Methods inherited from class java.lang.Object

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

Field Detail

token_source

public static ExpressionParserTokenManager token_source

token

public static Token token

jj_nt

public static Token jj_nt

Constructor Detail

ExpressionParser

public ExpressionParser(java.io.InputStream stream)

ExpressionParser

public ExpressionParser(java.io.Reader stream)

ExpressionParser

public ExpressionParser(ExpressionParserTokenManager tm)

Method Detail

parse

public static Expression parse(java.lang.String expr,
                               boolean throwsException)

Parse an expression.

Parameters:

expr - the expression text to parse

throwsException - true if this method should throw an exception if an error occurs or should fail quietly

Returns:

the parsed Expression, or null if the parse failed and throwsException is false

parse

public static Expression parse(java.lang.String expr)

Parse an expression. This method does not throw an exception if a parse error occurs. Use getError() to access any generated exceptions.

Parameters:

expr - the expression text to parse

Returns:

the parsed Expression, or null if the parse failed

predicate

public static Predicate predicate(java.lang.String expr)

Parse an expression as a predicate. This method does not throw an exception if a parse error occurs. Use getError() to access any generated exceptions.

Parameters:

expr - the expression text to parse

Returns:

the parsed Expression, or null if the parse failed

getError

public static java.lang.Throwable getError()

Get the last error, if any, generated by a parse operation.

Returns:

the last error generated during parsing

Name

public static final java.lang.String Name()
                                   throws ParseException

Throws:

ParseException

Quoted

public static final java.lang.String Quoted()
                                     throws ParseException

Throws:

ParseException

Parse

public static final Expression Parse()
                              throws ParseException

Throws:

ParseException

Expression

public static final Expression Expression()
                                   throws ParseException

Throws:

ParseException

OrExpression

public static final Expression OrExpression()
                                     throws ParseException

Throws:

ParseException

XorExpression

public static final Expression XorExpression()
                                      throws ParseException

Throws:

ParseException

AndExpression

public static final Expression AndExpression()
                                      throws ParseException

Throws:

ParseException

EqualityExpression

public static final Expression EqualityExpression()
                                           throws ParseException

Throws:

ParseException

RelationalExpression

public static final Expression RelationalExpression()
                                             throws ParseException

Throws:

ParseException

AdditiveExpression

public static final Expression AdditiveExpression()
                                           throws ParseException

Throws:

ParseException

MultiplicativeExpression

public static final Expression MultiplicativeExpression()
                                                 throws ParseException

Throws:

ParseException

UnaryExpression

public static final Expression UnaryExpression()
                                        throws ParseException

Throws:

ParseException

UnaryExpressionNotPlusMinus

public static final Expression UnaryExpressionNotPlusMinus()
                                                    throws ParseException

Throws:

ParseException

PrimaryExpression

public static final Expression PrimaryExpression()
                                          throws ParseException

Throws:

ParseException

Literal

public static final Expression Literal()
                                throws ParseException

Throws:

ParseException

Identifier

public static final Expression Identifier()
                                   throws ParseException

Throws:

ParseException

IfStatement

public static final Expression IfStatement()
                                    throws ParseException

Throws:

ParseException

ReInit

public static void ReInit(java.io.InputStream stream)

ReInit

public static void ReInit(java.io.Reader stream)

ReInit

public void ReInit(ExpressionParserTokenManager tm)

getNextToken

public static final Token getNextToken()

getToken

public static final Token getToken(int index)

generateParseException

public static ParseException generateParseException()

enable_tracing

public static final void enable_tracing()

disable_tracing

public static final void disable_tracing()