1MIME::Types(3)        User Contributed Perl Documentation       MIME::Types(3)
2
3
4

NAME

6       MIME::Types - Definition of MIME types
7

INHERITANCE

9        MIME::Types
10          is a Exporter
11

SYNOPSIS

13        use MIME::Types;
14        my $mt    = MIME::Types->new(...);    # MIME::Types object
15        my $type  = $mt->type('text/plain');  # MIME::Type  object
16        my $type  = $mt->mimeTypeOf('gif');
17        my $type  = $mt->mimeTypeOf('picture.jpg');
18        my @types = $mt->httpAccept('text/html, application/json;q=0.1')
19

DESCRIPTION

21       MIME types are used in many applications (for instance as part of
22       e-mail and HTTP traffic) to indicate the type of content which is
23       transmitted.  or expected.  See RFC2045 at
24       https://www.ietf.org/rfc/rfc2045.txt
25
26       Sometimes detailed knowledge about a mime-type is need, however this
27       module only knows about the file-name extensions which relate to some
28       filetype.  It can also be used to produce the right format: types which
29       are not registered at IANA need to use 'x-' prefixes.
30
31       This object administers a huge list of known mime-types, combined from
32       various sources.  For instance, it contains all IANA types and the
33       knowledge of Apache.  Probably the most complete table on the net!
34
35   MIME::Types and daemons (fork)
36       If your program uses fork (usually for a daemon), then you want to have
37       the type table initialized before you start forking. So, first call
38
39          my $mt = MIME::Types->new;
40
41       Later, each time you create this object (you may, of course, also reuse
42       the object you create here) you will get access to the same global
43       table of types.
44

METHODS

46   Constructors
47       MIME::Types->new(%options)
48           Create a new "MIME::Types" object which manages the data.  In the
49           current implementation, it does not matter whether you create this
50           object often within your program, but in the future this may
51           change.
52
53            -Option         --Default
54             db_file          <installed source>
55             only_complete    <false>
56             only_iana        <false>
57             skip_extensions  <false>
58
59           db_file => FILENAME
60             The location of the database which contains the type information.
61             Only the first instantiation of this object will have this
62             parameter obeyed.
63
64             [2.10] This parameter can be globally overruled via the
65             "PERL_MIME_TYPE_DB" environment variable, which may be needed in
66             case of PAR or other tricky installations.  For PAR, you probably
67             set this environment variable to "inc/lib/MIME/types.db"
68
69           only_complete => BOOLEAN
70             Only include complete MIME type definitions: requires at least
71             one known extension.  This will reduce the number of entries
72             --and with that the amount of memory consumed-- considerably.
73
74             In your program you have to decide: the first time that you call
75             the creator ("new") determines whether you get the full or the
76             partial information.
77
78           only_iana => BOOLEAN
79             Only load the types which are currently known by IANA.
80
81           skip_extensions => BOOLEAN
82             Do not load the table to map extensions to types, which is quite
83             large.
84
85   Knowledge
86       $obj->addType($type, ...)
87           Add one or more TYPEs to the set of known types.  Each TYPE is a
88           "MIME::Type" which must be experimental: either the main-type or
89           the sub-type must start with "x-".
90
91           Please inform the maintainer of this module when registered types
92           are missing.  Before version MIME::Types version 1.14, a warning
93           was produced when an unknown IANA type was added.  This has been
94           removed, because some people need that to get their application to
95           work locally... broken applications...
96
97       $obj->extensions()
98           Returns a list of all defined extensions.
99
100       $obj->listTypes()
101           Returns a list of all defined mime-types by name only.  This will
102           not instantiate MIME::Type objects.  See types()
103
104       $obj->mimeTypeOf($filename)
105           Returns the "MIME::Type" object which belongs to the FILENAME (or
106           simply its filename extension) or "undef" if the file type is
107           unknown.  The extension is used and considered case-insensitive.
108
109           In some cases, more than one type is known for a certain filename
110           extension.  In that case, the preferred one is taken (for an
111           unclear definition of preference)
112
113           example: use of mimeTypeOf()
114
115            my $types = MIME::Types->new;
116            my $mime = $types->mimeTypeOf('gif');
117
118            my $mime = $types->mimeTypeOf('picture.jpg');
119            print $mime->isBinary;
120
121       $obj->type($string)
122           Returns the "MIME::Type" which describes the type related to
123           STRING.  [2.00] Only one type will be returned.
124
125           [before 2.00] One type may be described more than once.  Different
126           extensions may be in use for this type, and different operating
127           systems may cause more than one "MIME::Type" object to be defined.
128           In scalar context, only the first is returned.
129
130       $obj->types()
131           Returns a list of all defined mime-types.  For reasons of backwards
132           compatibility, this will instantiate MIME::Type objects, which will
133           be returned.  See listTypes().
134
135   HTTP support
136       $obj->httpAccept($header)
137           [2.07] Decompose a typical HTTP-Accept header, and sort it based on
138           the included priority information.  Returned is a sorted list of
139           type names, where the highest priority type is first.  The list may
140           contain '*/*' (accept any) or a '*' as subtype.
141
142           Ill-formated typenames are ignored.  On equal qualities, the order
143           is kept.  See RFC2616 section 14.1
144
145           example:
146
147             my @types = $types->httpAccept('text/html, application/json;q=0.9');
148
149       $obj->httpAcceptBest($accept|\@types, @have)
150           [2.07] The $accept string is processed via httpAccept() to order
151           the types on preference.  You may also provide a list of ordered
152           @types which may have been the result of that method, called
153           earlier.
154
155           As second parameter, you pass a LIST of types you @have to offer.
156           Those need to be MIME::Type objects. The preferred type will get
157           selected.  When none of these are accepted by the client, this will
158           return "undef".  It should result in a 406 server response.
159
160           example:
161
162              my $accept = $req->header('Accept');
163              my @have   = map $mt->type($_), qw[text/plain text/html];
164              my @ext    = $mt->httpAcceptBest($accept, @have);
165
166       $obj->httpAcceptSelect($accept|\@types, @filenames|\@filenames)
167           [2.07] Like httpAcceptBest(), but now we do not return a pair with
168           mime-type and filename, not just the type.  If $accept is "undef",
169           the first filename is returned.
170
171           example:
172
173              use HTTP::Status ':constants';
174              use File::Glob   'bsd_glob';    # understands blanks in filename
175
176              my @filenames   = bsd_glob "$imagedir/$fnbase.*;
177              my $accept      = $req->header('Accept');
178              my ($fn, $mime) = $mt->httpAcceptSelect($accept, @filenames);
179              my $code        = defined $mime ? HTTP_NOT_ACCEPTABLE : HTTP_OK;
180

FUNCTIONS

182       The next functions are provided for backward compatibility with
183       MIME::Types versions [0.06] and below.  This code originates from Jeff
184       Okamoto okamoto@corp.hp.com and others.
185
186       by_mediatype(TYPE)
187           This function takes a media type and returns a list or anonymous
188           array of anonymous three-element arrays whose values are the file
189           name suffix used to identify it, the media type, and a content
190           encoding.
191
192           TYPE can be a full type name (contains '/', and will be matched in
193           full), a partial type (which is used as regular expression) or a
194           real regular expression.
195
196       by_suffix(FILENAME|SUFFIX)
197           Like "mimeTypeOf", but does not return an "MIME::Type" object. If
198           the file +type is unknown, both the returned media type and
199           encoding are empty strings.
200
201           example: use of function by_suffix()
202
203            use MIME::Types 'by_suffix';
204            my ($mediatype, $encoding) = by_suffix('image.gif');
205
206            my $refdata = by_suffix('image.gif');
207            my ($mediatype, $encoding) = @$refdata;
208
209       import_mime_types()
210           This method has been removed: mime-types are only useful if
211           understood by many parties.  Therefore, the IANA assigns names
212           which can be used.  In the table kept by this "MIME::Types" module
213           all these names, plus the most often used temporary names are kept.
214           When names seem to be missing, please contact the maintainer for
215           inclusion.
216

SEE ALSO

218       This module is part of MIME-Types distribution version 2.17, built on
219       January 26, 2018. Website: http://perl.overmeer.net/CPAN/
220

LICENSE

222       Copyrights 1999-2018 by [Mark Overmeer <markov@cpan.org>]. For other
223       contributors see ChangeLog.
224
225       This program is free software; you can redistribute it and/or modify it
226       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
227
228
229
230perl v5.30.1                      2020-01-30                    MIME::Types(3)
Impressum