ruby_pptx 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6cd5ac8827fcd5b81d86a1b0a0faa9f619f776dd005580589bbe88fd3f666d4a
+  data.tar.gz: 6dafdf4a15d53bb8d4a795d3e2c0a18beebab2bd35070076d69e2a7cddddd29f
+SHA512:
+  metadata.gz: b54ec7a6115da3d4da42ee124faefb0fee0e51d200525af1c05527fe9a6c579d279ca7da59293ce71b81a56a03c4e1567b228cb86caa234e28f1b0faf44bd9ef
+  data.tar.gz: 2d991bf2f20c571783f5d1243d586b9e0aa9b4f2db655872c1b60a71ada29495b5e91ab587674e82fa98d34a8cb552e51f5c6fc20b76afa680691cf84bbccce8

data/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to this gem are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Before 1.0 a minor
+version may change the public API.
+
+## [0.1.0] - 2026-09-28
+
+The first release: a Ruby port of [python-pptx](https://github.com/scanny/python-pptx)
+1.0.2, covering its whole public API, with an API redesigned for Ruby over an
+object model kept close to the original.
+
+### Added
+
+**Everything python-pptx does.** Every public class and member of python-pptx
+1.0.2 has a counterpart; `spec/ruby_pptx/api_completeness_spec.rb` checks this
+against python-pptx itself and fails if a gap appears.
+
+- Presentations: open, create from the default template, save; slide size;
+  core properties.
+- Slides, layouts and masters: add slides; find layouts by name and delete
+  unused ones; backgrounds; speaker notes (`slide.notes = "…"`) and the notes
+  master.
+- Shapes: auto shapes with adjustment handles, text boxes, pictures, movies,
+  connectors attached to shapes, groups, freeforms, tables with merged cells,
+  and OLE objects shown as icons.
+- Placeholders, with geometry inherited from layout and master, and
+  `insert_picture` (cropped to fit), `insert_table` and `insert_chart`.
+- Text: paragraphs, runs, fonts, alignment, spacing, autofit, hyperlinks and
+  click actions, and `fit_text` to shrink text into its shape.
+- Formatting: solid, patterned, gradient and background fills; line width,
+  colour and dash style; shadows; theme and RGB colours with brightness.
+- Pictures: PNG, JPEG, GIF, BMP, TIFF, WMF and EMF, read without Pillow;
+  cropping; masking with a shape; reading the embedded image back.
+- Charts: bar, column, line, pie, doughnut, area, radar, XY and bubble, in
+  every python-pptx variant; grouped and date categories; replacing a chart's
+  data; titles, legends, axes, tick marks and labels, gridlines, data labels
+  per plot, series and point; markers; fonts; chart style; the exact chart
+  type read back from an existing chart. The embedded workbook is written
+  without XlsxWriter.
+
+**Beyond python-pptx.**
+
+- Slide sections.
+- Paging a long table across as many slides as it needs.
+- Combo charts, with a secondary axis.
+- SVG pictures, with a raster fallback for older viewers.
+- Defining a slide master, its theme and its layouts in code.
+- `Pptx.build`, a declarative way to write a whole deck.
+
+**A Ruby API.**
+
+- Keyword arguments for position and size (`at:`, `size:`), which also accept
+  `Pptx::Point` and `Pptx::Size` value objects with arithmetic.
+- Explicit lengths (`Pptx.inches(1)`, `Pptx.pt(18)`), and `1.inch` through
+  either the `Pptx::Lengths` refinement or the opt-in `ruby_pptx/core_ext`.
+- Enumerable collections that index like arrays, ranges included.
+- `case`/`in` pattern matching on shapes, slides, text, charts, lengths and
+  colours.
+- Predicates (`chart.legend?`, `frame.chart?`) and nil for "inherited" or
+  "absent" throughout; reading a property never changes the document.
+
+### Differences from python-pptx
+
+Output matches python-pptx part for part, except where python-pptx is wrong
+or where matching it cannot be done. Each case is listed, with its reason, in
+[PORTING.md](PORTING.md):
+
+- `fit_text` measures glyph outlines rather than rasterizing with Pillow, so
+  it can choose a size one point different on text that only just fits. It
+  also takes a `font_file:` rather than searching for one, since python-pptx's
+  search works only on macOS and Windows.
+- The chart's embedded workbook is written directly; its contents match, its
+  bytes do not.
+- python-pptx bugs this does not reproduce: `fit_text` raising `TypeError` on a
+  word wider than the shape; reading the angle of a fresh gradient raising
+  `TypeError`; an empty category label reading as `"None"`; an axis with no
+  delete setting reading as hidden; EMF images stored as WMF.
+- Getters that write to the document in python-pptx -- data-label flags, axis
+  and chart titles -- do not here.
+
+[0.1.0]: https://github.com/Largo/ruby_pptx/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andi
+
+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/NOTICE

@@ -0,0 +1,48 @@
+# Third-party notices
+
+## python-pptx
+
+This gem is a port of python-pptx (https://github.com/scanny/python-pptx).
+Much of its structure, and the behaviour it reproduces, derives directly from
+that project. The following files are copied from it verbatim:
+
+    lib/ruby_pptx/templates/default.pptx
+    lib/ruby_pptx/templates/notes.xml
+    lib/ruby_pptx/templates/notesMaster.xml
+    lib/ruby_pptx/templates/theme.xml
+    lib/ruby_pptx/templates/media-speaker.png
+    lib/ruby_pptx/templates/docx-icon.emf
+    lib/ruby_pptx/templates/pptx-icon.emf
+    lib/ruby_pptx/templates/xlsx-icon.emf
+    lib/ruby_pptx/templates/generic-icon.emf
+
+The following file is derived from python-pptx's default template: its colour
+map and text styles are taken verbatim from the slide master inside
+`default.pptx`, with the shape tree emptied and the layout list cleared, so
+that a master created by this gem starts from the same defaults PowerPoint
+itself would use:
+
+    lib/ruby_pptx/templates/slideMaster.xml
+
+python-pptx is distributed under the MIT License, reproduced in full below.
+
+The MIT License (MIT)
+Copyright (c) 2013 Steve Canny, https://github.com/scanny
+
+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,272 @@
+# ruby_pptx
+
+Create, read and update PowerPoint (`.pptx`) files from Ruby.
+
+A port of [python-pptx](https://github.com/scanny/python-pptx) — the same
+battle-tested OOXML object model underneath, with a public API redesigned for
+Ruby. See [PORTING.md](PORTING.md) for the architecture and the milestone plan.
+
+> **Status:** every public class and member of python-pptx 1.0.2 has a
+> counterpart here, which `spec/ruby_pptx/api_completeness_spec.rb` checks
+> rather than asserts. Output is verified against python-pptx part for part.
+> Where the two deliberately differ -- mostly python-pptx bugs this does not
+> reproduce -- [PORTING.md](PORTING.md) lists each one.
+
+```ruby
+require "ruby_pptx"
+
+prs = Pptx::Presentation.new_default          # or .open("deck.pptx")
+slide = prs.slides.add(prs.slide_layouts["Title and Content"])
+
+slide.shapes.title.text = "Quarterly Review"
+
+body = slide.placeholders[1].text_frame
+body.text = "Revenue up 12%\nCosts flat"
+body.paragraphs.first.runs.first.font.tap do |font|
+  font.bold = true
+  font.size = Pptx.pt(24)
+  font.color.rgb = Pptx::RGBColor["C0504D"]
+end
+
+box = slide.shapes.add_shape(:rounded_rectangle,
+                             at: [Pptx.inches(1), Pptx.inches(5)],
+                             size: [Pptx.inches(3), Pptx.inches(1)])
+box.fill.solid
+box.fill.fore_color.rgb = Pptx::RGBColor["1F497D"]
+box.text_frame.text = "Next steps"
+
+slide.shapes.add_picture("logo.png", at: [Pptx.inches(7), Pptx.inches(0.5)],
+                         width: Pptx.inches(2))
+
+table_frame = slide.shapes.add_table(2, 3, at: [Pptx.inches(1), Pptx.inches(3)],
+                                     size: [Pptx.inches(8), Pptx.inches(2)])
+table_frame.table[0, 0].text = "Region"
+
+data = Pptx::ChartData.new
+data.categories = ["East", "West", "Midwest"]
+data.add_series("Q1", [1.2, 2.0, 3.5])
+slide.shapes.add_chart(:column_clustered, data,
+                       at: [Pptx.inches(1), Pptx.inches(3)],
+                       size: [Pptx.inches(8), Pptx.inches(4)])
+
+# Scatter and bubble charts take points rather than a value per category.
+xy = Pptx::XyChartData.new
+xy.add_series("Alpha", points: [[1, 10], [2, 20]])
+
+box.hyperlink = "https://example.com"
+
+# Connectors attach to shapes, and groups size themselves around their contents.
+line = slide.shapes.add_connector(:straight, begin_at: [0, 0], end_at: [0, 0])
+line.begin_connect(box, 3)
+group = slide.shapes.add_group_shape([box, table_frame])
+
+slide.shapes.add_movie("clip.mp4", at: [x, y], size: [w, h], content_type: "video/mp4")
+
+prs.save("out.pptx")
+```
+
+Or build a whole deck declaratively:
+
+```ruby
+deck = Pptx.build do |d|
+  d.slide_size = :widescreen
+
+  d.slide("Title Slide") do |s|
+    s.title = "Annual Report"
+    s.subtitle = "Prepared in Ruby"
+  end
+
+  d.section("Detail") do
+    d.slide("Blank") do |s|
+      s.shape :rounded_rectangle, at: [Pptx.inches(1), Pptx.inches(1)],
+                                  size: [Pptx.inches(3), Pptx.inches(1)],
+                                  fill: "1F497D", text: "Next steps"
+      s.chart :column_clustered, categories: %w[East West],
+                                 series: { "Q1" => [1, 2] },
+                                 at: [Pptx.inches(1), Pptx.inches(3)],
+                                 size: [Pptx.inches(6), Pptx.inches(4)]
+    end
+  end
+end
+
+deck.save("out.pptx")
+```
+
+Five things python-pptx does not do: **SVG pictures**, **slide sections**,
+**paging a long table across as many slides as it needs**, **combo charts**
+with a secondary axis, and **defining a slide master in code**.
+
+```ruby
+data = Pptx::ChartData.new
+data.categories = %w[Q1 Q2 Q3]
+data.add_series("Revenue", [120, 135, 150])
+data.add_series("Margin", [0.21, 0.24, 0.22])
+
+slide.shapes.add_combo_chart(data, at: [x, y], size: [w, h]) do |combo|
+  combo.plot :column_clustered, series: "Revenue"
+  combo.plot :line, series: "Margin", secondary_axis: true
+end
+```
+
+```ruby
+# PowerPoint wants a raster stand-in beside the vector, and this gem has no
+# rasterizer, so you supply it.
+slide.shapes.add_picture("logo.svg", at: [x, y], fallback: "logo.png")
+```
+
+Text can be shrunk to fit the shape holding it. Measuring needs the actual
+glyph outlines, so you pass the font file; `font_family` is what gets written
+into the deck.
+
+```ruby
+box.text_frame.fit_text(font_file: "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+                        font_family: "DejaVu Sans",
+                        max_size: 28)
+#=> 28   (the point size applied, never above max_size)
+```
+
+That turns word wrap on, autofit off, and applies the size to every run. Sizes
+are measured from the font's own metrics rather than by rendering, so they can
+differ from python-pptx's by a point on text that only just fits; PORTING.md
+has the measured comparison.
+
+A slide master can be built from scratch, rather than only edited in a
+template. The master gets its own theme, so its colours and fonts are
+independent of any other master in the deck.
+
+```ruby
+master = deck.slide_masters.add(name: "Corporate")
+master.theme.colors.update(accent1: "1F497D", accent2: "C0504D")
+master.theme.fonts.major = "Georgia"
+master.theme.fonts.minor = "Verdana"
+
+layout = master.slide_layouts.add("Title and Content", type: "obj") do |l|
+  l.placeholders.add(:title, at: [Pptx.inches(0.5), Pptx.inches(0.3)],
+                             size: [Pptx.inches(9), Pptx.inches(1.25)])
+  l.placeholders.add(:body, idx: 1, at: [Pptx.inches(0.5), Pptx.inches(1.75)],
+                                    size: [Pptx.inches(9), Pptx.inches(4.5)])
+end
+
+slide = deck.slides.add(layout)
+slide.shapes.title.text = "Built from a hand-made master"
+```
+
+The master starts with the five placeholders PowerPoint expects — title, body,
+date, footer and slide number — scaled to the deck's slide size. Pass
+`placeholders: :none` for a bare one.
+
+```ruby
+deck.sections.add("Appendix", slides: deck.slides.to_a.last(2))
+
+deck.slides.add_table_pages(rows,
+                            layout: deck.slide_layouts["Blank"],
+                            left: Pptx.inches(0.5), top: Pptx.inches(1),
+                            width: Pptx.inches(9), height: Pptx.inches(5))
+```
+
+Lengths are explicit rather than bare numbers:
+
+```ruby
+Pptx.inches(1).emu        #=> 914400
+Pptx.cm(2.54).pt          #=> 72.0
+```
+
+Numeric sugar is opt-in, and comes two ways. Prefer the refinement: it is
+scoped to the file that asks for it, so it cannot surprise anything else
+sharing the process.
+
+```ruby
+require "ruby_pptx/refinements"
+using Pptx::Lengths               # this file only
+1.inch == 72.points               #=> true
+
+require "ruby_pptx/core_ext"      # or patch Numeric process-wide
+```
+
+`at:` and `size:` have always taken a two-element array, and still do. Passing
+a `Point` or a `Size` instead costs nothing and buys named readers, arithmetic
+and pattern matching:
+
+```ruby
+origin = Pptx.point(Pptx.inches(1), Pptx.inches(1))
+box    = Pptx.size(Pptx.inches(3), Pptx.inches(1))
+
+slide.shapes.add_shape(:rectangle, at: origin, size: box)
+slide.shapes.add_shape(:rectangle, at: origin + [0, Pptx.inches(1.5)], size: box * 2)
+```
+
+Reading a deck back supports `case`/`in`. Enum-valued attributes read as their
+symbolic name in a pattern, and only the keys a pattern asks for are computed:
+
+```ruby
+slide.shapes.each do |shape|
+  case shape
+  in {shape_type: :PICTURE, name:}                      then puts "picture #{name}"
+  in {shape_type: :PLACEHOLDER, placeholder_format: {type: :TITLE}}
+                                                        then puts shape.text_frame.text
+  in {width:} if width > Pptx.inches(5)                 then puts "#{shape.name} is wide"
+  else next
+  end
+end
+```
+
+Collections index like arrays — `slides[2]`, `slides[-1]`, `slides[1..3]`,
+`slides[1, 2]` — and deconstruct into array patterns.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+`.rubocop.yml` records where this codebase deliberately departs from the
+default style — chiefly that the `oxml` layer keeps the OOXML schema's own
+names (`CT_Shape`, `#cSld`, `accent1`) so the XML, the specification and the
+Ruby read side by side.
+
+Specs compare the packages this gem writes against the ones python-pptx writes
+for the same operation, part by part, on canonicalised XML. To run those:
+
+```bash
+pip install -r spec/oracle-requirements.txt
+```
+
+Without it, the oracle-backed specs skip and the rest still run. CI sets
+`REQUIRE_ORACLE=1`, which turns those skips into failures so a broken Python
+environment cannot quietly reduce the suite to its unit tests. The same goes
+for the `fit_text` specs, which measure with fonts from Debian's
+`fonts-dejavu-core` and `fonts-urw-base35` packages.
+
+A slide master has no oracle — python-pptx can read one but not create one —
+so it is validated against the published ISO/IEC 29500-4 schemas instead.
+Those are not redistributed here; point `OOXML_SCHEMAS` at a directory holding
+`pml.xsd`, `dml-main.xsd` and the `shared-*.xsd` files they import:
+
+```bash
+OOXML_SCHEMAS=/path/to/schemas bundle exec rspec
+```
+
+### Releasing
+
+Bump `Pptx::VERSION`, add its `CHANGELOG.md` entry, then push a matching tag:
+
+```bash
+git tag -a v0.1.0 -m "ruby_pptx 0.1.0" && git push origin v0.1.0
+```
+
+`.github/workflows/release.yml` runs the full CI suite, builds the gem, installs
+it into an empty gem home to prove it loads, and creates a GitHub release with
+the gem attached and the changelog entry as its notes. It pushes to RubyGems
+only once a `RUBYGEMS_API_KEY` secret is set.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+This gem is a port of [python-pptx](https://github.com/scanny/python-pptx) by
+Steve Canny, which is also MIT licensed, and it vendors nine template files
+(the default deck, notes and theme templates, the video poster frame and the
+OLE object icons) from that project verbatim, plus one derived from them. See
+[NOTICE](NOTICE) for the full attribution and the upstream licence text.

data/lib/ruby_pptx/action.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/oxml/action"
+require "ruby_pptx/enum/action"
+
+module Pptx
+  # What happens when a shape or run is clicked.
+  #
+  # Most callers want {Pptx::BaseShape#hyperlink}, which is a shortcut to this
+  # object's URL. Reach for `click_action` when the click does something other
+  # than open a link -- jumping to a slide, for instance.
+  class ActionSetting
+    # `ppaction://hlinkshowjump?jump=...` covers the relative moves.
+    RELATIVE_JUMPS = {
+      "firstslide" => :FIRST_SLIDE, "lastslide" => :LAST_SLIDE,
+      "lastslideviewed" => :LAST_SLIDE_VIEWED, "nextslide" => :NEXT_SLIDE,
+      "previousslide" => :PREVIOUS_SLIDE, "endshow" => :END_SHOW
+    }.freeze
+
+    # Every other action is identified by the host of its `ppaction://` URL.
+    # A hyperlink has no action attribute at all.
+    ACTION_VERBS = {
+      nil => :HYPERLINK, "hlinksldjump" => :NAMED_SLIDE, "hlinkpres" => :PLAY,
+      "hlinkfile" => :OPEN_FILE, "customshow" => :NAMED_SLIDE_SHOW,
+      "ole" => :OLE_VERB, "macro" => :RUN_MACRO, "program" => :RUN_PROGRAM
+    }.freeze
+
+    # @param x_pr [Pptx::Oxml::Element] a `p:cNvPr` or an `a:rPr`
+    # @param parent the shape or run this action belongs to
+    def initialize(x_pr, parent, hover: false)
+      @element = x_pr
+      @parent = parent
+      @hover = hover
+    end
+
+    def part = @parent.part
+
+    # @return [Pptx::Enum::PP_ACTION] NONE when nothing happens on click
+    def action
+      link = hlink
+      return Enum::PP_ACTION::NONE if link.nil?
+
+      verb = link.action_verb
+      if verb == "hlinkshowjump"
+        name = RELATIVE_JUMPS[link.action_fields["jump"]]
+        return name ? Enum::PP_ACTION.fetch(name) : Enum::PP_ACTION::NONE
+      end
+
+      name = ACTION_VERBS[verb]
+      name ? Enum::PP_ACTION.fetch(name) : Enum::PP_ACTION::NONE
+    end
+
+    # The relationship target of this click, whatever kind it is.
+    #
+    # For a hyperlink that is the URL. For a slide jump it is the target
+    # slide's partname, which is what python-pptx reports here too -- its
+    # docstring says otherwise, but the code returns the ref for any action
+    # carrying a relationship. {#url} is the one that means "a hyperlink".
+    def address
+      link = hlink
+      return nil if link.nil?
+
+      r_id = link.rId
+      return nil if r_id.nil? || r_id.empty?
+
+      part.target_ref(r_id)
+    end
+
+    # Set, change or (with nil) remove the hyperlink.
+    def address=(url)
+      clear
+      return if url.nil? || url.empty?
+
+      get_or_add_hlink.rId = part.relate_to(url, Opc::RELATIONSHIP_TYPE::HYPERLINK, external: true)
+    end
+
+    # The URL this click opens, or nil when the click is not a hyperlink.
+    #
+    # Unlike {#address} this does not report a slide partname for a jump: a
+    # thing called a URL should be a URL.
+    def url = action == Enum::PP_ACTION::HYPERLINK ? address : nil
+
+    # The slide this click jumps to, or nil.
+    def target_slide
+      return nil unless action == Enum::PP_ACTION::NAMED_SLIDE
+
+      part.related_part(hlink.rId).slide
+    end
+
+    def target_slide=(slide)
+      clear
+      return if slide.nil?
+
+      link = get_or_add_hlink
+      link.action = "#{Oxml::CT_Hyperlink::ACTION_SCHEME}hlinksldjump"
+      link.rId = part.relate_to(slide.part, Opc::RELATIONSHIP_TYPE::SLIDE)
+    end
+
+    # Remove whatever this click does, and the relationship behind it.
+    def clear
+      link = hlink
+      return self if link.nil?
+
+      r_id = link.rId
+      part.drop_rel(r_id) if r_id && !r_id.empty?
+      @element.remove(link)
+      self
+    end
+
+    def inspect = "#<Pptx::ActionSetting #{action.name} #{address.inspect}>"
+
+    private
+
+    def hlink = @element.find(@hover ? "a:hlinkHover" : "a:hlinkClick")
+
+    def get_or_add_hlink
+      @hover ? @element.get_or_add_hlinkHover : @element.get_or_add_hlinkClick
+    end
+  end
+end