Prelude.Spiros

Re-exports

These are re-exported by Prelude.Spiros.

Prelude.Spiros.Reexports re-exports: the core types/values from several packages; minus all partial functions, except for some functions whose names are prefixed with "unsafe", i.e. "explicitly partial functions", e.g. unsafeNatural (however, no unsafeHead is exported, as its need often implies that the [] being used is the wrong type).

Prelude.Spiros.Utilities defines a few dozen simple utilities, like an extended prelude.

Prelude.Spiros.System provides system information: about the current operating system, architecture, and compiler.

Prelude.Spiros.Exception defines a few new exception types, which may (or may not) tag the message with a TemplateHaskell Name or with a CallStack, as auxiliary/contextual information.

Prelude.Spiros.Validator re-exports helpers for defining simple validators (e.g. a -> Maybe b).

Prelude.Spiros.GUI provides helpers for working with TemplateHaskell Names.

Prelude.Spiros.TemplateHaskell provides a few helpers for using doctest and working with TemplateHaskell.

module Prelude.Spiros.Print

module Prelude.Spiros.Parse

data Replace a

Intended Specializations:

• Replace Text

• Replace Text

Constructors

Replace

Fields

• old :: !a
• new :: !a

Instances

Functor Replace

Defined in Prelude.Spiros.Enriched

Methods

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

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

Foldable Replace

Defined in Prelude.Spiros.Enriched

Methods

fold :: Monoid m => Replace m -> m

foldMap :: Monoid m => (a -> m) -> Replace a -> m

foldr :: (a -> b -> b) -> b -> Replace a -> b

foldr' :: (a -> b -> b) -> b -> Replace a -> b

foldl :: (b -> a -> b) -> b -> Replace a -> b

foldl' :: (b -> a -> b) -> b -> Replace a -> b

foldr1 :: (a -> a -> a) -> Replace a -> a

foldl1 :: (a -> a -> a) -> Replace a -> a

toList :: Replace a -> [a]

null :: Replace a -> Bool

length :: Replace a -> Int

elem :: Eq a => a -> Replace a -> Bool

maximum :: Ord a => Replace a -> a

minimum :: Ord a => Replace a -> a

sum :: Num a => Replace a -> a

product :: Num a => Replace a -> a

Traversable Replace

Defined in Prelude.Spiros.Enriched

Methods

traverse :: Applicative f => (a -> f b) -> Replace a -> f (Replace b)

sequenceA :: Applicative f => Replace (f a) -> f (Replace a)

mapM :: Monad m => (a -> m b) -> Replace a -> m (Replace b)

sequence :: Monad m => Replace (m a) -> m (Replace a)

Eq a => Eq (Replace a)

Defined in Prelude.Spiros.Enriched

Methods

(==) :: Replace a -> Replace a -> Bool

(/=) :: Replace a -> Replace a -> Bool

Ord a => Ord (Replace a)

Defined in Prelude.Spiros.Enriched

Methods

compare :: Replace a -> Replace a -> Ordering

(<) :: Replace a -> Replace a -> Bool

(<=) :: Replace a -> Replace a -> Bool

(>) :: Replace a -> Replace a -> Bool

(>=) :: Replace a -> Replace a -> Bool

max :: Replace a -> Replace a -> Replace a

min :: Replace a -> Replace a -> Replace a

Read a => Read (Replace a)

Defined in Prelude.Spiros.Enriched

Methods

readsPrec :: Int -> ReadS (Replace a)

readList :: ReadS [Replace a]

readPrec :: ReadPrec (Replace a)

readListPrec :: ReadPrec [Replace a]

Show a => Show (Replace a)

Defined in Prelude.Spiros.Enriched

Methods

showsPrec :: Int -> Replace a -> ShowS

show :: Replace a -> String

showList :: [Replace a] -> ShowS

Generic (Replace a)

Defined in Prelude.Spiros.Enriched

Associated Types

type Rep (Replace a) :: Type -> Type

Methods

from :: Replace a -> Rep (Replace a) x

to :: Rep (Replace a) x -> Replace a

Lift a => Lift (Replace a)

Defined in Prelude.Spiros.Enriched

Methods

lift :: Replace a -> Q Exp

NFData a => NFData (Replace a)

Defined in Prelude.Spiros.Enriched

Methods

rnf :: Replace a -> ()

Hashable a => Hashable (Replace a)

Defined in Prelude.Spiros.Enriched

Methods

hashWithSalt :: Int -> Replace a -> Int

hash :: Replace a -> Int

type Rep (Replace a)

Defined in Prelude.Spiros.Enriched

type Rep (Replace a) = D1 (MetaData "Replace" "Prelude.Spiros.Enriched" "spiros-0.4.0-4h2fnqdGzKwEsvTfCIxvsa" False) (C1 (MetaCons "Replace" PrefixI True) (S1 (MetaSel (Just "old") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 a) :*: S1 (MetaSel (Just "new") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 a)))

checkReplace :: (IsString t, Eq t) => Replace t -> Maybe (Replace t)

Ensure that old is nonempty.

replace_StrictText :: Replace Text -> Text -> Text

(Original Documention...)

O(m+n) Replace every non-overlapping occurrence of needle (a.k.a. old) in haystack with replacement (a.k.a. new).

This function behaves as though it was defined as follows:

replace_StrictText Replace{old,new} haystack =
  intercalate new (splitOn needle haystack)

As this suggests, each occurrence is replaced exactly once. So if needle occurs in replacement, that occurrence will not itself be replaced recursively:

>>> replace_StrictText Replace{ old = "oo", new = "foo" } "oo"
"foo"

In cases where several instances of needle overlap, only the first one will be replaced:

>>> replace_StrictText Replace{ old = "ofo", new = "bar" } "ofofo"
"barfo"

(Additional Documention...)

this function has two differences from the function it wraps:

• the "enriched" argument record Replace, done for clarity of argument order.
• the behavior when new (i.e. needle), is empty (i.e. ""), which simply outputs the input unchanged, rather than erroring.

i.e.

>>> replace_StrictText Replace{ old = "", new = "anything" } "unchanged"
"unchanged"

You can use (the trivial) checkReplace.

replace :: Replace Text -> Text -> Text

Alias for replace_StrictText.

(See replace_StrictText for documentation).

replace_LazyText :: Replace Text -> Text -> Text

Lazy analogue to replace_StrictText.

(See replace_StrictText for documentation).

sappendGeneric :: (Generic a, GSemigroup' (Rep a)) => a -> a -> a infixr 6

memptyGeneric :: (Generic a, GMonoid' (Rep a)) => a

mappendGeneric :: (Generic a, GMonoid' (Rep a)) => a -> a -> a infixr 6

data GUI

A globally unique haskell identifier, for either a value or type, fully-qualified with its module and package.

TODO new field: Version.

Constructors

GUI

Fields

• _guiPackage :: !PkgName
• _guiModule :: !ModName
• _guiIdentifier :: !OccName
• _guiNamespace :: !NameSpace

Instances

Eq GUI

Defined in Prelude.Spiros.GUI

Methods

(==) :: GUI -> GUI -> Bool

(/=) :: GUI -> GUI -> Bool

Data GUI

Defined in Prelude.Spiros.GUI

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> GUI -> c GUI

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c GUI

toConstr :: GUI -> Constr

dataTypeOf :: GUI -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c GUI)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c GUI)

gmapT :: (forall b. Data b => b -> b) -> GUI -> GUI

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> GUI -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> GUI -> r

gmapQ :: (forall d. Data d => d -> u) -> GUI -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> GUI -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> GUI -> m GUI

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> GUI -> m GUI

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> GUI -> m GUI

Ord GUI

Defined in Prelude.Spiros.GUI

Methods

compare :: GUI -> GUI -> Ordering

(<) :: GUI -> GUI -> Bool

(<=) :: GUI -> GUI -> Bool

(>) :: GUI -> GUI -> Bool

(>=) :: GUI -> GUI -> Bool

max :: GUI -> GUI -> GUI

min :: GUI -> GUI -> GUI

Show GUI

Defined in Prelude.Spiros.GUI

Methods

showsPrec :: Int -> GUI -> ShowS

show :: GUI -> String

showList :: [GUI] -> ShowS

Generic GUI

Defined in Prelude.Spiros.GUI

Associated Types

type Rep GUI :: Type -> Type

Methods

from :: GUI -> Rep GUI x

to :: Rep GUI x -> GUI

NFData GUI

Defined in Prelude.Spiros.GUI

Methods

rnf :: GUI -> ()

Hashable GUI

Defined in Prelude.Spiros.GUI

Methods

hashWithSalt :: Int -> GUI -> Int

hash :: GUI -> Int

type Rep GUI

Defined in Prelude.Spiros.GUI

type Rep GUI = D1 (MetaData "GUI" "Prelude.Spiros.GUI" "spiros-0.4.0-4h2fnqdGzKwEsvTfCIxvsa" False) (C1 (MetaCons "GUI" PrefixI True) ((S1 (MetaSel (Just "_guiPackage") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 PkgName) :*: S1 (MetaSel (Just "_guiModule") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 ModName)) :*: (S1 (MetaSel (Just "_guiIdentifier") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 OccName) :*: S1 (MetaSel (Just "_guiNamespace") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 NameSpace))))

unsafeGUI :: Name -> GUI

Return a globally unique identifier from a Template Haskell Name, even if it's local (i.e. not global).

Implementation: TemplateHaskellQuotes return only "local names" (NameL) and "global names" (NameG, which fromGlobalName validates).

• NameG

See Name:

• NameS: An unqualified name; dynamically bound
• NameQ ModName: A qualified name; dynamically bound
• NameU !Int: A unique local name
• NameL !Int: Local name bound outside of the TH AST
• NameG NameSpace PkgName ModName: Global name bound outside of the TH AST: An original name (occurrences only, not binders) Need the namespace too to be sure which thing we are naming

fromGlobalName :: Name -> Maybe GUI

if the given identifier is [1] global and [2] a value, then return it as a GUI.

e.g.

> fromGlobalName 'fromGlobalName 
Just (PkgName "spiros-0.0.1-inplace",ModName Prelude.Spiros.Exception,OccName "fromGlobalName")

Implementation Note: Name use is compatible with template-haskell >=2.11.

fromValueName :: Name -> Maybe GUI

like fromGlobalName, but restricted to identifiers (i.e. not types/classes, not constructors/patterns).

e.g.

fromTypeProxy :: forall a proxy. Typeable a => proxy a -> GUI

The globally unique identifier for a type: (pkg, modid, tycon)

>>> :set -XPolyKinds
>>> import Data.Proxy
>>> displayGUI $ fromTypeProxy (Proxy :: Proxy [])
"ghc-prim:GHC.Types.(type [])"

displayGUI :: GUI -> String

>>> displayGUI (GUI (PkgName "package-name") (ModName "Module.SubModule") (OccName "identifierName") VarName)
"package-name:Module.SubModule.identifierName"
>>> displayGUI (GUI (PkgName "package-name") (ModName "Module.SubModule") (OccName "ConstructorName") DataName)
"package-name:Module.SubModule.ConstructorName"
>>> displayGUI (GUI (PkgName "package-name") (ModName "Module.SubModule") (OccName "TypeName") TcClsName)
"package-name:Module.SubModule.(type TypeName)"

type Validator a b = forall m. MonadThrow m => a -> m b

Represents a validator as something that injects a type into another type, with the possibility of failure.

Equivalent to:

Validator a b ≡ (a -> Possibly b)
Validator a b ≡ (∀m. (MonadThrow m) => Kleisli m a b)

Specializations:

Validator a b ~ (a -> Maybe                b)
Validator a b ~ (a -> []                   b)
Validator a b ~ (a -> Either SomeException b)
Validator a b ~ (a -> IO                   b)
...

Usage:

-- x :: a
return x :: Validator a a

type Possibly b = forall m. MonadThrow m => m b

Represents a value that has possibly failed ("or" will possibly fail).

Specializations:

Possibly b ~ Maybe    b
Possibly b ~         [b]
Possibly b ~ Either _ b
Possibly b ~ IO       b
...

validator :: (MonadThrow m, Show a) => HaskellName -> (a -> Bool) -> (String -> String) -> (a -> b) -> a -> m b

Parameters:

name = validator name check display cast :: Validator _ _

e.g. validating naturals:

validateNatural :: Validator Integer Natural
validateNatural = validator 'natural
 (\i -> i >= 0)
 (\i -> i ++ " must be non-negative")
 (\i -> fromIntegral i)

is the same as the explicit:

validateNatural :: (MonadThrow m) => Integer -> m Natural
validateNatural i
 | i >= 0    = return $ fromIntegral i
 | otherwise = throwN 'validateNatural $ "must be non-negative"

and as the point-free styled:

validateNatural :: Integer -> Possibly Natural
validateNatural = validator 'natural
 (>= 0)
 (++ " must be non-negative")
 (fromIntegral)

Wraps throwN.

validator_ :: MonadThrow m => HaskellName -> (a -> Bool) -> (a -> b) -> a -> m b

More convenient, but less informative, than validator.

Parameters:

name = validator_ 'name check cast :: Validator _ _

e.g. validating naturals:

validateNatural :: Integer -> Possibly Natural
validateNatural = validator 'validateNatural (>= 0) fromIntegral

Wraps throwN_.

validateNatural :: forall i m. (Integral i, Show i) => MonadThrow m => i -> m Natural

>>> validateNatural 2
2
>>> validateNatural (-2) :: Maybe Natural
Nothing

> validateNatural (-2)

*** Exception: 
...
-2 must be non-negative
...

Specializations of i:

validateNatural Int     :: Validator Int     Natural
validateNatural Integer :: Validator Integer Natural
validateNatural @Natural :: Validator Natural Natural
...

Specializations of m:

validateNatural Int Maybe      :: Integer ->                Maybe Natural
validateNatural Int (Either _) :: Integer -> Either SomeException Natural
validateNatural Int []         :: Integer ->                     [Natural]
validateNatural Int IO         :: Integer ->                   IO Natural

Definition:

validateNatural :: forall i m. ...
validateNatural = validator 'validateNatural
 (>= 0)
 (++ " must be non-negative")
 (fromIntegral)

someMonadThrowException :: Show a => a -> SomeException

A default Exception, useful when manipulating MonadThrow instances.

An ErrorCall (whose message is uninformative).

maybeMonadThrow :: MonadThrow m => Maybe a -> m a

Generalize Maybe (a concrete, pure MonadThrow instance), to an abstract MonadThrow m.

≡ maybe (throwM _) return

maybeMonadThrowWith :: MonadThrow m => SomeException -> Maybe a -> m a

Generalize Maybe (a concrete, pure MonadThrow instance), to an abstract MonadThrow m.

maybeMonadThrowWith ≡ maybe (throwM e) return

listMonadThrow :: MonadThrow m => [a] -> m a

Generalize '[]' (a concrete, pure MonadThrow instance), to an abstract MonadThrow m.

listMonadThrow ≡ \case
  []    -> throwM _
  (x:_) -> return x

Only return the first success (i.e. the head of the "list of successes").

listMonadThrowWith :: MonadThrow m => SomeException -> [a] -> m a

Generalize '[]' (a concrete, pure MonadThrow instance), to an abstract MonadThrow m.

eitherMonadThrow :: MonadThrow m => Either SomeException a -> m a

Generalize Either SomeException (a concrete, pure MonadThrow instance), to an abstract MonadThrow m.

≡ either throwM return

newtype CallStack'

Constructors

CallStack'

Fields

• toCallFrames :: Seq CallFrame

Instances

Eq CallStack'

Defined in Prelude.Spiros.Exception

Methods

(==) :: CallStack' -> CallStack' -> Bool

(/=) :: CallStack' -> CallStack' -> Bool

Ord CallStack'

Defined in Prelude.Spiros.Exception

Methods

compare :: CallStack' -> CallStack' -> Ordering

(<) :: CallStack' -> CallStack' -> Bool

(<=) :: CallStack' -> CallStack' -> Bool

(>) :: CallStack' -> CallStack' -> Bool

(>=) :: CallStack' -> CallStack' -> Bool

max :: CallStack' -> CallStack' -> CallStack'

min :: CallStack' -> CallStack' -> CallStack'

Show CallStack'

Defined in Prelude.Spiros.Exception

Methods

showsPrec :: Int -> CallStack' -> ShowS

show :: CallStack' -> String

showList :: [CallStack'] -> ShowS

Generic CallStack'

Defined in Prelude.Spiros.Exception

Associated Types

type Rep CallStack' :: Type -> Type

Methods

from :: CallStack' -> Rep CallStack' x

to :: Rep CallStack' x -> CallStack'

NFData CallStack'

Defined in Prelude.Spiros.Exception

Methods

rnf :: CallStack' -> ()

Hashable CallStack'

Defined in Prelude.Spiros.Exception

Methods

hashWithSalt :: Int -> CallStack' -> Int

hash :: CallStack' -> Int

type Rep CallStack'

Defined in Prelude.Spiros.Exception

type Rep CallStack' = D1 (MetaData "CallStack'" "Prelude.Spiros.Exception" "spiros-0.4.0-4h2fnqdGzKwEsvTfCIxvsa" True) (C1 (MetaCons "CallStack'" PrefixI True) (S1 (MetaSel (Just "toCallFrames") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Seq CallFrame))))

data CallFrame

Constructors

CallFrame

Fields

• _CallFrame_caller :: !GUI
• _CallFrame_callSite :: !Source

Instances

Eq CallFrame

Defined in Prelude.Spiros.Exception

Methods

(==) :: CallFrame -> CallFrame -> Bool

(/=) :: CallFrame -> CallFrame -> Bool

Ord CallFrame

Defined in Prelude.Spiros.Exception

Methods

compare :: CallFrame -> CallFrame -> Ordering

(<) :: CallFrame -> CallFrame -> Bool

(<=) :: CallFrame -> CallFrame -> Bool

(>) :: CallFrame -> CallFrame -> Bool

(>=) :: CallFrame -> CallFrame -> Bool

max :: CallFrame -> CallFrame -> CallFrame

min :: CallFrame -> CallFrame -> CallFrame

Show CallFrame

Defined in Prelude.Spiros.Exception

Methods

showsPrec :: Int -> CallFrame -> ShowS

show :: CallFrame -> String

showList :: [CallFrame] -> ShowS

Generic CallFrame

Defined in Prelude.Spiros.Exception

Associated Types

type Rep CallFrame :: Type -> Type

Methods

from :: CallFrame -> Rep CallFrame x

to :: Rep CallFrame x -> CallFrame

NFData CallFrame

Defined in Prelude.Spiros.Exception

Methods

rnf :: CallFrame -> ()

Hashable CallFrame

Defined in Prelude.Spiros.Exception

Methods

hashWithSalt :: Int -> CallFrame -> Int

hash :: CallFrame -> Int

type Rep CallFrame

Defined in Prelude.Spiros.Exception

type Rep CallFrame = D1 (MetaData "CallFrame" "Prelude.Spiros.Exception" "spiros-0.4.0-4h2fnqdGzKwEsvTfCIxvsa" False) (C1 (MetaCons "CallFrame" PrefixI True) (S1 (MetaSel (Just "_CallFrame_caller") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 GUI) :*: S1 (MetaSel (Just "_CallFrame_callSite") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Source)))

data Source

A single location in the source code.

Equivalent to SrcLoc:

srcLocPackage   :: String
srcLocModule    :: String
srcLocFile      :: String
srcLocStartLine :: Int	 
srcLocStartCol  :: Int	 
srcLocEndLine   :: Int	 
srcLocEndCol    :: Int

but with more instances.

Constructors

Source

Fields

• _sourcePackage :: !Text
• _sourceModule :: !Text
• _sourceFilename :: !Text
• _sourceFileSpan :: !FileSpan

Instances

Eq Source

Defined in Prelude.Spiros.Exception

Methods

(==) :: Source -> Source -> Bool

(/=) :: Source -> Source -> Bool

Ord Source

Defined in Prelude.Spiros.Exception

Methods

compare :: Source -> Source -> Ordering

(<) :: Source -> Source -> Bool

(<=) :: Source -> Source -> Bool

(>) :: Source -> Source -> Bool

(>=) :: Source -> Source -> Bool

max :: Source -> Source -> Source

min :: Source -> Source -> Source

Read Source

Defined in Prelude.Spiros.Exception

Methods

readsPrec :: Int -> ReadS Source

readList :: ReadS [Source]

readPrec :: ReadPrec Source

readListPrec :: ReadPrec [Source]

Show Source

Defined in Prelude.Spiros.Exception

Methods

showsPrec :: Int -> Source -> ShowS

show :: Source -> String

showList :: [Source] -> ShowS

Generic Source

Defined in Prelude.Spiros.Exception

Associated Types

type Rep Source :: Type -> Type

Methods

from :: Source -> Rep Source x

to :: Rep Source x -> Source

NFData Source

Defined in Prelude.Spiros.Exception

Methods

rnf :: Source -> ()

Hashable Source

Defined in Prelude.Spiros.Exception

Methods

hashWithSalt :: Int -> Source -> Int

hash :: Source -> Int

type Rep Source

Defined in Prelude.Spiros.Exception

type Rep Source = D1 (MetaData "Source" "Prelude.Spiros.Exception" "spiros-0.4.0-4h2fnqdGzKwEsvTfCIxvsa" False) (C1 (MetaCons "Source" PrefixI True) ((S1 (MetaSel (Just "_sourcePackage") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Text) :*: S1 (MetaSel (Just "_sourceModule") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Text)) :*: (S1 (MetaSel (Just "_sourceFilename") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Text) :*: S1 (MetaSel (Just "_sourceFileSpan") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 FileSpan))))

data FileSpan

The location of something spanning a contiguous region in a file.

The [start .. end] range is inclusive.

e.g. a highlighted region.

Constructors

FileSpan

Fields

• _spanStart :: !FilePosition
• _spanEnd :: !FilePosition

Instances

Eq FileSpan

Defined in Prelude.Spiros.Exception

Methods

(==) :: FileSpan -> FileSpan -> Bool

(/=) :: FileSpan -> FileSpan -> Bool

Ord FileSpan

Defined in Prelude.Spiros.Exception

Methods

compare :: FileSpan -> FileSpan -> Ordering

(<) :: FileSpan -> FileSpan -> Bool

(<=) :: FileSpan -> FileSpan -> Bool

(>) :: FileSpan -> FileSpan -> Bool

(>=) :: FileSpan -> FileSpan -> Bool

max :: FileSpan -> FileSpan -> FileSpan

min :: FileSpan -> FileSpan -> FileSpan

Read FileSpan

Defined in Prelude.Spiros.Exception

Methods

readsPrec :: Int -> ReadS FileSpan

readList :: ReadS [FileSpan]

readPrec :: ReadPrec FileSpan

readListPrec :: ReadPrec [FileSpan]

Show FileSpan

Defined in Prelude.Spiros.Exception

Methods

showsPrec :: Int -> FileSpan -> ShowS

show :: FileSpan -> String

showList :: [FileSpan] -> ShowS

Generic FileSpan

Defined in Prelude.Spiros.Exception

Associated Types

type Rep FileSpan :: Type -> Type

Methods

from :: FileSpan -> Rep FileSpan x

to :: Rep FileSpan x -> FileSpan

NFData FileSpan

Defined in Prelude.Spiros.Exception

Methods

rnf :: FileSpan -> ()

Hashable FileSpan

Defined in Prelude.Spiros.Exception

Methods

hashWithSalt :: Int -> FileSpan -> Int

hash :: FileSpan -> Int

type Rep FileSpan

Defined in Prelude.Spiros.Exception

type Rep FileSpan = D1 (MetaData "FileSpan" "Prelude.Spiros.Exception" "spiros-0.4.0-4h2fnqdGzKwEsvTfCIxvsa" False) (C1 (MetaCons "FileSpan" PrefixI True) (S1 (MetaSel (Just "_spanStart") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 FilePosition) :*: S1 (MetaSel (Just "_spanEnd") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 FilePosition)))

data FilePosition

The location of a single cell (e.g. a character) in a file.

We conceive text files as grids, so this is equivalent to a 2 dimensional point, with different naming. The line number $sel:_fileLine:FilePosition is like the y-coordinate (descending vertically); the column number $sel:_fileColumn:FilePosition being the x-coordinate.

TODO One-indexed ("the first line") versus Zero-indexed?

Constructors

FilePosition

Fields

• _fileLine :: !Int
• _fileColumn :: !Int

Instances

Eq FilePosition

Defined in Prelude.Spiros.Exception

Methods

(==) :: FilePosition -> FilePosition -> Bool

(/=) :: FilePosition -> FilePosition -> Bool

Ord FilePosition

Defined in Prelude.Spiros.Exception

Methods

compare :: FilePosition -> FilePosition -> Ordering

(<) :: FilePosition -> FilePosition -> Bool

(<=) :: FilePosition -> FilePosition -> Bool

(>) :: FilePosition -> FilePosition -> Bool

(>=) :: FilePosition -> FilePosition -> Bool

max :: FilePosition -> FilePosition -> FilePosition

min :: FilePosition -> FilePosition -> FilePosition

Read FilePosition

Defined in Prelude.Spiros.Exception

Methods

readsPrec :: Int -> ReadS FilePosition

readList :: ReadS [FilePosition]

readPrec :: ReadPrec FilePosition

readListPrec :: ReadPrec [FilePosition]

Show FilePosition

Defined in Prelude.Spiros.Exception

Methods

showsPrec :: Int -> FilePosition -> ShowS

show :: FilePosition -> String

showList :: [FilePosition] -> ShowS

Generic FilePosition

Defined in Prelude.Spiros.Exception

Associated Types

type Rep FilePosition :: Type -> Type

Methods

from :: FilePosition -> Rep FilePosition x

to :: Rep FilePosition x -> FilePosition

NFData FilePosition

Defined in Prelude.Spiros.Exception

Methods

rnf :: FilePosition -> ()

Hashable FilePosition

Defined in Prelude.Spiros.Exception

Methods

hashWithSalt :: Int -> FilePosition -> Int

hash :: FilePosition -> Int

type Rep FilePosition

Defined in Prelude.Spiros.Exception

type Rep FilePosition = D1 (MetaData "FilePosition" "Prelude.Spiros.Exception" "spiros-0.4.0-4h2fnqdGzKwEsvTfCIxvsa" False) (C1 (MetaCons "FilePosition" PrefixI True) (S1 (MetaSel (Just "_fileLine") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Int) :*: S1 (MetaSel (Just "_fileColumn") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Int)))

throwEither :: (MonadThrow m, Exception e) => Either e a -> m a

throwEither = either
 throwE
 return

throwEitherWith :: (MonadThrow m, Show e) => Either e a -> m a

throwMaybe :: MonadThrow m => Maybe a -> m a

throwMaybeWith :: (MonadThrow m, Exception e) => e -> Maybe a -> m a

throwList :: MonadThrow m => List a -> m a

throwListWith :: (MonadThrow m, Exception e) => e -> List a -> m a

data SimpleException

Constructors

SimpleException

Fields

• _SimpleException_message :: !String

Instances

Eq SimpleException

Defined in Prelude.Spiros.Exception

Methods

(==) :: SimpleException -> SimpleException -> Bool

(/=) :: SimpleException -> SimpleException -> Bool

Ord SimpleException

Defined in Prelude.Spiros.Exception

Methods

compare :: SimpleException -> SimpleException -> Ordering

(<) :: SimpleException -> SimpleException -> Bool

(<=) :: SimpleException -> SimpleException -> Bool

(>) :: SimpleException -> SimpleException -> Bool

(>=) :: SimpleException -> SimpleException -> Bool

max :: SimpleException -> SimpleException -> SimpleException

min :: SimpleException -> SimpleException -> SimpleException

Read SimpleException

Defined in Prelude.Spiros.Exception

Methods

readsPrec :: Int -> ReadS SimpleException

readList :: ReadS [SimpleException]

readPrec :: ReadPrec SimpleException

readListPrec :: ReadPrec [SimpleException]

Show SimpleException

custom for Exception (non-Readable).

= displaySimpleException

Defined in Prelude.Spiros.Exception

Methods

showsPrec :: Int -> SimpleException -> ShowS

show :: SimpleException -> String

showList :: [SimpleException] -> ShowS

IsString SimpleException

SimpleException

Defined in Prelude.Spiros.Exception

Methods

fromString :: String -> SimpleException

Generic SimpleException

Defined in Prelude.Spiros.Exception

Associated Types

type Rep SimpleException :: Type -> Type

Methods

from :: SimpleException -> Rep SimpleException x

to :: Rep SimpleException x -> SimpleException

Exception SimpleException

Defined in Prelude.Spiros.Exception

Methods

toException :: SimpleException -> SomeException

fromException :: SomeException -> Maybe SimpleException

displayException :: SimpleException -> String

Default SimpleException

SimpleException ""

Defined in Prelude.Spiros.Exception

Methods

def :: SimpleException

NFData SimpleException

Defined in Prelude.Spiros.Exception

Methods

rnf :: SimpleException -> ()

Hashable SimpleException

Defined in Prelude.Spiros.Exception

Methods

hashWithSalt :: Int -> SimpleException -> Int

hash :: SimpleException -> Int

type Rep SimpleException

Defined in Prelude.Spiros.Exception

type Rep SimpleException = D1 (MetaData "SimpleException" "Prelude.Spiros.Exception" "spiros-0.4.0-4h2fnqdGzKwEsvTfCIxvsa" False) (C1 (MetaCons "SimpleException" PrefixI True) (S1 (MetaSel (Just "_SimpleException_message") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 String)))

displaySimpleException :: SimpleException -> String

formatCustomExceptionWithCaller if the message is empty, formatCustomExceptionWithMessage otherwise.

data QuotedException

Constructors

QuotedException

Fields

• _QuotedException_caller :: !GUI
• _QuotedException_message :: !String

Instances

Eq QuotedException

Defined in Prelude.Spiros.Exception

Methods

(==) :: QuotedException -> QuotedException -> Bool

(/=) :: QuotedException -> QuotedException -> Bool

Ord QuotedException

Defined in Prelude.Spiros.Exception

Methods

compare :: QuotedException -> QuotedException -> Ordering

(<) :: QuotedException -> QuotedException -> Bool

(<=) :: QuotedException -> QuotedException -> Bool

(>) :: QuotedException -> QuotedException -> Bool

(>=) :: QuotedException -> QuotedException -> Bool

max :: QuotedException -> QuotedException -> QuotedException

min :: QuotedException -> QuotedException -> QuotedException

Show QuotedException

custom for Exception (non-Readable).

= displayQuotedException

Defined in Prelude.Spiros.Exception

Methods

showsPrec :: Int -> QuotedException -> ShowS

show :: QuotedException -> String

showList :: [QuotedException] -> ShowS

IsString QuotedException

= QuotedException 'throwM.

NOTE the prefixing apostrophe is a TemplateHaskellQuotes name quote (not a typo)

Defined in Prelude.Spiros.Exception

Methods

fromString :: String -> QuotedException

Generic QuotedException

Defined in Prelude.Spiros.Exception

Associated Types

type Rep QuotedException :: Type -> Type

Methods

from :: QuotedException -> Rep QuotedException x

to :: Rep QuotedException x -> QuotedException

Exception QuotedException

Defined in Prelude.Spiros.Exception

Methods

toException :: QuotedException -> SomeException

fromException :: SomeException -> Maybe QuotedException

displayException :: QuotedException -> String

Default QuotedException

"" :: QuotedException (see the IsString instance).

Defined in Prelude.Spiros.Exception

Methods

def :: QuotedException

NFData QuotedException

Defined in Prelude.Spiros.Exception

Methods

rnf :: QuotedException -> ()

Hashable QuotedException

Defined in Prelude.Spiros.Exception

Methods

hashWithSalt :: Int -> QuotedException -> Int

hash :: QuotedException -> Int

type Rep QuotedException

Defined in Prelude.Spiros.Exception

type Rep QuotedException = D1 (MetaData "QuotedException" "Prelude.Spiros.Exception" "spiros-0.4.0-4h2fnqdGzKwEsvTfCIxvsa" False) (C1 (MetaCons "QuotedException" PrefixI True) (S1 (MetaSel (Just "_QuotedException_caller") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 GUI) :*: S1 (MetaSel (Just "_QuotedException_message") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 String)))

displayQuotedException :: QuotedException -> String

formatCustomExceptionWithMessage

formatCustomExceptionWithCaller :: String -> String

formatCustomExceptionWithMessage :: String -> String -> String

formatCustomExceptionWithCallStack :: String -> String -> String -> String

displayQualifiedVariable :: Name -> String

>>> :set -XTemplateHaskellQuotes
>>> displayQualifiedVariable 'length
"base:Data.Foldable.length"
>>> import qualified Prelude
>>> displayQualifiedVariable 'Prelude.length
"base:Data.Foldable.length"

let x = undefined in displayQualifiedVariable 'x == "?"

throwE :: (MonadThrow m, Exception e) => e -> m a

E for Exception,

throwMs a SimpleException.

throwS :: MonadThrow m => String -> m a

S for String,

throwMs a SimpleException.

e.g.

> throwS "this is an example"
*** Exception: 

[spiros-0.0.1-inplace:Prelude.Spiros.Exception.throwS] was called with:

this is an example

e.g.

> throwS ""
*** Exception: 

[spiros-0.0.1-inplace:Prelude.Spiros.Exception.throwS] was called.

throwN :: MonadThrow m => Name -> String -> m a

N for Name,

throwMs a QuotedException with the given caller and message.

e.g.

> throwN 'throwN "this is an example"
*** Exception: 

[spiros-0.0.1-inplace:Prelude.Spiros.Exception.throwN] was called with:

this is an example

Useful for easily defining smart constructors, whose error message has a fully-qualified name for debugging. If you rename the module, the error message changes automatically; and if you rename the identifier, you will get a compile time error from Template Haskell if you don't simultaneously update the useage of throwN (unless another name is captured).

e.g. validating naturals:

natural :: Integer -> Possibly Natural
natural i
 | i >= 0    = return $ fromIntegral i
 | otherwise = throwN 'natural $ "must be non-negative"

throwN_ :: MonadThrow m => Name -> m a

throwN_ name = throwN name ""

e.g. validating naturals:

natural :: Integer -> Possibly Natural
natural i
 | i >= 0    = return $ fromIntegral i
 | otherwise = throwN_ 'natural

guardE :: (MonadThrow m, Exception e) => e -> Bool -> m ()

E for Exception, calls throwM.

NOTE if [1] you don't like the naming convention of the convenience functions below, or [2] if you need custom exceptions that aren't just a message with some location information, then directly use some exception (like when using the exceptions pacakge).

e.g.:

>>> import Control.Exception (ArithException(..))
>>> divideM x y = guardE DivideByZero (y /= (0::Double)) >> return (x / y)
>>> :t divideM
divideM :: MonadThrow m => Double -> Double -> m Double
>>> divideM 1 4
0.25
>>> divideM 1 0
*** Exception: divide by zero
>>> divideM 1 4 :: Maybe Double
Just 0.25
>>> divideM 1 0 :: Maybe Double
Nothing

guardM :: MonadThrow m => Bool -> m ()

M for MonadThrow, like throwM.

MonadThrow analogue of base's guard.

= guardE uninformative

guardS :: MonadThrow m => String -> Bool -> m ()

S for String, calls throwM.

guardN :: MonadThrow m => Name -> Bool -> m ()

N for Name, calls throwM.

guardF :: MonadFail m => String -> Bool -> m ()

F for MonadFail, calls fail.

guardP :: MonadPlus m => Bool -> m ()

P for MonadPlus, calls mzero.

uninformative :: SomeException

someSimpleException_

someSimpleException_ :: SomeException

the default SimpleException.

someQuotedException_ :: SomeException

the default QuotedException.

someSimpleException :: String -> SomeException

someQuotedException :: Name -> String -> SomeException

throwL :: (MonadThrow m, HasCallStack) => String -> m a

L for Location or CallStack (caLLstack, lol).

throwMs a LocatedException with the given call-stack and message.

e.g.

> caller = throwL "this is an example"

> caller
*** Exception: 

[safe-exceptions-0.1.6.0-HpnSY2upHz4DtQ1B03RoNw:Control.Exception.Safe.throwM] was called with:

this is an example

... and called from:

CallStack (from HasCallStack):
  toLocatedException, called at sourcesPreludeSpiros/Exception.hs:385:20 in spiros-0.0.1-inplace:Prelude.Spiros.Exception
  throwL, called at interactive:28:1 in interactive:Ghci1

guardL :: (MonadThrow m, HasCallStack) => Bool -> m ()

L for Location or CallStack (caLLstack).

someLocatedException_ :: HasCallStack => SomeException

the default LocatedException.

someLocatedException :: HasCallStack => String -> SomeException

data LocatedException

Constructors

LocatedException

Fields

• _LocatedException_stack :: !CallStack
• _LocatedException_message :: !String

Instances

Show LocatedException

custom for Exception (non-Readable).

= displayLocatedException

Defined in Prelude.Spiros.Exception

Methods

showsPrec :: Int -> LocatedException -> ShowS

show :: LocatedException -> String

showList :: [LocatedException] -> ShowS

IsString LocatedException

Requires HasCallStack around wherever the string literal is (i.e. at the "call-site" of fromString).

Defined in Prelude.Spiros.Exception

Methods

fromString :: String -> LocatedException

Generic LocatedException

Defined in Prelude.Spiros.Exception

Associated Types

type Rep LocatedException :: Type -> Type

Methods

from :: LocatedException -> Rep LocatedException x

to :: Rep LocatedException x -> LocatedException

Exception LocatedException

Defined in Prelude.Spiros.Exception

Methods

toException :: LocatedException -> SomeException

fromException :: SomeException -> Maybe LocatedException

displayException :: LocatedException -> String

Default LocatedException

"" :: LocatedException (see the IsString instance).

Defined in Prelude.Spiros.Exception

Methods

def :: LocatedException

type Rep LocatedException

Defined in Prelude.Spiros.Exception

type Rep LocatedException = D1 (MetaData "LocatedException" "Prelude.Spiros.Exception" "spiros-0.4.0-4h2fnqdGzKwEsvTfCIxvsa" False) (C1 (MetaCons "LocatedException" PrefixI True) (S1 (MetaSel (Just "_LocatedException_stack") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 CallStack) :*: S1 (MetaSel (Just "_LocatedException_message") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 String)))

toLocatedException :: HasCallStack => String -> LocatedException

LocatedException callStack _

displayLocatedException :: LocatedException -> String

formatCustomExceptionWithCallStack

module Prelude.Spiros.System

module Prelude.Spiros.Utilities

module Prelude.Spiros.Reexports

module Prelude.Spiros.Types

Usage

assertions:

assert :: Bool -> a -> a 

If the first argument evaluates to True, then the result is the second argument. Otherwise an AssertionFailed exception is raised, containing a String with the source file and line number of the call to assert.

Assertions can normally be turned on or off with a compiler flag (for GHC, assertions are normally on unless optimisation is turned on with -O or the -fignore-asserts option is given). When assertions are turned off, the first argument to assert is ignored, and the second argument is returned as the result.

Non-exports

These must be explicitly imported, they aren't re-exported by Prelude.Spiros.

Prelude.Spiros.Classes re-exports only typeclases/methods (and a few helpers), from several packages (like Prelude.Spiros.Reexports), for deriving or defining instances (e.g. in a .Types module). Unlike Prelude.Spiros.Reexports, partial functions that are methods (like toEnum and fromEnum) are necessarily exported, since they must be visible when manually writing instances.

Notes

Most examples (all those prefixed with a triple @>>>@) are doctested. Those with single @>@ may have brittle output, and codeblocks might describe relations by "returning" variables, and thus aren't.