forked from mr-july/phpHypher
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.ru
349 lines (239 loc) · 21.4 KB
/
README.ru
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
Название: phpHypher
Версия: 0.1.0
Дата: 29.05.2010
Статус: beta
Автор: Сергей Куракин <sergeykurakin@gmail.com>
Лицензия: LGPL v.3
URL: http://quittance.ru/hyphenator.php
Описание: Класс php5 для расстановки мягких переносов по алгоритму
Ляна-Кнута. Включает свободно распространяемый набор
правил переносов для русского языка.
========================================================================
Quickstart
========================================================================
<?php
// Подключение библиотеки.
require_once 'libs/hypher.php';
// Создание объекта, загрузка файла описания и набора правил.
$hy_ru = new phpHypher('libs/hyph_ru_RU.conf');
// Расстановка переносов.
echo $hy_ru->hyphenate('Текст, в котором надо расставить переносы', 'UTF-8');
echo $hy_ru->hyphenate('Текст для расстановки переносов', 'UTF-8');
echo $hy_ru->hyphenate('...и так далее...', 'UTF-8');
?>
В этом примере предполагается, что все файлы библиотеки, включая файл
описания языка и наборы правил, находятся в директории libs/. Кодировка
текста для расстановки переносов может быть utf-8 или любая восьмибит-
ная; указывается вторым параметром метода hyphenate().
========================================================================
Особенности и преимущества phpHypher
========================================================================
Конфигурационный файл описания языка
Многочисленные параметры расстановки переносов для каждого конкретного
языка задаются директивами в файле описания языка, имя которого является
обязательным параметром при создании экземпляра объекта phpHypher.
Кеширование обработанных словарей со встроенным механизмом
проверки их актуальности
В процессе создания экземпляра объекта phpHypher происходит загрузка и
обработка наборов правил (паттернов) и других данных, необходимых для
расстановки переносов. Процесс обработки и оптимизации данных занимает
доли секунды, но эти доли секунды могут оказаться критичными для произ-
водительности нагруженной системы. Поэтому обработанные данные сохраня-
ются для дальнейшего использования в файл, имя которого задано директи-
вой compiled.
В дальнейшем обработанные и оптимизированные словари будут загружаться
непосредственно из compiled-файла с обязательным контролем его актуаль-
ности. В случае потери актуальности (или отсутствия), compiled-файл бу-
дет автоматически обновлен (или создан заново) из исходных файлов пра-
вил.
Таким образом, время загрузки словарей и других необходимых для расста-
новки переносов данных сведено к минимуму. С другой стороны, phpHypher
позволяет оперативно вносить изменения в файл описания языка и в файлы
правил переносов -- изменения будут учтены при первом же вызове кон-
структора класса.
Расширенные настройки условий переноса слов
Обычно системы расстановки переносов в тексте позволяют задавать три
стандартных условия переносов: ограничение слева -- минимальное количе-
ство символов, которое допустимо отделять от слова спереди; ограничение
справа -- минимальное количество букв, которое можно переносить на дру-
гую строку; ограничение по длине -- минимальная длина слова, допускающая
переносы.
Помимо стандартных, phpHypher предоставляет возможность отдельно задать
еще два дополнительных условия: ограничение слева для слов, начинающихся
с заглавной буквы и ограничение справа для последнего слова абзаца. Рас-
ширенные условия переноса слов позволяют более тонко настроить систему
автоматической расстановки мягких переносов в особых случаях для различ-
ных способов выключки текста.
Запрет переноса слов
Переносы не будут расставлены в словах, экранированных при помощи обрат-
ной косой черты "\" (код символа 0x5C), которая должна располагаться
непосредственно перед первой буквой экранируемого слова.
Например, для расстановки переносов в англоязычном тексте, включающем в
себя теги разметки, необходимо экранировать теги, чтобы избежать расста-
новки переносов внутри них. Но такой необходимости нет при расстановке
переносов на русском языке, поскольку русскоязычный текст не пересекает-
ся по алфавиту с тегами, записанными латинскими буквами.
Возможность одновременного использования нескольких наборов
правил переносов
Конфигурационный файл описания языка позволяет подключать одновременно
несколько наборов правил, что придает системе дополнительную гибкость.
Можно иметь один основной набор правил, а исправления и дополнения вно-
сить в дополнительный набор, не меняя основного. Или расставлять перено-
сы в тексте сразу на двух языках, если эти языки не пересекаются по ал-
фавиту -- например, на русском и английском.
Другие преимущества
Обработка текста в кодировке utf-8 и во всех однобайтовых; отсутствие
потерь при перекодировках; высокая производительность; отсутствие зави-
симости от установок системной локали.
========================================================================
Разъяснение работы phpHypher с различными кодировками
========================================================================
Немного забегая вперед, необходимо сделать два заявления. Класс
phpHypher корректно работает с текстом в кодировке utf-8, а также с лю-
быми однобайтными кодовыми страницами. Класс phpHypher не потеряет ни
одного символа при перекодировке текста.
Понятие базовой кодировки
Базовая кодировка -- это рабочая кодовая страница, непосредственно ис-
пользуемая внутри phpHypher в процессе расстановки переносов. Задается
в файле описания языка. С целью достижения высокой производительности, в
качестве базовой рабочей кодировки допускаются только однобайтные
(в оригинальном наборе для русского языка используется кодовая страница
CP1251).
Базовая кодировка не имеет отношения к кодовой странице обрабатываемого
текста.
Кодировка обрабатываемого текста
Кодовая страница обрабатываемого текста может быть utf-8 или любой одно-
байтной. Она никак не зависит от базовой кодировки. Задается вторым па-
раметром при вызове метода hyphenate().
Высказывались опасения, что внутри phpHypher преобразование обрабатывае-
мого текста в базовую кодировку приведет к потере отсутствующих в ней
символов. Спешим развеять эти опасения, ни один символ не будет потерян!
Отсутствие потерь гарантируется в силу того, что phpHypher не занимается
перекодировкой всего текста. Вместо этого, в базовую кодировку и обратно
преобразуются отдельные слова, вычлененные из текста для расстановки пе-
реносов. Такие слова заведомо не содержат символов, несовместимых с ра-
бочей кодовой страницей.
Алгоритм вычленения слов из текста выбирает непрерывные фрагменты, со-
стоящие только из символов алфавита определенного языка, и по-отдельно-
сти направляет их на расстановку переносов в защищенный метод
hyphenate_word(). Таким образом гарантируется, что метод
hyphenate_word() никогда не получит символов, отсутствующих в рабочей
кодовой странице, и всегда может безопасно, то есть без потерь, выпол-
нить преобразование слова в базовую кодировку и обратно.
Кодовая страница наборов правил (словарей)
Допускается любая кодировка для файлов с наборами правил, причем каждый
словарь может иметь свою собственную. Никаких ограничений нет. Кодовая
страница словаря обязательно должна быть указана в его первой значащей
строке.
Установки системной локали
Внутри phpHypher не используются зависимые от локали функции и шаблоны
регулярных выражений, поэтому результат его работы никак не связан с
установками локали.
Вычленение слов из текста и преобразования регистра букв производятся
при помощи соответствующих параметров файла описания языка, которые со-
держат все символы алфавита в верхнем и нижнем регистре.
Уникальный дизайн phpHypher обеспечивает корректную работу даже в самых
экзотических ситуациях. Например, может использоваться CP1251 в качестве
базовой кодировки, два файла правил в кодовых страницах koi8-r и
ISO-8859-5, установлена китайская локаль, а исходный русский текст может
подаваться в кодировке utf-8... И даже в такой ситуации phpHypher рас-
ставит переносы и не потеряет ни одного символа из обрабатываемого тек-
ста.
========================================================================
Описание методов и свойств класса phpHypher
========================================================================
// Constructor
__construct ( string $conffile [, int $recompile] )
Создает экземпляр объекта phpHypher и загружает информацию, необходимую
для расстановки переносов.
$conffile путь и имя файла описания
$recompile параметр, определяющий необходимость обновления
compiled-файла
// Properties
public $proceed_uppercase = false
public $left_limit;
public $right_limit;
public $length_limit;
public $left_limit_uc;
public $right_limit_last;
$proceed_uppercase -- свойство, позволяющее при необходимости расстав-
лять переносы в словах, содержащих заглавные буквы кроме первой. По
умолчанию переносы расставляются только в словах, полностью состоящих из
строчных букв или начинающихся с заглавной буквы.
Остальные свойства класса определяют условия переноса. Для их установки
следует использовать публичный метод set_limits(), который дополнительно
проверяет корректность условий переноса.
// Method
set_limits([, int $left_limit [, int $right_limit [,
int $length_limit [, int $right_limit_last [,
int $left_limit_uc]]]]] )
Устанавливает условия переноса с проверкой их корректности.
$left_limit ограничение слева -- минимальное количество симво-
лов, которое можно оставлять на строке; значение по
умолчанию берется из файла описания языка
$right_limit ограничение справа -- минимальное количество симво-
лов, которое можно переносить на другую строку; зна-
чение по умолчанию берется из файла описания языка
$length_limit минимальная длина слова, в котором можно расставлять
переносы; значение по умолчанию вычисляется как сум-
ма двух предыдущих параметров
$right_limit_last минимальное количество символов, которое можно пере-
носить на другую строку в последнем слове абзаца; по
умолчанию равно ограничению справа
$left_limit_uc минимальное количество символов, которое можно
оставлять на строке в словах, начинающихся с заглав-
ной буквы; по умолчанию равно ограничению слева
// Method
string hyphenate(string $instr [, string $encoding [, string $shy]] )
Расставляет мягкие переносы в тексте.
возвращает строку с расставленными мягкими переносами
$instr текст для расстановки переносов
$encoding кодировка входного и выходного текста в виде строки,
распознаваемой функцией iconv; по умолчанию: базовая
кодировка из файла описания языка
$shy строка, используемая для обозначения мягкого перено-
са; по умолчанию: "­"
========================================================================
Директивы файла описания языка
========================================================================
Директивы подробно документированы в самом файле описания языка, для
русского -- hyph_ru_RU.conf.
========================================================================
Формат файлов правил переносов phpHypher
========================================================================
Формат файлов с шаблонами phpHypher предельно прост и имеет много общего
с соответствующими файлами системы TeX.
Пустые строки и пробельные символы в начале и конце строки игнорируются.
Допускаются комментарии в стиле:
// комментарий
Если файлы шаблонов изготавливались из файлов TeX, убедитесь, что удале-
ны все элементы разметки TeX -- знаки процента, фигурные скобки, назва-
ния секций...
В первой значащей строке файла шаблонов должно находиться обозначение
его кодировки. Она может отличаться от базовой кодировки, может совпа-
дать с нею, но должна быть указана в любом случае.
Основу файла правил переносов составляет список шаблонов, по одному шаб-
лону в строке, аналогично секции patterns в системе TeX.
Кроме шаблонов, в файле могут находиться словарные слова, в которых ме-
ста возможных переносов обозначены дефисами, аналогично секции
hyphenation в системе TeX.
Если строка не содержит ни одной цифры, то она воспринимается как сло-
варное слово. При загрузке файла правил переносов словарные слова авто-
матически преобразуются в шаблоны следующим образом:
сло-во >> .с8л8о9в8о.
========================================================================
Файлы phpHypher
========================================================================
hypher.php класс phpHypher
sk_lib_i.php служебные функции, используемые в phpHypher
hyph_ru_RU.conf файл описания для русского языка
hyph_ru_RU.al базовый набор правил переносов для русского язы-
ка, получен из свободно распространяемого набора
правил проф. Александра Ивановича Лебедева
ruhyphal-030310
hyph_ru_RU.addition дополнительный набор правил, исправляющий неко-
торые ошибки и неточности основного набора
hyph_ru_RU.perfect дополнительный набор правил, позволяющий избе-
жать некоторых неблагозвучных или искажающих
смысл переносов
README.ru документация на русском языке