# 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
Description
`static final String`
`ACTIVATION_CLASSES_PROPERTY`

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

`CLASSES_PROPERTY`

## Method Summary

Modifier and Type
Method
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, String label)`
Converts a data label to a JEL-friendly expression for a table quantity.
`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[]`
`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 Object

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

## Field Details

### ACTIVATION_CLASSES_PROPERTY

public static final String ACTIVATION_CLASSES_PROPERTY

See Also:
  - Constant Field Values

## Method Details

### 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`