jcnetdev-paperclip 1.0.20080704

data/lib/paperclip/attachment.rb

@@ -0,0 +1,243 @@
+module Paperclip
+  # The Attachment class manages the files for a given attachment. It saves when the model saves,
+  # deletes when the model is destroyed, and processes the file upon assignment.
+  class Attachment
+    
+    def self.default_options
+      @default_options ||= {
+        :url           => "/:attachment/:id/:style/:basename.:extension",
+        :path          => ":rails_root/public/:attachment/:id/:style/:basename.:extension",
+        :styles        => {},
+        :default_url   => "/:attachment/:style/missing.png",
+        :default_style => :original,
+        :validations   => [],
+        :storage       => :filesystem
+      }
+    end
+
+    attr_reader :name, :instance, :styles, :default_style
+
+    # 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
+    # passed to +has_attached_file+.
+    def initialize name, instance, options = {}
+      @name              = name
+      @instance          = instance
+
+      options = self.class.default_options.merge(options)
+
+      @url               = options[:url]
+      @path              = options[:path]
+      @styles            = options[:styles]
+      @default_url       = options[:default_url]
+      @validations       = options[:validations]
+      @default_style     = options[:default_style]
+      @storage           = options[:storage]
+      @whiny_thumbnails  = options[:whiny_thumbnails]
+      @options           = options
+      @queued_for_delete = []
+      @queued_for_write  = {}
+      @errors            = []
+      @validation_errors = nil
+      @dirty             = false
+
+      normalize_style_definition
+      initialize_storage
+    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.
+    def assign uploaded_file
+      return nil unless valid_assignment?(uploaded_file)
+
+      queue_existing_for_delete
+      @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.strip.gsub /[^\w\d\.\-]+/, '_'
+      @instance[:"#{@name}_content_type"] = uploaded_file.content_type.strip
+      @instance[:"#{@name}_file_size"]    = uploaded_file.size.to_i
+
+      @dirty = true
+
+      post_process
+    ensure
+      validate
+    end
+
+    # Returns the public URL of the attachment, with a given style. Note that this
+    # does not necessarily need to point to a file that your web server can access
+    # and can point to an action in your app, if you need fine grained security.
+    # 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)
+    end
+
+    # Returns the path of the attachment as defined by the :path optionn. 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,
+    # and the :bucket option refers to the S3 bucket.
+    def path style = nil #:nodoc:
+      interpolate(@path, style)
+    end
+
+    # Alias to +url+
+    def to_s style = nil
+      url(style)
+    end
+
+    # Returns true if there are any errors on this attachment.
+    def valid?
+      errors.length == 0
+    end
+
+    # Returns an array containing the errors on this attachment.
+    def errors
+      @errors.compact.uniq
+    end
+
+    # Returns true if there are changes that need to be saved.
+    def dirty?
+      @dirty
+    end
+
+    # Saves the file, if there are no errors. If there are, it flushes them to
+    # the instance's errors and returns false, cancelling the save.
+    def save
+      if valid?
+        flush_deletes
+        flush_writes
+        @dirty = false
+        true
+      else
+        flush_errors
+        false
+      end
+    end
+
+    # 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"]
+    end
+
+    # A hash of procs that are run during the interpolation of a path or url.
+    # A variable of the format :name will be replaced with the return value of
+    # the proc named ":name". Each lambda takes the attachment and the current
+    # style as arguments. This hash can be added to with your own proc if
+    # necessary.
+    def self.interpolations
+      @interpolations ||= {
+        :rails_root   => lambda{|attachment,style| RAILS_ROOT },
+        :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), "")
+                         end,
+        :extension    => lambda do |attachment,style| 
+                           ((style = attachment.styles[style]) && style.last) ||
+                           File.extname(attachment.original_filename).gsub(/^\.+/, "")
+                         end,
+        :id           => lambda{|attachment,style| attachment.instance.id },
+        :id_partition => lambda do |attachment, style|
+                           ("%09d" % attachment.instance.id).scan(/\d{3}/).join("/")
+                         end,
+        :attachment   => lambda{|attachment,style| attachment.name.to_s.downcase.pluralize },
+        :style        => lambda{|attachment,style| style || attachment.default_style },
+      }
+    end
+
+    # This method really shouldn't be called that often. It's expected use is 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!
+      new_original = Tempfile.new("paperclip-reprocess")
+      old_original = to_file(:original)
+      new_original.write( old_original.read )
+      new_original.rewind
+
+      @queued_for_write = { :original => new_original }
+      post_process
+
+      old_original.close if old_original.respond_to?(:close)
+    end
+
+    private
+
+    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
+      end
+    end
+
+    def normalize_style_definition
+      @styles.each do |name, args|
+        dimensions, format = [args, nil].flatten[0..1]
+        format             = nil if format == ""
+        @styles[name]      = [dimensions, format]
+      end
+    end
+
+    def initialize_storage
+      @storage_module = Paperclip::Storage.const_get(@storage.to_s.capitalize)
+      self.extend(@storage_module)
+    end
+
+    def post_process #:nodoc:
+      return if @queued_for_write[:original].nil?
+      @styles.each do |name, args|
+        begin
+          dimensions, format = args
+          @queued_for_write[name] = Thumbnail.make(@queued_for_write[:original], 
+                                                   dimensions,
+                                                   format, 
+                                                   @whiny_thumnails)
+        rescue PaperclipError => e
+          @errors << e.message if @whiny_thumbnails
+        end
+      end
+    end
+
+    def interpolate pattern, style = default_style #:nodoc:
+      interpolations = self.class.interpolations.sort{|a,b| a.first.to_s <=> b.first.to_s }
+      interpolations.reverse.inject( pattern.dup ) do |result, interpolation|
+        tag, blk = interpolation
+        result.gsub(/:#{tag}/) do |match|
+          blk.call( self, style )
+        end
+      end
+    end
+
+    def queue_existing_for_delete #:nodoc:
+      return if original_filename.blank?
+      @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
+    end
+
+    def flush_errors #:nodoc:
+      @errors.each do |error|
+        instance.errors.add(name, error)
+      end
+    end
+
+  end
+end
+

data/lib/paperclip/geometry.rb

@@ -0,0 +1,109 @@
+module Paperclip
+  
+  # Defines the geometry of an image.
+  class Geometry
+    attr_accessor :height, :width, :modifier
+
+    # Gives a Geometry representing the given height and width
+    def initialize width = nil, height = nil, modifier = nil
+      height = nil if height == ""
+      width  = nil if width  == ""
+      @height = (height || width).to_f
+      @width  = (width  || height).to_f
+      @modifier = modifier
+    end
+
+    # Uses ImageMagick to determing the dimensions of a file, passed in as either a
+    # File or path.
+    def self.from_file file
+      file = file.path if file.respond_to? "path"
+      parse(`#{Paperclip.path_for_command('identify')} "#{file}"`) ||
+        raise(NotIdentifiedByImageMagickError.new("#{file} is not recognized by the 'identify' command."))
+    end
+
+    # Parses a "WxH" formatted string, where W is the width and H is the height.
+    def self.parse string
+      if match = (string && string.match(/\b(\d*)x(\d*)\b([\>\<\#\@\%^!])?/))
+        Geometry.new(*match[1,3])
+      end
+    end
+
+    # True if the dimensions represent a square
+    def square?
+      height == width
+    end
+
+    # True if the dimensions represent a horizontal rectangle
+    def horizontal?
+      height < width
+    end
+
+    # True if the dimensions represent a vertical rectangle
+    def vertical?
+      height > width
+    end
+
+    # The aspect ratio of the dimensions.
+    def aspect
+      width / height
+    end
+
+    # Returns the larger of the two dimensions
+    def larger
+      [height, width].max
+    end
+
+    # Returns the smaller of the two dimensions
+    def smaller
+      [height, width].min
+    end
+
+    # Returns the width and height in a format suitable to be passed to Geometry.parse
+    def to_s
+      "%dx%d%s" % [width, height, modifier]
+    end
+
+    # Same as to_s
+    def inspect
+      to_s
+    end
+
+    # Returns the scaling and cropping geometries (in string-based ImageMagick format) 
+    # neccessary to transform this Geometry into the Geometry given. If crop is true, 
+    # then it is assumed the destination Geometry will be the exact final resolution. 
+    # In this case, the source Geometry is scaled so that an image containing the 
+    # destination Geometry would be completely filled by the source image, and any 
+    # overhanging image would be cropped. Useful for square thumbnail images. The cropping 
+    # is weighted at the center of the Geometry.
+    def transformation_to dst, crop = false
+      ratio = Geometry.new( dst.width / self.width, dst.height / self.height )
+
+      if crop
+        scale_geometry, scale = scaling(dst, ratio)
+        crop_geometry         = cropping(dst, ratio, scale)
+      else
+        scale_geometry        = dst.to_s
+      end
+      
+      [ scale_geometry, crop_geometry ]
+    end
+
+    private
+
+    def scaling dst, ratio
+      if ratio.horizontal? || ratio.square?
+        [ "%dx" % dst.width, ratio.width ]
+      else
+        [ "x%d" % dst.height, ratio.height ]
+      end
+    end
+
+    def cropping dst, ratio, scale
+      if ratio.horizontal? || ratio.square?
+        "%dx%d+%d+%d" % [ dst.width, dst.height, 0, (self.height * scale - dst.height) / 2 ]
+      else
+        "%dx%d+%d+%d" % [ dst.width, dst.height, (self.width * scale - dst.width) / 2, 0 ]
+      end
+    end
+  end
+end

data/lib/paperclip/iostream.rb

@@ -0,0 +1,43 @@
+# Provides method that can be included on File-type objects (IO, StringIO, Tempfile, etc) to allow stream copying
+# and Tempfile conversion.
+module IOStream
+
+  # Returns a Tempfile containing the contents of the readable object.
+  def to_tempfile
+    tempfile = Tempfile.new("stream")
+    tempfile.binmode
+    self.stream_to(tempfile)
+  end
+
+  # Copies one read-able object from one place to another in blocks, obviating the need to load
+  # the whole thing into memory. Defaults to 8k blocks. If this module is included in both
+  # both StringIO and Tempfile, then either can have its data copied anywhere else without typing
+  # worries or memory overhead worries. Returns a File if a String is passed in as the destination
+  # and returns the IO or Tempfile as passed in if one is sent as the destination.
+  def stream_to path_or_file, in_blocks_of = 8192
+    dstio = case path_or_file
+            when String   then File.new(path_or_file, "wb+")
+            when IO       then path_or_file
+            when Tempfile then path_or_file
+            end
+    buffer = ""
+    self.rewind
+    while self.read(in_blocks_of, buffer) do
+      dstio.write(buffer)
+    end
+    dstio.rewind    
+    dstio
+  end
+end
+
+class IO
+  include IOStream
+end
+
+%w( Tempfile StringIO ).each do |klass|
+  if Object.const_defined? klass
+    Object.const_get(klass).class_eval do
+      include IOStream
+    end
+  end
+end

data/lib/paperclip/storage.rb

@@ -0,0 +1,179 @@
+module Paperclip
+  module Storage
+
+    # The default place to store attachments is in the filesystem. Files on the local
+    # filesystem can be very easily served by Apache without requiring a hit to your app.
+    # They also can be processed more easily after they've been saved, as they're just
+    # normal files. There is one Filesystem-specific option for has_attached_file.
+    # * +path+: The location of the repository of attachments on disk. This can (and, in
+    #   almost all cases, should) 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"
+    module Filesystem
+      def self.extended base
+      end
+      
+      def exists?(style = default_style)
+        if original_filename
+          File.exist?(path(style))
+        else
+          false
+        end
+      end
+
+      # Returns representation of the data of the file assigned to the given
+      # style, in the format most representative of the current storage.
+      def to_file style = default_style
+        @queued_for_write[style] || (File.new(path(style)) if exists?(style))
+      end
+      alias_method :to_io, :to_file
+
+      def flush_writes #:nodoc:
+        @queued_for_write.each do |style, file|
+          FileUtils.mkdir_p(File.dirname(path(style)))
+          result = file.stream_to(path(style))
+          file.close
+          result.close
+        end
+        @queued_for_write = {}
+      end
+
+      def flush_deletes #:nodoc:
+        @queued_for_delete.each do |path|
+          begin
+            FileUtils.rm(path) if File.exist?(path)
+          rescue Errno::ENOENT => e
+            # ignore file-not-found, let everything else pass
+          end
+        end
+        @queued_for_delete = []
+      end
+    end
+
+    # Amazon's S3 file hosting service is a scalable, easy place to store files for
+    # distribution. You can find out more about it at http://aws.amazon.com/s3
+    # There are a few S3-specific options for has_attached_file:
+    # * +s3_credentials+: Takes a path, a File, or a Hash. The path (or File) must point
+    #   to a YAML file containing the +access_key_id+ and +secret_access_key+ that Amazon
+    #   gives you. You can 'environment-space' this just like you do to your
+    #   database.yml file, so different environments can use different accounts:
+    #     development:
+    #       access_key_id: 123...
+    #       secret_access_key: 123... 
+    #     test:
+    #       access_key_id: abc...
+    #       secret_access_key: abc... 
+    #     production:
+    #       access_key_id: 456...
+    #       secret_access_key: 456... 
+    #   This is not required, however, and the file may simply look like this:
+    #     access_key_id: 456...
+    #     secret_access_key: 456... 
+    #   In which case, those access keys will be used in all environments.
+    # * +s3_permissions+: This is a String that should be one of the "canned" access
+    #   policies that S3 provides (more information can be found here:
+    #   http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html#RESTCannedAccessPolicies)
+    #   The default for Paperclip is "public-read".
+    # * +bucket+: This is the name of the S3 bucket that will store your files. Remember
+    #   that the bucket must be unique across all of Amazon S3. If the bucket does not exist
+    #   Paperclip will attempt to create it. The bucket name will not be interpolated.
+    # * +path+: This is the key under the bucket in which the file will be stored. The
+    #   URL will be constructed from the bucket and the path. This is what you will want
+    #   to interpolate. Keys should be unique, like filenames, and despite the fact that
+    #   S3 (strictly speaking) does not support directories, you can still use a / to
+    #   separate parts of your file name.
+    module S3
+      def self.extended base
+        require 'right_aws'
+        base.instance_eval do
+          @bucket             = @options[:bucket]
+          @s3_credentials     = parse_credentials(@options[:s3_credentials])
+          @s3_options         = @options[:s3_options] || {}
+          @s3_permissions     = @options[:s3_permissions] || 'public-read'
+          @url                = ":s3_url"
+        end
+        base.class.interpolations[:s3_url] = lambda do |attachment, style|
+          "https://s3.amazonaws.com/#{attachment.bucket_name}/#{attachment.path(style).gsub(%r{^/}, "")}"
+        end
+      end
+
+      def s3
+        @s3 ||= RightAws::S3.new(@s3_credentials[:access_key_id],
+                                 @s3_credentials[:secret_access_key],
+                                 @s3_options)
+      end
+
+      def s3_bucket
+        @s3_bucket ||= s3.bucket(@bucket, true, @s3_permissions)
+      end
+
+      def bucket_name
+        @bucket
+      end
+
+      def parse_credentials creds
+        creds = find_credentials(creds).stringify_keys
+        (creds[ENV['RAILS_ENV']] || creds).symbolize_keys
+      end
+      
+      def exists?(style = default_style)
+        s3_bucket.key(path(style)) ? true : false
+      end
+
+      # Returns representation of the data of the file assigned to the given
+      # style, in the format most representative of the current storage.
+      def to_file style = default_style
+        @queued_for_write[style] || s3_bucket.key(path(style))
+      end
+      alias_method :to_io, :to_file
+
+      def flush_writes #:nodoc:
+        @queued_for_write.each do |style, file|
+          begin
+            key = s3_bucket.key(path(style))
+            key.data = file
+            key.put(nil, @s3_permissions)
+          rescue RightAws::AwsError => e
+            raise
+          end
+        end
+        @queued_for_write = {}
+      end
+
+      def flush_deletes #:nodoc:
+        @queued_for_delete.each do |path|
+          begin
+            if file = s3_bucket.key(path)
+              file.delete
+            end
+          rescue RightAws::AwsError
+            # Ignore this.
+          end
+        end
+        @queued_for_delete = []
+      end
+      
+      def find_credentials creds
+        case creds
+        when File:
+          YAML.load_file(creds.path)
+        when String:
+          YAML.load_file(creds)
+        when Hash:
+          creds
+        else
+          raise ArgumentError, "Credentials are not a path, file, or hash."
+        end
+      end
+      private :find_credentials
+
+    end
+  end
+end