=encoding utf8
=head1 NAME
MIME::Type - description of one MIME type
=head1 SYNOPSIS
use MIME::Types;
my $mimetypes = MIME::Types->new;
my MIME::Type $plaintext = $mimetypes->type('text/plain');
print $plaintext->mediaType; # text
print $plaintext->subType; # plain
my @ext = $plaintext->extensions;
print "@ext" # txt asc c cc h hh cpp
print $plaintext->encoding # 8bit
if($plaintext->isBinary) # false
if($plaintext->isAscii) # true
if($plaintext->equals('text/plain') {...}
if($plaintext eq 'text/plain') # same
print MIME::Type->simplified('x-appl/x-zip') # 'appl/zip'
=head1 DESCRIPTION
MIME types are used in MIME entities, for instance as part of e-mail
and HTTP traffic. Sometimes real knowledge about a mime-type is need.
Objects of C<MIME::Type> store the information on one such type.
=head1 OVERLOADED
=over 4
=item overload: B<string comparison>
When a MIME::Type object is compared to either a string or another
MIME::TYpe, the L<equals()|MIME::Type/"Knowledge"> method is called. Comparison is smart,
which means that it extends common string comparison with some
features which are defined in the related RFCs.
=item overload: B<stringification>
The stringification (use of the object in a place where a string
is required) will result in the type name, the same as L<type()|MIME::Type/"Attributes">
returns.
example: use of stringification
my $mime = MIME::Type->new('text/html');
print "$mime\n"; # explicit stringification
print $mime; # implicit stringification
=back
=head1 METHODS
=head2 Initiation
=over 4
=item MIME::Type-E<gt>B<new>(%options)
Create (I<instantiate>) a new MIME::Type object which manages one
mime type.
-Option --Default
encoding <depends on type>
extensions []
simplified <derived from type>
system undef
type <required>
=over 2
=item encoding => '7bit'|'8bit'|'base64'|'quoted-printable'
How must this data be encoded to be transported safely. The default
depends on the type: mimes with as main type C<text/> will default
to C<quoted-printable> and all other to C<base64>.
=item extensions => REF-ARRAY
An array of extensions which are using this mime.
=item simplified => STRING
The mime types main- and sub-label can both start with C<x->, to indicate
that is a non-registered name. Of course, after registration this flag
can disappear which adds to the confusion. The simplified string has the
C<x-> thingies removed and are translated to lower-case.
=item system => REGEX
Regular expression which defines for which systems this rule is valid. The
REGEX is matched on C<$^O>.
=item type => STRING
The type which is defined here. It consists of a I<type> and a I<sub-type>,
both case-insensitive. This module will return lower-case, but accept
upper-case.
=back
=back
=head2 Attributes
=over 4
=item $obj-E<gt>B<encoding>()
Returns the type of encoding which is required to transport data of this
type safely.
=item $obj-E<gt>B<extensions>()
Returns a list of extensions which are known to be used for this
mime type.
=item $obj-E<gt>B<simplified>( [$string] )
=item MIME::Type-E<gt>B<simplified>( [$string] )
Returns the simplified mime type for this object or the specified STRING.
Mime type names can get officially registered. Until then, they have to
carry an C<x-> preamble to indicate that. Of course, after recognition,
the C<x-> can disappear. In many cases, we prefer the simplified version
of the type.
example: results of simplified()
my $mime = MIME::Type->new(type => 'x-appl/x-zip');
print $mime->simplified; # 'appl/zip'
print $mime->simplified('text/PLAIN'); # 'text/plain'
print MIME::Type->simplified('x-xyz/x-abc'); # 'xyz/abc'
=item $obj-E<gt>B<system>()
Returns the regular expression which can be used to determine whether this
type is active on the system where you are working on.
=item $obj-E<gt>B<type>()
Returns the long type of this object, for instance C<'text/plain'>
=back
=head2 Knowledge
=over 4
=item $obj-E<gt>B<equals>($string|$mime)
Compare this mime-type object with a STRING or other object. In case of
a STRING, simplification will take place.
=item $obj-E<gt>B<isAscii>()
Old name for L<isText()|MIME::Type/"Knowledge">.
=item $obj-E<gt>B<isBinary>()
Returns true when the type is not known to be text. See L<isText()|MIME::Type/"Knowledge">.
=item $obj-E<gt>B<isExperimental>()
[2.00] Return C<true> when the type is defined for experimental
use; the subtype starts with C<x.>
=item $obj-E<gt>B<isPersonal>()
[2.00] Return C<true> when the type is defined by a person for
private use; the subtype starts with C<prs.>
=item $obj-E<gt>B<isRegistered>()
Mime-types which are not registered by IANA nor defined in RFCs shall
start with an C<x->. This counts for as well the media-type as the
sub-type. In case either one of the types starts with C<x-> this
method will return false.
=item $obj-E<gt>B<isSignature>()
Returns true when the type is in the list of known signatures.
=item $obj-E<gt>B<isText>()
[2.05] All types which may have the charset attribute, are text. However,
there is currently no record of attributes in this module... so we guess.
=item $obj-E<gt>B<isVendor>()
[2.00] Return C<true> when the type is defined by a vendor; the subtype
starts with C<vnd.>
=item $obj-E<gt>B<mediaType>()
The media type of the simplified mime.
For C<'text/plain'> it will return C<'text'>.
For historical reasons, the C<'mainType'> method still can be used
to retrieve the same value. However, that method is deprecated.
=item $obj-E<gt>B<subType>()
The sub type of the simplified mime.
For C<'text/plain'> it will return C<'plain'>.
=back
=head1 DIAGNOSTICS
=over 4
=item Error: Type parameter is obligatory.
When a L<MIME::Type|MIME::Type> object is created, the type itself must be
specified with the C<type> option flag.
=back
=head1 SEE ALSO
This module is part of MIME-Types distribution version 2.17,
built on January 26, 2018. Website: F<http://perl.overmeer.net/CPAN/>
=head1 LICENSE
Copyrights 1999-2018 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://dev.perl.org/licenses/>