# Adding a new VFS type

Multiple steps are involved in adding a new dfVFS type:

1. Adding a type indicator
2. Adding a path specification
3. Adding a virtual file system and file entry implementation
4. Adding a file IO implementation
5. Adding a path specification resolver helper
6. Adding a format analyzer helper

## Adding a type indicator

The type indicators are stored in:

```
dfvfs/lib/definitions.py
```

Add a new type indicator:

```
TYPE_INDICATOR_MY = 'MY'
```

## Adding a path specification

The path specifications are stored in:

```
dfvfs/path/
```

Create a new path specification:

```
dfvfs/path/my_path_specification.py
```

Implement a path specification class based on the PathSpec interface class:

```
from dfvfs.lib import definitions
from dfvfs.path import factory
from dfvfs.path import path_spec

class MyPathSpec(path_spec.PathSpec):
  """Class that implements the my path specification."""

  TYPE_INDICATOR = definitions.TYPE_INDICATOR_MY
  ...
```

A path specification class largely consists of:

* an object initialization method (``` __init__ ```) that sets the class attributes;
* a ``` comparable ``` property that returns a comparable string form of the path specification.

The comparable string form normally consist of multiple (newline terminated)
lines in the form:

```
type: TYPE_INDICATOR, ADDRESSING_ATTRIBUTES
```

where every line represent an individual path specification.

Make sure the path specification will register with the factory on import.

```
factory.Factory.RegisterPathSpec(MyPathSpec)
```

To have the path specification loaded when dfvfs is used, make sure to include
in:

```
dfvfs/path/__init__.py
```

```
from dfvfs.path import my_path_specification
```

## Adding a virtual file system and file entry implementation

The virtual file systems and file entries are stored in:

```
dfvfs/vfs/
```

The file system and file entry are co-dependent.

### Adding a virtual file system implementation

Create a new file system and file entry:

```
dfvfs/path/my_file_system.py
```

Implement a file system class based on the FileSystem interface class:

```
from dfvfs.lib import definitions
from dfvfs.path import my_path_spec
from dfvfs.vfs import file_system
from dfvfs.vfs import my_file_entry

class MyFileSystem(file_system.FileSystem):
  """Class that implements my file system object."""

  TYPE_INDICATOR = definitions.TYPE_INDICATOR_MY
  ...
```

A file system class largely consists of:

* A class constant to define the path (segment) separator used by the file system (``` PATH_SEPARATOR ```);
* A method to determine if a file entry for a specific path specification exists (``` FileEntryExistsByPathSpec ```);
* A method to retrieve if a file entry for a specific path specification (``` GetFileEntryByPathSpec ```);
* A method to retrieve the root file entry (``` GetRootFileEntry ```).

### Adding a virtual file entry implementation

Create a new file system and file entry:

```
dfvfs/path/my_file_entry.py
```

Implement a file entry class based on the FileEntry interface class and a
directory class based on the Directory interface class:

```
from dfvfs.lib import definitions
from dfvfs.file_io import fake_file_io
from dfvfs.path import fake_path_spec
from dfvfs.vfs import file_entry

class MyDirectory(file_entry.Directory):
  """Class that implements my directory object."""
  ...

class MyFileEntry(file_entry.FileEntry):
  """Class that implements my file entry object."""

  TYPE_INDICATOR = definitions.TYPE_INDICATOR_MY
  ...
```

A directory class largely consists of:

* A protected method to generate path specification of directory entries for a specific directory path specification (``` _EntriesGenerator ```).

A file entry class largely consists of:

* (``` _GetDirectory ```);
* (``` _GetStat ```);
* a ``` name ``` property that ...
* a ``` sub_file_entries ``` property that ...
* (``` GetFileObject ```);
* (``` GetParentFileEntry ```).

**TODO describe a bit more what should be in the class.**

## Adding a file IO implementation

The file IO (or file-like) objects are stored in:

```
dfvfs/file_io/
```

Create a new file IO object:

```
dfvfs/file_io/my_file_io.py
```

Implement a path specification class based on the FileIO interface class:

```
class MyFile(file_io.FileIO):
  """Class that implements my file-like object."""

  TYPE_INDICATOR = definitions.TYPE_INDICATOR_MY
  ...
```

A file IO class largely consists of:

* (``` open ```);
* (``` close ```);
* (``` read ```);
* (``` seek ```);
* (``` get_offset ```);
* (``` get_size ```);

**TODO describe a bit more what should be in the class.**

dfVFS does not implement ``` write ``` or any of the ``` readline ``` functions
in its file-like object. Also ``` tell ``` is implemented in the FileIO
interface as an alias of ``` get_offset ```.

## Adding a path specification resolver helper

The path specification resolver helpers are stored in:

```
dfvfs/resolver/
```

Create a new resolver helper:

```
dfvfs/resolver/my_resolver_helper.py
```

Implement a resolver helper class based on the ResolverHelper interface class:

```
from dfvfs.lib import definitions
from dfvfs.resolver import resolver_helper

class MyResolverHelper(resolver_helper.ResolverHelper):
  """Class that implements my resolver helper."""

  TYPE_INDICATOR = definitions.TYPE_INDICATOR_MY
  ...
```

A resolver helper class largely consists of:

* (``` NewFileObject ```);
* (``` NewFileSystem ```).

**TODO describe a bit more what should be in the class.**

Make sure the resolver helper will register with the resolver on import.

```
resolver.Resolver.RegisterHelper(MyResolverHelper())
```

To have the resolver helper loaded when the resolver is used, make sure to include in:

```
dfvfs/resolver/__init__.py
```

```
from dfvfs.resolver import my_resolver_helper
```

## Adding a format analyzer helper

The format analyzer helpers are stored in:

```
dfvfs/analyzer/
```

Create a new analyzer helper:

```
dfvfs/analyzer/my_analyzer_helper.py
```

Implement an analyzer helper class based on the AnalyzerHelper interface class:

```
from dfvfs.analyzer import analyzer_helper
from dfvfs.lib import definitions

class MyAnalyzerHelper(resolver_helper.AnalyzerHelper):
  """Class that implements my analyzer helper."""

  TYPE_INDICATOR = definitions.TYPE_INDICATOR_MY
  ...
```

An analyzer helper class largely consists of:

* A FORMAT_CATEGORIES definition;
* (``` GetFormatSpecification ```)

**TODO describe a bit more what should be in the class.**

Make sure the analyzer helper will register with the analyzer on import.

```
analyzer.Analyzer.RegisterHelper(MyAnalyzerHelper())
```

To have the analyzer helper loaded when the analyzer is used, make sure to include in:

```
dfvfs/analyzer/__init__.py
```

```
from dfvfs.analyzer import my_analyzer_helper
```