hyperresource 0.1.9.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 297e7456b1c2ea2b42d9ed4ca690f98a90c5e33a
-  data.tar.gz: 4e89207bc9ab1bfaf0148ff99e57517bf1c80414
+  metadata.gz: 8d9374b1ec64fdce21a54dfa34bd053c991f0541
+  data.tar.gz: 0442f93a99aaed8e1e023ad9aa8ff00ecc2978f5
 SHA512:
-  metadata.gz: 14720ef3ba836d285ae6b0b0ed2e9577c307538a12f833cfbed99f519f38a45e7c0e7c65ae2e55cf6f0725aa07d2be0e675db5c296de7c63babe8713c73b034d
-  data.tar.gz: dc6f658a981ac5b2f5e9596e677aac6f4b2ae45f712ce10fe39eecc69045f3e66beea8a90208034fee8de071cd9bbc513b0cb6d828658fba1f86acd92c5fa0c1
+  metadata.gz: c3e3388c09971d33a9c0062377ef356bcb35e2770c060d8d61ce0a8cf0a992b2f255726dbdaeffd94adee8ee91964eae2beff2e13551a3ac76a59d3a7e0add34
+  data.tar.gz: 2eeb5c948b3736691cbf273310f4c98d8413ea2fa2a8725675985d9749bd035f42793828b1300e23452ac92fbf85b9a4de67153fec07f08790066a3cb577f4e9

data/lib/hyper_resource.rb

@@ -1,58 +1,36 @@
-this_dir = File.dirname(__FILE__)
-Dir.glob(this_dir + '/hyper_resource/**/*.rb') {|f| require f}
+require 'hyper_resource/attributes'
+require 'hyper_resource/exceptions'
+require 'hyper_resource/link'
+require 'hyper_resource/links'
+require 'hyper_resource/objects'
+require 'hyper_resource/response'
+require 'hyper_resource/version'
 
-if RUBY_VERSION[0..2] == '1.8'
-  require 'rubygems'
-end
+require 'hyper_resource/adapter'
+require 'hyper_resource/adapter/hal_json'
 
-require 'pp'
+require 'hyper_resource/modules/http'
+require 'hyper_resource/modules/internal_attributes'
 
-class HyperResource
-  include HyperResource::Modules::Utils
-  include HyperResource::Modules::HTTP
+require 'rubygems' if RUBY_VERSION[0..2] == '1.8'
 
-private
+require 'pp'
 
-  def self._hr_class_attributes
-    [ :root,             ## e.g. 'https://example.com/api/v1'
-      :auth,             ## e.g. {:basic => ['username', 'password']}
-      :headers,          ## e.g. {'Accept' => 'application/vnd.example+json'}
-      :namespace,        ## e.g. 'ExampleAPI', or the class ExampleAPI itself
-      :adapter           ## subclass of HR::Adapter
-    ]
-  end
+## HyperResource is the main resource base class.  Normally it will be used
+## through subclassing, though it may also be used directly.
 
-  def self._hr_attributes
-    [ :root,
-      :href,
-      :auth,
-      :headers,
-      :namespace,
-      :adapter,
+class HyperResource
 
-      :request,
-      :response,
-      :response_object,
+  include HyperResource::Modules::HTTP
+  include HyperResource::Modules::InternalAttributes
+  include Enumerable
 
-      :attributes,
-      :links,
-      :objects,
+private
 
-      :loaded
-    ]
-  end
+  DEFAULT_HEADERS = { 'Accept' => 'application/json' }
 
 public
 
-  _hr_class_attributes.each                    {|attr| class_attribute    attr}
-  (_hr_attributes & _hr_class_attributes).each {|attr| fallback_attribute attr}
-  (_hr_attributes - _hr_class_attributes).each {|attr| attr_accessor      attr}
-
-  # :nodoc:
-  DEFAULT_HEADERS = {
-    'Accept' => 'application/json'
-  }
-
   ## Create a new HyperResource, given a hash of options.  These options
   ## include:
   ##
@@ -107,14 +85,15 @@ public
   end
 
 
-public
-
   ## Returns true if one or more of this object's attributes has been
   ## reassigned.
   def changed?(*args)
     attributes.changed?(*args)
   end
 
+
+  #### Filters
+
   ## +incoming_body_filter+ filters a hash of attribute keys and values
   ## on their way from a response body to a HyperResource.  Override this
   ## in a subclass of HyperResource to implement filters on incoming data.
@@ -138,13 +117,23 @@ public
   end
 
 
-  ## Returns the first object in the first collection of objects embedded
-  ## in this resource.  Equivalent to +self.objects.first+.
-  def first; self.objects.first end
+  #### Enumerable support
 
   ## Returns the *i*th object in the first collection of objects embedded
-  ## in this resource.  Equivalent to +self.objects[i]+.
-  def [](i); self.objects.ith(i) end
+  ## in this resource.  Returns nil on failure.
+  def [](i)
+    get unless loaded
+    self.objects.first[1][i] rescue nil
+  end
+
+  ## Iterates over the objects in the first collection of embedded objects
+  ## in this resource.
+  def each(&block)
+    get unless loaded
+    self.objects.first[1].each(&block) rescue nil
+  end
+
+  #### Magic
 
   ## method_missing will load this resource if not yet loaded, then 
   ## attempt to delegate to +attributes+, then +objects+, then +links+.
@@ -171,23 +160,34 @@ public
   end
 
 
-  def inspect # :nodoc:
+  def inspect # @private
     "#<#{self.class}:0x#{"%x" % self.object_id} @root=#{self.root.inspect} "+
     "@href=#{self.href.inspect} @loaded=#{self.loaded} "+
     "@namespace=#{self.namespace.inspect} ...>"
   end
 
-  ## +response_body+ is deprecated in favor of +response_object+.
-  def response_body; response_object end # :nodoc:
-
+  ## +response_body+, +response_object+, and +deserialized_response+
+  ##  are deprecated in favor of +body+.  (Sorry. Naming things is hard.)
+  def response_body # @private
+    _hr_deprecate('HyperResource#response_body is deprecated. '+
+                  'Please use HyperResource#body instead.')
+    body
+  end
+  def response_object # @private
+    _hr_deprecate('HyperResource#response_object is deprecated. '+
+                  'Please use HyperResource#body instead.')
+    body
+  end
+  def deserialized_response # @private
+    _hr_deprecate('HyperResource#deserialized_response is deprecated. '+
+                  'Please use HyperResource#body instead.')
+    body
+  end
 
-  #######################################################################
-  ####   Underscored functions are not meant to be used outside of   ####
-  ####   HyperResource machinery.  You have been warned.             ####
 
 
   ## Return a new HyperResource based on this object and a given href.
-  def _new_from_link(href) # :nodoc:
+  def _hr_new_from_link(href) # @private
     self.class.new(:root    => self.root,
                    :auth    => self.auth,
                    :headers => self.headers,
@@ -197,24 +197,23 @@ public
 
 
   ## Returns the class into which the given response should be cast.
-  ## If the object is not loaded yet, or if +opts[:namespace]+ is
+  ## If the object is not loaded yet, or if +namespace+ is
   ## not set, returns +self+.
   ##
-  ## Otherwise, +_get_response_class+ uses +_get_response_data_type+ to
+  ## Otherwise, +response_class+ uses +get_data_type_from_response+ to
   ## determine subclass name, glues it to the given namespace, and
   ## creates the class if it's not there yet. E.g., given a namespace of
   ## +FooAPI+ and a response content-type of
   ## "application/vnd.foocorp.fooapi.v1+json;type=User", this should
   ## return +FooAPI::User+ (even if +FooAPI::User+ hadn't existed yet).
-
-  def self._get_response_class(response, namespace) # :nodoc:
+  def self.response_class(response, namespace)
     if self.to_s == 'HyperResource'
       return self unless namespace
     end
 
     namespace ||= self.to_s
 
-    type_name = self._get_response_data_type(response)
+    type_name = self.get_data_type_from_response(response)
     return self unless type_name
 
     class_name = "#{namespace}::#{type_name}"
@@ -236,45 +235,57 @@ public
     eval(class_name)
   end
 
-  def _get_response_class # :nodoc:
+  def _hr_response_class # @private
     self.namespace ||= self.class.to_s unless self.class.to_s=='HyperResource'
-    self.class._get_response_class(self.response, self.namespace)
+    self.class.response_class(self.response, self.namespace)
   end
 
 
-  ## Inspects the given response, and returns a string describing this
-  ## resource's data type.
+  ## Inspects the given Faraday::Response, and returns a string describing
+  ## this resource's data type.
   ##
   ## By default, this method looks for a +type=...+ modifier in the
   ## response's +Content-type+ and returns that value, capitalized.
   ##
   ## Override this method in a subclass to alter HyperResource's behavior.
-
-  def self._get_response_data_type(response) # :nodoc:
+  def self.get_data_type_from_response(response)
     return nil unless response
     return nil unless content_type = response['content-type']
     return nil unless m=content_type.match(/;\s* type=([0-9A-Za-z:]+)/x)
     m[1][0,1].upcase + m[1][1..-1]
   end
 
-  def _get_response_data_type # :nodoc:
-    self.class._get_response_data_type(self.response)
+  ## Uses +HyperResource.get_response_data_type+ to determine the proper
+  ## data type for this object.  Override to change behavior (though you
+  ## probably just want to override the class method).
+  def get_data_type_from_response
+    self.class.get_data_type_from_response(self.response)
   end
 
 private
 
   ## Return this object, "cast" into its proper response class.
-  def to_response_class # :nodoc:
-    response_class = self._get_response_class
+  def to_response_class
+    response_class = self._hr_response_class
     return self if self.class == response_class
     response_class.new(self)
   end
 
+  ## Use the given resource's data to initialize this one.
   def init_from_resource(resource)
     (self.class._hr_attributes - [:attributes, :links, :objects]).each do |attr|
       self.send("#{attr}=".to_sym, resource.send(attr))
     end
-    self.adapter.apply(self.response_object, self)
+    self.adapter.apply(self.body, self)
   end
 
+
+  ## Show a deprecation message.
+  def self._hr_deprecate(message) # @private
+    STDERR.puts "#{message} (called from #{caller[2]})"
+  end
+
+  def _hr_deprecate(*args) # @private
+    self.class._hr_deprecate(*args)
+  end
 end

data/lib/hyper_resource/adapter/hal_json.rb

@@ -3,6 +3,11 @@ require 'json'
 
 class HyperResource
   class Adapter
+
+    ## HyperResource::Adapter::HAL_JSON provides support for the HAL+JSON
+    ## hypermedia format by implementing the interface defined in
+    ## HyperResource::Adapter.
+
     class HAL_JSON < Adapter
       class << self
 
@@ -42,24 +47,24 @@ class HyperResource
           resp['_embedded'].each do |name, collection|
             if collection.is_a? Hash
               r = rc.new(:root => rsrc.root, :namespace => rsrc.namespace)
-              r.response_object = collection
+              r.body = collection
               objs[name] = apply(collection, r)
             else
               objs[name] = collection.map do |obj|
                 r = rc.new(:root => rsrc.root, :namespace => rsrc.namespace)
-                r.response_object = obj
+                r.body = obj
                 apply(obj, r)
               end
             end
           end
 
-          objs.create_methods!
+          objs._hr_create_methods!
         end
 
 
         def apply_links(resp, rsrc)
           return unless resp['_links']
-          rsrc.links = rsrc._get_response_class::Links.new(rsrc)
+          rsrc.links = rsrc._hr_response_class::Links.new(rsrc)
           links = rsrc.links
 
           resp['_links'].each do |rel, link_spec|
@@ -72,16 +77,16 @@ class HyperResource
             end
           end
 
-          links.create_methods!
+          links._hr_create_methods!
         end
 
-        def new_link_from_spec(resource, link_spec) # :nodoc:
+        def new_link_from_spec(resource, link_spec)
           resource.class::Link.new(resource, link_spec)
         end
 
 
         def apply_attributes(resp, rsrc)
-          rsrc.attributes = rsrc._get_response_class::Attributes.new(rsrc)
+          rsrc.attributes = rsrc._hr_response_class::Attributes.new(rsrc)
 
           given_attrs = resp.reject{|k,v| %w(_links _embedded).include?(k)}
           filtered_attrs = rsrc.incoming_body_filter(given_attrs)
@@ -90,7 +95,7 @@ class HyperResource
             rsrc.attributes[attr] = filtered_attrs[attr]
           end
 
-          rsrc.attributes.create_methods!
+          rsrc.attributes._hr_create_methods!
         end
 
       end

data/lib/hyper_resource/attributes.rb

@@ -1,16 +1,16 @@
 class HyperResource
   class Attributes < Hash
 
-    attr_accessor :_resource # :nodoc:
+    attr_accessor :_resource # @private
 
-    def initialize(resource=nil) # :nodoc:
+    def initialize(resource=nil) # @private
       self._resource = resource || HyperResource.new
     end
 
     ## Creates accessor methods in self.class and self._resource.class.
     ## Protects against method creation into HyperResource::Attributes and
     ## HyperResource classes.  Just subclasses, please!
-    def create_methods!(opts={})
+    def _hr_create_methods!(opts={}) # @private
       return if self.class.to_s == 'HyperResource::Attributes' ||
                 self._resource.class.to_s == 'HyperResource'
 
@@ -58,25 +58,25 @@ class HyperResource
       @_hr_changed.select{|k,v| v}.keys.inject({}) {|h,k| h[k]=self[k]; h}
     end
 
-    def []=(attr, value) # :nodoc:
+    def []=(attr, value) # @private
       _hr_mark_changed(attr)
       super(attr.to_s, value)
     end
 
-    def [](key) # :nodoc:
+    def [](key) # @private
       return super(key.to_s) if self.has_key?(key.to_s)
       return super(key.to_sym) if self.has_key?(key.to_sym)
       nil
     end
 
-    def method_missing(method, *args) # :nodoc:
+    def method_missing(method, *args) # @private
       return self[method] if self[method]
       raise NoMethodError, "undefined method `#{method}' for #{self.inspect}"
     end
 
   private
 
-    def _hr_mark_changed(attr, is_changed=true) # :nodoc:
+    def _hr_mark_changed(attr, is_changed=true) # @private
       attr = attr.to_sym
       @_hr_changed ||= Hash.new(false)
       @_hr_changed[attr] = is_changed

data/lib/hyper_resource/exceptions.rb

@@ -1,28 +1,40 @@
 class HyperResource
-  class Exception < ::Exception
-    attr_accessor :response         # Response body which led to this
-    attr_accessor :response_object  # Response object which led to this
-    attr_accessor :cause            # Internal exception which led to this
+  class Exception < ::StandardError
+    ## The internal exception which led to this one, if any.
+    attr_accessor :cause
 
-    def initialize(message, opts={})
-      self.response = opts[:response]
-      self.response_object = opts[:response_object]
-      self.cause = opts[:cause]
+    def initialize(message, attrs={}) # @private
+      self.cause = attrs[:cause]
+      super(message)
+    end
+  end
+
+  class ResponseError < Exception
+    ## The +Faraday::Response+ object which led to this exception.
+    attr_accessor :response
+
+    ## The deserialized response body which led to this exception.
+    ## May be blank, e.g. in case of deserialization errors.
+    attr_accessor :body
+
+    def initialize(message, attrs={}) # @private
+      self.response = attrs[:response]
+      self.body = attrs[:body]
 
       ## Try to help out with the message
-      if self.response_object
-        if error = self.response_object['error']
+      if self.body
+        if error = self.body['error']
           message = "#{message} (#{error})"
         end
       elsif self.response
         message = "#{message} (\"#{self.response.inspect}\")"
       end
 
-      super(message)
+      super(message, attrs)
     end
   end
 
-  class ResponseError < Exception; end
-  class ClientError   < Exception; end
-  class ServerError   < Exception; end
+  class ClientError < ResponseError; end
+  class ServerError < ResponseError; end
 end
+

data/lib/hyper_resource/link.rb

@@ -7,6 +7,7 @@ class HyperResource::Link
                 :params,
                 :parent_resource
 
+  ## Returns true if this link is templated.
   def templated?; templated end
 
   def initialize(resource=nil, link_spec={})
@@ -40,7 +41,7 @@ class HyperResource::Link
 
   ## Returns a HyperResource representing this link
   def resource
-    parent_resource._new_from_link(self.href)
+    parent_resource._hr_new_from_link(self.href)
   end
 
   ## Returns a HyperResource representing this link, and fetches it.

data/lib/hyper_resource/links.rb

@@ -9,7 +9,7 @@ class HyperResource
     ## Creates accessor methods in self.class and self._resource.class.
     ## Protects against method creation into HyperResource::Links and
     ## HyperResource classes.  Just subclasses, please!
-    def create_methods!(opts={})
+    def _hr_create_methods!(opts={}) # @private
       return if self.class.to_s == 'HyperResource::Links' ||
                 self._resource.class.to_s == 'HyperResource'
 
@@ -33,17 +33,17 @@ class HyperResource
       end
     end
 
-    def []=(attr, value) # :nodoc:
+    def []=(attr, value) # @private
       super(attr.to_s, value)
     end
 
-    def [](key) # :nodoc:
+    def [](key) # @private
       return super(key.to_s) if self.has_key?(key.to_s)
       return super(key.to_sym) if self.has_key?(key.to_sym)
       nil
     end
 
-    def method_missing(method, *args) # :nodoc:
+    def method_missing(method, *args) # @private
       unless self[method]
         raise NoMethodError, "undefined method `#{method}' for #{self.inspect}"
       end

data/lib/hyper_resource/modules/http.rb

@@ -3,93 +3,121 @@ require 'uri'
 require 'json'
 
 class HyperResource
-  module Modules; module HTTP
-
-    ## Loads and returns the resource pointed to by +href+.  The returned
-    ## resource will be blessed into its "proper" class, if
-    ## +self.class.namespace != nil+.
-    def get
-      self.response = faraday_connection.get(self.href || '')
-      finish_up
-    end
+  module Modules
+    module HTTP
 
-    def create(*args); post(*args) end
-    def post(params=nil)
-      params ||= self.attributes
-      self.response = faraday_connection.post do |req|
-        req.body = adapter.serialize(params)
+      ## Loads and returns the resource pointed to by +href+.  The returned
+      ## resource will be blessed into its "proper" class, if
+      ## +self.class.namespace != nil+.
+      def get
+        self.response = faraday_connection.get(self.href || '')
+        finish_up
       end
-      finish_up
-    end
 
-    def update(*args); put(*args) end
-    def put(params=nil)
-      params ||= self.attributes.changed_attributes
-      self.response = faraday_connection.put do |req|
-        req.body = adapter.serialize(params)
+      ## By default, calls +post+ with the given arguments. Override to
+      ## change this behavior.
+      def create(*args)
+        post(*args)
       end
-      finish_up
-    end
 
-    def delete
-      self.response = faraday_connection.delete
-      finish_up
-    end
+      ## POSTs the given attributes to this resource's href, and returns
+      ## the response resource.
+      def post(attrs)
+        self.response = faraday_connection.post do |req|
+          req.body = adapter.serialize(attrs)
+        end
+        finish_up
+      end
 
-    ## Returns a raw Faraday connection to this resource's URL, with proper
-    ## headers (including auth).
-    def faraday_connection(url=nil)
-      url ||= URI.join(self.root, self.href)
-      key = "faraday_connection_#{url}"
-      return Thread.current[key] if Thread.current[key]
-
-      fc = Faraday.new(:url => url)
-      fc.headers.merge!('User-Agent' => "HyperResource #{HyperResource::VERSION}")
-      fc.headers.merge!(self.headers || {})
-      if ba=self.auth[:basic]
-        fc.basic_auth(*ba)
+      ## By default, calls +put+ with the given arguments.  Override to
+      ## change this behavior.
+      def update(*args)
+        put(*args)
+      end
+
+      ## PUTs this resource's attributes to this resource's href, and returns
+      ## the response resource.  If attributes are given, +put+ uses those
+      ## instead.
+      def put(attrs=nil)
+        attrs ||= self.attributes
+        self.response = faraday_connection.put do |req|
+          req.body = adapter.serialize(attrs)
+        end
+        finish_up
+      end
+
+      ## PATCHes this resource's changed attributes to this resource's href,
+      ## and returns the response resource.  If attributes are given, +patch+
+      ## uses those instead.
+      def patch(attrs=nil)
+        attrs ||= self.attributes.changed_attributes
+        self.response = faraday_connection.patch do |req|
+          req.body = adapter.serialize(attrs)
+        end
+        finish_up
       end
-      Thread.current[key] = fc
-    end
 
-  private
-
-    def finish_up
-      begin
-        self.response_object = self.adapter.deserialize(self.response.body)
-      rescue StandardError => e
-        raise HyperResource::ResponseError.new(
-          "Error when deserializing response body",
-          :response => self.response,
-          :cause => e
-        )
+      ## DELETEs this resource's href, and returns the response resource.
+      def delete
+        self.response = faraday_connection.delete
+        finish_up
       end
 
-      self.adapter.apply(self.response_object, self)
-      self.loaded = true
-
-      status = self.response.status
-      if status / 100 == 2
-        return to_response_class
-      elsif status / 100 == 3
-        ## TODO redirect logic?
-      elsif status / 100 == 4
-        raise HyperResource::ClientError.new(status.to_s,
-                                             :response => self.response,
-                                             :response_object => self.response_object)
-      elsif status / 100 == 5
-        raise HyperResource::ServerError.new(status.to_s,
-                                             :response => self.response,
-                                             :response_object => self.response_object)
-
-      else ## 1xx? really?
-        raise HyperResource::ResponseError.new("Got status #{status}, wtf?",
+      ## Returns a raw Faraday connection to this resource's URL, with proper
+      ## headers (including auth).  Threadsafe.
+      def faraday_connection(url=nil)
+        url ||= URI.join(self.root, self.href)
+        key = "faraday_connection_#{url}"
+        return Thread.current[key] if Thread.current[key]
+
+        fc = Faraday.new(:url => url)
+        fc.headers.merge!('User-Agent' => "HyperResource #{HyperResource::VERSION}")
+        fc.headers.merge!(self.headers || {})
+        if ba=self.auth[:basic]
+          fc.basic_auth(*ba)
+        end
+        Thread.current[key] = fc
+      end
+
+    private
+
+      def finish_up
+        begin
+          self.body = self.adapter.deserialize(self.response.body)
+        rescue StandardError => e
+          raise HyperResource::ResponseError.new(
+            "Error when deserializing response body",
+            :response => self.response,
+            :cause => e
+          )
+        end
+
+        self.adapter.apply(self.body, self)
+        self.loaded = true
+
+        status = self.response.status
+        if status / 100 == 2
+          return to_response_class
+        elsif status / 100 == 3
+          ## TODO redirect logic?
+        elsif status / 100 == 4
+          raise HyperResource::ClientError.new(status.to_s,
+                                               :response => self.response,
+                                               :body => self.body)
+        elsif status / 100 == 5
+          raise HyperResource::ServerError.new(status.to_s,
                                                :response => self.response,
-                                               :response_object => self.response_object)
+                                               :body => self.body)
+
+        else ## 1xx? really?
+          raise HyperResource::ResponseError.new("Got status #{status}, wtf?",
+                                                 :response => self.response,
+                                                 :body => self.body)
 
+        end
       end
-    end
 
-  end end
+    end
+  end
 end
 

data/lib/hyper_resource/modules/internal_attributes.rb

@@ -0,0 +1,88 @@
+module HyperResource::Modules
+  module InternalAttributes
+
+    def self.included(base)
+      base.extend(ClassMethods)
+
+      base._hr_class_attributes.each do |attr|
+        base._hr_class_attribute attr
+      end
+
+      (base._hr_attributes - base._hr_class_attributes).each do |attr|
+         base.send(:attr_accessor, attr)
+      end
+
+      ## Fallback attributes fall back from instance to class.
+      (base._hr_attributes & base._hr_class_attributes).each do |attr|
+         base._hr_fallback_attribute attr
+      end
+    end
+
+    module ClassMethods
+
+      def _hr_class_attributes # @private
+        [ :root,             ## e.g. 'https://example.com/api/v1'
+          :auth,             ## e.g. {:basic => ['username', 'password']}
+          :headers,          ## e.g. {'Accept' => 'application/vnd.example+json'}
+          :namespace,        ## e.g. 'ExampleAPI', or the class ExampleAPI itself
+          :adapter           ## subclass of HR::Adapter
+        ]
+      end
+
+      def _hr_attributes # @private
+        [ :root,
+          :href,
+          :auth,
+          :headers,
+          :namespace,
+          :adapter,
+
+          :request,
+          :response,
+          :body,
+
+          :attributes,
+          :links,
+          :objects,
+
+          :loaded
+        ]
+      end
+
+      ## Inheritable class attribute, kinda like in Rails.
+      def _hr_class_attribute(*names)
+        names.map(&:to_sym).each do |name|
+          instance_eval <<-EOT
+            def #{name}=(val)
+              @#{name} = val
+            end
+            def #{name}
+              return @#{name} if defined?(@#{name})
+              return superclass.#{name} if superclass.respond_to?(:#{name})
+              nil
+            end
+          EOT
+        end
+      end
+
+      ## Instance attributes which fall back to class attributes.
+      def _hr_fallback_attribute(*names)
+        names.map(&:to_sym).each do |name|
+          class_eval <<-EOT
+            def #{name}=(val)
+              @#{name} = val
+            end
+            def #{name}
+              return @#{name} if defined?(@#{name})
+              return self.class.#{name} if self.class.respond_to?(:#{name})
+              nil
+            end
+          EOT
+        end
+      end
+
+    end # ClassMethods
+
+  end
+end
+

data/lib/hyper_resource/objects.rb

@@ -9,7 +9,7 @@ class HyperResource
     ## Creates accessor methods in self.class and self._resource.class.
     ## Protects against method creation into HyperResource::Objects and
     ## HyperResource classes.  Just subclasses, please!
-    def create_methods!(opts={})
+    def _hr_create_methods!(opts={}) # @private
       return if self.class.to_s == 'HyperResource::Objects' ||
                 self._resource.class.to_s == 'HyperResource'
 
@@ -29,28 +29,25 @@ class HyperResource
       end
     end
 
-    ## Returns the first item in the first collection in +self+.
-    alias_method :first_orig, :first
-    def first
-      self.first_orig[1][0]
-    end
-
-    ## Returns the ith item in the first collection in +self+.
-    def ith(i)
-      self.first_orig[1][i]
-    end
-
-    def []=(attr, value) # :nodoc:
+    def []=(attr, value) # @private
       super(attr.to_s, value)
     end
 
-    def [](key) # :nodoc:
-      return super(key.to_s) if self.has_key?(key.to_s)
-      return super(key.to_sym) if self.has_key?(key.to_sym)
+    ## When +key+ is a string, returns the array of objects under that name.
+    ## When +key+ is a number, returns +ith(key)+. Returns nil on lookup
+    ## failure.
+    def [](key)
+      case key
+      when String, Symbol
+        return super(key.to_s) if self.has_key?(key.to_s)
+        return super(key.to_sym) if self.has_key?(key.to_sym)
+      when Fixnum
+        return ith(key)
+      end
       nil
     end
 
-    def method_missing(method, *args) # :nodoc:
+    def method_missing(method, *args) # @private
       return self[method] if self[method]
       raise NoMethodError, "undefined method `#{method}' for #{self.inspect}"
     end

data/lib/hyper_resource/version.rb

@@ -1,4 +1,4 @@
 class HyperResource
-  VERSION = '0.1.9.5'
-  VERSION_DATE = '2013-10-11'
+  VERSION = '0.2.0'
+  VERSION_DATE = '2013-10-31'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hyperresource
 version: !ruby/object:Gem::Version
-  version: 0.1.9.5
+  version: 0.2.0
 platform: ruby
 authors:
 - Pete Gamache
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-11 00:00:00.000000000 Z
+date: 2013-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: uri_template
@@ -108,6 +108,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: 1.4.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.5
 description: |2
       HyperResource is a hypermedia client library for Ruby.  Its goals are to
       interface directly with well-behaved hypermedia APIs, to allow the data
@@ -125,7 +139,7 @@ files:
 - lib/hyper_resource/link.rb
 - lib/hyper_resource/links.rb
 - lib/hyper_resource/modules/http.rb
-- lib/hyper_resource/modules/utils.rb
+- lib/hyper_resource/modules/internal_attributes.rb
 - lib/hyper_resource/objects.rb
 - lib/hyper_resource/response.rb
 - lib/hyper_resource/version.rb

data/lib/hyper_resource/modules/utils.rb

@@ -1,45 +0,0 @@
-module HyperResource::Modules
-  module Utils
-
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
-
-    module ClassMethods
-
-      ## Inheritable class attribute, kinda like in Rails.
-      def class_attribute(*names)
-        names.map(&:to_sym).each do |name|
-          instance_eval <<-EOT
-            def #{name}=(val)
-              @#{name} = val
-            end
-            def #{name}
-              return @#{name} if defined?(@#{name})
-              return superclass.#{name} if superclass.respond_to?(:#{name})
-              nil
-            end
-          EOT
-        end
-      end
-
-      ## Instance attributes which fall back to class attributes.
-      def fallback_attribute(*names)
-        names.map(&:to_sym).each do |name|
-          class_eval <<-EOT
-            def #{name}=(val)
-              @#{name} = val
-            end
-            def #{name}
-              return @#{name} if defined?(@#{name})
-              return self.class.#{name} if self.class.respond_to?(:#{name})
-              nil
-            end
-          EOT
-        end
-      end
-
-    end # module ClassMethods
-
-  end
-end