Merge branch 'main' into destructuring-docs

.github/workflows/tact.yml

@@ -4,10 +4,8 @@ env:
   HUSKY: 0
 
 on:
-  push:
-    branches: ["main"]
   pull_request:
-    branches: ["main"]
+    branches: ["**"]
   workflow_dispatch:
 
 jobs:

.gitignore

@@ -1,4 +1,5 @@
 .vscode
+.idea
 .DS_Store
 *.swp
 node_modules

CHANGELOG.md

@@ -15,7 +15,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Docs: Google Analytics tags per every page: PR [#921](https://github.com/tact-lang/tact/pull/921)
 - Docs: Added NFTs cookbook: PR [#958](https://github.com/tact-lang/tact/pull/958)
 - Ability to specify a compile-time method ID expression for getters: PR [#922](https://github.com/tact-lang/tact/pull/922) and PR [#932](https://github.com/tact-lang/tact/pull/932)
-- Destructuring of structs and messages: PR [#856](https://github.com/tact-lang/tact/pull/856), PR [#964](https://github.com/tact-lang/tact/pull/964)
+- Destructuring of structs and messages: PR [#856](https://github.com/tact-lang/tact/pull/856), PR [#964](https://github.com/tact-lang/tact/pull/964), PR [#969](https://github.com/tact-lang/tact/pull/969)
+- Docs: automatic links to Web IDE from all code blocks: PR [#994](https://github.com/tact-lang/tact/pull/994)
+- The `SendDefaultMode` send mode constant to the standard library: PR [#1010](https://github.com/tact-lang/tact/pull/1010)
+- Docs: initial semi-automated Chinese translation of the documentation: PR [#942](https://github.com/tact-lang/tact/pull/942)
+- The `replace` and `replaceGet` methods for the `Map` type: PR [#941](https://github.com/tact-lang/tact/pull/941)
 
 ### Changed
 
@@ -32,6 +36,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Prevent inline code snippets from changing their background color: PR [#935](https://github.com/tact-lang/tact/pull/935)
 - Docs: correctly handle next and previous page links at the bottom of the pages when there's a separator item in the sidebar: PR [#949](https://github.com/tact-lang/tact/pull/949)
 - Docs: compilation of examples in `data-structures.mdx` and across Cookbook: PR [#917](https://github.com/tact-lang/tact/pull/917)
+- `as coins` map value serialization type is now handled correctly: PR [#987](https://github.com/tact-lang/tact/pull/987)
+- Type checking for `foreach` loops in trait methods: PR [#1017](https://github.com/tact-lang/tact/pull/1017)
 
 ### Release contributors
 

crowdin.yml

@@ -0,0 +1,8 @@
+project_id: "723773"
+api_token_env: CROWDIN_PERSONAL_TOKEN
+preserve_hierarchy: 1
+files:
+  - source: /docs/src/content/docs/**/*
+    translation: /docs/src/content/docs/%two_letters_code%/**/%original_file_name%
+    ignore:
+      - /docs/src/content/docs/%two_letters_code%

cspell.json

@@ -89,6 +89,7 @@
     "rangle",
     "rawslice",
     "renamer",
+    "replaceget",
     "rparen",
     "rugpull",
     "rugpulled",
@@ -113,6 +114,7 @@
     "uintptr",
     "uninit",
     "unixfs",
+    "varuint",
     "workchain",
     "xffff",
     "привет"

docs/astro.config.mjs

@@ -14,6 +14,9 @@ import rehypeAutolinkHeadings from 'rehype-autolink-headings';
 import remarkMath from 'remark-math';
 import rehypeKatex from 'rehype-katex';
 
+// Adds links to Web IDE from code blocks
+import remarkLinksToWebIDE from './links-to-web-ide';
+
 // Adds syntax highlighting for inline code blocks
 import rehypeInlineCodeHighlighting from './inline-code-highlighting';
 
@@ -26,7 +29,7 @@ export default defineConfig({
 	outDir: './dist', // default, just to be sure
 	site: 'https://docs.tact-lang.org',
 	markdown: {
-		remarkPlugins: [remarkHeadingId, remarkMath],
+		remarkPlugins: [remarkHeadingId, remarkMath, remarkLinksToWebIDE],
 		rehypePlugins: [
 			rehypeHeadingIds,
 			[rehypeAutolinkHeadings, {

docs/grammars/grammar-tact.json

@@ -293,7 +293,7 @@
           },
           {
             "comment": "Other constants from the core library",
-            "match": "(?<!\\.)\\b(SendRemainingValue|SendRemainingBalance|SendPayGasSeparately|SendIgnoreErrors|SendBounceIfActionFail|SendDestroyIfZero|SendOnlyEstimateFee|ReserveExact|ReserveAllExcept|ReserveAtMost|ReserveAddOriginalBalance|ReserveInvertSign|ReserveBounceIfActionFail)\\b",
+            "match": "(?<!\\.)\\b(SendDefaultMode|SendRemainingValue|SendRemainingBalance|SendPayGasSeparately|SendIgnoreErrors|SendBounceIfActionFail|SendDestroyIfZero|SendOnlyEstimateFee|ReserveExact|ReserveAllExcept|ReserveAtMost|ReserveAddOriginalBalance|ReserveInvertSign|ReserveBounceIfActionFail)\\b",
             "name": "constant.other.builtin.tact"
           },
           {

docs/links-to-web-ide.js

@@ -0,0 +1,97 @@
+/**
+ * @import {Root} from 'mdast'
+ * @import {VFile} from 'vfile'
+ */
+import { visit } from 'unist-util-visit';
+
+/**
+ * Maximum allowed characters in a Chrome
+ * Firefox has more limit but we are using less for compatibility
+ */
+const maxAllowedCharacters = 32779;
+
+/**
+ * Adds links to every code block, allowing to open its contents in the Web IDE
+ *
+ * @returns Transform.
+ */
+export default function remarkLinksToWebIDE() {
+  /**
+   * @param tree {Root}
+   * @param file {VFile}
+   * @return {undefined}
+   */
+  return function(tree, file) {
+    // Specifying 'code' items guarantees non-inline code blocks
+    visit(tree, 'code', function(node, index, parent) {
+      // Only allow Tact code blocks
+      if (node.lang !== 'tact') { return undefined; }
+
+      // Only allow certain amount of characters
+      let src = node.value.trim();
+      if (src.length > maxAllowedCharacters) { return undefined; }
+
+      // Disallow single-line code blocks as they pose very little value and they're often represent function signatures in the Reference section
+      const lines = src.split('\n');
+      if (lines.length <= 1) { return undefined; }
+
+      // Only allow pages in the Cookbook
+      // NOTE: This limitation can be lifted in the future if there's popular demand
+      if (file.path.indexOf('docs/cookbook') === -1) { return undefined; }
+
+      // Detect module-level items
+      let hasModuleItems = false;
+      for (let i = 0; i < lines.length; i += 1) {
+        // Same regex as in scripts/check-cookbook-examples.js
+        const matchRes = lines[i].match(/^\s*(?:import|primitive|const|asm|fun|extends|mutates|virtual|override|inline|abstract|@name|@interface|contract|trait|struct|message)\b/);
+        // TODO: Unite the regexes when Tact 2.0 arrives (or if some new module-level item arrives, or via try/catch and re-using compiler's parser)
+
+        if (matchRes !== null) {
+          hasModuleItems = true;
+          break;
+        }
+      }
+
+      // Adjust the source code if the module-level items are NOT present
+      if (!hasModuleItems) {
+        src = [
+          'fun fromTactDocs() {',
+          lines.map(line => `    ${line}`).join('\n'),
+          '}',
+        ].join('\n');
+      }
+
+      // Encode to URL-friendly Base64
+      const encoded = Buffer.from(src).toString('base64url');
+
+      // Double-check the number of characters in the link
+      const link = `https://ide.ton.org?lang=tact&code=${encoded}`;
+      if (link.length > maxAllowedCharacters) { return undefined; }
+
+      /** @type import('mdast').Html */
+      const button = {
+        type: 'html',
+        value: [
+          // Constructing opening <a> tag
+          [
+            // Open the tag
+            '<a',
+            // Make links opened in new tab
+            'target="_blank"',
+            // Set styles
+            'class="web-ide-link"',
+            // Add hyperref with > to close the tag
+            `href="${link}">`,
+          ].join(' '),
+          // The text to click on
+          '<span class="web-ide-link-span">▶️ Open in Web IDE</span>',
+          // Closing </a> tag
+          '</a>',
+        ].join(''),
+      };
+
+      // Place the button after the code block
+      parent.children.splice(index + 1, 0, button);
+    });
+  }
+}

docs/package.json

@@ -10,24 +10,26 @@
     "build": "yarn clean && yarn lint:all && astro check && astro build",
     "preview": "astro preview",
     "astro": "astro",
-    "spell": "cspell --no-progress src/content/docs",
+    "spell": "yarn cspell --no-progress src/content/docs",
     "lint:all": "yarn spell"
   },
   "dependencies": {
-    "@astrojs/check": "^0.9.3",
-    "@astrojs/markdown-remark": "^5.2.0",
-    "@astrojs/starlight": "^0.28.2",
-    "astro": "^4.16.1",
+    "@astrojs/check": "0.9.4",
+    "@astrojs/markdown-remark": "5.3.0",
+    "@astrojs/starlight": "0.28.4",
+    "astro": "4.16.7",
     "cspell": "^8.14.4",
     "hast-util-to-string": "^3.0.0",
     "rehype-autolink-headings": "7.1.0",
     "rehype-katex": "7.0.1",
+    "remark": "^15.0.1",
     "remark-custom-heading-id": "2.0.0",
     "remark-math": "6.0.0",
     "sharp": "^0.32.5",
     "starlight-links-validator": "^0.12.1",
     "typescript": "^5.6.2",
     "unist-util-visit": "^5.0.0"
   },
-  "packageManager": "[email protected]"
+  "packageManager": "[email protected]",
+  "version": ""
 }

docs/scripts/check-cookbook-examples.js

@@ -16,7 +16,6 @@ import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import {
   mkdtempSync,
-  mkdtemp,
   readFileSync,
   readdirSync,
   statSync,

docs/src/content/docs/book/maps.mdx

@@ -96,6 +96,90 @@ if (gotButUnsure != null) {
 }
 ```
 
+### Replace values, `.replace()` {#replace}
+
+<Badge text="Available since Tact 1.6" variant="tip" size="medium"/><p/>
+
+To replace the value under a key, if such a key exists, use the `.replace(){:tact}` [method](/book/functions#extension-function). It returns `true{:tact}` on successful replacement and `false{:tact}` otherwise.
+
+```tact
+// Empty map
+let fizz: map<Int, Int> = emptyMap();
+
+// Setting a couple of values under different keys
+fizz.set(7, 70);
+fizz.set(42, 42);
+
+// Overriding one of the existing key-value pairs
+let replaced1 = fizz.replace(7, 68); // key 7 now points to value 68
+replaced1; // true
+
+// Trying to replace the value in a non-existing key-value pair will do nothing
+let replaced2 = fizz.replace(8, 68); // no key 8, so nothing was altered
+replaced2; // false
+```
+
+If the given value is [`null{:tact}`](/book/optionals) and the key exists, the entry will be deleted from the map.
+
+```tact
+// Empty map
+let fizz: map<Int, Int> = emptyMap();
+
+// Setting a couple of values under different keys
+fizz.set(7, 70);
+fizz.set(42, 42);
+
+// Overriding one of the existing key-value pairs
+let replaced1 = fizz.replace(7, null); // the entry under key 7 is now deleted
+replaced1; // true
+
+// Trying to replace the value in a non-existing key-value pair will do nothing
+let replaced2 = fizz.replace(8, null); // no key 8, so nothing was altered
+replaced2; // false
+```
+
+### Replace and get old value, `.replaceGet()` {#replaceget}
+
+<Badge text="Available since Tact 1.6" variant="tip" size="medium"/><p/>
+
+Like [`.replace()`](#replace), but instead of returning a [`Bool{:tact}`](/book/types#booleans) it returns the old (pre-replacement) value on successful replacement and [`null{:tact}`](/book/optionals) otherwise.
+
+```tact
+// Empty map
+let fizz: map<Int, Int> = emptyMap();
+
+// Setting a couple of values under different keys
+fizz.set(7, 70);
+fizz.set(42, 42);
+
+// Overriding one of the existing key-value pairs
+let oldVal1 = fizz.replaceGet(7, 68); // key 7 now points to value 68
+oldVal1; // 70
+
+// Trying to replace the value in a non-existing key-value pair will do nothing
+let oldVal2 = fizz.replaceGet(8, 68); // no key 8, so nothing was altered
+oldVal2; // null
+```
+
+If the given value is [`null{:tact}`](/book/optionals) and the key exists, the entry will be deleted from the map.
+
+```tact
+// Empty map
+let fizz: map<Int, Int> = emptyMap();
+
+// Setting a couple of values under different keys
+fizz.set(7, 70);
+fizz.set(42, 42);
+
+// Overriding one of the existing key-value pairs
+let oldVal1 = fizz.replaceGet(7, null); // the entry under key 7 is now deleted
+oldVal1; // 70
+
+// Trying to replace the value in a non-existing key-value pair will do nothing
+let oldVal2 = fizz.replaceGet(8, null); // no key 8, so nothing was altered
+oldVal2; // null
+```
+
 ### Delete entries, `.del()` {#del}
 
 To delete a single key-value pair (single entry), use the `.del(){:tact}` [method](/book/functions#extension-function). It returns `true{:tact}` in the case of successful deletion and `false{:tact}` otherwise.

docs/src/content/docs/book/message-mode.mdx

@@ -3,6 +3,8 @@ title: Message mode
 description: "Messages are sent with the mode param of a struct SendParameters. It's an Int value, which is combined from base modes and optional flags, which are also Int values"
 ---
 
+import { Badge } from '@astrojs/starlight/components';
+
 As it was previously mentioned, messages are sent with the `mode` param of a struct `SendParameters{:tact}`. It's an [`Int{:tact}`][int] value, which is combined from base modes and optional flags, which are also [`Int{:tact}`][int] values.
 
 It's possible to use raw [`Int{:tact}`][int] values and manually provide them for the `mode`, but for your convenience there's a set of constants which you may use to construct the compound `mode` with ease. Take a look at the following tables for more information on base modes and optional flags.
@@ -11,7 +13,7 @@ It's possible to use raw [`Int{:tact}`][int] values and manually provide them fo
 
 Mode value | Constant name                 | Description
 ---------: | :---------------------------- | -----------
-$0$        | -                             | Ordinary message (default).
+$0$        | <Badge text="Since Tact 1.6" variant="tip"/> `SendDefaultMode{:tact}` | Ordinary message (default).
 $64$       | `SendRemainingValue{:tact}`   | Carry all the remaining value of the inbound message in addition to the value initially indicated in the new message.
 $128$      | `SendRemainingBalance{:tact}` | Carry all the remaining balance of the current smart contract instead of the value originally indicated in the message.
 
@@ -35,7 +37,7 @@ Alternatively, if you want to send the whole contract balance and destroy it imm
 Here's how the latter example would look in code:
 
 ```tact
-let to: Address = ...;
+let to: Address = address("...");
 let value: Int = ton("1");
 send(SendParameters{
     to: to,

docs/src/content/docs/book/send.mdx

@@ -46,7 +46,7 @@ send(SendParameters{
 Another example sends a message to the specified [`Address{:tact}`][p] with a `value` of $1$ TON and the `body` of a comment with a [`String{:tact}`][p] `"Hello, World!"{:tact}`:
 
 ```tact
-let recipient: Address = ...;
+let recipient: Address = address("...");
 let value: Int = ton("1");
 send(SendParameters{
     // bounce is set to true by default
@@ -64,7 +64,7 @@ The [optional flag](/book/message-mode#optional-flags) `SendIgnoreErrors{:tact}`
 To send a binary typed message you can use the following code:
 
 ```tact
-let recipient: Address = ...;
+let recipient: Address = address("...");
 let value: Int = ton("1");
 send(SendParameters{
     // bounce is set to true by default

docs/src/content/docs/index.mdx

@@ -5,8 +5,8 @@ template: splash
 hero:
   tagline: Tact is a new programming language for TON Blockchain that is focused on efficiency and simplicity. It is designed to be easy to learn and use, and to be a good fit for smart contracts. Tact is a statically typed language with a simple syntax and a powerful type system.
   image:
-    dark: ../../../public/logomark-dark.svg
-    light: ../../../public/logomark-light.svg
+    dark: /public/logomark-dark.svg
+    light: /public/logomark-light.svg
     alt: Tact logo
   actions:
     - text: 📚 Book

docs/src/content/docs/ref/core-cells.mdx

@@ -22,7 +22,7 @@ import { Badge } from '@astrojs/starlight/components';
 ## beginCell
 
 ```tact
-fun beginCell(): Builder
+fun beginCell(): Builder;
 ```
 
 Creates a new empty [`Builder{:tact}`][builder].