- How to use
- Motivation and Features
- Binary and source compatibility guarantees
- Contributions and issues
Replace the X with the Scala 3 minor version you are using, then add this to
your build.sbt (notice the single percent sign):
libraryDependencies += "org.felher" % "s3te-compile_3.X" % "0.0.2" % Compileand then call org.felher.s3te.S3te.renderTreeHTML("/tmp/out.html", expr.asTerm)
in your macro to generate a tree of the expression expr in the file
/tmp/out.html.
Replace the X with the Scala 3 minor version you are using, then add this to
your build.sbt (notice the single percent sign):
libraryDependencies += "org.felher" % "s3te-compile_3.X" % "0.0.2" % CompileIf you are using Scala 3.5.2, X should be 5.
Tip
You should be able to user an older versions of this library to inspect code of a newer Scala version, though some new stuff added to Scala in the meantime might not show up. So if s3te is not yet published for your cutting-edge Scala version, try the minor version of Scala release before that.
The reverse is not true, though. You can't use a newer version of this library with an older version of Scala, which means, currently, s3te is only supported on Scala 3.3+.
Then create a macro in a new file like this:
import scala.quoted.*
object MyMacro:
inline def myMacro(inline a: Any): Any = ${ myMacroImpl('a) }
def myMacroImpl(a: Expr[Any])(using Quotes): Expr[Any] =
import quotes.reflect.*
org.felher.s3te.S3te.renderTreeHTML("/tmp/tree.html", a.asTerm)
'{ null }and then call your macro in another file with the tree you want to explore:
object MyMain:
def main(): Unit =
MyMacro.myMacro:
// your code here
val a = 3
val b = 4
a + bThen compile your code in SBT. You should now be able to browse the HTML file
in your browser using file:///tmp/tree.html as the U
72C1
RL.
Here is a quick list of the features of s3te:
- hover over code to highlight associated tree (and vice versa)
- click on code to scroll tree into view (and vice versa)
- click multiple times to select successively larger spans of code or trees
- drill into part of the tree by clicking the "tree" icon right of the name of a node
- collapse/expand parts of the tree by clicking the arrow icon left of the name of a node
- hover over the name of a node on the tree to show a small description (short scaladocs)
- click on the info icon right of the name of a node to show a detailed description of the node, including:
- larger description (large scaldocs)
- overview of the type hierarchy of the node in question
- links to all the scala docs (methods and modules) for any node in the hierarchy, including the node in question
- view the symbol, as well as all the flags of the symbol, with a description of each flag
- view the type of the node (TypeRepr from .tpe) if it has an associated type, including cycle detection for self-referential types
- see generated code to copy into your macro that extracts the node in question from the root of the tree you've given to the explorer
You can also watch this 5 to 6 minute video for a more visual explanation:
s3te-video.mp4
Currently, basically none. I mean, I won't break api just for the fun of it, but the purpose of this library is mainly to debug and explore Scala code. I don't expect anyone to keep this library around. If you would like some guarantees, please open an issue to discuss it.
If you are missing some feature or think something is wrong, please open an issue. I still consider this library beta status! Of course, pull requests are also very welcome.
Big thanks to the Scala 3 team for making this possible. The docs are mostly copied from the Scala 3 docs and the implementation is heavily inspired by the Scala 3 code base as well.