class MIME::Type

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"

Constants

VERSION: The released version of the mime-types library.

Attributes

content_type [R]

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

docs [RW]

The documentation for this MIME::Type.

encoding [RW]

The encoding (7bit, 8bit, quoted-printable, or base64) required to transport the data of this content type safely across a network, which roughly corresponds to Content-Transfer-Encoding. A value of nil or :default will reset the encoding to the default_encoding for the MIME::Type. Raises ArgumentError if the encoding provided is invalid.

If the encoding is not provided on construction, this will be either “quoted-printable” (for text/* media types) and “base64” for eveything else.

i18n_key [R]

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

media_type [R]

Returns the media type of the simplified MIME::Type.

text/plain        => text
x-chemical/x-pdb  => x-chemical
audio/QCELP       => audio

obsolete [R]

Returns true if the media type is obsolete.

:attr_accessor: obsolete

obsolete? [R]

Returns true if the media type is obsolete.

:attr_accessor: obsolete

preferred_extension [RW]

The preferred extension for this MIME type. If one is not set and there are exceptions defined, the first extension will be used.

When setting preferred_extensions, if extensions does not contain this extension, this will be added to extensions.

provisional [R]

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

:attr_accessor: provisional

raw_media_type [R]

Returns the media type of the unmodified MIME::Type.

text/plain        => text
x-chemical/x-pdb  => x-chemical
audio/QCELP       => audio

raw_sub_type [R]

Returns the media type of the unmodified MIME::Type.

text/plain        => plain
x-chemical/x-pdb  => x-pdb
audio/QCELP       => qcelp

registered [R]

Indicates whether the MIME type has been registered with IANA.

:attr_accessor: registered

registered? [R]

Indicates whether the MIME type has been registered with IANA.

:attr_accessor: registered

signature [RW]

Indicateswhether the MIME type is declared as a signature type.

signature? [RW]

Indicateswhether the MIME type is declared as a signature type.

simplified [R]

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

sub_type [R]

Returns the sub-type of the simplified MIME::Type.

text/plain        => plain
x-chemical/x-pdb  => pdb
audio/QCELP       => QCELP

use_instead [RW]

Returns the media type or types that should be used instead of this media type, if it is obsolete. If there is no replacement media type, or it is not obsolete, nil will be returned.

xrefs [RW]

The cross-references list for this MIME::Type.

Public Class Methods

i18n_key (content_type)

Converts a provided content_type into a translation key suitable for use with the I18n library.

# 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)

Return a MatchData object of the content_type against pattern of media types.

# 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

new (content_type) { |self| ... }

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.

# 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

simplified (content_type, remove_x_prefix: false)

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.

# File lib/mime/type.rb, line 623
def simplified(content_type, remove_x_prefix: false)
  simplify_matchdata(match(content_type), remove_x_prefix)
end

Public Instance Methods

<=> (other)

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.

# File lib/mime/type.rb, line 193
def <=>(other)
  return priority_compare(other) if other.is_a?(MIME::Type)
  simplified <=> other
end

add_extensions (*extensions)

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

# File lib/mime/type.rb, line 338
def add_extensions(*extensions)
  self.extensions += extensions
end

ascii? ()

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.

# File lib/mime/type.rb, line 516
def ascii?
  ASCII_ENCODINGS.include?(encoding)
end

binary? ()

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.

# File lib/mime/type.rb, line 509
def binary?
  BINARY_ENCODINGS.include?(encoding)
end

complete? ()

Returns true if the MIME::Type specifies an extension list, indicating that it is a complete MIME::Type.

# File lib/mime/type.rb, line 526
def complete?
  !@extensions.empty?
end

default_encoding ()

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

# File lib/mime/type.rb, line 391
def default_encoding
  (@media_type == "text") ? "quoted-printable" : "base64"
end

encode_with (coder)

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.

# 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)

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

# File lib/mime/type.rb, line 240
def eql?(other)
  other.is_a?(MIME::Type) && (self == other)
end

extensions ()

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

# File lib/mime/type.rb, line 325
def extensions
  @extensions.to_a
end

friendly # → "Text File"

friendly("en") # → "Text File"

A friendly short description for this MIME::Type.

# 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 ()

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

# File lib/mime/type.rb, line 266
def hash
  simplified.hash
end

init_with (coder)

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.

# 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

like? (other)

Indicates that a MIME type is like another type. This differs from == because x- prefixes are removed for this comparison.

# 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

obsolete= (value)

# File lib/mime/type.rb, line 417
def obsolete=(value)
  clear_sort_priority
  @obsolete = !!value
end

priority_compare (other)

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.

# 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= (value)

# File lib/mime/type.rb, line 496
def provisional=(value)
  clear_sort_priority
  @provisional = !!value
end

provisional? ()

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

# File lib/mime/type.rb, line 502
def provisional?
  registered? && @provisional
end

registered= (value)

# File lib/mime/type.rb, line 485
def registered=(value)
  clear_sort_priority
  @registered = !!value
end

to_h ()

Converts the MIME::Type to a hash. The output of this method can also be used to initialize a MIME::Type.

# File lib/mime/type.rb, line 551
def to_h
  encode_with({})
end

to_json (*args)

Converts the MIME::Type to a JSON string.

# File lib/mime/type.rb, line 544
def to_json(*args)
  require "json"
  to_h.to_json(*args)
end

to_s ()

Returns the MIME::Type as a string.

# File lib/mime/type.rb, line 531
def to_s
  content_type
end

to_str ()

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")

# File lib/mime/type.rb, line 539
def to_str
  content_type
end

xref_urls ()

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

# 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