Package 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 | Description
    --- | --- | ---
    `static java.lang.String` | `ACTIVATION_CLASSES_PROPERTY` |

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

      `CLASSES_PROPERTY`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.lang.String` | `betweenExpression​(java.lang.String expr, double lo, double hi, boolean isLog, int npix)` | Returns a JEL expression that characterises a univariate range of values.
    `static java.lang.Class<?>` | `classForName​(java.lang.String cname)` | Returns the class with the given name, or null if it's not on the path.
    `static java.lang.String` | `combineSubsetsExpression​(TopcatModel tcModel, java.lang.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 java.lang.String[]` | `formatAxisRangeLimits​(double lo, double hi, boolean isLog, int npix)` | Formats a pair of values representing data bounds of a range along a graphics axis.
    `static java.util.List<java.lang.Class<?>>` | `getActivationStaticClasses()` | Returns the list of classes whose static methods will be mapped into the JEL evaluation namespace for activation purposes only.
    `static java.lang.String` | `getColumnId​(uk.ac.starlink.table.gui.StarTableColumn tcol)` | Returns the JEL $Identifier for a given column.
    `static java.lang.String` | `getDataExpression​(TopcatModel tcModel, GuiCoordContent content)` | Returns a single JEL-friendly expression which may be used to reference a GuiCoordContent, if possible.
    `static java.lang.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 java.lang.String` | `getSubsetExpression​(TopcatModel tcModel, RowSubset rset)` | Returns a JEL-friendly expression which may be used to reference a RowSubset.
    `static boolean` | `isColumnReferenced​(TopcatModel tcModel, int icol, java.lang.String expr)` | Indicates whether a given JEL expression makes direct or indirect reference to an existing column in a given table.
    `static boolean` | `isJelIdentifier​(java.lang.String label)` | Indicates whether a given string is a syntactically legal Java identifier.
    `static boolean` | `isSubsetReferenced​(TopcatModel tcModel, int rsetId, java.lang.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, java.lang.String rsetName, java.lang.String expr)` | Indicates whether a given JEL expression makes direct or indirect reference to a named subset in a given topcat model.
    `static java.lang.Class<?>` | `wrapPrimitiveClass​(java.lang.Class<?> prim)` | Turns a primitive class into the corresponding wrapper class.

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

      `checkExpressionType, compile, compile, compileQuantity, createDatalessRowReader, 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 java.lang.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 java.util.List<java.lang.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 java.lang.Class<?> wrapPrimitiveClass​(java.lang.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 java.lang.Class<?> classForName​(java.lang.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,
                                                   java.lang.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

    - #### isSubsetReferenced

          public static boolean isSubsetReferenced​(TopcatModel tcModel,
                                                   int rsetId,
                                                   java.lang.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

    - #### isSubsetReferenced

          public static boolean isSubsetReferenced​(TopcatModel tcModel,
                                                   java.lang.String rsetName,
                                                   java.lang.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 java.lang.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 java.lang.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

    - #### getSubsetExpression

          public static java.lang.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 java.lang.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​(java.lang.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 java.lang.String combineSubsetsExpression​(TopcatModel tcModel,
                                                                  java.lang.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

    - #### betweenExpression

          public static java.lang.String betweenExpression​(java.lang.String expr,
                                                           double lo,
                                                           double hi,
                                                           boolean isLog,
                                                           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
        `isLog` - true for logarithmic range, false for linear
        `npix` - approximate number of pixels covered by the range
      Returns:
        JEL expression with the meaning `lo<=expr<=hi`

    - #### formatAxisRangeLimits

          public static java.lang.String[] formatAxisRangeLimits​(double lo,
                                                                 double hi,
                                                                 boolean isLog,
                                                                 int npix)

      Formats a pair of values representing data bounds of a range along a graphics axis. nge. The number of pixels separating the values is used to determine the formatting precision.
      Parameters:
        `lo` - data lower bound
        `hi` - data upper bound
        `isLog` - true for logarithmic axis, false for linear
        `npix` - approximate number of pixels covered by the range
      Returns:
        2-element array giving (lower,upper) bounds formatted and ready for presentation to the user