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.
