Configuration

Catnip combine des valeurs par défaut, un fichier TOML, l'environnement et les options CLI.

Fichier

Le fichier par défaut est :

~/.config/catnip/catnip.toml

XDG_CONFIG_HOME remplace ~/.config. CATNIP_CONFIG ou catnip --config FILE sélectionne un autre fichier. Le serveur LSP résout le même fichier au démarrage et en honore la section [lint] ; un changement de configuration lui demande un redémarrage.

Le dépôt fournit aussi catnip.toml.example, commenté avec toutes les clés.

Structure

Les sections suivantes définissent les clés ; catnip.toml.example les rassemble dans un même fichier.

Précédence

Une valeur plus à droite remplace les valeurs situées à sa gauche :

défaut ⇒ fichier global ⇒ override de mode ⇒ environnement ⇒ CLI

Exemple :

[optimize]
jit = false

[mode.standalone]
jit = true

CATNIP_OPTIMIZE=jit:off catnip -o jit script.cat

Le fichier active le JIT pour les scripts, l'environnement le désactive, puis -o jit le réactive.

Le niveau optimize est un seuil : 0 désactive les passes ; 1 et 2 activent les passes locales ; 3 ajoute le tier inter-blocs CFG+SSA. Le défaut est 2. Les détails des passes sont dans OPTIMIZATIONS.

Overrides par mode

Les sections [mode.standalone] et [mode.repl] remplacent les clés globales pour le mode correspondant :

[mode.standalone]
jit = false
tco = true
optimize = 2

[mode.repl]
jit = true
tco = true
optimize = 2

Le mode DSL n'est pas auto-détecté. Pour l'embedding Python, configurer les sections globales ou passer les options à l'API hôte. Cette règle évite qu'un même fichier soit interprété différemment selon le chemin d'import Python.

Exécution et affichage

La section [optimize] configure le pipeline :

La section [repl] configure l'affichage :

L'éditeur interactif /config distingue les valeurs persistées de celles qui ne valent que pour la session. Voir REPL.

Modules

[modules]
auto = ["io", "math"]
policy = "deny"
allow = ["math", "json", "io"]
deny = ["os", "subprocess"]

[modules.repl]
auto = ["io", "math"]

[modules.cli]
auto = ["io"]

[modules.dsl]
auto = []

auto charge les modules avant l'exécution. La section du mode courant remplace [modules].auto; les modules -m s'y ajoutent, après déduplication.

policy, allow et deny contrôlent les imports. La syntaxe des patterns, les policies nommées et l'ordre de résolution sont définis dans MODULE_LOADING.

Cache

Le cache de parsing et de bytecode est stocké sous $XDG_CACHE_HOME/catnip, ou ~/.cache/catnip par défaut.

enable_cache = true

[cache]
cache_max_size_mb = 100
cache_ttl_seconds = 86400

Commandes de gestion :

catnip cache stats
catnip cache prune
catnip cache prune --dry-run
catnip cache clear

prune supprime d'abord les entrées expirées, puis applique la limite de taille selon l'ordre d'utilisation récent.

Diagnostics

Les erreurs internes peuvent produire des rapports JSON sous $XDG_STATE_HOME/catnip/weird, ou ~/.local/state/catnip/weird par défaut :

[diagnostics]
log_weird_errors = true
max_weird_logs = 50

CATNIP_WEIRD_LOG=off désactive ces rapports. Une erreur d'écriture du rapport ne remplace pas l'erreur originale.

Formatter

[format]
indent_size = 4
line_length = 120
align = false

CATNIP_FORMAT_INDENT_SIZE et CATNIP_FORMAT_LINE_LENGTH surchargent le fichier. Les options de catnip format prennent ensuite priorité. Voir Formatter.

Linter

[lint]
disable = ["W401", "I200"]

--disable CODE ajoute des codes et --enable CODE les réactive. L'ensemble désactivé est :

(fichier ∪ --disable) ∖ --enable

--enable ne lance pas une analyse opt-in : --check-names et --deep restent nécessaires pour les phases correspondantes. Voir Linter.

Variables d'environnement

Une valeur qu'une variable ne sait pas lire lève, en la nommant :

CATNIP_CACHE=bogus catnip script.cat
# Error: Invalid value 'bogus' for CATNIP_CACHE: expected on/true/1/yes or off/false/0/no

Une variable définie mais vide compte comme absente, et laisse donc le fichier de configuration décider. CATNIP_EXECUTOR= ne renverse pas un executor écrit dans le fichier, CATNIP_CACHE= ne réactive pas un cache désactivé. C'est la règle que suivent déjà HOME et les bases XDG_* ; NO_COLOR l'a dans sa propre spécification.

Pour CATNIP_EXECUTOR, la casse et les espaces autour de la valeur sont ignorés : CATNIP_EXECUTOR='AST ' sélectionne l'interpréteur AST.

catnip config show --debug donne la source retenue pour chaque valeur — default, file, env ou cli —, ce qui est le moyen de vérifier qu'un réglage a bien été pris en compte, et par qui.

Inspecter et modifier

catnip config show
catnip config show --debug
catnip config get jit
catnip config set jit true
catnip config path

show --debug affiche la source de chaque valeur : default, file, env ou cli.

En REPL, /config ouvre l'éditeur interactif ; /config show, /config get, /config set et /config path restent disponibles sous forme textuelle.

Une configuration a plusieurs sources, mais une seule valeur effective. Le reste est de la généalogie.