FileTypes

File Types

When performing file manipulations, you have to specify a file type using -t, which can be one of

auto,any,as,bin,txt,raw,rec,atok,atxt,itok,itxt,mtok,mtxt

Your choice affects how the data is packed in the allocation blocks and/or how the data is encoded.

Automatic (auto)

Specifying auto tells a2kit you would like to use file system hints and/or contents to automatically select a file type.

FileImage (any)

The native file image used within a2kit is the only type that will preserve everything. It is exposed as a JSON string. It is quite complete in terms of file systems that a2kit explicitly handles. The pack and unpack subcommands are used to manipulate it. For details see the spec page.

AppleSingle (as)

AppleSingle is a kind of file image developed by Apple. It is exposed as a stream of bytes. It preserves the resource forks that occur in Macintosh file systems, but can be used to preserve ProDOS or FAT information as well. It does not preserve sparse structure. If your operations are staying within a2kit you should prefer the any type. If you need to interact with other tools you might need as.

Regarding Apple DOS 3.x: although AppleSingle does not strictly support this, a2kit will make it work by first converting to or from ProDOS depending on the direction the data is flowing.

Raw Files (raw)

The raw type treats a file's allocation blocks as a byte stream, with no interpretation at all. You can ask for the byte stream to be truncated at the EOF using the --trunc flag. The exact effect of --trunc depends on how metadata is stored in the file system's directory.

When a raw file is saved to a file system that maintains its own type codes (e.g. ProDOS), the file will be saved as text, regardless of contents. This can be changed after the fact using the retype subcommand.

The raw type works with any file system.

Binary Files (bin)

Some file systems define a load-address. When working with binary files, a2kit passes only the data between pipeline nodes, i.e., the load-address is discarded (you could keep it by using any). As a result, for some file systems, the load-address has to be specified anew for each node in the pipeline.

The bin type works with any file system.

Raw vs. Binary

While bin and raw both work with binary data, the packing strategy is different. Refer to the following table for the various distinctions.

Property	raw	bin
get truncates at EOF	with --trunc maybe	always
get strips header	never	always
put sets EOF	always	always
put adds header	never	always
put maps to FS type	text	binary

Further details depend on the file system.

Sequential Text (txt)

Text files on disk images may be encoded differently from those on the local file system. For example, DOS 3.3 text files are negative ASCII and use carriage returns as line separators. When using get and put the encoding is automatically converted if the file type is txt. If you want to preserve the original encoding, use the raw type. As an example,

a2kit get -f mytext -t txt -d img.dsk

will display readable text. On the other hand,

a2kit get -f mytext -t raw -d img.dsk --trunc

will display a hex dump. When forming a pipeline use txt unless you have a specific reason to use raw.

Sequential text works with any file system.

Random Access Text (rec)

Random access text files can be loaded into a special JSON string as follows:

a2kit get -f myrecords -t rec -d img.dsk

In some cases (like DOS 3.x, or non-standard ProDOS files) the record length has to be given:

a2kit get -f myrecords -t rec -d img.dsk -l 127

The result might look something like this:

{
    "fimg_type": "rec",
    "record_length": 127,
    "records": {
        "5": ["field1","field2"],
        "2": ["field"]
    }
}

Notice the record numbers do not have to be in any sequence or order. This structure can be passed along the pipeline, for example, you can copy the records from a DOS 3.3 disk to a ProDOS disk:

a2kit get -f myrecords -t rec -d img.dsk -l 127 | a2kit put -f myrecords -t rec -d img.po

If you want to put a local file as random access text, it must be in the JSON representation. N.b. this is different from the other basic file types where the source can be a simple binary or text file.

Random access text works with DOS and ProDOS. a2kit does not yet support CP/M random access text files. You can, however, use the any type to manipulate an arbitrary sparse file, including on CP/M.

BASIC Language Files

BASIC is an interpreted language, but the representation on an Apple II disk is usually tokenized, i.e., keywords and other symbols are represented by a single byte. This byte is chosen to have no overlap with whatever text encoding is chosen. When processing BASIC files you have to know whether you are dealing with a "source" file (almost always this will be found on the local file system, and not on a disk image), or a tokenized file. The a2kit type codes are as follows:

BASIC	format	type code
Applesoft	source	atxt
Applesoft	tokens	atok
Integer	source	itxt
Integer	tokens	itok

It is important to realize a2kit will not automatically tokenize the source or detokenize the tokens. You have to insert a pipeline node if you want to do this. See Languages for examples.

Applesoft and Integer BASIC are specific to DOS and ProDOS.

Assembly Language Files

Some assembly language source files, notably Merlin, are "tokenized" in the sense that they are not simple ASCII. The a2kit type codes are as follows:

Assembler	format	type code
Merlin	local source	mtxt
Merlin	disk image source	mtok
Merlin	assembled executable	bin

Just as with BASIC program files, a2kit will not automatically "tokenize" local source files or "detokenize" source files taken from a disk image. You have to insert a pipeline node if you want to do this. See Languages for examples.

Merlin assembly language is specific to DOS and ProDOS.

Other Types

You can always use the retype subcommand to change one of the above types into any other type, e.g., you can change a binary file into a ProDOS system file. Of course the contents of the file must be consistent with the requirements of the type. Remember that you can control every possible detail with the any representation.