Merge pull request #546 from ProvableHQ/minor-reorg/11-7-25

Reorganization

Author: AleoAlexander

documentation/language/01_layout.md

@@ -5,7 +5,7 @@ sidebar_label: Project Layout
 ---
 [general tags]: # (project, project_layout, manifest, module)
 
-## The Manifest
+## Manifest
 
 **program.json** is the Leo manifest file that configures our package.
 ```json title="program.json"
@@ -26,12 +26,109 @@ The program ID in `program` is the official name that other developers will be a
 
 Dependencies will be added to the field of the same name, as they are added. The dependencies are also pegged in the **leo.lock** file.
 
-## The Code
 
-The `src/` directory is where all of your Leo code will live.  The main entry point of your project is a file in this directory.appropriately named `main.leo`.  Calls to many of the Leo CLI commands will require you to have this file within your project in order to succeed properly.
+The `src/` directory is where all of your Leo code will live.  The main entry point of your project is a file in this directory appropriately named `main.leo`.  Calls to many of the Leo CLI commands will require you to have this file within your project in order to succeed properly.
 
 
-### Modules 
+## Programs
+
+A program is a collection of code (its functions) and data (its types) that resides at a
+[program ID](#program-id) on the Aleo blockchain. A program is declared as `program {name}.{network} { ... }`.
+The body of the program is delimited by curly braces `{}`.
+
+```leo title=main.leo
+import foo.aleo;
+
+program hello.aleo {
+    const FOO: u64 = 1u64;
+    mapping account: address => u64;
+
+    record Token {
+        owner: address,
+        amount: u64,
+    }
+
+    struct Message {
+        sender: address,
+        object: u64,
+    }
+
+    async transition mint_public(
+        public receiver: address,
+        public amount: u64,
+    ) -> (Token, Future) {
+        return (Token {
+            owner: receiver,
+            amount,
+        }, update_state(receiver, amount));
+    }
+
+    async function update_state(
+        public receiver: address,
+        public amount: u64,
+    ) {
+        let current_amount: u64 = Mapping::get_or_use(account, receiver, 0u64);
+        Mapping::set(account, receiver, current_amount + amount);
+   }
+
+    function compute(a: u64, b: u64) -> u64 {
+        return a + b + FOO;
+    }
+}
+```
+
+
+
+The following must be declared inside the scope of a program in a Leo file:
+
+- [Constants](#constant)
+- [Mappings](#mapping) and [Storage](#storage)
+- [Records](#record)
+- [Structs](#struct)
+- [Transitions](#transition-function) and [Async Transitions](#async-function)
+- [Functions](#transition-function) and [Async Functions](#async-function)
+- [Inlines](#inline)
+
+The following must be declared outside the scope of a program in a Leo file:
+
+- [Imports](#imports)
+
+Declarations are locally accessible within a program file.  If you need a declaration from another Leo file, you must import it.
+### Imports
+
+You can import dependencies that are downloaded to the `imports` directory.
+An import is declared as `import {filename}.aleo;`
+The dependency resolver will pull the imported program from the network or the local filesystem.
+
+```leo showLineNumbers
+import foo.aleo; // Import all `foo.aleo` declarations into the `hello.aleo` program.
+
+program hello.aleo { }
+```
+
+### Program ID
+
+A program ID is declared as `{name}.{network}`.
+
+The first character of a `name` must be a lowercase letter.
+`name` can only contain lowercase letters, numbers, and underscores, and must not contain a double underscore (`__`) or the keyword `aleo` in it.
+
+Currently, `aleo` is the only supported `network` domain.
+
+```leo showLineNumbers
+program hello.aleo; // valid
+
+program Foo.aleo;   // invalid
+program baR.aleo;   // invalid
+program 0foo.aleo;  // invalid
+program 0_foo.aleo; // invalid
+program _foo.aleo;  // invalid
+program foo__bar.aleo;  // invalid
+program aleo.aleo;  // invalid
+```
+
+
+## Modules 
 
 In addition to your main file, Leo also supports a module system as of v3.2.0.
 
@@ -75,6 +172,7 @@ inline increment(x: field) -> field {
 ```
 
 
+
 <!-- 
 
 ## The Tests

documentation/language/03_data_types.md

@@ -6,7 +6,17 @@ sidebar_label: Data Types
 [general tags]: # (boolean, integer, field, group, scalar, address, signature, array, tuple, struct)
 
 
-## Types
+## Primitive Types
+
+### Addresses
+
+Addresses are defined to enable compiler-optimized routines for parsing and operating over addresses.
+These semantics will be accompanied by a standard library in a future sprint.
+
+```leo
+let sender: address = aleo1ezamst4pjgj9zfxqq0fwfj8a4cjuqndmasgata3hggzqygggnyfq6kmyd4;
+let receiver = aleo129nrpl0dxh4evdsan3f4lyhz5pdgp6klrn5atp37ejlavswx5czsk0j5dj;
+```
 
 ### Booleans
 
@@ -87,15 +97,6 @@ let b = 211111543735709260606220623469538663283887092640840819519368524639472136
 let c: scalar = 0;
 ```
 
-### Addresses
-
-Addresses are defined to enable compiler-optimized routines for parsing and operating over addresses.
-These semantics will be accompanied by a standard library in a future sprint.
-
-```leo
-let sender: address = aleo1ezamst4pjgj9zfxqq0fwfj8a4cjuqndmasgata3hggzqygggnyfq6kmyd4;
-let receiver = aleo129nrpl0dxh4evdsan3f4lyhz5pdgp6klrn5atp37ejlavswx5czsk0j5dj;
-```
 
 ### Signatures
 
@@ -125,8 +126,9 @@ program test.aleo {
 }
 ```
 
+## Composite Types
 
-### Array
+### Arrays
 
 Leo supports static arrays. Array types are declared as `[type; length]` and can be nested. Arrays cannot be empty nor modified.
 
@@ -179,7 +181,7 @@ transition sum_with_loop(a: [u64; 4]) -> u64 {
 }
 ```
 
-### Tuple
+### Tuples
 
 Leo supports tuples. Tuple types are declared as `(type1, type2, ...)` and can be nested. Tuples cannot be empty or modified.
 
@@ -232,8 +234,25 @@ let m = Matrix::[2, 2] { data: [0, 1, 2, 3] };
 ```
 Note that generic structs cannot currently be imported outside a program, but can be declared and used in submodules. Acceptable types for const generic parameters include integer types, `bool`,  `scalar`, `group`, `field`, and `address`.
 
+### Records
+
+A [record](https://developer.aleo.org/concepts/fundamentals/records) data type is the method of encoding private state on Aleo.  Records are declared as `record {name} {}`. A record name must not contain the keyword `aleo`, and must not be a prefix of any other record name.
+
+Records contain component declarations `{visibility} {name}: {type},`. Names of record components must not contain the keyword `aleo`.  The visibility qualifier may be specified as `constant`, `public`, or `private`. If no qualifier is provided, Leo defaults to `private`.
+
+Record data structures must always contain a component named `owner` of type `address`, as shown below. When passing a record as input to a program function, the `_nonce: group` and `_version: u8` components are also required but do not need to be declared in the Leo program. They are inserted automatically by the compiler.
+
+```aleo showLineNumbers
+record Token {
+    // The token owner.
+    owner: address,
+    // The token amount.
+    amount: u64,
+}
+```
+
 ## Option Types
-As of v3.3.0, Leo supports first-class option types using the `T?` syntax, where `T` is any of the types previously mentioned, excluding `address`, `signature`, and `tuple`.  A value of type `T?` can be initialized into two states: either a value of type `T`, or `none`:
+As of v3.3.0, Leo supports first-class option types using the `T?` syntax, where `T` is any of the types previously mentioned, excluding `record`, `address`, `signature`, and `tuple`.  A value of type `T?` can be initialized into two states: either a value of type `T`, or `none`:
 ```leo
 let w: u8? = 42u8;
 let x: u8? = none;

documentation/language/programs_in_practice/control_flow.md

@@ -0,0 +1,62 @@
+---
+id: control_flow
+title: Control Flow
+sidebar_label: Control Flow
+---
+[general tags]: # (loop, conditional, return)
+
+## Conditional Statements
+
+Conditional statements are declared as `if {condition} {...} else if {condition} {...} else {...}`.
+Conditional statements can be nested.
+```leo
+    let a: u8 = 1u8;
+    
+    if a == 1u8 {
+        a += 1u8;
+    } else if a == 2u8 {
+        a += 2u8;
+    } else {
+        a += 3u8;
+    }
+```
+
+Leo also supports ternary expressions.  Ternary expressions are declared as `{condition} ? {then} : {else}`, and can be nested.
+```leo
+let a: u8 = 1u8;    
+a = (a == 1u8) ? a + 1u8 : ((a == 2u8) ? a + 2u8 : a + 3u8);
+```
+
+## For Loops
+
+For loops are declared as `for {variable: type} in {lower bound}..{upper bound}`.
+The loop bounds must be integer constants of the same type. Furthermore, if
+the lower bound is superior or equal to the upper bound, the loop will result in no operations.
+Nested loops are supported.
+
+
+```leo
+  let count: u32 = 0u32;
+
+  for i: u32 in 0u32..5u32 {
+    count += 1u32;
+  }
+
+  return count; // returns 5u32
+```
+
+## Return Statements
+
+Return statements are declared as `return {expression};`.
+
+```leo
+    let a: u8 = 1u8;
+    
+    if a == 1u8 {
+        return a + 1u8;
+    } else if a == 2u8 {
+        return a + 2u8;
+    } else {
+        return a + 3u8;
+    }
+```