* show() documented

* tuples documented
* automatic tuple unpacking documented

package.json

@@ -13,7 +13,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@hyperionbt/helios": "^0.16.1",
+    "@hyperionbt/helios": "^0.16.4",
     "@jsdoc/ast": "^0.2.1",
     "@jsdoc/parse": "^0.3.1",
     "helios": "^0.0.5",

src/lang/builtins/address.md

@@ -77,6 +77,14 @@ Address != Address -> Bool
 address.serialize() -> ByteArray
 ```
 
+### `show`
+
+Alias for [`to_hex`](#to_hex).
+
+```helios
+address.show() -> String
+```
+
 ### `to_bytes`
 
 Returns the raw address bytes (see [CIP 19](https://cips.cardano.org/cips/cip19/)). [`IS_TESTNET`](../../api/reference/namespaces/config.md#is_testnet) must be set to `false` for this to return a raw mainnet addresses.
@@ -89,6 +97,6 @@ address.to_bytes() -> ByteArray
 
 Encodes the raw address bytes as a hexadecimal `String` (see [CIP 19](https://cips.cardano.org/cips/cip19/)). [`IS_TESTNET`](../../api/reference/namespaces/config.md#is_testnet) must be set to `false` for this to return a raw mainnet addresses.
 
-```
+```helios
 address.to_hex() -> String
 ```

src/lang/builtins/assetclass.md

@@ -63,4 +63,12 @@ AssetClass != AssetClass -> Bool
 
 ```helios
 asset_class.serialize() -> ByteArray
+```
+
+### `show`
+
+Returns the hexadecimal representation of the `MintingPolicyHash` and the token name, separated by a period (`.`).
+
+```helios
+asset_class.show() -> String
 ```

src/lang/builtins/duration.md

@@ -143,3 +143,11 @@ Duration % Duration -> Duration
 ```helios
 duration.serialize() -> ByteArray
 ```
+
+### `show`
+
+Returns the string representation of the `Duration` in milliseconds.
+
+```helios
+duration.show() -> String
+```

src/lang/builtins/list.md

@@ -292,6 +292,14 @@ Creates a new list, replacing an item at an `index`. Throws an error if the `ind
 list.set(index: Int, item: ItemType) -> []ItemType
 ```
 
+### `show`
+
+Returns a string representation of the list and its content. This can be useful for debugging.
+
+```helios
+list.show() -> String
+```
+
 ### `sort`
 
 Sorts the list using insertion sort.

src/lang/builtins/map.md

@@ -252,6 +252,14 @@ Sets the first entry with given key to a new value. This entry is appended to en
 map.set(key: KeyType, value: ValueType) -> Map[KeyType]ValueType
 ```
 
+### `show`
+
+Returns a string representation of the map and its content. This can be useful for debugging.
+
+```helios
+map.show() -> String
+```
+
 ### `sort`
 
 Sorts the map using insertion sort. The comparison function should return `true` if `a` and `b` are in the correct order.

src/lang/builtins/option.md

@@ -66,6 +66,14 @@ option.map[NewSomeType](
 option.serialize() -> ByteArray
 ```
 
+### `show`
+
+Returns a string representation of the option, and, in case of `Some`, its content. This can be useful for debugging.
+
+```helios
+option.show() -> String
+```
+
 ### `unwrap`
 
 Returns the value wrapped by `Some`. Throws an error if `None`.

src/lang/builtins/string.md

@@ -14,6 +14,14 @@ string: String = "Woah!"; ...
 String::from_data(data: Data) -> String
 ```
 
+### `is_valid_utf8`
+
+Method that checks if a `ByteArray` contains a valid utf-8 encoded string.
+
+```helios
+String::is_valid_utf8(bytes: ByteArray) -> Bool
+```
+
 ## Operators
 
 ### `==`
@@ -38,32 +46,40 @@ String + String -> String
 
 ## Methods
 
-### `serialize`
+### `encode_utf8`
+
+Turns a `String` into a sequence of utf-8 bytes.
 
 ```helios
-string.serialize() -> ByteArray
+string.encode_utf() -> ByteArray
 ```
 
-### `encode_utf8`
+### `ends_with`
 
-Turns a `String` into a sequence of utf-8 bytes.
+Checks if a `String` ends with a given suffix.
 
 ```helios
-string.encode_utf() -> ByteArray
+string.ends_with(suffix: String) -> Bool
 ```
 
-### `starts_with`
+### `serialize`
 
-Checks if a `String` starts with a given prefix.
+```helios
+string.serialize() -> ByteArray
+```
+
+### `show`
+
+Returns the string wrapped with quotes. This is useful when debugging.
 
 ```helios
-string.starts_with(prefix: String) -> Bool
+string.show() -> String
 ```
 
-### `ends_with`
+### `starts_with`
 
-Checks if a `String` ends with a given suffix.
+Checks if a `String` starts with a given prefix.
 
 ```helios
-string.ends_with(suffix: String) -> Bool
+string.starts_with(prefix: String) -> Bool
 ```

src/lang/builtins/timerange.md

@@ -84,12 +84,6 @@ TimeRange != TimeRange -> Bool
 
 ## Methods
 
-### `serialize`
-
-```helios
-time_range.serialize() -> ByteArray
-```
-
 ### `contains`
 
 Returns `true` if a `TimeRange` contains the given time.
@@ -114,6 +108,12 @@ Returns `true` if the start of a `TimeRange` is after the given time. Always ret
 time_range.is_after(time: Time) -> Bool
 ```
 
+### `serialize`
+
+```helios
+time_range.serialize() -> ByteArray
+```
+
 ### `show`
 
 ```helios

src/lang/container-types.md

@@ -4,6 +4,7 @@ Helios has 3 **container** types:
   * List (linked list)
   * `Map` (association list of key-value pairs)
   * `Option` (equivalent to `Maybe` in Haskell)
+  * Tuple (fixed list with heterogenous item types)
 
 
 ## List
@@ -67,6 +68,36 @@ Option[Int]::Some{my_int} = option; ...
 
 More information about `Option` can be found [here](./builtins/option.md).
 
+## Tuple
+
+A tuple is a collection of two or more items which can have different types.
+
+```helios
+my_tuple = (1, "hello", true)
+```
+
+Tuples are convenient when returning multiple values from a function:
+
+```helios
+func my_pair(a: Int) -> (Int, Int) {
+    (a+1, a+2)
+}
+```
+
+Tuples can contain anything, including functions. The contents of a tuple can be accessed through destructuring, or via getters:
+
+```helios
+(my_number: Int, my_string: String, my_bool: Bool) = my_tuple;
+
+my_number_alt: Int = my_tuple.first;
+my_string_alt: String = my_tuple.second;
+my_bool_alt: Bool = my_tuple.third
+```
+
+> **Note**: tuples in Helios are limited to 5 entries. The getters are named `first`, `second`, `third`, `fourth` and `fifth`.
+
+> **Note**: although tuples can be used as fields in structs/enums this is not recommended as it can become unclear what the meaning is of the tuples items, and there is also a performance penalty to doing so.
+
 ## Nested literal constructors
 
 If a literal List, `Map`, or `Option` contains other literal constructors, the types of those literal constructors can be omitted.

src/lang/functions/multiple_return_values.md

@@ -1,14 +1,14 @@
 # Multiple return values
 
-A Helios function can return multiple values:
+A Helios function can return multiple values using [tuples](../container-types.md#tuple):
 
 ```helios
 func swap(a: Int, b: Int) -> (Int, Int) {
     (b, a)
 }
 ```
 
-You can assign to multiple return values:
+You can assign to multiple return values using tuple destructuring:
 
 ```helios
 (a: Int, b: Int) = swap(10, 20); ... // a==20 && b==10
@@ -18,4 +18,12 @@ Some of the multiple return values can be discarded with an underscore (`_`):
 
 ```helios
 (a: Int, _) = swap(10, 20); ...
+```
+
+## Automatic unpacking of tuples
+
+Tuples are automatically unpacked during a function call, in a way that matches the type signature of the function being called:
+
+```helios
+(a: Int, b: Int) = swap(swap(10, 20)); // a==10 && b==20
 ```

src/lang/functions/named_arguments.md

@@ -10,6 +10,6 @@ func sub(a: Int, b: Int) -> Int {
 sub(b: 1, a: 2) // == 1
 ```
 
-Named arguments can't be mixed with positional arguments.
+A function call can't mix named arguments with positional arguments.
 
 Named arguments are mostly used when calling the [`copy()`](../user-defined-types/methods/automatic-methods.md#copy) method.

src/lang/user-defined-types/methods/automatic-methods.md

@@ -47,4 +47,14 @@ The `serialize` method is automatically defined on every user-type, and thus `se
 my_instance.serialize() -> ByteArray
 ```
 
-> **Note**: when debugging you can inspect the output of `print(my_data.serialize().show())` using [this cbor tool](https://cbor.nemo157.com).
+> **Note**: when debugging you can inspect the output of `print(x.serialize().show())` using [this cbor tool](https://cbor.nemo157.com).
+
+## `show`
+
+The `show` method returns a string representation of underlying instance, which is convenient when debugging.
+
+```helios
+my_instance.show() -> String
+```
+
+> **Note**: usually you will use `print(x.show())` instead `print(x.serialize().show())` when debugging.