Change filename or path to file in json and QPDFJob

Use "file" consistently for specifying a file path. We use "filename"
when adding attachments for a completely different purpose.

11 files changed, 72 insertions, 68 deletions

diff --git a/generate_auto_job b/generate_auto_job
index 6b59debc..63eb4350 100755
--- a/generate_auto_job
+++ b/generate_auto_job
@@ -495,7 +495,11 @@ class Main:
     def build_schema(self, j, path, flag, expected, options_seen):
         if flag in expected:
             options_seen.add(flag)
-        elif not (flag == '' or flag.startswith('_') or isinstance(j, str)):
+        elif isinstance(j, str):
+            if not flag.startswith('_'):
+                raise Exception(f'json: {flag} has a description'
+                                ' but doesn\'t start with _')
+        elif not (flag == '' or flag.startswith('_')):
             raise Exception(f'json: unknown key {flag}')
 
         if isinstance(j, dict):
diff --git a/include/qpdf/QPDFJob.hh b/include/qpdf/QPDFJob.hh
index bc8c3b9e..bedf808e 100644
--- a/include/qpdf/QPDFJob.hh
+++ b/include/qpdf/QPDFJob.hh
@@ -190,7 +190,7 @@ class QPDFJob
         QPDF_DLL
         Config* endAddAttachment();
         QPDF_DLL
-        AttConfig* path(char const* parameter);
+        AttConfig* file(char const* parameter);
 
 #       include <qpdf/auto_job_c_att.hh>
 
@@ -210,7 +210,7 @@ class QPDFJob
         QPDF_DLL
         Config* endCopyAttachmentsFrom();
         QPDF_DLL
-        CopyAttConfig* path(char const* parameter);
+        CopyAttConfig* file(char const* parameter);
 
 #       include <qpdf/auto_job_c_copy_att.hh>
 
@@ -251,7 +251,7 @@ class QPDFJob
         QPDF_DLL
         Config* endUnderlayOverlay();
         QPDF_DLL
-        UOConfig* path(char const* parameter);
+        UOConfig* file(char const* parameter);
 
 #       include <qpdf/auto_job_c_uo.hh>
 
@@ -270,7 +270,7 @@ class QPDFJob
         QPDF_DLL
         Config* endEncrypt();
         QPDF_DLL
-        EncConfig* path(char const* parameter);
+        EncConfig* file(char const* parameter);
 
 #       include <qpdf/auto_job_c_enc.hh>
 
diff --git a/job.sums b/job.sums
index bae3dd3a..205b652e 100644
--- a/job.sums
+++ b/job.sums
@@ -1,17 +1,17 @@
 # Generated by generate_auto_job
-generate_auto_job e28f3fb4938f6307bb4c23c084c239832dbee3bbaedf19a22fb19215312b30b0
+generate_auto_job ef1b438aeebed7ca0afcbe4d1f9c54d3acf899aec8410ebc69cd15ec673dd158
 include/qpdf/auto_job_c_att.hh 7ad43bb374c1370ef32ebdcdcb7b73a61d281f7f4e3f12755585872ab30fb60e
 include/qpdf/auto_job_c_copy_att.hh 32275d03cdc69b703dd7e02ba0bbe15756e714e9ad185484773a6178dc09e1ee
 include/qpdf/auto_job_c_enc.hh 72e138c7b96ed5aacdce78c1dec04b1c20d361faec4f8faf52f64c1d6be99265
 include/qpdf/auto_job_c_main.hh 516adb23cc7e44e614e436880be870d0574e4ebbc706cd855a1360000eed31bb
 include/qpdf/auto_job_c_pages.hh 931840b329a36ca0e41401190e04537b47f2867671a6643bfd8da74014202671
 include/qpdf/auto_job_c_uo.hh 0585b7de459fa479d9e51a45fa92de0ff6dee748efc9ec1cedd0dde6cee1ad50
-job.yml 2ccc58ef74b875524505d7f00561b2df27ec2000846a549ac21a1fdd2f74c096
+job.yml fe299f5fe022bd79884b3c66a8134386d8bf5ad42c32bdef37fc7044e5f003b9
 libqpdf/qpdf/auto_job_decl.hh 9f79396ec459f191be4c5fe34cf88c265cf47355a1a945fa39169d1c94cf04f6
 libqpdf/qpdf/auto_job_help.hh 23c79f1d2c02bda28f64aace17f69487205c797e7ae2234892cbbabab49d6d47
 libqpdf/qpdf/auto_job_init.hh 8e9e31b6099a662497339b27f6e2d7f779f35011e88a834bee8811c33405a0fe
-libqpdf/qpdf/auto_job_json_decl.hh 4846055075dcb7365c56c02150e955979b522d14f4329ce7a8a302ccd1d7aa2a
-libqpdf/qpdf/auto_job_json_init.hh 8ccfcfe06339c69631da2167cd1a77844a3cc9031e4090998113ef70b96bcb70
-libqpdf/qpdf/auto_job_schema.hh 27cadf4f0c99dd27c569ec6d870a51d2abb51c8daaad94a55c42b6e86cf7726a
+libqpdf/qpdf/auto_job_json_decl.hh 741a44106f7850b6cbc8af264b5b77bb605475c8d8dd8cd87011d5debbee6269
+libqpdf/qpdf/auto_job_json_init.hh 886dd8ed7ae7691eaa97a0e5b3f1445f4cccab88ed372f530a8524d198c8f1d9
+libqpdf/qpdf/auto_job_schema.hh a764050cc99f1cc95645fd1ea2f020c4b778957abc64fbc55c12eac3a369dc92
 manual/_ext/qpdf.py e9ac9d6c70642a3d29281ee5ad92ae2422dee8be9306fb8a0bc9dba0ed5e28f3
 manual/cli.rst 79140e023faa0cb77afe0b1dc512dd120ee5617f4db82f842596e4f239f93882
diff --git a/job.yml b/job.yml
index 92702c70..9cd0673a 100644
--- a/job.yml
+++ b/job.yml
@@ -249,23 +249,23 @@ no-json:
   - is-encrypted
 json:
   # The structure of this section defines what the json input to
-  # QPDFJob looks like. If a key starts with underscore or has a value
-  # that is a string, it does not map to a command-line argument. If
-  # value is null, its properties and help come from other information
-  # known by generate_auto_job. Otherwise, it has to match a
-  # command-line option. This information is used to construct a
-  # "schema" (as in JSON.hh) for the json input to QPDFJob. The
-  # leading underscore is removed. *NOTE*: all keys are converted to
-  # camelCase for the schema and must be appear that way in the
-  # user-supplied json. This makes it more convenient to populate JSON
-  # objects in some languages.
+  # QPDFJob looks like. If a key starts with underscore, it does not
+  # map to a command-line argument. If the value is a string, that is
+  # the help information. Otherwise, if the value is null, it has to
+  # match a command-line option, and its properties and help come from
+  # other information known by generate_auto_job. This information is
+  # used to construct a "schema" (as in JSON.hh) for the json input to
+  # QPDFJob. The leading underscore is removed. *NOTE*: all keys are
+  # converted to camelCase for the schema and must be appear that way
+  # in the user-supplied json. This makes it more convenient to
+  # populate JSON objects in some languages.
   _input:
-    _filename: "input filename"
+    _file: "input filename"
     main.password:
     password-file:
     empty:
   _output:
-    _filename: "output filename"
+    _file: "output filename"
     _replace-input: "set to true to replace input"
     _options:
       qdf:
@@ -291,8 +291,8 @@ json:
       progress:
       split-pages:
       encrypt:
-        user-password: "user password"
-        owner-password: "owner password"
+        _user-password: "user password"
+        _owner-password: "owner password"
         _40bit:
           Enc40.annotate:
           Enc40.extract:
@@ -359,7 +359,7 @@ json:
     ii-min-bytes:
     remove-unreferenced-resources:
     add-attachment:
-      - path: "attachment to add"
+      - _file: "attachment to add"
         creationdate:
         description:
         filename:
@@ -369,7 +369,7 @@ json:
         replace:
     remove-attachment:
     copy-attachments-from:
-      - path: "attachment source filename"
+      - _file: "attachment source filename"
         CopyAtt.password:
         prefix:
     collate:
@@ -382,19 +382,19 @@ json:
     oi-min-width:
     optimize-images:
     pages:
-      - file: "source for for pages"
+      - _file: "source for for pages"
         Pages.password:
-        range: "page range"
+        _range: "page range"
     remove-page-labels:
     rotate:
     overlay:
-      file: "source file for overlay"
+      _file: "source file for overlay"
       UO.password:
       from:
       repeat:
       to:
     underlay:
-      file: "source file for underlay"
+      _file: "source file for underlay"
       UO.password:
       from:
       repeat:
diff --git a/libqpdf/QPDFJob_argv.cc b/libqpdf/QPDFJob_argv.cc
index b0715819..66ae02a5 100644
--- a/libqpdf/QPDFJob_argv.cc
+++ b/libqpdf/QPDFJob_argv.cc
@@ -426,7 +426,7 @@ ArgParser::argEnd256BitEncryption()
 void
 ArgParser::argUOPositional(char* arg)
 {
-    c_uo->path(arg);
+    c_uo->file(arg);
 }
 
 void
@@ -439,7 +439,7 @@ ArgParser::argEndUnderlayOverlay()
 void
 ArgParser::argAttPositional(char* arg)
 {
-    c_att->path(arg);
+    c_att->file(arg);
 }
 
 void
@@ -452,7 +452,7 @@ ArgParser::argEndAttachment()
 void
 ArgParser::argCopyAttPositional(char* arg)
 {
-    c_copy_att->path(arg);
+    c_copy_att->file(arg);
 }
 
 void
diff --git a/libqpdf/QPDFJob_config.cc b/libqpdf/QPDFJob_config.cc
index 02f1b69e..33c2e94a 100644
--- a/libqpdf/QPDFJob_config.cc
+++ b/libqpdf/QPDFJob_config.cc
@@ -761,7 +761,7 @@ QPDFJob::CopyAttConfig::CopyAttConfig(Config* c) :
 }
 
 QPDFJob::CopyAttConfig*
-QPDFJob::CopyAttConfig::path(char const* parameter)
+QPDFJob::CopyAttConfig::file(char const* parameter)
 {
     this->caf.path = parameter;
     return this;
@@ -786,7 +786,7 @@ QPDFJob::CopyAttConfig::endCopyAttachmentsFrom()
 {
     if (this->caf.path.empty())
     {
-        usage("copy attachments: no path specified");
+        usage("copy attachments: no file specified");
     }
     this->config->o.m->attachments_to_copy.push_back(this->caf);
     return this->config;
@@ -804,7 +804,7 @@ QPDFJob::Config::addAttachment()
 }
 
 QPDFJob::AttConfig*
-QPDFJob::AttConfig::path(char const* parameter)
+QPDFJob::AttConfig::file(char const* parameter)
 {
     this->att.path = parameter;
     return this;
@@ -878,12 +878,12 @@ QPDFJob::AttConfig::endAddAttachment()
         QUtil::get_current_qpdf_time());
     if (this->att.path.empty())
     {
-        usage("add attachment: no path specified");
+        usage("add attachment: no file specified");
     }
     std::string last_element = QUtil::path_basename(this->att.path);
     if (last_element.empty())
     {
-        usage("path for --add-attachment may not be empty");
+        usage("file for --add-attachment may not be empty");
     }
     if (this->att.filename.empty())
     {
@@ -972,7 +972,7 @@ QPDFJob::UOConfig::endUnderlayOverlay()
 }
 
 QPDFJob::UOConfig*
-QPDFJob::UOConfig::path(char const* parameter)
+QPDFJob::UOConfig::file(char const* parameter)
 {
     if (! config->o.m->under_overlay->filename.empty())
     {
diff --git a/libqpdf/QPDFJob_json.cc b/libqpdf/QPDFJob_json.cc
index 967f0cc9..da1e19e2 100644
--- a/libqpdf/QPDFJob_json.cc
+++ b/libqpdf/QPDFJob_json.cc
@@ -228,7 +228,7 @@ Handlers::endInput()
 }
 
 void
-Handlers::setupInputFilename()
+Handlers::setupInputFile()
 {
     addParameter([this](char const* p) {
         c_main->inputFile(p);
@@ -264,7 +264,7 @@ Handlers::endOutput()
 }
 
 void
-Handlers::setupOutputFilename()
+Handlers::setupOutputFile()
 {
     addParameter([this](char const* p) {
         c_main->outputFile(p);
@@ -465,10 +465,10 @@ Handlers::endOptionsAddAttachment()
 }
 
 void
-Handlers::setupOptionsAddAttachmentPath()
+Handlers::setupOptionsAddAttachmentFile()
 {
     addParameter([this](char const* p) {
-        c_att->path(p);
+        c_att->file(p);
     });
 }
 
@@ -498,10 +498,10 @@ Handlers::endOptionsCopyAttachmentsFrom()
 }
 
 void
-Handlers::setupOptionsCopyAttachmentsFromPath()
+Handlers::setupOptionsCopyAttachmentsFromFile()
 {
     addParameter([this](char const* p) {
-        c_copy_att->path(p);
+        c_copy_att->file(p);
     });
 }
 
@@ -600,7 +600,7 @@ void
 Handlers::setupOptionsOverlayFile()
 {
     addParameter([this](char const* p) {
-        c_uo->path(p);
+        c_uo->file(p);
     });
 }
 
@@ -629,7 +629,7 @@ void
 Handlers::setupOptionsUnderlayFile()
 {
     addParameter([this](char const* p) {
-        c_uo->path(p);
+        c_uo->file(p);
     });
 }
 
diff --git a/libqpdf/qpdf/auto_job_json_decl.hh b/libqpdf/qpdf/auto_job_json_decl.hh
index 8dc37adf..ba9b7029 100644
--- a/libqpdf/qpdf/auto_job_json_decl.hh
+++ b/libqpdf/qpdf/auto_job_json_decl.hh
@@ -5,12 +5,12 @@
 //
 void beginInput(JSON);
 void endInput();
-void setupInputFilename();
+void setupInputFile();
 void setupInputPassword();
 void setupInputEmpty();
 void beginOutput(JSON);
 void endOutput();
-void setupOutputFilename();
+void setupOutputFile();
 void setupOutputReplaceInput();
 void beginOutputOptions(JSON);
 void endOutputOptions();
@@ -36,12 +36,12 @@ void beginOptionsAddAttachmentArray(JSON);
 void endOptionsAddAttachmentArray();
 void beginOptionsAddAttachment(JSON);
 void endOptionsAddAttachment();
-void setupOptionsAddAttachmentPath();
+void setupOptionsAddAttachmentFile();
 void beginOptionsCopyAttachmentsFromArray(JSON);
 void endOptionsCopyAttachmentsFromArray();
 void beginOptionsCopyAttachmentsFrom(JSON);
 void endOptionsCopyAttachmentsFrom();
-void setupOptionsCopyAttachmentsFromPath();
+void setupOptionsCopyAttachmentsFromFile();
 void setupOptionsCopyAttachmentsFromPassword();
 void beginOptionsPagesArray(JSON);
 void endOptionsPagesArray();
diff --git a/libqpdf/qpdf/auto_job_json_init.hh b/libqpdf/qpdf/auto_job_json_init.hh
index 68808130..39eb6437 100644
--- a/libqpdf/qpdf/auto_job_json_init.hh
+++ b/libqpdf/qpdf/auto_job_json_init.hh
@@ -16,9 +16,9 @@ static char const* modify128_choices[] = {"all", "annotate", "form", "assembly",
 
 pushKey("input");
 beginDict(bindJSON(&Handlers::beginInput), bindBare(&Handlers::endInput)); // .input
-pushKey("filename");
-setupInputFilename();
-popHandler(); // key: filename
+pushKey("file");
+setupInputFile();
+popHandler(); // key: file
 pushKey("password");
 setupInputPassword();
 popHandler(); // key: password
@@ -31,9 +31,9 @@ popHandler(); // key: empty
 popHandler(); // key: input
 pushKey("output");
 beginDict(bindJSON(&Handlers::beginOutput), bindBare(&Handlers::endOutput)); // .output
-pushKey("filename");
-setupOutputFilename();
-popHandler(); // key: filename
+pushKey("file");
+setupOutputFile();
+popHandler(); // key: file
 pushKey("replaceInput");
 setupOutputReplaceInput();
 popHandler(); // key: replaceInput
@@ -311,9 +311,9 @@ popHandler(); // key: removeUnreferencedResources
 pushKey("addAttachment");
 beginArray(bindJSON(&Handlers::beginOptionsAddAttachmentArray), bindBare(&Handlers::endOptionsAddAttachmentArray)); // .options.addAttachment[]
 beginDict(bindJSON(&Handlers::beginOptionsAddAttachment), bindBare(&Handlers::endOptionsAddAttachment)); // .options.addAttachment
-pushKey("path");
-setupOptionsAddAttachmentPath();
-popHandler(); // key: path
+pushKey("file");
+setupOptionsAddAttachmentFile();
+popHandler(); // key: file
 pushKey("creationdate");
 addParameter([this](char const* p) { c_att->creationdate(p); });
 popHandler(); // key: creationdate
@@ -343,9 +343,9 @@ popHandler(); // key: removeAttachment
 pushKey("copyAttachmentsFrom");
 beginArray(bindJSON(&Handlers::beginOptionsCopyAttachmentsFromArray), bindBare(&Handlers::endOptionsCopyAttachmentsFromArray)); // .options.copyAttachmentsFrom[]
 beginDict(bindJSON(&Handlers::beginOptionsCopyAttachmentsFrom), bindBare(&Handlers::endOptionsCopyAttachmentsFrom)); // .options.copyAttachmentsFrom
-pushKey("path");
-setupOptionsCopyAttachmentsFromPath();
-popHandler(); // key: path
+pushKey("file");
+setupOptionsCopyAttachmentsFromFile();
+popHandler(); // key: file
 pushKey("password");
 setupOptionsCopyAttachmentsFromPassword();
 popHandler(); // key: password
diff --git a/libqpdf/qpdf/auto_job_schema.hh b/libqpdf/qpdf/auto_job_schema.hh
index 9b85536a..df430a27 100644
--- a/libqpdf/qpdf/auto_job_schema.hh
+++ b/libqpdf/qpdf/auto_job_schema.hh
@@ -1,12 +1,12 @@
 static constexpr char const* JOB_SCHEMA_DATA = R"({
   "input": {
-    "filename": "input filename",
+    "file": "input filename",
     "password": "specify password",
     "passwordFile": "read password from a file",
     "empty": "empty input file"
   },
   "output": {
-    "filename": "output filename",
+    "file": "output filename",
     "replaceInput": "set to true to replace input",
     "options": {
       "qdf": "enable viewing PDF code in a text editor",
@@ -110,7 +110,7 @@ static constexpr char const* JOB_SCHEMA_DATA = R"({
     "removeUnreferencedResources": "remove unreferenced page resources",
     "addAttachment": [
       {
-        "path": "attachment to add",
+        "file": "attachment to add",
         "creationdate": "set attachment's creation date",
         "description": "set attachment's description",
         "filename": "set attachment's displayed filename",
@@ -123,7 +123,7 @@ static constexpr char const* JOB_SCHEMA_DATA = R"({
     "removeAttachment": "remove an embedded file",
     "copyAttachmentsFrom": [
       {
-        "path": "attachment source filename",
+        "file": "attachment source filename",
         "password": "specify password",
         "prefix": "key prefix for copying attachments"
       }
diff --git a/qpdf/qtest/qpdf.test b/qpdf/qtest/qpdf.test
index f8fb7950..447aa258 100644
--- a/qpdf/qtest/qpdf.test
+++ b/qpdf/qtest/qpdf.test
@@ -668,7 +668,7 @@ $td->runtest("add attachment: bad mod date",
 $td->runtest("add attachment: trailing slash",
 	     {$td->COMMAND => "qpdf minimal.pdf a.pdf" .
                   " --add-attachment --"},
-	     {$td->REGEXP => ".*add attachment: no path specified.*",
+	     {$td->REGEXP => ".*add attachment: no file specified.*",
                   $td->EXIT_STATUS => 2},
 	     $td->NORMALIZE_NEWLINES);