module Shrine::UploadedFile::InstanceMethods

  1. lib/shrine/uploaded_file.rb

Public Instance Aliases

content_type -> mime_type
eql? -> ==

Attributes

data [R]

The hash of information which defines this uploaded file.

Public Class methods

new (data)

Initializes the uploaded file with the given data hash.

[show source]
# File lib/shrine/uploaded_file.rb, line 30
def initialize(data)
  raise Error, "#{data.inspect} isn't valid uploaded file data" unless data["id"] && data["storage"]

  @data = data
  @data["metadata"] ||= {}
  storage # ensure storage is registered
end

Public Instance methods

== (other)

Returns true if the other UploadedFile is uploaded to the same storage and it has the same id.

[show source]
# File lib/shrine/uploaded_file.rb, line 222
def ==(other)
  other.is_a?(self.class) &&
  self.id == other.id &&
  self.storage_key == other.storage_key
end
as_json (*args)

Conform to ActiveSupport's JSON interface.

[show source]
# File lib/shrine/uploaded_file.rb, line 216
def as_json(*args)
  data
end
close ()

Part of complying to the IO interface. It delegates to the internally opened IO object.

[show source]
# File lib/shrine/uploaded_file.rb, line 173
def close
  io.close if opened?
end
delete ()

Calls #delete on the storage, which deletes the file from the storage.

[show source]
# File lib/shrine/uploaded_file.rb, line 200
def delete
  storage.delete(id)
end
download (*args)

Streams content into a newly created Tempfile and returns it.

If a block is given, the opened Tempfile object is yielded to the block, and at the end of the block it's automatically closed and deleted. In this case the return value of the method is the block return value.

If no block is given, the opened Tempfile is returned.

uploaded_file.download
#=> #<File:/var/folders/.../20180302-33119-1h1vjbq.jpg>

# or

uploaded_file.download { |tempfile| tempfile.read } # tempfile is deleted
[show source]
# File lib/shrine/uploaded_file.rb, line 123
def download(*args)
  tempfile = Tempfile.new(["shrine", ".#{extension}"], binmode: true)
  stream(tempfile, *args)
  tempfile.open

  block_given? ? yield(tempfile) : tempfile
ensure
  tempfile.close! if ($! || block_given?) && tempfile
end
eof? ()

Part of complying to the IO interface. It delegates to the internally opened IO object.

[show source]
# File lib/shrine/uploaded_file.rb, line 161
def eof?
  io.eof?
end
exists? ()

Calls #exists? on the storage, which checks whether the file exists on the storage.

[show source]
# File lib/shrine/uploaded_file.rb, line 189
def exists?
  storage.exists?(id)
end
extension ()

The extension derived from id if present, otherwise it's derived from original_filename.

[show source]
# File lib/shrine/uploaded_file.rb, line 60
def extension
  result = File.extname(id)[1..-1] || File.extname(original_filename.to_s)[1..-1]
  result.sub!(/\?.+$/, "") if result && id =~ URI::regexp # strip query params for shrine-url
  result.downcase if result
end
hash ()

Enables using UploadedFile objects as hash keys.

[show source]
# File lib/shrine/uploaded_file.rb, line 230
def hash
  [id, storage_key].hash
end
id ()

The location where the file was uploaded to the storage.

[show source]
# File lib/shrine/uploaded_file.rb, line 39
def id
  @data.fetch("id")
end
metadata ()

A hash of file metadata that was extracted during upload.

[show source]
# File lib/shrine/uploaded_file.rb, line 49
def metadata
  @data.fetch("metadata")
end
mime_type ()

The MIME type of the uploaded file.

[show source]
# File lib/shrine/uploaded_file.rb, line 72
def mime_type
  metadata["mime_type"]
end
open (*args)

Calls #open on the storage to open the uploaded file for reading. Most storages will return a lazy IO object which dynamically retrieves file content from the storage as the object is being read.

If a block is given, the opened IO object is yielded to the block, and at the end of the block it's automatically closed. In this case the return value of the method is the block return value.

If no block is given, the opened IO object is returned.

uploaded_file.open #=> IO object returned by the storage
uploaded_file.read #=> "..."
uploaded_file.close

# or

uploaded_file.open { |io| io.read } # the IO is automatically closed
[show source]
# File lib/shrine/uploaded_file.rb, line 94
def open(*args)
  @io.close if @io
  @io = storage.open(id, *args)

  return @io unless block_given?

  begin
    yield @io
  ensure
    close
    @io = nil
  end
end
opened? ()

Returns whether the file has already been opened.

[show source]
# File lib/shrine/uploaded_file.rb, line 178
def opened?
  !!@io
end
original_filename ()

The filename that was extracted from the uploaded file.

[show source]
# File lib/shrine/uploaded_file.rb, line 54
def original_filename
  metadata["filename"]
end
read (*args)

Part of complying to the IO interface. It delegates to the internally opened IO object.

[show source]
# File lib/shrine/uploaded_file.rb, line 155
def read(*args)
  io.read(*args)
end
replace (io, context = {})

Uploads a new file to this file's location and returns it.

[show source]
# File lib/shrine/uploaded_file.rb, line 194
def replace(io, context = {})
  uploader.upload(io, context.merge(location: id))
end
rewind ()

Part of complying to the IO interface. It delegates to the internally opened IO object.

[show source]
# File lib/shrine/uploaded_file.rb, line 167
def rewind
  io.rewind
end
shrine_class ()

Returns the Shrine class that this file's class is namespaced under.

[show source]
# File lib/shrine/uploaded_file.rb, line 245
def shrine_class
  self.class.shrine_class
end
size ()

The filesize of the uploaded file.

[show source]
# File lib/shrine/uploaded_file.rb, line 67
def size
  (@io && @io.size) || (metadata["size"] && Integer(metadata["size"]))
end
storage ()

Returns the storage that this file was uploaded to.

[show source]
# File lib/shrine/uploaded_file.rb, line 240
def storage
  shrine_class.find_storage(storage_key)
end
storage_key ()

The string identifier of the storage the file is uploaded to.

[show source]
# File lib/shrine/uploaded_file.rb, line 44
def storage_key
  @data.fetch("storage")
end
stream (destination, *args)

Streams uploaded file content into the specified destination. The destination object is given directly to IO.copy_stream, so it can be either a path on disk or an object that responds to #write.

If the uploaded file is already opened, it will be simply rewinded after streaming finishes. Otherwise the uploaded file is opened and then closed after streaming.

uploaded_file.stream(StringIO.new)
# or
uploaded_file.stream("/path/to/destination")
[show source]
# File lib/shrine/uploaded_file.rb, line 144
def stream(destination, *args)
  if opened?
    IO.copy_stream(io, destination)
    io.rewind
  else
    open(*args) { |io| IO.copy_stream(io, destination) }
  end
end
to_io ()

Returns an opened IO object for the uploaded file.

[show source]
# File lib/shrine/uploaded_file.rb, line 205
def to_io
  io
end
to_json (*args)

Returns the data hash in the JSON format. Suitable for storing in a database column or passing to a background job.

[show source]
# File lib/shrine/uploaded_file.rb, line 211
def to_json(*args)
  data.to_json(*args)
end
uploader ()

Returns an uploader object for the corresponding storage.

[show source]
# File lib/shrine/uploaded_file.rb, line 235
def uploader
  shrine_class.new(storage_key)
end
url (**options)

Calls #url on the storage, forwarding any given URL options.

[show source]
# File lib/shrine/uploaded_file.rb, line 183
def url(**options)
  storage.url(id, **options)
end