representable 0.0.1.alpha1

data/lib/representable.rb

@@ -0,0 +1,257 @@
+require 'active_support'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/array/extract_options'
+require 'active_support/core_ext/string/starts_ends_with'
+require 'active_support/core_ext/string/inflections.rb'
+require 'active_support/core_ext/hash/reverse_merge.rb'
+
+require 'hooks/inheritable_attribute'
+
+
+require 'representable/definition'
+require 'representable/nokogiri_extensions'
+require 'representable/references'
+
+require 'representable/xml' # TODO: do that dynamically.
+
+module Representable
+  VERSION = '3.1.5'
+  
+  
+  def self.included(base)
+    base.class_eval do
+      extend  ClassMethods::Accessors, ClassMethods::Declarations
+              
+      
+
+      attr_accessor :roxml_references
+      
+      extend Hooks::InheritableAttribute
+      inheritable_attr :representable_attrs
+      self.representable_attrs = []
+      
+      inheritable_attr :explicit_representation_name  # FIXME: move to Accessors.
+      
+      
+      extend Xml::Declarations  # DISCUSS: do that dynamically?
+      extend Xml::ClassMethods  # DISCUSS: do that dynamically?
+      include Xml::InstanceMethods  # DISCUSS: do that dynamically?
+    end
+  end
+  
+  module ClassMethods # :nodoc:
+    module Declarations
+      def definition_class
+        Definition
+      end
+      
+
+      # Declares a reference to a certain xml element, whether an attribute, a node,
+      # or a typed collection of nodes.  This method does not add a corresponding accessor
+      # to the object.  For that behavior see the similar methods: .xml_reader and .xml_accessor.
+      #
+      # == Sym Option
+      # [sym]   Symbol representing the name of the accessor.
+      #
+      # === Default naming
+      # This name will be the default node or attribute name searched for,
+      # if no other is declared.  For example,
+      #
+      #  xml_reader   :bob
+      #  xml_accessor :pony, :from => :attr
+      #
+      # are equivalent to:
+      #
+      #  xml_reader   :bob, :from => 'bob'
+      #  xml_accessor :pony, :from => '@pony'
+      #
+      # == Options
+      # === :as
+      # ==== Basic Types
+      # Allows you to specify one of several basic types to return the value as.  For example
+      #
+      #  xml_reader :count, :as => Integer
+      #
+      # is equivalent to:
+      #
+      #  xml_reader(:count) {|val| Integer(val) unless val.empty? }
+      #
+      # Such block shorthands for Integer, Float, Fixnum, BigDecimal, Date, Time, and DateTime
+      # are currently available, but only for non-Hash declarations.
+      #
+      # To reference many elements, put the desired type in a literal array. e.g.:
+      #
+      #   xml_reader :counts, :as => [Integer]
+      #
+      # Even an array of text nodes can be specified with :as => []
+      #
+      #   xml_reader :quotes, :as => []
+      #
+      # === Other ROXML Class
+      # Declares an accessor that represents another ROXML class as child XML element
+      # (one-to-one or composition) or array of child elements (one-to-many or
+      # aggregation) of this type. Default is one-to-one. For one-to-many, simply pass the class
+      # as the only element in an array.
+      #
+      # Composition example:
+      #  <book>
+      #   <publisher>
+      #     <name>Pragmatic Bookshelf</name>
+      #   </publisher>
+      #  </book>
+      #
+      # Can be mapped using the following code:
+      #   class Book
+      #     xml_reader :publisher, :as => Publisher
+      #   end
+      #
+      # Aggregation example:
+      #  <library>
+      #   <books>
+      #    <book/>
+      #    <book/>
+      #   </books>
+      #  </library>
+      #
+      # Can be mapped using the following code:
+      #  class Library
+      #    xml_reader :books, :as => [Book], :in => "books"
+      #  end
+      #
+      # If you don't have the <books> tag to wrap around the list of <book> tags:
+      #  <library>
+      #   <name>Ruby books</name>
+      #   <book/>
+      #   <book/>
+      #  </library>
+      #
+      # You can skip the wrapper argument:
+      #    xml_reader :books, :as => [Book]
+      #
+      # === :from
+      # The name by which the xml value will be found, either an attribute or tag name in XML.
+      # Default is sym, or the singular form of sym, in the case of arrays and hashes.
+      #
+      # This value may also include XPath notation.
+      #
+      # ==== :from => :content
+      # When :from is set to :content, this refers to the content of the current node,
+      # rather than a sub-node. It is equivalent to :from => '.'
+      #
+      # Example:
+      #  class Contributor
+      #    xml_reader :name, :from => :content
+      #    xml_reader :role, :from => :attr
+      #  end
+      #
+      # To map:
+      #  <contributor role="editor">James Wick</contributor>
+      #
+      # ==== :from => :attr
+      # When :from is set to :attr, this refers to the content of an attribute,
+      # rather than a sub-node. It is equivalent to :from => '@attribute_name'
+      #
+      # Example:
+      #  class Book
+      #    xml_reader :isbn, :from => "@ISBN"
+      #    xml_accessor :title, :from => :attr # :from defaults to '@title'
+      #  end
+      #
+      # To map:
+      #  <book ISBN="0974514055" title="Programming Ruby: the pragmatic programmers' guide" />
+      #
+      # ==== :from => :text
+      # The default source, if none is specified, this means the accessor
+      # represents a text node from XML.  This is documented for completeness
+      # only.  You should just leave this option off when you want the default behavior,
+      # as in the examples below.
+      #
+      # :text is equivalent to :from => accessor_name, and you should specify the
+      # actual node name (and, optionally, a namespace) if it differs, as in the case of :author below.
+      #
+      # Example:
+      #  class Book
+      #    xml_reader :author, :from => 'Author'
+      #    xml_accessor :description, :cdata => true
+      #    xml_reader :title
+      #  end
+      #
+      # To map:
+      #  <book>
+      #   <title>Programming Ruby: the pragmatic programmers' guide</title>
+      #   <description><![CDATA[Probably the best Ruby book out there]]></description>
+      #   <Author>David Thomas</Author>
+      #  </book>
+      #
+      # Likewise, a number of :text node values can be collected in an array like so:
+      #
+      # Example:
+      #  class Library
+      #    xml_reader :books, :as => []
+      #  end
+      #
+      # To map:
+      #  <library>
+      #      <book>To kill a mockingbird</book>
+      #      <book>House of Leaves</book>
+      #    <book>Gödel, Escher, Bach</book>
+      #  </library>
+      #
+      # === Other Options
+      # [:in] An optional name of a wrapping tag for this XML accessor.
+      #       This can include other xpath values, which will be joined with :from with a '/'
+      # [:required] If true, throws RequiredElementMissing when the element isn't present
+      # [:cdata] true for values which should be input from or output as cdata elements
+      # [:to_xml] this proc is applied to the attributes value outputting the instance via #to_xml
+      #
+      def representable_attr(*syms, &block)
+        opts = syms.extract_options!
+        syms.map do |sym|
+          definition_class.new(sym, opts, &block).tap do |attr|
+            representable_attrs << attr
+          end
+        end
+      end
+
+      # Declares a read-only xml reference. See xml_attr for details.
+      #
+      # Note that while xml_reader does not create a setter for this attribute,
+      # its value can be modified indirectly via methods.  For more complete
+      # protection, consider the :frozen option.
+      def representable_reader(*syms, &block)
+        representable_attr(*syms, &block).each do |attr|
+          add_reader(attr)
+        end
+      end
+
+      # Declares a writable xml reference. See xml_attr for details.
+      #
+      # Note that while xml_accessor does create a setter for this attribute,
+      # you can use the :frozen option to prevent its value from being
+      # modified indirectly via methods.
+      def representable_accessor(*syms, &block)
+        representable_attr(*syms, &block).each do |attr|
+          add_reader(attr)
+          attr_writer(attr.accessor)
+        end
+      end
+
+    private
+      def add_reader(attr)
+        define_method(attr.accessor) do
+          instance_variable_get(attr.instance_variable_name)
+        end
+      end
+    end
+
+    module Accessors
+      def representation_name=(name)
+        self.explicit_representation_name = name
+      end
+      
+      def representation_name
+        explicit_representation_name or name.split('::').last.underscore
+      end
+    end
+  end
+end

data/lib/representable/definition.rb

@@ -0,0 +1,109 @@
+class Module
+  def bool_attr_reader(*attrs)
+    attrs.each do |attr|
+      define_method :"#{attr}?" do
+        instance_variable_get(:"@#{attr}") || false
+      end
+    end
+  end
+end
+
+module Representable
+  class ContradictoryNamespaces < StandardError
+  end
+  class Definition # :nodoc:
+    attr_reader :name, :sought_type, :wrapper, :accessor, :namespace
+    bool_attr_reader :name_explicit, :array, :cdata
+    
+    def initialize(sym, opts={})
+      @accessor   = sym.to_s
+      @namespace  = opts.delete(:namespace)
+      
+      
+      if opts[:as].is_a?(Array) # DISCUSS: move to ArrayDefinition.
+        @array      = true
+        @name       = (opts[:tag] || @accessor).to_s
+      else
+        @name = accessor
+        @name = (opts[:from] || @name).to_s
+      end
+
+      @sought_type = extract_type(opts[:as])
+      if @sought_type.respond_to?(:roxml_tag_name)
+        opts[:from] ||= @sought_type.roxml_tag_name
+      end
+
+      if opts[:from] == :content
+        opts[:from] = '.'
+      elsif opts[:from] == :name
+        opts[:from] = '*'
+      elsif opts[:from] == :attr
+        @sought_type = :attr
+        opts[:from] = nil
+      elsif opts[:from] == :namespace
+        opts[:from] = '*'
+        @sought_type = :namespace
+      elsif opts[:from].to_s.starts_with?('@')
+        @sought_type = :attr
+        opts[:from].sub!('@', '')
+      end
+
+      
+      #raise ContradictoryNamespaces if @name.include?(':') && (@namespace.present? || @namespace == false)
+
+    end
+
+    def instance_variable_name
+      :"@#{accessor}"
+    end
+
+    def setter
+      :"#{accessor}="
+    end
+    
+    def typed?
+      sought_type.is_a?(Class)
+    end
+    
+    
+    def name?
+      @name == '*'
+    end
+
+    def content?
+      @name == '.'
+    end
+    
+    # Applies the block to +value+ which might also be a collection.
+    def apply(value)
+      return value unless value # DISCUSS: is that ok here?
+      
+      if array?
+        value = value.collect do |item|
+          yield item
+        end
+      else
+        value = yield value
+      end
+      
+      value
+    end
+    
+    def to_ref
+      case sought_type
+      when :attr          then XMLAttributeRef
+      when :text          then XMLTextRef
+      when :namespace     then XMLNameSpaceRef
+      when Symbol         then raise ArgumentError, "Invalid type argument #{sought_type}"
+      else                     XMLObjectRef
+      end.new(self)
+    end
+
+  private
+    def extract_type(as)
+      as = as.first if as.is_a?(Array)  # TODO: move to ArrayDefinition.
+      
+      as || :text
+    end
+  end
+end

data/lib/representable/nokogiri_extensions.rb

@@ -0,0 +1,19 @@
+require 'nokogiri'
+
+Nokogiri::XML::Node.class_eval do
+  def add_node(name)
+    add_child Nokogiri::XML::Node.new(name, document)
+  end
+  
+  # FIXME: remove switch. where is #from used with nodes?
+  def self.from(data)
+    case data
+    when Nokogiri::XML::Node
+      data
+    when Nokogiri::XML::Document
+      data.root
+    else
+      Nokogiri::XML(data).root
+    end
+  end
+end

data/lib/representable/references.rb

@@ -0,0 +1,153 @@
+module Representable
+  class RequiredElementMissing < Exception # :nodoc:
+  end
+
+  # Internal base class that represents an XML - Class binding.
+  class XMLRef
+    attr_reader :definition
+    delegate :required?, :array?, :accessor, :wrapper, :name, :to => :definition
+
+    def initialize(definition)
+      @definition = definition
+    end
+    
+    def value_in(xml)
+      xml = Nokogiri::XML::Node.from(xml) or return default
+      
+      value_from_node(xml) or default
+    end
+    
+  private
+    def default
+      ""
+    end
+    
+    def xpath
+      name
+    end
+
+    def wrap(xml, opts = {:always_create => false})
+      wrap_with = @auto_vals ? auto_wrapper : wrapper
+
+      return xml if !wrap_with || xml.name == wrap_with
+      if !opts[:always_create] && (child = xml.children.find {|c| c.name == wrap_with })
+       return child
+      end
+      xml.add_node(wrap_with.to_s)
+    end
+
+    def collect_for(xml)
+      nodes = xml.search("./#{xpath}")
+      vals  = nodes.collect { |node| yield node }
+      
+      array? ? vals : vals.first
+    end
+  end
+  
+  # Represents a tag attribute.
+  class XMLAttributeRef < XMLRef
+    # Updates the attribute in the given XML block to
+    # the value provided.
+    def update_xml(xml, values)
+      wrap(xml).tap do |xml|
+        xml[name] = values.to_s
+      end
+    end
+
+  private
+    def value_from_node(xml)
+      xml[name]
+    end
+  end
+  
+  # Represents text content in a tag.
+  class XMLTextRef < XMLRef
+    delegate :cdata?, :content?, :name?, :to => :definition
+
+    # Updates the text in the given _xml_ block to
+    # the _value_ provided.
+    def update_xml(xml, value)
+      wrap(xml).tap do |xml|
+        if content?
+          add(xml, value)
+        elsif name?
+          xml.name = value
+        elsif array?
+          value.each do |v|
+            add(xml.add_node(name), v)
+          end
+        else
+          add(xml.add_node(name), value)
+        end
+      end
+    end
+
+  private
+    def value_from_node(xml)
+      collect_for(xml) do |node| 
+        node.content
+      end
+    end
+
+    def add(dest, value)
+      if cdata?
+        dest.add_child(Nokogiri::XML::CDATA.new(dest.document, content))
+      else
+        dest.content = value.to_s
+      end
+    end
+  end
+
+  class XMLNameSpaceRef < XMLRef
+    private
+      def value_from_node(xml)
+        xml.namespace.prefix
+      end
+  end
+
+  # Represents a tag with object binding.
+  class XMLObjectRef < XMLTextRef
+    delegate :sought_type, :to => :definition
+
+    # Adds the ref's markup to +xml+. 
+    def update_xml(xml, value)
+      wrap(xml).tap do |xml|
+        if array?
+          update_xml_for_collection(xml, value)
+        else
+          update_xml_for_entity(xml, value)
+        end
+      end
+    end
+
+  private
+    def default
+      []
+    end
+    
+    def serialize(object)
+      object.to_xml
+    end
+    
+    def deserialize(node_class, xml)
+      node_class.from_xml(xml)
+    end
+    
+    # Deserializes the ref's element from +xml+.
+    def value_from_node(xml)
+      collect_for(xml) do |node|
+        deserialize(sought_type, node)
+      end
+    end
+    
+    def update_xml_for_collection(xml, collection)
+      collection.each do |item|
+        update_xml_for_entity(xml, item)
+      end
+    end
+    
+    def update_xml_for_entity(xml, entity)
+      xml.add_child(serialize(entity))
+    end
+  end
+end