allow subclasses to modify included content in an easy way

[johannesjh]

Hi, thank you for this nice and clean extension!

Can we make it easier for subclasses to modify the content to be included? I can offer a pull request for it. Which solution would you prefer?

Background:
I wrote the asciidoctor-indir_ext extension based on this extension. My extension adds lines at the beginning and end of included content, based information from the document and reader objects.

Problems and Proposed Solutions:

• Problem A: Overriding read_lines seems to be the obvious way to go. But I cannot access the document and reader objects from within this method. (And I cannot simply set member variables because the include extension gets frozen by asciidoctor; the current implementation of my extension has an ugly workaround for this).

  • Proposed solution A:
    Pass the arguments that were received by the process method to the submethods, for example in a single hash object process_args to avoid cluttering the method signatures:

    def process(document, reader, target, attributes)
      process_args = {
        'document': document,
        'reader': reader,
        'target': target,
        'attributes': attributes
      }
      # ...
      lines = read_lines(path, selector, process_args)

• Problem B: Overridingprocess instead of read_lines would allow my extension to access the document and reader objects, but would need a lot of code duplication. To ease overriding, it would be better if the method was split into smaller methods and/or if it included a method preprocess_lines that could be overridden by subclasses.

  • Proposed solution B: Add and call an additional method

    def preprocess_lines (lines, process_args)
      return lines

    As shown above, the preprocess_lines method can simply be implemented as identity function in asciidoctor-indir_ext, allowing subclasses to override the method.

Personally, I think solution A would be the most simple and elegant.