jnicklas-carrierwave 0.1.1 → 0.2.0

data/lib/carrierwave/uploader.rb

@@ -15,39 +15,63 @@ module CarrierWave
   # these are *very* simple (they are only a dozen lines of code), so adding your own should
   # be trivial.
   #
-  class Uploader
+  module Uploader
 
-    class << self
+    def self.append_features(base) #:nodoc:
+      super
+      base.extend(ClassMethods)
+    end
     
+    ##
+    # Generates a unique cache id for use in the caching system
+    #
+    # === Returns
+    #
+    # [String] a cache id in the format YYYYMMDD-HHMM-PID-RND
+    #
+    def self.generate_cache_id
+      Time.now.strftime('%Y%m%d-%H%M') + '-' + Process.pid.to_s + '-' + ("%04d" % rand(9999))
+    end
+
+    module ClassMethods
+
       ##
-      # Returns a list of processor callbacks which have been declared for this uploader
+      # Lists processor callbacks declared
       #
-      # @return [String] 
+      # === Returns
+      #
+      # [Array[Array[Symbol, Array]]] a list of processor callbacks which have been declared for this uploader
       #
       def processors
         @processors ||= []
       end
-    
+
       ##
       # Adds a processor callback which applies operations as a file is uploaded.
       # The argument may be the name of any method of the uploader, expressed as a symbol,
       # or a list of such methods, or a hash where the key is a method and the value is
       # an array of arguments to call the method with
       #
-      # @param [*Symbol, Hash{Symbol => Array[]}] args
-      # @example
-      #     class MyUploader < CarrierWave::Uploader
+      # === Parameters
+      #
+      # args (*Symbol, Hash{Symbol => Array[]})
+      #
+      # === Examples
+      #
+      #     class MyUploader
+      #       include CarrierWave::Uploader
+      #
       #       process :sepiatone, :vignette
       #       process :scale => [200, 200]
-      #     
+      #
       #       def sepiatone
       #         ...
       #       end
-      #     
+      #
       #       def vignette
       #         ...
       #       end
-      #     
+      #
       #       def scale(height, width)
       #         ...
       #       end
@@ -64,7 +88,7 @@ module CarrierWave
           end
         end
       end
-      
+
       ##
       # Sets the storage engine to be used when storing files with this uploader.
       # Can be any class that implements a #store!(CarrierWave::SanitizedFile) and a #retrieve!
@@ -73,14 +97,21 @@ module CarrierWave
       # to by a symbol, which should be more convenient
       #
       # If no argument is given, it will simply return the currently used storage engine.
-      # 
-      # @param [Symbol, Class] storage The storage engine to use for this uploader
-      # @return [Class] the storage engine to be used with this uploader
-      # @example
+      #
+      # === Parameters
+      #
+      # [storage (Symbol, Class)] The storage engine to use for this uploader
+      #
+      # === Returns
+      #
+      # [Class] the storage engine to be used with this uploader
+      #
+      # === Examples
+      #
       #     storage :file
       #     storage CarrierWave::Storage::File
       #     storage MyCustomStorageEngine
-      # 
+      #
       def storage(storage = nil)
         if storage.is_a?(Symbol)
           @storage = get_storage_by_symbol(storage)
@@ -101,54 +132,54 @@ module CarrierWave
       end
 
       alias_method :storage=, :storage
-      
-      attr_accessor :version_name
+
+      def version_names
+        @version_names ||= []
+      end
 
       ##
       # Adds a new version to this uploader
       #
-      # @param [#to_sym] name name of the version
-      # @param [Proc] &block a block to eval on this version of the uploader
+      # === Parameters
+      #
+      # [name (#to_sym)] name of the version
+      # [&block (Proc)] a block to eval on this version of the uploader
       #
       def version(name, &block)
         name = name.to_sym
-        klass = Class.new(self)
-        klass.version_name = name
-        klass.class_eval(&block) if block
-        versions[name] = klass
-        class_eval <<-RUBY
-          def #{name}
-            versions[:#{name}]
-          end
-        RUBY
+        unless versions[name]
+          versions[name] = Class.new(self)
+          versions[name].version_names.push(*version_names)
+          versions[name].version_names.push(name)
+          class_eval <<-RUBY
+            def #{name}
+              versions[:#{name}]
+            end
+          RUBY
+        end
+        versions[name].class_eval(&block) if block
+        versions[name]
       end
 
       ##
-      # @return [Hash{Symbol => Class}] a list of versions available for this uploader
+      # === Returns
+      #
+      # [Hash{Symbol => Class}] a list of versions available for this uploader
       #
       def versions
         @versions ||= {}
       end
 
-      ##
-      # Generates a unique cache id for use in the caching system
-      #
-      # @return [String] a cache if in the format YYYYMMDD-HHMM-PID-RND
-      #
-      def generate_cache_id
-        Time.now.strftime('%Y%m%d-%H%M') + '-' + Process.pid.to_s + '-' + ("%04d" % rand(9999))
-      end
-    
     private
-    
+
       def get_storage_by_symbol(symbol)
-        CarrierWave.config[:storage_engines][symbol]
+        eval(CarrierWave.config[:storage_engines][symbol])
       end
-    
-    end # class << self
-  
+
+    end # ClassMethods
+
     attr_reader :file, :model, :mounted_as
-    
+
     ##
     # If a model is given as the first parameter, it will stored in the uploader, and
     # available throught +#model+. Likewise, mounted_as stores the name of the column
@@ -158,10 +189,16 @@ module CarrierWave
     # If you do not wish to mount your uploaders with the ORM extensions in -more then you
     # can override this method inside your uploader.
     #
-    # @param [Object] model Any kind of model object
-    # @param [Symbol] mounted_as The name of the column where this uploader is mounted
-    # @example
-    #     class MyUploader < CarrierWave::Uploader
+    # === Parameters
+    #
+    # [model (Object)] Any kind of model object
+    # [mounted_as (Symbol)] The name of the column where this uploader is mounted
+    #
+    # === Examples
+    #
+    #     class MyUploader
+    #       include CarrierWave::Uploader
+    #
     #       def store_dir
     #         File.join('public', 'files', mounted_as, model.permalink)
     #       end
@@ -171,14 +208,16 @@ module CarrierWave
       @model = model
       @mounted_as = mounted_as
     end
-    
+
     ##
-    # @return [Boolean] Whether the uploaded file is blank
+    # === Returns
+    #
+    # [Boolean] Whether the uploaded file is blank
     #
     def blank?
-      !file or file.empty?
+      !file or file.blank?
     end
-    
+
     ##
     # Apply all process callbacks added through CarrierWave.process
     #
@@ -187,18 +226,24 @@ module CarrierWave
         self.send(method, *args)
       end
     end
-    
+
     ##
-    # @return [String] the path where the file is currently located.
+    # === Returns
+    #
+    # [String] the path where the file is currently located.
     #
     def current_path
       file.path if file.respond_to?(:path)
     end
-    
+
+    alias_method :path, :current_path
+
     ##
     # Returns a hash mapping the name of each version of the uploader to an instance of it
     #
-    # @return [Hash{Symbol => CarrierWave::Uploader}] a list of uploader instances
+    # === Returns
+    #
+    # [Hash{Symbol => CarrierWave::Uploader}] a list of uploader instances
     #
     def versions
       return @versions if @versions
@@ -210,7 +255,9 @@ module CarrierWave
     end
 
     ##
-    # @return [String] the location where this file is accessible via a url
+    # === Returns
+    #
+    # [String] the location where this file is accessible via a url
     #
     def url
       if file.respond_to?(:url) and not file.url.blank?
@@ -219,18 +266,31 @@ module CarrierWave
         File.expand_path(current_path).gsub(File.expand_path(public), '')
       end
     end
-    
+
     alias_method :to_s, :url
-    
+
     ##
     # Returns a string that uniquely identifies the last stored file
     #
-    # @return [String] uniquely identifies a file
+    # === Returns
+    #
+    # [String] uniquely identifies a file
     #
     def identifier
       file.identifier if file.respond_to?(:identifier)
     end
-  
+
+    ##
+    # Read the contents of the file
+    #
+    # === Returns
+    #
+    # [String] contents of the file
+    #
+    def read
+      file.read if file.respond_to?(:read)
+    end
+
     ##
     # Override this in your Uploader to change the filename.
     #
@@ -241,28 +301,36 @@ module CarrierWave
     # Do not use the version_name in the filename, as it will prevent versions from being
     # loaded correctly.
     #
-    # @return [String] a filename
+    # === Returns
+    #
+    # [String] a filename
     #
     def filename
       @filename
     end
 
     ##
-    # @return [String] the name of this version of the uploader
+    # === Returns
+    #
+    # [String] the name of this version of the uploader
     #
     def version_name
-      self.class.version_name
+      self.class.version_names.join('_').to_sym unless self.class.version_names.blank?
     end
-    
+
     ##
-    # @return [String] the directory that is the root of the application
+    # === Returns
+    #
+    # [String] the directory that is the root of the application
     #
     def root
       CarrierWave.config[:root]
     end
-    
+
     ##
-    # @return [String] the directory where files will be publically accessible
+    # === Returns
+    #
+    # [String] the directory where files will be publically accessible
     #
     def public
       CarrierWave.config[:public]
@@ -272,55 +340,73 @@ module CarrierWave
     # Override this method in your uploader to provide a white list of extensions which
     # are allowed to be uploaded.
     #
-    # @return [NilClass, Array[String]] a white list of extensions which are allowed to be uploaded
-    # @example
+    # === Returns
+    #
+    # [NilClass, Array[String]] a white list of extensions which are allowed to be uploaded
+    #
+    # === Examples
+    #
     #     def extension_white_list
     #       %w(jpg jpeg gif png)
     #     end
     #
     def extension_white_list; end
-  
+
     ####################
     ## Cache
     ####################
-  
+
     ##
     # Override this in your Uploader to change the directory where files are cached.
     #
-    # @return [String] a directory
+    # === Returns
+    #
+    # [String] a directory
     #
     def cache_dir
       CarrierWave.config[:cache_dir]
     end
-    
+
     ##
     # Returns a String which uniquely identifies the currently cached file for later retrieval
     #
-    # @return [String] a cache name, in the format YYYYMMDD-HHMM-PID-RND/filename.txt
+    # === Returns
+    #
+    # [String] a cache name, in the format YYYYMMDD-HHMM-PID-RND/filename.txt
     #
     def cache_name
       File.join(cache_id, [version_name, original_filename].compact.join('_')) if cache_id and original_filename
     end
-    
+
     ##
     # Caches the given file unless a file has already been cached, stored or retrieved.
     #
-    # @param [File, IOString, Tempfile] new_file any kind of file object
-    # @raise [CarrierWave::FormNotMultipart] if the assigned parameter is a string
+    # === Parameters
+    #
+    # [new_file (File, IOString, Tempfile)] any kind of file object
+    #
+    # === Raises
+    #
+    # [CarrierWave::FormNotMultipart] if the assigned parameter is a string
     #
     def cache(new_file)
       cache!(new_file) unless file
     end
-    
+
     ##
     # Caches the given file. Calls process! to trigger any process callbacks.
     #
-    # @param [File, IOString, Tempfile] new_file any kind of file object
-    # @raise [CarrierWave::FormNotMultipart] if the assigned parameter is a string
+    # === Parameters
+    #
+    # [new_file (File, IOString, Tempfile)] any kind of file object
+    #
+    # === Raises
+    #
+    # [CarrierWave::FormNotMultipart] if the assigned parameter is a string
     #
     def cache!(new_file)
       new_file = CarrierWave::SanitizedFile.new(new_file)
-      raise CarrierWave::FormNotMultipart if new_file.string?
+      raise CarrierWave::FormNotMultipart if new_file.is_path?
 
       unless new_file.empty?
         if extension_white_list and not extension_white_list.include?(new_file.extension.to_s)
@@ -333,8 +419,8 @@ module CarrierWave
 
         @filename = new_file.filename
         self.original_filename = new_file.filename
-      
-        @file = @file.copy_to(cache_path)
+
+        @file = @file.copy_to(cache_path, CarrierWave.config[:permissions])
         process!
 
         versions.each do |name, v|
@@ -343,23 +429,30 @@ module CarrierWave
         end
       end
     end
-    
+
     ##
     # Retrieves the file with the given cache_name from the cache, unless a file has
     # already been cached, stored or retrieved.
     #
-    # @param [String] cache_name uniquely identifies a cache file
+    # === Parameters
+    #
+    # [cache_name (String)] uniquely identifies a cache file
     #
     def retrieve_from_cache(cache_name)
       retrieve_from_cache!(cache_name) unless file
     rescue CarrierWave::InvalidParameter
     end
-    
+
     ##
     # Retrieves the file with the given cache_name from the cache.
     #
-    # @param [String] cache_name uniquely identifies a cache file
-    # @raise [CarrierWave::InvalidParameter] if the cache_name is incorrectly formatted.
+    # === Parameters
+    #
+    # [cache_name (String)] uniquely identifies a cache file
+    #
+    # === Raises
+    #
+    # [CarrierWave::InvalidParameter] if the cache_name is incorrectly formatted.
     #
     def retrieve_from_cache!(cache_name)
       self.cache_id, self.original_filename = cache_name.split('/', 2)
@@ -367,22 +460,40 @@ module CarrierWave
       @file = CarrierWave::SanitizedFile.new(cache_path)
       versions.each { |name, v| v.retrieve_from_cache!(cache_name) }
     end
-    
+
     ####################
     ## STORE
     ####################
-    
+
     ##
     # Override this in your Uploader to change the directory where the file backend stores files.
     #
     # Other backends may or may not use this method, depending on their specific needs.
     #
-    # @return [String] a directory
+    # === Returns
+    #
+    # [String] a directory
     #
     def store_dir
-      [CarrierWave.config[:store_dir], version_name].compact.join(File::Separator)
+      CarrierWave.config[:store_dir]
     end
-    
+
+    ##
+    # Calculates the path where the file should be stored. If +for_file+ is given, it will be
+    # used as the filename, otherwise +CarrierWave::Uploader#filename+ is assumed.
+    #
+    # === Parameters
+    #
+    # [for_file (String)] name of the file <optional>
+    #
+    # === Returns
+    #
+    # [String] the store path
+    #
+    def store_path(for_file=filename)
+      File.join(store_dir, [version_name, for_file].compact.join('_'))
+    end
+
     ##
     # Stores the file by passing it to this Uploader's storage engine, unless a file has
     # already been cached, stored or retrieved.
@@ -390,18 +501,22 @@ module CarrierWave
     # If CarrierWave.config[:use_cache] is true, it will first cache the file
     # and apply any process callbacks before uploading it.
     #
-    # @param [File, IOString, Tempfile] new_file any kind of file object
+    # === Parameters
+    #
+    # [new_file (File, IOString, Tempfile)] any kind of file object
     #
     def store(new_file)
       store!(new_file) unless file
     end
-    
+
     ##
     # Stores the file by passing it to this Uploader's storage engine.
     #
     # If new_file is omitted, a previously cached file will be stored.
     #
-    # @param [File, IOString, Tempfile] new_file any kind of file object
+    # === Parameters
+    #
+    # [new_file (File, IOString, Tempfile)] any kind of file object
     #
     def store!(new_file=nil)
       cache!(new_file) if new_file
@@ -411,49 +526,53 @@ module CarrierWave
         versions.each { |name, v| v.store!(new_file) }
       end
     end
-    
+
     ##
     # Retrieves the file from the storage, unless a file has
     # already been cached, stored or retrieved.
-    # 
-    # @param [String] identifier uniquely identifies the file to retrieve
+    #
+    # === Parameters
+    #
+    # [identifier (String)] uniquely identifies the file to retrieve
     #
     def retrieve_from_store(identifier)
       retrieve_from_store!(identifier) unless file
     rescue CarrierWave::InvalidParameter
     end
-    
+
     ##
     # Retrieves the file from the storage.
-    # 
-    # @param [String] identifier uniquely identifies the file to retrieve
+    #
+    # === Parameters
+    #
+    # [identifier (String)] uniquely identifies the file to retrieve
     #
     def retrieve_from_store!(identifier)
       @file = storage.retrieve!(self, identifier)
       versions.each { |name, v| v.retrieve_from_store!(identifier) }
     end
-    
+
   private
-  
+
     def cache_path
       File.expand_path(File.join(cache_dir, cache_name), public)
     end
-  
+
     def storage
       self.class.storage
     end
-    
+
     attr_reader :cache_id, :original_filename
 
     def cache_id=(cache_id)
       raise CarrierWave::InvalidParameter, "invalid cache id" unless cache_id =~ /\A[\d]{8}\-[\d]{4}\-[\d]+\-[\d]{4}\z/
       @cache_id = cache_id
     end
-    
+
     def original_filename=(filename)
       raise CarrierWave::InvalidParameter, "invalid filename" unless filename =~ /\A[a-z0-9\.\-\+_]+\z/i
       @original_filename = filename
     end
-    
+
   end # Uploader
-end # CarrierWave
+end # CarrierWave