NAME

SYNOPSIS

 # Matched tables are returned as table objects; tables can be matched
 # using column headers, depth, count within a depth, table tag
 # attributes, or some combination of the four.

 # Example: Using column header information.
 # Assume an HTML document with tables that have "Date", "Price", and
 # "Cost" somewhere in a row. The columns beneath those headings are
 # what you want to extract. They will be returned in the same order as
 # you specified the headers since 'automap' is enabled by default.

 use HTML::TableExtract;
 my $te = HTML::TableExtract->new( headers => [qw(Date Price Cost)] );
 $te->parse($html_string);

 # Examine all matching tables
 foreach my $ts ($te->tables) {
   print "Table (", join(',', $ts->coords), "):\n";
   foreach my $row ($ts->rows) {
      print join(',', @$row), "\n";
   }
 }

 # Shorthand...top level rows() method assumes the first table found in
 # the document if no arguments are supplied.
 foreach my $row ($te->rows) {
    print join(',', @$row), "\n";
 }

 # Example: Using depth and count information.
 # Every table in the document has a unique depth and count tuple, so
 # when both are specified it is a unique table. Depth and count both
 # begin with 0, so in this case we are looking for a table (depth 2)
 # within a table (depth 1) within a table (depth 0, which is the top
 # level HTML document). In addition, it must be the third (count 2)
 # such instance of a table at that depth.

 my $te = HTML::TableExtract->new( depth => 2, count => 2 );
 $te->parse_file($html_file);
 foreach my $ts ($te->tables) {
    print "Table found at ", join(',', $ts->coords), ":\n";
    foreach my $row ($ts->rows) {
       print "   ", join(',', @$row), "\n";
    }
 }

 # Example: Using table tag attributes.
 # If multiple attributes are specified, all must be present and equal
 # for match to occur.

 my $te = HTML::TableExtract->new( attribs => { border => 1 } );
 $te->parse($html_string);
 foreach my $ts ($te->tables) {
   print "Table with border=1 found at ", join(',', $ts->coords), ":\n";
   foreach my $row ($ts->rows) {
      print "   ", join(',', @$row), "\n";
   }
 }

 # Example: Extracting as an HTML::Element tree structure
 # Rather than extracting raw text, the html can be converted into a
 # tree of element objects. The HTML document is composed of
 # HTML::Element objects and the tables are HTML::ElementTable
 # structures. Using this, the contents of tables within a document can
 # be edited in-place.

 use HTML::TableExtract qw(tree);
 my $te = HTML::TableExtract->new( headers => qw(Fee Fie Foe Fum) );
 $te->parse_file($html_file);
 my $table = $te->first_table_found;
 my $table_tree = $table->tree;
 $table_tree->cell(4,4)->replace_content('Golden Goose');
 my $table_html = $table_tree->as_HTML;
 my $table_text = $table_tree->as_text;
 my $document_tree = $te->tree;
 my $document_html = $document_tree->as_HTML;

DESCRIPTION

There are currently four constraints available to specify which tables you would like to extract from a document: Headers, Depth, Count, and Attributes.

Headers, the most flexible and adaptive of the techniques, involves specifying text in an array that you expect to appear above the data in the tables of interest. Once all headers have been located in a row of that table, all further cells beneath the columns that matched your headers are extracted. All other columns are ignored: think of it as vertical slices through a table. In addition, TableExtract automatically rearranges each row in the same order as the headers you provided. If you would like to disable this, set automap to 0 during object creation, and instead rely on the column_map() method to find out the order in which the headers were found. Furthermore, TableExtract will automatically compensate for cell span issues so that columns are really the same columns as you would visually see in a browser. This behavior can be disabled by setting the gridmap parameter to 0. HTML is stripped from the entire textual content of a cell before header matches are attempted -- unless the keep_html parameter was enabled.

Depth and Count are more specific ways to specify tables in relation to one another. Depth represents how deeply a table resides in other tables. The depth of a top-level table in the document is 0. A table within a top-level table has a depth of 1, and so on. Each depth can be thought of as a layer; tables sharing the same depth are on the same layer. Within each of these layers, Count represents the order in which a table was seen at that depth, starting with 0. Providing both a depth and a count will uniquely specify a table within a document.

Attributes match based on the attributes of the html <table> tag, for example, border widths or background color.

Each of the Headers, Depth, Count, and Attributes specifications are cumulative in their effect on the overall extraction. For instance, if you specify only a Depth, then you get all tables at that depth (note that these could very well reside in separate higher- level tables throughout the document since depth extends across tables). If you specify only a Count, then the tables at that Count from all depths are returned (i.e., the nth occurrence of a table at each depth). If you only specify Headers, then you get all tables in the document containing those column headers. If you have specified multiple constraints of Headers, Depth, Count, and Attributes, then each constraint has veto power over whether a particular table is extracted.

If no Headers, Depth, Count, or Attributes are specified, then all tables match.

When extracting only text from tables, the text is decoded with HTML::Entities by default; this can be disabled by setting the decode parameter to 0.

  use HTML::TableExtract;

  use HTML::TableExtract qw(tree);

METHODS

NOTES ON TREE EXTRACTION MODE

  use HTML::TableExtract 'tree';

There are a number of things to take note of while using this mode. The entire HTML document is encoded into an HTML::Element tree. Each table is part of this structure, but nevertheless is tracked separately via an HTML::ElementTable structure, which is a specialized form of HTML::Element tree.

The HTML::ElementTable objects are accessible by invoking the tree() method from within each table object returned by HTML::TableExtract. The HTML::ElementTable objects have their own row(), col(), and cell() methods (among others). These are not to be confused with the row() and column() methods provided by the HTML::TableExtract::Table objects.

For example, the row() method from HTML::ElementTable will provide a reference to a 'glob' of all the elements in that row. Actions (such as setting attributes) performed on that row reference will affect all elements within that row. On the other hand, the row() method from the HTML::TableExtract::Table object will return an array (either by reference or list, depending on context) of the contents of each cell within the row. In tree mode, the content is represented by individual references to each cell -- these are references to the same HTML::Element objects that reside in the HTML::Element tree.

The cell() methods provided in both cases will therefore return references to the same object. The exception to this is when a 'cell' in the table grid was originally 'covered' due to rowspan or colspan issues -- in this case the cell content will be undef. Likewise, the row() or column() methods from HTML::TableExtract::Table objects will return arrays potentially containing a mixture of object references and undefs. If you're going to be doing lots of manipulation of the table elements, it might be more efficient to access them via the methods provided by the HTML::ElementTable object instead. See HTML::ElementTable for more information on how to manipulate those objects.

An alternative to the cell() method in HTML::TableExtract::Table is the space() method. It is largely similar to cell(), except when given coordinates of a cell that was covered due to rowspan or colspan effects, it will return the contents of the cell that was covering that space rather than undef. So if, for example, cell (0,0) had a rowspan of 2 and colspan of 2, cell(1,1) would return undef and space(1,1) would return the same content as cell(0,0) or space(0,0).

REQUIRES

OPTIONALLY REQUIRES

AUTHOR

COPYRIGHT

SEE ALSO