cnngimenez/zx-tools

Some tools to read DSK images for ZX Spectrum emulators.

Table of Contents

1. What is it?
2. What can I do with this?
3. What is the objective?
4. Programs
5. How to use in development?
   1. API Documentation
   2. Install gem
   3. Run tests
6. License

What is it?

These are tools to read and modify ZX Spectrum diskette images.

What can I do with this?

It provides the following features:

• Extract files from a diskette image.
• List files inside the diskette.
• Show disk, tracks, and sectors information.
• Show blocks data.
• Add files to a diskette images.
• Provide a Ruby API to read and modify diskette images pragmatically.
• A complete documentation about the diskette image format.

What is the objective?

Programming inside a ZX Spectrum emulator is fun. But, sometimes, you want to use you usual editor, to see get the file, study it, mess with the binary code, etc.

The atari800 emulator has a particular feature for this: it is possible to assign a specific directory from the host computer as the unit H1, H2, etc. Thus, a file saved on H1 through the emulator, will appear on a directory on the host machine.

The Fuse emulator does not have this possibility, but it can use cassettes and diskettes image files. Also, the emulator does not provide any means to read or extract the file from the images through programs on the host machine.

So, the objective can be explained as this: Read/edit file in host ↔ zxtools ↔ Fuse emulator. The idea is to make it possible to read and edit files using nowadays tools, and at the same time, that it can be processed by the Fuse emulator too. In order to do this, the zxtools is needed as intermediary.

Programs

All programs are in the bin directory. This is a Ruby Gem file, so it is supposed to be installed in your home directory with gem install utility.

bin/listdir	Print all diskette files
bin/zxblock	Print binary data from a specific block
bin/zxdisk	Show diskette image information
bin/zxdiskdata	Print binary data of the whole diskette image
bin/zxtracks	Show all tracks header information
	(sector sizes, sector count, track number, etc.)

How to use in development?

API Documentation

As any other Ruby code, rdoc can be used to generate the documentation inside a specific directory in the source code. Just change dir inside the zx-tools cloned repository and run rdoc.

rdoc -o api-docs
firefox api-docs/index.html

Install gem

See “Make your own gem” guide at rubygems.org for information about how to create the gem. In summary, the gem must be built first, then it can be installed. The following commands should work:

gem build zx-tools.gempsec
gem install ./zx-tools-*.gem

Run tests

rake test

License

This work is under the GNU General Public License version 3 (GPLv3) except where specified.

The source code of the program CLOCK.BAS inside the disk file tests/data/manual.dsk, is the Clock program which source code where obtained from The Sinclair ZX Spectrum +3 manual, copyright Amstrad Plc. The manual was found at:

https://worldofspectrum.net/ZXSpectrum128+3Manual/index.html

The Basic source code of Clock can be found at Chapter 8 Part 33, under the following URL:

https://worldofspectrum.net/ZXSpectrum128+3Manual/chapter8pt33.html

Both URL were available and visited on April 20, 2024.