txt: ## dist_zef-thundergnat-Filetype-Magic.md
  [![Actions Status](https://github.com/thundergnat/Filetype-Magic/actions/workflows/test.yml/badge.svg)](https://github.com/thundergnat/Filetype-Magic/actions)
  
  # NAME Filetype::Magic
  
  Try to guess a files type using the libmagic heuristic library.
  
  # SYNOPSIS
  
  Object oriented mode:
  
  ```
  use Filetype::Magic;
  
  my $magic = Magic.new;
  
  say $magic.type: '/path/to/file.name';
  
  ```
  
  Or use a convenience function.
  
  Subroutine interface:
  
  ```
  use Filetype::Magic;
  
  say file-type '/path/to/file.name';
  
  ```
  
  # DESCRIPTION
  
  Provides a Raku interface to the libmagic shared library used by the 'file' utility to guess file types, installed by default on most BSDs and Linuxs. Libraries available for OSX and Windows as well.
  
  Linux / BSD / OSX: Needs to have the shared library: libmagic-dev installed. May install the shared library directly or install the file-dev packages which will include the shared libmagic library file. Needs the header files so will need the dev packages even if you already have libmagic installed.
  
  Windows: Needs libmagic.dll. Older 32bit packages are available on the authors site; the newest version available is 5.03. 64bit dlls can be built by following instructions on the nscaife github page (link below). At 5.29 by default, though it appears that it attempts to update to the latest version on build. (5.32 as of this writing.)
  
  | Platform | Install Method |
  | --- | --- |
  | Debian derivatives | [sudo] apt-get install libmagic-dev |
  | FreeBSD | [sudo] pkg install libmagic-dev |
  | Fedora | [sudo] dnf install libmagic-dev |
  | OSX | [sudo] brew install libmagic |
  | OpenSUSE | [sudo] zypper install libmagic-dev |
  | Red Hat | [sudo] yum install file-devel |
  | Source Code on GitHub | https://github.com/file/file |
  | Windows 32bit (older) | http://gnuwin32.sourceforge.net/packages/file.htm |
  | Windows 64bit (newer) | https://github.com/nscaife/file-windows |
  
  ---
  
  ## FLAGS
  
  There is a series of flags which control the behavior of the search:
  
  | Flag | hex value | meaning |
  | --- | --- | --- |
  | MAGIC\_NONE | 0x000000, | No flags |
  | MAGIC\_DEBUG | 0x000001, | Turn on debugging |
  | MAGIC\_SYMLINK | 0x000002, | Follow symlinks |
  | MAGIC\_COMPRESS | 0x000004, | Check inside compressed files |
  | MAGIC\_DEVICES | 0x000008, | Look at the contents of devices |
  | MAGIC\_MIME\_TYPE | 0x000010, | Return the MIME type |
  | MAGIC\_CONTINUE | 0x000020, | Return all matches |
  | MAGIC\_CHECK | 0x000040, | Print warnings to stderr |
  | MAGIC\_PRESERVE\_ATIME | 0x000080, | Restore access time on exit |
  | MAGIC\_RAW | 0x000100, | Don't translate unprintable chars |
  | MAGIC\_ERROR | 0x000200, | Handle ENOENT etc as real errors |
  | MAGIC\_MIME\_ENCODING | 0x000400, | Return the MIME encoding |
  | MAGIC\_MIME | 0x000410, | MAGIC\_MIME\_TYPE +| MAGIC\_MIME\_ENCODING |
  | MAGIC\_APPLE | 0x000800, | Return the Apple creator and type |
  | MAGIC\_NO\_CHECK\_COMPRESS | 0x001000, | Don't check for compressed files |
  | MAGIC\_NO\_CHECK\_TAR | 0x002000, | Don't check for tar files |
  | MAGIC\_NO\_CHECK\_SOFT | 0x004000, | Don't check magic entries |
  | MAGIC\_NO\_CHECK\_APPTYPE | 0x008000, | Don't check application |
  | MAGIC\_NO\_CHECK\_ELF | 0x010000, | Don't check for elf details |
  | MAGIC\_NO\_CHECK\_TEXT | 0x020000, | Don't check for text files |
  | MAGIC\_NO\_CHECK\_CDF | 0x040000, | Don't check for cdf files |
  | MAGIC\_NO\_CHECK\_TOKENS | 0x100000, | Don't check tokens |
  | MAGIC\_NO\_CHECK\_ENCODING | 0x200000, | Don't check text encodings |
  
  The flags may be set during construction by passing a :flags(WHATEVER) value in to the `.new( )` method, or may be adjusted later using the `.set-flags( )` method.
  
  ## FUNCTIONS - subroutine interface
  
  Useful for one-and-done, one-off use.
  
  ```
  sub file-type( IO::Path $path, Bool :$mime )
     # or
  sub file-type( Str $filename, Bool :$mime )
     # or
  sub file-type( IO::Handle $handle, Bool :$mime )
      # or
  sub file-type( Buf $buffer, Bool :$mime )
  
  ```
  
  Try to detect file type of a given file path/name, or open file handle, or string buffer. Strings must be in a specific encoding for the C library, so to avoid encoding issues and to differentiate string buffers from string filenames, you must pass strings as a Buf encoded appropriately. Pass a keyword parameter `mime` to get a mime type result.
  
  --
  
  ## METHODS - object interface
  
  For when you would like a persistent instance.
  
  ```
  method new  # Default database, default flags(none)
     # or
  method new( :magicfile( '/path/to/magic/database.file' ) ) # Load a custom database
     # or
  method new( :flags( MAGIC_SYMLINK +| MAGIC_MIME ) ) # Adjust search/reporting behavior
  
  ```
  
  Construct a new `Magic` instance with passed parameters if desired.
  
  --
  
  ```
  method set-flags( int32 $flags = 0 )
  
  ```
  
  Allows modification of parameters after initialization. Numeric-bitwise `or` any parameters together.
  
  E.G. `$magic-instance.set-flags( MAGIC_SYMLINK +| MAGIC_MIME )`.
  
  --
  
  ```
  method get-flags( )
  
  ```
  
  Query which flags are set, returns the int32 value of the set flags.
  
  --
  
  ```
  method type( IO::Path $path )
     # or
  method type( Str $filename )
     # or
  method type( IO::Handle $handle )
     # or
  method type( Buf $buffer )
  
  ```
  
  Try to detect file type of a given a file path/name, or open file handle, or string buffer. Strings must be in a specific encoding for the C library, so to avoid encoding issues and to differentiate string buffers from string filenames, you must pass strings as a Buf encoded appropriately.
  
  --
  
  ```
  method version()
  
  ```
  
  Return the current version. First digit is major version number, rest are minor.
  
  ---
  
  There are several semi-private methods which mostly deal with initialization and setup. There is nothing preventing you from accessing them, they are publically available, but most people won't ever need to use them.
  
  ```
  method magic-database( str $magic-database, int32 $flags )
  
  ```
  
  Location of the magic database file, pass Nil to load the default database. Pass any flags numeric-bitwise `or`ed together to adjust behavior. (See `method set-flags`)
  
  --
  
  ```
  method magic-init( int32 $flags = 0 )
  
  ```
  
  Initialize the file-magic instance, allocate a data structure to hold information and return a pointer to it. Pointer is stored in the class as $!magic-cookie.
  
  --
  
  ```
  method magic-load( Pointer $magic-struct, str $database-list )
  
  ```
  
  Load the database file(s) into the data structure.
  
  --
  
  ```
  method magic-error()
  
  ```
  
  Pass any errors back up to the calling code.
  
  --
  
  Once the Magic instance is initialized, you may query the database locations by checking the `$magic-instance.database` string. Contains the various file paths to loaded database files as a colon separated string. Do not try to change the database string directly. It will not affect the current instance; it is only a convenience method to make it easier to see the currently loaded files. Changes to the database need to be done with the `magic-load( )` method.
  
  ---
  
  A few methods dealing with generating, compiling, and checking magic database files have yet to be implemented.
  
  # AUTHOR
  
  2019 Steve Schulze aka thundergnat
  
  This package is free software and is provided "as is" without express or implied warranty. You can redistribute it and/or modify it under the same terms as Perl itself.
  
  libmagic library and file utility v5.x author: Ian Darwin, Christos Zoulas, et al.
  
  #### CONTRIBUTORS
  
  github: gmoshkin
  
  # LICENSE
  
  Licensed under The Artistic 2.0; see LICENSE.
  