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 37     37   277 use base 'PDF::Builder::Basic::PDF::String';
  37         89  
  37         4075  
19              
20 37     37   241 use strict;
  37         83  
  37         766  
21 37     37   174 use warnings;
  37         79  
  37         18262  
22              
23             our $VERSION = '3.023'; # VERSION
24             our $LAST_UPDATE = '3.022'; # 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             =head2 $n = PDF::Builder::Basic::PDF::Name->from_pdf($string)
34              
35             Creates a new string object (not a full object yet) from a given
36             string. The string is parsed according to input criteria with
37             escaping working, particular to Names.
38              
39             =cut
40              
41             sub from_pdf {
42 522     522 1 933 my ($class, $string, $pdf) = @_;
43              
44 522         1152 my ($self) = $class->SUPER::from_pdf($string);
45              
46 522         815 $self->{'val'} = name_to_string($self->{'val'}, $pdf);
47 522         995 return $self;
48             }
49              
50             =head2 $n->convert($string, $pdf)
51              
52             Converts a name into a string by removing the / and converting any hex
53             munging.
54              
55             =cut
56              
57             sub convert {
58 522     522 1 839 my ($self, $string, $pdf) = @_;
59              
60 522         850 $string = name_to_string($string, $pdf);
61 522         1326 return $string;
62             }
63              
64             =head2 $s->as_pdf($pdf)
65              
66             Returns a name formatted as PDF. C<$pdf> is optional but should be the
67             PDF File object for which the name is intended if supplied.
68              
69             =cut
70              
71             sub as_pdf {
72 6474     6474 1 9534 my ($self, $pdf) = @_;
73              
74 6474         10582 my $string = $self->{'val'};
75              
76 6474         10079 $string = string_to_name($string, $pdf);
77 6474         21170 return '/' . $string;
78             }
79              
80              
81             # Prior to PDF version 1.2, '#' was a literal character. Embedded
82             # spaces were implicitly allowed in names as well but it would be best
83             # to ignore that (PDF 1.3, section H.3.2.4.3).
84              
85             =head2 PDF::Builder::Basic::PDF::Name->string_to_name($string, $pdf)
86              
87             Suitably encode the string C<$string> for output in the File object C<$pdf>
88             (the exact format may depend on the version of $pdf).
89              
90             =cut
91              
92             sub string_to_name {
93 9554     9554 1 14990 my ($string, $pdf) = @_;
94              
95             # PDF 1.0 and 1.1 didn't treat the # symbol as an escape character
96 9554 50 33     38387 unless ($pdf and $pdf->{' version'} and $pdf->{' version'} < 1.2) {
      33        
97 9554         17217 $string =~ s|([\x00-\x20\x7f-\xff%()\[\]{}<>#/])|'#' . sprintf('%02X', ord($1))|oge;
  0         0  
98             }
99              
100 9554         22488 return $string;
101             }
102              
103             =head2 PDF::Builder::Basic::PDF::Name->name_to_string($string, $pdf)
104              
105             Suitably decode the string C<$string> as read from the File object C<$pdf>
106             (the exact decoding may depend on the version of $pdf). Principally,
107             undo the hex encoding for PDF versions > 1.1.
108              
109             =cut
110              
111             sub name_to_string {
112 1418     1418 1 2301 my ($string, $pdf) = @_;
113              
114 1418         1911 $string =~ s|^/||o;
115              
116             # PDF 1.0 and 1.1 didn't treat the # symbol as an escape character
117 1418 50 66     4594 unless ($pdf and $pdf->{' version'} and $pdf->{' version'} < 1.2) {
      33        
118 1418         1953 $string =~ s/#([0-9a-f]{2})/chr(hex($1))/oige;
  0         0  
119             }
120              
121 1418         2497 return $string;
122             }
123              
124             1;