www.aleph1.co.uk Git - yaffs-website/blob - node_modules/grunt-contrib-watch/node_modules/globule/README.md

   1 # globule [![Build Status: Linux](https://travis-ci.org/cowboy/node-globule.svg?branch=master)](https://travis-ci.org/cowboy/node-globule) [![Build Status: Windows](https://ci.appveyor.com/api/projects/status/i9fnc38q952r9nc0/branch/master?svg=true)](https://ci.appveyor.com/project/gruntjs/node-globule/branch/master)
   2
   3 An easy-to-use wildcard globbing library.
   4
   5 ## Getting Started
   6 Install the module with: `npm install globule`
   7
   8 ```javascript
   9 var globule = require('globule');
  10 var filepaths = globule.find('**/*.js');
  11 ```
  12
  13 ## Documentation
  14
  15 ### globule.find
  16 Returns a unique array of all file or directory paths that match the given globbing pattern(s). This method accepts either comma separated globbing patterns or an array of globbing patterns. Paths matching patterns that begin with `!` will be excluded from the returned array. Patterns are processed in order, so inclusion and exclusion order is significant. Patterns may be specified as function arguments or as a `src` property of the options object.
  17
  18 ```js
  19 globule.find(patterns [, patterns [, ...]] [, options])
  20 globule.find({src: patterns, /* other options */})
  21 ```
  22
  23 The `options` object supports all [glob][] library options, along with a few extras. These are the most commonly used:
  24
  25 * `src` This property may be used instead of specifying patterns as function arguments.
  26 * `filter` Either a valid [fs.Stats method name](http://nodejs.org/docs/latest/api/fs.html#fs_class_fs_stats) or a function that will be passed the matched `src` filepath and `options` object as arguments. This function should return a `Boolean` value.
  27 * `nonull` Retain globbing patterns in result set even if they fail to match files.
  28 * `matchBase` Patterns without slashes will match just the basename part. Eg. this makes `*.js` work like `**/*.js`.
  29 * `srcBase` Patterns will be matched relative to the specified path instead of the current working directory. This is a synonym for `cwd`.
  30 * `prefixBase` Any specified `srcBase` will be prefixed to all returned filepaths.
  31
  32 [glob]: https://github.com/isaacs/node-glob
  33
  34 ### globule.match
  35 Match one or more globbing patterns against one or more file paths. Returns a uniqued array of all file paths that match any of the specified globbing patterns. Both the `patterns` and `filepaths` arguments can be a single string or array of strings. Paths matching patterns that begin with `!` will be excluded from the returned array. Patterns are processed in order, so inclusion and exclusion order is significant.
  36
  37 ```js
  38 globule.match(patterns, filepaths [, options])
  39 ```
  40
  41 ### globule.isMatch
  42 This method contains the same signature and logic as the `globule.match` method, but returns `true` if any files were matched, otherwise `false`.
  43
  44 ```js
  45 globule.isMatch(patterns, filepaths [, options])
  46 ```
  47
  48 ### globule.mapping
  49 Given a set of source file paths, returns an array of src-dest file mapping objects. Both src and dest paths may be renamed, depending on the options specified. Patterns may be specified as function arguments or as a `src` property of the options object.
  50
  51 ```js
  52 globule.mapping(filepaths [, filepaths [, ...]]  [, options])
  53 globule.mapping({src: filepaths, /* other options */})
  54 ```
  55
  56 In addition to the options the `globule.find` method supports, the options object also supports these properties:
  57
  58 * `srcBase` The directory from which patterns are matched. Any string specified as `srcBase` is effectively stripped from the beginning of all matched paths.
  59 * `destBase` The specified path is prefixed to all `dest` filepaths.
  60 * `ext` Remove anything after (and including) the first `.` in the destination path, then append this value.
  61 * `extDot` Change the behavior of `ext`, `"first"` and `"last"` will remove anything after the first or last `.` in the destination filename, respectively. Defaults to `"first"`.
  62 * `flatten` Remove the path component from all matched src files. The src file path is still joined to the specified destBase.
  63 * `rename` If specified, this function will be responsible for returning the final `dest` filepath. By default, it flattens paths (if specified), changes extensions (if specified) and joins the matched path to the `destBase`.
  64
  65 ### globule.findMapping
  66 This method is a convenience wrapper around the `globule.find` and `globule.mapping` methods.
  67
  68 ```js
  69 globule.findMapping(patterns [, options])
  70 ```
  71
  72
  73 ## Examples
  74
  75 Given the files `foo/a.js` and `foo/b.js`:
  76
  77 ### srcBase and destBase
  78
  79 ```js
  80 globule.find("foo/*.js")
  81 // ["foo/a.js", "foo/b.js"]
  82
  83 globule.find("*.js", {srcBase: "foo"})
  84 // ["a.js", "b.js"]
  85
  86 globule.find({src: "*.js", srcBase: "foo", prefixBase: true})
  87 // ["foo/a.js", "foo/b.js"]
  88 ```
  89
  90 ```js
  91 globule.findMapping("foo/*.js")
  92 // [{src: ["foo/a.js"], dest: "foo/a.js"}, {src: ["foo/b.js"], dest: "foo/b.js"}]
  93
  94 globule.findMapping("foo/*.js", {destBase: "bar"})
  95 // [{src: ["foo/a.js"], dest: "bar/foo/a.js"}, {src: ["foo/b.js"], dest: "bar/foo/b.js"}]
  96
  97 globule.findMapping({src: "*.js", srcBase: "foo", destBase: "bar"})
  98 // [{src: ["foo/a.js"], dest: "bar/a.js"}, {src: ["foo/b.js"], dest: "bar/b.js"}]
  99 ```
 100
 101 ```js
 102 globule.mapping(["foo/a.js", "foo/b.js"])
 103 // [{src: ["foo/a.js"], dest: "foo/a.js"}, {src: ["foo/b.js"], dest: "foo/b.js"}]
 104
 105 globule.mapping(["foo/a.js", "foo/b.js"], {destBase: "bar"})
 106 // [{src: ["foo/a.js"], dest: "bar/foo/a.js"}, {src: ["foo/b.js"], dest: "bar/foo/b.js"}]
 107
 108 globule.mapping("foo/a.js", "foo/b.js", {destBase: "bar"})
 109 // [{src: ["foo/a.js"], dest: "bar/foo/a.js"}, {src: ["foo/b.js"], dest: "bar/foo/b.js"}]
 110
 111 globule.mapping(["a.js", "b.js"], {srcBase: "foo", destBase: "bar"})
 112 // [{src: ["foo/a.js"], dest: "bar/a.js"}, {src: ["foo/b.js"], dest: "bar/b.js"}]
 113
 114 globule.mapping({src: ["a.js", "b.js"], srcBase: "foo", destBase: "bar"})
 115 // [{src: ["foo/a.js"], dest: "bar/a.js"}, {src: ["foo/b.js"], dest: "bar/b.js"}]
 116 ```
 117
 118 ## Contributing
 119 In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using [Grunt](http://gruntjs.com/).
 120
 121 ## Release History
 122 2016-10-23 - v1.1.0 - Update dependencies, lodash@4.16, glob@7.1.
 123 2016-04-14 - v1.0.0 - Update dependencies, lodash@4.9, glob@7.0, minimatch@3.0. Paths are unix-style with prefixBase enabled.
 124 2014-01-07 - v0.2.0 - Updated dependencies. Added `src` option. Improved exclusion speed significantly.
 125 2013-04-11 - v0.1.0 - Initial release.
 126
 127 ## License
 128 Copyright (c) 2016 "Cowboy" Ben Alman
 129 Licensed under the MIT license.