tilia-xml 1.2.0.2 → 1.3.0

data/lib/tilia/xml/serializer.rb

@@ -0,0 +1,194 @@
+module Tilia
+  module Xml
+    # This file provides a number of 'serializer' helper functions.
+    #
+    # These helper functions can be used to easily xml-encode common PHP
+    # data structures, or can be placed in the class_map.
+    module Serializer
+      # The 'enum' serializer writes simple list of elements.
+      #
+      # For example, calling:
+      #
+      # enum(writer, [
+      #   "{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",
+      # ])
+      #
+      # Will generate something like this (if the correct namespace is declared):
+      #
+      # <s:elem1 />
+      # <s:elem2 />
+      # <s:elem3 />
+      # <s:elem4>content</s:elem4>
+      # <s:elem5 attr="val" />
+      #
+      # @param [Writer] writer
+      # @param [Array<String>] values
+      # @return [void]
+      def self.enum(writer, values)
+        values.each do |value|
+          writer.write_element(value)
+        end
+      end
+
+      # The valueObject serializer turns a simple PHP object into a classname.
+      #
+      # Every public property will be encoded as an xml element with the same
+      # name, in the XML namespace as specified.
+      #
+      # @param [Writer] writer
+      # @param [Object] value_object
+      # @param [String] namespace
+      def self.value_object(writer, value_object, namespace)
+        value_object.instance_variables.each do |key|
+          value = value_object.instance_variable_get(key)
+
+          # key is a symbol and starts with @
+          key = key.to_s[1..-1]
+
+          writer.write_element("{#{namespace}}#{key}", value)
+        end
+      end
+
+      # This serializer helps you serialize xml structures that look like
+      # this:
+      #
+      # <collection>
+      #    <item>...</item>
+      #    <item>...</item>
+      #    <item>...</item>
+      # </collection>
+      #
+      # In that previous example, this serializer just serializes the item element,
+      # and this could be called like this:
+      #
+      # repeating_elements(writer, items, '{}item')
+      #
+      # @param [Writer] writer
+      # @param [Array] items A list of items sabre/xml can serialize.
+      # @param [String] child_element_name Element name in clark-notation
+      # @return [void]
+      def self.repeating_elements(writer, items, child_element_name)
+        items.each do |item|
+          writer.write_element(child_element_name, item)
+        end
+      end
+
+      # This function is the 'default' serializer that is able to serialize most
+      # things, and delegates to other serializers if needed.
+      #
+      # The standardSerializer supports a wide-array of values.
+      #
+      # value may be a string or integer, it will just write out the string as text.
+      # value may be an instance of XmlSerializable or Element, in which case it
+      #    calls it's xml_serialize method.
+      # value may be a PHP callback/function/closure, in case we call the callback
+      #    and give it the Writer as an argument.
+      # value may be a an object, and if it's in the classMap we automatically call
+      #    the correct serializer for it.
+      # value may be null, in which case we do nothing.
+      #
+      # If value is an array, the array must look like this:
+      #
+      # [
+      #    [
+      #       'name' => '{namespaceUri}element-name',
+      #       'value' => '...',
+      #       'attributes' => [ 'attName' => 'attValue' ]
+      #    ]
+      #    [,
+      #       'name' => '{namespaceUri}element-name2',
+      #       'value' => '...',
+      #    ]
+      # ]
+      #
+      # This would result in xml like:
+      #
+      # <element-name xmlns="namespaceUri" attName="attValue">
+      #   ...
+      # </element-name>
+      # <element-name2>
+      #   ...
+      # </element-name2>
+      #
+      # The value property may be any value standardSerializer supports, so you can
+      # nest data-structures this way. Both value and attributes are optional.
+      #
+      # Alternatively, you can also specify the array using this syntax:
+      #
+      # [
+      #    [
+      #       '{namespaceUri}element-name' => '...',
+      #       '{namespaceUri}element-name2' => '...',
+      #    ]
+      # ]
+      #
+      # This is excellent for simple key.value structures, and here you can also
+      # specify anything for the value.
+      #
+      # You can even mix the two array syntaxes.
+      #
+      # @param [Writer] writer
+      # @param value
+      # @return [void]
+      def self.standard_serializer(writer, value)
+        if value.is_a?(Numeric) || value.is_a?(String)
+          writer.write_string(value.to_s)
+        elsif value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          writer.write_string(value.to_s)
+        elsif value.is_a?(XmlSerializable)
+          value.xml_serialize(writer)
+        elsif writer.class_map.key?(value.class)
+          # It's an object which class appears in the classmap.
+          writer.class_map[value.class].call(writer, value)
+        elsif value.respond_to?(:call)
+          # A callback
+          value.call(writer)
+        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')
+                raise ArgumentError, 'When passing an array to ->write with numeric indices, every item must be an array containing at least the "name" 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
+
+            writer.start_element(name)
+            writer.write_attributes(attributes)
+            writer.write(item)
+            writer.end_element
+          end
+        else
+          raise ArgumentError, "The writer cannot serialize objects of type: #{value.class}"
+        end
+      end
+    end
+  end
+end

data/lib/tilia/xml/service.rb

@@ -25,6 +25,32 @@ module Tilia
       # @return [Hash]
       attr_accessor :namespace_map
 
+      # This is a list of custom serializers for specific classes.
+      #
+      # The writer may use this if you attempt to serialize an object with a
+      # class that does not implement XmlSerializable.
+      #
+      # Instead it will look at this classmap to see if there is a custom
+      # serializer here. This is useful if you don't want your value objects
+      # to be responsible for serializing themselves.
+      #
+      # The keys in this classmap need to be fully qualified PHP class names,
+      # the values must be callbacks. The callbacks take two arguments. The
+      # writer class, and the value that must be written.
+      #
+      # function (Writer writer, object value)
+      #
+      # @return [Hash]
+      attr_accessor :class_map
+
+      # Initializes the xml service
+      def initialize
+        @element_map = {}
+        @namespace_map = {}
+        @class_map = {}
+        @value_object_map = {}
+      end
+
       # Returns a fresh XML Reader
       #
       # @return [Reader]
@@ -40,6 +66,7 @@ module Tilia
       def writer
         writer = Writer.new
         writer.namespace_map = @namespace_map
+        writer.class_map = @class_map
         writer
       end
 
@@ -57,7 +84,7 @@ module Tilia
       #
       # @param [String, File, StringIO] input
       # @param [String, nil] context_uri
-      # @param [String, nil] root_element_name
+      # @param [Tilia::Box, nil] root_element_name
       # @raise [ParseException]
       # @return [Array, Object, String]
       def parse(input, context_uri = nil, root_element_name = Box.new)
@@ -81,19 +108,20 @@ module Tilia
       # 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, Array<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
+        root_element_name = [root_element_name] unless root_element_name.is_a?(Array)
+
         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"
+        unless root_element_name.include?(result['name'])
+          raise Tilia::Xml::ParseException, "Expected #{root_element_name.join(' or ')} but received #{result['name']} as the root element"
         end
         result['value']
       end
@@ -125,6 +153,68 @@ module Tilia
         writer.output_memory
       end
 
+      # Map an xml element to a PHP class.
+      #
+      # Calling this function will automatically setup the Reader and Writer
+      # classes to turn a specific XML element to a PHP class.
+      #
+      # For example, given a class such as :
+      #
+      # class Author {
+      #   public first_name
+      #   public last_name
+      # }
+      #
+      # and an XML element such as:
+      #
+      # <author xmlns="http://example.org/ns">
+      #   <firstName>...</firstName>
+      #   <lastName>...</lastName>
+      # </author>
+      #
+      # These can easily be mapped by calling:
+      #
+      # service.map_value_object('{http://example.org}author', 'Author')
+      #
+      # @param [String] element_name
+      # @param [Class] klass
+      # @return [void]
+      def map_value_object(element_name, klass)
+        namespace = Service.parse_clark_notation(element_name).first
+
+        @element_map[element_name] = lambda do |reader|
+          return Deserializer.value_object(reader, klass, namespace)
+        end
+        @class_map[klass] = lambda do |writer, value_object|
+          return Serializer.value_object(writer, value_object, namespace)
+        end
+        @value_object_map[klass] = element_name
+      end
+
+      # Writes a value object.
+      #
+      # This function largely behaves similar to write, except that it's
+      # intended specifically to serialize a Value Object into an XML document.
+      #
+      # The ValueObject must have been previously registered using
+      # map_value_object.
+      #
+      # @param object
+      # @param [String] context_uri
+      # @return [void]
+      def write_value_object(object, context_uri = nil)
+        unless @value_object_map.key?(object.class)
+          raise ArgumentError,
+                "'#{object.class}' is not a registered value object class. Register your class with mapValueObject"
+        end
+
+        write(
+          @value_object_map[object.class],
+          object,
+          context_uri
+        )
+      end
+
       # Parses a clark-notation string, and returns the namespace and element
       # name components.
       #
@@ -132,20 +222,14 @@ module Tilia
       #
       # @param [String] str
       # @raise [InvalidArgumentException]
-      # @return [Array]
+      # @return [Array(String, String)]
       def self.parse_clark_notation(str)
         if str =~ /^{([^}]*)}(.*)/
-          [Regexp.last_match[1], Regexp.last_match[2]]
+          [Regexp.last_match[1] || '', Regexp.last_match[2]]
         else
-          fail ArgumentError, "'#{str}' is not a valid clark-notation formatted string"
+          raise 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

@@ -3,7 +3,7 @@ module Tilia
     # This class contains the version number for this package.
     class Version
       # Full version number
-      VERSION = '1.2.0.2'
+      VERSION = '1.3.0'.freeze
     end
   end
 end

data/lib/tilia/xml/writer.rb

@@ -22,27 +22,6 @@ module Tilia
     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:
@@ -84,53 +63,7 @@ module Tilia
       # @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
+        Serializer.standard_serializer(self, value)
       end
 
       # Starts an element.
@@ -141,20 +74,20 @@ module Tilia
         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
+          if @namespace_map.key?(namespace)
+            tmp_ns = @namespace_map[namespace]
+            tmp_ns = nil if tmp_ns.blank?
+            result = start_element_ns(tmp_ns, local_name, nil)
+          elsif namespace.blank?
             # 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)
+            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
         else
           result = @writer.start_element(name)
@@ -162,7 +95,7 @@ module Tilia
 
         unless @namespaces_written
           @namespace_map.each do |ns, prefix|
-            write_attribute((prefix ? 'xmlns:' + prefix : 'xmlns'), ns)
+            write_attribute((prefix.present? ? 'xmlns:' + prefix : 'xmlns'), ns)
           end
           @namespaces_written = true
         end
@@ -170,10 +103,24 @@ module Tilia
         result
       end
 
-      # Write a full element tag.
+      # Write a full element tag and it's contents.
       #
       # This method automatically closes the element as well.
       #
+      # The element name may be specified in clark-notation.
+      #
+      # Examples:
+      #
+      #    writer.write_element('{http://www.w3.org/2005/Atom}author',null)
+      #    becomes:
+      #    <author xmlns="http://www.w3.org/2005" />
+      #
+      #    writer.write_element('{http://www.w3.org/2005/Atom}author', [
+      #       '{http://www.w3.org/2005/Atom}name' => 'Evert Pot',
+      #    ])
+      #    becomes:
+      #    <author xmlns="http://www.w3.org/2005" /><name>Evert Pot</name></author>
+      #
       # @param [String] name
       # @param [String] content
       # @return [Boolean]
@@ -211,7 +158,7 @@ module Tilia
       def write_attribute(name, value)
         if name[0] == '{'
           (namespace, local_name) = Service.parse_clark_notation(name)
-          if @namespace_map.key? namespace
+          if @namespace_map.key?(namespace)
             # It's an attribute with a namespace we know
             write_attribute(
               @namespace_map[namespace] + ':' + local_name,
@@ -233,26 +180,33 @@ module Tilia
         end
       end
 
-      # TODO: document this
+      # Initializes the instance variables
       def initialize
         @adhoc_namespaces = {}
         @namespaces_written = false
-        initialize_context_stack_attributes
+
+        super
       end
 
-      # TODO: documentation
+      # Fakes the php function open_memory
+      #
+      # Initilizes the LibXML Writer
+      #
+      # @return [void]
       def open_memory
-        fail 'XML document already created' if @writer
+        raise 'XML document already created' if @writer
 
         @writer = ::LibXML::XML::Writer.string
       end
 
-      # TODO: documentation
+      # Fakes the php function output_memory
+      #
+      # @return [String]
       def output_memory
         @writer.result
       end
 
-      # TODO: documentation
+      # Delegates missing methods to XML::Writer instance
       def method_missing(name, *args)
         @writer.send(name, *args)
       end