Scalameta

https://scalameta.org/docs/
Admin
Scalameta is a metaprogramming platform for Scala that provides portable APIs for syntax trees,...
Tokens:30,585
Snippets:464
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install and use metap CLI tool

Source: https://scalameta.org/docs/semanticdb/guide.html

Install the metap command-line tool using 'cs install metap'. Use it to prettyprint .semanticdb files found in the provided classpath. Options control the prettyprinting format.

```bash
# downloads CLI tool based on org.scalameta.semanticdb-metap, version 4.17.0
cs install metap # if necessary
metap [options] <classpath>
```

--------------------------------

### Install metac and metap with Coursier

Source: https://scalameta.org/docs/semanticdb/guide.html

Installs the metac and metap command-line tools using the Coursier package manager. Ensure Coursier is installed first.

```bash
cs install metac metap
```

--------------------------------

### Install and Use Metac CLI Tool

Source: https://scalameta.org/docs/semanticdb/guide.html

Instructions for installing the metac command-line tool and its basic usage. Metac acts as a replacement for scalac for generating SemanticDB files.

```bash
# downloads CLI tool based on org.scalameta.metac, version 4.17.0
cs install metac # if necessary
metac [<pluginOption> ...] [<scalacOption> ...] [<sourceFile> ...]

```

--------------------------------

### AnnotationTree Examples

Source: https://scalameta.org/docs/semanticdb/specification.html

Provides examples of how AnnotationTree can represent various Java annotation syntaxes, from simple annotations to those with arguments and nested annotations.

```scala
AnnotationTree(TypeRef(None, <NoArgs#>, List()), None)
```

```scala
AnnotationTree(TypeRef(None, <StringArg#>, List()),         List(AssignTree(IdTree(<StringArg#value().>),           LiteralTree(StringConstant("arg")))))
```

```scala
AnnotationTree(TypeRef(None, <ArrayArg#>, List()),         List(AssignTree(IdTree(<ArrayArg#value().>),           ApplyTree(IdTree(<scala/Array#>), List())))
```

```scala
AnnotationTree(TypeRef(None, <EnumConstArg#>, List()),         List(AssignTree(IdTree(<EnumConstArg#value().>),           SelectTree(IdTree(<X#>), IdTree(<X#CONST.>))))
```

```scala
AnnotationTree(TypeRef(None, <Get#>, List()),         List(AssignTree(IdTree(<Get#route().>),           LiteralTree(StringConstant("/")))))
```

```scala
AnnotationTree(TypeRef(None, <A#>, List()),         List(AssignTree(IdTree(<A#value().>),           AnnotationTree(TypeRef(None, <B#>, List()),             None))))
```

--------------------------------

### Scala Program Example

Source: https://scalameta.org/docs/semanticdb/guide.html

A simple Scala object with a main method, used to demonstrate SemanticDB generation.

```scala
object Test {
  def main(args: Array[String]): Unit = {
    println("hello world")
  }
}
```

--------------------------------

### Scala Annotation Examples

Source: https://scalameta.org/docs/semanticdb/specification.html

Illustrates how various Scala annotations are represented using AnnotationTree. Note that expression annotations are not supported.

```scala
AnnotationTree(TypeRef(None, <NoArgs#>, List()), None)
```

```scala
AnnotationTree(TypeRef(None, <StringArg#>, List()), List(AssignTree(IdTree(<StringArg#value().>), LiteralTree(StringConstant("arg")))))
```

```scala
AnnotationTree(TypeRef(None, <ArrayArg#>, List()), List(AssignTree(IdTree(<ArrayArg#value().>), ApplyTree(IdTree(<scala/Array#>), List()))))
```

```scala
AnnotationTree(TypeRef(None, <EnumConstArg#>, List()), List(AssignTree(IdTree(<EnumConstArg#value().>), SelectTree(IdTree(<X#>), IdTree(<X#CONST.>))))
```

--------------------------------

### Access Modifier Examples

Source: https://scalameta.org/docs/semanticdb/specification.html

Illustrates how different Java access modifiers (private, protected, public) are represented using the Access protobuf messages. Notes unsupported Java constructs.

```text
`private F f;`
```

```text
`package x; class A {}`
```

```text
`protected F f;`
```

```text
`public F f;`
```

--------------------------------

### Scala Class Definition Example

Source: https://scalameta.org/docs/semanticdb/specification.html

Illustrates a Scala class definition with a method that uses a structural type, relevant for understanding hardlinking in SemanticDB.

```scala
class C {
  def m = new { def x: Int = ??? }
}

```

--------------------------------

### Scala Class and Constructor Declaration

Source: https://scalameta.org/docs/semanticdb/specification.html

Example of declaring a class with nested classes and constructors in Scala. This serves as a basis for symbol representation.

```scala
package a;
class Outer {
  Outer() {}
  class Inner {
    Inner() {}
  }
}

```

--------------------------------

### Parse Code with Comments Attached to Different Trees

Source: https://scalameta.org/docs/trees/examples.html

Illustrates how scalameta attaches comments to trees, showing an example where a comment can be accessible from both a value definition and a term name. This highlights the parser's logic for comment association.

```scala
val foo = bar // some comment


```

--------------------------------

### Get structure of a syntax tree

Source: https://scalameta.org/docs/trees/guide.html

Obtain the structural representation of an existing syntax tree node by calling the `.structure` method. This output can be safely copied and pasted into code to reconstruct the tree.

```scala
println("function(argument)".parse[Stat].get.structure)
```

--------------------------------

### Initialize Ammonite REPL with Scalameta

Source: https://scalameta.org/docs/trees/guide.html

Run the Ammonite REPL with the --thin option and import Scalameta to experiment with its features interactively.

```bash
$ amm --thin
Loading...
Welcome to the Ammonite Repl 2.3.8 (Scala 2.13.5 Java 11.0.7)
@ import $ivy.`org.scalameta::scalameta:4.17.0`, scala.meta._
```

--------------------------------

### Construct a simple function call with quasiquotes

Source: https://scalameta.org/docs/trees/guide.html

Use quasiquotes with `q"""` to construct code. The `.structure` method displays the resulting tree.

```scala
println(q"function(argument)".structure)
```

--------------------------------

### Parse Package to Source Tree

Source: https://scalameta.org/docs/trees/examples.html

Demonstrates parsing a package string into a Scalameta Source tree, showing the representation of a package declaration.

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

--------------------------------

### Inspect SemanticDB files with protoc

Source: https://scalameta.org/docs/semanticdb/guide.html

Use the protoc command-line tool with --decode or --decode_raw options to inspect SemanticDB protobuf payloads. This method is lower-level and metap is generally recommended.

```bash
$ tree
.
├── META-INF
│   └── semanticdb
│       └── Test.scala.semanticdb
└── Test.scala

$ protoc --proto_path <directory with the .proto file>\
--decode scala.meta.internal.semanticdb.TextDocuments\
semanticdb.proto < META-INF/semanticdb/Test.scala.semanticdb
```

```protobuf
documents {
  schema: SEMANTICDB4
  uri: "Test.scala"
  symbols {
    symbol: "_empty_/Test.main().(args)"
    kind: PARAMETER
    name: "args"
    access {
      publicAccess {
      }
    }
    language: SCALA
    signature {
      valueSignature {
        tpe {
          typeRef {
            symbol: "scala/Array#"
            type_arguments {
              typeRef {
                symbol: "scala/Predef.String#"
              }
            }
          }
        }
      }
    }
  }
  symbols {
    symbol: "_empty_/Test."
    kind: OBJECT
    properties: 8
... 
```

--------------------------------

### Define Range Structure

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents a range within a document using zero-based line and character offsets. The start point is inclusive, and the end point is exclusive.

```protobuf
message Range {
  int32 start_line = 1;
  int32 start_character = 2;
  int32 end_line = 3;
  int32 end_character = 4;
}

```

--------------------------------

### Print syntax tree to source code

Source: https://scalameta.org/docs/trees/guide.html

Convert a Scalameta syntax tree back into its original Scala source code representation using the `.syntax` method.

```scala
println(tree.syntax)
// object Main extends App { print("Hello!") }
```

--------------------------------

### Inspect SemanticDB file structure

Source: https://scalameta.org/docs/semanticdb/guide.html

Displays the directory structure after running metac, showing the generated .semanticdb file within the META-INF/semanticdb directory.

```bash
$ tree
.
├── META-INF
│   └── semanticdb
│       └── Test.scala.semanticdb
└── Test.scala
```

--------------------------------

### Scala Access Modifier Examples

Source: https://scalameta.org/docs/semanticdb/specification.html

Maps Scala access modifiers to their corresponding SemanticDB Access messages. Covers private, protected, and public access with 'this' and 'within' qualifiers.

```scala
PrivateAccess()
```

```scala
PrivateThisAccess()
```

```scala
PrivateWithinAccess()
```

```scala
ProtectedAccess()
```

```scala
ProtectedThisAccess()
```

```scala
ProtectedWithinAccess()
```

```scala
PublicAccess()
```

--------------------------------

### Parse virtual file with Sbt1 dialect

Source: https://scalameta.org/docs/trees/guide.html

Demonstrates parsing a virtual file with multiple top-level statements using the `dialects.Sbt1` dialect, similar to parsing a string directly.

```scala
println(
  dialects.Sbt1(
    Input.VirtualFile("build.sbt", buildSbt)
  ).parse[Source].get.stats
)
```

--------------------------------

### Import Scalameta

Source: https://scalameta.org/docs/trees/guide.html

Ensure this import is in your scope to use Scalameta's extension methods for parsing and other functionalities.

```scala
import scala.meta._
```

--------------------------------

### Init Quasiquote

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent initialization of classes or traits using `init"$tpe(...$exprss)"` or `init"this(...$exprss)"`. `exprss` is a comma-separated list of expressions.

```scala
init"$tpe(...$exprss)"
init"this(...$exprss)"
```

--------------------------------

### Parse and display SemanticDB with metap

Source: https://scalameta.org/docs/semanticdb/guide.html

Uses the metap command-line tool to prettyprint the contents of a .semanticdb file. This tool helps in understanding the semantic information stored in the protobuf payload.

```bash
$ metap .
Test.scala
----------

Summary:
Schema => SemanticDB v4
Uri => Test.scala
Text => empty
Language => Scala
Symbols => 3 entries
Occurrences => 7 entries

Symbols:
_empty_/Test. => final object Test extends AnyRef { +1 decls }
_empty_/Test.main(). => method main(args: Array[String]): Unit
_empty_/Test.main().(args) => param args: Array[String]

Occurrences:
[0:7..0:11) <= _empty_/Test.
[1:6..1:10) <= _empty_/Test.main().
[1:11..1:15) <= _empty_/Test.main().(args)
[1:17..1:22) => scala/Array#
[1:23..1:29) => scala/Predef.String#
[1:33..1:37) => scala/Unit#
[2:4..2:11) => scala/Predef.println(+1).

```

--------------------------------

### Define build.sbt content

Source: https://scalameta.org/docs/trees/guide.html

Define a string containing the content of a build.sbt file with multiple top-level statements.

```scala
val buildSbt = """
val core = project
val cli = project.dependsOn(core)
"""
```

--------------------------------

### Generate SemanticDB with metac

Source: https://scalameta.org/docs/semanticdb/guide.html

Uses the metac command-line tool to generate .semanticdb files for a given Scala source file. Metac acts as a wrapper around the Scala compiler.

```bash
metac Test.scala
```

--------------------------------

### Import Quasiquote

Source: https://scalameta.org/docs/trees/quasiquotes.html

Construct or deconstruct import statements in Scala.

```scala
q"import ..$importersnel"
```

--------------------------------

### Expression Quasiquotes: New

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent `new` expressions for creating instances of classes using `q"new $init"`. `$init` refers to an `Init` quasiquote.

```scala
q"new $init"
```

--------------------------------

### Comparing Scalameta Trees for Equality

Source: https://scalameta.org/docs/trees/guide.html

Understand that scalameta trees use reference equality by default (`==`). Use pattern matching or `.structure` for structural equality. For efficiency, consider `isEqual` from `scala.meta.contrib`.

```scala
"true".parse[Term].get == q"true"
// res27: Boolean = false
```

```scala
q"true" == q"true"
// res28: Boolean = false
```

```scala
{ val treeReference = q"true"
  treeReference == treeReference }
// res29: Boolean = true
```

```scala
q"true" match { case q"true" => println("YAY!") }
// YAY!
```

```scala
q"true".structure == q"true".structure
// res31: Boolean = true
```

```scala
import scala.meta.contrib._
q"true".isEqual(q"true")
// res32: Boolean = true
```

--------------------------------

### Pattern Matching and Variable Declarations in Scala

Source: https://scalameta.org/docs/semanticdb/specification.html

Illustrates how pattern variables in matching expressions and pattern definitions are represented as symbols.

```scala
class C {
  ??? match { case List(x) => ??? }
  val List(xval) = ???
  var List(xvar) = ???
}

```

--------------------------------

### Print virtual file syntax tree

Source: https://scalameta.org/docs/trees/guide.html

Prints the syntax tree obtained from parsing a virtual file. The output reflects the structure of the Scala code within that file.

```scala
print(exampleTree.syntax)
// object Example extends App {
//   println("Hello from a file!")
// }
```

--------------------------------

### Scalac Plugin Options Format

Source: https://scalameta.org/docs/semanticdb/guide.html

The format for passing options to the semanticdb-scalac plugin via scalac. Options are prefixed with -P:semanticdb:.

```bash
-P:semanticdb:<option>:<value>

```

--------------------------------

### ApplyTree Message Definition

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents a method application with a function and a list of arguments.

```protobuf
message ApplyTree {
  Tree function = 1;
  repeated Tree arguments = 2;
  int32 properties = 3; // bitmask of SymbolInformation.Property
}
```

--------------------------------

### View .semanticdb file content with xxd

Source: https://scalameta.org/docs/semanticdb/guide.html

Displays the raw hexadecimal content of a .semanticdb file using the xxd utility. These files contain protobuf payloads.

```bash
$ xxd META-INF/semanticdb/Test.scala.semanticdb
00000000: 0aaa 0408 0412 0a54 6573 742e 7363 616c  .......Test.scal
00000010: 612a 580a 1a5f 656d 7074 795f 2f54 6573  a*X.._empty_/Tes
00000020: 742e 6d61 696e 2829 2e28 6172 6773 2918  t.main().(args).
00000030: 082a 0461 7267 7380 0101 8a01 2e22 2c0a  .*.args......",.
00000040: 2a12 2812 0c73 6361 6c61 2f41 7272 6179  *.(..scala/Array
00000050: 231a 1812 1612 1473 6361 6c61 2f50 7265  #......scala/Pre
00000060: 6465 662e 5374 7269 6e67 232a 530a 0d5f  def.String#*S.._
00000070: 656d 7074 795f 2f54 6573 742e 180a 2008  empty_/Test... .
00000080: 2a04 5465 7374 8001 018a 012f 0a2d 0a00  *.Test...../.-..
00000090: 1211 120f 120d 7363 616c 612f 416e 7952  ......scala/AnyR
000000a0: 6566 2322 160a 145f 656d 7074 795f 2f54  ef#".._empty_/T
000000b0: 6573 742e 6d61 696e 2829 2e92 0102 3a00  est.main()....:.
000000c0: 2a5c 0a14 5f65 6d70 7479 5f2f 5465 7374  *\.._empty_/Test
...
```

--------------------------------

### Member Quasiquotes: Def Definition

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent `def` definitions using `q"..$mods def $ename[..$tparams](...$paramss): $tpeopt = $expr"`. `mods` are modifiers, `ename` is the name, `tparams` are type parameters, `paramss` are parameter lists, `tpeopt` is an optional return type, and `expr` is the body.

```scala
q"..$mods def $ename[..$tparams](...$paramss): $tpeopt = $expr"
```

--------------------------------

### By-Name and Repeated Type Definitions

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents signatures for by-name parameters and repeated parameters.

```protobuf
message ByNameType {
  Type tpe = 1;
}

message RepeatedType {
  Type tpe = 1;
}

```

--------------------------------

### Construct a Term Name with Comments

Source: https://scalameta.org/docs/trees/examples.html

Shows how to create a `Term.Name` with leading comments using `createWithComments`. This is useful for programmatically generating code elements with associated comments.

```scala
Term.Name.createWithComments(
  "identifier",
  begComment = Some(Tree.Comments(List(
    Tree.Comment(List(Lit.String("/* comment */")))
  ))),
  endComment = None // default
)

```

--------------------------------

### Type Declarations and Aliases in Scala

Source: https://scalameta.org/docs/semanticdb/specification.html

Demonstrates the representation of type declarations and type aliases as TYPE symbols in SemanticDB.

```scala
class C {
  type T1 <: Hi
  type T2 >: Lo
  type T = Int
}

```

--------------------------------

### Simple Tree Transformation with .transform

Source: https://scalameta.org/docs/trees/guide.html

Use the .transform method to visit and transform specific tree nodes. Be cautious of infinite recursion, as .transform recursively visits transformed trees.

```scala
println(
  q"val x = 2".transform { case q"2" => q"42" }
)
// val x = 42
```

```scala
q"a + b".transform {
  case name @ Term.Name.Initial("b") => q"function($name)"
}.toString
// [error] java.lang.StackOverflowError
// at scala.meta.transversers.Api$XtensionCollectionLikeUI$transformer$2$.apply(Api.scala:10)
// at scala.meta.transversers.Transformer.apply(Transformer.scala:4)
```

--------------------------------

### Construct a Null Literal with Comments

Source: https://scalameta.org/docs/trees/examples.html

Demonstrates constructing a `Lit.Null` tree with explicit leading and trailing comments using `createWithComments`. This is useful for programmatically generating code with comments.

```scala
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")))
  )))
)

```

--------------------------------

### Implicit Parameter: CanBuildFrom

Source: https://scalameta.org/docs/semanticdb/specification.html

Illustrates the synthetic for an inferred implicit parameter, specifically canBuildFrom.

```scala
List(1).map(_ + 2)
```

```scala
Synthetic(
  <List(1).map(_ + 2)>,
  ApplyTree(
    OriginalTree(<List(1).map(_ + 2)>),
    List(
      TypeApplyTree(
        IdTree(<List.canBuildFrom>),
        List(TypeRef(None, <Int>, List()))))))

```

--------------------------------

### Member Quasiquotes: Package Definition

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent `package` definitions using `q"package $eref { ..$stats }"`. `eref` is the package reference, and `stats` is a sequence of statements.

```scala
q"package $eref { ..$stats }"
```

--------------------------------

### Construct multiline code with quasiquotes

Source: https://scalameta.org/docs/trees/guide.html

Multiline quasiquotes allow for the construction of larger code structures like objects and applications.

```scala
println(
  q"""
  object Example extends App {
    println(42)
  }
  ".structure
)
```

--------------------------------

### Parse Scala code from a virtual file

Source: https://scalameta.org/docs/trees/guide.html

Recommended approach for parsing code, especially when dealing with files. It involves reading file content into a string and then creating an `Input.VirtualFile` for better error reporting.

```scala
val path = java.nio.file.Paths.get("docs", "example.scala")
val bytes = java.nio.file.Files.readAllBytes(path)
val text = new String(bytes, "UTF-8")
val input = Input.VirtualFile(path.toString, text)
val exampleTree = input.parse[Source].get
```

--------------------------------

### Type Reference Definition

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents a reference to a Symbol, potentially parameterized. Includes a prefix to model nested type definitions.

```protobuf
message TypeRef {
  Type prefix = 1;
  string symbol = 2;
  repeated Type type_arguments = 3;
}

```

--------------------------------

### Quasiquote Comment Handling

Source: https://scalameta.org/docs/trees/quasiquotes.html

Demonstrates how to include scaladoc and inline comments within scalameta quasiquotes. Interpolated comments must be passed as Scala strings.

```scala
val scaladoc = q"""
  "some scaladoc string"
"""
val comment = q
```

```scala
"some comment string""
val tree = q"""
  /** $scaladoc */
  val foo = bar // $comment
"""

```

--------------------------------

### sbt Integration for SemanticDB

Source: https://scalameta.org/docs/semanticdb/guide.html

Configuration for enabling the semanticdb-scalac compiler plugin in an sbt project. Requires adding the plugin and enabling the -Yrangepos compiler option.

```scala
addCompilerPlugin("org.scalameta" % "semanticdb-scalac" % "4.17.0" cross CrossVersion.full)
scalacOptions += "-Yrangepos"

```

--------------------------------

### Attempt to parse expression as Source

Source: https://scalameta.org/docs/trees/guide.html

Demonstrates that parsing a simple expression like `a + b` with `parse[Source]` results in an error because it's not a valid top-level Scala program structure.

```scala
println("a + b".parse[Source])
// <input>:1: error: illegal start of definition `identifier`
// a + b
// ^
```

--------------------------------

### Source Quasiquote

Source: https://scalameta.org/docs/trees/quasiquotes.html

Construct or deconstruct a Scala source file, typically containing a list of statements.

```scala
source"..$stats"
```

--------------------------------

### Define Location Structure

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents a location within a document, combining a URI and a Range. Corresponds to LSP's Location.

```protobuf
message Location {
  string uri = 1;
  Range range = 2;
}

```

--------------------------------

### Pattern Quasiquotes: Bind

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent binding patterns (e.g., `name @ pattern`) using `p"$pat @ $pat"`.

```scala
p"$pat @ $pat"
```

--------------------------------

### Using Versioned Matchers for Tree Evolution

Source: https://scalameta.org/docs/trees/guide.html

Use versioned matchers like `.Initial` and `.After_x_y_z` to handle evolving tree structures. This ensures compatibility with different versions of tree fields.

```scala
"function(arg1, arg2)".parse[Term].get match {
  case Term.Apply.Initial(function, List(arg1, arg2)) =>
    println("1 " + function)
    println("2 " + arg1)
    println("3 " + arg2)
}
// 1 function
// 2 arg1
// 3 arg2
```

```scala
"function(using arg1, arg2)".parse[Term].get match {
  case Term.Apply.After_4_6_0(function, Term.ArgClause.Initial(List(arg1, arg2), mod)) =>
    println("1 " + function)
    println("2 " + arg1)
    println("3 " + arg2)
    println("4 " + mod)
}
// 1 function
// 2 arg1
// 3 arg2
// 4 Some(using)
```

--------------------------------

### Parse Infix Operation to Term Tree

Source: https://scalameta.org/docs/trees/examples.html

Demonstrates parsing an infix arithmetic operation into a Scalameta Term.ApplyInfix tree.

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

--------------------------------

### Pattern Matching with Quasiquotes

Source: https://scalameta.org/docs/trees/guide.html

Leverage quasiquotes for pattern matching on code structures. Use `...$` for curried argument lists and `$_` to ignore specific modifiers.

```scala
Term.Apply(
  Term.Name("function"),
  List(Term.Name("arg1"), Term.Name("arg2"))
) match {
  case q"$function(..$args)" =>
    println("1 " + function)
    println("2 " + args)
}
// 1 function
// 2 (arg1, arg2)
```

```scala
"function(arg1, arg2)(arg3, arg4)".parse[Term].get match {
  case q"$function(...$args)" =>
    println("1 " + function)
    println("2 " + args)
}
// 1 function
// 2 List((arg1, arg2), (arg3, arg4))
```

```scala
q"final val x = 2" match {
  case q"val x = 2" => // boom!
}
// scala.MatchError: final val x = 2 (of class scala.meta.Defn$Val$DefnValImpl)
//  at repl.MdocSession$MdocApp$$anonfun$5.apply(guide.md:282)
```

```scala
q"final val x = 2" match {
  case q"$_ val x = 2" => println("OK")
}
// OK
```

--------------------------------

### Construct Apply term dynamically

Source: https://scalameta.org/docs/trees/guide.html

Dynamically construct a syntax tree representing a function application using normal constructors. This is useful for programmatically generating code structures.

```scala
println(Term.Apply(Term.Name("function"), List(Term.Name("argument"))))
```

--------------------------------

### Pattern Quasiquotes: Var

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent variable patterns using `p"<name>"`.

```scala
p"<name>"
```

--------------------------------

### Member Quasiquotes: Primary Constructor

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent primary constructor definitions using `q"..$mods def this(...$paramss)"`. `mods` are modifiers, and `paramss` are parameter lists.

```scala
q"..$mods def this(...$paramss)"
```

--------------------------------

### Define MethodSignature Message

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents signatures for methods, constructors, and macros. It supports multiple parameter lists, type parameters, return types, and thrown types.

```protobuf
message MethodSignature {
  Scope type_parameters = 1;
  repeated Scope parameter_lists = 2;
  Type return_type = 3;
  repeated Type throws = 4;
}

```

--------------------------------

### Define Language Enum

Source: https://scalameta.org/docs/semanticdb/specification.html

Enumerates supported programming languages for SemanticDB entities. Currently includes Scala and Java.

```protobuf
enum Language {
  UNKNOWN_LANGUAGE = 0;
  SCALA = 1;
  JAVA = 2;
}

```

--------------------------------

### TypeApplyTree Message Definition

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents the type application of a method with type arguments.

```protobuf
message TypeApplyTree {
  Tree function = 1;
  repeated Type type_arguments = 2;
}
```

--------------------------------

### Insert curried argument lists with `...$`

Source: https://scalameta.org/docs/trees/guide.html

Use `...$listOfLists` to splice multiple lists of trees, representing curried function arguments, into a quasiquote.

```scala
val arguments2 = List(q"arg3", q"arg4")
val allArguments = List(arguments, arguments2)
println(q"function(...$allArguments)")
```

--------------------------------

### Expression Quasiquotes: New Anonymous

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent anonymous class instantiations with initializers and parents using `q"new { ..$stat } with ..$inits { $self => ..$stats }"`.

```scala
q"new { ..$stat } with ..$inits { $self => ..$stats }"
```

--------------------------------

### Parse build.sbt with Sbt1 dialect

Source: https://scalameta.org/docs/trees/guide.html

Use the `dialects.Sbt1` dialect to successfully parse a string containing multiple top-level statements, such as those found in build.sbt files. This returns a list of the parsed statements.

```scala
println(dialects.Sbt1(buildSbt).parse[Source].get.stats)
```

--------------------------------

### Scala Class Symbol Representation

Source: https://scalameta.org/docs/semanticdb/specification.html

Illustrates how a Scala class with constructor parameters and members is represented in SemanticDB, showing the symbols, kinds, and signatures for each element.

```scala
abstract class C(val xp: Int) {
  val xm: Int = ???
  val xam: Int
  private[this] val xlm: Int = ???
  def m = {
    val xl: Int = ???
    type S = { val xs: Int }
    type E = xe.type forSome { val xe: AnyRef }
  }
}

```

--------------------------------

### Define Compile-Time Constants

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents compile-time constants including primitive types, strings, and null. Used for values known at compile time.

```protobuf
message Constant {
  oneof sealed_value {
    UnitConstant unit_constant = 1;
    BooleanConstant boolean_constant = 2;
    ByteConstant byte_constant = 3;
    ShortConstant short_constant = 4;
    CharConstant char_constant = 5;
    IntConstant int_constant = 6;
    LongConstant long_constant = 7;
    FloatConstant float_constant = 8;
    DoubleConstant double_constant = 9;
    StringConstant string_constant = 10;
    NullConstant null_constant = 11;
  }
}

message UnitConstant {
}

message BooleanConstant {
  bool value = 1;
}

message ByteConstant {
  int32 value = 1;
}

message ShortConstant {
  int32 value = 1;
}

message CharConstant {
  int32 value = 1;
}

message IntConstant {
  int32 value = 1;
}

message LongConstant {
  int64 value = 1;
}

message FloatConstant {
  float value = 1;
}

message DoubleConstant {
  double value = 1;
}

message StringConstant {
  string value = 1;
}

message NullConstant {
}

```

--------------------------------

### Representing Type Parameters in Scala

Source: https://scalameta.org/docs/semanticdb/specification.html

Demonstrates the declaration of type parameters, including those with bounds and higher-order type parameters, and their representation using `TYPE_PARAMETER` symbols. Supported properties include `COVARIANT` and `CONTRAVARIANT`.

```scala
class C[T1] {
  def m[T2[T3] <: Hi] = ???
  type T[T4 >: Lo] = ???
}
```

--------------------------------

### Scalac Compiler Plugin Usage

Source: https://scalameta.org/docs/semanticdb/guide.html

How to invoke the scalac compiler with the semanticdb-scalac plugin. Ensure -Yrangepos is enabled for the plugin to function correctly.

```bash
scalac -Xplugin:path/to.jar -Yrangepos [<pluginOption> ...] [<scalacOption> ...] [<sourceFile> ...]

```

--------------------------------

### Expression Quasiquotes: Application

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent method or function applications in expressions using `q"$expr(...$exprss)"`. The `exprss` part represents a comma-separated list of expressions.

```scala
q"$expr(...$exprss)"
```

--------------------------------

### Primitive Type Representation

Source: https://scalameta.org/docs/semanticdb/specification.html

Illustrates how primitive Java types are mapped to ScalaMeta TypeRef representations.

```scala
  * `byte` ~ `TypeRef(None, <scala/Byte#>, List())`.
  * `short` ~ `TypeRef(None, <scala/Short#>, List())`.
  * `int` ~ `TypeRef(None, <scala/Int#>, List())`.
  * `long` ~ `TypeRef(None, <scala/Long#>, List())`.
  * `char` ~ `TypeRef(None, <scala/Char#>, List())`.
  * `float` ~ `TypeRef(None, <scala/Float#>, List())`.
  * `double` ~ `TypeRef(None, <scala/Double#>, List())`.
  * `boolean` ~ `TypeRef(None, <scala/Boolean#>, List())`.
  * `void` ~ `TypeRef(None, <scala/Unit#>, List())`.

```

--------------------------------

### Parse and Structure a Pattern Alternative

Source: https://scalameta.org/docs/trees/examples.html

Parses a string representing a pattern alternative and shows its structured representation. Useful for analyzing complex pattern matching logic.

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

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

--------------------------------

### Representing Parameters in Scala

Source: https://scalameta.org/docs/semanticdb/specification.html

Shows various ways parameters are declared in Scala classes and methods, including value parameters, default parameters, by-name parameters, repeated parameters, context bounds, and view bounds. These are represented by `PARAMETER` symbols.

```scala
class C(p1: Int) {
  def m2(p2: Int) = ???
  def m3(p3: Int = 42) = ???
  def m4(p4: => Int) = ???
  def m5(p5: Int*) = ???
  def m6[T: C <% V] = ???
}
```

--------------------------------

### Scala Macro Definition

Source: https://scalameta.org/docs/semanticdb/specification.html

Shows a basic macro definition within a Scala object, using a macro implementation.

```scala
object M {
  def m: Int = macro impl
}

```

--------------------------------

### Parse Value Definition to Tree

Source: https://scalameta.org/docs/trees/examples.html

Illustrates parsing a value definition with an assigned literal into a Scalameta Defn.Val tree.

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

--------------------------------

### Insert lists of trees with `..$`

Source: https://scalameta.org/docs/trees/guide.html

Use `..$listName` to splice a list of trees into a quasiquote, typically for arguments or body elements.

```scala
val arguments = List(q"arg1", q"arg2")
println(q"function(..$arguments)")
```

--------------------------------

### With Type Definition

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents a Scala-like compound type based on a list of types. Order matters, unlike intersection types.

```protobuf
message WithType {
  repeated Type types = 1;
}

```

--------------------------------

### Expression Quasiquotes: Do While

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent `do-while` loops using `q"do $expr while($expr)"`. Note the semicolon is optional.

```scala
q"do $expr while($expr)"
```

--------------------------------

### Expression Quasiquotes: Try

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent `try-catch-finally` expressions using `q"try $expr catch { ..case $cases } finally $expropt"`. `cases` is a sequence of case clauses, and `expropt` is an optional expression.

```scala
q"try $expr catch { ..case $cases } finally $expropt"
```

--------------------------------

### SelectTree Message Definition

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents a method or field selection on a qualifier.

```protobuf
message SelectTree {
  Tree qualifier = 1;
  IdTree id = 2;
}
```

--------------------------------

### Singleton Type Definition

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents a singleton type inhabited by a specific value. Includes definitions for 'this' and 'super' references.

```protobuf
message SingleType {
  Type prefix = 1;
  string symbol = 2;
}

message ThisType {
  string symbol = 1;
}

message SuperType {
  Type prefix = 1;
  string symbol = 2;
}

```

--------------------------------

### Scala Definition to Symbol Mapping

Source: https://scalameta.org/docs/semanticdb/specification.html

Provides a table mapping Scala definitions within a class to their corresponding SemanticDB symbols, kinds, and signatures. This is useful for understanding how code elements are identified.

```scala
**Definition** | **Symbol** | **Kind** | **Signature**  
---|---|---|---
`xp` | `_empty_/C#xp().` | `METHOD` | `MethodSignature(List(), List(), TypeRef(None, <Int>, List()), List())`  
`xp` | `_empty_/C#`<init>`().(xp)` | `PARAMETER` | `ValueSignature(TypeRef(None, <Int>, List()))`  
`xm` | `_empty_/C#xm().` | `METHOD` | `MethodSignature(List(), List(), TypeRef(None, <Int>, List()), List())`  
`xam` | `_empty_/C#xam().` | `METHOD` | `MethodSignature(List(), List(), TypeRef(None, <Int>, List()), List())`  
`xlm` | `_empty_/C#xlm().` | `METHOD` | `MethodSignature(List(), List(), TypeRef(None, <Int>, List()), List())`  
`xl` | `local0` | `LOCAL` | `ValueSignature(TypeRef(None, <Int>, List()))`  
`xs` | `local1` | `METHOD` | `MethodSignature(List(), List(), TypeRef(None, <Int>, List()), List())`  
`xe` | `local2` | `METHOD` | `ValueSignature(TypeRef(None, <Int>, List()))`
```

--------------------------------

### Sbt1 dialect limitations with package declarations

Source: https://scalameta.org/docs/trees/guide.html

The `dialects.Sbt1` dialect does not accept programs that include package declarations. Attempting to parse such code will not produce the expected output.

```scala
println(
  dialects.Sbt1("package library; object Main").parse[Source]
)
```

--------------------------------

### Expression Quasiquotes: Infix Application

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent infix operations in expressions. Supports both `q"$expr $ename[..$tpes] $expr"` and `q"$expr $ename[..$tpes] (..$exprs)"` forms.

```scala
q"$expr $ename[..$tpes] $expr"
q"$expr $ename[..$tpes] (..$exprs)"
```

--------------------------------

### Pattern Quasiquotes: Alternative

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent alternative patterns (e.g., `A | B`) using `p"$pat | $pat"`.

```scala
p"$pat | $pat"
```

--------------------------------

### Java Package Symbol Format

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents the symbol format for Java packages, including the root, unnamed, and top-level packages.

```text
java/
```

--------------------------------

### MacroExpansionTree Message Definition

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents a macro expansion, potentially including the code before expansion.

```protobuf
message MacroExpansionTree {
  Tree before_expansion = 1;
  Type tpe = 2;
}
```

--------------------------------

### Inferred Method Call: List UnapplySeq

Source: https://scalameta.org/docs/semanticdb/specification.html

Illustrates the synthetic for a pattern match on List using unapplySeq.

```scala
val List(a, b) = ...
```

```scala
Synthetic(
  <List>,
  TypeApplyTree(
    SelectTree(
      OriginalTree(<List>),
      Some(IdTree(<SeqFactory.unapplySeq>))),
    List(TypeRef(None, <Nothing>, List()))))

```

--------------------------------

### Parse string with syntax error

Source: https://scalameta.org/docs/trees/guide.html

Demonstrates how parsing a string with a syntax error results in an error message without a filename. Use `Input.VirtualFile` for more helpful error reporting.

```scala
println(
  "object Main {".parse[Source]
)
// <input>:1: error: `}` expected but `end of file` found
// object Main {
//              ^
```

--------------------------------

### Importer Quasiquote

Source: https://scalameta.org/docs/trees/quasiquotes.html

Define an importer for a specific reference, including a list of imported members.

```scala
importer"$eref.{..$importeesnel}"
```

--------------------------------

### Parse and Structure a Null Literal

Source: https://scalameta.org/docs/trees/examples.html

Parses the string 'null' and shows its scalameta representation as `Lit.Null()`. This demonstrates how basic literals are handled.

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

Lit.Null()

```

--------------------------------

### Define Access messages

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents access modifiers for definitions, including private, protected, and public variants, with options for instance-specific or symbol-limited access.

```protobuf
message Access {
  oneof sealed_value {
    PrivateAccess private_access = 1;
    PrivateThisAccess private_this_access = 2;
    PrivateWithinAccess private_within_access = 3;
    ProtectedAccess protected_access = 4;
    ProtectedThisAccess protected_this_access = 5;
    ProtectedWithinAccess protected_within_access = 6;
    PublicAccess public_access = 7;
  }
}

message PrivateAccess {
}

message PrivateThisAccess {
}

message PrivateWithinAccess {
  string symbol = 1;
}

message ProtectedAccess {
}

message ProtectedThisAccess {
}

message ProtectedWithinAccess {
  string symbol = 1;
}

message PublicAccess {
}

```

--------------------------------

### Member Quasiquotes: Secondary Constructor

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent secondary constructor definitions using `q"..$mods def this(...$paramss) = $expr"`. `mods` are modifiers, `paramss` are parameter lists, and `expr` is the body.

```scala
q"..$mods def this(...$paramss) = $expr"
```

--------------------------------

### Member Quasiquotes: Macro Definition

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent macro definitions using `q"..$mods def $ename[..$tparams](...$paramss): $tpeopt = macro $expr"`.

```scala
q"..$mods def $ename[..$tparams](...$paramss): $tpeopt = macro $expr"
```

--------------------------------

### Pattern Quasiquotes: Literal

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent literal patterns using `p"<lit>"`.

```scala
p"<lit>"
```

--------------------------------

### Add semanticdb-shared dependency

Source: https://scalameta.org/docs/semanticdb/guide.html

Add the semanticdb-shared library to your project dependencies to use ScalaPB bindings for the SemanticDB protobuf schema.

```scala
libraryDependencies += "org.scalameta" %% "semanticdb-shared" % "4.17.0"
```

--------------------------------

### Parse Value Declaration to Tree

Source: https://scalameta.org/docs/trees/examples.html

Shows how a value declaration with a type annotation is parsed into a Scalameta Decl.Val tree.

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

--------------------------------

### Parse build.sbt with default dialect (error)

Source: https://scalameta.org/docs/trees/guide.html

Attempting to parse a string with multiple top-level statements using the default dialect results in an error, as vals are not allowed at the top level in standard Scala programs.

```scala
println(buildSbt.parse[Source])
```

--------------------------------

### Class Declaration Representation in SemanticDB

Source: https://scalameta.org/docs/semanticdb/specification.html

Illustrates how a Java class declaration is represented as a SemanticDB symbol. This includes the class itself, its fields, methods, and nested classes, along with their respective kinds and signatures.

```java
package a;
class C extends S1 implements I {
  T1 m1;
  static T2 m2();
  zero.Overload m3;
  T3 m3(one.Overload e1);
  static T4 m3(two.Overload e2);
  T5 m3(three.Overload e3);
  static class D1<T6 extends S2 & S3, T7> { }
  class D2 { }
}

```

--------------------------------

### Existential and Universal Type Definitions

Source: https://scalameta.org/docs/semanticdb/specification.html

Defines types that are existentially or universally quantified over declarations or type parameters.

```protobuf
message ExistentialType {
  reserved 2;
  Type tpe = 1;
  Scope declarations = 3;
}

message UniversalType {
  reserved 1;
  Scope type_parameters = 3;
  Type tpe = 2;
}

```

--------------------------------

### Scala Class Method Declarations

Source: https://scalameta.org/docs/semanticdb/specification.html

Illustrates various method declarations within an abstract Scala class, including overloaded methods and value definitions.

```scala
abstract class C {
  def m1: Int = ???
  def m2(): Int = ???
  object m3
  def m3(x: Int): Int = ???
  def m3(x: org.Int): Int = ???
  val m4: Int
  def m4(x: Int)(y: Int): Int = ???
}

```

--------------------------------

### Member Quasiquotes: Package Object Definition

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent `package object` definitions using `q"package object $ename $template"`. `template` can be an `extends` clause or a block.

```scala
q"package object $ename $template"
```

--------------------------------

### Constant Type Definition

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents a singleton type inhabited by a Constant value.

```protobuf
message ConstantType {
  Constant constant = 1;
}

```

--------------------------------

### Raw Type Representation

Source: https://scalameta.org/docs/semanticdb/specification.html

Shows the ScalaMeta representation for raw types in Java.

```scala
  * `C` ~ `TypeRef(None, <C>, List())`.

```

--------------------------------

### Traversing Scalameta Trees with .traverse

Source: https://scalameta.org/docs/trees/guide.html

Use the `.traverse` method to visit every node in a tree and perform a side-effect, similar to `.foreach`. This method does not support customizing recursion.

```scala
q"val x = 2".traverse {
  case node =>
    println(s"${node.productPrefix}: $node")
}
// Defn.Val: val x = 2
// Pat.Var: x
// Term.Name: x
// Lit.Int: 2
```

--------------------------------

### Parse Scala expression with virtual file for error reporting

Source: https://scalameta.org/docs/trees/guide.html

Parsing using `Input.VirtualFile` includes the filename in error messages, making debugging easier compared to parsing directly from strings.

```scala
println(
  Input.VirtualFile("example.scala", "object Main {").parse[Source]
)
// example.scala:1: error: `}` expected but `end of file` found
// object Main {
//              ^
```

--------------------------------

### Implicit View/Conversion: Augment String

Source: https://scalameta.org/docs/semanticdb/specification.html

Shows the synthetic for an implicit view conversion, such as augmentString.

```scala
"fooo".stripPrefix("o")
```

```scala
Synthetic(
  <"fooo">,
  ApplyTree(
    IdTree(<Predef.augmentString>),
    List(OriginalTree(<"fooo">))))

```

--------------------------------

### Parse and Structure a Case Statement

Source: https://scalameta.org/docs/trees/examples.html

Parses a string representing a simple case statement and displays its structured form. This is helpful for understanding how scalameta represents case clauses.

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

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

```

--------------------------------

### OriginalTree Message Definition

Source: https://scalameta.org/docs/semanticdb/specification.html

Represents a quote from the original source text, identified by a range.

```protobuf
message OriginalTree {
  Range range = 1;
}
```

--------------------------------

### Pattern Quasiquotes: Wildcard

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent the wildcard pattern `_` using `p"_"`.

```scala
p"_"
```

--------------------------------

### Type Quasiquotes: Infix Application

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent infix type operations (e.g., `A with B`) using `t"$tpe $tname $tpe"`.

```scala
t"$tpe $tname $tpe"
```

--------------------------------

### Pattern Quasiquotes: Sequence Wildcard

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent a wildcard for a sequence of elements using `p"_*"`.

```scala
p"_*"
```

--------------------------------

### Expression Quasiquotes: Return

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent the `return` statement in expressions using `q"return $expr"`.

```scala
q"return $expr"
```

--------------------------------

### Parse Scala code from a string

Source: https://scalameta.org/docs/trees/guide.html

Use the `parse[Source]` extension method to convert a Scala code string into a syntax tree. The `.get` method is used here for simplicity, but error handling should be considered in production code.

```scala
val program = """object Main extends App { print("Hello!") }"""
val tree = program.parse[Source].get
```

--------------------------------

### Expression Quasiquotes: Match

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent `match` expressions using `q"$expr match { ..case $casesnel }"`. `casesnel` is a sequence of case clauses.

```scala
q"$expr match { ..case $casesnel }"
```

--------------------------------

### Expression Quasiquotes: Eta Expansion

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent eta expansion (e.g., `func _`) using `q"$expr _"`.

```scala
q"$expr _"
```

--------------------------------

### Type Quasiquotes: With

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent compound types using the `with` keyword, e.g., `t"$tpe with $tpe"`. Support depends on the dialect.

```scala
t"$tpe with $tpe"
```

--------------------------------

### Expression Quasiquotes: Type Application

Source: https://scalameta.org/docs/trees/quasiquotes.html

Represent type applications (e.g., `list[Int]`) in expressions using `q"$expr[..$tpesnel]"`. `tpesnel` represents a comma-separated list of types.

```scala
q"$expr[..$tpesnel]"
```
Tokens:
Raw