From 809e9cd669c4881afd58337424b1aa55e18aa4c8 Mon Sep 17 00:00:00 2001 From: Andrea Rossato Date: Fri, 16 Nov 2007 13:09:38 +0100 Subject: XMonad.Util.Run: meny haddock fixes I've also trasnformed gwern's comments to use '--' instead of {- -}, for uniformity. darcs-hash:20071116120938-32816-c342a43b4bb3dc813ac8231838b607cd8f58b530.gz --- XMonad/Util/Run.hs | 66 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 38 insertions(+), 28 deletions(-) (limited to 'XMonad/Util') diff --git a/XMonad/Util/Run.hs b/XMonad/Util/Run.hs index 7d9da86..f013ea8 100644 --- a/XMonad/Util/Run.hs +++ b/XMonad/Util/Run.hs @@ -9,8 +9,8 @@ -- Portability : unportable -- -- This modules provides several commands to run an external process. --- It is composed of functions formerly defined in XMonad.Util.Dmenu (by --- Spencer Jannsen), XMonad.Util.Dzen (by glasser\@mit.edu) and +-- It is composed of functions formerly defined in "XMonad.Util.Dmenu" (by +-- Spencer Jannsen), "XMonad.Util.Dzen" (by glasser\@mit.edu) and -- XMonad.Util.RunInXTerm (by Andrea Rossato). -- ----------------------------------------------------------------------------- @@ -40,12 +40,15 @@ import System.Process (runInteractiveProcess, waitForProcess) import XMonad -- $usage --- For an example usage of runInTerm see XMonad.Prompt.Ssh +-- For an example usage of 'runInTerm' see "XMonad.Prompt.Ssh" -- --- For an example usage of runProcessWithInput see --- XMonad.Prompt.{DirectoryPrompt,Dmenu,ShellPrompt,WmiiActions,WorkspaceDir} +-- 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 +-- For an example usage of 'runProcessWithInputAndWait' see +-- "XMonad.Util.Dzen" -- | Returns Just output if the command succeeded, and Nothing if it didn't. -- This corresponds to dmenu's notion of exit code 1 for a cancelled invocation. @@ -61,7 +64,7 @@ runProcessWithInput cmd args input = do waitForProcess ph return output --- wait is in us +-- | Wait is in us runProcessWithInputAndWait :: FilePath -> [String] -> String -> Int -> IO () runProcessWithInputAndWait cmd args input timeout = do pid <- forkProcess $ do @@ -81,35 +84,42 @@ runProcessWithInputAndWait cmd args input timeout = do getProcessStatus True False pid return () -{- | Multiplies by ONE MILLION, for use with runProcessWithInputAndWait. - Use like: - - > (5.5 `seconds`) --} +-- | Multiplies by ONE MILLION, for use with +-- 'runProcessWithInputAndWait'. +-- +-- Use like: +-- +-- > (5.5 `seconds`) seconds :: Rational -> Int seconds = fromEnum . (* 1000000) -{- | safeSpawn bypasses XMonad's 'spawn' command, 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. - unsafeSpawn is an alias for XMonad's 'spawn', to remind one that use of it can be, well, unsafe. - Examples: - - > , ((modMask, xK_Print ), unsafeSpawn "import -window root png:$HOME/xwd-$(date +%s)$$.png") - > , ((modMask, 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. --} +-- | safeSpawn bypasses XMonad's 'spawn' command, 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. +-- unsafeSpawn is an alias for XMonad's 'spawn', to remind one that use +-- of it can be, well, unsafe. +-- Examples: +-- +-- > , ((modMask, xK_Print), unsafeSpawn "import -window root png:$HOME/xwd-$(date +%s)$$.png") +-- > , ((modMask, 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. safeSpawn :: MonadIO m => FilePath -> String -> m () safeSpawn prog arg = liftIO (try (forkProcess $ executeFile prog True [arg] Nothing) >> return ()) + unsafeSpawn :: MonadIO m => String -> m () unsafeSpawn = spawn --- | Run a given program in the preferred terminal emulator. This uses safeSpawn. +-- | Run a given program in the preferred terminal emulator. This uses +-- 'safeSpawn'. safeRunInTerm :: String -> X () safeRunInTerm command = asks (terminal . config) >>= \t -> safeSpawn t ("-e " ++ command) -- cgit v1.2.3