Use described functions for operators (#1964)

The git dif on this was not pretty. I needed to use
app.register("ready", on_ready) to define operators to allow working
with an action.
The lua actions could probably be better described.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Nicholas Riley <[email protected]>

Author: 3 people

core/described_functions.py

@@ -0,0 +1,21 @@
+# This file provides support for defining functions that have an associated description
+# Talon's version of Python does not allow getting the code of a function through reflection, so we are instead allowing associating doc strings with lambdas and functions as a way to apply descriptions to the community help system
+
+
+from typing import Callable
+
+from talon import actions
+
+
+def create_described_function(function: Callable, description: str) -> Callable:
+    """Creates a function with an associated doc string. Primarily intended to be used with lambdas"""
+    function.__doc__ = description
+    return function
+
+
+def create_described_insert_between(before: str, after: str) -> Callable:
+    """Creates a described function for calling actions.user.insert_between"""
+    return create_described_function(
+        lambda: actions.user.insert_between(before, after),
+        f"wraps the cursor with {before} and {after}",
+    )

core/help/help.py

@@ -121,8 +121,11 @@ def update_operators_text():
                     # If the operator is implemented as text insertion,
                     # display the operator text
                     operator = operators.get(operator_text)
-                    if type(operator) == str:
+                    if isinstance(operator, str):
                         text = ": " + operator
+                    # If a documentation string is available, use that
+                    elif doc_string := getattr(operator, "__doc__", None):
+                        text = ": " + doc_string
                     # Otherwise display the operator name from list
                     else:
                         has_operator_without_text_implementation = True

lang/c/c.py

@@ -1,5 +1,6 @@
 from talon import Context, Module, actions, settings
 
+from ...core.described_functions import create_described_insert_between
 from ..tags.operators import Operators
 
 mod = Module()
@@ -140,7 +141,7 @@ def c_variable(m) -> str:
 
 
 operators = Operators(
-    SUBSCRIPT=lambda: actions.user.insert_between("[", "]"),
+    SUBSCRIPT=create_described_insert_between("[", "]"),
     ASSIGNMENT=" = ",
     ASSIGNMENT_ADDITION=" += ",
     ASSIGNMENT_SUBTRACTION=" -= ",

lang/csharp/csharp.py

@@ -1,5 +1,6 @@
 from talon import Context, actions, settings
 
+from ...core.described_functions import create_described_insert_between
 from ..tags.operators import Operators
 
 ctx = Context()
@@ -9,7 +10,7 @@
 
 operators = Operators(
     # code_operators_array
-    SUBSCRIPT=lambda: actions.user.insert_between("[", "]"),
+    SUBSCRIPT=create_described_insert_between("[", "]"),
     # code_operators_assignment
     ASSIGNMENT=" = ",
     ASSIGNMENT_ADDITION=" += ",

lang/go/go.py

@@ -1,5 +1,6 @@
 from talon import Context, Module, actions, settings
 
+from ...core.described_functions import create_described_insert_between
 from ..tags.operators import Operators
 
 ctx = Context()
@@ -47,7 +48,7 @@
 
 operators = Operators(
     # code_operators_array
-    SUBSCRIPT=lambda: actions.user.insert_between("[", "]"),
+    SUBSCRIPT=create_described_insert_between("[", "]"),
     # code_operators_assignment
     ASSIGNMENT=" = ",
     ASSIGNMENT_ADDITION=" += ",

lang/java/java.py

@@ -1,5 +1,6 @@
 from talon import Context, Module, actions, settings
 
+from ...core.described_functions import create_described_insert_between
 from ..tags.operators import Operators
 
 ctx = Context()
@@ -91,7 +92,7 @@
 
 operators = Operators(
     # code_operators_array
-    SUBSCRIPT=lambda: actions.user.insert_between("[", "]"),
+    SUBSCRIPT=create_described_insert_between("[", "]"),
     # code_operators_assignment
     ASSIGNMENT=" = ",
     ASSIGNMENT_SUBTRACTION=" -= ",

lang/javascript/javascript.py

@@ -1,5 +1,6 @@
 from talon import Context, Module, actions, settings
 
+from ...core.described_functions import create_described_insert_between
 from ..tags.operators import Operators
 
 mod = Module()
@@ -60,7 +61,7 @@
 
 operators = Operators(
     # code_operators_array
-    SUBSCRIPT=lambda: actions.user.insert_between("[", "]"),
+    SUBSCRIPT=create_described_insert_between("[", "]"),
     # code_operators_assignment
     ASSIGNMENT=" = ",
     ASSIGNMENT_OR=" ||= ",

lang/kotlin/kotlin.py

@@ -1,5 +1,6 @@
 from talon import Context, Module, actions, settings
 
+from ...core.described_functions import create_described_insert_between
 from ..tags.operators import Operators
 
 ctx = Context()
@@ -44,7 +45,7 @@
 
 operators = Operators(
     # code_operators_array
-    SUBSCRIPT=lambda: actions.user.insert_between("[", "]"),
+    SUBSCRIPT=create_described_insert_between("[", "]"),
     # code_operators_assignment
     ASSIGNMENT=" = ",
     ASSIGNMENT_ADDITION=" += ",

lang/lua/lua.py

@@ -1,5 +1,9 @@
 from talon import Context, Module, actions, settings
 
+from ...core.described_functions import (
+    create_described_function,
+    create_described_insert_between,
+)
 from ..tags.operators import Operators
 
 mod = Module()
@@ -46,37 +50,43 @@ def lua_functions(m) -> str:
 
 # NOTE: < 5.3 assumes Lua BitOp usage
 #       > 5.2 assumes native bitwise operators
+# ALSO NOTE: The documentation strings for these functions are used by help operators
 # TODO: Possibly add settings to define which library to use, as 5.2
 # includes bit32. Neovim uses luajit, which uses Lua BitOp
 def code_operator_bitwise_and():
+    "Insert & or library call based on user.lua_version"
     if settings.get("user.lua_version") > 5.2:
         actions.insert(" & ")
     else:
         actions.insert(" bit.band() ")
 
 
 def code_operator_bitwise_or():
+    "Insert | or library call based on user.lua_version"
     if settings.get("user.lua_version") > 5.2:
         actions.insert(" | ")
     else:
         actions.insert(" bit.bor() ")
 
 
 def code_operator_bitwise_exclusive_or():
+    "Insert ~ or library call based on user.lua_version"
     if settings.get("user.lua_version") > 5.2:
         actions.insert(" ~ ")
     else:
         actions.insert(" bit.xor() ")
 
 
 def code_operator_bitwise_left_shift():
+    "Insert << or library call based on user.lua_version"
     if settings.get("user.lua_version") > 5.2:
         actions.insert(" << ")
     else:
         actions.insert(" bit.lshift() ")
 
 
 def code_operator_bitwise_right_shift():
+    "Insert >> or library call based on user.lua_version"
     if settings.get("user.lua_version") > 5.2:
         actions.insert(" >> ")
     else:
@@ -85,7 +95,7 @@ def code_operator_bitwise_right_shift():
 
 operators = Operators(
     # code_operators_array
-    SUBSCRIPT=lambda: actions.user.insert_between("[", "]"),
+    SUBSCRIPT=create_described_insert_between("[", "]"),
     # code_operators_assignment
     ASSIGNMENT=" = ",
     # code_operators_bitwise

lang/python/python.py

@@ -2,6 +2,7 @@
 
 from talon import Context, Module, actions, settings
 
+from ...core.described_functions import create_described_insert_between
 from ..tags.operators import Operators
 
 mod = Module()
@@ -123,7 +124,7 @@
 
 operators = Operators(
     # code_operators_array
-    SUBSCRIPT=lambda: actions.user.insert_between("[", "]"),
+    SUBSCRIPT=create_described_insert_between("[", "]"),
     # code_operators_assignment
     ASSIGNMENT=" = ",
     ASSIGNMENT_SUBTRACTION=" -= ",
@@ -145,7 +146,7 @@
     BITWISE_LEFT_SHIFT=" << ",
     BITWISE_RIGHT_SHIFT=" >> ",
     # code_operators_lambda
-    LAMBDA=lambda: actions.user.insert_between("lambda ", ": "),
+    LAMBDA=create_described_insert_between("lambda ", ": "),
     # code_operators_math
     MATH_SUBTRACT=" - ",
     MATH_ADD=" + ",