diff --git a/docs/bindings.md b/docs/bindings.md index 57678a1..5314b2b 100644 --- a/docs/bindings.md +++ b/docs/bindings.md @@ -24,16 +24,55 @@ fn main(num: Int) -> Int { In this example, we declare two bindings to make the code more readable. These can be reused multiple times to avoid calculating the same value twice or writing duplicate code. +A binding must always have a value, since it can't be assigned later. The type is inferred from the value, but you can also specify it explicitly: + +```rue +fn main() -> List { + let items: List = [1, 2, 3]; + [0, ...items] +} +``` + +## Shadowing + +You can declare a new binding with the same name as an existing one. The new binding shadows the old one for the rest of the scope, but doesn't change it: + +```rue +fn main(value: Int) -> Int { + let value = value * 2; + let value = value + 1; + value * value +} +``` + +:::tip +If you'd rather avoid shadowing in your project, you can enable the `shadowed_binding` [lint](/docs/lints.md). +::: + +## Blocks + +A block is a group of statements surrounded by braces, which ends in an expression. It can be used anywhere an expression is expected, and bindings declared inside of it are only visible within the block: + +```rue +fn main() -> Int { + let value = { + let a = 34; + a * 2 + }; + value + 1 +} +``` + ## Inline Bindings You can mark a `let` binding as `inline`, which forces its value to be inserted everywhere it's referenced rather than being defined a single time and reused. -As an example, this will insert `num * num` multiple times, rather than computing it once up front: +As an example, this will insert `num * num` twice, rather than computing it once up front: ```rue fn main(num: Int) -> Int { inline let squared = num * num; - square + squared + squared + squared } ``` @@ -43,23 +82,53 @@ This should be used sparingly, since it can come with either a performance hit, The compiler will automatically inline `let` bindings if they are only referenced a single time. ::: +## Unused Bindings + +The compiler warns about bindings and parameters that are never used. If a binding or parameter is intentionally unused (for example, a parameter that's only there to match the layout of a solution), you can prefix its name with an underscore to silence the warning (see [Unused Code](/docs/lints.md#unused-code)): + +```rue +fn main(_unused: Int, value: Int) -> Int { + value +} +``` + ## Destructuring -You can destructure values (including `let` bindings and function parameters) into multiple bindings at once. +You can destructure values (including `let` bindings, function parameters, and lambda parameters) into multiple bindings at once. For example, if you have a pair, you can destructure the first and rest values into separate bindings: ```rue -let (first, rest) = (100, 200); +fn main() -> Int { + let (first, rest) = (100, 200); + first + rest +} ``` -This also works for lists (as long as the values are known to not be nil): +This also works for lists (as long as the values are known to not be nil). You can use the spread operator to bind the rest of the list: ```rue -let [a, b, c] = [100, 200, 300]; +fn main() -> Int { + let [a, b, ...rest] = [100, 200, 300, 400]; + a + b + sum(rest) +} +``` + +If you have a struct, you can destructure the fields by name, and rename them with a `:`: + +```rue +struct Point { + x: Int, + y: Int, +} + +fn main() -> Int { + let { x, y: vertical } = Point { x: 100, y: 200 }; + x + vertical +} ``` -If you have a struct, you can destructure the fields: +In a struct pattern, a spread binding (such as `...point`) binds the whole value, so that you can still access the fields you didn't destructure: ```rue struct Point { @@ -67,13 +136,23 @@ struct Point { y: Int, } -let { x, y } = Point { x: 100, y: 200 }; +fn add_x({ x, ...point }: Point) -> Int { + x + point.y +} ``` These destructuring patterns can be combined arbitrarily: ```rue -let ([a, b, c], { x, y }) = ([100, 200, 300], Point { x: 400, y: 500 }); +struct Point { + x: Int, + y: Int, +} + +fn main() -> Int { + let ([a, b, c], { x, y }) = ([100, 200, 300], Point { x: 400, y: 500 }); + a + b + c + x + y +} ``` :::note diff --git a/docs/builtins.md b/docs/builtins.md index 1f1ac30..5239e33 100644 --- a/docs/builtins.md +++ b/docs/builtins.md @@ -4,7 +4,9 @@ slug: /builtins # Builtins -There are a number of built-in functions and types. These are intrinsic to the language and are used to implement the standard library, but can and should also be used in your code. +There are a number of built-in types, functions, and constants. These are intrinsic to the language and are used to implement the [standard library](/docs/standard-library.md), but can and should also be used in your code. Unlike the standard library, builtins are always available, even with `std = false`. + +Most builtin functions compile directly to a CLVM operator. They can only be called directly, rather than being used as a value. ## Types @@ -26,226 +28,251 @@ You can click on each of these types to go to their corresponding page and learn 14. [**List**](/docs/type-system/pairs.md#lists) 15. [**AlternatingList**](/docs/type-system/pairs.md#alternating-lists) -## Functions +## Constants -### `sha256` +| Constant | Type | Description | +| ------------- | ----------- | ----------------------------------------------------------------- | +| `INFINITY_G1` | `PublicKey` | The BLS G1 point at infinity, which is the identity for addition. | +| `INFINITY_G2` | `Signature` | The BLS G2 point at infinity, which is the identity for addition. | -Calculates the [SHA-256](https://en.wikipedia.org/wiki/SHA-2) hash of the bytes provided. While this hashes the value at runtime, there is also a `sha256_inline` builtin that allows you to hash a constant value at compile time and insert the result into the program. Its use is discouraged (because hard coding 32 bytes is costly in CLVM) unless you have a very large constant value that you want to avoid hashing multiple times. +## Casting -For example: +### `unchecked_cast` + +Changes the type of a value to the given type, without any checks. See [Unchecked Casts](/docs/type-system/casting.md#unchecked-casts). ```rue -let hash = sha256("hello"); +fn main(value: Any) -> Int { + unchecked_cast::(value) +} ``` -There's also a variant with the spread syntax that allows you to hash a list of arguments that is computed at runtime (rather than a static list): +## Hashing + +### `sha256` + +Calculates the [SHA-256](https://en.wikipedia.org/wiki/SHA-2) hash of the bytes provided. ```rue -let hash = sha256(...list); +fn main() -> Bytes32 { + sha256("hello") +} ``` -Note that this prevents the compiler from being able to fold the arguments into a constant at compile time. However, it saves CLVM cost by not having to recursively concatenate the arguments. +There's also a variant with the spread syntax that allows you to hash the concatenation of a list of values that is computed at runtime: -### `keccak256` +```rue +fn main(list: List) -> Bytes32 { + sha256(...list) +} +``` -Calculates the [Keccak-256](https://en.wikipedia.org/wiki/SHA-3) hash of the bytes provided. While this hashes the value at runtime, there is also a `keccak256_inline` builtin that allows you to hash a constant value at compile time and insert the result into the program. Its use is discouraged (because hard coding 32 bytes is costly in CLVM) unless you have a very large constant value that you want to avoid hashing multiple times. +This saves CLVM cost compared to concatenating the values first, since the `sha256` operator accepts multiple arguments. -For example: +### `sha256_inline` -```rue -let hash = keccak256("hello"); -``` +The same as `sha256`, but the hash is calculated at compile time if the value is constant, and the result is inserted into the program. Its use is discouraged (because hard coding 32 bytes is costly in CLVM) unless you have a very large constant value that you want to avoid hashing at runtime. See also [Const Expressions](/docs/constants.md#const-expressions). + +### `keccak256` -There's also a variant with the spread syntax that allows you to hash a list of arguments that is computed at runtime (rather than a static list): +Calculates the [Keccak-256](https://en.wikipedia.org/wiki/SHA-3) hash of the bytes provided. Like `sha256`, it supports the spread syntax. ```rue -let hash = keccak256(...list); +fn main() -> Bytes32 { + keccak256("hello") +} ``` -Note that this prevents the compiler from being able to fold the arguments into a constant at compile time. However, it saves CLVM cost by not having to recursively concatenate the arguments. +### `keccak256_inline` -### `coinid` +The same as `keccak256`, but calculated at compile time if the value is constant, like `sha256_inline`. -A builtin CLVM opcode for hashing the parent coin id, puzzle hash, and amount of a coin into its coin id. See the [Security](/docs/security.md#untrusted-values) section for an explanation of why this opcode exists. Essentially, it adds runtime checks to make sure that the length of the parent coin id and puzzle hash are 32. +### `coinid` -For example: +Calculates the coin id of a coin from its parent coin id, puzzle hash, and amount. It uses a CLVM opcode that also checks that the parent coin id and puzzle hash are each 32 bytes long, and that the amount is a valid coin amount. See the [Security](/docs/security.md#untrusted-values) section for why this matters. ```rue -coinid(parent_coin_id, puzzle_hash, amount) +fn main(parent_coin_id: Bytes32, puzzle_hash: Bytes32, amount: Int) -> Bytes32 { + coinid(parent_coin_id, puzzle_hash, amount) +} ``` -### `substr` +## Bytes -Returns a substring of a byte value, given a range of indices. Note that if either index is out of bounds, this will raise an error. +### `concat` -For example: +Concatenates a list of `Bytes` values. This is what the `+` operator on bytes uses internally, but it's useful when the list is computed at runtime: ```rue -substr("hello", 1, 4) +fn main(list: List) -> Bytes { + concat(list) +} ``` -This would return `"ell"` +### `substr` -The end index is optional, and defaults to the length of the string: +Returns a substring of a byte value, given a start index and an optional end index. If the end index is omitted, it defaults to the length of the value. If either index is out of bounds, this will raise an error. ```rue -substr("hello", 1) +fn main() -> Bytes { + substr("hello", 1, 4) +} ``` -### `g1_map` +This would return `"ell"`. + +## Arithmetic -Hashes the data to a BLS public key, with sha256 and ExpandMsgXmd. +### `divmod` -For example: +Computes both `numerator / denominator` and `numerator % denominator` and returns a pair of the results: ```rue -g1_map("hello") +fn main() -> Int { + let (quotient, remainder) = divmod(50, 3); + quotient + remainder +} ``` -You can also specify an optional DST parameter: +### `modpow` + +Computes `(base ^ exponent) % modulus`. The base may be negative, the exponent must not be, and the modulus must not be `0`: ```rue -g1_map("hello", "dst") +fn main() -> Int { + modpow(5, 50, 45) +} ``` -### `g2_map` - -Hashes the data to a BLS signature, with sha256 and ExpandMsgXmd. +### `sum`, `difference`, `product` -For example: +Computes the sum, difference, or product of a list of `Int` values. These are what the `+`, `-`, and `*` operators use internally, but are useful when the list is computed at runtime: ```rue -g2_map("hello") +fn main(list: List) -> Int { + sum(list) +} ``` -You can also specify an optional DST parameter: +The `difference` of a list subtracts each of the rest of the values from the first one. The `sum` and `difference` of an empty list are `0`, and the `product` of an empty list is `1`. -```rue -g2_map("hello", "dst") -``` +### `any`, `all` -### `pubkey_for_exp` +Returns whether any or all of a list of `Bool` values are `true`. These are what the `|` and `&` operators on booleans use internally. + +## BLS -Maps an exponent (secret key) to a G1 point (public key). +### `pubkey_for_exp` -For example: +Maps an exponent (secret key) to a G1 point (public key). The exponent can be an `Int`, or a `Bytes32` value which is interpreted as an integer: ```rue -pubkey_for_exp("hello") +fn main(secret_key: Bytes32) -> PublicKey { + pubkey_for_exp(secret_key) +} ``` -### `modpow` +### `g1_sum`, `g1_difference` -Computes `(base ^ exponent) % modulus`. Base may be negative, exponent must not be, modulus must not be 0. +Adds or subtracts a list of public keys. These are what the `+` and `-` operators on `PublicKey` use internally. -For example: +### `g2_sum`, `g2_difference` -```rue -modpow(5, 50, 45) -``` +Adds or subtracts a list of signatures. These are what the `+` and `-` operators on `Signature` use internally. -### `divmod` +### `g1_map` + +Hashes the data to a BLS public key, with SHA-256 and ExpandMsgXmd: -Computes both `numerator / denominator` and `numerator % denominator` and returns a pair of the results. +```rue +fn main() -> PublicKey { + g1_map("hello") +} +``` -For example: +You can also specify an optional DST (domain separation tag) parameter: ```rue -let (quotient, remainder) = divmod(50, 3); +fn main() -> PublicKey { + g1_map("hello", "dst") +} ``` -## Operator Optimizations +### `g2_map` -Similarly to [sha256](#sha256) and [keccak256](#keccak256), the following builtin functions are provided to optimize the use of operators on lists of arguments: +Hashes the data to a BLS signature, with SHA-256 and ExpandMsgXmd. Like `g1_map`, it accepts an optional DST parameter: -1. `concat` (the `+` operator on bytes) -2. `sum` (the `+` operator on integers) -3. `difference` (the `-` operator on integers) -4. `product` (the `*` operator on integers) -5. `any` (the `|` operator on booleans) -6. `all` (the `&` operator on booleans) -7. `g1_sum` (the `+` operator on BLS public keys) -8. `g1_difference` (the `-` operator on BLS public keys) -9. `g2_sum` (the `+` operator on BLS signatures) -10. `g2_difference` (the `-` operator on BLS signatures) +```rue +fn main() -> Signature { + g2_map("hello") +} +``` ## Verifications -The following CLVM operators return `nil` on success, and raise if they fail: +The following builtins return `nil` on success, and raise an error if they fail: 1. `bls_pairing_identity` 2. `bls_verify` 3. `secp256k1_verify` 4. `secp256r1_verify` -You can think of these like specialized `assert` statements, since they will raise if the verification fails, and continue on if not. Rue provides these as builtin functions that can be called as a statement. - -These are automatically optimized such that ordinary references to `nil` after the verification statements in the block are replaced with the verification expression (since it returns `nil` anyways). If there aren't any possible substitutions, the rest of the block will be wrapped in a cons pair, with the verifications happening first, and then unwrapped back into the expression value of the block. And finally, if multiple verifications need to be done in a group, the `all` operator will be used, since it will always return `nil` as well. +You can think of these like specialized `assert` statements, since they will raise if the verification fails, and continue on if not. They can be called as a statement. -All of this is to say that the compiler will pick the most efficient way to insert these verifications into your program without disrupting its behavior at runtime. +The compiler will pick the most efficient way to insert these verifications into your program without disrupting its behavior at runtime. For example, references to `nil` after a verification can be replaced with the verification itself (since it returns `nil` anyways), and multiple verifications can be grouped together with the `all` operator. ### `bls_pairing_identity` Accepts a flattened sequence of public key and signature pairs, and verifies that the pairing of all pairs is the identity. Otherwise, this will raise. -For example: - ```rue -bls_pairing_identity( - 0xa3050a67e4771030dade87560e175206a1a93c44461619de07a4e50bfe11ef80f8eaa4956f4648b7ff26c6551dd6ee90, - 0xa6242cc5b80eb338a96b41035738eb9973d2c0f892fc52e47e55fc288da1a595a3577b0f995be3d2f4ff71b1948181840e95e79f176f657ade50780f1d77179e82133987025bdeaf37b0052c7dee524a17746b3270eb18a18701ab8157049734, - 0xae0154514ac83b8efea5b2eee425fc41ead032bb04b8a977eff85e80f9dd8940833c0d7d85921bf18fe84f639f417cca, - 0xa446e176d5aba64e9714fab391b917ea6be087e3d11c5b6bf1fa15d87bf267cfc8dbd479cd2f5a94b78f4ca9aa77850810078fb439e70559c2ea0bbddc5a1b749f5d50a6b466adb1ccd67a62a351997b9a81309b3bddff6168051dc74432d5d5, - 0xb066ce9e6484fe574ed55003449fae4d08652f85de45d718c2397c667cd80ed5571458d58c7d28b101ab1ef986973e77, - 0x8708f12e05766a8ecbba88e978b9236d4bf998b33f6924258ec9a333190df64a050fe15b9085608c2277f032845c523e16cc1d2dbd4457cd431d18b1419fe45a098205482ee4d41915506f2687778103f32f3cac3ce6cca176d002fffd756860, - 0xb7f1d3a73197d7942695638c4fa9ac0fc3688c4f9774b905a14e3a3f171bac586c55e83ff97a1aeffb3af00adb22c6bb, - 0xac168cd0efa5188f370bbe566dfbbb8c8c69a985e7cad8eed7b136ebdcd6338f1d5781e8fd340963fa96a5704a3b7b15046be60b3d17ec1f962191e90b39b36b5ff81548e0baf6f6564f83dbe50258df62f271fdba7a042ed530eeb6a15b794c, -); +fn main(public_key: PublicKey, signature: Signature) { + bls_pairing_identity(public_key, signature); +} ``` -You can use the spread syntax to verify a list of pairs. +You can also spread an `AlternatingList` instead: + +```rue +fn main(pairs: AlternatingList) { + bls_pairing_identity(...pairs); +} +``` ### `bls_verify` Accepts a signature followed by a flattened sequence of public key and message pairs, and verifies that the aggregate signature is valid. Otherwise, this will raise. -For example: - ```rue -bls_verify( - 0x80c37921e62092ef55f85f9eccb21bd80cfaafc0bce9cbdd6999b1a8cabadc8f23720f0261efafaf53cbcc74580b9432007b66d824668900a94934f184bc41bf9ccf9ec141c6f7da610aa7296cd0a181ae8fe176b607aa4c367f15ee0cb985d7, - 0x8b202593319bce41b090f3309986de59861ab1e2ff32aef871d83f9aac232c7253c01f1f649c6f69879c441286319de4, - 0x39cb1950dba19a7bee9924b5bd2b29f190ffe4ef, -); +fn main(signature: Signature, public_key: PublicKey, message: Bytes) { + bls_verify(signature, public_key, message); +} ``` -You can use the spread syntax to verify a list of pairs. +You can also spread an `AlternatingList` after the signature: -### `secp256k1_verify` +```rue +fn main(signature: Signature, pairs: AlternatingList) { + bls_verify(signature, ...pairs); +} +``` -Verifies a signature that uses the secp256r1 curve against its message hash and signature. +### `secp256k1_verify` -For example: +Verifies a signature that uses the secp256k1 curve, given the public key, the message hash, and the signature: ```rue -secp256k1_verify( - 0x02390b19842e100324163334b16947f66125b76d4fa4a11b9ccdde9b7398e64076, - 0x85932e4d075615be881398cc765f9f78204033f0ef5f832ac37e732f5f0cbda2, - 0x481477e62a1d02268127ae89cc58929e09ad5d30229721965ae35965d098a5f630205a7e69f4cb8084f16c7407ed7312994ffbf87ba5eb1aee16682dd324943e, -); - +fn main(public_key: K1PublicKey, message_hash: Bytes32, signature: K1Signature) { + secp256k1_verify(public_key, message_hash, signature); +} ``` ### `secp256r1_verify` -Verifies a signature that uses the secp256r1 curve against its message hash and signature. - -For example: +Verifies a signature that uses the secp256r1 curve, given the public key, the message hash, and the signature: ```rue -secp256r1_verify( - 0x033e1a1b2ccbc35883c60fdfc3f4a02175096ade6271fe85517ca5772594bbd0dc, - 0x85932e4d075615be881398cc765f9f78204033f0ef5f832ac37e732f5f0cbda2, - 0xeae2f488080919bd0a7069c24cdd9c6ce2db423861b0c9d4236cdadbd0005f6d8f3709e6eb19249fd9c8bea664aba35218e67ea4b0f2239488dc3147f336e1e6, -); +fn main(public_key: R1PublicKey, message_hash: Bytes32, signature: R1Signature) { + secp256r1_verify(public_key, message_hash, signature); +} ``` diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..5f29029 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,108 @@ +--- +slug: /cli +--- + +# Command Line + +The `rue` command line tool is installed with `cargo install rue-cli` (see [Installation](/docs/installation.md)). + +| Command | Description | +| -------------------------------- | ----------------------------------------------------------------- | +| `rue init [path]` | Create a new project with a `Rue.toml` manifest. | +| `rue build [file]` | Compile the project (or a single file) and print the CLVM output. | +| `rue test [file]` | Run every `test fn` in the project. | +| `rue fmt [paths...] [--check]` | Format Rue source files, or check that they're already formatted. | +| `rue debug [solution]` | Run a CLVM program against a solution and print the result. | +| `rue lints` | List every lint and its default level, and the lint groups. | + +## `rue init` + +Creates a new [project](/docs/projects.md) in the given directory (or the current directory, if none is given), with a `Rue.toml` manifest and a `puzzles/main.rue` file. It fails if either of those files already exist. + +```bash +rue init my-project +``` + +## `rue build` + +Compiles the project's `main` function, and prints the CLVM output. + +```bash +$ rue build +(q . "Hello, world!") +``` + +If you pass a file, its `main` function is compiled instead: + +```bash +rue build puzzles/other.rue +``` + +| Flag | Description | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `-e`, `--export` | Compile the exported function with this name instead of `main`. | +| `-x`, `--hex` | Output the serialized bytecode as hex, instead of the CLVM text. | +| `-h`, `--hash` | Output the tree hash of the compiled program. This can be combined with `--hex` to output both. | +| `-s`, `--split` | Split the hex output into lines of 64 characters. This requires `--hex` (or `--all`). | +| `-d`, `--debug` | Compile in debug mode, which includes `debug` statements and messages for failed assertions, and disables some optimizations. | +| `-a`, `--all` | Compile every entrypoint in the project, and write each one to a file. See [Building Everything](/docs/projects.md#building-everything). | +| `-A`, `--allow` | Allow a lint or lint group. Can be repeated. | +| `-W`, `--warn` | Report a lint or lint group as a warning. Can be repeated. | +| `-D`, `--deny` | Report a lint or lint group as an error, which fails compilation. Can be repeated. | +| `-F`, `--forbid` | Like `--deny`, but attributes and later flags can't change the level. Can be repeated. | + +:::note +Since `-h` is short for `--hash`, the help text for `rue build` is only available as `--help`. +::: + +Errors and warnings are printed with the file, line, and column they occurred at. If there are any errors (including lints that are denied), nothing is output and the command fails. + +## `rue test` + +Compiles the project in debug mode, and runs every [test function](/docs/testing.md) in it. If you pass a file or directory, it's used to find the project, and all of that project's tests are run. A file that isn't part of a project is tested by itself. + +```bash +$ rue test +Running test `factorial_works` (1/1) +``` + +A test passes if it finishes without raising an error and returns `nil`. The command fails if any of the tests fail. + +| Flag | Description | +| ---------------------- | ------------------------------------------------------------------------------------------------------------ | +| `--max-cost` | The maximum CLVM cost each test can use before it fails. Defaults to `11000000000`, Chia's block cost limit. | +| `-A`, `-W`, `-D`, `-F` | Set the level of a lint or lint group, the same as for `rue build`. | + +## `rue fmt` + +Formats Rue source files in place. With no arguments, every file in the project is formatted. Otherwise, you can pass any number of files, directories, or glob patterns: + +```bash +rue fmt +rue fmt puzzles/main.rue +rue fmt 'puzzles/**/*.rue' +``` + +With `--check`, files are not changed. Instead, it lists the files that need to be formatted, and fails if there are any. This is useful in CI. + +See [Formatting](/docs/formatting.md) for more details. + +## `rue debug` + +Runs a CLVM program against a solution (which defaults to `nil`), and prints the result. Both are written in CLVM's text format, or as hex with `--hex`: + +```bash +$ rue debug "(+ 2 5)" "(10 20)" +30 +``` + +Unlike other CLVM runners, this supports the debug output from programs compiled with `rue build --debug`, which prints the value of each `debug` statement as the program runs. See [Debugging](/docs/debugging.md). + +| Flag | Description | +| ------------- | -------------------------------------------------------------------------------------------------------------- | +| `-x`, `--hex` | Read the program and solution as serialized hex, instead of CLVM text. | +| `--max-cost` | The maximum CLVM cost the program can use before it fails. Defaults to `11000000000`, Chia's block cost limit. | + +## `rue lints` + +Lists every lint, along with its default level and a short description, as well as the lint groups and the lints in each of them. See [Lints](/docs/lints.md). diff --git a/docs/constants.md b/docs/constants.md index cf410ab..7fcfa36 100644 --- a/docs/constants.md +++ b/docs/constants.md @@ -6,9 +6,9 @@ slug: /constants Constants allow you to write a value a single time, give it a name, and then reuse it throughout your program. -They are similar to [Bindings](/docs/bindings.md), which the primary difference being that they are defined at the top level of the program and are order independent. They will live for and be reused for the entire lifecycle of the `main` function. +They are similar to [Bindings](/docs/bindings.md), with the primary difference being that they are defined at the top level of the program and are order independent. They will live for and be reused for the entire lifecycle of the `main` function. -As a simple example, you might want to reuse a string multiple times: +A constant must have an explicit type. As a simple example, you might want to reuse a string multiple times: ```rue const GREET: String = "Hello, "; @@ -18,6 +18,8 @@ fn main(person_a: String, person_b: String) -> (String, String) { } ``` +A constant's value can be any expression, including calls to functions and references to other constants. However, a constant can't refer to itself, either directly or through other constants. + ## Inline Constants You can mark a constant as `inline`, which forces its value to be inserted everywhere it's referenced rather than being defined a single time and reused. @@ -32,8 +34,47 @@ fn main(person_a: String, person_b: String) -> (String, String) { } ``` -This should be used sparingly, since it can come with either a performance hit, an increase in compiled output size, or both. +This should be used sparingly, since it can come with either a performance hit, an increase in compiled output size, or both. It's best suited for small values, like the condition opcodes in the [standard library](/docs/standard-library.md), which are cheaper to repeat than to reference. :::tip The compiler will automatically inline constants if they are only referenced a single time. ::: + +## Const Expressions + +A `const` block is evaluated at compile time, and its result is inserted into the program as a constant value. This lets you precompute values that would otherwise be computed every time the program runs: + +```rue +fn main() -> Bytes32 { + const { tree_hash([1, 2, 3]) } +} +``` + +This compiles to `(q . 0xbcd55bcd0daebba8cb158547e8480dc968570faf958f1e31a9887d6ae3dba591)`, instead of hashing the list at runtime. + +A const block can contain statements like any other [block](/docs/bindings.md#blocks), and can call functions (including recursive ones) and reference constants: + +```rue +const BASE: Int = 5; + +fn factorial(value: Int) -> Int { + if value <= 1 { + 1 + } else { + value * factorial(value - 1) + } +} + +fn main() -> Int { + const { + let result = factorial(BASE); + result * 2 + } +} +``` + +However, it can't depend on any values that are only known at runtime, such as function parameters or `let` bindings declared outside of it. If the expression raises an error while it's being evaluated, or it uses more than the CLVM cost limit of 11,000,000,000, it's reported as a compile error. + +:::tip +Keep in mind that a large constant value (such as a hash) can cost more to include in a program than it costs to compute at runtime, since every byte of a puzzle adds to its cost. Const expressions are most useful for values that are expensive to compute, but small to store. +::: diff --git a/docs/control-flow.md b/docs/control-flow.md index 88bc8fa..0c2d940 100644 --- a/docs/control-flow.md +++ b/docs/control-flow.md @@ -8,58 +8,106 @@ Control flow is used to change the behavior of the program based on certain cond ## If Expression -You can use an `if` expression to execute different blocks of code based on a condition. +You can use an `if` expression to execute different blocks of code based on a condition. The condition must be a `Bool`. For example: ```rue -let size = if number > 100 { - "large" -} else { - "small" -}; +fn size(number: Int) -> String { + if number > 100 { + "large" + } else { + "small" + } +} +``` + +Since `if` is an expression, both branches must produce a value, and the result can be assigned to a binding or returned from a function. + +You can chain multiple conditions with `else if`: + +```rue +fn size(number: Int) -> String { + if number > 100 { + "large" + } else if number > 10 { + "medium" + } else { + "small" + } +} ``` -It's worth noting that this will only execute the branch that matches the condition. This means that you can use a [type guard](/docs/type-system/guards.md) to narrow the type of variables after the condition is evaluated. +It's worth noting that this will only execute the branch that matches the condition. This means that you can use a [type guard](/docs/type-system/guards.md) to narrow the type of variables in each branch. + +## Inline If -However, if you don't need to narrow the type, you can use an `inline if` expression to immediately execute both branches and return the result of the branch that matches the condition. This can be an important optimization to reduce the size of the compiled program, but it can also lead to logic errors or higher runtime costs if you're not careful. +If you don't need to narrow the type, you can use an `inline if` expression to evaluate both branches up front, and return the result of the branch that matches the condition. This can be an important optimization to reduce the size and cost of the compiled program, since it avoids wrapping each branch in its own program. -The example above is a great example of when you should use an `inline if` expression: +The example above is a great example of when you should use an `inline if` expression, since each branch is just a constant value: ```rue -let size = inline if number > 100 { - "large" -} else { - "small" -}; +fn size(number: Int) -> String { + inline if number > 100 { "large" } else { "small" } +} ``` -## If Statement +However, since both branches are always evaluated, this can lead to logic errors or higher runtime costs if you're not careful. In particular, if either branch can raise an error, it will raise even when the condition doesn't select it. The `inline_if_may_raise` [lint](/docs/lints.md) warns about this. -To reduce the amount of indentation, you can use an `if` statement instead of an `if` expression if you're going to exit the function early if the condition is met (i.e., an early `return`). +## If Statement -This might look like this: +To reduce the amount of indentation, you can use an `if` statement (an `if` without an `else` branch) to exit the function early if the condition is met. Its block must end with a `return` or `raise`: ```rue -if list is nil { - return 0; +fn first_or_zero(list: List) -> Int { + if list is nil { + return 0; + } + + list.first } +``` + +Type guards in the condition of an `if` statement narrow the type for the rest of the block after it. In this case, `list` is known to not be `nil` after the `if` statement, so `list.first` can be accessed. + +## Return -let (first, rest) = list; +You can use a `return` statement to exit the current function early and return a value: + +```rue +fn clamp(value: Int) -> Int { + if value > 100 { + return 100; + } + + value +} ``` +If the function doesn't return a value, you can write `return;` on its own. + +:::note +A `return` statement can only be used directly in a function body, or in the block of an `if` statement. Inside of an expression (such as a branch of an `if` expression), the block must end with its value instead. +::: + ## Raise -You can use a `raise` statement to immediately exit the program with an error. +You can use a `raise` statement to immediately exit the program with an error: ```rue -raise "List is empty"; +fn main(list: List) -> Int { + if list is nil { + raise "List is empty"; + } + + list.first +} ``` -This will cause the program to fail with the message "List is empty". +This will cause the program to fail with the message "List is empty". The message is optional, so you can also write `raise;` on its own. :::info -In release builds, error messages will automatically be omitted to reduce the size of the compiled program. +Error messages are omitted when compiling normally, to reduce the size of the compiled program. They are only included when compiling in debug mode, such as with `rue build --debug` or `rue test`. ::: ## Assert @@ -67,15 +115,12 @@ In release builds, error messages will automatically be omitted to reduce the si The `assert` statement is a shorthand for `raise` inside of an `if` statement: ```rue -assert !(list is nil); +fn main(value: Int) -> Int { + assert value > 0; + value * 2 +} ``` -It's useful for checking types at runtime and raising an error if the condition is not met. - -## Return +It's useful for checking conditions or types at runtime and raising an error if they are not met. Like an `if` statement, type guards in an `assert` narrow the type of values for the rest of the block. -You can use a `return` statement to exit the current function early and return a value. - -```rue -return 0; -``` +In debug mode, the error includes the location of the assertion that failed, such as `"assertion failed at main.rue:2:5"`. diff --git a/docs/debugging.md b/docs/debugging.md index d7db9b1..31b6cb6 100644 --- a/docs/debugging.md +++ b/docs/debugging.md @@ -4,18 +4,59 @@ slug: /debugging # Debugging -:::note -Rue's developer tools are still a work in progress, and important functionality may be missing in the meantime. +## Debug Mode + +By default, the compiler optimizes your program as much as possible, and leaves out anything that isn't needed for it to run correctly, such as error messages. + +When you compile in debug mode, with `rue build --debug`: + +1. `debug` statements are included in the program. +2. `raise` statements include their message, and the location they occurred at. +3. Failed `assert` statements raise a message with their location, such as `"assertion failed at main.rue:2:5"`. +4. Some optimizations are disabled, so the output more closely matches the structure of your code. + +Tests are always compiled in debug mode. + +:::warning +Debug builds should only be used for development. They are larger and more expensive to run, have a different puzzle hash than the normal build, and `debug` statements use an operator that isn't part of standard CLVM. Always deploy puzzles compiled without `--debug`. ::: -## Debug Print +## Debug Statements -You can use `debug` statements to print messages to the console: +You can use `debug` statements to print values to the console while a program runs: ```rue -debug "Hello, world!"; +fn main(value: Int) -> Int { + debug value; + value * 2 +} ``` -If you compile this with `rue build`, it will be omitted from the compiled program (since printing isn't supported in CLVM natively). However, if you compile this with `rue build -d`, special debug symbols will be included that will print the message (as an untyped CLVM value) to the console at runtime. +The value can be anything, and is printed as an untyped CLVM value, along with the location of the statement. + +If you compile this with `rue build`, it will be omitted from the compiled program (since printing isn't supported in CLVM natively). However, if you compile this with `rue build --debug`, special debug symbols will be included that will print the value at runtime. + +This modified version of CLVM can be executed with the `rue debug` command, with `rue test`, or with the [Wallet SDK](https://github.com/xch-dev/chia-wallet-sdk) simulator. For example: + +```bash +$ rue debug "$(rue build --debug)" "(10)" +main.rue:2:5: 10 +20 +``` + +:::tip +Since `debug` statements shouldn't be left in your code once you're done with them, you can enable the `debug_statement` [lint](/docs/lints.md) to report any that remain. +::: + +## Running Programs + +The `rue debug` command runs any CLVM program against a solution, and prints the result. This is useful for checking how a compiled puzzle behaves with different solutions, without having to write a test: + +```bash +$ rue build +(* 2 (q . 2)) +$ rue debug "(* 2 (q . 2))" "(10)" +20 +``` -This modified version of CLVM can be executed with the `rue debug` command, with `rue test`, or with the [Wallet SDK](https://github.com/xch-dev/chia-wallet-sdk) simulator. +See [Command Line](/docs/cli.md#rue-debug) for the available options. diff --git a/docs/formatting.md b/docs/formatting.md new file mode 100644 index 0000000..20806a2 --- /dev/null +++ b/docs/formatting.md @@ -0,0 +1,50 @@ +--- +slug: /formatting +--- + +# Formatting + +Rue has a built-in code formatter, which formats your code in a consistent style, similar to `rustfmt` for Rust. It keeps your comments, and breaks up long lines so they fit within the maximum width. + +You can format every file in the project with: + +```bash +rue fmt +``` + +Or specific files, directories, or glob patterns: + +```bash +rue fmt puzzles/main.rue 'tests/**/*.rue' +``` + +Files with syntax errors are skipped, since they can't be formatted reliably. + +## Checking Formatting + +To check that files are formatted without changing them (for example, in CI), use `--check`: + +```bash +rue fmt --check +``` + +This lists every file that needs to be formatted, and fails if there are any. + +## Options + +The formatter can be configured in the `[formatter]` section of [`Rue.toml`](/docs/projects.md#manifest): + +```toml +[formatter] +max_width = 100 +indent_width = 4 +``` + +| Key | Default | Description | +| -------------- | ------- | -------------------------------------------------------- | +| `max_width` | `100` | The maximum width of a line before it's broken up. | +| `indent_width` | `4` | The number of spaces used for each level of indentation. | + +## Editor Integration + +The [language server](/docs/installation.md#editor-support) can also format files, so you can use your editor's format command, or enable format on save. It uses the same options as `rue fmt`. diff --git a/docs/functions.md b/docs/functions.md index 2747a53..3a8c90b 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -4,9 +4,9 @@ slug: /functions # Functions -A [function]() is a self contained part of a program. You can break up complex code into multiple programs to make it more readable, or use recursive functions to implement looping. +A [function]() is a self contained part of a program. You can break up complex code into multiple functions to make it more readable, or use recursive functions to implement looping. -Function items can be declared at the top level: +Function items can be declared at the top level of a file or module: ```rue fn add(a: Int, b: Int) -> Int { @@ -17,12 +17,38 @@ fn add(a: Int, b: Int) -> Int { And they can be called by other functions: ```rue -add(42, 34) +fn main() -> Int { + add(42, 34) +} ``` +Every parameter must have a type. The return type comes after the `->`, and if it's omitted, the function returns `nil`. The last expression in the body (without a semicolon) is the value that the function returns, although you can also [return early](/docs/control-flow.md#return). + +Functions can be declared in any order, and can call themselves recursively: + +```rue +fn factorial(num: Int) -> Int { + if num > 1 { + num * factorial(num - 1) + } else { + 1 + } +} +``` + +:::info +CLVM doesn't have loops, so recursion is how you iterate over a list or repeat a computation in Rue. +::: + ## Entrypoints -The `main` function is the primary entrypoint to your program. It's used to determine which symbols are used and its body is compiled verbatim (along with any functions and constants it depends on) rather than being called. +An entrypoint is a function that's compiled as a standalone program, rather than being called by another function. Its parameters are read from the program's solution (or for a puzzle, the curried arguments followed by the solution) as a list, and its return value is the output of the program. + +Only entrypoints, and the functions and constants they depend on, are included in the compiled output. Anything that isn't used is removed. + +### Main Function + +The `main` function is the primary entrypoint to your program. Its body is compiled directly (along with any functions and constants it depends on) rather than being called. For example, the following program: @@ -36,9 +62,7 @@ Will compile to the CLVM `(q . 42)`. ### Test Functions -Another form of entrypoint (which behaves like `main`) is a test function. - -This lets you write unit tests directly in your Rue code: +Another kind of entrypoint is a test function, which lets you write unit tests directly alongside your Rue code: ```rue test fn verify() { @@ -46,7 +70,7 @@ test fn verify() { } ``` -When you run `rue test`, all of the tests in the file will be executed. If they raise an error, the line number of the assertion will be included in the error message. +When you run `rue test`, all of the tests in the project will be executed. See [Testing](/docs/testing.md) for more details. ### Exported Functions @@ -58,13 +82,15 @@ export fn puzzle() -> List { } ``` -If you run `rue build -e puzzle`, it will build this export as if it were the main function. This lets you include multiple programs inside of a single file. +If you run `rue build --export puzzle`, it will build this export as if it were the main function. This lets you include multiple programs in a single project. + +The `export` keyword also makes the function visible to other [modules](/docs/modules.md). ## Inline Functions You can mark a function as `inline`. This will change the behavior of the compiler to insert the function body everywhere it's referenced, substituting each of the parameters with the corresponding arguments in the function call, instead of defining the function separately and calling it. -As an example, this will insert the parameter value `num + 10` four times, twice for each multiplication, rather than defining the function once and calling it twice: +As an example, this will insert the argument `num + 10` four times, twice for each multiplication, rather than defining the function once and calling it twice: ```rue fn main(num: Int) -> Int { @@ -84,11 +110,13 @@ A recursive function cannot be marked as `inline`. The compiler will automatically inline functions if they are referenced a single time and their parameters are referenced a single time. ::: -## Extern Functions +## Parameter Layout -Function parameters are optimized into an efficient binary tree structure, as long as the function is neither an entrypoint, nor used as a closure. This binary tree optimization is not allowed for those because it's an implementation detail of the compiler and hard to rely on as a public interface. For example, if you accept a function as an argument, its arguments must be in the expected layout. +Most functions are only ever called by your own code, so the compiler is free to choose how their arguments are passed. Parameters of these functions are stored in an efficient binary tree structure, rather than a list, which makes them cheaper to access. -The compiler will pick the optimized parameter layout automatically when it can, but you can opt out of this with the `extern` keyword: +This isn't possible for entrypoints, or functions that are used as values (such as [closures](#closures), or functions passed as arguments), since other programs need to know how to call them. Those always use the standard list layout, where the arguments are a nil-terminated list. + +The compiler picks the layout automatically, but you can force a function to use the standard list layout with the `extern` keyword: ```rue extern fn add(a: Int, b: Int) -> Int { @@ -98,32 +126,32 @@ extern fn add(a: Int, b: Int) -> Int { Just keep in mind that this can increase the size of the generated program, as well as its runtime CLVM cost. -### Spread Syntax +### Spread Parameters -Although it's not very useful for optimized functions (since the parameter layout is managed by the compiler anyways), you can remove the nil terminator from the parameter list in an extern function by using the spread operator. You can think of this as binding a parameter to the "rest" of the parameters in CLVM. +You can mark the last parameter with the spread operator (`...`), which binds it to the rest of the arguments, rather than to a single argument. In CLVM terms, this removes the nil terminator from the parameter list. For example: ```rue -extern fn sum(...numbers: List) -> Int { +extern fn sum_all(...numbers: List) -> Int { if numbers is nil { 0 } else { - numbers.first + sum(...numbers.rest) + numbers.first + sum_all(...numbers.rest) } } ``` -However, Rue does not allow you to specify an arbitrary number of arguments, and will force you to use the spread syntax on a list manually. - -So, this can be called like this: +Rue doesn't allow you to pass an arbitrary number of arguments directly. Instead, when a function has a spread parameter, the last argument you pass to it must also be spread: ```rue -let list = [1, 2, 3, 4, 5]; -let total = sum(...list); +fn main() -> Int { + let list = [1, 2, 3, 4, 5]; + sum_all(...list) +} ``` -It's also possible to use the spread syntax with non-list types, which allows for flexibility with external functions: +It's also possible to use the spread syntax with non-list types, which allows for flexibility with external programs: ```rue fn main( @@ -144,14 +172,31 @@ struct Solution { fn main(...solution: Solution) -> List { let message = tree_hash(solution.conditions); - let agg_sig = AggSigMe { - public_key: solution.public_key, - message, - }; + let agg_sig = AggSigMe { public_key: solution.public_key, message }; [agg_sig, ...solution.conditions] } ``` +## External Functions + +An `extern` function can also be loaded from a program that's already been compiled, instead of being written in Rue. The program is read from a hex file (such as one produced by `rue build --hex`, or the `.hex` files in the [chia_puzzles](https://github.com/Chia-Network/chia_puzzles) repository), with a path relative to the source file: + +```rue +extern fn add(a: Int, b: Int) -> Int from "./add.hex"; + +fn main() -> Int { + add(20, 22) +} +``` + +The signature of the function is up to you, and isn't checked against the program, so make sure that it matches the parameters the program actually expects. The program is called with its arguments in the standard list layout. + +An external function can be used like any other function, including as a value. For example, `tree_hash(add)` computes the puzzle hash of the program, and `const { tree_hash(add) }` does so at compile time (see [Const Expressions](/docs/constants.md#const-expressions)). + +:::note +The path must be relative and end in `.hex`, and the file must contain a valid serialized CLVM program. +::: + ## Closures Because functions can be passed around as values, it's sometimes useful to be able to write a function inline. @@ -159,8 +204,20 @@ Because functions can be passed around as values, it's sometimes useful to be ab You can do this with a lambda: ```rue -let adder = fn(a: Int, b: Int) => a + b; -let sum = adder(42, 34); +fn main() -> Int { + let adder = fn(a: Int, b: Int) => a + b; + adder(42, 34) +} +``` + +The parameter types can be left out if they can be inferred from the expected type, and you can specify the return type after the parameters with a `:`: + +```rue +fn main() -> Int { + let double: fn(value: Int) -> Int = fn(value) => value * 2; + let triple = fn(value: Int): Int => value * 3; + double(1) + triple(2) +} ``` :::warning @@ -185,3 +242,31 @@ fn create_adder(a: Int) -> fn(b: Int) -> Int { ``` In this case, `create_adder` returns a closure which captures the value of `a` into the lambda function. + +## Function Types + +The type of a function is written like its signature, with the `fn` keyword, parameter names, and the return type: + +```rue +type Operation = fn(a: Int, b: Int) -> Int; + +fn apply(operation: Operation, a: Int, b: Int) -> Int { + operation(a, b) +} + +fn multiply(a: Int, b: Int) -> Int { + a * b +} + +fn main() -> Int { + apply(multiply, 6, 7) +} +``` + +The return type of a function type is required. A function type can also have a spread parameter (such as `fn(...solution: Any) -> List`), and can be [generic](/docs/type-system/generics.md#generic-function-types). + +A function can be assigned to a function type if it has the same number of parameters, each parameter accepts at least the expected type, and it returns a compatible value. So a function that accepts `Bytes` can be used where a function that accepts `Bytes32` is expected, but not the other way around. + +:::note +A function value is just a compiled CLVM program at runtime, so there's no way to check whether an arbitrary value is a function. See [Type Guards](/docs/type-system/guards.md#limitations). +::: diff --git a/docs/installation.md b/docs/installation.md index cef7713..e307369 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -7,19 +7,29 @@ import TabItem from '@theme/TabItem'; # Installation +Rue is a statically typed programming language that compiles to [CLVM](https://chialisp.com/clvm) bytecode. It's designed as an alternative to [Chialisp](https://chialisp.com) for writing coin puzzles on the [Chia blockchain](https://chia.net). + :::note Rue is still in active development. If you run into any issues, please report them in [GitHub issues](https://github.com/xch-dev/rue/issues). ::: +:::tip +If you just want to try the language, the [Playground](https://play.rue-lang.com) runs the compiler entirely in your browser, with no installation required. +::: + +## Command Line Tool + First, you will need to install the [Rust toolchain](https://rustup.rs). -You can install the Rue CLI with this command: +Then you can install the Rue CLI from [crates.io](https://crates.io/crates/rue-cli): ```bash cargo install rue-cli ``` -It's also useful to install [clvm_tools_rs](https://github.com/Chia-Network/clvm_tools_rs): +This installs the `rue` command, which includes the compiler, test runner, formatter, and CLVM debugger. See the [Command Line](/docs/cli.md) page for everything it can do. + +It's also useful to install [clvm_tools_rs](https://github.com/Chia-Network/clvm_tools_rs), which provides tools such as `brun` and `opd` for working with CLVM directly: ```bash cargo install clvm_tools_rs @@ -27,65 +37,64 @@ cargo install clvm_tools_rs ## Editor Support - - +Rue has a language server, which provides diagnostics as you type, hover information, go to definition, find references, completions, formatting, and quick fixes for many lints. -You will need to install [Visual Studio Code](https://code.visualstudio.com). - -Then, you can install the [Rue extension](https://marketplace.visualstudio.com/items?itemName=Rigidity.rue-language) on the VSCode marketplace. It provides syntax highlighting and LSP integration. - -You can install the Rue language server with this command: +You can install it with this command: ```bash cargo install rue-lsp ``` -This should automatically work with the extension. + + + +You will need to install [Visual Studio Code](https://code.visualstudio.com). + +Then, you can install the [Rue extension](https://marketplace.visualstudio.com/items?itemName=Rigidity.rue-language) on the VSCode marketplace. It provides syntax highlighting, and uses the `rue-lsp` language server installed above. You will need to install [Cursor](https://cursor.com/). -Then, you can install the [Rue extension](https://open-vsx.org/extension/Rigidity/rue-language) on the Open VSX marketplace. It provides syntax highlighting and LSP integration. - -You can install the Rue language server with this command: - -```bash -cargo install rue-lsp -``` - -This should automatically work with the extension. +Then, you can install the [Rue extension](https://open-vsx.org/extension/Rigidity/rue-language) on the Open VSX marketplace. It provides syntax highlighting, and uses the `rue-lsp` language server installed above. :::tip -Any editor that supports Open VSX and VSCode extensions will likely support this. +Any editor that supports Open VSX and VSCode extensions will likely support this. Other editors can run `rue-lsp` directly, since it communicates over the standard [Language Server Protocol](https://microsoft.github.io/language-server-protocol/). ::: ## Hello World The simplest program in Rue is the classic "hello world" example. -You can run the following command to setup a new project: +You can run the following command to set up a new project: ```bash -rue init +rue init my-project +cd my-project ``` -And then you can build it: +This creates a `Rue.toml` manifest, and a `puzzles/main.rue` file with the following contents: + +```rue +fn main() -> String { + "Hello, world!" +} +``` + +Now you can build it: ```bash rue build ``` -The `puzzles/main.rue` file should contain something like this: +The output is the compiled CLVM program: -```rue -fn main() -> String { - "Hello, world!" -} +``` +(q . "Hello, world!") ``` -And the CLVM output when compiling it is `(q . "Hello, world!)"`. +You can learn more about how projects are laid out on the [Projects](/docs/projects.md) page. diff --git a/docs/lints.md b/docs/lints.md new file mode 100644 index 0000000..61e7577 --- /dev/null +++ b/docs/lints.md @@ -0,0 +1,199 @@ +--- +slug: /lints +--- + +# Lints + +Besides errors, which prevent a program from compiling, the compiler reports warnings about code that works but is likely to be a mistake, or could be written more simply. These are called lints. + +Each lint can be configured to one of the following levels: + +| Level | Description | +| -------- | ------------------------------------------------------------------- | +| `allow` | The lint isn't reported. | +| `warn` | The lint is reported as a warning. | +| `deny` | The lint is reported as an error, which fails compilation. | +| `forbid` | Like `deny`, but attributes and later flags can't change the level. | + +You can see every lint and its default level by running `rue lints`. Many lints come with a suggested fix, which the [language server](/docs/installation.md#editor-support) can apply for you as a quick fix. + +## Lint Groups + +Related lints are also in groups, which can be configured anywhere a lint can: + +- `unused` contains every `unused_*` lint. +- `style` contains lints for code that works, but could be written more simply, such as `unnecessary_parens` and `collapsible_if`. +- `suspicious` contains lints for code that's likely to be a mistake, such as `self_comparison` and `unconditional_recursion`. + +A group sets the level of every lint in it, including the ones that are allowed by default, so `style = "warn"` also enables `negated_condition` and `shadowed_binding`. + +## Configuring Lints + +### Rue.toml + +Levels can be set in the `[lints]` section of `Rue.toml`: + +```toml +[lints] +unused = "deny" +unused_binding = "allow" +unnecessary_cast = "allow" +``` + +The `[lints]` section goes alongside the `[compiler]` section, which every `Rue.toml` must have. + +Within `Rue.toml`, a lint's own level takes precedence over the level of its group, regardless of the order they're written in. Here every `unused_*` lint is denied, except for `unused_binding`. The exception is a forbidden group, whose lints can't be set to any other level, so `unused = "forbid"` with `unused_binding = "allow"` is an error. + +### Command Line + +Levels can also be overridden for a single `rue build` or `rue test` with `-A`/`--allow`, `-W`/`--warn`, `-D`/`--deny` and `-F`/`--forbid`, which take precedence over `Rue.toml`: + +```bash +rue build -D unused -A unused_import +``` + +Among the flags, a lint's own flag takes precedence over its group's, unless the group is forbidden. Otherwise, if a lint is passed more than once, the last flag wins, unless the lint is already forbidden in `Rue.toml` or by an earlier flag (which is an error). + +### Attributes + +Levels can also be set in the source code, with an `allow`, `warn`, `deny` or `forbid` attribute on an item (such as a function, constant, struct, type alias, import or module) or a statement. The attribute applies to everything inside of what it's attached to, and the innermost one takes precedence over any outer attributes and the project's levels, whether it names a lint or a group. An attribute can list multiple lints, separated by commas: + +```rue +#[deny(unused_binding)] +mod strict { + #[allow(unused_function, unused_parameter)] + fn reserved(value: Int) -> Int { + #[warn(unused_binding)] + let unused = 1; + 42 + } +} +``` + +If an item or statement has more than one attribute for the same lint, the last one wins. + +A `forbid` attribute works like `deny`, but nothing inside of it can change the lint's level. The same goes for lints forbidden in `Rue.toml` or on the command line. An attribute or flag that tries to change the level of a forbidden lint has no effect on it, and is reported as an error: + +```rue +#[forbid(unused_binding)] +fn strict() -> Int { + #[allow(unused_binding)] // Error: Cannot set lint `unused_binding` to `allow` + let unused = 1; + 42 +} +``` + +### Expectations + +An `expect` attribute allows a lint like `allow` does, but also expects it to be reported inside of what it's attached to. If it never is, the attribute is reported with the `unfulfilled_lint_expectation` lint, so it doesn't stay around after the code it was written for changes: + +```rue +fn main() -> Int { + #[expect(unused_binding)] + let unused = 1; + 42 +} +``` + +An `expect` for a group is fulfilled by any lint in it, and like `allow`, it can't change a forbidden lint. Expectations aren't checked if there are any errors other than lints, since code that doesn't compile can't be fully linted. + +### Inner Attributes + +To set a level for a whole file, use an inner attribute (with a `!`) at the start of the file, before any items. Inner attributes can also go at the start of a `mod { ... }` body to apply to the whole module, where they come after the attributes on the `mod` itself, so they take precedence unless those forbid the lint. Attributes on the items inside still override them: + +```rue +#![allow(unused_function)] + +fn reserved() -> Int { + 0 +} + +#[warn(unused_function)] +fn checked() -> Int { + 1 +} +``` + +## Naming Conventions + +The `naming_convention` lint checks that names follow these conventions: + +| Kind | Convention | Example | +| ---------------------------------------- | ----------------------------------------------------------- | ------------- | +| Functions, modules, and bindings | `snake_case` | `tree_hash` | +| Structs, type aliases, and generic types | `UpperCamelCase` | `CreateCoin` | +| Constants | `SCREAMING_SNAKE_CASE` | `CREATE_COIN` | +| Parameters and struct fields | `snake_case`, `SCREAMING_SNAKE_CASE`, or `Title_Snake_Case` | `public_key` | + +Parameters and struct fields can also use `SCREAMING_SNAKE_CASE`, since curried parameters are conventionally written that way (such as `MOD_HASH`), or `Title_Snake_Case`, which is conventionally used for truths (such as `Ephemeral_State`). A leading underscore isn't considered part of the name. + +## Unused Code + +Names that start with an underscore are exempt from the `unused_*` lints. This is useful for parameters and struct fields that are only needed to match the layout of a value: + +```rue +fn main(_curried_value: Bytes32, amount: Int) -> Int { + amount +} +``` + +## List of Lints + +### Unused + +| Lint | Default | Description | +| --------------------- | ------- | -------------------------------------------------------------------------------------- | +| `unused_function` | warn | Functions that are never used | +| `unused_constant` | warn | Constants that are never used | +| `unused_binding` | warn | Let bindings that are never used | +| `unused_parameter` | warn | Function parameters that are never used | +| `unused_struct` | warn | Structs that are never used | +| `unused_type_alias` | warn | Type aliases that are never used | +| `unused_generic_type` | warn | Generic type parameters that are never used | +| `unused_import` | warn | Imports that are never used | +| `unused_value` | warn | Values returned by expression statements that are discarded | +| `unused_struct_field` | warn | Struct fields that are never read, in structs whose values are only ever read by field | +| `unused_export` | warn | Exported items of a module that are only used inside of it | + +### Style + +| Lint | Default | Description | +| ----------------------- | ------- | --------------------------------------------------------------------------------------------------- | +| `empty_generics` | warn | Empty generic parameter or argument lists | +| `unnecessary_cast` | warn | Casts between types that are already compatible | +| `unnecessary_guard` | warn | Type guards between types that are already compatible | +| `unnecessary_plus` | warn | Unary `+` operators, which have no effect | +| `unnecessary_return` | warn | `return` statements directly in a function body, which can end in an expression instead | +| `bool_comparison` | warn | Comparisons with `true` or `false`, which can use the value or its negation instead | +| `needless_bool` | warn | `if` expressions that return `true` and `false`, which can use the condition instead | +| `negated_condition` | allow | `if` expressions with a negated condition and an `else` branch, which can swap the branches instead | +| `collapsible_if` | warn | `else` blocks that only contain an `if` expression, which can be written as `else if` | +| `manual_assert` | warn | `if` statements that only `raise`, which can be written as an `assert` | +| `needless_let_return` | warn | Blocks that end by returning a binding declared directly before, which can end in its value instead | +| `redundant_field_names` | warn | Struct fields written as `name: name`, which can use the shorthand `name` instead | +| `unnecessary_parens` | warn | Parentheses that don't change how an expression is evaluated | +| `naming_convention` | warn | Names that don't follow the naming convention for what they name | +| `shadowed_binding` | allow | Bindings and parameters that shadow another binding or parameter with the same name | + +### Suspicious + +| Lint | Default | Description | +| ------------------------- | ------- | ------------------------------------------------------------------------------------------------ | +| `indistinguishable_guard` | warn | Type guards that are always true at runtime | +| `constant_condition` | warn | Conditions that always evaluate to the same value | +| `double_negation` | warn | Use of `--`, which could be confused with a decrement operator | +| `unreachable_code` | warn | Code after a `return`, `raise` or other expression that never finishes, which is never evaluated | +| `inline_if_may_raise` | warn | `inline if` branches that can raise, even though both are always evaluated | +| `self_comparison` | warn | Comparisons and operations between an expression and itself, which always have the same result | +| `identical_branches` | warn | `if` expressions whose branches are the same, so the condition has no effect | +| `duplicate_condition` | warn | Conditions in an `else if` chain, `&&` or `\|\|` that repeat an earlier one | +| `unconditional_recursion` | warn | Functions that call themselves on every path, so they never return | +| `bytes_int_confusion` | warn | Casts of byte literals to `Int` whose value is negative or not in canonical form | + +### Other + +| Lint | Default | Description | +| ------------------------------ | ------- | -------------------------------------------------------------------------------- | +| `debug_statement` | allow | `debug` statements, which shouldn't be left in a release build | +| `unknown_lint` | warn | Lint names in attributes or `Rue.toml` that don't refer to a known lint or group | +| `unfulfilled_lint_expectation` | warn | `expect` attributes whose lint is never reported inside of them | diff --git a/docs/modules.md b/docs/modules.md index 537618e..713abb2 100644 --- a/docs/modules.md +++ b/docs/modules.md @@ -1,22 +1,51 @@ +--- +slug: /modules +--- + # Modules -Modules are a way to organize your code into separate files. +Modules are a way to organize your code into separate files and namespaces. ## File Structure -As long as you have a `main.rue` file in the root of your project, the compiler will automatically include all of the `.rue` files adjacent to it (including subdirectories) in the compilation. +Every `.rue` file in a [project](/docs/projects.md) is a module, and every directory is a module that contains the files and directories inside of it. The name of a file's module is its name without the `.rue` extension. + +For example, take the following project: + +``` +puzzles +├── main.rue +├── utils.rue +└── conditions + ├── create.rue + └── messages.rue +``` -All files are modules and can reference each other by name: +The rules for how they can reference each other are: -1. Each file includes every other adjacent file or directory in its scope. -2. Each directory's module automatically exports all of its children. -3. Each file has access to the parent directory's module with `super`. +1. Each file can reference the other files and directories in the same directory by name. +2. Each file can reference the parent of its directory with `super`. +3. Only items that are marked with `export` can be referenced from another module. -If there is no `main.rue` file, then each file ending in `.rue` will be compiled completely independently, rather than as a single program. +So in this example, `main.rue` can reference `utils` and `conditions::create`, and `create.rue` can reference `messages` directly and `utils` with `super::utils`. + +## Exports + +Items (such as functions, constants, structs, and type aliases) are private to the module they're declared in by default. To make one visible to other modules, mark it with `export`: + +```rue +export fn greet(name: String) -> String { + "Hello, " + name + "!" +} +``` + +:::note +Exporting a function from `main.rue` also makes it an [entrypoint](/docs/functions.md#exported-functions) that can be compiled with `rue build --export`. +::: ## Paths -You can reference exported symbols and types from other modules by using the module name followed by the path to the symbol or type. +You can reference exported symbols and types from other modules by using the module name followed by the path to the symbol or type: ```rue fn main() -> String { @@ -28,7 +57,7 @@ In this case, we are referencing the `greet` function from the `utils` module. ## Imports -Instead of referencing by path every time, you can import symbols and types from other modules into the current scope so that they can be referenced directly. +Instead of referencing by path every time, you can import symbols and types from other modules into the current scope so that they can be referenced directly: ```rue import utils::greet; @@ -38,17 +67,17 @@ fn main() -> String { } ``` -You can import multiple paths: +You can import multiple items at once: ```rue -import utils::{greet, exclaim}; +import utils::{exclaim, greet}; fn main() -> String { exclaim(greet("Alice")) } ``` -You can also import all symbols and types from a module by using the `*` wildcard: +You can also import all of the exported items from a module by using the `*` wildcard: ```rue import utils::*; @@ -58,24 +87,35 @@ fn main() -> String { } ``` -Finally, it's possible to re-export things that you import: +If a glob import brings in two different items with the same name, using that name is an error, since it's ambiguous. Importing a module itself (such as `import std::singleton;`) lets you refer to its items with a shorter path. + +A name can refer to both a symbol (such as a function or constant) and a type (such as a struct or type alias) at the same time, since they are in separate namespaces. Importing the name imports both. + +## Re-exports + +It's possible to re-export items, which makes them available to other modules as if they were declared in the current module: ```rue -export utils::*; +export conditions::*; +export utils::greet; ``` -## Module Block +This is how the standard library's prelude makes everything available in one place. -You can create a module by using the `mod` keyword followed by the name of the module. This is here for completeness more than anything, since most of the time you'll want to use multiple files instead. +## Module Blocks + +You can also create a module inside of a file by using the `mod` keyword followed by the name of the module: ```rue -mod utils { +mod math { export fn add(a: Int, b: Int) -> Int { a + b } } fn main() -> Int { - utils::add(42, 34) + math::add(42, 34) } ``` + +A module block can reference the items in the scope it's declared in, as well as its own items. Like files, only the items it exports are visible outside of it. diff --git a/docs/operators.md b/docs/operators.md index b34e1a8..19c78cf 100644 --- a/docs/operators.md +++ b/docs/operators.md @@ -12,21 +12,23 @@ slug: /operators | --- | ------- | ------------------------------------------------------ | | `+` | `1 + 2` | Adds two `Int` values and returns the sum. | | `-` | `1 - 2` | Subtracts two `Int` values and returns the difference. | -| `*` | `2 * 2` | Multiplies two `Int` values and return the product. | +| `*` | `2 * 2` | Multiplies two `Int` values and returns the product. | | `/` | `4 / 2` | Divides two `Int` values and returns the quotient. | | `%` | `3 % 2` | Divides two `Int` values and returns the remainder. | +Division rounds towards negative infinity, and the remainder has the same sign as the divisor. For example, `-200 / 3` is `-67`, and `-200 % 3` is `1`. You can use the [`divmod`](/docs/builtins.md#divmod) builtin to compute both at once. + :::note -The `+` operator can be used with `Bytes` values to concatenate them together. +The `+` operator can also be used with `Bytes` (or `String`) values to concatenate them together. -The `+`, `-`, and `*` operators can be used with `PublicKey` or `Signature` values to perform the corresponding BLS math operations (ie point addition, subtraction, or multiplication). +The `+` and `-` operators can be used with `PublicKey` or `Signature` values to perform BLS point addition and subtraction. The `*` operator can multiply a `PublicKey` or `Signature` by an `Int` scalar, with the point on the left (such as `public_key * 2`). ::: ### Unary | Op | Example | Description | | --- | ------- | -------------------------------------------------- | -| `+` | `+42` | An unnecessary no-op. | +| `+` | `+42` | Has no effect, and is reported by a lint. | | `-` | `-42` | Returns the negative equivalent of an `Int` value. | :::note @@ -35,24 +37,33 @@ The `-` operator can be used with `PublicKey` or `Signature` values to negate th ## Bitwise -| Op | Example | Description | -| ---- | ----------- | ------------------------------------------------------- | -| `<<` | `42 << 2` | Shifts the bits of the left hand side to the left. | -| `>>` | `42 >> 2` | Shifts the bits of the left hand side to the right. | -| `~` | `~42` | Performs a bitwise NOT on the bits of the `Int` value. | -| `&` | `42 & 100` | Performs a bitwise AND on the bits of the `Int` values. | -| `\|` | `42 \| 100` | Performs a bitwise OR on the bits of the `Int` values. | -| `^` | `42 ^ 100` | Performs a bitwise XOR on the bits of the `Int` values. | +| Op | Example | Description | +| ----- | ----------- | ----------------------------------------------------------------------------------- | +| `<<` | `42 << 2` | Shifts the bits of the left hand side to the left. | +| `>>` | `42 >> 2` | Shifts the bits of the left hand side to the right, preserving the sign. | +| `>>>` | `42 >>> 2` | Shifts the bits of the left hand side to the right, treating them as unsigned bits. | +| `~` | `~42` | Performs a bitwise NOT on the bits of the `Int` value. | +| `&` | `42 & 100` | Performs a bitwise AND on the bits of the `Int` values. | +| `\|` | `42 \| 100` | Performs a bitwise OR on the bits of the `Int` values. | +| `^` | `42 ^ 100` | Performs a bitwise XOR on the bits of the `Int` values. | + +:::info +The `>>>` operator is a logical shift. Since it treats the value as unsigned, shifting a negative number gives a positive result (for example, `-50 >>> 1` is `103`). It's useful for walking the bits of a path, such as in a merkle proof. +::: ## Logical -| Op | Example | Description | -| ------ | ----------------- | ------------------------------------------------- | -| `!` | `!true` | Returns `true` if `false`, and `false` if `true`. | -| `&&` | `true && false` | Lazy evaluates if both `Bool` values are `true`. | -| `\|\|` | `true \|\| false` | Lazy evaluates if either `Bool` value is `true`. | -| `&` | `true & false` | Returns whether both `Bool` values are `true`. | -| `\|` | `true \| false` | Returns whether either `Bool` value is `true`. | +| Op | Example | Description | +| ------ | ----------------- | ---------------------------------------------------------------------------------------- | +| `!` | `!true` | Returns `true` if `false`, and `false` if `true`. | +| `&&` | `true && false` | Returns whether both `Bool` values are `true`, only evaluating the right side if needed. | +| `\|\|` | `true \|\| false` | Returns whether either `Bool` value is `true`, only evaluating the right side if needed. | +| `&` | `true & false` | Returns whether both `Bool` values are `true`, always evaluating both. | +| `\|` | `true \| false` | Returns whether either `Bool` value is `true`, always evaluating both. | + +The `&&` and `||` operators short-circuit, so the right side is only evaluated if it's needed to determine the result. This makes them safe to use when the right side depends on the left side, such as `value is Int && value > 5`. However, short-circuiting requires extra branching in the generated code. + +The `&` and `|` operators on `Bool` values are compiled to the CLVM `all` and `any` operators, which always evaluate both sides. They are cheaper when both sides are simple and can't raise an error. ## Comparison @@ -64,7 +75,7 @@ The `-` operator can be used with `PublicKey` or `Signature` values to negate th | `>=` | `1 >= 2` | If the left side is greater than or equal to the right side. | :::note -The comparison operators can also be used with `Bytes` values, and the special byte-specific `>s` operator is used to implement this in [CLVM](https://chialisp.com/operators/#comparison). +The comparison operators can also be used with `Bytes` values, which compares them lexicographically. The byte-specific `>s` operator is used to implement this in [CLVM](https://chialisp.com/operators/#comparison). ::: ## Equality @@ -73,3 +84,32 @@ The comparison operators can also be used with `Bytes` values, and the special b | ---- | -------- | ------------------------------------------------ | | `==` | `1 == 2` | If the left side is equal to the right side. | | `!=` | `1 != 2` | If the left side is not equal to the right side. | + +Both sides must be atoms of the same kind, such as `Int`, `Bytes`, `Bool`, `PublicKey`, or `Signature`. Atoms are compared by their bytes, so an `Int` and a `Bytes` value need to be cast to the same type before they can be compared. + +To compare structs, pairs, or lists, use the [`deep_equal`](/docs/standard-library.md#utilities) function from the standard library, or compare their tree hashes. + +## Precedence + +Operators are listed from highest to lowest precedence. Operators with the same precedence are evaluated from left to right. + +| Operators | Description | +| --------------------------- | ---------------------------------- | +| `f()`, `.field`, `as`, `is` | Calls, field access, casts, guards | +| `!`, `-`, `+`, `~` (prefix) | Unary operators | +| `*`, `/`, `%` | Multiplicative | +| `+`, `-` | Additive | +| `<<`, `>>`, `>>>` | Shifts | +| `&` | Bitwise or logical AND | +| `^` | Bitwise XOR | +| `\|` | Bitwise or logical OR | +| `<`, `>`, `<=`, `>=` | Comparison | +| `==`, `!=` | Equality | +| `&&` | Short-circuiting AND | +| `\|\|` | Short-circuiting OR | + +:::tip +Since `is` and `as` bind more tightly than prefix operators, `!value is Int` is parsed as `!(value is Int)`. Writing the parentheses explicitly makes this easier to read. + +Also, the type after `is` or `as` can be a union, so `value is Int | other` is read as a guard against the type `Int | other`. Use parentheses when combining a guard or cast with `|`, such as `(value is Int) | (other is Int)`. +::: diff --git a/docs/projects.md b/docs/projects.md new file mode 100644 index 0000000..b27fab0 --- /dev/null +++ b/docs/projects.md @@ -0,0 +1,106 @@ +--- +slug: /projects +--- + +# Projects + +A Rue project is a directory with a `Rue.toml` manifest, and a directory of `.rue` source files. + +You can create one with `rue init`: + +```bash +rue init my-project +``` + +This creates the following files: + +``` +my-project +├── Rue.toml +└── puzzles + └── main.rue +``` + +Every `.rue` file inside of the `puzzles` directory (including in subdirectories) is part of the project, and can reference the others as [modules](/docs/modules.md). + +## Finding the Project + +When you run a command such as `rue build` or `rue test`, the CLI searches for the project that the current directory (or the file you pass to it) belongs to: + +1. The nearest `Rue.toml` in the directory or any of its parents is used, if there is one. So you can run commands from anywhere inside a project. +2. Otherwise, the nearest directory with a `main.rue` file is treated as the project, using the default settings. +3. Otherwise, a single `.rue` file is compiled by itself. + +## Manifest + +The `Rue.toml` file configures the compiler, the formatter, and which lints are reported. The `[compiler]` section is required, but all of its keys are optional. Here's what `rue init` generates: + +```toml +[compiler] +version = "0.12.0" +entrypoint = "puzzles" + +[formatter] +max_width = 100 +indent_width = 4 +``` + +### Compiler + +| Key | Default | Description | +| ------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `version` | Not set | The version of Rue that the project is written for. If it's set and doesn't match the installed version of the CLI, `rue build` fails (`rue test` doesn't check it). | +| `entrypoint` | `"puzzles"` | The directory (or file) containing the source code, relative to `Rue.toml`. | +| `std` | `true` | Whether to include the [standard library](/docs/standard-library.md). Set this to `false` to only have access to [builtins](/docs/builtins.md). | +| `dist_dir` | Not set | The directory that `rue build --all` writes compiled programs to, relative to the directory the command is run from. If it's not set, each program is written next to its source file. | + +### Formatter + +| Key | Default | Description | +| -------------- | ------- | -------------------------------------------------------- | +| `max_width` | `100` | The maximum width of a line before it's broken up. | +| `indent_width` | `4` | The number of spaces used for each level of indentation. | + +See [Formatting](/docs/formatting.md) for more details. + +### Lints + +The `[lints]` section sets the level of individual lints or lint groups: + +```toml +[lints] +unused = "deny" +unused_binding = "allow" +``` + +See [Lints](/docs/lints.md) for the list of lints and how their levels are resolved. + +## Entrypoints + +The `main` function in `main.rue` is the project's primary entrypoint, and is what `rue build` compiles by default. + +Each file can also have its own `main` function, which can be compiled by passing the file to the CLI: + +```bash +rue build puzzles/other.rue +``` + +And any exported function can be compiled with `--export`: + +```bash +rue build --export my_puzzle +``` + +See [Functions](/docs/functions.md#entrypoints) for more on how entrypoints are compiled. + +## Building Everything + +When a project contains multiple puzzles, you can compile all of them at once: + +```bash +rue build --all +``` + +This compiles the `main` function of every file, as well as every exported function in `main.rue`, and writes each one as a hex file. Add `--hash` to also write the tree hash of each program. + +By default, the files are written next to their source file, and exports are prefixed with the name of the file they're in (such as `puzzles/main.rue.hex` and `puzzles/main.rue_my_puzzle.rue.hex`). If `dist_dir` is set in `Rue.toml`, they are all written to that directory instead, and are named after just the file or export (such as `dist/main.rue.hex` and `dist/my_puzzle.rue.hex`). Since those names can collide, two programs with the same name are an error. diff --git a/docs/security.md b/docs/security.md index 2c9646e..c5ff00d 100644 --- a/docs/security.md +++ b/docs/security.md @@ -4,18 +4,16 @@ slug: /security # Security +Puzzles control real value on the blockchain, and anyone can choose the solution they spend a coin with. So it's important to keep in mind what the type system can and can't guarantee. + ## Untrusted Values -While Rue's type system aims to provide the means to comprehensively check the type of values at runtime, the types of values passed into the `main` function are currently assumed to be correct by default. +While Rue's type system aims to provide the means to comprehensively check the type of values at runtime, the types of the parameters of the `main` function are assumed to be correct. Nothing checks that a solution actually matches the types you declared. This means that a program like this is actually incorrect: ```rue -fn main( - parent_coin_id: Bytes32, - puzzle_hash: Bytes32, - amount: Int, -) -> Bytes32 { +fn main(parent_coin_id: Bytes32, puzzle_hash: Bytes32, amount: Int) -> Bytes32 { sha256(parent_coin_id + puzzle_hash + amount as Bytes) } ``` @@ -29,11 +27,7 @@ This is what led to the [CAT1 vulnerability](https://www.chia.net/2022/07/29/cat The solution is to use a more general type and check the invariants you care about at runtime: ```rue -fn main( - parent_coin_id: Bytes, - puzzle_hash: Bytes, - amount: Int, -) -> Bytes32 { +fn main(parent_coin_id: Bytes, puzzle_hash: Bytes, amount: Int) -> Bytes32 { assert parent_coin_id is Bytes32; assert puzzle_hash is Bytes32; @@ -41,10 +35,30 @@ fn main( } ``` -Or you can use the builtin `calculate_coin_id` function: +Or you can use the builtin [`coinid`](/docs/builtins.md#coinid) function, which checks the lengths for you: ```rue -calculate_coin_id(parent_coin_id, puzzle_hash, amount) +fn main(parent_coin_id: Bytes32, puzzle_hash: Bytes32, amount: Int) -> Bytes32 { + coinid(parent_coin_id, puzzle_hash, amount) +} ``` -Now, if someone tried to play tricks with the lengths, the assertions would fail and the program would raise an error. +Now, if someone tried to play tricks with the lengths, the program would raise an error. + +## Untrusted Structure + +The same applies to the structure of values. If a parameter is declared as a struct or a list, an attacker can pass an atom, a shorter list, or a list with extra values instead. Accessing a field of a value that isn't a pair raises an error, which is usually safe, but anything that depends on the exact contents of a value (such as a hash) should be checked. + +When in doubt, accept a broader type (such as `Any`) and narrow it with a [type guard](/docs/type-system/guards.md), which emits the runtime checks for you. + +## Other Things to Watch Out For + +- `inline if` evaluates both branches, so an error in the branch that isn't selected still causes the program to raise. See [Inline If](/docs/control-flow.md#inline-if). +- `nil`, `0`, `false`, and `""` are the same value at runtime, so a type guard can't distinguish between them. See [Type Guards](/docs/type-system/guards.md#overlapping-values). +- Byte values with leading zeros aren't equal to the integer they appear to represent. See [Int](/docs/type-system/atoms.md#int). +- `unchecked_cast` bypasses the type system entirely. See [Unchecked Casts](/docs/type-system/casting.md#unchecked-casts). +- Puzzles compiled with `--debug` aren't meant to be deployed. See [Debugging](/docs/debugging.md). + +:::warning +The example puzzles in the Rue repository have not been audited, and are for educational purposes only. Have puzzles that hold real value reviewed carefully before deploying them. +::: diff --git a/docs/standard-library.md b/docs/standard-library.md new file mode 100644 index 0000000..9be4404 --- /dev/null +++ b/docs/standard-library.md @@ -0,0 +1,188 @@ +--- +slug: /standard-library +--- + +# Standard Library + +Rue comes with a standard library, which is written in Rue itself. It provides types for the conditions a puzzle can output, functions for tree hashing and currying, and other common utilities. + +The standard library is included by default, and can be disabled by setting `std = false` in the [`Rue.toml`](/docs/projects.md#compiler) manifest. Like any other code, only the parts you use are included in the compiled program. + +## Prelude + +The items most commonly used in puzzles are in the prelude, which is available in every file without importing anything. This includes all of the [conditions](#conditions), [condition opcodes](#opcodes), [message flags](#message-flags), [tree hashing](#tree-hashing) functions, [merkle proofs](#merkle-proofs), and [utilities](#utilities). + +## Modules + +Everything in the standard library can also be referenced with a path through the `std` module, including a few modules that aren't part of the prelude: + +| Module | Contents | +| ---------------------- | -------------------------------------------------------------------- | +| `std::conditions` | The `types`, `opcodes` and `message_flags` modules for conditions. | +| `std::tree_hash` | `tree_hash`, `tree_hash_atom`, and `tree_hash_pair`. | +| `std::curry_tree_hash` | `curry_tree_hash`. | +| `std::merkle` | `MerkleProof`, `calculate_merkle_root`, and `simplify_merkle_proof`. | +| `std::utils` | `merge_list` and `deep_equal`. | +| `std::offer` | `NotarizedPayment` and `Payment`, for settlement payments in offers. | +| `std::singleton` | `SingletonStruct` and the singleton lineage proofs. | + +For example: + +```rue +import std::singleton::LineageProof; + +fn main(proof: LineageProof) -> Int { + proof.parent_amount +} +``` + +## Conditions + +A puzzle outputs a list of conditions, which tell the blockchain what the spend should do (such as creating coins) and what must be true for the spend to be valid (such as signatures and announcements). The standard library defines a struct for each condition, and the `Condition` type is a union of all of them. + +For example, this puzzle requires a signature on the conditions, and then outputs them: + +```rue +fn main(public_key: PublicKey, conditions: List) -> List { + let agg_sig = AggSigMe { public_key, message: tree_hash(conditions) }; + [agg_sig, ...conditions] +} +``` + +Each struct has an `opcode` field with a [literal type](/docs/type-system/atoms.md#literal-types) and a default value, so you don't need to specify it when creating one, and you can tell the conditions apart with a [type guard](/docs/type-system/guards.md). + +| Struct | Fields | +| ----------------------------- | --------------------------------------------------------------------- | +| `Remark` | `...rest: Any = nil` | +| `AggSigParent` | `public_key: PublicKey`, `message: Bytes` | +| `AggSigPuzzle` | `public_key: PublicKey`, `message: Bytes` | +| `AggSigAmount` | `public_key: PublicKey`, `message: Bytes` | +| `AggSigPuzzleAmount` | `public_key: PublicKey`, `message: Bytes` | +| `AggSigParentAmount` | `public_key: PublicKey`, `message: Bytes` | +| `AggSigParentPuzzle` | `public_key: PublicKey`, `message: Bytes` | +| `AggSigUnsafe` | `public_key: PublicKey`, `message: Bytes` | +| `AggSigMe` | `public_key: PublicKey`, `message: Bytes` | +| `CreateCoin` | `puzzle_hash: Bytes32`, `amount: Int`, `...memos: Memos \| nil = nil` | +| `ReserveFee` | `amount: Int` | +| `CreateCoinAnnouncement` | `message: Bytes` | +| `AssertCoinAnnouncement` | `id: Bytes32` | +| `CreatePuzzleAnnouncement` | `message: Bytes` | +| `AssertPuzzleAnnouncement` | `id: Bytes32` | +| `AssertConcurrentSpend` | `coin_id: Bytes32` | +| `AssertConcurrentPuzzle` | `puzzle_hash: Bytes32` | +| `SendMessage` | `mode: Int`, `message: Bytes`, `...receiver: List` | +| `ReceiveMessage` | `mode: Int`, `message: Bytes`, `...sender: List` | +| `AssertMyCoinId` | `coin_id: Bytes32` | +| `AssertMyParentId` | `parent_id: Bytes32` | +| `AssertMyPuzzleHash` | `puzzle_hash: Bytes32` | +| `AssertMyAmount` | `amount: Int` | +| `AssertMyBirthSeconds` | `seconds: Int` | +| `AssertMyBirthHeight` | `height: Int` | +| `AssertEphemeral` | None | +| `AssertSecondsRelative` | `seconds: Int` | +| `AssertSecondsAbsolute` | `seconds: Int` | +| `AssertHeightRelative` | `height: Int` | +| `AssertHeightAbsolute` | `height: Int` | +| `AssertBeforeSecondsRelative` | `seconds: Int` | +| `AssertBeforeSecondsAbsolute` | `seconds: Int` | +| `AssertBeforeHeightRelative` | `height: Int` | +| `AssertBeforeHeightAbsolute` | `height: Int` | +| `Softfork` | `cost: Int`, `...args: List` | + +The memos of a `CreateCoin` condition are wrapped in a `Memos` struct, which has a single `value: Any` field: + +```rue +fn main(puzzle_hash: Bytes32) -> CreateCoin { + CreateCoin { puzzle_hash, amount: 1, memos: Memos { value: [puzzle_hash] } } +} +``` + +See the [Chia documentation](https://docs.chia.net/conditions/) for what each condition does. + +### Opcodes + +The opcode of each condition is also available as a constant, named in `SCREAMING_SNAKE_CASE` (such as `CREATE_COIN`, which is `51`). This is useful when working with raw conditions. + +### Message Flags + +The `mode` of a `SendMessage` or `ReceiveMessage` condition specifies which parts of the sender and receiver coins are committed to. The following constants can be combined with the `|` operator: + +| Constant | Value | +| ----------------- | ---------- | +| `SENDER_COIN` | `0b111000` | +| `SENDER_PARENT` | `0b100000` | +| `SENDER_PUZZLE` | `0b010000` | +| `SENDER_AMOUNT` | `0b001000` | +| `RECEIVER_COIN` | `0b000111` | +| `RECEIVER_PARENT` | `0b000100` | +| `RECEIVER_PUZZLE` | `0b000010` | +| `RECEIVER_AMOUNT` | `0b000001` | + +For example: + +```rue +fn main(puzzle_hash: Bytes32) -> SendMessage { + SendMessage { mode: SENDER_COIN | RECEIVER_PUZZLE, message: "hello", receiver: [puzzle_hash] } +} +``` + +## Tree Hashing + +The tree hash of a value is the standard way to hash CLVM values, and the tree hash of a program is its puzzle hash. + +| Function | Description | +| ---------------------------------------------------------- | ------------------------------------------------------------------------------ | +| `tree_hash(value: Any) -> Bytes32` | Computes the tree hash of any value, recursively. | +| `tree_hash_atom(value: Bytes) -> Bytes32` | Computes the tree hash of an atom. | +| `tree_hash_pair(first: Bytes32, rest: Bytes32) -> Bytes32` | Computes the tree hash of a pair, given the tree hashes of its first and rest. | + +If you already know that a value is an atom, or have the tree hashes of the values in a pair, `tree_hash_atom` and `tree_hash_pair` are much cheaper than `tree_hash`. + +### Currying + +`curry_tree_hash(mod_hash: Bytes32, parameters: List) -> Bytes32` computes the puzzle hash of a program with the given parameters curried in, given the tree hash of the program and the tree hash of each parameter. + +This is how a puzzle can calculate the puzzle hash of another puzzle (or a new version of itself), without needing to reveal the whole program: + +```rue +fn main(mod_hash: Bytes32, owner: Bytes32) -> Bytes32 { + curry_tree_hash(mod_hash, [tree_hash_atom(mod_hash), tree_hash_atom(owner)]) +} +``` + +## Merkle Proofs + +| Item | Description | +| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| `MerkleProof` | A struct with a `path: Int`, followed by the list of sibling `hashes` up the tree. | +| `calculate_merkle_root(path: Int, current_hash: Bytes32, additional_steps: List) -> Bytes32` | Computes the root of a merkle tree, given the hash of a node and its siblings. | +| `simplify_merkle_proof(leaf: Bytes32, proof: MerkleProof) -> Bytes32` | Computes the root of a merkle tree, given a leaf value and a proof. | + +## Utilities + +| Function | Description | +| -------------------------------------------------- | ------------------------------------------------------------------- | +| `merge_list(a: List, b: List) -> List` | Returns a list with the items of `a`, followed by those of `b`. | +| `deep_equal(a: Any, b: Any) -> Bool` | Returns whether two values are structurally equal, including pairs. | + +## Offers + +The `std::offer` module contains types for the settlement payments puzzle, which is used by offers: + +| Struct | Fields | +| ------------------ | --------------------------------------------------------------- | +| `NotarizedPayment` | `nonce: Bytes32`, `...payments: List` | +| `Payment` | `puzzle_hash: Bytes32`, `amount: Int`, `...memos: Memos \| nil` | + +## Singletons + +The `std::singleton` module contains types used by the singleton puzzle: + +| Item | Description | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `SingletonStruct` | The singleton's `mod_hash`, `launcher_id`, and `...launcher_puzzle_hash`. | +| `LineageProof` | Proves the parent was the same singleton, with `parent_parent_coin_info`, `parent_inner_puzzle_hash`, and `parent_amount`. | +| `EveProof` | Proves the parent was the launcher, with `parent_parent_coin_info` and `parent_amount`. | +| `Proof` | A union of `LineageProof` and `EveProof`. | + +See the [singleton example](https://github.com/xch-dev/rue/blob/main/examples/puzzles/singleton.rue) for how these are used. diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..251effc --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,64 @@ +--- +slug: /testing +--- + +# Testing + +Rue has a built-in test runner, so you can write unit tests right alongside your code. Tests are just functions marked with `test`: + +```rue +fn factorial(num: Int) -> Int { + if num > 1 { + num * factorial(num - 1) + } else { + 1 + } +} + +test fn factorial_works() { + assert factorial(0) == 1; + assert factorial(5) == 120; +} +``` + +You can run every test in the project with: + +```bash +rue test +``` + +If you pass a file or directory, it's used to find the project, and all of that project's tests are run. A file that isn't part of a project is tested by itself: + +```bash +rue test scratch.rue +``` + +## How Tests Run + +Each test function is compiled as its own program, in debug mode, and run with an empty solution. A test passes if it finishes without raising an error, and returns `nil`. + +The output shows each test as it runs, and the reason for any failure. For example, if there was also a `factorial_fails` test with an incorrect assertion: + +``` +Running test `factorial_works` (1/2) +Running test `factorial_fails` (2/2) +Test failed due to raise: "assertion failed at main.rue:15:5" +``` + +Since tests are compiled in debug mode, failed assertions and `raise` statements include the location they occurred at, and [debug statements](/docs/debugging.md) print their values as the test runs. + +Test functions aren't included when compiling the program normally, so they don't affect the size or cost of your puzzles. + +## Cost Limit + +To prevent a test that never ends (such as one with infinite recursion) from hanging, each test stops once its CLVM cost passes 11,000,000,000, which is the same as Chia's block cost limit. You can change the limit with `--max-cost`: + +```bash +rue test --max-cost 100000000 +``` + +This is also a useful way to make sure that a puzzle stays within a certain cost. + +## Testing Puzzles + +Tests are great for checking the logic of individual functions. To test a full puzzle with real coins, signatures, and conditions, you can use a simulator like the one in the [Chia Wallet SDK](https://github.com/xch-dev/chia-wallet-sdk), which can compile Rue code directly. The [tutorials](/docs/tutorials/password.md) show how to set this up. diff --git a/docs/tutorials/password.md b/docs/tutorials/password.md index 7e21572..2e8a314 100644 --- a/docs/tutorials/password.md +++ b/docs/tutorials/password.md @@ -6,8 +6,8 @@ Before we get started, make sure you have [installed Rue](/docs/installation.md) This was last tested with the following versions: -- **Rue**: 0.6.0 -- **Wallet SDK**: 0.32.0 +- **Rue**: 0.12.0 +- **Wallet SDK**: 0.38.0 :::warning This is for educational purposes only. It's not secure enough to be used in production, so we'll be using a local simulator instead. diff --git a/docs/tutorials/signature.md b/docs/tutorials/signature.md index 17a0f33..79e3e1c 100644 --- a/docs/tutorials/signature.md +++ b/docs/tutorials/signature.md @@ -6,8 +6,8 @@ Before we get started, make sure you have [installed Rue](/docs/installation.md) This was last tested with the following versions: -- **Rue**: 0.6.0 -- **Wallet SDK**: 0.32.0 +- **Rue**: 0.12.0 +- **Wallet SDK**: 0.38.0 :::info This is for educational purposes only. While it's secure, there are standard puzzles that accomplish the same thing (with more interoperability with wallets). diff --git a/docs/type-system/aliases.md b/docs/type-system/aliases.md index 98b8c5f..effe7a8 100644 --- a/docs/type-system/aliases.md +++ b/docs/type-system/aliases.md @@ -11,7 +11,7 @@ For example: ```rue type MathOp = fn(a: Int, b: Int) -> Int; -fn adder(a: Int, y: Int) -> Int { +fn adder(a: Int, b: Int) -> Int { a + b } @@ -20,22 +20,41 @@ fn get_adder() -> MathOp { } ``` +An alias is just another name for the type, so it can be assigned to and from the original type without a cast. + +## Generic Aliases + +A type alias can have [generic](/docs/type-system/generics.md) type parameters, which are substituted when the alias is used: + +```rue +type Pair = (T, T); + +fn swap(pair: Pair) -> Pair { + (pair.rest, pair.first) +} +``` + ## Recursion You can use type aliases for recursive type definitions: ```rue -type List = nil | (T, List); +type Tree = Int | (Tree, Tree); + +fn sum_tree(tree: Tree) -> Int { + if tree is Int { + return tree; + } + + sum_tree(tree.first) + sum_tree(tree.rest) +} ``` -The type system should be equipped to handle recursive types like this, and they are quite useful for modeling complex CLVM values. +The type system is equipped to handle recursive types like this, and they are quite useful for modeling complex CLVM values. Builtin types such as `List` and `Any` are defined this way. -:::warning -There is currently nothing preventing you from making a type that _always_ references itself (without any base case or nesting): +However, a type must pass through a pair before it refers to itself. A type that refers to itself directly (or through a union, or another alias) without any nesting is an error, since it doesn't describe any actual value: ```rue -type Value = Value; +// Error: Type `Value` refers to itself without passing through a pair +type Value = Value | Int; ``` - -This type will allow any value to be assigned to it, and some things may unexpectedly fail. A future release will likely forbid such type declarations from being created. -::: diff --git a/docs/type-system/atoms.md b/docs/type-system/atoms.md index 494cf2c..4af5d99 100644 --- a/docs/type-system/atoms.md +++ b/docs/type-system/atoms.md @@ -21,6 +21,22 @@ There are multiple types of atoms: 11. **Int** - a signed integer of arbitrary size 12. **Bool** - either `true` or `false` +## Literals + +| Literal | Example | Type | +| ------- | ----------------- | ---------------------------------------------------------------------------- | +| Integer | `42`, `1_000_000` | `Int` | +| Hex | `0xCAFE_F00D` | `Bytes` (or `Bytes32`, `PublicKey`, or `Signature`, depending on the length) | +| Binary | `0b101010` | `Int` | +| Octal | `0o52` | `Int` | +| String | `"Hello, world!"` | `String` | +| Boolean | `true`, `false` | `Bool` | +| Nil | `nil` | `nil` | + +Underscores can be used anywhere in a number to make it easier to read. Hex literals with an odd number of digits are padded with a leading zero, so `0x1` is the same as `0x01`. + +Strictly speaking, the type of a literal is more specific than shown here. See [Literal Types](#literal-types) below. + ## Atom The plain `Atom` type should be used when you don't care about the semantics of the value. Any other atom type can be assigned to `Atom` without requiring a cast, whereas a cast is required to go from `Atom` to anything else. @@ -48,7 +64,10 @@ The `Bytes32` type represents any `Bytes` value with a length of 32. If a hex literal or string literal produces a value that is exactly 32 bytes, it will be compatible with this type automatically. However, if you have an atom with an unknown length, you will need to check the type first: ```rue -assert value is Bytes32; +fn main(value: Bytes) -> Bytes32 { + assert value is Bytes32; + value +} ``` This will emit code at runtime to check that the value has a length of 32. @@ -59,7 +78,7 @@ This will emit code at runtime to check that the value has a length of 32. ## String -The `String` type represents a UTF-8 encoded string. It's functionally equivalent to `Bytes`, but provides a more descriptive name for working with text values, and hints to the compiler that the value is a string rather than a sequence of bytes (which is useful for error messages). +The `String` type represents a UTF-8 encoded string. It's functionally equivalent to `Bytes` (and they can be assigned to each other without a cast), but provides a more descriptive name for working with text values, and hints to the compiler that the value is a string rather than a sequence of bytes (which is useful for error messages). ## PublicKey @@ -67,12 +86,16 @@ The `PublicKey` type represents a [BLS12-381](https://en.wikipedia.org/wiki/BLS_ An atom must be 48 bytes long to be compatible with `PublicKey`, although there is typically no harm done by not verifying the length at runtime before using it in conditions or BLS opcodes, as long as it's not directly concatenated with other bytes. +Public keys can be added, subtracted, negated, and multiplied by an `Int` with the [arithmetic operators](/docs/operators.md#arithmetic). The `INFINITY_G1` [builtin](/docs/builtins.md#constants) is the identity element. + ## Signature The `Signature` type represents a [BLS12-381](https://en.wikipedia.org/wiki/BLS_digital_signature) signature (also commonly referred to as a G2 element). An atom must be 96 bytes long to be compatible with `Signature`, although there is typically no harm done by not verifying the length at runtime before using it in conditions or BLS opcodes, as long as it's not directly concatenated with other bytes. +Signatures support the same operators as public keys. The `INFINITY_G2` [builtin](/docs/builtins.md#constants) is the identity element. + ## K1PublicKey The `K1PublicKey` type represents a secp256k1 public key. @@ -99,23 +122,43 @@ An atom must be 64 bytes long to be compatible with `R1Signature`, although ther ## Int -The `Int` type represents any integer value, positive or negative. You can use arithmetic and comparison operators with integers. +The `Int` type represents any integer value, positive or negative. You can use arithmetic, bitwise, and comparison operators with integers. -You can construct a value that is compatible with `Int` by using integer literals such as `42`. +You can construct a value that is compatible with `Int` by using integer literals such as `42`, as well as binary and octal literals. -You can also cast other atom types to `Int` when needed. +You can also cast other atom types to `Int` when needed. For example, `0x05 as Int` is `5`. + +:::warning +CLVM integers are stored as the shortest signed big-endian representation of their value. So a byte value like `0x00` or `0x80` is not the same as the integer `0` or `128` (which are `nil` and `0x0080` respectively). The `bytes_int_confusion` [lint](/docs/lints.md) warns when you cast a literal like this to `Int`. +::: ## Bool `Bool` is simply a union of the literal values `true` and `false`. You can use logical operators with boolean values. +At runtime, `true` is represented as `1`, and `false` is represented as `nil`. + +## Length + +Every atom type has a `length` field (except for unions of atoms such as `Bool`, which need to be cast first), which returns the number of bytes in the value as an `Int`: + +```rue +fn main(value: Bytes) -> Int { + value.length +} +``` + +This compiles to the CLVM `strlen` operator. + ## Representation Because the various atom types differ solely by semantic meaning, there can be overlap in their CLVM representation. This is important to know when you need to differentiate between different values at runtime. For example, the values `nil`, `false`, `0`, `""`, and `[]` all have the same runtime representation (even though each of them are semantically different and would require a cast to one another). -## Value Types +This is also why a type guard can't distinguish between `Int` and `nil`, since `0` and `nil` are the same value. + +## Literal Types In most languages, the type of literal values is general enough to cover all other values. For example, `42` would have the type `Int`. This is for a few reasons: @@ -125,6 +168,16 @@ In most languages, the type of literal values is general enough to cover all oth However, in Rue it's not possible to reassign to a variable, and we can use union types to alleviate some of the frustration that would be caused by a type being too specific. -Thus, every literal value has a corresponding type - for example, `42` has the type `42`. This can be surprising in some situations, but it's also important to make the language work. +Thus, every literal value has a corresponding type - for example, `42` has the type `42`. This can be surprising in some situations, but it's also important to make the language work. A literal type is assignable to its general type (such as `Int`), but not the other way around. + +You can also write literal types yourself, which is useful for values that must be exactly one of a few options: + +```rue +type Mode = 0 | 1 | 2; + +fn main(mode: Mode) -> Bool { + mode == 2 +} +``` -It allows for more efficient type checking, disambiguation of values at runtime, and preventing certain logic errors at compile time. +It allows for more efficient type checking, disambiguation of values at runtime, and preventing certain logic errors at compile time. For example, the `opcode` field of each [condition](/docs/standard-library.md#conditions) in the standard library has a literal type, which is how the type of a condition can be narrowed with a type guard. diff --git a/docs/type-system/casting.md b/docs/type-system/casting.md new file mode 100644 index 0000000..e6993b2 --- /dev/null +++ b/docs/type-system/casting.md @@ -0,0 +1,53 @@ +--- +slug: /casting +--- + +# Casting + +A cast changes the type of a value at compile time, without changing the value itself or emitting any code at runtime. It's written with the `as` keyword. + +## Semantic Casts + +Some types have the same runtime representation, but are semantically different. For example, an `Int` and a `Bytes` value are both atoms, but they are treated differently by operators. Assigning one to the other requires a cast, to make sure it's intentional: + +```rue +fn main(value: Bytes) -> Int { + value as Int + 1 +} +``` + +The same goes for [structs](/docs/type-system/structs.md#semantics), which are lists at runtime, but can't be assigned to and from lists or other structs without a cast: + +```rue +struct Point { + x: Int, + y: Int, +} + +fn main() -> Point { + [1, 2] as Point +} +``` + +## What Can Be Cast + +A cast is only allowed if the value is already known to have the structure of the target type. So you can cast between atom types, or between pairs, lists, and structs with the same layout. However, you can't use a cast to check something that's only known at runtime, such as: + +1. Casting a pair to an atom, or an atom to a pair, which is an error since they have different runtime representations. +2. Casting to a narrower type, such as `Bytes` to `Bytes32` or `Any` to `Int`, which requires a [type guard](/docs/type-system/guards.md) to check the value at runtime. + +Casting to a type that the value is already compatible with is reported by the `unnecessary_cast` [lint](/docs/lints.md). + +## Unchecked Casts + +If you need to cast a value to a type that it can't be cast to normally, you can use the `unchecked_cast` builtin. It changes the type to anything you want, without any checks at compile time or at runtime: + +```rue +fn main(value: Any) -> Int { + unchecked_cast::(value) +} +``` + +:::danger +An unchecked cast tells the compiler to trust you, so if the value doesn't actually match the type, the program can behave in unexpected ways. This is especially dangerous for values that come from the solution of a puzzle, which an attacker can choose. Prefer a type guard whenever possible. +::: diff --git a/docs/type-system/generics.md b/docs/type-system/generics.md new file mode 100644 index 0000000..6ceb777 --- /dev/null +++ b/docs/type-system/generics.md @@ -0,0 +1,111 @@ +--- +slug: /generics +--- + +# Generics + +Generics let you write functions and types that work with any type, instead of writing a separate version for each one. + +## Generic Functions + +A generic function declares its type parameters in angle brackets after its name, and can use them in its parameters, return type, and body: + +```rue +fn identity(value: T) -> T { + value +} +``` + +When you call a generic function, the compiler infers the type parameters from the arguments you pass: + +```rue +fn main() -> Int { + identity(42) +} +``` + +Here's a more useful example, which applies a function to every item in a list: + +```rue +fn map(list: List, function: fn(value: T) -> U) -> List { + if list is nil { + return nil; + } + + [function(list.first), ...map(list.rest, function)] +} + +fn main() -> List { + map([1, 2, 3], fn(value: Int) => value * 2) +} +``` + +The types are inferred from every argument, as well as the expected return type if there is one. + +### Explicit Arguments + +If a type parameter can't be inferred from the arguments or the expected type, you need to specify the generic arguments explicitly with `::<...>` (known as the turbofish syntax): + +```rue +fn empty() -> List { + nil +} + +fn main() -> List { + let items = empty::(); + ["hello", ...items] +} +``` + +You can use `_` as a placeholder for any argument that should still be inferred: + +```rue +fn wrap(value: A) -> (A, B | nil) { + (value, nil) +} + +fn main() -> Int { + let pair = wrap::<_, Bytes>(1); + pair.first + 1 +} +``` + +## Generic Types + +[Structs](/docs/type-system/structs.md#generic-structs) and [type aliases](/docs/type-system/aliases.md#generic-aliases) can also have type parameters: + +```rue +struct Box { + value: T, +} + +type Pair = (T, T); +``` + +When you use a generic type, you need to provide its arguments, such as `Box` or `Pair`. The builtin `List` and `AlternatingList` types are generic type aliases. + +## Generic Function Types + +A [function type](/docs/functions.md#function-types) can have its own type parameters, which means the function must work for any type: + +```rue +fn identity(value: T) -> T { + value +} + +fn twice(function: fn(value: U) -> U, value: T) -> T { + function(function(value)) +} + +fn main() -> Int { + twice(identity, 42) +} +``` + +A generic function can also be assigned to a non-generic function type, as long as it's compatible once its type parameters are filled in. For example, `identity` can be used as a `fn(value: Int) -> Int`. + +Lambdas can be generic as well, such as `fn(value: U): U => value`. + +## Limitations + +A generic type parameter could be any type at runtime, so values of a generic type can't be checked with a [type guard](/docs/type-system/guards.md#generic-types), and you can't access fields on them. You can still pass them around, store them in pairs and structs, and return them. diff --git a/docs/type-system/guards.md b/docs/type-system/guards.md index d469e35..89064d4 100644 --- a/docs/type-system/guards.md +++ b/docs/type-system/guards.md @@ -2,60 +2,140 @@ slug: /guards --- -# Guards +# Type Guards -A type guard allows you to check a value at runtime and change the type at compile time to match. +A type guard allows you to check a value at runtime and change the type at compile time to match. It's written with the `is` keyword, and evaluates to a `Bool`. As a simple example, you can check the length of values: ```rue -assert bytes is Bytes32; +fn main(bytes: Bytes) -> Bytes32 { + assert bytes is Bytes32; + bytes +} ``` After this assertion, the type of `bytes` is now `Bytes32` since it has been checked. -However, if you negate a type guard with the `!` operator or use the value in an else branch, it will revert to the `Bytes` type since there was no union that could be narrowed: +However, if you negate a type guard with the `!` operator or use the value in an else branch, it will remain the `Bytes` type since there was no union that could be narrowed: ```rue -assert !(bytes is Bytes32); +fn main(bytes: Bytes) -> Bytes { + assert !(bytes is Bytes32); + bytes +} ``` -## Subtraction +## What's Checked + +The compiler emits the minimum set of checks needed to verify that the value on the left matches the type on the right. It skips any checks that are already implied by the type on the left. Depending on the types involved, it can check: + +1. Whether the value is an atom or a pair, such as `value is Bytes` or `value is (Any, Any)`. +2. The length of an atom, such as `value is Bytes32` or `value is PublicKey`. +3. The exact value of an atom, for [literal types](/docs/type-system/atoms.md#literal-types), such as `value is 42` or `value is nil`. +4. Each of the above for the `first` and `rest` of a pair, recursively. + +Since a struct is a list at runtime, checking for a struct checks its structure and any fields with literal types. For example, every [condition](/docs/standard-library.md#conditions) in the standard library has a literal `opcode`, so if you already know that a value is a `Condition`, checking whether it's a `CreateCoin` only needs to compare the opcode to `51`. + +## Narrowing Type guards can be used to narrow the type of a union to one or more of its variants. Let's say you have a union of structurally distinct types: ```rue -type Condition = CreateCoin | ReserveFee; +fn fee(condition: CreateCoin | ReserveFee) -> Int { + if condition is CreateCoin { + // The type is CreateCoin in this branch + 0 + } else { + // The type is ReserveFee in this branch + condition.amount + } +} ``` -You can check the type, and depending on the branch the value will have the correct narrowed type: +The else branch removes `CreateCoin` as a possibility, narrowing it down to the opposite, which is `ReserveFee`. This works regardless of how many variants you have in the union. + +The narrowed type applies anywhere the result of the guard is known: + +1. In the branches of an `if` expression. +2. After an `if` statement that returns or raises, using the opposite of the condition. +3. After an `assert` statement. +4. On the right side of `&&` and `||`, such as `value is Int && value > 5`. + +Guards can be combined with `!`, `&&`, `||`, `&`, and `|`, and the compiler will narrow each value based on what's known in each branch: ```rue -if condition is CreateCoin { - // The type is CreateCoin in this branch -} else { - // The type is ReserveFee in this branch +fn add(x: Int | (Int, Int), y: Int | (Int, Int)) -> Int { + if x is Int && y is Int { + x + y + } else { + 0 + } } ``` -Subtraction is the mechanism in which `CreateCoin | ReserveFee` can remove `CreateCoin` as a possibility in the else branch, narrowing it down into the opposite, which is `ReserveFee`. This should work regardless of how many variants you have in the union. +:::warning +The type after `is` can be a union, so a `|` directly after a guard is read as part of the type. Wrap each guard in parentheses before combining them with `|`, such as `(x is Int) | (y is Int)`. The same applies to casts with `as`. +::: -## Function Types +### Fields -Rue supports [higher-order functions](https://en.wikipedia.org/wiki/Higher-order_function), which means functions can be passed around freely as values. As such, it's possible to express functions as types. +You can also guard a field of a pair or struct, such as `pair.first` or `point.x`. This narrows the type of that field wherever it's accessed through the same value: + +```rue +struct Point { + x: Int | (Int, Int), + y: Int, +} + +fn sum(point: Point) -> Int { + if point.x is Int { + point.x + point.y + } else { + point.y + } +} +``` + +This works for nested fields as well, such as `outer.inner.x`. + +## Lints + +The compiler warns about type guards that don't do anything useful: + +- `unnecessary_guard` reports guards where the value is already known to be of the type, so a check isn't needed. +- `indistinguishable_guard` reports guards that are always true at runtime, even though the types are different. For example, `value is Int` when `value` is `Int | nil` can never be false, since `nil` and `0` have the same runtime representation. + +## Limitations + +Some types can't be checked at runtime. Using them on the right side of a type guard is an error. + +### Function Types + +Rue supports [higher-order functions](https://en.wikipedia.org/wiki/Higher-order_function), which means functions can be passed around freely as values. As such, it's possible to express [functions as types](/docs/functions.md#function-types). However, there's no way to know at runtime whether or not a value fits the definition of a given function type. Any value _could_ match the type, but not every value _does_ match the type. -Due to this, it is **not possible** to check if a value is a function, or to narrow union types that contain function variants. However, you _can_ include a function type inside of one you are guarding, and as long as it's compatible it will be skipped. +Due to this, it is **not possible** to check if a value is a function, or to narrow union types that contain function variants. + +### Recursive Types + +A recursive type such as `List` can't be checked, since it would require a loop to check every item, and the length of the list isn't known at compile time. + +However, you can check a recursive type against a non-recursive one, such as `list is nil` or `list is (Int, List)`, since that only requires a fixed number of checks. + +### Generic Types + +A [generic type](/docs/type-system/generics.md) parameter such as `T` could be any type, so there's no way to know what to check. -If a function type is used on the left hand side, you can check the type of the underlying value. It will be treated as if it were equivalent to `Any`. +### Deeply Nested Types -## Recursive Types +The compiler limits how deeply nested a type can be checked, to avoid generating an excessive amount of code. A very long list type such as `[Int, Int, ..., Int]` can't be checked all at once. -When you use a type guard, the compiler emits a series of type checks in order to verify that the value on the left matches the type on the right. It skips any checks that are already implied by the type on the left as an optimization. +### Overlapping Values -However, recursive checks cannot currently be emitted by the compiler. This does not mean that recursive _types_ aren't allowed, and as long as you're either checking if a static type matches a recursive one, or a recursive type matches a static one it will likely work. +Because different types can share the same runtime representation, a guard can only tell types apart if there's a value that belongs to one and not the other. In particular, `nil` is the same as `0`, `false`, and `""`. So in a union like `Int | nil`, every value is also a valid `Int`, and `value is Int` is always true. -The compiler will simply limit the number of iterations it will run the type check until failing, so if you try to guard `List` into `List` you will get a compiler error. +To represent an optional value that can be told apart from `nil`, use a type that never has that value, such as `Bytes32`, a pair, or a struct. diff --git a/docs/type-system/pairs.md b/docs/type-system/pairs.md index eaafdd9..8618d4d 100644 --- a/docs/type-system/pairs.md +++ b/docs/type-system/pairs.md @@ -2,21 +2,26 @@ slug: /pairs --- -# Pairs +# Pairs and Lists A pair is one of two fundamental data types in [CLVM](https://chialisp.com/clvm/). Put simply, a pair is a container that holds two values. The values themselves are called `first` and `rest`. For example, let's say you have the following pair: ```rue -let value = (1, 2); +fn main() -> (Int, Int) { + (1, 2) +} ``` +The type of a pair is written the same way as the value, so this has the type `(Int, Int)`. + You can access the inner values like so: ```rue -let first = value.first; -let rest = value.rest; +fn sum(value: (Int, Int)) -> Int { + value.first + value.rest +} ``` ## Lists @@ -26,17 +31,31 @@ A list isn't a special type, it's instead made up of a chain of pairs (terminati Here are some examples of lists: ```rue -let empty = nil; -let one_item = (1, nil); -let two_items = (1, (2, nil)); +fn main() -> (List, (List, List)) { + let empty: List = nil; + let one_item = (1, nil); + let two_items = (1, (2, nil)); + (empty, (one_item, two_items)) +} ``` There is a special syntax for constructing list values that yields the same result: ```rue -let empty = []; -let one_item = [1]; -let two_items = [1, 2]; +fn main() -> (List, (List, List)) { + let empty: List = []; + let one_item = [1]; + let two_items = [1, 2]; + (empty, (one_item, two_items)) +} +``` + +You can use the spread operator on the last item to prepend values to an existing list: + +```rue +fn prepend(list: List) -> List { + [1, 2, ...list] +} ``` Finally, there is a builtin recursive list type defined as such: @@ -45,7 +64,27 @@ Finally, there is a builtin recursive list type defined as such: type List = nil | (T, List); ``` -This type is general enough to allow a list of arbitrary or unknown length. However, you can also explicitly write a sequence of nested pairs as a type if you want to. +This type is general enough to allow a list of arbitrary or unknown length. To access the items of a `List`, you first need to check that it isn't `nil` with a [type guard](/docs/type-system/guards.md): + +```rue +fn first_or_zero(list: List) -> Int { + if list is nil { + return 0; + } + + list.first +} +``` + +:::info +CLVM doesn't have loops, so you iterate over a list with recursion. Each call handles the first item, and calls itself again with the rest of the list until it reaches `nil`. +::: + +### List Types + +If you know the exact length of a list, you can write its type with the list syntax as well. For example, `[Int, Bytes]` is the same as `(Int, (Bytes, nil))`. + +A list type can end with a spread type, which is used as the rest of the list instead of `nil`. For example, `[Int, ...List]` is a list that starts with an `Int`, followed by any number of `Bytes` values. ## Alternating Lists @@ -65,8 +104,6 @@ Any is defined recursively with a type alias as well: type Any = Atom | (Any, Any); ``` -It allows any combination of nested atoms and pairs, which sufficiently covers all possible CLVM values. +It allows any combination of nested atoms and pairs, which sufficiently covers all possible CLVM values. Every value (including structs and functions) can be assigned to `Any` without a cast. -:::note -Due to the way the type system is designed, structs require casting when assigned to other types. So it may currently be required to explicitly cast values that contain structs to `Any`. This requirement will be lifted in the future. -::: +To do anything useful with an `Any` value, you need to narrow it first with a [type guard](/docs/type-system/guards.md), such as `value is Bytes` or `value is (Any, Any)`. diff --git a/docs/type-system/structs.md b/docs/type-system/structs.md index 595ceaa..7c0bacb 100644 --- a/docs/type-system/structs.md +++ b/docs/type-system/structs.md @@ -18,44 +18,59 @@ struct Point { You can initialize a value with this type like so: ```rue -let point = Point { - x: 42, - y: 34, -}; +fn main() -> Point { + Point { x: 42, y: 34 } +} +``` + +If you have a binding with the same name as a field, you can use the shorthand syntax: + +```rue +fn point(x: Int, y: Int) -> Point { + Point { x, y } +} ``` And access fields on the value: ```rue -let value = point.x * point.y; +fn area(point: Point) -> Int { + point.x * point.y +} ``` +At runtime, the `Point` above is the list `(x y)`, or `(x . (y . nil))`. + ## Semantics -Every struct has its own semantic type id, which determines whether they can be directly assigned or if a cast is required. +Every struct has its own semantic type, which determines whether they can be directly assigned or if a cast is required. A cast is required for structurally identical values when: 1. You're assigning a struct to a different struct 2. You're assigning a non-struct to a struct -3. You're assigning a struct to a non-struct +3. You're assigning a struct to a non-struct (other than `Any`) For example: ```rue -struct PointTwo { +struct Point { x: Int, y: Int, } -let point = Point { x: 0, y: 0 }; -let point_two = PointTwo { x: 0, y: 0 }; +struct Vector { + x: Int, + y: Int, +} -// This will fail since the structs are different -let value: Point = point_two; +fn main(vector: Vector) -> Point { + // This would fail since the structs are different + // let point: Point = vector; -// You can cast explicitly -let value = point_two as Point; + // You can cast explicitly instead + vector as Point +} ``` ## Default Values @@ -69,9 +84,26 @@ struct Point { x: Int = 0, y: Int = 0, } + +fn main() -> Point { + Point { y: 42 } +} ``` -While the type can technically be inferred, it's often necessary to explicitly use a more broad type than the default, since in this case we want values other than `0` to be assignable to `x` and `y`. +A default value can refer to constants, functions, and types, even if they are declared later in the file. + +If you leave out the type of a field with a default value, its type is inferred from the value. Since the type of a literal is the [literal type](/docs/type-system/atoms.md#literal-types) itself, this is a useful way to declare a field that always has the same value, such as the opcode of a condition: + +```rue +struct ReserveFee { + opcode = 52, + amount: Int, +} +``` + +Here, the `opcode` field has the type `52`, so it can't be set to anything else, and it can be used to tell the struct apart from other structs in a [type guard](/docs/type-system/guards.md). + +When the field could have other values, you should specify a broader type explicitly, since in the `Point` example we want values other than `0` to be assignable to `x` and `y`. :::note Default values are always inlined exactly as written. If the value is expensive to compute, or would require a lot of bytes to duplicate in the output program, it should be extracted out into a constant: @@ -87,3 +119,62 @@ struct Person { This way, the normal inlining rules can take effect. ::: + +## Spread Fields + +The last field of a struct can be marked with the spread operator (`...`). Instead of being the last item of a nil-terminated list, the field is the rest of the list itself. + +This is commonly used when a struct has a variable number of trailing values: + +```rue +struct Payment { + puzzle_hash: Bytes32, + amount: Int, + ...memos: List, +} + +fn main(puzzle_hash: Bytes32) -> Payment { + Payment { puzzle_hash, amount: 1, memos: ["hint"] } +} +``` + +At runtime, this is the list `(puzzle_hash amount "hint")`, rather than `(puzzle_hash amount ("hint"))`. + +It can also be used to make one struct extend another, or to match a value that isn't a nil-terminated list at all. For example, this struct is a chain of pairs, where the rest of each pair is either the next node or `nil`: + +```rue +struct Node { + value: Int, + ...next: Node | nil, +} +``` + +## Generic Structs + +A struct can have [generic](/docs/type-system/generics.md) type parameters: + +```rue +struct Box { + value: T, + count: Int = 1, +} + +fn main() -> Int { + let box = Box:: { value: 5 }; + box.value + box.count +} +``` + +When initializing a generic struct, the generic arguments must be specified explicitly with `::<...>`. + +## Unused Fields + +If a struct is only ever read by its fields, the compiler warns about any fields that are never read. When a field is only needed so that the struct matches the layout of a value, you can prefix its name with an underscore to silence the warning: + +```rue +struct LineageProof { + parent_parent_coin_info: Bytes32, + _parent_inner_puzzle_hash: Bytes32, + parent_amount: Int, +} +``` diff --git a/docs/type-system/unions.md b/docs/type-system/unions.md index 759b2c1..329ee2e 100644 --- a/docs/type-system/unions.md +++ b/docs/type-system/unions.md @@ -4,7 +4,7 @@ slug: /unions # Unions -A union allows you to allow multiple distinct types to be assigned. +A union allows a value to be one of multiple distinct types. For example, either `Bytes32` or `nil`: @@ -15,20 +15,42 @@ type Owner = Bytes32 | nil; You can assign either of these types to `Owner`: ```rue -let owner: Owner = nil; +fn main() -> Owner { + nil +} ``` -But you must narrow the type further through [Type Guards](/docs/type-system/guards.md) before assigning it to its individual types: +But you must narrow the type further through [Type Guards](/docs/type-system/guards.md) before using it as one of its individual types: ```rue -let maybe_owner: Owner = nil; +type Owner = Bytes32 | nil; + +fn main(maybe_owner: Owner) -> Bytes32 { + // This would fail because the type is too broad + // let owner: Bytes32 = maybe_owner; + + // This will check at runtime, allowing the type to be narrowed + assert maybe_owner is Bytes32; + + // And now this works because we know it's not nil + maybe_owner +} +``` -// This fails because the type is too broad -let owner: Bytes32 = maybe_owner; +## Fields of Unions -// This will check at runtime, allowing the type to be narrowed -assert maybe_owner is Bytes32; +If every type in a union is a pair, you can access `first` and `rest` directly, and the result is the union of each type's field: -// And now this works because we know it's not nil -let owner: Bytes32 = maybe_owner; +```rue +fn first(value: (Int, Bytes) | (Bytes32, nil)) -> Int | Bytes32 { + value.first +} ``` + +However, named fields can't be accessed on a union of different structs, even if every struct has a field with that name. Narrow it to one of the structs first. + +## Optional Values + +A union with `nil` is the idiomatic way to represent a value that may not be present, like `Option` or `null` in other languages. + +However, `nil` is the same value as `0`, `false`, and `""` at runtime, so a union like `Int | nil` can't be narrowed. Use a type that never has that value instead, such as `Bytes32`, a pair, or a struct. See [Overlapping Values](/docs/type-system/guards.md#overlapping-values). diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 9b3888e..f84ff26 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -49,6 +49,11 @@ const config: Config = { position: "left", label: "Docs", }, + { + href: "https://play.rue-lang.com", + label: "Playground", + position: "left", + }, { href: "https://github.com/xch-dev/rue", label: "GitHub", @@ -66,6 +71,10 @@ const config: Config = { label: "Installation", to: "/docs/installation", }, + { + label: "Playground", + href: "https://play.rue-lang.com", + }, ], }, { diff --git a/sidebars.ts b/sidebars.ts index 99330be..b3ea80d 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -3,19 +3,29 @@ import type { SidebarsConfig } from "@docusaurus/plugin-content-docs"; const sidebars: SidebarsConfig = { docs: [ "installation", + "projects", { type: "category", label: "Tutorials", items: ["tutorials/password", "tutorials/signature"], }, - "modules", - "functions", - "control-flow", - "bindings", - "constants", + { + type: "category", + label: "Language", + collapsed: false, + items: [ + "functions", + "bindings", + "constants", + "control-flow", + "operators", + "modules", + ], + }, { type: "category", label: "Type System", + collapsed: false, items: [ "type-system/atoms", "type-system/pairs", @@ -23,11 +33,18 @@ const sidebars: SidebarsConfig = { "type-system/aliases", "type-system/unions", "type-system/guards", + "type-system/generics", + "type-system/casting", ], }, - "operators", + "standard-library", "builtins", - "debugging", + { + type: "category", + label: "Tooling", + collapsed: false, + items: ["cli", "testing", "debugging", "lints", "formatting"], + }, "security", ], }; diff --git a/src/theme/prism-rue.ts b/src/theme/prism-rue.ts index 10fe67e..d123c11 100644 --- a/src/theme/prism-rue.ts +++ b/src/theme/prism-rue.ts @@ -1,4 +1,18 @@ Prism.languages.rue = { + string: { + pattern: /"[^"]*"/, + greedy: true, + }, + comment: { + pattern: /\/\/.*|\/\*[^]*?\*\//, + multiline: true, + greedy: true, + }, + attribute: { + pattern: /#!?\[[^\]]*\]/, + greedy: true, + alias: "attr-name", + }, function: { pattern: /\b(fn)\s+[a-zA-Z_][a-zA-Z0-9_]*/, lookbehind: true, @@ -16,15 +30,7 @@ Prism.languages.rue = { lookbehind: true, alias: "property", }, - string: { - pattern: /"[^"]*"/, - }, - comment: { - pattern: /\/\/.*|\/\*[^]*?\*\//, - multiline: true, - greedy: true, - }, - number: /\b(?:0[xX][0-9a-fA-F_]+|[0-9][0-9_]*)\b/, + number: /\b(?:0[xX][0-9a-fA-F_]+|0[bB][01_]+|0[oO][0-7_]+|[0-9][0-9_]*)\b/, operator: /[+\-*?%!\^~]|<[<=]?|>[>=]?|=[=>]?|!=?|\.(?:\.\.)?|::|->?|&&?|\|\|?/, punctuation: /[(){}[\],:]/,