libs/js/jquery-mobile-1.2.0/node_modules/grunt/docs/api_file.md

   1 [Grunt homepage](https://github.com/gruntjs/grunt) | [Documentation table of contents](toc.md)
   2
   3 # [The grunt API](api.md) / grunt.file
   4
   5 Wildcard expansion, file reading, writing, directory traversing.
   6
   7 See the [file lib source](../lib/grunt/file.js) for more information.
   8
   9 ## The file API
  10 There are many provided methods for reading and writing files, as well as traversing the filesystem and finding files by wildcard patterns. Many of these methods are wrappers around core Node.js file functionality, but with additional error handling and logging.
  11
  12 _Note: all file paths are relative to the [grunt.js gruntfile](getting_started.md) unless the current working directory is changed with `grunt.file.setBase` or the `--base` command-line option._
  13
  14 ### grunt.file.read
  15 Read and return a file's contents. The `encoding` argument defaults to `utf8` if unspecified.
  16
  17 ```javascript
  18 grunt.file.read(filepath, encoding)
  19 ```
  20
  21 ### grunt.file.readJSON
  22 Read a file's contents, parsing the data as JSON and returning the result.
  23
  24 ```javascript
  25 grunt.file.readJSON(filepath)
  26 ```
  27
  28 ### grunt.file.write
  29 Write the specified contents to a file, creating intermediate directories if necessary.
  30
  31 _If the `--no-write` command-line option is specified, the file won't actually be written._
  32
  33 ```javascript
  34 grunt.file.write(filepath, contents)
  35 ```
  36
  37 ### grunt.file.copy
  38 Copy a source file to a destination path, creating intermediate directories if necessary.
  39
  40 _If the `--no-write` command-line option is specified, the file won't actually be written._
  41
  42 ```javascript
  43 grunt.file.copy(srcpath, destpath [, options])
  44 ```
  45
  46 The `options` object has these possible properties:
  47
  48 ```javascript
  49 var options = {
  50   // If specified, the file contents will be parsed as `utf8` and passed into
  51   // the function, whose return value will be used as the destination file's
  52   // contents. If this function returns false, the file copy will be aborted.
  53   process: processFunction,
  54   // These optional wildcard patterns will be matched against the filepath using
  55   // grunt.file.isMatch. If a specified wildcard pattern matches, the file will
  56   // not be processed via `processFunction`. Note that `true` may also be
  57   // specified to prvent processing.
  58   noProcess: wildcardPatterns
  59 };
  60 ```
  61
  62 ### grunt.file.mkdir
  63 Works like `mkdir -p`. Create a directory along with any intermediate directories.
  64
  65 _If the `--no-write` command-line option is specified, directories won't actually be created._
  66
  67 ```javascript
  68 grunt.file.mkdir(dirpath)
  69 ```
  70
  71 ### grunt.file.recurse
  72 Recurse into a directory, executing `callback` for each file.
  73
  74 ```javascript
  75 grunt.file.recurse(rootdir, callback)
  76 ```
  77
  78 The callback function receives the following arguments:
  79
  80 ```javascript
  81 function callback(abspath, rootdir, subdir, filename) {
  82   // The full path to the current file, which is nothing more than
  83   // the rootdir + subdir + filename arguments, joined.
  84   abspath
  85   // The root director, as originally specified.
  86   rootdir
  87   // The current file's directory, relative to rootdir.
  88   subdir
  89   // The filename of the current file, without any directory parts.
  90   filename
  91 }
  92 ```
  93
  94 ### grunt.file.findup
  95 Search for a filename in the given directory followed by all parent directories. Returns the first matching filepath found, otherwise returns `null`.
  96
  97 ```javascript
  98 grunt.file.findup(rootdir, filename)
  99 ```
 100
 101 ### grunt.file.isPathAbsolute
 102 Is a given file path absolute? Returns a boolean.
 103
 104 Like the Node.js [path.join](http://nodejs.org/docs/latest/api/path.html#path_path_join_path1_path2) method, this method will join all arguments together and normalize the resulting path.
 105
 106 ```javascript
 107 grunt.file.isPathAbsolute(path1 [, path2 [, ...]])
 108 ```
 109
 110 ### grunt.file.userDir
 111 Return a file path relative to the user's `.grunt` directory, which is `%USERPROFILE%\.grunt\` on Windows, and `~/.grunt/` on OS X or Linux. If no file path is specified, the base user `.grunt` directory path will be returned. If the specified path is not found, `null` is returned.
 112
 113 Windows users: `%USERPROFILE%` is generally your `Documents and Settings` directory.
 114
 115 _Like the Node.js [path.join](http://nodejs.org/docs/latest/api/path.html#path_path_join_path1_path2) method, this method will join all arguments together and normalize the resulting path._
 116
 117 ```javascript
 118 grunt.file.userDir([path1, [, path2 [, ...]]])
 119 ```
 120
 121 ### grunt.file.setBase
 122 Change grunt's current working directory. By default, all file paths are relative to the [grunt.js gruntfile](getting_started.md). This works just like the `--base` command-line option.
 123
 124 ```javascript
 125 grunt.file.setBase(path1 [, path2 [, ...]])
 126 ```
 127
 128 Like the Node.js [path.join](http://nodejs.org/docs/latest/api/path.html#path_path_join_path1_path2) method, this method will join all arguments together and normalize the resulting path.
 129
 130
 131 ## File Lists and Wildcards
 132 Wildcard patterns are resolved using the [glob-whatev library](https://github.com/cowboy/node-glob-whatev). See the [minimatch](https://github.com/isaacs/minimatch) module documentation for more details on supported wildcard patterns.
 133
 134 There are also a number of [task-specific file listing methods](api_task.md) that find files inside grunt plugins and task directories.
 135
 136 _Note: all file paths are relative to the [grunt.js gruntfile](getting_started.md) unless the current working directory is changed with `grunt.file.setBase` or the `--base` command-line option._
 137
 138 ### grunt.file.expand
 139 Return a unique array of all file or directory paths that match the given wildcard pattern(s). This method accepts one or more comma separated wildcard patterns as well as an array of wildcard patterns.
 140
 141 The `options` object supports all [minimatch](https://github.com/isaacs/minimatch) options.
 142
 143 ```javascript
 144 grunt.file.expand([options, ] patterns)
 145 ```
 146
 147 ### grunt.file.expandDirs
 148 This method behaves the same as `grunt.file.expand` except it only returns directory paths.
 149
 150 ```javascript
 151 grunt.file.expandDirs([options, ] patterns)
 152 ```
 153
 154 ### grunt.file.expandFiles
 155 This method behaves the same as `grunt.file.expand` except it only returns file paths.
 156
 157 ```javascript
 158 grunt.file.expandFiles([options, ] patterns)
 159 ```
 160
 161 This method is used by many built-in tasks to handle wildcard expansion of the specified source files. See the [concat task source](../tasks/concat.js) for an example.
 162
 163 ### grunt.file.expandFileURLs
 164 Return a unique array of all `file://` URLs for files that match the given wildcard pattern(s). Any absolute `file://`, `http://` or `https://` URLs specified will be passed through. This method accepts one or more comma separated wildcard patterns (or URLs), as well as an array of wildcard patterns (or URLs).
 165
 166 ```javascript
 167 grunt.file.expandFileURLs(patternsOrURLs)
 168 ```
 169
 170 See the [qunit task source](../tasks/qunit.js) for an example.
 171
 172 ### grunt.file.isMatch
 173 Match one or more wildcard patterns against a file path. If any of the specified matches, return `true` otherwise return `false`. This method accepts a single string wildcard pattern as well as an array of wildcard patterns. Note that `true` may also be specified to prvent processing.
 174
 175 ```javascript
 176 grunt.file.isMatch(patterns, filepath)
 177 ```
 178
 179 Patterns without slashes will be matched against the basename of the path if it contains slashes, eg. pattern `*.js` will match filepath `path/to/file.js`.
 180
 181 ## External libraries
 182
 183 ### grunt.file.glob
 184 [glob-whatev](https://github.com/cowboy/node-glob-whatev) - Synchronous file globbing utility.