Tree Examples

This document lists examples of how Scala source code maps to Scalameta tree nodes.

Top level (meta.Source, meta.Pkg, meta.Pkg.Object)

"package a".parse[Source].get.structure

Source(stats = List(Pkg(ref = Term.Name("a"), stats = Nil)))

Declarations (meta.Decl)

"val a: Int".parse[Stat].get.structure

Decl.Val(
  mods = Nil,
  pats = List(Pat.Var(name = Term.Name("a"))),
  decltpe = Type.Name("Int")
)

Decl	Examples
Decl.Val	val a: Int
Decl.Var	var a: Int
Decl.Def	def f: Int
Decl.Type	type T

Definitions (meta.Defn)

"val a = 1".parse[Stat].get.structure

Defn.Val(
  mods = Nil,
  pats = List(Pat.Var(name = Term.Name("a"))),
  decltpe = None,
  rhs = Lit.Int(value = 1)
)

Defn	Examples
Defn.Val	val a = 1
Defn.Var	var a = 1
Defn.Def	def f = 1
Defn.Macro	def f = macro impl
Defn.Type	type T = Int
Defn.Class	class A
Defn.Trait	trait A
Defn.Object	object A
Defn.Enum	enum A (Scala 3)
Defn.EnumCase	case A1 extends A (Scala 3)
Defn.RepeatedEnumCase	case A1, A2 (Scala 3)
Defn.Given	given A as C[T] (Scala 3)
Defn.GivenAlias	given C[T] = A (Scala 3)
Defn.ExtensionGroup	extension (b: B) def a = 1 (Scala 3)

Terms (meta.Term)

"1 + 1".parse[Term].get.structure

Term.ApplyInfix(
  lhs = Lit.Int(value = 1),
  op = Term.Name("+"),
  targs = Nil,
  args = List(Lit.Int(value = 1))
)

Ref	Examples
Term.This	this, a.this
Term.Super	super, a.super, super[a], a.super[b]
Term.Name	a
Term.Select	a.b
Term.ApplyUnary	!a, ~a, -a, a

Term	Examples
Term.Apply	f(42)
Term.ApplyType	implicitly[Ordering[Int]]
Term.ApplyInfix	a + a
Term.Assign	a = 1
Term.Return	return a
Term.Throw	throw e
Term.Ascribe	a: Int
Term.Annotate	(x: @annot)
Term.Tuple	(1, 1)
Term.Block	{ f1(); f2() }
Term.If	if (p) t else f
Term.Match	x match { case _ => }
Term.Try	try f catch { case _ => }
Term.TryWithHandler	try f catch (h)
Term.Function	(a, b) => a + b
Term.PartialFunction	{ case _ => }
Term.While	while(p){ f() }
Term.Do	do { f() } while(p)
Term.For	for{x <- xs} f(x)
Term.ForYield	for{x <- xs} yield f(x)
Term.New	new A
Term.NewAnonymous	new A { }
Term.Placeholder	_
Term.Eta	f _
Term.Repeated	f(x: _*)
Term.Param	x: Int in def f(x: Int)
Term.Interpolate	s"Hello $name"
Term.Xml	<h1>Hello {name}</h1>
Term.ApplyUsing	method(using c) (Scala 3)
Term.EndMarker	end if (Scala 3)
Term.QuotedMacroExpr	'{ 'ax } (Scala 3)
Term.QuotedMacroType	'[ Map[Int, String] ] (Scala 3)
Term.SplicedMacroExpr	${ env } (Scala 3)
Term.ContextFunction	ExecutionContext ?=> T (Scala 3)
Term.PolyFunction	[T] => (t: T) => t (Scala 3)

Types (meta.Type)

"A with B".parse[Type].get.structure

Type.With(lhs = Type.Name("A"), rhs = Type.Name("B"))

Ref	Examples
Type.Name	B
Type.Select	a.B
Type.Project	a#B
Type.Singleton	a.type

Type	Examples
Type.Apply	F[T]
Type.ApplyInfix	K Map V
Type.Function	A => B
Type.Tuple	(A, B)
Type.With	A with B
Type.And	A & B (Scala 3)
Type.Or	A | B (Scala 3)
Type.Refine	A { def f: Int }
Type.Existential	A forSome { type T }
Type.Annotate	T @annot
Type.Lambda	[T] => (T, T) (only for supported dialects)
Type.Method	(x: T): T (only for supported dialects)
Type.Placeholder	_ in T[_]
Type.Bounds	T >: Lower <: Upper in def F[T >: Lower <: Upper] = 1
Type.ByName	=>T in def f(x: => T) = x
Type.Repeated	T* in def f(x: T*): Unit
Type.Var	t in case _: List[t] =>
Type.Param	X in trait A[X]
Type.PolyFunction	[T] => (t: T) => t (Scala 3)
Type.ContextFunction	ExecutionContext ?=> T (Scala 3)
Type.Match	type T = match { case A => B} (Scala 3)

Patterns (meta.Pat) and Cases (meta.Case)

"_: A | _: B".parse[Pat].get.structure

Pat.Alternative(
  Pat.Typed(Pat.Wildcard(), Type.Name("A")),
  Pat.Typed(Pat.Wildcard(), Type.Name("B"))
)

Pat	Examples
Lit	"literal"
Pat.Wildcard	_
Pat.SeqWildcard	_* in case List(xs @ _*) =>
Pat.Var	a in case a =>
Pat.Bind	a @ A()
Pat.Alternative	1 | 2
Pat.Tuple	(a, b)
Pat.Extract	A(a, b)
Pat.ExtractInfix	a E b
Pat.Interpolate	r"Hello (.+)$name"
Pat.Xml	<h1>Hello, World!</h1>
Pat.Typed	a: Int
Term.Select	a.b
Term.Macro	case 'c => 1 (Scala 3)
Term.Given	case ctx as given Context (Scala 3)

"case a => ()".parse[Case].get.structure

Case(Pat.Var(Term.Name("a")), None, Lit.Unit(()))

Case	Examples
Case	case a if p => f()
TypeCase	case A[t] => F[t] (Scala 3)

Name (meta.Name)

meta.Name.Anonymous()

"class B { }".parse[Source].get.structure

Source(
  stats = List(
    Defn.Class(
      mods = Nil,
      name = Type.Name("B"),
      tparams = Nil,
      ctor = Ctor.Primary(
        mods = Nil,
        name = Name.Anonymous(),
        paramss = Nil
      ),
      templ = Template(
        early = Nil,
        inits = Nil,
        self = Self(
          name = Name.Anonymous(),
          decltpe = None
        ),
        stats = Nil
      )
    )
  )
)

meta.name.Indeterminate()

Is it a type, or is it a term? Indeterminate.

"import a.b".parse[Source].get.structure

Source(
  stats = List(
    Import(
      importers = List(
        Importer(
          ref = Term.Name("a"),
          importees = List(
            Importee.Name(
              name = Name.Indeterminate(
                value = b
              )
            )
          )
        )
      )
    )
  )
)

Literals (meta.Lit)

"null".parse[Term].get.structure

Lit.Null()

Lit	Example
Null	null
Boolean	true
Unit	()
Int	1
Double	1.0
Float	1.0F
Long	1L
Byte	(no available syntax)
Short	(no available syntax)
Char	'a'
Symbol	'a
String	"A"

Coments (meta.Tree.Comments)

Starting with v4.14.3, scalameta allows both parsing some comments and attaching them to trees.

"""|/*
   | * leading comment 1
   | */
   |// leading comment
   |null /* trailing comment 1 */ // trailing comment 2
   |// unattached comment
   |""".stripMargin.parse[Term].get.structure

/*
 * leading comment 1
 */
// leading comment 2
Lit.Null() /* trailing comment 1 */ // trailing comment 2

Constructing trees with comments

To create a tree with comments, instead of the standard apply method, use createWithComments which appends two additional parameters:

Lit.Null.createWithComments(
  begComment = Some(Tree.Comments(List(
    Tree.Comment(List(Lit.String("/*\n * leading comment 1\n */"))),
    Tree.Comment(List(Lit.String("// leading comment 2")))
  ))),
  endComment = Some(Tree.Comments(List(
    Tree.Comment(List(Lit.String("/* trailing comment 1 */"))),
    Tree.Comment(List(Lit.String("// trailing comment 2")))
  )))
)
Term.Name.createWithComments(
  "identifier",
  begComment = Some(Tree.Comments(List(
    Tree.Comment(List(Lit.String("/* comment */")))
  ))),
  endComment = None // default
)

In addition, the trees now also provide copyWithComments instance methods, which work similarly.

Parsing trees with comments

The scalameta parser will attach the following comments to a parsed tree:

• any comment tokens which follow the tree until the first newline or non-trivial (non-space and non-comment) token
• any comment tokens which precede the tree if they are themselves preceded by a newline or if the first non-trivial token before them is neither an identifier nor a closing delimiter (because then that comment would be attached to the tree ending in that token)

This means, for instance, that a comment following punctuation (say, a comma or a an equals or a colon) would be attached to the next tree rather than the preceding (because punctuation is not included in that previous tree):

foo: // fewer braces call; leading for `bar`
  bar, // first argument comment; leading for `baz`
  baz // second argument; trailing for `baz
)

foo /* fewer braces call; trailing for `foo` */:
  bar /* first argument comment; trailing for `bar` */,
  baz
)

Keep in mind that after parsing, multiple trees might refer to the same exact comments. In the example below, // some comment will be accessible both from Term.Name("bar") and from Defn.Val("foo", ...).

val foo = bar // some comment

Showing trees with comments

The .structure and .syntax methods will only output a comment associated with a tree if

• the tree is not parsed (say, created manually), or
• its parent is not set (also a likely case with manually generated trees), or
• the parent does not contain the same comment
  • if it does, the comment will simply be attributed to the parent