Allow --file with --overlay and --underlay

15 files changed, 59 insertions, 25 deletions

diff --git a/ChangeLog b/ChangeLog
index 6127cf64..f6fac9a1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2024-01-09  Jay Berkenbilt  <ejb@ql.org>
+
+	* Add new command-line arguments --file and --range which can be
+	used within --pages in place of positional arguments. Allow --file
+	to be used inside of --overlay and --underlay as well. These new
+	options can be freely intermixed with positional arguments. Also
+	add file(), range(), and password() to QPDFJob::PagesConfig as an
+	alternative to pageSpec.
+
 2024-01-08  Jay Berkenbilt  <ejb@ql.org>
 
 	* 11.8.0: release
diff --git a/include/qpdf/QPDFJob.hh b/include/qpdf/QPDFJob.hh
index 443fa75c..d2028b0a 100644
--- a/include/qpdf/QPDFJob.hh
+++ b/include/qpdf/QPDFJob.hh
@@ -266,8 +266,6 @@ class QPDFJob
       public:
         QPDF_DLL
         Config* endUnderlayOverlay();
-        QPDF_DLL
-        UOConfig* file(std::string const& parameter);
 
 #include <qpdf/auto_job_c_uo.hh>
 
diff --git a/include/qpdf/auto_job_c_uo.hh b/include/qpdf/auto_job_c_uo.hh
index e9894730..547ecf3f 100644
--- a/include/qpdf/auto_job_c_uo.hh
+++ b/include/qpdf/auto_job_c_uo.hh
@@ -5,6 +5,7 @@
 //
 // clang-format off
 //
+QPDF_DLL UOConfig* file(std::string const& parameter);
 QPDF_DLL UOConfig* to(std::string const& parameter);
 QPDF_DLL UOConfig* from(std::string const& parameter);
 QPDF_DLL UOConfig* repeat(std::string const& parameter);
diff --git a/job.sums b/job.sums
index 26bbcac8..900bb801 100644
--- a/job.sums
+++ b/job.sums
@@ -6,15 +6,15 @@ include/qpdf/auto_job_c_copy_att.hh 50609012bff14fd82f0649185940d617d05d530cdc52
 include/qpdf/auto_job_c_enc.hh 28446f3c32153a52afa239ea40503e6cc8ac2c026813526a349e0cd4ae17ddd5
 include/qpdf/auto_job_c_main.hh dbfc221d1533120d1aa9c361d8d2483dea5fcb1c0fd95144d98d305e64ed32a6
 include/qpdf/auto_job_c_pages.hh 09ca15649cc94fdaf6d9bdae28a20723f2a66616bf15aa86d83df31051d82506
-include/qpdf/auto_job_c_uo.hh ae21b69a1efa9333050f4833d465f6daff87e5b38e5106e49bbef5d4132e4ed1
-job.yml 45761edeca048c7aa3e99340fcda1b6cd8efe4cc4c8b8a6628580243a4f49b57
+include/qpdf/auto_job_c_uo.hh 9c2f98a355858dd54d0bba444b73177a59c9e56833e02fa6406f429c07f39e62
+job.yml 790dd0f62f124a6cc97cc54bae992a1f1b1f3a9b4f0294bcf123868f3d3b39d3
 libqpdf/qpdf/auto_job_decl.hh 20d6affe1e260f5a1af4f1d82a820b933835440ff03020e877382da2e8dac6c6
-libqpdf/qpdf/auto_job_help.hh b19f8a7433c70df70b42f893a8964c801aa2bb78eecaa13cffab7add2ff81e0a
-libqpdf/qpdf/auto_job_init.hh d74759d4999201a89dafddf6f0c855e9151bbf77ea91a92d6806510292950123
-libqpdf/qpdf/auto_job_json_decl.hh 485540cde820987cfbed0aa7642a6416f2bd37164c8d4f2322f1381e73edf903
-libqpdf/qpdf/auto_job_json_init.hh c8de8658daa82115b49bf084cebe1be0b8aea73f864a219d7349acc0982b56fe
-libqpdf/qpdf/auto_job_schema.hh 3e000b87255bee62ba29b794d67b2ae97cbbdfdb78be3878c51786913564901e
+libqpdf/qpdf/auto_job_help.hh 5808d936f6cd41af278ca298ed0c0762ce0a16956cbe1757a40e4443485cf31e
+libqpdf/qpdf/auto_job_init.hh 19d1da7c4c0c635bd1c5db8d5f17df8edad3442f8eba006adb075cec295fa158
+libqpdf/qpdf/auto_job_json_decl.hh 7c7fbf9f7fdf7a1f5f7cedb09af16b8dcf30b6860947bd38c970385b05d22fc1
+libqpdf/qpdf/auto_job_json_init.hh 436567565691252d62a1852564729925ef996e78eba9ea3d947829c05f72a309
+libqpdf/qpdf/auto_job_schema.hh 30dcb22bfa76d731dfa2cc2a226d7deaa25145f964b19ab44161356c909e4dc1
 manual/_ext/qpdf.py 6add6321666031d55ed4aedf7c00e5662bba856dfcd66ccb526563bffefbb580
-manual/cli.rst 408e17dc13d37befe34badc400dd34d3c283952d17ee3bf9a9d44898af3dabc7
-manual/qpdf.1 c99d66833aee7a2294176875ca2e9ddf2531d4ab8fb282ea5c45cb82a5d028ea
+manual/cli.rst 0e6a957defa4839abb9a69414de6a5ec5524fd6ff56fe9abf8f241bee54813e2
+manual/qpdf.1 9833f7d93f66889413545ebac9b762cfd522bd632e5df3ad0b415daa55eac3a0
 manual/qpdf.1.in 436ecc85d45c4c9e2dbd1725fb7f0177fb627179469f114561adf3cb6cbb677b
diff --git a/job.yml b/job.yml
index d82111ad..079d36d5 100644
--- a/job.yml
+++ b/job.yml
@@ -260,6 +260,7 @@ options:
     prefix: UO
     positional: true
     required_parameter:
+      file: file
       to: page-range
       from: page-range
       repeat: page-range
@@ -436,7 +437,7 @@ json:
   oi-min-width:
   optimize-images:
   pages:
-    - file:
+    - Pages.file:
       Pages.password:
       range:
   remove-page-labels:
@@ -445,13 +446,13 @@ json:
   set-page-labels:
     - null
   overlay:
-    _file: "source file for overlay"
+    UO.file:
     UO.password:
     from:
     repeat:
     to:
   underlay:
-    _file: "source file for underlay"
+    UO.file:
     UO.password:
     from:
     repeat:
diff --git a/libqpdf/QPDFJob_json.cc b/libqpdf/QPDFJob_json.cc
index 5565ea93..797ee81d 100644
--- a/libqpdf/QPDFJob_json.cc
+++ b/libqpdf/QPDFJob_json.cc
@@ -487,6 +487,12 @@ Handlers::endPages()
 }
 
 void
+Handlers::setupPagesFile()
+{
+    addParameter([this](char const* p) { c_pages->file(p); });
+}
+
+void
 Handlers::setupPagesPassword()
 {
     addParameter([this](char const* p) { c_pages->password(p); });
diff --git a/libqpdf/qpdf/auto_job_help.hh b/libqpdf/qpdf/auto_job_help.hh
index a3572aed..903bdd56 100644
--- a/libqpdf/qpdf/auto_job_help.hh
+++ b/libqpdf/qpdf/auto_job_help.hh
@@ -695,7 +695,7 @@ underlaid on the primary output. Overlaid pages are drawn on top of
 the destination page and may obscure the page. Underlaid pages are
 drawn below the destination page. Usage:
 
-{--overlay|--underlay} file
+{--overlay|--underlay} [--file=]file
       [--password=password]
       [--to=page-range]
       [--from=[page-range]]
diff --git a/libqpdf/qpdf/auto_job_init.hh b/libqpdf/qpdf/auto_job_init.hh
index 401406db..ac42ea6a 100644
--- a/libqpdf/qpdf/auto_job_init.hh
+++ b/libqpdf/qpdf/auto_job_init.hh
@@ -166,6 +166,7 @@ this->ap.addChoices("modify-other", [this](std::string const& x){c_enc->modifyOt
 this->ap.addChoices("modify", [this](std::string const& x){c_enc->modify(x);}, true, modify128_choices);
 this->ap.registerOptionTable("underlay/overlay", b(&ArgParser::argEndUnderlayOverlay));
 this->ap.addPositional(p(&ArgParser::argUOPositional));
+this->ap.addRequiredParameter("file", [this](std::string const& x){c_uo->file(x);}, "file");
 this->ap.addRequiredParameter("to", [this](std::string const& x){c_uo->to(x);}, "page-range");
 this->ap.addRequiredParameter("from", [this](std::string const& x){c_uo->from(x);}, "page-range");
 this->ap.addRequiredParameter("repeat", [this](std::string const& x){c_uo->repeat(x);}, "page-range");
diff --git a/libqpdf/qpdf/auto_job_json_decl.hh b/libqpdf/qpdf/auto_job_json_decl.hh
index b2ae4c1e..d7cb9595 100644
--- a/libqpdf/qpdf/auto_job_json_decl.hh
+++ b/libqpdf/qpdf/auto_job_json_decl.hh
@@ -41,6 +41,7 @@ void beginPagesArray(JSON);
 void endPagesArray();
 void beginPages(JSON);
 void endPages();
+void setupPagesFile();
 void setupPagesPassword();
 void beginSetPageLabelsArray(JSON);
 void endSetPageLabelsArray();
diff --git a/libqpdf/qpdf/auto_job_json_init.hh b/libqpdf/qpdf/auto_job_json_init.hh
index fb4d93b9..aaa1fb64 100644
--- a/libqpdf/qpdf/auto_job_json_init.hh
+++ b/libqpdf/qpdf/auto_job_json_init.hh
@@ -402,7 +402,7 @@ pushKey("pages");
 beginArray(bindJSON(&Handlers::beginPagesArray), bindBare(&Handlers::endPagesArray)); // .pages[]
 beginDict(bindJSON(&Handlers::beginPages), bindBare(&Handlers::endPages)); // .pages
 pushKey("file");
-addParameter([this](std::string const& p) { c_pages->file(p); });
+setupPagesFile();
 popHandler(); // key: file
 pushKey("password");
 setupPagesPassword();
diff --git a/libqpdf/qpdf/auto_job_schema.hh b/libqpdf/qpdf/auto_job_schema.hh
index bb4b04ea..507a54a4 100644
--- a/libqpdf/qpdf/auto_job_schema.hh
+++ b/libqpdf/qpdf/auto_job_schema.hh
@@ -152,14 +152,14 @@ static constexpr char const* JOB_SCHEMA_DATA = R"({
     "number pages for the entire document"
   ],
   "overlay": {
-    "file": "source file for overlay",
+    "file": "source for pages",
     "password": "password for encrypted file",
     "from": "source pages for underlay/overlay",
     "repeat": "overlay/underlay pages to repeat",
     "to": "destination pages for underlay/overlay"
   },
   "underlay": {
-    "file": "source file for underlay",
+    "file": "source for pages",
     "password": "password for encrypted file",
     "from": "source pages for underlay/overlay",
     "repeat": "overlay/underlay pages to repeat",
diff --git a/manual/cli.rst b/manual/cli.rst
index 70253a5f..0ccdee8f 100644
--- a/manual/cli.rst
+++ b/manual/cli.rst
@@ -2789,7 +2789,7 @@ Overlay and Underlay
    the destination page and may obscure the page. Underlaid pages are
    drawn below the destination page. Usage:
 
-   {--overlay|--underlay} file
+   {--overlay|--underlay} [--file=]file
          [--password=password]
          [--to=page-range]
          [--from=[page-range]]
@@ -2813,7 +2813,7 @@ as follows:
 
 ::
 
-   {--overlay|--underlay} file [options] --
+   {--overlay|--underlay} [--file=]file [options] --
 
 Overlay and underlay options are processed late, so they can be
 combined with other options like merging and will apply to the final
@@ -2821,8 +2821,10 @@ output. The ``--overlay`` and ``--underlay`` options work the same
 way, except underlay pages are drawn underneath the page to which they
 are applied, possibly obscured by the original page, and overlay files
 are drawn on top of the page to which they are applied, possibly
-obscuring the page. You can combine overlay and underlay, but you can
-only specify each option at most one time.
+obscuring the page. The ability to specify the file using the
+:qpdf:ref:`--file` option was added in qpdf 11.9.0. You can combine
+overlay and underlay, but you can only specify each option at most one
+time.
 
 The default behavior of overlay and underlay is that pages are taken
 from the overlay/underlay file in sequence and applied to
diff --git a/manual/qpdf.1 b/manual/qpdf.1
index 4de6427d..edad42b3 100644
--- a/manual/qpdf.1
+++ b/manual/qpdf.1
@@ -833,7 +833,7 @@ underlaid on the primary output. Overlaid pages are drawn on top of
 the destination page and may obscure the page. Underlaid pages are
 drawn below the destination page. Usage:
 
-{--overlay|--underlay} file
+{--overlay|--underlay} [--file=]file
       [--password=password]
       [--to=page-range]
       [--from=[page-range]]
diff --git a/manual/release-notes.rst b/manual/release-notes.rst
index 53d41942..938d2705 100644
--- a/manual/release-notes.rst
+++ b/manual/release-notes.rst
@@ -38,6 +38,21 @@ Planned changes for future 12.x (subject to change):
 
 .. x.y.z: not yet released
 
+11.9.0: not yet released
+  - CLI Enhancements
+
+    - Add new command-line arguments :qpdf:ref:`--file` and
+      :qpdf:ref:`--range` which can be used within :qpdf:ref:`--pages`
+      in place of positional arguments. Allow :qpdf:ref:`--file` to be
+      used inside of :qpdf:ref:`--overlay` and :qpdf:ref:`--underlay`
+      as well. These new options can be freely intermixed with
+      positional arguments.
+
+  - Library Enhancements
+
+    - Add ``file()``, ``range()``, and ``password()`` to
+      ``QPDFJob::PagesConfig`` as an alternative to ``pageSpec``.
+
 11.8.0: January 8, 2024
   - Bug fixes:
 
diff --git a/qpdf/qtest/form-xobject.test b/qpdf/qtest/form-xobject.test
index 2a9bac83..fc98e264 100644
--- a/qpdf/qtest/form-xobject.test
+++ b/qpdf/qtest/form-xobject.test
@@ -51,9 +51,9 @@ foreach (my $i = 64; $i <= 67; ++$i)
 
 my @uo_cases = (
     '--underlay fxo-green.pdf --repeat=z --to=1-14 --' .
-    ' --overlay fxo-blue.pdf --', # 1
+    ' --overlay --file=fxo-blue.pdf --', # 1
     '--overlay fxo-green.pdf --from= --repeat=r2,r1 --' .
-    ' --underlay fxo-blue.pdf --from=z-1 --', # 2
+    ' --underlay --file=fxo-blue.pdf --from=z-1 --', # 2
     '--overlay fxo-green.pdf --from= --repeat=r2,r1 --' .
     ' --underlay fxo-blue.pdf --from=z-1 -- --coalesce-contents', # 3
     '--overlay fxo-green.pdf --', # 4