Attribute Preservation Schemes
Files stored in disk images and file archives have a number of attributes, such as file types, dates, and access flags, that should be preserved when files are extracted, and restored when files are added. In some cases, the host filesystem might not support all possible filenames, e.g. HFS allows a file called "Face/Off" but Windows, Linux, and modern Mac OS systems won't allow it.
In addition, files used on the Apple IIgs and Macintosh may have resource forks. These can be tricky to deal with because it means a single file entry can have two sets of file data.
Five strategies are supported:
- None - do nothing. Resource forks, file types, and access flags are discarded when files are extracted. File dates will be preserved if the host filesystem has something equivalent. (Most filesystems record modification dates, but not all store creation dates.)
- AppleSingle (AS) - entries are stored as a single ".as" file. This format defines a way to store the data fork, resource fork, original filename, and all file attributes in a single file.
- AppleDouble (ADF) - entries are stored as a pair of files. The data fork
is stored in a file with the original name, while the resource fork and
any attributes are stored in an optional "header" file whose name starts with
._". This can be convenient to work with, because anything that is only interested in the contents of the data fork can just read the file as it normally would. The header file format is structurally identical to AppleSingle.
- NuLib2 Attribute Preservation Strings (NAPS) - this scheme encodes the file type and auxiliary type in the filename by appending a string like "#062000". Invalid characters are replaced with '%' escapes. Data and resource forks are stored in different files; for resource forks, the appended string ends with "r". This approach is fairly convenient, and was used to good effect by NuLib2 and the original CiderPress, but it can lose file dates and most of the access flags.
- Host-specific - for operating systems that natively support resource forks and extended file attributes, the values can be stored in the host filesystem. This is currently only available for Mac OS. (Since the GUI app was written for Windows, this feature is only available from the CLI tool.)
The panel on the right side of the screen has a collection of configuration options that affect add/extract and import/export operations. These are presented here so that they can be applied equally to operations started with menu items, copy & paste operations, and drag & drop.
Options you can set when adding or importing files:
- Recurse Into Directories - determines whether the application descends into the contents of selected subdirectories.
- Use Compression - determines whether files added will be compressed. Only meaningful for file archives that support compression.
- Strip Paths - if set, partial paths will be stripped from files as they are added.
- Raw - if set, file data forks will be opened in "raw" mode. This is only meaningful for DOS 3.2/3.3 files, and should only be used for files that were generated or extracted as "raw" data.
- Preservation Handling - check the boxes to specify which file attribute preservation systems should be handled when adding files. Normally all three should be checked, but if you wanted to, say, add an AppleSingle file as a ".as" file instead of adding its contents, you would uncheck the AppleSingle box.
- Strip Redundant Extensions - if set, imported files will have any extraneous file extensions removed. For example, when adding a ".txt" file, the file's type would be set to TXT or TEXT, and the ".txt" dropped from the filename.
- Conversion Mode - when importing files, this determines which converter will be applied. (Converters are not auto-selected for imports.)
In addition, the Conversion Settings button will open a configuration window that lets you set the default parameters for importers. For example, you can specify which character set to use when importing text files.
Options you can set when extracting or exporting files:
- Strip Paths - if set, files will not be extracted with subdirectory names. Only matters for file archives and filesystems that store full pathnames, such as ProDOS and HFS.
- Raw - if set, file data forks will be opened in "raw" mode. This is only meaningful for DOS 3.2/3.3 files, and should be used when attempting to preserve the full file contents.
- Preservation Mode - select one preservation mode to use when extracting files.
- Conversion Mode - when exporting files, this determines which converter will be applied. You can choose one specific converter, or select Best to have the program choose one for you.
In addition, the Conversion Settings button will open a configuration window that lets you set the default parameters for exporters. For example, you can specify the color mode for Apple II hi-res images.
The settings panel can be toggled out of sight with the Show/Hide Settings button at the bottom right.
Adding and Extracting Files
To add files, select the Actions > Add Files menu item. Select the set of files and directories to add, and click Select. The files will be added to the directory that is currently selected in the directory tree.
To extract files, select the files and directories you want to extract in the file list, and select the Actions > Extract Files menu item. Navigate to the directory where you want to extract the files, and click Select Here.
If a file already exists, you will be prompted for permission to overwrite the file, or skip add/extract of that one file.
The pathnames of extracted files can be affected by the current file list view mode. For example, suppose you have an HFS volume with a subdirectory called Subdir that has a file called MyFile in it. If you're in single-directory view mode, with Subdir selected in the Directory tree, extracting MyFile will result in the creation of a file called MyFile in the chosen output directory. If you're in full-file mode, the file list shows all files on the volume, and will display the file's partial pathname as Subdir/MyFile. When you extract the entry, a subdirectory called Subdir will be created, and MyFile will be extracted into it.
The rule is that the extraction process matches what you see in the file list. You can modify this by checking the Strip Paths option.
Importing and Exporting files
Import/export have the same general behavior as add/extract.
To import files, choose the desired conversion mode from the options panel. Select the Actions > Import Files menu item. Select the set of files and directories to import, and click Select. The files will be added to the directory that is currently selected in the directory tree.
To export files, choose the desired conversion mode from the options panel. Select the files and directories you want to export in the file list, and select the Actions > Export Files menu item. Navigate to the directory where you want to extract the files, and click Select Here.
If a file already exists, you will be prompted for permission to overwrite the file, or skip import/export of that one file.