Class: MIME::Type
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 =
The released version of Ruby MIME::Types
'1.23'
- 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
-
#content_type ⇒ Object
readonly
Returns the whole MIME content-type string.
-
#default_encoding ⇒ Object
readonly
Returns the default encoding for the MIME::Type based on the media type.
-
#docs ⇒ Object
The documentation for this MIME::Type.
-
#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.
-
#extensions ⇒ Object
The list of extensions which are known to be used for this MIME::Type.
-
#media_type ⇒ Object
readonly
Returns the media type of the simplified MIME type.
-
#obsolete ⇒ Object
writeonly
Sets the obsolescence indicator for this media type.
-
#raw_media_type ⇒ Object
readonly
Returns the media type of the unmodified MIME type.
-
#raw_sub_type ⇒ Object
readonly
Returns the media type of the unmodified MIME type.
-
#registered ⇒ Object
writeonly
:nodoc:.
-
#simplified ⇒ Object
readonly
The MIME types main- and sub-label can both start with
x-
, which indicates that it is a non-registered name. -
#sub_type ⇒ Object
readonly
Returns the sub-type of the simplified MIME type.
-
#system ⇒ Object
The regexp for the operating system that this MIME::Type is specific to.
-
#url ⇒ Object
The encoded URL list for this MIME::Type.
-
#use_instead ⇒ Object
readonly
Returns the media type or types that should be used instead of this media type, if it is obsolete.
Class Method Summary collapse
-
.from_array(*args) ⇒ Object
Creates a MIME::Type from an array in the form of: [type-name, [extensions], encoding, system].
-
.from_hash(hash) {|m| ... } ⇒ Object
Creates a MIME::Type from a hash.
-
.from_mime_type(mime_type) {|m| ... } ⇒ Object
Essentially a copy constructor.
-
.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.
Instance Method Summary collapse
-
#<=>(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).
-
#ascii? ⇒ Boolean
MIME types can be specified to be sent across a network in particular formats.
-
#binary? ⇒ Boolean
MIME types can be specified to be sent across a network in particular formats.
-
#complete? ⇒ Boolean
Returns
true
if the MIME::Type specifies an extension list, indicating that it is a complete MIME::Type. -
#eql?(other) ⇒ Boolean
Returns
true
if the other object is a MIME::Type and the content types match. -
#initialize(content_type) {|_self| ... } ⇒ Type
constructor
Builds a MIME::Type object from the provided MIME Content Type value (e.g., ‘text/plain’ or ‘applicaton/x-eruby’).
-
#like?(other) ⇒ Boolean
Returns
true
if the simplified type matches the current. -
#obsolete? ⇒ Boolean
Returns
true
if the media type is obsolete. -
#platform? ⇒ Boolean
Returns
true
if the MIME::Type is specific to the current operating system as represented by RUBY_PLATFORM. -
#priority_compare(other) ⇒ Object
Compares the MIME::Type based on how reliable it is before doing a normal <=> comparison.
-
#registered? ⇒ Boolean
MIME content-types which are not regestered by IANA nor defined in RFCs are required to start with
x-
. -
#signature? ⇒ Boolean
Returns
true
when the simplified MIME type is in the list of known digital signatures. -
#system? ⇒ Boolean
Returns
true
if the MIME::Type is specific to an operating system. -
#to_a ⇒ Object
Returns the MIME type as an array suitable for use with MIME::Type.from_array.
-
#to_hash ⇒ Object
Returns the MIME type as an array suitable for use with MIME::Type.from_hash.
-
#to_s ⇒ Object
Returns the MIME type as a string.
-
#to_str ⇒ Object
Returns the MIME type as a string for implicit conversions.
-
#urls ⇒ Object
The decoded URL list for this MIME::Type.
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.
415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 |
# File 'lib/mime/types.rb', line 415 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
125 126 127 |
# File 'lib/mime/types.rb', line 125 def content_type @content_type end |
#default_encoding ⇒ Object (readonly)
Returns the default encoding for the MIME::Type based on the media type.
199 200 201 |
# File 'lib/mime/types.rb', line 199 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.
225 226 227 |
# File 'lib/mime/types.rb', line 225 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.
174 175 176 |
# File 'lib/mime/types.rb', line 174 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.
158 159 160 |
# File 'lib/mime/types.rb', line 158 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
130 131 132 |
# File 'lib/mime/types.rb', line 130 def media_type @media_type end |
#obsolete=(value) ⇒ Object (writeonly)
Sets the obsolescence indicator for this media type.
220 221 222 |
# File 'lib/mime/types.rb', line 220 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
135 136 137 |
# File 'lib/mime/types.rb', line 135 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
145 146 147 |
# File 'lib/mime/types.rb', line 145 def raw_sub_type @raw_sub_type end |
#registered=(value) ⇒ Object (writeonly)
:nodoc:
454 455 456 |
# File 'lib/mime/types.rb', line 454 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
154 155 156 |
# File 'lib/mime/types.rb', line 154 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
140 141 142 |
# File 'lib/mime/types.rb', line 140 def sub_type @sub_type end |
#system ⇒ Object
The regexp for the operating system that this MIME::Type is specific to.
188 189 190 |
# File 'lib/mime/types.rb', line 188 def system @system end |
#url ⇒ Object
The encoded URL list for this MIME::Type. See #urls for more information.
242 243 244 |
# File 'lib/mime/types.rb', line 242 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.
208 209 210 |
# File 'lib/mime/types.rb', line 208 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
318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 |
# File 'lib/mime/types.rb', line 318 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
361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 |
# File 'lib/mime/types.rb', line 361 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
392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 |
# File 'lib/mime/types.rb', line 392 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.
291 292 293 294 295 296 297 298 299 300 301 302 |
# File 'lib/mime/types.rb', line 291 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.
61 62 63 64 65 66 67 68 69 |
# File 'lib/mime/types.rb', line 61 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
.
466 467 468 |
# File 'lib/mime/types.rb', line 466 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
.
459 460 461 |
# File 'lib/mime/types.rb', line 459 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.
489 490 491 |
# File 'lib/mime/types.rb', line 489 def complete? not @extensions.empty? end |
#eql?(other) ⇒ Boolean
Returns true
if the other object is a MIME::Type and the content types match.
117 118 119 |
# File 'lib/mime/types.rb', line 117 def eql?(other) other.kind_of?(MIME::Type) and self == other end |
#like?(other) ⇒ Boolean
Returns true
if the simplified type matches the current
49 50 51 52 53 54 55 |
# File 'lib/mime/types.rb', line 49 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.
216 217 218 |
# File 'lib/mime/types.rb', line 216 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.
483 484 485 |
# File 'lib/mime/types.rb', line 483 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:
-
self.simplified <=> other.simplified (ensures that we don’t try to compare different types)
-
IANA-registered definitions > other definitions.
-
Generic definitions > platform definitions.
-
Complete definitions > incomplete definitions.
-
Current definitions > obsolete definitions.
-
Obselete with use-instead references > obsolete without.
-
Obsolete use-instead definitions are compared.
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 |
# File 'lib/mime/types.rb', line 83 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
.
447 448 449 450 451 452 453 |
# File 'lib/mime/types.rb', line 447 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.
472 473 474 |
# File 'lib/mime/types.rb', line 472 def signature? SIGNATURES.include?(@simplified.downcase) end |
#system? ⇒ Boolean
Returns true
if the MIME::Type is specific to an operating system.
477 478 479 |
# File 'lib/mime/types.rb', line 477 def system? not @system.nil? end |
#to_a ⇒ Object
Returns the MIME type as an array suitable for use with MIME::Type.from_array.
505 506 507 508 |
# File 'lib/mime/types.rb', line 505 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.
512 513 514 515 516 517 518 519 520 521 522 |
# File 'lib/mime/types.rb', line 512 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.
494 495 496 |
# File 'lib/mime/types.rb', line 494 def to_s @content_type end |
#to_str ⇒ Object
Returns the MIME type as a string for implicit conversions.
499 500 501 |
# File 'lib/mime/types.rb', line 499 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.
262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 |
# File 'lib/mime/types.rb', line 262 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 |