uk.ac.starlink.topcat

Class TopcatJELUtils

java.lang.Object

uk.ac.starlink.ttools.jel.JELUtils

uk.ac.starlink.topcat.TopcatJELUtils

public class TopcatJELUtils
extends uk.ac.starlink.ttools.jel.JELUtils

This class provides some utility methods for use with the JEL expression compiler.

Author:

Mark Taylor (Starlink)

Field Summary

Fields

Modifier and Type	Field and Description
static String	ACTIVATION_CLASSES_PROPERTY

Fields inherited from class uk.ac.starlink.ttools.jel.JELUtils

CLASSES_PROPERTY

Method Summary

Modifier and Type	Method and Description
static String	betweenExpression(String expr, double lo, double hi, uk.ac.starlink.ttools.plot2.Scale scale, int npix) Returns a JEL expression that characterises a univariate range of values.
static Class<?>	classForName(String cname) Returns the class with the given name, or null if it's not on the path.
static String	combineSubsetsExpression(TopcatModel tcModel, String expr, RowSubset[] rowSubsets) Returns a JEL expression that represents the union of a given array of subsets ANDed with a given JEL expression.
static List<Class<?>>	getActivationStaticClasses() Returns the list of classes whose static methods will be mapped into the JEL evaluation namespace for activation purposes only.
static String	getAngleExpression(TopcatModel tcModel, ColumnSelector angleSelector, AngleColumnConverter.Unit unit) Returns a JEL expression for the value in a given angular unit represented by a column selector that reads angular data.
static String	getColumnId(uk.ac.starlink.table.gui.StarTableColumn tcol) Returns the JEL $Identifier for a given column.
static String	getContentIdentifier(TopcatModel tcModel, String expr) Returns a string characterising the content of the expression in the context of a given topcat model.
static String	getDataExpression(TopcatModel tcModel, ColumnSelector colSelector) Returns a JEL expression for the value given by a column selector.
static String	getDataExpression(TopcatModel tcModel, GuiCoordContent content) Returns a single JEL-friendly expression which may be used to reference a GuiCoordContent, if possible.
static String	getDataExpression(TopcatModel tcModel, String label) Converts a data label to a JEL-friendly expression for a table quantity.
static String[]	getDataExpressions(TopcatModel tcModel, GuiCoordContent content) Returns an array of JEL-friendly expressions which may be used to reference a GuiCoordContent.
static gnu.jel.Library	getLibrary(uk.ac.starlink.ttools.jel.JELRowReader rowReader, boolean activation) Returns a JEL Library suitable for expression evaluation.
static Set<Integer>	getReferencedColumns(TopcatModel tcModel, String expr) Returns a list of the column indices that are directly or indirectly referenced by a given JEL expression.
static Set<uk.ac.starlink.ttools.jel.Constant<?>>	getReferencedConstants(TopcatModel tcModel, String expr) Returns a set of the Constant values that are directly or indirectly referenced by a given JEL expression.
static Set<Integer>	getReferencedSubsets(TopcatModel tcModel, String expr) Returns a list of subset IDs that are directly or indirectly referenced by a given JEL expression.
static String	getSubsetExpression(TopcatModel tcModel, RowSubset rset) Returns a JEL-friendly expression which may be used to reference a RowSubset.
static String	groupForMultiply(String expr) Provides grouping as required for a given JEL expression.
static boolean	isColumnReferenced(TopcatModel tcModel, int icol, String expr) Indicates whether a given JEL expression makes direct or indirect reference to an existing column in a given table.
static boolean	isJelIdentifier(String label) Indicates whether a given string is a syntactically legal Java identifier.
static boolean	isSubsetReferenced(TopcatModel tcModel, int rsetId, String expr) Indicates whether a given JEL expression makes direct or indirect reference to an existing subset in a given topcat model.
static boolean	isSubsetReferenced(TopcatModel tcModel, String rsetName, String expr) Indicates whether a given JEL expression makes direct or indirect reference to a named subset in a given topcat model.
static String	multiplyExpression(String expr, double factor) Returns a JEL expression multiplied by a factor.
static Class<?>	wrapPrimitiveClass(Class<?> prim) Turns a primitive class into the corresponding wrapper class.

Methods inherited from class uk.ac.starlink.ttools.jel.JELUtils

checkExpressionType, compile, compile, compileExpressions, compileQuantity, compiler, createDatalessRowReader, createLibrary, getExpressionType, getLibrary, getStaticClasses, getWrapperType, toIOException

Methods inherited from class java.lang.Object

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

Field Detail

ACTIVATION_CLASSES_PROPERTY

public static final String ACTIVATION_CLASSES_PROPERTY

See Also:

Constant Field Values

Method Detail

getLibrary

public static gnu.jel.Library getLibrary(uk.ac.starlink.ttools.jel.JELRowReader rowReader,
                                         boolean activation)

Returns a JEL Library suitable for expression evaluation.

Parameters:

rowReader - object which can read rows from the table to be used for expression evaluation

activation - true iff the result is to include classes used only for activation (e.g. write to System.out, pop up viewers) as well as classes with methods for calculations

Returns:

a JEL library

getActivationStaticClasses

public static List<Class<?>> getActivationStaticClasses()

Returns the list of classes whose static methods will be mapped into the JEL evaluation namespace for activation purposes only. This may be modified.

Returns:

list of activation classes with static methods

wrapPrimitiveClass

public static Class<?> wrapPrimitiveClass(Class<?> prim)

Turns a primitive class into the corresponding wrapper class.

Parameters:

prim - primitive class

Returns:

the corresponding non-primitive wrapper class

classForName

public static Class<?> classForName(String cname)

Returns the class with the given name, or null if it's not on the path.

Parameters:

cname - class name

Returns:

class or null

isColumnReferenced

public static boolean isColumnReferenced(TopcatModel tcModel,
                                         int icol,
                                         String expr)

Indicates whether a given JEL expression makes direct or indirect reference to an existing column in a given table. If the expression cannot be compiled, false is returned

Parameters:

tcModel - topcat model

icol - column index to test

expr - JEL expression

Returns:

true iff expr references the column with index icol

getReferencedColumns

public static Set<Integer> getReferencedColumns(TopcatModel tcModel,
                                                String expr)

Returns a list of the column indices that are directly or indirectly referenced by a given JEL expression. If the expression cannot be compiled, an empty list is returned.

Parameters:

tcModel - topcat model

expr - JEL expression

Returns:

set of column indices referenced

isSubsetReferenced

public static boolean isSubsetReferenced(TopcatModel tcModel,
                                         int rsetId,
                                         String expr)

Indicates whether a given JEL expression makes direct or indirect reference to an existing subset in a given topcat model. If the expression cannot be compiled, false is returned.

Parameters:

tcModel - topcat model

rsetId - ID of row subset to test

expr - JEL expression

Returns:

true iff expr references the subset with index rsetId

getReferencedSubsets

public static Set<Integer> getReferencedSubsets(TopcatModel tcModel,
                                                String expr)

Returns a list of subset IDs that are directly or indirectly referenced by a given JEL expression. If the expression cannot be compiled, an empty list is returned.

Parameters:

tcModel - topcat model

expr - JEL expression

Returns:

set of subset IDs referenced

getReferencedConstants

public static Set<uk.ac.starlink.ttools.jel.Constant<?>> getReferencedConstants(TopcatModel tcModel,
                                                                                String expr)

Returns a set of the Constant values that are directly or indirectly referenced by a given JEL expression. If the expression cannot be compiled, an empty set is returned.

Parameters:

tcModel - topcat model

expr - JEL expression

Returns:

set of Constant instances referenced

getContentIdentifier

public static String getContentIdentifier(TopcatModel tcModel,
                                          String expr)

Returns a string characterising the content of the expression in the context of a given topcat model.

The returned string is likely to differ if the expression itself changes, or if the definitions of any expressions it depends on (synthetic columns or row subsets) change, or if any constants it depends on change. This assessment is done recursively.

Collisions may be possible, but I think they're unlikely.

Parameters:

tcModel - topcat model

expr - expression to evaluate

Returns:

opaque string that can be used to determine whether the result of evaluating the expression will change

isSubsetReferenced

public static boolean isSubsetReferenced(TopcatModel tcModel,
                                         String rsetName,
                                         String expr)

Indicates whether a given JEL expression makes direct or indirect reference to a named subset in a given topcat model. If the expression cannot be compiled, or no subset with the given name exists, false is returned.

Parameters:

tcModel - topcat model

rsetName - name of row subset to test

expr - JEL expression

Returns:

true iff expr references the subset with name rsetName

getDataExpression

public static String getDataExpression(TopcatModel tcModel,
                                       ColumnSelector colSelector)

Returns a JEL expression for the value given by a column selector. Converters are accounted for.

Parameters:

tcModel - topcat model

colSelector - column selector

Returns:

JEL expression

getAngleExpression

public static String getAngleExpression(TopcatModel tcModel,
                                        ColumnSelector angleSelector,
                                        AngleColumnConverter.Unit unit)

Returns a JEL expression for the value in a given angular unit represented by a column selector that reads angular data. The selector's ColumnConverter should be an AngleColumnConverter. If it's not, a strong warning will be issued through the logging system.

Parameters:

tcModel - topcat model

angleSelector - selector for an angular quantity

unit - required angular unit

Returns:

JEL expression for selected value, in requested unit

getDataExpression

public static String getDataExpression(TopcatModel tcModel,
                                       GuiCoordContent content)

Returns a single JEL-friendly expression which may be used to reference a GuiCoordContent, if possible. This will only succeed (return a non-null value) if the supplied GuiCoordContent corresponds to a single user-supplied label.

Parameters:

tcModel - topcat model

content - user specification for a plotted quantity

Returns:

JEL-safe expression for referencing the quantity, or null

getDataExpressions

public static String[] getDataExpressions(TopcatModel tcModel,
                                          GuiCoordContent content)

Returns an array of JEL-friendly expressions which may be used to reference a GuiCoordContent.

Parameters:

tcModel - topcat model

content - user specification for a plotted quantity

Returns:

array of JEL-safe expressions, one for each user-supplied label in the content

getDataExpression

public static String getDataExpression(TopcatModel tcModel,
                                       String label)

Converts a data label to a JEL-friendly expression for a table quantity. The label will typically be a string that the user has selected or entered to identify a quantity to be plotted.

Parameters:

tcModel - topcat model

label - textual identifier for data

getSubsetExpression

public static String getSubsetExpression(TopcatModel tcModel,
                                         RowSubset rset)

Returns a JEL-friendly expression which may be used to reference a RowSubset.

Parameters:

tcModel - topcat model

rset - row subset

Returns:

JEL-safe expression for subset

getColumnId

public static String getColumnId(uk.ac.starlink.table.gui.StarTableColumn tcol)

Returns the JEL $Identifier for a given column.

Parameters:

tcol - table column from data model

Returns:

"$nn" expression referencing column

isJelIdentifier

public static boolean isJelIdentifier(String label)

Indicates whether a given string is a syntactically legal Java identifier. It has to have the right form and not be a reserved word.

Parameters:

label - text to test

Returns:

true iff it can be used as an identifier in JEL expressions

combineSubsetsExpression

public static String combineSubsetsExpression(TopcatModel tcModel,
                                              String expr,
                                              RowSubset[] rowSubsets)

Returns a JEL expression that represents the union of a given array of subsets ANDed with a given JEL expression.

Parameters:

tcModel - topcat model

expr - expression to AND with

rowSubsets - array of zero or more subsets composing union; if none are provided, ALL is assumed

Returns:

combined expression

groupForMultiply

public static String groupForMultiply(String expr)

Provides grouping as required for a given JEL expression. The resulting string can have multiplication-like operations applied, for instance just adding "*x". Basically, it checks if the input has embedded "+" or "-" signs and if so wraps it in parentheses.

This is not bulletproof, but will generally do the right thing.

Parameters:

expr - input JEL expression

Returns:

equivalent expression suitable for multiplication etc, best efforts

multiplyExpression

public static String multiplyExpression(String expr,
                                        double factor)

Returns a JEL expression multiplied by a factor.

Parameters:

expr - base JEL expression

factor - factor to multiply by

Returns:

JEL expression representing expr * factor

betweenExpression

public static String betweenExpression(String expr,
                                       double lo,
                                       double hi,
                                       uk.ac.starlink.ttools.plot2.Scale scale,
                                       int npix)

Returns a JEL expression that characterises a univariate range of values.

Parameters:

expr - JEL expression whose value is to be constrained

lo - lowest permissible bound for expr

hi - highest permissible bound for expr

scale - scaling

npix - approximate number of pixels covered by the range

Returns:

JEL expression with the meaning lo<=expr<=hi