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,242 @@
+# 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
+
+or in Rails:
+
+    script/generate 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.
+
+## Making uploads work across form redisplays
+
+Often you'll notice that uploaded files disappear when a validation
+fails. CarrierWave has a feature that makes it easy to remember the
+uploaded file even in that case. Suppose your `user` model has an uploader mounted on `avatar` file, just add a hidden field called `avatar_cache`.
+In Rails, this would look like this:
+
+    <% form_for @user do |f| %>
+      <p>
+        <label>My Avatar</label>
+        <%= f.file_field :avatar %>
+        <%= f.hidden_field :avatar_cache %>
+      </p>
+    <% end %>
+
+It might be a good idea to show th user that a file has been uploaded,
+in the case of images, a small thumbnail would be a good indicator:
+
+    <% form_for @user do |f| %>
+      <p>
+        <label>My Avatar</label>
+        <%= image_tag(@user.avatar.url) if @user.avatar %>
+        <%= f.file_field :avatar %>
+        <%= f.hidden_field :avatar_cache %>
+      </p>
+    <% end %>
+
+## 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,rails_generators}/**/*")
+  
+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.rb

@@ -0,0 +1,67 @@
+require 'fileutils'
+
+module CarrierWave
+  class << self
+    attr_accessor :config
+  end
+  
+  class UploadError < StandardError; end
+  class NoFileError < UploadError; end
+  class FormNotMultipart < UploadError
+    def message
+      "You tried to assign a String or a Pathname to an uploader, for security reasons, this is not allowed.\n\n If this is a file upload, please check that your upload form is multipart encoded."
+    end
+  end
+  class InvalidParameter < UploadError; end
+  # Should be used by methods used as process callbacks.
+  class ProcessingError < UploadError; end
+end
+
+dir = File.join(File.dirname(__FILE__), 'carrierwave')
+
+require File.join(dir, 'sanitized_file')
+require File.join(dir, 'uploader')
+require File.join(dir, 'mount')
+require File.join(dir, 'storage', 'abstract')
+require File.join(dir, 'storage', 'file')
+require File.join(dir, 'storage', 's3')
+
+CarrierWave.config = {
+  :storage => :file,
+  :use_cache => true,
+  :storage_engines => {
+    :file => CarrierWave::Storage::File,
+    :s3 => CarrierWave::Storage::S3
+  },
+  :s3 => {
+    :access => :public_read
+  },
+  :store_dir => 'uploads',
+  :cache_dir => 'uploads/tmp'
+}
+
+if defined?(Merb)
+  CarrierWave.config[:root] = Merb.root
+  CarrierWave.config[:public] = Merb.dir_for(:public)
+  
+  orm_path = File.dirname(__FILE__) / 'carrierwave' / 'orm' / Merb.orm
+  require orm_path if File.exist?(orm_path + '.rb')
+  
+  Merb.push_path(:uploader, Merb.root / "app" / "uploaders")
+  
+  Merb.add_generators File.dirname(__FILE__) / 'generators' / 'uploader_generator'
+end
+
+if defined?(Rails)
+  CarrierWave.config[:root] = Rails.root
+  CarrierWave.config[:public] = File.join(Rails.root, 'public')
+  
+  require File.join(File.dirname(__FILE__), "carrierwave", "orm", 'activerecord')
+
+  ActiveSupport::Dependencies.load_paths << File.join(Rails.root, "app", "uploaders")
+end
+
+if defined?(Sinatra)
+  CarrierWave.config[:root] = Sinatra::Application.root
+  CarrierWave.config[:public] = Sinatra::Application.public
+end

data/lib/carrierwave/mount.rb

@@ -0,0 +1,153 @@
+module CarrierWave
+  
+  ##
+  # If a Class is extended with this module, it gains the mount_uploader
+  # method, which is used for mapping attributes to uploaders and allowing
+  # easy assignment.
+  #
+  # You can use mount_uploader with pretty much any class, however it is
+  # intended to be used with some kind of persistent storage, like an ORM.
+  # If you want to persist the uploaded files in a particular Class, it
+  # needs to implement a `read_uploader` and a `write_uploader` method.
+  #
+  module Mount
+
+    ##
+    # @return [Hash{Symbol => CarrierWave}] what uploaders are mounted on which columns
+    #
+    def uploaders
+      @uploaders ||= {}
+    end
+
+    ##
+    # Mounts the given uploader on the given column. This means that assigning
+    # and reading from the column will upload and retrieve files. Supposing
+    # that a User class has an uploader mounted on image, you can assign and
+    # retrieve files like this:
+    #
+    #     @user.image # => <Uploader>
+    #     @user.image = some_file_object
+    #
+    #     @user.store_image!
+    #
+    #     @user.image.url # => '/some_url.png'
+    #
+    # It is also possible (but not recommended) to ommit the uploader, which
+    # will create an anonymous uploader class. Passing a block to this method
+    # makes it possible to customize it. This can be convenient for brevity,
+    # but if there is any significatnt logic in the uploader, you should do
+    # the right thing and have it in its own file.
+    #
+    # @param [Symbol] column the attribute to mount this uploader on
+    # @param [CarrierWave::Uploader] uploader the uploader class to mount
+    # @param [Proc] &block customize anonymous uploaders
+    # @example
+    #     class Song
+    #       mount_uploader :lyrics, LyricsUploader
+    #       mount_uploader :file, SongUploader
+    #     end
+    # @example
+    #     class Data
+    #       # this will add an anonymous uploader with only
+    #       # the default settings
+    #       mount_uploader :csv
+    #     end
+    # @example
+    #     class Product
+    #       # this will add an anonymous uploader overriding
+    #       # the store_dir
+    #       mount_uploader :blueprint do
+    #         def store_dir
+    #           'blueprints'
+    #         end
+    #       end
+    #     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
+
+    module Extension
+    
+    private
+    
+      # overwrite this to read from a serialized attribute
+      def read_uploader(column); end
+
+      # overwrite this to write to a serialized attribute
+      def write_uploader(column, identifier); end
+
+      def uploaders
+        @uploaders ||= {}
+      end
+    
+      def store_uploader!(column)
+        unless uploaders[column].blank?
+          uploaders[column].store!
+          write_uploader(column, uploaders[column].identifier)
+        end
+      end
+    
+      def get_uploader(column)
+        return uploaders[column] unless uploaders[column].blank?
+
+        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)
+        uploaders[column] ||= self.class.uploaders[column].new(self, column)
+        uploaders[column].cache!(new_file)
+      end
+    
+      def get_uploader_cache(column)
+        uploaders[column].cache_name unless uploaders[column].blank?
+      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
+  
+  end # Mount
+end # CarrierWave