From df8c0d9eddbe11efb2051f95d24b5c58efb55b31 Mon Sep 17 00:00:00 2001 From: Richard Feldman Date: Sat, 26 Nov 2022 17:44:33 -0500 Subject: [PATCH] Update tutorial to use basic-cli URLs --- www/public/tutorial/index.html | 78 +++++++++++++++------------------- 1 file changed, 35 insertions(+), 43 deletions(-) diff --git a/www/public/tutorial/index.html b/www/public/tutorial/index.html index 87771cfd20..bc9e337f92 100644 --- a/www/public/tutorial/index.html +++ b/www/public/tutorial/index.html @@ -175,20 +175,16 @@ to use them for more than that.

Let's move out of the REPL and create our first Roc application!

Make a file named main.roc and put this in it:

app "hello" - packages { pf: "examples/cli/cli-platform/main.roc" } + packages { pf: "https://github.com/roc-lang/basic-cli/releases/download/0.1.0/_V6HO2Dwez0xsSstgK8qC6wBLXSfNlVFyUTMg0cYiQQ.tar.br" } imports [pf.Stdout] provides [main] to pf main = Stdout.line "I'm a Roc application!" -

In order to get access to this examples/cli/cli-platform/main.roc file, you'll need -to download the Roc source code repository, which -contains the examples directory at the beginning of that string. Make sure you cd -into that directory once you've downloaded it!

Try running this with:

roc dev -

You should see this printed to the terminal:

+

You should a see a message about a file being downloaded, followed by this:

I'm a Roc application!

Congratulations - you've written your first Roc application! We'll go over what the parts of this file above main do later, but first let's play around a bit.

@@ -203,7 +199,9 @@ total = Num.toStr (birds = Stdout.line "There are \(total) animals." -

Now if you run roc dev, you should see this:

+

Now run roc dev again. This time the "Downloading …" message won't appear; +the file has been cached from last time, and won't need to be downloaded again.

+

You should see this:

There are 5 animals.

main.roc now has four definitions—defs for short—birds, iguanas, total, and main.

@@ -367,8 +365,16 @@ because total is calling addAndStringify passing a rec

Comments

By the way, this is a comment in Roc:

# The `name` field is unused by addAndStringify -

Whenever you write # it means that the rest of the line is a comment, -and will have no effect on the program.

+

Whenever you write # it means that the rest of the line is a comment, +and will not affect the program.

+

Doc Comments

+

Comments that begin with ## will be included in generated documentation (roc docs). They can include code blocks by adding five spaces after ##.

+## This is a comment for documentation, and includes a code block. +## +## x = 2 +## expect x == 2 + +

Roc does not have multiline comment syntax.

Record shorthands

Roc has a couple of shorthands you can use to express some record-related operations more concisely.

Instead of writing \record -> record.x we can write .x and it will evaluate to the same thing: @@ -1231,7 +1237,7 @@ Roc compiler. That's why they're called "builtins!"

The app module header

Let's take a closer look at the part of main.roc above the main def:

app "hello" - packages { pf: "examples/cli/cli-platform/main.roc" } + packages { pf: "https://github.com/roc-lang/basic-cli/releases/download/0.1.0/_V6HO2Dwez0xsSstgK8qC6wBLXSfNlVFyUTMg0cYiQQ.tar.br" } imports [pf.Stdout] provides main to pf @@ -1244,13 +1250,18 @@ means when you run roc dev, the Roc compiler will build an executab named hello (or hello.exe on Windows) and run it. You can also build the executable without running it by running roc build.

The remaining lines all involve the platform this application is built on:

-packages { pf: "examples/cli/cli-platform/main.roc" } -imports [pf.Stdout] -provides main to pf +packages { pf: "https://github.com/roc-lang/basic-cli/releases/download/0.1.0/_V6HO2Dwez0xsSstgK8qC6wBLXSfNlVFyUTMg0cYiQQ.tar.br" } +imports [pf.Stdout] +provides [main] to pf -

The packages { pf: "examples/cli/cli-platform/main.roc" } part says two things:

+

The packages { pf: "https://…tar.br" } part says three things:

    -
  • We're going to be using a package (that is, a collection of modules) called "examples/cli/cli-platform/main.roc"
    • +
  • We're going to be using a package (that is, a collection of modules) that can be downloaded from the URL "https://…tar.br"
    • +
  • That package's base64url-encoded BLAKE3 +cryptographic hash is the long string at the end (before the .tar.br file extension). +Once the file has been downloaded, its contents will be verified against this hash, and it will only +be installed if they match. (This way, you can be confident the download was neither corrupted nor +changed since it was originally published.)
  • We're going to name that package pf so we can refer to it more concisely in the future.

The imports [pf.Stdout] line says that we want to import the Stdout module @@ -1263,34 +1274,15 @@ at that again:

calling a function named line which is exposed by a module named Stdout.

When we write imports [pf.Stdout], it specifies that the Stdout -module comes from the pf package.

-

Since pf was the name we chose for the examples/cli/cli-platform/main.roc -package (when we wrote packages { pf: "examples/cli/cli-platform/main.roc" }), -this imports line tells the Roc compiler that when we call Stdout.line, it -should look for that line function in the Stdout module of the -examples/cli/cli-platform/main.roc package.

+module comes from the package we named pf in the packages { pf: … } section.

If we would like to include other modules in our application, say AdditionalModule.roc and AnotherModule.roc, then they can be imported directly in imports like this:

-packages { pf: "examples/cli/cli-platform/main.roc" } -imports [pf.Stdout, AdditionalModule, AnotherModule] -provides main to pf +imports [pf.Stdout, AdditionalModule, AnotherModule] -

Comments

-

Comments that begin with ## will be included in generated documentation (roc docs). They require a single space after the ##, and can include code blocks by adding five spaces after ##.

-## This is a comment for documentation, and includes a code block. -## -## x = 2 -## expect x == 2 - -

Roc also supports inline comments and line comments with #. They can be used to add information that won't be included in documentation.

-# This is a line comment that won't appear in documentation. -myFunction : U8 -> U8 -myFunction = \bit -></span> bit % 2 # this is an inline comment - -

Roc does not have multiline comment syntax.

Tasks

Tasks are technically not part of the Roc language, but they're very common in -platforms. Let's use the CLI platform in examples/cli/cli-platform/main.roc as an example!

-

In the CLI platform, we have four operations we can do:

+platforms. Let's continue using the basic-cli platform +we've been using up to this point as an example!

+

In the basic-cli platform, we have four operations we can do:

  • Write a string to the console
  • Read a string from user input
    • @@ -1298,9 +1290,9 @@ platforms. Let's use the CLI platform in examples/cli/cli-platform/main.ro
  • Read a string from a file

We'll use these four operations to learn about tasks.

-

First, let's do a basic "Hello World" using the tutorial app.

+

Let's start with a basic "Hello World" program.

app "cli-tutorial" - packages { pf: "examples/cli/cli-platform/main.roc" } + packages { pf: "https://github.com/roc-lang/basic-cli/releases/download/0.1.0/_V6HO2Dwez0xsSstgK8qC6wBLXSfNlVFyUTMg0cYiQQ.tar.br" } imports [pf.Stdout] provides [main] to pf @@ -1325,7 +1317,7 @@ when it runs (hence the *).

Let's change main to read a line from stdin, and then print it back out again:

app "cli-tutorial" - packages { pf: "examples/cli/cli-platform/main.roc" } + packages { pf: "https://github.com/roc-lang/basic-cli/releases/download/0.1.0/_V6HO2Dwez0xsSstgK8qC6wBLXSfNlVFyUTMg0cYiQQ.tar.br" } imports [pf.Stdout, pf.Stdin, pf.Task] provides [main] to pf @@ -1360,7 +1352,7 @@ the program isn't doing anything when we start it up:

This works, but we can make it a little nicer to read. Let's change it to the following:

app "cli-tutorial" - packages { pf: "examples/cli/cli-platform/main.roc" } + packages { pf: "https://github.com/roc-lang/basic-cli/releases/download/0.1.0/_V6HO2Dwez0xsSstgK8qC6wBLXSfNlVFyUTMg0cYiQQ.tar.br" } imports [pf.Stdout, pf.Stdin, pf.Task.{ await }] provides [main] to pf