org.zmpp.vm
Class Machine3

java.lang.Object
  extended by org.zmpp.vm.Machine3
All Implemented Interfaces:
Machine

public class Machine3
extends Object
implements Machine

This class implements the state and some services of a Z-machine, version 3.

Version:
1.0
Author:
Wei-ju Wu

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.zmpp.vm.Machine
Machine.VariableType
 
Constructor Summary
Machine3()
          Constructor.
 
Method Summary
 void enableOutputStream(int streamnumber, boolean flag)
          Enables or disables the specified output stream.
 RoutineContext getCurrentRoutineContext()
          Returns the current routine context without affecting the state of the machine.
 Dictionary getDictionary()
          Returns the dictonary.
 MemoryAccess getMemoryAccess()
          Returns the reference to the memory access object.
 ObjectTree getObjectTree()
          Returns the object tree.
 int getProgramCounter()
          Returns the current program counter.
 int getRoutineStackPointer()
           
 int getStackPointer()
          Returns the global stack pointer.
 short getStackTopElement()
          Returns the value at the top of the stack without removing it.
 StoryFileHeader getStoryFileHeader()
          Returns the story file header.
 short getVariable(int variableNumber)
          Returns the value of the specified variable.
static Machine.VariableType getVariableType(int variableNumber)
          Returns the variable type for the given variable number.
 void halt(String errormsg)
          Halts the machine with the specified error message.
 boolean hasValidChecksum()
          Returns true, if the checksum validation was successful.
 void initialize(MemoryAccess memaccess, StoryFileHeader fileheader)
          Initialization function.
 boolean isRunning()
          Indicates if the virtual machine is running.
 void newline()
          Prints a newline to the active output streams.
 Instruction nextStep()
           
 void popRoutineContext(short returnValue)
          Pops the current routine context from the stack.
 void print(String str)
          Prints the specified string to the active output streams.
 void printNumber(short number)
          Prints the specified signed number.
 void printZchar(short zchar)
          Prints the specified ZSCII character.
 void printZsciiString(int address)
          Prints the ZSCII string at the specified address to the active output streams.
 void pushRoutineContext(RoutineContext routineContext)
          Pushes a new routine context onto the routine context stack.
 void quit()
          Exists the virtual machine.
 short random(short range)
          Generates a number in the range between 1 and range.
 void readLine(int address, int bufferlen)
          Reads a string from the selected input stream.
 void restart()
          Restarts the virtual machine.
 boolean restore()
          Restores a previously saved state.
 boolean save()
          Saves the current state.
 void selectInputStream(int streamnumber)
          Selects an input stream.
 void setInputStream(int streamnumber, InputStream stream)
          Sets an input stream to the specified number.
 void setOutputStream(int streamnumber, OutputStream stream)
          Sets the output stream to the specified number.
 void setProgramCounter(int address)
          Sets the program counter to a new address.
 void setStackPointer(int stackpointer)
          Sets the global stack pointer to the specified value.
 void setStackTopElement(short value)
          Sets the value of the element at the top of the stack without incrementing the stack pointer.
 void setStatusLine(StatusLine statusLine)
          Sets the Z-machine's status line.
 void setVariable(int variableNumber, short value)
          Sets the value of the specified variable.
 void start()
          Starts the virtual machine.
 int translatePackedAddress(int packedAddress)
          Translates a packed address into a byte address.
 void updateStatusLine()
          Updates the status line.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Machine3

public Machine3()
Constructor.

Method Detail

initialize

public void initialize(MemoryAccess memaccess,
                       StoryFileHeader fileheader)
Initialization function.

Specified by:
initialize in interface Machine
Parameters:
memaccess - the MemoryAccess object
fileheader - the story file header

getStoryFileHeader

public StoryFileHeader getStoryFileHeader()
Returns the story file header.

Specified by:
getStoryFileHeader in interface Machine
Returns:
the story file header

hasValidChecksum

public boolean hasValidChecksum()
Returns true, if the checksum validation was successful.

Specified by:
hasValidChecksum in interface Machine
Returns:
true if checksum is valid

getMemoryAccess

public MemoryAccess getMemoryAccess()
Returns the reference to the memory access object.

Specified by:
getMemoryAccess in interface Machine
Returns:
the reference to the MemoryAccess object

getDictionary

public Dictionary getDictionary()
Returns the dictonary.

Specified by:
getDictionary in interface Machine
Returns:
the dictionary

getObjectTree

public ObjectTree getObjectTree()
Description copied from interface: Machine
Returns the object tree.

Specified by:
getObjectTree in interface Machine
Returns:
the object tree

getStackPointer

public int getStackPointer()
Returns the global stack pointer. This function is mainly exposed for testing purposes.

Specified by:
getStackPointer in interface Machine
Returns:
the stack pointer

setStackPointer

public void setStackPointer(int stackpointer)
Sets the global stack pointer to the specified value.

Specified by:
setStackPointer in interface Machine
Parameters:
stackpointer - the new stack pointer value

getStackTopElement

public short getStackTopElement()
Returns the value at the top of the stack without removing it.

Specified by:
getStackTopElement in interface Machine
Returns:
the stack top element

setStackTopElement

public void setStackTopElement(short value)
Description copied from interface: Machine
Sets the value of the element at the top of the stack without incrementing the stack pointer.

Specified by:
setStackTopElement in interface Machine
Parameters:
value - the value to set

getProgramCounter

public int getProgramCounter()
Returns the current program counter.

Specified by:
getProgramCounter in interface Machine
Returns:
the current program counter

setProgramCounter

public void setProgramCounter(int address)
Sets the program counter to a new address.

Specified by:
setProgramCounter in interface Machine
Parameters:
address - the new address

getVariable

public short getVariable(int variableNumber)
Returns the value of the specified variable. 0 is the stack pointer, 0x01-0x0f are local variables, and 0x10-0xff are global variables. If the stack pointer is read from, its top value will be popped off.

Specified by:
getVariable in interface Machine
Parameters:
variableNumber - the variable number
Returns:
the value of the variable

setVariable

public void setVariable(int variableNumber,
                        short value)
Sets the value of the specified variable. If the stack pointer is written to, the stack will contain one more value.

Specified by:
setVariable in interface Machine
Parameters:
variableNumber - the variable number
value - the value to write

pushRoutineContext

public void pushRoutineContext(RoutineContext routineContext)
Pushes a new routine context onto the routine context stack.

Specified by:
pushRoutineContext in interface Machine
Parameters:
routineContext - the routine context object

popRoutineContext

public void popRoutineContext(short returnValue)
Pops the current routine context from the stack. It will also restore the state before the invocation of the routine, i.e. it will restore the program counter and the stack pointers and set the specfied return value to the return variable.

Specified by:
popRoutineContext in interface Machine
Parameters:
returnValue - the return value

getCurrentRoutineContext

public RoutineContext getCurrentRoutineContext()
Returns the current routine context without affecting the state of the machine.

Specified by:
getCurrentRoutineContext in interface Machine
Returns:
the current routine context

getRoutineStackPointer

public int getRoutineStackPointer()

getVariableType

public static Machine.VariableType getVariableType(int variableNumber)
Returns the variable type for the given variable number.

Parameters:
variableNumber - the variable number
Returns:
STACK if stack variable, LOCAL if local variable, GLOBAL if global

random

public short random(short range)
Generates a number in the range between 1 and range. If range is negative, the random generator will be seeded to abs(range), if range is 0, the random generator will be initialized to a new random seed. In both latter cases, the result will be 0.

Specified by:
random in interface Machine
Parameters:
range - the range
Returns:
a random number

setOutputStream

public void setOutputStream(int streamnumber,
                            OutputStream stream)
Sets the output stream to the specified number.

Specified by:
setOutputStream in interface Machine
Parameters:
streamnumber - the stream number
stream - the output stream

printZsciiString

public void printZsciiString(int address)
Prints the ZSCII string at the specified address to the active output streams.

Specified by:
printZsciiString in interface Machine
Parameters:
address - the address of an ZSCII string

print

public void print(String str)
Prints the specified string to the active output streams.

Specified by:
print in interface Machine
Parameters:
str - the string to print

newline

public void newline()
Prints a newline to the active output streams.

Specified by:
newline in interface Machine

printZchar

public void printZchar(short zchar)
Prints the specified ZSCII character.

Specified by:
printZchar in interface Machine
Parameters:
zchar - the ZSCII character to print

printNumber

public void printNumber(short number)
Prints the specified signed number.

Specified by:
printNumber in interface Machine
Parameters:
number - the number to print§

enableOutputStream

public void enableOutputStream(int streamnumber,
                               boolean flag)
Enables or disables the specified output stream.

Specified by:
enableOutputStream in interface Machine
Parameters:
streamnumber - the output stream number
flag - true to enable, false to disable

setInputStream

public void setInputStream(int streamnumber,
                           InputStream stream)
Sets an input stream to the specified number.

Specified by:
setInputStream in interface Machine
Parameters:
streamnumber - the input stream number
stream - the input stream to set

selectInputStream

public void selectInputStream(int streamnumber)
Selects an input stream.

Specified by:
selectInputStream in interface Machine
Parameters:
streamnumber - the input stream number to select

readLine

public void readLine(int address,
                     int bufferlen)
Reads a string from the selected input stream.

Specified by:
readLine in interface Machine
Parameters:
address - the start address in memory
bufferlen - the length of the buffer

translatePackedAddress

public int translatePackedAddress(int packedAddress)
Translates a packed address into a byte address.

Specified by:
translatePackedAddress in interface Machine
Parameters:
packedAddress - the packed address
Returns:
the translated byte address

updateStatusLine

public void updateStatusLine()
Description copied from interface: Machine
Updates the status line.

Specified by:
updateStatusLine in interface Machine

setStatusLine

public void setStatusLine(StatusLine statusLine)
Sets the Z-machine's status line.

Specified by:
setStatusLine in interface Machine
Parameters:
statusLine - the status line

halt

public void halt(String errormsg)
Halts the machine with the specified error message.

Specified by:
halt in interface Machine
Parameters:
errormsg - the error message

save

public boolean save()
Saves the current state.

Specified by:
save in interface Machine

restore

public boolean restore()
Restores a previously saved state.

Specified by:
restore in interface Machine

restart

public void restart()
Restarts the virtual machine.

Specified by:
restart in interface Machine

quit

public void quit()
Exists the virtual machine.

Specified by:
quit in interface Machine

isRunning

public boolean isRunning()
Indicates if the virtual machine is running.

Specified by:
isRunning in interface Machine
Returns:
true if the machine is running, false, otherwise

start

public void start()
Starts the virtual machine.

Specified by:
start in interface Machine

nextStep

public Instruction nextStep()


Copyright © 2005 . All Rights Reserved.