Dovetail

Documentation

module Dovetail.Types

module Dovetail.FFI

module Dovetail.FFI

module Dovetail.FFI.Builder

High-level API

data InterpretT m a

A monad transformer for high-level tasks involving PureScript code, including separate compilation. Its job is to keep track of available modules, any foreign imports from Haskell code, and run PureScript code.

Note: do not confuse this monad transformer with EvalT, which is only responsible for powering evaluation of PureScript expressions.

The transformed monad is used to track any benign side effects that might be exposed via the foreign function interface to PureScript code, in the same sense as EvalT.

Instances

MonadTrans InterpretT

Defined in Dovetail

Methods

lift :: Monad m => m a -> InterpretT m a

Monad m => Monad (InterpretT m)

Defined in Dovetail

Methods

(>>=) :: InterpretT m a -> (a -> InterpretT m b) -> InterpretT m b

(>>) :: InterpretT m a -> InterpretT m b -> InterpretT m b

return :: a -> InterpretT m a

Functor m => Functor (InterpretT m)

Defined in Dovetail

Methods

fmap :: (a -> b) -> InterpretT m a -> InterpretT m b

(<$) :: a -> InterpretT m b -> InterpretT m a

Monad m => Applicative (InterpretT m)

Defined in Dovetail

Methods

pure :: a -> InterpretT m a

(<*>) :: InterpretT m (a -> b) -> InterpretT m a -> InterpretT m b

liftA2 :: (a -> b -> c) -> InterpretT m a -> InterpretT m b -> InterpretT m c

(*>) :: InterpretT m a -> InterpretT m b -> InterpretT m b

(<*) :: InterpretT m a -> InterpretT m b -> InterpretT m a

Monad m => MonadError (InterpretError m) (InterpretT m)

Defined in Dovetail

Methods

throwError :: InterpretError m -> InterpretT m a

catchError :: InterpretT m a -> (InterpretError m -> InterpretT m a) -> InterpretT m a

runInterpretT :: Monad m => InterpretT m a -> m (Either (InterpretError m) a)

Run a computation in the InterpretT monad, possibly returning an error. Note: errors can occur during module building or evaluation (i.e. module loading).

The runInterpret function is a simpler alternative in the case where benign side-effects are not needed.

For example:

runInterpret Module do
  -- Load the prelude
  ffi prelude
  -- Build a module from source
  build "module Main where main = \"example\"" --

runInterpret (Eval Text) do
  ffi prelude
  _ <- build "module Main where main = \"example\""
  -- Evaluate the main function
  evalMain (ModuleName "Main")

runInterpret :: Interpret a -> Either (InterpretError Identity) a

liftEvalT :: Monad m => EvalT m a -> InterpretT m a

A convenience function for running EvalT computations in InterpretT, reporting errors via InterpretError.

Debugging

runInterpretTWithDebugger :: (MonadIO m, MonadFix m, MonadMask m) => InterpretT m a -> m ()

Like runInterpretT, but starts an interactive debugging session in the event of a debugging error.

Error messages

data InterpretError m

The type of errors that can occur in the InterpretT monad.

Constructors

ErrorDuringEvaluation (EvaluationError m)

Evaluation errors can occur during the initial evaluation of the module when it is loaded into the environment.

ErrorDuringBuild BuildError

Build errors can occur if we are building modules from source or corefn.

Instances

Monad m => MonadError (InterpretError m) (InterpretT m)

Defined in Dovetail

Methods

throwError :: InterpretError m -> InterpretT m a

catchError :: InterpretT m a -> (InterpretError m -> InterpretT m a) -> InterpretT m a

renderInterpretError :: RenderValueOptions -> InterpretError m -> String

Foreign function interface

ffi :: Monad m => FFI m -> InterpretT m ()

Make an FFI module available for use to subsequent operations.

For example, to make the prelude available:

ffi prelude

Building PureScript source

build :: MonadFix m => Text -> InterpretT m (Module Ann)

Build a PureScript module from source, and make its exported functions available during subsequent evaluations.

buildCoreFn :: MonadFix m => ExternsFile -> Module Ann -> InterpretT m (Module Ann)

Build a PureScript module from corefn, and make its exported functions available during subsequent evaluations.

The corefn module may be preprepared, for example by compiling from source text using the functions in the Dovetail.Build module.

data BuildError

Constructors

UnableToParse (NonEmpty ParserError)

UnableToCompile MultipleErrors

InternalError

Instances

Show BuildError

Defined in Dovetail.Build

Methods

showsPrec :: Int -> BuildError -> ShowS

show :: BuildError -> String

showList :: [BuildError] -> ShowS

renderBuildError :: BuildError -> String

Evaluating expressions

eval

Arguments

:: (MonadFix m, ToValueRHS m a)

=> Maybe ModuleName

The name of the "default module" whose exports will be made available unqualified to the evaluated expression.

-> Text

-> InterpretT m (a, SourceType)

Evaluate a PureScript expression from source

evalCoreFn :: (MonadFix m, ToValueRHS m a) => Expr Ann -> InterpretT m a

Evaluate a PureScript corefn expression and return the result. Note: The expression is not type-checked by the PureScript typechecker. See the documentation for ToValueRHS for valid result types.

evalMain :: (MonadFix m, ToValueRHS m a) => ModuleName -> InterpretT m a

Evaluate main in the specified module and return the result.

type Eval = EvalT Identity

Non-transformer version of EvalT, useful in any settings where the FFI does not use any side effects during evaluation.

newtype EvalT m a

The monad used by the interpreter, which supports error reporting for errors which can occur during evaluation.

The transformed monad is used to track any benign side effects that might be exposed via the foreign function interface to PureScript code.

Constructors

EvalT

Fields

• unEvalT :: ReaderT (EvaluationContext m) (ExceptT (EvaluationError m) m) a

Instances

MonadTrans EvalT

Defined in Dovetail.Types

Methods

lift :: Monad m => m a -> EvalT m a

(ToValue m a, n ~ m) => ToValueRHS m (EvalT n a)

Defined in Dovetail.Evaluate

Methods

toValueRHS :: EvalT n a -> EvalT m (Value m)

fromValueRHS :: EvalT m (Value m) -> EvalT n a

Monad m => Monad (EvalT m)

Defined in Dovetail.Types

Methods

(>>=) :: EvalT m a -> (a -> EvalT m b) -> EvalT m b

(>>) :: EvalT m a -> EvalT m b -> EvalT m b

return :: a -> EvalT m a

Functor m => Functor (EvalT m)

Defined in Dovetail.Types

Methods

fmap :: (a -> b) -> EvalT m a -> EvalT m b

(<$) :: a -> EvalT m b -> EvalT m a

MonadFix m => MonadFix (EvalT m)

Defined in Dovetail.Types

Methods

mfix :: (a -> EvalT m a) -> EvalT m a

Monad m => Applicative (EvalT m)

Defined in Dovetail.Types

Methods

pure :: a -> EvalT m a

(<*>) :: EvalT m (a -> b) -> EvalT m a -> EvalT m b

liftA2 :: (a -> b -> c) -> EvalT m a -> EvalT m b -> EvalT m c

(*>) :: EvalT m a -> EvalT m b -> EvalT m b

(<*) :: EvalT m a -> EvalT m b -> EvalT m a

Monad m => MonadError (EvaluationError m) (EvalT m)

Defined in Dovetail.Types

Methods

throwError :: EvaluationError m -> EvalT m a

catchError :: EvalT m a -> (EvaluationError m -> EvalT m a) -> EvalT m a

Monad m => MonadReader (EvaluationContext m) (EvalT m)

Defined in Dovetail.Types

Methods

ask :: EvalT m (EvaluationContext m)

local :: (EvaluationContext m -> EvaluationContext m) -> EvalT m a -> EvalT m a

reader :: (EvaluationContext m -> a) -> EvalT m a

type Env m = Map (Qualified Ident) (Value m)

An environment, i.e. a mapping from names to evaluated values.

An environment for a single built-in function can be constructed using the builtIn function, and environments can be combined easily using the Monoid instance for Map.

runEvalT :: EvalT m a -> m (Either (EvaluationError m) a)

runEval :: Eval a -> Either (EvaluationError Identity) a

class ToValueRHS m a where

ToValue should support functions with types such as

a -> EvalT m b
a -> b -> EvalT m c
a -> b -> c -> EvalT m d
(a -> EvalT m b) -> EvalT m c
(a -> b -> EvalT m c) -> EvalT m d

Note that every type in a return position is wrapped in the EvalT monad transformer. This is because evaluation in general may result in errors. However, a naive translation would result in too many applications of EvalT.

Specifically, we do not want to require types such as these, in which EvalT appears on the right hand side of every function arrow:

a -> EvalT m b (b -> EvalT m c)
a -> EvalT m b (b -> EvalT m (c -> EvalT m d))

For this reason, the ToValue instance for functions delegates to this type class for the type on the right hand side of the function. It skips the application of EvalT for nested function types.

Methods

toValueRHS :: a -> EvalT m (Value m)

fromValueRHS :: EvalT m (Value m) -> a

Instances

(ToValue m a, n ~ m) => ToValueRHS m (EvalT n a)

Defined in Dovetail.Evaluate

Methods

toValueRHS :: EvalT n a -> EvalT m (Value m)

fromValueRHS :: EvalT m (Value m) -> EvalT n a

(MonadFix m, ToValue m a, ToValueRHS m b) => ToValueRHS m (a -> b)

Defined in Dovetail.Evaluate

Methods

toValueRHS :: (a -> b) -> EvalT m (Value m)

fromValueRHS :: EvalT m (Value m) -> a -> b

class MonadFix m => ToValue m a where

Values which can be communicated across the FFI boundary from Haskell to PureScript.

Instances should identify and document any valid representations as a subset of the semantic domain Value. Such a subset can be identified by an injective function toValue, and a partial inverse, fromValue, defined on the image of toValue.

Laws:

fromValue . toValue = pure

Minimal complete definition

Nothing

Methods

toValue :: a -> Value m

The default implementation uses generic deriving to identify a Haskell record type with a single data constructor with a PureScript record with the same field names.

default toValue :: (Generic a, ToObject m (Rep a)) => a -> Value m

fromValue :: Value m -> EvalT m a

default fromValue :: (Generic a, ToObject m (Rep a)) => Value m -> EvalT m a

Instances

MonadFix m => ToValue m Bool

Haskell booleans are represented by boolean values.

Defined in Dovetail.Evaluate

Methods

toValue :: Bool -> Value m

fromValue :: Value m -> EvalT m Bool

MonadFix m => ToValue m Char

The Haskell Char type is represented by PureScript characters.

Defined in Dovetail.Evaluate

Methods

toValue :: Char -> Value m

fromValue :: Value m -> EvalT m Char

MonadFix m => ToValue m Text

The Haskell Text type is represented by PureScript strings which contain no lone surrogates.

Defined in Dovetail.Evaluate

Methods

toValue :: Text -> Value m

fromValue :: Value m -> EvalT m Text

MonadFix m => ToValue m Double

The Haskell Douvle type corresponds to the subset of PureScript values consisting of its Number type.

Defined in Dovetail.Evaluate

Methods

toValue :: Double -> Value m

fromValue :: Value m -> EvalT m Double

MonadFix m => ToValue m Integer

The Haskell Integer type corresponds to PureScript's integer type.

Defined in Dovetail.Evaluate

Methods

toValue :: Integer -> Value m

fromValue :: Value m -> EvalT m Integer

MonadFix m => ToValue m UnknownJSON

Defined in Dovetail.JSON

Methods

toValue :: UnknownJSON -> Value m

fromValue :: Value m -> EvalT m UnknownJSON

ToValue m a => ToValue m (Vector a)

Haskell vectors are represented as homogeneous vectors of values, each of which are valid representations of the element type.

Defined in Dovetail.Evaluate

Methods

toValue :: Vector a -> Value m

fromValue :: Value m -> EvalT m (Vector a)

MonadFix m => ToValue m (Value m)

Defined in Dovetail.Evaluate

Methods

toValue :: Value m -> Value m

fromValue :: Value m -> EvalT m (Value m)

ToValue m a => ToValue m (Nullable a)

Defined in Dovetail.JSON

Methods

toValue :: Nullable a -> Value m

fromValue :: Value m -> EvalT m (Nullable a)

(MonadFix m, ToValue m a, ToValueRHS m b) => ToValue m (a -> b)

Haskell functions are represented as closures which take valid representations for the domain type to valid representations of the codomain type.

Defined in Dovetail.Evaluate

Methods

toValue :: (a -> b) -> Value m

fromValue :: Value m -> EvalT m (a -> b)

REPL

repl

Arguments

:: (MonadFix m, MonadIO m, MonadMask m)

=> Maybe ModuleName

The default module, whose members will be available unqualified in scope

-> InterpretT m ()

Start an interactive debugger (REPL) session.

Re-exports

type Ann = (SourceSpan, [Comment], Maybe SourceType, Maybe Meta)

data Expr a

Instances

Functor Expr

Defined in Language.PureScript.CoreFn.Expr

Methods

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

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

Show a => Show (Expr a)

Defined in Language.PureScript.CoreFn.Expr

Methods

showsPrec :: Int -> Expr a -> ShowS

show :: Expr a -> String

showList :: [Expr a] -> ShowS

data Module a

Instances

Show a => Show (Module a)

Defined in Language.PureScript.CoreFn.Module

Methods

showsPrec :: Int -> Module a -> ShowS

show :: Module a -> String

showList :: [Module a] -> ShowS