rbpptx 0.1.0 → 0.2.0

data/lib/rbpptx/slide.rb

@@ -1,78 +1,171 @@
 module Rbpptx
-  # A single slide loaded from a presentation's ZIP container.
+  # Common behavior for an XML part that holds a shape tree (+<p:cSld>/
+  # <p:spTree>+): slides and notes slides.
   #
-  # 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
+  # Parsing is deferred until the shape tree is first accessed and then
+  # cached, so simply enumerating slides does not pay the per-slide parse
+  # cost.
+  class SlidePart
+    include ShapeContainer
 
-    # @return [String] the part name of the slide inside the package, e.g.
+    # @return [String] the part name inside the package, e.g.
     #   +"ppt/slides/slide1.xml"+
     attr_reader :part_name
 
-    # @param zip [Zip::File] the open package
+    # @param package [Package] the open package
     # @param part_name [String] absolute part name (no leading slash)
-    def initialize(zip:, part_name:)
-      @zip = zip
+    # @api private
+    def initialize(package:, part_name:)
+      @package = package
       @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
+    # @return [Placeholders] placeholder shapes on this part, addressable as
+    #   +placeholders[:body]+ (by type) or +placeholders[1]+ (by +idx+)
+    def placeholders
+      Placeholders.new(shapes)
     end
 
-    # @return [Boolean] whether any shape on this slide has been mutated since
-    #   load
+    # @return [Boolean] whether any shape on this part has been mutated since
+    #   load or the last save
     def dirty?
       @dirty
     end
 
-    # Marks the slide as dirty. Called by {Shape} setters; not part of the
-    # public API.
+    # Marks the part as dirty. Called by {Shape} and {Run} setters; not part
+    # of the public API.
     #
     # @api private
     def mark_dirty!
+      @package.touch(@part_name)
       @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
 
+    # @return [String] the part's XML, reflecting any in-memory mutations.
+    #   The XML declaration is preserved.
+    def to_xml
+      doc.to_xml(save_with: Package::SAVE_OPTIONS)
+    end
+
     private
 
     def doc
-      @doc ||= parse_doc
+      @doc ||= @package.xml(@part_name, error_class: SlideFormatError)
+    end
+
+    def shape_tree_node
+      doc.at_xpath("/*/p:cSld/p:spTree", "p" => P_NS)
+    end
+
+    def owner_part
+      self
+    end
+  end
+
+  # A single slide.
+  class Slide < SlidePart
+    NOTES_SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesSlide".freeze
+
+    # @param package [Package] the open package
+    # @param part_name [String] absolute part name (no leading slash)
+    # @param presentation [Presentation, nil] owner, needed to create a notes
+    #   slide on demand
+    # @api private
+    def initialize(package:, part_name:, presentation: nil)
+      super(package: package, part_name: part_name)
+      @presentation = presentation
+    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. Shapes inside groups are not included; see
+    #   {#all_shapes} and {#groups}.
+    def shapes
+      @shapes ||= super
+    end
+
+    # @return [Shape, nil] the title placeholder (+:title+ or +:ctrTitle+),
+    #   or +nil+ when the slide has none
+    def title
+      shapes.find { |s| %i[title ctrTitle].include?(s.placeholder_type) }
     end
 
-    def parse_doc
-      entry = @zip.find_entry(@part_name)
-      raise SlideFormatError, "missing slide part #{@part_name}" unless entry
+    # @return [NotesSlide, nil] the slide's notes page, or +nil+ when the
+    #   slide has none. Does not create one; see {#notes=}.
+    def notes_slide
+      return @notes_slide if defined?(@notes_slide)
+
+      part = @package.related(@part_name, NOTES_SLIDE_REL_TYPE).first
+      @notes_slide = part && NotesSlide.new(package: @package, part_name: part)
+    end
+
+    # @return [String] speaker notes text, or +""+ when the slide has no
+    #   notes page
+    def notes
+      notes_slide&.text || ""
+    end
 
-      parsed = Nokogiri::XML(entry.get_input_stream.read)
-      raise SlideFormatError, "#{@part_name}: #{parsed.errors.first}" unless parsed.errors.empty?
+    # Replaces the speaker notes. If the slide has no notes page yet, one is
+    # created from the presentation's notes master.
+    #
+    # @param new_text [String]
+    # @return [String]
+    # @raise [Rbpptx::Error] if a notes page must be created but the
+    #   presentation has no notes master, or the notes page has no body
+    #   placeholder
+    def notes=(new_text)
+      ns = notes_slide
+      unless ns
+        raise Error, "#{@part_name}: cannot create a notes slide without a presentation" unless @presentation
+
+        ns = @presentation.create_notes_slide_for(self)
+        @notes_slide = ns
+      end
+      ns.text = new_text
+    end
+
+    # @return [Boolean] whether this slide or its notes page has been mutated
+    #   since load or the last save
+    def dirty?
+      super || (defined?(@notes_slide) && @notes_slide&.dirty?) || false
+    end
+
+    # @api private
+    def clear_dirty!
+      @notes_slide&.clear_dirty! if defined?(@notes_slide)
+      super
+    end
+  end
+
+  # The notes page (+<p:notes>+) attached to a {Slide}.
+  class NotesSlide < SlidePart
+    # @return [Shape, nil] the body placeholder that holds the speaker notes
+    def notes_placeholder
+      shapes.find { |s| s.placeholder_type == :body }
+    end
 
-      parsed
+    # @return [String] the speaker notes text (+""+ if there is no body
+    #   placeholder)
+    def text
+      notes_placeholder&.text || ""
     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) }
+    # @param new_text [String]
+    # @return [String]
+    # @raise [Rbpptx::Error] if the notes page has no body placeholder
+    def text=(new_text)
+      ph = notes_placeholder or raise Error, "#{@part_name}: notes slide has no body placeholder"
+      ph.text = new_text
     end
   end
 end

data/lib/rbpptx/table.rb

@@ -0,0 +1,106 @@
+module Rbpptx
+  # A table: a +<p:graphicFrame>+ whose graphic data is an +<a:tbl>+.
+  #
+  # Only cell text is exposed. Grid geometry, table styles, borders and fills
+  # are left untouched; adding or removing rows and columns is out of scope.
+  #
+  #   table = slide.tables.first
+  #   table.cell(0, 1).text            # => "Q2"
+  #   table.cell(1, 1).text = "42"
+  #   table.rows.map { |r| r.cells.map(&:text) }
+  class Table
+    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:graphicFrame>+ element
+    # @param slide [Slide, NotesSlide, nil] owning part
+    def initialize(node:, slide: nil)
+      @node = node
+      @slide = slide
+      @tbl = node.at_xpath("./a:graphic/a:graphicData/a:tbl", "a" => A_NS)
+    end
+
+    # @return [String, nil] value of +<p:nvGraphicFramePr>/<p:cNvPr name>+
+    def name
+      @node.at_xpath("./p:nvGraphicFramePr/p:cNvPr/@name", "p" => P_NS)&.value
+    end
+
+    # @return [Array<TableRow>]
+    def rows
+      @tbl.xpath("./a:tr", "a" => A_NS).map { |tr| TableRow.new(node: tr, slide: @slide) }
+    end
+
+    # @return [Integer]
+    def row_count
+      @tbl.xpath("./a:tr", "a" => A_NS).size
+    end
+
+    # @return [Integer] number of grid columns (+<a:tblGrid>/<a:gridCol>+)
+    def column_count
+      @tbl.xpath("./a:tblGrid/a:gridCol", "a" => A_NS).size
+    end
+
+    # @param row [Integer] zero-based row index
+    # @param col [Integer] zero-based column index
+    # @return [TableCell, nil] +nil+ when out of range
+    def cell(row, col)
+      rows[row]&.cells&.[](col)
+    end
+  end
+
+  # A table row (+<a:tr>+).
+  class TableRow
+    A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main".freeze
+
+    def initialize(node:, slide: nil)
+      @node = node
+      @slide = slide
+    end
+
+    # @return [Array<TableCell>] one per grid column, including cells that
+    #   are covered by a horizontal or vertical merge (see
+    #   {TableCell#spanned?})
+    def cells
+      @node.xpath("./a:tc", "a" => A_NS).map { |tc| TableCell.new(node: tc, slide: @slide) }
+    end
+  end
+
+  # A table cell (+<a:tc>+). Text access is identical to {Shape}; see
+  # {TextBody}.
+  class TableCell
+    include TextBody
+
+    A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main".freeze
+
+    def initialize(node:, slide: nil)
+      @node = node
+      @slide = slide
+    end
+
+    # @return [Boolean] whether this cell is the top-left origin of a merged
+    #   range (+gridSpan+ or +rowSpan+ greater than 1)
+    def merge_origin?
+      @node["gridSpan"].to_i > 1 || @node["rowSpan"].to_i > 1
+    end
+
+    # @return [Boolean] whether this cell is hidden under a merged range
+    #   (+hMerge+ or +vMerge+ set). PowerPoint does not render its text.
+    def spanned?
+      truthy?(@node["hMerge"]) || truthy?(@node["vMerge"])
+    end
+
+    private
+
+    def truthy?(value)
+      value == "1" || value == "true"
+    end
+
+    def text_body_node
+      @node.at_xpath("./a:txBody", "a" => A_NS)
+    end
+
+    def text_body_label
+      "table cell has no <a:txBody>"
+    end
+  end
+end

data/lib/rbpptx/text_body.rb

@@ -0,0 +1,92 @@
+require "cgi"
+
+module Rbpptx
+  # Text access shared by everything that owns a DrawingML text body:
+  # {Shape} (+<p:txBody>+) and {TableCell} (+<a:txBody>+).
+  #
+  # Including classes provide a private +text_body_node+ returning the text
+  # body element (or +nil+), a private +text_body_label+ used in error
+  # messages, and an +@slide+ owner that responds to +mark_dirty!+.
+  module TextBody
+    A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main".freeze
+
+    # @return [Array<Paragraph>] paragraphs in the text body, in document
+    #   order. Returns +[]+ when there is no text body.
+    def paragraphs
+      txbody = text_body_node
+      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 text body, flattened across
+    #   paragraphs in document order
+    def runs
+      paragraphs.flat_map(&:runs)
+    end
+
+    # Concatenated text of the 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 text body. Lines (separated by +"\n"+) become individual
+    # +<a:p>+ paragraphs. Template formatting carries through:
+    #
+    # * run properties from the first existing +<a:rPr>+ (font, size, color,
+    #   language) are cloned onto each new run. When the body has no runs —
+    #   an empty form field or table cell — the first +<a:endParaRPr>+ is
+    #   used instead, since that is where PowerPoint keeps the formatting
+    #   of an empty paragraph;
+    # * the first paragraph's +<a:pPr>+ (alignment, indent, bullets) and
+    #   +<a:endParaRPr>+ are cloned onto each new paragraph.
+    #
+    # This is the bulldozer-level setter; to preserve individual run
+    # formatting use {#runs} and {Run#text=} instead.
+    #
+    # @param new_text [String]
+    # @return [String] the value that was set
+    # @raise [Rbpptx::Error] if there is no text body
+    def text=(new_text)
+      txbody = text_body_node
+      raise Error, "#{text_body_label}; cannot set text" unless txbody
+
+      template_rpr = txbody.at_xpath(".//a:r/a:rPr", "a" => A_NS)
+      first_p = txbody.at_xpath("./a:p", "a" => A_NS)
+      template_ppr = first_p&.at_xpath("./a:pPr", "a" => A_NS)
+      template_end = first_p&.at_xpath("./a:endParaRPr", "a" => A_NS)
+      template_rpr ||= txbody.at_xpath(".//a:p/a:endParaRPr", "a" => A_NS)&.dup&.tap { |n| n.name = "rPr" }
+      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))
+
+      txbody.xpath("./a:p", "a" => A_NS).each do |para|
+        para.prepend_child(template_ppr.dup) if template_ppr
+        para.add_child(template_end.dup) if template_end
+        next unless template_rpr
+
+        para.xpath("./a:r", "a" => A_NS).each { |run| run.prepend_child(template_rpr.dup) }
+      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/version.rb

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

data/lib/rbpptx.rb

@@ -2,9 +2,13 @@ require "nokogiri"
 require "zip"
 
 require_relative "rbpptx/errors"
+require_relative "rbpptx/package"
+require_relative "rbpptx/text_body"
 require_relative "rbpptx/run"
 require_relative "rbpptx/paragraph"
+require_relative "rbpptx/shape_container"
 require_relative "rbpptx/shape"
+require_relative "rbpptx/table"
 require_relative "rbpptx/slide"
 require_relative "rbpptx/presentation"
 require_relative "rbpptx/version"

data/sig/rbpptx.rbs

@@ -29,51 +29,189 @@ module Rbpptx
     P_NS: String
     A_NS: String
     R_NS: String
+    P14_NS: String
     PKG_REL_NS: String
     OFFICE_DOC_REL_TYPE: String
     SLIDE_REL_TYPE: String
+    NOTES_SLIDE_REL_TYPE: String
+    NOTES_MASTER_REL_TYPE: String
+    NOTES_SLIDE_CONTENT_TYPE: String
+    LEGACY_PPT_SIGNATURE: String
+    ZIP_SIGNATURE: String
 
     attr_reader path: String
 
     def self.open: (pathish path) -> Presentation
     def initialize: (pathish path) -> void
     def slides: () -> Array[Slide]
+    def slide: (Integer index) -> Slide
+    def move_slide: (Slide | Integer slide_or_index, Integer new_index) -> Array[Slide]
+    def delete_slide: (Slide | Integer slide_or_index, ?unlink: bool) -> Slide
     def save: (pathish path) -> String
     def close: () -> bool
     def closed?: () -> bool
+    def create_notes_slide_for: (Slide slide) -> NotesSlide
   end
 
-  class Slide
+  # @api private
+  class Package
+    PKG_REL_NS: String
+    CT_NS: String
+    CONTENT_TYPES_PART: String
+    SAVE_OPTIONS: Integer
+
+    class Relationship < Struct[untyped]
+      attr_accessor id: String
+      attr_accessor type: String
+      attr_accessor target: String
+      attr_accessor part: String?
+      attr_accessor external: bool
+    end
+
+    attr_reader path: String
+
+    def initialize: (String path) -> void
+    def close: () -> void
+    def part?: (String name) -> bool
+    def part_names: () -> Array[String]
+    def xml: (String name, ?error_class: singleton(Error)) -> untyped
+    def touch: (String name) -> true
+    def add: (String name, untyped doc) -> untyped
+    def delete: (String name) -> void
+    def rels_part_for: (String part) -> String
+    def relationships: (String part) -> Array[Relationship]
+    def related: (String part, String rel_type) -> Array[String]
+    def referrers_of: (String target_part) -> Array[String]
+    def add_relationship: (String source, String rel_type, String target_part) -> String
+    def remove_relationship: (String source, String rid) -> void
+    def resolve: (String source, String target) -> String
+    def relative_target: (String source, String target_part) -> String
+    def add_content_type_override: (String part, String content_type) -> void
+    def remove_content_type_override: (String part) -> void
+    def save: (String out_path) -> String
+  end
+
+  interface _DirtyTracking
+    def mark_dirty!: () -> bool
+  end
+
+  module TextBody
+    A_NS: String
+
+    def paragraphs: () -> Array[Paragraph]
+    def runs: () -> Array[Run]
+    def text: () -> String
+    def text=: (String new_text) -> String
+  end
+
+  module ShapeContainer
     P_NS: String
+    A_NS: String
+
+    def shapes: () -> Array[Shape]
+    def groups: () -> Array[GroupShape]
+    def tables: () -> Array[Table]
+    def all_shapes: () -> Array[Shape]
+    def all_tables: () -> Array[Table]
+  end
+
+  class SlidePart
+    include ShapeContainer
 
     attr_reader part_name: String
 
-    def initialize: (zip: untyped, part_name: String) -> void
-    def name: () -> String
-    def shapes: () -> Array[Shape]
+    def initialize: (package: Package, part_name: String) -> void
+    def placeholders: () -> Placeholders
     def dirty?: () -> bool
     def mark_dirty!: () -> bool
     def clear_dirty!: () -> bool
     def to_xml: () -> String
   end
 
+  class Slide < SlidePart
+    NOTES_SLIDE_REL_TYPE: String
+
+    def initialize: (package: Package, part_name: String, ?presentation: Presentation?) -> void
+    def name: () -> String
+    def title: () -> Shape?
+    def notes_slide: () -> NotesSlide?
+    def notes: () -> String
+    def notes=: (String new_text) -> String
+  end
+
+  class NotesSlide < SlidePart
+    def notes_placeholder: () -> Shape?
+    def text: () -> String
+    def text=: (String new_text) -> String
+  end
+
   class Shape
+    include TextBody
+
     P_NS: String
     A_NS: String
 
-    def initialize: (node: untyped, ?slide: Slide?) -> void
+    def initialize: (node: untyped, ?slide: _DirtyTracking?) -> void
     def name: () -> String?
+    def placeholder?: () -> bool
     def placeholder_type: () -> Symbol?
-    def paragraphs: () -> Array[Paragraph]
-    def runs: () -> Array[Run]
+    def placeholder_idx: () -> Integer?
+  end
+
+  class GroupShape
+    include ShapeContainer
+
+    def initialize: (node: untyped, ?slide: _DirtyTracking?) -> void
+    def name: () -> String?
     def text: () -> String
-    def text=: (String new_text) -> String
+  end
+
+  class Placeholders
+    include Enumerable[Shape]
+
+    def initialize: (Array[Shape] shapes) -> void
+    def each: () { (Shape) -> void } -> self
+            | () -> Enumerator[Shape, self]
+    def []: (Symbol | Integer key) -> Shape?
+    def size: () -> Integer
+    def length: () -> Integer
+    def empty?: () -> bool
+    def to_a: () -> Array[Shape]
+  end
+
+  class Table
+    P_NS: String
+    A_NS: String
+
+    def initialize: (node: untyped, ?slide: _DirtyTracking?) -> void
+    def name: () -> String?
+    def rows: () -> Array[TableRow]
+    def row_count: () -> Integer
+    def column_count: () -> Integer
+    def cell: (Integer row, Integer col) -> TableCell?
+  end
+
+  class TableRow
+    A_NS: String
+
+    def initialize: (node: untyped, ?slide: _DirtyTracking?) -> void
+    def cells: () -> Array[TableCell]
+  end
+
+  class TableCell
+    include TextBody
+
+    A_NS: String
+
+    def initialize: (node: untyped, ?slide: _DirtyTracking?) -> void
+    def merge_origin?: () -> bool
+    def spanned?: () -> bool
   end
 
   class Paragraph
     A_NS: String
 
-    def initialize: (node: untyped, ?slide: Slide?) -> void
+    def initialize: (node: untyped, ?slide: _DirtyTracking?) -> void
     def runs: () -> Array[Run]
     def text: () -> String
   end
@@ -81,7 +219,7 @@ module Rbpptx
   class Run
     A_NS: String
 
-    def initialize: (node: untyped, ?slide: Slide?) -> void
+    def initialize: (node: untyped, ?slide: _DirtyTracking?) -> void
     def text: () -> String
     def text=: (String new_text) -> String
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbpptx
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Taro KOBAYASHI
@@ -13,16 +13,22 @@ dependencies:
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -57,11 +63,15 @@ files:
 - Rakefile
 - lib/rbpptx.rb
 - lib/rbpptx/errors.rb
+- lib/rbpptx/package.rb
 - lib/rbpptx/paragraph.rb
 - lib/rbpptx/presentation.rb
 - lib/rbpptx/run.rb
 - lib/rbpptx/shape.rb
+- lib/rbpptx/shape_container.rb
 - lib/rbpptx/slide.rb
+- lib/rbpptx/table.rb
+- lib/rbpptx/text_body.rb
 - lib/rbpptx/version.rb
 - sig/rbpptx.rbs
 homepage: https://github.com/matzlika/rbpptx