local-lib5/man/man3/MIME::Type.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "MIME::Type 3"
 132 .TH MIME::Type 3 "2009-09-06" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 MIME::Type \- Definition of one MIME type
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 5
 138 \& use MIME::Types;
 139 \& my $mimetypes = MIME::Types\->new;
 140 \& my MIME::Type $plaintext = $mimetypes\->type('text/plain');
 141 \& print $plaintext\->mediaType;   # text
 142 \& print $plaintext\->subType;     # plain
 143 .Ve
 144 .PP
 145 .Vb 2
 146 \& my @ext = $plaintext\->extensions;
 147 \& print "@ext"                   # txt asc c cc h hh cpp
 148 .Ve
 149 .PP
 150 .Vb 5
 151 \& print $plaintext\->encoding     # 8bit
 152 \& if($plaintext\->isBinary)       # false
 153 \& if($plaintext\->isAscii)        # true
 154 \& if($plaintext\->equals('text/plain') {...}
 155 \& if($plaintext eq 'text/plain') # same
 156 .Ve
 157 .PP
 158 .Vb 1
 159 \& print MIME::Type\->simplified('x\-appl/x\-zip') #  'appl/zip'
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 \&\s-1MIME\s0 types are used in \s-1MIME\s0 entities, for instance as part of e\-mail
 164 and \s-1HTTP\s0 traffic.  Sometimes real knowledge about a mime-type is need.
 165 Objects of \f(CW\*(C`MIME::Type\*(C'\fR store the information on one such type.
 166 .PP
 167 This module is built to conform to the \s-1MIME\s0 types of \s-1RFC\s0's 2045 and 2231.
 168 It follows the official \s-1IANA\s0 registry at
 169 \&\fIhttp://www.iana.org/assignments/media\-types/\fR
 170 and the collection kept at \fIhttp://www.ltsw.se/knbase/internet/mime.htp\fR
 171 .SH "OVERLOADED"
 172 .IX Header "OVERLOADED"
 173 overload: \fBstring comparison\fR
 174 .Sp
 175 .RS 4
 176 When a MIME::Type object is compared to either a string or an other
 177 MIME::TYpe, the \fIequals()\fR method is called.  Comparison is smart,
 178 which means that it extends common string comparison with some
 179 features which are defined in the related RFCs.
 180 .RE
 181 .PP
 182 overload: \fBstringification\fR
 183 .Sp
 184 .RS 4
 185 The stringification (use of the object in a place where a string
 186 is required) will result in the type name, the same as \fItype()\fR
 187 returns.
 188 .Sp
 189 example: use of stringification
 190 .Sp
 191 .Vb 3
 192 \& my $mime = MIME::Type\->new('text/html');
 193 \& print "$mime\en";   # explicit stringification
 194 \& print $mime;       # implicit stringification
 195 .Ve
 196 .RE
 197 .SH "METHODS"
 198 .IX Header "METHODS"
 199 .Sh "Initiation"
 200 .IX Subsection "Initiation"
 201 MIME::Type\->\fBnew\fR(\s-1OPTIONS\s0)
 202 .Sp
 203 .RS 4
 204 Create (\fIinstantiate\fR) a new MIME::Type object which manages one
 205 mime type.
 206 .Sp
 207 .Vb 6
 208 \& Option    \-\-Default
 209 \& encoding    <depends on type>
 210 \& extensions  []
 211 \& simplified  <derived from type>
 212 \& system      undef
 213 \& type        <required>
 214 .Ve
 215 .Sp
 216 \&. encoding => '7bit'|'8bit'|'base64'|'quoted\-printable'
 217 .Sp
 218 .RS 4
 219 How must this data be encoded to be transported safely.  The default
 220 depends on the type: mimes with as main type \f(CW\*(C`text/\*(C'\fR will default
 221 to \f(CW\*(C`quoted\-printable\*(C'\fR and all other to \f(CW\*(C`base64\*(C'\fR.
 222 .RE
 223 .RE
 224 .RS 4
 225 .Sp
 226 \&. extensions => REF-ARRAY
 227 .Sp
 228 .RS 4
 229 An array of extensions which are using this mime.
 230 .RE
 231 .RE
 232 .RS 4
 233 .Sp
 234 \&. simplified => \s-1STRING\s0
 235 .Sp
 236 .RS 4
 237 The mime types main\- and sub-label can both start with \f(CW\*(C`x\-\*(C'\fR, to indicate
 238 that is a non-registered name.  Of course, after registration this flag
 239 can disappear which adds to the confusion.  The simplified string has the
 240 \&\f(CW\*(C`x\-\*(C'\fR thingies removed and are translated to lower\-case.
 241 .RE
 242 .RE
 243 .RS 4
 244 .Sp
 245 \&. system => \s-1REGEX\s0
 246 .Sp
 247 .RS 4
 248 Regular expression which defines for which systems this rule is valid.  The
 249 \&\s-1REGEX\s0 is matched on \f(CW$^O\fR.
 250 .RE
 251 .RE
 252 .RS 4
 253 .Sp
 254 \&. type => \s-1STRING\s0
 255 .Sp
 256 .RS 4
 257 The type which is defined here.  It consists of a \fItype\fR and a \fIsub-type\fR,
 258 both case\-insensitive.  This module will return lower\-case, but accept
 259 upper\-case.
 260 .RE
 261 .RE
 262 .RS 4
 263 .RE
 264 .Sh "Attributes"
 265 .IX Subsection "Attributes"
 266 $obj\->\fBencoding\fR
 267 .Sp
 268 .RS 4
 269 Returns the type of encoding which is required to transport data of this
 270 type safely.
 271 .RE
 272 .PP
 273 $obj\->\fBextensions\fR
 274 .Sp
 275 .RS 4
 276 Returns a list of extensions which are known to be used for this
 277 mime type.
 278 .RE
 279 .PP
 280 $obj\->\fBsimplified\fR([\s-1STRING\s0])
 281 .PP
 282 MIME::Type\->\fBsimplified\fR([\s-1STRING\s0])
 283 .Sp
 284 .RS 4
 285 Returns the simplified mime type for this object or the specified \s-1STRING\s0.
 286 Mime type names can get officially registered.  Until then, they have to
 287 carry an \f(CW\*(C`x\-\*(C'\fR preamble to indicate that.  Of course, after recognition,
 288 the \f(CW\*(C`x\-\*(C'\fR can disappear.  In many cases, we prefer the simplified version
 289 of the type.
 290 .Sp
 291 example: results of \fIsimplified()\fR
 292 .Sp
 293 .Vb 4
 294 \& my $mime = MIME::Type\->new(type => 'x\-appl/x\-zip');
 295 \& print $mime\->simplified;                     # 'appl/zip'
 296 \& print $mime\->simplified('text/plain');       # 'text/plain'
 297 \& print MIME::Type\->simplified('x\-xyz/x\-abc'); # 'xyz/abc'
 298 .Ve
 299 .RE
 300 .PP
 301 $obj\->\fBsystem\fR
 302 .Sp
 303 .RS 4
 304 Returns the regular expression which can be used to determine whether this
 305 type is active on the system where you are working on.
 306 .RE
 307 .PP
 308 $obj\->\fBtype\fR
 309 .Sp
 310 .RS 4
 311 Returns the long type of this object, for instance \f(CW'text/plain'\fR
 312 .RE
 313 .Sh "Knowledge"
 314 .IX Subsection "Knowledge"
 315 $obj\->\fBequals\fR(STRING|MIME)
 316 .Sp
 317 .RS 4
 318 Compare this mime-type object with a \s-1STRING\s0 or other object.  In case of
 319 a \s-1STRING\s0, simplification will take place.
 320 .RE
 321 .PP
 322 $obj\->\fBisAscii\fR
 323 .Sp
 324 .RS 4
 325 Returns false when the encoding is base64, and true otherwise.  All encodings
 326 except base64 are text encodings.
 327 .RE
 328 .PP
 329 $obj\->\fBisBinary\fR
 330 .Sp
 331 .RS 4
 332 Returns true when the encoding is base64.
 333 .RE
 334 .PP
 335 $obj\->\fBisRegistered\fR
 336 .Sp
 337 .RS 4
 338 Mime-types which are not registered by \s-1IANA\s0 nor defined in RFCs shall
 339 start with an \f(CW\*(C`x\-\*(C'\fR.  This counts for as well the media-type as the
 340 sub\-type.  In case either one of the types starts with \f(CW\*(C`x\-\*(C'\fR this
 341 method will return false.
 342 .RE
 343 .PP
 344 $obj\->\fBisSignature\fR
 345 .Sp
 346 .RS 4
 347 Returns true when the type is in the list of known signatures.
 348 .RE
 349 .PP
 350 $obj\->\fBmediaType\fR
 351 .Sp
 352 .RS 4
 353 The media type of the simplified mime.
 354 For \f(CW'text/plain'\fR it will return \f(CW'text'\fR.
 355 .Sp
 356 For historical reasons, the \f(CW'mainType'\fR method still can be used
 357 to retreive the same value.  However, that method is deprecated.
 358 .RE
 359 .PP
 360 $obj\->\fBsubType\fR
 361 .Sp
 362 .RS 4
 363 The sub type of the simplified mime.
 364 For \f(CW'text/plain'\fR it will return \f(CW'plain'\fR.
 365 .RE
 366 .SH "DIAGNOSTICS"
 367 .IX Header "DIAGNOSTICS"
 368 Error: Type parameter is obligatory.
 369 .Sp
 370 .RS 4
 371 When a MIME::Type object is created, the type itself must be
 372 specified with the \f(CW\*(C`type\*(C'\fR option flag.
 373 .RE
 374 .SH "SEE ALSO"
 375 .IX Header "SEE ALSO"
 376 This module is part of MIME-Types distribution version 1.28,
 377 built on September 07, 2009. Website: \fIhttp://perl.overmeer.net/mimetypes/\fR
 378 .SH "LICENSE"
 379 .IX Header "LICENSE"
 380 Copyrights 1999,2001\-2009 by Mark Overmeer. For other contributors see ChangeLog.
 381 .PP
 382 This program is free software; you can redistribute it and/or modify it
 383 under the same terms as Perl itself.
 384 See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR