Add sbt command generateDocumentation to update the tree documentation

.github/workflows/ci.yml

@@ -15,10 +15,10 @@ jobs:
       with:
         submodules: 'true'
 
-    - name: Set up JDK 1.8
+    - name: Set up JDK 11
       uses: actions/setup-java@v1
       with:
-        java-version: 1.8
+        java-version: 11
 
     - name: Install Chez Scheme
       run: sudo apt-get install chezscheme

.github/workflows/deploy.yml

@@ -15,10 +15,10 @@ jobs:
       with:
         submodules: 'true'
 
-    - name: Set up JDK 1.8
+    - name: Set up JDK 11
       uses: actions/setup-java@v1
       with:
-        java-version: 1.8
+        java-version: 11
 
     - name: Set up NodeJS
       uses: actions/setup-node@v1

README.md

@@ -13,7 +13,7 @@ play with it and give us your feedback :)
 
 ## Installation
 
-You need to have Java (>= 1.8) and Node (>= 10) and npm installed.
+You need to have Java (>= 11) and Node (>= 10) and npm installed.
 
 The recommended way of installing Effekt is by running:
 

build.sbt

@@ -8,6 +8,7 @@ lazy val generateLicenses = taskKey[Unit]("Analyses dependencies and downloads a
 lazy val updateVersions = taskKey[Unit]("Update version in package.json and pom.xml")
 lazy val install = taskKey[Unit]("Installs the current version locally")
 lazy val assembleBinary = taskKey[Unit]("Assembles the effekt binary in bin/effekt")
+lazy val generateDocumentation = taskKey[Unit]("Generates some documentation.")
 
 
 lazy val effektVersion = "0.2.0"
@@ -66,8 +67,6 @@ lazy val root = project.in(file("effekt"))
     Compile / run := (effekt.jvm / Compile / run).evaluated
   ))
 
-
-
 lazy val effekt: CrossProject = crossProject(JSPlatform, JVMPlatform).in(file("effekt"))
   .settings(
     name := "effekt",
@@ -155,8 +154,9 @@ lazy val effekt: CrossProject = crossProject(JSPlatform, JVMPlatform).in(file("e
       Process(s"${npm.value} version ${effektVersion} --no-git-tag-version --allow-same-version").!!
       Process(s"${mvn.value} versions:set -DnewVersion=${effektVersion} -DgenerateBackupPoms=false").!!
     },
-
-    Compile / sourceGenerators += versionGenerator.taskValue
+    generateDocumentation := TreeDocs.replacer.value,
+    Compile / sourceGenerators += versionGenerator.taskValue,
+    Compile / sourceGenerators += TreeDocs.generator.taskValue
   )
   .jsSettings(
     scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.CommonJSModule) },

effekt/shared/src/main/scala/effekt/Namer.scala

@@ -189,7 +189,7 @@ object Namer extends Phase[Parsed, NameResolved] {
       Context.define(id, sym)
       Context.bindBlock(sym)
 
-    case d @ source.ExternInclude(path) =>
+    case d @ source.ExternInclude(path, _, _) =>
       d.contents = Context.contentsOf(path).getOrElse {
         Context.abort(s"Missing include: ${path}")
       }
@@ -312,7 +312,7 @@ object Namer extends Phase[Parsed, NameResolved] {
     case source.ExternInterface(id, tparams) => ()
     case source.ExternDef(pure, id, tps, vps, bps, ret, body) => ()
     case source.ExternResource(id, tpe) => ()
-    case source.ExternInclude(path) => ()
+    case source.ExternInclude(path, _, _) => ()
 
     case source.If(cond, thn, els) =>
       resolveGeneric(cond);

effekt/shared/src/main/scala/effekt/Parser.scala

@@ -315,7 +315,7 @@ class EffektParsers(positions: Positions) extends Parsers(positions) {
     )
 
   lazy val externInclude: P[Def] =
-    `extern` ~> `include` ~/> """\"([^\"]*)\"""".r ^^ { s => ExternInclude(s.stripPrefix("\"").stripSuffix("\""))("", IdDef("")) }
+    `extern` ~> `include` ~/> """\"([^\"]*)\"""".r ^^ { s => ExternInclude(s.stripPrefix("\"").stripSuffix("\"")) }
 
 
   /**

effekt/shared/src/main/scala/effekt/core/Transformer.scala

@@ -77,8 +77,8 @@ object Transformer extends Phase[Typechecked, CoreTransformed] {
       val sym = f.symbol
       Def(f.symbol, Context.functionTypeOf(sym), Extern((vps map transform) ++ (bps map transform), body), rest())
 
-    case e @ source.ExternInclude(path) =>
-      Include(e.contents, rest())
+    case e @ source.ExternInclude(path, contents, _) =>
+      Include(contents, rest())
 
     // For now we forget about all of the following definitions in core:
     case d: source.ExternResource => rest()

effekt/shared/src/main/scala/effekt/core/Tree.scala

@@ -3,6 +3,53 @@ package core
 
 import effekt.symbols.{ Symbol, TermSymbol, ValueSymbol, BlockSymbol, Interface, Operation, Type, ValueType, BlockType }
 
+/**
+ * Tree structure of programs in our internal core representation.
+ *
+ * ----------[[ effekt.core.Tree ]]----------
+ *
+ *   ─ [[ Tree ]]
+ *     │─ [[ ModuleDecl ]]
+ *     │─ [[ Argument ]]
+ *     │  │─ [[ Pure ]]
+ *     │  │─ [[ Block ]]
+ *     │
+ *     │─ [[ Expr ]]
+ *     │  │─ [[ DirectApp ]]
+ *     │  │─ [[ Run ]]
+ *     │  │─ [[ Pure ]]
+ *     │
+ *     │─ [[ Param ]]
+ *     │  │─ [[ ValueParam ]]
+ *     │  │─ [[ BlockParam ]]
+ *     │
+ *     │─ [[ Pattern ]]
+ *     │  │─ [[ IgnorePattern ]]
+ *     │  │─ [[ AnyPattern ]]
+ *     │  │─ [[ TagPattern ]]
+ *     │  │─ [[ LiteralPattern ]]
+ *     │
+ *     │─ [[ Stmt ]]
+ *     │  │─ [[ Def ]]
+ *     │  │─ [[ Val ]]
+ *     │  │─ [[ Let ]]
+ *     │  │─ [[ Data ]]
+ *     │  │─ [[ Record ]]
+ *     │  │─ [[ App ]]
+ *     │  │─ [[ If ]]
+ *     │  │─ [[ While ]]
+ *     │  │─ [[ Return ]]
+ *     │  │─ [[ Match ]]
+ *     │  │─ [[ Include ]]
+ *     │  │─ [[ Hole ]]
+ *     │  │─ [[ State ]]
+ *     │  │─ [[ Handle ]]
+ *     │  │─ [[ Region ]]
+ *     │
+ *     │─ [[ Handler ]]
+ *
+ * -------------------------------------------
+ */
 sealed trait Tree
 
 /**
@@ -15,6 +62,7 @@ case class ModuleDecl(path: String, imports: List[String], defs: Stmt, exports:
  */
 sealed trait Argument extends Tree
 
+
 /**
  * Expressions (with potential IO effects)
  *
@@ -30,8 +78,26 @@ case class DirectApp(b: Block, targs: List[Type], args: List[Argument]) extends
 // only inserted by the transformer if stmt is pure / io
 case class Run(s: Stmt, tpe: ValueType) extends Expr
 
+
 /**
  * Pure Expressions (no IO effects, or control effects)
+ *
+ * ----------[[ effekt.core.Pure ]]----------
+ *
+ *   ─ [[ Pure ]]
+ *     │─ [[ ValueVar ]]
+ *     │─ [[ Literal ]]
+ *     │  │─ [[ UnitLit ]]
+ *     │  │─ [[ IntLit ]]
+ *     │  │─ [[ BooleanLit ]]
+ *     │  │─ [[ DoubleLit ]]
+ *     │  │─ [[ StringLit ]]
+ *     │
+ *     │─ [[ PureApp ]]
+ *     │─ [[ Select ]]
+ *     │─ [[ Box ]]
+ *
+ * -------------------------------------------
  */
 sealed trait Pure extends Expr with Argument
 object Pure {
@@ -56,16 +122,19 @@ export Literal.*
 
 /**
  * Blocks
+ *
+ * ----------[[ effekt.core.Block ]]----------
+ *
+ *   ─ [[ Block ]]
+ *     │─ [[ BlockVar ]]
+ *     │─ [[ BlockLit ]]
+ *     │─ [[ Member ]]
+ *     │─ [[ Extern ]]
+ *     │─ [[ Unbox ]]
+ *     │─ [[ New ]]
+ *
+ * -------------------------------------------
  */
-
-enum Param extends Tree {
-  def id: TermSymbol
-
-  case ValueParam(id: ValueSymbol, tpe: ValueType)
-  case BlockParam(id: BlockSymbol, tpe: BlockType)
-}
-export Param.*
-
 enum Block extends Argument {
   case BlockVar(id: BlockSymbol)
   case BlockLit(params: List[Param], body: Stmt)
@@ -76,6 +145,15 @@ enum Block extends Argument {
 }
 export Block.*
 
+enum Param extends Tree {
+  def id: TermSymbol
+
+  case ValueParam(id: ValueSymbol, tpe: ValueType)
+  case BlockParam(id: BlockSymbol, tpe: BlockType)
+}
+export Param.*
+
+
 enum Pattern extends Tree {
   case IgnorePattern()
   case AnyPattern()
@@ -87,6 +165,27 @@ export Pattern.*
 
 /**
  * Statements
+ *
+ * ----------[[ effekt.core.Stmt ]]----------
+ *
+ *   ─ [[ Stmt ]]
+ *     │─ [[ Def ]]
+ *     │─ [[ Val ]]
+ *     │─ [[ Let ]]
+ *     │─ [[ Data ]]
+ *     │─ [[ Record ]]
+ *     │─ [[ App ]]
+ *     │─ [[ If ]]
+ *     │─ [[ While ]]
+ *     │─ [[ Return ]]
+ *     │─ [[ Match ]]
+ *     │─ [[ Include ]]
+ *     │─ [[ Hole ]]
+ *     │─ [[ State ]]
+ *     │─ [[ Handle ]]
+ *     │─ [[ Region ]]
+ *
+ * -------------------------------------------
  */
 enum Stmt extends Tree {
   case Def(id: BlockSymbol, tpe: BlockType, block: Block, rest: Stmt)

effekt/shared/src/main/scala/effekt/machine/Tree.scala

@@ -28,7 +28,7 @@ case class Label(name: String, environment: Environment)
  *
  *    List(x -> y)
  *
- * will replace all occurrences of x by y. Here x is a binding occurrence 
+ * will replace all occurrences of x by y. Here x is a binding occurrence
  * and y is a bound occurrence.
  */
 type Substitution = List[(Variable, Variable)]
@@ -52,22 +52,47 @@ export Declaration.*
 
 
 /**
- * Clauses are parametrized statements 
- * 
+ * Clauses are parametrized statements
+ *
  * e.g. { (x1...) => s }
- * 
+ *
  * The parameters (x1, etc.) are binding occurrences.
- * 
+ *
  *    Gamma ++ Delta |- s
  *    -----------------------
  *    Gamma |- { Delta => s }
- * 
+ *
  * In the typing rule Delta corresponds to [[parameters]].
  */
 case class Clause(parameters: Environment, body: Statement)
 
+
 /**
  * Statements
+ *
+ * ----------[[ effekt.machine.Statement ]]----------
+ *
+ *   ─ [[ Statement ]]
+ *     │─ [[ Def ]]
+ *     │─ [[ Jump ]]
+ *     │─ [[ Substitute ]]
+ *     │─ [[ Construct ]]
+ *     │─ [[ Switch ]]
+ *     │─ [[ New ]]
+ *     │─ [[ Invoke ]]
+ *     │─ [[ PushFrame ]]
+ *     │─ [[ Return ]]
+ *     │─ [[ NewStack ]]
+ *     │─ [[ PushStack ]]
+ *     │─ [[ PopStacks ]]
+ *     │─ [[ ForeignCall ]]
+ *     │─ [[ ComposeEvidence ]]
+ *     │─ [[ LiteralInt ]]
+ *     │─ [[ LiteralDouble ]]
+ *     │─ [[ LiteralUTF8String ]]
+ *     │─ [[ LiteralEvidence ]]
+ *
+ * --------------------------------------------------
  */
 enum Statement {