read -package:tar -package:vector-sized package:protolude

The read function reads input from a string, which must be completely consumed by the input process. read fails with an error if the parse is unsuccessful, and it is therefore discouraged from being used in real applications. Use readMaybe or readEither for safe alternatives.

>>> read "123" :: Int
123

>>> read "hello" :: Int
*** Exception: Prelude.read: no parse

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

Read the next value from the Chan. Blocks when the channel is empty. Since the read end of a channel is an MVar, this operation inherits fairness guarantees of MVars (e.g. threads blocked in this operation are woken up in FIFO order). Throws BlockedIndefinitelyOnMVar when the channel is empty and no other thread holds a reference to the channel.

Parse a string using the Read instance. Succeeds if there is exactly one valid result. A Left value indicates a parse error.

>>> readEither "123" :: Either Text Int
Right 123

>>> readEither "hello" :: Either Text Int
Left "Prelude.read: no parse"

The readFile function reads a file and returns the contents of the file as a string. The entire file is read strictly, as with getContents.

Atomically read the contents of an MVar. If the MVar is currently empty, readMVar will wait until it is full. readMVar is guaranteed to receive the next putMVar. readMVar is multiple-wakeup, so when multiple readers are blocked on an MVar, all of them are woken up at the same time. Compatibility note: Prior to base 4.7, readMVar was a combination of takeMVar and putMVar. This mean that in the presence of other threads attempting to putMVar, readMVar could block. Furthermore, readMVar would not receive the next putMVar if there was already a pending thread blocked on takeMVar. The old behavior can be recovered by implementing 'readMVar as follows:

readMVar :: MVar a -> IO a
readMVar m =
mask_ $ do
a <- takeMVar m
putMVar m a
return a

Parse a string using the Read instance. Succeeds if there is exactly one valid result.

>>> readMaybe ("123" :: Text) :: Maybe Int
Just 123

>>> readMaybe ("hello" :: Text) :: Maybe Int
Nothing

Retrieves a function of the current environment.

equivalent to readsPrec with a precedence of 0.

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.

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.

See examples in Control.Monad.Reader. Note, the partially applied function type (->) r is a simple reader monad. See the instance declaration below.

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.

This exception is raised by another thread calling killThread, or by the system if it needs to terminate the thread for some reason.

Returns True if the calling thread is bound, that is, if it is safe to use foreign libraries that rely on thread-local state from the calling thread.

killThread raises the ThreadKilled exception in the given thread (GHC only).

killThread tid = throwTo tid ThreadKilled

Make a weak pointer to a ThreadId. It can be important to do this if you want to hold a reference to a ThreadId while still allowing the thread to receive the BlockedIndefinitely family of exceptions (e.g. BlockedIndefinitelyOnMVar). Holding a normal ThreadId reference will prevent the delivery of BlockedIndefinitely exceptions because the reference could be used as the target of throwTo at any time, which would unblock the thread. Holding a Weak ThreadId, on the other hand, will not prevent the thread from receiving BlockedIndefinitely exceptions. It is still possible to throw an exception to a Weak ThreadId, but the caller must use deRefWeak first to determine whether the thread still exists.

Returns the ThreadId of the calling thread (GHC only).

True if bound threads are supported. If rtsSupportsBoundThreads is False, isCurrentThreadBound will always return False and both forkOS and runInBoundThread will fail.

Run the IO computation passed as the first argument. If the calling thread is not bound, a bound thread is created temporarily. runInBoundThread doesn't finish until the IO computation finishes. You can wrap a series of foreign function calls that rely on thread-local state with runInBoundThread so that you can use them without knowing whether the current thread is bound.

Run the IO computation passed as the first argument. If the calling thread is bound, an unbound thread is created temporarily using forkIO. runInBoundThread doesn't finish until the IO computation finishes. Use this function only in the rare case that you have actually observed a performance loss due to the use of bound threads. A program that doesn't need its main thread to be bound and makes heavy use of concurrency (e.g. a web server), might want to wrap its main action in runInUnboundThread. Note that exceptions which are thrown to the current thread are thrown in turn to the thread that is executing the given computation. This ensures there's always a way of killing the forked thread.

Runs a Reader and extracts the final value from it. (The inverse of reader.)