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