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