ruby_pptx 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cd5ac8827fcd5b81d86a1b0a0faa9f619f776dd005580589bbe88fd3f666d4a
-  data.tar.gz: 6dafdf4a15d53bb8d4a795d3e2c0a18beebab2bd35070076d69e2a7cddddd29f
+  metadata.gz: 7f8ea512f0616c3815f62322b952b77ff602f61cbb907de7168308aebd26507b
+  data.tar.gz: '00468b31384c6b3dee28b54c28934e802eff15a7e1f9a7654d30db47c72d1e7f'
 SHA512:
-  metadata.gz: b54ec7a6115da3d4da42ee124faefb0fee0e51d200525af1c05527fe9a6c579d279ca7da59293ce71b81a56a03c4e1567b228cb86caa234e28f1b0faf44bd9ef
-  data.tar.gz: 2d991bf2f20c571783f5d1243d586b9e0aa9b4f2db655872c1b60a71ada29495b5e91ab587674e82fa98d34a8cb552e51f5c6fc20b76afa680691cf84bbccce8
+  metadata.gz: 3c696588e9468af5de7c99e48fa7129b1066579eb85d1a955e9d1994d42c71da96765465c108653734b54a4fd301a73d6ef159b6e5a2c58c984bbb2612e05e8f
+  data.tar.gz: 19fe045441180661f4629bf93c46a1efc12e6ac62d6d31207bd792f871ff60f9c3bcb7e96ef74fb4632d98dea56a4d24192a9425071e0c811a9db37322dce9e3

data/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this gem are recorded here. The format follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Before 1.0 a minor
 version may change the public API.
 
+## [0.2.0] - 2026-09-28
+
+### Added
+
+- A pure-Ruby XML backend built on REXML, used automatically where Nokogiri
+  cannot be loaded -- notably ruby.wasm. It writes the same packages as the
+  Nokogiri backend; CI runs every spec under both, and builds, saves and
+  rereads a deck inside ruby.wasm. `Pptx.xml_backend` reports which is in
+  use, and `RUBY_PPTX_XML_BACKEND` chooses one explicitly.
+- `rexml` is now a runtime dependency. Nokogiri remains one too.
+
+### Changed
+
+- `require "ruby_pptx"` no longer requires Nokogiri directly; the XML
+  backend loads it.
+
+## [0.1.1] - 2026-09-28
+
+### Fixed
+
+- `gem install ruby_pptx` failed on Windows while generating ri
+  documentation (`Errno::ENOENT` on a very long `.ri` path). RDoc 7 and
+  earlier, which Ruby 3.3 to 4.0 bundle, cannot parse endless method
+  definitions (`def x = ...`); each one ended its class early, so every later
+  class was documented inside the one before it. On other platforms the
+  install succeeded but the ri documentation was wrong. The library no longer
+  uses endless methods, and CI checks that RDoc places every class correctly.
+- `Presentation.open(path)` left a file handle open for every member of the
+  package until garbage collection, so on Windows the `.pptx` stayed locked
+  and could not be deleted or overwritten after opening it.
+
 ## [0.1.0] - 2026-09-28
 
 The first release: a Ruby port of [python-pptx](https://github.com/scanny/python-pptx)
@@ -80,4 +111,6 @@ or where matching it cannot be done. Each case is listed, with its reason, in
 - Getters that write to the document in python-pptx -- data-label flags, axis
   and chart titles -- do not here.
 
+[0.2.0]: https://github.com/Largo/ruby_pptx/releases/tag/v0.2.0
+[0.1.1]: https://github.com/Largo/ruby_pptx/releases/tag/v0.1.1
 [0.1.0]: https://github.com/Largo/ruby_pptx/releases/tag/v0.1.0

data/README.md

@@ -92,6 +92,52 @@ end
 deck.save("out.pptx")
 ```
 
+Speaker notes are plain text for the common case, with the full text frame
+underneath when you want formatting. Reading `notes` never creates a notes
+page; assigning does.
+
+```ruby
+slide.notes = "Mention the Q3 dip.\nThank the team."
+slide.notes                            #=> "Mention the Q3 dip.\nThank the team."
+slide.notes_slide.notes_text_frame.paragraphs.last.runs.first.font.bold = true
+```
+
+Picture, table and chart placeholders are filled in place, so the content takes
+the layout's position and size. A picture is cropped to fill its placeholder,
+never stretched.
+
+```ruby
+photo = deck.slides.add(deck.slide_layouts["Picture with Caption"])
+photo.placeholders[1].insert_picture("office.jpg")
+photo.placeholders[2].text_frame.text = "Our new office"
+
+# The default template has no table or chart placeholders, so add a layout
+# with both to its master.
+layout = deck.slide_masters[0].slide_layouts.add("Table and Chart", type: "twoObj") do |l|
+  l.placeholders.add(:title)
+  l.placeholders.add(:table, idx: 1, at: [Pptx.inches(0.5), Pptx.inches(1.5)],
+                                     size: [Pptx.inches(4.25), Pptx.inches(4.5)])
+  l.placeholders.add(:chart, idx: 2, at: [Pptx.inches(5.25), Pptx.inches(1.5)],
+                                     size: [Pptx.inches(4.25), Pptx.inches(4.5)])
+end
+
+report = deck.slides.add(layout)
+report.placeholders[1].insert_table(3, 2).table[0, 0].text = "Region"
+report.placeholders[2].insert_chart(:column_clustered, data)
+```
+
+Any file can be embedded as an OLE object, shown as an icon that opens it when
+double-clicked. Word, Excel and PowerPoint files get Office's own icon; for
+anything else, name its ProgID and optionally supply an icon.
+
+```ruby
+sheet = slide.shapes.add_ole_object("budget.xlsx", prog_id: :xlsx, at: [x, y])
+sheet.ole_format.prog_id               #=> "Excel.Sheet.12"
+
+slide.shapes.add_ole_object("report.pdf", prog_id: "AcroExch.Document", at: [x, y],
+                            icon_file: "pdf-icon.png")
+```
+
 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**.
@@ -213,6 +259,36 @@ end
 Collections index like arrays — `slides[2]`, `slides[-1]`, `slides[1..3]`,
 `slides[1, 2]` — and deconstruct into array patterns.
 
+## Nokogiri, REXML and ruby.wasm
+
+ruby_pptx reads and writes XML with Nokogiri. Where Nokogiri cannot load --
+ruby.wasm, in a browser or elsewhere -- it falls back to REXML, which is pure
+Ruby, with no configuration:
+
+```ruby
+Pptx.xml_backend   #=> :nokogiri, or :rexml without Nokogiri
+```
+
+The output does not depend on the backend: CI runs every spec under both, and
+the packages they write are identical part for part. REXML is slower -- in a
+60-slide deck with text, tables and charts, about 3.3 s against 0.5 s to build
+and save, and 0.7 s against 0.1 s to open and read it back. Set
+`RUBY_PPTX_XML_BACKEND=rexml` (or `nokogiri`) to choose explicitly.
+
+Nokogiri stays a declared dependency, so a normal `gem install` or `bundle
+install` gets the fast path. Two things to know when loading the gem in
+ruby.wasm yourself:
+
+- Load `ruby_pptx`, `rubyzip` and `rexml`, but not `nokogiri`, which is
+  native. A loader that installs a gem together with its runtime
+  dependencies will stop at Nokogiri.
+- Ship the whole `lib/` directory, not only its `.rb` files: the templates
+  in `lib/ruby_pptx/templates` (the default deck, notes pages, icons) are
+  read as files.
+
+`tools/wasm/run.mjs` runs the gem this way under ruby.wasm's browser
+filesystem, and CI uses it to build, save and reread a deck on every push.
+
 ## Development
 
 ```bash
@@ -258,8 +334,13 @@ 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.
+the gem attached and the changelog entry as its notes.
+
+Publishing to RubyGems is a separate step: in the Actions tab, open **Publish to
+RubyGems**, choose **Run workflow**, and pick the release's tag under "Use
+workflow from". It refuses to run from a branch. RubyGems' `release-gem` action
+builds the tagged commit and pushes it, authenticating by RubyGems trusted
+publishing rather than a stored API key.
 
 ## License
 

data/lib/ruby_pptx/action.rb

@@ -33,7 +33,9 @@ module Pptx
       @hover = hover
     end
 
-    def part = @parent.part
+    def part
+      @parent.part
+    end
 
     # @return [Pptx::Enum::PP_ACTION] NONE when nothing happens on click
     def action
@@ -78,7 +80,9 @@ module Pptx
     #
     # 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
+    def url
+      action == Enum::PP_ACTION::HYPERLINK ? address : nil
+    end
 
     # The slide this click jumps to, or nil.
     def target_slide
@@ -107,11 +111,15 @@ module Pptx
       self
     end
 
-    def inspect = "#<Pptx::ActionSetting #{action.name} #{address.inspect}>"
+    def inspect
+      "#<Pptx::ActionSetting #{action.name} #{address.inspect}>"
+    end
 
     private
 
-    def hlink = @element.find(@hover ? "a:hlinkHover" : "a:hlinkClick")
+    def hlink
+      @element.find(@hover ? "a:hlinkHover" : "a:hlinkClick")
+    end
 
     def get_or_add_hlink
       @hover ? @element.get_or_add_hlinkHover : @element.get_or_add_hlinkClick

data/lib/ruby_pptx/autoshape_spec.rb

@@ -330,8 +330,12 @@ module Pptx
       end
     end
 
-    def basename(shape_type) = self.for(shape_type)[:basename]
+    def basename(shape_type)
+      self.for(shape_type)[:basename]
+    end
 
-    def default_adjustments(shape_type) = self.for(shape_type)[:default_adjustments]
+    def default_adjustments(shape_type)
+      self.for(shape_type)[:default_adjustments]
+    end
   end
 end

data/lib/ruby_pptx/builder.rb

@@ -223,6 +223,8 @@ module Pptx
     end
 
     # A colour may be given as an RGBColor or as a hex string.
-    def rgb(value) = value.is_a?(RGBColor) ? value : RGBColor.from_string(value)
+    def rgb(value)
+      value.is_a?(RGBColor) ? value : RGBColor.from_string(value)
+    end
   end
 end

data/lib/ruby_pptx/chart/categories.rb

@@ -54,14 +54,22 @@ module Pptx
       ChartDataCategory.new(label, self).tap { |category| @categories << category }
     end
 
-    def each(&) = @categories.each(&)
+    def each(&)
+      @categories.each(&)
+    end
 
-    def [](index) = @categories[index]
+    def [](index)
+      @categories[index]
+    end
 
-    def size = @categories.size
+    def size
+      @categories.size
+    end
     alias length size
 
-    def empty? = @categories.empty?
+    def empty?
+      @categories.empty?
+    end
 
     # Levels of labels: 0 with no categories, 1 for a plain list.
     #
@@ -76,7 +84,9 @@ module Pptx
     end
 
     # The number of categories actually plotted.
-    def leaf_count = @categories.sum(&:leaf_count)
+    def leaf_count
+      @categories.sum(&:leaf_count)
+    end
 
     # Each level as [index, label] pairs, leaf level first. The index is the
     # leaf position where that label's run begins.
@@ -85,11 +95,17 @@ module Pptx
     end
 
     # The leaf labels in plotting order.
-    def leaf_labels = levels.first.to_a.map(&:last)
+    def leaf_labels
+      levels.first.to_a.map(&:last)
+    end
 
-    def dates? = depth == 1 && date?(first.label)
+    def dates?
+      depth == 1 && date?(first.label)
+    end
 
-    def numeric? = depth == 1 && (first.label.is_a?(Numeric) || date?(first.label))
+    def numeric?
+      depth == 1 && (first.label.is_a?(Numeric) || date?(first.label))
+    end
 
     # The number format for the categories: as set, or a date format for
     # dates, or "General".
@@ -111,7 +127,9 @@ module Pptx
       raise Error, "category not in these categories"
     end
 
-    def inspect = "#<Pptx::ChartDataCategories depth=#{depth} #{leaf_labels.inspect}>"
+    def inspect
+      "#<Pptx::ChartDataCategories depth=#{depth} #{leaf_labels.inspect}>"
+    end
 
     private
 
@@ -121,7 +139,9 @@ module Pptx
       lower + [categories.map { |category| [category.idx, category.label] }]
     end
 
-    def date?(value) = value.is_a?(Date) || value.is_a?(Time)
+    def date?(value)
+      value.is_a?(Date) || value.is_a?(Time)
+    end
   end
 
   # One category, or a group of them when it has sub-categories.
@@ -135,7 +155,9 @@ module Pptx
     end
 
     # The label; "" for a category given as nil.
-    def label = @label.nil? ? "" : @label
+    def label
+      @label.nil? ? "" : @label
+    end
 
     # @return [ChartDataCategory] the new sub-category
     def add_sub_category(label)
@@ -161,10 +183,14 @@ module Pptx
       depths.first + 1
     end
 
-    def leaf_count = @sub_categories.empty? ? 1 : @sub_categories.sum(&:leaf_count)
+    def leaf_count
+      @sub_categories.empty? ? 1 : @sub_categories.sum(&:leaf_count)
+    end
 
     # The leaf position at which this category's run begins.
-    def idx = @parent.index_of(self)
+    def idx
+      @parent.index_of(self)
+    end
 
     # @api private
     def index_of(sub_category)
@@ -190,9 +216,13 @@ module Pptx
     end
 
     # The label as it appears in the category cache and worksheet.
-    def to_s = label.to_s
+    def to_s
+      label.to_s
+    end
 
-    def inspect = "#<Pptx::ChartDataCategory #{label.inspect}>"
+    def inspect
+      "#<Pptx::ChartDataCategory #{label.inspect}>"
+    end
 
     private
 

data/lib/ruby_pptx/chart/chart.rb

@@ -31,10 +31,14 @@ module Pptx
     # python-pptx's PlotTypeInspector does.
     #
     # @return [Pptx::Enum::Member] a member of XL_CHART_TYPE
-    def chart_type = ChartTypeInspector.chart_type(plot_area.plot_elements.first)
+    def chart_type
+      ChartTypeInspector.chart_type(plot_area.plot_elements.first)
+    end
 
     # The chart style number, 1 to 48, or nil when none is set.
-    def chart_style = @element.style&.val
+    def chart_style
+      @element.style&.val
+    end
 
     def chart_style=(value)
       @element.remove_style
@@ -42,7 +46,9 @@ module Pptx
     end
 
     # The default font for all text in the chart, created on first use.
-    def font = @font ||= Font.new(@element.defRPr)
+    def font
+      @font ||= Font.new(@element.defRPr)
+    end
 
     # Every series in the chart: plot by plot, and within a plot in the order
     # it draws them.
@@ -65,7 +71,9 @@ module Pptx
     end
 
     # Whether a legend is drawn.
-    def legend? = !chart_element.legend.nil?
+    def legend?
+      !chart_element.legend.nil?
+    end
 
     def legend=(value)
       value ? chart_element.get_or_add_legend : chart_element.remove_legend
@@ -78,7 +86,9 @@ module Pptx
       element.nil? ? nil : (@legend ||= ChartLegend.new(element))
     end
 
-    def title? = !chart_element.title.nil?
+    def title?
+      !chart_element.title.nil?
+    end
 
     # @return [ChartTitle, nil]
     def title
@@ -105,7 +115,9 @@ module Pptx
     #
     # Nearly every chart has exactly one; a combo chart has several, which is
     # why this is a collection rather than a property of the chart.
-    def plots = plot_area.plot_elements.map { |element| ChartPlot.new(element, self) }
+    def plots
+      plot_area.plot_elements.map { |element| ChartPlot.new(element, self) }
+    end
 
     # The horizontal axis: a category or date axis, or, on an XY or bubble
     # chart, the first value axis. nil for a chart with no axes, such as a pie.
@@ -129,7 +141,9 @@ module Pptx
       ValueAxis.new(axes[axes.size > 1 ? 1 : 0])
     end
 
-    def value_axes = plot_area.value_axes.map { |element| ValueAxis.new(element) }
+    def value_axes
+      plot_area.value_axes.map { |element| ValueAxis.new(element) }
+    end
 
     # The category labels cached in the chart XML.
     def categories
@@ -139,13 +153,19 @@ module Pptx
       first.xpath("./c:cat//c:pt/c:v").map(&:text)
     end
 
-    def inspect = "#<Pptx::Chart #{chart_type.name} series=#{series.size}>"
+    def inspect
+      "#<Pptx::Chart #{chart_type.name} series=#{series.size}>"
+    end
 
     private
 
-    def chart_element = @element.chart
+    def chart_element
+      @element.chart
+    end
 
-    def plot_area = chart_element.plotArea
+    def plot_area
+      chart_element.plotArea
+    end
   end
 
   # Works out the full chart type from a plot element, after python-pptx's
@@ -200,11 +220,17 @@ module Pptx
       rule.call(plot)
     end
 
-    def line_markers?(plot) = plot.xpath('c:ser/c:marker/c:symbol[@val="none"]').empty?
+    def line_markers?(plot)
+      plot.xpath('c:ser/c:marker/c:symbol[@val="none"]').empty?
+    end
 
-    def exploded?(plot) = !plot.xpath("./c:ser/c:explosion").empty?
+    def exploded?(plot)
+      !plot.xpath("./c:ser/c:explosion").empty?
+    end
 
-    def first_symbol(plot) = plot.xpath("c:ser/c:marker/c:symbol").first&.get("val")
+    def first_symbol(plot)
+      plot.xpath("c:ser/c:marker/c:symbol").first&.get("val")
+    end
 
     def bubble(plot)
       bubble3d = plot.xpath("c:ser/c:bubble3D").first
@@ -260,17 +286,27 @@ module Pptx
     end
 
     # The fill and outline of this series.
-    def format = @format ||= ChartFormat.new(@element)
+    def format
+      @format ||= ChartFormat.new(@element)
+    end
 
     # The series' chart-wide index.
-    def index = @element.idx.val
+    def index
+      @element.idx.val
+    end
 
-    def name = @element.xpath("./c:tx//c:pt/c:v").first&.text.to_s
+    def name
+      @element.xpath("./c:tx//c:pt/c:v").first&.text.to_s
+    end
 
     # Cached values, with nil where the chart records a gap.
-    def values = cached(@element.val)
+    def values
+      cached(@element.val)
+    end
 
-    def inspect = "#<#{self.class.name} #{name.inspect}>"
+    def inspect
+      "#<#{self.class.name} #{name.inspect}>"
+    end
 
     private
 
@@ -286,15 +322,21 @@ module Pptx
   # Data labels and per-point formatting, for series plotted by category.
   module CategorySeriesFeatures
     # This series' own data labels, created on first use.
-    def data_labels = @data_labels ||= ChartDataLabels.new(@element.get_or_add_dLbls)
+    def data_labels
+      @data_labels ||= ChartDataLabels.new(@element.get_or_add_dLbls)
+    end
 
     # The points of this series, one per category.
-    def points = ChartPoints.new(@element, @element.cat_ptCount_val)
+    def points
+      ChartPoints.new(@element, @element.cat_ptCount_val)
+    end
   end
 
   # Markers, for the kinds of series that draw them.
   module MarkerFeatures
-    def marker = @marker ||= Marker.new(@element)
+    def marker
+      @marker ||= Marker.new(@element)
+    end
   end
 
   class AreaSeriesView < ChartSeriesView
@@ -310,7 +352,9 @@ module Pptx
 
     # Whether a negative bar is drawn in inverted colours. An absent
     # `c:invertIfNegative` reads as true, the schema default.
-    def invert_if_negative? = @element.invertIfNegative.nil? || @element.invertIfNegative.val
+    def invert_if_negative?
+      @element.invertIfNegative.nil? || @element.invertIfNegative.val
+    end
 
     def invert_if_negative=(value)
       @element.get_or_add_invertIfNegative.val = value ? true : false
@@ -323,7 +367,9 @@ module Pptx
 
     # Whether the line is drawn as a smooth curve. An absent `c:smooth` reads
     # as true, the schema default.
-    def smooth? = @element.smooth.nil? || @element.smooth.val
+    def smooth?
+      @element.smooth.nil? || @element.smooth.val
+    end
 
     def smooth=(value)
       @element.get_or_add_smooth.val = value ? true : false
@@ -339,9 +385,13 @@ module Pptx
   class XySeriesView < ChartSeriesView
     include MarkerFeatures
 
-    def values = cached(@element.yVal)
+    def values
+      cached(@element.yVal)
+    end
 
-    def points = ChartPoints.new(@element, [@element.xVal_ptCount_val, @element.yVal_ptCount_val].min)
+    def points
+      ChartPoints.new(@element, [@element.xVal_ptCount_val, @element.yVal_ptCount_val].min)
+    end
   end
 
   class BubbleSeriesView < XySeriesView
@@ -387,10 +437,10 @@ module Pptx
 
       next_index = plot_area.series_elements.size
       count.times do |offset|
-        copy = last.parent.build_from_xml(last.node.to_xml)
+        copy = last.parent.import(last)
         copy.get_or_add_idx.val = next_index + offset
         copy.get_or_add_order.val = next_index + offset
-        last.node.add_next_sibling(copy.node)
+        last.add_next_sibling(copy)
         last = copy
       end
     end

data/lib/ruby_pptx/chart/combo.rb

@@ -62,7 +62,9 @@ module Pptx
       self
     end
 
-    def secondary_axis? = @specs.any?(&:secondary_axis)
+    def secondary_axis?
+      @specs.any?(&:secondary_axis)
+    end
 
     private
 
@@ -122,7 +124,9 @@ module Pptx
 
     private
 
-    def plot_elements = @builder.specs.map { |spec| plot_element(spec) }.join
+    def plot_elements
+      @builder.specs.map { |spec| plot_element(spec) }.join
+    end
 
     def plot_element(spec)
       family = ChartXmlWriter.family_of(spec.chart_type)
@@ -141,7 +145,9 @@ module Pptx
       XML
     end
 
-    def plot_tag(family) = { bar: "c:barChart", line: "c:lineChart", area: "c:areaChart" }[family]
+    def plot_tag(family)
+      { bar: "c:barChart", line: "c:lineChart", area: "c:areaChart" }[family]
+    end
 
     def bar_plot_body(spec)
       direction = ChartXmlWriter::BarChartWriter::BAR_TYPES.include?(spec.chart_type.name) ? "bar" : "col"