Merge branch 'release/1.0.0' into master

Release: com.io7m.blackthorne 1.0.0

.github/workflows/main-openjdk_current-linux.yml

@@ -0,0 +1,19 @@
+name: main-openjdk_current-linux
+
+on:
+  push:
+    branches: [ develop, feature/*, release/* ]
+  pull_request:
+    branches: [ develop ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: JDK
+        uses: actions/setup-java@v1
+        with:
+          java-version: 15
+      - name: Build
+        run: mvn --errors clean verify site

.github/workflows/main-openjdk_current-windows.yml

@@ -0,0 +1,19 @@
+name: main-openjdk_current-windows
+
+on:
+  push:
+    branches: [ develop, feature/*, release/* ]
+  pull_request:
+    branches: [ develop ]
+
+jobs:
+  build:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: JDK
+        uses: actions/setup-java@v1
+        with:
+          java-version: 15
+      - name: Build
+        run: mvn --errors clean verify site

.github/workflows/main-openjdk_lts-linux.yml

@@ -0,0 +1,23 @@
+name: main-openjdk_lts-linux
+
+on:
+  push:
+    branches: [ develop, feature/*, release/* ]
+  pull_request:
+    branches: [ develop ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: JDK
+        uses: actions/setup-java@v1
+        with:
+          java-version: 11
+      - name: Build
+        run: mvn --errors clean verify site
+      - name: Coverage
+        uses: codecov/codecov-action@v1
+        with:
+          file: com.io7m.blackthorne.tests/target/site/jacoco/jacoco.xml

README-CHANGES.xml

@@ -1,6 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <c:changelog project="com.io7m.blackthorne" xmlns:c="urn:com.io7m.changelog:4.0">
-  <c:releases/>
+  <c:releases>
+    <c:release date="2020-10-15T14:07:35+00:00" ticket-system="com.github.io7m.blackthorne" version="1.0.0">
+      <c:changes/>
+    </c:release>
+  </c:releases>
   <c:ticket-systems>
     <c:ticket-system default="true" id="com.github.io7m.blackthorne" url="https://www.github.com/io7m/blackthorne/issues/"/>
   </c:ticket-systems>

README.md

@@ -1,11 +1,15 @@
 blackthorne
 ===
 
-[![Travis](https://img.shields.io/travis/io7m/blackthorne.png?style=flat-square)](https://travis-ci.org/io7m/blackthorne)
-[![Maven Central](https://img.shields.io/maven-central/v/com.io7m.blackthorne/com.io7m.blackthorne.png?style=flat-square)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.io7m.blackthorne%22)
+[![Maven Central](https://img.shields.io/maven-central/v/com.io7m.blackthorne/com.io7m.blackthorne.svg?style=flat-square)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.io7m.blackthorne%22)
 [![Maven Central (snapshot)](https://img.shields.io/nexus/s/https/oss.sonatype.org/com.io7m.blackthorne/com.io7m.blackthorne.svg?style=flat-square)](https://oss.sonatype.org/content/repositories/snapshots/com/io7m/blackthorne/)
-[![Codacy grade](https://img.shields.io/codacy/grade/0b143cd2902b46e19be55cc6933e2362.png?style=flat-square)](https://www.codacy.com/app/github_79/blackthorne)
-[![Codecov](https://img.shields.io/codecov/c/github/io7m/blackthorne.png?style=flat-square)](https://codecov.io/gh/io7m/blackthorne)
+[![Codecov](https://img.shields.io/codecov/c/github/io7m/blackthorne.svg?style=flat-square)](https://codecov.io/gh/io7m/blackthorne)
 
 ![blackthorne](./src/site/resources/blackthorne.jpg?raw=true)
 
+| JVM             | Platform | Status |
+|-----------------|----------|--------|
+| OpenJDK LTS     | Linux    | [![Build (OpenJDK LTS, Linux)](https://img.shields.io/github/workflow/status/io7m/blackthorne/main-openjdk_lts-linux)](https://github.com/io7m/blackthorne/actions?query=workflow%3Amain-openjdk_lts-linux) |
+| OpenJDK Current | Linux    | [![Build (OpenJDK Current, Linux)](https://img.shields.io/github/workflow/status/io7m/blackthorne/main-openjdk_current-linux)](https://github.com/io7m/blackthorne/actions?query=workflow%3Amain-openjdk_current-linux)
+| OpenJDK Current | Windows  | [![Build (OpenJDK Current, Windows)](https://img.shields.io/github/workflow/status/io7m/blackthorne/main-openjdk_current-windows)](https://github.com/io7m/blackthorne/actions?query=workflow%3Amain-openjdk_current-windows)
+

com.io7m.blackthorne.api/pom.xml

@@ -8,7 +8,7 @@
   <parent>
     <artifactId>com.io7m.blackthorne</artifactId>
     <groupId>com.io7m.blackthorne</groupId>
-    <version>0.0.5</version>
+    <version>1.0.0</version>
   </parent>
 
   <artifactId>com.io7m.blackthorne.api</artifactId>
@@ -41,6 +41,11 @@
       <artifactId>org.osgi.annotation.bundle</artifactId>
       <scope>provided</scope>
     </dependency>
+    <dependency>
+      <groupId>org.osgi</groupId>
+      <artifactId>org.osgi.annotation.versioning</artifactId>
+      <scope>provided</scope>
+    </dependency>
     <dependency>
       <groupId>org.immutables</groupId>
       <artifactId>value</artifactId>

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/BTException.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright © 2020 Mark Raynsford <code@io7m.com> http://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.api;
+
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * An exception raised by convenience methods.
+ */
+
+public final class BTException extends Exception
+{
+  private final List<BTParseError> errors;
+
+  /**
+   * @return The parse errors encountered during parsing
+   */
+
+  public List<BTParseError> errors()
+  {
+    return this.errors;
+  }
+
+  /**
+   * Construct an exception.
+   *
+   * @param inMessage The exception message
+   * @param inErrors  The parse errors
+   */
+
+  public BTException(
+    final String inMessage,
+    final List<BTParseError> inErrors)
+  {
+    super(Objects.requireNonNull(inMessage, "message"));
+    this.errors = Objects.requireNonNull(inErrors, "errors");
+  }
+
+  /**
+   * Construct an exception.
+   *
+   * @param inMessage The exception message
+   * @param inCause   The cause
+   * @param inErrors  The parse errors
+   */
+
+  public BTException(
+    final String inMessage,
+    final Throwable inCause,
+    final List<BTParseError> inErrors)
+  {
+    super(
+      Objects.requireNonNull(inMessage, "message"),
+      Objects.requireNonNull(inCause, "cause"));
+    this.errors = Objects.requireNonNull(inErrors, "errors");
+  }
+
+  /**
+   * Construct an exception.
+   *
+   * @param inCause  The cause
+   * @param inErrors The parse errors
+   */
+
+  public BTException(
+    final Throwable inCause,
+    final List<BTParseError> inErrors)
+  {
+    super(Objects.requireNonNull(inCause, "cause"));
+    this.errors = Objects.requireNonNull(inErrors, "errors");
+  }
+}

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/BTQualifiedNameType.java

@@ -14,7 +14,6 @@
  * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-
 package com.io7m.blackthorne.api;
 
 import com.io7m.immutables.styles.ImmutablesStyleType;

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/Blackthorne.java

@@ -16,19 +16,36 @@
 
 package com.io7m.blackthorne.api;
 
+import com.io7m.jlexing.core.LexicalPosition;
 import com.io7m.junreachable.UnreachableCodeException;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.xml.sax.InputSource;
+import org.xml.sax.SAXParseException;
+import org.xml.sax.XMLReader;
 
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Optional;
+import java.util.concurrent.Callable;
 import java.util.function.Function;
 
+import static com.io7m.blackthorne.api.BTParseErrorType.Severity.ERROR;
+
 /**
  * Convenience functions.
  */
 
 public final class Blackthorne
 {
+  private static final Logger LOG =
+    LoggerFactory.getLogger(Blackthorne.class);
+
   private Blackthorne()
   {
     throw new UnreachableCodeException();
@@ -198,7 +215,9 @@ public static <S> BTElementHandlerConstructorType<?, S> forScalarAttribute(
     Objects.requireNonNull(namespaceURI, "namespaceURI");
     Objects.requireNonNull(localName, "localName");
     Objects.requireNonNull(parser, "parser");
-    return forScalarAttribute(BTQualifiedName.of(namespaceURI, localName), parser);
+    return forScalarAttribute(
+      BTQualifiedName.of(namespaceURI, localName),
+      parser);
   }
 
   /**
@@ -224,7 +243,11 @@ public static <S> BTElementHandlerConstructorType<S, List<S>> forListMono(
     Objects.requireNonNull(childElementName, "childElementName");
     Objects.requireNonNull(itemHandler, "itemHandler");
     return context ->
-      new BTListMonoHandler<>(elementName, childElementName, itemHandler, ignoreUnrecognized);
+      new BTListMonoHandler<>(
+        elementName,
+        childElementName,
+        itemHandler,
+        ignoreUnrecognized);
   }
 
   /**
@@ -247,6 +270,87 @@ public static <S> BTElementHandlerConstructorType<S, List<S>> forListPoly(
   {
     Objects.requireNonNull(elementName, "elementName");
     Objects.requireNonNull(itemHandlers, "itemHandlers");
-    return context -> new BTListPolyHandler<S>(elementName, itemHandlers, ignoreUnrecognized);
+    return context -> new BTListPolyHandler<S>(
+      elementName,
+      itemHandlers,
+      ignoreUnrecognized);
+  }
+
+  /**
+   * A convenience method to configure and execute a parser.
+   *
+   * @param source       The source URI
+   * @param stream       The input stream
+   * @param xmlReaders   A supplier of XML readers
+   * @param rootElements The root element handlers
+   * @param <T>          The type of returned values
+   *
+   * @return The parsed value
+   *
+   * @throws BTException On parse errors
+   */
+
+  public static <T> T parse(
+    final URI source,
+    final InputStream stream,
+    final Callable<XMLReader> xmlReaders,
+    final Map<BTQualifiedName, BTElementHandlerConstructorType<?, T>> rootElements)
+    throws BTException
+  {
+    final var errors =
+      new ArrayList<BTParseError>(32);
+    final var contentHandler =
+      new BTContentHandler<>(source, errors::add, rootElements);
+
+    try {
+      final var reader = xmlReaders.call();
+      reader.setContentHandler(contentHandler);
+      reader.setErrorHandler(contentHandler);
+
+      final var inputSource = new InputSource(stream);
+      inputSource.setPublicId(source.toString());
+
+      reader.parse(inputSource);
+
+      final var resultOpt = contentHandler.result();
+      if (resultOpt.isEmpty()) {
+        throw new BTException("Parse failed.", new IOException(), errors);
+      }
+
+      return resultOpt.get();
+    } catch (final SAXParseException e) {
+      LOG.error("error encountered during parsing: ", e);
+
+      final var position =
+        LexicalPosition.of(
+          e.getLineNumber(),
+          e.getColumnNumber(),
+          Optional.of(source)
+        );
+
+      errors.add(
+        BTParseError.builder()
+          .setLexical(position)
+          .setSeverity(ERROR)
+          .setMessage(e.getMessage())
+          .build()
+      );
+
+      throw new BTException(e.getMessage(), e, errors);
+    } catch (final Exception e) {
+      LOG.error("error encountered during parsing: ", e);
+
+      final var position =
+        LexicalPosition.of(-1, -1, Optional.of(source));
+
+      errors.add(
+        BTParseError.builder()
+          .setLexical(position)
+          .setSeverity(ERROR)
+          .setMessage(e.getMessage())
+          .build()
+      );
+      throw new BTException(e.getMessage(), e, errors);
+    }
   }
 }

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/package-info.java

@@ -18,5 +18,9 @@
  * Typed XML stream processing (API)
  */
 
-@org.osgi.annotation.bundle.Export
+@Export
+@Version("1.0.0")
 package com.io7m.blackthorne.api;
+
+import org.osgi.annotation.bundle.Export;
+import org.osgi.annotation.versioning.Version;