Pod 6 Tables
The Good, the Bad, and the Ugly
The official specification for Perl 6 POD tables is located in the Documentation specification here: Tables. Although Pod 6 specifications are not completely handled properly yet, several projects are ongoing to correct the situation; one such project is ensuring the proper handling of Pod 6 tables.
As part of that effort, this document explains the current state of Pod 6 tables by example: valid tables, invalid tables, and ugly tables (i.e., valid tables that, because of sloppy construction, may result in something different than the user expects).
1. The only valid column separators are either visible (' | ' or ' + ') (note at least one space is required before and after the visible column separators) or invisible [two or more contiguous whitespace (WS) characters (e.g., ' ')].
2. Mixing visible and invisible column separators in the same table is illegal.
3. The only valid row separator characters are '_', '-', '+', ' ', '|', and '='.
4. Consecutive row separator lines are illegal.
1. Use of WS for column separators is fragile, and they should only be used for simple tables. The
Ugly Tables section below illustrates the problem.
2. Align table columns and rows carefully. See the examples in later best practices.
3. For tables with a heading and single- or multi-line content, use one or more contiguous equal signs ('=') as the row separator after the heading, and use one or more contiguous hyphens ('-') as the row separator in the content portion of the table. For example,
Heading and single- or multi-line content
=begin tablehdr col 0 | hdr col 1======================row 0 | row 0col 0 | col 1----------------------row 1 | row 1col 0 | col 1----------------------=end table
Heading and single-line content
=begin tablehdr col 0 | hdr col 1======================row 0 col 0 | row 0 col 1row 1 col 0 | row 1 col 1=end table
4. For tables with no header and multi-line content, use one or more contiguous hyphens ('-') as the row separator in the content portion of the table. For example,
=begin tablerow 0 | row 0col 0 | col 1----------------------row 1 col 0 | row 1 col 1=end table
5. For tables with many rows and no multi-line content, using no row separators is fine. However, with one or more rows with multi-line content, it is easier to ensure proper results by using a row separator line (visible or invisible) between every content row.
Following are examples of valid (Good) tables (taken from the current Specification Tests).
=begin tableThe Shoveller Eddie Stevens King Arthur's singing shovelBlue Raja Geoffrey Smith Master of cutleryMr Furious Roy Orson Ticking time bomb of furyThe Bowler Carol Pinnsler Haunted bowling ball=end table
=tableConstants 1Variables 10Subroutines 33Everything else 57
=for tablemouse | micehorse | horseselephant | elephants
=tableAnimal | Legs | Eats=======================Zebra + 4 + CookiesHuman + 2 + PizzaShark + 0 + Fish
=tableSuperhero | Secret || Identity | Superpower==============|=================|================================The Shoveller | Eddie Stevens | King Arthur's singing shovel
=begin tableSecretSuperhero Identity Superpower============= =============== ===================The Shoveller Eddie Stevens King Arthur'ssinging shovelBlue Raja Geoffrey Smith Master of cutleryMr Furious Roy Orson Ticking time bombof furyThe Bowler Carol Pinnsler Haunted bowling ball=end table
=tableX | O |---+---+---| X | O---+---+---| | X
=tableX O===========X O===========X
=begin tablefoobar=end table
Following are examples of invalid (Bad) tables, and they should trigger an unhandled exception during parsing. They are taken from tests used in the table-pod-fix project mentioned above. After acceptance of the project's code into the Rakudo source, they will be added to the current
Specification Tests. Note they may not trigger an exception at the moment, but they will after the project's code is integrated.
Mixed column separator types in the same row are not allowed:
=begin tabler0c0 + r0c1 | r0c3=end table
Mixed visual and whitespace column separator type in the same table are not allowed:
=begin tabler0c0 + r0c1 | r0c3r1c0 r0c1 r0c3=end table
Two consecutive row separators are not allowed:
=begin tabler0c0 | r0c1========================r1c0 | r1c1=end table
Following are examples of valid tables that are probably intended to be two columns, but the columns are not aligned well so each will parse as a single-column table.
Unaligned columns with WS column separators:
Notice the second row has the two words separated by only one WS character, while it takes at least two adjacent WS characters to define a column separation. This is a valid table but will be parsed as a single-column table.
=begin tabler0c0 r0c1r1c0 r0c1=end table
Unaligned columns with visual column separators:
Notice the second row has the two words separated by a visible character ('|') but the character is not recognized as a column separator because it doesn't have an adjacent WS character on both sides of it. Although this is a legal table, the result will not be what the user intended because the first row has two columns while the second row has only one column, and it will thus have an empty second column.
=begin tabler0c0 | r0c1r1c0 |r0c1=end table