carrierwave 0.2.1 → 0.2.3

data/lib/carrierwave/uploader/cache.rb

@@ -0,0 +1,114 @@
+module CarrierWave
+  module Uploader
+    module Cache
+
+      depends_on CarrierWave::Uploader::Paths
+      depends_on CarrierWave::Uploader::Callbacks
+
+      ##
+      # Returns true if the uploader has been cached
+      #
+      # === Returns
+      #
+      # [Bool] whether the current file is cached
+      #
+      def cached?
+        @cache_id
+      end
+
+      ##
+      # Override this in your Uploader to change the directory where files are cached.
+      #
+      # === Returns
+      #
+      # [String] a directory
+      #
+      def cache_dir
+        CarrierWave.config[:cache_dir]
+      end
+
+      ##
+      # Returns a String which uniquely identifies the currently cached file for later retrieval
+      #
+      # === Returns
+      #
+      # [String] a cache name, in the format YYYYMMDD-HHMM-PID-RND/filename.txt
+      #
+      def cache_name
+        File.join(cache_id, full_original_filename) if cache_id and original_filename
+      end
+
+      ##
+      # Caches the given file. Calls process! to trigger any process callbacks.
+      #
+      # === Parameters
+      #
+      # [new_file (File, IOString, Tempfile)] any kind of file object
+      #
+      # === Raises
+      #
+      # [CarrierWave::FormNotMultipart] if the assigned parameter is a string
+      #
+      def cache!(new_file)
+        new_file = CarrierWave::SanitizedFile.new(new_file)
+        raise CarrierWave::FormNotMultipart if new_file.is_path?
+
+        unless new_file.empty?
+          with_callbacks(:cache, new_file) do
+            self.cache_id = CarrierWave.generate_cache_id unless cache_id
+
+            @filename = new_file.filename
+            self.original_filename = new_file.filename
+
+            if CarrierWave.config[:cache_to_cache_dir]
+              @file = new_file.copy_to(cache_path, CarrierWave.config[:permissions])
+            else
+              @file = new_file
+            end
+          end
+        end
+      end
+
+      ##
+      # Retrieves the file with the given cache_name from the cache.
+      #
+      # === Parameters
+      #
+      # [cache_name (String)] uniquely identifies a cache file
+      #
+      # === Raises
+      #
+      # [CarrierWave::InvalidParameter] if the cache_name is incorrectly formatted.
+      #
+      def retrieve_from_cache!(cache_name)
+        with_callbacks(:retrieve_from_cache, cache_name) do
+          self.cache_id, self.original_filename = cache_name.to_s.split('/', 2)
+          @filename = original_filename
+          @file = CarrierWave::SanitizedFile.new(cache_path)
+        end
+      end
+
+    private
+
+      def cache_path
+        File.expand_path(File.join(cache_dir, cache_name), public)
+      end
+
+      attr_reader :cache_id, :original_filename
+
+      # We can override the full_original_filename method in other modules
+      alias_method :full_original_filename, :original_filename
+
+      def cache_id=(cache_id)
+        raise CarrierWave::InvalidParameter, "invalid cache id" unless cache_id =~ /\A[\d]{8}\-[\d]{4}\-[\d]+\-[\d]{4}\z/
+        @cache_id = cache_id
+      end
+
+      def original_filename=(filename)
+        raise CarrierWave::InvalidParameter, "invalid filename" unless filename =~ /\A[a-z0-9\.\-\+_]+\z/i
+        @original_filename = filename
+      end
+
+    end # Cache
+  end # Uploader
+end # CarrierWave

data/lib/carrierwave/uploader/callbacks.rb

@@ -0,0 +1,40 @@
+module CarrierWave
+  module Uploader
+    module Callbacks
+
+      setup do
+        extlib_inheritable_accessor :_before_callbacks, :_after_callbacks
+      end
+
+      def with_callbacks(kind, *args)
+        self.class._before_callback(kind).each { |callback| self.send(callback, *args) }
+        yield
+        self.class._after_callback(kind).each { |callback| self.send(callback, *args) }
+      end
+
+      module ClassMethods
+        
+        def _before_callback(kind) #:nodoc:
+          self._before_callbacks ||= {}
+          self._before_callbacks[kind] ||= []
+          self._before_callbacks[kind]
+        end
+
+        def _after_callback(kind) #:nodoc:
+          self._after_callbacks ||= {}
+          self._after_callbacks[kind] ||= []
+          self._after_callbacks[kind]
+        end
+
+        def before(kind, callback)
+          _before_callback(kind) << callback
+        end
+
+        def after(kind, callback)
+          _after_callback(kind) << callback
+        end
+      end # ClassMethods
+
+    end # Url
+  end # Uploader
+end # CarrierWave

data/lib/carrierwave/uploader/default_path.rb

@@ -0,0 +1,21 @@
+module CarrierWave
+  module Uploader
+    module DefaultPath
+
+      def initialize(*args)
+        super
+        if default_path
+          @file = CarrierWave::SanitizedFile.new(File.expand_path(default_path, public))
+          def @file.blank?; true; end
+        end
+      end
+
+      ##
+      # Override this method in your uploader to provide a default path
+      # in case no file has been cached/stored yet.
+      #
+      def default_path; end
+
+    end # DefaultPath
+  end # Uploader
+end # CarrierWave

data/lib/carrierwave/uploader/extension_whitelist.rb

@@ -0,0 +1,35 @@
+module CarrierWave
+  module Uploader
+    module ExtensionWhitelist
+
+      setup do
+        before :cache, :check_whitelist!
+      end
+
+      ##
+      # Override this method in your uploader to provide a white list of extensions which
+      # are allowed to be uploaded.
+      #
+      # === Returns
+      #
+      # [NilClass, Array[String]] a white list of extensions which are allowed to be uploaded
+      #
+      # === Examples
+      #
+      #     def extension_white_list
+      #       %w(jpg jpeg gif png)
+      #     end
+      #
+      def extension_white_list; end
+
+    private
+
+      def check_whitelist!(new_file)
+        if extension_white_list and not extension_white_list.include?(new_file.extension.to_s)
+          raise CarrierWave::IntegrityError, "You are not allowed to upload #{new_file.extension.inspect} files, allowed types: #{extension_white_list.inspect}"
+        end
+      end
+
+    end # ExtensionWhitelist
+  end # Uploader
+end # CarrierWave

data/lib/carrierwave/uploader/mountable.rb

@@ -0,0 +1,37 @@
+module CarrierWave
+  module Uploader
+    module Mountable
+
+      attr_reader :model, :mounted_as
+
+      ##
+      # If a model is given as the first parameter, it will stored in the uploader, and
+      # available throught +#model+. Likewise, mounted_as stores the name of the column
+      # where this instance of the uploader is mounted. These values can then be used inside
+      # your uploader.
+      #
+      # If you do not wish to mount your uploaders with the ORM extensions in -more then you
+      # can override this method inside your uploader. Just be sure to call +super+
+      #
+      # === Parameters
+      #
+      # [model (Object)] Any kind of model object
+      # [mounted_as (Symbol)] The name of the column where this uploader is mounted
+      #
+      # === Examples
+      #
+      #     class MyUploader < CarrierWave::Uploader::Base
+      #
+      #       def store_dir
+      #         File.join('public', 'files', mounted_as, model.permalink)
+      #       end
+      #     end
+      #
+      def initialize(model=nil, mounted_as=nil)
+        @model = model
+        @mounted_as = mounted_as
+      end
+
+    end # Mountable
+  end # Uploader
+end # CarrierWave

data/lib/carrierwave/uploader/paths.rb

@@ -0,0 +1,25 @@
+module CarrierWave
+  module Uploader
+    module Paths
+
+      ##
+      # === Returns
+      #
+      # [String] the directory that is the root of the application
+      #
+      def root
+        CarrierWave.config[:root]
+      end
+
+      ##
+      # === Returns
+      #
+      # [String] the directory where files will be publically accessible
+      #
+      def public
+        CarrierWave.config[:public]
+      end
+
+    end # Paths
+  end # Uploader
+end # CarrierWave

data/lib/carrierwave/uploader/processing.rb

@@ -0,0 +1,79 @@
+module CarrierWave
+  module Uploader
+    module Processing
+
+      depends_on CarrierWave::Uploader::Callbacks
+
+      setup do
+        after :cache, :process!
+      end
+
+      module ClassMethods
+
+        ##
+        # Lists processor callbacks declared
+        #
+        # === Returns
+        #
+        # [Array[Array[Symbol, Array]]] a list of processor callbacks which have been declared for this uploader
+        #
+        def processors
+          @processors ||= []
+        end
+
+        ##
+        # Adds a processor callback which applies operations as a file is uploaded.
+        # The argument may be the name of any method of the uploader, expressed as a symbol,
+        # or a list of such methods, or a hash where the key is a method and the value is
+        # an array of arguments to call the method with
+        #
+        # === Parameters
+        #
+        # args (*Symbol, Hash{Symbol => Array[]})
+        #
+        # === Examples
+        #
+        #     class MyUploader < CarrierWave::Uploader::Base
+        #
+        #       process :sepiatone, :vignette
+        #       process :scale => [200, 200]
+        #
+        #       def sepiatone
+        #         ...
+        #       end
+        #
+        #       def vignette
+        #         ...
+        #       end
+        #
+        #       def scale(height, width)
+        #         ...
+        #       end
+        #     end
+        #
+        def process(*args)
+          args.each do |arg|
+            if arg.is_a?(Hash)
+              arg.each do |method, args|
+                processors.push([method, args])
+              end
+            else
+              processors.push([arg, []])
+            end
+          end
+        end
+
+      end # ClassMethods
+
+      ##
+      # Apply all process callbacks added through CarrierWave.process
+      #
+      def process!(new_file=nil)
+        self.class.processors.each do |method, args|
+          self.send(method, *args)
+        end
+      end
+
+    end # Processing
+  end # Uploader
+end # CarrierWave

data/lib/carrierwave/uploader/proxy.rb

@@ -0,0 +1,60 @@
+module CarrierWave
+  module Uploader
+    module Proxy
+
+      ##
+      # === Returns
+      #
+      # [Boolean] Whether the uploaded file is blank
+      #
+      def blank?
+        !file or file.blank?
+      end
+
+      ##
+      # === Returns
+      #
+      # [String] the path where the file is currently located.
+      #
+      def current_path
+        file.path if file.respond_to?(:path)
+      end
+
+      alias_method :path, :current_path
+
+      ##
+      # Returns a string that uniquely identifies the last stored file
+      #
+      # === Returns
+      #
+      # [String] uniquely identifies a file
+      #
+      def identifier
+        file.identifier if file.respond_to?(:identifier)
+      end
+
+      ##
+      # Read the contents of the file
+      #
+      # === Returns
+      #
+      # [String] contents of the file
+      #
+      def read
+        file.read if file.respond_to?(:read)
+      end
+
+      ##
+      # Fetches the size of the currently stored/cached file
+      #
+      # === Returns
+      #
+      # [Integer] size of the file
+      #
+      def size
+        file.respond_to?(:size) ? file.size : 0
+      end
+
+    end # Proxy
+  end # Uploader
+end # CarrierWave

data/lib/carrierwave/uploader/remove.rb

@@ -0,0 +1,21 @@
+module CarrierWave
+  module Uploader
+    module Remove
+
+      depends_on CarrierWave::Uploader::Callbacks
+
+      ##
+      # Removes the file and reset it
+      #
+      def remove!
+        with_callbacks(:remove) do
+          CarrierWave.logger.info 'CarrierWave: removing file'
+          storage.destroy!(self, file)
+          @file = nil
+          @cache_id = nil
+        end
+      end
+
+    end # Remove
+  end # Uploader
+end # CarrierWave

data/lib/carrierwave/uploader/store.rb

@@ -0,0 +1,154 @@
+module CarrierWave
+  module Uploader
+    module Store
+
+      depends_on CarrierWave::Uploader::Paths
+      depends_on CarrierWave::Uploader::Callbacks
+      depends_on CarrierWave::Uploader::Cache
+
+      module ClassMethods
+
+        ##
+        # Sets the storage engine to be used when storing files with this uploader.
+        # Can be any class that implements a #store!(CarrierWave::SanitizedFile) and a #retrieve!
+        # method. See lib/carrierwave/storage/file.rb for an example. Storage engines should
+        # be added to CarrierWave.config[:storage_engines] so they can be referred
+        # to by a symbol, which should be more convenient
+        #
+        # If no argument is given, it will simply return the currently used storage engine.
+        #
+        # === Parameters
+        #
+        # [storage (Symbol, Class)] The storage engine to use for this uploader
+        #
+        # === Returns
+        #
+        # [Class] the storage engine to be used with this uploader
+        #
+        # === Examples
+        #
+        #     storage :file
+        #     storage CarrierWave::Storage::File
+        #     storage MyCustomStorageEngine
+        #
+        def storage(storage = nil)
+          if storage.is_a?(Symbol)
+            @storage = get_storage_by_symbol(storage)
+            @storage.setup!
+          elsif storage
+            @storage = storage
+            @storage.setup!
+          elsif @storage.nil?
+            # Get the storage from the superclass if there is one
+            @storage = superclass.storage rescue nil
+          end
+          if @storage.nil?
+            # If we were not able to find a store any other way, setup the default store
+            @storage ||= get_storage_by_symbol(CarrierWave.config[:storage])
+            @storage.setup!
+          end
+          return @storage
+        end
+
+        alias_method :storage=, :storage
+
+      private
+
+        def get_storage_by_symbol(symbol)
+          eval(CarrierWave.config[:storage_engines][symbol])
+        end
+
+      end
+
+      ##
+      # Override this in your Uploader to change the filename.
+      #
+      # Be careful using record ids as filenames. If the filename is stored in the database
+      # the record id will be nil when the filename is set. Don't use record ids unless you
+      # understand this limitation.
+      #
+      # Do not use the version_name in the filename, as it will prevent versions from being
+      # loaded correctly.
+      #
+      # === Returns
+      #
+      # [String] a filename
+      #
+      def filename
+        @filename
+      end
+
+      ##
+      # Override this in your Uploader to change the directory where the file backend stores files.
+      #
+      # Other backends may or may not use this method, depending on their specific needs.
+      #
+      # === Returns
+      #
+      # [String] a directory
+      #
+      def store_dir
+        CarrierWave.config[:store_dir]
+      end
+
+      ##
+      # Calculates the path where the file should be stored. If +for_file+ is given, it will be
+      # used as the filename, otherwise +CarrierWave::Uploader#filename+ is assumed.
+      #
+      # === Parameters
+      #
+      # [for_file (String)] name of the file <optional>
+      #
+      # === Returns
+      #
+      # [String] the store path
+      #
+      def store_path(for_file=filename)
+        File.join(store_dir, full_filename(for_file))
+      end
+
+      ##
+      # Stores the file by passing it to this Uploader's storage engine.
+      #
+      # If new_file is omitted, a previously cached file will be stored.
+      #
+      # === Parameters
+      #
+      # [new_file (File, IOString, Tempfile)] any kind of file object
+      #
+      def store!(new_file=nil)
+        cache!(new_file) if new_file
+        if @file and @cache_id
+          with_callbacks(:store, new_file) do
+            @file = storage.store!(self, @file)
+            @cache_id = nil
+          end
+        end
+      end
+
+      ##
+      # Retrieves the file from the storage.
+      #
+      # === Parameters
+      #
+      # [identifier (String)] uniquely identifies the file to retrieve
+      #
+      def retrieve_from_store!(identifier)
+        with_callbacks(:retrieve_from_store, identifier) do
+          @file = storage.retrieve!(self, identifier)
+        end
+      end
+
+    private
+
+      def full_filename(for_file)
+        for_file
+      end
+
+      def storage
+        self.class.storage
+      end
+
+    end # Store
+  end # Uploader
+end # CarrierWave