representable 0.0.1.alpha1 → 0.0.1

data/README.rdoc

@@ -1,186 +1,91 @@
-ROXML Ruby Object to XML mapping library.
+= Representable
 
-For more information visit:
+<em>Maps representation documents from and to Ruby objects.</em>
 
-    http://rdoc.info/projects/Empact/roxml
-    http://empact.github.com/roxml/
-    http://rubyforge.org/projects/roxml/
 
-Please submit bugs here:
+== Introduction
 
-    http://github.com/Empact/roxml/issues
+_Representable_ maps fragments in documents to attributes in Ruby objects and back. It allows parsing representations and gives an object-oriented interface to the document. But that's only half of it! Representable can also render documents from an object instance. 
 
-=Quick Start Guide
+This is especially helpful when implementing REST services and clients and keeps your representation knowledge in one place.
 
-This is a short usage example. See ROXML::ClassMethods::Declarations and packaged test cases for more information.
+== Example
 
-==Basic Mapping
+When writing a REST service you'd have to parse and extract data from an incoming representation document manually. Given the following XML document which represents an order.
 
-Consider an XML document representing a Library containing a number of Books. You
-can map this structure to Ruby classes that provide addition useful behavior. With
-ROXML, you can annotate the Ruby classes as follows:
+  <order>
+    <id>1</id>
+    <item>
+      <name>Chocolate Cookie</name>
+    </item>
+    <item>
+      <name>Vanilla Muffin</name>
+    </item>
+  </order>  
 
-  class Book
-    include ROXML
+Now, parsing manually starts simple but gets complex soon. In the end, you have a nested hash data structure. Try this with Representable.
 
-    xml_accessor :isbn, :from => "@ISBN" # attribute with name 'ISBN'
-    xml_accessor :title
-    xml_accessor :description, :cdata => true  # text node with cdata protection
-    xml_accessor :author
+  class Order
+    include Representable::XML
+    
+    representable_property :id
+    representable_collection :items, :tag => :item, :as => Item
   end
-
-  class Library
-    include ROXML
-
-    xml_accessor :name, :from => "NAME", :cdata => true
-    xml_accessor :books, :as => [Book] # by default roxml searches for books for in <book> child nodes, then, if none are present, in ./books/book children
-  end
-
-To create a library and put a number of books in it we could run the following code:
-
-  book = Book.new
-  book.isbn = "0201710897"
-  book.title = "The PickAxe"
-  book.description = "Best Ruby book out there!"
-  book.author = "David Thomas, Andrew Hunt, Dave Thomas"
-
-  lib = Library.new
-  lib.name = "Favorite Books"
-  lib.books = [book]
-
-To save this information to an XML file:
-
-  doc = Nokogiri::XML::Document.new
-  doc.root = lib.to_xml
-  open("library.xml", 'w') do |file|
-    file << doc.serialize
-  end
-
-or
-
-  doc = LibXML::XML::Document.new
-  doc.root = lib.to_xml
-  doc.save("library.xml")
-
-To later populate the library object from the XML file:
-
-  lib = Library.from_xml(File.read("library.xml"))
-
-Similarly, to do a one-to-one mapping between XML objects, such as book and publisher,
-you would add a reference to another ROXML class. For example:
-
-  <book isbn="0974514055">
-    <title>Programming Ruby - 2nd Edition</title>
-    <description>Second edition of the great book.</description>
-    <publisher>
-      <name>Pragmatic Bookshelf</name>
-    </publisher>
-  </book>
-
-can be mapped using the following code:
-
-  class Publisher
-    include ROXML
-
-    xml_accessor :name
-
-    # other important functionality
+  
+  class Item
+    include Representable::XML
+    
+    representable_property :name
   end
+    
+== Consuming Representations
 
-  class BookWithPublisher
-    include ROXML
+Representable gives you easy access for consuming incoming representation documents. It maps the appropriate content to objects' attributes.
 
-    xml_name 'book'
-    xml_reader :publisher, :as => Publisher
+  @order = Order.from_xml(xml)
+  @order.id               # => "1"
+  @order.items            # => [<item>, <item>]
+  @order.items.first.name # => "Chocolate Cookie"
 
-    #  or, alternatively, if no class is needed to hang functionality on:
-    # xml_reader :publisher, :from => 'name', :in => 'publisher'
-  end
-
-Note: In the above example, _xml_name_ annotation tells ROXML to set the element
-name to "book" for mapping to XML. The default is XML element name is the class name in lowercase; "bookwithpublisher"
-in this case.
-
-=== Namespace Support
-
-Namespaced nodes are supported via the xml_namespace and xml_namespaces declarations and the :from and :namespace attr options.  See spec/xml/namespace_spec.rb for usage.
-
-Note that ROXML does not currently support outputting namespaced nodes.  This is planned for a future version.
 
-== Manipulation
+== Extendability
 
-Extending the above examples, say you want to parse a book's page count and have it available as an Integer.
-In such a case, you can extend any object with a block to manipulate it's value at parse time.  For example:
+The cool thing with object-oriented representations is: you can treat them just like any other object in Ruby and extend them dynamically - which is impossible with plain hashes.
 
-  class Dog
-    include ROXML
-
-    xml_reader(:age, :from => '@human_years', :as => Integer) {|years| years * 7 }
+  class Order
+    # ...
+    
+    def sort_items
+      items.sort! do |a,b|
+        a.name <=> b.name
+      end
+    end
   end
 
-The result of the block above is stored, rather than the actual value parsed from the document.
 
-== Construction
+== Generating Representations
 
-Object life-cycle is as follows: .from_xml is called with a first argument representing the xml
-in file, string, or path form, and with optional initialization_args following.
+Usually you have two places that share knowledge about a representation and its syntax and semantics: the parser <em>and</em> the renderer. With Representable, this is kept in one place.
 
-Firt .new and thus #initialize, is called with those same initialization_args, or no args if none
-are present.  Then the object is populated with the attribute values from xml.  Then the
-#after_parse callback is called, with no arguments.
+  @order.to_xml # => "<order><id>1</id>...</order>"
+  
+You can also render a representation from a newly created object.
 
-In #after_parse you can ensure that your object initialization is complete, including initialization which
-requires more than one variable in concert.
+  Order.new(:id => 2, :items => [candy]).to_xml
 
-E.g.:
 
-  class Measurement
-    include ROXML
+Representable makes working with representations extremely easy and testable.
 
-    xml_reader :units, :from => :attr
-    xml_reader :value, :from => :content
+== More
 
-    def initialize(value = 0, units = 'meters')
-      to_metric
-    end
+Representable was written with REST representations in mind. However, it is a generic module for working with documents. If you do consider using it for a REST project, check out the {Roar framework}[http://github.com/apotonick/roar], which comes with representers, built-in hypermedia support and more. It internally uses Representable and streamlines the process for building hypermedia-driven REST applications.
 
-  private
-    def after_parse
-      # xml attributes of self are already valid
-      to_metric
-    end
+Representable comes with parser and renderer for XML and JSON and can easily be extended (Warning: internal API still changing).
 
-    def to_metric
-      # translate units & value into metric, for example
-    end
-  end
-
-One important use of this approach is to make ROXML object which may or may not include an xml backing,
-which may be used via _new_ construction as well as _from_xml_ construction.
-
-== Selecting a parser
-
-By default, ROXML will use Nokogiri if it is available, followed by LibXML.  If you'd like to
-explicitly require one or the other, you may do the following:
-
-  module ROXML
-    XML_PARSER = 'nokogiri' # or 'libxml'
-  end
-  require 'roxml'
-
-For more information on available annotations, see ROXML::ClassMethods::Declarations
-
-== Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add specs for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but
-   bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
 
 == Copyright
 
-Copyright (c) 2004-2009 Ben Woosley, Zak Mandhro and Anders Engstrom. See LICENSE for details.
+Representable is a simplified fork of the ROXML gem. Big thanks to Ben Woosley for his work.
+
+Copyright (c) 2011 Nick Sutterer <apotonick@gmail.com>
+Copyright (c) 2004-2009 Ben Woosley, Zak Mandhro and Anders Engstrom.

data/lib/representable.rb

@@ -1,7 +1,5 @@
 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'
 
@@ -10,32 +8,19 @@ require 'hooks/inheritable_attribute'
 
 require 'representable/definition'
 require 'representable/nokogiri_extensions'
-require 'representable/references'
 
-require 'representable/xml' # TODO: do that dynamically.
+#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
   
@@ -204,39 +189,30 @@ module Representable
       # [: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
+      def representable_property(*args) # TODO: make it accept 1-n props.
+        attr = representable_attr(*args)
+        add_reader(attr)
+        attr_writer(attr.accessor)
       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)
+      
+      def representable_collection(name, options={})
+        options[:as] = [options[:as]].compact
+        representable_property(name, options)
+      end
+      
+    private
+      def representable_attr(name, options={})
+        definition_class.new(name, options).tap do |attr|
+          representable_attrs << 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)
+      
+      def representable_reader(*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)

data/lib/representable/bindings/json_bindings.rb

@@ -0,0 +1,69 @@
+module Representable
+  module JSON
+    class Binding
+      attr_reader :definition
+      delegate :required?, :array?, :accessor, :wrapper, :name, :to => :definition
+
+      def initialize(definition)
+        @definition = definition
+      end
+      
+      def value_in(hash)
+        value_from_hash(hash) or default
+      end
+      
+    private
+      def default
+        ""
+      end
+      
+      def collect_for(hash)
+        nodes = hash[name.to_s] or return
+        nodes = [nodes] unless nodes.is_a?(Array)
+        
+        vals  = nodes.collect { |node| yield node }
+        
+        array? ? vals : vals.first
+      end
+    end
+    
+    # Represents plain key-value.
+    class TextBinding < Binding
+      def update_json(hash, value)
+        hash[name] = value
+      end
+
+    private
+      def value_from_hash(hash)
+        collect_for(hash) do |value|
+          value
+        end
+      end
+    end
+  
+    # Represents a tag with object binding.
+    class ObjectBinding < Binding
+      delegate :sought_type, :to => :definition
+      
+      def update_json(hash, value)
+        if array?
+          hash.merge! ({accessor => value.collect {|v| v.to_json(:wrap => false)}}) # hier name=> wech.
+        else
+          hash.merge! value.to_json
+        end
+      end
+
+    private
+      def default
+        []
+      end
+      
+      def value_from_hash(xml)
+        collect_for(xml) do |node|
+          sought_type.from_json(node, :wrap => false) # hier name=> wech.
+        end
+      end
+      
+    end
+  end
+end

data/lib/representable/bindings/xml_bindings.rb

@@ -0,0 +1,152 @@
+module Representable
+  module XML
+    class Binding
+      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 AttributeBinding < Binding
+      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. # FIXME: is this tested???
+    class TextBinding < Binding
+      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 NamespaceBinding < Binding
+    private
+      def value_from_node(xml)
+        xml.namespace.prefix
+      end
+    end
+
+    # Represents a tag with object binding.
+    class ObjectBinding < Binding
+      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
+end