ghc-exactprint-1.10.0.0: ExactPrint for GHC

Safe Haskell | None
Language | Haskell2010

Language.Haskell.GHC.ExactPrint.Transform

Contents

- The Transform Monad
- Transform monad operations
  - Managing declarations, in Transform monad
    - Utility, does not manage layout
  - New gen functions
  - Managing lists, Transform monad
    - Low level operations used in `HasDecls`
  - Managing lists, pure functions
- Operations
- Pure functions

Description

This module is currently under heavy development, and no promises are made about API stability. Use with care.

We welcome any feedback / contributions on this, as it is the main point of the library.

Synopsis

- type Transform = TransformT Identity
- newtype TransformT (m :: Type -> Type) a = TransformT {
  - unTransformT :: RWST () [String] Int m a
  }
- hoistTransform :: (forall x. m x -> n x) -> TransformT m a -> TransformT n a
- runTransform :: Transform a -> (a, Int, [String])
- runTransformT :: TransformT m a -> m (a, Int, [String])
- runTransformFrom :: Int -> Transform a -> (a, Int, [String])
- runTransformFromT :: Int -> TransformT m a -> m (a, Int, [String])
- logTr :: forall (m :: Type -> Type). Monad m => String -> TransformT m ()
- logDataWithAnnsTr :: forall (m :: Type -> Type) a. (Monad m, Data a) => String -> a -> TransformT m ()
- uniqueSrcSpanT :: forall (m :: Type -> Type). Monad m => TransformT m SrcSpan
- class Monad m => HasTransform (m :: Type -> Type) where
  - liftT :: Transform a -> m a
- class Data t => HasDecls t where
  - hsDecls :: t -> [LHsDecl GhcPs]
  - replaceDecls :: t -> [LHsDecl GhcPs] -> t
- hsDeclsPatBind :: LHsBind GhcPs -> [LHsDecl GhcPs]
- hsDeclsPatBindD :: LHsDecl GhcPs -> [LHsDecl GhcPs]
- replaceDeclsPatBind :: LHsBind GhcPs -> [LHsDecl GhcPs] -> LHsBind GhcPs
- replaceDeclsPatBindD :: LHsDecl GhcPs -> [LHsDecl GhcPs] -> LHsDecl GhcPs
- modifyDeclsT :: (HasDecls t, HasTransform m) => ([LHsDecl GhcPs] -> m [LHsDecl GhcPs]) -> t -> m t
- modifyValD :: SrcSpan -> Decl -> (PMatch -> [Decl] -> ([Decl], Maybe t)) -> (Decl, Maybe t)
- hsDeclsValBinds :: HsValBindsLR GhcPs GhcPs -> [LHsDecl GhcPs]
- replaceDeclsValbinds :: WithWhere -> HsLocalBinds GhcPs -> [LHsDecl GhcPs] -> HsLocalBinds GhcPs
- data WithWhere
  - = WithWhere
  - | WithoutWhere
- noAnnSrcSpanDP :: NoAnn ann => DeltaPos -> EpAnn ann
- noAnnSrcSpanDP0 :: NoAnn ann => EpAnn ann
- noAnnSrcSpanDP1 :: NoAnn ann => EpAnn ann
- noAnnSrcSpanDPn :: NoAnn ann => Int -> EpAnn ann
- d0 :: EpaLocation
- d1 :: EpaLocation
- dn :: Int -> EpaLocation
- addComma :: SrcSpanAnnA -> SrcSpanAnnA
- insertAt :: HasDecls ast => (LHsDecl GhcPs -> [LHsDecl GhcPs] -> [LHsDecl GhcPs]) -> ast -> LHsDecl GhcPs -> ast
- insertAtStart :: HasDecls ast => ast -> LHsDecl GhcPs -> ast
- insertAtEnd :: HasDecls ast => ast -> LHsDecl GhcPs -> ast
- insertAfter :: HasDecls (LocatedA ast) => LocatedA old -> LocatedA ast -> LHsDecl GhcPs -> LocatedA ast
- insertBefore :: HasDecls (LocatedA ast) => LocatedA old -> LocatedA ast -> LHsDecl GhcPs -> LocatedA ast
- balanceComments :: LHsDecl GhcPs -> LHsDecl GhcPs -> (LHsDecl GhcPs, LHsDecl GhcPs)
- balanceCommentsList :: [LHsDecl GhcPs] -> [LHsDecl GhcPs]
- balanceCommentsListA :: [LocatedA a] -> [LocatedA a]
- anchorEof :: ParsedSource -> ParsedSource
- captureOrderBinds :: [LHsDecl GhcPs] -> AnnSortKey BindTag
- captureLineSpacing :: [LocatedA e] -> [LocatedA e]
- captureMatchLineSpacing :: LHsDecl GhcPs -> LHsDecl GhcPs
- captureTypeSigSpacing :: LHsDecl GhcPs -> LHsDecl GhcPs
- isUniqueSrcSpan :: SrcSpan -> Bool
- setEntryDP :: LocatedAn t a -> DeltaPos -> LocatedAn t a
- setEntryDPDecl :: LHsDecl GhcPs -> DeltaPos -> LHsDecl GhcPs
- getEntryDP :: LocatedAn t a -> DeltaPos
- transferEntryDP :: (Typeable t1, Typeable t2) => LocatedAn t1 a -> LocatedAn t2 b -> LocatedAn t2 b
- transferEntryDP' :: LHsDecl GhcPs -> LHsDecl GhcPs -> LHsDecl GhcPs
- wrapSig :: LSig GhcPs -> LHsDecl GhcPs
- wrapDecl :: LHsBind GhcPs -> LHsDecl GhcPs
- decl2Sig :: LHsDecl GhcPs -> [LSig GhcPs]
- decl2Bind :: LHsDecl GhcPs -> [LHsBind GhcPs]

# The Transform Monad

type Transform = TransformT Identity Source #

Monad type for updating the AST and managing the annotations at the same time. The W state is used to generate logging information if required.

newtype TransformT (m :: Type -> Type) a Source #

Monad transformer version of `Transform` monad

Constructors

TransformT |

Fields

- unTransformT :: RWST () [String] Int m a

#### Instances

Instances details

MonadTrans TransformT Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods lift :: Monad m => m a -> TransformT m a Source #
Monad m => MonadReader () (TransformT m) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods ask :: TransformT m () Source # local :: (() -> ()) -> TransformT m a -> TransformT m a Source # reader :: (() -> a) -> TransformT m a Source #
Monad m => MonadState Int (TransformT m) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods get :: TransformT m Int Source # put :: Int -> TransformT m () Source # state :: (Int -> (a, Int)) -> TransformT m a Source #
Monad m => HasTransform (TransformT m) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods liftT :: Transform a -> TransformT m a Source #
Monad m => Applicative (TransformT m) Source # |

Instance details

Defined in Language.Haskell.GHC.ExactPrint.Transform

Methods

pure :: a -> TransformT m a Source #

(<*>) :: TransformT m (a -> b) -> TransformT m a -> TransformT m b Source #

liftA2 :: (a -> b -> c) -> TransformT m a -> TransformT m b -> TransformT m c Source #

(*>) :: TransformT m a -> TransformT m b -> TransformT m b Source #

(<*) :: TransformT m a -> TransformT m b -> TransformT m a Source #

Functor m => Functor (TransformT m) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods fmap :: (a -> b) -> TransformT m a -> TransformT m b Source # (<$) :: a -> TransformT m b -> TransformT m a Source #
Monad m => Monad (TransformT m) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods (>>=) :: TransformT m a -> (a -> TransformT m b) -> TransformT m b Source # (>>) :: TransformT m a -> TransformT m b -> TransformT m b Source # return :: a -> TransformT m a Source #
MonadFail m => MonadFail (TransformT m) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods fail :: String -> TransformT m a Source #
Monad m => MonadWriter [String] (TransformT m) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods writer :: (a, [String]) -> TransformT m a Source # tell :: [String] -> TransformT m () Source # listen :: TransformT m a -> TransformT m (a, [String]) Source # pass :: TransformT m (a, [String] -> [String]) -> TransformT m a Source #

hoistTransform :: (forall x. m x -> n x) -> TransformT m a -> TransformT n a Source #

Change inner monad of `TransformT`.

runTransform :: Transform a -> (a, Int, [String]) Source #

Run a transformation in the `Transform` monad, returning the updated annotations and any logging generated via `logTr`

runTransformT :: TransformT m a -> m (a, Int, [String]) Source #

runTransformFrom :: Int -> Transform a -> (a, Int, [String]) Source #

Run a transformation in the `Transform` monad, returning the updated annotations and any logging generated via `logTr`, allocating any new SrcSpans from the provided initial value.

runTransformFromT :: Int -> TransformT m a -> m (a, Int, [String]) Source #

Run a monad transformer stack for the `TransformT` monad transformer

# Transform monad operations

logTr :: forall (m :: Type -> Type). Monad m => String -> TransformT m () Source #

Log a string to the output of the Monad

logDataWithAnnsTr :: forall (m :: Type -> Type) a. (Monad m, Data a) => String -> a -> TransformT m () Source #

Log a representation of the given AST with annotations to the output of the Monad

uniqueSrcSpanT :: forall (m :: Type -> Type). Monad m => TransformT m SrcSpan Source #

If we need to add new elements to the AST, they need their own `SrcSpan` for this. This should no longer be needed, we use an `EpaDelta` location instead.

## Managing declarations, in Transform monad

class Monad m => HasTransform (m :: Type -> Type) where Source #

Used to integrate a `Transform` into other Monad stacks

Methods

liftT :: Transform a -> m a Source #

#### Instances

Instances details

Monad m => HasTransform (TransformT m) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods liftT :: Transform a -> TransformT m a Source #

class Data t => HasDecls t where Source #

Provide a means to get and process the immediate child declarations of a given AST element.

Methods

hsDecls :: t -> [LHsDecl GhcPs] Source #

Return the `HsDecl`s that are directly enclosed in the given syntax phrase. They are always returned in the wrapped `HsDecl` form, even if orginating in local decls. This is safe, as annotations never attach to the wrapper, only to the wrapped item.

replaceDecls :: t -> [LHsDecl GhcPs] -> t Source #

Replace the directly enclosed decl list by the given decl list. As parto of replacing it will update list order annotations, and rebalance comments and other layout changes as needed.

For example, a call on replaceDecls for a wrapped `FunBind` having no where clause will convert

    -- |This is a function
    foo = x -- comment1

in to

    -- |This is a function
    foo = x -- comment1
      where
        nn = 2

#### Instances

Instances details

HasDecls ParsedSource Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods hsDecls :: ParsedSource -> [LHsDecl GhcPs] Source # replaceDecls :: ParsedSource -> [LHsDecl GhcPs] -> ParsedSource Source #
HasDecls (LocatedA (HsDecl GhcPs)) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods hsDecls :: LocatedA (HsDecl GhcPs) -> [LHsDecl GhcPs] Source # replaceDecls :: LocatedA (HsDecl GhcPs) -> [LHsDecl GhcPs] -> LocatedA (HsDecl GhcPs) Source #
HasDecls (LocatedA (HsExpr GhcPs)) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods hsDecls :: LocatedA (HsExpr GhcPs) -> [LHsDecl GhcPs] Source # replaceDecls :: LocatedA (HsExpr GhcPs) -> [LHsDecl GhcPs] -> LocatedA (HsExpr GhcPs) Source #
HasDecls (LocatedA (Match GhcPs (LocatedA (HsExpr GhcPs)))) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods hsDecls :: LocatedA (Match GhcPs (LocatedA (HsExpr GhcPs))) -> [LHsDecl GhcPs] Source # replaceDecls :: LocatedA (Match GhcPs (LocatedA (HsExpr GhcPs))) -> [LHsDecl GhcPs] -> LocatedA (Match GhcPs (LocatedA (HsExpr GhcPs))) Source #
HasDecls (LocatedA (Stmt GhcPs (LocatedA (HsExpr GhcPs)))) Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods hsDecls :: LocatedA (Stmt GhcPs (LocatedA (HsExpr GhcPs))) -> [LHsDecl GhcPs] Source # replaceDecls :: LocatedA (Stmt GhcPs (LocatedA (HsExpr GhcPs))) -> [LHsDecl GhcPs] -> LocatedA (Stmt GhcPs (LocatedA (HsExpr GhcPs))) Source #

hsDeclsPatBind :: LHsBind GhcPs -> [LHsDecl GhcPs] Source #

Extract the immediate declarations for a `PatBind`. This cannot be a member of `HasDecls` because a `FunBind` is not idempotent for `hsDecls` / `replaceDecls`. `hsDeclsPatBind` / `replaceDeclsPatBind` is idempotent.

hsDeclsPatBindD :: LHsDecl GhcPs -> [LHsDecl GhcPs] Source #

Extract the immediate declarations for a `PatBind` wrapped in a `ValD`. This cannot be a member of `HasDecls` because a `FunBind` is not idempotent for `hsDecls` / `replaceDecls`. `hsDeclsPatBindD` / `replaceDeclsPatBindD` is idempotent.

replaceDeclsPatBind :: LHsBind GhcPs -> [LHsDecl GhcPs] -> LHsBind GhcPs Source #

Replace the immediate declarations for a `PatBind`. This cannot be a member of `HasDecls` because a `FunBind` is not idempotent for `hsDecls` / `replaceDecls`. `hsDeclsPatBind` / `replaceDeclsPatBind` is idempotent.

replaceDeclsPatBindD :: LHsDecl GhcPs -> [LHsDecl GhcPs] -> LHsDecl GhcPs Source #

Replace the immediate declarations for a `PatBind` wrapped in a `ValD`. This cannot be a member of `HasDecls` because a `FunBind` is not idempotent for `hsDecls` / `replaceDecls`. `hsDeclsPatBindD` / `replaceDeclsPatBindD` is idempotent.

modifyDeclsT :: (HasDecls t, HasTransform m) => ([LHsDecl GhcPs] -> m [LHsDecl GhcPs]) -> t -> m t Source #

Apply a transformation to the decls contained in `t`

modifyValD :: SrcSpan -> Decl -> (PMatch -> [Decl] -> ([Decl], Maybe t)) -> (Decl, Maybe t) Source #

Modify a `LHsBind` wrapped in a `ValD`. For a `PatBind` the declarations are extracted and returned after modification. For a `FunBind` the supplied `SrcSpan` is used to identify the specific `Match` to be transformed, for when there are multiple of them.

### Utility, does not manage layout

hsDeclsValBinds :: HsValBindsLR GhcPs GhcPs -> [LHsDecl GhcPs] Source #

replaceDeclsValbinds :: WithWhere -> HsLocalBinds GhcPs -> [LHsDecl GhcPs] -> HsLocalBinds GhcPs Source #

Utility function for returning decls to `HsLocalBinds`. Use with care, as this does not manage the declaration order, the ordering should be done by the calling function from the `HsLocalBinds` context in the AST.

data WithWhere Source #

Constructors

WithWhere |
WithoutWhere |

#### Instances

Instances details

Show WithWhere Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods showsPrec :: Int -> WithWhere -> ShowS Source # show :: WithWhere -> String Source # showList :: [WithWhere] -> ShowS Source #
Eq WithWhere Source # |
Instance details Defined in Language.Haskell.GHC.ExactPrint.Transform Methods (==) :: WithWhere -> WithWhere -> Bool Source # (/=) :: WithWhere -> WithWhere -> Bool Source #

## New gen functions

noAnnSrcSpanDP :: NoAnn ann => DeltaPos -> EpAnn ann Source #

Create a `SrcSpanAnn` with a `MovedAnchor` operation using the given `DeltaPos`.

noAnnSrcSpanDP0 :: NoAnn ann => EpAnn ann Source #

noAnnSrcSpanDP1 :: NoAnn ann => EpAnn ann Source #

noAnnSrcSpanDPn :: NoAnn ann => Int -> EpAnn ann Source #

d0 :: EpaLocation Source #

d1 :: EpaLocation Source #

dn :: Int -> EpaLocation Source #

addComma :: SrcSpanAnnA -> SrcSpanAnnA Source #

## Managing lists, Transform monad

insertAt :: HasDecls ast => (LHsDecl GhcPs -> [LHsDecl GhcPs] -> [LHsDecl GhcPs]) -> ast -> LHsDecl GhcPs -> ast Source #

Insert a declaration into an AST element having sub-declarations (`HasDecls`) according to the given location function.

insertAtStart :: HasDecls ast => ast -> LHsDecl GhcPs -> ast Source #

Insert a declaration at the beginning or end of the subdecls of the given AST item

insertAtEnd :: HasDecls ast => ast -> LHsDecl GhcPs -> ast Source #

Insert a declaration at the beginning or end of the subdecls of the given AST item

insertAfter :: HasDecls (LocatedA ast) => LocatedA old -> LocatedA ast -> LHsDecl GhcPs -> LocatedA ast Source #

Insert a declaration at a specific location in the subdecls of the given AST item

insertBefore :: HasDecls (LocatedA ast) => LocatedA old -> LocatedA ast -> LHsDecl GhcPs -> LocatedA ast Source #

Insert a declaration at a specific location in the subdecls of the given AST item

### Low level operations used in `HasDecls`

balanceComments :: LHsDecl GhcPs -> LHsDecl GhcPs -> (LHsDecl GhcPs, LHsDecl GhcPs) Source #

The GHC parser puts all comments appearing between the end of one AST item and the beginning of the next as `annPriorComments` for the second one. This function takes two adjacent AST items and moves any `annPriorComments` from the second one to the `annFollowingComments` of the first if they belong to it instead. This is typically required before deleting or duplicating either of the AST elements.

balanceCommentsList :: [LHsDecl GhcPs] -> [LHsDecl GhcPs] Source #

If we compile in haddock mode we get DocDecls, which we strip out while exact printing. Make sure we do not balance any comments on to them be stripping them out here already.

balanceCommentsListA :: [LocatedA a] -> [LocatedA a] Source #

anchorEof :: ParsedSource -> ParsedSource Source #

## Managing lists, pure functions

captureOrderBinds :: [LHsDecl GhcPs] -> AnnSortKey BindTag Source #

captureLineSpacing :: [LocatedA e] -> [LocatedA e] Source #

captureMatchLineSpacing :: LHsDecl GhcPs -> LHsDecl GhcPs Source #

captureTypeSigSpacing :: LHsDecl GhcPs -> LHsDecl GhcPs Source #

# Operations

isUniqueSrcSpan :: SrcSpan -> Bool Source #

Test whether a given `SrcSpan` was generated by `uniqueSrcSpanT`

# Pure functions

setEntryDP :: LocatedAn t a -> DeltaPos -> LocatedAn t a Source #

Set the true entry `DeltaPos` from the annotation for a given AST element. This is the `DeltaPos` ignoring any comments.

setEntryDPDecl :: LHsDecl GhcPs -> DeltaPos -> LHsDecl GhcPs Source #

getEntryDP :: LocatedAn t a -> DeltaPos Source #

transferEntryDP :: (Typeable t1, Typeable t2) => LocatedAn t1 a -> LocatedAn t2 b -> LocatedAn t2 b Source #

Take the annEntryDelta associated with the first item and associate it with the second. Also transfer any comments occurring before it.

transferEntryDP' :: LHsDecl GhcPs -> LHsDecl GhcPs -> LHsDecl GhcPs Source #

Take the annEntryDelta associated with the first item and associate it with the second. Also transfer any comments occurring before it. TODO: call transferEntryDP, and use pushDeclDP

wrapSig :: LSig GhcPs -> LHsDecl GhcPs Source #

Convert a `LSig` into a `LHsDecl`

wrapDecl :: LHsBind GhcPs -> LHsDecl GhcPs Source #

Convert a `LHsBind` into a `LHsDecl`

decl2Sig :: LHsDecl GhcPs -> [LSig GhcPs] Source #

Pure function to convert a `LSig` to a `LHsBind`. This does nothing to any annotations that may be attached to either of the elements. It is used as a utility function in `replaceDecls`

decl2Bind :: LHsDecl GhcPs -> [LHsBind GhcPs] Source #

Pure function to convert a `LHsDecl` to a `LHsBind`. This does nothing to any annotations that may be attached to either of the elements. It is used as a utility function in `replaceDecls`