======== dfsimage

BBC Micro Acorn DFS floppy disk image maintenance utility

This package contains a command-line utility and a Python module dedicated for maintenance of BBC Micro disk image files. Those files usually have extensions .ssd - for single sided disk image, or .dsd - for double sided disk image.

This package allows indexing contents of the disk images, importing files to and exporting from the disk images, modifying disk images in place, such as renaming files or changing disk title and transferring data between disk images.

The dfsimage module also supports MMB files. MMB files are containers for large number of .ssd disk images, designed for storing disk images on a MMC or SD card. All commands that work with .ssd FILES can be also used on a disk image contained within an MMB file. Index of a disk image within an MMB file can be either specified using index__ option, or appended to the MMB file name, following a colon character, e.g. beeb.mmb:12. Commands |list|, |dump| and |digest|_ can take a range of disk images, e.g. beeb.mmb:10-20 or an entire MMB file. In that case command will be applied to all initialized disk image in the specified range.

There are few commands intended specially for MMB files, such as |donboot|_ or |drecat|_.

__ index-opt_

usage

.. code-block:: shell-session

dfsimage COMMAND IMAGE [options]... dfsimage --help [COMMAND] dfsimage --help-options dfsimage --help-format

examples:

Index all floppy images with contents from the 'images' directory to 'index.json' file

.. code-block:: shell-session

dfsimage index -f json images/.ssd images/.dsd > index.json

Covert a linear double sided image to a '.dsd' file

.. code-block:: shell-session

dfsimage convert --from -D -L linear.img --to inter.dsd

Import all files from the 'files' directory to a new image 'games.ssd'

.. code-block:: shell-session

dfsimage import --new games.ssd --title="GAMES" files/*

Export all files from the disk image at index 12 in 'beeb.mmb' file to the 'files' directory

.. code-block:: shell-session

dfsimage export beeb.mmb:12 -o files/

Index all floppy image contents from the 'images' directory to text table file

.. code-block:: shell-session

dfsimage index --only-files -f table images/.ssd images/.dsd > files.csv

installation

At this point the package is not yet available in the PyPI repository, so it has to be build and installed manually:

Linux

Make sure that pip and dependencies are installed. If you are running Debian, Ubuntu or derived Linux distribution, install the python3-pip package like this.

.. code-block:: shell-session

~$ sudo apt-get install python3-pip

Upgrade pip to latest version.

.. code-block:: shell-session

~$ python -m pip install --upgrade pip

Clone the repository

.. code-block:: shell-session

~/src$ git clone https://github.com/monkeyman79/dfsimage.git ~/src$ cd dfsimage

Build and install package

.. code-block:: shell-session

~/src/dfsimage$ python -m pip install .

Windows

Before installing this package on a Windows machine, make sure that both Python and Git are installed on your system.

• Python can be downloaded from here: https://www.python.org/downloads/
• Git for Windows can be downloaded from here: https://gitforwindows.org/

Make sure to add both Python and Git to your PATH when asked by the installer.

Execute steps below in either Command Prompt or Windows PowerShell.

.. code-block:: ps1con

PS C:\Users\you> mkdir Documents\src PS C:\Users\you> cd Documents\src PS C:\Users\you\Documents\src> git clone "https://github.com/monkeyman79/dfsimage.git" PS C:\Users\you\Documents\src> cd dfsimage PS C:\Users\you\Documents\src\dfsimage> python -m pip install --user .

During installation, you may see the following warning message:

WARNING: The script dfsimage.exe is installed in 'C:\Users\you\AppData\Local\Packages\...\Scripts' which is not on PATH.

Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.

This means that the 'dfsimage' command will not be directly available. There are two options here:

• Always execute dfsimage via python -m dfsimage COMMAND...
• Add the Scripts directory to your PATH variable

Adding Scripts directory to your PATH variable

We can combine powers of Python and PowerShell to automatically add your local Scripts directory to PATH. Execute the steps below in the Windows PowerShell:

.. code-block:: ps1con

PS C:\Users\you> $USER_SITE = python -m site --user-site PS C:\Users\you> $USER_SCRIPTS = (Get-ChildItem (Split-Path -Path $USER_SITE -Parent) Scripts).FullName PS C:\Users\you> [Environment]::SetEnvironmentVariable("PATH",

[Environment]::GetEnvironmentVariable("PATH", "User") + ";$USER_SCRIPTS", "User")

Now close your console window and open it again to make the change take effect.

command list

.. |list| replace:: list .. |create| replace:: create .. |backup| replace:: backup .. |import| replace:: import .. |export| replace:: export .. |dump| replace:: dump .. |build| replace:: build .. |copy-over| replace:: copy-over .. |format| replace:: format .. |copy| replace:: copy .. |rename| replace:: rename .. |delete| replace:: delete .. |destroy| replace:: destroy .. |lock| replace:: lock .. |unlock| replace:: unlock .. |attrib| replace:: attrib .. |digest| replace:: digest .. |validate| replace:: validate .. |create-mmb| replace:: create-mmb .. |dkill| replace:: dkill .. |drestore| replace:: drestore .. |drecat| replace:: drecat .. |donboot| replace:: donboot

|list|_ (cat, index) List files or disk image properties. |create|_ (modify) Create new floppy disk image or modify existing image. |backup|_ (convert, copy-disk) Copy (and convert) image or one floppy side of image. |import|_ Import files to floppy image. |export|_ Export files from floppy image. |dump|_ (read) Dump file or sectors contents |build|_ (write) Write to file or sectors. |copy-over|_ Copy files from one image to another. |format|_ Format disk image removing all files. |copy|_ Copy single file. |rename|_ Rename single file. |delete|_ Delete single file. |destroy|_ Delete multiple files. |lock|_ Lock files. |unlock|_ Unlock files. |attrib|_ Change existing file attributes. |digest|_ Display digest (hash) of file or sectors contents |validate|_ Check disk for errors. |create-mmb|_ Create a new MMB file. |dkill|_ Mark disk image as uninitialized in the MMB index. |drestore|_ Restore disk image marked previously as uninitialized. |drecat|_ Refresh image titles in MMB file catalog. |donboot|_ Display or set images mounted in drives on boot.

options

global options

--warn={none,first,all} Validation warnings display mode. (default: first)

• none - Don't display validation warnings.
• first - Display first warning and skip further validation
• all - Display all validation warning. Some warnings may be redundant.

-v, --verbose Verbose mode - list copied files. -q, --quiet Quiet mode - don't report successful operations. -s, --silent Don't generate error if a file doesn't exist. --continue, --no-continue Continue on non-fatal errors. (default: True)

common command options

.. |pattern| replace:: -p, --pattern=PATTERN .. _pattern:

|pattern| File name or pattern. The fnmatch function is used for pattern matching. If the directory-matching part (e.g. '?.') is not present in the pattern, only files in the default directory are matched.

• pattern '*' matches any string,
• pattern '?' matches any single character,
• pattern '[seq]' matches any character in seq,
• pattern '[!seq]' matches any character not in seq.

Commands: list_, export_

.. |inf| replace:: --inf={always,auto,never} .. _inf:

|inf| Use of inf files.

• always - always create .inf files, fail import if inf file doesn't exist.
• auto - create .inf file if either load or exec address is not 0, file is locked or filename cannot be directly translated to OS filename.
• never - never create .inf files and ignore existing inf files on import.

Commands: import_, export_

.. |replace| replace:: --replace, --no-replace .. _replace:

|replace| Allow replacing existing files. (default: False)

Commands: import_, export_, build_, copy-over_, copy_, rename_

.. |ignore-access| replace:: --ignore-access, --no-ignore-access .. _ignore-access:

|ignore-access| Allow deleting or replacing locked files. (default: False)

Commands: import_, build_, copy-over_, copy_, rename_, delete_, destroy_

.. |preserve-attr| replace:: --preserve-attr, --no-preserve-attr .. _preserve-attr:

|preserve-attr| Preserve 'locked' attribute on copying. (default: False)

Commands: copy-over_, copy_

.. |format-opt| replace:: -f, --format={raw,ascii,hex} .. _format-opt:

|format-opt| Data format. (default: raw)

• raw - read or write raw bytes.
• text - convert line endings to and from BBC's '\r'
• ascii - escape all non-readable or non-ascii characters.
• hex - hexadecimal dump.

Commands: dump_, build_

.. |sector| replace:: --sector=[TRACK/]SECTOR[-[TRACK/]SECTOR] .. _sector:

|sector| Process sectors instead of files. Argument can be a range of sectors, with start and end separated by a dash. Physical sector address format is 'track/sector'.

Commands: dump_, build_, digest_

.. |track| replace:: --track=TRACK[-TRACK] .. _track:

|track| Process tracks instead of files. Argument can be a range of tracks, with start and end separated by a dash.

Comma