Pod6 表格的官方规范位于文档规范中:表格。虽然 Pod6 规范尚未完全正确处理,但正在进行几个项目来纠正这种情况;其中一个项目是确保正确处理 Pod6 表格。
作为该工作的一部分,本文档通过示例解释了 Pod6 表格的当前状态:有效表格、无效表格和意外表格(即由于构造草率而可能导致与用户预期不同的结果的有效表格)。
限制§
1. 唯一有效的列分隔符是可见的(' | ' 或 ' + ')(注意,在可见列分隔符之前和之后至少需要一个空格)或不可见的 [两个或多个连续的空白字符 (WS)(例如,' ')]。列分隔符通常不会在表格的左侧或右侧被识别为列分隔符,但右侧的列分隔符可能会导致一个或多个空单元格,具体取决于其他行中单元格的数量。(注意,作为单元格数据一部分的管道或加号字符会导致意外的额外列,除非该字符用反斜杠转义,例如,'\|' 或 '\+'。)
2. 在同一个表格中混合使用可见和不可见列分隔符是非法的。
3. 唯一有效的行分隔符字符是 '_', '-', '+', ' ', '|', 和 '='。
4. 连续的内部行分隔符是非法的。
5. 前导和尾随行分隔符会生成警告。
6. 表格单元格中的格式化块目前被忽略并视为纯文本。
提示:在开发过程中,使用环境变量 RAKUDO_POD6_TABLE_DEBUG
将显示 Rakudo 如何解释您的 Pod 表格,然后再将它们传递给渲染器,例如 Pod::To::HTML
、Pod::To::Text
和 Pod::To::Markdown
。
最佳实践§
提示:不遵守以下最佳实践可能需要更多表格处理,因为需要额外循环遍历表格行。
1. 使用 WS 作为列分隔符很脆弱,它们只应用于简单的表格。下面的“丑陋表格”部分说明了这个问题。
2. 仔细对齐表格列和行。请参阅后面最佳实践中的示例。
3. 不要在表格上使用视觉边框。
4. 对于具有标题和单行或多行内容的表格,在标题之后使用一个或多个连续的等号 ('=') 作为行分隔符,并在表格内容部分使用一个或多个连续的连字符 ('-') 作为行分隔符。例如,
标题和单行或多行内容
=begin tablehdr col 0 | hdr col 1======================row 0 | row 0col 0 | col 1----------------------row 1 | row 1col 0 | col 1----------------------=end table
标题和单行内容
=begin tablehdr col 0 | hdr col 1======================row 0 col 0 | row 0 col 1row 1 col 0 | row 1 col 1=end table
5. 对于没有标题和多行内容的表格,在表格内容部分使用一个或多个连续的连字符 ('-') 作为行分隔符。例如,
=begin tablerow 0 | row 0col 0 | col 1----------------------row 1 col 0 | row 1 col 1=end table
6. 对于具有许多行且没有多行内容的表格,不使用行分隔符是可以的。但是,对于具有一个或多个具有多行内容的行,通过在每个内容行之间使用行分隔符(可见或不可见)来确保正确的结果更容易。
7. 确保有意为空的单元格具有列分隔符,否则会收到有关短行用空单元格填充的警告。(表格行始终与具有最多单元格的行具有相同数量的单元格。短行在右侧用空单元格填充,并会生成警告。)
8. 可以使用 =begin table
行将标题添加到表格中,如以下示例所示
=begin table :caption<My Tasks>mow lawntake out trash=end table
虽然不是最佳实践,但目前正在使用一种定义标题的替代方法,如以下示例所示
=begin table :config{caption => "My Tasks"}mow lawntake out trash=end table
请注意,在实现 :caption
方法之前,将标题放在 config
哈希中的替代方法是必要的,但该方法现在被认为已弃用。此做法将在即将发布的 6.d
版本中生成警告,并在 6.e
版本中引发异常。
有效表格§
以下是有效表格的示例(取自当前的 规范测试)。
=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
无效表格§
以下是无效表格的示例,它们应该在解析期间触发未处理的异常。
不允许在同一行中混合使用列分隔符类型
=begin tabler0c0 + r0c1 | r0c3=end table
不允许在同一个表格中混合使用视觉和空格列分隔符类型
=begin tabler0c0 + r0c1 | r0c3r1c0 r0c1 r0c3=end table
不允许使用两个连续的内部行分隔符
=begin tabler0c0 | r0c1========================r1c0 | r1c1=end table
意外表格§
以下是有效表格的示例,它们可能打算为两列,但列未对齐,因此每个表格都将解析为单列表格。
未对齐的列,使用 WS 列分隔符
请注意,第二行中的两个单词仅由 **一个** WS 字符分隔,而定义列分隔符至少需要 **两个** 相邻的 WS 字符。**这是一个有效的表格,但将被解析为单列表格**。
=begin tabler0c0 r0c1r1c0 r0c1=end table
未对齐的列,使用视觉列分隔符
请注意,第二行中的两个单词由一个可见字符 ('|') 分隔,但该字符不被识别为列分隔符,因为它两侧没有相邻的 WS 字符。虽然这是一个合法的表格,但结果将不是用户预期的,因为第一行有两列,而第二行只有一列,因此它将有一个空的第二列。
=begin tabler0c0 | r0c1r1c0 |r0c1=end table