An explanation to Yambar's configuration
Preface
Explanation valid as of the time of publication.
This EXPLANATION is a personal effort to jump the biggest hurdle I had when learning to configure Yambar: it's terminology.
Yambar's documentation is one step away from being excellent. IMO there's two things its missing: an easily digestible summary of what can be found in its man pages, and definitions for widely used terms like "attribute".
This is a summary, written from the bottom up, that presents the concepts used in Yambar's man pages in terms of those defined previously. Read this explanation with both all the man pages in front of you, and an example config, for the best results.
YAML
Yambar's file format of choice for its configuration is YAML, a superset of JSON. ANY valid JSON document is valid YAML. This means we can have JSON with comments, if nothing else. Hooray! Also, YAML doesn't require quoted keys. You'll find plenty of almost valid, unquoted JSON like that in most Yambar configs.
content:
- string: {text: " ", font: *awesome}
- string: {text: "{date}", right-margin: 10}
- string: {text: " ", font: *awesome}
- string: {text: "{time}", right-margin: 10}
The most incredible guide to YAML I read can be found here. This supposes previous knowledge of JSON, which you MUST HAVE. I recommend reading this before proceeding.
Yambar's config base concepts
Tip: When testing new Yambar configurations, you can use
yambar -C -c "your_config.yml" to check for correctness errors in your
file. Pair this command with entr for maximum awesomeness:
find "$XDG_CONFIG_HOME/yambar" | entr yambar -C # This uses the default config path
Now it'll automatically check every time you save a change to your file. If you get no output, that's good news!
bar:
location: top # Attribute of =bar=
height: 26 # Attribute of =bar=
background: 00000066 # Attribute of =bar=
right: # =right= is an attribute of =bar=. Contains a sequence of modules
- clock: # The clock module
content: # =content= is an attribute supported by all modules
- string: {text: "The current time is {time}"} # =string= is a particle, and ={time}= is a tag.
The two data structures in YAML, like in JSON, are sequences and maps. They can be freely nested.
A Yambar configuration file contains a required, top level map named
bar, and possibly a number of other top level definitions that contain
YAML anchored values (e.g. &anchor_name), to later be referenced by
YAML aliases (e.g. *anchor_name) inside of bar.
We'll define an attribute as a possible key-value pair with special
meaning inside that map. Example attributes of bar would be right or
location. The set of attributes of a map is named its format.
To check the attributes supported by bar, open the man page for
yambar's configuration file: yambar(5). The first table contains it's
format.
Right, center and left are among the top level keys of the bar
map. They're not modules, nor tags, nor particles, just attributes.
Modules expose their data through tags, which are rendered by particles. Tags are to modules what variables are to functions; they're lexically bound to the module that exposes them. Tags, like variables, have a name, a type and a value.
You can access tags by using the syntax {tag_name} or
{tag_name:formatter}. You can access tags inside your strings, which
makes it resemble String interpolation:
"This is a String containing the current time... {time}". {time}
will be substituted with the actual value of the tag. Read more about
tags and formatters in the man page for tags: yambar-tags(5).
A module defines its own configuration format, but all modules share a set of commot attributes. Attributes are concrete keys-value pairs, child of a module definition.
Recap
The following example should help you visualize everything so far (BTW sorry for the missing Font Awesome icons. That's a feature that BearBlog is missing):
# Top level anchor definition.
# key_name: &anchor_name "Actual value"
awesome_font: &awesome "Font Awesome 6 Free:style=solid:pixelsize=20"
# Top level map. =bar= is always required
bar:
# =bar= attributes:
height: 40
location: "top"
font: "JuliaMono:pixelsize=24"
spacing: 2
margin: 0
layer: "bottom"
foreground: "eeeeeeff"
background: "2E3440dd"
# =right= is not a module, nor a tag, nor a particle. It too is an attribute of =bar=.
right:
# This is the clock module.
# More at its corresponding man page: yambar-modules-clock(5)
- clock:
# =time-format= is an attribute of =clock=
time-format: "%H:%M %Z"
# =date-format= is an attribute of =clock=
date-format: "%A %Y-%m-%d"
# The =content= key is an attribute common to all modules.
# It always contains a seq(uence) of particles
content:
# =string= is a particle.
- string: {text: " ", font: *awesome}
# The value of =string= (a particle) is a map with two keys!
- string: {text: "{date}", right-margin: 10}
# *awesome is an alias to the value of =awesome_font,
# and will get substituted by its value
- string: {text: " ", font: *awesome}
# {date} and {time} are tags accessible inside of =clock=
- string: {text: "{time}", right-margin: 10}
# =label= is a module too!
- label:
content:
string:
# This is interesting! You can define commands that will be executed on demand
# =on-click= is an attribute common to all particles.
# Yes, you can interact with everything in yambar!
on-click: 'sudo poweroff'
text: ""
font: *awesome
right-margin: 1
The previous configuration file should result in this rendered Yambar, as long as you've got font-awesome installed in your system:
