dtRdr::Book - base and factory class for books
dtRdr::Book->import(%arguments);
Called by 'use dtRdr::Book (%arguments)'. Only applicable to plugins.
A hash reference which is passed to register_plugin().
use dtRdr::Book (register => {}); use dtRdr::Book (register => {foo => "bar"});
Registers your plugin with dtRdr::Plugins::Book.
dtRdr::Book->register_plugin(%args);
Create a new object and load the uri.
dtRdr::Book->new_from_uri($uri);
my $class = dtRdr::Book->identify_by_uri($uri);
These methods may be overridden by subclasses.
$book = dtRdr::Book->new();
Subclasses need to implement these.
$book->load_uri($uri);
$book->identify_uri();
my $bool = $book->member_exists($filepath);
Gets the string for the member at path $filepath.
my $string = $book->get_member_string($filepath);
Returns the HTML and associated image and object data for a portion of the book.
my $html = $book->get_content($toc)
The $toc object is a ('dtRdr::TOC') node representing the content location.
$toc
'dtRdr::TOC'
my $html = $book->get_content_by_id($id);
Unprocessed content for a given node.
$book->get_raw_content($toc);
Copyable content for a given node.
$book->get_copy_content($toc);
Gets all of the rendered xml content for a $toc node.
my $xml = $book->get_trimmed_content($toc);
A class method that says whether the book needs special treatment.
Create and store a checksum for the book.
$book->mk_fingerprint($stringref);
Can only happen once.
$book->set_id($id);
$book->add_note($note); $book->add_bookmark($bookmark); $book->add_highlight($highlight);
Notify callbacks and IO subsystem that the annotation has changed.
$note = $book->change_note($note); $bookmark = $book->change_bookmark($bookmark); $highlight = $book->change_highlight($highlight);
Alternatively, for internal usage, will replace an annotation object with a new one bearing the same id. If the object returned is not the same reference that you passed, you should use the one which is returned.
$book->delete_note($note); $book->delete_bookmark($bookmark); $book->delete_highlight($highlight);
my $note = $book->find_note($anno_id); my $bookmark = $book->find_bookmark($anno_id); my $highlight = $book->find_highlight($anno_id);
Get all highlights for a given node, including ancestors, those that start in older siblings, etc.
my @notes = $book->node_notes($node); my @bookmarks = $book->node_bookmarks($node); my @highlights = $book->node_highlights($node);
Highlights which structurally belong to the given TOC node.
my @notes = $book->local_notes($node); my @bookmarks = $book->local_bookmarks($node); my @highlights = $book->local_highlights($node);
Highlights which appear in the given TOC $node (e.g. anchored in that node's descendants, ancestors, and older siblings.)
my @notes = $book->related_notes($node); my @bookmarks = $book->related_bookmarks($node); my @highlights = $book->related_highlights($node);
Look for notes in the same thread and build them into a tree. Returns a dtRdr::NoteThread object, unless the note is a single, in which case it returns only the note object.
my $thread = $book->note_thread($note);
$note may be a note object or note id.
A really stupid name? Maybe just in the wrong place.
my @pile = $book->find_note_references($note);
$book->drop_selections;
Globalize a Node Position
$self->_GP_to_NP($node, $pos);
$self->_NP_to_GP($node, $pos);
$book->localize_annotation($anno, $node);
Get the annotation IO object.
Set the annotation IO object.
This sidesteps the issue of having distinct add_foo(), add_foo_nowrite() methods. If there is a serializer (see dtRdr::Annotation::IO) available, we call $action on it with $object and %args.
$book->do_serialize($action, $object, %args);
Disable the annotation I/O system while running an action. Designed for use by the I/O system.
$book->io_action(sub {...});
Insert the note, bookmark, and highlight data for the given node.
$content = $self->insert_nbh($node, $content);
This also creates the cache_chars data needed for locate_string() operations.
cache_chars
locate_string()
TODO a better name (like rapidfire_xml_hatchet or something)
ALSO TODO currently, books need to call this from their get_content() or else they have no specialness. Books really must call this though, since e.g. mozilla requires that the images get rewritten as base64 encoded.
Finds $string in $node and returns a Selection object (possibly for a different node) with RENDERED POSITIONS.
my $range = $book->locate_string($node, $string, $lwing, $rwing);
my @matches = _context_match(\$string, $left, $search, $right);
Returns a list of match pairs: @matches = ([$start, $end], ...);
Returns a Range with the appropriate TOC node and start/end positions.
my $range = $book->reduce_word_scope($node, $start, $end);
The characters (for use in annotation placement) are cached by insert_nbh(), but can also be created and managed with these methods.
The cache is currently permanent WRT the life of the object. This is, of course, a slow memory leak. If you're short on ram, please send code and/or time.
my $bool = $book->has_cached_node_characters($node);
Saves the characters in the cache, and will eventually implement cache management.
$book->cache_node_characters($node, $chars);
Get the cache characters for a given TOC node.
my $chars = $book->get_cache_chars($node);
Get the characters for $node. Will check the cache and/or create them.
my $chars = $book->get_node_characters($node);
my $chars = $book->create_node_characters($node);
Every book has a table of contents.
my $root = $book->get_toc;
See TOC for tree-related methods and below for book-related methods (book related methods can transcend the tree structure, allowing us to support less-than-elegant book formats.)
Find the TOC node for $id.
my $toc = $book->find_toc($id);
my @nodes = $book->descendant_nodes($node);
my @nodes = $book->ancestor_nodes($node);
my @visible = $book->visible_nodes;
Gets the xml callbacks for xml rewrite processing.
my %dispatch = $book->xml_callbacks;
This %dispatch table will contain start and end keys, below which will be keys for individual xml elements (aka 'a', 'img', etc.)
start
end
For the basic case of adding or overriding element handlers, plugins should define the augment_xml_callbacks() method rather than overriding this method. No mechanism is provided or planned for chained handlers -- in that case you should override, then curry as needed.
Callbacks are fired during the parse() method of dtRdr::BookUtil::AnnoInsert. The parameters are as follows.
$subref->( $book, node => $node, parser => $parser, attributes => \%atts, before => \$before, during => \$during, after => \$after );
The $before, $during, and $after references are strings which the plugin should modify as needed.
Note that this is very similar to the XML start/end handler. The only thing missing is the element name (you know that already.)
The book object (aka $self.)
The Expat object.
The %atts hash which was fed to the tag handler by the parser (only in start tag.)
A reference to the hoppers string intended to be placed before the element.
A reference to the $parser->recognized_string value.
A referece to the hoppers string intended to be placed after the element.
Note (again) that before, during, and after are *references* to strings. This is speed-critical, or else the API would be more user-friendly.
This key is replaced with the value of $book->XML_CONTENT_NODE (or dropped if there is no such method.) This builtin callback provides the copy_ok handling (and maybe more later.)
Just a constant, but may be overridden.
my %dispatch = $self->_standard_xml_callbacks;
dtRdr::Book::Zombie - Books that walk around mindlessly
Though they don't eat flesh, these are the undead books. They have no content or other book-like capabilities besides an id and possibly a uri.
They may be resurrect()ed, though that magic isn't done yet. Similarly, calling $book->kill should turn it into a zombie.
dtRdr::Book::Zombie->new(id => $id);
dtRdr::Plugins::Book
Eric Wilhelm <ewilhelm at cpan dot org>
Copyright (C) 2006-2007 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.