Bashets

From awesome
Jump to: navigation, search

Intro[edit]

Bashets is a user widget library (but really not only for widget-related things) powered by shell scripts (but more data sources to come).

Bashets is glue code which empowers you to fetch data somewhere, and put it somewhere. It is a distinct approach from Obvious or Vicious, which try to implement and package predefined widgets themselves.

Supported sources are:

  • Launch shell script for timed execution.
  • Launch shell script to provide data itself.
  • Listen to DBus signals and fetch data from them.
  • Fetch data from a user-provided function.

Supported destinations are:

  • A widget's content. The widget could be a textbox, imagebox, progressbar, or graph.
  • A callback function. You are able to catch data updates in your own way.

Note: Bashets is compatible with awesome 3.5 and greater.

Why you should use it[edit]

Unix-like systems have over 9000 terminal tools for data acquisition and processing. So, the simplest way to get data from somewhere is the shellscript.

If you choose a widget system, you really choose a mean of representing the processed data. For example, your CPU usage could be represented as: graph, progressbar, pie-diagram or plain text.

So, what should you do? Yes, you should write a shellscript to process data, and have a widget to represent the value.

And bashets is a small piece of glue code to simplify the task and abstract you from working with raw timers, awesome-client or dbus apis of awesome WM.

You should only write one bashets.register() call in your rc.lua per widget - and your counters and graphs should be alive.

What can be done with it[edit]

A real-world example

In the example to the right, you can see my current desktop with the following widgets:

  • Keyboard layout (textbox)
  • Battery charge (imagebox)
  • Music player widget with coverart display and progressbar (textbox + imagebox + progressbar combination).

Irony: Yes, Wicked widgets are the grandfather of all current awesome widget libraries and there should be a symphony in its honour.

Of course, I am able to held all routinous tasks myself: to create the timers for scheduled mpc/acpi calls, to create a shellscript to feed keyboard widget with data.

But instead, it costs me not more than 5 lines of lua code with the help of bashets.

Here's my old desktop, where I had 7 progressbars showing info from different sources. Without Bashets this could've been a nightmare or a birth of several separate widget modules, but with Bashets it took 7 lines of lua code.

How to use it[edit]

  1. Get bashets.lua and copy it to /usr/share/awesome/lib
  2. Add require("bashets") to the top of your rc.lua
  3. Create a widget:
    • Textbox:
      xkbw = wibox.widget.textbox()
    • Imagebox:
      batw = wibox.widget.imagebox()
    • Progress Bar:
      coverpg = awful.widget.progressbar()
    • Graph:
      cpugraph = awful.widget.graph()
  4. Register a data source to update the widget
    • A timed-execution shell script:
      bashets.register("batpic.sh", {widget = batw, separator = " ", update_time=1})
    • External shell script:
      bashets.register("xkb.sh", {widget = xkbw, update_time = 1, external = true, format = ' $1'})
    • DBus signal:
      bashets.register("org.freedesktop.Hal.Manager", {dbus = true, busname = "system", widget = datew, format="$3"})
  5. Edit format string and separator such as you need (by default, "$1" and space symbol are used).
  6. After all widget registrations, add the line: bashets.start()
  7. Add the line bashets.stop() adjacent to awesome.quit() if you use external shell scripts. Otherwise your terminal will be flooded with DBus errors.
  8. Enjoy!

A note about "timed-execution" vs "external" shell scripts:

  • Timed-execution scripts are launched every update_time period
  • External shell scripts launch with awesome and work in the background, they provide widgets with data through awesome-client

From the user's viewpoint, there should be no difference between the two. They should print several lines to stdout, nothing more.

To learn more, read the docs.

PS: The previous version of this page covers more of the design and ideology behind Bashets.

Get Bashets[edit]

Bashets is hosted at Gitorious, alongside thorough documentation. There's also an Arch Linux package in AUR.