ruby_pptx 0.1.0

data/lib/ruby_pptx/chart/combo.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/chart/xml_writer"
+
+module Pptx
+  # Describes a chart that draws more than one plot over the same categories --
+  # a bar chart with a line over it, most often.
+  #
+  # python-pptx can read such a chart but only ever writes one plot, so this is
+  # new ground rather than a port.
+  #
+  #   slide.shapes.add_combo_chart(data, at: [x, y], size: [w, h]) do |combo|
+  #     combo.plot :column_clustered, series: "Revenue"
+  #     combo.plot :line, series: "Margin", secondary_axis: true
+  #   end
+  #
+  # All the series live in one {ChartData}, because they share a worksheet;
+  # each plot names the ones it draws.
+  class ComboChartBuilder
+    # What a plot draws and how.
+    PlotSpec = Data.define(:chart_type, :series, :secondary_axis)
+
+    # The families that can share a category axis. A pie or a scatter cannot,
+    # so they are not combinable.
+    COMBINABLE = %i[bar line area].freeze
+
+    attr_reader :chart_data, :specs
+
+    def initialize(chart_data)
+      @chart_data = chart_data
+      @specs = []
+    end
+
+    # Add a plot drawing +series+.
+    #
+    # @param series [String, Integer, Array] series names or indices; all of
+    #   them when omitted
+    # @param secondary_axis [Boolean] draw against a second value axis on the
+    #   right, for values on a different scale
+    def plot(chart_type, series: nil, secondary_axis: false)
+      member = Enum::XL_CHART_TYPE.fetch(chart_type)
+      family = ChartXmlWriter.family_of(member)
+      unless COMBINABLE.include?(family)
+        raise Error,
+              "a #{member.name} chart cannot share a category axis, so it " \
+              "cannot be part of a combo chart"
+      end
+
+      @specs << PlotSpec.new(chart_type: member, series: resolve(series),
+                             secondary_axis: secondary_axis)
+      self
+    end
+
+    # @raise [Error] when the combination could not be drawn
+    def validate!
+      raise Error, "a combo chart needs at least two plots" if @specs.size < 2
+
+      drawn = @specs.flat_map(&:series)
+      duplicated = drawn.map(&:index).tally.select { |_, count| count > 1 }.keys
+      raise Error, "series #{duplicated.inspect} appear in more than one plot" unless duplicated.empty?
+
+      self
+    end
+
+    def secondary_axis? = @specs.any?(&:secondary_axis)
+
+    private
+
+    # Accepts a name, an index, or a list of either; nil means every series.
+    def resolve(selector)
+      return @chart_data.series if selector.nil?
+
+      Array(selector).map do |key|
+        case key
+        when Integer then @chart_data.series[key]
+        when String then @chart_data.series.find { |s| s.name == key }
+        else key
+        end || raise(NotFoundError, "no series #{key.inspect} in this chart data")
+      end
+    end
+  end
+
+  # Writes the `c:chartSpace` for a combo chart.
+  #
+  # The plot area holds one element per plot followed by the axes, which is the
+  # order the schema requires. Every plot names exactly two axis ids and each
+  # must be backed by a real axis element, so a secondary value axis brings a
+  # category axis with it -- a hidden one, since the categories are already
+  # drawn by the primary pair.
+  class ComboChartWriter < ChartXmlWriter::Base
+    CAT_AX_ID = "-2068027336"
+    VAL_AX_ID = "-2113994440"
+    SECONDARY_CAT_AX_ID = "-2068027337"
+    SECONDARY_VAL_AX_ID = "-2113994441"
+
+    def initialize(builder)
+      super(nil, builder.chart_data)
+      @builder = builder
+    end
+
+    def xml
+      <<~XML
+        #{ChartXmlWriter::Base::DECLARATION}
+        <c:chartSpace #{ChartXmlWriter::Base::CHART_SPACE_NS}>
+          <c:date1904 val="0"/>
+          <c:chart>
+            <c:autoTitleDeleted val="0"/>
+            <c:plotArea>
+              <c:layout/>
+        #{indent(plot_elements, 6).chomp}
+        #{indent(axes_xml, 6).chomp}
+            </c:plotArea>
+        #{indent(ChartXmlWriter::Base::LEGEND, 4).chomp}
+            <c:plotVisOnly val="1"/>
+            <c:dispBlanksAs val="gap"/>
+            <c:showDLblsOverMax val="0"/>
+          </c:chart>
+        #{indent(ChartXmlWriter::Base::TEXT_PROPERTIES, 2).chomp}
+        </c:chartSpace>
+      XML
+    end
+
+    private
+
+    def plot_elements = @builder.specs.map { |spec| plot_element(spec) }.join
+
+    def plot_element(spec)
+      family = ChartXmlWriter.family_of(spec.chart_type)
+      value_ax = spec.secondary_axis ? SECONDARY_VAL_AX_ID : VAL_AX_ID
+      cat_ax = spec.secondary_axis ? SECONDARY_CAT_AX_ID : CAT_AX_ID
+      body = send(:"#{family}_plot_body", spec)
+
+      <<~XML
+        <#{plot_tag(family)}>
+        #{indent(body, 2).chomp}
+        #{indent(spec.series.map { |s| series_xml(s) }.join, 2).chomp}
+        #{indent(plot_tail(family, spec), 2).chomp}
+          <c:axId val="#{cat_ax}"/>
+          <c:axId val="#{value_ax}"/>
+        </#{plot_tag(family)}>
+      XML
+    end
+
+    def plot_tag(family) = { bar: "c:barChart", line: "c:lineChart", area: "c:areaChart" }[family]
+
+    def bar_plot_body(spec)
+      direction = ChartXmlWriter::BarChartWriter::BAR_TYPES.include?(spec.chart_type.name) ? "bar" : "col"
+      grouping = ChartXmlWriter::BarChartWriter::GROUPINGS.fetch(spec.chart_type.name)
+      %(<c:barDir val="#{direction}"/>\n<c:grouping val="#{grouping}"/>\n)
+    end
+
+    def line_plot_body(spec)
+      grouping = ChartXmlWriter::LineChartWriter::GROUPINGS.fetch(spec.chart_type.name)
+      %(<c:grouping val="#{grouping}"/>\n<c:varyColors val="0"/>\n)
+    end
+
+    def area_plot_body(spec)
+      grouping = ChartXmlWriter::AreaChartWriter::GROUPINGS.fetch(spec.chart_type.name)
+      %(<c:grouping val="#{grouping}"/>\n<c:varyColors val="0"/>\n)
+    end
+
+    def plot_tail(family, spec)
+      case family
+      when :bar
+        stacked = ChartXmlWriter::BarChartWriter::STACKED_TYPES.include?(spec.chart_type.name)
+        stacked ? %(<c:overlap val="100"/>\n) : ""
+      when :line
+        %(<c:marker val="1"/>\n<c:smooth val="0"/>\n)
+      else ""
+      end
+    end
+
+    def axes_xml
+      xml = +""
+      xml << category_axis_xml(CAT_AX_ID, VAL_AX_ID, hidden: false)
+      xml << value_axis_xml(VAL_AX_ID, CAT_AX_ID, position: "l", crosses: "autoZero")
+      return xml unless @builder.secondary_axis?
+
+      # The secondary pair: a value axis on the right, and the category axis
+      # the schema demands to go with it, hidden because the primary pair
+      # already draws the categories.
+      xml << category_axis_xml(SECONDARY_CAT_AX_ID, SECONDARY_VAL_AX_ID, hidden: true)
+      xml << value_axis_xml(SECONDARY_VAL_AX_ID, SECONDARY_CAT_AX_ID,
+                            position: "r", crosses: "max")
+      xml
+    end
+
+    def category_axis_xml(ax_id, cross_ax_id, hidden:)
+      <<~XML
+        <c:catAx>
+          <c:axId val="#{ax_id}"/>
+          <c:scaling>
+            <c:orientation val="minMax"/>
+          </c:scaling>
+          <c:delete val="#{hidden ? 1 : 0}"/>
+          <c:axPos val="b"/>
+          <c:majorTickMark val="out"/>
+          <c:minorTickMark val="none"/>
+          <c:tickLblPos val="nextTo"/>
+          <c:crossAx val="#{cross_ax_id}"/>
+          <c:crosses val="autoZero"/>
+          <c:auto val="1"/>
+          <c:lblAlgn val="ctr"/>
+          <c:lblOffset val="100"/>
+          <c:noMultiLvlLbl val="0"/>
+        </c:catAx>
+      XML
+    end
+
+    def value_axis_xml(ax_id, cross_ax_id, position:, crosses:)
+      <<~XML
+        <c:valAx>
+          <c:axId val="#{ax_id}"/>
+          <c:scaling>
+            <c:orientation val="minMax"/>
+          </c:scaling>
+          <c:delete val="0"/>
+          <c:axPos val="#{position}"/>
+          #{"<c:majorGridlines/>" if position == "l"}
+          <c:numFmt formatCode="General" sourceLinked="1"/>
+          <c:majorTickMark val="out"/>
+          <c:minorTickMark val="none"/>
+          <c:tickLblPos val="nextTo"/>
+          <c:crossAx val="#{cross_ax_id}"/>
+          <c:crosses val="#{crosses}"/>
+        </c:valAx>
+      XML
+    end
+  end
+end

data/lib/ruby_pptx/chart/data.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/errors"
+require "ruby_pptx/chart/categories"
+
+module Pptx
+  # The categories and series a chart depicts.
+  #
+  #   data = Pptx::ChartData.new
+  #   data.categories = ["East", "West", "Midwest"]
+  #   data.add_series("Q1", [1.2, 2.0, 3.5])
+  #   data.add_series("Q2", [4.1, 5.0, 6.2])
+  #
+  # Categories can be grouped, which draws a multi-level axis, and can be
+  # dates, which draws a date axis; see {ChartDataCategories}.
+  #
+  # The values also become an embedded Excel workbook, which is what PowerPoint
+  # opens when the user chooses "Edit Data". The worksheet references in the
+  # chart XML are derived from the same layout, so the two always agree.
+  class ChartData
+    include Enumerable
+
+    # The row the first data value sits on; row 1 holds the series names.
+    FIRST_DATA_ROW = 2
+    # Category labels fill the first columns, one per level; series follow.
+    WORKSHEET_NAME = "Sheet1"
+    DEFAULT_NUMBER_FORMAT = "General"
+
+    attr_reader :series, :number_format, :categories
+
+    def initialize(number_format: DEFAULT_NUMBER_FORMAT)
+      @categories = ChartDataCategories.new
+      @series = []
+      @number_format = number_format
+    end
+
+    # Replace the categories: a list of labels, or a Hash of groups whose
+    # values are their sub-categories.
+    def categories=(values)
+      @categories = values.is_a?(ChartDataCategories) ? values : ChartDataCategories.from(values)
+    end
+
+    # Add a series of values, one per category.
+    #
+    # @return [ChartSeries]
+    def add_series(name, values, number_format: nil)
+      series = ChartSeries.new(self, @series.size, name, values.to_a,
+                               number_format || @number_format)
+      @series << series
+      series
+    end
+
+    def each(&) = @series.each(&)
+
+    def size = @series.size
+
+    # The number of categories plotted: the leaves, when they are grouped.
+    def category_count = @categories.leaf_count
+
+    # True when the categories are numbers or dates, which makes the category
+    # cache numeric rather than textual. Decided by the first category, as
+    # python-pptx decides it.
+    def numeric_categories? = @categories.numeric?
+
+    # @api private
+    # The category block: one column per level, one row per leaf.
+    def categories_ref
+      raise Error, "chart data contains no categories" if @categories.depth.zero?
+
+      right = ChartData.column_reference(@categories.depth)
+      "#{WORKSHEET_NAME}!$A$#{FIRST_DATA_ROW}:$#{right}$#{FIRST_DATA_ROW + category_count - 1}"
+    end
+
+    # @api private
+    def series_name_ref(series) = "#{WORKSHEET_NAME}!$#{column_letter(series)}$1"
+
+    # @api private
+    # As long as the series itself, which python-pptx also measures by the
+    # series rather than by the categories.
+    def series_values_ref(series)
+      letter = column_letter(series)
+      last_row = FIRST_DATA_ROW + series.size - 1
+      "#{WORKSHEET_NAME}!$#{letter}$#{FIRST_DATA_ROW}:$#{letter}$#{last_row}"
+    end
+
+    # @api private
+    # The Excel column letter for a series: after the category columns.
+    def column_letter(series) = ChartData.column_reference(1 + @categories.depth + series.index)
+
+    # Excel's bijective base-26 column names: 1 => "A", 27 => "AA".
+    def self.column_reference(column_number)
+      raise ArgumentError, "column number must be positive" unless column_number.positive?
+
+      letters = +""
+      remaining = column_number
+      while remaining.positive?
+        remaining, remainder = (remaining - 1).divmod(26)
+        letters.prepend((remainder + 65).chr)
+      end
+      letters
+    end
+
+    # @api private
+    # Bytes of the embedded Excel workbook holding this data.
+    def xlsx_blob = ChartWorkbookWriter.new(self).blob
+
+    def inspect = "#<Pptx::ChartData categories=#{category_count} series=#{size}>"
+  end
+
+  # One series of a chart: a name and one value per category.
+  class ChartSeries
+    include Enumerable
+
+    attr_reader :chart_data, :index, :name, :values, :number_format
+
+    def initialize(chart_data, index, name, values, number_format)
+      @chart_data = chart_data
+      @index = index
+      @name = name
+      @values = values
+      @number_format = number_format
+    end
+
+    def each(&) = @values.each(&)
+
+    def size = @values.size
+
+    # Append one value, for building a series up point by point.
+    #
+    # python-pptx's add_data_point also takes a per-point number format, but
+    # nothing it writes ever reads it; the series' format is the one used.
+    def <<(value)
+      @values << value
+      self
+    end
+
+    def categories = @chart_data.categories
+
+    def name_ref = @chart_data.series_name_ref(self)
+
+    def values_ref = @chart_data.series_values_ref(self)
+
+    def categories_ref = @chart_data.categories_ref
+
+    def inspect = "#<Pptx::ChartSeries #{@name.inspect} #{size} values>"
+  end
+end