tilia-xml 1.2.0.2 → 1.3.0

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

@@ -9,13 +9,6 @@ module Tilia
       class Base
         include Element
 
-        protected
-
-        # PHP value to serialize.
-        attr_accessor :value
-
-        public
-
         # Constructor
         #
         # @param value
@@ -23,46 +16,12 @@ module Tilia
           @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 XmlSerializable 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]
+        # (see XmlSerializable#xml_serialize)
         def xml_serialize(writer)
           writer.write(@value)
         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->parseInnerTree() will parse the entire sub-tree, and advance to
-        # the next element.
-        #
-        # @param [Reader] reader
-        # @return mixed
+        # (see XmlDeserializable#xml_deserialize)
         def self.xml_deserialize(reader)
           sub_tree = reader.parse_inner_tree
           sub_tree

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

@@ -11,15 +11,6 @@ module Tilia
       class Cdata
         include XmlSerializable
 
-        protected
-
-        # CDATA element value.
-        #
-        # @return [String]
-        attr_accessor :value
-
-        public
-
         # Constructor
         #
         # @param [String] value
@@ -27,23 +18,7 @@ module Tilia
           @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]
+        # (see XmlSerializable#xml_serialize)
         def xml_serialize(writer)
           writer.write_cdata(@value)
         end

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

@@ -25,15 +25,6 @@ module Tilia
       class Elements
         include Element
 
-        protected
-
-        # Value to serialize
-        #
-        # @return [Array]
-        attr_accessor :value
-
-        public
-
         # Constructor
         #
         # @param [Array] value
@@ -41,67 +32,14 @@ module Tilia
           @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]
+        # (see XmlSerializable#xml_serialize)
         def xml_serialize(writer)
-          @value.each do |val|
-            writer.write_element(val)
-          end
+          Serializer.enum(writer, @value)
         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
+        # (see XmlDeserializable#xml_deserialize)
         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
+          Deserializer.enum(reader)
         end
       end
     end

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

@@ -26,15 +26,6 @@ module Tilia
       class KeyValue
         include Element
 
-        protected
-
-        # Value to serialize
-        #
-        # @return [Array]
-        attr_accessor :value
-
-        public
-
         # Constructor
         #
         # @param [Array] value
@@ -42,67 +33,14 @@ module Tilia
           @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]
+        # (see XmlSerializable#xml_serialize)
         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
+        # (see XmlDeserializable#xml_deserialize)
         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
+          Deserializer.key_value(reader)
         end
       end
     end

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

@@ -14,15 +14,6 @@ module Tilia
       class Uri
         include Element
 
-        protected
-
-        # Uri element value.
-        #
-        # @return [String]
-        attr_accessor :value
-
-        public
-
         # Constructor
         #
         # @param [String] value
@@ -30,23 +21,7 @@ module Tilia
           @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]
+        # (see XmlSerializable#xml_serialize)
         def xml_serialize(writer)
           writer.write_string(
             ::Tilia::Uri.resolve(
@@ -56,25 +31,7 @@ module Tilia
           )
         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
+        # (see XmlDeserializable#xml_deserialize)
         def self.xml_deserialize(reader)
           new(
             ::Tilia::Uri.resolve(

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

@@ -16,35 +16,13 @@ module Tilia
       class XmlFragment
         include Element
 
-        protected
-
-        attr_writer :xml
-
-        public
-
         def initialize(xml)
           @xml = xml
         end
 
         attr_reader :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]
+        # (see XmlSerializable#xml_serialize)
         def xml_serialize(writer)
           reader = Reader.new
 
@@ -89,25 +67,7 @@ XML
           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
+        # (see XmlDeserializable#xml_deserialize)
         def self.xml_deserialize(reader)
           result = new(reader.read_inner_xml)
           reader.next

data/lib/tilia/xml/reader.rb

@@ -88,7 +88,7 @@ module Tilia
         text = nil
         elements = []
 
-        if node_type == ::LibXML::XML::Reader::TYPE_ELEMENT && self.empty_element?
+        if node_type == ::LibXML::XML::Reader::TYPE_ELEMENT && empty_element?
           # Easy!
           self.next
           return nil
@@ -117,7 +117,7 @@ module Tilia
             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.'
+            raise 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
@@ -160,22 +160,10 @@ module Tilia
 
         attributes = {}
 
-        attributes = parse_attributes if self.has_attributes?
+        attributes = parse_attributes if has_attributes?
 
-        if @element_map.key? name
-          deserializer = @element_map[name]
+        value = deserializer_for_element_name(name).call(self)
 
-          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,
@@ -211,27 +199,44 @@ module Tilia
         attributes
       end
 
-      # TODO: document this
-      def initialize
-        initialize_context_stack_attributes
-      end
-
-      # TODO: documentation
+      # Fakes PHP method xml
+      #
+      # Creates a new XML::Reader instance
+      #
+      # @return [XML::Reader]
       def xml(input)
-        fail 'XML document already loaded' if @reader
+        raise 'XML document already loaded' if @reader
 
-        if input.is_a? String
+        if input.is_a?(String)
           @reader = ::LibXML::XML::Reader.string(input)
-        elsif input.is_a? File
+        elsif input.is_a?(File)
           @reader = ::LibXML::XML::Reader.file(input)
-        elsif input.is_a? StringIO
+        elsif input.is_a?(StringIO)
           @reader = ::LibXML::XML::Reader.io(input)
         else
-          fail 'Unable to load XML document'
+          raise 'Unable to load XML document'
         end
       end
 
-      # TODO: documentation
+      # Returns the function that should be used to parse the element identified
+      # by it's clark-notation name.
+      #
+      # @param [String] name
+      # @return [#call]
+      def deserializer_for_element_name(name)
+        return Element::Base.method(:xml_deserialize) unless @element_map.key?(name)
+
+        deserializer = @element_map[name]
+        return deserializer if deserializer.respond_to?(:call)
+
+        return deserializer.method(:xml_deserialize) if deserializer.include?(XmlDeserializable)
+
+        raise "Could not use this type as a deserializer: #{deserializer.inspect} for element: #{name}"
+      end
+
+      # Delegates missing methods to XML::Reader instance
+      #
+      # @return [void]
       def method_missing(name, *args)
         @reader.send(name, *args)
       end