vinyl
Advanced tools
Comparing version 1.2.0 to 2.0.0
168
index.js
@@ -0,14 +1,20 @@ | ||
'use strict'; | ||
var path = require('path'); | ||
var isBuffer = require('buffer').Buffer.isBuffer; | ||
var clone = require('clone'); | ||
var isStream = require('is-stream'); | ||
var cloneable = require('cloneable-readable'); | ||
var replaceExt = require('replace-ext'); | ||
var cloneStats = require('clone-stats'); | ||
var cloneBuffer = require('./lib/cloneBuffer'); | ||
var isBuffer = require('./lib/isBuffer'); | ||
var isStream = require('./lib/isStream'); | ||
var isNull = require('./lib/isNull'); | ||
var inspectStream = require('./lib/inspectStream'); | ||
var Stream = require('stream'); | ||
var replaceExt = require('replace-ext'); | ||
var cloneBuffer = require('clone-buffer'); | ||
var removeTrailingSep = require('remove-trailing-separator'); | ||
var normalize = require('./lib/normalize'); | ||
var inspectStream = require('./lib/inspect-stream'); | ||
var builtInFields = [ | ||
'_contents', 'contents', 'stat', 'history', 'path', 'base', 'cwd', | ||
'_contents', '_symlink', 'contents', 'stat', 'history', 'path', | ||
'_base', 'base', '_cwd', 'cwd', | ||
]; | ||
@@ -23,9 +29,2 @@ | ||
// Record path change | ||
var history = file.path ? [file.path] : file.history; | ||
this.history = history || []; | ||
this.cwd = file.cwd || process.cwd(); | ||
this.base = file.base || this.cwd; | ||
// Stat = files stats object | ||
@@ -37,4 +36,19 @@ this.stat = file.stat || null; | ||
// Replay path history to ensure proper normalization and trailing sep | ||
var history = Array.prototype.slice.call(file.history || []); | ||
if (file.path) { | ||
history.push(file.path); | ||
} | ||
this.history = []; | ||
history.forEach(function(path) { | ||
self.path = path; | ||
}); | ||
this.cwd = file.cwd || process.cwd(); | ||
this.base = file.base; | ||
this._isVinyl = true; | ||
this._symlink = null; | ||
// Set custom properties | ||
@@ -57,10 +71,29 @@ Object.keys(file).forEach(function(key) { | ||
File.prototype.isNull = function() { | ||
return isNull(this.contents); | ||
return (this.contents === null); | ||
}; | ||
// TODO: Should this be moved to vinyl-fs? | ||
File.prototype.isDirectory = function() { | ||
return this.isNull() && this.stat && this.stat.isDirectory(); | ||
if (!this.isNull()) { | ||
return false; | ||
} | ||
if (this.stat && typeof this.stat.isDirectory === 'function') { | ||
return this.stat.isDirectory(); | ||
} | ||
return false; | ||
}; | ||
File.prototype.isSymbolic = function() { | ||
if (!this.isNull()) { | ||
return false; | ||
} | ||
if (this.stat && typeof this.stat.isSymbolicLink === 'function') { | ||
return this.stat.isSymbolicLink(); | ||
} | ||
return false; | ||
}; | ||
File.prototype.clone = function(opt) { | ||
@@ -87,4 +120,3 @@ var self = this; | ||
if (this.isStream()) { | ||
contents = this.contents.pipe(new Stream.PassThrough()); | ||
this.contents = this.contents.pipe(new Stream.PassThrough()); | ||
contents = this.contents.clone(); | ||
} else if (this.isBuffer()) { | ||
@@ -111,29 +143,2 @@ contents = opt.contents ? cloneBuffer(this.contents) : this.contents; | ||
File.prototype.pipe = function(stream, opt) { | ||
if (!opt) { | ||
opt = {}; | ||
} | ||
if (typeof opt.end === 'undefined') { | ||
opt.end = true; | ||
} | ||
if (this.isStream()) { | ||
return this.contents.pipe(stream, opt); | ||
} | ||
if (this.isBuffer()) { | ||
if (opt.end) { | ||
stream.end(this.contents); | ||
} else { | ||
stream.write(this.contents); | ||
} | ||
return stream; | ||
} | ||
// Check if isNull | ||
if (opt.end) { | ||
stream.end(); | ||
} | ||
return stream; | ||
}; | ||
File.prototype.inspect = function() { | ||
@@ -143,3 +148,3 @@ var inspect = []; | ||
// Use relative path if possible | ||
var filePath = (this.base && this.path) ? this.relative : this.path; | ||
var filePath = this.path ? this.relative : null; | ||
@@ -176,5 +181,13 @@ if (filePath) { | ||
set: function(val) { | ||
if (!isBuffer(val) && !isStream(val) && !isNull(val)) { | ||
if (!isBuffer(val) && !isStream(val) && (val !== null)) { | ||
throw new Error('File.contents can only be a Buffer, a Stream, or null.'); | ||
} | ||
// Ask cloneable if the stream is a already a cloneable | ||
// this avoid piping into many streams | ||
// reducing the overhead of cloning | ||
if (isStream(val) && !cloneable.isCloneable(val)) { | ||
val = cloneable(val); | ||
} | ||
this._contents = val; | ||
@@ -184,8 +197,36 @@ }, | ||
Object.defineProperty(File.prototype, 'cwd', { | ||
get: function() { | ||
return this._cwd; | ||
}, | ||
set: function(cwd) { | ||
if (!cwd || typeof cwd !== 'string') { | ||
throw new Error('cwd must be a non-empty string.'); | ||
} | ||
this._cwd = removeTrailingSep(normalize(cwd)); | ||
}, | ||
}); | ||
Object.defineProperty(File.prototype, 'base', { | ||
get: function() { | ||
return this._base || this._cwd; | ||
}, | ||
set: function(base) { | ||
if (base == null) { | ||
delete this._base; | ||
return; | ||
} | ||
if (typeof base !== 'string' || !base) { | ||
throw new Error('base must be a non-empty string, or null/undefined.'); | ||
} | ||
base = removeTrailingSep(normalize(base)); | ||
if (base !== this._cwd) { | ||
this._base = base; | ||
} | ||
}, | ||
}); | ||
// TODO: Should this be moved to vinyl-fs? | ||
Object.defineProperty(File.prototype, 'relative', { | ||
get: function() { | ||
if (!this.base) { | ||
throw new Error('No base specified! Can not get relative.'); | ||
} | ||
if (!this.path) { | ||
@@ -212,3 +253,3 @@ throw new Error('No path specified! Can not get relative.'); | ||
} | ||
this.path = path.join(dirname, path.basename(this.path)); | ||
this.path = path.join(dirname, this.basename); | ||
}, | ||
@@ -228,3 +269,3 @@ }); | ||
} | ||
this.path = path.join(path.dirname(this.path), basename); | ||
this.path = path.join(this.dirname, basename); | ||
}, | ||
@@ -245,3 +286,3 @@ }); | ||
} | ||
this.path = path.join(path.dirname(this.path), stem + this.extname); | ||
this.path = path.join(this.dirname, stem + this.extname); | ||
}, | ||
@@ -271,4 +312,5 @@ }); | ||
if (typeof path !== 'string') { | ||
throw new Error('path should be string'); | ||
throw new Error('path should be a string.'); | ||
} | ||
path = removeTrailingSep(normalize(path)); | ||
@@ -282,2 +324,16 @@ // Record history only when path changed | ||
Object.defineProperty(File.prototype, 'symlink', { | ||
get: function() { | ||
return this._symlink; | ||
}, | ||
set: function(symlink) { | ||
// TODO: should this set the mode to symbolic if set? | ||
if (typeof symlink !== 'string') { | ||
throw new Error('symlink should be a string'); | ||
} | ||
this._symlink = removeTrailingSep(normalize(symlink)); | ||
}, | ||
}); | ||
module.exports = File; |
{ | ||
"name": "vinyl", | ||
"description": "A virtual file format", | ||
"version": "1.2.0", | ||
"homepage": "http://github.com/gulpjs/vinyl", | ||
"repository": "git://github.com/gulpjs/vinyl.git", | ||
"author": "Fractal <contact@wearefractal.com> (http://wearefractal.com/)", | ||
"main": "./index.js", | ||
"version": "2.0.0", | ||
"description": "Virtual file format.", | ||
"author": "Gulp Team <team@gulpjs.com> (http://gulpjs.com/)", | ||
"contributors": [ | ||
"Eric Schoffstall <yo@contra.io>", | ||
"Blaine Bublitz <blaine.bublitz@gmail.com>" | ||
], | ||
"repository": "gulpjs/vinyl", | ||
"license": "MIT", | ||
"engines": { | ||
"node": ">= 0.10" | ||
}, | ||
"main": "index.js", | ||
"files": [ | ||
"LICENSE", | ||
"index.js", | ||
"lib" | ||
], | ||
"scripts": { | ||
"lint": "eslint . && jscs index.js lib/ test/", | ||
"pretest": "npm run lint", | ||
"test": "mocha --async-only", | ||
"cover": "istanbul cover _mocha --report lcovonly", | ||
"coveralls": "npm run cover && istanbul-coveralls" | ||
}, | ||
"dependencies": { | ||
"clone": "^1.0.0", | ||
"clone-stats": "^0.0.1", | ||
"replace-ext": "0.0.1" | ||
"clone-buffer": "^1.0.0", | ||
"clone-stats": "^1.0.0", | ||
"cloneable-readable": "^0.5.0", | ||
"is-stream": "^1.1.0", | ||
"remove-trailing-separator": "^1.0.1", | ||
"replace-ext": "^1.0.0" | ||
}, | ||
"devDependencies": { | ||
"buffer-equal": "0.0.1", | ||
"eslint": "^1.7.3", | ||
"eslint-config-gulp": "^2.0.0", | ||
"event-stream": "^3.1.0", | ||
"github-changes": "^1.0.1", | ||
"istanbul": "^0.3.0", | ||
"istanbul-coveralls": "^1.0.1", | ||
"expect": "^1.20.2", | ||
"istanbul": "^0.4.3", | ||
"istanbul-coveralls": "^1.0.3", | ||
"jscs": "^2.3.5", | ||
"jscs-preset-gulp": "^1.0.0", | ||
"lodash.templatesettings": "^3.1.0", | ||
"mocha": "^2.0.0", | ||
"rimraf": "^2.2.5", | ||
"should": "^7.0.0" | ||
"mississippi": "^1.2.0", | ||
"mocha": "^2.4.5" | ||
}, | ||
"scripts": { | ||
"lint": "eslint . && jscs *.js lib/ test/", | ||
"pretest": "npm run lint", | ||
"test": "mocha", | ||
"coveralls": "istanbul cover _mocha && istanbul-coveralls", | ||
"changelog": "github-changes -o gulpjs -r vinyl -b master -f ./CHANGELOG.md --order-semver --use-commit-body" | ||
}, | ||
"engines": { | ||
"node": ">= 0.9" | ||
}, | ||
"license": "MIT" | ||
"keywords": [ | ||
"virtual", | ||
"filesystem", | ||
"file", | ||
"directory", | ||
"stat", | ||
"path" | ||
] | ||
} |
446
README.md
@@ -1,158 +0,239 @@ | ||
# vinyl [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Dependency Status][depstat-image]][depstat-url] | ||
<p align="center"> | ||
<a href="http://gulpjs.com"> | ||
<img height="257" width="114" src="https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png"> | ||
</a> | ||
</p> | ||
## Information | ||
<table><tr><td>Package</td><td>vinyl</td></tr><tr><td>Description</td><td>A virtual file format</td></tr><tr><td>Node Version</td><td>>= 0.9</td></tr></table> | ||
# vinyl | ||
## What is this? | ||
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) | ||
[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][travis-image]][travis-url] [![AppVeyor Build Status][appveyor-image]][appveyor-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Gitter chat][gitter-image]][gitter-url] | ||
## File | ||
Virtual file format. | ||
```javascript | ||
var File = require('vinyl'); | ||
## What is Vinyl? | ||
var coffeeFile = new File({ | ||
cwd: "/", | ||
base: "/test/", | ||
path: "/test/file.coffee", | ||
contents: new Buffer("test = 123") | ||
Vinyl is a very simple metadata object that describes a file. When you think of a file, two attributes come to mind: `path` and `contents`. These are the main attributes on a Vinyl object. A file does not necessarily represent something on your computer’s file system. You have files on S3, FTP, Dropbox, Box, CloudThingly.io and other services. Vinyl can be used to describe files from all of these sources. | ||
## What is a Vinyl Adapter? | ||
While Vinyl provides a clean way to describe a file, we also need a way to access these files. Each file source needs what I call a "Vinyl adapter". A Vinyl adapter simply exposes a `src(globs)` and a `dest(folder)` method. Each return a stream. The `src` stream produces Vinyl objects, and the `dest` stream consumes Vinyl objects. Vinyl adapters can expose extra methods that might be specific to their input/output medium, such as the `symlink` method [`vinyl-fs`][vinyl-fs] provides. | ||
## Usage | ||
```js | ||
var Vinyl = require('vinyl'); | ||
var jsFile = new Vinyl({ | ||
cwd: '/', | ||
base: '/test/', | ||
path: '/test/file.js', | ||
contents: new Buffer('var x = 123') | ||
}); | ||
``` | ||
### isVinyl | ||
When checking if an object is a vinyl file, you should not use instanceof. Use the isVinyl function instead. | ||
## API | ||
```js | ||
var File = require('vinyl'); | ||
### `new Vinyl([options])` | ||
var dummy = new File({stuff}); | ||
var notAFile = {}; | ||
The constructor is used to create a new instance of `Vinyl`. Each instance represents a separate file, directory or symlink. | ||
File.isVinyl(dummy); // true | ||
File.isVinyl(notAFile); // false | ||
``` | ||
All internally managed paths (`cwd`, `base`, `path`, `history`) are normalized and have trailing separators removed. See [Normalization and concatenation][normalization] for more information. | ||
### isCustomProp | ||
Vinyl checks if a property is not managed internally, such as `sourceMap`. This is than used in `constructor(options)` when setting, and `clone()` when copying properties. | ||
Options may be passed upon instantiation to create a file with specific properties. | ||
```js | ||
var File = require('vinyl'); | ||
#### `options` | ||
File.isCustomProp('sourceMap'); // true | ||
File.isCustomProp('path'); // false -> internal getter/setter | ||
``` | ||
Options are not mutated by the constructor. | ||
Read more in [Extending Vinyl](#extending-vinyl). | ||
##### `options.cwd` | ||
### constructor(options) | ||
#### options.cwd | ||
Type: `String`<br><br>Default: `process.cwd()` | ||
The current working directory of the file. | ||
#### options.base | ||
Used for relative pathing. Typically where a glob starts. | ||
Type: `String` | ||
Type: `String`<br><br>Default: `options.cwd` | ||
Default: `process.cwd()` | ||
#### options.path | ||
Full path to the file. | ||
##### `options.base` | ||
Type: `String`<br><br>Default: `undefined` | ||
Used for calculating the `relative` property. This is typically where a glob starts. | ||
#### options.history | ||
Path history. Has no effect if `options.path` is passed. | ||
Type: `String` | ||
Type: `Array`<br><br>Default: `options.path ? [options.path] : []` | ||
Default: `options.cwd` | ||
#### options.stat | ||
The result of an fs.stat call. See [fs.Stats](http://nodejs.org/api/fs.html#fs_class_fs_stats) for more information. | ||
##### `options.path` | ||
Type: `fs.Stats`<br><br>Default: `null` | ||
The full path to the file. | ||
#### options.contents | ||
File contents. | ||
Type: `String` | ||
Type: `Buffer, Stream, or null`<br><br>Default: `null` | ||
Default: `undefined` | ||
#### options.{custom} | ||
Any other option properties will just be assigned to the new File object. | ||
##### `options.history` | ||
Stores the path history. If `options.path` and `options.history` are both passed, `options.path` is appended to `options.history`. All `options.history` paths are normalized by the `file.path` setter. | ||
Type: `Array` | ||
Default: `[]` (or `[options.path]` if `options.path` is passed) | ||
##### `options.stat` | ||
The result of an `fs.stat` call. This is how you mark the file as a directory or symbolic link. See [isDirectory()][is-directory], [isSymbolic()][is-symbolic] and [fs.Stats][fs-stats] for more information. | ||
Type: [`fs.Stats`][fs-stats] | ||
Default: `undefined` | ||
##### `options.contents` | ||
The contents of the file. If `options.contents` is a [`Stream`][stream], it is wrapped in a [`cloneable-readable`][cloneable-readable] stream. | ||
Type: [`Stream`][stream], [`Buffer`][buffer], or `null` | ||
Default: `null` | ||
##### `options.{custom}` | ||
Any other option properties will be directly assigned to the new Vinyl object. | ||
```js | ||
var File = require('vinyl'); | ||
var Vinyl = require('vinyl'); | ||
var file = new File({foo: 'bar'}); | ||
var file = new Vinyl({ foo: 'bar' }); | ||
file.foo === 'bar'; // true | ||
``` | ||
### isBuffer() | ||
Returns true if file.contents is a Buffer. | ||
### Instance methods | ||
### isStream() | ||
Returns true if file.contents is a Stream. | ||
Each Vinyl object will have instance methods. Every method will be available but may return differently based on what properties were set upon instantiation or modified since. | ||
### isNull() | ||
Returns true if file.contents is null. | ||
#### `file.isBuffer()` | ||
### clone([opt]) | ||
Returns a new File object with all attributes cloned.<br>By default custom attributes are deep-cloned. | ||
Returns `true` if the file contents are a [`Buffer`][buffer], otherwise `false`. | ||
If opt or opt.deep is false, custom attributes will not be deep-cloned. | ||
#### `file.isStream()` | ||
If opt.contents is false, it will copy file.contents Buffer's reference. | ||
Returns `true` if the file contents are a [`Stream`][stream], otherwise `false`. | ||
### pipe(stream[, opt]) | ||
If file.contents is a Buffer, it will write it to the stream. | ||
#### `file.isNull()` | ||
If file.contents is a Stream, it will pipe it to the stream. | ||
Returns `true` if the file contents are `null`, otherwise `false`. | ||
If file.contents is null, it will do nothing. | ||
#### `file.isDirectory()` | ||
If opt.end is false, the destination stream will not be ended (same as node core). | ||
Returns `true` if the file represents a directory, otherwise `false`. | ||
Returns the stream. | ||
A file is considered a directory when: | ||
### inspect() | ||
Returns a pretty String interpretation of the File. Useful for console.log. | ||
- `file.isNull()` is `true` | ||
- `file.stat` is an object | ||
- `file.stat.isDirectory()` returns `true` | ||
### contents | ||
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. | ||
When constructing a Vinyl object, pass in a valid [`fs.Stats`][fs-stats] object via `options.stat`. If you are mocking the [`fs.Stats`][fs-stats] object, you may need to stub the `isDirectory()` method. | ||
For example: | ||
#### `file.isSymbolic()` | ||
```js | ||
if (file.isBuffer()) { | ||
console.log(file.contents.toString()); // logs out the string of contents | ||
} | ||
``` | ||
Returns `true` if the file represents a symbolic link, otherwise `false`. | ||
### path | ||
Absolute pathname string or `undefined`. Setting to a different value pushes the old value to `history`. | ||
A file is considered symbolic when: | ||
### history | ||
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`. | ||
- `file.isNull()` is `true` | ||
- `file.stat` is an object | ||
- `file.stat.isSymbolicLink()` returns `true` | ||
### relative | ||
Returns path.relative for the file base and file path. | ||
When constructing a Vinyl object, pass in a valid [`fs.Stats`][fs-stats] object via `options.stat`. If you are mocking the [`fs.Stats`][fs-stats] object, you may need to stub the `isSymbolicLink()` method. | ||
#### `file.clone([options])` | ||
Returns a new Vinyl object with all attributes cloned. | ||
__By default custom attributes are cloned deeply.__ | ||
If `options` or `options.deep` is `false`, custom attributes will not be cloned deeply. | ||
If `file.contents` is a [`Buffer`][buffer] and `options.contents` is `false`, the [`Buffer`][buffer] reference will be reused instead of copied. | ||
#### `file.inspect()` | ||
Returns a formatted-string interpretation of the Vinyl object. Automatically called by node's `console.log`. | ||
### Instance properties | ||
Each Vinyl object will have instance properties. Some may be unavailable based on what properties were set upon instantiation or modified since. | ||
#### `file.contents` | ||
Gets and sets the contents of the file. If set to a [`Stream`][stream], it is wrapped in a [`cloneable-readable`][cloneable-readable] stream. | ||
Throws when set to any value other than a [`Stream`][stream], a [`Buffer`][buffer] or `null`. | ||
Type: [`Stream`][stream], [`Buffer`][buffer] or `null` | ||
#### `file.cwd` | ||
Gets and sets current working directory. Will always be normalized and have trailing separators removed. | ||
Throws when set to any value other than non-empty strings. | ||
Type: `String` | ||
#### `file.base` | ||
Gets and sets base directory. Used for relative pathing (typically where a glob starts). | ||
When `null` or `undefined`, it simply proxies the `file.cwd` property. Will always be normalized and have trailing separators removed. | ||
Throws when set to any value other than non-empty strings or `null`/`undefined`. | ||
Type: `String` | ||
#### `file.path` | ||
Gets and sets the absolute pathname string or `undefined`. Setting to a different value appends the new path to `file.history`. If set to the same value as the current path, it is ignored. All new values are normalized and have trailing separators removed. | ||
Throws when set to any value other than a string. | ||
Type: `String` | ||
#### `file.history` | ||
Array of `file.path` values the Vinyl object has had, from `file.history[0]` (original) through `file.history[file.history.length - 1]` (current). `file.history` and its elements should normally be treated as read-only and only altered indirectly by setting `file.path`. | ||
Type: `Array` | ||
#### `file.relative` | ||
Gets the result of `path.relative(file.base, file.path)`. | ||
Throws when set or when `file.path` is not set. | ||
Type: `String` | ||
Example: | ||
```javascript | ||
```js | ||
var file = new File({ | ||
cwd: "/", | ||
base: "/test/", | ||
path: "/test/file.coffee" | ||
cwd: '/', | ||
base: '/test/', | ||
path: '/test/file.js' | ||
}); | ||
console.log(file.relative); // file.coffee | ||
console.log(file.relative); // file.js | ||
``` | ||
### dirname | ||
Gets and sets path.dirname for the file path. | ||
#### `file.dirname` | ||
Gets and sets the dirname of `file.path`. Will always be normalized and have trailing separators removed. | ||
Throws when `file.path` is not set. | ||
Type: `String` | ||
Example: | ||
```javascript | ||
```js | ||
var file = new File({ | ||
cwd: "/", | ||
base: "/test/", | ||
path: "/test/file.coffee" | ||
cwd: '/', | ||
base: '/test/', | ||
path: '/test/file.js' | ||
}); | ||
@@ -165,35 +246,45 @@ | ||
console.log(file.dirname); // /specs | ||
console.log(file.path); // /specs/file.coffee | ||
console.log(file.path); // /specs/file.js | ||
``` | ||
### basename | ||
Gets and sets path.basename for the file path. | ||
#### `file.basename` | ||
Gets and sets the basename of `file.path`. | ||
Throws when `file.path` is not set. | ||
Type: `String` | ||
Example: | ||
```javascript | ||
```js | ||
var file = new File({ | ||
cwd: "/", | ||
base: "/test/", | ||
path: "/test/file.coffee" | ||
cwd: '/', | ||
base: '/test/', | ||
path: '/test/file.js' | ||
}); | ||
console.log(file.basename); // file.coffee | ||
console.log(file.basename); // file.js | ||
file.basename = 'file.js'; | ||
file.basename = 'file.txt'; | ||
console.log(file.basename); // file.js | ||
console.log(file.path); // /test/file.js | ||
console.log(file.basename); // file.txt | ||
console.log(file.path); // /test/file.txt | ||
``` | ||
### stem | ||
Gets and sets stem (filename without suffix) for the file path. | ||
#### `file.stem` | ||
Gets and sets stem (filename without suffix) of `file.path`. | ||
Throws when `file.path` is not set. | ||
Type: `String` | ||
Example: | ||
```javascript | ||
```js | ||
var file = new File({ | ||
cwd: "/", | ||
base: "/test/", | ||
path: "/test/file.coffee" | ||
cwd: '/', | ||
base: '/test/', | ||
path: '/test/file.js' | ||
}); | ||
@@ -206,26 +297,94 @@ | ||
console.log(file.stem); // foo | ||
console.log(file.path); // /test/foo.coffee | ||
console.log(file.path); // /test/foo.js | ||
``` | ||
### extname | ||
Gets and sets path.extname for the file path. | ||
#### `file.extname` | ||
Gets and sets extname of `file.path`. | ||
Throws when `file.path` is not set. | ||
Type: `String` | ||
Example: | ||
```javascript | ||
```js | ||
var file = new File({ | ||
cwd: "/", | ||
base: "/test/", | ||
path: "/test/file.coffee" | ||
cwd: '/', | ||
base: '/test/', | ||
path: '/test/file.js' | ||
}); | ||
console.log(file.extname); // .coffee | ||
console.log(file.extname); // .js | ||
file.extname = '.js'; | ||
file.extname = '.txt'; | ||
console.log(file.extname); // .js | ||
console.log(file.path); // /test/file.js | ||
console.log(file.extname); // .txt | ||
console.log(file.path); // /test/file.txt | ||
``` | ||
#### `file.symlink` | ||
Gets and sets the path where the file points to if it's a symbolic link. Will always be normalized and have trailing separators removed. | ||
Throws when set to any value other than a string. | ||
Type: `String` | ||
### `Vinyl.isVinyl(file)` | ||
Static method used for checking if an object is a Vinyl file. Use this method instead of `instanceof`. | ||
Takes an object and returns `true` if it is a Vinyl file, otherwise returns `false`. | ||
__Note: This method uses an internal flag that some older versions of Vinyl didn't expose.__ | ||
Example: | ||
```js | ||
var Vinyl = require('vinyl'); | ||
var file = new Vinyl(); | ||
var notAFile = {}; | ||
Vinyl.isVinyl(file); // true | ||
Vinyl.isVinyl(notAFile); // false | ||
``` | ||
### `Vinyl.isCustomProp(property)` | ||
Static method used by Vinyl when setting values inside the constructor or when copying properties in `file.clone()`. | ||
Takes a string `property` and returns `true` if the property is not used internally, otherwise returns `false`. | ||
This method is usefuly for inheritting from the Vinyl constructor. Read more in [Extending Vinyl][extending-vinyl]. | ||
Example: | ||
```js | ||
var Vinyl = require('vinyl'); | ||
Vinyl.isCustomProp('sourceMap'); // true | ||
Vinyl.isCustomProp('path'); // false -> internal getter/setter | ||
``` | ||
## Normalization and concatenation | ||
Since all properties are normalized in their setters, you can just concatenate with `/`, and normalization takes care of it properly on all platforms. | ||
Example: | ||
```js | ||
var file = new File(); | ||
file.path = '/' + 'test' + '/' + 'foo.bar'; | ||
console.log(file.path); | ||
// posix => /test/foo.bar | ||
// win32 => \\test\\foo.bar | ||
``` | ||
But never concatenate with `\`, since that is a valid filename character on posix system. | ||
## Extending Vinyl | ||
When extending Vinyl into your own class with extra features, you need to think about a few things. | ||
@@ -236,7 +395,7 @@ | ||
```js | ||
const File = require('vinyl'); | ||
var Vinyl = require('vinyl'); | ||
const builtInProps = ['foo', '_foo']; | ||
var builtInProps = ['foo', '_foo']; | ||
class SuperFile extends File { | ||
class SuperFile extends Vinyl { | ||
constructor(options) { | ||
@@ -261,9 +420,30 @@ super(options); | ||
[npm-url]: https://npmjs.org/package/vinyl | ||
[npm-image]: https://badge.fury.io/js/vinyl.svg | ||
## License | ||
MIT | ||
[is-symbolic]: #issymbolic | ||
[is-directory]: #isdirectory | ||
[normalization]: #normalization-and-concatenation | ||
[extending-vinyl]: #extending-vinyl | ||
[stream]: https://nodejs.org/api/stream.html#stream_stream | ||
[buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer | ||
[fs-stats]: http://nodejs.org/api/fs.html#fs_class_fs_stats | ||
[vinyl-fs]: https://github.com/gulpjs/vinyl-fs | ||
[cloneable-readable]: https://github.com/mcollina/cloneable-readable | ||
[downloads-image]: http://img.shields.io/npm/dm/vinyl.svg | ||
[npm-url]: https://www.npmjs.com/package/vinyl | ||
[npm-image]: http://img.shields.io/npm/v/vinyl.svg | ||
[travis-url]: https://travis-ci.org/gulpjs/vinyl | ||
[travis-image]: https://travis-ci.org/gulpjs/vinyl.svg?branch=master | ||
[coveralls-url]: https://coveralls.io/github/gulpjs/vinyl | ||
[coveralls-image]: https://coveralls.io/repos/github/gulpjs/vinyl/badge.svg | ||
[depstat-url]: https://david-dm.org/gulpjs/vinyl | ||
[depstat-image]: https://david-dm.org/gulpjs/vinyl.svg | ||
[travis-image]: http://img.shields.io/travis/gulpjs/vinyl.svg?label=travis-ci | ||
[appveyor-url]: https://ci.appveyor.com/project/gulpjs/vinyl | ||
[appveyor-image]: https://img.shields.io/appveyor/ci/gulpjs/vinyl.svg?label=appveyor | ||
[coveralls-url]: https://coveralls.io/r/gulpjs/vinyl | ||
[coveralls-image]: http://img.shields.io/coveralls/gulpjs/vinyl/master.svg | ||
[gitter-url]: https://gitter.im/gulpjs/gulp | ||
[gitter-image]: https://badges.gitter.im/gulpjs/gulp.svg |
Sorry, the diff of this file is not supported yet
9
296
446
23342
7
6
+ Addedclone-buffer@^1.0.0
+ Addedcloneable-readable@^0.5.0
+ Addedis-stream@^1.1.0
+ Addedclone-buffer@1.0.0(transitive)
+ Addedclone-stats@1.0.0(transitive)
+ Addedcloneable-readable@0.5.0(transitive)
+ Addedcore-util-is@1.0.3(transitive)
+ Addedinherits@2.0.4(transitive)
+ Addedis-stream@1.1.0(transitive)
+ Addedisarray@1.0.0(transitive)
+ Addedprocess-nextick-args@1.0.72.0.1(transitive)
+ Addedreadable-stream@2.3.8(transitive)
+ Addedremove-trailing-separator@1.1.0(transitive)
+ Addedreplace-ext@1.0.1(transitive)
+ Addedsafe-buffer@5.1.2(transitive)
+ Addedstring_decoder@1.1.1(transitive)
+ Addedthrough2@2.0.5(transitive)
+ Addedutil-deprecate@1.0.2(transitive)
+ Addedxtend@4.0.2(transitive)
- Removedclone-stats@0.0.1(transitive)
- Removedreplace-ext@0.0.1(transitive)
Updatedclone-stats@^1.0.0
Updatedreplace-ext@^1.0.0