jnicklas-carrierwave 0.1

data/Generators

@@ -0,0 +1,4 @@
+scope 'merb-gen' do
+  dir = File.join(File.dirname(__FILE__), 'lib', 'generators/')
+  Merb.add_generators dir + 'uploader_generator'
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 YOUR NAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,211 @@
+# CarrierWave
+
+This plugin for Merb and Rails provides a simple and extremely flexible way to upload files.
+
+## Getting Started
+
+At the moment you are going to have to grab it here from github and install it yourself.
+
+In Merb, add it as a dependency to your config/dependencies.rb:
+    
+    dependency 'carrierwave'
+
+In Rails, add it to your environment.rb:
+
+    config.gem "carrierwave"
+
+## Quick Start
+
+Start off by generating an uploader:
+
+    merb-gen uploader Avatar
+
+this should give you a file in:
+
+    app/uploaders/avatar_uploader.rb
+
+Check out this file for some hints on how you can customize your uploader. It should look something like this:
+
+    class AvatarUploader < CarrierWave::Uploader
+      storage :file
+    end
+
+You can use your uploader class to store and retrieve files like this:
+
+    uploader = AvatarUploader.new
+    
+    uploader.store!(my_file)
+    
+    uploader.retrieve_from_store!('my_file.png')
+
+CarrierWave gives you a `store` for permanent storage, and a `cache` for temporary storage. You can use different stores, at the moment a filesystem store and an Amazon S3 store are bundled.
+
+Most of the time you are going to want to use CarrierWave together with an ORM. It is quite simple to mount uploaders on columns in your model, so you can simply assign files and get going:
+
+### ActiveRecord
+
+First require the activerecord extension:
+
+    require 'carrierwave/orm/activerecord
+
+You don't need to do this if you are using Merb or Rails.
+
+Open your model file, and do something like:
+
+    class User < ActiveRecord::Base
+      mount_uploader :avatar, AvatarUploader
+    end
+
+Now you can upload files!
+
+    u = User.new
+    u.avatar = params[:file]
+    u.avatar = File.open('somewhere')
+    u.save!
+    u.avatar.url # => '/url/to/file.png'
+    u.avatar.current_path # => 'path/to/file.png'
+
+### DataMapper
+
+First require the activerecord extension:
+
+    require 'carrierwave/orm/datamapper
+
+You don't need to do this if you are using Merb or Rails.
+
+Open your model file, and do something like:
+
+    class User
+      include DataMapper::Resource
+
+      mount_uploader :avatar, AvatarUploader
+    end
+
+Now you can upload files!
+
+    u = User.new
+    u.avatar = params[:file]
+    u.avatar = File.open('somewhere')
+    u.save!
+    u.avatar.url # => '/url/to/file.png'
+    u.avatar.current_path # => 'path/to/file.png'
+
+## Changing the storage directory
+
+In order to change where uploaded files are put, just override the `store_dir` method:
+
+    class MyUploader < CarrierWave::Uploader
+      def store_dir
+        'public/my/upload/directory'
+      end
+    end
+
+This works for the file storage as well as Amazon S3.
+
+## Adding versions
+
+Often you'll want to add different versions of the same file. The classic example is image thumbnails. There is built in support for this:
+
+    class MyUploader < CarrierWave::Uploader
+      include CarrierWave::RMagick
+      
+      process :resize => [800, 800]
+
+      version :thumb do
+        process :crop_resized => [200,200]
+      end
+      
+    end
+
+When this uploader is used, an uploaded image would be scaled to be no larger than 800 by 800 pixels. A version called thumb is then created, which is scaled and cropped to exactly 200 by 200 pixels. The uploader could be used like this:
+
+    uploader = AvatarUploader.new
+    uploader.store!(my_file)                              # size: 1024x768
+    
+    uploader.url # => '/url/to/my_file.png'               # size: 800x600
+    uploader.thumb.url # => '/url/to/thumb_my_file.png'   # size: 200x200
+
+One important thing to remember is that process is called *before* versions are created. This can cut down on processing cost.
+
+## What's in that uploader file?
+
+The fact that uploaders are separate classes in CarrierWave is a big advantage. What this means for you is:
+
+#### Less magic
+
+In order to customize your uploader, all you need to do is override methods and use normal, clear and simple Ruby code. That means no `alias_method_chain`'ing to hook into the upload process, no messing around with weird extensions. The code in CarrierWave is very simple and easy because of this.
+
+#### Easier to test
+
+How do you test file uploads? I always found this ridiculously hard. A separate class means you can test is separately, which is nicer, easier and more maintainable.
+
+#### More Flexible
+
+Many of the things you can do in CarrierWave are hard, or impossible to do in other file upload plugins, and have previously required you to roll your own. Now you can get all the flexibility without having to write low level stuff.
+
+#### Easy to extend
+
+CarrierWave has support for a few different image manipulation libraries. These need *no* code to hook into CarrierWave, because they are simple modules. If you want to write your own manipulation library (doesn't need to be for images), you can do the same.
+
+## Using Amazon S3
+
+You'll need to configure a bucket, access id and secret key like this:
+
+    CarrierWave.config[:s3][:access_key_id] = 'xxxxxx'
+    CarrierWave.config[:s3][:secret_access_key] = 'xxxxxx'
+    CarrierWave.config[:s3][:bucket] = 'name_of_bucket'
+
+Do this in an initializer in Rails, and in a `before_app_loads` block in Merb.
+
+And then in your uploader, set the storage to :s3
+
+    class AvatarUploader < CarrierWave::Uploader
+      storage :s3
+    end
+
+That's it! You can still use the `CarrierWave::Uploader#url` method to return the url to the file on Amazon S3
+
+## Using RMagick
+
+If you're uploading images, you'll probably want to manipulate them in some way, you might want to create thumbnail images for example. CarrierWave comes with a small library to make manipulating images with RMagick easier. It's not loaded by default so you'll need to require it:
+
+    require 'carrierwave/processing/rmagick'
+
+You'll also need to include it in your Uploader:
+
+    class AvatarUploader < CarrierWave::Uploader
+      include CarrierWave::RMagick
+    end
+
+The RMagick module gives you a few methods, like `CarrierWave::RMagick#crop_resized` which manipulate the image file in some way. You can set a `process` callback, which will call that method any time a file is uploaded.
+
+    class AvatarUploader < CarrierWave::Uploader
+      include CarrierWave::RMagick
+      
+      process :crop_resized => [200, 200]
+      process :convert => 'png'
+      
+      def filename
+        super + '.png'
+      end
+    end
+
+Check out the manipulate! method, which makes it easy for you to write your own manipulation methods.
+
+## Using ImageScience
+
+ImageScience works the same way as RMagick. As with RMagick you'll need to require it:
+
+    require 'carrierwave/processing/image_science'
+
+And then include it in your model:
+
+    class AvatarUploader < CarrierWave::Uploader
+      include CarrierWave::ImageScience
+      
+      process :crop_resized => [200, 200]
+    end
+
+## Read the source
+
+CarrierWave is still young, but most of it is pretty well documented. Just dig in and look at the source for more in-depth explanation of what things are doing.

data/Rakefile

@@ -0,0 +1,96 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+
+require 'yard'
+require 'spec/rake/spectask'
+require 'cucumber/rake/task'
+
+NAME = "carrierwave"
+GEM_VERSION = "0.1"
+AUTHOR = "Jonas Nicklas"
+EMAIL = "jonas.nicklas@gmail.com"
+HOMEPAGE = "http://www.example.com"
+SUMMARY = "Simple and powerful uploads for Merb and Rails"
+
+spec = Gem::Specification.new do |s|
+  s.rubyforge_project = 'carrierwave'
+  s.name = NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README.md", "LICENSE", 'TODO']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  s.require_path = 'lib'
+  s.files = %w(LICENSE Generators README.md Rakefile TODO) + Dir.glob("{lib,spec}/**/*")
+  
+end
+
+# Try these:
+#
+# rake features
+# rake features PROFILE=html
+Cucumber::Rake::Task.new do |t|
+  profile = ENV['PROFILE'] || 'default'
+  t.cucumber_opts = "--profile #{profile}"
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ["README.md", "LICENSE", "TODO", 'lib/carrierwave/**/*.rb']
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "install the plugin locally"
+task :install => [:package] do
+  sh %{#{sudo} gem install #{install_home} pkg/#{NAME}-#{GEM_VERSION} --no-update-sources}
+end
+
+desc "create a gemspec file"
+task :make_spec do
+  File.open("#{NAME}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+namespace :jruby do
+
+  desc "Run :package and install the resulting .gem with jruby"
+  task :install => :package do
+    sh %{#{sudo} jruby -S gem install #{install_home} pkg/#{NAME}-#{GEM_VERSION}.gem --no-rdoc --no-ri}
+  end
+
+end
+
+file_list = FileList['spec/**/*_spec.rb']
+
+desc "Run all examples"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = file_list
+end
+
+namespace :spec do
+  desc "Run all examples with RCov"
+  Spec::Rake::SpecTask.new('rcov') do |t|
+    t.spec_files = file_list
+    t.rcov = true
+    t.rcov_dir = "doc/coverage"
+    t.rcov_opts = ['--exclude', 'spec']
+  end
+  
+  desc "Generate an html report"
+  Spec::Rake::SpecTask.new('report') do |t|
+    t.spec_files = file_list
+    t.spec_opts = ["--format", "html:doc/reports/specs.html"]
+    t.fail_on_error = false
+  end
+
+end
+
+desc 'Default: run unit tests.'
+task :default => 'spec'

data/lib/carrierwave/mount.rb

@@ -0,0 +1,93 @@
+module CarrierWave
+  
+  module Mount
+    module Extension
+    
+    private
+
+      def uploaders
+        @uploaders ||= {}
+      end
+    
+      def store_uploader!(column)
+        if uploaders[column]
+          uploaders[column].store!
+          write_uploader(column, uploaders[column].identifier)
+        end
+      end
+    
+      def get_uploader(column)
+        return uploaders[column] if uploaders[column]
+
+        identifier = read_uploader(column)
+      
+        unless identifier.blank?
+          uploaders[column] ||= self.class.uploaders[column].new(self, column)
+          uploaders[column].retrieve_from_store!(identifier)
+          uploaders[column]
+        end
+      end
+    
+      def set_uploader(column, new_file)
+        new_file = CarrierWave::SanitizedFile.new(new_file)
+      
+        unless new_file.empty?
+          uploaders[column] ||= self.class.uploaders[column].new(self, column)
+          uploaders[column].cache!(new_file) 
+        end
+      end
+    
+      def get_uploader_cache(column)
+        uploaders[column].cache_name if uploaders[column]
+      end
+
+      def set_uploader_cache(column, cache_name)
+        unless cache_name.blank?
+          uploaders[column] ||= self.class.uploaders[column].new(self, column)
+          uploaders[column].retrieve_from_cache(cache_name)
+        end
+      end
+
+    end # Extension
+  
+    def uploaders
+      @uploaders ||= {}
+    end
+  
+    def mount_uploader(column, uploader=nil, &block)
+      unless uploader
+        uploader = Class.new(CarrierWave::Uploader)
+        uploader.class_eval(&block)
+      end
+    
+      uploaders[column.to_sym] = uploader
+    
+      include CarrierWave::Mount::Extension
+    
+      class_eval <<-EOF, __FILE__, __LINE__+1
+        def #{column}                                     # def image
+          get_uploader(:#{column})                        #   get_uploader(:image)
+        end                                               # end
+                                                          #
+        def #{column}=(new_file)                          # def image=(new_file)
+          set_uploader(:#{column}, new_file)              #   set_uploader(:image, new_file)
+        end                                               # end
+                                                          #
+        def #{column}_cache                               # def image_cache
+          get_uploader_cache(:#{column})                  #   get_uploader_cache(:image)
+        end                                               # end
+                                                          #
+        def #{column}_cache=(cache_name)                  # def image_cache=(cache_name)
+          set_uploader_cache(:#{column}, cache_name)      #   set_uploader_cache(:image, cache_name)
+        end                                               # end
+                                                          #
+        def store_#{column}!                              # def store_image!
+          store_uploader!(:#{column})                     #   store_uploader!(:image)
+        end                                               # end
+      EOF
+    
+      after_mount(column, uploader) if respond_to?(:after_mount)
+    end
+  
+  end # Mount
+end # CarrierWave

data/lib/carrierwave/orm/activerecord.rb

@@ -0,0 +1,20 @@
+require 'activerecord'
+
+module CarrierWave
+  module ActiveRecord
+
+    include CarrierWave::Mount
+
+    def after_mount(column, uploader)
+      alias_method :read_uploader, :read_attribute
+      alias_method :write_uploader, :write_attribute
+
+      before_save do |record|
+        record.send("store_#{column}!")
+      end
+    end
+
+  end # ActiveRecord
+end # CarrierWave
+
+ActiveRecord::Base.send(:extend, CarrierWave::ActiveRecord)

data/lib/carrierwave/orm/datamapper.rb

@@ -0,0 +1,20 @@
+require 'dm-core'
+
+module CarrierWave
+  module DataMapper
+
+    include CarrierWave::Mount
+
+    def after_mount(column, uploader)
+      alias_method :read_uploader, :attribute_get
+      alias_method :write_uploader, :attribute_set
+
+      before :save do
+        send("store_#{column}!")
+      end
+    end
+
+  end # DataMapper
+end # CarrierWave
+
+DataMapper::Model.send(:include, CarrierWave::DataMapper)

data/lib/carrierwave/processing/image_science.rb

@@ -0,0 +1,70 @@
+require "image_science"
+
+module CarrierWave
+  module ImageScience
+    
+    # Resize the image so that it will not exceed the dimensions passed
+    # via geometry, geometry should be a string, formatted like '200x100' where
+    # the first number is the height and the second is the width
+    def resize!( geometry )
+      ::ImageScience.with_image(self.current_path) do |img|
+        width, height = extract_dimensions(img.width, img.height, geometry)
+        img.resize( width, height ) do |file|
+          file.save( self.current_path )
+        end
+      end
+    end
+
+    # Resize and crop the image so that it will have the exact dimensions passed
+    # via geometry, geometry should be a string, formatted like '200x100' where
+    # the first number is the height and the second is the width
+    def crop_resized!( geometry )
+      ::ImageScience.with_image(self.current_path) do |img|
+        new_width, new_height = geometry.split('x').map{|i| i.to_i }
+
+        width, height = extract_dimensions_for_crop(img.width, img.height, geometry)
+        x_offset, y_offset = extract_placement_for_crop(width, height, geometry)
+
+        img.resize( width, height ) do |i2|
+
+          i2.with_crop( x_offset, y_offset, new_width + x_offset, new_height + y_offset) do |file|
+            file.save( self.current_path )
+          end
+        end
+      end
+    end
+
+    private
+
+    def extract_dimensions(width, height, new_geometry, type = :resize)
+      new_width, new_height = convert_geometry(new_geometry)
+
+      aspect_ratio = width.to_f / height.to_f
+      new_aspect_ratio = new_width / new_height
+
+      if (new_aspect_ratio > aspect_ratio) ^ ( type == :crop )  # Image is too wide, the caret is the XOR operator
+        new_width, new_height = [ (new_height * aspect_ratio), new_height]
+      else #Image is too narrow
+        new_width, new_height = [ new_width, (new_width / aspect_ratio)]
+      end
+
+      [new_width, new_height].collect! { |v| v.round }
+    end
+
+    def extract_dimensions_for_crop(width, height, new_geometry)
+      extract_dimensions(width, height, new_geometry, :crop)
+    end
+
+    def extract_placement_for_crop(width, height, new_geometry)
+      new_width, new_height = convert_geometry(new_geometry)
+      x_offset = (width / 2.0) - (new_width / 2.0)
+      y_offset = (height / 2.0) - (new_height / 2.0)
+      [x_offset, y_offset].collect! { |v| v.round }
+    end
+
+    def convert_geometry(geometry)
+      geometry.split('x').map{|i| i.to_f }      
+    end
+
+  end # ImageScience
+end # CarrierWave