1 | gulp-if ![status](https://secure.travis-ci.org/robrich/gulp-if.png?branch=master)
|
2 | =======
|
3 |
|
4 | A ternary gulp plugin: conditionally control the flow of vinyl objects.
|
5 |
|
6 | **Note**: Badly behaved plugins can often get worse when used with gulp-if. Typically the fix is not in gulp-if.
|
7 |
|
8 | **Note**: Works great with [lazypipe](https://github.com/OverZealous/lazypipe), see below
|
9 |
|
10 | ## Usage
|
11 |
|
12 | 1: Conditionally filter content
|
13 |
|
14 | **Condition**
|
15 |
|
16 | ![][condition]
|
17 |
|
18 | ```javascript
|
19 | var gulpif = require('gulp-if');
|
20 | var uglify = require('gulp-uglify');
|
21 |
|
22 | var condition = true; // TODO: add business logic
|
23 |
|
24 | gulp.task('task', function() {
|
25 | gulp.src('./src/*.js')
|
26 | .pipe(gulpif(condition, uglify()))
|
27 | .pipe(gulp.dest('./dist/'));
|
28 | });
|
29 | ```
|
30 | Only uglify the content if the condition is true, but send all the files to the dist folder
|
31 |
|
32 |
|
33 | 2: Ternary filter
|
34 |
|
35 | **Ternary**
|
36 |
|
37 | ![][ternary]
|
38 |
|
39 | ```javascript
|
40 | var gulpif = require('gulp-if');
|
41 | var uglify = require('gulp-uglify');
|
42 | var beautify = require('gulp-beautify');
|
43 |
|
44 | var condition = function (file) {
|
45 | // TODO: add business logic
|
46 | return true;
|
47 | }
|
48 |
|
49 | gulp.task('task', function() {
|
50 | gulp.src('./src/*.js')
|
51 | .pipe(gulpif(condition, uglify(), beautify()))
|
52 | .pipe(gulp.dest('./dist/'));
|
53 | });
|
54 | ```
|
55 |
|
56 | If condition returns true, uglify else beautify, then send everything to the dist folder
|
57 |
|
58 |
|
59 | 3: Remove things from the stream
|
60 |
|
61 | **Remove from here on**
|
62 |
|
63 | ![][exclude]
|
64 |
|
65 | ```javascript
|
66 | var gulpIgnore = require('gulp-ignore');
|
67 | var uglify = require('gulp-uglify');
|
68 | var jshint = require('gulp-jshint');
|
69 |
|
70 | var condition = './gulpfile.js';
|
71 |
|
72 | gulp.task('task', function() {
|
73 | gulp.src('./*.js')
|
74 | .pipe(jshint())
|
75 | .pipe(gulpIgnore.exclude(condition))
|
76 | .pipe(uglify())
|
77 | .pipe(gulp.dest('./dist/'));
|
78 | });
|
79 | ```
|
80 |
|
81 | Run JSHint on everything, remove gulpfile from the stream, then uglify and write everything else.
|
82 |
|
83 |
|
84 | 4: Exclude things from the stream
|
85 |
|
86 | **Exclude things from entering the stream**
|
87 |
|
88 | ![][glob]
|
89 |
|
90 | ```javascript
|
91 | var uglify = require('gulp-uglify');
|
92 |
|
93 | gulp.task('task', function() {
|
94 | gulp.src(['./*.js', '!./node_modules/**'])
|
95 | .pipe(uglify())
|
96 | .pipe(gulp.dest('./dist/'));
|
97 | });
|
98 | ```
|
99 |
|
100 | Grab all JavaScript files that aren't in the node_modules folder, uglify them, and write them.
|
101 | This is fastest because nothing in node_modules ever leaves `gulp.src()`
|
102 |
|
103 |
|
104 | ## works great with [lazypipe](https://github.com/OverZealous/lazypipe)
|
105 |
|
106 | Lazypipe creates a function that initializes the pipe chain on use. This allows you to create a chain of events inside the gulp-if condition. This scenario will run jshint analysis and reporter only if the linting flag is true.
|
107 |
|
108 | ```js
|
109 | var gulpif = require('gulp-if');
|
110 | var jshint = require('gulp-jshint');
|
111 | var uglify = require('gulp-uglify');
|
112 | var lazypipe = require('lazypipe');
|
113 |
|
114 | var linting = false;
|
115 | var compressing = false;
|
116 |
|
117 | var jshintChannel = lazypipe()
|
118 | // adding a pipeline step
|
119 | .pipe(jshint) // notice the stream function has not been called!
|
120 | .pipe(jshint.reporter)
|
121 | // adding a step with an argument
|
122 | .pipe(jshint.reporter, 'fail');
|
123 |
|
124 | gulp.task('scripts', function () {
|
125 | return gulp.src(paths.scripts.src)
|
126 | .pipe(gulpif(linting, jshintChannel()))
|
127 | .pipe(gulpif(compressing, uglify()))
|
128 | .pipe(gulp.dest(paths.scripts.dest));
|
129 | });
|
130 | ```
|
131 | [source](https://github.com/spenceralger/gulp-jshint/issues/38#issuecomment-40423932)
|
132 |
|
133 | ## works great inside [lazypipe](https://github.com/OverZealous/lazypipe)
|
134 |
|
135 | Lazypipe assumes that all function parameters are static, gulp-if arguments need to be instantiated inside each lazypipe. This difference can be easily solved by passing a function on the lazypipe step
|
136 |
|
137 | ```js
|
138 | var gulpif = require('gulp-if');
|
139 | var jshint = require('gulp-jshint');
|
140 | var uglify = require('gulp-uglify');
|
141 | var lazypipe = require('lazypipe');
|
142 |
|
143 | var compressing = false;
|
144 |
|
145 | var jsChannel = lazypipe()
|
146 | // adding a pipeline step
|
147 | .pipe(jshint) // notice the stream function has not been called!
|
148 | .pipe(jshint.reporter)
|
149 | // adding a step with an argument
|
150 | .pipe(jshint.reporter, 'fail')
|
151 | // you can't say: .pipe(gulpif, compressing, uglify)
|
152 | // because uglify needs to be instantiated separately in each lazypipe instance
|
153 | // you can say this instead:
|
154 | .pipe(function () {
|
155 | return gulpif(compressing, uglify());
|
156 | });
|
157 | // why does this work? lazypipe calls the function, passing in the no arguments to it,
|
158 | // it instantiates a new gulp-if pipe and returns it to lazypipe.
|
159 |
|
160 | gulp.task('scripts', function () {
|
161 | return gulp.src(paths.scripts.src)
|
162 | .pipe(jsChannel())
|
163 | .pipe(gulp.dest(paths.scripts.dest));
|
164 | });
|
165 | ```
|
166 |
|
167 | [source](https://github.com/robrich/gulp-if/issues/32)
|
168 |
|
169 | ## gulp-if API
|
170 |
|
171 | ### gulpif(condition, stream [, elseStream, [, minimatchOptions]])
|
172 |
|
173 | gulp-if will pipe data to `stream` whenever `condition` is truthy.
|
174 |
|
175 | If `condition` is falsey and `elseStream` is passed, data will pipe to `elseStream`
|
176 |
|
177 | After data is piped to `stream` or `elseStream` or neither, data is piped down-stream.
|
178 |
|
179 | #### Parameters
|
180 |
|
181 | ##### condition
|
182 |
|
183 | Type: `boolean` or [`stat`](http://nodejs.org/api/fs.html#fs_class_fs_stats) object or `function` that takes in a vinyl file and returns a boolean or `RegularExpression` that works on the `file.path`
|
184 |
|
185 | The condition parameter is any of the conditions supported by [gulp-match](https://github.com/robrich/gulp-match). The `file.path` is passed into `gulp-match`.
|
186 |
|
187 | If a function is given, then the function is passed a vinyl `file`. The function should return a `boolean`.
|
188 |
|
189 | ##### stream
|
190 |
|
191 | Stream for gulp-if to pipe data into when condition is truthy.
|
192 |
|
193 | ##### elseStream
|
194 |
|
195 | Optional, Stream for gulp-if to pipe data into when condition is falsey.
|
196 |
|
197 | ##### minimatchOptions
|
198 |
|
199 | Optional, if it's a glob condition, these options are passed to [minimatch](https://github.com/isaacs/minimatch).
|
200 |
|
201 |
|
202 | LICENSE
|
203 | -------
|
204 |
|
205 | (MIT License)
|
206 |
|
207 | Copyright (c) 2014 [Richardson & Sons, LLC](http://richardsonandsons.com/)
|
208 |
|
209 | Permission is hereby granted, free of charge, to any person obtaining
|
210 | a copy of this software and associated documentation files (the
|
211 | "Software"), to deal in the Software without restriction, including
|
212 | without limitation the rights to use, copy, modify, merge, publish,
|
213 | distribute, sublicense, and/or sell copies of the Software, and to
|
214 | permit persons to whom the Software is furnished to do so, subject to
|
215 | the following conditions:
|
216 |
|
217 | The above copyright notice and this permission notice shall be
|
218 | included in all copies or substantial portions of the Software.
|
219 |
|
220 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
221 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
222 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
223 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
224 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
225 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
226 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
227 |
|
228 | [condition]: https://rawgithub.com/robrich/gulp-if/master/img/condition.svg
|
229 | [ternary]: https://rawgithub.com/robrich/gulp-if/master/img/ternary.svg
|
230 | [exclude]: https://rawgithub.com/robrich/gulp-if/master/img/exclude.svg
|
231 | [glob]: https://rawgithub.com/robrich/gulp-if/master/img/glob.svg
|