From 0cc1b8b37e38a8d18a8df21cd81c7b607f0efba3 Mon Sep 17 00:00:00 2001
From: Mark Raynsford <code@io7m.com>
Date: Sun, 24 Jan 2021 12:57:09 +0000
Subject: [PATCH] Add more scalar element handlers

This adds more scalar element handlers to the Blackthorne API to make
it more convenient to parse text values from elements.

Affects: https://github.com/io7m/blackthorne/issues/2
---
 README-CHANGES.xml                            |   9 +-
 com.io7m.blackthorne.api/pom.xml              |   2 +-
 .../com/io7m/blackthorne/api/Blackthorne.java |  81 ++++++++++++
 .../io7m/blackthorne/api/package-info.java    |   2 +-
 com.io7m.blackthorne.jxe/pom.xml              |   2 +-
 com.io7m.blackthorne.tests/pom.xml            |   2 +-
 .../blackthorne/tests/BlackthorneTest.java    | 119 ++++++++++++++++++
 .../com/io7m/blackthorne/tests/choice.xsd     |   6 +
 .../com/io7m/blackthorne/tests/string.xml     |   3 +
 pom.xml                                       |   4 +-
 10 files changed, 222 insertions(+), 8 deletions(-)
 create mode 100644 com.io7m.blackthorne.tests/src/test/resources/com/io7m/blackthorne/tests/string.xml

diff --git a/README-CHANGES.xml b/README-CHANGES.xml
index c7e2022..e2c3423 100644
--- a/README-CHANGES.xml
+++ b/README-CHANGES.xml
@@ -13,13 +13,18 @@
         </c:change>
       </c:changes>
     </c:release>
-    <c:release date="2021-01-24T12:38:06+00:00" is-open="true" ticket-system="com.github.io7m.blackthorne" version="1.2.0">
+    <c:release date="2021-01-24T12:55:01+00:00" is-open="true" ticket-system="com.github.io7m.blackthorne" version="1.2.0">
       <c:changes>
-        <c:change date="2021-01-24T12:38:06+00:00" summary="Add logging for content handlers">
+        <c:change date="2021-01-24T00:00:00+00:00" summary="Add logging for content handlers">
           <c:tickets>
             <c:ticket id="3"/>
           </c:tickets>
         </c:change>
+        <c:change date="2021-01-24T12:55:01+00:00" summary="Add more convenience methods for scalar elements">
+          <c:tickets>
+            <c:ticket id="2"/>
+          </c:tickets>
+        </c:change>
       </c:changes>
     </c:release>
   </c:releases>
diff --git a/com.io7m.blackthorne.api/pom.xml b/com.io7m.blackthorne.api/pom.xml
index 5347e8c..615bfc0 100644
--- a/com.io7m.blackthorne.api/pom.xml
+++ b/com.io7m.blackthorne.api/pom.xml
@@ -8,7 +8,7 @@
   <parent>
     <artifactId>com.io7m.blackthorne</artifactId>
     <groupId>com.io7m.blackthorne</groupId>
-    <version>1.1.1-SNAPSHOT</version>
+    <version>1.2.0-SNAPSHOT</version>
   </parent>
 
   <artifactId>com.io7m.blackthorne.api</artifactId>
diff --git a/com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/Blackthorne.java b/com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/Blackthorne.java
index 3024ae9..9826549 100644
--- a/com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/Blackthorne.java
+++ b/com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/Blackthorne.java
@@ -276,6 +276,87 @@ public static <S> BTElementHandlerConstructorType<S, List<S>> forListPoly(
       ignoreUnrecognized);
   }
 
+  /**
+   * A convenience function for constructing content handlers that produce a scalar value from the
+   * text content of a single XML element.
+   *
+   * @param elementName The name of the element
+   *
+   * @return A content handler constructor
+   */
+
+  public static BTElementHandlerConstructorType<?, String> forScalarString(
+    final BTQualifiedName elementName)
+  {
+    return forScalar(elementName, (context, characters, offset, length) -> {
+      // CHECKSTYLE:OFF
+      return new String(characters, offset, length);
+      // CHECKSTYLE:ON
+    });
+  }
+
+  /**
+   * A convenience function for constructing content handlers that produce a scalar value from the
+   * text content of a single XML element.
+   *
+   * @param namespaceURI The namespace of the element
+   * @param localName    The local element name
+   *
+   * @return A content handler constructor
+   */
+
+  public static BTElementHandlerConstructorType<?, String> forScalarString(
+    final String namespaceURI,
+    final String localName)
+  {
+    return forScalar(
+      namespaceURI,
+      localName,
+      (context, characters, offset, length) -> {
+        // CHECKSTYLE:OFF
+        return new String(characters, offset, length);
+        // CHECKSTYLE:ON
+      });
+  }
+
+  /**
+   * A convenience function for constructing content handlers that produce a scalar value from the
+   * text content of a single XML element.
+   *
+   * @param elementName The name of the element
+   * @param parser      A function from strings to values of type {@code S}
+   * @param <S>         The type of returned values
+   *
+   * @return A content handler constructor
+   */
+
+  public static <S> BTElementHandlerConstructorType<?, S> forScalarFromString(
+    final BTQualifiedName elementName,
+    final Function<String, S> parser)
+  {
+    return mapConstructor(forScalarString(elementName), parser);
+  }
+
+  /**
+   * A convenience function for constructing content handlers that produce a scalar value from the
+   * text content of a single XML element.
+   *
+   * @param namespaceURI The namespace of the element
+   * @param localName    The local element name
+   * @param parser       A function from strings to values of type {@code S}
+   * @param <S>          The type of returned values
+   *
+   * @return A content handler constructor
+   */
+
+  public static <S> BTElementHandlerConstructorType<?, S> forScalarFromString(
+    final String namespaceURI,
+    final String localName,
+    final Function<String, S> parser)
+  {
+    return mapConstructor(forScalarString(namespaceURI, localName), parser);
+  }
+
   /**
    * A convenience method to configure and execute a parser.
    *
diff --git a/com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/package-info.java b/com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/package-info.java
index 81fbddc..7fa8a09 100644
--- a/com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/package-info.java
+++ b/com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/package-info.java
@@ -19,7 +19,7 @@
  */
 
 @Export
-@Version("1.1.0")
+@Version("1.2.0")
 package com.io7m.blackthorne.api;
 
 import org.osgi.annotation.bundle.Export;
diff --git a/com.io7m.blackthorne.jxe/pom.xml b/com.io7m.blackthorne.jxe/pom.xml
index 6b069a2..6ef07dc 100644
--- a/com.io7m.blackthorne.jxe/pom.xml
+++ b/com.io7m.blackthorne.jxe/pom.xml
@@ -8,7 +8,7 @@
   <parent>
     <artifactId>com.io7m.blackthorne</artifactId>
     <groupId>com.io7m.blackthorne</groupId>
-    <version>1.1.1-SNAPSHOT</version>
+    <version>1.2.0-SNAPSHOT</version>
   </parent>
 
   <artifactId>com.io7m.blackthorne.jxe</artifactId>
diff --git a/com.io7m.blackthorne.tests/pom.xml b/com.io7m.blackthorne.tests/pom.xml
index 9baf51e..24699f2 100644
--- a/com.io7m.blackthorne.tests/pom.xml
+++ b/com.io7m.blackthorne.tests/pom.xml
@@ -8,7 +8,7 @@
   <parent>
     <artifactId>com.io7m.blackthorne</artifactId>
     <groupId>com.io7m.blackthorne</groupId>
-    <version>1.1.1-SNAPSHOT</version>
+    <version>1.2.0-SNAPSHOT</version>
   </parent>
 
   <artifactId>com.io7m.blackthorne.tests</artifactId>
diff --git a/com.io7m.blackthorne.tests/src/test/java/com/io7m/blackthorne/tests/BlackthorneTest.java b/com.io7m.blackthorne.tests/src/test/java/com/io7m/blackthorne/tests/BlackthorneTest.java
index 1580929..811d64a 100644
--- a/com.io7m.blackthorne.tests/src/test/java/com/io7m/blackthorne/tests/BlackthorneTest.java
+++ b/com.io7m.blackthorne.tests/src/test/java/com/io7m/blackthorne/tests/BlackthorneTest.java
@@ -1278,4 +1278,123 @@ public void testLeafIntegerAttr0()
     Assertions.assertEquals(0, this.errors.size());
     Assertions.assertEquals(BigInteger.valueOf(23L), handler.result().get());
   }
+
+  /**
+   * Scalar element handlers work.
+   *
+   * @throws Exception On errors
+   */
+
+  @Test
+  public void testText0()
+    throws Exception
+  {
+    final var handler =
+      BTContentHandler.<String>builder()
+        .addHandler(
+          "urn:tests",
+          "string",
+          Blackthorne.forScalarString("urn:tests", "string"))
+        .build(URI.create("urn:text"), this::logError);
+
+    final var reader = createReader();
+    reader.setContentHandler(handler);
+    reader.setErrorHandler(handler);
+    reader.parse(resource("string.xml"));
+
+    Assertions.assertFalse(handler.failed());
+    Assertions.assertEquals(0, this.errors.size());
+    Assertions.assertEquals("This is some text.", handler.result().get());
+  }
+
+  /**
+   * Scalar element handlers work.
+   *
+   * @throws Exception On errors
+   */
+
+  @Test
+  public void testText1()
+    throws Exception
+  {
+    final var name =
+      BTQualifiedName.of("urn:tests", "string");
+
+    final var handler =
+      BTContentHandler.<String>builder()
+        .addHandler(name, Blackthorne.forScalarString(name))
+        .build(URI.create("urn:text"), this::logError);
+
+    final var reader = createReader();
+    reader.setContentHandler(handler);
+    reader.setErrorHandler(handler);
+    reader.parse(resource("string.xml"));
+
+    Assertions.assertFalse(handler.failed());
+    Assertions.assertEquals(0, this.errors.size());
+    Assertions.assertEquals("This is some text.", handler.result().get());
+  }
+
+  /**
+   * Scalar element handlers work.
+   *
+   * @throws Exception On errors
+   */
+
+  @Test
+  public void testText2()
+    throws Exception
+  {
+    final var handler =
+      BTContentHandler.<Exception>builder()
+        .addHandler(
+          "urn:tests",
+          "string",
+          Blackthorne.forScalarFromString(
+            "urn:tests",
+            "string",
+            Exception::new))
+        .build(URI.create("urn:text"), this::logError);
+
+    final var reader = createReader();
+    reader.setContentHandler(handler);
+    reader.setErrorHandler(handler);
+    reader.parse(resource("string.xml"));
+
+    Assertions.assertFalse(handler.failed());
+    Assertions.assertEquals(0, this.errors.size());
+    Assertions.assertEquals(
+      "This is some text.",
+      handler.result().get().getMessage());
+  }
+
+  /**
+   * Scalar element handlers work.
+   *
+   * @throws Exception On errors
+   */
+
+  @Test
+  public void testText3()
+    throws Exception
+  {
+    final var name =
+      BTQualifiedName.of("urn:tests", "string");
+
+    final var handler =
+      BTContentHandler.<Exception>builder()
+        .addHandler(name, Blackthorne.forScalarFromString(name, Exception::new))
+        .build(URI.create("urn:text"), this::logError);
+
+    final var reader = createReader();
+    reader.setContentHandler(handler);
+    reader.setErrorHandler(handler);
+    reader.parse(resource("string.xml"));
+
+    Assertions.assertFalse(handler.failed());
+    Assertions.assertEquals(0, this.errors.size());
+    Assertions.assertEquals(
+      "This is some text.",
+      handler.result().get().getMessage());
+  }
 }
diff --git a/com.io7m.blackthorne.tests/src/test/resources/com/io7m/blackthorne/tests/choice.xsd b/com.io7m.blackthorne.tests/src/test/resources/com/io7m/blackthorne/tests/choice.xsd
index fe87c61..fd2e9a6 100644
--- a/com.io7m.blackthorne.tests/src/test/resources/com/io7m/blackthorne/tests/choice.xsd
+++ b/com.io7m.blackthorne.tests/src/test/resources/com/io7m/blackthorne/tests/choice.xsd
@@ -5,6 +5,12 @@
             attributeFormDefault="qualified"
             targetNamespace="urn:tests">
 
+  <xsd:element name="string">
+    <xsd:simpleType>
+      <xsd:restriction base="xsd:string"/>
+    </xsd:simpleType>
+  </xsd:element>
+
   <xsd:element name="int">
     <xsd:simpleType>
       <xsd:restriction base="xsd:integer"/>
diff --git a/com.io7m.blackthorne.tests/src/test/resources/com/io7m/blackthorne/tests/string.xml b/com.io7m.blackthorne.tests/src/test/resources/com/io7m/blackthorne/tests/string.xml
new file mode 100644
index 0000000..5048ee2
--- /dev/null
+++ b/com.io7m.blackthorne.tests/src/test/resources/com/io7m/blackthorne/tests/string.xml
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<ts:string xmlns:ts="urn:tests">This is some text.</ts:string>
diff --git a/pom.xml b/pom.xml
index 9a916ed..5f45004 100644
--- a/pom.xml
+++ b/pom.xml
@@ -13,7 +13,7 @@
 
   <groupId>com.io7m.blackthorne</groupId>
   <artifactId>com.io7m.blackthorne</artifactId>
-  <version>1.1.1-SNAPSHOT</version>
+  <version>1.2.0-SNAPSHOT</version>
   <packaging>pom</packaging>
 
   <name>com.io7m.blackthorne</name>
@@ -33,7 +33,7 @@
     <com.io7m.immutables.version>2.7.5</com.io7m.immutables.version>
     <com.io7m.junit.version>5.7.0</com.io7m.junit.version>
     <com.io7m.jxe.version>1.0.0</com.io7m.jxe.version>
-    <io7m.api.previousVersion>1.0.0</io7m.api.previousVersion>
+    <io7m.api.previousVersion>1.1.0</io7m.api.previousVersion>
   </properties>
 
   <licenses>