resty 0.2.2 → 0.3.0

data/README.md

@@ -0,0 +1,86 @@
+Resty
+=====
+
+What is Resty about?
+--------------------
+
+Resty is designed as a client for a particular type of discoverable REST API; one that returns JSON, and where that JSON
+has particular keys which enable navigation of the data graph.
+
+An example of a Resty response
+-------------------------------
+
+A GET made to:
+
+    http://fishy.fish/fish/123
+
+Might return the following JSON:
+
+    {
+      ':href': 'http://fishy.fish/fish/123',
+      'tag_number': '3987349834',
+      'name': 'Bob the Fish'
+      'species' => {
+        ':href' => 'http://species.fish/species/555'
+      },
+      'habitat' => {
+        ':href' => 'http://fishy.fish/oceans/atlantic',
+        'name' => 'Atlantic Ocean'
+        'size' => 'quite large'
+      }
+    }
+
+  - The ':href' indicates the URL this resource is available at.  In this case the URL is the one we requested, which is the
+  normal case.
+
+  - The 'species' key is a link to another resource.  If a GET is made to that URL, more information about that species will
+  be available.  No other information about the species is available without doing that extra request.  It's also on a different
+  domain, which doesn't matter to Resty at all.
+
+  - The 'habitat' key is an example of a link containing the information you'll find at the link; this means that it's not
+  necessary to do the extra request.  Generally this is done if it's always known that the related resources will be required.
+
+Accessing the simple example with Resty
+---------------------------------------
+
+Given the above resource, you could execute the following code in IRB:
+
+    ruby-1.9.2-p180 :001 > require 'resty'
+     => true 
+    ruby-1.9.2-p180 :002 > fish = Resty.href('http://fishy.fish/fish/123')
+     => #<Resty:0xa5ba70c ...> 
+
+At this stage, no requests will be made.  Once you start look at the properties of "fish", a request will be made to
+GET the resource.
+
+    ruby-1.9.2-p180 :003 > fish.name
+     => "Bob the Fish"
+    ruby-1.9.2-p180 :004 > fish.habitat
+     => #<Resty:0xa590a24 ...> 
+    ruby-1.9.2-p180 :005 > fish.habitat.name
+     => "Atlantic Ocean"
+
+Navigating the resource graph
+-----------------------------
+
+Looking at "habitat" didn't require extra requests (because the data for "habitat" was already populated in the first request),
+but looking at "species" will require us to fetch that resource.  Let's assume that the species GET returns the following JSON:
+
+    {
+      ':href' => 'http://species.fish/species/555',
+      'commonName' => 'Atlantic Salmon',
+      'scientificName' => 'Salmo salar'
+      'kingdom' => {
+        ':href' => 'http://species.fish/kingdom/223'
+      }
+    }
+
+Then the following will happen; notice that "common_name" is translated to "commonName".
+
+    ruby-1.9.2-p180 :006 > fish.species.common_name
+     => "Atlantic Salmon"
+
+Now assume that the kingdom GET returns something sensible; we can do the following, chaining our method calls:
+
+    ruby-1.9.2-p180 :007 > fish.species.kingdom.scientific_name
+     => "Animalia"

data/lib/resty.rb

@@ -2,29 +2,37 @@ require 'rest-client'
 require 'json'
 require 'base64'
 
+# @author Simon Russell
 class Resty
   include Enumerable
   
+  # @note Generally, use Resty::from instead of Resty::new.
   def initialize(attributes)
     @attributes = attributes
   end
 
+  # @return [String, nil] The URL of the resource, or nil if none present.
   def _href
     @attributes.href
   end
 
+  # The data from the resource; will cause the resource to be loaded if it hasn't already occurred.
+  # @return [Hash] The data from the resource
   def _populated_data
     @attributes.populated_data
   end
 
+  # Make respond_to? return true to the corresponding magic methods added using {#method_missing}.
   def respond_to_missing?(name, include_private)
     @attributes.key?(name.to_s)
   end
   
+  # @return [String, nil] The URL of the resource, encoded for safe insertion into a URL.  Used for Rails routing.
   def to_param
     Resty.encode_param(_href)
   end
   
+  # Iterate through each item in the array; doesn't iterate over keys in the hash.
   def each
     @attributes.items.each do |x|
       yield x
@@ -35,6 +43,31 @@ class Resty
     @attributes.items[index]
   end
 
+  # Resty exposes the values and actions from the resource as methods on the object.
+  #
+  # @example Reading an attribute value
+  #   r = Resty.href('http://fish.fish/123')  # { ':href': 'http://fish.fish/123', 'name': 'Bob' }
+  #   r.name                                  # => "Bob"
+  #
+  # @example Checking a boolean value
+  #   r = Resty.href('http://fish.fish/123')  # { ':href': 'http://fish.fish/123', 'fun': true }
+  #   r.fun?                                  # => true
+  #
+  # @example Calling an action on the resource
+  #   r = Resty.href('http://fish.fish/123')  # { 
+  #                                           #   ':href': 'http://fish.fish/123',
+  #                                           #   ':actions': {
+  #                                           #     'cook': { 
+  #                                           #       ':href': 'http://fish.fish/123/cook'
+  #                                           #       ':method': 'POST'
+  #                                           #     } 
+  #                                           #   }
+  #                                           # }
+  #   r.cook!
+  #
+  # @example Calling an action on the resource with params
+  #   r = Resty.href('http://fish.fish/123')
+  #   r.cook!(style: 'lightly', flavoursomeness: 12)  # this will cause those parameters to be posted with the action
   def method_missing(name, *args)
     if name =~ /^(.+)!$/
       if @attributes.actions.exist?($1)
@@ -55,10 +88,14 @@ class Resty
     super.gsub('>', _href ? " #{_href}>" : " no-href>")
   end
 
+  # @return [Resty] A new Resty constructed from the given hash.
+  # @example
+  #   r = Resty.from('name' => 'Bob')
   def self.from(data)
     new(Resty::Attributes.new(data))
   end
 
+  # @return The input object, or a Resty wrapping if it's a Hash or Array.
   def self.wrap(object)
     case object
     when Hash
@@ -70,18 +107,24 @@ class Resty
     end
   end
 
+  # @return [Resty] A new Resty pointing at the given URL.
+  # @example
+  #   r = Resty.href('http://fish.fish/')
   def self.href(href)
     from(':href' => href)
   end
 
+  # @return [String] The input encoded for safe use in a URL.
   def self.encode_param(s)
     s && Base64.urlsafe_encode64(s.to_s)
   end
   
+  # @return [String] The input (previously encoded using Resty::encode_param) decoded into a string.
   def self.decode_param(s)
     s && Base64.urlsafe_decode64(s.to_s)
   end
   
+  # @return [Resty] A new Resty created from the URL encoded in the input.
   def self.from_param(s)
     href(decode_param(s))
   end

data/lib/resty/attributes.rb

@@ -4,34 +4,34 @@ class Resty::Attributes
 
   def initialize(data)
     @href = data[':href']
-    @populated = if @href
-                   !data[':partial'] && data.length > 1
-                 else
-                   true
-                 end
+    @fully_populated = if @href
+                         !data[':partial'] && data.length > 1
+                       else
+                         true
+                       end
 
     @data = data
     @wrapped = {}
   end
 
   def key?(name)
-    populate! unless populated?
-    @data.key?(translate_key(name))
-  end
-  
-  def translate_key(name)
-    populate! unless populated?
-    if @data.key?(name)
-      name
-    elsif @data.key?(camelized_name = camelize_key(name))
-      camelized_name
+    until_populated do
+      key_variants(name) do |key|
+        return true
+      end
     end
-  end
 
+    false
+  end
+ 
   def [](name)
-    populate! unless populated?
-    name = translate_key(name)
-    @wrapped[name] ||= Resty.wrap(@data[name])
+    until_populated do
+      key_variants(name) do |key|
+        return wrap_data(key)
+      end
+    end
+
+    nil
   end
 
   def items
@@ -39,13 +39,13 @@ class Resty::Attributes
     @wrapped[':items'] ||= (@data[':items'] || []).map { |item| Resty.wrap(item) }
   end
     
-  def populated?
-    @populated
+  def populated?(key = nil)
+    @fully_populated
   end
 
   def populate!
     new_data = Resty::Transport.request_json(@href)
-    
+
     @data = case new_data
             when Array
               { ':href' => @href, ':items' => new_data }
@@ -53,7 +53,8 @@ class Resty::Attributes
               new_data
             end
             
-    @populated = true
+    @fully_populated = true
+    @wrapped = {}
   end
 
   def populated_data
@@ -72,8 +73,28 @@ class Resty::Attributes
   
   private
   
+  def wrap_data(key)
+    @wrapped[key] ||= Resty.wrap(@data[key])
+  end
+
   def camelize_key(key)
     key.gsub(/_([a-z])/) { $1.upcase }
   end
+
+  def key_variants(name)
+    yield name if @data.key?(name)
+
+    camelized_name = camelize_key(name)
+    yield camelized_name if camelized_name != name && @data.key?(camelized_name)
+  end
+
+  def until_populated
+    yield
+    
+    unless populated?
+      populate!
+      yield
+    end
+  end
   
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: resty
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -14,7 +14,7 @@ default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
-  requirement: &23422920 !ruby/object:Gem::Requirement
+  requirement: &79995340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,10 +22,10 @@ dependencies:
         version: 1.6.3
   type: :runtime
   prerelease: false
-  version_requirements: *23422920
+  version_requirements: *79995340
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &23422440 !ruby/object:Gem::Requirement
+  requirement: &79995100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -33,20 +33,23 @@ dependencies:
         version: 1.5.1
   type: :runtime
   prerelease: false
-  version_requirements: *23422440
-description: 
-email: 
+  version_requirements: *79995100
+description: ! "                    Resty is designed as a client for a particular
+  type of discoverable REST API; one that returns JSON, and \n                    where
+  that JSON has particular keys which enable navigation of the data graph.\n"
+email: spam+resty@bellyphant.com
 executables:
 - resty
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/resty/attributes.rb
-- lib/resty/actions.rb
 - lib/resty/transport.rb
+- lib/resty/actions.rb
 - lib/resty.rb
 - bin/resty
 - LICENSE
+- README.md
 has_rdoc: true
 homepage: http://github.com/simonrussell/resty
 licenses: []