Class: MIME::Type

Inherits:
Object show all
Includes:
Comparable
Defined in:
lib/mime-types-1.16/lib/mime/types.rb

Overview

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'

Constant Summary collapse

VERSION = 
'1.16'
MEDIA_TYPE_RE = 
%r{([-\w.+]+)/([-\w.+]*)}o
UNREG_RE = 
%r{[Xx]-}o
ENCODING_RE = 
%r{(?:base64|7bit|8bit|quoted\-printable)}o
PLATFORM_RE = 
%r|#{RUBY_PLATFORM}|o
SIGNATURES = 
%w(application/pgp-keys application/pgp
application/pgp-signature application/pkcs10
application/pkcs7-mime application/pkcs7-signature
text/vcard)
IANA_URL = 
"http://www.iana.org/assignments/media-types/%s/%s"
RFC_URL = 
"http://rfc-editor.org/rfc/rfc%s.txt"
DRAFT_URL = 
"http://datatracker.ietf.org/public/idindex.cgi?command=id_details&filename=%s"
LTSW_URL = 
"http://www.ltsw.se/knbase/internet/%s.htp"
CONTACT_URL = 
"http://www.iana.org/assignments/contact-people.htm#%s"

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

Yields:

  • (_self)

Yield Parameters:

  • _self (MIME::Type) —

    the object that the method was called on



425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 425

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

Instance Attribute Details

#content_type ⇒ Object (readonly)

Returns the whole MIME content-type string.

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



135
136
137
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 135

def content_type
  @content_type
end

#default_encoding ⇒ Object (readonly)

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



209
210
211
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 209

def default_encoding
  @default_encoding
end

#docs ⇒ Object

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.



235
236
237
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 235

def docs
  @docs
end

#encoding ⇒ Object

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.



184
185
186
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 184

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



168
169
170
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 168

def extensions
  @extensions
end

#media_type ⇒ Object (readonly)

Returns the media type of the simplified MIME type.

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



140
141
142
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 140

def media_type
  @media_type
end

#obsolete=(value) ⇒ Object (writeonly)

Sets the obsolescence indicator for this media type.



230
231
232
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 230

def obsolete=(value)
  @obsolete = value
end

#raw_media_type ⇒ Object (readonly)

Returns the media type of the unmodified MIME type.

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



145
146
147
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 145

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



155
156
157
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 155

def raw_sub_type
  @raw_sub_type
end

#registered=(value) ⇒ Object (writeonly)

:nodoc:



464
465
466
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 464

def registered=(value)
  @registered = value
end

#simplified ⇒ Object (readonly)

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



164
165
166
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 164

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



150
151
152
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 150

def sub_type
  @sub_type
end

#system ⇒ Object

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



198
199
200
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 198

def system
  @system
end

#url ⇒ Object

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



252
253
254
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 252

def url
  @url
end

#use_instead ⇒ Object (readonly)

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.



218
219
220
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 218

def use_instead
  @use_instead
end

Class Method Details

.from_array(*args) ⇒ Object

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



328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 328

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| ... } ⇒ Object

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

Yields:

  • (m) 


371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 371

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

  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| ... } ⇒ Object

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

Yields:

  • (m) 


402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 402

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

.simplified(content_type) ⇒ Object

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.



301
302
303
304
305
306
307
308
309
310
311
312
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 301

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

Instance Method Details

#<=>(other) ⇒ Object

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.



71
72
73
74
75
76
77
78
79
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 71

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? ⇒ 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) 


476
477
478
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 476

def ascii?
  not binary?
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) 


469
470
471
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 469

def binary?
  @encoding == 'base64'
end

#complete? ⇒ Boolean

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

Returns:

  • (Boolean) 


499
500
501
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 499

def complete?
  not @extensions.empty?
end

#eql?(other) ⇒ Boolean

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

Returns:

  • (Boolean) 


127
128
129
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 127

def eql?(other)
  other.kind_of?(MIME::Type) and self == other
end

#like?(other) ⇒ Boolean

Returns true if the simplified type matches the current

Returns:

  • (Boolean) 


59
60
61
62
63
64
65
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 59

def like?(other)
  if other.respond_to?(:simplified)
    @simplified == other.simplified
  else
    @simplified == Type.simplified(other)
  end
end

#obsolete? ⇒ Boolean

Returns true if the media type is obsolete.

Returns:

  • (Boolean) 


226
227
228
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 226

def obsolete?
  @obsolete ? true : false
end

#platform? ⇒ Boolean

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

Returns:

  • (Boolean) 


493
494
495
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 493

def platform?
  system? and (RUBY_PLATFORM =~ @system)
end

#priority_compare(other) ⇒ Object

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.



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 93

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? ⇒ Boolean

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.

Returns:

  • (Boolean) 


457
458
459
460
461
462
463
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 457

def registered?
  if (@raw_media_type =~ UNREG_RE) || (@raw_sub_type =~ UNREG_RE)
    false
  else
    @registered
  end
end

#signature? ⇒ Boolean

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

Returns:

  • (Boolean) 


482
483
484
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 482

def signature?
  SIGNATURES.include?(@simplified.downcase)
end

#system? ⇒ Boolean

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

Returns:

  • (Boolean) 


487
488
489
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 487

def system?
  not @system.nil?
end

#to_a ⇒ Object

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



515
516
517
518
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 515

def to_a
  [ @content_type, @extensions, @encoding, @system, @obsolete, @docs,
    @url, registered? ]
end

#to_hash ⇒ Object

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



522
523
524
525
526
527
528
529
530
531
532
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 522

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 ⇒ Object

Returns the MIME type as a string.



504
505
506
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 504

def to_s
  @content_type
end

#to_str ⇒ Object

Returns the MIME type as a string for implicit conversions.



509
510
511
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 509

def to_str
  @content_type
end

#urls ⇒ Object

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.



272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 272

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