Shrine::UploadedFile::InstanceMethods

Methods

Public Class

Public Instance

==
[]
as_json
close
data
delete
download
eof?
exists?
extension
hash
id
inspect
metadata
mime_type
open
opened?
original_filename
read
replace
rewind
shrine_class
size
storage
storage_key
stream
to_io
to_json
uploader
url

Constants

RFC2396_PARSER = URI::RFC2396_Parser.new

Public Instance Aliases

content_type	->	mime_type
eql?	->	==

Attributes

id	[R]	The location where the file was uploaded to the storage.
metadata	[R]	A hash of file metadata that was extracted during upload.
storage_key	[R]	The identifier of the storage the file is uploaded to.

Public Class methods

new(data)

Initializes the uploaded file with the given data hash.

[show source]

   # File lib/shrine/uploaded_file.rb
37 def initialize(data)
38   @id          = data[:id]              || data["id"]
39   @storage_key = data[:storage]&.to_sym || data["storage"]&.to_sym
40   @metadata    = data[:metadata]        || data["metadata"]        || {}
41 
42   fail Error, "#{data.inspect} isn't valid uploaded file data" unless @id && @storage_key
43 
44   storage # ensure storage is registered
45 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
228 def ==(other)
229   self.class       == other.class       &&
230   self.id          == other.id          &&
231   self.storage_key == other.storage_key
232 end

[](key)

Shorthand for accessing metadata values.

[show source]

   # File lib/shrine/uploaded_file.rb
73 def [](key)
74   metadata[key]
75 end

as_json(*)

Conform to ActiveSupport’s JSON interface.

[show source]

    # File lib/shrine/uploaded_file.rb
217 def as_json(*)
218   data
219 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
173 def close
174   io.close if opened?
175   @io = nil
176 end

data()

Returns serializable hash representation of the uploaded file.

[show source]

    # File lib/shrine/uploaded_file.rb
222 def data
223   { "id" => id, "storage" => storage_key.to_s, "metadata" => metadata }
224 end

delete()

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

[show source]

    # File lib/shrine/uploaded_file.rb
201 def delete
202   storage.delete(id)
203 end

download(**)

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
123 def download(**)
124   tempfile = Tempfile.new(["shrine", ".#{extension}"], binmode: true)
125   stream(tempfile, **)
126   tempfile.open
127 
128   block_given? ? yield(tempfile) : tempfile
129 ensure
130   tempfile.close! if ($! || block_given?) && tempfile
131 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
161 def eof?
162   io.eof?
163 end

exists?()

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

[show source]

    # File lib/shrine/uploaded_file.rb
190 def exists?
191   storage.exists?(id)
192 end

extension()

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

[show source]

   # File lib/shrine/uploaded_file.rb
54 def extension
55   identifier = id =~ RFC2396_PARSER.make_regexp ? id.sub(/\?.+$/, "") : id # strip query params for shrine-url
56   result = File.extname(identifier)[1..-1]
57   result ||= File.extname(original_filename.to_s)[1..-1]
58   result.downcase if result
59 end

hash()

Enables using UploadedFile objects as hash keys.

[show source]

    # File lib/shrine/uploaded_file.rb
236 def hash
237   [id, storage_key].hash
238 end

inspect()

Returns simplified inspect output.

[show source]

    # File lib/shrine/uploaded_file.rb
256 def inspect
257   "#<#{self.class.inspect} storage=#{storage_key.inspect} id=#{id.inspect} metadata=#{metadata.inspect}>"
258 end

mime_type()

The MIME type of the uploaded file.

[show source]

   # File lib/shrine/uploaded_file.rb
67 def mime_type
68   metadata["mime_type"]
69 end

open(**)

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
 94 def open(**)
 95   @io.close if @io
 96   @io = _open(**)
 97 
 98   return @io unless block_given?
 99 
100   begin
101     yield @io
102   ensure
103     close
104     @io = nil
105   end
106 end

opened?()

Returns whether the file has already been opened.

[show source]

    # File lib/shrine/uploaded_file.rb
179 def opened?
180   !!@io
181 end

original_filename()

The filename that was extracted from the uploaded file.

[show source]

   # File lib/shrine/uploaded_file.rb
48 def original_filename
49   metadata["filename"]
50 end

read(*)

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

[show source]

    # File lib/shrine/uploaded_file.rb
155 def read(*)
156   io.read(*)
157 end

replace(io, **)

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

[show source]

    # File lib/shrine/uploaded_file.rb
195 def replace(io, **)
196   uploader.upload(io, **, location: id)
197 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
167 def rewind
168   io.rewind
169 end

shrine_class()

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

[show source]

    # File lib/shrine/uploaded_file.rb
251 def shrine_class
252   self.class.shrine_class
253 end

size()

The filesize of the uploaded file.

[show source]

   # File lib/shrine/uploaded_file.rb
62 def size
63   (@io && @io.size) || (metadata["size"] && Integer(metadata["size"]))
64 end

storage()

Returns the storage that this file was uploaded to.

[show source]

    # File lib/shrine/uploaded_file.rb
246 def storage
247   shrine_class.find_storage(storage_key)
248 end

stream(destination, **)

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
144 def stream(destination, **)
145   if opened?
146     IO.copy_stream(io, destination)
147     io.rewind
148   else
149     open(**) { |io| IO.copy_stream(io, destination) }
150   end
151 end

to_io()

Returns an opened IO object for the uploaded file.

[show source]

    # File lib/shrine/uploaded_file.rb
206 def to_io
207   io
208 end

to_json(*)

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
212 def to_json(*)
213   data.to_json(*)
214 end

uploader()

Returns an uploader object for the corresponding storage.

[show source]

    # File lib/shrine/uploaded_file.rb
241 def uploader
242   shrine_class.new(storage_key)
243 end

url(**)

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

[show source]

    # File lib/shrine/uploaded_file.rb
184 def url(**)
185   storage.url(id, **)
186 end

module Shrine::UploadedFile::InstanceMethods

Methods

Public Class

Public Instance

Constants

Public Instance Aliases

Attributes

Public Class methods

Public Instance methods