Changes for version 2.042 - 2021-09-16

  • This release includes many changes to method names, options, and documentation aimed at improving approachability, but existing code should continue to work. See the new Backward Compatibility section in the main PDF::API2 documentation for details about deprecation timelines and a suggested workflow for handling upgrades. See the new Migration section for a consolidated list of deprecated methods/options and their replacements.
  • Renamed several methods in the PDF::API2 base class:
    • end -> close
    • open_scalar -> from_string
    • stringify -> to_string
    • pages -> page_count
    • importPageIntoForm -> embed_page
    • isEncrypted -> is_encrypted
    • xmpMetadata -> xml_metadata
    • outlines -> outline
  • Merged saveas into save.
  • Added individual accessors for PDF metadata (title, author, producer, etc.). Replaced info and infoMetaAttributes with info_metadata for custom metadata.
  • Renamed the following methods in the PDF::API2::Page class:
    • gfx -> graphics
    • rotate -> rotation
  • Added $page->boundaries() and $pdf->default_page_boundaries() to replace the separate methods for the various page boundaries. The supported arguments are slightly different; some edge cases have been removed and new options have been added. See below and the PDF::API2::Page documentation for details.
  • Added $page->size() and $pdf->default_page_size() as a shortcut for setting the media box.
  • Both $page->size() and $page->boundaries() (and their $pdf default equivalents) now accept "WxH" page sizes in inches (e.g. 11x17 or 8.5x11). This does not apply to the deprecated versions of these methods.
  • Both $page->size() and $page->boundaries() (and their $pdf default equivalents) now accept a single number for page boundaries other than the media box, representing an amount in points to shrink the next larger box. This does not apply to the deprecated versions of these methods.
  • Replaced pageLabel with page_labels. The option syntax is slightly different (pass options as a hash instead of a hashref; remove hyphens from option names).
  • Replaced image_jpeg, image_tiff, image_pnm, image_png, image_gif, and image_gd with $pdf->image.
  • Replaced the individual barcode methods with $pdf->barcode, which is fully documented and includes reasonable defaults based on the chosen barcode format.
  • Improved spacing between barcodes and labels when both bar_extend (formerly -lmzn) and font_size (formerly -fnsz) are set and the font size is larger than the bar extension.
  • Replaced corefont, ttfont, psfont, and bdfont with $pdf->font. Unlike corefont, font requires the exact name of one of the standard fonts. Kerning is on by default (vs. off by default in the type-specific methods).
  • Renamed synfont to synthetic_font. Renamed and documented the options. The new hscale option (formerly -slant) now takes a percentage (100 = no change, vs. 1 = no change for -slant) to match the hscale method in Content. The new "bold" option is in thousandths of a text unit, vs. hundredths for "-bold", so multiply the old value by 10 when migrating.
  • Replaced the individual colorspace methods with $pdf->colorspace. Added documentation and examples for the various colorspace types except for the former colorspace_hue, because I couldn't find the standard that it implements (if one exists).
  • Renamed several methods in PDF::API2::Content:
    • linewidth -> line_width
    • linecap -> line_cap
    • linejoin -> line_join
    • miterlimit -> miter_limit
    • flatness -> flatness_tolerance
    • endpath -> end
    • rectxy -> rectangle
    • fillstroke -> paint
    • charspace -> character_spacing
    • wordspace -> word_spacing
    • nl -> crlf
    • advancewidth -> text_width
  • In PDF::API2::Content, replaced image and formimage with object. Added a $page->object() convenience method that is equivalent to $page->graphics->object().
  • In PDF::API2::Content, merged text_center and text_right into text. Use the "align" option to set alignment to "center" or "right".
  • In PDF::API2::Content, merged paragraphs into paragraph.
  • In PDF::API2::Content, deprecated poly and added polyline. poly was the only path-drawing method that took a starting position as its first two arguments. These should be passed to a move call instead, with the remaining arguments passed to the new polyline method.
  • In PDF::API2::Content, added position, which combines the functionality of distance and textpos2 (which was undocumented). Deprecated textpos, which attempted to return the position of the "cursor" after taking into account coordinate transformations. textpos2 and the new position method return the text position before any coordinate transformations are applied, which is consistent with how the other methods in this class behave.
  • In PDF::API2::Content, deprecated bogen. Recreate using arc, if feasible. If not, I'm likely to leave the code in place indefinitely as an undocumented method.
  • In PDF::API2::Content, deprecated cr. Replace with either position (if called with arguments) or crlf (if called without arguments).
  • Tentatively deprecated $pdf->cjkfont. If you're successfully using this method for CJK font support, read PDF::API2::Resource::CIDFont::CJKFont and contact me to discuss your use case.
  • Tentatively deprecated $pdf->unifont. If you're successfully using this method for Unicode support, please contact me to discuss your use case.
  • Replaced $pdf->preferences() with separate page_mode, page_layout, viewer_preferences, and open_action methods, all of which are now fully documented.
  • Added font_path and set_font_path accessors for the font search path (the list of directories searched when a font name is included without its full path). Renamed addFontDirs to add_to_font_path.
  • Removed C:/WinNT/Fonts from the default font search path.
  • Named Destinations are now fully documented, with updated method names and arguments.
  • Outlines are now fully documented, with additional methods for examining and modifying the outline tree. Existing method names and arguments have been updated to match those used in Named Destinations. Various bugs have been fixed when reading or modifying outlines in existing PDFs.
  • Updated annotation documentation. Revised methods and arguments to match those used in Named Destinations and Outlines.
  • A PDF version number specified in the document catalog is now respected by $pdf->version().
  • Fixed space calculation between words in justified text (report and fix by Vladislav Glinsky).

Modules

Create, modify, and examine PDF files
Add annotations to a PDF
Low-level PDF array object
Low-level PDF boolean object true or false
Low-level dictionary and stream objects
Low-level PDF file access
Abstract superclass for PDF stream filters
Low-level PDF name object
Low-level PDF null object
Low-level PDF numeric object
Low-level PDF indirect object
Low-level PDF page object
Low-level page tree object
Low-level PDF string object
Convenience functions for creating low-level PDF objects
Methods for adding graphics and text to a PDF
(do not use)
Add named destinations (views) to a PDF
Manage PDF outlines (a.k.a. bookmarks)
Methods to interact with individual pages
Base class for PDF resources
Base class for font resources
Base class for CID fonts
Deprecated base class for CJK fonts
Base class for PDF color spaces
Support for color space separations
Graphics state dictionary support
Module for using bitmapped Fonts.
Module for using the 14 standard PDF fonts.
Module for creating synthetic Fonts.
Base class for external objects
Base class for external form objects
Base class for one-dimensional barcodes
Code 128 and EAN-128 barcode support
Base class for external raster image objects
How the PDF should be displayed or printed

Provides

in lib/PDF/API2/Win32.pm
in lib/PDF/API2/Basic/PDF/Filter/ASCII85Decode.pm
in lib/PDF/API2/Basic/PDF/Filter/ASCIIHexDecode.pm
in lib/PDF/API2/Basic/PDF/Filter/FlateDecode.pm
in lib/PDF/API2/Basic/PDF/Filter/LZWDecode.pm
in lib/PDF/API2/Basic/PDF/Filter/RunLengthDecode.pm
in lib/PDF/API2/Basic/PDF/Literal.pm
in lib/PDF/API2/Content/Text.pm
in lib/PDF/API2/Matrix.pm
in lib/PDF/API2/Outlines.pm
in lib/PDF/API2/Resource/CIDFont/TrueType/FontFile.pm
in lib/PDF/API2/Resource/ColorSpace/DeviceN.pm
in lib/PDF/API2/Resource/ColorSpace/Indexed.pm
in lib/PDF/API2/Resource/ColorSpace/Indexed/Hue.pm
in lib/PDF/API2/Resource/ColorSpace/Indexed/WebColor.pm
in lib/PDF/API2/Resource/Colors.pm
in lib/PDF/API2/Resource/Font.pm
in lib/PDF/API2/Resource/Font/CoreFont/bankgothic.pm
in lib/PDF/API2/Resource/Font/CoreFont/courier.pm
in lib/PDF/API2/Resource/Font/CoreFont/courierbold.pm
in lib/PDF/API2/Resource/Font/CoreFont/courierboldoblique.pm
in lib/PDF/API2/Resource/Font/CoreFont/courieroblique.pm
in lib/PDF/API2/Resource/Font/CoreFont/georgia.pm
in lib/PDF/API2/Resource/Font/CoreFont/georgiabold.pm
in lib/PDF/API2/Resource/Font/CoreFont/georgiabolditalic.pm
in lib/PDF/API2/Resource/Font/CoreFont/georgiaitalic.pm
in lib/PDF/API2/Resource/Font/CoreFont/helvetica.pm
in lib/PDF/API2/Resource/Font/CoreFont/helveticabold.pm
in lib/PDF/API2/Resource/Font/CoreFont/helveticaboldoblique.pm
in lib/PDF/API2/Resource/Font/CoreFont/helveticaoblique.pm
in lib/PDF/API2/Resource/Font/CoreFont/symbol.pm
in lib/PDF/API2/Resource/Font/CoreFont/timesbold.pm
in lib/PDF/API2/Resource/Font/CoreFont/timesbolditalic.pm
in lib/PDF/API2/Resource/Font/CoreFont/timesitalic.pm
in lib/PDF/API2/Resource/Font/CoreFont/timesroman.pm
in lib/PDF/API2/Resource/Font/CoreFont/trebuchet.pm
in lib/PDF/API2/Resource/Font/CoreFont/trebuchetbold.pm
in lib/PDF/API2/Resource/Font/CoreFont/trebuchetbolditalic.pm
in lib/PDF/API2/Resource/Font/CoreFont/trebuchetitalic.pm
in lib/PDF/API2/Resource/Font/CoreFont/verdana.pm
in lib/PDF/API2/Resource/Font/CoreFont/verdanabold.pm
in lib/PDF/API2/Resource/Font/CoreFont/verdanabolditalic.pm
in lib/PDF/API2/Resource/Font/CoreFont/verdanaitalic.pm
in lib/PDF/API2/Resource/Font/CoreFont/webdings.pm
in lib/PDF/API2/Resource/Font/CoreFont/wingdings.pm
in lib/PDF/API2/Resource/Font/CoreFont/zapfdingbats.pm
in lib/PDF/API2/Resource/Font/Postscript.pm
in lib/PDF/API2/Resource/Glyphs.pm
in lib/PDF/API2/Resource/PaperSizes.pm
in lib/PDF/API2/Resource/Pattern.pm
in lib/PDF/API2/Resource/Shading.pm
in lib/PDF/API2/Resource/UniFont.pm
in lib/PDF/API2/Resource/XObject/Form/BarCode/codabar.pm
in lib/PDF/API2/Resource/XObject/Form/BarCode/code3of9.pm
in lib/PDF/API2/Resource/XObject/Form/BarCode/ean13.pm
in lib/PDF/API2/Resource/XObject/Form/BarCode/int2of5.pm
in lib/PDF/API2/Resource/XObject/Form/Hybrid.pm
in lib/PDF/API2/Resource/XObject/Image/GD.pm
in lib/PDF/API2/Resource/XObject/Image/GIF.pm
in lib/PDF/API2/Resource/XObject/Image/JPEG.pm
in lib/PDF/API2/Resource/XObject/Image/PNG.pm
in lib/PDF/API2/Resource/XObject/Image/PNM.pm
in lib/PDF/API2/Resource/XObject/Image/TIFF/File.pm
in lib/PDF/API2/UniWrap.pm
in lib/PDF/API2/Util.pm
in lib/PDF/API2/Win32.pm