wrest 0.0.5 → 0.0.6

data/bin/wrest_shell.rb

@@ -0,0 +1,21 @@
+puts "Ruby #{RUBY_VERSION}, #{RUBY_RELEASE_DATE}, #{RUBY_PLATFORM}"
+
+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/components.rb

@@ -15,4 +15,7 @@ module Wrest #:nodoc:
   end
 end
 
-require "#{WREST_ROOT}/wrest/components/attributes_container"
+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

@@ -17,26 +17,39 @@ module Wrest::Components #:nodoc:
   # <tt>respond_to?</tt> however will respond as though 
   # they are all already present.
   # This means that two different instances of the same 
-  # <tt>AttributesContainer</tt> could well have
+  # AttributesContainer could well have
   # different attribute getters/setters/query methods.
-  # 
-  # Note that this means the first call to a particular
+  #
+  # Note that the first call to a particular getter/setter/query
   # method will be slower because the method is defined
   # at that point; subsequent calls will be much faster.
   #
-  # If you're implementing your own initialize method
-  # remember to delegate to the default initialize 
-  # of AttributesContainer by invoking <tt>super(attributes)</tt>
   # Also keep in mind that attribute getter/setter/query methods
   # will _not_ override any existing methods on the class.
   #
   # 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 <tt>has_attributes</tt> macro.
+  # Object#id, it is recommended to create getter/setter/query methods
+  # on the class (which affects all instances) using the +has_attributes+ macro. 
+  #
+  # If you're implementing your own initialize method
+  # remember to delegate to the default initialize 
+  # of AttributesContainer by invoking <tt>super(attributes)</tt>
+  #
+  # Example:
+  #  class ShenCoin
+  #    include Wrest::Components::AttributesContainer
+  #
+  #    has_attributes  :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
     
@@ -59,8 +72,7 @@ module Wrest::Components #:nodoc:
       # 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, as defining methods on the first 
-      # invocation is no longer necessary.      
+      # attributes are known beforehand.
       def has_attributes(*attribute_names)
         attribute_names.each do |attribute_name|
           self.class_eval(
@@ -70,6 +82,45 @@ module Wrest::Components #:nodoc:
           ) 
         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
@@ -81,6 +132,10 @@ 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

data/lib/wrest/{translators/xml.rb → components/mutators.rb}

@@ -7,18 +7,16 @@
 # 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 'xmlsimple'
-
-module Wrest 
-  module Translators
-    # Knows how to deserialise xml.
-    # Depends on the xmlsimple gem.
-    Xml = lambda{|response|
-        XmlSimple.xml_in(
-          response.body,
-          'keeproot'  => true
-        )
-    }
+module Wrest #:nodoc:
+  module Components
+    # A mutator understands how to transform
+    # one tuple(key/value pair) from a hash
+    # into another
+    module Mutators
+    end
   end
 end
-    
+
+require "#{WREST_ROOT}/wrest/components/mutators/base"
+require "#{WREST_ROOT}/wrest/components/mutators/xml_simple_type_caster"
+require "#{WREST_ROOT}/wrest/components/mutators/camel_to_snake_case"

data/lib/wrest/components/mutators/base.rb

@@ -0,0 +1,43 @@
+# 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. 
+
+# This is a base implementation of a
+# hash mutator that ensures that the <tt>mutate</tt> method
+# will chain to the next mutator by using a
+# template method.
+class Wrest::Components::Mutators::Base
+  attr_reader :next_mutator
+    
+  def initialize(next_mutator = nil)
+    @next_mutator = next_mutator
+  end
+  
+  # This is a template method which operates on a tuple (well, pair)
+  # from a hash map and guarantees mutator chaining.
+  #
+  # Iterating over any hash using <tt>each</tt> injects
+  # each key/value pair from the hash in the
+  # form of an array.
+  # This method expects of this form as an argument, i.e.
+  # an array with the structure [:key, :value]
+  #
+  # The implementation of the mutation is achieved by
+  # overriding the <tt>do_mutate</tt> method in a subclass.
+  # Note that failing to do so will result in an exception
+  # at runtime.
+  def mutate(tuple)
+    out_tuple = do_mutate(tuple)
+    next_mutator ? next_mutator.mutate(out_tuple) : out_tuple
+  end
+  
+  protected
+  def do_mutate(tuple)
+    raise Wrest::Exceptions::MethodNotOverriddenException
+  end
+end

data/lib/wrest/components/mutators/camel_to_snake_case.rb

@@ -0,0 +1,20 @@
+# 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::Components
+  class Mutators::CamelToSnakeCase < Mutators::Base
+    # Converts the key to snake case
+    #
+    # Example:
+    #  Mutators::CamelToSnakeCase.new.mutate(['Spirit-Sword', 'true'])  # => ['spirit_sword', 'true']
+    def do_mutate(tuple)
+      [tuple.first.underscore, tuple.last]
+    end
+  end
+end

data/lib/wrest/components/mutators/xml_simple_type_caster.rb

@@ -0,0 +1,35 @@
+# 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.
+
+# This mutator undertands how do type casting
+# using the type data embedded in a hash
+# created by deserialising an xml using
+# xml-simple
+module Wrest::Components
+  class Mutators::XmlSimpleTypeCaster < Mutators::Base
+    def do_mutate(tuple)
+      out_key = tuple.first
+      in_value = tuple.last[0]
+      out_value = in_value
+
+      case in_value
+      when Hash
+        if in_value['nil'] == 'true'
+          out_value = nil
+        elsif in_value.key?('type')
+          out_value = ActiveSupport::CoreExtensions::Hash::Conversions::XML_PARSING[in_value['type']].call(in_value['content'])
+        else
+          out_value = in_value.mutate_using(self)
+        end
+      end
+
+      [out_key, out_value]
+    end
+  end
+end

data/lib/wrest/{translators.rb → components/translators.rb}

@@ -7,20 +7,19 @@
 # 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 Wrest::Components #:nodoc:
   # Contains strategies/lambdas which know how to deserialise
   # different content types.
   module Translators
     # Loads the appropriate desirialisation strategy based on
     # the content type
-    def self.load(content_type)
+    def self.lookup(content_type)
       translator = CONTENT_TYPES[content_type]
-      translator || (raise UnsupportedContentTypeException.new("Unsupported content type #{content_type}"))
+      translator || (raise Wrest::Exceptions::UnsupportedContentTypeException.new("Unsupported content type #{content_type}"))
     end
   end
 end
 
-require "#{WREST_ROOT}/wrest/translators/xml"
-require "#{WREST_ROOT}/wrest/translators/json"
-require "#{WREST_ROOT}/wrest/translators/content_types"
-require "#{WREST_ROOT}/wrest/translators/typed_hash"
+require "#{WREST_ROOT}/wrest/components/translators/xml"
+require "#{WREST_ROOT}/wrest/components/translators/json"
+require "#{WREST_ROOT}/wrest/components/translators/content_types"

data/lib/wrest/{translators → components/translators}/content_types.rb

@@ -7,14 +7,14 @@
 # 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 Wrest::Components 
   module Translators
     # Maps content types to deserialisers
     CONTENT_TYPES = {
-      'application/xml' => Wrest::Translators::Xml,
-      'text/xml' => Wrest::Translators::Xml,
-      'application/json' => Wrest::Translators::Json,
-      'text/javascript' => Wrest::Translators::Json
+      'application/xml' => Wrest::Components::Translators::Xml,
+      'text/xml' => Wrest::Components::Translators::Xml,
+      'application/json' => Wrest::Components::Translators::Json,
+      'text/javascript' => Wrest::Components::Translators::Json
     }
   end
 end

data/lib/wrest/components/translators/json.rb

@@ -0,0 +1,22 @@
+# 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::Components::Translators
+  module Json
+    extend self
+
+    def deserialise(response)
+      ActiveSupport::JSON.decode(response.body)
+    end
+
+    def serialise(hash)
+      ActiveSupport::JSON.encode(hash)
+    end
+  end
+end

data/lib/wrest/components/translators/xml.rb

@@ -0,0 +1,26 @@
+# 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 'xmlsimple'
+
+module Wrest::Components::Translators
+  module Xml
+    extend self
+
+    def deserialise(response)
+      XmlSimple.xml_in(
+      response.body,
+      'keeproot'  => true
+      )
+    end
+
+    def serialise(hash)
+    end
+  end
+end

data/lib/wrest/components/typecast_helpers.rb

@@ -0,0 +1,41 @@
+module Wrest::Components #:nodoc:
+  # Provides helper methods which build lambdas
+  # to cast strings to specific types.
+  module TypecastHelpers
+    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
+end

data/lib/wrest/core_ext/hash.rb

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

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

@@ -0,0 +1,44 @@
+# 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 Hash #:nodoc:
+      # Makes it easier to build other objects from a Hash
+      module Conversions
+
+        # This method accepts a hash mutator (found in Wrest::Compononents)
+        # to build a new hash map by making changes to an existing one.
+        #
+        # No, this method does not mutate the state of the hash it is invoked on, 
+        # but rather builds a new one.
+        #
+        # Yes, the name is misleading in that respect. However, one 
+        # hopes the absence of an exclamation mark will increase clarity.
+        #
+        # Uses include mutating the hash produced by xml-simple
+        # by using the meta data in the hash to type cast values.
+        # 
+        # Example:
+        # "http://search.yahooapis.com/NewsSearchService/V1/newsSearch".to_uri.get(
+        #                           :appid  => 'YahooDemo', 
+        #                           :output => 'xml',
+        #                           :query  => 'India',
+        #                           :results=> '3',
+        #                           :start  => '1'
+        #                         ).deserialise.mutate_using(XmlSimpleTypeCaster.new)
+        def mutate_using(mutator)
+          returning({})do |mutated_hash|
+            self.each{|tuple| mutated_hash.store(*mutator.mutate(tuple))}
+          end
+        end
+      end
+    end
+  end
+end