1Paper::Specs(3)       User Contributed Perl Documentation      Paper::Specs(3)
2
3
4

NAME

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

SYNOPSIS

10        use Paper::Specs units => 'cm';
11        my $form = Paper::Specs->find( brand => 'Avery', code => '1234');
12
13        use Paper::Specs units => 'cm', brand => 'Avery';
14        my $form = Paper::Specs->find( code => '1234');
15
16        # location of first label on sheet
17        my ($xpos, $ypos) = $form->label_location( 1, 1);
18        my ($h, $w)       = $form->label_size;
19

IMPORTANT NOTES

21       I appologise in advance for the hasty nature of this code. I want to
22       get it out to support some other code I am writing. I promise to
23       revisit it shortly to clear up the rough patches - however your
24       valuable input is most welcome.
25
26       CAVEAT ALPHA CODE - This is a preliminary module and will be subject to
27       fluctuations in API and structure based on feedback from users.
28
29       I expect that there will be some interest in this code and it should
30       firm up quickly.
31
32       If this module does not deliver what you are looking for then you are
33       encouraged to contact the author and voice your needs!
34
35       OTHER LABELS - I know about the Labels.xml file which is part of
36       OpenOffice but have not figured out how it is encoded. I have the
37       gLabels specifications file too. I plan to use these to help populate
38       the data for this module.
39

Paper::Specs methods

41       Import options
42           You can supply any of the methods for this class when it is
43           imported:
44
45            use Paper::Specs
46               strict => 1,
47               units  => 'cm';
48
49       @forms = Paper::Specs->find( criteria )
50           Returns a list of forms that matches the criteria. There are two
51           fields for criteria: brand and code. The brand can be set for the
52           class via the Paper::Specs->brand method.
53
54           You must supply at least a brand or a code to find. If no brand is
55           supplied then all known brands will be searched.
56
57           If you set the module to strict, its default, the find must return
58           extactly zero or one forms as a scalar. Otherwise it will throw an
59           exception.
60
61           See the beginning of this module for examples of finds.
62
63       @brands = Paper::Specs->brands
64           Returns a list or reference to a list of the brands for the paper
65           forms that this module is aware of. One brand, 'standard' is
66           reserved for well known paper formats such as letter, A4, etc.
67
68       $new_value = Paper::Specs->convert( value, units )
69           Converts 'value' which is in 'units' to new value which is in
70           Paper::Specs->units units.
71
72       $units = Paper::Specs->units( units )
73           Gets/sets the units that you wish to work with in your code. If you
74           are using metric then you might want 'mm' or 'cm'. If you are using
75           empirial then you might want 'in' or 'pt' (points = 1/72 in).
76
77           Current units supported are: in, cm, mm, and pt.
78
79       Paper::Specs->layout( 'normal' | 'pdf' )
80           This sets the co-ordinate system for some forms such as labels.
81           'normal' puts (0,0) at the top left corner. 'pdf' puts (0,0) at the
82           lower left corner.
83
84           As well 'pdf' calls units('pt'). You can reset this afterwards if
85           you are working in a different unit system.
86
87       Paper::Specs->strict( 0 | 1 )
88           Sets the strictness of this module. If it is strict then it will
89           throw exceptions via 'die' for things like finding more than one
90           form on a find method.
91
92           The default is to be strict.
93

Paper::Specs items

95       You get little object references back when you find specifications.
96       These objects can supply you with information that you are looking for
97       but do not actually store any values.
98
99       You should test that the object is of the type you are looking for
100
101        if ($form->type ne 'label') {
102           die "Feed me labels Seymore\n";
103        }
104
105       Other than that - most forms should be based on a sheet (of paper) but
106       will have different methods depending on what they are.
107

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

109       These methods apply forms of type 'sheet' and all that are derived from
110       it. (all other forms and stock)
111
112       ($h, $w) = $form->sheet_size
113           Returns the height and width of your sheet.
114
115       $size = $form->sheet_width
116           Width of the stock
117
118       $size = $form->sheet_height
119           Height of the stock
120

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

122       These methods apply to forms of type 'label' and all that are derived
123       from it.
124
125       Inherits methods from Paper::Specs::sheet.
126
127       ( $width, $height ) = $form->label_size
128           Returns just that; a list with the width and height of a label in
129           it
130
131       ( $x, $y ) = $form->label_location( $r, $c )
132           Returns the location of the upper left corner for label at row $r
133           and col $c based on your current format/co-ordinate system.
134
135       $size = $form->margin_left
136           Space between left edge of paper and first column of labels.
137
138       $size = $form->margin_right
139           Space between right edge of paper and last column of labels.
140
141       $size = $form->margin_top
142           Space between top edge of paper and first row of labels.
143
144       $size = $form->margin_bottom
145           Space between bottom edge of paper and last row of labels.
146
147       $size = $form->label_height
148           Height of one label
149
150       $size = $form->label_width
151           Width of one label
152
153       $count = label_rows
154           Number of rows of labels on a sheet
155
156       $count = label_cols
157           Number of columns of labels on a sheet
158
159       $size = $form->gutter_cols
160           Inner space between labels - column gutter.
161
162       $size = $form->gutter_rows
163           Inner space between labels - row gutter.
164

SEE ALSO

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

BUGS

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

AUTHORS

174       Originally written by Jay Lawrence <jlawrenc@cpan.org>
175
176       From version 0.06 onwards this module is maintained by Jon Allen (JJ)
177       <jj@jonallen.info> / <http://perl.jonallen.info>
178
180       Copyright (c)2001-2003 - Jay Lawrence, Infonium Inc. All rights
181       reserved.
182
183       Modifications from version 0.06 onwards Copyright (c) 2004-2005 Jon
184       Allen (JJ).
185
186       This library is free software; you can redistribute it and/or modify it
187       under the same terms as Perl itself.
188
189       Software distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND,
190       either express or implied. This software is not affiliated with the
191       Apache Software Foundation (ASF).
192
193
194
195perl v5.36.0                      2023-01-20                   Paper::Specs(3)
Impressum