The PDF::Reader library implements a PDF parser conforming as much as possible to the PDF specification from Adobe.
It provides programmatic access to the contents of a PDF file with a high degree of flexibility.
The PDF 1.7 specification is a weighty document and not all aspects are currently supported. I welcome submission of PDF files that exhibit unsupported aspects of the spec to assist with improving our support.
The recommended installation method is via Rubygems.
gem install pdf-reader
Begin by creating a PDF::Reader instance that points to a PDF file. Document level information (metadata, page count, bookmarks, etc) is available via this object.
reader = PDF::Reader.new("somefile.pdf") puts reader.pdf_version puts reader.info puts reader.metadata puts reader.page_count
PDF is a page based file format, so most visible information is available via page-based iteration
reader = PDF::Reader.new("somefile.pdf") reader.pages.each do |page| puts page.fonts puts page.images puts page.text end
For low level access to the objects in a PDF file, use the ObjectHash class. You can build an ObjectHash instance directly:
or via a PDF::Reader instance:
reader = PDF::Reader.new("somefile.pdf") puts reader.objects
Internally, text can be stored inside a PDF in various encodings, including zingbats, win-1252, mac roman and a form of Unicode. To avoid confusion, all text will be converted to UTF-8 before it is passed back from PDF::Reader.
Strings that contain binary data (like font blobs) will be marked as such on M17N aware VMs.
There are two key exceptions that you will need to watch out for when processing a PDF file:
MalformedPDFError - The PDF appears to be corrupt in some way. If you believe the file should be valid, or that a corrupt file didn't raise an exception, please forward a copy of the file to the maintainers (preferably via the google group) and we can attempt to improve the code.
UnsupportedFeatureError - The PDF uses a feature that PDF::Reader doesn't currently support. Again, we welcome submissions of PDF files that exhibit these features to help us with future code improvements.
MalformedPDFError has some subclasses if you want to detect finer grained issues. If you don't, 'rescue MalformedPDFError' will catch all the subclassed errors as well.
Any other exceptions should be considered bugs in either PDF::Reader (please report it!).
James Healy <email@example.com>
This library is distributed under the terms of the MIT License. See the included file for more detail.
Any questions or feedback should be sent to the PDF::Reader google group. It's better that any answers be available for others instead of hiding in someone's inbox.
The easiest way to explain how this works in practice is to show some examples. Check out the examples/ directory for a few files.
Occasionally some text cannot be extracted properly due to the way it has been stored, or the use of invalid bytes. In these cases PDF::Reader will output a little UTF-8 friendly box to indicate an unrecognisable character.
PDF::Reader Code Repository: github.com/yob/pdf-reader
PDF Specification: www.adobe.com/devnet/pdf/pdf_reference.html
PDF Tutorial Slide Presentations: home.comcast.net/~jk05/presentations/PDFTutorials.html