Maybe package:clash-prelude

The Maybe type encapsulates an optional value. A value of type Maybe a either contains a value of type a (represented as Just a), or it is empty (represented as Nothing). Using Maybe is a good way to deal with errors or exceptional cases without resorting to drastic measures such as error. The Maybe type is also a monad. It is a simple kind of error monad, where all errors are represented by Nothing. A richer error monad can be built using the Either type.

The maybe function takes a default value, a function, and a Maybe value. If the Maybe value is Nothing, the function returns the default value. Otherwise, it applies the function to the value inside the Just and returns the result.

Examples

Basic usage:

>>> maybe False odd (Just 3)
True

>>> maybe False odd Nothing
False

Read an integer from a string using readMaybe. If we succeed, return twice the integer; that is, apply (*2) to it. If instead we fail to parse an integer, return 0 by default:

>>> import Text.Read ( readMaybe )

>>> maybe 0 (*2) (readMaybe "5")
10

>>> maybe 0 (*2) (readMaybe "")
0

Apply show to a Maybe Int. If we have Just n, we want to show the underlying Int n. But if we have Nothing, we return the empty string instead of (for example) "Nothing":

>>> maybe "" show (Just 5)
"5"

>>> maybe "" show Nothing
""

Helpers to make XException explicit in the type system. Using these helpers can help programmers account for XExceptions properly in blackbox models or tests. Note that none of these operations can be translated to HDL.

Structure helping programmers to deal with XException values. For safety reasons it can't be constructed directly, but should be constructed using either pure or toMaybeX. After construction, it can be deconstructed using either IsX or IsDefined.

Return a typed 'Maybe TopEntity' expression given a Name. This will return an TExp of Nothing if TopEntity generation failed.

Fully evaluate a value, returning Nothing if it throws XException. Note that non-XException errors take precedence over XException ones.

maybeHasX 42                    = Just 42
maybeHasX (XException msg)      = Nothing
maybeHasX (3, XException msg)   = Nothing
maybeHasX (XException msg, _|_) = _|_
maybeHasX (_|_, XException msg) = _|_
maybeHasX (3, _|_)              = _|_
maybeHasX _|_                   = _|_

Evaluate a value to WHNF, returning Nothing if it throws XException.

maybeIsX 42                  = Just 42
maybeIsX (XException msg)    = Nothing
maybeIsX (3, XException msg) = Just (3, XException msg)
maybeIsX (3, _|_)            = Just (3, _|_)
maybeIsX _|_                 = _|_

Map functions over both constructors.

Derive a compactly represented version of Maybe a.

Version of delay that only updates when its third argument is a Just value.

>>> let input = fromList [Just 1, Just 2, Nothing, Nothing, Just 5, Just 6, Just (7::Int)]

>>> sampleN 7 (delayMaybe systemClockGen enableGen 0 input)
[0,1,2,2,2,5,6]

Version of register that only updates its content when its fourth argument is a Just value. So given:

sometimes1 clk rst en = s where
s = register clk rst en Nothing (switch <$> s)

switch Nothing = Just 1
switch _       = Nothing

countSometimes clk rst en = s where
s     = regMaybe clk rst en 0 (plusM (pure <$> s) (sometimes1 clk rst en))
plusM = liftA2 (liftA2 (+))

We get:

>>> sampleN 9 (sometimes1 systemClockGen resetGen enableGen)
[Nothing,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1]

>>> sampleN 9 (count systemClockGen resetGen enableGen)
[0,0,0,1,1,2,2,3,3]

Version of delay that only updates when its second argument is a Just value.

>>> let input = fromList [Just 1, Just 2, Nothing, Nothing, Just 5, Just 6, Just (7::Int)]

>>> sampleN @System 7 (delayMaybe 0 input)
[0,1,2,2,2,5,6]

Version of register that only updates its content when its second argument is a Just value. So given:

sometimes1 = s where
s = register Nothing (switch <$> s)

switch Nothing = Just 1
switch _       = Nothing

countSometimes = s where
s     = regMaybe 0 (plusM (pure <$> s) sometimes1)
plusM = liftA2 (liftA2 (+))

We get:

>>> sampleN @System 9 sometimes1
[Nothing,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1]

>>> sampleN @System 9 countSometimes
[0,0,0,1,1,2,2,3,3]

Deconstruct MaybeX into an a - the opposite of toMaybeX. Be careful when using this function, because it might return an XException if the argument was IsX.

Construct a MaybeX value. If hasX evaluates to Left, this function will return IsX. Otherwise, it will return IsDefined.

Construct a MaybeX value. If a evaluates to XException, this function will return IsX. Otherwise, it will return IsDefined.