Class: MIME::Types

Inherits:
Object show all
Defined in:
lib/mime-types-1.16/lib/mime/types.rb,
lib/rest-client-1.4.2/lib/restclient/request.rb

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

This is originally based on Perl MIME::Types by Mark Overmeer.

Author

Copyright

Copyright © 2002 - 2009 by Austin Ziegler <[email protected]>

Version

1.16

Based On

Perl MIME::Types, Copyright © 2001 - 2009 by Mark Overmeer <[email protected]>.

Licence

Ruby’s, Perl Artistic, or GPL version 2 (or later)

See Also

www.iana.org/assignments/media-types/ www.ltsw.se/knbase/internet/mime.htp

Constant Summary collapse

VERSION =

The released version of Ruby MIME::Types

'1.16'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data_version = nil) ⇒ Types

Returns a new instance of Types.



596
597
598
599
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 596

def initialize(data_version = nil)
  @type_variants    = Hash.new { |h, k| h[k] = [] }
  @extension_index  = Hash.new { |h, k| h[k] = [] }
end

Instance Attribute Details

#data_version ⇒ Object (readonly)

The data version.



594
595
596
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 594

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



717
718
719
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 717

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.

Please inform the maintainer of this module when registered types are missing.



744
745
746
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 744

def add(*types)
  @__types__.add(*types)
end

.add_type_variant(mime_type) ⇒ Object

:nodoc:



695
696
697
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 695

def add_type_variant(mime_type) #:nodoc:
  @__types__.add_type_variant(mime_type)
end

.index_extensions(mime_type) ⇒ Object

:nodoc:



699
700
701
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 699

def index_extensions(mime_type) #:nodoc:
  @__types__.index_extensions(mime_type)
end

.of(filename, platform = false) ⇒ Object

A synonym for MIME::Types.type_for



734
735
736
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 734

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.

puts "MIME::Types.type_for('citydesk.xml')
  => "#{MIME::Types.type_for('citydesk.xml')}"
puts "MIME::Types.type_for('citydesk.gif')
  => "#{MIME::Types.type_for('citydesk.gif')}"



729
730
731
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 729

def type_for(filename, platform = false)
  @__types__.type_for(filename, platform)
end

.type_for_extension(ext) ⇒ Object 



254
255
256
 
# File 'lib/rest-client-1.4.2/lib/restclient/request.rb', line 254

def type_for_extension ext
  @__types__.type_for_extension ext
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.



637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 637

def [](type_id, flags = {})
  if type_id.kind_of?(Regexp)
    matches = []
    @type_variants.each_key do |k|
      matches << @type_variants[k] if k =~ type_id
    end
    matches.flatten!
  elsif type_id.kind_of?(MIME::Type)
    matches = [type_id]
  else
    matches = @type_variants[MIME::Type.simplified(type_id)]
  end

  matches.delete_if { |e| not e.complete? } if flags[:complete]
  matches.delete_if { |e| not e.platform? } if flags[:platform]

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

Please inform the maintainer of this module when registered types are missing.



682
683
684
685
686
687
688
689
690
691
692
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 682

def add(*types)
  types.each do |mime_type|
    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}."
      end
    end
    add_type_variant(mime_type)
    index_extensions(mime_type)
  end
end

#add_type_variant(mime_type) ⇒ Object

:nodoc:



601
602
603
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 601

def add_type_variant(mime_type) #:nodoc:
  @type_variants[mime_type.simplified] << mime_type
end

#index_extensions(mime_type) ⇒ Object

:nodoc:



605
606
607
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 605

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



672
673
674
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 672

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.

puts "MIME::Types.type_for('citydesk.xml')
  => "#{MIME::Types.type_for('citydesk.xml')}"
puts "MIME::Types.type_for('citydesk.gif')
  => "#{MIME::Types.type_for('citydesk.gif')}"



664
665
666
667
668
669
 
# File 'lib/mime-types-1.16/lib/mime/types.rb', line 664

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

#type_for_extension(ext) ⇒ Object

Return the first found content-type for a value considered as an extension or the value itself



248
249
250
251
 
# File 'lib/rest-client-1.4.2/lib/restclient/request.rb', line 248

def type_for_extension ext
  candidates = @extension_index[ext]
  candidates.empty? ? ext : candidates[0].content_type
end