Package org.apache.commons.jexl3.internal

Class Debugger

  • All Implemented Interfaces:
    JexlInfo.Detail
    Direct Known Subclasses:
    TemplateDebugger
    public class Debugger
extends ParserVisitor
implements JexlInfo.Detail
    Helps pinpoint the cause of problems in expressions that fail during evaluation.

    It rebuilds an expression string from the tree and the start/end offsets of the cause in that string. This implies that exceptions during evaluation do always carry the node that's causing the error.

    Since:
    2.0

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.lang.String arrow
      Arrow symbol.
      protected java.lang.StringBuilder builder
      The builder to compose messages.
      protected JexlNode cause
      The cause of the issue to debug.
      protected int depth
      Accept() relative depth.
      protected int end
      The ending character location offset of the cause in the builder.
      protected int indent
      Perform indentation?.
      protected int indentLevel
      The indentation level.
      protected java.lang.String lf
      EOL.
      protected boolean outputPragmas
      Pragmas out.
      protected static java.util.regex.Pattern QUOTED_IDENTIFIER
      Checks identifiers that contain spaces or punctuation (but underscore, at-sign, sharp-sign and dollar).
      protected int start
      The starting character location offset of the cause in the builder.

    • Constructor Summary

      Constructors 
      Constructor Description
      Debugger()
      Creates a Debugger.

    • Field Detail

      • QUOTED_IDENTIFIER

        protected static final java.util.regex.Pattern QUOTED_IDENTIFIER
        Checks identifiers that contain spaces or punctuation (but underscore, at-sign, sharp-sign and dollar).

      • builder

        protected final java.lang.StringBuilder builder
        The builder to compose messages.

      • cause

        protected JexlNode cause
        The cause of the issue to debug.

      • start

        protected int start
        The starting character location offset of the cause in the builder.

      • end

        protected int end
        The ending character location offset of the cause in the builder.

      • indentLevel

        protected int indentLevel
        The indentation level.

      • indent

        protected int indent
        Perform indentation?.

      • depth

        protected int depth
        Accept() relative depth.

      • arrow

        protected java.lang.String arrow
        Arrow symbol.

      • lf

        protected java.lang.String lf
        EOL.

      • outputPragmas

        protected boolean outputPragmas
        Pragmas out.

    • Constructor Detail

      • Debugger

        public Debugger()
        Creates a Debugger.

    • Method Detail

      • isLambdaExpr

        private static boolean isLambdaExpr​(ASTJexlLambda lambda)

      • isStatement

        private static boolean isStatement​(JexlNode child)
        Tests whether a node is a statement (vs an expression).
        Parameters:
        child - the node
        Returns:
        true if node is a statement

      • semicolTerminated

        private static boolean semicolTerminated​(java.lang.CharSequence cs)
        Tests whether a script or expression ends with a semicolumn.
        Parameters:
        cs - the string
        Returns:
        true if a semicolumn is the last non-whitespace character

      • writePragmas

        private static void writePragmas​(java.lang.StringBuilder builder,
                                 java.util.Map<java.lang.String,​java.lang.Object> pragmas)
        Stringifies the pragmas.
        Parameters:
        builder - where to stringify
        pragmas - the pragmas, may be null

      • accept

        protected java.lang.Object accept​(JexlNode node,
                                  java.lang.Object data)
        Checks if a child node is the cause to debug & adds its representation to the rebuilt expression.
        Parameters:
        node - the child node
        data - visitor pattern argument
        Returns:
        visitor pattern value

      • acceptStatement

        protected java.lang.Object acceptStatement​(JexlNode child,
                                           java.lang.Object data)
        Adds a statement node to the rebuilt expression.
        Parameters:
        child - the child node
        data - visitor pattern argument
        Returns:
        visitor pattern value

      • additiveNode

        protected java.lang.Object additiveNode​(JexlNode node,
                                        java.lang.String op,
                                        java.lang.Object data)
        Rebuilds an additive expression.
        Parameters:
        node - the node
        op - the operator
        data - visitor pattern argument
        Returns:
        visitor pattern value

      • check

        protected java.lang.Object check​(JexlNode node,
                                 java.lang.String image,
                                 java.lang.Object data)
        Checks if a terminal node is the cause to debug & adds its representation to the rebuilt expression.
        Parameters:
        node - the child node
        image - the child node token image (optionally null)
        data - visitor pattern argument
        Returns:
        visitor pattern value

      • data

        public java.lang.String data​(JexlNode node)
        Rebuilds an expression from a JEXL node.
        Parameters:
        node - the node to rebuilt from
        Returns:
        the rebuilt expression
        Since:
        3.0

      • debug

        public boolean debug​(JexlExpression jscript)
        Position the debugger on the root of an expression.
        Parameters:
        jscript - the expression
        Returns:
        true if the expression was a Script instance, false otherwise

      • debug

        public boolean debug​(JexlNode node)
        Seeks the location of an error cause (a node) in an expression.
        Parameters:
        node - the node to debug
        Returns:
        true if the cause was located, false otherwise

      • debug

        public boolean debug​(JexlNode node,
                     boolean r)
        Seeks the location of an error cause (a node) in an expression.
        Parameters:
        node - the node to debug
        r - whether we should actively find the root node of the debugged node
        Returns:
        true if the cause was located, false otherwise

      • debug

        public boolean debug​(JexlScript jscript)
        Position the debugger on the root of a script.
        Parameters:
        jscript - the script
        Returns:
        true if the script was a Script instance, false otherwise

      • depth

        public Debugger depth​(int rdepth)
        Sets this debugger relative maximum depth.
        Parameters:
        rdepth - the maximum relative depth from the debugged node
        Returns:
        this debugger instance

      • end

        public int end()
        Description copied from interface: JexlInfo.Detail
        Gets the end column on the line that triggered the error
        Specified by:
        end in interface JexlInfo.Detail
        Returns:
        The end offset location of the cause in the expression

      • getFeatures

        protected JexlFeatures getFeatures​(JexlNode node)
        Tries (hard) to find the features used to parse a node.
        Parameters:
        node - the node
        Returns:
        the features or null

      • indentation

        public Debugger indentation​(int level)
        Sets the indentation level.
        Parameters:
        level - the number of spaces for indentation, none if less or equal to zero
        Returns:
        this debugger instance

      • infixChildren

        protected java.lang.Object infixChildren​(JexlNode node,
                                         java.lang.String infix,
                                         boolean paren,
                                         java.lang.Object data)
        Checks if the children of a node using infix notation is the cause to debug, adds their representation to the rebuilt expression.
        Parameters:
        node - the child node
        infix - the child node token
        paren - whether the child should be parenthesized
        data - visitor pattern argument
        Returns:
        visitor pattern value

      • lineFeed

        public Debugger lineFeed​(java.lang.String lf)
        Sets this debugger line-feed string.
        Parameters:
        lf - the string used to delineate lines (usually "\" or "")
        Returns:
        this debugger instance

      • needQuotes

        protected boolean needQuotes​(java.lang.String str)
        Checks whether an identifier should be quoted or not.
        Parameters:
        str - the identifier
        Returns:
        true if needing quotes, false otherwise

      • outputPragmas

        public Debugger outputPragmas​(boolean flag)
        Lets the debugger write out pragmas if any.
        Parameters:
        flag - turn on or off
        Returns:
        this debugger instance

      • postfixChild

        protected java.lang.Object postfixChild​(JexlNode node,
                                        java.lang.String prefix,
                                        java.lang.Object data)
        Postfix operators.
        Parameters:
        node - a postfix operator
        prefix - the postfix
        data - visitor pattern argument
        Returns:
        visitor pattern value

      • prefixChild

        protected java.lang.Object prefixChild​(JexlNode node,
                                       java.lang.String prefix,
                                       java.lang.Object data)
        Checks if the child of a node using prefix notation is the cause to debug, adds their representation to the rebuilt expression.
        Parameters:
        node - the node
        prefix - the node token
        data - visitor pattern argument
        Returns:
        visitor pattern value

      • acceptValue

        static void acceptValue​(java.lang.StringBuilder builder,
                        java.lang.Object value,
                        boolean quotedStrings)
        Accepts a (simple) value and appends its representation to the builder.
        Parameters:
        builder - where to append
        value - the value to append

      • reset

        public void reset()
        Resets this debugger state.

      • setArrowSymbol

        protected void setArrowSymbol​(JexlNode node)
        Sets the arrow style (fat or thin) depending on features.
        Parameters:
        node - the node to start seeking features from.

      • setIndentation

        public void setIndentation​(int level)
        Sets the indentation level.
        Parameters:
        level - the number of spaces for indentation, none if less or equal to zero

      • start

        public int start()
        Description copied from interface: JexlInfo.Detail
        Gets the start column on the line that triggered the error
        Specified by:
        start in interface JexlInfo.Detail
        Returns:
        The starting offset location of the cause in the expression

      • toString

        public java.lang.String toString()
        Description copied from interface: JexlInfo.Detail
        Gets the code that triggered the error
        Specified by:
        toString in interface JexlInfo.Detail
        Overrides:
        toString in class java.lang.Object
        Returns:
        The rebuilt expression

      • visit

        protected java.lang.Object visit​(ASTBlock node,
                                 java.lang.Object data)
        Specified by:
        visit in class ParserVisitor

      • acceptBlock

        private java.lang.Object acceptBlock​(JexlNode node,
                                     int begin,
                                     java.lang.Object data)

      • visit

        protected java.lang.Object visit​(ASTBreak node,
                                 java.lang.Object data)
        Specified by:
        visit in class ParserVisitor

      • visitCaseStatement

        private java.lang.Object visitCaseStatement​(ASTCaseStatement node,
                                            java.lang.Object data)

      • visitCaseExpression

        private java.lang.Object visitCaseExpression​(ASTCaseStatement node,
                                             java.lang.Object data)

      • visit

        protected java.lang.Object visit​(ASTVar node,
                                 java.lang.Object data)
        Specified by:
        visit in class ParserVisitor

      • visitParameter

        protected java.lang.String visitParameter​(java.lang.String p,
                                          java.lang.Object data)
        A pseudo visitor for parameters.
        Parameters:
        p - the parameter name
        data - the visitor argument
        Returns:
        the parameter name to use