Class: MIME::Type
Overview
The definition of one MIME content-type.
Usage
require 'mime/types'
plaintext = MIME::Types['text/plain'] # => [ text/plain ]
text = plaintext.first
puts text.media_type # => 'text'
puts text.sub_type # => 'plain'
puts text.extensions.join(' ') # => 'txt asc c cc h hh cpp hpp dat hlp'
puts text.preferred_extension # => 'txt'
puts text.friendly # => 'Text Document'
puts text.i18n_key # => 'text.plain'
puts text.encoding # => quoted-printable
puts text.default_encoding # => quoted-printable
puts text.binary? # => false
puts text.ascii? # => true
puts text.obsolete? # => false
puts text.registered? # => true
puts text.provisional? # => false
puts text.complete? # => true
puts text # => 'text/plain'
puts text == 'text/plain' # => true
puts 'text/plain' == text # => true
puts text == 'text/x-plain' # => false
puts 'text/x-plain' == text # => false
puts MIME::Type.simplified('x-appl/x-zip') # => 'x-appl/x-zip'
puts MIME::Type.i18n_key('x-appl/x-zip') # => 'x-appl.x-zip'
puts text.like?('text/x-plain') # => true
puts text.like?(MIME::Type.new('x-text/x-plain')) # => true
puts text.xrefs.inspect # => { "rfc" => [ "rfc2046", "rfc3676", "rfc5147" ] }
puts text.xref_urls # => [ "http://www.iana.org/go/rfc2046",
# "http://www.iana.org/go/rfc3676",
# "http://www.iana.org/go/rfc5147" ]
xtext = MIME::Type.new('x-text/x-plain')
puts xtext.media_type # => 'text'
puts xtext.raw_media_type # => 'x-text'
puts xtext.sub_type # => 'plain'
puts xtext.raw_sub_type # => 'x-plain'
puts xtext.complete? # => false
puts MIME::Types.any? { |type| type.content_type == 'text/plain' } # => true
puts MIME::Types.all?(&:registered?) # => false
# Various string representations of MIME types
qcelp = MIME::Types['audio/QCELP'].first # => audio/QCELP
puts qcelp.content_type # => 'audio/QCELP'
puts qcelp.simplified # => 'audio/qcelp'
xwingz = MIME::Types['application/x-Wingz'].first # => application/x-Wingz
puts xwingz.content_type # => 'application/x-Wingz'
puts xwingz.simplified # => 'application/x-wingz'
Direct Known Subclasses
Defined Under Namespace
Classes: Columnar, InvalidContentType, InvalidEncoding
Constant Summary collapse
- VERSION =
The released version of the mime-types library.
"3.5.2"
Instance Attribute Summary collapse
-
#content_type ⇒ Object
readonly
Returns the whole MIME content-type string.
-
#docs ⇒ Object
The documentation for this MIME::Type.
-
#encoding ⇒ Object
Returns the value of attribute encoding.
-
#i18n_key ⇒ Object
readonly
A key suitable for use as a lookup key for translations, such as with the I18n library.
-
#media_type ⇒ Object
readonly
Returns the media type of the simplified MIME::Type.
-
#obsolete ⇒ Object
(also: #obsolete?)
Returns
true
if the media type is obsolete. -
#provisional ⇒ Object
Indicates whether the MIME type’s registration with IANA is provisional.
-
#raw_media_type ⇒ Object
readonly
Returns the media type of the unmodified MIME::Type.
-
#raw_sub_type ⇒ Object
readonly
Returns the media type of the unmodified MIME::Type.
-
#registered ⇒ Object
(also: #registered?)
Indicates whether the MIME type has been registered with IANA.
-
#signature ⇒ Object
(also: #signature?)
Indicateswhether the MIME type is declared as a signature type.
-
#simplified ⇒ Object
readonly
A simplified form of the MIME content-type string, suitable for case-insensitive comparison, with the content_type converted to lowercase.
-
#sub_type ⇒ Object
readonly
Returns the sub-type of the simplified MIME::Type.
- #use_instead ⇒ Object
-
#xrefs ⇒ Object
Returns the value of attribute xrefs.
Class Method Summary collapse
-
.i18n_key(content_type) ⇒ Object
Converts a provided
content_type
into a translation key suitable for use with the I18n library. -
.match(content_type) ⇒ Object
Return a
MatchData
object of thecontent_type
against pattern of media types. -
.simplified(content_type, remove_x_prefix: false) ⇒ Object
MIME media types are case-insensitive, but are typically presented in a case-preserving format in the type registry.
Instance Method Summary collapse
-
#<=>(other) ⇒ Object
Compares the
other
MIME::Type against the exact content type or the simplified type (the simplified type will be used if comparing against something that can be treated as a String with #to_s). -
#add_extensions(*extensions) ⇒ Object
Merge the
extensions
provided into this MIME::Type. -
#ascii? ⇒ Boolean
MIME types can be specified to be sent across a network in particular formats.
-
#binary? ⇒ Boolean
MIME types can be specified to be sent across a network in particular formats.
-
#complete? ⇒ Boolean
Returns
true
if the MIME::Type specifies an extension list, indicating that it is a complete MIME::Type. -
#default_encoding ⇒ Object
Returns the default encoding for the MIME::Type based on the media type.
-
#encode_with(coder) ⇒ Object
Populates the
coder
with attributes about this record for serialization. -
#eql?(other) ⇒ Boolean
Returns
true
if theother
object is a MIME::Type and the content types match. -
#extensions ⇒ Object
The list of extensions which are known to be used for this MIME::Type.
-
#extensions=(value) ⇒ Object
:nodoc:.
-
#friendly(lang = "en") ⇒ Object
A friendly short description for this MIME::Type.
-
#hash ⇒ Object
Returns a hash based on the #simplified value.
-
#init_with(coder) ⇒ Object
Initialize an empty object from
coder
, which must contain the attributes necessary for initializing an empty object. -
#initialize(content_type) {|_self| ... } ⇒ Type
constructor
Builds a MIME::Type object from the
content_type
, a MIME Content Type value (e.g., ‘text/plain’ or ‘application/x-eruby’). -
#inspect ⇒ Object
:nodoc:.
-
#like?(other) ⇒ Boolean
Indicates that a MIME type is like another type.
- #preferred_extension ⇒ Object
-
#preferred_extension=(value) ⇒ Object
:nodoc:.
-
#priority_compare(other) ⇒ Object
Compares the
other
MIME::Type based on how reliable it is before doing a normal <=> comparison. -
#provisional? ⇒ Boolean
Indicates whether the MIME type’s registration with IANA is provisional.
-
#to_h ⇒ Object
Converts the MIME::Type to a hash.
-
#to_json(*args) ⇒ Object
Converts the MIME::Type to a JSON string.
-
#to_s ⇒ Object
Returns the MIME::Type as a string.
-
#to_str ⇒ Object
Returns the MIME::Type as a string for implicit conversions.
-
#xref_urls ⇒ Object
The decoded cross-reference URL list for this MIME::Type.
Constructor Details
#initialize(content_type) {|_self| ... } ⇒ Type
Builds a MIME::Type object from the content_type
, a MIME Content Type value (e.g., ‘text/plain’ or ‘application/x-eruby’). The constructed object is yielded to an optional block for additional configuration, such as associating extensions and encoding information.
-
When provided a Hash or a MIME::Type, the MIME::Type will be constructed with #init_with.
-
When provided an Array, the MIME::Type will be constructed using the first element as the content type and the remaining flattened elements as extensions.
-
Otherwise, the content_type will be used as a string.
Yields the newly constructed self
object.
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 |
# File 'lib/mime/type.rb', line 125 def initialize(content_type) # :yields: self @friendly = {} @obsolete = @registered = @provisional = false @preferred_extension = @docs = @use_instead = nil self.extensions = [] case content_type when Hash init_with(content_type) when Array self.content_type = content_type.shift self.extensions = content_type.flatten when MIME::Type init_with(content_type.to_h) else self.content_type = content_type end self.encoding ||= :default self.xrefs ||= {} yield self if block_given? end |
Instance Attribute Details
#content_type ⇒ Object
Returns the whole MIME content-type string.
The content type is a presentation value from the MIME type registry and should not be used for comparison. The case of the content type is preserved, and extension markers (x-
) are kept.
text/plain => text/plain
x-chemical/x-pdb => x-chemical/x-pdb
audio/QCELP => audio/QCELP
262 263 264 |
# File 'lib/mime/type.rb', line 262 def content_type @content_type end |
#docs ⇒ Object
The documentation for this MIME::Type.
390 391 392 |
# File 'lib/mime/type.rb', line 390 def docs @docs end |
#encoding ⇒ Object
Returns the value of attribute encoding.
352 353 354 |
# File 'lib/mime/type.rb', line 352 def encoding @encoding end |
#i18n_key ⇒ Object (readonly)
A key suitable for use as a lookup key for translations, such as with the I18n library.
call-seq:
text_plain.i18n_key # => "text.plain"
3gpp_xml.i18n_key # => "application.vnd-3gpp-bsf-xml"
# from application/vnd.3gpp.bsf+xml
x_msword.i18n_key # => "application.word"
# from application/x-msword
422 423 424 |
# File 'lib/mime/type.rb', line 422 def i18n_key @i18n_key end |
#media_type ⇒ Object (readonly)
Returns the media type of the simplified MIME::Type.
text/plain => text
x-chemical/x-pdb => x-chemical
audio/QCELP => audio
275 276 277 |
# File 'lib/mime/type.rb', line 275 def media_type @media_type end |
#obsolete ⇒ Object Also known as: obsolete?
Returns true
if the media type is obsolete.
386 387 388 |
# File 'lib/mime/type.rb', line 386 def obsolete @obsolete end |
#provisional ⇒ Object
Indicates whether the MIME type’s registration with IANA is provisional.
450 451 452 |
# File 'lib/mime/type.rb', line 450 def provisional @provisional end |
#raw_media_type ⇒ Object (readonly)
Returns the media type of the unmodified MIME::Type.
text/plain => text
x-chemical/x-pdb => x-chemical
audio/QCELP => audio
281 282 283 |
# File 'lib/mime/type.rb', line 281 def raw_media_type @raw_media_type end |
#raw_sub_type ⇒ Object (readonly)
Returns the media type of the unmodified MIME::Type.
text/plain => plain
x-chemical/x-pdb => x-pdb
audio/QCELP => qcelp
293 294 295 |
# File 'lib/mime/type.rb', line 293 def raw_sub_type @raw_sub_type end |
#registered ⇒ Object Also known as: registered?
Indicates whether the MIME type has been registered with IANA.
446 447 448 |
# File 'lib/mime/type.rb', line 446 def registered @registered end |
#signature ⇒ Object Also known as: signature?
Indicateswhether the MIME type is declared as a signature type.
472 473 474 |
# File 'lib/mime/type.rb', line 472 def signature @signature end |
#simplified ⇒ Object (readonly)
A simplified form of the MIME content-type string, suitable for case-insensitive comparison, with the content_type converted to lowercase.
text/plain => text/plain
x-chemical/x-pdb => x-chemical/x-pdb
audio/QCELP => audio/qcelp
269 270 271 |
# File 'lib/mime/type.rb', line 269 def simplified @simplified end |
#sub_type ⇒ Object (readonly)
Returns the sub-type of the simplified MIME::Type.
text/plain => plain
x-chemical/x-pdb => pdb
audio/QCELP => QCELP
287 288 289 |
# File 'lib/mime/type.rb', line 287 def sub_type @sub_type end |
#use_instead ⇒ Object
378 379 380 |
# File 'lib/mime/type.rb', line 378 def use_instead obsolete? ? @use_instead : nil end |
#xrefs ⇒ Object
Returns the value of attribute xrefs.
430 431 432 |
# File 'lib/mime/type.rb', line 430 def xrefs @xrefs end |
Class Method Details
.i18n_key(content_type) ⇒ Object
Converts a provided content_type
into a translation key suitable for use with the I18n library.
576 577 578 579 580 |
# File 'lib/mime/type.rb', line 576 def i18n_key(content_type) simplify_matchdata(match(content_type), joiner: ".") { |e| e.gsub!(I18N_RE, "-") } end |
.match(content_type) ⇒ Object
Return a MatchData
object of the content_type
against pattern of media types.
584 585 586 587 588 589 590 591 |
# File 'lib/mime/type.rb', line 584 def match(content_type) case content_type when MatchData content_type else MEDIA_TYPE_RE.match(content_type) end end |
.simplified(content_type, remove_x_prefix: false) ⇒ Object
MIME media types are case-insensitive, but are typically presented in a case-preserving format in the type registry. This method converts content_type
to lowercase.
In previous versions of mime-types, this would also remove any extension prefix (x-
). This is no longer default behaviour, but may be provided by providing a truth value to remove_x_prefix
.
570 571 572 |
# File 'lib/mime/type.rb', line 570 def simplified(content_type, remove_x_prefix: false) simplify_matchdata(match(content_type), remove_x_prefix) end |
Instance Method Details
#<=>(other) ⇒ Object
Compares the other
MIME::Type against the exact content type or the simplified type (the simplified type will be used if comparing against something that can be treated as a String with #to_s). In comparisons, this is done against the lowercase version of the MIME::Type.
165 166 167 168 169 170 171 172 173 174 175 176 177 |
# File 'lib/mime/type.rb', line 165 def <=>(other) if other.nil? -1 elsif other.respond_to?(:simplified) simplified <=> other.simplified else filtered = "silent" if other == :silent filtered ||= "true" if other == true filtered ||= other.to_s simplified <=> MIME::Type.simplified(filtered) end end |
#add_extensions(*extensions) ⇒ Object
Merge the extensions
provided into this MIME::Type. The extensions added will be merged uniquely.
313 314 315 |
# File 'lib/mime/type.rb', line 313 def add_extensions(*extensions) self.extensions += extensions end |
#ascii? ⇒ Boolean
MIME types can be specified to be sent across a network in particular formats. This method returns false
when the MIME::Type encoding is set to base64
.
467 468 469 |
# File 'lib/mime/type.rb', line 467 def ascii? ASCII_ENCODINGS.include?(encoding) end |
#binary? ⇒ Boolean
MIME types can be specified to be sent across a network in particular formats. This method returns true
when the MIME::Type encoding is set to base64
.
460 461 462 |
# File 'lib/mime/type.rb', line 460 def binary? BINARY_ENCODINGS.include?(encoding) end |
#complete? ⇒ Boolean
Returns true
if the MIME::Type specifies an extension list, indicating that it is a complete MIME::Type.
477 478 479 |
# File 'lib/mime/type.rb', line 477 def complete? !@extensions.empty? end |
#default_encoding ⇒ Object
Returns the default encoding for the MIME::Type based on the media type.
366 367 368 |
# File 'lib/mime/type.rb', line 366 def default_encoding (@media_type == "text") ? "quoted-printable" : "base64" end |
#encode_with(coder) ⇒ Object
Populates the coder
with attributes about this record for serialization. The structure of coder
should match the structure used with #init_with.
This method should be considered a private implementation detail.
511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 |
# File 'lib/mime/type.rb', line 511 def encode_with(coder) coder["content-type"] = @content_type coder["docs"] = @docs unless @docs.nil? || @docs.empty? coder["friendly"] = @friendly unless @friendly.nil? || @friendly.empty? coder["encoding"] = @encoding coder["extensions"] = @extensions.to_a unless @extensions.empty? coder["preferred-extension"] = @preferred_extension if @preferred_extension if obsolete? coder["obsolete"] = obsolete? coder["use-instead"] = use_instead if use_instead end unless xrefs.empty? {}.tap do |hash| xrefs.each do |k, v| hash[k] = v.to_a.sort end coder["xrefs"] = hash end end coder["registered"] = registered? coder["provisional"] = provisional? if provisional? coder["signature"] = signature? if signature? coder end |
#eql?(other) ⇒ Boolean
Returns true
if the other
object is a MIME::Type and the content types match.
223 224 225 |
# File 'lib/mime/type.rb', line 223 def eql?(other) other.is_a?(MIME::Type) && (self == other) end |
#extensions ⇒ Object
The list of extensions which are known to be used for this MIME::Type. Non-array values will be coerced into an array with #to_a. Array values will be flattened, nil
values removed, and made unique.
:attr_accessor: extensions
301 302 303 |
# File 'lib/mime/type.rb', line 301 def extensions @extensions.to_a end |
#extensions=(value) ⇒ Object
:nodoc:
306 307 308 309 |
# File 'lib/mime/type.rb', line 306 def extensions=(value) # :nodoc: @extensions = Set[*Array(value).flatten.compact].freeze MIME::Types.send(:reindex_extensions, self) end |
#friendly(lang = "en") ⇒ Object
A friendly short description for this MIME::Type.
call-seq:
text_plain.friendly # => "Text File"
text_plain.friendly('en') # => "Text File"
397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 |
# File 'lib/mime/type.rb', line 397 def friendly(lang = "en") @friendly ||= {} case lang when String, Symbol @friendly[lang.to_s] when Array @friendly.update(Hash[*lang]) when Hash @friendly.update(lang) else fail ArgumentError, "Expected a language or translation set, not #{lang.inspect}" end end |
#hash ⇒ Object
Returns a hash based on the #simplified value.
This maintains the invariant that two #eql? instances must have the same #hash (although having the same #hash does not imply that the objects are #eql?).
To see why, suppose a MIME::Type instance a
is compared to another object b
, and that a.eql?(b)
is true. By the definition of #eql?, we know the following:
-
b
is a MIME::Type instance itself. -
a == b
is true.
Due to the first point, we know that b
should respond to the #simplified method. Thus, per the definition of #<=>, we know that a.simplified
must be equal to b.simplified
, as compared by the <=> method corresponding to a.simplified
.
Presumably, if a.simplified <=> b.simplified
is 0
, then a.simplified
has the same hash as b.simplified
. So we assume it’s suitable for #hash to delegate to #simplified in service of the #eql? invariant.
249 250 251 |
# File 'lib/mime/type.rb', line 249 def hash simplified.hash end |
#init_with(coder) ⇒ Object
Initialize an empty object from coder
, which must contain the attributes necessary for initializing an empty object.
This method should be considered a private implementation detail.
540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 |
# File 'lib/mime/type.rb', line 540 def init_with(coder) self.content_type = coder["content-type"] self.docs = coder["docs"] || "" self.encoding = coder["encoding"] self.extensions = coder["extensions"] || [] self.preferred_extension = coder["preferred-extension"] self.obsolete = coder["obsolete"] || false self.registered = coder["registered"] || false self.provisional = coder["provisional"] || false self.signature = coder["signature"] self.xrefs = coder["xrefs"] || {} self.use_instead = coder["use-instead"] friendly(coder["friendly"] || {}) end |
#inspect ⇒ Object
:nodoc:
556 557 558 559 560 |
# File 'lib/mime/type.rb', line 556 def inspect # :nodoc: # We are intentionally lying here because MIME::Type::Columnar is an # implementation detail. "#<MIME::Type: #{self}>" end |
#like?(other) ⇒ Boolean
Indicates that a MIME type is like another type. This differs from ==
because x-
prefixes are removed for this comparison.
151 152 153 154 155 156 157 158 159 |
# File 'lib/mime/type.rb', line 151 def like?(other) other = if other.respond_to?(:simplified) MIME::Type.simplified(other.simplified, remove_x_prefix: true) else MIME::Type.simplified(other.to_s, remove_x_prefix: true) end MIME::Type.simplified(simplified, remove_x_prefix: true) == other end |
#preferred_extension ⇒ Object
327 328 329 |
# File 'lib/mime/type.rb', line 327 def preferred_extension @preferred_extension || extensions.first end |
#preferred_extension=(value) ⇒ Object
:nodoc:
332 333 334 335 |
# File 'lib/mime/type.rb', line 332 def preferred_extension=(value) # :nodoc: add_extensions(value) if value @preferred_extension = value end |
#priority_compare(other) ⇒ Object
Compares the other
MIME::Type based on how reliable it is before doing a normal <=> comparison. Used by MIME::Types#[] to sort types. The comparisons involved are:
-
self.simplified <=> other.simplified (ensures that we don’t try to compare different types)
-
IANA-registered definitions < other definitions.
-
Complete definitions < incomplete definitions.
-
Current definitions < obsolete definitions.
-
Obselete with use-instead names < obsolete without.
-
Obsolete use-instead definitions are compared.
While this method is public, its use is strongly discouraged by consumers of mime-types. In mime-types 3, this method is likely to see substantial revision and simplification to ensure current registered content types sort before unregistered or obsolete content types.
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 |
# File 'lib/mime/type.rb', line 195 def priority_compare(other) pc = simplified <=> other.simplified if pc.zero? || !(extensions & other.extensions).empty? pc = if (reg = registered?) != other.registered? reg ? -1 : 1 # registered < unregistered elsif (comp = complete?) != other.complete? comp ? -1 : 1 # complete < incomplete elsif (obs = obsolete?) != other.obsolete? obs ? 1 : -1 # current < obsolete elsif obs && ((ui = use_instead) != (oui = other.use_instead)) if ui.nil? 1 elsif oui.nil? -1 else ui <=> oui end else 0 end end pc end |
#provisional? ⇒ Boolean
Indicates whether the MIME type’s registration with IANA is provisional.
453 454 455 |
# File 'lib/mime/type.rb', line 453 def provisional? registered? && @provisional end |
#to_h ⇒ Object
Converts the MIME::Type to a hash. The output of this method can also be used to initialize a MIME::Type.
502 503 504 |
# File 'lib/mime/type.rb', line 502 def to_h encode_with({}) end |
#to_json(*args) ⇒ Object
Converts the MIME::Type to a JSON string.
495 496 497 498 |
# File 'lib/mime/type.rb', line 495 def to_json(*args) require "json" to_h.to_json(*args) end |
#to_s ⇒ Object
Returns the MIME::Type as a string.
482 483 484 |
# File 'lib/mime/type.rb', line 482 def to_s content_type end |
#to_str ⇒ Object
490 491 492 |
# File 'lib/mime/type.rb', line 490 def to_str content_type end |
#xref_urls ⇒ Object
The decoded cross-reference URL list for this MIME::Type.
438 439 440 441 442 443 |
# File 'lib/mime/type.rb', line 438 def xref_urls xrefs.flat_map { |type, values| name = :"xref_url_for_#{type.tr("-", "_")}" respond_to?(name, true) && xref_map(values, name) || values.to_a } end |