VFile is a virtual file format used by retext (natural language) and mdast (markdown). Two processors which parse, transform, and compile text. Both need a virtual representation of files and a place to store warnings. And, they work in the browser. VFile provides these requirements.

Also, VFile exposes a warning mechanism compatible with ESLints formatters, making it easy to expose stylish warnings, or export tap compliant messages.

Installation

npm:

npm install vfile

VFile is also available for bower, component, and duo, and as an AMD, CommonJS, and globals module, uncompressed and compressed.

Table of Contents

• Usage

• API

  • VFile()
  • VFile#contents
  • VFile#directory
  • VFile#filename
  • VFile#extension
  • VFile#quiet
  • VFile#messages
  • VFile#toString()
  • VFile#filePath()
  • VFile#move(options)
  • VFile#message(reason, position?)
  • VFile#warn(reason, position?)
  • VFile#fail(reason, position?)
  • VFile#hasFailed()
  • VFileMessage

• License

Usage

var VFile = require('vfile');

var file = new VFile({
  'directory': '~',
  'filename': 'example',
  'extension': 'txt',
  'contents': 'Foo *bar* baz'
});

file.toString(); // 'Foo *bar* baz'
file.filePath(); // '~/example.txt'

file.move({'extension': 'md'});
file.filePath(); // '~/example.md'

file.warn('Something went wrong', {'line': 1, 'column': 3});
// { [~/example.md:1:3: Something went wrong]
//   name: '~/example.md:1:3',
//   file: '~/example.md',
//   reason: 'Something went wrong',
//   line: 1,
//   column: 3,
//   fatal: false }

API

VFile()

VFile objects make it easy to move files, to trigger warnings and errors, and to store supplementary metadata relating to files, all without accessing the file-system.

Example

var file = new VFile({
  'directory': '~',
  'filename': 'example',
  'extension': 'txt',
  'contents': 'Foo *bar* baz'
});

file === VFile(file); // true
file === new VFile(file); // true

VFile('foo') instanceof VFile; // true

Signatures

• file = VFile(contents|options|vFile?).

Parameters

• contents (string) — Contents of the file;

• vFile (VFile) — Existing representation, returned without modification;

• options (Object):

  • directory (string?, default: '') — Parent directory;

  • filename (string?, default: '') — Name, without extension;

  • extension (string?, default: '') — Extension(s), without initial dot;

  • contents (string?, default: '') — Raw value.

Returns

vFile — Instance.

Notes

VFile exposes an interface compatible with ESLint’s formatters. For example, to expose warnings using ESLint’s compact formatter, execute the following:

var compact = require('eslint/lib/formatters/compact');
var VFile = require('vfile');

var vFile = new VFile({
    'directory': '~',
    'filename': 'hello',
    'extension': 'txt'
});

vFile.warn('Whoops, something happened!');

console.log(compact([vFile]));

Which would yield the following:

~/hello.txt: line 0, col 0, Warning - Whoops, something happened!

1 problem

VFile#contents

string — Content of file.

VFile#directory

string — Path to parent directory.

VFile#filename

string — Filename. A file-path can still be generated when no filename exists.

VFile#extension

string — Extension. A file-path can still be generated when no extension exists.

VFile#quiet

boolean? — Whether an error created by VFile#fail() is returned (when truthy) or thrown (when falsey).

Ensure all messages associated with a file are handled properly when setting this to true.

VFile#messages

Array.<VFileMessage> — List of associated messages.

Notes

VFile#message(), and in turn VFile#warn() and VFile#fail(), return Error objects that adhere to the VFileMessage schema. Its results can populate messages.

VFile#toString()

Get the value of the file.

Example

var vFile = new VFile('Foo');
String(vFile); // 'Foo'

Signatures

• string = vFile.toString().

Returns

string — Contents.

VFile#filePath()

Get the filename, with extension and directory, if applicable.

Example

var file = new VFile({
  'directory': '~',
  'filename': 'example',
  'extension': 'txt'
});

String(file.filePath); // ~/example.txt
file.filePath() // ~/example.txt

Signatures

• string = vFile.filePath().

Returns

string — If the vFile has a filename, it will be prefixed with the directory (slashed), if applicable, and suffixed with the (dotted) extension (if applicable). Otherwise, an empty string is returned.

VFile#move(options)

Move a file by passing a new directory, filename, and extension. When these are not given, the default values are kept.

Example

var file = new VFile({
  'directory': '~',
  'filename': 'example',
  'extension': 'txt',
  'contents': 'Foo *bar* baz'
});

file.move({'directory': '/var/www'});
file.filePath(); // '/var/www/example.txt'

file.move({'extension': 'md'});
file.filePath(); // '/var/www/example.md'

Parameters

• options (Object):

  • directory (string, default: '') — Parent directory;

  • filename (string?, default: '') — Name, without extension;

  • extension (string, default: '') — Extension(s), without initial dot.

Signatures

• vFile = vFile.move(options?).

Returns

vFile — Context object (chainable).

VFile#message(reason, position?)

Create a message with reason at position. When an error is passed in as reason, copies the stack. This does not add a message to messages.

Example

var file = new VFile();

file.message('Something went wrong');
// { [1:1: Something went wrong]
//   name: '1:1',
//   file: '',
//   reason: 'Something went wrong',
//   line: null,
//   column: null }

Signatures

• VFileMessage = vFile.message(err|reason, node|location|position?).

Parameters

• err (Error) — Original error, whose stack and message are used;

• reason (string) — Reason for message;

• node (Node) — Syntax tree object;

• location (Object) — Syntax tree location (found at node.position);

• position (Object) — Syntax tree position (found at node.position.start or node.position.end).

Returns

VFileMessage — File-related message with location information.

VFile#warn(reason, position?)

Warn. Creates a non-fatal message (see VFile#message()), and adds it to the file's messages list.

Example

var file = new VFile();

file.warn('Something went wrong');
// { [1:1: Something went wrong]
//   name: '1:1',
//   file: '',
//   reason: 'Something went wrong',
//   line: null,
//   column: null,
//   fatal: false }

See

• VFile#message

VFile#fail(reason, position?)

Fail. Creates a fatal message (see VFile#message()), sets fatal: true, adds it to the file's messages list.

If quiet is not true, throws the error.

Example

var file = new VFile();

file.fail('Something went wrong');
// 1:1: Something went wrong
//     at VFile.exception (vfile/index.js:296:11)
//     at VFile.fail (vfile/index.js:360:20)
//     at repl:1:6

file.quiet = true;
file.fail('Something went wrong');
// { [1:1: Something went wrong]
//   name: '1:1',
//   file: '',
//   reason: 'Something went wrong',
//   line: null,
//   column: null,
//   fatal: true }

See

• VFile#message

VFile#hasFailed()

Check if a fatal message occurred making the file no longer processable.

Example

var file = new VFile();
file.quiet = true;

file.hasFailed(); // false

file.fail('Something went wrong');
file.hasFailed(); // true

Signatures

• boolean = vFile.hasFailed().

Returns

boolean — true if at least one of file’s messages has a fatal property set to true.

VFileMessage

Error — File-related message with location information.

Properties

• name (string) — (Starting) location of the message, preceded by its file-path when available, and joined by ':'. Used by the native Error#toString();

• file (string) — File-path;

• reason (string) — Reason for message;

• line (number?) — Line of error, when available;

• column (number?) — Column of error, when available;

• stack (string?) — Stack of message, when available;

• fatal (boolean?) — Whether the associated file is still processable.

License

MIT © Titus Wormer