Skip to content

Latest commit

 

History

History
81 lines (53 loc) · 5.71 KB

README.md

File metadata and controls

81 lines (53 loc) · 5.71 KB
Raw

XSLT Accumulator Tools

Utilities for exploring and testing XSLT accumulators, to complement the Balisage 2023 conference presentation, Accumulators in XSLT and XSpec: Developing, Debugging, and Testing XSLT 3 Accumulators.

License: AGPL 3.0 or later

Report of Accumulator Values

Use the src/acc-reporter.xsl stylesheet to generate an HTML report of accumulator values associated with nodes of an XML file.

Here are samples that show how the report looks:

Required Inputs

The src/acc-reporter.xsl stylesheet requires the following information that you provide:

  1. An XML file. Provide it as the source document for the transformation.

  2. Information about your accumulator. Specify it through either XSLT global parameters or top-level processing instructions (example) in the XML source document, as the next table describes. (The parameter takes precedence over the processing instruction, if both appear.)

Item XSLT Parameter Processing Instruction
Accumulator name $acc-name <?acc-name my-accumulator-name?>
URI of XSLT file containing accumulator declaration, relative to the XML file's base URI $acc-decl-uri <?acc-decl-uri my-accumulator-declaration-uri?>
URI of top-level XSLT module, if different from the file containing the accumulator declaration, relative to the XML file's base URI $acc-toplevel-uri <?acc-toplevel-uri my-main-xslt-uri?>

If your accumulator's name is in a namespace with URI foo, you can use notation Q{foo}my-accumulator-name in the value of the $acc-name XSLT parameter or the acc-name processing instruction.

Oxygen XML Editor Instructions

  1. In Oxygen, load xslt-accumulator-tools.xpr and open the XML source document
  2. Either add processing instructions as described above to the XML source document, or modify (a copy of) the "Accumulator Report" transformation scenario to populate the XSLT parameters
  3. Apply the "Accumulator Report" transformation scenario to the XML source document, which automatically opens the HTML report in your default browser

Command-Line Examples (Saxon)

Prerequisite: Install Saxon, referring to Saxon documentation as needed.

From your clone of this repository, you can execute a command like the following:

java -cp "...path to Saxon jar file..." net.sf.saxon.Transform -t -s:src/sample-acc/sample-xml/section-with-elements.xml -xsl:src/acc-reporter.xsl -o:section-with-elements-report.html

The file section-with-elements.xml contains processing instructions that identify the relevant XSLT modules and the accumulator name, so the command above does not need to pass in any global parameter values. In the absence of those processing instructions, your command would have looked like this:

java -cp "...path to Saxon jar file..." net.sf.saxon.Transform -t -s:src/sample-acc/sample-xml/section-with-elements.xml -xsl:src/acc-reporter.xsl -o:section-with-elements-report.html acc-name=Q{my-acc-ns}element-count acc-decl-uri=../acc-decl-not-standalone.xsl acc-toplevel-uri=../parent.xsl

Variation: Generating Report Based on Tree Not in XML File

You can generate an HTML report of accumulator values associated with nodes of a tree that your XSLT stylesheet defines in a variable, even if the tree is not saved to an XML file. In this situation, you do the following:

  1. Augment your XSLT stylesheet to supply data that the report generation code needs and to invoke it from a location of your code where the tree variable is in scope.
  2. Run your XSLT transformation.

For an example that illustrates step 1, see this set of files:

src/sample-acc/tree-report-example.xsl
src/sample-acc/glossary.xsl
src/sample-acc/sample-xml/glossary.xml

If you generate an XML-file-based report for glossary.xml, you can see that the report shows glossary terms in the same sequence as in this XML file.

If you generate a tree-based report by transforming the sample source document glossary.xml with the stylesheet tree-report-example.xsl, you can see that the reports show glossary terms in alphabetical order. That is because the tree-report-example.xsl stylesheet creates a tree in an XSLT variable by sorting the glossary terms from the XML source file.

java -cp "...path to Saxon jar file..." net.sf.saxon.Transform -t -s:src/sample-acc/sample-xml/glossary.xml -xsl:src/sample-acc/tree-report-example.xsl

Helper for XSpec Tests for Accumulators

Import the src/accumulator-test-tools.xsl file in an XSLT stylesheet that you want to test with XSpec via run-as="external". An example of this test architecture is in the following file:

src/sample-acc/test/internal-elem-external.xspec

For examples of architectures that test accumulators using run-as="import" (default), see these files:

src/sample-acc/test/internal-elem-dedicated.xspec
src/sample-acc/test/internal-elem-integrated.xspec