internal package Foswiki::Tables::Parser

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

internal package Foswiki::Parsers::Table

Re-usable sequential access event-based parser for TML tables.

A sequential access event-based parser works by parsing content and calling back to "event listeners" when syntactic constructs are recognised.

StaticMethod parse( $text, \&dispatch )

  • $text - text to parse
  • \&dispatch($event_name, ...) - event dispatcher (function)

This is a sequential event-based parser. As each line in the text is read, it is analysed and if it meets the criteria for an event, it is fired.

In keeping with the line-oriented nature of TML, the parser works on a line-by-line basis. <verbatim> and <literal> blocks are respected.

Events are fired by a call to $dispatch( ... ). The following events are fired:


Opens a new table with the given line. Note that this same line will be passed to new_row as well.


Close the currently open table.


Called for any line that is not part of a table.


Called on each row in an open table (including the header and footer rows)
  • $before - leading content (spaces and |)

th($pre, $data, $post)

Called to create a table header cell.
  • $pre - preamble (spaces)
  • $data - real content
  • $post - postamble (spaces)

td($pre, $data, $post)

Called to create a table cell.
  • $pre - preamble (spaces)
  • $data - real content
  • $post - postamble (spaces)


Called to close an open table row.
  • $after - trailing content (| and spaces)


Called at end of all input.

An additional event is provided for those seeking to perform special processing of certain lines, including rewriting them.

early_line($line) -> $integer

Provided for handling lines other than TML content that may interact with tables during a static parse e.g. special macros such as %EDITTABLE.

If early_line returns a positive result, then the parser will open a table on the next line, whether or not it is a table line, *BUT ONLY IF* the early_line handler for that next line returns 0. Any non-whitespace left in $line will be inserted as text.

If it returns a negative result, then any non-whitespace left in $line will be inserted as text, but no other processing will be performed.

Otherwise the line is processed normally.

Note that early_line operates on the internal representation of the line in the parser. Certain constructs, such as verbatim blocks, are specially marked in this content. early_line can be used to rewrite the $line in place, but only with great care. Caveat emptor.

The early_line handler is fired for all lines that may be part of a table (i.e. not verbatim or literal lines).

StaticMethod split_cell($cell) → ($pre, $main, $post, $ish)

Given a table cell datum with significant leading and trailing space, split the cell data into pre-, main-, and post- text, and set $ish if it is a header cell.

Topic revision: r1 - 21 Nov 2014, ProjectContributor
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback