Talon tools

Linting and formatting tools for Talon and Cursorless.

Installation

Local dev dependency

Install the package in your project:

npm install --save-dev @cursorless/talon-tools

Run the local CLI commands with npx:

npx talon-fmt [options] [file/dir/glob ...]
npx snippet-fmt [options] [file/dir/glob ...]
npx tree-sitter-fmt [options] [file/dir/glob ...]

Global install

Install the binaries globally:

npm install --global @cursorless/talon-tools

Run the binaries directly:

talon-fmt [options] [file/dir/glob ...]
snippet-fmt [options] [file/dir/glob ...]
tree-sitter-fmt [options] [file/dir/glob ...]

CLI options

All binaries support these options:

Option	Meaning
--help	Show help
--version	Show version
--quiet	Suppress non-error output
--check	Check formatting without writing
--debug	Print debug output

Use --debug when diagnosing parser or formatter support for new syntax.

Formatting options

Formatting options are read from .editorconfig based on the file path being formatted. For stdin, the formatter resolves a synthetic file such as stdin.talon, stdin.talon-list, stdin.scm, or stdin.snippet from the current working directory and loads .editorconfig relative to that path.

Supported .editorconfig properties:

Property	Meaning	Default	talon-fmt	snippet-fmt	tree-sitter-fmt
end_of_line	Set output line endings	lf	yes	yes	yes
indent_style	Use tabs or spaces for indentation	spaces	yes	no	yes
indent_size	Set indentation width	4	yes	no	yes
max_line_length	Set preferred maximum line width	80	yes	no	no
insert_final_newline	Ensure the file ends with a newline	true	yes	yes	yes
preserve_multiline	Keep existing multi-line formatting	false	yes	no	no
column_width	Set aligned left-column width		yes	no	no

Use -- to mark the end of options. Any following arguments are treated as file, directory, or glob patterns even if they start with --.

talon-fmt -- --check

Column width comment

The column width option can be enabled on a per file basis using a fmt comment.

# fmt: columnWidth=15

foo:           "foo"
foo bar baz:   "foo bar baz"

Exit codes

Code	Information
0	Everything formatted properly
1	Something wasn't formatted properly
2	Runtime error

Pre commit

repos:
  - repo: https://github.com/cursorless-dev/talon-tools
    rev: v0.8.0
    hooks:
      - id: talon-fmt
      - id: snippet-fmt
      - id: tree-sitter-fmt

Guidelines

• Each pre-commit hook should have a matching npm binary with the same name.
• Binaries ending with -fmt are formatters by default and turn into linters/checkers with the --check argument.
• (Future) binaries ending with -check are linters by default and turn into fixers with the --fix argument.

Developer

# Try formatter without pre-commit
node dist/talonFormatter.js test.talon

# Try formatter with pre-commit
pre-commit try-repo . talon-fmt --files test.talon -v

Install the hooks locally:

# .pre-commit-config.yaml
repos:
  - repo: .
    rev: HEAD
    hooks:
      - id: talon-fmt
      - id: snippet-fmt
      - id: tree-sitter-fmt

pre-commit install
pre-commit run --all-files

Release

When creating a new release do the following:

• Update version in package.json
• Update version in README.md
• Run build: npm run build
• Add new tag eg git tag v1.2.0
• Publish lib: npm publish --access public