NAME

dtRdr::TOC - a linked Table of Contents tree

SYNOPSIS

This pod needs work.

Constructor

new

Create a new TOC item.

  my $toc = dtRdr::TOC->new( $book, $id, $range,
    {
      title   => $title,
      visible => 1|0,
      info => {
        my_thing => $foo,
      }
    },
    );

where

book is the book object for this TOC entry,

id is a unique identifier within this tree,

range is a dtRdr::Range object that represents the text to which this TOC entry refers,

title is the display title for the TOC entry,

info => {foo => 'bar'} is some information for your own later reference.

and

A final, optional argument parent is the parent TOC item for this item. You should typically not need the parent argument. See create_child() for why.

create_child

  my $child = $toc->create_child($id, $range, \%info);

TODO

And maybe something in Range -- see Metadata.pm's feature envy

my ($node, $bytes) = $toc->node_before_location($loc);

foreach my $node (@toc) { if($start < $loc and $loc < $stop) { last; } }

Accessors

All accessors are foo() and set_foo(). get_foo() is an alias to foo().

id

Returns the ID for this TOC object

  my $id = $toc->id;

book

Returns something representing the book object (maybe just an identifier for it) for this TOC object.

TREATING THE RESULT AS A BOOK MAY BREAK YOUR CODE!

  my $bookid = $toc->book;

range

Returns the range object for this TOC object

  my $range = $toc->range;

get_title

returns the title for this TOC node

  $toc->title

get_visible

  $toc->visible and print "visible!\n";

Returns true or false indicating whether the TOC item should be displayed in the TOC widget.

Tree Operations

children

Returns all the child TOC objects for this TOC object. Returns the empty list if there are none.

  my @children = $toc->children;

descendants

Recursive children

  my @descendants = $toc->descendants;

older_siblings

Nodes before this, at the same level.

  $toc->older_siblings;

younger_siblings

  my @nodes = $toc->younger_siblings;

next_sibling

Returns the next sibling or undef.

  $younger = $toc->next_sibling;

prev_sibling

Returns the previous sibling or undef.

  $older = $toc->prev_sibling;

parent

Returns the parent TOC object for the current object, or undef if there is no parent TOC object.

  $toc->parent

ancestors

Returns all of the node's ancestors (from parent upward.)

  my @ancestors = $toc->ancestors;

has_children

True if the node has children.

  $toc->has_children

add_child

Add a child TOC entry to this TOC entry.

  $toc->add_child($child);

child

Get the child with index $i.

  my $child = $toc->child($i);

root

  my $root = $toc->root;
  $root ||= $toc; # it was the root

is_root

  $toc->is_root;

_walk_to_node

Walks to the tree vector given by a list of successive child indices.

  my $node = $toc->_walk_to_node(@list);

_add_to_index

  $root->_add_to_index($self);

get_by_id

  my $node = $toc->get_by_id($id);

enclosing_node

Searches for the node which encloses the given offset.

  $toc->enclosing_node($offset);

Meta Accessors

get_info

  $toc->get_info($key);

set_info

  $toc->set_info($key, $val);

validate_ranges

  my $bool = $toc->validate_ranges;

validate_ids

  my @errors = $toc->validate_ids;

_dump

  print $toc->_dump;

rmap

Depth-first recursion. At each level, $sub is called as $sub->($node, \%ctrl).

The %ctrl hash allows you to send commands back to the dispatcher.

  my $sub = sub {
    my ($node, $ctrl) = @_;
    if(something($node)) {
      $ctrl->{prune} = 1; # do not follow children
    }
  };
  $toc->rmap($sub);

_rmap

deprecated

  $toc->_rmap($sub);

_while_gutted

  $toc->_while_gutted(sub {my $braindead = shift;});

_unhook

Drop book, parent, and _index. Turn ranges into [$id, $start, $end].

  $simple = $toc->_unhook;

_rehook

...re-attach the book (as well as rebuilding the index.)

  $obj->_rehook($book);

unhooked

  my $plain = $toc->unhooked;

yaml_dump

Maybe Deprecated - do your own dumps?

  my $yaml = $toc->yaml_dump;

yaml_load

Load the TOC from a YAML string (or reference if you need the speed) and re-attach the book (as well as rebuilding the index.)

  my $re_toc = dtRdr::TOC->yaml_load($yaml, $book);

  my $re_toc = dtRdr::TOC->yaml_load(\$yaml, $book);

stb_load

Load from a Storable.pm binary file.

  my $re_toc = dtRdr::TOC->stb_load(\$stb, $book);

freeze

  $stored = $toc->freeze;

thaw

  $toc->thaw($book);

AUTHOR

Eric Wilhelm <ewilhelm at cpan dot org>

COPYRIGHT

Copyright (C) 2006 Eric L. Wilhelm and OSoft, All Rights Reserved.

NO WARRANTY

Absolutely, positively NO WARRANTY, neither express or implied, is offered with this software. You use this software at your own risk. In case of loss, no person or entity owes you anything whatsoever. You have been warned.

LICENSE

The dotReader(TM) is OSI Certified Open Source Software licensed under the GNU General Public License (GPL) Version 2, June 1991. Non-encrypted and encrypted packages are usable in connection with the dotReader(TM). The ability to create, edit, or otherwise modify content of such encrypted packages is self-contained within the packages, and NOT provided by the dotReader(TM), and is addressed in a separate commercial license.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

cpanm dtRdr

perl -MCPAN -e shell
install dtRdr