# Грамматические и смысловые преобразования русских слов и предложений

Класс использует грамматические правила, а не словари. Исключение: для работы методов преобразования слов из одной части речи в другую используется Yandex.Speller. Класс хорошо подходит для работы с формальными утверждениями, структурными высказываниями, а также со словами, для которых не существует словарных синонимов - например, сложными научными терминами.  

## Функционал: 

1. Выделение в тексте частей речи 
2. Удаление окончаний у слов по двум алгоритмам (Мартина Поттера и по словарю окончаний)
3. Преобразование текста в массив слов
4. Очистка текста от незначимых частей речи
5. Поиск в тексте объекта, подлежащего и определения
6. Образование словоформ от стэмов слов
7. Преобразование прилагательных, являющимися определениями в тексте, в существительные
8. Преобразование существительных, являющихся субъектами в тексте, в прилагательные 
9. Преобразование слов из одной части речи в другую
10. Добавление оконечных суффиксов к стэмам
12. Образование возможных суффиксальных словоформ от слова 

## Установка

```shell
composer require zoviet/lexicon
```

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

См. examples.php для более подробной информации.

### Возвращаемые указатели типа и их интерпретация

- 'UNKN' => 'Не определено',
- 'PRES' => 'Предлог',
- 'NUMS' => 'Числительное',
- 'ADVS' => 'Наречие',
- 'NOUNS' => 'Существительное',
- 'VERBS' => 'Глагол',
- 'PARTS' => 'Причастие',
- 'ADJS' => 'Прилагательное',
- 'UNIS' => 'Союзы'

Эта интерпретация доступна в константе TYPES;


### Статические методы (для обработки слов)

- test_word($word,FALSE|TRUE) - Определение части речи слова, вторым параметром передается необходимость интерпретации в текстовом виде (по умолчанию FALSE).

 
```php
echo \Lexicon\Semantic::test_word('курица');

//Вернет: NOUNS

echo \Lexicon\Semantic::test_word('курица',TRUE);

//Вернет: Существительное

```

- remove_ending($word,$type=FALSE) - Избавление слова от окончаний по словарю окончаний, второй параметр - указатель на то, как интерпретировать слово (например, 'PARTS' - причастие. Не обязательно)

```php
echo \Lexicon\Semantic::remove_ending('курица');

//Вернет: куриц

echo \Lexicon\Semantic::remove_ending('курица','ADVS');

//Вернет: курица

```
- stem($word) - Стемминг слова по алгоритму Мартина Портера. 

```php
echo \Lexicon\Semantic::stem('гиперборейский');

//Вернет: гиперборейск
```

- transform($word,$type,FALSE) - Трансформация слова в другой тип (из существительного в прилагательное и обратно), указатель на который передается вторым параметром, третьим параметром передается необходимость получения массива вариантов, а не единственного с наибольшей доверительной вероятностью. Метод использует Speller. 

```php
echo \Lexicon\Semantic::transform('ботаник','ADJS');

//Вернет: ботанический

echo \Lexicon\Semantic::transform('некоторый','ADJS');

//Вернет FALSE, т.к. некоторый - не существительное

echo \Lexicon\Semantic::transform('аалдрораловавыаффвыпрафп','ADJS');

//Вернет NULL, т.к. преобразование не получилось

```
- remove_suffix($word,$type) - Рекурсивно убирает все суффиксы слова тип type (например, VERBS - глагол). Может принимать слова, уже лишенные окончаний. 	 

```php
echo \Lexicon\Semantic::remove_suffix('патологоанатомический','ADJS');

//Вернет: патологоанат

```
- add_suffix($stem,$type,FALSE) - Добавляет суффиксы типа type к стэмму (слову без суффиксов) с проверкой получившегося словаря вариантов. При третьем параметре, установленном в TRUE вернет не один вариант с наибольшей доверительной вероятностью, а словарь с ключами в виде доверительности. Использует Speller.

```php
echo \Lexicon\Semantic::add_suffix('ботан','ADJS');

//Вернет: ботанический

\Lexicon\Semantic::add_suffix('лис','ADJS');

//Вернет: ["лисянский"]=>
  int(5)
  ["лысенький"]=>
  int(3) 
  ["лисицкий"]=>
  int(3)
  ["лысоватый"]=>
  int(3) 
  ["лисовский"]=>
  int(2)
  ["листоватый"]=>
  int(2)
  ["лесистый"]=>
  int(2) 
  ["лосский"]=>
  int(2)


```
- forms ($stem,$type) - получение массива всех "грязных" словоформ от стемма по типу type.

```php
var_dump (\Lexicon\Semantic::forms('лис','ADJS'));

//Вернет: array(94) {[0]=>
  string(26) "лисоватенький"
  [1]=>
  string(26) "лисоватенькый"
  [2]=>
  string(26) "лисеватенький"
  [3]=>
  string(26) "лисеватенькый"
  [4]=>
  string(22) "лисехонький"
  [5]=>
  string(22) "лисехонькый"
  [6]=>
  string(22) "лисохонький"
  [7]=>
  string(22) "лисохонькый"
  [8]=>
  string(22) "лисешенький"
  [9]=>
  string(22) "лисешенькый"
  [10]=>
  string(22) "лисошенький"
  
  и т д

```

### Методы обработки текста: фразы, высказывания, предложения

#### Инициализация

```php

$semantic = new \Lexicon\Semantic();

//или инициализация с передачей текста:

$semantic = new \Lexicon\Semantic('Программное обеспечение P позволяет рационально организовать распорядок дня и освободить до 70% времени.');

```

#### Сквозные свойства

- string - содержит исходную фразу со всеми базовыми ее преобразованиями (если они были)

- words - массив слов текста по очереди их появления в нем. Создается либо методом words либо автоматически при вызове любого метода обработки

- result - хранит результаты грамматического разбора текста в виде массива по частям речи с полными словами или (если были применены методы массовой работы с окончаниями) стэммы слов

Если для метода не указано иное, то результатом его работы является изменение сквозных свойств класса.

#### Методы базовой обработки текста

Если для методов не указаны передаваемые свойства, значит их нет. 

- text(строка) - передача текста на обработку
- remove_braces() - удалить из текста скобки вместе с их содержимым
- words(array=NULL) - преобразование строки в массив слов без переданных свойств либо установка в виде массива слов класса переданного массива
- remove_pres() - удаление из массива слов предлогов
- remove_unis() - удаление союзов
- remove_nums() - удаление числительных
- remove_all() - применение всех вышеперечисленных удалений
- remover($array) - удаление из массива слов и знаков, переданных в виде массива  

```php
$string = 'Программное обеспечение (P) позволяет чуть более рационально организовать распорядок дня и освободить до 70% времени.';

$semantic->text($string)->remove_braces()->words()->remove_all()->remover(array('%','.'));

var_dump($semantic->words);

//Вернет

array(9) {
  [0]=>
  string(22) "Программное"
  [1]=>
  string(22) "обеспечение"
  [2]=>
  string(18) "позволяет"
  [3]=>
  string(22) "рационально"
  [4]=>
  string(24) "организовать"
  [5]=>
  string(20) "распорядок"
  [6]=>
  string(6) "дня"
  [7]=>
  string(20) "освободить"
  [8]=>
  string(14) "времени"
}

```
#### Разбор текста на части речи

Метод устанавливают свойство result класса. 

- explore() 

```php
$string = 'Программное обеспечение (P) позволяет чуть более рационально организовать распорядок дня и освободить до 70% времени.';

$semantic->text($string)->remove_braces()->words()->remove_all()->explore();

//или если предварительный разбор не нужен, а текст передан через конструктор

$semantic->explore();

var_dump($semantic->result);

//Вернет

 ["ADJS"]=>
  array(2) {
    [0]=>
    string(22) "Программное"
    [1]=>
    string(22) "обеспечение"
  }
  ["VERBS"]=>
  array(3) {
    [0]=>
    string(18) "позволяет"
    [1]=>
    string(24) "организовать"
    [2]=>
    string(20) "освободить"
  }
  ["ADVS"]=>
  array(1) {
    [0]=>
    string(22) "рационально"
  }
  ["NOUNS"]=>
  array(3) {
    [0]=>
    string(20) "распорядок"
    [1]=>
    string(6) "дня"
    [2]=>
    string(14) "времени"
  }
}

```
#### Работа с окончаниями и суффиксами

- stemming() - удаление окончаний по словарю. Если метод применить ТО разбора текста на части речи, то окончания будут убраны в массиве слов (words), если после, то в массиве частей речи (results).

```php
$string = 'Программное обеспечение (P) позволяет чуть более рационально организовать распорядок дня и освободить до 70% времени.';

$semantic->text($string)->remove_braces()->words()->remove_all()->explore()->stemming();

var_dump($semantic->result);

//Вернет:

 ["ADJS"]=>
  array(2) {
    [0]=>
    string(18) "программн"
    [1]=>
    string(18) "обеспечен"
  }
  ["VERBS"]=>
  array(3) {
    [0]=>
    string(14) "позволя"
    [1]=>
    string(20) "организова"
    [2]=>
    string(14) "освобод"
  }
  ["ADVS"]=>
  array(1) {
    [0]=>
    string(14) "рациона"
  }
  ["NOUNS"]=>
  array(3) {
    [0]=>
    string(16) "распоряд"
    [1]=>
    string(4) "дн"
    [2]=>
    string(12) "времен"
  }
}


$semantic->text($string)->stemming();

var_dump($semantic->words);

//Вернет:

 [0]=>
  string(18) "программн"
  [1]=>
  string(18) "обеспечен"
  [2]=>
  string(14) "позволя"
  [3]=>
  string(14) "рациона"
  [4]=>
  string(20) "организова"
  [5]=>
  string(16) "распоряд"
  [6]=>
  string(4) "дн"
  [7]=>
  string(14) "освобод"
  [8]=>
  string(12) "времен"
}


```
#### Выделение субъектов, предиктов и определений

Методы вероятностные, выделение не гарантируется. Работают как с массивом слов, так и с массивом стэмов.

- subject() - выделение субъекта - наиболее "значимого" существительного. Возвращает существительное или NULL если не найдно.
- defenition() - то же для прилагательных.
- predict() - то же для предикта. 

```php
$string = 'Программное обеспечение (P) позволяет чуть более рационально организовать распорядок дня и освободить до 70% времени.';

echo 'Предикт:'. $semantic->text($string)->predict();
echo ' | Субъект:'. $semantic->subject();
echo ' | Отношение:'. $semantic->definition();

//Вернет:

Предикт:позволяет | Субъект:распорядок | Отношение:Программное

```
#### Преобразования между частями речи строки

- to_noun(FALSE) - Преобразует значимое прилагательное (найдет сам) (отношение) в существительное. Возвращает одно значение (наиболее вероятное) при запуске без свойств или массив (словарь) слов при TRUE. Используется Speller;
- to_adj(false) - то же самое, только в обратную сторону

```php
$string = 'Программное обеспечение (P) позволяет чуть более рационально организовать распорядок дня и освободить до 70% времени.';

echo 'Новый субъект:'. $semantic->text($string)->to_noun();
echo ' | Новое отношение:'. $semantic->to_adj();

//Вернет:

Новый субъект:программа | Новое отношение:распорядительный

```

- analise($deep) - Глубокое преобразование на заданную глубину вложения. Подразумевается работа со значительно усложенными утверждениями. Глубина - число рассматриваемых для анализа сущностей (прилагательных и существительных). Возвращает ассоциированный массив уровней раскрытия и соответсвующих им субъектов.

```php
$string = 'Программное обеспечение (P) позволяет чуть более рационально организовать распорядок дня и освободить до 70% времени.';

var_dump ($semantic->text($string)->analise(2));

//Вернет:

array(2) {
  ["level"]=>
  array(3) {
    [0]=>
    string(32) "распорядительный"
    [1]=>
    string(10) "новый"
    [2]=>
    string(18) "временный"
  }
  ["subject"]=>
  array(2) {
    [0]=>
    string(16) "программа"
    [1]=>
    string(20) "беспечность"
  }
}

```
Обработка такого массива: отнесения уровня раскрытия к субъекту. Например, в случае из примера выше массив может быть прочтен как "распорядительный программа - новый временный беспечность". После обработки спеллером: "распорядительная программа - новая временная беспечность".