# easyconf-lemonbar (eclb)

A small python script to easily configure lemonbar. Uses a simple yaml file to
declaratively define your custom bar, and includes useful features such as
asynchronous refreshing and signal handling. Concept inspired by
[UtkarshVerma/dwmblocks-async](https://github.com/UtkarshVerma/dwmblocks-async).

## Installation
### Prerequisites
 - python3: a fairly recent version
 - lemonbar: your fork of choice
 - poetry: python package manager

This project uses [poetry](https://github.com/python-poetry/poetry) as the
package manager. This will take care of the necessary python libraries and
stuff. It should be available in your distro's package repos. Just make sure it
is installed and the script will do the rest for you.

### Instructions
To install the latest release:
```sh
git clone --depth 1 --branch latest https://git.noahsw.xyz/noah/easyconf-lemonbar.git
cd easyconf-lemonbar
sudo sh install.sh
```

To uninstall from your system:
```sh
sudo sh uninstall.sh
```
This will leave your config file in place, should you ever reinstall eclb.


**To update: uninstall, then follow the installation instructions again.**

## Configuration and Usage
### Config File
After installing, you will need to copy the example config file to your
XDG_CONFIG_HOME.

```sh
cp /usr/local/share/doc/easyconf-lemonbar/example_config.yml ${HOME}/.config/easyconf-lemonbar.yml
```

This example file is very heavily commented. Almost all the info you will need
is contained in the file.

### Running
Make sure `/usr/local/bin` is in your path (it should be by default) and run:

```sh
easyconf-lemonbar &
```

### Signals
You may update individual modules by sending a real-time signal to the
easyconf-lemonbar process. First, in the module configuration, specify which
signal to listen for, e.g.

```yaml
# Display a random number, and only update when we recieve the RTMIN+1 signal.
- name: "random"
  command: "python -c 'from random import randrange; print(randrange(1000))'"
  refresh: 0
  signal: 1
  format:
    align: left
```

In the example above, the refresh is `0`. This means that the module *will never
refresh on its own*; it will wait for the RTMIN+1 signal. You may also configure
your module to both refresh on a time interval AND listen for a signal.

Unfortunately, to send the signal, you cant just `pkill easyconf-lemonbar`. You
have to read the PID from eclb's pidfile. I would recommend creating an alias in
your shell as shown below.

```sh
alias eclb_kill="cat /run/user/${UID}/easyconf-lemonbar.pid | xargs kill"
eclb_kill -RTMIN+1
```

This will refresh the module that is listening for signal `1`. To kill eclb
completely, just run `eclb_kill` (after setting the above alias).