# `Text.Sentiment.Lexicons.AFINN`
[🔗](https://github.com/kipcole9/text/blob/v0.5.0/lib/sentiment/lexicons/afinn.ex#L1)

Bundled [AFINN](https://github.com/fnielsen/afinn) sentiment lexicons.

AFINN is a list of words rated for sentiment polarity on an integer
scale from `-5` (extremely negative) to `+5` (extremely positive),
with `0` reserved for neutral terms. The English list (`AFINN-165`)
has roughly 3,400 entries; community translations cover ~100
additional languages at varying quality.

All AFINN data is distributed under the Apache 2.0 license, the same
as this package, and is bundled in `priv/sentiment/`.

This module exposes:

* `lexicon/1` — returns the AFINN word→score map for a language tag,
  plus two synthetic lexicons:
    * `:emoticon` — text emoticons (`:-)`, `:(`, `<3`, …).
    * `:emoji`    — Unicode emoji, derived from the
      [Emoji Sentiment Ranking 1.0](http://kt.ijs.si/data/Emoji_sentiment_ranking/)
      corpus and rescaled to AFINN's −5..+5 range.

* `negators/1` — returns the per-language list of negation phrases
  used by `Text.Sentiment.Backends.Lexicon` to flip polarity for the
  word that follows. The English fallback is used when a language
  has no negator list.

* `available/0` — every loaded language tag, including `:emoji` and
  `:emoticon`.

## Quality note

The English (`:en`), Danish (`:da`), Finnish (`:fi`), French
(`:fr`), Polish (`:pl`), Swedish (`:sv`), and Turkish (`:tr`)
lexicons are hand-curated by the upstream AFINN project. The other
~95 language lexicons are machine-translated derivatives from the
same upstream source — useful as a baseline, but expect noisier
scores for low-resource languages.

## Tag list

Language tags are the upstream filenames lower-cased: typically
ISO 639-1 two-letter codes (`:en`, `:de`, `:ja`), occasionally
three-letter codes (`:ceb`, `:haw`, `:hmn`), and one BCP-47-style
tag (`:"zh-tw"`). Note that the upstream uses the legacy ISO
codes `:iw` for Hebrew and `:jw` for Javanese; modern code values
are `:he` and `:jv` respectively.

Use `available/0` to enumerate the tags loaded into the running
build.

# `tag`

```elixir
@type tag() :: atom()
```

An AFINN language tag, plus the synthetic `:emoticon` / `:emoji`.

# `available`

```elixir
@spec available() :: [tag()]
```

Returns the list of every loaded AFINN language tag, sorted.

The list always includes the synthetic `:emoticon` and `:emoji`
lexicons.

### Examples

    iex> :en in Text.Sentiment.Lexicons.AFINN.available()
    true

    iex> :emoji in Text.Sentiment.Lexicons.AFINN.available()
    true

# `has_negators?`

```elixir
@spec has_negators?(atom()) :: boolean()
```

Returns `true` if `tag` has a curated negator list.

### Examples

    iex> Text.Sentiment.Lexicons.AFINN.has_negators?(:en)
    true

    iex> Text.Sentiment.Lexicons.AFINN.has_negators?(:nonexistent)
    false

# `lexicon`

```elixir
@spec lexicon(tag()) :: %{required(String.t()) =&gt; integer()}
```

Returns the bundled AFINN lexicon for `tag` as a `%{token =>
integer}` map.

Raises `ArgumentError` if `tag` is not in `available/0`.

### Examples

    iex> Text.Sentiment.Lexicons.AFINN.lexicon(:en) |> Map.get("good")
    3

    iex> Text.Sentiment.Lexicons.AFINN.lexicon(:fr) |> Map.get("excellent")
    4

    iex> Text.Sentiment.Lexicons.AFINN.lexicon(:emoticon) |> Map.get(":-)")
    2

    iex> Text.Sentiment.Lexicons.AFINN.lexicon(:emoji) |> Map.get("😂")
    2

# `negators`

```elixir
@spec negators(atom()) :: [String.t()]
```

Returns the list of negation phrases for the given language tag,
used by `Text.Sentiment.Backends.Lexicon` to flip the polarity of
the word immediately following a negator.

Falls back to a built-in English negator list when the tag has no
curated entry.

### Examples

    iex> "not" in Text.Sentiment.Lexicons.AFINN.negators(:en)
    true

    iex> Text.Sentiment.Lexicons.AFINN.negators(:fr) |> Enum.take(1) |> length()
    1

---

*Consult [api-reference.md](api-reference.md) for complete listing*