Skip to content

Commit fc09067

Browse files
janiceilenephated
janiceilene
authored and
phated
committed
Docs: Add Vinyl documentation
1 parent 69c22f0 commit fc09067

File tree

1 file changed

+141
-0
lines changed

1 file changed

+141
-0
lines changed

‎docs/api/vinyl.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
<!-- front-matter
2+
id: api-vinyl
3+
title: Vinyl
4+
hide_title: true
5+
sidebar_label: Vinyl
6+
-->
7+
8+
# Vinyl
9+
10+
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.
11+
12+
Vinyl objects can have transformations applied using [plugins][using-plugins-docs]. They may also be persisted to the file system using `dest()`.
13+
14+
When creating your own Vinyl objects - instead of generating with `src()` - use the external `vinyl` module, as shown in Usage below.
15+
16+
## Usage
17+
18+
```js
19+
const Vinyl = require('vinyl');
20+
21+
const file = new Vinyl({
22+
cwd: '/',
23+
base: '/test/',
24+
path: '/test/file.js',
25+
contents: new Buffer('var x = 123')
26+
});
27+
28+
file.relative === 'file.js';
29+
30+
file.dirname === '/test';
31+
file.dirname = '/specs';
32+
file.path === '/specs/file.js';
33+
34+
file.basename === 'file.js';
35+
file.basename = 'file.txt';
36+
file.path === '/specs/file.txt';
37+
38+
file.stem === 'file';
39+
file.stem = 'foo';
40+
file.path === '/specs/foo.txt';
41+
file.extname === '.txt';
42+
file.extname = '.js';
43+
file.path === '/specs/file.js';
44+
```
45+
46+
## Signature
47+
48+
```js
49+
new Vinyl([options])
50+
```
51+
52+
### Parameters
53+
54+
| parameter | type | note |
55+
|:--------------:|:------:|-------|
56+
| options | object | Detailed in [Options][options-section] below. |
57+
58+
### Returns
59+
60+
An instance of the Vinyl class representing a single virtual file, detailed in [Vinyl instance][vinyl-instance-section] below.
61+
62+
### Errors
63+
64+
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.
65+
66+
### Options
67+
68+
| name | type | default | note |
69+
|:-------:|:------:|-----------|--------|
70+
| 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. |
71+
| 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.|
72+
| path | string | | The full, absolute file path. Will be [normalized][normalization-and-concatenation-section] and have trailing separators removed. |
73+
| 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. |
74+
| 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. |
75+
| 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. |
76+
77+
Any other properties on `options` will be directly assigned to the Vinyl instance.
78+
79+
```js
80+
const Vinyl = require('vinyl');
81+
82+
const file = new Vinyl({ foo: 'bar' });
83+
file.foo === 'bar';
84+
```
85+
86+
## Vinyl instance
87+
88+
Each instance of a Vinyl object will have properties and methods to access and/or modify information about the virtual file.
89+
90+
### Instance properties
91+
92+
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.
93+
94+
| property | type | description | throws |
95+
|:-----------:|:------:|----------------|----------|
96+
| 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`. |
97+
| 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. | |
98+
| 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. |
99+
| 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`). |
100+
| 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. |
101+
| 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. | |
102+
| 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. |
103+
| dirname | string | Gets and sets the directory of the `path` instance property. | If accessed when `path` is not available. |
104+
| stem | string | Gets and sets the stem (filename without extension) of the `path` instance property. | If accessed when `path` is not available. |
105+
| extname | string | Gets and sets the extension of the `path` instance property. | If accessed when `path` is not available. |
106+
| basename | string | Gets and sets the filename (`stem + extname`) of the `path` instance property. | If accessed when `path` is not available. |
107+
| symlink | string | Gets and sets the reference path of a symbolic link. | If set to any non-string value. |
108+
109+
### Instance methods
110+
111+
| method | return type | returns |
112+
|:----------:|:--------------:|--------|
113+
| `isBuffer()` | boolean | If the `contents` instance property is a Buffer, returns true. |
114+
| `isStream()` | boolean | If the `contents` instance property is a Stream, returns true. |
115+
| `isNull()` | boolean | If the `contents` instance property is `null`, returns true. |
116+
| `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. |
117+
| `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. |
118+
| `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. |
119+
| `inspect()` | string | Returns a formatted interpretation of the Vinyl object. Automatically called by Node's console.log. |
120+
121+
## Normalization and concatenation
122+
123+
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.
124+
125+
```js
126+
const file = new File();
127+
file.path = '/' + 'test' + '/' + 'foo.bar';
128+
129+
console.log(file.path);
130+
// posix => /test/foo.bar
131+
// win32 => \\test\\foo.bar
132+
```
133+
134+
[options-section]: #options
135+
[vinyl-instance-section]: #vinyl-instance
136+
[instance-properties-section]: #instance-properties
137+
[normalization-and-concatenation-section]: #normalization-and-concatenation
138+
[glob-base-concepts]: concepts.md#glob-base
139+
[fs-stats-concepts]: concepts.md#file-system-stats
140+
[using-plugins-docs]: ../getting-started/7-using-plugins.md
141+
[cloneable-readable-external]: https://github.com/mcollina/cloneable-readable

0 commit comments

Comments
 (0)