wrest 0.0.6 → 0.0.7

data/README.rdoc

@@ -40,30 +40,56 @@ You can launch the interactive Wrest shell by running bin/wrest if you have the
 								)
 === Basic Http Calls
 
-==== Get
+==== GET
 
-A couple of ways to get the Yahoo news as hash map (needs the JSON gem - gem install json). 
+A couple of ways to get the Yahoo news as hash map. 
 
 * 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 specify a custom deserialiser to produce a hash-map from the response, as well as a hash mutator to clean up the deserialised hash.
-  require 'rubygems'
-  require 'wrest'
+ require 'rubygems'
+ require 'wrest'
+ include Wrest::Components
+ y "http://search.yahooapis.com/NewsSearchService/V1/newsSearch".to_uri.get(
+									:appid  => 'YahooDemo', 
+									:output => 'xml',
+									:query  => 'India',
+									:results=> '3',
+									:start  => '1'
+								).deserialise_using(
+									Translators::Xml
+								).mutate_using(
+									Mutators::XmlSimpleTypeCaster.new
+								)									  
+
+==== OPTIONS
+
+To find out what actions are permitted on a URI:
+
+ 'http://www.yahoo.com'.to_uri.options.headers['allow']
+
+
+=== Attributes Container
+
+Allows any class to hold an attributes hash, somewhat like ActiveResource. It also supports several extensions to this base fuctionality such as support for typecasting attribute values.
+
+Example:
+
+ class Demon
+   include Wrest::Components::AttributesContainer
+   include Wrest::Components::AttributesContainer::Typecaster
 
-  include Wrest::Components
-  p "http://search.yahooapis.com/NewsSearchService/V1/newsSearch".to_uri.get(
-																			  :appid  => 'YahooDemo', 
-																			  :output => 'xml',
-																			  :query  => 'India',
-																			  :results=> '3',
-																			  :start  => '1'
-																			).deserialise_using(
-																			  Translators::Xml
-																			).mutate_using(
-																			  Mutators::XmlSimpleTypeCaster.new
-																			)
+   always_has	    :id  
+   typecast         :age          =>  as_integer,
+                    :chi          =>  lambda{|chi| Chi.new(chi)}
+ end
 
+ kai_wren = Demon.new('id => '1', 'age' => '1500', 'chi' => '1024', 'teacher' => 'Viss')
+ kai_wren.id            # => '1'
+ kai_wren.age           # => 1500
+ kai_wren.chi           # => #<Chi:0x113af8c @count="1024">
+ kai_wren.teacher		# => 'Viss'
 
 === Logging
 
@@ -80,9 +106,14 @@ Wrest RDocs can be found at http://wrest.rubyforge.org
 
 == Wrest::Resource 
 
-Wrest::Resource is an alternative to ActiveResource. It targets Rails REST services and is currently under development.
+Wrest::Resource is an alternative to ActiveResource. It targets Rails REST (well, POX - turns out Rails isn't really REST) services and is currently under development.
 
-* No more pretending that REST resources are the same as database records
+* No more pretending that REST resources are the same as records in a database (yeah, no more freaking ActiveResource::Connection)
+* Treat put as 'create or update,' not just 'update'
+* Response codes result in user defined state transitions; favours state transitions based on response code over arbitrary ones
+* Supports moving toward hypermedia links as opposed to client server collusion through URI templates
+* The header is now exposed as metadata, rather being than something you have no control over
+* Out of the box support for If-Unmodified-Since/If-Match+Etag
 * 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
@@ -92,14 +123,15 @@ Wrest::Resource is an alternative to ActiveResource. It targets Rails REST servi
 * 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.
+* Consider support for OPTIONS and response codes 100/417
 
 == Dependencies
 
 === Source
 * gems
-* xmlsimple
 * json (json-jruby on JRuby)
 * active_support
+* ruby-libxml (Recommended, will fall back to REXML if absent; be aware that Wrest uses ActiveSupport::XmlMini, so if you're using Wrest as a plugin in a Rails application, all xml parsing across the application will switch to using libxml if it's available. You're free to change this by hand by using the ActiveSupport::XmlMini.backend= method.)
 
 === Build
 * rspec

data/Rakefile

@@ -10,7 +10,6 @@
 require 'rubygems'
 gem 'rspec'
 require 'rake'
-require 'hanna/rdoctask'
 require 'spec'
 require 'spec/rake/spectask'
 
@@ -25,6 +24,12 @@ Spec::Rake::SpecTask.new(:spec) do |task|
   task.spec_opts = ['--options', 'spec/spec.opts']
 end
 
+begin
+  require 'hanna/rdoctask'
+rescue LoadError
+  puts 'Hanna not available, using standard Rake rdoctask. Fix this by running gem install mislav-hanna.'
+  require 'rake/rdoctask'
+end  
 desc 'Generate documentation for Wrest'
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
@@ -62,12 +67,11 @@ begin
     gemspec.homepage = "http://github.com/kaiwren/wrest"
     gemspec.has_rdoc = true
     gemspec.rubyforge_project = 'wrest'
-    gemspec.executables = ['wrest']
+    gemspec.executables = ['wrest', 'jwrest']
     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('xml-simple', '>= 1.0.11')
+    gemspec.add_dependency('activesupport', '>= 2.3.2')
     case RUBY_PLATFORM
     when /java/
       gemspec.add_dependency('json-jruby', '>= 1.1.3')  

data/VERSION.yml

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

data/lib/wrest.rb

@@ -7,6 +7,8 @@
 # See the License for the specific language governing permissions and limitations under the License. 
 
 require 'rubygems'
+gem 'activesupport', '>= 2.3.2'
+
 require 'net/http'
 require 'net/https'
 require 'forwardable'
@@ -19,7 +21,7 @@ require 'active_support'
 
 WREST_ROOT = File.dirname(__FILE__)
 
-module Wrest
+module Wrest  #:nodoc:
   def self.logger=(logger)
     @logger = logger
   end
@@ -29,9 +31,16 @@ module Wrest
   end
 end
 
-Wrest.logger = Logger.new(STDOUT)
+Wrest.logger = ActiveSupport::BufferedLogger.new(STDOUT)
 Wrest.logger.level = Logger::DEBUG
 
+begin
+  gem 'libxml-ruby', '>= 1.1.3'
+  ActiveSupport::XmlMini.backend='LibXML'
+rescue Gem::LoadError
+  Wrest.logger.warn "LibXML >= 1.1.3 not found, falling back to #{ActiveSupport::XmlMini.backend}. To install LibXML run `sudo gem install ruby-libxml`"
+end
+
 source_dirs = ["/wrest/core_ext/*.rb", "/wrest/*.rb"]
 
 source_dirs.each{|directory|

data/lib/wrest/components.rb

@@ -7,7 +7,7 @@
 # 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:
+module Wrest
   # A component is a building block that can
   # be used while building an object oriented wrapper
   # around a REST service
@@ -15,7 +15,6 @@ module Wrest #:nodoc:
   end
 end
 
-require "#{WREST_ROOT}/wrest/components/typecast_helpers"
 require "#{WREST_ROOT}/wrest/components/attributes_container"
 require "#{WREST_ROOT}/wrest/components/mutators"
 require "#{WREST_ROOT}/wrest/components/translators"

data/lib/wrest/components/attributes_container.rb

@@ -7,16 +7,23 @@
 # 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::Components #:nodoc:
+module Wrest
+  module Components::AttributesContainer
+  end
+end
+
+require "#{WREST_ROOT}/wrest/components/attributes_container/typecaster"
+
+module Wrest::Components
 
   # Adds behaviour allowing a class to
   # contain attributes and providing support
   # for dynamic getters, setters and query methods.
   # These methods are added at runtime, on the first
-  # invocation and on a per instance basis.   
-  # <tt>respond_to?</tt> however will respond as though 
+  # invocation and on a per instance basis.
+  # <tt>respond_to?</tt> however will respond as though
   # they are all already present.
-  # This means that two different instances of the same 
+  # This means that two different instances of the same
   # AttributesContainer could well have
   # different attribute getters/setters/query methods.
   #
@@ -30,99 +37,60 @@ module Wrest::Components #:nodoc:
   # In situations where this is a problem, such as a client consuming Rails
   # REST services where <tt>id</tt> is a common attribute and clashes with
   # Object#id, it is recommended to create getter/setter/query methods
-  # on the class (which affects all instances) using the +has_attributes+ macro. 
+  # on the class (which affects all instances) using the +always_has+ macro.
   #
   # If you're implementing your own initialize method
-  # remember to delegate to the default initialize 
+  # remember to delegate to the default initialize
   # of AttributesContainer by invoking <tt>super(attributes)</tt>
   #
   # Example:
   #  class ShenCoin
   #    include Wrest::Components::AttributesContainer
+  #    include Wrest::Components::AttributesContainer::Typecaster
   #
-  #    has_attributes  :id
-  #    typecast        :id => as_integer
-  #  end 
+  #    always_has   :id
+  #    typecast         :id   =>  as_integer
+  #  end
   #  coin = ShenCoin.new(:id => '5', :chi_count => 500, :owner => 'Kai Wren')
   #  coin.id    # => 5
   #  coin.owner # => 'Kai Wren'
   module AttributesContainer
     def self.included(klass) #:nodoc:
       klass.extend AttributesContainer::ClassMethods
-      klass.extend TypecastHelpers
       klass.class_eval{ include AttributesContainer::InstanceMethods }
     end
-    
+
     def self.build_attribute_getter(attribute_name) #:nodoc:
       "def #{attribute_name};@attributes[:#{attribute_name}];end;"
     end
-    
+
     def self.build_attribute_setter(attribute_name) #:nodoc:
       "def #{attribute_name}=(value);@attributes[:#{attribute_name}] = value;end;"
     end
-    
+
     def self.build_attribute_queryer(attribute_name) #:nodoc:
       "def #{attribute_name}?;not @attributes[:#{attribute_name}].nil?;end;"
     end
-    
+
     module ClassMethods
       # This macro explicitly creates getter, setter and query methods on
-      # a class, overriding any exisiting methods with the same names. 
+      # a class, overriding any exisiting methods with the same names.
       # This can be used when attribute names clash with method names;
       # an example would be Rails REST services which frequently make use
       # an attribute named <tt>id</tt> which clashes with Object#id. Also,
       # this can be used as a performance optimisation if the incoming
       # attributes are known beforehand.
-      def has_attributes(*attribute_names)
+      def always_has(*attribute_names)
         attribute_names.each do |attribute_name|
           self.class_eval(
-            AttributesContainer.build_attribute_getter(attribute_name) +
-            AttributesContainer.build_attribute_setter(attribute_name) +
-            AttributesContainer.build_attribute_queryer(attribute_name)
-          ) 
+          AttributesContainer.build_attribute_getter(attribute_name) +
+          AttributesContainer.build_attribute_setter(attribute_name) +
+          AttributesContainer.build_attribute_queryer(attribute_name)
+          )
         end
       end
-      
-      # Accepts a set of attribute-name/lambda pairs which are used
-      # to typecast string values injected through the constructor.
-      # Typically needed when populating an +AttributesContainer+
-      # directly from request params. Typecasting kicks in for
-      # a given value _only_ if it is a string.
-      #
-      # Typcast information is inherited by subclasses; however be
-      # aware that explicitly invoking +typecast+ in a subclass will
-      # discard inherited typecast information leaving only the casts
-      # defined in the subclass.
-      #
-      # Common typecasts such as integer, float, datetime etc. are
-      # available through predefined helpers. See TypecastHelpers
-      # for a full list.
-      #
-      # Example:
-      #
-      #  class Demon
-      #    include Wrest::Components::AttributesContainer
-      #    typecast :age  =>  as_integer,
-      #             :chi  =>  lambda{|chi| Chi.new(chi)}  
-      #  end
-      #  kai_wren = Demon.new('age' => '1500', 'chi' => '1024')
-      #  kai_wren.age # => 1500   
-      #  kai_wren.chi # => #<Chi:0x113af8c @count="1024">   
-      def typecast(cast_map)
-        @typecast_map = @typecast_map ? @typecast_map.merge(cast_map.symbolize_keys) : cast_map.symbolize_keys
-      end
-      
-      def typecast_map #:nodoc:
-        if defined?(@typecast_map)
-          @typecast_map
-        elsif superclass != Object && superclass.respond_to?(:typecast_map)
-          superclass.typecast_map
-        else
-          {}  
-        end
-      end  
     end
-       
+
     module InstanceMethods
       # Sets up any class to act like
       # an attributes container by creating
@@ -132,22 +100,18 @@ module Wrest::Components #:nodoc:
       # own class.
       def initialize(attributes = {})
         @attributes = attributes.symbolize_keys
-        self.class.typecast_map.each do |key, typecaster|
-          value = @attributes[key]
-          @attributes[key] = typecaster.call(value) if value.is_a?(String)
-        end
         @interface = Module.new
         self.extend @interface
       end
-      
+
       def [](key)
         @attributes[key.to_sym]
       end
-      
+
       def []=(key, value)
         @attributes[key.to_sym] = value
       end
-      
+
       def respond_to?(method_name, include_private = false)
         super(method_name, include_private) ? true : @attributes.include?(method_name.to_s.gsub(/(\?$)|(=$)/, '').to_sym)
       end
@@ -157,7 +121,6 @@ module Wrest::Components #:nodoc:
       def method_missing(method_sym, *arguments)
         method_name = method_sym.to_s
         attribute_name = method_name.gsub(/(\?$)|(=$)/, '')
-
         if @attributes.include?(attribute_name.to_sym) || method_name.last == '='
           case method_name.last
           when '='
@@ -172,7 +135,6 @@ module Wrest::Components #:nodoc:
           super(method_sym, *arguments)
         end
       end
-      
     end
   end
 end

data/lib/wrest/components/attributes_container/typecaster.rb

@@ -0,0 +1,121 @@
+# 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 Components::AttributesContainer
+    # An extension to AttributesContainer that adds support for
+    # specifying how the values associated with certain attribute keys
+    # should be typecast.
+    #
+    # This extension can be used in situations where the attributes
+    # hash consists of just strings with no associated tup information.
+    # For example, params recieved from a web browser may contain
+    # attributes like
+    #  'id' => '4', 'dateofbirth' => '1984-04-05'
+    # and we'd like to have these cast to an integer and a date
+    # respectively, rather than have to deal with them as strings.
+    module Typecaster
+      def self.included(klass) #:nodoc:
+        klass.extend Typecaster::ClassMethods
+        klass.class_eval{ include Typecaster::InstanceMethods }
+        klass.alias_method_chain  :initialize,  :typecasting
+      end
+
+      module ClassMethods
+        # Accepts a set of attribute-name/lambda pairs which are used
+        # to typecast string values injected through the constructor.
+        # Typically needed when populating an +AttributesContainer+
+        # directly from request params. Typecasting kicks in for
+        # a given value _only_ if it is a string.
+        #
+        # Typecast information is inherited by subclasses; however be
+        # aware that explicitly invoking +typecast+ in a subclass will
+        # discard inherited typecast information leaving only the casts
+        # defined in the subclass.
+        #
+        # Common typecasts such as integer, float, datetime etc. are
+        # available through predefined helpers. See TypecastHelpers
+        # for a full list.
+        #
+        # Example:
+        #
+        #  class Demon
+        #    include Wrest::Components::AttributesContainer
+        #    include Wrest::Components::AttributesContainer::Typecaster
+        #
+        #    typecast         :age          =>  as_integer,
+        #                     :chi          =>  lambda{|chi| Chi.new(chi)}
+        #  end
+        #
+        #  kai_wren = Demon.new('age' => '1500', 'chi' => '1024')
+        #  kai_wren.age           # => 1500
+        #  kai_wren.chi           # => #<Chi:0x113af8c @count="1024">
+        def typecast(cast_map)
+          @typecast_map = @typecast_map ? @typecast_map.merge(cast_map.symbolize_keys) : cast_map.symbolize_keys
+        end
+
+        def typecast_map #:nodoc:
+          if defined?(@typecast_map)
+            @typecast_map
+          elsif superclass != Object && superclass.respond_to?(:typecast_map)
+            superclass.typecast_map
+          else
+            {}
+          end
+        end
+
+        def as_base64Binary
+          ActiveSupport::CoreExtensions::Hash::Conversions::XML_PARSING['base64Binary']
+        end
+
+        def as_boolean
+          ActiveSupport::CoreExtensions::Hash::Conversions::XML_PARSING['boolean']
+        end
+
+        def as_decimal
+          ActiveSupport::CoreExtensions::Hash::Conversions::XML_PARSING['decimal']
+        end
+
+        def as_date
+          ActiveSupport::CoreExtensions::Hash::Conversions::XML_PARSING['date']
+        end
+
+        def as_datetime
+          ActiveSupport::CoreExtensions::Hash::Conversions::XML_PARSING['datetime']
+        end
+
+        def as_float
+          ActiveSupport::CoreExtensions::Hash::Conversions::XML_PARSING['float']
+        end
+
+        def as_integer
+          ActiveSupport::CoreExtensions::Hash::Conversions::XML_PARSING['integer']
+        end
+
+        def as_symbol
+          ActiveSupport::CoreExtensions::Hash::Conversions::XML_PARSING['symbol']
+        end
+
+        def as_yaml
+          ActiveSupport::CoreExtensions::Hash::Conversions::XML_PARSING['yaml']
+        end
+      end
+
+      module InstanceMethods # :nodoc:
+        def initialize_with_typecasting(attributes = {}) # :nodoc:
+          initialize_without_typecasting(attributes)
+          self.class.typecast_map.each do |key, typecaster|
+            value = @attributes[key]
+            @attributes[key] = typecaster.call(value) if value.is_a?(String)
+          end
+        end
+      end
+    end
+  end
+end