npm package: @freedomsex/text-censor
Description: Censor or highlight words.
Author: Tebaly
Latest version: 0.0.4

# Text Censor

Модуль для простого цензурирования сообщений. Сам по себе модульный, поддерживает расширение плагинами. Фильтры, в том числе встроенные, добавляются через _плагины_. Есть возможность добавлять и удалять фильтры используя соответствующие методы `add` и `delete`.

## Фильтры

Грубо говоря - это обычное _регулярное выражение_. Чтобы иметь возможность управлять регуляркой, ему дается _имя_, _состояние_ и _обработчик_. Состояние позволяет _включить_ или _выключить_ фильтр. По имени фильтр можно _удалить_ из списка, например. _Обработчик_, это функция, класс или модуль, которые включают логику о том, что делать с текстом, если _сработал паттерн_ регулярного выражения. Для каждого экземпляра можно настроить свой список фильтров.

## Обработчик

Функция, класс или модуль, которые включают логику обработки текста. Например, найденный текст можно _заменить звездочками_. Количество звездочек можно настроить. Либо это будет стандартно 3 звездочки, либо количество равное длине слова. Также можно установить _фильтр подсвечивающий_ найденное слово, либо заменяющий на стандартный _текст заглушку_. Для каждого фильтра можно добавить свой обработчик.

Обработчик должен иметь только один метод `replace` - функция, которая под капотом подставляется вторым аргументом в одноименную `String.prototype.replace()`. От вас нужена только сама функция, если хотите добавить свою логику. Либо используйте имеющиеся обработчики.

## Плагин

Это очень простые файлы, которые содержат лишь голый _паттерн регулярки_ и метод `install` - который добавляет новый фильтр в список фильтров. Метод получает экземпляр модуля и опции в виде параметров.

Логику самого плагина вы вправе писать какую угодно. Чаще всего через плагины добавляются новые фильтры, по одному на каждый плагин. Хорошим тоном будет добавить паттерн как отдельное свойство плагина `pattern` - тогда его будет легко получить из плагина в любой другой библиотеке или внешнем модуле.

## Использование

```js
var TextCensor = new Censor();
var prepared = TextCensor.filter('Плохой текст, support@google.com - емайл');
// prepared - Плохой текст, ****************** - емайл
```

Конструтор принимает два необязательных параметра `handler` и `filters`. Первый устанавливает _глобальный обработчик_ для всех фильтров. Второй _заменяет собой_ список предустановленных фильтров. Можно просто _отключить_ ненужные и _добавить_ необходимые фильтры, а можно установить полностью свой список.

### $filters

Объект для работы с фильтрами. Через него можно управлять списком фильтров

#### add(name, filter) - добавить фильтр

#### get(name) - получить

#### toggle(name) - включить/выключить

#### enable(name) - включить

#### disable(name) - выключить

## Изменить обработчики

```js
var handler = new handlers/Placeholder();
var Censor = new Censoring(handler);
```

По умолчанию просто звездочки. Но даже сами звездочки можно перенастроить.

## Свой список

```js
var Filters = new Filters();
// ... Настроили список как хотим
var Censor = new Censoring(null, Filters);
```

Когда очень нужны только свои фильтры или индивидуальные обработчики вместо дефолтного. Любые другие причины.