РВБ лого Последнее обновление: 10.08.2016
Русская виртуальная библиотека

Графический интерфейс утилиты xMarkup. Руководство пользователя

Содержание

1. Общая информация

Утилита xMarkup предназначена для выполнения процедур строковых преобразований в множестве текстовых файлов (смотри Руководство пользователя). Ядро утилиты реализовано в виде консольного приложения MS Windows 32bit и написано на языке Icon (в настоящее время используется более прогрессивный вариант развития этого языка, Unicon).

Так как использование командной строки имеет очевидные неудобства, впоследствие был разработан графический интерфейс, который максимально упрощает и делает наглядным весь процесс работы с утилитой. Кроме того в графический интерфейс были добавлены многие другие полезные функции. Графический интерфейс первоначально был разработан в среде Delphi 7. Осенью 2012 графический интерфейс был портирован в открытую среду разработки Lazarus. Благодаря этому в GUI появились поддержка UTF-8 и удобный механизм локализации. Более того, появилась возможность создания кросс-платформенного GUI с поддержкой Windows, Linux и Mac OS.

Интегрирование с внешним текстовым редактором Notepad++ обеспечивает пользователя удобной средой разработки (IDE), которая позволяет редактировать файл правил обработки с подсветкой синтаксиса и использованием опции авто-завершения набираемого текста. При желании вместо Notepad++ можно использовать любой другой аналогичный редактор. Например, jEdit или WinPad XP (в последенне время появились лругие, еще более удобные, варианты интеграции: Geany, SynWrite, Textadept).

Реализована интеграция с внешней программой сравнения файлов WinMerge, которая позволяет визуально анализировать изменения, сделанные в результате обработки исходных файлов. При желании вместо WinMerge можно использовать любую другую аналогичную программу. Например, KDiff3.

Реализована опция проверки валидности заданных процедурных макросов, что позволяет значительно ускорить и облегчить процесс их отладки.

Реализована возможность копирования экранного вывода утилиты в выходной файл.

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

1.1 Благодарности

Разработка графического интерфейса осуществлялось в рамках проекта МНТЦ #3361р. Участие в этом проекте оказалось возможным благодаря поддержке Владимира Литвинова (litvinov@snezhinsk.ru), технического редактора Русской Виртуальной Библиотеки.

В составе графического интерфейса использована компонента TmFileScan, разработанная Mats Asplund, MASoft. С помощью этой прекрасной компоненты реализован режим поиска исходных файлов.

1.2 История изменений

Версия 2.0, апрель 2007

Выпущена начальная версия графического интерфейса утилиты. Для согласования с номером версии консольного ядра ей присвоен номер 2.0

Версия 2.0.1, июль 2007

Исключена операция сохранения файла параметров при включенной опции автосохранения, если он на самом деле не изменялся.

Версия 2.1.0, октябрь 2007

Добавлена возможность задания оформления консольных и рабочих окон на вкладке Установки.

Версия 2.1.1, апрель 2008

Изменения, связанные с расширением функциональности консольного ядра утилиты:

Версия 2.1.2, май 2008

Изменения, связанные с фиксацией ошибок в консольном ядре.

Версия 2.1.3, сентябрь 2008

Простая алфавитная сортировка списка обрабатываемых файлов заменена сортировкой с учетом иерархии путей. В верх списка обрабатываемых файлов добавлена панель, нажатие на которую изменяет порядок сортировки.

Версия 2.1.4, январь 2009

Восстановлен режим сохранения выходных файлов с добавлением к их имени префикса "xm$". На закладке "Помощь" добавлена ссылка к домашней страничке загрузки программы.

Версия 2.1.5, апрель 2010

Исправлены незначительные шерохотоватости интерфейса. Добавлена функциональность автоматической проверки обновлений программы при запуске (см.закладку "Установки"). На закладке "Помощь" добавлена ссылка проверки наличия обновления программы.

Версия 2.1.6, август 2010

Версия 2.1.7, январь 2011

Версия 2.1.8, декабрь 2011

Версия 3.0, май 2012

Исправлены незначительные ошибки и внесены некоторые улучшения:

Версия 3.2, ноябрь 2012

В октябре планировался выпуск версии 3.1, который был отложен из-за многочисленных изменений. В итоге появилась значительно переработанная версия 3.2.

Версия 3.6, июнь 2015

Версия 4.0, август 2016

2. Как начать?

Процесс работы с графическим интерфейсом утилиты xMarkup заключается в следующей последовательности действий:

При этом пользователь может всегда быть спокойным насчет оригиналов исходных файлов - утилита НИКОГДА их не изменяет! Результирующие файлы копируются в заданную выходную папку или создаются рядом с оригиналами, но с префиксом "xm$" в имени. По умолчанию установлен режим, в котором выходные файлы вообще не создаются.

3. Описание интерфейса пользователя

Графический интерфейс утилиты xMarkup представляет собой главное окно, имеющее закладки для перехода на различные функциональные страницы приложения. Ниже приводится описание этих страниц.

4. Функциональные страницы приложения

4.1 Исходные файлы

При старте приложения эта страница открывается первой. На данной странице формируется список исходных файлов, которые требуется обработать.

page Source Files

Страница содержит следующие компоненты:

  1. окно комби-списка, в котором задается требуемая маска поиска файлов;
  2. флажок, задающий рекурсивный поиск файлов во всех вложенных папках;
  3. окно, содержащее список исходных файлов для обработки;
  4. панель вверху списка файлов для смены направления сортировки;
  5. нижнее черное окно, в котором отображается консольный вывод утилиты (вертикальный размер этого окна может регулироваться пользователем);
  6. кнопку [Найти] для добавления в список файлов, найденных в выбранной папке по текущей маске;
  7. кнопку [Добавить] для ручного добавления файлов в список;
  8. кнопку [Удалить] для удаления из списка выделенных файлов (сами файлы при этом не уничтожаются);
  9. кнопку [Открыть] для открытия выделенного файла списка;
  10. кнопку [Править] для редактирования выделенного файла списка во внешнем текстовом редакторе;
  11. кнопку [Загрузить] для загрузки списка из ранее сохраненного файла;
  12. кнопку [Сохранить] для сохранения текущего списка в файл;
  13. кнопку [Очистить] для очистки текущего списка файлов;
  14. кнопку [Start] для старта обработки текущего списка файлов;
  15. флажок [Режим Отладки], задающий режим отладки при нажатии на кнопку [Start].

Добавление файлов к списку может осуществляться многократно, при этом по умолчанию список автоматически сортируется. Добавление файлов к списку в режиме поиска может быть прервано нажатием клавиши [Esc] или вводом Ctrl-C.

Навигация по списку обрабатываемых файлов и выделение его элементов делается стандартным для Windows образом - с помощью мыши или клавиш. Двойной щелчок мыши по выделенному файлу или нажатие клавиши [Enter] вызывает его открытие. Нажатием клавиши [Del] выделенный файл(ы) удаляются из списка. При нажатии правой кнопки мыши активизируется контекстное меню:

Context Menu

Пункты контекстного меню "Сравнить", "Открыть Результат", "Править Результат" активны только при условии, если при обработке исходного файла был создан выходной файл (результат).

При старте обработки в статусной строке высвечивается прогресс-индикатор с отсчетом затраченного времени и в нижнем окне отображается консольный вывод утилиты (задание его режимов осуществляется на странице Результаты).

xMarkup Processing

Процесс обработки может быть всегда прерван нажатием на кнопку [Stop] или вводом Ctrl-C.

4.2 Установки

На этой странице задаются необходимые установки пользовательского интерфейса.

page Preferences

Страница содержит следующие компоненты:

  1. список [Язык Интерфейса] для задания языка пользовательского интерфейса (русский или английский);
  2. поле [Внешний Текстовый Редактор] для задания пути к внешнему текстовому редактору (по умолчанию Notepad++ или, если он не установлен в системе, то стандартный блокнот);
  3. поле [Внешняя Программа Сравнения Файлов] для задания пути к программе сравнения текстовых файлов (по умолчанию WinMerge);
  4. флажок для задания автоматического сохранения всех параметров текущей сессии (включая список исходных файлов);
  5. флажок для задания автоматической сортировки списка обрабатываемых файлов при добавлении в него новых файлов;
  6. кнопки выбора шрифта и цвета фона рабочих окон;
  7. кнопки выбора шрифта и цвета фона консольных окон;
  8. поле [Конфигурация] для задания имени файла конфигурации. Кнопка [...] справа позволяет загрузить требуемую конфигурацию;
  9. кнопку [Сохранить] для сохранения текущих настроек в заданный конфигурационный файл.

Файлы, которые явно открываются из тела макро-процедур в процессе обработки, например:

procedure initialize
  in := open("infile.txt", "r")
  out := open("outfile.txt", "w")
  ...
  t := get_content("infile.txt")
end

по умолчанию читаются/создаются по пути, заданному папкой размещения файла текущих правил обработки. Т.е. эта папка всегда задает рабочую папку утилиты. Вы можете также использовать относительные пути, которые указываются относительно рабочей папки. Естественно, можно использовать полные пути к файлам, тогда они могут размещаться в любом месте. Сказанное также справедливо для макропределения @read(file).

Следует отметить, что результаты обработки, формирующиеся из исходных файлов, всегда сохраняются в заданной выходной папке (см. следующий раздел).

Файл правил обработки теперь автоматически сохраняется (если в него до этого были внесены изменения) при старте обработки, отладочной компиляции, отладочном прогоне или сборке .exe файла. Это свойство закреплено как фиксированное и поэтому изменению больше не подлежит!

Также теперь при старте программы в асинхронном режиме всегда проверяется наличие обновления на сайте sourceforge.net.

4.3 Результаты

На этой странице задаются опции экранного вывода и параметры сохранения результатов обработки.

page Output

Страница содержит следующие компоненты.

    Опции экранного вывода:

  1. флажок [Сохранить в Файл], задающий копирование экранного вывода в текстовый файл;
  2. текстовое поле для задания имени файла экранного вывода (по умолчанию этот файл создается в рабочей папке);
  3. кнопку [...] для выбора или создания файла экранного вывода;
  4. кнопку [Править] для просмотра файла экранного вывода в окне внешнего редактора;
  5. флажок [Не выводить статистику обработки], задающий подавление вывода списка обработанных файлов и итоговой статистики на экран;
  6. поле [Размер Экранного Буфера] для задания размера буфера окна экранного вывода в строках.

    Параметры сохранения выходных файлов, образующихся в результате обработки исходных файлов:

  1. группа переключателей, задающая режим сохранения результирующих файлов:
  2. - создавать с сохранением исходной структуры папок (сохраняется иерархия папок исходных файлов);
    - сохранять в плоскую выходную папку (иерархия папок исходных файлов не сохраняется);
    - сохранять с префиксом xm$ в имени в исходную папку;
    - перенаправить вывод на экран;
    - не сохранять.
  3. текстовое поле [Выходной Путь], в котором задается путь к выходной папке;
  4. кнопка [...] для выбора или создания требуемой выходной папки;
  5. кнопка [Explore] для открытия выходной папки в Проводнике Windows.

4.4 Правила Обработки

На этой странице задаются правила обработки исходных файлов.

page Markup Rules

Страница содержит следующие компоненты:

  1. поле [Файл скрипта обработки], в котором задается имя файла правил обработки;
  2. кнопку [...] для загрузки ранее сохраненного файла скрипта обработки;
  3. кнопку [Править] для редактирования текущего скрипта обработки в окне внешнего редактора;
  4. кнопку [Сохр.] для сохранения текущего скрипта обработки в заданный файл;
  5. кнопку [Сохр. Как] для сохранения текущего скрипта обработки в файл с другим именем;
  6. кнопку [Создать] для создания нового скрипта обработки;
  7. поле [Кодировка текста] выбора типа обрабатываемых данных: ANSI или UTF-8;
  8. поле [Режим вывода] выбора режима вывода: "Стандартный" или "Графический" (для графических визуализаций);
  9. окно [Заголовок], в котором задаются комментарии к правилам обработки. Вертикальный размер этого окна может регулироваться пользователем;
  10. флажок синхронизации обработки списков начальных и конечных маркеров;
  11. флажок синхронизации обработки списков начальных маркеров и шаблонов преобразований;
  12. таблицу для задания списков начальных и конечных маркеров и шаблонов преобразований;
  13. поле задания шаблона пост-преобразования.

Чтобы добавить новую строку в конец таблицы, нужно нажать Ctrl+Ins. Чтобы удалить выбранную строку из таблицы, нужно нажать Ctrl+Del.

Так редактирование списков маркеров и шаблонов замен в табличной форме может быть неудобным, рекомендуется для этого использовать внешний редактор (см. пункт 5).

При задании кодировки текста UTF-8 файл скрипта обработки сохраняется в формате UTF-8. В этом случае для получения правильных результатов обрабатываемые файлы также должны быть в формате UTF-8. В режиме ANSI файл скрипта обработки сохраняется в системной 1-байтовой кодировке (Windows-1251 для русской локали).

4.5 Опции Обработки

На этой странице задаются различные опции обработки исходных файлов. Назначение данных опций детально описано в руководстве по утилите xMarkup.

page Markup Options

Страница содержит следующие компоненты.

    Параметры внутренних счетчиков утилиты xMarkup:

  1. поле [Нач.Значения] для задания начальных значений счетчиков;
  2. поле [Инкр.Значения] для задания приращений счетчиков;
  3. флажок [Автоинкрементация], задающий автоинкрементацию счетчиков;
  4. комби-список, с помощью которого задается тип счетчиков (относительный или абсолютный).

    Дополнительные опции обработки:

  1. флажок [Добавлять символ newline...], задающий добавление символа новой строки (\n) в конец каждой считываемой строки исходного файла;
  2. флажок [Нечувствительный к регистру поиск], задающий нечувствительный к регистру поиск стартовых и стоповых маркеров;
  3. флажок [Пропускать HTML теги], задающий пропуск при обработке тела HTML тегов;
  4. поле, задающую минимальную длину искомых текстовых элементов (между начальным и конечным маркерами);
  5. флажок [Нетранслируемый режим чтения], задающий потоковый режим чтения для бинарных файлов;
  6. флажок [Нетранслируемый режим записи], задающий потоковый режим записи для бинарных файлов.

4.6 Процедуры

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

page Macros

Страница содержит следующие компоненты:

  1. Окно редактирования исходного текста процедур;
  2. Нижнее окно отладочного вывода (вертикальный размер этого окна может изменяться);
  3. Кнопку [Тест.Компил.] для проверки валидности синстаксиса заданных процедур с помощью Icon-компилятора;
  4. Кнопку [Собрать *.exe] для сборки правил обработки в виде исполнимого *.exe файла.
  5. Кнопку [Удалить *.exe] для удаления существующего *.exe файла правил обработки.
Примечания:
  1. если в теле процедуры содержится директива @include включения текста из внешнего файла, то открыть этот файл на редактирование можно двойным щелчком мыши по строке директивы.
  2. окно редактирования процедур автоматически блокируется, если существует *.exe файл правил обработки;

4.7 Помощь

На этой странице приводятся информация о версии, copyright и ссылки к разделам документации и внешним интернет-ресурсам.

page Macros

Ссылка "Проверить обновление xMarkup" позволяет узнать о наличии доступного обновления утилиты на сайте SourceForge.net.

Ссылка "Версия ядра" выводит список свойств текущей сборки программы (аналог команды xm -version)

Версия ядра

5. Использование внешнего редактора

Утилита xMarkup поддерживает интеграцию с любым внешним редактором, который может использоваться для быстрого просмотра или редактирования обрабатываемых файлов и правил обработки. Если в вашей системе установлен редактор Notepad++, то он используется по умолчанию как внешний редактор. Назначение другого внешнего редактора задается на странице Установки. Смотри документ Использование расширений xMarkup как установить и настроить другие варианты текстовых редакторов.

При загрузке файла правил обработки (тип .par или .xm) в окно редактора Notepad++ автоматически осуществляется подсветка синтаксиса, например:

page Notepad++

При нажатиии комбинации клавиш Ctrl+Space активизируется функция авто-завершения ввода, с помощью которой можно выбрать требуемую синтаксическую конструкцию файла правил - имя макроопределения или функции. При нажатии Ctrl+Space в процессе ввода строки осуществляется автоматический поиск имени конструкции, начинающегося введенной строкой.

При сохранении сделанных изменений и возврате к окну утилиты xMarkup автоматически выводится диалоговое окно, предлагающее перезагрузить текущий файл параметров, чтобы учесть эти изменения:

page Reload

6. Использование внешней программы сравнения файлов

Утилита xMarkup поддерживает интеграцию с внешней программой сравнения файлов, с помощью которой можно визуально сравнивать исходный файл с результатом его обработки. Если в вашей системе установлена программа WinMerge, то она используется по умолчанию как внешняя программа сравнения файлов. Назначение другой внешней программы сравнения файлов задается на странице Установки. При этом нужно иметь ввиду, чтобы данная программа поддерживала следующий синтаксис командной строки запуска:

имя-программы файл-1 файл-2

Для выполнения операции сравнения необходимо после завершения обработки выбрать требуемый исходный файл в списке, нажать правую кнопку мыши и выполнить команду Сравнить. Сравнение возможно только в том случае, если на странице Результаты был задан какой-либо режим создания выходных файлов.

7. Отладка процедур

В этой главе описано как отлаживать процедуры, используемые в правилах обработки.

7.1 Тестовая компиляция

В этом режиме "вылавливаются" грубые синтаксические ошибки с помощью компиляции заданных макросов стандартным Icon-компилятором. При этом следует помнить, что Icon-компилятор может посчитать валидными многие выражения, которые дадут сбой только во время выполнения. Эта особенность вызвана тем обстоятельством, что Icon не использует жестко типизированных переменных и не проверяет существования вызываемых функций и процедур на этапе компиляции.

Режим тестовой компиляции задается нажатием кнопки [Тест.Компил.] в окне [Макросы]. Ниже приведен пример выходного листинга компиляции:

page Test Compile

В данном случае в шестой строке
t := lower(@body
пропущена правая закрывающая скобка из-за чего конструкция "if-then" в следующей строке была также не распознана.

7.2 Обработка в режиме отладки

В этом режиме можно проследить по шагам реальный процесс обработки исходных файлов. Чтобы попасть в режим отладки нужно выбрать опцию [Режим Отладки] в окне [Результаты] и запустить обработку:

page Debug Processing

После каждого шага обработки (т.е. поиска и трансформации очередного элемента текста) утилита делает останов, ожидая ввода от пользователя. В консольном окне требуется ввести номер варианта ответа (1-3) и нажать возврат каретки:

Завершить отладку также можно нажатием на кнопку [Stop] или вводом управляющего символа Ctrl-C.

8. Сборка .exe файла

В обычном режиме скрипт правил обработки, содержащий макро-процедуры, выполняется консольной компонентой утилиты (xm.exe) в режиме интерпретации. Естественно, это значительно замедляет процесс. Начиная с версии 2.1.6 утилиты появилась возможность собрать правила обработки в виде исполнимого .exe файла. При наличии такого файла вся обработка осуществляется именно этим файлом. Это может дать очень значительный прирост производительности - в 10 и более раз!

page Сборка .exe

Исполнимый .exe файл правил обработки создается в папке bin установки утилиты. Имя этого файла совпадает с именем исходных правил обработки (например, list_tags.par.exe для файла правил list_tags.par). При загрузке обычного файла правил обработки утилита всегда проверяет наличие соответствующего .exe файла. Если такой файл существует, то окно редактирования макросов автоматически блокируется, чтобы исключить возможное изменение макро-процедур. Также блокируется кнопка [Править] редактирования правил обработки во внешнем редакторе. Чтобы внести изменения в макро-процедуры в этом случае необходимо сначала удалить исполнимый .exe файл (кнопка "Удалить .exe").

Если файл правил обработки не включает никаких процедурных макросов, то создание .exe файла в этом случае абсолютно избыточно и кнопка "Собрать .exe" заблокирована.

8.1 Особенности новейших версий Windows

В новейших версиях Windows, начиная с Windows Vista, реализован так называемый механизм контроля прав пользователя (UAC). В этом случае, даже являясь монопольным пользователем системы с административными правами, вы по умолчанию не имеете прав на выполнение некоторых операций, например, модификации данных в папке Program Files или папке установки Windows. Т.е. даже администратор системы как-бы понижен до уровня обычного пользователя. Для выполнения защищенных операций требуется явный запрос на эскалацию полномочий. На уровне системы это выглядит в виде всплывающего окна, в котором предлагается выполнить операцию от имени администратора (если соответсвующие права у вас есть). Однако запущенные вами приложения по умолчанию всегда выполняются без эскалации прав и в них автоматически блокируется выполнение защищенных операций. Поэтому, если вы, например, попытаетесь в приложении изменить или создать файл в папке Program Files, то у вас ничего не получится. Чтобы избежать такой ситуации в Windows Vista/7/8/10 папка установки программы должна размещаться вне системных папок \Program Files или \Windows. Иначе сборка *.exe файла или тестовая компиляция скрипта обработки никогда не будут работать. Также программа не сможет сохранить файл конфигурации при ее закрытии.

Ниже показано как можно обойти ограничения UAC, хотя это не особенно рекомендуется.

Являясь администратором, вы всегда можете запустить любое приложение с эскалацией прав доступа. Для этого необходимо кликнуть правой кнопкой мыши по ярлыку приложения на рабочем столе и выбрать в меню команду "Запуск от имени администратора" ("Run as administrator").

page Run as administrator

Можно закрепить свойство запуска приложения от имени администратора. Для этого необходимо измененить расширенные свойства ярлыка запуска приложения. Кликните правой кнопкой мыши по ярлыку и выберите пункт "Свойства" ("Properties"), затем в открывшемся окне свойств нажмите кнопку "Дополнительно" ("Advanced") и отметьте флажок "Запуск от имени администратора" ("Run as administrator"). Чтобы зафиксировать изменения нажмите ОК.

page Run as administrator

© Сергей Логичев, 1999-2016
РВБ