diff options
author | Michaël Zasso <targos@protonmail.com> | 2017-12-22 16:53:42 +0100 |
---|---|---|
committer | Michaël Zasso <targos@protonmail.com> | 2018-01-11 09:48:05 +0100 |
commit | 3dc30632755713179f345f4af024bd904c6162d0 (patch) | |
tree | f28c4f6dd6dfc5992edf301449d1a371d229755b /tools/node_modules/eslint/node_modules/vfile/readme.md | |
parent | a2c7085dd4a8e60d1a47572aca8bb6fcb7a32f88 (diff) | |
download | android-node-v8-3dc30632755713179f345f4af024bd904c6162d0.tar.gz android-node-v8-3dc30632755713179f345f4af024bd904c6162d0.tar.bz2 android-node-v8-3dc30632755713179f345f4af024bd904c6162d0.zip |
tools: move eslint from tools to tools/node_modules
This is required because we need to add the babel-eslint dependency
and it has to be able to resolve "eslint".
babel-eslint is required to support future ES features such as async
iterators and import.meta.
Refs: https://github.com/nodejs/node/pull/17755
PR-URL: https://github.com/nodejs/node/pull/17820
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Diffstat (limited to 'tools/node_modules/eslint/node_modules/vfile/readme.md')
-rw-r--r-- | tools/node_modules/eslint/node_modules/vfile/readme.md | 285 |
1 files changed, 285 insertions, 0 deletions
diff --git a/tools/node_modules/eslint/node_modules/vfile/readme.md b/tools/node_modules/eslint/node_modules/vfile/readme.md new file mode 100644 index 0000000000..1488031d7e --- /dev/null +++ b/tools/node_modules/eslint/node_modules/vfile/readme.md @@ -0,0 +1,285 @@ +# ![vfile][] + +[![Build Status][build-badge]][build-status] +[![Coverage Status][coverage-badge]][coverage-status] + +**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 +* [`weh`](https://github.com/wehjs/weh) + — 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) +* [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-location`](https://github.com/vfile/vfile-location) + — Convert between line/column- and range-based locations +* [`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-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]. + +## License + +[MIT][license] © [Titus Wormer][author] + +<!-- Definitions --> + +[build-badge]: https://img.shields.io/travis/vfile/vfile.svg + +[build-status]: https://travis-ci.org/vfile/vfile + +[coverage-badge]: https://img.shields.io/codecov/c/github/vfile/vfile.svg + +[coverage-status]: https://codecov.io/github/vfile/vfile + +[npm]: https://docs.npmjs.com/cli/install + +[license]: LICENSE + +[author]: http://wooorm.com + +[vfile]: https://cdn.rawgit.com/vfile/vfile/f65510e/logo.svg + +[unified]: https://github.com/unifiedjs/unified + +[retext]: https://github.com/wooorm/retext + +[remark]: https://github.com/wooorm/remark + +[rehype]: https://github.com/wooorm/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 |