ruby_pptx 0.1.0

data/lib/ruby_pptx/oxml/content_model.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/oxml/element"
+
+module Pptx
+  module Oxml
+    # The class macros that declare an element's content model.
+    #
+    # This replaces python-pptx's `MetaOxmlElement` metaclass. Where Python
+    # collected descriptor objects out of the class dict and post-processed
+    # them, Ruby can just generate the methods as each macro runs, which reads
+    # far more directly.
+    #
+    # Generated method names follow the declared property name +name+:
+    #
+    # | macro               | generates                                            |
+    # |---------------------|------------------------------------------------------|
+    # | `optional_attr`     | `name`, `name=`                                      |
+    # | `required_attr`     | `name`, `name=`                                      |
+    # | `one_and_only_one`  | `name` (raises if absent)                            |
+    # | `zero_or_one`       | `name`, `get_or_add_name`, `add_name`, `new_name`,
+    #                         `insert_name`, `remove_name` |
+    # | `zero_or_more`      | `name_list`, `add_name`, `new_name`, `insert_name`    |
+    # | `one_or_more`       | as `zero_or_more`                                    |
+    # | `zero_or_one_choice`| `name`, `remove_name`, plus per-choice accessors and `get_or_change_to_x` |
+    #
+    # python-pptx generates a private `_add_x` and, for repeating elements, a
+    # separate public `add_x`. Here they are one `add_x` taking keyword
+    # arguments, which is simpler but means a hand-written convenience wrapper
+    # cannot reuse the name -- call it something like `add_x_for` instead.
+    module ContentModel
+      # A member of an `EG_*` element group, for {#zero_or_one_choice}.
+      Choice = Data.define(:nsptag) do
+        def prop_name = Ns.split_tag(nsptag).last
+      end
+
+      # Declare one member of a choice group.
+      def choice(nsptag) = Choice.new(nsptag)
+
+      # An attribute that may be absent. Reading returns +default+ when it is;
+      # assigning +default+ removes it, so a document never carries an
+      # attribute that only restates the schema default.
+      def optional_attr(xml_name, type:, default: nil, as: nil)
+        name = as || attr_prop_name(xml_name)
+
+        define_method(name) do
+          raw = get(xml_name)
+          raw.nil? ? default : type.from_xml(raw)
+        end
+
+        define_method("#{name}=") do |value|
+          if value == default || value.nil?
+            delete_attribute(xml_name)
+          else
+            set(xml_name, type.to_xml(value))
+          end
+          value
+        end
+      end
+
+      # An attribute the schema requires. Reading raises when it is missing,
+      # because that means the document is invalid rather than merely sparse.
+      def required_attr(xml_name, type:, as: nil)
+        name = as || attr_prop_name(xml_name)
+
+        define_method(name) do
+          raw = get(xml_name)
+          if raw.nil?
+            raise InvalidXmlError,
+                  "required #{xml_name.inspect} attribute not present on <#{nsptag}>"
+          end
+          type.from_xml(raw)
+        end
+
+        define_method("#{name}=") { |value| set(xml_name, type.to_xml(value)) }
+      end
+
+      # A required child element.
+      def one_and_only_one(nsptag, as: nil)
+        name = as || Ns.split_tag(nsptag).last
+
+        define_method(name) do
+          find(nsptag) ||
+            raise(InvalidXmlError, "required <#{nsptag}> child element not present")
+        end
+      end
+
+      # An optional child element.
+      def zero_or_one(nsptag, successors: [], as: nil)
+        name = as || Ns.split_tag(nsptag).last
+
+        define_method(name) { find(nsptag) }
+        define_creator(name, nsptag)
+        define_inserter(name, successors)
+        define_adder(name)
+        define_once("get_or_add_#{name}") { find(nsptag) || public_send("add_#{name}") }
+        define_once("remove_#{name}") { remove_all(nsptag) }
+      end
+
+      # A child element that may repeat. The singular accessor is deliberately
+      # not generated -- with a repeating element there is no "the" one.
+      def zero_or_more(nsptag, successors: [], as: nil)
+        name = as || Ns.split_tag(nsptag).last
+
+        define_method("#{name}_list") { find_all(nsptag) }
+        define_creator(name, nsptag)
+        define_inserter(name, successors)
+        define_adder(name)
+      end
+
+      # A child element that must appear at least once. Structurally identical
+      # to {#zero_or_more}; the distinction is documentation of the schema.
+      def one_or_more(nsptag, successors: [], as: nil)
+        zero_or_more(nsptag, successors: successors, as: as)
+      end
+
+      # An `EG_*` group, at most one member of which may be present.
+      def zero_or_one_choice(choices, as:, successors: [])
+        member_tags = choices.map(&:nsptag)
+
+        define_method(as) { first_child_found_in(*member_tags) }
+        define_once("remove_#{as}") { remove_all(*member_tags) }
+
+        choices.each { |c| define_choice(c, as, successors) }
+      end
+
+      private
+
+      def define_choice(choice, group_name, successors)
+        name = choice.prop_name
+        nsptag = choice.nsptag
+
+        define_method(name) { find(nsptag) }
+        define_creator(name, nsptag)
+        define_inserter(name, successors)
+        define_adder(name)
+
+        # Swapping in a different group member means clearing whichever one is
+        # there now; two members present at once would be invalid.
+        define_once("get_or_change_to_#{name}") do
+          find(nsptag) || begin
+            public_send("remove_#{group_name}")
+            public_send("add_#{name}")
+          end
+        end
+      end
+
+      def define_creator(name, nsptag)
+        define_once("new_#{name}") { build(nsptag) }
+      end
+
+      def define_inserter(name, successors)
+        define_once("insert_#{name}") do |child|
+          insert_element_before(child, *successors)
+        end
+      end
+
+      def define_adder(name)
+        define_once("add_#{name}") do |**attrs|
+          child = public_send("new_#{name}")
+          attrs.each { |attr, value| child.public_send("#{attr}=", value) }
+          public_send("insert_#{name}", child)
+          child
+        end
+      end
+
+      # Define +name+ unless the class (or an ancestor) already has it, so a
+      # hand-written override placed above the macro wins. A definition placed
+      # below the macro wins by simply replacing it.
+      def define_once(name, &)
+        return if method_defined?(name) || private_method_defined?(name)
+
+        define_method(name, &)
+      end
+
+      # "r:embed" -> "embed", "macro" -> "macro"
+      def attr_prop_name(xml_name)
+        xml_name.to_s.include?(":") ? Ns.split_tag(xml_name.to_s).last : xml_name.to_s
+      end
+    end
+
+    class Element
+      extend ContentModel
+    end
+  end
+end

data/lib/ruby_pptx/oxml/core_properties.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "time"
+require "date"
+require "ruby_pptx/oxml/element"
+require "ruby_pptx/oxml/content_model"
+require "ruby_pptx/oxml/ns"
+
+module Pptx
+  module Oxml
+    # `cp:coreProperties`, the root of `/docProps/core.xml`.
+    #
+    # Implements the Dublin Core metadata elements. Text properties read as an
+    # empty string when absent and are capped at 255 characters, as the schema
+    # requires.
+    class CT_CoreProperties < Element
+      tag "cp:coreProperties"
+
+      TEXT_PROPERTIES = {
+        category: "cp:category",
+        content_status: "cp:contentStatus",
+        author: "dc:creator",
+        comments: "dc:description",
+        identifier: "dc:identifier",
+        keywords: "cp:keywords",
+        language: "dc:language",
+        last_modified_by: "cp:lastModifiedBy",
+        subject: "dc:subject",
+        title: "dc:title",
+        version: "cp:version"
+      }.freeze
+
+      DATETIME_PROPERTIES = {
+        created: "dcterms:created",
+        last_printed: "cp:lastPrinted",
+        modified: "dcterms:modified"
+      }.freeze
+
+      # `dcterms:created` and `dcterms:modified` must carry an explicit
+      # xsi:type; the others must not.
+      W3CDTF_TYPED = %i[created modified].freeze
+
+      MAX_TEXT_LENGTH = 255
+
+      (TEXT_PROPERTIES.values + DATETIME_PROPERTIES.values + ["cp:revision"]).each do |nsptag|
+        zero_or_one nsptag, successors: []
+      end
+
+      def self.new_element
+        Element.parse(%(<cp:coreProperties #{Ns.nsdecls("cp", "dc", "dcterms")}/>))
+      end
+
+      TEXT_PROPERTIES.each do |name, nsptag|
+        define_method(name) { find(nsptag)&.text.to_s }
+
+        define_method("#{name}=") do |value|
+          value = value.to_s
+          if value.length > MAX_TEXT_LENGTH
+            raise ArgumentError,
+                  "#{name} exceeds the #{MAX_TEXT_LENGTH}-character limit (got #{value.length})"
+          end
+
+          public_send("get_or_add_#{Ns.split_tag(nsptag).last}").text = value
+        end
+      end
+
+      DATETIME_PROPERTIES.each do |name, nsptag|
+        define_method(name) do
+          raw = find(nsptag)&.text
+          raw.nil? || raw.empty? ? nil : CT_CoreProperties.parse_w3cdtf(raw)
+        end
+
+        define_method("#{name}=") do |value|
+          raise TypeError, "#{name} requires a Time, got #{value.class}" unless value.is_a?(Time)
+
+          element = public_send("get_or_add_#{Ns.split_tag(nsptag).last}")
+          element.text = value.getutc.strftime("%Y-%m-%dT%H:%M:%SZ")
+          if W3CDTF_TYPED.include?(name)
+            # PowerPoint declares xsi on the root, not on each child that uses
+            # it, so declare it here first and let the child find it in scope.
+            declare_namespace("xsi")
+            element.set("xsi:type", "dcterms:W3CDTF")
+          end
+          value
+        end
+      end
+
+      # A non-integer, negative or absent revision all read as 0.
+      def revision
+        raw = find("cp:revision")&.text
+        return 0 if raw.nil?
+
+        value = Integer(raw, 10, exception: false) || 0
+        value.negative? ? 0 : value
+      end
+
+      def revision=(value)
+        unless value.is_a?(Integer) && value >= 1
+          raise ArgumentError, "revision requires a positive Integer, got #{value.inspect}"
+        end
+
+        get_or_add_revision.text = value.to_s
+      end
+
+      # Parse a W3CDTF timestamp, which may be a year, a year-month, a date,
+      # or a full timestamp with a `Z` or numeric offset. Returns UTC, or nil
+      # when the value does not parse.
+      #
+      # Each format must consume the *whole* string. Ruby's `strptime` is happy
+      # to parse a prefix and discard the rest, so without that check "%Y"
+      # would match "2003-12-31T10:14:55" and silently yield 2003-01-01.
+      FORMATS = ["%Y-%m-%dT%H:%M:%S", "%Y-%m-%d", "%Y-%m", "%Y"].freeze
+
+      def self.parse_w3cdtf(value)
+        parseable = value[0, 19]
+        offset = value[19..].to_s
+
+        parts = FORMATS.lazy.filter_map { |format| full_match(parseable, format) }.first
+        return nil if parts.nil?
+
+        time = Time.utc(parts[:year], parts[:mon] || 1, parts[:mday] || 1,
+                        parts[:hour] || 0, parts[:min] || 0, parts[:sec] || 0)
+        apply_offset(time, offset)
+      end
+
+      # Parsed fields for +value+, but only if +format+ consumed all of it.
+      def self.full_match(value, format)
+        parts = Date._strptime(value, format)
+        parts if parts && parts[:leftover].nil? && parts[:year]
+      end
+      private_class_method :full_match
+
+      # A trailing "+02:00" means the stamp is local to that offset; shift it
+      # back to UTC. A "Z" or an absent offset is already UTC.
+      def self.apply_offset(time, offset)
+        match = /\A([+-])(\d\d):(\d\d)\z/.match(offset)
+        return time unless match
+
+        sign = match[1] == "+" ? -1 : 1
+        time + (sign * ((Integer(match[2], 10) * 3600) + (Integer(match[3], 10) * 60)))
+      end
+      private_class_method :apply_offset
+    end
+  end
+end

data/lib/ruby_pptx/oxml/dml/color.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/oxml/element"
+require "ruby_pptx/oxml/content_model"
+require "ruby_pptx/oxml/simple_types"
+require "ruby_pptx/enum/dml"
+
+module Pptx
+  module Oxml
+    # The colour elements share a luminance-adjustment pair: `a:lumMod` scales
+    # the colour (a shade) and `a:lumOff` lightens it (a tint).
+    module BaseColorElement
+      def self.included(base)
+        base.class_eval do
+          zero_or_one "a:lumMod", successors: []
+          zero_or_one "a:lumOff", successors: []
+        end
+      end
+
+      def add_lumMod(value) = add_lumMod_element(value)
+
+      def add_lumOff(value) = add_lumOff_element(value)
+
+      # Remove any luminance adjustment, returning self.
+      def clear_lum
+        remove_lumMod
+        remove_lumOff
+        self
+      end
+
+      private
+
+      def add_lumMod_element(value)
+        el = get_or_add_lumMod
+        el.val = value
+        el
+      end
+
+      def add_lumOff_element(value)
+        el = get_or_add_lumOff
+        el.val = value
+        el
+      end
+    end
+
+    # `a:lumMod` and `a:lumOff`.
+    class CT_Percentage < Element
+      tag "a:lumMod", "a:lumOff"
+      required_attr "val", type: SimpleTypes::ST_Percentage
+    end
+
+    # `a:srgbClr`, a literal RGB colour.
+    class CT_SRgbColor < Element
+      include BaseColorElement
+
+      tag "a:srgbClr"
+      required_attr "val", type: SimpleTypes::ST_HexColorRGB
+    end
+
+    # `a:schemeClr`, a reference to a theme colour.
+    class CT_SchemeColor < Element
+      include BaseColorElement
+
+      tag "a:schemeClr"
+      required_attr "val", type: Enum::MSO_THEME_COLOR
+    end
+
+    # `a:hslClr`, a hue/saturation/luminance colour.
+    class CT_HslColor < Element
+      include BaseColorElement
+
+      tag "a:hslClr"
+    end
+
+    # `a:sysClr`, a system colour such as "windowText".
+    class CT_SystemColor < Element
+      include BaseColorElement
+
+      tag "a:sysClr"
+    end
+
+    # `a:prstClr`, a named preset colour.
+    class CT_PresetColor < Element
+      include BaseColorElement
+
+      tag "a:prstClr"
+    end
+
+    # `a:scrgbClr`, a percentage-based RGB colour.
+    class CT_ScRgbColor < Element
+      include BaseColorElement
+
+      tag "a:scrgbClr"
+    end
+
+    # The six-way colour choice shared by everything that carries a colour.
+    module ColorChoice
+      COLOR_CHOICES = %w[a:scrgbClr a:srgbClr a:hslClr a:sysClr a:schemeClr a:prstClr].freeze
+
+      def self.included(base)
+        base.class_eval do
+          zero_or_one_choice ColorChoice::COLOR_CHOICES.map { |t| choice(t) },
+                             successors: [], as: :eg_colorChoice
+        end
+      end
+    end
+
+    # `a:fgClr` and `a:bgClr`, which are colours and nothing else.
+    class CT_Color < Element
+      include ColorChoice
+
+      tag "a:fgClr", "a:bgClr"
+    end
+  end
+end

data/lib/ruby_pptx/oxml/dml/fill.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "ruby_pptx/oxml/dml/color"
+
+module Pptx
+  module Oxml
+    # `a:solidFill`, a single flat colour.
+    class CT_SolidColorFillProperties < Element
+      include ColorChoice
+
+      tag "a:solidFill"
+    end
+
+    # `a:noFill`, explicitly transparent.
+    class CT_NoFillProperties < Element
+      tag "a:noFill"
+    end
+
+    # `a:grpFill`, inheriting the group's fill.
+    class CT_GroupFillProperties < Element
+      tag "a:grpFill"
+    end
+
+    # `a:gs`, one stop in a gradient.
+    class CT_GradientStop < Element
+      include ColorChoice
+
+      tag "a:gs"
+      required_attr "pos", type: SimpleTypes::ST_PositiveFixedPercentage
+    end
+
+    # `a:gsLst`, the stops of a gradient.
+    class CT_GradientStopList < Element
+      tag "a:gsLst"
+      one_or_more "a:gs", as: :gs
+    end
+
+    # `a:lin`, the direction of a linear gradient.
+    class CT_LinearShadeProperties < Element
+      tag "a:lin"
+      optional_attr "ang", type: SimpleTypes::ST_PositiveFixedAngle
+      optional_attr "scaled", type: SimpleTypes::XsdBoolean
+    end
+
+    # `a:gradFill`, a gradient fill.
+    class CT_GradientFillProperties < Element
+      tag "a:gradFill"
+      zero_or_one "a:gsLst", successors: %w[a:lin a:path a:tileRect]
+      zero_or_one "a:lin", successors: %w[a:path a:tileRect]
+      zero_or_one "a:path", successors: %w[a:tileRect]
+
+      # python-pptx's default, verbatim: PowerPoint's "White" template
+      # gradient, two accent-1 stops on a linear path. The `a:lin` carries no
+      # angle, so the direction is inherited until one is set.
+      DEFAULT_XML = <<~XML.freeze
+        <a:gradFill #{Ns.nsdecls("a")} rotWithShape="1">
+          <a:gsLst>
+            <a:gs pos="0">
+              <a:schemeClr val="accent1">
+                <a:tint val="100000"/>
+                <a:shade val="100000"/>
+                <a:satMod val="130000"/>
+              </a:schemeClr>
+            </a:gs>
+            <a:gs pos="100000">
+              <a:schemeClr val="accent1">
+                <a:tint val="50000"/>
+                <a:shade val="100000"/>
+                <a:satMod val="350000"/>
+              </a:schemeClr>
+            </a:gs>
+          </a:gsLst>
+          <a:lin scaled="0"/>
+        </a:gradFill>
+      XML
+
+      def self.new_grad_fill(context) = context.build_from_xml(DEFAULT_XML)
+    end
+
+    # `a:blip`, the image reference inside a picture fill.
+    class CT_Blip < Element
+      tag "a:blip"
+      optional_attr "r:embed", type: SimpleTypes::ST_RelationshipId, as: :embed
+      zero_or_one "a:extLst", successors: []
+
+      # The Office 2016 extension that carries an SVG beside the raster the
+      # blip itself points at. Consumers that understand it draw the vector;
+      # those that do not draw the fallback.
+      SVG_EXT_URI = "{96DAC541-7B7A-43D3-8B79-37D633B846F1}"
+
+      # Point this blip's SVG extension at the part related by +r_id+.
+      def add_svg_blip(r_id)
+        ext_list = get_or_add_extLst
+        ext_list.append(ext_list.build_from_xml(<<~XML))
+          <a:ext #{Ns.nsdecls("a")} uri="#{SVG_EXT_URI}">
+            <asvg:svgBlip #{Ns.nsdecls("asvg", "r")} r:embed="#{r_id}"/>
+          </a:ext>
+        XML
+        self
+      end
+
+      # The relationship id of the SVG, or nil when this is a plain raster.
+      def svg_rId = xpath("./a:extLst/a:ext/asvg:svgBlip/@r:embed").first&.value
+    end
+
+    # `a:extLst` as it appears on a blip.
+    class CT_BlipExtensionList < Element
+      tag "a:extLst"
+      zero_or_more "a:ext", as: :ext
+    end
+
+    # `a:srcRect`: how much of an image is cropped from each side, as a
+    # fraction of its size. Negative values extend past the image edge.
+    class CT_RelativeRect < Element
+      tag "a:srcRect"
+      optional_attr "l", type: SimpleTypes::ST_Percentage, default: 0.0
+      optional_attr "t", type: SimpleTypes::ST_Percentage, default: 0.0
+      optional_attr "r", type: SimpleTypes::ST_Percentage, default: 0.0
+      optional_attr "b", type: SimpleTypes::ST_Percentage, default: 0.0
+    end
+
+    # `a:blipFill`, a picture fill; `p:blipFill` on a picture is the same type.
+    class CT_BlipFillProperties < Element
+      tag "a:blipFill", "p:blipFill"
+      zero_or_one "a:blip", successors: %w[a:srcRect a:tile a:stretch]
+      zero_or_one "a:srcRect", successors: %w[a:tile a:stretch]
+    end
+
+    # `a:pattFill`, a two-colour pattern fill.
+    class CT_PatternFillProperties < Element
+      tag "a:pattFill"
+      zero_or_one "a:fgClr", successors: %w[a:bgClr]
+      zero_or_one "a:bgClr", successors: []
+      optional_attr "prst", type: Enum::MSO_PATTERN_TYPE
+    end
+  end
+end