DMenu

Overview

This module provides complete bindings to the dmenu and dmenu2 command-line tools.

The dmenu command line tool

1. takes command line Options and reads a list of strings from stdin,
2. presents the list in a special overlay window, in which the user can select from the list via fuzzy matching, and
3. prints the selected string to stdout or fails with exit code 1 if the user hit the ESC key.

Typical uses of dmenu are for example

1. as a program launcher by piping the program names from PATH into dmenu and executing the selected program.
2. as an interface for killing programs by piping process information from ps aux into dmenu, and running kill -9 on the selected process id.
3. as an interface for mounting devices by piping the device files from /dev/ into dmenu, and running pmount on the selected device (shown in the image above).

dmenu2 is a fork of dmenu, which provides additional options, e.g. selecting multiple items at once.

Ontop of the functionality of dmenu and dmenu2, this library supports a configuration file for specifying default command line options for dmenu. See the last section for more on the configuration file.

The simplest way to run dmenu is with the select function.

Note for stack users: When running programs using this library via stack exec, the program may fail to find dmenu in the PATH. This problem can be solved by running the program directly without stack, or by temporarily using an absolute path for dmenu in the binaryPath option.

Types

type DMenuT = StateT Options

A state monad transformer in which the command line options of dmenu can be configured.

type MonadDMenu m = (MonadIO m, MonadState Options m)

The MonadIO constraint additionally allows to spawn processes with System.Process in between.

type ProcessError = (Int, String)

When a spawned process fails, this type is used to represent the exit code and stderr output.

Running dmenu

run :: MonadIO m => DMenuT m a -> m a

Run a StateT Options m a action using the command line options from the config file or an empty set of options as initial state.

For example

import qualified DMenu

main :: IO ()
main = DMenu.run $ do
  DMenu.numLines .= 10
  DMenu.prompt   .= "run"
  liftIO . print =<< DMenu.selectM ["A","B","C"]

Selecting a single item

selectM

Arguments

:: MonadDMenu m

=> [String]

List from which the user should select.

-> m (Either ProcessError String)

The selection made by the user, or a ProcessError, if the user canceled.

Run DMenu with the command line options from m and a list of Strings from which the user should choose.

select

Arguments

:: MonadIO m

=> DMenuT m ()

State Options action which changes the default command line options.

-> [String]

List from which the user should select.

-> m (Either ProcessError String)

The selection made by the user, or a ProcessError, if the user canceled.

Convenience function combining run and selectM.

The following example has the same behavior as the example for run:

import qualified DMenu

main :: IO ()
main = print =<< DMenu.select setOptions ["A","B","C"]

setOptions :: DMenu.MonadDMenu m => m ()
setOptions = do
  DMenu.numLines .= 10
  DMenu.prompt   .= "run"

selectWithM

Arguments

:: MonadDMenu m

=> (a -> String)

How to display an a in dmenu.

-> [a]

List from which the user should select.

-> m (Either ProcessError a)

The selection made by the user, or a ProcessError, if the user canceled.

Same as selectM, but allows the user to select from a list of arbitrary elements, which have a String representation.

selectWith

Arguments

:: MonadIO m

=> DMenuT m ()

State Options action which changes the default command line options.

-> (a -> String)

How to display an a in dmenu.

-> [a]

List from which the user should select.

-> m (Either ProcessError a)

The selection made by the user, or a ProcessError, if the user canceled.

Same as select, but allows the user to select from a list of arbitrary elements, which have a String representation.

For example

import qualified DMenu

main :: IO ()
main = print =<< DMenu.selectWith setOptions show [1..10::Int]

setOptions :: DMenu.MonadDMenu m => m ()
setOptions = do
  DMenu.numLines .= 10
  DMenu.prompt   .= "run"

Selecting multiple items

filterM

Arguments

:: MonadDMenu m

=> [String]

List from which the user should filter.

-> m (Either ProcessError [String])

The selection made by the user, or a ProcessError, if the user canceled.

Like selectM but uses the dmenu2 option filterMode, which returns not only the selected item, but all items which fuzzy match the input term.

filter

Arguments

:: MonadIO m

=> DMenuT m ()

State Options action which changes the default command line options.

-> [String]

List from which the user should select.

-> m (Either ProcessError [String])

The selection made by the user, or a ProcessError, if the user canceled.

Like select but uses the dmenu2 option filterMode, which returns not only the selected item, but all items which fuzzy match the input term.

filterWithM

Arguments

:: MonadDMenu m

=> (a -> String)

How to display an a in dmenu.

-> [a]

List from which the user should select.

-> m (Either ProcessError [a])

The selection made by the user, or a ProcessError, if the user canceled.

Like selectWithM but uses the dmenu2 option filterMode, which returns not only the selected item, but all items which fuzzy match the input term.

filterWith

Arguments

:: MonadIO m

=> DMenuT m ()

State Options action which changes the default command line options.

-> (a -> String)

How to display an a in dmenu.

-> [a]

List from which the user should select.

-> m (Either ProcessError [a])

The selection made by the user, or a ProcessError, if the user canceled.

Like selectWith but uses the dmenu2 option filterMode, which returns not only the selected item, but all items which fuzzy match the input term.

dmenu Command Line Options

data Options

Contains the binary path and command line options of dmenu. The option descriptions are copied from the dmenu man page.

Lenses

binaryPath :: Lens' Options FilePath

Path to the the dmenu executable file. Default looks for dmenu in the PATH enviroment variable.

displayAtBottom :: Lens' Options Bool

-b; dmenu appears at the bottom of the screen.

grabKeyboardBeforeStdin :: Lens' Options Bool

-f; dmenu grabs the keyboard before reading stdin. This is faster, but will lock up X until stdin reaches end-of-file.

caseInsensitive :: Lens' Options Bool

-i; dmenu matches menu items case insensitively.

spawnOnMonitor :: Lens' Options Int

-m screen; dmenu is displayed on the monitor number supplied. Monitor numbers are starting from 0.

numLines :: Lens' Options Int

-l lines; dmenu lists items vertically, with the given number of lines.

prompt :: Lens' Options String

-p prompt; defines the prompt to be displayed to the left of the input field.

font :: Lens' Options String

-fn font; defines the font or font set used. eg. "fixed" or "Monospace-12:normal" (an xft font)

normalBGColor :: Lens' Options Color

-nb color; defines the normal background color. #RGB, #RRGGBB, and X color names are supported.

normalFGColor :: Lens' Options Color

-nf color; defines the normal foreground color.

selectedBGColor :: Lens' Options Color

-sb color; defines the selected background color.

selectedFGColor :: Lens' Options Color

-sf color; defines the selected foreground color.

printVersionAndExit :: Lens' Options Bool

-v; prints version information to stdout, then exits.

dmenu2 :: Lens' Options Options2

Extra options only available in the dmenu2 fork.

noDMenu2 :: Lens' Options Bool

When set to True, the dmenu2 options are ignored. This ensures compatibility with the normal dmenu. A user may set this flag in the configuration file.

extraArgs :: Lens' Options [String]

List of extra command line arguments to pass to dmenu. This can be useful, when the client wants to forward some of its own command line arguments directly to the executed dmenu processes.

Default: []

Forwarding Command Line Arguments

forwardExtraArgs :: MonadDMenu m => m ()

Forwards all command line arguments from getArgs, which appear after the first "--" argument, to dmenu by setting them as extraArgs.

dmenu2-specific Command Line Options

data Options2

Contains the command line options of dmenu2 which are not part of dmenu. The option descriptions are copied from the dmenu2 man page.

Lenses

displayNoItemsIfEmpty :: Lens' Options2 Bool

-q; dmenu will not show any items if the search string is empty.

filterMode :: Lens' Options2 Bool

-r; activates filter mode. All matching items currently shown in the list will be selected, starting with the item that is highlighted and wrapping around to the beginning of the list. (Note: Instead of setting this flag yourself, the dmenu filter functions can be used instead of the select functions.)

fuzzyMatching :: Lens' Options2 Bool

-z; dmenu uses fuzzy matching. It matches items that have all characters entered, in sequence they are entered, but there may be any number of characters between matched characters. For example it takes "txt" makes it to "*t*x*t" glob pattern and checks if it matches.

tokenMatching :: Lens' Options2 Bool

-t; dmenu uses space-separated tokens to match menu items. Using this overrides -z option.

maskInputWithStar :: Lens' Options2 Bool

-mask; dmenu masks input with asterisk characters (*).

ignoreStdin :: Lens' Options2 Bool

-noinput; dmenu ignores input from stdin (equivalent to: echo | dmenu).

spawnOnScreen :: Lens' Options2 Int

-s screen; dmenu apears on the specified screen number. Number given corespondes to screen number in X configuration.

windowName :: Lens' Options2 String

-name name; defines window name for dmenu. Defaults to "dmenu".

windowClass :: Lens' Options2 String

-class class; defines window class for dmenu. Defaults to "Dmenu".

windowOpacity :: Lens' Options2 Double

-o opacity; defines window opacity for dmenu. Defaults to 1.0.

windowDimOpacity :: Lens' Options2 Double

-dim opacity; enables screen dimming when dmenu appers. Takes dim opacity as argument.

windowDimColor :: Lens' Options2 Color

-dc color; defines color of screen dimming. Active only when -dim in effect. Defautls to black (#000000)

heightInPixels :: Lens' Options2 Int

-h height; defines the height of the bar in pixels.

underlineHeightInPixels :: Lens' Options2 Int

-uh height; defines the height of the underline in pixels.

windowOffsetX :: Lens' Options2 Int

-x xoffset; defines the offset from the left border of the screen.

windowOffsetY :: Lens' Options2 Int

-y yoffset; defines the offset from the top border of the screen.

width :: Lens' Options2 Int

-w width; defines the desired menu window width.

underlineColor :: Lens' Options2 Color

-uc color; defines the underline color.

historyFile :: Lens' Options2 FilePath

-hist histfile; the file to use for history

Color

data Color

Multiple representations for colors.

For example, green can be defined as

green1 = HexColor 0x00FF00
green2 = RGBColor 0 255 0
green3 = RGBColorF 0 1 0

Constructors

HexColor Int

RGBColor Int Int Int

RGBColorF Float Float Float

Instances

Eq Color

Methods

(==) :: Color -> Color -> Bool

(/=) :: Color -> Color -> Bool

Ord Color

Methods

compare :: Color -> Color -> Ordering

(<) :: Color -> Color -> Bool

(<=) :: Color -> Color -> Bool

(>) :: Color -> Color -> Bool

(>=) :: Color -> Color -> Bool

max :: Color -> Color -> Color

min :: Color -> Color -> Color

Read Color

Methods

readsPrec :: Int -> ReadS Color

readList :: ReadS [Color]

readPrec :: ReadPrec Color

readListPrec :: ReadPrec [Color]

Show Color

Methods

showsPrec :: Int -> Color -> ShowS

show :: Color -> String

showList :: [Color] -> ShowS

Reexports from lens

(.=) :: MonadState s m => ASetter s s a b -> b -> m () infix 4

Replace the target of a Lens or all of the targets of a Setter or Traversal in our monadic state with a new value, irrespective of the old.

This is an infix version of assign.

>>> execState (do _1 .= c; _2 .= d) (a,b)
(c,d)

>>> execState (both .= c) (a,b)
(c,c)

(.=) :: MonadState s m => Iso' s a       -> a -> m ()
(.=) :: MonadState s m => Lens' s a      -> a -> m ()
(.=) :: MonadState s m => Traversal' s a -> a -> m ()
(.=) :: MonadState s m => Setter' s a    -> a -> m ()

It puts the state in the monad or it gets the hose again.

Configuration File

The default Options used by run, select, etc. can be specified in the ~/.haskell-dmenu file.

The following example shows the ~/.haskell-dmenu file used for the image from the first section:

numLines         15
font             "FiraMono:size=11"
caseInsensitive  True
normalBGColor    RGBColorF 0.02 0.02 0.02

The configuration file contains one line per option. Each line consists of an option name and a value for the option. The option names are identical to the corresponding lens names. The values are read via their Read instances.

If reading a value fails, exitFailure is called and an error message is presented to the user, e.g.

`caseInsensitive` must be a boolean, i.e. `True` or `False`.

configFileUsage :: String

Description of the configuration file syntax of ~/.haskell-dmenu, as written in the CONFIG.md file.

This String may be useful to inform clients about the config file, e.g. in the usage information.