Merging JSLigo v2 in stable

gitlab-pages/docs/advanced/attributes-decorators.md

@@ -0,0 +1,187 @@
+---
+id: decorators
+title: Attributes or Decorators
+---
+
+import Syntax from '@theme/Syntax';
+
+<Syntax syntax="cameligo">
+
+# Attributes
+
+Attributes (also known as "decorators" in JsLIGO, annotations or pragmas in other languages) are markers that can affect how the code immediately after is compiled or interpreted. Depending on the attribute, that code can be a definition, variable, statement block and so on. The sections below describe the attributes supported by CameLIGO.
+
+It is possible to specify multiple attributes as follows:
+
+```cameligo
+type storage = int
+type result = operation list * storage
+
+[@entry] [@no_mutation]
+let sub (delta : int) (store : storage) : result =
+  [], store - delta
+```
+
+## @entry to mark a function as a Smart Contract entrypoint
+
+The `@entry` attribute is used to indicate that a function should be available as an entrypoint of the smart contract. It is essentially declaring that function as one of the several "main" functions. For more information, see [Entrypoints](../syntax/contracts/entrypoints).
+
+## @dyn_entry to mark a function as a dynamic entrypoint
+
+The `@dyn_entry` attribute is used to indicate that a function should be available as a dynamic entrypoint of the smart contract. Dynamic entrypoints can be removed or updated without deploying a new contract, unlike entrypoints marked with `@entry`, which cannot be modified after the contract is originated. Dynamic entrypoints can be used for example to implement a DAO (Decentralized Autonomous Organization) with a built-in update mechanism that allows participants to vote on upgrades to the contract, somewhat akin to the process which allows to amend the Tezos protocol. For more information, see [Dynamic entrypoints](../syntax/contracts/dynamic-entrypoints.md).
+
+## @inline to ensure a function is inlined at its call sites
+
+The `@inline` attribute indicates that the code of the function it annotates must be inlined wherever it is called. This allows some optimizations to be performed, possibly at the expense of a larger compiled code. Benchmarks and profiling can help decide whether a function should be inlined or nor. For more information, see [Inlining](../syntax/functions#inlining).
+
+## @view to mark a function as a Smart Contract on-chain view
+
+Views are a form of read-only entrypoints, that can be called synchronously. For more information, see [LIGO views](../syntax/contracts/views).
+
+## @no_mutation
+
+See [the documentation on mutation testing](../testing/mutation-testing.md#preventing-mutation).
+
+## @private to prevent an identifier from being accessed outside of its defining module
+
+The `[@private]` decorator can be used on a top-level declaration, to prevent that value from being used outside the declaring module.
+
+```cameligo group=module-with-private
+(* This is gitlab-pages/docs/advanced/src/attributes-decorators/module-with-private.mligo *)
+[@private] let stuff = 42
+[@private] let g x = x * stuff
+let f x = (g x) + 1
+```
+
+```cameligo group=import-module-with-private
+module ModuleWithPrivate =
+  Gitlab_pages.Docs.Advanced.Src.Attributes_decorators.Module_with_private
+
+(* foo = 5167 = (123 * 42) + 1 *)
+let foo = ModuleWithPrivate.f 123
+
+(*
+  The following lines cause errors because g and stuff are private:
+
+  let bad_1 = ModuleWithPrivate.g 123
+  let bad_2 = ModuleWithPrivate.stuff
+*)
+```
+
+## @annot to ornate the generated code with Michelson annotations
+
+This attribute can be used to choose the name of the Michelson equivalent of record fields or variant constructors. By default, a variant is compiled to a comb of Michelson `or`, and each leaf in the nested tree of `or` that corresponds to a constructor is annotated with that constructor's name. Similarly, a record is compiled to a comb of Michelson `pair`, and each leaf in the nested tree of `pair` that corresponds to a field is annotated with that field's name.
+
+Using `@annot`, the Michelson annotation for a given field or constructor can be customized. This is useful for interoperability, where a third-party program or contract expects specific Michelson annotations, even if the LIGO code might not use these names internally.
+
+For more information, see [Interop: Different Michelson annotations](../syntax/contracts/interop.md#different-michelson-annotations)?
+
+## @layout to specify the Michelson layout of composite data types (structures and variants)
+
+Michelson does not natively support records or variants. These have to be encoded using nested `pair`s or nested `or`s. Many tree representations could translate to the same linear sequence of fields or constructors. LIGO makes it possible to choose between a right comb which preserves the order or the fields or constructors as declared in the source code, and a left-balanced, alphabetically ordered binary tree. The attributes `[@layout comb]` and `[@layout tree]` can be placed before the `{ ... }` for records and before the first constructor or leading `|` for variants, in order to explicitly choose the desired layout.
+
+For more information, see [Interop: Michelson layout of LIGO data structures](../syntax/contracts/interop.md##michelson-layout-of-ligo-data-structures).
+
+## @tzip16_compatible to enable TZIP-16 storage checks
+
+The `@tzip16_compatible` attribute is used to indicate a storage variable that is expected to contain metadata compliant with [TZIP-16 specification](https://gitlab.com/tezos/tzip/-/blob/master/proposals/tzip-16/tzip-16.md). Values marked with this attribute are subject to automatic checks verifying that the storage indeed satisfies TZIP-16 rules.
+
+Note that at the moment there is no support for thus feature from the LIGO compiler; IDEs however can recognize the attribute and provide additional verification.
+
+The attribute works only on variables that are not functions. In case a function returning storage needs to be verified, one can create one or several sample storages out of it and apply the attribute to them.
+
+## Internal attributes
+
+Furthermore, the following attributes are used internally by the compiler, you may encounter them when exporting the AST after a certain compilation pass, but they should not appear in normal source code.
+
+* `@thunk`
+* `@hidden`
+* `@deprecated`
+
+</Syntax>
+
+<Syntax syntax="jsligo">
+
+# Decorators
+
+Decorators (also known as "attributes" in CameLIGO, annotations or pragmas in other languages) are markers that can affect how the code immediately after is compiled or interpreted. Depending on the decorator, that code can be a definition, variable, statement block and so on. The sections below describe the decorators supported by JsLIGO.
+
+It is possible to specify multiple decorators as follows:
+
+```jsligo
+type storage = int;
+type result = [list<operation>, storage];
+
+// @entry
+// @no_mutation
+const sub = (delta : int, store : storage) : result =>
+  [[], store - delta]
+```
+
+## @entry to mark a function as a Smart Contract entrypoint
+
+The `@entry` decorator is used to indicate that a function should be available as an entrypoint of the smart contract. It is essentially declaring that function as one of the several "main" functions. For more information, see [Entrypoints](../syntax/contracts/entrypoints).
+
+## @dyn_entry to mark a function as a dynamic entrypoint
+
+The `@dyn_entry` decorator is used to indicate that a function should be available as a dynamic entrypoint of the smart contract. Dynamic entrypoints can be removed or updated without deploying a new contract, unlike entrypoints marked with `@entry`, which cannot be modified after the contract is originated. Dynamic entrypoints can be used for example to implement a DAO (Decentralized Autonomous Organization) with a built-in update mechanism that allows participants to vote on upgrades to the contract, somewhat akin to the process which allows to amend the Tezos protocol. For more information, see [Dynamic entrypoints](../syntax/contracts/dynamic-entrypoints.md).
+
+## @inline to ensure a function is inlined at its call sites
+
+The `@inline` decorator indicates that the code of the function it annotates must be inlined wherever it is called. This allows some optimizations to be performed, possibly at the expense of a larger compiled code. Benchmarks and profiling can help decide whether a function should be inlined or nor. For more information, see [Inlining](../syntax/functions#inlining).
+
+## @view to mark a function as a Smart Contract on-chain view
+
+Views are a form of read-only entrypoints, that can be called synchronously. For more information, see [LIGO views](../syntax/contracts/views).
+
+## @no_mutation
+
+See [the documentation on mutation testing](../testing/mutation-testing.md#preventing-mutation).
+
+## @private to prevent an identifier from being accessed outside of its defining module
+
+This decorator is meant to be used in CameLIGO, where definitions are public/exported by default. It has no use in JsLIGO.
+
+## @annot to ornate the generated code with Michelson annotations
+
+This decorator can be used to choose the name of the Michelson equivalent of record fields or variant constructors. By default, a variant is compiled to a comb of Michelson `or`, and each leaf in the nested tree of `or` that corresponds to a constructor is annotated with that constructor's name. Similarly, a record is compiled to a comb of Michelson `pair`, and each leaf in the nested tree of `pair` that corresponds to a field is annotated with that field's name.
+
+Using `@annot`, the Michelson annotation for a given field or constructor can be customized. This is useful for interoperability, where a third-party program or contract expects specific Michelson annotations, even if the LIGO code might not use these names internally.
+
+For more information, see [Interop: Different Michelson annotations](../syntax/contracts/interop.md#different-michelson-annotations)?
+
+## @layout to specify the Michelson layout of composite data types (structures and variants)
+
+Michelson does not natively support objects or variants. These have to be encoded using nested `pair`s or nested `or`s. Many tree representations could translate to the same linear sequence of fields or constructors. LIGO makes it possible to choose between a right comb which preserves the order or the fields or constructors as declared in the source code, and a left-balanced, alphabetically ordered binary tree. The decorators `@layout("comb")` and `@layout("tree")` can be placed before the `{ ... }` for objects and before the first constructor or leading `|` for variants, in order to explicitly choose the desired layout.
+
+For more information, see [Interop: Michelson layout of LIGO data structures](../syntax/contracts/interop.md##michelson-layout-of-ligo-data-structures).
+
+## @tzip16_compatible to enable TZIP-16 storage checks
+
+The `@tzip16_compatible` decorator is used to indicate a storage variable that is expected to contain metadata compliant with [TZIP-16 specification](https://gitlab.com/tezos/tzip/-/blob/master/proposals/tzip-16/tzip-16.md). Values marked with this decorator are subject to automatic checks verifying that the storage indeed satisfies TZIP-16 rules.
+
+Note that at the moment there is no support for thus feature from the LIGO compiler; IDEs however can recognize the decorator and provide additional verification.
+
+The decorator works only on variables that are not functions. In case a function returning storage needs to be verified, one can create one or several sample constant storages out of it and apply the decorator to them.
+
+## export to mark an identifier as accessible outside its defining module
+
+This decorator is slightly different from the others in that it does not need `@` and simply appears as follows:
+
+```jsligo
+namespace MathPi {
+  export const pi_millionth_numerator : int = 3141593
+  export const pi_millionth_denominator : nat = 1000000 as nat
+}
+```
+
+## Internal decorators
+
+Furthermore, the following attributes are used internally by the compiler, you may encounter them when exporting the AST after a certain compilation pass, but they should not appear in normal source code.
+
+* `@thunk`
+* `@hidden`
+* `@public`
+* `@deprecated`
+
+</Syntax>

gitlab-pages/docs/advanced/code-injection.md

@@ -119,19 +119,19 @@ let main (action : parameter) (store : storage) : operation list * storage =
 
 <Syntax syntax="jsligo">
 
-```jsligo skip
+```jsligo group=never
 type parameter =
   ["Increment", int]
 | ["Extend", never];
 
 type storage = int;
 
-@entry
+// @entry
 function main (action: parameter, store: storage) : [list<operation>, storage] {
   let storage =
-    match(action, {
-      Increment: n => store + n,
-      Extend: k => (Michelson`{ NEVER }` as ((n: never) => int))(k)
+    $match(action, {
+      "Increment": n => store + n,
+      "Extend": k => (Michelson`{ NEVER }` as ((n: never) => int))(k)
     });
   return [[], storage];
 };
@@ -155,4 +155,3 @@ ligo compile contract --protocol nairobi --disable-michelson-typechecking gitlab
 > instruction `NEVER` directly from LIGO, using `Tezos.never`.
 
 <!-- updated use of entry -->
-

gitlab-pages/docs/advanced/global-constants.md

@@ -57,10 +57,10 @@ let main (_p : unit) (s : int) : operation list * int =
 <Syntax syntax="jsligo">
 
 ```jsligo group=global_call
-const c : ((_p : int) => int) = Tezos.constant("expruCKsgmUZjC7k8NRcwbcGbFSuLHv5rUyApNd972MwArLuxEZQm2")
+const c : (_p : int) => int = Tezos.constant("expruCKsgmUZjC7k8NRcwbcGbFSuLHv5rUyApNd972MwArLuxEZQm2")
 
-@entry
-let main = (_p : unit, s : int) : [list<operation>, int] =>
+// @entry
+const main = (_p : unit, s : int) : [list<operation>, int] =>
   [[], c(s)]
 ```
 
@@ -147,7 +147,7 @@ let main (p : string) (s : int) : operation list * int =
 const helper = ([s, x]: [string, int]) =>
   String.length(s) + x * 3 + 2;
 
-@entry
+// @entry
 const main = (p: string, s: int) : [list<operation>, int] =>
   [[], helper ([p, s])];
 ```
@@ -165,7 +165,7 @@ ligo compile constant cameligo "helper" --init-file ./gitlab-pages/docs/advanced
 # Michelson constant as JSON string:
 # "{ UNPAIR ;\n  PUSH int 2 ;\n  PUSH int 3 ;\n  DIG 3 ;\n  MUL ;\n  DIG 2 ;\n  SIZE ;\n  ADD ;\n  ADD }"
 # This string can be passed in `--constants` argument when compiling a contract.
-# 
+#
 # Remember to register it in the network, e.g.:
 # > tezos-client register global constant "{ UNPAIR ;
 #   PUSH int 2 ;
@@ -176,7 +176,7 @@ ligo compile constant cameligo "helper" --init-file ./gitlab-pages/docs/advanced
 #   SIZE ;
 #   ADD ;
 #   ADD }" from bootstrap1
-# 
+#
 # Constant hash:
 # exprv547Y7U5wKLbQGmkDU9Coh5tKPzvEJjyUed7px9yGt9nrkELXf
 ```
@@ -191,7 +191,7 @@ ligo compile constant jsligo "helper" --init-file ./gitlab-pages/docs/advanced/s
 # Michelson constant as JSON string:
 # "{ UNPAIR ;\n  PUSH int 2 ;\n  PUSH int 3 ;\n  DIG 3 ;\n  MUL ;\n  DIG 2 ;\n  SIZE ;\n  ADD ;\n  ADD }"
 # This string can be passed in `--constants` argument when compiling a contract.
-# 
+#
 # Remember to register it in the network, e.g.:
 # > tezos-client register global constant "{ UNPAIR ;
 #   PUSH int 2 ;
@@ -202,7 +202,7 @@ ligo compile constant jsligo "helper" --init-file ./gitlab-pages/docs/advanced/s
 #   SIZE ;
 #   ADD ;
 #   ADD }" from bootstrap1
-# 
+#
 # Constant hash:
 # exprv547Y7U5wKLbQGmkDU9Coh5tKPzvEJjyUed7px9yGt9nrkELXf
 ```
@@ -241,7 +241,7 @@ references to `helper` by
 <Syntax syntax="jsligo">
 
 ```
-(Tezos.constant("exprv547Y7U5wKLbQGmkDU9Coh5tKPzvEJjyUed7px9yGt9nrkELXf") as ((_ps : [string, int]) => int))
+(Tezos.constant("exprv547Y7U5wKLbQGmkDU9Coh5tKPzvEJjyUed7px9yGt9nrkELXf") as (_ps : [string, int]) => int)
 ```
 
 </Syntax>
@@ -261,7 +261,7 @@ let main (p : string) (s : int) : operation list * int =
 <Syntax syntax="jsligo">
 
 ```jsligo group=global_call_2
-@entry
+// @entry
 const main = (p: string, s: int) : [list<operation>, int] =>
   [ [], Tezos.constant("exprv547Y7U5wKLbQGmkDU9Coh5tKPzvEJjyUed7px9yGt9nrkELXf")([p, s]) ];
 ```
@@ -340,7 +340,7 @@ The string returned by `Test.register_constant` can be used via
 `Tezos.constant`, as in the examples above.
 
 A simple usage case is the following, in which we obtain a
-`michelson_program` by using `Test.eval`:
+`michelson_program` by using `Test.Michelson.eval`:
 
 <Syntax syntax="cameligo">
 
@@ -352,41 +352,41 @@ module C = struct
 
   let f (x : int) = x * 3 + 2
 
-  let ct = Test.register_constant (Test.eval f)
+  let ct = Test.State.register_constant (Test.Michelson.eval f)
 
   [@entry]
   let main (() : parameter) (store : storage) : return =
-    [], (Tezos.constant ct store)
+    [], Tezos.constant ct store
 end
 
 let test =
-  let orig = Test.originate (contract_of C) 1 0tez in
-  let _ = Test.transfer_exn orig.addr (Main ()) 0tez in
-  assert (Test.get_storage orig.addr = 5)
+  let orig = Test.Originate.contract (contract_of C) 1 0tez in
+  let _ = Test.Typed_address.transfer_exn orig.taddr (Main ()) 0tez in
+  Assert.assert (Test.Typed_address.get_storage orig.taddr = 5)
 ```
 
 </Syntax>
 
 <Syntax syntax="jsligo">
 
 ```jsligo test-ligo group=test_global
-namespace C {
-  type storage = int
-  type parameter = unit
+type storage = int;
+type parameter = unit;
 
-  const f = (x : int) => x * 3 + 2;
+class C {
+  static f = (x : int) => x * 3 + 2;
 
-  const ct = Test.register_constant(Test.eval(f));
+  static ct = Test.State.register_constant(Test.Michelson.eval(f));
 
   @entry
-  const main = (p: parameter, s: storage) : [list<operation>, storage] =>
+  main = (_p: parameter, s: storage) : [list<operation>, storage] =>
     [[], Tezos.constant(ct)(s)];
 }
 
 const _test = () => {
-  let orig = Test.originate(contract_of(C), 1, 0tez);
-  Test.transfer_exn(orig.addr, Main(unit), 0tez);
-  assert (Test.get_storage(orig.addr) == 5);
+  let orig = Test.Originate.contract(contract_of(C), 1, 0 as tez);
+  Test.Typed_address.transfer_exn(orig.taddr, ["Main" as "Main"], 0 as tez);
+  Assert.assert (Test.Typed_address.get_storage(orig.taddr) == 5);
 };
 
 const test = _test();

gitlab-pages/docs/advanced/include.md

@@ -0,0 +1,33 @@
+---
+id: include
+title: Including Other Contracts
+---
+
+import Syntax from '@theme/Syntax';
+
+<Syntax syntax="cameligo">
+
+Let us say that we have a contract that is getting a too large. If it
+has a modular structure, you might find it useful to use the
+`#include` statement to split the contract up over multiple files.
+
+You take the code that you want to include and put it in a separate
+file, for example the contract names `included`:
+
+```cameligo group=included
+(* This is "included.mligo" *)
+(* Demonstrate CameLIGO inclusion statements, see includer.mligo *)
+
+let foo = 144
+```
+
+And then you can include this code using the `#include` statement like
+so:
+
+```cameligo
+#include "gitlab-pages/docs/advanced/src/include/included.mligo"
+
+let bar = foo
+```
+
+</Syntax>