README.txt

= 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], {Yaroslav 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