= RuTils
http://rutils.rubyforge.org
RuTils - простой обработчик русского текста на Ruby.
Основная цель RuTils - сделать разработку русскоязычных приложений на Ruby (и Rails) максимально простой
и приятной (в идеале - столь же простой как и разработку оных на английском).
== Шеф! все пропало! я обновил RuTils и он работает совершенно по-другому!
Раздел также известен под именем "Что поменялось в RuTils 1.0.0". Вам сюда.[link:files/WHAT_HAS_CHANGED_txt.html]
== Чье это
Разработчики RuTils - Julik[http://julik.nl], Mash[http://imfo.ru], Markin[http://markin.net/]
Большое спасибо Роману Иванову aka Kukutz и Николаю Яремко aka Kuso Mendokuzee за
реализацию большинства алгоритмов на PHP.
= Как воспользоваться
Просто включите rutils в свою программу как библиотеку
require 'rutils'
Для использования с Ruby on Rails установите RuTils как плагин
(скопируйте библиотеку в vendor/plugins приложения).
= Что оно делает
== Cумма прописью и выбор числительного
RuTils реализует сумму прописью для целых и дробных чисел, с дополнительным
учетом рода. Например:
4.propisju => "четыре"
345.propisju => "триста сорок пять"
231.propisju(2) => "двести тридцать одна"
341.propisju_items(1, "чемодан", "чемодана", "чемоданов") => "триста сорок один чемодан"
(212.40).propisju_items(2, "сволочь", "сволочи", "сволочей") => "двести двенадцать целых
четыре десятых сволочи"
Также реализуется выбор варианта числительного в зависимости от числа
15.items("кодер", "кодера", "кодеров") => "кодеров"
и вывод "суммы прописью" для денежных сумм в рублях
(413.2).rublej => "четыреста тринадцать рублей двадцать копеек"
1.rubl => "один рубль"
22.rublja => "двадцать два рубля"
Если вы храните денежные единицы в целочисленных типах, пользуйтесь "копеечными" вариантами:
300.kopeek => "три рубля"
121.kopeika => "один рубль двадцать одна копейка"
== Транслит
RuTils на данный момент реализует простейший транслит "в одну сторону".
"Взаимно-однозначный транслит" (BiDi-транслит) больше не поддерживается.
"Вот такое вот дело".translify => "Vot takoye vot delo"
"Несомненный прогресс по сравнению с PHP".dirify => "nesomnennyi-progress-po-sravneniu-s-php"
== Обработка русской типографики в HTML
Gilenson - порт Typografica[http://pixel-apes.com/typografica] от Pixel Apes.
Тыпографица - механизм автоматической расстановки подстановок в тексте перед его
выводом в HTML, оформляющий неразрывные пробелы, типографские кавычки и тому
подобные "украшательства".
Gilenson расставит в тексте "умные" правильные кавычки (русские - для кириллицы,
английские - для латиницы), заменит "хитрые" пунктуационные символы на entities и
отформатирует знаки типа (c), (tm), телефоны и адреса.
%qэто называется языком?", -- таков был его вопрос.gilensize => "«И
это называется языком?», — таков был его вопрос"
Более подробная документация по Gilenson доступна в документах к
RuTils::Gilenson::Formatter
В комплекте также есть скрипт gilensize, которым можно поточно обрабатывать
Unicode-тексты в среде UNIX пользуясь стандартным выводом
$ cat myfile.txt | gilensize > myfile.html
== Даты
В класс Date введены следующие константы:
* RU_MONTHNAMES (Январь Февраль Март...)
* RU_DAYNAMES (Воскресенье Понедельник...)
* RU_ABBR_MONTHNAMES (Янв Фев Мар...)
* RU_ABBR_DAYNAMES (Вск Пн Вт Ср...)
* RU_INFLECTED_MONTHNAMES (Января Февраля Марта...)
* RU_DAYNAMES_E (первое второе третье...)
Пример использования:
require 'date' date = Date.new(2005, 11, 9)
puts "#Date::RU_ABBR_MONTHNAMES[date.mon]" => Ноя
puts "#Date::RU_MONTHNAMES[date.mon]" => Ноябрь
puts "#Date::RU_ABBR_DAYNAMES[date.wday]" => Ср
puts "#Date::RU_DAYNAMES[date.wday]" => Среда
При включенной перезагрузке функций (RuTils::overrides_enabled) осуществляется
"покрытие" стандартной функции Time#strftime ("родную" #strftime можно продолжать
использовать через alias-метод #strftime_norutils):
Time.local(2005,"dec",31).strftime("%a, %A, %b, %B") => "Сб, Суббота, Дек, Декабрь"
Time.local(2005,"dec",31).strftime_norutils("%a, %A, %b, %B") => "Sat, Saturday, Dec, December"
== Интеграция с RedCloth и BlueCloth
RuTils в первую очередь задумывался как максимально "прозрачный" механизм
обработки русского текста в контексте Rails-приложения.
Если вы используете RuTils в одном приложении со стандартными форматтерами (RedCloth, BlueCloth...) воспользуйтесь
дополнительными модулями которые выводят отформатированный Гиленсоном результат работы форматтеров
Gilenson определяет следующие дополнительные форматтеры (они работают так же как и их базовые классы)
* RuTils::Gilenson::RedClothExtra
* RuTils::Gilenson::BlueClothExtra
* RuTils::Gilenson::RDiscountExtra
* RuTils::Gilenson::MarukuExtra
В этих классах Gilenson будет обрабатывать типографику во всех текстах, пропускаемых через
них. Эти классы при включенном флаге RuTils.overrides автоматически подключаются в хелперы
+markdown+ и +textilize+.
== Интеграция с Rails версии 2.2.2 и выше
Используйте гем russian для дат и RuTils как дополнение (для транслита, функций kopeek и так далее)
== Интеграция с Rails версий 1.2 - 2.1.1
RuTils заставляет следующие функции старых (pre-i18n) версий Rails говорить по-русски:
* Меню выбора даты (+date_select+ и +datetime_select+) и связанные с этим хелперы
будут выводиться с русскими именами месяцев, и учитывая локализованный порядок дат
(сначала число, потом месяц, потом год)
* +distance_of_time_in_words+ будет выводить
русские описания длительности ("более 2 часов")
== Управление оверрайдами
Перегрузку всех функций других модулей можно включать и отключать в любое время с
помощью метода RuTils::overrides=. Когда перегрузка выключена, все сторонние
хелперы будут работать в стандартном режиме (например, даты и время будут выводиться по-русски).
Это нужно когда вам нужно переключиться на английский (или любой другой язык) без перезапуска приложения.
Рекомендуемый способ использования RuTils с Ruby on Rails приложением -- установка RuTils
плагином. Для этого скопируйте директорию rutils в папку vendor/plugins вашего
приложения или воспользуйтесь командой rutilize путь_к_rails_приложению чтобы сделать это
автоматически. После этого вы сможете использовать RuTils без необходимости
установки gem на вашем сервере (не забудьте перезапустить приложение чтобы
вгрузить в него RuTils).
$ rutilize /Sites/my_app1 /Sites/my_app2 /Sites/my_another_app
== Распространения
Вы можете свободно распространять RuTils со своим приложением при условии
сохранения структуры и файла README.
== Совместимость
* Ruby 1.8.x
* Ruby 1.9.x (релизные версии начиная с 1.9.1)
* JRuby 1.1.6
== Требования
* Ruby 1.8.2 или выше, немного прямых рук
* Rake[http://rake.rubyforge.org],
Rails[http://rubyonrails.org],
RedCloth[http://www.whytheluckystiff.net/ruby/redcloth/] и
BlueCloth[http://www.deveiate.org/projects/BlueCloth] для выполнения тестов.
== Работает ли это с текстом в кодировке отличной от UTF-8 (Windows-1251, KOI-8)
Нет и никогда не будет.
== Как получить помощь
Весь функционал RuTils поддерживает только UTF-8 (настройка $KCODE / KanjiCode
'u'). Удостоверьтесь, что ваш скрипт правильно обрабатывает Unicode - то есть:
* Переменная $KCODE включена в режим 'u'
* Все строки которые вы собираетесь обрабатывать уже в кодировке UTF-8
Если вы используете RuTils для сайта под mod_ruby воспользуйтесь директивой
RubyKanjiCode в своем httpd.conf.
== Если вы все сделали правильно но что-то не работает
Сообщите об ошибке на странице проекта на RubyForge[http://rubyforge.org/projects/rutils]
Не забудьте указать версию, ее всегда можно узнать в константе
RuTils::VERSION
== Как ускорить реализацию новых функций
Воспользуйтесь трекером на RubyForge. Опишите нужный вам функционал и приложите
тесты, которым этот функционал должен удовлетворять. Схему организации тестов вы
можете скопировать из собственных тестов RuTils.
Если вы пишете исходный код, который войдет в RuTils или в тестовые наборы,
пожалуйста следуйте следующим правилам оформления кода:
* Unix line breaks (LF)
* Кодировка файлов - строго UTF-8 без BOM (Byte Order Mark)
* Все файлы должны содержать emacs-прагму
# -*- encoding: utf-8 -*-
в первой строке
* Отступы в 2 пробела, без табуляций
* Только однозначный код для 1.8 и 1.9
* Без функций которые отсутствуют в 1.8 (в первую очередь encodings)
* Без функций которые убраны из 1.9
* Однострочные блоки с фигурными скобками, многострочные - с +do ... end+
* Все другие конвенции нормального написания
Ruby-кода (http://github.com/chneukirchen/styleguide/tree/master)
При сравнении текстовых сегментов, прошедших через хитрые форматтеры пользуйтесь assert_equal_cp
- он внятно покажет вам какой символ отличается в двух строках (иначе будете вслепую искать
разницу между двумя разными пробелами, например)
Если вы хотите участвовать в разработке RuTils - fork us on GitHub
git clone git://github.com/julik/rutils.git
http://rutils.rubyforge.org
RuTils - простой обработчик русского текста на Ruby.
Основная цель RuTils - сделать разработку русскоязычных приложений на Ruby (и Rails) максимально простой
и приятной (в идеале - столь же простой как и разработку оных на английском).
== Шеф! все пропало! я обновил RuTils и он работает совершенно по-другому!
Раздел также известен под именем "Что поменялось в RuTils 1.0.0". Вам сюда.[link:files/WHAT_HAS_CHANGED_txt.html]
== Чье это
Разработчики RuTils - Julik[http://julik.nl], Mash[http://imfo.ru], Markin[http://markin.net/]
Большое спасибо Роману Иванову aka Kukutz и Николаю Яремко aka Kuso Mendokuzee за
реализацию большинства алгоритмов на PHP.
= Как воспользоваться
Просто включите rutils в свою программу как библиотеку
require 'rutils'
Для использования с Ruby on Rails установите RuTils как плагин
(скопируйте библиотеку в vendor/plugins приложения).
= Что оно делает
== Cумма прописью и выбор числительного
RuTils реализует сумму прописью для целых и дробных чисел, с дополнительным
учетом рода. Например:
4.propisju => "четыре"
345.propisju => "триста сорок пять"
231.propisju(2) => "двести тридцать одна"
341.propisju_items(1, "чемодан", "чемодана", "чемоданов") => "триста сорок один чемодан"
(212.40).propisju_items(2, "сволочь", "сволочи", "сволочей") => "двести двенадцать целых
четыре десятых сволочи"
Также реализуется выбор варианта числительного в зависимости от числа
15.items("кодер", "кодера", "кодеров") => "кодеров"
и вывод "суммы прописью" для денежных сумм в рублях
(413.2).rublej => "четыреста тринадцать рублей двадцать копеек"
1.rubl => "один рубль"
22.rublja => "двадцать два рубля"
Если вы храните денежные единицы в целочисленных типах, пользуйтесь "копеечными" вариантами:
300.kopeek => "три рубля"
121.kopeika => "один рубль двадцать одна копейка"
== Транслит
RuTils на данный момент реализует простейший транслит "в одну сторону".
"Взаимно-однозначный транслит" (BiDi-транслит) больше не поддерживается.
"Вот такое вот дело".translify => "Vot takoye vot delo"
"Несомненный прогресс по сравнению с PHP".dirify => "nesomnennyi-progress-po-sravneniu-s-php"
== Обработка русской типографики в HTML
Gilenson - порт Typografica[http://pixel-apes.com/typografica] от Pixel Apes.
Тыпографица - механизм автоматической расстановки подстановок в тексте перед его
выводом в HTML, оформляющий неразрывные пробелы, типографские кавычки и тому
подобные "украшательства".
Gilenson расставит в тексте "умные" правильные кавычки (русские - для кириллицы,
английские - для латиницы), заменит "хитрые" пунктуационные символы на entities и
отформатирует знаки типа (c), (tm), телефоны и адреса.
%qэто называется языком?", -- таков был его вопрос.gilensize => "«И
это называется языком?», — таков был его вопрос"
Более подробная документация по Gilenson доступна в документах к
RuTils::Gilenson::Formatter
В комплекте также есть скрипт gilensize, которым можно поточно обрабатывать
Unicode-тексты в среде UNIX пользуясь стандартным выводом
$ cat myfile.txt | gilensize > myfile.html
== Даты
В класс Date введены следующие константы:
* RU_MONTHNAMES (Январь Февраль Март...)
* RU_DAYNAMES (Воскресенье Понедельник...)
* RU_ABBR_MONTHNAMES (Янв Фев Мар...)
* RU_ABBR_DAYNAMES (Вск Пн Вт Ср...)
* RU_INFLECTED_MONTHNAMES (Января Февраля Марта...)
* RU_DAYNAMES_E (первое второе третье...)
Пример использования:
require 'date' date = Date.new(2005, 11, 9)
puts "#Date::RU_ABBR_MONTHNAMES[date.mon]" => Ноя
puts "#Date::RU_MONTHNAMES[date.mon]" => Ноябрь
puts "#Date::RU_ABBR_DAYNAMES[date.wday]" => Ср
puts "#Date::RU_DAYNAMES[date.wday]" => Среда
При включенной перезагрузке функций (RuTils::overrides_enabled) осуществляется
"покрытие" стандартной функции Time#strftime ("родную" #strftime можно продолжать
использовать через alias-метод #strftime_norutils):
Time.local(2005,"dec",31).strftime("%a, %A, %b, %B") => "Сб, Суббота, Дек, Декабрь"
Time.local(2005,"dec",31).strftime_norutils("%a, %A, %b, %B") => "Sat, Saturday, Dec, December"
== Интеграция с RedCloth и BlueCloth
RuTils в первую очередь задумывался как максимально "прозрачный" механизм
обработки русского текста в контексте Rails-приложения.
Если вы используете RuTils в одном приложении со стандартными форматтерами (RedCloth, BlueCloth...) воспользуйтесь
дополнительными модулями которые выводят отформатированный Гиленсоном результат работы форматтеров
Gilenson определяет следующие дополнительные форматтеры (они работают так же как и их базовые классы)
* RuTils::Gilenson::RedClothExtra
* RuTils::Gilenson::BlueClothExtra
* RuTils::Gilenson::RDiscountExtra
* RuTils::Gilenson::MarukuExtra
В этих классах Gilenson будет обрабатывать типографику во всех текстах, пропускаемых через
них. Эти классы при включенном флаге RuTils.overrides автоматически подключаются в хелперы
+markdown+ и +textilize+.
== Интеграция с Rails версии 2.2.2 и выше
Используйте гем russian для дат и RuTils как дополнение (для транслита, функций kopeek и так далее)
== Интеграция с Rails версий 1.2 - 2.1.1
RuTils заставляет следующие функции старых (pre-i18n) версий Rails говорить по-русски:
* Меню выбора даты (+date_select+ и +datetime_select+) и связанные с этим хелперы
будут выводиться с русскими именами месяцев, и учитывая локализованный порядок дат
(сначала число, потом месяц, потом год)
* +distance_of_time_in_words+ будет выводить
русские описания длительности ("более 2 часов")
== Управление оверрайдами
Перегрузку всех функций других модулей можно включать и отключать в любое время с
помощью метода RuTils::overrides=. Когда перегрузка выключена, все сторонние
хелперы будут работать в стандартном режиме (например, даты и время будут выводиться по-русски).
Это нужно когда вам нужно переключиться на английский (или любой другой язык) без перезапуска приложения.
Рекомендуемый способ использования RuTils с Ruby on Rails приложением -- установка RuTils
плагином. Для этого скопируйте директорию rutils в папку vendor/plugins вашего
приложения или воспользуйтесь командой rutilize путь_к_rails_приложению чтобы сделать это
автоматически. После этого вы сможете использовать RuTils без необходимости
установки gem на вашем сервере (не забудьте перезапустить приложение чтобы
вгрузить в него RuTils).
$ rutilize /Sites/my_app1 /Sites/my_app2 /Sites/my_another_app
== Распространения
Вы можете свободно распространять RuTils со своим приложением при условии
сохранения структуры и файла README.
== Совместимость
* Ruby 1.8.x
* Ruby 1.9.x (релизные версии начиная с 1.9.1)
* JRuby 1.1.6
== Требования
* Ruby 1.8.2 или выше, немного прямых рук
* Rake[http://rake.rubyforge.org],
Rails[http://rubyonrails.org],
RedCloth[http://www.whytheluckystiff.net/ruby/redcloth/] и
BlueCloth[http://www.deveiate.org/projects/BlueCloth] для выполнения тестов.
== Работает ли это с текстом в кодировке отличной от UTF-8 (Windows-1251, KOI-8)
Нет и никогда не будет.
== Как получить помощь
Весь функционал RuTils поддерживает только UTF-8 (настройка $KCODE / KanjiCode
'u'). Удостоверьтесь, что ваш скрипт правильно обрабатывает Unicode - то есть:
* Переменная $KCODE включена в режим 'u'
* Все строки которые вы собираетесь обрабатывать уже в кодировке UTF-8
Если вы используете RuTils для сайта под mod_ruby воспользуйтесь директивой
RubyKanjiCode в своем httpd.conf.
== Если вы все сделали правильно но что-то не работает
Сообщите об ошибке на странице проекта на RubyForge[http://rubyforge.org/projects/rutils]
Не забудьте указать версию, ее всегда можно узнать в константе
RuTils::VERSION
== Как ускорить реализацию новых функций
Воспользуйтесь трекером на RubyForge. Опишите нужный вам функционал и приложите
тесты, которым этот функционал должен удовлетворять. Схему организации тестов вы
можете скопировать из собственных тестов RuTils.
Если вы пишете исходный код, который войдет в RuTils или в тестовые наборы,
пожалуйста следуйте следующим правилам оформления кода:
* Unix line breaks (LF)
* Кодировка файлов - строго UTF-8 без BOM (Byte Order Mark)
* Все файлы должны содержать emacs-прагму
# -*- encoding: utf-8 -*-
в первой строке
* Отступы в 2 пробела, без табуляций
* Только однозначный код для 1.8 и 1.9
* Без функций которые отсутствуют в 1.8 (в первую очередь encodings)
* Без функций которые убраны из 1.9
* Однострочные блоки с фигурными скобками, многострочные - с +do ... end+
* Все другие конвенции нормального написания
Ruby-кода (http://github.com/chneukirchen/styleguide/tree/master)
При сравнении текстовых сегментов, прошедших через хитрые форматтеры пользуйтесь assert_equal_cp
- он внятно покажет вам какой символ отличается в двух строках (иначе будете вслепую искать
разницу между двумя разными пробелами, например)
Если вы хотите участвовать в разработке RuTils - fork us on GitHub
git clone git://github.com/julik/rutils.git