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 [-qsv] [-x txtfile] input.pdf
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 options are as follows:
-q Query/quiet mode. Do not print to stdout and suppress any messages
about parse errors. Just indicate success/failure via the exit status.
-s Strict mode. Treat most format violations as parse errors.
-v Verbose mode. Show additional informational messages.
-x txtfile
Extract the text content of the input document and write it as plain
text to 'txtfile'.
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>
EXIT STATUS
On valid input, the program returns with exit code 0. An exit code of 1
indicates that the parser identified the input as invalid and otherwise
executed normally. Exit codes >1 indicate abnormal termination, i.e.
program failure with indeterminate result.
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.
