kaiwren-wrest 0.0.4

data/README.rdoc

@@ -0,0 +1,104 @@
+= Wrest
+
+(c) Copyright 2009 {Sidu Ponnappa}[http://blog.sidu.in]. All Rights Reserved.
+
+Wrest is a ruby REST client library which allows you to quickly build object oriented wrappers around any web service. It has two components - Wrest Core and Wrest::Resource.
+
+== Installation
+
+The source is available at git://github.com/kaiwren/wrest.git
+
+To install as a Rails plugin, do <tt>script/plugin install git://github.com/kaiwren/wrest.git</tt>
+
+To install the Wrest gem, you'll need to add GitHub to you gem sources if you haven't already done so:
+
+  gem sources -a http://gems.github.com
+
+Then to install Wrest and its dependencies:
+
+  sudo gem install kaiwren-wrest
+
+
+== Wrest Core
+
+* Designed to be used as a library, not just a command line REST client
+* Provides basic infrastructure (including an interactive shell) and convenient HTTP wrappers
+* Makes it easy to extend and modify both serialisation, deserialisation and object creation
+* Isn't coupled to Rails (usable in a pure Ruby application to consume any REST api)
+* Can be used both stand alone as well as to build object oriented abstractions around web services (Wrest::Resource is an example of the latter)
+
+=== Usage: Shell
+
+You can launch the interactive Wrest shell by running bin/wrest if you have the source or invoking <tt>wrest</tt> from your prompt if you've installed the gem.
+  $ wrest
+  >> "http://search.yahooapis.com/NewsSearchService/V1/newsSearch?appid=YahooDemo&output=json&query=India&results=3&start=1".to_uri.get
+
+=== Usage: Library
+
+  require 'rubygems'
+  require 'wrest'
+  y "http://search.yahooapis.com/NewsSearchService/V1/newsSearch".to_uri.get(
+									:appid  => 'YahooDemo', 
+									:output => 'xml',
+									:query  => 'India',
+									:results=> '3',
+									:start  => '1'
+								)
+=== Basic Http Calls
+
+==== Get
+
+A couple of ways to get the Yahoo news as hash map (needs the JSON gem - gem install json). 
+
+* This example simply does a get on a uri and figures out the appropriate deserialiser using the content-type (in this case 'text/javascript', which uses Wrest::Translators::Json). See content_types.rb under lib/wrest/mappers/translators.
+ "http://search.yahooapis.com/NewsSearchService/V1/newsSearch?appid=YahooDemo&output=json&query=India&results=3&start=1".to_uri.get.deserialise
+
+* This example does a get on a base uri with several parameters passed to it, resulting in a uri essentially the same as the one above. It also shows how you can use a custom deserialiser to produce a hash-map from the response. 
+ "http://search.yahooapis.com/NewsSearchService/V1/newsSearch".to_uri.get(
+									:appid  => 'YahooDemo', 
+									:output => 'xml',
+									:query  => 'India',
+									:results=> '3',
+									:start  => '1'
+								).deserialise_using(Wrest::Translators::Xml)
+
+
+=== Logging
+
+The Wrest logger can be set and accessed through Wrest.logger and is configured by default to log to STDOUT. If you're using Wrest in a Rails application, you can configure logging by placing the following line in your environment file:
+  Wrest.logger = ActiveRecord::Base.logger
+
+=== Build
+
+Standard options are available and can be listed using <tt>rake -T</tt>. Use rake:rcov for coverage and rake:rdoc to generate documentation.
+
+== Wrest::Resource 
+
+Wrest::Resource is an alternative to ActiveResource which targets Rails REST services; it is currently under development.
+
+* Out of the box support for collections
+* Out of the box support for collection pagination (including support for WillPaginate), both header based and xml attribute based
+* Out of the box support for operations on all the records on the collection
+* Out of the box support for nested resources
+* Out of the box support for cached resources
+* Out of the box support for type-casting data that comes in as parameter strings
+* More natural mapping of deserialised entities to existing classes
+* No communication via exceptions for http error status codes
+* Better extensibility - allows access to request/response objects, avoids class variables, favours symbols over strings etc.
+
+== Dependencies
+
+* gems
+* xmlsimple
+* json
+* rspec
+* rcov
+* active_support
+
+== Support
+
+This project uses Assembla for ticketing: http://www.assembla.com/spaces/wrest/tickets
+
+== Licence
+
+Wrest is released under the Apache 2.0 licence

data/Rakefile

@@ -0,0 +1,203 @@
+# Copyright 2009 Sidu Ponnappa
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+gem 'rspec'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec'
+require 'spec/rake/spectask'
+require 'rcov'
+require 'rcov/rcovtask'
+
+desc 'Default: run spec tests.'
+task :default => :spec
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new(:spec) do |task|
+  task.spec_files = FileList['spec/wrest/**/*_spec.rb']
+  task.spec_opts = ['--options', 'spec/spec.opts']
+end
+
+desc 'Generate documentation for Wrest'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = 'WRest'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Run all specs in spec directory with RCov"
+Spec::Rake::SpecTask.new(:rcov) do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_files = FileList["spec/wrest/**/*_spec.rb"]
+  t.rcov = true
+  t.rcov_opts = lambda do
+    IO.readlines("spec/rcov.opts").map {|l| l.chomp.split " "}.flatten
+  end
+  # t.verbose = true
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "wrest"
+    gemspec.version = "0.0.3"
+    gemspec.summary = "REST client library for Ruby."
+    gemspec.description = "Wrest is a REST client library which allows you to quickly build object oriented wrappers around any web service. It has two main components - Wrest Core and Wrest::Resource."
+    gemspec.authors = ["Sidu Ponnappa"]
+    gemspec.email = "ckponnappa@gmail.com"
+    gemspec.homepage = "http://github.com/kaiwren/wrest"
+    gemspec.has_rdoc = true
+    gemspec.platform = Gem::Platform::RUBY
+    gemspec.executables = ['wrest']
+    gemspec.require_path = "lib"
+    gemspec.files.exclude 'spec/wrest/meh_spec.rb'
+    gemspec.test_files.exclude 'spec/wrest/meh_spec.rb'
+    gemspec.add_dependency('activesupport', '>= 2.1.0')    
+    gemspec.add_dependency('json', '>= 1.1.3')    
+    gemspec.add_dependency('xml-simple', '>= 1.0.11')    
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+namespace (:benchmark) do
+  desc "Create classes to be used in Wrest::Resource vs. ActiveResource"
+  task :setup_test_classes do
+    require 'active_resource'
+    require 'wrest'
+    
+    class Ooga < Wrest::Mappers::Resource::Base;end
+    class Booga < ActiveResource::Base; self.site='';end
+  end
+  
+  desc "Benchmark when objects are created each time before getting data; i.e there are few queries per instantiation"
+  task :create_and_get => :setup_test_classes do |t|    
+    
+    n = 10000
+    puts "Running #{n} times per report"
+    Benchmark.bmbm(10) do |rpt|
+      rpt.report("Wrest::Resource") do
+        n.times { 
+          ooga = Ooga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+          ooga.profession
+          ooga.profession?
+          ooga.enhanced_by 
+          ooga.enhanced_by? 
+        }
+      end
+
+      rpt.report("ActiveResource") do
+        n.times { 
+          booga = Booga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+          booga.profession
+          booga.profession?
+          booga.enhanced_by 
+          booga.enhanced_by?
+        }
+      end
+    end
+  end
+  
+  desc "Benchmark when objects are created beforehand; i.e there are many queries per instantiation"
+  task :create_once_and_get => :setup_test_classes do |t|    
+
+    n = 10000
+    puts "Running #{n} times per report"
+    
+    Benchmark.bmbm(10) do |rpt|      
+      rpt.report("Wrest::Resource") do
+        ooga = Ooga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+        
+        n.times { 
+          ooga.profession
+          ooga.profession?
+          ooga.enhanced_by 
+          ooga.enhanced_by?
+        }
+      end
+
+      rpt.report("ActiveResource") do
+        booga = Booga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+                
+        n.times { 
+          booga.profession
+          booga.profession?
+          booga.enhanced_by 
+          booga.enhanced_by?
+        }
+      end
+    end
+  end
+  
+  desc "Benchmark objects respond_to? performance without invocation"
+  task :responds_to_before => :setup_test_classes do |t|    
+
+    n = 10000
+    puts "Running #{n} times per report"
+    
+    Benchmark.bmbm(10) do |rpt|      
+      rpt.report("Wrest::Resource") do
+        ooga = Ooga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+        
+        n.times { 
+          ooga.respond_to?(:profession)
+          ooga.respond_to?(:profession?)
+          ooga.respond_to?(:profession=)
+        }
+      end
+
+      rpt.report("ActiveResource") do
+        booga = Booga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+                
+        n.times { 
+          booga.respond_to?(:profession)
+          booga.respond_to?(:profession?)
+          booga.respond_to?(:profession=)
+        }
+      end
+    end
+  end
+
+  desc "Benchmark objects respond_to? performance after invocation"
+  task :responds_to_after => :setup_test_classes do |t|    
+
+    n = 10000
+    puts "Running #{n} times per report"
+    
+    Benchmark.bmbm(10) do |rpt|      
+      rpt.report("Wrest::Resource") do
+        ooga = Ooga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+        ooga.profession
+        ooga.profession?
+        ooga.profession = ''
+        
+        n.times { 
+          ooga.respond_to?(:profession)
+          ooga.respond_to?(:profession?)
+          ooga.respond_to?(:profession=)
+        }
+      end
+
+      rpt.report("ActiveResource") do
+        booga = Booga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+        booga.profession
+        booga.profession?
+        booga.profession = ''
+                        
+        n.times { 
+          booga.respond_to?(:profession)
+          booga.respond_to?(:profession?)
+          booga.respond_to?(:profession=)
+        }
+      end
+    end
+  end
+end

data/VERSION.yml

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

data/bin/wrest

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+#!/usr/bin/env ruby
+entry_point = "#{File.dirname(__FILE__)}/../lib/wrest.rb"
+version = "#{File.dirname(__FILE__)}/../lib/wrest/version"
+
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+require 'optparse'
+options = { :irb => irb }
+OptionParser.new do |opt|
+  opt.banner = "Usage: console [options]"
+  opt.on("--irb=[#{irb}]", 'Invoke a different irb.') { |v| options[:irb] = v }
+  opt.parse!(ARGV)
+end
+
+libs =  " -r irb/completion"
+libs << " -r #{entry_point}"
+
+require version
+puts "Loading (Wrest #{Wrest::VERSION::STRING})"
+exec "#{options[:irb]} #{libs} --simple-prompt"

data/lib/wrest.rb

@@ -0,0 +1,41 @@
+# Copyright 2009 Sidu Ponnappa
+# Licensed under the Apache License, Version 2.0 (the "License"); 
+# you may not use this file except in compliance with the License. 
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 
+# Unless required by applicable law or agreed to in writing, software distributed under the License 
+# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+# See the License for the specific language governing permissions and limitations under the License. 
+
+require 'rubygems'
+require 'net/http'
+require 'net/https'
+require 'forwardable'
+require 'date'
+require 'cgi'
+require 'base64'
+require 'logger'
+require 'benchmark'
+require 'active_support'
+
+WREST_ROOT = File.dirname(__FILE__)
+
+module Wrest
+  def self.logger=(logger)
+    @logger = logger
+  end
+  
+  def self.logger
+    @logger
+  end
+end
+
+Wrest.logger = Logger.new(STDOUT)
+Wrest.logger.level = Logger::DEBUG
+
+source_dirs = ["/wrest/core_ext/*.rb", "/wrest/*.rb"]
+
+source_dirs.each{|directory|
+  Dir["#{File.expand_path(File.dirname(__FILE__) + directory)}"].each { |file|
+    require file
+  }
+}

data/lib/wrest/core_ext/string.rb

@@ -0,0 +1,5 @@
+require "#{WREST_ROOT}/wrest/core_ext/string/conversions"
+
+class String #:nodoc:
+  include Wrest::CoreExt::String::Conversions
+end

data/lib/wrest/core_ext/string/conversions.rb

@@ -0,0 +1,23 @@
+# Copyright 2009 Sidu Ponnappa
+
+# Licensed under the Apache License, Version 2.0 (the "License"); 
+# you may not use this file except in compliance with the License. 
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 
+# Unless required by applicable law or agreed to in writing, software distributed under the License 
+# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+# See the License for the specific language governing permissions and limitations under the License. 
+
+module Wrest
+  module CoreExt #:nodoc:
+    module String #:nodoc:
+      # Makes it easier to build other objects from a String
+      module Conversions
+
+        # A convenience method equivalent to Wrest::Uri.new(string)
+        def to_uri
+          Wrest::Uri.new(self)
+        end
+      end
+    end
+  end
+end

data/lib/wrest/exceptions.rb

@@ -0,0 +1 @@
+require "#{WREST_ROOT}/wrest/exceptions/unsupported_content_type_exception"

data/lib/wrest/exceptions/unsupported_content_type_exception.rb

@@ -0,0 +1,15 @@
+# Copyright 2009 Sidu Ponnappa
+
+# Licensed under the Apache License, Version 2.0 (the "License"); 
+# you may not use this file except in compliance with the License. 
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 
+# Unless required by applicable law or agreed to in writing, software distributed under the License 
+# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+# See the License for the specific language governing permissions and limitations under the License. 
+
+module Wrest
+  # Raised when a translator for an unregisterd response content type
+  # is requested. See Translators.
+  class UnsupportedContentTypeException < StandardError
+  end
+end

data/lib/wrest/mappers.rb

@@ -0,0 +1,21 @@
+# Copyright 2009 Sidu Ponnappa
+
+# Licensed under the Apache License, Version 2.0 (the "License"); 
+# you may not use this file except in compliance with the License. 
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 
+# Unless required by applicable law or agreed to in writing, software distributed under the License 
+# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+# See the License for the specific language governing permissions and limitations under the License. 
+
+module Wrest #:nodoc:
+  # A Mapper is anything that constructs an object
+  # or object graph from a hash map. This hash map
+  # is typically obtained by using a Translator to
+  # deserialise a Response.
+  module Mappers
+  end
+end
+
+require "#{WREST_ROOT}/wrest/mappers/attributes_container"
+require "#{WREST_ROOT}/wrest/mappers/simple_resource"
+require "#{WREST_ROOT}/wrest/mappers/resource"