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

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

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>
 

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);

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
+include/qpdf/auto_job_c_uo.hh 9c2f98a355858dd54d0bba444b73177a59c9e56833e02fa6406f429c07f39e62
-job.yml 45761edeca048c7aa3e99340fcda1b6cd8efe4cc4c8b8a6628580243a4f49b57
+job.yml 790dd0f62f124a6cc97cc54bae992a1f1b1f3a9b4f0294bcf123868f3d3b39d3
 libqpdf/qpdf/auto_job_decl.hh 20d6affe1e260f5a1af4f1d82a820b933835440ff03020e877382da2e8dac6c6
-libqpdf/qpdf/auto_job_help.hh b19f8a7433c70df70b42f893a8964c801aa2bb78eecaa13cffab7add2ff81e0a
+libqpdf/qpdf/auto_job_help.hh 5808d936f6cd41af278ca298ed0c0762ce0a16956cbe1757a40e4443485cf31e
-libqpdf/qpdf/auto_job_init.hh d74759d4999201a89dafddf6f0c855e9151bbf77ea91a92d6806510292950123
+libqpdf/qpdf/auto_job_init.hh 19d1da7c4c0c635bd1c5db8d5f17df8edad3442f8eba006adb075cec295fa158
-libqpdf/qpdf/auto_job_json_decl.hh 485540cde820987cfbed0aa7642a6416f2bd37164c8d4f2322f1381e73edf903
+libqpdf/qpdf/auto_job_json_decl.hh 7c7fbf9f7fdf7a1f5f7cedb09af16b8dcf30b6860947bd38c970385b05d22fc1
-libqpdf/qpdf/auto_job_json_init.hh c8de8658daa82115b49bf084cebe1be0b8aea73f864a219d7349acc0982b56fe
+libqpdf/qpdf/auto_job_json_init.hh 436567565691252d62a1852564729925ef996e78eba9ea3d947829c05f72a309
-libqpdf/qpdf/auto_job_schema.hh 3e000b87255bee62ba29b794d67b2ae97cbbdfdb78be3878c51786913564901e
+libqpdf/qpdf/auto_job_schema.hh 30dcb22bfa76d731dfa2cc2a226d7deaa25145f964b19ab44161356c909e4dc1
 manual/_ext/qpdf.py 6add6321666031d55ed4aedf7c00e5662bba856dfcd66ccb526563bffefbb580
-manual/cli.rst 408e17dc13d37befe34badc400dd34d3c283952d17ee3bf9a9d44898af3dabc7
+manual/cli.rst 0e6a957defa4839abb9a69414de6a5ec5524fd6ff56fe9abf8f241bee54813e2
-manual/qpdf.1 c99d66833aee7a2294176875ca2e9ddf2531d4ab8fb282ea5c45cb82a5d028ea
+manual/qpdf.1 9833f7d93f66889413545ebac9b762cfd522bd632e5df3ad0b415daa55eac3a0
 manual/qpdf.1.in 436ecc85d45c4c9e2dbd1725fb7f0177fb627179469f114561adf3cb6cbb677b

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:

libqpdf/QPDFJob_json.cc

@@ -486,6 +486,12 @@ Handlers::endPages()
     // nothing needed
 }
 
+void
+Handlers::setupPagesFile()
+{
+    addParameter([this](char const* p) { c_pages->file(p); });
+}
+
 void
 Handlers::setupPagesPassword()
 {

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]]

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");

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();

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();

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",

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
+obscuring the page. The ability to specify the file using the
-only specify each option at most one time.
+: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

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]]

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:
 

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