adrift 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+doc/*
+pkg/*
+*.gem
+.bundle
+.rvmrc
+Gemfile.lock

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Gabriel Andretta
+
+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.rdoc

@@ -0,0 +1,10 @@
+= Adrift
+
+Adrift is a DIY library to ease attaching files to a model.
+
+It currently works only with ActiveRecord and DataMapper within Rails
+or Sinatra, but it should be pretty adaptable to another environment.
+
+== License
+
+Adrift is released under MIT license.  See LICENSE.

data/Rakefile

@@ -0,0 +1,22 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+require 'cucumber'
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new(:features)
+
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'Adrift'
+  rdoc.main     = 'README.rdoc'
+
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('LICENSE')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :default => :spec

data/adrift.gemspec

@@ -0,0 +1,38 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "adrift/version"
+
+Gem::Specification.new do |s|
+  s.name        = "adrift"
+  s.version     = Adrift::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Gabriel Andretta"]
+  s.email       = ["ohhgabriel@gmail.com"]
+  s.homepage    = ""
+  s.summary     = "Simplistic attachment management"
+  s.description = "Simplistic attachment management"
+
+  s.rubyforge_project = "adrift"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {spec,features}/*`.split("\n")
+
+  s.require_paths = ["lib"]
+
+  s.has_rdoc = true
+
+  s.add_dependency 'activesupport', '~>3.0'
+  s.add_dependency 'i18n'
+
+  s.add_development_dependency 'rspec', '~>2.4'
+  s.add_development_dependency 'cucumber', '~>0.10'
+  s.add_development_dependency 'activerecord', '~>3.0'
+  s.add_development_dependency 'dm-core', '~>1.0'
+  s.add_development_dependency 'dm-migrations'
+  s.add_development_dependency 'dm-validations'
+  s.add_development_dependency 'dm-sqlite-adapter'
+  s.add_development_dependency 'sqlite3'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'ZenTest'
+  s.add_development_dependency 'rdoc', '~>3.5'
+end

data/autotest/discover.rb

@@ -0,0 +1 @@
+Autotest.add_discovery { "rspec2" }

data/features/active_record_integration.feature

@@ -0,0 +1,42 @@
+Feature: ActiveRecord integration
+
+  In order to handle file attachments easily
+  As a Ruby developer using ActiveRecord
+  I want to let Adrift do the dirty work
+
+  Scenario: A file is attached
+    Given I instantiate an active record model
+    When I attach a file to it
+    And I save it
+    Then the file should be stored
+
+  Scenario: A file is attached to an invalid model
+    Given I instantiate an invalid active record model
+    When I attach a file to it
+    And I try to save it
+    Then it should not be saved
+    And the file should not be stored
+
+  Scenario: Two files are attached
+    Given I instantiate an active record model
+    When I attach a file to it
+    And I save it
+    And I attach another file to it
+    And I save it again
+    Then the first file should not still be stored
+    And the second file should be stored
+
+  Scenario: A file is detached
+    Given I instantiate an active record model
+    When I attach a file to it
+    And I save it
+    And I detach the file from it
+    And I save it
+    Then the file should not still be stored
+
+  Scenario: A model with an attached file is destroyed
+    Given I instantiate an active record model
+    When I attach a file to it
+    And I save it
+    And I destroy it
+    Then the file should not still be stored

data/features/data_mapper_integration.feature

@@ -0,0 +1,42 @@
+Feature: DataMapper integration
+
+  In order to handle file attachments easily
+  As a Ruby developer using DataMapper
+  I want to let Adrift do the dirty work
+
+  Scenario: A file is attached
+    Given I instantiate a data mapper model
+    When I attach a file to it
+    And I save it
+    Then the file should be stored
+
+  Scenario: A file is attached to an invalid model
+    Given I instantiate an invalid data mapper model
+    When I attach a file to it
+    And I try to save it
+    Then it should not be saved
+    And the file should not be stored
+
+  Scenario: Two files are attached
+    Given I instantiate a data mapper model
+    When I attach a file to it
+    And I save it
+    And I attach another file to it
+    And I save it again
+    Then the first file should not still be stored
+    And the second file should be stored
+
+  Scenario: A file is detached
+    Given I instantiate a data mapper model
+    When I attach a file to it
+    And I save it
+    And I detach the file from it
+    And I save it
+    Then the file should not still be stored
+
+  Scenario: A model with an attached file is destroyed
+    Given I instantiate a data mapper model
+    When I attach a file to it
+    And I save it
+    And I destroy it
+    Then the file should not still be stored

data/features/step_definitions/model_steps.rb

@@ -0,0 +1,54 @@
+Given /^I instantiate an active record model$/ do
+  instantiate :active_record
+end
+
+Given /^I instantiate an invalid active record model$/ do
+  instantiate :active_record, :valid => false
+end
+
+Given /^I instantiate a data mapper model$/ do
+  instantiate :data_mapper
+end
+
+Given /^I instantiate an invalid data mapper model$/ do
+  instantiate :data_mapper, :valid => false
+end
+
+When /^I attach a(?:nother)? file to it$/ do
+  attach(attached? ? other_original_file : original_file)
+end
+
+When /^I(?: try to)? save it(?: again)?$/ do
+  instance.save
+end
+
+When /^I destroy it$/ do
+  instance.destroy
+end
+
+When /^I detach the file from it$/ do
+  detach
+end
+
+Then /^it should not be saved$/ do
+  if instance.respond_to?(:persisted?)
+    instance.should_not be_persisted
+  else
+    instance.should_not be_saved
+  end
+end
+
+Then /^the(?: second)? file should be stored$/ do
+  File.exist?(last_attachment).should be_true
+  read_file(last_attachment).should == read_file(last_file)
+end
+
+Then /^the file should not(?: still)? be stored$/ do
+  last_attachment.should_not be_nil
+  File.exist?(last_attachment).should be_false
+end
+
+Then /^the first file should not still be stored$/ do
+  first_attachment.should_not be_nil
+  File.exist?(first_attachment).should be_false
+end

data/features/support/env.rb

@@ -0,0 +1,55 @@
+$:.unshift File.expand_path('../../../lib', __FILE__)
+require 'cucumber'
+require 'adrift'
+require 'adrift/integration'
+
+require 'active_record'
+Adrift::Integration::ActiveRecord.install
+
+ActiveRecord::Base.establish_connection(
+  :adapter => 'sqlite3',
+  :database => '/tmp/adrift-activerecord.sqlite3'
+)
+
+ActiveRecord::Migration.verbose = false
+
+ActiveRecord::Schema.define(:version => 1) do
+  create_table 'ar_users', :force => true do |t|
+    t.string 'name'
+    t.string 'avatar_filename'
+  end
+end
+
+class ARUser < ActiveRecord::Base
+  validates :name, :presence => true
+  attachment :avatar
+end
+
+require 'dm-core'
+require 'dm-validations'
+require 'dm-migrations'
+Adrift::Integration::DataMapper.install
+
+DataMapper.setup(:default, 'sqlite::memory:')
+
+class DMUser
+  include DataMapper::Resource
+
+  property :id,              Serial
+  property :name,            String
+  property :avatar_filename, String
+
+  validates_presence_of :name
+
+  attachment :avatar
+end
+
+DataMapper.finalize
+DataMapper.auto_migrate!
+
+Before do
+  ARUser.delete_all
+  DMUser.destroy
+end
+
+After  { system 'rm -rf public' }

data/features/support/world.rb

@@ -0,0 +1,58 @@
+module Adrift
+  module Cucumber
+    module Attachment
+      def read_file(path)
+        File.open(path, 'rb') { |io| io.read }
+      end
+
+      def original_file
+        'spec/fixtures/me.png'
+      end
+
+      def other_original_file
+        'spec/fixtures/me_no_colors.png'
+      end
+    end
+
+    module Model
+      attr_accessor :instance, :last_file, :last_attachment, :first_file,
+                    :first_attachment
+
+      def instantiate(orm, opts={ :valid => true })
+        @last_id ||= 0
+        self.instance = class_for(orm).new.tap do |user|
+          user.id   = @last_id += 1
+          user.name = 'ohhgabriel' if opts[:valid]
+        end
+      end
+
+      def attached?
+        !last_file.nil?
+      end
+
+      def attach(path)
+        instance.avatar = File.new(path)
+        if first_file.nil?
+          self.first_file = last_file
+          self.first_attachment = last_attachment
+        end
+        self.last_file = path
+        self.last_attachment = instance.avatar.path
+      end
+
+      def detach
+        instance.avatar.destroy
+      end
+
+      def class_for(orm)
+        case orm
+        when :active_record then ARUser
+        when :data_mapper   then DMUser
+        end
+      end
+    end
+  end
+end
+
+World(Adrift::Cucumber::Attachment)
+World(Adrift::Cucumber::Model)

data/lib/adrift.rb

@@ -0,0 +1,10 @@
+require 'adrift/attachment'
+require 'adrift/file_to_attach'
+require 'adrift/pattern'
+require 'adrift/processor'
+require 'adrift/storage'
+
+require 'adrift/railtie' if defined?(Rails::Railtie)
+
+module Adrift
+end

data/lib/adrift/attachment.rb

@@ -0,0 +1,246 @@
+module Adrift
+  # Handles attaching files to a model, allowing to automatically
+  # create different stlyes (versions) of them.
+  #
+  # Actually, this class's responsibility consist in just directing
+  # this process: it relies on a #storage object, for saving and
+  # removing the attached files, and on a #processor object, for the
+  # task of generating the different versions of a file from the given
+  # style definitions.
+  #
+  # Also, it provides a naive pattern mechanism to express the
+  # attachment's #path and #url.
+  class Attachment
+    attr_accessor :default_style, :styles, :storage, :processor, :pattern_class
+    attr_writer   :default_url, :url, :path
+    attr_reader   :name, :model
+
+    # Allows to change the options used for every new attachment.  For
+    # instance, to change the +:default_style+ and +:path+ options:
+    #
+    #   Adrift::Attachment.config do
+    #     default_style :default
+    #     path '/custom/storage/path/:url'
+    #   end
+    #
+    # See ::default_options for a list of the supported options.
+    def self.config(&block)
+      config = BasicObject.new
+      def config.method_missing(m, *args)
+        options = Attachment.default_options
+        options[m] = args.first if options.has_key?(m)
+      end
+      config.instance_eval(&block)
+    end
+
+    # Default options for every new Attachment.  These are:
+    #
+    # [+:default_style+]
+    #   Style assumed by #url and #path when no one has been provided.
+    #
+    # [+:styles+]
+    #   Hash with the style definitions, they keys are the style
+    #   names, and the values whatever makes sense to the processor to
+    #   generate the alternate versions of the attached file.  By
+    #   default, they indicate the thumbnails dimmensions, for
+    #   instance:
+    #
+    #       styles: { small: '50x50', medium: '100x100' }
+    #
+    #   See Processor::Thumbnail for the details.
+    #
+    # [+:default_url+]
+    #   String pattern used to build the returned value of #url when
+    #   the attachment is empty.
+    #
+    # [+:url+]
+    #   String pattern used to build the returned value of #url when
+    #   the attachment is not empty.
+    #
+    # [+:path+]
+    #   String pattern used to build the path where the attachment
+    #   will be stored (and will be returned by #path).
+    #
+    #   *Note*: when having an attachment with more than one style,
+    #   the path must be unique for each one, otherwise the stored
+    #   files will be overwritten.  In the most common case, what this
+    #   means is just that the path option must have a +:style+ tag.
+    #
+    # [+:storage+]
+    #   Object delegated with the task of saving and removing files.
+    #   See Storage for details and Storage::Filesystem for an
+    #   implementation.
+    #
+    # [+:processor+]
+    #   Object delegated with the task of generating the alternate
+    #   versions of the attached file from the :styles.  See Processor
+    #   for details and Processor::Thumbnail for an implementation.
+    #
+    # [+:pattern_class+]
+    #   The class used to build the #url and #path of the Attachment
+    #   from the string patterns provided.
+    #
+    # See the source of this method to know the values of this
+    # options. Note that these values can be changed for every new
+    # attachment with ::config, or in a per-attachment basis, when
+    # they are constructed with ::new, or after, just calling the
+    # attachment's writer method named after the option.
+    def self.default_options
+      @default_options ||= {
+        :default_style => :original,
+        :styles        => {},
+        :default_url   => '/:attachment/:style/missing.png',
+        :url           => '/system/:attachment/:id/:style/:filename',
+        :path          => ':root/public:url',
+        :storage       => Proc.new { Storage::Filesystem.new },
+        :processor     => Proc.new { Processor::Thumbnail.new },
+        :pattern_class => Pattern
+      }
+    end
+
+    # Restores the attachment's options to their default values.  See
+    # the source of ::default_options to know what these default
+    # values are.
+    def self.reset_default_options
+      @default_options = nil
+    end
+
+    # Creates a new Attachment object. +name+ is the name of the
+    # Attachment, +model+ is the model object it's attached to, and
+    # +options+ is a Hash that lets customize the Attachment's
+    # behaviour.
+    #
+    # The +model+ object must allow reading and writing to an
+    # attribute called after the Attachment's +name+ which stores the
+    # attached file's name.  For instance, for an attachment named
+    # +avatar+, the +model+ needs to respond to the methods
+    # +avatar_filename+ and +avatar_filename=+.
+    #
+    # See ::default_options for a list of the supported +options+.
+    # The options passed here will overwrite the default ones.
+    def initialize(name, model, options={})
+      self.class.default_options.merge(options).each do |name, value|
+        writer_name = "#{name}="
+        if respond_to?(writer_name)
+          send writer_name, value.is_a?(Proc) ? value.call : value
+        end
+      end
+      @name, @model = name, model
+    end
+
+    # Indicates whether or not there are changes that need to be
+    # saved, that is, files that need to be processed and stored
+    # and/or removed.
+    def dirty?
+      !@file_to_attach.nil? || storage.dirty?
+    end
+
+    # Returns the attachment's url for the given +style+.  If no
+    # +style+ is given it assumes the +:default_style+ option.  Also,
+    # it uses the +:url+ or the +:default_url+ option, depending
+    # whether or not the attachment is empty.
+    def url(style=default_style)
+      specialize(empty? ? @default_url : @url, style)
+    end
+
+    # Returns the attachment's path for the given +style+.  If no
+    # +style+ is given it assumes +:default_style+ option.  When the
+    # attachment is empty it returns +nil+.
+    def path(style=default_style)
+      specialize(@path, style) unless empty?
+    end
+
+    # Makes +file_to_attach+ the new attached file, but it won't be
+    # stored nor processed until the attachment receives #save.  It
+    # also updates the model's attachment file name attribute.
+    #
+    # See FileToAttach::Adapters for the expected interface of
+    # +file_to_attach+.
+    def assign(file_to_attach)
+      enqueue_files_for_removal
+      model_send(
+        :filename=,
+        file_to_attach.original_filename.to_s.tr('^a-zA-Z0-9.', '_')
+      )
+      @file_to_attach = file_to_attach
+    end
+
+    # Throws away the current attached file, but it won't actually be
+    # removed until the attachment receives #save.  It also sets the
+    # model's attachment file name attribute to +nil+.
+    def clear
+      enqueue_files_for_removal
+      @file_to_attach = nil
+      model_send(:filename=, nil)
+    end
+
+    # When there is a new attached file will store and process it, and
+    # if there was a previous attached file it will also remove it.
+    # On the other hand it will remove the current attached file if it
+    # was thrown away (in other words, the attachment has received
+    # #clear).
+    #
+    # Generally, this will get called when the model is saved.
+    def save
+      unless @file_to_attach.nil?
+        processor.process(@file_to_attach.path, styles)
+        enqueue_files_for_storage
+      end
+      storage.flush
+      @file_to_attach = nil
+    end
+
+    # Removes the current attached file, setting the model's
+    # attachment file name attribute to +nil+.
+    def destroy
+      clear
+      save
+    end
+
+    # Indicates whether or not there is a file attached.  Note that a
+    # file could be attached without being stored or processed.
+    def empty?
+      filename.nil?
+    end
+
+    # Returns the attachment's file name.
+    def filename
+      model_send(:filename)
+    end
+
+  private
+
+    # Sends the message +message_without_prefix+ to the model,
+    # prefixed with the attachment's name, and passing the given
+    # +args+.
+    def model_send(message_without_prefix, *args)
+      model.public_send("#{name}_#{message_without_prefix}", *args)
+    end
+
+    # Specializes the string pattern +str+, for the attachment which
+    # receives this message and the given +style+.
+    def specialize(str, style)
+      pattern_class.new(str).specialize(:attachment => self, :style => style)
+    end
+
+    # Adds all the current attached files to the storage's removal
+    # queue, unless they don't exist or are already there.
+    def enqueue_files_for_removal
+      return if empty? || dirty?
+      [:original, *styles.keys].uniq.each { |style| storage.remove path(style) }
+    end
+
+    # Adds all the current attached files to the storage's queue.
+    def enqueue_files_for_storage
+      files_for_storage.each { |style, file| storage.store(file, path(style)) }
+    end
+
+    # Returns a hash containing the files that need to be stored as
+    # values and their styles as keys.
+    def files_for_storage
+      processor.processed_files.dup.tap do |files|
+        files[:original] ||= @file_to_attach.path
+      end
+    end
+  end
+end