API Reference


A Packrat / Parsing Grammar / TDPL parser for Common Lisp.


  • Generic-Function ESRAP-ERROR-POSITION (condition)
    Return the input position at which the parse failure represented by CONDITION occurred.
  • Generic-Function ESRAP-PARSE-ERROR-RESULT (condition)
    Return the result associated to the parse error represented by CONDITION.
  • Generic-Function ESRAP-PARSE-ERROR-CONTEXT (condition)
    Return the context result associated to the parse error represented by CONDITION.
  • Variable *ON-LEFT-RECURSION*
    This special variable controls Esrap's behavior with respect to allowing left recursion. When :ERROR, PARSE signals a LEFT-RECURSION error when it encounters a left recursive rule. Otherwise the rule is processed. Note: when processing left recursive rules, linear-time guarantees generally no longer hold.
    Signaled when an invalid expression is encountered.
  • Function INVALID-EXPRESSION-ERROR (expression)
    Signaled when an Esrap parse fails. Use ESRAP-ERROR-TEXT to obtain the string that was being parsed, and ESRAP-ERROR-POSITION the position at which the error occurred.
    This error is signaled when a parse attempt fails in a way that .
  • Method ESRAP-ERROR-POSITION ((condition esrap-parse-error))
  • Method ESRAP-PARSE-ERROR-CONTEXT ((condition esrap-parse-error))
  • Function ESRAP-PARSE-ERROR (text result)
    May be signaled when left recursion is detected during Esrap parsing. LEFT-RECURSION-NONTERMINAL names the symbol for which left recursion was detected, and LEFT-RECURSION-PATH lists nonterminals of which the left recursion cycle consists. Note: This error is only signaled if *ON-LEFT-RECURSION* is bound to :ERROR.
  • Function LEFT-RECURSION (text position nonterminal path-butlast)
    Signaled when an undefined rule is encountered.
  • Function EXPRESSION-START-TERMINALS (expression &key (when-rule-error-report nil when-rule-error-report-p))
    Return a list of terminals or tree of expressions with which a text parsable by EXPRESSION can start. A tree instead of a list is returned when EXPRESSION contains semantic predicates, NOT or !. Elements in the returned list or tree are * case (in)sensitive characters, character ranges, case (in)sensitive strings, function terminals * semantic predicates represented as (PREDICATE-NAME NESTED-ELEMENTS) where NESTED-ELEMENTS is the list of start terminals of the expression to which PREDICATE-NAME is applied. * NOT and ! expressions are represented as ({not,!} NESTED-ELEMENTS) where NESTED-ELEMENTS is the list of start terminals of the negated expression. * < and > expressions are represented as ({<,>} OFFSET NESTED-ELEMENTS) where OFFSET is a positive integer and NESTED-ELEMENTS is the list of start terminals of the expression that should match OFFSET characters backward/forward from the current position. The (outermost) list is sorted likes this: 1. string terminals 2. character terminals 3. the CHARACTER wildcard terminal 4. semantic predicates 5. everything else If supplied, WHEN-RULE-ERROR-REPORT restricts processing of nonterminals to rules whose :ERROR-REPORT option is compatible with the value of WHEN-RULE-ERROR-REPORT.
  • Function DESCRIBE-TERMINAL (terminal &optional (stream *standard-output*))
    Print a description of TERMINAL onto STREAM. In additional to actual terminals, TERMINAL can be of the forms (PREDICATE-NAME TERMINALS) ({not,!} TERMINALS) ({<,>} OFFSET TERMINALS) (i.e. as produced by EXPRESSION-START-TERMINALS).
  • Class RULE
  • Function RULE-DEPENDENCIES (rule)
    Returns the dependencies of the RULE: primary value is a list of defined nonterminal symbols, and secondary value is a list of undefined nonterminal symbols.
  • Function TEXT (&rest arguments)
    Arguments must be strings, or lists whose leaves are strings. Catenates all the strings in arguments into a single string.
  • Function PARSE (expression text &key (start 0) end junk-allowed raw)
    Parses TEXT using EXPRESSION from START to END. Incomplete parses, that is not consuming the entirety of TEXT, are allowed only if JUNK-ALLOWED is true. Returns three values: 1) A production, if the parse succeeded, NIL otherwise. 2) The position up to which TEXT has been consumed or NIL if the entirety of TEXT has been consumed. 3) If the parse succeeded, even if it did not consume any input, T is returned as a third value. The third return value is necessary to distinguish successful and failed parses for cases like (parse '(! #\a) "a" :junk-allowed t) (parse '(! #\a) "b" :junk-allowed t) in which the first two return values cannot indicate failures. RAW controls whether the parse result is interpreted and translated into the return values described above. If RAW is true, a parse result of type RESULT or ERROR-RESULT is returned as a single value. Note that the combination of arguments :junk-allowed t :raw t does not make sense since the JUNK-ALLOWED parameter is used when parse results are interpreted and translated into return values which does not happen when :raw t.
  • Macro DEFRULE (&whole form symbol expression &body options)
    Define SYMBOL as a nonterminal, using EXPRESSION as associated the parsing expression. Multiple OPTIONS specifying transforms are composed in the order of appearance: (:text t) (:function parse-integer) => (alexandria:compose #'parse-integer #'text) Following OPTIONS can be specified: * (:WHEN TEST) The rule is active only when TEST evaluates to true. This can be used to specify optional extensions to a grammar. This option can only be supplied once. * (:CONSTANT CONSTANT) No matter what input is consumed or what EXPRESSION produces, the production of the rule is always CONSTANT. * (:FUNCTION FUNCTION) If provided the production of the expression is transformed using FUNCTION. FUNCTION can be a function name or a lambda-expression. * (:IDENTITY BOOLEAN) If true, the production of expression is used as-is, as if (:FUNCTION IDENTITY) has been specified. If no production option is specified, this is the default. * (:TEXT BOOLEAN) If true, the production of expression is flattened and concatenated into a string as if by (:FUNCTION TEXT) has been specified. * (:LAMBDA LAMBDA-LIST &BODY BODY) If provided, same as using the corresponding lambda-expression with :FUNCTION. As an extension of the standard lambda list syntax, LAMBDA-LIST accepts the optional pseudo lambda-list keyword ESRAP:&BOUNDS, which (1) must appear after all standard lambda list keywords. (2) can be followed by one or two variables to which bounding indexes of the matching substring are bound. Therefore: LAMBDA-LIST ::= (STANDARD-LAMBDA-LIST-ELEMENTS [&BOUNDS START [END]]) * (:DESTRUCTURE DESTRUCTURING-LAMBDA-LIST &BODY BODY) If provided, same as using a lambda-expression that destructures its argument using DESTRUCTURING-BIND and the provided lambda-list with :FUNCTION. DESTRUCTURING-LAMBDA-LIST can use ESRAP:&BOUNDS in the same way as described for :LAMBDA. * (:AROUND ([&BOUNDS START [END]]) &BODY BODY) If provided, execute BODY around the construction of the production of the rule. BODY has to call ESRAP:CALL-TRANSFORM to trigger the computation of the production. Any transformation provided via :LAMBDA, :FUNCTION or :DESTRUCTURE is executed inside the call to ESRAP:CALL-TRANSFORM. As a result, modification to the dynamic state are visible within the transform. ESRAP:&BOUNDS can be used in the same way as described for :LAMBDA and :DESTRUCTURE. This option can be used to safely track nesting depth, manage symbol tables or for other stack-like operations. * (:ERROR-REPORT ( T | NIL | :CONTEXT | :DETAIL )) Defaults to T if not provided. Controls whether and how the rule is used in parse error reports: * T The rule is used in parse error reports without restriction (i.e. when describing the context of a failure as well as listing failed rules and expected inputs). * NIL The rule is not used in parse error reports in any capacity. In particular, inputs expected by the rule are not mentioned. This value is useful for things like whitespace rules since something like "expected space, tab or newline", even if it would have allowed the parser to continue for one character, is rarely helpful. * :CONTEXT The rule is used in the "context" part of parse error reports. The rule is neither mentioned in the list of failed rules nor are inputs expected by it. * :DETAIL The rule is not used in the "context" part of parse error reports, but can appear in the list of failed rules. Inputs expected by the rule are mentioned as well.
  • Function ADD-RULE (symbol rule)
    Associates RULE with the nonterminal SYMBOL. Signals an error if the rule is already associated with a nonterminal. If the symbol is already associated with a rule, the old rule is removed first.
  • Function FIND-RULE (symbol)
    Returns rule designated by SYMBOL, if any. Symbol must be a nonterminal symbol.
  • Function REMOVE-RULE (symbol &key force)
    Makes the nonterminal SYMBOL undefined. If the nonterminal is defined an already referred to by other rules, an error is signalled unless :FORCE is true.
  • Function TRACE-RULE (symbol &key recursive break condition)
    Turn on tracing of nonterminal SYMBOL. If RECURSIVE is true, turn on tracing for the whole grammar rooted at SYMBOL. If BREAK is true, break is entered when the rule is invoked. If supplied, CONDITION has to be a function whose lambda-list is compatible to (symbol text position end). This function is called to determine whether trace actions should be executed for the traced rule. SYMBOL is the name of the rule being executed. TEXT is the whole text being parsed. POSITION is the position within TEXT at which the rule is executed. END is the end position of the portion of TEXT being parsed.
  • Function UNTRACE-RULE (symbol &key recursive break condition)
    Turn off tracing of nonterminal SYMBOL. If RECURSIVE is true, untraces the whole grammar rooted at SYMBOL. BREAK and CONDITION are ignored, and are provided only for symmetry with TRACE-RULE.
  • Function RULE-EXPRESSION (rule)
    Return the parsing expression associated with the RULE.
  • Function (setf RULE-EXPRESSION) (expression rule)
    Modify RULE to use EXPRESSION as the parsing expression. The rule must be detached beforehand.
  • Function CHANGE-RULE (symbol expression)
    Modifies the nonterminal SYMBOL to use EXPRESSION instead. Temporarily removes the rule while it is being modified.
  • Function DESCRIBE-GRAMMAR (symbol &optional (stream *standard-output*))
    Prints the grammar tree rooted at nonterminal SYMBOL to STREAM for human inspection.

Also exports