local-lib5/lib/perl5/MIME/Types.pod

   1 =head1 NAME
   2
   3 MIME::Types - Definition of MIME types
   4
   5 =head1 INHERITANCE
   6
   7  MIME::Types
   8    is a Exporter
   9
  10 =head1 SYNOPSIS
  11
  12  use MIME::Types;
  13  my $mimetypes = MIME::Types->new;
  14  my MIME::Type $plaintext = $mimetypes->type('text/plain');
  15  my MIME::Type $imagegif  = $mimetypes->mimeTypeOf('gif');
  16
  17 =head1 DESCRIPTION
  18
  19 MIME types are used in MIME compliant lines, for instance as part
  20 of e-mail and HTTP traffic, to indicate the type of content which is
  21 transmitted.  Sometimes real knowledge about a mime-type is need.
  22
  23 This module maintains a set of L<MIME::Type|MIME::Type> objects, which
  24 each describe one known mime type.  There are many types defined
  25 by RFCs and vendors, so the list is long but not complete.  Please
  26 don't hestitate to ask to add additional information.
  27
  28 If you wish to get access to the C<mime.types> files, which are
  29 available on various places in UNIX and Linux systems, then have a
  30 look at File::TypeInfo.
  31
  32 =head1 METHODS
  33
  34 =head2 Instantiation
  35
  36 MIME::Types-E<gt>B<new>(OPTIONS)
  37
  38 =over 4
  39
  40 Create a new C<MIME::Types> object which manages the data.  In the current
  41 implementation, it does not matter whether you create this object often
  42 within your program, but in the future this may change.
  43
  44  Option       --Default
  45  only_complete  <false>
  46
  47 . only_complete => BOOLEAN
  48
  49 =over 4
  50
  51 Only include complete MIME type definitions: requires at least one known
  52 extension.  This will reduce the number of entries --and with that the
  53 amount of memory consumed-- considerably.
  54
  55 In your program you have to decide: the first time that you call
  56 the creator (C<new>) determines whether you get the full or the partial
  57 information.
  58
  59 =back
  60
  61 =back
  62
  63 =head2 Knowledge
  64
  65 $obj-E<gt>B<addType>(TYPE, ...)
  66
  67 =over 4
  68
  69 Add one or more TYPEs to the set of known types.  Each TYPE is a
  70 C<MIME::Type> which must be experimental: either the main-type or
  71 the sub-type must start with C<x->.
  72
  73 Please inform the maintainer of this module when registered types
  74 are missing.  Before version MIME::Types version 1.14, a warning
  75 was produced when an unknown IANA type was added.  This has been
  76 removed, because some people need that to get their application
  77 to work locally... broken applications...
  78
  79 =back
  80
  81 $obj-E<gt>B<extensions>
  82
  83 =over 4
  84
  85 Returns a list of all defined extensions.
  86
  87 =back
  88
  89 $obj-E<gt>B<mimeTypeOf>(FILENAME)
  90
  91 =over 4
  92
  93 Returns the C<MIME::Type> object which belongs to the FILENAME (or simply
  94 its filename extension) or C<undef> if the file type is unknown.  The extension
  95 is used, and considered case-insensitive.
  96
  97 In some cases, more than one type is known for a certain filename extension.
  98 In that case, one of the alternatives is chosen at random.
  99
 100 example: use of mimeTypeOf()
 101
 102  my MIME::Types $types = MIME::Types->new;
 103  my MIME::Type  $mime = $types->mimeTypeOf('gif');
 104
 105  my MIME::Type  $mime = $types->mimeTypeOf('jpg');
 106  print $mime->isBinary;
 107
 108 =back
 109
 110 $obj-E<gt>B<type>(STRING)
 111
 112 =over 4
 113
 114 Return the C<MIME::Type> which describes the type related to STRING.  One
 115 type may be described more than once.  Different extensions is use for
 116 this type, and different operating systems may cause more than one
 117 C<MIME::Type> object to be defined.  In scalar context, only the first
 118 is returned.
 119
 120 =back
 121
 122 $obj-E<gt>B<types>
 123
 124 =over 4
 125
 126 Returns a list of all defined mime-types
 127
 128 =back
 129
 130 =head1 FUNCTIONS
 131
 132 The next functions are provided for backward compatibility with MIME::Types
 133 versions 0.06 and below.  This code originates from Jeff Okamoto
 134 F<okamoto@corp.hp.com> and others.
 135
 136 B<by_mediatype>(TYPE)
 137
 138 =over 4
 139
 140 This function takes a media type and returns a list or anonymous array of
 141 anonymous three-element arrays whose values are the file name suffix used to
 142 identify it, the media type, and a content encoding.
 143
 144 TYPE can be a full type name (contains '/', and will be matched in full),
 145 a partial type (which is used as regular expression) or a real regular
 146 expression.
 147
 148 =back
 149
 150 B<by_suffix>(FILENAME|SUFFIX)
 151
 152 =over 4
 153
 154 Like C<mimeTypeOf>, but does not return an C<MIME::Type> object. If the file
 155 +type is unknown, both the returned media type and encoding are empty strings.
 156
 157 example: use of function by_suffix()
 158
 159  use MIME::Types 'by_suffix';
 160  my ($mediatype, $encoding) = by_suffix 'image.gif';
 161
 162  my $refdata =  by_suffix 'image.gif';
 163  my ($mediatype, $encoding) = @$refdata;
 164
 165 =back
 166
 167 B<import_mime_types>
 168
 169 =over 4
 170
 171 This method has been removed: mime-types are only useful if understood
 172 by many parties.  Therefore, the IANA assigns names which can be used.
 173 In the table kept by this C<MIME::Types> module all these names, plus
 174 the most often used termporary names are kept.  When names seem to be
 175 missing, please contact the maintainer for inclussion.
 176
 177 =back
 178
 179 =head1 SEE ALSO
 180
 181 This module is part of MIME-Types distribution version 1.28,
 182 built on September 07, 2009. Website: F<http://perl.overmeer.net/mimetypes/>
 183
 184 =head1 LICENSE
 185
 186 Copyrights 1999,2001-2009 by Mark Overmeer. For other contributors see ChangeLog.
 187
 188 This program is free software; you can redistribute it and/or modify it
 189 under the same terms as Perl itself.
 190 See F<http://www.perl.com/perl/misc/Artistic.html>
 191