17.4. General Communication interfaces

In this section the general interfaces that are used in several plugins are explained. They are all placed in the package 'kickass.plugins.interf.general'. The most important ones are IEngine and IValue. Give them a quick review and return to this chapter when you need info for implementing a particular plugin.

17.4.1. The IEngine Interface

The IEngine interface is the central object when you want to communicate with Kick Assembler. With this you can report errors, print text, create an output stream for outputting a file, etc.

Table 17.1. IEngine Interface

Method Description
void addError(String message, ISourceRange range); Adds an error to the engines error list, but continues execution. With this method you can report several errors from your plug in.
byte charToByte(char c); Converts a char to a petscii byte (upper case).
IMemoryBlock createMemoryBlock(String name, int startAddr, byte[] bytes); Creates a memory block. Used as result in some plug ins.
void error(String message); Prints an error message and stops execution. Works like the .error directive. Important! This method will throw an AsmException which you have to pass through any try-catch block used in your code.
void error(String message, ISourceRange); Like error(string message), buy with a specified position in the code (SourceRange)
File getCurrentDirectory(); Gets the current directory.
File getFile(String filename); Opens a file with the given filename. The assembler will look for the file as it would look for a source code file. If it isn't present in the current directory, it will look in the library directories. It will return null if the file can't be found.
String normalizeFileName(String name); Used to evaluate any parameters in a filename string. E.g. if a filename for a disk is given as "%o.d64" and assembled from MyDemo.asm %o is replaced and "MyDemo.d64" is returned.
OutputStream openOutputStream(String name) throws Exception; Use this to create output from the assembler (like a disk file for a disk writer)
void print(String message); Prints a message to the screen. Works like the .print directive.
void printNow(String message); Prints a message to the screen. Works like the .printnow directive.
byte[] stringToBytes(String str); Converts a string to petscii bytes (Upper case)