NAME

Apache2::SSI::File::Type - Guess file MIME Type using Magic

SYNOPSIS

    use Apache2::SSI::File::Type;
    
    # use internal magic data; no outside dependencies
    my $m = Apache2::SSI::File::Type->new;
    # use external magic file
    # my $m = Apache2::SSI::File::Type->new( '/etc/apache2/magic' );
    my $mime_type = $m->file( "/somewhere/unknown/file" );
    # or, on windows
    my $mime_type = $m->file( "C:\Documents\myfile.cgi" );
    # using a file handle works too
    my $io = IO::File->new( "</somewhere/unknown/file2" );
    my $mime_type = $m->handle( $io );
    
    $io->read( $data, 0x8564 );
    my $mime_type = $m->data( $data );

DESCRIPTION

This module emulates the functionnality of file(1) unix utility cross platform, and returns the file MIME type.

It can guess it from a file name, data or file handle using methods described below.

It does not depend upon an external application to function.

CONSTRUCTOR

new( [ "/some/where/file.cgi" ] )

Creates a new Apache2::SSI::File::Type object and returns it. If a file is provided, Apache2::SSI::File::Type will use it instead of its default internal data.

If it can not open it or read it, it will set an error object and return undef. See "error" in Module::Generic for more information.

The result of the parsing of the given file is cached as a json file in the system's temporary folder, wherever that is. The location is provided by "tmpdir" in File::Spec

The internal magic data is provided internally from a json data file located in the same place as this module.

METHODS

as_json

This returns the internal magic data as a properly formatted json string using JSON.

This is used to create cache of magic files.

check( "/etc/apache2/magic" )

Checks the magic file provided and dumps it on the STDERR.

This is equivalent to option -c of file(1).

check_magic

Set or gets the boolean value used to decide whether the magic data are checked.

data( $some_data )

Guess the mime type based upon the data provided with $some_data and returns it.

If $some_data is zero length big, it will return application/x-empty.

Otherwise, it defaults to the value set with "default_type", which, by default, is text/plain if "default_type" is set to a true value or an empty value otherwise.

default_type

Set the default mime type to be returned as default, if any at all. If this is empty, it will default to text/plain by default.

If it iset to a true value, it will return that value or text/plain if it is set to empty string otherwise.

dump

Provided with an optional data as an array reference, or if nothing is provided, the internal magic data and this will print it out as a properly formatted magic file suitable to be re-used.

For example on your command line interface:

    # my_script.pl file:
    #/usr/bin/perl
    BEGIN
    {
        use strict;
        use warnings;
        use Apache2::SSI::File::Type;
    };
    
    my $m = Apache2::SSI::File::Type->new;
    $m->dump;
    exit;
    
    # on the command line:
    ./my_script.pl 2>my_magic

error_returns_undef

Sets or gets the boolean value to decide whether this module will return a default value (see "default_type") or undef when there is an error.

By default this is set to false, and the module will return a default value upon error.

file( '/some/file/path.txt' )

Provided with a file and this will guess its mim type.

If an error occurs, and if "error_returns_undef" is set to true, it will return x-system/x-error; description where description is the description of the error, otherwise it will set an error object with the error string and return undef. See "error" in Module::Generic for more information about the error object.

If the file to check is not a regular file or is empty, it will call "stat" in perlfunc and it will try hard to find its mime type.

Otherwise, it defaults to the value set with "default_type".

follow_links

Provided with a boolean value, this sets whether links should be followed.

Default to true.

handle

Provided with an opened file handle and this method will try to guess the mime type and returns it.

It defaults to whatever value is set with "default_type".

AUTHOR

Jacques Deguest <jack@deguest.jp>

CREDITS

Credits Nokubi Takatsugu.

SEE ALSO

file(1)

Apache2::SSI, Apache2::SSI::File, Apache2::SSI::Finfo, Apache2::SSI::URI

COPYRIGHT & LICENSE

Copyright (c) 2021 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.

cpanm Apache2::SSI

perl -MCPAN -e shell
install Apache2::SSI