fix bug in template exec pattern

add py execution support to templates, loosen generate matches
update README links, minor logging fix
2024-08-18 14:14:51 -07:00 · 2024-08-18 11:56:28 -07:00 · 2024-08-12 01:52:28 -07:00 · 2024-08-12 00:23:39 -07:00 · 2024-08-11 16:01:18 -07:00 · 2024-08-11 05:18:47 -07:00
49 changed files with 2465 additions and 797 deletions
--- a/README.md
+++ b/README.md
@ -1,233 +1,142 @@
-# autoconf
+# Symconf
-The `autoconf` project is an attempt at wrangling the complexity of configuring many
+`symconf` is a CLI tool for managing local application configuration. It implements a
-applications across one's Linux system. It provides a simple operational model for pulling
+general model that supports dynamically switching/reloading themes for any application,
-many application config files into one place, as well as generating/setting color schemes
+and provides a basic means of templatizing your config files.
 across apps.
-Quick terminology rundown for theme-related items:
+## Simple example
 Below is a simple example demonstrating two system-wide theme switches:
- **Theme**: loose term referring generally to the overall aesthetic of a visual setting.
+![Simple example](docs/_static/example.gif)
  Ignoring stylistic changes (only applicable to some apps; example here might be a
  a particular setting of the `waybar` layout), a theme is often just the wrapper term for
  a choice of color _palette_ and _scheme_. For example, "tone4-light" could be a _theme_
  setting for an app like `kitty`, referring to both a palette and scheme.
 - **Palette**: a set of base colors used to style text or other aspects of an app's
  displayed assets
 - **Scheme**: an indication of lightness, typically either "light" or "dark.
-As far as managing settings across apps, there are current two useful classifications
+This GIF shows two `symconf` calls, the first of which applies a `gruvbox` dark theme and
-here:
+the second a dark [`monobiome`][1] variant. Each call (of the form `symconf config -m dark -s
 style`) indicates a dark mode preference and a particular color palette that should be
 used when populating config file templates. Specifically, in this example, invoking
 `symconf` results in the following app-specific config updates:
-1. **Inseparable from theme**: some apps (e.g., `sway`, `waybar`) have color scheme
+- **GTK**: reacts to the mode setting and sets `prefer-dark` system-wide, changing general
-   components effectively built in to their canonical configuration file. This can make it
+  GTK-responsive applications like Nautilus and Firefox (and subsequently websites that
-   hard to set themes dynamically, as it would likely require some involved
+  are responsive to `prefers-color-scheme`)
-   matching/substitution rules. This is not a level of complexity I'm willing to embrace,
+- **kitty**: theme template is re-generated using the specified palette, and `kitty`
-   so we simply split the config files according to theme and/or scheme.
+  processes are sent a message to live-reload the new config file
-2. **Can load an external theme file**: some apps (e.g., `kitty`) have a clear mechanism
+- **neovim**: a `vim` theme file (along with a statusline theme) is generated from the
-   for loading themes. This typically implies some distinct color format, although usually
+  chosen palette, and running instances of `neovim` are sent a message to re-source this
-   somewhat easy to generate (don't have to navigate non-color settings, for instance).
+  theme (via `nvim --remote-send`)
-   Such apps allow for an even less "invasive" config swapping process when setting a new
+- **waybar**: bar styles are updated to match the mode setting
-   theme, as one can just swap out the external theme file.
+- **sway**: the background color and window borders are dynamically set to base palette
  colors, and `swaymsg reload` is called
 - **fzf**: a palette-dependent theme is re-generated and re-exported
 - **rofi**: launcher text and highlight colors are set according to the mode and palette,
  applying on next invocation
-To be clear on operation implications here: apps of type (1) must have _manually
+This example highlights the generality of `symconf`, and so long as an app's config can be
-maintained_ config variations according the desired themes. General theme settings must
+reloaded dynamically, you can use a single `symconf` call to apply themes for an arbitrary
-follow the naming scheme `<app-name>-<palette>-<scheme>.<ext>`. For example, if I wanted to set
+number of apps at once.
 `sway` to a light variation (which, at the time of writing, would just entail changing a
 single background color), I must have explicitly created a `sway-tone4-light.conf` file
 that captures this setting. The canonical config file will then be symlinked to the
 theme-specific file when the theme is set. (Note that the palette in this example is pretty much
 irrelevant, but it needs to be present in order to match the overarching setting; here you
 can just think of the format being `<app-name>-<theme>.<ext>`, where `tone4-light` is the
 provided theme name.)
-For apps of type (2), the canonical config file can remain untouched so long as it refers
+# Behavior
-to a fixed, generic theme file. For example, with `kitty`, my config file can point to a
+`symconf` uses a simple operational model that symlinks centralized config files to their
-`current-theme.conf` file, which will be symlinked to a specific theme file here in
+expected locations across the system. This central config directory can then be version
-`autoconf` when a change is requested. This enables a couple of conveniences:
+controlled, and app config files can be updated in one place.
- The true config directory on disk remains unpolluted with theme variants.
+App config files can either be concrete (fully-specified) or templates (to be populated by
- If the set theme is regenerated, there is no intervention necessary to propagate its
+values conditional on style, e.g., a palette). When `symconf` is executed with a
-  changes to the target app. The symlinked file itself will be updated when the theme
+particular mode preference (dark or light) and a style (any other indicator of thematic
-  does, ensuring the latest theme version is always immediately available and pointed to
+elements, often simply in the form of a palette like `solarized` or `gruvbox`), it
-  by the app.
+searches for both concrete and template config files that match and symlinks them to
 registered locations. When necessary, `symconf` will also match and execute scripts to
 reload apps after updating their configuration.
-Keep in mind that some apps may fall into some grey area here, allowing some external
+You can find more details on how `symconf`'s matching scheme works in
-customization but locking down other settings internally. In such instances, there's no
+[Matching](docs/reference/matching.md).
 need to overcomplicate things; just stick to explicit config variants under the type (1)
 umbrella. Type (2) only works for generated themes anyhow; even if the target app can load
 an external theme, type (1) should be used if preset themes are fixed.
-## Naming standards
+# Configuring
-To keep things simple, we use a few fixed naming standards for setting app config files
+Before using, you must first set up your config directory to house your config files and
-and their themed counterparts. The app registry requires each theme-eligible app to
+give `symconf` something to act on. See [Configuring](docs/reference/configuring.md) for
-provide a config directory (`config_dir`), containing some canonical config file
+details.
 (`config_file`) and to serve as a place for theme-specific config variations. The
 following naming schemes must be used in order for theme switching to behave
 appropriately: 
- When setting a theme for a particular app, the following variables will be available:
+# Installation
-    * `<app-name>`
+The recommended way to install `symconf` is via `pipx`, which is particularly well-suited
-    * `<palette>`
+for managing Python packages meant to be used as CLI programs. With `pipx` on your system,
-    * `<scheme>`
+you can install with
 - For apps with `external_theme = False`, config variants must named as
  `<app-name>-<palette>-<scheme>.<ext>`, where `<ext>` is the app's default config file
  extension.
 - For apps with `external_theme = True`, the file `<config-dir>/current-theme.conf` will
  be used when symlinking the requested theme. The config file thus must point to this
  file in order to change with the set theme.
-  Additionally, the theme symlink will be created from the file
+```sh
 pipx install symconf
 ```
-  ```
+You can also install via `pip`, or clone and install locally.
-  <autoconf-root>/autoconf/themes/<palette>/apps/<app-name>/generated/<scheme>.conf
+
 # Usage
 - `-h --help`: print help message
 - `-c --config-dir`: set the location of the `symconf` config directory
 - `symconf config` is the subcommand used to match and set available config files for
  registered applications
  * `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to consider
    all registered apps.
  * `-m --mode`: preferred lightness mode/scheme, either `light`, `dark`, `any`, or
    `none`.
  * `-s --style`: style indicator, often the name of a color palette, capturing thematic
    details in a config file to be matched. `any` or `none` are reserved keywords (see
    below).
  * `-T --template-vars`: additional groups to use when populating templates, in the form
    `<group>=<value>`, where `<group>` is a template group with a folder
    `$CONFIG_HOME/groups/<group>/` and `<value>` should correspond to a TOML file in this
    folder (i.e., `<value>.toml`).
 - `symconf generate` is a subcommand that can be used for batch generation of config
  files. It accepts the same arguments as `symconf config`, but rather than selecting the
  best match to be used for the system setting, all matching templates are generated.
  There is one additional required argument:
  * `-o --output-dir`: the directory under which generated config files should be written.
    App-specific subdirectories are created to house config files for each provided app.
 - `symconf install`: runs install scripts for matching apps that specify one
  * `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to consider
    all registered apps.
 - `symconf update`: runs update scripts for matching apps that specify one
  * `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to consider
    all registered apps.
 The keywords `any` and `none` can be used when specifying `--mode`, `--style`, or as a
 value in `--template-vars` (and we refer to each of these variables as _factors_ that help
 determine a config match):
 - `any` will match config files with _any_ value for this factor, preferring config files
  with a value `none`, indicating no dependence on the factor. This is the default value
  when a factor is left unspecified.
 - `none` will match `"none"` directly for a given factor (so no special behavior), but
  used to indicate that a config file is independent of the factor. For instance,
  ```sh
  symconf config -m light -s none
  ```
-  to `<config-dir>/current-theme.conf`. 
+  will match config files that capture the notion of a light mode, but do not depend on or
  provide further thematic components such as a color palette.
-## Directory structure
+## Examples
 - Set a dark mode for all registered apps, matching any available style/palette component:
- `autoconf/`: main repo directory
+  ```sh
-    * `config/`: app-specific configuration files. Each folder inside this directory is
+  symconf config -m dark
-      app-specific, and the target of associated copy operations when a config sync is
+  ```
-      performed. Nothing in this directory should pertain to any repo functionality; it
+- Set `solarized` theme for `kitty` and match any available mode (light or dark):
      should only contain config files that originated elsewhere on the system.
    * `themes/`: app-independent theme data files. Each folder in this directory should
      correspond to a specific color palette and house any relevant color spec files
      (currently likely be a `colors.json`). Also servers the output location for
      generated theme files
        * `<palette>/colors.json`: JSON formatted color key-value pairings for palette
          colors. There's no standard here aside from the filename and format; downstream
          app-specific TOML templates can be dependent on any key naming scheme within the
          JSON.
        + `<palette>/apps/<app-name>/templates/`: houses the TOML maps for the color
          palette `<palette>` under app `<app-name>`. Files `<fname>.toml` will be mapped to
          `<fname>.conf` in the theme output folder (below), so ensure the naming
          standards align with those outlined above.
        + `<palette>/apps/<app-name>/generated/`: output directory for generated scheme
          variants. These are the symlink targets for dynamically set external themes.
    * `app_registry.toml`: global application "registry" used by sync and theme-setting
      scripts. This lets apps be dynamically added or removed from being eligible for
      config-related operations.
-## Scripts
+  ```sh
  symconf config -s solarized -a kitty
  ```
 - Set a dark `gruvbox` theme for multiple apps (but not all):
-`set_theme.py`: sets a theme across select apps.
+  ```sh
  symconf config -m dark -s gruvbox -apps="kitty,nvim"
  ```
 - Set a dark `gruvbox` theme for all apps, and attempt to match other template elements:
- Applies to specific app with `-a <app>` , or to all apps in the `app_registry.toml` with
+  ```sh
-  `-a "*"`.
+  symconf config -m dark -s gruvbox -T font=mono window=sharp
- Uses symlinks to set canonical config files to theme-based variations. Which files get
+  ```
-  set depends on the _app type_ (see above), which really just boils down to whether
+
-  theming (1) can be specified with an external format, and (2) if it depends on
+  which would attempt to find and load key-value pairs in the files
-  auto-generated theme files from within `autoconf`.
+  `$CONFIG_HOME/groups/font/mono.toml` and `$CONFIG_HOME/groups/window/sharp.toml` to be
- Palette and scheme are specified as expected. They are used to infer proper paths
+  used as values when filling templatized config files.
  according to naming and structure standards.
 - Real config files will never be overwritten. To begin setting themes with the script,
  you must delete the canonical config file expected by the app (and specified in the app
  registry) to allow the first symlink to be set. From there on out, symlinks will be
  automatically flushed.
 - A report will be provided on which apps were successfully set to the requested theme,
  along with the file stems. A number of checks are in place for the existence of involved
  files and directories. Overall, the risk of overwritting a real config file is low; we
  only flush existing symlinks, and if the would-be target for the requested theme (be it
  from an auto-generated theme file, or from a manually manage config variant) doesn't
  exist, that app's config will be completed skipped. Essentially, everything must be in
  perfect shape before the symlink trigger is officially pulled.
 `gen_theme.py`: generates theme files for palettes by mapping their color definitions
 through app-specific templates. These templates specific how to relate an app's theme
 variables to the color names provided by the template.
- An app and palette are the two required parameters. If no template or output paths are
+[1]: https://github.com/ologio/monobiome
  provided, they will be inferred according to the theme path standards seen above.
 - The `--template` argument can be a directory or a file, depending on what theme files
  you'd like to render.
 - The `--output` path, if specified, must be a directory. Generated theme files take on
  a name with the same stem as their source template, but using the `.conf` extension.
 - The TOML templates should make config variable names to JSON dot-notation accessors. If
  color definitions are nested, the dot notation should be properly expanded by the script
  when mapping the colors to keyword values.
 - There are a number of checks for existing paths, even those inferred (e.g., template and
  output) from the palette and app. If the appropriate setup hasn't been followed, the
  script will fail. Make sure the `theme` folder in question and it's nested `app`
  directory are correctly setup before running the script. (Perhaps down the line there
  are some easy auto-setup steps to take here, but I'm not making that jump now.)
 - TODO: open up different app "writers," or make it easy to extend output syntax based on
  the app in question. This would like be as simple as mapping app names to
  line-generating functions, which accept the keyword and color (among other items). This
  can be fleshed out as needed.
 `sync.sh`: copies relevant configuration files from local paths into the `autoconf`
 subpath. Markdown files in the docs directory then reference the local copies of these
 files, meaning the documentation updates dynamically when the configuration files do. That
 is, the (possibly extracted) config snippets will change with the current state of my
 system config without any manual intervention of the documentation files.
 ### Specific theme-setting example
 To make clear how the theme setting script works on my system, the following breaks down
 exactly what steps are taken to exert as much scheme control as possible. Everything at this
 point is wrapped up in a single `make set-<palette>-<scheme>` call; suppose we're
 currently running the dark scheme (see first image) and I run `make set-tone4-light`:
 ![
  Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the
  system-dependent default theme set). In Firefox, I have open `localsys` with its
  scheme-mode to set to "auto," which should reflect the theme setting picked up by the
  browser (and note the white tab icon).
 ](_static/set-theme-1.png)
 _(Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the
 system-dependent default theme set). In Firefox, I have open `localsys` with its
 scheme-mode to set to "auto," which should reflect the theme setting picked up by the
 browser (and note the white tab icon).)_
 1. `set_theme.py` is invoked. Global settings are applied first, based on my OS (`Linux`),
   which calls
   ```
   gsettings set org.gnome.desktop.interface color-scheme 'prefer-light'
   ```
   controlling settings for GTK apps and other `desktop-portal`-aware programs. This
   yields the following:
   ![Portal-aware apps changed, config apps not yet set](_static/set-theme-2.png)
   _(Portal-aware apps changed, config apps not yet set. Scheme-aware sites are updated
   without page refresh.)_
 2. Specific application styles are set. For now the list is small, including `kitty`,
   `waybar`, and `sway`. `kitty` is the only type (2) application here, whereas the other
   two are type (1).
   a. For the type (1) apps, the canonical config files as specified in the app registry
      are symlinked to their light variants. For `sway`, this is `~/.config/sway/config`,
      and if we look at the `file`:
      ```sh
      .config/sway/config: symbolic link to ~/.config/sway/sway-tone4-light
      ```
   b. For the type (2) apps, just the `current-theme.conf` file is symlinked to the
      relevant palette-scheme file. `kitty` is such an app, with a supported theme file
      for `tone4`, and those files have been auto-generated via `gen_theme.py`. Looking at
      this file under the `kitty` config directory:
      ```sh
      .config/kitty/current-theme.conf: symbolic link to ~/Documents/projects/autoconf/autoconf/themes/tone4/apps/kitty/generated/light.conf
      ```
      The `kitty.conf` file isn't changed, as all palette-related items are specified in
      the theme file. (Note that the general notion of a "theme" could include changes to
      other stylistic aspects, like the font family; this would likely require some hybrid
      type 1-2 approach not yet implemented).
 3. Live application instances are reloaded, according to the registered `refresh_cmd`s.
   Here the apps with style/config files set in step (2) are reloaded to reflect those
   changes. Again, in this example, this is `kitty`, `sway`, and the `waybar`.
   ![Final light setting: portal-dependent apps _and_ config-based apps changed](_static/set-theme-3.png)
   _(Final light setting: portal-dependent apps _and_ config-based apps changed)_
 4. `set_theme.py` provides a report for the actions taken; in this case, the following was
   printed:
   ![`set_theme.py` output](_static/set-theme-4.png)
   _(`set_theme.py` output)_
--- a/REFACTOR.md
+++ b/REFACTOR.md
@ -52,3 +52,4 @@
 - Refresh scripts should likely specify a shell shabang at the top of the file
 - `apps` can serve as a dotfiles folder
 - Support symlinking whole folders?
 - `any` might prefer to match configs with none over specific options, but will match any
--- a/TODO.md
+++ b/TODO.md
@ -1,5 +1,3 @@
- Push scheme generation to `~/.config/autoconf`
+- Add local app caching for `auto` logic
- Copy default app registry to the config location
+- Better script handling: 1) should be live, basically reconnecting output to native
- Formalize the theme spec (JSON) and `autoconf gen` to produce color configs
+  terminal, 2) catch and print errors from STDERR
 - Likely need to formalize the `sync.sh` script logic better, possibly associated directly
  with registry TOML
--- a/autoconf/init.py
+++ b/autoconf/init.py
@ -1 +0,0 @@
 from autoconf.config import ConfigManager
--- a/autoconf/main.py
+++ b/autoconf/main.py
@ -1,102 +0,0 @@
 import argparse
 import util
 #from gen_theme import generate_theme_files
 from autoconf.config import ConfigManager
 def add_set_subparser(subparsers):
    def update_app_settings(args):
        cm = ConfigManager(args.config_dif)
        cm.update_apps(
            apps=args.apps,
            scheme=args.scheme,
            palette=args.palette,
        )
    parser = subparsers.add_parser(
        'set',
        description='Generate theme files for various applications. Uses a template (in TOML ' \
                  + 'format) to map application-specific config keywords to colors (in JSON '  \
                  + 'format).' 
    )
    parser.add_argument(
        '-p', '--palette',
        required = False,
        default  = "any",
        help     = 'Palette name, must match a folder in themes/'
    )
    parser.add_argument(
        '-s', '--scheme',
        required = False,
        default  = "any",
        help     = 'Preferred lightness scheme, either "light" or "dark".'
    )
    parser.add_argument(
        '-a', '--apps',
        required = False,
        default  = "any",
        type     = lambda s: s.split(',') if s != '*' else s
        help     = 'Application target for theme. App must be present in the registry. ' \
                 + 'Use "*" to apply to all registered apps'
    )
    parser.set_defaults(func=update_app_settings)
 def add_gen_subparser(subparsers):
    parser = subparsers.add_parser(
        'gen',
        description='Generate theme files for various applications. Uses a template (in TOML ' \
                  + 'format) to map application-specific config keywords to colors (in JSON '  \
                  + 'format).' 
    )
    parser.add_argument(
        '-a', '--app',
        required=True,
        help='Application target for theme. Supported: ["kitty"]'
    )
    parser.add_argument(
        '-p', '--palette',
        required=True,
        help='Palette to use for template mappings. Uses local "theme/<palette>/colors.json".'
    )
    parser.add_argument(
        '-t', '--template',
        default=None,
        help='Path to TOML template file. If omitted, app\'s default template path is used.' \
           + 'If a directory is provided, all TOML files in the folder will be used.'
    )
    parser.add_argument(
        '-o', '--output',
        default=None,
        help='Output file path for theme. If omitted, app\'s default theme output path is used.'
    )
    parser.set_defaults(func=generate_theme_files)
 # central argparse entry point
 parser = argparse.ArgumentParser(
    'autoconf',
    description='Generate theme files for various applications. Uses a template (in TOML ' \
              + 'format) to map application-specific config keywords to colors (in JSON '  \
              + 'format).' 
 )
 parser.add_argument(
    '-c', '--config-dir',
    default = util.xdg_config_path(),
    type    = util.absolute_path,
    help    = 'Path to config directory'
 )
 # add subparsers
 subparsers = parser.get_subparsers()
 #add_gen_subparser(subparsers)
 add_set_subparser(subparsers)
 if __name__ == '__main__':
    args = parser.parse_args()
    if 'func' in args:
        args.func(args)
    else:
        parser.print_help()
--- a/autoconf/config.py
+++ b/autoconf/config.py
@ -1,370 +0,0 @@
 import os
 import json
 import inspect
 import tomllib
 import argparse
 import subprocess
 from pathlib import Path
 from colorama import Fore, Back, Style
 from autoconf import util
 class ConfigManager:
    def __init__(
        self,
        config_dir=None,
        disable_registry=False,
    ):
        '''
        Configuration manager class
        Parameters:
            config_dir: config parent directory housing expected files (registry,
                        app-specific conf files, etc). Defaults to
                        ``"$XDG_CONFIG_HOME/autoconf/"``.
            disable_registry: disable checks for a registry file in the ``config_dir``.
                              Should really only be set when using this programmatically
                              and manually supplying app settings.
        '''
        if config_dir == None:
            config_dir = util.xdg_config_path()
        self.config_dir = util.absolute_path(config_dir)
        self.apps_dir   = Path(self.config_dir, 'apps')
        self.app_registry = {}
        self._check_paths()
        if not disable_registry:
            self._check_registry()
    def _check_paths(self):
        '''
        Check necessary paths for existence.
        Regardless of programmatic use or ``disable_registry``, we need to a valid
        ``config_dir`` and it must have an ``apps/`` subdirectory (otherwise there are
        simply no files to act on, not even when manually providing app settings).
        '''
        # throw error if config dir doesn't exist
        if not self.config_dir.exists():
            raise ValueError(
                f'Config directory "{self.config_dir}" doesn\'t exist.'
            )
        # throw error if apps dir doesn't exist or is empty
        if not self.apps_dir.exists() or not list(self.apps_dir.iterdir()):
            raise ValueError(
                f'Config directory "{self.config_dir}" must have an "apps/" subdirectory.'
            )
    def _check_registry(self):
        registry_path = Path(self.config_dir, 'app_registry.toml')
        self.app_registry = {}
        if not registry_path.exists():
            print(
                Fore.YELLOW \
                + f'No registry file found at expected location "{registry_path}"'
            )
            return
        app_registry = tomllib.load(registry_path.open('rb'))
        if 'app' not in app_registry:
            print(
                Fore.YELLOW \
                + f'Registry file found but is either empty or incorrectly formatted (no "app" key).'
            )
        self.app_registry = app_registry.get('app', {})
    def resolve_scheme(self, scheme):
        # if scheme == 'auto':
        #     os_cmd_groups = {
        #         'Linux': (
        #             "gsettings get org.gnome.desktop.interface color-scheme",
        #             lambda r: r.split('-')[1][:-1],
        #         ),
        #         'Darwin': (),
        #     }
        #     osname = os.uname().sysname
        #     os_group = os_cmd_groups.get(osname, [])
        #     for cmd in cmd_list:
        #         subprocess.check_call(cmd.format(scheme=scheme).split())
        # return scheme
        if scheme == 'auto':
            return 'any'
        return scheme
    def resolve_palette(self, palette):
        if palette == 'auto':
            return 'any'
        return palette
    def app_config_map(self, app_name):
        '''
        Get the config map for a provided app.
        The config map is a dict mapping from config file **path names** to their absolute
        path locations. That is, 
        ```sh
        <config_path_name> -> <config_dir>/apps/<app_name>/<subdir>/<palette>-<scheme>.<config_path_name>
        ```
        For example,
        ```
        palette1-light.conf.ini -> ~/.config/autoconf/apps/user/palette1-light.conf.ini
        palette2-dark.app.conf -> ~/.config/autoconf/apps/generated/palette2-dark.app.conf
        ```
        This ensures we have unique config names pointing to appropriate locations (which
        is mostly important when the same config file names are present across ``user``
        and ``generated`` subdirectories).
        '''
        # first look in "generated", then overwrite with "user"
        file_map = {}
        app_dir  = Path(self.apps_dir, app_name)
        for subdir in ['generated', 'user']:
            subdir_path = Path(app_dir, subdir)
            if not subdir_path.is_dir():
                continue
            for conf_file in subdir_path.iterdir():
                file_map[conf_file.name] = conf_file
        return file_map
    def get_matching_configs(
        self, 
        app_name,
        scheme='auto',
        palette='auto',
    ) -> dict[str, str]:
        '''
        Get app config files that match the provided scheme and palette.
        Unique config file path names are written to the file map in order of specificity.
        All config files follow the naming scheme ``<palette>-<scheme>.<path-name>``,
        where ``<palette>-<scheme>`` is the "theme part" and ``<path-name>`` is the "conf
        part." For those config files with the same "conf part," only the entry with the
        most specific "theme part" will be stored. By "most specific," we mean those
        entries with the fewest possible components named ``any``, with ties broken in
        favor of a more specific ``palette`` (the only "tie" really possible here is when
        `any-<scheme>` and `<palette>-any` are both available, in which case the latter
        will overwrite the former).
        '''
        app_dir = Path(self.apps_dir, app_name)
        scheme  = self.resolve_scheme(scheme)
        palette = self.resolve_palette(palette)
        # now match theme files in order of inc. specificity; for each unique config file
        # tail, only the most specific matching file sticks
        file_parts = []
        app_config_map = self.app_config_map(app_name)
        for pathname in app_config_map:
            parts = pathname.split('.')
            if len(parts) < 2:
                print(f'Filename "{filename}" incorrectly formatted, ignoring')
                continue
            theme_part, conf_part = parts[0], '.'.join(parts[1:])
            file_parts.append((theme_part, conf_part, pathname))
        theme_prefixes = [
            'any-any',
            f'any-{scheme}',
            f'{palette}-any',
            f'{palette}-{scheme}'
        ]
        matching_file_map = {}
        for theme_prefix in theme_prefixes:
            for theme_part, conf_part, pathname in file_parts:
                if theme_part == theme_prefix:
                    matching_file_map[conf_part] = app_config_map[pathname]
        return matching_file_map
    def get_matching_scripts(
        self,
        app_name,
        scheme='any',
        palette='any',
    ):
        '''
        Execute matching scripts in the app's ``call/`` directory.
        Scripts need to be placed in 
        ```sh
        <config_dir>/apps/<app_name>/call/<palette>-<scheme>.sh
        ```
        and are matched using the same heuristic employed by config file symlinking
        procedure (see ``get_matching_configs()``).
        '''
        app_dir  = Path(self.apps_dir, app_name)
        call_dir = Path(app_dir, 'call')
        if not call_dir.is_dir():
            return
        theme_prefixes = [
            'any-any',
            f'any-{scheme}',
            f'{palette}-any',
            f'{palette}-{scheme}'
        ]
        # do it this way to keep order for downstream exec
        script_list = []
        for theme_prefix in theme_prefixes:
            for script_path in call_dir.iterdir():
                theme_part = script_path.stem
                if theme_part == theme_prefix:
                    script_list.append(script_path)
        return list(set(script_list))
    def update_app_config(
        self,
        app_name,
        app_settings = None,
        scheme       = 'any',
        palette      = 'any',
    ):
        '''
        Perform full app config update process, applying symlinks and running scripts.
        Note that this explicitly accepts app settings to override or act in place of
        missing app details in the app registry file. This is mostly to provide more
        programmatic control and test settings without needing them present in the
        registry file. The ``update_apps()`` method, however, **will** more strictly
        filter out those apps not in the registry, accepting a list of app keys that
        ultimately call this method.
        Note: symlinks point **from** the target location **to** the known internal config
        file; can be a little confusing.
        '''
        if app_settings is None:
            app_settings = self.app_registry.get(app_name, {})
        if 'config_dir' in app_settings and 'config_map' in app_settings:
            print(f'App "{app_name}" incorrectly configured, skipping')
            return
        to_symlink: list[tuple[Path, Path]] = []
        file_map = self.get_matching_configs(
            app_name,
            scheme=scheme,
            palette=palette,
        )
        if 'config_dir' in app_settings:
            for config_tail, full_path in file_map.items():
                to_symlink.append((
                    util.absolute_path(Path(app_settings['config_dir'], config_tail)), # point from real config dir
                    full_path, # to internal config location
                ))
        elif 'config_map' in app_settings:
            for config_tail, full_path in file_map.items():
                # app's config map points config tails to absolute paths
                if config_tail in app_settings['config_map']:
                    to_symlink.append((
                        abs_pat(Path(app_settings['config_map'][config_tail])), # point from real config path
                        full_path, # to internal config location
                    ))
        links_succ = []
        links_fail = []
        for from_path, to_path in to_symlink:
            if not to_path.exists():
                print(f'Internal config path "{to_path}" doesn\'t exist, skipping')
                links_fail.append((from_path, to_path))
                continue
            if not from_path.parent.exists():
                print(f'Target config parent directory for "{from_path}" doesn\'t exist, skipping')
                links_fail.append((from_path, to_path))
                continue
            # if config file being symlinked exists & isn't already a symlink (i.e.,
            # previously set by this script), throw an error. 
            if from_path.exists() and not from_path.is_symlink():
                print(
                    f'Symlink target "{from_path}" exists and isn\'t a symlink, NOT overwriting;' \
                   + ' please first manually remove this file so a symlink can be set.'
                )
                links_fail.append((from_path, to_path))
                continue
            else:
                # if path doesn't exist, or exists and is symlink, remove the symlink in
                # preparation for the new symlink setting
                from_path.unlink(missing_ok=True)
            #print(f'Linking [{from_path}] -> [{to_path}]')
            from_path.symlink_to(to_path)
            links_succ.append((from_path, to_path))
            # run matching scripts for app-specific reload
            # TODO: store the status of this cmd & print with the messages
            script_list = self.get_matching_scripts(
                app_name,
                scheme=scheme,
                palette=palette,
            )
            for script in script_list:
                print(Fore.BLUE + f'> Running script "{script.relative_to(self.config_dir}"')
                output = subprocess.check_output(str(script), shell=True)
                print(
                    Fore.BLUE + Style.DIM + f'-> Captured script output "{output.decode().strip()}"' + Style.RESET
                )
        for from_p, to_p in links_succ:
            from_p = from_p
            to_p   = to_p.relative_to(self.config_dir)
            print(Fore.GREEN + f'> {app_name} :: {from_p} -> {to_p}')
        for from_p, to_p in links_fail:
            from_p = from_p
            to_p   = to_p.relative_to(self.config_dir)
            print(Fore.RED + f'> {app_name} :: {from_p} -> {to_p}')
    def update_apps(
        self,
        apps: str | list[str] = '*',
        scheme                = 'any',
        palette               = 'any',
    ):
        if apps == '*':
            # get all registered apps
            app_list = list(self.app_registry.keys())
        else:
            # get requested apps that overlap with registry
            app_list = [a for a in app_list if a in app_registry]
        if not app_list:
            print(f'None of the apps "apps" are registered, exiting')
            return
        for app_name in app_list:
            self.update_app_config(
                app_name,
                app_settings=app_registry[app_name],
                scheme=scheme,
                palette=palette,
            )
--- a/autoconf/theme.py
+++ b/autoconf/theme.py
@ -1,74 +0,0 @@
 import argparse
 import inspect
 import json
 import tomllib as toml
 from pathlib import Path
 # separation sequences to use base on app
 app_sep_map = {
    'kitty': ' ',
 }
 def generate_theme_files():
    basepath = get_running_path()
    # set arg conditional variables 
    palette_path  = Path(basepath, 'themes', args.palette)
    colors_path   = Path(palette_path, 'colors.json')
    theme_app     = args.app
    template_path = None
    output_path   = None
    if args.template is None:
        template_path = Path(palette_path, 'apps', theme_app, 'templates')
    else:
        template_path = Path(args.template).resolve()
    if args.output is None:
        output_path = Path(palette_path, 'apps', theme_app, 'generated')
    else:
        output_path = Path(args.output).resolve()
    # check paths
    if not colors_path.exists():
        print(f'Resolved colors path [{colors_path}] doesn\'t exist, exiting')
        return
    if not template_path.exists():
        print(f'Template path [{template_path}] doesn\'t exist, exiting')
        return
    if not output_path.exists() or not output_path.is_dir():
        print(f'Output path [{output_path}] doesn\'t exist or not a directory, exiting')
        return
    print(f'Using palette colors [{colors_path}]')
    print(f'-> with templates in [{template_path}]')
    print(f'-> to output path [{output_path}]\n')
    # load external files (JSON, TOML)
    colors_json = json.load(colors_path.open())
    # get all matching TOML files
    template_list = [template_path]
    if template_path.is_dir():
        template_list = template_path.rglob('*.toml')
    for template_path in template_list:
        template_toml = toml.load(template_path.open('rb'))
        # lookup app-specific config separator
        config_sep = app_sep_map.get(theme_app, ' ')
        output_lines = []
        for config_key, color_key in template_toml.items():
            color_value = colors_json
            for _key in color_key.split('.'):
                color_value = color_value.get(_key, {})
            output_lines.append(f'{config_key}{config_sep}{color_value}') 
        output_file = Path(output_path, template_path.stem).with_suffix('.conf')
        output_file.write_text('\n'.join(output_lines))
        print(f'[{len(output_lines)}] lines written to [{output_file}] for app [{theme_app}]')
--- a/autoconf/util.py
+++ b/autoconf/util.py
@ -1,9 +0,0 @@
 from pathlib import Path
 from xdg import BaseDirectory
 def absolute_path(path: str | Path) -> Path:
    return Path(path).expanduser().absolute()
 def xdg_config_path():
    return Path(BaseDirectory.save_config_path('autoconf'))
--- a/docs/Makefile
+++ b/docs/Makefile
@ -0,0 +1,20 @@
 # Minimal makefile for Sphinx documentation
 #
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 .PHONY: help Makefile
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
--- a/docs/_static/example.gif
+++ b/docs/_static/example.gif
--- a/docs/conf.py
+++ b/docs/conf.py
@ -6,7 +6,7 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-project = '<project-name>'
+project = 'symconf'
 copyright = '2024, Sam Griesemer'
 author = 'Sam Griesemer'
@ -15,18 +15,25 @@ author = 'Sam Griesemer'
 extensions = [
    "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
+    "sphinx.ext.autosummary", # enables a directive to be specified manually that gathers
-    "sphinx.ext.viewcode",
+                              # module/object summary details in a table
-    "myst_parser",
+    "sphinx.ext.viewcode",    # allow viewing source in the HTML pages
    "myst_parser",            # only really applies to manual docs; docstrings still need RST-like
    "sphinx.ext.napoleon",    # enables Google-style docstring formats
    "sphinx_autodoc_typehints", # external extension that allows arg types to be inferred by type hints
 ]
 autosummary_generate = True
 autosummary_imported_members = True
 # include __init__ definitions in autodoc
 autodoc_default_options = {
    'special-members': '__init__',
 }
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
--- a/docs/index.md
+++ b/docs/index.md
@ -1,29 +1,41 @@
-# `autoconf` package docs 
+# `symconf` package docs 
 {ref}`genindex`
 {ref}`modindex`
 {ref}`search`
 ## Top-level module overview
 ```{eval-rst}
 .. autosummary::
   :nosignatures:
   :recursive:
-    # list modules here for quick links
+    symconf.config
    symconf.template
    symconf.matching
    symconf.reader
    symconf.runner
 ```
 ## Auto-reference contents
 ```{toctree}
 :maxdepth: 3
 _autoref/symconf.rst
 ```
 ```{toctree}
-:maxdepth: 3
+:maxdepth: 2
 :caption: Autoref
 _autoref/autoconf.rst
 ```
 ```{toctree}
 :maxdepth: 3
 :caption: Contents
 reference/configuring
 reference/usage
 reference/archive
 reference/documentation/index
 reference/site/index
 ```
 ```{include} ../README.md
 :relative-docs: docs/
 :relative-images:
 ```
--- a/docs/reference/archive.md
+++ b/docs/reference/archive.md
@ -0,0 +1,233 @@
 # Archive
 The `autoconf` project is an attempt at wrangling the complexity of configuring many
 applications across one's Linux system. It provides a simple operational model for pulling
 many application config files into one place, as well as generating/setting color schemes
 across apps.
 Quick terminology rundown for theme-related items:
 - **Theme**: loose term referring generally to the overall aesthetic of a visual setting.
  Ignoring stylistic changes (only applicable to some apps; example here might be a
  a particular setting of the `waybar` layout), a theme is often just the wrapper term for
  a choice of color _palette_ and _scheme_. For example, "tone4-light" could be a _theme_
  setting for an app like `kitty`, referring to both a palette and scheme.
 - **Palette**: a set of base colors used to style text or other aspects of an app's
  displayed assets
 - **Scheme**: an indication of lightness, typically either "light" or "dark.
 As far as managing settings across apps, there are current two useful classifications
 here:
 1. **Inseparable from theme**: some apps (e.g., `sway`, `waybar`) have color scheme
   components effectively built in to their canonical configuration file. This can make it
   hard to set themes dynamically, as it would likely require some involved
   matching/substitution rules. This is not a level of complexity I'm willing to embrace,
   so we simply split the config files according to theme and/or scheme.
 2. **Can load an external theme file**: some apps (e.g., `kitty`) have a clear mechanism
   for loading themes. This typically implies some distinct color format, although usually
   somewhat easy to generate (don't have to navigate non-color settings, for instance).
   Such apps allow for an even less "invasive" config swapping process when setting a new
   theme, as one can just swap out the external theme file.
 To be clear on operation implications here: apps of type (1) must have _manually
 maintained_ config variations according the desired themes. General theme settings must
 follow the naming scheme `<app-name>-<palette>-<scheme>.<ext>`. For example, if I wanted to set
 `sway` to a light variation (which, at the time of writing, would just entail changing a
 single background color), I must have explicitly created a `sway-tone4-light.conf` file
 that captures this setting. The canonical config file will then be symlinked to the
 theme-specific file when the theme is set. (Note that the palette in this example is pretty much
 irrelevant, but it needs to be present in order to match the overarching setting; here you
 can just think of the format being `<app-name>-<theme>.<ext>`, where `tone4-light` is the
 provided theme name.)
 For apps of type (2), the canonical config file can remain untouched so long as it refers
 to a fixed, generic theme file. For example, with `kitty`, my config file can point to a
 `current-theme.conf` file, which will be symlinked to a specific theme file here in
 `autoconf` when a change is requested. This enables a couple of conveniences:
 - The true config directory on disk remains unpolluted with theme variants.
 - If the set theme is regenerated, there is no intervention necessary to propagate its
  changes to the target app. The symlinked file itself will be updated when the theme
  does, ensuring the latest theme version is always immediately available and pointed to
  by the app.
 Keep in mind that some apps may fall into some grey area here, allowing some external
 customization but locking down other settings internally. In such instances, there's no
 need to overcomplicate things; just stick to explicit config variants under the type (1)
 umbrella. Type (2) only works for generated themes anyhow; even if the target app can load
 an external theme, type (1) should be used if preset themes are fixed.
 ## Naming standards
 To keep things simple, we use a few fixed naming standards for setting app config files
 and their themed counterparts. The app registry requires each theme-eligible app to
 provide a config directory (`config_dir`), containing some canonical config file
 (`config_file`) and to serve as a place for theme-specific config variations. The
 following naming schemes must be used in order for theme switching to behave
 appropriately: 
 - When setting a theme for a particular app, the following variables will be available:
    * `<app-name>`
    * `<palette>`
    * `<scheme>`
 - For apps with `external_theme = False`, config variants must named as
  `<app-name>-<palette>-<scheme>.<ext>`, where `<ext>` is the app's default config file
  extension.
 - For apps with `external_theme = True`, the file `<config-dir>/current-theme.conf` will
  be used when symlinking the requested theme. The config file thus must point to this
  file in order to change with the set theme.
  Additionally, the theme symlink will be created from the file
  ```
  <autoconf-root>/autoconf/themes/<palette>/apps/<app-name>/generated/<scheme>.conf
  ```
  to `<config-dir>/current-theme.conf`. 
 ## Directory structure
 - `autoconf/`: main repo directory
    * `config/`: app-specific configuration files. Each folder inside this directory is
      app-specific, and the target of associated copy operations when a config sync is
      performed. Nothing in this directory should pertain to any repo functionality; it
      should only contain config files that originated elsewhere on the system.
    * `themes/`: app-independent theme data files. Each folder in this directory should
      correspond to a specific color palette and house any relevant color spec files
      (currently likely be a `colors.json`). Also servers the output location for
      generated theme files
        * `<palette>/colors.json`: JSON formatted color key-value pairings for palette
          colors. There's no standard here aside from the filename and format; downstream
          app-specific TOML templates can be dependent on any key naming scheme within the
          JSON.
        + `<palette>/apps/<app-name>/templates/`: houses the TOML maps for the color
          palette `<palette>` under app `<app-name>`. Files `<fname>.toml` will be mapped to
          `<fname>.conf` in the theme output folder (below), so ensure the naming
          standards align with those outlined above.
        + `<palette>/apps/<app-name>/generated/`: output directory for generated scheme
          variants. These are the symlink targets for dynamically set external themes.
    * `app_registry.toml`: global application "registry" used by sync and theme-setting
      scripts. This lets apps be dynamically added or removed from being eligible for
      config-related operations.
 ## Scripts
 `set_theme.py`: sets a theme across select apps.
 - Applies to specific app with `-a <app>` , or to all apps in the `app_registry.toml` with
  `-a "*"`.
 - Uses symlinks to set canonical config files to theme-based variations. Which files get
  set depends on the _app type_ (see above), which really just boils down to whether
  theming (1) can be specified with an external format, and (2) if it depends on
  auto-generated theme files from within `autoconf`.
 - Palette and scheme are specified as expected. They are used to infer proper paths
  according to naming and structure standards.
 - Real config files will never be overwritten. To begin setting themes with the script,
  you must delete the canonical config file expected by the app (and specified in the app
  registry) to allow the first symlink to be set. From there on out, symlinks will be
  automatically flushed.
 - A report will be provided on which apps were successfully set to the requested theme,
  along with the file stems. A number of checks are in place for the existence of involved
  files and directories. Overall, the risk of overwritting a real config file is low; we
  only flush existing symlinks, and if the would-be target for the requested theme (be it
  from an auto-generated theme file, or from a manually manage config variant) doesn't
  exist, that app's config will be completed skipped. Essentially, everything must be in
  perfect shape before the symlink trigger is officially pulled.
 `gen_theme.py`: generates theme files for palettes by mapping their color definitions
 through app-specific templates. These templates specific how to relate an app's theme
 variables to the color names provided by the template.
 - An app and palette are the two required parameters. If no template or output paths are
  provided, they will be inferred according to the theme path standards seen above.
 - The `--template` argument can be a directory or a file, depending on what theme files
  you'd like to render.
 - The `--output` path, if specified, must be a directory. Generated theme files take on
  a name with the same stem as their source template, but using the `.conf` extension.
 - The TOML templates should make config variable names to JSON dot-notation accessors. If
  color definitions are nested, the dot notation should be properly expanded by the script
  when mapping the colors to keyword values.
 - There are a number of checks for existing paths, even those inferred (e.g., template and
  output) from the palette and app. If the appropriate setup hasn't been followed, the
  script will fail. Make sure the `theme` folder in question and it's nested `app`
  directory are correctly setup before running the script. (Perhaps down the line there
  are some easy auto-setup steps to take here, but I'm not making that jump now.)
 - TODO: open up different app "writers," or make it easy to extend output syntax based on
  the app in question. This would like be as simple as mapping app names to
  line-generating functions, which accept the keyword and color (among other items). This
  can be fleshed out as needed.
 `sync.sh`: copies relevant configuration files from local paths into the `autoconf`
 subpath. Markdown files in the docs directory then reference the local copies of these
 files, meaning the documentation updates dynamically when the configuration files do. That
 is, the (possibly extracted) config snippets will change with the current state of my
 system config without any manual intervention of the documentation files.
 ### Specific theme-setting example
 To make clear how the theme setting script works on my system, the following breaks down
 exactly what steps are taken to exert as much scheme control as possible. Everything at this
 point is wrapped up in a single `make set-<palette>-<scheme>` call; suppose we're
 currently running the dark scheme (see first image) and I run `make set-tone4-light`:
 ![
  Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the
  system-dependent default theme set). In Firefox, I have open `localsys` with its
  scheme-mode to set to "auto," which should reflect the theme setting picked up by the
  browser (and note the white tab icon).
 ](_static/set-theme-1.png)
 _(Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the
 system-dependent default theme set). In Firefox, I have open `localsys` with its
 scheme-mode to set to "auto," which should reflect the theme setting picked up by the
 browser (and note the white tab icon).)_
 1. `set_theme.py` is invoked. Global settings are applied first, based on my OS (`Linux`),
   which calls
   ```
   gsettings set org.gnome.desktop.interface color-scheme 'prefer-light'
   ```
   controlling settings for GTK apps and other `desktop-portal`-aware programs. This
   yields the following:
   ![Portal-aware apps changed, config apps not yet set](_static/set-theme-2.png)
   _(Portal-aware apps changed, config apps not yet set. Scheme-aware sites are updated
   without page refresh.)_
 2. Specific application styles are set. For now the list is small, including `kitty`,
   `waybar`, and `sway`. `kitty` is the only type (2) application here, whereas the other
   two are type (1).
   a. For the type (1) apps, the canonical config files as specified in the app registry
      are symlinked to their light variants. For `sway`, this is `~/.config/sway/config`,
      and if we look at the `file`:
      ```sh
      .config/sway/config: symbolic link to ~/.config/sway/sway-tone4-light
      ```
   b. For the type (2) apps, just the `current-theme.conf` file is symlinked to the
      relevant palette-scheme file. `kitty` is such an app, with a supported theme file
      for `tone4`, and those files have been auto-generated via `gen_theme.py`. Looking at
      this file under the `kitty` config directory:
      ```sh
      .config/kitty/current-theme.conf: symbolic link to ~/Documents/projects/autoconf/autoconf/themes/tone4/apps/kitty/generated/light.conf
      ```
      The `kitty.conf` file isn't changed, as all palette-related items are specified in
      the theme file. (Note that the general notion of a "theme" could include changes to
      other stylistic aspects, like the font family; this would likely require some hybrid
      type 1-2 approach not yet implemented).
 3. Live application instances are reloaded, according to the registered `refresh_cmd`s.
   Here the apps with style/config files set in step (2) are reloaded to reflect those
   changes. Again, in this example, this is `kitty`, `sway`, and the `waybar`.
   ![Final light setting: portal-dependent apps _and_ config-based apps changed](_static/set-theme-3.png)
   _(Final light setting: portal-dependent apps _and_ config-based apps changed)_
 4. `set_theme.py` provides a report for the actions taken; in this case, the following was
   printed:
   ![`set_theme.py` output](_static/set-theme-4.png)
   _(`set_theme.py` output)_
--- a/docs/reference/configuring.md
+++ b/docs/reference/configuring.md
@ -0,0 +1,178 @@
 # Configuring
 `symconf` operates on a central directory that houses all of the config files you may wish
 to apply. The default location for this directory is your `$XDG_CONFIG_HOME` (e.g.,
 `~/.config/symconf/`), but it can be any location on your system so long as it's specified
 (see more in Usage). 
 `symconf` expects you to create two top-level components in your config directory: an
 `apps/` directory and an `app_registry.toml` file.
 **High-level view**:
 - `symconf` operates on a single directory that houses all your config files
 - Config files in this directory must be placed under an `apps/<app-name>/` folder to be
  associated with the app `<app-name>`
 - For apps to be visible, you need an `app_registry.toml` file that tells `symconf` where
  to symlink your files in `apps/`
 ## Apps directory
 An `apps/` directory should be created in your config home, with a subdirectory
 `apps/<app-name>/` for each app with config files that you'd like to be visible to
 `symconf`. Note that simply populating an app's config folder here will do nothing on its
 own; the app must also have been registered (discussed in item #2) in order for these
 files to be used when `symconf` is invoked. (This just means you can populate your `apps/`
 folder safely without expecting any default behavior. More often than not you'll be
 expected to tell `symconf` exactly where your config files should end up, meaning you know
 exactly what it's doing.)
 ### User config 
 Inside your app-specific subdirectory, your managed config files should be placed in a
 `user/` subdirectory (distinguishing them from those generated by templates; see more
 in Themes). Your config files themselves are then expected to follow a specific naming
 scheme:
 ```sh
 <palette>-<scheme>.<config-name>
 ```
 This ties your config file to a particular theme setting as needed, and `symconf` will
 apply it if it matches the theme setting you provide when invoked. The specific values are
 as follows:
 - `scheme`: can be `light`, `dark`, or `none`. Indicates whether the config file should
  be applied specifically when requesting a light or dark mode. Use `none` to indicate
  that the config file does not have settings specific to a light/dark mode.
 - `palette`: a "palette name" of your choosing, or `none`. The palette name you use
  here may refer specifically to a color palette used by the config file, but can be
  used generally to indicate any particular group of config settings (e.g., fonts,
  transparency, etc). Use `none` to indicate that the file does not correspond to any
  particular style group.
 - `config-name`: the _name_ of the config file. This should correspond to _same path
  name_ that is expected by the app being configured. For example, if your app expects a
  config file at `a/b/c/d.conf`, "`d.conf`" is the path name.
 When invoking `symconf` with specific scheme and palette settings (see more in Usage),
 appropriate config files can be matched based on how you've named your files.
 For example, suppose I want to set up a simple light/dark mode switch for the `kitty`
 terminal emulator. The following tree demonstrates a valid setup:
 ```sh
 <config-home>
 └── apps/
    └── kitty/
        └── user/
            ├── none-light.kitty.conf
            └── none-dark.kitty.conf
 ```
 where `none-light.kitty.conf` may set a light background and `none-dark.kitty.conf` a dark
 one. `none` is used for the `<palette>` part of the name to indicate the configuration does
 not pertain to any specific palette and can be matched even if one is not provided. With
 an appropriate `app_regsitry.toml` file (see below), invoking 
 ```sh
 symconf --theme=light --apps=kitty
 ```
 would symlink `$XDG_CONFIG_HOME/symconf/apps/kitty/user/none-light.kitty.conf` to
 `~/.config/kitty/kitty.conf`.
 ### Templatized config
 Note the potential inconvenience in needing to manage two separate config files in the
 above example, very likely with all but one line of difference. Templating enables
 populating config template files dynamically with theme-specific variables of your
 choosing.
 ### Reload scripts
 After symlinking a new set of config files, it is often necessary to reload the system or
 relevant apps in order for the new config settings to apply. Within an app's subdirectory,
 a `call/` folder can be created to hold scripts that should apply based on certain schemes
 or palettes (matching them in the same way as config files). For example,
 ```sh
 <config-home>
 └── apps/
    └── kitty/
        └── call/
            └── none-none.sh
 ```
 `none-none.sh` might simply contain `kill -s USR1 $(pgrep kitty)`, which is a way to tell
 all running `kitty` instances to reload their config settings. Again, following the naming
 scheme for config files, a script named `none-none.sh` will apply under any scheme or
 palette specification. Thus, in our light/dark mode switch example, invoking `symconf
 --theme=light --apps=kitty` would:
 1. Search and match the config name `none-light.kitty.conf` and symlink it to
   `~/.config/kitty/kitty.conf`.
 2. Search and match `none-none.sh` and execute it, applying the new light mode settings to
   all running `kitty` instances.
 ## App registry
 An `app_registry.toml` file, used to specify the target locations for app-specific
 config files. To "register" an app, you simply need to add the following text block to
 the `app_registry.toml` file:
 ```toml
 [app.<app-name>]
 # DEFINE *ONE* OF THE FOLLOWING
 config_dir = "<path-to-app-config-folder>"
 # OR 
 config_map = {
    "<conf-pathname-1>" = "<path-to-exact-config-file>"
    "<conf-pathname-2>" = "<path-to-exact-config-file>"
    # ...
 }
 ```
 (Note that text in angle brackets refers to values that should be replaced.) This tells
 `symconf` how it should handle each app's config files. The `<app-name>` (e.g.,
 `kitty`) should correspond to a subdirectory under `apps/` (e.g., `apps/kitty/`) that
 holds your config files for that app. As shown, you then need to supply either of the
 following options:
 - `config_dir`: specifies a single directory where all of the app's matching config
  files should be symlinked. In the `kitty` example, this might be `~/.config/kitty`.
  This is the simplest and most common option provided most apps expect all of their
  config files to be in a single directory.
 - `config_map`: a dictionary mapping config file _path names_ to the _exact paths_ that
  should be created during the symlink process. This is typically needed when an app
  has many config files that need to be set in several disparate locations across your
  system. In the `kitty` example, although not necessary (and in general you should
  prefer to set `config_dir` when applicable), we could have the following
  `config_map`:
  ```toml
  [app.kitty]
  config_map = {
      "kitty.conf": "~/.config/kitty/kitty.conf"
  }
  ```
  This tells `symconf` to symlink the exact location `~/.config/kitty/kitty.conf` to
  the matching `kitty.conf` under the `apps/kitty` directory.
 ## Directory structure
 In total, the structure of your base config directory can look as follows:
 ```sh
 ~/.config/symconf/
 ├── app_registry.toml
 └── apps/
    └── <app>/
        ├── user/                      # user managed
        │   └── none-none.<config-name>
        ├── generated/                 # automatically populated
        │   └── none-none.<config-name>
        ├── templates/                 # config templates
        │   └── none-none.template
        └── call/                      # reload scripts
            └── none-none.sh
 ```
 ## Misc remarks
 ### Multiple config files with same path name
--- a/docs/reference/documentation/index.md
+++ b/docs/reference/documentation/index.md
@ -1,8 +1,5 @@
 # Documentation
 ```{toctree}
 :hidden:
 sphinx
 ```
--- a/docs/reference/matching.md
+++ b/docs/reference/matching.md
@ -0,0 +1,17 @@
 # Matching
 This file describes the naming and matching scheme employed by `symconf`.
 ```
 ~/.config/symconf/
 ├── app_registry.toml
 └── apps/
    └── <app>/
        ├── user/                      # user managed
        │   └── none-none.<config-name>
        ├── generated/                 # automatically populated
        │   └── none-none.<config-name>
        ├── templates/                 # config templates
        │   └── none-none.template
        └── call/                      # reload scripts
            └── none-none.sh
 ```
--- a/docs/reference/usage.md
+++ b/docs/reference/usage.md
@ -0,0 +1,6 @@
 # Usage
 ```{toctree}
 :hidden:
 ```
--- a/tests/test-config-dir/apps/kitty/user/any-any.conf.ini
+++ b/tests/test-config-dir/apps/kitty/user/any-any.conf.ini
--- a/pyproject.toml
+++ b/pyproject.toml
@ -25,8 +25,12 @@ classifiers = [
 ]
 dependencies = [
    "pyxdg",
    "colorama",
 ]
 [project.scripts]
 symconf = "symconf.__main__:main"
 [project.optional-dependencies]
 tests = ["pytest"]
 docs = [
@ -36,6 +40,7 @@ docs = [
    "furo",
    "myst-parser",
 ]
 build = ["build", "twine"]
 [project.urls]
 Homepage = "https://doc.olog.io/symconf"
--- a/symconf/init.py
+++ b/symconf/init.py
@ -0,0 +1,16 @@
 from symconf.runner import Runner
 from symconf.reader import DictReader
 from symconf.config import ConfigManager
 from symconf.matching import Matcher, FilePart
 from symconf.template import Template, FileTemplate, TOMLTemplate
 from symconf import config
 from symconf import matching
 from symconf import reader
 from symconf import template
 from symconf import util
 from importlib.metadata import version
 __version__ = version('symconf')
--- a/symconf/main.py
+++ b/symconf/main.py
@ -0,0 +1,179 @@
 import argparse
 from importlib.metadata import version
 from symconf import util, __version__
 from symconf.config import ConfigManager
 def add_install_subparser(subparsers):
    def install_apps(args):
        cm = ConfigManager(args.config_dir)
        cm.install_apps(apps=args.apps)
    parser = subparsers.add_parser(
        'install',
        description='Run install scripts for registered applications.'
    )
    parser.add_argument(
        '-a', '--apps',
        required = False,
        default  = "*",
        type     = lambda s: s.split(',') if s != '*' else s,
        help     = 'Application target for theme. App must be present in the registry. ' \
                 + 'Use "*" to apply to all registered apps'
    )
    parser.set_defaults(func=install_apps)
 def add_update_subparser(subparsers):
    def update_apps(args):
        cm = ConfigManager(args.config_dir)
        cm.update_apps(apps=args.apps)
    parser = subparsers.add_parser(
        'update',
        description='Run update scripts for registered applications.'
    )
    parser.add_argument(
        '-a', '--apps',
        required = False,
        default  = '*',
        type     = lambda s: s.split(',') if s != '*' else s,
        help     = 'Application target for theme. App must be present in the registry. ' \
                 + 'Use "*" to apply to all registered apps'
    )
    parser.set_defaults(func=update_apps)
 def add_config_subparser(subparsers):
    def configure_apps(args):
        cm = ConfigManager(args.config_dir)
        cm.configure_apps(
            apps=args.apps,
            scheme=args.mode,
            style=args.style,
            **args.template_vars
        )
    parser = subparsers.add_parser(
        'config',
        description='Set config files for registered applications.'
    )
    parser.add_argument(
        '-s', '--style',
        required = False,
        default  = 'any',
        help     = 'Style indicator (often a color palette) capturing thematic details in '
                   'a config file'
    )
    parser.add_argument(
        '-m', '--mode',
        required = False,
        default  = "any",
        help     = 'Preferred lightness mode/scheme, either "light," "dark," "any," or "none."'
    )
    parser.add_argument(
        '-a', '--apps',
        required = False,
        default  = "*",
        type     = lambda s: s.split(',') if s != '*' else s,
        help     = 'Application target for theme. App must be present in the registry. ' \
                 + 'Use "*" to apply to all registered apps'
    )
    parser.add_argument(
        '-T', '--template-vars',
        required = False,
        nargs='+',
        default  = {},
        action=util.KVPair,
        help='Groups to use when populating templates, in the form group=value'
    )
    parser.set_defaults(func=configure_apps)
 def add_generate_subparser(subparsers):
    def generate_apps(args):
        cm = ConfigManager(args.config_dir)
        cm.generate_app_templates(
            gen_dir=args.output_dir,
            apps=args.apps,
            scheme=args.mode,
            style=args.style,
            **args.template_vars
        )
    parser = subparsers.add_parser(
        'generate',
        description='Generate all template config files for specified apps'
    )
    parser.add_argument(
        '-o', '--output-dir',
        required = True,
        type     = util.absolute_path,
        help     = 'Path to write generated template files'
    )
    parser.add_argument(
        '-s', '--style',
        required = False,
        default  = 'any',
        help     = 'Style indicator (often a color palette) capturing thematic details in '
                   'a config file'
    )
    parser.add_argument(
        '-m', '--mode',
        required = False,
        default  = "any",
        help     = 'Preferred lightness mode/scheme, either "light," "dark," "any," or "none."'
    )
    parser.add_argument(
        '-a', '--apps',
        required = False,
        default  = "*",
        type     = lambda s: s.split(',') if s != '*' else s,
        help     = 'Application target for theme. App must be present in the registry. ' \
                 + 'Use "*" to apply to all registered apps'
    )
    parser.add_argument(
        '-T', '--template-vars',
        required = False,
        nargs    = '+',
        default  = {},
        action   = util.KVPair,
        help     = 'Groups to use when populating templates, in the form group=value'
    )
    parser.set_defaults(func=generate_apps)
 # central argparse entry point
 parser = argparse.ArgumentParser(
    'symconf',
    description='Manage application configuration with symlinks.'
 )
 parser.add_argument(
    '-c', '--config-dir',
    default = util.xdg_config_path(),
    type    = util.absolute_path,
    help    = 'Path to config directory'
 )
 parser.add_argument(
    '-v', '--version',
    action='version',
    version=__version__,
    help    = 'Print symconf version'
 )
 # add subparsers
 subparsers = parser.add_subparsers(title='subcommand actions')
 add_config_subparser(subparsers)
 add_generate_subparser(subparsers)
 add_install_subparser(subparsers)
 add_update_subparser(subparsers)
 def main():
    args = parser.parse_args()
    if 'func' in args:
        args.func(args)
    else:
        parser.print_help()
 if __name__ == '__main__':
    main()
--- a/symconf/config.py
+++ b/symconf/config.py
@ -0,0 +1,879 @@
 '''
 Primary config management abstractions
 The config map is a dict mapping from config file **path names** to their absolute
 path locations. That is,
 .. code-block:: sh
    <config_path_name> -> <config_dir>/apps/<app_name>/<subdir>/<palette>-<scheme>.<config_path_name>
 For example,
 .. code-block:: sh
    palette1-light.conf.ini -> ~/.config/symconf/apps/user/palette1-light.conf.ini
    palette2-dark.app.conf -> ~/.config/symconf/apps/generated/palette2-dark.app.conf
 This ensures we have unique config names pointing to appropriate locations (which
 is mostly important when the same config file names are present across ``user``
 and ``generated`` subdirectories; unique path names need to be resolved to unique
 path locations).
 '''
 import os
 import tomllib
 from pathlib import Path
 from colorama import Fore, Back, Style
 from symconf import util
 from symconf.util import printc, color_text
 from symconf.runner import Runner
 from symconf.template import FileTemplate, TOMLTemplate
 from symconf.matching import Matcher, FilePart
 class ConfigManager:
    def __init__(
        self,
        config_dir=None,
        disable_registry=False,
    ):
        '''
        Configuration manager class
        Parameters:
            config_dir: config parent directory housing expected files (registry,
                        app-specific conf files, etc). Defaults to
                        ``"$XDG_CONFIG_HOME/symconf/"``.
            disable_registry: disable checks for a registry file in the ``config_dir``.
                              Should really only be set when using this programmatically
                              and manually supplying app settings.
        '''
        if config_dir == None:
            config_dir = util.xdg_config_path()
        self.config_dir = util.absolute_path(config_dir)
        self.apps_dir   = Path(self.config_dir, 'apps')
        self.group_dir  = Path(self.config_dir, 'groups')
        self.app_registry = {}
        self.matcher = Matcher()
        self.runner  = Runner()
        self._check_dirs()
        if not disable_registry:
            self._check_registry()
    def _check_dirs(self):
        '''
        Check necessary config directories for existence.
        Regardless of programmatic use or ``disable_registry``, we need a valid
        ``config_dir`` and it must have an ``apps/`` subdirectory (otherwise there are
        simply no files to act on, not even when manually providing app settings).
        '''
        # throw error if config dir doesn't exist
        if not self.config_dir.exists():
            raise ValueError(
                f'Config directory "{self.config_dir}" doesn\'t exist.'
            )
        # throw error if apps dir doesn't exist or is empty
        if not self.apps_dir.exists() or not list(self.apps_dir.iterdir()):
            raise ValueError(
                f'Config directory "{self.config_dir}" must have an "apps/" subdirectory.'
            )
    def _check_registry(self):
        '''
        Check the existence and format of the registry file
        ``<config_dir>/app_registry.toml``.
        All that's needed to pass the format check is the existence of the key `"app"` in
        the registry dict. If this isn't present, the TOML file is either incorrectly
        configured, or it's empty and there are no apps to operate on.
        '''
        registry_path = Path(self.config_dir, 'app_registry.toml')
        if not registry_path.exists():
            printc(
                f'No registry file found at expected location "{registry_path}"',
                Fore.YELLOW
            )
            return
        app_registry = tomllib.load(registry_path.open('rb'))
        if 'app' not in app_registry:
            printc(
                'Registry file found but is either empty or incorrectly formatted (no "app" key).',
                Fore.YELLOW
            )
        self.app_registry = app_registry.get('app', {})
    def _resolve_group(self, group, value='auto'):
        '''
        Resolve group inputs to concrete values.
        This method is mostly meant to handle values like ``auto`` which can be provided
        by the user, but need to be interpreted in the system context (e.g., either
        resolving to "any" or using the app's currently set option from the cache).
        '''
        if value == 'auto':
            # look group up in app cache and set to current value
            return 'any'
        return value
    def _symlink_paths(
        self,
        to_symlink: list[tuple[Path, Path]],
    ):
        '''
        Symlink paths safely from target paths to internal config paths 
        This method upholds the consistent symlink model: target locations are only
        symlinked from if they don't exist or are already a symlink. We never overwrite
        any concrete files, preventing accidental deletion of config files. This means
        users must physically delete/move their existing configs into a ``symconf`` config
        directory if they want it to be managed; otherwise, we don't touch it.
        Parameters:
            to_symlink: path pairs to symlink, from target (external) path to source
                        (internal) path
        '''
        links_succ = []
        links_fail = []
        for from_path, to_path in to_symlink:
            if not to_path.exists():
                print(f'Internal config path "{to_path}" doesn\'t exist, skipping')
                links_fail.append((from_path, to_path))
                continue
            # if config file being symlinked exists & isn't already a symlink (i.e.,
            # previously set by this script), throw an error.
            if from_path.exists() and not from_path.is_symlink():
                printc(
                    f'Symlink target "{from_path}" exists and isn\'t a symlink, NOT overwriting; '
                    f'please first manually remove this file so a symlink can be set.',
                    Fore.RED 
                )
                links_fail.append((from_path, to_path))
                continue
            else:
                # if path doesn't exist, or exists and is symlink, remove the symlink in
                # preparation for the new symlink setting
                from_path.unlink(missing_ok=True)
            # create parent directory if doesn't exist
            from_path.parent.mkdir(parents=True, exist_ok=True)
            from_path.symlink_to(to_path)
            links_succ.append((from_path, to_path))
        # link report
        for from_p, to_p in links_succ:
            from_p = util.to_tilde_path(from_p)
            to_p   = to_p.relative_to(self.config_dir)
            print(
                color_text("│", Fore.BLUE),
                color_text(
                    f' > linked {color_text(from_p,Style.BRIGHT)} -> {color_text(to_p,Style.BRIGHT)}',
                    Fore.GREEN
                )
            )
        for from_p, to_p in links_fail:
            from_p = util.to_tilde_path(from_p)
            to_p   = to_p.relative_to(self.config_dir)
            print(
                color_text("│", Fore.BLUE),
                color_text(
                    f' > failed to link {from_p} -> {to_p}',
                    Fore.RED
                )
            )
    def _matching_template_groups(
        self, 
        scheme = 'auto',
        style  = 'auto',
        **kw_groups,
    ) -> tuple[dict, list[FilePart]]:
        '''
        Find matching template files for provided template groups.
        For template groups other than "scheme" and "style," this method performs a
        basic search for matching filenames in the respective group directory. For
        example, a KW group like ``font = "mono"`` would look for ``font/mono.toml`` (as
        well as the relaxation ``font/none.toml``). These template TOML files are stacked
        and ultimately presented to downstream config templates to be filled. Note how
        there is no dependence on the scheme during the filename match (e.g., we don't
        look for ``font/mono-dark.toml``).
        For "scheme" and "style," we have slightly different behavior, more closely
        aligning with the non-template matching. We don't have "scheme" and "style"
        template folders, but a single "theme" folder, within which we match template
        files just the same as we do for non-template config files. That is, we will look
        for files of the format
        .. code-block:: sh
            <style>-<scheme>.toml
        The only difference is that, while ``style`` can still include arbitrary style
        variants, it *must* have the form
        .. code-block:: sh
            <variant-1>-...-<variant-N>-<palette>
        if you want to match a ``palette`` template. Palettes are like regular template
        groups, and should be placed in their own template folder. But when applying those
        palette colors, they almost always need to be coupled with a scheme setting (e.g.,
        "solarized-dark"). This is the one place where the templating system allows
        "intermediate templates:" raw palette colors can fill theme templates, which then
        fill user config templates.
        So in summary: palette files can be used to populate theme templates by providing a
        style string that matches the format ``<variant>-<palette>``. The ``<palette>``
        will be extracted and used to match filenames in the palette template folder. The
        term ``<variant>-<palette>-<scheme>`` will be used to match templates in the theme
        folder, where ``<variant>-<palette> = <style>`` and ``<scheme>`` are independently
        specifiable with supported for ``auto``, ``none``, etc.
        Note that "strictness" doesn't really apply in this setting. In the non-template
        config matching setting, setting strict means there's no relaxation to "none," but
        here, any "none" group template files just help fill any gaps (but are otherwise
        totally overwritten, even if matched, by more precise matches). You can match
        ``nones`` directly if you want by specifying that directly.
        ``get_matching_scripts()`` is similar in this sense.
        '''
        scheme = self._resolve_group('scheme', scheme)
        style  = self._resolve_group('style', style)
        groups = {
            k : self._resolve_group(k, v)
            for k, v in kw_groups.items()
        }
        if not self.group_dir.exists():
            return {}, []
        # palette lookup will behave like other groups; strip it out of the `style` string
        # and it to the keyword groups to be searched regularly (but only if the palette
        # group exists)
        if Path(self.group_dir, 'palette').exists():
            palette = style.split('-')[-1]
            groups['palette'] = palette
        # handle individual groups (not part of joint style-scheme)
        group_matches = {}
        for fkey, fval in groups.items():
            key_group_dir = Path(self.group_dir, fkey)
            if not key_group_dir.exists():
                print(f'Group directory "{fkey}" doesn\'t exist, skipping')
                continue
            # mirror matching scheme: 1) prefix order, 2) full enumeration, 3) select
            # best, 4) make unique, 5) ordered relaxation
            stem_map = {path.stem : path for path in key_group_dir.iterdir()}
            # 1) establish prefix order
            if fval == 'any':
                prefix_order = [fval, 'none']
            else:
                prefix_order = ['none', fval]
            # 2) fully enumerate matches, including "any"
            matches = []
            for prefix in prefix_order:
                for stem in stem_map:
                    if prefix == stem or prefix == 'any':
                        matches.append(stem)
            if not matches:
                # no matches for group, skip
                continue
            # 3) select best matches; done in a loop to smooth the logic, else we'd need
            # to check if the last match is "none," and if not, find out if it was
            # available. This alone makes the following loop more easy to follow: walk
            # through full enumeration, and if it's the target match or "none," take the
            # file, nicely handling the fact those may both be the same.
            #
            # also 4) uniqueness happening here
            match_dict = {}
            target = matches[-1] # select best based on order, make new target
            for stem in matches:
                if stem == target or stem == 'none':
                    match_dict[stem] = stem_map[stem]
            group_matches[fkey] = list(match_dict.values())
        # first handle scheme maps; matching palette files should already be found in the
        # regular group matching process. This is the one template group that gets nested
        # treatment
        palette_dict = TOMLTemplate.stack_toml(group_matches.get('palette', []))
        # then palette-scheme groups (require 2-combo logic)
        theme_matches = []
        theme_group_dir = Path(self.group_dir, 'theme')
        if theme_group_dir.exists():
            theme_matches = self.matcher.match_paths(
                theme_group_dir.iterdir(),               # match files in groups/theme/
                self.matcher.prefix_order(scheme, style) # reg non-template order
            )
        # 5) final match relaxation
        relaxed_theme_matches = self.matcher.relaxed_match(theme_matches)
        theme_dict = {}
        for file_part in relaxed_theme_matches:
            toml_dict = TOMLTemplate(file_part.path).fill(palette_dict)
            theme_dict = util.deep_update(theme_dict, toml_dict)
        template_dict = {
            group : TOMLTemplate.stack_toml(ordered_matches)
            for group, ordered_matches in group_matches.items()
        }
        template_dict['theme'] = theme_dict
        return template_dict, relaxed_theme_matches
    def _prepare_all_templates(
        self,
        scheme = 'any',
        style  = 'any',
    ) -> dict[str, dict]:
        palette_map = {}
        palette_group_dir = Path(self.group_dir, 'palette')
        if palette_group_dir.exists():
            for palette_path in palette_group_dir.iterdir():
                palette_map[palette_path.stem] = palette_path
        palette_base = []
        if 'none' in palette_map:
            palette_base.append(palette_map['none'])
        # then palette-scheme groups (require 2-combo logic)
        theme_matches = []
        theme_group_dir = Path(self.group_dir, 'theme')
        if theme_group_dir.exists():
            theme_matches = self.matcher.match_paths(
                theme_group_dir.iterdir(),     # match files in groups/theme/
                self.matcher.prefix_order(     # reg non-template order
                    scheme, style, strict=True # set strict=True to ignore "nones"
                ) 
            )
        theme_map = {}
        for fp in theme_matches:
            # still look through whole theme dir here (eg to match nones)
            theme_matches = self.matcher.match_paths(
                theme_group_dir.iterdir(),               # match files in groups/theme/
                self.matcher.prefix_order(fp.scheme, fp.style) # reg non-template order
            )
            relaxed_theme_matches = self.matcher.relaxed_match(theme_matches)
            palette = fp.style.split('-')[-1]
            palette_paths = [*palette_base]
            if palette in palette_map:
                palette_paths.append(palette_map[palette])
            theme_dict = {}
            palette_dict = TOMLTemplate.stack_toml(palette_paths)
            for file_part in relaxed_theme_matches:
                toml_dict = TOMLTemplate(file_part.path).fill(palette_dict)
                theme_dict = util.deep_update(theme_dict, toml_dict)
            theme_map[fp.path.stem] = {'theme': theme_dict}
        return theme_map
    def get_matching_configs(
        self, 
        app_name,
        scheme = 'auto',
        style  = 'auto',
        strict = False,
    ) -> dict[str, FilePart]:
        '''
        Get user-provided app config files that match the provided scheme and style
        specifications.
        Unique config file path names are written to the file map in order of specificity.
        All config files follow the naming scheme ``<style>-<scheme>.<path-name>``,
        where ``<style>-<scheme>`` is the "theme part" and ``<path-name>`` is the "conf
        part." For those config files with the same "conf part," only the entry with the
        most specific "theme part" will be stored. By "most specific," we mean those
        entries with the fewest possible components named ``none``, with ties broken in
        favor of a more specific ``style`` (the only "tie" really possible here is when
        ``none-<scheme>`` and ``<style>-none`` are both available, in which case the latter
        will overwrite the former).
        .. admonition:: Edge cases
            There are a few quirks to this matching scheme that yield potentially
            unintuitive results. As a recap:
            - The "theme part" of a config file name includes both a style (palette and
              more) and a scheme component. Either of those parts may be "none," which
              simply indicates that that particular file does not attempt to change that
              factor. "none-light," for instance, might simply set a light background,
              having no effect on other theme settings.
            - Non-keyword queries for scheme and style will always be matched exactly.
              However, if an exact match is not available, we also look for "none" in each
              component's place. For example, if we wanted to set "solarized-light" but
              only "none-light" was available, it would still be set because we can still
              satisfy the desire scheme (light). The same goes for the style
              specification, and if neither match, "none-none" will always be matched if
              available. Note that if "none" is specified exactly, it will be matched
              exactly, just like any other value.
            - During a query, "any" may also be specified for either component, indicating
              we're okay to match any file's text for that part. For example, if I have
              two config files ``"p1-dark"`` and ``"p2-dark"``, the query for ``("any",
              "dark")`` would suggest I'd like the dark scheme but am okay with either
              style.
            It's under the "any" keyword where possibly counter-intuitive results may come
            about. Specifying "any" does not change the mechanism that seeks to optionally
            match "none" if no specific match is available. For example, suppose we have
            the config file ``red-none`` (setting red colors regardless of a light/dark
            mode). If I query for ``("any", "dark")``, ``red-none`` will be matched
            (supposing there are no more direct matches available). Because we don't a
            match specifically for the scheme "dark," it gets relaxed to "none." But we
            indicated we're okay to match any style. So despite asking for a config that
            sets a dark scheme and not caring about the style, we end up with a config
            that explicitly does nothing about the scheme but sets a particular style.
            This matching process is still consistent with what we expect the keywords to
            do, it just slightly muddies the waters with regard to what can be matched
            (mostly due to the amount that's happening under the hood here).
            This example is the primary driver behind the optional ``strict`` setting,
            which in this case would force the dark scheme to be matched (and ultimately
            find no matches).
            Also: when "any" is used for a component, options with "none" are prioritized,
            allowing "any" to be as flexible and unassuming as possible (only matching a
            random specific config among the options if there is no "none" available).
        Returns:
            Dictionary 
        '''
        user_app_dir = Path(self.apps_dir, app_name, 'user')
        paths = []
        if user_app_dir.is_dir():
            paths = user_app_dir.iterdir()
        # 1) establish prefix order
        prefix_order = self.matcher.prefix_order(
            self._resolve_group('scheme', scheme),
            self._resolve_group('style', style),
            strict=strict
        )
        # 2) match enumeration
        ordered_matches = self.matcher.match_paths(paths, prefix_order)
        # 3) make unique (by pathname)
        matching_file_map = {
            file_part.conf : file_part
            for file_part in ordered_matches
        }
        return matching_file_map
    def get_matching_templates(
        self,
        app_name,
        scheme='auto',
        style='auto',
        **kw_groups,
    ) -> tuple[dict[str, Path], dict, list[FilePart], int]:
        template_dict, theme_matches = self._matching_template_groups(
            scheme=scheme,
            style=style,
            **kw_groups,
        )
        max_idx = 0
        if theme_matches:
            max_idx = max([fp.index for fp in theme_matches])
        template_map = {}
        template_dir = Path(self.apps_dir, app_name, 'templates')
        if template_dir.is_dir():
            for template_file in template_dir.iterdir():
                template_map[template_file.name] = template_file
        return template_map, template_dict, theme_matches, max_idx
    def get_matching_scripts(
        self,
        app_name,
        scheme='any',
        style='any',
    ) -> list[FilePart]:
        '''
        Execute matching scripts in the app's ``call/`` directory.
        Scripts need to be placed in
        .. code-block:: sh
            <config_dir>/apps/<app_name>/call/<style>-<scheme>.sh
        and are matched using the same heuristic employed by config file symlinking
        procedure (see ``get_matching_configs()``), albeit with a forced ``prefix_order``,
        ordered by increasing specificity. The order is then reversed, and the final list
        orders the scripts by the first time they appear (intention being to reload
        specific settings first).
        TODO: consider running just the most specific script? Users might want to design
        their scripts to be stackable, or they may just be independent.
        '''
        app_dir  = Path(self.apps_dir, app_name)
        call_dir = Path(app_dir, 'call')
        if not call_dir.is_dir():
            return []
        prefix_order = [
            ('none', 'none'),
            ('none', scheme),
            (style,  'none'),
            (style,  scheme),
        ]
        script_matches = self.matcher.match_paths(
            call_dir.iterdir(),
            prefix_order=prefix_order
        )
        relaxed_matches = self.matcher.relaxed_match(script_matches)
        # flip list to execute by decreasing specificity
        return relaxed_matches[::-1]
    def update_app_config(
        self,
        app_name     : str,
        app_settings : dict = None,
        scheme       : str  = 'any',
        style        : str  = 'any',
        strict       : bool = False,
        **kw_groups,
    ):
        '''
        Perform full app config update process, applying symlinks and running scripts.
        Note that this explicitly accepts app settings to override or act in place of
        missing app details in the app registry file. This is mostly to provide more
        programmatic control and test settings without needing them present in the
        registry file. The ``update_apps()`` method, however, **will** more strictly
        filter out those apps not in the registry, accepting a list of app keys that
        ultimately call this method.
        Note: symlinks point **from** the target location **to** the known internal config
        file; can be a little confusing.
        .. admonition:: Logic overview
            This method is the center point of the ConfigManager class. It unifies the
            user and template matching, file generation, setting of symlinks, and running
            of scripts. At a high level,
            1. An app name (e.g., kitty), app settings (e.g., a ``config_dir`` or
               ``config_map``), scheme (e.g., "dark"), and style (e.g., "soft-gruvbox")
            2. Get matching user config files via ``get_matching_configs()``
            3. Get matching template config files and the aggregate template dict via
               ``get_matching_templates()``
            4. Interleave the two result sets by pathname and match quality. Template
               matches are preferred in the case of tied scores. This resolves any
               pathname clashes across matching files.
               This is a particularly important step. It compares concrete config names
               explicitly provided by the user (e.g., ``soft-gruvbox-dark.kitty.conf``)
               with named TOML files in a group directory (e.g,.
               ``theme/soft-gruvbox-dark.toml``). We have to determine whether the
               available templates constitute a better match than the best user option,
               which is done by comparing the level in the prefix order (the index)
               where the match takes place.
               Templates are generally more flexible, and other keywords may also provide
               a matching template group (e.g., ``-T font=mono`` to match some
               font-specific settings). When the match is otherwise equally good (e.g.,
               both style and scheme match directly), we prefer the template due to its
               general portability and likelihood of being more up-to-date. We also don't
               explicitly use the fact auxiliary template groups might be matched by the
               user's input: we only compare the user and template configs on the basis of
               the quality of the style-scheme match. This effectively means additional
               template groups (e.g., font) don't "count" if the basis style-scheme
               doesn't win over a user config file. There could be an arbitrary number of
               other template group matches, but they don't contribute to the match
               quality. For instance, a concrete user config ``solarized-dark.kitty.conf``
               will be selected over ``solarized-none.toml`` plus 10 other matching theme
               elements if the user asked for ``-s dark -t solarized``.
            5. For those template matches, fill/generate the template file and place it in
               the app's ``generated/`` directory.
        Parameters:
            app_name: name of the app whose config files should be updated
            app_settings: dict of app settings (i.e., ``config_dir`` or ``config_map``)
            scheme: scheme spec
            style: style spec
            strict: whether to match ``scheme`` and ``style`` strictly 
        '''
        if app_settings is None:
            app_settings = self.app_registry.get(app_name, {})
        if 'config_dir' in app_settings and 'config_map' in app_settings:
            print(f'App "{app_name}" incorrectly configured, skipping')
            return
        # match both user configs and templates
        # -> "*_map" are dicts from config pathnames to FilePart / Paths
        config_map = self.get_matching_configs(
            app_name,
            scheme=scheme,
            style=style,
            strict=strict,
        )
        template_map, template_dict, theme_matches, tidx = self.get_matching_templates(
            app_name,
            scheme=scheme,
            style=style,
            **kw_groups
        )
        # create "generated" directory for the app
        generated_path = Path(self.apps_dir, app_name, 'generated')
        generated_path.mkdir(parents=True, exist_ok=True)
        # track selected configs with a pathname -> fullpath map 
        final_config_map = {}
        # tracker for template configs that were generated
        generated_config = []
        # interleave user and template matches
        for pathname, full_path in template_map.items():
            if pathname in config_map and config_map[pathname].index > tidx:
                final_config_map[pathname] = config_map[pathname].path
            else:
                config_path = Path(generated_path, pathname)
                config_path.write_text(
                    FileTemplate(full_path).fill(template_dict)
                )
                final_config_map[pathname] = config_path
                generated_config.append(pathname)
        # fill in any config matches not added to final_config_map above
        for pathname, file_part in config_map.items():
            if pathname not in final_config_map:
                final_config_map[pathname] = file_part.path
        # prepare symlinks (inverse loop and conditional order is sloppier)
        to_symlink: list[tuple[Path, Path]] = []
        if 'config_dir' in app_settings:
            config_dir = util.absolute_path(app_settings['config_dir'])
            for ext_pathname, int_fullpath in final_config_map.items():
                ext_fullpath = Path(config_dir, ext_pathname)
                to_symlink.append((
                    ext_fullpath, # point from external config dir
                    int_fullpath, # to internal config location
                ))
        elif 'config_map' in app_settings:
            for ext_pathname, int_fullpath in final_config_map.items():
                # app's config map points config pathnames to absolute paths
                if ext_pathname in app_settings['config_map']:
                    ext_fullpath = util.absolute_path(app_settings['config_map'][ext_pathname])
                    to_symlink.append((
                        ext_fullpath, # point from external config path
                        int_fullpath, # to internal config location
                    ))
        # run matching scripts for app-specific reload
        script_list = self.get_matching_scripts(
            app_name,
            scheme=scheme,
            style=style,
        )
        script_list = list(map(lambda f:f.path, script_list))
        # print match messages
        num_links = len(to_symlink)
        num_scripts = len(script_list)
        print(
            color_text("├─", Fore.BLUE),
            f'{app_name} :: matched ({num_links}) config files and ({num_scripts}) scripts'
        )
        rel_theme_matches = ' < '.join([
            str(fp.path.relative_to(self.group_dir))
            for fp in theme_matches
        ])
        for pathname in generated_config:
            print(
                color_text("│", Fore.BLUE),
                color_text(
                    f' > generating config "{pathname}" from [{rel_theme_matches}]',
                    Style.DIM
                )
            )
        self._symlink_paths(to_symlink)
        self.runner.run_many(script_list)
    def configure_apps(
        self,
        apps   : str | list[str] = '*',
        scheme : str             = 'any',
        style  : str             = 'any',
        strict : bool            = False,
        **kw_groups,
    ):
        if apps == '*':
            # get all registered apps
            app_list = list(self.app_registry.keys())
        else:
            # get requested apps that overlap with registry
            app_list = [a for a in apps if a in self.app_registry]
        if not app_list:
            print(f'None of the apps "{apps}" are registered, exiting')
            return
        print(f'> symconf parameters: ')
        print(f'  > registered apps :: {color_text(app_list, Fore.YELLOW)}')
        print(f'  > style           :: {color_text(style, Fore.YELLOW)}')
        print(f'  > scheme          :: {color_text(scheme, Fore.YELLOW)}\n')
        for app_name in app_list:
            app_dir = Path(self.apps_dir, app_name)
            if not app_dir.exists():
                # app has no directory, skip it
                continue
            self.update_app_config(
                app_name,
                app_settings=self.app_registry[app_name],
                scheme=scheme,
                style=style,
                strict=False,
                **kw_groups,
            )
    def _app_action(
        self,
        script_pathname,
        apps: str | list[str] = '*',
    ):
        '''
        Execute a static script-based action for a provided set of apps.
        Mostly a helper method for install and update actions, calling a static script
        name under each app's directory.
        '''
        if apps == '*':
            # get all registered apps
            app_list = list(self.app_registry.keys())
        else:
            # get requested apps that overlap with registry
            app_list = [a for a in apps if a in self.app_registry]
        if not app_list:
            print(f'None of the apps "{apps}" are registered, exiting')
            return
        print(
            f'> symconf parameters: '
            f'  > registered apps :: {color_text(app_list, Fore.YELLOW)}'
        )
        for app_name in app_list:
            target_script = Path(self.apps_dir, app_name, script_pathname)
            if not target_script.exists():
                continue
            self.runner.run_script(target_script)
    def install_apps(
        self,
        apps: str | list[str] = '*',
    ):
        self._app_action('install.sh', apps)
    def update_apps(
        self,
        apps: str | list[str] = '*',
    ):
        self._app_action('update.sh', apps)
    def generate_app_templates(
        self,
        gen_dir : str | Path,
        apps    : str | list[str] = '*',
        scheme : str             = 'any',
        style  : str             = 'any',
        **kw_groups,
    ):
        if apps == '*':
            app_list = list(self.app_registry.keys())
        else:
            app_list = [a for a in apps if a in self.app_registry]
        if not app_list:
            print(f'None of the apps "{apps}" are registered, exiting')
            return
        print(f'> symconf parameters: ')
        print(f'  > registered apps :: {color_text(app_list, Fore.YELLOW)}')
        print(f'> Writing templates...')
        gen_dir = util.absolute_path(gen_dir)
        theme_map = self._prepare_all_templates(scheme, style)
        for app_name in app_list:
            app_template_dir = Path(self.apps_dir, app_name, 'templates')
            if not app_template_dir.exists():
                continue
            app_template_files = list(app_template_dir.iterdir())
            self.get_matching_templates(
                app_name,
                scheme=scheme,
                style=style,
                **kw_groups
            )
            num_temps  = len(app_template_files)
            num_themes = len(theme_map)
            print(
                color_text("├─", Fore.BLUE),
                f'{app_name} :: generating ({num_temps}) templates from ({num_themes}) themes'
            )
            for template_file in app_template_files:
                app_template = FileTemplate(template_file)
                for theme_stem, theme_dict in theme_map.items():
                    tgt_template_dir = Path(gen_dir, app_name)
                    tgt_template_dir.mkdir(parents=True, exist_ok=True)
                    tgt_template_path = Path(
                        tgt_template_dir,
                        f'{theme_stem}.{template_file.name}'
                    )
                    filled_template = app_template.fill(theme_dict)
                    tgt_template_path.write_text(filled_template)
                    print(
                        color_text("│", Fore.BLUE),
                        f'>  generating "{tgt_template_path.name}"'
                    )
--- a/symconf/matching.py
+++ b/symconf/matching.py
@ -0,0 +1,253 @@
 '''
 Generic combinatorial name-matching subsystem
 Config files are expected to have names matching the following spec:
 .. code-block:: sh
    <style>-<scheme>.<config_pathname>
 - ``config_pathname``: refers to a concrete filename, typically that which is expected by
  the target app (e.g., ``kitty.conf``). In the context of ``config_map`` in the registry,
  however, it merely serves as an identifier, as it can be mapped onto any path.
 - ``scheme``: indicates the lightness mode ("light" or "dark")
 - ``style``: general identifier capturing the stylizations applied to the config file.
  This is typically of the form ``<variant>-<palette>``, i.e., including a reference to a
  particular color palette. 
 For example
 .. code-block:: sh
    soft-gruvbox-dark.kitty.conf
 gets mapped to 
 .. code-block:: sh
    style    -> "soft-gruvbox"
    scheme   -> "dark"
    pathname -> "kitty.conf"
 '''
 from pathlib import Path
 from symconf import util
 class FilePart:
    def __init__(self, path: str | Path):
        self.path = util.absolute_path(path)
        self.pathname = self.path.name
        parts = str(self.pathname).split('.')
        if len(parts) < 2:
            raise ValueError(f'Filename "{pathname}" incorrectly formatted, ignoring')
        self.theme = parts[0]
        self.conf  = '.'.join(parts[1:])
        theme_split = self.theme.split('-')
        self.scheme = theme_split[-1]
        self.style  = '-'.join(theme_split[:-1])
        self.index = -1
    def set_index(self, idx: int):
        self.index = idx
 class Matcher:
    def get_file_parts(
        self, 
        paths: list[str | Path],
    ) -> list[FilePart]:
        '''
        Split pathnames into parts for matching.
        Pathnames should be of the format
        .. code-block:: sh
            <style>-<scheme>.<config_pathname>
        where ``style`` is typically itself of the form ``<variant>-<palette>``.
        '''
        file_parts = []
        for path in paths:
            try:
                config_file = FilePart(path)
                file_parts.append(config_file)
            except ValueError as e:
                print(f'Filename "{pathname}" incorrectly formatted, ignoring')
        return file_parts
    def prefix_order(
        self, 
        scheme,
        style,
        strict=False,
    ) -> list[tuple[str, str]]:
        '''
        Determine the order of concrete config pathname parts to match, given the
        ``scheme`` and ``style`` inputs.
        There is a unique preferred match order when ``style``, ``scheme``, both, or none
        are ``any``. In general, when ``any`` is provided for a given factor, it is
        best matched by a config file that expresses indifference under that factor.
        '''
        # explicit cases are the most easily managed here, even if a little redundant
        if strict:
            theme_order = [
                (style, scheme),
            ]
        else:
            # inverse order of match relaxation; intention being to overwrite with
            # results from increasingly relevant groups given the conditions
            if style == 'any' and scheme == 'any':
                # prefer both be "none", with preference for specific scheme
                theme_order = [
                    (style , scheme),
                    (style , 'none'),
                    ('none'  , scheme),
                    ('none'  , 'none'),
                ]
            elif style == 'any':
                # prefer style to be "none", then specific, then relax specific scheme
                # to "none"
                theme_order = [
                    (style , 'none'),
                    ('none'  , 'none'),
                    (style , scheme),
                    ('none'  , scheme),
                ]
            elif scheme == 'any':
                # prefer scheme to be "none", then specific, then relax specific style
                # to "none"
                theme_order = [
                    ('none'  , scheme),
                    ('none'  , 'none'),
                    (style , scheme),
                    (style , 'none'),
                ]
            else:
                # neither component is any; prefer most specific
                theme_order = [
                    ('none'  , 'none'),
                    ('none'  , scheme),
                    (style , 'none'),
                    (style , scheme),
                ]
        return theme_order
    def match_paths(
        self, 
        paths: list[str | Path],
        prefix_order: list[tuple[str, str]],
    ) -> list[FilePart]:
        '''
        Find and return FilePart matches according to the provided prefix order.
        The prefix order specifies all valid style-scheme combos that can be considered as
        "consistent" with some user input (and is computed external to this method). For
        example, it could be
        .. code-block:: python
            [
                ('none', 'none')
                ('none', 'dark')
            ]
        indicating that either ``none-none.<config>`` or ``none-dark.<config>`` would be
        considered matching pathnames, with the latter being preferred.
        This method exists because we need a way to allow any of the combos in the prefix
        order to match the candidate files. We don't know a priori how good of a match
        will be available, so we consider each file for each of the prefixes, and take the
        latest/best match for each unique config pathname (allowing for a "soft" match).
        .. admonition:: Checking for matches
            When thinking about how best to structure this method, it initially felt like
            indexing factors of the FileParts would make the most sense, preventing the
            inner loop that needs to inspect each FilePart for each element of the prefix
            order. But indexing the file parts and checking against prefixes isn't so
            straightforward, as we'd still need to check matches by factor. For instance,
            if we index by style-scheme, either are allowed to be "any," so we'd need to
            check for the 4 valid combos and join the matching lists. If we index by both
            factors individually, we may have several files associated with a given key,
            and then need to coordinate the checks across both to ensure they belong to
            the same file.
            In any case, you should be able to do this in a way that's a bit more
            efficient, but the loop and the simple conditionals is just much simpler to
            follow. We're also talking about at most 10s of files, so it really doesn't
            matter.
        Parameters:
            pathnames:
            scheme:
            style:
            prefix_order:
            strict:
        '''
        file_parts = self.get_file_parts(paths)
        ordered_matches = []
        for i, (style_prefix, scheme_prefix) in enumerate(prefix_order):
            for fp in file_parts:
                style_match  = style_prefix == fp.style or style_prefix == 'any'
                scheme_match = scheme_prefix == fp.scheme or scheme_prefix == 'any'
                if style_match and scheme_match:
                    fp.set_index(i+1)
                    ordered_matches.append(fp)
        return ordered_matches
    def relaxed_match(
        self,
        match_list: list[FilePart]
    ) -> list[FilePart]:
        '''
        Isolate the best match in a match list and find its relaxed variants.
        This method allows us to use the ``match_paths()`` method for matching templates
        rather than direct user config files. In the latter case, we want to symlink the
        single best config file match for each stem, across all stems with matching
        prefixes (e.g., ``none-dark.config.a`` and ``solarized-dark.config.b`` have two
        separate stems with prefixes that could match ``scheme=dark, style=any`` query).
        We can find these files by just indexing the ``match_path`` outputs (i.e., all
        matches) by config pathname and taking the one that appears latest (under the
        prefix order) for each unique value.
        In the template matching case, we want only a single best file match, period
        (there's really no notion of "config stems," it's just the prefixes). Once that
        match has been found, we can then "relax" either the scheme or style (or both) to
        ``none``, and if the corresponding files exist, we use those as parts of the
        template keys. For example, if we match ``solarized-dark.toml``, we would also
        consider the values in ``none-dark.toml`` if available. The TOML values that are
        defined in the most specific (i.e., better under the prefix order) match are
        loaded "on top of" those less specific matches, overwriting keys when there's a
        conflict. ``none-dark.toml``, for instance, might define a general dark scheme
        background color, but a more specific definition in ``solarized-dark.toml`` would
        take precedent. These TOML files would be stacked before using the resulting
        dictionary to populate config templates.
        '''
        if not match_list:
            return []
        relaxed_map = {}
        match = match_list[-1]
        for fp in match_list:
            style_match  = fp.style  == match.style  or fp.style  == 'none'
            scheme_match = fp.scheme == match.scheme or fp.scheme == 'none'
            if style_match and scheme_match:
                relaxed_map[fp.pathname] = fp
        return list(relaxed_map.values())
--- a/symconf/reader.py
+++ b/symconf/reader.py
@ -0,0 +1,97 @@
 '''
 Simplified management for nested dictionaries
 '''
 import copy
 import pprint
 import tomllib
 import hashlib
 from typing import Any
 from pathlib import Path
 from symconf.util import deep_update
 class DictReader:
    def __init__(self, toml_path=None):
        self._config = {}
        self.toml_path = toml_path
        if toml_path is not None:
            self._config = self._load_toml(toml_path)
    def __str__(self):
        return pprint.pformat(self._config, indent=4)
    @staticmethod
    def _load_toml(toml_path) -> dict[str, Any]:
        return tomllib.loads(Path(toml_path).read_text())
    @classmethod
    def from_dict(cls, config_dict):
        new_instance = cls()
        new_instance._config = copy.deepcopy(config_dict)
        return new_instance
    def update(self, config, in_place=False):
        new_config = deep_update(self._config, config._config)
        if in_place:
            self._config = new_config
            return self
        return self.from_dict(new_config)
    def copy(self):
        return self.from_dict(copy.deepcopy(self._config))
    def get_subconfig(self, key): pass
    def get(self, key, default=None):
        keys = key.split('.')
        subconfig = self._config
        for subkey in keys[:-1]:
            subconfig = subconfig.get(subkey)
            if type(subconfig) is not dict:
                return default
        return subconfig.get(keys[-1], default)
    def set(self, key, value):
        keys = key.split('.')
        subconfig = self._config
        for subkey in keys[:-1]:
            if subkey in subconfig:
                subconfig = subconfig[subkey]
                if type(subconfig) is not dict:
                    logger.debug(
                        'Attempting to set nested key with an existing non-dict parent'
                    )
                    return False
                continue
            subdict = {}
            subconfig[subkey] = subdict
            subconfig = subdict
        subconfig.update({ keys[-1]: value })
        return True
    def generate_hash(self, exclude_keys=None):
        inst_copy = self.copy()
        if exclude_keys is not None:
            for key in exclude_keys:
                inst_copy.set(key, None)
        items = inst_copy._config.items()
        # create hash from config options
        config_str = str(sorted(items))
        return hashlib.md5(config_str.encode()).hexdigest()
--- a/symconf/runner.py
+++ b/symconf/runner.py
@ -0,0 +1,64 @@
 '''
 Handle job/script execution
 '''
 import stat
 import subprocess
 from pathlib import Path
 from colorama import Fore, Back, Style
 from symconf.util import printc, color_text
 class Runner:
    def run_script(
        self,
        script: str | Path,
    ):
        script_path = Path(script)
        if script_path.stat().st_mode & stat.S_IXUSR == 0:
            print(
                color_text("│", Fore.BLUE),
                color_text(
                    f'   > script "{script_path.name}" missing execute permissions, skipping',
                    Fore.RED + Style.DIM
                )
            )
            return
        print(
            color_text("│", Fore.BLUE),
            color_text(
                f' > running script "{script_path.name}"',
                Fore.BLUE
            )
        )
        output = subprocess.check_output(str(script_path), shell=True)
        if output:
            fmt_output = output.decode().strip().replace(
                '\n',
                f'\n{Fore.BLUE}{Style.NORMAL}│{Style.DIM}    '
            )
            print(
                color_text("│", Fore.BLUE),
                color_text(
                    f'   captured script output "{fmt_output}"',
                    Fore.BLUE + Style.DIM
                )
            )
        return output
    def run_many(
        self,
        script_list: list[str | Path],
    ):
        outputs = []
        for script in script_list:
            output = self.run_script(script)
            outputs.append(output)
        return outputs
--- a/symconf/template.py
+++ b/symconf/template.py
@ -0,0 +1,109 @@
 '''
 Support for basic config templates
 '''
 import re
 import tomllib
 from pathlib import Path
 from symconf import util
 from symconf.reader import DictReader
 class Template:
    def __init__(
        self,
        template_str  : str,
        key_pattern   : str = r'f{{(\S+?)}}',
        exe_pattern   : str = r'x{{((?:(?!x{{).)*)}}',
    ):
        self.template_str = template_str
        self.key_pattern  = key_pattern
        self.exe_pattern  = exe_pattern
    def fill(
        self,
        template_dict : dict,
    ) -> str:
        dr = DictReader.from_dict(template_dict)
        exe_filled = re.sub(
            self.exe_pattern,
            lambda m: self._exe_fill(m, dr),
            self.template_str
        )
        key_filled = re.sub(
            self.key_pattern,
            lambda m: self._key_fill(m, dr),
            exe_filled
        )
        return key_filled
    def _key_fill(
        self,
        match,
        dict_reader: DictReader,
    ) -> str:
        key = match.group(1)
        return str(dict_reader.get(key))
    def _exe_fill(
        self,
        match,
        dict_reader: DictReader,
    ) -> str:
        key_fill = re.sub(
            self.key_pattern,
            lambda m: f'"{self._key_fill(m, dict_reader)}"',
            match.group(1)
        )
        return str(eval(key_fill))
 class FileTemplate(Template):
    def __init__(
        self,
        path:        Path,
        key_pattern: str = r'f{{(\S+?)}}',
        exe_pattern   : str = r'x{{((?:(?!x{{).)*)}}',
    ):
        super().__init__(
            path.open('r').read(),
            key_pattern=key_pattern,
            exe_pattern=exe_pattern,
        )
 class TOMLTemplate(FileTemplate):
    def __init__(
        self,
        toml_path:   Path,
        key_pattern: str = r'f{{(\S+?)}}',
        exe_pattern   : str = r'x{{((?:(?!x{{).)*)}}',
    ):
        super().__init__(
            toml_path,
            key_pattern=key_pattern,
            exe_pattern=exe_pattern,
        )
    def fill(
        self,
        template_dict : dict,
    ) -> str:
        filled_template = super().fill(template_dict)
        toml_dict = tomllib.loads(filled_template)
        return toml_dict
    @staticmethod
    def stack_toml(
        path_list: list[Path]
    ) -> dict:
        stacked_dict = {}
        for toml_path in path_list:
            updated_map = tomllib.load(toml_path.open('rb'))
            stacked_dict = util.deep_update(stacked_dict, updated_map)
        return stacked_dict
--- a/symconf/util.py
+++ b/symconf/util.py
@ -0,0 +1,80 @@
 import re
 import argparse
 from pathlib import Path
 from xdg import BaseDirectory
 from colorama import Fore, Back, Style
 from colorama.ansi import AnsiFore, AnsiBack, AnsiStyle
 def color_text(text, *colorama_args): 
    '''
    Colorama text helper function
    Note: we attempt to preserve expected nested behavior by only resetting the groups
    (Fore, Back, Style) affected the styles passed in. This works when an outer call is
    changing styles in one group, and an inner call is changing styles in another, but
    *not* when affected groups overlap.
    For example, if an outer call is setting the foreground color (e.g., ``Fore.GREEN``),
    nested calls on the text being passed into the function can modify and reset the
    background or style with affecting the foreground. The primary use case here is
    styling a group of text a single color, but applying ``BRIGHT`` or ``DIM`` styles only
    to some text elements within. If we didn't reset by group, the outer coloration
    request will be "canceled out" as soon as the first inner call is made (since the
    unconditional behavior just employs ``Style.RESET_ALL``).
    '''
    # reverse map colorama Ansi codes
    resets = []
    for carg in colorama_args:
        match = re.match(r'.*\[(\d+)m', carg)
        if match:
            intv = int(match.group(1))
            if (intv >= 30 and intv <= 39) or (intv >= 90 and intv <= 97):
                resets.append(Fore.RESET)
            elif (intv >= 40 and intv <= 49) or (intv >= 100 and intv <= 107):
                resets.append(Back.RESET)
            elif (intv >= 0 and intv <= 2) or intv == 22:
                resets.append(Style.NORMAL)
    return f"{''.join(colorama_args)}{text}{''.join(resets)}"
 def printc(text, *colorama_args):
    print(color_text(text, *colorama_args))
 def absolute_path(path: str | Path) -> Path:
    return Path(path).expanduser().absolute()
 def xdg_config_path():
    return Path(BaseDirectory.save_config_path('symconf'))
 def to_tilde_path(path: Path) -> Path:
    '''
    Abbreviate an absolute path by replacing HOME with "~", if applicable.
    '''
    try:
        return Path(f"~/{path.relative_to(Path.home())}")
    except ValueError:
        return path
 def deep_update(mapping: dict, *updating_mappings: dict) -> dict:
    '''Code adapted from pydantic'''
    updated_mapping = mapping.copy()
    for updating_mapping in updating_mappings:
        for k, v in updating_mapping.items():
            if k in updated_mapping and isinstance(updated_mapping[k], dict) and isinstance(v, dict):
                updated_mapping[k] = deep_update(updated_mapping[k], v)
            else:
                updated_mapping[k] = v
    return updated_mapping
 class KVPair(argparse.Action):
    def __call__(self, parser, namespace, values, option_string=None):
        kv_dict = getattr(namespace, self.dest, {})
        if kv_dict is None:
            kv_dict = {}
        for value in values:
            key, val = value.split('=', 1)
            kv_dict[key] = val
        setattr(namespace, self.dest, kv_dict)
--- a/tests/test-config-dir/apps/kitty/user/any-light.conf.ini
+++ b/tests/test-config-dir/apps/kitty/user/any-light.conf.ini
--- a/tests/test-config-dir/app_registry.toml
+++ b/tests/test-config-dir/app_registry.toml
@ -0,0 +1,2 @@
 [app.test]
 config_dir = 'sym_tgt/test'
--- a/tests/test-config-dir/apps/gnome/call/any-dark.sh
+++ b/tests/test-config-dir/apps/gnome/call/any-dark.sh
@ -1 +0,0 @@
 gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark'
--- a/tests/test-config-dir/apps/gnome/call/any-light.sh
+++ b/tests/test-config-dir/apps/gnome/call/any-light.sh
@ -1 +0,0 @@
 gsettings set org.gnome.desktop.interface color-scheme 'prefer-light'
--- a/tests/test-config-dir/apps/kitty/call/any-any.sh
+++ b/tests/test-config-dir/apps/kitty/call/any-any.sh
@ -1 +0,0 @@
 echo "> Testing script"
--- a/tests/test-config-dir/apps/test/call/none-light.sh
+++ b/tests/test-config-dir/apps/test/call/none-light.sh
@ -0,0 +1 @@
 echo "none-light ran"
--- a/tests/test-config-dir/apps/test/call/none-none.sh
+++ b/tests/test-config-dir/apps/test/call/none-none.sh
@ -0,0 +1 @@
 echo "none-none ran"
--- a/tests/test-config-dir/apps/test/call/test-none.sh
+++ b/tests/test-config-dir/apps/test/call/test-none.sh
@ -0,0 +1 @@
 echo "> test-none ran"
--- a/tests/test-config-dir/apps/kitty/user/spec-dark.conf
+++ b/tests/test-config-dir/apps/kitty/user/spec-dark.conf
--- a/tests/test-config-dir/apps/kitty/user/test-light.conf.aba
+++ b/tests/test-config-dir/apps/kitty/user/test-light.conf.aba
--- a/tests/test-config-dir/apps/test/user/test-dark.bbb
+++ b/tests/test-config-dir/apps/test/user/test-dark.bbb
--- a/tests/test-config-dir/apps/test/user/test-light.ccc
+++ b/tests/test-config-dir/apps/test/user/test-light.ccc
--- a/tests/test-config-dir/apps/test/user/test-none.aaa
+++ b/tests/test-config-dir/apps/test/user/test-none.aaa
--- a/tests/test-config-dir/groups/test/none.toml
+++ b/tests/test-config-dir/groups/test/none.toml
@ -0,0 +1 @@
 base = "aaa"
--- a/tests/test-config-dir/groups/test/test.toml
+++ b/tests/test-config-dir/groups/test/test.toml
@ -0,0 +1 @@
 concrete = "zzz"
--- a/tests/test-config-dir/sym_tgt/aaa
+++ b/tests/test-config-dir/sym_tgt/aaa
@ -0,0 +1 @@
 /home/smgr/Documents/projects/olog/symconf/tests/test-config-dir/apps/test/user/none-none.aaa
--- a/tests/test-config-dir/sym_tgt/bbb
+++ b/tests/test-config-dir/sym_tgt/bbb
@ -0,0 +1 @@
 /home/smgr/Documents/projects/olog/symconf/tests/test-config-dir/apps/test/user/test-dark.bbb
--- a/tests/test-config-dir/sym_tgt/ccc
+++ b/tests/test-config-dir/sym_tgt/ccc
@ -0,0 +1 @@
 /home/smgr/Documents/projects/olog/symconf/tests/test-config-dir/apps/test/user/test-light.ccc
--- a/tests/test-config-dir/sym_tgt/ddd
+++ b/tests/test-config-dir/sym_tgt/ddd
@ -0,0 +1 @@
 /home/smgr/Documents/projects/olog/symconf/tests/test-config-dir/apps/test/generated/test-none.ddd
--- a/tests/test_imports.py
+++ b/tests/test_imports.py
@ -1,5 +1,10 @@
 def test_imports():
-    from autoconf import ConfigManager
+    from symconf.runner import Runner
    from symconf.reader import DictReader
    from symconf.config import ConfigManager
    from symconf.matching import Matcher, FilePart
    from symconf.template import Template, FileTemplate, TOMLTemplate
-    from autoconf import config
+    from symconf import config
-    from autoconf import theme
+    from symconf import reader
    from symconf import util
--- a/tests/test_matching.py
+++ b/tests/test_matching.py
@ -0,0 +1,120 @@
 from pathlib import Path
 from symconf import ConfigManager
 config_dir = Path(
    __file__, '..', 'test-config-dir/'
 ).resolve()
 cm = ConfigManager(config_dir)
 def test_matching_configs_exact():
    '''
    Test matching exact style and scheme. Given strict mode not set (allowing relaxation
    to "none"), the order of matching should be
    1. (none, none)    :: none-none.aaa
    2. (none, scheme)  :: none-light.aaa
    3. (style, none)   :: test-none.aaa
    4. (style, scheme) :: test-light.ccc
    Yielding "test-light.aaa", "test-light.ccc" (unique only on config pathname).
    '''
    any_light = cm.get_matching_configs(
        'test', 
        style='test',
        scheme='light',
    )
    print(any_light)
    assert len(any_light) == 2
    assert any_light['aaa'].pathname == 'test-none.aaa'
    assert any_light['ccc'].pathname == 'test-light.ccc'
 def test_matching_configs_any_style():
    '''
    Test matching "any" style and exact scheme. Given strict mode not set (allowing
    relaxation to "none"), the order of matching should be
    1. (style, none)   :: none-none.aaa, test-none.aaa
    2. (none, none)    :: none-none.aaa
    3. (style, scheme) :: test-dark.bbb
    4. (none, scheme)  :: (nothing)
    Yielding "none-none.aaa" (should always overwrite "test-none.aaa" due to "any"'s
    preference for non-specific matches, i.e., "none"s), "test-none.ddd", "test-dark.bbb"
    (unique only on config pathname).
    '''
    any_dark = cm.get_matching_configs(
        'test', 
        style='any',
        scheme='dark',
    )
    assert len(any_dark) == 2
    assert any_dark['aaa'].pathname == 'none-none.aaa'
    assert any_dark['bbb'].pathname == 'test-dark.bbb'
 def test_matching_configs_any_scheme():
    '''
    Test matching exact style and "any" scheme. Given strict mode not set (allowing
    relaxation to "none"), the order of matching should be
    1. (none, scheme)  :: none-light.aaa & none-none.aaa
    2. (none, none)    :: none-none.aaa
    3. (style, scheme) :: test-dark.bbb & test-light.ccc & test-none.aaa
    4. (style, none)   :: test-none.aaa
    Yielding "test-none.aaa", "test-light.ccc", "test-dark.bbb"
    '''
    test_any = cm.get_matching_configs(
        'test', 
        style='test',
        scheme='any',
    )
    assert len(test_any) == 3
    assert test_any['aaa'].pathname == 'test-none.aaa'
    assert test_any['bbb'].pathname == 'test-dark.bbb'
    assert test_any['ccc'].pathname == 'test-light.ccc'
 def test_matching_scripts():
    '''
    Test matching exact style and scheme. Given strict mode not set (allowing relaxation
    to "none"), the order of matching should be
    1. (none, none)    :: none-none.sh
    2. (none, scheme)  :: none-light.sh
    3. (style, none)   :: test-none.sh
    4. (style, scheme) :: (nothing)
    Yielding (ordered by dec specificity) "test-none.sh" as primary match, then relaxation
    match "none-none.sh".
    '''
    test_any = cm.get_matching_scripts(
        'test', 
        style='test',
        scheme='any',
    )
    assert len(test_any) == 2
    assert list(map(lambda p:p.pathname, test_any)) == ['test-none.sh', 'none-none.sh']
    any_light = cm.get_matching_scripts(
        'test', 
        style='any',
        scheme='light',
    )
    assert len(any_light) == 2
    assert list(map(lambda p:p.pathname, any_light)) == ['none-light.sh', 'none-none.sh']
    any_dark = cm.get_matching_scripts(
        'test', 
        style='any',
        scheme='dark',
    )
    assert len(any_dark) == 2
    assert list(map(lambda p:p.pathname, any_dark)) == ['test-none.sh', 'none-none.sh']
--- a/tests/test_template.py
+++ b/tests/test_template.py
@ -0,0 +1,31 @@
 from pathlib import Path
 from symconf import Template, TOMLTemplate
 def test_template_fill():
    # test simple replacment
    assert Template('f{{a}} - f{{b}}').fill({
        'a': 1,
        'b': 2,
    }) == '1 - 2'
    # test nested brackets (using default pattern)
    assert Template('{{ f{{a}} - f{{b}} }}').fill({
        'a': 1,
        'b': 2,
    }) == '{{ 1 - 2 }}'
    # test tight nested brackets (requires greedy quantifier)
    assert Template('{{f{{a}} - f{{b}}}}').fill({
        'a': 1,
        'b': 2,
    }) == '{{1 - 2}}'
 def test_toml_template_fill():
    test_group_dir = Path(
        __file__, '..', 'test-config-dir/groups/test/'
    ).resolve()
    stacked_dict = TOMLTemplate.stack_toml(test_group_dir.iterdir())
    assert stacked_dict == {'base':'aaa','concrete':'zzz'}
Author	SHA1	Message	Date
Sam G.	96fba06709	fix bug in template exec pattern	2024-08-18 14:14:51 -07:00
Sam G.	2553bc14af	add py execution support to templates, loosen generate matches	2024-08-18 11:56:28 -07:00
Sam G.	017f1c5b1c	update README links, minor logging fix	2024-08-12 01:52:28 -07:00
Sam G.	433af79028	add template generation functionality, version mapping	2024-08-12 00:23:39 -07:00
Sam G.	b565d99882	fix CLI arg clash	2024-08-11 16:01:18 -07:00
Sam G.	c0d94b2de7	fix README tag issue	2024-08-11 05:18:47 -07:00
Sam G.	4ab6c4f100	modify argument names, update README with examples and demo	2024-08-11 04:13:39 -07:00
Sam G.	e2f1fd30b6	minor README update	2024-08-11 01:19:13 -07:00
Sam G.	bf311d57a5	large refactor (break up ConfigManager), add more tests	2024-08-10 23:48:35 -07:00
Sam G.	cb1dd52833	add install/update subcommands, add key-val spec for templates	2024-07-12 03:01:13 -07:00
Sam G.	8a78da1a28	fix minor script match bug	2024-07-09 15:36:58 -07:00
Sam G.	ec5893581e	fix small config-map bug	2024-07-09 15:34:19 -07:00
Sam G.	8afdadc263	fix bug when group dir doesn't exist	2024-07-09 14:52:42 -07:00
Sam G.	5bb280b1da	add binary target in pyproject	2024-07-09 12:18:16 -07:00
Sam G.	533c533034	add support for palette variants, minor bug fixes	2024-07-07 16:30:07 -07:00
Sam G.	3120638ef3	add template generation, generalize search heuristics	2024-07-07 04:21:51 -07:00
Sam G.	2f78fa0527	clean up for refined release	2024-07-05 04:15:06 -07:00
Sam G.	b72de8e28f	improve output formatting	2024-07-05 04:11:54 -07:00
Sam G.	fd32cfd5ba	overhaul ConfigManager, add basic tests, add basic docs	2024-07-05 02:06:05 -07:00
		`@ -1 +0,0 @@`
			`gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark'`
		`@ -0,0 +1 @@`
							`/home/smgr/Documents/projects/olog/symconf/tests/test-config-dir/apps/test/user/none-none.aaa`