NAME

       Padre::MIME - Padre MIME Registry and Type Detection

DESCRIPTION

       Padre::MIME is a light weight module for detecting the MIME type of files and the type
       registry acts as the basis for all other type-specific functionality in Padre.

       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.

       The class itself consists of two main elements, a type registry and a type detection
       mechanism.

METHODS

   exts
         my @extensions = Padre::MIME->exts;

       The "exts" method returns the list of all known file extensions.

   types
         my @registered = Padre::MIME->types;

       The "types" method returns the list of all registered MIME types.

   find
         my $mime = Padre::MIME->find('text/plain');

       The "find" method takes a MIME type string and returns a Padre::MIME object for that
       string. If the MIME type is not registered, then the unknown type object will be returned.

   new
         my $mime = Padre::MIME->new(
             type      => 'text/x-csrc',
             name      => _T('C'),
             supertype => 'text/plain',
         );

       The "new" constructor creates a new anonymous MIME type object which is not registered
       with the MIME type system.

       It takes three parameters, "type" which should be the string identifying the MIME type,
       "name" which should be the (localisable) English name for the language, and "supertype"
       which should be the parent type that the new type inherits from.

       While not compulsory, all MIME types generally inherit from other languages with three
       main types at the top of the inheritance tree.

       •   "text/plain" for human-readable text files including pretty-printed XML

       •   "application/xml" for tightly packed XML files not intended to opened

       •   "application/octet-stream" for binary files (that cannot be opened)

       At the time of creation, new MIME type objects (even anonymous ones) must inherit from a
       registered MIME type if the "supertype" param is provided.

       Returns a Padre::MIME object, or throws an exception on error.

   create
        Padre::MIME->create(
             type      => 'application/x-shellscript',
             name      => _T('Shell Script'),
             supertype => 'text/plain',
         );

       The "create" method creates and registers a new MIME type for use in Padre. It will not in
       and of itself add support for that file type, but registration of the MIME type is the
       first step, and a prerequisite of, supporting that file type anywhere else in Padre.

       Returns the new Padre::MIME object as a convenience, or throws an exception on error.

   type
         print Padre::MIME->find('text/plain')->type;

       The "type" accessor returns the type string for the MIME type, for example the above would
       print "text/plain".

   name
         print Padre::MIME->find('text/plain')->name;

       The "name" accessor returns the (localisable) English name of the MIME type. For example,
       the above would print "Text".

   super
         # Find the root type for a mime type
         my $mime = Padre::MIME->find('text/x-actionscript');
         $mime = $mime->super while $mime->super;

       The "super" method returns the Padre::MIME object for the immediate supertype of a
       particular MIME type, or false if there is no supertype.

   supertype
         # Find the root type for a mime type
         my $mime = Padre::MIME->find('text/x-actionscript');
         $mime = $mime->super while defined $mime->supertype;

       The "supertype" method returns the string form of the immediate supertype for a particular
       MIME type, or "undef" if there is no supertype.

   superpath
         # Find the comment format for a type
         my $mime    = Padre::MIME->find('text/x-actionscript');
         my $comment = undef;
         foreach my $type ( $mime->superpath ) {
             $comment = Padre::Comment->find($type) and last;
         }

       The "superpath" method returns a list of MIME type strings of the entire inheritance path
       for a particular MIME type, including itself.

       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.

   document
         my $module = Padre::MIME->find('text/x-perl')->document;

       The "document" method attempts to resolve an implementation class for this MIME type,
       either from the Padre core or from a plugin. For example, the above would return
       'Padre::Document::Perl'.

       Returns the class name as a string, or "undef" if no implementation class can be resolved.

   binary
         if ( Padre::MIME->find('application/octet-stream')->binary ) {
             die "Padre does not support binary files";
         }

       The "binary" method is a convenience for determining if a MIME type is a type of non-text
       file that Padre does not support opening.

       Returns true if the MIME type is binary or false if not.

   plugin
         # Overload the default Python support
         my $python = Padre::MIME->find('text/x-python');
         $python->plugin('Padre::Plugin::Python::Document');

       The "plugin" method is used to overload support for a MIME 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.

   reset
         # Remove the overloaded Python support
         Padre::MIME->find('text/x-python')->reset;

       The "reset" method is used to remove the overloading of a MIME 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.

   comment
         my $comment = Padre::MIME->find('text/x-perl')->comment;

       The "comment" method fetches the comment rules for the mime type from the Padre::Comment
       subsystem of Padre.

       Returns the basic comment as a string, or "undef" if no comment rule is known for the MIME
       type.

   detect
         my $type = Padre::MIME->detect(
             file => 'path/file.pm',
             text => "#!/usr/bin/perl\n\n",
             svn  => 1,
         );

       The "detect" method implements MIME 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.

       The optional parameter "file" param can either be a Padre::File object, or the path of the
       file in string form.

       The optional string parameter "text" should be all or part of the content of the file as a
       plain string.

       The optional boolean parameter "svn" indicates whether or not the detection code should
       look for a "svn:mime-type" property in the ".svn" metadata directory for the file.

       Returns a MIME type string for a registered MIME type if a reasonable guess can be made,
       or the null string '' if the detection code cannot determine the MIME type of the
       file/content.

   detect_svn
         my $type = Padre::MIME->detect_svn($path);

       The "detect_svn" method takes the path to a file as a string, and attempts to determine a
       MIME type for the file based on the file's Subversion "svn:eol-style" property.

       Returns a MIME type string which may or may not be registered with Padre or the null
       string '' if the property does not exist (or it is not stored in Subversion).

   detect_content
       The "detect_content" 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.

       Returns a MIME type string for a registered MIME type if a reasonable guess can be made,
       or the null string '' if the detection code cannot determine the file type of the content.

   detect_perl6
         my $is_perl6 = Padre::MIME->detect_perl6($content);

       The "detect_perl6" is a special case method used to distinguish between Perl 5 and Perl 6,
       as the two types often share the same file extension.

       Returns true if the content appears to be Perl 6, or false if the content appears to be
       Perl 5.

COPYRIGHT & LICENSE

       Copyright 2008-2013 The Padre development team as listed in Padre.pm.

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