relax 0.1.3 → 0.2.0

data/README.rdoc

@@ -1,194 +0,0 @@
-= 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/VERSION.yml

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

data/lib/relax/action.rb

@@ -1,49 +0,0 @@
-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, options, *args)
-      args.unshift(values) if values
-      instance = Instance.new(options, *args)
-      response = performer(instance, options).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, options)
-      values = instance.values(context)
-      Performer.new(method, url, values, options)
-    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

@@ -1,46 +0,0 @@
-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.named?(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.named?(name) }
-        parameter.value = value
-      end
-    end
-
-    def parser(root, options={}, &block) # :nodoc:
-      @parser ||= begin
-        if root.kind_of?(Class)
-          root.new(options, &block)
-        else
-          Relief::Parser.new(root, options, &block)
-        end
-      end
-    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

@@ -1,15 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,25 +0,0 @@
-module Relax
-  class Instance # :nodoc:
-    def initialize(options, *args)
-      @options = options
-
-      @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.options[:as] || parameter.name
-
-        if (value = @values[name] || parameter.value) || @options[:include_blank_values]
-          values[parameter.name] = value
-        elsif parameter.required?
-          raise ArgumentError.new("Missing value for '#{name}'.")
-        end
-
-        values
-      end
-    end
-  end
-end

data/lib/relax/parameter.rb

@@ -1,23 +0,0 @@
-module Relax
-  class Parameter
-    attr_reader :name, :options
-    attr_writer :value
-
-    def initialize(name, options={})
-      @name = name
-      @options = options
-    end
-
-    def named?(name)
-      name == (@options[:as] || @name)
-    end
-
-    def value
-      @value || @options[:default]
-    end
-
-    def required?
-      @options[:required]
-    end
-  end
-end

data/lib/relax/performer.rb

@@ -1,58 +0,0 @@
-module Relax
-  class Performer
-    def initialize(method, url, values, options={})
-      @method = method
-      @url = url
-      @values = values
-      @logger = options.delete(:logger)
-      @credentials = options.delete(:credentials)
-      @proxy = options.delete(:proxy)
-      @options = options
-
-      parse_url_tokens
-    end
-
-    def perform
-      RestClient.proxy = @proxy if @proxy
-
-      case @method
-        when :delete, :get, :head
-          @logger.info "#{@method.to_s.upcase} #{url}" if @logger
-          RestClient.send(@method, url)
-        when :post, :put
-          @logger.info "#{@method.to_s.upcase} #{url}\n#{query}" if @logger
-          RestClient.send(@method, url, query)
-      end
-    end
-
-    def url
-      url = @url.gsub(/\:[a-z_]+/) do |name|
-        @url_values[name[1..-1].to_sym]
-      end
-
-      uri = URI.parse(url)
-      uri.query = query unless query.nil? || query.empty?
-      uri.userinfo = @credentials.join(':') if @credentials
-      uri.to_s
-    end
-    private :url
-
-    def query
-      @values.collect do |name, value|
-        "#{name}=#{value}" if value || @options[:include_blank_values]
-      end.compact.join('&')
-    end
-    private :query
-
-    def parse_url_tokens
-      tokens = @url.scan(/(?:\:)([a-z_]+)/).flatten
-
-      @url_values = tokens.inject({}) do |values, name|
-        name = name.to_sym
-        values[name] = @values.delete(name) if @values.key?(name)
-        values
-      end
-    end
-    private :parse_url_tokens
-  end
-end