Merge branch 'main' into centralized-please-command

.gitignore

@@ -6,3 +6,4 @@ __pycache__
 /settings
 .vscode/settings.json
 .DS_Store
+.bak

BREAKING_CHANGES.txt

@@ -1,28 +1,41 @@
-This file lists known changes to `community` that are likely to have broken existing
-functionality. The file is sorted by date with the newest entries up the top.
+This file lists known changes to `community` that are likely to have
+broken existing functionality. The file is sorted by date with the
+newest entries up the top.
 
-Be aware there may be some difference between the date in this file and when the change was
-applied given the delay between changes being submitted and the time they were reviewed
-and merged.
+Be aware there may be some difference between the date in this file
+and when the change was applied given the delay between changes being
+submitted and the time they were reviewed and merged.
 
 ---
-* 2024-07-31 Remove commands `"command mode"`, `"dictation mode"` from custom user modes. Note that if you have any custom modes where you want these commands you could add that mode to the context of `command_and_dictation_mode.talon` or copying the command to one of your custom files.
-* 2024-07-30 Deprecate `lend` and `bend` commands in favor of `go line end | tail` and `go line start | head`.
-* 2024-07-28 Removed the following user namespace actions in favor of the new action/modifier grammar.
+* 2024-09-07 If you've updated `community` since 2024-08-31, you may
+  need to replace `host:` with `hostname:` in the header of
+  `core/system_paths-<hostname>.talon-list` due to an issue with
+  automatic conversion from CSV (#1268).
+* 2024-07-31 Remove commands `"command mode"`, `"dictation mode"` from
+  custom user modes. Note that if you have any custom modes where you
+  want these commands you could add that mode to the context of
+  `command_and_dictation_mode.talon` or copying the command to one of
+  your custom files.
+* 2024-07-30 Deprecate `lend` and `bend` commands in favor of `go line
+  end | tail` and `go line start | head`.
+* 2024-07-28 Removed the following user namespace actions in favor of
+  the new action/modifier grammar.
     https://github.com/talonhub/community/blob/37a8ebde90c8120a0b52555030988d4f54e65159/core/edit/edit.talon#L3
     cut_word, copy_word, paste_word
     cut_all, copy_all, paste_all, delete_all
     copy_line, paste_line
     cut_line_start, copy_line_start, paste_line_start, delete_line_start
     cut_line_end, copy_line_end, paste_line_end, delete_line_end
-* 2024-05-30 Deprecate 'drop down <user.number_small>' in favor of overridable 'choose' helper
-* 2024-01-27 Deprecate '<user.number_string>' command without a spoken prefix like `numb`.
-See `numbers.talon` and `numbers_unprefixed.talon.` If in the future you want to still use
-unprefixed numbers, you will need to comment out the
-`tag(): user.prefixed_numbers` line in your `settings.talon` file.
-* 2023-06-06 Deprecate `go ` command for VSCode. Use 'bar marks' instead.
+* 2024-05-30 Deprecate 'drop down <user.number_small>' in favor of
+  overridable 'choose' helper
+* 2024-01-27 Deprecate '<user.number_string>' command without a spoken
+  prefix like `numb`. See `numbers.talon` and
+  `numbers_unprefixed.talon.` If in the future you want to still use
+  unprefixed numbers, you will need to comment out the
+  `tag(): user.prefixed_numbers` line in your `settings.talon` file.
+* 2023-06-06 Deprecate `go` command for VSCode. Use 'bar marks' instead.
 * 2023-02-04 Deprecate `murder` command for i3wm. Use 'win kill' instead.
-* 2022-12-11 Deprecate user.insert_with_history. Just use `user.add_phrase_to_history(text);
-insert(text)` instead. See #939.
-* 2022-10-01 Large refactoring of code base that moves many files into new locations. No
-other backwards-incompatible changes included.
+* 2022-12-11 Deprecate user.insert_with_history. Just use
+  `user.add_phrase_to_history(text); insert(text)` instead. See #939.
+* 2022-10-01 Large refactoring of code base that moves many files into
+  new locations. No other backwards-incompatible changes included.

README.md

@@ -287,6 +287,27 @@ You can customize common Talon list and CSV files with voice commands: say the w
 
 You can also add words to the vocabulary or replacements (words_to_replace) by using the commands in [edit_vocabulary.talon](core/vocabulary/edit_vocabulary.talon).
 
+## 💡 Tip: Overriding cleanly
+
+You can override Talon lists by creating a new `.talon-list` file of your own, rather than changing the existing list in the repository.
+This reduces how much manual `git merge`-ing you'll have to do in the future, when you go to merge new versions of this repository (colloquially called "upstream") with your local changes. This is because _new_ files you create will almost never conflict with upstream changes, whereas changing an existing file (especially hot spots, like commonly-customized lists) frequently do.
+Your override files can even live outside of the `community` repository (anywhere in the Talon user directory), if you prefer, further simplifying merging.
+To do so, simply create a `.talon-list` file with a more specific [context header](https://talon.wiki/Customization/talon-files#context-header) than the default. (For example, `lang: en` or `os: mac` main). Talon ensures that the most specific header (your override file) wins.
+
+For example, to override `user.modifier_key`, you could create `modifier_keys_MYNAME.talon`:
+
+```talon
+list:  user.modifier_key
+language: en
+-
+
+# My preferred modifier keys
+rose: cmd
+troll: control
+shift: shift
+alt: alt
+```
+
 ## Other Talon user file sets
 
 In addition to this repo, there are [other Talon user file sets](https://talon.wiki/talon_user_file_sets/) containing additional commands that you may want to experiment with if you're feeling adventurous 😊. Many of them are meant to be used alongside `community`, but a few of them are designed as replacements. If it's not clear which, please file an issue against the given GitHub repository for that user file set!

core/system_paths.py

@@ -1,56 +1,69 @@
 """
 This module gives us the list {user.system_paths} and the capture <user.system_path> that wraps
 the list to easily refer to system paths in talon and python files. It also creates a file
-system_paths.csv in the settings folder so they user can easily add their own custom paths.
+system_paths-<hostname>.talon-list in the core folder so the user can easily add their own
+custom paths.
 """
 
-import os
+from pathlib import Path
 
-from talon import Context, Module, actions, app
-
-from .user_settings import get_list_from_csv
+from talon import Context, Module, actions, app, registry
 
 mod = Module()
-ctx = Context()
-
 mod.list("system_paths", desc="List of system paths")
 
-user_path = os.path.expanduser("~")
-
 
-# We need to wait for ready before we can call "actions.path.talon_home()" and
-# "actions.path.talon_user()"
 def on_ready():
-    default_system_paths = {
-        "user": user_path,
-        "profile": user_path,
-        "desktop": os.path.join(user_path, "Desktop"),
-        "desk": os.path.join(user_path, "Desktop"),
-        "documents": os.path.join(user_path, "Documents"),
-        "docks": os.path.join(user_path, "Documents"),
-        "downloads": os.path.join(user_path, "Downloads"),
-        "music": os.path.join(user_path, "Music"),
-        "pictures": os.path.join(user_path, "Pictures"),
-        "videos": os.path.join(user_path, "Videos"),
-        "talon home": str(actions.path.talon_home()),
-        "talon user": str(actions.path.talon_user()),
-    }
+    # If user.system_paths defined otherwise, don't generate a file
+    if registry.lists["user.system_paths"][0]:
+        return
 
-    if app.platform == "windows":
-        one_drive_path = os.path.expanduser(os.path.join("~", "OneDrive"))
+    hostname = actions.user.talon_get_hostname()
+    system_paths = Path(__file__).with_name(f"system_paths-{hostname}.talon-list")
+    if system_paths.is_file():
+        return
 
-        # this is probably not the correct way to check for onedrive, quick and dirty
-        if os.path.isdir(os.path.expanduser(os.path.join("~", r"OneDrive\Desktop"))):
-            onedrive_paths = {
-                "desktop": os.path.join(one_drive_path, "Desktop"),
-                "documents": os.path.join(one_drive_path, "Documents"),
-                "one drive": one_drive_path,
-                "pictures": os.path.join(one_drive_path, "Pictures"),
-            }
+    home = Path.home()
+    talon_home = Path(actions.path.talon_home())
 
-            default_system_paths.update(onedrive_paths)
+    default_system_paths = {
+        "user": home,
+        "desktop": home / "Desktop",
+        "desk": home / "Desktop",
+        "documents": home / "Documents",
+        "docks": home / "Documents",
+        "downloads": home / "Downloads",
+        "music": home / "Music",
+        "pictures": home / "Pictures",
+        "videos": home / "Videos",
+        "talon home": talon_home,
+        "talon recordings": talon_home / "recordings",
+        "talon user": actions.path.talon_user(),
+    }
 
-    ctx.lists["user.system_paths"] = default_system_paths
+    if app.platform == "windows":
+        default_system_paths["profile"] = home
+        onedrive_path = home / "OneDrive"
+
+        # this is probably not the correct way to check for OneDrive, quick and dirty
+        if (onedrive_path / "Desktop").is_dir():
+            default_system_paths["desktop"] = onedrive_path / "Desktop"
+            default_system_paths["documents"] = onedrive_path / "Documents"
+            default_system_paths["one drive"] = onedrive_path
+            default_system_paths["pictures"] = onedrive_path / "Pictures"
+    else:
+        default_system_paths["home"] = home
+
+    with open(system_paths, "x") as f:
+        print("list: user.system_paths", file=f)
+        print(f"hostname: {hostname}", file=f)
+        print("-", file=f)
+        for spoken_form, path in default_system_paths.items():
+            path = str(path)
+            if not str.isprintable(path) or "'" in path or '"' in path:
+                path = repr(path)
+
+            print(f"{spoken_form}: {path}", file=f)
 
 
 @mod.capture(rule="{user.system_paths}")

migration_helpers/migration_helpers.py

@@ -62,7 +62,7 @@ class CSVData:
         lambda: os.path.join(
             "core", f"system_paths-{actions.user.talon_get_hostname()}.talon-list"
         ),
-        custom_header=(lambda: f"host: {actions.user.talon_get_hostname()}"),
+        custom_header=(lambda: f"hostname: {actions.user.talon_get_hostname()}"),
     ),
     CSVData(
         "user.search_engine",
@@ -255,7 +255,17 @@ def migrate_custom_csv(
 
 
 def on_ready():
-    actions.user.migrate_known_csv_files()
+    try:
+        actions.user.migrate_known_csv_files()
+    except KeyError:
+        # Due to a core Talon bug, the above action may not be available when a ready callback is invoked.
+        # (see https://github.com/talonhub/community/pull/1268#issuecomment-2325721706)
+        notification = (
+            "Unable to migrate CSVs to Talon lists.",
+            "Please quit and restart Talon.",
+        )
+        app.notify(*notification)
+        print(*notification)
 
 
 app.register("ready", on_ready)

plugin/mouse/mouse.py

@@ -148,6 +148,13 @@ def mouse_drag_end():
         for button in ctrl.mouse_buttons_down():
             ctrl.mouse_click(button=button, up=True)
 
+    def mouse_drag_toggle(button: int):
+        """If the button is held down, release the button, else start dragging"""
+        if button in list(ctrl.mouse_buttons_down()):
+            ctrl.mouse_click(button=button, up=True)
+        else:
+            actions.user.mouse_drag(button=button)
+
     def mouse_sleep():
         """Disables control mouse, zoom mouse, and re-enables cursor"""
         actions.tracking.control_zoom_toggle(False)
@@ -222,6 +229,13 @@ def mouse_gaze_scroll():
             actions.tracking.control_toggle(True)
             control_mouse_forced = True
 
+    def mouse_gaze_scroll_toggle():
+        """If not scrolling, start gaze scroll, else stop scrolling."""
+        if continuous_scroll_mode == "":
+            actions.user.mouse_gaze_scroll()
+        else:
+            actions.user.mouse_scroll_stop()
+
     def copy_mouse_position():
         """Copy the current mouse position coordinates"""
         position = ctrl.mouse_pos()