Skip to content

Commit dca4afe

Browse files
tolk-vmtolk-vm
authored
feat: documentation for Tolk (#1421)
1 parent da70be2 commit dca4afe

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

64 files changed

+10159
-5190
lines changed

‎.cspell.jsonc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,18 @@
8383
"!2lw-deny-list", // turns off the dictionary
8484
]
8585
},
86+
{
87+
"filename": "languages/tolk/features/compiler-optimizations.mdx",
88+
"ignoreWords": [
89+
"fifting",
90+
]
91+
},
92+
{
93+
"filename": "languages/tolk/from-func/tolk-vs-func.mdx",
94+
"ignoreWords": [
95+
"transpiles",
96+
]
97+
},
8698
{
8799
"filename": "**/api/**/*.{json,yml,yaml}",
88100
"ignoreWords": [
@@ -110,6 +122,7 @@
110122
"foundations/whitepapers/ton.mdx",
111123
"foundations/whitepapers/tvm.mdx",
112124
"languages/fift/whitepaper.mdx",
125+
"languages/tolk/features/standard-library.mdx",
113126
// Generated files
114127
"tvm/instructions.mdx",
115128
// Binaries

‎contract-dev/first-smart-contract.mdx‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ First, we need a way to store the counter value. Tolk makes this simple with <To
118118

119119
```tolk title="./contracts/first_contract.tolk"
120120
struct Storage {
121-
counter: uint64; // the current counter value
121+
counter: uint64 // the current counter value
122122
}
123123
124124
// load contract data from persistent storage
@@ -153,17 +153,17 @@ Tolk structures are also useful for defining message bodies. In our case, we’l
153153
Each structure has a unique prefix (`0x7e8764ef` and `0x3a752f06`), widely called opcodes, that lets the contract distinguish between them.
154154

155155
```tolk title="./contracts/first_contract.tolk"
156-
struct(0x7e8764ef) IncreaseCounter {
156+
struct (0x7e8764ef) IncreaseCounter {
157157
increaseBy: uint32
158158
}
159159
160-
struct(0x3a752f06) ResetCounter {}
160+
struct (0x3a752f06) ResetCounter {}
161161
```
162162

163163
To group them together, we'll use a union. Unions allow multiple types to be bundled into a single type that can be serialized and deserialized automatically:
164164

165165
```tolk title="./contracts/first_contract.tolk"
166-
type AllowedMessage = IncreaseCounter | ResetCounter;
166+
type AllowedMessage = IncreaseCounter | ResetCounter
167167
```
168168

169169
Now we can write our message handler:
@@ -227,7 +227,7 @@ Here’s the full source code of `contracts/first_contract.tolk`:
227227

228228
```tolk title="./contracts/first_contract.tolk" expandable
229229
struct Storage {
230-
counter: uint64;
230+
counter: uint64
231231
}
232232
233233
fun Storage.load() {
@@ -238,13 +238,13 @@ fun Storage.save(self) {
238238
contract.setData(self.toCell());
239239
}
240240
241-
struct(0x7e8764ef) IncreaseCounter {
241+
struct (0x7e8764ef) IncreaseCounter {
242242
increaseBy: uint32
243243
}
244244
245-
struct(0x3a752f06) ResetCounter {}
245+
struct (0x3a752f06) ResetCounter {}
246246
247-
type AllowedMessage = IncreaseCounter | ResetCounter;
247+
type AllowedMessage = IncreaseCounter | ResetCounter
248248
249249
fun onInternalMessage(in: InMessage) {
250250
val msg = lazy AllowedMessage.fromSlice(in.body);
@@ -292,7 +292,7 @@ npx blueprint build FirstContract
292292

293293
Expected output:
294294

295-
```
295+
```ansi
296296
Build script running, compiling FirstContract
297297
🔧 Using tolk version 1.1.0...
298298

‎docs.json‎

Lines changed: 121 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -386,21 +386,71 @@
386386
"tag": "recommended",
387387
"pages": [
388388
"languages/tolk/overview",
389+
"languages/tolk/basic-syntax",
390+
"languages/tolk/idioms-conventions",
389391
{
390-
"group": "From FunC",
392+
"group": "Type system",
391393
"pages": [
392-
"languages/tolk/from-func/in-short",
393-
"languages/tolk/from-func/in-detail",
394-
"languages/tolk/from-func/mutability",
395-
"languages/tolk/from-func/stdlib",
396-
"languages/tolk/from-func/create-message",
397-
"languages/tolk/from-func/lazy-loading",
398-
"languages/tolk/from-func/pack"
394+
"languages/tolk/types/list-of-types",
395+
"languages/tolk/types/numbers",
396+
"languages/tolk/types/booleans",
397+
"languages/tolk/types/address",
398+
"languages/tolk/types/cells",
399+
"languages/tolk/types/strings",
400+
"languages/tolk/types/structures",
401+
"languages/tolk/types/aliases",
402+
"languages/tolk/types/generics",
403+
"languages/tolk/types/enums",
404+
"languages/tolk/types/nullable",
405+
"languages/tolk/types/unions",
406+
"languages/tolk/types/tensors",
407+
"languages/tolk/types/tuples",
408+
"languages/tolk/types/maps",
409+
"languages/tolk/types/callables",
410+
"languages/tolk/types/void-never",
411+
"languages/tolk/types/type-checks-and-casts",
412+
"languages/tolk/types/overall-tvm-stack",
413+
"languages/tolk/types/overall-serialization"
414+
]
415+
},
416+
{
417+
"group": "Syntax details",
418+
"pages": [
419+
"languages/tolk/syntax/variables",
420+
"languages/tolk/syntax/conditions-loops",
421+
"languages/tolk/syntax/exceptions",
422+
"languages/tolk/syntax/functions-methods",
423+
"languages/tolk/syntax/structures-fields",
424+
"languages/tolk/syntax/pattern-matching",
425+
"languages/tolk/syntax/mutability",
426+
"languages/tolk/syntax/operators",
427+
"languages/tolk/syntax/imports"
428+
]
429+
},
430+
{
431+
"group": "Language features",
432+
"pages": [
433+
"languages/tolk/features/message-handling",
434+
"languages/tolk/features/contract-storage",
435+
"languages/tolk/features/contract-getters",
436+
"languages/tolk/features/message-sending",
437+
"languages/tolk/features/auto-serialization",
438+
"languages/tolk/features/lazy-loading",
439+
"languages/tolk/features/jetton-payload",
440+
"languages/tolk/features/standard-library",
441+
"languages/tolk/features/asm-functions",
442+
"languages/tolk/features/compiler-optimizations"
443+
]
444+
},
445+
{
446+
"group": "Migrating from FunC",
447+
"pages": [
448+
"languages/tolk/from-func/tolk-vs-func",
449+
"languages/tolk/from-func/tolk-vs-tlb",
450+
"languages/tolk/from-func/stdlib-fc",
451+
"languages/tolk/from-func/converter"
399452
]
400453
},
401-
"languages/tolk/environment-setup",
402-
"languages/tolk/counter-smart-contract",
403-
"languages/tolk/language-guide",
404454
"languages/tolk/changelog"
405455
]
406456
},
@@ -911,52 +961,52 @@
911961
},
912962
{
913963
"source": "/v3/documentation/smart-contracts/tolk/environment-setup",
914-
"destination": "/languages/tolk/environment-setup",
964+
"destination": "contract-dev/first-smart-contract",
915965
"permanent": true
916966
},
917967
{
918968
"source": "/v3/documentation/smart-contracts/tolk/counter-smart-contract",
919-
"destination": "languages/tolk/counter-smart-contract",
969+
"destination": "contract-dev/first-smart-contract",
920970
"permanent": true
921971
},
922972
{
923973
"source": "/v3/documentation/smart-contracts/tolk/language-guide",
924-
"destination": "languages/tolk/language-guide",
974+
"destination": "languages/tolk/basic-syntax",
925975
"permanent": true
926976
},
927977
{
928978
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short",
929-
"destination": "/languages/tolk/from-func/in-short",
979+
"destination": "/languages/tolk/from-func/tolk-vs-func",
930980
"permanent": true
931981
},
932982
{
933983
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail",
934-
"destination": "/languages/tolk/from-func/in-detail",
984+
"destination": "/languages/tolk/from-func/tolk-vs-func",
935985
"permanent": true
936986
},
937987
{
938988
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/mutability",
939-
"destination": "/languages/tolk/from-func/mutability",
989+
"destination": "/languages/tolk/syntax/mutability",
940990
"permanent": true
941991
},
942992
{
943993
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/stdlib",
944-
"destination": "/languages/tolk/from-func/stdlib",
994+
"destination": "/languages/tolk/from-func/stdlib-fc",
945995
"permanent": true
946996
},
947997
{
948998
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/pack-to-from-cells",
949-
"destination": "languages/tolk/from-func/pack",
999+
"destination": "languages/tolk/features/auto-serialization",
9501000
"permanent": true
9511001
},
9521002
{
9531003
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/create-message",
954-
"destination": "languages/tolk/from-func/create-message",
1004+
"destination": "languages/tolk/features/message-sending",
9551005
"permanent": true
9561006
},
9571007
{
9581008
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/lazy-loading",
959-
"destination": "languages/tolk/from-func/lazy-loading",
1009+
"destination": "languages/tolk/features/lazy-loading",
9601010
"permanent": true
9611011
},
9621012
{
@@ -3193,6 +3243,56 @@
31933243
"source": "/contract-dev/using-onchain-libraries",
31943244
"destination": "/contract-dev/using-on-chain-libraries",
31953245
"permanent": true
3246+
},
3247+
{
3248+
"source": "/languages/tolk/from-func/in-short",
3249+
"destination": "/languages/tolk/from-func/tolk-vs-func",
3250+
"permanent": true
3251+
},
3252+
{
3253+
"source": "/languages/tolk/from-func/in-detail",
3254+
"destination": "/languages/tolk/from-func/tolk-vs-func",
3255+
"permanent": true
3256+
},
3257+
{
3258+
"source": "/languages/tolk/from-func/mutability",
3259+
"destination": "/languages/tolk/syntax/mutability",
3260+
"permanent": true
3261+
},
3262+
{
3263+
"source": "/languages/tolk/from-func/stdlib",
3264+
"destination": "/languages/tolk/from-func/stdlib-fc",
3265+
"permanent": true
3266+
},
3267+
{
3268+
"source": "/languages/tolk/from-func/create-message",
3269+
"destination": "/languages/tolk/features/message-sending",
3270+
"permanent": true
3271+
},
3272+
{
3273+
"source": "/languages/tolk/from-func/lazy-loading",
3274+
"destination": "/languages/tolk/features/lazy-loading",
3275+
"permanent": true
3276+
},
3277+
{
3278+
"source": "/languages/tolk/from-func/pack",
3279+
"destination": "/languages/tolk/features/auto-serialization",
3280+
"permanent": true
3281+
},
3282+
{
3283+
"source": "/languages/tolk/environment-setup",
3284+
"destination": "/languages/tolk/overview",
3285+
"permanent": true
3286+
},
3287+
{
3288+
"source": "/languages/tolk/counter-smart-contract",
3289+
"destination": "/languages/tolk/overview",
3290+
"permanent": true
3291+
},
3292+
{
3293+
"source": "/languages/tolk/language-guide",
3294+
"destination": "/languages/tolk/overview",
3295+
"permanent": true
31963296
}
31973297
]
31983298
}

‎extra.css‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,3 +75,57 @@ table {
7575
div[data-component-part="callout-content"]>.code-block:last-child {
7676
margin-bottom: 0;
7777
}
78+
79+
/*
80+
A temporary solution syntax highlighting of Tolk snippets: invoke Prism.js on a client-side.
81+
See `snippets/tolk-highlight.jsx`.
82+
@link https://github.com/ton-org/docs/issues/1473
83+
*/
84+
85+
:root {
86+
--tolk-token-comment: #808080;
87+
--tolk-token-type-hint: #D500EC;
88+
--tolk-token-keyword: #0000FF;
89+
--tolk-token-struct: #007EA2;
90+
--tolk-token-variable: #444444;
91+
--tolk-token-attr-name: #808000;
92+
--tolk-token-function: #A82D2D;
93+
--tolk-token-number: #0B9000;
94+
--tolk-token-string: #008000;
95+
--tolk-token-string-bg: #FAF9EF;
96+
--tolk-token-operator: #A0A000;
97+
--tolk-token-punctuation: #808000;
98+
--tolk-token-three-dots: #999999;
99+
}
100+
101+
code.language-tolk { color: var(--tolk-token-variable); }
102+
.token.comment { color: var(--tolk-token-comment); font-style: italic; }
103+
.token.type-hint { color: var(--tolk-token-type-hint); }
104+
.token.boolean { color: var(--tolk-token-keyword); }
105+
.token.keyword { color: var(--tolk-token-keyword); }
106+
.token.self { color: var(--tolk-token-variable); font-weight: bold; }
107+
.token.attr-name { color: var(--tolk-token-attr-name); }
108+
.token.function { color: var(--tolk-token-function); }
109+
.token.number { color: var(--tolk-token-number); }
110+
.token.string { color: var(--tolk-token-string); background-color: var(--tolk-token-string-bg); }
111+
.token.operator { color: var(--tolk-token-operator); }
112+
.token.punctuation { color: var(--tolk-token-punctuation); }
113+
.token.three-dots { color: var(--tolk-token-three-dots); }
114+
.token.struct { color: var(--tolk-token-struct); }
115+
.token.variable { color: var(--tolk-token-variable); }
116+
117+
html.dark {
118+
--tolk-token-comment: #808080;
119+
--tolk-token-type-hint: #DF90F8;
120+
--tolk-token-keyword: #D75F02;
121+
--tolk-token-struct: #56C1FF;
122+
--tolk-token-variable: #C5D2E0;
123+
--tolk-token-attr-name: #808000;
124+
--tolk-token-function: #F9B900;
125+
--tolk-token-number: #33A033;
126+
--tolk-token-string: #33A033;
127+
--tolk-token-string-bg: #1B1C1E;
128+
--tolk-token-operator: #A0A000;
129+
--tolk-token-punctuation: #85B2A0;
130+
--tolk-token-three-dots: #777777;
131+
}

0 commit comments

Comments
 (0)