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


-- | Lightweight replacement for Plugins, specific to GHC
--   
--   The Plugins package unfortunately does not work on GHC 6.12, and is at
--   any rate rather poorly documented. This package uses the same general
--   strategy but without quite as many options, aiming to be simple and
--   useful rather than complete. This release renames load to unsafeLoad
--   and adds loadDynamic, which is type-safe.
@package direct-plugins
@version 1.1


-- | The recommended interface, because it is safer (guaranteed not to
--   crash as long as modules have not been mis-installed somehow), is
--   <a>loadDynamic</a>. For versatility's sake, <a>unsafeLoad</a> is
--   provided as well, but caveat codor!
module System.Plugins

-- | Resolves the specified symbol to any given type. This means linking
--   the package containing it if it is not already linked, extracting the
--   value of that symbol, and returning that value. Because a call is made
--   to <a>unsafeCoerce</a>, the behavior is unpredictable (most likely an
--   immediate crash) if the symbol is not actually of the expected type.
--   Because <tt>load</tt> has no a priori way to know the type, you must
--   be certain to provide adequate type information in the caller, ie by
--   giving a type signature.
--   
--   Three error conditions are detected and handled nicely, returning
--   <a>Nothing</a>: The package does not exist; the package does not
--   contain the given module; or the module does not contain a symbol by
--   the given name.
--   
--   As a limitation which may be relaxed in a future version, note that
--   re-exports are not chased; thus for example it is not possible to find
--   the symbol <tt>base:Prelude.sum</tt>, because that symbol is actually
--   defined in <tt>base:Data.List</tt>.
unsafeLoad :: (String, String, String) -> IO (Maybe a)

-- | Resolves the specified symbol to a Dynamic. This means first parsing
--   the installed .hi file for the package containing the symbol to verify
--   that the symbol is in fact a Dynamic, then, if it is, linking the
--   package if it is not already linked, extracting the value of that
--   symbol, and returning that value. Unlike <tt>load</tt>, this function
--   should be "perfectly safe", not crashing even if the symbol is not
--   actually of the expected type.
--   
--   Four error conditions are detected and handled nicely, returning
--   <a>Nothing</a>: The package does not exist; the package does not
--   contain the given module; the module does not contain a symbol by the
--   given name; or the symbol's type is not <a>Dynamic</a>.
--   
--   As a limitation which may be relaxed in a future version, note that
--   re-exports are not chased; thus for example it is not possible to find
--   the symbol <tt>base:Prelude.sum</tt>, because that symbol is actually
--   defined in <tt>base:Data.List</tt>. (Also because that symbol is not a
--   <a>Dynamic</a>.)
loadDynamic :: (String, String, String) -> IO (Maybe Dynamic)