summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--contributing.org7
-rw-r--r--doc/using-haskell.org125
-rw-r--r--doc/write-your-own-plugin.org73
-rw-r--r--readme.org288
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!
diff --git a/readme.org b/readme.org
index 23758fa..017e3d9 100644
--- a/readme.org
+++ b/readme.org
@@ -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