tilia-xml 1.2.0

data/lib/tilia/xml/element/elements.rb

@@ -0,0 +1,109 @@
+module Tilia
+  module Xml
+    module Element
+      # 'Elements' is a simple list of elements, without values or attributes.
+      # For example, Elements will parse:
+      #
+      # <?xml version="1.0"?>
+      # <s:root xmlns:s="http://sabredav.org/ns">
+      #   <s:elem1 />
+      #   <s:elem2 />
+      #   <s:elem3 />
+      #   <s:elem4>content</s:elem4>
+      #   <s:elem5 attr="val" />
+      # </s:root>
+      #
+      # Into:
+      #
+      # [
+      #   "{http://sabredav.org/ns}elem1",
+      #   "{http://sabredav.org/ns}elem2",
+      #   "{http://sabredav.org/ns}elem3",
+      #   "{http://sabredav.org/ns}elem4",
+      #   "{http://sabredav.org/ns}elem5",
+      # ];
+      class Elements
+        include Element
+
+        protected
+
+        # Value to serialize
+        #
+        # @return [Array]
+        attr_accessor :value
+
+        public
+
+        # Constructor
+        #
+        # @param [Array] value
+        def initialize(value = [])
+          @value = value
+        end
+
+        # The xml_serialize metod is called during xml writing.
+        #
+        # Use the writer argument to write its own xml serialization.
+        #
+        # An important note: do _not_ create a parent element. Any element
+        # implementing XmlSerializble should only ever write what's considered
+        # its 'inner xml'.
+        #
+        # The parent of the current element is responsible for writing a
+        # containing element.
+        #
+        # This allows serializers to be re-used for different element names.
+        #
+        # If you are opening new elements, you must also close them again.
+        #
+        # @param [Writer] writer
+        # @return [void]
+        def xml_serialize(writer)
+          @value.each do |val|
+            writer.write_element(val)
+          end
+        end
+
+        # The deserialize method is called during xml parsing.
+        #
+        # This method is called statictly, this is because in theory this method
+        # may be used as a type of constructor, or factory method.
+        #
+        # Often you want to return an instance of the current class, but you are
+        # free to return other data as well.
+        #
+        # Important note 2: You are responsible for advancing the reader to the
+        # next element. Not doing anything will result in a never-ending loop.
+        #
+        # If you just want to skip parsing for this element altogether, you can
+        # just call reader->next();
+        #
+        # reader->parseSubTree() will parse the entire sub-tree, and advance to
+        # the next element.
+        #
+        # @param [Reader] reader
+        # @return mixed
+        def self.xml_deserialize(reader)
+          # If there's no children, we don't do anything.
+          if reader.empty_element?
+            reader.next
+            return []
+          end
+          reader.read
+          current_depth = reader.depth
+
+          values = []
+          loop do
+            if reader.node_type == ::LibXML::XML::Reader::TYPE_ELEMENT
+              values << reader.clark
+            end
+            break unless reader.depth >= current_depth && reader.next
+          end
+
+          reader.next
+          values
+        end
+      end
+    end
+  end
+end

data/lib/tilia/xml/element/key_value.rb

@@ -0,0 +1,110 @@
+module Tilia
+  module Xml
+    module Element
+      # 'KeyValue' parses out all child elements from a single node, and outputs a
+      # key=>value struct.
+      #
+      # Attributes will be removed, and duplicate child elements are discarded.
+      # Complex values within the elements will be parsed by the 'standard' parser.
+      #
+      # For example, KeyValue will parse:
+      #
+      # <?xml version="1.0"?>
+      # <s:root xmlns:s="http://sabredav.org/ns">
+      #   <s:elem1>value1</s:elem1>
+      #   <s:elem2>value2</s:elem2>
+      #   <s:elem3 />
+      # </s:root>
+      #
+      # Into:
+      #
+      # [
+      #   "{http://sabredav.org/ns}elem1" => "value1",
+      #   "{http://sabredav.org/ns}elem2" => "value2",
+      #   "{http://sabredav.org/ns}elem3" => null,
+      # ];
+      class KeyValue
+        include Element
+
+        protected
+
+        # Value to serialize
+        #
+        # @return [Array]
+        attr_accessor :value
+
+        public
+
+        # Constructor
+        #
+        # @param [Array] value
+        def initialize(value = [])
+          @value = value
+        end
+
+        # The xml_serialize metod is called during xml writing.
+        #
+        # Use the writer argument to write its own xml serialization.
+        #
+        # An important note: do _not_ create a parent element. Any element
+        # implementing XmlSerializble should only ever write what's considered
+        # its 'inner xml'.
+        #
+        # The parent of the current element is responsible for writing a
+        # containing element.
+        #
+        # This allows serializers to be re-used for different element names.
+        #
+        # If you are opening new elements, you must also close them again.
+        #
+        # @param [Writer] writer
+        # @return [void]
+        def xml_serialize(writer)
+          writer.write(@value)
+        end
+
+        # The deserialize method is called during xml parsing.
+        #
+        # This method is called staticly, this is because in theory this method
+        # may be used as a type of constructor, or factory method.
+        #
+        # Often you want to return an instance of the current class, but you are
+        # free to return other data as well.
+        #
+        # Important note 2: You are responsible for advancing the reader to the
+        # next element. Not doing anything will result in a never-ending loop.
+        #
+        # If you just want to skip parsing for this element altogether, you can
+        # just call reader->next();
+        #
+        # reader->parseInnerTree() will parse the entire sub-tree, and advance to
+        # the next element.
+        #
+        # @param [Reader] reader
+        # @return mixed
+        def self.xml_deserialize(reader)
+          # If there's no children, we don't do anything.
+          if reader.empty_element?
+            reader.next
+            return {}
+          end
+
+          values = {}
+
+          reader.read
+          loop do
+            if reader.node_type == ::LibXML::XML::Reader::TYPE_ELEMENT
+              clark = reader.clark
+              values[clark] = reader.parse_current_element['value']
+            else
+              reader.read
+            end
+            break unless reader.node_type != ::LibXML::XML::Reader::TYPE_END_ELEMENT
+          end
+          reader.read
+          values
+        end
+      end
+    end
+  end
+end

data/lib/tilia/xml/element/uri.rb

@@ -0,0 +1,98 @@
+module Tilia
+  module Xml
+    module Element
+      # Uri element.
+      #
+      # This represents a single uri. An example of how this may be encoded:
+      #
+      #    <link>/foo/bar</link>
+      #    <d:href xmlns:d="DAV:">http://example.org/hi</d:href>
+      #
+      # If the uri is relative, it will be automatically expanded to an absolute
+      # url during writing and reading, if the contextUri property is set on the
+      # reader and/or writer.
+      class Uri
+        include Element
+
+        protected
+
+        # Uri element value.
+        #
+        # @return [String]
+        attr_accessor :value
+
+        public
+
+        # Constructor
+        #
+        # @param [String] value
+        def initialize(value)
+          @value = value
+        end
+
+        # The xml_serialize metod is called during xml writing.
+        #
+        # Use the writer argument to write its own xml serialization.
+        #
+        # An important note: do _not_ create a parent element. Any element
+        # implementing XmlSerializble should only ever write what's considered
+        # its 'inner xml'.
+        #
+        # The parent of the current element is responsible for writing a
+        # containing element.
+        #
+        # This allows serializers to be re-used for different element names.
+        #
+        # If you are opening new elements, you must also close them again.
+        #
+        # @param [Writer] writer
+        # @return [void]
+        def xml_serialize(writer)
+          writer.write_string(
+            ::Tilia::Uri.resolve(
+              writer.context_uri,
+              @value
+            )
+          )
+        end
+
+        # This method is called during xml parsing.
+        #
+        # This method is called statically, this is because in theory this method
+        # may be used as a type of constructor, or factory method.
+        #
+        # Often you want to return an instance of the current class, but you are
+        # free to return other data as well.
+        #
+        # Important note 2: You are responsible for advancing the reader to the
+        # next element. Not doing anything will result in a never-ending loop.
+        #
+        # If you just want to skip parsing for this element altogether, you can
+        # just call reader->next();
+        #
+        # reader->parseSubTree() will parse the entire sub-tree, and advance to
+        # the next element.
+        #
+        # @param [Reader] reader
+        # @return mixed
+        def self.xml_deserialize(reader)
+          new(
+            ::Tilia::Uri.resolve(
+              reader.context_uri,
+              reader.read_text
+            )
+          )
+        end
+
+        # TODO: document
+        def ==(other)
+          if other.is_a? self.class
+            other.instance_eval { @value } == @value
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tilia/xml/element/xml_fragment.rb

@@ -0,0 +1,128 @@
+module Tilia
+  module Xml
+    module Element
+      # The XmlFragment element allows you to extract a portion of your xml tree,
+      # and get a well-formed xml string.
+      #
+      # This goes a bit beyond `innerXml` and friends, as we'll also match all the
+      # correct namespaces.
+      #
+      # Please note that the XML fragment:
+      #
+      # 1. Will not have an <?xml declaration.
+      # 2. Or a DTD
+      # 3. It will have all the relevant xmlns attributes.
+      # 4. It may not have a root element.
+      class XmlFragment
+        include Element
+
+        protected
+
+        attr_accessor :xml
+
+        public
+
+        def initialize(xml)
+          @xml = xml
+        end
+
+        # get_xml replaced by xml
+
+        # The xml_serialize metod is called during xml writing.
+        #
+        # Use the writer argument to write its own xml serialization.
+        #
+        # An important note: do _not_ create a parent element. Any element
+        # implementing XmlSerializble should only ever write what's considered
+        # its 'inner xml'.
+        #
+        # The parent of the current element is responsible for writing a
+        # containing element.
+        #
+        # This allows serializers to be re-used for different element names.
+        #
+        # If you are opening new elements, you must also close them again.
+        #
+        # @param [Writer] writer
+        # @return [void]
+        def xml_serialize(writer)
+          reader = Reader.new
+
+          # Wrapping the xml in a container, so root-less values can still be
+          # parsed.
+          xml = <<XML
+<?xml version="1.0"?>
+<xml-fragment xmlns="http://sabre.io/ns">#{@xml}</xml-fragment>
+XML
+
+          reader.xml(xml)
+
+          while reader.read
+            if reader.depth < 1
+              # Skipping the root node.
+              next
+            end
+
+            case reader.node_type
+            when ::LibXML::XML::Reader::TYPE_ELEMENT
+              writer.start_element(reader.clark)
+              empty = reader.empty_element?
+
+              while reader.move_to_next_attribute != 0
+                case reader.namespace_uri
+                when '', nil # RUBY namespace_uri = nil ...
+                  writer.write_attribute(reader.local_name, reader.value)
+                when 'http://www.w3.org/2000/xmlns/'
+                  # Skip namespace declarations
+                else
+                  writer.write_attribute(reader.clark, reader.value)
+                end
+              end
+
+              writer.end_element if empty
+            when ::LibXML::XML::Reader::TYPE_CDATA,
+                ::LibXML::XML::Reader::TYPE_TEXT
+              writer.write_string(reader.value)
+            when ::LibXML::XML::Reader::TYPE_END_ELEMENT
+              writer.end_element
+            end
+          end
+        end
+
+        # The deserialize method is called during xml parsing.
+        #
+        # This method is called statictly, this is because in theory this method
+        # may be used as a type of constructor, or factory method.
+        #
+        # Often you want to return an instance of the current class, but you are
+        # free to return other data as well.
+        #
+        # You are responsible for advancing the reader to the next element. Not
+        # doing anything will result in a never-ending loop.
+        #
+        # If you just want to skip parsing for this element altogether, you can
+        # just call reader->next();
+        #
+        # reader->parseInnerTree() will parse the entire sub-tree, and advance to
+        # the next element.
+        #
+        # @param [Reader] reader
+        # @return mixed
+        def self.xml_deserialize(reader)
+          result = new(reader.read_inner_xml)
+          reader.next
+          result
+        end
+
+        # TODO: document
+        def ==(other)
+          if other.is_a? self.class
+            other.xml == @xml
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tilia/xml/element.rb

@@ -0,0 +1,22 @@
+module Tilia
+  module Xml
+    # This is the XML element interface.
+    #
+    # Elements are responsible for serializing and deserializing part of an XML
+    # document into PHP values.
+    #
+    # It combines XmlSerializable and XmlDeserializable into one logical class
+    # that does both.
+    module Element
+      include XmlSerializable
+      include XmlDeserializable
+
+      require 'tilia/xml/element/base'
+      require 'tilia/xml/element/cdata'
+      require 'tilia/xml/element/elements'
+      require 'tilia/xml/element/key_value'
+      require 'tilia/xml/element/uri'
+      require 'tilia/xml/element/xml_fragment'
+    end
+  end
+end

data/lib/tilia/xml/lib_xml_exception.rb

@@ -0,0 +1,9 @@
+module Tilia
+  module Xml
+    # This exception is thrown when the Readers runs into a parsing error.
+    #
+    # This exception effectively wraps 1 or more LibXMLError objects.
+    class LibXmlException < ParseException
+    end
+  end
+end

data/lib/tilia/xml/parse_exception.rb

@@ -0,0 +1,7 @@
+module Tilia
+  module Xml
+    # This is a base exception for any exception related to parsing xml files.
+    class ParseException < ::StandardError
+    end
+  end
+end