1 | # gulp-util [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Dependency Status][depstat-image]][depstat-url]
|
2 |
|
3 | ## Information
|
4 |
|
5 | <table>
|
6 | <tr>
|
7 | <td>Package</td><td>gulp-util</td>
|
8 | </tr>
|
9 | <tr>
|
10 | <td>Description</td>
|
11 | <td>Utility functions for gulp plugins</td>
|
12 | </tr>
|
13 | <tr>
|
14 | <td>Node Version</td>
|
15 | <td>>= 0.10</td>
|
16 | </tr>
|
17 | </table>
|
18 |
|
19 | ## Usage
|
20 |
|
21 | ```javascript
|
22 | var gutil = require('gulp-util');
|
23 |
|
24 | gutil.log('stuff happened', 'Really it did', gutil.colors.magenta('123'));
|
25 |
|
26 | gutil.replaceExtension('file.coffee', '.js'); // file.js
|
27 |
|
28 | var opt = {
|
29 | name: 'todd',
|
30 | file: someGulpFile
|
31 | };
|
32 | gutil.template('test <%= name %> <%= file.path %>', opt) // test todd /js/hi.js
|
33 | ```
|
34 |
|
35 | ### log(msg...)
|
36 |
|
37 | Logs stuff. Already prefixed with [gulp] and all that. If you pass in multiple arguments it will join them by a space.
|
38 |
|
39 | The default gulp coloring using gutil.colors.<color>:
|
40 | ```
|
41 | values (files, module names, etc.) = cyan
|
42 | numbers (times, counts, etc) = magenta
|
43 | ```
|
44 |
|
45 | ### colors
|
46 |
|
47 | Is an instance of [chalk](https://github.com/sindresorhus/chalk).
|
48 |
|
49 | ### replaceExtension(path, newExtension)
|
50 |
|
51 | Replaces a file extension in a path. Returns the new path.
|
52 |
|
53 | ### isStream(obj)
|
54 |
|
55 | Returns true or false if an object is a stream.
|
56 |
|
57 | ### isBuffer(obj)
|
58 |
|
59 | Returns true or false if an object is a Buffer.
|
60 |
|
61 | ### template(string[, data])
|
62 |
|
63 | This is a lodash.template function wrapper. You must pass in a valid gulp file object so it is available to the user or it will error. You can not configure any of the delimiters. Look at the [lodash docs](http://lodash.com/docs#template) for more info.
|
64 |
|
65 | ## new File(obj)
|
66 |
|
67 | This is just [vinyl](https://github.com/wearefractal/vinyl)
|
68 |
|
69 | ```javascript
|
70 | var file = new gutil.File({
|
71 | base: path.join(__dirname, './fixtures/'),
|
72 | cwd: __dirname,
|
73 | path: path.join(__dirname, './fixtures/test.coffee')
|
74 | });
|
75 | ```
|
76 |
|
77 | ## noop()
|
78 |
|
79 | Returns a stream that does nothing but pass data straight through.
|
80 |
|
81 | ```javascript
|
82 | // gulp should be called like this :
|
83 | // $ gulp --type production
|
84 | gulp.task('scripts', function() {
|
85 | gulp.src('src/**/*.js')
|
86 | .pipe(concat('script.js'))
|
87 | .pipe(gutil.env.type === 'production' ? uglify() : gutil.noop())
|
88 | .pipe(gulp.dest('dist/'));
|
89 | });
|
90 | ```
|
91 |
|
92 | ## buffer(cb)
|
93 |
|
94 | This is similar to es.wait but instead of buffering text into one string it buffers anything into an array (so very useful for file objects).
|
95 |
|
96 | Returns a stream that can be piped to.
|
97 |
|
98 | The stream will emit one data event after the stream piped to it has ended. The data will be the same array passed to the callback.
|
99 |
|
100 | Callback is optional and receives two arguments: error and data
|
101 |
|
102 | ```javascript
|
103 | gulp.src('stuff/*.js')
|
104 | .pipe(gutil.buffer(function(err, files) {
|
105 |
|
106 | }));
|
107 | ```
|
108 |
|
109 | ## new PluginError(pluginName, message[, options])
|
110 |
|
111 | - pluginName should be the module name of your plugin
|
112 | - message can be a string or an existing error
|
113 | - By default the stack will not be shown. Set `options.showStack` to true if you think the stack is important for your error.
|
114 | - If you pass an error in as the message the stack will be pulled from that, otherwise one will be created.
|
115 | - Note that if you pass in a custom stack string you need to include the message along with that.
|
116 | - Error properties will be included in `err.toString()`. Can be omitted by including `{showProperties: false}` in the options.
|
117 |
|
118 | These are all acceptable forms of instantiation:
|
119 |
|
120 | ```javascript
|
121 | var err = new gutil.PluginError('test', {
|
122 | message: 'something broke'
|
123 | });
|
124 |
|
125 | var err = new gutil.PluginError({
|
126 | plugin: 'test',
|
127 | message: 'something broke'
|
128 | });
|
129 |
|
130 | var err = new gutil.PluginError('test', 'something broke');
|
131 |
|
132 | var err = new gutil.PluginError('test', 'something broke', {showStack: true});
|
133 |
|
134 | var existingError = new Error('OMG');
|
135 | var err = new gutil.PluginError('test', existingError, {showStack: true});
|
136 | ```
|
137 |
|
138 | [npm-url]: https://www.npmjs.com/package/gulp-util
|
139 | [npm-image]: https://badge.fury.io/js/gulp-util.svg
|
140 | [travis-url]: https://travis-ci.org/gulpjs/gulp-util
|
141 | [travis-image]: https://img.shields.io/travis/gulpjs/gulp-util.svg?branch=master
|
142 | [coveralls-url]: https://coveralls.io/r/gulpjs/gulp-util
|
143 | [coveralls-image]: https://img.shields.io/coveralls/gulpjs/gulp-util.svg
|
144 | [depstat-url]: https://david-dm.org/gulpjs/gulp-util
|
145 | [depstat-image]: https://david-dm.org/gulpjs/gulp-util.svg
|