Added documentation for stepwise execution. Modified the callback parameters for stepwise execution to look more like the table

Author: craftybones

README.md

@@ -13,6 +13,7 @@ This project is a small simulator that combines BASIC like line numbers and asse
 4. [Instruction Set](#instruction-set)
 5. [Documentation](#documentation)
 6. [Error Handling](#error-handling)
+
 ### Installation
 
 `npm install https://github.com/step/assembly_simulator.git`
@@ -406,20 +407,60 @@ There is also a stack that you can `PUSH` and `POP` from.
  4. The line number from the source file or program that was executed in `SL`
  5. The actual instruction being executed in `INST`
 
+ 
+#### Stepwise Execution
+
+The Machine has the capability of executing stepwise. This feature allows one to 'step through' the program. 
+
+```javascript
+const machine = new Machine();
+let program = fs.readFileSync("add.asm","utf8");
+let callBack = (state) => {
+ let { A, B, C, D } = state;
+ let { EQ, NE, GT, LT } = state;
+ let { PRN } = state;
+ let { CL, NL } = state;
+ let { SL, INST } = state;
+ console.log(`A : ${A}, B : ${B}, C : ${C}, D : ${D}`);
+ console.log(`EQ : ${EQ}, NE : ${NE}, GT : ${GT}, LT : ${LT}`);
+ console.log(`CL : ${CL}, NL : ${NL}`);
+ console.log(`SL : ${SL}, INST : ${INST}`);
+ console.log(`INST : ${INST}`);
+} 
+let executor;
+try {
+ machine.load(program);
+ executor = machine.executeStepWise();
+} catch(e) {
+ console.log("Error on ", e.lineNumber, e.instruction);
+}
+
+try {
+ machine.nextStep();
+ machine.nextStep();
+} catch(e) {
+ // do whatever with the error
+}
+```
+
+As shown above, in order to use it, you are required to pass a callback. The callback will be called with the same fields that `getTable` fetches. The important thing to note here is that once the machine executes the program completely, the callback will no longer be called no matter how many times you call `nextStep`.
+
+This manner of execution is very useful to debug things like infinite loops.
+
 ### Error Handling
 
- All errors currently are encapsulated by the `InvalidInstructionException` class. All exceptions have two pieces of information currently.
+All errors currently are encapsulated by the `InvalidInstructionException` class. All exceptions have two pieces of information currently.
 
- 1. Source line number where the exception occurred in `lineNumber`
- 2. The offending instruction in `instruction`
+1. Source line number where the exception occurred in `lineNumber`
+2. The offending instruction in `instruction`
 
- Always surround your machine's `load` and `execute` in try catch blocks.
+Always surround your machine's `load` and `execute` in try catch blocks.
 
- ```javascript
- try {
-  machine.load(program);
-  machine.execute();
- } catch(e) {
-  console.log("Error on ", e.lineNumber, e.instruction);
- }
- ```
+```javascript
+try {
+ machine.load(program);
+ machine.execute();
+} catch(e) {
+ console.log("Error on ", e.lineNumber, e.instruction);
+}
+```

src/lines.js

@@ -15,7 +15,6 @@ class Lines {
  let { regs, flags, stack } = initState;
  let state = { regs, flags, halt: false };
  let lineNumbers = this.lines.map(l => l.getLineNumber());
- console.log(this.fnTable);
  let programCounter = new ProgramCounter(lineNumbers, this.fnTable);
  let executor = () => {
  let line = this.lines[programCounter.getCurrentLineIndex()];

src/machine.js

@@ -69,7 +69,7 @@ class Machine {
  return this.stack.asArray();
  }
 
- _addToTable({ regs, flags, nextLine, currLine, prn, srcLine, instruction }) {
+ _toRow({ regs, flags, nextLine, currLine, prn, srcLine, instruction }) {
  let { A, B, C, D } = regs;
  let { EQ, NE, GT, LT } = flags;
  let row = {
@@ -87,7 +87,11 @@ class Machine {
  SL: srcLine,
  INST: instruction
  };
- this.table.push(row);
+ return row;
+ }
+
+ _addToTable(state) {
+ this.table.push(this._toRow(state));
  }
 
  getTable() {
@@ -139,7 +143,7 @@ class Machine {
  this._reset();
  let wrappedCb = state => {
  this._updateCurrentExecState(state);
- cb(state);
+ cb(this._toRow(state));
  };
  let regs = this.getRegs();
  let flags = this.getFlags();

test/testMachine.js

@@ -128,8 +128,7 @@ describe('Machine step wise execution', () => {
  const machine = new Machine();
  const program = ['10 START', '30 MOV A,10', '40 STOP'];
  let actualRegs = {};
- const cb = state => {
- let { A, B, C, D } = state.regs;
+ const cb = ({ A, B, C, D}) => {
  actualRegs = { A, B, C, D };
  };
  machine.load(stitch(program));
@@ -146,11 +145,10 @@ describe('Machine step wise execution', () => {
  const machine = new Machine();
  const program = ['10 START', '30 JMP 50', '40 MOV A,10', '50 STOP'];
  let actualCurrLine, actualNextLine, actualRegs;
- const cb = ({ nextLine, currLine, regs }) => {
- let { A, B, C, D } = regs;
+ const cb = ({ NL, CL, A, B, C, D }) => {
  actualRegs = { A, B, C, D };
- actualCurrLine = currLine;
- actualNextLine = nextLine;
+ actualCurrLine = CL;
+ actualNextLine = NL;
  };
  machine.load(stitch(program));
  machine.executeStepWise(cb);
@@ -179,7 +177,7 @@ describe('Machine step wise execution', () => {
  '60 STOP'
  ];
  let actualFlags;
- let cb = ({ flags }) => (actualFlags = flags);
+ let cb = ({ EQ, NE, GT, LT }) => (actualFlags = { EQ, NE, GT, LT});
  machine.load(stitch(program));
  machine.executeStepWise(cb);
  machine.nextStep();