Acorn DFS .ssd File Manager

Extract contents of a disc image elite.ssd into a directory name elite and detokenize any BBC BASIC programs::

dfstool extract elite.ssd elite

Make a disc image named elite-new.ssd from the manifest file elite/elite.json and referenced files:

dfstool make elite/elite.json elite-new.ssd

Extract files from a disc image stored in zip file Elite.zip using .inf files to store file metadata and generate a manifest:

dfstool extract Elite.zip elite --inf

extract does not preserve data in sectors that are not referenced by files present in the catalogue, though it would be straightforward to modify it to do so. extract and make do not currently losslessly roundtrip since make stores files in the created .ssd file in alphabetic order by directory/file name and does not retain the original start sector of each file. Again, it would be straightforward to change this behaviour. extract and make store file metadata in a JSON file which is used to reconstruct the original DFS catalogue. The metadata tracks the following information:

• DFS directory and file name
• DFS locked attribute
• Load and execution addresses
• Inferred file type

extract will also attempt to detokenize any BBC BASIC files it finds along the way.

By default, detokenize will generate "printable" output: i.e. only valid printable ASCII characters will be present in the output and line endings will be normalized to Unix-style LF line endings for ease of consumption in modern text editors etc. "Lossless" mode can be specified with the --lossless option which will retain all non-printable control characters in the original file as well as using Acorn-style LFCR line endings (mimicking the output generated by the *SPOOL command). Lossless format can be used to retain the content of obfuscated BBC BASIC programs but must be carefully edited (most likely as binary files) to retain the control codes.

The manifest is a JSON file that describes the contents of an .ssd or a single side of a .dsd file in terms of files on the current file system. Each file is described by a blob of JSON that looks like the following:

{
    "fileName": "!BOOT",
    "directory": "$",
    "discSide": 0,
    "locked": false,
    "loadAddress": "&000000",
    "executionAddress": "&000000",
    "contentPath": "!BOOT",
    "type": "other"
},

Metadata can also be stored in .inf files. These can be created using the --inf option passed to the extract command. The make and manifest commands will also import .inf files when provided. A manifest can define metadata as a mixture of .inf files and information defined in the JSON file.

The fields are as follows:

• fileName: the DFS file name
• directory: the DFS directory
• locked: the DFS "locked" attribute (*ACCESS etc.)
• loadAddress: the 18-bit DFS load address of the file
• executionAddress: the 18-bit DFS execution address of the file
• contentPath: the path to the file on the local file system relative to the manifest---this must be a valid local absolute or relative path and is, therefore, not subject to DFS restrictions
• type: the file's type: this field is not used for anything when making a new .ssd file but might be useful for something; this value is inferred from the content of the file itself

The "DFS" attributes are those that were read from, or will be written to, the .ssd file's DFS catalogue.

• Acorn DFS Disc Format
• BBC BASIC Token Format
• BBC BASIC Binary Line Number Format

MIT License