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.
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.