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


-- | shell monad
--   
--   This is a shell monad, for generating shell scripts.
@package shell-monad
@version 0.2.1


-- | This is a shell monad, for generating shell scripts.
module Control.Monad.Shell

-- | Shell script monad.
data Script a

-- | Generates a shell script, including hashbang, suitable to be written
--   to a file.
script :: Script f -> Text

-- | Generates a single line of shell code.
linearScript :: Script f -> Text

-- | A shell variable.
data Var

-- | Expand a shell variable to its value.
val :: Var -> Quoted Text

-- | A value that is safely quoted.
data Quoted a

-- | Quotes the Text to allow it to be safely exposed to the shell.
--   
--   The method used is to replace ' with '"'"' and wrap the value inside
--   single quotes. This works for POSIX shells, as well as other shells
--   like csh.
quote :: Text -> Quoted Text

-- | Treats the Text as a glob, which expands to one parameter per matching
--   file.
--   
--   The input is assumed to be a well-formed glob. Characters in it that
--   are not alphanumeric and are not wildcard characters will be escaped
--   before it is exposed to the shell. This allows eg, spaces in globs.
glob :: Text -> Quoted Text

-- | Adds a shell command to the script.
run :: Text -> [Text] -> Script ()

-- | Variadic and polymorphic version of <a>run</a>
--   
--   A command can be passed any number of Params.
--   
--   <pre>
--   demo = script $ do
--     cmd "echo" "hello, world"
--     name &lt;- newVar "name"
--     readVar name
--     cmd "echo" "hello" name
--   </pre>
--   
--   For the most efficient use of <a>cmd</a>, add the following
--   boilerplate, which will make string literals in your program default
--   to being Text:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings, ExtendedDefaultRules #-}
--   {-# OPTIONS_GHC -fno-warn-type-defaults #-}
--   import Control.Monad.Shell
--   import qualified Data.Text.Lazy as L
--   default (L.Text)
--   </pre>
--   
--   Note that the command to run is itself a Param, so it can be a Text,
--   or a String, or even a Var or Output. For example, this echos "hi":
--   
--   <pre>
--   demo = script $ do
--      echovar &lt;- newVarContaining "echo" ()
--      cmd echovar "hi"
--   </pre>
cmd :: (Param command, CmdParams params) => command -> params

-- | A Param is anything that can be used as the parameter of a command.
class Param a

-- | Allows a function to take any number of Params.
class CmdParams t

-- | The output of a command, or even a more complicated Script can be
--   passed as a parameter to <a>cmd</a>
--   
--   Examples:
--   
--   <pre>
--   cmd "echo" "hello there," (Output (cmd "whoami"))
--   cmd "echo" "root's pwent" (Output (cmd "cat" "/etc/passwd" -|- cmd "grep" "root"))
--   </pre>
newtype Output
Output :: (Script ()) -> Output

-- | An arbitrary value.
newtype Val v
Val :: v -> Val v

-- | Adds a comment that is embedded in the generated shell script.
comment :: Text -> Script ()

-- | Suggests that a shell variable or function have its name contain the
--   specified Text.
newtype NamedLike
NamedLike :: Text -> NamedLike

-- | Class of values that provide a hint for the name to use for a shell
--   variable or function.
--   
--   To skip providing a hint, use '()'. To provide a hint, use '(NamedLike
--   "name")'.
class NameHinted h

-- | Defines a new shell variable.
--   
--   Each call to newVar will generate a new, unique variable name.
--   
--   The namehint can influence this name, but is modified to ensure
--   uniqueness.
newVar :: NameHinted namehint => namehint -> Script Var

-- | Creates a new shell variable, with an initial value.
newVarContaining :: NameHinted namehint => Text -> namehint -> Script Var

-- | Gets a Var that refers to a global variable, such as PATH
globalVar :: Text -> Script Var

-- | This special Var expands to whatever parameters were passed to the
--   shell script.
--   
--   Inside a func, it expands to whatever parameters were passed to the
--   func.
--   
--   (This is <tt>$@</tt> in shell)
positionalParameters :: Var

-- | Takes the first positional parameter, removing it from
--   positionalParameters and returning a new Var that holds the value of
--   the parameter.
--   
--   If there are no more positional parameters, the script will crash with
--   an error.
--   
--   For example:
--   
--   <pre>
--   removefirstfile = script $ do
--     cmd "rm" =&lt;&lt; takeParameter
--     cmd "echo" "remaining parameters:" positionalParameters
--   </pre>
takeParameter :: NameHinted namehint => namehint -> Script Var

-- | Defines a shell function, and returns an action that can be run to
--   call the function.
--   
--   The action is variadic; it can be passed any number of CmdParams.
--   Typically, it will make sense to specify a more concrete type when
--   defining the shell function.
--   
--   The shell function will be given a unique name, that is not used by
--   any other shell function. The namehint can be used to influence the
--   contents of the function name, which makes for more readable generated
--   shell code.
--   
--   For example:
--   
--   <pre>
--   demo = script $ do
--      hohoho &lt;- mkHohoho
--      hohoho (Val 1)
--      echo "And I heard him exclaim, ere he rode out of sight ..."
--      hohoho (Val 3)
--   
--   mkHohoho :: Script (Val Int -&gt; Script ())
--   mkHohoho = func (NamedLike "hohoho") $ do
--      num &lt;- takeParameter
--      forCmd (cmd "seq" "1" num) $ \_n -&gt;
--         cmd "echo" "Ho, ho, ho!" "Merry xmas!"
--   </pre>
func :: (NameHinted namehint, CmdParams callfunc) => namehint -> Script () -> Script callfunc

-- | Runs the command, and separates its output into parts (using the IFS)
--   
--   The action is run for each part, passed a Var containing the part.
forCmd :: Script () -> (Var -> Script ()) -> Script ()

-- | As long as the first Script exits nonzero, runs the second script.
whileCmd :: Script () -> Script () -> Script ()

-- | if with a monadic conditional
--   
--   If the conditional exits 0, the first action is run, else the second.
ifCmd :: Script () -> Script () -> Script () -> Script ()

-- | when with a monadic conditional
whenCmd :: Script () -> Script () -> Script ()

-- | unless with a monadic conditional
unlessCmd :: Script () -> Script () -> Script ()

-- | Generates shell code to fill a variable with a line read from stdin.
readVar :: Var -> Script ()

-- | By default, shell scripts continue running past commands that exit
--   nonzero. Use "stopOnFailure True" to make the script stop on the first
--   such command.
stopOnFailure :: Bool -> Script ()

-- | Makes a nonzero exit status be ignored.
ignoreFailure :: Script () -> Script ()

-- | Pipes together two Scripts.
(-|-) :: Script () -> Script () -> Script ()

-- | ANDs two Scripts.
(-&&-) :: Script () -> Script () -> Script ()

-- | ORs two Scripts.
(-||-) :: Script () -> Script () -> Script ()

-- | Any function that takes a RedirFile can be passed a a FilePath, in
--   which case the default file descriptor will be redirected to/from the
--   FilePath.
--   
--   Or, it can be passed a tuple of (Fd, FilePath), in which case the
--   specified Fd will be redirected to/from the FilePath.
class RedirFile r

-- | Redirects to a file, overwriting any existing file.
--   
--   For example, to shut up a noisy command:
--   
--   <pre>
--   cmd "find" "/" |&gt; "/dev/null"
--   </pre>
(|>) :: RedirFile f => Script () -> f -> Script ()

-- | Appends to a file. (If file doesn't exist, it will be created.)
(|>>) :: RedirFile f => Script () -> f -> Script ()

-- | Redirects standard input from a file.
(|<) :: RedirFile f => Script () -> f -> Script ()

-- | Redirects a script's output to stderr.
toStderr :: Script () -> Script ()

-- | Redirects the first file descriptor to output to the second.
--   
--   For example, to redirect a command's stderr to stdout:
--   
--   <pre>
--   cmd "foo" -&gt;- stdError) |&gt;&amp; stdOutput
--   </pre>
(|>&) :: (Script (), Fd) -> Fd -> Script ()

-- | Redirects the first file descriptor to input from the second.
(|<&) :: (Script (), Fd) -> Fd -> Script ()

-- | Helper for <a>|&gt;&amp;</a> and <a>|&lt;&amp;</a>
(->-) :: Script () -> Fd -> (Script (), Fd)

-- | Provides the Text as input to the Script, using a here-document.
hereDocument :: Script () -> Text -> Script ()
instance Eq Var
instance Ord Var
instance Show Var
instance Eq a => Eq (Quoted a)
instance Ord a => Ord (Quoted a)
instance Show a => Show (Quoted a)
instance Monoid a => Monoid (Quoted a)
instance Eq Func
instance Ord Func
instance Show Func
instance Functor Script
instance RedirFile (Fd, FilePath)
instance RedirFile FilePath
instance NameHinted (Maybe Text)
instance NameHinted NamedLike
instance NameHinted ()
instance f ~ () => CmdParams (Script f)
instance (Param arg, CmdParams result) => CmdParams (arg -> result)
instance Param Output
instance Param (Quoted Text)
instance Param Var
instance Show v => Param (Val v)
instance Param String
instance Param Text
instance Monoid Env
instance Monad Script