NEXUS CLASS LIBRARY home | classes | functions

Class BASICCMDLINE

Enums

UserQueryEnum

Data Members

assumptions, characters, data, distances, inf_open, logf, logf_open, message, next_command, quit_now, taxa, trees

Member Functions

BASICCMDLINE, ~BASICCMDLINE, CharLabelToNumber, EnteringBlock, ExitingBlock, FactoryDefaults, FileExists, GetFileName, HandleEndblock, HandleExecute, HandleHelp, HandleLog, HandleNextCommand, HandleShow, NexusError, PreprocessNextCommand, PrintMessage, PurgeBlocks, Read, Report, Reset, Run, SkippingBlock, SkippingCommand, SkippingDisabledBlock, TaxonLabelToNumber, UserQuery

Class Description

BASICCMDLINE provides a template for creating a program that reads NEXUS data files and provides a basic command line. After compiling BASICCMDLINE, you will already have a program that understands the following commands, either typed in at the console or provided in a BASICCMDLINE block in a NEXUS data file (exception is the execute command, which can only be entered at the console). Keywords in the descriptions below are given in uppercase, however the commands themselves are case-insensitive. Lower-case indicates a parameter supplied by the user (e.g., "filename" would be replaced by the actual name of the file). Square brackets indicate optional keywords or subcommands.

 EXECUTE filename;

 LOG [options];

   Option         Action
   ------------------------------------------------------
   FILE=filename  specifies name of log file to start
   START          indicates logging is to be started
   STOP           indicates logging is to be stopped
   APPEND         append to log file if it already exists
   REPLACE        replace log file without asking

 QUIT;
See the Read function for details and to add other commands. To change the name of the program (which is also the prompt name and the name of the program's private NEXUS block), replace all occurrences of BASICCMDLINE with the name of your program (also search for the string "basiccmdline" and replace with an appropriate string at each occurrence). This class handles reading and storage for the NxsReader block BASICCMDLINE. It also serves as the main class for the program BASICCMDLINE, acting as both a NxsReader object (in order to be capable of parsing data files) as well as a NxsBlock object (in order to be able to process commands in a BASICCMDLINE block). Acting as a NxsBlock , it overrides the member functions Read and Reset, which are virtual functions in the base class NxsBlock . Acting as a NxsReader object, it overrides the member functions EnteringBlock, SkippingBlock, and NexusError. Adding a new data member? Don't forget to:

Key to symbols and colors

public, protected, private, A = abstract, C = constructor, D = destructor, I = inline, S = static, V = virtual, F = friend

 

Enums
enum UserQueryEnum
  uq_cancel = 0x01
    provide opportunity to cancel
  uq_ok = 0x02
    provide opportunity to answer ok
  uq_yes = 0x04
    provide opportunity to answer yes
  uq_no = 0x08
    provide opportunity to answer no

 

Data Members
     NxsAssumptionsBlock   *assumptions
       
pointer to NxsAssumptionsBlock object
     NxsCharactersBlock   *characters
       
pointer to NxsCharactersBlock object
     NxsDataBlock   *data
       
pointer to NxsDataBlock object
     NxsDistancesBlock   *distances
       
pointer to NxsDistancesBlock object
     bool   inf_open
       
true if inf is currently open
     ofstream   logf
       
the log file output stream
     bool   logf_open
       
true if logf is currently open
     NxsString   message
       
workspace for composing output strings
     char   *next_command
       
workspace for processing next command entered interactively by user
     bool   quit_now
       
set to false at beginning of Run and turns true only when QUIT command processed
     NxsTaxaBlock   *taxa
       
pointer to NxsTaxaBlock object
     NxsTreesBlock   *trees
       
pointer to NxsTreesBlock object

 

Member Functions
C     BASICCMDLINE()
       
Initializes the id data member to "BASICCMDLINE" and calls the FactoryDefaults member function to perform the remaining initializations. The data member `'' is set to NULL so that memory will be allocated for it in FactoryDefaults.
D     ~BASICCMDLINE()
       
Closes logf if it is open and deletes memory allocated to next_command.
    unsigned   CharLabelToNumber(NxsString s)
       
The code here is identical to the base class version (simply returns 0), so the code here should either be modified or this derived version eliminated altogether. Under what circumstances would you need to modify the default code, you ask? This function should be modified to something meaningful if this derived class needs to construct and run a NxsSetReader object to read a set involving characters. The NxsSetReader object may need to use this function to look up a character label encountered in the set. A class that overrides this method should return the character index in the range [1..nchar]; i.e., add one to the 0-offset index.
    bool   EnteringBlock(NxsString blockName)
       
Called by the NxsReader object when a block named blockName is entered. Allows program to notify user of progress in parsing the NEXUS file. Also gives program the opportunity to ask user if it is ok to purge data currently contained in this block. If user is asked whether existing data should be deleted, and the answer comes back no, then then return false, otherwise return true. Overrides pure virtual function in class NxsReader.
    void   ExitingBlock(NxsString blockName)
       
Called by the NxsReader object when exiting a block named blockName. Allows program to notify user of progress in parsing the NEXUS file. Virtual function that overrides the pure virtual function in the base class NxsReader.
    void   FactoryDefaults()
       
Sets all data members to their factory default settings: inf_open, logf_open and quit_now are set to false; message to the null string, and the pointers data, characters, assumptions, taxa and trees are all set to NULL. The C-string next_command is allocated COMMAND_MAXLEN + 1 bytes if it is currently NULL, and its first byte is set to the null character to create an empty next_command string.
    bool   FileExists(const char *fn)
       
Returns true if file named fn already exists, false otherwise.
    NxsString   GetFileName(NxsToken &token)
       
Called whenever a file name needs to be read from either the command line or a file. Expects next token to be "=" followed by the token representing the file name. Call this function after, say, the keyword "file" has been read in the following LOG command:
 log file=doofus.txt start replace;
Note that this function will read only the "=doofus.txt " leaving "start replace;" in the stream for reading at a later time.
    void   HandleEndblock(NxsToken &token)
       
Called when the END or ENDBLOCK command needs to be parsed from within the BASICCMDLINE block. Basically just checks to make sure the next token in the data file is a semicolon.
    void   HandleExecute(NxsToken &token)
       
Handles everything after the EXECUTE keyword and the terminating semicolon. Purges all blocks before executing file specified, and no warning is given of this.
    void   HandleHelp(NxsToken &token)
       
Called when the HELP command needs to be parsed from within the BASICCMDLINE block.
    void   HandleLog(NxsToken &token)
       
Called when the LOG command needs to be parsed from within the BASICCMDLINE block.
    void   HandleNextCommand()
       
Accepts a string in the form of a BASICCMDLINE block containing one command and processes it just like a real BASICCMDLINE block in a NEXUS data file.
    void   HandleShow(NxsToken &token)
       
Called when the HELP command needs to be parsed from within the BASICCMDLINE block.
    void   NexusError(NxsString &msg, file_pos pos, long line, long col)
       
Called when an error is encountered in a NEXUS file. Allows program to give user details of the error as well as the precise location of the error.
    void   PreprocessNextCommand()
       
Begins with the command just entered by the user, which is stored in the data member next_command, adds a semicolon (if the user failed to supply one), and then adds the string "end;" so the whole bundle looks like a very short BASICCMDLINE block. This is then passed to HandleNextCommand, which processes it just like a real BASICCMDLINE block in a NEXUS data file.
    void   PrintMessage(bool linefeed)
       
All output is funneled through here. Writes string currently stored in message (a NxsString data member) to the output file stream, if open, and also to the console via cerr. Places a newline after the string if linefeed is true.
    void   PurgeBlocks()
       
Detaches all blocks, deletes them, creates new blocks, and finally adds the new blocks. Call this function if you want to be sure that there is no data currently stored in any blocks.
V   void   Read(NxsToken &token)
       
This function provides the ability to read everything following the block name (which is read by the NxsReader object) to the END or ENDBLOCK statement. Characters are read from the input stream in. Overrides the virtual function in the base class.
V   void   Report(ostream &out)
       
This function outputs a brief report of the contents of this BASICCMDLINE block. Overrides the virtual function in the NxsBlock base class.
V   void   Reset()
       
Overrides the NxsBlock virtual function. This function does nothing because the BASICCMDLINE block is simply a private command block and does not store any data.
    void   Run(char *infile_name)
       
Runs the command line interpreter, allowing BASICCMDLINE to interact with user. Typically, this is the only function called in main after a BASICCMDLINE object is created. If infile_name is non-NULL, the first command executed by the command interpreter will be "EXECUTE infile_name".
    void   SkippingBlock(NxsString blockName)
       
Called when program does not recognize a block name encountered in a NEXUS file. Virtual function that overrides the virtual function in the base class NxsReader.
    void   SkippingCommand(NxsString commandName)
       
This function is called when an unknown command named commandName is about to be skipped. This version of the function (which is identical to the base class version) does nothing (i.e., no warning is issued that a command was unrecognized). Modify this virtual function to provide such warnings to the user (or eliminate it altogether since the base class version already does what this does).
    void   SkippingDisabledBlock(NxsString blockName)
       
Called by the NxsReader object when skipping a block named blockName that has been disabled. Allows program to notify user of progress in parsing the NEXUS file. Virtual function that overrides the virtual function in the base class NxsReader.
    unsigned   TaxonLabelToNumber(NxsString s)
       
The code here is identical to the base class version (simply returns 0), so the code here should either be modified or this derived version eliminated altogether. Under what circumstances would you need to modify the default code, you ask? This function should be modified to something meaningful if this derived class needs to construct and run a NxsSetReader object to read a set involving taxa. The NxsSetReader object may need to use this function to look up a taxon label encountered in the set. A class that overrides this method should return the taxon index in the range [1..ntax]; i.e., add one to the 0-offset index.
V   bool   UserQuery(NxsString mb_message, NxsString mb_title, BASICCMDLINE::UserQueryEnum mb_choices)
       
Returns true if response is either "ok" or "yes", and returns false if response is either "no" or "cancel". This is a general query function that can handle many situations. The possible responses are enumerated in BASICCMDLINE::UserQueryEnum: uq_cancel, uq_ok, uq_yes, and uq_no. Not yet fully implemented: only handles uq_ok alone or the (uq_yes | uq_no) combination.