.config/awesome/lain/wiki/watch.md

   1 ## Usage
   2
   3 [Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
   4
   5 ### Description
   6
   7 Template for asynchronous watcher widgets.
   8
   9 Executes an input command and makes the user feed a `wibox.widget` with the output.
  10
  11 ```lua
  12 local mywatch = lain.widget.watch()
  13 ```
  14
  15 This has been implemented in Awesome 4.0 as [`awful.widget.watch`](https://awesomewm.org/doc/api/classes/awful.widget.watch.html). But while Awesome `watch` returns only the widget, Lain one returns a table including its timer and internal update function too.
  16
  17 ## Input table
  18
  19 Variable | Meaning | Type | Default
  20 --- | --- | --- | ---
  21 `widget` | Widget to feed | `wibox.widget` | `wibox.widget.textbox`
  22 `timeout` | Refresh timeout seconds | number | 5
  23 `cmd` | The command to execute | string **or** table | `nil`
  24 `nostart` | Widget timer doesn't start immediately | boolean | false
  25 `stoppable` | Widget timer is stoppable | boolean | false
  26 `settings` | User settings | function | see [Default `settings` function](https://github.com/lcpz/lain/wiki/watch#default-settings-function)
  27
  28 If your command needs a shell, you need to set `cmd` as an array of 3 strings, where the first contains the shell, the second contains `-c`, and the third contains the actual command. Example:
  29
  30 ```lua
  31 cmd = { awful.util.shell, "-c", "myactualcommand" }
  32 ```
  33
  34 `settings` can use the string `output`, which is the output of `cmd`.
  35
  36 ### Default `settings` function
  37
  38 ```lua
  39 settings = function() widget:set_text(output) end
  40 ```
  41 ## Output table
  42
  43 Variable | Meaning | Type
  44 --- | --- | ---
  45 `widget` | The widget | input widget type or `wibox.widget.textbox`
  46 `update` | Update `widget` | function
  47 `timer` | The widget timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html) or `nil`
  48
  49 The `update` function can be used to refresh the widget before `timeout` expires.
  50
  51 If `stoppable == true`, the widget will have an ad-hoc timer, which you can control though `timer` variable.
  52
  53 ## Use case examples
  54
  55 ### bitcoin
  56
  57 ```lua
  58 -- Bitcoin to USD current price, using Coinbase V1 API
  59 local bitcoin = lain.widget.watch({
  60     timeout = 43200, -- half day
  61     stoppable = true,
  62     cmd = "curl -m5 -s 'https://coinbase.com/api/v1/prices/buy'",
  63     settings = function()
  64         local btc, pos, err = require("lain.util").dkjson.decode(output, 1, nil)
  65         local btc_price = (not err and btc and btc["subtotal"]["amount"]) or "N/A"
  66
  67         -- customize here
  68         widget:set_text(btc_price)
  69     end
  70 })
  71 ```
  72
  73 ### btrfs
  74
  75 ```lua
  76 -- btrfs root df
  77 local myrootfs = lain.widget.watch({
  78     timeout = 600,
  79     cmd = "btrfs filesystem df -g /",
  80     settings  = function()
  81         local total, used  = string.match(output, "Data.-total=(%d+%.%d+)GiB.-used=(%d+%.%d+)GiB")
  82         local percent_used = math.ceil((tonumber(used) / tonumber(total)) * 100)
  83
  84         -- customize here
  85         widget:set_text(" [/: " .. percent_used .. "%] ")
  86     end
  87 })
  88 ```
  89
  90 ### cmus
  91
  92 ```lua
  93 -- cmus audio player
  94 local cmus = lain.widget.watch({
  95     timeout = 2,
  96     stoppable = true,
  97     cmd = "cmus-remote -Q",
  98     settings = function()
  99         local cmus_now = {
 100             state   = "N/A",
 101             artist  = "N/A",
 102             title   = "N/A",
 103             album   = "N/A"
 104         }
 105
 106         for w in string.gmatch(output, "(.-)tag") do
 107             a, b = w:match("(%w+) (.-)\n")
 108             cmus_now[a] = b
 109         end
 110
 111         -- customize here
 112         widget:set_text(cmus_now.artist .. " - " .. cmus_now.title)
 113     end
 114 })
 115 ```
 116
 117 ### maildir
 118
 119 ```lua
 120 -- checks whether there are files in the "new" directories of a mail dirtree
 121 local mailpath = "~/Mail"
 122 local mymaildir = lain.widget.watch({
 123     timeout = 60,
 124     stoppable = true,
 125     cmd = { awful.util.shell, "-c", string.format("ls -1dr %s/*/new/*", mailpath) },
 126     settings = function()
 127         local inbox_now = { digest = "" }
 128
 129         for dir in output:gmatch(".-/(%w+)/new") do
 130             inbox_now[dir] = 1
 131             for _ in output:gmatch(dir) do
 132                 inbox_now[dir] = inbox_now[dir] + 1
 133             end
 134             if #inbox_now.digest > 0 then inbox_now.digest = inbox_now.digest .. ", " end
 135             inbox_now.digest = inbox_now.digest .. string.format("%s (%d)", dir, inbox_now[dir])
 136         end
 137
 138         -- customize here
 139         widget:set_text("mail: " .. inbox_now.digest)
 140     end
 141 })
 142 ```
 143
 144 ### mpris
 145
 146 ```lua
 147 -- infos from mpris clients such as spotify and VLC
 148 -- based on https://github.com/acrisci/playerctl
 149 local mpris = lain.widget.watch({
 150     cmd = "playerctl status && playerctl metadata",
 151     timeout = 2,
 152     stoppable = true,
 153     settings = function()
 154          local escape_f  = require("awful.util").escape
 155          local mpris_now = {
 156              state        = "N/A",
 157              artist       = "N/A",
 158              title        = "N/A",
 159              art_url      = "N/A",
 160              album        = "N/A",
 161              album_artist = "N/A"
 162          }
 163
 164          mpris_now.state = string.match(output, "Playing") or
 165                            string.match(output, "Paused")  or "N/A"
 166
 167          for k, v in string.gmatch(output, "'[^:]+:([^']+)':[%s]<%[?'([^']+)'%]?>")
 168          do
 169              if     k == "artUrl"      then mpris_now.art_url      = v
 170              elseif k == "artist"      then mpris_now.artist       = escape_f(v)
 171              elseif k == "title"       then mpris_now.title        = escape_f(v)
 172              elseif k == "album"       then mpris_now.album        = escape_f(v)
 173              elseif k == "albumArtist" then mpris_now.album_artist = escape_f(v)
 174              end
 175          end
 176
 177         -- customize here
 178         widget:set_text(mpris_now.artist .. " - " .. mpris_now.title)
 179     end
 180 })
 181 ```
 182
 183 ### upower
 184
 185 ```lua
 186 -- battery infos from freedesktop upower
 187 local mybattery = lain.widget.watch({
 188     timeout = 30,
 189     cmd = { awful.util.shell, "-c", "upower -i /org/freedesktop/UPower/devices/battery_BAT | sed -n '/present/,/icon-name/p'" },
 190     settings = function()
 191         local bat_now = {
 192             present      = "N/A",
 193             state        = "N/A",
 194             warninglevel = "N/A",
 195             energy       = "N/A",
 196             energyfull   = "N/A",
 197             energyrate   = "N/A",
 198             voltage      = "N/A",
 199             percentage   = "N/A",
 200             capacity     = "N/A",
 201             icon         = "N/A"
 202         }
 203
 204         for k, v in string.gmatch(output, '([%a]+[%a|-]+):%s*([%a|%d]+[,|%a|%d]-)') do
 205             if     k == "present"       then bat_now.present      = v
 206             elseif k == "state"         then bat_now.state        = v
 207             elseif k == "warning-level" then bat_now.warninglevel = v
 208             elseif k == "energy"        then bat_now.energy       = string.gsub(v, ",", ".") -- Wh
 209             elseif k == "energy-full"   then bat_now.energyfull   = string.gsub(v, ",", ".") -- Wh
 210             elseif k == "energy-rate"   then bat_now.energyrate   = string.gsub(v, ",", ".") -- W
 211             elseif k == "voltage"       then bat_now.voltage      = string.gsub(v, ",", ".") -- V
 212             elseif k == "percentage"    then bat_now.percentage   = tonumber(v)              -- %
 213             elseif k == "capacity"      then bat_now.capacity     = string.gsub(v, ",", ".") -- %
 214             elseif k == "icon-name"     then bat_now.icon         = v
 215             end
 216         end
 217
 218         -- customize here
 219         widget:set_text("Bat: " .. bat_now.percentage .. " " .. bat_now.state)
 220     end
 221 })
 222 ```