1 | [Grunt homepage](https://github.com/cowboy/grunt) | [Documentation table of contents](toc.md)
|
2 |
|
3 | # [The grunt API](api.md) / grunt.log, grunt.verbose
|
4 |
|
5 | Output messages to the console.
|
6 |
|
7 | See the [log lib source](../lib/grunt/log.js) for more information.
|
8 |
|
9 | ## The log API
|
10 | Grunt output should look consistent, and maybe even pretty. As such, there is a plethora of logging methods, and a few useful patterns. All of the methods that actually log something are chainable.
|
11 |
|
12 | _Note: all methods available under `grunt.verbose` work exactly like `grunt.log` methods, but only log if the `--verbose` command-line option was specified._
|
13 |
|
14 | ### grunt.log.write / grunt.verbose.write
|
15 | Log the specified `msg` string, with no trailing newline.
|
16 |
|
17 | ```javascript
|
18 | grunt.log.write(msg)
|
19 | ```
|
20 |
|
21 | ### grunt.log.writeln / grunt.verbose.writeln
|
22 | Log the specified `msg` string, with trailing newline.
|
23 |
|
24 | ```javascript
|
25 | grunt.log.writeln([msg])
|
26 | ```
|
27 |
|
28 | ### grunt.log.error / grunt.verbose.error
|
29 | If `msg` string is omitted, logs `ERROR` in red, otherwise logs `>> msg`, with trailing newline.
|
30 |
|
31 | ```javascript
|
32 | grunt.log.error([msg])
|
33 | ```
|
34 |
|
35 | ### grunt.log.ok / grunt.verbose.ok
|
36 | If `msg` string is omitted, logs `OK` in green, otherwise logs `>> msg`, with trailing newline.
|
37 |
|
38 | ```javascript
|
39 | grunt.log.ok([msg])
|
40 | ```
|
41 |
|
42 | ### grunt.log.subhead / grunt.verbose.subhead
|
43 | Log the specified `msg` string in **bold**, with trailing newline.
|
44 |
|
45 | ```javascript
|
46 | grunt.log.subhead(msg)
|
47 | ```
|
48 |
|
49 | ### grunt.log.writeflags / grunt.verbose.writeflags
|
50 | Log a list of `obj` properties (good for debugging flags).
|
51 |
|
52 | ```javascript
|
53 | grunt.log.writeflags(obj, prefix)
|
54 | ```
|
55 |
|
56 | ### grunt.log.debug / grunt.verbose.debug
|
57 | Logs a debugging message, but only if the `--debug` command-line option was specified.
|
58 |
|
59 | ```javascript
|
60 | grunt.log.debug(msg)
|
61 | ```
|
62 |
|
63 | ## Verbose and Notverbose
|
64 | All logging methods available under `grunt.verbose` work exactly like their `grunt.log` counterparts, but only log if the `--verbose` command-line option was specified. There is also a "notverbose" counterpart available at both `grunt.log.notverbose` and `grunt.log.verbose.or`. In fact, the `.or` property can be used on both `verbose` and `notverbose` to effectively toggle between the two.
|
65 |
|
66 | ### grunt.verbose / grunt.log.verbose
|
67 | This object contains all methods of `grunt.log` but only logs if the `--verbose` command-line option was specified.
|
68 |
|
69 | ```javascript
|
70 | grunt.verbose
|
71 | ```
|
72 |
|
73 | ### grunt.verbose.or / grunt.log.notverbose
|
74 | This object contains all methods of `grunt.log` but only logs if the `--verbose` command-line option was _not_ specified.
|
75 |
|
76 | ```javascript
|
77 | grunt.verbose.or
|
78 | ```
|
79 |
|
80 | ## Utility Methods
|
81 | These methods don't actually log, they just return strings that can be used in other methods.
|
82 |
|
83 | ### grunt.log.wordlist
|
84 | Returns a comma-separated list of `arr` array items.
|
85 |
|
86 | ```javascript
|
87 | grunt.log.wordlist(arr)
|
88 | ```
|
89 |
|
90 | ### grunt.log.uncolor
|
91 | Removes all color information from a string, making it suitable for testing `.length` or perhaps logging to a file.
|
92 |
|
93 | ```javascript
|
94 | grunt.log.uncolor(str)
|
95 | ```
|
96 |
|
97 | ### grunt.log.wraptext
|
98 | Wrap `text` string to `width` characters with `\n`, ensuring that words are not split in the middle unless absolutely necessary.
|
99 |
|
100 | ```javascript
|
101 | grunt.log.wraptext(width, text)
|
102 | ```
|
103 |
|
104 | ### grunt.log.table
|
105 | Wrap `texts` array of strings to columns `widths` characters wide. A wrapper for the `grunt.log.wraptext` method that can be used to generate output in columns.
|
106 |
|
107 | ```javascript
|
108 | grunt.log.table(widths, texts)
|
109 | ```
|
110 |
|
111 |
|
112 | ## An Example
|
113 |
|
114 | A common pattern is to only log when in `--verbose` mode OR if an error occurs, like so:
|
115 |
|
116 | ```javascript
|
117 | grunt.registerHelper('something', function(arg) {
|
118 | var result;
|
119 | var msg = 'Doing something...';
|
120 | grunt.verbose.write(msg);
|
121 | try {
|
122 | result = doSomethingThatThrowsAnExceptionOnError(arg);
|
123 | // Success!
|
124 | grunt.verbose.ok();
|
125 | return result;
|
126 | } catch(e) {
|
127 | // Something went wrong.
|
128 | grunt.verbose.or.write(msg).error().error(e.message);
|
129 | grunt.fail.warn('Something went wrong.', 50);
|
130 | }
|
131 | });
|
132 | ```
|
133 |
|
134 | An explanation of the above code:
|
135 |
|
136 | 1. `grunt.verbose.write(msg);` logs the message (no newline), but only in `--verbose` mode.
|
137 | 2. `grunt.verbose.ok();` logs OK in green, with a newline.
|
138 | 3. `grunt.verbose.or.write(msg).error().error(e.message);` does a few things:
|
139 | 1. `grunt.verbose.or.write(msg)` logs the message (no newline) if not in `--verbose` mode, and returns the `notverbose` object.
|
140 | 2. `.error()` logs ERROR in red, with a newline, and returns the `notverbose` object.
|
141 | 3. `.error(e.message);` logs the actual error message (and returns the `notverbose` object).
|
142 | 4. `grunt.fail.warn('Something went wrong.', 50);` logs a warning in bright yellow, exiting grunt with exit code 50, unless `--force` was specified.
|
143 |
|
144 | Take a look at the [built-in tasks source code](../tasks) for more examples.
|