internal package
Foswiki::Tables::Parser
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)
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.