# userctx

Manage you configurations and themes with ease.

## Installation
You just need to copy the file to a directory
in your $PATH (for example: /usr/loca/bin) and 
copy/create a config file.
```bash
sudo install userctx.py /usr/local/bin/userctx
mkdir -p ~/.config/userctx
cp config.toml ~/.config/userctx
```

## userctx basics
**userctx** manages configuration *contexts*. A context is a directory somewhere
in your system which stores actual configuration files for your apps
similar to what resides in ~/.config. 

Typically a context directory looks like this.
```bash
/home/dmitry/.config/userctx/Goldfish
├── sway
│   └── theme.conf
└── wofi
    └── style.css

```
In the above example, context "Goldfish" contains configs for apps "sway" and "wofi". 
These configs will be applied when you apply context "Goldfish".

When a context is applied the app configs from context directory are 
symlinked you ~/.config/ folder for each managed app. Goldfish/wofi/style.css symlinks to
\~/.config/wofi/style.css, Goldfish/sway/theme.conf symlinks to \~/.config/sway/theme.conf etc.

This default behaviour can be changed and specific actions or customizations
can be configured on per-app basis by editing **userctx** config file.
The default location for the config is ~/.config/userctx/config.toml.

**userctx** can also be configured to run scripts, trigger your apps to
reload configs etc. For a detailed overview of all config options see below.

There are two commands **userctx** understands: *list* and *apply*.
- *list* lists available contexts in a manner suitable for dmenu-like menu apps
- *apply* \<context\> applies named context

To test your configuration run:
```bash
userctx --nop apply <context_name>
```
The program will then only output what it will do without changing
anything in your home directory.

For a quickstart and simple examples jump to "Examples" section below.

## Configuring userctx
TODO: full description of config options.

## Examples
### Basic usecase: we only need symlinks
Let's add configuration for "foot" terminal emulator, which 
will be applied when we apply context "Goldfish" assuming
we would like to switch foot's visual theme when swithching context.

1. First we need to create a separate file for visuals config in out
context directory.

```bash
mkdir ~/.config/userctx/Goldfish/foot/
vim ~/.config/userctx/Goldfish/foot/theme.ini
```
And put the awesome "Tempus Day" into theme.ini:
```
# -*- conf -*-
# theme: Tempus Day
# author: Protesilaos Stavrou (https://protesilaos.com)
# description: Light theme with warm colours (WCAG AA compliant)

[colors]
foreground = 464340
# original background
# background = f8f2e5
background = ffffff
regular0 = 464340
regular1 = c81000
regular2 = 107410
regular3 = 806000
regular4 = 385dc4
regular5 = b63052
regular6 = 007070
regular7 = e7e3d7
bright0 = 68607d
bright1 = b24000
bright2 = 427040
bright3 = 6f6600
bright4 = 0f64c4
bright5 = 8050a7
bright6 = 336c87
bright7 = f8f2e5
```
You could as well symlink any file (pre-existing theme for foot) 
to ~/.config/userctx/Goldfish/foot/theme.ini

2. To include this theme file from main foot config add the following line
to $HOME/.config/foot/foot.ini (edit to match your user's homedir):
```
include=/home/dmitry/.config/foot/theme.ini
```
Do not forget to remove style settings from foot.ini so they do not
conflict with separate theme.ini.

3. Finally, tell userctx to manage foot config for you.
Edit ~/.config/userctx/config.toml and add "foot" to "apps"
array in "general" section of the config.
```
[general]
apps = [
  "foot",
  "sway",
  "wofi",
]
```
4. Test you configuration
```bash
userctx --nop apply Goldfish
```
The **--nop** (no-op) flag tells **userctx** to perform a dry-run. It will just output
what it is going to do when you actually apply context.

If all looks good - that's it. When you issue **userctx apply Goldfish**
a symlink will be created in your homedir:

~/.config/foot/theme.ini -> ~/.config/userctx/Goldfish/foot/theme.ini

### More advanced usecase: run command and hot-reload
Let's configure **userctx** to apply theme to helix editor.

1. Similar to the above section, create ~/.config/userctx/Goldfish/helix/helix.toml 
with the following contents:
```toml
inherits = "github_light"
"ui.background" = {}
```
Now edit  ~/.config/userctx/config.toml.

Add the "helix" to "general" section.
```toml
[general]
apps = [
  "foot",
  "sway",
  "helix",
  "wofi",
]
```
2. Add "apps.helix" section:
```toml
[apps.helix]
symlink."*" = "themes/current_theme.toml"
exec = """sed -i -E 's/^theme = (.+)/theme = "current_theme"/' ~/.config/helix/config.toml"""
reload = "pkill -USR1 hx"
```
Here we instruct **userctx** to symlink any (single) file it finds in "helix" subdirectory of context folder
to  ~/.config/helix/themes/current_theme.toml

Then we run sed to change the config file. This part is not really necessare if helix is 
configured to use theme named "current_theme" and you're sure that config won't change.
We could just replace the file and issue USR1. The sed part if for the case when config 
is changed by user or other app. 

Finally we set the reload command which
will tell helix to reload config.

3. Test your configuration,
```bash
userctx --nop apply Goldfish
```

See also template "config.toml" with numerous app settings.