resolvers ++= Seq(
"Sonatype OSS Releases" at "http://oss.sonatype.org/content/repositories/releases/",
"Sonatype OSS Snapshots" at "http://oss.sonatype.org/content/repositories/snapshots/"
)
val scalaVersion = "2.11.1" // or "2.10.4"
val libraryVersion = "0.4.0" // or "0.5-SNAPSHOT"
libraryDependencies ++= Seq(
"com.github.julien-truffaut" %% "monocle-core" % libraryVersion,
"com.github.julien-truffaut" %% "monocle-generic" % libraryVersion,
"com.github.julien-truffaut" %% "monocle-macro" % libraryVersion, // since 0.4.0
"com.github.julien-truffaut" %% "monocle-law" % libraryVersion % test // since 0.4.0
)Monocle is a Lens library, or more generally an Optics library where Optics gather the concepts
of Lens, Traversal, Optional, Prism and Iso. Monocle is strongly inspired by Haskell Lens.
Optics are a set of purely functional abstractions to manipulate (get, set, modify) immutable objects. Optics compose between each other and particularly shine with nested objects.
Scala already provides getters and setters for case classes but modifying nested object is verbose which makes code difficult to understand and reason about. Let's have a look at some examples:
case class Street(name: String, ...) // ... means it contains other fields
case class Address(street: Street, ...)
case class Company(address: Address, ...)
case class Employee(company: Company, ...)Let's say we have an employee and we need to set the first character of his company street name address in upper case. Here is how we could write it in vanilla Scala:
val employee: Employee = ...
employee.copy(
company = employee.company.copy(
address = employee.company.address.copy(
name = employee.company.address.name.capitalize // luckily capitalize exists
)
)
)As you can see copy is not convenient to update nested objects as we need to repeat at each level the full path to reach it. Let's see what could we do with Monocle:
val _name : SimpleLens[Street , String] = ... // we'll see later how to build Lens
val _street : SimpleLens[Address , Street] = ...
val _address: SimpleLens[Company , Address] = ...
val _company: SimpleLens[Employee, Company] = ...
import monocle.syntax._
employee applyLens _company
composeLens _address
composeLens _street
composeLens _name
modify (_.capitalize)or with some syntax sugar:
employee |-> _company |-> _address |-> _street |-> _name modify (_.capitalize)ComposeLens takes two Lens, one from A to B and another from B to C and creates a third Lens from A to C.
Therefore, after composing _company, _address, _street and _name, we obtain a Lens from Employee to String (the street name).
In the above example, we used capitalize to upper case the first letter of a String.
It works but it would be clearer if we could use Lens to zoom into the first character of a String.
However, we cannot write such a Lens because a Lens defines how to focus from an object S into a mandatory
object A and in our case, the first character of a String is optional as a String might be empty. For this
we need a sort of partial Lens, in Monocle it is called Optional.
import monocle.syntax._
import monocle.function.HeadOption._ // to use headOption
employee applyLens _company
composeLens _address
composeLens _street
composeLens _name
composeOptional headOption // generic Optional that focus into the first element
modify toUpperor with some syntax sugar:
employee |-> _company |-> _address |-> _street |-> _name |-? headOption modify toUpperSimilarly to composeLens, composeOptional takes two Optional, one from A to B and another from B to C and
creates a third Optional from A to C. All Lens can be seen as Optional where the optional element to zoom to is always
present, hence composing an Optional and a Lens always produces an Optional (see class diagram for full inheritance
relation between Optics).
For more examples, see the example module.
Lens can be created by a pair of getter and setter:
val _company = SimpleLens[Employee, Company](_.company, (e, c) => e.copy(company = c))This is quite a lot of boiler plate, so Monocle provides a macro to simplify Lens creation:
import monocle.Macro._ // require monocle-macro dependency
val _company = mkLens[Employee, Company]("company") // company is checked at compiled time to be a valid accessorIn future version of the library, we are planning to introduce helpers to facilitate even further Lens creation.
Core contains the main library concepts: Lens, Traversal, Prism, Iso, Getter and Setter. Core only depends on scalaz for type classes.
Law defines Iso, Lens, Prism, Setter and Traversal laws using scalacheck.
Macro defines a macro to reduce Lens creation boiler plate.
Generic is an experiment to provide highly generalised Lens and Iso using HList from shapeless. Generic focus is on neat abstraction but that may come at additional runtime or compile time cost.
Example shows how other sub projects can be used.
We are happy to have as many people as possible contributing to Monocle. Therefore, we made this small workflow to simplify the process:
- Select or create an issue (issues tagged with label "padawan-friendly" are designed for Scala novice)
- Comment on the issue letting everyone knows that you are working on it.
- Fork Monocle
- Work on your fork until you are satisfied (label your commits with issue number)
- Submit a pull request
- We will review your pull request and merge it back to master
If you have any questions, we have irc channel on freenode #scala-monocle and a mailing group
Thank you for you contribution!
Julien Truffaut - @JulienTruffaut
Ross Huggett - ross.huggett@gmail.com / @rosshuggett
Ilan Godik - ilan3580@gmail.com / NightRa


