XMonad.Util.Run

xmonad-contrib-0.12: Third party extensions for xmonad

Copyright | (C) 2007 Spencer Janssen, Andrea Rossato, glasser@mit.edu
License | BSD-style (see LICENSE)
Maintainer | Christian Thiemann <mail@christian-thiemann.de>
Stability | unstable
Portability | unportable
Safe Haskell | None
Language | Haskell98

XMonad.Util.Run

Contents

- Usage

Description

This modules provides several commands to run an external process. It is composed of functions formerly defined in XMonad.Util.Dmenu (by Spencer Janssen), XMonad.Util.Dzen (by glasser@mit.edu) and XMonad.Util.RunInXTerm (by Andrea Rossato).

Synopsis

- runProcessWithInput :: MonadIO m => FilePath -> [String] -> String -> m String
- runProcessWithInputAndWait :: MonadIO m => FilePath -> [String] -> String -> Int -> m ()
- safeSpawn :: MonadIO m => FilePath -> [String] -> m ()
- safeSpawnProg :: MonadIO m => FilePath -> m ()
- unsafeSpawn :: MonadIO m => String -> m ()
- runInTerm :: String -> String -> X ()
- safeRunInTerm :: String -> String -> X ()
- seconds :: Rational -> Int
- spawnPipe :: MonadIO m => String -> m Handle
- hPutStr :: Handle -> String -> IO ()
- hPutStrLn :: Handle -> String -> IO ()

# Usage

For an example usage of `runInTerm` see XMonad.Prompt.Ssh

For an example usage of `runProcessWithInput` see XMonad.Prompt.DirectoryPrompt, XMonad.Util.Dmenu, XMonad.Prompt.ShellPrompt, XMonad.Actions.WmiiActions, XMonad.Prompt.WorkspaceDir

For an example usage of `runProcessWithInputAndWait` see XMonad.Util.Dzen

runProcessWithInput :: MonadIO m => FilePath -> [String] -> String -> m String

Returns the output.

runProcessWithInputAndWait :: MonadIO m => FilePath -> [String] -> String -> Int -> m ()

Wait is in μ (microseconds)

safeSpawn :: MonadIO m => FilePath -> [String] -> m ()

`safeSpawn` bypasses `spawn`, because spawn passes strings to /bin/sh to be interpreted as shell commands. This is often what one wants, but in many cases the passed string will contain shell metacharacters which one does not want interpreted as such (URLs particularly often have shell metacharacters like '&' in them). In this case, it is more useful to specify a file or program to be run and a string to give it as an argument so as to bypass the shell and be certain the program will receive the string as you typed it.

Examples:

    , ((modm, xK_Print), unsafeSpawn "import -window root $HOME/xwd-$(date +%s)$$.png")
    , ((modm, xK_d    ), safeSpawn "firefox" [])

Note that the unsafeSpawn example must be unsafe and not safe because it makes use of shell interpretation by relying on `$HOME` and interpolation, whereas the safeSpawn example can be safe because Firefox doesn't need any arguments if it is just being started.

safeSpawnProg :: MonadIO m => FilePath -> m ()

Simplified `safeSpawn`; only takes a program (and no arguments):

    , ((modm, xK_d    ), safeSpawnProg "firefox")

unsafeSpawn :: MonadIO m => String -> m ()

An alias for `spawn`; the name emphasizes that one is calling out to a Turing-complete interpreter which may do things one dislikes; for details, see `safeSpawn`.

runInTerm :: String -> String -> X ()

Open a terminal emulator. The terminal emulator is specified in the default configuration as xterm by default. It is then asked to pass the shell a command with certain options. This is unsafe in the sense of `unsafeSpawn`

safeRunInTerm :: String -> String -> X ()

Run a given program in the preferred terminal emulator; see `runInTerm`. This makes use of `safeSpawn`.

seconds :: Rational -> Int

Multiplies by ONE MILLION, for functions that take microseconds.

Use like:

    (5.5 `seconds`)

In GHC 7 and later, you must either enable the PostfixOperators extension (by adding

    {-# LANGUAGE PostfixOperators #-}

to the top of your file) or use seconds in prefix form:

    5.5 seconds

spawnPipe :: MonadIO m => String -> m Handle

Launch an external application through the system shell and return a `Handle` to its standard input.

hPutStr :: Handle -> String -> IO ()

Computation `hPutStr` `hdl s` writes the string `s` to the file or channel managed by `hdl`.

This operation may fail with:

- `isFullError` if the device is full; or
- `isPermissionError` if another system resource limit would be exceeded.

hPutStrLn :: Handle -> String -> IO ()

The same as `hPutStr`, but adds a newline character.