Skip to content

doc(multi-staging): fix typos #8363

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Feb 27, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 23 additions & 31 deletions docs/docs/reference/metaprogramming/staging.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,25 @@ 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.

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
Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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.