Roc

# Click anything here to see an explanation.Tap anything here to
# see an explanation.X
Comments in Roc begin with # and go to the end of the line.
main =X
This defines main, which is where our program will begin.
In Roc, all definitions are constant, so writing main = again in the same scope would give an error.
    Path.fromStr "url.txt"X
This converts the string "url.txt" into a Path by passing it to Path.fromStr.
Function arguments are separated with whitespace. Parentheses are only needed in nested function calls.
    |> storeEmailX
The pipe operator (|>) is syntax sugar for passing the previous value to the next function in the "pipeline."
This line takes the value that Path.fromStr "url.txt" returns and passes it to storeEmail.
The next |> continues the pipeline.
    |> Task.onErr handleErrX
If the task returned by the previous step in the pipeline fails, pass its error to handleErr.
The pipeline essentially does this:
a = Path.fromStr "url.txt"
b = storeEmail a

Task.onErr b handleErr
It creates a Path from a string, passes it to storeEmail, and specifies how to handle errors if storing the email fails.

storeEmail = \path ->X
This defines a function named storeEmail. It takes one argument, named path.
In Roc, functions are ordinary values, so we assign names to them using = like with any other value.
The \arg1, arg2 -> syntax begins a function, and the part after -> is the function's body.
    url = File.readUtf8! pathX
This passes path to the File.readUtf8 function, which reads the contents of the file (as a UTF-8 string) into url.
The ! operator is similar to await in other languages. It means “wait until the asynchronous File.readUtf8 operation successfully completes.”
If the file read fails (maybe because path refers to a missing file), the rest of this function will be skipped, and the handleErr function will take over.
    user = Http.get! url Json.utf8X
This fetches the contents of the URL and decodes them as JSON.
If the shape of the JSON isn't compatible with the type of user (based on type inference), this will give a decoding error immediately.
As with all the other function calls involving the ! operator, if there's an error, nothing else in storeEmail will be run, and handleErr will run.
    dest = Path.fromStr "$(user.name).txt"X
The $(user.name) in this string literal will be replaced with the value stored in the user record's name field. This is string interpolation.
Note that this function call doesn't involve the ! operator. That's because Path.fromStr doesn't involve any Tasks, so there's no need to use ! to wait for it to finish.
    File.writeUtf8! dest user.emailX
This writes user.email to the file, encoded as UTF-8.
Since File.writeUtf8 doesn't produce any information on success, we don't bother using = like we did on the other lines.
    Stdout.line! "Wrote email to $(Path.display dest)"X
This prints what we did to stdout.
Notice that this does a function call inside the string interpolation. Any valid Roc expression is allowed inside string interpolation, as long as it doesn't contain any newlines.

handleErr = \err ->X
Like storeEmail, handleErr is also a function.
Although type annotations are optional everywhere in Roc—because the language has 100% type inference—you could add type annotations to main, storeEmail, and handleErr if you wanted to.
    when err isX
This will run one of the following lines depending on what value the err argument has.
Each line does a pattern match on the shape of the error to decide whether to run, or to move on and try the next line's pattern.
Roc will do compile-time exhaustiveness checking and tell you if you forgot to handle any error cases here that could have occurred, based on the tasks that were run in storeEmail.
        HttpErr url _ -> Stderr.line! "Error fetching URL $(url)"X
This line will run if the Http.get request from earlier encountered an HTTP error.
It handles the error by printing an error message to stderr.
The _ is where more information about the error is stored in the HttpErr. If we wanted to print more detail about what the error was, we'd name that something other than _ and actually use it.
        FileReadErr path _ -> Stderr.line! "Error reading from $(Path.display path)"X
This line will run if the File.readUtf8 from earlier encountered a file I/O error.
It handles the error by printing an error message to stderr.
The _ is where more information about the error is stored in the FileReadErr. If we wanted to print more detail about what the error was, we'd name that something other than _ and actually use it.
        FileWriteErr path _ -> Stderr.line! "Error writing to $(Path.display path)"X
This line will run if the File.writeUtf8 from earlier encountered a file I/O error.
It handles the error by printing an error message to stderr.
The _ is where more information about the error is stored in the FileWriteErr. If we wanted to print more detail about what the error was, we'd name that something other than _ and actually use it.

To get started with the language, try the tutorial!

Start Tutorial