tilia-xml 1.2.0

data/lib/tilia/xml/reader.rb

@@ -0,0 +1,240 @@
+require 'libxml'
+require 'stringio'
+LibXML::XML::Error.set_handler(&LibXML::XML::Error::QUIET_HANDLER)
+
+module Tilia
+  module Xml
+    # The Reader class expands upon PHP's built-in XMLReader.
+    #
+    # The intended usage, is to assign certain XML elements to PHP classes. These
+    # need to be registered using the element_map public property.
+    #
+    # After this is done, a single call to parse() will parse the entire document,
+    # and delegate sub-sections of the document to element classes.
+    class Reader
+      include Tilia::Xml::ContextStackTrait
+
+      # Returns the current nodename in clark-notation.
+      #
+      # For example: "{http://www.w3.org/2005/Atom}feed".
+      # Or if no namespace is defined: "{}feed".
+      #
+      # This method returns null if we're not currently on an element.
+      #
+      # @return [String, nil]
+      def clark
+        return nil unless local_name
+
+        "{#{namespace_uri}}#{local_name}"
+      end
+
+      # Reads the entire document.
+      #
+      # This function returns an array with the following three elements:
+      #    * name - The root element name.
+      #    * value - The value for the root element.
+      #    * attributes - An array of attributes.
+      #
+      # This function will also disable the standard libxml error handler (which
+      # usually just results in PHP errors), and throw exceptions instead.
+      #
+      # @return [Hash]
+      def parse
+        begin
+          nil while node_type != ::LibXML::XML::Reader::TYPE_ELEMENT && read # noop
+
+          result = parse_current_element
+        rescue ::LibXML::XML::Error => e
+          raise Tilia::Xml::LibXmlException, e.to_s
+        end
+
+        result
+      end
+
+      # parse_get_elements parses everything in the current sub-tree,
+      # and returns a an array of elements.
+      #
+      # Each element has a 'name', 'value' and 'attributes' key.
+      #
+      # If the the element didn't contain sub-elements, an empty array is always
+      # returned. If there was any text inside the element, it will be
+      # discarded.
+      #
+      # If the element_map argument is specified, the existing element_map will
+      # be overridden while parsing the tree, and restored after this process.
+      #
+      # @param [Hash] element_map
+      # @return [Array]
+      def parse_get_elements(element_map = nil)
+        result = parse_inner_tree(element_map)
+
+        return [] unless result.is_a?(Array)
+        result
+      end
+
+      # Parses all elements below the current element.
+      #
+      # This method will return a string if this was a text-node, or an array if
+      # there were sub-elements.
+      #
+      # If there's both text and sub-elements, the text will be discarded.
+      #
+      # If the element_map argument is specified, the existing element_map will
+      # be overridden while parsing the tree, and restored after this process.
+      #
+      # @param [Hash] element_map
+      # @return [Array, String]
+      def parse_inner_tree(element_map = nil)
+        text = nil
+        elements = []
+
+        if node_type == ::LibXML::XML::Reader::TYPE_ELEMENT && self.empty_element?
+          # Easy!
+          self.next
+          return nil
+        end
+
+        unless element_map.nil?
+          push_context
+          @element_map = element_map
+        end
+
+        return false unless read
+
+        loop do
+          # RUBY: Skip is_valid block
+
+          case node_type
+          when ::LibXML::XML::Reader::TYPE_ELEMENT
+            elements << parse_current_element
+          when ::LibXML::XML::Reader::TYPE_TEXT,
+              ::LibXML::XML::Reader::TYPE_CDATA
+            text ||= ''
+            text += value
+            read
+          when ::LibXML::XML::Reader::TYPE_END_ELEMENT
+            # Ensuring we are moving the cursor after the end element.
+            read
+            break
+          when ::LibXML::XML::Reader::TYPE_NONE
+            fail Tilia::Xml::ParseException, 'We hit the end of the document prematurely. This likely means that some parser "eats" too many elements. Do not attempt to continue parsing.'
+          else
+            # Advance to the next element
+            read
+          end
+        end
+
+        pop_context unless element_map.nil?
+
+        elements.any? ? elements : text
+      end
+
+      # Reads all text below the current element, and returns this as a string.
+      #
+      # @return [String]
+      def read_text
+        result = ''
+        previous_depth = depth
+
+        while read && depth != previous_depth
+          result += value if [
+            ::LibXML::XML::Reader::TYPE_TEXT,
+            ::LibXML::XML::Reader::TYPE_CDATA,
+            ::LibXML::XML::Reader::TYPE_WHITESPACE
+          ].include? node_type
+        end
+
+        result
+      end
+
+      # Parses the current XML element.
+      #
+      # This method returns arn array with 3 properties:
+      #   * name - A clark-notation XML element name.
+      #   * value - The parsed value.
+      #   * attributes - A key-value list of attributes.
+      #
+      # @return [Hash]
+      def parse_current_element
+        name = clark
+
+        attributes = {}
+
+        attributes = parse_attributes if self.has_attributes?
+
+        if @element_map.key? name
+          deserializer = @element_map[name]
+
+          if deserializer.is_a?(Class) && deserializer.include?(XmlDeserializable)
+            value = deserializer.xml_deserialize(self)
+          elsif deserializer.is_a? Proc
+            value = deserializer.call(self)
+          else
+            # Omit php stuff for error creation
+            fail "Could not use this type as a deserializer: #{deserializer.inspect}"
+          end
+        else
+          value = Element::Base.xml_deserialize(self)
+        end
+        {
+          'name'       => name,
+          'value'      => value,
+          'attributes' => attributes
+        }
+      end
+
+      # Grabs all the attributes from the current element, and returns them as a
+      # key-value array.
+      #
+      # If the attributes are part of the same namespace, they will simply be
+      # short keys. If they are defined on a different namespace, the attribute
+      # name will be retured in clark-notation.
+      #
+      # @return [Hash]
+      def parse_attributes
+        attributes = {}
+
+        while move_to_next_attribute != 0
+          if namespace_uri
+            # Ignoring 'xmlns', it doesn't make any sense.
+            next if namespace_uri == 'http://www.w3.org/2000/xmlns/'
+
+            name = clark
+            attributes[name] = value
+          else
+            attributes[local_name] = value
+          end
+        end
+
+        move_to_element
+
+        attributes
+      end
+
+      # TODO: document this
+      def initialize
+        initialize_context_stack_attributes
+      end
+
+      # TODO: documentation
+      def xml(input)
+        fail 'XML document already loaded' if @reader
+
+        if input.is_a? String
+          @reader = ::LibXML::XML::Reader.string(input)
+        elsif input.is_a? File
+          @reader = ::LibXML::XML::Reader.file(input)
+        elsif input.is_a? StringIO
+          @reader = ::LibXML::XML::Reader.io(input)
+        else
+          fail 'Unable to load XML document'
+        end
+      end
+
+      # TODO: documentation
+      def method_missing(name, *args)
+        @reader.send(name, *args)
+      end
+    end
+  end
+end

data/lib/tilia/xml/service.rb

@@ -0,0 +1,151 @@
+module Tilia
+  module Xml
+    # XML parsing and writing service.
+    #
+    # You are encouraged to make a instance of this for your application and
+    # potentially extend it, as a central API point for dealing with xml and
+    # configuring the reader and writer.
+    class Service
+      # This is the element map. It contains a list of XML elements (in clark
+      # notation) as keys and PHP class names as values.
+      #
+      # The PHP class names must implement Sabre\Xml\Element.
+      #
+      # Values may also be a callable. In that case the function will be called
+      # directly.
+      #
+      # @return [Hash]
+      attr_accessor :element_map
+
+      # This is a list of namespaces that you want to give default prefixes.
+      #
+      # You must make sure you create this entire list before starting to write.
+      # They should be registered on the root element.
+      #
+      # @return [Hash]
+      attr_accessor :namespace_map
+
+      # Returns a fresh XML Reader
+      #
+      # @return [Reader]
+      def reader
+        reader = Reader.new
+        reader.element_map = @element_map
+        reader
+      end
+
+      # Returns a fresh xml writer
+      #
+      # @return [Writer]
+      def writer
+        writer = Writer.new
+        writer.namespace_map = @namespace_map
+        writer
+      end
+
+      # Parses a document in full.
+      #
+      # Input may be specified as a string or readable stream resource.
+      # The returned value is the value of the root document.
+      #
+      # Specifying the context_uri allows the parser to figure out what the URI
+      # of the document was. This allows relative URIs within the document to be
+      # expanded easily.
+      #
+      # The root_element_name is specified by reference and will be populated
+      # with the root element name of the document.
+      #
+      # @param [String, File, StringIO] input
+      # @param [String, nil] context_uri
+      # @param [String, nil] root_element_name
+      # @raise [ParseException]
+      # @return [Array, Object, String]
+      def parse(input, context_uri = nil, root_element_name = nil)
+        # Skip php short commings
+        reader = self.reader
+        reader.context_uri = context_uri
+        reader.xml(input)
+
+        result = reader.parse
+        root_element_name.replace(result['name'])
+        result['value']
+      end
+
+      # Parses a document in full, and specify what the expected root element
+      # name is.
+      #
+      # This function works similar to parse, but the difference is that the
+      # user can specify what the expected name of the root element should be,
+      # in clark notation.
+      #
+      # This is useful in cases where you expected a specific document to be
+      # passed, and reduces the amount of if statements.
+      #
+      # @param [String] root_element_name
+      # @param [String, File, StringIO] input
+      # @param [String, nil] context_uri
+      # @return [void]
+      def expect(root_element_name, input, context_uri = nil)
+        # Skip php short commings
+        reader = self.reader
+        reader.context_uri = context_uri
+        reader.xml(input)
+
+        result = reader.parse
+        if root_element_name != result['name']
+          fail Tilia::Xml::ParseException, "Expected #{root_element_name} but received #{result['name']} as the root element"
+        end
+        result['value']
+      end
+
+      # Generates an XML document in one go.
+      #
+      # The $rootElement must be specified in clark notation.
+      # The value must be a string, an array or an object implementing
+      # XmlSerializable. Basically, anything that's supported by the Writer
+      # object.
+      #
+      # context_uri can be used to specify a sort of 'root' of the PHP application,
+      # in case the xml document is used as a http response.
+      #
+      # This allows an implementor to easily create URI's relative to the root
+      # of the domain.
+      #
+      # @param [String] root_element_name
+      # @param [String, Array, XmlSerializable] value
+      # @param [String, nil] context_uri
+      # @return [void]
+      def write(root_element_name, value, context_uri = nil)
+        writer = self.writer
+        writer.open_memory
+        writer.context_uri = context_uri
+        writer.set_indent(true)
+        writer.start_document
+        writer.write_element(root_element_name, value)
+        writer.output_memory
+      end
+
+      # Parses a clark-notation string, and returns the namespace and element
+      # name components.
+      #
+      # If the string was invalid, it will throw an InvalidArgumentException.
+      #
+      # @param [String] str
+      # @raise [InvalidArgumentException]
+      # @return [Array]
+      def self.parse_clark_notation(str)
+        if str =~ /^{([^}]*)}(.*)/
+          [Regexp.last_match[1], Regexp.last_match[2]]
+        else
+          fail ArgumentError, "'#{str}' is not a valid clark-notation formatted string"
+        end
+      end
+
+      # TODO: document
+      def initialize
+        @element_map = {}
+        @namespace_map = {}
+      end
+    end
+  end
+end

data/lib/tilia/xml/version.rb

@@ -0,0 +1,9 @@
+module Tilia
+  module Xml
+    # This class contains the version number for this package.
+    class Version
+      # Full version number
+      VERSION = '1.2.0'
+    end
+  end
+end

data/lib/tilia/xml/writer.rb

@@ -0,0 +1,261 @@
+require 'libxml'
+module Tilia
+  module Xml
+    # The XML Writer class.
+    #
+    # This class works exactly as PHP's built-in XMLWriter, with a few additions.
+    #
+    # Namespaces can be registered beforehand, globally. When the first element is
+    # written, namespaces will automatically be declared.
+    #
+    # The write_attribute, startElement and write_element can now take a
+    # clark-notation element name (example: {http://www.w3.org/2005/Atom}link).
+    #
+    # If, when writing the namespace is a known one a prefix will automatically be
+    # selected, otherwise a random prefix will be generated.
+    #
+    # Instead of standard string values, the writer can take Element classes (as
+    # defined by this library) to delegate the serialization.
+    #
+    # The write() method can take array structures to quickly write out simple xml
+    # trees.
+    class Writer
+      include ContextStackTrait
+
+      protected
+
+      # Any namespace that the writer is asked to write, will be added here.
+      #
+      # Any of these elements will get a new namespace definition *every single
+      # time* they are used, but this array allows the writer to make sure that
+      # the prefixes are consistent anyway.
+      #
+      # @return [Hash]
+      attr_accessor :adhoc_namespaces
+
+      # When the first element is written, this flag is set to true.
+      #
+      # This ensures that the namespaces in the namespaces map are only written
+      # once.
+      #
+      # @return [Boolean]
+      attr_accessor :namespaces_written
+
+      public
+
+      # Writes a value to the output stream.
+      #
+      # The following values are supported:
+      #   1. Scalar values will be written as-is, as text.
+      #   2. Null values will be skipped (resulting in a short xml tag).
+      #   3. If a value is an instance of an Element class, writing will be
+      #      delegated to the object.
+      #   4. If a value is an array, two formats are supported.
+      #
+      #  Array format 1:
+      #  [
+      #    "{namespace}name1" => "..",
+      #    "{namespace}name2" => "..",
+      #  ]
+      #
+      #  One element will be created for each key in this array. The values of
+      #  this array support any format this method supports (this method is
+      #  called recursively).
+      #
+      #  Array format 2:
+      #
+      #  [
+      #    [
+      #      "name" => "{namespace}name1"
+      #      "value" => "..",
+      #      "attributes" => [
+      #          "attr" => "attribute value",
+      #      ]
+      #    ],
+      #    [
+      #      "name" => "{namespace}name1"
+      #      "value" => "..",
+      #      "attributes" => [
+      #          "attr" => "attribute value",
+      #      ]
+      #    ]
+      # ]
+      #
+      # @param value
+      # @return [void]
+      def write(value)
+        if value.is_a?(Numeric) || value.is_a?(String)
+          write_string(value.to_s)
+        elsif value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          write_string(value.to_s)
+        elsif value.is_a? XmlSerializable
+          value.xml_serialize(self)
+        elsif value.nil?
+          # noop
+        elsif value.is_a?(Hash) || value.is_a?(Array)
+          # Code for ruby implementation
+          if value.is_a?(Array)
+            hash = {}
+            value.each_with_index do |v, i|
+              hash[i] = v
+            end
+            value = hash
+          end
+
+          value.each do |name, item|
+            if name.is_a? Fixnum
+              # This item has a numeric index. We expect to be an array with a name and a value.
+              unless item.is_a?(Hash) && item.key?('name') && item.key?('value')
+                fail ArgumentError, 'When passing an array to ->write with numeric indices, every item must be an array containing the "name" and "value" key'
+              end
+
+              attributes = item.key?('attributes') ? item['attributes'] : []
+              name = item['name']
+              item = item['value']
+            elsif item.is_a?(Hash) && item.key?('value')
+              # This item has a text index. We expect to be an array with a value and optional attributes.
+              attributes = item.key?('attributes') ? item['attributes'] : []
+              item = item['value']
+            else
+              # If it's an array with text-indices, we expect every item's
+              # key to be an xml element name in clark notation.
+              # No attributes can be passed.
+              attributes = []
+            end
+
+            start_element(name)
+            write_attributes(attributes)
+            write(item)
+            end_element
+          end
+        else
+          fail ArgumentError, "The writer cannot serialize objects of type: #{value.class}"
+        end
+      end
+
+      # Starts an element.
+      #
+      # @param [String] name
+      # @return [Boolean]
+      def start_element(name)
+        if name[0] == '{'
+          (namespace, local_name) = Service.parse_clark_notation(name)
+
+          if @namespace_map.key? namespace
+            result = start_element_ns(@namespace_map[namespace], local_name, nil)
+          else
+            # An empty namespace means it's the global namespace. This is
+            # allowed, but it mustn't get a prefix.
+            if namespace == ''
+              result = start_element(local_name)
+              write_attribute('xmlns', '')
+            else
+              unless @adhoc_namespaces.key? namespace
+                @adhoc_namespaces[namespace] = 'x' + (@adhoc_namespaces.size + 1).to_s
+              end
+              result = start_element_ns(@adhoc_namespaces[namespace], local_name, namespace)
+            end
+          end
+        else
+          result = @writer.start_element(name)
+        end
+
+        unless @namespaces_written
+          @namespace_map.each do |ns, prefix|
+            write_attribute((prefix ? 'xmlns:' + prefix : 'xmlns'), ns)
+          end
+          @namespaces_written = true
+        end
+
+        result
+      end
+
+      # Write a full element tag.
+      #
+      # This method automatically closes the element as well.
+      #
+      # @param [String] name
+      # @param [String] content
+      # @return [Boolean]
+      def write_element(name, content = nil)
+        start_element(name)
+        write(content) unless content.nil?
+        end_element
+      end
+
+      # Writes a list of attributes.
+      #
+      # Attributes are specified as a key->value array.
+      #
+      # The key is an attribute name. If the key is a 'localName', the current
+      # xml namespace is assumed. If it's a 'clark notation key', this namespace
+      # will be used instead.
+      #
+      # @param [Hash] attributes
+      # @return [void]
+      def write_attributes(attributes)
+        attributes.each do |name, value|
+          write_attribute(name, value)
+        end
+      end
+
+      # Writes a new attribute.
+      #
+      # The name may be specified in clark-notation.
+      #
+      # Returns true when successful.
+      #
+      # @param [String] name
+      # @param [String] value
+      # @return [Boolean]
+      def write_attribute(name, value)
+        if name[0] == '{'
+          (namespace, local_name) = Service.parse_clark_notation(name)
+          if @namespace_map.key? namespace
+            # It's an attribute with a namespace we know
+            write_attribute(
+              @namespace_map[namespace] + ':' + local_name,
+              value
+            )
+          else
+            # We don't know the namespace, we must add it in-line
+            @adhoc_namespaces[namespace] = 'x' + (@adhoc_namespaces.size + 1).to_s unless @adhoc_namespaces.key?(namespace)
+
+            write_attribute_ns(
+              @adhoc_namespaces[namespace],
+              local_name,
+              namespace,
+              value
+            )
+          end
+        else
+          @writer.write_attribute(name, value)
+        end
+      end
+
+      # TODO: document this
+      def initialize
+        @adhoc_namespaces = {}
+        @namespaces_written = false
+        initialize_context_stack_attributes
+      end
+
+      # TODO: documentation
+      def open_memory
+        fail 'XML document already created' if @writer
+
+        @writer = ::LibXML::XML::Writer.string
+      end
+
+      # TODO: documentation
+      def output_memory
+        @writer.result
+      end
+
+      # TODO: documentation
+      def method_missing(name, *args)
+        @writer.send(name, *args)
+      end
+    end
+  end
+end

data/lib/tilia/xml/xml_deserializable.rb

@@ -0,0 +1,29 @@
+module Tilia
+  module Xml
+    # Implementing the XmlDeserializable interface allows you to use a class as a
+    # deserializer for a specific element.
+    module XmlDeserializable
+      # 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 xml_deserialize(_reader)
+      end
+    end
+  end
+end