348 lines
10 KiB
Markdown
348 lines
10 KiB
Markdown
# ![vfile][]
|
||
|
||
[![Travis][build-badge]][build]
|
||
[![Coverage][coverage-badge]][coverage]
|
||
[![Downloads][downloads-badge]][downloads]
|
||
[![Size][size-badge]][size]
|
||
[![Chat][chat-badge]][chat]
|
||
|
||
**VFile** is a virtual file format used by [**unified**][unified],
|
||
a text processing umbrella (it powers [**retext**][retext] for
|
||
natural language, [**remark**][remark] for markdown, and
|
||
[**rehype**][rehype] for HTML). Each processors that parse, transform,
|
||
and compile text, and need a virtual representation of files and a
|
||
place to store [messages][] about them. Plus, they work in the browser.
|
||
**VFile** provides these requirements at a small size, in IE 9 and up.
|
||
|
||
> **VFile** is different from the excellent [**vinyl**][vinyl]
|
||
> in that it has a smaller API, a smaller size, and focuses on
|
||
> [messages][].
|
||
|
||
VFile can be used anywhere where files need a lightweight representation.
|
||
For example, it’s used in:
|
||
|
||
* [`documentation`](https://github.com/documentationjs/documentation)
|
||
— The documentation system for modern JavaScript
|
||
* [`awoo`](https://github.com/awoojs/awoo)
|
||
— Declarative small site generator
|
||
* [`geojsonhint`](https://github.com/mapbox/geojsonhint)
|
||
— Complete, fast, standards-based validation for geojson
|
||
|
||
## Installation
|
||
|
||
[npm][]:
|
||
|
||
```bash
|
||
npm install vfile
|
||
```
|
||
|
||
## Table of Contents
|
||
|
||
* [Usage](#usage)
|
||
* [Utilities](#utilities)
|
||
* [Reporters](#reporters)
|
||
* [API](#api)
|
||
* [VFile(\[options\])](#vfileoptions)
|
||
* [vfile.contents](#vfilecontents)
|
||
* [vfile.cwd](#vfilecwd)
|
||
* [vfile.path](#vfilepath)
|
||
* [vfile.basename](#vfilebasename)
|
||
* [vfile.stem](#vfilestem)
|
||
* [vfile.extname](#vfileextname)
|
||
* [vfile.dirname](#vfiledirname)
|
||
* [vfile.history](#vfilehistory)
|
||
* [vfile.messages](#vfilemessages)
|
||
* [vfile.data](#vfiledata)
|
||
* [VFile#toString(\[encoding\])](#vfiletostringencoding)
|
||
* [VFile#message(reason\[, position\]\[, origin\])](#vfilemessagereason-position-origin)
|
||
* [VFile#info(reason\[, position\]\[, origin\])](#vfileinforeason-position-origin)
|
||
* [VFile#fail(reason\[, position\]\[, origin\])](#vfilefailreason-position-origin)
|
||
* [Contribute](#contribute)
|
||
* [Acknowledgments](#acknowledgments)
|
||
* [License](#license)
|
||
|
||
## Usage
|
||
|
||
```js
|
||
var vfile = require('vfile')
|
||
|
||
var file = vfile({path: '~/example.txt', contents: 'Alpha *braavo* charlie.'})
|
||
|
||
file.path // => '~/example.txt'
|
||
file.dirname // => '~'
|
||
|
||
file.extname = '.md'
|
||
|
||
file.basename // => 'example.md'
|
||
|
||
file.basename = 'index.text'
|
||
|
||
file.history // => ['~/example.txt', '~/example.md', '~/index.text']
|
||
|
||
file.message('`braavo` is misspelt; did you mean `bravo`?', {
|
||
line: 1,
|
||
column: 8
|
||
})
|
||
|
||
console.log(file.messages)
|
||
```
|
||
|
||
Yields:
|
||
|
||
```js
|
||
[ { [~/index.text:1:8: `braavo` is misspelt; did you mean `bravo`?]
|
||
message: '`braavo` is misspelt; did you mean `bravo`?',
|
||
name: '~/index.text:1:8',
|
||
file: '~/index.text',
|
||
reason: '`braavo` is misspelt; did you mean `bravo`?',
|
||
line: 1,
|
||
column: 8,
|
||
location: { start: [Object], end: [Object] },
|
||
ruleId: null,
|
||
source: null,
|
||
fatal: false } ]
|
||
```
|
||
|
||
## Utilities
|
||
|
||
The following list of projects includes tools for working with virtual
|
||
files. See [**Unist**][unist] for projects working with nodes.
|
||
|
||
* [`convert-vinyl-to-vfile`](https://github.com/dustinspecker/convert-vinyl-to-vfile)
|
||
— Convert from [Vinyl][]
|
||
* [`is-vfile-message`](https://github.com/shinnn/is-vfile-message)
|
||
— Check if a value is a `VMessage` object
|
||
* [`to-vfile`](https://github.com/vfile/to-vfile)
|
||
— Create a virtual file from a file-path (and optionally read it)
|
||
* [`vfile-find-down`](https://github.com/vfile/vfile-find-down)
|
||
— Find files by searching the file system downwards
|
||
* [`vfile-find-up`](https://github.com/vfile/vfile-find-up)
|
||
— Find files by searching the file system upwards
|
||
* [`vfile-glob`](https://github.com/shinnn/vfile-glob)
|
||
— Find files by glob patterns
|
||
* [`vfile-location`](https://github.com/vfile/vfile-location)
|
||
— Convert between line/column- and range-based locations
|
||
* [`vfile-message`](https://github.com/vfile/vfile-message)
|
||
— Create a `VMessage` object (used in `vfile` itself)
|
||
* [`vfile-statistics`](https://github.com/vfile/vfile-statistics)
|
||
— Count messages per category
|
||
* [`vfile-messages-to-vscode-diagnostics`](https://github.com/shinnn/vfile-messages-to-vscode-diagnostics)
|
||
— Convert to VS Code diagnostics
|
||
* [`vfile-sort`](https://github.com/vfile/vfile-sort)
|
||
— Sort messages by line/column
|
||
* [`vfile-to-eslint`](https://github.com/vfile/vfile-to-eslint)
|
||
— Convert VFiles to ESLint formatter compatible output
|
||
|
||
## Reporters
|
||
|
||
The following list of projects show linting results for given virtual files.
|
||
Reporters _must_ accept `Array.<VFile>` as their first argument, and return
|
||
`string`. Reporters _may_ accept other values too, in which case it’s suggested
|
||
to stick to `vfile-reporter`s interface.
|
||
|
||
* [`vfile-reporter`][reporter]
|
||
— Stylish reporter
|
||
* [`vfile-reporter-json`](https://github.com/vfile/vfile-reporter-json)
|
||
— JSON reporter
|
||
* [`vfile-reporter-folder-json`](https://github.com/vfile/vfile-reporter-folder-json)
|
||
— JSON reporter with a folder structure
|
||
* [`vfile-reporter-pretty`](https://github.com/vfile/vfile-reporter-pretty)
|
||
— Pretty reporter
|
||
|
||
## API
|
||
|
||
### `VFile([options])`
|
||
|
||
Create a new virtual file. If `options` is `string` or `Buffer`, treats
|
||
it as `{contents: options}`. If `options` is a `VFile`, returns it.
|
||
All other options are set on the newly created `vfile`.
|
||
|
||
Path related properties are set in the following order (least specific
|
||
to most specific): `history`, `path`, `basename`, `stem`, `extname`,
|
||
`dirname`.
|
||
|
||
It’s not possible to set either `dirname` or `extname` without setting
|
||
either `history`, `path`, `basename`, or `stem` as well.
|
||
|
||
###### Example
|
||
|
||
```js
|
||
vfile()
|
||
vfile('console.log("alpha");')
|
||
vfile(Buffer.from('exit 1'))
|
||
vfile({path: path.join(__dirname, 'readme.md')})
|
||
vfile({stem: 'readme', extname: '.md', dirname: __dirname})
|
||
vfile({other: 'properties', are: 'copied', ov: {e: 'r'}})
|
||
```
|
||
|
||
### `vfile.contents`
|
||
|
||
`Buffer`, `string`, `null` — Raw value.
|
||
|
||
### `vfile.cwd`
|
||
|
||
`string` — Base of `path`. Defaults to `process.cwd()`.
|
||
|
||
### `vfile.path`
|
||
|
||
`string?` — Path of `vfile`. Cannot be nullified.
|
||
|
||
### `vfile.basename`
|
||
|
||
`string?` — Current name (including extension) of `vfile`. Cannot
|
||
contain path separators. Cannot be nullified either (use
|
||
`file.path = file.dirname` instead).
|
||
|
||
### `vfile.stem`
|
||
|
||
`string?` — Name (without extension) of `vfile`. Cannot be nullified,
|
||
and cannot contain path separators.
|
||
|
||
### `vfile.extname`
|
||
|
||
`string?` — Extension (with dot) of `vfile`. Cannot be set if
|
||
there’s no `path` yet and cannot contain path separators.
|
||
|
||
### `vfile.dirname`
|
||
|
||
`string?` — Path to parent directory of `vfile`. Cannot be set if
|
||
there’s no `path` yet.
|
||
|
||
### `vfile.history`
|
||
|
||
`Array.<string>` — List of file-paths the file moved between.
|
||
|
||
### `vfile.messages`
|
||
|
||
[`Array.<VMessage>`][message] — List of messages associated with the file.
|
||
|
||
### `vfile.data`
|
||
|
||
`Object` — Place to store custom information. It’s OK to store custom
|
||
data directly on the `vfile`, moving it to `data` gives a _little_ more
|
||
privacy.
|
||
|
||
### `VFile#toString([encoding])`
|
||
|
||
Convert contents of `vfile` to string. If `contents` is a buffer,
|
||
`encoding` is used to stringify buffers (default: `'utf8'`).
|
||
|
||
### `VFile#message(reason[, position][, origin])`
|
||
|
||
Associates a message with the file, where `fatal` is set to `false`.
|
||
Constructs a new [`VMessage`][vmessage] and adds it to
|
||
[`vfile.messages`][messages].
|
||
|
||
##### Returns
|
||
|
||
[`VMessage`][vmessage].
|
||
|
||
### `VFile#info(reason[, position][, origin])`
|
||
|
||
Associates an informational message with the file, where `fatal` is set to
|
||
`null`. Calls [`#message()`][message] internally.
|
||
|
||
##### Returns
|
||
|
||
[`VMessage`][vmessage].
|
||
|
||
### `VFile#fail(reason[, position][, origin])`
|
||
|
||
Associates a fatal message with the file, then immediately throws it.
|
||
Note: fatal errors mean a file is no longer processable.
|
||
Calls [`#message()`][message] internally.
|
||
|
||
##### Throws
|
||
|
||
[`VMessage`][vmessage].
|
||
|
||
## Contribute
|
||
|
||
**VFile** is built by people just like you! Check out
|
||
[`contributing.md`][contribute] for ways to get started.
|
||
|
||
This project has a [Code of Conduct][coc]. By interacting with this repository,
|
||
organisation, or community you agree to abide by its terms.
|
||
|
||
Want to chat with the community and contributors? Join us in [Gitter][chat]!
|
||
|
||
Have an idea for a cool new utility or tool? That’s great! If you want
|
||
feedback, help, or just to share it with the world you can do so by creating
|
||
an issue in the [`vfile/ideas`][ideas] repository!
|
||
|
||
## Acknowledgments
|
||
|
||
The initial release of this project was authored by
|
||
[**@wooorm**](https://github.com/wooorm).
|
||
|
||
Thanks to [**@contra**](https://github.com/contra),
|
||
[**@phated**](https://github.com/phated), and others for their work on
|
||
[Vinyl][], which was a huge inspiration.
|
||
|
||
Thanks to
|
||
[**@brendo**](https://github.com/brendo),
|
||
[**@shinnn**](https://github.com/shinnn),
|
||
[**@KyleAMathews**](https://github.com/KyleAMathews), [**@sindresorhus**](https://github.com/sindresorhus),
|
||
and [**@denysdovhan**](https://github.com/denysdovhan)
|
||
for contributing commits since!
|
||
|
||
## License
|
||
|
||
[MIT][license] © [Titus Wormer][author]
|
||
|
||
<!-- Definitions -->
|
||
|
||
[build-badge]: https://img.shields.io/travis/vfile/vfile/master.svg
|
||
|
||
[build]: https://travis-ci.org/vfile/vfile
|
||
|
||
[coverage-badge]: https://img.shields.io/codecov/c/github/vfile/vfile.svg
|
||
|
||
[coverage]: https://codecov.io/github/vfile/vfile
|
||
|
||
[downloads-badge]: https://img.shields.io/npm/dm/vfile.svg
|
||
|
||
[downloads]: https://www.npmjs.com/package/vfile
|
||
|
||
[size-badge]: https://img.shields.io/bundlephobia/minzip/vfile.svg
|
||
|
||
[size]: https://bundlephobia.com/result?p=vfile
|
||
|
||
[chat-badge]: https://img.shields.io/gitter/room/vfile/Lobby.svg
|
||
|
||
[chat]: https://gitter.im/vfile/Lobby
|
||
|
||
[npm]: https://docs.npmjs.com/cli/install
|
||
|
||
[license]: license
|
||
|
||
[author]: https://wooorm.com
|
||
|
||
[vfile]: https://raw.githubusercontent.com/vfile/vfile/7e1e6a6/logo.svg?sanitize=true
|
||
|
||
[unified]: https://github.com/unifiedjs/unified
|
||
|
||
[retext]: https://github.com/retextjs/retext
|
||
|
||
[remark]: https://github.com/remarkjs/remark
|
||
|
||
[rehype]: https://github.com/rehypejs/rehype
|
||
|
||
[vinyl]: https://github.com/gulpjs/vinyl
|
||
|
||
[unist]: https://github.com/syntax-tree/unist#list-of-utilities
|
||
|
||
[reporter]: https://github.com/vfile/vfile-reporter
|
||
|
||
[vmessage]: https://github.com/vfile/vfile-message
|
||
|
||
[messages]: #vfilemessages
|
||
|
||
[message]: #vfilemessagereason-position-origin
|
||
|
||
[contribute]: contributing.md
|
||
|
||
[coc]: code-of-conduct.md
|
||
|
||
[ideas]: https://github.com/vfile/ideas
|