Paper::Specs(3)

📦
version 0.10 · 2 versions
, in fedora 43

🌸 NAME 🌸

Paper::Specs — all the size + layout tea for paper stock, forms, and labels. Like, every deets you need bestie 💖

✨ 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 💅

Okay so first things first, the author is literally apologising up front for how hasty this code is. They wanted to ship it fast to support some other code they were writing, and they promise they'll come back and clean up the rough patches shortly — but your input? So welcome. Genuinely. 🫶

CAVEAT ALPHA CODE — this is a preliminary module and the API and structure will be subject to fluctuations based on feedback from users. It's giving baby module, not final form 😭

The author expects there'll be some interest in this code and it should firm up quickly. Slay.

And if this module does not deliver what you're looking for? You are encouraged to contact the author and voice your needs. Speak up bestie, they want to hear it 📣

OTHER LABELS — the author knows about the Labels.xml file which is part of OpenOffice but has not figured out how it is encoded. They also have the gLabels specifications file. The plan is 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, which is 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 a 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 a new value which is in Paper::Specs->units units. Math but make it paper 💅
  • $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. No cap. 🔥

  • 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. Periodt. 💀

🌈 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 to 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.

🌟 SEE ALSO 🌟

Paper::Specs homepage — <http://perl.jonallen.info/projects/paper-specs>

🙈 BUGS 🙈

Please report your bugs and suggestions for improvement to <jj@jonallen.info>. They wanna hear it, fr fr 💌

👑 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 (c)2001-2003 — Jay Lawrence, Infonium Inc. All rights reserved.

Modifications from version 0.06 onwards Copyright (c) 2004-2005 Jon Allen (JJ).

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

and that's the whole page bestie ✨ this one shipped as perl v5.42.0, dated 2025-07-25, and it's filed under Paper::Specs(3) in the User Contributed Perl Documentation — go forth and measure some labels, you icon 💅🎀

📦 where this page comes from