First programs: scala run, scripts and the REPL

A Scala program needs one method marked @main and nothing else. The tip calculator below is seven lines, and scala run . -- 4250 15 compiles it and prints a tip of 638 cents on a bill of 4,250 cents. The same command runs scripts, and scala repl answers one line of code at a time.

This lesson writes that first program, shows what it does when its arguments are wrong, runs a script, explores types in the REPL, and explains the compile server that keeps scala run quick on your computer, and why the runs in this track switch it off.

@main turns a method into a program with typed arguments

Here is the whole program. The arithmetic is an ordinary function, and the method marked @main reads the bill and the percentage from the command line:

// A tip calculator: the arithmetic is a plain function, and @main turns the rest into a program.
def tipCents(billCents: Long, percent: Int): Long =
  (billCents * percent + 50) / 100

@main def tip(billCents: Long, percent: Int): Unit =
  val t = tipCents(billCents, percent)
  println(s"Tip: $t cents. Total: ${billCents + t} cents.")

scala run . compiles every Scala file in the current folder and starts the program, and everything after -- goes to the program as its arguments. The session runs it four times, with good arguments, with a word where a number belongs, with one argument missing and with one too many:

from session import run

# The tip program with good arguments, with one that does not parse, with one missing and with one too many.
run("""
cd tip
scala run . --server=false -- 4250 15
scala run . --server=false -- 4250 fifteen
scala run . --server=false -- 4250
scala run . --server=false -- 4250 15 99
""")

$ cd tip
$ scala run . --server=false -- 4250 15
Tip: 638 cents. Total: 4888 cents.
$ scala run . --server=false -- 4250 fifteen
Illegal command line after first argument: java.lang.NumberFormatException: For input string: "fifteen"
$ scala run . --server=false -- 4250
Illegal command line after first argument: more arguments expected
$ scala run . --server=false -- 4250 15 99
Tip: 638 cents. Total: 4888 cents.

The first run worked: (4250 * 15 + 50) / 100 is 638 in whole-number arithmetic, so the tip rounds to the nearest cent. The arguments arrive as text, and the @main method@main method: A method marked @main, which the compiler turns into a program: a class with the method's name and a static main method that converts each command-line argument to its parameter's type. converts each one to its parameter’s type before your code runs: "4250" to a Long and "15" to an Int. When a conversion fails, the program prints Illegal command line with the reason, here a NumberFormatException for "fifteen", and when an argument is missing it says more arguments expected. The fourth run shows a quieter case: the extra 99 was ignored.

Step through what happened inside the first run:

The conversion works for every parameter type that has a FromString instance in scala.util.CommandLineParser: String, Boolean and the number types come with one, and your own types can get one too.

scala run compiles the whole folder, not one file

scala run . takes the folder, not a file, so it compiles every .scala and .sc file in it. Put the tip program and a hello program in one folder, and the command no longer knows which program to start:

from session import run

# One folder with two @main methods: scala run . must be told which program to start.
run("""
cd two-mains
!scala run . --server=false
scala run . --server=false --main-class hello
""")

$ cd two-mains
$ scala run . --server=false
[error]  Found several main classes: hello, tip
You can run one of them by passing it with the --main-class option, e.g.
  scala run . --server=false --main-class hello

You can pick the main class interactively by passing the --interactive option.
  scala run . --server=false --interactive
[exit status 1]
$ scala run . --server=false --main-class hello
Hello from Scala 3.9.0

Each @main method made a program named after the method, hello and tip, and Scala CLI stops rather than guess. --main-class hello chooses one; --interactive, which the message also offers, asks you to pick from a list, which works at a keyboard but not in a script or CI. A .sc script left in the same folder is compiled along with the rest, so a forgotten file with a mistake in it stops the run too. While you learn, keep one program per folder, or name the file, as in scala run tip.scala, which compiles that file alone.

A script runs from top to bottom

A scriptscript: A .sc file whose top-level statements run from top to bottom, with the command-line arguments in args. Scala CLI wraps it in a class with a main method before it runs. is a .sc file with statements at the top level and no @main method. Scala CLI wraps the statements in a class with a main method of its own, runs them in order, and passes the words after -- in a value named args:

// A script: its statements run from top to bottom, and args holds the words after -- on the command line.
val expenses = List("train" -> 4250L, "hostel" -> 9800L, "food" -> 3675L)
for (name, cents) <- expenses do println(f"$name%-7s $cents%6d")
val total = expenses.map(_._2).sum
println(f"${"total"}%-7s $total%6d")
if args.nonEmpty then
  println(s"Each of ${args.mkString(", ")} pays ${total / args.length} cents.")

from session import run

# A script runs from top to bottom; the words after -- reach it as args.
run("""
cd script
scala run expenses.sc --server=false
scala run expenses.sc --server=false -- Asha Ben
""")

$ cd script
$ scala run expenses.sc --server=false
train     4250
hostel    9800
food      3675
total    17725
$ scala run expenses.sc --server=false -- Asha Ben
train     4250
hostel    9800
food      3675
total    17725
Each of Asha, Ben pays 8862 cents.

Without arguments the if at the end does nothing; with two names it splits the total. Look at the share: 17,725 cents between two people is 8,862.5, and dividing two whole numbers drops the half, so one cent is lost. Money in this track is counted in whole cents, so that rounding is always visible.

Scripts suit quick jobs, such as adding up a list, renaming files or trying an idea. Move the code into .scala files as soon as it needs tests, a second file that uses its functions, or a name of its own as a program: definitions in a .scala file can be imported and tested, while a script runs once, from top to bottom.

The REPL answers one line at a time

The REPLREPL: Read-eval-print loop: a prompt that compiles and runs each line you type, then prints the value and its type, so you can try code without writing a program., short for read-eval-print loop, compiles and runs each line you type and prints what it got. scala repl opens it, and :quit closes it. The session typed eight lines; each answer comes right after the line it answers:

from session import repl

# The REPL in a terminal of its own: each line is typed after the scala> prompt, and the REPL answers it.
repl([
    "val bill = 4250L",
    "bill * 15 / 100",
    ":type bill * 15 / 100",
    'val code: Int | String = "A1"',
    "def tipCents(billCents: Long, percent: Int): Long = (billCents * percent + 50) / 100",
    "tipCents(bill, 15)",
    'List("train" -> 4250L, "food" -> 3675L)',
    ":quit",
])

$ scala repl --server=false
Welcome to Scala 3.9.0 (25.0.4.1, Java OpenJDK 64-Bit Server VM).
Type in expressions for evaluation. Or try :help.

scala> val bill = 4250L
val bill: Long = 4250L

scala> bill * 15 / 100
val res0: Long = 637L

scala> :type bill * 15 / 100
Long

scala> val code: Int | String = "A1"
val code: Int | String = "A1"

scala> def tipCents(billCents: Long, percent: Int): Long = (billCents * percent + 50) / 100
def tipCents(billCents: Long, percent: Int): Long

scala> tipCents(bill, 15)
val res1: Long = 638L

scala> List("train" -> 4250L, "food" -> 3675L)
val res2: List[(String, Long)] = List(("train", 4250L), ("food", 3675L))

scala> :quit

Read the answers as declarations. val bill: Long = 4250L says that bill is a Long, inferred from the L at the end of 4250L. An expression that you do not name gets one: res0, then res1 and so on, which you can use in later lines. :type prints only the type of an expression, without running it. Int | String is a union type, a value that is either an Int or a String; the REPL is a quick way to see such types. A def answers with its signature, and since Scala 3.8 the REPL pretty-prints results, which is why strings appear in quotes and Long values with their L.

The REPL forgets everything when you quit. For experiments you want to keep, an editor offers worksheets: a file whose name ends in .worksheet.sc. Metals in VS Code evaluates it each time you save it, IntelliJ IDEA when you press its run arrow, and both show each line’s result beside it.

The compile server is fast once it is running, and needs a download first

On your computer, scala run compiles through a compile servercompile server: A background JVM that keeps a warm Scala compiler between builds. Scala CLI uses Bloop by default and downloads it on first use; --server=false compiles inside the scala command instead. called Bloop: a background JVM that keeps a warm compiler between runs, so a second run after a small change compiles quickly. Scala CLI downloads Bloop the first time it needs it, starts it, and leaves it running after the command ends; scala --power bloop exit stops it. --server=false skips the server: the scala command starts a fresh compiler for that one run, which starts cold every time, ends with the command and prints the compiler’s own messages unchanged. The Scala CLI documentation suggests it for setups with limited web access, and that is the case the session below shows: a computer that has never downloaded Bloop, with no network:

from session import run

# Without network access: the first run with the compile server needs Bloop, which has never been downloaded here.
run("""
cd hello
!scala run .
scala run . --server=false
""", downloads="first")

$ cd hello
$ scala run .
Downloading https://repo1.maven.org/maven2/ch/epfl/scala/bloop-frontend_2.12/2.1.1/bloop-frontend_2.12-2.1.1.pom
Failed to download https://repo1.maven.org/maven2/ch/epfl/scala/bloop-frontend_2.12/2.1.1/bloop-frontend_2.12-2.1.1.pom
[10 more lines of download attempts not shown]
Error: java.lang.Exception: Error getting Bloop class path
For more details, please see '.scala-build/stacktraces/<n>.log'
[exit status 1]
$ scala run . --server=false
Hello from Scala 3.9.0

The first command tried to download Bloop from Maven Central, every attempt failed, and it stopped with Error getting Bloop class path. The second compiled and ran the same program with --server=false, from what was already on the computer. Step through both kinds of run:

So leave the server on for your own work: after its first download it makes every later run in a session faster. Turn it off with --server=false on a computer without network access, in a CI job that should leave no background process behind, and whenever you want the compiler’s messages exactly as it prints them, which is why every run in this track uses it.

Practise: split a bill

The program below shares a bill equally among some people and says how many cents are left over. Both functions return 0 for now, and a second @main method, checks, tests them on four cases. Copy the folder, write the two functions, and run scala run . --main-class checks until all four pass; then try scala run . --main-class split -- 17725 3 on your own numbers:

// Practise: share a bill equally. Write the two functions so that every check passes, then run the checks with
//   scala run . --main-class checks
def shareCents(totalCents: Long, people: Int): Long = 0

def leftoverCents(totalCents: Long, people: Int): Long = 0

@main def split(totalCents: Long, people: Int): Unit =
  val share = shareCents(totalCents, people)
  val left = leftoverCents(totalCents, people)
  println(s"Each of $people people pays $share cents, and $left cents are left over.")

@main def checks(): Unit =
  val cases = List((17725L, 2, 8862L, 1L), (17725L, 3, 5908L, 1L), (900L, 4, 225L, 0L), (5L, 7, 0L, 5L))
  val results =
    for (total, people, share, left) <- cases yield
      val ok = shareCents(total, people) == share && leftoverCents(total, people) == left
      println(s"${if ok then "ok  " else "FAIL"} $total cents among $people: share $share, left over $left")
      ok
  println(s"${results.count(ok => ok)} of ${results.size} checks pass")
  if results.contains(false) then sys.exit(1)

As given, every check fails, the checks end with status 1, and the program itself prints nonsense:

from session import run

# The practice program as given: both functions return 0, so the checks fail and the program reports nonsense.
run("""
cd split
!scala run . --server=false --main-class checks
scala run . --server=false --main-class split -- 17725 3
""")

$ cd split
$ scala run . --server=false --main-class checks
FAIL 17725 cents among 2: share 8862, left over 1
FAIL 17725 cents among 3: share 5908, left over 1
FAIL 900 cents among 4: share 225, left over 0
FAIL 5 cents among 7: share 0, left over 5
0 of 4 checks pass
[exit status 1]
$ scala run . --server=false --main-class split -- 17725 3
Each of 3 people pays 0 cents, and 0 cents are left over.

First hint: whole-number division / drops the remainder, and % gives exactly what it dropped, so 17,725 among 3 is 17725 / 3 cents each and 17725 % 3 cents left over.

Then put the five ideas of this lesson to work in thirteen short questions, from a program’s arguments to the compile server; each one shows why its answer is right as soon as you check it:

Interview questions

Fresher · What does @main do in Scala 3, and how is it different from writing def main(args: Array[String]) yourself?

@main on a method tells the compiler to generate a program: a class named after the method, with the standard public static void main(String[]) that the JVM starts. The generated main converts each command-line argument to the type of the matching parameter, using a FromString instance from scala.util.CommandLineParser, and calls your method. A bad or missing argument makes it print Illegal command line with the reason, and it ignores extra arguments. With def main(args: Array[String]) inside an object you get the raw strings and do every conversion and check yourself, which gives you full control over messages and exit status, and it is the form that also compiles with Scala 2. @main is the shorter and recommended way for Scala 3 programs; the hand-written form suits tools that need their own argument handling.

Key takeaways

• An @main method is a program: scala run . -- 4250 15 compiles the folder and converts each argument to the type of its parameter.
• A bad or missing argument prints Illegal command line, an extra one is ignored, and the exit status stays 0, so check arguments yourself when callers rely on the status.
• scala run . compiles every file in the folder and refuses to guess between two @main methods; choose with --main-class, or keep one program per folder.
• A .sc script runs its statements from top to bottom with its arguments in args; code that needs tests belongs in .scala files.
• The REPL prints the name, type and value of every line, :type shows a type without running anything, and worksheets keep experiments in a file.
• The compile server, Bloop, keeps a warm compiler after a first download; --server=false starts a fresh compiler for each run, leaves nothing running and needs no download of Bloop.