Term.of and .asExprOf is confusing to new users, please add back seal/unseal

[deusaquilus]

@nicolasstucki @lihaoyi I understand that changing seal/unseal to Term.of and .asExprOf makes sense internally, especially since it avoid the need for an extra call (i.e. in x.seal.cast[T]). For new users for Tasty Reflect however, the mental-model of "sealing" and "unsealing" is beautifully intuitive and makes the whole Term <-> Expr duality much, much easier to understand. Several students to whom I have taught Tasty-Reflect have told me this. Is there any possibility that the following could be added for user-convenience?

expr.unseal     // as a shortcut for Term.of(expr)
term.sealAs[T] // as a shortcut for term.asExprOf[T]
term.seal         // as a shortcut for term.asExprOf[Any]

Normally I would just add these things in my own codebase as extension classes but Quotes being a path-dependent variable makes this very difficult to do.

[nicolasstucki]

seal and unseal were renamed to have meaningful names for those operations. The expr.unseal was especially dangerous to non-power users as it makes it too simple to access accidentally the reflection API.

[liufengyun]

The expr.unseal was especially dangerous to non-power users as it makes it too simple to access accidentally the reflection API.

Meta-programmers are usually advanced Scala programmers.

[nicolasstucki]

Not those that only use inline and '{...}. That was only true for Scala 2 because you needed to be an advanced programmer to start using macros. Now we have simpler alternatives which users should favor.

[deusaquilus]

Please understand that I am not trying to throw a wrench into the process of refiling this API and I am not trying to be annoying for no reason. Once Dotty is released, the entire community of Macro-Writers are going to start re-writing their frameworks and they are all going to start submitting feedback about this API, but because this is still an early stage it's just me.

People are going to be able to do .seal and .unseal and fairly frequently. In my own codebase, in order to parse Tasty trees, I need to go down to the Term layer in many, many, many more places then I had to do with quasai quoting because of the many restrictions of Quoted Matching (I can give you many, many examples of this). Once these things are matched, they all need to be sealed back up again and this needs to get done hundreds of times.

These macro writers of frameworks like magnolia, contextual, and others are power-users and fully understand the consequences of what they are doing. As I plan out the Quill parser I am seeing more and more need to use .seal and .unseal in the coming weeks. I would not be asking this unless I saw a great need for this.

[deusaquilus]

Here's a super simple, example. In Quill I need to match a generic property-application, this is a fairly common case where field selection is done inside of a query e.g. person => person.name where person.name is being parsed.

Using quasai quotes, I could just do this:

query match 
  case "$prefix.$member" =>
    Property(astParse(prefix), IdentParse(member))

None of these things are possible to do with qutoed matching because it is much more restrictive so I need to go down to the term layer:

query match
  case Unseal(Select(prefix, member)) =>
    Property(astParse(prefix.seal), astParse(member.seal))

See how in order to do things after matching I need to seal things back up? Then I need to seal them back up immediately afterword. To finish writing my parser I am going to need to do this much, much more often. Sure I can do Term.of everywhere but that is more verbose and not intuitive to a user.

[deusaquilus]

Here is an another example. Right now, because of the limits of quoted matching, I cannot directly invoke ctx.executeQuery on my Context since the result is a path-dependent type. So instead I have to do something like this:

val applyExecuteQuery =
  Apply(
    TypeApply(Select(Term.of(ctx), executeQueryMethod), List(TypeTree.of[T])),
    List(Term.of(Expr(query)), Term.of(prepare), Term.of(extractor), Term.of('{ExecutionType.Static}))
  )

I think this would be much more easy to understand with .unseal

val applyExecuteQuery =
  Apply(
    TypeApply(Select(ctx.unseal, executeQueryMethod), List(TypeTree.of[T])),
    List(Expr(query).unseal, prepare.unseal, extractor.unseal, '{ExecutionType.Static}.unseal)
  )

I imagine in libraries like contextual where they need to be more flexible about types they will have to do stuff like this in many more places then me.

[nicolasstucki]

It will be relatively simple to add unseal as an extension method in 3.0.0-M3 as shown in the following example

import scala.quoted._

object MyAPI:
  extension (expr: Expr[Any]) def asTerm(using Quotes): quotes.reflect.Term =
    quotes.reflect.Term.of(expr)
    
def test[T: Type](expr: Expr[T])(using q: Quotes): Expr[T] =
  import MyAPI.asTerm
  val term = expr.asTerm
  term.asExprOf[T]

[deusaquilus]

@nicolasstucki Won't the compiler complain that Quotes is being exposed to the outside? That's typically what happens with local variables qctx.

Is there any way unseal can be exposed to the user, just as a user-level API? I would even be happy if it was under quotes.reflect.extras or something like that. The thing about Term.of or asTerm or things like that is that they express a mechanism as opposed to an intent, this is a common theme in Dotty. The intention of the user is to "unseal the tree."

Btw, I started a discussion of this and #10673 on the contributors forum here. I think in both of these it is important to think about macro-developer's usability.

[nicolasstucki]

We originally moved away from seal/unseal because new users were confused. At that point, we decided to make the intention of the operations clear in their name. Now if a user as the intention of transforming a Term into an Expr the operation asExpr/asExprOf conveys this intention explicitly. unseal/seal have always been a mechanism-based API as they were names after the implementation detail that we wrap the Tree in an Expr object. Conceptually the Expr abstraction does not need to be seen as a wrapper, it could perfectly be a refinement of a Tree.

We used Trem.of instead of asTerm because of some quirks with extension methods. These are gone in the final revision. Now we can implement this operation properly in the reflection API. I created #10694 to try this out.

[deusaquilus]

Okay, asTerm seems like a reasonable alternative.