carrierwave 0.5.1 → 0.5.4

data/README.rdoc

@@ -1,22 +1,20 @@
 = CarrierWave
 
-http://carrierwave.rubyforge.org
-
-== Summary
-
 This gem provides a simple and extremely flexible way to upload files from Ruby applications.
 It works well with Rack based web applications, such as Ruby on Rails.
 
-== Description
+== Information
 
-* RDoc Documentation {available at Rubyforge}[http://carrierwave.rubyforge.org/rdoc].
-* Source code {hosted at GitHub}[http://github.com/jnicklas/carrierwave]
-* Please {report any issues}[http://github.com/jnicklas/carrierwave/issues] on GitHub
-* Please direct any questions at the {mailing list}[http://groups.google.com/group/carrierwave]
-* Check out the {example app}[http://github.com/jnicklas/carrierwave-example-app]
-* Instructions for setting up a development environment are at the bottom of this file
+* RDoc documentation {available on RubyDoc.info}[http://rubydoc.info/gems/carrierwave/frames]
+* Source code {available on GitHub}[http://github.com/jnicklas/carrierwave]
+* More information, known limitations, and how-tos {available on the wiki}[https://github.com/jnicklas/carrierwave/wiki]
 
-== Getting Started
+== Getting Help
+
+* Please ask the {Groogle Group}[http://groups.google.com/group/carrierwave] for help if you have any questions.
+* Please report bugs on the {issue tracker}[http://github.com/jnicklas/carrierwave/issues] but read the "getting help" section in the wiki first.
+
+== Installation
 
 Install the latest stable release:
 
@@ -26,12 +24,10 @@ In Rails, add it to your Gemfile:
 
     gem 'carrierwave'
 
-CarrierWave is only compatible with Rails 3 and later as of version 0.5. If you want to use
-Rails 2, please use the latest gem in the 0.4.X series. You may also consider trying
-{this plugin}[http://github.com/gbuesing/carrierwave_rails23_compat] which allows CarrierWave
-to be used with a Rails 2.3 app.
+Note that CarrierWave is not compatible with Rails 2 as of version 0.5. If you want to use
+Rails 2, please use the 0.4-stable branch on GitHub.
 
-== Quick Start
+== Getting Started
 
 Start off by generating an uploader:
 
@@ -94,6 +90,12 @@ automatically be stored when the record is saved.
     u.avatar.url # => '/url/to/file.png'
     u.avatar.current_path # => 'path/to/file.png'
 
+If using DataMapper, make sure to disable auto_validation on the mounted column.
+
+If using Mongoid, note that embedded documents files aren't saved when parent documents are saved.
+You must explicitly call save on embedded documents in order to save their attached files.
+You can read more about this {here}[https://github.com/jnicklas/carrierwave/issues#issue/81]
+
 == Changing the storage directory
 
 In order to change where uploaded files are put, just override the +store_dir+
@@ -123,6 +125,63 @@ make the record invalid instead. Otherwise, an error is raised.
       end
     end
 
+=== Validating Uploads
+
+Standard active model validations can be used to ensure a file is uploaded.
+
+   mount_uploader :avatar, AvatarUploader 
+
+   validate_presence_of :avatar
+
+CarrierWave also supplies additional validations, such as validating the integrity of an uploaded file.
+
+    validates_integrity_of :avatar
+
+or validating that the file was sucessfully processed
+
+    validates_processing_of :avatar
+
+The validations use translated error messages and can be changed using i18n localization
+
+    en:
+      errors:
+        messages:
+          carrierwave_processing_error: failed to be processed
+          carrierwave_integrity_error: is not an allowed file type
+
+
+=== Filenames and unicode chars
+
+Another security issue you should care for is the file names (see
+{Ruby On Rails Security Guide}[http://guides.rubyonrails.org/security.html#file-uploads]).
+By default, CarrierWave provides only English letters, arabic numerals and '-+_.' symbols as
+white-listed characters in the file name.
+
+If you want to support local scripts (Cyrillic letters, letters with diacritics and so on), you
+have to override +sanitize_regexp+ method. It should return regular expression which would match
+all *non*-allowed symbols.
+
+With Ruby 1.9 and higher you can simply write (as it has {Oniguruma}[http://oniguruma.rubyforge.org/oniguruma/]
+built-in):
+
+    class MyUploader < CarrierWave::Uploader::Base
+      def sanitize_regexp
+        /[^[:word:]\.\-\+]/
+      end
+    end
+
+With Ruby 1.8.* you have to manually specify all character ranges. For example, for files which may
+contain Russian letters:
+
+    class MyUploader < CarrierWave::Uploader::Base
+      def sanitize_regexp
+        /[^a-zA-Zа-яА-ЯёЁ0-9\.\-\+_]/u
+      end
+    end
+
+Also make sure that allowing non-latin characters won't cause a compatibility issue with a third-party
+plugins or client-side software.
+
 == Adding versions
 
 Often you'll want to add different versions of the same file. The classic
@@ -243,7 +302,7 @@ this easily by overriding the +default_url+ method in your uploader:
 
 You might come to a situation where you want to retroactively change a version
 or add a new one. You can use the recreate_versions! method to recreate the
-versions from the base file. This uses a naive approach which will reupload and
+versions from the base file. This uses a naive approach which will re-upload and
 process all versions.
 
    instance = MyUploader.new
@@ -275,7 +334,7 @@ If you're using Rails, create an initializer for this:
 
     config/initializers/carrierwave.rb
 
-== Testing CarrierWave
+== Testing with CarrierWave
 
 It's a good idea to test you uploaders in isolation. In order to speed up your
 tests, it's recommended to switch off processing in your tests, and to use the
@@ -331,48 +390,90 @@ Fog[http://github.com/geemus/fog] is used to support Amazon S3. Ensure you have
 
     gem install fog
 
-You'll need to configure a bucket, access id and secret key like this in an initializer:
+You'll need to provide your fog_credentials and a fog_directory (also known as a bucket) in an initializer.
+For the sake of performance it is assumed that the directory already exists, so please create it if need be.
+You can also pass in additional options, as documented fully in lib/carrierwave/storage/fog.rb. Here's a full example:
 
     CarrierWave.configure do |config|
-      config.s3_access_key_id = 'xxxxxx'
-      config.s3_secret_access_key = 'xxxxxx'
-      config.s3_bucket = 'name_of_bucket'
+      config.fog_credentials = {
+        :provider               => 'AWS',       # required
+        :aws_access_key_id      => 'xxx',       # required
+        :aws_secret_access_key  => 'yyy',       # required
+        :region                 => 'eu-west-1'  # optional, defaults to 'us-east-1'
+      }
+      config.fog_directory  = 'name_of_directory'                     # required
+      config.fog_host       = 'https://assets.example.com'            # optional, defaults to nil
+      config.fog_public     = false                                   # optional, defaults to true
+      config.fog_attributes = {'Cache-Control'=>'max-age=315576000'}  # optional, defaults to {}
     end
 
-In your uploader, set the storage to :s3
+In your uploader, set the storage to :fog
 
     class AvatarUploader < CarrierWave::Uploader::Base
-      storage :s3
+      storage :fog
     end
 
-That's it! You can still use the <code>CarrierWave::Uploader#url</code> method to return
-the url to the file on Amazon S3.
+That's it! You can still use the <code>CarrierWave::Uploader#url</code> method to return the url to the file on Amazon S3.
 
 == Using Rackspace Cloud Files
 
-Cloud Files support requires a {Rackspace Cloud}[http://rackspacecloud.com] username and API key.
-You must also create a container for Carrierwave to use, and mark it public (publish it to the CDN)
+Fog[http://github.com/geemus/fog] is used to support Rackspace Cloud Files. Ensure you have it installed:
+
+    gem install fog
+
+You'll need to configure a directory (also known as a container), username and api key in the initializer.
+For the sake of performance it is assumed that the directory already exists, so please create it if need be.
 
     CarrierWave.configure do |config|
-      config.cloud_files_username = 'xxxxxx'
-      config.cloud_files_api_key = 'xxxxxxxxxxxxxxxxxxxxx'
-      config.cloud_files_container = 'name_of_bucket'
+      config.fog_credentials = {
+        :provider           => 'Rackspace',
+        :rackspace_username => 'xxxxxx',
+        :rackspace_api_key  => 'yyyyyy'
+      }
+      config.fog_directory = 'name_of_directory'
     end
 
 You can optionally include your CDN host name in the configuration.
 This is *highly* recommended, as without it every request requires a lookup
 of this information.
 
-    config.cloud_files_cdn_host = "c000000.cdn.rackspacecloud.com"
+    config.fog_host = "c000000.cdn.rackspacecloud.com"
 
-In your uploader, set the storage to :cloud_files
+In your uploader, set the storage to :fog
 
     class AvatarUploader < CarrierWave::Uploader::Base
-      storage :cloud_files
+      storage :fog
     end
 
 That's it! You can still use the <code>CarrierWave::Uploader#url</code> method to return
-the url to the file on the Cloud Files CDN.
+the url to the file on Rackspace Cloud Files.
+
+== Using Google Storage for Developers
+
+Fog[http://github.com/geemus/fog] is used to support Google Storage for Developers. Ensure you have it installed:
+
+    gem install fog
+
+You'll need to configure a directory (also known as a bucket), access key id and secret access key in the initialiazer.
+For the sake of performance it is assumed that the directory already exists, so please create it if need be.
+
+    CarrierWave.configure do |config|
+      config.fog_credentials = {
+        :provider                         => 'Google',
+        :google_storage_access_key_id     => 'xxxxxx',
+        :google_storage_secret_access_key => 'yyyyyy'
+      }
+      config.fog_directory = 'name_of_directory'
+    end
+
+In your uploader, set the storage to :fog
+
+    class AvatarUploader < CarrierWave::Uploader::Base
+      storage :fog
+    end
+
+That's it! You can still use the <code>CarrierWave::Uploader#url</code> method to return
+the url to the file on Google.
 
 == Using MongoDB's GridFS store
 
@@ -463,7 +564,7 @@ for the RMagick processor.
       process :resize_to_fill => [200, 200]
     end
 
-== Migrating
+== Migrating from Paperclip
 
 If you are using Paperclip, you can use the provided compatibility module:
 
@@ -472,19 +573,19 @@ If you are using Paperclip, you can use the provided compatibility module:
     end
 
 See the documentation for <code>CarrierWave::Compatibility::Paperclip</code> for more
-detaills.
+details.
 
 Be sure to use mount_on to specify the correct column:
 
     mount_uploader :avatar, AvatarUploader, :mount_on => :avatar_file_name
 
-Unfortunately AttachmentFoo differs too much in philosophy for there to be a
+Unfortunately attachment_fu differs too much in philosophy for there to be a
 sensible compatibility mode. Patches for migrating from other solutions will be
 happily accepted.
 
 == i18n
 
-The activerecord validations use the Rails i18n framework. Add these keys to
+The Active Record validations use the Rails i18n framework. Add these keys to
 your translations file:
 
     errors:
@@ -492,6 +593,36 @@ your translations file:
         carrierwave_processing_error: 'Cannot resize image.'
         carrierwave_integrity_error: 'Not an image.'
 
+== Contributing to CarrierWave
+
+CarrierWave thrives on a large number of {contributors}[https://github.com/jnicklas/carrierwave/contributors],
+and pull requests are very welcome. Before submitting a pull request, please make sure that your changes are well tested.
+
+You'll need to install bundler and the gem dependencies:
+
+    gem install bundler
+    bundle install
+
+You should now be able to run the local tests:
+
+    bundle exec rake
+
+You can also run the remote specs by creating a ~/.fog file:
+
+    :carrierwave:
+      :aws_access_key_id: xxx
+      :aws_secret_access_key: yyy
+      :rackspace_username: xxx
+      :rackspace_api_key: yyy
+      :google_storage_access_key_id: xxx
+      :google_storage_secret_access_key: yyy
+
+You should now be able to run the remote tests:
+
+    REMOTE=true bundle exec rake
+
+Please test with the latest Ruby 1.8.x and 1.9.x versions using RVM if possible.
+
 == License
 
 Copyright (c) 2008 Jonas Nicklas
@@ -514,21 +645,3 @@ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-== Development
-
-In order to setup a development environment and run the specs, you'll
-need to install bundler:
-
-    gem install bundler
-
-And then install the dependencies:
-
-    bundle install
-
-You should now be able to run the tests:
-
-    bundle exec rake
-
-Issues are reported on GitHub, pull requests are very welcome!
-

data/lib/carrierwave/compatibility/paperclip.rb

@@ -11,7 +11,7 @@ module CarrierWave
     #
     #     class MyUploader < CarrierWave::Uploader::Base
     #       include CarrierWave::Compatibility::Paperclip
-    #       
+    #
     #       def paperclip_path
     #         ":rails_root/public/uploads/:id/:attachment/:style_:basename.:extension"
     #       end
@@ -20,23 +20,23 @@ module CarrierWave
     # ---
     #
     # This file contains code taken from Paperclip
-    # 
+    #
     # LICENSE
-    # 
+    #
     # The MIT License
-    # 
+    #
     # Copyright (c) 2008 Jon Yurek and thoughtbot, inc.
-    # 
+    #
     # Permission is hereby granted, free of charge, to any person obtaining a copy
     # of this software and associated documentation files (the "Software"), to deal
     # in the Software without restriction, including without limitation the rights
     # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     # copies of the Software, and to permit persons to whom the Software is
     # furnished to do so, subject to the following conditions:
-    # 
+    #
     # The above copyright notice and this permission notice shall be included in
     # all copies or substantial portions of the Software.
-    # 
+    #
     # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
     # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
     # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
@@ -77,17 +77,17 @@ module CarrierWave
       end
 
       def mappings
-        {
-          :rails_root   => lambda{|u, f| Rails.root },
-          :rails_env    => lambda{|u, f| Rails.env },
-          :class        => lambda{|u, f| u.model.class.name.underscore.pluralize},
-          :id           => lambda{|u, f| u.model.id },
-          :id_partition => lambda{|u, f| ("%09d" % u.model.id).scan(/\d{3}/).join("/")},
-          :attachment   => lambda{|u, f| u.mounted_as.to_s.downcase.pluralize },
-          :style        => lambda{|u, f| u.paperclip_style },
-          :basename     => lambda{|u, f| f.gsub(/#{File.extname(f)}$/, "") },
-          :extension    => lambda{|u, f| File.extname(f).gsub(/^\.+/, "")}
-        }
+        [
+          [:rails_root   , lambda{|u, f| Rails.root }],
+          [:rails_env    , lambda{|u, f| Rails.env }],
+          [:class        , lambda{|u, f| u.model.class.name.underscore.pluralize}],
+          [:id_partition , lambda{|u, f| ("%09d" % u.model.id).scan(/\d{3}/).join("/")}],
+          [:id           , lambda{|u, f| u.model.id }],
+          [:attachment   , lambda{|u, f| u.mounted_as.to_s.downcase.pluralize }],
+          [:style        , lambda{|u, f| u.paperclip_style }],
+          [:basename     , lambda{|u, f| f.gsub(/#{File.extname(f)}$/, "") }],
+          [:extension    , lambda{|u, f| File.extname(f).gsub(/^\.+/, "")}]
+        ]
       end
 
     end # Paperclip

data/lib/carrierwave/mount.rb

@@ -80,7 +80,7 @@ module CarrierWave
     #
     # [image_url]               Returns the url to the uploaded file
     #
-    # [image_cache]             Returns a string that identifies the cache location of the file 
+    # [image_cache]             Returns a string that identifies the cache location of the file
     # [image_cache=]            Retrieves the file from the cache based on the given cache name
     #
     # [remote_image_url]        Returns previously cached remote url
@@ -106,7 +106,7 @@ module CarrierWave
     # [&block (Proc)]                     customize anonymous uploaders
     #
     # === Options
-    # 
+    #
     # [:mount_on => Symbol] if the name of the column to be serialized to differs you can override it using this option
     # [:ignore_integrity_errors => Boolean] if set to true, integrity errors will result in caching failing silently
     # [:ignore_processing_errors => Boolean] if set to true, processing errors will result in caching failing silently
@@ -256,6 +256,7 @@ module CarrierWave
     # this is an internal class, used by CarrierWave::Mount so that
     # we don't pollute the model with a lot of methods.
     class Mounter #:nodoc:
+      extend ActiveSupport::Memoizable
 
       attr_reader :column, :record, :remote_url, :integrity_error, :processing_error
       attr_accessor :remove
@@ -273,7 +274,7 @@ module CarrierWave
           record.write_uploader(serialization_column, uploader.identifier)
         end
       end
-      
+
       def identifier
         record.read_uploader(serialization_column)
       end
@@ -311,7 +312,7 @@ module CarrierWave
       def remote_url=(url)
         unless uploader.cached?
           @remote_url = url
-          uploader.download!(url) 
+          uploader.download!(url)
         end
       end
 
@@ -342,10 +343,11 @@ module CarrierWave
       end
 
     private
-      
+
       def option(name)
         record.class.uploader_option(column, name)
       end
+      memoize :option
 
       def serialization_column
         option(:mount_on) || column

data/lib/carrierwave/orm/activerecord.rb

@@ -24,9 +24,16 @@ module CarrierWave
       validates_integrity_of column if uploader_option(column.to_sym, :validate_integrity)
       validates_processing_of column if uploader_option(column.to_sym, :validate_processing)
 
-      after_save "store_#{column}!"
-      before_save "write_#{column}_identifier"
-      after_destroy "remove_#{column}!"
+      after_save :"store_#{column}!"
+      before_save :"write_#{column}_identifier"
+      after_destroy :"remove_#{column}!"
+
+      class_eval <<-RUBY, __FILE__, __LINE__+1
+        def #{column}=(new_file)
+          #{column}_will_change!
+          super
+        end
+      RUBY
 
     end
 

data/lib/carrierwave/orm/datamapper.rb

@@ -24,7 +24,7 @@ module CarrierWave
       # for objects that are not dirty. By explicitly calling
       # attribute_set we are marking the record as dirty.
       class_eval <<-RUBY
-        def remove_image=(value)
+        def remove_#{column}=(value)
           _mounter(:#{column}).remove = value
           attribute_set(:#{column}, '') if _mounter(:#{column}).remove?
         end

data/lib/carrierwave/orm/sequel.rb

@@ -1,25 +1,25 @@
 # encoding: utf-8
 
 require 'sequel'
- 
+
 module CarrierWave
   module Sequel
     include CarrierWave::Mount
- 
+
     def mount_uploader(column, uploader)
       raise "You need to use Sequel 3.0 or higher. Please upgrade." unless ::Sequel::Model.respond_to?(:plugin)
       super
- 
+
       alias_method :read_uploader, :[]
       alias_method :write_uploader, :[]=
- 
+
       include CarrierWave::Sequel::Hooks
       include CarrierWave::Sequel::Validations
     end
 
   end # Sequel
 end # CarrierWave
- 
+
 # Instance hook methods for the Sequel 3.x
 module CarrierWave::Sequel::Hooks
   def after_save

data/lib/carrierwave/processing/image_science.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-require "image_science"
+require 'image_science'
 
 module CarrierWave
   module ImageScience
@@ -34,6 +34,8 @@ module CarrierWave
     # [height (Integer)] the height to scale the image to
     #
     def resize_to_fit(new_width, new_height)
+      cache_stored_file! if !cached?
+
       ::ImageScience.with_image(self.current_path) do |img|
         width, height = extract_dimensions(img.width, img.height, new_width, new_height)
         img.resize( width, height ) do |file|
@@ -55,19 +57,38 @@ module CarrierWave
     # [height (Integer)] the height to scale the image to
     #
     def resize_to_fill(new_width, new_height)
+      cache_stored_file! if !cached?
+
       ::ImageScience.with_image(self.current_path) do |img|
         width, height = extract_dimensions_for_crop(img.width, img.height, new_width, new_height)
         x_offset, y_offset = extract_placement_for_crop(width, height, new_width, new_height)
 
+        # check if if new dimensions are too small for the new image
+        if width < new_width
+          width = new_width
+          height = (new_width.to_f*(img.height.to_f/img.width.to_f)).round
+        elsif height < new_height
+          height = new_height
+          width = (new_height.to_f*(img.width.to_f/img.height.to_f)).round
+        end
+
         img.resize( width, height ) do |i2|
 
+          # check to make sure offset is not negative
+          if x_offset < 0
+            x_offset = 0
+          end
+          if y_offset < 0
+            y_offset = 0
+          end
+
           i2.with_crop( x_offset, y_offset, new_width + x_offset, new_height + y_offset) do |file|
             file.save( self.current_path )
           end
         end
       end
     end
-    
+
     ##
     # Resize the image to fit within the specified dimensions while retaining
     # the original aspect ratio. Will only resize the image if it is larger than the
@@ -80,6 +101,8 @@ module CarrierWave
     # [height (Integer)] the height to scale the image to
     #
     def resize_to_limit(new_width, new_height)
+      cache_stored_file! if !cached?
+
       ::ImageScience.with_image(self.current_path) do |img|
         if img.width > new_width or img.height > new_height
           resize_to_fit(new_width, new_height)

data/lib/carrierwave/processing/mini_magick.rb

@@ -249,6 +249,7 @@ module CarrierWave
     # [CarrierWave::ProcessingError] if manipulation failed.
     #
     def manipulate!
+      cache_stored_file! if !cached?
       image = ::MiniMagick::Image.open(current_path)
       image = yield(image)
       image.write(current_path)

data/lib/carrierwave/processing/rmagick.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-unless defined? Magick 
+unless defined? Magick
   begin
     require 'rmagick'
   rescue LoadError
@@ -244,6 +244,7 @@ module CarrierWave
     # [CarrierWave::ProcessingError] if manipulation failed.
     #
     def manipulate!(options={})
+      cache_stored_file! if !cached?
       image = ::Magick::Image.read(current_path)
 
       frames = if image.size > 1
@@ -269,7 +270,7 @@ module CarrierWave
     end
 
   private
-  
+
     def destroy_image(image)
       image.destroy! if image.respond_to?(:destroy!)
     end

data/lib/carrierwave/sanitized_file.rb

@@ -1,6 +1,7 @@
 # encoding: utf-8
 
 require 'pathname'
+require 'active_support/core_ext/string/multibyte'
 
 module CarrierWave
 
@@ -147,7 +148,7 @@ module CarrierWave
     #
     def read
       if is_path?
-        File.open(@file, "rb").read
+        File.open(@file, "rb") {|file| file.read}
       else
         @file.rewind if @file.respond_to?(:rewind)
         @file.read
@@ -221,6 +222,17 @@ module CarrierWave
       @file.content_type.chomp if @file.respond_to?(:content_type) and @file.content_type
     end
 
+    ##
+    # Used to sanitize the file name. Public to allow overriding for non-latin characters.
+    #
+    # === Returns
+    #
+    # [Regexp] the regexp for sanitizing the file name
+    #
+    def sanitize_regexp
+      /[^a-zA-Z0-9\.\-\+_]/
+    end
+
   private
 
     def file=(file)
@@ -248,10 +260,10 @@ module CarrierWave
     def sanitize(name)
       name = name.gsub("\\", "/") # work-around for IE
       name = File.basename(name)
-      name = name.gsub(/[^a-zA-Z0-9\.\-\+_]/,"_")
+      name = name.gsub(sanitize_regexp,"_")
       name = "_#{name}" if name =~ /\A\.+\z/
       name = "unnamed" if name.size == 0
-      return name.downcase
+      return name.mb_chars.downcase.to_s
     end
 
     def split_extension(filename)