optional-args-1.0.2: Optional function arguments

Safe Haskell | Safe-Inferred
Language | Haskell2010

Data.Optional

Contents

- Optional
- Re-exports

Description

Use the `Optional` type for optional function arguments. For example:

    import Data.Optional

    greet :: Optional String -> String
    greet (Specific name) = "Hello, " ++ name
    greet  Default        = "Hello"

    >>> greet (Specific "John")
    "Hello, John"
    >>> greet Default
    "Hello"

The `Optional` type overloads as many Haskell literals as possible so that you do not need to wrap values in `Specific`. For example, if you enable the `OverloadedStrings` extension you can use a naked string literal instead:

    >>> :set -XOverloadedStrings
    >>> greet "John"
    "Hello, John"

The `Optional` type also implements `Num` and `Fractional`, so you can use numeric literals in place of `Optional` values:

    birthday :: Optional Int -> String
    birthday (Specific age) = "You are " ++ show age ++ " years old!"
    birthday  Default       = "You are one year older!"

    >>> birthday 20
    "You are 20 years old!"
    >>> birthday Default
    "You are one year older!"

The `IsString`, `Num`, and `Fractional` instances are recursive, so you can wrap your types in a more descriptive newtype and derive `IsString`, `Num` or `Fractional`:

    {-# LANGUAGE GeneralizedNewtypeDeriving #-}

    import Data.Optional
    import Data.String (IsString)

    newtype Name = Name { getName :: String } deriving (IsString)

    greet :: Optional Name -> String
    greet (Specific name) = "Hello, " ++ getName name
    greet  Default        = "Hello"

    newtype Age = Age { getAge :: Int } deriving (Num)

    birthday :: Optional Age -> String
    birthday (Specific age) = "You are " ++ show (getAge age) ++ " years old!"
    birthday  Default       = "You are one year older!"

... and you would still be able to provide naked numeric or string literals:

    >>> :set -XOverloadedStrings
    >>> greet "John"
    "Hello, John"
    >>> birthday 20
    "You are 20 years old!"

You can use `empty` as a short-hand for a `Default` argument:

    >>> greet empty
    "Hello"
    >>> birthday empty
    "You are one year older!"

You can also use `pure` as a short-hand for a `Specific` argument:

    >>> greet (pure "John")
    "Hello, John"
    >>> birthday (pure 20)
    "You are 20 years old!"

Synopsis

- data Optional a
  - = Default
  - | Specific a
- defaultTo :: a -> Optional a -> a
- fromOptional :: Alternative f => Optional a -> f a
- optional :: b -> (a -> b) -> Optional a -> b
- empty :: Alternative f => f a
- pure :: Applicative f => a -> f a

# Optional

data Optional a Source #

A function argument that has a `Default` value

Constructors

Default |
Specific a |

#### Instances

Instances details

Alternative Optional Source # |
Instance details Defined in Data.Optional Methods empty :: Optional a Source # (<|>) :: Optional a -> Optional a -> Optional a Source # some :: Optional a -> Optional [a] Source # many :: Optional a -> Optional [a] Source #
Applicative Optional Source # |
Instance details Defined in Data.Optional Methods pure :: a -> Optional a Source # (<*>) :: Optional (a -> b) -> Optional a -> Optional b Source # liftA2 :: (a -> b -> c) -> Optional a -> Optional b -> Optional c Source # (*>) :: Optional a -> Optional b -> Optional b Source # (<*) :: Optional a -> Optional b -> Optional a Source #
Functor Optional Source # |
Instance details Defined in Data.Optional Methods fmap :: (a -> b) -> Optional a -> Optional b Source # (<$) :: a -> Optional b -> Optional a Source #
Monad Optional Source # |
Instance details Defined in Data.Optional Methods (>>=) :: Optional a -> (a -> Optional b) -> Optional b Source # (>>) :: Optional a -> Optional b -> Optional b Source # return :: a -> Optional a Source #
MonadPlus Optional Source # |
Instance details Defined in Data.Optional Methods mzero :: Optional a Source # mplus :: Optional a -> Optional a -> Optional a Source #
Foldable Optional Source # |

Instance details

Defined in Data.Optional

Methods

fold :: Monoid m => Optional m -> m Source #

foldMap :: Monoid m => (a -> m) -> Optional a -> m Source #

foldMap' :: Monoid m => (a -> m) -> Optional a -> m Source #

foldr :: (a -> b -> b) -> b -> Optional a -> b Source #

foldr' :: (a -> b -> b) -> b -> Optional a -> b Source #

foldl :: (b -> a -> b) -> b -> Optional a -> b Source #

foldl' :: (b -> a -> b) -> b -> Optional a -> b Source #

foldr1 :: (a -> a -> a) -> Optional a -> a Source #

foldl1 :: (a -> a -> a) -> Optional a -> a Source #

toList :: Optional a -> [a] Source #

null :: Optional a -> Bool Source #

length :: Optional a -> Int Source #

elem :: Eq a => a -> Optional a -> Bool Source #

maximum :: Ord a => Optional a -> a Source #

minimum :: Ord a => Optional a -> a Source #

sum :: Num a => Optional a -> a Source #

product :: Num a => Optional a -> a Source #

Traversable Optional Source # |
Instance details Defined in Data.Optional Methods traverse :: Applicative f => (a -> f b) -> Optional a -> f (Optional b) Source # sequenceA :: Applicative f => Optional (f a) -> f (Optional a) Source # mapM :: Monad m => (a -> m b) -> Optional a -> m (Optional b) Source # sequence :: Monad m => Optional (m a) -> m (Optional a) Source #
Monoid a => Monoid (Optional a) Source # |
Instance details Defined in Data.Optional Methods mempty :: Optional a Source # mappend :: Optional a -> Optional a -> Optional a Source # mconcat :: [Optional a] -> Optional a Source #
Semigroup a => Semigroup (Optional a) Source # |
Instance details Defined in Data.Optional Methods (<>) :: Optional a -> Optional a -> Optional a Source # sconcat :: NonEmpty (Optional a) -> Optional a Source # stimes :: Integral b => b -> Optional a -> Optional a Source #
IsString a => IsString (Optional a) Source # |
Instance details Defined in Data.Optional Methods fromString :: String -> Optional a Source #
Num a => Num (Optional a) Source # |
Instance details Defined in Data.Optional Methods (+) :: Optional a -> Optional a -> Optional a Source # (-) :: Optional a -> Optional a -> Optional a Source # (*) :: Optional a -> Optional a -> Optional a Source # negate :: Optional a -> Optional a Source # abs :: Optional a -> Optional a Source # signum :: Optional a -> Optional a Source # fromInteger :: Integer -> Optional a Source #
Fractional a => Fractional (Optional a) Source # |
Instance details Defined in Data.Optional Methods (/) :: Optional a -> Optional a -> Optional a Source # recip :: Optional a -> Optional a Source # fromRational :: Rational -> Optional a Source #
Show a => Show (Optional a) Source # |
Instance details Defined in Data.Optional Methods showsPrec :: Int -> Optional a -> ShowS Source # show :: Optional a -> String Source # showList :: [Optional a] -> ShowS Source #
Eq a => Eq (Optional a) Source # |
Instance details Defined in Data.Optional Methods (==) :: Optional a -> Optional a -> Bool Source # (/=) :: Optional a -> Optional a -> Bool Source #

defaultTo :: a -> Optional a -> a Source #

The `defaultTo` function takes a default value and an `Optional` value. If the `Optional` is `Default`, it returns the default value; otherwise, it returns the value contained in the `Optional`.

fromOptional :: Alternative f => Optional a -> f a Source #

Convert an `Optional` value into an instance of `Alternative`.

optional :: b -> (a -> b) -> Optional a -> b Source #

The `optional` function takes a default value, a function, and an `Optional` value. If the `Optional` value is `Default`, the function returns the default value. Otherwise, it applies the function to the value inside the `Optional` and returns the result.

# Re-exports

empty :: Alternative f => f a Source #

The identity of `<|>`

    empty <|> a     == a
    a     <|> empty == a

pure :: Applicative f => a -> f a Source #

Lift a value into the Structure.

#### Examples

Expand

    >>> pure 1 :: Maybe Int
    Just 1

    >>> pure 'z' :: [Char]
    "z"

    >>> pure (pure ":D") :: Maybe [String]
    Just [":D"]