ruby_pptx 0.1.0

data/lib/ruby_pptx/oxml/slide.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/oxml/element"
+require "ruby_pptx/oxml/content_model"
+require "ruby_pptx/oxml/simple_types"
+require "ruby_pptx/oxml/ns"
+
+module Pptx
+  module Oxml
+    # Reads one of the XML templates shipped with the gem, e.g. "notes".
+    def self.parse_from_template(name)
+      path = File.expand_path("../templates/#{name}.xml", __dir__)
+      Element.parse(File.read(path))
+    end
+
+    # Behaviour common to the six slide-like root elements.
+    module BaseSlideElement
+      # The `p:cSld/p:spTree` grandchild every slide type has.
+      def spTree = cSld.spTree
+    end
+
+    # `p:cSld`, the common slide data holding the shape tree.
+    class CT_CommonSlideData < Element
+      tag "p:cSld"
+      zero_or_one "p:bg", successors: %w[p:spTree p:custDataLst p:controls p:extLst]
+      one_and_only_one "p:spTree"
+      optional_attr "name", type: SimpleTypes::XsdString, default: ""
+
+      # The `p:bg/p:bgPr` grandchild, establishing a no-fill background first
+      # if there is not already an explicit one.
+      #
+      # This is destructive by nature: a background given by a style reference
+      # (`p:bgRef`) is replaced, and an inherited background stops being
+      # inherited. python-pptx behaves the same way.
+      def get_or_add_bgPr
+        background = bg
+        background = change_to_no_fill_bg if background.nil? || background.bgPr.nil?
+        background.bgPr
+      end
+
+      private
+
+      def change_to_no_fill_bg
+        remove_bg
+        get_or_add_bg.tap(&:add_no_fill_bgPr)
+      end
+    end
+
+    # `p:bg`, a slide background.
+    class CT_Background < Element
+      tag "p:bg"
+      # Strictly a choice rather than a sequence, but treating it as two
+      # optional children is simpler and behaves the same here.
+      zero_or_one "p:bgPr", successors: []
+      zero_or_one "p:bgRef", successors: []
+
+      def add_no_fill_bgPr
+        bgPr = build_from_xml(
+          %(<p:bgPr #{Ns.nsdecls("a", "p")}><a:noFill/><a:effectLst/></p:bgPr>)
+        )
+        insert_bgPr(bgPr)
+        bgPr
+      end
+    end
+
+    # `p:bgPr`, explicit background fill properties.
+    class CT_BackgroundProperties < Element
+      tag "p:bgPr"
+      FILL_SUCCESSORS = %w[a:effectLst a:effectDag a:extLst].freeze
+
+      zero_or_one_choice [choice("a:noFill"), choice("a:solidFill"), choice("a:gradFill"),
+                          choice("a:blipFill"), choice("a:pattFill"), choice("a:grpFill")],
+                         successors: FILL_SUCCESSORS, as: :eg_fillProperties
+
+      # A new gradient starts from PowerPoint's default rather than empty; an
+      # `a:gradFill` with no stops draws nothing.
+      def new_gradFill = CT_GradientFillProperties.new_grad_fill(self)
+    end
+
+    # `p:sld`, the root of a slide part.
+    class CT_Slide < Element
+      include BaseSlideElement
+
+      tag "p:sld"
+      one_and_only_one "p:cSld"
+      zero_or_one "p:clrMapOvr", successors: %w[p:transition p:timing p:extLst]
+      zero_or_one "p:timing", successors: %w[p:extLst]
+
+      # A new, empty `p:sld` with the minimum structure PowerPoint requires.
+      def self.new_element = Element.parse(SLD_XML)
+
+      def bg = cSld.bg
+
+      # The node list a `p:video` entry hangs off, which is what makes
+      # PowerPoint show play controls under a movie.
+      #
+      # The precondition varies -- a slide may have no timing at all, or one
+      # already -- so an awkward case is replaced wholesale rather than
+      # patched. That can in principle discard existing timing information;
+      # python-pptx takes the same view.
+      def get_or_add_child_time_node_list
+        existing = xpath("./p:timing/p:tnLst/p:par/p:cTn/p:childTnLst").first
+        return existing if existing
+
+        remove(get_or_add_timing)
+        timing = build_from_xml(TIMING_XML)
+        insert_timing(timing)
+        timing.xpath("./p:tnLst/p:par/p:cTn/p:childTnLst").first
+      end
+
+      TIMING_XML = <<~XML.freeze
+        <p:timing #{Ns.nsdecls("p")}>
+          <p:tnLst>
+            <p:par>
+              <p:cTn id="1" dur="indefinite" restart="never" nodeType="tmRoot">
+                <p:childTnLst/>
+              </p:cTn>
+            </p:par>
+          </p:tnLst>
+        </p:timing>
+      XML
+
+      SLD_XML = <<~XML.freeze
+        <p:sld #{Ns.nsdecls("a", "p", "r")}>
+          <p:cSld>
+            <p:spTree>
+              <p:nvGrpSpPr>
+                <p:cNvPr id="1" name=""/>
+                <p:cNvGrpSpPr/>
+                <p:nvPr/>
+              </p:nvGrpSpPr>
+              <p:grpSpPr/>
+            </p:spTree>
+          </p:cSld>
+          <p:clrMapOvr>
+            <a:masterClrMapping/>
+          </p:clrMapOvr>
+        </p:sld>
+      XML
+    end
+
+    # `p:sldLayout`, the root of a slide-layout part.
+    class CT_SlideLayout < Element
+      include BaseSlideElement
+
+      tag "p:sldLayout"
+      one_and_only_one "p:cSld"
+      zero_or_one "p:clrMapOvr", successors: %w[p:transition p:timing p:hf p:extLst]
+      optional_attr "type", type: SimpleTypes::ST_SlideLayoutType
+      optional_attr "preserve", type: SimpleTypes::XsdBoolean
+
+      # A new `p:sldLayout` named +name+, inheriting its colour map from the
+      # master. `preserve` is set because a layout with no slides using it is
+      # otherwise discarded by PowerPoint when it tidies up.
+      def self.new_element(name, layout_type)
+        layout = Element.parse(SLD_LAYOUT_XML)
+        layout.cSld.name = name
+        layout.type = layout_type unless layout_type.nil?
+        layout
+      end
+
+      SLD_LAYOUT_XML = <<~XML.freeze
+        <p:sldLayout #{Ns.nsdecls("a", "p", "r")} preserve="1">
+          <p:cSld>
+            <p:spTree>
+              <p:nvGrpSpPr>
+                <p:cNvPr id="1" name=""/>
+                <p:cNvGrpSpPr/>
+                <p:nvPr/>
+              </p:nvGrpSpPr>
+              <p:grpSpPr/>
+            </p:spTree>
+          </p:cSld>
+          <p:clrMapOvr>
+            <a:masterClrMapping/>
+          </p:clrMapOvr>
+        </p:sldLayout>
+      XML
+    end
+
+    # `p:sldMaster`, the root of a slide-master part.
+    class CT_SlideMaster < Element
+      include BaseSlideElement
+
+      tag "p:sldMaster"
+      one_and_only_one "p:cSld"
+      one_and_only_one "p:clrMap"
+      zero_or_one "p:sldLayoutIdLst",
+                  successors: %w[p:transition p:timing p:hf p:txStyles p:extLst]
+      zero_or_one "p:txStyles", successors: %w[p:extLst]
+
+      # A new `p:sldMaster` carrying the colour map and text styles a master
+      # cannot do without, an empty shape tree and no layouts.
+      def self.new_element = Oxml.parse_from_template("slideMaster")
+    end
+
+    # `p:clrMap`, which binds each of a slide's colour roles to a theme colour.
+    class CT_ColorMapping < Element
+      tag "p:clrMap"
+      ROLES = %w[bg1 tx1 bg2 tx2 accent1 accent2 accent3 accent4 accent5
+                 accent6 hlink folHlink].freeze
+      ROLES.each { |role| required_attr role, type: SimpleTypes::XsdString }
+    end
+
+    # `p:txStyles`, the master's default text styling per outline level.
+    class CT_SlideMasterTextStyles < Element
+      tag "p:txStyles"
+      zero_or_one "p:titleStyle", successors: %w[p:bodyStyle p:otherStyle p:extLst]
+      zero_or_one "p:bodyStyle", successors: %w[p:otherStyle p:extLst]
+      zero_or_one "p:otherStyle", successors: %w[p:extLst]
+    end
+
+    # `p:sldLayoutIdLst`, the layouts inheriting from a slide master.
+    class CT_SlideLayoutIdList < Element
+      tag "p:sldLayoutIdLst"
+      zero_or_more "p:sldLayoutId", as: :sldLayoutId
+
+      def size = sldLayoutId_list.size
+    end
+
+    # `p:sldLayoutId`, a reference to one slide layout.
+    class CT_SlideLayoutIdListEntry < Element
+      tag "p:sldLayoutId"
+      required_attr "r:id", type: SimpleTypes::XsdString, as: :rId
+      optional_attr "id", type: SimpleTypes::ST_SlideLayoutId
+    end
+
+    # `p:notesMaster`, the root of the notes-master part.
+    class CT_NotesMaster < Element
+      include BaseSlideElement
+
+      tag "p:notesMaster"
+      one_and_only_one "p:cSld"
+
+      def self.new_default = Oxml.parse_from_template("notesMaster")
+    end
+
+    # `p:notes`, the root of a notes-slide part.
+    #
+    # The template carries no placeholders; those are cloned from the notes
+    # master once the shape layer exists.
+    class CT_NotesSlide < Element
+      include BaseSlideElement
+
+      tag "p:notes"
+      one_and_only_one "p:cSld"
+
+      def self.new_element = Oxml.parse_from_template("notes")
+    end
+
+    # `p:timing`, animation and timing information.
+    class CT_SlideTiming < Element
+      tag "p:timing"
+      zero_or_one "p:tnLst", successors: %w[p:bldLst p:extLst]
+    end
+
+    # `p:tnLst` and `p:childTnLst`, lists of timing nodes.
+    class CT_TimeNodeList < Element
+      tag "p:tnLst", "p:childTnLst"
+
+      # Register the movie with shape id +shape_id+ so its play controls
+      # appear.
+      def add_video(shape_id)
+        append(build_from_xml(<<~XML))
+          <p:video #{Ns.nsdecls("p")}>
+            <p:cMediaNode vol="80000">
+              <p:cTn id="#{next_time_node_id}" fill="hold" display="0">
+                <p:stCondLst>
+                  <p:cond delay="indefinite"/>
+                </p:stCondLst>
+              </p:cTn>
+              <p:tgtEl>
+                <p:spTgt spid="#{shape_id}"/>
+              </p:tgtEl>
+            </p:cMediaNode>
+          </p:video>
+        XML
+        self
+      end
+
+      private
+
+      # Timing node ids are scoped to the slide, so every existing one counts.
+      def next_time_node_id
+        used = xpath("/p:sld/p:timing//p:cTn/@id").map { |attr| attr.value.to_i }
+        (used.max || 0) + 1
+      end
+    end
+  end
+end

data/lib/ruby_pptx/oxml/table.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/oxml/element"
+require "ruby_pptx/oxml/content_model"
+require "ruby_pptx/oxml/simple_types"
+require "ruby_pptx/oxml/text"
+require "ruby_pptx/enum/text"
+
+module Pptx
+  module Oxml
+    # `a:gridCol`, one column of the table grid.
+    class CT_TableCol < Element
+      tag "a:gridCol"
+      required_attr "w", type: SimpleTypes::ST_Coordinate
+    end
+
+    # `a:tblGrid`, the column widths of a table.
+    class CT_TableGrid < Element
+      tag "a:tblGrid"
+      zero_or_more "a:gridCol", as: :gridCol
+
+      def add_grid_col(width) = add_gridCol(w: width)
+    end
+
+    # `a:tblPr`, whole-table properties such as banding and header rows.
+    class CT_TableProperties < Element
+      tag "a:tblPr"
+      %w[bandRow bandCol firstRow firstCol lastRow lastCol].each do |name|
+        optional_attr name, type: SimpleTypes::XsdBoolean, default: false
+      end
+    end
+
+    # `a:tcPr`, the properties of one cell.
+    class CT_TableCellProperties < Element
+      tag "a:tcPr"
+      FILL_SUCCESSORS = %w[a:headers a:extLst].freeze
+
+      zero_or_one_choice Oxml::FILL_CHOICES.map { |t| choice(t) },
+                         successors: FILL_SUCCESSORS, as: :eg_fillProperties
+      optional_attr "anchor", type: Enum::MSO_VERTICAL_ANCHOR
+      optional_attr "marL", type: SimpleTypes::ST_Coordinate32, default: Pptx::Length.emu(91_440)
+      optional_attr "marR", type: SimpleTypes::ST_Coordinate32, default: Pptx::Length.emu(91_440)
+      optional_attr "marT", type: SimpleTypes::ST_Coordinate32, default: Pptx::Length.emu(45_720)
+      optional_attr "marB", type: SimpleTypes::ST_Coordinate32, default: Pptx::Length.emu(45_720)
+
+      # A new gradient starts from PowerPoint's default rather than empty; an
+      # `a:gradFill` with no stops draws nothing.
+      def new_gradFill = CT_GradientFillProperties.new_grad_fill(self)
+    end
+
+    # `a:tc`, one cell of a table.
+    class CT_TableCell < Element
+      tag "a:tc"
+      zero_or_one "a:txBody", successors: %w[a:tcPr a:extLst]
+      zero_or_one "a:tcPr", successors: %w[a:extLst]
+      optional_attr "gridSpan", type: SimpleTypes::XsdInt, default: 1
+      optional_attr "rowSpan", type: SimpleTypes::XsdInt, default: 1
+      optional_attr "hMerge", type: SimpleTypes::XsdBoolean, default: false
+      optional_attr "vMerge", type: SimpleTypes::XsdBoolean, default: false
+
+      CELL_XML = <<~XML.freeze
+        <a:tc #{Ns.nsdecls("a")}>
+          <a:txBody>
+            <a:bodyPr/>
+            <a:lstStyle/>
+            <a:p/>
+          </a:txBody>
+          <a:tcPr/>
+        </a:tc>
+      XML
+
+      # A cell always has a text body, so a new one is created with it rather
+      # than empty.
+      def self.new_cell(context) = context.build_from_xml(CELL_XML)
+
+      # The `a:tr` this cell sits in.
+      def tr = parent
+
+      # The `a:tbl` this cell belongs to.
+      def tbl = tr.parent
+
+      def col_idx = tr.tc_list.index(self)
+
+      def row_idx = tbl.tr_list.index(tr)
+
+      # True when this is the top-left cell of a merged range.
+      #
+      # Only the origin carries the full span; the cells it covers are marked
+      # hMerge or vMerge and keep spans of 1.
+      def merge_origin?
+        return true if gridSpan > 1 && !vMerge
+
+        rowSpan > 1 && !hMerge
+      end
+
+      # True when this cell is covered by a merge rather than being its origin.
+      def spanned? = hMerge || vMerge
+
+      # Take the paragraphs from +other+ into this cell's text body.
+      #
+      # An empty source contributes nothing; a single empty paragraph in the
+      # target is replaced rather than appended to; and the source is left with
+      # one empty paragraph, since the schema requires at least one.
+      def append_paragraphs_from(other)
+        source = other.get_or_add_txBody
+        target = get_or_add_txBody
+        return self if source.empty?
+
+        target.clear_content if target.empty?
+        source.p_list.each { |paragraph| target.append(paragraph) }
+        source.unclear_content
+        self
+      end
+    end
+
+    # `a:tr`, one row of a table.
+    class CT_TableRow < Element
+      tag "a:tr"
+      zero_or_more "a:tc", successors: %w[a:extLst], as: :tc
+      required_attr "h", type: SimpleTypes::ST_Coordinate
+
+      def new_tc = CT_TableCell.new_cell(self)
+
+      def add_cell = add_tc
+    end
+
+    # `a:tbl`, a table.
+    class CT_Table < Element
+      tag "a:tbl"
+      zero_or_one "a:tblPr", successors: %w[a:tblGrid a:tr]
+      one_and_only_one "a:tblGrid"
+      zero_or_more "a:tr", successors: [], as: :tr
+
+      # The style PowerPoint applies to a table created through the UI.
+      DEFAULT_TABLE_STYLE_ID = "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}"
+
+      def self.tbl_xml(table_style_id)
+        <<~XML
+          <a:tbl #{Ns.nsdecls("a")}>
+            <a:tblPr firstRow="1" bandRow="1">
+              <a:tableStyleId>#{table_style_id}</a:tableStyleId>
+            </a:tblPr>
+            <a:tblGrid/>
+          </a:tbl>
+        XML
+      end
+
+      # A new `a:tbl` of +rows+ by +cols+ filling the given width and height.
+      #
+      # The width is divided evenly between columns and the height between
+      # rows; the last of each absorbs the rounding remainder so the totals
+      # come out exactly.
+      def self.new_tbl(context, rows, cols, width, height, table_style_id = DEFAULT_TABLE_STYLE_ID)
+        width = Pptx::Length.coerce(width).emu
+        height = Pptx::Length.coerce(height).emu
+        tbl = context.build_from_xml(tbl_xml(table_style_id))
+
+        col_width = width / cols
+        cols.times do |col|
+          this_width = col == cols - 1 ? width - ((cols - 1) * col_width) : col_width
+          tbl.tblGrid.add_grid_col(Pptx::Length.emu(this_width))
+        end
+
+        row_height = height / rows
+        rows.times do |row|
+          this_height = row == rows - 1 ? height - ((rows - 1) * row_height) : row_height
+          tr = tbl.add_tr(h: Pptx::Length.emu(this_height))
+          cols.times { tr.add_cell }
+        end
+
+        tbl
+      end
+
+      # The cell at +row_idx+, +col_idx+.
+      def tc(row_idx, col_idx) = tr_list[row_idx].tc_list[col_idx]
+
+      # The rectangle of cells spanned by the two opposite corners +a+ and +b+.
+      #
+      # The corners may be given in either order and along either diagonal, so
+      # the extents are normalised here.
+      def cell_range(a, b)
+        top, bottom = [a.row_idx, b.row_idx].minmax
+        left, right = [a.col_idx, b.col_idx].minmax
+        CellRange.new(self, top, left, bottom, right)
+      end
+
+      %w[firstRow firstCol lastRow lastCol bandRow bandCol].each do |name|
+        define_method(name) { tblPr ? tblPr.public_send(name) : false }
+
+        define_method("#{name}=") do |value|
+          get_or_add_tblPr.public_send("#{name}=", value)
+          value
+        end
+      end
+    end
+
+    # A rectangular block of `a:tc` elements, used when merging and splitting.
+    #
+    # It assumes the table's structure does not change while it is alive, so
+    # create one, use it, and let it go.
+    class CellRange
+      attr_reader :row_count, :column_count
+
+      def initialize(tbl, top, left, bottom, right)
+        @tbl = tbl
+        @top = top
+        @left = left
+        @bottom = bottom
+        @right = right
+        @row_count = bottom - top + 1
+        @column_count = right - left + 1
+      end
+
+      # The range a merge-origin cell already covers.
+      def self.from_merge_origin(tc)
+        tc.tbl.cell_range(tc, tc.tbl.tc(tc.row_idx + tc.rowSpan - 1,
+                                        tc.col_idx + tc.gridSpan - 1))
+      end
+
+      # Every cell in the range, left to right then top to bottom.
+      def cells
+        (@top..@bottom).flat_map { |row| (@left..@right).map { |col| @tbl.tc(row, col) } }
+      end
+
+      def top_row_cells = (@left..@right).map { |col| @tbl.tc(@top, col) }
+
+      def left_column_cells = (@top..@bottom).map { |row| @tbl.tc(row, @left) }
+
+      def cells_except_left_column
+        (@top..@bottom).flat_map { |row| ((@left + 1)..@right).map { |col| @tbl.tc(row, col) } }
+      end
+
+      def cells_except_top_row
+        ((@top + 1)..@bottom).flat_map { |row| (@left..@right).map { |col| @tbl.tc(row, col) } }
+      end
+
+      # True when any cell in the range is already part of a merge. Merging
+      # over an existing merge would produce a table PowerPoint cannot lay out.
+      def contains_merged_cell?
+        cells.any? { |tc| tc.gridSpan > 1 || tc.rowSpan > 1 || tc.hMerge || tc.vMerge }
+      end
+
+      # Gather the text of the whole range into its top-left cell, which is
+      # the one that stays visible.
+      def move_content_to_origin
+        all = cells
+        origin = all.first
+        all.drop(1).each { |spanned| origin.append_paragraphs_from(spanned) }
+        origin
+      end
+    end
+  end
+end