Library Documentation

PRELIMINARY

This initial documentation is very limited and quite informal; it consists primarily of the header files with a few comments. Not all of the header files are present yet; some internal classes are not included. Hopefully, it will be enough to get started with the library.

FAR files

The place to start is far.h which defines a class simFAR must be instantiated with either a file name or a seekable istream. The content is examined for valididity; if it is invalid, the err() member function will return true.

For a valid FAR file, the entries() member function will return the number of contained entries. Information about the entries may be accessed by subscripting. Thus, a code sequence to look at the first entry might look like this:

	simFAR f("/path/to/file.far");
	if (f.err()) return -1;
	simFAR::Entry &member = f[0];

Information about the entry may be accessed via the Entry class (member in the example). The content of the entry may be accessed by using the stream() member function of the Entry class, which returns a seekable istream that can be used like any other file.

	cout << member.name() << " is " << member.length() << " bytes long" << endl;
	std::istream *s = member.stream();

IFF files

Similarly, iff.h defines a class simIFF which must be instantiated with either a file name or a seekable istream. The content is examined for valididity; if it is invalid, the err() member function will return true.

For a valid IFF file, the entries() member function will return the number of contained resources. Information about the resources may be accessed by subscripting.

	simIFF iff(s);	// instantiate from FAR file's istream
	if (iff.err()) return -1;
	cout << "there are " << iff.entries() << " resources" << endl;
	simIFF::Entry &r = iff[0];
	cout << r.name() << " is " << r.length() << " bytes long" << endl;
	if (r.type("rsmp")) {
		Process_rsmp(r.stream());
	} else if (r.type("BHAV")) {
		Process_BHAV(r.stream());
	}

Processing of the rsmp resource (the resource map) is integrated with IFF processing. If a valid resource map is present, the IFF resources may be accessed by resource name and ID:

	// "iff" defined as above
	simIFF::Type &objd = iff["OBJD"];
	if (objd.err()) return -1;	     // no rsmp or no OBJDs
	cout << "there are " << objd.entries() << " OBJDs" << endl;
	simIFF::Entry &o1 = objd[0];	     // the first OBJD resource
	simIFF::Entry *o2 = objd.id(100);    // the OBJD resource with ID 100
	if (o2 == 0) return -1;		     // no OBJD with ID 100

Resources

Classes that deal with resources are instantiated with a seekable istream and then provide resource-specific access to that type of content. Here are the resources that can be handled at this writing: BCON, BHAV, CARR, DGRP, FCNS, FWAV, GLOB, OBJD, OBJF, SPR#/SPR2, TRCN, and TTAB. There's also a class for string resources such as CTSS, STR#, TTAs, FAMs, and the like. Many of these classes are still under development and the content may change without notice. Individual documentation for these classes will be added later.