.config/coc/extensions/node_modules/coc-prettier/node_modules/vfile/readme.md

   1 # ![vfile][]
   2
   3 [![Build Status][build-badge]][build-status]
   4 [![Coverage Status][coverage-badge]][coverage-status]
   5
   6 **VFile** is a virtual file format used by [**unified**][unified],
   7 a text processing umbrella (it powers [**retext**][retext] for
   8 natural language, [**remark**][remark] for markdown, and
   9 [**rehype**][rehype] for HTML).  Each processors that parse, transform,
  10 and compile text, and need a virtual representation of files and a
  11 place to store [messages][] about them.  Plus, they work in the browser.
  12 **VFile** provides these requirements at a small size, in IE 9 and up.
  13
  14 > **VFile** is different from the excellent [**vinyl**][vinyl]
  15 > in that it has a smaller API, a smaller size, and focuses on
  16 > [messages][].
  17
  18 VFile can be used anywhere where files need a lightweight representation.
  19 For example, it’s used in:
  20
  21 *   [`documentation`](https://github.com/documentationjs/documentation)
  22     — The documentation system for modern JavaScript
  23 *   [`weh`](https://github.com/wehjs/weh)
  24     — Declarative small site generator
  25 *   [`geojsonhint`](https://github.com/mapbox/geojsonhint)
  26     — Complete, fast, standards-based validation for geojson
  27
  28 ## Installation
  29
  30 [npm][]:
  31
  32 ```bash
  33 npm install vfile
  34 ```
  35
  36 ## Table of Contents
  37
  38 *   [Usage](#usage)
  39 *   [Utilities](#utilities)
  40 *   [Reporters](#reporters)
  41 *   [API](#api)
  42     *   [VFile(\[options\])](#vfileoptions)
  43     *   [vfile.contents](#vfilecontents)
  44     *   [vfile.cwd](#vfilecwd)
  45     *   [vfile.path](#vfilepath)
  46     *   [vfile.basename](#vfilebasename)
  47     *   [vfile.stem](#vfilestem)
  48     *   [vfile.extname](#vfileextname)
  49     *   [vfile.dirname](#vfiledirname)
  50     *   [vfile.history](#vfilehistory)
  51     *   [vfile.messages](#vfilemessages)
  52     *   [vfile.data](#vfiledata)
  53     *   [VFile#toString(\[encoding\])](#vfiletostringencoding)
  54     *   [VFile#message(reason\[, position\]\[, origin\])](#vfilemessagereason-position-origin)
  55     *   [VFile#info(reason\[, position\]\[, origin\])](#vfileinforeason-position-origin)
  56     *   [VFile#fail(reason\[, position\]\[, origin\])](#vfilefailreason-position-origin)
  57 *   [License](#license)
  58
  59 ## Usage
  60
  61 ```js
  62 var vfile = require('vfile');
  63
  64 var file = vfile({path: '~/example.txt', contents: 'Alpha *braavo* charlie.'});
  65
  66 file.path; //=> '~/example.txt'
  67 file.dirname; //=> '~'
  68
  69 file.extname = '.md';
  70
  71 file.basename; //=> 'example.md'
  72
  73 file.basename = 'index.text';
  74
  75 file.history; //=> ['~/example.txt', '~/example.md', '~/index.text']
  76
  77 file.message('`braavo` is misspelt; did you mean `bravo`?', {line: 1, column: 8});
  78
  79 console.log(file.messages);
  80 ```
  81
  82 Yields:
  83
  84 ```js
  85 [ { [~/index.text:1:8: `braavo` is misspelt; did you mean `bravo`?]
  86     message: '`braavo` is misspelt; did you mean `bravo`?',
  87     name: '~/index.text:1:8',
  88     file: '~/index.text',
  89     reason: '`braavo` is misspelt; did you mean `bravo`?',
  90     line: 1,
  91     column: 8,
  92     location: { start: [Object], end: [Object] },
  93     ruleId: null,
  94     source: null,
  95     fatal: false } ]
  96 ```
  97
  98 ## Utilities
  99
 100 The following list of projects includes tools for working with virtual
 101 files.  See [**Unist**][unist] for projects working with nodes.
 102
 103 *   [`convert-vinyl-to-vfile`](https://github.com/dustinspecker/convert-vinyl-to-vfile)
 104     — Convert from [Vinyl][]
 105 *   [`is-vfile-message`](https://github.com/shinnn/is-vfile-message)
 106     — Check if a value is a `VMessage` object
 107 *   [`to-vfile`](https://github.com/vfile/to-vfile)
 108     — Create a virtual file from a file-path (and optionally read it)
 109 *   [`vfile-find-down`](https://github.com/vfile/vfile-find-down)
 110     — Find files by searching the file system downwards
 111 *   [`vfile-find-up`](https://github.com/vfile/vfile-find-up)
 112     — Find files by searching the file system upwards
 113 *   [`vfile-location`](https://github.com/vfile/vfile-location)
 114     — Convert between line/column- and range-based locations
 115 *   [`vfile-statistics`](https://github.com/vfile/vfile-statistics)
 116     — Count messages per category
 117 *   [`vfile-messages-to-vscode-diagnostics`](https://github.com/shinnn/vfile-messages-to-vscode-diagnostics)
 118     — Convert to VS Code diagnostics
 119 *   [`vfile-sort`](https://github.com/vfile/vfile-sort)
 120     — Sort messages by line/column
 121 *   [`vfile-to-eslint`](https://github.com/vfile/vfile-to-eslint)
 122     — Convert VFiles to ESLint formatter compatible output
 123
 124 ## Reporters
 125
 126 The following list of projects show linting results for given virtual files.
 127 Reporters _must_ accept `Array.<VFile>` as their first argument, and return
 128 `string`.  Reporters _may_ accept other values too, in which case it’s suggested
 129 to stick to `vfile-reporter`s interface.
 130
 131 *   [`vfile-reporter`][reporter]
 132     — Stylish reporter
 133 *   [`vfile-reporter-json`](https://github.com/vfile/vfile-reporter-json)
 134     — JSON reporter
 135 *   [`vfile-reporter-pretty`](https://github.com/vfile/vfile-reporter-pretty)
 136     — Pretty reporter
 137
 138 ## API
 139
 140 ### `VFile([options])`
 141
 142 Create a new virtual file.  If `options` is `string` or `Buffer`, treats
 143 it as `{contents: options}`.  If `options` is a `VFile`, returns it.
 144 All other options are set on the newly created `vfile`.
 145
 146 Path related properties are set in the following order (least specific
 147 to most specific): `history`, `path`, `basename`, `stem`, `extname`,
 148 `dirname`.
 149
 150 It’s not possible to set either `dirname` or `extname` without setting
 151 either `history`, `path`, `basename`, or `stem` as well.
 152
 153 ###### Example
 154
 155 ```js
 156 vfile();
 157 vfile('console.log("alpha");');
 158 vfile(Buffer.from('exit 1'));
 159 vfile({path: path.join(__dirname, 'readme.md')});
 160 vfile({stem: 'readme', extname: '.md', dirname: __dirname});
 161 vfile({other: 'properties', are: 'copied', ov: {e: 'r'}});
 162 ```
 163
 164 ### `vfile.contents`
 165
 166 `Buffer`, `string`, `null` — Raw value.
 167
 168 ### `vfile.cwd`
 169
 170 `string` — Base of `path`.  Defaults to `process.cwd()`.
 171
 172 ### `vfile.path`
 173
 174 `string?` — Path of `vfile`.  Cannot be nullified.
 175
 176 ### `vfile.basename`
 177
 178 `string?` — Current name (including extension) of `vfile`.  Cannot
 179 contain path separators.  Cannot be nullified either (use
 180 `file.path = file.dirname` instead).
 181
 182 ### `vfile.stem`
 183
 184 `string?` — Name (without extension) of `vfile`.  Cannot be nullified,
 185 and cannot contain path separators.
 186
 187 ### `vfile.extname`
 188
 189 `string?` — Extension (with dot) of `vfile`.  Cannot be set if
 190 there’s no `path` yet and cannot contain path separators.
 191
 192 ### `vfile.dirname`
 193
 194 `string?` — Path to parent directory of `vfile`.  Cannot be set if
 195 there’s no `path` yet.
 196
 197 ### `vfile.history`
 198
 199 `Array.<string>` — List of file-paths the file moved between.
 200
 201 ### `vfile.messages`
 202
 203 [`Array.<VMessage>`][message] — List of messages associated with the file.
 204
 205 ### `vfile.data`
 206
 207 `Object` — Place to store custom information.  It’s OK to store custom
 208 data directly on the `vfile`, moving it to `data` gives a _little_ more
 209 privacy.
 210
 211 ### `VFile#toString([encoding])`
 212
 213 Convert contents of `vfile` to string.  If `contents` is a buffer,
 214 `encoding` is used to stringify buffers (default: `'utf8'`).
 215
 216 ### `VFile#message(reason[, position][, origin])`
 217
 218 Associates a message with the file, where `fatal` is set to `false`.
 219 Constructs a new [`VMessage`][vmessage] and adds it to
 220 [`vfile.messages`][messages].
 221
 222 ##### Returns
 223
 224 [`VMessage`][vmessage].
 225
 226 ### `VFile#info(reason[, position][, origin])`
 227
 228 Associates an informational message with the file, where `fatal` is set to
 229 `null`.  Calls [`#message()`][message] internally.
 230
 231 ##### Returns
 232
 233 [`VMessage`][vmessage].
 234
 235 ### `VFile#fail(reason[, position][, origin])`
 236
 237 Associates a fatal message with the file, then immediately throws it.
 238 Note: fatal errors mean a file is no longer processable.
 239 Calls [`#message()`][message] internally.
 240
 241 ##### Throws
 242
 243 [`VMessage`][vmessage].
 244
 245 ## License
 246
 247 [MIT][license] © [Titus Wormer][author]
 248
 249 <!-- Definitions -->
 250
 251 [build-badge]: https://img.shields.io/travis/vfile/vfile.svg
 252
 253 [build-status]: https://travis-ci.org/vfile/vfile
 254
 255 [coverage-badge]: https://img.shields.io/codecov/c/github/vfile/vfile.svg
 256
 257 [coverage-status]: https://codecov.io/github/vfile/vfile
 258
 259 [npm]: https://docs.npmjs.com/cli/install
 260
 261 [license]: LICENSE
 262
 263 [author]: http://wooorm.com
 264
 265 [vfile]: https://cdn.rawgit.com/vfile/vfile/f65510e/logo.svg
 266
 267 [unified]: https://github.com/unifiedjs/unified
 268
 269 [retext]: https://github.com/wooorm/retext
 270
 271 [remark]: https://github.com/wooorm/remark
 272
 273 [rehype]: https://github.com/wooorm/rehype
 274
 275 [vinyl]: https://github.com/gulpjs/vinyl
 276
 277 [unist]: https://github.com/syntax-tree/unist#list-of-utilities
 278
 279 [reporter]: https://github.com/vfile/vfile-reporter
 280
 281 [vmessage]: https://github.com/vfile/vfile-message
 282
 283 [messages]: #vfilemessages
 284
 285 [message]: #vfilemessagereason-position-origin