Log inRegister

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


Parent package: Foswiki::Tables
Child packages:

    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.