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


-- | Web framework
--   
--   Miscellaneous utilities for Happstack packages.
@package happstack-util
@version 0.5.0

module Happstack.Util.FileManip

-- | Unconditionally return <a>True</a>.
always :: FindClause Bool

-- | Search a directory recursively, with recursion controlled by a
--   <a>RecursionPredicate</a>. Lazily return a sorted list of all files
--   matching the given <a>FilterPredicate</a>. Any errors that occur are
--   ignored, with warnings printed to <a>stderr</a>.
find :: RecursionPredicate -> FilterPredicate -> FilePath -> IO [FilePath]
instance Functor FindClause
instance Monad FindClause
instance Eq FileInfo
instance Eq FileStatus

module Happstack.Util.TH

-- | Version of <a>instanceD</a> that takes in a Q [Dec] instead of a [Q
--   Dec] and filters out signatures from the list of declarations
instanceD' :: CxtQ -> TypeQ -> Q [Dec] -> DecQ

-- | Returns true if the Dec matches a SigD constructor
isSigD :: Dec -> Bool


-- | Cross platform way to open a file exclusively
module Happstack.Util.OpenExclusively
openExclusively :: FilePath -> IO Handle


-- | Mail is a simple library with which you can add email functionality to
--   your application. It assumes you have access to a smarthost which can
--   relay all your mail.
--   
--   As an example:
--   
--   <pre>
--   import Happstack.Util.Mail
--   main :: IO ()
--   main = do
--       sendSimpleMessages "10.2.23.11" "example.com" [message]
--       where message = SimpleMessage
--                           [NameAddr (Just "John Doe") "johnd@example.com"]
--                           [NameAddr (Just "Patch-Tag Team") "team@patch-tag.com"]
--                           "My test email using Happstack.Util.Mail"
--                           "Hi, this is a test email which uses Happstack."
--   </pre>
module Happstack.Util.Mail

-- | A NameAddr is composed of an optional realname a mandatory e-mail
--   <a>address</a>.
data NameAddr :: *
NameAddr :: Maybe String -> String -> NameAddr
nameAddr_name :: NameAddr -> Maybe String
nameAddr_addr :: NameAddr -> String
data SimpleMessage
SimpleMessage :: [NameAddr] -> [NameAddr] -> String -> String -> SimpleMessage

-- | The sender(s)
from :: SimpleMessage -> [NameAddr]

-- | The recipient(s)
to :: SimpleMessage -> [NameAddr]

-- | The subject line
subject :: SimpleMessage -> String

-- | The body
body :: SimpleMessage -> String

-- | Use this if you need more control than sendSimpleMessages gives you.
sendRawMessages :: SockAddr -> String -> [Message] -> IO ()

-- | Simplest way to send mail. Takes the smarthost ip, the HELO domain,
--   and a list of SimpleMessage.
sendSimpleMessages :: String -> String -> [SimpleMessage] -> IO ()
instance Show SimpleMessage

module Happstack.Util.LogFormat

-- | Format the time as describe in the Apache combined log format.
--   http:<i></i>httpd.apache.org<i>docs</i>2.2/logs.html#combined
--   
--   The format is: [day<i>month</i>year:hour:minute:second zone] day =
--   2*digit month = 3*letter year = 4*digit hour = 2*digit minute =
--   2*digit second = 2*digit zone = (<a>+</a> | <a>-</a>) 4*digit
formatTimeCombined :: (FormatTime t) => t -> String

-- | Format the request as describe in the Apache combined log format.
--   http:<i></i>httpd.apache.org<i>docs</i>2.2/logs.html#combined
--   
--   The format is: <a>%h - %u %t "%r" %&gt;s %b "%{Referer}i"
--   "%{User-agent}i"</a> %h: This is the IP address of the client (remote
--   host) which made the request to the server. %u: This is the userid of
--   the person requesting the document as determined by HTTP
--   authentication. %t: The time that the request was received. %r: The
--   request line from the client is given in double quotes. %&gt;s: This
--   is the status code that the server sends back to the client. %b: The
--   last part indicates the size of the object returned to the client, not
--   including the response headers. %{Referer}: The <a>Referer</a> (sic)
--   HTTP request header. %{User-agent}: The User-Agent HTTP request
--   header.
formatRequestCombined :: (FormatTime t) => String -> String -> t -> String -> Int -> Integer -> String -> String -> String

module Happstack.Util.HostAddress

-- | Converts a HostAddress to a String in dot-decimal notation
showHostAddress :: HostAddress -> String

-- | Converts a IPv6 HostAddress6 to standard hex notation
showHostAddress6 :: HostAddress6 -> String
type HostAddress = Word32
type HostAddress6 = (Word32, Word32, Word32, Word32)

module Happstack.Util.Cron

-- | Given an action f and a number of seconds t, cron will execute f every
--   t seconds with the first execution t seconds after cron is called.
--   cron does not spawn a new thread.
cron :: Seconds -> IO () -> IO a

module Happstack.Util.Concurrent

-- | Equivalent to a composition of fork and foreverSt
forkEverSt :: (t -> IO t) -> t -> IO ThreadId

-- | Similar to forever but with an explicit state parameter threaded
--   through the computation.
foreverSt :: (Monad m) => (t -> m t) -> t -> m b

-- | Equivalent to a composition of fork and forever
forkEver :: IO a -> IO ThreadId

-- | Lifts the argument with Right before writing it into the chan
writeChanRight :: Chan (Either a b) -> b -> IO ()

-- | Lifts the argument with Left before writing it into the chan
writeChanLeft :: Chan (Either a b) -> a -> IO ()

-- | Fork that throws away the ThreadId
fork_ :: IO a -> IO ()

-- | Fork a new thread.
fork :: IO a -> IO ThreadId

-- | Register an action to be run when ghci is restarted.
registerResetAction :: IO () -> IO ()

-- | Reset state
reset :: IO ()

-- | A version of forever that will gracefully catch IO exceptions and
--   continue executing the provided action.
forever :: IO a -> IO a

-- | Sleep N seconds
sleep :: Int -> IO ()


-- | Timeout implementation for performing operations in the IO monad with
--   a timeout added. Both using Maybe and exceptions to handle timeouts
--   are supported.
--   
--   Timeouts can be implemented in GHC with either a global handler or a
--   per-timeout thread which sleeps until the timeout. The latter is used
--   in this module. Blocking on foreign calls can cause problems as GHC
--   has no way of interrupting such threads. The module provides a
--   slightly slower alternative implementation which returns even if the
--   computation has blocked on a foreign call. This should not be an issue
--   unless -threaded is used.
--   
--   The timeouts are currently limited to a maximum of about 2000 seconds.
--   This is a feature of threadDelay, but supporting longer timeouts is
--   certainly possible if that is desirable.
--   
--   For nested timeouts there are different ways to implement them: a)
--   attach an id to the exception so that the catch knows wether it may
--   catch this timout exception. I've choosen this because overhead is
--   only passing and incrementing an integer value. A integer wrap araound
--   is possible but too unlikely to happen to make me worry about it b)
--   start a new workiing and killing thread so that if the original thread
--   was run within withTimeOut itself it catches the exception and not an
--   inner timout. (this is done in withSafeTimeOut, for another reason
--   though) c) keep throwing exceptions until the the withTimeOut function
--   kills the killing thread. But consider sequence (forever (timeOut
--   threadDelay 10sec) ) In this case the exception will be called and the
--   next timOut may be entered before the second Exception has been thrown
--   
--   All exceptions but the internal TimeOutExceptionI are rethrown in the
--   calling thread
module Happstack.Util.TimeOut

-- | This is the normal timeout handler. It throws a TimeOutException
--   exception, if the timeout occurs.
withTimeOut :: Int -> IO a -> IO a

-- | This handler returns <tt>Nothing</tt> if the timeout occurs and
--   <tt>Just a</tt> if computation returns <tt>a</tt>.
withTimeOutMaybe :: Int -> IO a -> IO (Maybe a)

-- | Like timeOut, but additionally it works even if the computation is
--   blocking async exceptions (explicitely or by a blocking FFI call).
--   This consumes more resources than timeOut, but is still quite fast.
withSafeTimeOut :: Int -> IO a -> IO a

-- | Like withTimeOutMaybe, but handles the operation blocking exceptions
--   like withSafeTimeOut does.
withSafeTimeOutMaybe :: Int -> IO a -> IO (Maybe a)
data TimeOutException
TimeOutException :: TimeOutException

-- | Constant representing one second.
second :: Int
instance Typeable TimeOutException
instance Typeable TimeOutExceptionI
instance Show TimeOutException
instance Exception TimeOutException
instance Exception TimeOutExceptionI
instance Show TimeOutExceptionI


-- | Various helper routines.
module Happstack.Util.Common
type Seconds = Int
type EpochSeconds = Int64
epochSeconds :: CalendarTime -> EpochSeconds
eSecsToCalTime :: EpochSeconds -> IO CalendarTime
epochPico :: CalendarTime -> Integer
logMC :: Priority -> String -> IO ()

-- | Put a line into a handle followed by <a>rn</a> and echo to stdout
hPutLine :: Handle -> String -> IO ()

-- | Get a line from the handle and echo to stdout
hGetLn :: Handle -> IO String
ltrim :: String -> String
rtrim :: String -> String
trim :: String -> String
unBracket :: String -> String

-- | Removes the whitespace surrounding a string as well as the first and
--   last character. <tt>unBracket <a> (asdf) </a> = <a>asdf</a></tt>
--   
--   Drops the whitespace at the start of the string
--   
--   Drops the whitespace at the end of the string
--   
--   Trims the beginning and ending whitespace of a string
--   
--   Repeadly splits a list by the provided separator and collects the
--   results
splitList :: (Eq a) => a -> [a] -> [[a]]

-- | Repeatedly splits a list and collects the results
splitListBy :: (a -> Bool) -> [a] -> [[a]]

-- | Split is like break, but the matching element is dropped.
split :: (a -> Bool) -> [a] -> ([a], [a])

-- | Read file with a default value if the file does not exist.
mbReadFile :: a -> (String -> a) -> FilePath -> IO a
mapFst :: (a -> b) -> [(a, x)] -> [(b, x)]
mapSnd :: (a -> b) -> [(x, a)] -> [(x, b)]

-- | applies the list of functions to the provided argument
revmap :: a -> [a -> b] -> [b]

-- | <tt>comp f a b</tt> compares <tt>a</tt> and <tt>b</tt> after apply
--   <tt>f</tt>.
comp :: (Ord t) => (a -> t) -> a -> a -> Ordering

-- | Run an external command. Upon failure print status to stderr.
runCommand :: String -> [String] -> IO ()

-- | Unsafe tracing, outputs the message and the value to stderr.
debug :: (Show a) => String -> a -> a

-- | Unsafe tracing messages inside a monad.
debugM :: (Monad m) => String -> m ()

-- | Read in any monad.
readM :: (Monad m, Read t) => String -> m t

-- | Convert Maybe into an another monad. This is a simple injection that
--   calls fail when given a Nothing.
maybeM :: (Monad m) => Maybe a -> m a

-- | Lifts a bool into a MonadPlus, with False mapped to the mzero.
boolM :: (MonadPlus m) => Bool -> m Bool

-- | <tt>notMb a b</tt> returns <tt>Just a</tt> if <tt>b</tt> is
--   <tt>Nothing</tt> and <tt>Nothing</tt> if <tt>b</tt> is <tt>Just
--   _</tt>.
notMb :: a -> Maybe a -> Maybe a

-- | Takes a list of delays, in seconds, and an action to execute
--   repeatedly. The action is then executed repeatedly in a separate
--   thread until the list has been consumed. The first action takes place
--   immediately.
periodic :: [Int] -> IO () -> IO ThreadId
(.^) :: Int -> Int -> Int

-- | Similar to <a>periodic</a> but runs in the same thread
periodic' :: [Int] -> IO a -> IO a


-- | Compatiblity for ByteStrings
module Happstack.Util.ByteStringCompat

-- | Semantically equivalent to break on strings
breakChar :: Char -> ByteString -> (ByteString, ByteString)

-- | <a>breakCharEnd</a> behaves like breakChar, but from the end of the
--   ByteString.
--   
--   <pre>
--   breakCharEnd ('b') (pack "aabbcc") == ("aab","cc")
--   </pre>
--   
--   and the following are equivalent:
--   
--   <pre>
--   breakCharEnd 'c' "abcdef"
--   let (x,y) = break (=='c') (reverse "abcdef")
--   in (reverse (drop 1 y), reverse x)
--   </pre>
breakCharEnd :: Char -> ByteString -> (ByteString, ByteString)

-- | Drops leading spaces in the ByteString
dropSpace :: ByteString -> ByteString

-- | Drops trailing spaces in the ByteString
dropSpaceEnd :: ByteString -> ByteString

-- | Chunk a lazy bytestring into reasonable chunks - is id from outside.
--   This is useful to make bytestring chunks reasonable sized for e.g.
--   compression.
rechunkLazy :: ByteString -> ByteString


module Happstack.Util.AutoBuild

-- | Functionality for the autoBuild tool. Inspired by searchpath.
autoBuild :: String -> String -> [String] -> IO ()

module Happstack.Crypto.MD5

-- | Will read the lazy ByteString and return the md5 digest. Some
--   application might want to wrap this function for type safty.
md5 :: ByteString -> ByteString
md5InitialContext :: MD5Context
md5Update :: MD5Context -> ByteString -> MD5Context
md5Finalize :: MD5Context -> ByteString
data MD5Context
md5File :: String -> IO ()
stringMD5 :: ByteString -> String
applyMD5Rounds :: MD5Partial -> ByteString -> MD5Partial
test :: IO ()

module Happstack.Crypto.SHA1
sha1 :: String -> String
sha1Raw :: String -> String
sha1_size :: (Integral a) => a -> String -> String

module Happstack.Util.Daemonize
daemonize :: FilePath -> IO a -> IO a
getDaemonizedId :: IO String

module Happstack.Crypto.DES
des_enc :: Message -> Key -> Enc
des_dec :: Message -> Key -> Enc
type Message = Zord64
type Enc = Zord64
instance Eq Zord64
instance Ord Zord64
instance Bounded Zord64
instance Bits [Bool]
instance Num [Bool]
instance Enum Zord64
instance Real Zord64
instance Integral Zord64
instance Bits Zord64
instance Num Zord64
instance Read Zord64
instance Show Zord64

module Happstack.Crypto.W64
pad :: String -> String
unpad :: (Enum a) => [a] -> [a]
prop_PadUnPad :: String -> Bool
is4Char :: [a] -> Bool
quadCharToW64 :: (Num b, Enum a) => [a] -> b
w64ToQuadChar :: (Integral a, Enum b) => a -> [b]
w64ToQuadNum :: (Integral a) => a -> [a]
toQuadChars :: [a] -> [[a]]
stringToW64s :: (Num a) => String -> [a]
w64sToString :: (Enum b) => [Integer] -> [b]
prop_stringW64 :: String -> Bool
hexToW64 :: (Num a) => String -> a
stringToKey :: (Num a) => String -> a
des_encrypt :: String -> String -> [Enc]
des_decrypt :: (Enum a) => String -> [Message] -> [a]
prop_DES :: String -> String -> Bool

module Happstack.Crypto.Base64
encode :: String -> String
decode :: String -> String

-- | Cut up a string into 72 char lines, each line terminated by CRLF.
chop72 :: String -> String

module Happstack.Crypto.HMAC
hmacSHA1 :: String -> String -> String