ruby_pptx 0.1.0

data/lib/ruby_pptx/oxml/element.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "ruby_pptx/errors"
+require "ruby_pptx/oxml/ns"
+require "ruby_pptx/oxml/simple_types"
+
+module Pptx
+  module Oxml
+    # Maps a Clark-notation tag name to the {Element} subclass that models it.
+    #
+    # python-pptx gets this for free from lxml, whose parser instantiates a
+    # custom class per tag. Nokogiri has no such hook, so element classes
+    # register themselves here and {Element.wrap} does the dispatch.
+    module Registry
+      @classes = {}
+
+      class << self
+        # A tag belongs to exactly one class. Registering a second one used to
+        # replace the first silently, so whichever file loaded last won --
+        # `c:tx` and `a:ext` each had two classes that way.
+        def register(clark_name, element_class)
+          existing = @classes[clark_name]
+          if existing && existing != element_class
+            raise ArgumentError, "#{clark_name} is already registered to #{existing}"
+          end
+
+          @classes[clark_name] = element_class
+        end
+
+        # @return [Class] the registered class, or {Element} for an unmodelled tag
+        def class_for(clark_name) = @classes.fetch(clark_name, Element)
+
+        def registered = @classes.dup
+
+        # Test seam: forget registrations made by a spec.
+        def reset!(to) = (@classes = to)
+      end
+    end
+
+    # Wraps a `Nokogiri::XML::Node` and gives it the schema-aware behaviour of
+    # one OOXML element type.
+    #
+    # Subclasses declare their content model with class macros, which generate
+    # the accessors that the rest of the library uses:
+    #
+    #   class CT_Shape < Element
+    #     tag "p:sp"
+    #     one_and_only_one "p:nvSpPr"
+    #     zero_or_one      "p:spPr", successors: %w[p:style p:txBody]
+    #     zero_or_more     "p:ext"
+    #     optional_attr    "macro", type: SimpleTypes::XsdString
+    #   end
+    #
+    # Local tag names are kept verbatim, camel case and all, so a method name
+    # can be grepped straight from the ECMA-376 schema. The snake_case Ruby
+    # idiom belongs to the public API layer built on top of this one.
+    #
+    # ## Identity
+    #
+    # Two wrappers around the same underlying node are `==` and hash alike, so
+    # correctness never depends on the wrapper cache. The cache exists to avoid
+    # re-allocating wrappers, not to make comparisons work.
+    class Element
+      # Declares the tag or tags this class models and registers them for
+      # dispatch. A few element types appear under more than one tag -- a
+      # transform is `a:xfrm` on a shape but `p:xfrm` on a graphic frame --
+      # and are the same class in both places.
+      def self.tag(*prefixed_tags)
+        @nsptags = prefixed_tags
+        prefixed_tags.each { |t| Registry.register(Ns.qn(t), self) }
+      end
+
+      def self.nsptag = @nsptags&.first
+
+      class << self
+        attr_reader :nsptags
+      end
+
+      # Wrap +node+ in the class registered for its tag.
+      #
+      # @param node [Nokogiri::XML::Node]
+      # @return [Element, nil] nil when +node+ is nil
+      def self.wrap(node)
+        return nil if node.nil?
+        return node if node.is_a?(Element)
+
+        cache = cache_for(node.document)
+        cache[node] ||= Registry.class_for(Ns.clark_name_of(node)).new(node)
+      end
+
+      # Parse +xml+ into a standalone element tree.
+      def self.parse(xml)
+        doc = Nokogiri::XML(xml) { |config| config.noblanks.strict }
+        raise InvalidXmlError, doc.errors.first.to_s if doc.errors.any?
+
+        wrap(doc.root)
+      end
+
+      # Per-document wrapper cache, keyed on node identity. Lives on the
+      # document so it dies with it.
+      def self.cache_for(document)
+        document.instance_variable_get(:@pptx_wrappers) ||
+          document.instance_variable_set(:@pptx_wrappers, {}.compare_by_identity)
+      end
+      private_class_method :cache_for
+
+      # @return [Nokogiri::XML::Node] the wrapped node
+      attr_reader :node
+
+      def initialize(node)
+        @node = node
+      end
+
+      # -- tree navigation -------------------------------------------------
+
+      # @return [String] this element's prefixed tag, e.g. "p:sp"
+      def nsptag = Ns.prefixed_tag(Ns.clark_name_of(@node))
+
+      def document = @node.document
+
+      def parent = Element.wrap(@node.parent.is_a?(Nokogiri::XML::Element) ? @node.parent : nil)
+
+      # @return [Array<Element>] every child element, in document order
+      def element_children = @node.element_children.map { |child| Element.wrap(child) }
+
+      # First child element with +nsptag+, or nil.
+      def find(nsptag) = Element.wrap(raw_find(nsptag))
+
+      # Every child element with +nsptag+, in document order.
+      def find_all(nsptag)
+        pfx, local = Ns.split_tag(nsptag)
+        @node.element_children
+             .select { |c| c.name == local && c.namespace&.href == Ns.nsuri(pfx) }
+             .map { |c| Element.wrap(c) }
+      end
+
+      # The first child matching any of +nsptags+, in the order given -- not in
+      # document order. Used to find an element's successor when inserting.
+      def first_child_found_in(*nsptags)
+        nsptags.each do |nsptag|
+          child = raw_find(nsptag)
+          return Element.wrap(child) if child
+        end
+        nil
+      end
+
+      # Run an XPath expression with the full OOXML namespace map bound.
+      def xpath(expression)
+        @node.xpath(expression, Ns::NSMAP).map do |result|
+          result.is_a?(Nokogiri::XML::Element) ? Element.wrap(result) : result
+        end
+      end
+
+      # -- mutation --------------------------------------------------------
+
+      # Insert +element+ before the first of +successor_tags+ present, or
+      # append it when none is. This is what keeps children in schema order.
+      def insert_element_before(element, *successor_tags)
+        successor = first_child_found_in(*successor_tags)
+        if successor
+          successor.node.add_previous_sibling(adopt(element))
+        else
+          @node.add_child(adopt(element))
+        end
+        element
+      end
+
+      def append(element)
+        @node.add_child(adopt(element))
+        element
+      end
+
+      # Remove every child element whose tag is in +nsptags+.
+      def remove_all(*nsptags)
+        nsptags.each { |nsptag| find_all(nsptag).each { |child| child.node.unlink } }
+        nil
+      end
+
+      def remove(element)
+        element.node.unlink
+        nil
+      end
+
+      # Create a new, empty element with +nsptag+, in *this* element's
+      # document.
+      #
+      # Creating it anywhere else would be a bug: Nokogiri re-creates a node
+      # adopted from another document, so the object you built is not the
+      # object that ends up in the tree, and every wrapper held on it goes
+      # stale. Staying in one document keeps node identity intact.
+      def build(nsptag)
+        pfx, local = Ns.split_tag(nsptag)
+        uri = Ns.nsuri(pfx)
+        child = Nokogiri::XML::Node.new(local, @node.document)
+        # Resolve against this element's scope, not the detached child's, so
+        # the new element joins an existing declaration instead of introducing
+        # a second one. Where the parent holds the namespace as its *default*
+        # -- as .rels and [Content_Types].xml do -- the child is created
+        # unprefixed to match, which matters because C14N preserves prefixes.
+        child.namespace = inherited_namespace(pfx, uri) ||
+                          child.add_namespace_definition(pfx, uri)
+        Element.wrap(child)
+      end
+
+      # Parse an XML literal into this element's document.
+      def build_from_xml(xml)
+        # noblanks matches Element.parse, so an indented XML literal does not
+        # smuggle whitespace text nodes into the tree.
+        fragment = @node.parse(xml, &:noblanks)
+        raise InvalidXmlError, "fragment produced no element: #{xml.inspect}" if fragment.first.nil?
+
+        Element.wrap(fragment.first)
+      end
+
+      # -- text content ----------------------------------------------------
+
+      # @return [String] the element's text content
+      def text = @node.text
+
+      def text=(value)
+        @node.content = value.to_s
+      end
+
+      # Declare +prefix+ on this element even if nothing uses it yet.
+      #
+      # Needed where a descendant carries a namespaced attribute but the
+      # declaration belongs on the root, which is where PowerPoint puts it.
+      def declare_namespace(prefix)
+        namespace_for(@node, prefix)
+        self
+      end
+
+      # -- attributes ------------------------------------------------------
+
+      # Attribute names may be prefixed ("r:embed") or not ("cstate").
+      #
+      # A prefixed name is resolved by namespace URI rather than by the literal
+      # prefix, because a document is free to bind that namespace to any prefix
+      # it likes. This matches the Clark-name semantics python-pptx inherits
+      # from lxml.
+      def get(attr_name)
+        pfx, local = prefixed_attr_parts(attr_name)
+        return @node[attr_name.to_s] unless pfx
+
+        @node.attribute_with_ns(local, Ns.nsuri(pfx))&.value
+      end
+
+      def set(attr_name, value)
+        pfx, local = prefixed_attr_parts(attr_name)
+        return @node[attr_name.to_s] = value.to_s unless pfx
+
+        uri = Ns.nsuri(pfx)
+        if (existing = @node.attribute_with_ns(local, uri))
+          existing.value = value.to_s
+        else
+          namespace_for(@node, pfx)
+          @node["#{pfx}:#{local}"] = value.to_s
+        end
+        value
+      end
+
+      def delete_attribute(attr_name)
+        pfx, local = prefixed_attr_parts(attr_name)
+        return @node.remove_attribute(attr_name.to_s) unless pfx
+
+        @node.attribute_with_ns(local, Ns.nsuri(pfx))&.unlink
+        nil
+      end
+
+      def attribute?(attr_name) = !get(attr_name).nil?
+
+      # -- serialization and equality --------------------------------------
+
+      # Pretty-printed XML for this element, without a declaration. For
+      # debugging and specs.
+      def xml = @node.to_xml(indent: 2)
+
+      def to_s = xml
+
+      def ==(other) = other.is_a?(Element) && other.node.equal?(@node)
+      alias eql? ==
+
+      def hash = @node.object_id.hash
+
+      def inspect = "#<#{self.class.name} <#{nsptag}> children=#{@node.element_children.size}>"
+
+      private
+
+      def raw_find(nsptag)
+        pfx, local = Ns.split_tag(nsptag)
+        uri = Ns.nsuri(pfx)
+        @node.element_children.find { |c| c.name == local && c.namespace&.href == uri }
+      end
+
+      # Guard against the cross-document trap described on {#build}.
+      def adopt(element)
+        node = element.is_a?(Element) ? element.node : element
+        return node if node.document.equal?(@node.document)
+
+        raise ArgumentError,
+              "cannot insert an element created in a different document; " \
+              "build it with #build on an element of this tree"
+      end
+
+      def prefixed_attr_parts(attr_name)
+        return nil unless attr_name.to_s.include?(":")
+
+        Ns.split_tag(attr_name.to_s)
+      end
+
+      # An in-scope declaration for +uri+, preferring one bound to +prefix+ but
+      # accepting any -- including a default (unprefixed) declaration.
+      def inherited_namespace(prefix, uri)
+        scopes = @node.namespace_scopes
+        scopes.find { |ns| ns.href == uri && ns.prefix == prefix } ||
+          scopes.find { |ns| ns.href == uri }
+      end
+
+      # Reuse an in-scope namespace declaration when there is one, so the
+      # output does not sprout a redundant xmlns on every new element.
+      def namespace_for(node, prefix)
+        uri = Ns.nsuri(prefix)
+        existing = node.namespace_scopes.find { |ns| ns.href == uri && ns.prefix == prefix }
+        existing || node.add_namespace_definition(prefix, uri)
+      end
+    end
+  end
+end

data/lib/ruby_pptx/oxml/ns.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Pptx
+  module Oxml
+    # The XML namespaces used across PresentationML, DrawingML and the OPC
+    # package format, plus helpers for moving between the three tag notations
+    # we need:
+    #
+    # - prefixed, `"p:cSld"`               -- how the spec and this code talk
+    # - Clark, `"{http://...}cSld"`        -- unambiguous, used as registry keys
+    # - Nokogiri, name + namespace object  -- what the parser hands back
+    module Ns
+      NSMAP = {
+        "a" => "http://schemas.openxmlformats.org/drawingml/2006/main",
+        "c" => "http://schemas.openxmlformats.org/drawingml/2006/chart",
+        "cp" => "http://schemas.openxmlformats.org/package/2006/metadata/core-properties",
+        "ct" => "http://schemas.openxmlformats.org/package/2006/content-types",
+        "dc" => "http://purl.org/dc/elements/1.1/",
+        "dcmitype" => "http://purl.org/dc/dcmitype/",
+        "dcterms" => "http://purl.org/dc/terms/",
+        "ep" => "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties",
+        "i" => "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image",
+        "m" => "http://schemas.openxmlformats.org/officeDocument/2006/math",
+        "mo" => "http://schemas.microsoft.com/office/mac/office/2008/main",
+        "mv" => "urn:schemas-microsoft-com:mac:vml",
+        "o" => "urn:schemas-microsoft-com:office:office",
+        "p" => "http://schemas.openxmlformats.org/presentationml/2006/main",
+        # PowerPoint 2010 extensions, which is where slide sections live.
+        "p14" => "http://schemas.microsoft.com/office/powerpoint/2010/main",
+        # Office 2016 SVG extension, which carries an SVG beside its raster
+        # fallback in a picture fill.
+        "asvg" => "http://schemas.microsoft.com/office/drawing/2016/SVG/main",
+        "pd" => "http://schemas.openxmlformats.org/drawingml/2006/presentationDrawing",
+        "pic" => "http://schemas.openxmlformats.org/drawingml/2006/picture",
+        "pr" => "http://schemas.openxmlformats.org/package/2006/relationships",
+        "r" => "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+        "sl" => "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout",
+        "v" => "urn:schemas-microsoft-com:vml",
+        "ve" => "http://schemas.openxmlformats.org/markup-compatibility/2006",
+        "w" => "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
+        "w10" => "urn:schemas-microsoft-com:office:word",
+        "wne" => "http://schemas.microsoft.com/office/word/2006/wordml",
+        "wp" => "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
+        "xsi" => "http://www.w3.org/2001/XMLSchema-instance"
+      }.freeze
+
+      # Namespace URI => preferred prefix. Built from NSMAP, so a URI that
+      # appears twice resolves to the last prefix declared for it.
+      PFXMAP = NSMAP.each_with_object({}) { |(pfx, uri), map| map[uri] = pfx }.freeze
+
+      module_function
+
+      # @param nspfx [String] e.g. "p"
+      # @return [String] the namespace URI for +nspfx+
+      def nsuri(nspfx)
+        NSMAP.fetch(nspfx) { raise KeyError, "unknown namespace prefix #{nspfx.inspect}" }
+      end
+
+      # Clark-notation name for a prefixed tag.
+      #
+      #   qn("p:cSld") #=> "{http://schemas.openxmlformats.org/presentationml/2006/main}cSld"
+      def qn(prefixed_tag)
+        pfx, local = split_tag(prefixed_tag)
+        "{#{nsuri(pfx)}}#{local}"
+      end
+
+      # The inverse of {qn}.
+      #
+      #   prefixed_tag("{http://...presentationml/2006/main}cSld") #=> "p:cSld"
+      def prefixed_tag(clark_name)
+        unless clark_name.start_with?("{") && (close = clark_name.index("}"))
+          raise ArgumentError, "not a Clark-notation name: #{clark_name.inspect}"
+        end
+
+        uri   = clark_name[1...close]
+        local = clark_name[(close + 1)..]
+        pfx = PFXMAP.fetch(uri) { raise KeyError, "unknown namespace URI #{uri.inspect}" }
+        "#{pfx}:#{local}"
+      end
+
+      # The subset of NSMAP for +prefixes+, in the shape Nokogiri's #xpath wants.
+      #
+      #   namespaces("a", "p") #=> {"a" => "...", "p" => "..."}
+      def namespaces(*prefixes)
+        prefixes.to_h { |pfx| [pfx, nsuri(pfx)] }
+      end
+
+      # Namespace declarations as literal XML attribute text, for building
+      # fragments by hand.
+      #
+      #   nsdecls("a") #=> 'xmlns:a="http://...drawingml/2006/main"'
+      def nsdecls(*prefixes)
+        prefixes.map { |pfx| %(xmlns:#{pfx}="#{nsuri(pfx)}") }.join(" ")
+      end
+
+      # The Clark name of a Nokogiri node, suitable as an element-registry key.
+      #
+      # @param node [Nokogiri::XML::Node]
+      def clark_name_of(node)
+        href = node.namespace&.href
+        href ? "{#{href}}#{node.name}" : node.name
+      end
+
+      # ["p", "cSld"] for "p:cSld".
+      def split_tag(prefixed_tag)
+        pfx, local, extra = prefixed_tag.split(":", 3)
+        if local.nil? || local.empty? || !extra.nil?
+          raise ArgumentError, "expected a prefixed tag like 'p:cSld', got #{prefixed_tag.inspect}"
+        end
+
+        [pfx, local]
+      end
+    end
+  end
+end

data/lib/ruby_pptx/oxml/presentation.rb

@@ -0,0 +1,110 @@
+# 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/section"
+require "ruby_pptx/oxml/ns"
+
+module Pptx
+  module Oxml
+    ST = SimpleTypes
+
+    # `p:presentation`, the root of `/ppt/presentation.xml`.
+    class CT_Presentation < Element
+      tag "p:presentation"
+      zero_or_one "p:sldMasterIdLst",
+                  successors: %w[p:notesMasterIdLst p:handoutMasterIdLst p:sldIdLst p:sldSz p:notesSz]
+      zero_or_one "p:sldIdLst", successors: %w[p:sldSz p:notesSz]
+      zero_or_one "p:sldSz", successors: %w[p:notesSz]
+      zero_or_one "p:extLst", successors: []
+
+      # The URI PowerPoint uses to mark the section-list extension.
+      SECTION_LIST_EXT_URI = "{521415D9-36F7-43E2-AB2F-B90AF26B5E84}"
+
+      # The `p14:sectionLst` element, or nil when the presentation has no
+      # sections.
+      def section_list
+        xpath("./p:extLst/p:ext/p14:sectionLst").first
+      end
+
+      # The `p14:sectionLst`, created inside its extension if absent.
+      def get_or_add_section_list
+        section_list || begin
+          ext = get_or_add_extLst.add_ext(uri: SECTION_LIST_EXT_URI)
+          ext.append(ext.build_from_xml(%(<p14:sectionLst #{Ns.nsdecls("p14")}/>)))
+          section_list
+        end
+      end
+
+      def remove_section_list
+        extension = xpath("./p:extLst/p:ext").find { |e| e.get("uri") == SECTION_LIST_EXT_URI }
+        return if extension.nil?
+
+        extLst.remove(extension)
+        remove_extLst if extLst.ext_list.empty?
+      end
+    end
+
+    # `p:sldId`, a reference from the presentation to one slide.
+    class CT_SlideId < Element
+      tag "p:sldId"
+      required_attr "id", type: ST::ST_SlideId
+      required_attr "r:id", type: ST::XsdString, as: :rId
+    end
+
+    # `p:sldIdLst`, the ordered list of slides in the presentation.
+    class CT_SlideIdList < Element
+      tag "p:sldIdLst"
+      zero_or_more "p:sldId", as: :sldId
+
+      MIN_SLIDE_ID = 256
+      MAX_SLIDE_ID = 2_147_483_647
+
+      def add_slide_id(r_id) = add_sldId(id: next_id, rId: r_id)
+
+      def size = sldId_list.size
+
+      private
+
+      # One greater than the highest id in use, which avoids reusing the id of
+      # a deleted slide. Only if that would overflow do we hunt for a gap.
+      def next_id
+        used = sldId_list.map(&:id)
+        simple_next = ([MIN_SLIDE_ID - 1] + used).max + 1
+        return simple_next if simple_next <= MAX_SLIDE_ID
+
+        valid = used.grep(MIN_SLIDE_ID..MAX_SLIDE_ID).sort
+        return MIN_SLIDE_ID if valid.empty?
+
+        valid.each_with_index do |used_id, i|
+          candidate = MIN_SLIDE_ID + i
+          return candidate if candidate != used_id
+        end
+        MIN_SLIDE_ID + valid.size
+      end
+    end
+
+    # `p:sldMasterIdLst`, the slide masters belonging to the presentation.
+    class CT_SlideMasterIdList < Element
+      tag "p:sldMasterIdLst"
+      zero_or_more "p:sldMasterId", as: :sldMasterId
+
+      def size = sldMasterId_list.size
+    end
+
+    # `p:sldMasterId`, a reference to one slide master.
+    class CT_SlideMasterIdListEntry < Element
+      tag "p:sldMasterId"
+      required_attr "r:id", type: ST::XsdString, as: :rId
+      optional_attr "id", type: ST::ST_SlideMasterId
+    end
+
+    # `p:sldSz`, the slide dimensions for the whole presentation.
+    class CT_SlideSize < Element
+      tag "p:sldSz"
+      required_attr "cx", type: ST::ST_SlideSizeCoordinate
+      required_attr "cy", type: ST::ST_SlideSizeCoordinate
+    end
+  end
+end

data/lib/ruby_pptx/oxml/section.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "ruby_pptx/oxml/element"
+require "ruby_pptx/oxml/content_model"
+require "ruby_pptx/oxml/simple_types"
+
+module Pptx
+  module Oxml
+    # `p:extLst`, the extension list on `p:presentation`.
+    class CT_PresentationExtensionList < Element
+      tag "p:extLst"
+      zero_or_more "p:ext", as: :ext
+    end
+
+    # `p:ext`, one extension, identified by its URI.
+    class CT_PresentationExtension < Element
+      tag "p:ext"
+      required_attr "uri", type: SimpleTypes::XsdString
+    end
+
+    # `p14:sldId`, a slide's membership in a section.
+    #
+    # Note this refers to the slide by its presentation-wide `p:sldId/@id`,
+    # not by a relationship.
+    class CT_SectionSlideId < Element
+      tag "p14:sldId"
+      required_attr "id", type: SimpleTypes::ST_SlideId
+    end
+
+    # `p14:sldIdLst`, the slides belonging to one section.
+    class CT_SectionSlideIdList < Element
+      tag "p14:sldIdLst"
+      zero_or_more "p14:sldId", as: :sldId
+    end
+
+    # `p14:section`, one named section of a presentation.
+    class CT_Section < Element
+      tag "p14:section"
+      required_attr "name", type: SimpleTypes::XsdString
+      required_attr "id", type: SimpleTypes::XsdString
+      one_and_only_one "p14:sldIdLst"
+
+      # PowerPoint identifies a section by a brace-wrapped uppercase GUID.
+      def self.new_id = "{#{SecureRandom.uuid.upcase}}"
+    end
+
+    # `p14:sectionLst`, the sections of a presentation.
+    class CT_SectionList < Element
+      tag "p14:sectionLst"
+      zero_or_more "p14:section", as: :section
+
+      def add_section(name, id = CT_Section.new_id)
+        build_from_xml(
+          %(<p14:section #{Ns.nsdecls("p14")} name="#{escape(name)}" id="#{id}">) \
+          "<p14:sldIdLst/></p14:section>"
+        ).tap { |element| append(element) }
+      end
+
+      def escape(text)
+        text.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;")
+      end
+    end
+  end
+end