wip

Author: biboudis

docs/docs/reference/metaprogramming/macros.md

@@ -487,95 +487,54 @@ the code it runs produces one.
 
 ### Example Expansion
 
-Assume an `Array` class with an inline `map` method that forwards to a macro
-implementation.
+TODO
+
+Assume we have two methods, one `map` that takes an `Expr[Array[T]]` and a
+function `f` and one `sum` that performs a sum by delegating to `map`.
 
 ```scala
-    class Array[T] {
-      inline def map[U](f: T => U): Array[U] = ${ Macros.mapImpl[T, U]('[U], 'this, 'f) }
+object Macros {
+  def map[T](arr: Expr[Array[T]], f: Expr[T] => Expr[Unit])(implicit t: Type[T]): Expr[Unit] = '{
+    var i: Int = 0
+    while (i < ($arr).length) {
+      val element: $t = ($arr)(i)
+      ${f('element)}
+      i += 1
     }
-```
-
-Here’s the definition of the `mapImpl` macro, which takes quoted types and
-expressions to a quoted expression:
+  }
 
-```scala
-    object Macros {
+  def sum(arr: Expr[Array[Int]]): Expr[Int] = '{
+    var sum = 0
+    ${ map(arr, x => '{sum += $x}) }
+    sum
+  }
 
-      def mapImpl[T, U](u: Type[U], arr: Expr[Array[T]], op: Expr[T => U]): Expr[Array[U]] = '{
-        var i = 0
-        val xs = $arr
-        var len = xs.length
-        val ys = new Array[$u](len)
-        while (i < len) {
-          ys(i) = ${ op('{ xs(i) }) }
-          i += 1
-        }
-        ys
-      }
-    }
+  inline def sum_m(arr: Array[Int]): Int = ${sum('arr)}
+}
 ```
 
-Here’s an application of `map` and how it rewrites to optimized code:
+A call to `sum_m(Array(1,2,3))` will first inline `sum`:
 
 ```scala
-    genSeq[Int]().map(x => x + 1)
+var sum = 0
+${ _root_.Macros.map(arr, x => '{sum += $x}) }
+sum
 ```
-==> (inline)
-```scala
-    val _this: Seq[Int] = genSeq[Int]()
-    val f: Int => Int = x => x + 1
-    ${ _root_.Macros.mapImpl[Int, Int]('[Int], '_this, 'f) }
-```
-==> (splice)
-```scala
-    val _this: Seq[Int] = genSeq[Int]()
-    val f: Int => Int = x => x + 1
 
-    {
-      var i = 0
-      val xs = ${ '_this }
-      var len = xs.length
-      val ys = new Array[${ '[Int] }](len)
-      while (i < len) {
-        ys(i) = ${ ('f)('{ xs(i) }) }
-        i += 1
-      }
-      ys
-    }
-```
-==> (expand and splice inside quotes)
-```scala
-    val _this: Seq[Int] = genSeq[Int]()
-    val f: Int => Int = x => x + 1
+then it will splice:
 
-    {
-      var i = 0
-      val xs = _this
-      var len = xs.length
-      val ys = new Array[Int](len)
-      while (i < len) {
-        ys(i) = xs(i) + 1
-        i += 1
-      }
-      ys
-    }
-```
-==> (elim dead code)
 ```scala
-    val _this: Seq[Int] = genSeq[Int]()
+var sum = 0
+var i: Int = 0
 
-    {
-      var i = 0
-      val xs = _this
-      var len = xs.length
-      val ys = new Array[Int](len)
-      while (i < len) {
-        ys(i) = xs(i) + 1
-        i += 1
-      }
-      ys
-    }
+while (i < ($arr).length) {
+  val element: $t = ($arr)(i)
+  ${f('element)}
+  i += 1
+}
+
+${ _root_.Macros.map(arr, x => '{sum += $x}) }
+sum
 ```
 
 ### Relationship with Whitebox Inline

docs/docs/reference/metaprogramming/staging.md

@@ -3,34 +3,47 @@ layout: doc-page
 title: "Multi-Stage Programming"
 ----
 
-The framework expresses at the same time compile-time meta-programming
-and staging. The phase in which code is run is determined by the
-difference between the number of splice scopes and quote scopes in
-which it is embedded.
-
- - If there are more splices than quotes, the code is run at
-   "compile-time" i.e. as a macro. In the general case, this means
-   running an interpreter that evaluates the code, which is
-   represented as a typed abstract syntax tree. The interpreter can
-   fall back to reflective calls when evaluating an application of a
-   previously compiled method.  If the splice excess is more than one,
-   it would mean that a macro’s implementation code (as opposed to the
-   code it expands to) invokes other macros. If macros are realized by
-   interpretation, this would lead to towers of interpreters, where
-   the first interpreter would itself interpret an interpreter code
-   that possibly interprets another interpreter and so on.
-
- - If the number of splices equals the number of quotes, the code is
-   compiled and run as usual.
-
- - If the number of quotes exceeds the number of splices, the code is
-   staged. That is, it produces a typed abstract syntax tree or type
-   structure at run-time. A quote excess of more than one corresponds
-   to multi-staged programming.
-
-Providing an interpreter for the full language is quite difficult, and
-it is even more difficult to make that interpreter run efficiently. So
-we currently impose the following restrictions on the use of splices.
+The framework expresses at the same time compile-time meta-programming and
+multi-staging programming. We can think of compile-time meta-programming as a
+two stage compilation process: one that we write the code in top-level splices,
+that will be used for code generation (macros) and one that will perform all
+necessecary evaluations at compile-time and an object program that we will run
+as usual. What if we could synthesize code at runtime and offer one extra stage
+to the programmer? Then we can have a value of type `Expr[T]` at runtime that we
+can essentially treat as a typed-syntax tree that we can either _show_ as a
+string (pretty-print) or compile and run. If the number of quotes exceeds the
+number of splices more than one (effectively handling at run-time values of type
+`Expr[Expr[T]]`, `Expr[Expr[Expr[T]]]`, ... we talk about Multi-Stage
+Programming).
+
+The motivation behind this _paradigm_ is to let runtime information affect or
+guide code-generation.
+
+Intuition: The phase in which code is run is determined by the difference
+between the number of splice scopes and quote scopes in which it is embedded.
+
+ - If there are more splices than quotes, the code is run at "compile-time" i.e.
+   as a macro. In the general case, this means running an interpreter that
+   evaluates the code, which is represented as a typed abstract syntax tree. The
+   interpreter can fall back to reflective calls when evaluating an application
+   of a previously compiled method.  If the splice excess is more than one, it
+   would mean that a macro’s implementation code (as opposed to the code it
+   expands to) invokes other macros. If macros are realized by interpretation,
+   this would lead to towers of interpreters, where the first interpreter would
+   itself interpret an interpreter code that possibly interprets another
+   interpreter and so on.
+
+ - If the number of splices equals the number of quotes, the code is compiled
+   and run as usual.
+
+ - If the number of quotes exceeds the number of splices, the code is staged.
+   That is, it produces a typed abstract syntax tree or type structure at
+   run-time. A quote excess of more than one corresponds to multi-staged
+   programming.
+
+Providing an interpreter for the full language is quite difficult, and it is
+even more difficult to make that interpreter run efficiently. So we currently
+impose the following restrictions on the use of splices.
 
  1. A top-level splice must appear in an inline method (turning that method
     into a macro)
@@ -42,6 +55,8 @@ we currently impose the following restrictions on the use of splices.
 
  4. A macro method is effectively final and it may override no other method.
 
+## API
+
 The framework as discussed so far allows code to be staged, i.e. be prepared
 to be executed at a later stage. To run that code, there is another method
 in class `Expr` called `run`. Note that `$` and `run` both map from `Expr[T]`
@@ -53,3 +68,17 @@ sealed abstract class Expr[T] {
   def show given (toolbox: Toolbox): String  // show staged code
 }
 ```
+
+## Example
+
+TODO
+sbt:dotty> dotr -classpath out -with-compiler Test
+
+```scala
+    // staging
+    implicit val toolbox: scala.quoted.Toolbox = scala.quoted.Toolbox.make(getClass.getClassLoader)
+    val sum_s = '{ (arr: Array[Int]) => ${sum('arr)}}
+    println(sum_s.show)
+
+    sum_s.run.apply(Array(1, 2, 3)) // Returns 6
+```

docs/sidebar.yml

@@ -67,6 +67,20 @@ sidebar:
               url: docs/reference/contextual/inferable-by-name-parameters.html
             - title: Relationship with Scala 2 Implicits
               url: docs/reference/contextual/relationship-implicits.html
+        - title: Metaprogramming
+          subsection:
+            - title: Overview
+              url: docs/reference/metaprogramming/toc.html
+            - title: Inline
+              url: docs/reference/metaprogramming/inline.html
+            - title: Macros
+              url: docs/reference/metaprogramming/macros.html
+            - title: Staging
+              url: docs/reference/metaprogramming/staging.html
+            - title: TASTy Reflection
+              url: docs/reference/metaprogramming/tasty-reflect.html
+            - title: TASTy Inspection
+              url: docs/reference/metaprogramming/tasty-inspect.html
         - title: Other New Features
           subsection:
             - title: Trait Parameters
@@ -75,12 +89,6 @@ sidebar:
               url: docs/reference/other-new-features/creator-applications.html
             - title: Export Clauses
               url: docs/reference/other-new-features/export.html
-            - title: Inlining by Rewriting
-              url: docs/reference/other-new-features/inline.html
-            - title: Meta Programming
-              url: docs/reference/other-new-features/principled-meta-programming.html
-            - title: TASTy Reflect
-              url: docs/reference/other-new-features/tasty-reflect.html
             - title: Opaque Type Aliases
               url: docs/reference/other-new-features/opaques.html
             - title: Parameter Untupling