[DOXIA-756] Allow to customize macro execution

doxia-core/src/main/java/org/apache/maven/doxia/macro/MacroExecutor.java

@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.doxia.macro;
+
+import org.apache.maven.doxia.macro.manager.MacroNotFoundException;
+import org.apache.maven.doxia.sink.Sink;
+
+/**
+ * Interface implemented by all parsers that support macros and which can be used to overwrite macro execution via {@link Parser#setMacroExecutor(MacroExecutor)}.
+ */
+public interface MacroExecutor {
+
+    /**
+     * Execute a macro on the given sink.
+     *
+     * @param macroId an id to lookup the macro
+     * @param request the corresponding MacroRequest
+     * @param sink the sink to receive the events
+     * @throws org.apache.maven.doxia.macro.MacroExecutionException if an error occurred during execution
+     * @throws org.apache.maven.doxia.macro.manager.MacroNotFoundException if the macro could not be found
+     */
+    void executeMacro(String macroId, MacroRequest request, Sink sink)
+            throws MacroExecutionException, MacroNotFoundException;
+}

doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java

@@ -34,6 +34,7 @@
 
 import org.apache.maven.doxia.macro.Macro;
 import org.apache.maven.doxia.macro.MacroExecutionException;
+import org.apache.maven.doxia.macro.MacroExecutor;
 import org.apache.maven.doxia.macro.MacroRequest;
 import org.apache.maven.doxia.macro.manager.MacroManager;
 import org.apache.maven.doxia.macro.manager.MacroNotFoundException;
@@ -49,7 +50,7 @@
  * @author Jason van Zyl
  * @since 1.0
  */
-public abstract class AbstractParser implements Parser {
+public abstract class AbstractParser implements Parser, MacroExecutor {
     /** Indicates that a second parsing is required. */
     private boolean secondParsing = false;
 
@@ -68,6 +69,8 @@ public abstract class AbstractParser implements Parser {
 
     private boolean emitAnchors = false;
 
+    private MacroExecutor macroExecutor = null;
+
     private static final String DOXIA_VERSION;
 
     static {
@@ -127,6 +130,10 @@ public void setEmitAnchorsForIndexableEntries(boolean emitAnchors) {
         this.emitAnchors = emitAnchors;
     }
 
+    @Override
+    public void setMacroExecutor(MacroExecutor macroExecutor) {
+        this.macroExecutor = macroExecutor;
+    }
     /**
      * Execute a macro on the given sink.
      *
@@ -136,13 +143,15 @@ public void setEmitAnchorsForIndexableEntries(boolean emitAnchors) {
      * @throws org.apache.maven.doxia.macro.MacroExecutionException if an error occurred during execution
      * @throws org.apache.maven.doxia.macro.manager.MacroNotFoundException if the macro could not be found
      */
-    // Made public right now because of the structure of the APT parser and
-    // all its inner classes.
+    @Override
     public void executeMacro(String macroId, MacroRequest request, Sink sink)
             throws MacroExecutionException, MacroNotFoundException {
-        Macro macro = getMacroManager().getMacro(macroId);
-
-        macro.execute(sink, request);
+        if (macroExecutor != null) {
+            macroExecutor.executeMacro(macroId, request, sink);
+        } else {
+            Macro macro = getMacroManager().getMacro(macroId);
+            macro.execute(sink, request);
+        }
     }
 
     /**

doxia-core/src/main/java/org/apache/maven/doxia/parser/Parser.java

@@ -21,6 +21,7 @@
 import java.io.Reader;
 
 import org.apache.maven.doxia.index.IndexingSink;
+import org.apache.maven.doxia.macro.MacroExecutor;
 import org.apache.maven.doxia.sink.Sink;
 import org.apache.maven.doxia.sink.impl.SinkWrapperFactory;
 
@@ -110,4 +111,11 @@ public interface Parser {
      * @since 2.0.0
      */
     boolean isEmitAnchorsForIndexableEntries();
+
+    /**
+     * Delegates macro execution to the given {@link MacroExecutor}.
+     * @param macroExecutor (may be {@code null} to use the built-in macro executor, which resolves all macros to {@link Sink} methods)}
+     * @since 2.1.0
+     */
+    void setMacroExecutor(MacroExecutor macroExecutor);
 }

doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptParser.java

@@ -25,7 +25,7 @@
 import java.io.Reader;
 import java.io.StringReader;
 import java.io.StringWriter;
-import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.StringTokenizer;
 
@@ -2405,7 +2405,7 @@ public void traverse() throws AptParseException {
 
             String macroId = params[0];
 
-            Map<String, Object> parameters = new HashMap<>();
+            Map<String, Object> parameters = new LinkedHashMap<>();
 
             for (int i = 1; i < params.length; i++) {
                 String[] param = StringUtils.split(params[i], "=");

doxia-modules/doxia-module-fml/src/main/java/org/apache/maven/doxia/module/fml/FmlParser.java

@@ -28,6 +28,7 @@
 import java.io.StringWriter;
 import java.util.HashMap;
 import java.util.Iterator;
+import java.util.LinkedHashMap;
 import java.util.Map;
 
 import org.apache.commons.io.IOUtils;
@@ -81,7 +82,7 @@ public class FmlParser extends AbstractXmlParser implements FmlMarkup {
     private String macroName;
 
     /** The macro parameters. */
-    private Map<String, Object> macroParameters = new HashMap<>();
+    private Map<String, Object> macroParameters = new LinkedHashMap<>();
 
     /** {@inheritDoc} */
     public void parse(Reader source, Sink sink, String reference) throws ParseException {

doxia-modules/doxia-module-xdoc/src/main/java/org/apache/maven/doxia/module/xdoc/XdocParser.java

@@ -27,6 +27,7 @@
 import java.io.StringReader;
 import java.io.StringWriter;
 import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.Map;
 
 import org.apache.commons.io.IOUtils;
@@ -72,7 +73,7 @@ public class XdocParser extends Xhtml1BaseParser implements XdocMarkup {
     /**
      * The macro parameters.
      */
-    private Map<String, Object> macroParameters = new HashMap<>();
+    private Map<String, Object> macroParameters = new LinkedHashMap<>();
 
     /**
      * Indicates that we're inside &lt;properties&gt; or &lt;head&gt;.

doxia-modules/doxia-module-xhtml5/src/main/java/org/apache/maven/doxia/module/xhtml5/Xhtml5Parser.java

@@ -26,7 +26,7 @@
 import java.io.Reader;
 import java.io.StringReader;
 import java.io.StringWriter;
-import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.Map;
 
 import org.apache.commons.io.IOUtils;
@@ -194,7 +194,7 @@ private void processMacro(String text, Sink sink) throws XmlPullParserException
         String[] params = StringUtils.split(s, "|");
         String macroName = params[0];
 
-        Map<String, Object> parameters = new HashMap<>();
+        Map<String, Object> parameters = new LinkedHashMap<>();
         for (int i = 1; i < params.length; i++) {
             String[] param = StringUtils.split(params[i], "=");
             if (param.length == 1) {