# Урѣзчикъ (HScrubber)

HScrubber есть движокъ для прорѣшиванія HTML-документа. Онъ позволяетъ процѣдить содержимое входного потока очистивъ его отъ ненужныхъ предмѣтовъ на основѣ рѣхи, являющейся YAML-документомъ, по опредѣлённымъ правиламъ состаленнымъ.

# Рѣха
## Объясненіе рѣхи

Рѣха задаётся въ видѣ YAML-документа. На самомъ верхнемъ уровнѣ описываются мѣты (HTML tags), допустимыя въ выходномъ документѣ. Слѣдующій уровень задаётъ допустимыя свойства (attributes) для опредѣлённой мѣты, а также ключи, управляющія мѣтою и её содержимымъ. Возможныя ключи и их значенія суть такія:

 * '_' содержимое мѣты будетъ очищено, если оно подпадаетъ подъ заданное въ значеніи ключа правило;

 * '-' мѣта удаляется въ томъ случаѣ, если её содержимое подпадаетъ подъ заданное въ значеніи ключа правило;

 * '^' содержимое мѣты добавляется къ содержимому родителькой мѣты въ томъ случаѣ, если содержимое сей мѣты подпадаетъ подъ правило, или если правило не задано;

 * '%' задаётъ порядокъ слѣдованія ключей мѣты въ выходномъ файлѣ. Ключи пишутся черезъ запятую.

Ключи здѣ расположены въ порядкѣ первичности ихъ провѣрки. Каджый изъ нихъ обязательно предваряется символомъ '@'

## Примѣръ
Примѣрный шаблонъ файла рѣхи представленъ нижѣ:

    ---
    html:
    body:
    p:
    i:
      @-: ^[.,:;!?\s]*$
    font:
      face:
      size:
      @%: size,face
      @-: ^\s+$
      @_: ^[.,:!?#]+$
    span:
      @^:
      @-: ^[.,:;!?\s]*$
    
Поясненія:

Мѣта 'i' не имѣетъ допустимыхъ ключей, и они будутъ удалены изъ входного потока. Въ случаѣ, если содержимое мѣты удовлѣтворяетъ правилу удаления, на выходѣ сія мѣта будетъ отсутствовать. Примѣры:

    <i id="i_id">Text</i> -> <i>Text</i>
    <font>Text<i>?</i></font> -> <font>Text</font>

Допустимыми ключами для мѣты 'font' являются 'face' и 'size'. Въ случаѣ, если содержимое мѣты удовлѣтворяетъ правилу удаления, на выходѣ сія мѣта будетъ отсутствовать, а если правилу очищенія, то её содержимое станетъ порожнимъ, ключи будутъ расположены въ порядкѣ size, face. Примѣры:

    <font size="5" color="blue">Text</font> -> <font size="5">Text</font>
    <i>Text<font>  </font></i> -> <i>Text</i>
    <i>Text<font>??</font></i> -> <i>Text<font></font></i>
    <font face="Arial" size="5">Text</font> -> <font size="5" face="Arial">Text</font>

Допустимыя ключи для мѣты 'span' отсутствуютъ, и въ случаѣ ихъ обнаруженія въ входномъ потокѣ они будутъ вырѣзаны изъ него. Если содержимое мѣты удовлѣтворяетъ правилу удаления, на выходѣ сія мѣта будетъ отсутствовать какъ таковая. Въ остальныхъ же случаяхъ её содержимое будетъ добавлено къ мѣтѣ родительской. Примѣры:

    <span id="span_id">Text</span> -> <span>Text</span>
    <i>Text<span>?</span></i> -> <i>Text</i>

## Использованіе
Суть 2 способа использованія пакета въ ruby-приложеніяхъ.

### Используя методъ экземпляра класса
Создай экземпляръ класса, передавъ конструктору рѣху загруженную въ видѣ строки или IO-класса, а затѣмъ прорѣши HTML-документъ:

    рѣха = IO.read('.рѣха.yml.sample')
    hs = HScrubber.new(рѣха)

    html = IO.read('sample.html').gsub(/\r/, '')
    new_html = hs.scrub_html(html)

    puts html

### Используя методъ класса
Можно прорѣшить HTML-документъ и не создавая экземпляръ класса. Тогда дѣлай такъ:

    рѣха = IO.read('.рѣха.yml.sample')
    html = IO.read('sample.html').gsub(/\r/, '')
    new_html = HScrubber.scrub_html(html, рѣха)

    puts html

# Права

Авторскія и исключительныя права (а) 2011 Малъ Скрылевъ. Зри LICENSE за подробностями.