NAME

 Document::Toc - Manage a Table of contents file.

SYNOPSIS

 use Document::Toc;

 @pagelist     = $obj->pages;
 @titles       = $obj->pageTitles              ($pageid);
 @categories   = $obj->pageTitleCategories     ($pageid, $title);

 $flg          = $obj->havePage                ($pageid);
 $flg          = $obj->havePageTitle           ($pageid, $title);
 $flg          = $obj->havePageTitleCategory   ($pageid, $title, $category);

 $flg          = $obj->addPages                (@pageids);
 $flg          = $obj->addPageTitles           ($pageid, @titles);
 $flg          = $obj->addPageTitleCategories  ($pageid, $title, @categories);

 $flg          = $obj->removePages             (@pageid);
 $flg          = $obj->removePageTitles        ($pageid, @titles);
 $flg          = $obj->removePageTitleCategories ($pageid,$title,@categories);

 $flg          = $obj->replacePageTitle        ($pageid, $oldtitle, $newtitle);
 @curselection = $obj->setpage                 ($page);
 @curselection = $obj->settitle                ($title);
 @curselection = $obj->setcategories;
 @curselection = $obj->setmark                 ($page, $title);
 @curselection = $obj->setfirstpage;
 @curselection = $obj->setfirsttitle;

 $page         = $obj->curpage;
 $title        = $obj->curtitle;
 @pages        = $obj->curpages;
 @titles       = $obj->curtitles;
 @categories   = $obj->curcategories;

 @members      = $obj->members;
 $flg          = $obj->isMember                ($member);
 $flg          = $obj->addMembers              (@members);
 $flg          = $obj->removeMembers           (@members);

Inheritance

 UNIVERSAL
   Document::Members
     Document::Toc

Description

This Class manages a table of contents object. A table of contents is keyed by pageids; each pageid may have zero or more titles; each title may belong to zero or more categories. It encodes the semantics of a .toc file.

 001 cover
 002 contents
 003 --
 005 ArticleTitleOne    Space, Aeronautics
 005 ArticleTitleTwo    Biology, Genetics
 006 backcover

into an easily modifiable and searchable form.

Examples

 use Document::Toc;
 my $toc = Document::Toc->new;

 my $f = $toc->addPages               ("001","002","003","005","006");
    $f = $toc->addPageTitles          ("002","TitleOne","TitleTwo");
    $f = $toc->addPageTitleCategories ("002","TitleTwo","Biology","Genetics");
    $f = $toc->addPageTitles          ("003","TitleOne","TitleTwo");
    $f = $toc->addPageTitleCategories ("003","TitleTwo","Biology","Genetics");
    $f = $toc->addPageTitles          ("005","TitleOne","TitleTwo");
    $f = $toc->addPageTitleCategories ("005","TitleTwo","Biology","Genetics");

 my @pages      = $toc->pages;
 my @titles     = $toc->pageTitles          ("005");
 my @categories = $toc->pageTitleCategories ("005", "TitleTwo");

    $f = $toc->havePage                     ("001");
    $f = $toc->havePageTitle                ("005","TitleTwo");
    $f = $toc->havePageTitleCategory        ("005","TitleTwo","Biology");

    $f = $toc->removePages                  ("002","006");
    $f = $toc->removePageTitles             ("003","TitleOne");
    $f = $toc->removePageTitleCategories    ("005","TitleTwo","Genetics");

    $f = $toc->replacePageTitle             ("005","TitleTwo","NewTitle");
 my @cursel = $toc->setpage                 ("005");
    @cursel = $toc->settitle                ("TitleTwo");
    @cursel = $toc->setcategories;
    @cursel = $toc->setmark                 ("003","TitleTwo");
    @cursel = $toc->setfirstpage;
    @cursel = $toc->setfirsttitle;

 my $page       = $toc->curpage;
 my $title      = $toc->curtitle;
    @pages      = $toc->curpages;
    @titles     = $toc->curtitles;
    @categories = $toc->curcategories;

    @pages      = $toc->members;
    $f          = $toc->isMember            ("001");
    $f          = $toc->addMembers          ("004");
    $f          = $toc->removeMembers       ("003");

Class Variables

 None.

Instance Variables

 None.

Class Methods

 None. 

Instance Methods

$flg = $obj->addMembers (@members)

Overrides parent and calls addPages.

$flg = $obj->addPages (@pageids)

Add new pageids to the toc with a blank title and no categories. True if it succeeds. Existing pages are unaffected.

$flg = $obj->addPageTitleCategories ($pageid, $title, @categories)

Merge new categories into the list of categories associated with title on the specified page. True if it succeeds. Existing categories are unaffected.

$flg = $obj->addPageTitles ($pageid, @titles)

Add new titles to an existing pageid. True if it succeeds. Existing titles are unaffected. Note that a blank title really is "" and not represented by "--" as in a TocFile!

@categories = $obj->curcategories

Return a list of all categories in the current page and table selection or an empty array.

$page = $obj->curpage

Return the current page name or undef if there is none.

@pages = $obj->curpages

Return a list of all pages in this Toc or undef if empty.

$title = $obj->curtitle

Return the current title or undef if there is none.

@titles = $obj->curtitles

Return a list of all titles on the current page or undef if there are none.

$flg = $obj->havePage ($pageid)

True if $pageid exists.

$flg = $obj->havePageTitle ($pageid, $title)

True if $title exists on $pageid.

$flg = $obj->havePageTitleCategory ($pageid, $title, $category)

True if $category is in use for $title on $pageid.

$flg = $obj->isMember ($member)

Overrides parent and calls havePage.

@members = $obj->members

Overrides parent and calls pages.

@pagelist = $obj->pages

Return a list of the pageids in the toc. List may be empty.

@categories = $obj->pageTitleCategories ($pageid, $title)

Return a list of all the categories associated with a specific page title. List can be empty if there is no assignment of the title to a category or categories yet.

@titles = $obj->pageTitles ($pageid)

Return a list of the page titles associated with a specific pageid found in the .toc. List can be empty as there will always be one untitled entry for each page in the Archivist::Publication's directory.

$flg = $obj->replacePageTitle ($pageid, $oldtitle, $newtitle)

Change the a title name without disturbing its' associated categories. Success means a new title was created, given the category hash of the old title, and the old title was deleted.

I might want some bulk operators to do complete replacement of a page title category list record.

$flg = $obj->removeMembers (@members)

Overrides parent and calls removePages.

$flg = $obj->removePages (@pageid)

Remove pageids from the hash. Will remove all titles and their associated categories that are part of the specified pages. Ignores pages that don't exist. Returns true if the operation succeeds.

$flg = $obj->removePageTitles ($pageid, @title)

Remove titles and their associated categories from a pageid. Ignores titles that don't exist. Returns true on success.

$flg = $obj->removePageTitleCategories ($pageid, $title, @category)

Remove categories from the specified title on the specified pageids. Ignores categories which don't exist. Returns true on success.

@curselection = $obj->setcategories

Set the selection mark to start with the categories associated with the current title. Return the modified current selection.

@curselection = $obj->setfirstpage

Set the selection mark to the firstpage. Return the modified current selection.

@curselection = $obj->setfirsttitle

Set the selection mark to the first title on the current page. Return the modified current selection.

@curselection = $obj->setmark ($page, $title)

Set the selection mark to start with the specified page and title. Return the modified current selection.

@curselection = $obj->setpage ($page)

Set the selection mark to start with the specified page. Return the modified current selection.

@curselection = $obj->settitle ($title)

Set the selection mark to start with the specified title on the current page. Return the modified current selection.

Private Class Methods

 None.

Private Instance Methods

$dideval = $obj->_lazy

SUBCLASS MAY CHAIN. Chains to parent class method. If the lazy evaluation bit is set, do evaluations and then clear it. Returns true if subclass should carry out it's own lazy evaluation.

This is an internal primitive operation on the members data. It assumes you know what you are doing because if you screw up the lazy evaluation you could create some really subtle bugs.

KNOWN BUGS

 See TODO.

SEE ALSO

Document::Members, Fault::DebugPrinter

AUTHOR

Dale Amon <amon@vnl.com>

cpanm Document::Toc

perl -MCPAN -e shell
install Document::Toc