s1kd-brexcheck: Add dynamic XPath support

If an XPath 2.0 engine is selected at compile-time, s1kd-brexcheck will now dynamically use the appropriate version of XPath based on the S1000D issue of the BREX data module (3.0 and lower = XPath 1.0, 4.0 and up = XPath 2.0). The -X (--xpath-version) option allows the user to force a particular version of XPath, regardless of the issue. The Makefile variable BREXCHECK_XPATH_ENGINE was renamed to XPATH2_ENGINE accordingly.
kibook · Sep 11, 2020 · 530216e · 530216e
1 parent 5a41746
commit 530216e
Show file tree

Hide file tree

Showing 9 changed files with 337 additions and 185 deletions.
diff --git a/INSTALL.md b/INSTALL.md
@@ -104,52 +104,42 @@ Additional Makefile parameters
 The following parameters can be given to `make` to control certain
 options when building and installing.
 
-### `BREXCHECK_XPATH_ENGINE`
+### `PREFIX`
+
+The `PREFIX` variable determines where the s1kd-tools are installed when
+running `make install`, and where they are uninstalled from when running
+`make uninstall`. The default value is `/usr/local`.
+
+Example:
 
-The `BREXCHECK_XPATH_ENGINE` variable determines which XPath
-implementation the s1kd-brexcheck tool will use to evaluate the object
-paths of BREX rules.
+    # make PREFIX=/usr install
+
+    # make PREFIX=/usr uninstall
+
+### `XPATH2_ENGINE`
+
+The `XPATH2_ENGINE` variable determines which XPath 2.0 implementation
+the s1kd-brexcheck tool will use to evaluate the object paths of BREX
+rules.
 
 The s1kd-tools are built on libxml, so by default s1kd-brexcheck uses
 libxml's XPath implementation. However, libxml only supports XPath 1.0.
 While as of Issue 5.0, the S1000D default BREX rules are all compatible
 with XPath 1.0, Issue 4.0 and up do reference the XPath 2.0
 specification. Therefore, if your project needs XPath 2.0 support for
-BREX rules, you should select a different implementation.
-
-`LIBXML`  
-The default implementation. Fast and requires no additional
-dependencies.
-
-Supports XPath 1.0 and some EXSLT functions.
+BREX rules, you should select one of these implementations:
 
 `SAXON`  
 Experimental implementation using the Saxon/C library. Slower, and
 Saxon/C itself is a very large dependency. Not recommended at this time
 due to memory leak issues.
 
-Supports XPath 1.0, 2.0 and 3.0.
-
 `XQILLA`  
 Experimental implementation using the Xerces-C and XQilla libraries. A
 little slower than libxml, but faster than Saxon/C, and the dependencies
 are much smaller than the latter. This is currently the recommended
 implementation if you need XPath 2.0 support.
 
-Supports XPath 1.0 and 2.0.
-
-Example:
-
-    $ make BREXCHECK_XPATH_ENGINE=XQILLA
-
-### `PREFIX`
-
-The `PREFIX` variable determines where the s1kd-tools are installed when
-running `make install`, and where they are uninstalled from when running
-`make uninstall`. The default value is `/usr/local`.
-
 Example:
 
-    # make PREFIX=/usr install
-
-    # make PREFIX=/usr uninstall
+    $ make XPATH2_ENGINE=XQILLA
diff --git a/doc/DMC-S1KDTOOLS-A-00-00-00-00A-920A-D_EN-CA.XML b/doc/DMC-S1KDTOOLS-A-00-00-00-00A-920A-D_EN-CA.XML
@@ -198,28 +198,29 @@
           <para>The following parameters can be given to <verbatimText>make</verbatimText> to control certain options when building and installing.</para>
           <levelledPara>
             <title>
-              <verbatimText>BREXCHECK_XPATH_ENGINE</verbatimText>
+              <verbatimText>PREFIX</verbatimText>
+            </title>
+            <para>The <verbatimText>PREFIX</verbatimText> variable determines where the s1kd-tools are installed when running <verbatimText>make install</verbatimText>, and where they are uninstalled from when running <verbatimText>make uninstall</verbatimText>. The default value is <verbatimText>/usr/local</verbatimText>.</para>
+            <para>
+              Example:
+              <verbatimText verbatimStyle="vs24"># make PREFIX=/usr install</verbatimText>
+              <verbatimText verbatimStyle="vs24"># make PREFIX=/usr uninstall</verbatimText>
+            </para>
+          </levelledPara>
+          <levelledPara>
+            <title>
+              <verbatimText>XPATH2_ENGINE</verbatimText>
             </title>
-            <para>The <verbatimText>BREXCHECK_XPATH_ENGINE</verbatimText> variable determines which XPath implementation the s1kd-brexcheck tool will use to evaluate the object paths of BREX rules.</para>
-            <para>The s1kd-tools are built on libxml, so by default s1kd-brexcheck uses libxml's XPath implementation. However, libxml only supports XPath 1.0. While as of Issue 5.0, the S1000D default BREX rules are all compatible with XPath 1.0, Issue 4.0 and up do reference the XPath 2.0 specification. Therefore, if your project needs XPath 2.0 support for BREX rules, you should select a different implementation.</para>
+            <para>The <verbatimText>XPATH2_ENGINE</verbatimText> variable determines which XPath 2.0 implementation the s1kd-brexcheck tool will use to evaluate the object paths of BREX rules.</para>
             <para>
+              The s1kd-tools are built on libxml, so by default s1kd-brexcheck uses libxml's XPath implementation. However, libxml only supports XPath 1.0. While as of Issue 5.0, the S1000D default BREX rules are all compatible with XPath 1.0, Issue 4.0 and up do reference the XPath 2.0 specification. Therefore, if your project needs XPath 2.0 support for BREX rules, you should select one of these implementations:
               <definitionList>
-                <definitionListItem>
-                  <listItemTerm>
-                    <verbatimText>LIBXML</verbatimText>
-                  </listItemTerm>
-                  <listItemDefinition>
-                    <para>The default implementation. Fast and requires no additional dependencies.</para>
-                    <para>Supports XPath 1.0 and some EXSLT functions.</para>
-                  </listItemDefinition>
-                </definitionListItem>
                 <definitionListItem>
                   <listItemTerm>
                     <verbatimText>SAXON</verbatimText>
                   </listItemTerm>
                   <listItemDefinition>
                     <para>Experimental implementation using the Saxon/C library. Slower, and Saxon/C itself is a very large dependency. Not recommended at this time due to memory leak issues.</para>
-                    <para>Supports XPath 1.0, 2.0 and 3.0.</para>
                   </listItemDefinition>
                 </definitionListItem>
                 <definitionListItem>
@@ -228,25 +229,13 @@
                   </listItemTerm>
                   <listItemDefinition>
                     <para>Experimental implementation using the Xerces-C and XQilla libraries. A little slower than libxml, but faster than Saxon/C, and the dependencies are much smaller than the latter. This is currently the recommended implementation if you need XPath 2.0 support.</para>
-                    <para>Supports XPath 1.0 and 2.0.</para>
                   </listItemDefinition>
                 </definitionListItem>
               </definitionList>
             </para>
             <para>
               Example:
-              <verbatimText verbatimStyle="vs24">$ make BREXCHECK_XPATH_ENGINE=XQILLA</verbatimText>
-            </para>
-          </levelledPara>
-          <levelledPara>
-            <title>
-              <verbatimText>PREFIX</verbatimText>
-            </title>
-            <para>The <verbatimText>PREFIX</verbatimText> variable determines where the s1kd-tools are installed when running <verbatimText>make install</verbatimText>, and where they are uninstalled from when running <verbatimText>make uninstall</verbatimText>. The default value is <verbatimText>/usr/local</verbatimText>.</para>
-            <para>
-              Example:
-              <verbatimText verbatimStyle="vs24"># make PREFIX=/usr install</verbatimText>
-              <verbatimText verbatimStyle="vs24"># make PREFIX=/usr uninstall</verbatimText>
+              <verbatimText verbatimStyle="vs24">$ make XPATH2_ENGINE=XQILLA</verbatimText>
             </para>
           </levelledPara>
         </levelledPara>

diff --git a/tools/s1kd-brexcheck/Makefile b/tools/s1kd-brexcheck/Makefile
@@ -25,9 +25,9 @@ PREFIX=/usr/local
 INSTALL_PREFIX=$(PREFIX)/bin
 INSTALL=install -Ds
 
-BREXCHECK_XPATH_ENGINE=LIBXML
+XPATH2_ENGINE=NONE
 
-ifeq ($(BREXCHECK_XPATH_ENGINE),SAXON)
+ifeq ($(XPATH2_ENGINE),SAXON)
   ifeq ($(OS),Windows_NT)
     SAXON_C_DIR=/cygdrive/c/Progra~1/Saxonica/SaxonHEC1.2.1
   else
@@ -74,7 +74,7 @@ ifeq ($(BREXCHECK_XPATH_ENGINE),SAXON)
   endif
 endif
 
-ifeq ($(BREXCHECK_XPATH_ENGINE),XQILLA)
+ifeq ($(XPATH2_ENGINE),XQILLA)
   XQILLA_OBJECTS+=xqilla/xqilla.o
 
   SOURCE+=$(XQILLA_OBJECTS)
@@ -89,7 +89,7 @@ ifeq ($(BREXCHECK_XPATH_ENGINE),XQILLA)
   endif
 endif
 
-CFLAGS+=-DXPATH_ENGINE=$(BREXCHECK_XPATH_ENGINE)
+CFLAGS+=-DXPATH2_ENGINE=$(XPATH2_ENGINE)
 
 all: $(OUTPUT)
 

diff --git a/tools/s1kd-brexcheck/README.md b/tools/s1kd-brexcheck/README.md
@@ -7,7 +7,8 @@ SYNOPSIS
 ========
 
     s1kd-brexcheck [-b <brex>] [-d <dir>] [-I <path>] [-w <severities>]
-                   [-F|-f] [-BceLlNnopqrS[tu]sTvx^h?] [<object>...]
+                   [-X <version>] [-F|-f] [-BceLlNnopqrS[tu]sTvx^h?]
+                   [<object>...]
 
 DESCRIPTION
 ===========
@@ -112,6 +113,10 @@ Verbose mode. The success or failure of each test is printed explicitly.
 -w, --severity-levels &lt;file&gt;  
 Specify a list of severity levels for business rules.
 
+-X, --xpath-version &lt;version&gt;  
+Force the specified version of XPath to be used when evaluating the
+object paths of BREX rules.
+
 -x, --xml  
 Output an XML report.
 
@@ -276,20 +281,22 @@ notation.
 XPath support
 -------------
 
-Supported XPath syntax depends on what XPath engine was selected at
-compile-time:
+By default, s1kd-brexcheck supports only XPath 1.0, with partial support
+for EXSLT functions.
 
-libxml (default)  
-XPath 1.0 and partial support for EXSLT functions
+If experimental XPath 2.0 support is enabled at compile-time,
+s1kd-brexcheck will automatically choose a version of XPath based on the
+S1000D issue of the BREX data module:
 
-Saxon (experimental)  
-XPath 1.0, 2.0 and 3.0
+3.0 and lower  
+XPath 1.0
 
-XQilla (experimental)  
-XPath 1.0 and 2.0
+4.0 and up  
+XPath 2.0
 
-Information on which XPath engine is in use can be obtained from the
---version option.
+The -X (--xpath-version) option can be specified to force a particular
+version of XPath to be used regardless of issue. Information on which
+XPath versions are supported can be obtained from the --version option.
 
 If the XPath given for the `<objectPath>` of a rule is invalid, the rule
 will be ignored when validating objects. A warning will be printed to
@@ -311,6 +318,9 @@ One or more CSDB objects specified could not be read.
 3  
 A referenced BREX data module could not be found.
 
+4  
+The XPath version specified is unsupported.
+
 5  
 The number of paths or CSDB objects specified exceeded the available
 memory.

diff --git a/tools/s1kd-brexcheck/doc/DMC-S1KDTOOLS-A-04-00-00-00A-040A-D_EN-CA.XML b/tools/s1kd-brexcheck/doc/DMC-S1KDTOOLS-A-04-00-00-00A-040A-D_EN-CA.XML
@@ -6,10 +6,10 @@
       <dmIdent>
         <dmCode modelIdentCode="S1KDTOOLS" systemDiffCode="A" systemCode="04" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="040" infoCodeVariant="A" itemLocationCode="D"/>
         <language languageIsoCode="en" countryIsoCode="CA"/>
-        <issueInfo issueNumber="039" inWork="02"/>
+        <issueInfo issueNumber="039" inWork="03"/>
       </dmIdent>
       <dmAddressItems>
-        <issueDate year="2020" month="09" day="04"/>
+        <issueDate year="2020" month="09" day="11"/>
         <dmTitle>
           <techName>s1kd-brexcheck(1) | s1kd-tools</techName>
         </dmTitle>
@@ -41,6 +41,9 @@
       <reasonForUpdate id="rfu-0001" updateHighlight="1" updateReasonType="urt02">
         <simplePara>Add experimental XQilla support.</simplePara>
       </reasonForUpdate>
+      <reasonForUpdate id="rfu-0002" updateHighlight="1" updateReasonType="urt02">
+        <simplePara>Add -X (--xpath-version) option.</simplePara>
+      </reasonForUpdate>
     </dmStatus>
   </identAndStatusSection>
   <content>
@@ -52,8 +55,9 @@
       <levelledPara>
         <title>SYNOPSIS</title>
         <para>
-          <verbatimText verbatimStyle="vs24"><![CDATA[s1kd-brexcheck [-b <brex>] [-d <dir>] [-I <path>] [-w <severities>]
-               [-F|-f] [-BceLlNnopqrS[tu]sTvx^h?] [<object>...]]]></verbatimText>
+          <verbatimText verbatimStyle="vs24" changeMark="1" changeType="modify" reasonForUpdateRefIds="rfu-0002"><![CDATA[s1kd-brexcheck [-b <brex>] [-d <dir>] [-I <path>] [-w <severities>]
+               [-X <version>] [-F|-f] [-BceLlNnopqrS[tu]sTvx^h?]
+               [<object>...]]]></verbatimText>
         </para>
       </levelledPara>
       <levelledPara>
@@ -203,6 +207,12 @@
                 <para>Specify a list of severity levels for business rules.</para>
               </listItemDefinition>
             </definitionListItem>
+            <definitionListItem changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0002">
+              <listItemTerm>-X, --xpath-version &lt;version&gt;</listItemTerm>
+              <listItemDefinition>
+                <para>Force the specified version of XPath to be used when evaluating the object paths of BREX rules.</para>
+              </listItemDefinition>
+            </definitionListItem>
             <definitionListItem>
               <listItemTerm>-x, --xml</listItemTerm>
               <listItemDefinition>
@@ -368,29 +378,24 @@
         </levelledPara>
         <levelledPara>
           <title>XPath support</title>
-          <para>
-            Supported XPath syntax depends on what XPath engine was selected at compile-time:
+          <para changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0002">By default, s1kd-brexcheck supports only XPath 1.0, with partial support for EXSLT functions.</para>
+          <para changeMark="1" changeType="modify" reasonForUpdateRefIds="rfu-0002">
+            If experimental XPath 2.0 support is enabled at compile-time, s1kd-brexcheck will automatically choose a version of XPath based on the S1000D issue of the BREX data module:
             <definitionList>
               <definitionListItem>
-                <listItemTerm>libxml (default)</listItemTerm>
+                <listItemTerm>3.0 and lower</listItemTerm>
                 <listItemDefinition>
-                  <para>XPath 1.0 and partial support for EXSLT functions</para>
+                  <para>XPath 1.0</para>
                 </listItemDefinition>
               </definitionListItem>
               <definitionListItem>
-                <listItemTerm>Saxon (experimental)</listItemTerm>
+                <listItemTerm>4.0 and up</listItemTerm>
                 <listItemDefinition>
-                  <para>XPath 1.0, 2.0 and 3.0</para>
-                </listItemDefinition>
-              </definitionListItem>
-              <definitionListItem changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0001">
-                <listItemTerm>XQilla (experimental)</listItemTerm>
-                <listItemDefinition>
-                  <para>XPath 1.0 and 2.0</para>
+                  <para>XPath 2.0</para>
                 </listItemDefinition>
               </definitionListItem>
             </definitionList>
-            Information on which XPath engine is in use can be obtained from the --version option.
+            The -X (--xpath-version) option can be specified to force a particular version of XPath to be used regardless of issue. Information on which XPath versions are supported can be obtained from the --version option.
           </para>
           <para>If the XPath given for the <verbatimText verbatimStyle="vs12">&lt;objectPath&gt;</verbatimText> of a rule is invalid, the rule will be ignored when validating objects. A warning will be printed to stderr, and the XML report will contain an <verbatimText verbatimStyle="vs12">&lt;xpathError&gt;</verbatimText> element for each error.</para>
         </levelledPara>
@@ -423,6 +428,12 @@
                 <para>A referenced BREX data module could not be found.</para>
               </listItemDefinition>
             </definitionListItem>
+            <definitionListItem changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0002">
+              <listItemTerm>4</listItemTerm>
+              <listItemDefinition>
+                <para>The XPath version specified is unsupported.</para>
+              </listItemDefinition>
+            </definitionListItem>
             <definitionListItem>
               <listItemTerm>5</listItemTerm>
               <listItemDefinition>