Cover all remaining statements and expressions in the spec

.github/workflows/main.yml

@@ -62,6 +62,8 @@ jobs:
           toolchain: stable
           override: true
           components: rustfmt, clippy
+      - name: Validate doc examples
+        run: ./docs/validate_doc_examples.py
       - name: Validate release notes entry
         run: ./newsfragments/validate_files.py
       - name: Lint with rustfmt

docs/book.toml

@@ -4,3 +4,6 @@ language = "en"
 multilingual = false
 src = "src"
 title = "The Fe Guide"
+
+[output.html]
+additional-css = ["theme/reference.css"]

docs/src/SUMMARY.md

@@ -26,13 +26,31 @@
         * [Contracts](spec/contracts.md)
     * [Statements](spec/statements.md)
         * [`pragma` Statement](spec/statement_pragma.md)
+        * [`let` Statement](spec/statement_let.md)
+        * [Assignment Statement](spec/statement_assign.md)
+        * [Augmenting Assignment Statement](spec/statement_augassign.md)
         * [`revert` Statement](spec/statement_revert.md)
         * [`return` Statement](spec/statement_return.md)
+        * [`emit` Statement](spec/statement_emit.md)
         * [`if` Statement](spec/statement_if.md)
+        * [`for` Statement](spec/statement_for.md)
+        * [`while` Statement](spec/statement_while.md)
+        * [`break` Statement](spec/statement_break.md)
+        * [`continue` Statement](spec/statement_continue.md)
+        * [`assert` Statement](spec/statement_assert.md)
+        * [`pass` Statement](spec/statement_pass.md)
     * [Expressions](spec/expressions.md)
-        * [Literal expressions](spec/expr-literal.md)
-        * [Arithmetic Operators](spec/arithmetic_operators.md)
-        * [Comparision Operators](spec/comparision_operators.md)
+        * [Call expressions](spec/expr_call.md)
+        * [Tuple expressions](spec/expr_tuple.md)
+        * [List expressions](spec/expr_list.md)
+        * [Index expressions](spec/expr_index.md)
+        * [Attribute expressions](spec/expr_attribute.md)
+        * [Name expressions](spec/expr_name.md)
+        * [Literal expressions](spec/expr_literal.md)
+        * [Arithmetic Operators](spec/expr_arithmetic_operators.md)
+        * [Comparision Operators](spec/expr_comparision_operators.md)
+        * [Boolean Operators](spec/expr_boolean_operators.md)
+        * [Unary Operators](spec/expr_unary_operators.md)
     * [Type System](spec/type_system.md)
         * [Types](spec/types.md)
             * [Boolean Type](spec/boolean_type.md)

docs/src/spec/contract_types.md

@@ -17,7 +17,7 @@ contract Foo:
 contract FooFactory:
     pub fn create2_foo() -> address:
         # `0` is the value being sent and `52` is the address salt
-        foo: Foo = Foo.create2(0, 52)
+        let foo: Foo = Foo.create2(0, 52)
         return address(foo)
 ```
 

docs/src/spec/events.md

@@ -17,16 +17,17 @@ An _event_ is a nominal [event type] defined with the keyword `event`. It is emi
 
 An example of a `event` item and its use:
 
-```
-event Transfer:
-    idx sender: address
-    idx receiver: address
-    value: u256
+```python
+contract Foo:
+    event Transfer:
+        idx sender: address
+        idx receiver: address
+        value: u256
 
-fn transfer(to : address, value : u256):
-   # Heavy logic here
-   # All done, log the event for listeners
-   emit Transfer(msg.sender, _to, _value)
+    fn transfer(to : address, value : u256):
+        # Heavy logic here
+        # All done, log the event for listeners
+        emit Transfer(sender=msg.sender, receiver=to, value)
 ```
 
 [NEWLINE]: tokens.md#newline

docs/src/spec/expr_attribute.md

@@ -0,0 +1,41 @@
+# Attribute expressions
+
+> **<sup>Syntax</sup>**\
+> _AttributeExpression_ :\
+> &nbsp;&nbsp; [_Expression_] `.` [IDENTIFIER]
+
+An attribute expression evaluates to the location of an attribute of a [struct], [tuple] or [contract].
+
+The syntax for an attribute expression is an expression, then a `.` and finally an identifier.
+
+
+Examples:
+
+```python
+struct Point:
+    x: u256
+    y: u256
+
+contract Foo:
+    some_point: Point
+    some_tuple: (bool, u256)
+
+    fn get_point() -> Point:
+        return Point(x=100, y=500)
+
+    pub fn baz(some_point: Point, some_tuple: (bool, u256)):
+        # Different examples of attribute expressions
+        let bool_1: bool = some_tuple.item0
+        let x1: u256 = some_point.x
+        let point1: u256 = self.get_point().x
+        let point2: u256 = self.some_point.x
+
+```
+
+[_Expression_]: expressions.md
+[expression]: expressions.md
+[IDENTIFIER]: identifiers.md
+[tuple]: tuple_types.md
+[struct]: structs.md
+[contract]: contracts.md
+[attribute expression]: expr_attribute.md

docs/src/spec/expr_boolean.md

@@ -0,0 +1 @@
+# Boolean Operators

docs/src/spec/expr_boolean_operators.md

@@ -0,0 +1,23 @@
+# Boolean Operators
+
+> **<sup>Syntax</sup>**\
+> _BooleanExpression_ :\
+> &nbsp;&nbsp;&nbsp;&nbsp; [_Expression_] `or` [_Expression_]\
+> &nbsp;&nbsp; | [_Expression_] `and` [_Expression_]\
+
+The operators `or` and `and` may be applied to operands of boolean type. The `or` operator denotes logical 'or', and the `and` operator denotes logical 'and'.
+
+<div class="warning">
+
+Warning:
+These operators do currently not evaluate lazily which is likely to change in the future. ([See GitHub issue](https://github.com/ethereum/fe/issues/488))
+
+</div>
+
+Example:
+
+```
+let x: bool = false or true # true
+```
+
+[_Expression_]:expressions.md

docs/src/spec/expr_call.md

@@ -0,0 +1,38 @@
+# Call expressions
+
+
+> **<sup>Syntax</sup>**\
+> _CallExpression_ :\
+> &nbsp;&nbsp; [_Expression_] _GenericArgs_<sup>?</sup> `(` _CallParams_<sup>?</sup> `)`
+>
+> _GenericArgs_ :\
+> &nbsp;&nbsp; `<` [IDENTIFIER] | [INTEGER_LITERAL]  (`,` [IDENTIFIER] | [INTEGER_LITERAL])<sup>*</sup> `>`
+>
+> _CallParams_ :\
+> &nbsp;&nbsp; _CallArg_&nbsp;( `,` _CallArg_ )<sup>\*</sup> `,`<sup>?</sup>
+>
+> _CallArg_ :\
+> &nbsp;&nbsp; (_CallArgLabel_ `=`)<sup>?</sup> [_Expression_]
+>
+> _CallArgLabel_ :\
+> &nbsp;&nbsp; [IDENTIFIER]<sup>Label must correspond to the name of the called function argument at the given position. It can be omitted if parameter name and the name of the called function argument are equal.</sup>
+
+A *call expression* calls a function. The syntax of a call expression is an [expression], followed by a parenthesized comma-separated list of call arguments. Call arguments are expressions which optionally may be labeled in which case the label must correspond to name of the function argument at the given position. Labels do **not allow** to change the order in which parameters can be applied to a function. If the function eventually returns, then the expression completes.
+
+
+Example:
+
+```python
+contract Foo:
+
+    pub fn baz():
+        self.bar(100, val2=300)
+
+    pub fn bar(val1: u256, val2: u256):
+        pass
+```
+
+[_Expression_]: expressions.md
+[expression]: expressions.md
+[IDENTIFIER]: identifiers.md
+[INTEGER_LITERAL]: tokens.md#integer-literals

docs/src/spec/expr_index.md

@@ -0,0 +1,32 @@
+# Index expressions
+
+> **<sup>Syntax</sup>**\
+> _IndexExpression_ :\
+> &nbsp;&nbsp; [_Expression_] `[` [_Expression_] `]`
+
+[Array] and [Map] types can be indexed by by writing a square-bracket-enclosed expression after them. For arrays, the type of the index key has to be `u256` whereas for [Map] types it has to be equal to the key type of the map.
+
+
+Example:
+
+```python
+contract Foo:
+
+    balances: Map<address, u256>
+
+    pub fn baz(values: u256[10]):
+        # Assign value at slot 5
+        values[5] = 1000
+        # Read value at slot 5
+        let val1: u256 = values[5]
+
+        # Assign value for address zero
+        self.balances[address(0)] = 10000
+
+        # Read balance of address zero
+        let bal: u256 = self.balances[address(0)]
+```
+
+[_Expression_]: expressions.md
+[Array]: array_types.md
+[Map]: hashmap_types.md

docs/src/spec/expr_list.md

@@ -0,0 +1,39 @@
+# List expressions
+
+> **<sup>Syntax</sup>**\
+> _ListExpression_ :\
+> &nbsp;&nbsp; `[` _ListElements_<sup>?</sup> `]`
+>
+> _ListElements_ :\
+> &nbsp;&nbsp; [_Expression_] (`,` [_Expression_])<sup>*</sup> `,`<sup>?</sup>
+
+A *list expression* constructs [array values].
+
+The syntax for list expressions is a parenthesized, comma separated list of expressions, called the *list initializer operands*. The number of list initializer operands must be equal to the static size of the array type. The types of all list initializer operands must conform to the type of the array.
+
+Examples of tuple expressions and their types:
+
+| Expression           | Type         |
+| -------------------- | ------------ |
+| `[1, self.get_number()]`             |   `u256[2]`  |
+| `[true, false, false]`         | `bool[3]` |
+
+An array item can be accessed via an [index expression].
+
+Example:
+
+```python
+contract Foo:
+
+    fn get_val3() -> u256:
+        return 3
+
+    pub fn baz():
+        let val1: u256 = 2
+        # A list expression
+        let foo: u256[3] = [1, val1, self.get_val3()]
+```
+
+[_Expression_]: expressions.md
+[array values]: array_types.md
+[index expression]: expr_index.md

docs/src/spec/expr_name.md

@@ -0,0 +1,19 @@
+# Name expressions
+
+> **<sup>Syntax</sup>**\
+> _NameExpression_ :\
+> &nbsp;&nbsp; [IDENTIFIER]
+
+A *name expression* resolves to a local variable.
+
+Example:
+
+```python
+contract Foo:
+
+    pub fn baz(foo: u256):
+        # name expression resolving to the value of `foo`
+        foo
+```
+
+[IDENTIFIER]: identifiers.md

docs/src/spec/expr_tuple.md

@@ -0,0 +1,53 @@
+# Tuple expressions
+
+> **<sup>Syntax</sup>**\
+> _TupleExpression_ :\
+> &nbsp;&nbsp; `(` _TupleElements_<sup>?</sup> `)`
+>
+> _TupleElements_ :\
+> &nbsp;&nbsp; ( [_Expression_] `,` )<sup>+</sup> [_Expression_]<sup>?</sup>
+
+A *tuple expression* constructs [tuple values].
+
+The syntax for tuple expressions is a parenthesized, comma separated list of expressions, called the *tuple initializer operands*. The number of tuple initializer operands is the *arity* of the constructed tuple.
+
+1-ary tuple expressions require a comma after their tuple initializer operand to be disambiguated with a parenthetical expression.
+
+Tuple expressions without any tuple initializer operands produce the unit tuple.
+
+For other tuple expressions, the first written tuple initializer operand initializes the field `item0` and subsequent operands initializes the next highest field.
+
+For example, in the tuple expression `(true, false, 1)`, `true` initializes the value of the field `item0`, `false` field `item1`, and `1` field `item2`.
+
+Examples of tuple expressions and their types:
+
+| Expression           | Type         |
+| -------------------- | ------------ |
+| `()`                 | `()` (unit)  |
+| `(0, 4)`         | `(u256, u256)` |
+| `(true, )` | `(bool, )`  |
+| `(true, -1, 1)`| `(bool, i256, u256)` |
+
+A tuple field can be accessed via an [attribute expression].
+
+Example:
+
+```python
+contract Foo:
+
+    pub fn bar():
+        # Creating a tuple via a tuple expression
+        let some_tuple: (u256, bool) = (1, false)
+
+        # Accessing the first tuple field via the `item0` field
+        self.baz(some_tuple.item0)
+
+    pub fn baz(input: u256):
+        pass
+```
+
+[_Expression_]: expressions.md
+[expression]: expressions.md
+[IDENTIFIER]: identifiers.md
+[tuple values]: tuple_types.md
+[attribute expression]: expr_attribute.md

docs/src/spec/expr_unary_operators.md

@@ -0,0 +1,26 @@
+# Unary Operators
+
+> **<sup>Syntax</sup>**\
+> _UnaryExpression_ :\
+> &nbsp;&nbsp;&nbsp;&nbsp; `not` [_Expression_]\
+> &nbsp;&nbsp; | `-` [_Expression_]\
+> &nbsp;&nbsp; | `~` [_Expression_]\
+
+The unary operators are used to negate expressions. The unary `-` (minus) operator yields the negation of its numeric argument. The unary `~` (invert) operator yields the *bitwise* inversion of its integer argument. The unary `not` operator yields the inversion of its boolean argument.
+
+<div class="warning">
+
+Warning:
+The unary NOT operator (`~`) isn't yet implemented ([See GitHub issue](https://github.com/ethereum/fe/issues/521))
+</div>
+
+
+Example:
+
+```
+let x: bool = not true # false
+let y: i256 = -1  # -1
+let y: i256 = ~1  # -2
+```
+
+[_Expression_]:expressions.md