-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Please see https://github.com/freckle/stackctl#readme
@package stackctl
@version 1.5.0.1
module Stackctl.Colors
module Stackctl.Prelude
-- | Append two lists, i.e.,
--
--
-- [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
-- [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
--
--
-- If the first list is not finite, the result is the first list.
(++) :: [a] -> [a] -> [a]
infixr 5 ++
-- | The value of seq a b is bottom if a is bottom, and
-- otherwise equal to b. In other words, it evaluates the first
-- argument a to weak head normal form (WHNF). seq is
-- usually introduced to improve performance by avoiding unneeded
-- laziness.
--
-- A note on evaluation order: the expression seq a b does
-- not guarantee that a will be evaluated before
-- b. The only guarantee given by seq is that the both
-- a and b will be evaluated before seq
-- returns a value. In particular, this means that b may be
-- evaluated before a. If you need to guarantee a specific order
-- of evaluation, you must use the function pseq from the
-- "parallel" package.
seq :: forall {r :: RuntimeRep} a (b :: TYPE r). a -> b -> b
infixr 0 `seq`
-- | <math>. filter, applied to a predicate and a list,
-- returns the list of those elements that satisfy the predicate; i.e.,
--
--
-- filter p xs = [ x | x <- xs, p x]
--
--
--
-- >>> filter odd [1, 2, 3]
-- [1,3]
--
filter :: (a -> Bool) -> [a] -> [a]
-- | <math>. zip takes two lists and returns a list of
-- corresponding pairs.
--
--
-- >>> zip [1, 2] ['a', 'b']
-- [(1,'a'),(2,'b')]
--
--
-- If one input list is shorter than the other, excess elements of the
-- longer list are discarded, even if one of the lists is infinite:
--
--
-- >>> zip [1] ['a', 'b']
-- [(1,'a')]
--
-- >>> zip [1, 2] ['a']
-- [(1,'a')]
--
-- >>> zip [] [1..]
-- []
--
-- >>> zip [1..] []
-- []
--
--
-- zip is right-lazy:
--
--
-- >>> zip [] undefined
-- []
--
-- >>> zip undefined []
-- *** Exception: Prelude.undefined
-- ...
--
--
-- zip is capable of list fusion, but it is restricted to its
-- first list argument and its resulting list.
zip :: [a] -> [b] -> [(a, b)]
-- | Extract the first component of a pair.
fst :: (a, b) -> a
-- | Extract the second component of a pair.
snd :: (a, b) -> b
-- | otherwise is defined as the value True. It helps to make
-- guards more readable. eg.
--
--
-- f x | x < 0 = ...
-- | otherwise = ...
--
otherwise :: Bool
-- | If the first argument evaluates to True, then the result is the
-- second argument. Otherwise an AssertionFailed exception is
-- raised, containing a String with the source file and line
-- number of the call to assert.
--
-- Assertions can normally be turned on or off with a compiler flag (for
-- GHC, assertions are normally on unless optimisation is turned on with
-- -O or the -fignore-asserts option is given). When
-- assertions are turned off, the first argument to assert is
-- ignored, and the second argument is returned as the result.
assert :: Bool -> a -> a
-- | <math>. map f xs is the list obtained by
-- applying f to each element of xs, i.e.,
--
--
-- map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
-- map f [x1, x2, ...] == [f x1, f x2, ...]
--
--
--
-- >>> map (+1) [1, 2, 3]
-- [2,3,4]
--
map :: (a -> b) -> [a] -> [b]
-- | Application operator. This operator is redundant, since ordinary
-- application (f x) means the same as (f $ x).
-- However, $ has low, right-associative binding precedence, so it
-- sometimes allows parentheses to be omitted; for example:
--
--
-- f $ g $ h x = f (g (h x))
--
--
-- It is also useful in higher-order situations, such as map
-- ($ 0) xs, or zipWith ($) fs xs.
--
-- Note that ($) is levity-polymorphic in its result
-- type, so that foo $ True where foo :: Bool ->
-- Int# is well-typed.
($) :: forall (r :: RuntimeRep) a (b :: TYPE r). (a -> b) -> a -> b
infixr 0 $
-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b
-- | general coercion to fractional types
realToFrac :: (Real a, Fractional b) => a -> b
-- | Conditional failure of Alternative computations. Defined by
--
--
-- guard True = pure ()
-- guard False = empty
--
--
-- Examples
--
-- Common uses of guard include conditionally signaling an error
-- in an error monad and conditionally rejecting the current choice in an
-- Alternative-based parser.
--
-- As an example of signaling an error in the error monad Maybe,
-- consider a safe division function safeDiv x y that returns
-- Nothing when the denominator y is zero and
-- Just (x `div` y) otherwise. For example:
--
--
-- >>> safeDiv 4 0
-- Nothing
--
--
--
-- >>> safeDiv 4 2
-- Just 2
--
--
-- A definition of safeDiv using guards, but not guard:
--
--
-- safeDiv :: Int -> Int -> Maybe Int
-- safeDiv x y | y /= 0 = Just (x `div` y)
-- | otherwise = Nothing
--
--
-- A definition of safeDiv using guard and Monad
-- do-notation:
--
--
-- safeDiv :: Int -> Int -> Maybe Int
-- safeDiv x y = do
-- guard (y /= 0)
-- return (x `div` y)
--
guard :: Alternative f => Bool -> f ()
-- | The join function is the conventional monad join operator. It
-- is used to remove one level of monadic structure, projecting its bound
-- argument into the outer level.
--
-- 'join bss' can be understood as the do
-- expression
--
--
-- do bs <- bss
-- bs
--
--
-- Examples
--
-- A common use of join is to run an IO computation
-- returned from an STM transaction, since STM transactions
-- can't perform IO directly. Recall that
--
--
-- atomically :: STM a -> IO a
--
--
-- is used to run STM transactions atomically. So, by specializing
-- the types of atomically and join to
--
--
-- atomically :: STM (IO b) -> IO (IO b)
-- join :: IO (IO b) -> IO b
--
--
-- we can compose them as
--
--
-- join . atomically :: STM (IO b) -> IO b
--
--
-- to run an STM transaction and the IO action it returns.
join :: Monad m => m (m a) -> m a
-- | The Bounded class is used to name the upper and lower limits of
-- a type. Ord is not a superclass of Bounded since types
-- that are not totally ordered may also have upper and lower bounds.
--
-- The Bounded class may be derived for any enumeration type;
-- minBound is the first constructor listed in the data
-- declaration and maxBound is the last. Bounded may also
-- be derived for single-constructor datatypes whose constituent types
-- are in Bounded.
class Bounded a
minBound :: Bounded a => a
maxBound :: Bounded a => a
-- | Class Enum defines operations on sequentially ordered types.
--
-- The enumFrom... methods are used in Haskell's translation of
-- arithmetic sequences.
--
-- Instances of Enum may be derived for any enumeration type
-- (types whose constructors have no fields). The nullary constructors
-- are assumed to be numbered left-to-right by fromEnum from
-- 0 through n-1. See Chapter 10 of the Haskell
-- Report for more details.
--
-- For any type that is an instance of class Bounded as well as
-- Enum, the following should hold:
--
--
--
--
-- enumFrom x = enumFromTo x maxBound
-- enumFromThen x y = enumFromThenTo x y bound
-- where
-- bound | fromEnum y >= fromEnum x = maxBound
-- | otherwise = minBound
--
class Enum a
-- | Convert to an Int. It is implementation-dependent what
-- fromEnum returns when applied to a value that is too large to
-- fit in an Int.
fromEnum :: Enum a => a -> Int
-- | The Eq class defines equality (==) and inequality
-- (/=). All the basic datatypes exported by the Prelude
-- are instances of Eq, and Eq may be derived for any
-- datatype whose constituents are also instances of Eq.
--
-- The Haskell Report defines no laws for Eq. However, instances
-- are encouraged to follow these properties:
--
--
-- - Reflexivity x == x = True
-- - Symmetry x == y = y == x
-- - Transitivity if x == y && y == z =
-- True, then x == z = True
-- - Extensionality if x == y = True and
-- f is a function whose return type is an instance of
-- Eq, then f x == f y = True
-- - Negation x /= y = not (x ==
-- y)
--
--
-- Minimal complete definition: either == or /=.
class Eq a
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool
infix 4 ==
infix 4 /=
-- | Trigonometric and hyperbolic functions and related functions.
--
-- The Haskell Report defines no laws for Floating. However,
-- (+), (*) and exp are
-- customarily expected to define an exponential field and have the
-- following properties:
--
--
-- - exp (a + b) = exp a * exp b
-- - exp (fromInteger 0) = fromInteger 1
--
class Fractional a => Floating a
pi :: Floating a => a
exp :: Floating a => a -> a
log :: Floating a => a -> a
sqrt :: Floating a => a -> a
(**) :: Floating a => a -> a -> a
logBase :: Floating a => a -> a -> a
sin :: Floating a => a -> a
cos :: Floating a => a -> a
tan :: Floating a => a -> a
asin :: Floating a => a -> a
acos :: Floating a => a -> a
atan :: Floating a => a -> a
sinh :: Floating a => a -> a
cosh :: Floating a => a -> a
tanh :: Floating a => a -> a
asinh :: Floating a => a -> a
acosh :: Floating a => a -> a
atanh :: Floating a => a -> a
infixr 8 **
-- | Fractional numbers, supporting real division.
--
-- The Haskell Report defines no laws for Fractional. However,
-- (+) and (*) are customarily expected
-- to define a division ring and have the following properties:
--
--
-- - recip gives the multiplicative inverse x
-- * recip x = recip x * x = fromInteger 1
--
--
-- Note that it isn't customarily expected that a type instance of
-- Fractional implement a field. However, all instances in
-- base do.
class Num a => Fractional a
-- | Fractional division.
(/) :: Fractional a => a -> a -> a
-- | Reciprocal fraction.
recip :: Fractional a => a -> a
-- | Conversion from a Rational (that is Ratio
-- Integer). A floating literal stands for an application of
-- fromRational to a value of type Rational, so such
-- literals have type (Fractional a) => a.
fromRational :: Fractional a => Rational -> a
infixl 7 /
-- | Integral numbers, supporting integer division.
--
-- The Haskell Report defines no laws for Integral. However,
-- Integral instances are customarily expected to define a
-- Euclidean domain and have the following properties for the
-- div/mod and quot/rem pairs, given suitable
-- Euclidean functions f and g:
--
--
-- - x = y * quot x y + rem x y with rem x y
-- = fromInteger 0 or g (rem x y) < g
-- y
-- - x = y * div x y + mod x y with mod x y
-- = fromInteger 0 or f (mod x y) < f
-- y
--
--
-- An example of a suitable Euclidean function, for Integer's
-- instance, is abs.
class (Real a, Enum a) => Integral a
-- | integer division truncated toward zero
quot :: Integral a => a -> a -> a
-- | integer remainder, satisfying
--
--
-- (x `quot` y)*y + (x `rem` y) == x
--
rem :: Integral a => a -> a -> a
-- | integer division truncated toward negative infinity
div :: Integral a => a -> a -> a
-- | integer modulus, satisfying
--
--
-- (x `div` y)*y + (x `mod` y) == x
--
mod :: Integral a => a -> a -> a
-- | simultaneous quot and rem
quotRem :: Integral a => a -> a -> (a, a)
-- | simultaneous div and mod
divMod :: Integral a => a -> a -> (a, a)
-- | conversion to Integer
toInteger :: Integral a => a -> Integer
infixl 7 `div`
infixl 7 `mod`
infixl 7 `quot`
infixl 7 `rem`
-- | 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:
--
--
--
-- Furthermore, the Monad and Applicative operations should
-- relate as follows:
--
--
--
-- The above laws imply:
--
--
--
-- 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.
class Applicative m => Monad (m :: Type -> Type)
-- | Sequentially compose two actions, passing any value produced by the
-- first as an argument to the second.
--
-- 'as >>= bs' can be understood as the do
-- expression
--
--
-- do a <- as
-- bs a
--
(>>=) :: Monad m => m a -> (a -> m b) -> m b
-- | Sequentially compose two actions, discarding any value produced by the
-- first, like sequencing operators (such as the semicolon) in imperative
-- languages.
--
-- 'as >> bs' can be understood as the do
-- expression
--
--
-- do as
-- bs
--
(>>) :: Monad m => m a -> m b -> m b
-- | Inject a value into the monadic type.
return :: Monad m => a -> m a
infixl 1 >>=
infixl 1 >>
-- | The Data class comprehends a fundamental primitive
-- gfoldl for folding over constructor applications, say terms.
-- This primitive can be instantiated in several ways to map over the
-- immediate subterms of a term; see the gmap combinators later
-- in this class. Indeed, a generic programmer does not necessarily need
-- to use the ingenious gfoldl primitive but rather the intuitive
-- gmap combinators. The gfoldl primitive is completed by
-- means to query top-level constructors, to turn constructor
-- representations into proper terms, and to list all possible datatype
-- constructors. This completion allows us to serve generic programming
-- scenarios like read, show, equality, term generation.
--
-- The combinators gmapT, gmapQ, gmapM, etc are all
-- provided with default definitions in terms of gfoldl, leaving
-- open the opportunity to provide datatype-specific definitions. (The
-- inclusion of the gmap combinators as members of class
-- Data allows the programmer or the compiler to derive
-- specialised, and maybe more efficient code per datatype. Note:
-- gfoldl is more higher-order than the gmap combinators.
-- This is subject to ongoing benchmarking experiments. It might turn out
-- that the gmap combinators will be moved out of the class
-- Data.)
--
-- Conceptually, the definition of the gmap combinators in terms
-- of the primitive gfoldl requires the identification of the
-- gfoldl function arguments. Technically, we also need to
-- identify the type constructor c for the construction of the
-- result type from the folded term type.
--
-- In the definition of gmapQx combinators, we use
-- phantom type constructors for the c in the type of
-- gfoldl because the result type of a query does not involve the
-- (polymorphic) type of the term argument. In the definition of
-- gmapQl we simply use the plain constant type constructor
-- because gfoldl is left-associative anyway and so it is readily
-- suited to fold a left-associative binary operation over the immediate
-- subterms. In the definition of gmapQr, extra effort is needed. We use
-- a higher-order accumulation trick to mediate between left-associative
-- constructor application vs. right-associative binary operation (e.g.,
-- (:)). When the query is meant to compute a value of type
-- r, then the result type within generic folding is r ->
-- r. So the result of folding is a function to which we finally
-- pass the right unit.
--
-- With the -XDeriveDataTypeable option, GHC can generate
-- instances of the Data class automatically. For example, given
-- the declaration
--
--
-- data T a b = C1 a b | C2 deriving (Typeable, Data)
--
--
-- GHC will generate an instance that is equivalent to
--
--
-- instance (Data a, Data b) => Data (T a b) where
-- gfoldl k z (C1 a b) = z C1 `k` a `k` b
-- gfoldl k z C2 = z C2
--
-- gunfold k z c = case constrIndex c of
-- 1 -> k (k (z C1))
-- 2 -> z C2
--
-- toConstr (C1 _ _) = con_C1
-- toConstr C2 = con_C2
--
-- dataTypeOf _ = ty_T
--
-- con_C1 = mkConstr ty_T "C1" [] Prefix
-- con_C2 = mkConstr ty_T "C2" [] Prefix
-- ty_T = mkDataType "Module.T" [con_C1, con_C2]
--
--
-- This is suitable for datatypes that are exported transparently.
class Typeable a => Data a
-- | Left-associative fold operation for constructor applications.
--
-- The type of gfoldl is a headache, but operationally it is a
-- simple generalisation of a list fold.
--
-- The default definition for gfoldl is const
-- id, which is suitable for abstract datatypes with no
-- substructures.
gfoldl :: Data a => (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. () => g -> c g) -> a -> c a
-- | Unfolding constructor applications
gunfold :: Data a => (forall b r. Data b => c (b -> r) -> c r) -> (forall r. () => r -> c r) -> Constr -> c a
-- | Obtaining the constructor from a given datum. For proper terms, this
-- is meant to be the top-level constructor. Primitive datatypes are here
-- viewed as potentially infinite sets of values (i.e., constructors).
toConstr :: Data a => a -> Constr
-- | The outer type constructor of the type
dataTypeOf :: Data a => a -> DataType
-- | Mediate types and unary type constructors.
--
-- In Data instances of the form
--
--
-- instance (Data a, ...) => Data (T a)
--
--
-- dataCast1 should be defined as gcast1.
--
-- The default definition is const Nothing, which
-- is appropriate for instances of other forms.
dataCast1 :: (Data a, Typeable t) => (forall d. Data d => c (t d)) -> Maybe (c a)
-- | Mediate types and binary type constructors.
--
-- In Data instances of the form
--
--
-- instance (Data a, Data b, ...) => Data (T a b)
--
--
-- dataCast2 should be defined as gcast2.
--
-- The default definition is const Nothing, which
-- is appropriate for instances of other forms.
dataCast2 :: (Data a, Typeable t) => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c a)
-- | A generic transformation that maps over the immediate subterms
--
-- The default definition instantiates the type constructor c in
-- the type of gfoldl to an identity datatype constructor, using
-- the isomorphism pair as injection and projection.
gmapT :: Data a => (forall b. Data b => b -> b) -> a -> a
-- | A generic query with a left-associative binary operator
gmapQl :: Data a => (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> a -> r
-- | A generic query with a right-associative binary operator
gmapQr :: forall r r'. Data a => (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> a -> r
-- | A generic query that processes the immediate subterms and returns a
-- list of results. The list is given in the same order as originally
-- specified in the declaration of the data constructors.
gmapQ :: Data a => (forall d. Data d => d -> u) -> a -> [u]
-- | A generic query that processes one child by index (zero-based)
gmapQi :: Data a => Int -> (forall d. Data d => d -> u) -> a -> u
-- | A generic monadic transformation that maps over the immediate subterms
--
-- The default definition instantiates the type constructor c in
-- the type of gfoldl to the monad datatype constructor, defining
-- injection and projection using return and >>=.
gmapM :: (Data a, Monad m) => (forall d. Data d => d -> m d) -> a -> m a
-- | Transformation of at least one immediate subterm does not fail
gmapMp :: (Data a, MonadPlus m) => (forall d. Data d => d -> m d) -> a -> m a
-- | Transformation of one immediate subterm with success
gmapMo :: (Data a, MonadPlus m) => (forall d. Data d => d -> m d) -> a -> m a
-- | A type f is a Functor if it provides a function fmap
-- which, given any types a and b lets you apply any
-- function from (a -> b) to turn an f a into an
-- f b, preserving the structure of f. Furthermore
-- f needs to adhere to the following:
--
--
--
-- Note, that the second law follows from the free theorem of the type
-- fmap and the first law, so you need only check that the former
-- condition holds.
class Functor (f :: Type -> Type)
-- | fmap is used to apply a function of type (a -> b)
-- to a value of type f a, where f is a functor, to produce a
-- value of type f b. Note that for any type constructor with
-- more than one parameter (e.g., Either), only the last type
-- parameter can be modified with fmap (e.g., b in
-- `Either a b`).
--
-- Some type constructors with two parameters or more have a
-- Bifunctor instance that allows both the last and the
-- penultimate parameters to be mapped over.
--
-- Examples
--
-- Convert from a Maybe Int to a Maybe String
-- using show:
--
--
-- >>> fmap show Nothing
-- Nothing
--
-- >>> fmap show (Just 3)
-- Just "3"
--
--
-- Convert from an Either Int Int to an Either Int
-- String using show:
--
--
-- >>> fmap show (Left 17)
-- Left 17
--
-- >>> fmap show (Right 17)
-- Right "17"
--
--
-- Double each element of a list:
--
--
-- >>> fmap (*2) [1,2,3]
-- [2,4,6]
--
--
-- Apply even to the second element of a pair:
--
--
-- >>> fmap even (2,2)
-- (2,True)
--
--
-- It may seem surprising that the function is only applied to the last
-- element of the tuple compared to the list example above which applies
-- it to every element in the list. To understand, remember that tuples
-- are type constructors with multiple type parameters: a tuple of 3
-- elements (a,b,c) can also be written (,,) a b c and
-- its Functor instance is defined for Functor ((,,) a
-- b) (i.e., only the third parameter is free to be mapped over with
-- fmap).
--
-- It explains why fmap can be used with tuples containing
-- values of different types as in the following example:
--
--
-- >>> fmap even ("hello", 1.0, 4)
-- ("hello",1.0,True)
--
fmap :: Functor f => (a -> b) -> f a -> f b
-- | Replace all locations in the input with the same value. The default
-- definition is fmap . const, but this may be
-- overridden with a more efficient version.
(<$) :: Functor f => a -> f b -> f a
infixl 4 <$
-- | Basic numeric class.
--
-- The Haskell Report defines no laws for Num. However,
-- (+) and (*) are customarily expected
-- to define a ring and have the following properties:
--
--
-- - Associativity of (+) (x + y) +
-- z = x + (y + z)
-- - Commutativity of (+) x + y
-- = y + x
-- - fromInteger 0 is the additive
-- identity x + fromInteger 0 = x
-- - negate gives the additive inverse x +
-- negate x = fromInteger 0
-- - Associativity of (*) (x * y) *
-- z = x * (y * z)
-- - fromInteger 1 is the multiplicative
-- identity x * fromInteger 1 = x and
-- fromInteger 1 * x = x
-- - Distributivity of (*) with respect to
-- (+) a * (b + c) = (a * b) + (a *
-- c) and (b + c) * a = (b * a) + (c * a)
--
--
-- Note that it isn't customarily expected that a type instance of
-- both Num and Ord implement an ordered ring. Indeed, in
-- base only Integer and Rational do.
class Num a
(+) :: Num a => a -> a -> a
(-) :: Num a => a -> a -> a
(*) :: Num a => a -> a -> a
-- | Unary negation.
negate :: Num a => a -> a
-- | Absolute value.
abs :: Num a => a -> a
-- | Sign of a number. The functions abs and signum should
-- satisfy the law:
--
--
-- abs x * signum x == x
--
--
-- For real numbers, the signum is either -1 (negative),
-- 0 (zero) or 1 (positive).
signum :: Num a => a -> a
-- | Conversion from an Integer. An integer literal represents the
-- application of the function fromInteger to the appropriate
-- value of type Integer, so such literals have type
-- (Num a) => a.
fromInteger :: Num a => Integer -> a
infixl 7 *
infixl 6 +
infixl 6 -
-- | The Ord class is used for totally ordered datatypes.
--
-- Instances of Ord can be derived for any user-defined datatype
-- whose constituent types are in Ord. The declared order of the
-- constructors in the data declaration determines the ordering in
-- derived Ord instances. The Ordering datatype allows a
-- single comparison to determine the precise ordering of two objects.
--
-- Ord, as defined by the Haskell report, implements a total order
-- and has the following properties:
--
--
-- - Comparability x <= y || y <= x =
-- True
-- - Transitivity if x <= y && y <=
-- z = True, then x <= z = True
-- - Reflexivity x <= x = True
-- - Antisymmetry if x <= y && y <=
-- x = True, then x == y = True
--
--
-- The following operator interactions are expected to hold:
--
--
-- - x >= y = y <= x
-- - x < y = x <= y && x /= y
-- - x > y = y < x
-- - x < y = compare x y == LT
-- - x > y = compare x y == GT
-- - x == y = compare x y == EQ
-- - min x y == if x <= y then x else y = True
-- - max x y == if x >= y then x else y = True
--
--
-- Note that (7.) and (8.) do not require min and
-- max to return either of their arguments. The result is merely
-- required to equal one of the arguments in terms of (==).
--
-- Minimal complete definition: either compare or <=.
-- Using compare can be more efficient for complex types.
class Eq a => Ord a
compare :: Ord a => a -> a -> Ordering
(<) :: Ord a => a -> a -> Bool
(<=) :: Ord a => a -> a -> Bool
(>) :: Ord a => a -> a -> Bool
(>=) :: Ord a => a -> a -> Bool
max :: Ord a => a -> a -> a
min :: Ord a => a -> a -> a
infix 4 >
infix 4 <=
infix 4 <
infix 4 >=
-- | Parsing of Strings, producing values.
--
-- Derived instances of Read make the following assumptions, which
-- derived instances of Show obey:
--
--
-- - If the constructor is defined to be an infix operator, then the
-- derived Read instance will parse only infix applications of the
-- constructor (not the prefix form).
-- - Associativity is not used to reduce the occurrence of parentheses,
-- although precedence may be.
-- - If the constructor is defined using record syntax, the derived
-- Read will parse only the record-syntax form, and furthermore,
-- the fields must be given in the same order as the original
-- declaration.
-- - The derived Read instance allows arbitrary Haskell
-- whitespace between tokens of the input string. Extra parentheses are
-- also allowed.
--
--
-- For example, given the declarations
--
--
-- infixr 5 :^:
-- data Tree a = Leaf a | Tree a :^: Tree a
--
--
-- the derived instance of Read in Haskell 2010 is equivalent to
--
--
-- instance (Read a) => Read (Tree a) where
--
-- readsPrec d r = readParen (d > app_prec)
-- (\r -> [(Leaf m,t) |
-- ("Leaf",s) <- lex r,
-- (m,t) <- readsPrec (app_prec+1) s]) r
--
-- ++ readParen (d > up_prec)
-- (\r -> [(u:^:v,w) |
-- (u,s) <- readsPrec (up_prec+1) r,
-- (":^:",t) <- lex s,
-- (v,w) <- readsPrec (up_prec+1) t]) r
--
-- where app_prec = 10
-- up_prec = 5
--
--
-- Note that right-associativity of :^: is unused.
--
-- The derived instance in GHC is equivalent to
--
--
-- instance (Read a) => Read (Tree a) where
--
-- readPrec = parens $ (prec app_prec $ do
-- Ident "Leaf" <- lexP
-- m <- step readPrec
-- return (Leaf m))
--
-- +++ (prec up_prec $ do
-- u <- step readPrec
-- Symbol ":^:" <- lexP
-- v <- step readPrec
-- return (u :^: v))
--
-- where app_prec = 10
-- up_prec = 5
--
-- readListPrec = readListPrecDefault
--
--
-- Why do both readsPrec and readPrec exist, and why does
-- GHC opt to implement readPrec in derived Read instances
-- instead of readsPrec? The reason is that readsPrec is
-- based on the ReadS type, and although ReadS is mentioned
-- in the Haskell 2010 Report, it is not a very efficient parser data
-- structure.
--
-- readPrec, on the other hand, is based on a much more efficient
-- ReadPrec datatype (a.k.a "new-style parsers"), but its
-- definition relies on the use of the RankNTypes language
-- extension. Therefore, readPrec (and its cousin,
-- readListPrec) are marked as GHC-only. Nevertheless, it is
-- recommended to use readPrec instead of readsPrec
-- whenever possible for the efficiency improvements it brings.
--
-- As mentioned above, derived Read instances in GHC will
-- implement readPrec instead of readsPrec. The default
-- implementations of readsPrec (and its cousin, readList)
-- will simply use readPrec under the hood. If you are writing a
-- Read instance by hand, it is recommended to write it like so:
--
--
-- instance Read T where
-- readPrec = ...
-- readListPrec = readListPrecDefault
--
class Read a
class (Num a, Ord a) => Real a
-- | the rational equivalent of its real argument with full precision
toRational :: Real a => a -> Rational
-- | Efficient, machine-independent access to the components of a
-- floating-point number.
class (RealFrac a, Floating a) => RealFloat a
-- | a constant function, returning the radix of the representation (often
-- 2)
floatRadix :: RealFloat a => a -> Integer
-- | a constant function, returning the number of digits of
-- floatRadix in the significand
floatDigits :: RealFloat a => a -> Int
-- | a constant function, returning the lowest and highest values the
-- exponent may assume
floatRange :: RealFloat a => a -> (Int, Int)
-- | The function decodeFloat applied to a real floating-point
-- number returns the significand expressed as an Integer and an
-- appropriately scaled exponent (an Int). If
-- decodeFloat x yields (m,n), then x
-- is equal in value to m*b^^n, where b is the
-- floating-point radix, and furthermore, either m and
-- n are both zero or else b^(d-1) <= abs m <
-- b^d, where d is the value of floatDigits
-- x. In particular, decodeFloat 0 = (0,0). If the
-- type contains a negative zero, also decodeFloat (-0.0) =
-- (0,0). The result of decodeFloat x is
-- unspecified if either of isNaN x or
-- isInfinite x is True.
decodeFloat :: RealFloat a => a -> (Integer, Int)
-- | encodeFloat performs the inverse of decodeFloat in the
-- sense that for finite x with the exception of -0.0,
-- uncurry encodeFloat (decodeFloat x) = x.
-- encodeFloat m n is one of the two closest
-- representable floating-point numbers to m*b^^n (or
-- ±Infinity if overflow occurs); usually the closer, but if
-- m contains too many bits, the result may be rounded in the
-- wrong direction.
encodeFloat :: RealFloat a => Integer -> Int -> a
-- | exponent corresponds to the second component of
-- decodeFloat. exponent 0 = 0 and for finite
-- nonzero x, exponent x = snd (decodeFloat x)
-- + floatDigits x. If x is a finite floating-point
-- number, it is equal in value to significand x * b ^^
-- exponent x, where b is the floating-point radix.
-- The behaviour is unspecified on infinite or NaN values.
exponent :: RealFloat a => a -> Int
-- | The first component of decodeFloat, scaled to lie in the open
-- interval (-1,1), either 0.0 or of absolute
-- value >= 1/b, where b is the floating-point
-- radix. The behaviour is unspecified on infinite or NaN
-- values.
significand :: RealFloat a => a -> a
-- | multiplies a floating-point number by an integer power of the radix
scaleFloat :: RealFloat a => Int -> a -> a
-- | True if the argument is an IEEE "not-a-number" (NaN) value
isNaN :: RealFloat a => a -> Bool
-- | True if the argument is an IEEE infinity or negative infinity
isInfinite :: RealFloat a => a -> Bool
-- | True if the argument is too small to be represented in
-- normalized format
isDenormalized :: RealFloat a => a -> Bool
-- | True if the argument is an IEEE negative zero
isNegativeZero :: RealFloat a => a -> Bool
-- | True if the argument is an IEEE floating point number
isIEEE :: RealFloat a => a -> Bool
-- | a version of arctangent taking two real floating-point arguments. For
-- real floating x and y, atan2 y x
-- computes the angle (from the positive x-axis) of the vector from the
-- origin to the point (x,y). atan2 y x returns
-- a value in the range [-pi, pi]. It follows the
-- Common Lisp semantics for the origin when signed zeroes are supported.
-- atan2 y 1, with y in a type that is
-- RealFloat, should return the same value as atan
-- y. A default definition of atan2 is provided, but
-- implementors can provide a more accurate implementation.
atan2 :: RealFloat a => a -> a -> a
-- | Extracting components of fractions.
class (Real a, Fractional a) => RealFrac a
-- | The function properFraction takes a real fractional number
-- x and returns a pair (n,f) such that x =
-- n+f, and:
--
--
-- - n is an integral number with the same sign as x;
-- and
-- - f is a fraction with the same type and sign as
-- x, and with absolute value less than 1.
--
--
-- The default definitions of the ceiling, floor,
-- truncate and round functions are in terms of
-- properFraction.
properFraction :: (RealFrac a, Integral b) => a -> (b, a)
-- | truncate x returns the integer nearest x
-- between zero and x
truncate :: (RealFrac a, Integral b) => a -> b
-- | round x returns the nearest integer to x; the
-- even integer if x is equidistant between two integers
round :: (RealFrac a, Integral b) => a -> b
-- | ceiling x returns the least integer not less than
-- x
ceiling :: (RealFrac a, Integral b) => a -> b
-- | floor x returns the greatest integer not greater than
-- x
floor :: (RealFrac a, Integral b) => a -> b
-- | Conversion of values to readable Strings.
--
-- Derived instances of Show have the following properties, which
-- are compatible with derived instances of Read:
--
--
-- - The result of show is a syntactically correct Haskell
-- expression containing only constants, given the fixity declarations in
-- force at the point where the type is declared. It contains only the
-- constructor names defined in the data type, parentheses, and spaces.
-- When labelled constructor fields are used, braces, commas, field
-- names, and equal signs are also used.
-- - If the constructor is defined to be an infix operator, then
-- showsPrec will produce infix applications of the
-- constructor.
-- - the representation will be enclosed in parentheses if the
-- precedence of the top-level constructor in x is less than
-- d (associativity is ignored). Thus, if d is
-- 0 then the result is never surrounded in parentheses; if
-- d is 11 it is always surrounded in parentheses,
-- unless it is an atomic expression.
-- - If the constructor is defined using record syntax, then
-- show will produce the record-syntax form, with the fields given
-- in the same order as the original declaration.
--
--
-- For example, given the declarations
--
--
-- infixr 5 :^:
-- data Tree a = Leaf a | Tree a :^: Tree a
--
--
-- the derived instance of Show is equivalent to
--
--
-- instance (Show a) => Show (Tree a) where
--
-- showsPrec d (Leaf m) = showParen (d > app_prec) $
-- showString "Leaf " . showsPrec (app_prec+1) m
-- where app_prec = 10
--
-- showsPrec d (u :^: v) = showParen (d > up_prec) $
-- showsPrec (up_prec+1) u .
-- showString " :^: " .
-- showsPrec (up_prec+1) v
-- where up_prec = 5
--
--
-- Note that right-associativity of :^: is ignored. For example,
--
--
-- - show (Leaf 1 :^: Leaf 2 :^: Leaf 3) produces the
-- string "Leaf 1 :^: (Leaf 2 :^: Leaf 3)".
--
class Show a
-- | A specialised variant of showsPrec, using precedence context
-- zero, and returning an ordinary String.
show :: Show a => a -> String
-- | The class Typeable allows a concrete representation of a type
-- to be calculated.
class Typeable (a :: k)
-- | When a value is bound in do-notation, the pattern on the left
-- hand side of <- might not match. In this case, this class
-- provides a function to recover.
--
-- A Monad without a MonadFail instance may only be used in
-- conjunction with pattern that always match, such as newtypes, tuples,
-- data types with only a single data constructor, and irrefutable
-- patterns (~pat).
--
-- Instances of MonadFail should satisfy the following law:
-- fail s should be a left zero for >>=,
--
--
-- fail s >>= f = fail s
--
--
-- If your Monad is also MonadPlus, a popular definition is
--
--
-- fail _ = mzero
--
class Monad m => MonadFail (m :: Type -> Type)
fail :: MonadFail m => String -> m a
-- | Class for string-like datastructures; used by the overloaded string
-- extension (-XOverloadedStrings in GHC).
class IsString a
fromString :: IsString a => String -> a
-- | A functor with application, providing operations to
--
--
-- - embed pure expressions (pure), and
-- - sequence computations and combine their results (<*>
-- and liftA2).
--
--
-- A minimal complete definition must include implementations of
-- pure and of either <*> or liftA2. If it
-- defines both, then they must behave the same as their default
-- definitions:
--
--
-- (<*>) = liftA2 id
--
--
--
-- liftA2 f x y = f <$> x <*> y
--
--
-- Further, any definition must satisfy the following:
--
--
--
-- The other methods have the following default definitions, which may be
-- overridden with equivalent specialized implementations:
--
--
--
-- As a consequence of these laws, the Functor instance for
-- f will satisfy
--
--
--
-- It may be useful to note that supposing
--
--
-- forall x y. p (q x y) = f x . g y
--
--
-- it follows from the above that
--
--
-- liftA2 p (liftA2 q u v) = liftA2 f u . liftA2 g v
--
--
-- If f is also a Monad, it should satisfy
--
--
--
-- (which implies that pure and <*> satisfy the
-- applicative functor laws).
class Functor f => Applicative (f :: Type -> Type)
-- | Lift a value.
pure :: Applicative f => a -> f a
-- | Sequential application.
--
-- A few functors support an implementation of <*> that is
-- more efficient than the default one.
--
-- Example
--
-- Used in combination with (<$>),
-- (<*>) can be used to build a record.
--
--
-- >>> data MyState = MyState {arg1 :: Foo, arg2 :: Bar, arg3 :: Baz}
--
--
--
-- >>> produceFoo :: Applicative f => f Foo
--
--
--
-- >>> produceBar :: Applicative f => f Bar
--
-- >>> produceBaz :: Applicative f => f Baz
--
--
--
-- >>> mkState :: Applicative f => f MyState
--
-- >>> mkState = MyState <$> produceFoo <*> produceBar <*> produceBaz
--
(<*>) :: Applicative f => f (a -> b) -> f a -> f b
-- | Lift a binary function to actions.
--
-- Some functors support an implementation of liftA2 that is more
-- efficient than the default one. In particular, if fmap is an
-- expensive operation, it is likely better to use liftA2 than to
-- fmap over the structure and then use <*>.
--
-- This became a typeclass method in 4.10.0.0. Prior to that, it was a
-- function defined in terms of <*> and fmap.
--
-- Example
--
--
-- >>> liftA2 (,) (Just 3) (Just 5)
-- Just (3,5)
--
liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c
-- | Sequence actions, discarding the value of the first argument.
--
-- Examples
--
-- If used in conjunction with the Applicative instance for Maybe,
-- you can chain Maybe computations, with a possible "early return" in
-- case of Nothing.
--
--
-- >>> Just 2 *> Just 3
-- Just 3
--
--
--
-- >>> Nothing *> Just 3
-- Nothing
--
--
-- Of course a more interesting use case would be to have effectful
-- computations instead of just returning pure values.
--
--
-- >>> import Data.Char
--
-- >>> import Text.ParserCombinators.ReadP
--
-- >>> let p = string "my name is " *> munch1 isAlpha <* eof
--
-- >>> readP_to_S p "my name is Simon"
-- [("Simon","")]
--
(*>) :: Applicative f => f a -> f b -> f b
-- | Sequence actions, discarding the value of the second argument.
(<*) :: Applicative f => f a -> f b -> f a
infixl 4 <*
infixl 4 *>
infixl 4 <*>
-- | The Foldable class represents data structures that can be reduced to a
-- summary value one element at a time. Strict left-associative folds are
-- a good fit for space-efficient reduction, while lazy right-associative
-- folds are a good fit for corecursive iteration, or for folds that
-- short-circuit after processing an initial subsequence of the
-- structure's elements.
--
-- Instances can be derived automatically by enabling the
-- DeriveFoldable extension. For example, a derived instance for
-- a binary tree might be:
--
--
-- {-# LANGUAGE DeriveFoldable #-}
-- data Tree a = Empty
-- | Leaf a
-- | Node (Tree a) a (Tree a)
-- deriving Foldable
--
--
-- A more detailed description can be found in the Overview
-- section of Data.Foldable#overview.
--
-- For the class laws see the Laws section of
-- Data.Foldable#laws.
class Foldable (t :: TYPE LiftedRep -> Type)
-- | Given a structure with elements whose type is a Monoid, combine
-- them via the monoid's (<>) operator. This fold
-- is right-associative and lazy in the accumulator. When you need a
-- strict left-associative fold, use foldMap' instead, with
-- id as the map.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> fold [[1, 2, 3], [4, 5], [6], []]
-- [1,2,3,4,5,6]
--
--
--
-- >>> fold $ Node (Leaf (Sum 1)) (Sum 3) (Leaf (Sum 5))
-- Sum {getSum = 9}
--
--
-- Folds of unbounded structures do not terminate when the monoid's
-- (<>) operator is strict:
--
--
-- >>> fold (repeat Nothing)
-- * Hangs forever *
--
--
-- Lazy corecursive folds of unbounded structures are fine:
--
--
-- >>> take 12 $ fold $ map (\i -> [i..i+2]) [0..]
-- [0,1,2,1,2,3,2,3,4,3,4,5]
--
-- >>> sum $ take 4000000 $ fold $ map (\i -> [i..i+2]) [0..]
-- 2666668666666
--
fold :: (Foldable t, Monoid m) => t m -> m
-- | Map each element of the structure into a monoid, and combine the
-- results with (<>). This fold is
-- right-associative and lazy in the accumulator. For strict
-- left-associative folds consider foldMap' instead.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> foldMap Sum [1, 3, 5]
-- Sum {getSum = 9}
--
--
--
-- >>> foldMap Product [1, 3, 5]
-- Product {getProduct = 15}
--
--
--
-- >>> foldMap (replicate 3) [1, 2, 3]
-- [1,1,1,2,2,2,3,3,3]
--
--
-- When a Monoid's (<>) is lazy in its second
-- argument, foldMap can return a result even from an unbounded
-- structure. For example, lazy accumulation enables
-- Data.ByteString.Builder to efficiently serialise large data
-- structures and produce the output incrementally:
--
--
-- >>> import qualified Data.ByteString.Lazy as L
--
-- >>> import qualified Data.ByteString.Builder as B
--
-- >>> let bld :: Int -> B.Builder; bld i = B.intDec i <> B.word8 0x20
--
-- >>> let lbs = B.toLazyByteString $ foldMap bld [0..]
--
-- >>> L.take 64 lbs
-- "0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24"
--
foldMap :: (Foldable t, Monoid m) => (a -> m) -> t a -> m
-- | Right-associative fold of a structure, lazy in the accumulator.
--
-- In the case of lists, foldr, when applied to a binary operator,
-- a starting value (typically the right-identity of the operator), and a
-- list, reduces the list using the binary operator, from right to left:
--
--
-- foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
--
--
-- Note that since the head of the resulting expression is produced by an
-- application of the operator to the first element of the list, given an
-- operator lazy in its right argument, foldr can produce a
-- terminating expression from an unbounded list.
--
-- For a general Foldable structure this should be semantically
-- identical to,
--
--
-- foldr f z = foldr f z . toList
--
--
-- Examples
--
-- Basic usage:
--
--
-- >>> foldr (||) False [False, True, False]
-- True
--
--
--
-- >>> foldr (||) False []
-- False
--
--
--
-- >>> foldr (\c acc -> acc ++ [c]) "foo" ['a', 'b', 'c', 'd']
-- "foodcba"
--
--
-- Infinite structures
--
-- ⚠️ Applying foldr to infinite structures usually doesn't
-- terminate.
--
-- It may still terminate under one of the following conditions:
--
--
-- - the folding function is short-circuiting
-- - the folding function is lazy on its second argument
--
--
-- Short-circuiting
--
-- (||) short-circuits on True values, so the
-- following terminates because there is a True value finitely far
-- from the left side:
--
--
-- >>> foldr (||) False (True : repeat False)
-- True
--
--
-- But the following doesn't terminate:
--
--
-- >>> foldr (||) False (repeat False ++ [True])
-- * Hangs forever *
--
--
-- Laziness in the second argument
--
-- Applying foldr to infinite structures terminates when the
-- operator is lazy in its second argument (the initial accumulator is
-- never used in this case, and so could be left undefined, but
-- [] is more clear):
--
--
-- >>> take 5 $ foldr (\i acc -> i : fmap (+3) acc) [] (repeat 1)
-- [1,4,7,10,13]
--
foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b
-- | Left-associative fold of a structure but with strict application of
-- the operator.
--
-- This ensures that each step of the fold is forced to Weak Head Normal
-- Form before being applied, avoiding the collection of thunks that
-- would otherwise occur. This is often what you want to strictly reduce
-- a finite structure to a single strict result (e.g. sum).
--
-- For a general Foldable structure this should be semantically
-- identical to,
--
--
-- foldl' f z = foldl' f z . toList
--
foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b
-- | List of elements of a structure, from left to right. If the entire
-- list is intended to be reduced via a fold, just fold the structure
-- directly bypassing the list.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> toList Nothing
-- []
--
--
--
-- >>> toList (Just 42)
-- [42]
--
--
--
-- >>> toList (Left "foo")
-- []
--
--
--
-- >>> toList (Node (Leaf 5) 17 (Node Empty 12 (Leaf 8)))
-- [5,17,12,8]
--
--
-- For lists, toList is the identity:
--
--
-- >>> toList [1, 2, 3]
-- [1,2,3]
--
toList :: Foldable t => t a -> [a]
-- | Test whether the structure is empty. The default implementation is
-- Left-associative and lazy in both the initial element and the
-- accumulator. Thus optimised for structures where the first element can
-- be accessed in constant time. Structures where this is not the case
-- should have a non-default implementation.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> null []
-- True
--
--
--
-- >>> null [1]
-- False
--
--
-- null is expected to terminate even for infinite structures. The
-- default implementation terminates provided the structure is bounded on
-- the left (there is a leftmost element).
--
--
-- >>> null [1..]
-- False
--
null :: Foldable t => t a -> Bool
-- | Returns the size/length of a finite structure as an Int. The
-- default implementation just counts elements starting with the
-- leftmost. Instances for structures that can compute the element count
-- faster than via element-by-element counting, should provide a
-- specialised implementation.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> length []
-- 0
--
--
--
-- >>> length ['a', 'b', 'c']
-- 3
--
-- >>> length [1..]
-- * Hangs forever *
--
length :: Foldable t => t a -> Int
-- | Does the element occur in the structure?
--
-- Note: elem is often used in infix form.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> 3 `elem` []
-- False
--
--
--
-- >>> 3 `elem` [1,2]
-- False
--
--
--
-- >>> 3 `elem` [1,2,3,4,5]
-- True
--
--
-- For infinite structures, the default implementation of elem
-- terminates if the sought-after value exists at a finite distance from
-- the left side of the structure:
--
--
-- >>> 3 `elem` [1..]
-- True
--
--
--
-- >>> 3 `elem` ([4..] ++ [3])
-- * Hangs forever *
--
elem :: (Foldable t, Eq a) => a -> t a -> Bool
-- | The sum function computes the sum of the numbers of a
-- structure.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> sum []
-- 0
--
--
--
-- >>> sum [42]
-- 42
--
--
--
-- >>> sum [1..10]
-- 55
--
--
--
-- >>> sum [4.1, 2.0, 1.7]
-- 7.8
--
--
--
-- >>> sum [1..]
-- * Hangs forever *
--
sum :: (Foldable t, Num a) => t a -> a
-- | The product function computes the product of the numbers of a
-- structure.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> product []
-- 1
--
--
--
-- >>> product [42]
-- 42
--
--
--
-- >>> product [1..10]
-- 3628800
--
--
--
-- >>> product [4.1, 2.0, 1.7]
-- 13.939999999999998
--
--
--
-- >>> product [1..]
-- * Hangs forever *
--
product :: (Foldable t, Num a) => t a -> a
infix 4 `elem`
-- | Functors representing data structures that can be transformed to
-- structures of the same shape by performing an
-- Applicative (or, therefore, Monad) action on each
-- element from left to right.
--
-- A more detailed description of what same shape means, the
-- various methods, how traversals are constructed, and example advanced
-- use-cases can be found in the Overview section of
-- Data.Traversable#overview.
--
-- For the class laws see the Laws section of
-- Data.Traversable#laws.
class (Functor t, Foldable t) => Traversable (t :: Type -> Type)
-- | Map each element of a structure to an action, evaluate these actions
-- from left to right, and collect the results. For a version that
-- ignores the results see traverse_.
--
-- Examples
--
-- Basic usage:
--
-- In the first two examples we show each evaluated action mapping to the
-- output structure.
--
--
-- >>> traverse Just [1,2,3,4]
-- Just [1,2,3,4]
--
--
--
-- >>> traverse id [Right 1, Right 2, Right 3, Right 4]
-- Right [1,2,3,4]
--
--
-- In the next examples, we show that Nothing and Left
-- values short circuit the created structure.
--
--
-- >>> traverse (const Nothing) [1,2,3,4]
-- Nothing
--
--
--
-- >>> traverse (\x -> if odd x then Just x else Nothing) [1,2,3,4]
-- Nothing
--
--
--
-- >>> traverse id [Right 1, Right 2, Right 3, Right 4, Left 0]
-- Left 0
--
traverse :: (Traversable t, Applicative f) => (a -> f b) -> t a -> f (t b)
-- | Evaluate each action in the structure from left to right, and collect
-- the results. For a version that ignores the results see
-- sequenceA_.
--
-- Examples
--
-- Basic usage:
--
-- For the first two examples we show sequenceA fully evaluating a a
-- structure and collecting the results.
--
--
-- >>> sequenceA [Just 1, Just 2, Just 3]
-- Just [1,2,3]
--
--
--
-- >>> sequenceA [Right 1, Right 2, Right 3]
-- Right [1,2,3]
--
--
-- The next two example show Nothing and Just will short
-- circuit the resulting structure if present in the input. For more
-- context, check the Traversable instances for Either and
-- Maybe.
--
--
-- >>> sequenceA [Just 1, Just 2, Just 3, Nothing]
-- Nothing
--
--
--
-- >>> sequenceA [Right 1, Right 2, Right 3, Left 4]
-- Left 4
--
sequenceA :: (Traversable t, Applicative f) => t (f a) -> f (t a)
-- | Map each element of a structure to a monadic action, evaluate these
-- actions from left to right, and collect the results. For a version
-- that ignores the results see mapM_.
--
-- Examples
--
-- mapM is literally a traverse with a type signature
-- restricted to Monad. Its implementation may be more efficient
-- due to additional power of Monad.
mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b)
-- | Evaluate each monadic action in the structure from left to right, and
-- collect the results. For a version that ignores the results see
-- sequence_.
--
-- Examples
--
-- Basic usage:
--
-- The first two examples are instances where the input and and output of
-- sequence are isomorphic.
--
--
-- >>> sequence $ Right [1,2,3,4]
-- [Right 1,Right 2,Right 3,Right 4]
--
--
--
-- >>> sequence $ [Right 1,Right 2,Right 3,Right 4]
-- Right [1,2,3,4]
--
--
-- The following examples demonstrate short circuit behavior for
-- sequence.
--
--
-- >>> sequence $ Left [1,2,3,4]
-- Left [1,2,3,4]
--
--
--
-- >>> sequence $ [Left 0, Right 1,Right 2,Right 3,Right 4]
-- Left 0
--
sequence :: (Traversable t, Monad m) => t (m a) -> m (t a)
-- | Representable types of kind *. This class is derivable in GHC
-- with the DeriveGeneric flag on.
--
-- A Generic instance must satisfy the following laws:
--
--
-- from . to ≡ id
-- to . from ≡ id
--
class Generic a
-- | The class of semigroups (types with an associative binary operation).
--
-- Instances should satisfy the following:
--
--
-- - Associativity x <> (y <> z) =
-- (x <> y) <> z
--
class Semigroup a
-- | An associative operation.
--
--
-- >>> [1,2,3] <> [4,5,6]
-- [1,2,3,4,5,6]
--
(<>) :: Semigroup a => a -> a -> a
infixr 6 <>
-- | The class of monoids (types with an associative binary operation that
-- has an identity). Instances should satisfy the following:
--
--
--
-- 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.
class Semigroup a => Monoid a
-- | Identity of mappend
--
--
-- >>> "Hello world" <> mempty
-- "Hello world"
--
mempty :: Monoid a => a
-- | An associative operation
--
-- NOTE: This method is redundant and has the default
-- implementation mappend = (<>) since
-- base-4.11.0.0. Should it be implemented manually, since
-- mappend is a synonym for (<>), it is expected that
-- the two functions are defined the same way. In a future GHC release
-- mappend will be removed from Monoid.
mappend :: Monoid a => a -> a -> a
-- | 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!"
--
mconcat :: Monoid a => [a] -> a
data Bool
False :: Bool
True :: Bool
-- | A String is a list of characters. String constants in Haskell
-- are values of type String.
--
-- See Data.List for operations on lists.
type String = [Char]
-- | The character type Char is an enumeration whose values
-- represent Unicode (or equivalently ISO/IEC 10646) code points (i.e.
-- characters, see http://www.unicode.org/ for details). This set
-- extends the ISO 8859-1 (Latin-1) character set (the first 256
-- characters), which is itself an extension of the ASCII character set
-- (the first 128 characters). A character literal in Haskell has type
-- Char.
--
-- To convert a Char to or from the corresponding Int value
-- defined by Unicode, use toEnum and fromEnum from the
-- Enum class respectively (or equivalently ord and
-- chr).
data Char
-- | Double-precision floating point numbers. It is desirable that this
-- type be at least equal in range and precision to the IEEE
-- double-precision type.
data Double
-- | Single-precision floating point numbers. It is desirable that this
-- type be at least equal in range and precision to the IEEE
-- single-precision type.
data Float
-- | A fixed-precision integer type with at least the range [-2^29 ..
-- 2^29-1]. The exact range for a given implementation can be
-- determined by using minBound and maxBound from the
-- Bounded class.
data Int
-- | 8-bit signed integer type
data Int8
-- | 16-bit signed integer type
data Int16
-- | 32-bit signed integer type
data Int32
-- | 64-bit signed integer type
data Int64
-- | Arbitrary precision integers. In contrast with fixed-size integral
-- types such as Int, the Integer type represents the
-- entire infinite range of integers.
--
-- Integers are stored in a kind of sign-magnitude form, hence do not
-- expect two's complement form when using bit operations.
--
-- If the value is small (fit into an Int), IS constructor
-- is used. Otherwise Integer and IN constructors are used
-- to store a BigNat representing respectively the positive or the
-- negative value magnitude.
--
-- Invariant: Integer and IN are used iff value doesn't fit
-- in IS
data Integer
-- | Natural number
--
-- Invariant: numbers <= 0xffffffffffffffff use the NS
-- constructor
data Natural
-- | 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.
data Maybe a
Nothing :: Maybe a
Just :: a -> Maybe a
data Ordering
LT :: Ordering
EQ :: Ordering
GT :: Ordering
-- | Arbitrary-precision rational numbers, represented as a ratio of two
-- Integer values. A rational number may be constructed using the
-- % operator.
type Rational = Ratio Integer
-- | A value of type IO a is a computation which, when
-- performed, does some I/O before returning a value of type a.
--
-- There is really only one way to "perform" an I/O action: bind it to
-- Main.main in your program. When your program is run, the I/O
-- will be performed. It isn't possible to perform I/O from an arbitrary
-- function, unless that function is itself in the IO monad and
-- called at some point, directly or indirectly, from Main.main.
--
-- IO is a monad, so IO actions can be combined using
-- either the do-notation or the >> and >>=
-- operations from the Monad class.
data IO a
-- | A Word is an unsigned integral type, with the same size as
-- Int.
data Word
-- | 8-bit unsigned integer type
data Word8
-- | 16-bit unsigned integer type
data Word16
-- | 32-bit unsigned integer type
data Word32
-- | 64-bit unsigned integer type
data Word64
-- | The Either type represents values with two possibilities: a
-- value of type Either a b is either Left
-- a or Right b.
--
-- The Either type is sometimes used to represent a value which is
-- either correct or an error; by convention, the Left constructor
-- is used to hold an error value and the Right constructor is
-- used to hold a correct value (mnemonic: "right" also means "correct").
--
-- Examples
--
-- The type Either String Int is the type
-- of values which can be either a String or an Int. The
-- Left constructor can be used only on Strings, and the
-- Right constructor can be used only on Ints:
--
--
-- >>> let s = Left "foo" :: Either String Int
--
-- >>> s
-- Left "foo"
--
-- >>> let n = Right 3 :: Either String Int
--
-- >>> n
-- Right 3
--
-- >>> :type s
-- s :: Either String Int
--
-- >>> :type n
-- n :: Either String Int
--
--
-- The fmap from our Functor instance will ignore
-- Left values, but will apply the supplied function to values
-- contained in a Right:
--
--
-- >>> let s = Left "foo" :: Either String Int
--
-- >>> let n = Right 3 :: Either String Int
--
-- >>> fmap (*2) s
-- Left "foo"
--
-- >>> fmap (*2) n
-- Right 6
--
--
-- The Monad instance for Either allows us to chain
-- together multiple actions which may fail, and fail overall if any of
-- the individual steps failed. First we'll write a function that can
-- either parse an Int from a Char, or fail.
--
--
-- >>> import Data.Char ( digitToInt, isDigit )
--
-- >>> :{
-- let parseEither :: Char -> Either String Int
-- parseEither c
-- | isDigit c = Right (digitToInt c)
-- | otherwise = Left "parse error"
--
-- >>> :}
--
--
-- The following should work, since both '1' and '2'
-- can be parsed as Ints.
--
--
-- >>> :{
-- let parseMultiple :: Either String Int
-- parseMultiple = do
-- x <- parseEither '1'
-- y <- parseEither '2'
-- return (x + y)
--
-- >>> :}
--
--
--
-- >>> parseMultiple
-- Right 3
--
--
-- But the following should fail overall, since the first operation where
-- we attempt to parse 'm' as an Int will fail:
--
--
-- >>> :{
-- let parseMultiple :: Either String Int
-- parseMultiple = do
-- x <- parseEither 'm'
-- y <- parseEither '2'
-- return (x + y)
--
-- >>> :}
--
--
--
-- >>> parseMultiple
-- Left "parse error"
--
data Either a b
Left :: a -> Either a b
Right :: b -> Either a b
-- | Non-empty (and non-strict) list type.
data NonEmpty a
(:|) :: a -> [a] -> NonEmpty a
infixr 5 :|
-- | CallStacks are a lightweight method of obtaining a partial
-- call-stack at any point in the program.
--
-- A function can request its call-site with the HasCallStack
-- constraint. For example, we can define
--
--
-- putStrLnWithCallStack :: HasCallStack => String -> IO ()
--
--
-- as a variant of putStrLn that will get its call-site and
-- print it, along with the string given as argument. We can access the
-- call-stack inside putStrLnWithCallStack with
-- callStack.
--
--
-- >>> :{
-- putStrLnWithCallStack :: HasCallStack => String -> IO ()
-- putStrLnWithCallStack msg = do
-- putStrLn msg
-- putStrLn (prettyCallStack callStack)
-- :}
--
--
-- Thus, if we call putStrLnWithCallStack we will get a
-- formatted call-stack alongside our string.
--
--
-- >>> putStrLnWithCallStack "hello"
-- hello
-- CallStack (from HasCallStack):
-- putStrLnWithCallStack, called at <interactive>:... in interactive:Ghci...
--
--
-- GHC solves HasCallStack constraints in three steps:
--
--
-- - If there is a CallStack in scope -- i.e. the enclosing
-- function has a HasCallStack constraint -- GHC will append the
-- new call-site to the existing CallStack.
-- - If there is no CallStack in scope -- e.g. in the GHCi
-- session above -- and the enclosing definition does not have an
-- explicit type signature, GHC will infer a HasCallStack
-- constraint for the enclosing definition (subject to the monomorphism
-- restriction).
-- - If there is no CallStack in scope and the enclosing
-- definition has an explicit type signature, GHC will solve the
-- HasCallStack constraint for the singleton CallStack
-- containing just the current call-site.
--
--
-- CallStacks do not interact with the RTS and do not require
-- compilation with -prof. On the other hand, as they are built
-- up explicitly via the HasCallStack constraints, they will
-- generally not contain as much information as the simulated call-stacks
-- maintained by the RTS.
--
-- A CallStack is a [(String, SrcLoc)]. The
-- String is the name of function that was called, the
-- SrcLoc is the call-site. The list is ordered with the most
-- recently called function at the head.
--
-- NOTE: The intrepid user may notice that HasCallStack is just an
-- alias for an implicit parameter ?callStack :: CallStack. This
-- is an implementation detail and should not be considered part
-- of the CallStack API, we may decide to change the
-- implementation in the future.
data CallStack
-- | A convenience function for throwing a user error. This is useful for
-- cases where it would be too high a burden to define your own exception
-- type.
--
-- This throws an exception of type StringException. When GHC
-- supports it (base 4.9 and GHC 8.0 and onward), it includes a call
-- stack.
throwString :: (MonadIO m, HasCallStack) => String -> m a
stderr :: Handle
stdout :: Handle
-- | Haskell defines operations to read and write characters from and to
-- files, represented by values of type Handle. Each value of
-- this type is a handle: a record used by the Haskell run-time
-- system to manage I/O with file system objects. A handle has at
-- least the following properties:
--
--
-- - whether it manages input or output or both;
-- - whether it is open, closed or
-- semi-closed;
-- - whether the object is seekable;
-- - whether buffering is disabled, or enabled on a line or block
-- basis;
-- - a buffer (whose length may be zero).
--
--
-- Most handles will also have a current I/O position indicating where
-- the next input or output operation will occur. A handle is
-- readable if it manages only input or both input and output;
-- likewise, it is writable if it manages only output or both
-- input and output. A handle is open when first allocated. Once
-- it is closed it can no longer be used for either input or output,
-- though an implementation cannot re-use its storage while references
-- remain to it. Handles are in the Show and Eq classes.
-- The string produced by showing a handle is system dependent; it should
-- include enough information to identify the handle for debugging. A
-- handle is equal according to == only to itself; no attempt is
-- made to compare the internal state of different handles for equality.
data Handle
runLoggerLoggingT :: (MonadUnliftIO m, HasLogger env) => env -> LoggingT m a -> m a
newLogger :: MonadIO m => LogSettings -> m Logger
data Logger
class HasLogger env
loggerL :: HasLogger env => Lens' env Logger
-- | Set the number of LoggerSet Buffers used by
-- fast-logger
--
-- By default this matches getNumCapabilities, which is more
-- performant but does not guarantee message order. If this matters, such
-- as in a CLI, set this value to 1.
--
-- Support for this option depends on your version of
-- fast-logger:
--
-- TODO: table
setLogSettingsConcurrency :: Maybe Int -> LogSettings -> LogSettings
setLogSettingsBreakpoint :: Int -> LogSettings -> LogSettings
setLogSettingsColor :: LogColor -> LogSettings -> LogSettings
setLogSettingsFormat :: LogFormat -> LogSettings -> LogSettings
setLogSettingsDestination :: LogDestination -> LogSettings -> LogSettings
setLogSettingsLevels :: LogLevels -> LogSettings -> LogSettings
defaultLogSettings :: LogSettings
data LogSettings
data LogDestination
LogDestinationStdout :: LogDestination
LogDestinationStderr :: LogDestination
LogDestinationFile :: FilePath -> LogDestination
data LogFormat
LogFormatJSON :: LogFormat
LogFormatTerminal :: LogFormat
data LogColor
LogColorAuto :: LogColor
LogColorAlways :: LogColor
LogColorNever :: LogColor
-- | A Message captures a textual component and a metadata
-- component. The metadata component is a list of SeriesElem to
-- support tacking on arbitrary structured data to a log message.
--
-- With the OverloadedStrings extension enabled, Message
-- values can be constructed without metadata fairly conveniently, just
-- as if we were using Text directly:
--
--
-- logDebug "Some log message without metadata"
--
--
-- Metadata may be included in a Message via the :#
-- constructor:
--
--
-- logDebug $ "Some log message with metadata" :#
-- [ "bloorp" .= (42 :: Int)
-- , "bonk" .= ("abc" :: Text)
-- ]
--
--
-- The mnemonic for the :# constructor is that the #
-- symbol is sometimes referred to as a hash, a JSON object can be
-- thought of as a hash map, and so with :# (and enough
-- squinting), we are cons-ing a textual message onto a JSON
-- object. Yes, this mnemonic isn't well-typed, but hopefully it still
-- helps!
data Message
(:#) :: Text -> [SeriesElem] -> Message
infixr 5 :#
-- | Logs a Message with the location provided by an implicit
-- CallStack.
logDebug :: (HasCallStack, MonadLogger m) => Message -> m ()
-- | See logDebug
logInfo :: (HasCallStack, MonadLogger m) => Message -> m ()
-- | See logDebug
logWarn :: (HasCallStack, MonadLogger m) => Message -> m ()
-- | See logDebug
logError :: (HasCallStack, MonadLogger m) => Message -> m ()
-- | See logDebug
logOther :: (HasCallStack, MonadLogger m) => LogLevel -> Message -> m ()
-- | See logDebugCS
logDebugNS :: (HasCallStack, MonadLogger m) => LogSource -> Message -> m ()
-- | See logDebugNS
logInfoNS :: (HasCallStack, MonadLogger m) => LogSource -> Message -> m ()
-- | See logDebugNS
logWarnNS :: (HasCallStack, MonadLogger m) => LogSource -> Message -> m ()
-- | See logDebugNS
logErrorNS :: (HasCallStack, MonadLogger m) => LogSource -> Message -> m ()
-- | See logDebugNS
logOtherNS :: (HasCallStack, MonadLogger m) => LogSource -> LogLevel -> Message -> m ()
-- | This function lets us register structured, contextual info for the
-- duration of the provided action. All messages logged within the
-- provided action will automatically include this contextual info. This
-- function is thread-safe, as the contextual info is scoped to the
-- calling thread only.
--
-- This function is additive: if we nest calls to it, each nested call
-- will add to the existing thread context. In the case of overlapping
-- keys, the nested call's Pair value(s) will win. Whenever the
-- inner action completes, the thread context is rolled back to its value
-- set in the enclosing action.
--
-- If we wish to include the existing thread context from one thread in
-- another thread, we must register the thread context explicitly on that
-- other thread. myThreadContext can be leveraged in this case.
--
-- Registering thread context for messages can be useful in many
-- scenarios. One particularly apt scenario is in wai
-- middlewares. We can generate an ID for each incoming request then
-- include it in the thread context. Now all messages subsequently logged
-- from our endpoint handler will automatically include that request ID:
--
--
-- import Control.Monad.Logger.Aeson ((.=), withThreadContext)
-- import Network.Wai (Middleware)
-- import qualified Data.UUID.V4 as UUID
--
-- addRequestId :: Middleware
-- addRequestId app = \request sendResponse -> do
-- uuid <- UUID.nextRandom
-- withThreadContext ["requestId" .= uuid] do
-- app request sendResponse
--
--
-- If we're coming from a Java background, it may be helpful for us to
-- draw parallels between this function and log4j2's
-- ThreadContext (or perhaps log4j's MDC).
-- They all enable the same thing: setting some thread-local info that
-- will be automatically pulled into each logged message.
withThreadContext :: (MonadIO m, MonadMask m) => [Pair] -> m a -> m a
-- | This function lets us retrieve the calling thread's thread context.
-- For more detail, we can consult the docs for withThreadContext.
--
-- Note that even though the type signature lists MonadThrow as a
-- required constraint, the library guarantees that
-- myThreadContext will never throw.
myThreadContext :: (MonadIO m, MonadThrow m) => m (KeyMap Value)
-- | Monad transformer that adds a new logging function.
data LoggingT (m :: Type -> Type) a
-- | An extension of MonadLogger for the common case where the
-- logging action is a simple IO action. The advantage of using
-- this typeclass is that the logging function itself can be extracted as
-- a first-class value, which can make it easier to manipulate monad
-- transformer stacks, as an example.
class (MonadLogger m, MonadIO m) => MonadLoggerIO (m :: Type -> Type)
-- | Request the logging function itself.
askLoggerIO :: MonadLoggerIO m => m (Loc -> LogSource -> LogLevel -> LogStr -> IO ())
-- | A Monad which has the ability to log messages in some manner.
class Monad m => MonadLogger (m :: Type -> Type)
monadLoggerLog :: (MonadLogger m, ToLogStr msg) => Loc -> LogSource -> LogLevel -> msg -> m ()
type LogSource = Text
data LogLevel
LevelDebug :: LogLevel
LevelInfo :: LogLevel
LevelWarn :: LogLevel
LevelError :: LogLevel
LevelOther :: Text -> LogLevel
-- | A class for monads which provide for the ability to account for all
-- possible exit points from a computation, and to mask asynchronous
-- exceptions. Continuation-based monads are invalid instances of this
-- class.
--
-- Instances should ensure that, in the following code:
--
--
-- fg = f `finally` g
--
--
-- The action g is called regardless of what occurs within
-- f, including async exceptions. Some monads allow f
-- to abort the computation via other effects than throwing an exception.
-- For simplicity, we will consider aborting and throwing an exception to
-- be two forms of "throwing an error".
--
-- If f and g both throw an error, the error thrown by
-- fg depends on which errors we're talking about. In a monad
-- transformer stack, the deeper layers override the effects of the inner
-- layers; for example, ExceptT e1 (Except e2) a represents a
-- value of type Either e2 (Either e1 a), so throwing both an
-- e1 and an e2 will result in Left e2. If
-- f and g both throw an error from the same layer,
-- instances should ensure that the error from g wins.
--
-- Effects other than throwing an error are also overriden by the deeper
-- layers. For example, StateT s Maybe a represents a value of
-- type s -> Maybe (a, s), so if an error thrown from
-- f causes this function to return Nothing, any
-- changes to the state which f also performed will be erased.
-- As a result, g will see the state as it was before
-- f. Once g completes, f's error will be
-- rethrown, so g' state changes will be erased as well. This is
-- the normal interaction between effects in a monad transformer stack.
--
-- By contrast, lifted-base's version of finally always
-- discards all of g's non-IO effects, and g never sees
-- any of f's non-IO effects, regardless of the layer ordering
-- and regardless of whether f throws an error. This is not the
-- result of interacting effects, but a consequence of
-- MonadBaseControl's approach.
class MonadCatch m => MonadMask (m :: Type -> Type)
-- | A key/value pair for an Object.
type Pair = (Key, Value)
-- | A series of values that, when encoded, should be separated by commas.
-- Since 0.11.0.0, the .= operator is overloaded to create
-- either (Text, Value) or Series. You can use Series
-- when encoding directly to a bytestring builder as in the following
-- example:
--
--
-- toEncoding (Person name age) = pairs ("name" .= name <> "age" .= age)
--
data Series
-- | File and directory names are values of type String, whose
-- precise meaning is operating system dependent. Files can be opened,
-- yielding a handle which can then be used to operate on the contents of
-- that file.
type FilePath = String
-- | span, applied to a predicate p and a list xs,
-- returns a tuple where first element is longest prefix (possibly empty)
-- of xs of elements that satisfy p and second element
-- is the remainder of the list:
--
--
-- >>> span (< 3) [1,2,3,4,1,2,3,4]
-- ([1,2],[3,4,1,2,3,4])
--
-- >>> span (< 9) [1,2,3]
-- ([1,2,3],[])
--
-- >>> span (< 0) [1,2,3]
-- ([],[1,2,3])
--
--
-- span p xs is equivalent to (takeWhile p xs,
-- dropWhile p xs)
span :: (a -> Bool) -> [a] -> ([a], [a])
-- | error stops execution and displays an error message.
error :: forall (r :: RuntimeRep) (a :: TYPE r). HasCallStack => [Char] -> a
-- | The strict ST monad. The ST monad allows for destructive
-- updates, but is escapable (unlike IO). A computation of type
-- ST s a returns a value of type a, and execute
-- in "thread" s. The s parameter is either
--
--
-- - an uninstantiated type variable (inside invocations of
-- runST), or
-- - RealWorld (inside invocations of stToIO).
--
--
-- It serves to keep the internal states of different invocations of
-- runST separate from each other and from invocations of
-- stToIO.
--
-- The >>= and >> operations are strict in the
-- state (though not in values stored in the state). For example,
--
--
-- runST (writeSTRef _|_ v >>= f) = _|_
--
data ST s a
-- | Promote a function to a monad.
liftM :: Monad m => (a1 -> r) -> m a1 -> m r
-- | Identity function.
--
--
-- id x = x
--
id :: a -> a
-- | Case analysis for the Either type. If the value is
-- Left a, apply the first function to a; if it
-- is Right b, apply the second function to b.
--
-- Examples
--
-- We create two values of type Either String
-- Int, one using the Left constructor and another
-- using the Right constructor. Then we apply "either" the
-- length function (if we have a String) or the "times-two"
-- function (if we have an Int):
--
--
-- >>> let s = Left "foo" :: Either String Int
--
-- >>> let n = Right 3 :: Either String Int
--
-- >>> either length (*2) s
-- 3
--
-- >>> either length (*2) n
-- 6
--
either :: (a -> c) -> (b -> c) -> Either a b -> c
-- | See examples in Control.Monad.Reader. Note, the partially
-- applied function type (->) r is a simple reader monad. See
-- the instance declaration below.
class Monad m => MonadReader r (m :: Type -> Type) | m -> r
-- | Retrieves the monad environment.
ask :: MonadReader r m => m r
-- | Executes a computation in a modified environment.
local :: MonadReader r m => (r -> r) -> m a -> m a
-- | Builders denote sequences of bytes. They are Monoids
-- where mempty is the zero-length sequence and mappend is
-- concatenation, which runs in O(1).
data Builder
-- | The class of types that can be converted to a hash value.
--
-- Minimal implementation: hashWithSalt.
--
-- Note: the hash is not guaranteed to be stable across library
-- versions, operating systems or architectures. For stable hashing use
-- named hashes: SHA256, CRC32 etc.
--
-- If you are looking for Hashable instance in time
-- package, check time-compat
class Eq a => Hashable a
-- | An infix synonym for fmap.
--
-- The name of this operator is an allusion to $. Note the
-- similarities between their types:
--
--
-- ($) :: (a -> b) -> a -> b
-- (<$>) :: Functor f => (a -> b) -> f a -> f b
--
--
-- Whereas $ is function application, <$> is function
-- application lifted over a Functor.
--
-- Examples
--
-- Convert from a Maybe Int to a Maybe
-- String using show:
--
--
-- >>> show <$> Nothing
-- Nothing
--
-- >>> show <$> Just 3
-- Just "3"
--
--
-- Convert from an Either Int Int to an
-- Either Int String using show:
--
--
-- >>> show <$> Left 17
-- Left 17
--
-- >>> show <$> Right 17
-- Right "17"
--
--
-- Double each element of a list:
--
--
-- >>> (*2) <$> [1,2,3]
-- [2,4,6]
--
--
-- Apply even to the second element of a pair:
--
--
-- >>> even <$> (2,2)
-- (2,True)
--
(<$>) :: Functor f => (a -> b) -> f a -> f b
infixl 4 <$>
-- | 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]
--
const :: a -> b -> a
-- | Function composition.
(.) :: (b -> c) -> (a -> b) -> a -> c
infixr 9 .
-- | A space-efficient representation of a Word8 vector, supporting
-- many efficient operations.
--
-- A ByteString contains 8-bit bytes, or by using the operations
-- from Data.ByteString.Char8 it can be interpreted as containing
-- 8-bit characters.
data ByteString
-- | A space efficient, packed, unboxed Unicode text type.
data Text
-- | A Map from keys k to values a.
--
-- The Semigroup operation for Map is union, which
-- prefers values from the left operand. If m1 maps a key
-- k to a value a1, and m2 maps the same key
-- to a different value a2, then their union m1 <>
-- m2 maps k to a1.
data Map k a
-- | A map from keys to values. A map cannot contain duplicate keys; each
-- key can map to at most one value.
data HashMap k v
-- | A type that can be converted to JSON.
--
-- Instances in general must specify toJSON and
-- should (but don't need to) specify toEncoding.
--
-- An example type and instance:
--
--
-- -- Allow ourselves to write Text literals.
-- {-# LANGUAGE OverloadedStrings #-}
--
-- data Coord = Coord { x :: Double, y :: Double }
--
-- instance ToJSON Coord where
-- toJSON (Coord x y) = object ["x" .= x, "y" .= y]
--
-- toEncoding (Coord x y) = pairs ("x" .= x <> "y" .= y)
--
--
-- Instead of manually writing your ToJSON instance, there are two
-- options to do it automatically:
--
--
-- - Data.Aeson.TH provides Template Haskell functions which
-- will derive an instance at compile time. The generated instance is
-- optimized for your type so it will probably be more efficient than the
-- following option.
-- - The compiler can provide a default generic implementation for
-- toJSON.
--
--
-- To use the second, simply add a deriving Generic
-- clause to your datatype and declare a ToJSON instance. If you
-- require nothing other than defaultOptions, it is sufficient to
-- write (and this is the only alternative where the default
-- toJSON implementation is sufficient):
--
--
-- {-# LANGUAGE DeriveGeneric #-}
--
-- import GHC.Generics
--
-- data Coord = Coord { x :: Double, y :: Double } deriving Generic
--
-- instance ToJSON Coord where
-- toEncoding = genericToEncoding defaultOptions
--
--
-- or more conveniently using the DerivingVia extension
--
--
-- deriving via Generically Coord instance ToJSON Coord
--
--
-- If on the other hand you wish to customize the generic decoding, you
-- have to implement both methods:
--
--
-- customOptions = defaultOptions
-- { fieldLabelModifier = map toUpper
-- }
--
-- instance ToJSON Coord where
-- toJSON = genericToJSON customOptions
-- toEncoding = genericToEncoding customOptions
--
--
-- Previous versions of this library only had the toJSON method.
-- Adding toEncoding had two reasons:
--
--
-- - toEncoding is more efficient for the common case that the
-- output of toJSON is directly serialized to a
-- ByteString. Further, expressing either method in terms of the
-- other would be non-optimal.
-- - The choice of defaults allows a smooth transition for existing
-- users: Existing instances that do not define toEncoding still
-- compile and have the correct semantics. This is ensured by making the
-- default implementation of toEncoding use toJSON. This
-- produces correct results, but since it performs an intermediate
-- conversion to a Value, it will be less efficient than directly
-- emitting an Encoding. (this also means that specifying nothing
-- more than instance ToJSON Coord would be sufficient as a
-- generically decoding instance, but there probably exists no good
-- reason to not specify toEncoding in new instances.)
--
class ToJSON a
-- | Convert a Haskell value to a JSON-friendly intermediate type.
toJSON :: ToJSON a => a -> Value
-- | Encode a Haskell value as JSON.
--
-- The default implementation of this method creates an intermediate
-- Value using toJSON. This provides source-level
-- compatibility for people upgrading from older versions of this
-- library, but obviously offers no performance advantage.
--
-- To benefit from direct encoding, you must provide an
-- implementation for this method. The easiest way to do so is by having
-- your types implement Generic using the DeriveGeneric
-- extension, and then have GHC generate a method body as follows.
--
--
-- instance ToJSON Coord where
-- toEncoding = genericToEncoding defaultOptions
--
toEncoding :: ToJSON a => a -> Encoding
toJSONList :: ToJSON a => [a] -> Value
toEncodingList :: ToJSON a => [a] -> Encoding
(.=) :: (KeyValue kv, ToJSON v) => Key -> v -> kv
infixr 8 .=
-- | Create a Value from a list of name/value Pairs. If
-- duplicate keys arise, later keys and their associated values win.
object :: [Pair] -> Value
-- | A mutable variable in the IO monad
data IORef a
-- | A set of values. A set cannot contain duplicate values.
data HashSet a
-- | A class of types that can be fully evaluated.
class NFData a
-- | rnf should reduce its argument to normal form (that is, fully
-- evaluate all sub-components), and then return ().
--
--
--
-- Starting with GHC 7.2, you can automatically derive instances for
-- types possessing a Generic instance.
--
-- Note: Generic1 can be auto-derived starting with GHC 7.4
--
--
-- {-# LANGUAGE DeriveGeneric #-}
--
-- import GHC.Generics (Generic, Generic1)
-- import Control.DeepSeq
--
-- data Foo a = Foo a String
-- deriving (Eq, Generic, Generic1)
--
-- instance NFData a => NFData (Foo a)
-- instance NFData1 Foo
--
-- data Colour = Red | Green | Blue
-- deriving Generic
--
-- instance NFData Colour
--
--
-- Starting with GHC 7.10, the example above can be written more
-- concisely by enabling the new DeriveAnyClass extension:
--
--
-- {-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}
--
-- import GHC.Generics (Generic)
-- import Control.DeepSeq
--
-- data Foo a = Foo a String
-- deriving (Eq, Generic, Generic1, NFData, NFData1)
--
-- data Colour = Red | Green | Blue
-- deriving (Generic, NFData)
--
--
-- Compatibility with previous deepseq versions
--
-- Prior to version 1.4.0.0, the default implementation of the rnf
-- method was defined as
--
--
-- rnf a = seq a ()
--
--
-- However, starting with deepseq-1.4.0.0, the default
-- implementation is based on DefaultSignatures allowing for
-- more accurate auto-derived NFData instances. If you need the
-- previously used exact default rnf method implementation
-- semantics, use
--
--
-- instance NFData Colour where rnf x = seq x ()
--
--
-- or alternatively
--
--
-- instance NFData Colour where rnf = rwhnf
--
--
-- or
--
--
-- {-# LANGUAGE BangPatterns #-}
-- instance NFData Colour where rnf !_ = ()
--
rnf :: NFData a => a -> ()
-- | The class of monad transformers. Instances should satisfy the
-- following laws, which state that lift is a monad
-- transformation:
--
--
class MonadTrans (t :: Type -> Type -> Type -> Type)
-- | Lift a computation from the argument monad to the constructed monad.
lift :: (MonadTrans t, Monad m) => m a -> t m a
-- | Boolean "or", lazy in the second argument
(||) :: Bool -> Bool -> Bool
infixr 2 ||
-- | Boolean "not"
not :: Bool -> Bool
-- | Boolean "and", lazy in the second argument
(&&) :: Bool -> Bool -> Bool
infixr 3 &&
-- | The SomeException type is the root of the exception type
-- hierarchy. When an exception of type e is thrown, behind the
-- scenes it is encapsulated in a SomeException.
data SomeException
SomeException :: e -> SomeException
-- | A special case of error. It is expected that compilers will
-- recognize this and insert error messages which are more appropriate to
-- the context in which undefined appears.
undefined :: forall (r :: RuntimeRep) (a :: TYPE r). HasCallStack => a
-- | Strict (call-by-value) application operator. It takes a function and
-- an argument, evaluates the argument to weak head normal form (WHNF),
-- then calls the function with that value.
($!) :: forall (r :: RuntimeRep) a (b :: TYPE r). (a -> b) -> a -> b
infixr 0 $!
-- | Same as >>=, but with the arguments interchanged.
(=<<) :: Monad m => (a -> m b) -> m a -> m b
infixr 1 =<<
-- | asTypeOf is a type-restricted version of const. It is
-- usually used as an infix operator, and its typing forces its first
-- argument (which is usually overloaded) to have the same type as the
-- second.
asTypeOf :: a -> a -> a
-- | flip f takes its (first) two arguments in the reverse
-- order of f.
--
--
-- >>> flip (++) "hello" "world"
-- "worldhello"
--
flip :: (a -> b -> c) -> b -> a -> c
-- | Promote a function to a monad, scanning the monadic arguments from
-- left to right. For example,
--
--
-- liftM2 (+) [0,1] [0,2] = [0,2,1,3]
-- liftM2 (+) (Just 1) Nothing = Nothing
--
liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r
-- | Conditional execution of Applicative expressions. For example,
--
--
-- when debug (putStrLn "Debugging")
--
--
-- will output the string Debugging if the Boolean value
-- debug is True, and otherwise do nothing.
when :: Applicative f => Bool -> f () -> f ()
-- | the same as flip (-).
--
-- Because - is treated specially in the Haskell grammar,
-- (- e) is not a section, but an application of
-- prefix negation. However, (subtract
-- exp) is equivalent to the disallowed section.
subtract :: Num a => a -> a -> a
-- | curry converts an uncurried function to a curried function.
--
-- Examples
--
--
-- >>> curry fst 1 2
-- 1
--
curry :: ((a, b) -> c) -> a -> b -> c
-- | uncurry converts a curried function to a function on pairs.
--
-- Examples
--
--
-- >>> uncurry (+) (1,2)
-- 3
--
--
--
-- >>> uncurry ($) (show, 1)
-- "1"
--
--
--
-- >>> map (uncurry max) [(1,2), (3,4), (6,8)]
-- [2,4,8]
--
uncurry :: (a -> b -> c) -> (a, b) -> c
-- | Flipped version of <$>.
--
--
-- (<&>) = flip fmap
--
--
-- Examples
--
-- Apply (+1) to a list, a Just and a Right:
--
--
-- >>> Just 2 <&> (+1)
-- Just 3
--
--
--
-- >>> [1,2,3] <&> (+1)
-- [2,3,4]
--
--
--
-- >>> Right 3 <&> (+1)
-- Right 4
--
(<&>) :: Functor f => f a -> (a -> b) -> f b
infixl 1 <&>
-- | void value discards or ignores the result of
-- evaluation, such as the return value of an IO action.
--
-- Examples
--
-- Replace the contents of a Maybe Int with unit:
--
--
-- >>> void Nothing
-- Nothing
--
-- >>> void (Just 3)
-- Just ()
--
--
-- Replace the contents of an Either Int
-- Int with unit, resulting in an Either
-- Int ():
--
--
-- >>> void (Left 8675309)
-- Left 8675309
--
-- >>> void (Right 8675309)
-- Right ()
--
--
-- Replace every element of a list with unit:
--
--
-- >>> void [1,2,3]
-- [(),(),()]
--
--
-- Replace the second element of a pair with unit:
--
--
-- >>> void (1,2)
-- (1,())
--
--
-- Discard the result of an IO action:
--
--
-- >>> mapM print [1,2]
-- 1
-- 2
-- [(),()]
--
-- >>> void $ mapM print [1,2]
-- 1
-- 2
--
void :: Functor f => f a -> f ()
-- | & is a reverse application operator. This provides
-- notational convenience. Its precedence is one higher than that of the
-- forward application operator $, which allows & to be
-- nested in $.
--
--
-- >>> 5 & (+1) & show
-- "6"
--
(&) :: a -> (a -> b) -> b
infixl 1 &
-- | The catMaybes function takes a list of Maybes and
-- returns a list of all the Just values.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> catMaybes [Just 1, Nothing, Just 3]
-- [1,3]
--
--
-- When constructing a list of Maybe values, catMaybes can
-- be used to return all of the "success" results (if the list is the
-- result of a map, then mapMaybe would be more
-- appropriate):
--
--
-- >>> import Text.Read ( readMaybe )
--
-- >>> [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]
-- [Just 1,Nothing,Just 3]
--
-- >>> catMaybes $ [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]
-- [1,3]
--
catMaybes :: [Maybe a] -> [a]
-- | The fromMaybe function takes a default value and a Maybe
-- value. If the Maybe is Nothing, it returns the default
-- value; otherwise, it returns the value contained in the Maybe.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> fromMaybe "" (Just "Hello, World!")
-- "Hello, World!"
--
--
--
-- >>> fromMaybe "" Nothing
-- ""
--
--
-- Read an integer from a string using readMaybe. If we fail to
-- parse an integer, we want to return 0 by default:
--
--
-- >>> import Text.Read ( readMaybe )
--
-- >>> fromMaybe 0 (readMaybe "5")
-- 5
--
-- >>> fromMaybe 0 (readMaybe "")
-- 0
--
fromMaybe :: a -> Maybe a -> a
-- | The isJust function returns True iff its argument is of
-- the form Just _.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> isJust (Just 3)
-- True
--
--
--
-- >>> isJust (Just ())
-- True
--
--
--
-- >>> isJust Nothing
-- False
--
--
-- Only the outer constructor is taken into consideration:
--
--
-- >>> isJust (Just Nothing)
-- True
--
isJust :: Maybe a -> Bool
-- | The isNothing function returns True iff its argument is
-- Nothing.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> isNothing (Just 3)
-- False
--
--
--
-- >>> isNothing (Just ())
-- False
--
--
--
-- >>> isNothing Nothing
-- True
--
--
-- Only the outer constructor is taken into consideration:
--
--
-- >>> isNothing (Just Nothing)
-- False
--
isNothing :: Maybe a -> Bool
-- | The listToMaybe function returns Nothing on an empty
-- list or Just a where a is the first element
-- of the list.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> listToMaybe []
-- Nothing
--
--
--
-- >>> listToMaybe [9]
-- Just 9
--
--
--
-- >>> listToMaybe [1,2,3]
-- Just 1
--
--
-- Composing maybeToList with listToMaybe should be the
-- identity on singleton/empty lists:
--
--
-- >>> maybeToList $ listToMaybe [5]
-- [5]
--
-- >>> maybeToList $ listToMaybe []
-- []
--
--
-- But not on lists with more than one element:
--
--
-- >>> maybeToList $ listToMaybe [1,2,3]
-- [1]
--
listToMaybe :: [a] -> Maybe a
-- | The mapMaybe function is a version of map which can
-- throw out elements. In particular, the functional argument returns
-- something of type Maybe b. If this is Nothing,
-- no element is added on to the result list. If it is Just
-- b, then b is included in the result list.
--
-- Examples
--
-- Using mapMaybe f x is a shortcut for
-- catMaybes $ map f x in most cases:
--
--
-- >>> import Text.Read ( readMaybe )
--
-- >>> let readMaybeInt = readMaybe :: String -> Maybe Int
--
-- >>> mapMaybe readMaybeInt ["1", "Foo", "3"]
-- [1,3]
--
-- >>> catMaybes $ map readMaybeInt ["1", "Foo", "3"]
-- [1,3]
--
--
-- If we map the Just constructor, the entire list should be
-- returned:
--
--
-- >>> mapMaybe Just [1,2,3]
-- [1,2,3]
--
mapMaybe :: (a -> Maybe b) -> [a] -> [b]
-- | 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
-- ""
--
maybe :: b -> (a -> b) -> Maybe a -> b
-- | The maybeToList function returns an empty list when given
-- Nothing or a singleton list when given Just.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> maybeToList (Just 7)
-- [7]
--
--
--
-- >>> maybeToList Nothing
-- []
--
--
-- One can use maybeToList to avoid pattern matching when combined
-- with a function that (safely) works on lists:
--
--
-- >>> import Text.Read ( readMaybe )
--
-- >>> sum $ maybeToList (readMaybe "3")
-- 3
--
-- >>> sum $ maybeToList (readMaybe "")
-- 0
--
maybeToList :: Maybe a -> [a]
-- | break, applied to a predicate p and a list
-- xs, returns a tuple where first element is longest prefix
-- (possibly empty) of xs of elements that do not satisfy
-- p and second element is the remainder of the list:
--
--
-- >>> break (> 3) [1,2,3,4,1,2,3,4]
-- ([1,2,3],[4,1,2,3,4])
--
-- >>> break (< 9) [1,2,3]
-- ([],[1,2,3])
--
-- >>> break (> 9) [1,2,3]
-- ([1,2,3],[])
--
--
-- break p is equivalent to span (not .
-- p).
break :: (a -> Bool) -> [a] -> ([a], [a])
-- | drop n xs returns the suffix of xs after the
-- first n elements, or [] if n >= length
-- xs.
--
--
-- >>> drop 6 "Hello World!"
-- "World!"
--
-- >>> drop 3 [1,2,3,4,5]
-- [4,5]
--
-- >>> drop 3 [1,2]
-- []
--
-- >>> drop 3 []
-- []
--
-- >>> drop (-1) [1,2]
-- [1,2]
--
-- >>> drop 0 [1,2]
-- [1,2]
--
--
-- It is an instance of the more general genericDrop, in which
-- n may be of any integral type.
drop :: Int -> [a] -> [a]
-- | dropWhile p xs returns the suffix remaining after
-- takeWhile p xs.
--
--
-- >>> dropWhile (< 3) [1,2,3,4,5,1,2,3]
-- [3,4,5,1,2,3]
--
-- >>> dropWhile (< 9) [1,2,3]
-- []
--
-- >>> dropWhile (< 0) [1,2,3]
-- [1,2,3]
--
dropWhile :: (a -> Bool) -> [a] -> [a]
-- | <math>. lookup key assocs looks up a key in an
-- association list.
--
--
-- >>> lookup 2 []
-- Nothing
--
-- >>> lookup 2 [(1, "first")]
-- Nothing
--
-- >>> lookup 2 [(1, "first"), (2, "second"), (3, "third")]
-- Just "second"
--
lookup :: Eq a => a -> [(a, b)] -> Maybe b
-- | replicate n x is a list of length n with
-- x the value of every element. It is an instance of the more
-- general genericReplicate, in which n may be of any
-- integral type.
--
--
-- >>> replicate 0 True
-- []
--
-- >>> replicate (-1) True
-- []
--
-- >>> replicate 4 True
-- [True,True,True,True]
--
replicate :: Int -> a -> [a]
-- | reverse xs returns the elements of xs in
-- reverse order. xs must be finite.
--
--
-- >>> reverse []
-- []
--
-- >>> reverse [42]
-- [42]
--
-- >>> reverse [2,5,7]
-- [7,5,2]
--
-- >>> reverse [1..]
-- * Hangs forever *
--
reverse :: [a] -> [a]
-- | take n, applied to a list xs, returns the
-- prefix of xs of length n, or xs itself if
-- n >= length xs.
--
--
-- >>> take 5 "Hello World!"
-- "Hello"
--
-- >>> take 3 [1,2,3,4,5]
-- [1,2,3]
--
-- >>> take 3 [1,2]
-- [1,2]
--
-- >>> take 3 []
-- []
--
-- >>> take (-1) [1,2]
-- []
--
-- >>> take 0 [1,2]
-- []
--
--
-- It is an instance of the more general genericTake, in which
-- n may be of any integral type.
take :: Int -> [a] -> [a]
-- | takeWhile, applied to a predicate p and a list
-- xs, returns the longest prefix (possibly empty) of
-- xs of elements that satisfy p.
--
--
-- >>> takeWhile (< 3) [1,2,3,4,1,2,3,4]
-- [1,2]
--
-- >>> takeWhile (< 9) [1,2,3]
-- [1,2,3]
--
-- >>> takeWhile (< 0) [1,2,3]
-- []
--
takeWhile :: (a -> Bool) -> [a] -> [a]
-- | <math>. zipWith generalises zip by zipping with
-- the function given as the first argument, instead of a tupling
-- function.
--
--
-- zipWith (,) xs ys == zip xs ys
-- zipWith f [x1,x2,x3..] [y1,y2,y3..] == [f x1 y1, f x2 y2, f x3 y3..]
--
--
-- For example, zipWith (+) is applied to two lists to
-- produce the list of corresponding sums:
--
--
-- >>> zipWith (+) [1, 2, 3] [4, 5, 6]
-- [5,7,9]
--
--
-- zipWith is right-lazy:
--
--
-- >>> let f = undefined
--
-- >>> zipWith f [] undefined
-- []
--
--
-- zipWith is capable of list fusion, but it is restricted to its
-- first list argument and its resulting list.
zipWith :: (a -> b -> c) -> [a] -> [b] -> [c]
-- | raise a number to a non-negative integral power
(^) :: (Num a, Integral b) => a -> b -> a
infixr 8 ^
-- | raise a number to an integral power
(^^) :: (Fractional a, Integral b) => a -> b -> a
infixr 8 ^^
even :: Integral a => a -> Bool
-- | gcd x y is the non-negative factor of both x
-- and y of which every common factor of x and
-- y is also a factor; for example gcd 4 2 = 2,
-- gcd (-4) 6 = 2, gcd 0 4 = 4.
-- gcd 0 0 = 0. (That is, the common divisor
-- that is "greatest" in the divisibility preordering.)
--
-- Note: Since for signed fixed-width integer types, abs
-- minBound < 0, the result may be negative if one of the
-- arguments is minBound (and necessarily is if the other
-- is 0 or minBound) for such types.
gcd :: Integral a => a -> a -> a
-- | lcm x y is the smallest positive integer that both
-- x and y divide.
lcm :: Integral a => a -> a -> a
odd :: Integral a => a -> Bool
-- | Proxy is a type that holds no data, but has a phantom parameter
-- of arbitrary type (or even kind). Its use is to provide type
-- information, even though there is no value available of that type (or
-- it may be too costly to create one).
--
-- Historically, Proxy :: Proxy a is a safer
-- alternative to the undefined :: a idiom.
--
--
-- >>> Proxy :: Proxy (Void, Int -> Int)
-- Proxy
--
--
-- Proxy can even hold types of higher kinds,
--
--
-- >>> Proxy :: Proxy Either
-- Proxy
--
--
--
-- >>> Proxy :: Proxy Functor
-- Proxy
--
--
--
-- >>> Proxy :: Proxy complicatedStructure
-- Proxy
--
data Proxy (t :: k)
Proxy :: Proxy (t :: k)
-- | lines breaks a string up into a list of strings at newline
-- characters. The resulting strings do not contain newlines.
--
-- Note that after splitting the string at newline characters, the last
-- part of the string is considered a line even if it doesn't end with a
-- newline. For example,
--
--
-- >>> lines ""
-- []
--
--
--
-- >>> lines "\n"
-- [""]
--
--
--
-- >>> lines "one"
-- ["one"]
--
--
--
-- >>> lines "one\n"
-- ["one"]
--
--
--
-- >>> lines "one\n\n"
-- ["one",""]
--
--
--
-- >>> lines "one\ntwo"
-- ["one","two"]
--
--
--
-- >>> lines "one\ntwo\n"
-- ["one","two"]
--
--
-- Thus lines s contains at least as many elements as
-- newlines in s.
lines :: String -> [String]
-- | unlines is an inverse operation to lines. It joins
-- lines, after appending a terminating newline to each.
--
--
-- >>> unlines ["Hello", "World", "!"]
-- "Hello\nWorld\n!\n"
--
unlines :: [String] -> String
-- | unwords is an inverse operation to words. It joins words
-- with separating spaces.
--
--
-- >>> unwords ["Lorem", "ipsum", "dolor"]
-- "Lorem ipsum dolor"
--
unwords :: [String] -> String
-- | words breaks a string up into a list of words, which were
-- delimited by white space.
--
--
-- >>> words "Lorem ipsum\ndolor"
-- ["Lorem","ipsum","dolor"]
--
words :: String -> [String]
-- | Determines whether all elements of the structure satisfy the
-- predicate.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> all (> 3) []
-- True
--
--
--
-- >>> all (> 3) [1,2]
-- False
--
--
--
-- >>> all (> 3) [1,2,3,4,5]
-- False
--
--
--
-- >>> all (> 3) [1..]
-- False
--
--
--
-- >>> all (> 3) [4..]
-- * Hangs forever *
--
all :: Foldable t => (a -> Bool) -> t a -> Bool
-- | and returns the conjunction of a container of Bools. For the
-- result to be True, the container must be finite; False,
-- however, results from a False value finitely far from the left
-- end.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> and []
-- True
--
--
--
-- >>> and [True]
-- True
--
--
--
-- >>> and [False]
-- False
--
--
--
-- >>> and [True, True, False]
-- False
--
--
--
-- >>> and (False : repeat True) -- Infinite list [False,True,True,True,...
-- False
--
--
--
-- >>> and (repeat True)
-- * Hangs forever *
--
and :: Foldable t => t Bool -> Bool
-- | Determines whether any element of the structure satisfies the
-- predicate.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> any (> 3) []
-- False
--
--
--
-- >>> any (> 3) [1,2]
-- False
--
--
--
-- >>> any (> 3) [1,2,3,4,5]
-- True
--
--
--
-- >>> any (> 3) [1..]
-- True
--
--
--
-- >>> any (> 3) [0, -1..]
-- * Hangs forever *
--
any :: Foldable t => (a -> Bool) -> t a -> Bool
-- | The concatenation of all the elements of a container of lists.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> concat (Just [1, 2, 3])
-- [1,2,3]
--
--
--
-- >>> concat (Left 42)
-- []
--
--
--
-- >>> concat [[1, 2, 3], [4, 5], [6], []]
-- [1,2,3,4,5,6]
--
concat :: Foldable t => t [a] -> [a]
-- | Map a function over all the elements of a container and concatenate
-- the resulting lists.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> concatMap (take 3) [[1..], [10..], [100..], [1000..]]
-- [1,2,3,10,11,12,100,101,102,1000,1001,1002]
--
--
--
-- >>> concatMap (take 3) (Just [1..])
-- [1,2,3]
--
concatMap :: Foldable t => (a -> [b]) -> t a -> [b]
-- | The sum of a collection of actions, generalizing concat.
--
-- msum is just like asum, but specialised to
-- MonadPlus.
msum :: (Foldable t, MonadPlus m) => t (m a) -> m a
-- | notElem is the negation of elem.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> 3 `notElem` []
-- True
--
--
--
-- >>> 3 `notElem` [1,2]
-- True
--
--
--
-- >>> 3 `notElem` [1,2,3,4,5]
-- False
--
--
-- For infinite structures, notElem terminates if the value exists
-- at a finite distance from the left side of the structure:
--
--
-- >>> 3 `notElem` [1..]
-- False
--
--
--
-- >>> 3 `notElem` ([4..] ++ [3])
-- * Hangs forever *
--
notElem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `notElem`
-- | or returns the disjunction of a container of Bools. For the
-- result to be False, the container must be finite; True,
-- however, results from a True value finitely far from the left
-- end.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> or []
-- False
--
--
--
-- >>> or [True]
-- True
--
--
--
-- >>> or [False]
-- False
--
--
--
-- >>> or [True, True, False]
-- True
--
--
--
-- >>> or (True : repeat False) -- Infinite list [True,False,False,False,...
-- True
--
--
--
-- >>> or (repeat False)
-- * Hangs forever *
--
or :: Foldable t => t Bool -> Bool
-- | Evaluate each monadic action in the structure from left to right, and
-- ignore the results. For a version that doesn't ignore the results see
-- sequence.
--
-- sequence_ is just like sequenceA_, but specialised to
-- monadic actions.
sequence_ :: (Foldable t, Monad m) => t (m a) -> m ()
-- | 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
--
class (Typeable e, Show e) => Exception e
toException :: Exception e => e -> SomeException
fromException :: Exception e => SomeException -> Maybe e
-- | Render this exception value in a human-friendly manner.
--
-- Default implementation: show.
displayException :: Exception e => e -> String
-- | Identity functor and monad. (a non-strict monad)
newtype Identity a
Identity :: a -> Identity a
[runIdentity] :: Identity a -> a
-- | forM is mapM with its arguments flipped. For a version
-- that ignores the results see forM_.
forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b)
-- | Strict version of <$>.
(<$!>) :: Monad m => (a -> b) -> m a -> m b
infixl 4 <$!>
-- | Right-to-left composition of Kleisli arrows.
-- (>=>), with the arguments flipped.
--
-- Note how this operator resembles function composition
-- (.):
--
--
-- (.) :: (b -> c) -> (a -> b) -> a -> c
-- (<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
--
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
infixr 1 <=<
-- | Left-to-right composition of Kleisli arrows.
--
-- '(bs >=> cs) a' can be understood as the
-- do expression
--
--
-- do b <- bs a
-- cs b
--
(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c
infixr 1 >=>
-- | This generalizes the list-based filter function.
filterM :: Applicative m => (a -> m Bool) -> [a] -> m [a]
-- | The foldM function is analogous to foldl, except that
-- its result is encapsulated in a monad. Note that foldM works
-- from left-to-right over the list arguments. This could be an issue
-- where (>>) and the `folded function' are not
-- commutative.
--
--
-- foldM f a1 [x1, x2, ..., xm]
--
-- ==
--
-- do
-- a2 <- f a1 x1
-- a3 <- f a2 x2
-- ...
-- f am xm
--
--
-- If right-to-left evaluation is required, the input list should be
-- reversed.
--
-- Note: foldM is the same as foldlM
foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b
-- | Like foldM, but discards the result.
foldM_ :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m ()
-- | Repeat an action indefinitely.
--
-- Examples
--
-- A common use of forever is to process input from network
-- sockets, Handles, and channels (e.g. MVar and
-- Chan).
--
-- For example, here is how we might implement an echo server,
-- using forever both to listen for client connections on a
-- network socket and to echo client input on client connection handles:
--
--
-- echoServer :: Socket -> IO ()
-- echoServer socket = forever $ do
-- client <- accept socket
-- forkFinally (echo client) (\_ -> hClose client)
-- where
-- echo :: Handle -> IO ()
-- echo client = forever $
-- hGetLine client >>= hPutStrLn client
--
--
-- Note that "forever" isn't necessarily non-terminating. If the action
-- is in a MonadPlus and short-circuits after some number
-- of iterations. then forever actually returns
-- mzero, effectively short-circuiting its caller.
forever :: Applicative f => f a -> f b
-- | Direct MonadPlus equivalent of filter.
--
-- Examples
--
-- The filter function is just mfilter specialized to the
-- list monad:
--
--
-- filter = ( mfilter :: (a -> Bool) -> [a] -> [a] )
--
--
-- An example using mfilter with the Maybe monad:
--
--
-- >>> mfilter odd (Just 1)
-- Just 1
--
-- >>> mfilter odd (Just 2)
-- Nothing
--
mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a
-- | Like replicateM, but discards the result.
--
-- Examples
--
--
-- >>> replicateM_ 3 (putStrLn "a")
-- a
-- a
-- a
--
replicateM_ :: Applicative m => Int -> m a -> m ()
-- | The reverse of when.
unless :: Applicative f => Bool -> f () -> f ()
-- | The zipWithM function generalizes zipWith to arbitrary
-- applicative functors.
zipWithM :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m [c]
-- | zipWithM_ is the extension of zipWithM which ignores the
-- final result.
zipWithM_ :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m ()
-- | Monads in which IO computations may be embedded. Any monad
-- built by applying a sequence of monad transformers to the IO
-- monad will be an instance of this class.
--
-- Instances should satisfy the following laws, which state that
-- liftIO is a transformer of monads:
--
--
class Monad m => MonadIO (m :: Type -> Type)
-- | Lift a computation from the IO monad. This allows us to run IO
-- computations in any monadic stack, so long as it supports these kinds
-- of operations (i.e. IO is the base monad for the stack).
--
-- Example
--
--
-- import Control.Monad.Trans.State -- from the "transformers" library
--
-- printState :: Show s => StateT s IO ()
-- printState = do
-- state <- get
-- liftIO $ print state
--
--
-- Had we omitted liftIO, we would have ended up with
-- this error:
--
--
-- • Couldn't match type ‘IO’ with ‘StateT s IO’
-- Expected type: StateT s IO ()
-- Actual type: IO ()
--
--
-- The important part here is the mismatch between StateT s IO
-- () and IO ().
--
-- Luckily, we know of a function that takes an IO a and
-- returns an (m a): liftIO, enabling us to run
-- the program and see the expected results:
--
--
-- > evalStateT printState "hello"
-- "hello"
--
-- > evalStateT printState 3
-- 3
--
liftIO :: MonadIO m => IO a -> m a
-- | Collects the list of elements of a structure, from left to right.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> biList (18, 42)
-- [18,42]
--
--
--
-- >>> biList (Left 18)
-- [18]
--
biList :: Bifoldable t => t a a -> [a]
-- | Determines whether all elements of the structure satisfy their
-- appropriate predicate argument. Empty structures yield True.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> biall even isDigit (27, 't')
-- False
--
--
--
-- >>> biall even isDigit (26, '8')
-- True
--
--
--
-- >>> biall even isDigit (Left 27)
-- False
--
--
--
-- >>> biall even isDigit (Left 26)
-- True
--
--
--
-- >>> biall even isDigit (BiList [26, 52] ['3', '8'])
-- True
--
--
-- Empty structures yield True:
--
--
-- >>> biall even isDigit (BiList [] [])
-- True
--
biall :: Bifoldable t => (a -> Bool) -> (b -> Bool) -> t a b -> Bool
-- | biand returns the conjunction of a container of Bools. For the
-- result to be True, the container must be finite; False,
-- however, results from a False value finitely far from the left
-- end.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> biand (True, False)
-- False
--
--
--
-- >>> biand (True, True)
-- True
--
--
--
-- >>> biand (Left True)
-- True
--
--
-- Empty structures yield True:
--
--
-- >>> biand (BiList [] [])
-- True
--
--
-- A False value finitely far from the left end yields
-- False (short circuit):
--
--
-- >>> biand (BiList [True, True, False, True] (repeat True))
-- False
--
--
-- A False value infinitely far from the left end hangs:
--
--
-- > biand (BiList (repeat True) [False])
-- * Hangs forever *
--
--
-- An infinitely True value hangs:
--
--
-- > biand (BiList (repeat True) [])
-- * Hangs forever *
--
biand :: Bifoldable t => t Bool Bool -> Bool
-- | Determines whether any element of the structure satisfies its
-- appropriate predicate argument. Empty structures yield False.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> biany even isDigit (27, 't')
-- False
--
--
--
-- >>> biany even isDigit (27, '8')
-- True
--
--
--
-- >>> biany even isDigit (26, 't')
-- True
--
--
--
-- >>> biany even isDigit (Left 27)
-- False
--
--
--
-- >>> biany even isDigit (Left 26)
-- True
--
--
--
-- >>> biany even isDigit (BiList [27, 53] ['t', '8'])
-- True
--
--
-- Empty structures yield False:
--
--
-- >>> biany even isDigit (BiList [] [])
-- False
--
biany :: Bifoldable t => (a -> Bool) -> (b -> Bool) -> t a b -> Bool
-- | The sum of a collection of actions, generalizing biconcat.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> biasum (Nothing, Nothing)
-- Nothing
--
--
--
-- >>> biasum (Nothing, Just 42)
-- Just 42
--
--
--
-- >>> biasum (Just 18, Nothing)
-- Just 18
--
--
--
-- >>> biasum (Just 18, Just 42)
-- Just 18
--
biasum :: (Bifoldable t, Alternative f) => t (f a) (f a) -> f a
-- | Reduces a structure of lists to the concatenation of those lists.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> biconcat ([1, 2, 3], [4, 5])
-- [1,2,3,4,5]
--
--
--
-- >>> biconcat (Left [1, 2, 3])
-- [1,2,3]
--
--
--
-- >>> biconcat (BiList [[1, 2, 3, 4, 5], [6, 7, 8]] [[9]])
-- [1,2,3,4,5,6,7,8,9]
--
biconcat :: Bifoldable t => t [a] [a] -> [a]
-- | Given a means of mapping the elements of a structure to lists,
-- computes the concatenation of all such lists in order.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> biconcatMap (take 3) (fmap digitToInt) ([1..], "89")
-- [1,2,3,8,9]
--
--
--
-- >>> biconcatMap (take 3) (fmap digitToInt) (Left [1..])
-- [1,2,3]
--
--
--
-- >>> biconcatMap (take 3) (fmap digitToInt) (Right "89")
-- [8,9]
--
biconcatMap :: Bifoldable t => (a -> [c]) -> (b -> [c]) -> t a b -> [c]
-- | Does the element occur in the structure?
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bielem 42 (17, 42)
-- True
--
--
--
-- >>> bielem 42 (17, 43)
-- False
--
--
--
-- >>> bielem 42 (Left 42)
-- True
--
--
--
-- >>> bielem 42 (Right 13)
-- False
--
--
--
-- >>> bielem 42 (BiList [1..5] [1..100])
-- True
--
--
--
-- >>> bielem 42 (BiList [1..5] [1..41])
-- False
--
bielem :: (Bifoldable t, Eq a) => a -> t a a -> Bool
-- | The bifind function takes a predicate and a structure and
-- returns the leftmost element of the structure matching the predicate,
-- or Nothing if there is no such element.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bifind even (27, 53)
-- Nothing
--
--
--
-- >>> bifind even (27, 52)
-- Just 52
--
--
--
-- >>> bifind even (26, 52)
-- Just 26
--
--
-- Empty structures always yield Nothing:
--
--
-- >>> bifind even (BiList [] [])
-- Nothing
--
bifind :: Bifoldable t => (a -> Bool) -> t a a -> Maybe a
-- | As bifoldl, but strict in the result of the reduction functions
-- at each step.
--
-- This ensures that each step of the bifold is forced to weak head
-- normal form before being applied, avoiding the collection of thunks
-- that would otherwise occur. This is often what you want to strictly
-- reduce a finite structure to a single, monolithic result (e.g.,
-- bilength).
bifoldl' :: Bifoldable t => (a -> b -> a) -> (a -> c -> a) -> a -> t b c -> a
-- | A variant of bifoldl that has no base case, and thus may only
-- be applied to non-empty structures.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bifoldl1 (+) (5, 7)
-- 12
--
--
--
-- >>> bifoldl1 (+) (Right 7)
-- 7
--
--
--
-- >>> bifoldl1 (+) (Left 5)
-- 5
--
--
--
-- > bifoldl1 (+) (BiList [1, 2] [3, 4])
-- 10 -- ((1 + 2) + 3) + 4
--
--
--
-- >>> bifoldl1 (+) (BiList [1, 2] [])
-- 3
--
--
-- On empty structures, this function throws an exception:
--
--
-- >>> bifoldl1 (+) (BiList [] [])
-- *** Exception: bifoldl1: empty structure
-- ...
--
bifoldl1 :: Bifoldable t => (a -> a -> a) -> t a a -> a
-- | Left associative monadic bifold over a structure.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bifoldlM (\a b -> print b >> pure a) (\a c -> print (show c) >> pure a) 42 ("Hello", True)
-- "Hello"
-- "True"
-- 42
--
--
--
-- >>> bifoldlM (\a b -> print b >> pure a) (\a c -> print (show c) >> pure a) 42 (Right True)
-- "True"
-- 42
--
--
--
-- >>> bifoldlM (\a b -> print b >> pure a) (\a c -> print (show c) >> pure a) 42 (Left "Hello")
-- "Hello"
-- 42
--
bifoldlM :: (Bifoldable t, Monad m) => (a -> b -> m a) -> (a -> c -> m a) -> a -> t b c -> m a
-- | As bifoldr, but strict in the result of the reduction functions
-- at each step.
bifoldr' :: Bifoldable t => (a -> c -> c) -> (b -> c -> c) -> c -> t a b -> c
-- | A variant of bifoldr that has no base case, and thus may only
-- be applied to non-empty structures.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bifoldr1 (+) (5, 7)
-- 12
--
--
--
-- >>> bifoldr1 (+) (Right 7)
-- 7
--
--
--
-- >>> bifoldr1 (+) (Left 5)
-- 5
--
--
--
-- > bifoldr1 (+) (BiList [1, 2] [3, 4])
-- 10 -- 1 + (2 + (3 + 4))
--
--
--
-- >>> bifoldr1 (+) (BiList [1, 2] [])
-- 3
--
--
-- On empty structures, this function throws an exception:
--
--
-- >>> bifoldr1 (+) (BiList [] [])
-- *** Exception: bifoldr1: empty structure
-- ...
--
bifoldr1 :: Bifoldable t => (a -> a -> a) -> t a a -> a
-- | Right associative monadic bifold over a structure.
bifoldrM :: (Bifoldable t, Monad m) => (a -> c -> m c) -> (b -> c -> m c) -> c -> t a b -> m c
-- | As bitraverse_, but with the structure as the primary argument.
-- For a version that doesn't ignore the results, see bifor.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bifor_ ("Hello", True) print (print . show)
-- "Hello"
-- "True"
--
--
--
-- >>> bifor_ (Right True) print (print . show)
-- "True"
--
--
--
-- >>> bifor_ (Left "Hello") print (print . show)
-- "Hello"
--
bifor_ :: (Bifoldable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f ()
-- | Returns the size/length of a finite structure as an Int.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bilength (True, 42)
-- 2
--
--
--
-- >>> bilength (Right 42)
-- 1
--
--
--
-- >>> bilength (BiList [1,2,3] [4,5])
-- 5
--
--
--
-- >>> bilength (BiList [] [])
-- 0
--
--
-- On infinite structures, this function hangs:
--
--
-- > bilength (BiList [1..] [])
-- * Hangs forever *
--
bilength :: Bifoldable t => t a b -> Int
-- | The largest element of a non-empty structure.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bimaximum (42, 17)
-- 42
--
--
--
-- >>> bimaximum (Right 42)
-- 42
--
--
--
-- >>> bimaximum (BiList [13, 29, 4] [18, 1, 7])
-- 29
--
--
--
-- >>> bimaximum (BiList [13, 29, 4] [])
-- 29
--
--
-- On empty structures, this function throws an exception:
--
--
-- >>> bimaximum (BiList [] [])
-- *** Exception: bimaximum: empty structure
-- ...
--
bimaximum :: (Bifoldable t, Ord a) => t a a -> a
-- | The largest element of a non-empty structure with respect to the given
-- comparison function.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bimaximumBy compare (42, 17)
-- 42
--
--
--
-- >>> bimaximumBy compare (Left 17)
-- 17
--
--
--
-- >>> bimaximumBy compare (BiList [42, 17, 23] [-5, 18])
-- 42
--
--
-- On empty structures, this function throws an exception:
--
--
-- >>> bimaximumBy compare (BiList [] [])
-- *** Exception: bifoldr1: empty structure
-- ...
--
bimaximumBy :: Bifoldable t => (a -> a -> Ordering) -> t a a -> a
-- | The least element of a non-empty structure.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> biminimum (42, 17)
-- 17
--
--
--
-- >>> biminimum (Right 42)
-- 42
--
--
--
-- >>> biminimum (BiList [13, 29, 4] [18, 1, 7])
-- 1
--
--
--
-- >>> biminimum (BiList [13, 29, 4] [])
-- 4
--
--
-- On empty structures, this function throws an exception:
--
--
-- >>> biminimum (BiList [] [])
-- *** Exception: biminimum: empty structure
-- ...
--
biminimum :: (Bifoldable t, Ord a) => t a a -> a
-- | The least element of a non-empty structure with respect to the given
-- comparison function.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> biminimumBy compare (42, 17)
-- 17
--
--
--
-- >>> biminimumBy compare (Left 17)
-- 17
--
--
--
-- >>> biminimumBy compare (BiList [42, 17, 23] [-5, 18])
-- -5
--
--
-- On empty structures, this function throws an exception:
--
--
-- >>> biminimumBy compare (BiList [] [])
-- *** Exception: bifoldr1: empty structure
-- ...
--
biminimumBy :: Bifoldable t => (a -> a -> Ordering) -> t a a -> a
-- | binotElem is the negation of bielem.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> binotElem 42 (17, 42)
-- False
--
--
--
-- >>> binotElem 42 (17, 43)
-- True
--
--
--
-- >>> binotElem 42 (Left 42)
-- False
--
--
--
-- >>> binotElem 42 (Right 13)
-- True
--
--
--
-- >>> binotElem 42 (BiList [1..5] [1..100])
-- False
--
--
--
-- >>> binotElem 42 (BiList [1..5] [1..41])
-- True
--
binotElem :: (Bifoldable t, Eq a) => a -> t a a -> Bool
-- | Test whether the structure is empty.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> binull (18, 42)
-- False
--
--
--
-- >>> binull (Right 42)
-- False
--
--
--
-- >>> binull (BiList [] [])
-- True
--
binull :: Bifoldable t => t a b -> Bool
-- | bior returns the disjunction of a container of Bools. For the
-- result to be False, the container must be finite; True,
-- however, results from a True value finitely far from the left
-- end.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bior (True, False)
-- True
--
--
--
-- >>> bior (False, False)
-- False
--
--
--
-- >>> bior (Left True)
-- True
--
--
-- Empty structures yield False:
--
--
-- >>> bior (BiList [] [])
-- False
--
--
-- A True value finitely far from the left end yields True
-- (short circuit):
--
--
-- >>> bior (BiList [False, False, True, False] (repeat False))
-- True
--
--
-- A True value infinitely far from the left end hangs:
--
--
-- > bior (BiList (repeat False) [True])
-- * Hangs forever *
--
--
-- An infinitely False value hangs:
--
--
-- > bior (BiList (repeat False) [])
-- * Hangs forever *
--
bior :: Bifoldable t => t Bool Bool -> Bool
-- | The biproduct function computes the product of the numbers of a
-- structure.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> biproduct (42, 17)
-- 714
--
--
--
-- >>> biproduct (Right 42)
-- 42
--
--
--
-- >>> biproduct (BiList [13, 29, 4] [18, 1, 7])
-- 190008
--
--
--
-- >>> biproduct (BiList [13, 29, 4] [])
-- 1508
--
--
--
-- >>> biproduct (BiList [] [])
-- 1
--
biproduct :: (Bifoldable t, Num a) => t a a -> a
-- | Evaluate each action in the structure from left to right, and ignore
-- the results. For a version that doesn't ignore the results, see
-- bisequence.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bisequence_ (print "Hello", print "World")
-- "Hello"
-- "World"
--
--
--
-- >>> bisequence_ (Left (print "Hello"))
-- "Hello"
--
--
--
-- >>> bisequence_ (Right (print "World"))
-- "World"
--
bisequence_ :: (Bifoldable t, Applicative f) => t (f a) (f b) -> f ()
-- | The bisum function computes the sum of the numbers of a
-- structure.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bisum (42, 17)
-- 59
--
--
--
-- >>> bisum (Right 42)
-- 42
--
--
--
-- >>> bisum (BiList [13, 29, 4] [18, 1, 7])
-- 72
--
--
--
-- >>> bisum (BiList [13, 29, 4] [])
-- 46
--
--
--
-- >>> bisum (BiList [] [])
-- 0
--
bisum :: (Bifoldable t, Num a) => t a a -> a
-- | Map each element of a structure using one of two actions, evaluate
-- these actions from left to right, and ignore the results. For a
-- version that doesn't ignore the results, see bitraverse.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bitraverse_ print (print . show) ("Hello", True)
-- "Hello"
-- "True"
--
--
--
-- >>> bitraverse_ print (print . show) (Right True)
-- "True"
--
--
--
-- >>> bitraverse_ print (print . show) (Left "Hello")
-- "Hello"
--
bitraverse_ :: (Bifoldable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f ()
-- | Bifoldable identifies foldable structures with two different
-- varieties of elements (as opposed to Foldable, which has one
-- variety of element). Common examples are Either and
-- (,):
--
--
-- instance Bifoldable Either where
-- bifoldMap f _ (Left a) = f a
-- bifoldMap _ g (Right b) = g b
--
-- instance Bifoldable (,) where
-- bifoldr f g z (a, b) = f a (g b z)
--
--
-- Some examples below also use the following BiList to showcase empty
-- Bifoldable behaviors when relevant (Either and (,)
-- containing always exactly resp. 1 and 2 elements):
--
--
-- data BiList a b = BiList [a] [b]
--
-- instance Bifoldable BiList where
-- bifoldr f g z (BiList as bs) = foldr f (foldr g z bs) as
--
--
-- A minimal Bifoldable definition consists of either
-- bifoldMap or bifoldr. When defining more than this
-- minimal set, one should ensure that the following identities hold:
--
--
-- bifold ≡ bifoldMap id id
-- bifoldMap f g ≡ bifoldr (mappend . f) (mappend . g) mempty
-- bifoldr f g z t ≡ appEndo (bifoldMap (Endo . f) (Endo . g) t) z
--
--
-- If the type is also a Bifunctor instance, it should satisfy:
--
--
-- bifoldMap f g ≡ bifold . bimap f g
--
--
-- which implies that
--
--
-- bifoldMap f g . bimap h i ≡ bifoldMap (f . h) (g . i)
--
class Bifoldable (p :: TYPE LiftedRep -> TYPE LiftedRep -> Type)
-- | Combines the elements of a structure using a monoid.
--
--
-- bifold ≡ bifoldMap id id
--
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bifold (Right [1, 2, 3])
-- [1,2,3]
--
--
--
-- >>> bifold (Left [5, 6])
-- [5,6]
--
--
--
-- >>> bifold ([1, 2, 3], [4, 5])
-- [1,2,3,4,5]
--
--
--
-- >>> bifold (Product 6, Product 7)
-- Product {getProduct = 42}
--
--
--
-- >>> bifold (Sum 6, Sum 7)
-- Sum {getSum = 13}
--
bifold :: (Bifoldable p, Monoid m) => p m m -> m
-- | Combines the elements of a structure, given ways of mapping them to a
-- common monoid.
--
--
-- bifoldMap f g ≡ bifoldr (mappend . f) (mappend . g) mempty
--
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bifoldMap (take 3) (fmap digitToInt) ([1..], "89")
-- [1,2,3,8,9]
--
--
--
-- >>> bifoldMap (take 3) (fmap digitToInt) (Left [1..])
-- [1,2,3]
--
--
--
-- >>> bifoldMap (take 3) (fmap digitToInt) (Right "89")
-- [8,9]
--
bifoldMap :: (Bifoldable p, Monoid m) => (a -> m) -> (b -> m) -> p a b -> m
-- | Combines the elements of a structure in a right associative manner.
-- Given a hypothetical function toEitherList :: p a b -> [Either
-- a b] yielding a list of all elements of a structure in order, the
-- following would hold:
--
--
-- bifoldr f g z ≡ foldr (either f g) z . toEitherList
--
--
-- Examples
--
-- Basic usage:
--
--
-- > bifoldr (+) (*) 3 (5, 7)
-- 26 -- 5 + (7 * 3)
--
-- > bifoldr (+) (*) 3 (7, 5)
-- 22 -- 7 + (5 * 3)
--
-- > bifoldr (+) (*) 3 (Right 5)
-- 15 -- 5 * 3
--
-- > bifoldr (+) (*) 3 (Left 5)
-- 8 -- 5 + 3
--
bifoldr :: Bifoldable p => (a -> c -> c) -> (b -> c -> c) -> c -> p a b -> c
-- | Combines the elements of a structure in a left associative manner.
-- Given a hypothetical function toEitherList :: p a b -> [Either
-- a b] yielding a list of all elements of a structure in order, the
-- following would hold:
--
--
-- bifoldl f g z
-- ≡ foldl (acc -> either (f acc) (g acc)) z . toEitherList
--
--
-- Note that if you want an efficient left-fold, you probably want to use
-- bifoldl' instead of bifoldl. The reason is that the
-- latter does not force the "inner" results, resulting in a thunk chain
-- which then must be evaluated from the outside-in.
--
-- Examples
--
-- Basic usage:
--
--
-- > bifoldl (+) (*) 3 (5, 7)
-- 56 -- (5 + 3) * 7
--
-- > bifoldl (+) (*) 3 (7, 5)
-- 50 -- (7 + 3) * 5
--
-- > bifoldl (+) (*) 3 (Right 5)
-- 15 -- 5 * 3
--
-- > bifoldl (+) (*) 3 (Left 5)
-- 8 -- 5 + 3
--
bifoldl :: Bifoldable p => (c -> a -> c) -> (c -> b -> c) -> c -> p a b -> c
-- | bifor is bitraverse with the structure as the first
-- argument. For a version that ignores the results, see bifor_.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bifor (Left []) listToMaybe (find even)
-- Nothing
--
--
--
-- >>> bifor (Left [1, 2, 3]) listToMaybe (find even)
-- Just (Left 1)
--
--
--
-- >>> bifor (Right [4, 5]) listToMaybe (find even)
-- Just (Right 4)
--
--
--
-- >>> bifor ([1, 2, 3], [4, 5]) listToMaybe (find even)
-- Just (1,4)
--
--
--
-- >>> bifor ([], [4, 5]) listToMaybe (find even)
-- Nothing
--
bifor :: (Bitraversable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f (t c d)
-- | The bimapAccumL function behaves like a combination of
-- bimap and bifoldl; it traverses a structure from left to
-- right, threading a state of type a and using the given
-- actions to compute new elements for the structure.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bimapAccumL (\acc bool -> (acc + 1, show bool)) (\acc string -> (acc * 2, reverse string)) 3 (True, "foo")
-- (8,("True","oof"))
--
bimapAccumL :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e)
-- | The bimapAccumR function behaves like a combination of
-- bimap and bifoldr; it traverses a structure from right
-- to left, threading a state of type a and using the given
-- actions to compute new elements for the structure.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bimapAccumR (\acc bool -> (acc + 1, show bool)) (\acc string -> (acc * 2, reverse string)) 3 (True, "foo")
-- (7,("True","oof"))
--
bimapAccumR :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e)
-- | Sequences all the actions in a structure, building a new structure
-- with the same shape using the results of the actions. For a version
-- that ignores the results, see bisequence_.
--
--
-- bisequence ≡ bitraverse id id
--
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bisequence (Just 4, Nothing)
-- Nothing
--
--
--
-- >>> bisequence (Just 4, Just 5)
-- Just (4,5)
--
--
--
-- >>> bisequence ([1, 2, 3], [4, 5])
-- [(1,4),(1,5),(2,4),(2,5),(3,4),(3,5)]
--
bisequence :: (Bitraversable t, Applicative f) => t (f a) (f b) -> f (t a b)
-- | Bitraversable identifies bifunctorial data structures whose
-- elements can be traversed in order, performing Applicative or
-- Monad actions at each element, and collecting a result
-- structure with the same shape.
--
-- As opposed to Traversable data structures, which have one
-- variety of element on which an action can be performed,
-- Bitraversable data structures have two such varieties of
-- elements.
--
-- A definition of bitraverse must satisfy the following laws:
--
--
--
-- where an applicative transformation is a function
--
--
-- t :: (Applicative f, Applicative g) => f a -> g a
--
--
-- preserving the Applicative operations:
--
--
-- t (pure x) = pure x
-- t (f <*> x) = t f <*> t x
--
--
-- and the identity functor Identity and composition functors
-- Compose are from Data.Functor.Identity and
-- Data.Functor.Compose.
--
-- Some simple examples are Either and (,):
--
--
-- instance Bitraversable Either where
-- bitraverse f _ (Left x) = Left <$> f x
-- bitraverse _ g (Right y) = Right <$> g y
--
-- instance Bitraversable (,) where
-- bitraverse f g (x, y) = (,) <$> f x <*> g y
--
--
-- Bitraversable relates to its superclasses in the following
-- ways:
--
--
-- bimap f g ≡ runIdentity . bitraverse (Identity . f) (Identity . g)
-- bifoldMap f g = getConst . bitraverse (Const . f) (Const . g)
--
--
-- These are available as bimapDefault and bifoldMapDefault
-- respectively.
class (Bifunctor t, Bifoldable t) => Bitraversable (t :: Type -> Type -> Type)
-- | Evaluates the relevant functions at each element in the structure,
-- running the action, and builds a new structure with the same shape,
-- using the results produced from sequencing the actions.
--
--
-- bitraverse f g ≡ bisequenceA . bimap f g
--
--
-- For a version that ignores the results, see bitraverse_.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bitraverse listToMaybe (find odd) (Left [])
-- Nothing
--
--
--
-- >>> bitraverse listToMaybe (find odd) (Left [1, 2, 3])
-- Just (Left 1)
--
--
--
-- >>> bitraverse listToMaybe (find odd) (Right [4, 5])
-- Just (Right 5)
--
--
--
-- >>> bitraverse listToMaybe (find odd) ([1, 2, 3], [4, 5])
-- Just (1,5)
--
--
--
-- >>> bitraverse listToMaybe (find odd) ([], [4, 5])
-- Nothing
--
bitraverse :: (Bitraversable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d)
-- | Uninhabited data type
data Void
-- | Monads that also support choice and failure.
class (Alternative m, Monad m) => MonadPlus (m :: Type -> Type)
-- | The identity of mplus. It should also satisfy the equations
--
--
-- mzero >>= f = mzero
-- v >> mzero = mzero
--
--
-- The default definition is
--
--
-- mzero = empty
--
mzero :: MonadPlus m => m a
-- | An associative operation. The default definition is
--
--
-- mplus = (<|>)
--
mplus :: MonadPlus m => m a -> m a -> m a
-- | A monoid on applicative functors.
--
-- If defined, some and many should be the least solutions
-- of the equations:
--
--
class Applicative f => Alternative (f :: Type -> Type)
-- | An associative binary operation
(<|>) :: Alternative f => f a -> f a -> f a
-- | One or more.
some :: Alternative f => f a -> f [a]
-- | Zero or more.
many :: Alternative f => f a -> f [a]
infixl 3 <|>
-- | Map each element of a structure to a monadic action, evaluate these
-- actions from left to right, and ignore the results. For a version that
-- doesn't ignore the results see mapM.
--
-- mapM_ is just like traverse_, but specialised to monadic
-- actions.
mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m ()
-- | forM_ is mapM_ with its arguments flipped. For a version
-- that doesn't ignore the results see forM.
--
-- forM_ is just like for_, but specialised to monadic
-- actions.
forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m ()
-- | A bifunctor is a type constructor that takes two type arguments and is
-- a functor in both arguments. That is, unlike with
-- Functor, a type constructor such as Either does not need
-- to be partially applied for a Bifunctor instance, and the
-- methods in this class permit mapping functions over the Left
-- value or the Right value, or both at the same time.
--
-- Formally, the class Bifunctor represents a bifunctor from
-- Hask -> Hask.
--
-- Intuitively it is a bifunctor where both the first and second
-- arguments are covariant.
--
-- You can define a Bifunctor by either defining bimap or
-- by defining both first and second.
--
-- If you supply bimap, you should ensure that:
--
--
-- bimap id id ≡ id
--
--
-- If you supply first and second, ensure:
--
--
-- first id ≡ id
-- second id ≡ id
--
--
-- If you supply both, you should also ensure:
--
--
-- bimap f g ≡ first f . second g
--
--
-- These ensure by parametricity:
--
--
-- bimap (f . g) (h . i) ≡ bimap f h . bimap g i
-- first (f . g) ≡ first f . first g
-- second (f . g) ≡ second f . second g
--
class Bifunctor (p :: Type -> Type -> Type)
-- | Map over both arguments at the same time.
--
--
-- bimap f g ≡ first f . second g
--
--
-- Examples
--
--
-- >>> bimap toUpper (+1) ('j', 3)
-- ('J',4)
--
--
--
-- >>> bimap toUpper (+1) (Left 'j')
-- Left 'J'
--
--
--
-- >>> bimap toUpper (+1) (Right 3)
-- Right 4
--
bimap :: Bifunctor p => (a -> b) -> (c -> d) -> p a c -> p b d
-- | Map covariantly over the first argument.
--
--
-- first f ≡ bimap f id
--
--
-- Examples
--
--
-- >>> first toUpper ('j', 3)
-- ('J',3)
--
--
--
-- >>> first toUpper (Left 'j')
-- Left 'J'
--
first :: Bifunctor p => (a -> b) -> p a c -> p b c
-- | Map covariantly over the second argument.
--
--
-- second ≡ bimap id
--
--
-- Examples
--
--
-- >>> second (+1) ('j', 3)
-- ('j',4)
--
--
--
-- >>> second (+1) (Right 3)
-- Right 4
--
second :: Bifunctor p => (b -> c) -> p a b -> p a c
stdin :: Handle
-- | A ThreadId is an abstract type representing a handle to a
-- thread. ThreadId is an instance of Eq, Ord and
-- Show, where the Ord instance implements an arbitrary
-- total ordering over ThreadIds. The Show instance lets
-- you convert an arbitrary-valued ThreadId to string form;
-- showing a ThreadId value is occasionally useful when debugging
-- or diagnosing the behaviour of a concurrent program.
--
-- Note: in GHC, if you have a ThreadId, you essentially
-- have a pointer to the thread itself. This means the thread itself
-- can't be garbage collected until you drop the ThreadId. This
-- misfeature will hopefully be corrected at a later date.
data ThreadId
-- | A version of waitBoth that can be used inside an STM
-- transaction.
waitBothSTM :: Async a -> Async b -> STM (a, b)
-- | A version of waitEither_ that can be used inside an STM
-- transaction.
waitEitherSTM_ :: Async a -> Async b -> STM ()
-- | A version of waitEither that can be used inside an STM
-- transaction.
waitEitherSTM :: Async a -> Async b -> STM (Either a b)
-- | A version of waitEitherCatch that can be used inside an STM
-- transaction.
waitEitherCatchSTM :: Async a -> Async b -> STM (Either (Either SomeException a) (Either SomeException b))
-- | A version of waitAny that can be used inside an STM
-- transaction.
waitAnySTM :: [Async a] -> STM (Async a, a)
-- | A version of waitAnyCatch that can be used inside an STM
-- transaction.
waitAnyCatchSTM :: [Async a] -> STM (Async a, Either SomeException a)
-- | A version of poll that can be used inside an STM transaction.
pollSTM :: Async a -> STM (Maybe (Either SomeException a))
-- | A version of waitCatch that can be used inside an STM
-- transaction.
waitCatchSTM :: Async a -> STM (Either SomeException a)
-- | A version of wait that can be used inside an STM transaction.
waitSTM :: Async a -> STM a
-- | An asynchronous action spawned by async or withAsync.
-- Asynchronous actions are executed in a separate thread, and operations
-- are provided for waiting for asynchronous actions to complete and
-- obtaining their results (see e.g. wait).
data Async a
-- | The exception thrown by cancel to terminate a thread.
data AsyncCancelled
AsyncCancelled :: AsyncCancelled
-- | Since Void values logically don't exist, this witnesses the
-- logical reasoning tool of "ex falso quodlibet".
--
--
-- >>> let x :: Either Void Int; x = Right 5
--
-- >>> :{
-- case x of
-- Right r -> r
-- Left l -> absurd l
-- :}
-- 5
--
absurd :: Void -> a
-- | Chan is an abstract type representing an unbounded FIFO
-- channel.
data Chan a
-- | QSem is a quantity semaphore in which the resource is acquired
-- and released in units of one. It provides guaranteed FIFO ordering for
-- satisfying blocked waitQSem calls.
--
-- The pattern
--
--
-- bracket_ waitQSem signalQSem (...)
--
--
-- is safe; it never loses a unit of the resource.
data QSem
-- | QSemN is a quantity semaphore in which the resource is acquired
-- and released in units of one. It provides guaranteed FIFO ordering for
-- satisfying blocked waitQSemN calls.
--
-- The pattern
--
--
-- bracket_ (waitQSemN n) (signalQSemN n) (...)
--
--
-- is safe; it never loses any of the resource.
data QSemN
-- | for is traverse with its arguments flipped. For a
-- version that ignores the results see for_.
for :: (Traversable t, Applicative f) => t a -> (a -> f b) -> f (t b)
-- | One or none.
--
-- It is useful for modelling any computation that is allowed to fail.
--
-- Examples
--
-- Using the Alternative instance of Control.Monad.Except,
-- the following functions:
--
--
-- >>> import Control.Monad.Except
--
--
--
-- >>> canFail = throwError "it failed" :: Except String Int
--
-- >>> final = return 42 :: Except String Int
--
--
-- Can be combined by allowing the first function to fail:
--
--
-- >>> runExcept $ canFail *> final
-- Left "it failed"
--
-- >>> runExcept $ optional canFail *> final
-- Right 42
--
optional :: Alternative f => f a -> f (Maybe a)
-- | The basic arrow class.
--
-- Instances should satisfy the following laws:
--
--
--
-- where
--
--
-- assoc ((a,b),c) = (a,(b,c))
--
--
-- The other combinators have sensible default definitions, which may be
-- overridden for efficiency.
class Category a => Arrow (a :: TYPE LiftedRep -> TYPE LiftedRep -> Type)
-- | Split the input between the two argument arrows and combine their
-- output. Note that this is in general not a functor.
--
-- The default definition may be overridden with a more efficient version
-- if desired.
(***) :: Arrow a => a b c -> a b' c' -> a (b, b') (c, c')
-- | Fanout: send the input to both argument arrows and combine their
-- output.
--
-- The default definition may be overridden with a more efficient version
-- if desired.
(&&&) :: Arrow a => a b c -> a b c' -> a b (c, c')
infixr 3 ***
infixr 3 &&&
-- | Shared memory locations that support atomic memory transactions.
data TVar a
-- | A monad supporting atomic memory transactions.
data STM a
-- | Write the supplied value into a TVar.
writeTVar :: TVar a -> a -> STM ()
-- | Return the current value stored in a TVar.
readTVar :: TVar a -> STM a
-- | Compose two alternative STM actions (GHC only).
--
-- If the first action completes without retrying then it forms the
-- result of the orElse. Otherwise, if the first action retries,
-- then the second action is tried in its place. If both actions retry
-- then the orElse as a whole retries.
orElse :: STM a -> STM a -> STM a
-- | Create a new TVar holding a value supplied
newTVar :: a -> STM (TVar a)
-- | Superclass for asynchronous exceptions.
data SomeAsyncException
SomeAsyncException :: e -> SomeAsyncException
-- | Defines the exit codes that a program can return.
data ExitCode
-- | indicates successful termination;
ExitSuccess :: ExitCode
-- | indicates program failure with an exit code. The exact interpretation
-- of the code is operating-system dependent. In particular, some values
-- may be prohibited (e.g. 0 on a POSIX-compliant system).
ExitFailure :: Int -> ExitCode
asyncExceptionToException :: Exception e => e -> SomeException
asyncExceptionFromException :: Exception e => SomeException -> Maybe e
-- | Three kinds of buffering are supported: line-buffering,
-- block-buffering or no-buffering. These modes have the following
-- effects. For output, items are written out, or flushed, from
-- the internal buffer according to the buffer mode:
--
--
-- - line-buffering: the entire output buffer is flushed
-- whenever a newline is output, the buffer overflows, a hFlush is
-- issued, or the handle is closed.
-- - block-buffering: the entire buffer is written out whenever
-- it overflows, a hFlush is issued, or the handle is closed.
-- - no-buffering: output is written immediately, and never
-- stored in the buffer.
--
--
-- An implementation is free to flush the buffer more frequently, but not
-- less frequently, than specified above. The output buffer is emptied as
-- soon as it has been written out.
--
-- Similarly, input occurs according to the buffer mode for the handle:
--
--
-- - line-buffering: when the buffer for the handle is not
-- empty, the next item is obtained from the buffer; otherwise, when the
-- buffer is empty, characters up to and including the next newline
-- character are read into the buffer. No characters are available until
-- the newline character is available or the buffer is full.
-- - block-buffering: when the buffer for the handle becomes
-- empty, the next block of data is read into the buffer.
-- - no-buffering: the next input item is read and returned. The
-- hLookAhead operation implies that even a no-buffered handle may
-- require a one-character buffer.
--
--
-- The default buffering mode when a handle is opened is
-- implementation-dependent and may depend on the file system object
-- which is attached to that handle. For most implementations, physical
-- files will normally be block-buffered and terminals will normally be
-- line-buffered.
data BufferMode
-- | buffering is disabled if possible.
NoBuffering :: BufferMode
-- | line-buffering should be enabled if possible.
LineBuffering :: BufferMode
-- | block-buffering should be enabled if possible. The size of the buffer
-- is n items if the argument is Just n and is
-- otherwise implementation-dependent.
BlockBuffering :: Maybe Int -> BufferMode
-- | A mode that determines the effect of hSeek hdl mode i.
data SeekMode
-- | the position of hdl is set to i.
AbsoluteSeek :: SeekMode
-- | the position of hdl is set to offset i from the
-- current position.
RelativeSeek :: SeekMode
-- | the position of hdl is set to offset i from the end
-- of the file.
SeekFromEnd :: SeekMode
-- | Exceptions that occur in the IO monad. An
-- IOException records a more specific error type, a descriptive
-- string and maybe the handle that was used when the error was flagged.
data IOException
-- | The Const functor.
newtype Const a (b :: k)
Const :: a -> Const a (b :: k)
[getConst] :: Const a (b :: k) -> a
-- | Map each element of a structure to an Applicative action,
-- evaluate these actions from left to right, and ignore the results. For
-- a version that doesn't ignore the results see traverse.
--
-- traverse_ is just like mapM_, but generalised to
-- Applicative actions.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> traverse_ print ["Hello", "world", "!"]
-- "Hello"
-- "world"
-- "!"
--
traverse_ :: (Foldable t, Applicative f) => (a -> f b) -> t a -> f ()
-- | Evaluate each action in the structure from left to right, and ignore
-- the results. For a version that doesn't ignore the results see
-- sequenceA.
--
-- sequenceA_ is just like sequence_, but generalised to
-- Applicative actions.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> sequenceA_ [print "Hello", print "world", print "!"]
-- "Hello"
-- "world"
-- "!"
--
sequenceA_ :: (Foldable t, Applicative f) => t (f a) -> f ()
-- | for_ is traverse_ with its arguments flipped. For a
-- version that doesn't ignore the results see for. This is
-- forM_ generalised to Applicative actions.
--
-- for_ is just like forM_, but generalised to
-- Applicative actions.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> for_ [1..4] print
-- 1
-- 2
-- 3
-- 4
--
for_ :: (Foldable t, Applicative f) => t a -> (a -> f b) -> f ()
-- | The sum of a collection of actions, generalizing concat.
--
-- asum is just like msum, but generalised to
-- Alternative.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> asum [Just "Hello", Nothing, Just "World"]
-- Just "Hello"
--
asum :: (Foldable t, Alternative f) => t (f a) -> f a
-- | The Down type allows you to reverse sort order conveniently. A
-- value of type Down a contains a value of type
-- a (represented as Down a).
--
-- If a has an Ord instance associated with it
-- then comparing two values thus wrapped will give you the opposite of
-- their normal sort order. This is particularly useful when sorting in
-- generalised list comprehensions, as in: then sortWith by
-- Down x.
--
--
-- >>> compare True False
-- GT
--
--
--
-- >>> compare (Down True) (Down False)
-- LT
--
--
-- If a has a Bounded instance then the wrapped
-- instance also respects the reversed ordering by exchanging the values
-- of minBound and maxBound.
--
--
-- >>> minBound :: Int
-- -9223372036854775808
--
--
--
-- >>> minBound :: Down Int
-- Down 9223372036854775807
--
--
-- All other instances of Down a behave as they do for
-- a.
newtype Down a
Down :: a -> Down a
[getDown] :: Down a -> a
-- |
-- comparing p x y = compare (p x) (p y)
--
--
-- Useful combinator for use in conjunction with the xxxBy
-- family of functions from Data.List, for example:
--
--
-- ... sortBy (comparing fst) ...
--
comparing :: Ord a => (b -> a) -> b -> b -> Ordering
-- | The member functions of this class facilitate writing values of
-- primitive types to raw memory (which may have been allocated with the
-- above mentioned routines) and reading values from blocks of raw
-- memory. The class, furthermore, includes support for computing the
-- storage requirements and alignment restrictions of storable types.
--
-- Memory addresses are represented as values of type Ptr
-- a, for some a which is an instance of class
-- Storable. The type argument to Ptr helps provide some
-- valuable type safety in FFI code (you can't mix pointers of different
-- types without an explicit cast), while helping the Haskell type system
-- figure out which marshalling method is needed for a given pointer.
--
-- All marshalling between Haskell and a foreign language ultimately
-- boils down to translating Haskell data structures into the binary
-- representation of a corresponding data structure of the foreign
-- language and vice versa. To code this marshalling in Haskell, it is
-- necessary to manipulate primitive data types stored in unstructured
-- memory blocks. The class Storable facilitates this manipulation
-- on all types for which it is instantiated, which are the standard
-- basic types of Haskell, the fixed size Int types
-- (Int8, Int16, Int32, Int64), the fixed
-- size Word types (Word8, Word16, Word32,
-- Word64), StablePtr, all types from
-- Foreign.C.Types, as well as Ptr.
class Storable a
-- | Parse a string using the Read instance. Succeeds if there is
-- exactly one valid result.
--
--
-- >>> readMaybe "123" :: Maybe Int
-- Just 123
--
--
--
-- >>> readMaybe "hello" :: Maybe Int
-- Nothing
--
readMaybe :: Read a => String -> Maybe a
-- | Extracts from a list of Either all the Right elements.
-- All the Right elements are extracted in order.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--
-- >>> rights list
-- [3,7]
--
rights :: [Either a b] -> [b]
-- | Partitions a list of Either into two lists. All the Left
-- elements are extracted, in order, to the first component of the
-- output. Similarly the Right elements are extracted to the
-- second component of the output.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--
-- >>> partitionEithers list
-- (["foo","bar","baz"],[3,7])
--
--
-- The pair returned by partitionEithers x should be the
-- same pair as (lefts x, rights x):
--
--
-- >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--
-- >>> partitionEithers list == (lefts list, rights list)
-- True
--
partitionEithers :: [Either a b] -> ([a], [b])
-- | Extracts from a list of Either all the Left elements.
-- All the Left elements are extracted in order.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--
-- >>> lefts list
-- ["foo","bar","baz"]
--
lefts :: [Either a b] -> [a]
-- | Return True if the given value is a Right-value,
-- False otherwise.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> isRight (Left "foo")
-- False
--
-- >>> isRight (Right 3)
-- True
--
--
-- Assuming a Left value signifies some sort of error, we can use
-- isRight to write a very simple reporting function that only
-- outputs "SUCCESS" when a computation has succeeded.
--
-- This example shows how isRight might be used to avoid pattern
-- matching when one does not care about the value contained in the
-- constructor:
--
--
-- >>> import Control.Monad ( when )
--
-- >>> let report e = when (isRight e) $ putStrLn "SUCCESS"
--
-- >>> report (Left "parse error")
--
-- >>> report (Right 1)
-- SUCCESS
--
isRight :: Either a b -> Bool
-- | Return True if the given value is a Left-value,
-- False otherwise.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> isLeft (Left "foo")
-- True
--
-- >>> isLeft (Right 3)
-- False
--
--
-- Assuming a Left value signifies some sort of error, we can use
-- isLeft to write a very simple error-reporting function that
-- does absolutely nothing in the case of success, and outputs "ERROR" if
-- any error occurred.
--
-- This example shows how isLeft might be used to avoid pattern
-- matching when one does not care about the value contained in the
-- constructor:
--
--
-- >>> import Control.Monad ( when )
--
-- >>> let report e = when (isLeft e) $ putStrLn "ERROR"
--
-- >>> report (Right 1)
--
-- >>> report (Left "parse error")
-- ERROR
--
isLeft :: Either a b -> Bool
-- | Return the contents of a Right-value or a default value
-- otherwise.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> fromRight 1 (Right 3)
-- 3
--
-- >>> fromRight 1 (Left "foo")
-- 1
--
fromRight :: b -> Either a b -> b
-- | Return the contents of a Left-value or a default value
-- otherwise.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> fromLeft 1 (Left 3)
-- 3
--
-- >>> fromLeft 1 (Right "foo")
-- 1
--
fromLeft :: a -> Either a b -> a
-- | A class for categories. Instances should satisfy the laws
--
--
-- - Right identity f . id = f
-- - Left identity id . f = f
-- - Associativity f . (g . h) = (f .
-- g) . h
--
class Category (cat :: k -> k -> Type)
-- | Left-to-right composition
(>>>) :: forall {k} cat (a :: k) (b :: k) (c :: k). Category cat => cat a b -> cat b c -> cat a c
infixr 1 >>>
-- | See openFile
data IOMode
ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode
ReadWriteMode :: IOMode
-- | Reverse order of bytes in Word64.
byteSwap64 :: Word64 -> Word64
-- | Reverse order of bytes in Word32.
byteSwap32 :: Word32 -> Word32
-- | Reverse order of bytes in Word16.
byteSwap16 :: Word16 -> Word16
-- | Return the value computed by a state thread. The forall
-- ensures that the internal state used by the ST computation is
-- inaccessible to the rest of the program.
runST :: (forall s. () => ST s a) -> a
-- | Case analysis for the Bool type. bool x y p
-- evaluates to x when p is False, and evaluates
-- to y when p is True.
--
-- This is equivalent to if p then y else x; that is, one can
-- think of it as an if-then-else construct with its arguments reordered.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> bool "foo" "bar" True
-- "bar"
--
-- >>> bool "foo" "bar" False
-- "foo"
--
--
-- Confirm that bool x y p and if p then y else
-- x are equivalent:
--
--
-- >>> let p = True; x = "bar"; y = "foo"
--
-- >>> bool x y p == if p then y else x
-- True
--
-- >>> let p = False
--
-- >>> bool x y p == if p then y else x
-- True
--
bool :: a -> a -> Bool -> a
-- | 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)
on :: (b -> b -> c) -> (a -> b) -> a -> a -> c
infixl 0 `on`
-- | fix f is the least fixed point of the function
-- f, i.e. the least defined x such that f x =
-- x.
--
-- For example, we can write the factorial function using direct
-- recursion as
--
--
-- >>> let fac n = if n <= 1 then 1 else n * fac (n-1) in fac 5
-- 120
--
--
-- This uses the fact that Haskell’s let introduces recursive
-- bindings. We can rewrite this definition using fix,
--
--
-- >>> fix (\rec n -> if n <= 1 then 1 else n * rec (n-1)) 5
-- 120
--
--
-- Instead of making a recursive call, we introduce a dummy parameter
-- rec; when used within fix, this parameter then refers
-- to fix’s argument, hence the recursion is reintroduced.
fix :: (a -> a) -> a
-- | Flipped version of <$.
--
-- Examples
--
-- Replace the contents of a Maybe Int with a
-- constant String:
--
--
-- >>> Nothing $> "foo"
-- Nothing
--
-- >>> Just 90210 $> "foo"
-- Just "foo"
--
--
-- Replace the contents of an Either Int
-- Int with a constant String, resulting in an
-- Either Int String:
--
--
-- >>> Left 8675309 $> "foo"
-- Left 8675309
--
-- >>> Right 8675309 $> "foo"
-- Right "foo"
--
--
-- Replace each element of a list with a constant String:
--
--
-- >>> [1,2,3] $> "foo"
-- ["foo","foo","foo"]
--
--
-- Replace the second element of a pair with a constant String:
--
--
-- >>> (1,2) $> "foo"
-- (1,"foo")
--
($>) :: Functor f => f a -> b -> f b
infixl 4 $>
-- | An MVar (pronounced "em-var") is a synchronising variable, used
-- for communication between concurrent threads. It can be thought of as
-- a box, which may be empty or full.
data MVar a
-- | Lift a ternary function to actions.
liftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d
-- | Lift a function to actions. Equivalent to Functor's fmap but
-- implemented using only Applicative's methods: `liftA f a = pure
-- f * a`
--
-- As such this function may be used to implement a Functor
-- instance from an Applicative one.
liftA :: Applicative f => (a -> b) -> f a -> f b
-- | Request a CallStack.
--
-- NOTE: The implicit parameter ?callStack :: CallStack is an
-- implementation detail and should not be considered part of the
-- CallStack API, we may decide to change the implementation in
-- the future.
type HasCallStack = ?callStack :: CallStack
-- | O(n). Convert a ShortByteString into a
-- ByteString.
fromShort :: ShortByteString -> ByteString
-- | A compact representation of a Word8 vector.
--
-- It has a lower memory overhead than a ByteString and does not
-- contribute to heap fragmentation. It can be converted to or from a
-- ByteString (at the cost of copying the string data). It
-- supports very few other operations.
--
-- It is suitable for use as an internal representation for code that
-- needs to keep many short strings in memory, but it should not
-- be used as an interchange type. That is, it should not generally be
-- used in public APIs. The ByteString type is usually more
-- suitable for use in interfaces; it is more flexible and it supports a
-- wide range of operations.
data ShortByteString
-- | O(n). Convert a ByteString into a
-- ShortByteString.
--
-- This makes a copy, so does not retain the input string.
toShort :: ByteString -> ShortByteString
-- | A class for monads in which exceptions may be thrown.
--
-- Instances should obey the following law:
--
--
-- throwM e >> x = throwM e
--
--
-- In other words, throwing an exception short-circuits the rest of the
-- monadic computation.
class Monad m => MonadThrow (m :: Type -> Type)
-- | Throw an exception. Note that this throws when this action is run in
-- the monad m, not when it is applied. It is a generalization
-- of Control.Exception's throwIO.
--
-- Should satisfy the law:
--
--
-- throwM e >> f = throwM e
--
throwM :: (MonadThrow m, Exception e) => e -> m a
-- | State token type.
type family PrimState (m :: Type -> Type)
-- | Class of monads which can perform primitive state-transformer actions.
class Monad m => PrimMonad (m :: Type -> Type) where {
-- | State token type.
type family PrimState (m :: Type -> Type);
}
-- | Execute a primitive operation.
primitive :: PrimMonad m => (State# (PrimState m) -> (# State# (PrimState m), a #)) -> m a
-- | Synchronously throw the given exception.
--
-- Note that, if you provide an exception value which is of an
-- asynchronous type, it will be wrapped up in
-- SyncExceptionWrapper. See toSyncException.
throwIO :: (MonadIO m, Exception e) => e -> m a
-- | O(n) Convert a Text into a String. Subject to
-- fusion.
unpack :: Text -> String
-- | Encode text using UTF-8 encoding.
encodeUtf8 :: Text -> ByteString
-- | O(n) Convert a String into a Text. Subject to
-- fusion. Performs replacement on invalid scalar values.
pack :: String -> Text
-- | Monads which allow their actions to be run in IO.
--
-- While MonadIO allows an IO action to be lifted into
-- another monad, this class captures the opposite concept: allowing you
-- to capture the monadic context. Note that, in order to meet the laws
-- given below, the intuition is that a monad must have no monadic state,
-- but may have monadic context. This essentially limits
-- MonadUnliftIO to ReaderT and IdentityT
-- transformers on top of IO.
--
-- Laws. For any function run provided by withRunInIO, it
-- must meet the monad transformer laws as reformulated for
-- MonadUnliftIO:
--
--
--
-- Instances of MonadUnliftIO must also satisfy the following
-- laws:
--
--
-- - Identity law withRunInIO (\run -> run m) =
-- m
-- - Inverse law withRunInIO (\_ -> m) = liftIO
-- m
--
--
-- As an example of an invalid instance, a naive implementation of
-- MonadUnliftIO (StateT s m) might be
--
--
-- withRunInIO inner =
-- StateT $ \s ->
-- withRunInIO $ \run ->
-- inner (run . flip evalStateT s)
--
--
-- This breaks the identity law because the inner run m would
-- throw away any state changes in m.
class MonadIO m => MonadUnliftIO (m :: Type -> Type)
-- | Convenience function for capturing the monadic context and running an
-- IO action with a runner function. The runner function is used
-- to run a monadic action m in IO.
withRunInIO :: MonadUnliftIO m => ((forall a. () => m a -> IO a) -> IO b) -> m b
-- | The reader monad transformer, which adds a read-only environment to
-- the given monad.
--
-- The return function ignores the environment, while
-- >>= passes the inherited environment to both
-- subcomputations.
newtype ReaderT r (m :: Type -> Type) a
ReaderT :: (r -> m a) -> ReaderT r (m :: Type -> Type) a
[runReaderT] :: ReaderT r (m :: Type -> Type) a -> r -> m a
-- | A map of integers to values a.
data IntMap a
-- | A set of integers.
data IntSet
-- | General-purpose finite sequences.
data Seq a
-- | A set of values a.
data Set a
-- | a variant of deepseq that is useful in some circumstances:
--
--
-- force x = x `deepseq` x
--
--
-- force x fully evaluates x, and then returns it. Note
-- that force x only performs evaluation when the value of
-- force x itself is demanded, so essentially it turns shallow
-- evaluation into deep evaluation.
--
-- force can be conveniently used in combination with
-- ViewPatterns:
--
--
-- {-# LANGUAGE BangPatterns, ViewPatterns #-}
-- import Control.DeepSeq
--
-- someFun :: ComplexData -> SomeResult
-- someFun (force -> !arg) = {- 'arg' will be fully evaluated -}
--
--
-- Another useful application is to combine force with
-- evaluate in order to force deep evaluation relative to other
-- IO operations:
--
--
-- import Control.Exception (evaluate)
-- import Control.DeepSeq
--
-- main = do
-- result <- evaluate $ force $ pureComputation
-- {- 'result' will be fully evaluated at this point -}
-- return ()
--
--
-- Finally, here's an exception safe variant of the readFile'
-- example:
--
--
-- readFile' :: FilePath -> IO String
-- readFile' fn = bracket (openFile fn ReadMode) hClose $ \h ->
-- evaluate . force =<< hGetContents h
--
force :: NFData a => a -> a
-- | deepseq: fully evaluates the first argument, before returning
-- the second.
--
-- The name deepseq is used to illustrate the relationship to
-- seq: where seq is shallow in the sense that it only
-- evaluates the top level of its argument, deepseq traverses the
-- entire data structure evaluating it completely.
--
-- deepseq can be useful for forcing pending exceptions,
-- eradicating space leaks, or forcing lazy I/O to happen. It is also
-- useful in conjunction with parallel Strategies (see the
-- parallel package).
--
-- There is no guarantee about the ordering of evaluation. The
-- implementation may evaluate the components of the structure in any
-- order or in parallel. To impose an actual order on evaluation, use
-- pseq from Control.Parallel in the parallel
-- package.
deepseq :: NFData a => a -> b -> b
-- | the deep analogue of $!. In the expression f $!! x,
-- x is fully evaluated before the function f is
-- applied to it.
($!!) :: NFData a => (a -> b) -> a -> b
infixr 0 $!!
-- | Combine two paths with a path separator. If the second path starts
-- with a path separator or a drive letter, then it returns the second.
-- The intention is that readFile (dir </> file)
-- will access the same file as setCurrentDirectory dir; readFile
-- file.
--
--
-- Posix: "/directory" </> "file.ext" == "/directory/file.ext"
-- Windows: "/directory" </> "file.ext" == "/directory\\file.ext"
-- "directory" </> "/file.ext" == "/file.ext"
-- Valid x => (takeDirectory x </> takeFileName x) `equalFilePath` x
--
--
-- Combined:
--
--
-- Posix: "/" </> "test" == "/test"
-- Posix: "home" </> "bob" == "home/bob"
-- Posix: "x:" </> "foo" == "x:/foo"
-- Windows: "C:\\foo" </> "bar" == "C:\\foo\\bar"
-- Windows: "home" </> "bob" == "home\\bob"
--
--
-- Not combined:
--
--
-- Posix: "home" </> "/bob" == "/bob"
-- Windows: "home" </> "C:\\bob" == "C:\\bob"
--
--
-- Not combined (tricky):
--
-- On Windows, if a filepath starts with a single slash, it is relative
-- to the root of the current drive. In [1], this is (confusingly)
-- referred to as an absolute path. The current behavior of
-- </> is to never combine these forms.
--
--
-- Windows: "home" </> "/bob" == "/bob"
-- Windows: "home" </> "\\bob" == "\\bob"
-- Windows: "C:\\home" </> "\\bob" == "\\bob"
--
--
-- On Windows, from [1]: "If a file name begins with only a disk
-- designator but not the backslash after the colon, it is interpreted as
-- a relative path to the current directory on the drive with the
-- specified letter." The current behavior of </> is to
-- never combine these forms.
--
--
-- Windows: "D:\\foo" </> "C:bar" == "C:bar"
-- Windows: "C:\\foo" </> "C:bar" == "C:bar"
--
() :: FilePath -> FilePath -> FilePath
infixr 5
-- | Tag the Nothing value of a Maybe
note :: a -> Maybe b -> Either a b
-- | Suppress the Left value of an Either
hush :: Either a b -> Maybe b
-- | Generalized version of Handler
data Handler (m :: Type -> Type) a
Handler :: (e -> m a) -> Handler (m :: Type -> Type) a
-- | Get the directory name, move up one level.
--
--
-- takeDirectory "/directory/other.ext" == "/directory"
-- takeDirectory x `isPrefixOf` x || takeDirectory x == "."
-- takeDirectory "foo" == "."
-- takeDirectory "/" == "/"
-- takeDirectory "/foo" == "/"
-- takeDirectory "/foo/bar/baz" == "/foo/bar"
-- takeDirectory "/foo/bar/baz/" == "/foo/bar/baz"
-- takeDirectory "foo/bar/baz" == "foo/bar"
-- Windows: takeDirectory "foo\\bar" == "foo"
-- Windows: takeDirectory "foo\\bar\\\\" == "foo\\bar"
-- Windows: takeDirectory "C:\\" == "C:\\"
--
takeDirectory :: FilePath -> FilePath
-- | Get the base name, without an extension or path.
--
--
-- takeBaseName "/directory/file.ext" == "file"
-- takeBaseName "file/test.txt" == "test"
-- takeBaseName "dave.ext" == "dave"
-- takeBaseName "" == ""
-- takeBaseName "test" == "test"
-- takeBaseName (addTrailingPathSeparator x) == ""
-- takeBaseName "file/file.tar.gz" == "file.tar"
--
takeBaseName :: FilePath -> String
-- | Remove last extension, and the "." preceding it.
--
--
-- dropExtension "/directory/path.ext" == "/directory/path"
-- dropExtension x == fst (splitExtension x)
--
dropExtension :: FilePath -> FilePath
-- | Add an extension, even if there is already one there, equivalent to
-- addExtension.
--
--
-- "/directory/path" <.> "ext" == "/directory/path.ext"
-- "/directory/path" <.> ".ext" == "/directory/path.ext"
--
(<.>) :: FilePath -> String -> FilePath
infixr 7 <.>
class (Vector Vector a, MVector MVector a) => Unbox a
-- | Boxed vectors, supporting efficient slicing.
data Vector a
-- | The parameterizable reader monad.
--
-- Computations are functions of a shared environment.
--
-- The return function ignores the environment, while
-- >>= passes the inherited environment to both
-- subcomputations.
type Reader r = ReaderT r Identity
-- | lens creates a Lens from a getter and a setter. The
-- resulting lens isn't the most effective one (because of having to
-- traverse the structure twice when modifying), but it shouldn't matter
-- much.
--
-- A (partial) lens for list indexing:
--
--
-- ix :: Int -> Lens' [a] a
-- ix i = lens (!! i) -- getter
-- (\s b -> take i s ++ b : drop (i+1) s) -- setter
--
--
-- Usage:
--
--
-- >>> [1..9] ^. ix 3
-- 4
--
-- >>> [1..9] & ix 3 %~ negate
-- [1,2,3,-4,5,6,7,8,9]
--
--
-- When getting, the setter is completely unused; when setting, the
-- getter is unused. Both are used only when the value is being modified.
-- For instance, here we define a lens for the 1st element of a list, but
-- instead of a legitimate getter we use undefined. Then we use
-- the resulting lens for setting and it works, which proves that
-- the getter wasn't used:
--
--
-- >>> [1,2,3] & lens undefined (\s b -> b : tail s) .~ 10
-- [10,2,3]
--
lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b
-- | s ^? t returns the 1st element t returns, or
-- Nothing if t doesn't return anything. It's trivially
-- implemented by passing the First monoid to the getter.
--
-- Safe head:
--
--
-- >>> [] ^? each
-- Nothing
--
--
--
-- >>> [1..3] ^? each
-- Just 1
--
--
-- Converting Either to Maybe:
--
--
-- >>> Left 1 ^? _Right
-- Nothing
--
--
--
-- >>> Right 1 ^? _Right
-- Just 1
--
--
-- A non-operator version of (^?) is called preview, and
-- – like view – it's a bit more general than (^?) (it
-- works in MonadReader). If you need the general version, you
-- can get it from microlens-mtl; otherwise there's preview
-- available in Lens.Micro.Extras.
(^?) :: s -> Getting (First a) s a -> Maybe a
infixl 8 ^?
-- | s ^.. t returns the list of all values that t gets
-- from s.
--
-- A Maybe contains either 0 or 1 values:
--
--
-- >>> Just 3 ^.. _Just
-- [3]
--
--
-- Gathering all values in a list of tuples:
--
--
-- >>> [(1,2),(3,4)] ^.. each.each
-- [1,2,3,4]
--
(^..) :: s -> Getting (Endo [a]) s a -> [a]
infixl 8 ^..
-- | to creates a getter from any function:
--
--
-- a ^. to f = f a
--
--
-- It's most useful in chains, because it lets you mix lenses and
-- ordinary functions. Suppose you have a record which comes from some
-- third-party library and doesn't have any lens accessors. You want to
-- do something like this:
--
--
-- value ^. _1 . field . at 2
--
--
-- However, field isn't a getter, and you have to do this
-- instead:
--
--
-- field (value ^. _1) ^. at 2
--
--
-- but now value is in the middle and it's hard to read the
-- resulting code. A variant with to is prettier and more
-- readable:
--
--
-- value ^. _1 . to field . at 2
--
to :: (s -> a) -> SimpleGetter s a
-- | (^.) applies a getter to a value; in other words, it gets a
-- value out of a structure using a getter (which can be a lens,
-- traversal, fold, etc.).
--
-- Getting 1st field of a tuple:
--
--
-- (^. _1) :: (a, b) -> a
-- (^. _1) = fst
--
--
-- When (^.) is used with a traversal, it combines all results
-- using the Monoid instance for the resulting type. For instance,
-- for lists it would be simple concatenation:
--
--
-- >>> ("str","ing") ^. each
-- "string"
--
--
-- The reason for this is that traversals use Applicative, and the
-- Applicative instance for Const uses monoid concatenation
-- to combine “effects” of Const.
--
-- A non-operator version of (^.) is called view, and
-- it's a bit more general than (^.) (it works in
-- MonadReader). If you need the general version, you can get it
-- from microlens-mtl; otherwise there's view available in
-- Lens.Micro.Extras.
(^.) :: s -> Getting a s a -> a
infixl 8 ^.
-- | set is a synonym for (.~).
--
-- Setting the 1st component of a pair:
--
--
-- set _1 :: x -> (a, b) -> (x, b)
-- set _1 = \x t -> (x, snd t)
--
--
-- Using it to rewrite (<$):
--
--
-- set mapped :: Functor f => a -> f b -> f a
-- set mapped = (<$)
--
set :: ASetter s t a b -> b -> s -> t
-- | (.~) assigns a value to the target. It's the same thing as
-- using (%~) with const:
--
--
-- l .~ x = l %~ const x
--
--
-- See set if you want a non-operator synonym.
--
-- Here it is used to change 2 fields of a 3-tuple:
--
--
-- >>> (0,0,0) & _1 .~ 1 & _3 .~ 3
-- (1,0,3)
--
(.~) :: ASetter s t a b -> b -> s -> t
infixr 4 .~
-- | over is a synonym for (%~).
--
-- Getting fmap in a roundabout way:
--
--
-- over mapped :: Functor f => (a -> b) -> f a -> f b
-- over mapped = fmap
--
--
-- Applying a function to both components of a pair:
--
--
-- over both :: (a -> b) -> (a, a) -> (b, b)
-- over both = \f t -> (f (fst t), f (snd t))
--
--
-- Using over _2 as a replacement for
-- second:
--
--
-- >>> over _2 show (10,20)
-- (10,"20")
--
over :: ASetter s t a b -> (a -> b) -> s -> t
-- | (%~) applies a function to the target; an alternative
-- explanation is that it is an inverse of sets, which turns a
-- setter into an ordinary function. mapped %~
-- reverse is the same thing as fmap
-- reverse.
--
-- See over if you want a non-operator synonym.
--
-- Negating the 1st element of a pair:
--
--
-- >>> (1,2) & _1 %~ negate
-- (-1,2)
--
--
-- Turning all Lefts in a list to upper case:
--
--
-- >>> (mapped._Left.mapped %~ toUpper) [Left "foo", Right "bar"]
-- [Left "FOO",Right "bar"]
--
(%~) :: ASetter s t a b -> (a -> b) -> s -> t
infixr 4 %~
-- | sets creates an ASetter from an ordinary function. (The
-- only thing it does is wrapping and unwrapping Identity.)
sets :: ((a -> b) -> s -> t) -> ASetter s t a b
-- | ASetter s t a b is something that turns a function modifying
-- a value into a function modifying a structure. If you ignore
-- Identity (as Identity a is the same thing as
-- a), the type is:
--
--
-- type ASetter s t a b = (a -> b) -> s -> t
--
--
-- The reason Identity is used here is for ASetter to be
-- composable with other types, such as Lens.
--
-- Technically, if you're writing a library, you shouldn't use this type
-- for setters you are exporting from your library; the right type to use
-- is Setter, but it is not provided by this package
-- (because then it'd have to depend on distributive). It's
-- completely alright, however, to export functions which take an
-- ASetter as an argument.
type ASetter s t a b = a -> Identity b -> s -> Identity t
-- | This is a type alias for monomorphic setters which don't change the
-- type of the container (or of the value inside). It's useful more often
-- than the same type in lens, because we can't provide real setters and
-- so it does the job of both ASetter' and
-- Setter'.
type ASetter' s a = ASetter s s a a
-- | A SimpleGetter s a extracts a from s; so,
-- it's the same thing as (s -> a), but you can use it in
-- lens chains because its type looks like this:
--
--
-- type SimpleGetter s a =
-- forall r. (a -> Const r a) -> s -> Const r s
--
--
-- Since Const r is a functor, SimpleGetter has the same
-- shape as other lens types and can be composed with them. To get (s
-- -> a) out of a SimpleGetter, choose r ~ a and
-- feed Const :: a -> Const a a to the getter:
--
--
-- -- the actual signature is more permissive:
-- -- view :: Getting a s a -> s -> a
-- view :: SimpleGetter s a -> s -> a
-- view getter = getConst . getter Const
--
--
-- The actual Getter from lens is more general:
--
--
-- type Getter s a =
-- forall f. (Contravariant f, Functor f) => (a -> f a) -> s -> f s
--
--
-- I'm not currently aware of any functions that take lens's
-- Getter but won't accept SimpleGetter, but you should
-- try to avoid exporting SimpleGetters anyway to minimise
-- confusion. Alternatively, look at microlens-contra, which
-- provides a fully lens-compatible Getter.
--
-- Lens users: you can convert a SimpleGetter to Getter
-- by applying to . view to it.
type SimpleGetter s a = forall r. () => Getting r s a
-- | Functions that operate on getters and folds – such as (^.),
-- (^..), (^?) – use Getter r s a (with different
-- values of r) to describe what kind of result they need. For
-- instance, (^.) needs the getter to be able to return a single
-- value, and so it accepts a getter of type Getting a s a.
-- (^..) wants the getter to gather values together, so it uses
-- Getting (Endo [a]) s a (it could've used Getting [a] s
-- a instead, but it's faster with Endo). The choice of
-- r depends on what you want to do with elements you're
-- extracting from s.
type Getting r s a = a -> Const r a -> s -> Const r s
-- | Lens s t a b is the lowest common denominator of a setter and
-- a getter, something that has the power of both; it has a
-- Functor constraint, and since both Const and
-- Identity are functors, it can be used whenever a getter or a
-- setter is needed.
--
--
-- - a is the type of the value inside of structure
-- - b is the type of the replaced value
-- - s is the type of the whole structure
-- - t is the type of the structure after replacing a
-- in it with b
--
type Lens s t a b = forall (f :: Type -> Type). Functor f => a -> f b -> s -> f t
-- | This is a type alias for monomorphic lenses which don't change the
-- type of the container (or of the value inside).
type Lens' s a = Lens s s a a
-- | Retrieves a function of the current environment.
asks :: MonadReader r m => (r -> a) -> m a
-- | preview is a synonym for (^?), generalised for
-- MonadReader (just like view, which is a synonym for
-- (^.)).
--
--
-- >>> preview each [1..5]
-- Just 1
--
preview :: MonadReader s m => Getting (First a) s a -> m (Maybe a)
-- | view is a synonym for (^.), generalised for
-- MonadReader (we are able to use it instead of (^.) since
-- functions are instances of the MonadReader class):
--
--
-- >>> view _1 (1, 2)
-- 1
--
--
-- When you're using Reader for config and your config type has
-- lenses generated for it, most of the time you'll be using view
-- instead of asks:
--
--
-- doSomething :: (MonadReader Config m) => m Int
-- doSomething = do
-- thingy <- view setting1 -- same as “asks (^. setting1)”
-- anotherThingy <- view setting2
-- ...
--
view :: MonadReader s m => Getting a s a -> m a
-- | Runs a Reader and extracts the final value from it. (The
-- inverse of reader.)
runReader :: Reader r a -> r -> a
-- | Lifted newChan.
newChan :: MonadIO m => m (Chan a)
-- | Lifted writeChan.
writeChan :: MonadIO m => Chan a -> a -> m ()
-- | Lifted readChan.
readChan :: MonadIO m => Chan a -> m a
-- | Lifted dupChan.
dupChan :: MonadIO m => Chan a -> m (Chan a)
-- | Lifted getChanContents.
getChanContents :: MonadIO m => Chan a -> m [a]
-- | Lifted writeList2Chan.
writeList2Chan :: MonadIO m => Chan a -> [a] -> m ()
-- | Exception type thrown by throwString.
--
-- Note that the second field of the data constructor depends on GHC/base
-- version. For base 4.9 and GHC 8.0 and later, the second field is a
-- call stack. Previous versions of GHC and base do not support call
-- stacks, and the field is simply unit (provided to make pattern
-- matching across GHC versions easier).
data StringException
StringException :: String -> CallStack -> StringException
-- | Catch a synchronous (but not asynchronous) exception and recover from
-- it.
--
-- This is parameterized on the exception type. To catch all synchronous
-- exceptions, use catchAny.
catch :: (MonadUnliftIO m, Exception e) => m a -> (e -> m a) -> m a
-- | catch specialized to only catching IOExceptions.
catchIO :: MonadUnliftIO m => m a -> (IOException -> m a) -> m a
-- | catch specialized to catch all synchronous exceptions.
catchAny :: MonadUnliftIO m => m a -> (SomeException -> m a) -> m a
-- | Same as catch, but fully force evaluation of the result value
-- to find all impure exceptions.
catchDeep :: (MonadUnliftIO m, Exception e, NFData a) => m a -> (e -> m a) -> m a
-- | catchDeep specialized to catch all synchronous exception.
catchAnyDeep :: (NFData a, MonadUnliftIO m) => m a -> (SomeException -> m a) -> m a
-- | catchJust is like catch but it takes an extra argument
-- which is an exception predicate, a function which selects which type
-- of exceptions we're interested in.
catchJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a
-- | A variant of catch that catches both synchronous and
-- asynchronous exceptions.
--
-- WARNING: This function (and other *SyncOrAsync functions) is
-- for advanced users. Most of the time, you probably want to use the
-- non-SyncOrAsync versions.
--
-- Before attempting to use this function, be familiar with the "Rules
-- for async safe handling" section in this blog post.
catchSyncOrAsync :: (MonadUnliftIO m, Exception e) => m a -> (e -> m a) -> m a
-- | Flipped version of catch.
handle :: (MonadUnliftIO m, Exception e) => (e -> m a) -> m a -> m a
-- | handle specialized to only catching IOExceptions.
handleIO :: MonadUnliftIO m => (IOException -> m a) -> m a -> m a
-- | Flipped version of catchAny.
handleAny :: MonadUnliftIO m => (SomeException -> m a) -> m a -> m a
-- | Flipped version of catchDeep.
handleDeep :: (MonadUnliftIO m, Exception e, NFData a) => (e -> m a) -> m a -> m a
-- | Flipped version of catchAnyDeep.
handleAnyDeep :: (MonadUnliftIO m, NFData a) => (SomeException -> m a) -> m a -> m a
-- | Flipped catchJust.
handleJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a
-- | A variant of handle that catches both synchronous and
-- asynchronous exceptions.
--
-- See catchSyncOrAsync.
handleSyncOrAsync :: (MonadUnliftIO m, Exception e) => (e -> m a) -> m a -> m a
-- | Run the given action and catch any synchronous exceptions as a
-- Left value.
--
-- This is parameterized on the exception type. To catch all synchronous
-- exceptions, use tryAny.
try :: (MonadUnliftIO m, Exception e) => m a -> m (Either e a)
-- | try specialized to only catching IOExceptions.
tryIO :: MonadUnliftIO m => m a -> m (Either IOException a)
-- | try specialized to catch all synchronous exceptions.
tryAny :: MonadUnliftIO m => m a -> m (Either SomeException a)
-- | Same as try, but fully force evaluation of the result value to
-- find all impure exceptions.
tryDeep :: (MonadUnliftIO m, Exception e, NFData a) => m a -> m (Either e a)
-- | tryDeep specialized to catch all synchronous exceptions.
tryAnyDeep :: (MonadUnliftIO m, NFData a) => m a -> m (Either SomeException a)
-- | A variant of try that takes an exception predicate to select
-- which exceptions are caught.
tryJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)
-- | A variant of try that catches both synchronous and asynchronous
-- exceptions.
--
-- See catchSyncOrAsync.
trySyncOrAsync :: (MonadUnliftIO m, Exception e) => m a -> m (Either e a)
-- | Evaluate the value to WHNF and catch any synchronous exceptions.
--
-- The expression may still have bottom values within it; you may instead
-- want to use pureTryDeep.
pureTry :: a -> Either SomeException a
-- | Evaluate the value to NF and catch any synchronous exceptions.
pureTryDeep :: NFData a => a -> Either SomeException a
-- | Similar to catch, but provides multiple different handler
-- functions.
--
-- For more information on motivation, see base's
-- catches. Note that, unlike that function, this function will
-- not catch asynchronous exceptions.
catches :: MonadUnliftIO m => m a -> [Handler m a] -> m a
-- | Same as catches, but fully force evaluation of the result value
-- to find all impure exceptions.
catchesDeep :: (MonadUnliftIO m, NFData a) => m a -> [Handler m a] -> m a
-- | Lifted version of evaluate.
evaluate :: MonadIO m => a -> m a
-- | Deeply evaluate a value using evaluate and NFData.
evaluateDeep :: (MonadIO m, NFData a) => a -> m a
-- | Allocate and clean up a resource safely.
--
-- For more information on motivation and usage of this function, see
-- base's bracket. This function has two differences from
-- the one in base. The first, and more obvious, is that it
-- works on any MonadUnliftIO instance, not just IO.
--
-- The more subtle difference is that this function will use
-- uninterruptible masking for its cleanup handler. This is a subtle
-- distinction, but at a high level, means that resource cleanup has more
-- guarantees to complete. This comes at the cost that an incorrectly
-- written cleanup function cannot be interrupted.
--
-- For more information, please see
-- https://github.com/fpco/safe-exceptions/issues/3.
bracket :: MonadUnliftIO m => m a -> (a -> m b) -> (a -> m c) -> m c
-- | Same as bracket, but does not pass the acquired resource to
-- cleanup and use functions.
--
-- For more information, see base's bracket_.
bracket_ :: MonadUnliftIO m => m a -> m b -> m c -> m c
-- | Same as bracket, but only perform the cleanup if an exception
-- is thrown.
bracketOnError :: MonadUnliftIO m => m a -> (a -> m b) -> (a -> m c) -> m c
-- | A variant of bracketOnError where the return value from the
-- first computation is not required.
bracketOnError_ :: MonadUnliftIO m => m a -> m b -> m c -> m c
-- | Perform thing, guaranteeing that after will run
-- after, even if an exception occurs.
--
-- Same interruptible vs uninterrupible points apply as with
-- bracket. See base's finally for more
-- information.
finally :: MonadUnliftIO m => m a -> m b -> m a
-- | Like onException, but provides the handler the thrown
-- exception.
withException :: (MonadUnliftIO m, Exception e) => m a -> (e -> m b) -> m a
-- | Like finally, but only call after if an exception
-- occurs.
onException :: MonadUnliftIO m => m a -> m b -> m a
-- | Convert an exception into a synchronous exception.
--
-- For synchronous exceptions, this is the same as toException.
-- For asynchronous exceptions, this will wrap up the exception with
-- SyncExceptionWrapper.
toSyncException :: Exception e => e -> SomeException
-- | Convert an exception into an asynchronous exception.
--
-- For asynchronous exceptions, this is the same as toException.
-- For synchronous exceptions, this will wrap up the exception with
-- AsyncExceptionWrapper.
toAsyncException :: Exception e => e -> SomeException
-- | Convert from a possibly wrapped exception.
--
-- The inverse of toAsyncException and toSyncException.
-- When using those functions (or functions that use them, like
-- throwTo or throwIO), fromException might not be
-- sufficient because the exception might be wrapped within
-- SyncExceptionWrapper or AsyncExceptionWrapper.
fromExceptionUnwrap :: Exception e => SomeException -> Maybe e
-- | Check if the given exception is synchronous.
isSyncException :: Exception e => e -> Bool
-- | Check if the given exception is asynchronous.
isAsyncException :: Exception e => e -> Bool
-- | Unlifted version of mask.
mask :: MonadUnliftIO m => ((forall a. () => m a -> m a) -> m b) -> m b
-- | Unlifted version of uninterruptibleMask.
uninterruptibleMask :: MonadUnliftIO m => ((forall a. () => m a -> m a) -> m b) -> m b
-- | Unlifted version of mask_.
mask_ :: MonadUnliftIO m => m a -> m a
-- | Unlifted version of uninterruptibleMask_.
uninterruptibleMask_ :: MonadUnliftIO m => m a -> m a
-- | Smart constructor for a StringException that deals with the
-- call stack.
stringException :: HasCallStack => String -> StringException
-- | Throw an asynchronous exception to another thread.
--
-- Synchronously typed exceptions will be wrapped into an
-- AsyncExceptionWrapper, see
-- https://github.com/fpco/safe-exceptions#determining-sync-vs-async.
--
-- It's usually a better idea to use the UnliftIO.Async module,
-- see https://github.com/fpco/safe-exceptions#quickstart.
throwTo :: (Exception e, MonadIO m) => ThreadId -> e -> m ()
-- | Generate a pure value which, when forced, will synchronously throw the
-- given exception.
--
-- Generally it's better to avoid using this function and instead use
-- throwIO, see
-- https://github.com/fpco/safe-exceptions#quickstart.
impureThrow :: Exception e => e -> a
-- | Unwrap an Either value, throwing its Left value as a
-- runtime exception via throwIO if present.
fromEither :: (Exception e, MonadIO m) => Either e a -> m a
-- | Same as fromEither, but works on an IO-wrapped
-- Either.
fromEitherIO :: (Exception e, MonadIO m) => IO (Either e a) -> m a
-- | Same as fromEither, but works on an m-wrapped
-- Either.
fromEitherM :: (Exception e, MonadIO m) => m (Either e a) -> m a
-- | Same as mapException, except works in a monadic context.
mapExceptionM :: (Exception e1, Exception e2, MonadUnliftIO m) => (e1 -> e2) -> m a -> m a
-- | Unlifted version of withFile.
withFile :: MonadUnliftIO m => FilePath -> IOMode -> (Handle -> m a) -> m a
-- | Lifted version of openFile
openFile :: MonadIO m => FilePath -> IOMode -> m Handle
-- | Lifted version of hClose
hClose :: MonadIO m => Handle -> m ()
-- | Lifted version of hFlush
hFlush :: MonadIO m => Handle -> m ()
-- | Lifted version of hFileSize
hFileSize :: MonadIO m => Handle -> m Integer
-- | Lifted version of hSetFileSize
hSetFileSize :: MonadIO m => Handle -> Integer -> m ()
-- | Lifted version of hIsEOF
hIsEOF :: MonadIO m => Handle -> m Bool
-- | Lifted version of hSetBuffering
hSetBuffering :: MonadIO m => Handle -> BufferMode -> m ()
-- | Lifted version of hGetBuffering
hGetBuffering :: MonadIO m => Handle -> m BufferMode
-- | Lifted version of hSeek
hSeek :: MonadIO m => Handle -> SeekMode -> Integer -> m ()
-- | Lifted version of hTell
hTell :: MonadIO m => Handle -> m Integer
-- | Lifted version of hIsOpen
hIsOpen :: MonadIO m => Handle -> m Bool
-- | Lifted version of hIsClosed
hIsClosed :: MonadIO m => Handle -> m Bool
-- | Lifted version of hIsReadable
hIsReadable :: MonadIO m => Handle -> m Bool
-- | Lifted version of hIsWritable
hIsWritable :: MonadIO m => Handle -> m Bool
-- | Lifted version of hIsSeekable
hIsSeekable :: MonadIO m => Handle -> m Bool
-- | Lifted version of hIsTerminalDevice
hIsTerminalDevice :: MonadIO m => Handle -> m Bool
-- | Lifted version of hSetEcho
hSetEcho :: MonadIO m => Handle -> Bool -> m ()
-- | Lifted version of hGetEcho
hGetEcho :: MonadIO m => Handle -> m Bool
-- | Lifted version of hWaitForInput
hWaitForInput :: MonadIO m => Handle -> Int -> m Bool
-- | Lifted version of hReady
hReady :: MonadIO m => Handle -> m Bool
-- | Get the number of seconds which have passed since an arbitrary
-- starting time, useful for calculating runtime in a program.
getMonotonicTime :: MonadIO m => m Double
-- | Lifted newIORef.
newIORef :: MonadIO m => a -> m (IORef a)
-- | Lifted readIORef.
readIORef :: MonadIO m => IORef a -> m a
-- | Lifted writeIORef.
writeIORef :: MonadIO m => IORef a -> a -> m ()
-- | Lifted modifyIORef.
modifyIORef :: MonadIO m => IORef a -> (a -> a) -> m ()
-- | Lifted modifyIORef'.
modifyIORef' :: MonadIO m => IORef a -> (a -> a) -> m ()
-- | Lifted atomicModifyIORef.
atomicModifyIORef :: MonadIO m => IORef a -> (a -> (a, b)) -> m b
-- | Lifted atomicModifyIORef'.
atomicModifyIORef' :: MonadIO m => IORef a -> (a -> (a, b)) -> m b
-- | Lifted atomicWriteIORef.
atomicWriteIORef :: MonadIO m => IORef a -> a -> m ()
-- | Unlifted mkWeakIORef.
mkWeakIORef :: MonadUnliftIO m => IORef a -> m () -> m (Weak (IORef a))
-- | Things that can go wrong in the structure of a Conc. These are
-- programmer errors.
data ConcException
EmptyWithNoAlternative :: ConcException
-- | A more efficient alternative to Concurrently, which reduces the
-- number of threads that need to be forked. For more information, see
-- this blog post. This is provided as a separate type to
-- Concurrently as it has a slightly different API.
--
-- Use the conc function to construct values of type Conc,
-- and runConc to execute the composed actions. You can use the
-- Applicative instance to run different actions and wait for
-- all of them to complete, or the Alternative instance to wait
-- for the first thread to complete.
--
-- In the event of a runtime exception thrown by any of the children
-- threads, or an asynchronous exception received in the parent thread,
-- all threads will be killed with an AsyncCancelled exception and
-- the original exception rethrown. If multiple exceptions are generated
-- by different threads, there are no guarantees on which exception will
-- end up getting rethrown.
--
-- For many common use cases, you may prefer using helper functions in
-- this module like mapConcurrently.
--
-- There are some intentional differences in behavior to
-- Concurrently:
--
--
-- - Children threads are always launched in an unmasked state, not the
-- inherited state of the parent thread.
--
--
-- Note that it is a programmer error to use the Alternative
-- instance in such a way that there are no alternatives to an empty,
-- e.g. runConc (empty | empty). In such a case, a
-- ConcException will be thrown. If there was an
-- Alternative in the standard libraries without empty,
-- this library would use it instead.
data Conc (m :: TYPE LiftedRep -> Type) a
-- | Unlifted Concurrently.
newtype Concurrently (m :: Type -> Type) a
Concurrently :: m a -> Concurrently (m :: Type -> Type) a
[runConcurrently] :: Concurrently (m :: Type -> Type) a -> m a
-- | Unlifted async.
async :: MonadUnliftIO m => m a -> m (Async a)
-- | Unlifted asyncBound.
asyncBound :: MonadUnliftIO m => m a -> m (Async a)
-- | Unlifted asyncOn.
asyncOn :: MonadUnliftIO m => Int -> m a -> m (Async a)
-- | Unlifted asyncWithUnmask.
asyncWithUnmask :: MonadUnliftIO m => ((forall b. () => m b -> m b) -> m a) -> m (Async a)
-- | Unlifted asyncOnWithUnmask.
asyncOnWithUnmask :: MonadUnliftIO m => Int -> ((forall b. () => m b -> m b) -> m a) -> m (Async a)
-- | Unlifted withAsync.
withAsync :: MonadUnliftIO m => m a -> (Async a -> m b) -> m b
-- | Unlifted withAsyncBound.
withAsyncBound :: MonadUnliftIO m => m a -> (Async a -> m b) -> m b
-- | Unlifted withAsyncOn.
withAsyncOn :: MonadUnliftIO m => Int -> m a -> (Async a -> m b) -> m b
-- | Unlifted withAsyncWithUnmask.
withAsyncWithUnmask :: MonadUnliftIO m => ((forall c. () => m c -> m c) -> m a) -> (Async a -> m b) -> m b
-- | Unlifted withAsyncOnWithMask.
withAsyncOnWithUnmask :: MonadUnliftIO m => Int -> ((forall c. () => m c -> m c) -> m a) -> (Async a -> m b) -> m b
-- | Lifted wait.
wait :: MonadIO m => Async a -> m a
-- | Lifted poll.
poll :: MonadIO m => Async a -> m (Maybe (Either SomeException a))
-- | Lifted waitCatch.
waitCatch :: MonadIO m => Async a -> m (Either SomeException a)
-- | Lifted cancel.
cancel :: MonadIO m => Async a -> m ()
-- | Lifted uninterruptibleCancel.
uninterruptibleCancel :: MonadIO m => Async a -> m ()
-- | Lifted cancelWith. Additionally uses toAsyncException to
-- ensure async exception safety.
cancelWith :: (Exception e, MonadIO m) => Async a -> e -> m ()
-- | Lifted waitAny.
waitAny :: MonadIO m => [Async a] -> m (Async a, a)
-- | Lifted waitAnyCatch.
waitAnyCatch :: MonadIO m => [Async a] -> m (Async a, Either SomeException a)
-- | Lifted waitAnyCancel.
waitAnyCancel :: MonadIO m => [Async a] -> m (Async a, a)
-- | Lifted waitAnyCatchCancel.
waitAnyCatchCancel :: MonadIO m => [Async a] -> m (Async a, Either SomeException a)
-- | Lifted waitEither.
waitEither :: MonadIO m => Async a -> Async b -> m (Either a b)
-- | Lifted waitEitherCatch.
waitEitherCatch :: MonadIO m => Async a -> Async b -> m (Either (Either SomeException a) (Either SomeException b))
-- | Lifted waitEitherCancel.
waitEitherCancel :: MonadIO m => Async a -> Async b -> m (Either a b)
-- | Lifted waitEitherCatchCancel.
waitEitherCatchCancel :: MonadIO m => Async a -> Async b -> m (Either (Either SomeException a) (Either SomeException b))
-- | Lifted waitEither_.
waitEither_ :: MonadIO m => Async a -> Async b -> m ()
-- | Lifted waitBoth.
waitBoth :: MonadIO m => Async a -> Async b -> m (a, b)
-- | Lifted link.
link :: MonadIO m => Async a -> m ()
-- | Lifted link2.
link2 :: MonadIO m => Async a -> Async b -> m ()
-- | Unlifted race.
race :: MonadUnliftIO m => m a -> m b -> m (Either a b)
-- | Unlifted race_.
race_ :: MonadUnliftIO m => m a -> m b -> m ()
-- | Unlifted concurrently.
concurrently :: MonadUnliftIO m => m a -> m b -> m (a, b)
-- | Unlifted concurrently_.
concurrently_ :: MonadUnliftIO m => m a -> m b -> m ()
-- | Similar to mapConcurrently but with arguments flipped
forConcurrently :: (MonadUnliftIO m, Traversable t) => t a -> (a -> m b) -> m (t b)
-- | Similar to mapConcurrently_ but with arguments flipped
forConcurrently_ :: (MonadUnliftIO m, Foldable f) => f a -> (a -> m b) -> m ()
-- | Unlifted replicateConcurrently.
replicateConcurrently :: MonadUnliftIO f => Int -> f a -> f [a]
-- | Unlifted replicateConcurrently_.
replicateConcurrently_ :: (Applicative m, MonadUnliftIO m) => Int -> m a -> m ()
-- | Executes a Traversable container of items concurrently, it uses
-- the Flat type internally.
mapConcurrently :: (MonadUnliftIO m, Traversable t) => (a -> m b) -> t a -> m (t b)
-- | Executes a Traversable container of items concurrently, it uses
-- the Flat type internally. This function ignores the results.
mapConcurrently_ :: (MonadUnliftIO m, Foldable f) => (a -> m b) -> f a -> m ()
-- | Construct a value of type Conc from an action. Compose these
-- values using the typeclass instances (most commonly Applicative
-- and Alternative) and then run with runConc.
conc :: m a -> Conc m a
-- | Run a Conc value on multiple threads.
runConc :: MonadUnliftIO m => Conc m a -> m a
-- | Like mapConcurrently from async, but instead of one thread per
-- element, it does pooling from a set of threads. This is useful in
-- scenarios where resource consumption is bounded and for use cases
-- where too many concurrent tasks aren't allowed.
--
-- Example usage
--
--
-- import Say
--
-- action :: Int -> IO Int
-- action n = do
-- tid <- myThreadId
-- sayString $ show tid
-- threadDelay (2 * 10^6) -- 2 seconds
-- return n
--
-- main :: IO ()
-- main = do
-- yx <- pooledMapConcurrentlyN 5 (\x -> action x) [1..5]
-- print yx
--
--
-- On executing you can see that five threads have been spawned:
--
--
-- $ ./pool
-- ThreadId 36
-- ThreadId 38
-- ThreadId 40
-- ThreadId 42
-- ThreadId 44
-- [1,2,3,4,5]
--
--
-- Let's modify the above program such that there are less threads than
-- the number of items in the list:
--
--
-- import Say
--
-- action :: Int -> IO Int
-- action n = do
-- tid <- myThreadId
-- sayString $ show tid
-- threadDelay (2 * 10^6) -- 2 seconds
-- return n
--
-- main :: IO ()
-- main = do
-- yx <- pooledMapConcurrentlyN 3 (\x -> action x) [1..5]
-- print yx
--
--
-- On executing you can see that only three threads are active totally:
--
--
-- $ ./pool
-- ThreadId 35
-- ThreadId 37
-- ThreadId 39
-- ThreadId 35
-- ThreadId 39
-- [1,2,3,4,5]
--
pooledMapConcurrentlyN :: (MonadUnliftIO m, Traversable t) => Int -> (a -> m b) -> t a -> m (t b)
-- | Similar to pooledMapConcurrentlyN but with number of threads
-- set from getNumCapabilities. Usually this is useful for CPU
-- bound tasks.
pooledMapConcurrently :: (MonadUnliftIO m, Traversable t) => (a -> m b) -> t a -> m (t b)
-- | Similar to pooledMapConcurrentlyN but with flipped arguments.
pooledForConcurrentlyN :: (MonadUnliftIO m, Traversable t) => Int -> t a -> (a -> m b) -> m (t b)
-- | Similar to pooledForConcurrentlyN but with number of threads
-- set from getNumCapabilities. Usually this is useful for CPU
-- bound tasks.
pooledForConcurrently :: (MonadUnliftIO m, Traversable t) => t a -> (a -> m b) -> m (t b)
-- | Like pooledMapConcurrentlyN but with the return value
-- discarded.
pooledMapConcurrentlyN_ :: (MonadUnliftIO m, Foldable f) => Int -> (a -> m b) -> f a -> m ()
-- | Like pooledMapConcurrently but with the return value discarded.
pooledMapConcurrently_ :: (MonadUnliftIO m, Foldable f) => (a -> m b) -> f a -> m ()
-- | Like pooledMapConcurrently_ but with flipped arguments.
pooledForConcurrently_ :: (MonadUnliftIO m, Foldable f) => f a -> (a -> m b) -> m ()
-- | Like pooledMapConcurrentlyN_ but with flipped arguments.
pooledForConcurrentlyN_ :: (MonadUnliftIO m, Foldable t) => Int -> t a -> (a -> m b) -> m ()
-- | Pooled version of replicateConcurrently. Performs the action in
-- the pooled threads.
pooledReplicateConcurrentlyN :: MonadUnliftIO m => Int -> Int -> m a -> m [a]
-- | Similar to pooledReplicateConcurrentlyN but with number of
-- threads set from getNumCapabilities. Usually this is useful for
-- CPU bound tasks.
pooledReplicateConcurrently :: MonadUnliftIO m => Int -> m a -> m [a]
-- | Pooled version of replicateConcurrently_. Performs the action
-- in the pooled threads.
pooledReplicateConcurrentlyN_ :: MonadUnliftIO m => Int -> Int -> m a -> m ()
-- | Similar to pooledReplicateConcurrently_ but with number of
-- threads set from getNumCapabilities. Usually this is useful for
-- CPU bound tasks.
pooledReplicateConcurrently_ :: MonadUnliftIO m => Int -> m a -> m ()
-- | Lifted newEmptyMVar.
newEmptyMVar :: MonadIO m => m (MVar a)
-- | Lifted newMVar.
newMVar :: MonadIO m => a -> m (MVar a)
-- | Lifted takeMVar.
takeMVar :: MonadIO m => MVar a -> m a
-- | Lifted putMVar.
putMVar :: MonadIO m => MVar a -> a -> m ()
-- | Lifted readMVar.
readMVar :: MonadIO m => MVar a -> m a
-- | Lifted swapMVar.
swapMVar :: MonadIO m => MVar a -> a -> m a
-- | Lifted tryTakeMVar.
tryTakeMVar :: MonadIO m => MVar a -> m (Maybe a)
-- | Lifted tryPutMVar.
tryPutMVar :: MonadIO m => MVar a -> a -> m Bool
-- | Lifted isEmptyMVar.
isEmptyMVar :: MonadIO m => MVar a -> m Bool
-- | Lifted tryReadMVar.
tryReadMVar :: MonadIO m => MVar a -> m (Maybe a)
-- | Unlifted withMVar.
withMVar :: MonadUnliftIO m => MVar a -> (a -> m b) -> m b
-- | Unlifted withMVarMasked.
withMVarMasked :: MonadUnliftIO m => MVar a -> (a -> m b) -> m b
-- | Unlifted modifyMVar_.
modifyMVar_ :: MonadUnliftIO m => MVar a -> (a -> m a) -> m ()
-- | Unlifted modifyMVar.
modifyMVar :: MonadUnliftIO m => MVar a -> (a -> m (a, b)) -> m b
-- | Unlifted modifyMVarMasked_.
modifyMVarMasked_ :: MonadUnliftIO m => MVar a -> (a -> m a) -> m ()
-- | Unlifted modifyMVarMasked.
modifyMVarMasked :: MonadUnliftIO m => MVar a -> (a -> m (a, b)) -> m b
-- | Unlifted mkWeakMVar.
mkWeakMVar :: MonadUnliftIO m => MVar a -> m () -> m (Weak (MVar a))
-- | A "run once" value, with results saved. Extract the value with
-- runMemoized. For single-threaded usage, you can use
-- memoizeRef to create a value. If you need guarantees that only
-- one thread will run the action at a time, use memoizeMVar.
--
-- Note that this type provides a Show instance for convenience,
-- but not useful information can be provided.
data Memoized a
-- | Extract a value from a Memoized, running an action if no cached
-- value is available.
runMemoized :: MonadIO m => Memoized a -> m a
-- | Create a new Memoized value using an IORef under the
-- surface. Note that the action may be run in multiple threads
-- simultaneously, so this may not be thread safe (depending on the
-- underlying action). Consider using memoizeMVar.
memoizeRef :: MonadUnliftIO m => m a -> m (Memoized a)
-- | Same as memoizeRef, but uses an MVar to ensure that an
-- action is only run once, even in a multithreaded application.
memoizeMVar :: MonadUnliftIO m => m a -> m (Memoized a)
-- | Lifted newQSem.
newQSem :: MonadIO m => Int -> m QSem
-- | Lifted waitQSem.
waitQSem :: MonadIO m => QSem -> m ()
-- | Lifted signalQSem.
signalQSem :: MonadIO m => QSem -> m ()
-- | withQSem is an exception-safe wrapper for performing the
-- provided operation while holding a unit of value from the semaphore.
-- It ensures the semaphore cannot be leaked if there are exceptions.
withQSem :: MonadUnliftIO m => QSem -> m a -> m a
-- | Lifted newQSemN.
newQSemN :: MonadIO m => Int -> m QSemN
-- | Lifted waitQSemN.
waitQSemN :: MonadIO m => QSemN -> Int -> m ()
-- | Lifted signalQSemN.
signalQSemN :: MonadIO m => QSemN -> Int -> m ()
-- | withQSemN is an exception-safe wrapper for performing the
-- provided operation while holding N unit of value from the semaphore.
-- It ensures the semaphore cannot be leaked if there are exceptions.
withQSemN :: MonadUnliftIO m => QSemN -> Int -> m a -> m a
-- | Lifted version of atomically
atomically :: MonadIO m => STM a -> m a
-- | Renamed retry for unqualified export
retrySTM :: STM a
-- | Renamed check for unqualified export
checkSTM :: Bool -> STM ()
-- | Lifted version of newTVarIO
newTVarIO :: MonadIO m => a -> m (TVar a)
-- | Lifted version of readTVarIO
readTVarIO :: MonadIO m => TVar a -> m a
-- | Lifted version of registerDelay
registerDelay :: MonadIO m => Int -> m (TVar Bool)
-- | Lifted version of mkWeakTVar
mkWeakTVar :: MonadUnliftIO m => TVar a -> m () -> m (Weak (TVar a))
-- | Lifted version of newTMVarIO
newTMVarIO :: MonadIO m => a -> m (TMVar a)
-- | Lifted version of newEmptyTMVarIO
newEmptyTMVarIO :: MonadIO m => m (TMVar a)
-- | Lifted version of mkWeakTMVar
mkWeakTMVar :: MonadUnliftIO m => TMVar a -> m () -> m (Weak (TMVar a))
-- | Lifted version of newTChanIO
newTChanIO :: MonadIO m => m (TChan a)
-- | Lifted version of newBroadcastTChanIO
newBroadcastTChanIO :: MonadIO m => m (TChan a)
-- | Lifted version of newTQueueIO
newTQueueIO :: MonadIO m => m (TQueue a)
-- | Lifted version of newTBQueueIO
newTBQueueIO :: MonadIO m => Natural -> m (TBQueue a)
-- | Create and use a temporary file in the system standard temporary
-- directory.
--
-- Behaves exactly the same as withTempFile, except that the
-- parent temporary directory will be that returned by
-- getCanonicalTemporaryDirectory.
withSystemTempFile :: MonadUnliftIO m => String -> (FilePath -> Handle -> m a) -> m a
-- | Create and use a temporary directory in the system standard temporary
-- directory.
--
-- Behaves exactly the same as withTempDirectory, except that the
-- parent temporary directory will be that returned by
-- getCanonicalTemporaryDirectory.
withSystemTempDirectory :: MonadUnliftIO m => String -> (FilePath -> m a) -> m a
-- | Use a temporary filename that doesn't already exist.
--
-- Creates a new temporary file inside the given directory, making use of
-- the template. The temp file is deleted after use. For example:
--
--
-- withTempFile "src" "sdist." $ \tmpFile hFile -> do ...
--
--
-- The tmpFile will be file in the given directory, e.g.
-- src/sdist.342.
withTempFile :: MonadUnliftIO m => FilePath -> String -> (FilePath -> Handle -> m a) -> m a
-- | Create and use a temporary directory.
--
-- Creates a new temporary directory inside the given directory, making
-- use of the template. The temp directory is deleted after use. For
-- example:
--
--
-- withTempDirectory "src" "sdist." $ \tmpDir -> do ...
--
--
-- The tmpDir will be a new subdirectory of the given directory,
-- e.g. src/sdist.342.
withTempDirectory :: MonadUnliftIO m => FilePath -> String -> (FilePath -> m a) -> m a
-- | Unlifted timeout.
timeout :: MonadUnliftIO m => Int -> m a -> m (Maybe a)
-- | A helper function for lifting IO a -> IO b functions into
-- any MonadUnliftIO.
--
-- Example
--
--
-- liftedTry :: (Exception e, MonadUnliftIO m) => m a -> m (Either e a)
-- liftedTry m = liftIOOp Control.Exception.try m
--
liftIOOp :: MonadUnliftIO m => (IO a -> IO b) -> m a -> m b
-- | A helper function for implementing MonadUnliftIO instances.
-- Useful for the common case where you want to simply delegate to the
-- underlying transformer.
--
-- Note: You can derive MonadUnliftIO for newtypes without this
-- helper function in unliftio-core 0.2.0.0 and later.
--
-- Example
--
--
-- newtype AppT m a = AppT { unAppT :: ReaderT Int (ResourceT m) a }
-- deriving (Functor, Applicative, Monad, MonadIO)
--
-- -- Same as `deriving newtype (MonadUnliftIO)`
-- instance MonadUnliftIO m => MonadUnliftIO (AppT m) where
-- withRunInIO = wrappedWithRunInIO AppT unAppT
--
wrappedWithRunInIO :: MonadUnliftIO n => (n b -> m b) -> (forall a. () => m a -> n a) -> ((forall a. () => m a -> IO a) -> IO b) -> m b
-- | Convert an action in m to an action in IO.
toIO :: MonadUnliftIO m => m a -> m (IO a)
-- | Convenience function for capturing the monadic context and running an
-- IO action. The UnliftIO newtype wrapper is rarely
-- needed, so prefer withRunInIO to this function.
withUnliftIO :: MonadUnliftIO m => (UnliftIO m -> IO a) -> m a
-- | Same as askUnliftIO, but returns a monomorphic function instead
-- of a polymorphic newtype wrapper. If you only need to apply the
-- transformation on one concrete type, this function can be more
-- convenient.
askRunInIO :: MonadUnliftIO m => m (m a -> IO a)
-- | Capture the current monadic context, providing the ability to run
-- monadic actions in IO.
--
-- See UnliftIO for an explanation of why we need a helper
-- datatype here.
--
-- Prior to version 0.2.0.0 of this library, this was a method in the
-- MonadUnliftIO type class. It was moved out due to
-- https://github.com/fpco/unliftio/issues/55.
askUnliftIO :: MonadUnliftIO m => m (UnliftIO m)
-- | The ability to run any monadic action m a as IO a.
--
-- This is more precisely a natural transformation. We need to new
-- datatype (instead of simply using a forall) due to lack of
-- support in GHC for impredicative types.
newtype UnliftIO (m :: Type -> Type)
UnliftIO :: (forall a. () => m a -> IO a) -> UnliftIO (m :: Type -> Type)
[unliftIO] :: UnliftIO (m :: Type -> Type) -> forall a. () => m a -> IO a
-- | Efficiently read the entire contents of a TBQueue into a list.
-- This function never retries.
flushTBQueue :: TBQueue a -> STM [a]
-- | Returns True if the supplied TBQueue is empty.
isEmptyTBQueue :: TBQueue a -> STM Bool
-- | Returns True if the supplied TBQueue is full.
isFullTBQueue :: TBQueue a -> STM Bool
-- | Return the length of a TBQueue.
lengthTBQueue :: TBQueue a -> STM Natural
-- | Builds and returns a new instance of TBQueue.
newTBQueue :: Natural -> STM (TBQueue a)
-- | Get the next value from the TBQueue without removing it,
-- retrying if the channel is empty.
peekTBQueue :: TBQueue a -> STM a
-- | Read the next value from the TBQueue.
readTBQueue :: TBQueue a -> STM a
-- | A version of peekTBQueue which does not retry. Instead it
-- returns Nothing if no value is available.
tryPeekTBQueue :: TBQueue a -> STM (Maybe a)
-- | A version of readTBQueue which does not retry. Instead it
-- returns Nothing if no value is available.
tryReadTBQueue :: TBQueue a -> STM (Maybe a)
-- | Put a data item back onto a channel, where it will be the next item
-- read. Blocks if the queue is full.
unGetTBQueue :: TBQueue a -> a -> STM ()
-- | Write a value to a TBQueue; blocks if the queue is full.
writeTBQueue :: TBQueue a -> a -> STM ()
-- | TBQueue is an abstract type representing a bounded FIFO
-- channel.
data TBQueue a
-- | Clone a TChan: similar to dupTChan, but the cloned channel
-- starts with the same content available as the original channel.
cloneTChan :: TChan a -> STM (TChan a)
-- | Duplicate a TChan: the duplicate channel begins empty, but data
-- written to either channel from then on will be available from both.
-- Hence this creates a kind of broadcast channel, where data written by
-- anyone is seen by everyone else.
dupTChan :: TChan a -> STM (TChan a)
-- | Returns True if the supplied TChan is empty.
isEmptyTChan :: TChan a -> STM Bool
-- | Create a write-only TChan. More precisely, readTChan
-- will retry even after items have been written to the channel.
-- The only way to read a broadcast channel is to duplicate it with
-- dupTChan.
--
-- Consider a server that broadcasts messages to clients:
--
--
-- serve :: TChan Message -> Client -> IO loop
-- serve broadcastChan client = do
-- myChan <- dupTChan broadcastChan
-- forever $ do
-- message <- readTChan myChan
-- send client message
--
--
-- The problem with using newTChan to create the broadcast channel
-- is that if it is only written to and never read, items will pile up in
-- memory. By using newBroadcastTChan to create the broadcast
-- channel, items can be garbage collected after clients have seen them.
newBroadcastTChan :: STM (TChan a)
-- | Build and return a new instance of TChan
newTChan :: STM (TChan a)
-- | Get the next value from the TChan without removing it,
-- retrying if the channel is empty.
peekTChan :: TChan a -> STM a
-- | Read the next value from the TChan.
readTChan :: TChan a -> STM a
-- | A version of peekTChan which does not retry. Instead it returns
-- Nothing if no value is available.
tryPeekTChan :: TChan a -> STM (Maybe a)
-- | A version of readTChan which does not retry. Instead it returns
-- Nothing if no value is available.
tryReadTChan :: TChan a -> STM (Maybe a)
-- | Put a data item back onto a channel, where it will be the next item
-- read.
unGetTChan :: TChan a -> a -> STM ()
-- | Write a value to a TChan.
writeTChan :: TChan a -> a -> STM ()
-- | TChan is an abstract type representing an unbounded FIFO
-- channel.
data TChan a
-- | Check whether a given TMVar is empty.
isEmptyTMVar :: TMVar a -> STM Bool
-- | Create a TMVar which is initially empty.
newEmptyTMVar :: STM (TMVar a)
-- | Create a TMVar which contains the supplied value.
newTMVar :: a -> STM (TMVar a)
-- | Put a value into a TMVar. If the TMVar is currently
-- full, putTMVar will retry.
putTMVar :: TMVar a -> a -> STM ()
-- | This is a combination of takeTMVar and putTMVar; ie. it
-- takes the value from the TMVar, puts it back, and also returns
-- it.
readTMVar :: TMVar a -> STM a
-- | Swap the contents of a TMVar for a new value.
swapTMVar :: TMVar a -> a -> STM a
-- | Return the contents of the TMVar. If the TMVar is
-- currently empty, the transaction will retry. After a
-- takeTMVar, the TMVar is left empty.
takeTMVar :: TMVar a -> STM a
-- | A version of putTMVar that does not retry. The
-- tryPutTMVar function attempts to put the value a into
-- the TMVar, returning True if it was successful, or
-- False otherwise.
tryPutTMVar :: TMVar a -> a -> STM Bool
-- | A version of readTMVar which does not retry. Instead it returns
-- Nothing if no value is available.
tryReadTMVar :: TMVar a -> STM (Maybe a)
-- | A version of takeTMVar that does not retry. The
-- tryTakeTMVar function returns Nothing if the
-- TMVar was empty, or Just a if the TMVar
-- was full with contents a. After tryTakeTMVar, the
-- TMVar is left empty.
tryTakeTMVar :: TMVar a -> STM (Maybe a)
-- | A TMVar is a synchronising variable, used for communication
-- between concurrent threads. It can be thought of as a box, which may
-- be empty or full.
data TMVar a
-- | Returns True if the supplied TQueue is empty.
isEmptyTQueue :: TQueue a -> STM Bool
-- | Build and returns a new instance of TQueue
newTQueue :: STM (TQueue a)
-- | Get the next value from the TQueue without removing it,
-- retrying if the channel is empty.
peekTQueue :: TQueue a -> STM a
-- | Read the next value from the TQueue.
readTQueue :: TQueue a -> STM a
-- | A version of peekTQueue which does not retry. Instead it
-- returns Nothing if no value is available.
tryPeekTQueue :: TQueue a -> STM (Maybe a)
-- | A version of readTQueue which does not retry. Instead it
-- returns Nothing if no value is available.
tryReadTQueue :: TQueue a -> STM (Maybe a)
-- | Put a data item back onto a channel, where it will be the next item
-- read.
unGetTQueue :: TQueue a -> a -> STM ()
-- | Write a value to a TQueue.
writeTQueue :: TQueue a -> a -> STM ()
-- | TQueue is an abstract type representing an unbounded FIFO
-- channel.
data TQueue a
-- | Mutate the contents of a TVar. N.B., this version is
-- non-strict.
modifyTVar :: TVar a -> (a -> a) -> STM ()
-- | Strict version of modifyTVar.
modifyTVar' :: TVar a -> (a -> a) -> STM ()
-- | Like modifyTVar' but the function is a simple state transition
-- that can return a side value which is passed on as the result of the
-- STM.
stateTVar :: TVar s -> (s -> (a, s)) -> STM a
-- | Swap the contents of a TVar for a new value.
swapTVar :: TVar a -> a -> STM a
-- | Wrap up a synchronous exception to be treated as an asynchronous
-- exception
--
-- This is intended to be created via toAsyncException
data AsyncExceptionWrapper
AsyncExceptionWrapper :: e -> AsyncExceptionWrapper
-- | Wrap up an asynchronous exception to be treated as a synchronous
-- exception
--
-- This is intended to be created via toSyncException
data SyncExceptionWrapper
SyncExceptionWrapper :: e -> SyncExceptionWrapper
-- | Unlifted withCurrentDirectory.
withCurrentDirectory :: MonadUnliftIO m => FilePath -> m a -> m a
traceDisplayStack :: Display a => a -> b -> b
traceDisplayMarkerIO :: (Display a, MonadIO m) => a -> m ()
traceDisplayMarker :: Display a => a -> b -> b
traceDisplayEventIO :: (Display a, MonadIO m) => a -> m ()
traceDisplayEvent :: Display a => a -> b -> b
traceDisplayM :: (Display a, Applicative f) => a -> f ()
traceDisplayIO :: (Display a, MonadIO m) => a -> m ()
traceDisplayId :: Display a => a -> a
traceDisplay :: Display a => a -> b -> b
traceShowStack :: Show a => a -> b -> b
traceShowMarkerIO :: (Show a, MonadIO m) => a -> m ()
traceShowMarker :: Show a => a -> b -> b
traceShowEventIO :: (Show a, MonadIO m) => a -> m ()
traceShowEvent :: Show a => a -> b -> b
traceShowM :: (Show a, Applicative f) => a -> f ()
traceShowIO :: (Show a, MonadIO m) => a -> m ()
traceShowId :: Show a => a -> a
traceShow :: Show a => a -> b -> b
traceStack :: Text -> a -> a
traceMarkerIO :: MonadIO m => Text -> m ()
traceMarker :: Text -> a -> a
traceEventIO :: MonadIO m => Text -> m ()
traceEvent :: Text -> a -> a
traceM :: Applicative f => Text -> f ()
traceIO :: MonadIO m => Text -> m ()
traceId :: Text -> Text
trace :: Text -> a -> a
-- | Run with a default configured SimpleApp, consisting of:
--
--
-- - Logging to stderr
-- - If the RIO_VERBOSE environment variable is set, turns on
-- verbose logging
-- - Default process context
--
runSimpleApp :: MonadIO m => RIO SimpleApp a -> m a
-- | Constructor for SimpleApp. In case when ProcessContext
-- is not supplied mkDefaultProcessContext will be used to create
-- it.
mkSimpleApp :: MonadIO m => LogFunc -> Maybe ProcessContext -> m SimpleApp
-- | A simple, non-customizable environment type for RIO, which
-- provides common functionality. If it's insufficient for your needs,
-- define your own, custom App data type.
data SimpleApp
-- | create a new unboxed SomeRef
newUnboxedSomeRef :: (MonadIO m, Unbox a) => a -> m (SomeRef a)
-- | create a new boxed SomeRef
newSomeRef :: MonadIO m => a -> m (SomeRef a)
-- | Modify a SomeRef This function is subject to change due to the lack of
-- atomic operations
modifySomeRef :: MonadIO m => SomeRef a -> (a -> a) -> m ()
-- | Write to a SomeRef
writeSomeRef :: MonadIO m => SomeRef a -> a -> m ()
-- | Read from a SomeRef
readSomeRef :: MonadIO m => SomeRef a -> m a
-- | Lift one RIO env to another.
mapRIO :: (outer -> inner) -> RIO inner a -> RIO outer a
-- | Abstract RIO to an arbitrary MonadReader instance, which
-- can handle IO.
liftRIO :: (MonadIO m, MonadReader env m) => RIO env a -> m a
-- | Using the environment run in IO the action that requires that
-- environment.
runRIO :: MonadIO m => env -> RIO env a -> m a
-- | The Reader+IO monad. This is different from a ReaderT because:
--
--
-- - It's not a transformer, it hardcodes IO for simpler usage and
-- error messages.
-- - Instances of typeclasses like MonadLogger are implemented
-- using classes defined on the environment, instead of using an
-- underlying monad.
--
newtype RIO env a
RIO :: ReaderT env IO a -> RIO env a
[unRIO] :: RIO env a -> ReaderT env IO a
-- | Abstraction over how to read from and write to a mutable reference
data SomeRef a
-- | Environment values with stateful capabilities to SomeRef
class HasStateRef s env | env -> s
stateRefL :: HasStateRef s env => Lens' env (SomeRef s)
-- | Environment values with writing capabilities to SomeRef
class HasWriteRef w env | env -> w
writeRefL :: HasWriteRef w env => Lens' env (SomeRef w)
-- | Modify a value in a URef. Note that this action is strict, and
-- will force evaluation of the result value.
modifyURef :: (PrimMonad m, Unbox a) => URef (PrimState m) a -> (a -> a) -> m ()
-- | Write a value into a URef. Note that this action is strict, and
-- will force evalution of the value.
writeURef :: (PrimMonad m, Unbox a) => URef (PrimState m) a -> a -> m ()
-- | Read the value in a URef
readURef :: (PrimMonad m, Unbox a) => URef (PrimState m) a -> m a
-- | Create a new URef
newURef :: (PrimMonad m, Unbox a) => a -> m (URef (PrimState m) a)
-- | An unboxed reference. This works like an IORef, but the data is
-- stored in a bytearray instead of a heap object, avoiding significant
-- allocation overhead in some cases. For a concrete example, see this
-- Stack Overflow question:
-- https://stackoverflow.com/questions/27261813/why-is-my-little-stref-int-require-allocating-gigabytes.
--
-- The first parameter is the state token type, the same as would be used
-- for the ST monad. If you're using an IO-based monad, you
-- can use the convenience IOURef type synonym instead.
data URef s a
-- | Helpful type synonym for using a URef from an IO-based
-- stack.
type IOURef = URef PrimState IO
-- | Yield an immutable copy of the underlying mutable vector. The
-- difference from dequeToVector is that the the copy will be
-- performed with a more efficient memcpy, rather than element
-- by element. The downside is that the resulting vector type must be the
-- one that corresponds to the mutable one that is used in the
-- Deque.
--
-- Example
--
--
-- >>> :set -XTypeApplications
--
-- >>> import qualified RIO.Vector.Unboxed as U
--
-- >>> d <- newDeque @U.MVector @Int
--
-- >>> mapM_ (pushFrontDeque d) [0..10]
--
-- >>> freezeDeque @U.Vector d
-- [10,9,8,7,6,5,4,3,2,1,0]
--
freezeDeque :: (Vector v a, PrimMonad m) => Deque (Mutable v) (PrimState m) a -> m (v a)
-- | Convert to an immutable vector of any type. If resulting pure vector
-- corresponds to the mutable one used by the Deque, it will be
-- more efficient to use freezeDeque instead.
--
-- Example
--
--
-- >>> :set -XTypeApplications
--
-- >>> import qualified RIO.Vector.Unboxed as U
--
-- >>> import qualified RIO.Vector.Storable as S
--
-- >>> d <- newDeque @U.MVector @Int
--
-- >>> mapM_ (pushFrontDeque d) [0..10]
--
-- >>> dequeToVector @S.Vector d
-- [10,9,8,7,6,5,4,3,2,1,0]
--
dequeToVector :: forall v' a (v :: Type -> TYPE LiftedRep -> TYPE LiftedRep) m. (Vector v' a, MVector v a, PrimMonad m) => Deque v (PrimState m) a -> m (v' a)
-- | Convert a Deque into a list. Does not modify the Deque.
dequeToList :: forall (v :: Type -> TYPE LiftedRep -> TYPE LiftedRep) a m. (MVector v a, PrimMonad m) => Deque v (PrimState m) a -> m [a]
-- | Fold over a Deque, starting at the end. Does not modify the
-- Deque.
foldrDeque :: forall (v :: Type -> TYPE LiftedRep -> TYPE LiftedRep) a m acc. (MVector v a, PrimMonad m) => (a -> acc -> m acc) -> acc -> Deque v (PrimState m) a -> m acc
-- | Fold over a Deque, starting at the beginning. Does not modify
-- the Deque.
foldlDeque :: forall (v :: Type -> TYPE LiftedRep -> TYPE LiftedRep) a m acc. (MVector v a, PrimMonad m) => (acc -> a -> m acc) -> acc -> Deque v (PrimState m) a -> m acc
-- | Push a new value to the end of the Deque
pushBackDeque :: forall (v :: Type -> TYPE LiftedRep -> TYPE LiftedRep) a m. (MVector v a, PrimMonad m) => Deque v (PrimState m) a -> a -> m ()
-- | Push a new value to the beginning of the Deque
pushFrontDeque :: forall (v :: Type -> TYPE LiftedRep -> TYPE LiftedRep) a m. (MVector v a, PrimMonad m) => Deque v (PrimState m) a -> a -> m ()
-- | Pop the first value from the end of the Deque
popBackDeque :: forall (v :: Type -> TYPE LiftedRep -> TYPE LiftedRep) a m. (MVector v a, PrimMonad m) => Deque v (PrimState m) a -> m (Maybe a)
-- | Pop the first value from the beginning of the Deque
popFrontDeque :: forall (v :: Type -> TYPE LiftedRep -> TYPE LiftedRep) a m. (MVector v a, PrimMonad m) => Deque v (PrimState m) a -> m (Maybe a)
-- | O(1) - Get the number of elements that is currently in the
-- Deque
getDequeSize :: forall m (v :: Type -> Type -> Type) a. PrimMonad m => Deque v (PrimState m) a -> m Int
-- | Create a new, empty Deque
newDeque :: forall (v :: Type -> TYPE LiftedRep -> TYPE LiftedRep) a m. (MVector v a, PrimMonad m) => m (Deque v (PrimState m) a)
-- | Helper function to assist with type inference, forcing usage of a
-- boxed vector.
asBDeque :: BDeque s a -> BDeque s a
-- | Helper function to assist with type inference, forcing usage of a
-- storable vector.
asSDeque :: SDeque s a -> SDeque s a
-- | Helper function to assist with type inference, forcing usage of an
-- unboxed vector.
asUDeque :: UDeque s a -> UDeque s a
-- | A double-ended queue supporting any underlying vector type and any
-- monad.
--
-- This implements a circular double-ended queue with exponential growth.
data Deque (v :: Type -> Type -> Type) s a
-- | A Deque specialized to unboxed vectors.
type UDeque = Deque MVector
-- | A Deque specialized to storable vectors.
type SDeque = Deque MVector
-- | A Deque specialized to boxed vectors.
type BDeque = Deque MVector
-- | Read a file in UTF8 encoding, throwing an exception on invalid
-- character encoding.
--
-- This function will use OS-specific line ending handling.
readFileUtf8 :: MonadIO m => FilePath -> m Text
-- | Same as writeFile, but generalized to MonadIO
writeFileBinary :: MonadIO m => FilePath -> ByteString -> m ()
-- | Same as readFile, but generalized to MonadIO
readFileBinary :: MonadIO m => FilePath -> m ByteString
hPutBuilder :: MonadIO m => Handle -> Builder -> m ()
-- | Write a file in UTF8 encoding
--
-- This function will use OS-specific line ending handling.
writeFileUtf8 :: MonadIO m => FilePath -> Text -> m ()
-- | Lazily read a file in UTF8 encoding.
withLazyFileUtf8 :: MonadUnliftIO m => FilePath -> (Text -> m a) -> m a
-- | Lazily get the contents of a file. Unlike readFile, this
-- ensures that if an exception is thrown, the file handle is closed
-- immediately.
withLazyFile :: MonadUnliftIO m => FilePath -> (ByteString -> m a) -> m a
-- | Make a GLogFunc via classic LogFunc. Use this if you'd
-- like to log your generic data type via the classic RIO terminal
-- logger.
gLogFuncClassic :: (HasLogLevel msg, HasLogSource msg, Display msg) => LogFunc -> GLogFunc msg
-- | Log a value generically.
glog :: (MonadIO m, HasCallStack, HasGLogFunc env, MonadReader env m) => GMsg env -> m ()
-- | Make a custom generic logger. With this you could, for example, write
-- to a database or a log digestion service. For example:
--
--
-- mkGLogFunc (\stack msg -> send (Data.Aeson.encode (JsonLog stack msg)))
--
mkGLogFunc :: (CallStack -> msg -> IO ()) -> GLogFunc msg
-- | A contramap. Use this to wrap sub-loggers via mapRIO.
--
-- If you are on base > 4.12.0, you can just use contramap.
contramapGLogFunc :: (a -> b) -> GLogFunc b -> GLogFunc a
-- | A vesion of contramapMaybeGLogFunc which supports filering.
contramapMaybeGLogFunc :: (a -> Maybe b) -> GLogFunc b -> GLogFunc a
-- | Disable logging capabilities in a given sub-routine
--
-- Intended to skip logging in general purpose implementations, where
-- secrets might be logged accidently.
noLogging :: (HasLogFunc env, MonadReader env m) => m a -> m a
-- | What accent colors, indexed by Int, is the log func configured
-- to use?
--
-- Intended for use by code which wants to optionally add additional
-- color to its log messages.
logFuncAccentColorsL :: HasLogFunc env => SimpleGetter env (Int -> Utf8Builder)
-- | What color is the log func configured to use for secondary content?
--
-- Intended for use by code which wants to optionally add additional
-- color to its log messages.
logFuncSecondaryColorL :: HasLogFunc env => SimpleGetter env Utf8Builder
-- | What color is the log func configured to use for each LogLevel?
--
-- Intended for use by code which wants to optionally add additional
-- color to its log messages.
logFuncLogLevelColorsL :: HasLogFunc env => SimpleGetter env (LogLevel -> Utf8Builder)
-- | Is the log func configured to use color output?
--
-- Intended for use by code which wants to optionally add additional
-- color to its log messages.
logFuncUseColorL :: HasLogFunc env => SimpleGetter env Bool
-- | Convert a CallStack value into a Utf8Builder indicating
-- the first source location.
--
-- TODO Consider showing the entire call stack instead.
displayCallStack :: CallStack -> Utf8Builder
-- | Set format method for messages
--
-- Default: id
setLogFormat :: (Utf8Builder -> Utf8Builder) -> LogOptions -> LogOptions
-- | Use code location in the log output.
--
-- Default: True if in verbose mode, False otherwise.
setLogUseLoc :: Bool -> LogOptions -> LogOptions
-- | ANSI color codes for accents in the log output. Accent colors are
-- indexed by Int.
--
-- Default: const "\ESC[92m" -- Bright green, for all indicies
setLogAccentColors :: (Int -> Utf8Builder) -> LogOptions -> LogOptions
-- | ANSI color codes for secondary content in the log output.
--
-- Default: "\ESC[90m" -- Bright black (gray)
setLogSecondaryColor :: Utf8Builder -> LogOptions -> LogOptions
-- | ANSI color codes for LogLevel in the log output.
--
-- Default: LevelDebug = "\ESC[32m" -- Green LevelInfo =
-- "\ESC[34m" -- Blue LevelWarn = "\ESC[33m" -- Yellow
-- LevelError = "\ESC[31m" -- Red LevelOther _ = "\ESC[35m"
-- -- Magenta
setLogLevelColors :: (LogLevel -> Utf8Builder) -> LogOptions -> LogOptions
-- | Use ANSI color codes in the log output.
--
-- Default: True if in verbose mode and the Handle
-- is a terminal device.
setLogUseColor :: Bool -> LogOptions -> LogOptions
-- | Include the time when printing log messages.
--
-- Default: True in debug mode, False otherwise.
setLogUseTime :: Bool -> LogOptions -> LogOptions
-- | Do we treat output as a terminal. If True, we will enable
-- sticky logging functionality.
--
-- Default: checks if the Handle provided to
-- logOptionsHandle is a terminal with hIsTerminalDevice.
setLogTerminal :: Bool -> LogOptions -> LogOptions
-- | Refer to setLogVerboseFormat. This modifier allows to alter the
-- verbose format value dynamically at runtime.
--
-- Default: follows the value of the verbose flag.
setLogVerboseFormatIO :: IO Bool -> LogOptions -> LogOptions
-- | Use the verbose format for printing log messages.
--
-- Default: follows the value of the verbose flag.
setLogVerboseFormat :: Bool -> LogOptions -> LogOptions
-- | Refer to setLogMinLevel. This modifier allows to alter the
-- verbose format value dynamically at runtime.
--
-- Default: in verbose mode, LevelDebug. Otherwise,
-- LevelInfo.
setLogMinLevelIO :: IO LogLevel -> LogOptions -> LogOptions
-- | Set the minimum log level. Messages below this level will not be
-- printed.
--
-- Default: in verbose mode, LevelDebug. Otherwise,
-- LevelInfo.
setLogMinLevel :: LogLevel -> LogOptions -> LogOptions
-- | Given a LogOptions value, run the given function with the
-- specified LogFunc. A common way to use this function is:
--
--
-- let isVerbose = False -- get from the command line instead
-- logOptions' <- logOptionsHandle stderr isVerbose
-- let logOptions = setLogUseTime True logOptions'
-- withLogFunc logOptions $ \lf -> do
-- let app = App -- application specific environment
-- { appLogFunc = lf
-- , appOtherStuff = ...
-- }
-- runRIO app $ do
-- logInfo "Starting app"
-- myApp
--
withLogFunc :: MonadUnliftIO m => LogOptions -> (LogFunc -> m a) -> m a
-- | Given a LogOptions value, returns both a new LogFunc and
-- a sub-routine that disposes it.
--
-- Intended for use if you want to deal with the teardown of
-- LogFunc yourself, otherwise prefer the withLogFunc
-- function instead.
newLogFunc :: (MonadIO n, MonadIO m) => LogOptions -> n (LogFunc, m ())
-- | Create a LogOptions value from the given Handle and
-- whether to perform verbose logging or not. Individiual settings can be
-- overridden using appropriate set functions. Logging output is
-- guaranteed to be non-interleaved only for a UTF-8 Handle in a
-- multi-thread environment.
--
-- When Verbose Flag is True, the following happens:
--
--
-- - setLogVerboseFormat is called with True
-- - setLogUseColor is called with True (except on
-- Windows)
-- - setLogUseLoc is called with True
-- - setLogUseTime is called with True
-- - setLogMinLevel is called with Debug log
-- level
--
logOptionsHandle :: MonadIO m => Handle -> Bool -> m LogOptions
-- | Create a LogOptions value which will store its data in memory.
-- This is primarily intended for testing purposes. This will return both
-- a LogOptions value and an IORef containing the resulting
-- Builder value.
--
-- This will default to non-verbose settings and assume there is a
-- terminal attached. These assumptions can be overridden using the
-- appropriate set functions.
logOptionsMemory :: MonadIO m => m (IORef Builder, LogOptions)
-- | This will print out the given message with a newline and disable any
-- further stickiness of the line until a new call to logSticky
-- happens.
logStickyDone :: (MonadIO m, HasCallStack, MonadReader env m, HasLogFunc env) => Utf8Builder -> m ()
-- | Write a "sticky" line to the terminal. Any subsequent lines will
-- overwrite this one, and that same line will be repeated below again.
-- In other words, the line sticks at the bottom of the output forever.
-- Running this function again will replace the sticky line with a new
-- sticky line. When you want to get rid of the sticky line, run
-- logStickyDone.
--
-- Note that not all LogFunc implementations will support sticky
-- messages as described. However, the withLogFunc implementation
-- provided by this module does.
logSticky :: (MonadIO m, HasCallStack, MonadReader env m, HasLogFunc env) => Utf8Builder -> m ()
-- | Generic, basic function for creating other logging functions.
logGeneric :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => LogSource -> LogLevel -> Utf8Builder -> m ()
-- | Create a LogFunc from the given function.
mkLogFunc :: (CallStack -> LogSource -> LogLevel -> Utf8Builder -> IO ()) -> LogFunc
-- | Environment values with a logging function.
class HasLogFunc env
logFuncL :: HasLogFunc env => Lens' env LogFunc
-- | A logging function, wrapped in a newtype for better error messages.
--
-- An implementation may choose any behavior of this value it wishes,
-- including printing to standard output or no action at all.
data LogFunc
-- | Configuration for how to create a LogFunc. Intended to be used
-- with the withLogFunc function.
data LogOptions
type family GMsg env
-- | An app is capable of generic logging if it implements this.
class HasGLogFunc env where {
type family GMsg env;
}
gLogFuncL :: HasGLogFunc env => Lens' env (GLogFunc (GMsg env))
-- | A generic logger of some type msg.
--
-- Your GLocFunc can re-use the existing classical logging
-- framework of RIO, and/or implement additional transforms, filters.
-- Alternatively, you may log to a JSON source in a database, or anywhere
-- else as needed. You can decide how to log levels or severities based
-- on the constructors in your type. You will normally determine this in
-- your main app entry point.
data GLogFunc msg
-- | Level, if any, of your logs. If unknown, use LogOther. Use
-- for your generic log data types that want to sit inside the classic
-- log framework.
class HasLogLevel msg
getLogLevel :: HasLogLevel msg => msg -> LogLevel
-- | Source of a log. This can be whatever you want. Use for your generic
-- log data types that want to sit inside the classic log framework.
class HasLogSource msg
getLogSource :: HasLogSource msg => msg -> LogSource
decodeUtf8Lenient :: ByteString -> Text
tshow :: Show a => a -> Text
yieldThread :: MonadIO m => m ()
fromStrictBytes :: ByteString -> LByteString
toStrictBytes :: LByteString -> ByteString
sappend :: Semigroup s => s -> s -> s
type UVector = Vector
type SVector = Vector
type GVector = Vector
type LByteString = ByteString
type LText = Text
-- | Helper function to force an action to run in IO. Especially
-- useful for overly general contexts, like hspec tests.
asIO :: IO a -> IO a
-- | Run the second value if the first value returns False
unlessM :: Monad m => m Bool -> m () -> m ()
-- | Run the second value if the first value returns True
whenM :: Monad m => m Bool -> m () -> m ()
-- | Strip out duplicates
nubOrd :: Ord a => [a] -> [a]
-- | Extend foldMap to allow side effects.
--
-- Internally, this is implemented using a strict left fold. This is used
-- for performance reasons. It also necessitates that this function has a
-- Monad constraint and not just an Applicative
-- constraint. For more information, see
-- https://github.com/commercialhaskell/rio/pull/99#issuecomment-394179757.
foldMapM :: (Monad m, Monoid w, Foldable t) => (a -> m w) -> t a -> m w
-- |
-- forMaybeM == flip mapMaybeM
--
forMaybeM :: Monad m => [a] -> (a -> m (Maybe b)) -> m [b]
-- | Monadic mapMaybe.
mapMaybeM :: Monad m => (a -> m (Maybe b)) -> [a] -> m [b]
-- |
-- forMaybeA == flip mapMaybeA
--
forMaybeA :: Applicative f => [a] -> (a -> f (Maybe b)) -> f [b]
-- | Applicative mapMaybe.
mapMaybeA :: Applicative f => (a -> f (Maybe b)) -> [a] -> f [b]
-- | Get a First value with a default fallback
fromFirst :: a -> First a -> a
-- | Apply a function to a Left constructor
mapLeft :: (a1 -> a2) -> Either a1 b -> Either a2 b
-- | Lifted version of "System.Exit.exitWith".
--
-- @since 0.1.9.0.
exitWith :: MonadIO m => ExitCode -> m a
-- | Lifted version of "System.Exit.exitSuccess".
--
-- @since 0.1.9.0.
exitSuccess :: MonadIO m => m a
-- | Lifted version of "System.Exit.exitFailure".
--
-- @since 0.1.9.0.
exitFailure :: MonadIO m => m a
-- | Write the given Utf8Builder value to a file.
writeFileUtf8Builder :: MonadIO m => FilePath -> Utf8Builder -> m ()
-- | Convert a Utf8Builder value into a lazy Text.
utf8BuilderToLazyText :: Utf8Builder -> Text
-- | Convert a Utf8Builder value into a strict Text.
utf8BuilderToText :: Utf8Builder -> Text
-- | Convert a ByteString into a Utf8Builder.
--
-- NOTE This function performs no checks to ensure that the data
-- is, in fact, UTF8 encoded. If you provide non-UTF8 data, later
-- functions may fail.
displayBytesUtf8 :: ByteString -> Utf8Builder
-- | Use the Show instance for a value to convert it to a
-- Utf8Builder.
displayShow :: Show a => a -> Utf8Builder
-- | A builder of binary data, with the invariant that the underlying data
-- is supposed to be UTF-8 encoded.
newtype Utf8Builder
Utf8Builder :: Builder -> Utf8Builder
[getUtf8Builder] :: Utf8Builder -> Builder
-- | A typeclass for values which can be converted to a Utf8Builder.
-- The intention of this typeclass is to provide a human-friendly display
-- of the data.
class Display a
display :: Display a => a -> Utf8Builder
-- | Display data as Text, which will also be used for
-- display if it is not overriden.
textDisplay :: Display a => a -> Text
-- | Unlifted version of withBinaryFile.
withBinaryFile :: MonadUnliftIO m => FilePath -> IOMode -> (Handle -> m a) -> m a
-- | Lifted version of myThreadId.
myThreadId :: MonadIO m => m ThreadId
-- | Lifted version of threadDelay.
threadDelay :: MonadIO m => Int -> m ()
-- | Lifted version of threadWaitRead.
threadWaitRead :: MonadIO m => Fd -> m ()
-- | Lifted version of threadWaitWrite.
threadWaitWrite :: MonadIO m => Fd -> m ()
-- | Lifted version of isCurrentThreadBound.
isCurrentThreadBound :: MonadIO m => m Bool
-- | Replace an invalid input byte with the Unicode replacement character
-- U+FFFD.
lenientDecode :: OnDecodeError
-- | An exception type for representing Unicode encoding errors.
data UnicodeException
-- | Could not decode a byte sequence because it was invalid under the
-- given encoding, or ran out of input in mid-decode.
DecodeError :: String -> Maybe Word8 -> UnicodeException
-- | Tried to encode a character that could not be represented under the
-- given encoding, or ran out of input in mid-encode.
EncodeError :: String -> Maybe Char -> UnicodeException
-- | Decode a ByteString containing UTF-8 encoded text.
--
-- If the input contains any invalid UTF-8 data, the relevant exception
-- will be returned, otherwise the decoded text.
decodeUtf8' :: ByteString -> Either UnicodeException Text
-- | Decode a ByteString containing UTF-8 encoded text.
--
-- NOTE: The replacement character returned by
-- OnDecodeError MUST be within the BMP plane; surrogate code
-- points will automatically be remapped to the replacement char
-- U+FFFD (since 0.11.3.0), whereas code points beyond
-- the BMP will throw an error (since 1.2.3.1); For earlier
-- versions of text using those unsupported code points would
-- result in undefined behavior.
decodeUtf8With :: OnDecodeError -> ByteString -> Text
-- | Encode text to a ByteString Builder using UTF-8 encoding.
encodeUtf8Builder :: Text -> Builder
decodeUtf8 :: ByteString -> Text
maybeLens :: a -> Lens' (Maybe a) a
module Stackctl.OneOrListOf
-- | Type representing one a or a list of a
--
-- This type is isomorphic both NonEmpty a and
-- Either a [a]. Its primary use-case is to parse Yaml
-- (through its FromJSON) where users may specify a list of
-- values, but specifying a single value is worth supporting, typically
-- for backwards-compatibility:
--
--
-- something:
-- field:
-- - one
-- - two
--
-- something:
-- field: one # => should be treated like field: [one]
--
--
-- The Foldable instance should be used to treat the value like a
-- list, such as extracting it directly via toList.
--
-- Implementation note: this type preserves the form in which it was
-- decoded (in other words, it's not a newtype over one of the
-- isomorphic types mentioned above), so that we can encode it back out
-- in the same format.
data OneOrListOf a
fromList :: [a] -> OneOrListOf a
instance Data.Foldable.Foldable Stackctl.OneOrListOf.OneOrListOf
instance GHC.Generics.Generic (Stackctl.OneOrListOf.OneOrListOf a)
instance GHC.Show.Show a => GHC.Show.Show (Stackctl.OneOrListOf.OneOrListOf a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Stackctl.OneOrListOf.OneOrListOf a)
instance GHC.Base.Semigroup (Stackctl.OneOrListOf.OneOrListOf a)
instance Data.Aeson.Types.FromJSON.FromJSON a => Data.Aeson.Types.FromJSON.FromJSON (Stackctl.OneOrListOf.OneOrListOf a)
instance Data.Aeson.Types.ToJSON.ToJSON a => Data.Aeson.Types.ToJSON.ToJSON (Stackctl.OneOrListOf.OneOrListOf a)
module Stackctl.DirectoryOption
newtype DirectoryOption
DirectoryOption :: FilePath -> DirectoryOption
[unDirectoryOption] :: DirectoryOption -> FilePath
defaultDirectoryOption :: DirectoryOption
class HasDirectoryOption env
directoryOptionL :: HasDirectoryOption env => Lens' env DirectoryOption
envDirectoryOption :: Parser Error DirectoryOption
directoryOption :: Parser DirectoryOption
instance GHC.Base.Semigroup Stackctl.DirectoryOption.DirectoryOption
instance Data.String.IsString Stackctl.DirectoryOption.DirectoryOption
instance Stackctl.DirectoryOption.HasDirectoryOption Stackctl.DirectoryOption.DirectoryOption
module Stackctl.Config.RequiredVersion
data RequiredVersion
RequiredVersion :: RequiredVersionOp -> Version -> RequiredVersion
[requiredVersionOp] :: RequiredVersion -> RequiredVersionOp
[requiredVersionCompareWith] :: RequiredVersion -> Version
data RequiredVersionOp
RequiredVersionEQ :: RequiredVersionOp
RequiredVersionLT :: RequiredVersionOp
RequiredVersionLTE :: RequiredVersionOp
RequiredVersionGT :: RequiredVersionOp
RequiredVersionGTE :: RequiredVersionOp
RequiredVersionIsh :: RequiredVersionOp
requiredVersionToText :: RequiredVersion -> Text
requiredVersionFromText :: Text -> Either String RequiredVersion
isRequiredVersionSatisfied :: RequiredVersion -> Version -> Bool
(=~) :: Version -> Version -> Bool
instance GHC.Enum.Enum Stackctl.Config.RequiredVersion.RequiredVersionOp
instance GHC.Enum.Bounded Stackctl.Config.RequiredVersion.RequiredVersionOp
instance GHC.Show.Show Stackctl.Config.RequiredVersion.RequiredVersionOp
instance GHC.Classes.Eq Stackctl.Config.RequiredVersion.RequiredVersionOp
instance GHC.Show.Show Stackctl.Config.RequiredVersion.RequiredVersion
instance GHC.Classes.Eq Stackctl.Config.RequiredVersion.RequiredVersion
instance Test.QuickCheck.Arbitrary.Arbitrary Stackctl.Config.RequiredVersion.RequiredVersion
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.Config.RequiredVersion.RequiredVersion
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.Config.RequiredVersion.RequiredVersion
instance Test.QuickCheck.Arbitrary.Arbitrary Stackctl.Config.RequiredVersion.RequiredVersionOp
module Stackctl.ColorOption
newtype ColorOption
ColorOption :: LogColor -> ColorOption
[unColorOption] :: ColorOption -> LogColor
class HasColorOption env
colorOptionL :: HasColorOption env => Lens' env (Maybe ColorOption)
colorOption :: Parser ColorOption
instance GHC.Base.Semigroup Stackctl.ColorOption.ColorOption
-- | Orphans so we can get ToJSON ChangeSet
-- without hand-writing a massive, incomplete, and doomed-to-drift
-- instance ourselves.
module Stackctl.AWS.Orphans
instance Data.Aeson.Types.FromJSON.FromJSON Amazonka.CloudFormation.Types.Change.Change
instance Data.Aeson.Types.ToJSON.ToJSON Amazonka.CloudFormation.Types.Change.Change
instance Data.Aeson.Types.FromJSON.FromJSON Amazonka.CloudFormation.DescribeChangeSet.DescribeChangeSetResponse
instance Data.Aeson.Types.ToJSON.ToJSON Amazonka.CloudFormation.DescribeChangeSet.DescribeChangeSetResponse
instance Data.Aeson.Types.FromJSON.FromJSON Amazonka.CloudFormation.Types.ModuleInfo.ModuleInfo
instance Data.Aeson.Types.ToJSON.ToJSON Amazonka.CloudFormation.Types.ModuleInfo.ModuleInfo
instance Data.Aeson.Types.FromJSON.FromJSON Amazonka.CloudFormation.Types.Parameter.Parameter
instance Data.Aeson.Types.ToJSON.ToJSON Amazonka.CloudFormation.Types.Parameter.Parameter
instance Data.Aeson.Types.FromJSON.FromJSON Amazonka.CloudFormation.Types.ResourceChange.ResourceChange
instance Data.Aeson.Types.ToJSON.ToJSON Amazonka.CloudFormation.Types.ResourceChange.ResourceChange
instance Data.Aeson.Types.FromJSON.FromJSON Amazonka.CloudFormation.Types.ResourceChangeDetail.ResourceChangeDetail
instance Data.Aeson.Types.ToJSON.ToJSON Amazonka.CloudFormation.Types.ResourceChangeDetail.ResourceChangeDetail
instance Data.Aeson.Types.FromJSON.FromJSON Amazonka.CloudFormation.Types.ResourceTargetDefinition.ResourceTargetDefinition
instance Data.Aeson.Types.ToJSON.ToJSON Amazonka.CloudFormation.Types.ResourceTargetDefinition.ResourceTargetDefinition
instance Data.Aeson.Types.FromJSON.FromJSON Amazonka.CloudFormation.Types.RollbackConfiguration.RollbackConfiguration
instance Data.Aeson.Types.ToJSON.ToJSON Amazonka.CloudFormation.Types.RollbackConfiguration.RollbackConfiguration
instance Data.Aeson.Types.FromJSON.FromJSON Amazonka.CloudFormation.Types.RollbackTrigger.RollbackTrigger
instance Data.Aeson.Types.ToJSON.ToJSON Amazonka.CloudFormation.Types.RollbackTrigger.RollbackTrigger
instance Data.Aeson.Types.FromJSON.FromJSON Amazonka.CloudFormation.Types.Tag.Tag
instance Data.Aeson.Types.ToJSON.ToJSON Amazonka.CloudFormation.Types.Tag.Tag
instance (GHC.Generics.Generic a, Data.Aeson.Types.FromJSON.GFromJSON Data.Aeson.Types.Generic.Zero (GHC.Generics.Rep a)) => Data.Aeson.Types.FromJSON.FromJSON (Stackctl.AWS.Orphans.Generically a)
instance (GHC.Generics.Generic a, Data.Aeson.Types.ToJSON.GToJSON' Data.Aeson.Types.Internal.Value Data.Aeson.Types.Generic.Zero (GHC.Generics.Rep a), Data.Aeson.Types.ToJSON.GToJSON' Data.Aeson.Encoding.Internal.Encoding Data.Aeson.Types.Generic.Zero (GHC.Generics.Rep a)) => Data.Aeson.Types.ToJSON.ToJSON (Stackctl.AWS.Orphans.Generically a)
module Stackctl.AWS.Core
data AwsEnv
class HasAwsEnv env
awsEnvL :: HasAwsEnv env => Lens' env AwsEnv
awsEnvDiscover :: MonadLoggerIO m => m AwsEnv
awsWithAuth :: (MonadIO m, MonadReader env m, HasAwsEnv env) => (AuthEnv -> m a) -> m a
awsSimple :: forall a env m b. (HasCallStack, MonadResource m, MonadReader env m, HasAwsEnv env, AWSRequest a, Typeable a, Typeable (AWSResponse a)) => a -> (AWSResponse a -> Maybe b) -> m b
awsSend :: (MonadResource m, MonadReader env m, HasAwsEnv env, AWSRequest a, Typeable a, Typeable (AWSResponse a)) => a -> m (AWSResponse a)
awsPaginate :: (MonadResource m, MonadReader env m, HasAwsEnv env, AWSPager a, Typeable a, Typeable (AWSResponse a)) => a -> ConduitM () (AWSResponse a) m ()
awsAwait :: (MonadResource m, MonadReader env m, HasAwsEnv env, AWSRequest a, Typeable a) => Wait a -> a -> m Accept
awsAssumeRole :: (MonadResource m, MonadReader env m, HasAwsEnv env) => Text -> Text -> m a -> m a
awsWithin :: (MonadReader env m, HasAwsEnv env) => Region -> m a -> m a
awsTimeout :: (MonadReader env m, HasAwsEnv env) => Seconds -> m a -> m a
awsSilently :: (MonadReader env m, HasAwsEnv env) => m a -> m a
newtype AccountId
AccountId :: Text -> AccountId
[unAccountId] :: AccountId -> Text
-- | Handle Error, log it and exitFailure
--
-- This is useful at the top-level of the app, where we'd be crashing
-- anyway. It makes things more readable and easier to debug.
handlingServiceError :: (MonadUnliftIO m, MonadLogger m) => m a -> m a
formatServiceError :: ServiceError -> Text
-- | The available AWS regions.
newtype Region
Region' :: Text -> Region
[$sel:fromRegion:Region'] :: Region -> Text
pattern Ohio :: Region
pattern NorthVirginia :: Region
pattern NorthCalifornia :: Region
pattern Oregon :: Region
pattern CapeTown :: Region
pattern HongKong :: Region
pattern Hyderabad :: Region
pattern Jakarta :: Region
pattern Melbourne :: Region
pattern Mumbai :: Region
pattern Osaka :: Region
pattern Seoul :: Region
pattern Singapore :: Region
pattern Sydney :: Region
pattern Tokyo :: Region
pattern Montreal :: Region
pattern Frankfurt :: Region
pattern Ireland :: Region
pattern London :: Region
pattern Milan :: Region
pattern Paris :: Region
pattern Spain :: Region
pattern Stockholm :: Region
pattern Zurich :: Region
pattern Bahrain :: Region
pattern UAE :: Region
pattern SaoPaulo :: Region
pattern GovCloudEast :: Region
pattern GovCloudWest :: Region
pattern Beijing :: Region
pattern Ningxia :: Region
class FromText a
fromText :: FromText a => Text -> Either String a
class ToText a
toText :: ToText a => a -> Text
-- | A Monad which allows for safe resource allocation. In theory,
-- any monad transformer stack which includes a ResourceT can be
-- an instance of MonadResource.
--
-- Note: runResourceT has a requirement for a MonadUnliftIO
-- m monad, which allows control operations to be lifted. A
-- MonadResource does not have this requirement. This means that
-- transformers such as ContT can be an instance of
-- MonadResource. However, the ContT wrapper will need
-- to be unwrapped before calling runResourceT.
--
-- Since 0.3.0
class MonadIO m => MonadResource (m :: Type -> Type)
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.AWS.Core.AccountId
instance GHC.Show.Show Stackctl.AWS.Core.AccountId
instance GHC.Classes.Ord Stackctl.AWS.Core.AccountId
instance GHC.Classes.Eq Stackctl.AWS.Core.AccountId
instance Stackctl.AWS.Core.HasAwsEnv Stackctl.AWS.Core.AwsEnv
module Stackctl.AWS.STS
awsGetCallerIdentityAccount :: (MonadResource m, MonadReader env m, HasAwsEnv env) => m AccountId
module Stackctl.AWS.Lambda
data LambdaInvokeResult
LambdaInvokeSuccess :: ByteString -> LambdaInvokeResult
LambdaInvokeError :: LambdaError -> Maybe Text -> LambdaInvokeResult
LambdaInvokeFailure :: Int -> Maybe Text -> LambdaInvokeResult
data LambdaError
LambdaError :: Text -> Text -> [Text] -> LambdaError
[errorType] :: LambdaError -> Text
[errorMessage] :: LambdaError -> Text
[trace] :: LambdaError -> [Text]
logLambdaInvocationResult :: MonadLogger m => LambdaInvokeResult -> m ()
isLambdaInvocationSuccess :: LambdaInvokeResult -> Bool
awsLambdaInvoke :: (MonadResource m, MonadLogger m, MonadReader env m, HasAwsEnv env, ToJSON a) => Text -> a -> m LambdaInvokeResult
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.AWS.Lambda.LambdaError
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.AWS.Lambda.LambdaError
instance GHC.Generics.Generic Stackctl.AWS.Lambda.LambdaError
instance GHC.Show.Show Stackctl.AWS.Lambda.LambdaError
instance GHC.Show.Show Stackctl.AWS.Lambda.LambdaInvokeResult
module Stackctl.AWS.EC2
awsEc2DescribeFirstAvailabilityZoneRegionName :: (MonadResource m, MonadReader env m, HasAwsEnv env) => m Region
module Stackctl.Prompt
prompt :: (MonadIO m, MonadLogger m, MonadReader env m, HasLogger env) => Text -> (Text -> Either Text a) -> (a -> m r) -> m r
promptContinue :: (MonadIO m, MonadLogger m, MonadReader env m, HasLogger env) => m ()
promptOrExit :: (MonadIO m, MonadLogger m, MonadReader env m, HasLogger env) => Text -> m ()
module Stackctl.AutoSSO
data AutoSSOOption
defaultAutoSSOOption :: AutoSSOOption
class HasAutoSSOOption env
autoSSOOptionL :: HasAutoSSOOption env => Lens' env AutoSSOOption
autoSSOOption :: Parser AutoSSOOption
envAutoSSOOption :: Parser Error AutoSSOOption
handleAutoSSO :: (MonadUnliftIO m, MonadReader env m, MonadLogger m, HasLogger env, HasAutoSSOOption options) => options -> m a -> m a
instance GHC.Base.Semigroup Stackctl.AutoSSO.AutoSSOOption
module Stackctl.Sort
sortByDependencies :: Ord k => (a -> k) -> (a -> [k]) -> [a] -> [a]
module Stackctl.StackDescription
newtype StackDescription
StackDescription :: Text -> StackDescription
[unStackDescription] :: StackDescription -> Text
addStackDescription :: Maybe StackDescription -> Text -> Text
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.StackDescription.StackDescription
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.StackDescription.StackDescription
instance GHC.Show.Show Stackctl.StackDescription.StackDescription
instance GHC.Classes.Ord Stackctl.StackDescription.StackDescription
instance GHC.Classes.Eq Stackctl.StackDescription.StackDescription
module Stackctl.AWS.CloudFormation
-- | The Stack data type.
--
-- See: newStack smart constructor.
data Stack
Stack' :: Maybe [Capability] -> Maybe Text -> Maybe ISO8601 -> Maybe Text -> Maybe Bool -> Maybe StackDriftInformation -> Maybe Bool -> Maybe ISO8601 -> Maybe [Text] -> Maybe [Output] -> Maybe [Parameter] -> Maybe Text -> Maybe Text -> Maybe RollbackConfiguration -> Maybe Text -> Maybe Text -> Maybe Text -> Maybe [Tag] -> Maybe Natural -> Text -> ISO8601 -> StackStatus -> Stack
-- | The capabilities allowed in the stack.
[$sel:capabilities:Stack'] :: Stack -> Maybe [Capability]
-- | The unique ID of the change set.
[$sel:changeSetId:Stack'] :: Stack -> Maybe Text
-- | The time the stack was deleted.
[$sel:deletionTime:Stack'] :: Stack -> Maybe ISO8601
-- | A user-defined description associated with the stack.
[$sel:description:Stack'] :: Stack -> Maybe Text
-- | Boolean to enable or disable rollback on stack creation failures:
--
--
-- - true: disable rollback.
-- - false: enable rollback.
--
[$sel:disableRollback:Stack'] :: Stack -> Maybe Bool
-- | Information about whether a stack's actual configuration differs, or
-- has drifted, from it's expected configuration, as defined in
-- the stack template and any values specified as template parameters.
-- For more information, see Detecting Unregulated Configuration
-- Changes to Stacks and Resources.
[$sel:driftInformation:Stack'] :: Stack -> Maybe StackDriftInformation
-- | Whether termination protection is enabled for the stack.
--
-- For nested stacks, termination protection is set on the root
-- stack and can't be changed directly on the nested stack. For more
-- information, see Protecting a Stack From Being Deleted in the
-- CloudFormation User Guide.
[$sel:enableTerminationProtection:Stack'] :: Stack -> Maybe Bool
-- | The time the stack was last updated. This field will only be returned
-- if the stack has been updated at least once.
[$sel:lastUpdatedTime:Stack'] :: Stack -> Maybe ISO8601
-- | Amazon SNS topic Amazon Resource Names (ARNs) to which stack related
-- events are published.
[$sel:notificationARNs:Stack'] :: Stack -> Maybe [Text]
-- | A list of output structures.
[$sel:outputs:Stack'] :: Stack -> Maybe [Output]
-- | A list of Parameter structures.
[$sel:parameters:Stack'] :: Stack -> Maybe [Parameter]
-- | For nested stacks--stacks created as resources for another stack--the
-- stack ID of the direct parent of this stack. For the first level of
-- nested stacks, the root stack is also the parent stack.
--
-- For more information, see Working with Nested Stacks in the
-- CloudFormation User Guide.
[$sel:parentId:Stack'] :: Stack -> Maybe Text
-- | The Amazon Resource Name (ARN) of an Identity and Access Management
-- (IAM) role that's associated with the stack. During a stack operation,
-- CloudFormation uses this role's credentials to make calls on your
-- behalf.
[$sel:roleARN:Stack'] :: Stack -> Maybe Text
-- | The rollback triggers for CloudFormation to monitor during stack
-- creation and updating operations, and for the specified monitoring
-- period afterwards.
[$sel:rollbackConfiguration:Stack'] :: Stack -> Maybe RollbackConfiguration
-- | For nested stacks--stacks created as resources for another stack--the
-- stack ID of the top-level stack to which the nested stack ultimately
-- belongs.
--
-- For more information, see Working with Nested Stacks in the
-- CloudFormation User Guide.
[$sel:rootId:Stack'] :: Stack -> Maybe Text
-- | Unique identifier of the stack.
[$sel:stackId:Stack'] :: Stack -> Maybe Text
-- | Success/failure message associated with the stack status.
[$sel:stackStatusReason:Stack'] :: Stack -> Maybe Text
-- | A list of Tags that specify information about the stack.
[$sel:tags:Stack'] :: Stack -> Maybe [Tag]
-- | The amount of time within which stack creation should complete.
[$sel:timeoutInMinutes:Stack'] :: Stack -> Maybe Natural
-- | The name associated with the stack.
[$sel:stackName:Stack'] :: Stack -> Text
-- | The time at which the stack was created.
[$sel:creationTime:Stack'] :: Stack -> ISO8601
-- | Current status of the stack.
[$sel:stackStatus:Stack'] :: Stack -> StackStatus
-- | The name associated with the stack.
stack_stackName :: Lens' Stack Text
-- | Current status of the stack.
stack_stackStatus :: Lens' Stack StackStatus
stackDescription :: Stack -> Maybe StackDescription
stackStatusRequiresDeletion :: Stack -> Maybe StackStatus
newtype StackId
StackId :: Text -> StackId
[unStackId] :: StackId -> Text
newtype StackName
StackName :: Text -> StackName
[unStackName] :: StackName -> Text
newtype StackDescription
StackDescription :: Text -> StackDescription
[unStackDescription] :: StackDescription -> Text
newtype StackStatus
StackStatus' :: Text -> StackStatus
[fromStackStatus] :: StackStatus -> Text
pattern StackStatus_UPDATE_ROLLBACK_IN_PROGRESS :: StackStatus
pattern StackStatus_UPDATE_ROLLBACK_FAILED :: StackStatus
pattern StackStatus_UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS :: StackStatus
pattern StackStatus_UPDATE_ROLLBACK_COMPLETE :: StackStatus
pattern StackStatus_UPDATE_IN_PROGRESS :: StackStatus
pattern StackStatus_UPDATE_FAILED :: StackStatus
pattern StackStatus_UPDATE_COMPLETE_CLEANUP_IN_PROGRESS :: StackStatus
pattern StackStatus_UPDATE_COMPLETE :: StackStatus
pattern StackStatus_ROLLBACK_IN_PROGRESS :: StackStatus
pattern StackStatus_ROLLBACK_FAILED :: StackStatus
pattern StackStatus_ROLLBACK_COMPLETE :: StackStatus
pattern StackStatus_REVIEW_IN_PROGRESS :: StackStatus
pattern StackStatus_IMPORT_ROLLBACK_IN_PROGRESS :: StackStatus
pattern StackStatus_IMPORT_ROLLBACK_FAILED :: StackStatus
pattern StackStatus_IMPORT_ROLLBACK_COMPLETE :: StackStatus
pattern StackStatus_IMPORT_IN_PROGRESS :: StackStatus
pattern StackStatus_IMPORT_COMPLETE :: StackStatus
pattern StackStatus_DELETE_IN_PROGRESS :: StackStatus
pattern StackStatus_DELETE_FAILED :: StackStatus
pattern StackStatus_DELETE_COMPLETE :: StackStatus
pattern StackStatus_CREATE_IN_PROGRESS :: StackStatus
pattern StackStatus_CREATE_FAILED :: StackStatus
pattern StackStatus_CREATE_COMPLETE :: StackStatus
-- | The StackEvent data type.
--
-- See: newStackEvent smart constructor.
data StackEvent
StackEvent' :: Maybe Text -> Maybe HookFailureMode -> Maybe HookInvocationPoint -> Maybe HookStatus -> Maybe Text -> Maybe Text -> Maybe Text -> Maybe Text -> Maybe Text -> Maybe ResourceStatus -> Maybe Text -> Maybe Text -> Text -> Text -> Text -> ISO8601 -> StackEvent
-- | The token passed to the operation that generated this event.
--
-- All events triggered by a given stack operation are assigned the same
-- client request token, which you can use to track operations. For
-- example, if you execute a CreateStack operation with the
-- token token1, then all the StackEvents generated by
-- that operation will have ClientRequestToken set as
-- token1.
--
-- In the console, stack operations display the client request token on
-- the Events tab. Stack operations that are initiated from the console
-- use the token format Console-StackOperation-ID, which helps you
-- easily identify the stack operation . For example, if you create a
-- stack using the console, each stack event would be assigned the same
-- token in the following format:
-- Console-CreateStack-7f59c3cf-00d2-40c7-b2ff-e75db0987002.
[$sel:clientRequestToken:StackEvent'] :: StackEvent -> Maybe Text
-- | Specify the hook failure mode for non-compliant resources in the
-- followings ways.
--
--
-- - FAIL Stops provisioning resources.
-- - WARN Allows provisioning to continue with a warning
-- message.
--
[$sel:hookFailureMode:StackEvent'] :: StackEvent -> Maybe HookFailureMode
-- | Invocation points are points in provisioning logic where hooks are
-- initiated.
[$sel:hookInvocationPoint:StackEvent'] :: StackEvent -> Maybe HookInvocationPoint
-- | Provides the status of the change set hook.
[$sel:hookStatus:StackEvent'] :: StackEvent -> Maybe HookStatus
-- | Provides the reason for the hook status.
[$sel:hookStatusReason:StackEvent'] :: StackEvent -> Maybe Text
-- | The name of the hook.
[$sel:hookType:StackEvent'] :: StackEvent -> Maybe Text
-- | The logical name of the resource specified in the template.
[$sel:logicalResourceId:StackEvent'] :: StackEvent -> Maybe Text
-- | The name or unique identifier associated with the physical instance of
-- the resource.
[$sel:physicalResourceId:StackEvent'] :: StackEvent -> Maybe Text
-- | BLOB of the properties used to create the resource.
[$sel:resourceProperties:StackEvent'] :: StackEvent -> Maybe Text
-- | Current status of the resource.
[$sel:resourceStatus:StackEvent'] :: StackEvent -> Maybe ResourceStatus
-- | Success/failure message associated with the resource.
[$sel:resourceStatusReason:StackEvent'] :: StackEvent -> Maybe Text
-- | Type of resource. (For more information, go to Amazon Web Services
-- Resource Types Reference in the CloudFormation User Guide.)
[$sel:resourceType:StackEvent'] :: StackEvent -> Maybe Text
-- | The unique ID name of the instance of the stack.
[$sel:stackId:StackEvent'] :: StackEvent -> Text
-- | The unique ID of this event.
[$sel:eventId:StackEvent'] :: StackEvent -> Text
-- | The name associated with a stack.
[$sel:stackName:StackEvent'] :: StackEvent -> Text
-- | Time the status was updated.
[$sel:timestamp:StackEvent'] :: StackEvent -> ISO8601
newtype ResourceStatus
ResourceStatus' :: Text -> ResourceStatus
[fromResourceStatus] :: ResourceStatus -> Text
pattern ResourceStatus_UPDATE_ROLLBACK_IN_PROGRESS :: ResourceStatus
pattern ResourceStatus_UPDATE_ROLLBACK_FAILED :: ResourceStatus
pattern ResourceStatus_UPDATE_ROLLBACK_COMPLETE :: ResourceStatus
pattern ResourceStatus_UPDATE_IN_PROGRESS :: ResourceStatus
pattern ResourceStatus_UPDATE_FAILED :: ResourceStatus
pattern ResourceStatus_UPDATE_COMPLETE :: ResourceStatus
pattern ResourceStatus_ROLLBACK_IN_PROGRESS :: ResourceStatus
pattern ResourceStatus_ROLLBACK_FAILED :: ResourceStatus
pattern ResourceStatus_ROLLBACK_COMPLETE :: ResourceStatus
pattern ResourceStatus_IMPORT_ROLLBACK_IN_PROGRESS :: ResourceStatus
pattern ResourceStatus_IMPORT_ROLLBACK_FAILED :: ResourceStatus
pattern ResourceStatus_IMPORT_ROLLBACK_COMPLETE :: ResourceStatus
pattern ResourceStatus_IMPORT_IN_PROGRESS :: ResourceStatus
pattern ResourceStatus_IMPORT_FAILED :: ResourceStatus
pattern ResourceStatus_IMPORT_COMPLETE :: ResourceStatus
pattern ResourceStatus_DELETE_SKIPPED :: ResourceStatus
pattern ResourceStatus_DELETE_IN_PROGRESS :: ResourceStatus
pattern ResourceStatus_DELETE_FAILED :: ResourceStatus
pattern ResourceStatus_DELETE_COMPLETE :: ResourceStatus
pattern ResourceStatus_CREATE_IN_PROGRESS :: ResourceStatus
pattern ResourceStatus_CREATE_FAILED :: ResourceStatus
pattern ResourceStatus_CREATE_COMPLETE :: ResourceStatus
-- | The unique ID of this event.
stackEvent_eventId :: Lens' StackEvent Text
-- | The logical name of the resource specified in the template.
stackEvent_logicalResourceId :: Lens' StackEvent (Maybe Text)
-- | Current status of the resource.
stackEvent_resourceStatus :: Lens' StackEvent (Maybe ResourceStatus)
-- | Success/failure message associated with the resource.
stackEvent_resourceStatusReason :: Lens' StackEvent (Maybe Text)
-- | Time the status was updated.
stackEvent_timestamp :: Lens' StackEvent UTCTime
newtype StackTemplate
StackTemplate :: FilePath -> StackTemplate
[unStackTemplate] :: StackTemplate -> FilePath
data StackDeployResult
StackCreateSuccess :: StackDeployResult
StackCreateFailure :: Bool -> StackDeployResult
StackUpdateSuccess :: StackDeployResult
StackUpdateFailure :: Bool -> StackDeployResult
prettyStackDeployResult :: StackDeployResult -> Text
data StackDeleteResult
StackDeleteSuccess :: StackDeleteResult
StackDeleteFailure :: Bool -> StackDeleteResult
prettyStackDeleteResult :: StackDeleteResult -> Text
-- | The Parameter data type.
--
-- See: newParameter smart constructor.
data Parameter
-- | The key associated with the parameter. If you don't specify a key and
-- value for a particular parameter, CloudFormation uses the default
-- value that's specified in your template.
parameter_parameterKey :: Lens' Parameter (Maybe Text)
-- | The input value associated with the parameter.
parameter_parameterValue :: Lens' Parameter (Maybe Text)
-- | Create a value of Parameter with all optional fields omitted.
--
-- Use generic-lens or optics to modify other optional
-- fields.
--
-- The following record fields are available, with the corresponding
-- lenses provided for backwards compatibility:
--
-- $sel:parameterKey:Parameter', parameter_parameterKey -
-- The key associated with the parameter. If you don't specify a key and
-- value for a particular parameter, CloudFormation uses the default
-- value that's specified in your template.
--
-- $sel:parameterValue:Parameter', parameter_parameterValue
-- - The input value associated with the parameter.
--
-- $sel:resolvedValue:Parameter', parameter_resolvedValue -
-- Read-only. The value that corresponds to a SSM parameter key. This
-- field is returned only for SSM parameter types in the template.
--
-- $sel:usePreviousValue:Parameter',
-- parameter_usePreviousValue - During a stack update, use the
-- existing parameter value that the stack is using for a given parameter
-- key. If you specify true, do not specify a parameter value.
newParameter :: Parameter
makeParameter :: Text -> Maybe Text -> Parameter
readParameter :: String -> Either String Parameter
newtype Capability
Capability' :: Text -> Capability
[fromCapability] :: Capability -> Text
pattern Capability_CAPABILITY_NAMED_IAM :: Capability
pattern Capability_CAPABILITY_IAM :: Capability
pattern Capability_CAPABILITY_AUTO_EXPAND :: Capability
-- | The Tag type enables you to specify a key-value pair that can be used
-- to store information about an CloudFormation stack.
--
-- See: newTag smart constructor.
data Tag
-- | Create a value of Tag with all optional fields omitted.
--
-- Use generic-lens or optics to modify other optional
-- fields.
--
-- The following record fields are available, with the corresponding
-- lenses provided for backwards compatibility:
--
-- $sel:key:Tag', tag_key - Required. A string used
-- to identify this tag. You can specify a maximum of 128 characters for
-- a tag key. Tags owned by Amazon Web Services (Amazon Web Services)
-- have the reserved prefix: aws:.
--
-- $sel:value:Tag', tag_value - Required. A string
-- containing the value for this tag. You can specify a maximum of 256
-- characters for a tag value.
newTag :: Text -> Text -> Tag
-- | Required. A string used to identify this tag. You can specify a
-- maximum of 128 characters for a tag key. Tags owned by Amazon Web
-- Services (Amazon Web Services) have the reserved prefix:
-- aws:.
tag_key :: Lens' Tag Text
-- | Required. A string containing the value for this tag. You can
-- specify a maximum of 256 characters for a tag value.
tag_value :: Lens' Tag Text
-- | The Output data type.
--
-- See: newOutput smart constructor.
data Output
-- | The key associated with the output.
output_outputKey :: Lens' Output (Maybe Text)
-- | The value associated with the output.
output_outputValue :: Lens' Output (Maybe Text)
awsCloudFormationDescribeStack :: (MonadResource m, MonadReader env m, HasAwsEnv env) => StackName -> m Stack
awsCloudFormationDescribeStackMaybe :: (MonadUnliftIO m, MonadResource m, MonadReader env m, HasAwsEnv env) => StackName -> m (Maybe Stack)
awsCloudFormationDescribeStackOutputs :: (MonadResource m, MonadReader env m, HasAwsEnv env) => StackName -> m [Output]
awsCloudFormationDescribeStackEvents :: (MonadResource m, MonadReader env m, HasAwsEnv env) => StackName -> Maybe Text -> m [StackEvent]
awsCloudFormationGetStackNamesMatching :: (MonadResource m, MonadReader env m, HasAwsEnv env) => Pattern -> m [StackName]
awsCloudFormationGetMostRecentStackEventId :: (MonadResource m, MonadReader env m, HasAwsEnv env) => StackName -> m (Maybe Text)
awsCloudFormationDeleteStack :: (MonadResource m, MonadLogger m, MonadReader env m, HasAwsEnv env) => StackName -> m StackDeleteResult
awsCloudFormationWait :: (MonadUnliftIO m, MonadResource m, MonadReader env m, HasAwsEnv env) => StackName -> m StackDeployResult
awsCloudFormationGetTemplate :: (MonadResource m, MonadReader env m, HasAwsEnv env) => StackName -> m Value
data ChangeSet
ChangeSet :: UTCTime -> Maybe [Change] -> ChangeSetName -> ExecutionStatus -> ChangeSetId -> Maybe [Parameter] -> StackId -> Maybe [Capability] -> Maybe [Tag] -> StackName -> ChangeSetStatus -> Maybe Text -> DescribeChangeSetResponse -> ChangeSet
[csCreationTime] :: ChangeSet -> UTCTime
[csChanges] :: ChangeSet -> Maybe [Change]
[csChangeSetName] :: ChangeSet -> ChangeSetName
[csExecutionStatus] :: ChangeSet -> ExecutionStatus
[csChangeSetId] :: ChangeSet -> ChangeSetId
[csParameters] :: ChangeSet -> Maybe [Parameter]
[csStackId] :: ChangeSet -> StackId
[csCapabilities] :: ChangeSet -> Maybe [Capability]
[csTags] :: ChangeSet -> Maybe [Tag]
[csStackName] :: ChangeSet -> StackName
[csStatus] :: ChangeSet -> ChangeSetStatus
[csStatusReason] :: ChangeSet -> Maybe Text
[csResponse] :: ChangeSet -> DescribeChangeSetResponse
changeSetFromResponse :: DescribeChangeSetResponse -> Maybe ChangeSet
changeSetJSON :: ChangeSet -> Text
newtype ChangeSetId
ChangeSetId :: Text -> ChangeSetId
[unChangeSetId] :: ChangeSetId -> Text
newtype ChangeSetName
ChangeSetName :: Text -> ChangeSetName
[unChangeSetName] :: ChangeSetName -> Text
-- | The Change structure describes the changes CloudFormation
-- will perform if you execute the change set.
--
-- See: newChange smart constructor.
data Change
Change' :: Maybe Natural -> Maybe ResourceChange -> Maybe ChangeType -> Change
-- | Is either null, if no hooks invoke for the resource, or
-- contains the number of hooks that will invoke for the resource.
[$sel:hookInvocationCount:Change'] :: Change -> Maybe Natural
-- | A ResourceChange structure that describes the resource and
-- action that CloudFormation will perform.
[$sel:resourceChange:Change'] :: Change -> Maybe ResourceChange
-- | The type of entity that CloudFormation changes. Currently, the only
-- entity type is Resource.
[$sel:type':Change'] :: Change -> Maybe ChangeType
-- | The ResourceChange structure describes the resource and the
-- action that CloudFormation will perform on it if you execute this
-- change set.
--
-- See: newResourceChange smart constructor.
data ResourceChange
ResourceChange' :: Maybe ChangeAction -> Maybe Text -> Maybe [ResourceChangeDetail] -> Maybe Text -> Maybe ModuleInfo -> Maybe Text -> Maybe Replacement -> Maybe Text -> Maybe [ResourceAttribute] -> ResourceChange
-- | The action that CloudFormation takes on the resource, such as
-- Add (adds a new resource), Modify (changes a
-- resource), Remove (deletes a resource), Import
-- (imports a resource), or Dynamic (exact action for the
-- resource can't be determined).
[$sel:action:ResourceChange'] :: ResourceChange -> Maybe ChangeAction
-- | The change set ID of the nested change set.
[$sel:changeSetId:ResourceChange'] :: ResourceChange -> Maybe Text
-- | For the Modify action, a list of
-- ResourceChangeDetail structures that describes the changes
-- that CloudFormation will make to the resource.
[$sel:details:ResourceChange'] :: ResourceChange -> Maybe [ResourceChangeDetail]
-- | The resource's logical ID, which is defined in the stack's template.
[$sel:logicalResourceId:ResourceChange'] :: ResourceChange -> Maybe Text
-- | Contains information about the module from which the resource was
-- created, if the resource was created from a module included in the
-- stack template.
[$sel:moduleInfo:ResourceChange'] :: ResourceChange -> Maybe ModuleInfo
-- | The resource's physical ID (resource name). Resources that you are
-- adding don't have physical IDs because they haven't been created.
[$sel:physicalResourceId:ResourceChange'] :: ResourceChange -> Maybe Text
-- | For the Modify action, indicates whether CloudFormation will
-- replace the resource by creating a new one and deleting the old one.
-- This value depends on the value of the RequiresRecreation
-- property in the ResourceTargetDefinition structure. For
-- example, if the RequiresRecreation field is Always
-- and the Evaluation field is Static,
-- Replacement is True. If the
-- RequiresRecreation field is Always and the
-- Evaluation field is Dynamic, Replacement is
-- Conditionally.
--
-- If you have multiple changes with different
-- RequiresRecreation values, the Replacement value
-- depends on the change with the most impact. A
-- RequiresRecreation value of Always has the most
-- impact, followed by Conditionally, and then Never.
[$sel:replacement:ResourceChange'] :: ResourceChange -> Maybe Replacement
-- | The type of CloudFormation resource, such as AWS::S3::Bucket.
[$sel:resourceType:ResourceChange'] :: ResourceChange -> Maybe Text
-- | For the Modify action, indicates which resource attribute is
-- triggering this update, such as a change in the resource attribute's
-- Metadata, Properties, or Tags.
[$sel:scope:ResourceChange'] :: ResourceChange -> Maybe [ResourceAttribute]
newtype Replacement
Replacement' :: Text -> Replacement
[fromReplacement] :: Replacement -> Text
pattern Replacement_True :: Replacement
pattern Replacement_False :: Replacement
pattern Replacement_Conditional :: Replacement
newtype ChangeAction
ChangeAction' :: Text -> ChangeAction
[fromChangeAction] :: ChangeAction -> Text
pattern ChangeAction_Remove :: ChangeAction
pattern ChangeAction_Modify :: ChangeAction
pattern ChangeAction_Import :: ChangeAction
pattern ChangeAction_Dynamic :: ChangeAction
pattern ChangeAction_Add :: ChangeAction
newtype ResourceAttribute
ResourceAttribute' :: Text -> ResourceAttribute
[fromResourceAttribute] :: ResourceAttribute -> Text
pattern ResourceAttribute_UpdatePolicy :: ResourceAttribute
pattern ResourceAttribute_Tags :: ResourceAttribute
pattern ResourceAttribute_Properties :: ResourceAttribute
pattern ResourceAttribute_Metadata :: ResourceAttribute
pattern ResourceAttribute_DeletionPolicy :: ResourceAttribute
pattern ResourceAttribute_CreationPolicy :: ResourceAttribute
-- | For a resource with Modify as the action, the
-- ResourceChange structure describes the changes CloudFormation
-- will make to that resource.
--
-- See: newResourceChangeDetail smart constructor.
data ResourceChangeDetail
ResourceChangeDetail' :: Maybe Text -> Maybe ChangeSource -> Maybe EvaluationType -> Maybe ResourceTargetDefinition -> ResourceChangeDetail
-- | The identity of the entity that triggered this change. This entity is
-- a member of the group that's specified by the ChangeSource
-- field. For example, if you modified the value of the
-- KeyPairName parameter, the CausingEntity is the name
-- of the parameter (KeyPairName).
--
-- If the ChangeSource value is DirectModification, no
-- value is given for CausingEntity.
[$sel:causingEntity:ResourceChangeDetail'] :: ResourceChangeDetail -> Maybe Text
-- | The group to which the CausingEntity value belongs. There are
-- five entity groups:
--
--
-- - ResourceReference entities are Ref intrinsic
-- functions that refer to resources in the template, such as { "Ref"
-- : "MyEC2InstanceResource" }.
-- - ParameterReference entities are Ref intrinsic
-- functions that get template parameter values, such as { "Ref" :
-- "MyPasswordParameter" }.
-- - ResourceAttribute entities are Fn::GetAtt
-- intrinsic functions that get resource attribute values, such as {
-- "Fn::GetAtt" : [ "MyEC2InstanceResource", "PublicDnsName" ]
-- }.
-- - DirectModification entities are changes that are made
-- directly to the template.
-- - Automatic entities are
-- AWS::CloudFormation::Stack resource types, which are also
-- known as nested stacks. If you made no changes to the
-- AWS::CloudFormation::Stack resource, CloudFormation sets the
-- ChangeSource to Automatic because the nested stack's
-- template might have changed. Changes to a nested stack's template
-- aren't visible to CloudFormation until you run an update on the parent
-- stack.
--
[$sel:changeSource:ResourceChangeDetail'] :: ResourceChangeDetail -> Maybe ChangeSource
-- | Indicates whether CloudFormation can determine the target value, and
-- whether the target value will change before you execute a change set.
--
-- For Static evaluations, CloudFormation can determine that the
-- target value will change, and its value. For example, if you directly
-- modify the InstanceType property of an EC2 instance,
-- CloudFormation knows that this property value will change, and its
-- value, so this is a Static evaluation.
--
-- For Dynamic evaluations, can't determine the target value
-- because it depends on the result of an intrinsic function, such as a
-- Ref or Fn::GetAtt intrinsic function, when the stack
-- is updated. For example, if your template includes a reference to a
-- resource that's conditionally recreated, the value of the reference
-- (the physical ID of the resource) might change, depending on if the
-- resource is recreated. If the resource is recreated, it will have a
-- new physical ID, so all references to that resource will also be
-- updated.
[$sel:evaluation:ResourceChangeDetail'] :: ResourceChangeDetail -> Maybe EvaluationType
-- | A ResourceTargetDefinition structure that describes the field
-- that CloudFormation will change and whether the resource will be
-- recreated.
[$sel:target:ResourceChangeDetail'] :: ResourceChangeDetail -> Maybe ResourceTargetDefinition
newtype ChangeSource
ChangeSource' :: Text -> ChangeSource
[fromChangeSource] :: ChangeSource -> Text
pattern ChangeSource_ResourceReference :: ChangeSource
pattern ChangeSource_ResourceAttribute :: ChangeSource
pattern ChangeSource_ParameterReference :: ChangeSource
pattern ChangeSource_DirectModification :: ChangeSource
pattern ChangeSource_Automatic :: ChangeSource
-- | The field that CloudFormation will change, such as the name of a
-- resource's property, and whether the resource will be recreated.
--
-- See: newResourceTargetDefinition smart constructor.
data ResourceTargetDefinition
ResourceTargetDefinition' :: Maybe ResourceAttribute -> Maybe Text -> Maybe RequiresRecreation -> ResourceTargetDefinition
-- | Indicates which resource attribute is triggering this update, such as
-- a change in the resource attribute's Metadata,
-- Properties, or Tags.
[$sel:attribute:ResourceTargetDefinition'] :: ResourceTargetDefinition -> Maybe ResourceAttribute
-- | If the Attribute value is Properties, the name of
-- the property. For all other attributes, the value is null.
[$sel:name:ResourceTargetDefinition'] :: ResourceTargetDefinition -> Maybe Text
-- | If the Attribute value is Properties, indicates
-- whether a change to this property causes the resource to be recreated.
-- The value can be Never, Always, or
-- Conditionally. To determine the conditions for a
-- Conditionally recreation, see the update behavior for that
-- property in the CloudFormation User Guide.
[$sel:requiresRecreation:ResourceTargetDefinition'] :: ResourceTargetDefinition -> Maybe RequiresRecreation
newtype RequiresRecreation
RequiresRecreation' :: Text -> RequiresRecreation
[fromRequiresRecreation] :: RequiresRecreation -> Text
pattern RequiresRecreation_Never :: RequiresRecreation
pattern RequiresRecreation_Conditionally :: RequiresRecreation
pattern RequiresRecreation_Always :: RequiresRecreation
awsCloudFormationCreateChangeSet :: (MonadUnliftIO m, MonadResource m, MonadLogger m, MonadReader env m, HasAwsEnv env) => StackName -> Maybe StackDescription -> StackTemplate -> [Parameter] -> [Capability] -> [Tag] -> m (Either Text (Maybe ChangeSet))
awsCloudFormationExecuteChangeSet :: (MonadResource m, MonadReader env m, HasAwsEnv env) => ChangeSetId -> m ()
awsCloudFormationDeleteAllChangeSets :: (MonadResource m, MonadLogger m, MonadReader env m, HasAwsEnv env) => StackName -> m ()
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.AWS.CloudFormation.StackId
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.AWS.CloudFormation.StackId
instance GHC.Show.Show Stackctl.AWS.CloudFormation.StackId
instance GHC.Classes.Ord Stackctl.AWS.CloudFormation.StackId
instance GHC.Classes.Eq Stackctl.AWS.CloudFormation.StackId
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.AWS.CloudFormation.StackName
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.AWS.CloudFormation.StackName
instance GHC.Show.Show Stackctl.AWS.CloudFormation.StackName
instance GHC.Classes.Ord Stackctl.AWS.CloudFormation.StackName
instance GHC.Classes.Eq Stackctl.AWS.CloudFormation.StackName
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.AWS.CloudFormation.StackTemplate
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.AWS.CloudFormation.StackTemplate
instance GHC.Show.Show Stackctl.AWS.CloudFormation.StackTemplate
instance GHC.Classes.Eq Stackctl.AWS.CloudFormation.StackTemplate
instance GHC.Show.Show Stackctl.AWS.CloudFormation.StackDeployResult
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.AWS.CloudFormation.ChangeSetId
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.AWS.CloudFormation.ChangeSetId
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.AWS.CloudFormation.ChangeSetName
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.AWS.CloudFormation.ChangeSetName
module Stackctl.ParameterOption
parameterOption :: Parser Parameter
module Stackctl.AWS
module Stackctl.Spec.Changes.Format
data Format
FormatTTY :: Format
FormatPullRequest :: Format
formatOption :: Parser Format
data OmitFull
OmitFull :: OmitFull
IncludeFull :: OmitFull
omitFullOption :: Parser OmitFull
formatChangeSet :: Colors -> OmitFull -> Text -> Format -> Maybe ChangeSet -> Text
formatRemovedStack :: Colors -> Format -> Stack -> Text
formatTTY :: Colors -> Text -> Maybe ChangeSet -> Text
instance GHC.Show.Show Stackctl.Spec.Changes.Format.Format
instance GHC.Enum.Enum Stackctl.Spec.Changes.Format.Format
instance GHC.Enum.Bounded Stackctl.Spec.Changes.Format.Format
-- | Actions that can be performed on certain Stack management events
--
-- For example, to invoke a Lambda whose name is found in the deploying
-- Stack's outputs after it's been deployed:
--
--
-- Actions:
-- - on: PostDeploy
-- run:
-- InvokeLambdaByStackOutput: OnDeployFunction
--
module Stackctl.Action
data Action
newAction :: ActionOn -> [ActionRun] -> Action
data ActionOn
PostDeploy :: ActionOn
data ActionRun
InvokeLambdaByStackOutput :: Text -> ActionRun
InvokeLambdaByName :: Text -> ActionRun
Exec :: NonEmpty String -> ActionRun
Shell :: String -> ActionRun
runActions :: (MonadResource m, MonadLogger m, MonadReader env m, HasLogger env, HasAwsEnv env) => StackName -> ActionOn -> [Action] -> m ()
instance GHC.Generics.Generic Stackctl.Action.ActionOn
instance GHC.Show.Show Stackctl.Action.ActionOn
instance GHC.Classes.Eq Stackctl.Action.ActionOn
instance GHC.Show.Show Stackctl.Action.ActionRun
instance GHC.Classes.Eq Stackctl.Action.ActionRun
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.Action.Action
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.Action.Action
instance GHC.Generics.Generic Stackctl.Action.Action
instance GHC.Show.Show Stackctl.Action.Action
instance GHC.Classes.Eq Stackctl.Action.Action
instance GHC.Exception.Type.Exception Stackctl.Action.ActionFailure
instance GHC.Show.Show Stackctl.Action.ActionFailure
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.Action.ActionRun
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.Action.ActionRun
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.Action.ActionOn
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.Action.ActionOn
module Stackctl.AWS.Scope
data AwsScope
AwsScope :: AccountId -> Text -> Region -> AwsScope
[awsAccountId] :: AwsScope -> AccountId
[awsAccountName] :: AwsScope -> Text
[awsRegion] :: AwsScope -> Region
awsScopeSpecPatterns :: AwsScope -> [Pattern]
awsScopeSpecStackName :: AwsScope -> FilePath -> Maybe StackName
class HasAwsScope env
awsScopeL :: HasAwsScope env => Lens' env AwsScope
fetchAwsScope :: (MonadResource m, MonadReader env m, HasAwsEnv env) => m AwsScope
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.AWS.Scope.AwsScope
instance GHC.Generics.Generic Stackctl.AWS.Scope.AwsScope
instance GHC.Show.Show Stackctl.AWS.Scope.AwsScope
instance GHC.Classes.Eq Stackctl.AWS.Scope.AwsScope
instance Stackctl.AWS.Scope.HasAwsScope Stackctl.AWS.Scope.AwsScope
module Stackctl.StackSpecPath
data StackSpecPath
stackSpecPathAccountId :: StackSpecPath -> AccountId
stackSpecPathAccountName :: StackSpecPath -> Text
stackSpecPathRegion :: StackSpecPath -> Region
stackSpecPathStackName :: StackSpecPath -> StackName
stackSpecPathBasePath :: StackSpecPath -> FilePath
-- | Render the (relative) StackSpecPath
stackSpecPathFilePath :: StackSpecPath -> FilePath
stackSpecPath :: AwsScope -> StackName -> FilePath -> StackSpecPath
stackSpecPathFromFilePath :: AwsScope -> FilePath -> Either String StackSpecPath
instance GHC.Show.Show Stackctl.StackSpecPath.StackSpecPath
instance GHC.Classes.Eq Stackctl.StackSpecPath.StackSpecPath
-- | Definition of our
-- stacksaccountregion/stack-name.yaml
-- format
--
--
-- Template: path
--
-- Depends:
-- - string
--
-- Parameters:
-- - ParameterKey: string
-- ParameterValue: string
--
-- Capabilities:
-- - capability
--
-- Tags:
-- - Key: string
-- Value: string
--
module Stackctl.StackSpecYaml
data StackSpecYaml
StackSpecYaml :: Maybe StackDescription -> FilePath -> Maybe [StackName] -> Maybe [Action] -> Maybe ParametersYaml -> Maybe [Capability] -> Maybe TagsYaml -> StackSpecYaml
[ssyDescription] :: StackSpecYaml -> Maybe StackDescription
[ssyTemplate] :: StackSpecYaml -> FilePath
[ssyDepends] :: StackSpecYaml -> Maybe [StackName]
[ssyActions] :: StackSpecYaml -> Maybe [Action]
[ssyParameters] :: StackSpecYaml -> Maybe ParametersYaml
[ssyCapabilities] :: StackSpecYaml -> Maybe [Capability]
[ssyTags] :: StackSpecYaml -> Maybe TagsYaml
data ParametersYaml
parametersYaml :: [ParameterYaml] -> ParametersYaml
unParametersYaml :: ParametersYaml -> [ParameterYaml]
data ParameterYaml
parameterYaml :: Parameter -> Maybe ParameterYaml
unParameterYaml :: ParameterYaml -> Parameter
data TagsYaml
tagsYaml :: [TagYaml] -> TagsYaml
unTagsYaml :: TagsYaml -> [TagYaml]
newtype TagYaml
TagYaml :: Tag -> TagYaml
[unTagYaml] :: TagYaml -> Tag
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.StackSpecYaml.ParameterValue
instance GHC.Base.Semigroup Stackctl.StackSpecYaml.ParameterValue
instance GHC.Show.Show Stackctl.StackSpecYaml.ParameterValue
instance GHC.Classes.Eq Stackctl.StackSpecYaml.ParameterValue
instance GHC.Show.Show Stackctl.StackSpecYaml.ParameterYaml
instance GHC.Classes.Eq Stackctl.StackSpecYaml.ParameterYaml
instance GHC.Show.Show Stackctl.StackSpecYaml.ParametersYaml
instance GHC.Classes.Eq Stackctl.StackSpecYaml.ParametersYaml
instance GHC.Show.Show Stackctl.StackSpecYaml.TagYaml
instance GHC.Classes.Eq Stackctl.StackSpecYaml.TagYaml
instance GHC.Show.Show Stackctl.StackSpecYaml.TagsYaml
instance GHC.Classes.Eq Stackctl.StackSpecYaml.TagsYaml
instance GHC.Generics.Generic Stackctl.StackSpecYaml.StackSpecYaml
instance GHC.Show.Show Stackctl.StackSpecYaml.StackSpecYaml
instance GHC.Classes.Eq Stackctl.StackSpecYaml.StackSpecYaml
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.StackSpecYaml.StackSpecYaml
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.StackSpecYaml.StackSpecYaml
instance GHC.Base.Semigroup Stackctl.StackSpecYaml.TagsYaml
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.StackSpecYaml.TagsYaml
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.StackSpecYaml.TagsYaml
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.StackSpecYaml.TagYaml
instance GHC.Base.Semigroup Stackctl.StackSpecYaml.ParametersYaml
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.StackSpecYaml.ParametersYaml
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.StackSpecYaml.ParametersYaml
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.StackSpecYaml.ParameterYaml
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.StackSpecYaml.ParameterValue
module Stackctl.Config
data Config
Config :: Maybe RequiredVersion -> Maybe Defaults -> Config
[required_version] :: Config -> Maybe RequiredVersion
[defaults] :: Config -> Maybe Defaults
configParameters :: Config -> Maybe ParametersYaml
configTags :: Config -> Maybe TagsYaml
emptyConfig :: Config
class HasConfig env
configL :: HasConfig env => Lens' env Config
data ConfigError
ConfigInvalidYaml :: ParseException -> ConfigError
ConfigInvalid :: NonEmpty Text -> ConfigError
ConfigVersionNotSatisfied :: RequiredVersion -> Version -> ConfigError
loadConfigOrExit :: (MonadIO m, MonadLogger m) => m Config
loadConfigFromBytes :: MonadError ConfigError m => ByteString -> m Config
applyConfig :: Config -> StackSpecYaml -> StackSpecYaml
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.Config.Defaults
instance GHC.Generics.Generic Stackctl.Config.Defaults
instance Data.Aeson.Types.FromJSON.FromJSON Stackctl.Config.Config
instance GHC.Generics.Generic Stackctl.Config.Config
instance GHC.Show.Show Stackctl.Config.ConfigError
instance Stackctl.Config.HasConfig Stackctl.Config.Config
module Stackctl.StackSpec
data StackSpec
stackSpecFilePath :: StackSpec -> FilePath
stackSpecSpecPath :: StackSpec -> StackSpecPath
stackSpecSpecBody :: StackSpec -> StackSpecYaml
stackSpecStackName :: StackSpec -> StackName
stackSpecStackDescription :: StackSpec -> Maybe StackDescription
stackSpecDepends :: StackSpec -> [StackName]
stackSpecActions :: StackSpec -> [Action]
stackSpecParameters :: StackSpec -> [Parameter]
stackSpecCapabilities :: StackSpec -> [Capability]
-- | Relative path stacks/...
stackSpecStackFile :: StackSpec -> FilePath
-- | Relative path templates/...
stackSpecTemplateFile :: StackSpec -> FilePath
stackSpecTags :: StackSpec -> [Tag]
buildStackSpec :: (MonadReader env m, HasConfig env) => FilePath -> StackSpecPath -> StackSpecYaml -> m StackSpec
data TemplateBody
templateBodyFromValue :: Value -> TemplateBody
writeStackSpec :: (MonadUnliftIO m, MonadLogger m) => Bool -> StackSpec -> Maybe TemplateBody -> m ()
readStackSpec :: (MonadIO m, MonadReader env m, HasConfig env) => FilePath -> StackSpecPath -> m StackSpec
-- | Create a Change Set between a Stack Specification and deployed state
createChangeSet :: (MonadUnliftIO m, MonadResource m, MonadLogger m, MonadReader env m, HasAwsEnv env) => StackSpec -> [Parameter] -> [Tag] -> m (Either Text (Maybe ChangeSet))
sortStackSpecs :: [StackSpec] -> [StackSpec]
instance GHC.Show.Show Stackctl.StackSpec.UnexpectedTemplateJson
instance GHC.Exception.Type.Exception Stackctl.StackSpec.UnexpectedTemplateJson
module Stackctl.FilterOption
data FilterOption
defaultFilterOption :: FilterOption
class HasFilterOption env
filterOptionL :: HasFilterOption env => Lens' env FilterOption
envFilterOption :: String -> Parser Error FilterOption
filterOption :: String -> Parser FilterOption
filterOptionFromPaths :: NonEmpty FilePath -> FilterOption
filterOptionFromText :: Text -> Maybe FilterOption
filterOptionToPaths :: FilterOption -> [FilePath]
filterStackSpecs :: FilterOption -> [StackSpec] -> [StackSpec]
instance GHC.Base.Semigroup Stackctl.FilterOption.FilterOption
instance Stackctl.FilterOption.HasFilterOption Stackctl.FilterOption.FilterOption
instance Data.Aeson.Types.ToJSON.ToJSON Stackctl.FilterOption.FilterOption
module Stackctl.RemovedStack
inferRemovedStacks :: (MonadUnliftIO m, MonadResource m, MonadReader env m, HasAwsEnv env, HasAwsScope env, HasFilterOption env) => m [Stack]
module Stackctl.Spec.Discover
forEachSpec_ :: (MonadMask m, MonadResource m, MonadLogger m, MonadReader env m, HasAwsScope env, HasConfig env, HasDirectoryOption env, HasFilterOption env) => (StackSpec -> m ()) -> m ()
discoverSpecs :: (MonadMask m, MonadResource m, MonadLogger m, MonadReader env m, HasAwsScope env, HasConfig env, HasDirectoryOption env, HasFilterOption env) => m [StackSpec]
buildSpecPath :: (MonadReader env m, HasAwsScope env) => StackName -> FilePath -> m StackSpecPath
module Stackctl.Spec.List
newtype ListOptions
ListOptions :: Bool -> ListOptions
[loLegend] :: ListOptions -> Bool
parseListOptions :: Parser ListOptions
runList :: (MonadUnliftIO m, MonadMask m, MonadResource m, MonadLogger m, MonadReader env m, HasAwsScope env, HasAwsEnv env, HasLogger env, HasConfig env, HasDirectoryOption env, HasFilterOption env) => ListOptions -> m ()
instance GHC.Enum.Enum Stackctl.Spec.List.Indicator
instance GHC.Enum.Bounded Stackctl.Spec.List.Indicator
module Stackctl.Spec.Generate
data Generate
Generate :: Maybe StackDescription -> Maybe [StackName] -> Maybe [Action] -> Maybe [Parameter] -> Maybe [Capability] -> Maybe [Tag] -> GenerateSpec -> GenerateTemplate -> Bool -> Generate
[gDescription] :: Generate -> Maybe StackDescription
[gDepends] :: Generate -> Maybe [StackName]
[gActions] :: Generate -> Maybe [Action]
[gParameters] :: Generate -> Maybe [Parameter]
[gCapabilities] :: Generate -> Maybe [Capability]
[gTags] :: Generate -> Maybe [Tag]
[gSpec] :: Generate -> GenerateSpec
[gTemplate] :: Generate -> GenerateTemplate
[gOverwrite] :: Generate -> Bool
data GenerateSpec
-- | Generate at an inferred name
GenerateSpec :: StackName -> GenerateSpec
-- | Generate to a given path
GenerateSpecTo :: StackName -> FilePath -> GenerateSpec
data GenerateTemplate
-- | Generate at an inferred name
GenerateTemplate :: TemplateBody -> TemplateFormat -> GenerateTemplate
-- | Generate to the given path
GenerateTemplateTo :: TemplateBody -> FilePath -> GenerateTemplate
-- | Assume template exists
UseExistingTemplate :: FilePath -> GenerateTemplate
generate :: (MonadMask m, MonadUnliftIO m, MonadLogger m, MonadReader env m, HasConfig env, HasAwsScope env, HasDirectoryOption env) => Generate -> m FilePath
data TemplateFormat
TemplateFormatYaml :: TemplateFormat
TemplateFormatJson :: TemplateFormat
module Stackctl.Spec.Cat
data CatOptions
CatOptions :: Bool -> Bool -> Bool -> CatOptions
[sctoNoStacks] :: CatOptions -> Bool
[sctoNoTemplates] :: CatOptions -> Bool
[sctoBrief] :: CatOptions -> Bool
parseCatOptions :: Parser CatOptions
runCat :: (MonadMask m, MonadResource m, MonadLogger m, MonadReader env m, HasLogger env, HasAwsScope env, HasConfig env, HasDirectoryOption env, HasFilterOption env) => CatOptions -> m ()
module Stackctl.Spec.Capture
data CaptureOptions
CaptureOptions :: Maybe Text -> Maybe FilePath -> Maybe FilePath -> Maybe [StackName] -> TemplateFormat -> Pattern -> CaptureOptions
[scoAccountName] :: CaptureOptions -> Maybe Text
[scoTemplatePath] :: CaptureOptions -> Maybe FilePath
[scoStackPath] :: CaptureOptions -> Maybe FilePath
[scoDepends] :: CaptureOptions -> Maybe [StackName]
[scoTemplateFormat] :: CaptureOptions -> TemplateFormat
[scoStackName] :: CaptureOptions -> Pattern
parseCaptureOptions :: Parser CaptureOptions
runCapture :: (MonadMask m, MonadUnliftIO m, MonadResource m, MonadLogger m, MonadReader env m, HasAwsScope env, HasAwsEnv env, HasConfig env, HasDirectoryOption env) => CaptureOptions -> m ()
module Stackctl.TagOption
tagOption :: Parser Tag
module Stackctl.Spec.Deploy
data DeployOptions
DeployOptions :: [Parameter] -> [Tag] -> Maybe FilePath -> DeployConfirmation -> Bool -> Bool -> DeployOptions
[sdoParameters] :: DeployOptions -> [Parameter]
[sdoTags] :: DeployOptions -> [Tag]
[sdoSaveChangeSets] :: DeployOptions -> Maybe FilePath
[sdoDeployConfirmation] :: DeployOptions -> DeployConfirmation
[sdoRemovals] :: DeployOptions -> Bool
[sdoClean] :: DeployOptions -> Bool
data DeployConfirmation
DeployWithConfirmation :: DeployConfirmation
DeployWithoutConfirmation :: DeployConfirmation
parseDeployOptions :: Parser DeployOptions
runDeploy :: (MonadMask m, MonadUnliftIO m, MonadResource m, MonadLogger m, MonadReader env m, HasLogger env, HasAwsScope env, HasAwsEnv env, HasConfig env, HasDirectoryOption env, HasFilterOption env) => DeployOptions -> m ()
instance GHC.Classes.Eq Stackctl.Spec.Deploy.DeployConfirmation
module Stackctl.Spec.Changes
data ChangesOptions
ChangesOptions :: Format -> OmitFull -> [Parameter] -> [Tag] -> Maybe FilePath -> ChangesOptions
[scoFormat] :: ChangesOptions -> Format
[scoOmitFull] :: ChangesOptions -> OmitFull
[scoParameters] :: ChangesOptions -> [Parameter]
[scoTags] :: ChangesOptions -> [Tag]
[scoOutput] :: ChangesOptions -> Maybe FilePath
parseChangesOptions :: Parser ChangesOptions
runChanges :: (MonadMask m, MonadUnliftIO m, MonadResource m, MonadLogger m, MonadReader env m, HasLogger env, HasAwsScope env, HasAwsEnv env, HasConfig env, HasDirectoryOption env, HasFilterOption env) => ChangesOptions -> m ()
module Stackctl.VerboseOption
data Verbosity
verbositySetLogLevels :: Verbosity -> LogSettings -> LogSettings
class HasVerboseOption env
verboseOptionL :: HasVerboseOption env => Lens' env Verbosity
verboseOption :: Parser Verbosity
instance GHC.Base.Monoid Stackctl.VerboseOption.Verbosity
instance GHC.Base.Semigroup Stackctl.VerboseOption.Verbosity
instance Stackctl.VerboseOption.HasVerboseOption Stackctl.VerboseOption.Verbosity
module Stackctl.Options
data Options
envParser :: Parser Error Options
optionsParser :: Parser Options
instance GHC.Base.Semigroup Stackctl.Options.Options
instance GHC.Generics.Generic Stackctl.Options.Options
instance Stackctl.DirectoryOption.HasDirectoryOption Stackctl.Options.Options
instance Stackctl.FilterOption.HasFilterOption Stackctl.Options.Options
instance Stackctl.ColorOption.HasColorOption Stackctl.Options.Options
instance Stackctl.VerboseOption.HasVerboseOption Stackctl.Options.Options
instance Stackctl.AutoSSO.HasAutoSSOOption Stackctl.Options.Options
module Stackctl.CLI
data App options
optionsL :: Lens' (App options) options
data AppT app m a
runAppT :: (MonadMask m, MonadUnliftIO m, HasColorOption options, HasVerboseOption options, HasAutoSSOOption options) => options -> AppT (App options) m a -> m a
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Stackctl.CLI.AppT app m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Stackctl.CLI.AppT app m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Stackctl.CLI.AppT app m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.Logger.MonadLogger (Stackctl.CLI.AppT app m)
instance GHC.Base.Monad m => Control.Monad.Reader.Class.MonadReader app (Stackctl.CLI.AppT app m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.Trans.Resource.Internal.MonadResource (Stackctl.CLI.AppT app m)
instance Control.Monad.IO.Unlift.MonadUnliftIO m => Control.Monad.IO.Unlift.MonadUnliftIO (Stackctl.CLI.AppT app m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Stackctl.CLI.AppT app m)
instance GHC.Base.Monad m => GHC.Base.Monad (Stackctl.CLI.AppT app m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Stackctl.CLI.AppT app m)
instance GHC.Base.Functor m => GHC.Base.Functor (Stackctl.CLI.AppT app m)
instance Blammo.Logging.Internal.Logger.HasLogger (Stackctl.CLI.App options)
instance Stackctl.Config.HasConfig (Stackctl.CLI.App options)
instance Stackctl.AWS.Scope.HasAwsScope (Stackctl.CLI.App options)
instance Stackctl.AWS.Core.HasAwsEnv (Stackctl.CLI.App options)
instance Stackctl.DirectoryOption.HasDirectoryOption options => Stackctl.DirectoryOption.HasDirectoryOption (Stackctl.CLI.App options)
instance Stackctl.FilterOption.HasFilterOption options => Stackctl.FilterOption.HasFilterOption (Stackctl.CLI.App options)
instance Stackctl.ColorOption.HasColorOption options => Stackctl.ColorOption.HasColorOption (Stackctl.CLI.App options)
instance Stackctl.VerboseOption.HasVerboseOption options => Stackctl.VerboseOption.HasVerboseOption (Stackctl.CLI.App options)
instance Stackctl.AutoSSO.HasAutoSSOOption options => Stackctl.AutoSSO.HasAutoSSOOption (Stackctl.CLI.App options)
module Stackctl.Subcommand
data Subcommand options subOptions
Subcommand :: Text -> Text -> Parser subOptions -> (subOptions -> options -> IO ()) -> Subcommand options subOptions
[name] :: Subcommand options subOptions -> Text
[description] :: Subcommand options subOptions -> Text
[parse] :: Subcommand options subOptions -> Parser subOptions
[run] :: Subcommand options subOptions -> subOptions -> options -> IO ()
subcommand :: Subcommand options subOptions -> Mod CommandFields (options -> IO ())
runSubcommand :: Mod CommandFields (Options -> IO a) -> IO a
runSubcommand' :: Semigroup options => Text -> Parser Error options -> Parser options -> Mod CommandFields (options -> IO a) -> IO a
-- | Use this in the run member of a Subcommand that wants
-- AppT
--
--
-- -- ...
-- , parse = parseFooOptions
-- , run = runAppSubcommand runFoo
-- }
--
-- runFoo :: (MonadReader env m, HasAws env) => FooOptions -> m ()
-- runFoo = undefined
--
runAppSubcommand :: (HasColorOption options, HasVerboseOption options, HasAutoSSOOption options) => (subOptions -> AppT (App options) IO a) -> subOptions -> options -> IO a
module Stackctl.Version
logVersion :: MonadIO m => m ()
module Stackctl.Commands
cat :: (HasColorOption options, HasVerboseOption options, HasDirectoryOption options, HasFilterOption options, HasAutoSSOOption options) => Subcommand options CatOptions
capture :: (HasColorOption options, HasVerboseOption options, HasDirectoryOption options, HasAutoSSOOption options) => Subcommand options CaptureOptions
changes :: (HasColorOption options, HasVerboseOption options, HasDirectoryOption options, HasFilterOption options, HasAutoSSOOption options) => Subcommand options ChangesOptions
deploy :: (HasColorOption options, HasVerboseOption options, HasDirectoryOption options, HasFilterOption options, HasAutoSSOOption options) => Subcommand options DeployOptions
list :: (HasColorOption options, HasVerboseOption options, HasDirectoryOption options, HasFilterOption options, HasAutoSSOOption options) => Subcommand options ListOptions
version :: Subcommand options ()