JarCastingDsl.scala 
Dsl.scala is a framework to create embedded Domain-Specific Languages in Scala. It can be considered as an alternative syntax to for comprehension, Scala Async and Scala Continuations. It unifies monads, generators, asynchronous functions, coroutines and continuations to a single universal syntax, and can be easily integrate to Scalaz, Cats, Scala Collections, Scala Futures, Akka HTTP, Java NIO, or your custom domains.
A DSL author is able to create language keywords by implementing the Dsl trait, which contains only one abstract method to be implemented. No knowledge about Scala compiler or AST macros is required.
DSLs written in Dsl.scala are collaborative with others DSLs and Scala control flows. A DSL user can create functions that contains interleaved DSLs implemented by different vendors, along with ordinary Scala control flows.
We also provide some built-in keywords, including:
- The
Awaitkeyword for creating memoized asynchronous values as Scala Futures, similar to theawait/asynckeywords in C#, Python and JavaScript. - The
Shiftkeyword for creating asynchronous tasks as delimited continuations, similar to theshiftoperator in Scala Continuations. - The
AsynchronousIo.Connect,AsynchronousIo.Accept,AsynchronousIo.ReadandAsynchronousIo.Writekeywords for performing I/O on an asynchronous channel. - The
Yieldkeyword for generating lazy streams, similar toyieldin C#, Python and JavaScript. - The
Eachkeyword for iterating on a collection, similar to the list comprehension feature in Scala, Haskell, OCaml, Python and Lisp. - The
Continuekeyword LDK for skipping an element in anEachcollection comprehension, similar to the nativecontinuekeyword in C/C++ or themzeroin Haskell. - The
Forkkeyword for duplicating current context, similar to theforksystem call in POSIX. - The
Returnkeyword for early returning, similar to the nativereturnkeyword in Scala. - The
Usingkeyword to automatically close resources when exiting a scope, similar to the nativeusingkeyword in C#. - The
Monadickeyword for creating Scalaz or Cats monadic control flow, similar to the !-notation in Idris. - The
NullSafekeyword for the null safe operator, similar to the?operator in Kotlin and Groovy. - The
NoneSafekeyword for theNonesafe operator, similar to theMaybemonad in Haskell.
All the above keywords can be used together with each others. For example you can perform list comprehension to manipulate native resources in an asynchronous task by using Each, Using and Shift together.
Getting Started
Suppose you want to create a random number generator. The generated numbers should be stored in a lazily evaluated infinite stream, which can be built with the help of our built-in domain-specific keyword Yield.
So, you need to add the library that contains the implementation of the keyword Yield:
// Add the "keywords-yield" library in your build.sbt, to use the `Yield` keyword
libraryDependencies += "com.thoughtworks.dsl" %% "keywords-yield" % "latest.release"
// Add other "keywords-xxx" libraries in your build.sbt, to use other keywords
// libraryDependencies += "com.thoughtworks.dsl" %% "keywords-xxx" % "latest.release"
And the Dsl.scala compiler plug-ins that are shared by all DSLs:
// Add the following settings in your build.sbt
addCompilerPlugin("com.thoughtworks.dsl" %% "compilerplugins-bangnotation" % "latest.release")
addCompilerPlugin("com.thoughtworks.dsl" %% "compilerplugins-reseteverywhere" % "latest.release")
The random number generator can be implemented as a recursive function that produces the next random number in each iteration.
import com.thoughtworks.dsl.keywords.Yield
// Must not annotated with @tailrec
def xorshiftRandomGenerator(seed: Int): scala.collection.immutable.Stream[Int] = {
val tmp1 = seed ^ (seed << 13)
val tmp2 = tmp1 ^ (tmp1 >>> 17)
val tmp3 = tmp2 ^ (tmp2 << 5)
!Yield(tmp3)
xorshiftRandomGenerator(tmp3)
}
Note that a keyword is a plain case class. You need a ! prefix to the keyword to activate the DSL.
It's done. We can test it in ScalaTest:
val myGenerator = xorshiftRandomGenerator(seed = 123)
myGenerator(0) should be(31682556)
myGenerator(1) should be(-276305998)
myGenerator(2) should be(2101636938)
The call to xorshiftRandomGenerator does not throw a StackOverflowError because the execution of xorshiftRandomGenerator will be paused at the keyword Yield, and it will be resumed when the caller is looking for the next number.
Showcases
- sbt-ammonite-classpath is an sbt plug-in that uses
Eachkeywords to iterate through configuations and keys, as an alternative syntax offorcomprehensions. - Dsl.scala-akka-actor provides the Akka Actor support for Dsl.scala. It is an alternative to Akka FSM, for building actors with complex states from simple native Scala control flows.
- Dsl.scala-akka-http contains utilities to integrate Akka HTTP with Dsl.scala.
- dsl-domains-cats contains utilities to integrate Cats with Dsl.scala. It provides the
!-notation for creating Cats monadic expressions.
(Feel free to add your project here)
Links and related works
- Check the Documentation to find examples about using or creating DSLs.
- See MVNRepository or Scaladex for the settings of each built-in DSLs for your build tools.
- Benchmarks: Dsl.scala vs Monix vs Cats Effect vs Scalaz Concurrent vs Scala Async vs Scala Continuation
- Control.Dsl is the Haskell port of this library.
- The syntax of our
BangNotationcompiler plugin is inspired by Idris' !-notation.
