Repository files navigation

Dsl.scala is a framework to create embeddedDomain-SpecificLanguages 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 theDsl trait, which contains only one abstract method to be implemented. No knowledge about Scala compiler or AST macros is required.

DSLs written inDsl.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:

• TheAwait keyword for creating memoized asynchronous values as ScalaFutures, similar to theawait /async keywords in C#, Python and JavaScript.
• TheShift keyword for creating asynchronous tasks as delimited continuations, similar to theshift operator inScala Continuations.
• TheAsynchronousIo.Connect,AsynchronousIo.Accept,AsynchronousIo.Read andAsynchronousIo.Write keywords for performing I/O on an asynchronous channel.
• TheYield keyword for generating lazy streams, similar toyield in C#, Python and JavaScript.
• TheFork keyword for duplicating current context, similar to thefork system call in POSIX.
• TheReturn keyword for early returning, similar to the nativereturn keyword in Scala.
• TheUsing keyword to automatically close resources when exiting a scope, similar to the nativeusing keyword in C#.
• TheMonadic keyword for creating Scalaz or Cats monadic control flow, similar to the !-notation in Idris.
• TheNullSafe keyword for the null safe operator, similar to the? operator in Kotlin and Groovy.
• TheNoneSafe keyword for theNone safe operator, similar to theMaybe monad 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 usingEach,Using andShift together.

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 keywordYield.

So, you need to add the library that contains the implementation of the keywordYield:

// Add the "keywords-yield" library in your build.sbt, to use the `Yield` keywordlibraryDependencies+="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"

The random number generator can be implemented as a recursive function that produces the next random number in each iteration.

importcom.thoughtworks.dsl.keywords.Yield// Must not annotated with @tailrecdefxorshiftRandomGenerator(seed:Int):LazyList[Int]= reset {valtmp1= seed^ (seed<<13)valtmp2= tmp1^ (tmp1>>>17)valtmp3= 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:

valmyGenerator= xorshiftRandomGenerator(seed=123)myGenerator(0) should be(31682556)myGenerator(1) should be(-276305998)myGenerator(2) should be(2101636938)

The call toxorshiftRandomGenerator does not throw aStackOverflowError because the execution ofxorshiftRandomGenerator will be paused at the keywordYield, and it will be resumed when the caller is looking for the next number.

• sbt-ammonite-classpath is an sbt plug-in thatusesEach keywords to iterate through configuations and keys, as an alternative syntax offor comprehensions.
• Dsl.scala-akka-actor provides theAkka Actor support for Dsl.scala. It is an alternative toAkka 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)

• Check theDocumentation to find examples about using or creating DSLs.
• SeeMVNRepository orScaladex 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 ourBangNotation compiler plugin is inspired byIdris' !-notation.