NAME
dtRdr::Book - base and factory class for books
import
dtRdr::Book->import(%arguments);Called by 'use dtRdr::Book (%arguments)'. Only applicable to plugins.
- register HASHREF
-
A hash reference which is passed to register_plugin().
use dtRdr::Book (register => {}); use dtRdr::Book (register => {foo => "bar"});
register_plugin
Registers your plugin with dtRdr::Plugins::Book.
dtRdr::Book->register_plugin(%args);Factory Methods
new_from_uri
Create a new object and load the uri.
dtRdr::Book->new_from_uri($uri);identify_by_uri
my $class = dtRdr::Book->identify_by_uri($uri);Base Class API
These methods may be overridden by subclasses.
Constructor
new
$book = dtRdr::Book->new();Virtual Methods
Subclasses need to implement these.
load_uri
$book->load_uri($uri);identify_uri
$book->identify_uri();member_exists
my $bool = $book->member_exists($filepath);get_member_string
Gets the string for the member at path $filepath.
my $string = $book->get_member_string($filepath);get_content
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.
get_content_by_id
my $html = $book->get_content_by_id($id);get_raw_content
Unprocessed content for a given node.
$book->get_raw_content($toc);get_copy_content
Copyable content for a given node.
$book->get_copy_content($toc);get_trimmed_content
Gets all of the rendered xml content for a $toc node.
my $xml = $book->get_trimmed_content($toc);is_nesty
A class method that says whether the book needs special treatment.
Methods
mk_fingerprint
Create and store a checksum for the book.
$book->mk_fingerprint($stringref);set_id
Can only happen once.
$book->set_id($id);Annotations
add_<annotation>
$book->add_note($note);
$book->add_bookmark($bookmark);
$book->add_highlight($highlight);change_<annotation>
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.
delete_<annotation>
$book->delete_note($note);
$book->delete_bookmark($bookmark);
$book->delete_highlight($highlight);find_<annotation>
my $note = $book->find_note($anno_id);
my $bookmark = $book->find_bookmark($anno_id);
my $highlight = $book->find_highlight($anno_id);node_<annotation>s
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);local_<annotation>s
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);related_<annotation>s
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);note_thread
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.
find_note_references
A really stupid name? Maybe just in the wrong place.
my @pile = $book->find_note_references($note);drop_selections
$book->drop_selections;Position Juggling
_GP_to_NP
Globalize a Node Position
$self->_GP_to_NP($node, $pos);_NP_to_GP
$self->_NP_to_GP($node, $pos);localize_annotation
$book->localize_annotation($anno, $node);Annotation Serialization
get_anno_io
Get the annotation IO object.
set_anno_io
Set the annotation IO object.
do_serialize
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);io_action
Disable the annotation I/O system while running an action. Designed for use by the I/O system.
$book->io_action(sub {...});Text Search
insert_nbh
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.
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.
locate_string
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);_context_match
my @matches = _context_match(\$string, $left, $search, $right);Returns a list of match pairs: @matches = ([$start, $end], ...);
reduce_word_scope
Returns a Range with the appropriate TOC node and start/end positions.
my $range = $book->reduce_word_scope($node, $start, $end);Character Cache Management
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.
has_cached_node_characters
my $bool = $book->has_cached_node_characters($node);cache_node_characters
Saves the characters in the cache, and will eventually implement cache management.
$book->cache_node_characters($node, $chars);get_cache_chars
Get the cache characters for a given TOC node.
my $chars = $book->get_cache_chars($node);get_node_characters
Get the characters for $node. Will check the cache and/or create them.
my $chars = $book->get_node_characters($node);create_node_characters
my $chars = $book->create_node_characters($node);TOC-related Methods
get_toc
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_toc
Find the TOC node for $id.
my $toc = $book->find_toc($id);descendant_nodes
my @nodes = $book->descendant_nodes($node);ancestor_nodes
my @nodes = $book->ancestor_nodes($node);visible_nodes
my @visible = $book->visible_nodes;XML processing
xml_callbacks
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.)
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.)
- $book
-
The book object (aka $self.)
- parser
-
The Expat object.
- attributes
-
The %atts hash which was fed to the tag handler by the parser (only in start tag.)
- before
-
A reference to the hoppers string intended to be placed before the element.
- during
-
A reference to the $parser->recognized_string value.
- after
-
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.
_standard_xml_callbacks
Just a constant, but may be overridden.
my %dispatch = $self->_standard_xml_callbacks;Zombies
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.
new
dtRdr::Book::Zombie->new(id => $id);See Also
AUTHOR
Eric Wilhelm <ewilhelm at cpan dot org>
COPYRIGHT
Copyright (C) 2006-2007 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.