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

   1 # globule [![Build Status](https://secure.travis-ci.org/cowboy/node-globule.png?branch=master)](http://travis-ci.org/cowboy/node-globule)
   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.
  17
  18 ```js
  19 globule.find(patterns [, options])
  20 ```
  21
  22 The `options` object supports all [glob][] library options, along with a few extras. These are the most commonly used:
  23
  24 * `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.
  25 * `nonull` Retain globbing patterns in result set even if they fail to match files.
  26 * `matchBase` Patterns without slashes will match just the basename part. Eg. this makes `*.js` work like `**/*.js`.
  27 * `srcBase` Patterns will be matched relative to the specified path instead of the current working directory. This is a synonym for `cwd`.
  28 * `prefixBase` Any specified `srcBase` will be prefixed to all returned filepaths.
  29
  30 [glob]: https://github.com/isaacs/node-glob
  31
  32 ### globule.match
  33 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.
  34
  35 ```js
  36 grunt.file.match(patterns, filepaths [, options])
  37 ```
  38
  39 ### globule.isMatch
  40 This method contains the same signature and logic as the `globule.match` method, but returns `true` if any files were matched, otherwise `false`.
  41
  42 ```js
  43 grunt.file.isMatch(patterns, filepaths [, options])
  44 ```
  45
  46 ### globule.mapping
  47 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.
  48
  49 ```js
  50 globule.mapping(filepaths [, options])
  51 ```
  52
  53 In addition to the options the `globule.find` method supports, the options object also supports these properties:
  54
  55 * `srcBase` The directory from which patterns are matched. Any string specified as `srcBase` is effectively stripped from the beginning of all matched paths.
  56 * `destBase` The specified path is prefixed to all `dest` filepaths.
  57 * `ext` Remove anything after (and including) the first `.` in the destination path, then append this value.
  58 * `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"`.
  59 * `flatten` Remove the path component from all matched src files. The src file path is still joined to the specified destBase.
  60 * `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`.
  61
  62 ### globule.findMapping
  63 This method is a convenience wrapper around the `globule.find` and `globule.mapping` methods.
  64
  65 ```js
  66 globule.findMapping(patterns [, options])
  67 ```
  68
  69
  70 ## Examples
  71
  72 Given the files `foo/a.js` and `foo/b.js`:
  73
  74 ### srcBase and destBase
  75
  76 ```js
  77 globule.find("foo/*.js")
  78 // ["foo/a.js", "foo/b.js"]
  79
  80 globule.find("*.js", {srcBase: "foo"})
  81 // ["a.js", "b.js"]
  82
  83 globule.find("*.js", {srcBase: "foo", prefixBase: true})
  84 // ["foo/a.js", "foo/b.js"]
  85 ```
  86
  87 ```js
  88 globule.findMapping("foo/*.js")
  89 // [{src: "foo/a.js", dest: "foo/a.js"}, {src: "foo/b.js", dest: "foo/b.js"}]
  90
  91 globule.findMapping("foo/*.js", {destBase: "bar"})
  92 // [{src: "foo/a.js", dest: "bar/foo/a.js"}, {src: "foo/b.js", dest: "bar/foo/b.js"}]
  93
  94 globule.findMapping("*.js", {srcBase: "foo", destBase: "bar"})
  95 // [{src: "foo/a.js", dest: "bar/a.js"}, {src: "foo/b.js", dest: "bar/b.js"}]
  96 ```
  97
  98 ```js
  99 globule.mapping(["foo/a.js", "foo/b.js"])
 100 // [{src: "foo/a.js", dest: "foo/a.js"}, {src: "foo/b.js", dest: "foo/b.js"}]
 101
 102 globule.mapping(["foo/a.js", "foo/b.js"], {destBase: "bar"})
 103 // [{src: "foo/a.js", dest: "bar/foo/a.js"}, {src: "foo/b.js", dest: "bar/foo/b.js"}]
 104
 105 globule.mapping(["a.js", "b.js"], {srcBase: "foo", destBase: "bar"})
 106 // [{src: "foo/a.js", dest: "bar/a.js"}, {src: "foo/b.js", dest: "bar/b.js"}]
 107 ```
 108
 109 ## Contributing
 110 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/).
 111
 112 ## Release History
 113 _(Nothing yet)_
 114
 115 ## License
 116 Copyright (c) 2013 "Cowboy" Ben Alman
 117 Licensed under the MIT license.