rbpptx 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4494da8ee976e807536010f1ffe12a0dbaecd1d13e4b91b22fc9874c6bf8cc60
-  data.tar.gz: f8b93b7f227deb25e04f1c1841210ece0f0806298e1b1ce9f910c23bb343544d
+  metadata.gz: c99ecf7e3e63fbcaa1de703c43ef4b922b91e7b28d66dccfda044031ec2a0032
+  data.tar.gz: b87c7117ae034d6c414999223ccb96e460b5ca0535463c32793dfd4af8183c30
 SHA512:
-  metadata.gz: 4db6d5cf34753a2ffc93472f08629fe515d28eb69053cb59dbcacb0138cd972eb214a7f78678b824f8f8b5f15cb81d58ec6a971ddd948e2d1e4ee4c39c5e6519
-  data.tar.gz: 1a988ba99c8a250f70a6edda334574701492e4b99482ff2055f65c10a7a02d37346753a7fb97a69f49c0bc3ca0d4d1a26d024a42546f93b20bdf8e57e0a4062f
+  metadata.gz: d60c2d4f46dfde855f3ca344789d3c44a2e1c058b2c4e223e0933b48c14cd2526678117006b21fdef481fb90a81792fd305530a50a3ff6fa8d804a9173d74179
+  data.tar.gz: da943c3e815292ab9828868d747c3808dbd4dbe971a9a297b4bd57c290780d7945ae0867a50edda626f5f9aaea70193b8fa7289aeff292dae0306559b46f3fec

data/CHANGELOG.md

@@ -6,6 +6,54 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-11-10
+
+### Added
+
+- Placeholder-aware API: `Slide#title` (the `:title` / `:ctrTitle`
+  placeholder), `Slide#placeholders` returning `Rbpptx::Placeholders`
+  (`placeholders[:body]` by type, `placeholders[1]` by `<p:ph idx>`),
+  `Shape#placeholder?` and `Shape#placeholder_idx`.
+- Speaker notes: `Slide#notes` / `Slide#notes=`, `Slide#notes_slide`
+  returning `Rbpptx::NotesSlide`. Setting notes on a slide without a notes
+  page creates one from the notes master; raises `Rbpptx::Error` when the
+  presentation has no notes master.
+- Group shapes and tables: `Slide#groups` (`Rbpptx::GroupShape`, nestable),
+  `Slide#all_shapes` (every `<p:sp>`, descending into groups),
+  `Slide#tables` / `Slide#all_tables` (`Rbpptx::Table`, `TableRow`,
+  `TableCell`). Table cells support the same `text` / `text=` /
+  `paragraphs` / `runs` API as shapes, plus `merge_origin?` / `spanned?`.
+- Slide structure edits: `Presentation#move_slide`,
+  `Presentation#delete_slide` (removes the notes page, section and
+  custom-show entries, relationships, and content-type overrides; refuses
+  when another part still references the slide unless `unlink: true` is
+  given, which strips "jump to slide" hyperlinks first), and
+  `Presentation#slide(index)` raising `Rbpptx::SlideNotFoundError`.
+
+### Changed
+
+- Allow `rubyzip` 3.x (`>= 2.3, < 4`). Development dependencies now allow
+  `rbs` 4.x and `rdoc` 8.x.
+- Re-serialized parts are written without pretty-printing, so edits no
+  longer re-indent single-line XML.
+- `text=` (shapes and table cells) keeps template formatting on empty
+  fields: when the body has no runs, the first `<a:endParaRPr>` is used as
+  the run template, and the first paragraph's `<a:pPr>` (alignment,
+  indent) and `<a:endParaRPr>` are cloned onto every new paragraph.
+  Previously, filling an empty form field fell back to PowerPoint's default
+  18pt text and lost the field's alignment.
+
+### Fixed
+
+- Saving a package whose ZIP entries use data descriptors (general-purpose
+  bit 3, as written by Google Slides exports and other streaming zippers)
+  produced a file PowerPoint refused to open, even for a no-op save. The
+  flag is now cleared on raw-copied entries, whose local headers carry the
+  real CRC and sizes.
+- Saving twice from the same `Presentation` lost the edits made before the
+  first save; saving over the source file broke later lazy reads of
+  not-yet-parsed slides.
+
 ## [0.1.0] - 2026-04-26
 
 - Initial public release.

data/README.md

@@ -29,6 +29,13 @@ Supported:
 - **surgical setter**: `run.text = "..."` rewrites only the run's `<a:t>`
   content, preserving `<a:rPr>`, soft line breaks, sibling runs, paragraph
   properties, and unknown OOXML extensions
+- placeholder-aware access: `slide.title`, `slide.placeholders[:body]`,
+  `slide.placeholders[1]` (by `idx`)
+- speaker notes: read and write `slide.notes`; a notes page is created from
+  the notes master when the slide has none
+- text inside group shapes (nested to any depth) and table cells:
+  `slide.groups`, `slide.all_shapes`, `slide.tables`, `table.cell(r, c)`
+- reorder and delete slides: `pres.move_slide`, `pres.delete_slide`
 - save back to a new path, or overwrite the original via temp-file + atomic
   rename — unmodified entries stream through untouched
 
@@ -36,10 +43,10 @@ Out of scope:
 
 - creating a presentation from scratch — `Rbpptx.new` is reserved for a
   future release and currently raises `NotImplementedError`
-- inserting / deleting / reordering / duplicating slides
+- inserting / duplicating slides
 - editing media (images, embedded fonts) or adding new shapes
-- placeholder-aware API (`slide.title`, `slide.placeholders[:body]`)
-- notes pages, comments, charts, SmartArt
+- adding / removing table rows and columns, table styling
+- comments, charts, SmartArt
 - legacy `.ppt` (BIFF/CFB) input — `rbpptx` reads OOXML `.pptx` only.
   Convert first, e.g. `libreoffice --headless --convert-to pptx file.ppt`.
   `Rbpptx.open` detects the OLE compound-file magic and raises
@@ -58,7 +65,7 @@ Or in a `Gemfile`:
 gem "rbpptx"
 ```
 
-Requires Ruby 3.2+, `nokogiri`, and `rubyzip`.
+Requires Ruby 3.2+, `nokogiri`, and `rubyzip` (2.3+ or 3.x).
 
 ## Usage
 
@@ -115,16 +122,92 @@ Rbpptx.open("template.pptx") do |pres|
 end
 ```
 
-Or target by placeholder role:
+### Placeholders
+
+Target shapes by placeholder role instead of by position:
 
 ```ruby
 Rbpptx.open("template.pptx") do |pres|
-  pres.slides.first.shapes.find { |s| s.placeholder_type == :ctrTitle }.text = "Q2 Review"
-  pres.slides.first.shapes.find { |s| s.placeholder_type == :subTitle }.text = "Acme Inc."
+  slide = pres.slides.first
+  slide.title.text = "Q2 Review"                    # :title or :ctrTitle
+  slide.placeholders[:subTitle].text = "Acme Inc."  # Symbol: by type
+  slide.placeholders[1].text = "Acme Inc."          # Integer: by <p:ph idx>
+  slide.placeholders.map(&:placeholder_type)        # => [:ctrTitle, :subTitle]
   pres.save("filled.pptx")
 end
 ```
 
+Integer keys follow python-pptx and match the placeholder's `idx`
+attribute, not its position in the list.
+
+### Speaker notes
+
+```ruby
+Rbpptx.open("deck.pptx") do |pres|
+  pres.slides.each { |s| puts s.notes }   # "" when the slide has no notes page
+  pres.slides[0].notes = "Talk about Q2.\nThen Q3."
+  pres.save("deck.pptx")
+end
+```
+
+Setting notes on a slide without a notes page creates one from the
+presentation's notes master (new part, relationships, and content-type
+override). Decks that have never had notes may lack a notes master; in that
+case `notes=` raises `Rbpptx::Error` — add a note in PowerPoint once to
+create it.
+
+### Groups and tables
+
+`slide.shapes` returns only the top-level `<p:sp>` shapes. Shapes inside
+group shapes and the text of table cells are reachable separately:
+
+```ruby
+Rbpptx.open("deck.pptx") do |pres|
+  slide = pres.slides[0]
+
+  slide.groups.first.shapes        # direct children of a group
+  slide.all_shapes                 # every <p:sp>, descending into nested groups
+  slide.all_shapes.flat_map(&:runs).each { |r| r.text = r.text.gsub("{{name}}", "Acme") }
+
+  table = slide.tables.first       # slide.all_tables also searches groups
+  table.row_count                  # => 3
+  table.cell(0, 1).text            # => "Q2"
+  table.cell(1, 1).text = "42"     # same setters as Shape (text=, runs, paragraphs)
+  table.rows.map { |row| row.cells.map(&:text) }
+  table.cell(1, 0).spanned?        # covered by a merged cell?
+
+  pres.save("deck.pptx")
+end
+```
+
+### Reordering and deleting slides
+
+```ruby
+Rbpptx.open("deck.pptx") do |pres|
+  pres.move_slide(0, -1)             # first slide to the end
+  pres.move_slide(pres.slides[3], 0)
+  pres.delete_slide(2)               # also removes its notes page
+  pres.slide(0).name                 # raises SlideNotFoundError when out of range
+  pres.save("deck.pptx")
+end
+```
+
+`delete_slide` removes the slide's `<p:sldId>`, its relationship, its
+custom-show and section entries, its content-type override, and the slide
+and notes parts. Shared parts (layouts, images) are kept.
+
+If another slide still points at the one being deleted — typically a
+"jump to slide" link on an agenda slide — deletion is refused with
+`Rbpptx::Error`, because PowerPoint treats a dangling reference as a
+corrupt file. Pass `unlink: true` to remove those hyperlinks first (the
+link text stays):
+
+```ruby
+pres.delete_slide(5, unlink: true)
+```
+
+References that are not hyperlinks are always refused.
+
 ### Same-path overwrite
 
 `Presentation#save` writes to a temp file in the target directory and
@@ -164,7 +247,7 @@ the presentation path and (where relevant) the offending part name:
 | `Rbpptx::UnsupportedFormatError`   | file is empty, not a ZIP, or a legacy `.ppt` (BIFF/CFB) container |
 | `Rbpptx::PresentationFormatError`  | `_rels/.rels`, `ppt/presentation.xml`, or its rels are malformed  |
 | `Rbpptx::SlideFormatError`         | a slide part is missing or its XML cannot be parsed               |
-| `Rbpptx::SlideNotFoundError`       | reserved for future index-based slide accessors                   |
+| `Rbpptx::SlideNotFoundError`       | `slide(i)` / `move_slide` / `delete_slide` index is out of range  |
 | `Rbpptx::ClosedPresentationError`  | `slides` / `save` called after `close`                            |
 
 ```ruby
@@ -188,7 +271,10 @@ end
   re-serialize only the slides whose shapes have been mutated, and stream
   every other ZIP entry through with its already-deflated bytes
   (`Zip::OutputStream#copy_raw_entry`) — no decompress, no re-deflate.
-  Bit-identical preservation, not just content-identical.
+  The compressed payload is copied verbatim. Entries written by streaming
+  zippers (e.g. Google Slides exports) get their "data descriptor" flag
+  cleared, since the real CRC and sizes are written into the local header
+  instead.
 - **rPr cloning, not rebuilding.** When a shape's text is replaced, the
   first existing `<a:rPr>` is deep-cloned onto each new run. A template's
   font, size, color, and `lang` attribute carry through without `rbpptx`

data/lib/rbpptx/package.rb

@@ -0,0 +1,274 @@
+require "pathname"
+require "set"
+
+module Rbpptx
+  # The OPC (Open Packaging Conventions) container underneath a presentation.
+  #
+  # +Package+ owns the open ZIP and is the single place that knows how parts
+  # are read, mutated, added, removed and written back. Parts are parsed on
+  # demand and cached; once a caller signals a mutation via {#touch}, the
+  # cached document is serialized in place of the original bytes on save.
+  # Everything else is streamed through with +copy_raw_entry+, so parts the
+  # gem never looked at round-trip byte-for-byte.
+  #
+  # @api private
+  class Package
+    PKG_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships".freeze
+    CT_NS = "http://schemas.openxmlformats.org/package/2006/content-types".freeze
+    CONTENT_TYPES_PART = "[Content_Types].xml".freeze
+    SAVE_OPTIONS = Nokogiri::XML::Node::SaveOptions::AS_XML
+
+    # A single +<Relationship>+ entry, with its target already resolved to an
+    # absolute part name (+nil+ for external targets such as hyperlinks).
+    Relationship = Struct.new(:id, :type, :target, :part, :external, keyword_init: true)
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+      @zip = Zip::File.open(path)
+      @docs = {}
+      @modified = Set.new
+      @deleted = Set.new
+    end
+
+    def close
+      @zip&.close
+      @zip = nil
+    end
+
+    # @return [Boolean] whether +name+ exists in the package as it would be
+    #   saved right now
+    def part?(name)
+      return false if @deleted.include?(name)
+
+      @docs.key?(name) || !@zip.find_entry(name).nil?
+    end
+
+    # @return [Array<String>] every part name as it would be saved right now
+    def part_names
+      names = @zip.entries.reject(&:directory?).map(&:name).reject { |n| @deleted.include?(n) }
+      names | @modified.to_a
+    end
+
+    # Parses (and caches) the XML part +name+.
+    #
+    # @raise [error_class] if the part is missing or not well-formed
+    def xml(name, error_class: PresentationFormatError)
+      @docs[name] ||= begin
+        entry = @deleted.include?(name) ? nil : @zip.find_entry(name)
+        raise error_class, "#{@path}: missing part #{name}" unless entry
+
+        doc = Nokogiri::XML(entry.get_input_stream.read)
+        raise error_class, "#{@path}: #{name}: #{doc.errors.first}" unless doc.errors.empty?
+
+        doc
+      end
+    end
+
+    # Marks +name+ as mutated so its cached document is written on save.
+    def touch(name)
+      @modified << name
+      true
+    end
+
+    # Adds a brand-new part (or replaces a deleted one).
+    def add(name, doc)
+      @deleted.delete(name)
+      @docs[name] = doc
+      @modified << name
+      doc
+    end
+
+    # Removes +name+, its relationships part, and its content-type override.
+    def delete(name)
+      [name, rels_part_for(name)].each do |n|
+        @docs.delete(n)
+        @modified.delete(n)
+        @deleted << n
+      end
+      remove_content_type_override(name)
+    end
+
+    # ---------- relationships ----------
+
+    # @return [String] the rels part name for +part+, e.g.
+    #   +ppt/slides/_rels/slide1.xml.rels+
+    def rels_part_for(part)
+      dir = File.dirname(part)
+      base = File.basename(part)
+      dir == "." ? "_rels/#{base}.rels" : "#{dir}/_rels/#{base}.rels"
+    end
+
+    # @return [Array<Relationship>] relationships whose source is +part+
+    def relationships(part)
+      rels_part = rels_part_for(part)
+      return [] unless part?(rels_part)
+
+      xml(rels_part).xpath("/pkg:Relationships/pkg:Relationship", "pkg" => PKG_REL_NS).map do |r|
+        external = r["TargetMode"] == "External"
+        Relationship.new(
+          id: r["Id"], type: r["Type"], target: r["Target"],
+          part: external ? nil : resolve(part, r["Target"].to_s), external: external
+        )
+      end
+    end
+
+    # @return [Array<String>] internal targets of +part+'s relationships of
+    #   type +rel_type+
+    def related(part, rel_type)
+      relationships(part).select { |r| r.type == rel_type && r.part }.map(&:part)
+    end
+
+    # @return [Array<String>] parts that hold an internal relationship
+    #   pointing at +target_part+
+    def referrers_of(target_part)
+      part_names.grep(%r{(\A|/)_rels/[^/]+\.rels\z}).filter_map do |rels_part|
+        source = source_part_for(rels_part)
+        source if relationships(source).any? { |r| r.part == target_part }
+      end
+    end
+
+    # Adds a relationship from +source+ to +target_part+, creating the rels
+    # part if needed.
+    #
+    # @return [String] the new relationship id
+    def add_relationship(source, rel_type, target_part)
+      rels_part = rels_part_for(source)
+      unless part?(rels_part)
+        add(rels_part, Nokogiri::XML(<<~XML))
+          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+          <Relationships xmlns="#{PKG_REL_NS}"/>
+        XML
+      end
+
+      doc = xml(rels_part)
+      root = doc.root
+      taken = root.xpath("./pkg:Relationship/@Id", "pkg" => PKG_REL_NS).map(&:value)
+      n = 1
+      n += 1 while taken.include?("rId#{n}")
+      rid = "rId#{n}"
+
+      rel = doc.create_element("Relationship", "Id" => rid, "Type" => rel_type,
+                                               "Target" => relative_target(source, target_part))
+      root.add_child(rel)
+      touch(rels_part)
+      rid
+    end
+
+    def remove_relationship(source, rid)
+      rels_part = rels_part_for(source)
+      return unless part?(rels_part)
+
+      doc = xml(rels_part)
+      doc.xpath("/pkg:Relationships/pkg:Relationship[@Id=$rid]", { "pkg" => PKG_REL_NS }, { "rid" => rid }).each(&:remove)
+      touch(rels_part)
+    end
+
+    # Resolves a relationship +target+ relative to the directory of +source+.
+    def resolve(source, target)
+      return target.sub(%r{\A/}, "") if target.start_with?("/")
+
+      base_dir = File.dirname(source)
+      base_dir = "" if base_dir == "."
+      File.expand_path(target, "/#{base_dir}").sub(%r{\A/}, "")
+    end
+
+    def relative_target(source, target_part)
+      base_dir = File.dirname("/#{source}")
+      Pathname.new("/#{target_part}").relative_path_from(Pathname.new(base_dir)).to_s
+    end
+
+    # ---------- content types ----------
+
+    def add_content_type_override(part, content_type)
+      doc = xml(CONTENT_TYPES_PART)
+      el = doc.create_element("Override", "PartName" => "/#{part}", "ContentType" => content_type)
+      doc.root.add_child(el)
+      touch(CONTENT_TYPES_PART)
+    end
+
+    def remove_content_type_override(part)
+      doc = xml(CONTENT_TYPES_PART)
+      nodes = doc.xpath("/ct:Types/ct:Override[@PartName=$name]", { "ct" => CT_NS }, { "name" => "/#{part}" })
+      return if nodes.empty?
+
+      nodes.each(&:remove)
+      touch(CONTENT_TYPES_PART)
+    end
+
+    # ---------- save ----------
+
+    # Writes the package to +out_path+ via temp file + atomic rename.
+    def save(out_path)
+      tmp_path = "#{out_path}.rbpptx-tmp.#{Process.pid}.#{rand(1 << 32).to_s(16)}"
+      begin
+        Zip::OutputStream.open(tmp_path) do |out|
+          written = Set.new
+          @zip.each do |entry|
+            next if entry.directory? || @deleted.include?(entry.name)
+
+            if @modified.include?(entry.name)
+              write_doc(out, entry.name)
+            else
+              copy_raw(out, entry)
+            end
+            written << entry.name
+          end
+          (@modified.to_a - written.to_a).each { |name| write_doc(out, name) }
+        end
+        File.rename(tmp_path, out_path)
+      rescue StandardError
+        File.unlink(tmp_path) if File.exist?(tmp_path)
+        raise
+      end
+
+      # The open Zip::File re-reads entries from @path by name, so after
+      # overwriting our own source the old central directory no longer
+      # matches the file on disk. Reopen so later lazy reads stay valid.
+      reopen if File.expand_path(out_path) == File.expand_path(@path)
+      out_path
+    end
+
+    private
+
+    DATA_DESCRIPTOR_FLAG = 0b1000
+    private_constant :DATA_DESCRIPTOR_FLAG
+
+    # Streams +entry+'s compressed bytes through unchanged.
+    #
+    # Entries written by streaming zippers (Google Slides exports, among
+    # others) set general-purpose bit 3: "CRC and sizes follow the data in
+    # a data descriptor". +copy_raw_entry+ writes the real CRC and sizes
+    # into the local header but keeps that bit and emits no descriptor,
+    # which PowerPoint rejects as corrupt. Clearing the bit on a copy makes
+    # the header self-describing again; the payload is not recompressed.
+    def copy_raw(out, entry)
+      if entry.gp_flags & DATA_DESCRIPTOR_FLAG != 0
+        entry = entry.dup
+        entry.gp_flags &= ~DATA_DESCRIPTOR_FLAG
+      end
+      out.copy_raw_entry(entry)
+    end
+
+    def write_doc(out, name)
+      out.put_next_entry(name)
+      out.write(@docs.fetch(name).to_xml(save_with: SAVE_OPTIONS))
+    end
+
+    def reopen
+      @zip.close
+      @zip = Zip::File.open(@path)
+      @deleted.clear
+    end
+
+    def source_part_for(rels_part)
+      return "" if rels_part == "_rels/.rels"
+
+      dir = File.dirname(rels_part)
+      base = File.basename(rels_part, ".rels")
+      parent = File.dirname(dir)
+      parent == "." ? base : "#{parent}/#{base}"
+    end
+  end
+end