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

-- | Library to mix shell scripting with Haskell programs
--   
--   HSH is designed to let you mix and match shell expressions with
--   Haskell programs. With HSH, it is possible to easily run shell
--   commands, capture their output or provide their input, and pipe them
--   to and from other shell commands and arbitrary Haskell functions at
--   will. Category: System
@package HSH
@version 2.1.0

-- | Copyright (c) 2006-2009 John Goerzen, jgoerzen@complete.org
module HSH.Channel

-- | The main type for communicating between commands. All are expected to
--   be lazy.
data Channel
ChanString :: String -> Channel
ChanBSL :: ByteString -> Channel
ChanHandle :: Handle -> Channel
chanAsString :: Channel -> IO String
chanAsBSL :: Channel -> IO ByteString
chanAsBS :: Channel -> IO ByteString

-- | Writes the Channel to the given Handle. If the first parameter is
--   True, do this in a separate thread and close the handle afterwards.
chanToHandle :: Bool -> Channel -> Handle -> IO ()
class Channelizable a
toChannel :: Channelizable a => a -> Channel
instance [overlap ok] Channelizable ByteString
instance [overlap ok] Channelizable Handle
instance [overlap ok] Channelizable ByteString
instance [overlap ok] Channelizable String

-- | Copyright (c) 2006-2009 John Goerzen, jgoerzen@complete.org
module HSH.Command

-- | Type for the environment.
type Environment = Maybe [(String, String)]

-- | A shell command is something we can invoke, pipe to, pipe from, or
--   pipe in both directions. All commands that can be run as shell
--   commands must define these methods.
--   
--   Minimum implementation is fdInvoke.
--   
--   Some pre-defined instances include:
--   
--   
--   
- A simple bare string, which is passed to the shell for execution.
--   The shell will then typically expand wildcards, parse parameters,
--   etc.
--   
- A (String, [String]) tuple. The first item in the tuple
--   gives the name of a program to run, and the second gives its
--   arguments. The shell is never involved. This is ideal for passing
--   filenames, since there is no security risk involving special shell
--   characters.
--   
- A Handle -> Handle -> IO () function, which reads
--   from the first handle and write to the second.
--   
- Various functions. These functions will accept input representing
--   its standard input and output will go to standard output.
--   
--   
--   Some pre-defined instance functions include:
--   
--   
--   
- (String -> String), (String -> IO String),
--   plus the same definitions for ByteStrings.
--   
- ([String] -> [String]), ([String] -> IO
--   [String]), where each String in the list represents a
--   single line
--   
- (() -> String), (() -> IO String), for
--   commands that explicitly read no input. Useful with closures. Useful
--   when you want to avoid reading stdin because something else already
--   is. These have the unit as part of the function because otherwise we
--   would have conflicts with things such as bare Strings, which represent
--   a command name.
--   
class Show a => ShellCommand a
fdInvoke :: ShellCommand a => a -> Environment -> Channel -> IO (Channel, [InvokeResult])
data PipeCommand a b
PipeCommand :: a -> b -> PipeCommand a b

-- | Pipe the output of the first command into the input of the second.
(-|-) :: (ShellCommand a, ShellCommand b) => a -> b -> PipeCommand a b

-- | Different ways to get data from run.
--   
--   
--   
- IO () runs, throws an exception on error, and sends stdout to
--   stdout
--   
- IO String runs, throws an exception on error, reads stdout into a
--   buffer, and returns it as a string. Note: This output is not
--   lazy.
--   
- IO [String] is same as IO String, but returns the results as
--   lines. Note: this output is not lazy.
--   
- IO ExitCode runs and returns an ExitCode with the exit
--   information. stdout is sent to stdout. Exceptions are not thrown.
--   
- IO (String, ExitCode) is like IO ExitCode, but also includes a
--   description of the last command in the pipe to have an error (or the
--   last command, if there was no error).
--   
- IO ByteString and are similar to their String counterparts.
--   
- IO (String, IO (String, ExitCode)) returns a String read lazily
--   and an IO action that, when evaluated, finishes up the process and
--   results in its exit status. This command returns immediately.
--   
- IO (IO (String, ExitCode)) sends stdout to stdout but returns
--   immediately. It forks off the child but does not wait for it to
--   finish. You can use checkResults to wait for the finish.
--   
- IO Int returns the exit code from a program directly. If a signal
--   caused the command to be reaped, returns 128 + SIGNUM.
--   
- IO Bool returns True if the program exited normally (exit code 0,
--   not stopped by a signal) and False otherwise.
--   
--   
--   To address insufficient laziness, you can process anything that needs
--   to be processed lazily within the pipeline itself.
class RunResult a
run :: (RunResult a, ShellCommand b) => b -> a

-- | A convenience function. Refers only to the version of run that
--   returns IO (). This prevents you from having to cast to it
--   all the time when you do not care about the result of run.
--   
--   The implementation is simply:
--   
--   
--   runIO :: (ShellCommand a) => a -> IO ()
--   runIO = run
--   
runIO :: ShellCommand a => a -> IO ()

-- | Another convenience function. This returns the first line of the
--   output, with any trailing newlines or whitespace stripped off. No
--   leading whitespace is stripped. This function will raise an exception
--   if there is not at least one line of output. Mnemonic: runSL means
--   "run single line".
--   
--   This command exists separately from run because there is
--   already a run instance that returns a String, though that
--   instance returns the entirety of the output in that String.
runSL :: ShellCommand a => a -> IO String

-- | Result type for shell commands. The String is the text description of
--   the command, not its output.
type InvokeResult = (String, IO ExitCode)

-- | Evaluates result codes and raises an error for any bad ones it finds.
checkResults :: (String, ExitCode) -> IO ()

-- | Handle an exception derived from a program exiting abnormally
tryEC :: IO a -> IO (Either ExitCode a)

-- | Catch an exception derived from a program exiting abnormally
catchEC :: IO a -> (ExitCode -> IO a) -> IO a

-- | Sets an environment variable, replacing an existing one if it exists.
--   
--   Here's a sample ghci session to illustrate. First, let's see the
--   defaults for some variables:
--   
--   
--   Prelude HSH> runIO $ "echo $TERM, $LANG"
--   xterm, en_US.UTF-8
--   
--   
--   Now, let's set one:
--   
--   
--   Prelude HSH> runIO $ setenv [("TERM", "foo")] $ "echo $TERM, $LANG"
--   foo, en_US.UTF-8
--   
--   
--   Or two:
--   
--   
--   Prelude HSH> runIO $ setenv [("TERM", "foo")] $ setenv [("LANG", "de_DE.UTF-8")] $ "echo $TERM, $LANG"
--   foo, de_DE.UTF-8
--   
--   
--   We could also do it easier, like this:
--   
--   
--   Prelude HSH> runIO $ setenv [("TERM", "foo"), ("LANG", "de_DE.UTF-8")] $ "echo $TERM, $LANG"
--   foo, de_DE.UTF-8
--   
--   
--   It can be combined with unsetenv:
--   
--   
--   Prelude HSH> runIO $ setenv [("TERM", "foo")] $ unsetenv ["LANG"] $ "echo $TERM, $LANG"
--   foo,
--   
--   
--   And used with pipes:
--   
--   
--   Prelude HSH> runIO $ setenv [("TERM", "foo")] $ "echo $TERM, $LANG" -|- "tr a-z A-Z"
--   FOO, EN_US.UTF-8
--   
--   
--   See also unsetenv.
setenv :: ShellCommand cmd => [(String, String)] -> cmd -> EnvironCommand cmd

-- | Removes an environment variable if it exists; does nothing otherwise.
--   
--   See also setenv, which has a more extensive example.
unsetenv :: ShellCommand cmd => [String] -> cmd -> EnvironCommand cmd
instance [overlap ok] Show (EnvironCommand a)
instance [overlap ok] Show (PipeCommand a b)
instance [overlap ok] ShellCommand a => ShellCommand (EnvironCommand a)
instance [overlap ok] Show EnvironFilter
instance [overlap ok] RunResult (IO (IO (String, ExitCode)))
instance [overlap ok] RunResult (IO (ByteString, IO (String, ExitCode)))
instance [overlap ok] RunResult (IO (ByteString, IO (String, ExitCode)))
instance [overlap ok] RunResult (IO (String, IO (String, ExitCode)))
instance [overlap ok] RunResult (IO ByteString)
instance [overlap ok] RunResult (IO ByteString)
instance [overlap ok] RunResult (IO String)
instance [overlap ok] RunResult (IO [String])
instance [overlap ok] RunResult (IO Bool)
instance [overlap ok] RunResult (IO Int)
instance [overlap ok] RunResult (IO ExitCode)
instance [overlap ok] RunResult (IO (String, ExitCode))
instance [overlap ok] RunResult (IO ())
instance [overlap ok] (ShellCommand a, ShellCommand b) => ShellCommand (PipeCommand a b)
instance [overlap ok] ShellCommand String
instance [overlap ok] ShellCommand (String, [String])
instance [overlap ok] ShellCommand (() -> IO [String])
instance [overlap ok] ShellCommand ([String] -> IO [String])
instance [overlap ok] ShellCommand (() -> [String])
instance [overlap ok] ShellCommand ([String] -> [String])
instance [overlap ok] Show (() -> IO [String])
instance [overlap ok] Show ([String] -> IO [String])
instance [overlap ok] Show (() -> [String])
instance [overlap ok] Show ([String] -> [String])
instance [overlap ok] ShellCommand (Channel -> IO Channel)
instance [overlap ok] ShellCommand (() -> ByteString)
instance [overlap ok] ShellCommand (ByteString -> ByteString)
instance [overlap ok] ShellCommand (() -> ByteString)
instance [overlap ok] ShellCommand (ByteString -> ByteString)
instance [overlap ok] ShellCommand (() -> String)
instance [overlap ok] ShellCommand (String -> String)
instance [overlap ok] ShellCommand (() -> IO ByteString)
instance [overlap ok] ShellCommand (ByteString -> IO ByteString)
instance [overlap ok] ShellCommand (() -> IO ByteString)
instance [overlap ok] ShellCommand (ByteString -> IO ByteString)
instance [overlap ok] ShellCommand (() -> IO String)
instance [overlap ok] ShellCommand (String -> IO String)
instance [overlap ok] Show (() -> IO ByteString)
instance [overlap ok] Show (ByteString -> IO ByteString)
instance [overlap ok] Show (() -> ByteString)
instance [overlap ok] Show (ByteString -> ByteString)
instance [overlap ok] Show (() -> IO ByteString)
instance [overlap ok] Show (ByteString -> IO ByteString)
instance [overlap ok] Show (() -> ByteString)
instance [overlap ok] Show (ByteString -> ByteString)
instance [overlap ok] Show (() -> IO String)
instance [overlap ok] Show (String -> IO String)
instance [overlap ok] Show (() -> String)
instance [overlap ok] Show (String -> String)
instance [overlap ok] Show (Channel -> IO Channel)
instance [overlap ok] Show (Handle -> Handle -> IO ())

-- | Copyright (c) 2006-2009 John Goerzen, jgoerzen@complete.org
--   
--   This module provides shell-like commands. Most, but not all, are
--   designed to be used directly as part of a HSH pipeline. All may be
--   used outside HSH entirely as well.
module HSH.ShellEquivs

-- | Return the absolute path of the arg. Raises an error if the
--   computation is impossible.
abspath :: FilePath -> IO FilePath

-- | Like catTo, but appends to the file.
appendTo :: FilePath -> String -> IO String

-- | The filename part of a path
basename :: FilePath -> FilePath

-- | 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.
--   
--   This is an alias for the MissingH function System.Path.bracketCWD.
bracketCD :: FilePath -> IO a -> IO a

-- | Load the specified files and display them, one at a time.
--   
--   The special file - means to display the input. If it is not
--   given, no input is processed at all.
--   
--   - may be given a maximum of one time.
--   
--   See also catBytes .
catFrom :: [FilePath] -> Channel -> IO Channel

-- | Copy data from input to output, optionally with a fixed maximum size,
--   in bytes. Processes data using ByteStrings internally, so be aware of
--   any possible UTF-8 conversions.
--   
--   You may wish to use hSetBuffering h (BlockBuffering Nothing)
--   prior to calling this function for optimal performance.
--   
--   See also catFrom, catBytesFrom
catBytes :: (Maybe Integer) -> Channel -> IO Channel

-- | Generic version of catBytes; reads data from specified Channel,
--   and ignores stdin.
catBytesFrom :: Channel -> (Maybe Integer) -> Channel -> IO Channel

-- | Takes input, writes it to the specified file, and does not pass it on.
--   The return value is the empty string. See also catToBS,
--   catToFIFO
catTo :: FilePath -> Channel -> IO Channel

-- | Like catTo, but opens the destination in ReadWriteMode instead
--   of ReadOnlyMode. Due to an oddity of the Haskell IO system, this is
--   required when writing to a named pipe (FIFO) even if you will never
--   read from it.
--   
--   This call will BLOCK all threads on open until a reader connects.
--   
--   This is provided in addition to catTo because you may want to
--   cat to something that you do not have permission to read from.
--   
--   This function is only available on POSIX platforms.
--   
--   See also catTo
catToFIFO :: FilePath -> Channel -> IO Channel

-- | An alias for System.Directory.setCurrentDirectory.
--   
--   Want to change to a user's home directory? Try this:
--   
--   
--   glob "~jgoerzen" >>= cd . head
--   
--   
--   See also bracketCD.
cd :: FilePath -> IO ()

-- | Split a list by a given character and select the nth list.
--   
--   
--   cut ' ' 2 "foo bar baz quux" -> "bar"
--   
cut :: Integer -> Char -> String -> String

-- | Split a list by a given character and select ranges of the resultant
--   lists.
--   
--   
--   cutR [2..4] ' ' "foo bar baz quux foobar" -> "baz quux foobar"
--   cutR [1..1000] ' ' "foo bar baz quux foobar" -> "bar baz quux foobar"
--   cutR [-1000..1000] ' ' "foo bar baz quux foobar" -> "foo bar baz quux foobar"
--   
--   
--   Note that too large and too small indices are essentially ignored.
cutR :: [Integer] -> Char -> String -> String

-- | The directory part of a path
dirname :: FilePath -> FilePath

-- | Read all input and produce no output. Discards input completely.
discard :: Channel -> IO Channel

-- | Takes a string and sends it on as standard output.
--   
--   The input to this function is never read.
--   
--   You can pass this thing a String, a ByteString, or even a Handle.
--   
--   See also echoBS.
echo :: Channelizable a => a -> Channel -> IO Channel

-- | Exits with the specified error code. 0 indicates no error.
exit :: Int -> IO a

-- | Takes a pattern. Returns a list of names that match that pattern.
--   Handles:
--   
--   
--   ~username at beginning of file to expand to user's home dir
--   ? matches exactly one character
--   * matches zero or more characters
--   [list] matches any character in list
--   [!list] matches any character not in list
--   
--   
--   The result of a tilde expansion on a nonexistant username is to do no
--   tilde expansion.
--   
--   The tilde with no username equates to the current user.
--   
--   Non-tilde expansion is done by the MissingH module System.Path.Glob.
glob :: FilePath -> IO [FilePath]

-- | Search for the string in the lines. Return those that match. Same as:
--   
--   
--   grep needle = filter (isInfixOf needle)
--   
grep :: String -> [String] -> [String]

-- | Search for the string in the lines. Return those that do NOT match.
grepV :: String -> [String] -> [String]

-- | Search for the regexp in the lines. Return those that match.
egrep :: String -> [String] -> [String]

-- | Search for the regexp in the lines. Return those that do NOT match.
egrepV :: String -> [String] -> [String]

-- | Join lines of a file
joinLines :: [String] -> [String]

-- | Convert a string to all lower case
lower :: String -> String

-- | Convert a string to all upper case
upper :: String -> String

-- | Creates the given directory. A value of 0o755 for mode would be
--   typical.
--   
--   An alias for System.Posix.Directory.createDirectory.
--   
--   The second argument will be ignored on non-POSIX systems.
mkdir :: FilePath -> FileMode -> IO ()

-- | Number each line of a file
numberLines :: [String] -> [String]

-- | An alias for System.Directory.getCurrentDirectory.
pwd :: IO FilePath

-- | Return the destination that the given symlink points to.
--   
--   An alias for System.Posix.Files.readSymbolicLink
--   
--   This function is only available on POSIX platforms.
readlink :: FilePath -> IO FilePath

-- | As readlink, but turns the result into an absolute path.
--   
--   This function is only available on POSIX platforms.
readlinkabs :: FilePath -> IO FilePath

-- | Reverse characters on each line (rev)
rev :: [String] -> [String]

-- | Reverse words on each line
--   
--   Reverse characters on each line (rev)
revW :: [String] -> [String]

-- | Sets an environment variable, replacing an existing one if it exists.
--   
--   Here's a sample ghci session to illustrate. First, let's see the
--   defaults for some variables:
--   
--   
--   Prelude HSH> runIO $ "echo $TERM, $LANG"
--   xterm, en_US.UTF-8
--   
--   
--   Now, let's set one:
--   
--   
--   Prelude HSH> runIO $ setenv [("TERM", "foo")] $ "echo $TERM, $LANG"
--   foo, en_US.UTF-8
--   
--   
--   Or two:
--   
--   
--   Prelude HSH> runIO $ setenv [("TERM", "foo")] $ setenv [("LANG", "de_DE.UTF-8")] $ "echo $TERM, $LANG"
--   foo, de_DE.UTF-8
--   
--   
--   We could also do it easier, like this:
--   
--   
--   Prelude HSH> runIO $ setenv [("TERM", "foo"), ("LANG", "de_DE.UTF-8")] $ "echo $TERM, $LANG"
--   foo, de_DE.UTF-8
--   
--   
--   It can be combined with unsetenv:
--   
--   
--   Prelude HSH> runIO $ setenv [("TERM", "foo")] $ unsetenv ["LANG"] $ "echo $TERM, $LANG"
--   foo,
--   
--   
--   And used with pipes:
--   
--   
--   Prelude HSH> runIO $ setenv [("TERM", "foo")] $ "echo $TERM, $LANG" -|- "tr a-z A-Z"
--   FOO, EN_US.UTF-8
--   
--   
--   See also unsetenv.
setenv :: ShellCommand cmd => [(String, String)] -> cmd -> EnvironCommand cmd

-- | Double space a file; add an empty line between each line.
space :: [String] -> [String]

-- | Inverse of double space; drop all empty lines.
unspace :: [String] -> [String]

-- | Reverse lines in a String (like Unix tac).
--   
--   Implemented as:
--   
--   
--   tac = reverse
--   
--   
--   See uniq.
tac :: [String] -> [String]

-- | Takes input, writes it to all the specified files, and passes it on.
--   This function does NOT buffer input.
--   
--   See also catFrom.
tee :: [FilePath] -> Channel -> IO Channel

-- | FIFO-safe version of tee.
--   
--   This call will BLOCK all threads on open until a reader connects.
--   
--   This function is only available on POSIX platforms.
teeFIFO :: [FilePath] -> Channel -> IO Channel

-- | Translate a character x to y, like:
--   
--   
--   tr 'e' 'f'
--   
--   
--   Or, in sed,
--   
--   
--   y//
--   
tr :: Char -> Char -> String -> String

-- | Delete specified character in a string.
trd :: Char -> String -> String

-- | Count number of words in a file (like wc -w)
wcW :: [String] -> [String]

-- | Count number of lines. Like wc -l
wcL :: [String] -> [String]

-- | Removes an environment variable if it exists; does nothing otherwise.
--   
--   See also setenv, which has a more extensive example.
unsetenv :: ShellCommand cmd => [String] -> cmd -> EnvironCommand cmd

-- | Remove duplicate lines from a file (like Unix uniq).
--   
--   Takes a String representing a file or output and plugs it through
--   lines and then nub to uniqify on a line basis.
uniq :: String -> String

-- | Copyright (c) 2006 John Goerzen, jgoerzen@complete.org
--   
--   Welcome to HSH, the Haskell Shell infrastructure.
--   
--   http://software.complete.org/hsh
--   
--   HSH is designed to let you mix and match shell expressions with
--   Haskell programs.
--   
--   Here are a few examples to get you started:
--   
--   
--   run $ "echo /etc/pass*" :: IO String
--    -> "/etc/passwd /etc/passwd-"
--   
--   runIO $ "ls -l" -|- "wc -l"
--    -> 12
--   
--   runIO $ "ls -l" -|- wcL
--    -> 12
--   
--   runIO $ ("ls", ["-l", "file with spaces.txt"])
--   glob "~jgoerzen" >>= cd . head
--   
--   
--   wcL is a pure Haskell function defined in HSH.ShellEquivs.wcL
--   as:
--   
--   
--   wcL :: [String] -> [String]
--   wcL inp = [show $ genericLength inp]
--   
--   
--   Here's another example:
--   
--   
--   let countLines = (zipWith (\i line -> printf "%-5d %s" i line) 
--        [(1::Int)..])::([String] -> [String])
--   
--   runIO $ ("ls", ["-l"]) -|- countLines -|- filter (isSuffixOf "hs")
--     6     -rw-r--r-- 1 jgoerzen jgoerzen  1285 Jun  6 09:43 HSH.hs
--     11    -rw-r--r-- 1 jgoerzen jgoerzen   565 Jun  6 09:43 test.hs
--   
--   
--   To use HSH, you'll just want to import the HSH module. To learn more,
--   please see the information in HSH.Command and
--   HSH.ShellEquivs.
--   
--   You can run a command with HSH in several ways:
--   
--   
--   
- By using run in a context that expects IO (), which will
--   leave the final standard output going to the normal standard output of
--   the program
--   
- By using run in a context that expects a String, which will
--   capture standard output into a buffer and present it as a String
--   
- Any of the numerous other methods documented in
--   RunResult.
--   
- The shortcut functions runIO and runSL. runIO
--   lets you run a command and force the context IO (), which is a
--   frequently-useful shortcut when you don't care about the result.
--   runSL grabs the first line of output in the result.
--   
--   
--   You can then specify a command, which could be a single command or a
--   command joined together with pipes.
--   
--   There are many different items that make valid types; see the list of
--   instances of ShellCommand for a full list. Here are a few:
--   
--   
--   
- A simple bare string is passed to the shell for execution. The
--   shell will then typically expand wildcards, parse parameters,
--   etc.
--   
- A (String, [String]) tuple. The first item in the tuple
--   gives the name of a program to run, and the second gives its
--   arguments. The shell is never involved. This is ideal for passing
--   filenames, since there is no security risk involving special shell
--   characters.
--   
- A Haskell function. This function will accept input representing
--   its standard input and generate output to go to stdout. Function types
--   that are supported natively include (String -> String),
--   (String -> IO String), plus many more involving
--   ByteStrings and functions that take no input. See ShellCommand
--   for more.
--   
--   
--   Pipes can be constructed by using the -|- operator, as illustrated
--   above. It is quite possible to pipe data between Haskell functions and
--   shell commands at will.
--   
--   In addition, HSH.ShellEquivs provides a number of useful
--   pure-Haskell equivalents of regular shell commands.
--   
--   For more information, please consult the other modules in HSH as well
--   as the HSH wiki at:
--   
--   http://software.complete.org/hsh
module HSH
