NAME

 Document::PageIterator - Page Iterator Class.

#head1 SYNOPSIS

  use Document::PageIterator;
  $bool   = $pg->setpageid        ($pageid);
  $pageid = $pg->nextid;
  $bool   = $pg->setfirstpage     ($n);

  $bool   = $pg->advancepage      ($inc);
  $bool   = $pg->advancesubpage   ($inc);
  $bool   = $pg->SetPagenumber    ($n);
  $bool   = $pg->SetSubpagenumber ($n);
  $bool   = $pg->SetAlphapage     ($c);

Inheritance

 UNIVERSAL
   Document::Page
    Document::PageIterator

Description

This subclass of Document::Page adds the ability to increment any of the pageid formats. Only the last element of a pageid is incremented. Increments may continue until an invalid character (anything past "z") for an alphapage or a number exceeding the available field size is produced.

Examples

  $pg = Document::PageIterator->new ("001") || die ("Invalid page id");
  $pg->setpageid ("001.01a")                || die ("Invalid page id");
  $pg->setfirstpage (1)                     || die ("Invalid 1st page num");
  $pageid = $pg->nextid;
  defined $pageid                           || die ("Page id overflow");

Class Variables

 None.

Instance Variables

 firstpage      The first page number in the document. This
                is used when resetting. Usually this is 1 
                or 0 for the cover page of most publications;
                But it could be any number for publications
                that use page numbering based on volumes rather
                than issues.

Class Methods

 None.

Instance Methods

$bool = $pg->advancepage ($inc);

If a page number exists in the current pageid, increment it by the specified $inc value. If $inc is not numeric or the result would exceed the field size of the subpage, it returns false.

This is not a commonly used operator.

$bool = $pg->advancesubpage ($inc);

If a subpage number exists in the current pageid, increment it by the specified $inc value. If $inc is not numeric or the result would exceed the field size of the subpage, it returns false.

This is not a commonly used operator.

$pageid = $pg->nextid

Increment the pageid. Returns undef if this would cause an overflow. Overflows can occur if any field size would be exceeded or an illegal value generated. For example, increments of the following would fail:

        100z
        001.01z
        001.99
        999

$bool = $pg->SetAlphapage ($c);

If a page alpha character exists in the current pageid, set it to the specified alphabetic character. If $c is not a single alphabetic character, it returns false.

This is not a commonly used operator.

$bool= $pg->setfirstpage ($n);

Set the first page number in the document. This is used when resetting. Usually it is 1 or 0 for the cover page of most publications; but it could be any number for publications which use page numbering based on volumes rather than issues.

$bool= $pg->setpageid ($pageid)

Set the page id string and fully reinitialize the object for the implied field sizes of that id. Returns undef if the pageid is invalid.

For example, "009.10a" would set the pagenumber to 9, with a field size of 3; the subpage number to 10 with a field size of 2; and the page alpha to "a". Since increments only happen at the end, this page id would be incrementable from "009.10a" to "009.10z" before an overflow would occur.

Typically such complex page numbers are only used for inserts and such; more typical is a plain "009" which would be incrementable to "999" before overflow occurred.

$bool = $pg->SetPagenumber ($n);

If a page number exists in the current pageid, set it to the specified number $n. If $n is not numeric or is too large for the page number field, it returns false.

This is not a commonly used operator.

$bool = $pg->SetSubpagenumber ($n);

If a subpage number exists in the current pageid, set it to the specified number $n. If $n is not numeric or is too large for the subpage number field, it returns false.

This is not a commonly used operator.

Private Class Method

 None.

Private Instance Methods

 None.

Errors and Warnings

 None.

KNOWN BUGS

 See TODO.

SEE ALSO

Document::PageId

AUTHOR

Dale Amon <amon@vnl.com>

cpanm Document::Toc

perl -MCPAN -e shell
install Document::Toc