diff --git a/docs/docs/reference/metaprogramming/staging.md b/docs/docs/reference/metaprogramming/staging.md index 3444e3a0be79..f5a59f4f946a 100644 --- a/docs/docs/reference/metaprogramming/staging.md +++ b/docs/docs/reference/metaprogramming/staging.md @@ -8,13 +8,13 @@ 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 +as usual. What if we could synthesize code at run-time and offer one extra stage +to the programmer? Then we can have a value of type `Expr[T]` at run-time 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). +number of splices by more than one (effectively handling at run-time values of type +`Expr[Expr[T]]`, `Expr[Expr[Expr[T]]]`, ...) then we talk about Multi-Stage +Programming. The motivation behind this _paradigm_ is to let runtime information affect or guide code-generation. @@ -22,11 +22,11 @@ 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. + - 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 + 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 @@ -61,7 +61,7 @@ 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]` to `T` but only `$` is subject to the PCP, whereas `run` is just a normal method. Run provides a `QuoteContext` that can be used to show the expression in the scope of `run`. -On the other hand `withQuoteContext` provides a `QuoteContext` without evauating the expression. +On the other hand `withQuoteContext` provides a `QuoteContext` without evaluating the expression. ```scala package scala.quoted.staging @@ -81,12 +81,25 @@ From [lampepfl/dotty-staging.g8](https://github.com/lampepfl/dotty-staging.g8). It will create a project with the necessary dependencies and some examples. +In case you prefer to create the project on your own, make sure to define the following dependency in your build.sbt + +```scala +libraryDependencies += "ch.epfl.lamp" %% "dotty-staging" % scalaVersion.value +``` + +and in case you use `dotc`/`dotr` directly, then use the `-with-compiler` flag for both: + +```shell +dotc -with-compiler -d out Test.scala +dotr -with-compiler -classpath out Test +``` + ## Example Now take exactly the same example as in [Macros](./macros.md). Assume that we -do not want to pass an array statically but generated code at run-time and pass +do not want to pass an array statically but generate code at run-time and pass the value, also at run-time. Note, how we make a future-stage function of type -`Expr[Array[Int] => Int]` in line 4 below. Using `run { ... }` we can evaluate an +`Expr[Array[Int] => Int]` in line 6 below. Using `run { ... }` we can evaluate an expression at runtime. Within the scope of `run` we can also invoke `show` on an expression to get a source-like representation of the expression. @@ -104,24 +117,3 @@ val f: Array[Int] => Int = run { f.apply(Array(1, 2, 3)) // Returns 6 ``` - -Note that if we need to run the main (in an object called `Test`) after -compilation we need make available the compiler to the runtime: - -```shell -dotc -with-compiler -d out Test.scala -dotr -with-compiler -classpath out Test -``` - -Or, from SBT: - -```scala -libraryDependencies += "ch.epfl.lamp" %% "dotty-staging" % scalaVersion.value -``` - -## Template project -Using sbt version `1.1.5+`, do: -``` -sbt new lampepfl/dotty-staging.g8 -``` -in the folder where you want to clone the template.