JarCasting
vfile is a small and browser friendly virtual file format that tracks metadata (such as a file’s path and contents) and messages.
It was made specifically for unified and generally for the common task of parsing, transforming, and serializing data, where vfile handles everything about the document being compiled. This is useful for example when building linters, compilers, static site generators, or other build tools. vfile is part of the unified collective.
- for updates, see Twitter
- for more about us, see
unifiedjs.com - for questions, see Discussions
- to help, see contribute or sponsor below
vfile is different from the excellent
vinylin that it has a smaller API, a smaller size, and focuses on messages.
Contents
Install
npm:
npm install vfile
Use
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 } ]
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
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. When contents is a Buffer, encoding is a character encoding to understand doc as (string, 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.
Returns
VFile#info(reason[, position][, origin])
Associates an informational message with the file, where fatal is set to null. Calls #message() internally.
Returns
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.
Throws
List of utilities
The following list of projects includes tools for working with virtual files. See unist for projects that work with nodes.
convert-vinyl-to-vfile— transform from Vinyl to vfileto-vfile— create a vfile from a filepathvfile-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-is— check if a vfile passes a testvfile-location— convert between positional and offset locationsvfile-matter— parse the YAML front mattervfile-message— create a vfile messagevfile-messages-to-vscode-diagnostics— transform vfile messages to VS Code diagnosticsvfile-mkdirp— make sure the directory of a vfile exists on the file systemvfile-rename— rename the path parts of a vfilevfile-sort— sort messages by line/columnvfile-statistics— count messages per category: failures, warnings, etcvfile-to-eslint— convert 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-reporters interface.
vfile-reporter— create a reportvfile-reporter-json— create a JSON reportvfile-reporter-folder-json— create a JSON representation of vfilesvfile-reporter-pretty— create a pretty reportvfile-reporter-junit— create a jUnit reportvfile-reporter-position— create a report with content excerpts
Contribute
See contributing.md in vfile/.github for ways to get started. See support.md for ways to get help. Ideas for new utilities and tools can be posted in vfile/ideas.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.
Sponsor
Support this effort and give back by sponsoring on OpenCollective!
Gatsby  |
Vercel  |
Netlify |
Holloway |
ThemeIsle |
Boost Hub |
Expo |
|||
| You? |
|||||||||
Acknowledgments
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!
