combine proposal

[James Clark <jjc@thaiopensource.com>]

Here's a proposal to deal with the combine issue.  My view is that
order-independence is highly desirable, but it's also essential to be able
to redefine things. My proposal:

1. Remove combine="replace".

2. Restrict combine="group" to cases where the order of the patterns being
combined is irrelevant (eg two <attribute> patterns).

3.  Allow a grammar-level <include> to contain one or more <define>
elements.  These <define> elements replace any definitions from that
include.

4.  We have an open issue on giving different names to the grammar-level
include and pattern-level include elements, which we might want to consider
at this time.  I would suggest leaving the pattern-level include as
"include", since it is close to a pure syntactic include, and renaming the
grammar-level include to "integrate".  Other suggestions for renaming are
welcome; I think this proposal really needs the grammar-level include and
pattern-level include to have different names.  Another possibility would be
"incorporate".

More details on 2.

Two input <define> elements are combined into a single output <define>
element as follows.  The input <define> elements will have been normalized
so that they contain exactly one child element before they are combined. It
is an error if neither input <define> element has  a combine attribute. It
is an error if both input <define> elements have a combine attribute, but
the values are different. The output <define> element has a combine
attribute with value equal to the combine attribute on one or both of the
input <define> elements.  If combine="group", then it is an error if
allowsChildren is true for both of the patterns in the define elements being
combined, where allowsChildren is defined as:

function boolean allowsChildren(pattern p) {
  switch (p) {
  case <oneOrMore> p1 </oneOrMore>:
     return allowsChildren(p1);
  case <interleave> p1 p2 </interleave>:
  case <group> p1 p2 </group>:
  case <choice> p1 p2 </choice>:
     return allowsChildren(p1) || allowsChildren(p2);
  case <anyString/>:
  case <element/>:
  case <data/>:
  case <string/>:
    return true;
  case <empty/>:
  case <notAllowed/>:
  case <attribute/>:
    return false:
  case <ref name=x/>:
    return allowsChildren(deref(x));
  }
}

(this assumes <notAllowed/> has been normalized out so that it occurs only
as a child of <define/>).

More details on 3.

<grammar>
<integrate href="X">
  <define name="Y">...</define>
</integrate>
...
</grammar>

is the same as

<grammar>
<integrate href="X"/>
<define name="Y">...</define>
...
</grammar>

except that any definitions of Y directly or indirectly inside X are ignored
(other than definitions inside nested grammars).  Note that a <define>
element inside the <integrate/> may have a combine attribute.   The same
rule applies in this case as well:

<integrate href="X">
  <define name="Y" combine="Z">...</define>
</integrate>
...

is the same as

<integrate href="X"/>
<define name="Y" combine="Z">...</define>
...

except that any definitions of Y directly or indirectly inside X are
ignored.

James