File Coverage

blib/lib/PDF/Builder/Basic/PDF/Name.pm
Criterion Covered Total %
statement 29 31 93.5
branch 2 4 50.0
condition 5 12 41.6
subroutine 8 8 100.0
pod 5 5 100.0
total 49 60 81.6


line stmt bran cond sub pod time code
1             #=======================================================================
2             #
3             # THIS IS A REUSED PERL MODULE, FOR PROPER LICENCING TERMS SEE BELOW:
4             #
5             # Copyright Martin Hosken
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             #=======================================================================
16             package PDF::Builder::Basic::PDF::Name;
17              
18 41     41   259 use base 'PDF::Builder::Basic::PDF::String';
  41         72  
  41         3751  
19              
20 41     41   260 use strict;
  41         75  
  41         698  
21 41     41   153 use warnings;
  41         79  
  41         16801  
22              
23             our $VERSION = '3.024'; # VERSION
24             our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
25              
26             =head1 NAME
27              
28             PDF::Builder::Basic::PDF::Name - Inherits from L
29             and stores PDF names (things beginning with /)
30              
31             =head1 METHODS
32              
33             =over
34              
35             =item $n = PDF::Builder::Basic::PDF::Name->from_pdf($string)
36              
37             Creates a new string object (not a full object yet) from a given
38             string. The string is parsed according to input criteria with
39             escaping working, particular to Names.
40              
41             =cut
42              
43             sub from_pdf {
44 573     573 1 982 my ($class, $string, $pdf) = @_;
45              
46 573         1336 my ($self) = $class->SUPER::from_pdf($string);
47              
48 573         848 $self->{'val'} = name_to_string($self->{'val'}, $pdf);
49 573         1129 return $self;
50             }
51              
52             =item $n->convert($string, $pdf)
53              
54             Converts a name into a string by removing the / and converting any hex
55             munging.
56              
57             =cut
58              
59             sub convert {
60 573     573 1 861 my ($self, $string, $pdf) = @_;
61              
62 573         835 $string = name_to_string($string, $pdf);
63 573         1524 return $string;
64             }
65              
66             =item $s->as_pdf($pdf)
67              
68             Returns a name formatted as PDF. C<$pdf> is optional but should be the
69             PDF File object for which the name is intended if supplied.
70              
71             =cut
72              
73             sub as_pdf {
74 7332     7332 1 8950 my ($self, $pdf) = @_;
75              
76 7332         9648 my $string = $self->{'val'};
77              
78 7332         9220 $string = string_to_name($string, $pdf);
79 7332         20265 return '/' . $string;
80             }
81              
82              
83             # Prior to PDF version 1.2, '#' was a literal character. Embedded
84             # spaces were implicitly allowed in names as well but it would be best
85             # to ignore that (PDF 1.3, section H.3.2.4.3).
86              
87             =item PDF::Builder::Basic::PDF::Name->string_to_name($string, $pdf)
88              
89             Suitably encode the string C<$string> for output in the File object C<$pdf>
90             (the exact format may depend on the version of $pdf).
91              
92             =cut
93              
94             sub string_to_name {
95 11636     11636 1 15518 my ($string, $pdf) = @_;
96              
97             # PDF 1.0 and 1.1 didn't treat the # symbol as an escape character
98 11636 50 33     38976 unless ($pdf and $pdf->{' version'} and $pdf->{' version'} < 1.2) {
      33        
99 11636         18441 $string =~ s|([\x00-\x20\x7f-\xff%()\[\]{}<>#/])|'#' . sprintf('%02X', ord($1))|oge;
  0         0  
100             }
101              
102 11636         23969 return $string;
103             }
104              
105             =item PDF::Builder::Basic::PDF::Name->name_to_string($string, $pdf)
106              
107             Suitably decode the string C<$string> as read from the File object C<$pdf>
108             (the exact decoding may depend on the version of $pdf). Principally,
109             undo the hex encoding for PDF versions > 1.1.
110              
111             =cut
112              
113             sub name_to_string {
114 1599     1599 1 2554 my ($string, $pdf) = @_;
115              
116 1599         1972 $string =~ s|^/||o;
117              
118             # PDF 1.0 and 1.1 didn't treat the # symbol as an escape character
119 1599 50 66     4949 unless ($pdf and $pdf->{' version'} and $pdf->{' version'} < 1.2) {
      33        
120 1599         2171 $string =~ s/#([0-9a-f]{2})/chr(hex($1))/oige;
  0         0  
121             }
122              
123 1599         2810 return $string;
124             }
125              
126             =back
127              
128             =cut
129              
130             1;