1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
|
#=======================================================================
#
# THIS IS A REUSED PERL MODULE, FOR PROPER LICENCING TERMS SEE BELOW:
#
# Copyright Martin Hosken <Martin_Hosken@sil.org>
#
# No warranty or expression of effectiveness, least of all regarding
# anyone's safety, is implied in this software or documentation.
#
# This specific module is licensed under the Perl Artistic License.
# Effective 28 January 2021, the original author and copyright holder,
# Martin Hosken, has given permission to use and redistribute this module
# under the MIT license.
#
#=======================================================================
package PDF::Builder::Basic::PDF::Utils;
use strict;
use warnings;
our $VERSION = '3.026'; # VERSION
our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
=head1 NAME
PDF::Builder::Basic::PDF::Utils - Utility functions for PDF library
=head1 DESCRIPTION
A set of utility functions to save the fingers of the PDF library users!
=head1 METHODS
=cut
use PDF::Builder::Basic::PDF::Array;
use PDF::Builder::Basic::PDF::Bool;
use PDF::Builder::Basic::PDF::Dict;
use PDF::Builder::Basic::PDF::Name;
use PDF::Builder::Basic::PDF::Null;
use PDF::Builder::Basic::PDF::Number;
use PDF::Builder::Basic::PDF::String;
use PDF::Builder::Basic::PDF::Literal;
use Exporter;
use vars qw(@EXPORT @ISA);
@ISA = qw(Exporter);
@EXPORT = qw(PDFBool PDFArray PDFDict PDFName PDFNull
PDFNum PDFString PDFStr PDFStrHex PDFUtf);
=head2 PDFBool
PDFBool()
=over
Creates a Bool via PDF::Builder::Basic::PDF::Bool->new()
=back
=cut
sub PDFBool {
return PDF::Builder::Basic::PDF::Bool->new(@_);
}
=head2 PDFArray
PDFArray()
=over
Creates an array via PDF::Builder::Basic::PDF::Array->new()
=back
=cut
sub PDFArray {
return PDF::Builder::Basic::PDF::Array->new(@_);
}
=head2 PDFDict
PDFDict()
=over
Creates a dict via PDF::Builder::Basic::PDF::Dict->new()
=back
=cut
sub PDFDict {
return PDF::Builder::Basic::PDF::Dict->new(@_);
}
=head2 PDFName
PDFName()
=over
Creates a name via PDF::Builder::Basic::PDF::Name->new()
=back
=cut
sub PDFName {
return PDF::Builder::Basic::PDF::Name->new(@_);
}
=head2 PDFNull
PDFNull()
=over
Creates a null via PDF::Builder::Basic::PDF::Null->new()
=back
=cut
sub PDFNull {
return PDF::Builder::Basic::PDF::Null->new(@_);
}
=head2 PDFNum
PDFNum()
=over
Creates a number via PDF::Builder::Basic::PDF::Number->new()
=back
=cut
sub PDFNum {
return PDF::Builder::Basic::PDF::Number->new(@_);
}
=head2 PDFString
PDFString($text, $usage)
=over
Returns either PDFStr($text) or PDFUtf($text), depending on whether C<$text>
is already in UTF-8 and whether the C<$usage> permits UTF-8. If UTF-8 is I<not>
permitted, C<downgrade> will be called on a UTF-8 formatted C<$text>.
C<$usage> is a single character string indicating the use for which C<$text>
is to be applied. Some uses permit UTF-8, while others (currently) forbid it:
=over
=item 's'
An ordinary B<string>, where UTF-8 text is permitted.
=item 'n'
A B<named destination>, where UTF-8 text is permitted.
=item 'o'
An B<outline title>, where UTF-8 text is permitted.
=item 'p'
A B<popup title>, where UTF-8 text is permitted.
=item 'm'
B<metadata>, where UTF-8 text is permitted.
=item 'f'
A B<file path and/or name>, where UTF-8 text is currently B<not> permitted.
=item 'u'
A B<URL>, where UTF-8 text is currently B<not> permitted.
=item 'x'
Any other usage where UTF-8 text is B<not> permitted.
=back
=back
=cut
sub PDFString {
my ($text, $usage) = @_;
# some old code also checked valid(), but that seems to always give a true
# return on non-UTF-8 text
#my $isUTF8 = utf8::is_utf8($text) || utf8::valid($text);
my $isUTF8 = utf8::is_utf8($text);
my $isPermitted = 0; # default NO
# someone is bound to forget whether it's upper or lowercase!
if ($usage =~ m/^[snopm]/i) {
$isPermitted = 1;
}
if ($isPermitted) {
if ($isUTF8) {
return PDFUtf($text);
} else {
return PDFStr($text);
}
} else {
if ($isUTF8) {
utf8::downgrade($text); # force 7 bit ASCII
}
return PDFStr($text);
}
}
=head2 PDFStr
PDFStr()
=over
Creates a string via PDF::Builder::Basic::PDF::String->new()
B<DEPRECATED.> It is preferable that you use C<PDFString> instead.
=back
=cut
sub PDFStr {
return PDF::Builder::Basic::PDF::String->new(@_);
}
=head2 PDFStrHex
PDFStrHex()
=over
Creates a hex-string via PDF::Builder::Basic::PDF::String->new()
=back
=cut
sub PDFStrHex {
my $string = PDF::Builder::Basic::PDF::String->new(@_);
$string->{' ishex'} = 1;
return $string;
}
=head2 PDFUtf
PDFUtf()
=over
Creates a utf8-string via PDF::Builder::Basic::PDF::String->new()
B<DEPRECATED.> It is preferable that you use C<PDFString> instead.
=back
=cut
sub PDFUtf {
my $string = PDF::Builder::Basic::PDF::String->new(@_);
$string->{' isutf'} = 1;
return $string;
}
1;
|
