-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | This package provides a Haskell interface to the C libmagic library.
--   With it, you can determine the type of a file by examining its
--   contents rather than its name. The Haskell interface provides a
--   full-featured binding.
--   
--   Note: this package requires the C libmagic library (part of the
--   <tt>file</tt> package) and its development headers to be installed at
--   build time.
@package magic
@version 1.1.2


-- | The <a>MagicFlag</a> enumeration, mapping the C <tt>libmagic</tt>
--   <tt>MAGIC_*</tt> constants to Haskell.
module Magic.Data

-- | Flags that control how <tt>libmagic</tt> examines a file and what it
--   reports. Combine them in the list passed to <tt>magicOpen</tt> or
--   <tt>magicSetFlags</tt>.
data MagicFlag

-- | No special handling; return a textual description (the default).
MagicNone :: MagicFlag

-- | Print debugging messages to stderr.
MagicDebug :: MagicFlag

-- | Follow symbolic links.
MagicSymlink :: MagicFlag

-- | Look inside compressed files.
MagicCompress :: MagicFlag

-- | Look at the contents of block or character special devices.
MagicDevices :: MagicFlag

-- | Return a MIME type string instead of a textual description.
MagicMimeType :: MagicFlag

-- | Return the MIME encoding (character set) instead of a textual
--   description.
MagicMimeEncoding :: MagicFlag

-- | Return both the MIME type and the encoding.
MagicMime :: MagicFlag

-- | Return all matches, not just the first.
MagicContinue :: MagicFlag

-- | Check the magic database for consistency and report problems.
MagicCheck :: MagicFlag

-- | Preserve the access time of examined files.
MagicPreserveAtime :: MagicFlag

-- | Do not translate unprintable characters to octal escapes.
MagicRaw :: MagicFlag

-- | Treat errors while examining a file as real errors instead of
--   embedding them in the result.
MagicError :: MagicFlag

-- | Return the Apple creator and type.
MagicApple :: MagicFlag

-- | Return a slash-separated list of valid file extensions for the
--   detected type.
MagicExtension :: MagicFlag

-- | Report on the compressed contents only, without mentioning the
--   compression itself (transparent decompression).
MagicCompressTransp :: MagicFlag

-- | Do not allow decompression that requires forking a helper process.
MagicNoCompressFork :: MagicFlag

-- | Composite of <a>MagicExtension</a>, <a>MagicMime</a> and
--   <a>MagicApple</a>: return identifiers rather than a textual
--   description.
MagicNodesc :: MagicFlag

-- | Do not look inside compressed files.
MagicNoCheckCompress :: MagicFlag

-- | Do not examine tar archives.
MagicNoCheckTar :: MagicFlag

-- | Do not consult the magic database entries (soft magic).
MagicNoCheckSoft :: MagicFlag

-- | Do not check for an application type (e.g. EMX).
MagicNoCheckApptype :: MagicFlag

-- | Do not examine ELF details.
MagicNoCheckElf :: MagicFlag

-- | Do not examine text files.
MagicNoCheckText :: MagicFlag

-- | Do not examine CDF (Microsoft Compound Document) files.
MagicNoCheckCdf :: MagicFlag

-- | Do not examine CSV files.
MagicNoCheckCsv :: MagicFlag

-- | Do not look for known text tokens.
MagicNoCheckTokens :: MagicFlag

-- | Do not check text encodings.
MagicNoCheckEncoding :: MagicFlag

-- | Do not examine JSON files.
MagicNoCheckJson :: MagicFlag

-- | Do not examine SIMH tape files.
MagicNoCheckSimh :: MagicFlag

-- | Disable all built-in tests; consult only the magic database.
MagicNoCheckBuiltin :: MagicFlag

-- | A flag value returned by libmagic that these bindings do not
--   recognise, carrying its raw integer value.
UnknownMagicFlag :: Int -> MagicFlag
instance GHC.Internal.Enum.Enum Magic.Data.MagicFlag
instance GHC.Classes.Eq Magic.Data.MagicFlag
instance GHC.Classes.Ord Magic.Data.MagicFlag
instance GHC.Internal.Show.Show Magic.Data.MagicFlag


-- | The core types of the binding: the opaque <a>Magic</a> handle, the
--   <a>MagicFlag</a> enumeration (re-exported from <a>Magic.Data</a>) and
--   the <a>MagicParam</a> tunables.
--   
--   Written by John Goerzen.
module Magic.Types

-- | The magic handle: an opaque cookie obtained from <tt>magicOpen</tt>
--   and passed to the loading and querying functions.
--   
--   Handles are closed (and their memory freed) automatically when they
--   are garbage-collected by Haskell. There is no need to close them
--   explicitly.
--   
--   <b>Thread safety.</b> A single <tt>Magic</tt> handle is <i>not</i>
--   safe for concurrent use: the underlying <tt>libmagic</tt> cookie keeps
--   mutable state, so calling operations on the same handle from multiple
--   threads at once is a data race. Use one handle per thread, or
--   serialise access to a shared handle (e.g. behind an <tt>MVar</tt>).
--   Distinct handles are independent and may be used concurrently.
--   Programs doing blocking work (loading databases, examining files)
--   should also be built with the threaded runtime (<tt>-threaded</tt>).
type Magic = ForeignPtr CMagic

-- | Phantom type standing in for the C <tt>magic_t</tt> cookie. It appears
--   only as the argument of a <a>ForeignPtr</a> (the <a>Magic</a> handle)
--   and has no values of its own.
data CMagic

-- | Flags that control how <tt>libmagic</tt> examines a file and what it
--   reports. Combine them in the list passed to <tt>magicOpen</tt> or
--   <tt>magicSetFlags</tt>.
data MagicFlag

-- | No special handling; return a textual description (the default).
MagicNone :: MagicFlag

-- | Print debugging messages to stderr.
MagicDebug :: MagicFlag

-- | Follow symbolic links.
MagicSymlink :: MagicFlag

-- | Look inside compressed files.
MagicCompress :: MagicFlag

-- | Look at the contents of block or character special devices.
MagicDevices :: MagicFlag

-- | Return a MIME type string instead of a textual description.
MagicMimeType :: MagicFlag

-- | Return the MIME encoding (character set) instead of a textual
--   description.
MagicMimeEncoding :: MagicFlag

-- | Return both the MIME type and the encoding.
MagicMime :: MagicFlag

-- | Return all matches, not just the first.
MagicContinue :: MagicFlag

-- | Check the magic database for consistency and report problems.
MagicCheck :: MagicFlag

-- | Preserve the access time of examined files.
MagicPreserveAtime :: MagicFlag

-- | Do not translate unprintable characters to octal escapes.
MagicRaw :: MagicFlag

-- | Treat errors while examining a file as real errors instead of
--   embedding them in the result.
MagicError :: MagicFlag

-- | Return the Apple creator and type.
MagicApple :: MagicFlag

-- | Return a slash-separated list of valid file extensions for the
--   detected type.
MagicExtension :: MagicFlag

-- | Report on the compressed contents only, without mentioning the
--   compression itself (transparent decompression).
MagicCompressTransp :: MagicFlag

-- | Do not allow decompression that requires forking a helper process.
MagicNoCompressFork :: MagicFlag

-- | Composite of <a>MagicExtension</a>, <a>MagicMime</a> and
--   <a>MagicApple</a>: return identifiers rather than a textual
--   description.
MagicNodesc :: MagicFlag

-- | Do not look inside compressed files.
MagicNoCheckCompress :: MagicFlag

-- | Do not examine tar archives.
MagicNoCheckTar :: MagicFlag

-- | Do not consult the magic database entries (soft magic).
MagicNoCheckSoft :: MagicFlag

-- | Do not check for an application type (e.g. EMX).
MagicNoCheckApptype :: MagicFlag

-- | Do not examine ELF details.
MagicNoCheckElf :: MagicFlag

-- | Do not examine text files.
MagicNoCheckText :: MagicFlag

-- | Do not examine CDF (Microsoft Compound Document) files.
MagicNoCheckCdf :: MagicFlag

-- | Do not examine CSV files.
MagicNoCheckCsv :: MagicFlag

-- | Do not look for known text tokens.
MagicNoCheckTokens :: MagicFlag

-- | Do not check text encodings.
MagicNoCheckEncoding :: MagicFlag

-- | Do not examine JSON files.
MagicNoCheckJson :: MagicFlag

-- | Do not examine SIMH tape files.
MagicNoCheckSimh :: MagicFlag

-- | Disable all built-in tests; consult only the magic database.
MagicNoCheckBuiltin :: MagicFlag

-- | A flag value returned by libmagic that these bindings do not
--   recognise, carrying its raw integer value.
UnknownMagicFlag :: Int -> MagicFlag

-- | Tunable limits that bound how hard <tt>libmagic</tt> works when
--   examining data, read and written with <tt>magicGetParam</tt> and
--   <tt>magicSetParam</tt> (see <a>Magic.Operations</a>). Lowering these
--   (especially <a>MagicParamBytesMax</a>) is a way to cap the effort
--   spent on untrusted input. Defaults below are those documented for
--   <tt>libmagic</tt> 5.45.
data MagicParam

-- | Maximum number of levels of recursion when following indirect magic.
--   (Default: 15.)
MagicParamIndirMax :: MagicParam

-- | Maximum length of a name used by name/use magic. (Default: 30.)
MagicParamNameMax :: MagicParam

-- | Maximum number of ELF program header sections processed. (Default:
--   128.)
MagicParamElfPhnumMax :: MagicParam

-- | Maximum number of ELF section header sections processed. (Default:
--   32768.)
MagicParamElfShnumMax :: MagicParam

-- | Maximum number of ELF notes processed. (Default: 256.)
MagicParamElfNotesMax :: MagicParam

-- | Maximum length of a regex search. (Default: 8192.)
MagicParamRegexMax :: MagicParam

-- | Maximum number of bytes read from a file before giving up. (Default:
--   1048576, i.e. 1 MiB.)
MagicParamBytesMax :: MagicParam

-- | Maximum number of bytes scanned when guessing a text encoding.
MagicParamEncodingMax :: MagicParam

-- | Maximum size of an ELF section processed.
MagicParamElfShsizeMax :: MagicParam
instance GHC.Internal.Enum.Bounded Magic.Types.MagicParam
instance GHC.Internal.Enum.Enum Magic.Types.MagicParam
instance GHC.Classes.Eq Magic.Types.MagicParam
instance GHC.Classes.Ord Magic.Types.MagicParam
instance GHC.Internal.Show.Show Magic.Types.MagicParam


-- | Querying the type of files and in-memory data, and other operations on
--   a magic handle. The handle must first be created with
--   <tt>magicOpen</tt> and populated with <tt>magicLoadDefault</tt> or
--   <tt>magicLoad</tt> (see <a>Magic.Init</a>).
--   
--   Written by John Goerzen.
module Magic.Operations

-- | Identify the file at the given path. The result is in the form
--   selected by the handle's flags (a textual description, a MIME type, an
--   encoding, and so on; see <a>MagicFlag</a>). Raises an <a>IOError</a>
--   if the file cannot be examined.
magicFile :: Magic -> FilePath -> IO String

-- | Identify the data available on standard input, as <a>magicFile</a>
--   does for a named file. Raises an <a>IOError</a> if the data cannot be
--   examined.
magicStdin :: Magic -> IO String

-- | Identify the data behind an open file descriptor, as <a>magicFile</a>
--   does for a named file. Useful for sockets, pipes, or files you have
--   already opened. Raises an <a>IOError</a> if the descriptor cannot be
--   examined.
magicDescriptor :: Magic -> Fd -> IO String

-- | Identify the contents of the given <a>String</a>. Note that the string
--   is processed strictly, not lazily.
--   
--   This is convenient for textual data. For binary data prefer
--   <a>magicCString</a> (or write it to a file and use <a>magicFile</a>):
--   marshalling through <a>String</a> goes via the current locale
--   encoding, which can corrupt non-textual bytes. Raises an
--   <a>IOError</a> if the data cannot be examined.
magicString :: Magic -> String -> IO String

-- | Identify the contents of a C string buffer (a pointer and a length).
--   This is the lower-level primitive behind <a>magicString</a>, and the
--   right choice for raw binary data since it does no encoding conversion.
--   Raises an <a>IOError</a> if the data cannot be examined.
magicCString :: Magic -> CStringLen -> IO String

-- | Identify the contents of a strict <a>ByteString</a>. Unlike
--   <a>magicString</a> this does no encoding conversion, so it is the
--   right choice for binary data. Raises an <a>IOError</a> if the data
--   cannot be examined.
magicByteString :: Magic -> ByteString -> IO String

-- | Change the flags (see <a>MagicFlag</a>) on an existing handle, for
--   example to switch between textual descriptions and MIME types. Raises
--   an <a>IOError</a> on failure.
magicSetFlags :: Magic -> [MagicFlag] -> IO ()

-- | Read the flags currently set on the handle (see <a>magicSetFlags</a>).
--   Composite masks are returned decomposed into their individual flags.
--   Raises an <a>IOError</a> if the running <tt>libmagic</tt> does not
--   support querying flags.
magicGetFlags :: Magic -> IO [MagicFlag]

-- | Read a tunable parameter (see <a>MagicParam</a>).
magicGetParam :: Magic -> MagicParam -> IO Int

-- | Set a tunable parameter (see <a>MagicParam</a>), for example to cap
--   the number of bytes scanned in untrusted input. Raises an
--   <a>IOError</a> on failure.
magicSetParam :: Magic -> MagicParam -> Int -> IO ()

-- | Compile the given colon-separated magic database file(s) into the
--   binary <tt>.mgc</tt> form. Each compiled file is named after its
--   source with <tt>.mgc</tt> appended. Pass <a>Nothing</a> to compile the
--   default database. Raises an <a>IOError</a> on failure.
magicCompile :: Magic -> Maybe String -> IO ()

-- | Check the validity of the given magic database file(s) without
--   compiling them, as <tt>file -c</tt> does. Pass <a>Nothing</a> for the
--   default database. Returns <a>True</a> if the database is valid.
magicCheck :: Magic -> Maybe FilePath -> IO Bool

-- | The path of the default magic database, honouring the <tt>MAGIC</tt>
--   environment variable.
magicGetPath :: IO FilePath

-- | The version of the <tt>libmagic</tt> library in use, encoded as a
--   single integer (for example <tt>545</tt> for version 5.45).
magicVersion :: IO Int

-- | The <tt>errno</tt> recorded by the last failing operation on the
--   handle, or <tt>0</tt> if the last failure was not caused by a system
--   error.
magicErrno :: Magic -> IO Int


-- | Creating a magic handle and loading magic databases into it. A handle
--   returned by <a>magicOpen</a> must be given a database with
--   <a>magicLoadDefault</a> or <a>magicLoad</a> before it can be queried
--   with the functions in <a>Magic.Operations</a>.
--   
--   Written by John Goerzen.
module Magic.Init

-- | Create a new magic handle configured with the given flags (see
--   <a>MagicFlag</a>). Before querying anything you must load a database
--   with <a>magicLoadDefault</a> or <a>magicLoad</a>.
--   
--   The handle is freed automatically when it is garbage-collected. Raises
--   an <a>IOError</a> if the handle cannot be created.
magicOpen :: [MagicFlag] -> IO Magic

-- | Load the given magic database(s) into the handle. The argument may be
--   a single path or several colon-separated paths. Raises an
--   <a>IOError</a> if a database cannot be loaded.
magicLoad :: Magic -> String -> IO ()

-- | Load the system's default magic database into the handle. Raises an
--   <a>IOError</a> if the database cannot be loaded.
magicLoadDefault :: Magic -> IO ()


-- | Haskell bindings to the C <tt>libmagic</tt> library, which identifies
--   the type of a file by inspecting its contents rather than its name. It
--   can report a textual description, a MIME type, or a character-set
--   encoding.
--   
--   This top-level module re-exports the whole interface: the types in
--   <a>Magic.Types</a>, the initialization functions in <a>Magic.Init</a>,
--   and the querying functions in <a>Magic.Operations</a>.
--   
--   A typical session creates a handle, loads the system magic database,
--   then queries files or in-memory data. The flags passed to
--   <a>magicOpen</a> (see <a>MagicFlag</a>) choose what kind of answer
--   comes back:
--   
--   <pre>
--   import Magic
--   
--   main :: IO ()
--   main = do
--     magic &lt;- magicOpen [MagicMimeType]   -- ask for MIME types
--     magicLoadDefault magic               -- load the system database
--     mime &lt;- magicFile magic "/etc/passwd"
--     putStrLn mime                        -- e.g. "text/plain"
--   </pre>
--   
--   Handles are closed and their memory freed automatically when they are
--   garbage-collected (see <a>Magic</a>); there is no explicit close. On
--   failure the operations in this library raise an <a>IOError</a>.
--   
--   Originally written by John Goerzen.
module Magic
