Paper::Specs - Size and layout information for paper stock, forms, and labels.

NAME
SYNOPSIS
IMPORTANT NOTES
Paper::Specs methods
Paper::Specs items
Paper::Specs::sheet methods / $form->type eq 'sheet'
Paper::Specs::label methods / $form->type eq 'label'
SEE ALSO
BUGS
AUTHORS
COPYRIGHT and LICENCE

NAME

Paper::Specs - Size and layout information for paper stock, forms, and labels.

SYNOPSIS

 use Paper::Specs units => 'cm';
 my $form = Paper::Specs->find( brand => 'Avery', code => '1234');

 use Paper::Specs units => 'cm', brand => 'Avery';
 my $form = Paper::Specs->find( code => '1234');

 # location of first label on sheet
 my ($xpos, $ypos) = $form->label_location( 1, 1);
 my ($h, $w)       = $form->label_size;

IMPORTANT NOTES

I appologise in advance for the hasty nature of this code. I want to get it out to support some other code I am writing. I promise to revisit it shortly to clear up the rough patches - however your valuable input is most welcome.

CAVEAT ALPHA CODE - This is a preliminary module and will be subject to fluctuations in API and structure based on feedback from users.

I expect that there will be some interest in this code and it should firm up quickly.

If this module does not deliver what you are looking for then you are encouraged to contact the author and voice your needs!

OTHER LABELS - I know about the Labels.xml file which is part of OpenOffice but have not figured out how it is encoded. I have the gLabels specifications file too. I plan to use these to help populate the data for this module.

Paper::Specs methods

Import options

You can supply any of the methods for this class when it is imported:

 use Paper::Specs
    strict => 1,
    units  => 'cm';

@forms = Paper::Specs->find( criteria )

Returns a list of forms that matches the criteria. There are two fields for criteria: brand and code. The brand can be set for the class via the Paper::Specs->brand method.

You must supply at least a brand or a code to find. If no brand is supplied then all known brands will be searched.

If you set the module to strict, its default, the find must return extactly zero or one forms as a scalar. Otherwise it will throw an exception.

See the beginning of this module for examples of finds.

@brands = Paper::Specs->brands

Returns a list or reference to a list of the brands for the paper forms that this module is aware of. One brand, 'standard' is reserved for well known paper formats such as letter, A4, etc.

$new_value = Paper::Specs->convert( value, units )

Converts 'value' which is in 'units' to new value which is in Paper::Specs->units units.

$units = Paper::Specs->units( units )

Gets/sets the units that you wish to work with in your code. If you are using metric then you might want 'mm' or 'cm'. If you are using empirial then you might want 'in' or 'pt' (points = 1/72 in).

Current units supported are: in, cm, mm, and pt.

Paper::Specs->layout( 'normal' | 'pdf' )

This sets the co-ordinate system for some forms such as labels. 'normal' puts (0,0) at the top left corner. 'pdf' puts (0,0) at the lower left corner.

As well 'pdf' calls units('pt'). You can reset this afterwards if you are working in a different unit system.

Paper::Specs->strict( 0 | 1 )

Sets the strictness of this module. If it is strict then it will throw exceptions via 'die' for things like finding more than one form on a find method.

The default is to be strict.

Paper::Specs items

You get little object references back when you find specifications. These objects can supply you with information that you are looking for but do not actually store any values.

You should test that the object is of the type you are looking for

 if ($form->type ne 'label') {
    die "Feed me labels Seymore\n";
 }

Other than that - most forms should be based on a sheet (of paper) but will have different methods depending on what they are.

Paper::Specs::sheet methods / $form->type eq 'sheet'

These methods apply forms of type 'sheet' and all that are derived from it. (all other forms and stock)

($h, $w) = $form->sheet_size: Returns the height and width of your sheet.
$size = $form->sheet_width: Width of the stock
$size = $form->sheet_height: Height of the stock

Paper::Specs::label methods / $form->type eq 'label'

These methods apply to forms of type 'label' and all that are derived from it.

Inherits methods from Paper::Specs::sheet.

( $width, $height ) = $form->label_size: Returns just that; a list with the width and height of a label in it
( $x, $y ) = $form->label_location( $r, $c ): Returns the location of the upper left corner for label at row $r and col $c based on your current format/co-ordinate system.
$size = $form->margin_left: Space between left edge of paper and first column of labels.
$size = $form->margin_right: Space between right edge of paper and last column of labels.
$size = $form->margin_top: Space between top edge of paper and first row of labels.
$size = $form->margin_bottom: Space between bottom edge of paper and last row of labels.
$size = $form->label_height: Height of one label
$size = $form->label_width: Width of one label
$count = label_rows: Number of rows of labels on a sheet
$count = label_cols: Number of columns of labels on a sheet
$size = $form->gutter_cols: Inner space between labels - column gutter.
$size = $form->gutter_rows: Inner space between labels - row gutter.

BUGS

Please report your bugs and suggestions for improvement to <jj@jonallen.info>.

AUTHORS

Originally written by Jay Lawrence <jlawrenc@cpan.org>

From version 0.06 onwards this module is maintained by Jon Allen (JJ) <jj@jonallen.info> / http://perl.jonallen.info

COPYRIGHT and LICENCE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Software distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. This software is not affiliated with the Apache Software Foundation (ASF).

Paper::Specs - Size and layout information for paper stock, forms, and labels.