XMonad.Prompt.Input

A generic framework for prompting the user for input and passing it along to some other action.

Usage

To use this module, import it along with XMonad.Prompt:

 import XMonad.Prompt
 import XMonad.Prompt.Input

This module provides no useful functionality in isolation, but is intended for use in building other actions which require user input.

For example, suppose Mr. Big wants a way to easily fire his employees. We'll assume that he already has a function

 fireEmployee :: String -> X ()

which takes as input the name of an employee, and fires them. He just wants a convenient way to provide the input for this function from within xmonad. Here is where the XMonad.Prompt.Input module comes into play. He can use the inputPrompt function to create a prompt, and the ?+ operator to compose the prompt with the fireEmployee action, like so:

 firingPrompt :: X ()
 firingPrompt = inputPrompt defaultXPConfig \"Fire\" ?+ fireEmployee

If employees contains a list of all his employees, he could also create an autocompleting version, like this:

 firingPrompt' = inputPromptWithCompl defaultXPConfig \"Fire\"
                     (mkComplFunFromList employees) ?+ fireEmployee

Now all he has to do is add a keybinding to firingPrompt (or firingPrompt'), such as

  , ((modm .|. controlMask, xK_f),  firingPrompt)

Now when Mr. Big hits mod-ctrl-f, a prompt will pop up saying "Fire: ", waiting for him to type the name of someone to fire. If he thinks better of it after hitting mod-ctrl-f and cancels the prompt (e.g. by hitting Esc), the fireEmployee action will not be invoked.

(For detailed instructions on editing your key bindings, see XMonad.Doc.Extending.)

XMonad.Prompt.Input is also intended to ease the process of developing other modules which require user input. For an example of a module developed using this functionality, see XMonad.Prompt.Email, which prompts the user for a recipient, subject, and one-line body, and sends a quick email.

inputPrompt :: XPConfig -> String -> X (Maybe String)

Given a prompt configuration and some prompt text, create an X action which pops up a prompt waiting for user input, and returns whatever they type. Note that the type of the action is X (Maybe String), which reflects the fact that the user might cancel the prompt (resulting in Nothing), or enter an input string s (resulting in Just s).

inputPromptWithCompl :: XPConfig -> String -> ComplFunction -> X (Maybe String)

The same as inputPrompt, but with a completion function. The type ComplFunction is String -> IO [String], as defined in XMonad.Prompt. The mkComplFunFromList utility function, also defined in XMonad.Prompt, is useful for creating such a function from a known list of possibilities.

(?+) :: Monad m => m (Maybe a) -> (a -> m ()) -> m ()

A combinator for hooking up an input prompt action to a function which can take the result of the input prompt and produce another action. If the user cancels the input prompt, the second function will not be run.

The astute student of types will note that this is actually a very general combinator and has nothing in particular to do with input prompts. If you find a more general use for it and want to move it to a different module, be my guest.