diff options
Diffstat (limited to 'lib/PDF/Builder/Basic')
20 files changed, 798 insertions, 280 deletions
diff --git a/lib/PDF/Builder/Basic/PDF.pm b/lib/PDF/Builder/Basic/PDF.pm index e997191..f4e9a45 100644 --- a/lib/PDF/Builder/Basic/PDF.pm +++ b/lib/PDF/Builder/Basic/PDF.pm @@ -3,7 +3,7 @@ package PDF::Builder::Basic::PDF; use strict; use warnings; -our $VERSION = '3.025'; # VERSION +our $VERSION = '3.026'; # VERSION our $LAST_UPDATE = '3.020'; # manually update whenever code is changed =head1 NAME diff --git a/lib/PDF/Builder/Basic/PDF/Array.pm b/lib/PDF/Builder/Basic/PDF/Array.pm index ac4b40e..18ede12 100644 --- a/lib/PDF/Builder/Basic/PDF/Array.pm +++ b/lib/PDF/Builder/Basic/PDF/Array.pm @@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::Objind'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed =head1 NAME @@ -30,13 +30,17 @@ Inherits from L<PDF::Builder::Basic::PDF::Objind> =head1 METHODS -=over +=head2 new + + PDF::Array->new($parent, @values) -=item PDF::Array->new($parent, @values) +=over Creates an array with the given storage parent and an optional list of values to initialise the array with. +=back + =cut sub new { @@ -49,9 +53,16 @@ sub new { return $self; } -=item $a->outobjdeep($fh, $pdf) +=head2 outobjdeep -Outputs an array as a PDF array to the given filehandle. + $a->outobjdeep($fh, $pdf) + +=over + +Outputs an array as a PDF array to the given filehandle. It's unusual to +need to call this method from user code. + +=back =cut @@ -67,26 +78,34 @@ sub outobjdeep { return; } -=item $a->elements() +=head2 elements + + $a->elements() + +=over Returns the contents of the array. -Formerly called C<elementsof>, which is now B<deprecated>. +=back =cut -sub elementsof { return elements(@_); } - sub elements { my $self = shift(); return @{$self->{' val'}}; } -=item $a->add_elements(@elements) +=head2 add_elements + + $a->add_elements(@elements) + +=over Appends the given elements to the array. An element is only added if it is defined. +=back + =cut sub add_elements { @@ -99,18 +118,18 @@ sub add_elements { return $self; } -=item $a->remove_element($element) +=head2 remove_element + + $a->remove_element($element) + +=over Removes all occurrences of an element from an array. -Formerly called C<removeobj>, which is now B<deprecated> and will be removed. +=back =cut -# not listed as deprecated, not used internally, should not have been -# used in external code. remove after July 2021. -sub removeobj { return remove_element(@_); } - sub remove_element { my ($self, $element) = @_; @@ -118,21 +137,33 @@ sub remove_element { return $self; } -=item $a->val() +=head2 val + + $a->val() + +=over Returns a reference to the contents of the array. +=back + =cut sub val { return $_[0]->{' val'}; } -=item $a->copy($pdf) +=head2 copy + + $a->copy($pdf) + +=over Copies the array with deep-copy on elements which are not full PDF objects with respect to a particular $pdf output context. +=back + =cut sub copy { @@ -151,8 +182,4 @@ sub copy { return $res; } -=back - -=cut - 1; diff --git a/lib/PDF/Builder/Basic/PDF/Bool.pm b/lib/PDF/Builder/Basic/PDF/Bool.pm index c163ca5..5dc796a 100644 --- a/lib/PDF/Builder/Basic/PDF/Bool.pm +++ b/lib/PDF/Builder/Basic/PDF/Bool.pm @@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::String'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed =head1 NAME @@ -31,30 +31,36 @@ B<true> or B<false> =head1 METHODS -=over +=head2 convert + + $b->convert($str) -=item $b->convert($str) +=over Converts a string into the string which will be stored. +=back + =cut sub convert { return $_[1] eq 'true'; } -=item $b->as_pdf() +=head2 as_pdf + + $b->as_pdf() + +=over Converts the value to a PDF output form. +=back + =cut sub as_pdf { return $_[0]->{'val'}? 'true': 'false'; } -=back - -=cut - 1; diff --git a/lib/PDF/Builder/Basic/PDF/Dict.pm b/lib/PDF/Builder/Basic/PDF/Dict.pm index 05264c6..c2a4ecb 100644 --- a/lib/PDF/Builder/Basic/PDF/Dict.pm +++ b/lib/PDF/Builder/Basic/PDF/Dict.pm @@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::Objind'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed our $mincache = 16 * 1024 * 1024; @@ -60,8 +60,17 @@ source PDF the stream starts. =head1 METHODS +=head2 new + + $d = PDF::Builder::Basic::PDF->new() + =over +Creates a new instance of a dictionary. The usual practice is to call +C<PDFDict()> instead. + +=back + =cut sub new { @@ -74,10 +83,16 @@ sub new { return $self; } -=item $type = $d->type($type) +=head2 type + + $type = $d->type($type) + +=over Get/Set the standard Type key. It can be passed, and will return, a text value rather than a Name object. +=back + =cut sub type { @@ -90,10 +105,16 @@ sub type { return $self->{'Type'}->val(); } -=item @filters = $d->filter(@filters) +=head2 filter + + @filters = $d->filter(@filters) + +=over Get/Set one or more filters being used by the optional stream attached to the dictionary. +=back + =cut sub filter { @@ -113,10 +134,14 @@ sub filter { return $self->{'Filter'}; } -# Undocumented alias, which may be removed in a future release +# Undocumented alias, which may be removed in a future release TBD sub filters { return filter(@_); } -=item $d->outobjdeep($fh, $pdf) +=head2 outobjdeep + + $d->outobjdeep($fh, $pdf) + +=over Outputs the contents of the dictionary to a PDF file. This is a recursive call. @@ -124,6 +149,8 @@ It also outputs a stream if the dictionary has a stream element. If this occurs then this method will calculate the length of the stream and insert it into the stream's dictionary. +=back + =cut sub outobjdeep { @@ -234,7 +261,11 @@ sub outobjdeep { return; } -=item $d->read_stream($force_memory) +=head2 read_stream + + $d->read_stream($force_memory) + +=over Reads in a stream from a PDF file. If the stream is greater than C<PDF::Dict::mincache> (defaults to 32768) bytes to be stored, then @@ -243,6 +274,8 @@ file as a data cache. If $force_memory is set, this caching will not occur and the data will all be stored in the $self->{' stream'} variable. +=back + =cut sub read_stream { @@ -316,18 +349,20 @@ sub read_stream { return $self; } -=item $d->val() +=head2 val + + $d->val() + +=over Returns the dictionary, which is itself. +=back + =cut sub val { return $_[0]; } -=back - -=cut - 1; diff --git a/lib/PDF/Builder/Basic/PDF/File.pm b/lib/PDF/Builder/Basic/PDF/File.pm index beafb51..e6561a3 100644 --- a/lib/PDF/Builder/Basic/PDF/File.pm +++ b/lib/PDF/Builder/Basic/PDF/File.pm @@ -20,8 +20,8 @@ package PDF::Builder::Basic::PDF::File; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed =head1 NAME @@ -29,12 +29,12 @@ PDF::Builder::Basic::PDF::File - Holds the trailers and cross-reference tables f =head1 SYNOPSIS - $p = PDF::Builder::Basic::PDF::File->open("filename.pdf", 1); - $p->new_obj($obj_ref); - $p->free_obj($obj_ref); - $p->append_file(); - $p->close_file(); - $p->release(); # IMPORTANT! + $p = PDF::Builder::Basic::PDF::File->open("filename.pdf", 1); + $p->new_obj($obj_ref); + $p->free_obj($obj_ref); + $p->append_file(); + $p->close_file(); + $p->release(); # IMPORTANT! =head1 DESCRIPTION @@ -142,10 +142,6 @@ is in PDF, which contains the location of the previous cross-reference table. =back -=head1 METHODS - -=over - =cut use Scalar::Util qw(blessed weaken); @@ -189,12 +185,20 @@ use PDF::Builder::Basic::PDF::Pages; use PDF::Builder::Basic::PDF::Null; use POSIX qw(ceil floor); -=item PDF::Builder::Basic::PDF::File->new() +=head1 METHODS + +=head2 new + + PDF::Builder::Basic::PDF::File->new() + +=over Creates a new, empty file object which can act as the host to other PDF objects. Since there is no file associated with this object, it is assumed that the object is created in readiness for creating a new PDF file. +=back + =cut sub new { @@ -211,7 +215,11 @@ sub new { return $self; } -=item $p = PDF::Builder::Basic::PDF::File->open($filename, $update, %options) +=head2 open + + $p = PDF::Builder::Basic::PDF::File->open($filename, $update, %options) + +=over Opens the file and reads all the trailers and cross reference tables to build a complete directory of objects. @@ -241,6 +249,8 @@ longer fail on them, but merely comment on their existence. =back +=back + =cut sub open { @@ -284,6 +294,7 @@ sub open { # out inline comment and create a separate comment further along). } + # there should always be 'startxref' within 16*64 bytes of end $fh->seek(0, 2); # go to end of file my $end = $fh->tell(); $self->{' epos'} = $end; @@ -297,7 +308,8 @@ sub open { warn "Malformed PDF file $filename"; #orig 'die' } } - my $xpos = $1; + my $xpos = $1; # offset given after 'startxref' + # should point to either xref table ('xref'), or object with xref stream $self->{' xref_position'} = $xpos; my $tdict = $self->readxrtr($xpos, %options); @@ -308,9 +320,13 @@ sub open { return $self; } # end of open() -=item $new_version = $p->version($version, %opts) # Set +=head2 version + + $new_version = $p->version($version, %opts) # Set -=item $ver = $p->version() # Get + $ver = $p->version() # Get + +=over Gets/sets the PDF version (e.g., 1.5). Setting sets both the header and trailer versions. Getting returns the higher of header and trailer versions. @@ -322,6 +338,8 @@ A warning message is given if you attempt to I<decrease> the PDF version, as you might have already read in a higher level file, or used a higher level feature. This message is suppressed if the 'silent' option is given with any value. +=back + =cut sub version { @@ -368,9 +386,13 @@ sub version { return $old_version; } -=item $new_version = $p->header_version($version, %opts) # Set +=head2 header_version + + $new_version = $p->header_version($version, %opts) # Set -=item $version = $p->header_version() # Get + $version = $p->header_version() # Get + +=over Gets/sets the PDF version stored in the file header. @@ -381,6 +403,8 @@ A warning message is given if you attempt to I<decrease> the PDF version, as you might have already read in a higher level file, or used a higher level feature. This message is suppressed if the 'silent' option is given with any value. +=back + =cut sub header_version { @@ -415,9 +439,13 @@ sub header_version { return $old_version; } -=item $new_version = $p->trailer_version($version, %opts) # Set +=head2 trailer_version + + $new_version = $p->trailer_version($version, %opts) # Set + + $version = $p->trailer_version() # Get -=item $version = $p->trailer_version() # Get +=over Gets/sets the PDF version stored in the document catalog. @@ -432,6 +460,8 @@ A warning message is given if you attempt to I<decrease> the PDF version, as you might have already read in a higher level file, or used a higher level feature. This message is suppressed if the 'silent' option is given with any value. +=back + =cut sub trailer_version { @@ -470,11 +500,17 @@ sub trailer_version { return $old_version; } -=item $prev_version = $p->require_version($version) +=head2 require_version + + $prev_version = $p->require_version($version) + +=over Ensures that the PDF version is at least C<$version>. Silently sets the version to the higher level. +=back + =cut sub require_version { @@ -484,7 +520,11 @@ sub require_version { return $current_version; } -=item $p->release() +=head2 release + + $p->release() + +=over Releases ALL of the memory used by the PDF document and all of its component objects. After calling this method, do B<NOT> expect to @@ -501,6 +541,8 @@ you've called this method, though, don't expect to be able to do anything else with the C<PDF::Builder::Basic::PDF::File> object; it'll have B<no> internal state whatsoever. +=back + =cut # Maintainer's Question: Couldn't this be handled by a DESTROY method @@ -540,11 +582,17 @@ sub release { return; } # end of release() -=item $p->append_file() +=head2 append_file + + $p->append_file() + +=over Appends the objects for output to the read file and then appends the appropriate table. +=back + =cut sub append_file { @@ -585,7 +633,11 @@ sub append_file { return; } # end of append_file() -=item $p->out_file($fname) +=head2 out_file + + $p->out_file($fname) + +=over Writes a PDF file to a file of the given filename, based on the current list of objects to be output. It creates the trailer dictionary based on information @@ -593,6 +645,8 @@ in C<$self>. $fname may be a string or an IO object. +=back + =cut sub out_file { @@ -604,12 +658,18 @@ sub out_file { return $self; } -=item $p->create_file($fname) +=head2 create_file + + $p->create_file($fname) + +=over Creates a new output file (no check is made of an existing open file) of the given filename or IO object. Note: make sure that C<< $p->{' version'} >> is set correctly before calling this function. +=back + =cut sub create_file { @@ -638,10 +698,16 @@ sub create_file { return $self; } -=item $p->close_file() +=head2 close_file + + $p->close_file() + +=over Closes up the open file for output, by outputting the trailer, etc. +=back + =cut sub close_file { @@ -674,7 +740,11 @@ sub close_file { return $self; } # end of close_file() -=item ($value, $str) = $p->readval($str, %opts) +=head2 readval + + ($value, $str) = $p->readval($str, %opts) + +=over Reads a PDF value from the current position in the file. If C<$str> is too short, read some more from the current location in the file until the whole @@ -684,6 +754,8 @@ object is read. This is a recursive call which may slurp in a whole big stream Returns the recursive data structure read and also the current C<$str> that has been read from the file. +=back + =cut sub readval { @@ -918,10 +990,16 @@ sub readval { return ($result, $str); } # end of readval() -=item $ref = $p->read_obj($objind, %opts) +=head2 read_obj + + $ref = $p->read_obj($objind, %opts) + +=over Given an indirect object reference, locate it and read the object returning -the read in object. +the read-in object. + +=back =cut @@ -934,10 +1012,16 @@ sub read_obj { return $objind; } -=item $ref = $p->read_objnum($num, $gen, %opts) +=head2 read_objnum + + $ref = $p->read_objnum($num, $gen, %opts) + +=over Returns a fully read object of given number and generation in this file +=back + =cut sub read_objnum { @@ -1014,12 +1098,18 @@ sub read_objnum { return $object; } # end of read_objnum() -=item $objind = $p->new_obj($obj) +=head2 new_obj + + $objind = $p->new_obj($obj) + +=over Creates a new, free object reference based on free space in the cross reference chain. If nothing is free, then think up a new number. If C<$obj>, then turns that object into this new object rather than returning a new object. +=back + =cut sub new_obj { @@ -1072,11 +1162,17 @@ sub new_obj { } } -=item $p->out_obj($obj) +=head2 out_obj + + $p->out_obj($obj) + +=over Indicates that the given object reference should appear in the output xref table whether with data or freed. +=back + =cut sub out_obj { @@ -1095,10 +1191,16 @@ sub out_obj { return $obj; } -=item $p->free_obj($obj) +=head2 free_obj + + $p->free_obj($obj) + +=over Marks an object reference for output as being freed. +=back + =cut sub free_obj { @@ -1111,10 +1213,16 @@ sub free_obj { return; } -=item $p->remove_obj($objind) +=head2 remove_obj + + $p->remove_obj($objind) + +=over Removes the object from all places where we might remember it. +=back + =cut sub remove_obj { @@ -1132,9 +1240,13 @@ sub remove_obj { return $self; } -=item $p->ship_out(@objects) +=head2 ship_out -=item $p->ship_out() + $p->ship_out(@objects) + + $p->ship_out() + +=over Ships the given objects (or all objects for output if C<@objects> is empty) to the currently open output file (assuming there is one). Freed objects are not @@ -1143,6 +1255,8 @@ becomes its source and it will not be shipped again unless out_obj is called again. Notice that a shipped out object can be re-output or even freed, but that it will not cause the data already output to be changed. +=back + =cut sub ship_out { @@ -1185,12 +1299,18 @@ sub ship_out { return $self; } # end of ship_out() -=item $p->copy($outpdf, \&filter) +=head2 copy + + $p->copy($outpdf, \&filter) + +=over Iterates over every object in the file reading the object, calling C<filter> with the object, and outputting the result. If C<filter> is not defined, just copies input to output. +=back + =cut sub copy { @@ -1237,21 +1357,23 @@ sub copy { return $self; } # end of copy() -=back - =head1 PRIVATE METHODS & FUNCTIONS The following methods and functions are considered B<private> to this class. This does not mean you cannot use them if you have a need, just that they aren't really designed for users of this class. -=over +=head2 locate_obj -=item $offset = $p->locate_obj($num, $gen) + $offset = $p->locate_obj($num, $gen) + +=over Returns a file offset to the object asked for by following the chain of cross reference tables until it finds the one you want. +=back + =cut sub locate_obj { @@ -1274,12 +1396,18 @@ sub locate_obj { return; } -=item update($fh, $str, $instream) +=head2 update + + update($fh, $str, $instream) + +=over Keeps reading C<$fh> for more data to ensure that C<$str> has at least a line full for C<readval> to work on. At this point we also take the opportunity to ignore comments. +=back + =cut sub update { @@ -1311,11 +1439,17 @@ sub update { return $str; } # end of update() -=item $objind = $p->test_obj($num, $gen) +=head2 test_obj + + $objind = $p->test_obj($num, $gen) + +=over Tests the cache to see whether an object reference (which may or may not have been getobj()ed) has been cached. Returns it if it has. +=back + =cut sub test_obj { @@ -1324,10 +1458,16 @@ sub test_obj { return $self->{' objcache'}{$num, $gen}; } -=item $p->add_obj($objind) +=head2 add_obj + + $p->add_obj($objind) + +=over Adds the given object to the internal object cache. +=back + =cut sub add_obj { @@ -1339,7 +1479,11 @@ sub add_obj { return $obj; } -=item $tdict = $p->readxrtr($xpos, %options) +=head2 readxrtr + + $tdict = $p->readxrtr($xpos, %options) + +=over Recursive function which reads each of the cross-reference and trailer tables in turn until there are no more. @@ -1355,6 +1499,8 @@ for details. See C<open> for options allowed. +=back + =cut sub _unpack_xref_stream { @@ -1403,7 +1549,8 @@ sub _unpack_xref_stream { sub readxrtr { my ($self, $xpos, %options) = @_; - # $xpos SHOULD be pointing to "xref" keyword + # $xpos SHOULD be pointing to "xref" keyword + # UNLESS an xref stream is in use (v 1.5+) # copy dashed option names to preferred undashed names if (defined $options{'-diags'} && !defined $options{'diags'}) { $options{'diags'} = delete($options{'-diags'}); } @@ -1423,7 +1570,7 @@ sub readxrtr { # $buf = update($fh, $buf); #} - if ($buf =~ s/^xref$cr//i) { # remove xrefEOL from buffer + if ($buf =~ s/^xref$cr//i) { # xref table, remove xrefEOL from buffer # Plain XRef tables. # # look to match startobj# count# EOL of first (or only) subsection @@ -1610,7 +1757,7 @@ sub readxrtr { ($tdict, $buf) = $self->readval($buf); - } elsif ($buf =~ m/^(\d+)\s+(\d+)\s+obj/i) { + } elsif ($buf =~ m/^(\d+)\s+(\d+)\s+obj/i) { # object for xref stream my ($xref_obj, $xref_gen) = ($1, $2); $PDF::Builder::global_pdf->verCheckOutput(1.5, "importing cross-reference stream"); # XRef streams @@ -1687,14 +1834,20 @@ sub readxrtr { return $tdict; } # end of readxrtr() -=item $p->out_trailer($tdict, $update) +=head2 out_trailer + + $p->out_trailer($tdict, $update) -=item $p->out_trailer($tdict) + $p->out_trailer($tdict) + +=over Outputs the body and trailer for a PDF file by outputting all the objects in the ' outlist' and then outputting a xref table for those objects and any freed ones. It then outputs the trailing dictionary and the trailer code. +=back + =cut sub out_trailer { @@ -1838,10 +1991,16 @@ sub out_trailer { return; } # end of out_trailer() -=item PDF::Builder::Basic::PDF::File->_new() +=head2 _new + + PDF::Builder::Basic::PDF::File->_new() + +=over Creates a very empty PDF file object (used by new() and open()) +=back + =cut sub _new { @@ -1860,13 +2019,11 @@ sub _new { 1; -=back - =head1 AUTHOR Martin Hosken Martin_Hosken@sil.org -Copyright Martin Hosken 1999 and onwards +Copyright Martin Hosken 1999 No warranty or expression of effectiveness, least of all regarding anyone's safety, is implied in this software or documentation. diff --git a/lib/PDF/Builder/Basic/PDF/Filter.pm b/lib/PDF/Builder/Basic/PDF/Filter.pm index f09ac70..1b5c741 100644 --- a/lib/PDF/Builder/Basic/PDF/Filter.pm +++ b/lib/PDF/Builder/Basic/PDF/Filter.pm @@ -18,8 +18,8 @@ package PDF::Builder::Basic::PDF::Filter; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed use PDF::Builder::Basic::PDF::Filter::ASCII85Decode; use PDF::Builder::Basic::PDF::Filter::ASCIIHexDecode; @@ -56,14 +56,22 @@ the same time. =head1 METHODS -=over +=head2 new + + PDF::Builder::Basic::PDF::Filter->new() -=item PDF::Builder::Basic::PDF::Filter->new() +=over Creates a new filter object with empty state information ready for processing data both input and output. -=item $dat = $f->infilt($str, $isend) +=back + +=head2 infilt + + $dat = $f->infilt($str, $isend) + +=over Filters from output to input the data. Notice that C<$isend == 0> implies that there is more data to come and so following it C<$f> may contain state @@ -75,7 +83,13 @@ C<$f> will be that the state information is empty. Error messages are most likely to occur here since if there is required state information to be stored following this data, then that would imply an error in the data. -=item $str = $f->outfilt($dat, $isend) +=back + +=head2 outfilt + + $str = $f->outfilt($dat, $isend) + +=over Filter stored data ready for output. Parallels C<infilt>. diff --git a/lib/PDF/Builder/Basic/PDF/Filter/ASCII85Decode.pm b/lib/PDF/Builder/Basic/PDF/Filter/ASCII85Decode.pm index ea436b8..d5f3e93 100644 --- a/lib/PDF/Builder/Basic/PDF/Filter/ASCII85Decode.pm +++ b/lib/PDF/Builder/Basic/PDF/Filter/ASCII85Decode.pm @@ -5,7 +5,7 @@ use base 'PDF::Builder::Basic::PDF::Filter'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION +our $VERSION = '3.026'; # VERSION our $LAST_UPDATE = '3.010'; # manually update whenever code is changed =head1 NAME diff --git a/lib/PDF/Builder/Basic/PDF/Filter/ASCIIHexDecode.pm b/lib/PDF/Builder/Basic/PDF/Filter/ASCIIHexDecode.pm index b1be2aa..8af79f7 100644 --- a/lib/PDF/Builder/Basic/PDF/Filter/ASCIIHexDecode.pm +++ b/lib/PDF/Builder/Basic/PDF/Filter/ASCIIHexDecode.pm @@ -5,7 +5,7 @@ use base 'PDF::Builder::Basic::PDF::Filter'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION +our $VERSION = '3.026'; # VERSION our $LAST_UPDATE = '2.029'; # manually update whenever code is changed =head1 NAME diff --git a/lib/PDF/Builder/Basic/PDF/Filter/FlateDecode.pm b/lib/PDF/Builder/Basic/PDF/Filter/FlateDecode.pm index 712f9d7..7ed60cc 100644 --- a/lib/PDF/Builder/Basic/PDF/Filter/FlateDecode.pm +++ b/lib/PDF/Builder/Basic/PDF/Filter/FlateDecode.pm @@ -5,8 +5,8 @@ use base 'PDF::Builder::Basic::PDF::Filter'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.016'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed use POSIX qw(ceil floor); @@ -18,18 +18,17 @@ PDF::Builder::Basic::PDF::Filter::FlateDecode - compress and uncompress stream f =cut +# not specifying a minimum version BEGIN { eval { require Compress::Zlib }; $havezlib = !$@; } sub new { - return unless $havezlib; + return unless $havezlib; # undef returned should prove fatal my ($class, $decode_parms) = @_; - my ($self) = { - DecodeParms => $decode_parms, - }; + my ($self) = { 'DecodeParms' => $decode_parms }; $self->{'outfilt'} = Compress::Zlib::deflateInit( -Level => 9, @@ -54,7 +53,7 @@ sub infilt { if ($self->{'DecodeParms'} and $self->{'DecodeParms'}->{'Predictor'}) { my $predictor = $self->{'DecodeParms'}->{'Predictor'}->val(); - if ($predictor == 2) { + if ($predictor == 2) { die "The TIFF predictor logic has not been implemented"; } elsif ($predictor >= 10 and $predictor <= 15) { $result = $self->_depredict_png($result); @@ -74,11 +73,11 @@ sub _depredict_png { $stream = $self->{'_depredict_next'} . $stream if defined $self->{'_depredict_next'}; $prev = $self->{'_depredict_prev'} if defined $self->{'_depredict_prev'}; - my $alpha = $param->{'Alpha'} ? $param->{'Alpha'}->val(): 0; - my $bpc = $param->{'BitsPerComponent'}? $param->{'BitsPerComponent'}->val(): 8; - my $colors = $param->{'Colors'} ? $param->{'Colors'}->val(): 1; - my $columns = $param->{'Columns'} ? $param->{'Columns'}->val(): 1; - my $height = $param->{'Height'} ? $param->{'Height'}->val(): 0; + my $alpha = $param->{'Alpha'} ? $param->{'Alpha'}->val(): 0; + my $bpc = $param->{'BitsPerComponent'} ? $param->{'BitsPerComponent'}->val(): 8; + my $colors = $param->{'Colors'} ? $param->{'Colors'}->val(): 1; + my $columns = $param->{'Columns'} ? $param->{'Columns'}->val(): 1; + my $height = $param->{'Height'} ? $param->{'Height'}->val(): 0; my $comp = $colors + $alpha; my $bpp = ceil($bpc * $comp / 8); diff --git a/lib/PDF/Builder/Basic/PDF/Filter/LZWDecode.pm b/lib/PDF/Builder/Basic/PDF/Filter/LZWDecode.pm index d4e91dd..7d444e6 100644 --- a/lib/PDF/Builder/Basic/PDF/Filter/LZWDecode.pm +++ b/lib/PDF/Builder/Basic/PDF/Filter/LZWDecode.pm @@ -6,8 +6,8 @@ use Carp; use POSIX; use base 'PDF::Builder::Basic::PDF::Filter::FlateDecode'; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.023'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed =head1 NAME @@ -15,10 +15,12 @@ PDF::Builder::Basic::PDF::Filter::LZWDecode - compress and uncompress stream fil =cut +# extensively extended from PDF::API2 version, for TIFF support + sub new { my ($class, $decode_parms) = @_; - my $self = { DecodeParms => $decode_parms, }; + my $self = { 'DecodeParms' => $decode_parms }; bless $self, $class; $self->_reset_code(); @@ -38,15 +40,15 @@ sub infilt { } $self->{'table'} = [ map { chr } 0 .. $self->{'clear_table'} - 1 ]; - while ( $data ne q{} ) { + while ($data ne q{}) { ($code, $partial_code, $partial_bits) = $self->read_dat(\$data, $partial_code, $partial_bits, $self->{'code_length'}); last unless defined $code; unless ($early_change) { - if ($self->{next_code} == (1 << $self->{code_length}) - and $self->{code_length} < 12) { + if ($self->{'next_code'} == (1 << $self->{'code_length'}) + and $self->{'code_length'} < 12) { $self->{'code_length'}++; } } @@ -71,7 +73,7 @@ sub infilt { if ($early_change) { if ($self->{'next_code'} == (1 << $self->{'code_length'}) - and $self->{code_length} < 12) { + and $self->{'code_length'} < 12) { $self->{'code_length'}++; } } @@ -80,8 +82,9 @@ sub infilt { $self->{'partial_bits'} = $partial_bits; if ($self->_predictor_type() == 2) { - return $self->_depredict($result); + return $self->_depredict($result); } + return $result; } @@ -95,30 +98,30 @@ sub outfilt { $self->{'buf'} = q{}; $self->{'buf_pos'} = 0; $self->_write_code($self->{'clear_table'}); - + if ($self->_predictor_type() == 2) { $str = $self->_predict($str); } - + for my $i (0 .. length($str)) { my $char = substr($str, $i, 1); $bytes_in += 1; - + if (exists $self->{'table'}{ $seen . $char }) { $seen .= $char; next; } - + $self->_write_code($self->{'table'}{$seen}); - + $self->_new_code($seen . $char); - + $seen = $char; - + if ($self->{'at_max_code'}) { $self->_write_code($self->{'clear_table'}); $self->_reset_code(); - + undef $checkpoint; undef $last_ratio; } @@ -132,10 +135,10 @@ sub outfilt { } return pack 'B*', $self->{'buf'}; } - + sub _reset_code { my $self = shift; - + $self->{'initial_code_length'} = 9; $self->{'max_code_length'} = 12; $self->{'code_length'} = $self->{'initial_code_length'}; @@ -147,15 +150,15 @@ sub _reset_code { $self->{'table'} = { map { chr $_ => $_ } 0 .. $self->{'clear_table'} - 1 }; return; } - + sub _new_code { my ($self, $word) = @_; - + if ($self->{'at_max_code'} == 0) { $self->{'table'}{$word} = $self->{'next_code'}; $self->{'next_code'} += 1; } - + if ($self->{'next_code'} >= $self->{'next_increase'}) { if ($self->{'code_length'} < $self->{'max_code_length'}) { $self->{'code_length'} += 1; @@ -166,17 +169,17 @@ sub _new_code { } return; } - + sub _write_code { my ($self, $code) = @_; - + if (not defined $code) { return; } - + if ($code > (2**$self->{'code_length'})) { croak "Code $code too large for current code length $self->{'code_length'}"; } - + for my $bit (reverse 0 .. ($self->{'code_length'} - 1)) { if (($code >> $bit) & 1) { $self->{'buf'} .= '1'; @@ -184,20 +187,20 @@ sub _write_code { $self->{'buf'} .= '0'; } } - + $self->{'buf_pos'} += $self->{'code_length'}; return; } - + sub read_dat { my ($self, $data_ref, $partial_code, $partial_bits, $code_length) = @_; if (not defined $partial_bits) { $partial_bits = 0; } if (not defined $partial_code) { $partial_code = 0; } - while ($partial_bits < $code_length ) { + while ($partial_bits < $code_length) { return (undef, $partial_code, $partial_bits) unless length($$data_ref); - $partial_code = ($partial_code << 8 ) + unpack('C', $$data_ref); + $partial_code = ($partial_code << 8) + unpack('C', $$data_ref); substr($$data_ref, 0, 1, q{}); $partial_bits += 8; } @@ -223,7 +226,7 @@ sub _predictor_type { } return 1; } - + sub _depredict { my ($self, $data) = @_; my $param = $self->{'DecodeParms'}; @@ -233,7 +236,7 @@ sub _depredict { my $colors = $param->{'Colors'} ? $param->{'Colors'}->val() : 1; my $columns = $param->{'Columns'} ? $param->{'Columns'}->val() : 1; my $rows = $param->{'Rows'} ? $param->{'Rows'}->val() : 0; - + my $comp = $colors + $alpha; my $bpp = ceil($bpc * $comp / 8); my $max = 256; @@ -252,7 +255,7 @@ sub _depredict { } return $data; } - + sub _predict { my ($self, $data) = @_; my $param = $self->{'DecodeParms'}; @@ -262,7 +265,7 @@ sub _predict { my $colors = $param->{'Colors'} ? $param->{'Colors'}->val() : 1; my $columns = $param->{'Columns'} ? $param->{'Columns'}->val() : 1; my $rows = $param->{'Rows'} ? $param->{'Rows'}->val() : 0; - + my $comp = $colors + $alpha; my $bpp = ceil($bpc * $comp / 8); my $max = 256; @@ -281,5 +284,5 @@ sub _predict { } return $data; } - + 1; diff --git a/lib/PDF/Builder/Basic/PDF/Filter/RunLengthDecode.pm b/lib/PDF/Builder/Basic/PDF/Filter/RunLengthDecode.pm index a4ab760..2e44356 100644 --- a/lib/PDF/Builder/Basic/PDF/Filter/RunLengthDecode.pm +++ b/lib/PDF/Builder/Basic/PDF/Filter/RunLengthDecode.pm @@ -5,7 +5,7 @@ use base 'PDF::Builder::Basic::PDF::Filter'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION +our $VERSION = '3.026'; # VERSION our $LAST_UPDATE = '2.029'; # manually update whenever code is changed =head1 NAME diff --git a/lib/PDF/Builder/Basic/PDF/Literal.pm b/lib/PDF/Builder/Basic/PDF/Literal.pm index 299d5f0..0e30ea5 100644 --- a/lib/PDF/Builder/Basic/PDF/Literal.pm +++ b/lib/PDF/Builder/Basic/PDF/Literal.pm @@ -6,7 +6,7 @@ use base 'PDF::Builder::Basic::PDF::Objind'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION +our $VERSION = '3.026'; # VERSION our $LAST_UPDATE = '3.024'; # manually update whenever code is changed use PDF::Builder::Basic::PDF::Filter; diff --git a/lib/PDF/Builder/Basic/PDF/Name.pm b/lib/PDF/Builder/Basic/PDF/Name.pm index fe1b94b..5402a71 100644 --- a/lib/PDF/Builder/Basic/PDF/Name.pm +++ b/lib/PDF/Builder/Basic/PDF/Name.pm @@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::String'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed =head1 NAME @@ -30,14 +30,18 @@ and stores PDF names (things beginning with /) =head1 METHODS -=over +=head2 from_pdf + + $n = PDF::Builder::Basic::PDF::Name->from_pdf($string) -=item $n = PDF::Builder::Basic::PDF::Name->from_pdf($string) +=over Creates a new string object (not a full object yet) from a given -string. The string is parsed according to input criteria with +string. The string is parsed according to input criteria with escaping working, particular to Names. +=back + =cut sub from_pdf { @@ -49,11 +53,17 @@ sub from_pdf { return $self; } -=item $n->convert($string, $pdf) +=head2 convert + + $n->convert($string, $pdf) + +=over Converts a name into a string by removing the / and converting any hex munging. +=back + =cut sub convert { @@ -63,11 +73,17 @@ sub convert { return $string; } -=item $s->as_pdf($pdf) +=head2 as_pdf + + $s->as_pdf($pdf) + +=over Returns a name formatted as PDF. C<$pdf> is optional but should be the PDF File object for which the name is intended if supplied. +=back + =cut sub as_pdf { @@ -84,11 +100,17 @@ sub as_pdf { # spaces were implicitly allowed in names as well but it would be best # to ignore that (PDF 1.3, section H.3.2.4.3). -=item PDF::Builder::Basic::PDF::Name->string_to_name($string, $pdf) +=head2 string_to_name + + PDF::Builder::Basic::PDF::Name->string_to_name($string, $pdf) + +=over Suitably encode the string C<$string> for output in the File object C<$pdf> (the exact format may depend on the version of $pdf). +=back + =cut sub string_to_name { @@ -102,12 +124,18 @@ sub string_to_name { return $string; } -=item PDF::Builder::Basic::PDF::Name->name_to_string($string, $pdf) +=head2 name_to_string + + PDF::Builder::Basic::PDF::Name->name_to_string($string, $pdf) + +=over Suitably decode the string C<$string> as read from the File object C<$pdf> (the exact decoding may depend on the version of $pdf). Principally, undo the hex encoding for PDF versions > 1.1. +=back + =cut sub name_to_string { @@ -123,8 +151,4 @@ sub name_to_string { return $string; } -=back - -=cut - 1; diff --git a/lib/PDF/Builder/Basic/PDF/Null.pm b/lib/PDF/Builder/Basic/PDF/Null.pm index ad2ff08..8a8ad71 100644 --- a/lib/PDF/Builder/Basic/PDF/Null.pm +++ b/lib/PDF/Builder/Basic/PDF/Null.pm @@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::Objind'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed =head1 NAME @@ -30,37 +30,53 @@ PDF::Builder::Basic::PDF::Objind and cannot be subclassed. =head1 METHODS -=over - =cut # There is only one null object (section 3.2.8). my $null_obj = bless {}, 'PDF::Builder::Basic::PDF::Null'; -=item PDF::Builder::Basic::PDF::Null->new() +=head2 new + + PDF::Builder::Basic::PDF::Null->new() + +=over Returns the null object. There is only one null object. +=back + =cut sub new { return $null_obj; } -=item $s->realise() +=head2 realise + + $s->realise() + +=over Pretends to finish reading the object. +=back + =cut sub realise { return $null_obj; } -=item $s->outobjdeep() +=head2 outobjdeep + + $s->outobjdeep() + +=over Output the object in PDF format. +=back + =cut sub outobjdeep { @@ -70,38 +86,52 @@ sub outobjdeep { return; } -=item $s->is_obj() +=head2 is_obj + + $s->is_obj() + +=over Returns false because null is not a full object. +=back + =cut sub is_obj { return 0; } -=item $s->copy() +=head2 copy + + $s->copy() + +=over Another no-op. +=back + =cut sub copy { return $null_obj; } -=item $s->val() +=head2 val + + $s->val() + +=over Return undef. +=back + =cut sub val { return undef; ## no critic (undef is intentional) } -=back - -=cut - 1; diff --git a/lib/PDF/Builder/Basic/PDF/Number.pm b/lib/PDF/Builder/Basic/PDF/Number.pm index 7cdde2c..3426a7b 100644 --- a/lib/PDF/Builder/Basic/PDF/Number.pm +++ b/lib/PDF/Builder/Basic/PDF/Number.pm @@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::String'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed =head1 NAME @@ -29,30 +29,36 @@ PDF::Builder::Basic::PDF::Number - Numbers in PDF. Inherits from L<PDF::Builder: =head1 METHODS -=over +=head2 convert + + $n->convert($str) -=item $n->convert($str) +=over Converts a string from PDF to internal, by doing nothing +=back + =cut sub convert { return $_[1]; } -=item $n->as_pdf() +=head2 as_pdf + + $n->as_pdf() + +=over Converts a number to PDF format +=back + =cut sub as_pdf { return $_[0]->{'val'}; } -=back - -=cut - 1; diff --git a/lib/PDF/Builder/Basic/PDF/Objind.pm b/lib/PDF/Builder/Basic/PDF/Objind.pm index 5553446..628e37c 100644 --- a/lib/PDF/Builder/Basic/PDF/Objind.pm +++ b/lib/PDF/Builder/Basic/PDF/Objind.pm @@ -19,8 +19,8 @@ use strict; use warnings; use Scalar::Util 'isweak'; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed =head1 NAME @@ -63,8 +63,6 @@ Holds a direct reference to the next free object in the free list. =head1 METHODS -=over - =cut use Scalar::Util qw(blessed reftype weaken); @@ -76,10 +74,16 @@ $uidc = "pdfuid000"; @inst = qw(parent objnum objgen isfree nextfree uid realised); $inst{" $_"} = 1 for @inst; -=item PDF::Builder::Basic::PDF::Objind->new() +=head2 new + + PDF::Builder::Basic::PDF::Objind->new() + +=over Creates a new indirect object +=back + =cut sub new { @@ -88,10 +92,16 @@ sub new { return bless {}, ref $class || $class; } -=item $UID = $r->uid() +=head2 uid + + $UID = $r->uid() + +=over Returns a Unique id for this object, creating one if it didn't have one before +=back + =cut sub uid { @@ -99,7 +109,11 @@ sub uid { return $_[0]->{' uid'}; } -=item $r->release() +=head2 release + + $r->release() + +=over Releases ALL of the memory used by this indirect object, and all of its component/child objects. This method is called automatically by @@ -113,6 +127,8 @@ references within our own internal data structures. Calling 'C<release()>' forces these circular references to be cleaned up and the entire internal data structure purged. +=back + =cut # Maintainer's Question: Couldn't this be handled by a DESTROY method @@ -143,7 +159,11 @@ sub release { return; } -=item $value = $r->val() +=head2 val + + $value = $r->val() + +=over Returns the value of this object or reads the object and then returns its value. @@ -151,6 +171,8 @@ its value. Note that all direct subclasses *must* make their own versions of this subroutine otherwise we could be in for a very deep loop! +=back + =cut sub val { @@ -170,10 +192,16 @@ sub val { } } -=item $r->realise() +=head2 realise + + $r->realise() + +=over Makes sure that the object is fully read in, etc. +=back + =cut sub realise { @@ -184,12 +212,18 @@ sub realise { return $self; } -=item $v = $r->outobjdeep($fh, $pdf) +=head2 outobjdeep + + $v = $r->outobjdeep($fh, $pdf) + +=over If you really want to output this object, then you need to read it first. This also means that all direct subclasses must subclass this method, or they will loop forever! +=back + =cut sub outobjdeep { @@ -209,11 +243,17 @@ sub outobjdeep { } } -=item $r->outobj($fh, $pdf) +=head2 outobj + + $r->outobj($fh, $pdf) + +=over If this is a full object then outputs a reference to the object, otherwise calls outobjdeep to output the contents of the object at this point. +=back + =cut sub outobj { @@ -227,18 +267,19 @@ sub outobj { return; } -=item $s = $r->elements() +=head2 elements + + $s = $r->elements() + +=over Abstract superclass function filler. Returns self here but should return something more useful if an array. -The old name of this method, C<elementsof>, has been B<deprecated> and will -be removed in the future. +=back =cut -sub elementsof { return elements(@_); } - sub elements { my ($self) = @_; @@ -249,12 +290,18 @@ sub elements { } } -=item $s = $r->empty() +=head2 empty + + $s = $r->empty() + +=over Empties all content from this object to free up memory or to be read to pass the object into the free list. Simplistically undefs all instance variables other than object number and generation. +=back + =cut sub empty { @@ -267,13 +314,19 @@ sub empty { return $self; } -=item $o = $r->merge($objind) +=head2 merge + + $o = $r->merge($objind) + +=over This merges content information into an object reference placeholder. This occurs when an object reference is read before the object definition and the information in the read data needs to be merged into the object placeholder. +=back + =cut sub merge { @@ -291,19 +344,29 @@ sub merge { return bless $self, ref($other); } -=item $r->is_obj($pdf) +=head2 is_obj + + $r->is_obj($pdf) + +=over Returns whether this object is a full object with its own object number or whether it is purely a sub-object. C<$pdf> indicates which output file we are concerned that the object is an object in. +=back + =cut sub is_obj { return defined $_[1]->{' objects'}{$_[0]->uid()}; } -=item $r->copy($pdf, $res) +=head2 copy + + $r->copy($pdf, $res) + +=over Returns a new copy of this object. The object is assumed to be some kind of associative array and the copy is a deep copy for elements which are @@ -317,6 +380,8 @@ new one. It is up to the caller to bless C<$res>, etc. Notice that elements from C<$self> are not copied into C<$res> if there is already an entry for them existing in C<$res>. +=back + =cut sub copy { @@ -338,8 +403,4 @@ sub copy { return $res; } -=back - -=cut - 1; diff --git a/lib/PDF/Builder/Basic/PDF/Page.pm b/lib/PDF/Builder/Basic/PDF/Page.pm index 2f66457..0824e4e 100644 --- a/lib/PDF/Builder/Basic/PDF/Page.pm +++ b/lib/PDF/Builder/Basic/PDF/Page.pm @@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::Pages'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.022'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed use PDF::Builder::Basic::PDF::Dict; use PDF::Builder::Basic::PDF::Utils; @@ -52,9 +52,11 @@ The currently open stream =head1 METHODS -=over +=head2 new + + PDF::Builder::Basic::PDF::Page->new($pdf, $parent, $index) -=item PDF::Builder::Basic::PDF::Page->new($pdf, $parent, $index) +=over Creates a new page based on a pages object (perhaps the root object). @@ -68,6 +70,8 @@ are either optional or can be inherited. The optional index value indicates the index in the parent list that this page should be inserted (so that new pages need not be appended) +=back + =cut sub new { @@ -87,7 +91,11 @@ sub new { # the add() method was deleted from PDF::API2 2.034, but it looks like it # still may be used in Builder.pm! apparently calls Content.pm's add(). -#=item $p->add($str) +#=head2 add +# +# $p->add($str) +# +#=over # #Adds the string to the currently active stream for this page. If no stream #exists, then one is created and added to the list of streams for this page. @@ -95,6 +103,8 @@ sub new { #The slightly cryptic name is an aim to keep it short given the number of times #people are likely to have to type it. # +#=back +# #=cut # #sub add { @@ -120,10 +130,16 @@ sub new { # return $self; #} -=item $p->ship_out($pdf) +=head2 ship_out + + $p->ship_out($pdf) + +=over Ships the page out to the given output file context +=back + =cut sub ship_out { @@ -137,8 +153,4 @@ sub ship_out { return $self; } -=back - -=cut - 1; diff --git a/lib/PDF/Builder/Basic/PDF/Pages.pm b/lib/PDF/Builder/Basic/PDF/Pages.pm index 569304d..707c8f0 100644 --- a/lib/PDF/Builder/Basic/PDF/Pages.pm +++ b/lib/PDF/Builder/Basic/PDF/Pages.pm @@ -20,8 +20,8 @@ use warnings; use base 'PDF::Builder::Basic::PDF::Dict'; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed use PDF::Builder::Basic::PDF::Array; use PDF::Builder::Basic::PDF::Dict; @@ -43,9 +43,11 @@ themselves. =head1 METHODS -=over +=head2 new + + PDF::Builder::Basic::PDF::Pages->new($pdf, $parent) -=item PDF::Builder::Basic::PDF::Pages->new($pdf, $parent) +=over This creates a new Pages object in a PDF. Notice that the C<$parent> here is not the file context for the object, but the parent pages object for these @@ -55,6 +57,8 @@ I<Pages>. C<$pdf> is the file object (or a reference to an array of I<one> file object [3.016 and later, or multiple file objects earlier]) in which to create the new Pages object. +=back + =cut sub new { @@ -96,7 +100,11 @@ sub new { # return $self; #} -#=item $p->out_obj($is_new) +#=head2 out_obj +# +# $p->out_obj($is_new) +# +#=over # #Tells all the files that this thing is destined for that they should output this #object, come time to output. If this object has no parent, then it must be the @@ -104,6 +112,8 @@ sub new { #If C<$is_new> is set, then call C<new_obj> rather than C<out_obj> to create as #a new object in the file. # +#=back +# #=cut # #sub out_obj { @@ -130,11 +140,17 @@ sub _pdf { return $self->get_top()->{' parent'}; } -=item $p->find_page($page_number) +=head2 find_page + + $p->find_page($page_number) + +=over Returns the given page, using the page count values in the pages tree. Pages start at 0. +=back + =cut sub find_page { @@ -165,7 +181,11 @@ sub find_page_recursively { return; } -=item $p->add_page($page, $page_number) +=head2 add_page + + $p->add_page($page, $page_number) + +=over Inserts the page before the given C<$page_number>. C<$page_number> can be negative to count backwards from the END of the document. -1 is after the last @@ -178,6 +198,8 @@ document may simply be inserted in the appropriate leaf in the pages tree without adding any new branches or leaves, leaving it unbalanced (slower performance, but still usable). +=back + =cut # -- removed from end of second para: @@ -237,10 +259,10 @@ sub add_page_recursively { my ($self, $page, $page_index) = @_; my $parent = $self; - my $max_kids_per_parent = 8; # Why 8? + my $max_kids_per_parent = 8; # Why 8? effort to somewhat balance tree? if (scalar $parent->{'Kids'}->elements() >= $max_kids_per_parent and $parent->{'Parent'} and - $page_index < 1) { + $page_index < 0) { my $grandparent = $parent->{'Parent'}->realise(); $parent = $parent->new($parent->_pdf(), $grandparent); @@ -275,7 +297,11 @@ sub set_modified { return; } -#=item $root_pages = $p->rebuild_tree([@pglist]) +#=head2 rebuild_tree +# +# $root_pages = $p->rebuild_tree([@pglist]) +# +#=over # #B<WARNING: Not yet implemented. Do not attempt to use!> # @@ -285,6 +311,8 @@ sub set_modified { # #Returns the top of the tree for insertion in the root object. # +#=back +# #=cut # TBD where's the code? @@ -293,10 +321,16 @@ sub set_modified { # return; #} -=item @objects = $p->get_pages() +=head2 get_pages + + @objects = $p->get_pages() + +=over Returns a list of page objects in the document, in page order. +=back + =cut sub get_pages { @@ -325,10 +359,16 @@ sub get_pages_recursively { return @pages; } -=item $p->find_prop($key) +=head2 find_prop + + $p->find_prop($key) + +=over Searches up through the inheritance tree to find a property (key). +=back + =cut sub find_prop { @@ -354,7 +394,11 @@ sub find_prop { return; } -=item $p->add_font($pdf, $font) +=head2 add_font + + $p->add_font($pdf, $font) + +=over Creates or edits the resource dictionary at this level in the hierarchy. If the font is already supported, even through the hierarchy, then it is not added. @@ -364,6 +408,8 @@ swapped the order of C<$pdf> and C<$font>, requiring ad hoc swapping of parameters in user code, contrary to the POD definition above. Now the code matches the documentation. +=back + =cut sub add_font { @@ -395,14 +441,20 @@ sub add_font { return $self; } # end of add_font() -=item $p->bbox($xmin,$ymin, $xmax,$ymax, $param) +=head2 bbox + + $p->bbox($xmin,$ymin, $xmax,$ymax, $param) -=item $p->bbox($xmin,$ymin, $xmax,$ymax) + $p->bbox($xmin,$ymin, $xmax,$ymax) + +=over Specifies the bounding box for this and all child pages. If the values are identical to those inherited, no change is made. C<$param> specifies the attribute name so that other 'bounding box'es can be set with this method. +=back + =cut sub bbox { @@ -428,11 +480,17 @@ sub bbox { return $self; } -=item $p->proc_set(@entries) +=head2 proc_set + + $p->proc_set(@entries) + +=over Ensures that the current resource contains all the entries in the proc_sets listed. If necessary, it creates a local resource dictionary to achieve this. +=back + =cut sub proc_set { @@ -474,10 +532,16 @@ sub empty { return $self; } -=item $p->get_top() +=head2 get_top + + $p->get_top() + +=over Returns the top of the pages tree. +=back + =cut sub get_top { @@ -489,8 +553,4 @@ sub get_top { return $top->realise(); } -=back - -=cut - 1; diff --git a/lib/PDF/Builder/Basic/PDF/String.pm b/lib/PDF/Builder/Basic/PDF/String.pm index 526a85b..3371103 100644 --- a/lib/PDF/Builder/Basic/PDF/String.pm +++ b/lib/PDF/Builder/Basic/PDF/String.pm @@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::Objind'; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed =head1 NAME @@ -30,8 +30,6 @@ for simple objects that are basically stringlike (Number, Name, etc.) =head1 METHODS -=over - =cut our %trans = ( @@ -56,12 +54,18 @@ our %out_trans = ( ')' => ')', ); -=item PDF::Builder::Basic::PDF::String->from_pdf($string) +=head2 from_pdf + + PDF::Builder::Basic::PDF::String->from_pdf($string) + +=over Creates a new string object (not a full object yet) from a given string. The string is parsed according to input criteria with escaping working. +=back + =cut sub from_pdf { @@ -74,12 +78,18 @@ sub from_pdf { return $self; } -=item PDF::Builder::Basic::PDF::String->new($string) +=head2 new + + PDF::Builder::Basic::PDF::String->new($string) + +=over Creates a new string object (not a full object yet) from a given string. The string is parsed according to input criteria with escaping working. +=back + =cut sub new { @@ -92,10 +102,16 @@ sub new { return $self; } -=item $s->convert($str) +=head2 convert + + $s->convert($str) + +=over Returns $str converted as per criteria for input from PDF file +=back + =cut sub convert { @@ -171,20 +187,32 @@ sub convert { return $output; } -=item $s->val() +=head2 val + + $s->val() + +=over Returns the value of this string (the string itself). +=back + =cut sub val { return $_[0]->{'val'}; } -=item $s->as_pdf() +=head2 as_pdf + + $s->as_pdf() + +=over Returns the string formatted for output as PDF for PDF File object $pdf. +=back + =cut sub as_pdf { @@ -210,10 +238,16 @@ sub as_pdf { } } -=item $s->outobjdeep($fh, $pdf) +=head2 outobjdeep + + $s->outobjdeep($fh, $pdf) + +=over Outputs the string in PDF format, complete with necessary conversions. +=back + =cut sub outobjdeep { @@ -223,8 +257,4 @@ sub outobjdeep { return; } -=back - -=cut - 1; diff --git a/lib/PDF/Builder/Basic/PDF/Utils.pm b/lib/PDF/Builder/Basic/PDF/Utils.pm index a008c9e..8b3f7ed 100644 --- a/lib/PDF/Builder/Basic/PDF/Utils.pm +++ b/lib/PDF/Builder/Basic/PDF/Utils.pm @@ -18,8 +18,8 @@ package PDF::Builder::Basic::PDF::Utils; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed =head1 NAME @@ -29,9 +29,7 @@ PDF::Builder::Basic::PDF::Utils - Utility functions for PDF library A set of utility functions to save the fingers of the PDF library users! -=head1 FUNCTIONS - -=over +=head1 METHODS =cut @@ -50,67 +48,107 @@ use vars qw(@EXPORT @ISA); @EXPORT = qw(PDFBool PDFArray PDFDict PDFName PDFNull PDFNum PDFString PDFStr PDFStrHex PDFUtf); -=item PDFBool() +=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(@_); } -=item PDFArray() +=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(@_); } -=item PDFDict() +=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(@_); } -=item PDFName() +=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(@_); } -=item PDFNull() +=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(@_); } -=item PDFNum() +=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(@_); } -=item PDFString($text, $usage) +=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> @@ -155,6 +193,8 @@ Any other usage where UTF-8 text is B<not> permitted. =back +=back + =cut sub PDFString { @@ -184,22 +224,34 @@ sub PDFString { } } -=item PDFStr() +=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(@_); } -=item PDFStrHex() +=head2 PDFStrHex + + PDFStrHex() + +=over Creates a hex-string via PDF::Builder::Basic::PDF::String->new() +=back + =cut sub PDFStrHex { @@ -208,12 +260,18 @@ sub PDFStrHex { return $string; } -=item PDFUtf() +=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 { @@ -222,8 +280,4 @@ sub PDFUtf { return $string; } -=back - -=cut - 1; |