summaryrefslogtreecommitdiffhomepage
path: root/doc/plugins.org
diff options
context:
space:
mode:
authorGuy Gastineau <strings.stringsandstrings@gmail.com>2021-09-14 20:43:30 -0400
committerGuy Gastineau <strings.stringsandstrings@gmail.com>2021-09-14 21:15:49 -0400
commit38adaf0ded1ca40bd7366af82f8e5bae737233ae (patch)
treefa670237f82f9558a094979cfed8dc6932a3992b /doc/plugins.org
parentec96ec469e9dff06bc503366ff7e3022c595d8f7 (diff)
downloadxmobar-38adaf0ded1ca40bd7366af82f8e5bae737233ae.tar.gz
xmobar-38adaf0ded1ca40bd7366af82f8e5bae737233ae.tar.bz2
Add documentation for QueueReader.
I added `QueueReader` as a section under `Software Transational Memory`, but it is all alone. Some other plugins actually use STM, and maybe they should actually go in that section too. I didn't make a safe versions since the plugin is not readable. It still would be nice to have, but I think exposing `stripActions` is the appropriate solution. That should be handled in a new PR I guess.
Diffstat (limited to 'doc/plugins.org')
-rw-r--r--doc/plugins.org44
1 files changed, 44 insertions, 0 deletions
diff --git a/doc/plugins.org b/doc/plugins.org
index 48999c2..a1fa4df 100644
--- a/doc/plugins.org
+++ b/doc/plugins.org
@@ -1436,6 +1436,50 @@ choice.
hPutStr writeHandle "Hello World"
#+end_src
+** Software Transactional Memory
+
+When invoking xmobar from other Haskell code it can be easier and
+more performant to use shared memory. The following plugins leverage
+=Control.Concurrent.STM= to realize these gains for xmobar.
+
+*** =QueueReader (TQueue a) (a -> String) String=
+
+ - Display data from a Haskell =TQueue a=.
+
+ - This plugin is only useful if you are running xmobar from another
+ haskell program like xmonad.
+
+ - You should make an =IO= safe =TQueue a= with =Control.Concurrent.STM.newTQueueIO=.
+ Write to it from the user code with =writeTQueue=, and read with =readTQueue=.
+ A common use is to overwite =ppOutput= from =XMonad.Hooks.DynamicLog= as shown
+ below.
+
+ #+begin_src haskell
+ main :: IO ()
+ main = do
+ q <- STM.newTQueueIO @String
+ bar <- forkIO $ xmobar myConf
+ { commands = Run (QueueReader q id "XMonadLog") : commands myConf }
+ xmonad $ def { logHook = logWorkspacesToQueue q }
+
+ logWorkspacesToQueue :: STM.TQueue String -> X ()
+ logWorkspacesToQueue q =
+ dynamicLogWithPP def { ppOutput = STM.atomically . STM.writeTQueue q }
+ where
+ -- Manage the PrettyPrinting configuration here.
+ ppLayout' :: String -> String
+ ppLayout' "Spacing Tall" = xpm "layout-spacing-tall"
+ ppLayout' "Spacing Mirror Tall" = xpm "layout-spacing-mirror"
+ ppLayout' "Spacing Full" = xpm "layout-full"
+ ppLayout' x = x
+
+ icon :: String -> String
+ icon path = "<icon=" ++ path ++ "/>"
+
+ xpm :: String -> String
+ xpm = icon . (++ ".xpm")
+ #+end_src
+
* Executing External Commands
In order to execute an external command you can either write the command