Format readers read file formats like tar, zip, OCFL, etc. Format readers provide methods for listing the contents of a directory or serialized file, and for reading individual files from the directory/file.
API and Events
Format readers must implement the following methods:
A constructor that takes a single parameter, which is the path to the file that the reader will read. (If the reader reads from a directory, such as an OCFL object, the path should point to a directory.)
A static definition method that takes no parameters and returns a description of the plugin (as described in The Base Plugin).
A read method that takes no parameters and emits events
A list method that takes no parameters and emits events
Property fileCount, a number that starts at zero and is incremented by one each time read or list emits an entry event for a file.
Property dirCount, a number that starts at zero and is incremented by one each time read or list emits an entry event for a directory.
Property byteCount, a number that starts at zero and is incremented by the number of bytes in a file each time read or list emits an entry event for a file.
The end event passes nothing to registered listeners and tells DART that the reader has finished with all entries.
The entry event passes an object containing the relative path of the current file entry, a lightweight FileStat object, and in the case a of the read method, an open Readable stream so DART can read the contents of the file.
DART uses its own simplified FileStat object instead of Node's built-in Stats object because format readers will often have to read from serialized formats that don't include all of the information you'd find in a Stats object. For example, tar and zip headers may exclude information about inode, blocksize, etc. The FileStat object simply captures the essentials that are common across most formats.
In cases where a FormatReader's read method cannot return a readable stream, it can return a DummyReader. This is necessary in cases where the reader encounters a directory entry that cannot be read like a regular file. DART will still try to read from the readable stream in the entry event, and a DummyReader will allow DART to read without error. For an example of how to do this, look for DummyReader in the read method of the FileSystemReader source code.
Format Reader Examples
The best way to understand how to write a FormatReader plugin is to review the API documentation, source code, and tests for the following: