@ifabs/vile
v4.1.2
Published
Fork of vfile
Downloads
2
Maintainers
Readme
vile is my fork of the vfile project, which is part of the unified collective.
Why the fork!?
Well, I got kinda peeved with the typings not being accurate anymore, so I said "fork it" it, I'll fix it myself and publish it on npm or something. Everything is the same except for one of the following changes, which will occur in types/index.d.ts:
Note: The interface is simplified for brevity in these examples. The only change so far is the result
field.
Option One
This is the simplist solution, but with the least benefit as well.
interface VFile {
<F extends VFile>(input?: VFileContents | F | VFileOptions): F
/**
* List of file-paths the file moved between.
*/
history: string[]
/**
* 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.
*/
data: unknown
/**
* Result from either `.process` or `.processSync`, can be anything
*/
result: any
}
Option Two
Option two is slightly more robust, but still poses limitations on plugin authors.
interface VFile<T> {
<F extends VFile>(input?: VFileContents | F | VFileOptions): F
/**
* List of file-paths the file moved between.
*/
history: string[]
/**
* 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.
*/
data: unknown
/**
* Result from either `.process` or `.processSync`, can be anything
*/
result: T
}
Option Three
This is the most robust solution, but also the most verbose.
interface VFile {
<F extends VFile>(input?: VFileContents | F | VFileOptions): F
/**
* List of file-paths the file moved between.
*/
history: string[]
/**
* 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.
*/
data: unknown
}
interface CustomVFile<T> extends VFile{
/**
* Result from either `.process` or `.processSync`, can be anything
*/
result: T
}
These options are not final, and are subject to change.
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.com
and 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
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 geojson
Sponsors
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-reporter
s 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!