-- 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.0.3 -- | 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: -- -- -- -- Some pre-defined instance functions include: -- -- class Show a => ShellCommand a fdInvoke :: ShellCommand a => a -> Environment -> Channel -> IO (Channel, [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 run. -- -- -- -- 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] (ShellCommand a, ShellCommand b) => Show (PipeCommand a b) instance [overlap ok] ShellCommand a => Show (EnvironCommand a) 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, 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 words on each line -- -- 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: -- -- -- -- 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: -- -- -- -- 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