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


-- | shell monad
--   
@package shell-monad
@version 0.2.0


-- | 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 params => Text -> params
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

-- | 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, an error will be thrown at
--   runtime.
--   
--   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 CmdArgs.
--   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, ShellCmd callfunc) => namehint -> Script () -> Script callfunc

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

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

-- | ORs 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 NameHinted (Maybe Text)
instance NameHinted NamedLike
instance NameHinted ()
instance f ~ () => ShellCmd (Script f)
instance (CmdArg arg, ShellCmd result) => ShellCmd (arg -> result)
instance CmdArg Output
instance CmdArg (Quoted Text)
instance CmdArg Var
instance Show v => CmdArg (Val v)
instance CmdArg String
instance CmdArg Text
instance Monoid Env
instance Monad Script