-
Notifications
You must be signed in to change notification settings - Fork 16
/
vinyl.node.txt
456 lines (369 loc) · 28.1 KB
/
vinyl.node.txt
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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
VINYL
VERSION ==> #Node module (3.0.0)
#Abstraction of a file (virtual file) content and metadata.
/=+===============================+=\
/ : : \
)==: CORE :==(
\ :_______________________________: /
\=+===============================+=/
new Vinyl([OPTS]) #OPTS are setting VINYL.*
#Paths are normalized.
VINYL.path #Absolute 'PATH'
VINYL.relative #Relative 'PATH'
VINYL.base #'DIR' used for relative paths (def: VINYL.cwd)
VINYL.cwd #'DIR' (def: process.cwd())
VINYL.dirname|basename|stem| #Get|set VINYL.path
extname #VINYL.stem is filename without extname
VINYL.history #'PATH'_ARR of all present|past VINYL.path
VINYL.contents #BUFFER|ISTREAM|null
VINYL.stat #FSSTAT|null
VINYL.symlink #'PATH'|null
#Must be manually set by the adapter (i.e. not deduced from VINYL.stat)
#This is set by ADAPTER-FS
Vinyl.isVinyl(VAL)->BOOL #
Vinyl.isCustomProp('PROP')->BOOL#Whether it is a core VINYL.* property
VINYL.isBuffer|Stream|Null()
->BOOL #According to VINYL.contents
VINYL.isDirectory|isSymbolic()
->BOOL #According to VINYL.stat
VINYL.clone([OPTS])->VINYL2 #OPTS:
# - deep BOOL (def: true)
# - contents BOOL (def: true): if false, re-use BUFFER if contents is BUFFER
VINYL[util.inspect.custom] #'<File PATH CONTENT_SUMMARY>'
EXTENDING VINYL ==> #Should override:
# - isCustomProp(): to return true for new properties, so they are not cloned by default
# - clone(): to specify how to clone new properties
/=+===============================+=\
/ : : \
)==: ADAPTERS :==(
\ :_______________________________: /
\=+===============================+=/
ADAPTER #Common interface for all adapters of VINYL
ADAPTER.src('FILES'[, OPTS]) #IOSTREAM in Object mode reading files, i.e. where each data event emits a VINYL
->IOSTREAM #Since is is an IOSTREAM, can be piped in as well, e.g. ADAPTER.src(...).pipe(ADAPTER.src(...))
ADAPTER.dest('DIR'[, OPTS]) #IOSTREAM in Object mode writing files
->IOSTREAM #Since it is an IOSTREAM, can be piped out as well, e.g. ADAPTER.src(...).pipe(ADAPTER.dest(...)).pipe(ADAPTER.dest(...))
VINYL-FS ##Vinyl adapter for the filesystem
##Version 4.0.0
VINYL-FS.src ##OPTS:
('GLOB'[_ARR][, OPTS]) ## - any passed to GLOB-STREAM (see its doc)
->IOSTREAM ## - buffer BOOL: if true (def), sets full contents as BUFFER instead of STREAMing it
## - read BOOL:
## - if false (def: true), do not read files content
## - i.e. VINYL.contents will be null, and VINYL-FS.dest() will not do anything
## - faster when files content is not used, e.g. only deleting files
## - since DATE[_NUM]: filter files by mtime|ctime
## - removeBOM BOOL: if true (def), remove UTF-8 BOM
## - resolveSymlinks BOOL (def: true)
## - sourcemaps BOOL (see source maps doc below)
## - encoding 'ENCODING' (def: 'utf8') or false (no conversion)
##All OPTS can be a FUNC(VINYL)->VAL
VINYL-FS.dest ##OPTS:
('DIR'[(VINYL)][, OPTS]) ## - cwd 'PATH' (def: process.cwd()): for relative 'DIR'
->IOSTREAM ## - overwrite BOOL (def: true): if input path is same as output
## - append BOOL (def: false): append instead of overwriting
## - mode NUM (def: no change): sets FSSTAT.mode for non-directories
## - dirMode NUM (def: process mode): sets FSSTAT.mode for directories
## - relativeSymlinks BOOL: whether created symlinks should be absolute (false, def) or relative (true)
## - sourcemaps BOOL|'PATH' (see source maps doc below)
## - encoding 'ENCODING' (def: 'utf8') or false (no conversion)
##All OPTS can be a FUNC(VINYL)->VAL
##If VINYL.symlink 'PATH' exists, a symlink will be created
VINYL-FS.symlink ##Creates symlinks
('DIR'[(VINYL)][, OPTS]) ##OPTS:
->IOSTREAM ## - cwd|overwrite|dirMode|relativeSymlinks: like VINYL-FS.dest()
/=+===============================+=\
/ : : \
)==: COMPATIBILITY :==(
\ :_______________________________: /
\=+===============================+=/
BUFFER-TO-VINYL.file ##Transforms BUFFER into VINYL with:
(BUFFER[, 'PATH'])->VINYL ## - contents BUFFER
## - path 'PATH' (def: UUIDv4.EXT)
##Version 1.1.0
BUFFER-TO-VINYL.stream ##Same but as IOSTREAM containing a single VINYL
(BUFFER[, 'PATH'])->IOSTREAM ##Prefer GULP-FILE, more maintained
GULP-FILE ##Transforms BUFFER|STR into IOSTREAM containing a single VINYL
('PATH', BUFFER|STR[, OPTS]) ##If OPTS.src true (def: false), calls IOSTREAM.end() (to do if used as first stream)
->IOSTREAM ##Version 0.4.0
GULP-FILE(OBJ_ARR) ##Same with OBJ: name, source
VINYL-BUFFER()->IOSTREAM ##IOSTREAM that modifies VINYL.contents from STREAM|BUFFER to BUFFER
##Good for plugins that do not support contents STREAM
##Version 1.0.1
VINYL-SOURCE-STREAM ##IOSTREAM that:
(['PATH'][, 'BASEDIR']) ## - takes a normal ISTREAM as input
->IOSTREAM ## - output a VINYL OSTREAM
## - containing a single VINYL with contents ISTREAM, filename 'PATH', base 'BASEDIR'
##Node module (2.0.0)
/=+===============================+=\
/ : : \
)==: MAPPING :==(
\ :_______________________________: /
\=+===============================+=/
VINYL-MAP(FUNC(BUFFER, 'PATH'))##IOSTREAM that modifies VINYL.contents
->IOSTREAM ##FUNC must return:
## - BUFFER|STR
## - undefined: "no modification"
##Version 1.0.2
/=+===============================+=\
/ : : \
)==: FILESYSTEM :==(
\ :_______________________________: /
\=+===============================+=/
GULP-RENAME(VAL) ##Rename filenames. VAL can be:
## - FILENAME_STR (single file)
## - OBJ: dirname STR, basename STR, prefix STR, suffix STR, extname STR
## (e.g. ".js")
## - FUNC(OBJ)->OBJ, with same OBJ as above
##Version 1.2.0
GULP-SYMLINK.relative|absolute ##Creates a symlink in DIR (creates it if not existing, overwrite if OBJ.force
(DIR_ARR| ##true) with same filename as current file, poiting to that file (with a
FUNC(VINYL)->VINYL[,OBJ]) ##relative|absolute path).
##Version 2.0.1
/=+===============================+=\
/ : : \
)==: FILTERING :==(
\ :_______________________________: /
\=+===============================+=/
GULP-MATCH(VINYL, VAL[, OPTS]) ##Returns BOOL according to VAL:
->BOOL ## - BOOL2[(VINYL)]
## - '*.EXT'
## - REGEXP: against VINYL.relative
## - 'GLOB'[_ARR]: against VINYL.relative, using MINIMATCH (with OPTS)
## - { isFile|isDirectory BOOL }
##Version 1.1.0
GULP-IF(VAL, IOSTREAM2, ##IOSTREAM that:
IOSTREAM3[, OPTS])->IOSTREAM ## - takes a VINYL ISTREAM as input
## - pipe into either IOSTREAM2|IOSTREAM3 depending on each GULP-MATCH(VINYL, VAL[, OPTS])
##Version 3.0.0
GULP-IGNORE[.include|exclude] ##IOSTREAM that only keeps the VINYL [not] satisfying GULP-MATCH(VINYL, VAL[, OPTS])
(VAL[, OPTS])->IOSTREAM ##Version 3.0.0
GULP-FILTER ##IOSTREAM that only keeps the VINYL satisfying VAL, either:
('GLOB'[_ARR][, OPTS]) ## - 'GLOB'[_ARR]: MULTIMATCH('PATH', 'GLOB'[_ARR], OPTS)
->IOSTREAM ## - FUNC(VINYL)->BOOL
##Version 8.0.0
IOSTREAM.restore ##IOSTREAM2 that puts back the VINYLs that were excluded
##Must set OPTS.restore true to be defined
##If OPTS.passthrough false, is ISTREAM2, not IOSTREAM2
GULP-CHANGED ##Excludes VINYL that have been modified after DIR files (usually same DIR as GULP.dest(DIR))
('DIR'[(VINYL)][, OPTS]) ##OPTS:
->IOSTREAM ## - transformPath('PATH')->'PATH': temporarily change VINYL.path, for matching purpose
## - extension '.EXT': same but only with extension
## - cwd 'DIR' (def: process.cwd())
## - hasChanged FUNC(IOSTREAM, VINYL, 'PATH')->[PROMISE_]BOOL: customize what 'has been modified' means
## - GULP-CHANGED.compareLastModifiedTime (def): compare mtime
## - GULP-CHANGED.compareContents (def): compare contents
##Version 4.0.3
GULP-NEWER ==> ##Similar to GULP-CHANGED (prefered)
GULP-CACHED('NAME'[, OPTS]) ##Caches each VINYL in-memory. Re-use them on later calls unless they have been modified since (using mtime).
->IOSTREAM ##Prefer GULP.lastRun() which achieves same goal, except when extra flexibility is needed
##OPTS:
## - optimizeMemory BOOL (def: false):
## - stores file contents MD5 instead of in full
## - i.e. more CPU intensive but less memory
##Version 1.1.1
GULP-CACHED.caches.NAME ##Can be deleted
/=+===============================+=\
/ : : \
)==: ERROR HANDLING :==(
\ :_______________________________: /
\=+===============================+=/
[new] PLUGIN-ERROR([OPTS]) ##Type of Error to throw in plugins
->ERROR ##Only difference is that it has a nice standardized ERROR.toString()
##OPTS:
## - plugin 'PLUGIN'
## - message 'ERROR' or error ERROR
## - name STR (def: 'Error')
## - showStack BOOL (def: false)
## - fileName STR
## - lineNumber NUM
## - stack STR (def: current one)
## - any other will be printed under 'Details:', except if showProperties BOOL false
##Version 2.0.1
[new] PLUGIN-ERROR('PLUGIN'
[, 'ERROR'|ERROR][, OPTS]) ##Same with OPTS.plugin|message|error
PROBLEM WITH ERRORS IN STREAMS ##When one STREAM errors:
==> ## - the STREAM it is piped into are not errored
## - i.e. the final STREAM will look successful
## - with Gulp, this means the task will show as successful,
## and the next tasks will continue
## - the STREAM it is piped into are not closed, i.e. they remain open
## - the error is not handled, i.e. it will throw an uncaught exception
## - with Gulp, this stops GULP.watch()
##Solutions:
## - since Gulp 4, returning STREAM just works
## - but does not work if function is async
## - returning STREAM.pipe(...), Stream.pipeline(STREAM,...) or PUMP(STREAM,...) (see its doc)
## does not make any difference
## - STREAM.pipe(...) is prefered
## - Stream.pipeline(...) is problematic as it overrides close event handlers and since
## STREAMs are errored before consumption, it only shows an error related to that and not
## the actual error
## - GULP-PLUMBER: does not work with Gulp 4
GULP-PLUMBER([OPTS])->IOSTREAM ##Creates 'error' event handler OPTS.errorHandler(ERROR) (def: prints log)
##Otherwise Gulp process might stop on error, even if in watch mode
##Also prints prettier error logs
##Version 1.2.0
GULP-PLUMBER.stop() ##
/=+===============================+=\
/ : : \
)==: LOGGING :==(
\ :_______________________________: /
\=+===============================+=/
ALTERNATIVES ==> ## - fancy-log: general logging
## - gulp-debug: better for debugging individual files
## - gulp-count: better for printing total number of files
FANCY-LOG[.info|warn|error|dir]##Same as console.*(...) but prefixed with colored timestamp
(...) ##Should be used for plugins
##Version 2.0.0
GULP-DEBUG([OPTS])->IOSTREAM ##For each VINYL (unless OPTS.showFiles false):
## - prints cwd, base, path and (if OPTS.verbose true) stat
## - path is absolute path if OPTS.minimal false
## - prepends each with OPTS.title (def: 'gulp-debug:')
##At the end (if OPTS.showCount true (def)):
## - prints total number of files
##OPTS:
## - logger (def: FANCY-LOG)
##Version 4.0.0
GULP-COUNT(['MESSAGE', ][OPTS])##For each VINYL (if OPTS.logFiles true|'TEMPLATE'):
->IOSTREAM ## - prints VINYL.path
## - 'TEMPLATE' with OBJ: path (relative), file (absolute)
## - can use OPTS.cwd 'DIR'
##At the end:
## - prints OPTS.message 'TEMPLATE' (def: '<%= files %>')
## - replaces '##' with total number of files
## - template OBJ: files ('NUM files')
## - if no files, prints according to OPTS.logEmpty BOOL|'TEMPLATE':
## - false (def): nothing
## - true (def): '0 files'
## - 'TEMPLATE' (def): '0 files'
##TEMPLATEs are Lodash templates.
##OPTS:
## - title STR (def: null): prepended
## - logger FUNC(STR) (def: console.log)
##Version 1.0.0
/=+===============================+=\
/ : : \
)==: SHELL :==(
\ :_______________________________: /
\=+===============================+=/
GENERAL ==> ##Just use Node.js CHILD_PROCESS.*() if the shell command does not need to be fired for each file.
ALTERNATIVES ==> ## - gulp-execa: always prefered
## - gulp-exec: prefered when need command return value
## - gulp-spawn: prefered when does not need command return value
GULP-EXEC ##For each VINYL:
('SHELL'[('PATH')][, OPTS]) ## - fires SHELL command with CHILD_PROCESS.exec('SHELL', OPTS)
->IOSTREAM ## - stores result in VINYL.exec.err ERROR and VINYL.exec.stdout|stderr STR (trimmed)
##./node_modules/.bin is added to PATH during execution
##OPTS:
## - pipeStdout BOOL (def: false):
## - replaces VINYL.contents by command's stdout
## - VINYL.exec.contents will contain previous contents
## - continueOnError BOOL: if false (def), throw error on command error
##Version 5.0.0
GULP-EXEC.reporter([OPTS])
->IOSTREAM ##Prints VINYL.exec.err|stdout|stderr on console
GULP-SHELL ##For each VINYL:
('SHELL'[_ARR][, OPTS]) ## - fires SHELL commands with CHILD_PROCESS.spawn()
->IOSTREAM ## - does not store result anywhere
##OPTS:
## - env|shell|cwd (def: process.env|true|process.cwd()): passed to CHILD_PROCESS.spawn()
## - quiet BOOL (def: false): passed to CHILD_PROCESS.spawn() stdio 'ignore|inherit'
## - verbose BOOL (def: false): prints command before executing it
## - ignoreErrors BOOL:
## - if false (def), throw error on command error
## - can use OPTS.errorMessage 'ERROR' (def: 'Command `<%= command %>` failed with exit code <%= error.code %>')
##Templates:
## - can be used by 'SHELL' and OPTS.cwd|errorMessage
## - are Lodash templates
## - with data: OPTS.templateData and file 'PATH'
##./node_modules/.bin is added to PATH during execution
##Version 0.8.0
GULP-SHELL.task
('SHELL'[_ARR][, OPTS])
->FUNC()->PROMISE[_ERROR] ##Same but only once (as opposed to as an IOSTREAM for each VINYL)
/=+===============================+=\
/ : : \
)==: SOURCE MAPS :==(
\ :_______________________________: /
\=+===============================+=/
VINYL.sourceMap ##Convention to where SOURCE_MAP_OBJ should be.
VINYL-SOURCEMAP ==> ##2.0.0
##Uses convert-source-map (see its doc)
VINYL-SOURCEMAP.add ##Adds VINYL.sourceMap SOURCE_MAP
(VINYL, FUNC(ERROR, VINYL)) ##Find source map from file using:
## - inline base64 sourceMappingURL comment
## - comment is stripped
## - external sourceMappingURL comment
## - sibling '.map' file
## - otherwise empty one
##SOURCE_MAP:
## - file 'COMPILED_FILENAME': VINYL.relative
## - sources 'SOURCE_PATH': fixed according to VINYL.base and SOURCE_MAP.sourceRoot
## - sourceContent: automatically added
VINYL-SOURCEMAP.write(VINYL, ##Persists VINYL.sourceMap SOURCE_MAP to:
['DIR', ]FUNC(ERROR, VINYL)) ## - if 'DIR': 'DIR/FILE.map'
## - otherwise: inline base64 sourceMappingURL comment
##Adds sourceMappingURL comment:
## - works for JavaScript comments or CSS comments (according to VINYL.extname)
ORDER ==> ## - VINYL-SOURCEMAP.add()
## - noop if VINYL.sourceMap already exists
## - plugins adding source map using VINYL-SOURCEMAPS-APPLY()
## - 'file' and 'sources' should be relative paths to VINYL.base (e.g. using VINYL.relative)
## - VINYL-SOURCEMAP.write()
## - noop if VINYL.sourceMap does not exist
VINYL-FS.src() OPTS.sourcemaps ##BOOL (def: false)
##Calls VINYL-SOURCEMAP.add()
VINYL-FS.dest() OPTS.sourcemaps##BOOL|'DIR' (def: false)
##Calls VINYL-SOURCEMAP.write()
GULP-SOURCEMAPS ==> ##3.0.0
##Like VINYL-SOURCEMAP.add|write() (re-use same code) but:
## - extra OPTS
## - not part of Gulp official
## - not integrated with VINYL-FS
##Should only use when need those extra OPTS.
GULP-SOURCEMAPS.init([OPTS]) ##OPTS:
->IOSTREAM ## - loadMaps BOOL (def: false): only tries to find source map from file if true
## - largeFile BOOL (def: false): do not remove sourceMappingURL comment
GULP-SOURCEMAPS.write ##OPTS:
(['DIR'][, 'OPTS'])->IOSTREAM ## - mapFile('PATH')->'PATH': maps source map file output path
## - mapSourcesAbsolute BOOL (def: false): make SOURCE_MAP.sources absolute
## - sourceRoot[(VINYL)] 'DIR': change SOURCE_MAP.sourceRoot
## - includeContent BOOL (def: true): automatically adds SOURCE_MAP.sourceContent if missing
## - destPath 'DIR': directory used for SOURCE_MAP.file|sourceRoot
## - addComment BOOL (def: true): if false, do add sourceMappingURL comment
## - sourceMappingURLPrefix STR[(VINYL)]: prefixed to sourceMappingURL comment
## - sourceMappingURL('URL')->'URL': maps sourceMappingURL comment
## - clone OBJ: options to VINYL.clone() when creating the SOURCE_MAP file
VINYL-SOURCEMAPS-APPLY ##Adds VINYL.sourceMap
(VINYL, SOURCE_MAP_STR|OBJ) ##If VINYL.sourceMap already exists, apply it with mozilla source-map GENERATOR.applySourceMap()
##0.2.1
##Not maintained
IDENTITY-MAP()->IOSTREAM ##Adds VINYL.sourceMap SOURCE_MAP:
## - file 'COMPILED_FILENAME': VINYL.relative
## - MAPPINGS, names, sourceContent:
## - created by tokenizing VINYL.contents and iterating over it
## - i.e. compiled file === source file (map to itself)
## - only supports JavaScript (using ACORN) and CSS (using rework css)
## - guessed from VINYL.extname
##Uses mozilla source-map GENERATOR.toJSON()
##2.0.1
GULP-SOURCEMAPS.identityMap() ##Reference to MAP-IDENTITY()
MAP-FILE
(FUNC('COMPILED_FILENAME', ##Apply mapping function to SOURCE_MAP.file
VINYL)->'COMPILED_FILENAME') ##1.0.0
->IOSTREAM ##Not maintained
MAP-SOURCES ##Apply mapping function to each SOURCE_MAP.sources
(FUNC('SOURCE_PATH', VINYL) ##1.0.0
->'SOURCE_PATH')->IOSTREAM ##Not maintained
GULP-SOURCEMAPS.mapSources(...)##Reference to MAP-SOURCES
/=+===============================+=\
/ : : \
)==: OTHERS :==(
\ :_______________________________: /
\=+===============================+=/
GULP-DATA ##Sets VINYL.data = VAL.
(FUNC(VINYL[,FUNC2(ERR, VAL)])##Is a convention for passing information between plugins
->[PROMISE_]VAL)->IOSTREAM ##Version 1.3.1