mystique 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0f60bb171d9f2634c6902175b28f63c5b79dcd2b
-  data.tar.gz: a6191d72cbc18501dd0b8358f0ad2ce6cc8f2649
+  metadata.gz: 8c89e0f208874318c9e36941c71ccb0bdda388bb
+  data.tar.gz: b0160e9d1679562db583098a437b1669642df789
 SHA512:
-  metadata.gz: d0bbe306e6c7e056a35ddd74e127cfd58babc4000511aacb16455acb3377d41ee337326ac5537ea51516f079289e451401e8f9626f632b66e0dca0b5f4956fc7
-  data.tar.gz: a04735375b41a8e81938ddf9f6a14b3ba8a4eaa417e9cae719108bc87c9f271d886bf4949a5545723e11569b120e00d88e5880b334f27b1f331942413eeb8dba
+  metadata.gz: fb0ac21270c00aeda63961b6c6fdc7afb9e13913f9f490d8d93deb10b42c3b70fc01c60c280b2324debd4fc3bb06d6d3ec5ae65415049dd1707eb6bfb2b9e948
+  data.tar.gz: aca76c6a29bfc17495d46cb7f0b47fe8c21abf2d00905e18fee8388930a1870c15771b650467a5efe5307f1f0c7feac42f30f0d1ea46277541383b00c9c8654b

data/README.md

@@ -2,9 +2,145 @@
 
 Mystique is a gem that implements the presenter pattern. It allows you to augment an object, by wrapping it and giving it access to the context in which you need to render it.
 
-## Usage
+## How to present
 
-TODO: Write usage instructions here
+Mystique ships with the `.present` method, which wraps the target object in a presenter and yield the presenter if a block is given, or returns it. If there default presenter is not available, the original object gets yielded/returned.
+
+```ruby
+Item = Struct.new(:name, :price)
+class ItemPresenter < Mystique::Presenter
+end
+
+item_presenter = Mystique.present(Item.new("Rubik's Cube", 30.5))
+
+item_presenter.class
+# => ItemPresenter
+
+item_presenter.name
+# => "Rubik's Cube"
+```
+
+### Default presenter
+
+The default presenter is inferred from the target object's class name. So, for the `Item` class, you'll get the `ItemPresenter` presenter.
+
+If `ItemPresenter` is not defined, you'll get back your original item.
+
+
+### Context
+
+The context is the object that, conveniently, provides the context in which the target object will be rendered.
+
+Currently, the context defaults to a null context, which accepts any message sent and does nothing.
+
+You can set the context in 3 ways:
+
+#### Using the `.context` method when defining your presenter:
+
+```ruby
+class UserPresenter < Mystique::Presenter
+  context MyHelpers
+
+  # ...
+end
+```
+
+This will set the `MyHelpers` module as the context for any instance of `UserPresenter`
+
+#### Passing it to the present method
+
+```ruby
+user_presenter = Mystique.present(some_user, context: MyHelpers)
+```
+
+Which will set `MyHelpers` as the context just for `user_presenter`
+
+#### Both
+
+You can pass the presenter using both methods.
+
+In that case, the one set on the class declaration will be the default one for that class,
+but if you pass a new context to a specific instance, it will use that one.
+
+## Formatting
+
+Mystique provides a `format` method that allows you to define defaults for some response types.
+
+In every case, `format` will accept a value or a block to return, which will yield the found value and the context.
+
+### Specific values
+
+This is a great way to return a default String when you get a nil back (but it's not limited to that).
+
+```ruby
+Item = Struct.new(:name, :price)
+class ItemPresenter < Mystique::Presenter
+  format nil, "N/A"
+end
+
+item_presenter.price
+# => "N/A"
+```
+
+### Classes
+
+You can pass a class name to the format method, and if the returned value is an instance of that class, it will return the specified value/block
+
+```ruby
+class ItemPresenter < Mystique::Presenter
+  context Helpers
+  format Float do |value, context|
+    context.number_to_currency(value)
+  end
+end
+
+item_presenter = Mystique.present(Item.new("Rubik's Cube", 5.3))
+
+item_presenter.price
+# => "$ 5.30"
+```
+
+### Regular Expressions
+
+You can also pass a regular expression to which the return value will be matched
+
+```ruby
+module Helpers
+  def self.link_to(text, url)
+    "<a href='#{url}'> #{text} </a>"
+  end
+end
+
+class UserPresenter < Mystique::Presenter
+  context Helpers
+
+  format /\w+@\w+\.\w+/ do |email, context|
+    context.link_to(email, "mailto://#{email}")
+  end
+end
+
+user_presenter = Mystique.present(User.new("Federico", "me@myself.com"))
+
+user_presenter.email
+# => "<a href='mailto://me@myself.com'> me@myself.com </a>"
+```
+
+### `format_multiple`
+
+You can also set multiple matchers by using the `.format_multiple` method:
+
+```ruby
+Mystique.present(Item.new("Wine", 50, 42.3)) do |presenter|
+  presenter.class
+  # => ItemPresenter
+
+  presenter.price
+  # => "$ 50.00"
+
+  presenter.list_price
+  # => "$ 42.30"
+end
+```
 
 ## Installation
 

data/lib/mystique.rb

@@ -1,12 +1,16 @@
 require "mystique/version"
+
 require "callable"
 require "string_plus"
 
+require "mystique/null_context"
+
+
 module Mystique
   class Presenter
     def initialize(object, context)
       @__object__ = object
-      @__context__ = context || self.class.context
+      @__context__ = context || self.class.context || NullContext
     end
 
     def self.present(object, context=nil)
@@ -25,9 +29,14 @@ module Mystique
       @__object__
     end
 
+    def inspect
+      "<#{self.class}(#{target.inspect}) context: #{context.inspect}>"
+    end
+    
     private
 
     def method_missing(method, *args, &block)
+      return target.send(method, *args, &block) if method.to_s.start_with?("to_")
       value = target.send(method, *args, &block)
       result = if __formats__.keys.include?(value)
                  __formats__[value]

data/lib/mystique/null_context.rb

@@ -0,0 +1,7 @@
+module Mystique
+  module NullContext
+    def method_missing(*)
+      self
+    end
+  end
+end

data/lib/mystique/version.rb

@@ -1,3 +1,3 @@
 module Mystique
-  VERSION = "0.4.0"
+  VERSION = "0.4.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mystique
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Federico Iachetti
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-03-09 00:00:00.000000000 Z
+date: 2015-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -96,6 +96,7 @@ files:
 - bin/console
 - bin/setup
 - lib/mystique.rb
+- lib/mystique/null_context.rb
 - lib/mystique/version.rb
 - mystique.gemspec
 homepage: https://github.com/iachettifederico/mystique