UNPKG

4.76 kBMarkdownView Raw
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
5Output messages to the console.
6
7See the [log lib source](../lib/grunt/log.js) for more information.
8
9## The log API
10Grunt 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
15Log the specified `msg` string, with no trailing newline.
16
17```javascript
18grunt.log.write(msg)
19```
20
21### grunt.log.writeln / grunt.verbose.writeln
22Log the specified `msg` string, with trailing newline.
23
24```javascript
25grunt.log.writeln([msg])
26```
27
28### grunt.log.error / grunt.verbose.error
29If `msg` string is omitted, logs `ERROR` in red, otherwise logs `>> msg`, with trailing newline.
30
31```javascript
32grunt.log.error([msg])
33```
34
35### grunt.log.ok / grunt.verbose.ok
36If `msg` string is omitted, logs `OK` in green, otherwise logs `>> msg`, with trailing newline.
37
38```javascript
39grunt.log.ok([msg])
40```
41
42### grunt.log.subhead / grunt.verbose.subhead
43Log the specified `msg` string in **bold**, with trailing newline.
44
45```javascript
46grunt.log.subhead(msg)
47```
48
49### grunt.log.writeflags / grunt.verbose.writeflags
50Log a list of `obj` properties (good for debugging flags).
51
52```javascript
53grunt.log.writeflags(obj, prefix)
54```
55
56### grunt.log.debug / grunt.verbose.debug
57Logs a debugging message, but only if the `--debug` command-line option was specified.
58
59```javascript
60grunt.log.debug(msg)
61```
62
63## Verbose and Notverbose
64All 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
67This object contains all methods of `grunt.log` but only logs if the `--verbose` command-line option was specified.
68
69```javascript
70grunt.verbose
71```
72
73### grunt.verbose.or / grunt.log.notverbose
74This object contains all methods of `grunt.log` but only logs if the `--verbose` command-line option was _not_ specified.
75
76```javascript
77grunt.verbose.or
78```
79
80## Utility Methods
81These methods don't actually log, they just return strings that can be used in other methods.
82
83### grunt.log.wordlist
84Returns a comma-separated list of `arr` array items.
85
86```javascript
87grunt.log.wordlist(arr)
88```
89
90### grunt.log.uncolor
91Removes all color information from a string, making it suitable for testing `.length` or perhaps logging to a file.
92
93```javascript
94grunt.log.uncolor(str)
95```
96
97### grunt.log.wraptext
98Wrap `text` string to `width` characters with `\n`, ensuring that words are not split in the middle unless absolutely necessary.
99
100```javascript
101grunt.log.wraptext(width, text)
102```
103
104### grunt.log.table
105Wrap `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
108grunt.log.table(widths, texts)
109```
110
111
112## An Example
113
114A common pattern is to only log when in `--verbose` mode OR if an error occurs, like so:
115
116```javascript
117grunt.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
134An explanation of the above code:
135
1361. `grunt.verbose.write(msg);` logs the message (no newline), but only in `--verbose` mode.
1372. `grunt.verbose.ok();` logs OK in green, with a newline.
1383. `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).
1424. `grunt.fail.warn('Something went wrong.', 50);` logs a warning in bright yellow, exiting grunt with exit code 50, unless `--force` was specified.
143
144Take a look at the [built-in tasks source code](../tasks) for more examples.