Skip to content

Add some docs in Quotes.scala #11218

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.

Sign up for GitHub

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 3 commits into from
Jan 27, 2021
Merged

Add some docs in Quotes.scala #11218

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d192c1f
Add some docs in Quotes.scala
nicolasstucki Jan 26, 2021
d8d6a62
Add back package
nicolasstucki Jan 26, 2021
e8b69dc
Apply suggestions from code review
nicolasstucki Jan 27, 2021
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
2 changes: 2 additions & 0 deletions compiler/src/scala/quoted/runtime/impl/QuotesImpl.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,8 +153,10 @@ class QuotesImpl private (using val ctx: Context) extends Quotes, QuoteUnpickler

object Import extends ImportModule:
def apply(expr: Term, selectors: List[Selector]): Import =
if selectors.isEmpty then throw IllegalArgumentException("Empty selectors")
withDefaultPos(tpd.Import(expr, selectors))
def copy(original: Tree)(expr: Term, selectors: List[Selector]): Import =
if selectors.isEmpty then throw IllegalArgumentException("Empty selectors")
tpd.cpy.Import(original)(expr, selectors)
def unapply(tree: Import): (Term, List[Selector]) =
(tree.expr, tree.selectors)
Expand Down
168 changes: 149 additions & 19 deletions library/src/scala/quoted/Quotes.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,16 @@ package scala.quoted

import scala.reflect.TypeTest

/** Current Quotes in scope */
/** Current Quotes in scope
*
* Usage:
* ```scala
* def myExpr[T](using Quotes): Expr[T] = {
* import quotes.relect._
* ...
* }
* ```
*/
inline def quotes(using q: Quotes): q.type = q

/** Quotation context provided by a macro expansion or in the scope of `scala.quoted.staging.run`.
Expand Down Expand Up @@ -223,8 +232,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
val Tree: TreeModule

/** Methods of the module object `val Tree` */
trait TreeModule { this: Tree.type =>
}
trait TreeModule { this: Tree.type => }

/** Makes extension methods on `Tree` available without any imports */
given TreeMethods: TreeMethods
Expand Down Expand Up @@ -260,7 +268,21 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>

}

/** Tree representing a pacakage clause in the source code */
/** Tree representing a pacakage clause in the source code
*
* ```scala
* package foo {
* // package stats
* }
* ```
*
* or
*
* ```scala
* package foo.bar
* // package stats
* ```
*/
type PackageClause <: Tree

/** `TypeTest` that allows testing at runtime in a pattern match if a `Tree` is a `PackageClause` */
Expand All @@ -271,8 +293,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>

/** Methods of the module object `val PackageClause` */
trait PackageClauseModule { this: PackageClause.type =>
/** Create a package clause `package pid { stats }` */
def apply(pid: Ref, stats: List[Tree]): PackageClause
/** Copy a package clause `package pid { stats }` */
def copy(original: Tree)(pid: Ref, stats: List[Tree]): PackageClause
/** Matches a package clause `package pid { stats }` and extracts the `pid` and `stats` */
def unapply(tree: PackageClause): (Ref, List[Tree])
}

Expand All @@ -282,12 +307,17 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `PackageClause` */
trait PackageClauseMethods:
extension (self: PackageClause)
/** Tree containing the package name */
def pid: Ref
/** Definitions, imports or exports within the package */
def stats: List[Tree]
end extension
end PackageClauseMethods

/** Tree representing an import in the source code */
/** Tree representing an import in the source code.
*
* See also documentation on `Selector`.
*/
type Import <: Statement

/** `TypeTest` that allows testing at runtime in a pattern match if a `Tree` is an `Import` */
Expand All @@ -298,8 +328,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>

/** Methods of the module object `val Import` */
trait ImportModule { this: Import.type =>
/** Create an `Import` with the given qualifier and selectors */
def apply(expr: Term, selectors: List[Selector]): Import
/** Copy an `Import` with the given qualifier and selectors */
def copy(original: Tree)(expr: Term, selectors: List[Selector]): Import
/** Matches an `Import` and extracts the qualifier and selectors */
def unapply(tree: Import): (Term, List[Selector])
}

Expand All @@ -309,7 +342,12 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `Import` */
trait ImportMethods:
extension (self: Import)
/** Qualifier of the import */
def expr: Term
/** List Selectors of the import
*
* See documentation on `Selector`
*/
def selectors: List[Selector]
end extension
end ImportMethods
Expand All @@ -327,6 +365,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>

/** Methods of the module object `val Export` */
trait ExportModule { this: Export.type =>
/** Matches an `Export` and extracts the qualifier and selectors */
def unapply(tree: Export): (Term, List[Selector])
}

Expand All @@ -336,7 +375,12 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `Export` */
trait ExportMethods:
extension (self: Export)
/** Qualifier of the export */
def expr: Term
/** List Selectors of the export
*
* See documentation on `Selector`
*/
def selectors: List[Selector]
end extension
end ExportMethods
Expand Down Expand Up @@ -367,6 +411,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `Definition` */
trait DefinitionMethods:
extension (self: Definition)
/** Name of the definition */
def name: String
end extension
end DefinitionMethods
Expand Down Expand Up @@ -395,10 +440,31 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `ClassDef` */
trait ClassDefMethods:
extension (self: ClassDef)
/** The primary constructor of this class */
def constructor: DefDef
/** List of extended parent classes or traits.
* The first parent is always a class.
*/
def parents: List[Tree /* Term | TypeTree */]
def derived: List[TypeTree]
/** List of derived type classes */
def derived: List[TypeTree] // TODO remove? It seems these don't exist after desugaring
/** Self-type of the class
*
* ```scala
* class C { self: T =>
* ...
* }
* ```
*/
def self: Option[ValDef]
/** Statements within the class
*
* ```scala
* class C {
* ... // statemets
* }
* ```
*/
def body: List[Statement]
end extension
end ClassDefMethods
Expand Down Expand Up @@ -452,7 +518,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** List of term parameter clauses */
def termParamss: List[TermParamClause]

/** The tree of the return type of the method */
/** The tree of the return type of this `def` definition */
def returnTpt: TypeTree

/** The tree of the implementation of the method.
Expand Down Expand Up @@ -496,7 +562,9 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `ValDef` */
trait ValDefMethods:
extension (self: ValDef)
/** The type tree of this `val` definition */
def tpt: TypeTree
/** The right-hand side of this `val` definition */
def rhs: Option[Term]
end extension
end ValDefMethods
Expand All @@ -515,8 +583,8 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Methods of the module object `val TypeDef` */
trait TypeDefModule { this: TypeDef.type =>
def apply(symbol: Symbol): TypeDef
def copy(original: Tree)(name: String, rhs: Tree /*TypeTree | TypeBoundsTree*/): TypeDef
def unapply(tdef: TypeDef): (String, Tree /*TypeTree | TypeBoundsTree*/ /* TypeTree | TypeBoundsTree */)
def copy(original: Tree)(name: String, rhs: Tree): TypeDef
def unapply(tdef: TypeDef): (String, Tree)
}

/** Makes extension methods on `TypeDef` available without any imports */
Expand All @@ -525,7 +593,8 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `TypeDef` */
trait TypeDefMethods:
extension (self: TypeDef)
def rhs: Tree /*TypeTree | TypeBoundsTree*/
/** The type bounds on the right-hand side of this `type` definition */
def rhs: Tree
end extension
end TypeDefMethods

Expand Down Expand Up @@ -666,6 +735,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `Ident` */
trait IdentMethods:
extension (self: Ident)
/** Name of this `Ident` */
def name: String
end extension
end IdentMethods
Expand Down Expand Up @@ -710,8 +780,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `Select` */
trait SelectMethods:
extension (self: Select)
/** Qualifier of the `qualifier.name` */
def qualifier: Term
/** Name of this `Select` */
def name: String
/** Signature of this method */
def signature: Option[Signature]
end extension
end SelectMethods
Expand Down Expand Up @@ -743,11 +816,12 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `Literal` */
trait LiteralMethods:
extension (self: Literal)
/** Value of this literal */
def constant: Constant
end extension
end LiteralMethods

/** Tree representing `this` in the source code */
/** Tree representing `this` or `C.this` in the source code */
type This <: Term

/** `TypeTest` that allows testing at runtime in a pattern match if a `Tree` is a `This` */
Expand All @@ -759,12 +833,12 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Methods of the module object `val This` */
trait ThisModule { this: This.type =>

/** Create a `this[<id: String]>` */
/** Create a `C.this` for `C` pointing to `cls` */
def apply(cls: Symbol): This

def copy(original: Tree)(qual: Option[String]): This

/** Matches `this[<id: Option[String]>` */
/** Matches `this` or `qual.this` and returns the name of `qual` */
def unapply(x: This): Some[Option[String]]
}

Expand All @@ -774,6 +848,10 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `This` */
trait ThisMethods:
extension (self: This)
/** Returns `C` if the underlying tree is of the form `C.this`
*
* Otherwise, return `None`.
*/
def id: Option[String]
end extension
end ThisMethods
Expand All @@ -795,7 +873,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>

def copy(original: Tree)(tpt: TypeTree): New

/** Matches a `new <tpt: TypeTree>` */
/** Matches `new <tpt: TypeTree>` */
def unapply(x: New): Some[TypeTree]
}

Expand All @@ -805,6 +883,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `New` */
trait NewMethods:
extension (self: New)
/** Returns the type tree of this `new` */
def tpt: TypeTree
end extension
end NewMethods
Expand Down Expand Up @@ -836,7 +915,9 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `NamedArg` */
trait NamedArgMethods:
extension (self: NamedArg)
/** The name part of `name = arg` */
def name: String
/** The argument part of `name = arg` */
def value: Term
end extension
end NamedArgMethods
Expand Down Expand Up @@ -868,7 +949,27 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `Apply` */
trait ApplyMethods:
extension (self: Apply)
/** The `fun` part of an (implicit) application like `fun(args)`
*
* It maybe a partially applied method:
* ```scala
* def f(x1: Int)(x2: Int) = ...
* f(1)(2)
* ```
* - `fun` is `f(1)` in the `Apply` of `f(1)(2)`
* - `fun` is `f` in the `Apply` of `f(1)`
*/
def fun: Term
/** The arguments (implicitly) passed to the method
*
* The `Apply` maybe a partially applied method:
* ```scala
* def f(x1: Int)(x2: Int) = ...
* f(1)(2)
* ```
* - `args` is `(2)` in the `Apply` of `f(1)(2)`
* - `args` is `(1)` in the `Apply` of `f(1)`
*/
def args: List[Term]
end extension
end ApplyMethods
Expand Down Expand Up @@ -900,7 +1001,35 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/** Extension methods of `TypeApply` */
trait TypeApplyMethods:
extension (self: TypeApply)
/** The `fun` part of an (inferred) type application like `fun[Args]`
*
* It maybe a partially applied method:
* ```scala
* extension (x: Int) def f[T](y: T) = ...
* // represented as
* // def f(x: Int)[T](y: T) = ...
*
* 1.f[Int](2)
* // represented as
* // f(1)[Int](2)
* ```
* - `fun` is `f(1)` in the `TypeApply` of `f(1)[Int]`
*/
def fun: Term
/** The (inferred) type arguments passed to the method
*
* The `TypeApply` maybe a partially applied method:
* ```scala
* extension (x: Int) def f[T](y: T) = ...
* // represented as
* // def f(x: Int)[T](y: T) = ...
*
* 1.f[Int](2)
* // represented as
* // f(1)[Int](2)
* ```
* - `fun` is `[Int]` in the `TypeApply` of `f(1)[Int]`
*/
def args: List[TypeTree]
end extension
end TypeApplyMethods
Expand Down Expand Up @@ -2040,11 +2169,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
/////////////////////

/** Import/Export selectors:
* * SimpleSelector: `.bar` in `import foo.bar`
* * RenameSelector: `.{bar => baz}` in `export foo.{bar => baz}`
* * OmitSelector: `.{bar => _}` in `import foo.{bar => _}`
* * GivenSelector: `.given`/`.{given T}` in `export foo.given`/`import foo.{given T}`
*/
* - SimpleSelector: `.bar` in `import foo.bar`
* - RenameSelector: `.{bar => baz}` in `export foo.{bar => baz}`
* - OmitSelector: `.{bar => _}` in `import foo.{bar => _}`
* - GivenSelector: `.given`/`.{given T}` in `export foo.given`/`import foo.{given T}`
*/
type Selector <: AnyRef

/** Module object of `type Selector` */
Expand Down Expand Up @@ -4324,3 +4453,4 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
type Nested = Quotes

}