Module

Prelude

Re-exports from Control.Applicative

#Applicative 

class (Apply f) <= Applicative f  where

The Applicative type class extends the Apply type class with a pure function, which can be used to create values of type f a from values of type a.

Where Apply provides the ability to lift functions of two or more arguments to functions whose arguments are wrapped using f, and Functor provides the ability to lift functions of one argument, pure can be seen as the function which lifts functions of zero arguments. That is, Applicative functors support a lifting operation for any number of function arguments.

Instances must satisfy the following laws in addition to the Apply laws:

  • Identity: (pure identity) <*> v = v
  • Composition: pure (<<<) <*> f <*> g <*> h = f <*> (g <*> h)
  • Homomorphism: (pure f) <*> (pure x) = pure (f x)
  • Interchange: u <*> (pure y) = (pure (_ $ y)) <*> u

Members

  • pure :: forall a. a -> f a

Instances

#when 

when :: forall m. Applicative m => Boolean -> m Unit -> m Unit

Perform an applicative action when a condition is true.

#unless 

unless :: forall m. Applicative m => Boolean -> m Unit -> m Unit

Perform an applicative action unless a condition is true.

#liftA1 

liftA1 :: forall f a b. Applicative f => (a -> b) -> f a -> f b

liftA1 provides a default implementation of (<$>) for any Applicative functor, without using (<$>) as provided by the Functor-Applicative superclass relationship.

liftA1 can therefore be used to write Functor instances as follows:

instance functorF :: Functor F where
  map = liftA1

Re-exports from Control.Apply

#Apply 

class (Functor f) <= Apply f  where

The Apply class provides the (<*>) which is used to apply a function to an argument under a type constructor.

Apply can be used to lift functions of two or more arguments to work on values wrapped with the type constructor f. It might also be understood in terms of the lift2 function:

lift2 :: forall f a b c. Apply f => (a -> b -> c) -> f a -> f b -> f c
lift2 f a b = f <$> a <*> b

(<*>) is recovered from lift2 as lift2 ($). That is, (<*>) lifts the function application operator ($) to arguments wrapped with the type constructor f.

Put differently...

foo =
  functionTakingNArguments <$> computationProducingArg1
                           <*> computationProducingArg2
                           <*> ...
                           <*> computationProducingArgN

Instances must satisfy the following law in addition to the Functor laws:

  • Associative composition: (<<<) <$> f <*> g <*> h = f <*> (g <*> h)

Formally, Apply represents a strong lax semi-monoidal endofunctor.

Members

  • apply :: forall a b. f (a -> b) -> f a -> f b

Instances

#(<*>)

Operator alias for Control.Apply.apply (left-associative / precedence 4)

#(<*)

Operator alias for Control.Apply.applyFirst (left-associative / precedence 4)

#(*>)

Operator alias for Control.Apply.applySecond (left-associative / precedence 4)

Re-exports from Control.Bind

#Bind 

class (Apply m) <= Bind m  where

The Bind type class extends the Apply type class with a "bind" operation (>>=) which composes computations in sequence, using the return value of one computation to determine the next computation.

The >>= operator can also be expressed using do notation, as follows:

x >>= f = do y <- x
             f y

where the function argument of f is given the name y.

Instances must satisfy the following laws in addition to the Apply laws:

  • Associativity: (x >>= f) >>= g = x >>= (\k -> f k >>= g)
  • Apply Superclass: apply f x = f >>= \f’ -> map f’ x

Associativity tells us that we can regroup operations which use do notation so that we can unambiguously write, for example:

do x <- m1
   y <- m2 x
   m3 x y

Members

  • bind :: forall a b. m a -> (a -> m b) -> m b

Instances

  • Bind (Function r)
  • Bind Array

    The bind/>>= function for Array works by applying a function to each element in the array, and flattening the results into a single, new array.

    Array's bind/>>= works like a nested for loop. Each bind adds another level of nesting in the loop. For example:

    foo :: Array String
foo =
  ["a", "b"] >>= \eachElementInArray1 ->
    ["c", "d"] >>= \eachElementInArray2
      pure (eachElementInArray1 <> eachElementInArray2)

-- In other words...
foo
-- ... is the same as...
[ ("a" <> "c"), ("a" <> "d"), ("b" <> "c"), ("b" <> "d") ]
-- which simplifies to...
[ "ac", "ad", "bc", "bd" ]
  • Bind Proxy

#Discard 

class Discard a  where

A class for types whose values can safely be discarded in a do notation block.

An example is the Unit type, since there is only one possible value which can be returned.

Members

  • discard :: forall f b. Bind f => f a -> (a -> f b) -> f b

Instances

#join 

join :: forall a m. Bind m => m (m a) -> m a

Collapse two applications of a monadic type constructor into one.

#ifM 

ifM :: forall a m. Bind m => m Boolean -> m a -> m a -> m a

Execute a monadic action if a condition holds.

For example:

main = ifM ((< 0.5) <$> random)
         (trace "Heads")
         (trace "Tails")

#(>>=)

Operator alias for Control.Bind.bind (left-associative / precedence 1)

#(>=>)

Operator alias for Control.Bind.composeKleisli (right-associative / precedence 1)

#(=<<)

Operator alias for Control.Bind.bindFlipped (right-associative / precedence 1)

#(<=<)

Operator alias for Control.Bind.composeKleisliFlipped (right-associative / precedence 1)

Re-exports from Control.Category

#Category 

class (Semigroupoid a) <= Category a  where

Members

Instances

Re-exports from Control.Monad

#Monad 

class (Applicative m, Bind m) <= Monad m

The Monad type class combines the operations of the Bind and Applicative type classes. Therefore, Monad instances represent type constructors which support sequential composition, and also lifting of functions of arbitrary arity.

Instances must satisfy the following laws in addition to the Applicative and Bind laws:

  • Left Identity: pure x >>= f = f x
  • Right Identity: x >>= pure = x

Instances

#whenM 

whenM :: forall m. Monad m => m Boolean -> m Unit -> m Unit

Perform a monadic action when a condition is true, where the conditional value is also in a monadic context.

#unlessM 

unlessM :: forall m. Monad m => m Boolean -> m Unit -> m Unit

Perform a monadic action unless a condition is true, where the conditional value is also in a monadic context.

#liftM1 

liftM1 :: forall m a b. Monad m => (a -> b) -> m a -> m b

liftM1 provides a default implementation of (<$>) for any Monad, without using (<$>) as provided by the Functor-Monad superclass relationship.

liftM1 can therefore be used to write Functor instances as follows:

instance functorF :: Functor F where
  map = liftM1

#ap 

ap :: forall m a b. Monad m => m (a -> b) -> m a -> m b

ap provides a default implementation of (<*>) for any Monad, without using (<*>) as provided by the Apply-Monad superclass relationship.

ap can therefore be used to write Apply instances as follows:

instance applyF :: Apply F where
  apply = ap

Re-exports from Control.Semigroupoid

#Semigroupoid 

class Semigroupoid a  where

Members

  • compose :: forall b c d. a c d -> a b c -> a b d

Instances

#(>>>)

Operator alias for Control.Semigroupoid.composeFlipped (right-associative / precedence 9)

#(<<<)

Operator alias for Control.Semigroupoid.compose (right-associative / precedence 9)

Re-exports from Data.Boolean

#otherwise 

otherwise :: Boolean

An alias for true, which can be useful in guard clauses:

max x y | x >= y    = x
        | otherwise = y

Re-exports from Data.BooleanAlgebra

#BooleanAlgebra 

class (HeytingAlgebra a) <= BooleanAlgebra a

The BooleanAlgebra type class represents types that behave like boolean values.

Instances should satisfy the following laws in addition to the HeytingAlgebra law:

  • Excluded middle:
    • a || not a = tt

Instances

Re-exports from Data.Bounded

#Bounded 

class (Ord a) <= Bounded a  where

The Bounded type class represents totally ordered types that have an upper and lower boundary.

Instances should satisfy the following law in addition to the Ord laws:

  • Bounded: bottom <= a <= top

Members

Instances

Re-exports from Data.CommutativeRing

#CommutativeRing 

class (Ring a) <= CommutativeRing a

The CommutativeRing class is for rings where multiplication is commutative.

Instances must satisfy the following law in addition to the Ring laws:

  • Commutative multiplication: a * b = b * a

Instances

Re-exports from Data.DivisionRing

#DivisionRing 

class (Ring a) <= DivisionRing a  where

The DivisionRing class is for non-zero rings in which every non-zero element has a multiplicative inverse. Division rings are sometimes also called skew fields.

Instances must satisfy the following laws in addition to the Ring laws:

  • Non-zero ring: one /= zero
  • Non-zero multiplicative inverse: recip a * a = a * recip a = one for all non-zero a

The result of recip zero is left undefined; individual instances may choose how to handle this case.

If a type has both DivisionRing and CommutativeRing instances, then it is a field and should have a Field instance.

Members

Instances

Re-exports from Data.Eq

#Eq 

class Eq a  where

The Eq type class represents types which support decidable equality.

Eq instances should satisfy the following laws:

  • Reflexivity: x == x = true
  • Symmetry: x == y = y == x
  • Transitivity: if x == y and y == z then x == z

Note: The Number type is not an entirely law abiding member of this class due to the presence of NaN, since NaN /= NaN. Additionally, computing with Number can result in a loss of precision, so sometimes values that should be equivalent are not.

Members

Instances

#notEq 

notEq :: forall a. Eq a => a -> a -> Boolean

notEq tests whether one value is not equal to another. Shorthand for not (eq x y).

#(==)

Operator alias for Data.Eq.eq (non-associative / precedence 4)

#(/=)

Operator alias for Data.Eq.notEq (non-associative / precedence 4)

Re-exports from Data.EuclideanRing

#EuclideanRing 

class (CommutativeRing a) <= EuclideanRing a  where

The EuclideanRing class is for commutative rings that support division. The mathematical structure this class is based on is sometimes also called a Euclidean domain.

Instances must satisfy the following laws in addition to the Ring laws:

  • Integral domain: one /= zero, and if a and b are both nonzero then so is their product a * b
  • Euclidean function degree:
    • Nonnegativity: For all nonzero a, degree a >= 0
    • Quotient/remainder: For all a and b, where b is nonzero, let q = a / b and r = a `mod` b; then a = q*b + r, and also either r = zero or degree r < degree b
  • Submultiplicative euclidean function:
    • For all nonzero a and b, degree a <= degree (a * b)

The behaviour of division by zero is unconstrained by these laws, meaning that individual instances are free to choose how to behave in this case. Similarly, there are no restrictions on what the result of degree zero is; it doesn't make sense to ask for degree zero in the same way that it doesn't make sense to divide by zero, so again, individual instances may choose how to handle this case.

For any EuclideanRing which is also a Field, one valid choice for degree is simply const 1. In fact, unless there's a specific reason not to, Field types should normally use this definition of degree.

The EuclideanRing Int instance is one of the most commonly used EuclideanRing instances and deserves a little more discussion. In particular, there are a few different sensible law-abiding implementations to choose from, with slightly different behaviour in the presence of negative dividends or divisors. The most common definitions are "truncating" division, where the result of a / b is rounded towards 0, and "Knuthian" or "flooring" division, where the result of a / b is rounded towards negative infinity. A slightly less common, but arguably more useful, option is "Euclidean" division, which is defined so as to ensure that a `mod` b is always nonnegative. With Euclidean division, a / b rounds towards negative infinity if the divisor is positive, and towards positive infinity if the divisor is negative. Note that all three definitions are identical if we restrict our attention to nonnegative dividends and divisors.

In versions 1.x, 2.x, and 3.x of the Prelude, the EuclideanRing Int instance used truncating division. As of 4.x, the EuclideanRing Int instance uses Euclidean division. Additional functions quot and rem are supplied if truncating division is desired.

Members

Instances

#lcm 

lcm :: forall a. Eq a => EuclideanRing a => a -> a -> a

The least common multiple of two values.

#gcd 

gcd :: forall a. Eq a => EuclideanRing a => a -> a -> a

The greatest common divisor of two values.

#(/)

Operator alias for Data.EuclideanRing.div (left-associative / precedence 7)

Re-exports from Data.Field

#Field 

class (EuclideanRing a, DivisionRing a) <= Field a

The Field class is for types that are (commutative) fields.

Mathematically, a field is a ring which is commutative and in which every nonzero element has a multiplicative inverse; these conditions correspond to the CommutativeRing and DivisionRing classes in PureScript respectively. However, the Field class has EuclideanRing and DivisionRing as superclasses, which seems like a stronger requirement (since CommutativeRing is a superclass of EuclideanRing). In fact, it is not stronger, since any type which has law-abiding CommutativeRing and DivisionRing instances permits exactly one law-abiding EuclideanRing instance. We use a EuclideanRing superclass here in order to ensure that a Field constraint on a function permits you to use div on that type, since div is a member of EuclideanRing.

This class has no laws or members of its own; it exists as a convenience, so a single constraint can be used when field-like behaviour is expected.

This module also defines a single Field instance for any type which has both EuclideanRing and DivisionRing instances. Any other instance would overlap with this instance, so no other Field instances should be defined in libraries. Instead, simply define EuclideanRing and DivisionRing instances, and this will permit your type to be used with a Field constraint.

Instances

Re-exports from Data.Function

#flip 

flip :: forall a b c. (a -> b -> c) -> b -> a -> c

Flips the order of the arguments to a function of two arguments.

flip const 1 2 = const 2 1 = 2

#const 

const :: forall a b. a -> b -> a

Returns its first argument and ignores its second.

const 1 "hello" = 1

It can also be thought of as creating a function that ignores its argument:

const 1 = \_ -> 1

#($)

Operator alias for Data.Function.apply (right-associative / precedence 0)

Applies a function to an argument: the reverse of (#).

length $ groupBy productCategory $ filter isInStock $ products

is equivalent to:

length (groupBy productCategory (filter isInStock products))

Or another alternative equivalent, applying chain of composed functions to a value:

length <<< groupBy productCategory <<< filter isInStock $ products

#(#)

Operator alias for Data.Function.applyFlipped (left-associative / precedence 1)

Applies an argument to a function: the reverse of ($).

products # filter isInStock # groupBy productCategory # length

is equivalent to:

length (groupBy productCategory (filter isInStock products))

Or another alternative equivalent, applying a value to a chain of composed functions:

products # filter isInStock >>> groupBy productCategory >>> length

Re-exports from Data.Functor

#Functor 

class Functor f  where

A Functor is a type constructor which supports a mapping operation map.

map can be used to turn functions a -> b into functions f a -> f b whose argument and return types use the type constructor f to represent some computational context.

Instances must satisfy the following laws:

  • Identity: map identity = identity
  • Composition: map (f <<< g) = map f <<< map g

Members

  • map :: forall a b. (a -> b) -> f a -> f b

Instances

#void 

void :: forall f a. Functor f => f a -> f Unit

The void function is used to ignore the type wrapped by a Functor, replacing it with Unit and keeping only the type information provided by the type constructor itself.

void is often useful when using do notation to change the return type of a monadic computation:

main = forE 1 10 \n -> void do
  print n
  print (n * n)

#flap 

flap :: forall f a b. Functor f => f (a -> b) -> a -> f b

Apply a value in a computational context to a value in no context.

Generalizes flip.

longEnough :: String -> Bool
hasSymbol :: String -> Bool
hasDigit :: String -> Bool
password :: String

validate :: String -> Array Bool
validate = flap [longEnough, hasSymbol, hasDigit]

flap (-) 3 4 == 1
threeve <$> Just 1 <@> 'a' <*> Just true == Just (threeve 1 'a' true)

#(<@>)

Operator alias for Data.Functor.flap (left-associative / precedence 4)

#(<$>)

Operator alias for Data.Functor.map (left-associative / precedence 4)

#(<$)

Operator alias for Data.Functor.voidRight (left-associative / precedence 4)

#(<#>)

Operator alias for Data.Functor.mapFlipped (left-associative / precedence 1)

#($>)

Operator alias for Data.Functor.voidLeft (left-associative / precedence 4)

Re-exports from Data.HeytingAlgebra

#HeytingAlgebra 

class HeytingAlgebra a  where

The HeytingAlgebra type class represents types that are bounded lattices with an implication operator such that the following laws hold:

  • Associativity:
    • a || (b || c) = (a || b) || c
    • a && (b && c) = (a && b) && c
  • Commutativity:
    • a || b = b || a
    • a && b = b && a
  • Absorption:
    • a || (a && b) = a
    • a && (a || b) = a
  • Idempotent:
    • a || a = a
    • a && a = a
  • Identity:
    • a || ff = a
    • a && tt = a
  • Implication:
    • a `implies` a = tt
    • a && (a `implies` b) = a && b
    • b && (a `implies` b) = b
    • a `implies` (b && c) = (a `implies` b) && (a `implies` c)
  • Complemented:
    • not a = a `implies` ff

Members

Instances

#(||)

Operator alias for Data.HeytingAlgebra.disj (right-associative / precedence 2)

#(&&)

Operator alias for Data.HeytingAlgebra.conj (right-associative / precedence 3)

Re-exports from Data.Monoid

#Monoid 

class (Semigroup m) <= Monoid m  where

A Monoid is a Semigroup with a value mempty, which is both a left and right unit for the associative operation <>:

  • Left unit: (mempty <> x) = x
  • Right unit: (x <> mempty) = x

Monoids are commonly used as the result of fold operations, where <> is used to combine individual results, and mempty gives the result of folding an empty collection of elements.

Newtypes for Monoid

Some types (e.g. Int, Boolean) can implement multiple law-abiding instances for Monoid. Let's use Int as an example

  1. <> could be + and mempty could be 0
  2. <> could be * and mempty could be 1.

To clarify these ambiguous situations, one should use the newtypes defined in Data.Monoid.<NewtypeName> modules.

In the above ambiguous situation, we could use Additive for the first situation or Multiplicative for the second one.

Members

Instances

Re-exports from Data.NaturalTransformation

#type (~>)

Operator alias for Data.NaturalTransformation.NaturalTransformation (right-associative / precedence 4)

Re-exports from Data.Ord

#Ord 

class (Eq a) <= Ord a  where

The Ord type class represents types which support comparisons with a total order.

Ord instances should satisfy the laws of total orderings:

  • Reflexivity: a <= a
  • Antisymmetry: if a <= b and b <= a then a = b
  • Transitivity: if a <= b and b <= c then a <= c

Members

Instances

#min 

min :: forall a. Ord a => a -> a -> a

Take the minimum of two values. If they are considered equal, the first argument is chosen.

#max 

max :: forall a. Ord a => a -> a -> a

Take the maximum of two values. If they are considered equal, the first argument is chosen.

#comparing 

comparing :: forall a b. Ord b => (a -> b) -> (a -> a -> Ordering)

Compares two values by mapping them to a type with an Ord instance.

#clamp 

clamp :: forall a. Ord a => a -> a -> a -> a

Clamp a value between a minimum and a maximum. For example:

let f = clamp 0 10
f (-5) == 0
f 5    == 5
f 15   == 10

#between 

between :: forall a. Ord a => a -> a -> a -> Boolean

Test whether a value is between a minimum and a maximum (inclusive). For example:

let f = between 0 10
f 0    == true
f (-5) == false
f 5    == true
f 10   == true
f 15   == false

#(>=)

Operator alias for Data.Ord.greaterThanOrEq (left-associative / precedence 4)

#(>)

Operator alias for Data.Ord.greaterThan (left-associative / precedence 4)

#(<=)

Operator alias for Data.Ord.lessThanOrEq (left-associative / precedence 4)

#(<)

Operator alias for Data.Ord.lessThan (left-associative / precedence 4)

Re-exports from Data.Ordering

#Ordering 

data Ordering

The Ordering data type represents the three possible outcomes of comparing two values:

LT - The first value is less than the second. GT - The first value is greater than the second. EQ - The first value is equal to the second.

Constructors

Instances

Re-exports from Data.Ring

#Ring 

class (Semiring a) <= Ring a  where

The Ring class is for types that support addition, multiplication, and subtraction operations.

Instances must satisfy the following laws in addition to the Semiring laws:

  • Additive inverse: a - a = zero
  • Compatibility of sub and negate: a - b = a + (zero - b)

Members

  • sub :: a -> a -> a

Instances

#negate 

negate :: forall a. Ring a => a -> a

negate x can be used as a shorthand for zero - x.

#(-)

Operator alias for Data.Ring.sub (left-associative / precedence 6)

Re-exports from Data.Semigroup

#Semigroup 

class Semigroup a  where

The Semigroup type class identifies an associative operation on a type.

Instances are required to satisfy the following law:

  • Associativity: (x <> y) <> z = x <> (y <> z)

One example of a Semigroup is String, with (<>) defined as string concatenation. Another example is List a, with (<>) defined as list concatenation.

Newtypes for Semigroup

There are two other ways to implement an instance for this type class regardless of which type is used. These instances can be used by wrapping the values in one of the two newtypes below:

  1. First - Use the first argument every time: append first _ = first.
  2. Last - Use the last argument every time: append _ last = last.

Members

Instances

#(<>)

Operator alias for Data.Semigroup.append (right-associative / precedence 5)

Re-exports from Data.Semiring

#Semiring 

class Semiring a  where

The Semiring class is for types that support an addition and multiplication operation.

Instances must satisfy the following laws:

  • Commutative monoid under addition:
    • Associativity: (a + b) + c = a + (b + c)
    • Identity: zero + a = a + zero = a
    • Commutative: a + b = b + a
  • Monoid under multiplication:
    • Associativity: (a * b) * c = a * (b * c)
    • Identity: one * a = a * one = a
  • Multiplication distributes over addition:
    • Left distributivity: a * (b + c) = (a * b) + (a * c)
    • Right distributivity: (a + b) * c = (a * c) + (b * c)
  • Annihilation: zero * a = a * zero = zero

Note: The Number and Int types are not fully law abiding members of this class hierarchy due to the potential for arithmetic overflows, and in the case of Number, the presence of NaN and Infinity values. The behaviour is unspecified in these cases.

Members

Instances

#(+)

Operator alias for Data.Semiring.add (left-associative / precedence 6)

#(*)

Operator alias for Data.Semiring.mul (left-associative / precedence 7)

Re-exports from Data.Show

#Show 

class Show a  where

The Show type class represents those types which can be converted into a human-readable String representation.

While not required, it is recommended that for any expression x, the string show x be executable PureScript code which evaluates to the same value as the expression x.

Members

Instances

Re-exports from Data.Unit

#Unit 

data Unit :: Type

The Unit type has a single inhabitant, called unit. It represents values with no computational content.

Unit is often used, wrapped in a monadic type constructor, as the return type of a computation where only the effects are important.

When returning a value of type Unit from an FFI function, it is recommended to use undefined, or not return a value at all.

Instances

#unit 

unit :: Unit

unit is the sole inhabitant of the Unit type.

Re-exports from Data.Void

#Void 

newtype Void

An uninhabited data type. In other words, one can never create a runtime value of type Void becaue no such value exists.

Void is useful to eliminate the possibility of a value being created. For example, a value of type Either Void Boolean can never have a Left value created in PureScript.

This should not be confused with the keyword void that commonly appears in C-family languages, such as Java:

public class Foo {
  void doSomething() { System.out.println("hello world!"); }
}

In PureScript, one often uses Unit to achieve similar effects as the void of C-family languages above.

Instances

#absurd 

absurd :: forall a. Void -> a

Eliminator for the Void type. Useful for stating that some code branch is impossible because you've "acquired" a value of type Void (which you can't).

rightOnly :: forall t . Either Void t -> t
rightOnly (Left v) = absurd v
rightOnly (Right t) = t

Modules