ruby_pptx 0.1.0 → 0.2.0

data/lib/ruby_pptx/oxml/element.rb

@@ -1,17 +1,21 @@
 # frozen_string_literal: true
 
-require "nokogiri"
 require "ruby_pptx/errors"
+require "ruby_pptx/oxml/backend"
 require "ruby_pptx/oxml/ns"
 require "ruby_pptx/oxml/simple_types"
 
 module Pptx
   module Oxml
+    # The XML library in use, chosen once at load; see {Backend}.
+    BACKEND = Backend.select
+
     # 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.
+    # custom class per tag. Neither Nokogiri nor REXML has such a hook, so
+    # element classes register themselves here and {Element.wrap} does the
+    # dispatch.
     module Registry
       @classes = {}
 
@@ -29,17 +33,23 @@ module Pptx
         end
 
         # @return [Class] the registered class, or {Element} for an unmodelled tag
-        def class_for(clark_name) = @classes.fetch(clark_name, Element)
+        def class_for(clark_name)
+          @classes.fetch(clark_name, Element)
+        end
 
-        def registered = @classes.dup
+        def registered
+          @classes.dup
+        end
 
         # Test seam: forget registrations made by a spec.
-        def reset!(to) = (@classes = to)
+        def reset!(to)
+          (@classes = to)
+        end
       end
     end
 
-    # Wraps a `Nokogiri::XML::Node` and gives it the schema-aware behaviour of
-    # one OOXML element type.
+    # Wraps an XML node -- Nokogiri's or REXML's, see {Backend} -- 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:
@@ -71,7 +81,9 @@ module Pptx
         prefixed_tags.each { |t| Registry.register(Ns.qn(t), self) }
       end
 
-      def self.nsptag = @nsptags&.first
+      def self.nsptag
+        @nsptags&.first
+      end
 
       class << self
         attr_reader :nsptags
@@ -79,33 +91,24 @@ module Pptx
 
       # Wrap +node+ in the class registered for its tag.
       #
-      # @param node [Nokogiri::XML::Node]
+      # @param node [Object] a node of the active {Backend}
       # @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 = BACKEND.wrapper_cache(node)
         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)
+        wrap(BACKEND.parse(xml))
       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
+      # @return [Object] the wrapped node, a Nokogiri or REXML element
+      #   depending on the active {Backend}. An escape hatch: code that uses
+      #   it ties itself to one backend.
       attr_reader :node
 
       def initialize(node)
@@ -115,24 +118,42 @@ module Pptx
       # -- tree navigation -------------------------------------------------
 
       # @return [String] this element's prefixed tag, e.g. "p:sp"
-      def nsptag = Ns.prefixed_tag(Ns.clark_name_of(@node))
+      def nsptag
+        Ns.prefixed_tag(Ns.clark_name_of(@node))
+      end
 
-      def document = @node.document
+      # An opaque token for the document this element belongs to; equal
+      # (+equal?+) for two elements exactly when they share a document.
+      def document
+        BACKEND.document(@node)
+      end
 
-      def parent = Element.wrap(@node.parent.is_a?(Nokogiri::XML::Element) ? @node.parent : nil)
+      def parent
+        Element.wrap(BACKEND.parent_element(@node))
+      end
 
       # @return [Array<Element>] every child element, in document order
-      def element_children = @node.element_children.map { |child| Element.wrap(child) }
+      def element_children
+        BACKEND.element_children(@node).map { |child| Element.wrap(child) }
+      end
+
+      # @return [String] this element's tag in Clark notation, "{uri}local"
+      def clark_name
+        Ns.clark_name_of(@node)
+      end
 
       # First child element with +nsptag+, or nil.
-      def find(nsptag) = Element.wrap(raw_find(nsptag))
+      def find(nsptag)
+        Element.wrap(raw_find(nsptag))
+      end
 
       # 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) }
+        uri = Ns.nsuri(pfx)
+        BACKEND.element_children(@node)
+               .select { |c| BACKEND.local_name(c) == local && BACKEND.namespace_uri(c) == uri }
+               .map { |c| Element.wrap(c) }
       end
 
       # The first child matching any of +nsptags+, in the order given -- not in
@@ -147,8 +168,8 @@ module Pptx
 
       # 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
+        BACKEND.xpath(@node, expression, Ns::NSMAP).map do |result|
+          BACKEND.element?(result) ? Element.wrap(result) : result
         end
       end
 
@@ -159,67 +180,82 @@ module Pptx
       def insert_element_before(element, *successor_tags)
         successor = first_child_found_in(*successor_tags)
         if successor
-          successor.node.add_previous_sibling(adopt(element))
+          successor.add_previous_sibling(element)
         else
-          @node.add_child(adopt(element))
+          append(element)
         end
         element
       end
 
       def append(element)
-        @node.add_child(adopt(element))
+        BACKEND.append_child(@node, adopt(element))
+        element
+      end
+
+      # Make +element+ this element's first child.
+      def prepend(element)
+        BACKEND.prepend_child(@node, adopt(element))
+        element
+      end
+
+      # Put +element+ immediately before this one.
+      def add_previous_sibling(element)
+        BACKEND.insert_before(@node, adopt(element))
+        element
+      end
+
+      # Put +element+ immediately after this one.
+      def add_next_sibling(element)
+        BACKEND.insert_after(@node, 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 } }
+        nsptags.each { |nsptag| find_all(nsptag).each { |child| BACKEND.unlink(child.node) } }
         nil
       end
 
       def remove(element)
-        element.node.unlink
+        BACKEND.unlink(element.node)
         nil
       end
 
       # Create a new, empty element with +nsptag+, in *this* element's
-      # document.
+      # document, reusing a namespace declaration already in scope here.
       #
-      # 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.
+      # Build new elements this way rather than parsing them separately:
+      # Nokogiri re-creates a node adopted from another document, so the
+      # object built is not the object that ends up in the tree, and every
+      # wrapper held on it goes stale.
       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.
+        Element.wrap(BACKEND.build(@node, pfx, local, Ns.nsuri(pfx)))
+      end
+
+      # Parse an XML literal into this element's document, its prefixes
+      # resolved against the namespaces in scope here.
       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?
+        fragment = BACKEND.parse_fragment(@node, xml)
+        raise InvalidXmlError, "fragment produced no element: #{xml.inspect}" if fragment.nil?
 
-        Element.wrap(fragment.first)
+        Element.wrap(fragment)
+      end
+
+      # A copy of +element+, from any document, built into this one.
+      def import(element)
+        build_from_xml(element.to_xml)
       end
 
       # -- text content ----------------------------------------------------
 
       # @return [String] the element's text content
-      def text = @node.text
+      def text
+        BACKEND.text(@node)
+      end
 
       def text=(value)
-        @node.content = value.to_s
+        BACKEND.set_text(@node, value.to_s)
       end
 
       # Declare +prefix+ on this element even if nothing uses it yet.
@@ -227,7 +263,7 @@ module Pptx
       # 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)
+        BACKEND.declare_namespace(@node, prefix, Ns.nsuri(prefix))
         self
       end
 
@@ -241,62 +277,79 @@ module Pptx
       # from lxml.
       def get(attr_name)
         pfx, local = prefixed_attr_parts(attr_name)
-        return @node[attr_name.to_s] unless pfx
+        return BACKEND.get_attribute(@node, attr_name.to_s) unless pfx
 
-        @node.attribute_with_ns(local, Ns.nsuri(pfx))&.value
+        BACKEND.get_attribute_ns(@node, local, Ns.nsuri(pfx))
       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
+        if pfx
+          BACKEND.set_attribute_ns(@node, pfx, local, Ns.nsuri(pfx), value.to_s)
         else
-          namespace_for(@node, pfx)
-          @node["#{pfx}:#{local}"] = value.to_s
+          BACKEND.set_attribute(@node, attr_name.to_s, 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
+        if pfx
+          BACKEND.remove_attribute_ns(@node, local, Ns.nsuri(pfx))
+        else
+          BACKEND.remove_attribute(@node, attr_name.to_s)
+        end
         nil
       end
 
-      def attribute?(attr_name) = !get(attr_name).nil?
+      def attribute?(attr_name)
+        !get(attr_name).nil?
+      end
 
       # -- serialization and equality --------------------------------------
 
       # Pretty-printed XML for this element, without a declaration. For
       # debugging and specs.
-      def xml = @node.to_xml(indent: 2)
+      def xml
+        BACKEND.pretty_xml(@node)
+      end
+
+      # Compact XML for this element, without a declaration.
+      def to_xml
+        BACKEND.to_xml(@node)
+      end
 
-      def to_s = xml
+      def to_s
+        xml
+      end
 
-      def ==(other) = other.is_a?(Element) && other.node.equal?(@node)
+      def ==(other)
+        other.is_a?(Element) && other.node.equal?(@node)
+      end
       alias eql? ==
 
-      def hash = @node.object_id.hash
+      def hash
+        @node.object_id.hash
+      end
 
-      def inspect = "#<#{self.class.name} <#{nsptag}> children=#{@node.element_children.size}>"
+      def inspect
+        "#<#{self.class.name} <#{nsptag}> children=#{BACKEND.element_children(@node).size}>"
+      end
 
       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 }
+        BACKEND.element_children(@node).find do |c|
+          BACKEND.local_name(c) == local && BACKEND.namespace_uri(c) == uri
+        end
       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)
+        return node if BACKEND.document(node).equal?(document)
 
         raise ArgumentError,
               "cannot insert an element created in a different document; " \
@@ -308,22 +361,6 @@ module Pptx
 
         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

@@ -8,7 +8,7 @@ module Pptx
     #
     # - 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
+    # - a backend node, name + namespace  -- what the parser hands back
     module Ns
       NSMAP = {
         "a" => "http://schemas.openxmlformats.org/drawingml/2006/main",
@@ -78,7 +78,7 @@ module Pptx
         "#{pfx}:#{local}"
       end
 
-      # The subset of NSMAP for +prefixes+, in the shape Nokogiri's #xpath wants.
+      # The subset of NSMAP for +prefixes+, in the shape an XPath query wants.
       #
       #   namespaces("a", "p") #=> {"a" => "...", "p" => "..."}
       def namespaces(*prefixes)
@@ -93,12 +93,12 @@ module Pptx
         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]
+      # The Clark name of a node of the active XML backend, suitable as an
+      # element-registry key.
       def clark_name_of(node)
-        href = node.namespace&.href
-        href ? "{#{href}}#{node.name}" : node.name
+        backend = BACKEND
+        href = backend.namespace_uri(node)
+        href ? "{#{href}}#{backend.local_name(node)}" : backend.local_name(node)
       end
 
       # ["p", "cSld"] for "p:cSld".

data/lib/ruby_pptx/oxml/presentation.rb

@@ -61,9 +61,13 @@ module Pptx
       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 add_slide_id(r_id)
+        add_sldId(id: next_id, rId: r_id)
+      end
 
-      def size = sldId_list.size
+      def size
+        sldId_list.size
+      end
 
       private
 
@@ -90,7 +94,9 @@ module Pptx
       tag "p:sldMasterIdLst"
       zero_or_more "p:sldMasterId", as: :sldMasterId
 
-      def size = sldMasterId_list.size
+      def size
+        sldMasterId_list.size
+      end
     end
 
     # `p:sldMasterId`, a reference to one slide master.

data/lib/ruby_pptx/oxml/section.rb

@@ -42,7 +42,9 @@ module Pptx
       one_and_only_one "p14:sldIdLst"
 
       # PowerPoint identifies a section by a brace-wrapped uppercase GUID.
-      def self.new_id = "{#{SecureRandom.uuid.upcase}}"
+      def self.new_id
+        "{#{SecureRandom.uuid.upcase}}"
+      end
     end
 
     # `p14:sectionLst`, the sections of a presentation.

data/lib/ruby_pptx/oxml/shapes/autoshape.rb

@@ -25,7 +25,9 @@ module Pptx
       required_attr "prst", type: Enum::MSO_AUTO_SHAPE_TYPE
 
       # The adjustment guides, in document order.
-      def gd_list = avLst ? avLst.gd_list : []
+      def gd_list
+        avLst ? avLst.gd_list : []
+      end
 
       # Replace the adjustment values with +name_value_pairs+.
       def rewrite_guides(name_value_pairs)
@@ -80,11 +82,17 @@ module Pptx
       optional_attr "w", type: SimpleTypes::ST_PositiveCoordinate
       optional_attr "h", type: SimpleTypes::ST_PositiveCoordinate
 
-      def move_to(x, y) = add_moveTo.point_at(x, y)
+      def move_to(x, y)
+        add_moveTo.point_at(x, y)
+      end
 
-      def line_to(x, y) = add_lnTo.point_at(x, y)
+      def line_to(x, y)
+        add_lnTo.point_at(x, y)
+      end
 
-      def close_contour = add_close
+      def close_contour
+        add_close
+      end
     end
 
     # `a:pathLst`, the contours of a freeform shape.
@@ -254,7 +262,9 @@ module Pptx
           XML
         end
 
-        def escape(text) = text.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub('"', "&quot;")
+        def escape(text)
+          text.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub('"', "&quot;")
+        end
 
         DEFAULT_STYLE = <<~XML
           <p:style>
@@ -276,7 +286,9 @@ module Pptx
 
       # A text body added to a shape that has none needs the minimum structure
       # the schema requires, not an empty element.
-      def new_txBody = CT_TextBody.new_element(self)
+      def new_txBody
+        CT_TextBody.new_element(self)
+      end
 
       # Start a new contour on this shape's custom geometry.
       #
@@ -288,23 +300,37 @@ module Pptx
         geometry.get_or_add_pathLst.add_path_of(width, height)
       end
 
-      def prstGeom = spPr.prstGeom
+      def prstGeom
+        spPr.prstGeom
+      end
 
-      def prst = prstGeom&.prst
+      def prst
+        prstGeom&.prst
+      end
 
-      def ln = spPr.ln
+      def ln
+        spPr.ln
+      end
 
-      def get_or_add_ln = spPr.get_or_add_ln
+      def get_or_add_ln
+        spPr.get_or_add_ln
+      end
 
       # A shape has custom geometry -- is a freeform -- when it carries
       # `a:custGeom` in place of `a:prstGeom`.
-      def custom_geometry? = !spPr.custGeom.nil?
+      def custom_geometry?
+        !spPr.custGeom.nil?
+      end
 
       # A text box is an `p:sp` whose `p:cNvSpPr` says `txBox="1"`.
-      def textbox? = nvSpPr.cNvSpPr.txBox == true
+      def textbox?
+        nvSpPr.cNvSpPr.txBox == true
+      end
 
       # An auto shape has preset geometry and is not a text box.
-      def autoshape? = !prstGeom.nil? && nvSpPr.cNvSpPr.txBox != true
+      def autoshape?
+        !prstGeom.nil? && nvSpPr.cNvSpPr.txBox != true
+      end
     end
   end
 end

data/lib/ruby_pptx/oxml/shapes/groupshape.rb

@@ -26,21 +26,29 @@ module Pptx
       SHAPE_TAGS = %w[p:sp p:grpSp p:graphicFrame p:cxnSp p:pic p:contentPart].freeze
 
       # A group's transform hangs off `p:grpSpPr`, not `p:spPr`.
-      def xfrm = grpSpPr.xfrm
+      def xfrm
+        grpSpPr.xfrm
+      end
 
-      def get_or_add_xfrm = grpSpPr.get_or_add_xfrm
+      def get_or_add_xfrm
+        grpSpPr.get_or_add_xfrm
+      end
 
-      def chOff = get_or_add_xfrm.get_or_add_chOff
+      def chOff
+        get_or_add_xfrm.get_or_add_chOff
+      end
 
-      def chExt = get_or_add_xfrm.get_or_add_chExt
+      def chExt
+        get_or_add_xfrm.get_or_add_chExt
+      end
 
       # Each shape child, in document order.
       def shape_elements
         return enum_for(:shape_elements) unless block_given?
 
         tags = SHAPE_TAGS.map { |t| Ns.qn(t) }
-        @node.element_children.each do |child|
-          yield Element.wrap(child) if tags.include?(Ns.clark_name_of(child))
+        element_children.each do |child|
+          yield child if tags.include?(child.clark_name)
         end
       end
 
@@ -210,7 +218,7 @@ module Pptx
       def adopt_xml(element)
         return element if element.document.equal?(document)
 
-        build_from_xml(element.node.to_xml)
+        import(element)
       end
     end
   end