representable 1.2.9 → 1.3.0

data/CHANGES.textile

@@ -1,3 +1,9 @@
+h2. 1.3.0
+
+* Remove @:exclude@ option.
+* Moving all read/write logic to @Binding@. If you did override @#read_fragment@ and friends in your representer/models this won't work anymore.
+* Options passed to @to_*/from_*@ are now passed to nested objects. 
+
 h2. 1.2.9
 
 * When @:class@ returns @nil@ we no longer try to create a new instance but use the processed fragment itself.

data/README.md

@@ -0,0 +1,485 @@
+# Representable
+
+Representable maps ruby objects to documents and back.
+
+In other words: Take an object and extend it with a representer module. This will allow you to render a JSON, XML or YAML document from that object. But that's only half of it! You can also use representers to parse a document and create an object.
+
+Representable is helpful for all kind of rendering and parsing workflows. However, it is mostly useful in API code. Are you planning to write a real REST API with representable? Then check out the [roar](http://github.com/apotonick/roar) gem first, save work and time and make the world a better place instead.
+
+
+## Installation
+
+The representable gem is almost dependency-free. Almost.
+
+    gem 'representable'
+
+
+## Example
+
+What if we're writing an API for music - songs, albums, bands.
+
+    class Song < OpenStruct
+    end
+
+    song = Song.new(title: "Fallout", track: 1)
+
+
+## Defining Representations
+
+Representations are defined using representer modules.
+
+    require 'representable/json'
+
+    module SongRepresenter
+      include Representable::JSON
+
+      property :title
+      property :track
+    end
+
+In the representer the #property method allows declaring represented attributes of the object. All the representer requires for rendering are readers on the represented object, e.g. `#title` and `#track`. When parsing, it will call setters - in our example, that'd be `#title=` and `#track=`.
+
+
+## Rendering
+
+Mixing in the representer into the object adds a rendering method.
+
+    song.extend(SongRepresenter).to_json
+    #=> {"title":"Fallout","track":1}
+
+
+## Parsing
+
+It also adds support for parsing.
+
+    song = Song.new.extend(SongRepresenter).from_json(%{ {"title":"Roxanne"} })
+    #=> #<Song title="Roxanne", track=nil>
+
+
+## Wrapping
+
+Let the representer know if you want wrapping.
+
+    module SongRepresenter
+      include Representable::JSON
+
+      self.representation_wrap= :hit
+
+      property :title
+      property :track
+    end
+
+This will add a container for rendering and consuming.
+
+    song.extend(SongRepresenter).to_json
+    #=> {"hit":{"title":"Fallout","track":1}}
+
+Setting `self.representation_wrap = true` will advice representable to figure out the wrap itself by inspecting the represented object class.
+
+
+## Collections
+
+Let's add a list of composers to the song representation.
+
+    module SongRepresenter
+      include Representable::JSON
+
+      property :title
+      property :track
+      collection :composers
+    end
+
+Surprisingly, `#collection` lets us define lists of objects to represent.
+
+    Song.new(title: "Fallout", composers: ["Steward Copeland", "Sting"]).
+      extend(SongRepresenter).to_json
+
+    #=> {"title":"Fallout","composers":["Steward Copeland","Sting"]}
+
+
+And again, this works both ways - in addition to the title it extracts the composers from the document, too.
+
+
+## Nesting
+
+Representers can also manage compositions. Why not use an album that contains a list of songs?
+
+    class Album < OpenStruct
+    end
+
+    album = Album.new(name: "The Police", songs: [song, Song.new(title: "Synchronicity")])
+
+
+Here comes the representer that defines the composition.
+
+    module AlbumRepresenter
+      include Representable::JSON
+
+      property :name
+      collection :songs, extend: SongRepresenter, class: Song
+    end
+
+Note that nesting works with both plain `#property` and `#collection`.
+
+When rendering, the `:extend` module is used to extend the attribute(s) with the correct representer module.
+
+    album.extend(AlbumRepresenter).to_json
+    #=> {"name":"The Police","songs":[{"title":"Fallout","composers":["Steward Copeland","Sting"]},{"title":"Synchronicity","composers":[]}]}
+
+Parsing a documents needs both `:extend` and the `:class` option as the parser requires knowledge what kind of object to create from the nested composition.
+
+    Album.new.extend(AlbumRepresenter).
+      from_json(%{{"name":"Offspring","songs":[{"title":"Genocide"},{"title":"Nitro","composers":["Offspring"]}]}})
+
+    #=> #<Album name="Offspring", songs=[#<Song title="Genocide">, #<Song title="Nitro", composers=["Offspring"]>]>
+
+
+## XML Support
+
+While representable does a great job with JSON, it also features support for XML, YAML and pure ruby hashes.
+
+    require 'representable/xml'
+
+    module SongRepresenter
+      include Representable::XML
+
+      property :title
+      property :track
+      collection :composers
+    end
+
+For XML we just include the `Representable::XML` module.
+
+    Song.new(title: "Fallout", composers: ["Steward Copeland", "Sting"]).
+      extend(SongRepresenter).to_xml
+
+    #=> <song>
+          <title>Fallout</title>
+          <composers>Steward Copeland</composers>
+          <composers>Sting</composers>
+        </song>
+
+
+## Using Helpers
+
+Sometimes it's useful to override accessors to customize output or parsing.
+
+    module AlbumRepresenter
+      include Representable::JSON
+      
+      property :name
+      collection :songs
+
+      def name
+        super.upcase
+      end
+    end
+
+    Album.new(:name => "The Police").
+      extend(AlbumRepresenter).to_json
+
+    #=> {"name":"THE POLICE","songs":[]}
+
+Note how the representer allows calling `super` in order to access the original attribute method of the represented object.
+
+To change the parsing process override the setter.
+
+      def name=(value)
+        super(value.downcase)
+      end
+
+
+## Inheritance
+
+To reuse existing representers you can inherit from those modules.
+
+    module CoverSongRepresenter
+      include Representable::JSON
+      include SongRepresenter
+
+      property :copyright
+    end
+
+Inheritance works by `include`ing already defined representers.
+
+    Song.new(:title => "Truth Hits Everybody", :copyright => "The Police").
+      extend(CoverSongRepresenter).to_json
+
+    #=> {"title":"Truth Hits Everybody","copyright":"The Police"}
+
+
+## Polymorphic Extend
+
+Sometimes heterogenous collections of objects from different classes must be represented. Or you don't know which representer to use at compile-time and need to delay the computation until runtime. This is why `:extend` accepts a lambda, too.
+
+Given we not only have songs, but also cover songs.
+
+    class CoverSong < Song
+    end
+
+And a non-homogenous collection of songs.
+
+    songs = [ Song.new(title: "Weirdo", track: 5), 
+              CoverSong.new(title: "Truth Hits Everybody", track: 6, copyright: "The Police")]
+    
+    album = Album.new(name: "Incognito", songs: songs)
+
+
+The `CoverSong` instances are to be represented by their very own `CoverSongRepresenter` defined above. We can't just use a static module in the `:extend` option, so go use a dynamic lambda!
+
+    module AlbumRepresenter
+      include Representable::JSON
+
+      property :name
+      collection :songs, :extend => lambda { |song| song.is_a?(CoverSong) ? CoverSongRepresenter : SongRepresenter }
+    end
+
+Note that the lambda block is evaluated in the represented object context which allows to access helpers or whatever in the block. This works for single properties, too.
+
+
+## Polymorphic Object Creation
+
+Rendering heterogenous collections usually implies that you also need to parse those. Luckily, `:class` also accepts a lambda.
+
+    module AlbumRepresenter
+      include Representable::JSON
+
+      property :name
+      collection :songs, 
+        :extend => ...,
+        :class  => lambda { |hsh| hsh.has_key?("copyright") ? CoverSong : Song }
+    end
+
+The block for `:class` receives the currently parsed fragment. Here, this might be somthing like `{"title"=>"Weirdo", "track"=>5}`.
+
+If this is not enough, you may override the entire object creation process using `:instance`.
+
+    module AlbumRepresenter
+      include Representable::JSON
+
+      property :name
+      collection :songs, 
+        :extend   => ...,
+        :instance => lambda { |hsh| hsh.has_key?("copyright") ? CoverSong.new : Song.new(original: true) }
+    end
+
+
+## Hashes
+
+As an addition to single properties and collections representable also offers to represent hash attributes.
+    
+    module SongRepresenter
+      include Representable::JSON
+
+      property :title
+      hash :ratings
+    end
+
+    Song.new(title: "Bliss", ratings: {"Rolling Stone" => 4.9, "FryZine" => 4.5}).
+    extend(SongRepresenter).to_json
+    
+    #=> {"title":"Bliss","ratings":{"Rolling Stone":4.9,"FryZine":4.5}}
+
+
+## Lonely Hashes
+
+Need to represent a bare hash without any container? Use the `JSON::Hash` representer (or XML::Hash).
+
+    require 'representable/json/hash'
+
+    module FavoriteSongsRepresenter
+      include Representable::JSON::Hash
+    end
+
+    {"Nick" => "Hyper Music", "El" => "Blown In The Wind"}.extend(FavoriteSongsRepresenter).to_json
+    #=> {"Nick":"Hyper Music","El":"Blown In The Wind"}
+
+Works both ways. The values are configurable and might be self-representing objects in turn. Tell the `Hash` by using `#values`.
+
+    module FavoriteSongsRepresenter
+      include Representable::JSON::Hash
+
+      values extend: SongRepresenter, class: Song
+    end
+
+    {"Nick" => Song.new(title: "Hyper Music")}.extend(FavoriteSongsRepresenter).to_json
+
+ In XML, if you want to store hash attributes in tag attributes instead of dedicated nodes, use `XML::AttributeHash`.
+
+## Lonely Collections
+
+Same goes with arrays.
+
+    require 'representable/json/collection'
+
+    module SongsRepresenter
+      include Representable::JSON::Collection
+
+      items extend: SongRepresenter, class: Song
+    end
+
+The `#items` method lets you configure the contained entity representing here.
+
+    [Song.new(title: "Hyper Music"), Song.new(title: "Screenager")].extend(SongsRepresenter).to_json
+    #=> [{"title":"Hyper Music"},{"title":"Screenager"}]
+
+Note that this also works for XML.
+
+
+## YAML Support
+
+Representable also comes with a YAML representer.
+
+    module SongRepresenter
+      include Representable::YAML
+
+      property :title
+      property :track
+      collection :composers, :style => :flow
+    end
+
+A nice feature is that `#collection` also accepts a `:style` option which helps having nicely formatted inline (or "flow") arrays in your YAML - if you want that!
+
+    song.extend(SongRepresenter).to_yaml
+    #=>
+    ---
+    title: Fallout
+    composers: [Steward Copeland, Sting]
+
+
+## More on XML
+
+### Mapping tag attributes
+
+You can also map properties to tag attributes in representable.
+
+    module SongRepresenter
+      include Representable::XML
+
+      property :title, attribute: true
+      property :track, attribute: true
+    end
+    
+    Song.new(title: "American Idle").to_xml
+    #=> <song title="American Idle" />
+
+Naturally, this works for both ways.
+
+### Wrapping collections
+
+It is sometimes unavoidable to wrap tag lists in a container tag.
+
+    module AlbumRepresenter
+      include Representable::XML
+
+      collection :songs, :as => :song, :wrap => :songs
+    end
+
+Note that `:wrap` defines the container tag name.
+
+    Album.new.to_xml #=> 
+      <album>
+        <songs>
+          <song>Laundry Basket</song>
+          <song>Two Kevins</song>
+          <song>Wright and Rong</song>
+        </songs>
+      </album>
+
+
+## Avoiding Modules
+
+There's been a rough discussion whether or not to use `extend` in Ruby. If you want to save that particular step when representing objects, define the representers right in your classes.
+
+    class Song < OpenStruct
+      include Representable::JSON
+
+      property :name
+    end
+
+I do not recommend this approach as it bloats your domain classes with representation logic that is barely needed elsewhere.
+
+
+## More Options
+
+Here's a quick overview about other available options for `#property` and its bro `#collection`.
+
+
+### Read/Write Restrictions
+
+Using the `:readable` and `:writeable` options access to properties can be restricted.
+
+    property :title, :readable => false
+
+This will leave out the `title` property in the rendered document. Vice-versa, `:writeable` will skip the property when parsing and does not assign it.
+
+
+### Filtering
+
+Representable also allows you to skip and include properties using the `:exclude` and `:include` options passed directly to the respective method.
+
+    song.to_json(:include => :title)
+    #=> {"title":"Roxanne"}
+
+
+### Conditions
+
+You can also define conditions on properties using `:if`, making them being considered only when the block returns a true value.
+
+    module SongRepresenter
+      include Representable::JSON
+
+      property :title
+      property :track, if: lambda { track > 0 }
+    end
+  
+When rendering or parsing, the `track` property is considered only if track is valid. Note that the block is executed in instance context, giving you access to instance methods.
+
+
+### Mapping
+
+If your property name doesn't match the attribute name in the document, use the `:as` option.
+
+    module SongRepresenter
+      property :title
+      property :track, as: :track_number
+    end
+    
+    song.to_json #=> {"title":"Superstars","track_number":1}
+
+
+### False and Nil Values
+
+Since representable-1.2 `false` values _are_ considered when parsing and rendering. That particularly means properties that used to be unset (i.e. `nil`) after parsing might be `false` now. Vice versa, `false` properties that weren't included in the rendered document will be visible now.
+
+If you want `nil` values to be included when rendering, use the `:render_nil` option.
+
+  property :track, render_nil: true
+
+
+## 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.
+
+Include virtus in your Gemfile, first. Be sure to include virtus 0.5.0 or greater.
+
+    gem 'virtus', ">= 0.5.0"
+
+Use the `:type` option to specify the conversion target. Note that `:default` still works.
+
+    module SongRepresenter
+      include Representable::JSON
+      include Virtus
+      include Representable::Coercion
+      
+      property :title
+      property :recorded_at, :type => DateTime, :default => "May 12th, 2012"
+    end
+
+
+## Copyright
+
+Representable started as a heavily simplified fork of the ROXML gem. Big thanks to Ben Woosley for his inspiring work.
+
+* Copyright (c) 2011-2013 Nick Sutterer <apotonick@gmail.com>
+* ROXML is Copyright (c) 2004-2009 Ben Woosley, Zak Mandhro and Anders Engstrom.