-- 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.
@package HSH
@version 1.2.6


-- | Copyright (c) 2006-2008 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 <a>catTo</a>, 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 <tt>-</tt> means to display the input. If it is not
--   given, no input is read.
--   
--   Unlike the shell cat, <tt>-</tt> may be given twice. However, if it
--   is, you will be forcing Haskell to buffer the input.
--   
--   Note: buffering behavior here is untested.
--   
--   See also <a>catFromBS</a>.
catFrom :: [FilePath] -> String -> IO String

-- | Lazy ByteString version of <a>catFrom</a>. This may have performance
--   benefits.
catFromBS :: [FilePath] -> ByteString -> IO ByteString

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

-- | Like <a>catTo</a>, but operates in a lazy ByteString. This could be a
--   performance benefit.
catToBS :: FilePath -> ByteString -> IO ByteString

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

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

-- | Split a list by a given character and select ranges of the resultant
--   lists.
--   
--   <pre>
--   cutR [2..4] ' ' "foo bar baz quux foobar" -&gt; "baz quux foobar"
--   cutR [1..1000] ' ' "foo bar baz quux foobar" -&gt; "bar baz quux foobar"
--   cutR [-1000..1000] ' ' "foo bar baz quux foobar" -&gt; "foo bar baz quux foobar"
--   </pre>
--   
--   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

-- | Takes a string and sends it on as standard output.
--   
--   The input to this function is never read.
--   
--   See also <a>echoBS</a>.
echo :: String -> String -> String

-- | ByteString.Lazy version of <a>echo</a>.
echoBS :: ByteString -> ByteString -> ByteString

-- | 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:
--   
--   <pre>
--   ~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
--   </pre>
--   
--   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:
--   
--   <pre>
--   grep needle = filter (isInfixOf needle)
--   </pre>
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]
lower :: String -> String

-- | Inverse of double space; drop empty lines
--   
--   Convert a string to all upper or lower case
upper :: String -> String

-- | Creates the given directory. A value of 0o755 for mode would be
--   typical.
--   
--   An alias for System.Posix.Directory.createDirectory.
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
readlink :: FilePath -> IO FilePath

-- | As <a>readlink</a>, but turns the result into an absolute path.
readlinkabs :: FilePath -> IO FilePath
rev :: [String] -> [String]

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

-- | Double space a file
unspace :: [String] -> [String]

-- | Reverse words on each line
--   
--   Reverse lines in a String (like Unix tac).
--   
--   Implemented as:
--   
--   <pre>
--   tac = reverse
--   </pre>
--   
--   See <a>uniq</a>.
tac :: [String] -> [String]

-- | Takes input, writes it to all the specified files, and passes it on.
--   This function buffers the input.
--   
--   See also <a>teeBS</a>, <a>catFrom</a>.
tee :: [FilePath] -> String -> IO String

-- | Lazy ByteString version of <a>tee</a>.
teeBS :: [FilePath] -> ByteString -> IO ByteString

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

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

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

-- | 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-2007 John Goerzen, jgoerzen@complete.org
module HSH.Command

-- | 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 <a>fdInvoke</a>.
class (Show a) => ShellCommand a
fdInvoke :: (ShellCommand a) => a -> Fd -> Fd -> [Fd] -> (IO ()) -> IO [InvokeResult]
data (ShellCommand a, ShellCommand b) => 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 <a>run</a>.
--   
--   <ul>
--   <li>IO () runs, throws an exception on error, and sends stdout to
--   stdout</li>
--   <li>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.</li>
--   <li>IO [String] is same as IO String, but returns the results as
--   lines. Note: this output is not lazy.</li>
--   <li>IO ProcessStatus runs and returns a ProcessStatus with the exit
--   information. stdout is sent to stdout. Exceptions are not thrown.</li>
--   <li>IO (String, ProcessStatus) is like IO ProcessStatus, 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)</li>
--   <li>IO ByteString and IO (ByteString, ProcessStatus) are similar to
--   their String counterparts.</li>
--   <li>IO Int returns the exit code from a program directly. If a signal
--   caused the command to be reaped, returns 128 + SIGNUM.</li>
--   <li>IO Bool returns True if the program exited normally (exit code 0,
--   not stopped by a signal) and False otherwise.</li>
--   </ul>
--   
--   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 <a>run</a> that
--   returns <tt>IO ()</tt>. This prevents you from having to cast to it
--   all the time when you do not care about the result of <a>run</a>.
--   
--   The implementation is simply:
--   
--   <pre>
--   runIO :: (ShellCommand a) =&gt; a -&gt; IO ()
--   runIO = run
--   </pre>
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 <a>run</a> because there is
--   already a <a>run</a> 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 ProcessStatus)

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

-- | Catch an exception derived from a program exiting abnormally
catchEC :: IO a -> (ProcessStatus -> IO a) -> IO a
instance [overlap ok] (ShellCommand a, ShellCommand b) => Show (PipeCommand a b)
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 ProcessStatus)
instance [overlap ok] RunResult (IO (String, ProcessStatus))
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 ([String] -> IO [String])
instance [overlap ok] ShellCommand ([String] -> [String])
instance [overlap ok] Show ([String] -> IO [String])
instance [overlap ok] Show ([String] -> [String])
instance [overlap ok] ShellCommand (ByteString -> ByteString)
instance [overlap ok] ShellCommand (ByteString -> ByteString)
instance [overlap ok] ShellCommand (String -> String)
instance [overlap ok] ShellCommand (ByteString -> IO ByteString)
instance [overlap ok] ShellCommand (ByteString -> IO ByteString)
instance [overlap ok] ShellCommand (String -> IO String)
instance [overlap ok] Show (ByteString -> IO ByteString)
instance [overlap ok] Show (ByteString -> ByteString)
instance [overlap ok] Show (ByteString -> IO ByteString)
instance [overlap ok] Show (ByteString -> ByteString)
instance [overlap ok] Show (String -> IO String)
instance [overlap ok] Show (String -> String)


-- | Copyright (c) 2006 John Goerzen, jgoerzen@complete.org
--   
--   Welcome to HSH, the Haskell Shell infrastructure.
--   
--   <a>http://software.complete.org/hsh</a>
--   
--   HSH is designed to let you mix and match shell expressions with
--   Haskell programs.
--   
--   Here are a few examples to get you started:
--   
--   <pre>
--   run $ "echo /etc/pass*" :: IO String
--    -&gt; "/etc/passwd /etc/passwd-"
--   
--   runIO $ "ls -l" -|- "wc -l"
--    -&gt; 12
--   
--   runIO $ "ls -l" -|- wcL
--    -&gt; 12
--   
--   runIO $ ("ls", ["-l", "file with spaces.txt"])
--   glob "~jgoerzen" &gt;&gt;= cd . head
--   </pre>
--   
--   wcL is a pure Haskell function defined in <a>HSH.ShellEquivs.wcL</a>
--   as:
--   
--   <pre>
--   wcL :: [String] -&gt; [String]
--   wcL inp = [show $ genericLength inp]
--   </pre>
--   
--   Here's another example:
--   
--   <pre>
--   let countLines = (zipWith (\i line -&gt; printf "%-5d %s" i line) 
--        [(1::Int)..])::([String] -&gt; [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
--   </pre>
--   
--   To use HSH, you'll just want to import the HSH module. To learn more,
--   please see the information in <a>HSH.Command</a> and
--   <a>HSH.ShellEquivs</a>.
--   
--   You can run a command with HSH in several ways:
--   
--   <ul>
--   <li>By using <a>run</a> in a context that expects IO (), which will
--   leave the final standard output going to the normal standard output of
--   the program</li>
--   <li>By using <a>run</a> in a context that expects a String, which will
--   capture standard output into a buffer and present it as a String</li>
--   <li>Any of the numerous other methods documented in
--   <a>RunResult</a>.</li>
--   <li>The shortcut functions <a>runIO</a> and <a>runSL</a>. <a>runIO</a>
--   lets you run a command and force the context IO (), which is a
--   frequently-useful shortcut when you don't care about the result.
--   <a>runSL</a> grabs the first line of output in the result.</li>
--   </ul>
--   
--   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 <a>ShellCommand</a> for a full list. Here are a few:
--   
--   <ul>
--   <li>A simple bare string is passed to the shell for execution. The
--   shell will then typically expand wildcards, parse parameters,
--   etc.</li>
--   <li>A <tt>(String, [String])</tt> 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.</li>
--   <li>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 <tt>(String -&gt; String)</tt>,
--   <tt>(String -&gt; IO String)</tt>, <tt>([String] -&gt; [String])</tt>,
--   <tt>([String] -&gt; IO [String])</tt>. Those that accept a
--   <tt>[String]</tt> type will have each string in the list representing
--   a single line.</li>
--   </ul>
--   
--   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, <a>HSH.ShellEquivs</a> 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:
--   
--   <a>http://software.complete.org/hsh</a>
module HSH