-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Haskell IDE library -- -- Scion is a Haskell library that aims to implement those parts of a -- Haskell IDE which are independent of a particular front-end. Scion is -- based on the GHC API and Cabal. It provides both a Haskell API and a -- server for non-Haskell clients such as Emacs and Vim. -- -- See the homepage (http:code.google.compscion-lib/) and -- the README -- (http:github.comnominoloscionblobmaster/README.markdown) -- for more information. @package scion @version 0.1 -- | Notes, i.e., warnings, errors, etc. module Scion.Types.Notes -- | Scion's type for source code locations (regions). -- -- We use a custom location type for two reasons: -- -- 1. We enforce the invariant, that the file path of the location is an -- absolute path. -- -- 2. Independent evolution from the GHC API. -- -- To save space, the Location type is kept abstract and uses -- special cases for notes that span only one line or are only one -- character wide. Use mkLocation and viewLoc as well as -- the respective accessor functions to construct and destruct nodes. -- -- If no reasonable can be given, use the mkNoLoc function, but be -- careful not to call viewLoc or any other accessor function on -- such a Location. data Location -- | The "source" of a location. data LocSource -- | The location refers to a position in a file. FileSrc :: AbsFilePath -> LocSource -- | The location refers to something else, e.g., the command line, or -- stdin. OtherSrc :: String -> LocSource -- | Construct a source code location from start and end point. -- -- If the start point is after the end point, they are swapped -- automatically. mkLocation :: LocSource -> Int -> Int -> Int -> Int -> Location -- | Construct a source location that does not specify a region. The -- argument can be used to give some hint as to why there is no location -- available. (E.g., "File not found"). mkNoLoc :: String -> Location locSource :: Location -> LocSource -- | Test whether a location is valid, i.e., not constructed with -- mkNoLoc. isValidLoc :: Location -> Bool noLocText :: Location -> String -- | View on a (valid) location. -- -- It holds the property: -- -- 
--   prop_viewLoc_mkLoc s l0 c0 l1 c1 =
--       viewLoc (mkLocation s l0 c0 l1 c1) == (s, l0, c0, l1, c1)
--
viewLoc :: Location -> (LocSource, Int, Int, Int, Int) -- | Return the start column. Only defined on valid locations. locStartCol :: Location -> Int -- | Return the end column. Only defined on valid locations. locEndCol :: Location -> Int -- | Return the start line. Only defined on valid locations. locStartLine :: Location -> Int -- | Return the end line. Only defined on valid locations. locEndLine :: Location -> Int -- | Represents a FilePath which we know is absolute. -- -- Since relative FilePaths depend on the a current working -- directory we normalise all paths to absolute paths. Use -- mkAbsFilePath to create absolute file paths. data AbsFilePath -- | Create an absolute file path given a base directory. -- -- Throws an error if the first argument is not an absolute path. mkAbsFilePath :: FilePath -> FilePath -> AbsFilePath -- | A note from the compiler or some other tool. data Note Note :: NoteKind -> Location -> String -> Note noteKind :: Note -> NoteKind noteLoc :: Note -> Location noteMessage :: Note -> String -- | Classifies the kind (or severity) of a note. data NoteKind ErrorNote :: NoteKind WarningNote :: NoteKind InfoNote :: NoteKind OtherNote :: NoteKind type Notes = MultiSet Note -- | Convert a SrcSpan to a Location. -- -- The first argument is used to normalise relative source locations to -- an absolute file path. ghcSpanToLocation :: FilePath -> SrcSpan -> Location ghcErrMsgToNote :: FilePath -> ErrMsg -> Note ghcWarnMsgToNote :: FilePath -> WarnMsg -> Note -- | Convert Messages to Notes. -- -- This will mix warnings and errors, but you can split them back up by -- filtering the Notes based on the noteKind. ghcMessagesToNotes :: FilePath -> Messages -> Notes instance Eq LocSource instance Ord LocSource instance Show LocSource instance Eq Location instance Show Location instance Eq AbsFilePath instance Ord AbsFilePath instance Eq NoteKind instance Ord NoteKind instance Show NoteKind instance Eq Note instance Ord Note instance Show Note instance Ord Location instance Show AbsFilePath module Scion.Types.ExtraInstances instance Foldable Bag instance Functor Bag instance Monoid (Bag a) -- | Types used throughout Scion. module Scion.Types data SessionState SessionState :: Verbosity -> DynFlags -> Maybe LocalBuildInfo -> Maybe Component -> CompilationResult -> Maybe ModSummary -> Maybe BgTcCache -> DefSiteDB -> String -> SessionState scionVerbosity :: SessionState -> Verbosity -- | The DynFlags as they were when Scion was started. This is used to -- reset flags when opening a new project. Arguably, the GHC API should -- provide calls to reset a session. initialDynFlags :: SessionState -> DynFlags -- | Build info from current Cabal project. localBuildInfo :: SessionState -> Maybe LocalBuildInfo -- | The current active Cabal component. This affects DynFlags and targets. -- ATM, we don't support multiple active components. activeComponent :: SessionState -> Maybe Component lastCompResult :: SessionState -> CompilationResult -- | The currently focused module for background typechecking. focusedModule :: SessionState -> Maybe ModSummary -- | Cached state of the background typechecker. bgTcCache :: SessionState -> Maybe BgTcCache -- | Source code locations. defSiteDB :: SessionState -> DefSiteDB -- | can be set by the client. Only used by vim to enable special hack client :: SessionState -> String mkSessionState :: DynFlags -> IO (IORef SessionState) newtype ScionM a ScionM :: (IORef SessionState -> Ghc a) -> ScionM a unScionM :: ScionM a -> IORef SessionState -> Ghc a liftScionM :: Ghc a -> ScionM a modifySessionState :: (SessionState -> SessionState) -> ScionM () getSessionState :: ScionM SessionState gets :: (SessionState -> a) -> ScionM a setSessionState :: SessionState -> ScionM () data Verbosity Silent :: Verbosity Normal :: Verbosity Verbose :: Verbosity Deafening :: Verbosity intToVerbosity :: Int -> Verbosity verbosityToInt :: Verbosity -> Int silent :: Verbosity normal :: Verbosity verbose :: Verbosity deafening :: Verbosity getVerbosity :: ScionM Verbosity setVerbosity :: Verbosity -> ScionM () message :: Verbosity -> String -> ScionM () -- | Reflect a computation in the ScionM monad into the IO -- monad. reflectScionM :: ScionM a -> (IORef SessionState, Session) -> IO a -- | Dual to reflectScionM. See its documentation. reifyScionM :: ((IORef SessionState, Session) -> IO a) -> ScionM a data BgTcCache Parsed :: ParsedModule -> BgTcCache Typechecked :: TypecheckedModule -> BgTcCache data CompilationResult CompilationResult :: Bool -> MultiSet Note -> NominalDiffTime -> CompilationResult compilationSucceeded :: CompilationResult -> Bool compilationNotes :: CompilationResult -> MultiSet Note compilationTime :: CompilationResult -> NominalDiffTime -- | Any exception raised inside Scion is a subtype of this exception. data SomeScionException SomeScionException :: e -> SomeScionException scionToException :: (Exception e) => e -> SomeException scionFromException :: (Exception e) => SomeException -> Maybe e -- | A fatal error. Like error but suggests submitting a bug report. dieHard :: String -> a data Component Library :: Component Executable :: String -> Component File :: FilePath -> Component -- | Shorthand for undefined. __ :: a -- | A definition site database. -- -- This is a map from names to the location of their definition and -- information about the defined entity. Note that a name may refer to -- multiple entities. -- -- XXX: Currently we use GHC's TyThing data type. However, this -- probably holds on to a lot of stuff we don't need. It also cannot be -- serialised directly. The reason it's done this way is that wrapping -- TyThing leads to a lot of duplicated code. Using a custom type -- might be useful to have fewer dependencies on the GHC API; however it -- also creates problems mapping things back into GHC API data -- structures. If we do this, we should at least remember the Unique in -- order to quickly look up the original thing. newtype DefSiteDB DefSiteDB :: (Map String [(Location, TyThing)]) -> DefSiteDB -- | The empty DefSiteDB. emptyDefSiteDB :: DefSiteDB -- | Combine two DefSiteDBs. XXX: check for duplicates? unionDefSiteDB :: DefSiteDB -> DefSiteDB -> DefSiteDB -- | Return the list of defined names (the domain) of the DefSiteDB. -- The result is, in fact, ordered. definedNames :: DefSiteDB -> [String] -- | Returns all the entities that the given name may refer to. lookupDefSite :: DefSiteDB -> String -> [(Location, TyThing)] data ScionError ScionError :: String -> ScionError scionError :: String -> ScionM a data CabalConfiguration CabalConfiguration :: FilePath -> [String] -> CabalConfiguration distDir :: CabalConfiguration -> FilePath extraArgs :: CabalConfiguration -> [String] type FileComponentConfiguration = (FilePath, [String]) data ScionProjectConfig ScionProjectConfig :: [CabalConfiguration] -> [FileComponentConfiguration] -> Maybe String -> ScionProjectConfig buildConfigurations :: ScionProjectConfig -> [CabalConfiguration] fileComponentExtraFlags :: ScionProjectConfig -> [FileComponentConfiguration] scionDefaultCabalConfig :: ScionProjectConfig -> Maybe String emptyScionProjectConfig :: ScionProjectConfig instance Typeable ScionError instance Typeable Component instance Typeable SomeScionException instance Show ScionError instance Eq Component instance Show Component instance Eq Verbosity instance Ord Verbosity instance Show Verbosity instance Enum Verbosity instance Bounded Verbosity instance Exception ScionError instance Monoid DefSiteDB instance Exception SomeScionException instance Show SomeScionException instance Monoid CompilationResult instance GhcMonad ScionM instance WarnLogMonad ScionM instance ExceptionMonad ScionM instance MonadIO ScionM instance Applicative ScionM instance Functor ScionM instance Monad ScionM -- | Collecting and finding the definition site of an identifier. -- -- This module analyses Haskell code to find the definition sites of -- identifiers within. module Scion.Inspect.DefinitionSite -- | Construct a DefSiteDB for a complete module graph. -- -- Note: All the modules mentioned in the module graph must have been -- loaded. This is done either by a successful call to load or by -- a call to loadModule for each module (in dependency order). moduleGraphDefSiteDB :: FilePath -> ModuleGraph -> ScionM DefSiteDB -- | Construct a DefSiteDB for a single module only. moduleSiteDB :: (FilePath, Module) -> ScionM DefSiteDB -- | Construct a SiteDB from a base directory and a list of -- TyThings. mkSiteDB :: FilePath -> [TyThing] -> DefSiteDB addToDB :: String -> Location -> TyThing -> DefSiteDB -> DefSiteDB -- | Dump a definition site DB to stdout. (For debugging purposes.) dumpDefSiteDB :: DefSiteDB -> String -- | Various utilities. module Scion.Utils thingsAroundPoint :: (Int, Int) -> [Located n] -> [Located n] modulesInDepOrder :: (GhcMonad m) => m [ModSummary] foldModSummaries :: (GhcMonad m) => (a -> ModSummary -> m a) -> a -> m a expectJust :: String -> Maybe a -> a unqualifiedForModule :: (TypecheckedMod m) => m -> ScionM PrintUnqualified second :: (a -> b) -> (c, a) -> (c, b) ifM :: (Monad m) => m Bool -> m a -> m a -> m a lookupKey :: (JSON a) => JSObject JSValue -> String -> Result a makeObject :: [(String, JSValue)] -> JSValue camelCaseMatch :: String -> String -> Bool data ScionDefaultCabalConfig ScionDefaultCabalConfig :: String -> ScionDefaultCabalConfig readFileComponentConfig :: JSValue -> Result (String, [String]) projectConfigFileFromDir :: FilePath -> FilePath projectConfigFromDir :: FilePath -> ScionM ScionProjectConfig writeSampleConfig :: FilePath -> IO () parseScionProjectConfig :: FilePath -> ScionM ScionProjectConfig instance JSON ScionDefaultCabalConfig instance JSON CabalConfiguration -- | Find things in a syntax tree. module Scion.Inspect.Find -- | Lookup all the things in a certain region. findHsThing :: (Search id a) => (SrcSpan -> Bool) -> a -> SearchResults id data SearchResult id FoundBind :: SrcSpan -> (HsBind id) -> SearchResult id FoundPat :: SrcSpan -> (Pat id) -> SearchResult id FoundType :: SrcSpan -> (HsType id) -> SearchResult id FoundExpr :: SrcSpan -> (HsExpr id) -> SearchResult id FoundStmt :: SrcSpan -> (Stmt id) -> SearchResult id FoundId :: Id -> SearchResult id FoundName :: Name -> SearchResult id FoundCon :: SrcSpan -> DataCon -> SearchResult id FoundLit :: SrcSpan -> HsLit -> SearchResult id type SearchResults id = PosForest (SearchResult id) data PosTree a Node :: a -> PosForest a -> PosTree a val :: PosTree a -> a children :: PosTree a -> PosForest a type PosForest a = Set (PosTree a) deepestLeaf :: (Ord a) => PosTree a -> a -- | Returns the deepest leaf, together with the path to this leaf. For -- example, for the following tree with root A: A -+- B --- -- C '- D --- E --- F this function will return: (F, [E, D, -- A]) If F were missing the result is either (C, -- [B,A]) or (E, [D,A]). pathToDeepest :: (Ord a) => PosForest a -> Maybe (a, [a]) surrounds :: SrcSpan -> SrcSpan -> Bool overlaps :: SrcSpan -> SrcSpan -> Bool instance (Eq a) => Eq (PosTree a) instance (Ord a) => Ord (PosTree a) instance (Search id id) => Search id (HsSplice id) instance (Search id id) => Search id (HsBracket id) instance (Search id e) => Search id (HsRecField id e) instance (Search id e) => Search id (HsRecFields id e) instance (Search id id) => Search id (ArithSeqInfo id) instance (Search id id) => Search id (GroupByClause id) instance (Search id id) => Search id (StmtLR id id) instance (Search id id) => Search id (HsCmdTop id) instance (Search id id) => Search id (HsValBindsLR id id) instance (Search id id) => Search id (HsLocalBindsLR id id) instance (Search id id) => Search id (HsExpr id) instance (Search id id) => Search id (GRHS id) instance (Search id id) => Search id (GRHSs id) instance (Search id id) => Search id (HsType id) instance (Search id arg, Search id rec) => Search id (HsConDetails arg rec) instance (Search id id) => Search id (Pat id) instance (Search id id) => Search id (Match id) instance (Search id id) => Search id (MatchGroup id) instance (Search id id) => Search id (HsBindLR id id) instance (Search id id) => Search id (HsGroup id) instance (Search id a) => Search id (Maybe a) instance (Search id a) => Search id [a] instance (Search id a) => Search id (Bag a) instance (Search id a) => Search id (Located a) instance (Search id id) => Search id (IPName id) instance Search id HsLit instance Search id DataCon instance Search Name Name instance Search Id Id instance (Outputable a) => Outputable (PosTree a) instance (OutputableBndr id, Outputable id) => Outputable (SearchResult id) instance Ord (SearchResult id) instance Eq (SearchResult id) module Scion.Inspect.TypeOf typeOf :: (SearchResult Id, [SearchResult Id]) -> Maybe Type -- | Reduce a top-level type application if possible. That is, we perform -- the following simplification step: (forall v . t) t' ==> t -- [t'/v] where [t'/v] is the substitution of t' -- for v. reduce_type :: Type -> Type subst_type :: TyVar -> Type -> Type -> Type -- | Functionality to inspect Haskell programs. module Scion.Inspect typeOfResult :: SearchResult Id -> Maybe Type prettyResult :: (OutputableBndr id) => SearchResult id -> SDoc typeDecls :: (TypecheckedMod m) => m -> [LTyClDecl Name] classDecls :: RenamedSource -> [LTyClDecl Name] familyDecls :: RenamedSource -> [LTyClDecl Name] toplevelNames :: (TypecheckedMod m) => m -> [Name] instance (Biplate b a) => Biplate [b] a instance (Biplate b a) => Biplate (Located b) a instance (Biplate b a) => Biplate (Bag b) a instance (Uniplate arg) => Biplate (HsRecField id (Located arg)) arg instance (Uniplate arg) => Biplate (HsRecFields id (Located arg)) arg instance Biplate (HsConDetails (LPat id) (HsRecFields id (LPat id))) (Pat id) instance Uniplate (Pat n) instance (Uniplate a) => Biplate a a -- | Utilities to manipulate the session state. module Scion.Session data CannotOpenCabalProject CannotOpenCabalProject :: String -> CannotOpenCabalProject data NoCurrentCabalProject NoCurrentCabalProject :: NoCurrentCabalProject data ComponentDoesNotExist ComponentDoesNotExist :: Component -> ComponentDoesNotExist initialScionDynFlags :: DynFlags -> DynFlags -- | Reset the state of the session to a defined default state. -- -- Due to some bugs in GHC this isn't completely possible. For example, -- GHC retains instance declarations which can lead to problems when you -- load a new module which defines a different instance. (You'll get a -- conflicting instance error, which can only be resolved by re-starting -- GHC.) resetSessionState :: ScionM () -- | Sets the current working directory and notifies GHC about the change. -- -- TODO: do we want to adjust certain flags automatically? setWorkingDir :: FilePath -> ScionM () -- | Try to open a Cabal project. The project must already be configured -- using the same version of Cabal that Scion was build against. -- -- Use configureCabalProject to automatically configure a project (if it -- hasn't been already.) -- -- TODO: Allow other working directories? Would require translating all -- the search paths from relative to absolute paths. Furthermore, what -- should the output directory be then? -- -- Throws: -- -- openCabalProject :: FilePath -> FilePath -> ScionM () -- | Return the (configured) package description of the current Cabal -- project. -- -- Throws: -- -- currentCabalPackage :: ScionM PackageDescription -- | Return path to the .cabal file of the current Cabal package. -- -- This is useful to identify the project when communicating with Scion -- from foreign code, because this does not require serialising the local -- build info. -- -- Throws: -- -- currentCabalFile :: ScionM FilePath -- | Return all components of the specified Cabal file. -- -- Throws: -- -- cabalProjectComponents :: FilePath -> ScionM [Component] cabalConfigurations :: FilePath -> String -> Bool -> ScionM [CabalConfiguration] -- | Run the steps that Cabal would call before building. preprocessPackage :: FilePath -> ScionM () -- | Return the current LocalBuildInfo. -- -- The LocalBuildInfo is the result of configuring a Cabal -- project, therefore requires that we have a current Cabal project. -- -- Throws: -- -- getLocalBuildInfo :: ScionM LocalBuildInfo -- | Root directory of the current Cabal project. -- -- Throws: -- -- projectRootDir :: ScionM FilePath -- | Set GHC's dynamic flags for the given component of the current Cabal -- project (see openCabalProject). -- -- Throws: -- -- setComponentDynFlags :: Component -> ScionM [PackageId] -- | Set the targets for a GHC.load command from the meta data of the -- current Cabal project. -- -- Throws: -- -- setComponentTargets :: Component -> ScionM () cabalModuleNameToTarget :: ModuleName -> Target -- | Load the specified component from the current Cabal project. -- -- Throws: -- -- loadComponent :: Component -> ScionM CompilationResult cabalProjectRoot :: ScionM FilePath -- | Make the specified component the active one. Sets the DynFlags to -- those specified for the given component. Unloads the possible -- -- Throws: -- -- setActiveComponent :: Component -> ScionM () -- | Return the currently active component. getActiveComponent :: ScionM (Maybe Component) noLibError :: ScionM a noExeError :: String -> ScionM a -- | Wrapper for GHC.load. load :: LoadHowMuch -> ScionM CompilationResult -- | Unload whatever is currently loaded. unload :: ScionM () -- | Parses the list of Strings as command line arguments and sets the -- DynFlags accordingly. -- -- Does not set the flags if a parse error occurs. XXX: There's currently -- no way to find out if there was an error from inside the program. addCmdLineFlags :: [String] -> ScionM [PackageId] -- | List all components in the current cabal project. -- -- This can be used to present the user a list of possible items to load. -- -- Throws: -- -- availableComponents :: ScionM [Component] -- | Set the verbosity of the GHC API. setGHCVerbosity :: Int -> ScionM () -- | Takes an absolute path to a file and attempts to typecheck it. -- -- This performs the following steps: -- -- 1. Check whether the file is actually part of the current project. -- It's also currently not possible to typecheck a .hs-boot file using -- this function. We simply bail out if these conditions are not met. -- -- 2. Make sure that all dependencies of the module are up to date. -- -- 3. Parse, typecheck, desugar and load the module. The last step is -- necessary so that we can we don't have to recompile in the case that -- we switch to another module. -- -- 4. If the previous step was successful, cache the results in the -- session for use by source code inspection utilities. Some of the above -- steps are skipped if we know that they are not necessary. backgroundTypecheckFile :: FilePath -> ScionM (Either String CompilationResult) -- | Return whether the filepath refers to a file inside the current -- project root. Return False if there is no current project. isRelativeToProjectRoot :: FilePath -> ScionM Bool filePathToProjectModule :: FilePath -> ScionM (Maybe ModSummary) isPartOfProject :: FilePath -> ScionM Bool -- | Ensure that all dependencies of the module are already loaded. -- -- Sets focusedModule if it was successful. setContextForBGTC :: ModSummary -> ScionM (Maybe ModuleName, CompilationResult) -- | Return the ModSummary that refers to the source file. -- -- Assumes that there is exactly one such ModSummary. modSummaryForFile :: FilePath -> ModuleGraph -> ModSummary removeMessagesForFile :: AbsFilePath -> CompilationResult -> ScionM CompilationResult instance Typeable ComponentDoesNotExist instance Typeable NoCurrentCabalProject instance Typeable CannotOpenCabalProject instance Show ComponentDoesNotExist instance Show NoCurrentCabalProject instance Show CannotOpenCabalProject instance Exception ComponentDoesNotExist instance Exception NoCurrentCabalProject instance Exception CannotOpenCabalProject module Scion.Configure -- | Open or configure a Cabal project using the Cabal library. -- -- Tries to open an existing Cabal project or configures it if opening -- failed. -- -- Throws: -- -- openOrConfigureCabalProject :: FilePath -> FilePath -> [String] -> ScionM () -- | Configure a Cabal project using the Cabal library. -- -- This is roughly equivalent to calling ./Setup configure on the -- command line. The difference is that this makes sure to use the same -- version of Cabal and the GHC API that Scion was built against. This is -- important to avoid compatibility problems. -- -- If configuration succeeded, sets it as the current project. -- -- TODO: Figure out a way to report more helpful error messages. -- -- Throws: -- -- configureCabalProject :: FilePath -> FilePath -> [String] -> ScionM () -- | Something went wrong during cabal configure. -- -- TODO: Add more detail. data ConfigException ConfigException :: ConfigException -- | Do the equivalent of runghc Setup.hs args using the -- GHC API. -- -- Instead of runghc, this function uses the GHC API so that the -- correct version of GHC and package database is used. -- -- TODO: Return exception or error message in failure case. cabalSetupWithArgs :: FilePath -> [String] -> ScionM Bool instance Typeable ConfigException instance Show ConfigException instance Exception ConfigException -- | Scion is a library on top of the GHC API to provide IDE-like -- functionality. module Scion data ScionM a -- | Run the ScionM monad. runScion :: ScionM a -> IO a -- | Run the session with the given static flags. -- -- Static flags cannot be changed during a session and can only be set -- once per process. That is, any session running in the same -- process (i.e. program) must not attempt to set the static flags again. -- -- Which flags are static flags depends on the version of GHC. runScion' :: [String] -> ScionM a -> IO a