add ixmlGrammar(), add option FAIL_ON_ERROR

GuntherRademacher · GuntherRademacher · commit 58f5324650c9 · 2023-11-02T20:03:20.000+01:00
diff --git a/README.md b/README.md
@@ -12,49 +12,68 @@ Markup Blitz is an implementation of [Invisible XML][IXML] (ixml). Please see th
 
 # Building Markup Blitz
 
-Use JDK 11 or higher. For building Markup Blitz, use these commands:
+Use JDK 11 or higher. For building Markup Blitz, clone this GitHub repository and go to the resulting directory:
 
 ```sh
 git clone https://github.com/GuntherRademacher/markup-blitz.git
 cd markup-blitz 
+```
+
+Then run this command, on Unix/Linux,
+
+```sh
+./gradlew clean jar
+```
+
+or this one, on Windows
+
+```sh
 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.
+This creates `build/libs/markup-blitz-1.1.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:
+For running the tests, use this command on Unix/Linux,
+
+```sh
+./gradlew test
+```
+
+or this one on Windows:
 
 ```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 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][markup-blitz] project and use the above command.
 
 # Markup Blitz in Eclipse
 
 The project can be imported into Eclipse as a Gradle project.
 
 # Markup Blitz on Maven Central
 
-Markup Blitz is available on Maven Central with groupId `de.bottlecaps` and artifactId `markup-blitz`.
+Markup Blitz is available on [Maven Central][maven-central] with groupId `de.bottlecaps` and artifactId `markup-blitz`.
 
 # Running Markup Blitz from command line
 
 Markup Blitz can be run from command line to process some input according to an Invisible XML grammar:
 
 ```txt
-Usage: java -jar markup-blitz.jar [<OPTION>...] <GRAMMAR> <INPUT>
+Usage: java -jar markup-blitz-1.1.jar [<OPTION>...] [<GRAMMAR>] <INPUT>
 
   Compile an Invisible XML grammar, and parse input with the resulting parser.
 
   <GRAMMAR>          the grammar (literal, file name or URL), in ixml notation.
+                     When omitted, the ixml grammar will be used.
   <INPUT>            the input (literal, file name or URL).
 
   <OPTION>:
     --indent         generate resulting xml with indentation.
     --trace          print parser trace.
+    --fail-on-error  throw an exception instead of returning an error document.
     --timing         print timing information.
     --verbose        print intermediate results.
 
@@ -100,15 +119,19 @@ public String parse(String input, Option... options)
 **Returns:** `String`: the resulting XML
 
 ### 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.
+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
+/** Parser and generator options. */
 public enum Option {
-  /** Print information on intermediate results. */ VERBOSE,
-  /** Print timing information. */                  TIMING,
-  /** Generate XML with indentation. */             INDENT,
-  /** Print parser trace. */                        TRACE;
+  /**    Parser option: Generate XML with indentation.             */ INDENT,
+  /**    Parser option: Print parser trace.                        */ TRACE,
+  /**    Parser option: Fail on parsing error.                     */ FAIL_ON_ERROR,
+  /** Generator option: Print timing information.                  */ TIMING,
+  /** Generator option: Print information on intermediate results. */ VERBOSE;
 }
 ```
+
 # Performance
 
 As with [REx Parser Generator][REx], the goal of Markup Blitz is to provide good performance. In general, however, REx parsers can be expected to perform much better. This is primarily because REx allows separating the specification into tokenization and parsing steps. This is in contrast to Invisible XML, which uses a uniform grammar to resolve from the start symbol down to codepoint level. Separate tokenization enables the use of algorithms optimized for this purpose, the establishment of token termination rules, and the easy accommodation of whitespace rules. Without it, all of this has to be accomplished by the parser alone, which often leads to costly handling of local ambiguities.
@@ -138,5 +161,7 @@ The work in this project was supported by the [BaseX][BaseX] organization.
 [parser]: https://en.wikipedia.org/wiki/Parsing#Parser
 [parse-tree]: https://en.wikipedia.org/wiki/Parse_tree
 [parser-generator]: https://en.wikipedia.org/wiki/Compiler-compiler
-[fnInvisibleXml]: https://github.com/qt4cg/qtspecs/issues/238
+[fnInvisibleXml]: https://qt4cg.org/pr/791/xpath-functions-40/Overview.html#func-invisible-xml
 [BXFiddle]: https://bxfiddle.cloud.basexgmbh.de/
+[markup-blitz]: https://github.com/GuntherRademacher/markup-blitz
+[maven-central]: https://github.com/GuntherRademacher/markup-blitz
diff --git a/src/main/java/de/bottlecaps/markup/Blitz.java b/src/main/java/de/bottlecaps/markup/Blitz.java
@@ -25,18 +25,22 @@
  * @author Gunther Rademacher
  */
 public class Blitz {
-  /** Generation time and parse time options. */
+  /** The ixml grammar resource. */
+  public final static String IXML_GRAMMAR_RESOURCE = "de/bottlecaps/markup/blitz/ixml.ixml";
+
+  /** Parser and generator options. */
   public enum Option {
-    /** Generate XML with indentation.             */ INDENT,
-    /** Print parser trace.                        */ TRACE,
-    /** Print timing information.                  */ TIMING,
-    /** Print information on intermediate results. */ VERBOSE;
+    /**    Parser option: Generate XML with indentation.             */ INDENT,
+    /**    Parser option: Print parser trace.                        */ TRACE,
+    /**    Parser option: Fail on parsing error.                     */ FAIL_ON_ERROR,
+    /** Generator option: Print timing information.                  */ TIMING,
+    /** Generator option: Print information on intermediate results. */ VERBOSE;
   }
 
   /**
    * Generate a parser from an Invisible XML grammar in ixml notation.
    *
-   * @param grammar the Invisible XML grammar in ixml notation
+   * @param grammar the Invisible XML grammar in ixml notation.
    * @param blitzOptions options for use at generation time and parsing time
    * @return the generated parser
    * @throws BlitzException if any error is detected while generating the parser
@@ -117,10 +121,12 @@ else if (args[i].startsWith("-"))
         break;
     }
 
-    if (i != args.length - 2)
+    if (i != args.length - 2 && i != args.length - 1)
       usage(1);
-    String grammar = args[i];
-    String input = args[i + 1];
+    String grammar = i == args.length - 1
+        ? ixmlGrammar()
+        : args[i];
+    String input = args[args.length - 1];
 
     String grammarString = grammar.startsWith("!")
                          ? grammar.substring(1)
@@ -137,16 +143,23 @@ else if (args[i].startsWith("-"))
   }
 
   private static void usage(int exitCode) {
-    System.err.println("Usage: java -jar markup-blitz.jar [<OPTION>...] <GRAMMAR> <INPUT>");
+    String resource = Blitz.class.getResource("/" + Blitz.class.getName().replace('.',  '/') + ".class").toString();
+    final String origin = resource.startsWith("jar:")
+      ? "-jar " + resource.replaceFirst("^.*/([^/]+.jar)!.*$", "$1")
+      : Blitz.class.getName();
+
+    System.err.println("Usage: java " + origin + " [<OPTION>...] [<GRAMMAR>] <INPUT>");
     System.err.println();
     System.err.println("  Compile an Invisible XML grammar, and parse input with the resulting parser.");
     System.err.println();
     System.err.println("  <GRAMMAR>          the grammar (literal, file name or URL), in ixml notation.");
+    System.err.println("                     When omitted, the ixml grammar will be used.");
     System.err.println("  <INPUT>            the input (literal, file name or URL).");
     System.err.println();
     System.err.println("  <OPTION>:");
     System.err.println("    --indent         generate resulting xml with indentation.");
     System.err.println("    --trace          print parser trace.");
+    System.err.println("    --fail-on-error  throw an exception instead of returning an error document.");
     System.err.println("    --timing         print timing information.");
     System.err.println("    --verbose        print intermediate results.");
     System.err.println();
@@ -197,8 +210,21 @@ public static URL url(final String input) {
       return uri.toURL();
     }
     catch (Exception e) {
-      throw new BlitzException("failed to process URL: " + input, e);
+      throw new BlitzException("Failed to process URL: " + input, e);
     }
   }
 
+  /**
+   * Return the ixml grammar as a string.
+   *
+   * @return the ixml grammar
+   */
+  public static String ixmlGrammar() {
+    try {
+      return urlContent(Blitz.class.getClassLoader().getResource(IXML_GRAMMAR_RESOURCE));
+    }
+    catch (IOException e) {
+      throw new BlitzException("Failed to access ixml grammar resource " + IXML_GRAMMAR_RESOURCE, e);
+    }
+  }
 }
diff --git a/src/main/java/de/bottlecaps/markup/blitz/Parser.java b/src/main/java/de/bottlecaps/markup/blitz/Parser.java
@@ -560,27 +560,31 @@ public String parse(String input, Option... options) {
       }
     }
     catch (BlitzIxmlException e) {
+      if (currentOptions.contains(Option.FAIL_ON_ERROR))
+        throw 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) {
+      if (currentOptions.contains(Option.FAIL_ON_ERROR))
+        throw 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});
     }
+    finally {
+      if (currentOptions.contains(Option.TIMING)) {
+        long t1 = System.currentTimeMillis();
+        System.err.println("        ixml parsing time: " + (t1 - t0) + " msec");
+      }
+    }
 
     b.serialize(s);
-    String result = w.toString();
-
-    if (currentOptions.contains(Option.TIMING)) {
-      long t1 = System.currentTimeMillis();
-      System.err.println("        ixml parsing time: " + (t1 - t0) + " msec");
-    }
-    return result;
+    return w.toString();
   }
 
   private Nonterminal attribute(String name, String value) {
diff --git a/src/main/resources/de/bottlecaps/markup/blitz/ixml.ixml b/src/main/resources/de/bottlecaps/markup/blitz/ixml.ixml
diff --git a/src/test/java/de/bottlecaps/markup/BlitzTest.java b/src/test/java/de/bottlecaps/markup/BlitzTest.java
@@ -5,6 +5,7 @@
 
 import java.util.Set;
 
+import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 
 import de.bottlecaps.markup.Blitz.Option;
@@ -109,8 +110,8 @@ public void testCss() {
 
   @Test
   public void testIxml() {
-    Parser parser = generate(resourceContent("ixml.ixml"), Option.INDENT); // , Option.TIMING);
-    String xml = parser.parse(resourceContent("ixml.ixml"));
+    Parser parser = generate(resourceContent(Blitz.IXML_GRAMMAR_RESOURCE), Option.INDENT); // , Option.TIMING);
+    String xml = parser.parse(resourceContent(Blitz.IXML_GRAMMAR_RESOURCE));
     assertEquals(resourceContent("ixml.xml"), xml);
   }
 
@@ -654,6 +655,54 @@ public void testUnicodeVersion() {
         result);
   }
 
+  @Test
+  public void testIxmlGrammar() {
+    Parser parser = generate(Blitz.ixmlGrammar());
+    String result = parser.parse(
+        "S: 'a'.",
+        Option.INDENT);
+    assertEquals(
+          "<ixml>\n"
+        + "   <rule name=\"S\">\n"
+        + "      <alt>\n"
+        + "         <literal string=\"a\"/>\n"
+        + "      </alt>\n"
+        + "   </rule>\n"
+        + "</ixml>",
+        result);
+  }
+
+  @Test
+  public void testErrorDocument() {
+    Parser parser = Blitz.generate("S: 'a'.");
+    String result = parser.parse("b");
+    assertEquals(
+          "<ixml xmlns:ixml=\"http://invisiblexml.org/NS\" ixml:state=\"failed\">Failed to parse input:\n"
+          + "lexical analysis failed\n"
+          + "while expecting 'a'\n"
+          + "at line 1, column 1:\n"
+          + "...b...</ixml>",
+        result);
+  }
+
+  @Test
+  public void testFailOnError() {
+    Parser parser = Blitz.generate("S: 'a'.", Option.FAIL_ON_ERROR);
+    try {
+      String result = parser.parse("b");
+      Assertions.fail("Parse did not fail, returned: \n" + result);
+    }
+    catch (BlitzParseException e) {
+      assertEquals(
+            "Failed to parse input:\n"
+            + "lexical analysis failed\n"
+            + "while expecting 'a'\n"
+            + "at line 1, column 1:\n"
+            + "...b...",
+          e.getMessage());
+    }
+  }
+
 //  @Test
 //  public void test() {
 //    Parser parser = generate(
diff --git a/src/test/java/de/bottlecaps/markup/blitz/grammar/IxmlTest.java b/src/test/java/de/bottlecaps/markup/blitz/grammar/IxmlTest.java
@@ -12,11 +12,11 @@
 import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 
+import de.bottlecaps.markup.Blitz;
 import de.bottlecaps.markup.TestBase;
 
 public class IxmlTest extends TestBase {
     private static final String invisiblexmlOrgUrl = "https://invisiblexml.org/1.0/ixml.ixml";
-    private static final String ixmlResource = "ixml.ixml";
 
     private static final String githubJsonIxmlUrl = "https://raw.githubusercontent.com/GuntherRademacher/rex-parser-benchmark/main/src/main/resources/de/bottlecaps/rex/benchmark/json/parsers/xquery/json.ixml";
     private static final String jsonIxmlResource = "json.ixml";
@@ -26,7 +26,7 @@ public class IxmlTest extends TestBase {
 
     @BeforeAll
     public static void beforeAll() throws URISyntaxException, IOException {
-      ixmlIxmlResourceContent = resourceContent(ixmlResource);
+      ixmlIxmlResourceContent = resourceContent(Blitz.IXML_GRAMMAR_RESOURCE);
       jsonIxmlResourceContent = resourceContent(jsonIxmlResource);
     }
 
@@ -36,7 +36,7 @@ public void testIxmlResource() throws Exception {
       String expectedResult = ixmlIxmlResourceContent
           .replaceAll("^\\{[^\n]*\n", "")
           .replaceAll("\\. \\{[^\n]*\n", ".\n");
-      assertEquals(expectedResult, grammar.toString(), "roundtrip failed for " + ixmlResource);
+      assertEquals(expectedResult, grammar.toString(), "roundtrip failed for " + Blitz.IXML_GRAMMAR_RESOURCE);
     }
 
     @Test
@@ -60,7 +60,7 @@ public void testInvisiblexmlOrgUrlContent() throws Exception {
       String expectedResult = ixmlIxmlResourceContent
           .replaceAll("^\\{[^\n]*\n", "")
           .replaceAll("\\. \\{[^\n]*\n", ".\n");
-      testUrlContent(invisiblexmlOrgUrl, ixmlResource, expectedResult);
+      testUrlContent(invisiblexmlOrgUrl, Blitz.IXML_GRAMMAR_RESOURCE, expectedResult);
     }
 
     private void testUrlContent(String url, String resource, String expectedResult) throws MalformedURLException {
diff --git a/src/test/java/de/bottlecaps/markup/blitz/ixml/IxmlCommunityTest.java b/src/test/java/de/bottlecaps/markup/blitz/ixml/IxmlCommunityTest.java
@@ -43,6 +43,7 @@
 import org.junit.jupiter.params.provider.MethodSource;
 import org.junit.jupiter.params.support.AnnotationConsumer;
 
+import de.bottlecaps.markup.Blitz;
 import de.bottlecaps.markup.BlitzException;
 import de.bottlecaps.markup.TestBase;
 import de.bottlecaps.markup.blitz.Parser;
@@ -359,7 +360,7 @@ private void test(TestCase testCase) {
       assertNull(input, "unexpected input for grammar test " + testCase.getName());
       assertEquals(1, testCase.getOutputs().size(), "expected a single reference output for grammar test");
       if (ixmlParser == null) {
-        String ixmlIxmlResourceContent = resourceContent("ixml.ixml");
+        String ixmlIxmlResourceContent = resourceContent(Blitz.IXML_GRAMMAR_RESOURCE);
         ixmlParser = generate(ixmlIxmlResourceContent);
       }
       String xmlRepresentation = ixmlParser.parse(testCase.getGrammar());
diff --git a/src/test/java/de/bottlecaps/markup/blitz/transform/TestBNF.java b/src/test/java/de/bottlecaps/markup/blitz/transform/TestBNF.java
@@ -14,6 +14,7 @@
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 
+import de.bottlecaps.markup.Blitz;
 import de.bottlecaps.markup.TestBase;
 import de.bottlecaps.markup.blitz.Parser;
 import de.bottlecaps.markup.blitz.codepoints.RangeSet;
@@ -30,15 +31,14 @@
 import de.bottlecaps.markup.blitz.grammar.Term;
 
 public class TestBNF extends TestBase {
-  private static final String ixmlResource = "ixml.ixml";
   private static final String jsonIxmlResource = "json.ixml";
 
   private static String ixmlIxmlResourceContent;
   private static String jsonIxmlResourceContent;
 
   @BeforeAll
   public static void beforeAll() throws URISyntaxException, IOException {
-    ixmlIxmlResourceContent = resourceContent(ixmlResource);
+    ixmlIxmlResourceContent = resourceContent(Blitz.IXML_GRAMMAR_RESOURCE);
     jsonIxmlResourceContent = resourceContent(jsonIxmlResource);
   }
 
diff --git a/src/test/java/de/bottlecaps/markup/blitz/transform/TestCopy.java b/src/test/java/de/bottlecaps/markup/blitz/transform/TestCopy.java
diff --git a/src/test/java/de/bottlecaps/markup/blitz/transform/TestToREx.java b/src/test/java/de/bottlecaps/markup/blitz/transform/TestToREx.java
