representable 1.7.7 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 453857338b438b7d68ffcdc22c4a673132d3193e
-  data.tar.gz: 19635dc3d647a965fcfe0af872db31f3eb305db3
+  metadata.gz: b00de985635f525b8a01171885aed414e6204034
+  data.tar.gz: dc62dd3c718b5969a663da9587ef815ddb4eb6e8
 SHA512:
-  metadata.gz: e20ce7e46c5a94ab219a8936c04fa1a6ed7c1f77f2be36fab23685b80c1fda109c950dd011ae35c5a638ba04e0ce739f64d612d4a01c826bc75bcdee16524e2b
-  data.tar.gz: 58791da0eef9d17e2c3f24c82fc9c532cbfdea78d159cd09be33bf91755257adb0dbf9cb889c4facc81a17a81995ae8d5e4712063aaf4549ab571db12d9426c4
+  metadata.gz: 9a7cc3fb19f4319e69cbf66e566ae70b9a8ede10bc5b9666756128ab7795eec2c35315f31603ff3ad3fa8b78ac170270389ba33e128b6848496d45fd1cec615f
+  data.tar.gz: d2eb8e52c0485aebea0fe956fa98ef9d9c06f87a8d00a0d027dbea804b573982b364d1bcc06f3db65bbeb33e89e814a594300302675776be11024ce335569d69

data/CHANGES.md

@@ -1,11 +1,45 @@
-h2. 1.8.0
-
-* Major API change: Remove defaults for collections. This fixes a major design flaw - when parsing a document a collection would be reset to `[]` even if it is not present in the parsed document.
-* Minor API change: Rename `Definition#sought_type` to `#deserialize_class`.
--> constantize :class etc (requires AS)
--> make all options lambda-able
--> make major steps lambda-able
--> strategies for deserialization (lambda-able!)
+# 1.8.0
+
+## Major Breakage
+
+* `:if` receives block arguments just like any other dynamic options. Refer to **Dynamic Options**.
+* Remove defaults for collections. This fixes a major design flaw - when parsing a document a collection would be reset to `[]` even if it is not present in the parsed document.
+* The number of arguments per block might have changed. Generally, if you're not interested in block arguments, use `Proc.new` or `lambda { |*| }`. See **Dynamic Options**.
+
+
+## Dynamic Options
+
+* The following options are dynamic now and can either be a static value, a lambda or an instance method symbol: `:as`, `:getter`, `:setter`, `:class`, `:instance`, `:reader`, `:writer`, `:extend`, `:prepare`, `:if`. Please refer to the README to see their signatures.
+* `representation_wrap` is dynamic, too, allowing you to change the wrap per instance.
+
+
+## Cool New Stuff
+
+* When unsure about the number of arguments passed into an option lambda, use `:pass_options`. This passes all general options in a dedicated `Options` object that responds to `binding`, `decorator`, `represented` and `user_options`. It's always the last argument for the block.
+* Added `parse_strategy: :find_or_instantiate`. More to come.
+* Use `representable: false` to prevent calling `to_*/from_*` on a represented object even if the property is `typed?` (`:extend`, `:class` or `:instance` set).
+* Introduced `:use_decorator` option to force an inline representer to be implemented with a Decorator even in a module. This fixes a bug since we used the `:decorate` option in earlier versions, which was already used for something else.
+* Autoload `Representable::Hash*` and `Representable::Decorator`.
+* Added `Representable::Hash::AllowSymbols` to convert symbol keys to strings in `from_hash`.
+
+
+## Deprecations
+* `decorator_scope: true` is deprecated, use `exec_context: :decorator` instead.
+* Using `:extend` in combination with an inline representer is deprecated. Include the module in the block.
+* `instance: lambda { true }` is deprecated. Use `parse_strategy: :sync`.
+* Removed `Config#wrap`. Only way to retrieve the evaluated wrap is `Config#wrap_for`.
+* `class: lambda { nil }` is deprecated. To return the fragment from parsing, use `instance: lambda { |fragment, *args| fragment }` instead.
+
+## Definition
+
+* Make `Definition < Hash`, all options can/should now be accessed with `Definition#[]`.
+* Make `Definition::new` and `#merge!` the only entry points so that a `Definition` becomes an almost *immutual* object. If you happened to modify a definition using `options[..]=` this will break now. Use `definition.merge!(..)` to change it after creation.
+* Deprecated `#options` as the definition itself is a hash (e.g. `definition[:default]`).
+* Removed `#sought_type`, `#default`, `#attribute`, `#content`.
+* `#from` is replaced by `#as` and hardcore deprecated.
+* `#name` and `#as` are _always_ strings.
+* A Definition is considered typed as soon as [`:extend`|`:class`|`:instance`] is set. In earlier versions, `property :song, class: Song` was considered typed, whereas `property :song, class: lambda { Song }` was static.
+
 
 h2. 1.7.7
 

data/README.md

@@ -174,9 +174,28 @@ Album.new.extend(AlbumRepresenter).
 #=> #<Album name="Offspring", songs=[#<Song title="Genocide">, #<Song title="Nitro", composers=["Offspring"]>]>
 ```
 
+
+## Parse Strategies
+
+When parsing `collection`s (also applies to single `property`s), representable usually iterates the incoming list and creates a new object per array item.
+
+Parse strategies let you do that manually.
+
+```ruby
+collection :songs, :parse_strategy => lambda { |fragment, i, options|
+  songs << song = Song.new
+  song
+}
+```
+
+The above code will *add* a new `Song` per incoming item. Each instance will still be extended and populated with attributes (note that you can [change that](#skipping-rendering-or-parsing) as well).
+
+This gives you all the freedom you need for your nested parsing.
+
+
 ## Syncing Objects
 
-Usually, representable creates a new nested object when parsing. If you want to update an existing object, use the `parse_strategy` option.
+Usually, representable creates a new nested object when parsing. If you want to update an existing object, use the `parse_strategy: :sync` option.
 
 ```ruby
 module AlbumRepresenter
@@ -203,6 +222,32 @@ album.songs.first #=> #<Song:0x999 title: "Eruption">
 
 Now, representable didn't create a new `Song` instance but updated the existing, resulting in renaming the song.
 
+
+## Find-or-Create For Incoming Objects
+
+Representable comes with another strategy called `:find_or_instantiate` which allows creating a property or collection from the incoming document.
+
+Consider the following incoming hash.
+
+```ruby
+{"songs" => [{"id" => 1, "title" => "American Paradox"}, {"title" => "Uncoil"}}
+```
+
+And this representer setup.
+
+```ruby
+collection :songs, class: Song, parse_strategy: :find_or_instantiate
+```
+
+In `album.from_hash(..)`, representable will try to call `Song.find(1)` for the first `songs` collection element and `Song.new` for the second (as it doesn't has any `id`), resulting in an array of two `Song` instances, the first an existing, the second a new object.
+
+**Note**: the various parsing strategies are a collection of "best practices" people find useful. Such a strategy is basically just a set of configuration options, mainly utilizing the `:instance` option.
+
+Check out the `ParsingStrategy` module to write your own strategy. If you find it useful, please commit it to the core library (with tests).
+
+The current state of the `:find_or_instantiate` strategy is subject to change.
+
+
 ## Inline Representers
 
 If you don't want to maintain two separate modules when nesting representations you can define the `SongRepresenter` inline.
@@ -222,13 +267,15 @@ module AlbumRepresenter
 
 This works both for representer modules and decorators.
 
-You can use an inline representer along with `:extend`. The latter will automatically be included in the inline representer. This is handy if you want to inline-extend a base decorator.
+An inline representer is just a Ruby module. You can include other representer modules. This is handy when having a base representer that needs to be extended in the inline block.
 
 ```ruby
 module AlbumRepresenter
   include Representable::JSON
 
-  property :hit, extend: SongRepresenter do
+  property :hit do
+    include SongRepresenter
+
     property :numbers_sold
   end
 ```
@@ -315,7 +362,7 @@ That works as the method is mixed into the represented object. When adding a hel
 
 ```ruby
 class SongRepresenter < Representable::Decorator
-  property :title, decorator_scope: true
+  property :title, exec_context: :decorator
 
   def title
     represented.name
@@ -323,7 +370,9 @@ class SongRepresenter < Representable::Decorator
 end
 ```
 
-This will call `title` getter and setter on the decorator instance, not on the represented object. You can still access the represented object in the decorator method using `represented`. BTW, in a module representer this option is ignored.
+This will call `title` getter and setter on the decorator instance, not on the represented object. You can still access the represented object in the decorator method using `represented`. BTW, in a module representer this option setting is ignored.
+
+Possible values for this switch (formerly known as `:decorator_scope`) are `:binding`, `:decorator` and `nil`, which is the default setting where lambdas and methods are invoked in the represented context.
 
 Or use `:getter` or `:setter` to dynamically add a method for the represented object.
 
@@ -333,33 +382,6 @@ class SongRepresenter < Representable::Decorator
 ```
 As always, the block is executed in the represented object's context.
 
-## XML Support
-
-While representable does a great job with JSON, it also features support for XML, YAML and pure ruby hashes.
-
-```ruby
-require 'representable/xml'
-
-module SongRepresenter
-  include Representable::XML
-
-  property :title
-  property :track
-  collection :composers
-end
-```
-
-For XML we just include the `Representable::XML` module.
-
-```xml
-Song.new(title: "Fallout", composers: ["Steward Copeland", "Sting"]).
-     extend(SongRepresenter).to_xml #=>
-<song>
-    <title>Fallout</title>
-    <composers>Steward Copeland</composers>
-    <composers>Sting</composers>
-</song>
-```
 
 ## Passing Options
 
@@ -398,6 +420,87 @@ property :title, :getter => lambda { |*| @name }
 
 This hash will also be available in the `:if` block, documented [here](https://github.com/apotonick/representable/#conditions) and will be passed to nested objects.
 
+
+## Dynamic Options
+
+Most of `property`'s options are dynamic, meaning the can be either a static value, a lambda or a :symbol refering to an instance method to be called.
+
+All user options are passed to the lambdas, e.g. when you call
+
+```ruby
+song.to_hash(volume: 9)
+```
+
+the lambda invocation for `:as` would look like this.
+
+```ruby
+property :name, as: lambda do |args|
+  args #=> {:volume=>9}
+end
+```
+
+### Available Options
+
+Here's a list of all dynamic options and their argument signature.
+
+* `as: lambda { |args| }` ([see Aliasing](#aliasing))
+* `getter: lambda { |args| }` ([see docs](#passing-options))
+* `setter: lambda { |value, args| }` ([see docs](#passing-options))
+* `class: lambda { |fragment, [i], args| }` ([see Nesting](#nesting))
+* `extend: lambda { |object, args| }` ([see Nesting](#nesting))
+* `instance: lambda { |fragment, [i], args| }` ([see Object Creation](#polymorphic-object-creation))
+* `reader: lambda { |document, args| }` ([see Read And Write](#overriding-read-and-write))
+* `writer: lambda { |document, args| }` ([see Read And Write](#overriding-read-and-write))
+* `if: lambda { |args| }` ([see Conditions](#conditions))
+* `prepare: lambda { |object, args| }` ([see docs](#rendering-and-parsing-without-extend))
+* `representation_wrap` is a dynamic option, too: `self.representation_wrap = lambda do { |args| }` ([see Wrapping](#wrapping))
+
+
+### Option Arguments
+
+The `pass_options: true` option instructs representable to pass a special `Options` instance into lambdas or methods. This is handy if you need access to the other stakeholder objects involved in representing objects.
+
+```ruby
+property :title, pass_options: true, getter: lambda do |args|
+  args #=> <#Options>
+  args.binding # etc.
+end
+```
+
+The `Options` instance exposes the following readers: `#binding`, `#represented`, `#decorator` and  `#user_options` which is the hash you usually have as `args`.
+
+Option-specific arguments (e.g. `fragment`, [see here](#available-options)) are still prepended, making the `Options` object always the *last* argument.
+
+
+## XML Support
+
+While representable does a great job with JSON, it also features support for XML, YAML and pure ruby hashes.
+
+```ruby
+require 'representable/xml'
+
+module SongRepresenter
+  include Representable::XML
+
+  property :title
+  property :track
+  collection :composers
+end
+```
+
+For XML we just include the `Representable::XML` module.
+
+```xml
+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.
@@ -432,7 +535,9 @@ end
 
 ## Inheritance
 
-To reuse existing representers you can inherit from those modules.
+To reuse existing representers use inheritance.
+
+Inheritance works by `include`ing already defined representers.
 
 ```ruby
 module CoverSongRepresenter
@@ -443,13 +548,14 @@ module CoverSongRepresenter
 end
 ```
 
-Inheritance works by `include`ing already defined representers.
+This results in a representer with the following properties.
+
+
 
-```ruby
-Song.new(:title => "Truth Hits Everybody", :copyright => "The Police").
-  extend(CoverSongRepresenter).to_json
 
-#=> {"title":"Truth Hits Everybody","copyright":"The Police"}
+```ruby
+property :title     # inherited from SongRepresenter.
+property :copyright
 ```
 
 With decorators, you - surprisingly - use class inheritance.
@@ -460,7 +566,6 @@ class HitRepresenter < SongRepresenter
 ```
 
 
-
 ## Overriding Properties
 
 You might want to override a particular property in an inheriting representer. Successively calling `property(name)` will override the former definition for `name` just as you know it from overriding methods.
@@ -489,7 +594,7 @@ module SongRepresenter
 end
 ```
 
-You can now inherit but still override or add options.
+You can now inherit properties but still override or add options.
 
 ```ruby
 module CoverSongRepresenter
@@ -500,13 +605,12 @@ module CoverSongRepresenter
 end
 ```
 
-This will result in a property having the following options.
+Using the `:inherit`, this will result in a property having the following options.
 
 ```ruby
-  property :title,
-    as:     :known_as,    # inherited from SongRepresenter
-    getter: lambda { .. } # added in inheriting representer.
-end
+property :title,
+  as:     :known_as,    # inherited from SongRepresenter.
+  getter: lambda { .. } # added in inheriting representer.
 ```
 
 ## Inheritance With Inline Representers
@@ -546,6 +650,8 @@ property :label do
 end
 ```
 
+Naturally, `:inherit` can be used within the inline representer block.
+
 Note that the following also works.
 
 ```ruby
@@ -559,7 +665,7 @@ end
 
 This renames the property but still inherits all the inlined configuration.
 
-Basically, `:inherit` copies the configuration from the parent property, then merges it your options from the inheriting representer. It exposes the same behaviour as `super` in Ruby - when using `:inherit` the property must exist in the parent representer.
+Basically, `:inherit` copies the configuration from the parent property, then merges in your options from the inheriting representer. It exposes the same behaviour as `super` in Ruby - when using `:inherit` the property must exist in the parent representer.
 
 ## Polymorphic Extend
 
@@ -724,7 +830,7 @@ composers: [Steward Copeland, Sting]
 
 ### Mapping Tag Attributes
 
-You can also map properties to tag attributes in representable. This works only for the top-level node, thou (seen from the representer's perspective).
+You can also map properties to tag attributes in representable. This works only for the top-level node, though (seen from the representer's perspective).
 
 ```ruby
 module SongRepresenter
@@ -921,6 +1027,7 @@ end
 
 Coercing values only happens when rendering or parsing a document. Representable does not create accessors in your model as `virtus` does.
 
+
 ## Undocumented Features
 
 *(Please don't read this section!)*
@@ -933,6 +1040,7 @@ If you need a special binding for a property you're free to create it using the
 property :title, :binding => lambda { |*args| JSON::TitleBinding.new(*args) }
 ```
 
+
 ### Syncing Parsing
 
 You can use the parsed document fragment directly as a representable instance by returning `nil` in `:class`.
@@ -951,32 +1059,77 @@ Representable will not attempt to create a `Song` instance for you but use the p
 
 Note that this is now the [official option](#syncing-objects) `:parse_strategy`.
 
-### Rendering Without Extend
 
-The same goes the other way when rendering. Just provide an empty `:instance` block.
+### Rendering And Parsing Without Extend
+
+Sometimes you wanna skip the preparation step when rendering and parsing, for instance, when the object already exposes a `#to_hash`/`#from_hash` method.
 
 ```ruby
-property :song, :instance => lambda { |*| nil }
+class ParsingSong
+  def from_hash(hash, *args)
+    # do whatever
+
+    self
+  end
+
+  def to_hash(*args)
+    {}
+  end
+end
 ```
 
-This will treat the `song` property instance as a representable object.
+This would work with a representer as the following.
 
 ```ruby
-hit.to_json # this will call hit.song.to_json
+property :song, :class => ParsingSong, prepare: lambda { |object| object }
 ```
 
-Rendering `collection`s works the same. Parsing doesn't work out-of-the-box, currently, as we're still unsure how to map items to fragments.
+Instead of automatically extending/decorating the object, the `:prepare` lambda is run. It's up to you to prepare you object - or simply return it, as in the above example.
+
+
+### Skipping Rendering Or Parsing
+
+You can skip to call to `#to_hash`/`#from_hash` on the prepared object by using `:representable`.
+
+```ruby
+property :song, :representable => false
+```
+
+This will run the entire serialization/deserialization _without_ calling the actual representing method on the object.
+
+Extremely helpful if you wanna use representable as a data mapping tool with filtering, aliasing, etc., without the rendering and parsing part.
+
+
+### Returning Arbitrary Objects When Parsing
+
+When representable parses the `song` attribute, it calls `ParsingSong#from_hash`. This method could return any object, which will then be assigned as the `song` property.
+
+```ruby
+class ParsingSong
+  def from_hash(hash, *args)
+    [1,2,3,4]
+  end
+end
+```
+
+Album.extend(AlbumRepresenter).from_hash(..).song #=> [1,2,3,4]
+
+This also works with `:extend` where the specified module overwrites the parsing method (e.g. `#from_hash`).
+
 
 ### Decorator In Module
 
 Inline representers defined in a module can be implemented as a decorator, thus wrapping the represented object without pollution.
 
 ```ruby
-property :label, decorator: true do
-  ...
+property :song, use_decorator: true do
+  property :title
 end
 ```
 
+This is an implementation detail most people shouldn't worry about.
+
+
 ## Copyright
 
 Representable started as a heavily simplified fork of the ROXML gem. Big thanks to Ben Woosley for his inspiring work.