Module: Paperclip

Defined in:
lib/paperclip.rb,
lib/paperclip/style.rb,
lib/paperclip/upfile.rb,
lib/paperclip/railtie.rb,
lib/paperclip/storage.rb,
lib/paperclip/version.rb,
lib/paperclip/geometry.rb,
lib/paperclip/matchers.rb,
lib/paperclip/processor.rb,
lib/paperclip/thumbnail.rb,
lib/paperclip/attachment.rb,
lib/paperclip/interpolations.rb,
lib/paperclip/callback_compatability.rb,
lib/paperclip/matchers/have_attached_file_matcher.rb,
lib/paperclip/matchers/validate_attachment_size_matcher.rb,
lib/paperclip/matchers/validate_attachment_presence_matcher.rb,
lib/paperclip/matchers/validate_attachment_content_type_matcher.rb

Overview

The base module that gets included in ActiveRecord::Base. See the documentation for Paperclip::ClassMethods for more useful information.

Defined Under Namespace

Modules: CallbackCompatability, ClassMethods, InstanceMethods, Interpolations, Shoulda, Storage, Upfile Classes: Attachment, CommandNotFoundError, Geometry, InfiniteInterpolationError, NotIdentifiedByImageMagickError, PaperclipCommandLineError, PaperclipError, Processor, Railtie, Style, Tempfile, Thumbnail

Constant Summary collapse

SIMPLE_MIME_TYPE = 
%r{\A([a-zA-Z0-9-]+/[a-zA-Z0-9-]+)}.freeze
VERSION = 
"2.3.3"

Class Method Summary collapse

Class Method Details

.bit_bucket ⇒ Object

:nodoc:



174
175
176
 
# File 'lib/paperclip.rb', line 174

def bit_bucket #:nodoc:
  File.exists?("/dev/null") ? "/dev/null" : "NUL"
end

.configure {|_self| ... } ⇒ Object

Yields:

  • (_self)

Yield Parameters:

  • _self (Paperclip) —

    the object that the method was called on



84
85
86
 
# File 'lib/paperclip.rb', line 84

def configure
  yield(self) if block_given?
end

.content_type_for_file(file) ⇒ Object

The content_type_for_file method determines the MIME type of a file using the ‘file` command. Returns nil on failure.



154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/paperclip.rb', line 154

def content_type_for_file file
  file = file.path if file.respond_to? "path"
  return nil if file.nil?
  begin
    output = Paperclip.run("file", '--brief', '--mime', file).strip
    mime_type = output.split(';').first
    match = SIMPLE_MIME_TYPE.match(mime_type)
    content_type = match ? match[0] : nil
  rescue PaperclipCommandLineError
    nil
  end
end

.extension_for_content_type(content_type) ⇒ Object

The extension_for_content_type method determines the best filename extension for a given MIME type. Returns the default first extension for the supplied MIME type. Returns nil on failure.



170
171
172
 
# File 'lib/paperclip.rb', line 170

def extension_for_content_type content_type
  (t = MIME::Types[content_type]) && (f = t.first) && f.extensions.first
end

.included(base) ⇒ Object

:nodoc:



178
179
180
181
182
183
184
185
 
# File 'lib/paperclip.rb', line 178

def included base #:nodoc:
  base.extend ClassMethods
  if base.respond_to?("set_callback")
    base.send :include, Paperclip::CallbackCompatability::Rails3
  else
    base.send :include, Paperclip::CallbackCompatability::Rails21
  end
end

.interpolates(key, &block) ⇒ Object 



96
97
98
 
# File 'lib/paperclip.rb', line 96

def interpolates key, &block
  Paperclip::Interpolations[key] = block
end

.log(message) ⇒ Object

Log a paperclip-specific line. Uses ActiveRecord::Base.logger by default. Set Paperclip.options to false to turn off.



198
199
200
 
# File 'lib/paperclip.rb', line 198

def log message
  logger.info("[paperclip] #{message}") if logging?
end

.logger ⇒ Object

:nodoc:



202
203
204
205
206
207
208
 
# File 'lib/paperclip.rb', line 202

def logger #:nodoc:
  if defined?(ActiveRecord) 
    ActiveRecord::Base.logger
  else
    Rails.logger
  end
end

.logging? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


210
211
212
 
# File 'lib/paperclip.rb', line 210

def logging? #:nodoc:
  options[:log]
end

.options ⇒ Object

Provides configurability to Paperclip. There are a number of options available, such as:

  • whiny: Will raise an error if Paperclip cannot process thumbnails of an uploaded image. Defaults to true.

  • log: Logs progress to the Rails log. Uses ActiveRecord’s logger, so honors log levels, etc. Defaults to true.

  • command_path: Defines the path at which to find the command line programs if they are not visible to Rails the system’s search path. Defaults to nil, which uses the first executable found in the user’s search path.

  • image_magick_path: Deprecated alias of command_path.



73
74
75
76
77
78
79
80
81
82
 
# File 'lib/paperclip.rb', line 73

def options
  @options ||= {
    :whiny             => true,
    :image_magick_path => nil,
    :command_path      => nil,
    :log               => true,
    :log_command       => true,
    :swallow_stderr    => true
  }
end

.path_for_command(command) ⇒ Object

:nodoc:



88
89
90
91
92
93
94
 
# File 'lib/paperclip.rb', line 88

def path_for_command command #:nodoc:
  if options[:image_magick_path]
    warn("[DEPRECATION] :image_magick_path is deprecated and will be removed. Use :command_path instead")
  end
  path = [options[:command_path] || options[:image_magick_path], command].compact
  File.join(*path)
end

.processor(name) ⇒ Object

:nodoc:



187
188
189
190
191
192
193
194
 
# File 'lib/paperclip.rb', line 187

def processor name #:nodoc:
  name = name.to_s.camelize
  processor = Paperclip.const_get(name)
  unless processor.ancestors.include?(Paperclip::Processor)
    raise PaperclipError.new("Processor #{name} was not found")
  end
  processor
end

.quote_command_options(*options) ⇒ Object 



144
145
146
147
148
 
# File 'lib/paperclip.rb', line 144

def quote_command_options(*options)
  options.map do |option|
    option.split("'").map{|m| "'#{m}'" }.join("\\'")
  end
end

.run(cmd, *params) ⇒ Object

The run method takes a command to execute and an array of parameters that get passed to it. The command is prefixed with the :command_path option from Paperclip.options. If you have many commands to run and they are in different paths, the suggested course of action is to symlink them so they are all in the same directory.

If the command returns with a result code that is not one of the expected_outcodes, a PaperclipCommandLineError will be raised. Generally a code of 0 is expected, but a list of codes may be passed if necessary. These codes should be passed as a hash as the last argument, like so:

Paperclip.run("echo", "something", :expected_outcodes => [0,1,2,3])

This method can log the command being run when Paperclip.options is set to true (defaults to false). This will only log if logging in general is set to true as well.



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/paperclip.rb', line 116

def run cmd, *params
  options           = params.last.is_a?(Hash) ? params.pop : {}
  expected_outcodes = options[:expected_outcodes] || [0]
  params            = quote_command_options(*params).join(" ")

  command = %Q[#{path_for_command(cmd)} #{params}]
  command = "#{command} 2>#{bit_bucket}" if Paperclip.options[:swallow_stderr]
  Paperclip.log(command) if Paperclip.options[:log_command]

  begin
    output = `#{command}`
    
    if $?
      raise CommandNotFoundError if $?.exitstatus == 127

      unless expected_outcodes.include?($?.exitstatus)
        raise PaperclipCommandLineError,
          "Error while running #{cmd}. Expected return code to be #{expected_outcodes.join(", ")} but was #{$?.exitstatus}",
          output
      end
    end
  rescue Errno::ENOENT => e
    raise CommandNotFoundError
  end

  output
end