lostboy-paperclip 2.2.6.1

data/lib/paperclip.rb

@@ -0,0 +1,318 @@
+# Paperclip allows file attachments that are stored in the filesystem. All graphical
+# transformations are done using the Graphics/ImageMagick command line utilities and
+# are stored in Tempfiles until the record is saved. Paperclip does not require a
+# separate model for storing the attachment's information, instead adding a few simple
+# columns to your table.
+#
+# Author:: Jon Yurek
+# Copyright:: Copyright (c) 2008 thoughtbot, inc.
+# License:: MIT License (http://www.opensource.org/licenses/mit-license.php)
+#
+# Paperclip defines an attachment as any file, though it makes special considerations
+# for image files. You can declare that a model has an attached file with the
+# +has_attached_file+ method:
+#
+#   class User < ActiveRecord::Base
+#     has_attached_file :avatar, :styles => { :thumb => "100x100" }
+#   end
+#
+#   user = User.new
+#   user.avatar = params[:user][:avatar]
+#   user.avatar.url
+#   # => "/users/avatars/4/original_me.jpg"
+#   user.avatar.url(:thumb)
+#   # => "/users/avatars/4/thumb_me.jpg"
+#
+# See the +has_attached_file+ documentation for more details.
+
+require 'tempfile'
+require 'paperclip/upfile'
+require 'paperclip/iostream'
+require 'paperclip/geometry'
+require 'paperclip/processor'
+require 'paperclip/thumbnail'
+require 'paperclip/storage'
+require 'paperclip/attachment'
+if defined? RAILS_ROOT
+  Dir.glob(File.join(File.expand_path(RAILS_ROOT), "lib", "paperclip_processors", "*.rb")).each do |processor|
+    require processor
+  end
+end
+
+# The base module that gets included in ActiveRecord::Base. See the
+# documentation for Paperclip::ClassMethods for more useful information.
+module Paperclip
+
+  VERSION = "2.2.6"
+
+  class << self
+    # Provides configurability to Paperclip. There are a number of options available, such as:
+    # * whiny_thumbnails: Will raise an error if Paperclip cannot process thumbnails of 
+    #   an uploaded image. Defaults to true.
+    # * log: Logs progress to the Rails log. Uses ActiveRecord's logger, so honors
+    #   log levels, etc. Defaults to true.
+    # * command_path: Defines the path at which to find the command line
+    #   programs if they are not visible to Rails the system's search path. Defaults to 
+    #   nil, which uses the first executable found in the user's search path.
+    # * image_magick_path: Deprecated alias of command_path.
+    def options
+      @options ||= {
+        :whiny_thumbnails  => true,
+        :image_magick_path => nil,
+        :command_path      => nil,
+        :log               => true,
+        :swallow_stderr    => true
+      }
+    end
+
+    def path_for_command command #:nodoc:
+      if options[:image_magick_path]
+        warn("[DEPRECATION] :image_magick_path is deprecated and will be removed. Use :command_path instead")
+      end
+      path = [options[:command_path] || options[:image_magick_path], command].compact
+      File.join(*path)
+    end
+
+    def interpolates key, &block
+      Paperclip::Attachment.interpolations[key] = block
+    end
+
+    # The run method takes a command to execute and a string of parameters
+    # that get passed to it. The command is prefixed with the :command_path
+    # option from Paperclip.options. If you have many commands to run and
+    # they are in different paths, the suggested course of action is to
+    # symlink them so they are all in the same directory.
+    #
+    # If the command returns with a result code that is not one of the
+    # expected_outcodes, a PaperclipCommandLineError will be raised. Generally
+    # a code of 0 is expected, but a list of codes may be passed if necessary.
+    def run cmd, params = "", expected_outcodes = 0
+      command = %Q<#{%Q[#{path_for_command(cmd)} #{params}].gsub(/\s+/, " ")}>
+      command = "#{command} 2>#{bit_bucket}" if Paperclip.options[:swallow_stderr]
+      output = `#{command}`
+      unless [expected_outcodes].flatten.include?($?.exitstatus)
+        raise PaperclipCommandLineError, "Error while running #{cmd}"
+      end
+      output
+    end
+
+    def bit_bucket #:nodoc:
+      File.exists?("/dev/null") ? "/dev/null" : "NUL"
+    end
+
+    def included base #:nodoc:
+      base.extend ClassMethods
+      unless base.respond_to?(:define_callbacks)
+        base.send(:include, Paperclip::CallbackCompatability)
+      end
+    end
+
+    def processor name #:nodoc:
+      name = name.to_s.camelize
+      processor = Paperclip.const_get(name)
+      unless processor.ancestors.include?(Paperclip::Processor)
+        raise PaperclipError.new("Processor #{name} was not found") 
+      end
+      processor
+    end
+  end
+
+  class PaperclipError < StandardError #:nodoc:
+  end
+
+  class PaperclipCommandLineError < StandardError #:nodoc:
+  end
+
+  class NotIdentifiedByImageMagickError < PaperclipError #:nodoc:
+  end
+
+  module ClassMethods
+    # +has_attached_file+ gives the class it is called on an attribute that maps to a file. This
+    # is typically a file stored somewhere on the filesystem and has been uploaded by a user. 
+    # The attribute returns a Paperclip::Attachment object which handles the management of
+    # that file. The intent is to make the attachment as much like a normal attribute. The 
+    # thumbnails will be created when the new file is assigned, but they will *not* be saved 
+    # until +save+ is called on the record. Likewise, if the attribute is set to +nil+ is 
+    # called on it, the attachment will *not* be deleted until +save+ is called. See the 
+    # Paperclip::Attachment documentation for more specifics. There are a number of options 
+    # you can set to change the behavior of a Paperclip attachment:
+    # * +url+: The full URL of where the attachment is publically accessible. This can just
+    #   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 
+    #   "/system/:attachment/:id/:style/:basename.:extension". See
+    #   Paperclip::Attachment#interpolate for more information on variable interpolaton.
+    #     :url => "/:class/:attachment/:id/:style_:basename.:extension"
+    #     :url => "http://some.other.host/stuff/:class/:id_:extension"
+    # * +default_url+: The URL that will be returned if there is no attachment assigned. 
+    #   This field is interpolated just as the url is. The default value is 
+    #   "/:attachment/:style/missing.png"
+    #     has_attached_file :avatar, :default_url => "/images/default_:style_avatar.png"
+    #     User.new.avatar_url(:small) # => "/images/default_small_avatar.png"
+    # * +styles+: A hash of thumbnail styles and their geometries. You can find more about 
+    #   geometry strings at the ImageMagick website 
+    #   (http://www.imagemagick.org/script/command-line-options.php#resize). Paperclip
+    #   also adds the "#" option (e.g. "50x50#"), which will resize the image to fit maximally 
+    #   inside the dimensions and then crop the rest off (weighted at the center). The 
+    #   default value is to generate no thumbnails.
+    # * +default_style+: The thumbnail style that will be used by default URLs. 
+    #   Defaults to +original+.
+    #     has_attached_file :avatar, :styles => { :normal => "100x100#" },
+    #                       :default_style => :normal
+    #     user.avatar.url # => "/avatars/23/normal_me.png"
+    # * +whiny_thumbnails+: Will raise an error if Paperclip cannot post_process an uploaded file due
+    #   to a command line error. This will override 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)
+
+      after_save :save_attached_files
+      before_destroy :destroy_attached_files
+
+      define_callbacks :before_post_process, :after_post_process
+      define_callbacks :"before_#{name}_post_process", :"after_#{name}_post_process"
+     
+      define_method name do |*args|
+        a = attachment_for(name)
+        (args.length > 0) ? a.to_s(args.first) : a
+      end
+
+      define_method "#{name}=" do |file|
+        attachment_for(name).assign(file)
+      end
+
+      define_method "#{name}?" do
+        attachment_for(name).file?
+      end
+
+      validates_each(name) do |record, attr, value|
+        attachment = record.attachment_for(name)
+        attachment.send(:flush_errors) unless attachment.valid?
+      end
+    end
+
+    # Places ActiveRecord-style validations on the size of the file assigned. The
+    # possible options are:
+    # * +in+: a Range of bytes (i.e. +1..1.megabyte+),
+    # * +less_than+: equivalent to :in => 0..options[:less_than]
+    # * +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 = {}
+      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
+
+    # Adds errors if thumbnail creation fails. The same as specifying :whiny_thumbnails => true.
+    def validates_attachment_thumbnails name, options = {}
+      attachment_definitions[name][:whiny_thumbnails] = true
+    end
+
+    # Places ActiveRecord-style validations on the presence of a file.
+    def validates_attachment_presence name, options = {}
+      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.  Each type can be a String or a Regexp. It should be 
+    #   noted that Internet Explorer upload 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.
+    # NOTE: If you do not specify an [attachment]_content_type field on your
+    # model, content_type validation will work _ONLY upon assignment_ and
+    # re-validation after the instance has been reloaded will always succeed.
+    def validates_attachment_content_type name, options = {}
+      attachment_definitions[name][:validations][:content_type] = lambda do |attachment, instance|
+        valid_types = [options[:content_type]].flatten
+        
+        unless attachment.original_filename.blank?
+          unless valid_types.blank?
+            content_type = attachment.instance_read(:content_type)
+            unless valid_types.any?{|t| content_type.nil? || t === content_type }
+              options[:message] || "is not one of the allowed file types."
+            end
+          end
+        end
+      end
+    end
+
+    # Returns the attachment definitions defined by each call to
+    # has_attached_file.
+    def attachment_definitions
+      read_inheritable_attribute(:attachment_definitions)
+    end
+  end
+
+  module InstanceMethods #:nodoc:
+    def attachment_for name
+      @_paperclip_attachments ||= {}
+      @_paperclip_attachments[name] ||= Attachment.new(name, self, self.class.attachment_definitions[name])
+    end
+    
+    def each_attachment
+      self.class.attachment_definitions.each do |name, definition|
+        yield(name, attachment_for(name))
+      end
+    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)
+      end
+    end
+  end
+
+end
+
+# Set it all up.
+if Object.const_defined?("ActiveRecord")
+  ActiveRecord::Base.send(:include, Paperclip)
+  File.send(:include, Paperclip::Upfile)
+end

data/shoulda_macros/paperclip.rb

@@ -0,0 +1,68 @@
+require 'paperclip/matchers'
+
+module Paperclip
+  # =Paperclip Shoulda Macros
+  #
+  # These macros are intended for use with shoulda, and will be included into
+  # your tests automatically. All of the macros use the standard shoulda
+  # assumption that the name of the test is based on the name of the model
+  # you're testing (that is, UserTest is the test for the User model), and
+  # will load that class for testing purposes.
+  module Shoulda
+    include Matchers
+    # This will test whether you have defined your attachment correctly by
+    # checking for all the required fields exist after the definition of the
+    # attachment.
+    def should_have_attached_file name
+      klass   = self.name.gsub(/Test$/, '').constantize
+      matcher = have_attached_file name
+      should matcher.description do
+        assert_accepts(matcher, klass)
+      end
+    end
+
+    # Tests for validations on the presence of the attachment.
+    def should_validate_attachment_presence name
+      klass   = self.name.gsub(/Test$/, '').constantize
+      matcher = validate_attachment_presence name
+      should matcher.description do
+        assert_accepts(matcher, klass)
+      end
+    end
+
+    # Tests that you have content_type validations specified. There are two
+    # options, :valid and :invalid. Both accept an array of strings. The
+    # strings should be a list of content types which will pass and fail
+    # validation, respectively.
+    def should_validate_attachment_content_type name, options = {}
+      klass   = self.name.gsub(/Test$/, '').constantize
+      valid   = [options[:valid]].flatten
+      invalid = [options[:invalid]].flatten
+      matcher = validate_attachment_content_type(name).allowing(valid).rejecting(invalid)
+      should matcher.description do
+        assert_accepts(matcher, klass)
+      end
+    end
+
+    # Tests to ensure that you have file size validations turned on. You
+    # can pass the same options to this that you can to 
+    # validate_attachment_file_size - :less_than, :greater_than, and :in.
+    # :less_than checks that a file is less than a certain size, :greater_than
+    # checks that a file is more than a certain size, and :in takes a Range or
+    # Array which specifies the lower and upper limits of the file size.
+    def should_validate_attachment_size name, options = {}
+      klass   = self.name.gsub(/Test$/, '').constantize
+      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)
+      matcher = validate_attachment_size(name).in(range)
+      should matcher.description do
+        assert_accepts(matcher, klass)
+      end
+    end
+  end
+end
+
+class Test::Unit::TestCase #:nodoc:
+ extend  Paperclip::Shoulda
+end

data/tasks/paperclip_tasks.rake

@@ -0,0 +1,79 @@
+def obtain_class
+  class_name = ENV['CLASS'] || ENV['class']
+  raise "Must specify CLASS" unless class_name
+  @klass = Object.const_get(class_name)
+end
+
+def obtain_attachments
+  name = ENV['ATTACHMENT'] || ENV['attachment']
+  raise "Class #{@klass.name} has no attachments specified" unless @klass.respond_to?(:attachment_definitions)
+  if !name.blank? && @klass.attachment_definitions.keys.include?(name)
+    [ name ]
+  else
+    @klass.attachment_definitions.keys
+  end
+end
+
+def for_all_attachments
+  klass = obtain_class
+  names = obtain_attachments
+  ids   = klass.connection.select_values(klass.send(:construct_finder_sql, :select => 'id'))
+
+  ids.each do |id|
+    instance = klass.find(id)
+    names.each do |name|
+      result = if instance.send("#{ name }?")
+                 yield(instance, name)
+               else
+                 true
+               end
+      print result ? "." : "x"; $stdout.flush
+    end
+  end
+  puts " Done."
+end
+
+namespace :paperclip do
+  desc "Refreshes both metadata and thumbnails."
+  task :refresh => ["paperclip:refresh:metadata", "paperclip:refresh:thumbnails"]
+
+  namespace :refresh do
+    desc "Regenerates thumbnails for a given CLASS (and optional ATTACHMENT)."
+    task :thumbnails => :environment do
+      errors = []
+      for_all_attachments do |instance, name|
+        result = instance.send(name).reprocess!
+        errors << [instance.id, instance.errors] unless instance.errors.blank?
+        result
+      end
+      errors.each{|e| puts "#{e.first}: #{e.last.full_messages.inspect}" }
+    end
+
+    desc "Regenerates content_type/size metadata for a given CLASS (and optional ATTACHMENT)."
+    task :metadata => :environment do
+      for_all_attachments do |instance, name|
+        if file = instance.send(name).to_file
+          instance.send("#{name}_file_name=", instance.send("#{name}_file_name").strip)
+          instance.send("#{name}_content_type=", file.content_type.strip)
+          instance.send("#{name}_file_size=", file.size) if instance.respond_to?("#{name}_file_size")
+          instance.save(false)
+        else
+          true
+        end
+      end
+    end
+  end
+
+  desc "Cleans out invalid attachments. Useful after you've added new validations."
+  task :clean => :environment do
+    for_all_attachments do |instance, name|
+      instance.send(name).send(:validate)
+      if instance.send(name).valid?
+        true
+      else
+        instance.send("#{name}=", nil)
+        instance.save
+      end
+    end
+  end
+end