Class: MIME::Types
Overview
MIME::Types
MIME types are used in MIME-compliant communications, as in e-mail or HTTP traffic, to indicate the type of content which is transmitted. MIME::Types provides the ability for detailed information about MIME entities (provided as a set of MIME::Type objects) to be determined and used programmatically. There are many types defined by RFCs and vendors, so the list is long but not complete; don’t hesitate to ask to add additional information. This library follows the IANA collection of MIME types (see below for reference).
Description
MIME types are used in MIME entities, as in email or HTTP traffic. It is useful at times to have information available about MIME types (or, inversely, about files). A MIME::Type stores the known information about one MIME 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.obsolete? # => false
puts plaintext.registered? # => true
puts plaintext == 'text/plain' # => true
puts MIME::Type.simplified('x-appl/x-zip') # => 'appl/zip'
This module is built to conform to the MIME types of RFCs 2045 and 2231. It follows the official IANA registry at www.iana.org/assignments/media-types/ and ftp.iana.org/assignments/media-types with some unofficial types added from the the collection at www.ltsw.se/knbase/internet/mime.htp
Defined Under Namespace
Classes: CacheContainer, HashWithArrayDefault
Constant Summary collapse
- VERSION =
The released version of Ruby MIME::Types
MIME::Type::VERSION
- DATA_VERSION =
(VERSION.to_f * 100).to_i
- TEXT_FORMAT_RE =
The regular expression used to match a file-based MIME type definition.
%r{ \A \s* ([*])? # 0: Unregistered? (!)? # 1: Obsolete? (?:(\w+):)? # 2: Platform marker #{MIME::Type::MEDIA_TYPE_RE}? # 3,4: Media type (?:\s+@([^\s]+))? # 5: Extensions (?:\s+:(#{MIME::Type::ENCODING_RE}))? # 6: Encoding (?:\s+'(.+))? # 7: URL list (?:\s+=(.+))? # 8: Documentation (?:\s*([#].*)?)? \s* \z }x
Instance Attribute Summary collapse
-
#data_version ⇒ Object
readonly
The data version.
Class Method Summary collapse
-
.[](type_id, flags = {}) ⇒ Object
Returns a list of MIME::Type objects, which may be empty.
-
.add(*types) ⇒ Object
Add one or more MIME::Type objects to the set of known types.
-
.add_type_variant(mime_type) ⇒ Object
:nodoc:.
-
.cache_file ⇒ Object
Returns the currently defined cache file, if any.
- .count ⇒ Object
- .each ⇒ Object
-
.index_extensions(mime_type) ⇒ Object
:nodoc:.
-
.load_from_file(filename) ⇒ Object
Build the type list from a file in the format:.
-
.of(filename, platform = false) ⇒ Object
A synonym for MIME::Types.type_for.
-
.type_for(filename, platform = false) ⇒ Object
Return the list of MIME::Types which belongs to the file based on its filename extension.
Instance Method Summary collapse
-
#[](type_id, flags = {}) ⇒ Object
Returns a list of MIME::Type objects, which may be empty.
-
#add(*types) ⇒ Object
Add one or more MIME::Type objects to the set of known types.
-
#add_type_variant(mime_type) ⇒ Object
:nodoc:.
-
#count ⇒ Object
Returns the number of known types.
-
#defined_types ⇒ Object
:nodoc:.
- #each ⇒ Object
-
#index_extensions(mime_type) ⇒ Object
:nodoc:.
-
#initialize(data_version = DATA_VERSION) ⇒ Types
constructor
A new instance of Types.
-
#of(filename, platform = false) ⇒ Object
A synonym for MIME::Types.type_for.
-
#type_for(filename, platform = false) ⇒ Object
Return the list of MIME::Types which belongs to the file based on its filename extension.
Constructor Details
#initialize(data_version = DATA_VERSION) ⇒ Types
Returns a new instance of Types.
591 592 593 594 595 |
# File 'lib/mime/types.rb', line 591 def initialize(data_version = DATA_VERSION) @type_variants = HashWithArrayDefault.new @extension_index = HashWithArrayDefault.new @data_version = data_version end |
Instance Attribute Details
#data_version ⇒ Object (readonly)
The data version.
568 569 570 |
# File 'lib/mime/types.rb', line 568 def data_version @data_version end |
Class Method Details
.[](type_id, flags = {}) ⇒ Object
Returns a list of MIME::Type objects, which may be empty. The optional flag parameters are :complete (finds only complete MIME::Type objects) and :platform (finds only MIME::Types for the current platform). It is possible for multiple matches to be returned for either type (in the example below, ‘text/plain’ returns two values – one for the general case, and one for VMS systems.
puts "\nMIME::Types['text/plain']"
MIME::Types['text/plain'].each { |t| puts t.to_a.join(", ") }
puts "\nMIME::Types[/^image/, :complete => true]"
MIME::Types[/^image/, :complete => true].each do |t|
puts t.to_a.join(", ")
end
849 850 851 |
# File 'lib/mime/types.rb', line 849 def [](type_id, flags = {}) __types__[type_id, flags] end |
.add(*types) ⇒ Object
Add one or more MIME::Type objects to the set of known types. Each type should be experimental (e.g., ‘application/x-ruby’). If the type is already known, a warning will be displayed.
<strong>Please inform the maintainer of this module when registered types are missing.</strong>
888 889 890 |
# File 'lib/mime/types.rb', line 888 def add(*types) __types__.add(*types) end |
.add_type_variant(mime_type) ⇒ Object
:nodoc:
722 723 724 |
# File 'lib/mime/types.rb', line 722 def add_type_variant(mime_type) #:nodoc: __types__.add_type_variant(mime_type) end |
.cache_file ⇒ Object
Returns the currently defined cache file, if any.
893 894 895 |
# File 'lib/mime/types.rb', line 893 def cache_file ENV['RUBY_MIME_TYPES_CACHE'] end |
.count ⇒ Object
855 856 857 |
# File 'lib/mime/types.rb', line 855 def count __types__.count end |
.each ⇒ Object
859 860 861 |
# File 'lib/mime/types.rb', line 859 def each __types__.each {|t| yield t } end |
.index_extensions(mime_type) ⇒ Object
:nodoc:
726 727 728 |
# File 'lib/mime/types.rb', line 726 def index_extensions(mime_type) #:nodoc: __types__.index_extensions(mime_type) end |
.load_from_file(filename) ⇒ Object
Build the type list from a file in the format:
[*][!][os:]mt/st[<ws>@ext][<ws>:enc][<ws>'url-list][<ws>=docs]
*
An unofficial MIME type. This should be used if and only if the MIME type is not properly specified (that is, not under either x-type or vnd.name.type).
!
An obsolete MIME type. May be used with an unofficial MIME type.
os:
Platform-specific MIME type definition.
mt
The media type.
st
The media subtype.
<ws>@ext
The list of comma-separated extensions.
<ws>:enc
The encoding.
<ws>‘url-list
The list of comma-separated URLs.
<ws>=docs
The documentation string.
That is, everything except the media type and the subtype is optional. The more information that’s available, though, the richer the values that can be provided.
784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 |
# File 'lib/mime/types.rb', line 784 def load_from_file(filename) #:nodoc: if defined? ::Encoding data = File.open(filename, 'r:UTF-8:-') { |f| f.read } else data = File.open(filename) { |f| f.read } end data = data.split($/) mime = MIME::Types.new data.each_with_index { |line, index| item = line.chomp.strip next if item.empty? begin m = TEXT_FORMAT_RE.match(item).captures rescue Exception puts "#{filename}:#{index}: Parsing error in MIME type definitions." puts "=> #{line}" raise end unregistered, obsolete, platform, mediatype, subtype, extensions, encoding, urls, docs, comment = *m if mediatype.nil? if comment.nil? puts "#{filename}:#{index}: Parsing error in MIME type definitions." puts "=> #{line}" raise RuntimeError end next end extensions &&= extensions.split(/,/) urls &&= urls.split(/,/) mime_type = MIME::Type.new("#{mediatype}/#{subtype}") do |t| t.extensions = extensions t.encoding = encoding t.system = platform t.obsolete = obsolete t.registered = false if unregistered t.docs = docs t.url = urls end mime.add(mime_type) } mime end |
.of(filename, platform = false) ⇒ Object
A synonym for MIME::Types.type_for
878 879 880 |
# File 'lib/mime/types.rb', line 878 def of(filename, platform = false) __types__.type_for(filename, platform) end |
.type_for(filename, platform = false) ⇒ Object
Return the list of MIME::Types which belongs to the file based on its filename extension. If platform
is true
, then only file types that are specific to the current platform will be returned.
This will always return an array.
puts "MIME::Types.type_for('citydesk.xml')
=> [application/xml, text/xml]
puts "MIME::Types.type_for('citydesk.gif')
=> [image/gif]
873 874 875 |
# File 'lib/mime/types.rb', line 873 def type_for(filename, platform = false) __types__.type_for(filename, platform) end |
Instance Method Details
#[](type_id, flags = {}) ⇒ Object
Returns a list of MIME::Type objects, which may be empty. The optional flag parameters are :complete (finds only complete MIME::Type objects) and :platform (finds only MIME::Types for the current platform). It is possible for multiple matches to be returned for either type (in the example below, ‘text/plain’ returns two values – one for the general case, and one for VMS systems.
puts "\nMIME::Types['text/plain']"
MIME::Types['text/plain'].each { |t| puts t.to_a.join(", ") }
puts "\nMIME::Types[/^image/, :complete => true]"
MIME::Types[/^image/, :complete => true].each do |t|
puts t.to_a.join(", ")
end
If multiple type definitions are returned, returns them sorted as follows:
1. Complete definitions sort before incomplete ones;
2. IANA-registered definitions sort before LTSW-recorded
definitions.
3. Generic definitions sort before platform-specific ones;
4. Current definitions sort before obsolete ones;
5. Obsolete definitions with use-instead clauses sort before those
without;
6. Obsolete definitions use-instead clauses are compared.
7. Sort on name.
648 649 650 651 652 653 654 655 656 657 658 659 |
# File 'lib/mime/types.rb', line 648 def [](type_id, flags = {}) matches = case type_id when MIME::Type @type_variants[type_id.simplified] when Regexp match(type_id) else @type_variants[MIME::Type.simplified(type_id)] end prune_matches(matches, flags).sort { |a, b| a.priority_compare(b) } end |
#add(*types) ⇒ Object
Add one or more MIME::Type objects to the set of known types. Each type should be experimental (e.g., ‘application/x-ruby’). If the type is already known, a warning will be displayed.
<strong>Please inform the maintainer of this module when registered types are missing.</strong>
689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 |
# File 'lib/mime/types.rb', line 689 def add(*types) types.each do |mime_type| if mime_type.kind_of? MIME::Types add(*mime_type.defined_types) else if @type_variants.include?(mime_type.simplified) if @type_variants[mime_type.simplified].include?(mime_type) warn "Type #{mime_type} already registered as a variant of #{mime_type.simplified}." unless defined? MIME::Types::LOAD end end add_type_variant(mime_type) index_extensions(mime_type) end end end |
#add_type_variant(mime_type) ⇒ Object
:nodoc:
597 598 599 |
# File 'lib/mime/types.rb', line 597 def add_type_variant(mime_type) #:nodoc: @type_variants[mime_type.simplified] << mime_type end |
#count ⇒ Object
Returns the number of known types. A shortcut of MIME::Types.size. (Keep in mind that this is memory intensive, cache the result to spare resources)
612 613 614 |
# File 'lib/mime/types.rb', line 612 def count defined_types.size end |
#defined_types ⇒ Object
:nodoc:
605 606 607 |
# File 'lib/mime/types.rb', line 605 def defined_types #:nodoc: @type_variants.values.flatten end |
#each ⇒ Object
616 617 618 |
# File 'lib/mime/types.rb', line 616 def each defined_types.each { |t| yield t } end |
#index_extensions(mime_type) ⇒ Object
:nodoc:
601 602 603 |
# File 'lib/mime/types.rb', line 601 def index_extensions(mime_type) #:nodoc: mime_type.extensions.each { |ext| @extension_index[ext] << mime_type } end |
#of(filename, platform = false) ⇒ Object
A synonym for MIME::Types.type_for
679 680 681 |
# File 'lib/mime/types.rb', line 679 def of(filename, platform = false) type_for(filename, platform) end |
#type_for(filename, platform = false) ⇒ Object
Return the list of MIME::Types which belongs to the file based on its filename extension. If platform
is true
, then only file types that are specific to the current platform will be returned.
This will always return an array.
puts "MIME::Types.type_for('citydesk.xml')
=> [application/xml, text/xml]
puts "MIME::Types.type_for('citydesk.gif')
=> [image/gif]
671 672 673 674 675 676 |
# File 'lib/mime/types.rb', line 671 def type_for(filename, platform = false) ext = filename.chomp.downcase.gsub(/.*\./o, '') list = @extension_index[ext] list.delete_if { |e| not e.platform? } if platform list end |