diff options
| -rw-r--r-- | contributing.org | 78 | ||||
| -rw-r--r-- | doc/write-your-own-plugin.org | 74 | ||||
| -rw-r--r-- | readme.org | 6 |
3 files changed, 84 insertions, 74 deletions
diff --git a/contributing.org b/contributing.org index 41c2af1..14bce0d 100644 --- a/contributing.org +++ b/contributing.org @@ -19,9 +19,10 @@ this case please don't merge any branches, but actually rebase! This is a very nifty feature that =git= offers in order to remain a clean history. -Give your commits descriptive names! Further, it's also highly recommended to -add a description of /why/ you made a certain change. The syntax for this is -*commit message*, blank line, *more description*. For example: +Give your commits descriptive names! Further, it's also highly +recommended to add a description of /why/ you made a certain change. +The syntax for this is *commit message*, blank line, *more description*. +For example: #+begin_src shell Commit Message (max. 50 characters) @@ -48,72 +49,5 @@ request: 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]]. - -* Writing Your Own 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 [[https://github.com/jaor/xmobar/blob/master/examples/xmobar.hs][examples/xmobar.hs]] for an example of -a plugin that runs just once, and [[https://github.com/jaor/xmobar/blob/master/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 - -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. - -** Using a Plugin - -To use your new plugin, you need to use a pure Haskell configuration for -xmobar, and load your definitions there. 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! +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]]. diff --git a/doc/write-your-own-plugin.org b/doc/write-your-own-plugin.org new file mode 100644 index 0000000..2645c3b --- /dev/null +++ b/doc/write-your-own-plugin.org @@ -0,0 +1,74 @@ +* Writing Your Own 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 [[https://github.com/jaor/xmobar/blob/master/examples/xmobar.hs][examples/xmobar.hs]] for an example of +a plugin that runs just once, and [[https://github.com/jaor/xmobar/blob/master/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, and load your definitions there. 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! @@ -209,8 +209,10 @@ Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2: - If you want to jump straight into configuring xmobar, head over to the [[./doc/quick-start.org][quick-start]] guide. -- If you want to know how to write your own plugin, or how to contribute - to the xmobar project, check out [[contributing.org][contributing]]. +- 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]]. * Authors and credits |