File

This class represents a file or directory in the file system. The file may or may not exist (try using exists to find out!). At it's core, each File is a path, and a collection of methods that operate on that path. In addition, each instance of a File is also a function that can be called; when called, it will return a new instance of a File with argument appended to the path of the original File. In other words:

var File = require('oofile').File
var docs = new File('~/Documents');
var work = docs('Work');   // '/Work' is valid as well - File will normalize the path

Files included in this array will be excluded from file listings (i.e. findAllFiles)

constructor

Create a new instance of a File it's already a File, so just return the File constructor returns an object that acts as a function and object simultaneously (technically, all functions are already Function objects, but you get the point). To do this, we create a function in the constructor, and return that function. But before we return it, we make it inherit from the File "class" via prototype inheritance this is the default function - if you invoke an instance of File as a function, you're calling this assign that function the prototype - now, it walks, talks and acts like a File, but can be invoked as method (on itself!) do some setup work

_init

This is a private method - do not invoke this yourself!

findAllFiles

Returns an array of files found within this directory and all sub-directories (recursively). If this instance's path is not a directory, it returns an array containing a single entry, itself.

findAllChildren

Returns an array of files or directories found within this directory and all sub-directories (recursively).If this instance's path is not a directory, it returns an empty array.

find

Returns an array of files found within this directory and all sub-directories (recursively) that match the given pattern (itself included). The pattern can either be a regular expression (must be an instance of RegExp) or a globbing pattern.

eachFile

Maps the supplied function over the result of this.findAllFiles() get all the files when you finish with a file ... invoke map on the next one kickoff

toString

If a File is asked to represent itself as a String via the toString method, it simply returns the absolute path it represents.

exists

Does the file or directory exist?

withExt

Returns a new instance of File with the current path and the given extension. If the current File has an extension, it will be replaced. If it has no extension, the supplied one will be appended.

isFile

Returns true if the current path is an actual file on the file system. If the path resolves to a directory, or doesn't exist, returns false.

isDir

Returns true if the current path is an actual directory on the file system. If the path resolves to a file, or doesn't exist, returns false.

rename

Renames the actual file in the file system. The optional second argument will change the extension as well; if none is supplied, the extension won't change. ext isnt "" then ext = ".#{ext}"

contents

Reads the contents of the file. If the file doesn't exist, or is a directory, returns false. To return a buffer, rather than the content itself, pass in { buffer: true } in the options hash. If buffer is false or not set, then the contents will be parsed as JSON. If the contents are not valid JSON, the function returns the contents as a raw string.

contains

Returns true if the supplied filename exists in this directory or and sub-directory (recursively). Returns false if the current path is a file.

insertBefore

Inserts the supplied content before the first occurence of the given marker, and writes the result to the file.

insertBefore

Inserts the supplied content after the first occurence of the given marker, and writes the result to the file.

write

Writes the supplied contents to the current path. If the parent directories of the current path do not exist, they will be created (mkdir -p style). If a string or buffer is provided as the contents, it will be written directly. If an object is provided, it will be stringified with JSON.stringify and the result will be written.

parent

Returns a new File instance representing the parent directory of the current path.

_mkdirs

Private method for generating containing directories recursively.

relativeTo

Returns a string representing the relative path to go from the current path to the supplied file.

isWithin

Checks to see if the current path is a child of the supplied path. The supplied path can be a string or an instance of File

withoutExt

Returns a new File instance representing the current path, minus any extension. If the current path contains multiple extensions (i.e. application.layout.html) the only the final extension will be removed.

ls

Mimics the command line ls - returns an array of files in the current directory (not including sub-directories). If the current path is a file or doesn't exist, returns false.

rm

Deletes this file or directory from the file system. If the current path is a directory, it's contents will be deleted recursively.

copyTo

Copies this file or directory to the given destination. The destination can be a string path or another File instance. If the current path is a directory, its contents will be recursively copied to the destination.

copyFrom

Copies from the given path (a string or instance of File) to the current path, recursively.

edit

edit accepts a worker function as an argument. It reads in the contents of the current path, calls the worker function with the contents of the file, and then writes the return value of that function back to the file.