x-file
v0.2.0
Published
Constructor for virtual file objects
Downloads
19
Readme
x-file
This is a constructor for virtual file objects. It's intended for use in incremental build systems, where files in a destination directory get granularly created/edited/deleted depending on decisions made in the build process. An x-file instance is essentially a record of what that decision is for a single build action on one file.
Instantiate it with a path and some contents:
var File = require('x-file');
var file = new File('some/imaginary/file.txt', 'hello');
The .path
property can be a string or null.
A file's .contents
property must be one of three types:
- a
Buffer
– simply, the contents you intend to be written to disk (at the end of the build process) false
– to be interpreted as an instruction to delete this file from whatever destination directorynull
– contents not decided yet, or an explicit instruction not to write/delete anything at the given path.
It constructs an object with .path
and .contents
properties. But it also has a dynamic .text
property for the common case of modifying the contents as a UTF-8 string over and over.
The .text
and .contents
properties automatically stay in sync, and they do this lazily in order to reduce work. If you make several changes to the .text
during a build process, the .contents
will only be updated when you next attempt to read it.
It also has an .ext
property that you can read and write, and .path
will automatically reflect it.
usage
var File = require('x-file');
var file = new File('some/imaginary/file.txt', 'hello');
file.contents.toString(); // "hello"
file.ext; // ".txt";
file.text += ' world';
file.contents.toString(); // "hello world"
file.contents = new Buffer('bye');
file.text; // "bye"
file.length; // 3
file.ext = '.foo';
file.path; // "some/imaginary/file.foo"
Note that calling .write()
or .fill()
to edit the buffer in place will not be reflected in .text
, because it won't trigger the .contents
setter. If you need to work around this, you can set file.contents = file.contents
after editing the buffer in place, to trigger the setter.
properties
.contents
- may be a Buffer,false
ornull
. Recommended interpretation of values:- a buffer means that when this file is 'output' somehow (e.g. saved to disk), this buffer is what should be written.
false
means that this file object is really a 'to be deleted' instruction; i.e. if the final stage of this build system requiresnull
- the recommended interpretation is that
null
means contents are undecided, or that they should not be changed (compared to some previous build).
.text
– the parallel to.contents
. May be a string,false
ornull
. This property is automatically kept in sync with.contents
.
licence
MIT