qpdf_ruby 0.1.1 → 0.2.0

data/ext/qpdf_ruby/qpdf_ruby.hpp

@@ -3,9 +3,6 @@
 
 #include "ruby.h"
 
-VALUE rb_qpdf_mark_paths_as_artifacts(VALUE self);
-VALUE rb_qpdf_ensure_bboxs(VALUE self);
-VALUE rb_qpdf_get_structure_string(VALUE self);
-VALUE rb_qpdf_doc_set_encryption(int argc, VALUE* argv, VALUE self);
+extern "C" void Init_qpdf_ruby(void);
 
 #endif /* QPDF_RUBY_H */

data/ext/qpdf_ruby/ruby_guard.hpp

@@ -0,0 +1,71 @@
+#pragma once
+
+#include <ruby.h>
+
+#include <cstring>
+#include <exception>
+#include <string>
+#include <type_traits>
+#include <utility>
+
+extern VALUE rb_eQpdfRubyError;  // QpdfRuby::Error, defined in Init_qpdf_ruby
+
+namespace qpdf_ruby {
+
+// Ruby raises by longjmp, which skips the destructors of every C++ object in the frames it leaves.
+// So no Ruby exception may ever travel while a C++ object with a destructor is alive. The methods in
+// qpdf_ruby.cpp keep to four rules:
+//   1. Check and convert arguments as Ruby values first, before any C++ object exists (Check_Type,
+//      #to_s, NUM2INT may all raise).
+//   2. Fetch the document handle (handle_of) only after the last conversion: #to_s or #to_int is
+//      Ruby code, and can call initialize on the same document, which frees the old handle.
+//   3. Build C++ values (std::string, containers) only inside the lambda given to guarded.
+//   4. Turn a C++ result into Ruby values only through guarded_to_ruby.
+// Checked by bin/asan-rspec.sh (use-after-free, ordinary leaks) and by
+// spec/qpdf_ruby/document_error_path_memory_spec.rb (destructors skipped by a raise, which
+// LeakSanitizer cannot see).
+
+// Runs C++ code from a Ruby method. A C++ exception becomes a QpdfRuby::Error only after the catch
+// block - and every C++ object with a destructor - is gone.
+template <typename Fn>
+auto guarded(Fn&& fn) -> decltype(fn()) {
+  char message[1024] = {0};
+  {
+    std::string what;
+    try {
+      return std::forward<Fn>(fn)();
+    } catch (const std::exception& e) {
+      what = e.what();
+    } catch (...) {
+      what = "unknown C++ exception";
+    }
+    std::strncpy(message, what.c_str(), sizeof(message) - 1);
+  }
+  rb_raise(rb_eQpdfRubyError, "%s", message);
+}
+
+// guarded, then `build(result)` to make the Ruby return value. Allocating Ruby objects can raise
+// (NoMemoryError); rb_protect stops that while the C++ result is alive, the result is destroyed, and
+// only then is the exception re-raised.
+template <typename Fn, typename Build>
+VALUE guarded_to_ruby(Fn&& fn, Build&& build) {
+  int state = 0;
+  VALUE out = Qnil;
+  {
+    auto result = guarded(std::forward<Fn>(fn));
+    struct Call {
+      decltype(result)* value;
+      std::remove_reference_t<Build>* to_ruby;
+    } call{&result, &build};
+    out = rb_protect(
+        [](VALUE arg) -> VALUE {
+          auto* c = reinterpret_cast<Call*>(arg);
+          return (*c->to_ruby)(*c->value);
+        },
+        reinterpret_cast<VALUE>(&call), &state);
+  }
+  if (state) rb_jump_tag(state);
+  return out;
+}
+
+}  // namespace qpdf_ruby

data/ext/qpdf_ruby/stroke_bounds.cpp

@@ -0,0 +1,155 @@
+#include "stroke_bounds.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <limits>
+
+namespace qpdf_ruby::paths {
+
+namespace {
+
+constexpr double kEpsilon = 1e-9;
+
+Point operator+(Point a, Point b) { return {a.x + b.x, a.y + b.y}; }
+Point operator-(Point a, Point b) { return {a.x - b.x, a.y - b.y}; }
+Point operator*(Point a, double k) { return {a.x * k, a.y * k}; }
+double length(Point a) { return std::hypot(a.x, a.y); }
+bool same(Point a, Point b) { return length(a - b) < kEpsilon; }
+Point unit(Point a) { return a * (1 / length(a)); }
+Point left_normal(Point t) { return {-t.y, t.x}; }
+
+class Bounds {
+ public:
+  explicit Bounds(Matrix const& m) : m_(m) {}
+
+  void point(Point p) {
+    double x = m_[0] * p.x + m_[2] * p.y + m_[4];
+    double y = m_[1] * p.x + m_[3] * p.y + m_[5];
+    add(x, y, 0, 0);
+  }
+
+  // A disk of radius r in user space becomes an ellipse; its box half-sizes follow from the matrix.
+  void disk(Point c, double r) {
+    double x = m_[0] * c.x + m_[2] * c.y + m_[4];
+    double y = m_[1] * c.x + m_[3] * c.y + m_[5];
+    add(x, y, r * std::hypot(m_[0], m_[2]), r * std::hypot(m_[1], m_[3]));
+  }
+
+  std::optional<Box> box() const {
+    if (llx_ > urx_) return std::nullopt;
+    return Box{llx_, lly_, urx_, ury_};
+  }
+
+ private:
+  void add(double x, double y, double dx, double dy) {
+    llx_ = std::min(llx_, x - dx);
+    lly_ = std::min(lly_, y - dy);
+    urx_ = std::max(urx_, x + dx);
+    ury_ = std::max(ury_, y + dy);
+  }
+
+  Matrix const& m_;
+  double llx_ = std::numeric_limits<double>::infinity();
+  double lly_ = std::numeric_limits<double>::infinity();
+  double urx_ = -std::numeric_limits<double>::infinity();
+  double ury_ = -std::numeric_limits<double>::infinity();
+};
+
+// Direction a segment leaves its start / enters its end; nullopt for a segment of zero length.
+std::optional<Point> start_tangent(Segment const& s) {
+  for (int i = 1; i <= 3; ++i) {
+    if ((s.curve || i == 3) && !same(s.p[i], s.p[0])) return unit(s.p[i] - s.p[0]);
+  }
+  return std::nullopt;
+}
+
+std::optional<Point> end_tangent(Segment const& s) {
+  for (int i = 2; i >= 0; --i) {
+    if ((s.curve || i == 0) && !same(s.p[3], s.p[i])) return unit(s.p[3] - s.p[i]);
+  }
+  return std::nullopt;
+}
+
+void cap(Bounds& out, Point at, Point outward, double r, StrokeStyle const& style) {
+  if (style.cap == 1) {
+    out.disk(at, r);
+  } else if (style.cap == 2) {
+    Point n = left_normal(outward) * r;
+    Point tip = at + outward * r;
+    out.point(tip + n);
+    out.point(tip - n);
+  }
+}
+
+// The join between a segment arriving in direction `a` and the next leaving in direction `b`.
+void join(Bounds& out, Point at, Point a, Point b, double r, StrokeStyle const& style) {
+  if (style.join == 1) {
+    out.disk(at, r);
+    return;
+  }
+  if (style.join != 0) return;  // bevel: the segments' own corners already bound it
+  double cos_turn = std::clamp(a.x * b.x + a.y * b.y, -1.0, 1.0);
+  double half = std::sqrt((1 + cos_turn) / 2);  // cos of half the turn angle
+  if (cos_turn > 1 - kEpsilon || half < kEpsilon || 1 / half > style.miter_limit) return;  // straight, or beveled
+  Point bisector = left_normal(a) + left_normal(b);
+  if (length(bisector) < kEpsilon) return;
+  bisector = unit(bisector);
+  if (a.x * b.y - a.y * b.x > 0) bisector = bisector * -1;  // a left turn has its point on the right
+  out.point(at + bisector * (r / half));
+}
+
+void stroke_subpath(Bounds& out, Subpath const& subpath, double r, StrokeStyle const& style) {
+  std::vector<Segment const*> drawn;
+  for (auto const& s : subpath.segments) {
+    if (start_tangent(s)) drawn.push_back(&s);
+  }
+  if (drawn.empty()) {
+    // A degenerate subpath is painted only with round caps, as a dot (ISO 32000-1, 8.5.3.2).
+    if (style.cap == 1 && (subpath.closed || !subpath.segments.empty())) out.disk(subpath.start, r);
+    return;
+  }
+
+  for (auto const* s : drawn) {
+    if (s->curve) {
+      for (auto const& p : s->p) out.disk(p, r);
+    } else {
+      Point n = left_normal(*start_tangent(*s)) * r;
+      for (Point p : {s->p[0], s->p[3]}) {
+        out.point(p + n);
+        out.point(p - n);
+      }
+    }
+  }
+  for (size_t i = 0; i + 1 < drawn.size(); ++i) {
+    join(out, drawn[i]->p[3], *end_tangent(*drawn[i]), *start_tangent(*drawn[i + 1]), r, style);
+  }
+  if (subpath.closed) {
+    join(out, drawn.back()->p[3], *end_tangent(*drawn.back()), *start_tangent(*drawn.front()), r, style);
+  } else {
+    cap(out, drawn.front()->p[0], *start_tangent(*drawn.front()) * -1, r, style);
+    cap(out, drawn.back()->p[3], *end_tangent(*drawn.back()), r, style);
+  }
+}
+
+}  // namespace
+
+std::optional<Box> fill_bounds(std::vector<Subpath> const& path, Matrix const& ctm) {
+  Bounds out(ctm);
+  for (auto const& subpath : path) {
+    if (subpath.segments.empty()) continue;
+    out.point(subpath.start);
+    for (auto const& s : subpath.segments) {
+      for (auto const& p : s.p) out.point(p);
+    }
+  }
+  return out.box();
+}
+
+std::optional<Box> stroke_bounds(std::vector<Subpath> const& path, Matrix const& ctm, StrokeStyle const& style) {
+  Bounds out(ctm);
+  double r = std::fabs(style.width) / 2;
+  for (auto const& subpath : path) stroke_subpath(out, subpath, r, style);
+  return out.box();
+}
+
+}  // namespace qpdf_ruby::paths

data/ext/qpdf_ruby/stroke_bounds.hpp

@@ -0,0 +1,49 @@
+#pragma once
+
+#include "mcid_bounds.hpp"
+
+#include <array>
+#include <optional>
+#include <vector>
+
+namespace qpdf_ruby::paths {
+
+using Matrix = std::array<double, 6>;  // a b c d e f, PDF's row-vector convention
+
+struct Point {
+  double x = 0;
+  double y = 0;
+};
+
+// A line uses `p[0]` and `p[3]`; a cubic Bezier curve all four.
+struct Segment {
+  bool curve = false;
+  std::array<Point, 4> p;
+};
+
+struct Subpath {
+  Point start;
+  std::vector<Segment> segments;
+  bool closed = false;
+};
+
+// The graphics state parameters that shape a stroke (w, J, j, M).
+struct StrokeStyle {
+  double width = 1;
+  int cap = 0;   // 0 butt, 1 round, 2 projecting square
+  int join = 0;  // 0 miter, 1 round, 2 bevel
+  double miter_limit = 10;
+};
+
+// The area a path covers in default user space when filled: the hull of its points (a curve
+// lies inside the hull of its control points). Empty for a path that has no segment.
+std::optional<Box> fill_bounds(std::vector<Subpath> const& path, Matrix const& ctm);
+
+// The area a stroke of the path paints in default user space: every segment widened by half the
+// line width, plus its caps and joins as the style draws them, all under the CTM (a round cap or
+// join becomes an ellipse). Curves are bounded by a disk of half the line width around each
+// control point - exact for lines, a little generous for curves. Dashes are ignored: they only
+// remove paint. Empty for a path that paints nothing.
+std::optional<Box> stroke_bounds(std::vector<Subpath> const& path, Matrix const& ctm, StrokeStyle const& style);
+
+}  // namespace qpdf_ruby::paths

data/ext/qpdf_ruby/xmp_scan.cpp

@@ -0,0 +1,257 @@
+#include "xmp_scan.hpp"
+
+#include <map>
+#include <vector>
+
+namespace qpdf_ruby::xmp {
+
+namespace {
+
+constexpr char kRdfNs[] = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
+constexpr char kXmlNs[] = "http://www.w3.org/XML/1998/namespace";
+
+bool is_space(char c) { return c == ' ' || c == '\t' || c == '\r' || c == '\n'; }
+
+bool is_name_end(char c) { return is_space(c) || c == '/' || c == '>' || c == '='; }
+
+void append_utf8(std::string& out, unsigned long cp) {
+  if (cp < 0x80) {
+    out += static_cast<char>(cp);
+  } else if (cp < 0x800) {
+    out += static_cast<char>(0xC0 | (cp >> 6));
+    out += static_cast<char>(0x80 | (cp & 0x3F));
+  } else if (cp < 0x10000) {
+    out += static_cast<char>(0xE0 | (cp >> 12));
+    out += static_cast<char>(0x80 | ((cp >> 6) & 0x3F));
+    out += static_cast<char>(0x80 | (cp & 0x3F));
+  } else {
+    out += static_cast<char>(0xF0 | (cp >> 18));
+    out += static_cast<char>(0x80 | ((cp >> 12) & 0x3F));
+    out += static_cast<char>(0x80 | ((cp >> 6) & 0x3F));
+    out += static_cast<char>(0x80 | (cp & 0x3F));
+  }
+}
+
+// Attribute values with the predefined and numeric character references resolved - enough to
+// compare namespace URIs. False for an unknown or broken reference.
+bool decode(std::string const& raw, std::string& out) {
+  static const std::map<std::string, char> named = {
+      {"amp", '&'}, {"lt", '<'}, {"gt", '>'}, {"quot", '"'}, {"apos", '\''}};
+  out.clear();
+  for (size_t i = 0; i < raw.size(); ++i) {
+    if (raw[i] != '&') {
+      out += raw[i];
+      continue;
+    }
+    size_t semi = raw.find(';', i);
+    if (semi == std::string::npos) return false;
+    std::string ref = raw.substr(i + 1, semi - i - 1);
+    if (auto it = named.find(ref); it != named.end()) {
+      out += it->second;
+    } else if (ref.size() > 1 && ref[0] == '#') {
+      bool hex = ref[1] == 'x';
+      std::string digits = ref.substr(hex ? 2 : 1);
+      if (digits.empty() || digits.size() > 8) return false;
+      unsigned long cp = 0;
+      for (char d : digits) {
+        int v = (d >= '0' && d <= '9') ? d - '0'
+                : hex && d >= 'a' && d <= 'f' ? d - 'a' + 10
+                : hex && d >= 'A' && d <= 'F' ? d - 'A' + 10
+                                              : -1;
+        if (v < 0) return false;
+        cp = cp * (hex ? 16 : 10) + static_cast<unsigned long>(v);
+      }
+      if (cp == 0 || cp > 0x10FFFF) return false;
+      append_utf8(out, cp);
+    } else {
+      return false;
+    }
+    i = semi;
+  }
+  return true;
+}
+
+using Bindings = std::map<std::string, std::string>;  // prefix ("" = default) -> namespace URI
+
+struct Element {
+  std::string qname;
+  Bindings bindings;
+  bool rdf_root;
+};
+
+// The namespace of a qualified name under `bindings`; false for an unbound prefix.
+bool resolve(std::string const& qname, Bindings const& bindings, bool is_attribute, std::string& ns,
+             std::string& local) {
+  size_t colon = qname.find(':');
+  if (colon == std::string::npos) {
+    local = qname;
+    ns.clear();
+    if (!is_attribute) {  // unprefixed attributes have no namespace; elements take the default
+      auto it = bindings.find("");
+      if (it != bindings.end()) ns = it->second;
+    }
+    return !local.empty();
+  }
+  std::string prefix = qname.substr(0, colon);
+  local = qname.substr(colon + 1);
+  if (prefix.empty() || local.empty() || local.find(':') != std::string::npos) return false;
+  if (prefix == "xml") {
+    ns = kXmlNs;
+    return true;
+  }
+  auto it = bindings.find(prefix);
+  if (it == bindings.end() || it->second.empty()) return false;
+  ns = it->second;
+  return true;
+}
+
+class Scanner {
+ public:
+  explicit Scanner(std::string const& xml) : xml_(xml) {}
+
+  Scan run() {
+    Scan out;
+    if (!walk(out)) return Scan{};
+    out.well_formed = stack_.empty() && seen_root_;
+    if (!out.well_formed) return Scan{};
+    return out;
+  }
+
+ private:
+  bool skip_past(std::string const& end) {
+    size_t at = xml_.find(end, pos_);
+    if (at == std::string::npos) return false;
+    pos_ = at + end.size();
+    return true;
+  }
+
+  bool starts(std::string const& s) const { return xml_.compare(pos_, s.size(), s) == 0; }
+
+  std::string name() {
+    size_t start = pos_;
+    while (pos_ < xml_.size() && !is_name_end(xml_[pos_])) ++pos_;
+    return xml_.substr(start, pos_ - start);
+  }
+
+  void spaces() {
+    while (pos_ < xml_.size() && is_space(xml_[pos_])) ++pos_;
+  }
+
+  bool walk(Scan& out) {
+    while (pos_ < xml_.size()) {
+      size_t lt = xml_.find('<', pos_);
+      if (lt == std::string::npos) return true;
+      pos_ = lt;
+      bool ok = starts("<!--")      ? skip_past("-->")
+                : starts("<![CDATA[") ? !stack_.empty() && skip_past("]]>")
+                : starts("<?")        ? skip_past("?>")
+                : starts("<!DOCTYPE") ? doctype()
+                : starts("</")        ? end_tag(out)
+                : starts("<!")        ? false
+                                      : start_tag(out);
+      if (!ok) return false;
+    }
+    return true;
+  }
+
+  bool doctype() {
+    if (seen_root_ || !stack_.empty()) return false;
+    for (int brackets = 0; pos_ < xml_.size(); ++pos_) {
+      char c = xml_[pos_];
+      if (c == '[') ++brackets;
+      if (c == ']') --brackets;
+      if (c == '>' && brackets == 0) {
+        ++pos_;
+        return true;
+      }
+    }
+    return false;
+  }
+
+  bool end_tag(Scan& out) {
+    size_t lt = pos_;
+    pos_ += 2;
+    std::string qname = name();
+    spaces();
+    if (pos_ >= xml_.size() || xml_[pos_] != '>' || stack_.empty() || stack_.back().qname != qname) return false;
+    ++pos_;
+    if (stack_.back().rdf_root) out.rdf_close = lt;
+    stack_.pop_back();
+    return true;
+  }
+
+  bool start_tag(Scan& out) {
+    ++pos_;
+    std::string qname = name();
+    if (qname.empty()) return false;
+    if (stack_.empty() && seen_root_) return false;  // a second root element
+
+    std::vector<std::pair<std::string, std::string>> attributes;
+    Bindings bindings = stack_.empty() ? Bindings{} : stack_.back().bindings;
+    bool self_closing = false;
+    while (true) {
+      size_t before = pos_;
+      spaces();
+      if (pos_ >= xml_.size()) return false;
+      if (xml_[pos_] == '>') {
+        ++pos_;
+        break;
+      }
+      if (starts("/>")) {
+        pos_ += 2;
+        self_closing = true;
+        break;
+      }
+      if (pos_ == before) return false;  // attributes must be separated by white space
+      std::string attribute = name();
+      spaces();
+      if (attribute.empty() || pos_ >= xml_.size() || xml_[pos_] != '=') return false;
+      ++pos_;
+      spaces();
+      if (pos_ >= xml_.size() || (xml_[pos_] != '"' && xml_[pos_] != '\'')) return false;
+      char quote = xml_[pos_++];
+      size_t close = xml_.find(quote, pos_);
+      if (close == std::string::npos) return false;
+      std::string raw = xml_.substr(pos_, close - pos_), value;
+      pos_ = close + 1;
+      if (raw.find('<') != std::string::npos || !decode(raw, value)) return false;
+      if (attribute == "xmlns") {
+        bindings[""] = value;
+      } else if (attribute.rfind("xmlns:", 0) == 0) {
+        // An empty prefix is no name; undeclaring a prefix is XML 1.1 only.
+        if (attribute.size() == 6 || value.empty()) return false;
+        bindings[attribute.substr(6)] = value;
+      } else {
+        attributes.emplace_back(attribute, value);
+      }
+    }
+
+    std::string ns, local;
+    if (!resolve(qname, bindings, false, ns, local)) return false;
+    out.properties.insert({ns, local});
+    for (auto const& [attribute, value] : attributes) {
+      std::string attribute_ns, attribute_local;
+      if (!resolve(attribute, bindings, true, attribute_ns, attribute_local)) return false;
+      if (!attribute_ns.empty()) out.properties.insert({attribute_ns, attribute_local});
+    }
+
+    bool rdf_root = ns == kRdfNs && local == "RDF" && !seen_rdf_;
+    if (rdf_root) seen_rdf_ = true;
+    if (stack_.empty()) seen_root_ = true;
+    if (self_closing) return true;
+    stack_.push_back({qname, std::move(bindings), rdf_root});
+    return true;
+  }
+
+  std::string const& xml_;
+  size_t pos_ = 0;
+  std::vector<Element> stack_;
+  bool seen_rdf_ = false;  // only the first rdf:RDF element counts
+  bool seen_root_ = false;
+};
+
+}  // namespace
+
+Scan scan(std::string const& xml) { return Scanner(xml).run(); }
+
+}  // namespace qpdf_ruby::xmp

data/ext/qpdf_ruby/xmp_scan.hpp

@@ -0,0 +1,27 @@
+#pragma once
+
+#include <set>
+#include <string>
+#include <utility>
+
+namespace qpdf_ruby::xmp {
+
+// What the identification step needs to know about an XMP packet, read with namespace scoping:
+// comments, CDATA sections, processing instructions and a DOCTYPE are skipped, so a property that
+// is only mentioned in one of them does not count.
+struct Scan {
+  // Every tag closed in order, one root element, every prefix bound, attributes quoted and
+  // separated. Not a validating parser: names and text outside the root are not checked.
+  bool well_formed = false;
+  // (namespace URI, local name) of every element and every namespaced attribute - XMP allows a
+  // simple property in either form.
+  std::set<std::pair<std::string, std::string>> properties;
+  // Offset of the "<" of the end tag of the outermost rdf:RDF element; npos without one.
+  size_t rdf_close = std::string::npos;
+
+  bool has(std::string const& ns, std::string const& local) const { return properties.count({ns, local}) > 0; }
+};
+
+Scan scan(std::string const& xml);
+
+}  // namespace qpdf_ruby::xmp

data/lib/qpdf_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module QpdfRuby
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/qpdf_ruby.rb

@@ -8,6 +8,7 @@ module QpdfRuby
   ENCRYPTION_REVISION_AES_256  = 5  # Acrobat 9.x, 256-bit AES
   ENCRYPTION_REVISION_AES_256U = 6  # Acrobat X, 256-bit AES (PDF 2.0+ update)
 
-  class Error < StandardError; end
-  # Your code goes here...
+  # Raised for every failure inside the extension (a PDF QPDF cannot read, write errors, ...).
+  # A RuntimeError, so code that rescued the extension's RuntimeErrors before keeps working.
+  class Error < RuntimeError; end
 end

data/sig/qpdf_ruby.rbs

@@ -1,4 +1,81 @@
 module QpdfRuby
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  ENCRYPTION_REVISION_AES_128: Integer
+  ENCRYPTION_REVISION_AES_256: Integer
+  ENCRYPTION_REVISION_AES_256U: Integer
+  PRINT_FULL: Integer
+  PRINT_LOW: Integer
+  PRINT_NONE: Integer
+
+  class Error < RuntimeError
+  end
+
+  class Document
+    type untagged_counts = {
+      paths: Integer,
+      texts: Integer,
+      xobjects: Integer,
+      shadings: Integer,
+      inline_images: Integer,
+      total: Integer
+    }
+
+    type pdfua_report = {
+      decorations: Integer,
+      artifacts: untagged_counts,
+      links: Integer,
+      list_bodies: Integer,
+      roles: Integer,
+      figure_groups: Integer,
+      figures_without_alt: Integer,
+      identified: bool,
+      unidentified_reason: String?
+    }
+
+    type link = { page: Integer, uri: String?, contents: String? }
+
+    def self.from_memory: (String data, ?String? password) -> Document
+
+    def initialize: (String filename, ?String? password) -> void
+
+    def write: (String filename) -> nil
+    def to_memory: () -> String
+
+    def show_structure: () -> String
+    def ensure_bbox: () -> nil
+
+    def apply_pdfua_fixes: (?link_texts: Hash[untyped, untyped]?, ?title: String?) -> pdfua_report
+    def mark_untagged_content_as_artifacts: () -> untagged_counts
+    # deprecated: use #mark_untagged_content_as_artifacts
+    def mark_paths_as_artifacts: () -> untagged_counts
+    def untagged_content: () -> untagged_counts
+    def describe_links: (?Hash[untyped, untyped]? texts) -> Integer
+    def artifact_tagged_decorations: () -> Integer
+    def wrap_list_bodies: () -> Integer
+    def parent_tree_mismatches: () -> Integer
+    def map_nonstandard_roles: () -> Integer
+    def retag_grouping_figures: () -> Integer
+    def figures_without_alt: () -> Integer
+    def add_pdfua_identification: (?title: String?) -> bool
+
+    def links: () -> Array[link]
+    def metadata: () -> String?
+    def role_map: () -> Hash[String, String]
+
+    def encrypt: (
+      ?user_pw: String,
+      ?owner_pw: String,
+      ?encryption_revision: Integer,
+      ?allow_print: Integer,
+      ?allow_modify: boolish,
+      ?allow_extract: boolish,
+      ?accessibility: boolish,
+      ?assemble: boolish,
+      ?annotate_and_form: boolish,
+      ?form_filling: boolish,
+      ?encrypt_metadata: boolish,
+      ?use_aes: boolish
+    ) -> nil
+  end
 end