Merge pull request #5173 from janekdb/topic/2.12.x-scaladoc-AnsiColour

Group Console and AnsiColor entities and add usage examples

2 files changed, 265 insertions, 36 deletions

diff --git a/src/library/scala/Console.scala b/src/library/scala/Console.scala
index 37127a93d5..0b079aae15 100644
--- a/src/library/scala/Console.scala
+++ b/src/library/scala/Console.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2003-2013, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2016, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
@@ -12,12 +12,115 @@ import java.io.{ BufferedReader, InputStream, InputStreamReader, OutputStream, P
 import scala.io.{ AnsiColor, StdIn }
 import scala.util.DynamicVariable
 
-/** Implements functionality for
- *  printing Scala values on the terminal as well as reading specific values.
+/** Implements functionality for printing Scala values on the terminal. For reading values
+ *  use [[scala.io.StdIn$ StdIn]].
  *  Also defines constants for marking up text on ANSI terminals.
  *
+ *  == Console Output ==
+ *
+ *  Use the print methods to output text.
+ *  {{{
+ *   scala> Console.printf(
+ *     "Today the outside temperature is a balmy %.1f°C. %<.1f°C beats the previous record of %.1f°C.\n",
+ *     -137.0,
+ *     -135.05)
+ *   Today the outside temperature is a balmy -137.0°C. -137.0°C beats the previous record of -135.1°C.
+ *  }}}
+ *
+ *  == ANSI escape codes ==
+ *  Use the ANSI escape codes for colorizing console output either to STDOUT or STDERR.
+ *  {{{
+ *    import Console.{GREEN, RED, RESET, YELLOW_B, UNDERLINED}
+ *
+ *    object PrimeTest {
+ *
+ *      def isPrime(): Unit = {
+ *
+ *        val candidate = io.StdIn.readInt().ensuring(_ > 1)
+ *
+ *        val prime = (2 to candidate - 1).forall(candidate % _ != 0)
+ *
+ *        if (prime)
+ *          Console.println(s"${RESET}${GREEN}yes${RESET}")
+ *        else
+ *          Console.err.println(s"${RESET}${YELLOW_B}${RED}${UNDERLINED}NO!${RESET}")
+ *      }
+ *
+ *      def main(args: Array[String]): Unit = isPrime()
+ *
+ *    }
+ *  }}}
+ *
+ *  <table style="border: 10px solid #000;width:100%">
+ *    <tr><td style="background-color:#000;color:#fff">$ scala PrimeTest</td></tr>
+ *    <tr><td style="background-color:#000;color:#fff">1234567891</td></tr>
+ *    <tr><td style="background-color:#000;color:#0f0">yes</td></tr>
+ *    <tr><td style="background-color:#000;color:#fff">$ scala PrimeTest</td></tr>
+ *    <tr><td style="background-color:#000;color:#fff">56474</td></tr>
+ *    <tr><td style="background-color:#000;color:#fff"><span style="background-color:#ff0;color:#f00;text-decoration:underline">NO!</span></td></tr>
+ *  </table>
+ *
+ *  == IO redefinition ==
+ *
+ *  Use IO redefinition to temporarily swap in a different set of input and/or output streams. In this example the stream based
+ *  method above is wrapped into a function.
+ *
+ *  {{{
+ *    import java.io.{ByteArrayOutputStream, StringReader}
+ *
+ *    object FunctionalPrimeTest {
+ *
+ *      def isPrime(candidate: Int): Boolean = {
+ *
+ *        val input = new StringReader(s"$candidate\n")
+ *        val outCapture = new ByteArrayOutputStream
+ *        val errCapture = new ByteArrayOutputStream
+ *
+ *        Console.withIn(input) {
+ *          Console.withOut(outCapture) {
+ *            Console.withErr(errCapture) {
+ *              PrimeTest.isPrime()
+ *            }
+ *          }
+ *        }
+ *
+ *        if (outCapture.toByteArray.nonEmpty) // "yes"
+ *          true
+ *        else if (errCapture.toByteArray.nonEmpty) // "NO!"
+ *          false
+ *        else throw new IllegalArgumentException(candidate.toString)
+ *      }
+ *
+ *      def main(args: Array[String]): Unit = {
+ *        val primes = (2 to 50) filter (isPrime)
+ *        println(s"First primes: $primes")
+ *      }
+ *
+ *    }
+ *  }}}
+ *
+ *
+ *  <table style="border: 10px solid #000;width:100%">
+ *    <tr><td style="background-color:#000;color:#fff">$ scala FunctionalPrimeTest</td></tr>
+ *    <tr><td style="background-color:#000;color:#fff">First primes: Vector(2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47)</td></tr>
+ *  </table>
+ *
  *  @author  Matthias Zenger
  *  @version 1.0, 03/09/2003
+ *
+ *  @groupname console-output Console Output
+ *  @groupprio console-output 30
+ *  @groupdesc console-output These methods provide output via the console.
+ *
+ *  @groupname io-default IO Defaults
+ *  @groupprio io-default 50
+ *  @groupdesc io-default These values provide direct access to the standard IO channels
+ *
+ *  @groupname io-redefinition IO Redefinition
+ *  @groupprio io-redefinition 60
+ *  @groupdesc io-redefinition These methods allow substituting alternative streams for the duration of
+ *             a body of code. Threadsafe by virtue of [[scala.util.DynamicVariable]].
+ *
  */
 object Console extends DeprecatedConsole with AnsiColor {
   private val outVar = new DynamicVariable[PrintStream](java.lang.System.out)
@@ -29,11 +132,17 @@ object Console extends DeprecatedConsole with AnsiColor {
   protected def setErrDirect(err: PrintStream): Unit  = errVar.value = err
   protected def setInDirect(in: BufferedReader): Unit = inVar.value = in
 
-  /** The default output, can be overridden by `setOut` */
+  /** The default output, can be overridden by `withOut`
+   *  @group io-default
+   */
   def out = outVar.value
-  /** The default error, can be overridden by `setErr` */
+  /** The default error, can be overridden by `withErr`
+   *  @group io-default
+   */
   def err = errVar.value
-  /** The default input, can be overridden by `setIn` */
+  /** The default input, can be overridden by `withIn`
+   *  @group io-default
+   */
   def in = inVar.value
 
   /** Sets the default output stream for the duration
@@ -48,6 +157,7 @@ object Console extends DeprecatedConsole with AnsiColor {
    *               the new output stream active
    *  @return the results of `thunk`
    *  @see `withOut[T](out:OutputStream)(thunk: => T)`
+   *  @group io-redefinition
    */
   def withOut[T](out: PrintStream)(thunk: =>T): T =
     outVar.withValue(out)(thunk)
@@ -60,6 +170,7 @@ object Console extends DeprecatedConsole with AnsiColor {
    *               the new output stream active
    *  @return the results of `thunk`
    *  @see `withOut[T](out:PrintStream)(thunk: => T)`
+   *  @group io-redefinition
    */
   def withOut[T](out: OutputStream)(thunk: =>T): T =
     withOut(new PrintStream(out))(thunk)
@@ -67,7 +178,7 @@ object Console extends DeprecatedConsole with AnsiColor {
   /** Set the default error stream for the duration
    *  of execution of one thunk.
    *  @example {{{
-   *  withErr(Console.out) { println("This goes to default _out_") }
+   *  withErr(Console.out) { err.println("This goes to default _out_") }
    *  }}}
    *
    *  @param err the new error stream.
@@ -75,6 +186,7 @@ object Console extends DeprecatedConsole with AnsiColor {
    *               the new error stream active
    *  @return the results of `thunk`
    *  @see `withErr[T](err:OutputStream)(thunk: =>T)`
+   *  @group io-redefinition
    */
   def withErr[T](err: PrintStream)(thunk: =>T): T =
     errVar.withValue(err)(thunk)
@@ -87,6 +199,7 @@ object Console extends DeprecatedConsole with AnsiColor {
    *               the new error stream active
    *  @return the results of `thunk`
    *  @see `withErr[T](err:PrintStream)(thunk: =>T)`
+   *  @group io-redefinition
    */
   def withErr[T](err: OutputStream)(thunk: =>T): T =
     withErr(new PrintStream(err))(thunk)
@@ -105,8 +218,9 @@ object Console extends DeprecatedConsole with AnsiColor {
    *  @param thunk the code to execute with
    *               the new input stream active
    *
-   * @return the results of `thunk`
-   * @see `withIn[T](in:InputStream)(thunk: =>T)`
+   *  @return the results of `thunk`
+   *  @see `withIn[T](in:InputStream)(thunk: =>T)`
+   *  @group io-redefinition
    */
   def withIn[T](reader: Reader)(thunk: =>T): T =
     inVar.withValue(new BufferedReader(reader))(thunk)
@@ -117,8 +231,9 @@ object Console extends DeprecatedConsole with AnsiColor {
    *  @param in the new input stream.
    *  @param thunk the code to execute with
    *               the new input stream active
-   * @return the results of `thunk`
-   * @see `withIn[T](reader:Reader)(thunk: =>T)`
+   *  @return the results of `thunk`
+   *  @see `withIn[T](reader:Reader)(thunk: =>T)`
+   *  @group io-redefinition
    */
   def withIn[T](in: InputStream)(thunk: =>T): T =
     withIn(new InputStreamReader(in))(thunk)
@@ -126,6 +241,7 @@ object Console extends DeprecatedConsole with AnsiColor {
   /** Prints an object to `out` using its `toString` method.
    *
    *  @param obj the object to print; may be null.
+   *  @group console-output
    */
   def print(obj: Any) {
     out.print(if (null == obj) "null" else obj.toString())
@@ -134,29 +250,31 @@ object Console extends DeprecatedConsole with AnsiColor {
   /** Flushes the output stream. This function is required when partial
    *  output (i.e. output not terminated by a newline character) has
    *  to be made visible on the terminal.
+    * @group console-output
    */
   def flush() { out.flush() }
 
   /** Prints a newline character on the default output.
+    * @group console-output
    */
   def println() { out.println() }
 
   /** Prints out an object to the default output, followed by a newline character.
    *
    *  @param x the object to print.
+   *  @group console-output
    */
   def println(x: Any) { out.println(x) }
 
   /** Prints its arguments as a formatted string to the default output,
    *  based on a string pattern (in a fashion similar to printf in C).
    *
-   *  The interpretation of the formatting patterns is described in
-   *  <a href="" target="contentFrame" class="java/util/Formatter">
-   *  `java.util.Formatter`</a>.
+   *  The interpretation of the formatting patterns is described in [[java.util.Formatter]].
    *
    *  @param text the pattern for formatting the arguments.
    *  @param args the arguments used to instantiating the pattern.
    *  @throws java.lang.IllegalArgumentException if there was a problem with the format string or arguments
+   *  @group console-output
    */
   def printf(text: String, args: Any*) { out.print(text format (args : _*)) }
 }
diff --git a/src/library/scala/io/AnsiColor.scala b/src/library/scala/io/AnsiColor.scala
index 39e2e3b0ca..720049ba8e 100644
--- a/src/library/scala/io/AnsiColor.scala
+++ b/src/library/scala/io/AnsiColor.scala
@@ -1,52 +1,163 @@
 package scala
 package io
 
+/** ANSI escape codes providing control over text formatting and color on supporting text terminals.
+  *
+  * ==ANSI Style and Control Codes==
+  *
+  * This group of escape codes provides control over text styling. For example, to turn on reverse video with bold and
+  * then turn off all styling embed these codes,
+  *
+  * {{{
+  * import io.AnsiColor._
+  *
+  * object ColorDemo extends App {
+  *
+  *   println(s"$REVERSED${BOLD}Hello 1979!$RESET")
+  * }
+  * }}}
+  *
+  * ==Foreground and Background Colors==
+  *
+  * Embedding ANSI color codes in text output will control the text foreground and background colors.
+  *
+  * <table>
+  *   <tr><th style="padding:4px 15px;text-decoration:underline">Foreground</th><th style="width:50%"></th><th style="padding:4px 15px;text-decoration:underline">Background</th></tr>
+  *   <tr><td style="padding:4px 15px">BLACK  </td><td style="background-color:#000"></td><td style="padding:4px 15px">BLACK_B  </td></tr>
+  *   <tr><td style="padding:4px 15px">RED    </td><td style="background-color:#f00"></td><td style="padding:4px 15px">RED_B    </td></tr>
+  *   <tr><td style="padding:4px 15px">GREEN  </td><td style="background-color:#0f0"></td><td style="padding:4px 15px">GREEN_B  </td></tr>
+  *   <tr><td style="padding:4px 15px">YELLOW </td><td style="background-color:#ff0"></td><td style="padding:4px 15px">YELLOW_B </td></tr>
+  *   <tr><td style="padding:4px 15px">BLUE   </td><td style="background-color:#00f"></td><td style="padding:4px 15px">BLUE_B   </td></tr>
+  *   <tr><td style="padding:4px 15px">MAGENTA</td><td style="background-color:#f0f"></td><td style="padding:4px 15px">MAGENTA_B</td></tr>
+  *   <tr><td style="padding:4px 15px">CYAN   </td><td style="background-color:#0ff"></td><td style="padding:4px 15px">CYAN_B   </td></tr>
+  *   <tr><td style="padding:4px 15px">WHITE  </td><td style="background-color:#fff"></td><td style="padding:4px 15px">WHITE_B  </td></tr>
+  * </table>
+  *
+  * @groupname style-control ANSI Style and Control Codes
+  * @groupprio style-control 101
+  *
+  * @groupname color-black ANSI Black
+  * @groupdesc color-black <table style="width:100%"><tr><td style="background-color:#000">&nbsp;</td></tr></table>
+  * @groupprio color-black 110
+  *
+  * @groupname color-red ANSI Red
+  * @groupdesc color-red <table style="width:100%"><tr><td style="background-color:#f00">&nbsp;</td></tr></table>
+  * @groupprio color-red 120
+  *
+  * @groupname color-green ANSI Green
+  * @groupdesc color-green <table style="width:100%"><tr><td style="background-color:#0f0">&nbsp;</td></tr></table>
+  * @groupprio color-green 130
+  *
+  * @groupname color-yellow ANSI Yellow
+  * @groupdesc color-yellow <table style="width:100%"><tr><td style="background-color:#ff0">&nbsp;</td></tr></table>
+  * @groupprio color-yellow 140
+  *
+  * @groupname color-blue ANSI Blue
+  * @groupdesc color-blue <table style="width:100%"><tr><td style="background-color:#00f">&nbsp;</td></tr></table>
+  * @groupprio color-blue 150
+  *
+  * @groupname color-magenta ANSI Magenta
+  * @groupdesc color-magenta <table style="width:100%"><tr><td style="background-color:#f0f">&nbsp;</td></tr></table>
+  * @groupprio color-magenta 160
+  *
+  * @groupname color-cyan ANSI Cyan
+  * @groupdesc color-cyan <table style="width:100%"><tr><td style="background-color:#0ff">&nbsp;</td></tr></table>
+  * @groupprio color-cyan 170
+  *
+  * @groupname color-white ANSI White
+  * @groupdesc color-white <table style="width:100%"><tr><td style="background-color:#fff">&nbsp;</td></tr></table>
+  * @groupprio color-white 180
+  */
 trait AnsiColor {
-  /** Foreground color for ANSI black */
+  /** Foreground color for ANSI black
+    * @group color-black
+    */
   final val BLACK      = "\u001b[30m"
-  /** Foreground color for ANSI red */
+  /** Foreground color for ANSI red
+    * @group color-red
+    */
   final val RED        = "\u001b[31m"
-  /** Foreground color for ANSI green */
+  /** Foreground color for ANSI green
+    * @group color-green
+    */
   final val GREEN      = "\u001b[32m"
-  /** Foreground color for ANSI yellow */
+  /** Foreground color for ANSI yellow
+    * @group color-yellow
+    */
   final val YELLOW     = "\u001b[33m"
-  /** Foreground color for ANSI blue */
+  /** Foreground color for ANSI blue
+    * @group color-blue
+    */
   final val BLUE       = "\u001b[34m"
-  /** Foreground color for ANSI magenta */
+  /** Foreground color for ANSI magenta
+    * @group color-magenta
+    */
   final val MAGENTA    = "\u001b[35m"
-  /** Foreground color for ANSI cyan */
+  /** Foreground color for ANSI cyan
+    * @group color-cyan
+    */
   final val CYAN       = "\u001b[36m"
-  /** Foreground color for ANSI white */
+  /** Foreground color for ANSI white
+    * @group color-white
+    */
   final val WHITE      = "\u001b[37m"
 
-  /** Background color for ANSI black */
+  /** Background color for ANSI black
+    * @group color-black
+    */
   final val BLACK_B    = "\u001b[40m"
-  /** Background color for ANSI red */
+  /** Background color for ANSI red
+    * @group color-red
+    */
   final val RED_B      = "\u001b[41m"
-  /** Background color for ANSI green */
+  /** Background color for ANSI green
+    * @group color-green
+    */
   final val GREEN_B    = "\u001b[42m"
-  /** Background color for ANSI yellow */
+  /** Background color for ANSI yellow
+    * @group color-yellow
+    */
   final val YELLOW_B   = "\u001b[43m"
-  /** Background color for ANSI blue */
+  /** Background color for ANSI blue
+    * @group color-blue
+    */
   final val BLUE_B     = "\u001b[44m"
-  /** Background color for ANSI magenta */
+  /** Background color for ANSI magenta
+    * @group color-magenta
+    */
   final val MAGENTA_B  = "\u001b[45m"
-  /** Background color for ANSI cyan */
+  /** Background color for ANSI cyan
+    * @group color-cyan
+    */
   final val CYAN_B     = "\u001b[46m"
-  /** Background color for ANSI white */
+  /** Background color for ANSI white
+    * @group color-white
+    */
   final val WHITE_B    = "\u001b[47m"
 
-  /** Reset ANSI styles */
+  /** Reset ANSI styles
+    * @group style-control
+    */
   final val RESET      = "\u001b[0m"
-  /** ANSI bold */
+  /** ANSI bold
+    * @group style-control
+    */
   final val BOLD       = "\u001b[1m"
-  /** ANSI underlines */
+  /** ANSI underlines
+    * @group style-control
+    */
   final val UNDERLINED = "\u001b[4m"
-  /** ANSI blink */
+  /** ANSI blink
+    * @group style-control
+    */
   final val BLINK      = "\u001b[5m"
-  /** ANSI reversed */
+  /** ANSI reversed
+    * @group style-control
+    */
   final val REVERSED   = "\u001b[7m"
-  /** ANSI invisible */
+  /** ANSI invisible
+    * @group style-control
+    */
   final val INVISIBLE  = "\u001b[8m"
 }