Add QPDFPageDocumentHelper and QPDFPageObjectHelper

This is the beginning of higher-level API support using helper
classes. The goal is to be able to add more helpers without continuing
to pollute QPDF's and QPDFObjectHandle's public interfaces.

1 files changed, 37 insertions, 81 deletions

diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh
index 4f5cde37..967e786c 100644
--- a/include/qpdf/QPDFObjectHandle.hh
+++ b/include/qpdf/QPDFObjectHandle.hh
@@ -278,37 +278,21 @@ class QPDFObjectHandle
                                   StringDecrypter* decrypter,
                                   QPDF* context);
 
-    // Helpers for parsing content streams
-
-    // Parse a page's contents through ParserCallbacks, described
-    // above. This method works whether the contents are a single
-    // stream or an array of streams. Call on a page object.
-    QPDF_DLL
-    void parsePageContents(ParserCallbacks* callbacks);
-
-    // Pass a page's contents through the given TokenFilter. If a
-    // pipeline is also provided, it will be the target of the write
-    // methods from the token filter. If a pipeline is not specified,
-    // any output generated by the token filter will be discarded. Use
-    // this interface if you need to pass a page's contents through
-    // filter for work purposes without having that filter
-    // automatically applied to the page's contents, as happens with
-    // addContentTokenFilter. See examples/pdf-count-strings.cc for an
-    // example.
-    QPDF_DLL
-    void filterPageContents(TokenFilter* filter, Pipeline* next = 0);
-
-    // Pipe a page's contents through the given pipeline. This method
-    // works whether the contents are a single stream or an array of
-    // streams. Call on a page object.
+    // Older method: stream_or_array should be the value of /Contents
+    // from a page object. It's more convenient to just call
+    // QPDFPageObjectHelper::parsePageContents on the page object, and
+    // error messages will also be more useful because the page object
+    // information will be known.
     QPDF_DLL
-    void pipePageContents(Pipeline* p);
+    static void parseContentStream(QPDFObjectHandle stream_or_array,
+                                   ParserCallbacks* callbacks);
 
     // When called on a stream or stream array that is some page's
     // content streams, do the same as pipePageContents. This method
-    // is a lower level way to do what pipePageContents does, but it
-    // allows you to perform this operation on a contents object that
-    // is disconnected from a page object. The description argument
+    // is a lower level way to do what
+    // QPDFPageObjectHelper::pipePageContents does, but it allows you
+    // to perform this operation on a contents object that is
+    // disconnected from a page object. The description argument
     // should describe the containing page and is used in error
     // messages. The all_description argument is initialized to
     // something that could be used to describe the result of the
@@ -318,32 +302,33 @@ class QPDFObjectHandle
     void pipeContentStreams(Pipeline* p, std::string const& description,
                             std::string& all_description);
 
-    // Older method: stream_or_array should be the value of /Contents
-    // from a page object. It's more convenient to just call
-    // parsePageContents on the page object, and error messages will
-    // also be more useful because the page object information will be
-    // known.
-    QPDF_DLL
-    static void parseContentStream(QPDFObjectHandle stream_or_array,
-                                   ParserCallbacks* callbacks);
-
-    // Attach a token filter to a page's contents. If the page's
-    // contents is an array of streams, it is automatically coalesced.
-    // The token filter is applied to the page's contents as a single
-    // stream.
-    QPDF_DLL
-    void addContentTokenFilter(PointerHolder<TokenFilter> token_filter);
-
     // As of qpdf 8, it is possible to add custom token filters to a
     // stream. The tokenized stream data is passed through the token
     // filter after all original filters but before content stream
     // normalization if requested. This is a low-level interface to
     // add it to a stream. You will usually want to call
-    // addContentTokenFilter instead, which can be applied to a page
-    // object, and which will automatically handle the case of pages
-    // whose contents are split across multiple streams.
+    // QPDFPageObjectHelper::addContentTokenFilter instead, which can
+    // be applied to a page object, and which will automatically
+    // handle the case of pages whose contents are split across
+    // multiple streams.
     void addTokenFilter(PointerHolder<TokenFilter> token_filter);
 
+    // Legacy helpers for parsing content streams. These methods are
+    // not going away, but newer code should call the correspond
+    // methods in QPDFPageObjectHelper instead. The specification and
+    // behavior of these methods are the same as the identically named
+    // methods in that class, but newer functionality will be added
+    // there.
+    QPDF_DLL
+    void parsePageContents(ParserCallbacks* callbacks);
+    QPDF_DLL
+    void filterPageContents(TokenFilter* filter, Pipeline* next = 0);
+    QPDF_DLL
+    void pipePageContents(Pipeline* p);
+    QPDF_DLL
+    void addContentTokenFilter(PointerHolder<TokenFilter> token_filter);
+    // End legacy content stream helpers
+
     // Type-specific factories
     QPDF_DLL
     static QPDFObjectHandle newNull();
@@ -731,51 +716,22 @@ class QPDFObjectHandle
     QPDF_DLL
     std::string unparseResolved();
 
-    // Convenience routines for commonly performed functions
-
-    // Returns an empty map if there are no images or no resources.
-    // This function does not presently support inherited resources.
-    // If this is a significant concern, call
-    // pushInheritedAttributesToPage() on the QPDF object that owns
-    // this page. See comment in the source for details. Return value
-    // is a map from XObject name to the image object, which is always
-    // a stream.
+    // Legacy helper methods for commonly performed operations on
+    // pages. Newer code should use QPDFPageObjectHelper instead. The
+    // specification and behavior of these methods are the same as the
+    // identically named methods in that class, but newer
+    // functionality will be added there.
     QPDF_DLL
     std::map<std::string, QPDFObjectHandle> getPageImages();
-
-    // Returns a vector of stream objects representing the content
-    // streams for the given page.  This routine allows the caller to
-    // not care whether there are one or more than one content streams
-    // for a page.
     QPDF_DLL
     std::vector<QPDFObjectHandle> getPageContents();
-
-    // Add the given object as a new content stream for this page. If
-    // parameter 'first' is true, add to the beginning. Otherwise, add
-    // to the end. This routine automatically converts the page
-    // contents to an array if it is a scalar, allowing the caller not
-    // to care what the initial structure is. You can call
-    // coalesceContentStreams() afterwards if you want to force it to
-    // be a single stream.
     QPDF_DLL
     void addPageContents(QPDFObjectHandle contents, bool first);
-
-    // Rotate a page. If relative is false, set the rotation of the
-    // page to angle. Otherwise, add angle to the rotation of the
-    // page. Angle must be a multiple of 90. Adding 90 to the rotation
-    // rotates clockwise by 90 degrees.
     QPDF_DLL
     void rotatePage(int angle, bool relative);
-
-    // Coalesce a page's content streams. A page's content may be a
-    // stream or an array of streams. If this page's content is an
-    // array, concatenate the streams into a single stream. This can
-    // be useful when working with files that split content streams in
-    // arbitrary spots, such as in the middle of a token, as that can
-    // confuse some software. You could also call this after calling
-    // addPageContents.
     QPDF_DLL
     void coalesceContentStreams();
+    // End legacy page helpers
 
     // Issue a warning about this object if possible. If the object
     // has a description, a warning will be issued. Otherwise, if