libghc-missingh-doc 1.3.0.1-5build1 / usr / share / doc / libghc-missingh-doc / html / MissingH.txt

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


-- | Large utility library
--   
--   MissingH is a library of all sorts of utility functions for Haskell
--   programmers. It is written in pure Haskell and thus should be
--   extremely portable and easy to use.
@package MissingH
@version 1.3.0.1


-- | Written by John Goerzen, jgoerzen@complete.org
--   
--   Utilities for command-line parsing, including wrappers around the
--   standard System.Console.GetOpt module.
module System.Console.GetOpt.Utils

-- | Simple command line parser -- a basic wrapper around the system's
--   default getOpt. See the System.Console.GetOpt manual for a description
--   of the first two parameters.
--   
--   The third parameter is a usage information header.
--   
--   The return value consists of the list of parsed flags and a list of
--   non-option arguments.
parseCmdLine :: ArgOrder a -> [OptDescr a] -> String -> IO ([a], [String])

-- | Similar to <a>parseCmdLine</a>, but takes an additional function that
--   validates the post-parse command-line arguments. This is useful, for
--   example, in situations where there are two arguments that are
--   mutually-exclusive and only one may legitimately be given at a time.
--   
--   The return value of the function indicates whether or not it detected
--   an error condition. If it returns Nothing, there is no error. If it
--   returns Just String, there was an error, described by the String.
validateCmdLine :: ArgOrder a -> [OptDescr a] -> String -> (([a], [String]) -> Maybe String) -> IO ([a], [String])

-- | A type to standardize some common uses of GetOpt.
--   
--   The first component of the tuple is the long name of the option.
--   
--   The second component is empty if there is no arg, or has the arg
--   otherwise.
type StdOption = (String, String)

-- | Handle a required argument.
stdRequired :: String -> String -> StdOption

-- | Handle an optional argument.
stdOptional :: String -> Maybe String -> StdOption


-- | This module provides various helpful utilities for dealing with Debian
--   files and programs.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module System.Debian

-- | The type representing the contents of a Debian control file, or any
--   control-like file (such as the output from apt-cache show, etc.)
type ControlFile = [(String, String)]

-- | The type representing a Debian version number. This type is an
--   instance of <a>Ord</a>, but you can also use <a>compareDebVersion</a>
--   if you prefer.
data DebVersion

-- | Compare the versions of two packages.
compareDebVersion :: String -> String -> IO Ordering
checkDebVersion :: String -> String -> String -> IO Bool
instance GHC.Classes.Eq System.Debian.DebVersion
instance GHC.Classes.Ord System.Debian.DebVersion


-- | Provides some types and related items on Windows to be compatible with
--   the System.Posix.* libraries
--   
--   See also <a>System.IO.StatCompat</a>, which this module re-exports.
--   
--   On non-Windows platforms, this module does nothing.
--   
--   On Windows, it re-exports <a>System.IO.StatCompat</a>. It also
--   provides various file type information modes that are otherwise in
--   <a>System.Posix.Types</a> or <a>System.Posix.Files</a>. It also
--   provides a rudimentary implemention of getFileStatus that emulates the
--   Posix call to stat(2).
--   
--   Common usage might be like this:
--   
--   <pre>
--   import System.Posix.Types
--   #if (defined(mingw32_HOST_OS) || defined(mingw32_TARGET_OS) || defined(__MINGW32__))
--   import System.IO.WindowsCompat
--   #else
--   import System.Posix.Files
--   #endif
--   </pre>
--   
--   Or, to avoid having to use CPP and make things even easier, just
--   import <a>System.IO.PlafCompat</a>, which essentially does the above.
module System.IO.WindowsCompat


-- | Exports some POSIX constants and functions that are not exported in
--   fptools by default.
module System.Posix.Consts
blockSpecialMode :: FileMode
characterSpecialMode :: FileMode
namedPipeMode :: FileMode
regularFileMode :: FileMode
directoryMode :: FileMode
fileTypeModes :: FileMode
socketMode :: FileMode
symbolicLinkMode :: FileMode


-- | Provide a stat-like structure for use in MissingH. Especially useful
--   with HVFS and on Windows. See also <a>System.IO.WindowsCompat</a>.
module System.IO.StatCompat
data FileStatusCompat
FileStatusCompat :: DeviceID -> FileID -> FileMode -> LinkCount -> UserID -> GroupID -> DeviceID -> FileOffset -> EpochTime -> EpochTime -> EpochTime -> FileStatusCompat
[deviceID] :: FileStatusCompat -> DeviceID
[fileID] :: FileStatusCompat -> FileID
[fileMode] :: FileStatusCompat -> FileMode
[linkCount] :: FileStatusCompat -> LinkCount
[fileOwner] :: FileStatusCompat -> UserID
[fileGroup] :: FileStatusCompat -> GroupID
[specialDeviceID] :: FileStatusCompat -> DeviceID
[fileSize] :: FileStatusCompat -> FileOffset
[accessTime] :: FileStatusCompat -> EpochTime
[modificationTime] :: FileStatusCompat -> EpochTime
[statusChangeTime] :: FileStatusCompat -> EpochTime
sc_helper :: FileMode -> FileStatusCompat -> Bool
isBlockDevice :: FileStatusCompat -> Bool
isCharacterDevice :: FileStatusCompat -> Bool
isNamedPipe :: FileStatusCompat -> Bool
isRegularFile :: FileStatusCompat -> Bool
isDirectory :: FileStatusCompat -> Bool
isSymbolicLink :: FileStatusCompat -> Bool
isSocket :: FileStatusCompat -> Bool


-- | On Unix, exports System.Posix.Types and System.Posix.Files.
--   
--   On Windows, exports System.Posix.Types and
--   <a>System.IO.WindowsCompat</a>.
--   
--   The result should be roughly the same set of defined variables and
--   types.
module System.IO.PlafCompat

-- | The name of the null device. NUL: on Windows, /dev/null everywhere
--   else.
nullFileName :: String


-- | Maintainer : <a>igloo@earth.li</a> Stability : provisional
--   Portability: portable
--   
--   Inflate algorithm implementation
--   
--   Copyright (C) 2004 Ian Lynagh
module Data.Compression.Inflate
inflate_string :: String -> String

-- | Returns (Data, Remainder)
inflate_string_remainder :: String -> (String, String)
inflate :: [Int] -> (Output, [Bit])
type Output = [Word32]
data Bit
bits_to_word32 :: [Bit] -> Word32
instance GHC.Classes.Eq Data.Compression.Inflate.Bit
instance GHC.Show.Show Data.Compression.Inflate.Bit
instance GHC.Base.Monad Data.Compression.Inflate.InfM
instance GHC.Base.Applicative Data.Compression.Inflate.InfM
instance GHC.Base.Functor Data.Compression.Inflate.InfM

module Data.Hash.MD5.Zord64_HARD
data Zord64
instance GHC.Enum.Bounded Data.Hash.MD5.Zord64_HARD.Zord64
instance GHC.Classes.Ord Data.Hash.MD5.Zord64_HARD.Zord64
instance GHC.Classes.Eq Data.Hash.MD5.Zord64_HARD.Zord64
instance GHC.Show.Show Data.Hash.MD5.Zord64_HARD.Zord64
instance GHC.Read.Read Data.Hash.MD5.Zord64_HARD.Zord64
instance GHC.Num.Num Data.Hash.MD5.Zord64_HARD.Zord64
instance Data.Bits.Bits Data.Hash.MD5.Zord64_HARD.Zord64
instance GHC.Real.Integral Data.Hash.MD5.Zord64_HARD.Zord64
instance GHC.Real.Real Data.Hash.MD5.Zord64_HARD.Zord64
instance GHC.Enum.Enum Data.Hash.MD5.Zord64_HARD.Zord64


-- | Generation of MD5sums
--   
--   Written by Ian Lynagh, igloo@earth.li
module Data.Hash.MD5

-- | The simplest function, gives you the MD5 of a string as 4-tuple of
--   32bit words.
md5 :: (MD5 a) => a -> ABCD

-- | Returns a hex number ala the md5sum program.
md5s :: (MD5 a) => a -> String

-- | Returns an integer equivalent to hex number from <a>md5s</a>.
md5i :: (MD5 a) => a -> Integer

-- | Anything we want to work out the MD5 of must be an instance of class
--   MD5
class MD5 a
get_next :: MD5 a => a -> ([Word32], Int, a)
len_pad :: MD5 a => Zord64 -> a -> a
finished :: MD5 a => a -> Bool
newtype ABCD
ABCD :: (Word32, Word32, Word32, Word32) -> ABCD
type Zord64 = Word64
newtype Str
Str :: String -> Str
newtype BoolList
BoolList :: [Bool] -> BoolList
newtype WordList
WordList :: ([Word32], Zord64) -> WordList
instance GHC.Show.Show Data.Hash.MD5.ABCD
instance GHC.Classes.Eq Data.Hash.MD5.ABCD
instance Data.Hash.MD5.MD5 Data.Hash.MD5.BoolList
instance Data.Hash.MD5.MD5 Data.Hash.MD5.Str
instance Data.Hash.MD5.MD5 Data.Hash.MD5.WordList
instance GHC.Num.Num Data.Hash.MD5.ABCD


-- | CRC32 checksumming using the GZIP/PKZIP algorithm as used in both ISO
--   3309 and section 8.1.1.6.2 of ITU-T V.42 and referenced in RFC1952.
module Data.Hash.CRC32.GZip
update_crc :: Word32 -> Char -> Word32
update_crc_list :: Word32 -> [Char] -> Word32
calc_crc32 :: [Char] -> Word32
gzipcrctab :: Array Int Word32


-- | CRC32 checksumming using POSIX 1003.2-1992 algorithm for the
--   polynomial { 32 26 23 22 16 12 11 10 8 7 5 4 2 1 }, also defined in
--   ISO 8802-3: 1989.
--   
--   Copyright (c) 2002 HardCore SoftWare, Doug Hoyte
module Data.Hash.CRC32.Posix
iter_crc32 :: Word32 -> Char -> Word32
calc_crc32 :: [Char] -> Word32 -> Word32 -> Word32
crc32 :: [Char] -> Word32
crctab :: Array Int Word32


-- | Bit-related utilities
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Data.Bits.Utils

-- | Returns a list representing the bytes that comprise a data type.
--   
--   Example:
--   
--   <pre>
--   getBytes (0x12345678::Int) -&gt; [0x12, 0x34, 0x56, 0x78]
--   </pre>
getBytes :: (Integral a, Bounded a, Bits a) => a -> [a]

-- | The opposite of <a>getBytes</a>, this function builds a number based
--   on its component bytes.
--   
--   Results are undefined if any components of the input list are &gt;
--   0xff!
fromBytes :: (Bits a, Num a) => [a] -> a

-- | Converts a Char to a Word8.
c2w8 :: Char -> Word8

-- | Converts a String to a [Word8].
s2w8 :: String -> [Word8]

-- | Converts a Word8 to a Char.
w82c :: Word8 -> Char

-- | Converts a [Word8] to a String.
w82s :: [Word8] -> String


-- | GZip file decompression
--   
--   Copyright (c) 2004 John Goerzen, jgoerzen@complete.org
--   
--   The GZip format is described in RFC1952.
module System.FileArchive.GZip

-- | The data structure representing the GZip header. This occurs at the
--   beginning of each <a>Section</a> on disk.
data Header
Header :: Int -> Int -> Maybe String -> Maybe String -> Maybe String -> Word32 -> Int -> Int -> Header

-- | Compression method. Only 8 is defined at present.
[method] :: Header -> Int
[flags] :: Header -> Int
[extra] :: Header -> Maybe String
[filename] :: Header -> Maybe String
[comment] :: Header -> Maybe String

-- | Modification time of the original file
[mtime] :: Header -> Word32

-- | Extra flags
[xfl] :: Header -> Int

-- | Creating operating system
[os] :: Header -> Int

-- | A section represents a compressed component in a GZip file. Every GZip
--   file has at least one.
type Section = (Header, String, Footer)
data GZipError

-- | CRC-32 check failed
CRCError :: GZipError

-- | Couldn't find a GZip header
NotGZIPFile :: GZipError

-- | Compressed with something other than method 8 (deflate)
UnknownMethod :: GZipError

-- | Other problem arose
UnknownError :: String -> GZipError

-- | Stored on-disk at the end of each section.
data Footer
Footer :: Word32 -> Word32 -> Bool -> Footer

-- | The size of the original, decompressed data
[size] :: Footer -> Word32

-- | The stored GZip CRC-32 of the original, decompressed data
[crc32] :: Footer -> Word32

-- | Whether or not the stored CRC-32 matches the calculated CRC-32 of the
--   data
[crc32valid] :: Footer -> Bool

-- | Read a GZip file, decompressing all sections that are found.
--   
--   Returns a decompresed data stream and Nothing, or an unreliable string
--   and Just (error). If you get anything other than Nothing, the String
--   returned should be discarded.
decompress :: String -> (String, Maybe GZipError)

-- | Read a GZip file, decompressing all sections found.
--   
--   Writes the decompressed data stream to the given output handle.
--   
--   Returns Nothing if the action was successful, or Just GZipError if
--   there was a problem. If there was a problem, the data written to the
--   output handle should be discarded.
hDecompress :: Handle -> Handle -> IO (Maybe GZipError)

-- | Read all sections.
read_sections :: String -> Either GZipError [Section]

-- | Read the GZip header. Return (Header, Remainder).
read_header :: String -> Either GZipError (Header, String)

-- | Read one section, returning (ThisSection, Remainder)
read_section :: String -> Either GZipError (Section, String)
instance GHC.Show.Show System.FileArchive.GZip.Header
instance GHC.Classes.Eq System.FileArchive.GZip.Header
instance GHC.Show.Show System.FileArchive.GZip.GZipError
instance GHC.Classes.Eq System.FileArchive.GZip.GZipError
instance Control.Monad.Trans.Error.Error System.FileArchive.GZip.GZipError


-- | This module provides various helpful utilities for dealing with lists.
--   
--   Written by Neil Mitchell, <a>http://www.cs.york.ac.uk/~ndm/</a>
module Data.Tuple.Utils

-- | Take the first item out of a 3 element tuple
fst3 :: (a, b, c) -> a

-- | Take the second item out of a 3 element tuple
snd3 :: (a, b, c) -> b

-- | Take the third item out of a 3 element tuple
thd3 :: (a, b, c) -> c


-- | Utilities for working with the Either data type
module Data.Maybe.Utils

-- | Pulls a Just value out of a Maybe value. If the Maybe value is
--   Nothing, raises an exception with error.
forceMaybe :: Maybe a -> a

-- | Like <a>forceMaybe</a>, but lets you customize the error message
--   raised if Nothing is supplied.
forceMaybeMsg :: String -> Maybe a -> a


-- | Utilities for working with the Either data type
module Data.Either.Utils

-- | Converts a Maybe value to an Either value, using the supplied
--   parameter as the Left value if the Maybe is Nothing.
--   
--   This function can be interpreted as:
--   
--   <pre>
--   maybeToEither :: e -&gt; Maybe a -&gt; Either e a
--   </pre>
--   
--   Its definition is given as it is so that it can be used in the Error
--   and related monads.
maybeToEither :: MonadError e m => e -> Maybe a -> m a

-- | Pulls a <a>Right</a> value out of an Either value. If the Either value
--   is Left, raises an exception with "error".
forceEither :: Show e => Either e a -> a

-- | Like <a>forceEither</a>, but can raise a specific message with the
--   error.
forceEitherMsg :: Show e => String -> Either e a -> a

-- | Takes an either and transforms it into something of the more generic
--   MonadError class.
eitherToMonadError :: MonadError e m => Either e a -> m a

-- | Take a Left to a value, crashes on a Right
fromLeft :: Either a b -> a

-- | Take a Right to a value, crashes on a Left
fromRight :: Either a b -> b

-- | Take an Either, and return the value inside it
fromEither :: Either a a -> a


-- | This module provides various helpful utilities for dealing with
--   networking
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Network.Utils

-- | Sets up the system for networking. Similar to the built-in
--   withSocketsDo (and actually, calls it), but also sets the SIGPIPE
--   handler so that signal is ignored.
--   
--   Example:
--   
--   <pre>
--   main = niceSocketsDo $ do { ... }
--   </pre>
niceSocketsDo :: IO a -> IO a
connectTCP :: HostName -> PortNumber -> IO Socket
connectTCPAddr :: SockAddr -> IO Socket
listenTCPAddr :: SockAddr -> Int -> IO Socket
showSockAddr :: SockAddr -> IO String


-- | This module provides an infrastructure to simplify server design.
--   
--   Written by John Goerzen, jgoerzen@complete.org
--   
--   Please note: this module is designed to work with TCP, UDP, and Unix
--   domain sockets, but only TCP sockets have been tested to date.
--   
--   This module is presently under-documented. For an example of usage,
--   please see the description of <a>Network.FTP.Server</a>.
module Network.SocketServer

-- | Options for your server.
data InetServerOptions
InetServerOptions :: Int -> PortNumber -> HostAddress -> Bool -> Family -> SocketType -> String -> InetServerOptions
[listenQueueSize] :: InetServerOptions -> Int
[portNumber] :: InetServerOptions -> PortNumber
[interface] :: InetServerOptions -> HostAddress
[reuse] :: InetServerOptions -> Bool
[family] :: InetServerOptions -> Family
[sockType] :: InetServerOptions -> SocketType
[protoStr] :: InetServerOptions -> String

-- | Get Default options. You can always modify it later.
simpleTCPOptions :: Int -> InetServerOptions
data SocketServer
SocketServer :: InetServerOptions -> Socket -> SocketServer
[optionsSS] :: SocketServer -> InetServerOptions
[sockSS] :: SocketServer -> Socket

-- | The main handler type.
--   
--   The first parameter is the socket itself.
--   
--   The second is the address of the remote endpoint.
--   
--   The third is the address of the local endpoint.
type HandlerT = Socket -> SockAddr -> SockAddr -> IO ()

-- | Convenience function to completely set up a TCP <a>SocketServer</a>
--   and handle all incoming requests.
--   
--   This function is literally this:
--   
--   <pre>
--   serveTCPforever options func =
--       do sockserv &lt;- setupSocketServer options
--          serveForever sockserv func
--   </pre>
serveTCPforever :: InetServerOptions -> HandlerT -> IO ()

-- | Takes some options and sets up the <a>SocketServer</a>. I will bind
--   and begin listening, but will not accept any connections itself.
setupSocketServer :: InetServerOptions -> IO SocketServer

-- | Handle one incoming request from the given <a>SocketServer</a>.
handleOne :: SocketServer -> HandlerT -> IO ()

-- | Handle all incoming requests from the given <a>SocketServer</a>.
serveForever :: SocketServer -> HandlerT -> IO ()

-- | Close the socket server. Does not terminate active handlers, if any.
closeSocketServer :: SocketServer -> IO ()

-- | Log each incoming connection using the interface in
--   <a>System.Log.Logger</a>.
--   
--   Log when the incoming connection disconnects.
--   
--   Also, log any failures that may occur in the child handler.
loggingHandler :: String -> Priority -> HandlerT -> HandlerT

-- | Handle each incoming connection in its own thread to make the server
--   multi-tasking.
threadedHandler :: HandlerT -> HandlerT

-- | Give your handler function a Handle instead of a Socket.
--   
--   The Handle will be opened with ReadWriteMode (you use one handle for
--   both directions of the Socket). Also, it will be initialized with
--   LineBuffering.
--   
--   Unlike other handlers, the handle will be closed when the function
--   returns. Therefore, if you are doing threading, you should to it
--   before you call this handler.
handleHandler :: (Handle -> SockAddr -> SockAddr -> IO ()) -> HandlerT
instance GHC.Show.Show Network.SocketServer.SocketServer
instance GHC.Classes.Eq Network.SocketServer.SocketServer
instance GHC.Show.Show Network.SocketServer.InetServerOptions
instance GHC.Classes.Eq Network.SocketServer.InetServerOptions


-- | Utility for parsing dates.
module System.Time.ParseDate

-- | Parse a date string as formatted by <a>formatCalendarTime</a>.
--   
--   The resulting <a>CalendarTime</a> will only have those fields set that
--   are represented by a format specifier in the format string, and those
--   fields will be set to the values given in the date string. If the same
--   field is specified multiple times, the rightmost occurence takes
--   precedence.
--   
--   The resulting date is not neccessarily a valid date. For example, if
--   there is no day of the week specifier in the format string, the value
--   of <a>ctWDay</a> will most likely be invalid.
--   
--   Format specifiers are % followed by some character. All other
--   characters are treated literally. Whitespace in the format string
--   matches zero or more arbitrary whitespace characters.
--   
--   Format specifiers marked with * are matched, but do not set any field
--   in the output.
--   
--   Some of the format specifiers are marked as space-padded or
--   zero-padded. Regardless of this, space-padded, zero-padded or unpadded
--   inputs are accepted. Note that strings using unpadded fields without
--   separating the fields may cause strange parsing.
--   
--   Supported format specfiers:
--   
--   <ul>
--   <li><i>%%</i> a % character.</li>
--   <li><i>%a</i> locale's abbreviated weekday name (Sun ... Sat)</li>
--   <li><i>%A</i> locale's full weekday name (Sunday .. Saturday)</li>
--   <li><i>%b</i> locale's abbreviated month name (Jan..Dec)</li>
--   <li><i>%B</i> locale's full month name (January..December)</li>
--   <li><i>%c</i> locale's date and time format (Thu Mar 25 17:47:03 CET
--   2004)</li>
--   <li><i>%C</i> century [00-99]</li>
--   <li><i>%d</i> day of month, zero padded (01..31)</li>
--   <li><i>%D</i> date (%m/%d/%y)</li>
--   <li><i>%e</i> day of month, space padded ( 1..31)</li>
--   <li><i>%h</i> same as %b</li>
--   <li><i>%H</i> hour, 24-hour clock, zero padded (00..23)</li>
--   <li><i>%I</i> hour, 12-hour clock, zero padded (01..12)</li>
--   <li><i>%j</i> day of the year, zero padded (001..366)</li>
--   <li><i>%k</i> hour, 24-hour clock, space padded ( 0..23)</li>
--   <li><i>%l</i> hour, 12-hour clock, space padded ( 1..12)</li>
--   <li><i>%m</i> month, zero padded (01..12)</li>
--   <li><i>%M</i> minute, zero padded (00..59)</li>
--   <li><i>%n</i> a newline character</li>
--   <li><i>%p</i> locale's AM or PM indicator</li>
--   <li><i>%r</i> locale's 12-hour time format (hh:mm:ss AM/PM)</li>
--   <li><i>%R</i> hours and minutes, 24-hour clock (hh:mm)</li>
--   <li><i>%s</i> * seconds since '00:00:00 1970-01-01 UTC'</li>
--   <li><i>%S</i> seconds, zero padded (00..59)</li>
--   <li><i>%t</i> a horizontal tab character</li>
--   <li><i>%T</i> time, 24-hour clock (hh:mm:ss)</li>
--   <li><i>%u</i> numeric day of the week (1=Monday, 7=Sunday)</li>
--   <li><i>%U</i> * week number, weeks starting on Sunday, zero padded
--   (01-53)</li>
--   <li><i>%V</i> * week number (as per ISO-8601), week 1 is the first
--   week with a Thursday, zero padded, (01-53)</li>
--   <li><i>%w</i> numeric day of the week, (0=Sunday, 6=Monday)</li>
--   <li><i>%W</i> * week number, weeks starting on Monday, zero padded
--   (01-53)</li>
--   <li><i>%x</i> locale's preferred way of printing dates (%m/%d/%y)</li>
--   <li><i>%X</i> locale's preferred way of printing time. (%H:%M:%S)</li>
--   <li><i>%y</i> year, within century, zero padded (00..99)</li>
--   <li><i>%Y</i> year, including century. Not padded (this is probably a
--   bug, but formatCalendarTime does it this way). (0-9999)</li>
--   <li><i>%Z</i> time zone abbreviation (e.g. CET) or RFC-822 style
--   numeric timezone (-0500)</li>
--   </ul>
parseCalendarTime :: TimeLocale -> String -> String -> Maybe CalendarTime


-- | Low-level path name manipulations.
--   
--   Written by Volker Wysk
module System.Path.NameManip

-- | Split a path in components. Repeated "<tt>/</tt>" characters don't
--   lead to empty components. "<tt>.</tt>" path components are removed. If
--   the path is absolute, the first component will start with
--   "<tt>/</tt>". "<tt>..</tt>" components are left intact. They can't be
--   simply removed, because the preceding component might be a symlink. In
--   this case, <tt>realpath</tt> is probably what you need.
--   
--   The case that the path is empty, is probably an error. However, it is
--   treated like "<tt>.</tt>", yielding an empty path components list.
--   
--   Examples:
--   
--   <pre>
--   slice_path "/"        = ["/"]
--   slice_path "/foo/bar" = ["/foo","bar"]
--   slice_path "..//./"   = [".."]
--   slice_path "."        = []
--   </pre>
--   
--   See <a>unslice_path</a>, <tt>realpath</tt>, <tt>realpath_s</tt>.
slice_path :: String -> [String]

-- | Form a path from path components. This isn't the inverse of
--   <a>slice_path</a>, since <tt><a>unslice_path</a> .
--   <a>slice_path</a></tt> normalises the path.
--   
--   See <a>slice_path</a>.
unslice_path :: [String] -> String

-- | Normalise a path. This is done by reducing repeated <tt>/</tt>
--   characters to one, and removing <tt>.</tt> path components.
--   <tt>..</tt> path components are left intact, because of possible
--   symlinks.
--   
--   <pre>
--   <a>normalise_path</a> = <a>unslice_path</a> . <a>slice_path</a>
--   </pre>
normalise_path :: String -> String

-- | Split a file name in components. This are the base file name and the
--   suffixes, which are separated by dots. If the name starts with a dot,
--   it is regarded as part of the base name. The result is a list of file
--   name components. The filename may be a path. In this case, everything
--   up to the last path component will be returned as part of the base
--   file name. The path gets normalised thereby.
--   
--   No empty suffixes are returned. If the file name contains several
--   consecutive dots, they are regared as part of the preceding file name
--   component.
--   
--   Concateneting the name components and adding dots, reproduces the
--   original name, with a normalised path: <tt>concat . intersperse "." .
--   <a>slice_filename</a> == <tt>normalise</tt></tt>.
--   
--   Note that the last path component might be "<tt>..</tt>". Then it is
--   not possible to deduce the refered directory's name from the path. An
--   IO action for getting the real path is then necessary.
--   
--   Examples:
--   
--   <pre>
--   <a>slice_filename</a> "a.b//./.foo.tar.gz" == ["a.b/.foo","tar","gz"]
--   <a>slice_filename</a> ".x..y."             == [".x.", "y."]
--   </pre>
--   
--   See <a>unslice_filename</a>, <tt>slice_filename'</tt>.
slice_filename :: String -> [String]

-- | This is a variant of <a>slice_filename</a>. It is like
--   <a>slice_filename</a>, except for being more efficient, and the
--   filename must not contain any preceding path, since this case isn't
--   considered.
--   
--   See <a>slice_filename</a>, <a>unslice_filename</a>.
slice_filename' :: String -> [String]

-- | Form file name from file name components, interspersing dots. This is
--   the inverse of <a>slice_filename</a>, except for normalisation of any
--   path.
--   
--   <pre>
--   unslice_filename = concat . intersperse "."
--   </pre>
--   
--   See <a>slice_filename</a>.
unslice_filename :: [String] -> String

-- | Split a path in directory and file name. Only in the case that the
--   supplied path is empty, both parts are empty strings. Otherwise,
--   <tt>"."</tt> is filled in for the corresponding part, if necessary.
--   Unless the path is empty, concatenating the returned path and file
--   name components with a slash in between, makes a valid path to the
--   file.
--   
--   <tt>split_path</tt> splits off the last path component. This isn't the
--   same as the text after the last <tt>/</tt>.
--   
--   Note that the last path component might be <tt>".."</tt>. Then it is
--   not possible to deduce the refered directory's name from the path.
--   Then an IO action for getting the real path is necessary.
--   
--   Examples:
--   
--   <pre>
--   split_path "/a/b/c"      == ("/a/b", "c")
--   split_path "foo"         == (".", "foo")
--   split_path "foo/bar"     == ("foo", "bar")
--   split_path "foo/.."      == ("foo", "..")
--   split_path "."           == (".", ".")
--   split_path ""            == ("", "")
--   split_path "/foo"        == ("/", "foo")
--   split_path "foo/"        == (".", "foo")
--   split_path "foo/."       == (".", "foo")
--   split_path "foo///./bar" == ("foo", "bar")
--   </pre>
--   
--   See <a>slice_path</a>.
split_path :: String -> (String, String)

-- | Get the directory part of a path.
--   
--   <pre>
--   dir_part = fst . split_path
--   </pre>
--   
--   See <a>split_path</a>.
dir_part :: String -> String

-- | Get the last path component of a path.
--   
--   <pre>
--   filename_part = snd . split_path
--   </pre>
--   
--   Examples:
--   
--   <pre>
--   filename_part "foo/bar" == "bar"
--   filename_part "."       == "."
--   </pre>
--   
--   See <a>split_path</a>.
filename_part :: String -> String

-- | Inverse of <a>split_path</a>, except for normalisation.
--   
--   This concatenates two paths, and takes care of <tt>"."</tt> and empty
--   paths. When the two components are the result of <tt>split_path</tt>,
--   then <tt>unsplit_path</tt> creates a normalised path. It is best
--   documented by its definition:
--   
--   <pre>
--   unsplit_path (".", "") = "."
--   unsplit_path ("", ".") = "."
--   unsplit_path (".", q)  = q
--   unsplit_path ("", q)   = q
--   unsplit_path (p, "")   = p
--   unsplit_path (p, ".")  = p
--   unsplit_path (p, q)    = p ++ "/" ++ q
--   </pre>
--   
--   Examples:
--   
--   <pre>
--   unsplit_path ("", "")     == ""
--   unsplit_path (".", "")    == "."
--   unsplit_path (".", ".")   == "."
--   unsplit_path ("foo", ".") == "foo"
--   </pre>
--   
--   See <a>split_path</a>.
unsplit_path :: (String, String) -> String

-- | Split a file name in prefix and suffix. If there isn't any suffix in
--   the file name, then return an empty suffix. A dot at the beginning or
--   at the end is not regarded as introducing a suffix.
--   
--   The last path component is what is being split. This isn't the same as
--   splitting the string at the last dot. For instance, if the file name
--   doesn't contain any dot, dots in previous path component's aren't
--   mistaken as introducing suffixes.
--   
--   The path part is returned in normalised form. This means, <tt>"."</tt>
--   components are removed, and multiple "<tt>/</tt>"s are reduced to one.
--   
--   Note that there isn't any plausibility check performed on the suffix.
--   If the file name doesn't have a suffix, but happens to contain a dot,
--   then this dot is mistaken as introducing a suffix.
--   
--   Examples:
--   
--   <pre>
--   split_filename "path/to/foo.bar"                             = ("path/to/foo","bar")
--   split_filename "path/to/foo"                                 = ("path/to/foo","")
--   split_filename "/path.to/foo"                                = ("/path.to/foo","")
--   split_filename "a///./x"                                     = ("a/x","")
--   split_filename "dir.suffix/./"                               = ("dir","suffix")
--   split_filename "Photographie, Das 20. Jahrhundert (300 dpi)" = ("Photographie, Das 20", " Jahrhundert (300 dpi)")
--   </pre>
--   
--   See <a>slice_path</a>, 'split_filename\''
split_filename :: String -> (String, String)

-- | Variant of <a>split_filename</a>. This is a more efficient version of
--   <a>split_filename</a>, for the case that you know the string is is a
--   pure file name without any slashes.
--   
--   See <a>split_filename</a>.
split_filename' :: String -> (String, String)

-- | Inverse of <a>split_filename</a>. Concatenate prefix and suffix,
--   adding a dot in between, iff the suffix is not empty. The path part of
--   the prefix is normalised.
--   
--   See <a>split_filename</a>.
unsplit_filename :: (String, String) -> String

-- | Split a path in directory, base file name and suffix.
split3 :: String -> (String, String, String)

-- | Form path from directory, base file name and suffix parts.
unsplit3 :: (String, String, String) -> String

-- | Test a path for a specific suffix and split it off.
--   
--   If the path ends with the suffix, then the result is <tt>Just
--   prefix</tt>, where <tt>prefix</tt> is the normalised path without the
--   suffix. Otherwise it's <tt>Nothing</tt>.
test_suffix :: String -> String -> Maybe String

-- | Make a path absolute, using the current working directory.
--   
--   This makes a relative path absolute with respect to the current
--   working directory. An absolute path is returned unmodified.
--   
--   The current working directory is determined with
--   <tt>getCurrentDirectory</tt> which means that symbolic links in it are
--   expanded and the path is normalised. This is different from
--   <tt>pwd</tt>.
absolute_path :: String -> IO String

-- | Make a path absolute.
--   
--   This makes a relative path absolute with respect to a specified
--   directory. An absolute path is returned unmodified.
absolute_path_by :: String -> String -> String

-- | Make a path absolute.
--   
--   This makes a relative path absolute with respect to a specified
--   directory. An absolute path is returned unmodified.
--   
--   The order of the arguments can be confusing. You should rather use
--   <a>absolute_path_by</a>. <tt>absolute_path'</tt> is included for
--   backwards compatibility.
absolute_path' :: String -> String -> String

-- | Guess the <tt>".."</tt>-component free form of a path, specified as a
--   list of path components, by syntactically removing them, along with
--   the preceding path components. This will produce erroneous results
--   when the path contains symlinks. If the path contains leading
--   <tt>".."</tt> components, or more <tt>".."</tt> components than
--   preceeding normal components, then the <tt>".."</tt> components can't
--   be normalised away. In this case, the result is <tt>Nothing</tt>.
guess_dotdot_comps :: [String] -> Maybe [String]

-- | Guess the <tt>".."</tt>-component free, normalised form of a path. The
--   transformation is purely syntactic. <tt>".."</tt> path components will
--   be removed, along with their preceding path components. This will
--   produce erroneous results when the path contains symlinks. If the path
--   contains leading <tt>".."</tt> components, or more <tt>".."</tt>
--   components than preceeding normal components, then the <tt>".."</tt>
--   components can't be normalised away. In this case, the result is
--   <tt>Nothing</tt>.
--   
--   <pre>
--   guess_dotdot = fmap unslice_path . guess_dotdot_comps . slice_path
--   </pre>
guess_dotdot :: String -> Maybe String


-- | Tools for rendering sizes
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Data.Quantity

-- | Render a number into a string, based on the given quantities. This is
--   useful for displaying quantities in terms of bytes or in SI units.
--   Give this function the <a>SizeOpts</a> for the desired output, and a
--   precision (number of digits to the right of the decimal point), and
--   you get a string output.
--   
--   Here are some examples:
--   
--   <pre>
--   Data.Quantity&gt; renderNum binaryOpts 0 1048576
--   "1M"
--   Data.Quantity&gt; renderNum binaryOpts 2 10485760
--   "10.00M"
--   Data.Quantity&gt; renderNum binaryOpts 3 1048576
--   "1.000M"
--   Data.Quantity&gt; renderNum binaryOpts 3 1500000
--   "1.431M"
--   Data.Quantity&gt; renderNum binaryOpts 2 (1500 ** 3)
--   "3.14G"
--   </pre>
--   
--   <pre>
--   Data.Quantity&gt; renderNum siOpts 2 1024
--   "1.02k"
--   Data.Quantity&gt; renderNum siOpts 2 1048576
--   "1.05M"
--   Data.Quantity&gt; renderNum siOpts 2 0.001
--   "1.00m"
--   Data.Quantity&gt; renderNum siOpts 2 0.0001
--   "100.00u"
--   </pre>
--   
--   If you want more control over the output, see <a>quantifyNum</a>.
renderNum :: (Ord a, Real a) => SizeOpts -> Int -> a -> String

-- | Like <a>renderNum</a>, but operates on a list of numbers. The first
--   number in the list will be evaluated for the suffix. The same suffix
--   and scale will be used for the remaining items in the list. See
--   <a>renderNum</a> for more examples.
--   
--   Also, unlike <a>renderNum</a>, the %f instead of %g printf format is
--   used so that "scientific" notation is avoided in the output.
--   
--   Examples:
--   
--   <pre>
--   *Data.Quantity&gt; renderNums binaryOpts 3 [1500000, 10240, 104857600]
--   ["1.431M","0.010M","100.000M"]
--   *Data.Quantity&gt; renderNums binaryOpts 3 [1500, 10240, 104857600]
--   ["1.465K","10.000K","102400.000K"]
--   </pre>
renderNums :: (Ord a, Real a) => SizeOpts -> Int -> [a] -> [String]

-- | Parses a String, possibly generated by <a>renderNum</a>. Parses the
--   suffix and applies it to the number, which is read via the Read class.
--   
--   Returns Left "error message" on error, or Right number on successful
--   parse.
--   
--   If you want an Integral result, the convenience function
--   <a>parseNumInt</a> is for you.
parseNum :: (Read a, Fractional a) => SizeOpts -> Bool -> String -> Either String a

-- | Parse a number as with <a>parseNum</a>, but return the result as an
--   <a>Integral</a>. Any type such as Integer, Int, etc. can be used for
--   the result type.
--   
--   This function simply calls <a>round</a> on the result of
--   <a>parseNum</a>. A <a>Double</a> is used internally for the parsing of
--   the numeric component.
--   
--   By using this function, a user can still say something like 1.5M and
--   get an integral result.
parseNumInt :: (Read a, Integral a) => SizeOpts -> Bool -> String -> Either String a

-- | Takes a number and returns a new (quantity, suffix) combination. The
--   space character is used as the suffix for items around 0.
quantifyNum :: (Ord a, Real a, Floating b, Ord b) => SizeOpts -> a -> (b, Char)

-- | Like <a>quantifyNum</a>, but takes a list of numbers. The first number
--   in the list will be evaluated for the suffix. The same suffix and
--   scale will be used for the remaining items in the list. Please see
--   <a>renderNums</a> for an example of how this works.
--   
--   It is invalid to use this function on an empty list.
quantifyNums :: (Ord a, Real a, Floating b, Ord b) => SizeOpts -> [a] -> ([b], Char)

-- | The options for <a>quantifyNum</a> and <a>renderNum</a>
data SizeOpts
SizeOpts :: Int -> Int -> Int -> String -> SizeOpts

-- | The base from which calculations are made
[base] :: SizeOpts -> Int

-- | The increment to the power for each new suffix
[powerIncr] :: SizeOpts -> Int

-- | The first power for which suffixes are given
[firstPower] :: SizeOpts -> Int

-- | The suffixes themselves
[suffixes] :: SizeOpts -> String

-- | Predefined definitions for byte measurement in groups of 1024, from 0
--   to 2**80
binaryOpts :: SizeOpts

-- | Predefined definitions for SI measurement, from 10**-24 to 10**24.
siOpts :: SizeOpts


-- | This module provides various Haskell utilities for dealing with times
--   and dates.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module System.Time.Utils

-- | Converts the specified CalendarTime (see System.Time) to
--   seconds-since-epoch format.
--   
--   The input CalendarTime is assumed to be the time as given in your
--   local timezone. All timezone and DST fields in the object are ignored.
--   
--   This behavior is equivolent to the timelocal() and mktime() functions
--   that C programmers are accustomed to.
--   
--   Please note that the behavior for this function during the hour
--   immediately before or after a DST switchover may produce a result with
--   a different hour than you expect.
timelocal :: CalendarTime -> IO Integer

-- | Converts the specified CalendarTime (see System.Time) to
--   seconds-since-epoch time.
--   
--   This conversion does respect the timezone specified on the input
--   object. If you want a conversion from UTC, specify ctTZ = 0 and
--   ctIsDST = False.
--   
--   When called like that, the behavior is equivolent to the GNU C
--   function timegm(). Unlike the C library, Haskell's CalendarTime
--   supports timezone information, so if such information is specified, it
--   will impact the result.
timegm :: CalendarTime -> Integer

-- | Converts the given timeDiff to the number of seconds it represents.
--   
--   Uses the same algorithm as normalizeTimeDiff in GHC.
timeDiffToSecs :: TimeDiff -> Integer

-- | January 1, 1970, midnight, UTC, represented as a CalendarTime.
epoch :: CalendarTime

-- | Converts an Epoch time represented with an arbitrary Real to a
--   ClockTime. This input could be a CTime from Foreign.C.Types or an
--   EpochTime from System.Posix.Types.
epochToClockTime :: Real a => a -> ClockTime

-- | Converts a ClockTime to something represented with an arbitrary Real.
--   The result could be treated as a CTime from Foreign.C.Types or
--   EpochTime from System.Posix.Types. The inverse of
--   <a>epochToClockTime</a>.
--   
--   Fractions of a second are not preserved by this function.
clockTimeToEpoch :: Num a => ClockTime -> a

-- | Render a number of seconds as a human-readable amount. Shows the two
--   most significant places. For instance:
--   
--   <pre>
--   renderSecs 121 = "2m1s"
--   </pre>
--   
--   See also <a>renderTD</a> for a function that works on a TimeDiff.
renderSecs :: Integer -> String

-- | Like <a>renderSecs</a>, but takes a TimeDiff instead of an integer
--   second count.
renderTD :: TimeDiff -> String


-- | Tools for tracking the status of a long operation.
--   
--   Written by John Goerzen, jgoerzen@complete.org
--   
--   See also <a>Data.Progress.Meter</a>
module Data.Progress.Tracker

-- | Create a new <a>Progress</a> object with the given name and number of
--   total units initialized as given. The start time will be initialized
--   with the current time at the present moment according to the system
--   clock. The units completed will be set to 0, the time source will be
--   set to the system clock, and the parents and callbacks will be empty.
--   
--   If you need more control, see 'newProgress\''.
--   
--   Example:
--   
--   <pre>
--   prog &lt;- newProgress "mytracker" 1024
--   </pre>
newProgress :: String -> Integer -> IO Progress

-- | Create a new <a>Progress</a> object initialized with the given status
--   and callbacks. No adjustment to the <a>startTime</a> will be made. If
--   you want to use the system clock, you can initialize <a>startTime</a>
--   with the return value of <a>defaultTimeSource</a> and also pass
--   <a>defaultTimeSource</a> as the timing source.
newProgress' :: ProgressStatus -> [ProgressCallback] -> IO Progress

-- | Adds an new callback to an existing <a>Progress</a>. The callback will
--   be called whenever the object's status is updated, except by the call
--   to finishP.
--   
--   Please note that the Progress object will be locked while the callback
--   is running, so the callback will not be able to make any modifications
--   to it.
addCallback :: Progress -> ProgressCallback -> IO ()

-- | Adds a new parent to an existing <a>Progress</a>. The parent will
--   automatically have its completed and total counters incremented by the
--   value of those counters in the existing <a>Progress</a>.
addParent :: Progress -> Progress -> IO ()

-- | Increment the completed unit count in the <a>Progress</a> object by
--   the amount given. If the value as given exceeds the total, then the
--   total will also be raised to match this value so that the completed
--   count never exceeds the total.
--   
--   You can decrease the completed unit count by supplying a negative
--   number here.
incrP :: Progress -> Integer -> IO ()

-- | Like <a>incrP</a>, but never modify the total.
incrP' :: Progress -> Integer -> IO ()

-- | Set the completed unit count in the <a>Progress</a> object to the
--   specified value. Unlike <a>incrP</a>, this function sets the count to
--   a specific value, rather than adding to the existing value. If this
--   value exceeds the total, then the total will also be raised to match
--   this value so that the completed count never exceeds teh total.
setP :: Progress -> Integer -> IO ()

-- | Like <a>setP</a>, but never modify the total.
setP' :: Progress -> Integer -> IO ()

-- | Increment the total unit count in the <a>Progress</a> object by the
--   amount given. This would rarely be needed, but could be needed in some
--   special cases when the total number of units is not known in advance.
incrTotal :: Progress -> Integer -> IO ()

-- | Set the total unit count in the <a>Progress</a> object to the
--   specified value. Like <a>incrTotal</a>, this would rarely be needed.
setTotal :: Progress -> Integer -> IO ()

-- | Call this when you are finished with the object. It is especially
--   important to do this when parent objects are involved.
--   
--   This will simply set the totalUnits to the current completedUnits
--   count, but will not call the callbacks. It will additionally propogate
--   any adjustment in totalUnits to the parents, whose callbacks
--   <i>will</i> be called.
--   
--   This ensures that the total expected counts on the parent are always
--   correct. Without doing this, if, say, a transfer ended earlier than
--   expected, ETA values on the parent would be off since it would be
--   expecting more data than actually arrived.
finishP :: Progress -> IO ()

-- | Returns the speed in units processed per time unit. (If you are using
--   the default time source, this would be units processed per second).
--   This obtains the current speed solely from analyzing the
--   <a>Progress</a> object.
--   
--   If no time has elapsed yet, returns 0.
--   
--   You can use this against either a <a>Progress</a> object or a
--   <a>ProgressStatus</a> object. This is in the IO monad because the
--   speed is based on the current time.
--   
--   Example:
--   
--   <pre>
--   getSpeed progressobj &gt;&gt;= print
--   </pre>
--   
--   Don't let the type of this function confuse you. It is a fancy way of
--   saying that it can take either a <a>Progress</a> or a
--   <a>ProgressStatus</a> object, and returns a number that is valid as
--   any Fractional type, such as a Double, Float, or Rational.
getSpeed :: (ProgressStatuses a (IO b), Fractional b) => a -> IO b

-- | Returns the estimated time remaining, in standard time units.
--   
--   Returns 0 whenever <a>getSpeed</a> would return 0.
--   
--   See the comments under <a>getSpeed</a> for information about this
--   function's type and result.
getETR :: (ProgressStatuses a (IO Integer), ProgressStatuses a (IO Rational)) => a -> IO Integer

-- | Returns the estimated system clock time of completion, in standard
--   time units. Returns the current time whenever <a>getETR</a> would
--   return 0.
--   
--   See the comments under <a>getSpeed</a> for information about this
--   function's type and result.
getETA :: (ProgressStatuses a (IO Integer), ProgressStatuses a (IO Rational)) => a -> IO Integer

-- | The main progress status record.
data ProgressStatus
ProgressStatus :: Integer -> Integer -> Integer -> String -> ProgressTimeSource -> ProgressStatus
[completedUnits] :: ProgressStatus -> Integer
[totalUnits] :: ProgressStatus -> Integer
[startTime] :: ProgressStatus -> Integer

-- | An identifying string
[trackerName] :: ProgressStatus -> String
[timeSource] :: ProgressStatus -> ProgressTimeSource

-- | The main Progress object.
data Progress

-- | A function that, when called, yields the current time. The default is
--   <a>defaultTimeSource</a>.
type ProgressTimeSource = IO Integer

-- | The type for a callback function for the progress tracker. When given
--   at creation time to 'newProgress\'' or when added via
--   <a>addCallback</a>, these functions get called every time the status
--   of the tracker changes.
--   
--   This function is passed two <a>ProgressStatus</a> records: the first
--   reflects the status prior to the update, and the second reflects the
--   status after the update.
--   
--   Please note that the owning <a>Progress</a> object will be locked
--   while the callback is running, so the callback will not be able to
--   make changes to it.
type ProgressCallback = ProgressStatus -> ProgressStatus -> IO ()
class ProgressStatuses a b

-- | Lets you examine the <a>ProgressStatus</a> that is contained within a
--   <a>Progress</a> object. You can simply pass a <a>Progress</a> object
--   and a function to <a>withStatus</a>, and <a>withStatus</a> will lock
--   the <a>Progress</a> object (blocking any modifications while you are
--   reading it), then pass the object to your function. If you happen to
--   already have a <a>ProgressStatus</a> object, withStatus will also
--   accept it and simply pass it unmodified to the function.
withStatus :: ProgressStatuses a b => a -> (ProgressStatus -> b) -> b

-- | The default time source for the system. This is defined as:
--   
--   <pre>
--   getClockTime &gt;&gt;= (return . clockTimeToEpoch)
--   </pre>
defaultTimeSource :: ProgressTimeSource
instance Data.Progress.Tracker.ProgressStatuses Data.Progress.Tracker.Progress (GHC.Types.IO b)
instance Data.Progress.Tracker.ProgressRecords Data.Progress.Tracker.Progress (GHC.Types.IO b)
instance Data.Progress.Tracker.ProgressStatuses Data.Progress.Tracker.ProgressStatus b


-- | Tools for packing into bins
--   
--   Written by John Goerzen, jgoerzen@complete.org
--   
--   This module is designed to solve this type of problem: Given a bunch
--   of objects of varying sizes, what is the best possible way to pack
--   them into fixed-size bins? This can be used, for instance, by the
--   datapacker program to pack files onto CDs or DVDs; by manufacturing
--   environments to pack physical items into physicl bins; etc.
--   
--   A description of bin packing algorithms can be found at
--   <a>http://en.wikipedia.org/wiki/Bin_packing_problem</a>.
module Data.BinPacking

-- | The primary type for bin-packing functions.
--   
--   These functions take a list of size of bins. If every bin is the same
--   size, you can pass <tt>repeat binSize</tt> to pass an infinite list of
--   bins if the same size. Any surplus bins will simply be ignored.
--   
--   <pre>
--   [size] is the sizes of bins
--   [(size, obj)] is the sizes and objects
--   result is Either error or results
--   </pre>
type BinPacker = (Num size, Ord size, Show size, Show obj) => [size] -> [(size, obj)] -> Either (BinPackerError size obj) [[(size, obj)]]

-- | Potential errors returned as Left values by <a>BinPacker</a>
--   functions. Calling <a>show</a> on this value will produce a nice error
--   message suitable for display.
data (Num size, Ord size, Show size, Show obj) => BinPackerError size obj

-- | Ran out of bins; attached value is the list of objects that do not fit
BPTooFewBins :: [(size, obj)] -> BinPackerError size obj

-- | Bin size1 exceeded by at least the given object and size
BPSizeTooLarge :: size -> (size, obj) -> BinPackerError size obj

-- | Other error
BPOther :: String -> BinPackerError size obj

-- | Pack objects into bins, preserving order. Objects will be taken from
--   the input list one by one, and added to each bin until the bin is
--   full. Work will then proceed on the next bin. No attempt is made to
--   optimize allocations to bins. This is the simplest and most naive
--   bin-packing algorithm, but may not make very good use of bin space.
packByOrder :: BinPacker

-- | Pack objects into bins. For each bin, start with the largest objects,
--   and keep packing the largest object from the remainder until no object
--   can be found to put in the bin. This is substantially more efficient
--   than <a>packByOrder</a>, but requires sorting the input.
packLargeFirst :: BinPacker
instance (GHC.Num.Num size, GHC.Classes.Ord size, GHC.Read.Read size, GHC.Read.Read obj, GHC.Show.Show size, GHC.Show.Show obj) => GHC.Read.Read (Data.BinPacking.BinPackerError size obj)
instance (GHC.Classes.Eq obj, GHC.Num.Num size, GHC.Classes.Ord size, GHC.Show.Show size, GHC.Show.Show obj) => GHC.Classes.Eq (Data.BinPacking.BinPackerError size obj)
instance (GHC.Num.Num size, GHC.Classes.Ord size, GHC.Show.Show size, GHC.Show.Show obj) => GHC.Show.Show (Data.BinPacking.BinPackerError size obj)
instance (GHC.Num.Num size, GHC.Classes.Ord size, GHC.Show.Show size, GHC.Show.Show obj) => Control.Monad.Trans.Error.Error (Data.BinPacking.BinPackerError size obj)


-- | Haskell Parsec parsers for comma-separated value (CSV) files.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Data.CSV

-- | Parse a Comma-Separated Value (CSV) file. The return value is a list
--   of lines; each line is a list of cells; and each cell is a String.
--   
--   Please note that CSV files may have a different number of cells on
--   each line. Also, it is impossible to distinguish a CSV line that has a
--   call with no data from a CSV line that has no cells.
--   
--   Here are some examples:
--   
--   <pre>
--   Input (literal strings)          Parses As (Haskell String syntax)
--   -------------------------------- ---------------------------------
--   1,2,3                            [["1", "2", "3"]]
--   
--   l1                               [["l1"], ["l2"]]
--   l2
--   
--    (empty line)                    [[""]]
--   
--   NQ,"Quoted"                      [["NQ", "Quoted"]]
--   
--   NQ,"Embedded""Quote"             [["NQ", "Embedded\"Quote"]]
--   </pre>
--   
--   To parse a String, you might use:
--   
--   <pre>
--   import Text.ParserCombinators.Parsec
--   import Data.String.CSV
--   ....
--   parse csvFile "" mystring
--   </pre>
--   
--   To parse a file, you might instead use:
--   
--   <pre>
--   do result &lt;- parseFromFile csvFile "/path/to/file"
--   </pre>
--   
--   Please note that the result of parsing will be of type (Either
--   ParseError [[String]]). A Left result indicates an error. For more
--   details, see the Parsec information.
csvFile :: CharParser st [[String]]

-- | Generate CSV data for a file. The resulting string can be written out
--   to disk directly.
genCsvFile :: [[String]] -> String


-- | Command invocation utilities.
--   
--   Written by John Goerzen, jgoerzen@complete.org
--   
--   Please note: Most of this module is not compatible with Hugs.
--   
--   Command lines executed will be logged using <a>System.Log.Logger</a>
--   at the DEBUG level. Failure messages will be logged at the WARNING
--   level in addition to being raised as an exception. Both are logged
--   under "System.Cmd.Utils.funcname" -- for instance,
--   "System.Cmd.Utils.safeSystem". If you wish to suppress these messages
--   globally, you can simply run:
--   
--   <pre>
--   updateGlobalLogger "System.Cmd.Utils.safeSystem"
--                       (setLevel CRITICAL)
--   </pre>
--   
--   See also: <a>updateGlobalLogger</a>, <a>System.Log.Logger</a>.
--   
--   It is possible to set up pipelines with these utilities. Example:
--   
--   <pre>
--   (pid1, x1) &lt;- pipeFrom "ls" ["/etc"]
--   (pid2, x2) &lt;- pipeBoth "grep" ["x"] x1
--   putStr x2
--   ... the grep output is displayed ...
--   forceSuccess pid2
--   forceSuccess pid1
--   </pre>
--   
--   Remember, when you use the functions that return a String, you must
--   not call <a>forceSuccess</a> until after all data from the String has
--   been consumed. Failure to wait will cause your program to appear to
--   hang.
--   
--   Here is an example of the wrong way to do it:
--   
--   <pre>
--   (pid, x) &lt;- pipeFrom "ls" ["/etc"]
--   forceSuccess pid         -- Hangs; the called program hasn't terminated yet
--   processTheData x
--   </pre>
--   
--   You must instead process the data before calling <a>forceSuccess</a>.
--   
--   When using the hPipe family of functions, this is probably more
--   obvious.
--   
--   Most of this module will be incompatible with Windows.
module System.Cmd.Utils

-- | Return value from <a>pipeFrom</a>, <a>pipeLinesFrom</a>,
--   <a>pipeTo</a>, or <a>pipeBoth</a>. Contains both a ProcessID and the
--   original command that was executed. If you prefer not to use
--   <a>forceSuccess</a> on the result of one of these pipe calls, you can
--   use (processID ph), assuming ph is your <a>PipeHandle</a>, as a
--   parameter to <a>getProcessStatus</a>.
data PipeHandle
PipeHandle :: ProcessID -> FilePath -> [String] -> String -> PipeHandle
[processID] :: PipeHandle -> ProcessID
[phCommand] :: PipeHandle -> FilePath
[phArgs] :: PipeHandle -> [String]

-- | Function that created it
[phCreator] :: PipeHandle -> String

-- | Invokes the specified command in a subprocess, waiting for the result.
--   If the command terminated successfully, return normally. Otherwise,
--   raises a userError with the problem.
--   
--   Implemented in terms of <a>posixRawSystem</a> where supported, and
--   System.Posix.rawSystem otherwise.
safeSystem :: FilePath -> [String] -> IO ()

-- | Uses <a>getProcessStatus</a> to obtain the exit status of the given
--   process ID. If the process terminated normally, does nothing.
--   Otherwise, raises an exception with an appropriate error message.
--   
--   This call will block waiting for the given pid to terminate.
--   
--   Not available on Windows.
forceSuccess :: PipeHandle -> IO ()

-- | Invokes the specified command in a subprocess, waiting for the result.
--   Return the result status. Never raises an exception. Only available on
--   POSIX platforms.
--   
--   Like system(3), this command ignores SIGINT and SIGQUIT and blocks
--   SIGCHLD during its execution.
--   
--   Logs as System.Cmd.Utils.posixRawSystem
posixRawSystem :: FilePath -> [String] -> IO ProcessStatus

-- | Invokes the specified command in a subprocess, without waiting for the
--   result. Returns the PID of the subprocess -- it is YOUR responsibility
--   to use getProcessStatus or getAnyProcessStatus on that at some point.
--   Failure to do so will lead to resource leakage (zombie processes).
--   
--   This function does nothing with signals. That too is up to you.
--   
--   Logs as System.Cmd.Utils.forkRawSystem
forkRawSystem :: FilePath -> [String] -> IO ProcessID

-- | Read data from a pipe. Returns a lazy string and a <a>PipeHandle</a>.
--   
--   ONLY AFTER the string has been read completely, You must call either
--   <a>getProcessStatus</a> or <a>forceSuccess</a> on the
--   <a>PipeHandle</a>. Zombies will result otherwise.
--   
--   Not available on Windows.
pipeFrom :: FilePath -> [String] -> IO (PipeHandle, String)

-- | Like <a>pipeFrom</a>, but returns data in lines instead of just a
--   String. Shortcut for calling lines on the result from <a>pipeFrom</a>.
--   
--   Note: this function logs as pipeFrom.
--   
--   Not available on Windows.
pipeLinesFrom :: FilePath -> [String] -> IO (PipeHandle, [String])

-- | Write data to a pipe. Returns a ProcessID.
--   
--   You must call either <a>getProcessStatus</a> or <a>forceSuccess</a> on
--   the ProcessID. Zombies will result otherwise.
--   
--   Not available on Windows.
pipeTo :: FilePath -> [String] -> String -> IO PipeHandle

-- | Like a combination of <a>pipeTo</a> and <a>pipeFrom</a>; forks an IO
--   thread to send data to the piped program, and simultaneously returns
--   its output stream.
--   
--   The same note about checking the return status applies here as with
--   <a>pipeFrom</a>.
--   
--   Not available on Windows.
pipeBoth :: FilePath -> [String] -> String -> IO (PipeHandle, String)

-- | Read data from a pipe. Returns a Handle and a <a>PipeHandle</a>.
--   
--   When done, you must hClose the handle, and then use either
--   <a>forceSuccess</a> or getProcessStatus on the <a>PipeHandle</a>.
--   Zombies will result otherwise.
--   
--   This function logs as pipeFrom.
--   
--   Not available on Windows or with Hugs.
hPipeFrom :: FilePath -> [String] -> IO (PipeHandle, Handle)

-- | Write data to a pipe. Returns a <a>PipeHandle</a> and a new Handle to
--   write to.
--   
--   When done, you must hClose the handle, and then use either
--   <a>forceSuccess</a> or getProcessStatus on the <a>PipeHandle</a>.
--   Zombies will result otherwise.
--   
--   This function logs as pipeTo.
--   
--   Not available on Windows.
hPipeTo :: FilePath -> [String] -> IO (PipeHandle, Handle)

-- | Like a combination of <a>hPipeTo</a> and <a>hPipeFrom</a>; returns a
--   3-tuple of (<a>PipeHandle</a>, Data From Pipe, Data To Pipe).
--   
--   When done, you must hClose both handles, and then use either
--   <a>forceSuccess</a> or getProcessStatus on the <a>PipeHandle</a>.
--   Zombies will result otherwise.
--   
--   Hint: you will usually need to ForkIO a thread to handle one of the
--   Handles; otherwise, deadlock can result.
--   
--   This function logs as pipeBoth.
--   
--   Not available on Windows.
hPipeBoth :: FilePath -> [String] -> IO (PipeHandle, Handle, Handle)
data PipeMode
ReadFromPipe :: PipeMode
WriteToPipe :: PipeMode

-- | Open a pipe to the specified command.
--   
--   Passes the handle on to the specified function.
--   
--   The <a>PipeMode</a> specifies what you will be doing. That is,
--   specifing <a>ReadFromPipe</a> sets up a pipe from stdin, and
--   <a>WriteToPipe</a> sets up a pipe from stdout.
--   
--   Not available on Windows.
pOpen :: PipeMode -> FilePath -> [String] -> (Handle -> IO a) -> IO a

-- | Runs a command, redirecting things to pipes.
--   
--   Not available on Windows.
--   
--   Note that you may not use the same fd on more than one item. If you
--   want to redirect stdout and stderr, dup it first.
pOpen3 :: Maybe Fd -> Maybe Fd -> Maybe Fd -> FilePath -> [String] -> (ProcessID -> IO a) -> IO () -> IO a

-- | Runs a command, redirecting things to pipes.
--   
--   Not available on Windows.
--   
--   Returns immediately with the PID of the child. Using
--   <tt>waitProcess</tt> on it is YOUR responsibility!
--   
--   Note that you may not use the same fd on more than one item. If you
--   want to redirect stdout and stderr, dup it first.
pOpen3Raw :: Maybe Fd -> Maybe Fd -> Maybe Fd -> FilePath -> [String] -> IO () -> IO ProcessID
instance GHC.Show.Show System.Cmd.Utils.PipeHandle
instance GHC.Classes.Eq System.Cmd.Utils.PipeHandle


-- | This Haskell module provides an interface to transmitting a mail
--   message.
--   
--   This is not compatible with Windows at this time.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Network.Email.Sendmail

-- | Transmits an e-mail message using the system's mail transport agent.
--   
--   This function takes a message, a list of recipients, and an optional
--   sender, and transmits it using the system's MTA, sendmail.
--   
--   If <tt>sendmail</tt> is on the <tt>PATH</tt>, it will be used;
--   otherwise, a list of system default locations will be searched.
--   
--   A failure will be logged, since this function uses <a>safeSystem</a>
--   internally.
--   
--   This function will first try <tt>sendmail</tt>. If it does not exist,
--   an error is logged under <tt>System.Cmd.Utils.pOpen3</tt> and various
--   default <tt>sendmail</tt> locations are tried. If that still fails, an
--   error is logged and an exception raised.
sendmail :: Maybe String -> [String] -> String -> IO ()


-- | This module provides various helpful utilities for dealing with
--   threads.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Control.Concurrent.Thread.Utils

-- | Takes a IO action and a function. The IO action will be called in a
--   separate thread. When it is completed, the specified function is
--   called with its result. This is a simple way of doing callbacks.
runInThread :: IO a -> (a -> IO b) -> IO ThreadId


-- | General support for e-mail mailboxes
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Network.Email.Mailbox

-- | The flags which may be assigned to a message.
data Flag
SEEN :: Flag
ANSWERED :: Flag
FLAGGED :: Flag
DELETED :: Flag
DRAFT :: Flag
FORWARDED :: Flag
OTHERFLAG :: String -> Flag

-- | Convenience shortcut
type Flags = [Flag]

-- | A Message is represented as a simple String.
type Message = String

-- | Main class for readable mailboxes.
--   
--   The mailbox object <i>a</i> represents zero or more <a>Message</a>s.
--   Each message has a unique identifier <i>b</i> in a format specific to
--   each given mailbox. This identifier may or may not be persistent.
--   
--   Functions which return a list are encouraged -- but not guaranteed --
--   to do so lazily.
--   
--   Implementing classes must provide, at minimum, <a>getAll</a>.
class (Show a, Show b, Eq b) => MailboxReader a b where listIDs mb = listMessageFlags mb >>= return . map fst listMessageFlags mb = getAll mb >>= return . map (\ (i, f, _) -> (i, f)) getMessages mb list = do { messages <- getAll mb; return $ filter (\ (id, f, m) -> id `elem` list) messages }

-- | Returns a list of all unique identifiers.
listIDs :: MailboxReader a b => a -> IO [b]

-- | Returns a list of all unique identifiers as well as all flags.
listMessageFlags :: MailboxReader a b => a -> IO [(b, Flags)]

-- | Returns a list of all messages, including their content, flags, and
--   unique identifiers.
getAll :: MailboxReader a b => a -> IO [(b, Flags, Message)]

-- | Returns information about specific messages.
getMessages :: MailboxReader a b => a -> [b] -> IO [(b, Flags, Message)]
class (MailboxReader a b) => MailboxWriter a b
appendMessages :: MailboxWriter a b => a -> [(Flags, Message)] -> IO [b]
deleteMessages :: MailboxWriter a b => a -> [b] -> IO ()
addFlags :: MailboxWriter a b => a -> [b] -> Flags -> IO ()
removeFlags :: MailboxWriter a b => a -> [b] -> Flags -> IO ()
setFlags :: MailboxWriter a b => a -> [b] -> Flags -> IO ()
instance GHC.Show.Show Network.Email.Mailbox.Flag
instance GHC.Classes.Eq Network.Email.Mailbox.Flag


-- | Written by John Goerzen, jgoerzen@complete.org
module Text.ParserCombinators.Parsec.Utils
type GeneralizedToken a = (SourcePos, a)
type GeneralizedTokenParser a st b = GenParser (GeneralizedToken a) st b

-- | Generate (return) a <a>GeneralizedToken</a>.
togtok :: a -> GenParser b st (GeneralizedToken a)

-- | Retrieve the next token from a <a>GeneralizedToken</a> stream. The
--   given function should return the value to use, or Nothing to cause an
--   error.
tokeng :: (Show a) => (a -> Maybe b) -> GeneralizedTokenParser a st b

-- | A shortcut to <a>tokeng</a>; the test here is just a function that
--   returns a Bool. If the result is true; return that value -- otherwise,
--   an error.
satisfyg :: (Show a) => (a -> Bool) -> GeneralizedTokenParser a st a

-- | Matches one item in a list and returns it.
oneOfg :: (Eq a, Show a) => [a] -> GeneralizedTokenParser a st a

-- | Matches one item not in a list and returns it.
noneOfg :: (Eq a, Show a) => [a] -> GeneralizedTokenParser a st a

-- | Matches one specific token and returns it.
specificg :: (Eq a, Show a) => a -> GeneralizedTokenParser a st a

-- | Matches all items and returns them
allg :: (Show a) => GeneralizedTokenParser a st [a]

-- | Running <tt>notMatching p msg</tt> will try to apply parser p. If it
--   fails, returns (). If it succeds, cause a failure and raise the given
--   error message. It will not consume input in either case.
notMatching :: GenParser a b c -> String -> GenParser a b ()


-- | Tools for writing daemons/server processes
--   
--   Written by John Goerzen, jgoerzen@complete.org
--   
--   Please note: Most of this module is not compatible with Hugs.
--   
--   Messages from this module are logged under <tt>System.Daemon</tt>. See
--   <a>Logger</a> for details.
--   
--   Based on background from
--   <a>http://www.erlenstar.demon.co.uk/unix/faq_2.html#SEC16</a> and
--   <a>http://www.haskell.org/hawiki/HaskellUnixDaemon</a>.
--   
--   This module is not available on Windows.
module System.Daemon

-- | Detach the process from a controlling terminal and run it in the
--   background, handling it with standard Unix deamon semantics.
--   
--   After running this, please note the following side-effects:
--   
--   <ul>
--   <li>The PID of the running process will change</li>
--   <li>stdin, stdout, and stderr will not work (they'll be set to
--   /dev/null)</li>
--   <li>CWD will be changed to /</li>
--   </ul>
--   
--   I <i>highly</i> suggest running this function before starting any
--   threads.
--   
--   Note that this is not intended for a daemon invoked from inetd(1).
detachDaemon :: IO ()


-- | Haskell Virtual I/O -- a system to increase the flexibility of input
--   and output in Haskell
--   
--   Copyright (c) 2004-2005 John Goerzen, jgoerzen@complete.org
--   
--   HVIO provides the following general features:
--   
--   <ul>
--   <li>The ability to use a single set of functions on various different
--   types of objects, including standard Handles, in-memory buffers,
--   compressed files, network data streams, etc.</li>
--   <li>The ability to transparently add filters to the I/O process. These
--   filters could include things such as character set conversions,
--   compression or decompression of a data stream, and more.</li>
--   <li>The ability to define new objects that have the properties of I/O
--   objects and can be used interchangably with them.</li>
--   <li>Specification compatibility with, and complete support for,
--   existing I/O on Handles.</li>
--   <li>Provide easier unit testing capabilities for I/O actions</li>
--   </ul>
--   
--   HVIO defines several basic type classes that you can use. You will
--   mostly be interested in <a>HVIO</a>.
--   
--   It's trivial to adapt old code to work with HVIO. For instance,
--   consider this example of old and new code:
--   
--   <pre>
--   printMsg :: Handle -&gt; String -&gt; IO ()
--   printMsg h msg = hPutStr h ("msg: " ++ msg)
--   </pre>
--   
--   And now, the new way:
--   
--   <pre>
--   printMsg :: HVIO h =&gt; h -&gt; String -&gt; IO ()
--   printMsg h msg = vPutStr h ("msg: " ++ msg)
--   </pre>
--   
--   There are several points to note about this conversion:
--   
--   <ul>
--   <li>The new method can still accept a Handle in exactly the same way
--   as the old method. Changing your functions to use HVIO will require no
--   changes from functions that call them with Handles.</li>
--   <li>Most "h" functions have equivolent "v" functions that operate on
--   HVIO classes instead of the more specific Handle. The "v" functions
--   behave identically to the "h" functions whenever possible.</li>
--   <li>There is no equivolent of "openFile" in any HVIO class. You must
--   create your Handle (or other HVIO object) using normal means. This is
--   because the creation is so different that it cannot be
--   standardized.</li>
--   </ul>
--   
--   In addition to Handle, there are several pre-defined classes for your
--   use. <a>StreamReader</a> is a particularly interesting one. At
--   creation time, you pass it a String. Its contents are read lazily
--   whenever a read call is made. It can be used, therefore, to implement
--   filters (simply initialize it with the result from, say, a map over
--   hGetContents from another HVIO object), codecs, and simple I/O
--   testing. Because it is lazy, it need not hold the entire string in
--   memory. You can create a <a>StreamReader</a> with a call to
--   <a>newStreamReader</a>.
--   
--   <a>MemoryBuffer</a> is a similar class, but with a different purpose.
--   It provides a full interface like Handle (it implements
--   <tt>HVIOReader</tt>, <tt>HVIOWriter</tt>, and <tt>HVIOSeeker</tt>).
--   However, it maintains an in-memory buffer with the contents of the
--   file, rather than an actual on-disk file. You can access the entire
--   contents of this buffer at any time. This can be quite useful for
--   testing I/O code, or for cases where existing APIs use I/O, but you
--   prefer a String representation. You can create a <a>MemoryBuffer</a>
--   with a call to <a>newMemoryBuffer</a>.
--   
--   Finally, there are pipes. These pipes are analogous to the Unix pipes
--   that are available from System.Posix, but don't require Unix and work
--   only in Haskell. When you create a pipe, you actually get two HVIO
--   objects: a <a>PipeReader</a> and a <a>PipeWriter</a>. You must use the
--   <a>PipeWriter</a> in one thread and the <a>PipeReader</a> in another
--   thread. Data that's written to the <a>PipeWriter</a> will then be
--   available for reading with the <a>PipeReader</a>. The pipes are
--   implemented completely with existing Haskell threading primitives, and
--   require no special operating system support. Unlike Unix pipes, these
--   pipes cannot be used across a fork(). Also unlike Unix pipes, these
--   pipes are portable and interact well with Haskell threads. A new pipe
--   can be created with a call to <a>newHVIOPipe</a>.
--   
--   Together with <a>System.IO.HVFS</a>, this module is part of a complete
--   virtual filesystem solution.
module System.IO.HVIO

-- | This is the generic I/O support class. All objects that are to be used
--   in the HVIO system must provide an instance of <a>HVIO</a>.
--   
--   Functions in this class provide an interface with the same
--   specification as the similar functions in System.IO. Please refer to
--   that documentation for a more complete specification than is provided
--   here.
--   
--   Instances of <a>HVIO</a> must provide <a>vClose</a>, <a>vIsEOF</a>,
--   and either <a>vIsOpen</a> or <a>vIsClosed</a>.
--   
--   Implementators of readable objects must provide at least
--   <a>vGetChar</a> and <a>vIsReadable</a>. An implementation of
--   <a>vGetContents</a> is also highly suggested, since the default cannot
--   implement proper partial closing semantics.
--   
--   Implementators of writable objects must provide at least
--   <a>vPutChar</a> and <a>vIsWritable</a>.
--   
--   Implementators of seekable objects must provide at least
--   <a>vIsSeekable</a>, <a>vTell</a>, and <a>vSeek</a>.
class (Show a) => HVIO a where vSetBuffering _ _ = return () vGetBuffering _ = return NoBuffering vShow x = return (show x) vMkIOError _ et desc mfp = mkIOError et desc Nothing mfp vGetFP _ = return Nothing vThrow h et = do { fp <- vGetFP h; ioError (vMkIOError h et "" fp) } vTestEOF h = do { e <- vIsEOF h; if e then vThrow h eofErrorType else return () } vIsOpen h = vIsClosed h >>= return . not vIsClosed h = vIsOpen h >>= return . not vTestOpen h = do { e <- vIsClosed h; if e then vThrow h illegalOperationErrorType else return () } vIsReadable _ = return False vGetLine h = let loop accum = let func = do { c <- vGetChar h; case c of { '\n' -> return accum x -> accum `seq` loop (accum ++ [x]) } } handler e = if isEOFError e then return accum else ioError e in catch func handler in do { firstchar <- vGetChar h; case firstchar of { '\n' -> return [] x -> loop [x] } } vGetContents h = let loop = let func = do { c <- vGetChar h; next <- loop; c `seq` return (c : next) } handler e = if isEOFError e then return [] else ioError e in catch func handler in do { loop } vReady h = do { vTestEOF h; return True } vIsWritable _ = return False vPutStr _ [] = return () vPutStr h (x : xs) = do { vPutChar h x; vPutStr h xs } vPutStrLn h s = vPutStr h (s ++ "\n") vPrint h s = vPutStrLn h (show s) vFlush = vTestOpen vIsSeekable _ = return False vRewind h = vSeek h AbsoluteSeek 0 vPutChar h _ = vThrow h illegalOperationErrorType vSeek h _ _ = vThrow h illegalOperationErrorType vTell h = vThrow h illegalOperationErrorType vGetChar h = vThrow h illegalOperationErrorType vPutBuf h buf len = do { str <- peekCStringLen (castPtr buf, len); vPutStr h str } vGetBuf h b l = worker b l 0 where worker _ 0 accum = return accum worker buf len accum = do { iseof <- vIsEOF h; if iseof then return accum else do { c <- vGetChar h; let cc = castCharToCChar c; poke (castPtr buf) cc; let newptr = plusPtr buf 1; worker newptr (len - 1) (accum + 1) } }

-- | Close a file
vClose :: HVIO a => a -> IO ()

-- | Test if a file is open
vIsOpen :: HVIO a => a -> IO Bool

-- | Test if a file is closed
vIsClosed :: HVIO a => a -> IO Bool

-- | Raise an error if the file is not open. This is a new HVIO function
--   and is implemented in terms of <a>vIsOpen</a>.
vTestOpen :: HVIO a => a -> IO ()

-- | Whether or not we're at EOF. This may raise on exception on some
--   items, most notably write-only Handles such as stdout. In general,
--   this is most reliable on items opened for reading. vIsEOF
--   implementations must implicitly call vTestOpen.
vIsEOF :: HVIO a => a -> IO Bool

-- | Detailed show output.
vShow :: HVIO a => a -> IO String

-- | Make an IOError.
vMkIOError :: HVIO a => a -> IOErrorType -> String -> Maybe FilePath -> IOError

-- | Throw an IOError.
vThrow :: HVIO a => a -> IOErrorType -> IO b

-- | Get the filename/object/whatever that this corresponds to. May be
--   Nothing.
vGetFP :: HVIO a => a -> IO (Maybe FilePath)

-- | Throw an isEOFError if we're at EOF; returns nothing otherwise. If an
--   implementation overrides the default, make sure that it calls
--   vTestOpen at some point. The default implementation is a wrapper
--   around a call to <a>vIsEOF</a>.
vTestEOF :: HVIO a => a -> IO ()

-- | Read one character
vGetChar :: HVIO a => a -> IO Char

-- | Read one line
vGetLine :: HVIO a => a -> IO String

-- | Get the remaining contents. Please note that as a user of this
--   function, the same partial-closing semantics as are used in the
--   standard <a>hGetContents</a> are <i>encouraged</i> from
--   implementators, but are not <i>required</i>. That means that, for
--   instance, a <a>vGetChar</a> after a <a>vGetContents</a> may return
--   some undefined result instead of the error you would normally get. You
--   should use caution to make sure your code doesn't fall into that trap,
--   or make sure to test your code with Handle or one of the default
--   instances defined in this module. Also, some implementations may
--   essentially provide a complete close after a call to
--   <a>vGetContents</a>. The bottom line: after a call to
--   <a>vGetContents</a>, you should do nothing else with the object save
--   closing it with <a>vClose</a>.
--   
--   For implementators, you are highly encouraged to provide a correct
--   implementation.
vGetContents :: HVIO a => a -> IO String

-- | Indicate whether at least one item is ready for reading. This will
--   always be True for a great many implementations.
vReady :: HVIO a => a -> IO Bool

-- | Indicate whether a particular item is available for reading.
vIsReadable :: HVIO a => a -> IO Bool

-- | Write one character
vPutChar :: HVIO a => a -> Char -> IO ()

-- | Write a string
vPutStr :: HVIO a => a -> String -> IO ()

-- | Write a string with newline character after it
vPutStrLn :: HVIO a => a -> String -> IO ()

-- | Write a string representation of the argument, plus a newline.
vPrint :: (HVIO a, Show b) => a -> b -> IO ()

-- | Flush any output buffers. Note: implementations should assure that a
--   vFlush is automatically performed on file close, if necessary to
--   ensure all data sent is written.
vFlush :: HVIO a => a -> IO ()

-- | Indicate whether or not this particular object supports writing.
vIsWritable :: HVIO a => a -> IO Bool

-- | Seek to a specific location.
vSeek :: HVIO a => a -> SeekMode -> Integer -> IO ()

-- | Get the current position.
vTell :: HVIO a => a -> IO Integer

-- | Convenience function to reset the file pointer to the beginning of the
--   file. A call to <tt>vRewind h</tt> is the same as <tt><a>vSeek</a> h
--   AbsoluteSeek 0</tt>.
vRewind :: HVIO a => a -> IO ()

-- | Indicate whether this instance supports seeking.
vIsSeekable :: HVIO a => a -> IO Bool

-- | Set buffering; the default action is a no-op.
vSetBuffering :: HVIO a => a -> BufferMode -> IO ()

-- | Get buffering; the default action always returns NoBuffering.
vGetBuffering :: HVIO a => a -> IO BufferMode

-- | Binary output: write the specified number of octets from the specified
--   buffer location.
vPutBuf :: HVIO a => a -> Ptr b -> Int -> IO ()

-- | Binary input: read the specified number of octets from the specified
--   buffer location, continuing to read until it either consumes that much
--   data or EOF is encountered. Returns the number of octets actually
--   read. EOF errors are never raised; fewer bytes than requested are
--   returned on EOF.
vGetBuf :: HVIO a => a -> Ptr b -> Int -> IO Int

-- | Simulate I/O based on a string buffer.
--   
--   When a <a>StreamReader</a> is created, it is initialized based on the
--   contents of a <a>String</a>. Its contents are read lazily whenever a
--   request is made to read something from the <a>StreamReader</a>. It can
--   be used, therefore, to implement filters (simply initialize it with
--   the result from, say, a map over hGetContents from another HVIO
--   object), codecs, and simple I/O testing. Because it is lazy, it need
--   not hold the entire string in memory. You can create a
--   <a>StreamReader</a> with a call to <a>newStreamReader</a>.
data StreamReader

-- | Create a new <a>StreamReader</a> object.
newStreamReader :: String -> IO StreamReader

-- | A <a>MemoryBuffer</a> simulates true I/O, but uses an in-memory buffer
--   instead of on-disk storage.
--   
--   It provides a full interface like Handle (it implements
--   <tt>HVIOReader</tt>, <tt>HVIOWriter</tt>, and <tt>HVIOSeeker</tt>).
--   However, it maintains an in-memory buffer with the contents of the
--   file, rather than an actual on-disk file. You can access the entire
--   contents of this buffer at any time. This can be quite useful for
--   testing I/O code, or for cases where existing APIs use I/O, but you
--   prefer a String representation. You can create a <a>MemoryBuffer</a>
--   with a call to <a>newMemoryBuffer</a>.
--   
--   The present <a>MemoryBuffer</a> implementation is rather inefficient,
--   particularly when reading towards the end of large files. It's best
--   used for smallish data storage. This problem will be fixed eventually.
data MemoryBuffer

-- | Create a new <a>MemoryBuffer</a> instance. The buffer is initialized
--   to the value passed, and the pointer is placed at the beginning of the
--   file.
--   
--   You can put things in it by using the normal <a>vPutStr</a> calls, and
--   reset to the beginning by using the normal <a>vRewind</a> call.
--   
--   The function is called when <a>vClose</a> is called, and is passed the
--   contents of the buffer at close time. You can use
--   <a>mbDefaultCloseFunc</a> if you don't want to do anything.
--   
--   To create an empty buffer, pass the initial value <tt>""</tt>.
newMemoryBuffer :: String -> (String -> IO ()) -> IO MemoryBuffer

-- | Default (no-op) memory buf close function.
mbDefaultCloseFunc :: String -> IO ()

-- | Grab the entire contents of the buffer as a string. Unlike
--   <a>vGetContents</a>, this has no effect on the open status of the
--   item, the EOF status, or the current position of the file pointer.
getMemoryBuffer :: MemoryBuffer -> IO String

-- | The reading side of a Haskell pipe. Please see <a>newHVIOPipe</a> for
--   more details.
data PipeReader

-- | The writing side of a Haskell pipe. Please see <a>newHVIOPipe</a> for
--   more details.
data PipeWriter

-- | Create a Haskell pipe.
--   
--   These pipes are analogous to the Unix pipes that are available from
--   System.Posix, but don't require Unix and work only in Haskell. When
--   you create a pipe, you actually get two HVIO objects: a
--   <a>PipeReader</a> and a <a>PipeWriter</a>. You must use the
--   <a>PipeWriter</a> in one thread and the <a>PipeReader</a> in another
--   thread. Data that's written to the <a>PipeWriter</a> will then be
--   available for reading with the <a>PipeReader</a>. The pipes are
--   implemented completely with existing Haskell threading primitives, and
--   require no special operating system support. Unlike Unix pipes, these
--   pipes cannot be used across a fork(). Also unlike Unix pipes, these
--   pipes are portable and interact well with Haskell threads.
newHVIOPipe :: IO (PipeReader, PipeWriter)
instance GHC.Show.Show System.IO.HVIO.PipeBit
instance GHC.Classes.Eq System.IO.HVIO.PipeBit
instance System.IO.HVIO.HVIO GHC.IO.Handle.Types.Handle
instance GHC.Show.Show System.IO.HVIO.StreamReader
instance System.IO.HVIO.HVIO System.IO.HVIO.StreamReader
instance GHC.Show.Show System.IO.HVIO.MemoryBuffer
instance System.IO.HVIO.HVIO System.IO.HVIO.MemoryBuffer
instance GHC.Show.Show System.IO.HVIO.PipeReader
instance System.IO.HVIO.HVIO System.IO.HVIO.PipeReader
instance GHC.Show.Show System.IO.HVIO.PipeWriter
instance System.IO.HVIO.HVIO System.IO.HVIO.PipeWriter


-- | Haskell Virtual FS -- generic support for real or virtual filesystem
--   in Haskell
--   
--   Copyright (c) 2004-2005 John Goerzen, jgoerzen@complete.org
--   
--   The idea of this module is to provide virtualization of filesystem
--   calls. In addition to the "real" system filesystem, you can also
--   provide access to other, virtual, filesystems using the same set of
--   calls. Examples of such virtual filesystems might include a remote FTP
--   server, WebDAV server, a local Hashtable, a ConfigParser object, or
--   any other data structure you can represent as a tree of named nodes
--   containing strings.
--   
--   Each <a>HVFS</a> function takes a <a>HVFS</a> "handle" (<a>HVFS</a>
--   instance) as its first parameter. If you wish to operate on the
--   standard system filesystem, you can just use <a>SystemFS</a>.
--   
--   The <a>MissingH.HVFS.IO.InstanceHelpers</a> module contains some code
--   to help you make your own HVFS instances.
--   
--   The <a>HVFSOpenable</a> class works together with the
--   <a>System.IO.HVIO</a> module to provide a complete virtual filesystem
--   and I/O model that allows you to open up virtual filesystem files and
--   act upon them in a manner similar to standard Handles.
module System.IO.HVFS

-- | The main HVFS class.
--   
--   Default implementations of these functions are provided:
--   
--   <ul>
--   <li><a>vGetModificationTime</a> -- implemented in terms of
--   <a>vGetFileStatus</a></li>
--   <li><a>vRaiseError</a></li>
--   <li><a>vDoesFileExist</a> -- implemented in terms of
--   <a>vGetFileStatus</a></li>
--   <li><a>vDoesDirectoryExist</a> -- implemented in terms of
--   <a>vGetFileStatus</a></li>
--   <li><a>vDoesExist</a> -- implemented in terms of
--   <a>vGetSymbolicLinkStatus</a></li>
--   <li><a>vGetSymbolicLinkStatus</a> -- set to call
--   <a>vGetFileStatus</a>.</li>
--   </ul>
--   
--   Default implementations of all other functions will generate an
--   isIllegalOperation error, since they are assumed to be un-implemented.
--   
--   You should always provide at least a <a>vGetFileStatus</a> call, and
--   almost certainly several of the others.
--   
--   Most of these functions correspond to functions in System.Directory or
--   System.Posix.Files. Please see detailed documentation on them there.
class (Show a) => HVFS a where vGetModificationTime fs fp = do { s <- vGetFileStatus fs fp; return $ epochToClockTime (withStat s vModificationTime) } vRaiseError _ et desc mfp = ioError $ mkIOError et desc Nothing mfp vGetCurrentDirectory fs = eh fs "vGetCurrentDirectory" vSetCurrentDirectory fs _ = eh fs "vSetCurrentDirectory" vGetDirectoryContents fs _ = eh fs "vGetDirectoryContents" vDoesFileExist fs fp = catch (do { s <- vGetFileStatus fs fp; return $ withStat s vIsRegularFile }) (\ (_ :: IOException) -> return False) vDoesDirectoryExist fs fp = catch (do { s <- vGetFileStatus fs fp; return $ withStat s vIsDirectory }) (\ (_ :: IOException) -> return False) vDoesExist fs fp = catch (do { s <- vGetSymbolicLinkStatus fs fp; return True }) (\ (_ :: IOException) -> return False) vCreateDirectory fs _ = eh fs "vCreateDirectory" vRemoveDirectory fs _ = eh fs "vRemoveDirectory" vRemoveFile fs _ = eh fs "vRemoveFile" vRenameFile fs _ _ = eh fs "vRenameFile" vRenameDirectory fs _ _ = eh fs "vRenameDirectory" vCreateSymbolicLink fs _ _ = eh fs "vCreateSymbolicLink" vReadSymbolicLink fs _ = eh fs "vReadSymbolicLink" vCreateLink fs _ _ = eh fs "vCreateLink" vGetSymbolicLinkStatus = vGetFileStatus
vGetCurrentDirectory :: HVFS a => a -> IO FilePath
vSetCurrentDirectory :: HVFS a => a -> FilePath -> IO ()
vGetDirectoryContents :: HVFS a => a -> FilePath -> IO [FilePath]
vDoesFileExist :: HVFS a => a -> FilePath -> IO Bool
vDoesDirectoryExist :: HVFS a => a -> FilePath -> IO Bool

-- | True if the file exists, regardless of what type it is. This is even
--   True if the given path is a broken symlink.
vDoesExist :: HVFS a => a -> FilePath -> IO Bool
vCreateDirectory :: HVFS a => a -> FilePath -> IO ()
vRemoveDirectory :: HVFS a => a -> FilePath -> IO ()
vRenameDirectory :: HVFS a => a -> FilePath -> FilePath -> IO ()
vRemoveFile :: HVFS a => a -> FilePath -> IO ()
vRenameFile :: HVFS a => a -> FilePath -> FilePath -> IO ()
vGetFileStatus :: HVFS a => a -> FilePath -> IO HVFSStatEncap
vGetSymbolicLinkStatus :: HVFS a => a -> FilePath -> IO HVFSStatEncap
vGetModificationTime :: HVFS a => a -> FilePath -> IO ClockTime

-- | Raise an error relating to actions on this class.
vRaiseError :: HVFS a => a -> IOErrorType -> String -> Maybe FilePath -> IO c
vCreateSymbolicLink :: HVFS a => a -> FilePath -> FilePath -> IO ()
vReadSymbolicLink :: HVFS a => a -> FilePath -> IO FilePath
vCreateLink :: HVFS a => a -> FilePath -> FilePath -> IO ()

-- | Evaluating types of files and information about them.
--   
--   This corresponds to the System.Posix.Types.FileStatus type, and
--   indeed, that is one instance of this class.
--   
--   Inplementators must, at minimum, implement <a>vIsDirectory</a> and
--   <a>vIsRegularFile</a>.
--   
--   Default implementations of everything else are provided, returning
--   reasonable values.
--   
--   A default implementation of this is not currently present on Windows.
class (Show a) => HVFSStat a where vDeviceID _ = 0 vFileID _ = 0 vFileMode x = if vIsDirectory x then 1877 else 420 vLinkCount _ = 1 vFileOwner _ = 0 vFileGroup _ = 0 vSpecialDeviceID _ = 0 vFileSize _ = 0 vAccessTime _ = 0 vModificationTime _ = 0 vStatusChangeTime _ = 0 vIsBlockDevice _ = False vIsCharacterDevice _ = False vIsNamedPipe _ = False vIsSymbolicLink _ = False vIsSocket _ = False
vDeviceID :: HVFSStat a => a -> DeviceID
vFileID :: HVFSStat a => a -> FileID

-- | Refers to file permissions, NOT the st_mode field from stat(2)
vFileMode :: HVFSStat a => a -> FileMode
vLinkCount :: HVFSStat a => a -> LinkCount
vFileOwner :: HVFSStat a => a -> UserID
vFileGroup :: HVFSStat a => a -> GroupID
vSpecialDeviceID :: HVFSStat a => a -> DeviceID
vFileSize :: HVFSStat a => a -> FileOffset
vAccessTime :: HVFSStat a => a -> EpochTime
vModificationTime :: HVFSStat a => a -> EpochTime
vStatusChangeTime :: HVFSStat a => a -> EpochTime
vIsBlockDevice :: HVFSStat a => a -> Bool
vIsCharacterDevice :: HVFSStat a => a -> Bool
vIsNamedPipe :: HVFSStat a => a -> Bool
vIsRegularFile :: HVFSStat a => a -> Bool
vIsDirectory :: HVFSStat a => a -> Bool
vIsSymbolicLink :: HVFSStat a => a -> Bool
vIsSocket :: HVFSStat a => a -> Bool

-- | Types that can open a HVIO object should be instances of this class.
--   You need only implement <a>vOpen</a>.
class HVFS a => HVFSOpenable a where vReadFile h fp = do { oe <- vOpen h fp ReadMode; withOpen oe (\ fh -> vGetContents fh) } vWriteFile h fp s = do { oe <- vOpen h fp WriteMode; withOpen oe (\ fh -> do { vPutStr fh s; vClose fh }) } vOpenBinaryFile = vOpen
vOpen :: HVFSOpenable a => a -> FilePath -> IOMode -> IO HVFSOpenEncap
vReadFile :: HVFSOpenable a => a -> FilePath -> IO String
vWriteFile :: HVFSOpenable a => a -> FilePath -> String -> IO ()
vOpenBinaryFile :: HVFSOpenable a => a -> FilePath -> IOMode -> IO HVFSOpenEncap

-- | Similar to <a>HVFSStatEncap</a>, but for <a>vOpen</a> result.
data HVFSOpenEncap
HVFSOpenEncap :: a -> HVFSOpenEncap

-- | Encapsulate a <a>HVFSStat</a> result. This is required due to Haskell
--   typing restrictions. You can get at it with:
--   
--   <pre>
--   case encap of
--      HVFSStatEncap x -&gt; -- now use x
--   </pre>
data HVFSStatEncap
HVFSStatEncap :: a -> HVFSStatEncap

-- | Convenience function for working with stat -- takes a stat result and
--   a function that uses it, and returns the result.
--   
--   Here is an example from the HVFS source:
--   
--   <pre>
--   vGetModificationTime fs fp = 
--      do s &lt;- vGetFileStatus fs fp
--         return $ epochToClockTime (withStat s vModificationTime)
--   </pre>
--   
--   See <a>epochToClockTime</a> for more information.
withStat :: HVFSStatEncap -> (forall a. HVFSStat a => a -> b) -> b

-- | Similar to <a>withStat</a>, but for the <a>vOpen</a> result.
withOpen :: HVFSOpenEncap -> (forall a. HVIO a => a -> b) -> b
data SystemFS
SystemFS :: SystemFS

-- | File and directory names are values of type <a>String</a>, whose
--   precise meaning is operating system dependent. Files can be opened,
--   yielding a handle which can then be used to operate on the contents of
--   that file.
type FilePath = String
type DeviceID = CDev
type FileID = CIno
type FileMode = CMode
type LinkCount = CNlink
type UserID = CUid
type GroupID = CGid
type FileOffset = COff
type EpochTime = CTime

-- | See <a>openFile</a>
data IOMode :: *
instance GHC.Show.Show System.IO.HVFS.SystemFS
instance GHC.Classes.Eq System.IO.HVFS.SystemFS
instance GHC.Show.Show System.Posix.Files.Common.FileStatus
instance System.IO.HVFS.HVFSStat System.Posix.Files.Common.FileStatus
instance System.IO.HVFS.HVFS System.IO.HVFS.SystemFS
instance System.IO.HVFS.HVFSOpenable System.IO.HVFS.SystemFS


-- | This module provides various helpful utilities for dealing with binary
--   input and output.
--   
--   You can use this module to deal with binary blocks of data as either
--   Strings or lists of Word8. The BinaryConvertible class provides this
--   abstraction.
--   
--   Wherever you see HVIO, you can transparently substite a regular
--   Handle. This module can work with any HVIO object, however. See
--   <a>System.IO.HVIO</a> for more details.
--   
--   Versions of MissingH prior 0.11.6 lacked the <a>BinaryConvertible</a>
--   class and worked only with Strings and Handles.
--   
--   Important note: /binary functions are not supported in all Haskell
--   implementations/. Do not import or use this module unless you know you
--   are using an implementation that supports them. At this time, here is
--   the support status:
--   
--   <ul>
--   <li>GHC 6.2 and above: yes</li>
--   <li>GHC 6.x, earlier versions: unknown</li>
--   <li>GHC 5.x: no</li>
--   <li>nhc98: no</li>
--   <li>Hugs: partial (maybe complete; needs more testing)</li>
--   </ul>
--   
--   Non-binary functions may be found in <a>System.IO</a>.
--   
--   See also: <a>System.IO.BlockIO</a>
--   
--   Written by John Goerzen, jgoerzen@complete.org
module System.IO.Binary

-- | Provides support for handling binary blocks with convenient types.
--   
--   This module provides implementations for Strings and for [Word8]
--   (lists of Word8s).
class (Eq a, Show a) => BinaryConvertible a
toBuf :: BinaryConvertible a => [a] -> (Ptr CChar -> IO c) -> IO c
fromBuf :: BinaryConvertible a => Int -> (Ptr CChar -> IO Int) -> IO [a]

-- | Copies everything from the input handle to the output handle using
--   binary blocks of the given size. This was once the following beautiful
--   implementation:
--   
--   <pre>
--   hBlockCopy bs hin hout = hBlockInteract bs hin hout id
--   </pre>
--   
--   (<a>id</a> is the built-in Haskell function that just returns whatever
--   is given to it)
--   
--   In more recent versions of MissingH, it uses a more optimized routine
--   that avoids ever having to convert the binary buffer at all.
hBlockCopy :: (HVIO a, HVIO b) => Int -> a -> b -> IO ()

-- | Copies from <a>stdin</a> to <a>stdout</a> using binary blocks of the
--   given size. An alias for <a>hBlockCopy</a> over <a>stdin</a> and
--   <a>stdout</a>
blockCopy :: Int -> IO ()

-- | Copies one filename to another in binary mode.
--   
--   Please note that the Unix permission bits on the output file cannot be
--   set due to a limitation of the Haskell <a>openBinaryFile</a> function.
--   Therefore, you may need to adjust those bits after the copy yourself.
--   
--   This function is implemented using <a>hBlockCopy</a> internally.
copyFileBlocksToFile :: Int -> FilePath -> FilePath -> IO ()

-- | As a wrapper around the standard function <a>hPutBuf</a>, this
--   function takes a standard Haskell <a>String</a> instead of the far
--   less convenient <tt>Ptr a</tt>. The entire contents of the string will
--   be written as a binary buffer using <a>hPutBuf</a>. The length of the
--   output will be the length of the passed String or list.
--   
--   If it helps, you can thing of this function as being of type
--   <tt>Handle -&gt; String -&gt; IO ()</tt>
hPutBufStr :: (HVIO a, BinaryConvertible b) => a -> [b] -> IO ()

-- | An alias for <a>hPutBufStr</a> <a>stdout</a>
putBufStr :: (BinaryConvertible b) => [b] -> IO ()

-- | Acts a wrapper around the standard function <a>hGetBuf</a>, this
--   function returns a standard Haskell String (or [Word8]) instead of
--   modifying a 'Ptr a' buffer. The length is the maximum length to read
--   and the semantice are the same as with <a>hGetBuf</a>; namely, the
--   empty string is returned with EOF is reached, and any given read may
--   read fewer bytes than the given length.
--   
--   (Actually, it's a wrapper around <a>vGetBuf</a>)
hGetBufStr :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [b]

-- | An alias for <a>hGetBufStr</a> <a>stdin</a>
getBufStr :: (BinaryConvertible b) => Int -> IO [b]

-- | Like <a>hGetBufStr</a>, but guarantees that it will only return fewer
--   than the requested number of bytes when EOF is encountered.
hFullGetBufStr :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [b]

-- | An alias for <a>hFullGetBufStr</a> <a>stdin</a>
fullGetBufStr :: BinaryConvertible b => Int -> IO [b]

-- | An alias for <a>hPutBlocks</a> <a>stdout</a> putBlocks ::
--   (BinaryConvertible b) =&gt; [[b]] -&gt; IO () putBlocks = hPutBlocks
--   stdout
--   
--   Returns a lazily-evaluated list of all blocks in the input file, as
--   read by <a>hGetBufStr</a>. There will be no 0-length block in this
--   list. The list simply ends at EOF.
hGetBlocks :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [[b]]

-- | An alias for <a>hGetBlocks</a> <a>stdin</a>
getBlocks :: BinaryConvertible b => Int -> IO [[b]]

-- | Same as <a>hGetBlocks</a>, but using <a>hFullGetBufStr</a> underneath.
hFullGetBlocks :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [[b]]

-- | An alias for <a>hFullGetBlocks</a> <a>stdin</a>
fullGetBlocks :: BinaryConvertible b => Int -> IO [[b]]

-- | Like the built-in <a>readFile</a>, but opens the file in binary
--   instead of text mode.
readBinaryFile :: FilePath -> IO String

-- | Like the built-in <a>writeFile</a>, but opens the file in binary
--   instead of text mode.
writeBinaryFile :: FilePath -> String -> IO ()

-- | Binary block-based interaction. This is useful for scenarios that take
--   binary blocks, manipulate them in some way, and then write them out.
--   Take a look at <a>hBlockCopy</a> for an example. The integer argument
--   is the size of input binary blocks. This function uses
--   <a>hGetBlocks</a> internally.
hBlockInteract :: (HVIO a, HVIO d, BinaryConvertible b, BinaryConvertible c) => Int -> a -> d -> ([[b]] -> [[c]]) -> IO ()

-- | An alias for <a>hBlockInteract</a> over <a>stdin</a> and <a>stdout</a>
blockInteract :: (BinaryConvertible b, BinaryConvertible c) => Int -> ([[b]] -> [[c]]) -> IO ()

-- | Same as <a>hBlockInteract</a>, but uses <a>hFullGetBlocks</a> instead
--   of <a>hGetBlocks</a> internally.
hFullBlockInteract :: (HVIO a, HVIO d, BinaryConvertible b, BinaryConvertible c) => Int -> a -> d -> ([[b]] -> [[c]]) -> IO ()

-- | An alias for <a>hFullBlockInteract</a> over <a>stdin</a> and
--   <a>stdout</a>
fullBlockInteract :: (BinaryConvertible b, BinaryConvertible c) => Int -> ([[b]] -> [[c]]) -> IO ()
instance System.IO.Binary.BinaryConvertible GHC.Types.Char
instance System.IO.Binary.BinaryConvertible GHC.Word.Word8


-- | This module provides various helpful utilities for dealing
--   filesystems.
--   
--   Written by John Goerzen, jgoerzen@complete.org
--   
--   To operate on your system's main filesystem, just pass SystemFS as the
--   first parameter to these functions.
module System.IO.HVFS.Utils

-- | Obtain a recursive listing of all files/directories beneath the
--   specified directory. The traversal is depth-first and the original
--   item is always present in the returned list.
--   
--   If the passed value is not a directory, the return value be only that
--   value.
--   
--   The "." and ".." entries are removed from the data returned.
recurseDir :: HVFS a => a -> FilePath -> IO [FilePath]

-- | Like <a>recurseDir</a>, but return the stat()
--   (System.Posix.Files.FileStatus) information with them. This is an
--   optimization if you will be statting files yourself later.
--   
--   The items are returned lazily.
--   
--   WARNING: do not change your current working directory until you have
--   consumed all the items. Doing so could cause strange effects.
--   
--   Alternatively, you may wish to pass an absolute path to this function.
recurseDirStat :: HVFS a => a -> FilePath -> IO [(FilePath, HVFSStatEncap)]

-- | Removes a file or a directory. If a directory, also removes all its
--   child files/directories.
recursiveRemove :: HVFS a => a -> FilePath -> IO ()

-- | Provide a result similar to the command ls -l over a directory.
--   
--   Known bug: setuid bit semantics are inexact compared with standard ls.
lsl :: HVFS a => a -> FilePath -> IO String
data SystemFS
SystemFS :: SystemFS


module System.IO.Utils

-- | Copies from one handle to another in raw mode (using hGetContents).
hCopy :: (HVIO a, HVIO b) => a -> b -> IO ()

-- | Copies from one handle to another in raw mode (using hGetContents).
--   Takes a function to provide progress updates to the user.
hCopyProgress :: (HVIO b, HVIO c, Integral a) => b -> c -> (Maybe a -> Integer -> Bool -> IO ()) -> Int -> Maybe a -> IO Integer

-- | Copies from one handle to another in text mode (with lines). Like
--   <tt>hBlockCopy</tt>, this implementation is nice:
--   
--   <pre>
--   hLineCopy hin hout = hLineInteract hin hout id
--   </pre>
hLineCopy :: (HVIO a, HVIO b) => a -> b -> IO ()

-- | Copies from <a>stdin</a> to <a>stdout</a> using lines. An alias for
--   <a>hLineCopy</a> over <a>stdin</a> and <a>stdout</a>.
lineCopy :: IO ()

-- | Copies one filename to another in text mode.
--   
--   Please note that the Unix permission bits are set at a default; you
--   may need to adjust them after the copy yourself.
--   
--   This function is implemented using <a>hLineCopy</a> internally.
copyFileLinesToFile :: FilePath -> FilePath -> IO ()

-- | Given a list of strings, output a line containing each item, adding
--   newlines as appropriate. The list is not expected to have newlines
--   already.
hPutStrLns :: HVIO a => a -> [String] -> IO ()

-- | Given a handle, returns a list of all the lines in that handle. Thanks
--   to lazy evaluation, this list does not have to be read all at once.
--   
--   Combined with <a>hPutStrLns</a>, this can make a powerful way to
--   develop filters. See the <a>lineInteract</a> function for more on that
--   concept.
--   
--   Example:
--   
--   <pre>
--   main = do
--          l &lt;- hGetLines stdin
--          hPutStrLns stdout $ filter (startswith "1") l
--   </pre>
hGetLines :: HVIO a => a -> IO [String]

-- | This is similar to the built-in <a>interact</a>, but works on any
--   handle, not just stdin and stdout.
--   
--   In other words:
--   
--   <pre>
--   interact = hInteract stdin stdout
--   </pre>
hInteract :: (HVIO a, HVIO b) => a -> b -> (String -> String) -> IO ()

-- | Line-based interaction over arbitrary handles. This is similar to
--   wrapping hInteract with <a>lines</a> and <a>unlines</a>.
--   
--   One could view this function like this:
--   
--   <pre>
--   hLineInteract finput foutput func =
--       let newf = unlines . func . lines in
--           hInteract finput foutput newf
--   </pre>
--   
--   Though the actual implementation is this for efficiency:
--   
--   <pre>
--   hLineInteract finput foutput func =
--       do
--       lines &lt;- hGetLines finput
--       hPutStrLns foutput (func lines)
--   </pre>
hLineInteract :: (HVIO a, HVIO b) => a -> b -> ([String] -> [String]) -> IO ()

-- | Line-based interaction. This is similar to wrapping your interact
--   functions with <a>lines</a> and <a>unlines</a>. This equality holds:
--   
--   <pre>
--   lineInteract = hLineInteract stdin stdout
--   </pre>
--   
--   Here's an example:
--   
--   <pre>
--   main = lineInteract (filter (startswith "1"))
--   </pre>
--   
--   This will act as a simple version of grep -- all lines that start with
--   1 will be displayed; all others will be ignored.
lineInteract :: ([String] -> [String]) -> IO ()

-- | Applies a given function to every item in a list, and returns the new
--   list. Unlike the system's mapM, items are evaluated lazily.
lazyMapM :: (a -> IO b) -> [a] -> IO [b]

-- | Sets stdin and stdout to be block-buffered. This can save a huge
--   amount of system resources since far fewer syscalls are made, and can
--   make programs run much faster.
optimizeForBatch :: IO ()

-- | Sets stdin and stdout to be line-buffered. This saves resources on
--   stdout, but not many on stdin, since it it still looking for newlines.
optimizeForInteraction :: IO ()


-- | This module provides various helpful utilities for dealing with lists.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Data.List.Utils

-- | Merge two sorted lists into a single, sorted whole.
--   
--   Example:
--   
--   <pre>
--   merge [1,3,5] [1,2,4,6] -&gt; [1,1,2,3,4,5,6]
--   </pre>
--   
--   QuickCheck test property:
--   
--   prop_merge xs ys = merge (sort xs) (sort ys) == sort (xs ++ ys) where
--   types = xs :: [Int]
merge :: (Ord a) => [a] -> [a] -> [a]

-- | Merge two sorted lists using into a single, sorted whole, allowing the
--   programmer to specify the comparison function.
--   
--   QuickCheck test property:
--   
--   prop_mergeBy xs ys = mergeBy cmp (sortBy cmp xs) (sortBy cmp ys) ==
--   sortBy cmp (xs ++ ys) where types = xs :: [ (Int, Int) ] cmp (x1,_)
--   (x2,_) = compare x1 x2
mergeBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a]

-- | Returns true if the given list starts with the specified elements;
--   false otherwise. (This is an alias for "Data.List.isPrefixOf".)
--   
--   Example:
--   
--   <pre>
--   startswith "He" "Hello" -&gt; True
--   </pre>
startswith :: Eq a => [a] -> [a] -> Bool

-- | Returns true if the given list ends with the specified elements; false
--   otherwise. (This is an alias for "Data.List.isSuffixOf".)
--   
--   Example:
--   
--   <pre>
--   endswith "lo" "Hello" -&gt; True
--   </pre>
endswith :: Eq a => [a] -> [a] -> Bool

-- | Returns true if the given parameter is a sublist of the given list;
--   false otherwise.
--   
--   Example:
--   
--   <pre>
--   contains "Haskell" "I really like Haskell." -&gt; True
--   contains "Haskell" "OCaml is great." -&gt; False
--   </pre>
--   
--   This function was submitted to GHC and was applied as
--   <a>isInfixOf</a>. This function therefore is deprecated and will be
--   removed in future versions.

-- | <i>Deprecated: Use Data.List.isInfixOf, will be removed in MissingH
--   1.1.0</i>
contains :: Eq a => [a] -> [a] -> Bool

-- | Returns true if the given list contains any of the elements in the
--   search list.
hasAny :: Eq a => [a] -> [a] -> Bool

-- | Adds the specified (key, value) pair to the given list, removing any
--   existing pair with the same key already present.
addToAL :: Eq key => [(key, elt)] -> key -> elt -> [(key, elt)]

-- | Removes all (key, value) pairs from the given list where the key
--   matches the given one.
delFromAL :: Eq key => [(key, a)] -> key -> [(key, a)]

-- | Flips an association list. Converts (key1, val), (key2, val) pairs to
--   (val, [key1, key2]).
flipAL :: (Eq key, Eq val) => [(key, val)] -> [(val, [key])]

-- | Returns the keys that comprise the (key, value) pairs of the given AL.
--   
--   Same as:
--   
--   <pre>
--   map fst
--   </pre>
keysAL :: [(key, a)] -> [key]

-- | Returns the values the comprise the (key, value) pairs of the given
--   AL.
--   
--   Same as:
--   
--   <pre>
--   map snd
--   </pre>
valuesAL :: [(a, value)] -> [value]

-- | Indicates whether or not the given key is in the AL.
hasKeyAL :: Eq a => a -> [(a, b)] -> Bool

-- | Converts an association list to a string. The string will have one
--   pair per line, with the key and value both represented as a Haskell
--   string.
--   
--   This function is designed to work with [(String, String)] association
--   lists, but may work with other types as well.
strFromAL :: (Show a, Show b) => [(a, b)] -> String

-- | The inverse of <a>strFromAL</a>, this function reads a string and
--   outputs the appropriate association list.
--   
--   Like <a>strFromAL</a>, this is designed to work with [(String,
--   String)] association lists but may also work with other objects with
--   simple representations.
strToAL :: (Read a, Read b) => String -> [(a, b)]

-- | Given a delimiter and a list (or string), split into components.
--   
--   Example:
--   
--   <pre>
--   split "," "foo,bar,,baz," -&gt; ["foo", "bar", "", "baz", ""]
--   </pre>
--   
--   <pre>
--   split "ba" ",foo,bar,,baz," -&gt; [",foo,","r,,","z,"]
--   </pre>
split :: Eq a => [a] -> [a] -> [[a]]

-- | Given a delimiter and a list of items (or strings), join the items by
--   using the delimiter.
--   
--   Example:
--   
--   <pre>
--   join "|" ["foo", "bar", "baz"] -&gt; "foo|bar|baz"
--   </pre>
join :: [a] -> [[a]] -> [a]

-- | Given a list and a replacement list, replaces each occurance of the
--   search list with the replacement list in the operation list.
--   
--   Example:
--   
--   <pre>
--   replace "," "." "127,0,0,1" -&gt; "127.0.0.1"
--   </pre>
--   
--   This could logically be thought of as:
--   
--   <pre>
--   replace old new l = join new . split old $ l
--   </pre>
replace :: Eq a => [a] -> [a] -> [a] -> [a]

-- | Like <a>join</a>, but works with a list of anything showable,
--   converting it to a String.
--   
--   Examples:
--   
--   <pre>
--   genericJoin ", " [1, 2, 3, 4] -&gt; "1, 2, 3, 4"
--   genericJoin "|" ["foo", "bar", "baz"] -&gt; "\"foo\"|\"bar\"|\"baz\""
--   </pre>
genericJoin :: Show a => String -> [a] -> String

-- | Similar to Data.List.takeWhile, takes elements while the func is true.
--   The function is given the remainder of the list to examine.
takeWhileList :: ([a] -> Bool) -> [a] -> [a]

-- | Similar to Data.List.dropWhile, drops elements while the func is true.
--   The function is given the remainder of the list to examine.
dropWhileList :: ([a] -> Bool) -> [a] -> [a]

-- | Similar to Data.List.span, but performs the test on the entire
--   remaining list instead of just one element.
--   
--   <tt>spanList p xs</tt> is the same as <tt>(takeWhileList p xs,
--   dropWhileList p xs)</tt>
spanList :: ([a] -> Bool) -> [a] -> ([a], [a])

-- | Similar to Data.List.break, but performs the test on the entire
--   remaining list instead of just one element.
breakList :: ([a] -> Bool) -> [a] -> ([a], [a])

-- | The type used for functions for <a>wholeMap</a>. See <a>wholeMap</a>
--   for details.
newtype WholeFunc a b
WholeFunc :: ([a] -> (WholeFunc a b, [a], [b])) -> WholeFunc a b

-- | This is an enhanced version of the concatMap or map functions in
--   Data.List.
--   
--   Unlike those functions, this one:
--   
--   <ul>
--   <li>Can consume a varying number of elements from the input list
--   during each iteration</li>
--   <li>Can arbitrarily decide when to stop processing data</li>
--   <li>Can return a varying number of elements to insert into the output
--   list</li>
--   <li>Can actually switch processing functions mid-stream</li>
--   <li>Is not even restricted to processing the input list intact</li>
--   </ul>
--   
--   The function used by wholeMap, of type <a>WholeFunc</a>, is repeatedly
--   called with the input list. The function returns three things: the
--   function to call for the next iteration (if any), what remains of the
--   input list, and the list of output elements generated during this
--   iteration. The return value of <a>wholeMap</a> is the concatenation of
--   the output element lists from all iterations.
--   
--   Processing stops when the remaining input list is empty. An example of
--   a <a>WholeFunc</a> is <a>fixedWidth</a>.
wholeMap :: WholeFunc a b -> [a] -> [b]

-- | A parser designed to process fixed-width input fields. Use it with
--   <a>wholeMap</a>.
--   
--   The Int list passed to this function is the list of the field widths
--   desired from the input. The result is a list of those widths, if
--   possible. If any of the input remains after processing this list, it
--   is added on as the final element in the result list. If the input is
--   less than the sum of the requested widths, then the result list will
--   be short the appropriate number of elements, and its final element may
--   be shorter than requested.
--   
--   Examples:
--   
--   <pre>
--   wholeMap (fixedWidth [1, 2, 3]) "1234567890"
--    --&gt; ["1","23","456","7890"]
--   wholeMap (fixedWidth (repeat 2)) "123456789"
--    --&gt; ["12","34","56","78","9"]
--   wholeMap (fixedWidth []) "123456789"
--    --&gt; ["123456789"]
--   wholeMap (fixedWidth [5, 3, 6, 1]) "Hello, This is a test."
--    --&gt; ["Hello",", T","his is"," ","a test."]
--   </pre>
fixedWidth :: [Int] -> WholeFunc a [a]

-- | Helps you pick out fixed-width components from a list.
--   
--   Example:
--   
--   <pre>
--   conv :: String -&gt; (String,String)
--   conv = runState $
--           do f3 &lt;- grab 3
--              n2 &lt;- grab 2
--              return $ f3 ++ "," ++ n2
--   
--   main = print $ conv "TestIng"
--   </pre>
--   
--   Prints:
--   
--   <pre>
--   ("Tes,tI","ng")
--   </pre>
grab :: Int -> State [a] [a]

-- | Returns a count of the number of times the given element occured in
--   the given list.
countElem :: Eq a => a -> [a] -> Int

-- | Returns the rightmost index of the given element in the given list.
elemRIndex :: Eq a => a -> [a] -> Maybe Int

-- | Like elemRIndex, but returns -1 if there is nothing found.
alwaysElemRIndex :: Eq a => a -> [a] -> Int

-- | Forces the evaluation of the entire list.
seqList :: [a] -> [a]

-- | Similar to Data.List.elemIndex. Instead of looking for one element in
--   a list, this function looks for the first occurance of a sublist in
--   the list, and returns the index of the first element of that
--   occurance. If there is no such list, returns Nothing.
--   
--   If the list to look for is the empty list, will return Just 0
--   regardless of the content of the list to search.
--   
--   Examples:
--   
--   <pre>
--   subIndex "foo" "asdfoobar" -&gt; Just 3
--   subIndex "foo" [] -&gt; Nothing
--   subIndex "" [] -&gt; Just 0
--   subIndex "" "asdf" -&gt; Just 0
--   subIndex "test" "asdftestbartest" -&gt; Just 4
--   subIndex [(1::Int), 2] [0, 5, 3, 2, 1, 2, 4] -&gt; Just 4
--   </pre>
subIndex :: Eq a => [a] -> [a] -> Maybe Int

-- | Given a list, returns a new list with all duplicate elements removed.
--   For example:
--   
--   <pre>
--   uniq "Mississippi" -&gt; "Misp"
--   </pre>
--   
--   You should not rely on this function necessarily preserving order,
--   though the current implementation happens to.
--   
--   This function is not compatible with infinite lists.
--   
--   This is presently an alias for Data.List.nub
uniq :: Eq a => [a] -> [a]


-- | This module provides various helpful utilities for dealing with
--   Data.Maps.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Data.Map.Utils

-- | Flips a Map. See <a>flipAL</a> for more on the similar function for
--   lists.
flipM :: (Ord key, Ord val) => Map key val -> Map val [key]

-- | Returns a list of all keys in the Map whose value matches the
--   parameter. If the value does not occur in the Map, the empty list is
--   returned.
flippedLookupM :: (Ord val, Ord key) => val -> Map key val -> [key]

-- | Performs a lookup, and raises an exception (with an error message
--   prepended with the given string) if the key could not be found.
forceLookupM :: (Show key, Ord key) => String -> key -> Map key elt -> elt

-- | Converts a String into a String, String Map. See <a>strToAL</a> for
--   more on the similar function for association lists.
--   
--   This implementation is simple:
--   
--   <pre>
--   strToM = Data.Map.fromList . strToAL
--   </pre>
--   
--   This function is designed to work with Map String String objects, but
--   may work with other key/value combinations if they have simple
--   representations.
strToM :: (Read a, Read b, Ord a) => String -> Map a b

-- | Converts a String, String Map into a string representation. See
--   <a>strFromAL</a> for more on the similar function for association
--   lists. This implementation is simple:
--   
--   <pre>
--   strFromM = strFromAL . Data.Map.toList
--   </pre>
--   
--   This function is designed to work with Map String String objects, but
--   may also work with other objects with simple representations.
strFromM :: (Show a, Show b, Ord a) => Map a b -> String


-- | This module provides various helpful utilities for dealing with path
--   and file names, directories, and related support.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module System.Path

-- | Splits a pathname into a tuple representing the root of the name and
--   the extension. The extension is considered to be all characters from
--   the last dot after the last slash to the end. Either returned string
--   may be empty.
splitExt :: String -> (String, String)

-- | Make an absolute, normalized version of a path with all double
--   slashes, dot, and dotdot entries removed.
--   
--   The first parameter is the base for the absolut calculation; in many
--   cases, it would correspond to the current working directory.
--   
--   The second parameter is the pathname to transform. If it is already
--   absolute, the first parameter is ignored.
--   
--   Nothing may be returned if there's an error; for instance, too many
--   <tt>..</tt> entries for the given path.
absNormPath :: String -> String -> Maybe String

-- | Like absNormPath, but returns Nothing if the generated result is not
--   the passed base path or a subdirectory thereof.
secureAbsNormPath :: String -> String -> Maybe String

-- | Obtain a recursive listing of all files/directories beneath the
--   specified directory. The traversal is depth-first and the original
--   item is always present in the returned list.
--   
--   If the passed value is not a directory, the return value be only that
--   value.
--   
--   The "." and ".." entries are removed from the data returned.
recurseDir :: HVFS a => a -> FilePath -> IO [FilePath]

-- | Like <a>recurseDir</a>, but return the stat()
--   (System.Posix.Files.FileStatus) information with them. This is an
--   optimization if you will be statting files yourself later.
--   
--   The items are returned lazily.
--   
--   WARNING: do not change your current working directory until you have
--   consumed all the items. Doing so could cause strange effects.
--   
--   Alternatively, you may wish to pass an absolute path to this function.
recurseDirStat :: HVFS a => a -> FilePath -> IO [(FilePath, HVFSStatEncap)]

-- | Removes a file or a directory. If a directory, also removes all its
--   child files/directories.
recursiveRemove :: HVFS a => a -> FilePath -> IO ()

-- | Changes the current working directory to the given path, executes the
--   given I/O action, then changes back to the original directory, even if
--   the I/O action raised an exception.
bracketCWD :: FilePath -> IO a -> IO a

-- | Creates a temporary directory for your use.
--   
--   The passed string should be a template suitable for mkstemp; that is,
--   end with <tt>"XXXXXX"</tt>.
--   
--   Your string should probably start with the value returned from
--   System.Directory.getTemporaryDirectory.
--   
--   The name of the directory created will be returned.
mktmpdir :: String -> IO String

-- | Creates a temporary directory for your use via <a>mktmpdir</a>, runs
--   the specified action (passing in the directory name), then removes the
--   directory and all its contents when the action completes (or raises an
--   exception.
brackettmpdir :: String -> (String -> IO a) -> IO a

-- | Runs the given I/O action with the CWD set to the given tmp dir,
--   removing the tmp dir and changing CWD back afterwards, even if there
--   was an exception.
brackettmpdirCWD :: String -> IO a -> IO a


-- | Utilities for creating instances of the items defined in
--   <a>System.IO.HVFS</a>.
module System.IO.HVFS.InstanceHelpers

-- | A simple <a>System.IO.HVFS.HVFSStat</a> class that assumes that
--   everything is either a file or a directory.
data SimpleStat
SimpleStat :: Bool -> FileOffset -> SimpleStat

-- | True if file, False if directory
[isFile] :: SimpleStat -> Bool

-- | Set to 0 if unknown or a directory
[fileSize] :: SimpleStat -> FileOffset

-- | An in-memory read/write filesystem. Think of it as a dynamically
--   resizable ramdisk written in Haskell.
data MemoryVFS

-- | Create a new <a>MemoryVFS</a> object from an existing tree. An empty
--   filesystem may be created by using <tt>[]</tt> for the parameter.
newMemoryVFS :: [MemoryNode] -> IO MemoryVFS

-- | Create a new <a>MemoryVFS</a> object using an IORef to an existing
--   tree.
newMemoryVFSRef :: IORef [MemoryNode] -> IO MemoryVFS

-- | The basic node of a <a>MemoryVFS</a>. The String corresponds to the
--   filename, and the entry to the contents.
type MemoryNode = (String, MemoryEntry)

-- | The content of a file or directory in a <a>MemoryVFS</a>.
data MemoryEntry
MemoryDirectory :: [MemoryNode] -> MemoryEntry
MemoryFile :: String -> MemoryEntry

-- | Similar to <a>NameManip</a> but the first element won't be <tt>/</tt>.
--   
--   <pre>
--   nice_slice "/" -&gt; []
--   nice_slice "/foo/bar" -&gt; ["foo", "bar"]
--   </pre>
nice_slice :: String -> [String]

-- | Gets a full path, after investigating the cwd.
getFullPath :: HVFS a => a -> String -> IO String

-- | Gets the full path via <a>getFullPath</a>, then splits it via
--   <a>nice_slice</a>.
getFullSlice :: HVFS a => a -> String -> IO [String]
instance GHC.Show.Show System.IO.HVFS.InstanceHelpers.MemoryEntry
instance GHC.Classes.Eq System.IO.HVFS.InstanceHelpers.MemoryEntry
instance GHC.Classes.Eq System.IO.HVFS.InstanceHelpers.SimpleStat
instance GHC.Show.Show System.IO.HVFS.InstanceHelpers.SimpleStat
instance System.IO.HVFS.HVFSStat System.IO.HVFS.InstanceHelpers.SimpleStat
instance GHC.Show.Show System.IO.HVFS.InstanceHelpers.MemoryVFS
instance System.IO.HVFS.HVFS System.IO.HVFS.InstanceHelpers.MemoryVFS
instance System.IO.HVFS.HVFSOpenable System.IO.HVFS.InstanceHelpers.MemoryVFS


-- | Support for combining different HVFS modules together
--   
--   Copyright (c) 2004-2005 John Goerzen, jgoerzen@complete.org
module System.IO.HVFS.Combinators

-- | Restrict access to the underlying filesystem to be strictly read-only.
--   Any write-type operations will cause an error.
--   
--   No constructor is required; just say <tt>HVFSReadOnly fs</tt> to make
--   a new read-only wrapper around the <a>HVFS</a> instance <tt>fs</tt>.
data HVFS a => HVFSReadOnly a
HVFSReadOnly :: a -> HVFSReadOnly a

-- | Access a subdirectory of a real filesystem as if it was the root of
--   that filesystem.
data HVFS a => HVFSChroot a

-- | Create a new <a>HVFSChroot</a> object.
newHVFSChroot :: HVFS a => a -> FilePath -> IO (HVFSChroot a)
instance System.IO.HVFS.HVFS a => GHC.Show.Show (System.IO.HVFS.Combinators.HVFSChroot a)
instance (GHC.Classes.Eq a, System.IO.HVFS.HVFS a) => GHC.Classes.Eq (System.IO.HVFS.Combinators.HVFSChroot a)
instance System.IO.HVFS.HVFS a => GHC.Show.Show (System.IO.HVFS.Combinators.HVFSReadOnly a)
instance (GHC.Classes.Eq a, System.IO.HVFS.HVFS a) => GHC.Classes.Eq (System.IO.HVFS.Combinators.HVFSReadOnly a)
instance System.IO.HVFS.HVFS a => System.IO.HVFS.HVFS (System.IO.HVFS.Combinators.HVFSReadOnly a)
instance System.IO.HVFS.HVFSOpenable a => System.IO.HVFS.HVFSOpenable (System.IO.HVFS.Combinators.HVFSReadOnly a)
instance System.IO.HVFS.HVFS a => System.IO.HVFS.HVFS (System.IO.HVFS.Combinators.HVFSChroot a)
instance System.IO.HVFS.HVFSOpenable a => System.IO.HVFS.HVFSOpenable (System.IO.HVFS.Combinators.HVFSChroot a)


-- | Utilities for guessing MIME types of files.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Data.MIME.Types

-- | Default MIME type data to use
defaultmtd :: MIMETypeData

-- | Read the given mime.types file and add it to an existing object.
--   Returns new object.
readMIMETypes :: MIMETypeData -> Bool -> FilePath -> IO MIMETypeData

-- | Load a mime.types file from an already-open handle.
hReadMIMETypes :: MIMETypeData -> Bool -> Handle -> IO MIMETypeData

-- | Read the system's default mime.types files, and add the data contained
--   therein to the passed object, then return the new one.
readSystemMIMETypes :: MIMETypeData -> IO MIMETypeData

-- | Return value from guessing a file's type.
--   
--   The first element of the tuple gives the MIME type. It is Nothing if
--   no suitable type could be found.
--   
--   The second element gives the encoding. It is Nothing if there was no
--   particular encoding for the file, or if no encoding could be found.
type MIMEResults = (Maybe String, Maybe String)
data MIMETypeData
MIMETypeData :: Map String String -> Map String String -> Map String String -> Map String String -> MIMETypeData

-- | A mapping used to expand common suffixes into equivolent,
--   better-parsed versions. For instance, ".tgz" would expand into
--   ".tar.gz".
[suffixMap] :: MIMETypeData -> Map String String

-- | A mapping used to determine the encoding of a file. This is used, for
--   instance, to map ".gz" to "gzip".
[encodingsMap] :: MIMETypeData -> Map String String

-- | A mapping used to map extensions to MIME types.
[typesMap] :: MIMETypeData -> Map String String

-- | A mapping used to augment the <a>typesMap</a> when non-strict lookups
--   are used.
[commonTypesMap] :: MIMETypeData -> Map String String

-- | Guess the type of a file given a filename or URL. The file is not
--   opened; only the name is considered.
guessType :: MIMETypeData -> Bool -> String -> MIMEResults

-- | Guess the extension of a file based on its MIME type. The return value
--   includes the leading dot.
--   
--   Returns Nothing if no extension could be found.
--   
--   In the event that multiple possible extensions are available, one of
--   them will be picked and returned. The logic to select one of these
--   should be considered undefined.
guessExtension :: MIMETypeData -> Bool -> String -> Maybe String

-- | Similar to <a>guessExtension</a>, but returns a list of all possible
--   matching extensions, or the empty list if there are no matches.
guessAllExtensions :: MIMETypeData -> Bool -> String -> [String]


-- | This module provides various helpful utilities for dealing with
--   strings.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Data.String.Utils

-- | Removes any whitespace characters that are present at the start or end
--   of a string. Does not alter the internal contents of a string. If no
--   whitespace characters are present at the start or end of a string,
--   returns the original string unmodified. Safe to use on any string.
--   
--   Note that this may differ from some other similar functions from other
--   authors in that:
--   
--   <ol>
--   <li>If multiple whitespace characters are present all in a row, they
--   are all removed;</li>
--   <li>If no whitespace characters are present, nothing is done.</li>
--   </ol>
strip :: String -> String

-- | Same as <a>strip</a>, but applies only to the left side of the string.
lstrip :: String -> String

-- | Same as <a>strip</a>, but applies only to the right side of the
--   string.
rstrip :: String -> String

-- | Returns true if the given list starts with the specified elements;
--   false otherwise. (This is an alias for "Data.List.isPrefixOf".)
--   
--   Example:
--   
--   <pre>
--   startswith "He" "Hello" -&gt; True
--   </pre>
startswith :: Eq a => [a] -> [a] -> Bool

-- | Returns true if the given list ends with the specified elements; false
--   otherwise. (This is an alias for "Data.List.isSuffixOf".)
--   
--   Example:
--   
--   <pre>
--   endswith "lo" "Hello" -&gt; True
--   </pre>
endswith :: Eq a => [a] -> [a] -> Bool

-- | Given a delimiter and a list of items (or strings), join the items by
--   using the delimiter.
--   
--   Example:
--   
--   <pre>
--   join "|" ["foo", "bar", "baz"] -&gt; "foo|bar|baz"
--   </pre>
join :: [a] -> [[a]] -> [a]

-- | Given a delimiter and a list (or string), split into components.
--   
--   Example:
--   
--   <pre>
--   split "," "foo,bar,,baz," -&gt; ["foo", "bar", "", "baz", ""]
--   </pre>
--   
--   <pre>
--   split "ba" ",foo,bar,,baz," -&gt; [",foo,","r,,","z,"]
--   </pre>
split :: Eq a => [a] -> [a] -> [[a]]

-- | Splits a string around whitespace. Empty elements in the result list
--   are automatically removed.
splitWs :: String -> [String]

-- | Given a list and a replacement list, replaces each occurance of the
--   search list with the replacement list in the operation list.
--   
--   Example:
--   
--   <pre>
--   replace "," "." "127,0,0,1" -&gt; "127.0.0.1"
--   </pre>
--   
--   This could logically be thought of as:
--   
--   <pre>
--   replace old new l = join new . split old $ l
--   </pre>
replace :: Eq a => [a] -> [a] -> [a] -> [a]

-- | Escape all characters in the input pattern that are not alphanumeric.
--   
--   Does not make special allowances for NULL, which isn't valid in a
--   Haskell regular expression pattern.
escapeRe :: String -> String

-- | Attempts to parse a value from the front of the string.
maybeRead :: Read a => String -> Maybe a


-- | Tool for maintaining a status bar, supporting multiple simultaneous
--   tasks, as a layer atop <a>Data.Progress.Tracker</a>.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module Data.Progress.Meter
type ProgressMeter = MVar ProgressMeterR

-- | Set up a new status bar using defaults:
--   
--   <ul>
--   <li>The given tracker</li>
--   <li>Width 80</li>
--   <li>Data.Quantity.renderNums binaryOpts 1</li>
--   <li>Unit inticator <tt><a>B</a></tt></li>
--   </ul>
simpleNewMeter :: Progress -> IO ProgressMeter

-- | Set up a new status bar.
newMeter :: Progress -> String -> Int -> ([Integer] -> [String]) -> IO ProgressMeter

-- | Adjust the list of components of this <a>ProgressMeter</a>.
setComponents :: ProgressMeter -> [Progress] -> IO ()

-- | Add a new component to the list of components.
addComponent :: ProgressMeter -> Progress -> IO ()

-- | Remove a component by name.
removeComponent :: ProgressMeter -> String -> IO ()

-- | Adjusts the width of this <a>ProgressMeter</a>.
setWidth :: ProgressMeter -> Int -> IO ()

-- | Render the current status.
renderMeter :: ProgressMeter -> IO String

-- | Like renderMeter, but prints it to the screen instead of returning it.
--   
--   This function will output CR, then the meter.
--   
--   Pass stdout as the handle for regular display to the screen.
displayMeter :: Handle -> ProgressMeter -> IO ()

-- | Clears the meter -- outputs CR, spaces equal to the width - 1, then
--   another CR.
--   
--   Pass stdout as the handle for regular display to the screen.
clearMeter :: Handle -> ProgressMeter -> IO ()

-- | Clears the meter, writes the given string, then restores the meter.
--   The string is assumed to contain a trailing newline.
--   
--   Pass stdout as the handle for regular display to the screen.
writeMeterString :: Handle -> ProgressMeter -> String -> IO ()

-- | Starts a thread that updates the meter every n seconds by calling the
--   specified function. Note: <tt>displayMeter stdout</tt> is an ideal
--   function here.
--   
--   Save this threadID and use it later to call
--   <tt>stopAutoDisplayMeter</tt>.
autoDisplayMeter :: ProgressMeter -> Int -> (ProgressMeter -> IO ()) -> IO ThreadId

-- | Stops the specified meter from displaying.
--   
--   You should probably call <a>clearMeter</a> after a call to this.
killAutoDisplayMeter :: ProgressMeter -> ThreadId -> IO ()


-- | Matching filenames with wildcards. See also <a>System.Path.Glob</a>
--   for support for generating lists of files based on wildcards.
--   
--   Inspired by fnmatch.py, part of the Python standard library.
--   
--   Written by John Goerzen, jgoerzen@complete.org
--   
--   The input wildcard for functions in this module is expected to be in
--   the standard style of Posix shells.
--   
--   That is:
--   
--   <pre>
--   ? matches exactly one character
--   \* matches zero or more characters
--   [list] matches any character in list
--   [!list] matches any character not in the list
--   </pre>
--   
--   The returned regular expression will always end in $ but never begins
--   with ^, making it suitable for appending to the end of paths. If you
--   want to match a given filename directly, you should prepend the ^
--   character to the returned value from this function.
--   
--   Please note:
--   
--   <ul>
--   <li>Neither the path separator (the slash or backslash) nor the period
--   carry any special meaning for the functions in this module. That is,
--   <tt>*</tt> will match <tt>/</tt> in a filename. If this is not the
--   behavior you want, you probably want <a>System.Path.Glob</a> instead
--   of this module.</li>
--   <li>Unlike the Unix shell, filenames that begin with a period are not
--   ignored by this module. That is, <tt>*.txt</tt> will match
--   <tt>.test.txt</tt>.</li>
--   <li>This module does not current permit escaping of special
--   characters.</li>
--   </ul>
module System.Path.WildMatch

-- | Check the given name against the given pattern, being case-sensitive.
--   
--   The given pattern is forced to match the given name starting at the
--   beginning.
wildCheckCase :: String -> String -> Bool

-- | Convert a wildcard to an (uncompiled) regular expression.
wildToRegex :: String -> String


-- | Functions for expanding wildcards, filenames, and pathnames.
--   
--   For information on the metacharacters recognized, please see the notes
--   in <a>System.Path.WildMatch</a>.
module System.Path.Glob

-- | Takes a pattern. Returns a list of names that match that pattern. The
--   pattern is evaluated by <a>System.Path.WildMatch</a>. This function
--   does not perform tilde or environment variable expansion.
--   
--   Filenames that begin with a dot are not included in the result set
--   unless that component of the pattern also begins with a dot.
--   
--   In MissingH, this function is defined as:
--   
--   <pre>
--   glob = vGlob SystemFS
--   </pre>
glob :: FilePath -> IO [FilePath]

-- | Like <a>glob</a>, but works on both the system ("real") and HVFS
--   virtual filesystems.
vGlob :: HVFS a => a -> FilePath -> IO [FilePath]


-- | This module provides various helpful utilities for dealing with Debian
--   files and programs.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module System.Debian.ControlParser

-- | Main parser for the control file
control :: CharParser a [(String, String)]

-- | Dependency parser.
--   
--   Returns (package name, Maybe version, arch list)
--   
--   version is (operator, operand)
depPart :: CharParser a (String, Maybe (String, String), [String])