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

   1 # vinyl [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Dependency Status](https://david-dm.org/wearefractal/vinyl.png?theme=shields.io)](https://david-dm.org/wearefractal/vinyl)
   2 ## Information
   3 <table><br><tr><br><td>Package</td><td>vinyl</td><br></tr><br><tr><br><td>Description</td><br><td>A virtual file format</td><br></tr><br><tr><br><td>Node Version</td><br><td>>= 0.9</td><br></tr><br></table>
   4
   5 ## What is this?
   6 Read this for more info about how this plays into the grand scheme of things [https://medium.com/@eschoff/3828e8126466](https://medium.com/@eschoff/3828e8126466)
   7
   8 ## File
   9
  10 ```javascript
  11 var File = require('vinyl');
  12
  13 var coffeeFile = new File({
  14   cwd: "/",
  15   base: "/test/",
  16   path: "/test/file.coffee",
  17   contents: new Buffer("test = 123")
  18 });
  19 ```
  20
  21 ### isVinyl
  22 When checking if an object is a vinyl file, you should not use instanceof. Use the isVinyl function instead.
  23
  24 ```js
  25 var File = require('vinyl');
  26
  27 var dummy = new File({stuff});
  28 var notAFile = {};
  29
  30 File.isVinyl(dummy); // true
  31 File.isVinyl(notAFile); // false
  32 ```
  33
  34 ### constructor(options)
  35 #### options.cwd
  36 Type: `String`<br><br>Default: `process.cwd()`
  37
  38 #### options.base
  39 Used for relative pathing. Typically where a glob starts.
  40
  41 Type: `String`<br><br>Default: `options.cwd`
  42
  43 #### options.path
  44 Full path to the file.
  45
  46 Type: `String`<br><br>Default: `undefined`
  47
  48 #### options.history
  49 Path history. Has no effect if `options.path` is passed.
  50
  51 Type: `Array`<br><br>Default: `options.path ? [options.path] : []`
  52
  53 #### options.stat
  54 The result of an fs.stat call. See [fs.Stats](http://nodejs.org/api/fs.html#fs_class_fs_stats) for more information.
  55
  56 Type: `fs.Stats`<br><br>Default: `null`
  57
  58 #### options.contents
  59 File contents.
  60
  61 Type: `Buffer, Stream, or null`<br><br>Default: `null`
  62
  63 ### isBuffer()
  64 Returns true if file.contents is a Buffer.
  65
  66 ### isStream()
  67 Returns true if file.contents is a Stream.
  68
  69 ### isNull()
  70 Returns true if file.contents is null.
  71
  72 ### clone([opt])
  73 Returns a new File object with all attributes cloned.<br>By default custom attributes are deep-cloned.
  74
  75 If opt or opt.deep is false, custom attributes will not be deep-cloned.
  76
  77 If opt.contents is false, it will copy file.contents Buffer's reference.
  78
  79 ### pipe(stream[, opt])
  80 If file.contents is a Buffer, it will write it to the stream.
  81
  82 If file.contents is a Stream, it will pipe it to the stream.
  83
  84 If file.contents is null, it will do nothing.
  85
  86 If opt.end is false, the destination stream will not be ended (same as node core).
  87
  88 Returns the stream.
  89
  90 ### inspect()
  91 Returns a pretty String interpretation of the File. Useful for console.log.
  92
  93 ### contents
  94 The [Stream](https://nodejs.org/api/stream.html#stream_stream) or [Buffer](https://nodejs.org/api/buffer.html#buffer_class_buffer) of the file as it was passed in via options, or as the result of modification.
  95
  96 For example:
  97
  98 ```js
  99 if (file.isBuffer()) {
 100     console.log(file.contents.toString()); // logs out the string of contents
 101 }
 102 ```
 103
 104 ### path
 105 Absolute pathname string or `undefined`. Setting to a different value pushes the old value to `history`.
 106
 107 ### history
 108 Array of `path` values the file object has had, from `history[0]` (original) through `history[history.length - 1]` (current). `history` and its elements should normally be treated as read-only and only altered indirectly by setting `path`.
 109
 110 ### relative
 111 Returns path.relative for the file base and file path.
 112
 113 Example:
 114
 115 ```javascript
 116 var file = new File({
 117   cwd: "/",
 118   base: "/test/",
 119   path: "/test/file.coffee"
 120 });
 121
 122 console.log(file.relative); // file.coffee
 123 ```
 124
 125 ### dirname
 126 Gets and sets path.dirname for the file path.
 127
 128 Example:
 129
 130 ```javascript
 131 var file = new File({
 132   cwd: "/",
 133   base: "/test/",
 134   path: "/test/file.coffee"
 135 });
 136
 137 console.log(file.dirname); // /test
 138
 139 file.dirname = '/specs';
 140
 141 console.log(file.dirname); // /specs
 142 console.log(file.path); // /specs/file.coffee
 143 `
 144 ```
 145
 146 ### basename
 147 Gets and sets path.basename for the file path.
 148
 149 Example:
 150
 151 ```javascript
 152 var file = new File({
 153   cwd: "/",
 154   base: "/test/",
 155   path: "/test/file.coffee"
 156 });
 157
 158 console.log(file.basename); // file.coffee
 159
 160 file.basename = 'file.js';
 161
 162 console.log(file.basename); // file.js
 163 console.log(file.path); // /test/file.js
 164 `
 165 ```
 166
 167 ### extname
 168 Gets and sets path.extname for the file path.
 169
 170 Example:
 171
 172 ```javascript
 173 var file = new File({
 174   cwd: "/",
 175   base: "/test/",
 176   path: "/test/file.coffee"
 177 });
 178
 179 console.log(file.extname); // .coffee
 180
 181 file.extname = '.js';
 182
 183 console.log(file.extname); // .js
 184 console.log(file.path); // /test/file.js
 185 `
 186 ```
 187
 188 [npm-url]: https://npmjs.org/package/vinyl
 189 [npm-image]: https://badge.fury.io/js/vinyl.png
 190 [travis-url]: https://travis-ci.org/wearefractal/vinyl
 191 [travis-image]: https://travis-ci.org/wearefractal/vinyl.png?branch=master
 192 [coveralls-url]: https://coveralls.io/r/wearefractal/vinyl
 193 [coveralls-image]: https://coveralls.io/repos/wearefractal/vinyl/badge.png
 194 [depstat-url]: https://david-dm.org/wearefractal/vinyl
 195 [depstat-image]: https://david-dm.org/wearefractal/vinyl.png