ruby_pptx 0.1.0

data/lib/ruby_pptx/parts/embedded_package.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/opc/package"
+require "ruby_pptx/opc/constants"
+require "ruby_pptx/enum/prog_id"
+require "ruby_pptx/parts/chart"
+
+module Pptx
+  module Parts
+    # A file embedded in the presentation as an OLE object.
+    #
+    # An Office document -- one of Enum::PROG_ID -- is stored as the document
+    # itself, under a name and content type saying what it is. Anything else
+    # is stored as an opaque `oleObjectN.bin`.
+    module EmbeddedPackagePart
+      OFFICE_PARTS = {
+        DOCX: ["/ppt/embeddings/Microsoft_Word_Document%d.docx", Opc::CONTENT_TYPE::WML_DOCUMENT],
+        PPTX: ["/ppt/embeddings/Microsoft_PowerPoint_Presentation%d.pptx",
+               Opc::CONTENT_TYPE::PML_PRESENTATION],
+        XLSX: [EmbeddedXlsxPart::PARTNAME_TEMPLATE, Opc::CONTENT_TYPE::SML_SHEET]
+      }.freeze
+
+      GENERIC_PARTNAME = "/ppt/embeddings/oleObject%d.bin"
+
+      module_function
+
+      # @param prog_id [Enum::PROG_ID::Member, String]
+      # @return [Opc::Part]
+      def new_part(prog_id, blob, package)
+        unless prog_id.is_a?(Enum::PROG_ID::Member)
+          return Opc::Part.new(package.next_partname(GENERIC_PARTNAME),
+                               Opc::CONTENT_TYPE::OFC_OLE_OBJECT, package, blob)
+        end
+
+        # An embedded workbook is the same kind of part a chart keeps its data in.
+        return EmbeddedXlsxPart.new_xlsx(blob, package) if prog_id.name == :XLSX
+
+        template, content_type = OFFICE_PARTS.fetch(prog_id.name)
+        Opc::Part.new(package.next_partname(template), content_type, package, blob)
+      end
+    end
+  end
+end

data/lib/ruby_pptx/parts/image.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/opc/package"
+require "ruby_pptx/image"
+
+module Pptx
+  module Parts
+    # An image part, `/ppt/media/imageN.<ext>`.
+    class ImagePart < Opc::Part
+      attr_reader :source_filename
+
+      # A new image part holding +image+.
+      def self.new_image(package, image)
+        new(package.next_image_partname(image.ext), image.content_type, package,
+            image.blob, image.filename)
+      end
+
+      def initialize(partname, content_type, package, blob = nil, source_filename = nil)
+        super(partname, content_type, package, blob)
+        @source_filename = source_filename
+      end
+
+      def image = @image ||= Image.from_blob(blob, @source_filename)
+
+      def ext = partname.ext
+
+      # The name PowerPoint shows in the alt-text/description field: the file
+      # the image came from, or a generic name when it came from a stream.
+      def desc = @source_filename || "image.#{ext}"
+
+      def sha1 = image.sha1
+
+      # Resolve a requested size against the image's native size.
+      #
+      # Supplying neither dimension uses the native size; supplying one scales
+      # the other to preserve the aspect ratio; supplying both stretches the
+      # image to fit.
+      #
+      # @return [Array(Pptx::Length, Pptx::Length)]
+      def scale(width, height)
+        native_width, native_height = image.native_size
+        return [Length.coerce(width), Length.coerce(height)] if width && height
+        return [native_width, native_height] unless width || height
+
+        if width
+          factor = Length.coerce(width).emu.to_f / native_width.emu
+          [Length.coerce(width), Length.emu((native_height.emu * factor).round)]
+        else
+          factor = Length.coerce(height).emu.to_f / native_height.emu
+          [Length.emu((native_width.emu * factor).round), Length.coerce(height)]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_pptx/parts/media.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/opc/package"
+require "ruby_pptx/media"
+
+module Pptx
+  module Parts
+    # A media part, `/ppt/media/mediaN.<ext>`: the audio or video itself.
+    class MediaPart < Opc::Part
+      def self.new_media(package, video)
+        new(package.next_media_partname(video.ext), video.content_type, package, video.blob)
+      end
+
+      def sha1 = @sha1 ||= Digest::SHA1.hexdigest(blob)
+    end
+  end
+end

data/lib/ruby_pptx/parts/presentation.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/opc/package"
+require "ruby_pptx/opc/constants"
+require "ruby_pptx/oxml/presentation"
+require "ruby_pptx/parts/slide"
+require "ruby_pptx/presentation"
+
+module Pptx
+  module Parts
+    # The presentation part, `/ppt/presentation.xml`; the package's main
+    # document part.
+    class PresentationPart < Opc::XmlPart
+      def presentation = @presentation ||= Presentation.new(element, self)
+
+      # Create a blank slide part inheriting from +slide_layout+.
+      #
+      # @return [Array(String, Pptx::Slide)] the new relationship id and slide
+      def add_slide(slide_layout)
+        slide_part = SlidePart.new_slide(next_slide_partname, package, slide_layout.part)
+        r_id = relate_to(slide_part, Opc::RELATIONSHIP_TYPE::SLIDE)
+        [r_id, slide_part.slide]
+      end
+
+      def core_properties = package.core_properties
+
+      # The presentation's notes master, created from the default template on
+      # first use.
+      #
+      # Like python-pptx, this relates the new part to the presentation but
+      # does not add a `p:notesMasterIdLst` entry for it.
+      def notes_master_part
+        existing = rels.find { |r| r.reltype == Opc::RELATIONSHIP_TYPE::NOTES_MASTER }
+        return existing.target_part if existing
+
+        part = NotesMasterPart.create_default(package)
+        relate_to(part, Opc::RELATIONSHIP_TYPE::NOTES_MASTER)
+        part
+      end
+
+      def related_slide(r_id) = related_part(r_id).slide
+
+      def related_slide_master(r_id) = related_part(r_id).slide_master
+
+      # The slide with presentation-wide id +slide_id+.
+      #
+      # @return [Slide, nil]
+      def slide_by_id(slide_id)
+        entry = element.sldIdLst&.sldId_list&.find { |s| s.id == slide_id }
+        entry && related_part(entry.rId).slide
+      end
+
+      # The slide id assigned to +slide_part+.
+      def slide_id_for(slide_part)
+        entry = element.sldIdLst&.sldId_list&.find { |s| related_part(s.rId).equal?(slide_part) }
+        entry&.id || raise(NotFoundError, "slide part is not in this presentation")
+      end
+
+      # Renumber the slide parts so their partnames form a gapless sequence in
+      # the order the slides appear.
+      #
+      # Slide order lives in `p:sldIdLst`, not in the partnames, so the two can
+      # drift apart after slides are added or deleted. PowerPoint tolerates
+      # that, but keeping them aligned makes saved packages predictable.
+      def renumber_slide_parts(r_ids)
+        r_ids.each_with_index do |r_id, index|
+          related_part(r_id).partname = Opc::PackURI.new("/ppt/slides/slide#{index + 1}.xml")
+        end
+      end
+
+      def next_slide_partname
+        count = element.get_or_add_sldIdLst.size
+        Opc::PackURI.new("/ppt/slides/slide#{count + 1}.xml")
+      end
+
+      def save(path_or_stream) = package.save(path_or_stream)
+    end
+  end
+end

data/lib/ruby_pptx/parts/slide.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/opc/package"
+require "ruby_pptx/opc/constants"
+require "ruby_pptx/oxml/slide"
+require "ruby_pptx/slide"
+require "ruby_pptx/parts/chart"
+
+module Pptx
+  module Parts
+    # Common to every slide-like part: slides, layouts, masters, notes slides
+    # and the notes master.
+    class BaseSlidePart < Opc::XmlPart
+      # The internal name of this slide.
+      def name = element.cSld.name
+
+      # Create a chart part for +chart_data+ and relate this slide to it.
+      #
+      # @return [String] the relationship id of the new chart part
+      def add_chart_part(chart_type, chart_data)
+        chart_part = ChartPart.new_chart(chart_type, chart_data, package)
+        relate_to(chart_part, Opc::RELATIONSHIP_TYPE::CHART)
+      end
+
+      # Create a combo chart part and relate this slide to it.
+      #
+      # @return [String] the relationship id of the new chart part
+      def add_combo_chart_part(builder)
+        chart_part = ChartPart.new_combo_chart(builder, package)
+        relate_to(chart_part, Opc::RELATIONSHIP_TYPE::CHART)
+      end
+
+      # Relate this slide to the media part holding +video+.
+      #
+      # Two relationships are made to the same part, one MEDIA and one VIDEO.
+      # PowerPoint has embedded media two different ways over the years and
+      # writes both so either era can find it.
+      #
+      # @return [Array(String, String)] the media rId and the video rId
+      def get_or_add_video_media_part(video)
+        media_part = package.get_or_add_media_part(video)
+        [relate_to(media_part, Opc::RELATIONSHIP_TYPE::MEDIA),
+         relate_to(media_part, Opc::RELATIONSHIP_TYPE::VIDEO)]
+      end
+
+      # The image part for +image_file+, related to this slide.
+      #
+      # Both the part and the relationship are reused when they already exist,
+      # so the same image added twice is stored once.
+      #
+      # @return [Array(Pptx::Parts::ImagePart, String)] the part and its rId
+      # Embed +object_file+ as an OLE object and relate this slide to it.
+      #
+      # An Office document is related as a package, anything else as an OLE
+      # object -- the two relationship types PowerPoint uses.
+      #
+      # @return [String] the relationship id
+      def add_embedded_ole_object_part(prog_id, object_file)
+        blob = object_file.respond_to?(:read) ? object_file.read : File.binread(object_file)
+        part = EmbeddedPackagePart.new_part(prog_id, blob, package)
+        reltype = if prog_id.is_a?(Enum::PROG_ID::Member)
+                    Opc::RELATIONSHIP_TYPE::PACKAGE
+                  else
+                    Opc::RELATIONSHIP_TYPE::OLE_OBJECT
+                  end
+        relate_to(part, reltype)
+      end
+
+      def get_or_add_image_part(image_file)
+        image_part = package.get_or_add_image_part(image_file)
+        [image_part, relate_to(image_part, Opc::RELATIONSHIP_TYPE::IMAGE)]
+      end
+    end
+
+    # A slide part, `/ppt/slides/slideN.xml`.
+    class SlidePart < BaseSlidePart
+      # A new, empty slide part inheriting from +slide_layout_part+.
+      def self.new_slide(partname, package, slide_layout_part)
+        part = new(partname, Opc::CONTENT_TYPE::PML_SLIDE, package, Oxml::CT_Slide.new_element)
+        part.relate_to(slide_layout_part, Opc::RELATIONSHIP_TYPE::SLIDE_LAYOUT)
+        part
+      end
+
+      def slide = @slide ||= Slide.new(element, self)
+
+      # The layout part this slide inherits from.
+      def slide_layout
+        part_related_by(Opc::RELATIONSHIP_TYPE::SLIDE_LAYOUT).slide_layout
+      end
+
+      # The presentation-wide id of this slide.
+      def slide_id = package.presentation_part.slide_id_for(self)
+
+      def notes_slide? = rels.any? { |r| r.reltype == Opc::RELATIONSHIP_TYPE::NOTES_SLIDE }
+
+      # This slide's notes slide, created on first use.
+      def notes_slide
+        existing = rels.find { |r| r.reltype == Opc::RELATIONSHIP_TYPE::NOTES_SLIDE }
+        return existing.target_part.notes_slide if existing
+
+        notes_part = NotesSlidePart.new_notes_slide(package, self)
+        relate_to(notes_part, Opc::RELATIONSHIP_TYPE::NOTES_SLIDE)
+        notes_part.notes_slide
+      end
+    end
+
+    # A slide-layout part, `/ppt/slideLayouts/slideLayoutN.xml`.
+    class SlideLayoutPart < BaseSlidePart
+      PARTNAME_TEMPLATE = "/ppt/slideLayouts/slideLayout%d.xml"
+
+      # A new layout named +name+, inheriting from +slide_master_part+.
+      def self.new_layout(package, slide_master_part, name, layout_type)
+        part = new(package.next_partname(PARTNAME_TEMPLATE),
+                   Opc::CONTENT_TYPE::PML_SLIDE_LAYOUT, package,
+                   Oxml::CT_SlideLayout.new_element(name, layout_type))
+        part.relate_to(slide_master_part, Opc::RELATIONSHIP_TYPE::SLIDE_MASTER)
+        part
+      end
+
+      def slide_layout = @slide_layout ||= SlideLayout.new(element, self)
+
+      def slide_master
+        part_related_by(Opc::RELATIONSHIP_TYPE::SLIDE_MASTER).slide_master
+      end
+    end
+
+    # A slide-master part, `/ppt/slideMasters/slideMasterN.xml`.
+    class SlideMasterPart < BaseSlidePart
+      PARTNAME_TEMPLATE = "/ppt/slideMasters/slideMaster%d.xml"
+      THEME_PARTNAME_TEMPLATE = "/ppt/theme/theme%d.xml"
+
+      # A new master with its own theme part and no layouts yet.
+      #
+      # The theme is a separate part related from the master, which is where
+      # the master's colours and fonts actually live.
+      def self.new_master(package, name: "Office Theme")
+        part = new(package.next_partname(PARTNAME_TEMPLATE),
+                   Opc::CONTENT_TYPE::PML_SLIDE_MASTER, package,
+                   Oxml::CT_SlideMaster.new_element)
+        theme = ThemePart.new_theme(package.next_partname(THEME_PARTNAME_TEMPLATE), package,
+                                    name: name)
+        part.relate_to(theme, Opc::RELATIONSHIP_TYPE::THEME)
+        part
+      end
+
+      def slide_master = @slide_master ||= SlideMaster.new(element, self)
+
+      # The theme this master draws its colours and fonts from.
+      def theme_part = part_related_by(Opc::RELATIONSHIP_TYPE::THEME)
+
+      # Add +slide_layout_part+ to this master's layout list.
+      #
+      # @return [String] the relationship id
+      def add_slide_layout(slide_layout_part)
+        r_id = relate_to(slide_layout_part, Opc::RELATIONSHIP_TYPE::SLIDE_LAYOUT)
+        entry = element.get_or_add_sldLayoutIdLst.add_sldLayoutId
+        entry.rId = r_id
+        entry.id = next_slide_layout_id
+        r_id
+      end
+
+      def related_slide_layout(r_id) = related_part(r_id).slide_layout
+
+      private
+
+      # Layout ids are numbered from 2147483649 upwards, continuing from the
+      # highest already in use so a removed layout does not free its id for
+      # reuse -- PowerPoint keeps references to them elsewhere in the package.
+      def next_slide_layout_id
+        used = element.get_or_add_sldLayoutIdLst.sldLayoutId_list.filter_map(&:id)
+        used.empty? ? 2_147_483_649 : used.max + 1
+      end
+    end
+
+    # A notes-master part.
+    class NotesMasterPart < BaseSlidePart
+      PARTNAME = "/ppt/notesMasters/notesMaster1.xml"
+
+      # A default notes master with the theme it needs, built from the
+      # templates shipped with the gem.
+      #
+      # The theme is the base theme as-is. It is not routed through
+      # ThemePart.new_theme, which renames the colour and font schemes along
+      # with the theme and so would not match what python-pptx writes.
+      def self.create_default(package)
+        part = new(Opc::PackURI.new(PARTNAME), Opc::CONTENT_TYPE::PML_NOTES_MASTER, package,
+                   Oxml::CT_NotesMaster.new_default)
+        theme = ThemePart.new(package.next_partname(SlideMasterPart::THEME_PARTNAME_TEMPLATE),
+                              Opc::CONTENT_TYPE::OFC_THEME, package,
+                              Oxml::CT_OfficeStyleSheet.new_default)
+        part.relate_to(theme, Opc::RELATIONSHIP_TYPE::THEME)
+        part
+      end
+
+      def notes_master = @notes_master ||= NotesMaster.new(element, self)
+    end
+
+    # A notes-slide part, `/ppt/notesSlides/notesSlideN.xml`.
+    class NotesSlidePart < BaseSlidePart
+      PARTNAME_TEMPLATE = "/ppt/notesSlides/notesSlide%d.xml"
+
+      # A new notes slide for +slide_part+, related to the notes master and
+      # carrying clones of the master's slide-image, body and slide-number
+      # placeholders. The notes master is created first if the presentation
+      # has none.
+      def self.new_notes_slide(package, slide_part)
+        notes_master_part = package.presentation_part.notes_master_part
+        part = new(package.next_partname(PARTNAME_TEMPLATE), Opc::CONTENT_TYPE::PML_NOTES_SLIDE,
+                   package, Oxml::CT_NotesSlide.new_element)
+        part.relate_to(notes_master_part, Opc::RELATIONSHIP_TYPE::NOTES_MASTER)
+        part.relate_to(slide_part, Opc::RELATIONSHIP_TYPE::SLIDE)
+        part.notes_slide.clone_master_placeholders(notes_master_part.notes_master)
+        part
+      end
+
+      def notes_slide = @notes_slide ||= NotesSlide.new(element, self)
+
+      def notes_master = part_related_by(Opc::RELATIONSHIP_TYPE::NOTES_MASTER).notes_master
+    end
+  end
+end

data/lib/ruby_pptx/parts/theme.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/opc/package"
+require "ruby_pptx/opc/constants"
+require "ruby_pptx/oxml/theme"
+require "ruby_pptx/theme"
+
+module Pptx
+  module Parts
+    # A theme part, `/ppt/theme/themeN.xml`.
+    #
+    # Every slide master relates to exactly one, and it is where the master's
+    # colours and fonts actually live -- the master itself only maps them.
+    class ThemePart < Opc::XmlPart
+      # A new theme part starting from the base theme shipped with the gem.
+      def self.new_theme(partname, package, name: "Office Theme")
+        part = new(partname, Opc::CONTENT_TYPE::OFC_THEME, package,
+                   Oxml::CT_OfficeStyleSheet.new_default)
+        part.theme.name = name
+        part
+      end
+
+      def theme = @theme ||= Theme.new(element, self)
+    end
+  end
+end

data/lib/ruby_pptx/pattern_matching.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Pptx
+  # `case`/`in` support for the objects a caller reads a deck with.
+  #
+  #   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: Pptx::Length => w} if w > Pptx.inches(5)
+  #                                             then puts "wide"
+  #   end
+  #
+  # **Enum-valued attributes read as their symbolic name in a pattern.**
+  # `shape.shape_type` returns a {Pptx::Enum::Member}, because that member
+  # carries the MS API value and the XML value and is the honest return type.
+  # In a pattern none of that helps -- `in {shape_type: :PICTURE}` is what
+  # anyone would write -- so the pattern-matching view reports the symbol.
+  #
+  # Only the keys a pattern actually asks for are computed, so matching on a
+  # shape's name does not walk its text.
+  module PatternMatching
+    def self.included(base) = base.extend(ClassMethods)
+
+    # A member reads as its name; anything else is passed through.
+    def self.for_pattern(value)
+      value.is_a?(Enum::Member) ? value.to_sym : value
+    end
+
+    module ClassMethods
+      # Declare the keys `case`/`in` may match on. Each names a public method.
+      def pattern_keys(*names)
+        names.freeze
+        define_method(:deconstruct_keys) do |keys|
+          wanted = keys.nil? ? names : names & keys
+          wanted.to_h { |name| [name, PatternMatching.for_pattern(public_send(name))] }
+        end
+      end
+    end
+  end
+
+  # Array patterns for the collections, so `in [first, *rest]` works.
+  #
+  # Kept separate from {PatternMatching} because deconstructing a collection
+  # means enumerating all of it, which is the opposite of the lazy wrapping
+  # everything else here does. Use it where the whole list is wanted anyway.
+  module DeconstructToArray
+    def deconstruct = to_a
+  end
+end

data/lib/ruby_pptx/presentation.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/pattern_matching"
+
+require "ruby_pptx/element_proxy"
+require "ruby_pptx/slide"
+require "ruby_pptx/section"
+
+module Pptx
+  # A PowerPoint presentation.
+  #
+  # Open one with {Presentation.open}, or start from the built-in template with
+  # {Presentation.new}:
+  #
+  #   prs = Pptx::Presentation.open("deck.pptx")
+  #   prs.slides.each { |slide| puts slide.name }
+  #   prs.slide_width = Pptx.inches(13.333)
+  #   prs.save("wide.pptx")
+  class Presentation < PartElementProxy
+    include PatternMatching
+
+    pattern_keys :slides, :slide_layouts, :slide_masters, :slide_width, :slide_height
+
+    class << self
+      # Open a presentation from a path or an IO stream.
+      #
+      # Given a block, yields the presentation and returns the block's value,
+      # as `File.open` does.
+      #
+      # @raise [PackageNotFoundError] when the file is not an OPC package
+      # @raise [Error] when the package is not a PowerPoint presentation
+      def open(pptx = nil)
+        pptx ||= default_template_path
+        presentation_part = Package.open(pptx).main_document_part
+        unless VALID_CONTENT_TYPES.include?(presentation_part.content_type)
+          raise Error,
+                "not a PowerPoint file; content type is #{presentation_part.content_type.inspect}"
+        end
+
+        presentation = presentation_part.presentation
+        block_given? ? yield(presentation) : presentation
+      end
+
+      # A new presentation based on the built-in default template.
+      def new_default = Presentation.open(nil)
+
+      def default_template_path
+        File.expand_path("templates/default.pptx", __dir__)
+      end
+    end
+
+    VALID_CONTENT_TYPES = [
+      Opc::CONTENT_TYPE::PML_PRESENTATION_MAIN,
+      Opc::CONTENT_TYPE::PML_PRES_MACRO_MAIN
+    ].freeze
+
+    # The Dublin Core metadata for this presentation.
+    def core_properties = part.core_properties
+
+    # The slides in this presentation.
+    def slides
+      @slides ||= begin
+        sld_id_list = @element.get_or_add_sldIdLst
+        part.renumber_slide_parts(sld_id_list.sldId_list.map(&:rId))
+        Slides.new(sld_id_list, self)
+      end
+    end
+
+    # The slide masters in this presentation.
+    def slide_masters
+      @slide_masters ||= SlideMasters.new(@element.get_or_add_sldMasterIdLst, self)
+    end
+
+    # The notes master, created from the default template on first use.
+    #
+    # @return [NotesMaster]
+    def notes_master = part.notes_master_part.notes_master
+
+    # The first slide master, which is the only one in most presentations.
+    def slide_master = slide_masters[0]
+
+    # The layouts of the first slide master.
+    #
+    # A presentation may have several masters, each with its own layouts; this
+    # is a convenience for the common case of one.
+    def slide_layouts = slide_master.slide_layouts
+
+    # The sections grouping this presentation's slides.
+    #
+    # Sections are a PowerPoint 2010 extension; a presentation with none has
+    # an empty collection and writes no extension element.
+    def sections = @sections ||= Sections.new(self)
+
+    # @return [Length, nil] nil when the presentation defines no slide size
+    def slide_width = @element.sldSz&.cx
+
+    def slide_width=(width)
+      @element.get_or_add_sldSz.cx = width
+    end
+
+    # @return [Length, nil]
+    def slide_height = @element.sldSz&.cy
+
+    def slide_height=(height)
+      @element.get_or_add_sldSz.cy = height
+    end
+
+    # Write this presentation to a path or an IO stream.
+    def save(path_or_stream)
+      part.save(path_or_stream)
+      self
+    end
+
+    # The .pptx bytes, for callers who want to hand them to something other
+    # than the filesystem.
+    #
+    # @return [String]
+    def to_blob
+      buffer = StringIO.new(+"", "w+b")
+      save(buffer)
+      buffer.string
+    end
+
+    def inspect
+      "#<Pptx::Presentation slides=#{slides.size} #{slide_width&.inches}x#{slide_height&.inches}in>"
+    end
+  end
+end

data/lib/ruby_pptx/refinements.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/numeric_lengths"
+
+module Pptx
+  # Numeric length sugar, scoped to the file that asks for it.
+  #
+  #   require "ruby_pptx/refinements"
+  #   using Pptx::Lengths
+  #
+  #   slide.shapes.add_shape(:rectangle, at: [1.inch, 2.inch], size: [3.inch, 1.inch])
+  #
+  # A refinement is the polite version of `ruby_pptx/core_ext`: `Numeric` gains
+  # these methods inside this file and nowhere else, so nothing else sharing
+  # the process can see them.
+  module Lengths
+    refine Numeric do
+      import_methods NumericLengths
+    end
+  end
+end