=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->isText)         # 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<""> 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

=item overload: B<==> numerical comparison

Compare whether the L<type()|MIME::Type/"Attributes"> of the objects is the same.

=item overload: B<cmp> string comparison

When a L<MIME::Type|MIME::Type> object is compared to either a string or another
L<MIME::Type|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.

=back

=head1 METHODS

=head2 Initiation

=over 4

=item $class-E<gt>B<new>(%options)

Create (I<instantiate>) a new L<MIME::Type|MIME::Type> object which manages one
mime type.

 -Option    --Default
  charset     undef
  encoding    <depends on type>
  extensions  []
  simplified  <derived from type>
  system      undef
  type        <required>

=over 2

=item charset => $charset

Specify the default charset for this type.

=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<charset>()

[2.28] RFC6657 prescribes that IANA registrations for text category
types explicitly state their default character-set.  MIME-Types contains
a manually produced list of these defaults.

This method may also return C<_REQUIRED>, when there is no default, or
C<_FRAMED> when the charset is determined by the content.

=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 $any-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<defaultCharset>()

[2.29] As per RFC6657, all C<text/*> types must either specify a default
charset in its IANA registration, or require the charset parameter.  Non-text
types may require a charset as well.

It is hard to extract this information from the IANA registration files
automagically, so is manually maintained.

example: default charset use

   $charset //= $type->defaultCharset // 'utf-8';

=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 C<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 C<false>.

=item $obj-E<gt>B<isSignature>()

Returns C<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.
Cast by new()

=back

=head1 SEE ALSO

This module is part of MIME-Types version 2.29,
built on September 15, 2025. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 1999-2025 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

