dtRdr::TOC - a linked Table of Contents tree
This pod needs work.
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,
book
id is a unique identifier within this tree,
id
range is a dtRdr::Range object that represents the text to which this TOC entry refers,
range
title is the display title for the TOC entry,
title
info => {foo => 'bar'} is some information for your own later reference.
info => {foo => 'bar'}
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.
parent
my $child = $toc->create_child($id, $range, \%info);
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; } }
All accessors are foo() and set_foo(). get_foo() is an alias to foo().
Returns the ID for this TOC object
my $id = $toc->id;
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;
Returns the range object for this TOC object
my $range = $toc->range;
returns the title for this TOC node
$toc->title
$toc->visible and print "visible!\n";
Returns true or false indicating whether the TOC item should be displayed in the TOC widget.
Returns all the child TOC objects for this TOC object. Returns the empty list if there are none.
my @children = $toc->children;
Recursive children
my @descendants = $toc->descendants;
Nodes before this, at the same level.
$toc->older_siblings;
my @nodes = $toc->younger_siblings;
Returns the next sibling or undef.
$younger = $toc->next_sibling;
Returns the previous sibling or undef.
$older = $toc->prev_sibling;
Returns the parent TOC object for the current object, or undef if there is no parent TOC object.
$toc->parent
Returns all of the node's ancestors (from parent upward.)
my @ancestors = $toc->ancestors;
True if the node has children.
$toc->has_children
Add a child TOC entry to this TOC entry.
$toc->add_child($child);
Get the child with index $i.
my $child = $toc->child($i);
my $root = $toc->root; $root ||= $toc; # it was the root
$toc->is_root;
Walks to the tree vector given by a list of successive child indices.
my $node = $toc->_walk_to_node(@list);
$root->_add_to_index($self);
my $node = $toc->get_by_id($id);
Searches for the node which encloses the given offset.
$toc->enclosing_node($offset);
$toc->get_info($key);
$toc->set_info($key, $val);
my $bool = $toc->validate_ranges;
my @errors = $toc->validate_ids;
print $toc->_dump;
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);
deprecated
$toc->_rmap($sub);
$toc->_while_gutted(sub {my $braindead = shift;});
Drop book, parent, and _index. Turn ranges into [$id, $start, $end].
$simple = $toc->_unhook;
...re-attach the book (as well as rebuilding the index.)
$obj->_rehook($book);
my $plain = $toc->unhooked;
Maybe Deprecated - do your own dumps?
my $yaml = $toc->yaml_dump;
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);
Load from a Storable.pm binary file.
my $re_toc = dtRdr::TOC->stb_load(\$stb, $book);
$stored = $toc->freeze;
$toc->thaw($book);
Eric Wilhelm <ewilhelm at cpan dot org>
Copyright (C) 2006 Eric L. Wilhelm and OSoft, All Rights Reserved.
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.
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.
To install dtRdr, copy and paste the appropriate command in to your terminal.
cpanm
cpanm dtRdr
CPAN shell
perl -MCPAN -e shell install dtRdr
For more information on module installation, please visit the detailed CPAN module installation guide.