view release on metacpan or  search on metacpan

lib/Module/Generic/File/Magic.pm  view on Meta::CPAN

    use Module::Generic::File::Magic qw( :flags );

    my $magic = Module::Generic::File::Magic->new( flags => MAGIC_MIME_TYPE ) ||
        die( Module::Generic::File::Magic->error );

    # Which backend is active?
    printf "Backend: %s\n", $magic->backend;    # xs, json, or file

    # Detect from a file path
    my $mime = $magic->from_file( '/path/to/archive.tar.gz' ) ||
        die( $magic->error );
    # -> "application/gzip"

    # Detect from an in-memory buffer
    open( my $fh, '<:raw', '/path/to/file' ) or die( $! );
    read( $fh, my $buf, 4096 );
    close( $fh );
    my $mime = $magic->from_buffer( $buf ) || die( $magic->error );

    # Detect from an open filehandle
    open( my $fh, '<:raw', '/path/to/file' ) or die( $! );
    my $mime = $magic->from_filehandle( $fh ) || die( $magic->error );

    # Convenience wrappers
    my $type = $magic->mime_type_from_file( '/path/to/file' );
    my $enc  = $magic->mime_encoding_from_file( '/path/to/file' );
    my $full = $magic->mime_from_file( '/path/to/file' );
    # -> "application/gzip; charset=binary"

    # Control the read size for pure-Perl backends (default: 512 bytes)
    my $magic2 = Module::Generic::File::Magic->new(
        flags    => MAGIC_MIME_TYPE,
        max_read => 1024,
    ) || die( Module::Generic::File::Magic->error );

    # Change max_read at any time
    $magic->max_read(1024);

    # Procedural interface
    use Module::Generic::File::Magic qw( :functions );
    my $mime = magic_mime_type( '/path/to/file' );

=head1 VERSION

    v0.2.0

=head1 DESCRIPTION

C<Module::Generic::File::Magic> detects file types and MIME types using a three-level cascade, automatically selecting the best available backend:

=over 4

=item B<Level 1 - xs> (preferred)

C<libmagic.so.1> is loaded at runtime via C<dlopen(3)> - no C<magic.h>, no C<libmagic-dev> package required at build time. Full libmagic accuracy and performance. The C<MAGIC_COMPRESS>, C<MAGIC_SYMLINK>, and all other flags
are fully supported. C<compile()>, C<check()>, and C<list()> are only available at this level.

=item B<Level 2 - json>

C<libmagic> is absent. The module loads C<lib/Module/Generic/File/magic.json> (generated from the freedesktop.org shared-mime-info database, bundled with the distribution) and runs pure-Perl byte-pattern matching. Covers ~500 MIME types with magic si...

=item B<Level 3 - file>

No pattern matched at level 2. Invokes C<file(1)> in a subprocess as a last resort. C<from_buffer> writes a temporary file via L<File::Temp>.

=back

The active backend is available via C<< $magic->backend >> and the package variable C<$Module::Generic::File::Magic::BACKEND>.

Note that within the json backend, a text-content heuristic is applied before falling through to C<file(1)>.

=head1 CONSTRUCTOR

=head2 new

    my $magic = Module::Generic::File::Magic->new( %opts ) ||
        die( Module::Generic::File::Magic->error );

=over 4

=item * C<flags> - integer bitmask (default: C<MAGIC_NONE>)

=item * C<magic_db> - path to a custom C<.mgc> database (xs backend only)

=item * C<max_read> - maximum bytes read from a file for pure-Perl backends (default: C<512>)

=back

=head1 METHODS

=head2 backend

Returns the name of the active backend: C<"xs">, C<"json">, or C<"file">. Note that the reported value is the I<top-level> configured backend; the actual detection at runtime may cascade through multiple levels.

=head2 check( [ $filename ] )

Validates a magic database. B<xs backend only.>

=head2 close

Releases the C<magic_t> cookie. No-op on non-xs backends.

=head2 compile( $filename )

Compiles a magic source file into a C<.mgc> database. B<xs backend only.>

=head2 flags

Getter/setter for the libmagic flags bitmask.

=head2 from_buffer( $scalar )

Detects type from a raw byte scalar.

=head2 from_file( $path )

Detects type from a file path.

=head2 from_filehandle( $fh )

lib/Module/Generic/File/Magic.pm  view on Meta::CPAN

Disable compression check. [xs only]

=head2 MAGIC_NO_CHECK_TAR

Disable tar check. [xs only]

=head2 MAGIC_NO_CHECK_SOFT

Disable soft magic check. [xs only]

=head2 MAGIC_NO_CHECK_APPTYPE

Disable Apple creator/type check. [xs only]

=head2 MAGIC_NO_CHECK_ELF

Disable ELF check. [xs only]

=head2 MAGIC_NO_CHECK_TEXT

Disable text check. [xs only]

=head2 MAGIC_NO_CHECK_CDF

Disable CDF check. [xs only]

=head2 MAGIC_NO_CHECK_TOKENS

Disable token check. [xs only]

=head2 MAGIC_NO_CHECK_ENCODING

Disable encoding check. [xs only]

Flags marked C<[xs only]> are silently ignored on non-xs backends.

Flags marked C<[xs only]> are silently ignored on non-xs backends.

=head1 INSTALLATION

The only requirement for the xs backend is the C<libmagic1> runtime package:

    # Debian / Ubuntu
    sudo apt-get install libmagic1

    # RPM-based
    sudo yum install file-libs

    # macOS (Homebrew)
    brew install libmagic

No C<libmagic-dev> or C<file-devel> required. The module compiles and works on any system with a C compiler (the same one that built Perl).

=head1 FILES

=over 4

=item * C<lib/Module/Generic/File/magic.json>

Bundled magic signature database generated from the freedesktop.org shared-mime-info XML. Used by the json backend. To regenerate:

    perl scripts/gen_magic_json.pl [xml_path] [out_json_path]

=back

=head1 AUTHOR

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

=head1 SEE ALSO

L<Module::Generic::Finfo>, L<File::LibMagic>, L<File::MimeInfo>

The C<libmagic(3)> man page.

=head1 COPYRIGHT & LICENSE

Copyright (c) 2026 DEGUEST Pte. Ltd.

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

=cut