Please document `fontoxpath:evaluate`

[rrthomas]

I just found this by accident, and I don't fully understand how it works from looking at the tests. As I wrote my own eval function, I'm quite interested in using fontoxpath:evaluate instead.

[DrRataplan]

Hey there!

The undocumentedness of that function is because we do not really regard as part of the public stable API. This is one of the (externally reachable) APIs that is prone to breaking every other release. Without notice.

That being said, the implementation lives here: https://github.com/FontoXML/fontoxpath/blob/master/src/expressions/functions/builtInFunctions_fontoxpath.ts#L177

It accepts a string or an element (the query or an XQueryX document representing a query) and a map for variables. That map has one special variable: ., which will be the context of the query.

Example use: fontoxpath:evaluate('name(.)', map{'.': //tips}), which executes fn:name() on the element found by //tips. Another example: fontoxpath:evaluate('$x || "ABC"', map{'x': 'XXX'}), which returns XXXABC.

Again, because we do not regard this as public API, your code might break when FontoXPath is updated. The changes are usually small though, it's more about changing scoping of namespace resolving, how variables are passed, that sort of thing.

I hope this clarifies the issue, please reach out if we can help out more!

Kind regards,

Martin Middel

[rrthomas]

Thanks very much. I note that most XQuery implementations seem to have some sort of eval function, so just maybe it might be time to think about whether you could commit to an API? :) At any rate, I will evaluate it (pun intended) myself when I get a chance and see whether it's easier to use it directly, wrap it (and make my own API promises externally) or whatever.