Module IOExts

Library with some useful extensions to the IO monad.

Author: Michael Hanus

Version: January 2017

Summary of exported operations:

execCmd :: String -> IO (Handle,Handle,Handle)   
Executes a command with a new default shell process.
evalCmd :: String -> [String] -> String -> IO (Int,String,String)   
Executes a command with the given arguments as a new default shell process and provides the input via the process' stdin input stream.
connectToCommand :: String -> IO Handle   
Executes a command with a new default shell process.
readCompleteFile :: String -> IO String   
An action that reads the complete contents of a file and returns it.
updateFile :: (String -> String) -> String -> IO ()   
An action that updates the contents of a file.
exclusiveIO :: String -> IO a -> IO a   
Forces the exclusive execution of an action via a lock file.
setAssoc :: String -> String -> IO ()   
Defines a global association between two strings.
getAssoc :: String -> IO (Maybe String)   
Gets the value associated to a string.
newIORef :: a -> IO (IORef a)   
Creates a new IORef with an initial value.
readIORef :: IORef a -> IO a   
Reads the current value of an IORef.
writeIORef :: IORef a -> a -> IO ()   
Updates the value of an IORef.
modifyIORef :: IORef a -> (a -> a) -> IO ()   
Modify the value of an IORef.

Exported datatypes:


IORef

Mutable variables containing values of some type. The values are not evaluated when they are assigned to an IORef.

Constructors:


Exported operations:

execCmd :: String -> IO (Handle,Handle,Handle)   

Executes a command with a new default shell process. The standard I/O streams of the new process (stdin,stdout,stderr) are returned as handles so that they can be explicitly manipulated. They should be closed with IO.hClose since they are not closed automatically when the process terminates.

Example call:
(execCmd cmd)
Parameters:
  • cmd : the shell command to be executed
Returns:
the handles of the input/output/error streams of the new process

evalCmd :: String -> [String] -> String -> IO (Int,String,String)   

Executes a command with the given arguments as a new default shell process and provides the input via the process' stdin input stream. The exit code of the process and the contents written to the standard I/O streams stdout and stderr are returned.

Example call:
(evalCmd cmd args input)
Parameters:
  • cmd : the shell command to be executed
  • args : the command's arguments
  • input : the input to be written to the command's stdin
Returns:
the exit code and the contents written to stdout and stderr

connectToCommand :: String -> IO Handle   

Executes a command with a new default shell process. The input and output streams of the new process is returned as one handle which is both readable and writable. Thus, writing to the handle produces input to the process and output from the process can be retrieved by reading from this handle. The handle should be closed with IO.hClose since they are not closed automatically when the process terminates.

Example call:
(connectToCommand cmd)
Parameters:
  • cmd : the shell command to be executed
Returns:
the handle connected to the input/output streams of the new process

readCompleteFile :: String -> IO String   

An action that reads the complete contents of a file and returns it. This action can be used instead of the (lazy) readFile action if the contents of the file might be changed.

Example call:
(readCompleteFile file)
Parameters:
  • file : the name of the file
Returns:
the complete contents of the file

updateFile :: (String -> String) -> String -> IO ()   

An action that updates the contents of a file.

Example call:
(updateFile f file)
Parameters:
  • f : the function to transform the contents
  • file : the name of the file

exclusiveIO :: String -> IO a -> IO a   

Forces the exclusive execution of an action via a lock file. For instance, (exclusiveIO "myaction.lock" act) ensures that the action "act" is not executed by two processes on the same system at the same time.

Example call:
(exclusiveIO lockfile action)
Parameters:
  • lockfile : the name of a global lock file
  • action : the action to be exclusively executed
Returns:
the result of the execution of the action

setAssoc :: String -> String -> IO ()   

Defines a global association between two strings. Both arguments must be evaluable to ground terms before applying this operation.

getAssoc :: String -> IO (Maybe String)   

Gets the value associated to a string. Nothing is returned if there does not exist an associated value.

newIORef :: a -> IO (IORef a)   

Creates a new IORef with an initial value.

Further infos:
  • externally defined

readIORef :: IORef a -> IO a   

Reads the current value of an IORef.

writeIORef :: IORef a -> a -> IO ()   

Updates the value of an IORef.

modifyIORef :: IORef a -> (a -> a) -> IO ()   

Modify the value of an IORef.