Padre::MIME(3) 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.

LAST SEARCHED