QPDFJob: a Job-Based Interface
All of the functionality from the qpdf command-line
executable is available from inside the C++ library using the
QPDFJob
class. There are several ways to access this functionality:
Command-line options
Run the qpdf command line
Use from the C++ API with
QPDFJob::initializeFromArgv
Use from the C API with
qpdfjob_run_from_argv
fromqpdfjob-c.h
. If you are calling from a Windows-style main and have an argv array ofwchar_t
, you can useqpdfjob_run_from_wide_argv
.
The job JSON file format
Use from the CLI with the
--job-json-file
parameterUse from the C++ API with
QPDFJob::initializeFromJson
Use from the C API with
qpdfjob_run_from_json
fromqpdfjob-c.h
Note: this is unrelated to
--json
but can be combined with it. For more information on qpdf JSON (vs. QPDFJob JSON), see qpdf JSON.
The
QPDFJob
C++ API
If you can understand how to use the qpdf CLI, you can
understand the QPDFJob
class and the JSON file. qpdf guarantees
that all of the above methods are in sync. Here’s how it works:
CLI |
JSON |
C++ |
---|---|---|
|
|
|
|
|
|
positional argument |
|
|
In the JSON file, the JSON structure is an object (dictionary) whose
keys are command-line flags converted to camelCase. Positional
arguments have some corresponding key, which you can find by running
qpdf
with the --job-json-help
flag. For example, input
and output files are named by positional arguments on the CLI. In the
JSON, they appear in the "inputFile"
and "outputFile"
keys.
The following are equivalent:
- CLI:
qpdf infile.pdf outfile.pdf \ --pages . other.pdf --password=x 1-5 -- \ --encrypt user owner 256 --print=low -- \ --object-streams=generate
- Job JSON:
{ "inputFile": "infile.pdf", "outputFile": "outfile.pdf", "pages": [ { "file": "." }, { "file": "other.pdf", "password": "x", "range": "1-5" } ], "encrypt": { "userPassword": "user", "ownerPassword": "owner", "256bit": { "print": "low" } }, "objectStreams": "generate" }
- C++ code:
#include <qpdf/QPDFJob.hh> #include <qpdf/QPDFUsage.hh> #include <iostream> int main(int argc, char* argv[]) { try { QPDFJob j; j.config() ->inputFile("infile.pdf") ->outputFile("outfile.pdf") ->pages() ->pageSpec(".", "1-z") ->pageSpec("other.pdf", "1-5", "x") ->endPages() ->encrypt(256, "user", "owner") ->print("low") ->endEncrypt() ->objectStreams("generate") ->checkConfiguration(); j.run(); } catch (QPDFUsage& e) { std::cerr << "configuration error: " << e.what() << std::endl; return 2; } catch (std::exception& e) { std::cerr << "other error: " << e.what() << std::endl; return 2; } return 0; }
Note the QPDFUsage
exception above. This is thrown whenever a
configuration error occurs. These exactly correspond to usage messages
issued by the qpdf CLI for things like omitting an output
file, specifying –pages multiple times, or other invalid
combinations of options. QPDFUsage
is thrown by the argv and JSON
interfaces as well as the native QPDFJob
interface.
It is also possible to mix and match command-line options and JSON
from the CLI. For example, you could create a file called
my-options.json
containing the following:
{
"encrypt": {
"userPassword": "",
"ownerPassword": "owner",
"256bit": {
}
},
"objectStreams": "generate"
}
and use it with other options to create 256-bit encrypted (but unrestricted) files with object streams while specifying other parameters on the command line, such as
qpdf infile.pdf outfile.pdf --job-json-file=my-options.json
See also examples/qpdf-job.cc
in the source distribution as
well as comments in QPDFJob.hh
.
QPDFJob Design
This section describes some of the design rationale and history behind
QPDFJob
.
Documentation of QPDFJob
is divided among three places:
“HOW TO ADD A COMMAND-LINE ARGUMENT” in
README-maintainer
provides a quick reminder of how to add a command-line argument.The source file
generate_auto_job
has a detailed explanation about howQPDFJob
andgenerate_auto_job
work together.This chapter of the manual has other details.
Prior to qpdf version 10.6.0, the qpdf CLI executable had a lot of functionality built into it that was not callable from the library as such. This created a number of problems:
Some of the logic in
qpdf.cc
was pretty complex, such as image optimization, generating JSON output, and many of the page manipulations. While those things could all be coded using the C++ API, there would be a lot of duplicated code.Page splitting and merging will get more complicated over time as qpdf supports a wider range of document-level options. It would be nice to be able to expose this to library users instead of baking it all into the CLI.
Users of other languages who just wanted an interface to do things that the CLI could do didn’t have a good way to do it, such as just handing a library call a set of command-line options or an equivalent JSON object that could be passed in as a string.
The qpdf CLI itself was almost 8,000 lines of code. It needed to be refactored, cleaned up, and split.
Exposing a new feature via the command-line required making lots of small edits to lots of small bits of code, and it was easy to forget something. Adding a code generator, while complex in some ways, greatly reduces the chances of error when extending qpdf.
Here are a few notes on some design decisions about QPDFJob and its various interfaces.
Bare command-line options (flags with no parameter) map to config functions that take no options and to JSON keys whose values are required to be the empty string. The rationale is that we can later change these bare options to options that take an optional parameter without breaking backward compatibility in the CLI or the JSON. Options that take optional parameters generate two config functions: one has no arguments, and one that has a
char const*
argument. This means that adding an optional parameter to a previously bare option also doesn’t break binary compatibility.Adding a new argument to
job.yml
automatically triggers almost everything by declaring and referencing things that you have to implement. This way, once you get the code to compile and link, you know you haven’t forgotten anything. There are two tricky cases:If an argument handler has to do something special, like call a nested config method or select an option table, you have to implement it manually. This is discussed in
generate_auto_job
.When you add an option that has optional parameters or choices, both of the handlers described above are declared, but only the one that takes an argument is referenced. You have to remember to implement the one that doesn’t take an argument or else people will get a linker error if they try to call it. The assumption is that things with optional parameters started out as bare, so the argument-less version is already there.
If you have to add a new option that requires its own option table, you will have to do some extra work including adding a new nested Config class, adding a config member variable to
ArgParser
inQPDFJob_argv.cc
andHandlers
inQPDFJob_json.cc
, and make sure that manually implemented handlers are consistent with each other. It is best to add explicit test cases for all the various ways to get to the option.