Safe Haskell | None |
---|---|
Language | Haskell2010 |
See documentation for Shh.
Synopsis
- initInteractive :: IO ()
- data Failure = Failure {
- failureProg :: String
- failureArgs :: [String]
- failureCode :: Int
- class PipeResult f where
- (<|) :: PipeResult f => Proc a -> Proc b -> f a
- withPipe :: (Handle -> Handle -> IO a) -> IO a
- writeOutput :: PipeResult io => String -> io ()
- writeError :: PipeResult io => String -> io ()
- readInput :: (NFData a, PipeResult io) => (String -> IO a) -> io a
- readInputSplit :: (NFData a, PipeResult io) => String -> ([String] -> IO a) -> io a
- readInputSplit0 :: (NFData a, PipeResult io) => ([String] -> IO a) -> io a
- readInputLines :: (NFData a, PipeResult io) => ([String] -> IO a) -> io a
- pureProc :: PipeResult io => (String -> String) -> io ()
- prefixLines :: PipeResult io => String -> io ()
- writeProc :: PipeResult io => Proc a -> String -> io a
- withRead :: (PipeResult f, NFData b) => Proc a -> (String -> IO b) -> f b
- data Stream
- devNull :: Stream
- newtype Proc a = Proc (Handle -> Handle -> Handle -> IO () -> IO () -> IO a)
- runProc :: Proc a -> IO a
- runProc' :: Handle -> Handle -> Handle -> Proc a -> IO a
- mkProc' :: Bool -> String -> [String] -> Proc ()
- mkProc :: String -> [String] -> Proc ()
- readProc :: PipeResult io => Proc a -> io String
- capture :: PipeResult io => io String
- captureTrim :: PipeResult io => io String
- captureSplit :: PipeResult io => String -> io [String]
- captureSplit0 :: PipeResult io => io [String]
- captureLines :: PipeResult io => io [String]
- withRead' :: (NFData b, PipeResult io) => (String -> a) -> Proc x -> (a -> IO b) -> io b
- withReadSplit :: (NFData b, PipeResult io) => String -> Proc a -> ([String] -> IO b) -> io b
- withReadSplit0 :: (NFData b, PipeResult io) => Proc a -> ([String] -> IO b) -> io b
- withReadLines :: (NFData b, PipeResult io) => Proc a -> ([String] -> IO b) -> io b
- withReadWords :: (NFData b, PipeResult io) => Proc a -> ([String] -> IO b) -> io b
- readWriteProc :: MonadIO io => Proc a -> String -> io String
- apply :: MonadIO io => Proc a -> String -> io String
- (>>>) :: PipeResult io => String -> Proc a -> io a
- (<<<) :: PipeResult io => Proc a -> String -> io a
- waitProc :: String -> [String] -> ProcessHandle -> IO ()
- trim :: String -> String
- class ProcFailure m where
- catchFailure :: Proc a -> m (Either Failure a)
- ignoreFailure :: (Functor m, ProcFailure m) => Proc a -> m ()
- catchCode :: (Functor m, ProcFailure m) => Proc a -> m Int
- readTrim :: (Functor io, PipeResult io) => Proc a -> io String
- class ExecArg a where
- asArg :: a -> [String]
- asArgFromList :: [a] -> [String]
- class ExecArgs a where
- class Unit a
- pathBins :: IO [FilePath]
- pathBinsAbs :: IO [FilePath]
- findBinsIn :: [FilePath] -> IO [FilePath]
- exe :: (Unit a, ExecArgs a) => String -> a
- loadExe :: ExecReference -> String -> Q [Dec]
- data ExecReference
- rawExe :: String -> String -> Q [Dec]
- loadExeAs :: ExecReference -> String -> String -> Q [Dec]
- encodeIdentifier :: String -> String
- loadEnv :: ExecReference -> Q [Dec]
- checkExecutable :: FilePath -> IO Bool
- load :: ExecReference -> [String] -> Q [Dec]
- loadAnnotated :: ExecReference -> (String -> String) -> [String] -> Q [Dec]
- loadAnnotatedEnv :: ExecReference -> (String -> String) -> Q [Dec]
- split :: String -> String -> [String]
- loadFromDirs :: [FilePath] -> Q [Dec]
- loadFromBins :: [FilePath] -> Q [Dec]
- loadAnnotatedFromDirs :: [FilePath] -> (String -> String) -> Q [Dec]
- split0 :: String -> [String]
- readSplit0 :: Proc () -> IO [String]
- readLines :: Proc () -> IO [String]
- readWords :: Proc () -> IO [String]
- readAuto :: Read a => Proc () -> IO a
- cd' :: FilePath -> IO ()
- class Cd a where
- cd :: a
- xargs1 :: (NFData a, Monoid a) => String -> (String -> Proc a) -> Proc a
- readInputP :: (NFData a, PipeResult io) => (String -> Proc a) -> io a
- readInputSplitP :: (NFData a, PipeResult io) => String -> ([String] -> Proc a) -> io a
- readInputSplit0P :: (NFData a, PipeResult io) => ([String] -> Proc a) -> io a
- readInputLinesP :: (NFData a, PipeResult io) => ([String] -> Proc a) -> io a
- withNullInput :: (Handle -> IO a) -> IO a
- withDuplicate :: Handle -> (Handle -> IO a) -> IO a
- withDuplicates :: Handle -> Handle -> Handle -> (Handle -> Handle -> Handle -> IO a) -> IO a
- withDuplicateNullInput :: Handle -> Handle -> (Handle -> Handle -> Handle -> IO a) -> IO a
- hDup :: Handle -> IO Handle
- dupHandleShh :: FilePath -> Handle -> Maybe (MVar Handle__) -> Handle__ -> Maybe HandleFinalizer -> IO Handle
- dupHandleShh_ :: (IODevice dev, BufferedIO dev, Typeable dev) => dev -> FilePath -> Maybe (MVar Handle__) -> Handle__ -> Maybe HandleFinalizer -> IO Handle
Documentation
For doc-tests. Not sure I can use TH in doc tests. >>> import Data.Monoid >>> let cat = exe "cat" >>> let echo = exe "echo" >>> let false = exe "false" >>> let head = exe "head" >>> let md5sum = exe "md5sum" >>> let printf = exe "printf" >>> let sleep = exe "sleep" >>> let true = exe "true" >>> let wc = exe "wc" >>> let xargs = exe "xargs" >>> let yes = exe "yes" >>> let some_command = writeOutput "this is stdout" >> (writeOutput "this is stderr" &> StdErr)
initInteractive :: IO () Source #
This function needs to be called in order to use the library successfully
from GHCi. If you use the formatPrompt
function from the shh-extras
package, this will be automatically called for you.
When a process exits with a non-zero exit code
we throw this Failure
exception.
The only exception to this is when a process is terminated
by SIGPIPE
in a pipeline, in which case we ignore it.
Failure | |
|
Instances
Eq Failure Source # | |
Ord Failure Source # | |
Show Failure Source # | |
Exception Failure Source # | |
Defined in Shh.Internal toException :: Failure -> SomeException # fromException :: SomeException -> Maybe Failure # displayException :: Failure -> String # |
class PipeResult f where Source #
This class is used to allow most of the operators in Shh to be
polymorphic in their return value. This makes using them in an IO
context
easier (we can avoid having to prepend everything with a runProc
).
(|>) :: Proc b -> Proc a -> f a infixl 1 Source #
Use this to send the output of on process into the input of another. This is just like a shells `|` operator.
The result is polymorphic in it's output, and can result in either another `Proc a` or an `IO a` depending on the context in which it is used.
If any intermediate process throws an exception, the whole pipeline is canceled.
The result of the last process in the chain is the result returned by the pipeline.
>>>
echo "Hello" |> wc
1 1 6
(|!>) :: Proc b -> Proc a -> f a infixl 1 Source #
Similar to |!>
except that it connects stderr to stdin of the
next process in the chain.
NB: The next command to be |>
on will recapture the stdout of
both preceding processes, because they are both going to the same
handle!
See the &>
and &!>
operators for redirection.
>>>
echo "Ignored" |!> wc "-c"
Ignored 0
(&>) :: Proc a -> Stream -> f a infixl 9 Source #
Redirect stdout of this process to another location
>>>
echo "Ignore me" &> Append "/dev/null"
(&!>) :: Proc a -> Stream -> f a infixl 9 Source #
Redirect stderr of this process to another location
>>>
echo "Shh" &!> StdOut
Shh
nativeProc :: NFData a => (Handle -> Handle -> Handle -> IO a) -> f a Source #
Instances
PipeResult IO Source # | |
PipeResult Proc Source # | |
(<|) :: PipeResult f => Proc a -> Proc b -> f a infixr 1 Source #
Flipped version of |>
with lower precedence.
>>>
captureTrim <| (echo "Hello" |> wc "-c")
"6"
withPipe :: (Handle -> Handle -> IO a) -> IO a Source #
Create a pipe, and close both ends on exception. The first argument is the read end, the second is the write end.
>>>
withPipe $ \r w -> hPutStrLn w "test" >> hClose w >> hGetLine r
"test"
writeOutput :: PipeResult io => String -> io () Source #
writeError :: PipeResult io => String -> io () Source #
Simple
that writes a Proc
String
to it's stderr
.
See also
.
>>> writeError Hello &> devNull
HellowriteOutput
readInputSplit :: (NFData a, PipeResult io) => String -> ([String] -> IO a) -> io a Source #
readInputSplit0 :: (NFData a, PipeResult io) => ([String] -> IO a) -> io a Source #
readInputLines :: (NFData a, PipeResult io) => ([String] -> IO a) -> io a Source #
pureProc :: PipeResult io => (String -> String) -> io () Source #
Creates a pure
that simple transforms the Proc
stdin
and writes
it to stdout
. The input can be infinite.
>>>
yes |> pureProc (take 4) |> capture
"y\ny\n"
prefixLines :: PipeResult io => String -> io () Source #
Captures the stdout of a process and prefixes all the lines with the given string.
>>>
some_command |> prefixLines "stdout: " |!> prefixLines "stderr: " &> StdErr
stdout: this is stdout stderr: this is stderr
writeProc :: PipeResult io => Proc a -> String -> io a Source #
Provide the stdin of a Proc
from a String
Same as writeOutput
s |> p
withRead :: (PipeResult f, NFData b) => Proc a -> (String -> IO b) -> f b Source #
Run a process and capture it's output lazily. Once the continuation
is completed, the handles are closed. However, the process is run
until it naturally terminates in order to capture the correct exit
code. Most utilities behave correctly with this (e.g. cat
will
terminate if you close the handle).
Same as p |> readInput f
Type representing a series or pipeline (or both) of shell commands.
Proc
's can communicate to each other via stdin
, stdout
and stderr
and can communicate to Haskell via their parameterised return type, or by
throwing an exception.
Instances
Monad Proc Source # | |
Functor Proc Source # | |
Applicative Proc Source # | |
MonadIO Proc Source # | |
Defined in Shh.Internal | |
ProcFailure Proc Source # | |
Defined in Shh.Internal | |
PipeResult Proc Source # | |
Semigroup (Proc a) Source # | The |
a ~ () => Monoid (Proc a) Source # | |
ExecArgs (Proc ()) Source # | |
mkProc :: String -> [String] -> Proc () Source #
Create a Proc
from a command and a list of arguments. Does not delegate
control-c handling.
capture :: PipeResult io => io String Source #
captureTrim :: PipeResult io => io String Source #
captureSplit :: PipeResult io => String -> io [String] Source #
captureSplit0 :: PipeResult io => io [String] Source #
Same as
.captureSplit
"0"
captureLines :: PipeResult io => io [String] Source #
Same as
.captureSplit
"n"
withRead' :: (NFData b, PipeResult io) => (String -> a) -> Proc x -> (a -> IO b) -> io b Source #
Apply a transformation function to the string before the IO action.
withReadSplit :: (NFData b, PipeResult io) => String -> Proc a -> ([String] -> IO b) -> io b Source #
Like
except it splits the string with the provided separator.withRead
withReadSplit0 :: (NFData b, PipeResult io) => Proc a -> ([String] -> IO b) -> io b Source #
withReadLines :: (NFData b, PipeResult io) => Proc a -> ([String] -> IO b) -> io b Source #
Like
except it splits the string with withRead
first.lines
NB: Please consider using
where you can.withReadSplit0
withReadWords :: (NFData b, PipeResult io) => Proc a -> ([String] -> IO b) -> io b Source #
readWriteProc :: MonadIO io => Proc a -> String -> io String Source #
Read and write to a Proc
. Same as
readProc proc <<< input
apply :: MonadIO io => Proc a -> String -> io String Source #
Some as readWriteProc
. Apply a Proc
to a String
.
> apply md5sum "Hello"
"8b1a9953c4611296a827abf8c47804d7 -n"
waitProc :: String -> [String] -> ProcessHandle -> IO () Source #
Wait on a given ProcessHandle
, and throw an exception of
type Failure
if it's exit code is non-zero (ignoring SIGPIPE)
class ProcFailure m where Source #
Instances
ProcFailure IO Source # | |
Defined in Shh.Internal | |
ProcFailure Proc Source # | |
Defined in Shh.Internal |
ignoreFailure :: (Functor m, ProcFailure m) => Proc a -> m () Source #
catchCode :: (Functor m, ProcFailure m) => Proc a -> m Int Source #
Run an Proc
action returning the return code if an
exception was thrown, and 0 if it wasn't.
readTrim :: (Functor io, PipeResult io) => Proc a -> io String Source #
Like readProc
, but trim leading and tailing whitespace.
class ExecArg a where Source #
A class for things that can be converted to arguments on the command
line. The default implementation is to use show
.
Nothing
asArg :: a -> [String] Source #
asArg :: Show a => a -> [String] Source #
asArgFromList :: [a] -> [String] Source #
asArgFromList :: Show a => [a] -> [String] Source #
class ExecArgs a where Source #
A class for building up a command
Force a `()` result.
Instances
a ~ () => Unit (m a) Source # | |
Defined in Shh.Internal | |
Unit b => Unit (a -> b) Source # | |
Defined in Shh.Internal |
pathBinsAbs :: IO [FilePath] Source #
Get all uniquely named executables on your `$PATH` as absolute file names. The uniqueness is determined by the filename, and not the whole path. First one found wins.
findBinsIn :: [FilePath] -> IO [FilePath] Source #
Get all uniquely named executables from the list of directories. Returns a list of absolute file names.
data ExecReference Source #
Specify how executables should be referenced.
Absolute | Find executables on PATH, but store their absolute path |
SearchPath | Always search on PATH |
rawExe :: String -> String -> Q [Dec] Source #
Template Haskell function to create a function from a path that will be called. This does not check for executability at compile time.
loadExeAs :: ExecReference -> String -> String -> Q [Dec] Source #
$(loadExeAs ref fnName executable)
defines a function called fnName
which executes the path in executable
. If executable
is an absolute path
it is used directly. If it is just an executable name, then it is searched
for in the PATH environment variable. If ref
is SearchPath
, the short
name is retained, and your PATH will be searched at runtime. If ref
is Absolute
, a executable name will be turned into an absolute path, which
will be used at runtime.
encodeIdentifier :: String -> String Source #
Takes a string, and makes a Haskell identifier out of it. There
is some chance of overlap. If the string is a path, the filename portion
is used. The transformation replaces all non-alphanumeric characters
with '_'
. If the first character is uppercase it is forced into lowercase.
If it starts with a number, it is prefixed with `_`. If it overlaps with
a reserved word or a builtin, it is suffixed with an `_`.
loadEnv :: ExecReference -> Q [Dec] Source #
Scans your '$PATH' environment variable and creates a function for each
executable found. Binaries that would not create valid Haskell identifiers
are encoded using the
function.encodeIdentifier
checkExecutable :: FilePath -> IO Bool Source #
Test to see if an executable can be found either on the $PATH or absolute.
load :: ExecReference -> [String] -> Q [Dec] Source #
Load the given executables into the program, checking their executability
and creating a function missingExecutables
to do a runtime check for their
availability. Uses the
function to create function
names.encodeIdentifier
loadAnnotated :: ExecReference -> (String -> String) -> [String] -> Q [Dec] Source #
Same as load
, but allows you to modify the function names.
loadAnnotatedEnv :: ExecReference -> (String -> String) -> Q [Dec] Source #
Like loadEnv
, but allows you to modify the function name that would
be generated.
split :: String -> String -> [String] Source #
Split a string separated by the provided separator. Trailing separators
are ignored, and do not produce an empty string. Compatible with the
output of most CLI programs, such as find -print0
.
>>>
split "\n" "a\nb\n"
["a","b"]
>>>
split "\n" "a\nb"
["a","b"]
loadFromBins :: [FilePath] -> Q [Dec] Source #
Load executables from the given directories appended with "/bin"
.
Useful for use with Nix.
loadAnnotatedFromDirs :: [FilePath] -> (String -> String) -> Q [Dec] Source #
Load executables from the given dirs, applying the given transformation to the filenames.
split0 :: String -> [String] Source #
Function that splits '\0' separated list of strings. Useful in conjunction
with find . "-print0"
.
readSplit0 :: Proc () -> IO [String] Source #
A convenience function for reading in a "\NUL"
separated list of
strings. This is commonly used when dealing with paths.
readSplit0 $ find "-print0"
readLines :: Proc () -> IO [String] Source #
A convenience function for reading the output lines of a Proc
.
Note: Please consider using
instead if you can.readSplit0
Helper class for variable number of arguments to cd
builtin.
xargs1 :: (NFData a, Monoid a) => String -> (String -> Proc a) -> Proc a Source #
xargs1 n f
runs f
for each item in the input separated by n
. Similar
to the standard xargs
utility, but you get to choose the separator, and it
only does one argument per command. Compare the following two lines, which
do the same thing.
>>>
printf "a\\0b" |> xargs "--null" "-L1" "echo" |> cat
a b>>>
printf "a\\0b" |> xargs1 "\0" echo |> cat
a b
One benefit of this method over the standard xargs
is that we can run
Haskell functions as well.
>>>
yes |> head "-n" 5 |> xargs1 "\n" (const $ pure $ Sum 1)
Sum {getSum = 5}
readInputP :: (NFData a, PipeResult io) => (String -> Proc a) -> io a Source #
readInputSplitP :: (NFData a, PipeResult io) => String -> ([String] -> Proc a) -> io a Source #
Like
, but splits the input.readInputP
readInputSplit0P :: (NFData a, PipeResult io) => ([String] -> Proc a) -> io a Source #
Like
, but splits the input on 0 bytes.readInputP
readInputLinesP :: (NFData a, PipeResult io) => ([String] -> Proc a) -> io a Source #
Like
, but splits the input on new lines.readInputP
withDuplicates :: Handle -> Handle -> Handle -> (Handle -> Handle -> Handle -> IO a) -> IO a Source #
Bracket three
shDup
withDuplicateNullInput :: Handle -> Handle -> (Handle -> Handle -> Handle -> IO a) -> IO a Source #
Bracket two
s and provide a null input handle.hDup
hDup :: Handle -> IO Handle Source #
Duplicate a
without trying to flush buffers. Only works on Handle
s.FileHandle
hDuplicate tries to "flush" read buffers by seeking backwards, which doesn't
work for streams/pipes. Since we are simulating a fork + exec
in
,
losing the buffers is actually the expected behaviour. (System.Process doesn't
attempt to flush the buffers).nativeProc
NB: An alternate solution that we could implement (even for System.Process forks) is to create a fresh pipe and spawn an async task to forward buffered content from the original handle if there is something in the buffer. My concern would be that it might be a performance hit that people aren't expecting.
Code basically copied from http://hackage.haskell.org/package/base-4.12.0.0/docs/src/GHC.IO.Handle.html#hDuplicate with minor modifications.