README

Beginnings of a PDF parser in Hammer
====================================


BUILDING

   Simply call 'make' in the top level directory.

       $ make

   The environment variables CC, CFLAGS, and LDFLAGS can be used in the usual
   way to control the compiler to use, compiler flags, and linker flags,
   respectively.

   This program uses the Hammer parser combinator library. It needs a recent
   version, which can be obtained from:

       https://gitlab.special-circumstanc.es/hammer/hammer/

   See the file README.md in that repository for build/install instructions.
   It is recommended to install Hammer as a system library. See also the
   TROUBLESHOOTING section below.


USAGE

       ./pdf [options] input.pdf [oid]

   The 'pdf' utility attempts to parse and validate the given PDF file. If
   successful, it prints the resulting AST to stdout using a JSON format.
   It exits 0 on success, 1 if the input file was found to be invalid, and >1
   if an error occurs. The optional oid argument selects a specific object to
   print instead of the whole document.

   Refer to the supplied manual page 'pdf.1' for details.


TROUBLESHOOTING

   <hammer/hammer.h> or libhammer.so not found:

     If Hammer is not installed as a system library or in a nonstandard
     location, cc and ld will fail to locate its headers and library. The
     quick fix for this is to create symlinks called 'hammer' and 'lib'
     pointing to Hammer's source and build output directories, respectively:

         $ ln -s ../hammer/src hammer
         $ ln -s ../hammer/build/opt/src lib
         $ make

     Likewise, when running 'pdf' directly, ld.so will fail to locate
     libhammer.so. The quick fix is to point LD_LIBRARY_PATH to the 'lib' dir:

         $ export LD_LIBRARY_PATH=$PWD/lib
         $ ./pdf <filename>


EVALUATING TEST RESULTS

   A suite of example files is provided in the test/ directory. To run the
   test suite:

       $ make test
 
   For every file in the test/valid/ and test/invalid/ subdirectories, the pdf
   parser is invoked.

   For the valid samples, a message of the following form is displayed on a
   successful parse (exit code 0):

       OK: test/valid/<filename>

   Non-fatal messages may be displayed above it, but presence of the "OK"
   indicates that the test passed. On any nonzero exit, i.e. if either the
   file is deemed invalid or the program encountered an unexpected error,
   error messages are displayed above an indication of the following form
   that includes the exact exit code:

       FAIL (exit <n>): test/valid/<filename>

   For the invalid samples, messages about parse errors are suppressed and an
   "OK" is displayed if and only if pdf exits with 1 ("invalid input"). An
   exit code of 0 or abnormal termination will produce the "FAIL" message with
   any program output appearing above it.


COPYRIGHT

   Various authors. Released under the terms of the ISC license.

   See LICENSE for full copyright and licensing notice.