-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Backend for text editors to provide better Haskell editing support. -- -- This project contains a library that utilizes the GHC API to provide -- some special features for Haskell text editors. Libhbb has been -- designed to extend ghc-mod (which does similar tasks) with certain -- features. However libhbb is completely independent of ghc-mod. The -- connection to ghc-mod is established in a package called hbb. The -- features of libhbb can be used standalone by the means of the -- executable libhbb-cli which is sipped as well. The big outstanding -- feature that libhbb provides is the ability to inline functions (their -- body is converted to a lambda function and written in place of the -- according name). @package libhbb @version 0.4.0.2 module Language.Haskell.HBB.ApplyTo -- | This function applies a String to String function to a certain String -- (everything in the context of the module Prelude). -- -- It is expensive as it calls ghc to produce its results. It -- has been created to formally provide the mode 'apply-to' but text -- editors should instead use ghc directly. The first argument -- control whether a warning message describing this fact is contained in -- the result. If it is False then the second tuple element of the result -- will contain an according warning otherwise it Nothing. -- -- The result is a tuple of which the first elements contains the -- (stdout-)output of the call to the ghc and the second element -- may contain warning messages. If the first function argument is False -- then the second tuple element will never be Nothing. Otherwise it may -- be Nothing or contain a messages (for example when the executable GHC -- isn'f found). applyTo :: Bool -> String -> String -> IO (String, Maybe String) module Language.Haskell.HBB.Internal.GHC -- | This is a wrapper around runGhc which allows to pass some command line -- options. -- -- This function takes ghc-specific command line flags and inserts them -- into the GHC monad. The passed Ghc action is then executed in an -- environment where these flags have been applied. Principally there are -- 3 types of flags for GHC: -- -- -- -- This function only processes dynamic and static flags. They should be -- passed as specified on the command line: -- -- 
--   runGhcWithCmdLineFlags [-isrc,-XDeriveDataTypeable] (Just libdir) someAction
--
-- -- This function will throw an exception if any of the specified options -- leads to a warning or cannot be parsed. runGhcWithCmdLineFlags :: [String] -> Maybe FilePath -> Ghc a -> IO a -- | Takes a module summary and returnes the renamed abstract syntax tree. -- -- This is a small auxiliary function that takes a module summary and -- extracts the renamed abstract syntax tree from it. The syntax tree is -- represented by the data structure HsGroup in GHC. extractRenamedAST :: GhcMonad m => ModSummary -> m RenamedSource -- | A small auxiliary function that updates the dynamic flags to suppress -- file output. updateDynFlagsToSuppressFileOutput :: GhcMonad m => m () -- | This function takes a file name or a module and searches the -- module-summary which is based on this source file out of the module -- graph. searchModGraphFor :: GhcMonad m => Either FilePath Module -> m (ModuleName, ModSummary) -- | This function creates a target from the passed file name by applying -- to most common used settings. fileToTarget :: FilePath -> Target -- | Wrapper around setTargets and load that treats the -- common case of a one-file-target. loadTargetsFromFilename :: GhcMonad m => FilePath -> m () module Language.Haskell.HBB.ExprType -- | This function takes a filename and an expression and evaluates the -- type of this expression in the context of the passed file. The result -- value is a tuple where the first element is GHCs representation of the -- type and the second one is the stringified version of the type. -- -- The first two command line parameter is: -- -- exprtype :: [String] -> FilePath -> String -> IO (Type, String) -- | This is a variant of exprtype that runs within the GHC monad and -- therefore allows a more fine-grained control over the behaviour of -- GHC. exprtypeM :: GhcMonad m => FilePath -> String -> m (Type, String) -- | This function creates a string of the result returned by exprtype or -- exprtypeM. -- -- The string has exactly the format that should be understood by text -- editors that are using this mode. showExprTypeResult :: (Type, String) -> String data Type :: * module Language.Haskell.HBB.Internal.AST -- | Uses SYB to create generic transformation that omits elements of type -- PostTcType. This is needed because after the renamer -- PostTcTypes must not be evaluated. transformRenamedAST :: (Monad m, Data a) => GenericM m -> a -> m a -- | This function is similar to everythingBut from the SYB -- schemes but uses a neutral element and automatically omits elements of -- the renamed AST that mustn't be evaluated. queryRenamedAST :: r -> (r -> r -> r) -> GenericQ r -> GenericQ r -- | Uses SYB to create generic transformation that omits elements of type -- NameSet. This is needed because after the renamer -- NameSet (the element bind_fvs in function bindings) must -- not be evaluated. transformTypecheckedAST :: (Monad m, Data a) => GenericM m -> a -> m a module Language.Haskell.HBB.Internal.InterfaceTypes -- | Instances of this data type control whether the non-first lines of a -- binding in mode inline or smart-inline should get some -- extra indentation to match the environment of the place where the -- binding should be written to. -- -- Assumed that the following call to factorial should get -- inlined: -- -- 
--   result = factorial 3
--
-- -- The function factorial looks this way: -- -- 
--   factorial 1 = 1
--   factorial x = x * factorial (x-1)
--
-- -- The lambda function that is produced in mode inline with -- IgnoreIndOfTargetEnv looks as follows: -- -- 
--   (x -> case x of 1 -> 1
--                    y -> y * factorial (y - 1))
--
-- -- The lambda function produced in mode inline with -- AdaptIndToTargetEnv looks as follows: -- -- 
--   (x -> case x of 1 -> 1
--                             y -> y * factorial (y - 1))
--
data NonFirstLinesIndenting -- | Increase indentation of non-first lines by the column number the -- inlined version of the the function starts at (short: adapt -- indentation to caller environment) AdaptIndToTargetEnv :: NonFirstLinesIndenting -- | Preserve indentation which means don't adapt the indentation to the -- environment of the caller. IgnoreIndOfTargetEnv :: NonFirstLinesIndenting module Language.Haskell.HBB.Internal.SrcSpan -- | This is just the combination of a line number and a column number. data BufLoc -- | BufLoc line column BufLoc :: Int -> Int -> BufLoc -- | A BufSpan is simply defined by two times a BufLoc. data BufSpan -- | BufSpan startLoc endLoc BufSpan :: BufLoc -> BufLoc -> BufSpan -- | This is a file/text portion buffered as list of lines. -- -- Line buffers are used to avoid repeated IO operations and to describe -- line-oriented content (for example at assembling the TTree). type LineBuf = [String] -- | Returns the start location of a BufSpan spanStart :: BufSpan -> BufLoc -- | Returns the end location of a BufSpan spanEnd :: BufSpan -> BufLoc -- | Deconstructs a RealSrcSpan to the types more often used in libhbb. unpackRealSrcSpan :: RealSrcSpan -> (FilePath, BufSpan) packRealSrcSpan :: (FilePath, BufSpan) -> RealSrcSpan normalisePath :: FilePath -> FilePath -> FilePath -- | This function converts a location in the form libhbb uses it into a -- string. The string has the format that is used by 'occurrences-of' and -- locate to report locations to the client. showSpan :: Maybe FilePath -> (FilePath, BufSpan) -> String -- | This is an auxiliary function that splits a string at all newlines. -- -- Note that lines from Prelude cannot be used here. The reason is -- following example: -- -- 
--   lines       "|  ->\n" = ["|  ->"]
--   str2LineBuf "|  ->\n" = ["|  ->",""]
--
str2LineBuf :: String -> LineBuf -- | Converts a line buffer to a string. -- -- Note that unlines doesn't work here because it doesn't treat -- the last line correctly. lineBuf2Str :: LineBuf -> String -- | This alias can be used to have a meaningful name for indentations. type Indentation = Int -- | For a line buffer this function returns the number of spaces -- charachters of the line with the smallest indentation. getIndentation :: LineBuf -> Indentation -- | Compares two non-overlapping RealSrcSpan elements by their starting -- location. compareByStartLoc :: RealSrcSpan -> RealSrcSpan -> Ordering -- | Converts a RealSrcLoc into a BufLoc effectively throwing away the -- filename. toBufLoc :: RealSrcLoc -> BufLoc -- | Converts a RealSrcSpan into a BufSpan effectively throwing away the -- filename. toBufSpan :: RealSrcSpan -> BufSpan -- | Creates a BufSpan where the first and the last BufLoc is the same. -- -- The first parameter is the line and the second one is the column. pointBufSpan :: Int -> Int -> BufSpan -- | This function splits the passed lines (of a file-cache) at the -- position passed as second parameter. -- -- Note that the line- and column-counts start with 1 (this is GHC -- behaviour). The split contains the character pointed to by the BufLoc -- in the right part of the tuple. -- -- This means that (in case of line=1 and column=1) following applies: -- -- 
--   splitAtBufLoc "hello world" loc == ([""],["hello world"])
--
splitAtBufLoc :: LineBuf -> BufLoc -> (LineBuf, LineBuf) -- | This function splits a number of input lines in a way so that the area -- located to by the passed source span is isolated. -- -- The three areas in the return tuple are: -- -- -- -- The last line of initLines and the first line of subjLines must be -- joined to reproduce the output. The same applies to subjLines and -- traiLines... splitBufferedLinesAtBufSpan :: LineBuf -> BufSpan -> (LineBuf, LineBuf, LineBuf) -- | This function returns true if the first RealSrcSpan points to a region -- that is located before the one pointed to by the second RealSrcSpan. -- -- The two spans must be disjoint otherwise the results are undefined -- (can be checked with the function disjoint)! leq :: RealSrcSpan -> RealSrcSpan -> Bool -- | This function returns true when the two passed RealSrcSpans do not -- overlap. -- -- This means that the end of the first RealSrcSpan is smaller or equal -- to the start of the second RealSrcSpan and vice versa. disjoint :: RealSrcSpan -> RealSrcSpan -> Bool -- | This function is the opposite of splitAtBufLoc. -- -- It can rejoin a split concerning that the last and the first line in -- the frist respective second element of the split tuple must be joined -- by string concatenation. This function has been designed to run with -- linear time complexity. joinSplit :: ([String], [String]) -> [String] -- | This function combines two times joinSplit to be able to join lines -- that have been split by a SrcSpan. reassembleSplit :: ([String], [String], [String]) -> [String] instance Typeable BufLoc instance Typeable BufSpan instance Eq BufLoc instance Data BufLoc instance Eq BufSpan instance Data BufSpan instance Show BufSpan instance Ord BufLoc instance Show BufLoc module Language.Haskell.HBB.Internal.TTree data TTreeNode a b Addition :: a -> TTreeNode a b Display :: b -> TTreeNode a b -- | This is the generic data structure representing a transformation tree. -- -- TransformationTree -- -- The transformation tree is a recursive data structure to represent -- modifications to text (files). It is used to represent the changes to -- source code made by the inlining function feature. -- -- Cover-Range -- -- The cover-range is the snippet of code that should be hidden by the -- new text. For the root of the tree this is a RealSrcSpan (which has a -- filename attached). For other location the cover-range refers to the -- text inserted by the parent element. -- -- Children -- -- The text that has been added by for example an addition may be altered -- again by the usage of nested transformations. These transformations -- always refer to their parent transformation whichs means that the -- Cover-Range for example contains lines- and column-indices which refer -- only to the snipped added by their parent transformation (and not the -- whole text which is referred to by the top-most addition or display). -- INVARIANT: Moreover the source-spans elements of child-transformations -- must be disjoint. Reassembling the transformation-tree can so be done -- by sorting the child-tranformations by their cover-range in reverse -- order (so that the last position is taken first) and applying them. -- -- Instance of TTree produced by ConvertibleToTTree: -- -- 
--   TTree LineBuf RealSrcSpan InsertionInfo
--
-- -- Instance of TTree that is searialized to JSON: -- -- 
--   TTree LineBuf (RealSrcSpan,Int) BufSpan
--
data TTree a b c TTree :: (TTreeNode a b) -> [(c, TTree a b c)] -> TTree a b c type ClientTTree = TTree LineBuf (RealSrcSpan, Int) BufSpan applyTTree :: [(FilePath, LineBuf)] -> (BufSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) -> LineBuf -> LineBuf applyTTreeGeneric :: Maybe (a, attr -> a, (a, attr) -> (LineBuf, LineBuf, LineBuf) -> (LineBuf, LineBuf, LineBuf)) -> [(FilePath, LineBuf)] -> (attr -> BufSpan) -> (attr, TTree LineBuf (RealSrcSpan, Int) attr) -> LineBuf -> LineBuf getCacheElement :: FilePath -> [(FilePath, LineBuf)] -> LineBuf collectFilenames :: (a, TTree b (RealSrcSpan, Int) a) -> [FilePath] cacheFiles :: [FilePath] -> IO [(FilePath, LineBuf)] instance (Show a, Show b) => Show (TTreeNode a b) instance (Eq a, Eq b) => Eq (TTreeNode a b) instance (Show a, Show b, Show c) => Show (TTree a b c) instance (Eq a, Eq b, Eq c) => Eq (TTree a b c) module Language.Haskell.HBB.Internal.Lexer -- | This function uses GHCs lexer to determine the token that is under the -- cursor (the passed SrcLoc). -- -- Currently only the tokens ITvarid (a variable id) and ITqvarid (a -- qualified variable id) are supported. If IncludeQualified euqal -- ExcludeQualifiedVars then ITqvarid will be ignored. A token of type -- ITqvarid has two strings attached, the name of the module (the -- qualifier) and the name of the variable. Of these twos only the name -- is contained by the result. getVariableIdUsingLexerAt :: GhcMonad m => (FilePath, BufLoc) -> IncludeQualified -> m (Either LexingFailReason (String, RealSrcSpan)) -- | This type holds possible return values of getVariableIdUsingLexerAt. data LexingFailReason LexingFailed :: LexingFailReason VarNotFound :: LexingFailReason data IncludeQualified IncludeQualifiedVars :: IncludeQualified ExcludeQualifiedVars :: IncludeQualified instance Eq IncludeQualified module Language.Haskell.HBB.Internal.GHCHighlevel -- | This function takes a file name and the location that is of interest -- and searches out the value or function binding for the name that -- stands at this location. The returned value contains all informations -- that are needed to inline the function definition or describe how to -- inline it (smart-inline). -- -- If the name refers to a name that is not part of the module graph -- (because it has been loaded by a library for example) this function -- will fail. searchFunctionBindingM :: GhcMonad m => FilePath -> BufLoc -> Maybe BufLoc -> m FunBindInfo -- | This version to search a function binding takes a Name and some -- details about it. searchFunctionBindingForNameM :: GhcMonad m => (Name, BufSpan, FilePath) -> m FunBindInfo -- | This is a generic function that takes informations about a Name and -- queries the renamed AST according to the parameters. searchTokenForNameM :: GhcMonad m => (Name, BufSpan, FilePath) -> b -> (b -> b -> b) -> (BufLoc -> GenericQ b) -> m (SearchedTokenInfo b) -- | This function is responsible to detect what kind of thing is located -- at the passed location (the token). whatIsAt :: GhcMonad m => FilePath -> BufSpan -> m WhatIsAt data WhatIsAt -- | Names are used for value- and function bindings as well as function -- parameters. External names refer to things outside of the module graph -- (external libraries for example) ThereIsAnExternalName :: Name -> WhatIsAt -- | (I)mport/(E)xport declaration that points to another compilation unit -- (package). ThereIsAnIEDeclToExtern :: Name -> WhatIsAt -- | (I)mport/(E)xport declaration that points to the thing stored as first -- parameter. ThereIsAnIEDeclFor :: WhatIsAt -> WhatIsAt -- | Names are just pointers to other things. When such a name is -- discovered, another run of WhatIsAt is triggered which searches for -- the thing that is at the location pointed to by this name. This can -- only be a binding (ThereIsABinding) or a function parameter -- (ThereIsAFunParameter). ThereIsANameFor :: WhatIsAt -> WhatIsAt -- | The token pointed to a binding. ThereIsABinding :: (LHsBindLR Name Name) -> WhatIsAt -- | Function parameters are of type (LPat Name) at the location where they -- are defined. ThereIsAFunParameter :: (LPat Name) -> WhatIsAt -- | The location specified points to a function or value bindings -- signature. ThereIsATypeSigFor :: WhatIsAt -> WhatIsAt -- | There is something that is currently not supported (e.g. a type -- declaration). UnknownElement :: WhatIsAt -- | This function extracts the RealSrcSpan elements of a function binding. -- The problem is that a function binding may contain several entry -- points of which each has its own src-span attached. Each of these -- spans will be contained by the result list produced by this function. -- -- This is the heading myfunction in myfunction x = x * -- x. realSrcSpansOfBinding :: Int -> HsBindLR Name Name -> [RealSrcSpan] -- | Parses the renamed AST of the module and returns all elements that -- start at the passed location sorted by length in increasing oder. getThingsAt :: (GhcMonad m, Typeable a) => (a -> BufLoc -> Maybe BufSpan) -> FilePath -> BufLoc -> m [a] -- | These are exceptions searchFunctionBinding(M) may throw. -- -- Each exception can be converted to a meaningful string. Moreover -- searchFunctionBinding is throwing internal errors via error (exception -- ErrorCall must be catched). data SearchTokenException LexingSearchError :: LexingFailReason -> SearchTokenException TokenIsntAName :: SearchTokenException TokenNotEndingAccordingly :: SearchTokenException IsFunctionApplication :: SearchTokenException IsExternalName :: ModuleName -> SearchTokenException IsntNameOfABinding :: SearchTokenException -- | This type holds possible return values of getVariableIdUsingLexerAt. data LexingFailReason LexingFailed :: LexingFailReason VarNotFound :: LexingFailReason data SearchedTokenInfo a SearchedTokenInfo :: (forall b. Outputable b => b -> String) -> RealSrcSpan -> Name -> a -> SearchedTokenInfo a -- | GHC internally uses Outputable for things that may be printed to the -- user for example. As the printing functions depend on the DynFlags -- used at compilation they can't be used any more when the GHC run has -- finished. So printFun uses a closure to save the DynFlags in a -- curried function to make it possible for clients to get a string -- representation of a GHC internal data type. printFun :: SearchedTokenInfo a -> (forall b. Outputable b => b -> String) -- | This is the Src-Span covering the full function name the -- searchFunctionBinding function has determined (the function gets -- passed only a certain point in a file pointing to a (part) of the -- function name) occSpan :: SearchedTokenInfo a -> RealSrcSpan -- | The name that was at the location that has been passed to -- searchFunctionBinding(M). In the case of inlining the name is what is -- to be replaced by the function definition. This name is completely -- enclosed by occSpan. name :: SearchedTokenInfo a -> Name -- | The type of the result is determined by the GenericQ a passed as -- parameter. result :: SearchedTokenInfo a -> a type FunBindInfo = SearchedTokenInfo (LHsBindLR Name Name, Maybe (LSig Name)) -- | A BufSpan is simply defined by two times a BufLoc. data BufSpan -- | BufSpan startLoc endLoc BufSpan :: BufLoc -> BufLoc -> BufSpan -- | This is just the combination of a line number and a column number. data BufLoc -- | BufLoc line column BufLoc :: Int -> Int -> BufLoc instance Typeable SearchTokenException instance Exception SearchTokenException instance Show SearchTokenException module Language.Haskell.HBB.Internal.TTreeColor applyColoredTTree :: [(FilePath, LineBuf)] -> (BufSpan, ClientTTree) -> LineBuf -> LineBuf module Language.Haskell.HBB.Internal.TTreeJSON -- | This function converts the tranformation-tree to JSON. -- -- This is an example of a tree containing two addition which has been -- converted to JSON (the JSON-code has been layouted to make it more -- readable): -- -- 
--   {
--       "addition-text": "()",
--       "children": [
--           {
--               "addition-text": "\x -> \"hello \" ++ x",
--               "children": [],
--               "cover-range": "1:2-1:2"
--           }
--       ],
--       "cover-range": "examples/PlayHelloPattern.hs,17:16-17:21"
--   }
--
encodeTTreeToJSON :: (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) -> ByteString -- | This is the function that allows the deserialization of the -- Transformation-Tree from JSON. decodeTTreeFromJSON :: ByteString -> Either String (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) instance ToJSON JSON_RootTTree instance ToJSON JSON_TTree instance FromJSON JSON_RootTTree instance FromJSON JSON_TTree instance ToJSON JSON_RealSrcSpan instance FromJSON JSON_RealSrcSpan instance ToJSON JSON_DisplaySpan instance FromJSON JSON_DisplaySpan instance ToJSON JSON_BufSpan instance FromJSON JSON_BufSpan instance ToJSON JSON_BufLoc instance FromJSON JSON_BufLoc module Language.Haskell.HBB.TestModes.ApplyTTree -- | This type is used to have influence on the processing of -- testModeApplyTTree. It is possible to activate ANSI color escape -- sequences for the text or to enable the printing of the file context. data ApplyTTreeArgs ApplyTTreeArgs :: Bool -> Bool -> ApplyTTreeArgs applyToShowContext :: ApplyTTreeArgs -> Bool applyToShowAnsiColored :: ApplyTTreeArgs -> Bool -- | These are the default options used for this mode. libhbb-cli only uses -- these default settings. defaultApplyTTreeArgs :: ApplyTTreeArgs -- | This function reads a transformation-tree serialized to JSON from -- standard input and applies it which means that it converts it to text. -- After having it applied the text is returned as one single string. testModeApplyTTree :: ApplyTTreeArgs -> IO String module Language.Haskell.HBB.OccurrencesOf -- | This function takes a location, searches out what is at this location -- and then returns a list of all occurrences of this identifier. This -- currently works for names of function- and value bindings. occurrencesOf :: [String] -> FilePath -> BufLoc -> [FilePath] -> IO [(FilePath, BufSpan)] -- | This is the monadic version of occurrencesOf which allows to use this -- mode of operation from a preconfigured GHC environment. occurrencesOfM :: GhcMonad m => FilePath -> BufLoc -> [FilePath] -> m [(FilePath, BufSpan)] -- | This Function formats the results from the occurrencesOf or -- occurrencesOfM function. showOccurrencesOfResult :: [(FilePath, BufSpan)] -> String -- | This is just the combination of a line number and a column number. data BufLoc -- | BufLoc line column BufLoc :: Int -> Int -> BufLoc -- | A BufSpan is simply defined by two times a BufLoc. data BufSpan -- | BufSpan startLoc endLoc BufSpan :: BufLoc -> BufLoc -> BufSpan module Language.Haskell.HBB.Locate -- | This function implements the mode locate. -- -- locate takes the name of a file and a position within this -- file. If this position points to a value or function binding this -- function returns the source-range where the binding is defined. If the -- position doesn't point to an according binding, the function will fail -- with an exception. In this case nothing is written to standard output. -- -- The first two command line parameters is: -- -- locate :: [String] -> FilePath -> BufLoc -> IO (FilePath, BufSpan) -- | This is a variant of locate that runs within the GHC monad and -- therefore allows a more fine-grained control over the behaviour of -- GHC. locateM :: GhcMonad m => FilePath -> BufLoc -> m (FilePath, BufSpan) -- | This function creates a string of the result returned by locate or -- locateM. -- -- The string has exactly the format that should be understood by text -- editors that are using the mode locate. showLocateResult :: (FilePath, BufSpan) -> String -- | This is just the combination of a line number and a column number. data BufLoc -- | BufLoc line column BufLoc :: Int -> Int -> BufLoc -- | A BufSpan is simply defined by two times a BufLoc. data BufSpan -- | BufSpan startLoc endLoc BufSpan :: BufLoc -> BufLoc -> BufSpan module Language.Haskell.HBB.Internal.InternalTTree applyIndentation :: (InsertionInfo, InternalTTree) -> (BufSpan, ClientTTree) -- | This function turns the (internal) transformation-tree (with the -- recursive elements offsets attached) into a transformation-tree the -- client understands. This is mostly a task of making the indentation -- (which first is attached implicitely) explicit which means that each -- addition begins with enough spaces for example. -- -- The (indentation-)calculations in applyInsertionInfo are kind of -- complex and therefore 'indentation.markdown' is a concept-paper which -- describes some details with the help of some examples. applyInsertionInfo :: Indentation -> Indentation -> [RecElementOffset] -> [AccLevelOffset] -> [Int] -> Indentation -> Int -> Int -> [((BufSpan, RecElementOffset), ClientTTree)] -> ((InsertionInfo, RecElementOffset), TTree LineBuf RealSrcSpan (InsertionInfo, RecElementOffset)) -> [((BufSpan, RecElementOffset), ClientTTree)] type InternalTTree = TTree LineBuf RealSrcSpan InsertionInfo data InsertionInfo IncInline :: BufSpan -> InsertionInfo NewSection :: Int -> InsertionInfo instance Show InsertionInfo module Language.Haskell.HBB.Internal.InternalTTreeCreation data ConversionInfo ProduceLambda :: ConversionInfo ProduceEqual :: ConversionInfo class ConvertibleToTTree a toTTree :: ConvertibleToTTree a => a -> Reader ConversionInfo InternalTTree onDifferentLines :: RealSrcSpan -> RealSrcSpan -> Bool type IsValueBinding = Bool combineRealSrcSpans :: RealSrcSpan -> RealSrcSpan -> RealSrcSpan data LambdaNotationStyle -- | may convert a where-expression to a let-expression ShortNotationStyle :: LambdaNotationStyle LongNotationWithWhere :: LambdaNotationStyle instance ConvertibleToTTree (LHsBindLR Name Name) instance ConvertibleToTTree ([LPat Name], GRHSs Name, LambdaNotationStyle) instance ConvertibleToTTree (IsValueBinding, GRHSs Name, LambdaNotationStyle) instance ConvertibleToTTree (HsLocalBinds Name) instance ConvertibleToTTree (HsValBindsLR Name Name) instance ConvertibleToTTree (IsValueBinding, LGRHS Name, Maybe (HsValBindsLR Name Name)) instance ConvertibleToTTree (LHsExpr Name) instance ConvertibleToTTree [LStmt Name] module Language.Haskell.HBB.SmartInline -- | This function implements the mode 'smart-inline'. -- -- Smart-inline takes a location or a span within a file which should be -- a function binding (as of 2014-09-16 excluding any parameter) and -- tries to produce an inlined version of the function. The inlined -- version of the function is described as transformation to the original -- source code. The transformation is a JSON string which is formatted -- according to the descriptions in the documentation. -- -- 
--   main :: IO ()
--   main = do
--       res <- smartinline ["-isrc"] IgnoreIndOfTargetEnv "example/Example.hs" (BufLoc 14 13)
--       LazyByteString.putStr $ encodeTTreeToJSON res
--       putStrLn ""
--
-- -- If a second location isn't passed this function will use GHCs lexer to -- find out where the end of the variable or function name is. -- Consequently to smart-inline a function and to simultaneously apply it -- to its arguments (which is not supported as of 2014-09-16) the second -- location must be passed. -- -- The first two command line parameters are: -- -- smartinline :: [String] -> NonFirstLinesIndenting -> FilePath -> BufLoc -> Maybe BufLoc -> IO (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) -- | This function is similar to smartinline except that it runs in a -- GhcMonad instance. smartinlineM :: GhcMonad m => NonFirstLinesIndenting -> FilePath -> BufLoc -> Maybe BufLoc -> m (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) -- | Converts the result of smartinline and smartinlineM to JSON. -- -- The resulting string has exactly the format that should be understood -- by text editors that are using mode smart-inline. showSmartInlineResult :: (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) -> String -- | This function is a performance optimization to showSmartInlineResult -- as the resulting bytestring isn't converted back to string. showSmartInlineResultAsByteString :: (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) -> ByteString -- | Instances of this data type control whether the non-first lines of a -- binding in mode inline or smart-inline should get some -- extra indentation to match the environment of the place where the -- binding should be written to. -- -- Assumed that the following call to factorial should get -- inlined: -- -- 
--   result = factorial 3
--
-- -- The function factorial looks this way: -- -- 
--   factorial 1 = 1
--   factorial x = x * factorial (x-1)
--
-- -- The lambda function that is produced in mode inline with -- IgnoreIndOfTargetEnv looks as follows: -- -- 
--   (x -> case x of 1 -> 1
--                    y -> y * factorial (y - 1))
--
-- -- The lambda function produced in mode inline with -- AdaptIndToTargetEnv looks as follows: -- -- 
--   (x -> case x of 1 -> 1
--                             y -> y * factorial (y - 1))
--
data NonFirstLinesIndenting -- | Increase indentation of non-first lines by the column number the -- inlined version of the the function starts at (short: adapt -- indentation to caller environment) AdaptIndToTargetEnv :: NonFirstLinesIndenting -- | Preserve indentation which means don't adapt the indentation to the -- environment of the caller. IgnoreIndOfTargetEnv :: NonFirstLinesIndenting -- | This is just the combination of a line number and a column number. data BufLoc -- | BufLoc line column BufLoc :: Int -> Int -> BufLoc -- | A BufSpan is simply defined by two times a BufLoc. data BufSpan -- | BufSpan startLoc endLoc BufSpan :: BufLoc -> BufLoc -> BufSpan data RealSrcSpan :: * -- | This is the generic data structure representing a transformation tree. -- -- TransformationTree -- -- The transformation tree is a recursive data structure to represent -- modifications to text (files). It is used to represent the changes to -- source code made by the inlining function feature. -- -- Cover-Range -- -- The cover-range is the snippet of code that should be hidden by the -- new text. For the root of the tree this is a RealSrcSpan (which has a -- filename attached). For other location the cover-range refers to the -- text inserted by the parent element. -- -- Children -- -- The text that has been added by for example an addition may be altered -- again by the usage of nested transformations. These transformations -- always refer to their parent transformation whichs means that the -- Cover-Range for example contains lines- and column-indices which refer -- only to the snipped added by their parent transformation (and not the -- whole text which is referred to by the top-most addition or display). -- INVARIANT: Moreover the source-spans elements of child-transformations -- must be disjoint. Reassembling the transformation-tree can so be done -- by sorting the child-tranformations by their cover-range in reverse -- order (so that the last position is taken first) and applying them. -- -- Instance of TTree produced by ConvertibleToTTree: -- -- 
--   TTree LineBuf RealSrcSpan InsertionInfo
--
-- -- Instance of TTree that is searialized to JSON: -- -- 
--   TTree LineBuf (RealSrcSpan,Int) BufSpan
--
data TTree a b c TTree :: (TTreeNode a b) -> [(c, TTree a b c)] -> TTree a b c -- | This is a file/text portion buffered as list of lines. -- -- Line buffers are used to avoid repeated IO operations and to describe -- line-oriented content (for example at assembling the TTree). type LineBuf = [String] -- | This function converts the tranformation-tree to JSON. -- -- This is an example of a tree containing two addition which has been -- converted to JSON (the JSON-code has been layouted to make it more -- readable): -- -- 
--   {
--       "addition-text": "()",
--       "children": [
--           {
--               "addition-text": "\x -> \"hello \" ++ x",
--               "children": [],
--               "cover-range": "1:2-1:2"
--           }
--       ],
--       "cover-range": "examples/PlayHelloPattern.hs,17:16-17:21"
--   }
--
encodeTTreeToJSON :: (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) -> ByteString -- | This is the function that allows the deserialization of the -- Transformation-Tree from JSON. decodeTTreeFromJSON :: ByteString -> Either String (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) module Language.Haskell.HBB.Inline -- | This function implements the mode inline. -- -- Inline takes a location or a span within a file which should be a -- function binding (as of 2014-09-16 excluding any parameter) and tries -- to produce an inlined version of the function. The inlined version of -- the function then is written to standard output. -- -- 
--   main :: IO ()
--   main = inline ["-iexample"] defaultInlineOptions "example/Example.hs" (BufLoc 14 13)
--
-- -- It is important to know that the indentation of non-first lines (as of -- 2014-09-16) is always adapted to match the indentation of the location -- where the name should be replaced. If a second location isn't passed -- this function will use GHCs lexer to find out where the end of the -- variable or function name is. Consequently to inline a function and to -- simultaneously apply it to its arguments (which is not supported as of -- 2014-09-16) the second location must be passed. -- -- The first three command line parameters are: -- -- inline :: [String] -> InlineOptions -> FilePath -> BufLoc -> Maybe BufLoc -> IO (BufSpan, String) -- | This is the monadic version of inline. -- -- Instead of taking command line flags to alter the GHC environment this -- function can be used with a custom GhcMonad instance which allows more -- control about GHCs behaviour. inlineM :: GhcMonad m => InlineOptions -> FilePath -> BufLoc -> Maybe BufLoc -> m (BufSpan, String) -- | This function creates a string of the result returned by inline or -- inlineM. -- -- The string has exactly the format that should be understood by text -- editors that are using the mode inline. showInlineResult :: (BufSpan, String) -> String -- | This is just the combination of a line number and a column number. data BufLoc -- | BufLoc line column BufLoc :: Int -> Int -> BufLoc -- | A BufSpan is simply defined by two times a BufLoc. data BufSpan -- | BufSpan startLoc endLoc BufSpan :: BufLoc -> BufLoc -> BufSpan -- | Instances of this data type control whether the non-first lines of a -- binding in mode inline or smart-inline should get some -- extra indentation to match the environment of the place where the -- binding should be written to. -- -- Assumed that the following call to factorial should get -- inlined: -- -- 
--   result = factorial 3
--
-- -- The function factorial looks this way: -- -- 
--   factorial 1 = 1
--   factorial x = x * factorial (x-1)
--
-- -- The lambda function that is produced in mode inline with -- IgnoreIndOfTargetEnv looks as follows: -- -- 
--   (x -> case x of 1 -> 1
--                    y -> y * factorial (y - 1))
--
-- -- The lambda function produced in mode inline with -- AdaptIndToTargetEnv looks as follows: -- -- 
--   (x -> case x of 1 -> 1
--                             y -> y * factorial (y - 1))
--
data NonFirstLinesIndenting -- | Increase indentation of non-first lines by the column number the -- inlined version of the the function starts at (short: adapt -- indentation to caller environment) AdaptIndToTargetEnv :: NonFirstLinesIndenting -- | Preserve indentation which means don't adapt the indentation to the -- environment of the caller. IgnoreIndOfTargetEnv :: NonFirstLinesIndenting -- | The data type InlineOptions is to alter the behviour of the function -- inline. -- -- If showContext is true inline not only prints the -- inlined version of the function or value binding but also the file -- context. -- -- If showAnsiColored is true inline will use ANSI terminal -- colors to highlight different logical informations in the inlined -- version. Colors are used for areas that are identical with the -- original function or value binding (displays) and a bold grey is used -- for areas that have been added and do not occur in the original -- binding (additions). data InlineOptions InlineOptions :: Bool -> Bool -> NonFirstLinesIndenting -> InlineOptions showContext :: InlineOptions -> Bool showAnsiColored :: InlineOptions -> Bool adaptToTargetEnv :: InlineOptions -> NonFirstLinesIndenting -- | This value defines the default options for inlining. -- -- Most text editors will need these settings (maybe adaptToTargetEnv -- should be adapted). The inlined version of the function or value -- binding is printed without ANSI colors and without context but with -- non-first lines being indented to a level that allows a text editor to -- replace the original name with the return value of mode inline. defaultInlineOptions :: InlineOptions