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 Details

  • 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