(updated August 2005)
Mesquite deals with many different aspects of phylogenetic information: taxa, characters, trees, models of character evolution, and so on. It can read this information from files on disk, for instance. Various pieces of information can be packaged in a single file on disk. As well, various pieces of information may be considered together by Mesquite while it is running, and these may come from more than one file on disk. Mesquite makes a distinction between collections of information on disk (files, represented in Mesquite by MesquiteFile objects) and the collections of information it is considering at any given time (projects, represented in Mesquite by MesquiteProject oblects). See the user's manual for a general introduction to projects versus files.
Managing projects and files is the duty of the Mesquite trunk module, and of the FileCoordinator module.
When a NEXUS file is read, its TAXA block is converted to a Taxa object, its CHARACTERS block is converted to a CharacterData object, and its TREES block is converted to a TreeVector object. Each of these objects represents a basic piece of phylogenetic information, and it is a subclass of FileElement. These objects have methods to set and get to which file the element belongs. (Because of the lack of multiple inheritance in Java, FileElements are subclasses of AssociableWithSpecs whose methods are needed by many, though not all, of the particular types of FileElements.)
A single block of a NEXUS file is represented as an object of type NexusBlock. Each file maintains a list of the NexusBlocks attached to them, so that on writing it knows what to components to request text from.
(Mesquite shifted from a more elaborate FileElement-only system to one that involves FileElements and NexusBlocks. The system probably hasn't quite stabilized, and this documentation doesn't tell the whole story.)
The file on disk or at a URL is represented in Mesquite as an object of class MesquiteFile. This class concerns mostly basic input/output, and does not concern itself with the collection of elements of phylogenetic information (Taxa, etc.) except insofar as these elements are represented by NexusBlocks & FileElements which need to know to what file they belong. The MesquiteProject is the class that coordinates these pieces of information.
A MesquiteProject is an object that refers to a collection of information about taxa, character data, and other things. It is not the same as the file sitting on the disk or on a server. Several NEXUS files can be read from disk and their pieces of information all contribute to the same MesquiteProject. Thus, a project needs to keep track of all the files it has read or is working on, as well as all the elements of information. The first MesquiteFile opened in opening the project is the projects's home file. It is the default place in which new information is stored.
Currently, every MesquiteModule object (i.e., every instantiation of a module) has a field which indicates which MesquiteProject it is working with. Almost every module is an employee-descendant of the file coordinator module that supervises that MesquiteProject.
A MesquiteProject can have belonging to it multiple CharacterData objects (each representing a CHARACTERS block in a NEXUS file) and multiple Taxa objects (each representing a TAXA block in a NEXUS file). Because of the possibility of more than one Taxa object, CharacterData objects and Tree objects must store the Taxa to which they refer. This has challenged the NEXUS file format (for instance, most blocks need titles and CHARACTERS and TREES blocks need to include an early line indicating the Taxa, e.g. "LINK TAXA=Adephaga;".
In many circumstances users will read in only a single file and work with it. In this case, the MesquiteProject has only a single MesquiteFile that belongs to it, and all of the informationwill be stored in that file. If this were the only way that Mesquite would be used, there would be no need for a distinction between projects and files. It is only when the user (or a script) requests to link other MesquiteFiles into the project that the notion of a project, as a multi-file collection of information, becomes useful. A design difficulty with Mesquite was how to minimize confusion in the user of projects vs. files. For instance, if there is only a single data file open, and thus one project, does the menu item say "Close File" or "Close project"? Technically Mesquite closes the whole MesquiteProject when this single file is closed, but the users probably thinks they have merely opened a single file, and now they want to close it. Thus, Mesquite in that case says only "Close File". It is only when there are multiple files open that the menu items start to make the distinction between files and projects. This is not ideal, but the alternative would seem to be a two-tiered system in which there are special sorts of files called Mesquite Project Files which contain references to data files. This would probably seem foreign to a user (other programs simply open up the data file directly) and burdens them with the extra step of creating a project in addition to the data files. If you've every tried to explain to a beginning programmer how to deal with projects in IDE's like Codewarrior you'll realize how confusing and complex an explicit project-file can be. Mesquite opts for implicit projects, that to a user arise out of linking files together at run time.
This is a bit messy, because when the reader asks to open a file, he/she might be requesting an entirely new project, or might be requesting that a file be read and added to an existing project. The system is not worked out thoroughly yet. In general a distinction is made between opening a file (which makes a new project and reads the file) and linking a file (which adds the file to the currently foremost project).
The options in opening files are seen in the menu items:
When the FileCoordinator attempts to read the file, it first checks to see if it is a NEXUS file. If so, it uses the NEXUS file interpreter to read the file (see Reading and Writing NEXUS files). If it isn't a NEXUS file, Mesquite queries the user to choose an interpreter module.
When writing a file, the project must be surveyed for all NexusBlocks that belong to the file, and arrange for each to be written up for saving to the file (see Reading and Writing NEXUS files).
class