Skip to content

ADR 13: Filesystem

Context

While accessing input files during runtime conversion, we are using Path objects to represent physical files in content directory. It seems practical to create some kind of virtualized tree of paths, which represents exact file structure of content directory. This kind of tree could allow us to track all the files which are going to be parsed, including their folders and may help us to simplify some of the patterns we are using during conversion.

Decision

We decided to create the FileSystem (lately referred to as fs) class which serves to virtualize and track whole content directory into the single tree. Besides mentioned FileSystem we have created following tree’s nodes:

  • Node to represent specific file.
  • DirNode to represent a directory path with its API.

Every tree begins with exactly one DirNode instance which represents root element - content dir.

We’ve also created ExternalPath classes. The motivation behind ExternalPath is the fact that in it4kt-builder there are situations, when we need to use/copy external files which are not parts of content directory, e.g. theme styles, scripts, etc.

There are 3 types of paths, which are used during conversion, namely content_dir, output_dir and relative path. We are getting first two from environment during runtime and they might change in order to reflect conversion phase (for example lecturer_mode flag). We decided to implement 3 main member variables into every node:

  • content_path - static variable assigned by current environment setup used mainly by Readers during reading phase.
  • output_path - dynamic variable which, when asked, is built using path and output_dir from environment. This variable is mainly used by Writers during write phase.
  • path - static variable initialized in constructor, which represents the “name” of the file used all across the app.

These three member variables allows us to care less about file locations and encourage us to think more about achieving our main goals during development.

We’ve decided to implement method find(path: Path) on our fs which is critical in order to access file system’s tree during runtime. Users are able to quickly search for a file node using any Path object. Method will try to match a node in tree and return the node if it is available.

In general, filesystem is small and easily extensible module, which helps us to quckly manage our content directory.

Status

Accepted.

Consequences

It is now possible to create virtualized file system tree that covers all files from content directory and enables accessing content files directly from environment variable. Virtualization process can be easily extended to manipulate, filter and/or edit tracked files.

File system is also able to work with external paths in order to track and manage them during conversion process. These files are separated from virtualized content directory tree but can be accessed using same way as our main tree.