coryodaniel-milton 0.3.7

data/lib/milton/attachment.rb

@@ -0,0 +1,202 @@
+require 'fileutils'
+require 'milton/derivatives/derivative'
+
+module Milton
+  module Attachment
+    # Call is_attachment with your options in order to add attachment
+    # functionality to your ActiveRecord model.
+    # 
+    # TODO: list options
+    def is_attachment(options={})
+      # Check to see that it hasn't already been extended so that subclasses
+      # can redefine is_attachment from their superclasses and overwrite 
+      # options w/o losing the superclass options.
+      unless respond_to?(:has_attachment_methods)
+        extend Milton::Attachment::AttachmentMethods
+        class_inheritable_accessor :milton_options
+      end
+      has_attachment_methods(options)
+    end
+    
+    module AttachmentMethods        
+      def require_column(column, message)
+        begin
+          raise message unless column_names.include?(column)
+        rescue ActiveRecord::StatementInvalid => i
+          # table doesn't exist yet, i.e. hasn't been migrated in...
+        end
+      end
+      
+      def has_attachment_methods(options={})
+        require_column 'filename', "Milton requires a filename column on #{class_name} table"
+        
+        # It's possible that this is being included from a class and a sub
+        # class of that class, in which case we need to merge the existing
+        # options up.
+        self.milton_options ||= {}
+        milton_options.merge!(options)
+        
+        # Character used to seperate a filename from its derivative options, this
+        # character will be stripped from all incoming filenames and replaced by
+        # replacement
+        milton_options[:separator]        ||= '.'
+        milton_options[:replacement]      ||= '-'          
+        milton_options[:tempfile_path]    ||= File.join(Rails.root, "tmp", "milton")
+        milton_options[:storage]          ||= :disk
+        milton_options[:storage_options]  ||= {}
+        milton_options[:processors]       ||= {}
+        milton_options[:uploading]        ||= true
+        
+        # Set to true to allow on-demand processing of derivatives. This can
+        # be rediculously slow because it requires that the existance of the
+        # derivative is checked each time it's requested -- throw in S3 and
+        # that becomes a huge lag. Reccommended only for prototyping.
+        milton_options[:postproccess]     ||= false
+        
+        # TODO: Write about recipes
+        #   * They're refered to by name in #path
+        #   * They're an order of derivations to make against this attachment
+        #   * They run in the order defined
+        #   * They are created and run when the AR model is created
+        #   * They're necessary when +:postprocessing+ is turned off
+        milton_options[:recipes]          ||= {}
+        milton_options[:recipes].each do |name, steps|
+          steps = [steps] unless steps.is_a?(Array)
+          steps.each do |step|
+            step.each { |processor, options| Milton.try_require "milton/derivatives/#{processor}", "No '#{processor}' processor found for Milton" }
+          end
+        end
+
+        # TODO: Write about storage options
+        #   * Late binding (so right_aws is only req'd if you use S3)
+        Milton.try_require "milton/storage/#{milton_options[:storage]}_file", "No '#{milton_options[:storage]}' storage found for Milton"
+
+        # TODO: initialize these options in DiskFile
+        if milton_options[:storage] == :disk
+          # root of where the underlying files are stored (or will be stored)
+          # on the file system
+          milton_options[:storage_options][:root]  ||= File.join(Rails.root, "public", table_name)
+          milton_options[:storage_options][:root]    = File.expand_path(milton_options[:storage_options][:root])
+          # mode to set on stored files and created directories
+          milton_options[:storage_options][:chmod] ||= 0755
+        end
+                  
+        validates_presence_of :filename
+        
+        after_destroy :destroy_attached_file
+        after_create :create_derivatives
+
+        include Milton::Attachment::InstanceMethods
+        
+        if milton_options[:uploading]
+          require 'milton/uploading'
+          extend  Milton::Uploading::ClassMethods
+          include Milton::Uploading::InstanceMethods
+        end
+      end        
+    end
+    
+    # These get mixed in to your model when you use Milton
+    module InstanceMethods
+      # Sets the filename to the given filename (sanitizes the given filename
+      # as well)
+      #
+      # TODO: change the filename on the underlying file system on save so as
+      # not to orphan the file
+      def filename=(name)
+        write_attribute :filename, Storage::StoredFile.sanitize_filename(name, self.class.milton_options)
+      end
+
+      # Returns the content_type of this attachment, tries to determine it if
+      # hasn't been determined yet or is not saved to the database
+      def content_type
+        return self[:content_type] unless self[:content_type].blank?
+        self.content_type = attached_file.mime_type
+      end
+      
+      # Sets the content type to the given type
+      def content_type=(type)
+        write_attribute :content_type, type.to_s.strip
+      end
+
+      # Simple helper, same as path except returns the directory from
+      # .../public/ on, i.e. for showing images in your views.
+      #
+      #   @asset.path        => /var/www/site/public/assets/000/000/001/313/milton.jpg
+      #   @asset.public_path => /assets/000/000/001/313/milton.jpg
+      #
+      # Can send a different base path than public if you want to give the
+      # path from that base on, useful if you change your root path to
+      # somewhere else.
+      def public_path(options={}, base='public')
+        path(options).gsub(/.*?\/#{base}/, '')
+      end
+      
+      # The path to the file.
+      def path(options=nil)
+        return attached_file.path if options.nil?
+        process(options).path
+      end
+      
+      protected
+      
+      # Meant to be used as an after_create filter -- loops over all the
+      # recipes and processes them to create the derivatives.
+      def create_derivatives
+        milton_options[:recipes].each{ |name, recipe| process(name, true) } if milton_options[:recipes].any?
+      end
+      
+      # Process the given options to produce a final derivative. +options+
+      # takes a Hash of options to process or the name of a pre-defined
+      # recipe which will be looked up and processed.
+      # 
+      # Pass +force = true+ to force processing regardless of if 
+      # +:postprocessing+ is turned on or not.
+      # 
+      # Returns the final Derivative of all processors in the recipe.
+      def process(options, force=false)
+        options = milton_options[:recipes][options] unless options.is_a?(Hash)
+        options = [options] unless options.is_a?(Array)
+        
+        source = attached_file
+        options.each do |recipe|
+          recipe.each do |processor, opts|
+            source = Derivative.factory(processor, source, opts, self.class.milton_options).process_if(process? || force).file
+          end
+        end
+        source
+      end
+      
+      # Returns true if derivaties of the attachment should be processed,
+      # returns false if no processing should be done when a derivative is
+      # requested.
+      # 
+      # No processing also means the derivative won't be checked for
+      # existance (since that can be slow) so w/o postprocessing things will
+      # be much faster but #path will happily return the paths to Derivatives
+      # which don't exist.
+      # 
+      # It is highly recommended that you turn +:postprocessing+ off for
+      # anything but prototyping, and instead use recipes and refer to them
+      # via #path. +:postprocessing+ relies on checking for existance which
+      # will kill any real application.
+      def process?
+        self.class.milton_options[:postprocessing]
+      end
+      
+      # A reference to the attached file, this is probably what you want to
+      # overwrite to introduce a new behavior
+      #
+      # i.e. 
+      #   have attached_file return a ResizeableFile, or a TranscodableFile
+      def attached_file
+        @attached_file ||= Storage::StoredFile.adapter(self.class.milton_options[:storage]).new(filename, id, self.class.milton_options)
+      end
+      
+      # Clean the file from the filesystem
+      def destroy_attached_file
+        attached_file.destroy
+      end
+    end
+  end
+end

data/lib/milton/core/file.rb

@@ -0,0 +1,22 @@
+begin
+  require 'mimetype_fu'
+rescue MissingSourceFile
+end
+
+module Milton
+  class File < ::File
+    class << self
+      def extension(filename)
+        extension = extname(filename)
+        extension.slice(1, extension.length-1)
+      end
+      
+      # File respond_to?(:mime_type) is true if mimetype_fu is installed, so
+      # this way we always have File.mime_type? available but it favors
+      # mimetype_fu's implementation.
+      def mime_type?(file)
+        ::File.respond_to?(:mime_type?) ? super(file.filename) : file.content_type
+      end
+    end
+  end
+end

data/lib/milton/core/tempfile.rb

@@ -0,0 +1,44 @@
+require 'tempfile'
+
+module Milton
+  # For lack of a better name, a MiltonTempfile adds some helpful
+  # functionality to Ruby's Tempfile
+  class Tempfile < ::Tempfile
+    class << self
+      def create(data_or_path, tempfile_path)
+        FileUtils.mkdir_p(tempfile_path) unless File.exists?(tempfile_path)
+    
+        tempfile = new(basename, tempfile_path)
+    
+        if data_or_path.is_a?(StringIO)
+          tempfile.binmode
+          tempfile.write data_or_path.read
+          tempfile.close
+        else
+          tempfile.close
+          FileUtils.cp((data_or_path.respond_to?(:path) ? data_or_path.path : data_or_path), tempfile.path)
+        end
+    
+        tempfile
+      end
+    
+      def basename
+        "#{rand(Time.now.to_i)}"
+      end
+    
+      def filename(extension)
+        "#{basename}.#{extension}"
+      end
+    
+      def path(tempfile_path, extension)
+        File.join(tempfile_path, filename(extension))
+      end
+      
+      # Simple helper that returns a path to a tempfile with a uniquely
+      # generated basename and same extension as the given source.
+      def from(source)
+        filename(Milton::File.extension(source))
+      end
+    end
+  end
+end

data/lib/milton/derivatives/derivative.rb

@@ -0,0 +1,106 @@
+module Milton
+  # Represents a file created on the file system that is a derivative of the
+  # one referenced by the model, i.e. a thumbnail of an image, or a transcode
+  # of a video.
+  # 
+  # Provides a container for options and a uniform API to dealing with
+  # passing options for the creation of derivatives.
+  # 
+  # Files created as derivatives have their creation options appended into
+  # their filenames so it can be checked later if a file w/ the given
+  # options already exists (so as not to create it again).
+  #
+  class Derivative
+    class << self
+      # Given a string of attachment options, splits them out into a hash,
+      # useful for things that take options on the query string or from
+      # filenames
+      def options_from(string)
+        Hash[*(string.split('_').collect { |option| 
+          key, value = option.split('=')
+          [ key.to_sym, value || true ] # nothing on RHS of = means it's a boolean true
+        }).flatten]
+      end
+
+      # Given a filename (presumably with options embedded in it) parses out
+      # the options and returns them as a hash.
+      def extract_options_from(filename, options)
+        File.basename(filename, File.extname(filename))[(filename.rindex(options[:separator]) + 1)..-1]
+      end
+      
+      # Creates a new Derivative from the given filename by extracting the
+      # options.
+      def from_filename(filename)
+        Derivative.new(filename, options_from(extract_options_from(filename)))
+      end
+      
+      def process(source, options={}, settings={})
+        returning(derivative = new(source, options, settings)) do
+          derivative.process unless derivative.exists?
+        end
+      end
+      
+      def factory(type, source, options={}, settings={})
+        begin
+          klass = "Milton::#{type.to_s.classify}".constantize
+        rescue NameError
+          begin
+            require "milton/derivatives/#{type.to_s}"
+          rescue MissingSourceFile => e
+            raise MissingSourceFile.new("#{e.message} (milton: couldn't find the processor '#{type}' you were trying to load)", e.path)
+          end
+          klass = "Milton::#{type.to_s.classify}".constantize
+        end
+        
+        klass.new(source, options, settings)
+      end
+    end
+
+    attr_reader :options, :settings
+
+    # Instantiate a new Derivative:
+    # * +source+: a reference to the Storage::StoredFile this will be a Derivative of
+    # * +options+: options to generate the Derivative using
+    # * +settings+: settings about how to create Derivatives
+    def initialize(source, options={}, settings={})
+      @source   = source
+      @options  = options.is_a?(String) ? self.class.options_from(options) : options
+      @settings = settings
+    end
+
+    # The resulting filename of this Derivative with embedded options.
+    def filename
+      # ignore false booleans and don't output =true for true booleans,
+      # otherwise just k=v
+      append    = options.reject{ |k, v| v.is_a?(FalseClass) }.collect { |k, v| v === true ? k.to_s : "#{k}=#{v}" }.sort.join('_')
+      extension = File.extname(@source.path)
+      File.basename(@source.path, extension) + (append.blank? ? '' : "#{settings[:separator]}#{append}") + extension
+    end
+
+    # The full path and filename to this Derivative.
+    def path
+      file.path
+    end
+    
+    # Returns true if this Derivative has already been generated and stored.
+    def exists?
+      file.exists?
+    end
+    
+    # Overwrite this to provide your derivatives processing.
+    def process;end;
+    
+    # Convenience method, only runs process if the given condition is true.
+    # Returns the derivative so it's chainable.
+    def process_if(condition)
+      process if condition && !exists?
+      return self
+    end
+    
+    # Returns the StoredFile which represents the Derivative (which is a copy
+    # of the source w/ a different filename).
+    def file
+      @file ||= @source.clone(filename)
+    end
+  end
+end

data/lib/milton/derivatives/thumbnail.rb

@@ -0,0 +1,39 @@
+require 'milton/derivatives/thumbnail/image'
+require 'milton/derivatives/thumbnail/crop_calculator'
+
+module Milton
+  class Thumbnail < Derivative
+    def process
+      raise "target size must be specified for resizing" unless options.has_key?(:size)
+      
+      temp_dst = File.join(settings[:tempfile_path], Milton::Tempfile.from(@source.filename))
+      temp_src = File.join(settings[:tempfile_path], Milton::Tempfile.from(@source.filename))
+      
+      @source.copy(temp_src)
+      image = Image.from_path(temp_src)
+      
+      # TODO: this really only makes sense for processing recipes, reimplement
+      # once it's setup to build all derivatives then push to storage
+      # 
+      # For speed, any derivatives less than 640-wide are made from a 
+      # 640-wide version of the image (so you're not generating tiny
+      # thumbnails from an 8-megapixel upload)
+      # source = if image.width > 640 && Image.from_geometry(options[:size]).width < 640
+      #   Thumbnail.process(@source, { :size => '640x' }, settings).file
+      # else
+      #   @source
+      # end
+      
+      if options[:crop]
+        crop = CropCalculator.new(image, Image.from_geometry(options[:size]))
+        size = crop.resizing_geometry
+        conversion_options = %Q(-gravity #{crop.gravity} -crop #{crop.cropping_geometry})
+      end
+      
+      Milton.syscall!(%Q{convert #{temp_src} -geometry #{size || options[:size]} #{conversion_options || ''} +repage "#{temp_dst}"})
+    
+      # TODO: raise if the store fails
+      file.store(temp_dst)
+    end
+  end
+end

data/lib/milton/derivatives/thumbnail/crop_calculator.rb

@@ -0,0 +1,64 @@
+module Milton
+  class CropCalculator
+    attr_reader :original, :target
+
+    # Initializes a new CropCalculator with the two given Images.
+    #
+    # A CropCalculator is used to calculate the proper zoom/crop dimensions
+    # to be passed to ImageMagick's convert method in order to transform
+    # the original Image's dimensions into the target Image's dimensions
+    # with sensible zoom/cropping.
+    def initialize(original, target)
+      @original = original
+      @target   = target
+    end
+
+    # Returns the geometry string to send to ImageMagick's convert -resize
+    # argument -- that is, the dimensions that the original Image would
+    # need to be resized to in order to result in the given target Image's
+    # dimensions with cropping.
+    def resizing_geometry
+      case
+        when original.wider? then "#{resized_width}x#{target.height}"
+        when original.square? && target.wider? then "#{target.width}x#{resized_height}"
+        when original.square? && !target.wider? then "#{resized_width}x#{target.height}"
+        else "#{target.width}x#{resized_height}"
+      end
+    end
+
+    # The geometry string to send to ImageMagick's convert -crop argument.
+    def cropping_geometry
+      "#{target.width}x#{target.height}+0+0"
+    end
+
+    # The gravity to use for cropping.
+    def gravity
+      original.wider? ? "center" : "north"
+    end
+
+    private
+
+    def resized_width
+      (target.height * original.width / original.height).to_i
+    end
+
+    def resized_height
+      (target.width * original.height / original.width).to_i
+    end
+
+    # TODO: this is the old-school cropping w/ coords, need to implement
+    # cropping w/ coords using the new system calls
+    # def crop_with_coordinates(img, x, y, size, options={})
+    #   gravity = options[:gravity] || Magick::NorthGravity
+    #   cropped_img = nil
+    #   img = Magick::Image.read(img).first unless img.is_a?(Magick::Image)
+    #   szx, szy = img.columns, img.rows
+    #   sz = self.class.get_size_from_parameter(size)
+    #   # logger.info "crop_with_coordinates: img.crop!(#{x}, #{y}, #{sz[0]}, #{sz[1]}, true)"
+    #   # cropped_img = img.resize!(sz[0], sz[1]) # EEEEEK
+    #   cropped_img = img.crop!(x, y, szx, szy, true)
+    #   cropped_img.crop_resized!(sz[0], sz[1], gravity) # EEEEEK
+    #   self.temp_path = write_to_temp_file(cropped_img.to_blob)
+    # end
+  end
+end