From d7ee473c4016235baaefefc06b7e238c500c0388 Mon Sep 17 00:00:00 2001 From: Robert Stoll Date: Mon, 24 Feb 2020 08:45:32 +0100 Subject: [PATCH 1/4] doc(multi-staging): fix typos --- docs/docs/reference/metaprogramming/staging.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/docs/reference/metaprogramming/staging.md b/docs/docs/reference/metaprogramming/staging.md index 3444e3a0be79..ebb7c92a2995 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 From 946604b5e207d1444906385a5c9dcfa2fd27823e Mon Sep 17 00:00:00 2001 From: Robert Stoll Date: Mon, 24 Feb 2020 08:49:56 +0100 Subject: [PATCH 2/4] doc(multi-staging): more typos --- docs/docs/reference/metaprogramming/staging.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/reference/metaprogramming/staging.md b/docs/docs/reference/metaprogramming/staging.md index ebb7c92a2995..6c47e70d6805 100644 --- a/docs/docs/reference/metaprogramming/staging.md +++ b/docs/docs/reference/metaprogramming/staging.md @@ -84,9 +84,9 @@ It will create a project with the necessary dependencies and some examples. ## 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. @@ -106,7 +106,7 @@ 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: +compilation we need to make available the compilation to the runtime: ```shell dotc -with-compiler -d out Test.scala From b3442396d9865ffabf14a4d2cff8784063b33ef2 Mon Sep 17 00:00:00 2001 From: Robert Stoll Date: Tue, 25 Feb 2020 15:07:52 +0100 Subject: [PATCH 3/4] doc(multi-staging): move setup/flags to create a new project --- .../docs/reference/metaprogramming/staging.md | 34 +++++++------------ 1 file changed, 13 insertions(+), 21 deletions(-) diff --git a/docs/docs/reference/metaprogramming/staging.md b/docs/docs/reference/metaprogramming/staging.md index 6c47e70d6805..b2b1b0c0411a 100644 --- a/docs/docs/reference/metaprogramming/staging.md +++ b/docs/docs/reference/metaprogramming/staging.md @@ -81,6 +81,19 @@ 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 @@ -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 to make available the compilation 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. From 5dcb63a3717226354e5f5886dc4e1274c631d731 Mon Sep 17 00:00:00 2001 From: Robert Stoll Date: Tue, 25 Feb 2020 15:09:03 +0100 Subject: [PATCH 4/4] doc(multi-staging): cleanup new lines --- docs/docs/reference/metaprogramming/staging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/reference/metaprogramming/staging.md b/docs/docs/reference/metaprogramming/staging.md index b2b1b0c0411a..f5a59f4f946a 100644 --- a/docs/docs/reference/metaprogramming/staging.md +++ b/docs/docs/reference/metaprogramming/staging.md @@ -88,12 +88,12 @@ 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