Define a custom refactoring script. A script is an IO action that defines a Retrie computation. The IO action is run once, and the resulting Retrie computation is run once for each target file. Typically, rewrite parsing/construction is done in the IO action, so it is performed only once. Example:

module Main where

main :: IO ()
main = runScript $ \opts -> do
  rr <- parseRewrites opts ["forall f g xs. map f (map g xs) = map (f . g) xs"]
  return $ apply rr

To run the script, compile the program and execute it.

Define a custom refactoring script and run it with modified options. This is the same as runScript, but the returned Options will be used during rewriting.

Parse import statements. Each string must be a full import statement, including the keyword 'import'. Supports full import syntax.

Create Querys from string specifications of expressionstypesstatements.

Specifies which parser to use in parseQueries.

Create Rewrites from string specifications of rewrites.

Possible ways to specify rewrites to parseRewrites.

A qualified name. (e.g. "Module.Name.functionName")

The Retrie monad is essentially IO, plus state containing the module that is being transformed. It is run once per target file.

It is special because it also allows Retrie to extract a set of GroundTerms from the Retrie computation without evaluating it.

Retrie uses the ground terms to select which files to target. This is the key optimization that allows Retrie to handle large codebases.

Note: Due to technical limitations, we cannot extract ground terms if you use liftIO before calling one of apply, focus, or query at least once. This will cause Retrie to attempt to parse every module in the target directory. In this case, please add a call to focus before the call to liftIO.

Apply a set of rewrites. By default, rewrites are applied top-down, pruning the traversal at successfully changed AST nodes. See topDownPrune.

Apply a set of rewrites with a custom traversal strategy.

Apply a set of rewrites with a custom context-update function.

Apply a set of rewrites with custom context-update and traversal strategy.

Add imports to the module.

If the first Retrie computation makes a change to the module, run the second Retrie computation.

Iterate given Retrie computation until it no longer makes changes, or N times, whichever happens first.

Use the given queries/rewrites to select files for rewriting. Does not actually perform matching. This is useful if the queries/rewrites which best determine which files to target are not the first ones you run, and when you need to liftIO before running any queries/rewrites.

Query the AST. Each match returns the context of the match, a substitution mapping quantifiers to matched subtrees, and the query's value.

Query the AST with a custom context update function.

Perform a bottom-up traversal.

Perform a top-down traversal.

Top-down traversal that does not descend into changed AST nodes. Default strategy used by apply.

A MatchResultTransformer allows the user to specify custom logic to modify the result of matching the left-hand side of a rewrite (the MatchResult). The MatchResult generated by this function is used to effect the resulting AST rewrite.

For example, this transformer looks at the matched expression to build the resulting expression:

fancyMigration :: MatchResultTransformer
fancyMigration ctxt matchResult
  | MatchResult sub t <- matchResult
  , HoleExpr e <- lookupSubst sub "x" = do
    e' <- ... some fancy IO computation using 'e' ...
    return $ MatchResult (extendSubst sub "x" (HoleExpr e')) t
  | otherwise = NoMatch

main :: IO ()
main = runScript $ \opts -> do
  rrs <- parseRewrites opts [Adhoc "forall x. ... = ..."]
  return $ apply
    [ setRewriteTransformer fancyMigration rr | rr <- rrs ]

Since the MatchResultTransformer can also modify the Template, you can construct an entirely novel right-hand side, add additional imports, or inject new dependent rewrites.

The default transformer. Returns the MatchResult unchanged.

The result of matching the left-hand side of a Rewrite.

Annotated packages an AST fragment with the annotations necessary to exactPrint or transform that AST.

Examine the actual AST.

Parse a top-level HsDecl.

Parse a HsExpr.

Parse a Pat.

Parse a Stmt.

Parse a HsType.

Transform an Annotated thing.

Graft an Annotated thing into the current transformation. The resulting AST will have proper annotations within the TransformT computation. For example:

mkDeclList :: IO (Annotated [LHsDecl GhcPs])
mkDeclList = do
  ad1 <- parseDecl "myId :: a -> a"
  ad2 <- parseDecl "myId x = x"
  transformA ad1 $ \ d1 -> do
    d2 <- graftA ad2
    return [d1, d2]

Encapsulate something in the current transformation into an Annotated thing. This is the inverse of graftT. For example:

splitHead :: Monad m => Annotated [a] -> m (Annotated a, Annotated [a])
splitHead l = fmap astA $ transformA l $ \(x:xs) -> do
  y <- pruneA x
  ys <- pruneA xs
  return (y, ys)

Trim the annotation data to only include annotations for ast. (Usually, the annotation data is a superset of what is necessary.) Also freshens all source locations, so filename information in annotation keys is discarded.

Note: not commonly needed, but useful if you want to inspect the annotation data directly and don't want to wade through a mountain of output.

Exactprint an Annotated thing.

Context maintained by AST traversals.

Type of context update functions for apply. When defining your own ContextUpdater, you probably want to extend updateContext using SYB combinators such as mkQ and extQ.

Default context update function.

Command-line options.

Query is the primitive way to specify a matchable pattern (quantifiers and expression). Whenever the pattern is matched, the associated result will be returned.

A Rewrite is a Query specialized to Template results, which have all the information necessary to replace one expression with another.

The right-hand side of a Rewrite.

Make a Rewrite from given quantifiers and left- and right-hand sides.

Pretty-print a Rewrite for debugging.

Add imports to a Rewrite. Whenever the Rewrite successfully rewrites an expression, the imports are inserted into the enclosing module.

Set the MatchResultTransformer for a Rewrite.

Perform the given Substitution on an AST, avoiding variable capture by alpha-renaming binders as needed.

A sum type to collect all possible top-level rewritable types.

Class of types which can be injected into the Universe type.

Inject a type-specific rewrite into the universal type.

Project a type-specific rewrite from the universal type.