hyperresource 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2fd8d70a1aa3c15bde69a7a26ca532232c1795cd
+  data.tar.gz: 87cf162990ed41accbb7fdf7b3bcc2abded565f7
+SHA512:
+  metadata.gz: 3b6b9a4e0a3e19f78af2d68ac3b9fe208b1db41b0dc413f393d9a7b20a66ea853f95e2836f9524406573251d42cb5cbaab642b6489c7d7f5a1ee216ffadf426a
+  data.tar.gz: 62fc3bf454b4b54427c9d481c4556039119ba48ddcddbda4aee3c14f68f1b2d3288a7ccebbf2ef38b1b3fbe2914ef4b83f06c93a6bc70c082a4875f1985d396d

data/lib/hyper_resource.rb

@@ -0,0 +1,154 @@
+require 'hyper_resource/version'
+require 'hyper_resource/attributes'
+require 'hyper_resource/links'
+require 'hyper_resource/link'
+require 'hyper_resource/objects'
+require 'hyper_resource/response'
+
+require 'hyper_resource/modules/utils'
+require 'hyper_resource/modules/http'
+require 'hyper_resource/modules/bless'
+
+require 'pp'
+
+class HyperResource
+  include HyperResource::Modules::Utils
+  include HyperResource::Modules::HTTP
+  include HyperResource::Modules::Bless
+
+private
+
+  def self._hr_class_attributes
+    %w( root auth headers namespace ).map(&:to_sym)
+  end
+
+  def self._hr_attributes
+    %w( root href auth headers namespace
+        request response response_body
+        attributes links objects loaded).map(&:to_sym)
+  end
+
+public
+
+  _hr_class_attributes.each {|attr| class_attribute attr}
+  _hr_attributes.each       {|attr| attr_accessor   attr}
+
+  # :nodoc:
+  DEFAULT_HEADERS = {
+    'Accept' => 'application/json'
+  }
+
+  ## Create a new HyperResource, given a hash of options.  These options
+  ## include:
+  ##
+  ## [root]  The root URL of the resource.
+  ##
+  ## [auth]  Authentication information.  Currently only +{basic:
+  ##         ['key', 'secret']}+ is supported.
+  ##
+  ## [namespace] Class or class name, into which resources should be
+  ##             instantiated.
+  ##
+  ## [headers] Headers to send along with requests for this resource (as
+  ##           well as its eventual child resources, if any).
+  def initialize(opts={})
+    if opts.is_a?(HyperResource)
+      self.class._hr_attributes.each {|attr| self.send("#{attr}=".to_sym, opts.send(attr))}
+      return
+    end
+
+    self.root       = opts[:root] || self.class.root
+    self.href       = opts[:href] || ''
+    self.auth       = (self.class.auth || {}).merge(opts[:auth] || {})
+    self.namespace  = opts[:namespace] || self.class.namespace
+    self.headers    = DEFAULT_HEADERS.merge(self.class.headers || {}).
+                                      merge(opts[:headers]     || {})
+
+    self.attributes = Attributes.new(self)
+    self.links      = Links.new(self)
+    self.objects    = Objects.new(self)
+    self.loaded     = false
+  end
+
+  ## Returns a new HyperResource based on the given HyperResource object.
+  def new_from_resource(rsrc); self.class.new_from_resource(rsrc) end
+  def self.new_from_resource(rsrc)
+    new_rsrc = self.new 
+    _hr_attributes.each do |attr|
+      new_rsrc.send("#{attr}=".to_sym, rsrc.send(attr))
+    end
+    new_rsrc
+  end
+
+  ## Returns a new HyperResource based on the given HAL document.
+  def new_from_hal(obj)
+    rsrc = self.class.new(:root    => self.root,
+                          :auth    => self.auth,
+                          :headers => self.headers,
+                          :namespace => self.namespace,
+                          :href    => obj['_links']['self']['href'])
+    rsrc.response_body = Response[obj]
+    rsrc.init_from_response_body!
+    rsrc
+  end
+
+  ## Returns a new HyperResource based on the given link href.
+  def new_from_link(href)
+    rsrc = self.class.new(:root    => self.root,
+                          :auth    => self.auth,
+                          :headers => self.headers,
+                          :namespace => self.namespace,
+                          :href    => href)
+  end
+
+  ## Populates +attributes+, +links+, and +objects+ from the contents of
+  ## +response+. Sets +loaded = true+.
+  def init_from_response_body!
+    return unless self.response_body
+    self.objects.   init_from_hal(self.response_body);
+    self.links.     init_from_hal(self.response_body);
+    self.attributes.init_from_hal(self.response_body);
+    self.loaded = true
+    self
+  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
+
+  ## Returns the *i*th object in the first collection of objects embedded
+  ## in this resource.  Equivalent to +self.objects[i]+.
+  def [](i); self.objects[i]    end
+
+
+  ## method_missing will load this resource if not yet loaded, then 
+  ## attempt to delegate to +attributes+, then +objects+,
+  ## then +links+.  When it finds a match, it will define a method class-wide
+  ## if self.class != HyperResource, instance-wide otherwise.
+  def method_missing(method, *args)
+    self.get unless self.loaded
+    [:attributes, :objects, :links].each do |field|
+      if self.send(field).respond_to?(method)
+        if self.class == HyperResource
+          define_singleton_method(method) do |*args|
+            self.send(field).send(method, *args)
+          end
+        else
+          self.class.send(:define_method, method) do |*args|
+            self.send(field).send(method, *args)
+          end
+        end
+        return self.send(field).send(method, *args)
+      end
+    end
+    super
+  end
+
+
+  def inspect # :nodoc:
+    "#<#{self.class}:0x#{"%x" % self.object_id} @root=#{self.root.inspect} "+
+    "@href=#{self.href.inspect} @loaded=#{self.loaded} "+
+    "@namespace=#{self.namespace.inspect} ...>"
+  end
+
+end

data/lib/hyper_resource/attributes.rb

@@ -0,0 +1,24 @@
+class HyperResource::Attributes < Hash
+  attr_accessor :parent_resource
+  def initialize(resource=nil)
+    self.parent_resource = resource || HyperResource.new
+  end
+  # Initialize attributes from a HAL response.
+  def init_from_hal(hal_resp)
+    (hal_resp.keys - ['_links', '_embedded']).map(&:to_s).each do |attr|
+      self[attr] = hal_resp[attr]
+
+      unless self.respond_to?(attr.to_sym)
+        define_singleton_method(attr.to_sym)       {    self[attr]  }
+        define_singleton_method("#{attr}=".to_sym) {|v| self[attr]=v}
+      end
+
+      unless self.parent_resource.respond_to?(attr.to_sym)
+        self.parent_resource.define_singleton_method(attr.to_sym) {self[attr]}
+        self.parent_resource.define_singleton_method("#{attr}=".to_sym) do |v|
+          self[attr] = v
+        end
+      end
+    end
+  end
+end

data/lib/hyper_resource/link.rb

@@ -0,0 +1,51 @@
+require 'uri_template'
+
+class HyperResource::Link
+  attr_accessor :base_href,
+                :templated,
+                :params,
+                :parent_resource
+
+  def templated?; templated end
+
+  def initialize(resource=nil, link_spec={})
+    self.parent_resource = resource || HyperResource.new
+    self.base_href  = link_spec['href']
+    self.templated  = !!link_spec['templated']
+    self.params     = link_spec['params'] || {}
+  end
+
+  ## Returns this link's href, applying any URI template params.
+  def href
+    if self.templated?
+      URITemplate.new(self.base_href).expand(params)
+    else
+      self.base_href
+    end
+  end
+
+  ## Returns a new scope with the given params; that is, returns a copy of
+  ## itself with the given params applied.
+  def where(params)
+    self.class.new(self.parent_resource,
+                   'href' => self.base_href,
+                   'templated' => self.templated,
+                   'params' => self.params.merge(params))
+  end
+
+  ## Returns a HyperResource representing this link
+  def resource
+    parent_resource.new_from_link(self.href)
+  end
+
+  ## Returns a HyperResource representing this link, and fetches it.
+  def get
+    self.resource.get
+  end
+
+  ## If we were called with a method we don't know, load this resource
+  ## and pass the message along.  This achieves implicit loading.
+  def method_missing(method, *args)
+    self.get.send(method, *args)
+  end
+end

data/lib/hyper_resource/links.rb

@@ -0,0 +1,26 @@
+class HyperResource
+ class Links < Hash
+   attr_accessor :resource
+
+   def initialize(resource=nil)
+     self.resource = resource || HyperResource.new
+   end
+
+    # Initialize links from a HAL response.
+    def init_from_hal(hal_resp)
+      return unless hal_resp['_links']
+      hal_resp['_links'].each do |rel, link_spec|
+        self[rel] = HyperResource::Link.new(resource, link_spec)
+        unless self.respond_to?(rel.to_sym)
+          define_singleton_method(rel.to_sym) { self[rel] }
+        end
+        unless self.resource.respond_to?(rel.to_sym)
+          self.resource.define_singleton_method(rel.to_sym) {self.links[rel]}
+        end
+      end
+    end
+
+  end
+end
+
+

data/lib/hyper_resource/modules/bless.rb

@@ -0,0 +1,57 @@
+module HyperResource::Modules::Bless
+
+  ## Returns this resource as an instance of +self.resource_class+.
+  ## The returned object will share structure with the source object;
+  ## beware.
+  def blessed
+    return self unless self.namespace
+    self.resource_class.new(self)
+  end
+
+  ## Returns the class into which this resource should be cast.
+  ## If the object is not loaded yet, or if +self.namespace+ is
+  ## not set, returns +self.class+.
+  ##
+  ## Otherwise, +resource_class+ looks at the returned content-type, and 
+  ## attempts to match a 'type=...' modifier.  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 resource_class
+    return self.class unless self.namespace
+    return self.class unless type_name = self.data_type_name
+    class_name = "#{self.namespace}::#{type_name}".
+                   gsub(/[^_0-9A-Za-z:]/, '')
+
+    ## Return data type class if it exists
+    klass = eval(class_name) rescue :sorry_dude
+    return klass if klass.is_a?(Class)
+
+    ## Data type class didn't exist -- create namespace (if necessary),
+    ## then the data type class
+    if self.namespace != ''
+      nsc = eval(self.namespace) rescue :bzzzzzt
+      unless nsc.is_a?(Class)
+        Object.module_eval "class #{self.namespace} < #{self.class}; end"
+      end
+    end
+    Object.module_eval "class #{class_name} < #{self.namespace}; end"
+    eval(class_name)
+  end
+
+  ## Inspects the 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+.  Override this method in a 
+  ## HyperResource subclass in order to implement different data type
+  ## detection.
+  def data_type_name
+    return nil unless self.response
+    return nil unless content_type = self.response['content-type']
+    return nil unless m=content_type.match(/;\s* type=(?<type> [0-9A-Za-z:]+)/x)
+    m[:type][0].upcase + m[:type][1..-1]
+  end
+
+
+end

data/lib/hyper_resource/modules/http.rb

@@ -0,0 +1,39 @@
+require 'faraday'
+require 'uri'
+require 'json'
+
+
+module HyperResource::Modules::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
+
+  ## Returns a per-thread Faraday connection for this object.
+  def faraday_connection(url=nil)
+    url ||= self.root
+    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
+    self.response_body = JSON.parse(self.response.body)
+    self.init_from_response_body!
+    self.blessed
+  end
+
+end

data/lib/hyper_resource/modules/utils.rb

@@ -0,0 +1,29 @@
+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
+
+    end # module ClassMethods
+
+  end
+end

data/lib/hyper_resource/objects.rb

@@ -0,0 +1,31 @@
+class HyperResource::Objects < Hash
+  attr_accessor :parent_resource
+  def initialize(parent_resource=nil)
+    self.parent_resource = parent_resource || HyperResource.new
+  end
+  def init_from_hal(hal_resp)
+    return unless hal_resp['_embedded']
+    hal_resp['_embedded'].each do |name, collection|
+      self[name] = collection.map do |obj|
+        self.parent_resource.new_from_hal(obj)
+      end
+      unless self.respond_to?(name.to_sym)
+        define_singleton_method(name.to_sym) { self[name] }
+      end
+      unless self.parent_resource.respond_to?(name.to_sym)
+        self.parent_resource.define_singleton_method(name.to_sym) {self[name]}
+      end
+    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 [](i)
+    self.first_orig[1][i]
+  end
+end

data/lib/hyper_resource/response.rb

@@ -0,0 +1,2 @@
+class HyperResource::Response < Hash
+end

data/lib/hyper_resource/version.rb

@@ -0,0 +1,4 @@
+class HyperResource
+  VERSION = '0.1.0'
+  VERSION_DATE = '2013-04-07'
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: hyperresource
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Pete Gamache
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: uri_template
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.5.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.5.2
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 10.0.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 10.0.4
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 4.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 4.7.0
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.13.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.13.3
+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
+      returned from these APIs to optionally be extended by client-side code,
+      and to present a modern replacement for ActiveResource.
+email: pete@gamache.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/hyper_resource/attributes.rb
+- lib/hyper_resource/link.rb
+- lib/hyper_resource/links.rb
+- lib/hyper_resource/modules/bless.rb
+- lib/hyper_resource/modules/http.rb
+- lib/hyper_resource/modules/utils.rb
+- lib/hyper_resource/objects.rb
+- lib/hyper_resource/response.rb
+- lib/hyper_resource/version.rb
+- lib/hyper_resource.rb
+homepage: https://github.com/gamache/hyperresource
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.2
+signing_key: 
+specification_version: 4
+summary: Extensible hypermedia client for Ruby
+test_files: []
+has_rdoc: true