ZArchive
Extension
ExtensionDescription
A compressed binary safe archive format. Supports very large file sizes and is fairly fast.
Compresses strings and symbols using a string lookup table. (limit: 65536 different strings/symbols)
Compresses repeated values (limit: 4294967296 consecutive repeated items)
The text archive written by Object.writeArchive will store an object and restore all of its internal variables. However, it will break with large file sizes because it actually writes compilable code and there is a fairly small size limit to that.
The binary archives written by Object.writeBinaryArchive will break if the instance variables change in any of the classes you have archived.
Binary archives loaded after the instance variables in the class has changed will corrupt the memory of SC and cause bleeding havoc.
This class can save large datasets without these drawbacks.
You manually write items to the archive and then should read from the archive in the exact same order you wrote in. With each item a type code is written followed by the data and possibly a repeat count if there was a repetition.
The best way is to write only one item on the top level: a Dictionary. Name each of your top level variables (eg. "title","patterns","songSequence"). The dictionary will be saved with all of its contents regardless of size.
This allows you to easily change your file format since you are not dependent on the top level order of variables, and to add or remove variables from your format without the risk of breaking previous files.
Class Methods
.write
open an archive for writing
Arguments:
| pathName |
path that the file will be written to |
Returns:
a ZArchive
.read
open an archive for reading
Arguments:
| pathName |
path to read. as a setter this is private |
Returns:
a ZArchive
Instance Methods
.path
path that the file is writing to or was loaded from
Returns:
the path
.writeItem
write an object to the archive this will write a character specifying the class type of the object and then will write the object in the smallest possible format. Floats, Integers, Strings, Symbols, SequenceableCollections and Dictionaries all have support to write to the archive. eg. a Float writes a float to the file. In compile string file formats a Float would lose accuracy, here it saves and loads with full accuracy. Strings and Symbols write using a string table, so your 10000 Events with \degree in every single one of them will only need to save the word "degree" once. All other objects will be saved asCompileString.
Arguments:
| thing |
the thing you are saving |
| extraArgs |
(describe argument here) |
Returns:
(returnvalue)
.writeClose
finish the write session and close the file.
Returns:
(returnvalue)
.readItem
read an item from the file and return it
Arguments:
| assertClass |
assertClass is optional. if supplied it will type check the item that is read and throw an error if the item is of a different class. |
Returns:
the object read from the archive
.asZArchive
see zArchiveSupport.sc This message converts the receiver to a valid ZArchive. since this is already a ZArchive then asZArchive returns this itself. this method would convert a string to a ZArchive by opening that path
Returns:
(returnvalue)
.version
Version is variable that can be used to store a file format version number. It is not referenced in the ZArchive class at all, it is not saved or loaded. Its just there for your convience. OK, for my convience. But to use it you could write version as the first object into the archive and then read it when you open it and set the opened ZArchive to this version number. Then objects that read the archive can consult the version number and use to switch their expectations about which variables will come in which order. It is better to use a Dictionary as the top level item and then just detect keys/values.
Returns:
version number
Examples
If your class already supports saving as a compile string, then it will simply save itself as a compile string without problem. If its data intensive (like a sequencer that records real time gesture information) then you can implement methods to read and write efficient and reversible data formats.
Adding support for your custom class: