{-|

Module      : Maybe
Description : A `Maybe` can help you with optional arguments, error handling, and records with optional fields.
License     : BSD 3
Maintainer  : terezasokol@gmail.com
Stability   : experimental
Portability : POSIX

A `Maybe` can help you with optional arguments, error handling, and records with optional fields.

-}

module Maybe
  ( -- * Definition
    Maybe(..)

    -- * Common Helpers
  , withDefault, map, map2, map3, map4, map5

    -- * Chaining Maybes
  , andThen

    -- * From Haskell types
  , fromHMaybe
  )
where

import Prelude (Applicative, Char, Eq, Functor, Monad, Num, Ord, Show, flip, fromIntegral, mappend, mconcat, otherwise, pure)
import qualified Prelude
import qualified Internal.Shortcut as Shortcut


{-| Represent values that may or may not exist. It can be useful if you have a
record field that is only filled in sometimes. Or if a function takes a value
sometimes, but does not absolutely need it.

  >  -- A person, but maybe we do not know their age.
  >  data Person = Person
  >      { name :: String
  >      , age :: Maybe Int
  >      }
  >
  >  tom = { name = "Tom", age = Just 42 }
  >  sue = { name = "Sue", age = Nothing }
-}
data Maybe a
  = Just a
  | Nothing
  deriving (Prelude.Show, Prelude.Eq)


instance Functor Maybe where
  fmap func maybe =
    case maybe of
      Just a -> Just (func a)
      Nothing -> Nothing


instance Applicative Maybe where
  pure a =
    Just a

  (<*>) func maybe =
    case (func, maybe) of
      (Just f, Just a) -> Just (f a)
      _ -> Nothing


instance Monad Maybe where
  maybe >>= func =
   case maybe of
      Just a -> func a
      Nothing -> Nothing


{-| Provide a default value, turning an optional value into a normal
value.  This comes in handy when paired with functions like
[`Dict.get`](Dict#get) which gives back a `Maybe`.

  >  withDefault 100 (Just 42)   -- 42
  >  withDefault 100 Nothing     -- 100
  >
  >  withDefault "unknown" (Dict.get "Tom" Dict.empty)   -- "unknown"

Note: This can be overused! Many cases are better handled by a `case`
expression. And if you end up using `withDefault` a lot, it can be a good sign
that a [custom type](https://guide.elm-lang.org/types/custom_types.html) will clean your code up quite a bit!
-}
withDefault :: a -> Maybe a -> a
withDefault value maybe =
  case maybe of
    Just a -> a
    Nothing -> value


{-| Transform a `Maybe` value with a given function:

  >  map sqrt (Just 9) == Just 3
  >  map sqrt Nothing  == Nothing

  >  map sqrt (String.toFloat "9") == Just 3
  >  map sqrt (String.toFloat "x") == Nothing

-}
map :: (a -> b) -> Maybe a -> Maybe b
map =
  Shortcut.map


{-| Apply a function if all the arguments are `Just` a value.

  >  map2 (+) (Just 3) (Just 4) == Just 7
  >  map2 (+) (Just 3) Nothing == Nothing
  >  map2 (+) Nothing (Just 4) == Nothing
  >
  >  map2 (+) (String.toInt "1") (String.toInt "123") == Just 124
  >  map2 (+) (String.toInt "x") (String.toInt "123") == Nothing
  >  map2 (+) (String.toInt "1") (String.toInt "1.3") == Nothing
-}
map2 :: (a -> b -> value) -> Maybe a -> Maybe b -> Maybe value
map2 =
  Shortcut.map2


{-|-}
map3 :: (a -> b -> c -> value) -> Maybe a -> Maybe b -> Maybe c -> Maybe value
map3 =
  Shortcut.map3


{-|-}
map4 :: (a -> b -> c -> d -> value) -> Maybe a -> Maybe b -> Maybe c -> Maybe d -> Maybe value
map4 =
  Shortcut.map4


{-|-}
map5 :: (a -> b -> c -> d -> e -> value) -> Maybe a -> Maybe b -> Maybe c -> Maybe d -> Maybe e -> Maybe value
map5 =
  Shortcut.map5


{-| Chain together many computations that may fail. It is helpful to see its
definition:

  >  andThen :: (a -> Maybe b) -> Maybe a -> Maybe b
  >  andThen callback maybe =
  >      case maybe of
  >          Just value ->
  >              callback value
  >
  >          Nothing ->
  >              Nothing

This means we only continue with the callback if things are going well. For
example, say you need to parse some user input as a month:

  >  parseMonth :: String -> Maybe Int
  >  parseMonth userInput =
  >      String.toInt userInput
  >        |> andThen toValidMonth
  >
  >  toValidMonth :: Int -> Maybe Int
  >  toValidMonth month =
  >      if 1 <= month && month <= 12 then
  >          Just month
  >      else
  >          Nothing

In the `parseMonth` function, if `String.toInt` produces `Nothing` (because
the `userInput` was not an integer) this entire chain of operations will
short-circuit and result in `Nothing`. If `toValidMonth` results in `Nothing`,
again the chain of computations will result in `Nothing`.
-}
andThen :: (a -> Maybe b) -> Maybe a -> Maybe b
andThen =
  Shortcut.andThen


{-| -}
fromHMaybe :: Prelude.Maybe a -> Maybe a
fromHMaybe maybe =
  case maybe of
    Prelude.Just a -> Just a
    Prelude.Nothing -> Nothing