From 2553bc14af81c805af752aeedf3b94153641afde Mon Sep 17 00:00:00 2001
From: "Sam G." <samgriesemer@gmail.com>
Date: Sun, 18 Aug 2024 11:56:28 -0700
Subject: [PATCH] add py execution support to templates, loosen generate
 matches

---
 README.md           | 19 +++++++--
 docs/index.md       | 16 ++++++--
 symconf/__main__.py | 30 +++++++++++++-
 symconf/config.py   | 98 +++++++++++++++++++++++++++------------------
 symconf/matching.py | 42 ++++++++++---------
 symconf/reader.py   |  3 ++
 symconf/runner.py   |  3 ++
 symconf/template.py | 61 +++++++++++++++++++++++-----
 symconf/util.py     |  2 +-
 9 files changed, 195 insertions(+), 79 deletions(-)

diff --git a/README.md b/README.md
index d592e1d..0295db3 100644
--- a/README.md
+++ b/README.md
@@ -19,8 +19,9 @@ used when populating config file templates. Specifically, in this example, invok
   are responsive to `prefers-color-scheme`)
 - **kitty**: theme template is re-generated using the specified palette, and `kitty`
   processes are sent a message to live-reload the new config file
-- **neovim**: a `vim` theme file is generated from the chosen palette, and running
-  instances of `neovim` are sent a message to re-source this theme
+- **neovim**: a `vim` theme file (along with a statusline theme) is generated from the
+  chosen palette, and running instances of `neovim` are sent a message to re-source this
+  theme (via `nvim --remote-send`)
 - **waybar**: bar styles are updated to match the mode setting
 - **sway**: the background color and window borders are dynamically set to base palette
   colors, and `swaymsg reload` is called
@@ -73,13 +74,25 @@ You can also install via `pip`, or clone and install locally.
     all registered apps.
   * `-m --mode`: preferred lightness mode/scheme, either `light`, `dark`, `any`, or
     `none`.
-  * `-s --style`: style indicate, often the name of a color palette, capturing thematic
+  * `-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
diff --git a/docs/index.md b/docs/index.md
index 68231e9..9a93d92 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,22 +3,29 @@
 {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
-:caption: Autoref
 
 _autoref/symconf.rst
 ```
 
 ```{toctree}
-:maxdepth: 3
+:maxdepth: 2
 :caption: Contents
 
 reference/configuring
@@ -28,4 +35,7 @@ reference/documentation/index
 ```
 
 ```{include} ../README.md
+:relative-docs: docs/
+:relative-images:
 ```
+
diff --git a/symconf/__main__.py b/symconf/__main__.py
index a500d3b..72fa083 100644
--- a/symconf/__main__.py
+++ b/symconf/__main__.py
@@ -50,6 +50,7 @@ def add_config_subparser(subparsers):
             apps=args.apps,
             scheme=args.mode,
             style=args.style,
+            **args.template_vars
         )
 
     parser = subparsers.add_parser(
@@ -81,6 +82,7 @@ def add_config_subparser(subparsers):
         '-T', '--template-vars',
         required = False,
         nargs='+',
+        default  = {},
         action=util.KVPair,
         help='Groups to use when populating templates, in the form group=value'
     )
@@ -90,8 +92,11 @@ def add_generate_subparser(subparsers):
     def generate_apps(args):
         cm = ConfigManager(args.config_dir)
         cm.generate_app_templates(
-            gen_dir=args.gen_dir,
+            gen_dir=args.output_dir,
             apps=args.apps,
+            scheme=args.mode,
+            style=args.style,
+            **args.template_vars
         )
 
     parser = subparsers.add_parser(
@@ -99,11 +104,24 @@ def add_generate_subparser(subparsers):
         description='Generate all template config files for specified apps'
     )
     parser.add_argument(
-        '-g', '--gen-dir',
+        '-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,
@@ -112,6 +130,14 @@ def add_generate_subparser(subparsers):
         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)
 
 
diff --git a/symconf/config.py b/symconf/config.py
index 0d21fa4..8db459c 100644
--- a/symconf/config.py
+++ b/symconf/config.py
@@ -1,19 +1,19 @@
 '''
-Get the config map for a provided app.
+Primary config management abstractions
 
 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>
-```
+.. code-block:: sh
+
+    <config_path_name> -> <config_dir>/apps/<app_name>/<subdir>/<palette>-<scheme>.<config_path_name>
 
 For example,
 
-```
-palette1-light.conf.ini -> ~/.config/symconf/apps/user/palette1-light.conf.ini
-palette2-dark.app.conf -> ~/.config/symconf/apps/generated/palette2-dark.app.conf
-```
+.. 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``
@@ -220,16 +220,16 @@ class ConfigManager:
         files just the same as we do for non-template config files. That is, we will look
         for files of the format
 
-        ```sh
-        <style>-<scheme>.toml
-        ```
+        .. code-block:: sh
+
+            <style>-<scheme>.toml
 
         The only difference is that, while ``style`` can still include arbitrary style
         variants, it *must* have the form
 
-        ```sh
-        <variant-1>-...-<variant-N>-<palette>
-        ```
+        .. 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
@@ -346,7 +346,11 @@ class ConfigManager:
 
         return template_dict, relaxed_theme_matches
 
-    def _prepare_all_templates(self) -> dict[str, dict]:
+    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():
@@ -358,30 +362,37 @@ class ConfigManager:
             palette_base.append(palette_map['none'])
 
         # then palette-scheme groups (require 2-combo logic)
-        theme_map = {}
+        theme_matches = []
         theme_group_dir = Path(self.group_dir, 'theme')
         if theme_group_dir.exists():
-            for theme_toml in theme_group_dir.iterdir():
-                fp = FilePart(theme_toml)
+            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_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)
+        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])
+            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_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}
+            theme_map[fp.path.stem] = {'theme': theme_dict}
 
         return theme_map
 
@@ -406,7 +417,7 @@ class ConfigManager:
         ``none-<scheme>`` and ``<style>-none`` are both available, in which case the latter
         will overwrite the former).
 
-        .. admonition: Edge cases
+        .. admonition:: Edge cases
 
             There are a few quirks to this matching scheme that yield potentially
             unintuitive results. As a recap:
@@ -515,9 +526,9 @@ class ConfigManager:
 
         Scripts need to be placed in
 
-        ```sh
-        <config_dir>/apps/<app_name>/call/<style>-<scheme>.sh
-        ```
+        .. 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``,
@@ -808,6 +819,9 @@ class ConfigManager:
         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())
@@ -823,7 +837,7 @@ class ConfigManager:
         print(f'> Writing templates...')
 
         gen_dir = util.absolute_path(gen_dir)
-        theme_map = self._prepare_all_templates()
+        theme_map = self._prepare_all_templates(scheme, style)
 
         for app_name in app_list:
             app_template_dir = Path(self.apps_dir, app_name, 'templates')
@@ -831,6 +845,12 @@ class ConfigManager:
                 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)
@@ -855,5 +875,5 @@ class ConfigManager:
 
                     print(
                         color_text("│", Fore.BLUE),
-                        f'> generating "{tgt_template_path.name}"'
+                        f'>  generating "{tgt_template_path.name}"'
                     )
diff --git a/symconf/matching.py b/symconf/matching.py
index e1560e2..e2bd712 100644
--- a/symconf/matching.py
+++ b/symconf/matching.py
@@ -1,9 +1,11 @@
 '''
-Top-level definitions
+Generic combinatorial name-matching subsystem
 
 Config files are expected to have names matching the following spec:
 
-<style>-<scheme>.<config_pathname>
+.. 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,
@@ -15,17 +17,17 @@ Config files are expected to have names matching the following spec:
 
 For example
 
-```sh
-soft-gruvbox-dark.kitty.conf
-```
+.. code-block:: sh
+
+    soft-gruvbox-dark.kitty.conf
 
 gets mapped to 
 
-```sh
-style    -> "soft-gruvbox"
-scheme   -> "dark"
-pathname -> "kitty.conf"
-```
+.. code-block:: sh
+
+    style    -> "soft-gruvbox"
+    scheme   -> "dark"
+    pathname -> "kitty.conf"
 '''
 from pathlib import Path
 
@@ -64,9 +66,9 @@ class Matcher:
 
         Pathnames should be of the format
 
-        ```sh
-        <style>-<scheme>.<config_pathname>
-        ```
+        .. code-block:: sh
+
+            <style>-<scheme>.<config_pathname>
 
         where ``style`` is typically itself of the form ``<variant>-<palette>``.
         '''
@@ -151,12 +153,12 @@ class Matcher:
         "consistent" with some user input (and is computed external to this method). For
         example, it could be
 
-        ```py
-        [
-            ('none', 'none')
-            ('none', 'dark')
-        ]
-        ```
+        .. 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.
@@ -166,7 +168,7 @@ class Matcher:
         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
+        .. 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
diff --git a/symconf/reader.py b/symconf/reader.py
index 9a57654..bbdb3b5 100644
--- a/symconf/reader.py
+++ b/symconf/reader.py
@@ -1,3 +1,6 @@
+'''
+Simplified management for nested dictionaries
+'''
 import copy
 import pprint
 import tomllib
diff --git a/symconf/runner.py b/symconf/runner.py
index ea6f2e0..ca04eeb 100644
--- a/symconf/runner.py
+++ b/symconf/runner.py
@@ -1,3 +1,6 @@
+'''
+Handle job/script execution
+'''
 import stat
 import subprocess
 from pathlib import Path
diff --git a/symconf/template.py b/symconf/template.py
index d5d8430..6ef9598 100644
--- a/symconf/template.py
+++ b/symconf/template.py
@@ -1,3 +1,6 @@
+'''
+Support for basic config templates
+'''
 import re
 import tomllib
 from pathlib import Path
@@ -10,10 +13,12 @@ class Template:
     def __init__(
         self,
         template_str  : str,
-        pattern       : str = r'f{{(\S+?)}}',
+        key_pattern   : str = r'f{{(\S+?)}}',
+        exe_pattern   : str = r'x{{(.*)}}',
     ):
         self.template_str = template_str
-        self.pattern = pattern
+        self.key_pattern  = key_pattern
+        self.exe_pattern  = exe_pattern
 
     def fill(
         self,
@@ -21,32 +26,66 @@ class Template:
     ) -> str:
         dr = DictReader.from_dict(template_dict)
 
-        return re.sub(
-            self.pattern,
-            lambda m: str(dr.get(m.group(1))),
+        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,
-        pattern : str = r'f{{(\S+)}}',
+        path:        Path,
+        key_pattern: str = r'f{{(\S+?)}}',
+        exe_pattern: str = r'x{{(.*)}}',
     ):
         super().__init__(
             path.open('r').read(),
-            pattern=pattern
+            key_pattern=key_pattern,
+            exe_pattern=exe_pattern,
         )
 
 class TOMLTemplate(FileTemplate):
     def __init__(
         self,
-        toml_path : Path,
-        pattern   : str = r'f{{(\S+)}}',
+        toml_path:   Path,
+        key_pattern: str = r'f{{(\S+?)}}',
+        exe_pattern: str = r'x{{(.*)}}',
     ):
         super().__init__(
             toml_path,
-            pattern=pattern
+            key_pattern=key_pattern,
+            exe_pattern=exe_pattern,
         )
 
     def fill(
diff --git a/symconf/util.py b/symconf/util.py
index 9dd1f62..bc42962 100644
--- a/symconf/util.py
+++ b/symconf/util.py
@@ -14,7 +14,7 @@ def color_text(text, *colorama_args):
     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.
+    *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