Invoke REPL from code

A FAQ is how to invoke REPL from code.

Document the common entry points.

Author: som-snytt

overviews/repl/embedding.md

@@ -0,0 +1,61 @@
+---
+layout: overview-large
+title: Programmatic Use of Scala REPL
+
+disqus: true
+
+partof: repl
+num: 2
+outof: 2
+---
+
+The REPL can be embedded and invoked programmatically.
+
+It supports the `javax.script` API, or it can be used
+as either a code interpreter or an interactive command line.
+
+    import scala.tools.nsc.Settings
+    import scala.tools.nsc.interpreter._
+    import javax.script._
+
+    /** A simple example showing programmatic usage of the REPL. */
+    object Main extends App {
+
+      // the REPL has some support for javax.script
+      val scripter = new ScriptEngineManager().getEngineByName("scala")
+      scripter.eval("""println("hello, world")""")
+
+      // compiler settings
+      val settings = new Settings
+      settings.processArgumentString("-deprecation -feature -Xfatal-warnings -Xlint")
+
+      // the interpreter is used by the javax.script engine
+      val intp = new IMain(settings)
+      def interpret(code: String): Unit = {
+        import Results._
+        val res = intp.interpret(code) match {
+          case Success => "OK!"
+          case _       => "Sorry, try again."
+        }
+        println(res)
+      }
+      interpret("""println("hello, world")""")
+      interpret("""println(""")
+      interpret("""val who = "world" ; println("hello, $who")""")
+
+      // the REPL uses a line reader and an interpreter interactively
+      val interactive = new ILoop()
+      interactive.process(settings)
+
+      // input to the REPL can be provided programmatically
+      import java.io.{BufferedReader, StringReader, PrintWriter}
+      val reader = new BufferedReader(new StringReader(""""hello, world""""))
+      val canned = new ILoop(reader, new PrintWriter(Console.out, true))
+      canned.process(settings)
+
+      // more canning
+      val code = """println("hello, world") ; 42"""
+      val out = ILoop.run(code)
+      println(s"Output is $out")
+    }
+

overviews/repl/overview.md

@@ -6,7 +6,7 @@ disqus: true
 
 partof: repl
 num: 1
-outof: 1
+outof: 2
 ---
 
 The Scala REPL is a tool (_scala_) for evaluating expressions in Scala.
@@ -30,17 +30,29 @@ Useful REPL features include:
   - the REPL's IMain is bound to `$intp`.
   - the REPL's last exception is bound to `lastException`.
   - use tab for completion.
+  - use `//print<tab>` to show typed desugarings.
   - use `:help` for a list of commands.
   - use `:paste` to enter a class and object as companions.
-  - use `:paste -raw` to specify a package (no template wrapper).
+  - use `:paste -raw` to disable code wrapping, to define a package.
   - use `:javap` to inspect class artifacts.
   - use `-Yrepl-outdir` to inspect class artifacts with external tools.
+  - use `:power` to enter power mode and import compiler components.
 
 Implementation notes:
 
   - user code can be wrapped in either an object (so that the code runs during class initialization)
     or a class (so that the code runs during instance construction). The switch is `-Yrepl-class-based`.
 
+### Power Mode
+
+`:power` mode imports identifiers from the interpreter's compiler.
+
+That is analogous to importing from the runtime reflective context using `import reflect.runtime._, universe._`.
+
+Power mode also offers some utility methods as documented in the welcome banner.
+
+Its facilities can be witnessed using `:imports` or `-Xprint:parser`.
+
 ### Contributing to Scala REPL
 
 The REPL source is part of the Scala project. Issues are tracked by the standard