=table.md

Plan for supporting =table in RakuAST

First of all: $=pod will be supported like it is now. This is about the intermediate RakuAST objects that will be used to create the legacy Pod::Block objects in $=pod, which will contain more information so that future renderers have more to work with. And this should also allow for a more truthful deparsing of RakuAST objects.

No special container object

As with all other rakudoc blocks, a =table will be a standard RakuAST::Doc::Block object. But instead of having strings or Rakuast::Doc::Paragraph objects in the paragraphs attribute, it will always be a list of instantiations of special RakuAST::Doc::xxx objects that contain enough information for a reliable deparse (and better to text rendering), and enough information to generate legacy Pod::Block objects out of.

RakuAST::Doc::Row

Contains the following attributes:

• column-dividers the column separator(s) being used ("|" "+" or "")
• column-divider-offsets an array with the positions where dividers occurred
• cells an array of strings with cell contents, keeping newlines

RakuAST::Doc::Divider

Contains the following attributes:

• row-divider the row separator being used ('_', '-', '+', ' ', '|' '='
• width an integer indicating the number of row-divider characters used
• column-dividers the column separator(s) being used (any row divider character or "")
• column-divider-offsets an array with the positions where dividers occurred (can be empty)

A Rakudoc =table such as:

=table :caption<demo>
head1  | head2
===============
col 0A | col 1A
col 0B | col 1B

would be represented in RakuAST as:

Rakuast::Doc::Block.new(
  type       => 'table',
  config     => { :caption<demo> },
  paragraphs => (
    RakuAST::Doc::Row.new(
      column-divider         => '|',
      column-divider-offsets => (7,)
      cells                  => ('head1','head2')
    ),
    RakuAST::Doc::Divider.new(
      row-divider => '=',
      width       => 15
    ),
    RakuAST::Doc::Row.new(
      column-divider         => '|',
      column-divider-offsets => (7,)
      cells                  => ('col 0A','col 1A')
    ),
    RakuAST::Doc::Row.new(
      column-divider         => '|',
      column-divider-offsets => (7,)
      cells                  => ('col 0B','col 1B')
    ),
  )
)

Conversion to legacy Pod::Block objects

The :caption will be stored in the config of the RakuAST::Doc::Block object. Whether the first row becomes a header, is determined by the difference of the row-divider character between the first and second row divider seen.

Notes

An empty column-dividers indicates the use of the invisible column separator. In which case the column-divider-offsets array represents the positions at which columns start.

Otherwise the column-dividers attribute consists of each character found at a column division (without the necessary spaces around it).

An empty line as a row divider will be represented as RakuAST::Doc::Divider.new, that is without even a row-divider or width.