@qt4cg statuses

Close #2460

This PR harmonizes the functions fn:unparsed-text, fn:unparsed-text-lines, file:read-text, and file:read-text-lines with respect to handling non-permitted characters. Each function has an options parameter and that parameter may contain a fallback function to remap non-permitted characters.

This leaves unresolved the question of what to do about permitted characters not allowed in XML, but that’s orthogonal. Strings containing such characters might arise from any of these functions, but equally, might arise from other operations.

The specification of format-number() says:

If there are several such values that are numerically equal to the mantissa (bearing in mind that if the mantissa is an xs:double or xs:float, the comparison will be done by converting the decimal value back to an xs:double or xs:float), the one that is chosen should be one with the smallest possible number of digits not counting leading or trailing zeroes (whether significant or insignificant).

The parenthetical "bearing in mind" note needs updating, because comparison of a decimal to a double is no longer done by converting the decimal back to a double.

Background: XSLT test case format-number-044a, which I have extricated from the composite test format-number-044, formats the x:double obtained as 1E100 div 3. This is giving me a result with sixteen 3s on Java, fifteen 3s on C#. I am trying to work out which is correct, or at any rate which one should be produced according to the above rules.

The error description for FODC0006 can be raised by fn:parse-xml and fn:parse-xml-fragment. It is currently described as

err:FODC0006, String passed to fn:parse-xml is not a well-formed XML document.
Raised by [fn:parse-xml](https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-parse-xml)
if the supplied string is not a well-formed and namespace-well-formed XML document;
or if DTD validation is requested and the document is not valid against its DTD.

I propose to alter the description to

err:FODC0006, String cannot be parsed as XML.
Raised by [fn:parse-xml](https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-parse-xml) or [fn:parse-xml-fragment](https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-parse-xml-fragment)
if the supplied string is not a well-formed and namespace-well-formed XML document;
or if DTD validation is requested and the document is not valid against its DTD;
or if it was passed to parse-xml-fragment and is not a well-formed external general parsed entity, if it contains entity references other than references to predefined entities, or if a document that incorporates this well-formed parsed entity would not be namespace-well-formed.

The description of fn:path() says Returns a path expression that can be used to select the supplied node relative to the root of its containing document, but gives no guidance as to how exactly to use such a path expression to select a node; one can use eval(), or could write an invisible XML grammar, but that'd like saying “if and do-while can be used to write a program to solve chess problems”.

Easiest fix - remove the text saying people can use the result of path() to select nodes, since they can’t.

Slightly harder - add a path-to-node($root, $path) as node()? function.

I’d prefer the function—unless there is one and i missed it, and then i’d prefer the obvious editorial change :-) —but reducing the reader’s expectations would be OK too.

With keyword arguments being available, it would make sense to have a map:apply($function, $map), in which keys in the map are mapped to argument names of the function.

Admittedly since fn:apply() takes an array and is not called array:apply(), maybe an optional 3rd argument to fn:apply() would work better, with the same rules as for static function application.

I would like to question the decision to allow function calls on sequences.

While I favored the change in the past, repeated user feedback indicates that the new behavior is confusing and complicates debugging. First, it legalizes cryptic code like ()(). Second, seemingly simple function calls like $add(1, 2) return an empty sequence if $add turns out to be empty.

I believe we should make type safety and readability a priority over convenience. If a short syntax is needed, one can still write $add ! .(1, 2).

Related: #2219 (can be closed if we revert dynamic function calls).

Support for unparsed entities and notations is something of a minority interest, but recent correspondence with a Saxon user reminds me that there are applications that depend on them quite heavily. There is limited support for them in the data model and in XSLT, but none in XPath or XQuery.

There is no logical reason for the two functions unparsed-entity-uri() and unparsed-entity-public-id() to be XSLT-only, other than to save XQuery implementors the trouble of implementing them.

At the same time, the functions are incomplete and inadequate. For example, there is no way of obtaining a complete list of declared entities, and there is no way of getting information about the notations that they refer to.

Many XML parsers do not expose information about entities and notations, so anything we define should be capable of returning a result that indicates "information not available for this document (or for this implementation)".

I propose a new function unparsed-entities($doc) which returns a map along the lines:

{ "entities": {
     "e-name-1": {
         "system-id": ....
         "public-id": ....
         "notation": ....
     }, ....
  },
 "notations":{
    "n-name-1": "system-id", ...
  }
} 

and which is allowed to return an empty sequence if information about unparsed entities is not available (making it possible to provide a trivial fallback implementation).

file:read-text() should be aligned with fn:unparsed-text() to remove the restriction regarding valid XML characters.

Incidentally, bin:decode-string() has never had such a restriction even in the EXPath 1.0 version.

Are we applying XML 1.0 rules or XML 1.1 rules? Does the user get to decide? How?

I can currently write $map/jnode("key") or $map/get("key"), and both have the same meaning.

Both imply the child axis: I can also write $map/child::jnode("key") or $map/child::get("key")

There are differences:

• jnode also allows a content type to be specified
• get allows the key to be an arbitrary expression, while jnode requires a Constant
• jnode allows an NCName-valued key to be written without quotes
• get allows multiple keys to be selected
• jnode allows all keys to be selected
• get also works with XNodes

I propose that we unify these constructs.

To do this we distinguish jnode as an item type from jnode as a selector.

When used as a selector, the first argument of jnode should accept a KeySpecifier rather than a Constant. KeySpecifier is the subset of Expression that we allow after the lookup operator ?. (We should extend it to generalise Literal to Constant) A KeySpecifier allows an arbitrary expression in parentheses; we can debate what focus should be used to evaluate it.

This means, for example, that $array/get($i) becomes $array/jnode($i)

We could apply the same treatment to element() and attribute(), allowing $doc//element($N).

The second optional argument of jnode(), element(), and attribute() is unaffected.