Language.Souffle.Interpreted

This module provides an implementation for the MonadSouffle typeclass defined in Language.Souffle.Class. It makes use of the Souffle interpreter and CSV files to offer an implementation optimized for quick development speed compared to Language.Souffle.Compiled.

It is however much slower so users are advised to switch over to the compiled alternative once the prototyping phase is finished.

Documentation

class Program a where

A typeclass for describing a datalog program.

Example usage (assuming the program was generated from path.dl and contains 2 facts: Edge and Reachable):

data Path = Path  -- Handle for the datalog program

instance Program Path where
  type ProgramFacts Path = '[Edge, Reachable]
  programName = const "path"

Associated Types

type ProgramFacts a :: [Type]

A type level list of facts that belong to this program. This list is used to check that only known facts are added to a program.

Methods

programName :: Proxy a -> String

Function for obtaining the name of a Datalog program. This has to be the same as the name of the .dl file (minus the extension).

It uses a Proxy to select the correct instance.

class Marshal a => Fact a where

A typeclass for data types representing a fact in datalog.

Methods

factName :: Proxy a -> String

Function for obtaining the name of a fact (has to be the same as described in the Datalog program).

It uses a Proxy to select the correct instance.

Example usage:

instance Fact Edge where
  factName = const "edge"

class Marshal a where

A typeclass for providing a uniform API to marshal/unmarshal values between Haskell and Souffle datalog.

The marshalling is done via a stack-based approach, where elements are pushed/popped one by one. You need to make sure that the marshalling of values happens in the correct order or unexpected things might happen (including crashes). Pushing and popping of fields should happen in the same order (from left to right, as defined in Datalog).

Generic implementations for push and pop that perform the previously described behavior are available. This makes it possible to write very succinct code:

data Edge = Edge String String deriving Generic

instance Marshal Edge

Minimal complete definition

Nothing

Methods

push :: MonadPush m => a -> m ()

Marshals a value to the datalog side.

default push :: (Generic a, SimpleProduct a (Rep a), GMarshal (Rep a), MonadPush m) => a -> m ()

pop :: MonadPop m => m a

Unmarshals a value from the datalog side.

default pop :: (Generic a, SimpleProduct a (Rep a), GMarshal (Rep a), MonadPop m) => m a

Instances

Marshal Int32

Defined in Language.Souffle.Marshal

Methods

push :: MonadPush m => Int32 -> m ()

pop :: MonadPop m => m Int32

Marshal String

Defined in Language.Souffle.Marshal

Methods

push :: MonadPush m => String -> m ()

pop :: MonadPop m => m String

Marshal Text

Defined in Language.Souffle.Marshal

Methods

push :: MonadPush m => Text -> m ()

pop :: MonadPop m => m Text

Marshal Text

Defined in Language.Souffle.Marshal

Methods

push :: MonadPush m => Text -> m ()

pop :: MonadPop m => m Text

data Config

A helper data type for storing the configurable settings of the interpreter.

• cfgDatalogDir: The directory where the datalog file(s) are located.
• cfgSouffleBin: The name of the souffle binary. Has to be available in $PATH or an absolute path needs to be provided. Note: Passing in Nothing will fail to start up the interpreter in the init function.
• cfgFactDir: The directory where the initial input fact file(s) can be found if present. If Nothing, then a temporary directory will be used, during the souffle session.
• cfgOutputDir: The directory where the output facts file(s) are created. If Nothing, it will be part of the temporary directory.

Constructors

Config

Fields

• cfgDatalogDir :: FilePath
• cfgSouffleBin :: Maybe FilePath
• cfgFactDir :: Maybe FilePath
• cfgOutputDir :: Maybe FilePath

Instances

Show Config

Defined in Language.Souffle.Interpreted

Methods

showsPrec :: Int -> Config -> ShowS

show :: Config -> String

showList :: [Config] -> ShowS

data Handle prog

A datatype representing a handle to a datalog program. The type parameter is used for keeping track of which program type the handle belongs to for additional type safety.

data SouffleM a

A monad for executing Souffle-related actions in.

Instances

Monad SouffleM

Defined in Language.Souffle.Interpreted

Methods

(>>=) :: SouffleM a -> (a -> SouffleM b) -> SouffleM b

(>>) :: SouffleM a -> SouffleM b -> SouffleM b

return :: a -> SouffleM a

Functor SouffleM

Defined in Language.Souffle.Interpreted

Methods

fmap :: (a -> b) -> SouffleM a -> SouffleM b

(<$) :: a -> SouffleM b -> SouffleM a

Applicative SouffleM

Defined in Language.Souffle.Interpreted

Methods

pure :: a -> SouffleM a

(<*>) :: SouffleM (a -> b) -> SouffleM a -> SouffleM b

liftA2 :: (a -> b -> c) -> SouffleM a -> SouffleM b -> SouffleM c

(*>) :: SouffleM a -> SouffleM b -> SouffleM b

(<*) :: SouffleM a -> SouffleM b -> SouffleM a

MonadIO SouffleM

Defined in Language.Souffle.Interpreted

Methods

liftIO :: IO a -> SouffleM a

MonadSouffle SouffleM

Defined in Language.Souffle.Interpreted

Associated Types

type Handler SouffleM :: Type -> Type

type CollectFacts SouffleM c

Methods

init :: Program prog => prog -> SouffleM (Maybe (Handler SouffleM prog))

run :: Handler SouffleM prog -> SouffleM ()

setNumThreads :: Handler SouffleM prog -> Word64 -> SouffleM ()

getNumThreads :: Handler SouffleM prog -> SouffleM Word64

getFacts :: (Fact a, ContainsFact prog a, CollectFacts SouffleM c) => Handler SouffleM prog -> SouffleM (c a)

findFact :: (Fact a, ContainsFact prog a, Eq a) => Handler SouffleM prog -> a -> SouffleM (Maybe a)

addFact :: (Fact a, ContainsFact prog a) => Handler SouffleM prog -> a -> SouffleM ()

addFacts :: (Foldable t, Fact a, ContainsFact prog a) => Handler SouffleM prog -> t a -> SouffleM ()

type Handler SouffleM

Defined in Language.Souffle.Interpreted

type Handler SouffleM = Handle

type CollectFacts SouffleM c

Defined in Language.Souffle.Interpreted

type CollectFacts SouffleM c

class Monad m => MonadSouffle m where

A mtl-style typeclass for Souffle-related actions.

Associated Types

type Handler m :: Type -> Type

Represents a handle for interacting with a Souffle program. See also init, which returns a handle of this type.

type CollectFacts m (c :: Type -> Type) :: Constraint

Helper associated type constraint that allows collecting facts from Souffle in a list or vector. Only used internally.

Methods

init :: Program prog => prog -> m (Maybe (Handler m prog))

Initializes a Souffle program.

The action will return Nothing if it failed to load the Souffle C++ program or if it failed to find the Souffle interpreter (depending on compiled/interpreted variant). Otherwise it will return a handle that can be used in other functions in this module.

run :: Handler m prog -> m ()

Runs the Souffle program.

setNumThreads :: Handler m prog -> Word64 -> m ()

Sets the number of CPU cores this Souffle program should use.

getNumThreads :: Handler m prog -> m Word64

Gets the number of CPU cores this Souffle program should use.

getFacts :: (Fact a, ContainsFact prog a, CollectFacts m c) => Handler m prog -> m (c a)

Returns all facts of a program. This function makes use of type inference to select the type of fact to return.

findFact :: (Fact a, ContainsFact prog a, Eq a) => Handler m prog -> a -> m (Maybe a)

Searches for a fact in a program. Returns Nothing if no matching fact was found; otherwise Just the fact.

Conceptually equivalent to List.find (== fact) <$> getFacts prog, but this operation can be implemented much faster.

addFact :: (Fact a, ContainsFact prog a) => Handler m prog -> a -> m ()

Adds a fact to the program.

addFacts :: (Foldable t, Fact a, ContainsFact prog a) => Handler m prog -> t a -> m ()

Adds multiple facts to the program. This function could be implemented in terms of addFact, but this is done as a minor optimization.

Instances

MonadSouffle SouffleM

Defined in Language.Souffle.Interpreted

Associated Types

type Handler SouffleM :: Type -> Type

type CollectFacts SouffleM c

Methods

init :: Program prog => prog -> SouffleM (Maybe (Handler SouffleM prog))

run :: Handler SouffleM prog -> SouffleM ()

setNumThreads :: Handler SouffleM prog -> Word64 -> SouffleM ()

getNumThreads :: Handler SouffleM prog -> SouffleM Word64

getFacts :: (Fact a, ContainsFact prog a, CollectFacts SouffleM c) => Handler SouffleM prog -> SouffleM (c a)

findFact :: (Fact a, ContainsFact prog a, Eq a) => Handler SouffleM prog -> a -> SouffleM (Maybe a)

addFact :: (Fact a, ContainsFact prog a) => Handler SouffleM prog -> a -> SouffleM ()

addFacts :: (Foldable t, Fact a, ContainsFact prog a) => Handler SouffleM prog -> t a -> SouffleM ()

MonadSouffle SouffleM

Defined in Language.Souffle.Compiled

Associated Types

type Handler SouffleM :: Type -> Type

type CollectFacts SouffleM c

Methods

init :: Program prog => prog -> SouffleM (Maybe (Handler SouffleM prog))

run :: Handler SouffleM prog -> SouffleM ()

setNumThreads :: Handler SouffleM prog -> Word64 -> SouffleM ()

getNumThreads :: Handler SouffleM prog -> SouffleM Word64

getFacts :: (Fact a, ContainsFact prog a, CollectFacts SouffleM c) => Handler SouffleM prog -> SouffleM (c a)

findFact :: (Fact a, ContainsFact prog a, Eq a) => Handler SouffleM prog -> a -> SouffleM (Maybe a)

addFact :: (Fact a, ContainsFact prog a) => Handler SouffleM prog -> a -> SouffleM ()

addFacts :: (Foldable t, Fact a, ContainsFact prog a) => Handler SouffleM prog -> t a -> SouffleM ()

MonadSouffle m => MonadSouffle (ExceptT e m)

Defined in Language.Souffle.Class

Associated Types

type Handler (ExceptT e m) :: Type -> Type

type CollectFacts (ExceptT e m) c

Methods

init :: Program prog => prog -> ExceptT e m (Maybe (Handler (ExceptT e m) prog))

run :: Handler (ExceptT e m) prog -> ExceptT e m ()

setNumThreads :: Handler (ExceptT e m) prog -> Word64 -> ExceptT e m ()

getNumThreads :: Handler (ExceptT e m) prog -> ExceptT e m Word64

getFacts :: (Fact a, ContainsFact prog a, CollectFacts (ExceptT e m) c) => Handler (ExceptT e m) prog -> ExceptT e m (c a)

findFact :: (Fact a, ContainsFact prog a, Eq a) => Handler (ExceptT e m) prog -> a -> ExceptT e m (Maybe a)

addFact :: (Fact a, ContainsFact prog a) => Handler (ExceptT e m) prog -> a -> ExceptT e m ()

addFacts :: (Foldable t, Fact a, ContainsFact prog a) => Handler (ExceptT e m) prog -> t a -> ExceptT e m ()

MonadSouffle m => MonadSouffle (ReaderT r m)

Defined in Language.Souffle.Class

Associated Types

type Handler (ReaderT r m) :: Type -> Type

type CollectFacts (ReaderT r m) c

Methods

init :: Program prog => prog -> ReaderT r m (Maybe (Handler (ReaderT r m) prog))

run :: Handler (ReaderT r m) prog -> ReaderT r m ()

setNumThreads :: Handler (ReaderT r m) prog -> Word64 -> ReaderT r m ()

getNumThreads :: Handler (ReaderT r m) prog -> ReaderT r m Word64

getFacts :: (Fact a, ContainsFact prog a, CollectFacts (ReaderT r m) c) => Handler (ReaderT r m) prog -> ReaderT r m (c a)

findFact :: (Fact a, ContainsFact prog a, Eq a) => Handler (ReaderT r m) prog -> a -> ReaderT r m (Maybe a)

addFact :: (Fact a, ContainsFact prog a) => Handler (ReaderT r m) prog -> a -> ReaderT r m ()

addFacts :: (Foldable t, Fact a, ContainsFact prog a) => Handler (ReaderT r m) prog -> t a -> ReaderT r m ()

MonadSouffle m => MonadSouffle (StateT s m)

Defined in Language.Souffle.Class

Associated Types

type Handler (StateT s m) :: Type -> Type

type CollectFacts (StateT s m) c

Methods

init :: Program prog => prog -> StateT s m (Maybe (Handler (StateT s m) prog))

run :: Handler (StateT s m) prog -> StateT s m ()

setNumThreads :: Handler (StateT s m) prog -> Word64 -> StateT s m ()

getNumThreads :: Handler (StateT s m) prog -> StateT s m Word64

getFacts :: (Fact a, ContainsFact prog a, CollectFacts (StateT s m) c) => Handler (StateT s m) prog -> StateT s m (c a)

findFact :: (Fact a, ContainsFact prog a, Eq a) => Handler (StateT s m) prog -> a -> StateT s m (Maybe a)

addFact :: (Fact a, ContainsFact prog a) => Handler (StateT s m) prog -> a -> StateT s m ()

addFacts :: (Foldable t, Fact a, ContainsFact prog a) => Handler (StateT s m) prog -> t a -> StateT s m ()

(Monoid w, MonadSouffle m) => MonadSouffle (WriterT w m)

Defined in Language.Souffle.Class

Associated Types

type Handler (WriterT w m) :: Type -> Type

type CollectFacts (WriterT w m) c

Methods

init :: Program prog => prog -> WriterT w m (Maybe (Handler (WriterT w m) prog))

run :: Handler (WriterT w m) prog -> WriterT w m ()

setNumThreads :: Handler (WriterT w m) prog -> Word64 -> WriterT w m ()

getNumThreads :: Handler (WriterT w m) prog -> WriterT w m Word64

getFacts :: (Fact a, ContainsFact prog a, CollectFacts (WriterT w m) c) => Handler (WriterT w m) prog -> WriterT w m (c a)

findFact :: (Fact a, ContainsFact prog a, Eq a) => Handler (WriterT w m) prog -> a -> WriterT w m (Maybe a)

addFact :: (Fact a, ContainsFact prog a) => Handler (WriterT w m) prog -> a -> WriterT w m ()

addFacts :: (Foldable t, Fact a, ContainsFact prog a) => Handler (WriterT w m) prog -> t a -> WriterT w m ()

(MonadSouffle m, Monoid w) => MonadSouffle (RWST r w s m)

Defined in Language.Souffle.Class

Associated Types

type Handler (RWST r w s m) :: Type -> Type

type CollectFacts (RWST r w s m) c

Methods

init :: Program prog => prog -> RWST r w s m (Maybe (Handler (RWST r w s m) prog))

run :: Handler (RWST r w s m) prog -> RWST r w s m ()

setNumThreads :: Handler (RWST r w s m) prog -> Word64 -> RWST r w s m ()

getNumThreads :: Handler (RWST r w s m) prog -> RWST r w s m Word64

getFacts :: (Fact a, ContainsFact prog a, CollectFacts (RWST r w s m) c) => Handler (RWST r w s m) prog -> RWST r w s m (c a)

findFact :: (Fact a, ContainsFact prog a, Eq a) => Handler (RWST r w s m) prog -> a -> RWST r w s m (Maybe a)

addFact :: (Fact a, ContainsFact prog a) => Handler (RWST r w s m) prog -> a -> RWST r w s m ()

addFacts :: (Foldable t, Fact a, ContainsFact prog a) => Handler (RWST r w s m) prog -> t a -> RWST r w s m ()

runSouffle :: SouffleM a -> IO a

Returns an IO action that will run the Souffle interpreter with default settings (see defaultConfig).

runSouffleWith :: Config -> SouffleM a -> IO a

Returns an IO action that will run the Souffle interpreter with the given interpreter settings.

defaultConfig :: MonadIO m => m Config

Retrieves the default config for the interpreter. These settings can be overridden using record update syntax if needed.

By default, the settings will be configured as follows:

• cfgDatalogDir: Looks at environment variable $DATALOG_DIR, falls back to the current directory if not set.
• cfgSouffleBin: Looks at environment variable $SOUFFLE_BIN, or tries to locate the souffle binary using the which shell command if the variable is not set.
• cfgFactDir: Will make use of a temporary directory.
• cfgOutputDir: Will make use of a temporary directory.

cleanup :: forall prog. Program prog => Handle prog -> SouffleM ()

Cleans up the temporary directory that this library has written files to. This functionality is only provided for the interpreted version since the compiled version directly (de-)serializes data via the C++ API.

souffleStdOut :: forall prog. Program prog => Handle prog -> SouffleM (Maybe Text)

Returns the handle of stdout from the souffle interpreter.

souffleStdErr :: forall prog. Program prog => Handle prog -> SouffleM (Maybe Text)

Returns the content of stderr from the souffle interpreter.