[Tolk] The magic lazy keyword

Lazy loading, partial loading, partial updating
See pipe-lazy-load-insertions.cpp for comments

Author: tolk-vm

crypto/smartcont/tolk-stdlib/common.tolk

@@ -233,15 +233,17 @@ struct PackOptions {
 
 /// UnpackOptions allows you to control behavior of `MyStruct.fromCell(c)` and similar functions.
 struct UnpackOptions {
-    // after finished reading all fields from a cell/slice, call [slice.assertEnd] to ensure no remaining data left;
-    // it's the default behavior, it ensures that you've fully described data you're reading with a struct;
-    // example: `struct Point { x: int8; y: int8 }`, input "0102" is ok, "0102FF" will throw excno 9;
-    // note: setting this to false does not decrease gas (DROP from a stack and ENDS cost the same);
-    // note: this option controls [T.fromCell] and [T.fromSlice], but is ignored by [slice.loadAny]
+    /// after finished reading all fields from a cell/slice, call [slice.assertEnd] to ensure no remaining data left;
+    /// it's the default behavior, it ensures that you've fully described data you're reading with a struct;
+    /// example: `struct Point { x: int8; y: int8 }`, input "0102" is ok, "0102FF" will throw excno 9;
+    /// note: setting this to false does not decrease gas (DROP from a stack and ENDS cost the same);
+    /// note: this option controls [T.fromCell] and [T.fromSlice], but is ignored by [slice.loadAny];
+    /// note: `lazy` ignores this option, because it reads fields on demand or even skips them
     assertEndAfterReading: bool = true,
 
     /// this excNo is thrown if a prefix doesn't match, e.g. for `struct (0x01) A` given input "88...";
-    /// similarly, for a union type, this is thrown when none of the opcodes match
+    /// similarly, for a union type, this is thrown when none of the opcodes match;
+    /// note: `lazy` ignores this option if you have `else` in `match` (you write custom logic there)
     throwIfOpcodeDoesNotMatch: int = 63,
 }
 
@@ -327,6 +329,26 @@ fun T.getDeclaredPackPrefix(): int
 fun T.getDeclaredPackPrefixLen(): int
     builtin;
 
+/// Forces an object created by `lazy` to load fully. Returns the remaining slice (having read all fields).
+/// Since `options.assertEndAfterReading` is ignored by `lazy` (fields are loaded on demand),
+/// this method can help you overcome this, if you really need to check input consistency.
+/// Example:
+/// ```
+/// val msg = lazy CounterMessage.fromSlice(s);
+/// match (msg) {     // it's a lazy match, without creating a union on the stack
+///     CounterIncrement => {
+///         ...
+///         newCounter = curCounter + msg.incBy;   // `incBy` loaded here, on demand
+///         msg.forceLoadLazyObject().assertEnd()  // the purpose: get remainder
+///     }
+/// }
+/// ```
+/// Note: while [slice.assertEnd] may seem reasonable, these checks are avoided in practice,
+/// because the purpose of `lazy` is to auto-detect and load only necessary fields, not up to the end.
+@pure
+fun T.forceLoadLazyObject(self): slice
+    builtin;
+
 /// Cell<T> represents a typed cell reference (as opposed to untyped `cell`).
 /// Example:
 /// ```

tolk-tester/tests/invalid-semantics/err-4460.tolk

@@ -0,0 +1,14 @@
+struct Point {
+    x: int8;
+    y: int8;
+}
+
+fun main() {
+    var p = lazy Point.fromSlice(stringHexToSlice("0A14"));
+    p.asdf;
+}
+
+/**
+@compilation_should_fail
+@stderr field `asdf` doesn't exist in type `Point`
+ */

tolk-tester/tests/invalid-serialization/err-7300.tolk

@@ -0,0 +1,15 @@
+struct A { a1: int7; a2: int8; a3: int8; }
+struct B { b1: int7; b2: int8; b3: int8; }
+type AOrB = A | B;
+
+fun f() {
+    val o = lazy AOrB.fromSlice("");
+    __expect_lazy("");
+    return (o is A) ? o.a1 : o.b1;
+}
+
+/**
+@compilation_should_fail
+@stderr `lazy` will not work here, because variable `o` it's used in a non-lazy manner
+@stderr hint: lazy union may be used only in `match` statement
+ */

tolk-tester/tests/invalid-serialization/err-7301.tolk

@@ -0,0 +1,14 @@
+type Int32Or64 = int32 | int64;
+
+fun f() {
+    val o = lazy Int32Or64.fromSlice("");
+    match (o) {
+        int32 => return o + 1,
+        int64 => throw o,
+    }
+}
+
+/**
+@compilation_should_fail
+@stderr `lazy` union should contain only structures, but it contains `int32`
+ */

tolk-tester/tests/invalid-serialization/err-7302.tolk

@@ -0,0 +1,16 @@
+struct A{}
+type StructAndNot = A | int8;
+
+fun f() {
+    var o = lazy StructAndNot.fromSlice("");   // neg5
+    __expect_lazy("");
+    match (o) {
+        A => {}
+        int8 => {}
+    }
+}
+
+/**
+@compilation_should_fail
+@stderr `lazy` union should contain only structures, but it contains `int8`
+ */

tolk-tester/tests/invalid-serialization/err-7303.tolk

@@ -0,0 +1,11 @@
+type PairInt8 = (int8, int8);
+
+fun f() {
+    var i = lazy PairInt8.fromSlice(stringHexToSlice("0102"));
+    return (i.0, i.1);
+}
+
+/**
+@compilation_should_fail
+@stderr `lazy` is applicable to structs, not to `PairInt8`
+ */

tolk-tester/tests/invalid-serialization/err-7304.tolk

@@ -0,0 +1,22 @@
+struct Counter7Increment { byValue: int7 }
+struct Counter7Decrement { byValue: int7 }
+type MsgEitherCounter = Counter7Increment | Counter7Decrement;
+
+fun f(c: cell) {
+    // because 2 matches
+    var msg = lazy MsgEitherCounter.fromCell(c);   // neg8
+    var t = createEmptyTuple();
+    match (msg) {
+        Counter7Increment => {}
+        Counter7Decrement => {}
+    }
+    match (msg) {
+        Counter7Increment => {}
+        Counter7Decrement => {}
+    }
+}
+
+/**
+@compilation_should_fail
+@stderr `lazy` will not work here, because variable `msg` it's used in a non-lazy manner
+ */

tolk-tester/tests/invalid-serialization/err-7305.tolk

@@ -0,0 +1,19 @@
+struct Counter7Increment { byValue: int7 }
+struct Counter7Decrement { byValue: int7 }
+type MsgEitherCounter = Counter7Increment | Counter7Decrement;
+
+fun f() {
+    // because .toCell()
+    var msg = lazy MsgEitherCounter.fromSlice("");  // neg9
+    match (msg) {
+        Counter7Increment => {}
+        Counter7Decrement => {}
+    }
+    return msg.toCell();
+}
+
+/**
+@compilation_should_fail
+@stderr `lazy` will not work here, because variable `msg` it's used in a non-lazy manner
+@stderr lazy MsgEitherCounter
+ */

tolk-tester/tests/invalid-serialization/err-7306.tolk

@@ -0,0 +1,17 @@
+struct Counter7Increment { byValue: int7 }
+struct Counter7Decrement { byValue: int7 }
+type MsgEitherCounter = Counter7Increment | Counter7Decrement;
+
+fun f() {
+    // because in a complex expression
+    var msg = lazy MsgEitherCounter.fromSlice("");
+    match (msg) {
+        Counter7Increment => 1 as int32,
+        Counter7Decrement => 2 as int32,
+    }.toCell()
+}
+
+/**
+@compilation_should_fail
+@stderr `lazy` will not work here, because variable `msg` it's used in a non-lazy manner
+ */

tolk-tester/tests/invalid-serialization/err-7307.tolk

@@ -0,0 +1,17 @@
+struct Counter7Increment { byValue: int7 }
+struct Counter7Decrement { byValue: int7 }
+type MsgEitherCounter = Counter7Increment | Counter7Decrement;
+
+fun f() {
+    var msg = lazy MsgEitherCounter.fromSlice("");  // neg10
+    match (msg) {
+        Counter7Increment => 1 as int32,
+        Counter7Decrement => 2 as int32,
+        else => throw 123,      // not allowed in either
+    }
+}
+
+/**
+@compilation_should_fail
+@stderr `else` is unreachable, because this `match` has only two options (0/1 prefixes)
+ */