[dev] Reorganization of the AsciidoctorJ AST data structures

Hi,

as discussed with Dan and Alex we'd like to clean up the naming of the AST classes a little bit.
I'd like to make an initial proposal as a basis for an open discussion.

One point to pay attention to is the split into an API part and an Impl part of AsciidoctorJ.
This is necessary imo to support alternative implementations like a Nashorn or native Java implementation.

The following table shows the interfaces and classes of the org.asciidoctor.ast package.
The first column shows the current name.
If the class or interface should be renamed a proposed new name is in the second column.
The third column contains the destined part, either API or Impl.
At the same time everything in the API part is an interface, everything in the Impl part is a class.

AbstractNode      -> Node         API
AbstractNodeImpl  -> NodeImpl     Impl

AbstractNode was introduced recently and it's the base for all nodes, blocks as well as inlines etc.
Node probably better hits the point.
I think no one is already using these so it shouldn't be any problem to rename them.

AbstractBlock                     API 
AbstractBlockImpl                 Impl
Block                             API
BlockImpl                         Impl
Section                           API
SectionImpl                       Impl
DocumentRuby      -> Document     API
Document          -> DocumentImpl Impl

Looking back it's probably better to name the document interface `Document` instead of `DocumentRuby`, in particular with a Nashorn imply. ;-)
The document class will be renamed and the interface will jump into this open name.
Some interfaces will change to have Document instead of DocumentRuby in their interface, so this could require some changes in the users of the API.
Nevertheless there will be no changes for extensions because with the new extension proxies in AsciidoctorJ 1.6.0 the process methods carrying the `DocumentRuby` will completely disappear and the existing implementations will now get a `Document` interface instead of class. But that should be even binary compatible.


Inline                            API
InlineImpl                        Impl
ListNode          -> List         API
ListImpl                          Impl
ListItem                          API
ListItemImpl                      Impl


`ListNode` is also new, so no one has used that yet and the renaming should be without any consequences.


Then there are the classes below that are part of a parallel API, where I am quite unsure how much it is actually used.
At the moment these are all classes and I would suggest turning them all to interfaces and create new classes in the Impl part.

ContentPart
Author
DocumentHeader
RevisionInfo
StructuredDocument
Title

Would be awesome to get some feedback on this like how could it be done better, or what breaking changes do you see here that I didn't see.

Best regards,
Robert

Hi Robert,

Great news, I'm looking forward to using this new API !

As you are asking for suggestions and ideas, here is one regarding 'AbstractBlock'.

To me, 'abstract' sounds weird here, as it makes me think of an abstract class, where it is really an interface. Interfaces are always abstract in Java.

I would prefer **BlockNode**.
It aligns better with 'InlineNode' or 'ListNode' ('ListNode extends BlockNode', 'Block extends BlockNode' sounds better than 'ListNode extends AbstractBlock', 'Block extends AbstractBlock').

Cheers
Dominik

Hi Dominik,

Thank you for your feedback.
In particular AbstractBlock was the one that Dan was not really comfortable with.
But it's actually taken from the class names in Ruby :).

What's actuall missing in my first mail is the hierarchy of the interfaces.
It's currently

AbstractNode
  +- AbstractBlock
  |   +- Block
  |   +- Section
  |   +- DocumentRuby
  |   +- ListNode
  |   +- ListItem
  +- Inline

So the current motivation for `Abstract` was that these interfaces are ony implemented by abstract classes.
After renaming AbstractNode to Node, BlockNode would be a good match.
This would result in this hierarchy of interfaces:

Node
  +- BlockNode
  |   +- Block
  |   +- Section
  |   +- Document
  |   +- List
  |   +- ListItem
  +- Inline

What do you think?

Best regards
Robert

Sourds good to me

Hi Robert, I think your work is just what we need in AsciidoctorJ, because currently names can be a bit confusing. and with your changes they are really fitting the intention of them.

About the the parallel structure, I know that some people are using it, so maybe what we could do is first of all set as @deprecated and for1.7.0 simply remove it.

WDYT?

Hi Alex,

Yes, we should definitely keep the StructuredDocument classes in 1.6.
But I wonder if we shouldn't keep them because it provides a view on a document that is hard to get with "real" AST classes.

If we keep this API in he future I'd like to turn them into interfaces though.

Thank you for your feedback!!!

Best regards
Robert

I like the relation to the HTML5 specification! I didn't make that link yet but I think it's a great idea.
The W3C really puts some energy into content structure etc and it shows that our class names are not born of necessity (as today with ListNode but Table;-) ) and plays nicely with adjacent specs.

I am a bit unsure about FlowContent though, because in the HTML5 spec it is a superset of PhrasingContent.
Maybe FlowContent would be a good name for the root node.
(There are only some MetadataContent elements that are not part of FlowContent. Apart from that FlowContent comprises everything.)

HTML5 does not have this term, but what do you think about sth like StructuringContent for what today is the AbstractBlock?
All subclassed like Block, Section, List, Table etc. give the document a structure, whereas PhrasingContent does not.

FlowContent
 +- StructuringContent
 | +- Block
 | +- Section
 | +- Document
 | +- List
 | +- ListItem
 | +- Table
 +- PhrasingNode (or PhrasingContent)

Looking at the HTML5 spec the elements td, th and tr are not mentioned with respect to any of these categories, so naming it FlowContent should be also ok:)

What do you think?

But I also like your idea and could provide a PR for that in the next days.

Best regards
Robert

I also think that Node is easier for beginners and it keeps the connection to the T in AST.
I will provide a PR for this:

FlowNode
 +- StructuralNode
 | +- Block
 | +- Section
 | +- Document
 | +- List
 | +- ListItem
 | +- Table
 +- PhrasingNode