restful 0.2.20

data/lib/restful/rails.rb

@@ -0,0 +1,22 @@
+module Restful
+  module Rails
+    
+    # sets the hostname for this request in a threadsafe manner. 
+    def self.api_hostname=(hostname)
+      Thread.current[:api_hostname] = hostname
+    end
+    
+    # gets the hostname for the currently running thread. 
+    def self.api_hostname
+      Thread.current[:api_hostname]
+    end
+    
+    #
+    #  Shortcuts past namespaces
+    #
+    def self.tools
+      Restful::Rails::ActiveRecord::MetadataTools::Utils
+    end
+
+  end
+end

data/lib/restful/rails/action_controller.rb

@@ -0,0 +1,14 @@
+module Restful
+  module Rails
+    module ActionController
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    
+      module ClassMethods
+      end
+    end
+  end
+end
+
+ActionController::Base.send :include, Restful::Rails::ActionController

data/lib/restful/rails/active_record/configuration.rb

@@ -0,0 +1,219 @@
+#
+#  Configuration options for restful. 
+#
+module Restful
+  module Rails
+    module ActiveRecord
+      module Utils
+        
+        def self.get_includes(config)
+          if config && config.is_a?(Hash) && config.keys.size == 1 && includes = config[:include] 
+            add_to_whitelist = [*includes].map { |el| el.is_a?(String) ? el.to_sym : el  }
+            return nil, add_to_whitelist
+          else
+            return config, []
+          end
+        end
+        
+        def self.convert_to_single_resource(config_parameter, el)
+          config = if config_parameter
+            returning Configuration::Config.new(config_parameter) do |c|
+              config, includes = Utils.get_includes(config_parameter)
+              c.whitelisted += el.class.restful_config.whitelisted unless config
+              c.whitelisted += includes unless includes.blank?
+            end
+          else
+            el.class.restful_config
+          end
+          
+          Restful::Converters::ActiveRecord.convert(el, config)
+        end  
+      end
+      
+      module Configuration
+        def self.included(base)
+          base.send :class_inheritable_accessor, :restful_config
+          base.restful_config = Config.new
+          base.send :include, ResourceInstanceMethods
+          base.send :include, CommonInstanceMethods
+          base.extend(ClassMethods)
+        end
+        
+        module ClassMethods
+          
+          #
+          #  In the form: 
+          #
+          #    Person.restful_publish(:name, :pets => [:name, :species])
+          #
+          #  If pet already has configured the api with restful_publish, you would
+          #  get the default nested attributes. In the above example, these would be
+          #  overriden. 
+          #
+          def restful_publish(*fieldnames) # declarative setter method
+            self.restful_config = Restful.cfg(*fieldnames)
+          end
+        end
+        
+        module CommonInstanceMethods
+          #
+          #  converts this AR object to an apimodel object. per default, only the
+          #  attributes in self.class.restful_config are shown. this can be overriden
+          #  by passing in something like @pet.to_restful(:name, :species).
+          #
+          def to_restful(config_parameter = nil)
+            config, add_to_whitelist = Utils.get_includes(config_parameter)
+            
+            config ||= self.class.restful_config.clone if self.class.respond_to?(:restful_config)
+            config ||= []
+            
+            if config && !config.is_a?(Config)
+             config = Config.new(config)
+            end
+            
+            if self.class.respond_to?(:restful_config)
+              config.whitelisted = Array.new(self.class.restful_config.whitelisted) if config.whitelisted.empty?
+              config.restful_options.merge! self.class.restful_config.restful_options
+            end
+            
+            config.whitelisted += add_to_whitelist
+            config.whitelisted = config.whitelisted.uniq
+            
+            # array
+            result = if self.is_a?(Array)
+              element_name = if fst = self.first
+                fst.class.respond_to?(:base_class) ? 
+                  fst.class.base_class.to_s.tableize :
+                  fst.class.to_s.pluralize
+              elsif self.respond_to?(:name)
+                self.name
+              else
+                "nil-classes"
+              end
+
+              elements = self.map do |el|
+                raise TypeError.new("Not all array elements respond to #to_restful. ") unless el.respond_to?(:to_restful)
+                
+                Utils.convert_to_single_resource(config_parameter, el)
+              end
+              
+              returning Restful.collection(element_name, elements, :array) do |collection|
+                collection.total_entries = self.total_entries if self.respond_to?(:total_entries)
+              end
+                        
+            elsif self.is_a?(Hash)
+              
+              elements = self.map do |k,v|
+                value = if v.respond_to?(:to_restful) and v.class.respond_to?(:restful_config)
+                  Utils.convert_to_single_resource(config_parameter, v)
+                else
+                  v.respond_to?(:to_restful) ? v.to_restful : v
+                end
+                Restful::ApiModel::Attribute.new(k, value, :map)
+              end
+              
+              map = Restful::ApiModel::Map.new("hash")
+              map.values =  elements
+              map
+            else
+              Restful::Converters::ActiveRecord.convert(self, config)
+            end  
+            
+            result
+          end
+                    
+          # FIXME: read Restful::Serializers::Base.serializers. Load order problems?
+          [:atom_like, :hash, :json, :params, :xml].each do |format|
+            define_method("to_restful_#{ format }") do |*args|
+              self.to_restful(*args).serialize(format)
+            end            
+          end
+        end
+    
+        module ResourceInstanceMethods
+                    
+          # simple method through which a model should know it's own name. override this where necessary. 
+          def restful_url(url_base = Restful::Rails.api_hostname)
+            "#{ url_base }#{ restful_path }"
+          end
+          
+          def restful_path
+            "/#{ self.class.base_class.to_s.tableize }/#{ self.to_param }"
+          end
+        end
+        
+        class Config # configures what attributes are exposed to the api. for a single resource.
+          
+          attr_accessor :whitelisted, :restful_options
+          
+          def initialize(*fields) # set; eg :name, :pets => [:name, :species]
+            @whitelisted, @restful_options = split_into_whitelist_and_restful_options([fields].flatten.compact)
+          end
+
+          def published?(key)
+            @whitelisted.include?(key) || 
+            !!@whitelisted.select { |field| field.is_a?(Hash)  && field.keys.include?(key) }.first ||
+            explicit_include?(key)
+          end
+
+          def expanded?(key, nested = false) # if nothing was set, this defaults to true. 
+            force_expanded?(key) || 
+            (@restful_options[:expansion] != :collapsed && !nested) || 
+            explicit_include?(key)
+          end
+          
+          def explicit_include?(key)
+            [*self.restful_options[:include]].include?(key)            
+          end
+          
+          def force_expanded?(key)
+            force = [*@restful_options[:force_expand]]
+            force.include?(key)
+          end
+
+          def nested?
+            !!restful_options[:nested]
+          end
+
+          def nested(key)
+            definition = @whitelisted.select { |field| field.is_a?(Hash)  && field.keys.include?(key) }.first
+            config = Config.new((definition[key] if definition))
+            config.restful_options[:include] = self.restful_options[:include]
+            config
+          end
+
+          private
+                    
+            def split_into_whitelist_and_restful_options(array)
+              options = {}
+        
+              return array.map do |el|
+                if el.is_a? Hash
+                  el = el.clone
+                  
+                  deleted = {}
+                  if restful_options = el.delete(:restful_options)
+                    deleted.merge! restful_options
+                  end
+                  
+                  if included = el.delete(:include)
+                    deleted[:include] = included
+                  end
+
+                  options.merge!(deleted) if deleted.keys.size > 0
+                  el = nil if el == {}
+                end
+              
+                el
+              end.compact, options
+            end
+            
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Restful::Rails::ActiveRecord::Configuration
+Array.send :include, Restful::Rails::ActiveRecord::Configuration::CommonInstanceMethods
+Hash.send :include, Restful::Rails::ActiveRecord::Configuration::CommonInstanceMethods

data/lib/restful/rails/active_record/metadata_tools.rb

@@ -0,0 +1,102 @@
+#
+#  Handle ActiveRecord associations and such like. 
+#
+module Restful
+  module Rails
+    module ActiveRecord
+      module MetadataTools
+        
+        def self.included(base)
+          base.class_inheritable_accessor :apiable_associations
+          base.class_inheritable_accessor :apiable_association_table
+        
+          base.send :include, InstanceMethods
+          base.extend(ClassMethods)
+        end
+        
+        module ClassMethods
+          
+          def apiable
+            cache_association_restful_url_metadata
+          end
+
+          def cache_association_restful_url_metadata
+            self.apiable_associations ||= (self.reflect_on_all_associations(:belongs_to) + self.reflect_on_all_associations(:has_one)).flatten.uniq
+            self.apiable_association_table ||= self.apiable_associations.inject({}) { |memo, reflection| memo[reflection.primary_key_name] = reflection; memo }
+          end
+          
+          def find_by_restful(id)
+            find(id)
+          end
+        end
+        
+        module InstanceMethods
+          def resolve_association_restful_url(association_key_name)            
+            self.class.cache_association_restful_url_metadata
+
+            if reflection = self.class.apiable_association_table[association_key_name]
+              related_resource = self.send(reflection.name)
+              [Restful::Rails.api_hostname, related_resource.restful_path] if related_resource
+            end
+          end
+        end
+
+        module  Utils
+          
+          # called for nested resources. 
+          def self.expand(resource, config)
+            config.restful_options[:nested] = true
+            resource.to_restful(config)
+          end
+
+          def self.dereference(url)
+            if url
+              regexp = Regexp.new("#{ Restful::Rails.api_hostname }\/(.*)\/(.*)")
+              m, resource, params = *url.match(regexp)
+              resource = if resource && params
+                clazz = resource.try(:singularize).try(:camelize).try(:constantize)
+                clazz.find_by_restful(params) if clazz 
+              end
+
+              resource.id if resource
+            end
+          end
+          
+          # retruns non association / collection attributes. 
+          def self.simple_attributes_on(model)
+            attributes = model.attributes
+            
+            attributes.delete_if do |k, v|
+              model.class.apiable_association_table && model.class.apiable_association_table.keys.include?(k)
+            end
+          end
+          
+          #
+          #  Takes an ar model and a key like :people, and returns an array of resources. 
+          #  
+          #   TODO: don't load the entire association, only the published attributes (with an appropriate :select). 
+          #   TODO: get some pagination in.
+          #
+          def self.convert_collection_to_resources(model, key, config)
+            
+            # load the associated objects.
+            models = model.send(key)
+            
+            # convert them to_restful. 
+            if models
+              [*models].map do |m| 
+                if m.respond_to? :to_restful
+                  expand(m, config)
+                else
+                  raise "Seems as if you want to export the relation #{ key } of an #{ model.class.to_s } object without making #{ key } apiable."
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Restful::Rails::ActiveRecord::MetadataTools

data/lib/restful/serializers/atom_like_serializer.rb

@@ -0,0 +1,51 @@
+require 'restful/serializers/base'
+require 'builder'
+
+#
+#  Converts an APIModel to and from XML. 
+#
+module Restful
+  module Serializers
+    class AtomLikeSerializer < XMLSerializer
+      
+      serializer_name :atom_like
+      
+      protected
+        
+        def root_resource(node)
+          url_base = node.attribute(:base, :xml)
+          me_node = node.delete_element("link[@rel='self']")
+          own_url = me_node.attribute(:href)
+          Restful.resource(node.name, :path => own_url, :base => url_base)
+        end
+      
+        def build_link(el, type)
+          Restful.link(revert_link_name(el.attribute('rel')), nil, el.attribute('href'), type)
+        end
+        
+        def calculate_node_type(el)
+          return :link if el.name.downcase == "link"
+          (el.attributes["type"] || "string").to_sym
+        end
+                
+        def add_link_to(resource, builder, options = {})
+          is_self = !!options[:self]
+          builder.tag!("link", { :href => resource.path, :rel => (is_self ? "self" : resource.name) })
+        end
+        
+        def root_element(resource)
+          decorations = {}
+          
+          unless @nested_root
+            decorations =  { :"xml:base" => Restful::Rails.api_hostname } unless Restful::Rails.api_hostname.blank?
+            @nested_root = true
+          end
+          
+          [resource.name, decorations]
+        end
+        
+        def decorations(value); {}; end
+        def collections_decorations; {}; end                
+    end
+  end
+end

data/lib/restful/serializers/base.rb

@@ -0,0 +1,58 @@
+#
+#  Converts an APIModel to and from a given format.  
+#
+module Restful
+  module Serializers
+    class Base
+      cattr_accessor :serializers
+      
+      def serialize(resource, options = {})
+        raise NotImplementedError.new
+      end
+      
+      def deserialize(resource, options = {})
+        raise NotImplementedError.new        
+      end
+      
+      #
+      #  Grabs a serializer, given...
+      #
+      #    #serialize :xml, Resource.new(:animal => "cow")
+      #
+      def self.serializer(type)
+        serializers[type].new
+      end
+      
+      def self.serializer_name(key)
+        self.serializers ||= {}
+        self.serializers[key] = self
+      end
+      
+      def serialize_attribute(attribute)
+        return formatted_ruby_type(attribute) unless attribute.respond_to?(:value)
+        return nil if attribute.value.blank? && attribute.extended_type != :false_class
+        
+        formatted_ruby_type(attribute.value)
+      end
+      
+      def formatted_ruby_type(obj)
+        case obj
+          when DateTime then obj.xmlschema
+          when Time     then obj.xmlschema
+          when Date     then obj.to_s(:db)
+          else
+            obj
+          end
+      end
+      
+      protected
+        def transform_link_name(name)
+          name.to_s.gsub /_id$/, "-restful-url"
+        end
+      
+        def revert_link_name(name)
+          name.to_s.gsub /-restful-url$/, "_id"
+        end      
+    end
+  end
+end