## mars
Class MIPSprogram

    java.lang.Object
      mars.MIPSprogram

    public class MIPSprogram

extends Object

Internal representations of MIPS program. Connects source, tokens and machine code. Having all these structures available facilitates construction of good messages, debugging, and easy simulation.

Author:
  Pete Sanderson

Constructor Summary
`MIPSprogram()`

Method Summary
`ErrorList` `assemble(ArrayList MIPSprogramsToAssemble, boolean extendedAssemblerEnabled)` Assembles the MIPS source program.
`ErrorList` `assemble(ArrayList MIPSprogramsToAssemble, boolean extendedAssemblerEnabled, boolean warningsAreErrors)` Assembles the MIPS source program.
`boolean` `backSteppingEnabled()` Returns status of BackStepper associated with this program.
`MacroPool` `createMacroPool()` Instantiates a new `MacroPool` and sends reference of this `MIPSprogram` to it
`ArrayList` `createParsedList()` Produces new empty list to hold parsed source code statements.
`BackStepper` `getBackStepper()` Returns BackStepper associated with this program.
`String` `getFilename()` Produces name of associated source code file.
`MacroPool` `getLocalMacroPool()` Gets local macro pool `MacroPool` for this program
`SymbolTable` `getLocalSymbolTable()` Returns SymbolTable associated with this program.
`ArrayList` `getMachineList()` Produces list of machine statements that are assembled from the program.
`ArrayList` `getParsedList()` Produces existing list of parsed source code statements.
`String` `getSourceLine(int i)` Produces specified line of MIPS source program.
`ArrayList<SourceLine>` `getSourceLineList()` Retrieve list of source statements that comprise the program.
`ArrayList` `getSourceList()` Produces list of source statements that comprise the program.
`Tokenizer` `getTokenizer()` Retrieves Tokenizer for this program
`ArrayList` `getTokenList()` Produces list of tokens that comprise the program.
`boolean` `inSteppedExecution()` Will be true only while in process of simulating a program statement in step mode (e.g.
`ArrayList` `prepareFilesForAssembly(ArrayList filenames, String leadFilename, String exceptionHandler)` Prepares the given list of files for assembly.
`void` `readSource(String file)` Reads MIPS source code from file into structure.
`void` `setLocalMacroPool(MacroPool macroPool)` Sets local macro pool `MacroPool` for this program
`void` `setSourceLineList(ArrayList<SourceLine> sourceLineList)` Set list of source statements that comprise the program.
`boolean` `simulate(int maxSteps)` Simulates execution of the MIPS program.
`boolean` `simulate(int[] breakPoints)` Simulates execution of the MIPS program.
`boolean` `simulateFromPC(int[] breakPoints, int maxSteps, AbstractAction a)` Simulates execution of the MIPS program.
`boolean` `simulateStepAtPC(AbstractAction a)` Simulates execution of the MIPS program.
`void` `tokenize()` Tokenizes the MIPS source program.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### MIPSprogram

    public MIPSprogram()

Method Detail

### getSourceList

    public ArrayList getSourceList()

  Produces list of source statements that comprise the program.

  Returns:
    ArrayList of String. Each String is one line of MIPS source code.

### setSourceLineList

    public void setSourceLineList(ArrayList<SourceLine> sourceLineList)

  Set list of source statements that comprise the program.

  Parameters:
    `sourceLineList` - ArrayList of SourceLine. Each SourceLine represents one line of MIPS source code.

### getSourceLineList

    public ArrayList<SourceLine> getSourceLineList()

  Retrieve list of source statements that comprise the program.

  Returns:
    ArrayList of SourceLine. Each SourceLine represents one line of MIPS source cod

### getFilename

    public String getFilename()

  Produces name of associated source code file.

  Returns:
    File name as String.

### getTokenList

    public ArrayList getTokenList()

  Produces list of tokens that comprise the program.

  Returns:
    ArrayList of TokenList. Each TokenList is list of tokens generated by corresponding line of MIPS source code.
  See Also:
    `TokenList`

### getTokenizer

    public Tokenizer getTokenizer()

  Retrieves Tokenizer for this program

  Returns:
    Tokenizer

### createParsedList

    public ArrayList createParsedList()

  Produces new empty list to hold parsed source code statements.

  Returns:
    ArrayList of ProgramStatement. Each ProgramStatement represents a parsed MIPS statement.
  See Also:
    `ProgramStatement`

### getParsedList

    public ArrayList getParsedList()

  Produces existing list of parsed source code statements.

  Returns:
    ArrayList of ProgramStatement. Each ProgramStatement represents a parsed MIPS statement.
  See Also:
    `ProgramStatement`

### getMachineList

    public ArrayList getMachineList()

  Produces list of machine statements that are assembled from the program.

  Returns:
    ArrayList of ProgramStatement. Each ProgramStatement represents an assembled basic MIPS instruction.
  See Also:
    `ProgramStatement`

### getBackStepper

    public BackStepper getBackStepper()

  Returns BackStepper associated with this program. It is created upon successful assembly.

  Returns:
    BackStepper object, null if there is none.

### getLocalSymbolTable

    public SymbolTable getLocalSymbolTable()

  Returns SymbolTable associated with this program. It is created at assembly time, and stores local labels (those not declared using .globl directive).

### backSteppingEnabled

    public boolean backSteppingEnabled()

  Returns status of BackStepper associated with this program.

  Returns:
    true if enabled, false if disabled or non-existant.

### getSourceLine

    public String getSourceLine(int i)

  Produces specified line of MIPS source program.

  Parameters:
    `i` - Line number of MIPS source program to get. Line 1 is first line.
  Returns:
    Returns specified line of MIPS source. If outside the line range, it returns null. Line 1 is first line.

### readSource

    public void readSource(String file)
                    throws ProcessingException

  Reads MIPS source code from file into structure. Will always read from file. It is GUI responsibility to assure that source edits are written to file when user selects compile or run/step options.

  Parameters:
    `file` - String containing name of MIPS source code file.
  Throws:
    `ProcessingException` - Will throw exception if there is any problem reading the file.

### tokenize

    public void tokenize()
                  throws ProcessingException

  Tokenizes the MIPS source program. Program must have already been read from file.

  Throws:
    `ProcessingException` - Will throw exception if errors occured while tokenizing.

### prepareFilesForAssembly

    public ArrayList prepareFilesForAssembly(ArrayList filenames,
                                             String leadFilename,
                                             String exceptionHandler)
                                      throws ProcessingException

  Prepares the given list of files for assembly. This involves reading and tokenizing all the source files. There may be only one.

  Parameters:
    `filenames` - ArrayList containing the source file name(s) in no particular order
    `leadFilename` - String containing name of source file that needs to go first and will be represented by "this" MIPSprogram object.
    `exceptionHandler` - String containing name of source file containing exception handler. This will be assembled first, even ahead of leadFilename, to allow it to include "startup" instructions loaded beginning at 0x00400000. Specify null or empty String to indicate there is no such designated exception handler.
  Returns:
    ArrayList containing one MIPSprogram object for each file to assemble. objects for any additional files (send ArrayList to assembler)
  Throws:
    `ProcessingException` - Will throw exception if errors occured while reading or tokenizing.

### assemble

    public ErrorList assemble(ArrayList MIPSprogramsToAssemble,
                              boolean extendedAssemblerEnabled)
                       throws ProcessingException

  Assembles the MIPS source program. All files comprising the program must have already been tokenized. Assembler warnings are not considered errors.

  Parameters:
    `MIPSprogramsToAssemble` - ArrayList of MIPSprogram objects, each representing a tokenized source file.
    `extendedAssemblerEnabled` - A boolean value - true means extended (pseudo) instructions are permitted in source code and false means they are to be flagged as errors.
  Returns:
    ErrorList containing nothing or only warnings (otherwise would have thrown exception).
  Throws:
    `ProcessingException` - Will throw exception if errors occured while assembling.

### assemble

    public ErrorList assemble(ArrayList MIPSprogramsToAssemble,
                              boolean extendedAssemblerEnabled,
                              boolean warningsAreErrors)
                       throws ProcessingException

  Assembles the MIPS source program. All files comprising the program must have already been tokenized.

  Parameters:
    `MIPSprogramsToAssemble` - ArrayList of MIPSprogram objects, each representing a tokenized source file.
    `extendedAssemblerEnabled` - A boolean value - true means extended (pseudo) instructions are permitted in source code and false means they are to be flagged as errors
    `warningsAreErrors` - A boolean value - true means assembler warnings will be considered errors and terminate the assemble; false means the assembler will produce warning message but otherwise ignore warnings.
  Returns:
    ErrorList containing nothing or only warnings (otherwise would have thrown exception).
  Throws:
    `ProcessingException` - Will throw exception if errors occured while assembling.

### simulate

    public boolean simulate(int[] breakPoints)
                     throws ProcessingException

  Simulates execution of the MIPS program. Program must have already been assembled. Begins simulation at beginning of text segment and continues to completion.

  Parameters:
    `breakPoints` - int array of breakpoints (PC addresses). Can be null.
  Returns:
    true if execution completed and false otherwise
  Throws:
    `ProcessingException` - Will throw exception if errors occured while simulating.

### simulate

    public boolean simulate(int maxSteps)
                     throws ProcessingException

  Simulates execution of the MIPS program. Program must have already been assembled. Begins simulation at beginning of text segment and continues to completion or until the specified maximum number of steps are simulated.

  Parameters:
    `maxSteps` - maximum number of steps to simulate.
  Returns:
    true if execution completed and false otherwise
  Throws:
    `ProcessingException` - Will throw exception if errors occured while simulating.

### simulateFromPC

    public boolean simulateFromPC(int[] breakPoints,
                                  int maxSteps,
                                  AbstractAction a)
                           throws ProcessingException

  Simulates execution of the MIPS program. Program must have already been assembled. Begins simulation at current program counter address and continues until stopped, paused, maximum steps exceeded, or exception occurs.

  Parameters:
    `breakPoints` - int array of breakpoints (PC addresses). Can be null.
    `maxSteps` - maximum number of instruction executions. Default -1 means no maximum.
    `a` - the GUI component responsible for this call (GO normally). set to null if none.
  Returns:
    true if execution completed and false otherwise
  Throws:
    `ProcessingException` - Will throw exception if errors occured while simulating.

### simulateStepAtPC

    public boolean simulateStepAtPC(AbstractAction a)
                             throws ProcessingException

  Simulates execution of the MIPS program. Program must have already been assembled. Begins simulation at current program counter address and executes one step.

  Parameters:
    `a` - the GUI component responsible for this call (STEP normally). Set to null if none.
  Returns:
    true if execution completed and false otherwise
  Throws:
    `ProcessingException` - Will throw exception if errors occured while simulating.

### inSteppedExecution

    public boolean inSteppedExecution()

  Will be true only while in process of simulating a program statement in step mode (e.g. returning to GUI after each step). This is used to prevent spurious AccessNotices from being sent from Memory and Register to observers at other times (e.g. while updating the data and register displays, while assembling program's data segment, etc).

### createMacroPool

    public MacroPool createMacroPool()

  Instantiates a new `MacroPool` and sends reference of this `MIPSprogram` to it

  Returns:
    instatiated MacroPool

### getLocalMacroPool

    public MacroPool getLocalMacroPool()

  Gets local macro pool `MacroPool` for this program

  Returns:
    MacroPool

### setLocalMacroPool

    public void setLocalMacroPool(MacroPool macroPool)

  Sets local macro pool `MacroPool` for this program

  Parameters:
    `macroPool` - reference to MacroPool