Skip to content

talon

This directory provides a suite of tools, contexts, and actions designed to assist in writing Talon files (.talon and .talon-list) and Talon-specific Python configuration scripts. It offers dynamic autocompletion, context insertion helpers, and unified syntax generation for both file formats.

Core Architecture and Dynamic Lists

The backbone of this directory is talon.py. It registers Talon modules, contexts, and lists, and implements a dynamic link between the Talon registry and your voice engine.

Dynamic Registry Synchronization

When Talon starts or its configuration updates, talon.py hooks into the global Talon registry (registry.decls). The on_update_decls function iterates over several key declaration categories:

  • Actions
  • Lists
  • Captures
  • Tags
  • Apps
  • Settings
  • Scopes
  • Modes

It extracts their names and converts them into spoken forms using actions.user.create_spoken_forms_from_list. These are then exposed as active Talon lists (such as user.talon_actions or user.talon_tags), making your entire configuration vocally searchable and scriptable on-the-fly.

The List Population Guard (user.talon_populate_lists)

Because generating spoken forms for thousands of system actions and lists can be CPU-intensive, talon.py restricts these dynamic lists to the context tag user.talon_populate_lists:

ctx_talon_lists.matches = r"""
tag: user.talon_populate_lists
"""
  • Dragon users: This tag should not be enabled, as it can make the engine unstable or unusable.
  • Conformer users: Enabling this tag may cause noticeable latency depending on CPU performance.

To activate these lists, you must uncomment the tag declaration inside talon.talon.

Shared Commands and Syntax Translation

A key feature of this module is its ability to use the same voice commands when editing standard .talon files and Talon-specific .py files, outputting the correct syntax for each format automatically.

Activation

  • Talon files: Actively targeted when the active editor language is talon.
  • Python files: Enabled via talon_python_activator.talon, which watches for Python files and applies the user.talon_python tag. This allows developers working on non-Talon Python codebases to prevent these commands from polluting their environment.

Command Translation

The file talon_common.talon contains commands for setting tags, declaring lists or captures, asserting settings, and calling actions. It executes polymorphic actions defined in talon.py that inspect the active context to format the output.

For example, when inserting a tag setting:

  • In .talon files, the action talon_code_enable_tag inserts: tag(): user.some_tag
  • In Python files, the action inserts: ctx.tags = ["user.some_tag"]

Similarly, settings declarations are translated:

  • In .talon files: some_setting =
  • In Python files: ctx.settings["some_setting"] =

Context and List Templates

Context Requirements

Writing context matches (header block constraints) is simplified by talon_context.talon. It provides rapid triggers for setting up platform and application requirements:

  • "win require" inserts os: windows\n
  • "mac require" inserts os: mac\n
  • "linux require" inserts os: linux\n
  • "application require <app>" inserts app: <app> matching against defined system application identifiers.

List Formatting

When editing .talon-list files, talon-list.talon assists with declaring standard lists, allowing you to insert the matching template by calling "list require" or specifying a predefined list from the dynamic registry.

Core Common Functions

To avoid relying entirely on heavy dynamic registries, talon_code_common_function.talon-list pre-populates a minimal, lightweight subset of standard actions used across almost all Talon files:

  • insert
  • key
  • print
  • repeat