A module that allows the user to use a prefix argument (raw or numeric).

This module implements Emacs-style prefix argument. The argument comes in two flavours, Raw and Numeric.

To initiate the "prefix mode" you hit the prefix keybinding (default C-u). This sets the Raw argument value to 1. Repeatedly hitting this key increments the raw value by 1. The Raw argument is usually used as a toggle, changing the behaviour of the function called in some way.

An example might be calling "mpc add" to add new song to the playlist, but with C-u we also clean up the playlist beforehand.

When in the "Raw mode", you can hit numeric keys 0..9 (with no modifier) to enter a "Numeric argument". Numeric argument represents a natural number. Hitting numeric keys in sequence produces the decimal number that would result from typing them. That is, the sequence C-u 4 2 sets the Numeric argument value to the number 42.

If you have a function which understands the prefix argument, for example:

   addMaybeClean :: PrefixArgument -> X ()
   addMaybeClean (Raw _) = spawn "mpc clear" >> spawn "mpc add <file>"
   addMaybeClean _ = spawn "mpc add <file>"

you can turn it into an X action with the function withPrefixArgument.

Binding it in your config

   ((modm, xK_a), withPrefixArgument addMaybeClean)

Hitting MOD-a will add the file to the playlist while C-u MOD-a will clear the playlist and then add the file.

You can of course use an anonymous action, like so:

   ((modm, xK_a), withPrefixArgument $ \prefix -> do
       case prefix of ...
   )

If the prefix key is followed by a binding which is unknown to XMonad, the prefix along with that binding is sent to the active window.

There is one caveat: when you use an application which has a nested C-u binding, for example C-c C-u in Emacs org-mode, you have to hit C-g (or any other non-recognized key really) to get out of the "xmonad grab" and let the C-c C-u be sent to the application.

The simplest way to enable this is to use useDefaultPrefixArgument

   xmonad $ useDefaultPrefixArgument $ def { .. }

The default prefix argument is C-u. If you want to customize the prefix argument, usePrefixArgument can be used:

   xmonad $ usePrefixArgument "M-u" $ def { .. }

where the key is entered in Emacs style (or XMonad.Util.EZConfig style) notation. The letter M stands for your chosen modifier. The function defaults to C-u if the argument could not be parsed.