tylerhunt-relax 0.0.5 → 0.1.1

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007-2008 Tyler Hunt
+Copyright (c) 2007-2009 Tyler Hunt
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -0,0 +1,194 @@
+= Relax
+
+Relax is a library that provides a foundation for writing REST consumer APIs,
+including the logic to handle the HTTP requests, build URLs with query
+parameters, and parse responses.
+
+
+== Tutorial
+
+This short tutorial will walk you through the basic steps of creating a simple Flickr API consumer that supports a single call to search for photos by tags.
+
+
+=== First Things First
+
+The first step we'll take is to load the Relax gem.
+
+  require 'rubygems'
+
+  gem 'relax', '~> 0.1.0'
+  require 'relax'
+
+Then we'll define our service class.
+
+  class Flickr < Relax::Service
+  end
+
+
+=== Adding an Endpoint
+
+An endpoint is the base URL for the service we'll be consuming. All of our
+actions will be nested inside of an endpoint and build on top of it to
+forumlate the final request URL.
+
+  class Flickr < Relax::Service
+    endpoint 'http://api.flickr.com/services/rest/' do
+    end
+  end
+
+
+=== Adding Default Parameters
+
+Since Flickr requires us to always pass an API key parameter let's make that a
+ required default parameter in our service class.
+
+  class Flickr < Relax::Service
+    defaults do
+      parameter :api_key, :required => true
+    end
+
+    endpoint 'http://api.flickr.com/services/rest/' do
+    end
+  end
+
+
+=== Adding an Action
+
+So we have our service now, but we need to define an action before we can
+actually fetch any data from it.
+
+  class Flickr < Relax::Service
+    defaults do
+      parameter :api_key, :required => true
+    end
+
+    endpoint 'http://api.flickr.com/services/rest/' do
+      action :search do
+        parameter :method, :default => 'flickr.photos.search'
+        parameter :per_page, :default => 5
+        parameter :tags
+      end
+    end
+  end
+
+We're defining an action here called <tt>:search</tt> that will create an
+instance method on our service with the same name. There are three parameters,
+<tt>:method</tt>, <tt>:per_page</tt>, and <tt>:tags</tt>, with <tt>:method</tt>
+and <tt>:per_page</tt> receiving default values.
+
+There are lots of other parameters for the <tt>flickr.photos.search</tt> method
+that we could define, but we'll just stick with these for simplicities sake.
+
+
+=== A Small Refactoring
+
+When adding more methods it will quickly become obvious that we have another
+common parameter in <tt>:method</tt>. We can refactor our service class
+slightly to make this a default parameter for all of the actions on our
+endpoint.
+
+  class Flickr < Relax::Service
+    defaults do
+      parameter :api_key, :required => true
+    end
+
+    endpoint 'http://api.flickr.com/services/rest/' do
+      defaults do
+        parameter :method, :required => true
+      end
+
+      action :search do
+        set :method, 'flickr.photos.search'
+        parameter :per_page, :default => 5
+        parameter :tags
+      end
+    end
+  end
+
+The <tt>set</tt> method allows us to define a default value for a default
+parameter so we don't have to redefine common parameters inside every action.
+
+
+=== Defining a Parser
+
+Before we can actually perform a request we need to let the service know how to
+handle the response. This is done by defining a parser.
+
+  class Flickr < Relax::Service
+    defaults do
+      parameter :api_key, :required => true
+    end
+
+    endpoint 'http://api.flickr.com/services/rest/' do
+      defaults do
+        parameter :method, :required => true
+      end
+
+      action :search do
+        set :method, 'flickr.photos.search'
+        parameter :per_page, :default => 5
+        parameter :tags
+
+        parser :rsp do
+          attribute :stat, :as => :status
+
+          element :photos do
+            attribute :page
+            attribute :pages
+            attribute :perpage, :as => :per_page
+            attribute :total
+
+            elements :photo do
+              attribute :id
+              attribute :owner
+              attribute :secret
+              attribute :server
+              attribute :farm
+              attribute :title
+              attribute :ispublic, :as => :is_public
+              attribute :isfriend, :as => :is_friend
+              attribute :isfamily, :as => :is_family
+            end
+          end
+        end
+      end
+    end
+  end
+
+dhe parsing is performed by the Relief gem, so you can find out more about the
+syntax in its own documentation.
+
+
+=== Making a Call
+
+Now, we're able to create a new instance of our service with the API key set.
+
+  flickr = Flickr.new(:api_key => FLICKR_API_KEY)
+
+We can now use this object to search for photos by tag.
+
+  flickr.search(:tags => 'cucumbers,lemons')
+
+This will return a Ruby response hash.
+
+  {
+    :status => "ok",
+    :photos => {
+      :page => "1",
+      :pages => "3947",
+      :per_page => "5",
+      :total => "19733",
+      :photo => [
+        { :is_public => "1", :secret => "3c196485d2", :server => "3182", :is_friend => "0", :farm => "4", :title => "lemons", :is_family => "0", :id => "3509955709", :owner => "37013676@N06" },
+        { :is_public => "1", :secret => "44f1306a63", :server => "3326", :is_friend => "0", :farm => "4", :title => "Peeto", :is_family => "0", :id => "3509461859", :owner => "13217824@N04" },
+        { :is_public => "1", :secret => "dce53bce7f", :server => "3364", :is_friend => "0", :farm => "4", :title => "Peeto Above", :is_family => "0", :id => "3509459585", :owner => "13217824@N04" },
+        { :is_public => "1", :secret => "12f9ba167c", :server => "3632", :is_friend => "0", :farm => "4", :title => "Lemonaid", :is_family => "0", :id => "3509415752", :owner => "35666391@N03" },
+        { :is_public => "1", :secret => "8caac1ff46", :server => "3320", :is_friend => "0", :farm => "4", :title => "Gardening 365 (Day 8)", :is_family => "0", :id => "3509251322", :owner => "21778017@N06" }
+      ]
+    }
+  }
+
+
+== Copyright
+
+Copyright (c) 2007-2009 Tyler Hunt. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+begin
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |gem|
+    gem.name = "relax"
+    gem.summary = %Q{A flexible library for creating web service consumers.}
+    gem.email = "tyler@tylerhunt.com"
+    gem.homepage = "http://github.com/tylerhunt/relax"
+    gem.authors = ["Tyler Hunt"]
+    gem.rubyforge_project = 'relax'
+
+    gem.add_dependency('rest-client', '~> 0.9.2')
+    gem.add_dependency('nokogiri', '~> 1.2.3')
+    gem.add_dependency('relief', '~> 0.0.3')
+
+    gem.add_development_dependency('jeweler', '~> 0.11.0')
+    gem.add_development_dependency('rspec', '~> 1.2.2')
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+task :default => :spec
+
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "relief #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('LICENSE*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 1

data/lib/relax.rb

@@ -1,13 +1,18 @@
-$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+require 'rubygems'
 
-require 'relax/query'
-require 'relax/parsers'
-require 'relax/request'
-require 'relax/response'
-require 'relax/service'
-require 'relax/symbolic_hash'
+gem 'relief', '~> 0.0.2'
+require 'relief'
 
-module Relax
-  class MissingParameter < ArgumentError ; end
-  class UnrecognizedParser < ArgumentError ; end
+gem 'rest-client', '~> 0.9.2'
+require 'restclient'
+
+module Relax # :nodoc:
+  autoload :Action, 'relax/action'
+  autoload :Context, 'relax/context'
+  autoload :Contextable, 'relax/contextable'
+  autoload :Endpoint, 'relax/endpoint'
+  autoload :Instance, 'relax/instance'
+  autoload :Parameter, 'relax/parameter'
+  autoload :Performer, 'relax/performer'
+  autoload :Service, 'relax/service'
 end

data/lib/relax/action.rb

@@ -0,0 +1,49 @@
+module Relax
+  class Action
+    include Contextable
+
+    attr_reader :name
+
+    def initialize(endpoint, name, options, &block)
+      @endpoint = endpoint
+      @name = name
+      @options = options
+
+      extend_context(endpoint)
+      parse_url_parameters
+      context.evaluate(&block) if block_given?
+    end
+
+    def execute(values, credentials, *args)
+      args.unshift(values) if values
+      instance = Instance.new(*args)
+      response = performer(instance, credentials).perform
+      context.parse(response)
+    end
+
+    def method
+      @options[:method] || :get
+    end
+    private :method
+
+    def url
+      [@endpoint.url, @options[:url]].join
+    end
+    private :url
+
+    def performer(instance, credentials)
+      values = instance.values(context)
+      Performer.new(method, url, values, credentials)
+    end
+    private :performer
+
+    def parse_url_parameters
+      url.scan(/(?:\:)([a-z_]+)/).flatten.each do |name|
+        defaults do
+          parameter name.to_sym, :required => true
+        end
+      end
+    end
+    private :parse_url_parameters
+  end
+end

data/lib/relax/context.rb

@@ -0,0 +1,41 @@
+module Relax
+  class Context
+    attr_reader :parameters
+
+    def initialize(parameters=[]) # :nodoc:
+      @parameters = parameters
+    end
+
+    def evaluate(&block) # :nodoc:
+      instance_eval(&block)
+    end
+
+    def parameter(name, options={})
+      unless @parameters.find { |parameter| parameter.name == name }
+        @parameters << Parameter.new(name, options)
+      else
+        raise ArgumentError.new("Duplicate parameter '#{name}'.")
+      end
+    end
+
+    def set(name, value)
+      if parameter = @parameters.find { |parameter| parameter.name == name }
+        parameter.value = value
+      end
+    end
+
+    def parser(root, options={}, &block) # :nodoc:
+      @parser ||= root.kind_of?(Class) ?  root.new(options, &block) : 
+                                          Relief::Parser.new(root, options, &block)
+    end
+
+    def parse(response) # :nodoc:
+      @parser.parse(response)
+    end
+
+    def clone # :nodoc:
+      cloned_parameters = @parameters.collect { |parameter| parameter.clone }
+      self.class.new(cloned_parameters)
+    end
+  end
+end

data/lib/relax/contextable.rb

@@ -0,0 +1,15 @@
+module Relax
+  module Contextable # :nodoc:
+    def context
+      @context ||= Context.new
+    end
+
+    def extend_context(base)
+      @context = base.context.clone
+    end
+
+    def defaults(&block)
+      context.evaluate(&block)
+    end
+  end
+end

data/lib/relax/endpoint.rb

@@ -0,0 +1,21 @@
+module Relax
+  class Endpoint
+    include Contextable
+
+    attr_reader :url
+
+    def initialize(service, url, options, &block)
+      @service = service
+      @url = url
+      @options = options
+
+      extend_context(service)
+      instance_eval(&block)
+    end
+
+    def action(name, options={}, &block)
+      action = Action.new(self, name, options, &block)
+      @service.register_action(action)
+    end
+  end
+end

data/lib/relax/instance.rb

@@ -0,0 +1,23 @@
+module Relax
+  class Instance # :nodoc:
+    def initialize(*args)
+      @values = args.inject({}) do |values, arg|
+        arg.is_a?(Hash) ? values.merge(arg) : values
+      end
+    end
+
+    def values(context)
+      context.parameters.inject({}) do |values, parameter|
+        name = parameter.name
+
+        if value = @values[parameter.name] || parameter.value
+          values[parameter.name] = value
+        elsif parameter.required?
+          raise ArgumentError.new("Missing value for '#{parameter.name}'.")
+        end
+
+        values
+      end
+    end
+  end
+end