some refactoring deferred error handling in the processor

Author: verhas

.mvn/touch

@@ -1 +1 @@
-000
+1740913148716

README.jrf

@@ -1,5 +1,5 @@
 # This is a Jamal reference file containing serialized base64 encoded macros
-# Created: 2025-02-27 17:32:21 +0100
+# Created: 2025-03-02 11:57:09 +0100
 # id|openStr|closeStr|verbatim|tailParameter|pure|content|parameters
 # TOC
 VE9D|eyU=|JX0=|0|0|0|Ci4gPDxJbnN0YWxsYXRpb24+PgouIDw8R1M+PgouIDw8Q29uZmlndXJhdGlvbj4+Ci4gPDxGZWF0dXJlcz4+Ci4gPDxDb250cmlidXRpbmc+PgouIDw8RG9jdW1lbnRhdGlvbj4+Ci4gPDxMaWNlbnNlPj4KLiA8PENoYW5nZWxvZz4+Ci4gPDxSb2FkbWFwPj4KLiA8PFN1cHBvcnQ+PgouIDw8RkFRPj4KLiA8PE1haW50ZW5hbmNlPj4=|

jamal-api/src/main/java/javax0/jamal/api/BadSyntax.java

@@ -139,6 +139,9 @@ public String getMessage() {
     public interface ThrowingSupplier<T> {
         T get() throws BadSyntax;
     }
+    public interface ThrowingRunnable {
+        void run() throws BadSyntax;
+    }
 
     /**
      * This method throws a {@code BadSyntax} exception when the {@code condition} is {@code true}.

jamal-api/src/main/java/javax0/jamal/api/Macro.java

@@ -42,10 +42,14 @@ interface Escape {
 
     /**
      * A signal interface to be implemented by all macros that implement state.
-     * Implementing state, a.k.a. having a non-static non-final field, is not recommended, but it is possible.
+     * Implementing state, a.k.a. having a non-static non-final field is possible.
      * When a macro is stateful then it has to be annotated using {@link Macro.Stateful}.
      * <p>
      * The use of this macro helps to ensure that the developer is aware of the fact that the macro is stateful.
+     * <p>
+     * The macro loading implementation uses a separate service loader for each processor instance, therefore, it
+     * is guaranteed that the macro object is not shared between processors and hence the state os tied to the
+     * current processor.
      */
     @Target(java.lang.annotation.ElementType.TYPE)
     @Retention(RetentionPolicy.RUNTIME)

jamal-api/src/main/java/javax0/jamal/api/Processor.java

@@ -148,7 +148,7 @@ default UserDefinedMacro newUserDefinedMacro(String id, String input, boolean ve
     /**
      * Register an AutoCloseable closer that has to be closed when the execution is finished.
      * <p>
-     * Some user defined (Java implemented) or built-in macro may create resources that perform some actions
+     * Some user-defined (Java implemented) or built-in macro may create resources that perform some actions
      * asynchronous. The typical example is when a macro that creates some external resource starts a separate thread to
      * execute the task. This task has to be joined at the end of the processing. The general model is that there is a
      * resource that has to be closed. The {@code closer} may be the resource itself or some object that will close the
@@ -181,7 +181,7 @@ default UserDefinedMacro newUserDefinedMacro(String id, String input, boolean ve
      * the input is processed, the invocation of the closers registered in the first round continues. Any closer
      * registered during the call to {@link Processor#process(Input) process(Input)} from a closer will be ignored.
      * <p>
-     * Calling this method the macro can register an {@link AutoCloseable} object. The method {@link
+     * Calling this method, the macro can register an {@link AutoCloseable} object. The method {@link
      * AutoCloseable#close() close()} will be invoked when the method {@link Processor#process(Input)} finishes its top
      * level execution. When the method is called in recursive calls from a macro or from any other place the deferred
      * resources will not be closed upon return, only when the top level call is to be returned.
@@ -191,6 +191,9 @@ default UserDefinedMacro newUserDefinedMacro(String id, String input, boolean ve
      * once. In the order of executions, the first registering is relevant. A closer {@code c2} is treated as already
      * registered if there is a registered closer {@code c1} so that {@code c1.equals(c2)}.
      * <p>
+     * It is important that the closer implemented {@link Object#equals(Object) equals(Object other)} never returns
+     * {@code true} if the {@code other} object is not an instance of the same class.
+     * <p>
      * It also means that any call to this method must use the return value of the method to reference the closer and
      * not the object passed as argument, unless they are the same object. If you pass an object {@code c2} that is
      * {@code c1.equals(c2)} but are not the exact same, then the method will return {@code c1} and the object {@code
@@ -199,19 +202,56 @@ default UserDefinedMacro newUserDefinedMacro(String id, String input, boolean ve
      * This approach was created to allow the macros to create cheap closer objects and call them from the macro
      * evaluation. In this case, the macro can register the closer when it knows that a closer is needed, and it does
      * not need to maintain a state and remember if there was already a closer registered. Also, the closer is not
-     * directly associated with the macro making it possible to register multiple closers assuming they are not
+     * directly associated with the macro, making it possible to register multiple closers assuming they are not
      * equal to each other.
      * <p>
      * Note that this method, or any other method of the processor MUST NOT be invoked from other than the main thread
-     * of the Jamal processing. Even if a macro spawns a new thread the new thread must not do anything with the
+     * of the Jamal processing. Even if a macro spawns a new thread, the new thread must not do anything with the
      * processor.
+     * <p>
+     * The closer has to implement {@link AutoCloseable} and not {@link java.io.Closeable} because
+     * {@link java.io.Closeable} does not allow
+     * checked exceptions, like BadSyntax from the method {@link AutoCloseable#close() close()}.
      *
-     * @param closer the autocloseable object to be closed at the end of the processing.
+     * @param closer the AutoCloseable object to be closed at the end of the processing.
      * @return the registered closer. It may not be the same closer as the argument {@code closer}. If the closer
      * was already registered, then the first registered closer will be returned. More formally, if there was a {@code
      * closer2} already registered such that {@code closer2.equals(closer)} then {@code closer2} will be returned.
      */
-    AutoCloseable deferredClose(AutoCloseable closer);
+    <T extends AutoCloseable> T deferredClose(T closer);
+
+    /**
+     * Create a bad syntax exception and add it to the list of exceptions to be thrown at the end of the processing.
+     * <p>
+     * This is a convenience method proxying {@link #deferredThrow(BadSyntax)}.
+     *
+     * @param errorMessage is the error message used in String format
+     * @param parameters   the parameters to create the error message
+     */
+    void deferredThrow(final String errorMessage, Object... parameters);
+
+    /**
+     * Add the BadSyntax exception to the list of exceptions to be thrown at the end of the processing.
+     * <p>
+     * Call this method instead of throwing a BadSyntax exception whenever further processing of the input is
+     * possible and can be advantageous to discover further syntax errors. That way the user can fix multiple
+     * syntax errors without having to rerun the program with the fixed first error, then the second and so on.
+     * <p>
+     * It is recommended to call {@link #newUserDefinedMacro(String, String, String...)} unless there is a special
+     * need to create the exception on the caller side, for example, adding a cause to the exception.
+     *
+     *
+     * @param bs the BadSyntax to be thrown
+     */
+    void deferredThrow(final BadSyntax bs);
+
+    default void deferBadSyntax(BadSyntax.ThrowingRunnable runner){
+        try{
+            runner.run();
+        }catch(BadSyntax bs){
+            deferredThrow(bs);
+        }
+    }
 
     /**
      * Get the context object that the embedding application was setting. The context object is a general object and the
@@ -369,6 +409,7 @@ interface FileWriter {
          * @return the structure containing the result, which is nothing, or final name
          */
         IOHookResult write(final String fileName, final String content);
+
         IOHookResult write(final String fileName, final byte[] content);
     }
 

jamal-api/src/main/java/javax0/jamal/api/ServiceLoaded.java

@@ -22,31 +22,31 @@
 public interface ServiceLoaded {
 
     /**
-     * Load the classes that implement the interface {@code klass} and are provided by the modules or are available.
+     * Load the classes that implement the interface {@code service} and are provided by the modules or are available.
      *
-     * @param klass the interface for which the implementing class instances are needed
+     * @param service the interface for which the implementing class instances are needed
      * @param <T>   the interface
      * @return the list of instances
      */
-    static <T> List<T> getInstances(Class<T> klass) {
-        final var services =  getInstances(klass, Thread.currentThread().getContextClassLoader());
+    static <T> List<T> getInstances(Class<T> service) {
+        final var services =  getInstances(service, Thread.currentThread().getContextClassLoader());
         if(!services.isEmpty()){
             return services;
         }
-        return getInstances(klass, ServiceLoaded.class.getClassLoader());
+        return getInstances(service, ServiceLoaded.class.getClassLoader());
     }
 
-    static <T> List<T> getInstances(Class<T> klass, final ClassLoader cl) {
+    static <T> List<T> getInstances(Class<T> service, final ClassLoader cl) {
         List<T> list = new ArrayList<>();
         try {
-            final ServiceLoader<T> services = ServiceLoader.load(klass, cl);
+            final ServiceLoader<T> services = ServiceLoader.load(service, cl);
             services.iterator().forEachRemaining(list::add);
             if (list.isEmpty()) {
-                loadViaMetaInf(klass, list, cl);
+                loadViaMetaInf(service, list, cl);
             }
             return list;
         } catch (ServiceConfigurationError ignored) {
-            loadViaMetaInf(klass, list, cl);
+            loadViaMetaInf(service, list, cl);
             return list;
         }
     }

jamal-asciidoc/src/main/java/javax0/jamal/asciidoc/ExceptionDumper.java

@@ -43,6 +43,10 @@ private void dumpIt(Throwable t, boolean printMessage) {
             output.append(t.getMessage());
         }
         for (final var s : t.getStackTrace()) {
+            if (s.getClassName().startsWith("javax0.jamal.engine")) {
+                output.append("\n");
+                break; // we do not need to dump the engine trace or above embedding
+            }
             if (s.getClassName().startsWith("javax0.jamal")) {
                 output.append(String.format("\t%s(%s:%d)\n", s.getClassName(), s.getMethodName(), s.getLineNumber()));
             }

jamal-core/src/main/java/javax0/jamal/builtins/Catch.java

@@ -8,6 +8,7 @@
 import javax0.jamal.tools.Option;
 import javax0.jamal.tools.OptionsStore;
 
+@Macro.Name("catch")
 public class Catch implements Macro {
     @Override
     public String evaluate(Input in, Processor processor) throws BadSyntax {
@@ -22,10 +23,6 @@ public String evaluate(Input in, Processor processor) throws BadSyntax {
         }
     }
 
-    @Override
-    public String getId() {
-        return "catch";
-    }
 }
 /*template jm_catch
 {template |catch|catch $C$|catch an error|

jamal-engine/src/main/java/javax0/jamal/engine/Processor.java

@@ -46,6 +46,7 @@ public class Processor implements javax0.jamal.api.Processor {
     final private JShellEngine shellEngine = getEngine();
     // cannot be a set, you cannot easily retrieve the already stored value when you give a new closer 'equals' the existing
     final private Map<AutoCloseable, AutoCloseable> openResources = new LinkedHashMap<>();
+    final private List<BadSyntax> deferredExceptions = new ArrayList<>();
     private final Context context;
     private final Debugger debugger;
     private final DebuggerStub debuggerStub = new DebuggerStub(this);
@@ -223,6 +224,16 @@ public String process(final Input input) throws BadSyntax {
         return output.toString();
     }
 
+    @Override
+    public void deferredThrow(final String errorMessage, final Object... parameters) {
+        deferredThrow(new BadSyntax(String.format(errorMessage, parameters)));
+    }
+
+    @Override
+    public void deferredThrow(final BadSyntax bs) {
+        deferredExceptions.add(bs);
+    }
+
     /**
      * Handles the closing process of the processor with exception handling.
      * If an exception occurs during the closing process, it is thrown after adding a possibly existing processing
@@ -235,7 +246,13 @@ public String process(final Input input) throws BadSyntax {
     private void closeProcessWithExceptionHandling(javax0.jamal.tools.Input output, BadSyntax processingException) throws BadSyntax {
         try {
             if (limiter.down() == 0) {
-                closeProcess(output);
+                if (deferredExceptions.isEmpty()) {
+                    closeProcess(output);
+                } else {
+                    final var bs = new BadSyntax(String.format("There were %d syntax error(s)", deferredExceptions.size()));
+                    deferredExceptions.forEach(bs::addSuppressed);
+                    throw bs;
+                }
             }
         } catch (Exception e) {
             if (processingException != null) {
@@ -443,7 +460,7 @@ private String evalMacro(final TraceRecord tr, final MacroQualifier qualifier, R
             } catch (BadSyntax bs) {
                 throw new BadSyntaxAt(bs, ref);
             } finally {
-                if( segmentsSize < rf.segment.size() ) {
+                if (segmentsSize < rf.segment.size()) {
                     rf.popSegment();
                 }
             }
@@ -1042,11 +1059,12 @@ public Context getContext() {
     }
 
     @Override
-    public AutoCloseable deferredClose(AutoCloseable closer) {
+    public <T extends AutoCloseable> T deferredClose(T closer) {
         if (!openResources.containsKey(closer)) {
             openResources.put(closer, closer);
         }
-        return openResources.get(closer);
+        //noinspection unchecked
+        return (T) openResources.get(closer);
     }
 
     private static JShellEngine getEngine() {

jamal-extensions/src/main/java/javax0/jamal/extensions/IndexStringTable.java

@@ -30,7 +30,7 @@
  * <pre>
  *     {{#get 1 2 |a/b/c|h/k/j|o/z}}
  * </pre>
- *
+ * <p>
  * will result {@code j} because that is the third element of the second
  * table. (Indexing starts with zero.)
  *
@@ -56,7 +56,9 @@
  * as a separator character on the top level, the second on the next and
  * so on.
  */
-public class IndexStringTable implements Macro {
+@Macro.Name("get")
+public
+class IndexStringTable implements Macro {
     private static final String DEFAULT = "|/:-.";
 
     @Override
@@ -77,7 +79,7 @@ public String evaluate(Input in, Processor processor) throws BadSyntax {
         BadSyntax.when(splitters.length() == 0, "$getsep defines a zero length separator");
         final var input = in.toString();
         final var index = input.indexOf(splitters.charAt(0));
-        BadSyntax.when(index == -1,  "There is no separator '%s' in the input.", splitters.charAt(0));
+        BadSyntax.when(index == -1, "There is no separator '%s' in the input.", splitters.charAt(0));
         final var indices = input.substring(0, index);
         var table = input.substring(index + 1);
         final var indexArray = Arrays.stream(indices.trim().split("\\s+")).mapToInt(Integer::parseInt).map(Math::abs).toArray();
@@ -88,14 +90,10 @@ public String evaluate(Input in, Processor processor) throws BadSyntax {
             final var table_ = table;
             final var i_ = i;
             BadSyntax.when(indexArray[i] >= cols.length, () -> String.format("There are only %d columns in the string \"%s\" using the splitter %s and macro 'get' wants to access %d",
-                            cols.length, table_, splitter, indexArray[i_]));
+                    cols.length, table_, splitter, indexArray[i_]));
             table = cols[indexArray[i]];
         }
         return table;
     }
 
-    @Override
-    public String getId() {
-        return "get";
-    }
 }