e dot dot dot

home << Programming << Perl << auto three ways to write a table in podlite

Thu, 16 Jul 2026

Three ways to write a table in Podlite
Furnished content.

In my previous article I introduced Podlite as a block-based markup language. Today I’ll zoom into one piece: tables.I write tables in three rough shapes: a few rows of words I’m jotting down, a visual grid like a tic-tac-toe board, or a data export I want to embed in a document. Podlite has three syntaxes around the same model, one per shape. The first has several flavors, so let’s start with that.

One model, three syntaxes

The first syntax is text-mode. It’s flexible. The simplest version is =table followed by rows. Pipes for separators:

=table    mouse    | mice    horse    | horses    elephant | elephants

Plurals rendered as a two-column table. Pipes mark column boundaries; no header.

Plus signs work too, and you can leave cells empty:

=table    X | O |   ---+---+---      | X | O   ---+---+---      |   | X

Tic-tac-toe board rendered as a 33 grid. Empty cells preserved; horizontal separators (+—+—+) mark row boundaries.

That renders as a tic-tac-toe board. Three rows of three cells, same table model as anything else.When you want a header and a caption, use the delimited form. Add :caption(...) and put a ===== row under the head:

=begin table :caption('Critters')    Animal     Legs    Eats    ======     ====    ====    Zebra      4       Cookies    Human      2       Pizza    Shark      0       Fish=end table

Critters rendered with bold header and caption. The ===== row marks the previous row as a semantic header.

The parser handles whitespace, pipes, or plus signs as column boundaries. A ===== line marks the previous row as a header. I reach for this form first when I’m typing into a notebook. It stays readable as I edit, and it survives copy-paste from a terminal.The second syntax is structured. Use it when you need cell spans, semantic markup, or rich content in cells. Each row and each cell becomes its own block. The ===== line becomes a :header attribute on the row:

=begin table :caption('My coffee morning')=begin row :header=cell Step=cell Tool=cell Time=end row=begin row=cell Grind=cell Burr grinder=cell 20s=end row=begin row=cell Brew=for cell :colspan(2)Aeropress, 90 seconds with bloom=end row=end table

My coffee morning rendered as a structured table. The Brew step spans the Tool and Time columns via :colspan(2).

A cell can hold any Podlite block: a paragraph, a code block, a picture, an embedded diagram. This call was made early in the spec: tables in Podlite are not a visual feature, they are containers that render as a grid.The third syntax is data-driven. If the numbers are short enough to live in the document, put them directly inside a =data-table block:

=begin data-table :caption('Build status') :mime-type<'text/csv; header=present'>component,statusparser,greenrenderer,greenplayground,yellow=end data-table

Build status rendered from inline CSV. The =data-table body holds the data; header=present marks the first row as a header.

Some data has its own life: a CSV export, a TSV log, anything that exists before the document does. Keep it in a separate =data block and reference it via :src. If the data starts with column labels, mark them with the header=present parameter from RFC 4180 3:

=for data-table :src<data:walks> :caption('Walks this month')=begin data :key<walks> :mime-type<'text/tab-separated-values; header=present'>datedistancenote2026-04-125kmmorning fog2026-04-153kmpark loop2026-04-228kmcoastal trail=end data

Walks this month rendered with a semantic header. The date/distance/note row is marked via the header=present parameter from RFC 4180 3.

The =data block holds raw TSV: tab-split, no quoting, which is what most TSV tools emit. Tools that walk the document read the structured data directly, and readers see the rendered table from the same source.

When tables break

Tables break in real documents. A copy-paste loses a column, two rows pick different separators, a CSV cell holds an unmatched quote. The Podlite spec defines four rules so the parser warns you instead of silently corrupting the document:

Per-line separator detection. Each row decides its separator from what it sees.
Cell count validation. Short rows pad with empty cells, long rows truncate. Both produce a warning.
Mixed-separator warning. Pipes in the header and whitespace in data still work, but you get a warning.
CSV recovery. Missing data renders an empty table. A non-CSV MIME type falls back to a =code block so the content stays visible.

I’d rather see a warning in the console than ship a document with a dropped row.

Try it

Paste any of these examples into pod6.in. The playground renders Podlite live, no install needed. The full table grammar lives in the Podlite specification.If you build something with this, or hit a case the spec does not cover, open a discussion at podlite-specs.Thanks for reading,Alex

Read more here

edit: Programming/Perl/auto___three_ways_to_write_a_table_in_podlite.wikieditish...

Password:

Title:

Body:

Furnished content.

In my <a href="https://www.perl.com/article/podlite-comes-to-perl-a-lightweight-block-based-markup-language-for-everyday-use/">previous article</a> I introduced Podlite as a block-based markup language. Today I’ll zoom into one piece: tables.I write tables in three rough shapes: a few rows of words I’m jotting down, a visual grid like a tic-tac-toe board, or a data export I want to embed in a document. Podlite has three syntaxes around the same model, one per shape. The first has several flavors, so let’s start with that.<h2 id="one-model-three-syntaxes">One model, three syntaxes</h2>The first syntax is text-mode. It’s flexible. The simplest version is <code>=table</code> followed by rows. Pipes for separators:<pre tabindex="0"><code class="language-podlite" data-lang="podlite">=table    mouse    | mice    horse    | horses    elephant | elephants</code></pre><img height=400 width=500 src="https://www.perl.com/images/three-ways-to-write-a-table-in-podlite/01-plurals.png" alt="Plurals rendered as a two-column table. Pipes mark column boundaries; no header.">Plus signs work too, and you can leave cells empty:<pre tabindex="0"><code class="language-podlite" data-lang="podlite">=table    X | O |   ---+---+---      | X | O   ---+---+---      |   | X</code></pre><img height=400 width=500 src="https://www.perl.com/images/three-ways-to-write-a-table-in-podlite/02-tic-tac-toe.png" alt="Tic-tac-toe board rendered as a 33 grid. Empty cells preserved; horizontal separators (+—+—+) mark row boundaries.">That renders as a tic-tac-toe board. Three rows of three cells, same table model as anything else.When you want a header and a caption, use the delimited form. Add <code>:caption(...)</code> and put a <code>=====</code> row under the head:<pre tabindex="0"><code class="language-podlite" data-lang="podlite">=begin table :caption('Critters')    Animal     Legs    Eats    ======     ====    ====    Zebra      4       Cookies    Human      2       Pizza    Shark      0       Fish=end table</code></pre><img height=400 width=500 src="https://www.perl.com/images/three-ways-to-write-a-table-in-podlite/03-critters.png" alt="Critters rendered with bold header and caption. The ===== row marks the previous row as a semantic header.">The parser handles whitespace, pipes, or plus signs as column boundaries. A <code>=====</code> line marks the previous row as a header. I reach for this form first when I’m typing into a notebook. It stays readable as I edit, and it survives copy-paste from a terminal.The second syntax is structured. Use it when you need cell spans, semantic markup, or rich content in cells. Each row and each cell becomes its own block. The <code>=====</code> line becomes a <code>:header</code> attribute on the row:<pre tabindex="0"><code class="language-podlite" data-lang="podlite">=begin table :caption('My coffee morning')=begin row :header=cell Step=cell Tool=cell Time=end row=begin row=cell Grind=cell Burr grinder=cell 20s=end row=begin row=cell Brew=for cell :colspan(2)Aeropress, 90 seconds with bloom=end row=end table</code></pre><img height=400 width=500 src="https://www.perl.com/images/three-ways-to-write-a-table-in-podlite/04-coffee-morning.png" alt="My coffee morning rendered as a structured table. The Brew step spans the Tool and Time columns via :colspan(2).">A cell can hold any Podlite block: a paragraph, a code block, a picture, an embedded diagram. This call was made early in the spec: tables in Podlite are not a visual feature, they are containers that render as a grid.The third syntax is data-driven. If the numbers are short enough to live in the document, put them directly inside a <code>=data-table</code> block:<pre tabindex="0"><code class="language-podlite" data-lang="podlite">=begin data-table :caption('Build status') :mime-type<'text/csv; header=present'>component,statusparser,greenrenderer,greenplayground,yellow=end data-table</code></pre><img height=400 width=500 src="https://www.perl.com/images/three-ways-to-write-a-table-in-podlite/05a-build-status.png" alt="Build status rendered from inline CSV. The =data-table body holds the data; header=present marks the first row as a header.">Some data has its own life: a CSV export, a TSV log, anything that exists before the document does. Keep it in a separate <code>=data</code> block and reference it via <code>:src</code>. If the data starts with column labels, mark them with the <code>header=present</code> parameter from RFC 4180 3:<pre tabindex="0"><code class="language-podlite" data-lang="podlite">=for data-table :src<data:walks> :caption('Walks this month')=begin data :key<walks> :mime-type<'text/tab-separated-values; header=present'>datedistancenote2026-04-125kmmorning fog2026-04-153kmpark loop2026-04-228kmcoastal trail=end data</code></pre><img height=400 width=500 src="https://www.perl.com/images/three-ways-to-write-a-table-in-podlite/05-walks-this-month.png" alt="Walks this month rendered with a semantic header. The date/distance/note row is marked via the header=present parameter from RFC 4180 3.">The <code>=data</code> block holds raw TSV: tab-split, no quoting, which is what most TSV tools emit. Tools that walk the document read the structured data directly, and readers see the rendered table from the same source.<h2 id="when-tables-break">When tables break</h2>Tables break in real documents. A copy-paste loses a column, two rows pick different separators, a CSV cell holds an unmatched quote. The Podlite spec defines four rules so the parser warns you instead of silently corrupting the document:<ul><li>Per-line separator detection. Each row decides its separator from what it sees.</li><li>Cell count validation. Short rows pad with empty cells, long rows truncate. Both produce a warning.</li><li>Mixed-separator warning. Pipes in the header and whitespace in data still work, but you get a warning.</li><li>CSV recovery. Missing data renders an empty table. A non-CSV MIME type falls back to a <code>=code</code> block so the content stays visible.</li></ul>I’d rather see a warning in the console than ship a document with a dropped row.<h2 id="try-it">Try it</h2>Paste any of these examples into <a href="https://pod6.in">pod6.in</a>. The playground renders Podlite live, no install needed. The full table grammar lives in the <a href="https://podlite.org/specification">Podlite specification</a>.If you build something with this, or hit a case the spec does not cover, open a discussion at <a href="https://github.com/podlite/podlite-specs/discussions">podlite-specs</a>.Thanks for reading,Alex

Read more <a class="sw_sl" href="https://www.perl.com/article/three-ways-to-write-a-table-in-podlite/" target="_blank">here</a>

Technorati tag?:

Delete this item?:

Treat as new?:

home << Programming << Perl << auto three ways to write a table in podlite