diff options
| -rw-r--r-- | contributing.org | 7 | ||||
| -rw-r--r-- | doc/using-haskell.org | 125 | ||||
| -rw-r--r-- | doc/write-your-own-plugin.org | 73 | ||||
| -rw-r--r-- | readme.org | 288 |
4 files changed, 254 insertions, 239 deletions
diff --git a/contributing.org b/contributing.org index f5ea875..62ae6cb 100644 --- a/contributing.org +++ b/contributing.org @@ -46,7 +46,6 @@ problems you are having, as well as the proposed solution. - A brief summary of how your commits fit together to achieve this (if necessary). - Please also remember to update the =changelog.md= file, as well as - any other documentation that your pull request touches upon. For - example, if you add a new plugin (see [[./doc/write-your-own-plugin.org][here]] for more information) - you should update the [[./doc/plugins.org][plugins documentation]]. + Please also remember to update the =changelog.md= file, as well as any other + documentation that your pull request touches upon. For example, if you + add a new plugin you should update the [[./doc/plugins.org][plugins documentation]]. diff --git a/doc/using-haskell.org b/doc/using-haskell.org new file mode 100644 index 0000000..5c48c06 --- /dev/null +++ b/doc/using-haskell.org @@ -0,0 +1,125 @@ +#+title: Using Haskell + +* Writing your own xmobar in Haskell + :PROPERTIES: + :CUSTOM_ID: xmobar-in-haskell + :END: + + Besides an standalone program, ~xmobar~ is also a Haskell library providing + an interface to write your own status bar. You can write, instead of a + configuration file, a real Haskell program that will be compiled and run + when you invoke =xmobar=. + + Make sure that ~ghc~ will be able to locate the xmobar library, e.g. with + + #+begin_src shell + cabal install --lib xmobar + #+end_src + + and then write your Haskell configuration and main function using the + functions and types exported in the library, which closely resemble those + used in configuration files. Here's a small example: + + #+begin_src haskell + import Xmobar + + config :: Config + config = + defaultConfig + { font = "xft:Terminus-8", + allDesktops = True, + alpha = 200, + commands = + [ Run XMonadLog, + Run $ Memory ["t", "Mem: <usedratio>%"] 10, + Run $ Kbd [], + Run $ Date "%a %_d %b %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10 + ], + template = "%XMonadLog% }{ %kbd% | %date% | %memory%", + alignSep = "}{" + } + + main :: IO () + main = xmobar config + #+end_src + + You can then for instance run =ghc --make xmobar.hs= to create a new xmobar + executable running exactly the monitors defined above. Or put your + =xmobar.hs= program in =~/.config/xmobar/xmobar.hs= and, when running the + system-wide xmobar, it will notice that you have your own implementation + and (re)compile and run it as needed. + +* Writing a plugin + :PROPERTIES: + :CUSTOM_ID: writing-a-plugin + :END: + Writing a plugin for xmobar is very simple! + + First, you need to create a data type with at least one constructor. Next + you must declare this data type an instance of the =Exec= class, by defining + the one needed method (alternatively =start= or =run=) and 3 optional ones + (=alias=, =rate=, and =trigger=): + + #+begin_src haskell + start :: e -> (String -> IO ()) -> IO () + run :: e -> IO String + rate :: e -> Int + alias :: e -> String + trigger :: e -> (Maybe SignalType -> IO ()) -> IO () + #+end_src + + =start= must receive a callback to be used to display the =String= produced by + the plugin. This method can be used for plugins that need to perform + asynchronous actions. See =src/Xmobar/Plugins/PipeReader.hs= for an example. + + =run= can be used for simpler plugins. If you define only =run= the plugin + will be run every second. To overwrite this default you just need to + implement =rate=, which must return the number of tenth of seconds between + every successive runs. See [[../examples/xmobar.hs][examples/xmobar.hs]] for an example of a plugin + that runs just once, and [[../src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one that + implements =rate=. + + Notice that Date could be implemented as: + + #+begin_src haskell + instance Exec Date where + alias (Date _ a _) = a + start (Date f _ r) = date f r + + date :: String -> Int -> (String -> IO ()) -> IO () + date format r callback = do go + where go = do + t <- toCalendarTime =<< getClockTime + callback $ formatCalendarTime defaultTimeLocale format t + tenthSeconds r >> go + #+end_src + + Modulo some technicalities like refreshing the time-zone in a clever way, + this implementation is equivalent to the one you can read in + =Plugins/Date.hs=. + + =alias= is the name to be used in the output template. Default alias will be + the data type constructor. + + After that your type constructor can be used as an argument for the + Runnable type constructor =Run= in the =commands= list of the configuration + options. + + If your plugin only implements =alias= and =start=, then it is advisable to + put it into the =Xmobar/Plugins/Monitors= directory and use one of the many + =run*= functions in [[../src/Xmobar/Plugins/Monitors/Common/Run.hs][Xmobar.Plugins.Monitors.Run]] in order to define + =start=. The =Exec= instance should then live in [[../src/Xmobar/Plugins/Monitors.hs][Xmobar.Plugins.Monitors]]. + +* Using a Plugin + + To use your new plugin, you just need to use a pure Haskell configuration + for xmobar (as explained [[#xmobar-in-haskell][above]]) and load your definitions in your =xmobar.hs= + file. You can see an example in [[../examples/xmobar.hs][examples/xmobar.hs]] showing you how to write + a Haskell configuration that uses a new plugin, all in one file. + + When xmobar runs with the full path to that Haskell file as its argument + (or if you put it in =~/.config/xmobar/xmobar.hs=), and with the xmobar + library installed (e.g., with =cabal install --lib xmobar=), the Haskell + code will be compiled as needed, and the new executable spawned for you. + + That's it! diff --git a/doc/write-your-own-plugin.org b/doc/write-your-own-plugin.org deleted file mode 100644 index fb1ca85..0000000 --- a/doc/write-your-own-plugin.org +++ /dev/null @@ -1,73 +0,0 @@ -#+title: Writing your own plugin - -*** Writing a plugin - Writing a plugin for xmobar is very simple! - - First, you need to create a data type with at least one constructor. Next - you must declare this data type an instance of the =Exec= class, by defining - the one needed method (alternatively =start= or =run=) and 3 optional ones - (=alias=, =rate=, and =trigger=): - - #+begin_src haskell - start :: e -> (String -> IO ()) -> IO () - run :: e -> IO String - rate :: e -> Int - alias :: e -> String - trigger :: e -> (Maybe SignalType -> IO ()) -> IO () - #+end_src - - =start= must receive a callback to be used to display the =String= produced by - the plugin. This method can be used for plugins that need to perform - asynchronous actions. See =src/Xmobar/Plugins/PipeReader.hs= for an example. - - =run= can be used for simpler plugins. If you define only =run= the plugin - will be run every second. To overwrite this default you just need to - implement =rate=, which must return the number of tenth of seconds between - every successive runs. See [[../examples/xmobar.hs][examples/xmobar.hs]] for an example of a plugin - that runs just once, and [[../src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one that - implements =rate=. - - Notice that Date could be implemented as: - - #+begin_src haskell - instance Exec Date where - alias (Date _ a _) = a - start (Date f _ r) = date f r - - date :: String -> Int -> (String -> IO ()) -> IO () - date format r callback = do go - where go = do - t <- toCalendarTime =<< getClockTime - callback $ formatCalendarTime defaultTimeLocale format t - tenthSeconds r >> go - #+end_src - - Modulo some technicalities like refreshing the time-zone in a clever way, - this implementation is equivalent to the one you can read in - =Plugins/Date.hs=. - - =alias= is the name to be used in the output template. Default alias will be - the data type constructor. - - After that your type constructor can be used as an argument for the - Runnable type constructor =Run= in the =commands= list of the configuration - options. - - If your plugin only implements =alias= and =start=, then it is advisable to - put it into the =Xmobar/Plugins/Monitors= directory and use one of the many - =run*= functions in [[../src/Xmobar/Plugins/Monitors/Common/Run.hs][Xmobar.Plugins.Monitors.Run]] in order to define - =start=. The =Exec= instance should then live in [[../src/Xmobar/Plugins/Monitors.hs][Xmobar.Plugins.Monitors]]. - -*** Using a Plugin - - To use your new plugin, you need to use a pure Haskell configuration for - xmobar (as explained [[../readme.org#xmobar-in-haskell][here)]] and load your definitions in your =xmobar.hs= - file. You can see an example in [[../examples/xmobar.hs][examples/xmobar.hs]] showing you how to - write a Haskell configuration that uses a new plugin, all in one file. - - When xmobar runs with the full path to that Haskell file as its argument - (or if you put it in =~/.config/xmobar/xmobar.hs=), and with the xmobar - library installed (e.g., with =cabal install --lib xmobar=), the Haskell - code will be compiled as needed, and the new executable spawned for you. - - That's it! @@ -33,179 +33,143 @@ channel, ~#xmobar~, at [[ircs://irc.libera.chat][Libera]]. :PROPERTIES: :CUSTOM_ID: installation :END: -*** From your system's package manager +** From your system's package manager - Xmobar is probably available from your distributions package - manager! Most distributions compile xmobar with the =all_extensions= - flag, so you don't have to. + Xmobar is probably available from your distributions package + manager! Most distributions compile xmobar with the =all_extensions= + flag, so you don't have to. - - Arch Linux - #+begin_src shell - pacman -S xmobar - #+end_src + - Arch Linux + #+begin_src shell + pacman -S xmobar + #+end_src - - Debian/Ubuntu based - #+begin_src shell - apt install xmobar - #+end_src + - Debian/Ubuntu based + #+begin_src shell + apt install xmobar + #+end_src - - OpenSUSE - #+begin_src shell - zypper install xmobar - #+end_src + - OpenSUSE + #+begin_src shell + zypper install xmobar + #+end_src - - Void Linux - #+begin_src shell - xbps-install xmobar - #+end_src + - Void Linux + #+begin_src shell + xbps-install xmobar + #+end_src - - Gentoo - #+begin_src shell - emerge --ask xmobar - #+end_src + - Gentoo + #+begin_src shell + emerge --ask xmobar + #+end_src -*** Using cabal-install +** Using cabal-install - Xmobar is available from [[http://hackage.haskell.org/package/xmobar/][Hackage]], and you can install it using - =cabal-install=: + Xmobar is available from [[http://hackage.haskell.org/package/xmobar/][Hackage]], and you can install it using + =cabal-install=: - #+begin_src shell - cabal install xmobar - #+end_src + #+begin_src shell + cabal install xmobar + #+end_src - Starting with version 0.35.1, xmobar now requires at least GHC - version 8.4.x. to build. See [[https://codeberg.org/xmobar/xmobar/issues/461][this issue]] for more information. + Starting with version 0.35.1, xmobar now requires at least GHC + version 8.4.x. to build. See [[https://codeberg.org/xmobar/xmobar/issues/461][this issue]] for more information. - See [[file:doc/compiling.org][compiling]] for a list of optional compilation flags that will - enable some optional plugins. For instance, to install xmobar with - all the bells and whistles (this is probably what you want), use: + See [[file:doc/compiling.org][compiling]] for a list of optional compilation flags that will + enable some optional plugins. For instance, to install xmobar with + all the bells and whistles (this is probably what you want), use: - #+begin_src shell - cabal install xmobar --flags="all_extensions" - #+end_src + #+begin_src shell + cabal install xmobar --flags="all_extensions" + #+end_src -*** From source +** From source - See [[file:doc/compiling.org][compiling]]. + See [[file:doc/compiling.org][compiling]]. * Running xmobar -*** Running xmobar with a configuration file - You can run xmobar with: - - #+begin_src shell - xmobar /path/to/config & - #+end_src - - or - - #+begin_src shell - xmobar & - #+end_src - - if you have the default configuration file saved as - =$XDG_CONFIG_HOME/xmobar/xmobarrc= (defaulting to - =~/.config/xmobar/xmobarrc=), or =~/.xmobarrc=. - -*** Writing your own xmobar in Haskell - :PROPERTIES: - :CUSTOM_ID: xmobar-in-haskell - :END: - - It is possible to install xmobar as a library and use it to write your own - xmobar using Haskell instead of using a configuration file. (This is very - similar to how [[http://xmonad.org][xmonad]] works.) - - Make sure that ~ghc~ will be able to locate the xmobar library, e.g. with - - #+begin_src shell - cabal install --lib xmobar - #+end_src - - and then write your Haskell configuration and main function using the - functions and types exported in the library, which closely resemble those - used in configuration files. Here's a small example: - - #+begin_src haskell - import Xmobar - - config :: Config - config = - defaultConfig - { font = "xft:Terminus-8", - allDesktops = True, - alpha = 200, - commands = - [ Run XMonadLog, - Run $ Memory ["t", "Mem: <usedratio>%"] 10, - Run $ Kbd [], - Run $ Date "%a %_d %b %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10 - ], - template = "%XMonadLog% }{ %kbd% | %date% | %memory%", - alignSep = "}{" - } - - main :: IO () - main = xmobar config - #+end_src - - You can then for instance run =ghc --make xmobar.hs= to create a new xmobar - executable running exactly the monitors defined above. Or put your - =xmobar.hs= program in =~/.config/xmobar/xmobar.hs= and, when running the - system-wide xmobar, it will notice that you have your own implementation - and (re)compile and run it as needed. See also this [[./examples/xmobar.hs][extended example]]. - -*** Running xmobar in text mode - - By default, xmobar will run as an X11 application, in a docked - window, but it is possible to redirect xmobar's to the standard - output, optionally with color escape sequences. In this mode, - xmobar can be run inside a terminal o console, or its output piped - to other applications, and there is no need for an X11 display - (so, for instance, you could pipe xmobar's output to a Wayland - application, such as swaybar.) - - To run xmobar in text mode, either pass the =-T= flag to its - invocation: - - #+begin_src shell - xmobar -T /path/to/config & - #+end_src - - or set the parameter =textOutput= to True in its configuration. You - can also specify the format of color escapes, for instance, - omitting them altogether with ~Plain~: - - #+begin_src shell - xmobar -TPlain /path/to/config & - #+end_src - - Other options are ~Ansi~, ~Pango~, and ~Swaybar~. - -*** Using xmobar in Wayland with swaybar or waybar - - In text mode, xmobar can be told to ouput its information using - pango markup for colors and fonts, and it that way you can use it - with swaybar or waybar, if you don't have actions or boxes in your - template. Here's a minimal ~bar~ configuration for sway's - configuration file: - - #+begin_src conf - bar { - status_command xmobar -TPango - pango_markup enabled - } - #+end_src - - In case you want to use boxes around text or click actions in your - template, you can use instead the format ~Swaybar~, which supports - both. This output format follows the JSON /swaybar-protocol/ - defined by swaybar. Configure it simply with: - - #+begin_src conf - bar { - status_command xmobar -TSwaybar - } - #+end_src +** Running xmobar with a configuration file + You can run xmobar with: + + #+begin_src shell + xmobar /path/to/config & + #+end_src + + or + + #+begin_src shell + xmobar & + #+end_src + + if you have the default configuration file saved as + =$XDG_CONFIG_HOME/xmobar/xmobarrc= (defaulting to =~/.config/xmobar/xmobarrc=), + or =~/.xmobarrc=. + + All the available command line switches and configuration parameters are + described in [[file:quick-start.org][the quick start guide]] and [[file:plugins.org][the plugins documentation]]. +** Writing your own xmobar in Haskell + + One can use ~xmobar~ as a regular program, via its configuration file, + without having to write any code. It also is possible to install xmobar as + a library and use it to write your own xmobar using Haskell instead of + using a configuration file. (This is very similar to how [[http://xmonad.org][xmonad]] works.) + That gives you the ability of using Haskell and its libraries to extend + xmobar to your heart's content. If you are a programmer, take a look at + [[file:doc/using-haskell.org][here]] to learn more. + +** Running xmobar in text mode + + By default, xmobar will run as an X11 application, in a docked + window, but it is possible to redirect xmobar's to the standard + output, optionally with color escape sequences. In this mode, + xmobar can be run inside a terminal o console, or its output piped + to other applications, and there is no need for an X11 display + (so, for instance, you could pipe xmobar's output to a Wayland + application, such as swaybar.) + + To run xmobar in text mode, either pass the =-T= flag to its + invocation: + + #+begin_src shell + xmobar -T /path/to/config & + #+end_src + + or set the parameter =textOutput= to True in its configuration. You + can also specify the format of color escapes, for instance, + omitting them altogether with ~Plain~: + + #+begin_src shell + xmobar -TPlain /path/to/config & + #+end_src + + Other options are ~Ansi~, ~Pango~, and ~Swaybar~. + +** Using xmobar in Wayland with swaybar or waybar + + In text mode, xmobar can be told to ouput its information using + pango markup for colors and fonts, and it that way you can use it + with swaybar or waybar, if you don't have actions or boxes in your + template. Here's a minimal ~bar~ configuration for sway's + configuration file: + + #+begin_src conf + bar { + status_command xmobar -TPango + pango_markup enabled + } + #+end_src + + In case you want to use boxes around text or click actions in your + template, you can use instead the format ~Swaybar~, which supports + both. This output format follows the JSON /swaybar-protocol/ + defined by swaybar. Configure it simply with: + + #+begin_src conf + bar { + status_command xmobar -TSwaybar + } + #+end_src * Configuration and further Links @@ -221,7 +185,7 @@ channel, ~#xmobar~, at [[ircs://irc.libera.chat][Libera]]. - If you want to know how to contribute to the xmobar project, check out [[contributing.org][contributing]]. - - If you want to write your own plugins, see [[./doc/write-your-own-plugin.org][Write your own plugin]]. + - If you want to write your own plugins, see [[./doc/using-haskell.org#writing-a-plugin][writing a plugin]]. - For elaborated examples of how to use xmobar as a Haskell library to create your monitors, see [[https://codeberg.org/jao/xmobar-config][this repo at jao/xmobar-config]]. @@ -264,9 +228,9 @@ channel, ~#xmobar~, at [[ircs://irc.libera.chat][Libera]]. * License -This software is released under a BSD-style license. See [[https://codeberg.org/xmobar/xmobar/src/branch/master/license][license]] for more -details. + This software is released under a BSD-style license. See [[https://codeberg.org/xmobar/xmobar/src/branch/master/license][license]] for more + details. -Copyright © 2010-2022 Jose Antonio Ortega Ruiz + Copyright © 2010-2022 Jose Antonio Ortega Ruiz -Copyright © 2007-2010 Andrea Rossato + Copyright © 2007-2010 Andrea Rossato |