diff --git a/.gitignore b/.gitignore
index 9c07d4a..d323b98 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,266 @@
-*.class
-*.log
+# Created by https://www.gitignore.io/api/osx,vim,code,linux,emacs,windows,eclipse,intellij+all
+
+### Code ###
+# Visual Studio Code - https://code.visualstudio.com/
+.settings/
+.vscode/
+tsconfig.json
+jsconfig.json
+
+### Eclipse ###
+
+.metadata
+bin/
+tmp/
+*.tmp
+*.bak
+*.swp
+*~.nib
+local.properties
+.loadpath
+.recommenders
+
+# External tool builders
+.externalToolBuilders/
+
+# Locally stored "Eclipse launch configurations"
+*.launch
+
+# PyDev specific (Python IDE for Eclipse)
+*.pydevproject
+
+# CDT-specific (C/C++ Development Tooling)
+.cproject
+
+# Java annotation processor (APT)
+.factorypath
+
+# PDT-specific (PHP Development Tools)
+.buildpath
+
+# sbteclipse plugin
+.target
+
+# Tern plugin
+.tern-project
+
+# TeXlipse plugin
+.texlipse
+
+# STS (Spring Tool Suite)
+.springBeans
+
+# Code Recommenders
+.recommenders/
+
+# Scala IDE specific (Scala & Java development for Eclipse)
+.cache-main
+.scala_dependencies
+.worksheet
+
+### Eclipse Patch ###
+# Eclipse Core
+.project
+
+# JDT-specific (Eclipse Java Development Tools)
+.classpath
+
+### Emacs ###
+# -*- mode: gitignore; -*-
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# Org-mode
+.org-id-locations
+*_archive
+
+# flymake-mode
+*_flymake.*
+
+# eshell files
+/eshell/history
+/eshell/lastdir
+
+# elpa packages
+/elpa/
+
+# reftex files
+*.rel
+
+# AUCTeX auto folder
+/auto/
+
+# cask packages
+.cask/
+dist/
+
+# Flycheck
+flycheck_*.el
+
+# server auth directory
+/server/
+
+# projectiles files
+.projectile
+projectile-bookmarks.eld
+
+# directory configuration
+.dir-locals.el
+
+# saveplace
+places
+
+# url cache
+url/cache/
+
+# cedet
+ede-projects.el
+
+# smex
+smex-items
+
+# company-statistics
+company-statistics-cache.el
+
+# anaconda-mode
+anaconda-mode/
+
+### Intellij+all ###
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff:
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/dictionaries
+
+# Sensitive or high-churn files:
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.xml
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+
+# Gradle:
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# CMake
+cmake-build-debug/
+
+# Mongo Explorer plugin:
+.idea/**/mongoSettings.xml
+
+## File-based project format:
+*.iws
+
+## Plugin-specific files:
+
+# IntelliJ
+/out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+### Intellij+all Patch ###
+# Ignores the whole idea folder
+# See https://github.com/joeblau/gitignore.io/issues/186 and https://github.com/joeblau/gitignore.io/issues/360
+
+.idea/
+
+### Linux ###
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### OSX ###
+*.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### Vim ###
+# swap
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-v][a-z]
+[._]sw[a-p]
+# session
+Session.vim
+# temporary
+.netrwhist
+# auto-generated tag files
+tags
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+ehthumbs.db
+ehthumbs_vista.db
+
+# Folder config file
+Desktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# End of https://www.gitignore.io/api/osx,vim,code,linux,emacs,windows,eclipse,intellij+all
diff --git a/exercises/intro/.gitignore b/exercises/intro/.gitignore
new file mode 100644
index 0000000..fecd5e1
--- /dev/null
+++ b/exercises/intro/.gitignore
@@ -0,0 +1,43 @@
+# Created by https://www.gitignore.io/api/sbt,java,scala
+
+### Java ###
+# Compiled class file
+*.class
+
+# Log file
+*.log
+
+# BlueJ files
+*.ctxt
+
+# Mobile Tools for Java (J2ME)
+.mtj.tmp/
+
+# Package Files #
+*.jar
+*.war
+*.ear
+*.zip
+*.tar.gz
+*.rar
+
+# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
+hs_err_pid*
+
+### SBT ###
+# Simple Build Tool
+# http://www.scala-sbt.org/release/docs/Getting-Started/Directories.html#configuring-version-control
+
+dist/*
+target/
+lib_managed/
+src_managed/
+project/boot/
+project/plugins/project/
+.history
+.cache
+.lib/
+
+### Scala ###
+
+# End of https://www.gitignore.io/api/sbt,java,scala
diff --git a/intro/README.md b/exercises/intro/README.md
similarity index 75%
rename from intro/README.md
rename to exercises/intro/README.md
index 8946ca6..095e8d0 100644
--- a/intro/README.md
+++ b/exercises/intro/README.md
@@ -1,17 +1,21 @@
-Introduction to Functional Programming in Scala
+Introduction to Functional Programming (FP) in Scala
============
In this tutorial we will start with a trivial program, written in imperative
style, and through a series of refactorings transform it into a functional
-program while learning the core FP concepts like referential transparency,
-expression-based programming, recursion, immutability and higher-order
-functions.
+program while learning core FP concepts such as:
+
+- referential transparency,
+- expression-based programming,
+- recursion,
+- immutability, and
+- higher-order functions.
Getting Started
--------
+---------------
-Open file `src/main/scala/Main.scala` in your editor of choice. To run the
-program start `sbt` from the terminal and type `run` in SBT prompt.
+Open file `src/main/scala/Main.scala` in your editor of choice.
+To run the program start `sbt` from the terminal and type `run` in SBT prompt.
The Challenge
-------------
@@ -31,7 +35,7 @@ The "Real" Program
------------------
We'll start with almost a schoolbook solution in Java that will have loops,
-conditionals and variables. This first example is in Java instead of Scala
+conditionals, and variables. This first example is in Java instead of Scala
so that it's immediately familiar to anyone who did some programming in
procedural imperative language before:
@@ -50,15 +54,18 @@ public class Loop {
}
```
-This program is on purpose easy enough to understand. Consider however that
-in your real programming work you would iterate over some complex domain
-objects instead on numbers, maybe over two or three arrays of those
-simultaneously, there would be many more conditions and they would be nested,
-there would be multiple variables to keep track of running totals and they
-would all change independently of each other based on complex conditional
-logic. And what about running this loop on multiple CPU cores in parallel so
-that it can finish faster? You see how a simple `for` loop with a variable can
-quickly get out of hand?
+> Source: [Loop1.java]
+
+This program is, on purpose, easy enough to understand. Consider however, that
+in your real programming work you might deal with several complexities at the same
+time and thus a simple `for` loop with a variable can quickly get out of hand:
+
+- iterating over some complex domain objects instead on numbers,
+- iterating over two or three arrays of those domain objects simultaneously,
+- multiple and / or nested conditions,
+- multiple variables to keep track of running totals,
+- multiple variables that all change independently based on complex conditional logic, and
+- parallel loop execution (i.e. utilising multiple CPU cores).
Two cornerstones of imperative programming languages contribute to the
problem here:
@@ -98,6 +105,8 @@ object Main extends App { // 1.
}
```
+> Source: [Loop2.scala]
+
First you notice that Scala is less verbose: no semicolons needed, no `public
static void main`, no explicit reassignment of `x` in `for` loop. Here are
other notable differences:
@@ -129,6 +138,27 @@ for (x <- 1 to 10) { // iterate
There are 4 distinct functions that are entangled in this statement-based
program. No single function can be tested in isolation. Let's pull them apart:
+```scala
+def iterate(max: Int): List[Int] = ???
+def filterEven(xs: List[Int]): List[Int] = ???
+def square(xs: List[Int]): List[Int] = ???
+def sum(xs: List[Int]): Int = ???
+
+val result = sum(square(filterEven(iterate(10))))
+```
+
+Let's review the function and variable assignment Scala syntax first:
+
+1. `def f(x: Int): List[Int]` defines function `f` that takes an
+argument `x` of type `Int` and returns a `List` of `Int`s;
+2. `???` is a way to define a method stub (like a TODO),
+which will allow the program to compile but throws `NotImplementedError`
+when the function is called;
+3. `val x = ...` defines an immutable value, once assigned the value
+cannot be changed (unlike a `var`).
+
+So how would the function implementation look?
+
```scala
def iterate(max: Int): List[Int] = {
var result = List[Int]()
@@ -170,15 +200,15 @@ def sum(xs: List[Int]): Int = {
val result = sum(square(filterEven(iterate(10))))
```
+> Source: [Loop3.scala]
+
Wow! The number of lines of code just exploded and we introduced a lot of
-duplication along the way. Let's review new Scala syntax first:
+duplication along the way. Let's review the function body implementation:
-1. `def f(x: Int): List[Int] = {...}` defines function `f` that takes an
-argument `x` of type `Int` and returns a `List` of `Int`s;
-2. The last expression of a function body is its return value;
-3. `List[Int]()` creates an empty list of integers;
-4. `list :+ element` returns a new list made of appending `element` to `list`;
-5. `val x = ...` defines an immutable value that cannot be changed.
+1. The last expression of a function body is its return value;
+2. `List[Int]()` creates an empty list of integers, one alternative is to use
+the equivalent factory method `List.empty[Int]` (a matter of preference);
+3. `list :+ element` returns a new list made of appending `element` to `list`;
Despite explosion of code and duplication we've made our program
composable: every function can be tested in isolation and functions can be
@@ -190,15 +220,18 @@ universal building blocks.
Consider the expression `sum(square(filterEven(iterate(10))))`. Unlike a
program made of statements, every sub-expression is an expression on its own:
- `10` is an expression which evaluates to 10, `iterate(10)` is an expression
-which evaluates to `List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)`, `filterEven
-(iterate(10))` is an expression which evaluates to `List(2, 4, 6, 8, 10)`
-and so on. Every expression can be replaced with the value it evaluates to as
+
+- `10` is an expression which evaluates to 10,
+- `iterate(10)` is an expression which evaluates to `List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)`,
+- `filterEven (iterate(10))` is an expression which evaluates to `List(2, 4, 6, 8, 10)`,
+- and so on.
+
+Every expression can be replaced with the value it evaluates to as
long as functions involved in the expression don't have side effects – e.g.
launch the proverbial missiles or modify variables in other parts of the
program. In functional programming such functions are called *pure* and the
property allowing substitution of values for expressions is called
-*referential transparency* meaning that referring to a value via an
+*referential transparency*, meaning that referring to a value via an
indirection of a function call is transparent and doesn't change program
execution.
@@ -256,7 +289,7 @@ recursion though;
3. We use *pattern matching* to match on integer `max`. It looks like `switch`
statement in other programming languages, but is an expression instead of a
statement because every `case` branch has to evaluate to the same type;
-4. `case _` matches any value;
+4. `case _` matches any value (i.e. catchall);
5. `element :: list` creates a new list with `element` prepended to `list`;
6. `Nil` is an empty list.
@@ -309,6 +342,9 @@ def sum(xs: List[Int]): Int = {
}
```
+> Source: [Loop4.scala]
+> Diff: [Loop3.scala => Loop4.scala]
+
Here we pattern match on a list instead of integer. Note how we used the same
list construction syntax in the `case` expression to capture list's head `x`
and its `tail`. `++` concatenates two lists.
@@ -355,6 +391,9 @@ def square(xs: List[Int]): List[Int] =
flatMap(xs, x => List(x * x))
```
+> Source: [Loop5.scala]
+> Diff: [Loop4.scala => Loop5.scala]
+
1. `flatMap` takes function `f` as its second argument;
2. `A => B` is type annotation for a function that takes an argument of type
`A` and returns a value of type `B`;
@@ -404,6 +443,9 @@ def sum(xs: List[Int]): Int =
foldLeft(xs)(0)((acc, x) => acc + x)
```
+> Source: [Loop6.scala]
+> Diff: [Loop5.scala => Loop6.scala]
+
1. `foldLeft[A, R]` is parametrized on type of the input list `A` as well as
the type of its return value `R` thus `foldLeft` is a *generic* function;
2. Scala functions can have multiple parameter lists. Here it's useful for
@@ -443,18 +485,21 @@ def isEven(x: Int): Boolean = x % 2 == 0
def square(x: Int): Int = x * x
def sumOfEvenSquares(max: Int): Int = {
- sum(map(filter(iterate(10))(isEven))(square))
+ sum(map(filter(iterate(max))(isEven))(square))
}
```
-Here `square` really does only what it says and doesn't mess with lists
-anymore, that's responsibility of `map` now.
+> Source: [Loop7.scala]
+> Diff: [Loop6.scala => Loop7.scala]
+
+Here, `square` really does only what it says and doesn't mess with lists
+anymore, which is now the responsibility of `map`.
Collection API
--------------
-By a lucky coincidence Scala standard library collection API already provides
-most of the functions that we've just discovered. It would be a shame not to
+"By a lucky coincidence", Scala standard library collection API already provides
+most of the functions that we've just discovered. It would be a shame not to
use them:
```scala
@@ -463,13 +508,16 @@ def isEven(x: Int): Boolean = x % 2 == 0
def square(x: Int): Int = x * x
def sumOfEvenSquares(max: Int): Int = {
- (1 to 10)
+ (1 to max)
.filter(isEven)
.map(square)
.sum
}
```
+> Source: [Loop8.scala]
+> Diff: [Loop7.scala => Loop8.scala]
+
We use `1 to 10` directly instead of our own `iterate` function. `filter`,
`map`, `sum` as well as `flatMap`, `foldLeft` and many more functions are
available as methods on any Scala collection. This allows using the fluid API
@@ -484,3 +532,18 @@ readable and easy to maintain and change because it doesn't contain any
mutable variables and imperative statements. It's very modular – we can
change the order of operations in predictable ways and we can add more
transformations without changing the existing ones.
+
+
+[Loop1.java]: https://github.com/SingaporeScalaProgrammers/scala-workshop/blob/master/references/intro/src/main/java/Loop1.java
+[Loop2.scala]: https://github.com/SingaporeScalaProgrammers/scala-workshop/blob/master/references/intro/src/main/scala/Loop2.scala
+[Loop3.scala]: https://github.com/SingaporeScalaProgrammers/scala-workshop/blob/master/references/intro/src/main/scala/Loop3.scala
+[Loop3.scala => Loop4.scala]: https://rawgit.com/SingaporeScalaProgrammers/scala-workshop/master/references/intro/diff/Loop3-Loop4.html
+[Loop4.scala]: https://github.com/SingaporeScalaProgrammers/scala-workshop/blob/master/references/intro/src/main/scala/Loop4.scala
+[Loop4.scala => Loop5.scala]: https://rawgit.com/SingaporeScalaProgrammers/scala-workshop/master/references/intro/diff/Loop4-Loop5.html
+[Loop5.scala]: https://github.com/SingaporeScalaProgrammers/scala-workshop/blob/master/references/intro/src/main/scala/Loop5.scala
+[Loop5.scala => Loop6.scala]: https://rawgit.com/SingaporeScalaProgrammers/scala-workshop/master/references/intro/diff/Loop5-Loop6.html
+[Loop6.scala]: https://github.com/SingaporeScalaProgrammers/scala-workshop/blob/master/references/intro/src/main/scala/Loop6.scala
+[Loop6.scala => Loop7.scala]: https://rawgit.com/SingaporeScalaProgrammers/scala-workshop/master/references/intro/diff/Loop6-Loop7.html
+[Loop7.scala]: https://github.com/SingaporeScalaProgrammers/scala-workshop/blob/master/references/intro/src/main/scala/Loop7.scala
+[Loop7.scala => Loop8.scala]: https://rawgit.com/SingaporeScalaProgrammers/scala-workshop/master/references/intro/diff/Loop7-Loop8.html
+[Loop8.scala]: https://github.com/SingaporeScalaProgrammers/scala-workshop/blob/master/references/intro/src/main/scala/Loop8.scala
diff --git a/intro/build.sbt b/exercises/intro/build.sbt
similarity index 100%
rename from intro/build.sbt
rename to exercises/intro/build.sbt
diff --git a/intro/project/build.properties b/exercises/intro/project/build.properties
similarity index 100%
rename from intro/project/build.properties
rename to exercises/intro/project/build.properties
diff --git a/intro/src/main/scala/Main.scala b/exercises/intro/src/main/scala/Main.scala
similarity index 99%
rename from intro/src/main/scala/Main.scala
rename to exercises/intro/src/main/scala/Main.scala
index e729297..ece9140 100644
--- a/intro/src/main/scala/Main.scala
+++ b/exercises/intro/src/main/scala/Main.scala
@@ -7,4 +7,5 @@ object Main extends App {
}
println(s"Sum of even numbers from 1 to 10 is $sum")
+
}
diff --git a/intro/.gitignore b/intro/.gitignore
deleted file mode 100644
index 07827cc..0000000
--- a/intro/.gitignore
+++ /dev/null
@@ -1,2 +0,0 @@
-target/
-.idea/
\ No newline at end of file
diff --git a/references/intro/.gitignore b/references/intro/.gitignore
new file mode 100644
index 0000000..fecd5e1
--- /dev/null
+++ b/references/intro/.gitignore
@@ -0,0 +1,43 @@
+# Created by https://www.gitignore.io/api/sbt,java,scala
+
+### Java ###
+# Compiled class file
+*.class
+
+# Log file
+*.log
+
+# BlueJ files
+*.ctxt
+
+# Mobile Tools for Java (J2ME)
+.mtj.tmp/
+
+# Package Files #
+*.jar
+*.war
+*.ear
+*.zip
+*.tar.gz
+*.rar
+
+# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
+hs_err_pid*
+
+### SBT ###
+# Simple Build Tool
+# http://www.scala-sbt.org/release/docs/Getting-Started/Directories.html#configuring-version-control
+
+dist/*
+target/
+lib_managed/
+src_managed/
+project/boot/
+project/plugins/project/
+.history
+.cache
+.lib/
+
+### Scala ###
+
+# End of https://www.gitignore.io/api/sbt,java,scala
diff --git a/references/intro/build.sbt b/references/intro/build.sbt
new file mode 100644
index 0000000..9631802
--- /dev/null
+++ b/references/intro/build.sbt
@@ -0,0 +1,5 @@
+name := "intro"
+
+version := "1.0"
+
+scalaVersion := "2.12.3"
diff --git a/references/intro/diff/Loop3-Loop4.html b/references/intro/diff/Loop3-Loop4.html
new file mode 100644
index 0000000..82ecaee
--- /dev/null
+++ b/references/intro/diff/Loop3-Loop4.html
@@ -0,0 +1,260 @@
+
+
+