Dave Rolsky > File-LibMagic-1.00 > File::LibMagic

Download:
File-LibMagic-1.00.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  4
Stalled  1
View/Report Bugs
Module Version: 1.00   Source   Latest Release: File-LibMagic-1.02

NAME ^

File::LibMagic - Determine MIME types of data or files using libmagic

VERSION ^

version 1.00

SYNOPSIS ^

  use File::LibMagic;

  my $magic = File::LibMagic->new();

  # prints a description like "ASCII text"
  print $magic->describe_filename('path/to/file');
  print $magic->describe_contents('this is some data');

  # Prints a MIME type like "text/plain; charset=us-ascii"
  print $magic->checktype_filename('path/to/file');
  print $magic->checktype_contents('this is some data');

DESCRIPTION ^

The File::LibMagic is a simple perl interface to libmagic from the file package (version 4.x or 5.x).

API ^

This module provides an object-oriented API with the following methods:

File::LibMagic->new()

Creates a new File::LibMagic object.

Using the object oriented interface provides an efficient way to repeatedly determine the magic of a file.

Each File::LibMagic object loads the magic database independently of other File::LibMagic objects, so you may want to share a single object across many modules as a singleton.

This method takes an optional argument containing a path to the magic file. If the file doesn't exist this will throw an exception (but only with libmagic 4.17+).

If you don't pass an argument, it will throw an exception if it can't find any magic files at all.

$magic->checktype_contents($data)

Returns the MIME type of the data given as the first argument. The data can be passed as a plain scalar or as a reference to a scalar.

This is the same value as would be returned by the file command with the -i switch.

$magic->checktype_filename($filename)

Returns the MIME type of the given file.

This is the same value as would be returned by the file command with the -i switch.

$magic->describe_contents($data)

Returns a description (as a string) of the data given as the first argument. The data can be passed as a plain scalar or as a reference to a scalar.

This is the same value as would be returned by the file command with no switches.

$magic->describe_filename($filename)

Returns a description (as a string) of the given file.

This is the same value as would be returned by the file command with no switches.

DEPRECATED APIS ^

This module offers two different procedural APIS based on optional exports, the "easy" and "complete" interfaces. These APIS are now deprecated. I strongly recommend you use the OO interface. It's simpler than the complete interface and more efficient than the easy interface.

The "easy" interface

This interface is exported by:

  use File::LibMagic ':easy';

This interface exports two subroutines:

The "complete" interface

This interface is exported by:

  use File::LibMagic ':easy';

This interface exports several subroutines:

EXCEPTIONS ^

This module can throw an exception if you system runs out of memory when trying to call magic_open internally.

SUPPORT ^

Please submit bugs to the CPAN RT system at http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-LibMagic or via email at bug-file-libmagic@rt.cpan.org.

BUGS ^

This module is totally dependent on the version of file on your system. It's possible that the tests will fail because of this. Please report these failures so I can make the tests smarter. Please make sure to report the version of file on your system as well!

DEPENDENCIES/PREREQUISITES ^

This module requires file 4.x or file 5x and the associated libmagic library and headers (http://darwinsys.com/file/).

RELATED MODULES ^

Andreas created File::LibMagic because he wanted to use libmagic (from file 4.x) File::MMagic only worked with file 3.x.

File::MimeInfo::Magic uses the magic file from freedesktop.org which is encoded in XML, and is thus not the fastest approach. See http://mail.gnome.org/archives/nautilus-list/2003-December/msg00260.html for a discussion of this issue.

File::Type uses a relatively small magic file, which is directly hacked into the module code. It is quite fast but the database is quite small relative to the file package.

AUTHORS ^

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2013 by Andreas Fitzner, Michael Hendricks, and Dave Rolsky.

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

syntax highlighting: