doc: Documents statements and expressions for declaring and accessing…

… variables
RomarQ · Mar 13, 2022 · f297cdb · f297cdb
1 parent 151611f
commit f297cdb
Show file tree

Hide file tree

Showing 7 changed files with 144 additions and 5 deletions.
diff --git a/documentation/docs/contract_api/entrypoint.md b/documentation/docs/contract_api/entrypoint.md
@@ -17,7 +17,7 @@ const contract = new Contract()
             ]);
     )
     .addEntrypoint(
-        new EntryPoint('entry_point_2').code((arg) => [
+        new EntryPoint('entry_point_2').code(() => [
             SetValue(ContractStorage(), GetLevel())
         ]);
     );

diff --git a/documentation/docs/expressions/serialization.md b/documentation/docs/expressions/serialization.md
@@ -2,7 +2,7 @@
 
 ## Serialize data
 
-Serializes any value of packable type to its optimized binary representation, of type `TBytes()`.
+The expression `Pack` serializes any value of packable type to its optimized binary representation, of type `TBytes()`.
 
 - [TypeDoc](https://romarq.github.io/smartts-sdk/api/modules/expression.html#Pack)
 
@@ -31,7 +31,7 @@ const contract = new Contract()
 
 ## Deserialize data
 
-Deserialize a value of type `TBytes()` into the corresponding Michelson value of type `TOption(...)`.
+The expression `Unpack` deserialize a value of type `TBytes()` into the corresponding Michelson value of type `TOption(...)`.
 
 - [TypeDoc](https://romarq.github.io/smartts-sdk/api/modules/expression.html#Unpack)
 

diff --git a/documentation/docs/expressions/variables.md b/documentation/docs/expressions/variables.md
@@ -0,0 +1,90 @@
+# Accessing Variables
+
+## Access a local variable
+
+The expression `GetVariable` is used to get the value stored in a local variable.
+
+- [TypeDoc](https://romarq.github.io/smartts-sdk/api/modules/expression.html#GetVariable)
+
+```ts
+const {
+    Contract,
+    EntryPoint,
+    SetValue,
+    NewVariable,
+    ContractStorage,
+    GetVariable,
+    TString,
+} = require('@tezwell/smartts-sdk');
+
+const contract = new Contract()
+    .setStorageType(TString())
+    .addEntrypoint(
+        new EntryPoint('entry_point_1')
+            .setInputType(TString())
+            .code((argument) => [
+                // let some_variable = "SOME_PREFIX_" + <argument>;
+                NewVariable("some_variable", Concat(["SOME_PREFIX_", argument])),
+                // <contract>.<storage> = some_variable
+                SetValue(ContractStorage(), GetVariable("some_variable"))
+            ]),
+    );
+```
+
+## Access the contract storage
+
+The expression `ContractStorage` is used to access the contract storage.
+
+- [TypeDoc](https://romarq.github.io/smartts-sdk/api/modules/expression.html#ContractStorage)
+
+```ts
+const {
+    Contract,
+    EntryPoint,
+    Require,
+    ContractStorage,
+    String,
+    TBool,
+} = require('@tezwell/smartts-sdk');
+
+const contract = new Contract()
+    .setStorageType(TBool())
+    .addEntrypoint(
+        new EntryPoint('entry_point_1').code(() => [
+            // The storage is a boolean that will be "true" only when the contract is active and false otherwise
+            Require(ContractStorage(), String("The contract is paused!")),
+        ]),
+    );
+```
+
+## Access the list of operations
+
+The expression `GetOperations` is used to get the operations list from the stack or an empty list otherwise.
+
+- [TypeDoc](https://romarq.github.io/smartts-sdk/api/modules/expression.html#GetOperations)
+
+```ts
+const {
+    Contract,
+    EntryPoint,
+    SetValue,
+    GetOperations,
+    SetDelegate,
+    PrependToList,
+    None
+} = require('@tezwell/smartts-sdk');
+
+const contract = new Contract()
+    .addEntrypoint(
+        new EntryPoint('entry_point_1').code(() => [
+            // Add a new operation to the stack
+            SetValue(
+                GetOperations(),
+                PrependToList(
+                    GetOperations(),
+                    SetDelegate(None()),
+                ),
+            ),
+        ]),
+    );
+```
diff --git a/documentation/docs/expressions/view.md b/documentation/docs/expressions/view.md
@@ -2,7 +2,7 @@
 
 ## Call an on-chain view
 
-Calls an on-chain view and returns an expression of type `TOption(<any>)`.
+The expression `CallView` calls an on-chain view and returns a result of type `TOption(<any>)`.
 
 - [TypeDoc](https://romarq.github.io/smartts-sdk/api/modules/expression.html#CallView)
 

diff --git a/documentation/docs/statements/variables.md b/documentation/docs/statements/variables.md
@@ -0,0 +1,44 @@
+# Declaring variables
+
+## NewVariable
+
+The statement `NewVariable` is used to declare local scoped variables.
+
+- [TypeDoc](https://romarq.github.io/smartts-sdk/api/modules/statement.html#NewVariable)
+
+```ts
+const {
+    Contract,
+    EntryPoint,
+    ContractStorage,
+    ForEachOf,
+    NewVariable,
+    SetValue,
+    Add,
+    PrependToList,
+    GetVariable,
+    TUnit,
+    List,
+    Nat
+} = require('@tezwell/smartts-sdk');
+
+const contract = new Contract()
+    // let <contract>.<storage> = [1, 2, 3];
+    .setStorage(List([Nat(1), Nat(2), Nat(3)]))
+    .addEntrypoint(
+        new EntryPoint('entry_point_1')
+            .setInputType(TUnit())
+            .code(() => [
+                // let sum = 0;
+                NewVariable("sum", Nat(0)),
+                // <contract>.<storage>.forEach((el) => {
+                //   sum += el;
+                // })
+                ForEachOf(ContractStorage()).Do((el) => [
+                    SetValue(GetVariable("sum"), Add(GetVariable("sum"), el))
+                ]),
+                // <contract>.<storage> = [...<contract>.<storage>, sum];
+                SetValue(ContractStorage(), PrependToList(ContractStorage(), GetVariable("sum")))
+            ])
+    );
+```
diff --git a/src/core/enums/expression.ts b/src/core/enums/expression.ts
@@ -66,6 +66,7 @@ export enum ExpressionAtom {
     getItemMessage = 'getItemMessage',
     attr = 'attr',
     params = 'params',
+    lambdaParams = 'lambdaParams',
     getLocal = 'getLocal',
     iter = 'iter',
     contract = 'contract',

diff --git a/src/expression/variables.ts b/src/expression/variables.ts
@@ -106,7 +106,11 @@ export const LambdaArgument = (
     argumentType = TUnknown(),
     id = LambdaLiteral.idCounter,
     line = new LineInfo(),
-) => proxy(new Expression<any>('lambdaParams', `${id}`, `"${name}"`, line, argumentType), Expression.proxyHandler);
+) =>
+    proxy(
+        new Expression<any>(ExpressionAtom.lambdaParams, `${id}`, `"${name}"`, line, argumentType),
+        Expression.proxyHandler,
+    );
 
 /**
  * Get operations list from the stack or an empty list otherwise.