Pod6 表格的官方规范位于文档规范中:表格。虽然 Pod6 规范尚未完全正确处理,但正在进行几个项目来纠正这种情况;其中一个项目是确保正确处理 Pod6 表格。

作为该工作的一部分,本文档通过示例解释了 Pod6 表格的当前状态:有效表格、无效表格和意外表格(即由于构造草率而可能导致与用户预期不同的结果的有效表格)。

限制§

1. 唯一有效的列分隔符是可见的(' | ' 或 ' + ')(注意,在可见列分隔符之前和之后至少需要一个空格)或不可见的 [两个或多个连续的空白字符 (WS)(例如,'  ')]。列分隔符通常不会在表格的左侧或右侧被识别为列分隔符,但右侧的列分隔符可能会导致一个或多个空单元格,具体取决于其他行中单元格的数量。(注意,作为单元格数据一部分的管道或加号字符会导致意外的额外列,除非该字符用反斜杠转义,例如,'\|' 或 '\+'。)

2. 在同一个表格中混合使用可见和不可见列分隔符是非法的。

3. 唯一有效的行分隔符字符是 '_', '-', '+', ' ', '|', 和 '='。

4. 连续的内部行分隔符是非法的。

5. 前导和尾随行分隔符会生成警告。

6. 表格单元格中的格式化块目前被忽略并视为纯文本。

提示:在开发过程中,使用环境变量 RAKUDO_POD6_TABLE_DEBUG 将显示 Rakudo 如何解释您的 Pod 表格,然后再将它们传递给渲染器,例如 Pod::To::HTMLPod::To::TextPod::To::Markdown

最佳实践§

提示:不遵守以下最佳实践可能需要更多表格处理,因为需要额外循环遍历表格行。

1. 使用 WS 作为列分隔符很脆弱,它们只应用于简单的表格。下面的“丑陋表格”部分说明了这个问题。

2. 仔细对齐表格列和行。请参阅后面最佳实践中的示例。

3. 不要在表格上使用视觉边框。

4. 对于具有标题和单行或多行内容的表格,在标题之后使用一个或多个连续的等号 ('=') 作为行分隔符,并在表格内容部分使用一个或多个连续的连字符 ('-') 作为行分隔符。例如,

  • 标题和单行或多行内容

=begin table
 hdr col 0 | hdr col 1
 ======================
 row 0     | row 0
 col 0     | col 1
 ----------------------
 row 1     | row 1
 col 0     | col 1
 ----------------------
=end table
  • 标题和单行内容

=begin table
 hdr col 0   | hdr col 1
 ======================
 row 0 col 0 | row 0 col 1
 row 1 col 0 | row 1 col 1
=end table

5. 对于没有标题和多行内容的表格,在表格内容部分使用一个或多个连续的连字符 ('-') 作为行分隔符。例如,

=begin table
 row 0       | row 0
 col 0       | col 1
 ----------------------
 row 1 col 0 | row 1 col 1
=end table

6. 对于具有许多行且没有多行内容的表格,不使用行分隔符是可以的。但是,对于具有一个或多个具有多行内容的行,通过在每个内容行之间使用行分隔符(可见或不可见)来确保正确的结果更容易。

7. 确保有意为空的单元格具有列分隔符,否则会收到有关短行用空单元格填充的警告。(表格行始终与具有最多单元格的行具有相同数量的单元格。短行在右侧用空单元格填充,并会生成警告。)

8. 可以使用 =begin table 行将标题添加到表格中,如以下示例所示

=begin table :caption<My Tasks>
mow lawn
take out trash
=end table

虽然不是最佳实践,但目前正在使用一种定义标题的替代方法,如以下示例所示

=begin table :config{caption => "My Tasks"}
mow lawn
take out trash
=end table

请注意,在实现 :caption 方法之前,将标题放在 config 哈希中的替代方法是必要的,但该方法现在被认为已弃用。此做法将在即将发布的 6.d 版本中生成警告,并在 6.e 版本中引发异常。

有效表格§

以下是有效表格的示例(取自当前的 规范测试)。

=begin table
        The Shoveller   Eddie Stevens     King Arthur's singing shovel
        Blue Raja       Geoffrey Smith    Master of cutlery
        Mr Furious      Roy Orson         Ticking time bomb of fury
        The Bowler      Carol Pinnsler    Haunted bowling ball
=end table
=table
    Constants           1
    Variables           10
    Subroutines         33
    Everything else     57
=for table
    mouse    | mice
    horse    | horses
    elephant | elephants
=table
    Animal | Legs |    Eats
    =======================
    Zebra  +   4  + Cookies
    Human  +   2  +   Pizza
    Shark  +   0  +    Fish
=table
        Superhero     | Secret          |
                      | Identity        | Superpower
        ==============|=================|================================
        The Shoveller | Eddie Stevens   | King Arthur's singing shovel
=begin table
 
                        Secret
        Superhero       Identity          Superpower
        =============   ===============   ===================
        The Shoveller   Eddie Stevens     King Arthur's
                                          singing shovel
 
        Blue Raja       Geoffrey Smith    Master of cutlery
 
        Mr Furious      Roy Orson         Ticking time bomb
                                          of fury
 
        The Bowler      Carol Pinnsler    Haunted bowling ball
=end table
=table
    X | O |
   ---+---+---
      | X | O
   ---+---+---
      |   | X
=table
    X   O
   ===========
        X   O
   ===========
            X
=begin table
 
foo
bar
 
=end table

无效表格§

以下是无效表格的示例,它们应该在解析期间触发未处理的异常。

  • 不允许在同一行中混合使用列分隔符类型

=begin table
r0c0 +  r0c1 | r0c3
=end table
  • 不允许在同一个表格中混合使用视觉和空格列分隔符类型

=begin table
r0c0 +  r0c1 | r0c3
r1c0    r0c1   r0c3
=end table
  • 不允许使用两个连续的内部行分隔符

=begin table
r0c0 |  r0c1
============
============
r1c0 |  r1c1
=end table

意外表格§

以下是有效表格的示例,它们可能打算为两列,但列未对齐,因此每个表格都将解析为单列表格。

  • 未对齐的列,使用 WS 列分隔符

请注意,第二行中的两个单词仅由 **一个** WS 字符分隔,而定义列分隔符至少需要 **两个** 相邻的 WS 字符。**这是一个有效的表格,但将被解析为单列表格**。

=begin table
r0c0    r0c1
 r1c0 r0c1
=end table
  • 未对齐的列,使用视觉列分隔符

请注意,第二行中的两个单词由一个可见字符 ('|') 分隔,但该字符不被识别为列分隔符,因为它两侧没有相邻的 WS 字符。虽然这是一个合法的表格,但结果将不是用户预期的,因为第一行有两列,而第二行只有一列,因此它将有一个空的第二列。

=begin table
r0c0  |  r0c1
 r1c0 |r0c1
=end table