NAME

wallust - Generate a 16 color scheme based on an image.

SYNOPSIS

wallust [-I|--ignore-sequence] [-q|--quiet] [-s|--skip-sequences] [-T|--skip-templates] [-u|--update-current] [-C|--config-file] [-d|--config-dir] [--templates-dir] [-N|--no-config] [-h|--help] [-V|--version] <subcommands>

DESCRIPTION

Reminder The options below can be used after the subcommand, for example: "wallust --quiet run image.png" is the same as "wallust run --quiet image.png"

OPTIONS

-I, --ignore-sequence=IGNORE_SEQUENCE

Won't send these colors sequences

[possible values: background, foreground, cursor, color0, color1, color2, color3, color4, color5, color6, color7, color8, color9, color10, color11, color12, color13, color14, color15]

-q, --quiet

Don't print anything

-s, --skip-sequences

Skip setting terminal sequences

-T, --skip-templates

Skip templating process

-u, --update-current

Only update the current terminal

-C, --config-file=CONFIG_FILE

Use CONFIG_FILE as the config file

-d, --config-dir=CONFIG_DIR

Uses CONFIG_DIR as the config directory, which holds both `wallust.toml` and the templates files (if existent)

--templates-dir=TEMPLATES_DIR

Uses TEMPLATE_DIR as the template directory

-N, --no-config

Won't read the config and avoids creating it's config path

-h, --help

Print help (see a summary with '-h')

-V, --version

Print version

SUBCOMMANDS

wallust-run(1)

Generate a palette from an image

wallust-cs(1)

Apply a certain colorscheme

wallust-theme(1)

Apply a custom built in theme

wallust-migrate

Migrate v2 config to v3

wallust-debug

Print information about the program and the enviroment it uses

wallust-help

Print this message or the help of the given subcommand(s)

TERMINAL COLORS

By default, wallust will send these sequences to all open terminals:

You can skip this with the `-s` or `--skip-sequences` flag.
When opening new terminals you will notice that the color sequences are not applied. To solve this you can send the sequences yourself when your shell opens. `wallust` will store the sequences in the cache directory as a file called `sequences`, the usual way is to `cat ~/.cache/wallust/sequences` in your `.zshrc`, `.bashrc`, etc.

TEMPLATE VARIABLES

COLORS

These types are formated like as HEX rgb (e.g. '#0A0B0C') by default. However a color literal can be represented in multiple ways, like HEXA rgba (e.g. '#0A0B0CFF', where 'FF' is the transparency value) or HEX rgb without the leading '#' ('0a0b0c').

color0, color1, color2, color3, color4, color5, color6, color7, color8, color9, color10, color11, color12, color13, color14, color15, background, foreground and cursor.

colors Additionally, this variable returns a vector of all the presented colors in the following order: starts with color0 to color15, background, foregroundand at the end, (index 18 if starting from 0), cursor. See TEMPLATE SYNTAX for a practical guide.

MISCELLANEOUS

TEMPLATE FILTERS

The Jinja2 format calls them 'filters', making a distincion from 'functions'.
Currently I haven't implemented any function because I haven't found a usecase (yet?).

UNSIGNED INT

COLORS

Functions that only work with colors. These can be applied to a color , which can be the COLOR variables listed above, see TEMPLATE VARIABLES, or a literal color like "#0A0B0C". These functions return a color in the mentioned format (hex rgb, like "#000000"), unless written otherwise (like rgb, rgba, the other filters that explicitly say it's output format). This allows to apply multiple filters at a time.

Note If an 'alpha' value is mentioned, it's defined in the config file, as a cli flag and by default it's value is '100'.

TEMPLATE SYNTAX

You reference variables in the following syntax:

{{color0}}

For applying a filter you use the 'pipe character` (|) like this:

{{background | strip}}

And if the filter requires an argument:

{{background | lighten(0.3)}}

Remember that filters require a valid type to apply to in these examples we are using colors, which can even be defined literally:

{{ "#4ff4ff" | lighten(0.3)}}

For both , being applied to or as an argument of a filter:

{{ color2 | blend("4ff4ff")}}

If you need to write a literal `{{`, that doesn't references any variable, you can write literals inside the delimiters:

{{ "{{" }} {{ "}}" }}

You can also use control flow expressions with `{% %}` delimiters:

{% if backend == "wal" %}
I am using the '{{backend}}' backend, getting a pywal like scheme.
{% elif backend == "fastresize" %}
This backend is called "{{palette}}" and, uses SIMD optimizations and is so fast!
{% else %}
I don't care about any other backends. Be happy!
{% endif %}

Or inline them:

{{ "I'm using the kmeans algo!" if backend == "kmeans" else "Some backend is in use" }}

Since mostly everything can be represented as a string (we've seen how colors are represented), indexing results very useful! The syntax for indexing is basically the Python one.

{# I'll hardcode a color based on the palette being used. #}
{% if palette[:4] == "dark" %}
somevariable = "#eeffbb"
{% else %}
somevariable = "#aabbee"
{% endif %}

And yes, you can comment inside your template, the comments won't be rendered in the final target file:

{# This won't be visible! #}

There are more control flow instructions, like the for loop:

{# This will generate color0 = .. to color18,
since `colors` contains background, foreground and cursor variables #}
{% for c in colors %}
color{{- loop.index }} = {{c-}}
{% endfor %}

You can add a minus sign (-) at the start or the end of the delimiters to supress vertical spacing[3]

The syntax comes from the library being used, which is minijinja , a subset of the template engine `Jinja2'.

You can read more at: Jinja2 official syntax[4] and contrast features with the supported syntax at Compatibility of minijinja[5]

TEMPLATE EXAMPLE

You can use wallust generated colors in a program by templating the colors in it's config file, like the following example:

# zathurarc config sample
# colors
set default-bg     "{{background}}"
set default-fg     "{{foreground}}"
# make it a bit lighter than background
set statusbar-bg   "{{background | lighten(0.3)}}"
# make it darken by blending to a darken color
set statusbar-fg   "{{foreground | blend("#eeeeee")}}"
# use it's complementary
set inputbar-bg    "{{background | complementary}}"

Then you can add this file to ~/.config/wallust/templates and use the config file to template it. For example, zathura.template = 'zathurarc' , and then define a target field, see wallust(5).

PYWAL TEMPLATE COMPATIBILITY

You can enable pywal like syntax in the config file with `pywal = true', see wallust(5).

The syntax is simple, but more variables are added given that it's engine and spec doesn't support runtime evaluation functions.

While the implementation is simple enough to be added in wallust, it's use is discoraged.

Variables

color0, color1, color2, color3, color4, color5, color6, color7, color8, color9, color10, color11, color12, color13, color14, color15, background, foreground, cursor, and it's .rgb, .rgba, .xrgba, .strip, .red, .green and .blue variants, just append it to the variable name (e.g. "color0.rgb", "background.blue" ...).

wallpaper, alpha and alpha_dec are also avaliable, these don't support the variants from above.

Syntax

The syntax logic is simply "Find and Replace" like:

somevariable = {color2}
anothervariable = {color8.rgb}

Don't forget to visit the full pywal spec[6]

SEE ALSO

wallust(5), wallust-run(1), wallust-cs(1), wallust-theme(1), wallust-themes[7].

NOTES

1.

ps to search active terminals
https://github.com/dylanaraps/pywal/pull/510

2.

Hexadecimal color code
https://gist.github.com/lopspower/03fb1cc0ac9f32ef38f4

3.

White space contron with the minus sign (-)
http://jinja.pocoo.org/docs/templates/#whitespace-control

4.

Official Jinja2 documentation
https://jinja.palletsprojects.com/en/2.10.x/

5.

Compatibility of Minijinja with Jinja2
https://github.com/mitsuhiko/minijinja/blob/main/COMPATIBILITY.md

6.

Full pywal template specification
https://github.com/dylanaraps/pywal/wiki/User-Template-Files

7.

Suggestions for new colorschemes returned by the themes subcommand should be filled here.
https://codeberg.org/explosion-mental/wallust-themes

BUGS

https://codeberg.org/explosion-mental/wallust