wip (address comments)

Author: biboudis

docs/docs/reference/metaprogramming/inline.md

@@ -367,6 +367,17 @@ final val two = toInt[Succ[Succ[Zero]]]
 behavior. Since `toInt` performs static checks over the static type of `N` we
 can safely use it to scrutinize its return type (`S[S[Z]]` in this case).
 
+##### Error
+
+This package provides a compile time `error` definition with the following signature:
+
+```scala
+inline def error(inline msg: String, objs: Any*): Nothing
+```
+
+The purpose of this is to expand at the point of use, an error message (a
+constant string) and append with commas, compile time values passed in the
+`objs` param.
 
 #### Implicit Match
 

docs/docs/reference/metaprogramming/macros-spec.md

@@ -23,9 +23,12 @@ a quoted expression or type is treated as a splice `${x}` and a quoted identifie
 
 ### Implementation in `dotc`
 
-Quotes and splices are primitive forms in the generated abstract
-syntax trees. They are eliminated in an expansion phase
-`Staging`. This phase runs after typing and pickling.
+Quotes and splices are primitive forms in the generated abstract syntax trees.
+Top-level splices are eliminated during macro expansion while typing. On the
+other hand, top-level quotes are eliminated in an expansion phase `ReifyQuotes`
+phase (after typing and pickling). PCP checking occurs while preparing the RHS
+of an inline method for top-level splices and in the `Staging` phase (after
+typing and before pickling).
 
 Macro-expansion works outside-in. If the outermost scope is a splice,
 the spliced AST will be evaluated in an interpreter. A call to a

docs/docs/reference/metaprogramming/macros.md

@@ -3,34 +3,33 @@ layout: doc-page
 title: "Macros"
 ---
 
-<!--
-Example introducing macros earlier, e.g.,
-http://dotty.epfl.ch/docs/reference/other-new-features/principled-meta-programming.html#relationship-with-inline-and-macros
-
-
-- Syntax (example through string interpolation)
-- Expr and Type
-- PCP
-- Quoted Functions and β-reduction
-- Types and PCP (e.g., healing)
-- Lifting
-  - Expressions (http://dotty.epfl.ch/docs/reference/other-new-features/principled-meta-programming.html#the-liftable-type-class)
-  - Types (http://dotty.epfl.ch/docs/reference/other-new-features/principled-meta-programming.html#lifting-types)
-- Scope Extrusion (needs new name)
-  http://dotty.epfl.ch/docs/reference/other-new-features/principled-meta-programming.html#limitations-to-splicing
-- var references (e.g., let)
-- More Details include: spec syntax, formalization -->
-
 ### Macros: Quotes and Splices
 
 Macros are built on two well-known fundamental operations: quotation and
 splicing.  Quotation is expressed as `'{...}` for expressions (both forms are
 equivalent) and as `'[...]` for types. Splicing is expressed as `${ ... }`.
+Additionally, within a quote or a splice we can quote or splice identifiers
+directly (i.e. `'e` and `$e`). Readers may notice the resemblance of the two
+aforementioned syntactic schemes with the familiar string interpolation syntax.
+
+```scala
+println(s"Hello, $name, here is the result of 1 + 1 = ${1 + 1}")
+```
 
-For example, the code below presents an inline function `assert`
-which calls at compile-time a method `assertImpl` with a boolean
-expression tree as argument. `assertImpl` evaluates the expression and
+In string interpolation we _quoted_ a string and then we _spliced_ into it, two
+others. The first, `name`, is a reference to a value of type `string`, and the
+second is an arithmetic expression that will be _evaluated_ followed by the
+splicing of its string representation.
+
+Quotes and splices in this section allow us to treat code in a similar way,
+effectively supporting macros. The entry point for macros is an inline method
+with a top-level splice. We call it a top-level because it is the only occation
+where we encounter a splice outside a quote (consider as a quote the
+compilation-unit at the call-site). For example, the code below presents an
+`inline` method `assert` which calls at compile-time a method `assertImpl` with
+a boolean expression tree as argument. `assertImpl` evaluates the expression and
 prints it again in an error message if it evaluates to `false`.
+
 ```scala
     import scala.quoted._
 
@@ -45,6 +44,7 @@ prints it again in an error message if it evaluates to `false`.
     def showExpr(expr: Expr[Boolean]): Expr[String] =
       '{ "<some source code>" } // Better implementation later in this document
 ```
+
 If `e` is an expression, then `'{e}` represent the typed
 abstract syntax tree representing `e`. If `T` is a type, then `'[T]`
 represents the type structure representing `T`.  The precise
@@ -264,7 +264,7 @@ several types including `Boolean`, `String`, and all primitive number
 types. For example, `Int` values can be converted to `Expr[Int]`
 values by wrapping the value in a `Literal` tree node. This makes use
 of the underlying tree representation in the compiler for
-efficiency. But the `Liftable` instances are nevertheless not "magic"
+efficiency. But the `Liftable` instances are nevertheless not _magic_
 in the sense that they could all be defined in a user program without
 knowing anything about the representation of `Expr` trees. For
 instance, here is a possible instance of `Liftable[Boolean]`:
@@ -292,26 +292,26 @@ a `List` is liftable if its element type is:
 ```scala
     implied [T: Liftable] for Liftable[List[T]] {
       def toExpr(xs: List[T]): Expr[List[T]] = xs match {
-        case x :: xs1 => '{ ${ toExpr(x) } :: ${ toExpr(xs1) } }
+        case head :: tail => '{ ${ toExpr(head) } :: ${ toExpr(tail) } }
         case Nil => '{ Nil: List[T] }
       }
     }
 ```
 In the end, `Liftable` resembles very much a serialization
 framework. Like the latter it can be derived systematically for all
 collections, case classes and enums. Note also that the synthesis
-of "type-tag" values of type `Type[T]` is essentially the type-level
+of _type-tag_ values of type `Type[T]` is essentially the type-level
 analogue of lifting.
 
 Using lifting, we can now give the missing definition of `showExpr` in the introductory example:
 ```scala
     def showExpr[T](expr: Expr[T]): Expr[String] = {
-      val code = expr.show
+      val code: String = expr.show
       code.toExpr
     }
 ```
 That is, the `showExpr` method converts its `Expr` argument to a string (`code`), and lifts
-the result back to an `Expr[String]` using the `toExpr` wrapper.
+the result back to an `Expr[String]` using the `toExpr` method.
 
 **Note**: the `toExpr` extension method can be ommited by importing an implicit
 conversion with `import scala.quoted.autolift._`. The programmer is able to
@@ -451,12 +451,12 @@ soundness: code in splices must be free of side effects. The restriction
 prevents code like this:
 
 ```scala
-  var x: Expr[T]
+  var x: Expr[T] = ...
   '{ (y: T) => ${ x = 'y; 1 } }
 ```
 
-This code, if it was accepted, would "extrude" a reference to a quoted variable
-`y` from its scope. This means we an subsequently access a variable outside the
+This code, if it was accepted, would _extrude_ a reference to a quoted variable
+`y` from its scope. This would subsequently allow access to a variable outside the
 scope where it is defined, which is likely problematic. The code is clearly
 phase consistent, so we cannot use PCP to rule it out. Instead we postulate a
 future effect system that can guarantee that splices are pure. In the absence of

docs/docs/reference/metaprogramming/tasty-inspect.md

@@ -3,9 +3,17 @@ layout: doc-page
 title: "TASTy Inspection"
 ---
 
+TASTy files contain the full typed tree of a class including source positions
+and documentation. This is ideal for tools that analyze or extract semantic
+information of the code. To avoid the hassle of working directly with the TASTy
+file we provide the `TastyConsumer` which loads the contents and exposes it
+through the TASTy reflect API.
+
+
 ## Inspecting TASTy files
 
-To inspect the TASTy Reflect trees of a TASTy file a consumer can be defined in the following way.
+To inspect the TASTy Reflect trees of a TASTy file a consumer can be defined in
+the following way.
 
 ```scala
 class Consumer extends TastyConsumer {
@@ -16,7 +24,8 @@ class Consumer extends TastyConsumer {
 }
 ```
 
-Then the consumer can be instantiated with the following code to get the tree of the class `foo.Bar` for a foo in the classpath.
+Then the consumer can be instantiated with the following code to get the tree of
+the class `foo.Bar` for a foo in the classpath.
 
 ```scala
 object Test {

docs/docs/reference/metaprogramming/tasty-reflect.md

@@ -13,11 +13,11 @@ You may find all you need without using TASTy Reflect.
 
 ## API: From quotes and splices to TASTy reflect trees and back
 
-`quoted.Expr` and `quoted.Type` are only meant for generative meta-programming,
-generation of code without inspecting the ASTs. [Macros](./macros.html) provides
-the guarantee that the generation of code will be type-correct. Using TASTy
-Reflect will break these guarantees and may fail at macro expansion time, hence
-additional explicit checks must be done.
+With `quoted.Expr` and `quoted.Type` we can compute code but also analyze code
+by inspecting the ASTs. [Macros](./macros.html) provides the guarantee that the
+generation of code will be type-correct. Using TASTy Reflect will break these
+guarantees and may fail at macro expansion time, hence additional explicit
+checks must be done.
 
 To provide reflection capabilities in macros we need to add an implicit
 parameter of type `scala.tasty.Reflection` and import it in the scope where it
@@ -41,7 +41,7 @@ def natConstImpl(x: Expr[Int])(implicit reflection: Reflection): Expr[Int] = {
 and `quoted.Type` which returns a `reflection.Term` that represents the tree of
 the expression and `reflection.TypeTree` that represents the tree of the type
 respectively. It will also import all extractors and methods on TASTy Reflect
-trees. For example the `Term.Literal(_)` extractor used below.
+trees. For example the `Literal(_)` extractor used below.
 
 ```scala
 def natConstImpl(x: Expr[Int])(implicit reflection: Reflection): Expr[Int] = {

docs/docs/reference/metaprogramming/toc.md

@@ -37,12 +37,14 @@ introduce the following fundamental facilities:
    the program in many phases or ... stages, thus the "Multi-Stage" in the
    programming paradigm we say it supports.
 
-4. [TASTy Inspection](./tasty-inspect.html) Up until now we described how we can
+4. [TASTy Reflection](./tasty-reflect.html) With TASTy reflection we can
+   `unseal` fragments of code and analyze them with reflection over the TASTy
+   format of the code.
+
+5. [TASTy Inspection](./tasty-inspect.html) Up until now we described how we can
    expand, calculate at compile-time, or generate programs. The Scala compiler
    offers quarantees at the level of types that the generated programs cannot go
    wrong. With TASTy inspection we can load compiled files and analyze their
    typed AST structure according to the TASTy format.
 
-5. [TASTy Reflection](./tasty-reflect.html) With TASTy reflection we can
-   `unseal` fragments of code and analyze them with reflection over the TASTy
-   format of the code.
+