Class: MIME::Type

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/mime/type.rb,
lib/mime/types/version.rb

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("content-type" => "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

Columnar

Defined Under Namespace

Classes: Columnar, InvalidContentType, InvalidEncoding

Constant Summary collapse

VERSION =

The released version of the mime-types library.

MIME::Types::VERSION

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

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.

There are two deprecated initialization forms:

  • 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.

Yields:

  • (_self)

Yield Parameters:

  • _self (MIME::Type) —

    the object that the method was called on



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/mime/type.rb', line 133

def initialize(content_type) # :yields: self
  @friendly = {}
  @obsolete = @registered = @provisional = false
  @preferred_extension = @docs = @use_instead = @__sort_priority = nil

  self.extensions = []

  case content_type
  when Hash
    init_with(content_type)
  when Array
    MIME::Types.deprecated(
      class: MIME::Type,
      method: :new,
      pre: "when called with an Array",
      once: true
    )
    self.content_type = content_type.shift
    self.extensions = content_type.flatten
  when MIME::Type
    init_with(content_type.to_h)
  else
    MIME::Types.deprecated(
      class: MIME::Type,
      method: :new,
      pre: "when called with a String",
      once: true
    )
    self.content_type = content_type
  end

  self.encoding ||= :default
  self.xrefs ||= {}

  yield self if block_given?

  update_sort_priority
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



286
287
288
 
# File 'lib/mime/type.rb', line 286

def content_type
  @content_type
end

#docs ⇒ Object

The documentation for this MIME::Type.



423
424
425
 
# File 'lib/mime/type.rb', line 423

def docs
  @docs
end

#encoding ⇒ Object

Returns the value of attribute encoding.



377
378
379
 
# File 'lib/mime/type.rb', line 377

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



455
456
457
 
# File 'lib/mime/type.rb', line 455

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



299
300
301
 
# File 'lib/mime/type.rb', line 299

def media_type
  @media_type
end

#obsolete ⇒ Object Also known as: obsolete?

Returns true if the media type is obsolete.

:attr_accessor: obsolete



413
414
415
 
# File 'lib/mime/type.rb', line 413

def obsolete
  @obsolete
end

#provisional ⇒ Object

Indicates whether the MIME type’s registration with IANA is provisional.

:attr_accessor: provisional



493
494
495
 
# File 'lib/mime/type.rb', line 493

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



305
306
307
 
# File 'lib/mime/type.rb', line 305

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



317
318
319
 
# File 'lib/mime/type.rb', line 317

def raw_sub_type
  @raw_sub_type
end

#registered ⇒ Object Also known as: registered?

Indicates whether the MIME type has been registered with IANA.

:attr_accessor: registered



481
482
483
 
# File 'lib/mime/type.rb', line 481

def registered
  @registered
end

#signature ⇒ Object Also known as: signature?

Indicateswhether the MIME type is declared as a signature type.



521
522
523
 
# File 'lib/mime/type.rb', line 521

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



293
294
295
 
# File 'lib/mime/type.rb', line 293

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



311
312
313
 
# File 'lib/mime/type.rb', line 311

def sub_type
  @sub_type
end

#use_instead ⇒ Object 



403
404
405
 
# File 'lib/mime/type.rb', line 403

def use_instead
  obsolete? ? @use_instead : nil
end

#xrefs ⇒ Object

Returns the value of attribute xrefs.



463
464
465
 
# File 'lib/mime/type.rb', line 463

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.



629
630
631
632
633
 
# File 'lib/mime/type.rb', line 629

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.



637
638
639
640
641
642
643
644
 
# File 'lib/mime/type.rb', line 637

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.



623
624
625
 
# File 'lib/mime/type.rb', line 623

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.

Note that this implementation of #<=> is deprecated and will be changed in the next major version to be the same as #priority_compare.

Note that MIME::Types no longer compare against nil.



193
194
195
196
 
# File 'lib/mime/type.rb', line 193

def <=>(other)
  return priority_compare(other) if other.is_a?(MIME::Type)
  simplified <=> other
end

#__extension_priority_compare(other, exts) ⇒ Object

Uses a modified pre-computed sort priority value based on whether one of the provided extensions is the preferred extension for a type.

This is an internal function. If an extension provided is a preferred extension either for this instance or the compared instance, the corresponding extension has its top extension bit cleared from its sort priority. That means that a type with between 0 and 8 extensions will be treated as if it had 9 extensions.



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/mime/type.rb', line 218

def __extension_priority_compare(other, exts) # :nodoc:
  tsp = __sort_priority

  if exts.include?(preferred_extension) && tsp & 0b1000 != 0
    tsp = tsp & 0b11110111 | 0b0111
  end

  osp = other.__sort_priority

  if exts.include?(other.preferred_extension) && osp & 0b1000 != 0
    osp = osp & 0b11110111 | 0b0111
  end

  if (cmp = tsp <=> osp) == 0
    simplified <=> other.simplified
  else
    cmp
  end
end

#__sort_priority ⇒ Object

The computed sort priority value. This is not intended to be used by most callers.



272
273
274
275
 
# File 'lib/mime/type.rb', line 272

def __sort_priority # :nodoc:
  update_sort_priority if !instance_variable_defined?(:@__sort_priority) || @__sort_priority.nil?
  @__sort_priority
end

#add_extensions(*extensions) ⇒ Object

Merge the extensions provided into this MIME::Type. The extensions added will be merged uniquely.



338
339
340
 
# File 'lib/mime/type.rb', line 338

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.

Returns:

  • (Boolean) 


516
517
518
 
# File 'lib/mime/type.rb', line 516

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.

Returns:

  • (Boolean) 


509
510
511
 
# File 'lib/mime/type.rb', line 509

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.

Returns:

  • (Boolean) 


526
527
528
 
# File 'lib/mime/type.rb', line 526

def complete?
  !@extensions.empty?
end

#default_encoding ⇒ Object

Returns the default encoding for the MIME::Type based on the media type.



391
392
393
 
# File 'lib/mime/type.rb', line 391

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.



560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
 
# File 'lib/mime/type.rb', line 560

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["sort-priority"] = __sort_priority || 0b11111111
  coder
end

#eql?(other) ⇒ Boolean

Returns true if the other object is a MIME::Type and the content types match.

Returns:

  • (Boolean) 


240
241
242
 
# File 'lib/mime/type.rb', line 240

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



325
326
327
 
# File 'lib/mime/type.rb', line 325

def extensions
  @extensions.to_a
end

#extensions=(value) ⇒ Object

:nodoc:



330
331
332
333
334
 
# File 'lib/mime/type.rb', line 330

def extensions=(value) # :nodoc:
  clear_sort_priority
  @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"



430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
 
# File 'lib/mime/type.rb', line 430

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:

  1. b is a MIME::Type instance itself.

  2. 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 is suitable for #hash to delegate to #simplified in service of the #eql? invariant.



266
267
268
 
# File 'lib/mime/type.rb', line 266

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.



590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
 
# File 'lib/mime/type.rb', line 590

def init_with(coder)
  @__sort_priority = 0
  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"] || {})

  update_sort_priority
end

#inspect ⇒ Object

:nodoc:



609
610
611
612
613
 
# File 'lib/mime/type.rb', line 609

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.

Returns:

  • (Boolean) 


174
175
176
177
178
179
180
181
182
 
# File 'lib/mime/type.rb', line 174

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 



352
353
354
 
# File 'lib/mime/type.rb', line 352

def preferred_extension
  @preferred_extension || extensions.first
end

#preferred_extension=(value) ⇒ Object

:nodoc:



357
358
359
360
 
# File 'lib/mime/type.rb', line 357

def preferred_extension=(value) # :nodoc:
  add_extensions(value) if value
  @preferred_extension = value
end

#priority_compare(other) ⇒ Object

Compares the other MIME::Type using a pre-computed sort priority value, then the simplified representation for an alphabetical sort.

For the next major version of MIME::Types, this method will become #<=> and #priority_compare will be removed.



203
204
205
206
207
208
209
 
# File 'lib/mime/type.rb', line 203

def priority_compare(other)
  if (cmp = __sort_priority <=> other.__sort_priority) == 0
    simplified <=> other.simplified
  else
    cmp
  end
end

#provisional? ⇒ Boolean

Indicates whether the MIME type’s registration with IANA is provisional.

Returns:

  • (Boolean) 


502
503
504
 
# File 'lib/mime/type.rb', line 502

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.



551
552
553
 
# File 'lib/mime/type.rb', line 551

def to_h
  encode_with({})
end

#to_json(*args) ⇒ Object

Converts the MIME::Type to a JSON string.



544
545
546
547
 
# File 'lib/mime/type.rb', line 544

def to_json(*args)
  require "json"
  to_h.to_json(*args)
end

#to_s ⇒ Object

Returns the MIME::Type as a string.



531
532
533
 
# File 'lib/mime/type.rb', line 531

def to_s
  content_type
end

#to_str ⇒ Object

Returns the MIME::Type as a string for implicit conversions. This allows MIME::Type objects to appear on either side of a comparison.

"text/plain" == MIME::Type.new("content-type" => "text/plain")



539
540
541
 
# File 'lib/mime/type.rb', line 539

def to_str
  content_type
end

#xref_urls ⇒ Object

The decoded cross-reference URL list for this MIME::Type.



471
472
473
474
475
476
 
# File 'lib/mime/type.rb', line 471

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