Add @scala.annotation.preview annotation and -preview flag.

Author: WojciechMazur

compiler/src/dotty/tools/dotc/ast/TreeInfo.scala

@@ -297,7 +297,7 @@ trait TreeInfo[T <: Untyped] { self: Trees.Instance[T] =>
     case TypeDefs(_) => true
     case _ => false
 
-  private val languageSubCategories = Set(nme.experimental, nme.deprecated)
+  private val languageSubCategories = Set(nme.experimental, nme.preview, nme.deprecated)
 
   /** If `path` looks like a language import, `Some(name)` where name
    *  is `experimental` if that sub-module is imported, and the empty

compiler/src/dotty/tools/dotc/config/Feature.scala

@@ -11,12 +11,16 @@ import SourceVersion.*
 import reporting.Message
 import NameKinds.QualifiedName
 import Annotations.ExperimentalAnnotation
+import Annotations.PreviewAnnotation
 import Settings.Setting.ChoiceWithHelp
 
 object Feature:
 
   def experimental(str: PreName): TermName =
     QualifiedName(nme.experimental, str.toTermName)
+    
+  def preview(str: PreName): TermName = 
+    QualifiedName(nme.preview, str.toTermName)
 
   private def deprecated(str: PreName): TermName =
     QualifiedName(nme.deprecated, str.toTermName)
@@ -44,6 +48,10 @@ object Feature:
     defn.languageExperimentalFeatures
       .map(sym => experimental(sym.name))
       .filterNot(_ == captureChecking) // TODO is this correct?
+      
+  def previewAutoEnableFeatures(using Context): List[TermName] =
+    defn.languagePreviewFeatures
+      .map(sym => preview(sym.name))
 
   val values = List(
     (nme.help, "Display all available features"),
@@ -224,7 +232,7 @@ object Feature:
 
   def isExperimentalEnabledByImport(using Context): Boolean =
     experimentalAutoEnableFeatures.exists(enabledByImport)
-
+  
   /** Handle language import `import language.<prefix>.<imported>` if it is one
    *  of the global imports `pureFunctions` or `captureChecking`. In this case
    *  make the compilation unit's and current run's fields accordingly.
@@ -242,4 +250,35 @@ object Feature:
       true
     else
       false
+      
+  def isPreviewEnabled(using Context): Boolean = 
+    ctx.settings.preview.value || 
+    previewAutoEnableFeatures.exists(enabled)
+  
+  def checkPreviewFeature(which: String, srcPos: SrcPos, note: => String = "")(using Context) =
+    if !isPreviewEnabled then
+      report.error(previewUseSite(which) + note, srcPos)
+      
+  def checkPreviewDef(sym: Symbol, srcPos: SrcPos)(using Context) = if !isPreviewEnabled then
+    val previewSym =
+      if sym.hasAnnotation(defn.PreviewAnnot) then sym
+      else if sym.owner.hasAnnotation(defn.PreviewAnnot) then sym.owner
+      else NoSymbol
+    val msg =
+      previewSym.getAnnotation(defn.PreviewAnnot).collectFirst {
+        case PreviewAnnotation(msg) if msg.nonEmpty => s": $msg"
+      }.getOrElse("")
+    val markedPreview =
+      if previewSym.exists
+      then i"$previewSym is marked @preview$msg"
+      else i"$sym inherits @preview$msg"
+    report.error(markedPreview + "\n\n" + previewUseSite("definition"), srcPos)
+  
+  private def previewUseSite(which: String): String =
+    s"""Preview $which may only be used under preview mode:
+       |  1. in a definition marked as @preview, or
+       |  2. a preview feature is imported at the package level, or
+       |  3. compiling with the -preview compiler flag.
+       |""".stripMargin
 end Feature
+

compiler/src/dotty/tools/dotc/config/ScalaSettings.scala

@@ -116,7 +116,8 @@ trait CommonScalaSettings:
   val unchecked: Setting[Boolean] = BooleanSetting(RootSetting, "unchecked", "Enable additional warnings where generated code depends on assumptions.", initialValue = true, aliases = List("--unchecked"))
   val language: Setting[List[ChoiceWithHelp[String]]] = MultiChoiceHelpSetting(RootSetting, "language", "feature", "Enable one or more language features.", choices = ScalaSettingsProperties.supportedLanguageFeatures, legacyChoices = ScalaSettingsProperties.legacyLanguageFeatures, default = Nil, aliases = List("--language"))
   val experimental: Setting[Boolean] = BooleanSetting(RootSetting, "experimental", "Annotate all top-level definitions with @experimental. This enables the use of experimental features anywhere in the project.")
-
+  val preview: Setting[Boolean] = BooleanSetting(RootSetting, "preview", "Enable the use of preview features anywhere in the project.")
+  
   /* Coverage settings */
   val coverageOutputDir = PathSetting(RootSetting, "coverage-out", "Destination for coverage classfiles and instrumentation data.", "", aliases = List("--coverage-out"))
   val coverageExcludeClasslikes: Setting[List[String]] = MultiStringSetting(RootSetting, "coverage-exclude-classlikes", "packages, classes and modules", "List of regexes for packages, classes and modules to exclude from coverage.", aliases = List("--coverage-exclude-classlikes"))

compiler/src/dotty/tools/dotc/core/Annotations.scala

@@ -303,5 +303,16 @@ object Annotations {
         case annot @ ExperimentalAnnotation(msg) => ExperimentalAnnotation(msg, annot.tree.span)
       }
   }
-
+  
+  object PreviewAnnotation {
+    /** Matches and extracts the message from an instance of `@preview(msg)`
+     *  Returns `Some("")` for `@preview` with no message.
+     */
+    def unapply(a: Annotation)(using Context): Option[String] =
+      if a.symbol ne defn.PreviewAnnot then
+        None
+      else a.argumentConstant(0) match
+        case Some(Constant(msg: String)) => Some(msg)
+        case _ => Some("")
+  }
 }

compiler/src/dotty/tools/dotc/core/Definitions.scala

@@ -808,6 +808,7 @@ class Definitions {
   @tu lazy val LanguageModule: Symbol = requiredModule("scala.language")
   @tu lazy val LanguageModuleClass: Symbol = LanguageModule.moduleClass.asClass
   @tu lazy val LanguageExperimentalModule: Symbol = requiredModule("scala.language.experimental")
+  @tu lazy val LanguagePreviewModule: Symbol = requiredModule("scala.language.preview")
   @tu lazy val LanguageDeprecatedModule: Symbol = requiredModule("scala.language.deprecated")
   @tu lazy val NonLocalReturnControlClass: ClassSymbol = requiredClass("scala.runtime.NonLocalReturnControl")
   @tu lazy val SelectableClass: ClassSymbol = requiredClass("scala.Selectable")
@@ -1053,6 +1054,7 @@ class Definitions {
   @tu lazy val CompileTimeOnlyAnnot: ClassSymbol = requiredClass("scala.annotation.compileTimeOnly")
   @tu lazy val SwitchAnnot: ClassSymbol = requiredClass("scala.annotation.switch")
   @tu lazy val ExperimentalAnnot: ClassSymbol = requiredClass("scala.annotation.experimental")
+  @tu lazy val PreviewAnnot: ClassSymbol = requiredClass("scala.annotation.preview")
   @tu lazy val ThrowsAnnot: ClassSymbol = requiredClass("scala.throws")
   @tu lazy val TransientAnnot: ClassSymbol = requiredClass("scala.transient")
   @tu lazy val UncheckedAnnot: ClassSymbol = requiredClass("scala.unchecked")
@@ -2079,6 +2081,10 @@ class Definitions {
   @tu lazy val languageExperimentalFeatures: List[TermSymbol] =
     LanguageExperimentalModule.moduleClass.info.decls.toList.filter(_.isAllOf(Lazy | Module)).map(_.asTerm)
 
+  /** Preview language features defined in `scala.runtime.stdLibPatches.language.preview` */
+  @tu lazy val languagePreviewFeatures: List[TermSymbol] =
+    LanguagePreviewModule.moduleClass.info.decls.toList.filter(_.isAllOf(Lazy | Module)).map(_.asTerm)
+
   // ----- primitive value class machinery ------------------------------------------
 
   class PerRun[T](generate: Context ?=> T) {

compiler/src/dotty/tools/dotc/core/StdNames.scala

@@ -579,6 +579,7 @@ object StdNames {
     val parts: N                = "parts"
     val postfixOps: N           = "postfixOps"
     val prefix : N              = "prefix"
+    val preview: N              = "preview"
     val processEscapes: N       = "processEscapes"
     val productArity: N         = "productArity"
     val productElement: N       = "productElement"

compiler/src/dotty/tools/dotc/core/SymUtils.scala

@@ -366,24 +366,31 @@ class SymUtils:
         && self.owner.linkedClass.isDeclaredInfix
 
     /** Is symbol declared or inherits @experimental? */
-    def isExperimental(using Context): Boolean =
-      self.hasAnnotation(defn.ExperimentalAnnot)
-      || (self.maybeOwner.isClass && self.owner.hasAnnotation(defn.ExperimentalAnnot))
-
-    def isInExperimentalScope(using Context): Boolean =
-      def isDefaultArgumentOfExperimentalMethod =
+    def isExperimental(using Context): Boolean = isFeatureAnnotated(defn.ExperimentalAnnot)
+    def isInExperimentalScope(using Context): Boolean = isInFeatureScope(defn.ExperimentalAnnot, _.isExperimental, _.isInExperimentalScope)
+
+    /** Is symbol declared or inherits @preview? */
+    def isPreview(using Context): Boolean = isFeatureAnnotated(defn.PreviewAnnot)       
+    def isInPreviewScope(using Context): Boolean = isInFeatureScope(defn.PreviewAnnot, _.isPreview, _.isInPreviewScope)
+      
+    private inline def isFeatureAnnotated(checkAnnotaton: ClassSymbol)(using Context): Boolean = 
+      self.hasAnnotation(checkAnnotaton)
+      || (self.maybeOwner.isClass && self.owner.hasAnnotation(checkAnnotaton))
+        
+    private inline def isInFeatureScope(checkAnnotation: ClassSymbol, checkSymbol: Symbol => Boolean, checkOwner: Symbol => Boolean)(using Context): Boolean =
+      def isDefaultArgumentOfCheckedMethod =
         self.name.is(DefaultGetterName)
         && self.owner.isClass
         && {
           val overloads = self.owner.asClass.membersNamed(self.name.firstPart)
           overloads.filterWithFlags(HasDefaultParams, EmptyFlags) match
-            case denot: SymDenotation => denot.symbol.isExperimental
+            case denot: SymDenotation => checkSymbol(denot.symbol)
             case _ => false
         }
-      self.hasAnnotation(defn.ExperimentalAnnot)
-      || isDefaultArgumentOfExperimentalMethod
-      || (!self.is(Package) && self.owner.isInExperimentalScope)
-
+      self.hasAnnotation(checkAnnotation)
+      || isDefaultArgumentOfCheckedMethod
+      || (!self.is(Package) && checkOwner(self.owner))
+      
     /** The declared self type of this class, as seen from `site`, stripping
     *  all refinements for opaque types.
     */

compiler/src/dotty/tools/dotc/typer/Checking.scala

@@ -1079,6 +1079,7 @@ trait Checking {
       case Some(prefix) =>
         val required =
           if prefix == nme.experimental then defn.LanguageExperimentalModule
+          else if prefix == nme.preview then defn.LanguagePreviewModule
           else if prefix == nme.deprecated then defn.LanguageDeprecatedModule
           else defn.LanguageModule
         if path.symbol != required then
@@ -1087,6 +1088,7 @@ trait Checking {
         val foundClasses = path.tpe.classSymbols
         if foundClasses.contains(defn.LanguageModule.moduleClass)
            || foundClasses.contains(defn.LanguageExperimentalModule.moduleClass)
+           || foundClasses.contains(defn.LanguagePreviewModule.moduleClass)
         then
           report.error(em"no aliases can be used to refer to a language import", path.srcPos)
 

compiler/src/dotty/tools/dotc/typer/CrossVersionChecks.scala

@@ -141,10 +141,12 @@ class CrossVersionChecks extends MiniPhase:
         if tree.span.isSourceDerived then
           checkDeprecatedRef(sym, tree.srcPos)
         checkExperimentalRef(sym, tree.srcPos)
+        checkPreviewFeatureRef(sym, tree.srcPos)
       case TermRef(_, sym: Symbol)  =>
         if tree.span.isSourceDerived then
           checkDeprecatedRef(sym, tree.srcPos)
         checkExperimentalRef(sym, tree.srcPos)
+        checkPreviewFeatureRef(sym, tree.srcPos)
       case AnnotatedType(_, annot) =>
         checkUnrollAnnot(annot.symbol, tree.srcPos)
       case _ =>
@@ -174,11 +176,12 @@ object CrossVersionChecks:
   val description: String = "check issues related to deprecated and experimental"
 
   /** Check that a reference to an experimental definition with symbol `sym` meets cross-version constraints
-   *  for `@deprecated` and `@experimental`.
+   *  for `@deprecated`, `@experimental` and `@preview`.
    */
   def checkRef(sym: Symbol, pos: SrcPos)(using Context): Unit =
     checkDeprecatedRef(sym, pos)
     checkExperimentalRef(sym, pos)
+    checkPreviewFeatureRef(sym, pos)
 
   /** Check that a reference to an experimental definition with symbol `sym` is only
    *  used in an experimental scope
@@ -187,6 +190,13 @@ object CrossVersionChecks:
     if sym.isExperimental && !ctx.owner.isInExperimentalScope then
       Feature.checkExperimentalDef(sym, pos)
 
+  /** Check that a reference to a preview definition with symbol `sym` is only
+   *  used in a preview mode.
+   */
+  private[CrossVersionChecks] def checkPreviewFeatureRef(sym: Symbol, pos: SrcPos)(using Context): Unit =
+    if sym.isPreview && !ctx.owner.isInPreviewScope then
+      Feature.checkPreviewDef(sym, pos)
+
   /** If @deprecated is present, and the point of reference is not enclosed
    *  in either a deprecated member or a scala bridge method, issue a warning.
    *

compiler/src/dotty/tools/dotc/typer/RefChecks.scala

@@ -306,6 +306,7 @@ object RefChecks {
    *           that passes its value on to O.
    *    1.13.  If O is non-experimental, M must be non-experimental.
    *    1.14.  If O has @publicInBinary, M must have @publicInBinary.
+   *    1.15.  If O is non-preview, M must be non-preview 
    *  2. Check that only abstract classes have deferred members
    *  3. Check that concrete classes do not have deferred definitions
    *     that are not implemented in a subclass.
@@ -643,8 +644,10 @@ object RefChecks {
             MigrationVersion.OverrideValParameter)
       else if !other.isExperimental && member.hasAnnotation(defn.ExperimentalAnnot) then // (1.13)
         overrideError("may not override non-experimental member")
-      else if !member.hasAnnotation(defn.PublicInBinaryAnnot) && other.hasAnnotation(defn.PublicInBinaryAnnot) then // (1.14)
+        else if !member.hasAnnotation(defn.PublicInBinaryAnnot) && other.hasAnnotation(defn.PublicInBinaryAnnot) then // (1.14)
         overrideError("also needs to be declared with @publicInBinary")
+        else if !other.isPreview && member.hasAnnotation(defn.PreviewAnnot) then // (1.15)
+          overrideError("may not override non-preview member")
       else if other.hasAnnotation(defn.DeprecatedOverridingAnnot) then
         overrideDeprecation("", member, other, "removed or renamed")
     end checkOverride