.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Padre::MIME 3pm"
.TH Padre::MIME 3pm "2014-09-11" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Padre::MIME \- Padre MIME Registry and Type Detection
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBPadre::MIME\fR is a light weight module for detecting the \s-1MIME\s0 type of files
and the type registry acts as the basis for all other type-specific
functionality in Padre.
.PP
Because of the light weight it can be quickly and safely loaded in any
background tasks that need to walk directories and act on files based on
their file type.
.PP
The class itself consists of two main elements, a type registry and a type
detection mechanism.
.SH "METHODS"
.IX Header "METHODS"
.SS "exts"
.IX Subsection "exts"
.Vb 1
\&  my @extensions = Padre::MIME\->exts;
.Ve
.PP
The \f(CW\*(C`exts\*(C'\fR method returns the list of all known file extensions.
.SS "types"
.IX Subsection "types"
.Vb 1
\&  my @registered = Padre::MIME\->types;
.Ve
.PP
The \f(CW\*(C`types\*(C'\fR method returns the list of all registered \s-1MIME\s0 types.
.SS "find"
.IX Subsection "find"
.Vb 1
\&  my $mime = Padre::MIME\->find(\*(Aqtext/plain\*(Aq);
.Ve
.PP
The \f(CW\*(C`find\*(C'\fR method takes a \s-1MIME\s0 type string and returns a Padre::MIME
object for that string. If the \s-1MIME\s0 type is not registered, then the
unknown type object will be returned.
.SS "new"
.IX Subsection "new"
.Vb 5
\&  my $mime = Padre::MIME\->new(
\&      type      => \*(Aqtext/x\-csrc\*(Aq,
\&      name      => _T(\*(AqC\*(Aq),
\&      supertype => \*(Aqtext/plain\*(Aq,
\&  );
.Ve
.PP
The \f(CW\*(C`new\*(C'\fR constructor creates a new anonymous \s-1MIME\s0 type object which
is not registered with the \s-1MIME\s0 type system.
.PP
It takes three parameters, \f(CW\*(C`type\*(C'\fR which should be the string identifying
the \s-1MIME\s0 type, \f(CW\*(C`name\*(C'\fR which should be the (localisable) English name for
the language, and \f(CW\*(C`supertype\*(C'\fR which should be the parent type that the
new type inherits from.
.PP
While not compulsory, all \s-1MIME\s0 types generally inherit from other languages
with three main types at the top of the inheritance tree.
.IP "\(bu" 4
\&\f(CW\*(C`text/plain\*(C'\fR for human-readable text files including pretty-printed \s-1XML\s0
.IP "\(bu" 4
\&\f(CW\*(C`application/xml\*(C'\fR for tightly packed \s-1XML\s0 files not intended to opened
.IP "\(bu" 4
\&\f(CW\*(C`application/octet\-stream\*(C'\fR for binary files (that cannot be opened)
.PP
At the time of creation, new \s-1MIME\s0 type objects (even anonymous ones) must
inherit from a registered \s-1MIME\s0 type if the \f(CW\*(C`supertype\*(C'\fR param is provided.
.PP
Returns a Padre::MIME object, or throws an exception on error.
.SS "create"
.IX Subsection "create"
.Vb 5
\& Padre::MIME\->create(
\&      type      => \*(Aqapplication/x\-shellscript\*(Aq,
\&      name      => _T(\*(AqShell Script\*(Aq),
\&      supertype => \*(Aqtext/plain\*(Aq,
\&  );
.Ve
.PP
The \f(CW\*(C`create\*(C'\fR method creates and registers a new \s-1MIME\s0 type for use in
Padre. It will not in and of itself add support for that file type,
but registration of the \s-1MIME\s0 type is the first step, and a prerequisite of,
supporting that file type anywhere else in Padre.
.PP
Returns the new Padre::MIME object as a convenience, or throws an
exception on error.
.SS "type"
.IX Subsection "type"
.Vb 1
\&  print Padre::MIME\->find(\*(Aqtext/plain\*(Aq)\->type;
.Ve
.PP
The \f(CW\*(C`type\*(C'\fR accessor returns the type string for the \s-1MIME\s0 type, for example
the above would print \f(CW\*(C`text/plain\*(C'\fR.
.SS "name"
.IX Subsection "name"
.Vb 1
\&  print Padre::MIME\->find(\*(Aqtext/plain\*(Aq)\->name;
.Ve
.PP
The \f(CW\*(C`name\*(C'\fR accessor returns the (localisable) English name of the \s-1MIME\s0
type. For example, the above would print \f(CW"Text"\fR.
.SS "super"
.IX Subsection "super"
.Vb 3
\&  # Find the root type for a mime type
\&  my $mime = Padre::MIME\->find(\*(Aqtext/x\-actionscript\*(Aq);
\&  $mime = $mime\->super while $mime\->super;
.Ve
.PP
The \f(CW\*(C`super\*(C'\fR method returns the Padre::MIME object for the immediate
supertype of a particular \s-1MIME\s0 type, or false if there is no supertype.
.SS "supertype"
.IX Subsection "supertype"
.Vb 3
\&  # Find the root type for a mime type
\&  my $mime = Padre::MIME\->find(\*(Aqtext/x\-actionscript\*(Aq);
\&  $mime = $mime\->super while defined $mime\->supertype;
.Ve
.PP
The \f(CW\*(C`supertype\*(C'\fR method returns the string form of the immediate supertype
for a particular \s-1MIME\s0 type, or \f(CW\*(C`undef\*(C'\fR if there is no supertype.
.SS "superpath"
.IX Subsection "superpath"
.Vb 6
\&  # Find the comment format for a type
\&  my $mime    = Padre::MIME\->find(\*(Aqtext/x\-actionscript\*(Aq);
\&  my $comment = undef;
\&  foreach my $type ( $mime\->superpath ) {
\&      $comment = Padre::Comment\->find($type) and last;
\&  }
.Ve
.PP
The \f(CW\*(C`superpath\*(C'\fR method returns a list of \s-1MIME\s0 type strings of the entire
inheritance path for a particular \s-1MIME\s0 type, including itself.
.PP
This can allow inherited types to gain default access to various resources
such as the comment type or syntax highlighting of the supertypes without
needing to be implemented separately, if they are no different from their
supertype in some respect.
.SS "document"
.IX Subsection "document"
.Vb 1
\&  my $module = Padre::MIME\->find(\*(Aqtext/x\-perl\*(Aq)\->document;
.Ve
.PP
The \f(CW\*(C`document\*(C'\fR method attempts to resolve an implementation class for this
\&\s-1MIME\s0 type, either from the Padre core or from a plugin. For example, the
above would return \f(CW\*(AqPadre::Document::Perl\*(Aq\fR.
.PP
Returns the class name as a string, or \f(CW\*(C`undef\*(C'\fR if no implementation class
can be resolved.
.SS "binary"
.IX Subsection "binary"
.Vb 3
\&  if ( Padre::MIME\->find(\*(Aqapplication/octet\-stream\*(Aq)\->binary ) {
\&      die "Padre does not support binary files";
\&  }
.Ve
.PP
The \f(CW\*(C`binary\*(C'\fR method is a convenience for determining if a \s-1MIME\s0 type is a
type of non-text file that Padre does not support opening.
.PP
Returns true if the \s-1MIME\s0 type is binary or false if not.
.SS "plugin"
.IX Subsection "plugin"
.Vb 3
\&  # Overload the default Python support
\&  my $python = Padre::MIME\->find(\*(Aqtext/x\-python\*(Aq);
\&  $python\->plugin(\*(AqPadre::Plugin::Python::Document\*(Aq);
.Ve
.PP
The \f(CW\*(C`plugin\*(C'\fR method is used to overload support for a \s-1MIME\s0 type and cause
it to be loaded by an arbitrary class. This method should generally not be
used directly, it is intended for internal use by Padre::PluginManager
and does not do any form of testing or management of the classes passed in.
.SS "reset"
.IX Subsection "reset"
.Vb 2
\&  # Remove the overloaded Python support
\&  Padre::MIME\->find(\*(Aqtext/x\-python\*(Aq)\->reset;
.Ve
.PP
The \f(CW\*(C`reset\*(C'\fR method is used to remove the overloading of a \s-1MIME\s0 type by a
plugin and return to default support. This method should generally not be
used directly, it is intended for internal use by Padre::PluginManager
and does not do any form of testing or management.
.SS "comment"
.IX Subsection "comment"
.Vb 1
\&  my $comment = Padre::MIME\->find(\*(Aqtext/x\-perl\*(Aq)\->comment;
.Ve
.PP
The \f(CW\*(C`comment\*(C'\fR method fetches the comment rules for the mime type from
the Padre::Comment subsystem of Padre.
.PP
Returns the basic comment as a string, or \f(CW\*(C`undef\*(C'\fR if no comment rule is
known for the \s-1MIME\s0 type.
.SS "detect"
.IX Subsection "detect"
.Vb 5
\&  my $type = Padre::MIME\->detect(
\&      file => \*(Aqpath/file.pm\*(Aq,
\&      text => "#!/usr/bin/perl\en\en",
\&      svn  => 1,
\&  );
.Ve
.PP
The \f(CW\*(C`detect\*(C'\fR method implements \s-1MIME\s0 detection using a variety of different
methods. It takes up to three different params, which it will use in the
order it considers most efficient and reliable.
.PP
The optional parameter \f(CW\*(C`file\*(C'\fR param can either be a Padre::File object,
or the path of the file in string form.
.PP
The optional string parameter \f(CW\*(C`text\*(C'\fR should be all or part of the content
of the file as a plain string.
.PP
The optional boolean parameter \f(CW\*(C`svn\*(C'\fR indicates whether or not the detection
code should look for a \f(CW\*(C`svn:mime\-type\*(C'\fR property in the \f(CW\*(C`.svn\*(C'\fR metadata
directory for the file.
.PP
Returns a \s-1MIME\s0 type string for a registered \s-1MIME\s0 type if a reasonable guess
can be made, or the null string \f(CW\*(Aq\*(Aq\fR if the detection code cannot determine
the \s-1MIME\s0 type of the file/content.
.SS "detect_svn"
.IX Subsection "detect_svn"
.Vb 1
\&  my $type = Padre::MIME\->detect_svn($path);
.Ve
.PP
The \f(CW\*(C`detect_svn\*(C'\fR method takes the path to a file as a string, and attempts
to determine a \s-1MIME\s0 type for the file based on the file's Subversion
\&\f(CW\*(C`svn:eol\-style\*(C'\fR property.
.PP
Returns a \s-1MIME\s0 type string which may or may not be registered with Padre
or the null string \f(CW\*(Aq\*(Aq\fR if the property does not exist (or it is not stored
in Subversion).
.SS "detect_content"
.IX Subsection "detect_content"
The \f(CW\*(C`detect_content\*(C'\fR method takes a string parameter containing the content
of a file (or head-anchored partial content of a file) and attempts to
heuristically determine the the type of the file based only on the content.
.PP
Returns a \s-1MIME\s0 type string for a registered \s-1MIME\s0 type if a reasonable guess
can be made, or the null string \f(CW\*(Aq\*(Aq\fR if the detection code cannot determine
the file type of the content.
.SS "detect_perl6"
.IX Subsection "detect_perl6"
.Vb 1
\&  my $is_perl6 = Padre::MIME\->detect_perl6($content);
.Ve
.PP
The \f(CW\*(C`detect_perl6\*(C'\fR is a special case method used to distinguish between
Perl 5 and Perl 6, as the two types often share the same file extension.
.PP
Returns true if the content appears to be Perl 6, or false if the content
appears to be Perl 5.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2008\-2013 The Padre development team as listed in Padre.pm.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl 5 itself.