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


-- | Parse Haskell Language Extensions
--   
--   Parse Haskell Language Extensions. See <a>README.md</a> for more
--   details.
@package extensions
@version 0.0.0.0


-- | Data types and functions to work with different types of
--   <a>Extension</a>s.
--   
--   <tt>extensions</tt> library supports the following types of
--   extensions:
--   
--   TODO: table
module Extensions.Types

-- | Main returned data type that includes merged <a>OnOffExtension</a>s
--   and possibly one <a>SafeHaskellExtension</a>.
data Extensions
Extensions :: !Set OnOffExtension -> !Maybe SafeHaskellExtension -> Extensions
[extensionsAll] :: Extensions -> !Set OnOffExtension
[extensionsSafe] :: Extensions -> !Maybe SafeHaskellExtension

-- | Extensions that are collected in the result of parsing <tt>.cabal</tt>
--   file or Haskell module (both <a>OnOffExtension</a> and possibly one
--   <a>SafeHaskellExtension</a>).
--   
--   <a>OnOffExtension</a>s are not necessary unique. They reflect exactly
--   the extensions found during parsing.
data ParsedExtensions
ParsedExtensions :: ![OnOffExtension] -> !Maybe SafeHaskellExtension -> ParsedExtensions
[parsedExtensionsAll] :: ParsedExtensions -> ![OnOffExtension]
[parsedExtensionsSafe] :: ParsedExtensions -> !Maybe SafeHaskellExtension

-- | Stores extensions from <tt>.cabal</tt> file and module separately.
data CabalAndModuleExtensions
CabalAndModuleExtensions :: !ParsedExtensions -> !ParsedExtensions -> CabalAndModuleExtensions
[cabalExtensions] :: CabalAndModuleExtensions -> !ParsedExtensions
[moduleExtensions] :: CabalAndModuleExtensions -> !ParsedExtensions

-- | Type alias for the result of extensions analysis.
type ExtensionsResult = Either ExtensionsError Extensions

-- | Represents possible errors during the work of extensions analyser.
data ExtensionsError

-- | Parse error during module extensions parsing.
ModuleParseError :: FilePath -> ModuleParseError -> ExtensionsError

-- | Error during <tt>.cabal</tt> file reading/parsing.
CabalError :: CabalException -> ExtensionsError

-- | File is in cabal file, but the source file is not provided where
--   requested.
SourceNotFound :: FilePath -> ExtensionsError

-- | Source file is provided, but module is not in cabal file.
NotCabalModule :: FilePath -> ExtensionsError

-- | Conflicting <a>SafeHaskellExtension</a>s in one scope.
SafeHaskellConflict :: NonEmpty SafeHaskellExtension -> ExtensionsError

-- | Exception that gets thrown when working with <tt>.cabal</tt> files.
data CabalException

-- | The <tt>.cabal</tt> file is not found.
CabalFileNotFound :: FilePath -> CabalException

-- | Parsing errors in the <tt>.cabal</tt> file.
CabalParseError :: Text -> CabalException

-- | Conflicting <a>SafeHaskellExtension</a>s in one scope.
CabalSafeExtensionsConflict :: NonEmpty SafeHaskellExtension -> CabalException

-- | Error while parsing Haskell source file.
data ModuleParseError

-- | File parsing error.
ParsecError :: ParseError -> ModuleParseError

-- | Uknown extensions were used in the module.
UnknownExtensions :: NonEmpty String -> ModuleParseError

-- | Conflicting <a>SafeHaskellExtension</a>s in one scope.
ModuleSafeHaskellConflict :: NonEmpty SafeHaskellExtension -> ModuleParseError

-- | Module file not found.
FileNotFound :: FilePath -> ModuleParseError

-- | Empty <a>Extensions</a> with no specified <a>SafeHaskellExtension</a>.
emptyExtensions :: Extensions

-- | Empty <a>ParsedExtensions</a> with no specified
--   <a>SafeHaskellExtension</a>.
emptyParsedExtensions :: ParsedExtensions

-- | Represents enabled/disabled extensions.
data OnOffExtension
On :: Extension -> OnOffExtension
Off :: Extension -> OnOffExtension

-- | Display <a>OnOffExtension</a> as GHC recognizes it.
showOnOffExtension :: OnOffExtension -> Text

-- | Parse <a>OnOffExtension</a> from a string that specifies extension.
readOnOffExtension :: String -> Maybe OnOffExtension

-- | Parse <a>Extension</a> from a string. <a>Read</a> instance for
--   <a>Extension</a> doesn't always work since some extensions are named
--   differently.
readExtension :: String -> Maybe Extension

-- | Take accumulated <a>OnOffExtension</a>s, and merge them into one
--   <a>Set</a>, excluding enabling of <a>default2010Extensions</a>.
--   
--   If the default extension is enabled manually it still won't count as
--   it doesn't affect real behaviour. However, disabling of default
--   extension will be included in the list.
--   
--   So, basically, this set will only have <a>On</a> extensions that are
--   not defaults, and <a>Off</a> extensions of defaults.
--   
--   'foldl'' is used in order to process them in the right order: first
--   all cabal extensions and then extensions from the module in the order
--   of appearance.
mergeExtensions :: [OnOffExtension] -> Set OnOffExtension

-- | Similar to <a>mergeExtensions</a>, but also merge
--   <a>SafeHaskellExtension</a>s. In case of conflicting
--   <a>SafeHaskellExtension</a> returns <a>Left</a> with the pair of
--   conflicting extension constructors under <a>SafeHaskellConflict</a>
--   error.
mergeAnyExtensions :: ParsedExtensions -> ParsedExtensions -> ExtensionsResult

-- | Default enabled extensions for <tt>Haskell2010</tt>
default2010Extensions :: [Extension]

-- | Language extensions that are used by Safe Haskell to indicate safety
--   of the code.
--   
--   To find out more, checkout the official documentation on
--   <tt>SafeHaskell</tt>:
--   
--   <ul>
--   <li><a>Safe Language Pragmas</a></li>
--   </ul>
data SafeHaskellExtension
Unsafe :: SafeHaskellExtension
Trustworthy :: SafeHaskellExtension
Safe :: SafeHaskellExtension
instance GHC.Classes.Eq Extensions.Types.Extensions
instance GHC.Show.Show Extensions.Types.Extensions
instance GHC.Classes.Eq Extensions.Types.CabalAndModuleExtensions
instance GHC.Show.Show Extensions.Types.CabalAndModuleExtensions
instance GHC.Classes.Eq Extensions.Types.ParsedExtensions
instance GHC.Show.Show Extensions.Types.ParsedExtensions
instance GHC.Classes.Ord Extensions.Types.OnOffExtension
instance GHC.Classes.Eq Extensions.Types.OnOffExtension
instance GHC.Show.Show Extensions.Types.OnOffExtension
instance GHC.Classes.Eq Extensions.Types.ExtensionsError
instance GHC.Show.Show Extensions.Types.ExtensionsError
instance GHC.Exception.Type.Exception Extensions.Types.CabalException
instance GHC.Classes.Eq Extensions.Types.CabalException
instance GHC.Show.Show Extensions.Types.CabalException
instance GHC.Classes.Eq Extensions.Types.ModuleParseError
instance GHC.Show.Show Extensions.Types.ModuleParseError
instance GHC.Enum.Bounded Extensions.Types.SafeHaskellExtension
instance GHC.Enum.Enum Extensions.Types.SafeHaskellExtension
instance GHC.Classes.Ord Extensions.Types.SafeHaskellExtension
instance GHC.Classes.Eq Extensions.Types.SafeHaskellExtension
instance GHC.Read.Read Extensions.Types.SafeHaskellExtension
instance GHC.Show.Show Extensions.Types.SafeHaskellExtension
instance GHC.Read.Read GHC.LanguageExtensions.Type.Extension
instance GHC.Classes.Ord GHC.LanguageExtensions.Type.Extension


-- | Parser for Haskell Modules to get all Haskell Language Extensions
--   used.
module Extensions.Module

-- | By the given file path, reads the file and returns
--   <a>ParsedExtensions</a>, if parsing succeeds.
parseFile :: FilePath -> IO (Either ModuleParseError ParsedExtensions)

-- | By the given file source content, returns <a>ParsedExtensions</a>, if
--   parsing succeeds.
parseSource :: ByteString -> Either ModuleParseError ParsedExtensions

-- | By the given file path and file source content, returns
--   <a>ParsedExtensions</a>, if parsing succeeds.
--   
--   This function takes a path to a Haskell source file. The path is only
--   used for error message. Pass empty string or use <a>parseSource</a>,
--   if you don't have a path to a Haskell module.
parseSourceWithPath :: FilePath -> ByteString -> Either ModuleParseError ParsedExtensions

-- | The main parser of <a>ParsedExtension</a>.
--   
--   It parses language pragmas or comments until end of file or the first
--   line with the function<i>import</i>module name.
extensionsP :: Parser [ParsedExtension]

-- | Single LANGUAGE pragma parser.
--   
--   <pre>
--   {-# LANGUAGE XXX
--    , YYY ,
--    ZZZ
--   #-}
--   </pre>
singleExtensionsP :: Parser [ParsedExtension]

-- | Parses all known and unknown <a>OnOffExtension</a>s or
--   <a>SafeHaskellExtension</a>s.
extensionP :: Parser ParsedExtension

-- | Parser for standard language pragma keywords: <tt>{-# LANGUAGE XXX
--   #-}</tt>
languagePragmaP :: Parser a -> Parser a

-- | Parser for GHC options pragma keywords: <tt>{-# OPTIONS_GHC YYY
--   #-}</tt>
optionsGhcP :: Parser [a]

-- | Parser for GHC pragmas with a given pragma word.
pragmaP :: Parser () -> Parser a -> Parser a

-- | Haskell comment parser. Supports both single-line comments:
--   
--   <pre>
--   -- I am a single comment
--   
--   </pre>
--   
--   and multi-line comments:
--   
--   <pre>
--   {- I
--   AM
--   MULTILINE
--   -}
--   
--   </pre>
commentP :: Parser [a]

-- | CPP syntax parser.
--   
--   <pre>
--   #if __GLASGOW_HASKELL__ &lt; 810
--   -- Could be more Language pragmas that should be parsed
--   #endif
--   
--   </pre>
cppP :: Parser [a]


-- | Functions to extract extensions from the <tt>.cabal</tt> files.
module Extensions.Cabal

-- | Parse default extensions from a <tt>.cabal</tt> file under given
--   <a>FilePath</a>.
--   
--   <b>Throws</b>:
--   
--   <ul>
--   <li><a>CabalException</a></li>
--   </ul>
parseCabalFileExtensions :: FilePath -> IO (Map FilePath ParsedExtensions)

-- | Parse default extensions from a <tt>.cabal</tt> file content. This
--   function takes a path to a <tt>.cabal</tt> file. The path is only used
--   for error message. Pass empty string, if you don't have a path to
--   <tt>.cabal</tt> file.
--   
--   <b>Throws</b>:
--   
--   <ul>
--   <li><a>CabalException</a></li>
--   </ul>
parseCabalExtensions :: FilePath -> ByteString -> IO (Map FilePath ParsedExtensions)

-- | Extract Haskell Language extensions from a Cabal package description.
extractCabalExtensions :: GenericPackageDescription -> IO (Map FilePath ParsedExtensions)

-- | Convert <a>Extension</a> to <a>OnOffExtension</a> or
--   <a>SafeHaskellExtension</a>.
cabalToGhcExtension :: Extension -> Maybe (Either SafeHaskellExtension OnOffExtension)

-- | Convert <a>KnownExtension</a> to <a>OnOffExtension</a>.
toGhcExtension :: KnownExtension -> Maybe Extension

-- | Convert <a>KnownExtension</a> to <a>SafeHaskellExtension</a>.
toSafeExtensions :: KnownExtension -> Maybe SafeHaskellExtension


-- | Parse Haskell Language Extensions.
module Extensions.Package

-- | By given path to <tt>.cabal</tt> file, analyse extensions for each
--   Haskell module and return the corresponding <a>Map</a> with
--   <a>ExtensionsResult</a>s.
--   
--   <b>Throws</b>:
--   
--   <ul>
--   <li><a>CabalException</a></li>
--   </ul>
getPackageExtentions :: FilePath -> IO (Map FilePath ExtensionsResult)

-- | By given path to <tt>.cabal</tt> file and <a>Map</a> of sources of all
--   Haskell modules, analyse extensions for each Haskell module and return
--   the corresponding <a>Map</a> with <a>ExtensionsResult</a>s.
getPackageExtentionsBySources :: FilePath -> Map FilePath ByteString -> IO (Map FilePath ExtensionsResult)

-- | By given path to <tt>.cabal</tt> file and path to Haskell module of
--   the corresponding package, analyse and return extensions for the given
--   module separately from .cabal file and from the module itself.
getModuleAndCabalExtentions :: FilePath -> FilePath -> IO (Either ExtensionsError CabalAndModuleExtensions)

-- | By given path to <tt>.cabal</tt> file and path to Haskell module of
--   the corresponding package, analyse and return summary set of
--   extensions for the given module.
getModuleExtentions :: FilePath -> FilePath -> IO ExtensionsResult

-- | By given path to <tt>.cabal</tt> file and path to Haskell module of
--   the corresponding package, analyse and return extensions extensions
--   for the given module separately from .cabal file and from the module
--   itself.
getModuleAndCabalExtentionsBySource :: FilePath -> FilePath -> ByteString -> IO (Either ExtensionsError CabalAndModuleExtensions)

-- | By given path to <tt>.cabal</tt> file and path to Haskell module of
--   the corresponding package, analyse and return combined set of
--   extensions for the given module.
getModuleExtentionsBySource :: FilePath -> FilePath -> ByteString -> IO ExtensionsResult


-- | Library to get Haskell Language Extensions from <tt>.cabal</tt> files,
--   Haskell Modules, or get combined information from both sources
--   preserving correct merge logic of extensions.
module Extensions