From cc5485dac1f224f856ce48781278b357f61f74bd Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Tue, 1 Feb 2022 07:18:23 -0500 Subject: QPDFJob: documentation --- libqpdf/QPDFJob.cc | 4 ++-- libqpdf/QPDFJob_config.cc | 1 - libqpdf/QPDFJob_json.cc | 22 ++++++++++++++++++++++ libqpdf/qpdf/auto_job_help.hh | 3 ++- 4 files changed, 26 insertions(+), 4 deletions(-) (limited to 'libqpdf') diff --git a/libqpdf/QPDFJob.cc b/libqpdf/QPDFJob.cc index 1c6a16d6..a06f87bc 100644 --- a/libqpdf/QPDFJob.cc +++ b/libqpdf/QPDFJob.cc @@ -646,7 +646,6 @@ QPDFJob::createsOutput() const void QPDFJob::checkConfiguration() { - // QXXXQ messages are CLI-centric if (m->replace_input) { if (m->outfilename) @@ -722,7 +721,8 @@ QPDFJob::checkConfiguration() { QTC::TC("qpdf", "qpdf same file error"); usage("input file and output file are the same;" - " use --replace-input to intentionally overwrite the input file"); + " use --replace-input to intentionally" + " overwrite the input file"); } } diff --git a/libqpdf/QPDFJob_config.cc b/libqpdf/QPDFJob_config.cc index fb61924c..68eaf5c8 100644 --- a/libqpdf/QPDFJob_config.cc +++ b/libqpdf/QPDFJob_config.cc @@ -28,7 +28,6 @@ QPDFJob::Config::emptyInput() { if (o.m->infilename == 0) { - // QXXXQ decide whether to fix this or just leave the comment: // Various places in QPDFJob.cc know that the empty string for // infile means empty. This means that passing "" as the // argument to inputFile, or equivalently using "" as a diff --git a/libqpdf/QPDFJob_json.cc b/libqpdf/QPDFJob_json.cc index cc4e2ff7..c0de8666 100644 --- a/libqpdf/QPDFJob_json.cc +++ b/libqpdf/QPDFJob_json.cc @@ -29,6 +29,28 @@ namespace typedef std::function param_handler_t; typedef std::function json_handler_t; + // The code that calls these methods is automatically + // generated by generate_auto_job. This describes how we + // implement what it does. We keep a stack of handlers in + // json_handlers. The top of the stack is the "current" json + // handler, intially for the top-level object. Whenever we + // encounter a scalar, we add a handler using addBare, + // addParameter, or addChoices. Whenever we encounter a + // dictionary, we first add the dictionary handlers. Then we + // walk into the dictionary and, for each key, we register a + // dict key handler and push it to the stack, then do the same + // process for the key's value. Then we pop the key handler + // off the stack. When we encounter an array, we add the array + // handlers, push an item handler to the stack, call + // recursively for the array's single item (as this is what is + // expected in a schema), and pop the item handler. Note that + // we don't pop dictionary start/end handlers. The dictionary + // handlers and the key handlers are at the same level in + // JSONHandler. This logic is subtle and took several tries to + // get right. It's best understood by carefully understanding + // the behavior of JSONHandler, the JSON schema, and the code + // in generate_auto_job. + void addBare(bare_handler_t); void addParameter(param_handler_t); void addChoices(char const** choices, bool required, param_handler_t); diff --git a/libqpdf/qpdf/auto_job_help.hh b/libqpdf/qpdf/auto_job_help.hh index 49ac3494..38d275b5 100644 --- a/libqpdf/qpdf/auto_job_help.hh +++ b/libqpdf/qpdf/auto_job_help.hh @@ -812,7 +812,8 @@ This option is repeatable. If given, only specified objects will be shown in the "objects" key of the JSON output. Otherwise, all objects will be shown. )"); -ap.addOptionHelp("--job-json-help", "json", "show format of job JSON", R"(Describe the format of the QPDFJob JSON input. +ap.addOptionHelp("--job-json-help", "json", "show format of job JSON", R"(Describe the format of the QPDFJob JSON input used by +--job-json-file. )"); ap.addHelpTopic("testing", "options for testing or debugging", R"(The options below are useful when writing automated test code that includes files created by qpdf or when testing qpdf itself. -- cgit v1.2.3-54-g00ecf