Configuration

clat reads its configuration from a TOML file. Two settings drive formatting: the threshold and each rule's weight. A third group of settings — protected environments — keeps clat's hands off picture and plot code such as TikZ.

Config tunes existing rules — it doesn't add new ones

Editing .clat.toml adjusts the weight of clat's built-in rules and the threshold; it can't introduce a rule that doesn't already exist. Got an idea for a rule that isn't there? See Suggesting a new rule.

Where config is read from

clat looks in this order and uses the first file it finds:

1. The path given with --config <path>
2. .clat.toml in the current working directory
3. ~/.config/clat/config.toml

If none exists, built-in defaults are used (threshold 5, each rule at its default weight).

Create a config file

clat set --init

This writes a .clat.toml in the current directory listing every rule with its default weight:

# clat configuration
# Adjust threshold and per-rule weights to taste.
#
# Categories are determined at runtime:
#   clang:  weight >= threshold AND fixable     (auto-fixed)
#   clunk:  weight >= threshold AND NOT fixable  (needs your attention)
#   splat:  0 < weight < threshold               (advisory)
#   off:    weight <= 0                          (disabled)

threshold = 5

# Contents of these environments are left untouched by every rule.
protected_environments = ["tikzpicture", "pgfpicture", "axis", "tikzcd"]
# Rule ids listed here still run inside protected environments.
unprotected_rules = []

[weights]
labels_inline         =  8  # Merge \label onto the same line as \section (fixable)
decorative_comments   =  6  # Strip decorative comment separators (fixable)
heading_spacing       =  7  # Two blank lines before headings, none after (fixable)
# ... all 21 rules listed

clat set --init refuses to overwrite an existing .clat.toml. To start over, use clat set --reset.

The threshold

The threshold is the single dial that decides how loud clat is. Each rule's weight is compared against it:

weight >= threshold  AND fixable      ->  clang  (auto-fixed)
weight >= threshold  AND NOT fixable  ->  clunk  (needs your attention)
0 < weight < threshold                ->  splat  (advisory)
weight <= 0                           ->  off    (disabled)

Lower the threshold to make more rules fire loudly; raise it so only your highest-priority rules do.

clat set --threshold 8

Fixable splats still apply; weight 0 turns rules off

A fixable rule under the threshold still rewrites your text — it is simply reported as a quiet splat instead of a clang. The threshold tunes reporting noise, not whether safe fixes happen. To stop a rule from running, set its weight to 0.

Set a rule weight

Prefer rule ids for scripts and repeatable configuration:

clat set ellipsis 9                  # set ellipsis to weight 9
clat set long_file 2                 # demote long_file to a splat
clat set math_delimiters_display 5   # enable display math delimiter conversion
clat set math_delimiters_equation 5  # convert display delimiters to equation

List numbers from clat list are also accepted for interactive use, but the .clat.toml file is always keyed by rule id:

clat set 14 9     # also accepted: current list number for ellipsis

You can also edit .clat.toml directly under [weights]:

[weights]
ellipsis  = 9
long_file = 2

Weights run 0–10. A weight of 0 disables a rule. A positive weight at or above the threshold promotes a rule to a clang (fixable) or clunk (detect-only); below the threshold it becomes a splat.

Protected environments

Picture and plot environments — TikZ, pgfplots, tikz-cd — are full of syntax that the prose-oriented rules would happily wreck: coordinates with commas, periods inside node text, 100 pt lengths, and table-like rows. clat masks these environments out before any rule runs and restores them verbatim afterwards, so nothing inside is touched (warnings inside them are suppressed too).

By default these environments are protected:

protected_environments = ["tikzpicture", "pgfpicture", "axis", "tikzcd"]

Add your own (anything matched by \begin{name} … \end{name}), or set it to [] to turn protection off entirely:

protected_environments = ["tikzpicture", "circuitikz", "forest"]

Letting a rule back in

If you do want a particular rule to run inside protected environments, list it in unprotected_rules. For example, to keep fixing abbreviation spacing even inside TikZ node text while leaving every other rule out:

unprotected_rules = ["abbreviation_spacing"]

clat list shows the active protected environments and any unprotected rules at the top of its output.

Reset to defaults

clat set --reset

Target a specific file

All set and list commands accept --config to operate on a file other than ./.clat.toml:

clat set --config ~/.config/clat/config.toml --threshold 7
clat list --config ~/.config/clat/config.toml

One-shot overrides

To change the threshold for a single run without editing any file:

clat --threshold 3 main.tex

This affects only that invocation.