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

cpanm Padre

perl -MCPAN -e shell
install Padre