Class: MIME::Type
Overview
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
Constant Summary collapse
- VERSION =
The released version of Ruby MIME::Types
'1.25.1'
- 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) ⇒ Object
Creates a MIME::Type from a hash.
-
.from_mime_type(mime_type) ⇒ 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.
413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 |
# File 'lib/mime/types.rb', line 413 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
131 132 133 |
# File 'lib/mime/types.rb', line 131 def content_type @content_type end |
#default_encoding ⇒ Object (readonly)
Returns the default encoding for the MIME::Type based on the media type.
205 206 207 |
# File 'lib/mime/types.rb', line 205 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.
231 232 233 |
# File 'lib/mime/types.rb', line 231 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.
180 181 182 |
# File 'lib/mime/types.rb', line 180 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.
164 165 166 |
# File 'lib/mime/types.rb', line 164 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
136 137 138 |
# File 'lib/mime/types.rb', line 136 def media_type @media_type end |
#obsolete=(value) ⇒ Object (writeonly)
Sets the obsolescence indicator for this media type.
226 227 228 |
# File 'lib/mime/types.rb', line 226 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
141 142 143 |
# File 'lib/mime/types.rb', line 141 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
151 152 153 |
# File 'lib/mime/types.rb', line 151 def raw_sub_type @raw_sub_type end |
#registered=(value) ⇒ Object (writeonly)
:nodoc:
452 453 454 |
# File 'lib/mime/types.rb', line 452 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
160 161 162 |
# File 'lib/mime/types.rb', line 160 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
146 147 148 |
# File 'lib/mime/types.rb', line 146 def sub_type @sub_type end |
#system ⇒ Object
The regexp for the operating system that this MIME::Type is specific to.
194 195 196 |
# File 'lib/mime/types.rb', line 194 def system @system end |
#url ⇒ Object
The encoded URL list for this MIME::Type. See #urls for more information.
248 249 250 |
# File 'lib/mime/types.rb', line 248 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.
214 215 216 |
# File 'lib/mime/types.rb', line 214 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
324 325 326 327 328 329 330 331 332 333 334 335 336 337 |
# File 'lib/mime/types.rb', line 324 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) ⇒ 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 |
# 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 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) ⇒ Object
391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 |
# File 'lib/mime/types.rb', line 391 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 |
.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.
297 298 299 300 301 302 303 304 305 306 307 308 |
# File 'lib/mime/types.rb', line 297 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.
69 70 71 72 73 74 75 76 77 |
# File 'lib/mime/types.rb', line 69 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
.
464 465 466 |
# File 'lib/mime/types.rb', line 464 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
.
457 458 459 |
# File 'lib/mime/types.rb', line 457 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.
487 488 489 |
# File 'lib/mime/types.rb', line 487 def complete? not @extensions.empty? end |
#eql?(other) ⇒ Boolean
Returns true
if the other object is a MIME::Type and the content types match.
123 124 125 |
# File 'lib/mime/types.rb', line 123 def eql?(other) other.kind_of?(MIME::Type) and self == other end |
#like?(other) ⇒ Boolean
Returns true
if the simplified type matches the current
57 58 59 60 61 62 63 |
# File 'lib/mime/types.rb', line 57 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.
222 223 224 |
# File 'lib/mime/types.rb', line 222 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.
481 482 483 |
# File 'lib/mime/types.rb', line 481 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.
91 92 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 |
# File 'lib/mime/types.rb', line 91 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? ⇒ 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
.
445 446 447 448 449 450 451 |
# File 'lib/mime/types.rb', line 445 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.
470 471 472 |
# File 'lib/mime/types.rb', line 470 def signature? SIGNATURES.include?(@simplified.downcase) end |
#system? ⇒ Boolean
Returns true
if the MIME::Type is specific to an operating system.
475 476 477 |
# File 'lib/mime/types.rb', line 475 def system? not @system.nil? end |
#to_a ⇒ Object
Returns the MIME type as an array suitable for use with MIME::Type.from_array.
503 504 505 506 |
# File 'lib/mime/types.rb', line 503 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.
510 511 512 513 514 515 516 517 518 519 520 |
# File 'lib/mime/types.rb', line 510 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.
492 493 494 |
# File 'lib/mime/types.rb', line 492 def to_s @content_type end |
#to_str ⇒ Object
Returns the MIME type as a string for implicit conversions.
497 498 499 |
# File 'lib/mime/types.rb', line 497 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.
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 |
# File 'lib/mime/types.rb', line 268 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 |