CloogleDB.dcl

definition module CloogleDB

from StdOverloaded import class ==, class <, class zero
from StdClass import class Ord

from Data.GenEq import generic gEq
from Data.Map import :: Map
from Data.Maybe import :: Maybe
from System.FilePath import :: FilePath
from Text.GenJSON import generic JSONEncode, generic JSONDecode, :: JSONNode

from Type import :: Type, :: TypeVar, :: TVAssignment, :: TypeDef,
	:: TypeContext, :: TypeRestriction, :: Priority, class print(..)

from Cloogle import :: FunctionKind, :: SyntaxExample, :: CleanLangReportLocation

from Doc import :: FunctionDoc, :: TypeDoc, :: ClassDoc, :: ModuleDoc
from DB import :: DB, :: Entry, :: Index
from NGramIndex import :: NGramIndex
from TypeTree import :: TypeTree

/**
 * A storage for function types, class definitions, type definitions, etc.
 */
:: *CloogleDB =
	{ db            :: !*DB CloogleEntry AnnotationKey Int //* Core data
	, name_ngrams   :: !NGramIndex Index //* Name ngrams
	, name_map      :: !Map Name [Index] //* For exact name search
	, types         :: !TypeTree Index   //* Types, map to FunctionEntries
	, core          :: ![Index]          //* Entries in core modules
	, apps          :: ![Index]          //* Entries in app modules
	, builtins      :: ![Index]          //* Entries in Clean core
	, syntax        :: ![Index]          //* SyntaxEntries
	, library_map   :: !Map Name [Index] //* Entries by library name
	, module_map    :: !Map Name [Index] //* Entries by module name
	, derive_map    :: !Map Name [Index] //* DeriveEntries by generic name
	, instance_map  :: !Map Name [Index] //* InstanceEntries by class name
	, always_unique :: !Map Name ()     //* Types that are always unique, like World
	}

/**
 * Information about a {{`CloogleDB`}}. Can be retrieved with {{`dbStats`}}.
 */
:: CloogleDBStats =
	{ n_modules             :: Int
	, n_functions           :: Int
	, n_functions_with_type :: Int
	, n_unique_types        :: Int
	, type_tree_depth       :: Int
	, n_type_definitions    :: Int
	, n_classes             :: Int
	, n_instances           :: Int
	, n_derivations         :: Int
	, n_syntax_constructs   :: Int
	}

/**
 * Annotations to store during search.
 */
:: AnnotationKey
	= MatchingNGrams //* For name search, the number of matching ngrams
	| UnifierSize    //* For type search, the 'size' of the unifier
	| ExactResult    //* 1 if this was an exact match found with filterExactName

instance == AnnotationKey
instance < AnnotationKey

/**
 * Wrapper around different kinds of entries to store all in one database.
 */
:: CloogleEntry
	= FunctionEntry FunctionEntry
	| TypeDefEntry  TypeDefEntry
	| ModuleEntry   ModuleEntry
	| ClassEntry    ClassEntry
	| InstanceEntry InstanceEntry
	| DeriveEntry   DeriveEntry
	| SyntaxEntry   SyntaxEntry

derive JSONEncode CloogleEntry
derive JSONDecode CloogleEntry

/**
 * A location in the Clean libraries
 */
:: Location
	= Location !Library !Module !FilePath !LineNr !LineNr !Name //* A normal location
	| Builtin !Name ![CleanLangReportLocation] //* A language builtin
	| NoLocation //* Only used internally

/**
 * Wrapper around {{`Location`}} for use in {{`CloogleDBFactory`}} to avoid
 * name clashes with {{`Module`}} in the compiler.
 */
location :: !Library !String !FilePath !LineNr !LineNr !Name -> Location

/**
 * Not-type information that is often associated with things that have a type
 */
:: FunctionEntry
	= { fe_loc            :: !Location       //* The location
	  , fe_kind           :: !FunctionKind   //* The type of entry
	  , fe_type           :: !Maybe Type     //* The type, Nothing for macros
	  , fe_priority       :: !Maybe Priority //* The infix priority
	  , fe_generic_vars   :: !Maybe [String] //* The names of the type variables of a generic function
	    // Using TypeVar causes import clashes in CloogleDBFactory
	  , fe_representation :: !Maybe String   //* A string representation of the entry
	  , fe_documentation  :: !Maybe FunctionDoc //* Documentation on this entry
	  , fe_class          :: !Maybe Index    //* The class, for class members
	  , fe_derivations    :: !Maybe [Index]  //* The DerivaionEntries
	  , fe_usages         :: ![Index]        //* FunctionEntries where the implementation uses this function
	  }

/**
 * A TypeDef with meta-data
 */
:: TypeDefEntry
	= { tde_loc         :: !Location      //* The location
	  , tde_typedef     :: !TypeDef       //* The TypeDef
	  , tde_doc         :: !Maybe TypeDoc //* Documentation on the TypeDef
	  , tde_instances   :: ![Index]       //* Instances of this type
	  , tde_derivations :: ![Index]       //* Derivations of this type
	  , tde_usages      :: ![Index]       //* FunctionEntries using the type
	  }

/**
 * Information about a Clean module
 */
:: ModuleEntry
	= { me_loc           :: !Location        //* The location
	  , me_is_core       :: !Bool            //* Whether this is a core module (e.g. the os* modules in ObjectIO and TCPIP)
	  , me_is_app        :: !Bool            //* Whether this module is not actually a library but an app
	  , me_documentation :: !Maybe ModuleDoc //* Documentation on this module
	  , me_usages        :: ![Index]         //* Modules importing this module
	  }

/**
 * Information about a Clean class
 */
:: ClassEntry
	= { ce_loc           :: !Location       //* The location
	  , ce_vars          :: ![String]       //* The type variables of the class
	    // Using TypeVar causes import clashes in CloogleDBFactory
	  , ce_is_meta       :: !Bool           //* Whether this is a meta class (no non-macro members and not TC)
	  , ce_context       :: !TypeContext    //* A class context
	  , ce_documentation :: !Maybe ClassDoc //* Documentation on this class
	  , ce_members       :: [Index]         //* Class members (FunctionEntries; must be lazy for CloogleDBFactory to work)
	  , ce_instances     :: ![Index]        //* All instances of the class
	  , ce_derivations   :: ![Index]        //* Derivations of generic meta-classes like iTask
	  , ce_usages        :: ![Index]        //* FunctionEntries, TypeDefEntries and ClassEntries using this class
	  }

/**
 * Information about a class instance
 */
:: InstanceEntry
	= { ie_class     :: Name             //* The class
	  , ie_types     :: [(Type, String)] //* The instantiated type and a string representation for each class variable
	  , ie_locations :: [Location]       //* The places where this instance is found
	  }

/**
 * Information about a generic derivation
 */
:: DeriveEntry
	= { de_generic             :: !Name       //* The generic
	  , de_type                :: !Type       //* The type to derive an instance for
	  , de_type_representation :: !String     //* A string representation of the type
	  , de_locations           :: ![Location] //* The locations in which the derivation occurs
	  }

/**
 * Information about a syntax construct
 * This is very similar to {{`SyntaxResultExtras`}}, but also includes a
 * description string.
 */
:: SyntaxEntry =
	{ syntax_title         :: String //* The name of the construct
	, syntax_patterns      :: [String] //* Patterns to search for the construct
	, syntax_code          :: [String] //* Strings describing the construct, as short as possible
	, syntax_description   :: String //* A description for documentation
	, syntax_doc_locations :: [CleanLangReportLocation] //* Where to find documentation on the construct
	, syntax_examples      :: [SyntaxExample] //* Some code examples (should include comments)
	}

/**
 * A search pattern for syntax constructs
 */
:: SyntaxPattern :== String

patternMatches :: !SyntaxPattern !String -> Bool

:: Name    :== String
:: Library :== String
:: Module  :== String
:: LineNr  :== Maybe Int

instance zero Location
instance == Location
instance zero FunctionEntry
instance zero ModuleEntry

instance print (!Name, !FunctionEntry)

class getLocation a :: !a -> Maybe Location
instance getLocation FunctionEntry
instance getLocation TypeDefEntry
instance getLocation ModuleEntry
instance getLocation ClassEntry
instance getLocation CloogleEntry

getLibrary :: !Location -> Maybe Name
getModule :: !Location -> Maybe Name
setModule :: !Name !Location -> Location
getFilename :: !Location -> Maybe String
getDclLine :: !Location -> Maybe Int
getIclLine :: !Location -> Maybe Int
getName :: !Location -> Name
setName :: !Name !Location -> Location
isBuiltin :: !Location -> Bool

toTypeDefEntry :: !Location !TypeDef !(Maybe TypeDoc) -> TypeDefEntry
getTypeDef :: !TypeDefEntry -> TypeDef
getTypeDefDoc :: !TypeDefEntry -> Maybe TypeDoc
mergeTypeDefEntries :: !TypeDefEntry !TypeDefEntry -> TypeDefEntry

/**
 * Wrapper around the Class record field to work around name clashes
 *
 * @param The location of the class
 * @param The type variables of the class
 * @param Whether this is a meta class
 * @param The class context
 * @param The documentation
 * @result A Class record with those data
 */
toClass :: !Location ![String] !Bool !TypeContext !(Maybe ClassDoc) -> ClassEntry
classContext :: !ClassEntry -> [TypeRestriction]

saveDB :: !*CloogleDB !*File -> *(!*CloogleDB, !*File)
openDB :: !*File -> *(!Maybe *CloogleDB, !*File)

/**
 * Reset the database (count everything as included again).
 */
resetDB :: !*CloogleDB -> *CloogleDB

dbStats :: !*CloogleDB -> *(CloogleDBStats, *CloogleDB)

/**
 * Write the type tree as dot graph to a file.
 */
writeTypeTree :: !*CloogleDB !*File -> *(*CloogleDB, *File)

getIndex :: !Index !*CloogleDB -> *(Entry CloogleEntry AnnotationKey Int, *CloogleDB)
getIndices :: ![Index] !*CloogleDB -> *([Entry CloogleEntry AnnotationKey Int], *CloogleDB)

filterDB :: (CloogleEntry -> Bool) !*CloogleDB -> *CloogleDB
excludeCore :: !*CloogleDB -> *CloogleDB
excludeApps :: !*CloogleDB -> *CloogleDB
excludeBuiltins :: !*CloogleDB -> *CloogleDB
includeBuiltins :: !*CloogleDB -> *CloogleDB
filterLibraries :: ![Name] !*CloogleDB -> *CloogleDB
filterModules :: ![Name] !*CloogleDB -> *CloogleDB
filterName :: !String !*CloogleDB -> *CloogleDB
filterExactName :: !String !*CloogleDB -> *CloogleDB
filterUnifying :: !Type !*CloogleDB -> *CloogleDB

filterUsages :: ![String] !*CloogleDB -> *CloogleDB

allTypeSynonyms :: !*CloogleDB -> *(Map Name [TypeDef], *CloogleDB)
alwaysUniquePredicate :: !*CloogleDB -> *(String -> Bool, *CloogleDB)
getInstances :: !Name !*CloogleDB -> *([InstanceEntry], *CloogleDB)
getDerivations :: !Name !*CloogleDB -> *([DeriveEntry], *CloogleDB)

getEntries :: !*CloogleDB -> *([(CloogleEntry, Map AnnotationKey Int)], *CloogleDB)