paperclip 2.3.8 → 2.3.9

data/{README.rdoc → README.md}

@@ -1,4 +1,5 @@
-=Paperclip
+Paperclip
+=========
 
 Paperclip is intended as an easy file attachment library for ActiveRecord. The
 intent behind it was to keep setup as easy as possible and to treat files as
@@ -12,64 +13,92 @@ packages). Attached files are saved to the filesystem and referenced in the
 browser by an easily understandable specification, which has sensible and
 useful defaults.
 
-See the documentation for +has_attached_file+ in Paperclip::ClassMethods for
+See the documentation for `has_attached_file` in Paperclip::ClassMethods for
 more detailed options.
 
-The complete RDoc[http://rdoc.info/projects/thoughtbot/paperclip] is online.
+The complete [RDoc](http://rdoc.info/gems/paperclip) is online.
 
-==Quick Start
+Requirements
+------------
 
-In your model:
+ImageMagick must be installed and Paperclip must have access to it. To ensure
+that it does, on your command line, run `which convert` (one of the ImageMagick
+utilities). This will give you the path where that utility is installed. For
+example, it might return `/usr/local/bin/convert`.
 
-  class User < ActiveRecord::Base
-    has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }
-  end
+Then, in your environment config file, let Paperclip know to look there by adding that 
+directory to its path.
 
-In your migrations:
+In development mode, you might add this line to `config/environments/development.rb)`:
+
+    Paperclip.options[:command_path] = "/usr/local/bin/"
+
+Installation
+------------
+
+Include the gem in your Gemfile:
+
+    gem "paperclip", "~> 2.3"
+
+Or as a plugin:
+
+  ruby script/plugin install git://github.com/thoughtbot/paperclip.git
+
+Quick Start
+-----------
+
+In your model:
 
-  class AddAvatarColumnsToUser < ActiveRecord::Migration
-    def self.up
-      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_updated_at,   :datetime
+    class User < ActiveRecord::Base
+      has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }
     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
+In your migrations:
+
+    class AddAvatarColumnsToUser < ActiveRecord::Migration
+      def self.up
+        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_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
-  end
 
 In your edit and new views:
 
-  <% form_for :user, @user, :url => user_path, :html => { :multipart => true } do |form| %>
-    <%= form.file_field :avatar %>
-  <% end %>
+    <% form_for :user, @user, :url => user_path, :html => { :multipart => true } do |form| %>
+      <%= form.file_field :avatar %>
+    <% end %>
 
 In your controller:
 
-  def create
-    @user = User.create( params[:user] )
-  end
+    def create
+      @user = User.create( params[:user] )
+    end
 
 In your show view:
 
-  <%= image_tag @user.avatar.url %>
-  <%= image_tag @user.avatar.url(:medium) %>
-  <%= image_tag @user.avatar.url(:thumb) %>
+    <%= image_tag @user.avatar.url %>
+    <%= image_tag @user.avatar.url(:medium) %>
+    <%= image_tag @user.avatar.url(:thumb) %>
 
-==Usage
+Usage
+-----
 
 The basics of paperclip are quite simple: Declare that your model has an
 attachment with the has_attached_file method, and give it a name. Paperclip
 will wrap up up to four attributes (all prefixed with that attachment's name,
 so you can have multiple attachments per model if you wish) and give the a
-friendly front end. The attributes are <attachment>_file_name,
-<attachment>_file_size, <attachment>_content_type, and <attachment>_updated_at.
-Only <attachment>_file_name is required for paperclip to operate. More
+friendly front end. The attributes are `<attachment>_file_name`,
+`<attachment>_file_size`, `<attachment>_content_type`, and `<attachment>_updated_at`.
+Only `<attachment>_file_name` is required for paperclip to operate. More
 information about the options to has_attached_file is available in the
 documentation of Paperclip::ClassMethods.
 
@@ -77,7 +106,8 @@ Attachments can be validated with Paperclip's validation methods,
 validates_attachment_presence, validates_attachment_content_type, and
 validates_attachment_size.
 
-==Storage
+Storage
+-------
 
 The files that are assigned as attachments are, by default, placed in the
 directory specified by the :path option to has_attached_file. By default, this
@@ -87,10 +117,10 @@ public/system directory is symlinked to the app's shared directory, meaning it
 will survive between deployments. For example, using that :path, you may have a
 file at
 
-  /data/myapp/releases/20081229172410/public/system/avatars/13/small/my_pic.png
+    /data/myapp/releases/20081229172410/public/system/avatars/13/small/my_pic.png
 
-NOTE: This is a change from previous versions of Paperclip, but is overall a
-safer choice for the default file store.
+_NOTE: This is a change from previous versions of Paperclip, but is overall a
+safer choice for the default file store._
 
 You may also choose to store your files using Amazon's S3 service. You can find
 more information about S3 storage at the description for
@@ -103,7 +133,8 @@ both the :path and :url options in order to make sure the files are unavailable
 to the public. Both :path and :url allow the same set of interpolated
 variables.
 
-==Post Processing
+Post Processing
+---------------
 
 Paperclip supports an extensible selection of post-processors. When you define
 a set of styles for an attachment, by default it is expected that those
@@ -114,8 +145,8 @@ your Rails app's lib/paperclip_processors directory is automatically loaded by
 paperclip, allowing you to easily define custom processors. You can specify a
 processor with the :processors option to has_attached_file:
 
-  has_attached_file :scan, :styles => { :text => { :quality => :better } },
-                           :processors => [:ocr]
+    has_attached_file :scan, :styles => { :text => { :quality => :better } },
+                             :processors => [:ocr]
 
 This would load the hypothetical class Paperclip::Ocr, which would have the
 hash "{ :quality => :better }" passed to it along with the uploaded file. For
@@ -125,7 +156,7 @@ The default processor is Paperclip::Thumbnail. For backwards compatability
 reasons, you can pass a single geometry string or an array containing a
 geometry and a format, which the file will be converted to, like so:
 
-  has_attached_file :avatar, :styles => { :thumb => ["32x32#", :png] }
+    has_attached_file :avatar, :styles => { :thumb => ["32x32#", :png] }
 
 This will convert the "thumb" style to a 32x32 square in png format, regardless
 of what was uploaded. If the format is not specified, it is kept the same (i.e.
@@ -137,39 +168,42 @@ be given the result of the previous processor's execution. All processors will
 receive the same parameters, which are what you define in the :styles hash.
 For example, assuming we had this definition:
 
-  has_attached_file :scan, :styles => { :text => { :quality => :better } },
-                           :processors => [:rotator, :ocr]
+    has_attached_file :scan, :styles => { :text => { :quality => :better } },
+                             :processors => [:rotator, :ocr]
 
 then both the :rotator processor and the :ocr processor would receive the
 options "{ :quality => :better }". This parameter may not mean anything to one
 or more or the processors, and they are expected to ignore it.
 
-NOTE: Because processors operate by turning the original attachment into the
-styles, no processors will be run if there are no styles defined.
+_NOTE: Because processors operate by turning the original attachment into the
+styles, no processors will be run if there are no styles defined._
 
-==Events
+Events
+------
 
 Before and after the Post Processing step, Paperclip calls back to the model
 with a few callbacks, allowing the model to change or cancel the processing
-step. The callbacks are "before_post_process" and "after_post_process" (which
+step. The callbacks are `before_post_process` and `after_post_process` (which
 are called before and after the processing of each attachment), and the
-attachment-specific "before_<attachment>_post_process" and
-"after_<attachment>_post_process". The callbacks are intended to be as close to
+attachment-specific `before_<attachment>_post_process` and
+`after_<attachment>_post_process`. The callbacks are intended to be as close to
 normal ActiveRecord callbacks as possible, so if you return false (specifically
 - returning nil is not the same) in a before_ filter, the post processing step
 will halt. Returning false in an after_ filter will not halt anything, but you
 can access the model and the attachment if necessary.
 
-NOTE: Post processing will not even *start* if the attachment is not valid
+_NOTE: Post processing will not even *start* if the attachment is not valid
 according to the validations. Your callbacks and processors will *only* be
-called with valid attachments.
+called with valid attachments._
 
-==Testing
+Testing
+-------
 
 Paperclip provides rspec-compatible matchers for testing attachments. See the
 documentation on Paperclip::Shoulda::Matchers for more information.
 
-==Contributing
+Contributing
+------------
 
 If you'd like to contribute a feature or bugfix: Thanks! To make sure your
 fix/feature has a high chance of being included, please read the following
@@ -180,3 +214,19 @@ guidelines:
 2. Make sure there are tests! We 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.
+
+Credits
+-------
+
+![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
+
+Paperclip is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
+
+Thank you to all [the contributors](https://github.com/thoughtbot/paperclip/contributors)!
+
+The names and logos for thoughtbot are trademarks of thoughtbot, inc.
+
+License
+-------
+
+Paperclip is Copyright © 2008-2011 thoughtbot. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.

data/lib/paperclip.rb

@@ -276,6 +276,7 @@ module Paperclip
       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."
+      message = message.call if message.respond_to?(:call)
       message = message.gsub(/:min/, min.to_s).gsub(/:max/, max.to_s)
 
       validates_inclusion_of :"#{name}_file_size",
@@ -330,6 +331,7 @@ module Paperclip
         if !allowed_types.any?{|t| t === value } && !(value.nil? || value.blank?)
           if record.errors.method(:add).arity == -2
             message = options[:message] || "is not one of #{allowed_types.join(", ")}"
+            message = message.call if message.respond_to?(:call)
             record.errors.add(:"#{name}_content_type", message)
           else
             record.errors.add(:"#{name}_content_type", :inclusion, :default => options[:message], :value => value)

data/lib/paperclip/attachment.rb

@@ -8,20 +8,24 @@ module Paperclip
 
     def self.default_options
       @default_options ||= {
-        :url               => "/system/:attachment/:id/:style/:filename",
-        :path              => ":rails_root/public:url",
-        :styles            => {},
-        :processors        => [:thumbnail],
-        :convert_options   => {},
-        :default_url       => "/:attachment/:style/missing.png",
-        :default_style     => :original,
-        :storage           => :filesystem,
-        :use_timestamp     => true,
-        :whiny             => Paperclip.options[:whiny] || Paperclip.options[:whiny_thumbnails]
+        :url                   => "/system/:attachment/:id/:style/:filename",
+        :path                  => ":rails_root/public:url",
+        :styles                => {},
+        :processors            => [:thumbnail],
+        :convert_options       => {},
+        :default_url           => "/:attachment/:style/missing.png",
+        :default_style         => :original,
+        :storage               => :filesystem,
+        :use_timestamp         => true,
+        :whiny                 => Paperclip.options[:whiny] || Paperclip.options[:whiny_thumbnails],
+        :use_default_time_zone => true,
+        :hash_digest           => "SHA1",
+        :hash_data             => ":class/:attachment/:id/:style/:updated_at"
       }
     end
 
     attr_reader :name, :instance, :default_style, :convert_options, :queued_for_write, :whiny, :options
+    attr_accessor :post_processing
 
     # Creates an Attachment object. +name+ is the name of the attachment,
     # +instance+ is the ActiveRecord object instance it's attached to, and
@@ -32,24 +36,29 @@ module Paperclip
 
       options = self.class.default_options.merge(options)
 
-      @url               = options[:url]
-      @url               = @url.call(self) if @url.is_a?(Proc)
-      @path              = options[:path]
-      @path              = @path.call(self) if @path.is_a?(Proc)
-      @styles            = options[:styles]
-      @normalized_styles = nil
-      @default_url       = options[:default_url]
-      @default_style     = options[:default_style]
-      @storage           = options[:storage]
-      @use_timestamp     = options[:use_timestamp]
-      @whiny             = options[:whiny_thumbnails] || options[:whiny]
-      @convert_options   = options[:convert_options]
-      @processors        = options[:processors]
-      @options           = options
-      @queued_for_delete = []
-      @queued_for_write  = {}
-      @errors            = {}
-      @dirty             = false
+      @url                   = options[:url]
+      @url                   = @url.call(self) if @url.is_a?(Proc)
+      @path                  = options[:path]
+      @path                  = @path.call(self) if @path.is_a?(Proc)
+      @styles                = options[:styles]
+      @normalized_styles     = nil
+      @default_url           = options[:default_url]
+      @default_style         = options[:default_style]
+      @storage               = options[:storage]
+      @use_timestamp         = options[:use_timestamp]
+      @whiny                 = options[:whiny_thumbnails] || options[:whiny]
+      @use_default_time_zone = options[:use_default_time_zone]
+      @hash_digest           = options[:hash_digest]
+      @hash_data             = options[:hash_data]
+      @hash_secret           = options[:hash_secret]
+      @convert_options       = options[:convert_options]
+      @processors            = options[:processors]
+      @options               = options
+      @post_processing       = true
+      @queued_for_delete     = []
+      @queued_for_write      = {}
+      @errors                = {}
+      @dirty                 = false
 
       initialize_storage
     end
@@ -98,7 +107,7 @@ module Paperclip
 
       @dirty = true
 
-      post_process
+      post_process if @post_processing
 
       # Reset the file size if the original file was reprocessed.
       instance_write(:file_size,   @queued_for_write[:original].size.to_i)
@@ -127,7 +136,7 @@ module Paperclip
     end
 
     # Alias to +url+
-    def to_s style_name = nil
+    def to_s style_name = default_style
       url(style_name)
     end
 
@@ -197,6 +206,21 @@ module Paperclip
       time && time.to_f.to_i
     end
 
+    # The time zone to use for timestamp interpolation.  Using the default
+    # time zone ensures that results are consistent across all threads.
+    def time_zone
+      @use_default_time_zone ? Time.zone_default : Time.zone
+    end
+
+    # Returns a unique hash suitable for obfuscating the URL of an otherwise
+    # publicly viewable attachment.
+    def hash(style_name = default_style)
+      raise ArgumentError, "Unable to generate hash without :hash_secret" unless @hash_secret
+      require 'openssl' unless defined?(OpenSSL)
+      data = interpolate(@hash_data, style_name)
+      OpenSSL::HMAC.hexdigest(OpenSSL::Digest.const_get(@hash_digest).new, @hash_secret, data)
+    end
+
     def generate_fingerprint(source)
       data = source.read
       source.rewind if source.respond_to?(:rewind)
@@ -219,7 +243,7 @@ module Paperclip
     # in the paperclip:refresh rake task and that's it. It will regenerate all
     # thumbnails forcefully, by reobtaining the original file and going through
     # the post-process again.
-    def reprocess!
+    def reprocess!(*style_args)
       new_original = Tempfile.new("paperclip-reprocess")
       new_original.binmode
       if old_original = to_file(:original)
@@ -227,7 +251,7 @@ module Paperclip
         new_original.rewind
 
         @queued_for_write = { :original => new_original }
-        post_process
+        post_process(*style_args)
 
         old_original.close if old_original.respond_to?(:close)
 
@@ -235,6 +259,9 @@ module Paperclip
       else
         true
       end
+    rescue Errno::EACCES => e
+      warn "#{e} - skipping file"
+      false
     end
 
     # Returns true if a file has been assigned.
@@ -299,21 +326,23 @@ module Paperclip
       [ style_options, all_options ].compact.join(" ")
     end
 
-    def post_process #:nodoc:
+    def post_process(*style_args) #:nodoc:
       return if @queued_for_write[:original].nil?
       instance.run_paperclip_callbacks(:post_process) do
         instance.run_paperclip_callbacks(:"#{name}_post_process") do
-          post_process_styles
+          post_process_styles(*style_args)
         end
       end
     end
 
-    def post_process_styles #:nodoc:
+    def post_process_styles(*style_args) #:nodoc:
       styles.each do |name, style|
         begin
-          raise RuntimeError.new("Style #{name} has no processors defined.") if style.processors.blank?
-          @queued_for_write[name] = style.processors.inject(@queued_for_write[:original]) do |file, processor|
-            Paperclip.processor(processor).make(file, style.processor_options, self)
+          if style_args.empty? || style_args.include?(name)
+            raise RuntimeError.new("Style #{name} has no processors defined.") if style.processors.blank?
+            @queued_for_write[name] = style.processors.inject(@queued_for_write[:original]) do |file, processor|
+              Paperclip.processor(processor).make(file, style.processor_options, self)
+            end
           end
         rescue PaperclipError => e
           log("An error was received while processing: #{e.inspect}")