Refactor API

Rename com.io7m.blackthorne.api -> com.io7m.blackthorne.core as it is really an implementation module. Add oneOf. Fix: #5
io7m-com · Aug 8, 2023 · 7e7ba41 · 7e7ba41
1 parent 83e28e3
commit 7e7ba41
Show file tree

Hide file tree

Showing 35 changed files with 534 additions and 190 deletions.
diff --git a/com.io7m.blackthorne.api/pom.xml → com.io7m.blackthorne.core/pom.xml b/com.io7m.blackthorne.api/pom.xml → com.io7m.blackthorne.core/pom.xml
@@ -11,10 +11,10 @@
     <version>2.0.0-SNAPSHOT</version>
   </parent>
 
-  <artifactId>com.io7m.blackthorne.api</artifactId>
+  <artifactId>com.io7m.blackthorne.core</artifactId>
 
-  <name>com.io7m.blackthorne.api</name>
-  <description>Typed XML stream processing (API)</description>
+  <name>com.io7m.blackthorne.core</name>
+  <description>Typed XML stream processing (Core)</description>
   <url>https://www.io7m.com/software/blackthorne</url>
 
   <dependencies>

diff --git a/...ckthorne/api/BTAttributesHandlerType.java → ...kthorne/core/BTAttributesHandlerType.java b/...ckthorne/api/BTAttributesHandlerType.java → ...kthorne/core/BTAttributesHandlerType.java
@@ -15,7 +15,7 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
 
 import org.xml.sax.Attributes;
 

diff --git a/...ackthorne/api/BTCharacterHandlerType.java → ...ckthorne/core/BTCharacterHandlerType.java b/...ackthorne/api/BTCharacterHandlerType.java → ...ckthorne/core/BTCharacterHandlerType.java
@@ -15,7 +15,7 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
 
 /**
  * A function that, given a string, returns a {@code T}.

diff --git a/...orne/api/BTContentHandlerBuilderType.java → ...rne/core/BTContentHandlerBuilderType.java b/...orne/api/BTContentHandlerBuilderType.java → ...rne/core/BTContentHandlerBuilderType.java
@@ -14,7 +14,9 @@
  * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
+
+import com.io7m.blackthorne.core.internal.BTContentHandler;
 
 import java.net.URI;
 import java.util.function.Consumer;

diff --git a/.../api/BTElementHandlerConstructorType.java → ...core/BTElementHandlerConstructorType.java b/.../api/BTElementHandlerConstructorType.java → ...core/BTElementHandlerConstructorType.java
@@ -14,7 +14,7 @@
  * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
 
 /**
  * A content handler constructor that produces handlers that produce values of type {@code A}

diff --git a/...blackthorne/api/BTElementHandlerType.java → ...lackthorne/core/BTElementHandlerType.java b/...blackthorne/api/BTElementHandlerType.java → ...lackthorne/core/BTElementHandlerType.java
@@ -15,8 +15,9 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
 
+import com.io7m.blackthorne.core.internal.BTFunctorHandler;
 import org.xml.sax.Attributes;
 
 import java.util.Map;

diff --git a/...orne/api/BTElementParsingContextType.java → ...rne/core/BTElementParsingContextType.java b/...orne/api/BTElementParsingContextType.java → ...rne/core/BTElementParsingContextType.java
@@ -15,7 +15,7 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
 
 import org.xml.sax.SAXParseException;
 import org.xml.sax.ext.Locator2;

diff --git a/...com/io7m/blackthorne/api/BTException.java → ...om/io7m/blackthorne/core/BTException.java b/...com/io7m/blackthorne/api/BTException.java → ...om/io7m/blackthorne/core/BTException.java
@@ -14,7 +14,7 @@
  * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
 
 import java.util.List;
 import java.util.Objects;

diff --git a/...rne/api/BTIgnoreUnrecognizedElements.java → ...ne/core/BTIgnoreUnrecognizedElements.java b/...rne/api/BTIgnoreUnrecognizedElements.java → ...ne/core/BTIgnoreUnrecognizedElements.java
@@ -15,7 +15,7 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
 
 /**
  * A specification of whether or not unrecognized elements should be ignored. For an ignored element

diff --git a/.../com/io7m/blackthorne/api/BTMessages.java → ...com/io7m/blackthorne/core/BTMessages.java b/.../com/io7m/blackthorne/api/BTMessages.java → ...com/io7m/blackthorne/core/BTMessages.java
@@ -14,7 +14,7 @@
  * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
 
 import java.text.MessageFormat;
 import java.util.Objects;
@@ -27,7 +27,7 @@
 public final class BTMessages
 {
   private static final ResourceBundle RESOURCES =
-    ResourceBundle.getBundle("com.io7m.blackthorne.api.Messages");
+    ResourceBundle.getBundle("com.io7m.blackthorne.core.Messages");
 
   private BTMessages()
   {

diff --git a/...om/io7m/blackthorne/api/BTParseError.java → ...m/io7m/blackthorne/core/BTParseError.java b/...om/io7m/blackthorne/api/BTParseError.java → ...m/io7m/blackthorne/core/BTParseError.java
@@ -15,7 +15,7 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
 
 import com.io7m.jlexing.core.LexicalPosition;
 import com.io7m.jlexing.core.LexicalType;

diff --git a/...7m/blackthorne/api/BTPreserveLexical.java → ...m/blackthorne/core/BTPreserveLexical.java b/...7m/blackthorne/api/BTPreserveLexical.java → ...m/blackthorne/core/BTPreserveLexical.java
@@ -15,7 +15,7 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
 
 /**
  * Whether lexical information from the XML parse should be preserved. If

diff --git a/...io7m/blackthorne/api/BTQualifiedName.java → ...o7m/blackthorne/core/BTQualifiedName.java b/...io7m/blackthorne/api/BTQualifiedName.java → ...o7m/blackthorne/core/BTQualifiedName.java
@@ -15,7 +15,7 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core;
 
 import java.net.URI;
 import java.util.Comparator;

diff --git a/...com/io7m/blackthorne/api/Blackthorne.java → ...om/io7m/blackthorne/core/Blackthorne.java b/...com/io7m/blackthorne/api/Blackthorne.java → ...om/io7m/blackthorne/core/Blackthorne.java
@@ -14,8 +14,14 @@
  * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-package com.io7m.blackthorne.api;
-
+package com.io7m.blackthorne.core;
+
+import com.io7m.blackthorne.core.internal.BTContentHandler;
+import com.io7m.blackthorne.core.internal.BTListMonoHandler;
+import com.io7m.blackthorne.core.internal.BTListPolyHandler;
+import com.io7m.blackthorne.core.internal.BTOneOfHandler;
+import com.io7m.blackthorne.core.internal.BTScalarAttributeHandler;
+import com.io7m.blackthorne.core.internal.BTScalarElementHandler;
 import com.io7m.jlexing.core.LexicalPosition;
 import com.io7m.junreachable.UnreachableCodeException;
 import org.slf4j.Logger;
@@ -35,8 +41,6 @@
 import java.util.concurrent.Callable;
 import java.util.function.Function;
 
-import static com.io7m.blackthorne.api.BTParseError.Severity.ERROR;
-
 /**
  * Convenience functions.
  */
@@ -436,7 +440,7 @@ public static <T> T parse(
       errors.add(
         new BTParseError(
           position,
-          ERROR,
+          BTParseError.Severity.ERROR,
           "sax-parse-error",
           e.getMessage(),
           Map.of(),
@@ -454,7 +458,7 @@ public static <T> T parse(
       errors.add(
         new BTParseError(
           position,
-          ERROR,
+          BTParseError.Severity.ERROR,
           "exception",
           e.getMessage(),
           Map.of(),
@@ -465,4 +469,23 @@ public static <T> T parse(
       throw new BTException(e.getMessage(), e, errors);
     }
   }
+
+  /**
+   * A convenience function for constructing content handlers that produce a
+   * value from a child element. Child elements may be of different types, but
+   * values produced by the content handlers for the child elements must have a
+   * common supertype.
+   *
+   * @param itemHandlers Handlers for child elements
+   * @param <S>          The type of returned scalar values
+   *
+   * @return A content handler constructor
+   */
+
+  public static <S> BTElementHandlerConstructorType<S, S> forOneOf(
+    final Map<BTQualifiedName, BTElementHandlerConstructorType<?, ? extends S>> itemHandlers)
+  {
+    Objects.requireNonNull(itemHandlers, "itemHandlers");
+    return context -> new BTOneOfHandler<>(itemHandlers);
+  }
 }
diff --git a/...o7m/blackthorne/api/BTContentHandler.java → ...horne/core/internal/BTContentHandler.java b/...o7m/blackthorne/api/BTContentHandler.java → ...horne/core/internal/BTContentHandler.java
@@ -14,8 +14,13 @@
  * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core.internal;
 
+import com.io7m.blackthorne.core.BTContentHandlerBuilderType;
+import com.io7m.blackthorne.core.BTElementHandlerConstructorType;
+import com.io7m.blackthorne.core.BTParseError;
+import com.io7m.blackthorne.core.BTPreserveLexical;
+import com.io7m.blackthorne.core.BTQualifiedName;
 import com.io7m.jlexing.core.LexicalPosition;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -33,8 +38,8 @@
 import java.util.Optional;
 import java.util.function.Consumer;
 
-import static com.io7m.blackthorne.api.BTParseError.Severity.ERROR;
-import static com.io7m.blackthorne.api.BTParseError.Severity.WARNING;
+import static com.io7m.blackthorne.core.BTParseError.Severity.ERROR;
+import static com.io7m.blackthorne.core.BTParseError.Severity.WARNING;
 
 /**
  * A dispatching handler that produces values of type {@code T}. The handler is responsible for

diff --git a/...o7m/blackthorne/api/BTFunctorHandler.java → ...horne/core/internal/BTFunctorHandler.java b/...o7m/blackthorne/api/BTFunctorHandler.java → ...horne/core/internal/BTFunctorHandler.java
@@ -15,8 +15,13 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core.internal;
 
+import com.io7m.blackthorne.core.BTElementHandlerConstructorType;
+import com.io7m.blackthorne.core.BTElementHandlerType;
+import com.io7m.blackthorne.core.BTElementParsingContextType;
+import com.io7m.blackthorne.core.BTIgnoreUnrecognizedElements;
+import com.io7m.blackthorne.core.BTQualifiedName;
 import org.xml.sax.Attributes;
 
 import java.util.Map;

diff --git a/...7m/blackthorne/api/BTListMonoHandler.java → ...orne/core/internal/BTListMonoHandler.java b/...7m/blackthorne/api/BTListMonoHandler.java → ...orne/core/internal/BTListMonoHandler.java
@@ -15,7 +15,13 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core.internal;
+
+import com.io7m.blackthorne.core.BTElementHandlerConstructorType;
+import com.io7m.blackthorne.core.BTElementHandlerType;
+import com.io7m.blackthorne.core.BTElementParsingContextType;
+import com.io7m.blackthorne.core.BTIgnoreUnrecognizedElements;
+import com.io7m.blackthorne.core.BTQualifiedName;
 
 import java.util.ArrayList;
 import java.util.List;

diff --git a/...7m/blackthorne/api/BTListPolyHandler.java → ...orne/core/internal/BTListPolyHandler.java b/...7m/blackthorne/api/BTListPolyHandler.java → ...orne/core/internal/BTListPolyHandler.java
@@ -15,7 +15,13 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core.internal;
+
+import com.io7m.blackthorne.core.BTElementHandlerConstructorType;
+import com.io7m.blackthorne.core.BTElementHandlerType;
+import com.io7m.blackthorne.core.BTElementParsingContextType;
+import com.io7m.blackthorne.core.BTIgnoreUnrecognizedElements;
+import com.io7m.blackthorne.core.BTQualifiedName;
 
 import java.util.ArrayList;
 import java.util.List;

diff --git a/...o7m.blackthorne.core/src/main/java/com/io7m/blackthorne/core/internal/BTOneOfHandler.java b/...o7m.blackthorne.core/src/main/java/com/io7m/blackthorne/core/internal/BTOneOfHandler.java
@@ -0,0 +1,84 @@
+/*
+ * Copyright © 2019 Mark Raynsford <code@io7m.com> https://www.io7m.com
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+
+package com.io7m.blackthorne.core.internal;
+
+import com.io7m.blackthorne.core.BTElementHandlerConstructorType;
+import com.io7m.blackthorne.core.BTElementHandlerType;
+import com.io7m.blackthorne.core.BTElementParsingContextType;
+import com.io7m.blackthorne.core.BTQualifiedName;
+
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * A convenience handler for constructing content handlers that produce lists of values from the
+ * child elements of a single element. Child elements may be of different types, but values produced
+ * by the content handlers for the child elements must have a common supertype.
+ *
+ * @param <A> The common supertype
+ * @param <B> The type of values produced by child elements
+ */
+
+public final class BTOneOfHandler<A, B extends A>
+  implements BTElementHandlerType<B, A>
+{
+  private final Map<BTQualifiedName, BTElementHandlerConstructorType<?, ? extends B>> itemHandlers;
+  private B childElement;
+
+  @Override
+  public Map<BTQualifiedName, BTElementHandlerConstructorType<?, ? extends B>>
+  onChildHandlersRequested(
+    final BTElementParsingContextType context)
+  {
+    return this.itemHandlers;
+  }
+
+  @Override
+  public String name()
+  {
+    return "[OneOf]";
+  }
+
+  @Override
+  public void onChildValueProduced(
+    final BTElementParsingContextType context,
+    final B result)
+  {
+    this.childElement = Objects.requireNonNull(result, "result");
+  }
+
+  /**
+   * Construct a handler.
+   *
+   * @param inItemHandlers The child item handlers
+   */
+
+  public BTOneOfHandler(
+    final Map<BTQualifiedName, BTElementHandlerConstructorType<?, ? extends B>> inItemHandlers)
+  {
+    this.itemHandlers =
+      Map.copyOf(Objects.requireNonNull(inItemHandlers, "itemHandler"));
+  }
+
+  @Override
+  public A onElementFinished(
+    final BTElementParsingContextType context)
+  {
+    return this.childElement;
+  }
+}
diff --git a/...kthorne/api/BTScalarAttributeHandler.java → ...re/internal/BTScalarAttributeHandler.java b/...kthorne/api/BTScalarAttributeHandler.java → ...re/internal/BTScalarAttributeHandler.java
@@ -15,8 +15,12 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core.internal;
 
+import com.io7m.blackthorne.core.BTAttributesHandlerType;
+import com.io7m.blackthorne.core.BTElementHandlerType;
+import com.io7m.blackthorne.core.BTElementParsingContextType;
+import com.io7m.blackthorne.core.BTQualifiedName;
 import org.xml.sax.Attributes;
 
 import java.util.Objects;

diff --git a/...ackthorne/api/BTScalarElementHandler.java → ...core/internal/BTScalarElementHandler.java b/...ackthorne/api/BTScalarElementHandler.java → ...core/internal/BTScalarElementHandler.java
@@ -15,7 +15,12 @@
  */
 
 
-package com.io7m.blackthorne.api;
+package com.io7m.blackthorne.core.internal;
+
+import com.io7m.blackthorne.core.BTCharacterHandlerType;
+import com.io7m.blackthorne.core.BTElementHandlerType;
+import com.io7m.blackthorne.core.BTElementParsingContextType;
+import com.io7m.blackthorne.core.BTQualifiedName;
 
 import java.util.Objects;