NEXUS CLASS LIBRARY: BASICCMDLINE Class

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:

- Describe it in the class header comment at the top of "basiccmdline.h"
- Initialize it (unless it is self-initializing) in the constructor and reinitialize it in the Reset function
- Describe the initial state in the constructor documentation
- Delete memory allocated to it in both the destructor and Reset function
- Report it in some way in the Report function

### 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.