PerlDoc

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::Tables::Parser

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:

open_table($line)

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

close_table()

Close the currently open table.

line($line)

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

open_tr($before)

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)

close_tr($after)

Called to close an open table row.

• $after - trailing content (| and spaces)

end_of_input()

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.