-
Notifications
You must be signed in to change notification settings - Fork 0
andrey-komarov/vizi
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
<html>
<head>
<title>Vizi readme</title>
<meta content="text/html; charset=WINDOWS-1251" http-equiv="Content-Type">
<style>
.c {
font-family: Courier;
}
td {
vertical-align:top;
}
</style>
</head>
<body>
<h1>Оглавление</h1>
<a href="#Thanks">Благодарности</a>
<br><a href="#Structure">Структура проекта</a>
<br> <a href="#Structure.files">Файлы и каталоги входящие в поставку</a>
<br> <a href="#Structure.download">Файлы скачиваемые отдельно</a>
<br> <a href="#Structure.runtime">Файлы и каталоги создаваемые в процессе работы</a>
<br><a href="#Build">Использование build-скрипта</a>
<br> <a href="#Build.targets">Определенные цели</a>
<br><a href="#AutoReverse">Автоматическое обращение шагов типа step</a>
<br><a href="#SaveLoadDialog">Использование SaveLoadDialog</a>
<br><a href="#SmartTokenizer">Использование SmartTokenizer</a>
<br><a href="#Verification">Автоматическая проверка автоматов</a>
<br><a href="#Variables">Использование переменных</a>
<br><a href="#JavaBeans">JavaBeans</a>
<br> <a href="#Configuration">Соглашение о формате конфигурации</a>
<br> <a href="#BeanConfig">Конфигурация бина</a>
<br><a href="#Debug">Отладка визуализатора</a>
<br> <a href="#Debug.source">Отладка визуализируемой программы</a>
<br> <a href="#Debug.check">Отладка системы автоматов</a>
<br><a href="#ImportantNotes">Важные замечания</a>
<p>
<b>Об ошибках сообщайте по адресу
<a href="mailto:kgeorgiy@rain.ifmo.ru">kgeorgiy@rain.ifmo.ru</a></b>
</p>
<!----------------------------------------------------------------------------->
<a name="Thanks"><h1>Благодарности</h1></a>
<!----------------------------------------------------------------------------->
<p>
Выражаю благодарность всем, кто помог мне в осущуствлении проекта
<em>Vizi</em>. В частности:
<table width="100%" border="1" cellspacing="0">
<tr>
<td>Сергею Ефимовичу Столяру</td>
<td>
За предложение разрабатывать данную область.
</td>
</tr><tr>
<td>Анатолию Абрамовичу Шалыто</td>
<td>
За идею использовать автоматы при программировании
логики визуализаторов.
</td>
</tr><tr>
<td>Матвею Казакову</td>
<td>
За опробывание идеи использования автоматов при
программировании логики визуализаторов.
</td>
</tr><tr>
<td>Андрею Станкевичу</td>
<td>За предложение названия "<em>Vizi</em>".</td>
</tr><tr>
<td>Владимиру Котову</td>
<td>
За исходную версию <tt>AboutDialog</tt>, выявление
ошибки в реализации обращения <tt>while</tt> и
другую помощь.
</td>
</tr>
</table>
</p>
<!----------------------------------------------------------------------------->
<a name="Structure"><h1>Структура проекта</h1></a>
<!----------------------------------------------------------------------------->
<a name="Structure.files"><h2>Файлы и каталоги входящие в поставку</h2></a>
<table width="100%" border="1" cellspacing="0">
<col width="200"/>
<tr>
<td class="c">docs/</td>
<td>Документация по <em>Vizi</em></td>
</tr><tr>
<td class="c"> readme.html</td>
<td>Этот файл</td>
</tr><tr>
<td class="c"> WhatsNew.html</td>
<td>Что уже сделано</td>
</tr><tr>
<td class="c"> ToDo.txt</td>
<td>Что еще нужно сделать</td>
</tr><tr>
<td class="c">meta/</td>
<td>Файлы необходимые для работы <em>Vizi</em></td>
</tr><tr>
<td class="c"> scripts</td>
<td>Содержит build файл и xsl скрипты</td>
</tr><tr>
<td class="c"> vizi-<version>.jar</td>
<td>Билд текущей версии <em>Vizi</em></td>
</tr><tr>
<td class="c">projects/</td>
<td>Проекты, входящие в поставку</td>
</tr><tr>
<td class="c"> FindMaximum/</td>
<td>Визуализатор алгоритма нахождения максимума (пример)</td>
</tr><tr>
<td class="c"> vizi/</td>
<td>Исходные коды <em>Vizi</em></td>
</tr><tr>
<td class="c">ant.bat</td>
<td>Запускает build-скрипт</td>
</tr><tr>
<td class="c">build.properties</td>
<td>Конфигурация build-скрипта в строчке <tt>project=</tt>
укажите путь к свойствам проекта (исходно —
к проекту <em>FindMaximum</em>).
</td>
</tr>
</table>
<a name="Structure.download"><h2>Файлы скачиваемые отдельно</h2></a>
<table width="100%" border="1" cellspacing="0">
<col width="250"/>
<tr>
<td class="c">meta/bin/</td>
<td><em>Apache Ant</em> (<a href="http://ant.apache.org">http://ant.apache.org</a>).
<br>Если <em>Ant</em> находится в другом месте, должна быть
установлена переменная окружения <tt>ANT_HOME</tt>.
</td>
</tr><tr>
<td class="c">meta/classes-1.1.8.jar</td>
<td>Java-классы от JDK v.1.1.8 используются для проверки
визуализатора на совместимость.
</td>
</tr>
</table>
<a name="Structure.runtime"><h2>Файлы и каталоги создаваемые в процессе работы</h2></a>
<table width="100%" border="1" cellspacing="0">
<col width="200"/>
</tr><tr>
<td class="c">build/</td>
<td>
Создается при построении проекта.
Содержит автоматически сгенерированные файлы.
</td>
</tr><tr>
<td class="c"> jars/</td>
<td>
Содержит откомпилированные классы и сконвертированные
<tt>.property</tt> файлы.
</td>
</tr><tr>
<td class="c"> properties/</td>
<td>
Содержит автоматически создаваемые <tt>.property</tt> файлы.
</td>
</tr><tr>
<td class="c"> temp/</td>
<td>Содержит временные файлы.</td>
</tr><tr>
<td class="c">deploy/</td>
<td>
Содержит автоматически сгенерированные HTML и
cmd файлы для проектов на русском и английском
языка и jar файлы для <em>Vizi</em> и визуализатора.
</td>
</tr><tr>
<td class="c"> vizi-<version>.jar</td>
<td>Запакованный <em>Vizi</em>.</td>
</tr><tr>
<td class="c"> <имя визуализатора>.jar</td>
<td>Запакованный визуализатор.</td>
</tr><tr>
<td class="c"> <имя визуализатора>_*.html</td>
<td>HTML с визуализатором на соответсвующем языке.</td>
</tr><tr>
<td class="c"> <имя визуализатора>_*.cmd</td>
<td>Скрипт запуска визуализатора из командной строки.</td>
</tr>
</table>
<!----------------------------------------------------------------------------->
<a name="Build"><h1>Использование build-скрипта</h1></a>
<!----------------------------------------------------------------------------->
<p>
Для запуска build-скрипта используется файл <tt>ant.bat</tt>
с параметром, определяющим что требуется сделать.
По умолчанию используется цель <tt>all</tt>.
</p>
<a name="Build.targets"><h2>Определенные цели</h2></a>
<table width="100%" border="1" cellspacing="0">
<col width="100">
<tr>
<th colspan="2">Компиляция визуализатора</th>
</tr><tr>
<td class="c">all</td>
<td>
Генерирует исходники автомата, файлы сообщения,
компилирует проект, создает <tt>.jar</tt> и <tt>.html</tt>
файлы.
<br>
См. описания целей <tt>jars</tt>, <tt>cmds</tt>,
<tt>htmls</tt>.
</td>
</tr><tr>
<td class="c">jars</td>
<td>
Компилирует проект и создает <tt>jar</tt>-файлы с
визуализатором.
<br>
Если в каталоге проекта находится файл
<tt>classes-1.1.8.jar</tt>, то при компиляции
осущетсвляется проверка на использование только методов
и классов определенных в <tt>jdk 1.1.8</tt>.
</td>
</tr><tr>
<td class="c">cmds</td>
<td>
Создает командные файлы для запуска визуализатора как
самостоятельного приложения.
</td>
</tr><tr>
<td class="c">htmls</td>
<td>
Создает <tt>html</tt>-файлы для запуска визуализатора.
</td>
</tr><tr>
<th colspan="2">Компиляция документации к визуализатору</th>
</tr><tr>
<td class="c">docs</td>
<td>
Создает документацию к визуализатору (см. цели
<tt>docs-config</tt>, <tt>docs-stats</tt> и
<tt>docs-javadoc</tt>).
</td>
</tr><tr>
<td class="c">docs-config</td>
<td>Создает документацию по конфигурации визуализатора.</td>
</tr><tr>
<td class="c">docs-stats</td>
<td>Подсчитывает статистику по визуализатору.</td>
</tr><tr>
<td class="c">docs-javadoc</td>
<td>Создает <em>JavaDoc</em> по исходному коду визуализатора.</td>
</tr><tr>
<th colspan="2">Отладка визуализатора</th>
</tr><tr>
<td class="c">debug-check</td>
<td>
Создает командный файл для автоматической проверки
правильности генирирования обратных автоматов.
</td>
</tr><tr>
<td class="c">debug-source</td>
<td>
Создает plain-java исходник по описанию алгоритма.
</td>
</tr><tr>
<th colspan="2">Компиляция <em>Vizi</em></th>
</tr><tr>
<td class="c">vizi</td>
<td>Компилирует библиотеку <em>Vizi</em>.</td>
</tr><tr>
<td class="c">vizi-javadoc</td>
<td>Компилирует <em>JavaDoc</em> файлы для <em>Vizi</em>.</td>
</tr><tr>
<th colspan="2">Прочее</th>
</tr><tr>
<td class="c">clean</td>
<td>Удаляет автоматически созданные каталоги.</td>
</tr><tr>
<td class="c">help</td>
<td>Выдает краткое описание целей на английском языке.</td>
</tr>
</table>
<!----------------------------------------------------------------------------->
<a name="AutoReverse"><h1>Автоматическое обращение шагов типа step</h1></a>
<!----------------------------------------------------------------------------->
<p>
Для автоматического обращения шагов типа <tt><step></tt>.
Треуется записать их с использование тега <tt><action></tt>
вместо тэга <tt><direct></tt>.
</p>
<p>
Все присваивания переменным модели, записываются в обратимом виде:
<br><tt> @<имя переменной> @= <выражение></tt>
<br>либо
<br><tt> @<имя переменной>[<индекс>] @= <выражение></tt>
</p>
<p>
Например:
<br><tt> @max @= @a[@i];</tt>
<br><tt> @i @= @i + 1; // Вместо @i++;</tt>
<br><tt> @a[@i] @= @i;</tt>
<br><tt> @a.b[@z[i][j]] @= @q[i][j];</tt>
</p>
<p>
Для присваиваний, осуществленных в теге <tt><action></tt>
будет сгенирирован код их обращающий.
</p>
<p>
<b>ПРИМЕЧАНИЕ:</b>
Присваивания не переменным модели нельзя записывать указанным образом.
</p>
<p>
<b>ПРИМЕЧАНИЕ:</b>
В одном шаге нельзя одновременно использовать
<tt><action></tt> и <tt><direct></tt> или
<tt><action></tt> и <tt><reverse></tt>.
</p>
<!----------------------------------------------------------------------------->
<a name="SaveLoadDialog"><h1>Использование SaveLoadDialog</h1></a>
<!----------------------------------------------------------------------------->
<p>
<tt>SaveLoadDialog</tt> позволяет унифицировать окна
сохраниения/восстановления состояния визуализатора. При этом он
определяет возможность работы с файлами и буфером обмена и отражает
соответствующие элементы интерфейса.
</p><p>
Для использования <tt>SaveLoadDialog</tt> вы создаете класс
унаследованный от него и определяющий метод <tt>load</tt>. Метод
<tt>load</tt> может возвращать логическое значение или бросать исключение.
Если метод вернул "<tt>true</tt>", то <tt>SaveLoadDialog</tt>
закрывается. Если метод бросил исключение, то сообщения этого исключения
отображается в строке комментария, что позволяет генерировать сообщение
в месте обнаружения ошибки.
</p><p>
Для <tt>SaveLoadDialog</tt> определены следующие свойства:
<table>
<tr>
<td>comment</td>
<td>-<td>
<td>комментарий отображаемый в строке комментария.</td>
</tr><tr>
<td>content</td>
<td>-<td>
<td>текущее содержимое.</td>
</tr><tr>
<td>initialContent</td>
<td>-<td>
<td>исходной содержимое (используется при нажатии на кнопку
"вернуть".
</td>
</tr><tr>
</table>
</p>
<p>
При конфигурации доступны следующие параметры:
<table width="100%" border="1" cellspacing="0">
<col width="250"/>
<tr>
<td class="c">SaveLoadDialog</td>
<td> </td>
</tr><tr>
<td class="c"> -CommentPane-lines</td>
<td>Высота области комментария в строках</td>
</tr><tr>
<td class="c"> -columns</td>
<td>Исходное количество столбцов в области ввода</td>
</tr><tr>
<td class="c"> -rows</td>
<td>Исходное количество строк в области ввода</td>
</tr>
</table>
</p>
<!----------------------------------------------------------------------------->
<a name="SmartTokenizer"><h1>Использование SmartTokenizer</h1></a>
<!----------------------------------------------------------------------------->
<p>
<tt>SmartTokenizer</tt> позволяет в удобном виде разбирать
данные полученые от <tt>SaveLoadDialog</tt>. Он позволяет легко
читать числа (целые и вещественные) и строчки. При этом, выводятся
локализованные сообщения об ошибках. Так же возможна проверка на
окончение ввода. При разборе игнорируются комментарии
(как <tt>/* */</tt> так и <tt>//</tt>). При заключении строки в
кавычки она считывается как одно слово.
</p><p>
<tt>SmartTokenizer</tt> удобно использовать непосредственно в методе
<tt>load</tt> <tt>SaveLoadDialog</tt>, так как при этом практически
не придется делать обработку ошибок.
</p>
<!----------------------------------------------------------------------------->
<a name="Verification"><h1>Автоматическая проверка автоматов</h1></a>
<!----------------------------------------------------------------------------->
<p>
В <em>Vizi</em> входит автоматический проверяльщик автоматов на
правильность обращения.
</p>
<p>
Для использования проверяльщика запустивть build-скрипт
с параметром <tt>check</tt>. При этом, в каталоге
<tt>deploy</tt> будет создан файл вида
<tt>Check<имя визуализатора>.cmd</tt>.
Этот при запуске получившегося файла указыватся размер
(уровень) шага проверки. Проверяльщик прогоняет визуализатор
до всех шагов указанного уровня и проверяет правильность обращения.
</p>
<p>
Для использования проверяльщика в вашу модель данных должны
быть включены значения переменных по умолчанию, задающих
пример на котором производится проверка.
</p>
<p>
Если при проверке вы получаете <tt>NullPointerException</tt>,
то скорее всего это означает, что переменная апплета используется
не только для рисования, что не правильно.
</p>
<!----------------------------------------------------------------------------->
<a name="Variables"><h1>Использование переменных</h1></a>
<!----------------------------------------------------------------------------->
<p>
Начиная с версии <em>0.4</em> введено разделение переменных
на глобальные и локальные, а соответствующая поддержка
введена в <em>Vizi</em>. Объявление переменных в модели данных
поддерживается в целях обеспечения обратной совместимости,
но их использование не рекомендуется.
</p>
<p>
Глобальные переменные определяются в описании
алгоритма (<tt><algorithm></tt>), а не в модели данных
(<tt><data></tt>) как раньше.
Глобальные переменные доступны во всех автоматах, если в них
не объявлена локальная переменная с тем же именем.
</p>
<p>
Локальные переменные определяются в описании автомате
(<tt><auto></tt>), и доступны внутри только этого автомата.
</p>
<p>
Для обращения к переменным используется синтаксис
<br> <tt>@<имя переменной></tt>
<br>На пример:
<br> <tt>@max @= @a[@i];</tt>
<br>при этом осуществляется обратимое присваивание переменной
<tt>max</tt> значения <tt>i</tt>-го элемента массива <tt>a</tt>.
Имя переменной, хранящей модель данных не используется в явном виде,
а подставляется автоматически.
</p>
<p>
Для обращения к локальным переменным автоматов в процедуре
<tt>toString</tt> введен синтаксис
<br> <tt>@<имя автомата>@<имя переменной></tt>
<br>На пример:
<br> <tt>buffer.append(@Main@i);</tt>
<br>при этом осуществляется добавление к буфферу значения
локальной переменной <tt>i</tt> автомата <tt>Main</tt>.
</p>
<p>
Для доступа к переменным модели из кода визуализатора используется
синтаксис
<br> <tt><модель>.<имя переменной></tt>
<br>для глобальных переменных и
<br> <tt><модель>.<имя автомата>_<имя переменной></tt>
<br>для локальных переменных.
На пример:
<br> <tt>data.max = 0;</tt>
<br> <tt>System.out.println(data.Main_i);</tt>
</p>
<!----------------------------------------------------------------------------->
<a name="JavaBeans"><h1>JavaBeans</h1></a>
<!----------------------------------------------------------------------------->
<p>
Начиная с <em>Vizi</em> версии <em>0.4</em> идет миграция
в сторону использования <em>JavaBeans</em>.
Все стандартные компоненты из пакетов <tt>ru.ifmo.vizi.base.ui</tt>
и <tt>ru.ifmo.vizi.base.widgets</tt> со временем будут превращены
в бины. Всвязи с этим будут переименованы некоторые методы
и переработаны некоторые классы.
</p>
<a name="Configuration"><h2>Соглашение о формате конфигурации</h2></a>
<p>С версии <em>0.4</em> вступает в силу новое соглашение о
наименовании конфигурационных параметров, согласованное с
<em>JavaBeans</em>.
</p>
<p>
Полное имя параметра (например <tt>delay-incrementButton-hint</tt>)
состоит из имен отдельных праметров, разделяемых дефисами
(в данном примере <tt>delay</tt>, <tt>incrementButton</tt>
и <tt>hint</tt>). Во всех остальных случаях дефисы не
используются. Имя параметра является правльным
<em>Java</em>-идентификатором и конструируется как имя переменной:
каждое слово, кроме первого начинается с большой буквы, слова
ни чем не разделяются, сокращения пишутся как есть
(например <tt>delay</tt>, <tt>incrementButton</tt>, <tt>myURL</tt>).
</p>
<p>
В ближайшее время все компоненты будут приведы к виду использующему
данную нотацию.
</p>
<a name="BeanConfig"><h2>Конфигурация бина</h2></a>
<p>
У каждого <em>JavaBean</em>а есть набор свойств. Для каждого
свойства определены <em>getter</em> и/или <em>setter</em>.
<em>Getter</em> имеет имя <tt>get<имя свойства></tt>,
а <em>setter</em> — <tt>set<имя свойства></tt>.
Например для свойства <tt>font</tt> они называются <tt>getFont</tt>
и <tt>setFont</tt> соответственно.
</p>
<p>
Свойства бывают простыми и составными, в зависимости от типа.
Простые свойства это все простые типы и типы <tt>Color</tt>
и <tt>String</tt> (значения эти типов можно записать одной строкой).
Составные свойства, это все остальные совйства, например типов
<tt>Button</tt> и <tt>Font</tt>.
</p>
<p>
Конфигурация бина является набором значений его свойств.
Указанные значения устанавливаются с помощью <em>setter</em>ов.
Соответсвенно смысл свойства можно узнать, прочитав описание
соотвествующего <em>setter</em>а. Просмотрев все <em>setter</em>ы
можно узнать все конфигурируемые свойства бина.
</p>
<!----------------------------------------------------------------------------->
<a name="Debug"><h1>Отладка визуализатора</h1></a>
<!----------------------------------------------------------------------------->
<p>
Отладка XML-описания визуализатора состоит из двух этапов:
<ol>
<li>отладка визуализируемой программы;</li>
<li>отладка сгенерированной системы автоматов.</li>
</ol>
На первом этапе осуществляется поиск ошибок переноса
визуализируемой программы в XML-описание, а на втором этапе
— отладка автоматически построенной программы визуализации.
</p>
<a name="Debug.source"><h2>Отладка визуализируемой программы</h2></a>
<p>
Для упрощения отладки визуализируемой программы предназначена
цель <tt>debug-source</tt>, определенная в <em>build</em>-сценарии,
которая строит реализацию визуализируемой программы, без
использования конечных автоматов.
</p><p>
Для каждого автомата (тег <tt><auto></tt>) создается
процедура с именем соответсвующим идентификатору автомата.
Элементы <tt>if</tt> и <tt>while</tt> преобразуются в
соответствующий операторы, а <tt>step</tt> и <tt>call-auto</tt>
в части кода и вызовы процедур соответственно.
</p><p>
В полученном исходный код переносятся комментарии из XML-описания.
Сгенерированный код помещается в файл с именем указанным в
XML-описании с добавленным суффиксом <tt>Debug</tt>.
Полученный исходный код может отлаживаться с использованием
любого программного инструмента.
</p>
<a name="Debug.check"><h2>Отладка системы автоматов</h2></a>
<p>
Отладка сгенерированной системы автоматов производится при помощи
валидатора. Для его использования служит цель <tt>debug-check</tt>,
определенная в <em>build</em>-сценарии. Она создает командный файл
служащий для запуска валидатора и помещает его в каталок файлов
визулизатора.
</p><p>
Валидатор осуществляет последовательную прогонку визуализатора на
все большее количество шагов и осуществляет проверку правильности
обращения на обратном проходе. При этом сравниваются значения
выданные процедурой преобразования состояния автомата в строку
(<tt>toString</tt>). При неравенстве строк на соответствующих
шагах выдается сообщение об ошибке.
</p><p>
При запуске валидатор выводит номер текущего шага и комментарий к
нему в стандартный поток вывода. При обнаружении ошибки в
стандартный поток вывода выдается отладочная информация:
<ul>
<li>номер шага, на котором произошла ошибка;
<li>результат функции <tt>toString</tt> при обратном проходе;
<li>результат функции <tt>toString</tt> при прямом проходе;
<li>результат функции <tt>toString</tt> для шага, после
возвращения от которого произошла ошибка;
<li>результат функции <tt>toString</tt> для шага,
предшествовавшего ошибке (при обратном проходе,
т.е. шаг с номером на единицу больше).
</ul>
При этом валидатор завершается кодом возврата 1, в отличие от
нормального завершения, когда код возврата равен 0.
</p><p>
Для вывода отладочной информации используется расширенная функция
<tt>toString</tt>, которая дополнительно выдает стек вызовов
автоматов для шага и стек в котором сохраняются значения для
обращения. При этом в функции <tt>toString</tt>, определенной в
XML-описании для облегчения отладки имеет смысл выводить значения
как можно большего количества переменных.
</p><p>
При запуске валидатора ему можно передать до двух параметров.
Первый из них означает шаги с каким уровнем проверять
(по умолчанию <tt>-1</tt>), а второй — с какого шага начинать
проверку (по умолчанию 0). Таким образом проверка может
осуществляется следующим образом: сначала быстрая проверка на
больших шагах, затем, при обнаружении ошибка локализуется с
использованием маленьких шагов.
</p>
<!----------------------------------------------------------------------------->
<a name="ImportantNotes"><h1>Важные замечания</h1></a>
<!----------------------------------------------------------------------------->
<ol>
<li>
Обращение к экземпляру апплета должно происходить только из
кода рисования (тега <tt><draw></tt>).
</li><li>
Все стили фигур (<tt>ShapeStyle</tt>) нужно получать из
конфигурации, а не пытаться создать в визуализаторе.
</li><li>
Присваивания не переменным модели нельзя записывать в обратимом
виде (см. <a href="#AutoReverse"><em>Автоматическое обращение шагов типа step</em></a>).
</li><li>
В одном шаге нельзя одновременно использовать
<tt><action></tt> и <tt><direct></tt> или
<tt><action></tt> и <tt><reverse></tt>
(см. <a href="#AutoReverse"><em>Автоматическое обращение шагов типа step</em></a>).
</li>
</ol>
</body>
</html>
About
Farach-Colton, Bender algorithm vizualizer
Resources
Stars
Watchers
Forks
Releases
No releases published
Packages 0
No packages published