Release 1.0

Author: GuntherRademacher

README.md

@@ -22,6 +22,16 @@ gradlew clean jar
 
 This creates `build\libs\markup-blitz.jar` which serves the Markup Blitz API. It is also usable as an executable jar for standalone execution.
 
+# Running tests
+
+For running the tests, use this command:
+
+```sh
+gradlew test
+```
+
+Markup Blitz comes with a few tests, but it also passes all of the 3091 tests in the Invisible XML community project [ixml][GHIXML]. For running those as well, make sure that the [ixml][GHIXML] project is available next to the Markup Blitz project and use the above command.
+
 # Markup Blitz in Eclipse
 
 The project can be imported into Eclipse as a Gradle project.
@@ -39,15 +49,19 @@ Usage: java -jar markup-blitz.jar [<OPTION>...] <GRAMMAR> <INPUT>
 
   Compile an Invisible XML grammar, and parse input with the resulting parser.
 
-  <GRAMMAR>          the grammar (file name or URL).
-  <INPUT>            the input (file name or URL).
+  <GRAMMAR>          the grammar (literal, file name or URL), in ixml notation.
+  <INPUT>            the input (literal, file name or URL).
 
-  Options:
-    --verbose, -v    print intermediate results (to standard output).
-    --timing         print timing information (to standard output).
-    --indent, -i     generate resulting xml with indentation.
-    --trace          print parser trace (to standard error).
-    --help, -h, -?   print this information.
+  <OPTION>:
+    --indent         generate resulting xml with indentation.
+    --trace          print parser trace.
+    --timing         print timing information.
+    --verbose        print intermediate results.
+
+  A literal grammar or input must be preceded by an exclamation point (!).
+  All inputs must be presented in UTF-8 encoding, and output is written in
+  UTF-8 as well. Resulting XML goes to standard output, all diagnostics go
+  to standard error.
 ```
 
 # Using the Java API
@@ -73,16 +87,14 @@ public static Parser generate(String grammar, Option... blitzOptions) throws Bli
 Parse the given input.
 
 ```java
-public String parse(String input, Option... options) throws BlitzException
+public String parse(String input, Option... options)
 ```
 **Parameters**:
 - `String input`: the input string
 - `Option options`: options for use at parsing time. If absent, any options passed at generation time will be in effect
 
 **Returns:** `String`: the resulting XML
 
-**Throws:** `BlitzException`: if any error is detected while parsing
-
 ### de.bottlecaps.markup.Blitz.Option
 Either of the `generate` and `parse` methods accepts `Option` arguments for creating extra diagnostic output. Generation time options are passed to the `Parser` object implicitly, and they are used at parsing time, when `parse`is called without any options.
 ```java
@@ -117,6 +129,7 @@ The work in this project was supported by the [BaseX][BaseX] organization.
 [GLR]: https://en.wikipedia.org/wiki/GLR_parser
 [rex-parser-benchmark]: https://github.com/GuntherRademacher/rex-parser-benchmark
 [IXML]: https://invisiblexml.org/
+[GHIXML]: https://github.com/invisibleXML/ixml
 [CFG]: https://en.wikipedia.org/wiki/Context-free_grammar
 [parser]: https://en.wikipedia.org/wiki/Parsing#Parser
 [parse-tree]: https://en.wikipedia.org/wiki/Parse_tree

build.gradle

@@ -4,11 +4,10 @@ plugins {
     id 'signing'
 }
 
-version = '0.7-SNAPSHOT'
+version = '1.0'
 group = 'de.bottlecaps'
 
 repositories {
-    mavenLocal()
     mavenCentral()
 }
 
@@ -50,7 +49,7 @@ void configureMetadata(MavenPublication mavenPublication) {
         pom {
             name = groupId + ':' + artifactId
             description = 'Markup Blitz Parser Generator'
-            url = 'https://bottlecaps.de/markup-blitz'
+            url = 'https://github.com/GuntherRademacher/markup-blitz'
             licenses {
                 license {
                     name = 'Apache-2.0'

src/main/java/de/bottlecaps/markup/Blitz.java

@@ -27,10 +27,10 @@
 public class Blitz {
   /** Generation time and parse time options. */
   public enum Option {
-    /** Print information on intermediate results. */ VERBOSE,
-    /** Print timing information.                  */ TIMING,
     /** Generate XML with indentation.             */ INDENT,
-    /** Print parser trace.                        */ TRACE;
+    /** Print parser trace.                        */ TRACE,
+    /** Print timing information.                  */ TIMING,
+    /** Print information on intermediate results. */ VERBOSE;
   }
 
   /**
@@ -64,7 +64,7 @@ public static Parser generate(String grammar, Blitz.Option... blitzOptions) thro
   }
 
   /**
-   * Generate a parser from an Invisible XML grammar in XML, passed as a String.
+   * Generate a parser from an Invisible XML grammar in XML, passed as an InputStream.
    *
    * @param xml the Invisible XML grammar in XML
    * @param blitzOptions options for use at generation time and parsing time
@@ -103,14 +103,14 @@ public static void main(String[] args) throws IOException {
     Set<Option> options = new HashSet<>();
     int i = 0;
     for (; i < args.length; ++i) {
-      if (args[i].equals("-v") || args[i].equals("--verbose"))
-        options.add(Option.VERBOSE);
-      else if (args[i].equals("-t") || args[i].equals("--trace"))
-        options.add(Option.TRACE);
-      else if (args[i].equals("-i") || args[i].equals("--indent"))
+      if (args[i].equals("--indent"))
         options.add(Option.INDENT);
-      else if (args[i].equals("-?") || args[i].equals("--help"))
-        usage(0);
+      else if (args[i].equals("--trace"))
+        options.add(Option.TRACE);
+      else if (args[i].equals("--timing"))
+        options.add(Option.TIMING);
+      else if (args[i].equals("--verbose"))
+        options.add(Option.VERBOSE);
       else if (args[i].startsWith("-"))
         usage(1);
       else
@@ -144,16 +144,16 @@ private static void usage(int exitCode) {
     System.err.println("  <GRAMMAR>          the grammar (literal, file name or URL), in ixml notation.");
     System.err.println("  <INPUT>            the input (literal, file name or URL).");
     System.err.println();
-    System.err.println("  Options:");
-    System.err.println("    --verbose, -v    print intermediate results (to standard output).");
-    System.err.println("    --timing         print timing information (to standard output).");
-    System.err.println("    --indent, -i     generate resulting xml with indentation.");
-    System.err.println("    --trace          print parser trace (to standard error).");
-    System.err.println("    --help, -h, -?   print this information.");
+    System.err.println("  <OPTION>:");
+    System.err.println("    --indent         generate resulting xml with indentation.");
+    System.err.println("    --trace          print parser trace.");
+    System.err.println("    --timing         print timing information.");
+    System.err.println("    --verbose        print intermediate results.");
     System.err.println();
     System.err.println("  A literal grammar or input must be preceded by an exclamation point (!).");
     System.err.println("  All inputs must be presented in UTF-8 encoding, and output is written in");
-    System.err.println("  UTF-8 as well.");
+    System.err.println("  UTF-8 as well. Resulting XML goes to standard output, all diagnostics go");
+    System.err.println("  to standard error.");
     System.err.println();
     System.exit(exitCode);
   }

src/main/java/de/bottlecaps/markup/BlitzIxmlException.java

@@ -0,0 +1,18 @@
+package de.bottlecaps.markup;
+
+import de.bottlecaps.markup.blitz.Errors;
+
+public class BlitzIxmlException extends BlitzException {
+  private static final long serialVersionUID = 1L;
+
+  private Errors error;
+
+  public BlitzIxmlException(Errors error, String message) {
+    super(message);
+    this.error = error;
+  }
+
+  public Errors getError() {
+    return error;
+  }
+}

src/main/java/de/bottlecaps/markup/blitz/Errors.java

@@ -1,6 +1,6 @@
 package de.bottlecaps.markup.blitz;
 
-import de.bottlecaps.markup.BlitzException;
+import de.bottlecaps.markup.BlitzIxmlException;
 
 public enum Errors {
   S01("Two rules are not separated by at least one whitespace character or comment."),
@@ -33,6 +33,6 @@ public void thro(String... args) {
     String msg = args.length == 0
         ? text
         : text.replaceFirst("\\.$", ": ") + String.join(", ", args) + ".";
-    throw new BlitzException("[" + name() + "] " + msg);
+    throw new BlitzIxmlException(this, "[" + name() + "] " + msg);
   }
 }

src/main/java/de/bottlecaps/markup/blitz/Parser.java

@@ -18,6 +18,7 @@
 
 import de.bottlecaps.markup.Blitz.Option;
 import de.bottlecaps.markup.BlitzException;
+import de.bottlecaps.markup.BlitzIxmlException;
 import de.bottlecaps.markup.BlitzParseException;
 import de.bottlecaps.markup.blitz.codepoints.Codepoint;
 import de.bottlecaps.markup.blitz.codepoints.RangeSet;
@@ -29,6 +30,7 @@
 
 public class Parser
 {
+  public static final String IXML_NAMESPACE = "http://invisiblexml.org/NS";
   private static int STALL_THRESHOLD = 8;
 
   private static class ParseException extends Exception
@@ -173,14 +175,9 @@ public void sendContent(EventHandler e)
     }
 
     public void addChildren(Symbol... newChildren) {
-      if (newChildren == null) {
-        children = newChildren;
-      }
-      else {
-        int length = children.length;
-        children = Arrays.copyOf(children, length + newChildren.length);
-        System.arraycopy(newChildren, 0, children, length, newChildren.length);
-      }
+      int length = children.length;
+      children = Arrays.copyOf(children, length + newChildren.length);
+      System.arraycopy(newChildren, 0, children, length, newChildren.length);
     }
   }
 
@@ -487,9 +484,8 @@ private String lineAndColumn(int pos) {
    * @param input the input string
    * @param options options for use at parsing time. If absent, any options passed at generation time will be in effect
    * @return the resulting XML
-   * @throws BlitzException if any error is detected while parsing
    */
-  public String parse(String input, Option... options) throws BlitzException {
+  public String parse(String input, Option... options) {
     Set<Option> currentOptions = options.length == 0
         ? defaultOptions
         : Set.of(options);
@@ -510,59 +506,71 @@ public String parse(String input, Option... options) throws BlitzException {
     size = input.length();
     maxId = 0;
 
-    ParsingThread thread;
     try {
-      thread = parse();
-    }
-    catch (ParseException pe) {
-      int begin = pe.getBegin();
-      String prefix = input.substring(0, begin);
-      int offending = pe.getOffending();
-      int line = prefix.replaceAll("[^\n]", "").length() + 1;
-      int column = prefix.length() - prefix.lastIndexOf('\n');
-      throw new BlitzParseException(
-          "Failed to parse input:\n" + getErrorMessage(pe),
-          offending >= 0 ? terminal[offending].shortName()
-                         : begin < input.length() ? ("'" + Character.toString(input.codePointAt(begin)) + "'")
-                                                   : "$",
-          line,
-          column
-      );
-    }
-    finally {
-      if (trace) {
-        writeTrace("</trace>\n");
-        try {
-          err.flush();
-        }
-        catch (IOException e) {
-          throw new BlitzException(e);
+      ParsingThread thread;
+      try {
+        thread = parse();
+      }
+      catch (ParseException pe) {
+        int begin = pe.getBegin();
+        String prefix = input.substring(0, begin);
+        int offending = pe.getOffending();
+        int line = prefix.replaceAll("[^\n]", "").length() + 1;
+        int column = prefix.length() - prefix.lastIndexOf('\n');
+        throw new BlitzParseException(
+            "Failed to parse input:\n" + getErrorMessage(pe),
+            offending >= 0 ? terminal[offending].shortName()
+                           : begin < input.length() ? ("'" + Character.toString(input.codePointAt(begin)) + "'")
+                                                     : "$",
+            line,
+            column
+        );
+      }
+      finally {
+        if (trace) {
+          writeTrace("</trace>\n");
+          try {
+            err.flush();
+          }
+          catch (IOException e) {
+          }
         }
+        w.flush();
       }
-      w.flush();
-    }
 
-    Nonterminal startSymbol = ((Nonterminal) b.stack[0]);
-    if (startSymbol.children == null || startSymbol.children.length == 0)
-      Errors.D01.thro(); // not well-formed
-    if (! (startSymbol.children[0] instanceof Nonterminal))
-      Errors.D06.thro(); // not exactly one element
-    Nonterminal nonterminal = (Nonterminal) startSymbol.children[0];
-    if (nonterminal.isAttribute)
-      Errors.D05.thro(); // attribute as root
-    if (startSymbol.children.length != 1)
-      Errors.D06.thro(); // not exactly one element
-
-    if (thread.isAmbiguous || isVersionMismatch) {
-      nonterminal.addChildren(attribute("xmlns:ixml", "http://invisiblexml.org/NS"));
-      List<String> state = new ArrayList<>();
-      if (thread.isAmbiguous)
-        state.add("ambiguous");
-//    if (...)
-//        state.add("stalled");
-      if (isVersionMismatch)
-        state.add("version-mismatch");
-      nonterminal.addChildren(attribute("ixml:state", String.join(" ", state)));
+      Nonterminal startSymbol = ((Nonterminal) b.stack[0]);
+      if (startSymbol.children == null || startSymbol.children.length == 0)
+        Errors.D01.thro(); // not well-formed
+      if (! (startSymbol.children[0] instanceof Nonterminal))
+        Errors.D06.thro(); // not exactly one element
+      Nonterminal nonterminal = (Nonterminal) startSymbol.children[0];
+      if (nonterminal.isAttribute)
+        Errors.D05.thro(); // attribute as root
+      if (startSymbol.children.length != 1)
+        Errors.D06.thro(); // not exactly one element
+
+      if (thread.isAmbiguous || isVersionMismatch) {
+        nonterminal.addChildren(attribute("xmlns:ixml", IXML_NAMESPACE));
+        List<String> state = new ArrayList<>();
+        if (thread.isAmbiguous)
+          state.add("ambiguous");
+        if (isVersionMismatch)
+          state.add("version-mismatch");
+        nonterminal.addChildren(attribute("ixml:state", String.join(" ", state)));
+      }
+    }
+    catch (BlitzIxmlException e) {
+      Nonterminal ixml = new Nonterminal("ixml", new Symbol[] {new Insertion(e.getMessage().codePoints().toArray())});
+      ixml.addChildren(attribute("xmlns:ixml", IXML_NAMESPACE));
+      ixml.addChildren(attribute("ixml:state", "failed"));
+      ixml.addChildren(attribute("ixml:error-code", e.getError().name()));
+      b.stack[0] = new Nonterminal("root", new Symbol[] {ixml});
+    }
+    catch (BlitzException e) {
+      Nonterminal ixml = new Nonterminal("ixml", new Symbol[] {new Insertion(e.getMessage().codePoints().toArray())});
+      ixml.addChildren(attribute("xmlns:ixml", IXML_NAMESPACE));
+      ixml.addChildren(attribute("ixml:state", "failed"));
+      b.stack[0] = new Nonterminal("root", new Symbol[] {ixml});
     }
 
     b.serialize(s);