Adding docs for Block Macro Processor positional attributes

asciidoctorj-documentation/build.gradle

@@ -49,6 +49,7 @@ task copyExtensionsExamplesToDocs(type: Copy) {
         include '**/extension/ContextMenuInlineMacroProcessor.java'
         include '**/extension/CopyrightFooterPostprocessor.java'
         include '**/extension/GistBlockMacroProcessor.java'
+        include '**/extension/GistBlockMacroPositionalAttributesProcessor.java'
         include '**/extension/ImageInlineMacroProcessor.java'
         include '**/extension/IssueInlineMacroProcessor.java'
         include '**/extension/IssueInlineMacroPositionalAttributesProcessor.java'
@@ -70,6 +71,7 @@ task copyExtensionsExamplesToDocs(type: Copy) {
         include 'comment-with-note.adoc'
         include 'gist-macro.adoc'
         include 'logging-macro.adoc'
+        include 'gist-macro-attributes.adoc'
         include 'issue-inline-macro.adoc'
         include 'issue-inline-macro-positional.adoc'
         include 'treeprocessorcontent.adoc'

asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/extension/GistBlockMacroPositionalAttributesProcessor.java

@@ -0,0 +1,44 @@
+package org.asciidoctor.integrationguide.extension;
+
+//tag::include[]
+import org.asciidoctor.ast.StructuralNode;
+import org.asciidoctor.extension.BlockMacroProcessor;
+import org.asciidoctor.extension.Name;
+import org.asciidoctor.extension.PositionalAttributes;
+
+import java.util.Map;
+
+@Name("gist")
+@PositionalAttributes({"provider", "repo"})                  // <1>
+public class GistBlockMacroPositionalAttributesProcessor extends BlockMacroProcessor {
+
+    @Override
+    public Object process(StructuralNode parent, String target, Map<String, Object> attributes) {
+
+        String script;
+        String provider = (String) attributes.get("provider");
+        if (provider == null || "github".equals(provider)) { // <2>
+            script = String.format("<script src=\"https://gist.github.com/%s.js\"/></script>", target);
+        } else if ("gitlab".equals(provider)) {
+            String repo = (String) attributes.get("repo");
+            if (repo == null) {
+                script = String.format("<script src=\"https://gitlab.com/-/snippets/%s.js\"></script>", target);
+            } else {
+                script = String.format("<script src=\"https://gitlab.com/%s/-/snippets/%s.js\"></script>", repo, target);
+            }
+        } else {
+            throw new IllegalArgumentException("Unknown provider " + provider);
+        }
+
+        String content = new StringBuilder()
+            .append("<div class=\"openblock gist\">")
+            .append("<div class=\"content\">")
+            .append(script)
+            .append("</div>")
+            .append("</div>").toString();
+
+        return createBlock(parent, "pass", content);
+    }
+
+}
+//end::include[]

asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/extension/GistBlockMacroProcessorTest.java

@@ -1,6 +1,7 @@
 package org.asciidoctor.integrationguide.extension;
 
 import org.asciidoctor.Asciidoctor;
+import org.asciidoctor.Options;
 import org.asciidoctor.OptionsBuilder;
 import org.asciidoctor.util.ClasspathResources;
 import org.jboss.arquillian.junit.Arquillian;
@@ -32,7 +33,7 @@ public void should_create_script_element_for_block_macro() {
 //tag::include[]
         asciidoctor.javaExtensionRegistry().blockMacro(GistBlockMacroProcessor.class);      // <1>
 
-        String result = asciidoctor.convertFile(gistmacro_adoc, OptionsBuilder.options().toFile(false));
+        String result = asciidoctor.convertFile(gistmacro_adoc, Options.builder().toFile(false).build());
 
         assertThat(
                 result,
@@ -41,5 +42,31 @@ public void should_create_script_element_for_block_macro() {
 //end::include[]
     }
 
+    @Test
+    public void should_create_script_element_for_block_macro_with_positional_attributes() {
+
+        File gistmacro_adoc = classpathResources.getResource("gist-macro-attributes.adoc");
+        asciidoctor.javaExtensionRegistry().blockMacro(GistBlockMacroPositionalAttributesProcessor.class);
+
+        String result = asciidoctor.convertFile(gistmacro_adoc, Options.builder().toFile(false).build());
+
+        assertThat(
+                result,
+                containsString(
+                        "<script src=\"https://gist.github.com/myaccount/1234abcd.js\"/></script>"));
+        assertThat(
+                result,
+                containsString(
+                        "<script src=\"https://gitlab.com/-/snippets/2228798.js\"></script>"));
+        assertThat(
+                result,
+                containsString(
+                        "<script src=\"https://gitlab.com/gitlab-org/gitlab-foss/-/snippets/1717978.js\"></script>"));
+        assertThat(
+                result,
+                containsString(
+                        "<script src=\"https://gitlab.com/gitlab-org/gitlab-foss/-/snippets/1717979.js\"></script>"));
+    }
+
 
 }

asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/extension/IssueInlineMacroPositionalAttributesProcessor.java

@@ -21,7 +21,9 @@ public Object process(ContentNode parent, String target, Map<String, Object> att
         String href =
                 new StringBuilder()
                     .append("https://github.com/")
-                    .append(attributes.get("repo"))
+                    .append(attributes.containsKey("repo") ?
+                            attributes.get("repo") :
+                            parent.getDocument().getAttribute("repo"))
                     .append("/issues/")
                     .append(target).toString();
 

asciidoctorj-documentation/src/test/resources/gist-macro-attributes.adoc

@@ -0,0 +1,9 @@
+== Gists
+
+gist::myaccount/1234abcd[]
+
+gist::2228798[gitlab]
+
+gist::1717978[gitlab,gitlab-org/gitlab-foss]
+
+gist::1717979[gitlab,repo=gitlab-org/gitlab-foss]

asciidoctorj-documentation/src/test/resources/issue-inline-macro-positional.adoc

@@ -1,3 +1,4 @@
- = InlineMacroProcessor Test Document
+= InlineMacroProcessor Test Document
+:repo: asciidoctor/asciidoctorj-groovy-dsl
 
-You might want to take a look at the issue issue:334[asciidoctor/asciidoctorj] and issue:3[asciidoctor/asciidoctorj-groovy-dsl].
+You might want to take a look at the issue issue:334[asciidoctor/asciidoctorj] and issue:3[].

docs/modules/extensions/examples/gist-macro-attributes.adoc

@@ -0,0 +1,9 @@
+== Gists
+
+gist::myaccount/1234abcd[]
+
+gist::2228798[gitlab]
+
+gist::1717978[gitlab,gitlab-org/gitlab-foss]
+
+gist::1717979[gitlab,repo=gitlab-org/gitlab-foss]

docs/modules/extensions/examples/org/asciidoctor/integrationguide/extension/GistBlockMacroPositionalAttributesProcessor.java

@@ -0,0 +1,44 @@
+package org.asciidoctor.integrationguide.extension;
+
+//tag::include[]
+import org.asciidoctor.ast.StructuralNode;
+import org.asciidoctor.extension.BlockMacroProcessor;
+import org.asciidoctor.extension.Name;
+import org.asciidoctor.extension.PositionalAttributes;
+
+import java.util.Map;
+
+@Name("gist")
+@PositionalAttributes({"provider", "repo"})                  // <1>
+public class GistBlockMacroPositionalAttributesProcessor extends BlockMacroProcessor {
+
+    @Override
+    public Object process(StructuralNode parent, String target, Map<String, Object> attributes) {
+
+        String script;
+        String provider = (String) attributes.get("provider");
+        if (provider == null || "github".equals(provider)) { // <2>
+            script = String.format("<script src=\"https://gist.github.com/%s.js\"/></script>", target);
+        } else if ("gitlab".equals(provider)) {
+            String repo = (String) attributes.get("repo");
+            if (repo == null) {
+                script = String.format("<script src=\"https://gitlab.com/-/snippets/%s.js\"></script>", target);
+            } else {
+                script = String.format("<script src=\"https://gitlab.com/%s/-/snippets/%s.js\"></script>", repo, target);
+            }
+        } else {
+            throw new IllegalArgumentException("Unknown provider " + provider);
+        }
+
+        String content = new StringBuilder()
+            .append("<div class=\"openblock gist\">")
+            .append("<div class=\"content\">")
+            .append(script)
+            .append("</div>")
+            .append("</div>").toString();
+
+        return createBlock(parent, "pass", content);
+    }
+
+}
+//end::include[]

docs/modules/extensions/examples/org/asciidoctor/integrationguide/extension/LsIncludeProcessor.java

@@ -28,7 +28,7 @@ public void process(Document document,                    // <3>
             sb.append(f.getName()).append("\n");
         }
 
-        reader.push_include(                                  // <4>
+        reader.pushInclude(                                  // <4>
                 sb.toString(),
                 target,
                 new File(".").getAbsolutePath(),

docs/modules/extensions/pages/block-macro-processor.adoc

@@ -39,6 +39,42 @@ Now, once it is registered, we would be able to use the new block macro in our d
 
 [[GistBlockMacroDocument]]
 .gist-macro.adoc
+[source,asciidoc]
 ----
 include::example$gist-macro.adoc[]
-----
+----
+
+== Attributes and Positional attributes
+
+As a next step for the gist macro we might want to add support for Gitlab Snippets, which are a similar system to Github Gists.
+The property whether we want to embed a Github Gist or a Gitlab Snippet can be passed as the first attribute to the macro.
+
+Gitlab Snippets can also be part of a project.
+This project could be accepted as a second attribute.
+
+That way Gists or Snippets could be embedded with our macro with these AsciiDoc block macros:
+
+.gist-marco-attributes.adoc
+[source,asciidoc]
+----
+include::example$gist-macro-attributes.adoc[]
+----
+
+The first macro shows our original notation for how to embed a Github Gist.
+
+The second macro shows how to embed a Snippet from Gitlab that is not associated with a project.
+
+The third macro shows how to embed a Snippet from Gitlab that is associated with the project `gitlab-org/gitlab-foss`.
+
+The last macro shows how to embed a Snippet from Gitlab that is associated with the project `gitlab-org/gitlab-foss` by not using a positional attribute, but instead naming it explicitly.
+
+This can be achieved by the following extension:
+
+.GistBlockMacroPositionalAttributesProcessor
+[source,java]
+----
+include::example$org/asciidoctor/integrationguide/extension/GistBlockMacroPositionalAttributesProcessor.java[tag=include]
+----
+<1> The positional attributes for this are `provider` and `repo` in that order.
+These attributes can be either passed by their position, or by name.
+<2> Based on the values of the two attributes the HTML content to embed the Gist is computed.