HLWM.IPC

An IPC client implementation for the herbstluftwm window manager.

See herbstluftwm(1) and herbstclient(1) for what this is all about.

Examples

Sending a command to herbstluftwm:

>>> withConnection (\con -> sendCommand con ["echo", "foo"])
Just (0,"foo\n")

Printing 2 hooks:

>>> withConnection (\con -> replicateM_ 2 $ unwords <$> nextHook con >>= putStrLn)
focus_changed 0x340004c IPC.hs - emacs
focus_changed 0x3200073 ROXTerm
Just ()

Although sendCommand is synchronous, you can use it with forkIO or the async library:

withConnection $ \con -> do
  var <- newEmptyMVar
  forkIO $ sendCommand con ["echo","foo"] >>= putMVar var
  -- do some stuff ...
  -- finally read output
  output <- takeMVar var

Connection

data HerbstConnection

Opaque type representing the connection to the herbstluftwm server

See connect and disconnect.

connect :: IO (Maybe HerbstConnection)

Connect to the herbstluftwm server.

Be sure to call disconnect if you don't need the connection anymore, to free any allocated resources. When in doubt, call withConnection.

Note that there must not be more than one connection open at any time!

disconnect :: HerbstConnection -> IO ()

Close connection to the herbstluftwm server.

After calling this function, the HerbstConnection is no longer valid and must not be used anymore.

withConnection :: (HerbstConnection -> IO a) -> IO (Maybe a)

Execute an action with a newly established HerbstConnection.

Connects to the herbstluftwm server, passes the connection on to the supplied action and closes the connection again after the action has finished.

Commands and Hooks

sendCommand :: HerbstConnection -> [String] -> IO (Int, String)

Execute a command in the herbstluftwm server.

Send a command consisting of a list of Strings to the server and wait for the response. Herbstluftwm interprets this list as a command followed by a number of arguments. Returns a tuple of the exit status and output of the called command.

nextHook :: HerbstConnection -> IO [String]

Wait for a hook event from the server and return it.

A hook is just an arbitrary list of strings generated by herbstluftwm or its clients.