Permalink
Browse files

[scalac-plugin] Documentation

  • Loading branch information...
cchantep
cchantep committed Feb 24, 2014
1 parent bce2867 commit 9b813586190f6e5f8e7c3fdcde642bcc2234e1a4
Showing with 57 additions and 14 deletions.
  1. +57 −14 scalac-plugin/readme.md
View
@@ -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:
```scala
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:
```scala
case class Regex(e: String) {
@@ -13,35 +27,54 @@ case class Regex(e: String) {
}
```
Then provided rich syntax can be used as following:
```scala
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:
```scala
val Xtr1 = Regex("^a.*")
// ...
str match {
case Xtr1 1 // no binding
// ...
}
```
## Usage
1.0.14-SNAPSHOT
https://raw.github.com/applicius/mvn-repo/master/snapshots/
This plugin is currently published as `1.0.14-SNAPSHOT` on repository `https://raw.github.com/applicius/mvn-repo/master/snapshots/`.
> If you have another `~` symbol, it will have to be renamed at `import pkg.{ ~ ⇒ renamed }`.
## SBT usage
### SBT usage
http://www.scala-sbt.org/0.12.3/docs/Detailed-Topics/Compiler-Plugins.html
Scalac plugin can be used with SBT project, using its [compiler plugins support](http://www.scala-sbt.org/0.12.3/docs/Detailed-Topics/Compiler-Plugins.html):
```scala
autoCompilerPlugins := true
addCompilerPlugin("org.eu.acolyte" %% "scalac-plugin" % "VERSION")
scalacOptions += "-P:acolyte:debug"
scalacOptions += "-P:acolyte:debug" // Optional
```
## Maven usage
### Maven usage
http://scala-tools.org/mvnsites/maven-scala-plugin/example_scalac_plugins.html
Maven scala plugin [supports compiler plugin](http://scala-tools.org/mvnsites/maven-scala-plugin/example_scalac_plugins.html), so you can do:
```xml
<project>
@@ -75,17 +108,27 @@ http://scala-tools.org/mvnsites/maven-scala-plugin/example_scalac_plugins.html
## Plugin options
-P:acolyte:debug
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.