Module-Generic

 view release on metacpan or  search on metacpan

CHANGES  view on Meta::CPAN

      with a pure-Perl JSON fallback, replacing the use of File::MMagic
    - Improved Module::Generic::File::Magic::from_buffer() to fall back to a
      temporary file when magic_buffer() returns a generic type, working around
      inconsistent behaviour across libmagic versions (5.39, 5.46)
    - Updated Module::Generic::Finfo::mime_type() to use Module::Generic::File::Magic
    - Fixed read-only value error in Module::Generic::Global on Perl 5.28
    - Fixed off-by-one in Module::Generic::Global max_size eviction (>= vs >)

v1.2.0 2026-03-08T22:47:58+0900
    - Added new module Module::Generic::File::Magic providing file type and MIME type detection
      through a three-level backend cascade: an XS binding to libmagic (loaded at runtime via
      dlopen, requiring only the libmagic1 runtime package, so no libmagic-dev at build time),
      a pure-Perl JSON backend using a bundled magic signature database derived from the
      freedesktop.org shared-mime-info XML, and a final fallback to the file(1) subprocess.
      The active backend is available via $Module::Generic::File::Magic::BACKEND and the
      backend() method. All MAGIC_* flag constants are exported via the :flags tag.
    - Added Generic.xs to the distribution to provide the XS backend for
      Module::Generic::File::Magic. The XS MODULE is declared as Module::Generic so that
      XSLoader resolves Generic.so correctly; PACKAGE = Module::Generic::File::Magic ensures
      all XS functions are installed in the correct namespace.
    - Added lib/Module/Generic/File/magic.json: a compact JSON magic signature database

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

}

1;
# NOTE: POD
__END__

=encoding utf-8

=head1 NAME

Module::Generic::File::Magic - File type and MIME detection with 3-level backend cascade

=head1 SYNOPSIS

    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

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

    # 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>

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

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