ruby_pptx 0.1.0

data/lib/ruby_pptx/chart/xy_data.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/chart/data"
+
+module Pptx
+  # Data for a scatter chart: series of (x, y) points.
+  #
+  #   data = Pptx::XyChartData.new
+  #   data.add_series("Alpha") do |s|
+  #     s.add_point(1, 10)
+  #     s.add_point(2, 20)
+  #   end
+  #
+  # Unlike a category chart, each series has its own x values, so the
+  # worksheet stacks the series in blocks rather than putting them side by
+  # side in shared columns.
+  class XyChartData
+    include Enumerable
+
+    WORKSHEET_NAME = "Sheet1"
+    DEFAULT_NUMBER_FORMAT = "General"
+    # Each series block is followed by a blank row, and preceded by its title
+    # row -- two rows of overhead per series.
+    ROWS_PER_SERIES_OVERHEAD = 2
+
+    attr_reader :series, :number_format
+
+    def initialize(number_format: DEFAULT_NUMBER_FORMAT)
+      @series = []
+      @number_format = number_format
+    end
+
+    # Add a series. Points may be given up front, added in a block, or both.
+    #
+    # @param points [Array<Array>] each [x, y]
+    # @return [XySeries]
+    def add_series(name, points: [], number_format: nil)
+      series = series_class.new(self, @series.size, name, number_format || @number_format)
+      @series << series
+      points.each { |point| series.add_point(*point) }
+      yield series if block_given?
+      series
+    end
+
+    def each(&) = @series.each(&)
+
+    def size = @series.size
+
+    # The row a series' title sits on, counting the blocks before it.
+    #
+    # @api private
+    def title_row(series)
+      preceding_points = @series[0...series.index].sum(&:size)
+      (series.index * ROWS_PER_SERIES_OVERHEAD) + preceding_points + 1
+    end
+
+    # @api private
+    def series_name_ref(series) = "#{WORKSHEET_NAME}!$B$#{title_row(series)}"
+
+    # @api private
+    def x_values_ref(series) = column_ref(series, "A")
+
+    # @api private
+    def y_values_ref(series) = column_ref(series, "B")
+
+    # @api private
+    def column_ref(series, column)
+      first = title_row(series) + 1
+      last = first + [series.size, 1].max - 1
+      "#{WORKSHEET_NAME}!$#{column}$#{first}:$#{column}$#{last}"
+    end
+
+    # @api private
+    def xlsx_blob = XyWorkbookWriter.new(self).blob
+
+    # @api private
+    # Whether the worksheet carries a third column of bubble sizes.
+    def bubble? = false
+
+    def inspect = "#<#{self.class.name} series=#{size}>"
+
+    private
+
+    def series_class = XySeries
+  end
+
+  # Data for a bubble chart: series of (x, y, size) points.
+  class BubbleChartData < XyChartData
+    # @api private
+    def bubble_sizes_ref(series) = column_ref(series, "C")
+
+    # @api private
+    def bubble? = true
+
+    private
+
+    def series_class = BubbleSeries
+  end
+
+  # One series of a scatter chart.
+  class XySeries
+    include Enumerable
+
+    attr_reader :chart_data, :index, :name, :number_format, :points
+
+    def initialize(chart_data, index, name, number_format)
+      @chart_data = chart_data
+      @index = index
+      @name = name
+      @number_format = number_format
+      @points = []
+    end
+
+    # @return [self] so points can be chained
+    def add_point(x, y)
+      @points << [x, y]
+      self
+    end
+
+    def each(&) = @points.each(&)
+
+    def size = @points.size
+
+    def x_values = @points.map(&:first)
+
+    def y_values = @points.map { |point| point[1] }
+
+    def name_ref = @chart_data.series_name_ref(self)
+    def x_values_ref = @chart_data.x_values_ref(self)
+    def y_values_ref = @chart_data.y_values_ref(self)
+
+    def inspect = "#<#{self.class.name} #{@name.inspect} #{size} points>"
+  end
+
+  # One series of a bubble chart, whose points carry a size as well.
+  class BubbleSeries < XySeries
+    def add_point(x, y, size)
+      @points << [x, y, size]
+      self
+    end
+
+    def bubble_sizes = @points.map { |point| point[2] }
+
+    def bubble_sizes_ref = @chart_data.bubble_sizes_ref(self)
+  end
+
+  # Writes the workbook behind a scatter or bubble chart.
+  #
+  # The layout differs from a category chart: each series gets its own block of
+  # rows, since the x values belong to the series rather than being shared.
+  class XyWorkbookWriter < ChartWorkbookWriter
+    private
+
+    def rows_xml
+      @chart_data.series.flat_map { |series| series_rows(series) }.join
+    end
+
+    def series_rows(series)
+      title_row = @chart_data.title_row(series)
+      rows = [title_row_xml(series, title_row)]
+      series.points.each_with_index do |point, offset|
+        rows << point_row_xml(point, title_row + 1 + offset)
+      end
+      rows
+    end
+
+    # Column A is left empty on the title row; the series name sits in B, and
+    # a bubble chart labels its third column.
+    def title_row_xml(series, row)
+      cells = [string_cell("B#{row}", series.name)]
+      cells << string_cell("C#{row}", "Size") if @chart_data.bubble?
+      %(<row r="#{row}">#{cells.join}</row>)
+    end
+
+    def point_row_xml(point, row)
+      cells = point.each_with_index.map do |value, column|
+        number_cell("#{(65 + column).chr}#{row}", value)
+      end
+      %(<row r="#{row}">#{cells.join}</row>)
+    end
+  end
+end

data/lib/ruby_pptx/core_ext.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/numeric_lengths"
+
+# Opt-in numeric sugar: `require "ruby_pptx/core_ext"` to write `1.inch` or `2.5.cm`
+# instead of `Pptx.inches(1)`. Kept out of the default require so the gem does
+# not monkey-patch Numeric behind your back.
+#
+# This patches Numeric for the whole process. `require "ruby_pptx/refinements"` and
+# `using Pptx::Lengths` does the same thing scoped to one file, and is the
+# better choice inside a library.
+Numeric.include(Pptx::NumericLengths)

data/lib/ruby_pptx/dml/color.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/pattern_matching"
+
+require "ruby_pptx/element_proxy"
+require "ruby_pptx/oxml/dml/color"
+require "ruby_pptx/enum/dml"
+
+module Pptx
+  # An RGB colour.
+  #
+  #   Pptx::RGBColor.new(60, 47, 128)
+  #   Pptx::RGBColor["3C2F80"]
+  class RGBColor
+    include PatternMatching
+
+    pattern_keys :r, :g, :b
+
+    attr_reader :r, :g, :b
+
+    # Array patterns too: `in [r, g, b]`.
+    def deconstruct = to_a
+
+    # Parse a hex string such as "3C2F80".
+    def self.from_string(hex)
+      unless /\A\h{6}\z/.match?(hex.to_s)
+        raise ArgumentError, "expected a six-digit hex string, got #{hex.inspect}"
+      end
+
+      new(hex[0, 2].to_i(16), hex[2, 2].to_i(16), hex[4, 2].to_i(16))
+    end
+
+    class << self
+      alias [] from_string
+    end
+
+    def initialize(r, g, b)
+      [r, g, b].each do |component|
+        unless component.is_a?(Integer) && component.between?(0, 255)
+          raise ArgumentError, "RGBColor takes three integers 0-255, got #{[r, g, b].inspect}"
+        end
+      end
+      @r = r
+      @g = g
+      @b = b
+      freeze
+    end
+
+    def to_a = [@r, @g, @b]
+
+    # The uppercase hex form OOXML uses, e.g. "3C2F80".
+    def to_s = format("%02X%02X%02X", @r, @g, @b)
+
+    def ==(other) = other.is_a?(RGBColor) && other.to_a == to_a
+    alias eql? ==
+
+    def hash = to_a.hash
+
+    def inspect = "#<Pptx::RGBColor #{self}>"
+  end
+
+  # The colour of a font, fill or line.
+  #
+  # A colour may be an explicit RGB value, a reference to a theme colour, or
+  # absent -- in which case it is inherited and {#type} is nil.
+  class ColorFormat
+    # @param color_choice_parent [Pptx::Oxml::Element] the element holding the
+    #   colour choice, e.g. `a:solidFill`
+    def self.from_color_choice_parent(color_choice_parent) = new(color_choice_parent)
+
+    def initialize(color_choice_parent)
+      @parent = color_choice_parent
+    end
+
+    # @return [Pptx::Enum::MSO_COLOR_TYPE, nil] nil when no colour is set here
+    def type
+      element = color_element
+      return nil if element.nil?
+
+      case element.nsptag
+      when "a:srgbClr" then Enum::MSO_COLOR_TYPE::RGB
+      when "a:schemeClr" then Enum::MSO_COLOR_TYPE::SCHEME
+      when "a:hslClr" then Enum::MSO_COLOR_TYPE::HSL
+      when "a:prstClr" then Enum::MSO_COLOR_TYPE::PRESET
+      when "a:scrgbClr" then Enum::MSO_COLOR_TYPE::SCRGB
+      when "a:sysClr" then Enum::MSO_COLOR_TYPE::SYSTEM
+      end
+    end
+
+    # @return [RGBColor, nil] nil unless an explicit RGB colour is set
+    def rgb
+      element = color_element
+      return nil unless element&.nsptag == "a:srgbClr"
+
+      RGBColor.from_string(element.val)
+    end
+
+    def rgb=(value)
+      value = RGBColor.from_string(value) if value.is_a?(String)
+      raise TypeError, "expected an RGBColor, got #{value.class}" unless value.is_a?(RGBColor)
+
+      @parent.get_or_change_to_srgbClr.val = value.to_s
+    end
+
+    # @return [Pptx::Enum::MSO_THEME_COLOR, nil] nil unless a theme colour is set
+    def theme_color
+      element = color_element
+      return nil unless element&.nsptag == "a:schemeClr"
+
+      element.val
+    end
+
+    def theme_color=(value)
+      @parent.get_or_change_to_schemeClr.val = Enum::MSO_THEME_COLOR.fetch(value)
+    end
+
+    # A luminance adjustment between -1.0 and 1.0: negative is darker (a
+    # shade), positive is lighter (a tint).
+    def brightness
+      element = color_element
+      return 0.0 if element.nil?
+
+      lum_off = element.lumOff
+      return lum_off.val if lum_off
+
+      lum_mod = element.lumMod
+      return lum_mod.val - 1.0 if lum_mod
+
+      0.0
+    end
+
+    def brightness=(value)
+      unless value.is_a?(Numeric) && value.between?(-1.0, 1.0)
+        raise ArgumentError, "brightness must be a number between -1.0 and 1.0, got #{value.inspect}"
+      end
+
+      element = color_element
+      raise Error, "cannot set brightness before a colour; set rgb or theme_color first" if element.nil?
+
+      element.clear_lum
+      if value.positive?
+        element.add_lumMod(1.0 - value)
+        element.add_lumOff(value)
+      elsif value.negative?
+        element.add_lumMod(1.0 + value)
+      end
+    end
+
+    def inspect = "#<Pptx::ColorFormat type=#{type&.name.inspect} rgb=#{rgb&.to_s.inspect}>"
+
+    private
+
+    def color_element = @parent.eg_colorChoice
+  end
+end

data/lib/ruby_pptx/dml/effect.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pptx
+  # The shadow of a shape.
+  #
+  # Only inheritance can be controlled so far, as in python-pptx: a shape
+  # either takes its shadow from the theme and style hierarchy, or has its
+  # effects switched off explicitly.
+  #
+  #   shape.shadow.inherit = false   # no shadow, whatever the theme says
+  class ShadowFormat
+    # @param shape_properties [Pptx::Oxml::Element] `p:spPr` or `p:grpSpPr`,
+    #   which both carry the `a:effectLst`
+    def initialize(shape_properties)
+      @element = shape_properties
+    end
+
+    # True when the shape takes its shadow from the style hierarchy.
+    def inherit? = @element.effectLst.nil?
+
+    alias inherit inherit?
+
+    # Restore inheritance with true; with false, break it so no effects show.
+    #
+    # Inheritance is all or nothing: restoring it removes every explicit
+    # effect on the shape -- glow and reflection too, not only the shadow.
+    def inherit=(value)
+      value ? @element.remove_effectLst : @element.get_or_add_effectLst
+    end
+
+    def inspect = "#<Pptx::ShadowFormat inherit=#{inherit?}>"
+  end
+end

data/lib/ruby_pptx/dml/fill.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/dml/color"
+require "ruby_pptx/oxml/dml/fill"
+require "ruby_pptx/enum/dml"
+require "ruby_pptx/element_proxy"
+require "ruby_pptx/sliceable"
+
+module Pptx
+  # The fill of a shape, text run, line or slide background.
+  #
+  # A fill starts out inherited -- {#type} is nil and nothing is written.
+  # Calling {#solid}, {#background} or {#gradient} makes it explicit, after
+  # which {#fore_color} and friends become available.
+  #
+  #   shape.fill.solid
+  #   shape.fill.fore_color.rgb = Pptx::RGBColor["C0504D"]
+  class FillFormat
+    # @param fill_parent [Pptx::Oxml::Element] the element carrying the fill
+    #   choice group, e.g. `p:spPr` or `a:rPr`
+    def self.from_fill_parent(fill_parent) = new(fill_parent)
+
+    def initialize(fill_parent)
+      @parent = fill_parent
+    end
+
+    # @return [Pptx::Enum::MSO_FILL_TYPE, nil] nil when the fill is inherited
+    def type
+      element = fill_element
+      return nil if element.nil?
+
+      TYPES[element.nsptag]
+    end
+
+    TYPES = {
+      "a:noFill" => Enum::MSO_FILL_TYPE::BACKGROUND,
+      "a:solidFill" => Enum::MSO_FILL_TYPE::SOLID,
+      "a:gradFill" => Enum::MSO_FILL_TYPE::GRADIENT,
+      "a:blipFill" => Enum::MSO_FILL_TYPE::PICTURE,
+      "a:pattFill" => Enum::MSO_FILL_TYPE::PATTERNED,
+      "a:grpFill" => Enum::MSO_FILL_TYPE::GROUP
+    }.freeze
+
+    # Make this a solid (flat colour) fill. The colour itself is then set
+    # through {#fore_color}.
+    def solid
+      @parent.get_or_change_to_solidFill
+      self
+    end
+
+    # Make this fill transparent, so whatever is behind shows through.
+    def background
+      @parent.get_or_change_to_noFill
+      self
+    end
+
+    # Make this a gradient fill, with PowerPoint's default stops.
+    def gradient
+      @parent.get_or_change_to_gradFill
+      self
+    end
+
+    # Make this a patterned fill.
+    def patterned
+      @parent.get_or_change_to_pattFill
+      self
+    end
+
+    # The foreground colour.
+    #
+    # @raise [Error] unless the fill is solid or patterned
+    def fore_color
+      case type&.name
+      when :SOLID then ColorFormat.from_color_choice_parent(fill_element)
+      when :PATTERNED then ColorFormat.from_color_choice_parent(fill_element.get_or_add_fgClr)
+      else
+        raise Error, "fill type #{type&.name.inspect} has no foreground colour"
+      end
+    end
+
+    # The background colour of a patterned fill.
+    #
+    # @raise [Error] unless the fill is patterned
+    def back_color
+      raise Error, "fill type #{type&.name.inspect} has no background colour" unless type&.name == :PATTERNED
+
+      ColorFormat.from_color_choice_parent(fill_element.get_or_add_bgClr)
+    end
+
+    # @return [Pptx::Enum::MSO_PATTERN_TYPE, nil]
+    def pattern
+      raise Error, "fill type #{type&.name.inspect} is not patterned" unless type&.name == :PATTERNED
+
+      fill_element.prst
+    end
+
+    def pattern=(value)
+      patterned unless type&.name == :PATTERNED
+      fill_element.prst = value
+    end
+
+    # The angle of a linear gradient in degrees, counter-clockwise from
+    # pointing right -- the way PowerPoint's dialog and trigonometry both
+    # count, although the file stores it clockwise. nil when inherited.
+    #
+    # @raise [Error] unless this is a gradient fill, or if it is not linear
+    def gradient_angle
+      gradient = require_gradient
+      raise Error, "not a linear gradient" unless gradient.path.nil?
+
+      clockwise = gradient.lin&.ang
+      return nil if clockwise.nil?
+
+      clockwise.zero? ? 0.0 : 360.0 - clockwise
+    end
+
+    def gradient_angle=(value)
+      linear = require_gradient.lin
+      raise Error, "not a linear gradient" if linear.nil?
+
+      linear.ang = 360.0 - value
+    end
+
+    # The colour stops the gradient passes through, in order.
+    #
+    # @return [GradientStops]
+    def gradient_stops = GradientStops.new(require_gradient.get_or_add_gsLst)
+
+    def inspect = "#<Pptx::FillFormat type=#{type&.name.inspect}>"
+
+    private
+
+    def fill_element = @parent.eg_fillProperties
+
+    def require_gradient
+      raise Error, "fill type #{type&.name.inspect} is not a gradient" unless type&.name == :GRADIENT
+
+      fill_element
+    end
+  end
+
+  # The outline of a shape.
+  # The stops of a gradient fill.
+  #
+  #   stops = shape.fill.gradient_stops
+  #   stops[0].color.rgb = Pptx::RGBColor["1F497D"]
+  #   stops[1].position = 0.75
+  class GradientStops
+    include Enumerable
+    include Sliceable
+
+    def initialize(gs_lst)
+      @element = gs_lst
+    end
+
+    def each(&)
+      return enum_for(:each) { size } unless block_given?
+
+      @element.gs_list.each { |gs| yield GradientStop.new(gs) }
+      self
+    end
+
+    def size = @element.gs_list.size
+    alias length size
+
+    def [](index, length = nil) = slice_members(@element.gs_list, index, length) { |gs| GradientStop.new(gs) }
+
+    def inspect = "#<Pptx::GradientStops size=#{size}>"
+  end
+
+  # One colour stop in a gradient.
+  class GradientStop < ElementProxy
+    def color = @color ||= ColorFormat.from_color_choice_parent(@element)
+
+    # Where along the gradient this stop sits, from 0.0 at the start to 1.0
+    # at the end.
+    def position = @element.pos
+
+    def position=(value)
+      @element.pos = Float(value)
+    end
+
+    def inspect = "#<Pptx::GradientStop position=#{position}>"
+  end
+
+  class LineFormat
+    def initialize(parent)
+      @parent = parent
+    end
+
+    # The `a:ln` element, added if not present.
+    def element = @element ||= @parent.get_or_add_ln
+
+    def fill = @fill ||= FillFormat.from_fill_parent(element)
+
+    # Shortcut to the line's solid colour, making the fill solid on first use.
+    def color
+      fill.solid if fill.type.nil?
+      fill.fore_color
+    end
+
+    # @return [Pptx::Length, nil] nil when the width is inherited
+    #
+    # Reading never adds an `a:ln`; only assigning does.
+    def width
+      value = @parent.ln&.w
+      value.nil? || value.zero? ? nil : value
+    end
+
+    # The dash pattern, or nil when it is inherited.
+    #
+    # @return [Pptx::Enum::Member, nil] a member of MSO_LINE_DASH_STYLE
+    def dash_style = @parent.ln&.prstDash_val
+
+    # Set the dash pattern, or restore inheritance with nil -- which also
+    # drops a custom dash, since either one would override the inherited
+    # style.
+    def dash_style=(value)
+      if value.nil?
+        line = @parent.ln or return
+        line.remove_prstDash
+        line.remove_custDash
+      else
+        element.prstDash_val = Enum::MSO_LINE_DASH_STYLE.fetch(value)
+      end
+    end
+
+    def width=(value)
+      element.w = value.nil? ? Pptx::Length.emu(0) : value
+    end
+
+    def inspect = "#<Pptx::LineFormat width=#{width&.pt}>"
+  end
+end

data/lib/ruby_pptx/element_proxy.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/sliceable"
+
+module Pptx
+  # Base for the objects that make up the public API.
+  #
+  # Almost every class a caller touches is a thin proxy whose state lives
+  # entirely in the XML element it wraps. Two proxies wrapping the same element
+  # are equal, whether or not they are the same object.
+  class ElementProxy
+    include Sliceable
+
+    attr_reader :element
+
+    def initialize(element)
+      @element = element
+    end
+
+    def ==(other) = other.is_a?(ElementProxy) && other.element == @element
+    alias eql? ==
+
+    def hash = @element.hash
+
+    def inspect = "#<#{self.class.name} <#{@element.nsptag}>>"
+  end
+
+  # A proxy that knows its parent, and through it the part it belongs to.
+  #
+  # An ancestor is occasionally needed to do something the proxy cannot, such
+  # as add or drop a relationship.
+  class ParentedElementProxy < ElementProxy
+    attr_reader :parent
+
+    def initialize(element, parent)
+      super(element)
+      @parent = parent
+    end
+
+    # The package part this object lives in.
+    def part = @parent.part
+  end
+
+  # A proxy wrapping a part's root element, such as `p:sld`.
+  class PartElementProxy < ElementProxy
+    attr_reader :part
+
+    def initialize(element, part)
+      super(element)
+      @part = part
+    end
+  end
+end