Extend Preprocessors to return Readers #1081
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…rocessor. Add method Reader.getLines
Add a Processor method to create a new Reader from a list of source lines.
Update example preprocessor to use newReader().
5363408 to
f9abf6c
Compare
|
Updated the PR with an extension migration guide which documents the necessary changes for existing preprocessors, and updated the docs to let the sample Preprocessor use |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Kind of change
Description
What is the goal of this pull request?
The Asciidoctor API currently allows a preprocessor to return a reader.
The AsciidoctorJ API does not allow this, making certain preprocessors awkward or even impossible.
This PR wants to align the AsciidoctorJ API with the API of Asciidoctor.
How does it achieve that?
I added method to the Processor base class to create new readers.
The Preprocessor API is extended to return a Reader instead of void.
If a preprocessor returns null, or the original reader, the processor proxy returns nil to Asciidoctor.
Otherwise the new Reader is returned.
As a PoC I've implemented the FrontMatterPreprocessor (which does not create a new reader) and the HardBreaksPreprocessor (which does).
Are there any alternative ways to implement this?
I was first considering to allow creation of new Readers directly, but of course that doesn't work in an implementation neutral way, also Reader exposes a complex API and internal state that is not easy to reimplement correctly from scratch for a simple extension.
Are there any implications of this pull request? Anything a user must know?
!!!It's a breaking change! Even recompiling will not work, so this would pull the trigger for a 3.0!!!
Issue
If this PR fixes an open issue, please add a line of the form:
Fixes #Issue
Release notes
Please add a corresponding entry to the file CHANGELOG.adoc