NAME

 Scanner::Page - Representation of a Page to be passed to a Scanner.

SYNOPSIS

 use Scanner::Page;

 $obj  = Scanner::Page->new ( list of named arguments );
 $bool = Scanner::Page->defaultNameVerifierIs ( $myverifierobj );

 $pagetitle        = $obj->pagetitle;
 $date             = $obj->date;
 $title            = $obj->title;
 $pageid           = $obj->pageid;
 $subtitle         = $obj->subtitle;
 ($width, $height) = $obj->ScanDimensions;
 $flg              = $obj->landscape;
 $flg              = $obj->portrait;
 $obj              = $obj->info;

Inheritance

 UNIVERSAL

Description

Pages are transient objects used to pass information to Scanner::Device and Document::Directory objects.

Examples

 use File::Spec::Scanner::Page;

 my $flg = Scanner::Page->defaultNameVerifierIs ( $myvfyobj );

 my $pg  = Scanner::Page->new ( 'format'      => $fmt,
                                'date'        => "20080818",
                                'title'       => "DailyBoggle",
                                'pageid'      => "001",
                               );

 if ($pg->landscape) {print "It is a landscape page.\n";}
 if ($pg->portrait ) {print "It is a portrait  page.\n";}

 my ($x,$y) = $pg->ScanDimensions;
 my $pt     = $obj->pagetitle;
 my $date   = $obj->date;
 my $title  = $obj->title;
 my $pgnum  = $obj->pageid;
 my $stitle = $obj->subtitle;

Class Variables

 DEFAULT_NAME_VERIFIER      Class used for verifying a page name 
                            consisting of  the a set or subset of 
                            date-title-pageid-subtitle. Default is undef.

Instance Variables

 format         A Scanner::Format object.
 date           The date part of the page name, eg 19941224.
 title          The document title portion of the name.
 pageid         The pageid, usually a simple page number: 104.
 subtitle       The page title portion of the name.

Class Methods

$bool = Scanner::Page->defaultNameVerifierIs ( $obj )

Sets the default verifier object. Returns true if it succeeded. A false return could indicate $obj is not a ref. undef is a valid value and will restore the default behavior of the class, ie to do not much of anything about checking the name related fields.

A Scanner::Page has several fields for the input of strings used in constructing a full page name. The actual format of these is not directly enforced by this object other than a requirement that the concatenation of them all generate a nonzero string length.

In practice it is desirable to check that these fields have strings which will create valid file names when put together in the form:

        date-title-pageid-subtitle

and from which the scanner will eventually create:

        date-title-pageid-subtitle.jpeg

If you wish each new object to check these fields rather than blindly use them as it does by default, you may load a default object with this Class method. Your object must have a method like this:

  $bool = $myobj->validateName ( $date, $title, $pageid, $subtitle )

If you do nothing, only the simplest of checks, as noted earlier, are done. This may be adequate for many applications which only wish to use the 'title' field and nothing else.

$obj = Scanner::Page->new ( named argument list )

This is the Class method for creating new Scanner::Page objects. It may have many different arguments. They are in short:

                format     -> $fmtobj         [REQUIRED]
                date       -> date string     [OPT: default is ""]
                title      -> title string    [OPT: default is ""]
                pageid     -> pageid string   [OPT: default is ""]
                subtitle   -> subtitle string [OPT: default is ""]

'format' => <Scanner::Format object>

A format object that defines the orientation and size of the page.

'date' => <date string>

A date to be included as the first part of the page name, where a single date is represented as:

        yyyymmdd
        yyyymmddhhmmss

and mm and dd may be 00 to represent 'the whole month' or the 'whole year' as in a monthly magazine or a yearly report, or to represent uncertainty, 'it was from sometime in that year'. there may optionally be two dates, so as to represent a period of time associated with the page:

        date1-date2

The default is the null string: "".

'title' => <title string>

The title associated with the document of which this page is a part or whole if there is only one page. eg

        ModernQuantumTheory

The default is the null string: "".

'pageid' => <pageid string>

If the document is part of a multi-page document, a representation of the page number is needed. There may be two adjacent pages if the current page is an opened booklet on the scanner. Pageid's may look like the following:

                000a
                001
                043.01
                001-002

The default is the null string: "".

'subtitle' => <subtitle string>

An individual title for the page, the name of an article within a magazine, a comment about the contents of the page...

        TheCatDied-SmithAndWesson-itsNotDeadYet

The default is the null string: "".

It returns either a pointer to the newly created and initialized object or undef if the object could not be created.

Instance Methods

$date = $obj->date

Return the date string.

($width, $height) = $obj-Egt>ScanDimensions>

Retrieve the page dimensions to be used for scanning. The height may include extra space for calibration devices as earlier discussed in the Scanner::Page->setDefaultCalibratorFlag section:

        (width, height+calibratorheight)

The scanner might of course have something to say about the height or width we have selected! That, however, is not the Page's problem. It is what it is and it might be too large for the scanner you have.

$obj = $obj->info

Print info on the Scanner::Page to stdout.

$flg = $obj->landscape

Return true if it uses a landscape page format.

$pageid = $obj->pageid

Return the pageid string.

$pagetitle = $obj->pagetitle

Generate the full page title. There are four possible elements, any of which might be null. The page title is built from whichever of date, title, pageid and subtitle are non-null. The title is built up in the order:

        <date>-<title>-p<pageid>-<subtitle>

Possible pagetitles are:

 20040819
 20040819-QuantumTheory
 20040819-p001
 20040819-20100918-QuantumTheoryAdvances-p005-010-ForwardByMartians

If somehow all four are null, undef is returned instead of a string.

[Internal code question: how should I handle the 'p' that goes before a pageid?]

$flg = $obj->portrait

Return true if it uses a portrait page format.

$subtitle = $obj->subtitle

Return the subtitle string.

$title = $obj->title

Return the title string.

Private Class Methods

 None.

Private Instance Methods

 None.

Errors and Warnings

 None.

KNOWN BUGS

 See TODO.

SEE ALSO

 None.

AUTHOR

Dale Amon <amon@vnl.com>

cpanm Scanner::Job

perl -MCPAN -e shell
install Scanner::Job