Balisage Paper: Accumulators in XSLT and XSpec

Start tags of either <remark> or any element with condition="future". When you see such start tags, an internal-only region begins or deepens.

End tags of either <remark> or any element with condition="future". When you see such end tags, an internal-only region ends or becomes shallower. At this point, you have already seen all the element's descendants, an observation whose relevance will appear soon.

The internal-depth accumulator records the depth of internal-only regions. For instance, this accumulator associates the integer value 2 with the text node having content "For next year, maybe", and the nonzero value indicates that this text node is internal-only. The text node having content "Additional content" is associated with the value 1, which is also nonzero and indicates internal-only status. By contrast, the text node having content "Sample external content" is associated with the value 0.

<xsl:accumulator name="internal-depth" as="xs:integer" initial-value="0">
   <xsl:accumulator-rule phase="start"
      match="remark | *[@condition='future']">
      <!-- Start: Increment depth -->
      <xsl:sequence select="$value + 1"/>
   </xsl:accumulator-rule>
   <xsl:accumulator-rule phase="end"
      match="remark | *[@condition='future']">
      <!-- End: Decrement depth -->
      <xsl:sequence select="$value - 1"/>
   </xsl:accumulator-rule>
</xsl:accumulator>

The internal-elem accumulator behaves like a stack, recording sequences of internal-only element names (with the most recent at the beginning). For instance, this accumulator associates the sequence ('remark', 'section') with the text node having content "For next year, maybe", and the nonempty value indicates that this text node is internal-only.

Recording element names might seem like overkill, but it depends on the situation. The additional information beyond depth could be helpful for debugging, testing, or hypothetical downstream processing that depends on the specific reason why a node is internal-only.

    <xsl:accumulator name="internal-elem" as="xs:string*"
        initial-value="()">
        <xsl:accumulator-rule phase="start"
            match="remark | *[@condition='future']">
            <!-- Start: Push element name on head of stack -->
            <xsl:sequence select="(name(.), $value)"/>
        </xsl:accumulator-rule>
        <xsl:accumulator-rule phase="end"
            match="remark | *[@condition='future']">
            <!-- End: Pop first item from stack -->
            <xsl:sequence select="tail($value)"/>
        </xsl:accumulator-rule>
    </xsl:accumulator>

/section/remark/accumulator-before('internal-depth') returns 1 because the phase="start" rule has just incremented the accumulator value.

/section/remark/accumulator-after('internal-depth') returns 0 because the phase="end" rule has just decremented the accumulator value.

Both functions return the same value if the context node is /section/para. Neither this element nor its descendants match any accumulator rule in the 'internal-depth' accumulator declaration. As a result, inertia preserves the accumulator value while the processor visits this element, its descendants, and this element again.

Both functions return the same value if the context node is a text node. A text node has no descendants, and text nodes do not match any accumulator rule in the 'internal-depth' accumulator declaration. Therefore, inertia preserves the accumulator value while the processor visits a given text node twice.

Inspired by an accumulator's counting behavior, you might try to make an accumulator count how many times your XSLT code processes a certain XML element. However, that would be a design mistake, because the tree traversal for accumulator computations is not the same as how templates or functions access the tree. An accumulator can say, "This is the third title I've seen so far in this document" but not, "This is the third time I've seen this title so far during processing: once when creating the table of contents, once when rendering the heading, and once when rendering a hyperlink that points here."

Suppose the original document order is not that significant in an XML document you are processing, such as when the XSLT sorts subsections of a topic. An accumulator might be a good fit either for a task unaffected by the sorting or if the accumulator operates on nodes of an already-sorted tree. On the other hand, you might decide that storing a sorted tree would add too much complexity and a non-accumulator solution would be better.

Suppose you are processing documents that can refer to other documents, and you need to track the document URIs as you follow the references. Inspired by mentions of accumulators that implement stacks, you might try to use an accumulator to track the URIs. However, if "following" the references means applying XSLT to the referenced documents using the XPath transform function, an accumulator might not be a suitable solution. I am not aware of a capability for passing an accumulator and its values across an XSLT stylesheet boundary via the transform function. The case where I saw this situation implemented the stack using a tunnel parameter instead of an accumulator.

This situation contrasts with one that came up on an XSL mailing list recently, where a user wanted to accumulate data across topics referenced by a DITA map [M]. This situation used doc rather than transform to access the referenced documents, and an accumulator worked fine because it was crossing a tree boundary, not an XSLT stylesheet boundary.

An accumulator might not be a good substitute for a user-defined function on attribute nodes, because accumulators do not associate values with attribute nodes. If you consider the desired behavior in terms of element nodes, you can judge whether an accumulator that matches element nodes and computes its value related to an element's attributes has any advantages in clarity or functionality compared to an ordinary function.

As you think about the match patterns for which you will create accumulator rules, think about how the patterns might occur in the actual trees you need to process. Plan for potential interactions among patterns:

If your design requires resetting the accumulator value in some way or shedding data that was accumulated earlier in the traversal, remember to implement the reset and do it correctly for your situation. For a resettable counter, consider whether you should reset the value to zero or decrement it by one. For a stack, consider whether you should empty the stack or remove one value from the beginning or the end.

Make sure your accumulator is applicable to the tree where you want to attach the data. Details of your situation determine whether the applicability comes for free, and the rules are in the Applicability of Accumulators section of the XSLT 3.0 specification. Sometimes, you need to add a use-accumulators attribute that lists either accumulator names or the token #all. For example, <xsl:mode use-accumulators="#all"/> makes all accumulators applicable to documents containing nodes in the initial match selection.

Watch the expressions accumulator-before(...) and accumulator-after(...), providing the name of your accumulator as the input argument to these functions. When the transformation is paused at a breakpoint, the XWatch pane shows the accumulator values at the context node. You can also select a row in the XWatch pane and view the value in a tree format, in the Nodes/Values Set pane. As you step through the transformation and the context node changes, the XWatch pane changes the values it shows because the accumulator functions operate at the context node.

Watch an expression that explicitly sets the context node, such as //body/h1[1]/accumulator-before('word-count'). This approach enables you to zero in on any node of interest, and it works at any XSLT breakpoint that the execution reaches, even if the node of interest hasn't yet become the context node for any template. To see multiple nodes' accumulator values together, you can use multiple rows in the XWatch view or specify a path that yields a node sequence of any length (e.g., remove the [1] predicate in the last expression).

URI of the XML document.

URI of the XSLT file containing the accumulator declaration.

Code in the <xsl:accumulator> element. Recording this code in the HTML report can be useful if you iteratively generate reports while modifying your accumulator definition in the XSLT file.

The first column shows element tags and non-element nodes from the XML document. For elements, separate listings for start and end tags distinguish between the accumulator's values before and after visiting the element's descendants. Global parameters in acc-reporter.xsl enable you to control whether the report suppresses whitespace-only text nodes and at what length the report truncates content of text and comment nodes. Truncation is meant to help you focus on the nodes and values, not voluminous text content that would require you to scroll a lot.

The second column shows associated accumulator values. To reduce clutter, the report populates this column only for the document node's values and wherever an accumulator changes its value.

Insert <xsl:message> as a child or other descendant of <xsl:accumulator-rule>, not as a child of <xsl:accumulator>.

Where <xsl:message> is inside <xsl:accumulator-rule>, the latter should contain a sequence constructor, not a select attribute. If you wrote the accumulator rule with a select attribute and want to insert <xsl:message>, modify the rule as in the following example.

<xsl:accumulator-rule match="*" select="newvalue"/>

<xsl:accumulator-rule match="*">
   <xsl:sequence select="newvalue"/>
   <xsl:message expand-text="1">
      At {name(.)} element, old accumulator value is {$value}
   </xsl:message>
</xsl:accumulator-rule>

In your message content, don't call the accumulator-before or accumulator-after functions to refer to the same accumulator whose declaration contains the message. If you try that, you will get an error message that says the accumulator requires access to its own value.

You can, however, use accumulator-before or accumulator-after functions to refer to a different accumulator. Doing so is helpful if you split a complicated computation across multiple accumulators that build on each other in a non-circular way.

You can use the special variable named $value in the message content. This variable stores the value of the accumulator before evaluating the content of this accumulator rule.

In your message content, you can call the accumulator-before and accumulator-after functions to refer to an applicable accumulator.

In your message content, don't use the special $value variable, which is accessible only within <xsl:accumulator-rule>.

The <xsl:message> instruction doesn't have to be in a template rule for the kind of node whose associated accumulator value you want to report. You can insert the message anywhere convenient that (a) will be reached during the transformation and (b) can assume your node of interest as the context node. (Requirement (b) is relevant for stream processing.) Within your message, you can change the context node to your node of interest and then call the accumulator function.

The ability to change context at will is convenient if you want to report accumulator values for multiple tree nodes and prefer to consolidate temporary debugging code in as few locations in your XSLT stylesheet as possible.

One way to begin an investigation of a bug is to write an XSpec test that reproduces the bug. Running the test repeatedly as you modify the code or insert debugging messages can help you diagnose and fix the bug efficiently. After you have fixed the bug, you might as well keep the test to guard against recurrences of the bug. This bug-fixing workflow can apply to code whether or not it involves an accumulator. When you suspect the cause of an XSLT bug is in an accumulator declaration, you might find it handy to know how to make a test that focuses on that declaration.

Some accumulators are complicated. Maybe you have one accumulator whose computations depend on another accumulator. Maybe your accumulator operates on XML documents that can exhibit a variety of pattern combinations, including important edge cases whose support must be maintained. Greater complexity in the accumulator is likely to provide a greater return on your test writing investment.

If the templates and functions that reference your accumulator are large or complicated themselves, you might like the modularity of testing the accumulator in isolation from them.

As in the examples in XSpec Test Importing XSLT Under Test, the scenario defines a tree with which you'd like the accumulator to associate data.

<x:variable name="myv:tree"
    href="../sample-xml/section-with-internal-content.xml"
    select="/"/>

Each lowest-level scenario uses <x:call> to call a wrapper function, at:accumulator-before or at:accumulator-after. The first function parameter is the context node whose accumulator value you want to retrieve, and the second parameter is the name of the accumulator.

The scenario has an <x:expect> element that checks the output of the specified accumulator function. The select attribute provides the expected value of the accumulator function at that context node. XSpec compares this expected value with the result of the <x:call> function call.

<x:expect label="2 internal-only elements in stack"
    select="('remark', 'section')"/>

If you prefer, you can omit the select attribute and write a Boolean expression in the test attribute, as in the following variation on the check for an empty sequence.

<x:expect label="Empty" test="empty($x:result)"/>

If the expected accumulator value is a node, you can provide it as content of the <x:expect> element instead of using the select attribute.