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


-- | properly streaming text
--   
--   <i>New in version 0.0.2.x</i>: The new module
--   <tt>Pipes.Prelude.Text</tt> exports line-based <tt>Text</tt> producers
--   and consumers as a drop-in replacement for the <tt>String</tt>
--   material in <tt>Pipes.Prelude</tt> and <tt>Pipes.Safe.Prelude</tt>.
--   They can be used as one uses <tt>Pipes.Prelude</tt> without reference
--   to the rest of this package. See the caveats in the documentation for
--   that module.
--   
--   The organization of this package follows the rule:
--   
--   <ul>
--   <li><pre>pipes-text : pipes-bytestring :: text : bytestring</pre></li>
--   </ul>
--   
--   Familiarity with the other three packages should give one an idea what
--   to expect where. The package has three principal modules,
--   <tt>Pipes.Text</tt> , <tt>Pipes.Text.Encoding</tt> and
--   <tt>Pipes.Text.IO</tt>; the division has more or less the significance
--   it has in the <tt>text</tt> library.
--   
--   The module <tt>Pipes.Text.IO</tt> is present as a convenience.
--   Official pipes IO uses <tt>Pipes.ByteString</tt> together with the
--   bytestring decoding functions in <tt>Pipes.Text.Encoding</tt>. In
--   particular, the <tt>Pipes.Text.IO</tt> functions use Text exceptions,
--   while <tt>Pipes.Text</tt> uses the standard pipes practice of breaking
--   with a failed parse. Thus, for example, the type of
--   <tt>decodeUtf8</tt> is
--   
--   <ul>
--   <li><pre>decodeUtf8 :: Monad m =&gt; Producer ByteString m r -&gt;
--   Producer Text m (Producer ByteString m r)</pre></li>
--   </ul>
--   
--   where any unparsed bytes are returned.
--   
--   <tt>Pipes.Text.IO</tt> and <tt>Pipes.Prelude.Text</tt> use version
--   0.11.3 or later of the <tt>text</tt> library; older versions of
--   <tt>text</tt> can be used with the flag <tt>-fnoio</tt>
@package pipes-text
@version 0.0.2.5

module Pipes.Prelude.Text

-- | Read separate lines of <a>Text</a> from a <a>Handle</a> using
--   <a>hGetLine</a>, terminating at the end of input
--   
--   This operation will accumulate indefinitely large strict texts. See
--   the caveats above.
fromHandleLn :: MonadIO m => Handle -> Producer' Text m ()

-- | Write separate lines of <a>Text</a> to a <a>Handle</a> using
--   <a>hPutStrLn</a>
toHandleLn :: MonadIO m => Handle -> Consumer' Text m r

-- | Read separate lines of <a>Text</a> from <a>stdin</a> using
--   <a>getLine</a>, terminating on end of input.
--   
--   This function will accumulate indefinitely long strict <a>Text</a>s.
--   See the caveats above.
stdinLn :: MonadIO m => Producer' Text m ()

-- | Write <a>Text</a> lines to <a>stdout</a> using <a>putStrLn</a>,
--   terminating without error on a broken output pipe
stdoutLn :: MonadIO m => Consumer' Text m ()

-- | Write lines of <a>Text</a> to <a>stdout</a>. This does not handle a
--   broken output pipe, but has a polymorphic return value.
stdoutLn' :: MonadIO m => Consumer' Text m r

-- | Stream separate lines of text from a file. Apply <tt>runSafeT</tt>
--   after running the pipeline to manage the opening and closing of the
--   handle.
--   
--   This operation will accumulate indefinitely long strict text chunks.
--   See the caveats above.
readFileLn :: MonadSafe m => FilePath -> Producer Text m ()

-- | Write lines to a file. Apply <tt>runSafeT</tt> after running the
--   pipeline to manage the opening and closing of the handle.
writeFileLn :: (MonadSafe m) => FilePath -> Consumer' Text m r


-- | The module <tt>Pipes.Text</tt> closely follows
--   <tt>Pipes.ByteString</tt> from the <tt>pipes-bytestring</tt> package.
--   A draft tutorial can be found in <tt>Pipes.Text.Tutorial</tt>.
module Pipes.Text

-- | Convert a lazy <a>Text</a> into a <a>Producer</a> of strict
--   <a>Text</a>s. Producers in IO can be found in <a>IO</a> or in
--   pipes-bytestring, employed with the decoding lenses in <a>Encoding</a>
fromLazy :: (Monad m) => Text -> Producer' Text m ()

-- | Apply a transformation to each <a>Char</a> in the stream
map :: (Monad m) => (Char -> Char) -> Pipe Text Text m r

-- | Map a function over the characters of a text stream and concatenate
--   the results
concatMap :: (Monad m) => (Char -> Text) -> Pipe Text Text m r

-- | <tt>(take n)</tt> only allows <tt>n</tt> individual characters to
--   pass; contrast <tt>Pipes.Prelude.take</tt> which would let <tt>n</tt>
--   chunks pass.
take :: (Monad m, Integral a) => a -> Pipe Text Text m ()

-- | Take characters until they fail the predicate
takeWhile :: (Monad m) => (Char -> Bool) -> Pipe Text Text m ()

-- | Only allows <a>Char</a>s to pass if they satisfy the predicate
filter :: (Monad m) => (Char -> Bool) -> Pipe Text Text m r

-- | <tt>toCaseFold</tt>, <tt>toLower</tt>, <tt>toUpper</tt> and
--   <tt>stripStart</tt> are standard <a>Text</a> utilities, here acting as
--   <a>Text</a> pipes, rather as they would on a lazy text
toCaseFold :: Monad m => Pipe Text Text m r

-- | lowercase incoming <a>Text</a>
toLower :: Monad m => Pipe Text Text m r

-- | uppercase incoming <a>Text</a>
toUpper :: Monad m => Pipe Text Text m r

-- | Remove leading white space from an incoming succession of <a>Text</a>s
stripStart :: Monad m => Pipe Text Text m r

-- | Strict left scan over the characters &gt;&gt;&gt; let margaret =
--   ["Margaret, are you grievingnOver Golde","ngrove unleaving?":: Text]
--   &gt;&gt;&gt; let title_caser a x = case a of ' ' -&gt;
--   Data.Char.toUpper x; _ -&gt; x &gt;&gt;&gt; toLazy $ each margaret
--   &gt;-&gt; scan title_caser ' ' " Margaret, Are You GrievingnOver
--   Goldengrove Unleaving?"
scan :: (Monad m) => (Char -> Char -> Char) -> Char -> Pipe Text Text m r

-- | Fold a pure <a>Producer</a> of strict <a>Text</a>s into a lazy
--   <a>Text</a>
toLazy :: Producer Text Identity () -> Text

-- | Fold an effectful <a>Producer</a> of strict <a>Text</a>s into a lazy
--   <a>Text</a>
--   
--   Note: <a>toLazyM</a> is not an idiomatic use of <tt>pipes</tt>, but I
--   provide it for simple testing purposes. Idiomatic <tt>pipes</tt> style
--   consumes the chunks immediately as they are generated instead of
--   loading them all into memory.
toLazyM :: (Monad m) => Producer Text m () -> m Text

-- | Reduce the text stream using a strict left fold over characters
foldChars :: Monad m => (x -> Char -> x) -> x -> (x -> r) -> Producer Text m () -> m r

-- | Retrieve the first <a>Char</a>
head :: (Monad m) => Producer Text m () -> m (Maybe Char)

-- | Retrieve the last <a>Char</a>
last :: (Monad m) => Producer Text m () -> m (Maybe Char)

-- | Determine if the stream is empty
null :: (Monad m) => Producer Text m () -> m Bool

-- | Count the number of characters in the stream
length :: (Monad m, Num n) => Producer Text m () -> m n

-- | Fold that returns whether <a>Any</a> received <a>Char</a>s satisfy the
--   predicate
any :: (Monad m) => (Char -> Bool) -> Producer Text m () -> m Bool

-- | Fold that returns whether <a>All</a> received <a>Char</a>s satisfy the
--   predicate
all :: (Monad m) => (Char -> Bool) -> Producer Text m () -> m Bool

-- | Return the maximum <a>Char</a> within a text stream
maximum :: (Monad m) => Producer Text m () -> m (Maybe Char)

-- | Return the minimum <a>Char</a> within a text stream (surely very
--   useful!)
minimum :: (Monad m) => Producer Text m () -> m (Maybe Char)

-- | Find the first element in the stream that matches the predicate
find :: (Monad m) => (Char -> Bool) -> Producer Text m () -> m (Maybe Char)

-- | Index into a text stream
index :: (Monad m, Integral a) => a -> Producer Text m () -> m (Maybe Char)

-- | Consume the first character from a stream of <a>Text</a>
--   
--   <a>next</a> either fails with a <a>Left</a> if the <a>Producer</a> has
--   no more characters or succeeds with a <a>Right</a> providing the next
--   character and the remainder of the <a>Producer</a>.
nextChar :: (Monad m) => Producer Text m r -> m (Either r (Char, Producer Text m r))

-- | Draw one <a>Char</a> from a stream of <a>Text</a>, returning
--   <a>Left</a> if the <a>Producer</a> is empty
drawChar :: (Monad m) => Parser Text m (Maybe Char)

-- | Push back a <a>Char</a> onto the underlying <a>Producer</a>
unDrawChar :: (Monad m) => Char -> Parser Text m ()

-- | <a>peekChar</a> checks the first <a>Char</a> in the stream, but uses
--   <a>unDrawChar</a> to push the <a>Char</a> back
--   
--   <pre>
--   peekChar = do
--       x &lt;- drawChar
--       case x of
--           Left  _  -&gt; return ()
--           Right c -&gt; unDrawChar c
--       return x
--   </pre>
peekChar :: (Monad m) => Parser Text m (Maybe Char)

-- | Check if the underlying <a>Producer</a> has no more characters
--   
--   Note that this will skip over empty <a>Text</a> chunks, unlike
--   <a>isEndOfInput</a> from <tt>pipes-parse</tt>, which would consider an
--   empty <a>Text</a> a valid bit of input.
--   
--   <pre>
--   isEndOfChars = liftM isLeft peekChar
--   </pre>
isEndOfChars :: (Monad m) => Parser Text m Bool

-- | Splits a <a>Producer</a> after the given number of characters
splitAt :: (Monad m, Integral n) => n -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))

-- | Split a text stream in two, producing the longest consecutive group of
--   characters that satisfies the predicate and returning the rest
span :: (Monad m) => (Char -> Bool) -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))

-- | Split a text stream in two, producing the longest consecutive group of
--   characters that don't satisfy the predicate
break :: (Monad m) => (Char -> Bool) -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))

-- | Improper lens that splits after the first group of equivalent Chars,
--   as defined by the given equivalence relation
groupBy :: (Monad m) => (Char -> Char -> Bool) -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))

-- | Improper lens that splits after the first succession of identical
--   <a>Char</a> s
group :: Monad m => Lens' (Producer Text m r) (Producer Text m (Producer Text m r))

-- | Improper lens that splits a <a>Producer</a> after the first word
--   
--   Unlike <a>words</a>, this does not drop leading whitespace
word :: (Monad m) => Lens' (Producer Text m r) (Producer Text m (Producer Text m r))
line :: (Monad m) => Lens' (Producer Text m r) (Producer Text m (Producer Text m r))

-- | <tt>(drop n)</tt> drops the first <tt>n</tt> characters
drop :: (Monad m, Integral n) => n -> Producer Text m r -> Producer Text m r

-- | Drop characters until they fail the predicate
dropWhile :: (Monad m) => (Char -> Bool) -> Producer Text m r -> Producer Text m r

-- | Improper lens from unpacked <tt>Word8</tt>s to packaged
--   <a>ByteString</a>s
pack :: Monad m => Lens' (Producer Char m r) (Producer Text m r)

-- | Improper lens from packed <a>ByteString</a>s to unpacked
--   <tt>Word8</tt>s
unpack :: Monad m => Lens' (Producer Text m r) (Producer Char m r)

-- | Intersperse a <a>Char</a> in between the characters of stream of
--   <a>Text</a>
intersperse :: (Monad m) => Char -> Producer Text m r -> Producer Text m r

-- | Split a text stream into <a>FreeT</a>-delimited text streams of fixed
--   size
chunksOf :: (Monad m, Integral n) => n -> Lens' (Producer Text m r) (FreeT (Producer Text m) m r)

-- | Split a text stream into sub-streams delimited by characters that
--   satisfy the predicate
splitsWith :: (Monad m) => (Char -> Bool) -> Producer Text m r -> FreeT (Producer Text m) m r

-- | Split a text stream using the given <a>Char</a> as the delimiter
splits :: (Monad m) => Char -> Lens' (Producer Text m r) (FreeT (Producer Text m) m r)

-- | Isomorphism between a stream of <a>Text</a> and groups of equivalent
--   <a>Char</a>s , using the given equivalence relation
groupsBy :: Monad m => (Char -> Char -> Bool) -> Lens' (Producer Text m x) (FreeT (Producer Text m) m x)

-- | Like <a>groupsBy</a>, where the equality predicate is (<a>==</a>)
groups :: Monad m => Lens' (Producer Text m x) (FreeT (Producer Text m) m x)

-- | Split a text stream into <a>FreeT</a>-delimited lines
lines :: (Monad m) => Lens' (Producer Text m r) (FreeT (Producer Text m) m r)
unlines :: Monad m => Lens' (FreeT (Producer Text m) m r) (Producer Text m r)

-- | Split a text stream into <a>FreeT</a>-delimited words. Note that
--   roundtripping with e.g. <tt>over words id</tt> eliminates extra space
--   characters as with <tt>Prelude.unwords . Prelude.words</tt>
words :: (Monad m) => Lens' (Producer Text m r) (FreeT (Producer Text m) m r)
unwords :: Monad m => Lens' (FreeT (Producer Text m) m r) (Producer Text m r)

-- | <a>intercalate</a> concatenates the <a>FreeT</a>-delimited text
--   streams after interspersing a text stream in between them
intercalate :: (Monad m) => Producer Text m () -> FreeT (Producer Text m) m r -> Producer Text m r


-- | This module uses the stream decoding functions from
--   <a>streaming-commons</a> package to define decoding functions and
--   lenses. The exported names conflict with names in
--   <tt>Data.Text.Encoding</tt> but not with the <tt>Prelude</tt>
module Pipes.Text.Encoding
type Codec = forall m r. Monad m => Lens' (Producer ByteString m r) (Producer Text m (Producer ByteString m r))

-- | <tt>decode</tt> is just the ordinary <tt>view</tt> or <tt>(^.)</tt> of
--   the lens libraries; exported here under a name appropriate to the
--   material. Thus given a bytestring producer called <tt>bytes</tt> we
--   have
--   
--   <pre>
--   decode utf8 bytes :: Producer Text IO (Producer ByteString IO ())
--   </pre>
--   
--   All of these are thus the same:
--   
--   <pre>
--   decode utf8 bytes 
--   view utf8 bytes
--   bytes ^. utf8 
--   decodeUtf8 bytes
--   </pre>
decode :: ((b -> Constant b b) -> (a -> Constant b a)) -> a -> b

-- | <tt>eof</tt> tells you explicitly when decoding stops due to bad bytes
--   or instead reaches end-of-file happily. (Without it one just makes an
--   explicit test for emptiness of the resulting bytestring production
--   using next) Thus
--   
--   <pre>
--   decode (utf8 . eof) bytes :: Producer T.Text IO (Either (Producer B.ByteString IO ()) ())
--   </pre>
--   
--   If we hit undecodable bytes, the remaining bytestring producer will be
--   returned as a Left value; in the happy case, a Right value is returned
--   with the anticipated return value for the original bytestring
--   producer.
--   
--   Given a bytestring producer called <tt>bytes</tt> all of these will be
--   the same:
--   
--   <pre>
--   decode (utf8 . eof) bytes 
--   view (utf8 . eof) bytes
--   bytes^.utf8.eof
--   </pre>
eof :: (Monad m, Monad (t m), MonadTrans t) => Lens' (t m (Producer ByteString m r)) (t m (Either (Producer ByteString m r) r))
utf8 :: Codec
utf8Pure :: Codec
utf16LE :: Codec
utf16BE :: Codec
utf32LE :: Codec
utf32BE :: Codec
decodeUtf8 :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
decodeUtf8Pure :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
decodeUtf16LE :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
decodeUtf16BE :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
decodeUtf32LE :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
decodeUtf32BE :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
encodeUtf8 :: Monad m => Text -> Producer' ByteString m ()
encodeUtf16LE :: Monad m => Text -> Producer' ByteString m ()
encodeUtf16BE :: Monad m => Text -> Producer' ByteString m ()
encodeUtf32LE :: Monad m => Text -> Producer' ByteString m ()
encodeUtf32BE :: Monad m => Text -> Producer' ByteString m ()

-- | <a>encodeAscii</a> reduces as much of your stream of <a>Text</a>
--   actually is ascii to a byte stream, returning the rest of the
--   <a>Text</a> at the first non-ascii <a>Char</a>
encodeAscii :: Monad m => Producer Text m r -> Producer ByteString m (Producer Text m r)

-- | Reduce a byte stream to a corresponding stream of ascii chars,
--   returning the unused <a>ByteString</a> upon hitting an un-ascii byte.
decodeAscii :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)

-- | Reduce as much of your stream of <a>Text</a> actually is iso8859 or
--   latin1 to a byte stream, returning the rest of the <a>Text</a> upon
--   hitting any non-latin <a>Char</a>
encodeIso8859_1 :: Monad m => Producer Text m r -> Producer ByteString m (Producer Text m r)

-- | Reduce a byte stream to a corresponding stream of ascii chars,
--   returning the unused <a>ByteString</a> upon hitting the rare
--   un-latinizable byte.
decodeIso8859_1 :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)

module Pipes.Text.IO

-- | Convert a <a>Handle</a> into a text stream using a text size
--   determined by the good sense of the text library. Note with the
--   remarks at the head of this module that this is slower than <tt>view
--   utf8 (Pipes.ByteString.fromHandle h)</tt> but uses the system encoding
--   and has other nice <tt>Data.Text.IO</tt> features
fromHandle :: MonadIO m => Handle -> Producer Text m ()

-- | Stream text from <a>stdin</a>
stdin :: MonadIO m => Producer Text m ()

-- | Stream text from a file in the simple fashion of <tt>Data.Text.IO</tt>
--   
--   <pre>
--   &gt;&gt;&gt; runSafeT $ runEffect $ Text.readFile "hello.hs" &gt;-&gt; Text.map toUpper &gt;-&gt; hoist lift Text.stdout
--   MAIN = PUTSTRLN "HELLO WORLD"
--   </pre>
readFile :: MonadSafe m => FilePath -> Producer Text m ()

-- | Convert a text stream into a <tt>Handle</tt>
--   
--   Note: again, for best performance, where possible use <tt>(for source
--   (liftIO . hPutStr handle))</tt> instead of <tt>(source &gt;-&gt;
--   toHandle handle)</tt>.
toHandle :: MonadIO m => Handle -> Consumer' Text m r

-- | Stream text to <a>stdout</a>
--   
--   Unlike <a>toHandle</a>, <a>stdout</a> gracefully terminates on a
--   broken output pipe.
--   
--   Note: For best performance, it might be best just to use <tt>(for
--   source (liftIO . putStr))</tt> instead of <tt>(source &gt;-&gt;
--   stdout)</tt> .
stdout :: MonadIO m => Consumer' Text m ()

-- | Stream text into a file. Uses <tt>pipes-safe</tt>.
writeFile :: (MonadSafe m) => FilePath -> Consumer' Text m ()

-- | <a>MonadSafe</a> lets you <a>register</a> and <a>release</a>
--   finalizers that execute in a <a>Base</a> monad
class (MonadCatch m, MonadMask m, MonadIO m, MonadIO Base m) => MonadSafe (m :: * -> *) where {
    type family Base (m :: * -> *) :: * -> *;
}

-- | Lift an action from the <a>Base</a> monad
liftBase :: MonadSafe m => Base m r -> m r

-- | <a>register</a> a finalizer, ensuring that the finalizer gets called
--   if the finalizer is not <a>release</a>d before the end of the
--   surrounding <a>SafeT</a> block.
register :: MonadSafe m => Base m () -> m ReleaseKey

-- | <a>release</a> a registered finalizer
--   
--   You can safely call <a>release</a> more than once on the same
--   <a>ReleaseKey</a>. Every <a>release</a> after the first one does
--   nothing.
release :: MonadSafe m => ReleaseKey -> m ()

-- | Run the <a>SafeT</a> monad transformer, executing all unreleased
--   finalizers at the end of the computation
runSafeT :: (MonadMask m, MonadIO m) => SafeT m r -> m r

-- | Run <a>SafeT</a> in the base monad, executing all unreleased
--   finalizers at the end of the computation
--   
--   Use <a>runSafeP</a> to safely flush all unreleased finalizers and
--   ensure prompt finalization without exiting the <a>Proxy</a> monad.
runSafeP :: (MonadMask m, MonadIO m) => Effect SafeT m r -> Effect' m r

-- | Acquire a <a>Handle</a> within <a>MonadSafe</a>
withFile :: MonadSafe m => FilePath -> IOMode -> (Handle -> m r) -> m r

module Pipes.Text.Tutorial
