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.
npm:
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.
dustinspecker/convert-vinyl-to-vfile
— Convert from Vinyl;shinnn/is-vfile-message
— Check if a value is aVFileMessage
object;vfile/to-vfile
— Create a virtual file from a file-path (and optionally read it);vfile/vfile-find-down
— Find files by searching the file system downwards;vfile/vfile-find-up
— Find files by searching the file system upwards;vfile/vfile-location
— Convert between line/column- and range-based locations;vfile/vfile-statistics
— Count messages per category;shinnn/vfile-messages-to-vscode-diagnostics
— Convert to VS Code diagnostics;vfile/vfile-sort
— Sort messages by line/column;sindresorhus/vfile-to-eslint
— Convert VFiles to ESLint formatter compatible output.
vfile/vfile-reporter
— Stylish reporter;vfile/vfile-reporter-json
— JSON reporter;sindresorhus/vfile-reporter-pretty
— Pretty reporter.
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 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'}});
Buffer
, string
, null
— Raw value.
string
— Base of path
. Defaults to process.cwd()
.
string?
— Path of vfile
. Cannot be nullified.
string?
— Current name (including extension) of vfile
. Cannot
contain path separators. Cannot be nullified either (use
file.path = file.dirname
instead).
string?
— Name (without extension) of vfile
. Cannot be nullified,
and cannot contain path separators.
string?
— Extension (with dot) of vfile
. Cannot be set if
there’s no path
yet and cannot contain path separators.
string?
— Path to parent directory of vfile
. Cannot be set if
there’s no path
yet.
Array.<string>
— List of file-paths the file moved between.
Array.<VFileMessage>
— List of messages associated with the file.
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.
Convert contents of vfile
to string. If contents
is a buffer,
encoding
is used to stringify buffers (default: 'utf8'
).
Associates a message with the file for reason
at position
. When an
error is passed in as reason
, copies the stack.
reason
(string
orError
) — Reason for message, uses the stack and message of the error if given;position
(Node
,Location
, orPosition
, optional) — Place at which the message occurred invfile
.ruleId
(string
, optional) — Category of warning.
Associates a fatal message with the file, then immediately throws it.
Note: fatal errors mean a file is no longer processable.
Calls #message()
internally.
File-related message describing something at certain position (extends
Error
).
file
(string
) — File-path (when the message was triggered);reason
(string
) — Reason for message;ruleId
(string?
) — Category of message;source
(string?
) — Namespace of warning;stack
(string?
) — Stack of message;fatal
(boolean?
) — Iftrue
, marks associated file as no longer processable;line
(number?
) — Starting line of error;column
(number?
) — Starting column of error;location
(object
) — Full range information, when available. Hasstart
andend
properties, both set to an object withline
andcolumn
, set tonumber?
.