Where it’s practical to write a grammar that is unambiguous, that’s best. But it isn’t always practical. Sometimes it’s difficult, and sometimes it’s impossible. If the data is actually ambiguous, you may have to reflect that in your grammar.

Invisible XML doesn’t consider ambiguity an error, but it also doesn’t provide any mechanism for controlling it. All parses are considered equal and the processor’s only obligation is to provide one of them.

That may not suit your needs. CoffeeSacks provides a way to examine the alternatives and select one. You can supply a choose-alternative function in the parser options. This must be a function that takes a single argument, a list of elements, and returns an integer.

The function must return an integer between 0 and the number of alternatives provided. The number is the alternative selected. A value of 0 indicates that the function did not select an alternative. The implementation may then go on to try other methods for selecting an alternative.

This function always selects the first alternative:

  |<xsl:function name="f:first" as="xs:integer">
  |  <xsl:param name="alts" as="element()+"/>
  |  <xsl:sequence select="1"/>
  |</xsl:function>

You could pass it in parse options like this:

  |<xsl:variable name="parser"
  |              select="cs:make-parser($grammar,
  |                      map{'choose-alternative': f:first#1})"/>

Of course, unconditionally choosing the first option isn’t very interesting. To explore further, consider this simple, ambiguous grammar:

1 | number-list: (number, -#a)+, number? .
  |-number: hex | decimal .
  | hex: hex-digit+ .
  | decimal: decimal-digit+ .
5 |-hex-digit: ["0"-"9" | "a"-"f" | "A"-"F" ] .
  |-decimal-digit: ["0"-"9" ] .

If we parse the following input,

  |bad
  |cafe
  |42

We might get this result:

1 |<number-list xmlns:ixml="http://invisiblexml.org/NS" ixml:state="ambiguous">
  |  <hex>bad</hex>
  |  <hex>cafe</hex>
  |  <hex>42</hex>
5 |</number-list>

Of course, we might equally get this result:

1 |<number-list xmlns:ixml="http://invisiblexml.org/NS" ixml:state="ambiguous">
  |  <hex>bad</hex>
  |  <hex>cafe</hex>
  |  <decimal>42</decimal>
5 |</number-list>

The ambiguity here is between “decimal” and “hexidecimal”. Here’s a function that will always select the decimal alternative:

  |<xsl:function name="f:choose-alternative" as="xs:integer">
  |  <xsl:param name="alternatives" as="element()+"/>
  |  <xsl:sequence select="$alternatives[decimal]/@alternative"/>
  |</xsl:function>

In order to understand how this works, we need to look at what’s passed to the function. The function get’s an XML description of the current state of the parse, where each element in the list represents an alternative. For the grammar and input above, what’s passed to the function is a sequence of two elements:

 1 |(<number alternative="1" name="number" from="9" to="11" mark="-">
   |   <hex name="hex" from="9" to="11" mark="^">
   |     <a:nonterminal name="$2_hex-digit-plus" mark="-">…</a:nonterminal>
   |   </hex>
 5 | </number>,
   | <number alternative="2" name="number" from="9" to="11" mark="-">
   |   <decimal name="decimal" from="9" to="11" mark="^">
   |     <a:nonterminal name="$3_decimal-digit-plus" mark="-">…</a:nonterminal>
   |   </decimal>
10 | </number>)

Each alternative is identified with its number, name, the range of tokens it covers, and its mark. The content of each alternative is the sequence of literals and nonterminals that are the “right hand side” of this alternative. For example, the first alternative above includes:

 1 |<number alternative="1"                          ①
   |        name="number"                            ②
   |        from="9" to="11"                         ③
   |        mark="-">                                ④
 5 |   <hex name="hex"                                         ②
   |        from="9" to="11"                                   ③
   |        mark="^">                                          ④
   |      <a:nonterminal name="$2_hex-digit-plus"    ⑤
   |                     mark="-">                             ④
10 |        …                                        ⑥
   |      </a:nonterminal>
   |   </hex>
   |</number>

The sequence of nodes passed to the function are the alternatives, but that isn’t the whole story. The alternatives will include additional context if they are not the root of the result tree. For example, the whole tree associated with the first alternative in this case is:

 1 |<number-list xmlns:a="https://nineml.org/ns/describe-ambiguity"
   |             a:version="1.0"
   |             name="number-list"
   |             mark="^">
 5 |   <number name="number"/>
   |   <number name="number"/>
   |   <number alternative="1" name="number" from="9" to="11" mark="^">
   |      <hex name="hex" from="9" to="11" mark="^">
   |         <a:nonterminal name="$2_hex-digit-plus" mark="-">…</a:nonterminal>
10 |      </hex>
   |   </number>
   |</number-list>

The context includes all of the ancestors of the point where a choice must be made and the number of preceding siblings. Preceding siblings are identified simply by name.

This example doesn’t include any matched literal tokens, but if they are present, they are wrapped in a:literal elements.

Which aspects of the context (if any) are relevant is going to depend on your grammar and the input.

 1 |                   $$ ::= number-list
   |          number-list ::= $1_number-plus, $4_number-optionⁿ
   |               number ::= hex
   |               number ::= decimal
 5 |                  hex ::= $2_hex-digit-plus
   |              decimal ::= $3_decimal-digit-plus
   |            hex-digit ::= ['0'-'9'; 'a'-'f'; 'A'-'F']
   |        decimal-digit ::= ['0'-'9']
   |       $1_number-plus ::= number, #A
10 |       $1_number-plus ::= number, #A, $1_number-plus
   |    $2_hex-digit-plus ::= hex-digit
   |    $2_hex-digit-plus ::= hex-digit, $2_hex-digit-plus
   |$3_decimal-digit-plus ::= decimal-digit
   |$3_decimal-digit-plus ::= decimal-digit, $3_decimal-digit-plus
15 |    $4_number-optionⁿ ::= ε
   |    $4_number-optionⁿ ::= number