representable 1.2.4 → 1.2.5

data/CHANGES.textile

@@ -1,3 +1,7 @@
+h2. 1.2.5
+
+* Add support for YAML.
+
 h2. 1.2.4
 
 * ObjectBinding no longer tries to extend nil values when rendering and @:render_nil@ is set.

data/README.rdoc

@@ -14,7 +14,7 @@ This keeps your representation knowledge in one place when implementing REST ser
 
 * Bidirectional - rendering and parsing
 * OOP access to documents
-* Support for JSON and XML
+* Support for JSON, XML and YAML.
 * Coercion support with virtus[https://github.com/solnic/virtus]
 
 
@@ -279,7 +279,7 @@ There's no need to specify a representer for the +origin+ property since the +Lo
 
 == XML support
 
-Representable allows declaring a document's syntax and structure while having different formats. Currently, it ships with JSON and XML bindings.
+Representable allows declaring a document's syntax and structure while having different formats. Currently, it ships with JSON, XML and YAML bindings.
   
   class Hero
     include Representable::XML
@@ -338,6 +338,50 @@ Note that +:wrap+ defines the container tag name.
       </songs>
     </album>
 
+
+== YAML Support
+
+Representers also come in handy if you need to render or parse YAML. The YAML module works exactly like the others.
+
+  module HotBandsRepresenter
+    include Representable::YAML
+
+    property :for
+    collection :names
+  end
+
+Now, just call #to_yaml to render or #from_yaml to parse.
+
+  HotBands.new(:for => "Nick", :names => ["Bad Religion", "Van Halen", "Mozart"]).
+    extend(HotBandsRepresenter).
+    to_yaml
+
+  #=> ---
+  for: Nick
+  names:
+  - Bad Religion
+  - Van Halen
+  - Mozart
+
+=== Nested Objects
+
+The YAML parser does handle nested objects just like JSON and XML does it.
+
+=== Flow Style Lists
+
+If you want flow style (aka inline style) lists, use the :style option. See http://www.yaml.org/spec/1.2/spec.html#id2790088 for more infos on flow sequences.
+
+  module HotBandsRepresenter
+    include Representable::YAML
+
+    collection :names, :style => :flow
+  end
+
+  #=> ---
+  names: [Bad Religion, Van Halen, Mozart]
+
+Need anything else for YAML? Let me know.
+
 == Coercion
 
 If you fancy coercion when parsing a document you can use the Coercion module which uses virtus[https://github.com/solnic/virtus] for type conversion.

data/gemfiles/Gemfile.mongoid-2.4

@@ -4,3 +4,4 @@ source "http://rubygems.org"
 gemspec :path => '../'
 
 gem 'mongoid', '~> 2.4.0'
+gem 'psych'

data/lib/representable/bindings/yaml_bindings.rb

@@ -0,0 +1,69 @@
+require 'representable/binding'
+
+module Representable
+  module YAML
+    module ObjectBinding
+      include Binding::Object
+      
+      def serialize_method
+        :to_ast
+      end
+      
+      def deserialize_method
+        :from_hash
+      end
+
+      def write_scalar(value)
+        value
+      end
+    end
+
+    class YAMLBinding < Representable::Binding
+      def initialize(definition) # FIXME. make generic.
+        super
+        extend ObjectBinding if definition.typed?
+      end
+      
+      def read(hash)
+        return FragmentNotFound unless hash.has_key?(definition.from) # DISCUSS: put it all in #read for performance. not really sure if i like returning that special thing.
+        
+        fragment = hash[definition.from]
+        deserialize_from(fragment)
+      end
+      
+      def write(map, value)
+        map.children << Psych::Nodes::Scalar.new(definition.from)
+        map.children << serialize_for(value)  # FIXME: should be serialize.
+      end
+    end
+    
+    
+    class PropertyBinding < YAMLBinding
+      def serialize_for(value)
+        write_scalar serialize(value)
+      end
+      
+      def deserialize_from(fragment)
+        deserialize(fragment)
+      end
+
+      def write_scalar(value)
+        Psych::Nodes::Scalar.new(value.to_s)
+      end
+    end
+    
+    
+    class CollectionBinding < PropertyBinding
+      def serialize_for(value)
+        Psych::Nodes::Sequence.new.tap do |seq|
+          seq.style = Psych::Nodes::Sequence::FLOW if definition.options[:style] == :flow
+          value.each { |obj| seq.children << super(obj) }
+        end
+      end
+      
+      def deserialize_from(fragment)
+        fragment.collect { |item_fragment| deserialize(item_fragment) }
+      end
+    end
+  end
+end

data/lib/representable/version.rb

@@ -1,3 +1,3 @@
 module Representable
-  VERSION = "1.2.4"
+  VERSION = "1.2.5"
 end

data/lib/representable/yaml.rb

@@ -0,0 +1,67 @@
+require 'representable'
+require 'representable/bindings/yaml_bindings'
+
+module Representable
+  module YAML
+    def self.binding_for_definition(definition)
+      return CollectionBinding.new(definition)      if definition.array?
+      #return HashBinding.new(definition)            if definition.hash? and not definition.options[:use_attributes] # FIXME: hate this.
+      #return AttributeHashBinding.new(definition)   if definition.hash? and definition.options[:use_attributes]
+      #return AttributeBinding.new(definition)       if definition.attribute
+      PropertyBinding.new(definition)
+    end
+    
+    def self.included(base)
+      base.class_eval do
+        include Representable
+        extend ClassMethods
+        #self.representation_wrap = true # let representable compute it.
+      end
+    end
+    
+    
+    module ClassMethods
+      # Creates a new Ruby object from XML using mapping information declared in the class.
+      #
+      # Accepts a block yielding the currently iterated Definition. If the block returns false 
+      # the property is skipped.
+      #
+      # Example:
+      #   band.from_xml("<band><name>Nofx</name></band>")
+      def from_xml(*args, &block)
+        create_represented(*args, &block).from_xml(*args)
+      end
+      
+      def from_node(*args, &block)
+        create_represented(*args, &block).from_node(*args)
+      end
+    end
+    
+    
+    def from_yaml(doc, *args)
+      hash = Psych.load(doc)
+      from_hash(hash, *args)
+    end
+    
+    def from_hash(hash, options={})
+      update_properties_from(hash, options, YAML)
+    end
+    
+    # Returns a Nokogiri::XML object representing this object.
+    def to_ast(options={})
+      #root_tag = options[:wrap] || representation_wrap
+      
+      Psych::Nodes::Mapping.new.tap do |map|
+        create_representation_with(map, options, YAML)
+      end
+    end
+    
+    def to_yaml(*args)
+      stream = Psych::Nodes::Stream.new 
+      stream.children << doc = Psych::Nodes::Document.new
+      
+      doc.children << to_ast(*args)
+      stream.to_yaml
+    end
+  end
+end

data/test/json_test.rb

@@ -185,7 +185,7 @@ module JsonTest
       end
 
       it "extends contained models when serializing" do
-        @album = Album.new(Song.new("I Hate My Brain"), Song.new("Mr. Charisma"))
+        @album = Album.new([Song.new("I Hate My Brain"), mr=Song.new("Mr. Charisma")], mr)
         @album.extend(AlbumRepresenter)
 
         assert_json "{\"best_song\":{\"name\":\"Mr. Charisma\"},\"songs\":[{\"name\":\"I Hate My Brain\"},{\"name\":\"Mr. Charisma\"}]}", @album.to_json

data/test/test_helper.rb

@@ -13,20 +13,25 @@ require 'mocha'
 
 class Album
   attr_accessor :songs, :best_song
-  def initialize(*songs)
+  def initialize(songs=nil, best_song=nil)
     @songs      = songs
-    @best_song  = songs.last
+    @best_song  = best_song
+  end
+
+  def ==(other)
+    songs == other.songs and best_song == other.best_song
   end
 end
 
 class Song
-  attr_accessor :name
-  def initialize(name=nil)
-    @name = name
+  attr_accessor :name, :track
+  def initialize(name=nil, track=nil)
+    @name   = name
+    @track  = track
   end
 
   def ==(other)
-    name == other.name
+    name == other.name and track == other.track
   end
 end
 

data/test/xml_test.rb

@@ -178,7 +178,7 @@ class XmlTest < MiniTest::Spec
       end
       
       it "extends contained models when serializing" do
-        @album = Album.new(Song.new("I Hate My Brain"), Song.new("Mr. Charisma"))
+        @album = Album.new([Song.new("I Hate My Brain"), mr=Song.new("Mr. Charisma")], mr)
         @album.extend(AlbumRepresenter)
         
         assert_xml_equal "<album>

data/test/yaml_test.rb

@@ -0,0 +1,166 @@
+require 'test_helper'
+require 'representable/yaml'
+
+class YamlTest < MiniTest::Spec
+  def self.yaml_representer(&block)
+    Module.new do
+      include Representable::YAML
+      instance_exec &block
+    end
+  end
+
+  def yaml_representer(&block)
+    self.class.yaml_representer(&block)
+  end
+
+
+  describe "property" do
+    let (:yaml) { yaml_representer do property :best_song end }
+
+    let (:album) { Album.new.tap do |album|
+      album.best_song = "Liar"
+    end }
+
+    describe "#to_yaml" do
+      it "renders plain property" do
+        album.extend(yaml).to_yaml.must_equal(
+"---
+best_song: Liar
+")
+      end
+
+      it "always renders values into strings" do
+        Album.new.tap { |a| a.best_song = 8675309 }.extend(yaml).to_yaml.must_equal(
+"---
+best_song: 8675309
+"
+)
+      end
+    end
+
+
+    describe "#from_yaml" do
+      it "parses plain property" do
+        album.extend(yaml).from_yaml(
+"---
+best_song: This Song Is Recycled
+").best_song.must_equal "This Song Is Recycled"
+      end
+    end
+
+
+    describe "with :class and :extend" do
+      yaml_song = yaml_representer do property :name end
+      let (:yaml_album) { Module.new do
+        include Representable::YAML
+        property :best_song, :extend => yaml_song, :class => Song
+      end }
+
+      let (:album) { Album.new.tap do |album|
+        album.best_song = Song.new("Liar")
+      end }
+
+
+      describe "#to_yaml" do
+        it "renders embedded typed property" do
+          album.extend(yaml_album).to_yaml.must_equal "---
+best_song:
+  name: Liar
+"
+        end
+      end
+
+      describe "#from_yaml" do
+        it "parses embedded typed property" do
+          album.extend(yaml_album).from_yaml("---
+best_song:
+  name: Go With Me
+").must_equal Album.new(nil,Song.new("Go With Me"))
+        end
+      end
+    end
+  end
+
+
+  describe "collection" do
+    let (:yaml) { yaml_representer do collection :songs end }
+
+    let (:album) { Album.new.tap do |album|
+      album.songs = ["Jackhammer", "Terrible Man"]
+    end }
+
+
+    describe "#to_yaml" do
+      it "renders a block style list per default" do
+        album.extend(yaml).to_yaml.must_equal "---
+songs:
+- Jackhammer
+- Terrible Man
+"
+      end
+
+      it "renders a flow style list when :style => :flow set" do
+        yaml = yaml_representer { collection :songs, :style => :flow }
+        album.extend(yaml).to_yaml.must_equal "---
+songs: [Jackhammer, Terrible Man]
+"
+      end
+    end
+
+
+    describe "#from_yaml" do
+      it "parses a block style list" do
+        album.extend(yaml).from_yaml("---
+songs:
+- Off Key Melody
+- Sinking").must_equal Album.new(["Off Key Melody", "Sinking"])
+
+      end
+
+      it "parses a flow style list" do
+        album.extend(yaml).from_yaml("---
+songs: [Off Key Melody, Sinking]").must_equal Album.new(["Off Key Melody", "Sinking"])
+      end
+    end
+
+
+    describe "with :class and :extend" do
+      yaml_song = yaml_representer do 
+        property :name
+        property :track
+      end
+      let (:yaml_album) { Module.new do
+        include Representable::YAML
+        collection :songs, :extend => yaml_song, :class => Song
+      end }
+
+      let (:album) { Album.new.tap do |album|
+        album.songs = [Song.new("Liar", 1), Song.new("What I Know", 2)]
+      end }
+
+
+      describe "#to_yaml" do
+        it "renders collection of typed property" do
+          album.extend(yaml_album).to_yaml.must_equal "---
+songs:
+- name: Liar
+  track: 1
+- name: What I Know
+  track: 2
+"
+        end
+      end
+
+      describe "#from_yaml" do
+        it "parses collection of typed property" do
+          album.extend(yaml_album).from_yaml("---
+songs:
+- name: One Shot Deal
+  track: 4
+- name: Three Way Dance
+  track: 5").must_equal Album.new([Song.new("One Shot Deal", 4), Song.new("Three Way Dance", 5)])
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: representable
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.2.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-25 00:00:00.000000000 Z
+date: 2012-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -160,6 +160,7 @@ files:
 - lib/representable/binding.rb
 - lib/representable/bindings/json_bindings.rb
 - lib/representable/bindings/xml_bindings.rb
+- lib/representable/bindings/yaml_bindings.rb
 - lib/representable/coercion.rb
 - lib/representable/definition.rb
 - lib/representable/deprecations.rb
@@ -171,6 +172,7 @@ files:
 - lib/representable/xml.rb
 - lib/representable/xml/collection.rb
 - lib/representable/xml/hash.rb
+- lib/representable/yaml.rb
 - representable.gemspec
 - test/coercion_test.rb
 - test/definition_test.rb
@@ -183,6 +185,7 @@ files:
 - test/test_helper_test.rb
 - test/xml_bindings_test.rb
 - test/xml_test.rb
+- test/yaml_test.rb
 homepage: http://representable.apotomo.de
 licenses: []
 post_install_message: