class MIME::Type

The definition of one MIME content-type.

Usage

require 'mime/types'

plaintext = MIME::Types['text/plain']
print plaintext.media_type           # => 'text'
print plaintext.sub_type             # => 'plain'

puts plaintext.extensions.join(" ")  # => 'asc txt c cc h hh cpp'

puts plaintext.encoding              # => 8bit
puts plaintext.binary?               # => false
puts plaintext.ascii?                # => true
puts plaintext == 'text/plain'       # => true
puts MIME::Type.simplified('x-appl/x-zip') # => 'appl/zip'

Constants

CONTACT_URL
DRAFT_URL
ENCODING_RE
IANA_URL
LTSW_URL
MEDIA_TYPE_RE
PLATFORM_RE
RFC_URL
SIGNATURES
UNREG_RE
VERSION

Attributes

content_type[R]

Returns the whole MIME content-type string.

text/plain        => text/plain
x-chemical/x-pdb  => x-chemical/x-pdb
default_encoding[R]

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

docs[RW]

The documentation for this MIME::Type. Documentation about media types will be found on a media type definition as a comment. Documentation will be found through docs.

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.

extensions[RW]

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 and nil values removed.

media_type[R]

Returns the media type of the simplified MIME type.

text/plain        => text
x-chemical/x-pdb  => chemical
obsolete[W]

Sets the obsolescence indicator for this media type.

raw_media_type[R]

Returns the media type of the unmodified MIME type.

text/plain        => text
x-chemical/x-pdb  => x-chemical
raw_sub_type[R]

Returns the media type of the unmodified MIME type.

text/plain        => plain
x-chemical/x-pdb  => x-pdb
simplified[R]

The MIME types main- and sub-label can both start with x-, which indicates that it is a non-registered name. Of course, after registration this flag can disappear, adds to the confusing proliferation of MIME types. The simplified string has the x- removed and are translated to lowercase.

text/plain        => text/plain
x-chemical/x-pdb  => chemical/pdb
sub_type[R]

Returns the sub-type of the simplified MIME type.

text/plain        => plain
x-chemical/x-pdb  => pdb
system[RW]

The regexp for the operating system that this MIME::Type is specific to.

url[RW]

The encoded URL list for this MIME::Type. See urls for more information.

use_instead[R]

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.

Public Class Methods

from_array(*args) { |m| ... } click to toggle source

Creates a MIME::Type from an array in the form of:

[type-name, [extensions], encoding, system]

extensions, encoding, and system are optional.

MIME::Type.from_array("application/x-ruby", ['rb'], '8bit')
MIME::Type.from_array(["application/x-ruby", ['rb'], '8bit'])

These are equivalent to:

MIME::Type.new('application/x-ruby') do |t|
  t.extensions  = %w(rb)
  t.encoding    = '8bit'
end
# File lib/mime/types.rb, line 327
def from_array(*args) #:yields MIME::Type.new:
  # Dereferences the array one level, if necessary.
  args = args[0] if args[0].kind_of?(Array)

  if args.size.between?(1, 8)
    m = MIME::Type.new(args[0]) do |t|
      t.extensions  = args[1] if args.size > 1
      t.encoding    = args[2] if args.size > 2
      t.system      = args[3] if args.size > 3
      t.obsolete    = args[4] if args.size > 4
      t.docs        = args[5] if args.size > 5
      t.url         = args[6] if args.size > 6
      t.registered  = args[7] if args.size > 7
    end
    yield m if block_given?
  else
    raise ArgumentError, "Array provided must contain between one and eight elements."
  end
  m
end
from_hash(hash) { |m| ... } click to toggle source

Creates a MIME::Type from a hash. Keys are case-insensitive, dashes may be replaced with underscores, and the internal Symbol of the lowercase-underscore version can be used as well. That is, Content-Type can be provided as content-type, Content_Type, #content_type, or :content_type.

Known keys are Content-Type, Content-Transfer-Encoding, Extensions, and System.

MIME::Type.from_hash('Content-Type' => 'text/x-yaml',
                     'Content-Transfer-Encoding' => '8bit',
                     'System' => 'linux',
                     'Extensions' => ['yaml', 'yml'])

This is equivalent to:

MIME::Type.new('text/x-yaml') do |t|
  t.encoding    = '8bit'
  t.system      = 'linux'
  t.extensions  = ['yaml', 'yml']
end
# File lib/mime/types.rb, line 370
def from_hash(hash) #:yields MIME::Type.new:
  type = {}
  hash.each_pair do |k, v| 
    type[k.to_s.tr('A-Z', 'a-z').gsub(%r-/, '_').to_sym] = v
  end

  m = MIME::Type.new(type[:content_type]) do |t|
    t.extensions  = type[:extensions]
    t.encoding    = type[:content_transfer_encoding]
    t.system      = type[:system]
    t.obsolete    = type[:obsolete]
    t.docs        = type[:docs]
    t.url         = type[:url]
    t.registered  = type[:registered]
  end

  yield m if block_given?
  m
end
from_mime_type(mime_type) { |m| ... } click to toggle source

Essentially a copy constructor.

MIME::Type.from_mime_type(plaintext)

is equivalent to:

MIME::Type.new(plaintext.content_type.dup) do |t|
  t.extensions  = plaintext.extensions.dup
  t.system      = plaintext.system.dup
  t.encoding    = plaintext.encoding.dup
end
# File lib/mime/types.rb, line 401
def from_mime_type(mime_type) #:yields the new MIME::Type:
  m = MIME::Type.new(mime_type.content_type.dup) do |t|
    t.extensions = mime_type.extensions.map { |e| e.dup }
    t.url = mime_type.url && mime_type.url.map { |e| e.dup }

    mime_type.system && t.system = mime_type.system.dup
    mime_type.encoding && t.encoding = mime_type.encoding.dup

    t.obsolete = mime_type.obsolete?
    t.registered = mime_type.registered?

    mime_type.docs && t.docs = mime_type.docs.dup
    
  end

  yield m if block_given?
end
new(content_type) { |self| ... } click to toggle source

Builds a MIME::Type object from the provided MIME Content Type value (e.g., 'text/plain' or 'applicaton/x-eruby'). The constructed object is yielded to an optional block for additional configuration, such as associating extensions and encoding information.

# File lib/mime/types.rb, line 424
def initialize(content_type) #:yields self:
  matchdata = MEDIA_TYPE_RE.match(content_type)

  if matchdata.nil?
    raise InvalidContentType, "Invalid Content-Type provided ('#{content_type}')"
  end

  @content_type = content_type
  @raw_media_type = matchdata.captures[0]
  @raw_sub_type = matchdata.captures[1]

  @simplified = MIME::Type.simplified(@content_type)
  matchdata = MEDIA_TYPE_RE.match(@simplified)
  @media_type = matchdata.captures[0]
  @sub_type = matchdata.captures[1]

  self.extensions   = nil
  self.encoding     = :default
  self.system       = nil
  self.registered   = true
  self.url          = nil
  self.obsolete     = nil
  self.docs         = nil

  yield self if block_given?
end
simplified(content_type) click to toggle source

The MIME types main- and sub-label can both start with x-, which indicates that it is a non-registered name. Of course, after registration this flag can disappear, adds to the confusing proliferation of MIME types. The simplified string has the x- removed and are translated to lowercase.

# File lib/mime/types.rb, line 300
def simplified(content_type)
  matchdata = MEDIA_TYPE_RE.match(content_type)

  if matchdata.nil?
    simplified = nil
  else
    media_type = matchdata.captures[0].downcase.gsub(UNREG_RE, '')
    subtype = matchdata.captures[1].downcase.gsub(UNREG_RE, '')
    simplified = "#{media_type}/#{subtype}"
  end
  simplified
end

Public Instance Methods

<=>(other) click to toggle source

Compares the 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.

# File lib/mime/types.rb, line 70
def <=>(other)
  if other.respond_to?(:content_type)
    @content_type.downcase <=> other.content_type.downcase
  elsif other.respond_to?(:to_s)
    @simplified <=> Type.simplified(other.to_s)
  else
    @content_type.downcase <=> other.downcase
  end
end
ascii?() click to toggle source

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/types.rb, line 475
def ascii?
  not binary?
end
binary?() click to toggle source

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/types.rb, line 468
def binary?
  @encoding == 'base64'
end
complete?() click to toggle source

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

# File lib/mime/types.rb, line 498
def complete?
  not @extensions.empty?
end
docs=(d) click to toggle source
# File lib/mime/types.rb, line 236
def docs=(d)
  if d
    a = d.scan(%r{use-instead:#{MEDIA_TYPE_RE}})

    if a.empty?
      @use_instead = nil
    else
      @use_instead = a.map { |el| "#{el[0]}/#{el[1]}" }
    end
  end
  @docs = d
end
eql?(other) click to toggle source

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

# File lib/mime/types.rb, line 126
def eql?(other)
  other.kind_of?(MIME::Type) and self == other
end
like?(other) click to toggle source

Returns true if the simplified type matches the current

# File lib/mime/types.rb, line 58
def like?(other)
  if other.respond_to?(:simplified)
    @simplified == other.simplified
  else
    @simplified == Type.simplified(other)
  end
end
obsolete?() click to toggle source

Returns true if the media type is obsolete.

# File lib/mime/types.rb, line 225
def obsolete?
  @obsolete ? true : false
end
platform?() click to toggle source

Returns true if the MIME::Type is specific to the current operating system as represented by RUBY_PLATFORM.

# File lib/mime/types.rb, line 492
def platform?
  system? and (RUBY_PLATFORM =~ @system)
end
priority_compare(other) click to toggle source

Compares the MIME::Type based on how reliable it is before doing a normal <=> comparison. Used by MIME::Types#[] to sort types. The comparisons involved are:

  1. self.simplified <=> other.simplified (ensures that we don't try to compare different types)

  2. IANA-registered definitions > other definitions.

  3. Generic definitions > platform definitions.

  4. Complete definitions > incomplete definitions.

  5. Current definitions > obsolete definitions.

  6. Obselete with use-instead references > obsolete without.

  7. Obsolete use-instead definitions are compared.

# File lib/mime/types.rb, line 92
def priority_compare(other)
  pc = simplified <=> other.simplified

  if pc.zero? and registered? != other.registered?
    pc = registered? ? -1 : 1
  end

  if pc.zero? and platform? != other.platform?
    pc = platform? ? 1 : -1
  end

  if pc.zero? and complete? != other.complete?
    pc = complete? ? -1 : 1
  end

  if pc.zero? and obsolete? != other.obsolete?
    pc = obsolete? ? 1 : -1
  end

  if pc.zero? and obsolete? and (use_instead != other.use_instead)
    pc = if use_instead.nil?
           -1
         elsif other.use_instead.nil?
           1
         else
           use_instead <=> other.use_instead
         end
  end

  pc
end
registered?() click to toggle source

MIME content-types which are not regestered by IANA nor defined in RFCs are required to start with x-. This counts as well for a new media type as well as a new sub-type of an existing media type. If either the media-type or the content-type begins with x-, this method will return false.

# File lib/mime/types.rb, line 456
def registered?
  if (@raw_media_type =~ UNREG_RE) || (@raw_sub_type =~ UNREG_RE)
    false
  else
    @registered
  end
end
signature?() click to toggle source

Returns true when the simplified MIME type is in the list of known digital signatures.

# File lib/mime/types.rb, line 481
def signature?
  SIGNATURES.include?(@simplified.downcase)
end
system?() click to toggle source

Returns true if the MIME::Type is specific to an operating system.

# File lib/mime/types.rb, line 486
def system?
  not @system.nil?
end
to_a() click to toggle source

Returns the MIME type as an array suitable for use with ::from_array.

# File lib/mime/types.rb, line 514
def to_a
  [ @content_type, @extensions, @encoding, @system, @obsolete, @docs,
    @url, registered? ]
end
to_hash() click to toggle source

Returns the MIME type as an array suitable for use with ::from_hash.

# File lib/mime/types.rb, line 521
def to_hash
  { 'Content-Type'              => @content_type,
    'Content-Transfer-Encoding' => @encoding,
    'Extensions'                => @extensions,
    'System'                    => @system,
    'Obsolete'                  => @obsolete,
    'Docs'                      => @docs,
    'URL'                       => @url,
    'Registered'                => registered?,
  }
end
to_s() click to toggle source

Returns the MIME type as a string.

# File lib/mime/types.rb, line 503
def to_s
  @content_type
end
to_str() click to toggle source

Returns the MIME type as a string for implicit conversions.

# File lib/mime/types.rb, line 508
def to_str
  @content_type
end
urls() click to toggle source

The decoded URL list for this MIME::Type. The special URL value IANA will be translated into:

http://www.iana.org/assignments/media-types/<mediatype>/<subtype>

The special URL value RFC### will be translated into:

http://www.rfc-editor.org/rfc/rfc###.txt

The special URL value DRAFT:name will be translated into:

https://datatracker.ietf.org/public/idindex.cgi?
    command=id_detail&filename=<name>

The special URL value LTSW will be translated into:

http://www.ltsw.se/knbase/internet/<mediatype>.htp

The special URL value [token] will be translated into:

http://www.iana.org/assignments/contact-people.htm#<token>

These values will be accessible through urls, which always returns an array.

# File lib/mime/types.rb, line 271
def urls
  @url.map do |el|
    case el
    when %r{^IANA$}
      IANA_URL % [ @media_type, @sub_type ]
    when %r{^RFC(\d+)$}
      RFC_URL % $1
    when %r{^DRAFT:(.+)$}
      DRAFT_URL % $1
    when %r{^LTSW$}
      LTSW_URL % @media_type
    when %r<^\{([^=]+)=([^\]]+)\}>
      [$1, $2]
    when %r{^\[([^=]+)=([^\]]+)\]}
      [$1, CONTACT_URL % $2]
    when %r{^\[([^\]]+)\]}
      CONTACT_URL % $1
    else
      el
    end
  end
end