Files added to an archive are copied without modification, other than what is required to separate the contents of the forks from file attribute preservation metadata. Sometimes you want to convert the file's contents as it's being added though.
Conversions are performed by the import command, which takes the same arguments as add, but with the addition of an "import-spec". The import specifier tells CiderPress II how to do the conversion. Unlike exports, there is no "best" conversion, so you must specify which converter to use.
Suppose we want to edit an Applesoft BASIC program. We first need to export the program to a text file:
cp2 xp code.shk bas HRBARS
exporting HRBARS -> HRBARS.txt [bas]
We would edit HRBARS.txt, making whatever changes were desired, and then we'd add it back:
cp2 import -f code.shk bas HRBARS.txt
Importing 1 file Overwriting 'HRBARS' importing HRBARS.txt -> HRBARS
If the import fails, e.g. because the Applesoft program has a syntax error (like an invalid line number) or it's simply the wrong type of file (like a PNG), the command will halt with an error message.
The only import converters currently defined are text, for text files, and bas, for Applesoft BASIC.
The text converter will change the text to use the proper end-of-line character, usually carriage return ($0D). The character set for the input can be specified as UTF-8, ISO 8859-1, or CP1252, while the output can be encoded as ASCII, high ASCII, or Mac OS Roman. The defaults are UTF-8 and ASCII, but if the target is a DOS filesystem the output will be set to high ASCII instead. See the manual for details.