libghc-classy-prelude-doc 0.9.3-1 / usr / share / doc / libghc-classy-prelude-doc / html / classy-prelude.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A typeclass-based Prelude.
--   
--   Focuses on using common typeclasses when possible, and creating new
--   ones to avoid name clashing. Exposes many recommended datastructures
--   (Map, ByteString, etc) directly without requiring long import lists
--   and qualified modules.
@package classy-prelude
@version 0.9.3

module ClassyPrelude

-- | We define our own <tt>undefined</tt> which is marked as deprecated.
--   This makes it useful to use during development, but let's you more
--   easily getting notification if you accidentally ship partial code in
--   production.
--   
--   The classy prelude recommendation for when you need to really have a
--   partial function in production is to use <tt>error</tt> with a very
--   descriptive message so that, in case an exception is thrown, you get
--   more information than <tt>Prelude.undefined</tt>.
--   
--   Since 0.5.5

-- | <i>Deprecated: It is highly recommended that you either avoid partial
--   functions or provide meaningful error messages </i>
undefined :: a
(++) :: Monoid m => m -> m -> m
class Semigroup a
(<>) :: Semigroup a => a -> a -> a
sconcat :: Semigroup a => NonEmpty a -> a
times1p :: (Semigroup a, Whole n) => n -> a -> a

-- | Provide a Semigroup for an arbitrary Monoid.
data WrappedMonoid m :: * -> *

-- | Only perform the action if the predicate returns <tt>True</tt>.
--   
--   Since 0.9.2
whenM :: Monad m => m Bool -> m () -> m ()

-- | Only perform the action if the predicate returns <tt>False</tt>.
--   
--   Since 0.9.2
unlessM :: Monad m => m Bool -> m () -> m ()

-- | Generalized version of <a>atomically</a>.
atomically :: MonadIO m => STM a -> m a

-- | Synonym for <a>always</a>.
alwaysSTM :: STM Bool -> STM ()

-- | Synonym for <a>alwaysSucceeds</a>.
alwaysSucceedsSTM :: STM a -> STM ()

-- | Synonym for <a>retry</a>.
retrySTM :: STM a

-- | Synonym for <a>orElse</a>.
orElseSTM :: STM a -> STM a -> STM a

-- | Synonym for <a>check</a>.
checkSTM :: Bool -> STM ()

-- | The <a>trace</a> function outputs the trace message given as its first
--   argument, before returning the second argument as its result.
--   
--   For example, this returns the value of <tt>f x</tt> but first outputs
--   the message.
--   
--   <pre>
--   trace ("calling f with x = " ++ show x) (f x)
--   </pre>
--   
--   The <a>trace</a> function should <i>only</i> be used for debugging, or
--   for monitoring execution. The function is not referentially
--   transparent: its type indicates that it is a pure function but it has
--   the side effect of outputting the trace message.
trace :: String -> a -> a

-- | Like <a>trace</a>, but uses <a>show</a> on the argument to convert it
--   to a <a>String</a>.
--   
--   This makes it convenient for printing the values of interesting
--   variables or expressions inside a function. For example here we print
--   the value of the variables <tt>x</tt> and <tt>z</tt>:
--   
--   <pre>
--   f x y =
--       traceShow (x, z) $ result
--     where
--       z = ...
--       ...
--   </pre>
traceShow :: Show a => a -> b -> b

-- | Since 0.5.9
traceId :: String -> String

-- | Since 0.5.9
traceM :: Monad m => String -> m ()

-- | Since 0.5.9
traceShowId :: Show a => a -> a

-- | Since 0.5.9
traceShowM :: (Show a, Monad m) => a -> m ()

-- | If the first argument evaluates to <a>True</a>, then the result is the
--   second argument. Otherwise an <tt>AssertionFailed</tt> exception is
--   raised, containing a <a>String</a> with the source file and line
--   number of the call to <a>assert</a>.
--   
--   Assertions can normally be turned on or off with a compiler flag (for
--   GHC, assertions are normally on unless optimisation is turned on with
--   <tt>-O</tt> or the <tt>-fignore-asserts</tt> option is given). When
--   assertions are turned off, the first argument to <a>assert</a> is
--   ignored, and the second argument is returned as the result.
assert :: Bool -> a -> a
defaultTimeLocale :: TimeLocale

-- | Representable types of kind *. This class is derivable in GHC with the
--   DeriveGeneric flag on.
class Generic a

-- | Haskell defines operations to read and write characters from and to
--   files, represented by values of type <tt>Handle</tt>. Each value of
--   this type is a <i>handle</i>: a record used by the Haskell run-time
--   system to <i>manage</i> I/O with file system objects. A handle has at
--   least the following properties:
--   
--   <ul>
--   <li>whether it manages input or output or both;</li>
--   <li>whether it is <i>open</i>, <i>closed</i> or
--   <i>semi-closed</i>;</li>
--   <li>whether the object is seekable;</li>
--   <li>whether buffering is disabled, or enabled on a line or block
--   basis;</li>
--   <li>a buffer (whose length may be zero).</li>
--   </ul>
--   
--   Most handles will also have a current I/O position indicating where
--   the next input or output operation will occur. A handle is
--   <i>readable</i> if it manages only input or both input and output;
--   likewise, it is <i>writable</i> if it manages only output or both
--   input and output. A handle is <i>open</i> 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 <a>Show</a> and <a>Eq</a> 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 <a>==</a> only to itself; no attempt is
--   made to compare the internal state of different handles for equality.
data Handle :: *

-- | A handle managing input from the Haskell program's standard input
--   channel.
stdin :: Handle

-- | A handle managing output to the Haskell program's standard output
--   channel.
stdout :: Handle

-- | A handle managing output to the Haskell program's standard error
--   channel.
stderr :: Handle
map :: Functor f => (a -> b) -> f a -> f b
concat :: (MonoFoldable c, Monoid (Element c)) => c -> Element c
concatMap :: (Monoid m, MonoFoldable c) => (Element c -> m) -> c -> m
length :: MonoFoldable c => c -> Int
null :: MonoFoldable c => c -> Bool
pack :: IsSequence c => [Element c] -> c
unpack :: MonoFoldable c => c -> [Element c]

-- | Repack from one type to another, dropping to a list in the middle.
--   
--   <tt>repack = pack . unpack</tt>.
repack :: (MonoFoldable a, IsSequence b, Element a ~ Element b) => a -> b
toList :: MonoFoldable c => c -> [Element c]

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and collect the results.
mapM :: Traversable t => forall a (m :: * -> *) b. Monad m => (a -> m b) -> t a -> m (t b)
mapM_ :: (Monad m, MonoFoldable c) => (Element c -> m ()) -> c -> m ()

-- | <a>forM</a> is <a>mapM</a> with its arguments flipped.
forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b)
forM_ :: (Monad m, MonoFoldable c) => c -> (Element c -> m ()) -> m ()
any :: MonoFoldable c => (Element c -> Bool) -> c -> Bool
all :: MonoFoldable c => (Element c -> Bool) -> c -> Bool

-- | Since 0.9.2
and :: (MonoFoldable mono, Element mono ~ Bool) => mono -> Bool

-- | Since 0.9.2
or :: (MonoFoldable mono, Element mono ~ Bool) => mono -> Bool
foldl' :: MonoFoldable c => (a -> Element c -> a) -> a -> c -> a
foldr :: MonoFoldable c => (Element c -> b -> b) -> b -> c -> b
foldM :: (Monad m, MonoFoldable c) => (a -> Element c -> m a) -> a -> c -> m a
readMay :: (Element c ~ Char, MonoFoldable c, Read a) => c -> Maybe a
intercalate :: (Monoid (Element c), IsSequence c) => Element c -> c -> Element c
zip :: Zip f => forall a b. f a -> f b -> f (a, b)
zip3 :: Zip3 f => forall a b c. f a -> f b -> f c -> f (a, b, c)
zip4 :: Zip4 f => forall a b c d. f a -> f b -> f c -> f d -> f (a, b, c, d)
zip5 :: Zip5 f => forall a b c d e. f a -> f b -> f c -> f d -> f e -> f (a, b, c, d, e)
zip6 :: Zip6 f => forall a b c d e g. f a -> f b -> f c -> f d -> f e -> f g -> f (a, b, c, d, e, g)
zip7 :: Zip7 f => forall a b c d e g h. f a -> f b -> f c -> f d -> f e -> f g -> f h -> f (a, b, c, d, e, g, h)
unzip :: Zip f => forall a b. f (a, b) -> (f a, f b)
unzip3 :: Zip3 f => forall a b c. f (a, b, c) -> (f a, f b, f c)
unzip4 :: Zip4 f => forall a b c d. f (a, b, c, d) -> (f a, f b, f c, f d)
unzip5 :: Zip5 f => forall a b c d e. f (a, b, c, d, e) -> (f a, f b, f c, f d, f e)
unzip6 :: Zip6 f => forall a b c d e g. f (a, b, c, d, e, g) -> (f a, f b, f c, f d, f e, f g)
unzip7 :: Zip7 f => forall a b c d e g h. f (a, b, c, d, e, g, h) -> (f a, f b, f c, f d, f e, f g, f h)
zipWith :: Zip f => forall a b c. (a -> b -> c) -> f a -> f b -> f c
zipWith3 :: Zip3 f => forall a b c d. (a -> b -> c -> d) -> f a -> f b -> f c -> f d
zipWith4 :: Zip4 f => forall a b c d e. (a -> b -> c -> d -> e) -> f a -> f b -> f c -> f d -> f e
zipWith5 :: Zip5 f => forall a b c d e g. (a -> b -> c -> d -> e -> g) -> f a -> f b -> f c -> f d -> f e -> f g
zipWith6 :: Zip6 f => forall a b c d e g h. (a -> b -> c -> d -> e -> g -> h) -> f a -> f b -> f c -> f d -> f e -> f g -> f h
zipWith7 :: Zip7 f => forall a b c d e g h i. (a -> b -> c -> d -> e -> g -> h -> i) -> f a -> f b -> f c -> f d -> f e -> f g -> f h -> f i

-- | same behavior as nub, but requires Hashable &amp; Eq and is O(n log n)
--   https:<i></i>github.com<i>nh2</i>haskell-ordnub
hashNub :: (Hashable a, Eq a) => [a] -> [a]

-- | same behavior as nub, but requires Ord and is O(n log n)
--   https:<i></i>github.com<i>nh2</i>haskell-ordnub
ordNub :: Ord a => [a] -> [a]

-- | same behavior as nubBy, but requires Ord and is O(n log n)
--   https:<i></i>github.com<i>nh2</i>haskell-ordnub
ordNubBy :: Ord b => (a -> b) -> (a -> a -> Bool) -> [a] -> [a]

-- | Sort elements using the user supplied function to project something
--   out of each element. Inspired by
--   <a>http://hackage.haskell.org/packages/archive/base/latest/doc/html/GHC-Exts.html#v:sortWith</a>.
sortWith :: (Ord a, IsSequence c) => (Element c -> a) -> c -> c
compareLength :: (Integral i, MonoFoldable c) => c -> i -> Ordering
sum :: (MonoFoldable c, Num (Element c)) => c -> Element c
product :: (MonoFoldable c, Num (Element c)) => c -> Element c

-- | <a>repeat</a> <tt>x</tt> is an infinite list, with <tt>x</tt> the
--   value of every element.
repeat :: a -> [a]

-- | An alias for <a>difference</a>.
(\\) :: SetContainer a => a -> a -> a

-- | An alias for <a>intersection</a>.
intersect :: SetContainer a => a -> a -> a
unions :: (MonoFoldable c, SetContainer (Element c)) => c -> Element c

-- | Conversion of values to readable <a>String</a>s.
--   
--   Minimal complete definition: <a>showsPrec</a> or <a>show</a>.
--   
--   Derived instances of <a>Show</a> have the following properties, which
--   are compatible with derived instances of <a>Read</a>:
--   
--   <ul>
--   <li>The result of <a>show</a> 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.</li>
--   <li>If the constructor is defined to be an infix operator, then
--   <a>showsPrec</a> will produce infix applications of the
--   constructor.</li>
--   <li>the representation will be enclosed in parentheses if the
--   precedence of the top-level constructor in <tt>x</tt> is less than
--   <tt>d</tt> (associativity is ignored). Thus, if <tt>d</tt> is
--   <tt>0</tt> then the result is never surrounded in parentheses; if
--   <tt>d</tt> is <tt>11</tt> it is always surrounded in parentheses,
--   unless it is an atomic expression.</li>
--   <li>If the constructor is defined using record syntax, then
--   <a>show</a> will produce the record-syntax form, with the fields given
--   in the same order as the original declaration.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Show</a> is equivalent to
--   
--   <pre>
--   instance (Show a) =&gt; Show (Tree a) where
--   
--          showsPrec d (Leaf m) = showParen (d &gt; app_prec) $
--               showString "Leaf " . showsPrec (app_prec+1) m
--            where app_prec = 10
--   
--          showsPrec d (u :^: v) = showParen (d &gt; up_prec) $
--               showsPrec (up_prec+1) u .
--               showString " :^: "      .
--               showsPrec (up_prec+1) v
--            where up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is ignored. For example,
--   
--   <ul>
--   <li><tt><a>show</a> (Leaf 1 :^: Leaf 2 :^: Leaf 3)</tt> produces the
--   string <tt>"Leaf 1 :^: (Leaf 2 :^: Leaf 3)"</tt>.</li>
--   </ul>
class Show a
showsPrec :: Show a => Int -> a -> ShowS
show :: Show a => a -> String
showList :: Show a => [a] -> ShowS
tshow :: Show a => a -> Text
tlshow :: Show a => a -> LText

-- | Convert a character to lower case.
--   
--   Character-based case conversion is lossy in comparison to string-based
--   <a>toLower</a>. For instance, 'İ' will be converted to 'i', instead of
--   "i̇".
charToLower :: Char -> Char

-- | Convert a character to upper case.
--   
--   Character-based case conversion is lossy in comparison to string-based
--   <a>toUpper</a>. For instance, 'ß' won't be converted to "SS".
charToUpper :: Char -> Char

-- | Data which can be read to and from files and handles.
--   
--   Note that, for lazy sequences, these operations may perform lazy I/O.
class IsSequence a => IOData a
readFile :: (IOData a, MonadIO m) => FilePath -> m a
writeFile :: (IOData a, MonadIO m) => FilePath -> a -> m ()
getLine :: (IOData a, MonadIO m) => m a
hGetContents :: (IOData a, MonadIO m) => Handle -> m a
hGetLine :: (IOData a, MonadIO m) => Handle -> m a
hPut :: (IOData a, MonadIO m) => Handle -> a -> m ()
hPutStrLn :: (IOData a, MonadIO m) => Handle -> a -> m ()
hGetChunk :: (IOData a, MonadIO m) => Handle -> m a
print :: (Show a, MonadIO m) => a -> m ()

-- | Computation <a>hClose</a> <tt>hdl</tt> makes handle <tt>hdl</tt>
--   closed. Before the computation finishes, if <tt>hdl</tt> is writable
--   its buffer is flushed as for <a>hFlush</a>. Performing <a>hClose</a>
--   on a handle that has already been closed has no effect; doing so is
--   not an error. All other operations on a closed handle will fail. If
--   <a>hClose</a> fails for any reason, any further operations (apart from
--   <a>hClose</a>) on the handle will still fail as if <tt>hdl</tt> had
--   been successfully closed.
hClose :: Handle -> IO ()
fpToString :: FilePath -> String
fpFromString :: String -> FilePath

-- | Translates a FilePath to a Text This translation is not correct for a
--   (unix) filename which can contain arbitrary (non-unicode) bytes: those
--   bytes will be discarded
--   
--   This means you cannot translate the Text back to the original file
--   name.
--   
--   If you control or otherwise understand the filenames and believe them
--   to be unicode valid consider using <a>fpToTextEx</a> or
--   <a>fpToTextWarn</a>
fpToText :: FilePath -> Text
fpFromText :: Text -> FilePath

-- | Translates a FilePath to a Text Warns if there are non-unicode
--   sequences in the file name
fpToTextWarn :: MonadIO m => FilePath -> m Text

-- | Translates a FilePath to a Text Throws an exception if there are
--   non-unicode sequences in the file name
--   
--   Use this to assert that you know a filename will translate properly
--   into a Text If you created the filename, this should be the case.
fpToTextEx :: FilePath -> Text

-- | A class for monads in which exceptions may be thrown.
--   
--   Instances should obey the following law:
--   
--   <pre>
--   throwM e &gt;&gt; x = throwM e
--   </pre>
--   
--   In other words, throwing an exception short-circuits the rest of the
--   monadic computation.
class Monad m => MonadThrow (m :: * -> *)
throwM :: (MonadThrow m, Exception e) => e -> m a
asByteString :: ByteString -> ByteString
asLByteString :: LByteString -> LByteString
asHashMap :: HashMap k v -> HashMap k v
asHashSet :: HashSet a -> HashSet a
asText :: Text -> Text
asLText :: LText -> LText
asList :: [a] -> [a]
asMap :: Map k v -> Map k v
asIntMap :: IntMap v -> IntMap v
asMaybe :: Maybe a -> Maybe a
asSet :: Set a -> Set a
asIntSet :: IntSet -> IntSet
asVector :: Vector a -> Vector a
asUVector :: UVector a -> UVector a
asSVector :: SVector a -> SVector a