Barr is a status line generator for Lemonbar. It is an alternative to the common method of using shell scripts to generate the bar's content. Barr is written in, and configured with, Ruby.
Barr aims to make creating and maintaining Lemonbar scripts much easier. At its core is a suite of re-usable and configurable Blocks. These blocks can be added to your bar as-is; configured to your liking; or extended to create your own behaviour. This allows status lines to be created in a more declarative manner.
$ gem install barr
If that doesn't work, you probably don't have Ruby installed. I'd recommend you install it via RVM or rbenv, though they're probably overkill if you don't already use Ruby regularly.
For a simpler install, check your distro's package manager. That should be fine.
To update to the latest release of Barr:
$ gem update barr
See Examples folder for more detailed usage examples.
Documentation about all available blocks and their options can be found further down in this document.
barr_example.rb
#!/usr/bin/env ruby
# pull in the Barr gem
require 'rubygems'
require 'barr'
# Create a new manager instance.
# The manager is responsible for organising the blocks and delivering their output to lemonbar
@manager = Barr::Manager.new
# Add a 'Whoami' block. This just outputs logged in username
# Give it a peach background, grey text and updates every 10000 seconds
# It will be aligned to the left of the bar
@manager.add Barr::Blocks::Whoami.new(bgcolor: '#FFAAAA', fgcolor: '#333333', interval: 10000)
# Add a 'Clock' block.
# Clocks can be formatted in the type strftime fashion. This example outputs the current Hour and Minute
# It will update every second.
# By default, the background text colour will be deferred to the Lemonbar config
# If FontAwesome font is available to lemonbar, it will be prepended with a clock icon.
@manager.add Barr::Blocks::Clock.new(icon: "\uf017", format: '%H:%M', align: :c, interval: 1)
# Add a 'CPU' block. This shows the current CPU usage (averaged across all cores if present)
# It will be aligned to the right side of of the bar
# As an interval is not provided, it will update every 5 seconds.
# It will be prepended with the text 'Cpu:'
@manager.add Barr::Blocks::CPU.new(icon: 'Cpu:', align: :r)
# Tell the manager to run the loop. This will continue indefinitely, outputing the data ready to be piped in to lemonbar.
@manager.run!
This can be piped in to lemonbar as usual:
#!/bin/bash
./barr_example.rb | lemonbar -g 800x30+960+00 -d -B "#333333" -f "Roboto Mono Medium:size=11" -f "Font Awesome:size=11" | sh
Which should have Lemonbar appear as:
All blocks inherit their behaviour from a base Block. This means that all blocks will respond to the following configuration options:
Option | Value | Description | Default |
---|---|---|---|
fgcolor |
RGB Hex string or - |
Equivalent to lemonbar's %{F} format. Takes a hex string in the format of #FFF , #FFFFFF , or #FFFFFFFF (for transparency). |
'-' |
bgcolor |
RGB Hex string or - |
As above. To use the configured lemonbar colors, use '-' . This also applies to the fgcolor option. |
'-' |
icon |
String | This is prepended to each blocks' data. It can be a normal string like 'CPU:' or a unicode string like "\uf164" (thumbs up in Font Awesome) |
'' |
interval |
Integer | How frequently the Block should perform its update! method in seconds. The block is drawn to lemonbar every second, this just affects how frequently the data can change. |
5 |
align |
Symbol | One of :l , :c , :r for left, centre and right alignment respectively. |
:l |
These are set when a Block is initialized:
@man = Barr::Manager.new
block1 = Barr::Block.new fgcolor: '#FF0000',
bgcolor: '#000000',
icon: 'I am:',
interval: 10,
align: :r
man.add block1
If you're unfamiliar with Ruby here's a couple of tips that might help with reading and writing your own blocks:
- Parentheses are optional most of the time. The exception is when their absense causes ambiguity as to which arguments belong to which methods.
- The arguments to
Barr::Block.new
are supplied as aHash
. This means that you don't need to put them in a specific order. - If you want to use a default value, you can just omit the option altogether.
- Whitespace isn't that important, at least compared to languages like Python. Feel free to use whitespace to make your code more readable.
For example, the following code:
@man = Barr::Manager.new()
block1 = Barr::Blocks::Whoami.new({fgcolor: '#FFF', bgcolor: '#000', align: :c})
@man.add(block1)
Is functionally the same as this:
@man = Barr::Manager.new
block1 = Barr::Blocks::Whoami.new align: :c,
fgcolor: '#FFF',
bgcolor: '#000'
@man.add block1
You can also add Blocks straight to the manager if you'd like to skip that step, or even mix/match:
@man = Barr::Manager.new
seperate_block = Barr::Blocks::Whoami.new
@man.add Barr::Blocks::Whoami.new bgcolor: '#000', fgcolor: '#FFF'
@man.add(Barr::Blocks::Whoami.new(icon: 'Me!', align: :c))
@man.add separate_block
Show battery status.
battery = Barr::Blocks::Battery.new show_remaining: true
Option | Value | Description | Default |
---|---|---|---|
show_remaining |
bool | Show the remaining battery time | true |
Requires Bspwm. Shows desktops for selected monitor. and highlights focused one. Unfocused desktops are clickable. Could do with some optimization work and feedback from people that use BSP frequently, especially with multiple monitors.
bsp = Barr::Blocks::Bspwm.new monitor: "DP-4", invert_focus_colors: true
Option | Value | Description | Default |
---|---|---|---|
focus_markers |
2 element Array | These are used to 'highlight' the active workspace. The first element is used on the left of the active workspace, the second element on the right. | ['>', '<'] |
invert_focus_colors |
bool | Should the block's fgcolor and bgcolor attributes be reversed for the workspace that is currently focused. |
false |
monitor |
String | The monitor ID (e.g. from xrandr ) that the bar should read the desktops from. |
First monitor found |
Shows the current date and/or time.
clock = Barr::Blocks::Clock.new format: '%m %b %Y', icon: 'Date: '
Option | Value | Description | Default |
---|---|---|---|
format |
strftime String | This takes a strftime formatted string. If you're not familiar with this syntax, you could use an online generator. | '%H:%M %m %b %Y' |
Requires Conky. Show a conky TEXT
formatted output. This is quite inefficient at the moment and if left running for prolonged periods will eat up your disk space. Otherwise works okay. Not all conky variables work well, will take a bit of trial and error.
conky = Barr::Blocks::Conky.new string: "${cpu}"
Option | Value | Description | Default |
---|---|---|---|
text |
Conky 'TEXT' string | String made up of one or more conky variables, as you might find in the TEXT section of a conkyrc |
REQUIRED |
Shows CPU load averaged across all cores.
cpu = Barr::Blocks::CPU.new
There are no CPU
block specific configurable options.
Shows selected filesystem's used and free space.
hdd = Barr::Blocks::HDD.new device: 'sda2'
Option | Value | Description | Default |
---|---|---|---|
device |
String | This is the name of the device for which you'd like to see free/used space. Something like /dev/sda2 . Run df -h in your terminal and look at the first column. |
REQUIRED |
Requires i3wm. Shows the current workspaces and highlights the active one. You can click a workspace name to change to there.
i3 = Barr::Blocks::I3.new focus_markers: ["\u02C3",'']
Option | Value | Description | Default |
---|---|---|---|
focus_markers |
2 element Array | These are used to 'highlight' the active workspace. The first element is used on the left of the active workspace, the second element on the right. | ['>', '<'] |
invert_focus_colors |
bool | Should the block's fgcolor and bgcolor attributes be reversed for the workspace that is currently focused. |
false |
Shows the selected adaptor's IP (IPv4 by default) address. If no device is specified, it will make a guess.
ip = Barr::Blocks::IP.new device: 'enp3s0'
Option | Value | Description | Default |
---|---|---|---|
device |
String | The name of the device | 192 |
ipv6 |
Boolean | Get the IPv6 address of the device | false |
Shows current RAM usage.
mem = Barr::Blocks::Mem.new
There are no Mem
block specific configurable options.
Shows the number of currently active processes on your system.
proc = Barr::Blocks::Processes.new
There are no Processes
block specific configurable options.
Requires Rhythmbox and rhythmbox-client. Shows currently playing artist and/or track, as well as control buttons. Control buttons use FontAwesome.
rb = Barr::Blocks::Rhythmbox.new buttons: false
Option | Value | Description | Default |
---|---|---|---|
artist |
bool | Set to true or false to set whether or not the currently playing artist should be shown. |
true |
buttons |
bool | As above, but for the player control buttons | true |
title |
bool | As above, but for the track title | true |
Requires MPD server (mpd or mopidy) and MPC. Shows currently playing artist and/or track, as well as control buttons. Control buttons use FontAwesome.
mpd = Barr::Blocks::MPD.new buttons: false
Option | Value | Description | Default |
---|---|---|---|
artist |
bool | Set to true or false to set whether or not the currently playing artist should be shown. |
true |
buttons |
bool | As above, but for the player control buttons | true |
title |
bool | As above, but for the track title | true |
ps. Most of the code for this block was directly taken from the above Rhythmbox block so most of the credit should go to them 😉
This block is a simple string to be used as a separator between other blocks.
Option | Value | Description | Default |
---|---|---|---|
symbol |
any string | The string to use as a separator | | |
Shows the current temperature and summary of a given location ID. Clicking it will open the full report in your browser.
temp = Barr::Blocks::Temperature.new location: '11921', unit: 'F'
Option | Value | Description | Default |
---|---|---|---|
location |
Yahoo Weather string | The ID Yahoo Weather uses for your chosen location. Search for your location then use the number that appears at the end of the URL. For example, New York is 2459115 | REQUIRED |
unit |
'C' or 'F' |
Choose between Celcius and Fahrenheit. | 'C' |
Shows the currently logged in user.
who = Barr::Blocks::Whoami.new
There are no Whoami
block specific configurable options.
It's reasonably simple to add your own block to your script. Create a class
that inherits from Barr::Block
and add your custom initialize
and update!
methods. The Barr::Manager
object will read your block's @output
on each update.
For example, a block which increments an integer might look like this:
#!/usr/bin/env ruby
require 'rubygems'
require 'barr'
class Incrementer < Barr::Block
def initialize opts={} # Don't forget to accept your options hash!
# super ensures the common configurable options can be set
super
# Accept a 'count' option, defaulting to 0 if none is provided
@count = opts[:count] || 0
end
def update!
# Increment the current count
@count += 1
# Set the @output to be the current count. This is what will be sent to lemonbar
@output = @count.to_s
end
end
@man = Barr::Manager.new
block = Incrementer.new count: 1, align: :r
@man.add block
@man.run!
Here are a few things I have planned
MPD support- Powerline styling options
- More configuration for existing blocks
- Some form of Conky support
- Volume display / control
- Stricter option typing
- RSS support
Bug reports and pull requests are welcome on GitHub at https://github.com/OkayDave/barr. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
I'd love to see PRs for more blocks. If you do make any, please ensure that you've added their config options to this README and that you've written some specs for it (including stubbing / mocking out any system and/or API calls it makes).
If there's a block you'd like to see, but don't have the time, knowledge, or desire to make one then please do open a request on the Issue Tracker.
The gem is available as open source under the terms of the MIT License.