JarCasting
vfile is a virtual file format part of the unified collective.
Intro
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.
- Visit
unifiedjs.comand see its learn section for an overview - Read unified’s readme for a technical intro
- Follow us on Medium and Twitter to see what we’re up to
- Check out Contribute below to find out how to help out
vfile is different from the excellent
vinylin 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 geojson
Sponsors
Support this effort and give back by sponsoring on OpenCollective!
Gatsby  |
Vercel  |
Netlify |
Holloway |
ThemeIsle |
Boost Hub |
Expo |
|||
| You? |
|||||||||
Install
npm:
npm install vfile
Contents
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. 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.
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
Utilities
The following list of projects includes tools for working with virtual files. See unist for projects working 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.
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!
