diff --git a/tools/console.js b/tools/console.js index c67d50ae31..7db7fa4321 100644 --- a/tools/console.js +++ b/tools/console.js @@ -1,19 +1,60 @@ +/// This class provides a set of utility functions for printing to the terminal +/// in the Meteor tool. /// -/// A set of utility functions for formatting output sent to the screen. +/// When you intend for your messages to be read by humans, you should use the +/// following functions to print to the terminal. They will automatically line +/// wrap output to either the width of the terminal, or 80 characters. They +/// will also end in a new line. /// -/// Console offers several pieces of functionality: -/// - debug / info / warn messages: Output to the screen, optionally with -/// colors (when pretty == true). Wrap the output to the width of the user's -/// terminal, making sure to not split the same word over multiple -/// lines. (Also provides 'rawInfo', 'rawDebug' (etc) for when you DON'T want -/// to pre-process the output.) -/// - Progress bar support -/// Display a progress bar on the screen, but hide it around log messages. +//// - Console.info : Print to stdout. +/// - Console.error: Print to stderr. +/// - Console.warn: Prints to stderr, if warnings are enabled. +/// - Console.debug: Prints to stdout, if debug is enabled. /// -/// In future, we might do things like move all support for verbose mode in -/// here, and also integrate the buildmessage functionality into here +/// Sometimes, there is a phrase that shouldn't be split up over multiple +/// lines (for example, 'meteor update'). When applicable, please use the +/// following functions (Some of them add aditional formatting, especially when +/// pretty-print is turned on): /// - +/// - Console.command: things to enter on the command-line, such as +/// 'meteor update' or 'cd foobar'. +/// - Console.url: URLs, such as 'www.meteor.com' +/// - Console.path: filepaths outside of Console.command. +/// - Console.noWrap: anything else that you don't want line-wrapped. +/// +/// Here is a contrived example: +/// Console.info( +/// "For more information, please run", Console.command("meteor show"), +/// "or check out the new releases at", Console.url("www.meteor.com"), +/// "or look at", Console.path(filepath), ". You are currently running", +/// "Console.noWrap("Meteor version 1.5") + "."); +/// +/// The Console.info/Console.error/Console.warn/Console.debug functions also +/// take in Console.options, as a last (optional) argument. These allow you to +/// set an indent or use a bulletpoint. You can check out their API below. If +/// possible, you might also want to use one of the existing wrapper functions, +/// such as Console.labelWarning or Console.arrowInfo. +/// +/// Output intended for machines (or pre-formatted in specific ways) should NOT +/// be line-wrapped. Do not wrap these things: JSON output, error stack traces, +/// logs from other programs, etc. For those, you should use the 'raw' +/// version of the API: +/// +/// - Console.rawInfo: Like Console.info, but without formatting. +/// - Console.rawError: Like Console.error, but without formatting. +/// - Console.rawWarn: Like Console.warn, but without formatting. +/// - Console.rawDebug: Like Console.debug, but without formatting. +/// +/// DO NOT use Console.command/Console.url/Console.path with the raw functions! +/// (They will change your output in ways that you probably do not want). These +/// don't auto-linewrap, end in a newline, or take in Console.options. +/// +/// Here is are some examples: +/// Console.rawInfo(JSON.stringify(myData, null, 2)); +/// Console.rawError(err.stack + "\n"); +/// +/// In addition to printing functions, the Console class provides progress bar +/// support, that is mostly handled through buildmessage.js. var _ = require('underscore'); var Fiber = require('fibers'); var Future = require('fibers/future'); @@ -615,10 +656,29 @@ _.extend(Console.prototype, { } }, - // Initializes and returns a new ConsoleOptions object. This allows us to call - // 'instance of' on the ConsoleOptions in parseVariadicInput, by ensuring that - // the object created with Console.options is, in fact, a new object. + // Initializes and returns a new ConsoleOptions object. Takes in the following + // Console options to pass to _wrapText eventually. + // + // - bulletPoint: start the first line with a given string, then offset the + // subsequent lines by the length of that string. For example, if the + // bulletpoint is " => ", we would get: + // " => some long message starts here + // and then continues here." + // - indent: offset the entire string by a specific number of + // characters. For example: + // " This entire message is indented + // by two characters." + // + // Passing in both options will offset the bulletPoint by the indentation, + // like so: + // " this message is indented by two." + // " => this mesage indented by two and + // and also starts with an arrow." + // options: function (o) { + // (This design pattern allows us to call 'instance of' on the + // ConsoleOptions in parseVariadicInput, by ensuring that the object created + // with Console.options is, in fact, a new object. return new ConsoleOptions(o); }, @@ -1036,25 +1096,9 @@ _.extend(Console.prototype, { // // text: the text to wrap // options: - - // - bulletPoint: start the first line with a given string, then offset the - // subsequent lines by the length of that string. For example, if the - // bulletpoint is " => ", we would get: - // " => some long message starts here - // and then continues here." - // - indent: offset the entire string by a specific number of - // characters. For example: - // " This entire message is indented - // by two characters." + // - bulletPoint: (see: Console.options) + // - indent: (see: Console.options) // - // Passing in both options will offset the bulletPoint by the indentation, - // like so: - // " this message is indented by two." - // " => this mesage indented by two and - // and also starts with an arrow." - // - // When printing commands in-line, it is best to wrap commands in with Console.command - // to make sure that they don't get line-wrapped. See Console.command for more details. _wrapText: function (text, options) { var self = this; options = options || {};