-- 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.0.3


-- | A shell script monad
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 value 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

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

-- | Variadic argument version of <a>run</a>.
--   
--   The command can be passed any number of CmdArgs.
--   
--   Convenient usage of <a>cmd</a> requires the following:
--   
--   <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>
--   
--   This allows writing, for example:
--   
--   <pre>
--   demo = script $ do
--     cmd "echo" "hello, world"
--     name &lt;- newVar "name"
--     readVar name
--     cmd "echo" "hello" name
--   </pre>
cmd :: ShellCmd result => Text -> result
class CmdArg a

-- | 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

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

-- | Defines a new shell variable.
--   
--   The name of the variable that appears in the shell script will be
--   based on provided name (which can be mempty), but each call to newVar
--   will generate a new, unique variable name.
newVar :: Text -> Script Var

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

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

-- | Defines a shell function, and returns an action that can be run to
--   call the function.
--   
--   TODO parameter passing to the function
func :: Script () -> Script (Script ())

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

-- | 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 ()
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 f ~ () => ShellCmd (Script f)
instance (CmdArg arg, ShellCmd result) => ShellCmd (arg -> result)
instance CmdArg Output
instance CmdArg (Quoted Text)
instance CmdArg Var
instance CmdArg Text
instance Monoid Env
instance Monad Script