rbpptx 0.1.0

checksums.yaml

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

data/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-26
+
+- Initial public release.
+
+### Added
+
+- `Rbpptx.open(path)` opens a `.pptx` package and returns a
+  `Rbpptx::Presentation`. Block form auto-closes the underlying ZIP on
+  return or exception, matching the `File.open` / `Zip::File.open` idiom.
+- `Rbpptx::Presentation#slides` enumerates slides in presentation order
+  (i.e. the order of `<p:sldId>` entries in `ppt/presentation.xml`,
+  resolved via the presentation's own rels), parsing slide XML lazily.
+- `Rbpptx::Slide#shapes` returns each `<p:sp>` child of the slide's
+  `<p:spTree>` wrapped as `Rbpptx::Shape`, with its own dirty tracking so
+  the slide knows whether its XML needs to be re-serialized on save.
+- `Rbpptx::Shape#text` returns the shape's concatenated text body —
+  paragraphs joined with `"\n"`, soft line breaks (`<a:br>`) also rendered
+  as `"\n"`.
+- `Rbpptx::Shape#text=` replaces the shape's text body. Lines (separated by
+  `"\n"`) become individual `<a:p>` paragraphs. Run properties from the
+  first existing `<a:rPr>` (font, size, color, language) are cloned onto
+  each new run so template formatting carries through. Shapes without a
+  `<p:txBody>` raise `Rbpptx::Error` rather than silently failing.
+- `Rbpptx::Shape#placeholder_type` returns the placeholder role as a
+  Symbol (`:ctrTitle`, `:subTitle`, `:title`, `:body`, `:obj`, `:ftr`,
+  `:dt`, `:sldNum`, `:pic`, ...) by reading
+  `<p:nvSpPr>/<p:nvPr>/<p:ph type="...">`. Returns `:body` when the
+  placeholder element is present without a `type` attribute (matches the
+  OOXML default), and `nil` for non-placeholder shapes.
+- `Rbpptx::Shape#paragraphs` and `Rbpptx::Shape#runs` expose the OOXML
+  paragraph and run granularity below the shape: `paragraphs` returns the
+  shape's `<a:p>` children; `runs` flattens runs across paragraphs in
+  document order.
+- `Rbpptx::Paragraph` and `Rbpptx::Run` wrappers; `Run#text=` is a
+  surgical text setter that rewrites only the run's `<a:t>` content.
+  `<a:rPr>`, `<a:br>` soft breaks, sibling runs, paragraph properties,
+  `<a:endParaRPr>`, and unknown OOXML extensions on the shape are all
+  preserved. Use this instead of `Shape#text=` when the template's
+  per-run formatting matters (e.g. replacing a `{{slot}}` marker inside a
+  multi-run paragraph).
+- `Rbpptx::Presentation#save(path)` writes the presentation to disk via a
+  sibling temp file and atomic rename, so `pres.save(original_path)` is
+  safe. Only slides whose shapes have been mutated are re-serialized;
+  every other ZIP entry (themes, masters, layouts, media, fonts, rels,
+  PowerPoint-extension XML) streams through with its already-deflated
+  bytes via `Zip::OutputStream#copy_raw_entry` — no inflate, no
+  re-deflate. The bytes of unmodified parts are bit-identical to the
+  source ZIP.
+- `Rbpptx::UnsupportedFormatError` raised by `Rbpptx.open` when the file
+  is empty, not a ZIP container, or a legacy `.ppt` (BIFF/CFB) file.
+  Legacy inputs are detected by the OLE compound-file magic and reported
+  with a `libreoffice --headless --convert-to pptx` hint rather than
+  surfacing an opaque `Zip::Error` from rubyzip.
+- `Rbpptx::PresentationFormatError`, `Rbpptx::SlideFormatError`,
+  `Rbpptx::SlideNotFoundError`, `Rbpptx::ClosedPresentationError` for
+  malformed-input and use-after-close cases. All error messages carry the
+  presentation path and (where relevant) the offending part name.
+- RBS signatures for the public surface (`sig/rbpptx.rbs`).
+- `benchmark/compare.rb` drives a three-way comparison against
+  python-pptx (via `uv run --with python-pptx`) and docxtemplater +
+  PizZip (via `node`). Three scenarios — read (open + walk all slides +
+  concatenate text), fill_one (replace one shape + save), fill_many
+  (replace 10 shapes + save) — configurable via `RBPPTX_BENCH_SAMPLE`,
+  `RBPPTX_BENCH_WARMUP`, `RBPPTX_BENCH_ITERATIONS`. On the 18 MB sample
+  deck rbpptx is 4.7x / 16.8x / 13.0x faster than python-pptx and
+  2.0x / 4.5x / 3.4x faster than docxtemplater across the three
+  scenarios.
+- `benchmark/fixture_gen.py` synthesizes a sized deck with `{{slot_*}}`
+  markers via python-pptx, so save-path benchmarks can isolate the cost
+  of the XML rewrite from the cost of re-deflating embedded media.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taro KOBAYASHI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,276 @@
+# rbpptx
+
+[![Gem Version](https://badge.fury.io/rb/rbpptx.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/rbpptx)
+
+Read-and-edit Ruby gem for `.pptx` (PowerPoint, OOXML) files, modeled after
+[python-pptx](https://github.com/scanny/python-pptx).
+
+`rbpptx` is built around a single design promise: **what we don't understand,
+we don't touch**. The presentation is opened as a ZIP package, only the
+parts you mutate are re-serialized, and every other entry — slide layouts,
+masters, themes, embedded fonts, images, animations, hyperlink colors,
+PowerPoint-extension XML — round-trips byte-for-byte. Inside a slide that
+you do edit, only the `<a:p>` children of the targeted `<p:txBody>` are
+rewritten; surrounding `<p:nvSpPr>`, `<p:spPr>`, `<a:bodyPr>`, `<a:lstStyle>`,
+and any unknown OOXML extensions remain in place. The first existing
+`<a:rPr>` (font, size, color, language) is cloned onto each new run, so
+template formatting carries through to the replacement text.
+
+Supported:
+
+- open an existing `.pptx`, enumerate slides in presentation order
+- read every shape's name, concatenated text, and placeholder type
+  (`:ctrTitle`, `:subTitle`, `:body`, ...)
+- walk into paragraphs and runs (`shape.paragraphs`, `shape.runs`,
+  `paragraph.runs`)
+- **bulldozer setter**: `shape.text = "..."` replaces the entire text body,
+  cloning the first existing `<a:rPr>` onto each new run so template
+  formatting carries through
+- **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
+- save back to a new path, or overwrite the original via temp-file + atomic
+  rename — unmodified entries stream through untouched
+
+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
+- editing media (images, embedded fonts) or adding new shapes
+- placeholder-aware API (`slide.title`, `slide.placeholders[:body]`)
+- notes pages, 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
+  `Rbpptx::UnsupportedFormatError` with the conversion hint rather than
+  surfacing an opaque ZIP parse error from rubyzip.
+
+## Install
+
+```bash
+gem install rbpptx
+```
+
+Or in a `Gemfile`:
+
+```ruby
+gem "rbpptx"
+```
+
+Requires Ruby 3.2+, `nokogiri`, and `rubyzip`.
+
+## Usage
+
+### Reading
+
+```ruby
+require "rbpptx"
+
+Rbpptx.open("deck.pptx") do |pres|
+  pres.slides.each do |slide|
+    puts slide.name                        # => "slide1", "slide2", ...
+    slide.shapes.each do |shape|
+      puts "  #{shape.name}: #{shape.text.inspect}"
+    end
+  end
+end
+```
+
+`Rbpptx.open` yields a `Rbpptx::Presentation` and auto-closes the underlying
+ZIP when the block returns (or raises). Without a block it returns the
+presentation; call `pres.close` when done.
+
+Slides are enumerated in the order they appear inside the presentation —
+i.e. the order of `<p:sldId>` entries in `ppt/presentation.xml`, which is
+not necessarily the slide-part filename order.
+
+### Editing text and saving
+
+The bulldozer setter replaces a shape's entire text body. Lines (separated
+by `"\n"`) become individual `<a:p>` paragraphs:
+
+```ruby
+require "rbpptx"
+
+Rbpptx.open("template.pptx") do |pres|
+  pres.slides.first.shapes.first.text = "差し替えタイトル"
+  pres.slides[1].shapes.find { |s| s.text.include?("会社名") }.text = "Acme Inc."
+  pres.save("filled.pptx")
+end
+```
+
+The surgical setter rewrites only the targeted run's `<a:t>`, preserving
+all other formatting and structural XML. Use it for `{{slot}}`-style
+template fills where a marker run sits inside a multi-run paragraph:
+
+```ruby
+Rbpptx.open("template.pptx") do |pres|
+  pres.slides.each do |slide|
+    slide.shapes.flat_map(&:runs).each do |run|
+      run.text = run.text.gsub("{{name}}", "Acme")
+    end
+  end
+  pres.save("filled.pptx")
+end
+```
+
+Or target by placeholder role:
+
+```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."
+  pres.save("filled.pptx")
+end
+```
+
+### Same-path overwrite
+
+`Presentation#save` writes to a temp file in the target directory and
+atomically renames it into place, so `pres.save(original_path)` is safe:
+
+```ruby
+Rbpptx.open("deck.pptx") do |pres|
+  pres.slides.first.shapes.first.text = "Updated"
+  pres.save("deck.pptx")    # overwrite in place
+end
+```
+
+If the rename fails, the temp file is removed before the error propagates.
+
+### Inspecting without parsing every slide
+
+Slide XML is parsed lazily: enumerating slides, reading their `name`, or
+checking `dirty?` does not pay the per-slide parse cost. The first call to
+`slide.shapes` (or `slide.to_xml`) is what triggers the parse, and the
+result is cached.
+
+```ruby
+Rbpptx.open("deck.pptx") do |pres|
+  pres.slides.length                       # cheap
+  pres.slides.map(&:name)                  # cheap
+  pres.slides.first.shapes.first.text      # parses only slide 1
+end
+```
+
+### Error handling
+
+All `rbpptx` exceptions inherit from `Rbpptx::Error` and the messages carry
+the presentation path and (where relevant) the offending part name:
+
+| Error                              | Raised when                                                       |
+| ---                                | ---                                                               |
+| `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::ClosedPresentationError`  | `slides` / `save` called after `close`                            |
+
+```ruby
+begin
+  Rbpptx.open("deck.pptx") { |pres| pres.slides.each { |s| process(s) } }
+rescue Rbpptx::UnsupportedFormatError => e
+  warn "not a pptx: #{e.message}"
+rescue Rbpptx::PresentationFormatError, Rbpptx::SlideFormatError => e
+  warn "malformed: #{e.message}"
+end
+```
+
+## Design Notes
+
+- **Fidelity over feature coverage.** `rbpptx` is a small, surgical editor,
+  not a PowerPoint object model. The bytes it doesn't understand are the
+  bytes it doesn't touch — including PowerPoint-version-specific extensions
+  (`p14:`, `p15:`, `ahyp:`, `mc:AlternateContent`) that a full object model
+  would have to know about to round-trip safely.
+- **Lazy parse, eager write.** Slides parse on first access; saves
+  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.
+- **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`
+  needing to model those properties.
+- **Atomic same-path save.** `save` writes to a sibling temp file and
+  renames it into place, so a crash mid-write cannot leave a half-written
+  `.pptx` at the target path.
+
+## Benchmarks
+
+The selling-point story for `rbpptx` is on real-world decks where the
+package carries embedded media — themes, slide masters, slide layouts,
+images, fonts. `python-pptx` parses these eagerly at `Presentation(path)`
+time; `rbpptx` defers everything past `presentation.xml` and its rels, so
+the open-and-read path stays cheap regardless of how much binary mass the
+deck carries.
+
+Real-world deck (18 MB, 21 slides, embedded fonts and images), 5 iterations:
+
+| benchmark             | rbpptx (s) | python-pptx (s) | docxtemplater (s) | rbpptx vs python-pptx | rbpptx vs docxtemplater |
+| ---                   | ---:       | ---:            | ---:              | ---:                  | ---:                    |
+| read (walk all text)  | **0.019**  | 0.089           | 0.037             | **4.7x faster**       | **2.0x faster**         |
+| fill_one (1 + save)   | **0.033**  | 0.555           | 0.149             | **16.8x faster**      | **4.5x faster**         |
+| fill_many (10 + save) | **0.042**  | 0.545           | 0.144             | **13.0x faster**      | **3.4x faster**         |
+
+Memory (RSS delta) on the read scenario:
+
+| library        | rss Δ (kB) |
+| ---            | ---:       |
+| rbpptx         | **2,956**  |
+| python-pptx    | 28,416     |
+| docxtemplater  | 34,816     |
+
+The fill scenarios used to tie when each library re-deflated every ZIP
+entry on save. `rbpptx` now streams unmodified entries through with
+`Zip::OutputStream#copy_raw_entry`, so the deflate cost is paid only on
+the slide XML that actually changed — which is what unlocks the 13–17x
+gap against python-pptx and the 3–4.5x gap against docxtemplater on
+read-modify-write. The advantage is real and reproducible:
+
+```bash
+cd benchmark && npm install && cd ..
+RBPPTX_SAMPLE=/path/to/your/deck.pptx bundle exec ruby benchmark/compare.rb
+```
+
+`uv` is required for the python-pptx subprocess; the comparison script
+invokes `uv run --with python-pptx python3 benchmark/python_pptx_compare.py`
+so no system-level Python install is mutated. The Node.js side runs from
+`benchmark/node_modules` (gitignored); rerun `npm install` after pulling
+benchmark changes. Use any `.pptx` you have on hand — the table above
+was measured against an 18 MB deck with 21 slides and embedded fonts.
+
+To benchmark against a synthetic deck with no embedded media (isolates the
+XML-rewrite cost from binary deflate), generate a fixture first:
+
+```bash
+uv run --with python-pptx python3 benchmark/fixture_gen.py 50 /tmp/bench_50.pptx
+RBPPTX_SAMPLE=/tmp/bench_50.pptx bundle exec ruby benchmark/compare.rb
+```
+
+## Development
+
+Development in this repository assumes Ruby 3.4.8 (`.ruby-version`).
+
+```bash
+bundle install
+
+# Run tests
+bundle exec ruby -Ilib -Itest test/rbpptx_test.rb
+
+# Generate API docs
+bundle exec rake rdoc
+```
+
+The bulk of the test suite runs against a small in-tree fixture
+(~3 KB) built from scratch by `test/fixture_builder.rb` using only
+`rubyzip` and hand-coded OOXML. No external sample is required for a
+fresh checkout to get meaningful coverage of read, edit, save, and
+fidelity behavior. A handful of dog-fooding tests (`test_sample_*`) opt
+into any real-world `.pptx` you point at via the `RBPPTX_SAMPLE`
+environment variable, and skip cleanly when it is unset:
+
+```bash
+RBPPTX_SAMPLE=/path/to/your/deck.pptx bundle exec ruby -Ilib -Itest test/rbpptx_test.rb
+```

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_helper"
+require "rdoc/task"
+
+Bundler::GemHelper.install_tasks
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
+end

data/lib/rbpptx/errors.rb

@@ -0,0 +1,28 @@
+module Rbpptx
+  # Base class for all errors raised by Rbpptx. Rescue this class to catch any
+  # library-specific failure without catching unrelated +StandardError+
+  # subclasses from the caller's code.
+  class Error < StandardError; end
+
+  # Raised by {Rbpptx.open} when the file is not a valid +.pptx+ container.
+  # Most commonly fires on legacy +.ppt+ (BIFF/CFB) files — the message names
+  # the detected format and suggests a conversion path rather than letting the
+  # underlying ZIP parser surface an opaque error.
+  class UnsupportedFormatError < Error; end
+
+  # Raised when presentation-level XML is malformed or internally inconsistent,
+  # for example when +ppt/presentation.xml+ cannot be parsed or references a
+  # missing relationship target.
+  class PresentationFormatError < Error; end
+
+  # Raised when a slide XML entry cannot be parsed.
+  class SlideFormatError < Error; end
+
+  # Raised by {Rbpptx::Presentation#slide} when the requested slide index is
+  # out of range.
+  class SlideNotFoundError < Error; end
+
+  # Raised when an operation is attempted against a presentation whose
+  # underlying ZIP resources have already been released via +close+.
+  class ClosedPresentationError < Error; end
+end

data/lib/rbpptx/paragraph.rb

@@ -0,0 +1,44 @@
+module Rbpptx
+  # A paragraph (+<a:p>+) inside a shape's text body.
+  #
+  # Paragraphs hold a sequence of {Run}s separated optionally by soft line
+  # breaks (+<a:br>+). The {#text} accessor mirrors {Shape#text} restricted
+  # to this paragraph: runs joined as-is, breaks rendered as +"\n"+. Since
+  # paragraphs map 1:1 to +<a:p>+ elements, paragraph boundaries are *not*
+  # rendered as +"\n"+ here — that is {Shape#text}'s job.
+  class Paragraph
+    A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main".freeze
+
+    # @param node [Nokogiri::XML::Element] the +<a:p>+ element
+    # @param slide [Slide, nil] back-reference propagated to runs so their
+    #   setters can mark the slide dirty
+    def initialize(node:, slide: nil)
+      @node = node
+      @slide = slide
+    end
+
+    # @return [Array<Run>] +<a:r>+ children in document order. +<a:fld>+
+    #   (field) and +<a:br>+ (line break) elements are not included.
+    def runs
+      @node.xpath("./a:r", "a" => A_NS).map { |r| Run.new(node: r, slide: @slide) }
+    end
+
+    # @return [String] concatenated text. Run text appears verbatim; +<a:br>+
+    #   between runs is rendered as +"\n"+.
+    def text
+      buf = +""
+      @node.children.each do |child|
+        next unless child.namespace&.href == A_NS
+
+        case child.name
+        when "r"
+          t = child.at_xpath("./a:t", "a" => A_NS)
+          buf << t.text if t
+        when "br"
+          buf << "\n"
+        end
+      end
+      buf
+    end
+  end
+end

data/lib/rbpptx/presentation.rb

@@ -0,0 +1,187 @@
+module Rbpptx
+  # A PowerPoint presentation loaded from a +.pptx+ file.
+  #
+  # Reading is the only mode wired up at present: the package is opened, the
+  # presentation part is located via +_rels/.rels+, the slide id list is read
+  # in document order, and slides are resolved through the presentation's own
+  # rels. Each {Slide} retains a handle on the underlying ZIP and parses its
+  # XML lazily.
+  class Presentation
+    P_NS = "http://schemas.openxmlformats.org/presentationml/2006/main".freeze
+    A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main".freeze
+    R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships".freeze
+    PKG_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships".freeze
+    OFFICE_DOC_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument".freeze
+    SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide".freeze
+
+    LEGACY_PPT_SIGNATURE = "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b.freeze
+    ZIP_SIGNATURE = "PK\x03\x04".b.freeze
+
+    # @return [String] absolute path the presentation was loaded from
+    attr_reader :path
+
+    # Opens an existing presentation. See {Rbpptx.open} for the public entry
+    # point that supports the block-with-auto-close idiom.
+    def self.open(path)
+      new(path)
+    end
+
+    def initialize(path)
+      @path = path.to_s
+      @closed = false
+      validate_signature!
+      begin
+        @zip = Zip::File.open(@path)
+      rescue Zip::Error => e
+        raise UnsupportedFormatError, "#{@path}: not a valid .pptx (#{e.message})"
+      end
+    end
+
+    # @return [Array<Slide>] slides in presentation order (matches the order of
+    #   +<p:sldId>+ entries inside +ppt/presentation.xml+)
+    def slides
+      ensure_open!
+      @slides ||= build_slides
+    end
+
+    # Writes the presentation out to +path+, preserving every part that has
+    # not been mutated byte-for-byte. Slides whose shapes have been edited are
+    # re-serialized from their in-memory Nokogiri document; all other entries
+    # (themes, masters, layouts, media, fonts, rels) are streamed straight
+    # from the source ZIP without re-parsing, so unknown PowerPoint features
+    # round-trip unchanged.
+    #
+    # +path+ may equal the original load path; the new file is written to a
+    # temp file in the same directory and atomically renamed into place. On
+    # success, dirty flags on each slide are cleared.
+    #
+    # @param path [String, #to_path]
+    # @return [String] the path that was written
+    def save(path)
+      ensure_open!
+      out_path = path.to_s
+      overrides = (@slides || []).each_with_object({}) do |slide, h|
+        h[slide.part_name] = slide.to_xml if slide.dirty?
+      end
+
+      tmp_path = "#{out_path}.rbpptx-tmp.#{Process.pid}.#{rand(1 << 32).to_s(16)}"
+      begin
+        Zip::OutputStream.open(tmp_path) do |out|
+          @zip.each do |entry|
+            next if entry.directory?
+
+            if (override_xml = overrides[entry.name])
+              out.put_next_entry(entry.name)
+              out.write(override_xml)
+            else
+              out.copy_raw_entry(entry)
+            end
+          end
+        end
+        File.rename(tmp_path, out_path)
+      rescue StandardError
+        File.unlink(tmp_path) if File.exist?(tmp_path)
+        raise
+      end
+
+      (@slides || []).each(&:clear_dirty!)
+      out_path
+    end
+
+    # Releases the underlying ZIP file. Idempotent.
+    #
+    # @return [Boolean] +true+ on the first call, +false+ on subsequent calls
+    def close
+      return false if @closed
+
+      @zip&.close
+      @zip = nil
+      @closed = true
+      true
+    end
+
+    # @return [Boolean]
+    def closed?
+      @closed
+    end
+
+    private
+
+    def ensure_open!
+      raise ClosedPresentationError, "#{@path}: presentation is closed" if @closed
+    end
+
+    def validate_signature!
+      head = File.binread(@path, 8) rescue nil
+      raise UnsupportedFormatError, "#{@path}: file is empty or unreadable" if head.nil? || head.empty?
+
+      if head.start_with?(LEGACY_PPT_SIGNATURE)
+        raise UnsupportedFormatError,
+              "#{@path}: looks like a legacy .ppt (BIFF/CFB) file. " \
+              "Convert to .pptx first, e.g. `libreoffice --headless --convert-to pptx`."
+      end
+
+      unless head.start_with?(ZIP_SIGNATURE)
+        raise UnsupportedFormatError, "#{@path}: missing ZIP signature; not a .pptx package"
+      end
+    end
+
+    def build_slides
+      pres_part = locate_presentation_part
+      pres_rels = parse_rels(rels_path_for(pres_part))
+      pres_dir = File.dirname(pres_part)
+
+      doc = parse_xml(pres_part)
+      sld_ids = doc.xpath("/p:presentation/p:sldIdLst/p:sldId", "p" => P_NS)
+
+      sld_ids.map do |sld_id|
+        rid = sld_id.attribute_with_ns("id", R_NS)&.value
+        target = pres_rels[rid] or raise PresentationFormatError, "#{@path}: rId #{rid.inspect} not found in presentation rels"
+        Slide.new(zip: @zip, part_name: resolve_relative(pres_dir, target))
+      end
+    end
+
+    def locate_presentation_part
+      doc = parse_xml("_rels/.rels")
+      rel = doc.at_xpath(
+        "/pkg:Relationships/pkg:Relationship[@Type=$type]",
+        { "pkg" => PKG_REL_NS },
+        { "type" => OFFICE_DOC_REL_TYPE }
+      )
+      raise PresentationFormatError, "#{@path}: officeDocument relationship missing from _rels/.rels" unless rel
+
+      target = rel["Target"] or raise PresentationFormatError, "#{@path}: officeDocument relationship has no Target"
+      target.sub(%r{\A/}, "")
+    end
+
+    def parse_rels(rels_part)
+      entry = @zip.find_entry(rels_part)
+      return {} unless entry
+
+      doc = Nokogiri::XML(entry.get_input_stream.read)
+      doc.xpath("/pkg:Relationships/pkg:Relationship", "pkg" => PKG_REL_NS).each_with_object({}) do |r, h|
+        h[r["Id"]] = r["Target"]
+      end
+    end
+
+    def parse_xml(part_name)
+      entry = @zip.find_entry(part_name) or raise PresentationFormatError, "#{@path}: missing part #{part_name}"
+      doc = Nokogiri::XML(entry.get_input_stream.read)
+      raise PresentationFormatError, "#{@path}: #{part_name}: #{doc.errors.first}" unless doc.errors.empty?
+
+      doc
+    end
+
+    def rels_path_for(part_name)
+      dir = File.dirname(part_name)
+      base = File.basename(part_name)
+      dir == "." ? "_rels/#{base}.rels" : "#{dir}/_rels/#{base}.rels"
+    end
+
+    def resolve_relative(base_dir, target)
+      return target.sub(%r{\A/}, "") if target.start_with?("/")
+
+      File.expand_path(target, "/#{base_dir}").sub(%r{\A/}, "")
+    end
+  end
+end

data/lib/rbpptx/run.rb

@@ -0,0 +1,47 @@
+require "cgi"
+
+module Rbpptx
+  # A single run (+<a:r>+) inside a paragraph.
+  #
+  # Runs are the smallest unit of text that shares a single set of run
+  # properties (+<a:rPr>+: font, size, color, language, hyperlink, ...). The
+  # text setter replaces only the content of the run's +<a:t>+ element, so
+  # every other property of the run survives the edit untouched — the
+  # surgical counterpart to the bulldozer-style {Shape#text=} setter.
+  class Run
+    A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main".freeze
+
+    # @param node [Nokogiri::XML::Element] the +<a:r>+ element
+    # @param slide [Slide, nil] back-reference used to mark the slide dirty
+    #   when this run is mutated
+    def initialize(node:, slide: nil)
+      @node = node
+      @slide = slide
+    end
+
+    # @return [String] the run's text content (the inner text of +<a:t>+),
+    #   or +""+ if the run has no +<a:t>+ element
+    def text
+      t = @node.at_xpath("./a:t", "a" => A_NS)
+      t ? t.text : ""
+    end
+
+    # Replaces the run's text content. Only the +<a:t>+ element's character
+    # data is rewritten; +<a:rPr>+ and any other children of the run are left
+    # in place. If the run has no +<a:t>+ element, one is appended.
+    #
+    # @param new_text [String]
+    # @return [String]
+    def text=(new_text)
+      value = new_text.to_s
+      t = @node.at_xpath("./a:t", "a" => A_NS)
+      if t
+        t.content = value
+      else
+        @node.add_child("<a:t>#{CGI.escapeHTML(value)}</a:t>")
+      end
+      @slide&.mark_dirty!
+      value
+    end
+  end
+end

data/lib/rbpptx/shape.rb

@@ -0,0 +1,127 @@
+require "cgi"
+
+module Rbpptx
+  # A single shape (+<p:sp>+) on a slide.
+  #
+  # Two layers of text access are exposed:
+  #
+  # * {#text} / {#text=} — bulldozer-level: read the entire concatenated
+  #   text body, or replace it wholesale. The setter cleans the text body's
+  #   +<a:p>+ children and rebuilds them, cloning the first existing
+  #   +<a:rPr>+ onto each new run so template formatting carries through.
+  # * {#paragraphs} / {#runs} — surgical: walk into individual {Paragraph}
+  #   and {Run} wrappers and mutate run text via {Run#text=}, which only
+  #   rewrites +<a:t>+ content. Run properties, hyperlinks, soft line
+  #   breaks, paragraph properties, and any unknown OOXML extensions on the
+  #   shape are preserved.
+  #
+  # In addition, {#placeholder_type} reads the shape's placeholder role from
+  # +<p:nvSpPr>/<p:nvPr>/<p:ph type="...">+ so callers can target shapes by
+  # semantic role (e.g. +:ctrTitle+, +:subTitle+, +:body+) instead of by
+  # index.
+  class Shape
+    P_NS = "http://schemas.openxmlformats.org/presentationml/2006/main".freeze
+    A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main".freeze
+
+    # @param node [Nokogiri::XML::Element] the +<p:sp>+ element
+    # @param slide [Slide, nil] back-reference used to mark the slide dirty
+    #   when this shape is mutated
+    def initialize(node:, slide: nil)
+      @node = node
+      @slide = slide
+    end
+
+    # @return [String, nil] value of +<p:cNvPr name="...">+, the human-readable
+    #   shape name set by the authoring tool
+    def name
+      @node.at_xpath("./p:nvSpPr/p:cNvPr/@name", "p" => P_NS)&.value
+    end
+
+    # @return [Symbol, nil] the placeholder type as a Symbol (e.g.
+    #   +:ctrTitle+, +:subTitle+, +:title+, +:body+, +:obj+, +:ftr+,
+    #   +:dt+, +:sldNum+, +:pic+), or +nil+ if the shape is not a
+    #   placeholder. Returns +:body+ when the shape has a +<p:ph>+ element
+    #   with no +type+ attribute, matching the OOXML default.
+    def placeholder_type
+      ph = @node.at_xpath("./p:nvSpPr/p:nvPr/p:ph", "p" => P_NS)
+      return nil unless ph
+
+      type = ph["type"]
+      type ? type.to_sym : :body
+    end
+
+    # @return [Array<Paragraph>] paragraphs in the shape's text body, in
+    #   document order. Returns +[]+ if the shape has no +<p:txBody>+ (e.g.
+    #   picture or group shapes).
+    def paragraphs
+      txbody = @node.at_xpath("./p:txBody", "p" => P_NS)
+      return [] unless txbody
+
+      txbody.xpath("./a:p", "a" => A_NS).map { |p| Paragraph.new(node: p, slide: @slide) }
+    end
+
+    # @return [Array<Run>] all runs in the shape's text body, flattened
+    #   across paragraphs in document order
+    def runs
+      paragraphs.flat_map(&:runs)
+    end
+
+    # Concatenated text of the shape's text body. Paragraphs are joined with
+    # +"\n"+; soft line breaks (+<a:br>+) inside a paragraph are also
+    # rendered as +"\n"+.
+    #
+    # @return [String]
+    def text
+      paragraphs.map(&:text).join("\n")
+    end
+
+    # Replaces the shape's text body. Lines (separated by +"\n"+) become
+    # individual +<a:p>+ paragraphs. Run properties from the first existing
+    # +<a:rPr>+ (font, size, color, language) are cloned onto each new run
+    # so template formatting carries through.
+    #
+    # This is the bulldozer-level setter; for edits that need to preserve
+    # individual run formatting (e.g. replacing a placeholder inside a
+    # multi-run paragraph), use {#runs} or {#paragraphs} and {Run#text=}
+    # instead.
+    #
+    # Shapes without a +<p:txBody>+ (e.g. picture or group shapes) cannot
+    # accept text and will raise.
+    #
+    # @param new_text [String]
+    # @return [String] the value that was set
+    # @raise [Rbpptx::Error] if the shape has no text body
+    def text=(new_text)
+      txbody = @node.at_xpath("./p:txBody", "p" => P_NS)
+      raise Error, "shape has no <p:txBody>; cannot set text" unless txbody
+
+      template_rpr = txbody.at_xpath(".//a:r/a:rPr", "a" => A_NS)
+      txbody.xpath("./a:p", "a" => A_NS).each(&:remove)
+
+      lines = new_text.to_s.empty? ? [""] : new_text.to_s.split("\n", -1)
+      txbody.add_child(build_paragraphs_xml(lines))
+
+      if template_rpr
+        txbody.xpath("./a:p/a:r", "a" => A_NS).each do |run|
+          first_child = run.children.first
+          first_child ? first_child.add_previous_sibling(template_rpr.dup) : run.add_child(template_rpr.dup)
+        end
+      end
+
+      @slide&.mark_dirty!
+      new_text
+    end
+
+    private
+
+    def build_paragraphs_xml(lines)
+      lines.map do |line|
+        if line.empty?
+          "<a:p/>"
+        else
+          "<a:p><a:r><a:t>#{CGI.escapeHTML(line)}</a:t></a:r></a:p>"
+        end
+      end.join
+    end
+  end
+end

data/lib/rbpptx/slide.rb

@@ -0,0 +1,78 @@
+module Rbpptx
+  # A single slide loaded from a presentation's ZIP container.
+  #
+  # Parsing of the slide's XML payload is deferred until {#shapes} is first
+  # called and then cached, so simply enumerating slides via
+  # {Presentation#slides} does not pay the per-slide parse cost.
+  class Slide
+    P_NS = "http://schemas.openxmlformats.org/presentationml/2006/main".freeze
+
+    # @return [String] the part name of the slide inside the package, e.g.
+    #   +"ppt/slides/slide1.xml"+
+    attr_reader :part_name
+
+    # @param zip [Zip::File] the open package
+    # @param part_name [String] absolute part name (no leading slash)
+    def initialize(zip:, part_name:)
+      @zip = zip
+      @part_name = part_name
+      @dirty = false
+    end
+
+    # @return [String] the slide's basename without extension, e.g. +"slide1"+
+    def name
+      File.basename(@part_name, ".xml")
+    end
+
+    # @return [Array<Shape>] +<p:sp>+ children of the slide's shape tree, in
+    #   document order
+    def shapes
+      @shapes ||= build_shapes
+    end
+
+    # @return [Boolean] whether any shape on this slide has been mutated since
+    #   load
+    def dirty?
+      @dirty
+    end
+
+    # Marks the slide as dirty. Called by {Shape} setters; not part of the
+    # public API.
+    #
+    # @api private
+    def mark_dirty!
+      @dirty = true
+    end
+
+    # @return [String] the slide's XML, reflecting any in-memory mutations.
+    #   The XML declaration is preserved.
+    def to_xml
+      doc.to_xml
+    end
+
+    # @api private
+    def clear_dirty!
+      @dirty = false
+    end
+
+    private
+
+    def doc
+      @doc ||= parse_doc
+    end
+
+    def parse_doc
+      entry = @zip.find_entry(@part_name)
+      raise SlideFormatError, "missing slide part #{@part_name}" unless entry
+
+      parsed = Nokogiri::XML(entry.get_input_stream.read)
+      raise SlideFormatError, "#{@part_name}: #{parsed.errors.first}" unless parsed.errors.empty?
+
+      parsed
+    end
+
+    def build_shapes
+      doc.xpath("/p:sld/p:cSld/p:spTree/p:sp", "p" => P_NS).map { |sp| Shape.new(node: sp, slide: self) }
+    end
+  end
+end

data/lib/rbpptx/version.rb

@@ -0,0 +1,4 @@
+module Rbpptx
+  # Gem version string, tracked with semantic versioning.
+  VERSION = "0.1.0"
+end

data/lib/rbpptx.rb

@@ -0,0 +1,60 @@
+require "nokogiri"
+require "zip"
+
+require_relative "rbpptx/errors"
+require_relative "rbpptx/run"
+require_relative "rbpptx/paragraph"
+require_relative "rbpptx/shape"
+require_relative "rbpptx/slide"
+require_relative "rbpptx/presentation"
+require_relative "rbpptx/version"
+
+# PowerPoint (+.pptx+) reader/writer for Ruby, modeled after +python-pptx+.
+#
+# Rbpptx exposes a single, unified +Presentation+ object that can be loaded
+# from disk, mutated in memory, and written back out:
+#
+#   require "rbpptx"
+#
+#   pres = Rbpptx.open("deck.pptx")
+#   pres.slides.each { |slide| puts slide.shapes.map(&:text).join(" / ") }
+#   pres.close
+#
+# Block form auto-closes the underlying ZIP:
+#
+#   Rbpptx.open("deck.pptx") do |pres|
+#     pres.slides.first.shapes.each { |s| puts s.text }
+#   end
+module Rbpptx
+  class << self
+    # Opens an existing +.pptx+ presentation.
+    #
+    # When a block is given, the presentation is yielded and automatically
+    # closed when the block returns (or raises), mirroring the +File.open+ and
+    # +Zip::File.open+ idiom.
+    #
+    # @param path [String, #to_path] filesystem path to a +.pptx+ file
+    # @yieldparam pres [Rbpptx::Presentation] opened presentation; auto-closed
+    #   when the block returns
+    # @return [Rbpptx::Presentation, Object] the presentation when no block is
+    #   given, otherwise the block's return value
+    def open(path)
+      pres = Presentation.open(path)
+      return pres unless block_given?
+
+      begin
+        yield pres
+      ensure
+        pres.close
+      end
+    end
+
+    # Creates a new empty presentation. Not yet implemented; tracked for
+    # future write-from-scratch support.
+    #
+    # @return [Rbpptx::Presentation]
+    def new
+      raise NotImplementedError, "Rbpptx.new (blank presentation creation) is not implemented yet"
+    end
+  end
+end

data/sig/rbpptx.rbs

@@ -0,0 +1,88 @@
+module Rbpptx
+  VERSION: String
+
+  type pathish = String | Pathname
+
+  def self.open: (pathish path) -> Presentation
+               | [T] (pathish path) { (Presentation) -> T } -> T
+  def self.new: () -> Presentation
+
+  class Error < StandardError
+  end
+
+  class UnsupportedFormatError < Error
+  end
+
+  class PresentationFormatError < Error
+  end
+
+  class SlideFormatError < Error
+  end
+
+  class SlideNotFoundError < Error
+  end
+
+  class ClosedPresentationError < Error
+  end
+
+  class Presentation
+    P_NS: String
+    A_NS: String
+    R_NS: String
+    PKG_REL_NS: String
+    OFFICE_DOC_REL_TYPE: String
+    SLIDE_REL_TYPE: String
+
+    attr_reader path: String
+
+    def self.open: (pathish path) -> Presentation
+    def initialize: (pathish path) -> void
+    def slides: () -> Array[Slide]
+    def save: (pathish path) -> String
+    def close: () -> bool
+    def closed?: () -> bool
+  end
+
+  class Slide
+    P_NS: String
+
+    attr_reader part_name: String
+
+    def initialize: (zip: untyped, part_name: String) -> void
+    def name: () -> String
+    def shapes: () -> Array[Shape]
+    def dirty?: () -> bool
+    def mark_dirty!: () -> bool
+    def clear_dirty!: () -> bool
+    def to_xml: () -> String
+  end
+
+  class Shape
+    P_NS: String
+    A_NS: String
+
+    def initialize: (node: untyped, ?slide: Slide?) -> void
+    def name: () -> String?
+    def placeholder_type: () -> Symbol?
+    def paragraphs: () -> Array[Paragraph]
+    def runs: () -> Array[Run]
+    def text: () -> String
+    def text=: (String new_text) -> String
+  end
+
+  class Paragraph
+    A_NS: String
+
+    def initialize: (node: untyped, ?slide: Slide?) -> void
+    def runs: () -> Array[Run]
+    def text: () -> String
+  end
+
+  class Run
+    A_NS: String
+
+    def initialize: (node: untyped, ?slide: Slide?) -> void
+    def text: () -> String
+    def text=: (String new_text) -> String
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: rbpptx
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Taro KOBAYASHI
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: rbpptx is a Ruby gem for reading and writing PowerPoint .pptx files,
+  modeled after python-pptx.
+email:
+- taro@matzlika.co.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/rbpptx.rb
+- lib/rbpptx/errors.rb
+- lib/rbpptx/paragraph.rb
+- lib/rbpptx/presentation.rb
+- lib/rbpptx/run.rb
+- lib/rbpptx/shape.rb
+- lib/rbpptx/slide.rb
+- lib/rbpptx/version.rb
+- sig/rbpptx.rbs
+homepage: https://github.com/matzlika/rbpptx
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/matzlika/rbpptx
+  bug_tracker_uri: https://github.com/matzlika/rbpptx/issues
+  changelog_uri: https://github.com/matzlika/rbpptx/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: PowerPoint (PPTX) processing for Ruby.
+test_files: []