snippets

The community/core/snippets directory contains the code for handling code snippets in Talon. It includes the logic for parsing, inserting, and managing snippets.

The snippets subdirectory contains a collection of .snippet files, each defining one or more code snippets. The README.md file provides a detailed explanation of the custom .snippet file format, which allows for multiple snippets per file, context-specific snippets, and variable tab stops within snippets. The snippets are language-aware, meaning that the code inserted can vary based on the selected language when using the snippet. Most of the snippets have multiple language versions included in the same file. Some of the more interesting snippets include:

tryStatement.snippet: Inserts a try block for JavaScript, Java, and Python.
global.snippet: Inserts a code block. It uses markdown code fence.
constructorDeclaration.snippet: Inserts a constructor declaration for JavaScript, Java, and Python.
commentBlock.snippet: Inserts a multi-line comment block for C, Javascript, Java, Python, and HTML.
typescript.snippet: Contains a snippet for a Typescript interface declaration.
javascript.snippet: Contains multiple JavaScript specific snippets.
lua.snippet: Contains Lua specific snippets.
python.snippet: Contains multiple Python specific snippets.
html.snippet: Contains multiple HTML specific snippets.
talon.snippet: Contains a Talon specific snippet for a voice command declaration.
markdown.snippet: Contains a snippet for inserting a markdown link.

The other files in the directory provide the functionality to use the snippets.

snippets_insert_raw_text.py contains the logic for inserting a snippet as raw text without editor support. It parses the snippet body to identify tab stops and variables that can be populated or used for cursor placement.
snippets.py contains the core logic for managing and using snippets. It defines Talon lists of snippets and wrapper snippets, parses snippets from .snippet files, handles context matching based on code language, and provides actions for getting and inserting snippets. This file uses the code_languages module from community/core/modes to determine the active language. This file also watches the snippet directory for changes to update the available snippets. It groups snippets by language and sets up the appropriate Talon context for each language.
snippet_types.py defines dataclasses to represent a snippet, its variables, insertion snippets, and wrapper snippets.
snippets_insert.py defines the Talon actions for inserting snippets, including the ability to insert a snippet by name and to substitute variables within the snippet.
snippets_parser.py provides functionality for parsing the .snippet files, extracting contexts, variables, and snippet bodies. It handles the --- delimiter to separate snippet documents, - to separate context and body, and : for key value pairs. It also handles tab stops, variables, and default values. It has error handling for invalid snippets.
snippets.talon defines the Talon commands for using the snippets, including snip {user.snippet} for inserting a snippet and snip {user.snippet_with_phrase} <user.text> for inserting a snippet that utilizes a phrase.

The files work together as follows:

.snippet files are stored in the snippets subdirectory, as well as in a user-defined directory. These files contain the raw text for snippets, as well as metadata like language, phrase, and insertion scope.
snippets_parser.py parses the .snippet files and extracts the individual snippets, storing them as Snippet objects (defined in snippet_types.py).
snippets.py watches the snippets directory for file changes. It groups the parsed snippets by language and stores them in Talon lists. This allows Talon to make available language-specific snippets in code editing contexts, via the code_languages module in community/core/modes.
When a snippet is invoked by a Talon command (defined in snippets.talon), snippets_insert.py uses the snippet metadata to substitute variables and insert the snippet text using snippets_insert_raw_text.py, which will handle cursor placement in tab stops.