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


-- | Clean up module imports, split and merge modules
--   
--   Clean up module imports, split and merge modules.
@package module-management
@version 0.17.2

module Language.Haskell.Modules.Util.Temp

-- | Adapted from <a>withTempDirectory</a> to work in MonadIO instances.
withTempDirectory :: (MonadIO m, MonadBaseControl IO m) => FilePath -> String -> (FilePath -> m a) -> m a

module Language.Haskell.Modules.Util.Symbols

-- | Do a fold over the names that are declared in a declaration (not every
--   name that appears, just the ones that the declaration is causing to
--   exist - what's the word for that? Reify!)
class FoldDeclared a
foldDeclared :: FoldDeclared a => (Maybe Name -> r -> r) -> r -> a -> r

-- | Fold over the declared members - e.g. the method names of a class
--   declaration, the constructors of a data declaration.
class FoldMembers a
foldMembers :: FoldMembers a => (Maybe Name -> r -> r) -> r -> a -> r
symbols :: FoldDeclared a => a -> Set (Maybe Name)
members :: FoldMembers a => a -> Set (Maybe Name)
exports :: (FoldDeclared a, FoldMembers a) => a -> [ExportSpec]
imports :: (FoldDeclared a, FoldMembers a) => a -> [ImportSpec]
instance FoldDeclared (GadtDecl l)
instance FoldDeclared (FieldDecl l)
instance FoldDeclared (ConDecl l)
instance FoldDeclared (QualConDecl l)
instance FoldMembers (Decl a)
instance FoldDeclared (ExportSpec l)
instance FoldDeclared (ImportSpec l)
instance FoldDeclared (Name l)
instance FoldDeclared (RPat a)
instance FoldDeclared (PatField a)
instance FoldDeclared (Pat a)
instance FoldDeclared (QName a)
instance FoldDeclared (Match a)
instance FoldDeclared (InstHead a)
instance FoldDeclared (ClassDecl a)
instance FoldDeclared (DeclHead a)
instance FoldDeclared (Decl a)

module Language.Haskell.Modules.Util.SrcLoc
class HasSpanInfo a
spanInfo :: HasSpanInfo a => a -> SrcSpanInfo
srcSpan :: HasSpanInfo x => x -> SrcSpan
srcLoc :: HasSpanInfo x => x -> SrcLoc
endLoc :: HasSpanInfo x => x -> SrcLoc
textEndLoc :: FilePath -> String -> SrcLoc

-- | Update a SrcLoc to move it from l past the string argument.
increaseSrcLoc :: String -> SrcLoc -> SrcLoc
textSpan :: FilePath -> String -> SrcSpanInfo

-- | Given a beginning and end location, and a string which starts at the
--   beginning location, return a (beforeend,afterend) pair.
srcPairText :: SrcLoc -> SrcLoc -> String -> (String, String)

-- | Build a tree of SrcSpanInfo
makeTree :: (HasSpanInfo a, Show a, Eq a, Ord a) => Set a -> Tree a
instance HasSpanInfo SrcSpanInfo
instance HasSpanInfo Decl
instance HasSpanInfo ImportDecl
instance HasSpanInfo ExportSpec
instance HasSpanInfo ExportSpecList
instance HasSpanInfo WarningText
instance HasSpanInfo ModulePragma
instance HasSpanInfo ModuleName
instance HasSpanInfo ModuleHead
instance HasSpanInfo a => HasSpanInfo (Tree a)
instance HasSpanInfo SrcSpan

module Language.Haskell.Modules.Util.DryIO
class MonadIO m => MonadDryRun m
dry :: MonadDryRun m => m Bool
putDry :: MonadDryRun m => Bool -> m ()
dryIO :: MonadDryRun m => IO () -> m ()
dryIO' :: MonadDryRun m => IO a -> IO a -> m a
tildeBackup :: FilePath -> Maybe FilePath
noBackup :: FilePath -> Maybe FilePath
readFileMaybe :: FilePath -> IO (Maybe String)

-- | Replace the file at path with the given text, moving the original to
--   the location returned by passing path to backup. If backup is the
--   identity function you're going to have a bad time.
replaceFile :: MonadDryRun m => (FilePath -> Maybe FilePath) -> FilePath -> String -> m ()
replaceFileIfDifferent :: MonadDryRun m => FilePath -> String -> m Bool
removeFileIfPresent :: MonadDryRun m => FilePath -> m ()
createDirectoryIfMissing :: MonadDryRun m => Bool -> String -> m ()
writeFile :: MonadDryRun m => FilePath -> String -> m ()

module Language.Haskell.Modules.Util.Test
repoModules :: [String]
logicModules :: [String]
diff :: FilePath -> FilePath -> IO (ExitCode, String, String)

-- | Like diff, but ignores extra files in b.
diff' :: FilePath -> FilePath -> IO (ExitCode, String, String)
rsync :: FilePath -> FilePath -> IO ()

-- | Convenience function for building the moduVerse, searches for modules
--   in a directory hierarchy. FIXME: This should be in MonadClean and use
--   the value of sourceDirs to remove prefixes from the module paths. And
--   then it should look at the module text to see what the module name
--   really is.
findHsModules :: [FilePath] -> IO [ModuleName]

-- | Find the paths of all the files below the directory <tt>top</tt>.
findHsFiles :: [FilePath] -> IO [FilePath]


-- | IO operations predicated on the verbosity value managed by the methods
--   of MonadVerbosity. Noisily increases this value and quietly decreases
--   it, and the q* operations only happen when the value is greater than
--   zero.
module Language.Haskell.Modules.Util.QIO
class MonadIO m => MonadVerbosity m
getVerbosity :: MonadVerbosity m => m Int
putVerbosity :: MonadVerbosity m => Int -> m ()
modifyVerbosity :: MonadVerbosity m => (Int -> Int) -> m ()

-- | Decrease the amount of progress reporting during an action.
quietly :: MonadVerbosity m => m a -> m a

-- | Increase the amount of progress reporting during an action.
noisily :: MonadVerbosity m => m a -> m a
qIO :: MonadVerbosity m => m () -> m ()
qPutStr :: MonadVerbosity m => String -> m ()
qPutStrLn :: MonadVerbosity m => String -> m ()
qLnPutStr :: MonadVerbosity m => String -> m ()

module Language.Haskell.Modules.SourceDirs
class (MonadIO m, MonadBaseControl IO m) => SourceDirs m
putDirs :: SourceDirs m => [FilePath] -> m ()
getDirs :: SourceDirs m => m [FilePath]

-- | Modify the list of directories that will be searched for imported
--   modules.
modifyDirs :: SourceDirs m => ([FilePath] -> [FilePath]) -> m ()
withDirs :: SourceDirs m => [FilePath] -> m a -> m a

-- | A FilePath that is relative to the SourceDir list
newtype RelPath
RelPath :: FilePath -> RelPath
unRelPath :: RelPath -> FilePath

-- | A FilePath that can be assumed to be unique.
newtype PathKey
PathKey :: FilePath -> PathKey
unPathKey :: PathKey -> FilePath

-- | A regular filepath with a wrapper
newtype APath
APath :: FilePath -> APath
unAPath :: APath -> FilePath
pathKey :: (SourceDirs m, Path p, Show p) => p -> m PathKey
class Path a
findFileMaybe :: (Path a, SourceDirs m) => a -> m (Maybe APath)
pathKeyMaybe :: (Path a, SourceDirs m) => a -> m (Maybe PathKey)

-- | Search the path directory list, preferring an already existing file,
--   but if there is none construct one using the first element of the
--   directory list.
modulePath :: SourceDirs m => String -> ModuleName -> m APath
modulePathBase :: String -> ModuleName -> RelPath
instance Eq PathKey
instance Ord PathKey
instance Show PathKey
instance Eq RelPath
instance Ord RelPath
instance Show RelPath
instance Eq APath
instance Ord APath
instance Show APath
instance Path APath
instance Path PathKey
instance Path RelPath

module Language.Haskell.Modules.ModuVerse
data ModuleInfo
ModuleInfo :: Module SrcSpanInfo -> String -> [Comment] -> PathKey -> ModuleInfo
module_ :: ModuleInfo -> Module SrcSpanInfo
text_ :: ModuleInfo -> String
comments_ :: ModuleInfo -> [Comment]
key_ :: ModuleInfo -> PathKey
moduleName :: ModuleInfo -> ModuleName
data ModuVerseState
moduVerseInit :: ModuVerseState
class (MonadIO m, MonadBaseControl IO m, Functor m) => ModuVerse m
getModuVerse :: ModuVerse m => m ModuVerseState
modifyModuVerse :: ModuVerse m => (ModuVerseState -> ModuVerseState) -> m ()
getNames :: ModuVerse m => m (Set ModuleName)
getInfo :: ModuVerse m => ModuleName -> m (Maybe ModuleInfo)
putModule :: (ModuVerse m, MonadVerbosity m) => ModuleName -> m ()
putModuleAnew :: (ModuVerse m, MonadVerbosity m) => ModuleName -> m PathKey
findModule :: (ModuVerse m, MonadVerbosity m) => ModuleName -> m (Maybe ModuleInfo)
delName :: ModuVerse m => ModuleName -> m ()
getExtensions :: ModuVerse m => m [Extension]

-- | Modify the list of extensions passed to GHC when dumping the minimal
--   imports. Note that GHC will also use the extensions in the module's
--   LANGUAGE pragma, so this can usually be left alone.
modifyExtensions :: ModuVerse m => ([Extension] -> [Extension]) -> m ()
parseModule :: (ModuVerse m, MonadVerbosity m) => PathKey -> m ModuleInfo
parseModuleMaybe :: (ModuVerse m, MonadVerbosity m) => Maybe PathKey -> m (Maybe ModuleInfo)

-- | Force a possibly cached module to be reloaded.
loadModule :: (ModuVerse m, MonadVerbosity m) => PathKey -> m ModuleInfo
unloadModule :: (ModuVerse m, MonadVerbosity m) => PathKey -> m ()
instance Ord Comment
instance Eq ModuleInfo
instance Ord ModuleInfo
instance Show ModuleInfo
instance Eq ModuVerseState
instance Ord ModuVerseState
instance Show ModuVerseState
instance ModuVerse m => SourceDirs m


-- | Functions to control the state variables of <a>MonadClean</a>.
module Language.Haskell.Modules.Params

-- | This contains the information required to run the state monad for
--   import cleaning and module spliting/mergeing.
data Params
Params :: FilePath -> Bool -> Int -> [String] -> ModuVerseState -> Set FilePath -> Bool -> Map ModuleName (Set ImportDecl) -> Bool -> Params

-- | Location of the temporary directory for ghc output.
scratchDir :: Params -> FilePath

-- | None of the operations that modify the modules will actually be
--   performed if this is ture.
dryRun :: Params -> Bool

-- | Increase or decrease the amount of progress reporting.
verbosity :: Params -> Int

-- | Extra flags to pass to GHC.
hsFlags :: Params -> [String]

-- | The set of modules that splitModules and catModules will check for
--   imports of symbols that moved.
moduVerse :: Params -> ModuVerseState

-- | Paths added to this list are removed as the state monad finishes.
junk :: Params -> Set FilePath

-- | If true, remove any import that became empty due to the clean. THe
--   import might still be required because of the instances it contains,
--   but usually it is not. Note that this option does not affect imports
--   that started empty and end empty.
removeEmptyImports :: Params -> Bool

-- | Deciding whether a module needs to be imported can be difficult when
--   instances are involved, this is a cheat to force keys of the map to
--   import the corresponding elements.
extraImports :: Params -> Map ModuleName (Set ImportDecl)

-- | For testing, do not run cleanImports on the results of the splitModule
--   and catModules operations.
testMode :: Params -> Bool

-- | An instance of MonadClean.
type CleanT m = StateT Params m
class (MonadIO m, MonadBaseControl IO m, Functor m) => MonadClean m
getParams :: MonadClean m => m Params
putParams :: MonadClean m => Params -> m ()
modifyParams :: MonadClean m => (Params -> Params) -> m ()

-- | Create the environment required to do import cleaning and module
--   splitting/merging. This environment, <tt>StateT Params m a</tt>, is an
--   instance of <a>MonadClean</a>.
runCleanT :: (MonadIO m, MonadBaseControl IO m) => CleanT m a -> m a
markForDelete :: MonadClean m => FilePath -> m ()

-- | If this flag is set, imports that become empty are removed. Sometimes
--   this will lead to errors, specifically when an instance in the removed
--   import that was required is no longer be available. (Note that this
--   reflects a limitation of the <tt>-ddump-minimal-imports</tt> option of
--   GHC.) If this happens this flag should be set. Note that an import
--   that is already empty when <tt>cleanImports</tt> runs will never be
--   removed, on the assumption that it was placed there only to import
--   instances. Default is True.
modifyRemoveEmptyImports :: MonadClean m => (Bool -> Bool) -> m ()

-- | Modify the list of extra flags passed to GHC. Default is <tt>[]</tt>.
modifyHsFlags :: MonadClean m => ([String] -> [String]) -> m ()

-- | Controls whether file updates will actually be performed. Default is
--   False. (I recommend running in a directory controlled by a version
--   control system so you don't have to worry about this.)
modifyDryRun :: MonadClean m => (Bool -> Bool) -> m ()

-- | If TestMode is turned on no import cleaning will occur after a split
--   or cat. Default is False. Note that the modules produced with this
--   option will often fail to compile to to circular imports. (Does this
--   seem counterintuitive to anyone else?)
modifyTestMode :: MonadClean m => (Bool -> Bool) -> m ()

-- | When we write module <tt>m</tt>, insert an extra line that imports the
--   instances (only) from module <tt>i</tt>.
extraImport :: MonadClean m => ModuleName -> ModuleName -> m ()
instance Eq Params
instance Ord Params
instance Show Params
instance MonadClean m => MonadDryRun m
instance MonadClean m => MonadVerbosity m
instance (MonadIO m, MonadBaseControl IO m, Functor m) => MonadClean (CleanT m)
instance MonadClean m => ModuVerse m


-- | <a>foldModule</a> is a utility function used to implement the clean,
--   split, and merge operations.
module Language.Haskell.Modules.Fold

-- | Given the result of parseModuleWithComments and the original module
--   text, this does a fold over the parsed module contents, calling the
--   seven argument functions in order. Each function is passed the AST
--   value, the text of the space and comments leading up to the element,
--   and the text for the element. Note that not everything passed to the
--   <a>pre</a> argument of the functions will be comments and space - for
--   example, the <a>module</a> keyword will be passed in the pre argument
--   to the ModuleName function.
foldModule :: Show r => (String -> r -> r) -> (ModulePragma -> String -> String -> String -> r -> r) -> (ModuleName -> String -> String -> String -> r -> r) -> (WarningText -> String -> String -> String -> r -> r) -> (String -> r -> r) -> (ExportSpec -> String -> String -> String -> r -> r) -> (String -> r -> r) -> (ImportDecl -> String -> String -> String -> r -> r) -> (Decl -> String -> String -> String -> r -> r) -> (String -> r -> r) -> ModuleInfo -> r -> r

-- | Do just the header portion of <a>foldModule</a>.
foldHeader :: Show r => (String -> r -> r) -> (ModulePragma -> String -> String -> String -> r -> r) -> (ModuleName -> String -> String -> String -> r -> r) -> (WarningText -> String -> String -> String -> r -> r) -> ModuleInfo -> r -> r

-- | Do just the exports portion of <a>foldModule</a>.
foldExports :: Show r => (String -> r -> r) -> (ExportSpec -> String -> String -> String -> r -> r) -> (String -> r -> r) -> ModuleInfo -> r -> r

-- | Do just the imports portion of <a>foldModule</a>.
foldImports :: Show r => (ImportDecl -> String -> String -> String -> r -> r) -> ModuleInfo -> r -> r

-- | Do just the declarations portion of <a>foldModule</a>.
foldDecls :: Show r => (Decl -> String -> String -> String -> r -> r) -> (String -> r -> r) -> ModuleInfo -> r -> r

-- | This can be passed to foldModule to include the original text in the
--   result
echo :: Monoid m => t -> m -> m -> m -> Seq m -> Seq m

-- | Similar to <a>echo</a>, but used for the two argument separator
--   functions
echo2 :: Monoid m => m -> Seq m -> Seq m

-- | This can be passed to foldModule to omit the original text from the
--   result.
ignore :: t -> m -> m -> m -> r -> r

-- | Similar to <a>ignore</a>, but used for the two argument separator
--   functions
ignore2 :: m -> r -> r
instance Show St
instance Spans (WarningText SrcSpanInfo)
instance Spans (ModuleName SrcSpanInfo)
instance Spans (Decl SrcSpanInfo)
instance Spans (ImportDecl SrcSpanInfo)
instance Spans (ModulePragma SrcSpanInfo)
instance Spans (ExportSpec SrcSpanInfo)
instance Spans (ExportSpecList SrcSpanInfo)
instance Spans (ModuleHead SrcSpanInfo)
instance Spans (Module SrcSpanInfo)

module Language.Haskell.Modules.Common

-- | Combine sortBy and groupBy
groupBy' :: Ord a => (a -> a -> Ordering) -> [a] -> [[a]]

-- | Perform an action with the working directory set to <tt>path</tt>.
withCurrentDirectory :: (MonadIO m, MonadBaseControl IO m) => FilePath -> m a -> m a
data ModuleResult
Unchanged :: ModuleName -> PathKey -> ModuleResult
ToBeRemoved :: ModuleName -> PathKey -> ModuleResult
JustRemoved :: ModuleName -> PathKey -> ModuleResult
ToBeModified :: ModuleName -> PathKey -> String -> ModuleResult
JustModified :: ModuleName -> PathKey -> ModuleResult
ToBeCreated :: ModuleName -> String -> ModuleResult
JustCreated :: ModuleName -> PathKey -> ModuleResult

-- | It is tempting to put import cleaning into these operations, but that
--   needs to be done after all of these operations are completed so that
--   all the compiles required for import cleaning succeed. On the other
--   hand, we might be able to maintain the moduVerse here.
doResult :: (ModuVerse m, MonadDryRun m, MonadVerbosity m) => ModuleResult -> m ModuleResult
reportResult :: ModuleResult -> String

-- | Update an export spec. The only thing we might need to change is
--   re-exports, of the form <a>module Foo</a>.
fixExport :: [ModuleName] -> ModuleName -> ModuleName -> ExportSpec l -> String -> String -> String -> Seq String -> Seq String
instance Show ModuleResult
instance Eq ModuleResult
instance Ord ModuleResult

module Language.Haskell.Modules.Imports

-- | Clean up the imports of a source file. This means:
--   
--   <ul>
--   <li>All import lines get an explict list of symbols</li>
--   <li>Imports of unused symbols are removed</li>
--   <li>Imports of modules whose symbol list becomse empty are removed,
--   unless the <a>removeEmptyImports</a> flag is set to <tt>False</tt>.
--   However, imports that started out with an empty import list
--   <tt>()</tt> are retained</li>
--   <li>Repeated imports are merged</li>
--   <li>Imports are alphabetized by module name</li>
--   <li>Imported symbols are alphabetized by symbol name</li>
--   <li>Imported constructors and field accessors are alphabetized</li>
--   </ul>
cleanImports :: MonadClean m => [FilePath] -> m [ModuleResult]

-- | Do import cleaning in response to the values returned by the split and
--   merge operations. Module import lists are cleaned if the module is
--   modified or created.
cleanResults :: MonadClean m => [ModuleResult] -> m [ModuleResult]

module Language.Haskell.Modules.Merge

-- | Merge the declarations from several modules into a single new one,
--   updating the imports of the modules in the moduVerse to reflect the
--   change. It *is* permissable to use one of the input modules as the
--   output module. Note that circular imports can be created by this
--   operation.
mergeModules :: MonadClean m => [ModuleName] -> ModuleName -> m [ModuleResult]

module Language.Haskell.Modules.Split

-- | Split the declarations of the module in the input file into new
--   modules as specified by the <tt>symToModule</tt> function, which maps
--   symbol name's to module names. It is permissable for the output
--   function to map one or more symbols to the original module. The
--   modules will be written into files whose names are constructed from
--   the module name in the usual way, but with a prefix taken from the
--   first element of the list of directories in the <tt>SourceDirs</tt>
--   list. This list is just <tt>[<a>.</a>]</tt> by default.
splitModule :: MonadClean m => (Maybe Name -> ModuleName) -> FilePath -> m [ModuleResult]

-- | Split each of a module's declarations into a new module. Update the
--   imports of all the modules in the moduVerse to reflect the split. For
--   example, if you have a module like
--   
--   <pre>
--   module Start (a, b, (.+.)) where
--   import
--   a = 1 + a
--   b = 2
--   c = 3
--   c' = 4
--   (.+.) = b + c
--   </pre>
--   
--   After running <tt>splitModuleDecls <a>Start.hs</a></tt> the
--   <tt>Start</tt> module will be gone. The <tt>a</tt> and <tt>b</tt>
--   symbols will be in new modules named <tt>Start.A</tt> and
--   <tt>Start.B</tt>. Because they were not exported by <tt>Start</tt>,
--   the <tt>c</tt> and <tt>c'</tt> symbols will both be in a new module
--   named <tt>Start.Internal.C</tt>. And the <tt>.+.</tt> symbol will be
--   in a module named <tt>Start.OtherSymbols</tt>. Note that this module
--   needs to import new <tt>Start.A</tt> and <tt>Start.Internal.C</tt>
--   modules.
--   
--   If we had imported and then re-exported a symbol in Start it would go
--   into a module named <tt>Start.ReExported</tt>. Any instance
--   declarations would go into <tt>Start.Instances</tt>.
splitModuleDecls :: MonadClean m => FilePath -> m [ModuleResult]

-- | This can be used to build the function parameter of
--   <a>splitModule</a>, it determines which module should a symbol be
--   moved to.
defaultSymbolToModule :: ModuleInfo -> Maybe Name -> ModuleName
instance Eq DeclClass
instance Ord DeclClass
instance Show DeclClass
instance Default ImportDecl


-- | This package provides functions to clean import lists, to split up
--   modules, and to merge modules. The important entry points are:
--   
--   There are several features worth noting. The <tt>Params</tt> type in
--   the state of <a>MonadClean</a> has a <tt>removeEmptyImports</tt>
--   field, which is True by default. This determines whether imports that
--   turn into empty lists are preserved or not - if your program needs
--   instances from a such an import, you will either want to set this flag
--   to False or (better) add an empty import list to the import.
--   
--   These are the important entry points:
--   
--   <ul>
--   <li><a>runCleanT</a> - Sets up the environment for splitting and
--   merging. These operations require updates to be made to all the
--   modules that import the modules being split or merged, so this
--   environment tracks the creation and removal of modules. This allows a
--   sequence of splits and merges to be performed without forgetting to
--   update newly created modules.</li>
--   <li><a>cleanImports</a> - uses ghc's -ddump-minimal-imports flag to
--   generate minimized and explicit imports and re-insert them into the
--   module.</li>
--   <li><a>splitModule</a> - Splits a module into two or more parts
--   according to the argument function.</li>
--   <li><a>splitModuleDecls</a> - Calls <a>splitModule</a> with a default
--   first argument. Each declaration goes into a different module, and
--   separate modules are created for instances and re-exports. Decls that
--   were local to the original module go into a subdirectory named
--   <tt>Internal</tt>. Symbols which can't be turned into valid module
--   names go into <tt>OtherSymbols</tt>.</li>
--   <li><a>mergeModules</a> - the inverse operation of <a>splitModule</a>,
--   it merges two or more modules into a new or existing module, updating
--   imports of the moduVerse elements as necessary.</li>
--   </ul>
--   
--   Examples:
--   
--   <ul>
--   <li>Use <a>findHsFiles</a> and <a>cleanImports</a> to clean up the
--   import lists of all the modules under <tt>./Language</tt>:</li>
--   </ul>
--   
--   <pre>
--   findHsFiles ["Language", "Tests.hs", "Tests"] &gt;&gt;= runCleanT . cleanImports
--   </pre>
--   
--   <ul>
--   <li>Split the module <tt>Language.Haskell.Modules.Common</tt>, and
--   then merge two of the declarations back in:</li>
--   </ul>
--   
--   <pre>
--   :m +Language.Haskell.Exts.Syntax
--       findHsModules ["Language", "Tests.hs", "Tests"] &gt;&gt;= \ modules -&gt; runCleanT $
--         mapM putModule modules &gt;&gt;
--         splitModuleDecls "Language/Haskell/Modules/Common.hs" &gt;&gt;
--         mergeModules [ModuleName "Language.Haskell.Modules.Common.WithCurrentDirectory",
--                       ModuleName "Language.Haskell.Modules.Common.Internal.ToEq"]
--                      (ModuleName "Language.Haskell.Modules.Common")
--   </pre>
--   
--   <ul>
--   <li>Move two declarations from Internal to Common. The intermediate
--   module <tt>Tmp</tt> is used because using existing modules for a split
--   is not allowed. The exception to this is that you can leave
--   declarations in the original module.</li>
--   </ul>
--   
--   <pre>
--   findHsModules ["Language", "Tests.hs", "Tests"] &gt;&gt;= \ modules -&gt; runCleanT $
--         mapM putModule modules &gt;&gt;
--         splitModule (\ n -&gt; if elem n [Just (Ident "ModuleResult"), Just (Ident "doResult")]
--                             then ModuleName "Tmp"
--                             else ModuleName "Language.Haskell.Modules.Internal")
--                     (ModuleName "Language/Haskell/Modules/Internal.hs") &gt;&gt;
--         mergeModules [ModuleName "Language.Haskell.Modules.Common", ModuleName "Tmp"]
--                      (ModuleName "Language.Haskell.Modules.Common")
--   </pre>
--   
--   <ul>
--   <li>Split a module where one of the result modules needs to import the
--   instances:</li>
--   </ul>
--   
--   <pre>
--   runCleanT $
--         putModule (ModuleName "Main") &gt;&gt;
--         extraImport (ModuleName "Main.GetPasteById") (ModuleName "Main.Instances") &gt;&gt;
--         splitModuleDecls "Main.hs"
--   </pre>
module Language.Haskell.Modules

-- | Clean up the imports of a source file. This means:
--   
--   <ul>
--   <li>All import lines get an explict list of symbols</li>
--   <li>Imports of unused symbols are removed</li>
--   <li>Imports of modules whose symbol list becomse empty are removed,
--   unless the <a>removeEmptyImports</a> flag is set to <tt>False</tt>.
--   However, imports that started out with an empty import list
--   <tt>()</tt> are retained</li>
--   <li>Repeated imports are merged</li>
--   <li>Imports are alphabetized by module name</li>
--   <li>Imported symbols are alphabetized by symbol name</li>
--   <li>Imported constructors and field accessors are alphabetized</li>
--   </ul>
cleanImports :: MonadClean m => [FilePath] -> m [ModuleResult]

-- | Split the declarations of the module in the input file into new
--   modules as specified by the <tt>symToModule</tt> function, which maps
--   symbol name's to module names. It is permissable for the output
--   function to map one or more symbols to the original module. The
--   modules will be written into files whose names are constructed from
--   the module name in the usual way, but with a prefix taken from the
--   first element of the list of directories in the <tt>SourceDirs</tt>
--   list. This list is just <tt>[<a>.</a>]</tt> by default.
splitModule :: MonadClean m => (Maybe Name -> ModuleName) -> FilePath -> m [ModuleResult]

-- | Split each of a module's declarations into a new module. Update the
--   imports of all the modules in the moduVerse to reflect the split. For
--   example, if you have a module like
--   
--   <pre>
--   module Start (a, b, (.+.)) where
--   import
--   a = 1 + a
--   b = 2
--   c = 3
--   c' = 4
--   (.+.) = b + c
--   </pre>
--   
--   After running <tt>splitModuleDecls <a>Start.hs</a></tt> the
--   <tt>Start</tt> module will be gone. The <tt>a</tt> and <tt>b</tt>
--   symbols will be in new modules named <tt>Start.A</tt> and
--   <tt>Start.B</tt>. Because they were not exported by <tt>Start</tt>,
--   the <tt>c</tt> and <tt>c'</tt> symbols will both be in a new module
--   named <tt>Start.Internal.C</tt>. And the <tt>.+.</tt> symbol will be
--   in a module named <tt>Start.OtherSymbols</tt>. Note that this module
--   needs to import new <tt>Start.A</tt> and <tt>Start.Internal.C</tt>
--   modules.
--   
--   If we had imported and then re-exported a symbol in Start it would go
--   into a module named <tt>Start.ReExported</tt>. Any instance
--   declarations would go into <tt>Start.Instances</tt>.
splitModuleDecls :: MonadClean m => FilePath -> m [ModuleResult]

-- | This can be used to build the function parameter of
--   <a>splitModule</a>, it determines which module should a symbol be
--   moved to.
defaultSymbolToModule :: ModuleInfo -> Maybe Name -> ModuleName

-- | Merge the declarations from several modules into a single new one,
--   updating the imports of the modules in the moduVerse to reflect the
--   change. It *is* permissable to use one of the input modules as the
--   output module. Note that circular imports can be created by this
--   operation.
mergeModules :: MonadClean m => [ModuleName] -> ModuleName -> m [ModuleResult]
class (MonadIO m, MonadBaseControl IO m, Functor m) => MonadClean m

-- | An instance of MonadClean.
type CleanT m = StateT Params m

-- | Create the environment required to do import cleaning and module
--   splitting/merging. This environment, <tt>StateT Params m a</tt>, is an
--   instance of <a>MonadClean</a>.
runCleanT :: (MonadIO m, MonadBaseControl IO m) => CleanT m a -> m a
putModule :: (ModuVerse m, MonadVerbosity m) => ModuleName -> m ()
findModule :: (ModuVerse m, MonadVerbosity m) => ModuleName -> m (Maybe ModuleInfo)

-- | Controls whether file updates will actually be performed. Default is
--   False. (I recommend running in a directory controlled by a version
--   control system so you don't have to worry about this.)
modifyDryRun :: MonadClean m => (Bool -> Bool) -> m ()

-- | Modify the list of extra flags passed to GHC. Default is <tt>[]</tt>.
modifyHsFlags :: MonadClean m => ([String] -> [String]) -> m ()

-- | If this flag is set, imports that become empty are removed. Sometimes
--   this will lead to errors, specifically when an instance in the removed
--   import that was required is no longer be available. (Note that this
--   reflects a limitation of the <tt>-ddump-minimal-imports</tt> option of
--   GHC.) If this happens this flag should be set. Note that an import
--   that is already empty when <tt>cleanImports</tt> runs will never be
--   removed, on the assumption that it was placed there only to import
--   instances. Default is True.
modifyRemoveEmptyImports :: MonadClean m => (Bool -> Bool) -> m ()

-- | Modify the list of extensions passed to GHC when dumping the minimal
--   imports. Note that GHC will also use the extensions in the module's
--   LANGUAGE pragma, so this can usually be left alone.
modifyExtensions :: ModuVerse m => ([Extension] -> [Extension]) -> m ()

-- | If TestMode is turned on no import cleaning will occur after a split
--   or cat. Default is False. Note that the modules produced with this
--   option will often fail to compile to to circular imports. (Does this
--   seem counterintuitive to anyone else?)
modifyTestMode :: MonadClean m => (Bool -> Bool) -> m ()

-- | Modify the list of directories that will be searched for imported
--   modules.
modifyDirs :: SourceDirs m => ([FilePath] -> [FilePath]) -> m ()

-- | Set the list of directories that will be searched for imported
--   modules. Similar to the Hs-Source-Dirs field in the cabal file.
putDirs :: SourceDirs m => [FilePath] -> m ()

-- | When we write module <tt>m</tt>, insert an extra line that imports the
--   instances (only) from module <tt>i</tt>.
extraImport :: MonadClean m => ModuleName -> ModuleName -> m ()

-- | Increase the amount of progress reporting during an action.
noisily :: MonadVerbosity m => m a -> m a

-- | Decrease the amount of progress reporting during an action.
quietly :: MonadVerbosity m => m a -> m a

-- | The name of a Haskell module.
newtype ModuleName :: *
ModuleName :: String -> ModuleName

-- | This type is used to represent variables, and also constructors.
data Name :: *

-- | <i>varid</i> or <i>conid</i>.
Ident :: String -> Name

-- | <i>varsym</i> or <i>consym</i>
Symbol :: String -> Name
modulePathBase :: String -> ModuleName -> RelPath

-- | Convenience function for building the moduVerse, searches for modules
--   in a directory hierarchy. FIXME: This should be in MonadClean and use
--   the value of sourceDirs to remove prefixes from the module paths. And
--   then it should look at the module text to see what the module name
--   really is.
findHsModules :: [FilePath] -> IO [ModuleName]

-- | Find the paths of all the files below the directory <tt>top</tt>.
findHsFiles :: [FilePath] -> IO [FilePath]

-- | Perform an action with the working directory set to <tt>path</tt>.
withCurrentDirectory :: (MonadIO m, MonadBaseControl IO m) => FilePath -> m a -> m a