Eric Wilhelm > dotReader-v0.11.2 > dtRdr::Book

Download:
dotReader-v0.11.2.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  1
View/Report Bugs
Source  

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.

Variably-Named Elements
_content_node

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.)

_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 ^

dtRdr::Plugins::Book

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.

syntax highlighting: