Language.Haskell.HBB.SmartInline

Documentation

smartinline :: [String] -> NonFirstLinesIndenting -> FilePath -> BufLoc -> Maybe BufLoc -> IO (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan)

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:

• The GHC options as string list (as they should appear on the command line)
• Some options to the mode inline that change the functions behaviour

smartinlineM :: GhcMonad m => NonFirstLinesIndenting -> FilePath -> BufLoc -> Maybe BufLoc -> m (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan)

This function is similar to smartinline except that it runs in a GhcMonad instance.

showSmartInlineResult :: (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) -> String

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.

showSmartInlineResultAsByteString :: (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) -> ByteString

This function is a performance optimization to showSmartInlineResult as the resulting bytestring isn't converted back to string.

data NonFirstLinesIndenting

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))

Constructors

AdaptIndToTargetEnv

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)

IgnoreIndOfTargetEnv

Preserve indentation which means don't adapt the indentation to the environment of the caller.

data BufLoc

This is just the combination of a line number and a column number.

Constructors

BufLoc Int Int

BufLoc line column

Instances

Eq BufLoc

Data BufLoc

Ord BufLoc

Show BufLoc

BufLocs are shown by separating the line and the column number by a colon.

Typeable BufLoc

data BufSpan

A BufSpan is simply defined by two times a BufLoc.

Constructors

BufSpan BufLoc BufLoc

BufSpan startLoc endLoc

Instances

Eq BufSpan

Data BufSpan

Show BufSpan

Typeable BufSpan

data RealSrcSpan

Instances

Eq RealSrcSpan

Data RealSrcSpan

Show RealSrcSpan

Typeable RealSrcSpan

Outputable RealSrcSpan

data TTree a b c

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

Constructors

TTree (TTreeNode a b) [(c, TTree a b c)]

Instances

(Eq a, Eq b, Eq c) => Eq (TTree a b c)

(Show a, Show b, Show c) => Show (TTree a b c)

type LineBuf = [String]

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).

encodeTTreeToJSON :: (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan) -> ByteString

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"
 }

decodeTTreeFromJSON :: ByteString -> Either String (RealSrcSpan, TTree LineBuf (RealSrcSpan, Int) BufSpan)

This is the function that allows the deserialization of the Transformation-Tree from JSON.