search

asciidoctor / asciidoctorj

:coffee: Java bindings for Asciidoctor. Asciidoctor on the JVM!
http://asciidoctor.org
Apache License 2.0
618 stars 172 forks source link

Move the methods related to Ruby from the Asciidoctor API to internals #714

Open ggrossetie opened 5 years ago

ggrossetie commented 5 years ago

Specifically:

I'm not really sure how we should handle this case. If a user want to require a (Ruby) library and/or to get the RubyExtensionRegistry they can cast the Asciidoctor interface to JRubyAsciidoctor and call the methods ? But that mean that they would have to use the asciidoctorj-core module as a "compile" dependency and not a runtime dependency.

Is there a benefit to move all the JRuby related code out of the asciidoctorj-core into a asciidoctorj-jruby ?

mojavelinux commented 5 years ago

This is where the pattern getDelegate() might apply well (like in JPA). We want to step from the generic interface to the vendor-specific interface to access additional implementation-specific methods.

((JRubyAsciidoctor) asciidoctor.getDelegate()).requireLibrary('asciimath')

We could also consider an API where the expected class is passed in:

asciidoctor.getDelegate(JRubyAsciidoctor.class).requireLibrary('asciimath')

If anyone is aware of similar competing patterns, please bring them forward.

robertpanzer commented 5 years ago

asciidoctor.getDelegate(JRubyAsciidoctor.class).requireLibrary('asciimath')

I like this. Or maybe .unwrap() instead of .getDelegate()? 

asciidoctor.unwrap(JRubyAsciidoctor.class).requireLibrary('asciimath')

I wonder though if we should make this change with 2.0 and keep 1.6 compatible with the current build plugins. In particular as we already have the RC out.

mojavelinux commented 5 years ago

Yes, this feels 2.0 to me.

ggrossetie commented 5 years ago

Yep, if you've already released a RC then this change shouldn't be part of the final release. AsciidoctorJ 1.6.0 is a "major" AsciidoctorJ but still based on Asciidoctor (Ruby) 1.5.8 ?

mojavelinux commented 5 years ago

AsciidoctorJ 1.6.0 is a major release for AsciidoctorJ to help the transition to the subsequent AsciidoctorJ 2.0.0 major release. You can think of it as early access to AsciidoctorJ 2.0.0. The reason we're making it is to get feedback on the major API changes and so we can make adjustments to get AsciidoctorJ 2.0.0 right. Trying to do this all in 2.0.0 would just be too much.

I expect the bulk of users will transition directly from AsciidoctorJ 1.5.8 to 2.0.0. But 1.6.0 is there to help them get ready.