Требования

• [обязательно] PHP 5.6 (на PHP 7 тоже заведётся, но совместимость с 5.6 обязательна) с предустановленной поддержкой mbstring. Требуется только интерпретатор языка; установленный web-сервер (apache, lighttpd и подобное) НЕ нужен.
• [опционально] git для лёгкой и человеческой загрузки исходников, а также последующих обновлений.

Предостережения

• Тестировалось только на debian. Пулл-реквесты для совместимости с другими ОС приветствуются.

Установка

• Если установлен git, то клонируем репозиторий со всеми зависимостями: ~/dev$ git clone --recursive git@github.com:klavogonki-dev/vocbook-split.git
• Если git отсутствует:
  • Скачиваем два архива с репозиториями: vocbook-fetch и vocbook-split.
  • Распаковываем проект vocbook-split, далее переходим в папку vendor и в неё распаковываем проект vocbook-fetch, при этом должен получиться корректный путь: %workdir%/vocbook-split/vendor/vocbook-fetch/autoloader.php. Однако распаковать можно и в любую другую папку, предварительно отредактировав соответствующую строку с подключением autoloader.php в начале файла index.php.

Настройка

• [обязательно] отредактировать файл ./books.php: закомментировать строчку, выбрасывающую исключение, и добавить в массив $books информацию об источнике txt-файла (книги).
• [обязательно] копируем один из файлов в директории ./parsers/*.php в файл ./parser.php. Этот путь занесён в .gitignore, поэтому постоянные изменения этого файла не будут мельтешить перед глазами при работе с git.
• [рекомендуется] скопировать файл ./conf.php.example как ./conf.php и отредактировать его, если необходимо.

Запуск

Запуск выполняется из командной строки путём выполнения команды $ php index.php.

В index.php есть код, на который обязательно стоит обратить внимание, и, возможно, внести свои правки: это блок кода в самом низу, после строчки с комментарием /** Feel free to change code below **/. Пример:

$book = new Book($books[0]);
if ($book->load()) {
	$book->split($parse);
	print "Parts: " . count($book->parts) . "\r\n";
	$book->view_parts();
	// $book->save_parts();
}

Краткое описание класса Book можно посмотреть ниже, более подробно можно изучить взглянув на исходный код vocbook-fetch.

Описание

Репозиторий vocbook_split

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

Репозиторий vocbook_fetch

Основные задачи vocbook_fetch:

• облегчение загрузки (download) книг из различных источников (ресурсов) за счёт использования различных драйверов;
• вызывать функцию разбивки (по умолчанию $parser в parser.php) таким образом, чтобы итоговая реализация интерфейса (некоего API) способствовала успешному и безболезненному встраиванию в какие-либо сторонние проекты;
• предоставлять удобный вывод результатов работы функции разбивки книг для последующего просмотра и анализа полученных результатов.

Все доступные функции можно посмотреть непосредственно в исходном коде, но список самых важных свойств и методов приведён в листинге ниже:

/**
 * @property-read array<BookPart> parts - получает список уже распарсенных отрывков.
 * Возвращает пустой массив если метод `split` для экземпляра этого класса ранее не был вызван
 * @property-read string driver - получает название связанного с книгой драйвера загрузки
 * @property-read string id - получает уникальный индентификатор источника книги (используется драйвером)
 * @property-read string author - автор книги
 * @property-read string title - название книги
 * @property-read string type - тип словаря: "private" или "public"
 */
class Book {
  /**
   * @constructor
   * @param array $book - массив описания источника книги, определённый в файле `books.php`
   */
  __construct (array $book)

  /**
   * @method загружает книгу. Если книга *не* найдена в хранилище,
   * т.е. прежде *не* была загружена и помещена по пути, указанном
   * в конфиге `conf.php` (свойство `data`), то пытается загрузить
   * книгу и поместить в хранилище.
   * @param bool $force - если `true`, то удаляет ранее загруженный
   * файл из хранилища и пытается загрузить заново.
   * @return bool - `true` если загрузка книги удалась, `false` в случае ошибки
   */  
  load ([bool $force]): bool

  /**
   * @method вызывает пользовательскую функцию разбивки книг (по умолчанию
   * функция определена в файле `parser.php`.
   * @param callable $parser - функция разбивки книг, подробнее см. выше.
   * @return Book $this
   * @throws Exception невозможно прочитать файл из хранилища
   * @throws Exception последовательность номеров отрывков не совпадает
   * с шаблоном `1..N`, т.е. либо есть недостающие номера, либо отсчёт начинается не с `1`.
   */
  split (callable $parser): Book

  /**
   * @method добавляет фрагмент (отрывок книги) в список отрывков ( { @see parts } )
   * По окончанию работы коллбека `$parser` проверяет массив `parts` на 
   * пропущенные номера отрывков
   * @param string $text - текст отрывка
   * @param integer $number - номер отрывка
   * @param BookPart $bp - отрывок
   * @return Book $this
   * @throws Exception передан неправильный тип аргументов
   */
  add_part (string $text, integer $number): Book
  add_part (BookPart $bp): Book
    
  /**
   * @method сохраняет все фрагменты отрывков книги.
   * @param callable $converter: коллбек-функция конвертации данных.
   * Указывается, если требуется иной формат сохранения отрывков, по умолчанию
   * используется `print_r` для каждого отрывка.
   * @return Book $this
   * @throws Exception не получается открыть файл для записи
   */
  save_parts ([callable $converter]): Book

  /**
   * @method выводит в стандартный поток вывода все фрагменты отрывков книги.
   * Функция полезна для обработки или фильтрации вывода внешними программами,
   * например, запуск `php index.php | less` поможет быстро просмотреть результат
   * разбивки для файлов огромных размеров.
   * @param callable $converter: коллбек-функция конвертации данных.
   * Указывается, если требуется иной формат вывода отрывков, по умолчанию
   * используется `print_r` для каждого отрывка.
   * @return Book $this
   */
  view_parts ([callable $converter]): Book
}

Функция разбивки книг $parser

Некоторые реализации этой функции уже есть в папке parsers/. Перед началом работы необходимо скопировать любой из файлов в директории parsers в корень репозитория с именем parser.php.

Функция должна иметь сигнатуру:

parser(resource $handle, callable $add, BookFlag $flags): void

где

• $handle — указатель на дескриптор открытого файла в режиме 'r' (только чтение), т.е. stream reader. Вызывать fclose для закрытия потока не требуется.
• $add — имеет точно такую же сигнатуру, как и Book::add_part (см. выше).
• $flags — набор битовых модификаторов режима разбивки. Например, если отсутствует выставленный бит по маске BookFlag::VOC_PRIVATE, то на парсинг накладываются определённые ограничения (которые должны быть реализованы в алгоритме разбивки), потому что словарь предполагается использовать публичным.

Де-факто $add — это массив с указателем на текущий обрабатываемый экземпляр класса Book, но эту возможность можно использовать только для отладки кода.

Вызывать $add нужно для каждого отрывка отдельно, обязательно с указанием номера отрывка. Если в процессе разбивки книги будет пропущен какой-либо номер отрывка (или каким-либо иным образом нарушится порядок), то будет сгенерировано предупреждение уровня E_USER_NOTICE. Это допустимо, если алгоритм такое предусматривает. Если по окончанию разбивки книги будет обнаружен пропуск номера отрывка, то будет сгенерировано исключение.

Основная проблема парсинга — корректное определение и обработка различных кодировок, этому надо уделять особое внимание и не стесняться пользоваться функциями mb_* \ iconv и подобными.

Допускается не ограничиваться одной лишь функцией и создавать свои собственные классы в этом же файле (parser.php) и\или создавать целую структуру каталогов с namespace'ами в случае, если это оправдано; использовать сторонние библиотеки (если их использованию не противоречит лицензия, под которой они распространяются) и прочие кошерные вещи. Однако вызов извне должен поддерживаться сигнатурой функции, определённой выше.

Драйверы

Для загрузок книг из различных источников используются различные драйверы, расположенные по пути /vocbook-fetch/vocbook/drivers/*.php.

При создании экземпляра класса Book требуется указать массив, который в том числе должен иметь свойство driver, содержащее название используемого драйвера. Драйвер в свою очередь будет скачивать книгу по уникальному индентификатору id, указанному также при вызове конструктора Book. Среди списков драйверов есть local: используется для обычного копирования книги с локальной файловой системы, id в этом случае — обычный путь к файлу.

Пулл-реквесты с драйверами загрузок из других источников — приветствуются.