Intended Specializations:

• Replace Text

• Replace Text

Ensure that old is nonempty.

(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.

Alias for replace_StrictText.

(See replace_StrictText for documentation).

Lazy analogue to replace_StrictText.

(See replace_StrictText for documentation).

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

TODO new field: Version.

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

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.

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

e.g.

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 (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)"

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

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
...

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.

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 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)

A default Exception, useful when manipulating MonadThrow instances.

An ErrorCall (whose message is uninformative).

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

≡ maybe (throwM _) return

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

maybeMonadThrowWith ≡ maybe (throwM e) return

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").

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

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

≡ either throwM return

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.

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

The [start .. end] range is inclusive.

e.g. a highlighted region.

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?

throwEither = either
 throwE
 return

formatCustomExceptionWithCaller if the message is empty, formatCustomExceptionWithMessage otherwise.

formatCustomExceptionWithMessage

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

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

E for Exception,

throwMs a SimpleException.

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.

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_ name = throwN name ""

e.g. validating naturals:

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

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

M for MonadThrow, like throwM.

MonadThrow analogue of base's guard.

= guardE uninformative

S for String, calls throwM.

N for Name, calls throwM.

F for MonadFail, calls fail.

P for MonadPlus, calls mzero.

someSimpleException_

the default SimpleException.

the default QuotedException.

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

L for Location or CallStack (caLLstack).

the default LocatedException.

LocatedException callStack _

formatCustomExceptionWithCallStack