adrift 0.0.1

data/lib/adrift/file_to_attach.rb

@@ -0,0 +1,121 @@
+module Adrift
+  class UnknownFileRepresentationError < StandardError
+  end
+
+  # Factory of the objects that Attachment#assign expects.  Theese are
+  # adapters for the Rack and Rails' uploaded file representations and
+  # File instances.
+  module FileToAttach
+    # Common adapter behaviour for the files who will be attached.
+    module Adapter
+      # Creates a new Adapter for the +file_representation+.
+      def initialize(file_representation)
+        @file_representation = file_representation
+      end
+    end
+
+    # Namespace containing the adapters for the objects that
+    # Attachment#assign expects.  They need to respond to
+    # :original_filename and :path (what theese methods return it's
+    # pretty much self-explanatory).
+    module Adapters
+      # Adapter that allows to attach an uploaded file within a Rack
+      # (non-Rails) application.
+      class Rack
+        include Adapter
+
+        # Indicates whether or not +file_representation+ is an
+        # uploaded file within a Rack application.
+        def self.recognize?(file_representation)
+          file_representation.respond_to?(:has_key?) &&
+            file_representation.has_key?(:filename) &&
+            file_representation.has_key?(:tempfile)
+        end
+
+        # Uploaded file's original filename.
+        def original_filename
+          @file_representation[:filename]
+        end
+
+        # Uploaded file's path.
+        def path
+          @file_representation[:tempfile].path
+        end
+      end
+
+      # Adapter that allows to attach an uploaded file within a Rails
+      # application.
+      class Rails
+        include Adapter
+
+        # Indicates whether or not +file_representation+ is an
+        # uploaded file within a Rails application.
+        def self.recognize?(file_representation)
+          file_representation.respond_to?(:original_filename) &&
+            file_representation.respond_to?(:tempfile)
+        end
+
+        # Uploaded file's original filename.
+        def original_filename
+          @file_representation.original_filename
+        end
+
+        # Uploaded file's path.
+        def path
+          @file_representation.tempfile.path
+        end
+      end
+
+      # Adapter that allow to attach a local file.
+      class LocalFile
+        include Adapter
+
+        # Indicates whether or not +file_representation+ is a local
+        # file.
+        def self.recognize?(file_representation)
+          file_representation.respond_to?(:to_path)
+        end
+
+        # Local file's name.
+        def original_filename
+          ::File.basename(@file_representation.to_path)
+        end
+
+        # Local file's path.
+        def path
+          @file_representation.to_path
+        end
+      end
+    end
+
+    # Creates a new object that will that will act as an adapter for
+    # +file_representation+, the object that represents the file to be
+    # attached.  This adapter wil have the interface expected by
+    # Attachment#assign.
+    #
+    # Raises Adrift::UnknownFileRepresentationError when it can't
+    # recognize +file_representation+.
+    def self.new(file_representation)
+      adapter_class = find_adapter_class(file_representation)
+      raise UnknownFileRepresentationError if adapter_class.nil?
+      adapter_class.new(file_representation)
+    end
+
+  private
+
+    # Finds the class of the object who will act as an adapter for
+    # +file_representation+.
+    def self.find_adapter_class(file_representation)
+      adapter_classes.find do |adapter|
+        adapter.respond_to?(:recognize?) &&
+          adapter.recognize?(file_representation)
+      end
+    end
+
+    # Lists the classes of the objects that act as adapters for the
+    # file representations.
+    def self.adapter_classes
+      Adapters.constants.map { |class_name| Adapters.const_get(class_name) }
+    end
+  end
+end

data/lib/adrift/integration.rb

@@ -0,0 +1,39 @@
+require 'adrift/integration/active_record'
+require 'adrift/integration/data_mapper'
+
+module Adrift
+  # Namespace for the modules that ease the usage of Adrift in
+  # conjuction with ORM libraries.
+  #
+  # This won't be loaded by default. In order to automatically try to
+  # integrate Adrift with the ORM library in use (just ActiveRecord or
+  # DataMapper for now), it is necessary to require this feature
+  # manually:
+  #
+  #     require 'adrift/integration'
+  #
+  # It is also possible to request Adrift to integrate with a specific
+  # library by requiring the corresponding integration feature:
+  #
+  #     require 'adrift/integration/active_record'
+  #     require 'adrift/integration/data_mapper'
+  #
+  # In order to any of this to work, the ORM library must be loaded
+  # before Adrift.  However, if (for whatever reason) that isn't the
+  # case, besides requiring the integration for the library, it must
+  # be installed by calling +install+ on the appropiate module.  For
+  # instance, to integrate Adrift with ActiveRecord:
+  #
+  #     require 'adrift/integration/active_record'
+  #     Adrift::Integration::ActiveRecord.install
+  #
+  # When the integration is ready, Base#attachment will become
+  # available as a method of the model classes.  For instance, when
+  # using ActiveRecord:
+  #
+  #     class User < ActiveRecord::Base
+  #       attachment :avatar
+  #     end
+  module Integration
+  end
+end

data/lib/adrift/integration/active_record.rb

@@ -0,0 +1,29 @@
+require 'adrift/integration/base'
+
+module Adrift
+  module Integration
+    # Integrates Adrift with ActiveRecord.
+    module ActiveRecord
+      include Base
+
+      # Does everything Base#attachment does, but it also registers
+      # the callbacks to save the attachments when the model is saved,
+      # and to destroy them, when it is destroyed.
+      def attachment(*)
+        super
+        after_save     :save_attachments
+        before_destroy :destroy_attachments
+      end
+
+      # Integrates Adrift with ActiveRecord if it has been loaded.
+      def self.install
+        if defined?(::ActiveRecord::Base)
+          ::ActiveRecord::Base.send(:extend, self)
+        end
+      end
+
+      install
+
+    end
+  end
+end

data/lib/adrift/integration/base.rb

@@ -0,0 +1,87 @@
+module Adrift
+  module Integration
+    # Common integration code.
+    module Base
+      # Methods that handle the communication with the Attachments of
+      # a given model.
+      #
+      # They are included in the model class by Base#attachment.
+      module InstanceMethods
+        # Attachment objects that belongs to the model.  It needs the
+        # model class to be able to respond to
+        # +attachment_definitions+ with a Hash where the keys are the
+        # Attachment names.
+        def attachments
+          self.class.attachment_definitions.keys.map { |name| send(name) }
+        end
+
+        # Sends +message+ to the Attachment objects that belongs to
+        # the model.
+        def send_to_attachments(message)
+          attachments.each { |attachment| attachment.send(message) }
+        end
+
+        # Sends the message :save to the Attachment objects that
+        # belongs to the model.
+        def save_attachments
+          send_to_attachments(:save)
+        end
+
+        # Sends the message :destroy to the Attachment objects that
+        # belongs to the model.
+        def destroy_attachments
+          send_to_attachments(:destroy)
+        end
+      end
+
+      # Defines accessor methods for the Attachment, includes
+      # InstanceMethods in the model class, and stores the attachment
+      # +name+ and +options+ for future reference (see
+      # #attachment_definitions).
+      #
+      # +name+ and +options+ are the arguments that Attachment::new
+      # expects, and receives, with the exception that it accepts an
+      # <tt>:class</tt> option with a custom class to use instead of
+      # Attachment.  In that case, <tt>options[:class]</tt> will
+      # receive +new+ with +name+, the model, and +options+ without
+      # +:class+.
+      #
+      # The accessor methods are named after the Attachment. For
+      # instance, the following code will define +avatar+ and
+      # <tt>avatar=</tt> on the model class that receives #attachment:
+      #
+      #     attachment :avatar
+      #
+      # The writter method (in the example: <tt>avatar=</tt>) will
+      # assign to the Attachment the results of calling
+      # FileToAttach::new with its argument.  See Attachment#assign
+      # for more details.
+      def attachment(name, options={})
+        include InstanceMethods
+
+        attachment_definitions[name] = options.dup
+        attachment_class = options.delete(:class) || Attachment
+
+        define_method(name) do
+          instance_variable = "@#{name}_attachment"
+          unless instance_variable_defined?(instance_variable)
+            attachment = attachment_class.new(name, self, options)
+            instance_variable_set(instance_variable, attachment)
+          end
+          instance_variable_get(instance_variable)
+        end
+
+        define_method("#{name}=") do |file_representation|
+          send(name).assign(FileToAttach.new(file_representation))
+        end
+      end
+
+      # Attachment definitions for the model.  Is a Hash where the
+      # keys are the +names+ and the values are the +options+ passed
+      # to #attachment.
+      def attachment_definitions
+        @attachment_definitions ||= {}
+      end
+    end
+  end
+end

data/lib/adrift/integration/data_mapper.rb

@@ -0,0 +1,29 @@
+require 'adrift/integration/base'
+
+module Adrift
+  module Integration
+    # Integrates Adrift with DataMapper.
+    module DataMapper
+      include Base
+
+      # Does everything Base#attachment does, but it also registers
+      # the callbacks to save the attachments when the model is saved,
+      # and to destroy them, when it is destroyed.
+      def attachment(*)
+        super
+        after  :save,    :save_attachments
+        before :destroy, :destroy_attachments
+      end
+
+      # Integrates Adrift with DataMapper if it has been loaded.
+      def self.install
+        if defined?(::DataMapper::Model)
+          ::DataMapper::Model.append_extensions(self) 
+        end
+      end
+
+      install
+
+    end
+  end
+end

data/lib/adrift/pattern.rb

@@ -0,0 +1,219 @@
+require 'active_support/inflector'
+
+module Adrift
+  # Provides a way for Attachment to generally define its paths and
+  # urls, allowing to specialize them for every individual instance.
+  #
+  # In order to do this, a Pattern is build from a String comprised of
+  # Tags (or more precisely, their labels) and when is asked to be
+  # specialized for a given Attachment and style, it replaces these
+  # Tags with they specialized values for that Attachment and that
+  # style.
+  class Pattern
+    # Namespace containing the Tag objects used by Pattern.
+    #
+    # They are the building blocks of a Pattern.  A Pattern is
+    # specialized by specializing the Tags that appear in its
+    # string. They need to satisfy the following interface:
+    #
+    # [+#label+]
+    #   Portion of Pattern#string that is replaced with the returned
+    #   value of +#specialize+.
+    #
+    # [<tt>#specialize(options)</tt>]
+    #   Value that will replace the label in the Pattern (+options+
+    #   are the same passed to Pattern#specialize).
+    module Tags
+      # Pattern's tag that allows to generally express the
+      # Attachment's name.
+      class Attachment
+        # Portion of Pattern#string that will be replaced.
+        def label
+          ':attachment'
+        end
+
+        # Pluralized Attachment's name.  Expects +options+ to include
+        # the Attachment (+:attachment+ key).
+        def specialize(options={})
+          options[:attachment].name.to_s.underscore.pluralize
+        end
+      end
+
+      # Pattern's tag that allows to generally express the selected
+      # style.
+      class Style
+        # Portion of Pattern#string that will be replaced.
+        def label
+          ':style'
+        end
+
+        # Selected style, expects +options+ to include it (+:style+
+        # key).
+        def specialize(options={})
+          options[:style].to_s
+        end
+      end
+
+      # Pattern's tag that allows to generally express the
+      # Attachment's url.
+      class Url
+        # Portion of Pattern#string that will be replaced.
+        def label
+          ':url'
+        end
+
+        # Attachment's url.  Expects +options+ to include the
+        # Attachment (+:attachment+ key), and the selected style
+        # (+:style+ key). .
+        def specialize(options={})
+          options[:attachment].url(options[:style]).to_s
+        end
+      end
+
+      # Pattern's tag that allows to generally express the model's to
+      # which the Attachment belongs class name including its namespace.
+      class Class
+        # Portion of Pattern#string that will be replaced.
+        def label
+          ':class'
+        end
+
+        # Pluralized model's class name namespaced.  Expects +options+
+        # to include the Attachment (+:attachment+ key).
+        def specialize(options={})
+          options[:attachment].model.class.name.underscore.pluralize
+        end
+      end
+
+      # Pattern's tag that allows to generally express the model's to
+      # which the Attachment belongs class name, without its
+      # namespace.
+      class ClassName
+        # Portion of Pattern#string that will be replaced.
+        def label
+          ':class_name'
+        end
+
+        # Pluralized model's class name no namespaced.  Expects
+        # +options+ to include the Attachment (+:attachment+ key).
+        def specialize(options={})
+          options[:attachment].model.class.name.demodulize.underscore.pluralize
+        end
+      end
+
+      # Pattern's tag that allows to generally express the model's to
+      # which the Attachment belongs ID.
+      class Id
+        # Portion of Pattern#string that will be replaced.
+        def label
+          ':id'
+        end
+
+        # Model's ID.  Expects +options+ to include the Attachment
+        # (+:attachment+ key).
+        def specialize(options={})
+          options[:attachment].model.id.to_s
+        end
+      end
+
+      # Pattern's tag that represents the application root directory.
+      class Root
+        class << self
+          attr_accessor :path
+        end
+
+        # Portion of Pattern#string that will be replaced.
+        def label
+          ':root'
+        end
+
+        # Returns Adrift::Pattern::Tags::Root.path when defined, '.'
+        # otherwise.
+        def specialize(*)
+          self.class.path || '.'
+        end
+      end
+
+      # Pattern's tag that allows to generally express the
+      # Attachment's file name.
+      class Filename
+        # Portion of Pattern#string that will be replaced.
+        def label
+          ':filename'
+        end
+
+        # Attachment's filename.  Expects +options+ to include the
+        # Attachment (+:attachment+ key).
+        def specialize(options={})
+          options[:attachment].filename.to_s
+        end
+      end
+
+      # Pattern's tag that allows to generally express the
+      # Attachment's file base name.
+      class Basename
+        # Portion of Pattern#string that will be replaced.
+        def label
+          ':basename'
+        end
+
+        # Attachment's file base name.  Expects +options+ to include
+        # the Attachment (+:attachment+ key).
+        def specialize(options={})
+          filename = options[:attachment].filename.to_s
+          filename.sub(File.extname(filename), '')
+        end
+      end
+
+      # Pattern's tag that allows to generally express the
+      # Attachment's extension.
+      class Extension
+        # Portion of Pattern#string that will be replaced.
+        def label
+          ':extension'
+        end
+
+        # Attachment's file extension.  Expects +options+ to include
+        # the Attachment (+:attachment+ key).
+        def specialize(options={})
+          File.extname(options[:attachment].filename.to_s).sub('.', '')
+        end
+      end
+    end
+
+    # Tags every instance of Pattern will be able to recognize (and
+    # specialize).
+    def self.tags
+      @tags ||= []
+    end
+
+    attr_reader :string
+
+    # Creates a new Pattern from a +string+ comprised of one o more
+    # tag's labels.
+    def initialize(string)
+      @string = string.dup
+    end
+
+    # Returns #string with the known Tags replaced with their specific
+    # values the given +options+.  While +options+ is just a Hash,
+    # it's expected to include the Attachment this Pattern belongs to
+    # (+:attachment+ key), and the selected style (+:style+ key).
+    def specialize(options={})
+      sorted_tags.inject(string) do |result, tag|
+        result.gsub(tag.label) { tag.specialize(options) }
+      end
+    end
+
+  private
+
+    # Known Tags sorted in reverse label order.
+    def sorted_tags
+      self.class.tags.sort_by(&:label).reverse
+    end
+  end
+
+  Pattern::Tags.constants.each do |class_name|
+    Pattern.tags << Pattern::Tags.const_get(class_name).new
+  end
+end