-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | HIE-based Haskell call graph and source code visualizer
--   
--   Calligraphy is a Haskell call graph/source code visualizer. It works
--   directly on GHC-generated HIE files, giving us features that would
--   otherwise be tricky, like type information and support for generated
--   files. Calligraphy has been tested with all versions of GHC that can
--   produce HIE files (i.e. GHC 8.8, 8.10, 9.0, and 9.2.) See the
--   project's github page for more information.
@package calligraphy
@version 0.1.2


-- | Thin compatability layer that re-exports things from GHC.
module Calligraphy.Compat.GHC
data BindType
RegularBind :: BindType
InstanceBind :: BindType

-- | Different contexts under which identifiers exist
data ContextInfo

-- | regular variable
Use :: ContextInfo
MatchBind :: ContextInfo

-- | import/export
IEThing :: IEType -> ContextInfo
TyDecl :: ContextInfo

-- | Value binding
ValBind :: BindType -> Scope -> Maybe Span -> ContextInfo

-- | Pattern binding
--   
--   This case is tricky because the bound identifier can be used in two
--   distinct scopes. Consider the following example (with
--   <tt>-XViewPatterns</tt>)
--   
--   <pre>
--   do (b, a, (a -&gt; True)) &lt;- bar
--      foo a
--   </pre>
--   
--   The identifier <tt>a</tt> has two scopes: in the view pattern <tt>(a
--   -&gt; True)</tt> and in the rest of the <tt>do</tt>-block in <tt>foo
--   a</tt>.
PatternBind :: Scope -> Scope -> Maybe Span -> ContextInfo
ClassTyDecl :: Maybe Span -> ContextInfo

-- | Declaration
Decl :: DeclType -> Maybe Span -> ContextInfo

-- | Type variable
TyVarBind :: Scope -> TyVarScope -> ContextInfo

-- | Record field
RecField :: RecFieldContext -> Maybe Span -> ContextInfo
data DeclType

-- | type or data family
FamDec :: DeclType

-- | type synonym
SynDec :: DeclType

-- | data declaration
DataDec :: DeclType

-- | constructor declaration
ConDec :: DeclType

-- | pattern synonym
PatSynDec :: DeclType

-- | class declaration
ClassDec :: DeclType

-- | instance declaration
InstDec :: DeclType
data HieAST a
Node :: NodeInfo a -> Span -> [HieAST a] -> HieAST a
[nodeInfo] :: HieAST a -> NodeInfo a
[nodeSpan] :: HieAST a -> Span
[nodeChildren] :: HieAST a -> [HieAST a]

-- | Mapping from filepaths (represented using <a>FastString</a>) to the
--   corresponding AST
newtype HieASTs a
HieASTs :: Map FastString (HieAST a) -> HieASTs a
[getAsts] :: HieASTs a -> Map FastString (HieAST a)

-- | GHC builds up a wealth of information about Haskell source as it
--   compiles it. <tt>.hie</tt> files are a way of persisting some of this
--   information to disk so that external tools that need to work with
--   haskell source don't need to parse, typecheck, and rename all over
--   again. These files contain:
--   
--   <ul>
--   <li>a simplified AST<ul><li>nodes are annotated with source positions
--   and types</li><li>identifiers are annotated with scope
--   information</li></ul></li>
--   <li>the raw bytes of the initial Haskell source</li>
--   </ul>
--   
--   Besides saving compilation cycles, <tt>.hie</tt> files also offer a
--   more stable interface than the GHC API.
data HieFile
HieFile :: FilePath -> Module -> Array TypeIndex HieTypeFlat -> HieASTs TypeIndex -> [AvailInfo] -> ByteString -> HieFile

-- | Initial Haskell source file path
[hie_hs_file] :: HieFile -> FilePath

-- | The module this HIE file is for
[hie_module] :: HieFile -> Module

-- | Types referenced in the <a>hie_asts</a>.
--   
--   See Note [Efficient serialization of redundant type info]
[hie_types] :: HieFile -> Array TypeIndex HieTypeFlat

-- | Type-annotated abstract syntax trees
[hie_asts] :: HieFile -> HieASTs TypeIndex

-- | The names that this module exports
[hie_exports] :: HieFile -> [AvailInfo]

-- | Raw bytes of the initial Haskell source
[hie_hs_src] :: HieFile -> ByteString
data HieFileResult
HieFileResult :: Integer -> ByteString -> HieFile -> HieFileResult
[hie_file_result_version] :: HieFileResult -> Integer
[hie_file_result_ghc_version] :: HieFileResult -> ByteString
[hie_file_result] :: HieFileResult -> HieFile

-- | A flattened version of <tt>Type</tt>.
--   
--   See Note [Efficient serialization of redundant type info]
data HieType a
HTyVarTy :: Name -> HieType a
HAppTy :: a -> HieArgs a -> HieType a
HTyConApp :: IfaceTyCon -> HieArgs a -> HieType a
HForAllTy :: ((Name, a), ArgFlag) -> a -> HieType a
HFunTy :: a -> a -> HieType a

-- | type with constraint: <tt>t1 =&gt; t2</tt> (see <tt>IfaceDFunTy</tt>)
HQualTy :: a -> a -> HieType a
HLitTy :: IfaceTyLit -> HieType a
HCastTy :: a -> HieType a
HCoercionTy :: HieType a
type HieTypeFlat = HieType TypeIndex
type Identifier = Either ModuleName Name

-- | Information associated with every identifier
--   
--   We need to include types with identifiers because sometimes multiple
--   identifiers occur in the same span(Overloaded Record Fields and so on)
data IdentifierDetails a
IdentifierDetails :: Maybe a -> Set ContextInfo -> IdentifierDetails a
[identType] :: IdentifierDetails a -> Maybe a
[identInfo] :: IdentifierDetails a -> Set ContextInfo
data IfaceTyCon
IfaceTyCon :: IfExtName -> IfaceTyConInfo -> IfaceTyCon
[ifaceTyConName] :: IfaceTyCon -> IfExtName
[ifaceTyConInfo] :: IfaceTyCon -> IfaceTyConInfo

-- | A ModuleName is essentially a simple string, e.g. <tt>Data.List</tt>.
data ModuleName

-- | A unique, unambiguous name for something, containing information about
--   where that thing originated.
data Name

-- | The NameCache makes sure that there is just one Unique assigned for
--   each original name; i.e. (module-name, occ-name) pair and provides
--   something of a lookup mechanism for those names.
data NameCache

-- | The information stored in one AST node.
--   
--   The type parameter exists to provide flexibility in representation of
--   types (see Note [Efficient serialization of redundant type info]).
data NodeInfo a
NodeInfo :: Set (FastString, FastString) -> [a] -> NodeIdentifiers a -> NodeInfo a

-- | (name of the AST node constructor, name of the AST node Type)
[nodeAnnotations] :: NodeInfo a -> Set (FastString, FastString)

-- | The Haskell types of this node, if any.
[nodeType] :: NodeInfo a -> [a]

-- | All the identifiers and their details
[nodeIdentifiers] :: NodeInfo a -> NodeIdentifiers a

-- | Real Source Location
--   
--   Represents a single point within a file
data RealSrcLoc

-- | A <a>RealSrcSpan</a> delimits a portion of a text file. It could be
--   represented by a pair of (line,column) coordinates, but in fact we
--   optimise slightly by using more compact representations for
--   single-line and zero-length spans, both of which are quite common.
--   
--   The end position is defined to be the column <i>after</i> the end of
--   the span. That is, a span of (1,1)-(1,2) is one character long, and a
--   span of (1,1)-(1,1) is zero characters long.
--   
--   Real Source Span
data RealSrcSpan
data RecFieldContext
RecFieldDecl :: RecFieldContext
RecFieldAssign :: RecFieldContext
RecFieldMatch :: RecFieldContext
RecFieldOcc :: RecFieldContext
data Scope
NoScope :: Scope
LocalScope :: Span -> Scope
ModuleScope :: Scope
type Span = RealSrcSpan
type TypeIndex = Int

-- | All names made available by the availability information (excluding
--   overloaded selectors)
availNames :: AvailInfo -> [Name]
getKey :: Unique -> Int
getOccString :: NamedThing a => a -> String

-- | Current version of <tt>.hie</tt> files
hieVersion :: Integer

-- | Return a function to atomically update the name cache.
initNameCache :: UniqSupply -> [Name] -> NameCache

-- | Create a unique supply out of thin air. The character given must be
--   distinct from those of all calls to this function in the compiler for
--   the values generated to be truly unique.
mkSplitUniqSupply :: Char -> IO UniqSupply
moduleName :: Module -> ModuleName
moduleNameString :: ModuleName -> String
nameUnique :: Name -> Unique
realSrcSpanEnd :: RealSrcSpan -> RealSrcLoc
realSrcSpanStart :: RealSrcSpan -> RealSrcLoc
srcSpanStartCol :: RealSrcSpan -> Int
srcSpanStartLine :: RealSrcSpan -> Int
srcSpanEndCol :: RealSrcSpan -> Int
srcSpanEndLine :: RealSrcSpan -> Int

-- | Raises an error when used on a "bad" <a>SrcLoc</a>
srcLocCol :: RealSrcLoc -> Int

-- | Raises an error when used on a "bad" <a>SrcLoc</a>
srcLocLine :: RealSrcLoc -> Int

module Calligraphy.Util.Lens
type Traversal s t a b = forall m. Applicative m => (a -> m b) -> (s -> m t)
type Traversal' s a = Traversal s s a a
over :: Traversal s t a b -> (a -> b) -> s -> t
forT_ :: Applicative m => Traversal s t a b -> s -> (a -> m ()) -> m ()
instance GHC.Base.Functor (Calligraphy.Util.Lens.ConstT m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Calligraphy.Util.Lens.ConstT m)

module Calligraphy.Compat.Lib
sourceInfo :: Traversal' (HieAST a) (NodeInfo a)
showContextInfo :: ContextInfo -> String
readHieFileCompat :: IORef NameCache -> FilePath -> IO HieFileResult
isInstanceNode :: NodeInfo a -> Bool
isTypeSignatureNode :: NodeInfo a -> Bool
isInlineNode :: NodeInfo a -> Bool
isMinimalNode :: NodeInfo a -> Bool
isDerivingNode :: NodeInfo a -> Bool
showAnns :: NodeInfo a -> String
mergeSpans :: Span -> Span -> Span
isPointSpan :: Span -> Bool

module Calligraphy.Phases.Search
searchFiles :: SearchConfig -> IO [HieFile]
pSearchConfig :: Parser SearchConfig
data SearchConfig


-- | A <a>LexTree</a> is a map designed to reconstruct the lexical
--   structure (tree of scopes) of a source file, given an unordered list
--   of scopes. Values are inserted with a pair source locations as its
--   key. For a given key, we can then ask what the smallest enclosing
--   scope is.
--   
--   For example, in the snippet below the smallest scope containing
--   <tt>x</tt> is <tt>b</tt>. <tt> x | a | | b | | c | </tt>
--   
--   Scopes are not allowed to overlap.
--   
--   The purpose of this data structure is to find out what surrounding
--   definition a certain use site belongs to.
module Calligraphy.Util.LexTree
data LexTree p a
Tip :: LexTree p a
Bin :: {-# UNPACK #-} !Int -> !LexTree p a -> !p -> a -> !LexTree p a -> !p -> !LexTree p a -> LexTree p a
data TreeError p a

-- | Nonsensical bounds, i.e. a left-hand bound larger than the right-hand
--   obund
InvalidBounds :: p -> a -> p -> TreeError p a

-- | Two identical scopes
OverlappingBounds :: a -> a -> p -> p -> TreeError p a

-- | An attempt to split halfway through a scope, usually the result of two
--   partially overlapping scopes
MidSplit :: TreeError p a

-- | Attempting to insert a scope that would not form a tree structure
LexicalError :: p -> a -> p -> LexTree p a -> TreeError p a
lookup :: Ord p => p -> LexTree p a -> Maybe a
lookupOuter :: Ord p => p -> LexTree p a -> Maybe a
insert :: Ord p => p -> a -> p -> LexTree p a -> Either (TreeError p a) (LexTree p a)
emptyLexTree :: LexTree p a
foldLexTree :: r -> (r -> p -> a -> r -> p -> r -> r) -> LexTree p a -> r
toForest :: LexTree p a -> Forest (p, a, p)
insertWith :: Ord p => (a -> a -> Maybe a) -> p -> a -> p -> LexTree p a -> Either (TreeError p a) (LexTree p a)
height :: LexTree p a -> Int
toList :: LexTree p a -> [(p, a, p)]

-- | Only works if the height difference of the two trees is at most 2
bin :: LexTree p a -> p -> a -> LexTree p a -> p -> LexTree p a -> LexTree p a
shift :: Num p => p -> LexTree p a -> LexTree p a
instance Data.Traversable.Traversable (Calligraphy.Util.LexTree.LexTree p)
instance Data.Foldable.Foldable (Calligraphy.Util.LexTree.LexTree p)
instance GHC.Base.Functor (Calligraphy.Util.LexTree.LexTree p)
instance (GHC.Show.Show p, GHC.Show.Show a) => GHC.Show.Show (Calligraphy.Util.LexTree.LexTree p a)
instance (GHC.Show.Show p, GHC.Show.Show a) => GHC.Show.Show (Calligraphy.Util.LexTree.TreeError p a)
instance (GHC.Classes.Eq p, GHC.Classes.Eq a) => GHC.Classes.Eq (Calligraphy.Util.LexTree.TreeError p a)
instance Data.Traversable.Traversable (Calligraphy.Util.LexTree.TreeError p)
instance Data.Foldable.Foldable (Calligraphy.Util.LexTree.TreeError p)
instance GHC.Base.Functor (Calligraphy.Util.LexTree.TreeError p)
instance (GHC.Classes.Eq p, GHC.Classes.Eq a) => GHC.Classes.Eq (Calligraphy.Util.LexTree.LexTree p a)

module Calligraphy.Util.Optparse

-- | Enable/disable flags for a <a>Bool</a>.
boolFlags :: Bool -> String -> String -> Mod FlagFields Bool -> Parser Bool

module Calligraphy.Util.Printer
newtype Printer a
Printer :: RWS Int () Builder a -> Printer a
[unPrinter] :: Printer a -> RWS Int () Builder a
type Prints a = a -> Printer ()
runPrinter :: Printer () -> Text
class Monad m => MonadPrint m
line :: MonadPrint m => Builder -> m ()
indent :: MonadPrint m => m a -> m a
brack :: MonadPrint m => String -> String -> m a -> m a
strLn :: MonadPrint m => String -> m ()
textLn :: MonadPrint m => Text -> m ()
showLn :: (MonadPrint m, Show a) => a -> m ()
instance GHC.Base.Monoid a => GHC.Base.Monoid (Calligraphy.Util.Printer.Printer a)
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Calligraphy.Util.Printer.Printer a)
instance GHC.Base.Monad Calligraphy.Util.Printer.Printer
instance GHC.Base.Applicative Calligraphy.Util.Printer.Printer
instance GHC.Base.Functor Calligraphy.Util.Printer.Printer
instance Calligraphy.Util.Printer.MonadPrint Calligraphy.Util.Printer.Printer
instance Calligraphy.Util.Printer.MonadPrint m => Calligraphy.Util.Printer.MonadPrint (Control.Monad.Trans.State.Lazy.StateT s m)


-- | Debug tools for GHC-related data
module Calligraphy.Compat.Debug
ppHieFile :: Prints HieFile
ppIdentifier :: Prints Identifier
showGHCName :: Name -> String

module Calligraphy.Util.Types

-- | This is the main type that processing phases will operate on. Note
--   that calls and typing judgments are part of this top-level structure,
--   not of the individual modules.
data CallGraph
CallGraph :: [Module] -> Set (Key, Key) -> Set (Key, Key) -> CallGraph
[_modules] :: CallGraph -> [Module]
[_calls] :: CallGraph -> Set (Key, Key)
[_types] :: CallGraph -> Set (Key, Key)
data Module
Module :: String -> FilePath -> Forest Decl -> Module
[moduleName] :: Module -> String
[modulePath] :: Module -> FilePath
[moduleForest] :: Module -> Forest Decl
data Decl
Decl :: String -> Key -> EnumSet GHCKey -> Bool -> DeclType -> Loc -> Decl
[declName] :: Decl -> String
[declKey] :: Decl -> Key
[declGHCKeys] :: Decl -> EnumSet GHCKey
[declExported] :: Decl -> Bool
[declType] :: Decl -> DeclType
[declLoc] :: Decl -> Loc
data DeclType
ValueDecl :: DeclType
RecDecl :: DeclType
ConDecl :: DeclType
DataDecl :: DeclType
ClassDecl :: DeclType

-- | A key in our own local space, c.f. a key that was generated by GHC.
newtype Key
Key :: Int -> Key
[unKey] :: Key -> Int

-- | A key that was produced by GHC, c.f. Key that we produced ourselves.
--   We wrap it in a newtype because GHC itself uses a type synonym, but we
--   want conversions to be as explicit as possible.
newtype GHCKey
GHCKey :: Int -> GHCKey
[unGHCKey] :: GHCKey -> Int
data Loc
Loc :: !Int -> !Int -> Loc
[locLine] :: Loc -> !Int
[locCol] :: Loc -> !Int
rekeyCalls :: (Enum a, Ord b) => EnumMap a b -> Set (a, a) -> Set (b, b)
ppCallGraph :: Prints CallGraph
over :: Traversal s t a b -> (a -> b) -> s -> t
forT_ :: Applicative m => Traversal s t a b -> s -> (a -> m ()) -> m ()
modForest :: Traversal' Module (Forest Decl)
modDecls :: Traversal' Module Decl
forestT :: Traversal (Forest a) (Forest b) a b
instance GHC.Classes.Ord Calligraphy.Util.Types.Key
instance GHC.Classes.Eq Calligraphy.Util.Types.Key
instance GHC.Show.Show Calligraphy.Util.Types.Key
instance GHC.Enum.Enum Calligraphy.Util.Types.Key
instance GHC.Classes.Ord Calligraphy.Util.Types.GHCKey
instance GHC.Classes.Eq Calligraphy.Util.Types.GHCKey
instance GHC.Enum.Enum Calligraphy.Util.Types.GHCKey
instance GHC.Show.Show Calligraphy.Util.Types.GHCKey
instance GHC.Show.Show Calligraphy.Util.Types.DeclType
instance GHC.Classes.Ord Calligraphy.Util.Types.DeclType
instance GHC.Classes.Eq Calligraphy.Util.Types.DeclType
instance GHC.Classes.Ord Calligraphy.Util.Types.Loc
instance GHC.Classes.Eq Calligraphy.Util.Types.Loc
instance GHC.Show.Show Calligraphy.Util.Types.Loc


-- | Rendering takes a callgraph, and produces a dot file
module Calligraphy.Phases.Render
render :: RenderConfig -> Prints CallGraph
pRenderConfig :: Parser RenderConfig
data RenderConfig
RenderConfig :: Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> LocMode -> Bool -> Bool -> Bool -> Bool -> RenderConfig
[showCalls] :: RenderConfig -> Bool
[showTypes] :: RenderConfig -> Bool
[showKey] :: RenderConfig -> Bool
[showGHCKeys] :: RenderConfig -> Bool
[showModulePath] :: RenderConfig -> Bool
[showChildArrowhead] :: RenderConfig -> Bool
[locMode] :: RenderConfig -> LocMode
[clusterModules] :: RenderConfig -> Bool
[clusterGroups] :: RenderConfig -> Bool
[splines] :: RenderConfig -> Bool
[reverseDependencyRank] :: RenderConfig -> Bool

module Calligraphy.Phases.Parse
parseHieFiles :: [HieFile] -> Either ParseError (ParsePhaseDebugInfo, CallGraph)
ppParseError :: Prints ParseError
ppParsePhaseDebugInfo :: Prints ParsePhaseDebugInfo
data ParseError
TreeError :: String -> FilePath -> TreeError Loc RawDecl -> ParseError
[_peModuleName] :: ParseError -> String
[_peModulePath] :: ParseError -> FilePath
[_peError] :: ParseError -> TreeError Loc RawDecl
newtype ParsePhaseDebugInfo
ParsePhaseDebugInfo :: [(String, LexTree Loc RawDecl)] -> ParsePhaseDebugInfo
[modulesLexTrees] :: ParsePhaseDebugInfo -> [(String, LexTree Loc RawDecl)]
instance GHC.Base.Semigroup Calligraphy.Phases.Parse.IdentifierType
instance GHC.Base.Monoid Calligraphy.Phases.Parse.IdentifierType
instance (GHC.Classes.Ord k, GHC.Base.Semigroup v) => GHC.Base.Semigroup (Calligraphy.Phases.Parse.Dedup k v)


-- | This modules manages the two ways we remove nodes from a graph;
--   collapsing and hiding.
--   
--   Collapsing means absorbing a node's descendants into itself, including
--   all edges.
--   
--   Hiding means removing a node (and its descendants), moving the edges
--   to the node's parent, if a parent exist.
--   
--   There's also the special option --collapse-modules. It's undeniably a
--   little hacky, but for now this is the best home for that
--   functionality. Functionality-wise, it's still essentially just
--   collapsing nodes into one another. The thing that makes it hacky is
--   that it then uses a value node to represent a module. This is not
--   actually a huge deal, because no other module actually cares about the
--   node type, but it's something to watch out for. There's more design
--   discussion on <a>https://github.com/jonascarpay/calligraphy/pull/5</a>
module Calligraphy.Phases.NodeFilter
filterNodes :: NodeFilterConfig -> CallGraph -> CallGraph
data NodeFilterConfig
NodeFilterConfig :: Bool -> Bool -> Mode -> Mode -> Mode -> Mode -> Bool -> NodeFilterConfig
[hideLocals] :: NodeFilterConfig -> Bool
[collapseModules] :: NodeFilterConfig -> Bool
[collapseClasses] :: NodeFilterConfig -> Mode
[collapseData] :: NodeFilterConfig -> Mode
[collapseValues] :: NodeFilterConfig -> Mode
[collapseConstructors] :: NodeFilterConfig -> Mode
[hideRecords] :: NodeFilterConfig -> Bool
pNodeFilterConfig :: Parser NodeFilterConfig
instance GHC.Show.Show Calligraphy.Phases.NodeFilter.Mode
instance GHC.Classes.Eq Calligraphy.Phases.NodeFilter.Mode


-- | This modules collects some opinionated common-sense heuristics for
--   removing edges that are probably redundant.
module Calligraphy.Phases.EdgeCleanup
data EdgeCleanupConfig
cleanupEdges :: EdgeCleanupConfig -> CallGraph -> CallGraph
pEdgeCleanupConfig :: Parser EdgeCleanupConfig


-- | Dependency filtering is removing all nodes that are not part of a
--   certain dependency tree
module Calligraphy.Phases.DependencyFilter
data DependencyFilterConfig
newtype DependencyFilterError
UnknownRootName :: String -> DependencyFilterError
ppFilterError :: Prints DependencyFilterError
dependencyFilter :: DependencyFilterConfig -> CallGraph -> Either DependencyFilterError CallGraph
pDependencyFilterConfig :: Parser DependencyFilterConfig

module Calligraphy
main :: IO ()
mainWithConfig :: AppConfig -> IO ()