VFile is a virtual file format used by unified, a text processing umbrella (it powers retext for natural language, remark for markdown, and 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 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
— The documentation system for modern JavaScriptawoo
— Declarative small site generatorgeojsonhint
— Complete, fast, standards-based validation for geojsonnpm:
npm install vfile
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:
[ { [~/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 } ]
The following list of projects includes tools for working with virtual files. See Unist for projects working with nodes.
convert-vinyl-to-vfile
— Convert from Vinylis-vfile-message
— Check if a value is a VMessage
objectto-vfile
— Create a virtual file from a file-path (and optionally read it)vfile-find-down
— Find files by searching the file system downwardsvfile-find-up
— Find files by searching the file system upwardsvfile-glob
— Find files by glob patternsvfile-location
— Convert between line/column- and range-based locationsvfile-message
— Create a VMessage
object (used in vfile
itself)vfile-statistics
— Count messages per categoryvfile-messages-to-vscode-diagnostics
— Convert to VS Code diagnosticsvfile-sort
— Sort messages by line/columnvfile-to-eslint
— Convert VFiles to ESLint formatter compatible outputThe 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
— Stylish reportervfile-reporter-json
— JSON reportervfile-reporter-folder-json
— JSON reporter with a folder structurevfile-reporter-pretty
— Pretty reporterVFile([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.
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>
— 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
and adds it to vfile.messages
.
VFile#info(reason[, position][, origin])
Associates an informational message with the file, where fatal
is set to null
. Calls #message()
internally.
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()
internally.
VFile is built by people just like you! Check out contributing.md
for ways to get started.
This project has a Code of Conduct. 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!
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
repository!
The initial release of this project was authored by @wooorm.
Thanks to @contra, @phated, and others for their work on Vinyl, which was a huge inspiration.
Thanks to @brendo, @shinnn, @KyleAMathews, @sindresorhus, and @denysdovhan for contributing commits since!