class MIME::Type - mime-types-1.25.1 Documentation

# class MIME::Type

The definition of one MIME content-type.

## Usage¶ ↑

    require 'mime/types'

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

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

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

    puts MIME::Types.any? { |type|
      type.content_type == 'text/plain'
    }                               # => true
    puts MIME::Types.all?(&:registered?)
                                    # => false

### Constants

CONTACT_URL
DRAFT_URL
ENCODING_RE
IANA_URL
LTSW_URL
MEDIA_TYPE_RE
PLATFORM_RE
RFC_URL
SIGNATURES
UNREG_RE
VERSION

  The released version of Ruby MIME::Types

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

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 412
    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

### 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 68
    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 463
    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 456
    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 486
    def complete?
      not @extensions.empty?
    end

docs=(d) click to toggle source

    # File lib/mime/types.rb, line 232
    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 122
    def eql?(other)
      other.kind_of?(MIME::Type) and self == other
    end

from_array(*args) { |t| ... } 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 323
    def from_array(*args) #:yields MIME::Type.new:
      # Dereferences the array one level, if necessary.
      args = args.first if args.first.kind_of? Array

      unless args.size.between?(1, 8)
        raise ArgumentError, "Array provided must contain between one and eight elements."
      end

      MIME::Type.new(args.shift) do |t|
        t.extensions, t.encoding, t.system, t.obsolete, t.docs, t.url,
          t.registered = *args
        yield t if block_given?
      end
    end

from_hash(hash) { |t| ... } 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 360
    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(/-/, '_').to_sym] = v
      end

      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]

        yield t if block_given?
      end
    end

from_mime_type(mime_type) { |t| ... } 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 390
    def from_mime_type(mime_type) #:yields the new MIME::Type:
      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

        yield t if block_given?
      end
    end

like?(other) click to toggle source

Returns `true` if the simplified type matches the current

    # File lib/mime/types.rb, line 56
    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 221
    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 480
    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 90
    def priority_compare(other)
      pc = simplified <=> other.simplified

      if pc.zero?
        pc = if registered? != other.registered?
               registered? ? -1 : 1 # registered < unregistered
             elsif platform? != other.platform?
               platform? ? 1 : -1 # generic < platform
             elsif complete? != other.complete?
               complete? ? -1 : 1 # complete < incomplete
             elsif obsolete? != other.obsolete?
               obsolete? ? 1 : -1 # current < obsolete
             else
               0
             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
      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 444
    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 469
    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 474
    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 502
    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 509
    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 491
    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 496
    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 267
    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