2021 2022202320242025 the Contributors to the XProc 3.1 Standard Step Library specifications XProc/specification XProc Next XML Norman Walsh This specification describes the p:invisible-xml step for XProc 3.1: An XML Pipeline Language. This specification was published by the XProc Next Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups. If you wish to make comments regarding this document, please send them to xproc-dev@w3.org. (subscribe, archives). This draft is the “editor’s working draft” and may continue to evolve.

This specification describes the p:invisible-xml XProc step. A machine-readable description of this step may be found in steps.xpl. Familarity with the general nature of steps is assumed.

The p:invisible-xml step performs Invisible XML processing per . It transforms a non-XML input into XML by applying the specified Invisible XML grammar. If no grammar is provided on the grammar port, the grammar for Invisible XML is assumed. If an XML or text grammar is provided it must be an Invisible XML grammar. It is a dynamic error if the grammar provided is not a valid Invisible XML grammar. It is a dynamic error if more than one document appears on the grammar port. The source to be processed is usually text, but there’s nothing in principle that prevents an Invisible XML grammar from applying to an arbitrary sequence of characters. The result should be XML. It is implementation-defined if other result formats are possible. (An implementation might, for example, provide a way for the p:invisible-xml step to compile an Invisible XML grammar into some format that can be processed more efficiently.) The parameters are implementation-defined. An implementation might provide parameters to select among different ambiguous parses or choose alternate representations. If fail-on-error is true, the step will raise an error if the input cannot be parsed by the grammar. It is a dynamic error if the source document cannot be parsed by the provided grammar. If fail-on-error is false, no error will be raised. The Invisible XML specification provides a mechanism to identify failed parses in the output.

Several examples demonstrate features of the step.

In this first example, no grammar is provided, so the pipeline parses the Invisible XML grammar on the source port and returns its XML representation: <p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.1"> <p:output port="result"/> <p:ixml> <p:with-input port="grammar"><p:empty /></p:with-input> <p:with-input port="source"> <p:inline content-type="text/plain"> date: s?, day, s, month, (s, year)? . -s: -" "+ . day: digit, digit? . -digit: "0"; "1"; "2"; "3"; "4"; "5"; "6"; "7"; "8"; "9". month: "January"; "February"; "March"; "April"; "May"; "June"; "July"; "August"; "September"; "October"; "November"; "December". year: (digit, digit)?, digit, digit . </p:inline> </p:with-input> </p:ixml> </p:declare-step> This would produce an XML version of the grammar: <ixml> <rule name="date"> <alt> <option> <nonterminal name="s"/> </option> <nonterminal name="day"/> <nonterminal name="s"/> <nonterminal name="month"/> <option> <alts> <alt> <nonterminal name="s"/> <nonterminal name="year"/> </alt> </alts> </option> </alt> </rule> <!-- … remaining rules elided for brevity … --> </ixml>

If the grammar is provided on the grammar port, it can be used to parse input, the string “31 December 2021” in this case: <p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.1"> <p:output port="result"/> <p:ixml> <p:with-input port="grammar"> <p:inline content-type="text/plain"> date: s?, day, s, month, (s, year)? . -s: -" "+ . day: digit, digit? . -digit: "0"; "1"; "2"; "3"; "4"; "5"; "6"; "7"; "8"; "9". month: "January"; "February"; "March"; "April"; "May"; "June"; "July"; "August"; "September"; "October"; "November"; "December". year: (digit, digit)?, digit, digit . </p:inline> </p:with-input> <p:with-input port="source"> <p:inline content-type="text/plain">31 December 2021</p:inline> </p:with-input> </p:ixml> </p:declare-step> This would produce an XML version of the date: <date><day>31</day><month>December</month><year>2021</year></date>

If a parse fails, the implementation must indicate this, but it may also provide information about where the processing failed. <p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.1"> <p:output port="result"/> <p:ixml fail-on-error="false"> <p:with-input port="grammar"> <p:inline content-type="text/plain"> date: s?, day, s, month, (s, year)? . -s: -" "+ . day: digit, digit? . -digit: "0"; "1"; "2"; "3"; "4"; "5"; "6"; "7"; "8"; "9". month: "January"; "February"; "March"; "April"; "May"; "June"; "July"; "August"; "September"; "October"; "November"; "December". year: (digit, digit)?, digit, digit . </p:inline> </p:with-input> <p:with-input port="source"> <p:inline content-type="text/plain">31 Mumble 2021</p:inline> </p:with-input> </p:ixml> </p:declare-step> Here the output might be something like this: <error xmlns:ixml="http://invisiblexml.org/NS" xmlns:ex="http://example.com/NS" ixml:state="failed" ex:lastChar="4"> <parse> month -> • M a r c h month -> M • a r c h </parse> <parse> month -> • M a y month -> M • a y </parse> </error> In the case of failure, Invisible XML requires that the ixml:state attribute appear on the root element containing the token “failed”. It doesn’t constrain the implementation’s choice of the root element or the content of the document.

An ixml grammar may be ambiguous. In the grammar below, there are three different possible ways to parse the input. By default, one of them is returned. <p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.1"> <p:output port="result"/> <p:ixml> <p:with-input port="grammar"> <p:inline content-type="text/plain"> letters: X, (A; B; C) . A: digits . B: digits . C: digits . X: "a" . digits: ["0"-"9"]+ . </p:inline> </p:with-input> <p:with-input port="source"> <p:inline content-type="text/plain">a123</p:inline> </p:with-input> </p:ixml> </p:declare-step> This might return any one of these parses: <letters ixml:state="ambiguous" xmlns:ixml="http://invisiblexml.org/NS"><X>a</X><C><digits>123</digits></C></letters> or <letters ixml:state="ambiguous" xmlns:ixml="http://invisiblexml.org/NS"><X>a</X><A><digits>123</digits></A></letters> or <letters ixml:state="ambiguous" xmlns:ixml="http://invisiblexml.org/NS"><X>a</X><B><digits>123</digits></B></letters> All are equally correct.

An implementation might provide a parameter to allow the author to select a particular parse: <p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:ex="http://example.com/" version="3.1"> <p:output port="result"/> <p:ixml parameters="map{'ex:select':2}"> <p:with-input port="grammar"> <p:inline content-type="text/plain"> letters: X, (A; B; C) . A: digits . B: digits . C: digits . X: "a" . digits: ["0"-"9"]+ . </p:inline> </p:with-input> <p:with-input port="source"> <p:inline content-type="text/plain">a123</p:inline> </p:with-input> </p:ixml> </p:declare-step> This might return: <letters ixml:state="ambiguous"><X>a</X><A><digits>123</digits></A></letters>

Or a processor might provide a parameter to return all of the parses. <p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:ex="http://example.com/" version="3.1"> <p:output port="result"/> <p:ixml parameters="map{'ex:select':'all'}"> <p:with-input port="grammar"> <p:inline content-type="text/plain"> letters: X, (A; B; C) . A: digits . B: digits . C: digits . X: "a" . digits: ["0"-"9"]+ . </p:inline> </p:with-input> <p:with-input port="source"> <p:inline content-type="text/plain">a123</p:inline> </p:with-input> </p:ixml> </p:declare-step> This might return three documents: <letters ixml:state="ambiguous"><X>a</X><C><digits>123</digits></C></letters> <letters ixml:state="ambiguous"><X>a</X><B><digits>123</digits></B></letters> <letters ixml:state="ambiguous"><X>a</X><A><digits>123</digits></A></letters> As before, there is nothing standardized about the results in this case.

In earlier drafts of this specification, the p:invisible-xml step was named p:ixml. Changing the name of the step to p:invisible-xml brings the name into better alignment with the naming conventions used for most other XProc steps and aligns its name with the fn:invisible-xml() function in XPath 4.0. Implementors may wish to support both names for some period of time in order to avoid breaking changes in existing pipelines. Support for the alternative name p:ixml is implementation-defined.

No document properties are preserved.

This step can raise dynamic errors. A dynamic error is one which occurs while a pipeline is being evaluated. Examples of dynamic errors include references to URIs that cannot be resolved, steps which fail, and pipelines that exhaust the capacity of an implementation (such as memory or disk space). For a more complete discussion of dynamic errors, see . If a step fails due to a dynamic error, failure propagates upwards until either a p:try is encountered or the entire pipeline fails. In other words, outside of a p:try, step failure causes the entire pipeline to fail. The following errors can be raised by this step:

Conformant processors must implement all of the features described in this specification except those that are explicitly identified as optional. Some aspects of processor behavior are not completely specified; those features are either implementation-dependent or implementation-defined. An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed. An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.

The following features are implementation-defined:

This step has no implementation-dependent features.

Glossary needs to be generated This specification includes by reference a number of ancillary files. An XProc step library for the declared steps.