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.
    store_email!(Path.from_str("url.txt")) ? handle_err!X
This converts the string "url.txt" into a Path by passing it to Path.from_str.
It then sends that result to store_email!. The ! sigil at the end tells you that this function is
effectual, meaning it will either do I/O, talk to the network, or can otherwise return a different result each time
it's called.  Functions that do not end in ! will always return the same result given the same arguments.
Function arguments are surrounded with parenthesis and separated by commas.
The ? infix operator here will return the result if successful, otherwise it will call handle_err!
with the error if it fails.

store_email! = |path|X
This defines a function named store_email!.
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 the final | is the function's body.
    url = File.read_utf8!(path)?X
This passes path to the File.read_utf8 function, which reads the contents of the file
(as a UTF-8 string) into url.
The ! sigil at the end tells you that this function is effectual, meaning it will either
do I/O, talk to the network, or can otherwise return a different result each time it's called.  Functions that do
not end in ! will always return the same result given the same arguments.
The ? is an operator that means, if the file read fails (maybe because path refers to a missing file),
the rest of this function will be skipped, and the handle_err function will take over.
    user = Http.get!(url, Json.utf8)?X
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 that end with the ? postfix operator, if there's an error,
nothing else in store_email! will be run, and handle_err! will run.
    dest = Path.from_str("${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.from_str isn't an effectual function and can't fail, so there's no need to use ? to handle it's result.
    File.write_utf8!(dest, user.email)?X
This writes user.email to the file, encoded as UTF-8.
Since File.write_utf8! 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.

handle_err! = |err|X
Like store_email!, handle_err! 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!, store_email!, and handle_err! 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 store_email.
        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.read_utf8! 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.write_utf8! 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