31.01.08
Документация
Пояснения предназначены в первую очередь для программистов, которые собираются изменять MyRewriter. Но и просто пользователям будет полезно почитать.
Это костяк документации, ещё не до конца наполненный содержимым. Впоследствии почти вся новая техническая информация по MyRewriter'у будет добавляться именно сюда.
Папка functions. Файлы с функциями, используемыми скриптом. Все .php файлы, положенные в неё, автоматически подключаются при работе скрипта. Стараемся придерживаться правила: "одна функция - один файл". Имя функции совпадает с названием файла, если для разделения слов вместо нижнего подчёркивания использовать заглавные буквы. Например, в файле my_cool_function.php должна быть функция MyCoolFunction().
Папка interfaces. Интерфейсы - удобная фишечка MyRewriter'а. Если говорить грубо, есть ядро - функции, занимающиеся синонимизированием, а есть интерфейсы - скрипты, занимающиеся передачей текстов в ядро. И это сильно упрощает жизнь тем, кто хочет получать/отправлять данные нестандартным способом.
Поясню на примере. Вот код файла start_synonymization.php интерфейса standart_browser. Синонимизированный текст вводится в форму в броузере, выводится тоже прямо в броузер.
(Заезжает под правую колонку, знаю. Ну и ладно. Тем, кто не сможет скопировать, код явно не нужен :-) )
Чтобы выбрать для работы какой-то интерфейс, имя его папки нужно написать в файле service/config.php в константу CURRENT_INTERFACE.
Папка service. Место, где живут скрипты, подготавливающие MyRewriter к работе. Там же настройки.
Папка templates. Если тебе придёт в голову изменить оформление MyRewriter'а (правильнее сказать - добавить к MyRewriter'у оформление :-) ), то следует создать в templates папку с именем шаблона и изменить на это имя значение константы CURRENT_TEMPLATE в service/config.php. В каждом шаблоне основной файл стилей должен называться style.css, тогда он будет автоматически подключаться к html-коду.
Файл .htaccess. Предлагает PHP не использовать Волшебные Кавычки (опция PHP, цель которой - портить кровь программистам) для скриптов этой папки.
Файл add.php. Используется для добавления синонимов в базу (ну и удаления из базы).
Файл check.php. Проверялка конфигурации хоста, используется сама по себе, для работы или установки MyRewriter'а больше не нужна. check.php не проверяет версию PHP - мы ещё не успели тщательно разобраться, что подходит, а что - нет. Но теоретически проблем быть не должно.
Файл index.php. Собственно, при запуске этого скрипта и будет происходить синонимизация.
Файл install.php. Инсталлятор. Создаст нужные таблицы в базе данных, импортирует синонимы из файла syns.txt.
Файл syns.txt. Синонимы. Вручную отобранные 1200 с лишним пар фраза|синоним. Как показывает практика, этого достаточно, чтобы заменять где-то каждое двенадцатое слово без значительной потери читаемости. При желании можно скормить MyRewriter'у какую-то из бесплатных мусорных баз синонимов, но текст будет годен только на дорвеи.
Это костяк документации, ещё не до конца наполненный содержимым. Впоследствии почти вся новая техническая информация по MyRewriter'у будет добавляться именно сюда.
Папка functions. Файлы с функциями, используемыми скриптом. Все .php файлы, положенные в неё, автоматически подключаются при работе скрипта. Стараемся придерживаться правила: "одна функция - один файл". Имя функции совпадает с названием файла, если для разделения слов вместо нижнего подчёркивания использовать заглавные буквы. Например, в файле my_cool_function.php должна быть функция MyCoolFunction().
Файл add_synonyms_to_database.php. Получает текст в формате
и добавляет его в базу. Если фраза (левая часть) уже есть в базе, то она не добавляется. Выводит статистику: сколько слов было, сколько и каких добавили, сколько и каких не добавили.
Файл begin_html.php. Выводит в броузер шапку из HTML-тегов. К html подключается файл style.css текущего шаблона.
Файл check_host.php. Вызывается при каждом запуске скрипта, останавливает работу, если обнаруживает, что настройки хоста не подходят.
Файл connect_to_database.php. Подключается к базе данных (настройки берутся из service/config.php), проверяет, есть ли в базе хоть что-то. Если нет и это не установка (нет константы IT_IS_INSTALLATION), то выводится ошибка и работа скрипта прерывается.
Файл count_all_synonyms.php. Подсчитывает общее число синонимов в базе.
Файл delete_all_synonyms.php. Удаляет из базы все синонимы.
Файл delete_blank_lines.php. Получает текст и удаляет из него все пустые строки. Используется при добавлении синонимов в базу.
Файл delete_comments.php. Удаляет из текста комментарии (всё от "#" или "//" до конца строки). Используется при добавлении синонимов в базу. Синонимы удобно до добавления хранить в текстовом файле, а в нём иногда полезно ставить комментарии. MyRewriter не споткнётся на них.
Файл delete_too_long_lines.php. Принимает строки в формате
и удаляет те, где либо фраза либо синоним длиннее 255 символов. Это лучше, чем случай, когда они записываются в базу не целиком. При этом об отброшенных строках выводятся сообщения типа info.
Файл end_html.php. Просто выводит </body> и </html>
Файл first_letter_of_each_sentence_to_upper.php. При синонимизации слова, написанные с большой буквы, заменяются на синонимы с маленькой. Функция пытается исправить эту проблему - делает первую букву слова в начале предложения заглавной. Находит первые слова предложений и передаёт их в FirstLetterOfStringToUpper() (см. ниже).
Файл first_letter_of_string_to_upper.php. Эта функция используется предыдущей. Принимает строку и делает её первую букву заглавной.
Файл is_debug_mode.php. Проверяет, передан ли в урле параметр d == 1. Например http://localhost/index.php?d=1. Используется в service/some_service_work_after_functions.php, чтобы проверить, нужно ли включать режим отладки.
Файл prepare_synonyms_and_add_them.php. Подготавливает синонимы к добавлению в базу (удаляет пустые строки, комментарии...) и добавляет их (передаёт в AddSynonymsToDatabase()).
Файл prepare_text_and_synonymize_it.php. Подготавливает текст к синонимизации (заменяет ё на е, конвертирует переводы строк в unix-style...) и передаёт его в SynonymizeText().
Файл show_synonyms_adding_form.php. Выводит форму для добавления новых синонимов. Отправка по Ctrl + Enter.
Файл start_counter.php. Запускает счётчик - возвращает текущее время с микросекундами как строку. Вызывается обычно как
Файл stop_counter.php. Возвращает разницу между полученным временем и текущим. Стандартно используется как
Файл stripslashes_for_array.php. Принимает массив, рекурсивно обходит его и применяет stripslashes() ко всем элементам. Используется в самом начале, в service/some_service_work_after_functions.php, чтобы очистить от слешей $_GET, $_POST, $_COOKIE и $_REQUEST, если включена magic_quotes_gpc.
Файл synonymize_phrase.php. Получает слово и синоним. Собирает некоторую статистику, возвращает синоним. Если включена SHOW_TIPS, то с всплывающей подсказкой, где текст подсказки - бывшее слово.
Файл synonymize_text.php. Синонимизирует полученный текст.
Файл write_message.php. Выводит сообщение. В зависимости типа отображает его по-разному и может выполнять какие-то специальные действия. Например, если тип error, то отправляет письмо-уведомление на админский ящик (если разрешено) и заканчивает работу скрипта.
крокодил|аллигатор
аллигатор|крокодил
красивые цветы|цветочки
и добавляет его в базу. Если фраза (левая часть) уже есть в базе, то она не добавляется. Выводит статистику: сколько слов было, сколько и каких добавили, сколько и каких не добавили.
Файл begin_html.php. Выводит в броузер шапку из HTML-тегов. К html подключается файл style.css текущего шаблона.
Файл check_host.php. Вызывается при каждом запуске скрипта, останавливает работу, если обнаруживает, что настройки хоста не подходят.
Файл connect_to_database.php. Подключается к базе данных (настройки берутся из service/config.php), проверяет, есть ли в базе хоть что-то. Если нет и это не установка (нет константы IT_IS_INSTALLATION), то выводится ошибка и работа скрипта прерывается.
Файл count_all_synonyms.php. Подсчитывает общее число синонимов в базе.
Файл delete_all_synonyms.php. Удаляет из базы все синонимы.
Файл delete_blank_lines.php. Получает текст и удаляет из него все пустые строки. Используется при добавлении синонимов в базу.
Файл delete_comments.php. Удаляет из текста комментарии (всё от "#" или "//" до конца строки). Используется при добавлении синонимов в базу. Синонимы удобно до добавления хранить в текстовом файле, а в нём иногда полезно ставить комментарии. MyRewriter не споткнётся на них.
Файл delete_too_long_lines.php. Принимает строки в формате
крокодил|аллигатор
аллигатор|крокодил
красивые цветы|цветочки
и удаляет те, где либо фраза либо синоним длиннее 255 символов. Это лучше, чем случай, когда они записываются в базу не целиком. При этом об отброшенных строках выводятся сообщения типа info.
Файл end_html.php. Просто выводит </body> и </html>
Файл first_letter_of_each_sentence_to_upper.php. При синонимизации слова, написанные с большой буквы, заменяются на синонимы с маленькой. Функция пытается исправить эту проблему - делает первую букву слова в начале предложения заглавной. Находит первые слова предложений и передаёт их в FirstLetterOfStringToUpper() (см. ниже).
Файл first_letter_of_string_to_upper.php. Эта функция используется предыдущей. Принимает строку и делает её первую букву заглавной.
Файл is_debug_mode.php. Проверяет, передан ли в урле параметр d == 1. Например http://localhost/index.php?d=1. Используется в service/some_service_work_after_functions.php, чтобы проверить, нужно ли включать режим отладки.
Файл prepare_synonyms_and_add_them.php. Подготавливает синонимы к добавлению в базу (удаляет пустые строки, комментарии...) и добавляет их (передаёт в AddSynonymsToDatabase()).
Файл prepare_text_and_synonymize_it.php. Подготавливает текст к синонимизации (заменяет ё на е, конвертирует переводы строк в unix-style...) и передаёт его в SynonymizeText().
Файл show_synonyms_adding_form.php. Выводит форму для добавления новых синонимов. Отправка по Ctrl + Enter.
Файл start_counter.php. Запускает счётчик - возвращает текущее время с микросекундами как строку. Вызывается обычно как
$GLOBALS["CounterStartTime"] = StartCounter();Файл stop_counter.php. Возвращает разницу между полученным временем и текущим. Стандартно используется как
WriteMessage("Время работы кода в счётчике", StopCounter($GLOBALS["CounterStartTime"]), "info");Файл stripslashes_for_array.php. Принимает массив, рекурсивно обходит его и применяет stripslashes() ко всем элементам. Используется в самом начале, в service/some_service_work_after_functions.php, чтобы очистить от слешей $_GET, $_POST, $_COOKIE и $_REQUEST, если включена magic_quotes_gpc.
Файл synonymize_phrase.php. Получает слово и синоним. Собирает некоторую статистику, возвращает синоним. Если включена SHOW_TIPS, то с всплывающей подсказкой, где текст подсказки - бывшее слово.
Файл synonymize_text.php. Синонимизирует полученный текст.
Файл write_message.php. Выводит сообщение. В зависимости типа отображает его по-разному и может выполнять какие-то специальные действия. Например, если тип error, то отправляет письмо-уведомление на админский ящик (если разрешено) и заканчивает работу скрипта.
Папка interfaces. Интерфейсы - удобная фишечка MyRewriter'а. Если говорить грубо, есть ядро - функции, занимающиеся синонимизированием, а есть интерфейсы - скрипты, занимающиеся передачей текстов в ядро. И это сильно упрощает жизнь тем, кто хочет получать/отправлять данные нестандартным способом.
Поясню на примере. Вот код файла start_synonymization.php интерфейса standart_browser. Синонимизированный текст вводится в форму в броузере, выводится тоже прямо в броузер.
(Заезжает под правую колонку, знаю. Ну и ладно. Тем, кто не сможет скопировать, код явно не нужен :-) )
<?php
/*
MyRewriter 1.2
http://shop.all4wm.net/myrewriter/
*/
//Если через POST передан текст, то синонимизирует его, иначе показывает форму для ввода текста.
function StartSynonymization ()
{
//Если форма не отправлена, то не надо ничего синонимизировать. Покажем форму
if (!isset($_POST["text"]))
{
ShowTextSynonymizingForm();
return;
}
//Если форма отправлена
$CurrentContent = $_POST["text"];
WriteMessage("Необработанный текст, который передали в форму:", $CurrentContent, "debug");
//Синонимизируем и выводим прямо в броузер, заменяя переводы строк на <br />.
$CurrentContent = PrepareTextAndSynonymizeIt($CurrentContent);
echo nl2br($CurrentContent);
WriteMessage("Всё синонимизировалось", "<a href='".VIRTUAL_PATH."'>Ещё ></a>", "imp_info");
}
?>
Большая часть - мишура и комментарии, три важные строки я подсветил красным. Первая - получаем текст. Вторая - синонимизируем. Третья - отдаём пользователю. Очень просто. Достаточно заменить echo() на mail(), чтобы получить новый интерфейс, который отправляет синонимизированные тексты на почту. Интеграция с твоим скриптом, получающим откуда-нибудь текст, займёт совсем немного времени. Конечно, может понадобиться ещё поправить функции сбора/показа статистики, но это легко и необязательно.Чтобы выбрать для работы какой-то интерфейс, имя его папки нужно написать в файле service/config.php в константу CURRENT_INTERFACE.
Папка standart_browser. Стандартный интерфейс, который принимает тексты, переданные через броузер (введённые в текстовое поле) и отдаёт синонимизированные тоже прямо в броузер.
Папка functions. Файлы с функциями, используемыми интерфейсом. Все .php файлы, положенные в неё, автоматически подключаются при работе скрипта, если выбран этот интерфейс.
Файл gather_stats.php. Собирает статистику и записывает её в базу. Всегда вызывается при добавлении синонимов в базу (это достаточно редкая операция и можно позволить себе потратить время на сбор статистики) и собственно при работе скрипта, если включена опция STATS_ONLINE_GATHERING. Если статистика не нужна, можно её выключить и чуть-чуть уменьшить время работы. Своя собственная у каждого интерфейса.
Файл show_synonymizing_stats.php. Показывает статистику синонимизации. Не собирает статистику, но просто берёт значения из базы. Разделение сбора-отображения на две функции даёт определённую дополнительную гибкость.
Файл show_text_synonymizing_form.php. Отдаёт в броузер форму для ввода текста, который будет синонимизироваться.
Файл start_synonymization.php. Непосредственно синонимизация. Этот файл свой в каждом интерфейсе, его задача - взять откуда-то текст (в данном случае текст вводят в броузер), передать его в PrepareTextAndSynonymizeIt() и выдать (в этом интерфейсе - прямо в броузер) готовый результат. Вызывается из index.php после подключения всего нужного.
Папка service. Настройки, служебная работа для этого интерфейса. Тут есть несколько пустых файлов - в них было нечего написать. Они не удалены, это позволит избежать путаницы с именами при изменении интерфейса.
Файл config.php. Тут теоретически должны быть настройки интерфейса. Но настроек нету, поэтому файл пустой.
Файл include_all_functions.php. Подключаем все файлы с расширением .php из папки functions этого интерфейса. Подключаются функции не всегда, но только в случае, если интерфейс активен.
Файл prepare_for_work.php. Подготавливает интерфейс к работе - подключает сервисные скрипты, лежащие в этой папке.
Файл some_service_work_after_functions.php. Предназначен для каких-то сервисных действий интерфейса, вызывается после подключения функций. Пустой.
Файл some_service_work_before_functions.php. Аналогично предыдущему, вызывается до функций. Тоже пустой.
Папка standart_files. Стандартный интерфейс, тексты берутся из файлов, в файлы же записываются. Кодировка обязательно должна быть UTF-8.
Папка functions. Файлы с функциями, используемыми интерфейсом. Все .php файлы, положенные в неё, автоматически подключаются при работе скрипта, если выбран этот интерфейс.
Файл gather_stats.php. Собирает статистику и записывает её в базу. Всегда вызывается при добавлении синонимов в базу (это достаточно редкая операция и можно позволить себе потратить время на сбор статистики) и собственно при работе скрипта, если включена опция STATS_ONLINE_GATHERING. Если статистика не нужна, можно её выключить и чуть-чуть уменьшить время работы. Своя собственная у каждого интерфейса.
Файл show_synonymizing_stats.php. Показывает статистику синонимизации. Не собирает статистику, но просто берёт значения из базы. Разделение сбора-отображения на две функции даёт определённую дополнительную гибкость.
Файл show_text_synonymizing_form.php. Отдаёт в броузер форму для ввода текста, который будет синонимизироваться.
Файл start_synonymization.php. Непосредственно синонимизация. Этот файл свой в каждом интерфейсе, его задача - взять откуда-то текст (в данном случае текст вводят в броузер), передать его в PrepareTextAndSynonymizeIt() и выдать (в этом интерфейсе - прямо в броузер) готовый результат. Вызывается из index.php после подключения всего нужного.
Папка service. Настройки, служебная работа для этого интерфейса. Тут есть несколько пустых файлов - в них было нечего написать. Они не удалены, это позволит избежать путаницы с именами при изменении интерфейса.
Файл config.php. Тут теоретически должны быть настройки интерфейса. Но настроек нету, поэтому файл пустой.
Файл include_all_functions.php. Подключаем все файлы с расширением .php из папки functions этого интерфейса. Подключаются функции не всегда, но только в случае, если интерфейс активен.
Файл prepare_for_work.php. Подготавливает интерфейс к работе - подключает сервисные скрипты, лежащие в этой папке.
Файл some_service_work_after_functions.php. Предназначен для каких-то сервисных действий интерфейса, вызывается после подключения функций. Пустой.
Файл some_service_work_before_functions.php. Аналогично предыдущему, вызывается до функций. Тоже пустой.
Папка standart_files. Стандартный интерфейс, тексты берутся из файлов, в файлы же записываются. Кодировка обязательно должна быть UTF-8.
(этот кусок документации ещё не написан)
Папка service. Место, где живут скрипты, подготавливающие MyRewriter к работе. Там же настройки.
Файл config.php. Все доступные настройки скрипта (у интерфейсов свои настройки) находятся именно здесь.
Файл include_all_functions.php. Подключает все файлы с расширением .php из папки functions.
Файл prepare_for_work.php. Подготавливает MyRewriter к работе, должен подключаться всегда в самом начале. Тут чтение настроек, подключение всего необходимого, запуск счётчика...
Файл some_service_work_after_functions.php. Кое-какие служебные действия, выполняются после подключения всех фукций. Некоторые проверки конфигурации хоста, соединение с БД.
Файл some_service_work_before_functions.php. Тоже сервисная работа, но выполняется до подключения всех функций. Сейчас там установка множества констант с путями до различных частей скрипта - без этого неудобно подключать функции. Причём пути сейчас определяются абсолютно ужасными способами, надо не забыть исправить.
Файл include_all_functions.php. Подключает все файлы с расширением .php из папки functions.
Файл prepare_for_work.php. Подготавливает MyRewriter к работе, должен подключаться всегда в самом начале. Тут чтение настроек, подключение всего необходимого, запуск счётчика...
Файл some_service_work_after_functions.php. Кое-какие служебные действия, выполняются после подключения всех фукций. Некоторые проверки конфигурации хоста, соединение с БД.
Файл some_service_work_before_functions.php. Тоже сервисная работа, но выполняется до подключения всех функций. Сейчас там установка множества констант с путями до различных частей скрипта - без этого неудобно подключать функции. Причём пути сейчас определяются абсолютно ужасными способами, надо не забыть исправить.
Папка templates. Если тебе придёт в голову изменить оформление MyRewriter'а (правильнее сказать - добавить к MyRewriter'у оформление :-) ), то следует создать в templates папку с именем шаблона и изменить на это имя значение константы CURRENT_TEMPLATE в service/config.php. В каждом шаблоне основной файл стилей должен называться style.css, тогда он будет автоматически подключаться к html-коду.
Папка first. Там живёт единственный идущий в комплекте файл стилей.
Файл style.css. Стили для разных сообщений и для всплывающих подсказок.
Файл .htaccess. Предлагает PHP не использовать Волшебные Кавычки (опция PHP, цель которой - портить кровь программистам) для скриптов этой папки.
Файл add.php. Используется для добавления синонимов в базу (ну и удаления из базы).
Файл check.php. Проверялка конфигурации хоста, используется сама по себе, для работы или установки MyRewriter'а больше не нужна. check.php не проверяет версию PHP - мы ещё не успели тщательно разобраться, что подходит, а что - нет. Но теоретически проблем быть не должно.
Файл index.php. Собственно, при запуске этого скрипта и будет происходить синонимизация.
Файл install.php. Инсталлятор. Создаст нужные таблицы в базе данных, импортирует синонимы из файла syns.txt.
Файл syns.txt. Синонимы. Вручную отобранные 1200 с лишним пар фраза|синоним. Как показывает практика, этого достаточно, чтобы заменять где-то каждое двенадцатое слово без значительной потери читаемости. При желании можно скормить MyRewriter'у какую-то из бесплатных мусорных баз синонимов, но текст будет годен только на дорвеи.