eww-config/README.md

# `eww.yuck` and friends

My personal eww config.

Install by linking or cloning to ~/.config/eww

## `track_anything.sh`

This config includes a helper bash source which may be used
to setup trackers of values.  It requires an on_event emitter
to already exist and should have one of the three output
formats: integer, boolean, and string.  Additionally, you will
need to provide a `poll` function which exposes the information
you care about.

Finally, you will need to source the main library file.  When
the library is in the same folder (or nearby) as the library,
this may be done as:

```bash
. "$(dirname "$0")/track_anything.sh"
```

### `poll`

Your provided poll function must return a valid output as its first
line and may provide log data on subsequent lines which will be
emitted at the info level (stderr, single -v).

A simple example is the pulseaudio mute state poller:

```bash
poll() {
  pamixer --get-mute
}
```

### `Configuration`

Options:

 - rate_limit
   - seconds to wait between running poll
     (default: `1`)

 - poll_interval
   - seconds to wait for an update before forcing a poll
     (default: `60`)
   - NOTE: must satisfy poll_interval >= rate_limit

 - filter: an arbitrary command to filter the total output of the poller in a loop
   (default: `uniq`)
   - NOTE: all arguments are collected and executed with eval.
   - Example: `cat` will allow duplicates.  `uniq` will filter them.

Event Emitters:

 - `on_volume`
   - emits on changes to pulseaudio sinks

 - `on_sway`
   - emits on changes to sway windows or workspaces

 - `on`
   - uses your own function to trigger an event
     which should be passed as the only argument to `on`
   - NOTE: the function in question _must_ emit events
     as newlines with no text.  multiple events may be
     emitted in general safety if `rate_limit` is > 0


Outputs:

 - `output_integer`
   - output a decimal integer

 - `output_boolean`
   - output a boolean (true, false)

 - `output_string`
   - output an arbitrary string, validated by a regex
   - args:
     - a validation regex string as the first argument
       (default: `.*`)

 - `output_json`
   - output an arbitrary json value, validated by jq
   - args:
     - a validation jq query which must not fail or return null
       (default: `.`)