Module-Generic

 view release on metacpan or  search on metacpan

CHANGES  view on Meta::CPAN

      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
      generated from the upstream freedesktop.org shared-mime-info XML (630 entries, covering
      binary signatures with offset ranges, endianness-aware integer types, AND sub-matches,
      and bitmask support).
    - Added scripts/gen_magic_json.pl: a generator script to regenerate magic.json from an
      updated freedesktop.org XML source. Supports XML::LibXML, XML::Twig, and XML::Parser.
      Included in the distribution for reference but not installed by make install.
    - Added unit test t/32.file_magic.t for Module::Generic::File::Magic.
    - Updated Module::Generic::Finfo to use Module::Generic::File::Magic for mime_type()
      detection, replacing the previous File::MMagic::XS / File::MMagic fallback chain.
    - Updated Module::Generic::File to add the alias method 'stringify' to 'load_utf8'
    - Added the option 'pretty' to the method 'unload_perl' in Module::Generic::File
    - Improved Module::Generic::Global by allowing a new option 'on_get' to set a callback upon deserialisation
    - Improved Module::Generic::File, and especially the subroutine 'tmpfile'
    - Improved cleanup in Module::Generic::Global

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

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

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

    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

lib/Module/Generic/File/magic.json  view on Meta::CPAN

      },
      {
        "offset": 0,
        "range": 256,
        "type": "string",
        "bytes": "3c554920"
      }
    ]
  },
  {
    "mime": "application/x-desktop",
    "priority": 50,
    "matches": [
      {
        "offset": 0,
        "range": 32,
        "type": "string",
        "bytes": "5b4465736b746f7020456e7472795d"
      },
      {
        "offset": 0,

scripts/gen_magic_json.pl  view on Meta::CPAN

#!/usr/bin/env perl
##----------------------------------------------------------------------------
## Module::Generic::File::Magic - scripts/gen_magic_json.pl
## Version v0.1.0
## Copyright(c) 2026 DEGUEST Pte. Ltd.
## Author: Jacques Deguest <jack@deguest.jp>
## Created  2026/03/08
## Modified 2026/03/08
##
## Converts a freedesktop.org shared-mime-info XML file into the compact JSON
## magic database used by Module::Generic::File::Magic's pure-Perl backend.
##
## Usage:
##   perl scripts/gen_magic_json.pl [XML_FILE] [OUT_FILE]
##
## Defaults:
##   XML_FILE : /usr/share/mime/packages/freedesktop.org.xml
##   OUT_FILE : lib/Module/Generic/File/magic.json
##
## Requirements:
##   XML::LibXML  (preferred)  OR  XML::Parser  OR  XML::Twig
##   JSON
##
## Output format:
##   A JSON array of objects, sorted by descending priority then MIME type:
##   [
##     {

scripts/gen_magic_json.pl  view on Meta::CPAN

##         }
##       ]
##     },
##     ...
##   ]
##----------------------------------------------------------------------------
use strict;
use warnings;
use File::Spec ();

my $XML_FILE = $ARGV[0] // '/usr/share/mime/packages/freedesktop.org.xml';
my $OUT_FILE = $ARGV[1] // File::Spec->catfile(
    File::Spec->curdir, 'lib', 'Module', 'Generic', 'File', 'magic.json'
);

die( "Cannot read XML file: $XML_FILE\n" ) unless( -r $XML_FILE );

my $NS = 'http://www.freedesktop.org/standards/shared-mime-info';

# NOTE: Load an XML parser — try in order of preference
my $parser_type = _detect_xml_parser();
die(
    "No XML parser found. Please install one of:\n"
    . "  cpanm XML::LibXML\n"
    . "  cpanm XML::Twig\n"
    . "  cpanm XML::Parser\n"
) unless( defined( $parser_type )) ;