Sample code for "Ignoring Code Comments During XSpec Testing"

README.md

@@ -16,6 +16,7 @@ Each post corresponds to a [subfolder under `src/`](https://github.com/galtm/xsp
 * [Content Outside the Selection in XSpec](https://github.com/galtm/xspectacles/tree/main/src/out-of-scope)
 * [Fixing Surprise Spaces in XSpec Actual Result](https://github.com/galtm/xspectacles/tree/main/src/space-actual)
 * [How to Test Error Handling in XSpec](https://github.com/galtm/xspectacles/tree/main/src/catch-error)
+* **(NEW!)** [Ignoring Code Comments During XSpec Testing](https://github.com/galtm/xspectacles/tree/main/src/helper-comments)
 * [Inheritance as a Form of Reuse in XSpec](https://github.com/galtm/xspectacles/tree/main/src/code-reuse-call)
 * [Multiple Cases in One XSpec Scenario](https://github.com/galtm/xspectacles/tree/main/src/context-sequence)
 * [My XML Content in XSpec Causes an Error](https://github.com/galtm/xspectacles/tree/main/src/xml-content-error)
@@ -30,7 +31,7 @@ Each post corresponds to a [subfolder under `src/`](https://github.com/galtm/xsp
 * [Testing Explicit Whitespace in XSpec](https://github.com/galtm/xspectacles/tree/main/src/space-explicit)
 * [Testing Invisible XML using XSpec](https://github.com/galtm/xspectacles/tree/main/src/ixml)
 * [Testing Preformatted or Codelike Text in XSpec](https://github.com/galtm/xspectacles/tree/main/src/space-preformatted)
-* **(NEW!)** [Testing Schematron Code Embedded in RELAX NG](https://github.com/galtm/xspectacles/tree/main/src/sch-in-relaxng)
+* [Testing Schematron Code Embedded in RELAX NG](https://github.com/galtm/xspectacles/tree/main/src/sch-in-relaxng)
 * [Testing Schematron Messages with XSpec 3.0](https://github.com/galtm/xspectacles/tree/main/src/schematron-messages)
 * [Testing Schematron Patterns in Isolation](https://github.com/galtm/xspectacles/tree/main/src/isolated-patterns)
 * [Text Nodes and Locations in XSpec Tests for Schematron](https://github.com/galtm/xspectacles/tree/main/src/schxslt-in-xspec)

src/helper-comments/README.md

@@ -0,0 +1,17 @@
+# Sample code for "Ignoring Code Comments During XSpec Testing"
+
+Example files for XSLT:
+
+- `test-target.xsl`
+- `helper-remove-comments.xsl`
+- `helper-remove-comments-xslt.xspec`
+
+Example files for XQuery:
+
+- `test-target.xqm`
+- `helper-remove-comments.xqm`
+- `helper-remove-comments-xq.xspec`
+
+
+#### Link to Topic
+[Ignoring Code Comments During XSpec Testing](https://medium.com/@xspectacles/ignoring-code-comments-during-xspec-testing-a460f35a25bb)

src/helper-comments/helper-remove-comments-xq.xspec

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<x:description query="urn:x-xspectacles:functions:report"
+  query-at="test-target.xqm"
+  xmlns:frc="urn:x-xspectacles:functions:helper:remove-comments"
+  xmlns:x="http://www.jenitennison.com/xslt/xspec">
+
+  <!--
+    Sample Code for "Ignoring Code Comments During XSpec Testing"
+    https://medium.com/@xspectacles/ignoring-code-comments-during-xspec-testing-a460f35a25bb
+  -->
+
+  <x:helper query="urn:x-xspectacles:functions:helper:remove-comments"
+    query-at="helper-remove-comments.xqm"/>
+
+  <!-- Scenarios for XSLT also work for XQuery, and 
+    XSpec ignores XSLT helper in a test for XQuery.-->
+  <x:import href="helper-remove-comments-xslt.xspec"/>
+
+</x:description>
+<!-- Copyright © 2024 by Amanda Galtman. -->

src/helper-comments/helper-remove-comments-xslt.xspec

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<x:description stylesheet="test-target.xsl"
+  xmlns:frc="urn:x-xspectacles:functions:helper:remove-comments"
+  xmlns:rpt="urn:x-xspectacles:functions:report"
+  xmlns:x="http://www.jenitennison.com/xslt/xspec">
+
+  <!--
+    Sample Code for "Ignoring Code Comments During XSpec Testing"
+    https://medium.com/@xspectacles/ignoring-code-comments-during-xspec-testing-a460f35a25bb
+  -->
+
+  <x:helper stylesheet="helper-remove-comments.xsl"/>
+
+  <x:scenario label="Use helper function">
+    <x:call function="rpt:report">
+      <x:param select="frc:remove-comments(dataset)">
+        <dataset>
+          <data>100</data>
+          <!-- TEST NOTE: Next data element exceeds 2^8. -->
+          <data>257</data>
+          <data>0</data>
+        </dataset>
+      </x:param>
+    </x:call>
+    <x:expect label="String length data for elements"
+      select="frc:remove-comments(report)">
+      <report>
+        <!--Report about data-->
+        <report-item>Sum: 357</report-item>
+        <!-- TEST NOTE: Mean happens to be an integer here. -->
+        <report-item>Mean: 119</report-item>
+      </report>
+    </x:expect>
+  </x:scenario>
+
+  <x:scenario label="Without helper function"
+    pending="Fails due to TEST NOTE: comments">
+    <x:call function="rpt:report">
+      <x:param>
+        <dataset>
+          <data>100</data>
+          <!-- TEST NOTE: Next data element exceeds 2^8. -->
+          <data>257</data>
+          <data>0</data>
+        </dataset>
+      </x:param>
+    </x:call>
+    <x:expect label="Report with standard comment">
+      <report>
+        <!--Report about data-->
+        <report-item>Sum: 357</report-item>
+        <!-- TEST NOTE: Mean happens to be an integer here. -->
+        <report-item>Mean: 119</report-item>
+      </report>
+    </x:expect>
+  </x:scenario>
+
+</x:description>
+<!-- Copyright © 2024 by Amanda Galtman. -->

src/helper-comments/helper-remove-comments.xqm

@@ -0,0 +1,67 @@
+xquery version "3.1";
+module namespace frc = "urn:x-xspectacles:functions:helper:remove-comments";
+
+(:
+  Sample Code for "Ignoring Code Comments During XSpec Testing"
+  https://medium.com/@xspectacles/ignoring-code-comments-during-xspec-testing-a460f35a25bb
+:)
+
+declare variable $frc:prefix as xs:string := 'TEST NOTE:';
+(:
+Removes certain comments from $node, assumed to be an element,
+document node, or empty sequence. The comments to remove are those
+whose space-normalized content starts with 'TEST NOTE:'.
+:)
+declare %public function frc:remove-comments(
+$node as node()?
+) {
+  typeswitch ($node)
+    case comment()
+      return
+        frc:comment-handler($node)
+    case document-node()
+      return
+        frc:doc-node-handler($node)
+    case element()
+      return
+        frc:element-handler($node)
+    default
+      return
+        $node
+};
+
+declare %private function frc:element-handler(
+$node as element()
+) as element() {
+  element {node-name($node)} {
+    for $n in in-scope-prefixes($node)
+    return
+      namespace {$n} {namespace-uri-for-prefix($n, $node)},
+    $node/@attribute(),
+    for $child in $node/node()
+    return
+      frc:remove-comments($child)
+  }
+};
+
+declare %private function frc:doc-node-handler(
+$node as document-node()
+) as document-node() {
+  document {
+    for $child in $node/node()
+    return
+      frc:remove-comments($child)
+  }
+};
+
+declare %private function frc:comment-handler(
+$node as comment()
+) as comment()? {
+  if (starts-with(normalize-space($node), $frc:prefix))
+  then
+    ()
+  else
+    $node
+};
+
+(: Copyright © 2024 by Amanda Galtman. :)

src/helper-comments/helper-remove-comments.xsl

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet exclude-result-prefixes="#all" version="3.0"
+  xmlns:frc="urn:x-xspectacles:functions:helper:remove-comments"
+  xmlns:mrc="urn:x-xspectacles:modes:helper:remove-comments"
+  xmlns:xs="http://www.w3.org/2001/XMLSchema"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+  <!--
+    Sample Code for "Ignoring Code Comments During XSpec Testing"
+    https://medium.com/@xspectacles/ignoring-code-comments-during-xspec-testing-a460f35a25bb
+  -->
+
+  <!--
+    Removes certain comments from $node, assumed to be an element,
+    document node, or empty sequence. The comments to remove are those
+    whose space-normalized content starts with 'TEST NOTE:'.
+  -->
+  <xsl:function name="frc:remove-comments" as="node()" visibility="public">
+    <xsl:param name="element-or-document-node" as="node()"/>
+    <xsl:apply-templates select="$element-or-document-node"
+      mode="mrc:remove-comments"/>
+  </xsl:function>
+
+  <xsl:mode name="mrc:remove-comments" on-multiple-match="fail"
+    on-no-match="fail"/>
+
+  <!-- Low-priority identity template -->
+  <xsl:template match="document-node() | node() | @*" mode="mrc:remove-comments"
+    priority="-10" as="node()">
+    <xsl:copy>
+      <xsl:apply-templates select="node() | @*" mode="#current"/>
+    </xsl:copy>
+  </xsl:template>
+
+  <!-- Discard comment nodes that start with specified prefix. -->
+  <xsl:variable name="frc:prefix" as="xs:string" select="'TEST NOTE:'"/>
+  <xsl:template match="comment()[starts-with(normalize-space(.), $frc:prefix)]"
+    mode="mrc:remove-comments" as="empty-sequence()"/>
+
+</xsl:stylesheet>
+<!-- Copyright © 2024 by Amanda Galtman. -->

src/helper-comments/test-target.xqm

@@ -0,0 +1,26 @@
+xquery version "3.1";
+module namespace rpt = "urn:x-xspectacles:functions:report";
+
+(:
+  Sample Code for "Ignoring Code Comments During XSpec Testing"
+  https://medium.com/@xspectacles/ignoring-code-comments-during-xspec-testing-a460f35a25bb
+:)
+
+declare function rpt:report(
+$input as node()
+) as element(report) {
+  let $boilerplate-comment as comment() :=
+  comment {'Report about data'}
+  return
+    <report>{
+        (
+        $input/descendant::comment(),
+        $boilerplate-comment
+        )[1]
+      }
+      <report-item>Sum: {sum($input//data/number())}</report-item>
+      <report-item>Mean: {avg($input//data/number())}</report-item>
+    </report>
+};
+
+(: Copyright © 2024 by Amanda Galtman. :)

src/helper-comments/test-target.xsl

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet exclude-result-prefixes="#all" version="3.0"
+  xmlns:rpt="urn:x-xspectacles:functions:report"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+  <!--
+    Sample Code for "Ignoring Code Comments During XSpec Testing"
+    https://medium.com/@xspectacles/ignoring-code-comments-during-xspec-testing-a460f35a25bb
+  -->
+
+  <xsl:function name="rpt:report" as="element(report)"
+    visibility="public">
+    <xsl:param name="input" as="node()"/>
+    <xsl:variable name="boilerplate-comment" as="comment()">
+      <xsl:comment>Report about data</xsl:comment>
+    </xsl:variable>
+    <report xsl:expand-text="yes">
+      <xsl:sequence select="
+          (
+          $input/descendant::comment(),
+          $boilerplate-comment
+          )[1]"/>
+      <report-item>Sum: {sum($input//data/number())}</report-item>
+      <report-item>Mean: {avg($input//data/number())}</report-item>
+    </report>
+  </xsl:function>
+</xsl:stylesheet>
+<!-- Copyright © 2024 by Amanda Galtman. -->