view release on metacpan or  search on metacpan

lib/Apache2/SSI/File/Type.pm  view on Meta::CPAN

        return( 1 );
    }
}

# Obsolete routines
sub add_specials 
{
    my $self = shift( @_ );
    my $type = shift( @_ );
    $self->{SPECIALS}->{ $type } = [ @_ ];
    return( $self );
}

sub add_file_exts 
{
    my $self    = shift( @_ );
    my $filepat = shift( @_ );
    my $type    = shift( @_ );
    $self->{FILE_EXTS}->{ $filepat } = $type;
    return( $self );
}

sub add_magic_entry 
{
    my $self  = shift( @_ );
    my $entry = shift( @_ );
    unshift( @{$self->{magic_data}}, [ $entry, -1, [] ] );
    return( $self );
}

1;
# NOTE: POD
__END__

=head1 NAME

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

=head1 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 );

=head1 DESCRIPTION

This module emulates the functionnality of L<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.

=head1 CONSTRUCTOR

=over 4

=item B<new>( [ "/some/where/file.cgi" ] )

Creates a new L<Apache2::SSI::File::Type> object and returns it.
If a file is provided, L<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 L<Module::Generic/error> 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 L<File::Spec/tmpdir>

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

=back

=head1 METHODS

=for Pod::Coverage add_file_exts

=for Pod::Coverage add_magic_entry

=for Pod::Coverage add_specials

=head2 as_json

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

This is used to create cache of magic files.

=head2 check( "/etc/apache2/magic" )

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

This is equivalent to option C<-c> of L<file(1)>.

=head2 check_magic

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

=head2 data( $some_data )

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

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

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

=head2 default_type

Set the default mime type to be returned as default, if any at all. If this is empty, it will default to C<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.

=head2 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

=head2 error_returns_undef

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

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

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

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

If an error occurs, and if L</error_returns_undef> is set to true, it will return C<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 C<undef>. See L<Module::Generic/error> for more information about the error object.

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

Otherwise, it defaults to the value set with L</default_type>.

=head2 follow_links

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

Default to true.

=head2 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 L</default_type>.

=head2 parse_magic_file

Provided with a file handle, and this will parse the magic file, and load its data into the object.

=for Pod::Coverage parse_magic_line

=for Pod::Coverage read_magic_entry

=head2 with_data

Provided with some data, and this will attempt at guessing the mime type, and return it.

=head2 with_filename

Provided with a file name, and this will attempt at guessing the mime type, and return it.

=head2 with_magic

Provided with a C<magic> value, and this will attempt at guessing the mime type, and return it.

=head1 AUTHOR

Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>

=head1 CREDITS

Credits Nokubi Takatsugu.

=head1 SEE ALSO

L<file(1)>

L<Apache2::SSI>, L<Apache2::SSI::File>, L<Apache2::SSI::Finfo>, L<Apache2::SSI::URI>

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

=cut