IncludeProcessor: clarification of PreprocessorReader.push_include(..)

[jmini]

I am trying to implement a custom IncludeProcessor and am trying to figure out how PreprocessorReader.push_include(..) is supposed to be used.

asciidoctorj/asciidoctorj-api/src/main/java/org/asciidoctor/extension/PreprocessorReader.java

Lines 7 to 10 in 9955e3a

	public interface PreprocessorReader extends Reader {
	void push_include(String data, String file, String path, int lineNumber, Map<String, Object> attributes);

There is some documentation in the Integrator Guide (Include Processors section).
https://github.com/asciidoctor/asciidoctorj/blob/master/docs/integrator-guide.adoc#include-processors

For the LsIncludeProcessor example:

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

Lines 19 to 37 in 9955e3a

	@Override
	public void process(Document document, // <3>
	PreprocessorReader reader,
	String target,
	Map<String, Object> attributes) {
	StringBuilder sb = new StringBuilder();
	for (File f: new File(".").listFiles()) {
	sb.append(f.getName()).append("\n");
	}
	reader.push_include( // <4>
	sb.toString(),
	target,
	new File(".").getAbsolutePath(),
	1,
	attributes);
	}

The docs says:

<4> Finally the call to the method push_include inserts the contents.
The second and third parameters contain the 'file name' of the include content.
In our example this will be basically the name ls and the path of the current directory.
The parameter 1 is the line number of the first line of the included content.
This makes the most sense when partial content is included.

What I got by reading the code.

• In data all the file-names that must be included
• In file the target is passed "ls" in this case.
• In path the folder absolute path is set
• In attributes the attribute parameter of the process(..) is passed.

I had also a look at the ruby sources.

https://github.com/asciidoctor/asciidoctor/blob/2dbbb04f6cd3c4728a2e24918814e30d642a6305/lib/asciidoctor/reader.rb#L662-L676

---

My questions:

1. What is expected for the 3 first parameters:

• String data
• String file
• String path

2. Can I call reader.push_include(..) multiple times in the same process(..) method?
   It seems that it is working as a stack, so I need to start with the included document that I want to have at the end.

---

Related issues:

• Allow IncludeProcessors to include other files #672
• Includeprocessor to transform a file to asciidoc #770

[jmini]

Ok now I understand better how it works.

The first parameter is the raw AsciiDoc content that will be included.

In my opinion it would be better if the LsIncludeProcessor would do:

        for (File f: new File(".").listFiles()) {
            sb.append("* `").append(f.getName()).append("`\n");
        }

The other parameters (file, path, lineNumber) help asciidoctor to understand what is currently parsed, for example if a warning needs to be reported. Like this:

WARNING: [filename]: line [lineNumber]: [message]

[abelsromero]

Added javadocs in PR #1020. I think we can close this issue.