Skip to content

Commit

Permalink
Docs: Add Vinyl documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
janiceilene authored and phated committed Oct 19, 2018
1 parent 69c22f0 commit fc09067
Showing 1 changed file with 141 additions and 0 deletions.
141 changes: 141 additions & 0 deletions docs/api/vinyl.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
<!-- front-matter
id: api-vinyl
title: Vinyl
hide_title: true
sidebar_label: Vinyl
-->

# Vinyl

A virtual file format. When a file is read by `src()`, a Vinyl object is generated to represent the file - including the path, contents, and other metadata.

Vinyl objects can have transformations applied using [plugins][using-plugins-docs]. They may also be persisted to the file system using `dest()`.

When creating your own Vinyl objects - instead of generating with `src()` - use the external `vinyl` module, as shown in Usage below.

## Usage

```js
const Vinyl = require('vinyl');

const file = new Vinyl({
cwd: '/',
base: '/test/',
path: '/test/file.js',
contents: new Buffer('var x = 123')
});

file.relative === 'file.js';

file.dirname === '/test';
file.dirname = '/specs';
file.path === '/specs/file.js';

file.basename === 'file.js';
file.basename = 'file.txt';
file.path === '/specs/file.txt';

file.stem === 'file';
file.stem = 'foo';
file.path === '/specs/foo.txt';
file.extname === '.txt';
file.extname = '.js';
file.path === '/specs/file.js';
```

## Signature

```js
new Vinyl([options])
```

### Parameters

| parameter | type | note |
|:--------------:|:------:|-------|
| options | object | Detailed in [Options][options-section] below. |

### Returns

An instance of the Vinyl class representing a single virtual file, detailed in [Vinyl instance][vinyl-instance-section] below.

### Errors

When any passed options don't conform to the [instance property definitions][instance-properties-section] (like if `path` is set to a number) throws as defined in the table.

### Options

| name | type | default | note |
|:-------:|:------:|-----------|--------|
| cwd | string | `process.cwd()` | The directory from which relative paths will be derived. Will be [normalized][normalization-and-concatenation-section] and have trailing separators removed. |
| base | string | | Used to calculate the `relative` instance property. Falls back to the value of `cwd` if not set. Typically set to the [glob base][glob-base-concepts]. Will be [normalized][normalization-and-concatenation-section] and have trailing separators removed.|
| path | string | | The full, absolute file path. Will be [normalized][normalization-and-concatenation-section] and have trailing separators removed. |
| history | array | `[ ]` | An array of paths to pre-populate the `history` of a Vinyl instance. Usually comes from deriving a new Vinyl object from a previous Vinyl object. If `path` and `history` are both passed, `path` is appended to `history`. Each item will be [normalized][normalization-and-concatenation-section] and have trailing separators removed. |
| stat | object | | An instance of `fs.Stats`, usually the result of calling `fs.stat()` on a file. Used to determine if a Vinyl object represents a directory or symbolic link. |
| contents | ReadableStream <br> Buffer <br> null | null | The contents of the file. If `contents` is a ReadableStream, it is wrapped in a [cloneable-readable][cloneable-readable-external] stream. |

Any other properties on `options` will be directly assigned to the Vinyl instance.

```js
const Vinyl = require('vinyl');

const file = new Vinyl({ foo: 'bar' });
file.foo === 'bar';
```

## Vinyl instance

Each instance of a Vinyl object will have properties and methods to access and/or modify information about the virtual file.

### Instance properties

All internally managed paths - any instance property except `contents` and `stat` - are normalized and have trailing separators removed. See [Normalization and concatenation][normalization-and-concatenation-section] for more information.

| property | type | description | throws |
|:-----------:|:------:|----------------|----------|
| contents | ReadableStream <br> Buffer <br> `null` | Gets and sets the contents of the virtual file. If set to a ReadableStream, it is wrapped in a [cloneable-readable][cloneable-readable-docs] stream. | If set to any value other than a ReadableStream, a Buffer, or `null`. |
| stat | object | Gets and sets an instance of [`fs.Stats`][fs-stats-concepts]. Used when determining if a Vinyl object represents a directory or symbolic link. | |
| cwd | string | Gets and sets the current working directory. Used for deriving relative paths. | If set to an empty string or any non-string value. |
| base | string | Gets and sets the base directory. Used to calculate the `relative` instance property. On a Vinyl object generated by `src()` will be set to the [glob base][glob-base-concepts]. If set to `null` or `undefined`, falls back to the value of the `cwd` instance property. | If set to an empty string or any non-string value (except `null` or `undefined`). |
| path | string | Gets and sets the full, absolute file path. Setting to a value different from the current `path` appends the new path to the `history` instance property. | If set to any non-string value. |
| history | array | Array of all `path` values the Vinyl object has been assigned. The first element (`history[0]`) is the original path and the last element (`history[file.history.length - 1]`) is the current path. This property and its elements should be treated as read-only and only altered indirectly by setting the `path` instance property. | |
| relative | string | Gets the relative path segment between the `base` and the `path` instance properties. | If set to any value. If accessed when `path` is not available. |
| dirname | string | Gets and sets the directory of the `path` instance property. | If accessed when `path` is not available. |
| stem | string | Gets and sets the stem (filename without extension) of the `path` instance property. | If accessed when `path` is not available. |
| extname | string | Gets and sets the extension of the `path` instance property. | If accessed when `path` is not available. |
| basename | string | Gets and sets the filename (`stem + extname`) of the `path` instance property. | If accessed when `path` is not available. |
| symlink | string | Gets and sets the reference path of a symbolic link. | If set to any non-string value. |

### Instance methods

| method | return type | returns |
|:----------:|:--------------:|--------|
| `isBuffer()` | boolean | If the `contents` instance property is a Buffer, returns true. |
| `isStream()` | boolean | If the `contents` instance property is a Stream, returns true. |
| `isNull()` | boolean | If the `contents` instance property is `null`, returns true. |
| `isDirectory()` | boolean | If the instance represents a directory, returns true. An instance is considered a directory when `isNull()` returns true, the `stat` instance property is an object, and `stat.isDirectory()` returns true. This assumes a Vinyl object was constructed with a valid (or properly mocked) `fs.Stats` object. |
| `isSymbolic()` | boolean | If the instance represents a symbolic link, returns true. An instance is considered symbolic when `isNull()` returns true, the `stat` instance property is an object, and `stat.isSymbolicLink()` returns true. This assumes a Vinyl object was constructed with a valid (or properly mocked) `fs.Stats` object. |
| `clone([options])` | object | A new Vinyl object with all properties cloned. By default custom properties are deep cloned. If the `deep` option is false, custom attributes will be shallow cloned. If the `contents` option is false and the `contents` instance property is a Buffer, the Buffer will be reused instead of cloned. |
| `inspect()` | string | Returns a formatted interpretation of the Vinyl object. Automatically called by Node's console.log. |

## Normalization and concatenation

All path properties are normalized by their setters. Concatenate paths with `/`, instead of using `path.join()`, and normalization will occur properly on all platforms. Never concatenate with `\` - it is a valid filename character on posix system.

```js
const file = new File();
file.path = '/' + 'test' + '/' + 'foo.bar';

console.log(file.path);
// posix => /test/foo.bar
// win32 => \\test\\foo.bar
```

[options-section]: #options
[vinyl-instance-section]: #vinyl-instance
[instance-properties-section]: #instance-properties
[normalization-and-concatenation-section]: #normalization-and-concatenation
[glob-base-concepts]: concepts.md#glob-base
[fs-stats-concepts]: concepts.md#file-system-stats
[using-plugins-docs]: ../getting-started/7-using-plugins.md
[cloneable-readable-external]: https://github.com/mcollina/cloneable-readable

0 comments on commit fc09067

Please sign in to comment.