Provide an XML version of the stack trace

[rhdunn]

While the string version of fn:stack-trace() is useful for debugging and including in log messages, being able to process that (from an XML representation) is also useful.

Use Cases

1. providing extended functionality, like implementing a current-function-name() helper function -- e.g. fn:stack-trace("json")[1]?function-name;
2. customizing the format of the stack trace (e.g. standardizing it across different implementations);
3. using the information in libraries/IDEs/editors that call the queries -- e.g. by returning the XML and processing it in the library/IDE/editor, such as mapping the data to stack frames in the IDE/editor. Note: This is what I'm doing in my IntelliJ plugin with the MarkLogic stack XML to process query exceptions and the stack when debugging a query.

fn:stack-trace

fn:stack-trace($format as enum("text", "xml", "json") := "text") as item()

Like the current specification version of this function (with the same default semantics), but also supports XML and JSON formats. The "text" format returns an instance of xs:string in an implementation-defined format, the "xml" format returns an instance of element(fn:stack-trace), and the "json" format returns an instance of array(fn:stack-frame).

Here, fn:stack-frame is defined as:

declare type fn:stack-frame as record(
    uri: xs:string,
    function-name: xs:QName?,
    line-number: xs:integer?,
    column-number: xs:integer?,
    *
);

The XML version has the same information as elements in the fn: namespace (e.g. fn:uri).

fn:format-stack-trace

fn:format-stack-trace($stack as item(),
                      $format as enum("text", "xml", "json") := "text") as item()

If $stack is an instance of element(fn:stack-trace), it is converted into the desired output format. (If the output format is "xml", no processing is performed.)

If $stack is an instance of array(fn:stack-frame), it is converted into the desired output format. (If the output format is "json", no processing is performed.)

Otherwise, an err:XPTY0004 error is raised.

fn:parse-stack-trace

fn:parse-stack-trace($stack as xs:string,
                     $format as enum("xml", "json")) as item()

This function takes a stack trace in the implementation-defined format and parses it to XML or JSON. The "xml" format returns an instance of element(fn:stack-trace), and the "json" format returns an instance of array(fn:stack-frame).

If $stack is not in the correct format, an error (error code TBD) is raised.

Note: This could be useful when processing log messages or similar output.

[ChristianGruen]

I’m still hesitant if we should include this function to the standard. I clearly see reasons for having a stack trace function, but we may (at this stage) need to consider numerous implementation-specific questions:

Code may be rewritten a lot by a processor before it’s eventually executed, and it’s often difficult to preserve the original location of a former expression (in particular, the column number), even if we ignore function inlining. An arbitrary example:

(: original query :)
some $s in
  (1, 2, 3)
satisfies
  $s > 1

(: rewritten query :)
((1 to 3) ! (. >= 2)) = true()

Rewritings could generally be suppressed if a stack-trace call is found in a sub expression, but this would change the way how a query is executed, and may lead to heisenbugs (and I assume the main reason for using this function is for debugging purposes).

[ChristianGruen]

I would tend to close this issue (and keep #689 open). I suppose we’d need to introduce much stricter optimization rules in the specification to achieve reasonable results across multiple processors.

[ndw]

The CG agreed to close this issue without action at meeting 065