feat: Language->Reference, a big update!

WIP, but almost there.

Author: novusnota

pages/book/config.mdx

@@ -15,7 +15,7 @@ Each project is described by the following fields:
 
 Tact support next parameters:
 * `debug: true`. Enables debug output of a contract. It is useful for debugging purposes. Enabling this contract would report that it was compiled in debug mode using the `supported_interfaces` method.
-* `masterchain: true`. Enables [masterchain support](/language/guides/masterchain) in the contract.
+* `masterchain: true`. Enables [masterchain support](/book/masterchain) in the contract.
 
 ## Example
 

pages/book/import.mdx

@@ -4,7 +4,7 @@ import { Callout } from 'nextra-theme-docs'
 
 Tact allows you to import Tact and [FunC](https://docs.ton.org/develop/func/overview) code — any given `.tact` or `.fc`/`.func` file can be imported into your project using an `import{:tact}` keyword.
 
-Additionally, Tact compiler has a versatile set of standard libraries, which come bundled in, but not included right away, see [Language→Libs→Overview](/language/libs/overview).
+Additionally, Tact compiler has a versatile set of standard libraries, which come bundled in, but not included right away, see [Standard libraries overview](/ref/standard-libraries).
 
 <Callout type="warning" emoji="⚠️">
   NOTE: All imported code is combined together with yours, so it's important to avoid name collisions and always double-check the sources!
@@ -36,7 +36,7 @@ import "./relative/path/to/the/target/func/file.fc";
 import "../subfolder/imported/func/file.fc";
 ```
 
-But in order to use functions from such file, one has to declare them as `native` functions first. For example, when standard library [@stdlib/dns](/language/libs/dns) uses a `dns.fc` FunC file, it maps FunC functions to Tact ones like so:
+But in order to use functions from such file, one has to declare them as `native` functions first. For example, when standard library [@stdlib/dns](/ref/stdlib-dns) uses a `dns.fc` FunC file, it maps FunC functions to Tact ones like so:
 
 ```tact
 // FunC code located in a file right next to the current Tact one:
@@ -49,4 +49,4 @@ native dnsStringToInternal(str: String): Slice?;
 
 ## Standard libraries
 
-See [Language→Libs→Overview](/language/libs/overview).
+See [Standard libraries overview](/ref/standard-libraries).

pages/book/integers.mdx

@@ -46,7 +46,7 @@ Use underscores (`_`) to improve readability: $\mathrm{0b111\_111\_111}$ is equa
 
 For example, arithmetic with dollars requires two decimal places after the dot — those are used for the cents value. But how would we represent the number \$$1.25$ if we're only able to work with integers? The solution is to work with _cents_ directly. This way, \$$1.25$ becomes $125$ cents. We simply memorize that the two rightmost digits represent the numbers after the decimal point.
 
-Similarly, working with Toncoins requires nine decimal places instead of the two. Therefore, the amount of $1.25$ TON, which can be represented in Tact as [`ton("1.25"){:tact}`](/language/ref/common#ton), is actually the number $1250000000$. We refer to such numbers as _nano-tons_ (or _nanoToncoins_) rather than _cents_.
+Similarly, working with Toncoins requires nine decimal places instead of the two. Therefore, the amount of $1.25$ TON, which can be represented in Tact as [`ton("1.25"){:tact}`](/ref/api-comptime#ton), is actually the number $1250000000$. We refer to such numbers as _nano-tons_ (or _nanoToncoins_) rather than _cents_.
 
 ## Serialization
 

pages/book/operators.mdx

@@ -8,7 +8,7 @@ This page lists all the operators in Tact in decreasing order of their [preceden
 
 <Callout>
 
-  Note, that there are no implicit type conversions in Tact, so operators can't be used to, say, add values of different type or compare them in terms of equality without explicitly casting to the same type. That's done with certain functions from the standard library. See [`Int.toString(){:tact}`](/language/ref/strings#inttostring) for an example of such function.
+  Note, that there are no implicit type conversions in Tact, so operators can't be used to, say, add values of different type or compare them in terms of equality without explicitly casting to the same type. That's done with certain functions from the standard library. See [`Int.toString(){:tact}`](/ref/api-strings#inttostring) for an example of such function.
 
 </Callout>
 
@@ -135,7 +135,7 @@ two % 1; // 1
 -1 % -5; // -1
 ```
 
-The simplest way to avoid confusion between the two is to prefer using positive values via [`abs(x: Int){:tact}`](/language/ref/math#abs):
+The simplest way to avoid confusion between the two is to prefer using positive values via [`abs(x: Int){:tact}`](/ref/api-math#abs):
 
 ```tact
 abs(-1) % abs(-5); // 1

pages/book/types.mdx

@@ -140,7 +140,7 @@ Read more about them on the dedicated page: [Contracts](/book/contracts).
 
 Tact doesn't support classical class inheritance, but instead introduces the concept of _traits_, which can be viewed as abstract contracts (like abstract classes in popular object-oriented languages). They have the same structure as [contracts](#contracts), but can't [initialize persistent state variables](/book/contracts#init-function), while allowing to override some of their behaviors.
 
-Example of a trait [`Ownable`](/language/libs/ownable#ownable) from [`@stdlib/ownable`](/language/libs/ownable):
+Example of a trait [`Ownable{:tact}`](/ref/stdlib-ownable#ownable) from [`@stdlib/ownable`](/ref/stdlib-ownable):
 
 ```tact
 trait Ownable {
@@ -159,14 +159,14 @@ trait Ownable {
 }
 ```
 
-And the [contract](#contracts) that uses trait [`Ownable`](/language/libs/ownable#ownable):
+And the [contract](#contracts) that uses trait [`Ownable{:tact}`](/ref/stdlib-ownable#ownable):
 
 ```tact
 contract Treasure with Ownable {
-    // persistent state variable, which MUST be defined in the contract
+    // Persistent state variable, which MUST be defined in the contract
     owner: Address;
 
-    // constructor function init(), where all the variables are initialized
+    // Constructor function init(), where all the variables are initialized
     init(owner: Address) {
         self.owner = owner;
     }

pages/cookbook/misc.mdx

@@ -26,7 +26,7 @@ nativeThrowUnless(39, number == 198);
 <Callout>
 
   **Useful links:**\
-  [`throw(){:tact}` in Language→Reference](/language/ref/advanced#throw)\
+  [`throw(){:tact}` in API Reference](/ref/api-debug#throw)\
   [Errors in Tact-By-Example](https://tact-by-example.org/03-errors)
 
 </Callout>

pages/cookbook/random.mdx

@@ -20,8 +20,8 @@ number = random(1, 12);
 <Callout>
 
   **Useful links:**\
-  [`randomInt(){:tact}` in Language→Reference](/language/ref/random#randomInt)\
-  [`random(){:tact}` in Language→Reference](/language/ref/random#random)
+  [`randomInt(){:tact}` in API Reference](/ref/api-random#randomInt)\
+  [`random(){:tact}` in API Reference](/ref/api-random#random)
 
 </Callout>
 

pages/cookbook/single-communication.mdx

@@ -91,7 +91,7 @@ send(SendParameters{
   ["Sending messages" in the Book](/book/send#send-message)\
   ["Message `mode`" in the Book](/book/message-mode)
   [`StringBuilder{:tact}` in the Book](/book/types#primitive-types)\
-  [`Cell{:tact}` in Language→Reference](/language/ref/cells)
+  [`Cell{:tact}` in API Reference](/ref/api-cells)
 
 </Callout>
 

pages/cookbook/time.mdx

@@ -19,7 +19,7 @@ if (currentTime > 1672080143) {
 <Callout>
 
   **Useful links:**\
-  [`now(){:tact}` in Language→Reference](/language/ref/common#now)\
+  [`now(){:tact}` in API Reference](/ref/api-common#now)\
   ["Current Time" in Tact-By-Example](https://tact-by-example.org/04-current-time)
 
 </Callout>

pages/cookbook/type-conversion.mdx

@@ -60,9 +60,9 @@ dump(coinsString);  // "0.261119911"
 <Callout>
 
   **Useful links:**\
-  [`Int.toString(){:tact}` in Language→Reference](/language/ref/strings#inttostring)\
-  [`Int.toFloatString(){:tact}` in Language→Reference](/language/ref/strings#inttofloatstring)\
-  [`Int.toCoinsString(){:tact}` in Language→Reference](/language/ref/strings#inttocoinsstring)
+  [`Int.toString(){:tact}` in API Reference](/ref/api-strings#inttostring)\
+  [`Int.toFloatString(){:tact}` in API Reference](/ref/api-strings#inttofloatstring)\
+  [`Int.toCoinsString(){:tact}` in API Reference](/ref/api-strings#inttocoinsstring)
 
 </Callout>
 

pages/index.mdx

@@ -109,7 +109,7 @@ For custom plugins for your favorite editor and other tooling see the [Tools](/e
 Alternatively, take a look at the following broader sections:
 * [Book](/book) helps you learn the language step-by-step
 * [Cookbook](/cookbook) gives you ready-made recipes of Tact code
-* [Language](/language) provides a complete reference of the standard library, grammar and evolution process
+* [Reference](/ref) provides a complete glossary of the standard library, grammar and evolution process
 * Finally, [Ecosystem](/ecosystem) describes "what's out there" in the Tacts' and TONs' ecosystems
 
 <Cards>
@@ -120,13 +120,13 @@ Alternatively, take a look at the following broader sections:
   />
   <Cards.Card
     icon="🍲 "
-    title="Examine the Cookbook"
+    title="Grind the Cookbook"
     href="/cookbook"
   />
   <Cards.Card
     icon="🔬 "
-    title="Study the Language"
-    href="/language"
+    title="Skim the Reference"
+    href="/ref"
   />
   <Cards.Card
     icon="🗺️ "

pages/ref/_meta.js

@@ -7,11 +7,12 @@ export default {
     title: 'API Reference',
   },
   'api-base': 'Base trait',
+  'api-common': 'Common',
   'api-comptime': 'Compile-time',
-  'api-common': 'Common', // what does it mean???
-  'api-strings': 'Strings', // text.tact + ...
+  'api-debug': 'Debug',
   'api-random': 'Random',
   'api-math': 'Math',
+  'api-strings': 'Strings and StringBuilders',
   'api-cells': 'Cells, Builders and Slices',
   'api-advanced': 'Advanced',
   '-- Stdlib': {

pages/ref/api-advanced.mdx

@@ -1,4 +1,4 @@
-# Miscellaneous
+# Advanced
 
 import { Callout } from 'nextra/components'
 
@@ -18,30 +18,6 @@ extends fun readForwardFee(self: Context): Int
 
 Read and compute forward fee from the `Context{:tact}` and return it as `Int{:tact}` value in nanoToncoins (nano-tons).
 
-## throw
-
-```tact
-fun throw(code: Int);
-```
-
-Throw an exception with error code equal `code`.
-
-## nativeThrowWhen
-
-```tact
-fun nativeThrowWhen(code: Int, condition: Bool);
-```
-
-Throw an exception with error code equal to `code` when `condition` is equal to `true{:tact}`.
-
-## nativeThrowUnless
-
-```tact
-fun nativeThrowUnless(code: Int, condition: Bool);
-```
-
-Throw an exception with error code equal to `code` when `condition` is equal to `false{:tact}`.
-
 ## getConfigParam
 
 ```tact
@@ -125,3 +101,19 @@ Function `raw_reserve` is roughly equivalent to creating an outbound message car
 <Callout type="warning" emoji="⚠️">
   Currently, `amount` must be a non-negative integer, and `mode` must be in the range 0..15, inclusive.
 </Callout>
+
+---
+
+TODO: remove
+
+```tact
+@name(raw_reserve)
+native nativeReserve(amount: Int, mode: Int);
+
+const ReserveExact: Int = 0;
+const ReserveAllExcept: Int = 1;
+const ReserveAtMost: Int = 2;
+const ReserveAddOriginalBalance: Int = 4;
+const ReserveInvertSign: Int = 8;
+const ReserveBounceIfActionFail: Int = 16;
+```

pages/ref/api-base.mdx

@@ -2,10 +2,124 @@
 
 import { Callout } from 'nextra-theme-docs'
 
-Every [contract](/book/contracts) and [trait](/book/types#traits) in Tact implicitly inherits the `Base{:tact}` trait, which contains a number of the most useful [internal functions (methods)](/book/contracts#internal-functions) for any kind of contract.
+Every [contract](/book/contracts) and [trait](/book/types#traits) in Tact implicitly inherits the `Base{:tact}` trait, which contains a number of the most useful [internal functions](/book/contracts#internal-functions) for any kind of contract, and a constant `storageReserve` aimed at advanced users of Tact.
 
-<Callout emoji="🚨">
+## Constants
 
-  This page is a stub. [Contributions are welcome!](https://github.com/tact-lang/tact-docs/issues)
+### self.storageReserve [#self-storagereserve]
+
+```tact
+virtual const storageReserve: Int = 0;
+```
+
+Usage example:
+
+```tact
+contract AllYourStorageBelongsToUs {
+    // This would change the behaviour of self.reserve() function,
+    // causing it to try reserving this amount of nanoToncoins before
+    // forwarding a message with SendRemainingBalance mode
+    override const storageReserve = ton("0.1");
+}
+```
+
+## Functions
+
+### self.reply [#self-reply]
+
+```tact
+virtual fun reply(body: Cell?);
+```
+
+An alias to calling the [`forward(){:tact}`](#self-forward) function with the following arguments:
+
+```tact
+self.forward(sender(), body, true, null);
+//           ↑         ↑     ↑     ↑
+//           |         |     |     init: StateInit?
+//           |         |     bounce: Bool
+//           |         body: Cell?
+//           to: Address
+```
+
+Usage example:
+
+```tact
+// This message can bounce back to us!
+self.reply("Beware, this is my reply to you!".asComment());
+```
+
+### self.notify [#self-notify]
+
+```tact
+virtual fun notify(body: Cell?);
+```
+
+An alias to calling the [`forward(){:tact}`](#self-forward) function with the following arguments:
+
+```tact
+self.forward(sender(), body, false, null);
+//           ↑         ↑     ↑      ↑
+//           |         |     |      init: StateInit?
+//           |         |     bounce: Bool
+//           |         body: Cell?
+//           to: Address
+```
+
+Usage example:
+
+```tact
+// This message won't bounce!
+self.notify("Beware, this is my reply to you!".asComment());
+```
+
+### self.forward [#self-forward]
+
+```tact
+virtual fun forward(to: Address, body: Cell?, bounce: Bool, init: StateInit?);
+```
+
+Sends a bounceable or non-bounceable message to the specified address `to`. Optionally, you may provide a `body` of the message and the [`init` package](/book/expressions#initof).
+
+When [`storageReserve{:tact}`](#self-storagereserve) constant is overwritten to be $> 0$, before sending a message it also tries to reserve the `storageReserve{:tact}` amount of nanoToncoins from the remaining balance before making the send in the [`SendRemainingBalance{:tact}`](https://docs.tact-lang.org/book/message-mode#base-modes) ($128$) mode.
+
+In case reservation attempt fails and in the default case without the attempt, the message is sent with the [`SendRemainingValue{:tact}`](https://docs.tact-lang.org/book/message-mode#base-modes) ($64$) mode instead.
+
+<Callout>
+
+  Note, that `self.forward(){:tact}` never sends additional Toncoins on top of what's available on the balance.\
+  To be able to send more Toncoins with a single message, use the the [`send(){:tact}`](/ref/api-common#send) function.
 
 </Callout>
+
+Usage example:
+
+```tact
+import "@stdlib/ownable";
+
+message PayoutOk {
+    address: Address;
+    value: Int as coins;
+}
+
+contract Payout with Ownable {
+    completed: Bool;
+    owner: Address;
+
+    init(owner: Address) {
+        self.owner = owner;
+        self.completed = false;
+    }
+
+    // ... some actions there ...
+
+    // Bounced receiver function, which is called when the specified outgoing message bounces back
+    bounced(msg: bounced<PayoutOk>) {
+        // Reset completed flag if our message bounced
+        self.completed = false;
+
+        // Send a notification that the payout failed using the remaining funds for processing this send
+        self.forward(self.owner, "Payout failed".asComment(), false, null);
+    }
+}
+```