LangCore API

Версия 0.2

Warning

Это черновой вариант.

Содержание

Классы

Value

Методы конвертации значений в значения Java. Если реальный тип не совпадает с запрашиваемым, то будет сгенерирован соответствующий exception (и выдано сообщение юзеру):

double getDouble()
long getLong()
boolean getBoolean()
List<Value> getList()
String getString()
Object getObject()

Метод

int getType()

возвращает код типа значения.

От класса Value унаследован ряд конкретных классов:

Каждый из этих классов реализует метод <type> getValue(), где <type> - java-тип, соответсвующий типу объекта.

ValueType

Перечисление. Определяет тип значения Value. Элементы перечисления:

  • OBJECT
  • INT
  • FLOAT
  • BOOL
  • STRING
  • ARRAY

ObjectValue

Значение объекта - любой java-объект. Значение такого типа нельзя использовать в Fingy-скрипте. Объект предназначен для внутреннего использования.

ArrayValue

Метод getValue() для данного объекта возвращает контейнер типа List<Value>.

Important

Изменение данного контейнера ведет к изменению исходного массива.

Variable

Переменная, обладает значением типа Value и именем. Предоставляет методы:

Value getValue()
void setValue(Value value)
String getName()

VList

Cписок значений, которые передаются в функцию (объект, реализующий Function). Поддерживает следующие методы:

VList(Value[] values)  // конструктор
VList(List<Value> values)  // конструктор
Value get(int index)
int size()
List<Value> asList()
void checkCount(int count)
void checkMinCount(int minCount)
void checkMaxCount(int maxCount)

Методы checkCount, checkMinCount, checkMaxCount проверяют количество элементов в VList. Если количество элементов не подходит, то генерируется соответствующее исключение. VList реализует интерфейс Iterable<Value>.

Breakpoint

Точка останова. Поддерживает методы:

int getLineNumber()
Interpreter getInterpreter()
boolean isEnabled()
boolean setEnable(boolean enabled)
void remove()

Interpreter

Главный класс интерпретатора. Именно через него осуществляется работа с LangCore. Поддерживаемые методы:

// загрузить сорсы (и откомпилить)
void compile(String program) throws SyntaxError
void compile(Reader program) throws SyntaxError

// работа с глобальными функциями и константами
Function getFunction(String name)
void addFunction(String name, Function func)
void removeFunction(String name)

// создать контекст VM
VMContext createVMContext()

// работа с точками останова
Breakpoint createBreakpoint()
Breakpoint[] getBreakpoints()

// XXX Работа с модулями
void addModule(String name, Module module)
void removeModule(String name)

VMContext

Контекст VM. Хранит в себе значения локальных и глобальных переменных, объявленных пользователем функций (в скрипте), стек вызова и др. Служит для непосредственного выполнения скрипта. Поддерживаемые методы:

void run() throws RuntimeError
void runLine(boolean stepInto) throws RuntimeError

// вызывается из другого потока, нежели run()
void pause()
boolean isRunning()

int getCurrentLine()

// Доступ к переменным (локальным)
Variable[] getVariables()
Variable getVariable(String name)

// доступ к определениям функций
...

Интерфейсы

Function

Интерфейс для пользовательских функций. Должен реализовывать один метод:

Value invoke(VMContext ctx, VList args) throws VMError

Типичный пример использования:

class StringConcatenate implements Function {
    Value invoke(VMContext ctx, VList args) {
        args.checkCount(2);
        String a = args.get(0).getString();
        String b = args.get(1).getString();
        return new StringValue(a + b);
    }
}

Module

Пользовательский модуль. Должен реализовывать следующие методы:

Function getFunction(String name)
Variable getVariable(String name)
boolean containsFunction(String name)
boolean containsVariable(String name)

Исключения

LangException

Базовое исключение для исключений LangCore. Содержит методы:

String getMessage()
int getLineNumber()
// номер символа в строке, при выполнении которого произошла ошибка
int getCharNumber()
Interpreter getInterpreter()

RuntimeError

Ошибка времени выполнения. Свидетельствует об ошибке в скрипте (деление на ноль, неверная типизация и т.п.). Данную ошибку выбрасывают методы run и т.п.

SyntaxError

Синтаксическая ошибка. Генерируется при компиляции скрипта.

VMError

Ошибка, сигнализирующая о сбое в работе виртуальной машины. Используется для внутренних целей и для сигнализирования об ошибках типизации.