animoto 0.1.1.beta1 → 1.0.0

data/lib/animoto/support/coverable.rb

@@ -19,7 +19,7 @@ module Animoto
     
       # Returns a representation of this visual as a Hash.
       #
-      # @return [Hash<String,Object>] this visual as a Hash
+      # @return [Hash{String=>Object}] this visual as a Hash
       def to_hash
         hash = super rescue {}
         hash['cover'] = cover? unless @cover.nil?

data/lib/animoto/support/dynamic_class_loader.rb

@@ -1,166 +1,107 @@
 module Animoto
   module Support
-
-    # Sets the search path where classes to be dynamically loaded can be found.
-    # This method is meant to be used in the following manner:
-    #   class Thing
-    #     extend Animoto::Support::DynamicClassLoader("some/search/path")
-    #   end
-    # Behind the scenes, this method sets a temporary instance variable on the
-    # DynamicClassLoader module which will be used (and then removed) the next time
-    # the module is extended into a class. Therefore, don't call this method if you
-    # don't intend to immediately extend the DynamicClassLoader module into the class
-    # that the search path given applies to, else strange behaviors could emerge.
-    #
-    # @param [String] search_path the path where classes to be dynamically loaded are located
-    # @return [Module] the DynamicClassLoader module
-    def self.DynamicClassLoader search_path
-      self::DynamicClassLoader.instance_variable_set(:@carryover_search_path, search_path)
-      self::DynamicClassLoader
-    end
-
-    # This module is a helper for families of "plugins" which rely on external libraries.
-    # It loads classes (and therefore their dependencies) on demand, obviating the need
-    # to require every possible plugin dependency all the time or the need for the end-user
-    # to explicitly require which certain plugin they want to use or know anything about the
-    # specific directory structure where plugins are located.
-    #
-    # A class gets dynamically loaded in one of two ways: either a const_missing hook, or by
-    # symbol-reference. Both methods interpolate the name of the file to load based on
-    # their inputs.
-    #
-    # Referencing a class name under a module that is extended by the DynamicClassLoader will
-    # search in the pre-set search path for a file matching the underscored version of the
-    # class' name. For example, assuming the Thing module is extended with DynamicClassLoader
-    # and its search path is "~/.things/plugins", referencing Thing::KlassName will look for
-    # a file called "klass_name.rb" in "~/.things/plugins", returning the class object if it's
-    # found or raising an exception if it isn't.
-    #
-    # Using a symbol reference is a little trickier. When a symbol is given to the [] method,
-    # the name will be transformed (explained later) and a file in the search path with the
-    # transformed name will be loaded, or an exception will be raised if the file isn't found.
-    #
-    # Name transformations are handled by three methods: symbol_reference_prefix,
-    # symbol_reference_transform, and symbol_reference_prefix. As their names suggest,
-    # symbol_reference_prefix and symbol_reference_suffix add the strings returned to the front
-    # or end of the symbol name. symbol_reference_transform takes the string version of the symbol
-    # and applies an arbitrary transform on it.
-    #
-    # After the file matching the transformed name is found, the class itself still has to
-    # get loaded. While it's easy enough to take a class name and produce an associated file name,
-    # the same is not true in reverse (for example, "HTTPEngine" => "http_engine" is straightforward,
-    # but there's not enough information to turn "http_engine" into "HTTPEngine" without enforcing
-    # class-naming restrictions). To get around this, any class that could get dynamically loaded
-    # should add itself to its containing module's adapter map, using a key that matches the class'
-    # file name.
     module DynamicClassLoader
-      
-      # When this module is extended into a class, it will set the search path where
-      # dynamically loaded classes can be found if it was set using the DynamicClassLoader
-      # method (see above). If not search path is set beforehand, it defaults to '.'.
+
+      # Retrieves the adapter class that the name corresponds to. The name in case- and
+      # punctuation-insensitive, meaning "SomeModule", "some_module", and "somemodule"
+      # are all treated as the same.
       #
-      # @param [Class] base the class this module will be extended into
-      # @return [void]
-      def self.extended base
-        if instance_variable_defined?(:@carryover_search_path)
-          base.instance_variable_set(:@dynamic_class_loader_search_path, @carryover_search_path)
-          remove_instance_variable(:@carryover_search_path)
+      # Note that classes defined as an #adapter for this module will be autoloaded upon
+      # successful reference, so there's no need to ensure that the file defining the class
+      # is already loaded when calling this method.
+      #
+      # @param [String] name the name of the module to access
+      # @return [Class] the class
+      # @raise [NameError] if the class doesn't exist.
+      def [] name
+        if klass = adapter_map[normalize_const_name(name)]
+          const_get(klass)
         else
-          base.instance_variable_set(:@dynamic_class_loader_search_path, '.')
+          raise NameError, "uninitialized constant #{self.name}::#{name}"
         end
       end
-    
-      # If a reference is made to a class under this one that hasn't been initialized yet,
-      # this will attempt to require a file with that class' name (underscored). If one is
-      # found, and the file defines the class requested, will return that class object.
-      #
-      # @param [Symbol] const the uninitialized class' name
-      # @return [Class] the class found
-      # @raise [NameError] if the file defining the class isn't found, or if the file required
-      #   doesn't define the class.
-      def const_missing const
-        load_missing_file_named underscore_class_name(const.to_s)
-        const_defined?(const) ? const_get(const) : super
-      end
 
-      # Returns the adapter class for the given symbol. If the file defining the class
-      # hasn't been loaded, will try to load it.
+      private
+
+      # Gets or sets the path where this module will look for files it autoloads.
       #
-      # @param [Symbol] engine the symbolic name of the adapter
-      # @return [Class] the class
-      # @raise [NameError] if the class isn't found
-      def [] engine
-        load_missing_file_named "#{symbol_reference_prefix}#{symbol_reference_transform(engine.to_s)}#{symbol_reference_suffix}"
-        adapter_map[engine]
+      # @param [String] path the path; if path is nil, returns the old path
+      # @return [String] the path
+      def dynamic_class_path path = nil
+        @dynamic_class_path = path if path
+        @dynamic_class_path
       end
 
-      private
-      
-      # When a class is loaded by symbol reference, the return value of this method
-      # will be prepended to the symbol to form the file name. Defaults to a blank
-      # string.
+      # A map of normalized class names to the actual class names.
       #
-      # @return [String] the prefix
-      def symbol_reference_prefix
-        ''
+      # @return [Hash{String=>Symbol}] the map
+      def adapter_map
+        @adapter_map ||= {}
       end
-      
-      # When a class is loaded by symbol reference, the return value of this method
-      # will replace the symbol that was passed in. Defaults to return the symbol
-      # unchanged.
-      # Note, the word 'symbol' is used, but in reality it's a String and won't need
-      # typecasting.
+
+      # Declare a class as an 'adapter' for this module. Given a name, for example
+      # "ChunkyBacon", it will expect the adapter class to be called ChunkyBaconAdapter
+      # and be defined in "chunky_bacon_adapter.rb" in this module's #dynamic_class_path.
       #
-      # @param [String] name the symbol referencing the class to load
-      # @return [String] the transformed symbol
-      def symbol_reference_transform name
-        name
-      end
-      
-      # When a class is loaded by symbol reference, the return value of this method
-      # will be appended to the symbol to form the file name. Defaults to '_adapter'.
+      # Once a class is declared as an adapter, will set this module to autoload the
+      # file on first reference, and sets a key in the #adapter_map mapping the normalized
+      # name of the adapter (in the case of ChunkyBaconAdapter, the normalized name is
+      # "chunkybacon").
       #
-      # @return [String] the suffix
-      def symbol_reference_suffix
-        '_adapter'
-      end
-      
-      # Requires the file in the search path with the given name (minus trailing '.rb').
+      # The class can be accessed by its normalized name through the #[] method, or simply
+      # referenced directly through a #const_missing hook. Using #const_missing will normalize
+      # the name of the constant and look it up in the #adapter_map, so capitalization (or even
+      # punctuation) need not be exact.
       #
-      # @param [String] name the name of the file
+      # @example Setting up a module and a dynamically-loaded adapter
+      #   module FunderfulWonderment
+      #     extend Animoto::Support::DynamicClassLoader
+      #     adapter 'ChunkyBacon'
+      #   end
+      # 
+      # Any reference to FunderfulWonderment::ChunkyBaconAdapter will autoload the class file
+      # and return the ChunkyBaconAdapter. As will FunderfulWonderment::Chunky_bacon_ADAPTER or
+      # any other name whose normalized name maps to "chunkybacon".
+      # 
+      # @param [String] name the name of the adapter class, minus the word "Adapter" at the end.
       # @return [void]
-      # @raise [NameError] if the file isn't found
-      def load_missing_file_named name
-        require "#{search_path}/#{name}.rb"
-      rescue LoadError
-        raise NameError, "Couldn't locate adapter named \"#{name}\""
+      # @see #[]
+      # @see #const_missing
+      def adapter name
+        klass_name = :"#{name}Adapter"
+        klass_file = klass_name.to_s.underscore
+        self.autoload klass_name, "#{dynamic_class_path}/#{klass_file}"
+        adapter_map[normalize_const_name(klass_file)] = klass_name
       end
-      
-      # Returns the path where dynamically loaded files can be found. Defaults to '.' or
-      # whatever was declared as the search path when this module was extended. The path
-      # should not end with a trailing slash.
+    
+      # Normalizes the name of the missing constant and tries to look it up in the #adapter_map.
       #
-      # @return [String] the path
-      def search_path
-        @dynamic_class_loader_search_path
+      # @param [Symbol] name the name of the constant, as a symbol
+      # @return [Class] the class the name corresponds to
+      # @raise [NameError] if the class can't be found
+      def const_missing name
+        if klass_name = adapter_map[normalize_const_name(name)]
+          klass = const_get(klass_name)
+          const_set name, klass
+          klass
+        end
+      rescue NameError
+        super
       end
 
-      # Returns a Hash mapping the symbolic names for adapters to their classes.
+      # Normalizes a constant name by downcasing it, stripping off the trailing word
+      # 'adapter', and removing all non-letter characters. Note that the name should
+      # be a valid Ruby constant name.
       #
-      # @return [Hash<Symbol,Class>] the map of adapters
-      def adapter_map
-        @adapter_map ||= {}
-      end
-
-      # Turns a camel-cased class name into an underscored version. Will only affect the base name
-      # of the class, so, for example, Animoto::DirectingAndRenderingJob becomes 'directing_and_rendering_job'
+      # @example
+      #   normalize_const_name(:ChunkyBaconAdapter) # => "chunkybacon"
       #
-      # @param [Class,String] klass a class or name of a class
-      # @return [String] the underscored version of the name
-      def underscore_class_name klass
-        klass_name = klass.is_a?(Class) ? klass.name.split('::').last : klass
-        klass_name.gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').gsub(/([a-z\d])([A-Z])/,'\1_\2').downcase
+      # @param [String, Symbol] name the name of the class as a String or Symbol
+      # @return [String] the normalized name
+      def normalize_const_name name
+        name.to_s.downcase[/^([\w_]+?)(?:_?adapter)?$/,1].gsub(/[^a-z]/,'')
       end
+
     end
-  end
-end
+  end 
+end

data/lib/animoto/support/errors.rb

@@ -2,4 +2,8 @@ module Animoto
   # This is the base class that all Animoto-specific errors descend from.
   class Error < StandardError
   end
+
+  # Raised when an abstract method is called.
+  class AbstractMethodError < Animoto::Error
+  end
 end

data/lib/animoto/support/hash.rb

@@ -0,0 +1,25 @@
+module Animoto
+  module Support
+    module Hash
+      
+      # Returns a new hash with only the listed keys from this hash.
+      #
+      # @param [Array<Object>] keys the keys to include
+      # @return [Hash{Object=>Object}] a new hash with only the listed keys
+      def only *keys
+        self.delete_if { |k,v| !keys.include?(k) }
+      end
+      
+      # Returns a new hash with all keys from this hash except the listed ones.
+      #
+      # @param [Array<Object>] keys the keys to exclude
+      # @return [Hash{Object=>Object}] a new hash without the listed keys
+      def except *keys
+        self.delete_if { |k,v| keys.include?(v) }
+      end
+      
+    end
+  end
+end
+
+Hash.__send__ :include, Animoto::Support::Hash

data/lib/animoto/support/standard_envelope.rb

@@ -4,6 +4,9 @@ module Animoto
     
       # When included into a class, also extends ClassMethods, inludes InstanceMethods, and
       # includes Support::ContentType
+      #
+      # @param [Module] base the module this is being included into
+      # @return [void]
       def self.included base
         base.class_eval {
           include Animoto::Support::StandardEnvelope::InstanceMethods
@@ -11,12 +14,31 @@ module Animoto
           include Animoto::Support::ContentType
         }
       end
+      
+      # Scans the structure of a standard envelope for the 'payload key' and tries to find
+      # the matching class for that key. Returns nil if the class isn't found (instead of,
+      # say, raising a NameError).
+      #
+      # @param [Hash{String=>Object}] envelope a 'standard envelope' hash
+      # @return [Class, nil] the class, or nil if either the payload key or the class couldn't be found
+      def self.find_class_for envelope
+        if payload_key = ((envelope['response'] || {})['payload'] || {}).keys.first
+          klass_name = payload_key.camelize
+          if /(?:Job|Callback)$/ === klass_name
+            Animoto::Jobs::const_get(klass_name) if Animoto::Jobs::const_defined?(klass_name)
+          else
+            Animoto::Resources::const_get(klass_name) if Animoto::Resources::const_defined?(klass_name)
+          end
+        end
+      rescue NameError
+        nil
+      end
     
       module InstanceMethods
         # Calls the class-level unpack_standard_envelope method.
-        # @return [Hash<Symbol,Object>]
+        # @return [Hash{Symbol=>Object}]
         # @see Animoto::Support::StandardEnvelope::ClassMethods#unpack_standard_envelope
-        def unpack_standard_envelope body = {}
+        def unpack_standard_envelope body
           self.class.unpack_standard_envelope body
         end
 
@@ -30,18 +52,14 @@ module Animoto
       end
     
       module ClassMethods
-        # @overload payload_key(key)
-        #   Sets the payload key for this class. When building an instance of this class from
-        #   a response body, the payload key determines which object in the response payload
-        #   holds the attributes for the instance.
+        
+        # Get or set the payload key for this class. When building an instance of this
+        # class from a response body, the payload key determines which object in the
+        # response payload holds the attributes for the instance.
         #
-        #   @param [String] key the key to set
-        #   @return [String] the key
-        #   
-        # @overload payload_key()
-        #   Returns the payload key for this class.
-        #
-        #   @return [String] the key
+        # @param [String, nil] key the key to set
+        # @return [String] the payload key (the old key if no argument was given), or
+        #   the inferred payload key if not set
         def payload_key key = nil
           @payload_key = key if key
           @payload_key || infer_content_type
@@ -49,17 +67,50 @@ module Animoto
 
         protected        
 
+        # Extracts the base payload element from the envelope.
+        #
+        # @param [Hash{String=>Object}] body the response body
+        # @return [Hash{String=>Object}] the base payload at $.response.payload
+        def unpack_base_payload body
+          (body['response'] || {})['payload'] || {}
+        end
+        
+        # Extracts the base status element from the envelope.
+        #
+        # @param [Hash{String=>Object}] body the response body
+        # @return [Hash{String=>Object}] the status element at $.response.status
+        def unpack_status body
+          (body['response'] || {})['status'] || {}
+        end
+
+        # Returns the payload, which is the part of the response classes will find the most
+        # interesting.
+        #
+        # @param [Hash{String=>Object}] body the response body
+        # @return [Hash{String=>Object}] the payload at $.response.payload[payload_key]
+        def unpack_payload body
+          unpack_base_payload(body)[payload_key] || {}
+        end
+        
+        # Returns the links element of the payload, or an empty hash if it doesn't exist.
+        # 
+        # @param [Hash{String=>Object}] body the response body
+        # @return [Hash{String=>Object}] the links at $.response.payload[payload_key].links
+        def unpack_links body
+          unpack_payload(body)['links'] || {}
+        end
+
         # Extracts common elements from the 'standard envelope' and returns them in a
         # easier-to-work-with hash.
         #
-        # @param [Hash<String,Object>] body the body, structured in the 'standard envelope'
-        # @return [Hash<Symbol,Object>] the nicer hash
-        def unpack_standard_envelope body = {}
+        # @param [Hash{String=>Object}] body the body, structured in the 'standard envelope'
+        # @return [Hash{Symbol=>Object}] the nicer hash
+        def unpack_standard_envelope body
           {
-            :url => body['response']['payload'][payload_key]['links']['self'],
-            :errors => body['response']['status'] ? (body['response']['status']['errors'] || []) : []
+            :url    => unpack_links(body)['self'],
+            :errors => unpack_status(body)['errors'] || []
           }
-        end
+        end        
       end
     end
   end

data/lib/animoto/support/string.rb

@@ -0,0 +1,31 @@
+module Animoto
+  module Support
+    module String
+      
+      # Transforms this string from underscore-form to camel case. Capitalizes
+      # the first letter.
+      #
+      # @example
+      #   "this_is_a_underscored_string" # => "ThisIsAUnderscoredString"
+      #
+      # @return [String] the camel case form of this string
+      def camelize
+        self.gsub(/(?:^|_)(.)/) { $1.upcase }
+      end
+      
+      # Transforms this string from camel case to underscore-form. Downcases the
+      # entire string.
+      #
+      # @example
+      #   "ThisIsACamelCasedString" # => "this_is_a_camel_cased_string"
+      #
+      # @return [String] the underscored form of this string
+      def underscore
+        self.gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').gsub(/([a-z\d])([A-Z])/,'\1_\2').downcase
+      end
+      
+    end
+  end
+end
+
+String.__send__ :include, Animoto::Support::String