# Raku-Lingua-StopwordsISO

## In brief

This is a Raku package for stop words of different languages. 
Follows 
["Stopwords ISO" project](https://github.com/stopwords-iso), [GDr1],
and Raku package 
["Lingua::Stopwords"](https://raku.land/cpan:CHSANCH/Lingua::Stopwords), [CSp1].

This package has the JSON file
["stopwords-iso.json"](https://github.com/stopwords-iso/stopwords-iso/blob/master/stopwords-iso.json)
from [GDr1] as a resource file.   

------

## Usage examples

### `stopwords-iso`

The function `stopwords-iso` takes as an argument a language spec (e.g. 'en' or 'English') and 
returns a `SetHash`:

```perl6
use Lingua::StopwordsISO;

"I Want You To Deal With Your Problems By Becoming Rich!"
        .words
        .map({ $_.lc => $_.lc ��� stopwords-iso('English')})
```
```
# (i => True want => True you => True to => True deal => False with => True your => True problems => True by => True becoming => True rich! => False)
```

If several languages are specified then the result is a `Hash` of `SetHash` objects:

```perl6
stopwords-iso(<Bulgarian Czech English Russian Spanish>)>>.elems
```
```
# {Bulgarian => 259, Czech => 423, English => 1298, Russian => 558, Spanish => 732}
```

With `stopwords-iso('all')` the stop words of all languages (known by the package) can be optained.

### `delete-stopwords`

The function `delete-stopwords` deletes the stop words in a string:

```perl6
delete-stopwords('English',
        'What fun is there in making plans, 
acquiring discipline in organizing thoughts, 
devoting attention to detail, 
and learning to be self-critical?')
```
```
# fun     plans, 
# acquiring discipline  organizing , 
# devoting attention  , 
#  learning   self-critical?
```

The first, language spec argument can be a word ('English', 'Russian', 'Spanish', etc.)
or an abbreviation ('en', 'ru', 'es', etc.)  

If only one argument is given to `delete-stopwords` then the language spec is 'English'.

------

## Command Line Interface (CLI)

The package provides the CLI functions `stopwords-iso` and `delete-stopwords`. 

### `stopwords-iso`

Here is the usage message of `stopwords-iso`:

```shell
> stopwords-iso --help
Usage:
  stopwords-iso [-f|--format=<Str>] [<langs> ...] -- Gives stop words for the specified languages in the specified format.
  stopwords-iso [-f|--format=<Str>] -- Gives stop words for language specs in (pipeline) input.
  
    [<langs> ...]        Languages to get the stop words for.
    -f|--format=<Str>    Output format one of 'text', 'json', or 'raku'. [default: 'text']
```
Here are example shell commands:

```shell
> stopwords-iso bg    
# �� �������������������� ���� ������ ������ ���� ������ �������� ���� �������� ���������� ���������� ������ �������� �������� �������� ������������������ ���������� ���������� �������� �������� 
# �� ������ ������ �������� ���������������� �������� ���������� ���� ������ ������������ �������������� ���������� ������ ���������� ������������ ������������ ���������� ������ �������������� ���������� 
# �� ���� ������������ ������������ ������������ �������� ���� ������������ ������������ �������������� �� ���� �������� ������ ���������� �������������� ������ ���������� ������ �������� ������ ���� 
# ���������� ���������� ���������� ���������� ������������ ������������ �������� ������������ ���������� �������� ���������� ���������� �� ���������� �������� �������� �������� �������������� �������������� 
# �������������� �������� �������� ������ ���������� ���� �������������� ������ ������������ ������������ ������������ ������������ ������������ �������� ������������ �� ���� ������ ���� ������ �������� 
# �������� �� �������� ������ ���������� ���������� ���������� ���������� �������� �������� ������������ ���������� ���������� ������ ���������� ���������� ���������� �������� ������������ ������ ���������� 
# ���������� ���� ������ �� ������ ���������� ���� ���������� ������ ������ ���������� ���� ���������� �������������� �������� ���������� �������� ���������� �������� �������������� ���� �� ���� ������ 
# ���������� ������ �������������� ������������ ���������������� ������ ���� �������� �������� ������ ���� ������ ���������� �������� �������� ���� ������ �������� �������� ������������ ���������� ���������� 
# �������������� �������� ���������� ���������� ���������� �������������� ���� ������������ ������������ ������ ������ ���� ������������ ���������������� ������ �������� ������������ ���������� ���������� 
# ���������� �������� ���������� �������� ������ ������ �������������� ���������� ���������� �������� ���������� ���������� �� ���� ������ �������� ���� �������� ���� ������ ���������� �������� �������������� 
# ������ �������� ������������ �������� ���������� ������ ������ ������ �������� �� ��.��. �������� �������� ������������ ���������� ������ �������� ���� �������� ���� ���� �������� ������������ �������� 
# ������ �������������� ���������� ������ ������������ ������ ������ ���� ������ �� �������� �������������� ������������ �� �������� ���� ���������� �������� ���� ������ ���������� �� ����
```

```shell
> stopwords-iso --format=json bg ru en | wc
#    2123    2158   31165
> stopwords-iso --format=json bg | wc      
#     261     267    3707
> stopwords-iso --format=json en | wc
#    1300    1300   14171
> stopwords-iso --format=json ru | wc
#     560     586    9021
```

### `delete-stopwords`

Here is the usage message of `delete-stopwords`:

```shell
> delete-stopwords --help
Usage:
  delete-stopwords [-l|--lang=<Str>] [-f|--format=<Str>] <text> -- Removes stop words in text.
  delete-stopwords [-l|--lang=<Str>] [-f|--format=<Str>] [<words> ...] -- Removes stop words from a list of words.
  delete-stopwords [-l|--lang=<Str>] [-f|--format=<Str>] -- Removes stop words in (pipeline) input.
  
    <text>               Text to remove stop words from.
    -l|--lang=<Str>      Language [default: 'English']
    -f|--format=<Str>    Output format one of 'text', 'lines', or 'raku'. [default: 'text']
    [<words> ...]        Text to remove stop words from.

```

Here are example shell commands:

```shell
> delete-stopwords -l=bg ���������������������� ���� ���������������� ���� ������������ �� ����������������, ���������� �� ��������������.
# ����������������������  ����������������  ������������  ����������������, ����������  ��������������.
```

```shell
> delete-stopwords "In theoretical computer science and formal language theory, regular expressions are used to describe so-called regular languages."
# theoretical  science  formal language theory, regular expressions     so-called regular languages.
```

```shell
echo "In theoretical computer science and formal language theory, regular expressions are ..." | xargs -n1 | delete-stopwords
# theoretical  science  formal language theory, regular expressions  ...
```
------

## Potential problems

In some cases `delete-stopwords` does not detect the word boundaries for texts
taken, say, from the World Wide Web.
 
This text "works":

```perl6
my $text1 = qq:to/BGEND/;
������������ ������������������ �������������� ���� ������������������ �������������� �������������� ��������������
���� ������������������������������ ���������������������� ���� �������������������� �� �������������������� ���� ������������������
�������� ���������� ������ ���������������������� ������������ �������������� ���� ������������������ ���� ����������������������������
�� �������������������� ����������������������.
BGEND

say delete-stopwords('bg', $text1);
```
```
# ������������ ������������������ ��������������  ������������������ �������������� �������������� ��������������
#  ������������������������������ ����������������������  ��������������������  ��������������������  ������������������
# �������� ����������  ���������������������� ������������ ��������������  ������������������  ����������������������������
#  �������������������� ����������������������.
```

This does not:

```perl6
my $text2 = qq:to/BGEND/;
Ho������e ����������a������ pa����ep�� ��a oc��o��������e ��ece������ pa��o������ ��a����a����
��a ��e��a��o������ec������e c��e����a����c���� ca ��o��o��ope���� c ��o������ca������ ��a o��pac��o��o
������o A��e��c ������ Ko��e�������������� ��py��o�� ��o��o��op ��a c��c��e��a��a ��a ��pe��y������������o��o
�� y������������o��o o��pa��o��a����e.
BGEND

say delete-stopwords('bg', $text2);
```
```
# Ho������e ����������a������ pa����ep�� ��a oc��o��������e ��ece������ pa��o������ ��a����a����
# ��a ��e��a��o������ec������e c��e����a����c���� ca ��o��o��ope���� c ��o������ca������ ��a o��pac��o��o
# ������o A��e��c ������ Ko��e�������������� ��py��o�� ��o��o��op ��a c��c��e��a��a ��a ��pe��y������������o��o
#  y������������o��o o��pa��o��a����e.
```

------

## References

[GDr1] Gene Diaz,
[Stopwords ISO project](https://github.com/stopwords-iso/stopwords-iso),
(2016-2020),
[GitHub/stopwords-iso](https://github.com/stopwords-iso).

[CSp1] Christian S��nchez,
[Lingua::Stopwords Raku package](https://raku.land/cpan:CHSANCH/Lingua::Stopwords),
(2018),
[Raku Land](https://raku.land).