on package:loc

on b u x y runs the binary function b on the results of applying unary function u to two arguments x and y. From the opposite perspective, it transforms two inputs and combines the outputs.

((+) `on` f) x y = f x + f y

Typical usage: sortBy (compare `on` fst). Algebraic properties:

• (*) `on` id = (*) -- (if (*) ∉ {⊥, const
  ⊥})

• ((*) `on` f) `on` g = (*) `on` (f . g)

• flip on f . flip on g = flip on (g .
  f)

List of length 1 or 2

List of length 1

List of length 1

The union of two Areas Spans that overlap or abut will be merged in the result. This is an alias for +.

Combine two Spans, merging them if they abut or overlap This is an alias for +.

Arithmetic exceptions.

Any type that you wish to throw or catch as an exception must be an instance of the Exception class. The simplest case is a new exception type directly below the root:

data MyException = ThisException | ThatException
deriving Show

instance Exception MyException

The default method definitions in the Exception class do what we need in this case. You can now throw and catch ThisException and ThatException as exceptions:

*Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
Caught ThisException

In more complicated examples, you may wish to define a whole hierarchy of exceptions:

---------------------------------------------------------------------
-- Make the root exception type for all the exceptions in a compiler

data SomeCompilerException = forall e . Exception e => SomeCompilerException e

instance Show SomeCompilerException where
show (SomeCompilerException e) = show e

instance Exception SomeCompilerException

compilerExceptionToException :: Exception e => e -> SomeException
compilerExceptionToException = toException . SomeCompilerException

compilerExceptionFromException :: Exception e => SomeException -> Maybe e
compilerExceptionFromException x = do
SomeCompilerException a <- fromException x
cast a

---------------------------------------------------------------------
-- Make a subhierarchy for exceptions in the frontend of the compiler

data SomeFrontendException = forall e . Exception e => SomeFrontendException e

instance Show SomeFrontendException where
show (SomeFrontendException e) = show e

instance Exception SomeFrontendException where
toException = compilerExceptionToException
fromException = compilerExceptionFromException

frontendExceptionToException :: Exception e => e -> SomeException
frontendExceptionToException = toException . SomeFrontendException

frontendExceptionFromException :: Exception e => SomeException -> Maybe e
frontendExceptionFromException x = do
SomeFrontendException a <- fromException x
cast a

---------------------------------------------------------------------
-- Make an exception type for a particular frontend compiler exception

data MismatchedParentheses = MismatchedParentheses
deriving Show

instance Exception MismatchedParentheses where
toException   = frontendExceptionToException
fromException = frontendExceptionFromException

We can now catch a MismatchedParentheses exception as MismatchedParentheses, SomeFrontendException or SomeCompilerException, but not other types, e.g. IOException:

*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: IOException))
*** Exception: MismatchedParentheses

The Monad class defines the basic operations over a monad, a concept from a branch of mathematics known as category theory. From the perspective of a Haskell programmer, however, it is best to think of a monad as an abstract datatype of actions. Haskell's do expressions provide a convenient syntax for writing monadic expressions. Instances of Monad should satisfy the following:

• Left identity return a >>= k = k a
• Right identity m >>= return = m
• Associativity m >>= (\x -> k x >>= h) = (m >>= k) >>= h

Furthermore, the Monad and Applicative operations should relate as follows:

• pure = return

• m1 <*> m2 = m1 >>= (x1 -> m2
  >>= (x2 -> return (x1 x2)))

The above laws imply:

• fmap f xs = xs >>= return .
  f

• (>>) = (*>)

and that pure and (<*>) satisfy the applicative functor laws. The instances of Monad for lists, Maybe and IO defined in the Prelude satisfy these laws.

The class of monoids (types with an associative binary operation that has an identity). Instances should satisfy the following:

• Right identity x <> mempty = x
• Left identity mempty <> x = x
• Associativity x <> (y <> z) = (x <> y) <> z (Semigroup law)
• Concatenation mconcat = foldr (<>) mempty

The method names refer to the monoid of lists under concatenation, but there are many other instances. Some types can be viewed as a monoid in more than one way, e.g. both addition and multiplication on numbers. In such cases we often define newtypes and make those instances of Monoid, e.g. Sum and Product. NOTE: Semigroup is a superclass of Monoid since base-4.11.0.0.

Non-empty (and non-strict) list type.

const x is a unary function which evaluates to x for all inputs.

>>> const 42 "hello"
42

>>> map (const 42) [0..3]
[42,42,42,42]

Fold a list using the monoid. For most types, the default definition for mconcat will be used, but the function is included in the class definition so that an optimized version can be provided for specific types.

>>> mconcat ["Hello", " ", "Haskell", "!"]
"Hello Haskell!"

Reduce a non-empty list with <> The default definition should be sufficient, but this can be overridden for efficiency.

>>> import Data.List.NonEmpty (NonEmpty (..))

>>> sconcat $ "Hello" :| [" ", "Haskell", "!"]
"Hello Haskell!"

Map covariantly over the second argument.

second ≡ bimap id

Examples

>>> second (+1) ('j', 3)
('j',4)

>>> second (+1) (Right 3)
Right 4

the rational equivalent of its real argument with full precision