Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Enhance code comments for key files #14

Merged
merged 1 commit into from
Jul 28, 2023
Merged

Enhance code comments for key files #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 85 additions & 7 deletions src/acc-report-inclusion.xsl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@
<!-- ============ -->
<!-- ACCUMULATORS -->

<!-- That at:indent-level accumulator tracks the indentation level to use
in the HTML report. -->
<xsl:accumulator name="at:indent-level" as="xs:integer" initial-value="0">
<xsl:accumulator-rule match="element() | text() | comment() | processing-instruction()"
select="$value + 1"/>
Expand All @@ -35,8 +37,8 @@
select="$value - 1"/>
</xsl:accumulator>

<!-- The at:two-value-queue accumulator stores another accumulator's
last value and current value. -->
<!-- The at:two-value-queue accumulator, as a stepping stone toward at:prior-value,
stores another accumulator's last value and current value. -->
<xsl:accumulator name="at:two-value-queue" initial-value="()" as="map(*)?">
<xsl:accumulator-rule match="element() | text() | comment() | processing-instruction() | document-node()"
phase="start">
Expand All @@ -54,6 +56,8 @@
</xsl:accumulator-rule>
</xsl:accumulator>

<!-- The at:prior-value accumulator reads off the prior value that was stored in the
at:two-value-queue accumulator. -->
<xsl:accumulator name="at:prior-value" initial-value="()">
<xsl:accumulator-rule match="element() | text() | comment() | processing-instruction() | document-node()">
<xsl:sequence select="(accumulator-before('at:two-value-queue'))('prior')"/>
Expand All @@ -67,6 +71,11 @@
<!-- ======================= -->
<!-- TEMPLATES AND FUNCTIONS -->

<!--
This template produces HTML markup for the report.
This template is the initial template when acc-reporter.xsl
calls a generated transform that includes this one.
-->
<xsl:template name="at:process-root" as="element(h:html)" expand-text="1">
<!-- Context item is document node or other root of tree -->
<xsl:context-item as="node()" use="required"/>
Expand Down Expand Up @@ -99,6 +108,10 @@
</html>
</xsl:template>

<!--
This template creates one table row each for the start and end of the
document, applying templates in between those two rows.
-->
<xsl:template match="document-node()" mode="at:acc-view" as="element(h:tr)+">
<tr>
<td>
Expand Down Expand Up @@ -127,6 +140,10 @@
</tr>
</xsl:template>

<!--
This template creates one table row each for the start and end of the
element, applying templates in between those two rows.
-->
<xsl:template match="element()" mode="at:acc-view" expand-text="1"
as="element(h:tr)+">
<tr>
Expand Down Expand Up @@ -156,6 +173,11 @@
</tr>
</xsl:template>

<!--
This template creates one table row for a text node, unless
the node consists of white space only and $at:skip-whitespace
is true.
-->
<xsl:template match="text()" mode="at:acc-view" as="element(h:tr)?">
<xsl:if test="not($at:skip-whitespace) or
string-length(replace(.,'\s+','')) gt 0">
Expand All @@ -170,6 +192,9 @@
</xsl:if>
</xsl:template>

<!--
This template creates one table row for a comment node.
-->
<xsl:template match="comment()" mode="at:acc-view" as="element(h:tr)?">
<tr>
<td>
Expand All @@ -183,6 +208,10 @@
</tr>
</xsl:template>

<!--
This template creates one table row for a processing instruction node,
unless it is a special PI for consumption by this reporting tool.
-->
<xsl:template match="processing-instruction()" mode="at:acc-view"
expand-text="1" as="element(h:tr)?">
<xsl:if test="not(name(.)=('acc-decl-uri','acc-name','acc-toplevel-uri'))">
Expand All @@ -191,7 +220,7 @@
<span class="pi">
<xsl:variable name="stringseq" as="xs:string+">
<xsl:call-template name="at:indent"/>
<xsl:sequence select="'&lt;?' || name(.) || ' ' || . || '?>'"/>
<xsl:sequence select="'&lt;?' || name(.) || ' ' || . || '?>'"/>
</xsl:variable>
<xsl:sequence select="string-join($stringseq,'')"/>
</span>
Expand All @@ -203,6 +232,10 @@
</xsl:if>
</xsl:template>

<!--
This template creates a string for indenting table cell content
by a depth taken from the at:indent-level accumulator.
-->
<xsl:template name="at:indent" as="xs:string">
<xsl:context-item use="required" as="node()"/>
<xsl:variable name="level" as="xs:integer"
Expand All @@ -213,10 +246,14 @@
'')"/>
</xsl:template>

<!-- For non-element nodes, first column doesn't render distinct start and
end phases. Make the second column distinguish phases only if the
accumulator has different values for this node at start and end phases
(which is probably uncommon in practice, for a non-element node). -->
<!--
This template creates content for a cell in the second column, in a
row for a non-element node. For these nodes, the first column doesn't
render distinct start and end phases. This template makes the second
column distinguish the two phases only if the accumulator has different
values for this node at start and end phases (which is probably
uncommon in practice, for a non-element node).
-->
<xsl:template name="at:second-column-non-element-node">
<xsl:context-item use="required"/>
<xsl:variable name="start-phase-info" as="element(h:pre)?">
Expand Down Expand Up @@ -245,6 +282,14 @@
</xsl:choose>
</xsl:template>

<!--
This template creates HTML markup for the accumulator declaration.

Parameters:

$acc-decl-uri: URI of file containing accumulator declaration
$acc-name: Accumulator name
-->
<xsl:template name="at:show-declaration" as="element(h:details)">
<xsl:param name="acc-decl-uri" as="xs:string" select="$at:acc-decl-uri"/>
<xsl:param name="acc-name" as="xs:string" select="$at:acc-name"/>
Expand All @@ -262,6 +307,11 @@
</details>
</xsl:template>

<!--
This template creates a string based on content of a text
or comment node. The string includes indentation and also
replaces text with "..." after $at:trunc characters.
-->
<xsl:template name="at:truncated-text-or-comment" as="xs:string">
<xsl:context-item use="required" as="node()"/>
<xsl:variable name="stringseq" as="xs:string+">
Expand All @@ -280,6 +330,16 @@
<xsl:sequence select="string-join($stringseq,'')"/>
</xsl:template>

<!--
This template creates a <pre> element with the serialized
value of the accumulator, but only if the value has changed
since its prior value.

Parameters:

$acc-value: Current value of accumulator
$acc-prior-value: Prior value of accumulator
-->
<xsl:template name="at:acc-value-if-changed" as="element(h:pre)?">
<xsl:param name="acc-value" select="accumulator-before($at:acc-name)"/>
<xsl:param name="acc-prior-value" select="accumulator-before('at:prior-value')"/>
Expand All @@ -298,6 +358,14 @@
</xsl:if>
</xsl:template>

<!--
This function produces HTML markup for displaying a
sequence of attributes.

Parameters:

$attrs: Sequence of attribute nodes
-->
<xsl:function name="at:list-attrs" as="element(h:span)*">
<xsl:param name="attrs" as="attribute()*"/>
<xsl:iterate select="$attrs" expand-text="1">
Expand All @@ -306,6 +374,16 @@
</xsl:iterate>
</xsl:function>

<!--
This function truncates the beginning of URIs in
clones of this repository so that they start from
.../xslt-accumulator-tools/. URIs outside this
repository are unchanged.

Parameters:

$uri: URI as a string
-->
<xsl:function name="at:truncate-uri" as="xs:string">
<xsl:param name="uri" as="xs:string?"/>
<xsl:variable name="repo-sample-acc" as="xs:string"
Expand Down
49 changes: 49 additions & 0 deletions src/acc-reporter.xsl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
exclude-result-prefixes="#all"
version="3.0">

<!-- ========== -->
<!-- PARAMETERS -->
<xsl:param name="acc-decl-uri" as="xs:string?"/>
<xsl:param name="acc-name" as="xs:string?"/>
Expand All @@ -16,12 +17,40 @@
<xsl:param name="at:skip-whitespace" as="xs:boolean" select="true()"/>
<xsl:param name="at:trunc" as="xs:integer" select="60"/>

<!-- ======= -->
<!-- IMPORTS -->
<xsl:import href="lib/xspec/src/compiler/base/util/compiler-eqname-utils.xsl"/>

<!-- ======= -->
<!-- ALIASES -->
<xsl:namespace-alias stylesheet-prefix="genxsl" result-prefix="xsl"/>

<!-- ========= -->
<!-- TEMPLATES -->

<!--
This template transforms the given XML file with a generated
XSLT stylesheet that combines tools from this repository
with user-specified XSLT code.

Parameters:

$acc-decl-uri-local: URI of file containing accumulator
declaration. Default is from global $acc-decl-uri, if
nonempty, or the XML tree's top-level processing
instruction named acc-decl-uri. If used, the default
value is resolved relative to the XML file's base URI.
$acc-name-local: Accumulator name. Default is from global
$acc-name, if nonempty, or the XML tree's top-level
processing instruction named acc-name.
$acc-toplevel-uri-local: URI of top-level XSLT file, if
different from the file containing the accumulator
declaration. Default is from global $acc-toplevel-uri,
if nonempty, or the XML tree's top-level processing
instruction named acc-toplevel-uri. If used, the
default value is resolved relative to the XML file's
base URI.
-->
<xsl:template match="/" as="element()">
<xsl:param name="acc-decl-uri-local" as="xs:string"
select="(if ($acc-decl-uri != '')
Expand Down Expand Up @@ -56,6 +85,17 @@
<xsl:sequence select="$transform-result?output"/>
</xsl:template>

<!--
This template creates a map of transform options suitable for
use with transform().

Parameters:

$acc-decl-uri: Like top-level template's $acc-decl-uri-local
$acc-name: Like top-level template's $acc-name-local
$acc-toplevel-uri: Like top-level template's $acc-toplevel-uri-local
$source: XML document node
-->
<xsl:template name="at:transform-options" as="map(xs:string, item()*)">
<xsl:param name="acc-decl-uri" as="xs:string"/>
<xsl:param name="acc-name" as="xs:string"/>
Expand Down Expand Up @@ -95,6 +135,15 @@
<xsl:sequence select="$transform-options"/>
</xsl:template>

<!--
This template checks that the user-specified XSLT module
has exactly one accumulator by the expected name.

Parameters:

$acc-decl-uri: Like top-level template's $acc-decl-uri-local
$acc-name: Like top-level template's $acc-name-local
-->
<xsl:template name="at:error-checking" as="empty-sequence()">
<xsl:param name="acc-decl-uri" as="xs:string" required="yes"/>
<xsl:param name="acc-name" as="xs:string" required="yes"/>
Expand Down
16 changes: 16 additions & 0 deletions src/accumulator-test-tools.xsl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,14 @@
so they can be accessed from an XSpec external transformation
using x:call. -->

<!--
This function is a wrapper around fn:accumulator-before.

Parameters:

$context: Context node from which to call fn:accumulator-before
$name: Accumulator name
-->
<xsl:function name="at:accumulator-before" visibility="public">
<xsl:param name="context" as="node()?"/>
<xsl:param name="name" as="xs:string"/>
Expand All @@ -23,6 +31,14 @@
<xsl:sequence select="$context/fn:accumulator-before($name)"/>
</xsl:function>

<!--
This function is a wrapper around fn:accumulator-after.

Parameters:

$context: Context node from which to call fn:accumulator-after
$name: Accumulator name
-->
<xsl:function name="at:accumulator-after" visibility="public">
<xsl:param name="context" as="node()?"/>
<xsl:param name="name" as="xs:string"/>
Expand Down