org.zmpp.vm
Interface Machine

All Known Implementing Classes:

Machine3

public interface Machine

This interface gives the instructions an abstract access to the current Z-machine's state.

Version:

1.0

Author:

Wei-ju Wu

Nested Class Summary

static class

Machine.VariableType The possible variable types.

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	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.
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.
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 num) Prints the specified signed number.
void	printZchar(short zchar) Prints the specified ZSCII character.
void	printZsciiString(int stringAddress) 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.

Method Detail

getStoryFileHeader

StoryFileHeader getStoryFileHeader()

Returns the story file header.

Returns:

the story file header

hasValidChecksum

boolean hasValidChecksum()

Returns true, if the checksum validation was successful.

Returns:

true if checksum is valid

getProgramCounter

int getProgramCounter()

Returns the current program counter.

Returns:

the current program counter

setProgramCounter

void setProgramCounter(int address)

Sets the program counter to a new address.

Parameters:

address - the new address

getStackPointer

int getStackPointer()

Returns the global stack pointer.

Returns:

the stack pointer

setStackPointer

void setStackPointer(int stackpointer)

Sets the global stack pointer to the specified value.

Parameters:

stackpointer - the new stack pointer value

getStackTopElement

short getStackTopElement()

Returns the value at the top of the stack without removing it.

Returns:

the stack top element

setStackTopElement

void setStackTopElement(short value)

Sets the value of the element at the top of the stack without incrementing the stack pointer.

Parameters:

value - the value to set

getMemoryAccess

MemoryAccess getMemoryAccess()

Returns the reference to the memory access object.

Returns:

the reference to the MemoryAccess object

getVariable

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.

Parameters:

variableNumber - the variable number

Returns:

the value of the variable

Throws:

IllegalStateException - if a local variable is accessed without a subroutine context or if a non-existent local variable is accessed

setVariable

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.

Parameters:

variableNumber - the variable number

value - the value to write

Throws:

IllegalStateException - if a local variable is accessed without a subroutine context or if a non-existent local variable is accessed

pushRoutineContext

void pushRoutineContext(RoutineContext routineContext)

Pushes a new routine context onto the routine context stack.

Parameters:

routineContext - the routine context object

popRoutineContext

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.

Parameters:

returnValue - the return value

Throws:

IllegalStateException - if no RoutineContext exists

getCurrentRoutineContext

RoutineContext getCurrentRoutineContext()

Returns the current routine context without affecting the state of the machine.

Returns:

the current routine context

getDictionary

Dictionary getDictionary()

Returns the dictonary.

Returns:

the dictionary

getObjectTree

ObjectTree getObjectTree()

Returns the object tree.

Returns:

the object tree

setOutputStream

void setOutputStream(int streamnumber,
                     OutputStream stream)

Sets the output stream to the specified number.

Parameters:

streamnumber - the stream number

stream - the output stream

enableOutputStream

void enableOutputStream(int streamnumber,
                        boolean flag)

Enables or disables the specified output stream.

Parameters:

streamnumber - the output stream number

flag - true to enable, false to disable

setInputStream

void setInputStream(int streamnumber,
                    InputStream stream)

Sets an input stream to the specified number.

Parameters:

streamnumber - the input stream number

stream - the input stream to set

selectInputStream

void selectInputStream(int streamnumber)

Selects an input stream.

Parameters:

streamnumber - the input stream number to select

readLine

void readLine(int address,
              int bufferlen)

Reads a string from the selected input stream.

Parameters:

address - the start address in memory

bufferlen - the length of the buffer

printZsciiString

void printZsciiString(int stringAddress)

Prints the ZSCII string at the specified address to the active output streams.

Parameters:

stringAddress - the address of an ZSCII string

print

void print(String str)

Prints the specified string to the active output streams.

Parameters:

str - the string to print

newline

void newline()

Prints a newline to the active output streams.

printZchar

void printZchar(short zchar)

Prints the specified ZSCII character.

Parameters:

zchar - the ZSCII character to print

printNumber

void printNumber(short num)

Prints the specified signed number.

Parameters:

num - the number to print§

translatePackedAddress

int translatePackedAddress(int packedAddress)

Translates a packed address into a byte address.

Parameters:

packedAddress - the packed address

Returns:

the translated byte address

random

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.

Parameters:

range - the range

Returns:

a random number

updateStatusLine

void updateStatusLine()

Updates the status line.

setStatusLine

void setStatusLine(StatusLine statusline)

Sets the Z-machine's status line.

Parameters:

statusline - the status line

initialize

void initialize(MemoryAccess memaccess,
                StoryFileHeader fileheader)

Initialization function.

Parameters:

memaccess - the MemoryAccess object

fileheader - the story file header

halt

void halt(String errormsg)

Halts the machine with the specified error message.

Parameters:

errormsg - the error message

save

boolean save()

Saves the current state.

restore

boolean restore()

Restores a previously saved state.

restart

void restart()

Restarts the virtual machine.

start

void start()

Starts the virtual machine.

quit

void quit()

Exists the virtual machine.

isRunning

boolean isRunning()

Indicates if the virtual machine is running.

Returns:

true if the machine is running, false, otherwise