Skip to content

Format Readers

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.

The initial release of DART 2.0 includes two format readers: a FileSystemReader and a TarReader. Developers can use these two examples as references for how to write a format reader.

API and Events

Format readers must extend the DART base Plugin and providing a description() method that returns meaningful PluginDescription information.

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 entry, error, and end (described below).

  • A list method that takes no parameters and emits events entry, error, and end (described below).

  • 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 error event passes a JavaScript error object to registered listeners and causes DART to stop reading.

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.

Note

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.

Tip

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: