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

   1 =head1 NAME
   2
   3 MIME::Type - Definition of one MIME type
   4
   5 =head1 SYNOPSIS
   6
   7  use MIME::Types;
   8  my $mimetypes = MIME::Types->new;
   9  my MIME::Type $plaintext = $mimetypes->type('text/plain');
  10  print $plaintext->mediaType;   # text
  11  print $plaintext->subType;     # plain
  12
  13  my @ext = $plaintext->extensions;
  14  print "@ext"                   # txt asc c cc h hh cpp
  15
  16  print $plaintext->encoding     # 8bit
  17  if($plaintext->isBinary)       # false
  18  if($plaintext->isAscii)        # true
  19  if($plaintext->equals('text/plain') {...}
  20  if($plaintext eq 'text/plain') # same
  21
  22  print MIME::Type->simplified('x-appl/x-zip') #  'appl/zip'
  23
  24 =head1 DESCRIPTION
  25
  26 MIME types are used in MIME entities, for instance as part of e-mail
  27 and HTTP traffic.  Sometimes real knowledge about a mime-type is need.
  28 Objects of C<MIME::Type> store the information on one such type.
  29
  30 This module is built to conform to the MIME types of RFC's 2045 and 2231.
  31 It follows the official IANA registry at
  32 F<http://www.iana.org/assignments/media-types/>
  33 and the collection kept at F<http://www.ltsw.se/knbase/internet/mime.htp>
  34
  35 =head1 OVERLOADED
  36
  37 overload: B<string comparison>
  38
  39 =over 4
  40
  41 When a MIME::Type object is compared to either a string or an other
  42 MIME::TYpe, the L<equals()|MIME::Type/"Knowledge"> method is called.  Comparison is smart,
  43 which means that it extends common string comparison with some
  44 features which are defined in the related RFCs.
  45
  46 =back
  47
  48 overload: B<stringification>
  49
  50 =over 4
  51
  52 The stringification (use of the object in a place where a string
  53 is required) will result in the type name, the same as L<type()|MIME::Type/"Attributes">
  54 returns.
  55
  56 example: use of stringification
  57
  58  my $mime = MIME::Type->new('text/html');
  59  print "$mime\n";   # explicit stringification
  60  print $mime;       # implicit stringification
  61
  62 =back
  63
  64 =head1 METHODS
  65
  66 =head2 Initiation
  67
  68 MIME::Type-E<gt>B<new>(OPTIONS)
  69
  70 =over 4
  71
  72 Create (I<instantiate>) a new MIME::Type object which manages one
  73 mime type.
  74
  75  Option    --Default
  76  encoding    <depends on type>
  77  extensions  []
  78  simplified  <derived from type>
  79  system      undef
  80  type        <required>
  81
  82 . encoding => '7bit'|'8bit'|'base64'|'quoted-printable'
  83
  84 =over 4
  85
  86 How must this data be encoded to be transported safely.  The default
  87 depends on the type: mimes with as main type C<text/> will default
  88 to C<quoted-printable> and all other to C<base64>.
  89
  90 =back
  91
  92 . extensions => REF-ARRAY
  93
  94 =over 4
  95
  96 An array of extensions which are using this mime.
  97
  98 =back
  99
 100 . simplified => STRING
 101
 102 =over 4
 103
 104 The mime types main- and sub-label can both start with C<x->, to indicate
 105 that is a non-registered name.  Of course, after registration this flag
 106 can disappear which adds to the confusion.  The simplified string has the
 107 C<x-> thingies removed and are translated to lower-case.
 108
 109 =back
 110
 111 . system => REGEX
 112
 113 =over 4
 114
 115 Regular expression which defines for which systems this rule is valid.  The
 116 REGEX is matched on C<$^O>.
 117
 118 =back
 119
 120 . type => STRING
 121
 122 =over 4
 123
 124 The type which is defined here.  It consists of a I<type> and a I<sub-type>,
 125 both case-insensitive.  This module will return lower-case, but accept
 126 upper-case.
 127
 128 =back
 129
 130 =back
 131
 132 =head2 Attributes
 133
 134 $obj-E<gt>B<encoding>
 135
 136 =over 4
 137
 138 Returns the type of encoding which is required to transport data of this
 139 type safely.
 140
 141 =back
 142
 143 $obj-E<gt>B<extensions>
 144
 145 =over 4
 146
 147 Returns a list of extensions which are known to be used for this
 148 mime type.
 149
 150 =back
 151
 152 $obj-E<gt>B<simplified>([STRING])
 153
 154 MIME::Type-E<gt>B<simplified>([STRING])
 155
 156 =over 4
 157
 158 Returns the simplified mime type for this object or the specified STRING.
 159 Mime type names can get officially registered.  Until then, they have to
 160 carry an C<x-> preamble to indicate that.  Of course, after recognition,
 161 the C<x-> can disappear.  In many cases, we prefer the simplified version
 162 of the type.
 163
 164 example: results of simplified()
 165
 166  my $mime = MIME::Type->new(type => 'x-appl/x-zip');
 167  print $mime->simplified;                     # 'appl/zip'
 168  print $mime->simplified('text/plain');       # 'text/plain'
 169  print MIME::Type->simplified('x-xyz/x-abc'); # 'xyz/abc'
 170
 171 =back
 172
 173 $obj-E<gt>B<system>
 174
 175 =over 4
 176
 177 Returns the regular expression which can be used to determine whether this
 178 type is active on the system where you are working on.
 179
 180 =back
 181
 182 $obj-E<gt>B<type>
 183
 184 =over 4
 185
 186 Returns the long type of this object, for instance C<'text/plain'>
 187
 188 =back
 189
 190 =head2 Knowledge
 191
 192 $obj-E<gt>B<equals>(STRING|MIME)
 193
 194 =over 4
 195
 196 Compare this mime-type object with a STRING or other object.  In case of
 197 a STRING, simplification will take place.
 198
 199 =back
 200
 201 $obj-E<gt>B<isAscii>
 202
 203 =over 4
 204
 205 Returns false when the encoding is base64, and true otherwise.  All encodings
 206 except base64 are text encodings.
 207
 208 =back
 209
 210 $obj-E<gt>B<isBinary>
 211
 212 =over 4
 213
 214 Returns true when the encoding is base64.
 215
 216 =back
 217
 218 $obj-E<gt>B<isRegistered>
 219
 220 =over 4
 221
 222 Mime-types which are not registered by IANA nor defined in RFCs shall
 223 start with an C<x->.  This counts for as well the media-type as the
 224 sub-type.  In case either one of the types starts with C<x-> this
 225 method will return false.
 226
 227 =back
 228
 229 $obj-E<gt>B<isSignature>
 230
 231 =over 4
 232
 233 Returns true when the type is in the list of known signatures.
 234
 235 =back
 236
 237 $obj-E<gt>B<mediaType>
 238
 239 =over 4
 240
 241 The media type of the simplified mime.
 242 For C<'text/plain'> it will return C<'text'>.
 243
 244 For historical reasons, the C<'mainType'> method still can be used
 245 to retreive the same value.  However, that method is deprecated.
 246
 247 =back
 248
 249 $obj-E<gt>B<subType>
 250
 251 =over 4
 252
 253 The sub type of the simplified mime.
 254 For C<'text/plain'> it will return C<'plain'>.
 255
 256 =back
 257
 258 =head1 DIAGNOSTICS
 259
 260 Error: Type parameter is obligatory.
 261
 262 =over 4
 263
 264 When a L<MIME::Type|MIME::Type> object is created, the type itself must be
 265 specified with the C<type> option flag.
 266
 267 =back
 268
 269 =head1 SEE ALSO
 270
 271 This module is part of MIME-Types distribution version 1.28,
 272 built on September 07, 2009. Website: F<http://perl.overmeer.net/mimetypes/>
 273
 274 =head1 LICENSE
 275
 276 Copyrights 1999,2001-2009 by Mark Overmeer. For other contributors see ChangeLog.
 277
 278 This program is free software; you can redistribute it and/or modify it
 279 under the same terms as Perl itself.
 280 See F<http://www.perl.com/perl/misc/Artistic.html>
 281