Merge branch 'main' into custom-inspect

.github/workflows/tests.yml

@@ -65,4 +65,4 @@ jobs:
         run: bash ./ci_scripts/check_index.sh
 
       # segfaults
-      # - run: ./roc_nightly/roc run main.roc -- examples build
+      # - run: ./roc_nightly/roc main.roc -- examples build

CONTRIBUTING.md

@@ -35,7 +35,7 @@ packages { pf: "/PATH_TO_ROC_REPO/examples/static-site-gen/platform/main.roc" }
 ```
 Generate the html files:
 ```
-roc run main.roc -- examples build 
+roc main.roc -- examples build 
 ```
 
 Copy the static assets from `./www` to `./build`:

ci_scripts/all_tests.sh

@@ -56,6 +56,9 @@ expect ci_scripts/expect_scripts/Tuples.exp
 
 $ROC test ./examples/TowersOfHanoi/Hanoi.roc
 
+$ROC build ./examples/Results/main.roc
+expect ci_scripts/expect_scripts/Results.exp
+
 $ROC build ./examples/Tasks/main.roc
 expect ci_scripts/expect_scripts/Tasks.exp
 

ci_scripts/expect_scripts/Arithmetic.exp

@@ -14,4 +14,4 @@ expect "sum: 24\r\ndifference: 16\r\nproduct: 80\r\ninteger quotient: 5\r\nremai
 }
 
 puts stderr "\nError: output was different from expected value."
-exit 1
+exit 1

ci_scripts/expect_scripts/Results.exp

@@ -0,0 +1,17 @@
+#!/usr/bin/expect
+
+# uncomment line below for debugging
+# exp_internal 1
+
+set timeout 7
+
+spawn ./examples/Results/main
+
+
+expect "Name: Harrison, George\r\nBorn:  1943\r\n\r\nName: Lennon, John\r\nBorn:  1940\r\n\r\nName: McCartney, Paul\r\nBorn:  1942\r\n\r\n" {
+  expect eof
+  exit 0
+}
+
+puts stderr "\nError: output was different from expected value."
+exit 1

examples/Arithmetic/README.md

@@ -12,7 +12,7 @@ file:main.roc
 Run this from the directory that has `main.roc` in it:
 
 ```
-$ roc run -- 20 4
+$ roc main.roc -- 20 4
 sum: 24
 difference: 16
 product: 80

examples/FizzBuzz/README.md

@@ -14,7 +14,7 @@ file:main.roc
 Run this from the directory that has `main.roc` in it:
 
 ```
-$ roc run
+$ roc main.roc
 1,2,Fizz,4,Buzz,Fizz,7,8,Fizz,Buzz,11,Fizz,13,14,FizzBuzz,16,17,Fizz,19,Buzz,Fizz,22,23,Fizz,Buzz,26,Fizz,28,29,FizzBuzz,31,32,Fizz,34,Buzz,Fizz,37,38,Fizz,Buzz,41,Fizz,43,44,FizzBuzz,46,47,Fizz,49,Buzz,Fizz,52,53,Fizz,Buzz,56,Fizz,58,59,FizzBuzz,61,62,Fizz,64,Buzz,Fizz,67,68,Fizz,Buzz,71,Fizz,73,74,FizzBuzz,76,77,Fizz,79,Buzz,Fizz,82,83,Fizz,Buzz,86,Fizz,88,89,FizzBuzz,91,92,Fizz,94,Buzz,Fizz,97,98,Fizz,Buzz
 ```
 

examples/GoPlatform/README.md

@@ -55,7 +55,7 @@ $ roc preprocess-host platform/dynhost platform/main.roc platform/libapp.so
 
 5. With our platform built we can run our app:
 ```bash
-$ roc run
+$ roc main.roc
 ```
 
 

examples/HelloWorld/README.md

@@ -12,6 +12,6 @@ file:main.roc
 Run this from the directory that has `main.roc` in it:
 
 ```
-$ roc run
+$ roc main.roc
 Hello, World!
 ```

examples/ImportFromDirectory/README.md

@@ -34,6 +34,6 @@ file:main.roc
 Run this from the directory that has `main.roc` in it:
 
 ```
-$ roc run
+$ roc main.roc
 Hello World from inside Dir!
 ```

examples/ImportPackageFromModule/README.md

@@ -9,12 +9,12 @@ But how can you use a package in a module?
 All dependencies go in the app file!
 
 So we have the app file just like before:
-```
+```roc
 file:main.roc
 ```
 And we put the unicode import in the module:
-```
-file:module.roc
+```roc
+file:Module.roc
 ```
 
 ## Output

examples/IngestFiles/README.md

@@ -17,6 +17,6 @@ file:main.roc
 Run this from the directory that has `main.roc` in it:
 
 ```
-$ roc run main.roc
+$ roc main.roc
 The quick brown fox jumps over the lazy dog
 ```

examples/Json/README.md

@@ -14,6 +14,6 @@ Run this from the directory that has `main.roc` in it:
 > Note: `--linker=legacy` is used here because of https://github.com/roc-lang/roc/issues/3609
 
 ```
-$ roc run --linker=legacy
+$ roc main.roc --linker=legacy
 Successfully decoded image, title:"View from 15th Floor"
 ```

examples/LeastSquares/README.md

@@ -14,7 +14,7 @@ file:main.roc
 Run this from the directory that has `main.roc` in it:
 
 ```
-$ roc run
+$ roc main.roc
 The least positive integer n, where the difference of n*n and (n-1)*(n-1) is greater than 1000, is 501
 ```
 

examples/MultipleRocFiles/README.md

@@ -21,6 +21,6 @@ file:main.roc
 Run this from the directory that has `main.roc` in it:
 
 ```
-$ roc run
+$ roc main.roc
 Hello World from interface!
 ```

examples/Parser/README.md

@@ -13,7 +13,7 @@ file:main.roc
 Run this from the directory that has `main.roc` in it:
 
 ```
-$ roc run
+$ roc main.roc
 I counted 7 letter A's!
 ```
 

examples/RandomNumbers/README.md

@@ -18,6 +18,6 @@ file:main.roc
 Run this from the directory that has `main.roc` in it:
 
 ```
-$ roc run
+$ roc main.roc
 Random numbers are: 29,30,71,64,48,33,55,68,53,28
 ```

examples/Results/README.md

@@ -0,0 +1,17 @@
+# Results & Error Handling
+
+This example shows how to use [`Result`](https://www.roc-lang.org/builtins/Result) in functions that can return errors. We will see how to use `Result.try` or the try operator `?` to chain functions and return the first error if any occurs.
+
+## Code
+
+```roc
+file:main.roc
+```
+
+## Output
+
+Run this from the directory that has `main.roc` in it:
+
+```sh
+roc examples/Results/main.roc
+```

examples/Results/main.roc

@@ -0,0 +1,103 @@
+app [main] {
+    pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.15.0/SlwdbJ-3GR7uBWQo6zlmYWNYOxnvo8r6YABXD-45UOw.tar.br",
+}
+
+import pf.Stdout
+
+## This function parses strings like "{FirstName} {LastName} was born in {Year}"
+## and if successful returns `Ok {firstName, lastName, birthYear}`. Otherwise
+## it returns an `Err` containing a descriptive tag.
+## This is the most verbose version, we will do better below.
+parseVerbose = \line ->
+    when line |> Str.splitFirst " was born in " is
+        Ok { before: fullName, after: birthYearStr } ->
+            when fullName |> Str.splitFirst " " is
+                Ok { before: firstName, after: lastName } ->
+                    when Str.toU16 birthYearStr is
+                        Ok birthYear ->
+                            Ok { firstName, lastName, birthYear }
+
+                        Err _ -> Err InvalidBirthYearFormat
+
+                _ -> Err InvalidNameFormat
+
+        _ -> Err InvalidRecordFormat
+
+## Here's a very slightly shorter version using `Result.try` to chain multiple
+## functions that each could return an error. It's a bit nicer, don't you think?
+## Note: this version returns "raw" errors (`Err NotFound` or `Err InvalidNumStr`).
+parseWithTry = \line ->
+    line
+    |> Str.splitFirst " was born in "
+    |> Result.try \{ before: fullName, after: birthYearStr } ->
+        fullName
+        |> Str.splitFirst " "
+        |> Result.try \{ before: firstName, after: lastName } ->
+            Str.toU16 birthYearStr
+            |> Result.try \birthYear ->
+                Ok { firstName, lastName, birthYear }
+
+## This version is like `parseWithTry`, except it uses `Result.mapErr`
+## to return more informative errors, just like the ones in `parseVerbose`.
+parseWithTryV2 = \line ->
+    line
+    |> Str.splitFirst " was born in "
+    |> Result.mapErr \_ -> Err InvalidRecordFormat
+    |> Result.try \{ before: fullName, after: birthYearStr } ->
+        fullName
+        |> Str.splitFirst " "
+        |> Result.mapErr \_ -> Err InvalidNameFormat
+        |> Result.try \{ before: firstName, after: lastName } ->
+            Str.toU16 birthYearStr
+            |> Result.mapErr \_ -> Err InvalidBirthYearFormat
+            |> Result.try \birthYear ->
+                Ok { firstName, lastName, birthYear }
+
+## The `?` operator, called the "try operator", is
+## [syntactic sugar](en.wikipedia.org/wiki/Syntactic_sugar) for `Result.try`.
+## It makes the code much less nested and easier to read.
+## The following function is equivalent to `parseWithTry`:
+parseWithTryOp = \line ->
+    { before: fullName, after: birthYearStr } = Str.splitFirst? line " was born in "
+    { before: firstName, after: lastName } = Str.splitFirst? fullName " "
+    birthYear = Str.toU16? birthYearStr
+    Ok { firstName, lastName, birthYear }
+
+## And lastly the following function is equivalent to `parseWithTryV2`.
+## Note that the `?` operator has moved from `splitFirst` & `toU16` to `mapErr`:
+parseWithTryOpV2 = \line ->
+    { before: fullName, after: birthYearStr } =
+        line
+            |> Str.splitFirst " was born in "
+            |> Result.mapErr? \_ -> Err InvalidRecordFormat
+    { before: firstName, after: lastName } =
+        fullName
+            |> Str.splitFirst " "
+            |> Result.mapErr? \_ -> Err InvalidNameFormat
+    birthYear =
+        Str.toU16 birthYearStr
+            |> Result.mapErr? \_ -> Err InvalidBirthYearFormat
+    Ok { firstName, lastName, birthYear }
+
+## This function parses a string using a given parser and returns a string to
+## display to the user. Note how we can handle errors individually or in bulk.
+parse = \line, parser ->
+    when parser line is
+        Ok { firstName, lastName, birthYear } ->
+            """
+            Name: $(lastName), $(firstName)
+            Born:  $(birthYear |> Num.toStr)
+
+            """
+
+        Err InvalidNameFormat -> "What kind of a name is this?"
+        Err InvalidBirthYearFormat -> "That birth year looks fishy."
+        Err InvalidRecordFormat -> "Oh wow, that's a weird looking record!"
+        _ -> "Something unexpected happened" # Err NotFound or Err InvalidNumStr
+
+main =
+    "George Harrison was born in 1943" |> parse parseVerbose |> Stdout.line!
+    "John Lennon was born in 1940" |> parse parseWithTry |> Stdout.line!
+    "Paul McCartney was born in 1942" |> parse parseWithTryV2 |> Stdout.line!
+    "Ringo Starr was born in 1940" |> parse parseWithTryOp |> Stdout.line!
+    "Stuart Sutcliffe was born in 1940" |> parse parseWithTryOpV2 |> Stdout.line!

examples/TaskLoop/README.md

@@ -60,7 +60,7 @@ file:main.roc
 Run this from the directory that has `main.roc` in it:
 
 ```
-$ roc run main.roc < numbers.txt 
+$ roc main.roc < numbers.txt 
 Enter some numbers on different lines, then press Ctrl-D to sum them up.
 Sum: 178
 ```

examples/Tuples/README.md

@@ -18,7 +18,7 @@ file:main.roc
 Run this from the directory that has `main.roc` in it:
 
 ```
-$ roc run
+$ roc main.roc
 First is: A String,
 Second is: true,
 Third is: 15000000.

examples/index.md

@@ -9,6 +9,7 @@ You can find the source code for all of these at [github.com/roc-lang/examples](
 - [Basic Dict Usage](/BasicDict/README.html)
 - [Tuples](/Tuples/README.html)
 - [Pattern Matching on Lists](/PatternMatching/README.html)
+- [Results & Error Handling](/Results/README.html)
 - [Tasks & Error Handling](/Tasks/README.html)
 - [Import Files](/IngestFiles/README.html)
 - [Import from Directory](/ImportFromDirectory/README.html)