Files
carbon-lang/utils/textmate/README.md
T
Chandler Carruth fccb349af4 Improve the TextMate grammar scopes and precision (again) (#7914)
This is a re-do of #7888

Outside a call, the grammar scoped a name as a type or a variable by its
capitalization. A theme could not distinguish a type from a value with
the same spelling, or a parameter, a member, or an implemented interface
from any other name. Pointer member access `->` was scoped as a result
arrow, which scoped `Lookup` in `regions->Lookup(x)` as a type.

`entity.name.type` now applies only in a type position (after `:`, `->`,
`as`, `adapt`, or `require`, or in an `impl`) and to the name a nominal
declaration declares. A qualifier, in a declared name like `fn N.Base(T:
type).F()` or in a type, is `entity.name.scope-resolution` nested in
`entity.name.type`. As in the parser, a name is a qualifier when its
parameter lists are followed by `.`. Parameters, `let` bindings, choice
alternatives, members, implemented interfaces, primitive types,
`import`, and the strings naming a builtin or a library have their own
scopes, and brackets use the C++ grammar's scopes. A `->` written
directly after its operand is member access; no result arrow in the
repository is written that way.

The sample palette renders each scope that depends on context
differently, and `tmlanguage.py` now supports nested captures.

In 17 of the 19 themes measured, the VS Code built-ins plus One Dark
Pro, Night Owl, Tokyo Night, and Nord, 13% to 27% of the characters in
hand-written Carbon change color or style. A theme loses a color where
`.` is now punctuation, where word operators like `as` are no longer
control-flow keywords, or where a name outside a type position is no
longer a type.

Assisted-by: Claude Code
2026-10-06 23:21:43 +00:00

60 lines
2.6 KiB
Markdown

# Textmate Language Definition
<!--
Part of the Carbon Language project, under the Apache License v2.0 with LLVM
Exceptions. See /LICENSE for license information.
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
-->
This directory contains a [TextMate](https://macromates.com/) bundle which can
be used in various editors such as TextMate, Atom, or the IntelliJ family for
syntax highlighting of Carbon source files.
If you are using TextMate, see the documentation on
[how to install TextMate bundles](https://macromates.com/manual/en/bundles#getting_more_bundles).
Clone the repository with Git and symlink/copy the `utils/textmate` directory to
any of the paths TextMate will search through (you can find these paths in the
TextMate documentation above).
## IntelliJ
If you are using IntelliJ or a IntelliJ Platform product, you can find
documentation on
[how to install TextMate bundles in IntelliJ](https://www.jetbrains.com/help/idea/textmate.html#import-textmate-bundles).
Clone the repository with Git and open the `utils/textmate` directory inside the
IntelliJ TextMate Bundle window.
## Atom
If you are using Atom, you can convert the bundle to an Atom-compatible one. See
[the Atom documentation on how to do that.](https://flight-manual.atom.io/hacking-atom/sections/converting-from-textmate/)
## Other
For other editors that support TextMate bundles you can consult your editors
documentation to see how to use the bundle.
## Samples
`Samples/` holds Carbon sources that exercise the grammar, each with an SVG
rendering of the scopes this bundle gives it. Some deliberately contain invalid
code, to show that highlighting stays sensible while something is being typed.
The renderings are generated, not screenshotted, so they always reflect the
grammar in this repository. Regenerate them in the same commit as any change to
the grammar, so a reviewer can see what the change does to real code:
```shell
utils/textmate/render_sample.py utils/textmate/Samples/*.carbon
```
The colors are a palette built for this grammar rather than an editor's theme.
Each family of related scopes gets one color, and bold, italic, and underline
distinguish the scopes within a family. Every scope the grammar picks from
context renders differently, so a change to what the grammar scopes is visible
in the image. Scopes that follow from the spelling alone, such as a bracket's
shape, can share a rendering, since the text already shows them. Unscoped text
is dimmer than any scope's color, so text the grammar misses stands out. A scope
with no entry of its own takes its family's color and style, so give a new
context-dependent scope an entry of its own.