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