From 68dabc66432a8f84c5b0de58b66d65bccfb1e5ed Mon Sep 17 00:00:00 2001 From: Christian Schmitz Date: Wed, 8 Nov 2023 14:23:40 -0600 Subject: [PATCH] * show() documented * tuples documented * automatic tuple unpacking documented --- package-lock.json | 8 ++-- package.json | 2 +- src/lang/builtins/address.md | 10 ++++- src/lang/builtins/assetclass.md | 8 ++++ src/lang/builtins/duration.md | 8 ++++ src/lang/builtins/list.md | 8 ++++ src/lang/builtins/map.md | 8 ++++ src/lang/builtins/option.md | 8 ++++ src/lang/builtins/string.md | 38 +++++++++++++------ src/lang/builtins/timerange.md | 12 +++--- src/lang/container-types.md | 31 +++++++++++++++ src/lang/functions/multiple_return_values.md | 12 +++++- src/lang/functions/named_arguments.md | 2 +- .../methods/automatic-methods.md | 12 +++++- 14 files changed, 140 insertions(+), 27 deletions(-) diff --git a/package-lock.json b/package-lock.json index 34c5d00d..be7e6b83 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ "version": "1.0.0", "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", @@ -61,9 +61,9 @@ } }, "node_modules/@hyperionbt/helios": { - "version": "0.16.1", - "resolved": "https://registry.npmjs.org/@hyperionbt/helios/-/helios-0.16.1.tgz", - "integrity": "sha512-ztcY+yvSArrYZTgaj0iebdDSoTkvWZmQMZKUqmdhPCA14M+pAkQ9wr3afBf7tlYFnNnatEV7bCKbfuXgRQc51Q==" + "version": "0.16.4", + "resolved": "https://registry.npmjs.org/@hyperionbt/helios/-/helios-0.16.4.tgz", + "integrity": "sha512-dkpTh3L4MPCws2sN1e7pkI1Cc2qIqTPBOH+kXvAdizFZteYHmKe4/ikth/Owg2EiKsrshHsfokysA/cL3RgefQ==" }, "node_modules/@jsdoc/ast": { "version": "0.2.1", diff --git a/package.json b/package.json index 8cb5ae2b..3206cca8 100644 --- a/package.json +++ b/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", diff --git a/src/lang/builtins/address.md b/src/lang/builtins/address.md index 4345b6b2..5440e032 100644 --- a/src/lang/builtins/address.md +++ b/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 ``` \ No newline at end of file diff --git a/src/lang/builtins/assetclass.md b/src/lang/builtins/assetclass.md index 39281fa5..04c05f72 100644 --- a/src/lang/builtins/assetclass.md +++ b/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 ``` \ No newline at end of file diff --git a/src/lang/builtins/duration.md b/src/lang/builtins/duration.md index 08b62c8c..16385b38 100644 --- a/src/lang/builtins/duration.md +++ b/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 +``` \ No newline at end of file diff --git a/src/lang/builtins/list.md b/src/lang/builtins/list.md index 7098ae19..4a24f9d9 100644 --- a/src/lang/builtins/list.md +++ b/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. diff --git a/src/lang/builtins/map.md b/src/lang/builtins/map.md index 6ee0bad0..e9a3e102 100644 --- a/src/lang/builtins/map.md +++ b/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. diff --git a/src/lang/builtins/option.md b/src/lang/builtins/option.md index 16063f17..c6904ba8 100644 --- a/src/lang/builtins/option.md +++ b/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`. diff --git a/src/lang/builtins/string.md b/src/lang/builtins/string.md index a46bb307..fb143ec4 100644 --- a/src/lang/builtins/string.md +++ b/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 ``` \ No newline at end of file diff --git a/src/lang/builtins/timerange.md b/src/lang/builtins/timerange.md index 7d58500f..6deab0b0 100644 --- a/src/lang/builtins/timerange.md +++ b/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 diff --git a/src/lang/container-types.md b/src/lang/container-types.md index 6a2c1c17..81218dae 100644 --- a/src/lang/container-types.md +++ b/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. diff --git a/src/lang/functions/multiple_return_values.md b/src/lang/functions/multiple_return_values.md index 03209eaf..9aa44852 100644 --- a/src/lang/functions/multiple_return_values.md +++ b/src/lang/functions/multiple_return_values.md @@ -1,6 +1,6 @@ # 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) { @@ -8,7 +8,7 @@ func swap(a: Int, b: Int) -> (Int, Int) { } ``` -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 ``` \ No newline at end of file diff --git a/src/lang/functions/named_arguments.md b/src/lang/functions/named_arguments.md index 089155ae..632458b8 100644 --- a/src/lang/functions/named_arguments.md +++ b/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. \ No newline at end of file diff --git a/src/lang/user-defined-types/methods/automatic-methods.md b/src/lang/user-defined-types/methods/automatic-methods.md index a6bdfcf7..36ec8c65 100644 --- a/src/lang/user-defined-types/methods/automatic-methods.md +++ b/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. \ No newline at end of file