carrierwave 0.1 → 0.2.0

data/lib/carrierwave/storage/abstract.rb

@@ -1,5 +1,6 @@
 module CarrierWave
   module Storage
+
     ##
     # This file serves mostly as a specification for Storage engines. There is no requirement
     # that storage engines must be a subclass of this class. However, any storage engine must
@@ -26,10 +27,14 @@ module CarrierWave
       ##
       # Do something to store the file
       #
-      # @param [CarrierWave::Uploader] uploader an uploader object
-      # @param [CarrierWave::SanitizedFile] file the file to store
+      # === Parameters
+      #
+      # [uploader (CarrierWave::Uploader)] an uploader object
+      # [file (CarrierWave::SanitizedFile)] the file to store
       #
-      # @return [#identifier] an object
+      # === Returns
+      #
+      # [#identifier] an object
       #
       def self.store!(uploader, file)
         self.new
@@ -37,10 +42,14 @@ module CarrierWave
       
       # Do something to retrieve the file
       #
-      # @param [CarrierWave::Uploader] uploader an uploader object
-      # @param [String] identifier uniquely identifies the file
+      # === Parameters
+      #
+      # [uploader (CarrierWave::Uploader)] an uploader object
+      # [identifier (String)] uniquely identifies the file
       #
-      # @return [#identifier] an object
+      # === Returns
+      #
+      # [#identifier] an object
       #
       def self.retrieve!(uploader, identifier)
         self.new
@@ -52,7 +61,9 @@ module CarrierWave
       #
       # This is OPTIONAL
       #
-      # @return [String] path to the file
+      # === Returns
+      #
+      # [String] path to the file
       #
       def identifier; end
 
@@ -62,7 +73,9 @@ module CarrierWave
       #
       # This is OPTIONAL
       #
-      # @return [String] file's url
+      # === Returns
+      #
+      # [String] file's url
       #
       def url; end
       
@@ -71,7 +84,9 @@ module CarrierWave
       #
       # This is OPTIONAL
       #
-      # @return [String] path to the file
+      # === Returns
+      #
+      # [String] path to the file
       #
       def path; end
       

data/lib/carrierwave/storage/file.rb

@@ -1,5 +1,11 @@
 module CarrierWave
   module Storage
+
+    ##
+    # File storage stores file to the Filesystem (surprising, no?). There's really not much
+    # to it, it uses the store_dir defined on the uploader as the storage location. That's
+    # pretty much it.
+    #
     class File < Abstract
       
       def initialize(uploader)
@@ -9,28 +15,36 @@ module CarrierWave
       ##
       # Move the file to the uploader's store path.
       #
-      # @param [CarrierWave::Uploader] uploader an uploader object
-      # @param [CarrierWave::SanitizedFile] file the file to store
+      # === Parameters
       #
-      # @return [CarrierWave::SanitizedFile] a sanitized file
+      # [uploader (CarrierWave::Uploader)] an uploader object
+      # [file (CarrierWave::SanitizedFile)] the file to store
+      #
+      # === Returns
+      #
+      # [CarrierWave::SanitizedFile] a sanitized file
       #
       def self.store!(uploader, file)
-        path = ::File.join(uploader.store_dir, uploader.filename)
+        path = ::File.join(uploader.store_path)
         path = ::File.expand_path(path, uploader.public)
-        file.move_to(path)
+        file.move_to(path, CarrierWave.config[:permissions])
         file
       end
       
       ##
       # Retrieve the file from its store path
       #
-      # @param [CarrierWave::Uploader] uploader an uploader object
-      # @param [String] identifier the filename of the file
+      # === Parameters
+      #
+      # [uploader (CarrierWave::Uploader)] an uploader object
+      # [identifier (String)] the filename of the file
+      #
+      # === Returns
       #
-      # @return [CarrierWave::SanitizedFile] a sanitized file
+      # [CarrierWave::SanitizedFile] a sanitized file
       #
       def self.retrieve!(uploader, identifier)
-        path = ::File.join(uploader.store_dir, identifier)
+        path = ::File.join(uploader.store_path(identifier))
         path = ::File.expand_path(path, uploader.public)
         CarrierWave::SanitizedFile.new(path)
       end

data/lib/carrierwave/storage/s3.rb

@@ -1,13 +1,36 @@
 module CarrierWave
   module Storage
+
     ##
-    # Uploads things to Amazon S3 webservices
+    # Uploads things to Amazon S3 webservices. It requies the aws/s3 gem. In order for
+    # CarrierWave to connect to Amazon S3, you'll need to specify an access key id, secret key
+    # and bucket
+    #
+    #     CarrierWave.config[:s3][:access_key_id] = "xxxxxx"
+    #     CarrierWave.config[:s3][:secret_access_key] = "xxxxxx"
+    #     CarrierWave.config[:s3][:bucket] = "my_bucket_name"
+    #
+    # You can also set the access policy for the uploaded files:
+    #
+    #     CarrierWave.config[:s3][:access] = :public_read
+    #
+    # Possible values are the 'canned access control policies' provided in the aws/s3 gem,
+    # they are:
+    #
+    # [:private]              No one else has any access rights.
+    # [:public_read]          The anonymous principal is granted READ access.
+    #                         If this policy is used on an object, it can be read from a
+    #                         browser with no authentication.
+    # [:public_read_write]    The anonymous principal is granted READ and WRITE access.
+    # [:authenticated_read]   Any principal authenticated as a registered Amazon S3 user
+    #                         is granted READ access.
+    #
+    # The default is :public_read, it should work in most cases.
     #
     class S3 < Abstract
       
-      def initialize(bucket, store_dir, identifier)
-        @bucket = bucket
-        @store_dir = store_dir
+      def initialize(store_path, identifier)
+        @store_path = store_path
         @identifier = identifier
       end
       
@@ -23,14 +46,18 @@ module CarrierWave
       end
       
       ##
-      # @return [String] the bucket set in the config options
+      # === Returns
+      #
+      # [String] the bucket set in the config options
       # 
       def self.bucket
         CarrierWave.config[:s3][:bucket]
       end
       
       ##
-      # @return [Symbol] the access priviliges the uploaded files should have
+      # === Returns
+      #
+      # [Symbol] the access priviliges the uploaded files should have
       #
       def self.access
         CarrierWave.config[:s3][:access]
@@ -39,14 +66,18 @@ module CarrierWave
       ##
       # Store the file on S3
       #
-      # @param [CarrierWave::Uploader] uploader an uploader object
-      # @param [CarrierWave::SanitizedFile] file the file to store
+      # === Parameters
+      #
+      # [uploader (CarrierWave::Uploader)] an uploader object
+      # [file (CarrierWave::SanitizedFile)] the file to store
       #
-      # @return [#identifier] an object
+      # === Returns
+      #
+      # [CarrierWave::Storage::S3] the stored file
       #
       def self.store!(uploader, file)
-        AWS::S3::S3Object.store(::File.join(uploader.store_dir, uploader.filename), file.read, bucket, :access => access)
-        self.new(bucket, uploader.store_dir, uploader.filename)
+        AWS::S3::S3Object.store(::File.join(uploader.store_path), file.read, bucket, :access => access)
+        self.new(uploader.store_dir, uploader.filename)
       end
       
       # Do something to retrieve the file
@@ -54,28 +85,48 @@ module CarrierWave
       # @param [CarrierWave::Uploader] uploader an uploader object
       # @param [String] identifier uniquely identifies the file
       #
-      # @return [#identifier] an object
+      # [uploader (CarrierWave::Uploader)] an uploader object
+      # [identifier (String)] uniquely identifies the file
+      #
+      # === Returns
+      #
+      # [CarrierWave::Storage::S3] the stored file
       #
       def self.retrieve!(uploader, identifier)
-        self.new(bucket, uploader.store_dir, identifier)
+        self.new(uploader.store_path(identifier), identifier)
       end
       
       ##
       # Returns the filename on S3
       #
-      # @return [String] path to the file
+      # === Returns
+      #
+      # [String] path to the file
       #
       def identifier
         @identifier
       end
 
+      ##
+      # Reads the contents of the file from S3
+      #
+      # === Returns
+      #
+      # [String] contents of the file
+      #
+      def read
+        S3Object.value @store_path, self.class.bucket
+      end
+
       ##
       # Returns the url on Amazon's S3 service
       #
-      # @return [String] file's url
+      # === Returns
+      #
+      # [String] file's url
       #
       def url
-        "http://s3.amazonaws.com/#{self.class.bucket}/#{@store_dir}/#{@identifier}"
+        ["http://s3.amazonaws.com", self.class.bucket, @store_path].compact.join('/')
       end
       
     end # S3

data/lib/carrierwave/test/matchers.rb

@@ -0,0 +1,112 @@
+module CarrierWave
+  module Test
+
+    ##
+    # These are some matchers that can be used in RSpec specs, to simplify the testing
+    # of uploaders.
+    #
+    module Matchers
+
+      class BeIdenticalTo
+        def initialize(expected)
+          @expected = expected
+        end
+        def matches?(actual)
+          @actual = actual
+          FileUtils.identical?(@actual, @expected)
+        end
+        def failure_message
+          "expected #{@actual.inspect} to be identical to #{@expected.inspect}"
+        end
+        def negative_failure_message
+          "expected #{@actual.inspect} to not be identical to #{@expected.inspect}"
+        end
+      end
+
+      def be_identical_to(expected)
+        BeIdenticalTo.new(expected)
+      end
+
+      class HavePermissions
+        def initialize(expected)
+          @expected = expected
+        end
+
+        def matches?(actual)
+          @actual = actual
+          # Satisfy expectation here. Return false or raise an error if it's not met.
+          (File.stat(@actual.path).mode & 0777) == @expected
+        end
+
+        def failure_message
+          "expected #{@actual.inspect} to have permissions #{@expected.to_s(8)}, but they were #{(File.stat(@actual.path).mode & 0777).to_s(8)}"
+        end
+
+        def negative_failure_message
+          "expected #{@actual.inspect} not to have permissions #{@expected.to_s(8)}, but it did"
+        end
+      end
+
+      def have_permissions(expected)
+        HavePermissions.new(expected)
+      end
+
+      class BeNoLargerThan
+        def initialize(width, height)
+          @width, @height = width, height
+        end
+
+        def matches?(actual)
+          @actual = actual
+          # Satisfy expectation here. Return false or raise an error if it's not met.
+          require 'RMagick'
+          img = ::Magick::Image.read(@actual.path).first
+          @actual_width = img.columns
+          @actual_height = img.rows
+          @actual_width <= @width && @actual_height <= @height
+        end
+
+        def failure_message
+          "expected #{@actual.inspect} to be no larger than #{@width} by #{@height}, but it was #{@actual_height} by #{@actual_width}."
+        end
+
+        def negative_failure_message
+          "expected #{@actual.inspect} to be larger than #{@width} by #{@height}, but it wasn't."
+        end
+      end
+
+      def be_no_larger_than(width, height)
+        BeNoLargerThan.new(width, height)
+      end
+
+      class HaveDimensions
+        def initialize(width, height)
+          @width, @height = width, height
+        end
+
+        def matches?(actual)
+          @actual = actual
+          # Satisfy expectation here. Return false or raise an error if it's not met.
+          require 'RMagick'
+          img = ::Magick::Image.read(@actual.path).first
+          @actual_width = img.columns
+          @actual_height = img.rows
+          @actual_width == @width && @actual_height == @height
+        end
+
+        def failure_message
+          "expected #{@actual.inspect} to have an exact size of #{@width} by #{@height}, but it was #{@actual_height} by #{@actual_width}."
+        end
+
+        def negative_failure_message
+          "expected #{@actual.inspect} not to have an exact size of #{@width} by #{@height}, but it did."
+        end
+      end
+
+      def have_dimensions(width, height)
+        HaveDimensions.new(width, height)
+      end
+      
+    end # SpecHelper
+  end # Test
+end # CarrierWave

data/lib/carrierwave/uploader.rb

@@ -1,37 +1,77 @@
 module CarrierWave
-  class Uploader
-  
-    class << self
+
+  ##
+  # An uploader is a class that allows you to easily handle the caching and storage of
+  # uploaded files. Please refer to the README for configuration options.
+  #
+  # Once you have an uploader you can use it in isolation:
+  #
+  #     my_uploader = MyUploader.new
+  #     my_uploader.cache!(File.open(path_to_file))
+  #     my_uploader.retrieve_from_store!('monkey.png')
+  #
+  # Alternatively, you can mount it on an ORM or other persistence layer, with
+  # +CarrierWave::Mount#mount_uploader+. There are extensions for activerecord and datamapper
+  # these are *very* simple (they are only a dozen lines of code), so adding your own should
+  # be trivial.
+  #
+  module Uploader
+
+    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
@@ -48,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!
@@ -57,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)
@@ -85,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
@@ -142,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
@@ -155,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
     #
@@ -171,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
@@ -194,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?
@@ -203,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.
     #
@@ -225,84 +301,126 @@ 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]
     end
-  
+
+    ##
+    # Override this method in your uploader to provide a white list of extensions which
+    # are allowed to be uploaded.
+    #
+    # === 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)
+          raise CarrierWave::IntegrityError, "You are not allowed to upload #{new_file.extension.inspect} files, allowed types: #{extension_white_list.inspect}"
+        end
+
         self.cache_id = CarrierWave::Uploader.generate_cache_id unless cache_id
 
         @file = new_file
 
         @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|
@@ -311,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)
@@ -335,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.
@@ -358,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
@@ -379,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 =~ /^[\d]{8}\-[\d]{4}\-[\d]+\-[\d]{4}$/
+      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-z0-9\.\-\+_]+$/i
+      raise CarrierWave::InvalidParameter, "invalid filename" unless filename =~ /\A[a-z0-9\.\-\+_]+\z/i
       @original_filename = filename
     end
-    
+
   end # Uploader
-end # CarrierWave
+end # CarrierWave