From 668cf19340918b20090b0ebf487dc65e95b53e1c Mon Sep 17 00:00:00 2001 From: Seth Tisue Date: Tue, 7 Feb 2017 15:13:24 -0800 Subject: [PATCH 1/3] many small tweaks to the Basics page all of these changes are small, don't involve changing ordering, and are hopefully not controversial. --- tutorials/tour/basics.md | 73 ++++++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 33 deletions(-) diff --git a/tutorials/tour/basics.md b/tutorials/tour/basics.md index 82b1afc3ce..a674f474ab 100644 --- a/tutorials/tour/basics.md +++ b/tutorials/tour/basics.md @@ -14,13 +14,13 @@ In this page, we will cover basics of Scala. ## Trying Scala in the Browser -You can run Scala in your browser by using [ScalaFiddle](https://scalafiddle.io). +You can run Scala in your browser with [ScalaFiddle](https://scalafiddle.io). 1. Go to https://scalafiddle.io. -2. Copy and paste `println("Hello, world!")` to the left pane. -3. Hit "Run" button and see it prints "Hello, world!" on the right pane. +2. Paste `println("Hello, world!")` in the left pane. +3. Hit "Run" button. Output appears in the right pane. -It is a perfect way for anybody to experiment with a piece of Scala code anywhere, anytime! +This is an easy, zero-setup way to experiment with pieces of Scala code. ## Expressions @@ -37,14 +37,15 @@ println("Hello," + " world!") // Hello, world! ### Values -You can name results of expressions by using the `val` keyword. +You can name results of expressions with the `val` keyword. ``` val x = 1 + 1 -println(x) // 2 +println(x * x) // 4 ``` -Named results are called values. For example, in above case, `x` is called a value. Values only hold results of expressions, so they will not re-compute expressions when referenced. +Named results, such as `x` here, are called values. Referencing +a value does not re-compute it. Values cannot be re-assigned. @@ -53,7 +54,7 @@ val x = 1 + 1 x = 3 // This does not compile. ``` -Types of values can be inferred, but you can also explicitly state types like below. +Types of values can be inferred, but you can also explicitly state the type, like this: ``` val x: Int = 1 + 1 @@ -61,15 +62,15 @@ val x: Int = 1 + 1 ### Variables -Variables are similar to values except you can re-assign results they hold. You can define variables with the `var` keyword. +Variables are like values, except you can re-assign them. You can define a variable with the `var` keyword. ``` var x = 1 + 1 x = 3 // This compiles because "x" is declared with the "var" keyword. -println(x) // 3 +println(x * x) // 9 ``` -Just like values, you can also explicitly state types of variables like below. +As with values, you can explicitly state the type if you want: ``` var x: Int = 1 + 1 @@ -77,9 +78,9 @@ var x: Int = 1 + 1 ### Blocks -You can create a single expression out of multiple statements by wrapping them with `{}`. We call them blocks or block expressions. +You can combine expressions by surrounding them with `{}`. We call this a block. -The result of the last statement of the block will be the result of the overall block. +The result of the last expression in the block is the result of the overall block, too. ``` println({ @@ -90,15 +91,15 @@ println({ ## Functions -Functions are expressions with parameters. +Functions are expressions that take parameters and compute a result. -You can define a function that returns a given integer + 1 like below. +You can define a function that returns a given integer plus one: ``` (x: Int) => x + 1 ``` -Left hand side of `=>` is a list of parameters and right hand side of `=>` is an expression taking the parameters. +On the left of `=>` is a list of parameters. On the right is an expression involving the parameters. You can also name functions. @@ -107,7 +108,7 @@ val addOne = (x: Int) => x + 1 println(addOne(1)) // 2 ``` -Or it can take multiple parameters. +Functions may take multiple parameters. ``` val add = (x: Int, y: Int) => x + y @@ -127,7 +128,7 @@ We will cover functions in depth [later](anonymous-function-syntax.md). Methods look and behave very similar to functions, but there are a few key differences between them. -Methods are defined like below with the `def` keyword followed by its name, a list of parameter groups, return type, and an expression. +Methods are defined with the `def` keyword. `def` is followed by a name, parameter lists, a return type, and a body. ``` def add(x: Int, y: Int): Int = x + y @@ -142,14 +143,14 @@ val add2 = add // This does not compile. var add3 = add // This does not compile either. ``` -Methods can take multiple parameter groups. +Methods can take multiple parameter lists. ``` def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier println(addThenMultiply(1, 2)(3)) // 9 ``` -Or no parameter groups at all. +Or no parameter lists at all. ``` def name: String = System.getProperty("name") @@ -163,12 +164,13 @@ There are some other differences, but for now, you can think of them as somethin You can define classes with the `class` keyword followed by its name and constructor parameters. ``` -class Greeter(prefix: String, postfix: String) { - def greet(name: String): Unit = println(prefix + name + postfix) +class Greeter(prefix: String, suffix: String) { + def greet(name: String): Unit = + println(prefix + name + suffix) } ``` -You can instantiate classes with the `new` keyword. +You can make an instance of a class with the `new` keyword. ``` val greeter = new Greeter("Hello, ", "!") @@ -179,7 +181,7 @@ We will cover classes in depth [later](classes.md). ## Case Classes -Scala has a special type of class called case class that's immutable and compared by value by default. You can define case classes with the `case class` keyword. +Scala has a special type of class called a "case" class. By default, case classes are immutable and compared by value. You can define case classes with the `case class` keywords. ``` case class Point(x: Int, y: Int) @@ -193,7 +195,7 @@ val anotherPoint = Point(1, 2) val yetAnotherPoint = Point(2, 2) ``` -And they are compared by values. +And they are compared by value. ``` if (point == anotherPoint) { @@ -222,7 +224,6 @@ You can define objects with the `object` keyword. ``` object IdFactory { private var counter = 0 - def create(): Int = { counter += 1 counter @@ -230,7 +231,7 @@ object IdFactory { } ``` -You can access objects by referring its name. +You can access an object by referring to its name. ``` val newId: Int = IdFactory.create() @@ -243,7 +244,7 @@ We will cover objects in depth [later](singleton-objects.md). ## Traits -Traits define specification of types as signature of fields and methods. +Traits are types containing certain fields and methods. Multiple traits can be combined. You can define traits with `trait` keyword. @@ -257,11 +258,12 @@ Traits can also have default implementations. ``` trait Greeter { - def greet(name: String): Unit = println("Hello, " + name + "!") + def greet(name: String): Unit = + println("Hello, " + name + "!") } ``` -You can extend traits with the `extends` keyword and override their implementations with the `override` keyword. +You can extend traits with the `extends` keyword and override an implementation with the `override` keyword. ``` class DefaultGreeter extends Greeter @@ -279,16 +281,21 @@ val customGreeter = new CustomizableGreeter("How are you, ", "?") customGreeter.greet("Scala developer") // How are you, Scala developer? ``` +Here, `DefaultGreeter` extends only a single trait, but it could extend multiple traits. + We will cover traits in depth [later](traits.md). ## Main Method -Main method is an entry point of a program. +The main method is an entry point of a program. The Java Virtual +Machine requires a main method to be named `main` and take one +argument, an array of strings. -Using objects, you can define main methods like below. +Using an object, you can define a main method as follows: ``` object Main { - def main(args: Array[String]): Unit = println("Hello, Scala developer!") + def main(args: Array[String]): Unit = + println("Hello, Scala developer!") } ``` From 73d1b820695b5be9f08e28fa2c903f96803b95db Mon Sep 17 00:00:00 2001 From: Seth Tisue Date: Tue, 7 Feb 2017 15:18:09 -0800 Subject: [PATCH 2/3] use 'tut' to check code blocks including using tut:nofail for blocks with some correct, some incorrect entries. the "nofail" name is confusing, but it does what we need. it is deprecated at present, but may be un-deprecated in the future, so it's provisionally ok for us to use. for details, see https://github.com/tpolecat/tut/issues/141 --- .gitignore | 2 ++ tutorials/tour/basics.md | 52 ++++++++++++++++++++-------------------- 2 files changed, 28 insertions(+), 26 deletions(-) diff --git a/.gitignore b/.gitignore index b13c80e619..22a496be82 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ _site *~ vendor/bundle .idea/ +/coursier +/tut-tmp/ diff --git a/tutorials/tour/basics.md b/tutorials/tour/basics.md index a674f474ab..c55784eb08 100644 --- a/tutorials/tour/basics.md +++ b/tutorials/tour/basics.md @@ -28,7 +28,7 @@ Expressions are computable statements. You can output results of expressions using `println`. -``` +```tut println(1) // 1 println(1 + 1) // 2 println("Hello!") // Hello! @@ -39,7 +39,7 @@ println("Hello," + " world!") // Hello, world! You can name results of expressions with the `val` keyword. -``` +```tut val x = 1 + 1 println(x * x) // 4 ``` @@ -49,14 +49,14 @@ a value does not re-compute it. Values cannot be re-assigned. -``` +```tut:nofail val x = 1 + 1 x = 3 // This does not compile. ``` Types of values can be inferred, but you can also explicitly state the type, like this: -``` +```tut val x: Int = 1 + 1 ``` @@ -64,7 +64,7 @@ val x: Int = 1 + 1 Variables are like values, except you can re-assign them. You can define a variable with the `var` keyword. -``` +```tut var x = 1 + 1 x = 3 // This compiles because "x" is declared with the "var" keyword. println(x * x) // 9 @@ -72,7 +72,7 @@ println(x * x) // 9 As with values, you can explicitly state the type if you want: -``` +```tut var x: Int = 1 + 1 ``` @@ -82,7 +82,7 @@ You can combine expressions by surrounding them with `{}`. We call this a block. The result of the last expression in the block is the result of the overall block, too. -``` +```tut println({ val x = 1 + 1 x + 1 @@ -95,7 +95,7 @@ Functions are expressions that take parameters and compute a result. You can define a function that returns a given integer plus one: -``` +```tut (x: Int) => x + 1 ``` @@ -103,21 +103,21 @@ On the left of `=>` is a list of parameters. On the right is an expression invol You can also name functions. -``` +```tut val addOne = (x: Int) => x + 1 println(addOne(1)) // 2 ``` Functions may take multiple parameters. -``` +```tut val add = (x: Int, y: Int) => x + y println(add(1, 2)) // 3 ``` Or it can take no parameters. -``` +```tut val getTheAnswer = () => 42 println(getTheAnswer()) // 42 ``` @@ -130,14 +130,14 @@ Methods look and behave very similar to functions, but there are a few key diffe Methods are defined with the `def` keyword. `def` is followed by a name, parameter lists, a return type, and a body. -``` +```tut def add(x: Int, y: Int): Int = x + y println(add(1, 2)) // 3 ``` Methods cannot be named with the `val` or `var` keywords. -``` +```tut:nofail def add(x: Int, y: Int): Int = x + y val add2 = add // This does not compile. var add3 = add // This does not compile either. @@ -145,14 +145,14 @@ var add3 = add // This does not compile either. Methods can take multiple parameter lists. -``` +```tut def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier println(addThenMultiply(1, 2)(3)) // 9 ``` Or no parameter lists at all. -``` +```tut def name: String = System.getProperty("name") println("Hello, " + name + "!") ``` @@ -163,7 +163,7 @@ There are some other differences, but for now, you can think of them as somethin You can define classes with the `class` keyword followed by its name and constructor parameters. -``` +```tut class Greeter(prefix: String, suffix: String) { def greet(name: String): Unit = println(prefix + name + suffix) @@ -172,7 +172,7 @@ class Greeter(prefix: String, suffix: String) { You can make an instance of a class with the `new` keyword. -``` +```tut val greeter = new Greeter("Hello, ", "!") greeter.greet("Scala developer") // Hello, Scala developer! ``` @@ -183,13 +183,13 @@ We will cover classes in depth [later](classes.md). Scala has a special type of class called a "case" class. By default, case classes are immutable and compared by value. You can define case classes with the `case class` keywords. -``` +```tut case class Point(x: Int, y: Int) ``` You can instantiate case classes without `new` keyword. -``` +```tut val point = Point(1, 2) val anotherPoint = Point(1, 2) val yetAnotherPoint = Point(2, 2) @@ -197,7 +197,7 @@ val yetAnotherPoint = Point(2, 2) And they are compared by value. -``` +```tut if (point == anotherPoint) { println(point + " and " + anotherPoint + " are the same.") } else { @@ -221,7 +221,7 @@ Objects are single instances of their own definitions. You can think of them as You can define objects with the `object` keyword. -``` +```tut object IdFactory { private var counter = 0 def create(): Int = { @@ -233,7 +233,7 @@ object IdFactory { You can access an object by referring to its name. -``` +```tut val newId: Int = IdFactory.create() println(newId) // 1 val newerId: Int = IdFactory.create() @@ -248,7 +248,7 @@ Traits are types containing certain fields and methods. Multiple traits can be You can define traits with `trait` keyword. -``` +```tut trait Greeter { def greet(name: String): Unit } @@ -256,7 +256,7 @@ trait Greeter { Traits can also have default implementations. -``` +```tut trait Greeter { def greet(name: String): Unit = println("Hello, " + name + "!") @@ -265,7 +265,7 @@ trait Greeter { You can extend traits with the `extends` keyword and override an implementation with the `override` keyword. -``` +```tut class DefaultGreeter extends Greeter class CustomizableGreeter(prefix: String, postfix: String) extends Greeter { @@ -293,7 +293,7 @@ argument, an array of strings. Using an object, you can define a main method as follows: -``` +```tut object Main { def main(args: Array[String]): Unit = println("Hello, Scala developer!") From 753b3ef64ed754e7daaaca32b748343e793d6ed0 Mon Sep 17 00:00:00 2001 From: Seth Tisue Date: Thu, 9 Feb 2017 09:41:18 -0800 Subject: [PATCH 3/3] respond to review feedback --- tutorials/tour/basics.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tutorials/tour/basics.md b/tutorials/tour/basics.md index c55784eb08..1afe78d1cf 100644 --- a/tutorials/tour/basics.md +++ b/tutorials/tour/basics.md @@ -14,9 +14,9 @@ In this page, we will cover basics of Scala. ## Trying Scala in the Browser -You can run Scala in your browser with [ScalaFiddle](https://scalafiddle.io). +You can run Scala in your browser with ScalaFiddle. -1. Go to https://scalafiddle.io. +1. Go to [https://scalafiddle.io](https://scalafiddle.io). 2. Paste `println("Hello, world!")` in the left pane. 3. Hit "Run" button. Output appears in the right pane. @@ -41,7 +41,7 @@ You can name results of expressions with the `val` keyword. ```tut val x = 1 + 1 -println(x * x) // 4 +println(x) // 2 ``` Named results, such as `x` here, are called values. Referencing @@ -91,7 +91,7 @@ println({ ## Functions -Functions are expressions that take parameters and compute a result. +Functions are expressions that take parameters. You can define a function that returns a given integer plus one: