BasicPrelude

BasicPrelude mostly re-exports several key libraries in their entirety. The exception is Data.List, where various functions are replaced by similar versions that are either generalized, operate on Text, or are implemented strictly.

Module exports

module CorePrelude

module Data.List

module Control.Monad

Folds and traversals

class Foldable t where

Data structures that can be folded.

Minimal complete definition: foldMap or foldr.

For example, given a data type

data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)

a suitable instance would be

instance Foldable Tree where
   foldMap f Empty = mempty
   foldMap f (Leaf x) = f x
   foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r

This is suitable even for abstract types, as the monoid is assumed to satisfy the monoid laws. Alternatively, one could define foldr:

instance Foldable Tree where
   foldr f z Empty = z
   foldr f z (Leaf x) = f x z
   foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l

Minimal complete definition

foldMap | foldr

Methods

foldMap :: Monoid m => (a -> m) -> t a -> m

Map each element of the structure to a monoid, and combine the results.

foldr :: (a -> b -> b) -> b -> t a -> b

Right-associative fold of a structure.

foldr f z = foldr f z . toList

foldr' :: (a -> b -> b) -> b -> t a -> b

Right-associative fold of a structure, but with strict application of the operator.

foldl :: (b -> a -> b) -> b -> t a -> b

Left-associative fold of a structure.

foldl f z = foldl f z . toList

foldl' :: (b -> a -> b) -> b -> t a -> b

Left-associative fold of a structure. but with strict application of the operator.

foldl f z = foldl' f z . toList

foldr1 :: (a -> a -> a) -> t a -> a

A variant of foldr that has no base case, and thus may only be applied to non-empty structures.

foldr1 f = foldr1 f . toList

foldl1 :: (a -> a -> a) -> t a -> a

A variant of foldl that has no base case, and thus may only be applied to non-empty structures.

foldl1 f = foldl1 f . toList

Instances

Foldable []

Foldable Maybe

Foldable Digit

Foldable Node

Foldable Elem

Foldable FingerTree

Foldable IntMap

Foldable Set

Foldable Seq

Foldable ViewL

Foldable ViewR

Foldable Identity

Foldable HashSet

Foldable Vector

Foldable (Either a)

Foldable ((,) a)

Ix i => Foldable (Array i)

Foldable (Const m)

Foldable (Proxy *)

Foldable (Map k)

Foldable f => Foldable (MaybeT f)

Foldable f => Foldable (ListT f)

Foldable f => Foldable (IdentityT f)

Foldable (HashMap k)

Foldable f => Foldable (WriterT w f)

Foldable f => Foldable (WriterT w f)

Foldable f => Foldable (ErrorT e f)

Foldable f => Foldable (ExceptT e f)

elem :: (Foldable t, Eq a) => a -> t a -> Bool

Does the element occur in the structure?

maximum :: (Foldable t, Ord a) => t a -> a

The largest element of a non-empty structure.

minimum :: (Foldable t, Ord a) => t a -> a

The least element of a non-empty structure.

class (Functor t, Foldable t) => Traversable t where

Functors representing data structures that can be traversed from left to right.

Minimal complete definition: traverse or sequenceA.

A definition of traverse must satisfy the following laws:

naturality

t . traverse f = traverse (t . f) for every applicative transformation t

identity

traverse Identity = Identity

composition

traverse (Compose . fmap g . f) = Compose . fmap (traverse g) . traverse f

A definition of sequenceA must satisfy the following laws:

naturality

t . sequenceA = sequenceA . fmap t for every applicative transformation t

identity

sequenceA . fmap Identity = Identity

composition

sequenceA . fmap Compose = Compose . fmap sequenceA . sequenceA

where an applicative transformation is a function

t :: (Applicative f, Applicative g) => f a -> g a

preserving the Applicative operations, i.e.

• t (pure x) = pure x

• t (x <*> y) = t x <*> t y

and the identity functor Identity and composition of functors Compose are defined as

  newtype Identity a = Identity a

  instance Functor Identity where
    fmap f (Identity x) = Identity (f x)

  instance Applicative Indentity where
    pure x = Identity x
    Identity f <*> Identity x = Identity (f x)

  newtype Compose f g a = Compose (f (g a))

  instance (Functor f, Functor g) => Functor (Compose f g) where
    fmap f (Compose x) = Compose (fmap (fmap f) x)

  instance (Applicative f, Applicative g) => Applicative (Compose f g) where
    pure x = Compose (pure (pure x))
    Compose f <*> Compose x = Compose ((<*>) <$> f <*> x)

(The naturality law is implied by parametricity.)

Instances are similar to Functor, e.g. given a data type

data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)

a suitable instance would be

instance Traversable Tree where
   traverse f Empty = pure Empty
   traverse f (Leaf x) = Leaf <$> f x
   traverse f (Node l k r) = Node <$> traverse f l <*> f k <*> traverse f r

This is suitable even for abstract types, as the laws for <*> imply a form of associativity.

The superclass instances should satisfy the following:

• In the Functor instance, fmap should be equivalent to traversal with the identity applicative functor (fmapDefault).
• In the Foldable instance, foldMap should be equivalent to traversal with a constant applicative functor (foldMapDefault).

Minimal complete definition

traverse | sequenceA

Methods

traverse :: Applicative f => (a -> f b) -> t a -> f (t b)

Map each element of a structure to an action, evaluate these actions from left to right, and collect the results.

sequenceA :: Applicative f => t (f a) -> f (t a)

Evaluate each action in the structure from left to right, and collect the results.

mapM :: Monad m => (a -> m b) -> t a -> m (t b)

Map each element of a structure to a monadic action, evaluate these actions from left to right, and collect the results.

sequence :: Monad m => t (m a) -> m (t a)

Evaluate each monadic action in the structure from left to right, and collect the results.

Instances

Traversable []

Traversable Maybe

Traversable Digit

Traversable Node

Traversable Elem

Traversable FingerTree

Traversable IntMap

Traversable Seq

Traversable ViewL

Traversable ViewR

Traversable Identity

Traversable Vector

Traversable (Either a)

Traversable ((,) a)

Ix i => Traversable (Array i)

Traversable (Const m)

Traversable (Proxy *)

Traversable (Map k)

Traversable f => Traversable (MaybeT f)

Traversable f => Traversable (ListT f)

Traversable f => Traversable (IdentityT f)

Traversable (HashMap k)

Traversable f => Traversable (WriterT w f)

Traversable f => Traversable (WriterT w f)

Traversable f => Traversable (ErrorT e f)

Traversable f => Traversable (ExceptT e f)

Enhanced exports

Simpler name for a typeclassed operation

map :: Functor f => (a -> b) -> f a -> f b

map = fmap

empty :: Monoid w => w

empty = mempty

(++) :: Monoid w => w -> w -> w infixr 5

(++) = mappend

concat :: Monoid w => [w] -> w

concat = mconcat

intercalate :: Monoid w => w -> [w] -> w

intercalate = mconcat .: intersperse

Strict implementation

sum :: Num a => [a] -> a

Compute the sum of a finite list of numbers.

product :: Num a => [a] -> a

Compute the product of a finite list of numbers.

Text for Read and Show operations

show :: Show a => a -> Text

Convert a value to readable Text

fromShow :: (Show a, IsString b) => a -> b

Convert a value to readable IsString

Since 0.3.12

read :: Read a => Text -> a

Parse Text to a value

readIO :: Read a => Text -> IO a

The readIO function is similar to read except that it signals parse failure to the IO monad instead of terminating the program.

FilePath for file operations

readFile :: FilePath -> IO Text

Read a file and return the contents of the file as Text. The entire file is read strictly.

writeFile :: FilePath -> Text -> IO ()

Write Text to a file. The file is truncated to zero length before writing begins.

appendFile :: FilePath -> Text -> IO ()

Write Text to the end of a file.

Text exports

Text operations (Pure)

lines :: Text -> [Text]

O(n) Breaks a Text up into a list of Texts at newline Chars. The resulting strings do not contain newlines.

words :: Text -> [Text]

O(n) Breaks a Text up into a list of words, delimited by Chars representing white space.

unlines :: [Text] -> Text

O(n) Joins lines, after appending a terminating newline to each.

unwords :: [Text] -> Text

O(n) Joins words using single space characters.

textToString :: Text -> String

ltextToString :: LText -> String

fpToText :: FilePath -> Text

Deprecated: Use Data.Text.pack

This function assumes file paths are encoded in UTF8. If it cannot decode the FilePath, the result is just an approximation.

Since 0.3.13

fpFromText :: Text -> FilePath

Deprecated: Use Data.Text.unpack

Since 0.3.13

fpToString :: FilePath -> String

Deprecated: Use id

Since 0.3.13

encodeUtf8 :: Text -> ByteString

Encode text using UTF-8 encoding.

decodeUtf8 :: ByteString -> Text

Note that this is not the standard Data.Text.Encoding.decodeUtf8. That function will throw impure exceptions on any decoding errors. This function instead uses decodeLenient.

Text operations (IO)

getLine :: IO Text

Read a single line of user input from stdin.

getContents :: IO Text

Lazily read all user input on stdin as a single string.

interact :: (Text -> Text) -> IO ()

The interact function takes a function of type Text -> Text as its argument. The entire input from the standard input device is passed (lazily) to this function as its argument, and the resulting string is output on the standard output device.

Miscellaneous prelude re-exports

Math

gcd :: Integral a => a -> a -> a

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.

lcm :: Integral a => a -> a -> a

lcm x y is the smallest positive integer that both x and y divide.

Show and Read

type ShowS = String -> String

The shows functions return a function that prepends the output String to an existing String. This allows constant-time concatenation of results using function composition.

showsPrec

Arguments

:: Show a

=> Int

the operator precedence of the enclosing context (a number from 0 to 11). Function application has precedence 10.

-> a

the value to be converted to a String

-> ShowS

Convert a value to a readable String.

showsPrec should satisfy the law

showsPrec d x r ++ s  ==  showsPrec d x (r ++ s)

Derived instances of Read and Show satisfy the following:

• (x,"") is an element of (readsPrec d (showsPrec d x "")).

That is, readsPrec parses the string produced by showsPrec, and delivers the value that showsPrec started with.

showList :: Show a => [a] -> ShowS

The method showList is provided to allow the programmer to give a specialised way of showing lists of values. For example, this is used by the predefined Show instance of the Char type, where values of type String should be shown in double quotes, rather than between square brackets.

shows :: Show a => a -> ShowS

equivalent to showsPrec with a precedence of 0.

showChar :: Char -> ShowS

utility function converting a Char to a show function that simply prepends the character unchanged.

showString :: String -> ShowS

utility function converting a String to a show function that simply prepends the string unchanged.

showParen :: Bool -> ShowS -> ShowS

utility function that surrounds the inner show function with parentheses when the Bool parameter is True.

type ReadS a = String -> [(a, String)]

A parser for a type a, represented as a function that takes a String and returns a list of possible parses as (a,String) pairs.

Note that this kind of backtracking parser is very inefficient; reading a large structure may be quite slow (cf ReadP).

readsPrec

Arguments

:: Read a

=> Int

the operator precedence of the enclosing context (a number from 0 to 11). Function application has precedence 10.

-> ReadS a

attempts to parse a value from the front of the string, returning a list of (parsed value, remaining string) pairs. If there is no successful parse, the returned list is empty.

Derived instances of Read and Show satisfy the following:

• (x,"") is an element of (readsPrec d (showsPrec d x "")).

That is, readsPrec parses the string produced by showsPrec, and delivers the value that showsPrec started with.

readList :: Read a => ReadS [a]

The method readList is provided to allow the programmer to give a specialised way of parsing lists of values. For example, this is used by the predefined Read instance of the Char type, where values of type String should be are expected to use double quotes, rather than square brackets.

reads :: Read a => ReadS a

equivalent to readsPrec with a precedence of 0.

readParen :: Bool -> ReadS a -> ReadS a

readParen True p parses what p parses, but surrounded with parentheses.

readParen False p parses what p parses, but optionally surrounded with parentheses.

lex :: ReadS String

The lex function reads a single lexeme from the input, discarding initial white space, and returning the characters that constitute the lexeme. If the input string contains only white space, lex returns a single successful `lexeme' consisting of the empty string. (Thus lex "" = [("","")].) If there is no legal lexeme at the beginning of the input string, lex fails (i.e. returns []).

This lexer is not completely faithful to the Haskell lexical syntax in the following respects:

• Qualified names are not handled properly
• Octal and hexadecimal numerics are not recognized as a single token
• Comments are not treated properly

readMay :: Read a => Text -> Maybe a

IO operations

putChar :: Char -> IO ()

Write a character to the standard output device (same as hPutChar stdout).

getChar :: IO Char

Read a character from the standard input device (same as hGetChar stdin).

readLn :: Read a => IO a

The readLn function combines getLine and readIO.