3 var grunt = require('../grunt');
6 var fs = require('fs');
7 var path = require('path');
9 // The module to be exported.
10 var file = module.exports = {};
13 file.glob = require('glob');
14 file.minimatch = require('minimatch');
15 file.findup = require('findup-sync');
16 var YAML = require('js-yaml');
17 var rimraf = require('rimraf');
18 var iconv = require('iconv-lite');
19 var pathIsAbsolute = require('path-is-absolute');
22 var win32 = process.platform === 'win32';
24 // Normalize \\ paths to / paths.
25 var unixifyPath = function(filepath) {
27 return filepath.replace(/\\/g, '/');
33 // Change the current base path (ie, CWD) to the specified path.
34 file.setBase = function() {
35 var dirpath = path.join.apply(path, arguments);
36 process.chdir(dirpath);
39 // Process specified wildcard glob patterns or filenames against a
40 // callback, excluding and uniquing files in the result set.
41 var processPatterns = function(patterns, fn) {
42 // Filepaths to return.
44 // Iterate over flattened patterns array.
45 grunt.util._.flattenDeep(patterns).forEach(function(pattern) {
46 // If the first character is ! it should be omitted
47 var exclusion = pattern.indexOf('!') === 0;
48 // If the pattern is an exclusion, remove the !
49 if (exclusion) { pattern = pattern.slice(1); }
50 // Find all matching files for this pattern.
51 var matches = fn(pattern);
53 // If an exclusion, remove matching files.
54 result = grunt.util._.difference(result, matches);
56 // Otherwise add matching files.
57 result = grunt.util._.union(result, matches);
63 // Match a filepath or filepaths against one or more wildcard patterns. Returns
64 // all matching filepaths.
65 file.match = function(options, patterns, filepaths) {
66 if (grunt.util.kindOf(options) !== 'object') {
71 // Return empty set if either patterns or filepaths was omitted.
72 if (patterns == null || filepaths == null) { return []; }
73 // Normalize patterns and filepaths to arrays.
74 if (!Array.isArray(patterns)) { patterns = [patterns]; }
75 if (!Array.isArray(filepaths)) { filepaths = [filepaths]; }
76 // Return empty set if there are no patterns or filepaths.
77 if (patterns.length === 0 || filepaths.length === 0) { return []; }
78 // Return all matching filepaths.
79 return processPatterns(patterns, function(pattern) {
80 return file.minimatch.match(filepaths, pattern, options);
84 // Match a filepath or filepaths against one or more wildcard patterns. Returns
85 // true if any of the patterns match.
86 file.isMatch = function() {
87 return file.match.apply(file, arguments).length > 0;
90 // Return an array of all file paths that match the given wildcard patterns.
91 file.expand = function() {
92 var args = grunt.util.toArray(arguments);
93 // If the first argument is an options object, save those options to pass
94 // into the file.glob.sync method.
95 var options = grunt.util.kindOf(args[0]) === 'object' ? args.shift() : {};
96 // Use the first argument if it's an Array, otherwise convert the arguments
97 // object to an array and use that.
98 var patterns = Array.isArray(args[0]) ? args[0] : args;
99 // Return empty set if there are no patterns or filepaths.
100 if (patterns.length === 0) { return []; }
101 // Return all matching filepaths.
102 var matches = processPatterns(patterns, function(pattern) {
103 // Find all matching files for this pattern.
104 return file.glob.sync(pattern, options);
106 // Filter result set?
107 if (options.filter) {
108 matches = matches.filter(function(filepath) {
109 filepath = path.join(options.cwd || '', filepath);
111 if (typeof options.filter === 'function') {
112 return options.filter(filepath);
114 // If the file is of the right type and exists, this should work.
115 return fs.statSync(filepath)[options.filter]();
118 // Otherwise, it's probably not the right type.
126 var pathSeparatorRe = /[\/\\]/g;
128 // The "ext" option refers to either everything after the first dot (default)
129 // or everything after the last dot.
131 first: /(\.[^\/]*)?$/,
132 last: /(\.[^\/\.]*)?$/,
135 // Build a multi task "files" object dynamically.
136 file.expandMapping = function(patterns, destBase, options) {
137 options = grunt.util._.defaults({}, options, {
139 rename: function(destBase, destPath) {
140 return path.join(destBase || '', destPath);
145 // Find all files matching pattern, using passed-in options.
146 file.expand(options, patterns).forEach(function(src) {
149 if (options.flatten) {
150 destPath = path.basename(destPath);
152 // Change the extension?
153 if ('ext' in options) {
154 destPath = destPath.replace(extDotRe[options.extDot], options.ext);
156 // Generate destination filename.
157 var dest = options.rename(destBase, destPath, options);
158 // Prepend cwd to src path if necessary.
159 if (options.cwd) { src = path.join(options.cwd, src); }
160 // Normalize filepaths to be unix-style.
161 dest = dest.replace(pathSeparatorRe, '/');
162 src = src.replace(pathSeparatorRe, '/');
163 // Map correct src path to dest path.
164 if (fileByDest[dest]) {
165 // If dest already exists, push this src onto that dest's src array.
166 fileByDest[dest].src.push(src);
168 // Otherwise create a new src-dest file mapping object.
173 // And store a reference for later use.
174 fileByDest[dest] = files[files.length - 1];
180 // Like mkdir -p. Create a directory and any intermediary directories.
181 file.mkdir = function(dirpath, mode) {
182 if (grunt.option('no-write')) { return; }
183 // Set directory mode in a strict-mode-friendly way.
185 mode = parseInt('0777', 8) & (~process.umask());
187 dirpath.split(pathSeparatorRe).reduce(function(parts, part) {
189 var subpath = path.resolve(parts);
190 if (!file.exists(subpath)) {
192 fs.mkdirSync(subpath, mode);
194 throw grunt.util.error('Unable to create directory "' + subpath + '" (Error code: ' + e.code + ').', e);
201 // Recurse into a directory, executing callback for each file.
202 file.recurse = function recurse(rootdir, callback, subdir) {
203 var abspath = subdir ? path.join(rootdir, subdir) : rootdir;
204 fs.readdirSync(abspath).forEach(function(filename) {
205 var filepath = path.join(abspath, filename);
206 if (fs.statSync(filepath).isDirectory()) {
207 recurse(rootdir, callback, unixifyPath(path.join(subdir || '', filename || '')));
209 callback(unixifyPath(filepath), rootdir, subdir, filename);
214 // The default file encoding to use.
215 file.defaultEncoding = 'utf8';
216 // Whether to preserve the BOM on file.read rather than strip it.
217 file.preserveBOM = false;
219 // Read a file, return its contents.
220 file.read = function(filepath, options) {
221 if (!options) { options = {}; }
223 grunt.verbose.write('Reading ' + filepath + '...');
225 contents = fs.readFileSync(String(filepath));
226 // If encoding is not explicitly null, convert from encoded buffer to a
227 // string. If no encoding was specified, use the default.
228 if (options.encoding !== null) {
229 contents = iconv.decode(contents, options.encoding || file.defaultEncoding, {stripBOM: !file.preserveBOM});
234 grunt.verbose.error();
235 throw grunt.util.error('Unable to read "' + filepath + '" file (Error code: ' + e.code + ').', e);
239 // Read a file, parse its contents, return an object.
240 file.readJSON = function(filepath, options) {
241 var src = file.read(filepath, options);
243 grunt.verbose.write('Parsing ' + filepath + '...');
245 result = JSON.parse(src);
249 grunt.verbose.error();
250 throw grunt.util.error('Unable to parse "' + filepath + '" file (' + e.message + ').', e);
254 // Read a YAML file, parse its contents, return an object.
255 file.readYAML = function(filepath, options) {
256 var src = file.read(filepath, options);
258 grunt.verbose.write('Parsing ' + filepath + '...');
260 result = YAML.load(src);
264 grunt.verbose.error();
265 throw grunt.util.error('Unable to parse "' + filepath + '" file (' + e.problem + ').', e);
270 file.write = function(filepath, contents, options) {
271 if (!options) { options = {}; }
272 var nowrite = grunt.option('no-write');
273 grunt.verbose.write((nowrite ? 'Not actually writing ' : 'Writing ') + filepath + '...');
274 // Create path, if necessary.
275 file.mkdir(path.dirname(filepath));
277 // If contents is already a Buffer, don't try to encode it. If no encoding
278 // was specified, use the default.
279 if (!Buffer.isBuffer(contents)) {
280 contents = iconv.encode(contents, options.encoding || file.defaultEncoding);
282 // Actually write file.
284 fs.writeFileSync(filepath, contents, 'mode' in options ? {mode: options.mode} : {});
289 grunt.verbose.error();
290 throw grunt.util.error('Unable to write "' + filepath + '" file (Error code: ' + e.code + ').', e);
294 // Read a file, optionally processing its content, then write the output.
295 // Or read a directory, recursively creating directories, reading files,
296 // processing content, writing output.
297 file.copy = function copy(srcpath, destpath, options) {
298 if (file.isDir(srcpath)) {
299 // Copy a directory, recursively.
300 // Explicitly create new dest directory.
301 file.mkdir(destpath);
302 // Iterate over all sub-files/dirs, recursing.
303 fs.readdirSync(srcpath).forEach(function(filepath) {
304 copy(path.join(srcpath, filepath), path.join(destpath, filepath), options);
307 // Copy a single file.
308 file._copy(srcpath, destpath, options);
312 // Read a file, optionally processing its content, then write the output.
313 file._copy = function(srcpath, destpath, options) {
314 if (!options) { options = {}; }
315 // If a process function was specified, and noProcess isn't true or doesn't
316 // match the srcpath, process the file's source.
317 var process = options.process && options.noProcess !== true &&
318 !(options.noProcess && file.isMatch(options.noProcess, srcpath));
319 // If the file will be processed, use the encoding as-specified. Otherwise,
320 // use an encoding of null to force the file to be read/written as a Buffer.
321 var readWriteOptions = process ? options : {encoding: null};
322 // Actually read the file.
323 var contents = file.read(srcpath, readWriteOptions);
325 grunt.verbose.write('Processing source...');
327 contents = options.process(contents, srcpath, destpath);
330 grunt.verbose.error();
331 throw grunt.util.error('Error while processing "' + srcpath + '" file.', e);
334 // Abort copy if the process function returns false.
335 if (contents === false) {
336 grunt.verbose.writeln('Write aborted.');
338 file.write(destpath, contents, readWriteOptions);
342 // Delete folders and files recursively
343 file.delete = function(filepath, options) {
344 filepath = String(filepath);
346 var nowrite = grunt.option('no-write');
348 options = {force: grunt.option('force') || false};
351 grunt.verbose.write((nowrite ? 'Not actually deleting ' : 'Deleting ') + filepath + '...');
353 if (!file.exists(filepath)) {
354 grunt.verbose.error();
355 grunt.log.warn('Cannot delete nonexistent file.');
359 // Only delete cwd or outside cwd if --force enabled. Be careful, people!
360 if (!options.force) {
361 if (file.isPathCwd(filepath)) {
362 grunt.verbose.error();
363 grunt.fail.warn('Cannot delete the current working directory.');
365 } else if (!file.isPathInCwd(filepath)) {
366 grunt.verbose.error();
367 grunt.fail.warn('Cannot delete files outside the current working directory.');
373 // Actually delete. Or not.
375 rimraf.sync(filepath);
380 grunt.verbose.error();
381 throw grunt.util.error('Unable to delete "' + filepath + '" file (' + e.message + ').', e);
385 // True if the file path exists.
386 file.exists = function() {
387 var filepath = path.join.apply(path, arguments);
388 return fs.existsSync(filepath);
391 // True if the file is a symbolic link.
392 file.isLink = function() {
393 var filepath = path.join.apply(path, arguments);
394 return file.exists(filepath) && fs.lstatSync(filepath).isSymbolicLink();
397 // True if the path is a directory.
398 file.isDir = function() {
399 var filepath = path.join.apply(path, arguments);
400 return file.exists(filepath) && fs.statSync(filepath).isDirectory();
403 // True if the path is a file.
404 file.isFile = function() {
405 var filepath = path.join.apply(path, arguments);
406 return file.exists(filepath) && fs.statSync(filepath).isFile();
409 // Is a given file path absolute?
410 file.isPathAbsolute = function() {
411 var filepath = path.join.apply(path, arguments);
412 return pathIsAbsolute(filepath);
415 // Do all the specified paths refer to the same path?
416 file.arePathsEquivalent = function(first) {
417 first = path.resolve(first);
418 for (var i = 1; i < arguments.length; i++) {
419 if (first !== path.resolve(arguments[i])) { return false; }
424 // Are descendant path(s) contained within ancestor path? Note: does not test
425 // if paths actually exist.
426 file.doesPathContain = function(ancestor) {
427 ancestor = path.resolve(ancestor);
429 for (var i = 1; i < arguments.length; i++) {
430 relative = path.relative(path.resolve(arguments[i]), ancestor);
431 if (relative === '' || /\w+/.test(relative)) { return false; }
436 // Test to see if a filepath is the CWD.
437 file.isPathCwd = function() {
438 var filepath = path.join.apply(path, arguments);
440 return file.arePathsEquivalent(fs.realpathSync(process.cwd()), fs.realpathSync(filepath));
446 // Test to see if a filepath is contained within the CWD.
447 file.isPathInCwd = function() {
448 var filepath = path.join.apply(path, arguments);
450 return file.doesPathContain(fs.realpathSync(process.cwd()), fs.realpathSync(filepath));