Finch 2.5.0: docs (EN, PL), Kate and VS Code for the new features

- cheat sheets, technicians' and engineers' guides: "\(x)", test blocks, finch fmt, finch.toml,
  the build cache, the chain of calls, threads and atomics, C++/Rust/Android, struct #defines,
  passing structs, why there is no warning for big copies
- Kate (version 4) and VS Code: code inside text, test, min/max/abs/clamp/assert/atomic_...
- finch.toml's name is used only for its entry; other files of the project keep their own name

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016GzNP6r8dg6WDxUVZy8wjL

editors/kate/finch.xml

@@ -5,7 +5,7 @@
   Install: copy to ~/.local/share/org.kde.syntax-highlighting/syntax/finch.xml
   (or run editors/kate/install.sh), then restart Kate.
 -->
-<language name="Finch" version="3" kateversion="5.0" section="Sources" extensions="*.fch"
+<language name="Finch" version="4" kateversion="5.0" section="Sources" extensions="*.fch"
           mimetype="text/x-finch" indenter="cstyle" author="The Finch authors" license="Apache-2.0">
   <highlighting>
     <list name="keywords">
@@ -71,6 +71,17 @@
       <item>new</item>
       <item>free</item>
       <item>error</item>
+      <item>min</item>
+      <item>max</item>
+      <item>abs</item>
+      <item>clamp</item>
+      <item>assert</item>
+      <item>atomic_add</item>
+      <item>atomic_sub</item>
+      <item>atomic_load</item>
+      <item>atomic_store</item>
+      <item>atomic_swap</item>
+      <item>atomic_cas</item>
     </list>
 
     <contexts>
@@ -85,6 +96,8 @@
         <DetectChar char="'" attribute="Char" context="Char"/>
 
         <WordDetect String="fn" attribute="Keyword" context="FunctionName"/>
+        <RegExpr String="\btest(?=\s*&quot;)" attribute="Keyword"/>
+        <RegExpr String="(?&lt;=\s)as(?=\s+[A-Za-z_])" attribute="Import"/>
         <WordDetect String="struct" attribute="Keyword" context="StructName"/>
         <keyword String="control" attribute="Control Flow"/>
         <keyword String="imports" attribute="Import"/>
@@ -134,16 +147,30 @@
       </context>
 
       <context name="String" attribute="String" lineEndContext="#pop">
+        <RegExpr String="\\\(" attribute="Escape" context="Interpolation"/>
         <RegExpr String="\\[ntr0\\&quot;']" attribute="Escape"/>
         <RegExpr String="\\." attribute="Error"/>
         <DetectChar char="&quot;" attribute="String" context="#pop"/>
       </context>
 
       <context name="LongString" attribute="String" lineEndContext="#stay">
+        <RegExpr String="\\\(" attribute="Escape" context="Interpolation"/>
         <RegExpr String="\\[ntr0\\&quot;']" attribute="Escape"/>
         <StringDetect String="&quot;&quot;&quot;" attribute="String" context="#pop" endRegion="LongString"/>
       </context>
 
+      <!-- "hp \(hp + 1)": code inside text, up to the ) that closes \( -->
+      <context name="Interpolation" attribute="Normal Text" lineEndContext="#stay">
+        <DetectChar char=")" attribute="Escape" context="#pop"/>
+        <DetectChar char="(" attribute="Symbol" context="InterpolationParen"/>
+        <IncludeRules context="Normal"/>
+      </context>
+      <context name="InterpolationParen" attribute="Normal Text" lineEndContext="#stay">
+        <DetectChar char=")" attribute="Symbol" context="#pop"/>
+        <DetectChar char="(" attribute="Symbol" context="InterpolationParen"/>
+        <IncludeRules context="Normal"/>
+      </context>
+
       <context name="Char" attribute="Char" lineEndContext="#pop">
         <RegExpr String="\\[ntr0\\&quot;']" attribute="Escape"/>
         <DetectChar char="'" attribute="Char" context="#pop"/>

editors/vscode/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.5.0
+
+- Highlighting for code inside text (`"hp \(hp)"`), `test "…" { }` blocks, `const`, `"""` text, `1e9`.
+- Built-ins `min`, `max`, `abs`, `clamp`, `assert` and `atomic_…` highlighted and described on hover.
+- Format Document (the language server runs `finch fmt` on the open file).
+
 ## 2.4.0
 
 - Highlighting for methods (`fn Point.move`), maps (`map[K]V`), `or`, `try`, `self` and `error(...)`.

editors/vscode/package.json

@@ -2,7 +2,7 @@
   "name": "finch-lang",
   "displayName": "Finch",
   "description": "The Finch programming language: highlighting, errors as you type, completion, hover, go to definition, and a Run button.",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "publisher": "nexoniarz",
   "license": "Apache-2.0",
   "icon": "images/icon.png",

editors/vscode/syntaxes/finch.tmLanguage.json

@@ -103,6 +103,10 @@
     },
     "statements": {
       "patterns": [
+        {
+          "name": "keyword.other.test.finch",
+          "match": "\\btest(?=\\s*\")"
+        },
         {
           "include": "#comments"
         },
@@ -147,7 +151,7 @@
           "match": "\\b(int|float|bool|char|str|ptr|map|i8|i16|i32|i64|u8|u16|u32|u64|f32|f64)\\b"
         },
         {
-          "match": "\\b(print|input|read_file|write_file|file_exists|delete_file|shell|exit|addr|new|free|error)\\s*(?=\\()",
+          "match": "\\b(print|input|read_file|write_file|file_exists|delete_file|shell|exit|addr|new|free|error|min|max|abs|clamp|assert|atomic_add|atomic_sub|atomic_load|atomic_store|atomic_swap|atomic_cas)\\s*(?=\\()",
           "captures": {
             "1": {
               "name": "support.function.builtin.finch"
@@ -217,6 +221,9 @@
       "begin": "\"",
       "end": "\"|$",
       "patterns": [
+        {
+          "include": "#interpolation"
+        },
         {
           "name": "constant.character.escape.finch",
           "match": "\\\\[ntr0\\\\\"']"
@@ -259,11 +266,49 @@
       "begin": "\"\"\"",
       "end": "\"\"\"",
       "patterns": [
+        {
+          "include": "#interpolation"
+        },
         {
           "name": "constant.character.escape.finch",
           "match": "\\\\[ntr0\\\\\"']"
         }
       ]
+    },
+    "interpolation": {
+      "name": "meta.embedded.line.finch",
+      "begin": "\\\\\\(",
+      "end": "\\)",
+      "beginCaptures": {
+        "0": {
+          "name": "punctuation.section.embedded.begin.finch"
+        }
+      },
+      "endCaptures": {
+        "0": {
+          "name": "punctuation.section.embedded.end.finch"
+        }
+      },
+      "patterns": [
+        {
+          "include": "#interpolation-parens"
+        },
+        {
+          "include": "$self"
+        }
+      ]
+    },
+    "interpolation-parens": {
+      "begin": "\\(",
+      "end": "\\)",
+      "patterns": [
+        {
+          "include": "#interpolation-parens"
+        },
+        {
+          "include": "$self"
+        }
+      ]
     }
   }
 }

editors/vscode/test/grammar.js

@@ -26,6 +26,9 @@ const code = [
   '    self.x += dx',
   '    return error("no")',
   '}',
+  'test "lives \\(hp + f(1)) left" {',
+  '    assert(clamp(x, 0, 9) == 3)',
+  '}',
 ];
 const expect = [  // [line, token text, scope that must be present]
   [0, 'import', 'keyword.control.import'], [0, '"stdio.h"', 'string.quoted.double'],
@@ -43,6 +46,9 @@ const expect = [  // [line, token text, scope that must be present]
   [13, 'try', 'keyword.control'], [13, 'or', 'keyword.control'],
   [14, 'self', 'variable.language.self'],
   [15, 'error', 'support.function.builtin'],
+  [17, 'test', 'keyword.other.test'], [17, '\\(', 'punctuation.section.embedded.begin'], [17, 'hp', 'meta.embedded.line'],
+  [17, 'f', 'meta.embedded.line'], [17, 'left', 'string.quoted.double'],
+  [18, 'assert', 'support.function.builtin'], [18, 'clamp', 'support.function.builtin'],
 ];
 registry.loadGrammar('source.finch').then((g) => {
   let state = vsctm.INITIAL, toks = [];