paperclip 2.1.2 → 2.1.5

data/{README → README.rdoc}

@@ -14,17 +14,19 @@ In your model:
 
 In your migrations:
 
-  class AddAvatarColumsToUser < ActiveRecord::Migration
+  class AddAvatarColumnsToUser < ActiveRecord::Migration
     def self.up
-      add_column :users, :avatar_file_name, :string
+      add_column :users, :avatar_file_name,    :string
       add_column :users, :avatar_content_type, :string
-      add_column :users, :avatar_file_size, :integer
+      add_column :users, :avatar_file_size,    :integer
+      add_column :users, :avatar_updated_at,   :datetime
     end
 
     def self.down
       remove_column :users, :avatar_file_name
       remove_column :users, :avatar_content_type
       remove_column :users, :avatar_file_size
+      remove_column :users, :avatar_updated_at
     end
   end
 
@@ -46,3 +48,12 @@ In your show view:
   <%= image_tag @user.avatar.url(:medium) %>
   <%= image_tag @user.avatar.url(:thumb) %>
 
+==Contributing
+
+If you'd like to contribute a feature or bugfix, thanks! To make sure your fix/feature
+has a high chance of being added, please read the following guidelines:
+
+1. Ask on the mailing list, or post a ticket in Lighthouse.
+2. Make sure there are tests! I will not accept any patch that is not tested.
+   It's a rare time when explicit tests aren't needed. If you have questions about
+   writing tests for paperclip, please ask the mailing list.

data/Rakefile

@@ -12,7 +12,7 @@ task :default => [:clean, :test]
 desc 'Test the paperclip plugin.'
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib' << 'profile'
-  t.pattern = 'test/**/test_*.rb'
+  t.pattern = 'test/**/*_test.rb'
   t.verbose = true
 end
 
@@ -50,21 +50,24 @@ spec = Gem::Specification.new do |s|
   s.version           = Paperclip::VERSION
   s.author            = "Jon Yurek"
   s.email             = "jyurek@thoughtbot.com"
-  s.homepage          = "http://www.thoughtbot.com/"
+  s.homepage          = "http://www.thoughtbot.com/projects/paperclip"
   s.platform          = Gem::Platform::RUBY
   s.summary           = "File attachments as attributes for ActiveRecord"
-  s.files             = FileList["README",
+  s.files             = FileList["README*",
                                  "LICENSE",
                                  "Rakefile",
                                  "init.rb",
-                                 "{generators,lib,tasks,test}/**/*"].to_a
+                                 "{generators,lib,tasks,test,shoulda_macros}/**/*"].to_a
   s.require_path      = "lib"
   s.test_files        = FileList["test/**/test_*.rb"].to_a
   s.rubyforge_project = "paperclip"
   s.has_rdoc          = true
-  s.extra_rdoc_files  = ["README"]
+  s.extra_rdoc_files  = FileList["README*"].to_a
   s.rdoc_options << '--line-numbers' << '--inline-source'
   s.requirements << "ImageMagick"
+  s.add_runtime_dependency 'right_aws'
+  s.add_development_dependency 'thoughtbot-shoulda'
+  s.add_development_dependency 'mocha'
 end
  
 Rake::GemPackageTask.new(spec) do |pkg| 
@@ -82,3 +85,10 @@ task :release => [:test, :sync_docs, :gem] do
                 spec.version,
                 File.join("pkg", "#{spec.name}-#{spec.version}.gem")
 end
+
+desc "Generate a gemspec file for GitHub"
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_ruby
+  end
+end

data/generators/paperclip/USAGE

@@ -1,5 +1,5 @@
 Usage:
 
-  script/generate attachment Class attachment1 attachment2
+  script/generate paperclip Class attachment1 (attachment2 ...)
   
 This will create a migration that will add the proper columns to your class's table.

data/generators/paperclip/paperclip_generator.rb

@@ -10,7 +10,7 @@ class PaperclipGenerator < Rails::Generator::NamedBase
     file_name = generate_file_name
     @migration_name = file_name.camelize
     record do |m|
-      m.migration_template "paperclip_migration.rb",
+      m.migration_template "paperclip_migration.rb.erb",
                            File.join('db', 'migrate'),
                            :migration_file_name => file_name
     end
@@ -24,4 +24,4 @@ class PaperclipGenerator < Rails::Generator::NamedBase
     "add_attachments_#{names.join("_")}_to_#{@class_name.underscore}"
   end
  
-end
+end

data/generators/paperclip/templates/{paperclip_migration.rb → paperclip_migration.rb.erb}

@@ -4,6 +4,7 @@ class <%= migration_name %> < ActiveRecord::Migration
     add_column :<%= class_name.underscore.camelize.tableize %>, :<%= attachment %>_file_name, :string
     add_column :<%= class_name.underscore.camelize.tableize %>, :<%= attachment %>_content_type, :string
     add_column :<%= class_name.underscore.camelize.tableize %>, :<%= attachment %>_file_size, :integer
+    add_column :<%= class_name.underscore.camelize.tableize %>, :<%= attachment %>_updated_at, :datetime
 <% end -%>
   end
 
@@ -12,6 +13,7 @@ class <%= migration_name %> < ActiveRecord::Migration
     remove_column :<%= class_name.underscore.camelize.tableize %>, :<%= attachment %>_file_name
     remove_column :<%= class_name.underscore.camelize.tableize %>, :<%= attachment %>_content_type
     remove_column :<%= class_name.underscore.camelize.tableize %>, :<%= attachment %>_file_size
+    remove_column :<%= class_name.underscore.camelize.tableize %>, :<%= attachment %>_updated_at
 <% end -%>
   end
 end

data/lib/paperclip.rb

@@ -33,10 +33,11 @@ require 'paperclip/thumbnail'
 require 'paperclip/storage'
 require 'paperclip/attachment'
 
-# The base module that gets included in ActiveRecord::Base.
+# The base module that gets included in ActiveRecord::Base. See the
+# documentation for Paperclip::ClassMethods for more useful information.
 module Paperclip
 
-  VERSION = "2.1.2"
+  VERSION = "2.1.5"
 
   class << self
     # Provides configurability to Paperclip. There are a number of options available, such as:
@@ -57,6 +58,18 @@ module Paperclip
       File.join(*path)
     end
 
+    def run cmd, params = "", expected_outcodes = 0
+      output = `#{%Q[#{path_for_command(cmd)} #{params} 2>#{bit_bucket}].gsub(/\s+/, " ")}`
+      unless [expected_outcodes].flatten.include?($?.exitstatus)
+        raise PaperclipCommandLineError, "Error while running #{cmd}"
+      end
+      output
+    end
+
+    def bit_bucket
+      File.exists?("/dev/null") ? "/dev/null" : "NUL"
+    end
+
     def included base #:nodoc:
       base.extend ClassMethods
     end
@@ -65,6 +78,9 @@ module Paperclip
   class PaperclipError < StandardError #:nodoc:
   end
 
+  class PaperclipCommandLineError < StandardError #:nodoc:
+  end
+
   class NotIdentifiedByImageMagickError < PaperclipError #:nodoc:
   end
 
@@ -82,7 +98,8 @@ module Paperclip
     #   as easily point to a directory served directly through Apache as it can to an action
     #   that can control permissions. You can specify the full domain and path, but usually
     #   just an absolute path is sufficient. The leading slash must be included manually for 
-    #   absolute paths. The default value is "/:class/:attachment/:id/:style_:filename". See
+    #   absolute paths. The default value is 
+    #   "/:class/:attachment/:id/:style_:basename.:extension". See
     #   Paperclip::Attachment#interpolate for more information on variable interpolaton.
     #     :url => "/:attachment/:id/:style_:basename:extension"
     #     :url => "http://some.other.host/stuff/:class/:id_:extension"
@@ -102,24 +119,33 @@ module Paperclip
     #     has_attached_file :avatar, :styles => { :normal => "100x100#" },
     #                       :default_style => :normal
     #     user.avatar.url # => "/avatars/23/normal_me.png"
-    # * +path+: The location of the repository of attachments on disk. This can be coordinated
-    #   with the value of the +url+ option to allow files to be saved into a place where Apache
-    #   can serve them without hitting your app. Defaults to 
-    #   ":rails_root/public/:class/:attachment/:id/:style_:filename". 
-    #   By default this places the files in the app's public directory which can be served 
-    #   directly. If you are using capistrano for deployment, a good idea would be to 
-    #   make a symlink to the capistrano-created system directory from inside your app's 
-    #   public directory.
-    #   See Paperclip::Attachment#interpolate for more information on variable interpolaton.
-    #     :path => "/var/app/attachments/:class/:id/:style/:filename"
     # * +whiny_thumbnails+: Will raise an error if Paperclip cannot process thumbnails of an
     #   uploaded image. This will ovrride the global setting for this attachment. 
     #   Defaults to true. 
+    # * +convert_options+: When creating thumbnails, use this free-form options
+    #   field to pass in various convert command options.  Typical options are "-strip" to
+    #   remove all Exif data from the image (save space for thumbnails and avatars) or
+    #   "-depth 8" to specify the bit depth of the resulting conversion.  See ImageMagick
+    #   convert documentation for more options: (http://www.imagemagick.org/script/convert.php)
+    #   Note that this option takes a hash of options, each of which correspond to the style
+    #   of thumbnail being generated. You can also specify :all as a key, which will apply
+    #   to all of the thumbnails being generated. If you specify options for the :original,
+    #   it would be best if you did not specify destructive options, as the intent of keeping
+    #   the original around is to regenerate all the thumbnails when requirements change.
+    #     has_attached_file :avatar, :styles => { :large => "300x300", :negative => "100x100" }
+    #                                :convert_options => {
+    #                                  :all => "-strip",
+    #                                  :negative => "-negate"
+    #                                }
+    # * +storage+: Chooses the storage backend where the files will be stored. The current
+    #   choices are :filesystem and :s3. The default is :filesystem. Make sure you read the
+    #   documentation for Paperclip::Storage::Filesystem and Paperclip::Storage::S3
+    #   for backend-specific options.
     def has_attached_file name, options = {}
       include InstanceMethods
 
       write_inheritable_attribute(:attachment_definitions, {}) if attachment_definitions.nil?
-      attachment_definitions[name] = {:validations => []}.merge(options)
+      attachment_definitions[name] = {:validations => {}}.merge(options)
 
       after_save :save_attached_files
       before_destroy :destroy_attached_files
@@ -134,11 +160,11 @@ module Paperclip
       end
 
       define_method "#{name}?" do
-        ! attachment_for(name).original_filename.blank?
+        attachment_for(name).file?
       end
 
       validates_each(name) do |record, attr, value|
-        value.send(:flush_errors)
+        value.send(:flush_errors) unless value.valid?
       end
     end
 
@@ -149,22 +175,14 @@ module Paperclip
     # * +greater_than+: equivalent to :in => options[:greater_than]..Infinity
     # * +message+: error message to display, use :min and :max as replacements
     def validates_attachment_size name, options = {}
-      attachment_definitions[name][:validations] << lambda do |attachment, instance|
-        unless options[:greater_than].nil?
-          options[:in] = (options[:greater_than]..(1/0)) # 1/0 => Infinity
-        end
-        unless options[:less_than].nil?
-          options[:in] = (0..options[:less_than])
-        end
-        unless attachment.original_filename.blank? || options[:in].include?(instance[:"#{name}_file_size"].to_i)
-          min = options[:in].first
-          max = options[:in].last
-          
-          if options[:message]
-            options[:message].gsub(/:min/, min.to_s).gsub(/:max/, max.to_s)
-          else
-            "file size is not between #{min} and #{max} bytes."
-          end
+      min     = options[:greater_than] || (options[:in] && options[:in].first) || 0
+      max     = options[:less_than]    || (options[:in] && options[:in].last)  || (1.0/0)
+      range   = (min..max)
+      message = options[:message] || "file size must be between :min and :max bytes."
+
+      attachment_definitions[name][:validations][:size] = lambda do |attachment, instance|
+        if attachment.file? && !range.include?(attachment.size.to_i)
+          message.gsub(/:min/, min.to_s).gsub(/:max/, max.to_s)
         end
       end
     end
@@ -176,26 +194,29 @@ module Paperclip
 
     # Places ActiveRecord-style validations on the presence of a file.
     def validates_attachment_presence name, options = {}
-      attachment_definitions[name][:validations] << lambda do |attachment, instance|
-        if attachment.original_filename.blank?
-          options[:message] || "must be set."
-        end
+      message = options[:message] || "must be set."
+      attachment_definitions[name][:validations][:presence] = lambda do |attachment, instance|
+        message unless attachment.file?
       end
     end
     
     # Places ActiveRecord-style validations on the content type of the file assigned. The
     # possible options are:
-    # * +content_type+: Allowed content types.  Can be a single content type or an array.  Allows all by default.
+    # * +content_type+: Allowed content types.  Can be a single content type or an array.
+    #   Each type can be a String or a Regexp. It should be noted that Internet Explorer uploads
+    #   files with content_types that you may not expect. For example, JPEG images are given
+    #   image/pjpeg and PNGs are image/x-png, so keep that in mind when determining how you match.
+    #   Allows all by default.
     # * +message+: The message to display when the uploaded file has an invalid content type.
     def validates_attachment_content_type name, options = {}
-      attachment_definitions[name][:validations] << lambda do |attachment, instance|
+      attachment_definitions[name][:validations][:content_type] = lambda do |attachment, instance|
         valid_types = [options[:content_type]].flatten
         
-        unless attachment.original_filename.nil?
+        unless attachment.original_filename.blank?
           unless options[:content_type].blank?
-            content_type = instance[:"#{name}_content_type"]
+            content_type = attachment.instance_read(:content_type)
             unless valid_types.any?{|t| t === content_type }
-              options[:message] || ActiveRecord::Errors.default_error_messages[:inclusion]
+              options[:message] || "is not one of the allowed file types."
             end
           end
         end
@@ -222,12 +243,14 @@ module Paperclip
     end
 
     def save_attached_files
+      logger.info("[paperclip] Saving attachments.")
       each_attachment do |name, attachment|
         attachment.send(:save)
       end
     end
 
     def destroy_attached_files
+      logger.info("[paperclip] Deleting attachments.")
       each_attachment do |name, attachment|
         attachment.send(:queue_existing_for_delete)
         attachment.send(:flush_deletes)

data/lib/paperclip/attachment.rb

@@ -10,12 +10,12 @@ module Paperclip
         :styles        => {},
         :default_url   => "/:attachment/:style/missing.png",
         :default_style => :original,
-        :validations   => [],
+        :validations   => {},
         :storage       => :filesystem
       }
     end
 
-    attr_reader :name, :instance, :styles, :default_style
+    attr_reader :name, :instance, :styles, :default_style, :convert_options
 
     # Creates an Attachment object. +name+ is the name of the attachment, +instance+ is the
     # ActiveRecord object instance it's attached to, and +options+ is the same as the hash
@@ -34,37 +34,59 @@ module Paperclip
       @default_style     = options[:default_style]
       @storage           = options[:storage]
       @whiny_thumbnails  = options[:whiny_thumbnails]
+      @convert_options   = options[:convert_options] || {}
       @options           = options
       @queued_for_delete = []
       @queued_for_write  = {}
-      @errors            = []
+      @errors            = {}
       @validation_errors = nil
       @dirty             = false
 
       normalize_style_definition
       initialize_storage
+
+      logger.info("[paperclip] Paperclip attachment #{name} on #{instance.class} initialized.")
     end
 
     # What gets called when you call instance.attachment = File. It clears errors,
     # assigns attributes, processes the file, and runs validations. It also queues up
     # the previous file for deletion, to be flushed away on #save of its host.
+    # In addition to form uploads, you can also assign another Paperclip attachment:
+    #   new_user.avatar = old_user.avatar
     def assign uploaded_file
+      %w(file_name).each do |field|
+        unless @instance.class.column_names.include?("#{name}_#{field}")
+          raise PaperclipError.new("#{@instance.class} model does not have required column '#{name}_#{field}'")
+        end
+      end
+
+      if uploaded_file.is_a?(Paperclip::Attachment)
+        uploaded_file = uploaded_file.to_file(:original)
+      end
+
       return nil unless valid_assignment?(uploaded_file)
+      logger.info("[paperclip] Assigning #{uploaded_file.inspect} to #{name}")
 
+      uploaded_file.binmode if uploaded_file.respond_to? :binmode
       queue_existing_for_delete
-      @errors            = []
+      @errors            = {}
       @validation_errors = nil
 
       return nil if uploaded_file.nil?
 
-      @queued_for_write[:original]        = uploaded_file.to_tempfile
-      @instance[:"#{@name}_file_name"]    = uploaded_file.original_filename
-      @instance[:"#{@name}_content_type"] = uploaded_file.content_type
-      @instance[:"#{@name}_file_size"]    = uploaded_file.size
+      logger.info("[paperclip] Writing attributes for #{name}")
+      @queued_for_write[:original]   = uploaded_file.to_tempfile
+      instance_write(:file_name,       uploaded_file.original_filename.strip.gsub(/[^\w\d\.\-]+/, '_'))
+      instance_write(:content_type,    uploaded_file.content_type.to_s.strip)
+      instance_write(:file_size,       uploaded_file.size.to_i)
+      instance_write(:updated_at,      Time.now)
 
       @dirty = true
 
       post_process
+ 
+      # Reset the file size if the original file was reprocessed.
+      instance_write(:file_size, uploaded_file.size.to_i)
     ensure
       validate
     end
@@ -75,15 +97,16 @@ module Paperclip
     # This is not recommended if you don't need the security, however, for
     # performance reasons.
     def url style = default_style
-      original_filename.nil? ? interpolate(@default_url, style) : interpolate(@url, style)
+      url = original_filename.nil? ? interpolate(@default_url, style) : interpolate(@url, style)
+      updated_at ? [url, updated_at].compact.join(url.include?("?") ? "&" : "?") : url
     end
 
-    # Returns the path of the attachment as defined by the :path optionn. If the
+    # Returns the path of the attachment as defined by the :path option. If the
     # file is stored in the filesystem the path refers to the path of the file on
-    # disk. If the file is stored in S3, the path is the "key" part of th URL,
+    # disk. If the file is stored in S3, the path is the "key" part of the URL,
     # and the :bucket option refers to the S3 bucket.
     def path style = nil #:nodoc:
-      interpolate(@path, style)
+      original_filename.nil? ? nil : interpolate(@path, style)
     end
 
     # Alias to +url+
@@ -91,14 +114,15 @@ module Paperclip
       url(style)
     end
 
-    # Returns true if there are any errors on this attachment.
+    # Returns true if there are no errors on this attachment.
     def valid?
-      errors.length == 0
+      validate
+      errors.empty?
     end
 
     # Returns an array containing the errors on this attachment.
     def errors
-      @errors.compact.uniq
+      @errors
     end
 
     # Returns true if there are changes that need to be saved.
@@ -110,11 +134,13 @@ module Paperclip
     # the instance's errors and returns false, cancelling the save.
     def save
       if valid?
+        logger.info("[paperclip] Saving files for #{name}")
         flush_deletes
         flush_writes
         @dirty = false
         true
       else
+        logger.info("[paperclip] Errors on #{name}. Not saving.")
         flush_errors
         false
       end
@@ -123,7 +149,20 @@ module Paperclip
     # Returns the name of the file as originally assigned, and as lives in the
     # <attachment>_file_name attribute of the model.
     def original_filename
-      instance[:"#{name}_file_name"]
+      instance_read(:file_name)
+    end
+
+    def size
+      instance_read(:file_size) || (@queued_for_write[:original] && @queued_for_write[:original].size)
+    end
+
+    def content_type
+      instance_read(:content_type)
+    end
+    
+    def updated_at
+      time = instance_read(:updated_at)
+      time && time.to_i
     end
 
     # A hash of procs that are run during the interpolation of a path or url.
@@ -134,11 +173,12 @@ module Paperclip
     def self.interpolations
       @interpolations ||= {
         :rails_root   => lambda{|attachment,style| RAILS_ROOT },
+        :rails_env    => lambda{|attachment,style| RAILS_ENV },
         :class        => lambda do |attachment,style|
                            attachment.instance.class.name.underscore.pluralize
                          end,
         :basename     => lambda do |attachment,style|
-                           attachment.original_filename.gsub(File.extname(attachment.original_filename), "")
+                           attachment.original_filename.gsub(/#{File.extname(attachment.original_filename)}$/, "")
                          end,
         :extension    => lambda do |attachment,style| 
                            ((style = attachment.styles[style]) && style.last) ||
@@ -159,29 +199,58 @@ module Paperclip
     # again.
     def reprocess!
       new_original = Tempfile.new("paperclip-reprocess")
-      old_original = to_file(:original)
-      new_original.write( old_original.read )
-      new_original.rewind
+      if old_original = to_file(:original)
+        new_original.write( old_original.read )
+        new_original.rewind
 
-      @queued_for_write = { :original => new_original }
-      post_process
+        @queued_for_write = { :original => new_original }
+        post_process
+
+        old_original.close if old_original.respond_to?(:close)
 
-      old_original.close if old_original.respond_to?(:close)
+        save
+      else
+        true
+      end
+    end
+    
+    def file?
+      !original_filename.blank?
+    end
+
+    def instance_write(attr, value)
+      setter = :"#{name}_#{attr}="
+      responds = instance.respond_to?(setter)
+      instance.send(setter, value) if responds || attr.to_s == "file_name"
+    end
+
+    def instance_read(attr)
+      getter = :"#{name}_#{attr}"
+      responds = instance.respond_to?(getter)
+      instance.send(getter) if responds || attr.to_s == "file_name"
     end
 
     private
 
+    def logger
+      instance.logger
+    end
+
     def valid_assignment? file #:nodoc:
       file.nil? || (file.respond_to?(:original_filename) && file.respond_to?(:content_type))
     end
 
     def validate #:nodoc:
       unless @validation_errors
-        @validation_errors = @validations.collect do |v|
-          v.call(self, instance)
-        end.flatten.compact.uniq
-        @errors += @validation_errors
+        @validation_errors = @validations.inject({}) do |errors, validation|
+          name, block = validation
+          errors[name] = block.call(self, instance) if block
+          errors
+        end
+        @validation_errors.reject!{|k,v| v == nil }
+        @errors.merge!(@validation_errors)
       end
+      @validation_errors
     end
 
     def normalize_style_definition
@@ -197,17 +266,24 @@ module Paperclip
       self.extend(@storage_module)
     end
 
+    def extra_options_for(style) #:nodoc:
+      [ convert_options[style], convert_options[:all] ].compact.join(" ")
+    end
+
     def post_process #:nodoc:
       return if @queued_for_write[:original].nil?
+      logger.info("[paperclip] Post-processing #{name}")
       @styles.each do |name, args|
         begin
           dimensions, format = args
+          dimensions = dimensions.call(instance) if dimensions.respond_to? :call
           @queued_for_write[name] = Thumbnail.make(@queued_for_write[:original], 
                                                    dimensions,
                                                    format, 
-                                                   @whiny_thumnails)
+                                                   extra_options_for(name),
+                                                   @whiny_thumbnails)
         rescue PaperclipError => e
-          @errors << e.message if @whiny_thumbnails
+          (@errors[:processing] ||= []) << e.message if @whiny_thumbnails
         end
       end
     end
@@ -223,18 +299,20 @@ module Paperclip
     end
 
     def queue_existing_for_delete #:nodoc:
-      return if original_filename.blank?
+      return unless file?
+      logger.info("[paperclip] Queueing the existing files for #{name} for deletion.")
       @queued_for_delete += [:original, *@styles.keys].uniq.map do |style|
         path(style) if exists?(style)
       end.compact
-      @instance[:"#{@name}_file_name"]    = nil
-      @instance[:"#{@name}_content_type"] = nil
-      @instance[:"#{@name}_file_size"]    = nil
+      instance_write(:file_name, nil)
+      instance_write(:content_type, nil)
+      instance_write(:file_size, nil)
+      instance_write(:updated_at, nil)
     end
 
     def flush_errors #:nodoc:
-      @errors.each do |error|
-        instance.errors.add(name, error)
+      @errors.each do |error, message|
+        instance.errors.add(name, message) if message
       end
     end