Skip to content
Browse files

[scalac-plugin] Documentation

  • Loading branch information
cchantep committed Feb 24, 2014
1 parent bce2867 commit 9b813586190f6e5f8e7c3fdcde642bcc2234e1a4
Showing with 57 additions and 14 deletions.
  1. +57 −14 scalac-plugin/
@@ -1,10 +1,24 @@
# Acolyte Scalac plugin

Scala compiler plugin

## Match component

Scala pattern matching: case class | extractor
Extract created with arg -> Stable identifier (ex regexp)
-> ~(extractorFactory[, bindings])
Scala pattern matching involves use of either case class or extractor.

When extractor needs parameters to be created, it should be declared as stable identifier before `match` block. e.g. With regular expression matching:

val Letter = "[a-zA-Z]+".r
"String" match {
case Letter true

Match component included in this plugin provides syntax `~(extractorFactory[, bindings])` for rich pattern matching.

Consider following extractor, instantiated with one parameter:

case class Regex(e: String) {
@@ -13,35 +27,54 @@ case class Regex(e: String) {

Then provided rich syntax can be used as following:

str match {
case ~(Regex("^a.*")) 1
case ~(Regex("# ([A-Z]+).*"), a) 2
case ~(Regex("^a.*")) 1 // no binding
case ~(Regex("# ([A-Z]+).*"), a) 2
// if str == "# BCD123", then a = "BCD"
case ~(Regex("([0-9]+);([a-z]+)"), (a, b)) 3
// if str == "234;xyz", then a = "234" and b = "xyz"
case _ 4

It will be refactored by plugin, so that required stable identifiers will be available for matching:

val Xtr1 = Regex("^a.*")
// ...
str match {
case Xtr1 1 // no binding
// ...

## Usage

This plugin is currently published as `1.0.14-SNAPSHOT` on repository ``.

> If you have another `~` symbol, it will have to be renamed at `import pkg.{ ~ ⇒ renamed }`.
## SBT usage
### SBT usage
Scalac plugin can be used with SBT project, using its [compiler plugins support](

autoCompilerPlugins := true
addCompilerPlugin("" %% "scalac-plugin" % "VERSION")
scalacOptions += "-P:acolyte:debug"
scalacOptions += "-P:acolyte:debug" // Optional

## Maven usage
### Maven usage
Maven scala plugin [supports compiler plugin](, so you can do:

@@ -75,17 +108,27 @@

## Plugin options

There is few option for this plugin.

- `-P:acolyte:debug`: Display debug while compiling with (e.g. refactored match code).

## Compilation errors

As match component refactors `match` AST when `~(…, …)` is used, then if there is compilation error around that location will be mentioned as `/path/to/file.scala#refactored-match-M` (with `M` informational index of refactored match).

If there is an error with given extractor factory, you will get something like:

[error] /path/to/file.scala#refactored-match-M:1: Compilation error.
[error] Error details.
[error] val Xtr1 = B() // generated from ln L, col C

Comment `// generated from ln L, col C` indicates location in original code, before it gets refactored.

If there result from given extractor factory is not a valid extract, it will raise:

[error] /path/to/file.scala#refactored-match-M:1: value Xtr0 is not a case class constructor, nor does it have an unapply/unapplySeq method
[error] case Xtr1((a @ _)) => Nil // generated from ln L, col C

0 comments on commit 9b81358

Please sign in to comment.
You can’t perform that action at this time.