Об ошибках сообщайте по адресу kgeorgiy@rain.ifmo.ru
Выражаю благодарность всем, кто помог мне в осущуствлении проекта Vizi. В частности:
| Сергею Ефимовичу Столяру | За предложение разрабатывать данную область. |
| Анатолию Абрамовичу Шалыто | За идею использовать автоматы при программировании логики визуализаторов. |
| Матвею Казакову | За опробывание идеи использования автоматов при программировании логики визуализаторов. |
| Андрею Станкевичу | За предложение названия "Vizi". |
| Владимиру Котову | За исходную версию AboutDialog, выявление ошибки в реализации обращения while и другую помощь. |
| docs/ | Документация по Vizi |
| readme.html | Этот файл |
| WhatsNew.html | Что уже сделано |
| ToDo.txt | Что еще нужно сделать |
| meta/ | Файлы необходимые для работы Vizi |
| scripts | Содержит build файл и xsl скрипты |
| vizi-<version>.jar | Билд текущей версии Vizi |
| projects/ | Проекты, входящие в поставку |
| FindMaximum/ | Визуализатор алгоритма нахождения максимума (пример) |
| vizi/ | Исходные коды Vizi |
| ant.bat | Запускает build-скрипт |
| build.properties | Конфигурация build-скрипта в строчке project= укажите путь к свойствам проекта (исходно — к проекту FindMaximum). |
| meta/bin/ | Apache Ant (http://ant.apache.org).
Если Ant находится в другом месте, должна быть установлена переменная окружения ANT_HOME. |
| meta/classes-1.1.8.jar | Java-классы от JDK v.1.1.8 используются для проверки визуализатора на совместимость. |
| build/ | Создается при построении проекта. Содержит автоматически сгенерированные файлы. |
| jars/ | Содержит откомпилированные классы и сконвертированные .property файлы. |
| properties/ | Содержит автоматически создаваемые .property файлы. |
| temp/ | Содержит временные файлы. |
| deploy/ | Содержит автоматически сгенерированные HTML и cmd файлы для проектов на русском и английском языка и jar файлы для Vizi и визуализатора. |
| vizi-<version>.jar | Запакованный Vizi. |
| <имя визуализатора>.jar | Запакованный визуализатор. |
| <имя визуализатора>_*.html | HTML с визуализатором на соответсвующем языке. |
| <имя визуализатора>_*.cmd | Скрипт запуска визуализатора из командной строки. |
Для запуска build-скрипта используется файл ant.bat с параметром, определяющим что требуется сделать. По умолчанию используется цель all.
| Компиляция визуализатора | |
|---|---|
| all |
Генерирует исходники автомата, файлы сообщения,
компилирует проект, создает .jar и .html
файлы.
См. описания целей jars, cmds, htmls. |
| jars |
Компилирует проект и создает jar-файлы с
визуализатором.
Если в каталоге проекта находится файл classes-1.1.8.jar, то при компиляции осущетсвляется проверка на использование только методов и классов определенных в jdk 1.1.8. |
| cmds | Создает командные файлы для запуска визуализатора как самостоятельного приложения. |
| htmls | Создает html-файлы для запуска визуализатора. |
| Компиляция документации к визуализатору | |
| docs | Создает документацию к визуализатору (см. цели docs-config, docs-stats и docs-javadoc). |
| docs-config | Создает документацию по конфигурации визуализатора. |
| docs-stats | Подсчитывает статистику по визуализатору. |
| docs-javadoc | Создает JavaDoc по исходному коду визуализатора. |
| Отладка визуализатора | |
| debug-check | Создает командный файл для автоматической проверки правильности генирирования обратных автоматов. |
| debug-source | Создает plain-java исходник по описанию алгоритма. |
| Компиляция Vizi | |
| vizi | Компилирует библиотеку Vizi. |
| vizi-javadoc | Компилирует JavaDoc файлы для Vizi. |
| Прочее | |
| clean | Удаляет автоматически созданные каталоги. |
| help | Выдает краткое описание целей на английском языке. |
Для автоматического обращения шагов типа <step>. Треуется записать их с использование тега <action> вместо тэга <direct>.
Все присваивания переменным модели, записываются в обратимом виде:
@<имя переменной> @= <выражение>
либо
@<имя переменной>[<индекс>] @= <выражение>
Например:
@max @= @a[@i];
@i @= @i + 1; // Вместо @i++;
@a[@i] @= @i;
@a.b[@z[i][j]] @= @q[i][j];
Для присваиваний, осуществленных в теге <action> будет сгенирирован код их обращающий.
ПРИМЕЧАНИЕ: Присваивания не переменным модели нельзя записывать указанным образом.
ПРИМЕЧАНИЕ: В одном шаге нельзя одновременно использовать <action> и <direct> или <action> и <reverse>.
SaveLoadDialog позволяет унифицировать окна сохраниения/восстановления состояния визуализатора. При этом он определяет возможность работы с файлами и буфером обмена и отражает соответствующие элементы интерфейса.
Для использования SaveLoadDialog вы создаете класс унаследованный от него и определяющий метод load. Метод load может возвращать логическое значение или бросать исключение. Если метод вернул "true", то SaveLoadDialog закрывается. Если метод бросил исключение, то сообщения этого исключения отображается в строке комментария, что позволяет генерировать сообщение в месте обнаружения ошибки.
Для SaveLoadDialog определены следующие свойства:
| comment | - | комментарий отображаемый в строке комментария. | |
| content | - | текущее содержимое. | |
| initialContent | - | исходной содержимое (используется при нажатии на кнопку "вернуть". | |
При конфигурации доступны следующие параметры:
| SaveLoadDialog | |
| -CommentPane-lines | Высота области комментария в строках |
| -columns | Исходное количество столбцов в области ввода |
| -rows | Исходное количество строк в области ввода |
SmartTokenizer позволяет в удобном виде разбирать данные полученые от SaveLoadDialog. Он позволяет легко читать числа (целые и вещественные) и строчки. При этом, выводятся локализованные сообщения об ошибках. Так же возможна проверка на окончение ввода. При разборе игнорируются комментарии (как /* */ так и //). При заключении строки в кавычки она считывается как одно слово.
SmartTokenizer удобно использовать непосредственно в методе load SaveLoadDialog, так как при этом практически не придется делать обработку ошибок.
В Vizi входит автоматический проверяльщик автоматов на правильность обращения.
Для использования проверяльщика запустивть build-скрипт с параметром check. При этом, в каталоге deploy будет создан файл вида Check<имя визуализатора>.cmd. Этот при запуске получившегося файла указыватся размер (уровень) шага проверки. Проверяльщик прогоняет визуализатор до всех шагов указанного уровня и проверяет правильность обращения.
Для использования проверяльщика в вашу модель данных должны быть включены значения переменных по умолчанию, задающих пример на котором производится проверка.
Если при проверке вы получаете NullPointerException, то скорее всего это означает, что переменная апплета используется не только для рисования, что не правильно.
Начиная с версии 0.4 введено разделение переменных на глобальные и локальные, а соответствующая поддержка введена в Vizi. Объявление переменных в модели данных поддерживается в целях обеспечения обратной совместимости, но их использование не рекомендуется.
Глобальные переменные определяются в описании алгоритма (<algorithm>), а не в модели данных (<data>) как раньше. Глобальные переменные доступны во всех автоматах, если в них не объявлена локальная переменная с тем же именем.
Локальные переменные определяются в описании автомате (<auto>), и доступны внутри только этого автомата.
Для обращения к переменным используется синтаксис
@<имя переменной>
На пример:
@max @= @a[@i];
при этом осуществляется обратимое присваивание переменной
max значения i-го элемента массива a.
Имя переменной, хранящей модель данных не используется в явном виде,
а подставляется автоматически.
Для обращения к локальным переменным автоматов в процедуре
toString введен синтаксис
@<имя автомата>@<имя переменной>
На пример:
buffer.append(@Main@i);
при этом осуществляется добавление к буфферу значения
локальной переменной i автомата Main.
Для доступа к переменным модели из кода визуализатора используется
синтаксис
<модель>.<имя переменной>
для глобальных переменных и
<модель>.<имя автомата>_<имя переменной>
для локальных переменных.
На пример:
data.max = 0;
System.out.println(data.Main_i);
Начиная с Vizi версии 0.4 идет миграция в сторону использования JavaBeans. Все стандартные компоненты из пакетов ru.ifmo.vizi.base.ui и ru.ifmo.vizi.base.widgets со временем будут превращены в бины. Всвязи с этим будут переименованы некоторые методы и переработаны некоторые классы.
С версии 0.4 вступает в силу новое соглашение о наименовании конфигурационных параметров, согласованное с JavaBeans.
Полное имя параметра (например delay-incrementButton-hint) состоит из имен отдельных праметров, разделяемых дефисами (в данном примере delay, incrementButton и hint). Во всех остальных случаях дефисы не используются. Имя параметра является правльным Java-идентификатором и конструируется как имя переменной: каждое слово, кроме первого начинается с большой буквы, слова ни чем не разделяются, сокращения пишутся как есть (например delay, incrementButton, myURL).
В ближайшее время все компоненты будут приведы к виду использующему данную нотацию.
У каждого JavaBeanа есть набор свойств. Для каждого свойства определены getter и/или setter. Getter имеет имя get<имя свойства>, а setter — set<имя свойства>. Например для свойства font они называются getFont и setFont соответственно.
Свойства бывают простыми и составными, в зависимости от типа. Простые свойства это все простые типы и типы Color и String (значения эти типов можно записать одной строкой). Составные свойства, это все остальные совйства, например типов Button и Font.
Конфигурация бина является набором значений его свойств. Указанные значения устанавливаются с помощью setterов. Соответсвенно смысл свойства можно узнать, прочитав описание соотвествующего setterа. Просмотрев все setterы можно узнать все конфигурируемые свойства бина.
Отладка XML-описания визуализатора состоит из двух этапов:
Для упрощения отладки визуализируемой программы предназначена цель debug-source, определенная в build-сценарии, которая строит реализацию визуализируемой программы, без использования конечных автоматов.
Для каждого автомата (тег <auto>) создается процедура с именем соответсвующим идентификатору автомата. Элементы if и while преобразуются в соответствующий операторы, а step и call-auto в части кода и вызовы процедур соответственно.
В полученном исходный код переносятся комментарии из XML-описания. Сгенерированный код помещается в файл с именем указанным в XML-описании с добавленным суффиксом Debug. Полученный исходный код может отлаживаться с использованием любого программного инструмента.
Отладка сгенерированной системы автоматов производится при помощи валидатора. Для его использования служит цель debug-check, определенная в build-сценарии. Она создает командный файл служащий для запуска валидатора и помещает его в каталок файлов визулизатора.
Валидатор осуществляет последовательную прогонку визуализатора на все большее количество шагов и осуществляет проверку правильности обращения на обратном проходе. При этом сравниваются значения выданные процедурой преобразования состояния автомата в строку (toString). При неравенстве строк на соответствующих шагах выдается сообщение об ошибке.
При запуске валидатор выводит номер текущего шага и комментарий к нему в стандартный поток вывода. При обнаружении ошибки в стандартный поток вывода выдается отладочная информация:
Для вывода отладочной информации используется расширенная функция toString, которая дополнительно выдает стек вызовов автоматов для шага и стек в котором сохраняются значения для обращения. При этом в функции toString, определенной в XML-описании для облегчения отладки имеет смысл выводить значения как можно большего количества переменных.
При запуске валидатора ему можно передать до двух параметров. Первый из них означает шаги с каким уровнем проверять (по умолчанию -1), а второй — с какого шага начинать проверку (по умолчанию 0). Таким образом проверка может осуществляется следующим образом: сначала быстрая проверка на больших шагах, затем, при обнаружении ошибка локализуется с использованием маленьких шагов.