Merge branch 'main' into micah/file-errors

book/src/language-tour/assert.md

@@ -7,4 +7,10 @@ assert rawdata = SomeType
 Causes the script to fail if the rawdata doesn't match the structure of datumtype
 Otherwise, returns a value of SomeType
 
-Primarily for validating input datums / redeemers.
+Primarily for validating input datums / redeemers.
+
+You can unpack (1-match) data in the assertion
+
+```gleam
+assert Some(x) = Option(Int)
+```

book/src/language-tour/blocks.md

@@ -1,36 +1,28 @@
 # Blocks
-
-If statements
+Let bindings with blocks
 
 ```gleam
-if condition {
-
-} else {
+let x = 3
 
+let z = {
+    let y = 2
+    x + y
 }
 ```
 
-Case Patterns
-
-```gleam
-when color is {
-    Green -> "Success."
-    Blue -> "Warning."
-    Red -> "Error!"
-}
-```
+A block can be thought of as calling an anonymous function with no arguments. They can be used anywhere a value is.
+Since everything is secretly a function, the last statement in any block is implicitly its return.
 
-Let bindings with blocks
 
+Blocks within a where-if clause
 ```gleam
-let num = -5
-let absNum = if num>=0 {num} else {-num}
-
-let message = when color is {
-    Green -> "Success."
-    Blue -> "Warning."
-    Red -> "Error!"
+let name: Option(String) = someFunction()
+let suffix = ""
+when name is {
+    Some(s)->{
+        let combined = s + suffix
+        Some(combined)
+    }
+    None->None
 }
-```
-
-Since everything is secretly a function, the last statement in any block is implicitly its return.
+```

book/src/language-tour/bool.md

@@ -1,19 +1,39 @@
 # Bool
 
-Bools are True or False
+Bools (short for booleans) are True or False. They correspond to the plutus bool primitive type.
+There are logical disjunctions (True || False) or conjunctions (True && True).
+```gleam
+False || False -- -> False
+True || False -- -> True
+False || True -- -> True
+True || True -- -> True
+
+False && False -- -> False
+True && False -- -> False
+False && True -- -> False
+True && True -- -> True
+```
 
-There are logical conjunctions (True && True) or disjunctions (True || False).
+These are implemented using the plutus ifThenElse primitive.
+```gleam
+a || b -- if a {True} else {b} -- ifThenElse(a, True, b)
+a && b -- if a {b} else {False} -- ifThenElse(a, b, False)
+```
 
+An if statement decides on a boolean value.
 ```gleam
-fn negate(b: Bool)->Bool {
+fn negate(b: Bool) -> Bool {
     if b {
         False
     }else{
         True
     }
 }
+```
 
-fn and(b: Bool, c: Bool, d: Bool)->Bool{
+The && operator in a function
+```gleam
+fn and(b: Bool, c: Bool, d: Bool) -> Bool{
     b && c && d
 }
 ```

book/src/language-tour/check.md

@@ -1 +1,8 @@
 # Check
+
+Check is slower than assert but has stronger guarantees.
+You can unpack (1-match) data in a check.
+
+```gleam
+check Some(x) = Option(Int)
+```

book/src/language-tour/functions.md

@@ -6,7 +6,7 @@ fn f(x) {
 
 }
 ```
-l functions in aiken are pure without side effect, so all functions also must return some value.
+Functions in aiken are pure without side effect, so all functions also must return some value.
 A function with no return value (like above) will error.
 
 Providing arg types:

book/src/language-tour/int.md

@@ -1,8 +1,7 @@
 # Int
 
 Ints are plutus integers which are arbitrary size.
-
-So, there is no underflow. Basic arithmetic can be done for O(1) between ints (+,-,*).
+So, there is no underflow or overflow. Basic arithmetic can be done for O(1) between ints (+,-,*).
 
 ```gleam
 // A convenient helper function to get the number 7.

book/src/language-tour/list.md

@@ -1,11 +1,13 @@
 # List
 
-Aiken lists are plutus linked lists. Accessing by index is O(n). Appending or accessing head is O(1). Grabbing tail is O(1).
+Aiken lists are plutus linked lists.
+Accessing by index is O(n).
+Appending or accessing head is O(1).
+Grabbing tail is O(1).
 
 There is no builtin syntax for accessing by index as this is implemented by standard libs.
 
 Accessing head, tail, or preceding elements can be done by pattern matching.
-
 ```gleam
 // this function checks if a list has a sequence of 1 then 2 contained within it.
 fn listStuff(a: List(Int)){
@@ -18,4 +20,6 @@ fn listStuff(a: List(Int)){
 ```
 
 Helper functions for safely accessing head, tail, are provided in standard lib but are implemented using comprehensions.
-It is usually best to use your own comprehensions for efficiency (until the optimiser is better).
+It is usually best to use your own comprehensions for efficiency (until the optimiser is better).
+
+It is best to avoid accesses by indexes if possible for efficiency.

book/src/language-tour/matching.md

@@ -1 +1,11 @@
 # Matching
+
+Where-if Patterns (also known as case in lamer languages)
+
+```gleam
+when color is {
+    Green -> "Success."
+    Blue -> "Warning."
+    Red -> "Error!"
+}
+```

book/src/language-tour/string.md

@@ -1 +1,15 @@
 # String
+
+There are Strings and ByteArrays (plutus bytestrings)
+
+The default representation using double quotes is a string.
+```
+let mystring = "Hello World!"
+```
+Strings may be appended and compared.
+
+For char operations, ByteArrays must be used.
+ByteArrays have efficient indexing, slicing, and can be compared or concatenated.
+ByteArrays can also be useful for non-text data (hence why we call them arrays not strings.)
+
+Due to their fixed byte width, you may find them not suitable for complex structures.

book/src/language-tour/todo.md

@@ -1 +1,12 @@
 # Todo
+
+A 'todo' type errors on evaluation but casts to any type.
+It can be useful to let your project typecheck while you are still working on parts of it.
+
+```
+fn notImplementedYet(){
+    todo
+}
+```
+
+It is also good practice to use instead of a todo comment.

book/src/language-tour/tuple.md

@@ -1 +1,9 @@
 # Tuple
+
+Tuples are anonymous product types. They are useful for passing combinations of data between functions.
+
+```
+let x = (1, 2)
+let y = (3, 4)
+pairAdder(x, y) -- --> (4, 6)
+```

book/src/language-tour/type-aliases.md

@@ -1 +1,24 @@
 # Type aliases
+
+A type alias lets you create a name which is identical to another type, without any additional information.
+We like type names (including type alias names) to be PascalCase.
+
+```gleam
+type MyNumber = Integer
+```
+
+I imagine them like variables for types. You could use this to simplify your type signatures for tuples.
+
+```gleam
+type Person = (String, Integer)
+
+fn createPerson(name: String, age: Integer) -> Person {
+    (name, age)
+}
+```
+
+If you want the type-alias to be accessible as a module, you should pub it.
+
+```
+pub type MyVector3 = (Integer, Integer, Integer)
+```

crates/cli/src/cmd/new.rs

@@ -15,32 +15,32 @@ pub struct Args {
 
 pub struct Creator {
     root: PathBuf,
-    src: PathBuf,
-    scripts: PathBuf,
-    project: PathBuf,
+    lib: PathBuf,
+    validators: PathBuf,
+    project_lib: PathBuf,
     project_name: String,
 }
 
 impl Creator {
     fn new(args: Args, project_name: String) -> Self {
         let root = args.name;
-        let src = root.join("src");
-        let scripts = src.join("scripts");
+        let lib = root.join("lib");
+        let validators = root.join("validators");
         let project_name = project_name;
-        let project = src.join(&project_name);
+        let project_lib = lib.join(&project_name);
         Self {
             root,
-            src,
-            scripts,
-            project,
+            lib,
+            validators,
+            project_lib,
             project_name,
         }
     }
 
     fn run(&self) -> miette::Result<()> {
-        fs::create_dir_all(&self.src).into_diagnostic()?;
-        fs::create_dir_all(&self.scripts).into_diagnostic()?;
-        fs::create_dir_all(&self.project).into_diagnostic()?;
+        fs::create_dir_all(&self.lib).into_diagnostic()?;
+        fs::create_dir_all(&self.project_lib).into_diagnostic()?;
+        fs::create_dir_all(&self.validators).into_diagnostic()?;
 
         self.aiken_toml()?;
         self.context()?;
@@ -52,18 +52,18 @@ impl Creator {
 
     fn always_true_script(&self) -> miette::Result<()> {
         write(
-            self.scripts.join("always_true.ak"),
+            self.validators.join("always_true.ak"),
             indoc! {"
                 pub fn spend() -> Bool {
                     True
-                }            
+                }
             "},
         )
     }
 
     fn project(&self) -> miette::Result<()> {
         write(
-            self.src.join(format!("{}.ak", self.project_name)),
+            self.lib.join(format!("{}.ak", self.project_name)),
             indoc! {"
                 pub type Datum {
                     something: String,
@@ -74,7 +74,7 @@ impl Creator {
 
     fn context(&self) -> miette::Result<()> {
         write(
-            self.project.join("context.ak"),
+            self.project_lib.join("context.ak"),
             indoc! {"
                 pub type ScriptContext(purpose) {
                     tx_info: TxInfo,
@@ -143,8 +143,7 @@ pub fn exec(args: Args) -> miette::Result<()> {
 
         validate_name(&project_name).into_diagnostic()?;
 
-        let creator = Creator::new(args, project_name);
-        creator.run()?;
+        Creator::new(args, project_name).run()?;
     }
 
     Ok(())