From f05000629d68d67d3940f9ea00cf68cf37f8d1ba Mon Sep 17 00:00:00 2001 From: Aleksandar Pokopec Date: Mon, 14 Feb 2011 17:32:02 +0000 Subject: Applying davetron5000's Console docs patch. No review. --- src/library/scala/Console.scala | 230 ++++++++++++++++++++++++---------------- 1 file changed, 137 insertions(+), 93 deletions(-) (limited to 'src/library') diff --git a/src/library/scala/Console.scala b/src/library/scala/Console.scala index fe71aab8e8..f27393a294 100644 --- a/src/library/scala/Console.scala +++ b/src/library/scala/Console.scala @@ -16,9 +16,9 @@ import java.text.MessageFormat import scala.util.DynamicVariable -/** The Console object implements functionality for - * printing Scala values on the terminal. There are also functions - * for reading specific values. Console also defines +/** Implements functionality for + * printing Scala values on the terminal as well as reading specific values. + * Also defines * constants for marking up text on ANSI terminals. * * @author Matthias Zenger @@ -26,32 +26,51 @@ import scala.util.DynamicVariable */ object Console { - // ANSI colors foreground + /** Foreground color for ANSI black */ final val BLACK = "\033[30m" + /** Foreground color for ANSI red */ final val RED = "\033[31m" + /** Foreground color for ANSI green */ final val GREEN = "\033[32m" + /** Foreground color for ANSI yellow */ final val YELLOW = "\033[33m" + /** Foreground color for ANSI blue */ final val BLUE = "\033[34m" + /** Foreground color for ANSI magenta */ final val MAGENTA = "\033[35m" + /** Foreground color for ANSI cyan */ final val CYAN = "\033[36m" + /** Foreground color for ANSI white */ final val WHITE = "\033[37m" - // ANSI colors background + /** Background color for ANSI black */ final val BLACK_B = "\033[40m" + /** Background color for ANSI red */ final val RED_B = "\033[41m" + /** Background color for ANSI green */ final val GREEN_B = "\033[42m" + /** Background color for ANSI yellow */ final val YELLOW_B = "\033[43m" + /** Background color for ANSI blue */ final val BLUE_B = "\033[44m" + /** Background color for ANSI magenta */ final val MAGENTA_B = "\033[45m" + /** Background color for ANSI cyan */ final val CYAN_B = "\033[46m" + /** Background color for ANSI white */ final val WHITE_B = "\033[47m" - // ANSI styles + /** Reset ANSI styles */ final val RESET = "\033[0m" + /** ANSI bold */ final val BOLD = "\033[1m" + /** ANSI underlines */ final val UNDERLINED = "\033[4m" + /** ANSI blink */ final val BLINK = "\033[5m" + /** ANSI reversed */ final val REVERSED = "\033[7m" + /** ANSI invisible */ final val INVISIBLE = "\033[8m" private val outVar = new DynamicVariable[PrintStream](java.lang.System.out) @@ -59,47 +78,57 @@ object Console { private val inVar = new DynamicVariable[BufferedReader]( new BufferedReader(new InputStreamReader(java.lang.System.in))) + /** The default output, can be overridden by `setOut` */ def out = outVar.value + /** The default error, can be overridden by `setErr` */ def err = errVar.value + /** The default input, can be overridden by `setIn` */ def in = inVar.value - /** Set the default output stream. + /** Sets the default output stream. * * @param out the new output stream. */ def setOut(out: PrintStream) { outVar.value = out } - /** Set the default output stream for the duration + /** Sets the default output stream for the duration * of execution of one thunk. * + * @example {{{ + * withOut(Console.err) { println("This goes to default _error_") } + * }}} + * * @param out the new output stream. * @param thunk the code to execute with * the new output stream active - * @return ... + * @return the results of `thunk` + * @see `withOut[T](out:OutputStream)(thunk: => T)` */ def withOut[T](out: PrintStream)(thunk: =>T): T = outVar.withValue(out)(thunk) - /** Set the default output stream. + /** Sets the default output stream. * * @param out the new output stream. */ def setOut(out: OutputStream): Unit = setOut(new PrintStream(out)) - /** Set the default output stream for the duration + /** Sets the default output stream for the duration * of execution of one thunk. * + * * @param out the new output stream. * @param thunk the code to execute with * the new output stream active - * @return ... + * @return the results of `thunk` + * @see `withOut[T](out:PrintStream)(thunk: => T)` */ def withOut[T](out: OutputStream)(thunk: =>T): T = withOut(new PrintStream(out))(thunk) - /** Set the default error stream. + /** Sets the default error stream. * * @param err the new error stream. */ @@ -107,35 +136,40 @@ object Console { /** Set the default error stream for the duration * of execution of one thunk. + * @example {{{ + * withErr(Console.out) { println("This goes to default _out_") } + * }}} * * @param err the new error stream. * @param thunk the code to execute with * the new error stream active - * @return ... + * @return the results of `thunk` + * @see `withErr[T](err:OutputStream)(thunk: =>T)` */ def withErr[T](err: PrintStream)(thunk: =>T): T = errVar.withValue(err)(thunk) - /** Set the default error stream. + /** Sets the default error stream. * * @param err the new error stream. */ def setErr(err: OutputStream): Unit = setErr(new PrintStream(err)) - /** Set the default error stream for the duration + /** Sets the default error stream for the duration * of execution of one thunk. * * @param err the new error stream. * @param thunk the code to execute with * the new error stream active - * @return ... + * @return the results of `thunk` + * @see `withErr[T](err:PrintStream)(thunk: =>T)` */ def withErr[T](err: OutputStream)(thunk: =>T): T = withErr(new PrintStream(err))(thunk) - /** Set the default input stream. + /** Sets the default input stream. * * @param reader specifies the new input stream. */ @@ -143,18 +177,29 @@ object Console { inVar.value = new BufferedReader(reader) } - /** Set the default input stream for the duration + /** Sets the default input stream for the duration * of execution of one thunk. * + * @example {{{ + * val someFile:Reader = openFile("file.txt") + * withIn(someFile) { + * // Reads a line from file.txt instead of default input + * println(readLine) + * } + * }}} + * * @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](in:InputStream)(thunk: =>T)` */ def withIn[T](reader: Reader)(thunk: =>T): T = inVar.withValue(new BufferedReader(reader))(thunk) - /** Set the default input stream. + /** Sets the default input stream. * * @param in the new input stream. */ @@ -162,81 +207,80 @@ object Console { setIn(new InputStreamReader(in)) } - /** Set the default input stream for the duration + /** Sets the default input stream for the duration * of execution of one thunk. * * @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)` */ def withIn[T](in: InputStream)(thunk: =>T): T = withIn(new InputStreamReader(in))(thunk) - /** Print an object on the terminal. + /** Prints an object to `out` using its `toString` method. * - * @param obj the object to print. + * @param obj the object to print; may be null. */ def print(obj: Any) { out.print(if (null == obj) "null" else obj.toString()) } - /** Flush the output stream. This function is required when partial - * output (i.e. output not terminated by a new line character) has + /** 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. */ def flush() { out.flush() } - /** Print a new line character on the terminal. + /** Prints a newline character on the default output. */ def println() { out.println() } - /** Print out an object followed by a new line character. + /** Prints out an object to the default output, followed by a newline character. * * @param x the object to print. */ def println(x: Any) { out.println(x) } - /**

- * Prints its arguments as a formatted string, based on a string + /** + * 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 * * java.util.Formatter. - *

* * @param text the pattern for formatting the arguments. * @param args the arguments used to instantiating the pattern. - * @throws java.lang.IllegalArgumentException + * @throws java.lang.IllegalArgumentException if there was a problem with the format string or arguments */ def printf(text: String, args: Any*) { out.print(text format (args : _*)) } - /** Read a full line from the terminal. Returns null if the end of the + /** Read a full line from the default input. Returns null if the end of the * input stream has been reached. * - * @return the string read from the terminal. + * @return the string read from the terminal or null if the end of stream was reached. */ def readLine(): String = in.readLine() - /** Print a formatted text and read a full line from the terminal. + /** Print formatted text to the default output and read a full line from the default input. * Returns null if the end of the input stream has been reached. * - * @param text the format of the text to print out. - * @param args the parameters used to instantiate the format. - * @return the string read from the terminal. + * @param text the format of the text to print out, as in `printf`. + * @param args the parameters used to instantiate the format, as in `printf`. + * @return the string read from the default input */ def readLine(text: String, args: Any*): String = { printf(text, args: _*) readLine() } - /** Read a boolean value from the terminal. - * Throws EOFException if the end of the - * input stream has been reached. + /** Reads a boolean value from an entire line of the default input. + * Has a fairly liberal interpretation of the input. * - * @return the boolean value read from the terminal. - * @throws java.io.EOFException + * @return the boolean value read, or false if it couldn't be converted to a boolean + * @throws java.io.EOFException if the end of the input stream has been reached. */ def readBoolean(): Boolean = { val s = readLine() @@ -252,11 +296,12 @@ object Console { } } - /** Read a byte value from the terminal. - * Throws EOFException if the end of the - * input stream has been reached. + /** Reads a byte value from an entire line of the default input. * - * @throws java.io.EOFException + * @return the Byte that was read + * @throws java.io.EOFException if the end of the + * input stream has been reached. + * @throws java.lang.NumberFormatException if the value couldn't be converted to a Byte */ def readByte(): Byte = { val s = readLine() @@ -266,11 +311,12 @@ object Console { s.toByte } - /** Read a short value from the terminal. - * Throws EOFException if the end of the - * input stream has been reached. + /** Reads a short value from an entire line of the default input. * - * @throws java.io.EOFException + * @return the short that was read + * @throws java.io.EOFException if the end of the + * input stream has been reached. + * @throws java.lang.NumberFormatException if the value couldn't be converted to a Short */ def readShort(): Short = { val s = readLine() @@ -280,11 +326,12 @@ object Console { s.toShort } - /** Read a char value from the terminal. - * Throws EOFException if the end of the - * input stream has been reached. + /** Reads a char value from an entire line of the default input. * - * @throws java.io.EOFException + * @return the Char that was read + * @throws java.io.EOFException if the end of the + * input stream has been reached. + * @throws java.lang.StringIndexOutOfBoundsException if the line read from default input was empty */ def readChar(): Char = { val s = readLine() @@ -294,11 +341,12 @@ object Console { s charAt 0 } - /** Read an int value from the terminal. - * Throws EOFException if the end of the - * input stream has been reached. + /** Reads an int value from an entire line of the default input. * - * @throws java.io.EOFException + * @return the Int that was read + * @throws java.io.EOFException if the end of the + * input stream has been reached. + * @throws java.lang.NumberFormatException if the value couldn't be converted to an Int */ def readInt(): Int = { val s = readLine() @@ -308,11 +356,12 @@ object Console { s.toInt } - /** Read an int value from the terminal. - * Throws EOFException if the end of the - * input stream has been reached. + /** Reads an long value from an entire line of the default input. * - * @throws java.io.EOFException + * @return the Long that was read + * @throws java.io.EOFException if the end of the + * input stream has been reached. + * @throws java.lang.NumberFormatException if the value couldn't be converted to a Long */ def readLong(): Long = { val s = readLine() @@ -322,11 +371,12 @@ object Console { s.toLong } - /** Read a float value from the terminal. - * Throws EOFException if the end of the + /** Reads a float value from an entire line of the default input. + * @return the Float that was read. + * @throws java.io.EOFException if the end of the * input stream has been reached. + * @throws java.lang.NumberFormatException if the value couldn't be converted to a Float * - * @throws java.io.EOFException */ def readFloat(): Float = { val s = readLine() @@ -336,11 +386,12 @@ object Console { s.toFloat } - /** Read a double value from the terminal. - * Throws EOFException if the end of the - * input stream has been reached. + /** Reads a double value from an entire line of the default input. * - * @throws java.io.EOFException + * @return the Double that was read. + * @throws java.io.EOFException if the end of the + * input stream has been reached. + * @throws java.lang.NumberFormatException if the value couldn't be converted to a Float */ def readDouble(): Double = { val s = readLine() @@ -350,15 +401,14 @@ object Console { s.toDouble } - /** Read in some structured input, specified by a format specifier. + /** Reads in some structured input (from the default input), specified by a format specifier. * See class java.text.MessageFormat for details of * the format specification. - * Throws EOFException if the end of the - * input stream has been reached. * * @param format the format of the input. * @return a list of all extracted values. - * @throws java.io.EOFException + * @throws java.io.EOFException if the end of the + * input stream has been reached. */ def readf(format: String): List[Any] = { val s = readLine() @@ -368,36 +418,30 @@ object Console { textComponents(new MessageFormat(format).parse(s)) } - /** Read in some structured input, specified by a format specifier. - * Opposed to readf, this function only returns the - * first value extracted from the input according to the format - * specification. + /** Reads in some structured input (from the default input), specified by a format specifier, returning + * only the first value extracted, according to the format specification. * - * @param format ... - * @return ... + * @param format format string, as accepted by `readf`. + * @return The first value that was extracted from the input */ def readf1(format: String): Any = readf(format).head - /** Read in some structured input, specified by a format specifier. - * Opposed to readf, this function only returns the - * first two values extracted from the input according to the format - * specification. + /** Reads in some structured input (from the default input), specified by a format specifier, returning + * only the first two values extracted, according to the format specification. * - * @param format ... - * @return ... + * @param format format string, as accepted by `readf`. + * @return A [[scala.Tuple2]] containing the first two values extracted */ def readf2(format: String): (Any, Any) = { val res = readf(format) (res.head, res.tail.head) } - /** Read in some structured input, specified by a format specifier. - * Opposed to readf, this function only returns the - * first three values extracted from the input according to the format - * specification. + /** Reads in some structured input (from the default input), specified by a format specifier, returning + * only the first three values extracted, according to the format specification. * - * @param format ... - * @return ... + * @param format format string, as accepted by `readf`. + * @return A [[scala.Tuple3]] containing the first three values extracted */ def readf3(format: String): (Any, Any, Any) = { val res = readf(format) -- cgit v1.2.3