Merge pull request #4 from xch-dev/compiler-redesign

Compiler redesign

Author: Rigidity

docs/bindings.md

@@ -0,0 +1,44 @@
+---
+slug: /bindings
+---
+
+# Bindings
+
+Rue is a [purely-functional](https://en.wikipedia.org/wiki/Purely_functional_programming) programming language, and doesn't directly support mutation.
+
+Practically, this means a few things:
+
+1. The output of a function will remain the same every time, as long as its arguments don't change
+2. There is no support for mutable variables
+3. A function cannot change the outer scope in any way
+
+However, even though _mutation_ isn't supported, you can still define `let` bindings:
+
+```rue
+fn main(num: Int) -> Int {
+    let squared = num * num;
+    let doubled = squared * 2;
+    doubled + 100
+}
+```
+
+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.
+
+## 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:
+
+```rue
+fn main(num: Int) -> Int {
+    inline let squared = num * num;
+    square + squared
+}
+```
+
+This should be used sparingly, since it can come with either a performance hit, an increase in compiled output size, or both.
+
+:::tip
+The compiler will automatically inline `let` bindings if they are only referenced a single time. You almost never need to explicitly mark them as `inline`.
+:::

docs/builtins.md

@@ -0,0 +1,64 @@
+---
+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.
+
+## Types
+
+You can click on each of these types to go to their corresponding page and learn more:
+
+1. [**Atom**](/docs/type-system/atoms.md#atom)
+2. [**Bytes**](/docs/type-system/atoms.md#bytes)
+3. [**Bytes32**](/docs/type-system/atoms.md#bytes32)
+4. [**PublicKey**](/docs/type-system/atoms.md#publickey)
+5. [**Int**](/docs/type-system/atoms.md#int)
+6. [**Bool**](/docs/type-system/atoms.md#bool)
+7. [**Any**](/docs/type-system/pairs.md#any)
+8. [**List**](/docs/type-system/pairs.md#lists)
+
+## Functions
+
+### `sha256`
+
+Calculates the [SHA-256](https://en.wikipedia.org/wiki/SHA-2) hash of the bytes provided. This hash is calculated at runtime.
+
+For example:
+
+```rue
+let hash = sha256("hello");
+```
+
+### `sha256_inline`
+
+The same as `sha256`, except the value will be calculated at compile time and inserted into the program. In some rare scenario, this may be an important optimization to avoid hashing the same large constant value many times. However, in most cases, you should just use the regular `sha256` function.
+
+For example:
+
+```rue
+let hash = sha256_inline("hello");
+```
+
+### `calculate_coin_id`
+
+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.
+
+For example:
+
+```rue
+calculate_coin_id(parent_coin_id, puzzle_hash, amount)
+```
+
+### `substr`
+
+Returns a substring of a byte value, given a range of indices.
+
+For example:
+
+```rue
+substr("hello", 1, 4)
+```
+
+This would return `"ell"`

docs/constants.md

@@ -0,0 +1,39 @@
+---
+slug: /constants
+---
+
+# 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.
+
+As a simple example, you might want to reuse a string multiple times:
+
+```rue
+const GREET: Bytes = "Hello, ";
+
+fn main(person_a: Bytes, person_b: Bytes) -> (Bytes, Bytes) {
+    (GREET + person_a, GREET + person_b)
+}
+```
+
+## 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.
+
+As an example, this will behave the same as if you had written the string multiple times:
+
+```rue
+inline const GREET: Bytes = "Hello, ";
+
+fn main(person_a: Bytes, person_b: Bytes) -> (Bytes, Bytes) {
+    (GREET + person_a, GREET + person_b)
+}
+```
+
+This should be used sparingly, since it can come with either a performance hit, an increase in compiled output size, or both.
+
+:::tip
+The compiler will automatically inline constants if they are only referenced a single time. You almost never need to explicitly mark them as `inline`.
+:::