hypermedia 1.1.1 → 1.2.0

data/lib/api/api.rb

@@ -4,7 +4,9 @@ module HypermediaAPI
   BadURI = Class.new(Exception)
   MissingForm = Class.new(Exception)
   MissingLink = Class.new(Exception)
+  UnsupportedHTTPMethod = Class.new(Exception)
   
+  # Returns an open Net::HTTP connection to the given URI.
   def HypermediaAPI.connection (uri)
     connection = Net::HTTP.new(uri.host, uri.port)
     
@@ -16,13 +18,30 @@ module HypermediaAPI
     connection
   end
   
+  # Raises an error. DELETE requests are unsupported.
+  def HypermediaAPI.delete (*)
+    raise HypermediaAPI::UnsupportedHTTPMethod, "Only GET and POST requests are supported (attempted DELETE)"
+  end
+  
+  # GETs the given uri (with or without form data) and returns a
+  # HypermediaAPI::Document representing the response. Currently the valid
+  # options are 1) an :inputs Hash containing form data key-value pairs and
+  # 2) an :auth Hash containing HTTP basic auth username and password.
   def HypermediaAPI.get (uri_string, options = {})
     uri = URI(uri_string)
     get = Net::HTTP::Get.new(uri.request_uri)
     
+    if options[:inputs]
+      get.set_form_data(options[:inputs])
+    end
+    
     HypermediaAPI.send_request(uri, get, options)
   end
   
+  # POSTs form data to the given uri and returns a HypermediaAPI::Document
+  # representing the response. Currently the valid options are 1) an :inputs
+  # Hash containing form data key-value pairs and 2) an :auth Hash containing
+  # HTTP basic auth username and password.
   def HypermediaAPI.post (uri_string, options = {})
     uri = URI(uri_string)
     post = Net::HTTP::Post.new(uri.request_uri)
@@ -31,8 +50,16 @@ module HypermediaAPI
     HypermediaAPI.send_request(uri, post, options)
   end
   
+  # Raises an error. PUT requests are unsupported.
+  def HypermediaAPI.put (*)
+    raise HypermediaAPI::UnsupportedHTTPMethod, "Only GET and POST requests are supported (attempted PUT)"
+  end
+  
+  # Sends a request to the given URI and returns a HypermediaAPI::Document
+  # representing the response. Currently the only valid option is an :auth Hash
+  # containing HTTP basic auth username and password.
   def HypermediaAPI.send_request (uri, request, options)
-    if auth = options[:basic_auth]
+    if auth = options[:auth]
       request.basic_auth(auth[:username], auth[:password])
     end
     

data/lib/api/document.rb

@@ -1,68 +1,22 @@
 # encoding: UTF-8
 
 class HypermediaAPI::Document
-  def entity (klass)
-    article_element = @document.at_css("article.#{klass.name.underscore}")
-    return nil unless article_element
-    
-    klass.new_from_fields(article_element.element_children.filter('code'))
-  end
-  
-  def entities (klass)
-    article_elements = @document.css("article.#{klass.name.underscore}")
-    article_elements.map {|article_element| klass.new_from_fields(article_element.element_children.filter('code')) }
-  end
-  
-  def form (css_selector)
-    if form_element = @document.at_css(css_selector)
-      action_uri = form_element['action']
-      http_method = form_element['method'].downcase
-      
-      HypermediaAPI::Form.new(action_uri, http_method)
-    else
-      raise HypermediaAPI::MissingForm, "The API does not have a form matching '#{css_selector}'."
-    end
-  end
+  include HypermediaAPI::Html
   
+  # Returns the document's HTTP headers as a Hash.
   def headers
     @headers
   end
   
-  def html
-    @document.to_html
-  end
-  
-  def initialize (nokogiri_html_document, status, headers, auth)
-    @document = nokogiri_html_document
+  # Sets the HTML, status, headers, and auth info of the new document.
+  def initialize (nokogiri_html, status, headers, http_basic_auth)
+    @nhtml = nokogiri_html
     @status = status.to_i
     @headers = headers
-    @auth = auth
-  end
-  
-  def link (css_selector)
-    if a_element = @document.at_css(css_selector)
-      href_uri = a_element['href']
-      HypermediaAPI::Link.new(href_uri)
-    else
-      raise HypermediaAPI::MissingLink, "The API does not have a link matching '#{css_selector}'."
-    end
-  end
-  
-  def look_up_entity (klass, kv_pair)
-    index_link = self.link("nav#index-links a##{klass.name.underscore.pluralize}-link")
-    index_doc = index_link.click(basic_auth: @auth)
-    
-    data_name, value = kv_pair.first
-    article_element = index_doc.instance_variable_get(:@document).at_xpath("//article[@class='#{klass.name.underscore}']/code[@data-name='#{data_name}' and text()='#{value}']/ancestor::article")
-    return nil unless article_element
-    
-    bookmark_link_element = article_element.at_css('a[rel="bookmark"]')
-    bookmark_link = HypermediaAPI::Link.new(bookmark_link_element['href'])
-    entity_doc = bookmark_link.click(basic_auth: @auth)
-    
-    entity_doc.entity(klass)
+    @http_basic_auth = http_basic_auth
   end
   
+  # Returns the HTTP status code of the document as an integer.
   def status
     @status
   end

data/lib/api/entity.rb

@@ -0,0 +1,103 @@
+# encoding: UTF-8
+
+class HypermediaAPI::Entity
+  include HypermediaAPI::Html
+  
+  # Sets the fields for this entity class.
+  def self.fields (*field_names)
+    return (@field_names || []) if field_names.empty?
+    @field_names = field_names.map(&:to_sym).each {|field_name| attr_reader field_name }
+  end
+  
+  # Returns a Hash containing the HTTP Basic Auth :username and :password for
+  # this entity class.
+  def self.auth
+    @auth ||= { username: '', password: '' }
+  end
+  
+  # Sets the HTTP Basic Auth :username and :password for this entity class.
+  def self.authorize (username, password)
+    @auth = { username: username, password: password }
+  end
+  
+  # Sets the authorization and API root url for subclasses of this entity class.
+  def self.inherited (subclass)
+    subclass.authorize(self.auth[:username], self.auth[:password])
+    subclass.root_url(@root_url)
+  end
+  
+  # Creates a new entity of this entity class using the HTML in article_element.
+  def self.new_from_article_element (article_element)
+    entity = self.new
+    entity.instance_variable_set(:"@nhtml", article_element)
+    entity.instance_variable_set(:"@http_basic_auth", self.auth)
+    
+    if bookmark_a_element = article_element.element_children.filter('a[rel=bookmark]').first
+      link = HypermediaAPI::Link.new(bookmark_a_element['href'], self.auth)
+      entity.instance_variable_set(:"@bookmark_link", link)
+    end
+    
+    values = article_element.element_children.filter('code').map do |field_element|
+      value_str = field_element.content
+      name = field_element['data-name']
+      
+      value = case field_element['data-type']
+        when 'date' then value_str.empty? ? nil : Date.parse(value_str)
+        when 'integer' then value_str.empty? ? nil : value_str.to_i
+        when 'float' then value_str.empty? ? nil : value_str.to_f
+        when 'boolean' then value_str.empty? ? nil : value_str != 'false'
+        when 'string' then value_str
+      end
+      
+      [name, value]
+    end
+    
+    values.each do |name, value|
+      next unless entity.respond_to?(name)
+      entity.instance_variable_set(:"@#{name}", value)
+    end
+    
+    entity
+  end
+  
+  # Submits a query using the named query form found in the API root document of
+  # this entity class, then returns a Hypermedia::Document representing the
+  # response.
+  def self.query (query_name, form_values)
+    query_form = self.root_doc.form("##{query_name.to_s.dasherize}")
+    query_form.submit(form_values)
+  end
+  
+  # Returns the API root document for this entity class.
+  def self.root_doc
+    @root_doc ||= HypermediaAPI.get(@root_url, auth: self.auth)
+  end
+  
+  # Sets the API root url for this entity class.
+  def self.root_url (url)
+    @root_url = url
+  end
+  
+  # Returns a HypermediaAPI::Link pointing to the bookmark uri of the entity.
+  def bookmark_link
+    @bookmark_link
+  end
+  
+  # Reloads the HypermediaAPI::Entity from the uri in the bookmark link.
+  def reload!
+    response = self.bookmark_link.click
+    
+    if response.status == 200
+      entity = response.entity(self.class)
+      
+      self.instance_variable_set(:"@nhtml", entity.instance_variable_get(:"@nhtml"))
+      self.instance_variable_set(:"@bookmark_link", entity.instance_variable_get(:"@bookmark_link"))
+      
+      self.class.fields.each do |field_name|
+        self.instance_variable_set(:"@#{field_name}", entity.send(field_name))
+      end
+    end
+    
+    self
+  end
+end

data/lib/api/form.rb

@@ -1,16 +1,33 @@
 # encoding: UTF-8
 
 class HypermediaAPI::Form
-  def initialize (action_uri, http_method)
-    @action_uri = action_uri
-    @http_method = http_method.downcase
+  # Returns the action uri of this form.
+  def action
+    @action_uri_str
   end
   
+  # Returns the HTTP basic auth of this form.
+  def auth
+    @http_basic_auth
+  end
+  
+  # Sets the action uri, HTTP method, and HTTP basic auth of this form.
+  def initialize (action_uri_str, http_method, http_basic_auth = nil)
+    @action_uri_str = action_uri_str.to_s
+    @http_method = http_method.to_s.upcase
+    @http_basic_auth = http_basic_auth || { username: '', password: '' }
+  end
+  
+  # Returns the HTTP method of this form.
+  def method
+    @http_method
+  end
+  
+  # Submits this form with the given inputs, then returns a Hypermedia::Document
+  # representing the response.
   def submit (inputs, options = {})
-    case @http_method
-      when 'post' then HypermediaAPI.post(@action_uri, options.merge(inputs: inputs))
-    end
+    HypermediaAPI.send(self.method.downcase, self.action, { inputs: inputs, auth: self.auth }.merge(options))
   rescue SocketError
-    raise HypermediaAPI::BadURI, "The client was unable to interact with a resource at #{@action_uri}."
+    raise HypermediaAPI::BadURI, "The client was unable to interact with a resource at #{self.action}."
   end
 end

data/lib/api/html.rb

@@ -0,0 +1,48 @@
+# encoding: UTF-8
+
+module HypermediaAPI::Html
+  # Returns the HTTP basic auth of the HTML.
+  def auth
+    @http_basic_auth
+  end
+  
+  # Returns the first HypermediaAPI::Entity of the given class found in the
+  # HTML, or nil if no such entity exists.
+  def entity (entity_class)
+    article_element = @nhtml.at_css("article.#{entity_class.name.underscore}")
+    entity_class.new_from_article_element(article_element)
+  end
+  
+  # Returns an array of every HypermediaAPI::Entity of the given class found in
+  # the HTML.
+  def entities (entity_class)
+    @nhtml.css("article.#{entity_class.name.underscore}").map do |article_element|
+      entity_class.new_from_article_element(article_element)
+    end.compact
+  end
+  
+  # Returns a HypermediaAPI::Form representing the first form element that
+  # matches the given css_selector. If no such form is found, raises an error.
+  def form (css_selector)
+    if form_element = @nhtml.css(css_selector).filter('form').first
+      HypermediaAPI::Form.new(form_element['action'], form_element['method'], self.auth)
+    else
+      raise HypermediaAPI::MissingForm, "There is no form matching '#{css_selector}' in HTML:\n#{self.html}"
+    end
+  end
+  
+  # Returns the HTML as a string.
+  def html
+    @nhtml.to_html
+  end
+  
+  # Returns a HypermediaAPI::Link representing the first anchor element that
+  # matches the given css_selector. If no such anchor is found, raises an error.
+  def link (css_selector)
+    if a_element = @nhtml.css(css_selector).filter('a').first
+      HypermediaAPI::Link.new(a_element['href'], self.auth)
+    else
+      raise HypermediaAPI::MissingLink, "There is no link matching '#{css_selector}' in HTML:\n#{self.html}"
+    end
+  end
+end

data/lib/api/link.rb

@@ -1,13 +1,27 @@
 # encoding: UTF-8
 
 class HypermediaAPI::Link
-  def initialize (href_uri)
-    @href_uri = href_uri
+  # Returns the HTTP basic auth of this link.
+  def auth
+    @http_basic_auth
   end
   
+  # Sends a GET request to the href uri of this link, then returns a
+  # HypermediaAPI::Document representing the response.
   def click (options = {})
-    document = HypermediaAPI.get(@href_uri, options)
+    document = HypermediaAPI.get(self.href, { auth: self.auth }.merge(options))
   rescue SocketError
-    raise HypermediaAPI::BadURI, "The client was unable to interact with a resource at #{@href_uri}."
+    raise HypermediaAPI::BadURI, "The client was unable to interact with a resource at #{self.href}."
+  end
+  
+  # Returns the href uri of this link.
+  def href
+    @href_uri_str
+  end
+  
+  # Sets the href uri and HTTP basic auth of this link.
+  def initialize (href_uri_str, http_basic_auth = nil)
+    @href_uri_str = href_uri_str.to_s
+    @http_basic_auth = http_basic_auth || { username: '', password: '' }
   end
 end

data/lib/hypermedia.rb

@@ -6,7 +6,8 @@ require 'net/http'
 require 'active_support/all'
 
 require_relative 'api/api.rb'
+require_relative 'api/html.rb'
 require_relative 'api/document.rb'
+require_relative 'api/entity.rb'
 require_relative 'api/form.rb'
 require_relative 'api/link.rb'
-require_relative 'api/model.rb'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hypermedia
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -51,9 +51,10 @@ extra_rdoc_files: []
 files:
 - ./lib/api/api.rb
 - ./lib/api/document.rb
+- ./lib/api/entity.rb
 - ./lib/api/form.rb
+- ./lib/api/html.rb
 - ./lib/api/link.rb
-- ./lib/api/model.rb
 - ./lib/hypermedia.rb
 homepage: 
 licenses: []

data/lib/api/model.rb

@@ -1,52 +0,0 @@
-# encoding: UTF-8
-
-class HypermediaAPI::Model
-  def self.auth
-    @auth ||= { username: '', password: '' }
-  end
-  
-  def self.authorize (username, password)
-    @auth = { username: username, password: password }
-  end
-  
-  def self.inherited (subclass)
-    subclass.authorize(self.auth[:username], self.auth[:password])
-    subclass.root_url(@root_url)
-  end
-  
-  def self.new_from_fields (field_elements)
-    instance = self.new
-    
-    field_elements.each do |field_element|
-      value_str = field_element.content
-      name = field_element['data-name']
-      
-      value = case field_element['data-type']
-        when 'date' then value_str.empty? ? nil : Date.parse(value_str)
-        when 'integer' then value_str.empty? ? nil : value_str.to_i
-        when 'float' then value_str.empty? ? nil : value_str.to_f
-        when 'boolean' then value_str.empty? ? nil : value_str != 'false'
-        when 'string' then value_str
-      end
-      
-      if instance.respond_to?(name)
-        instance.send(:"#{name}=", value)
-      end
-    end
-    
-    instance
-  end
-  
-  def self.root_url (url)
-    @root_url = url
-  end
-  
-  def self.root_doc
-    @root_doc ||= HypermediaAPI.get(@root_url, basic_auth: self.auth)
-  end
-  
-  def self.query (query_name, form_values)
-    query_form = self.root_doc.form("##{query_name.to_s.dasherize}")
-    query_form.submit(form_values, basic_auth: self.auth)
-  end
-end