# Textgain

The **Textgain** Elixir package provides a simple interface into the [Textgain](https://www.textgain.com/) web service for natural language processing (NLP) and text analytics.  The analytics services currently available are:
 
* Age
* Concepts
* Education
* Gender
* Genre
* Language
* Part-of-speech tags
* Personality
* Sentiment

## Installation

If [available in Hex](https://hex.pm/packages/textgain), the package can be installed as:

  1. Add `textgain` to your list of dependencies in `mix.exs`:

    ```elixir
    def deps do
      [{:textgain, "~> 0.1.0"}]
    end
    ```

  2. Ensure `textgain` is started before your application:

    ```elixir
    def application do
      [applications: [:textgain]]
    end
    ```

  3. Configure your API key, if you have one, in config.exs:
  
    ```elixir
    config :textgain,
      key: "***"
    ```

## Usage

The package's main API module is `Textgain` which leverages the `service` macro defined in `Textgain.Service` to instantiate endpoints for each Textgain service.  All returned data is decoded into service-specific structs to facilitate leveraging Elixir's pattern matching to process responses.

Additionally, the `Textgain.Service` module exposes a public function `raw_query` which can be used to execute custom queries against the service if necessary.

To use the module, simply call the service by function name in the `Textgain` module, with the text to be analyzed as the first argument followed by a keyword list of optional parameters, per the [API services documentation](https://www.textgain.com/api).  Valid return values are also documented on the API services page.

```elixir
iex(1)> Textgain.age("The quick brown fox jumps over the lazy dog.", lang: "en")
{:ok, %Textgain.Age{age: "25+", confidence: 0.75}}

iex(2)> Textgain.concepts("The quick brown fox jumps over the lazy dog.", lang: "en")
{:ok, %Textgain.Concepts{concepts: ["jump", "fox", "dog"]}}

iex(3)> Textgain.education("The quick brown fox jumps over the lazy dog.", lang: "en")
{:ok, %Textgain.Education{confidence: 0.8, education: "-"}}

iex(4)> Textgain.gender("The quick brown fox jumps over the lazy dog.", lang: "en")
{:ok, %Textgain.Gender{confidence: 0.75, gender: "m"}}

iex(5)> Textgain.genre("The quick brown fox jumps over the lazy dog.", lang: "en")
{:ok, %Textgain.Genre{confidence: 0.95, genre: "review", review: nil}}

iex(6)> Textgain.language("The quick brown fox jumps over the lazy dog.", lang: "en")
{:ok, %Textgain.Language{confidence: 0.95, language: "en"}}

iex(7)> Textgain.personality("The quick brown fox jumps over the lazy dog.", lang: "en")
{:ok, %Textgain.Personality{confidence: 0.6, personality: "E"}}

iex(8)> Textgain.sentiment("The quick brown fox jumps over the lazy dog.", lang: "en")
{:ok, %Textgain.Sentiment{confidence: 0.7, polarity: 0.0}}

iex(9)> Textgain.tag("The quick brown fox jumps over the lazy dog.", lang: "en")
{:ok,
 %Textgain.Tag{confidence: 0.95,
  text: [[[%{"tag" => "DET", "word" => "The"},
     %{"tag" => "ADJ", "word" => "quick"}, %{"tag" => "ADJ", "word" => "brown"},
     %{"tag" => "NOUN", "word" => "fox"},
     %{"tag" => "NOUN", "word" => "jumps"}],
    [%{"tag" => "PREP", "word" => "over"}],
    [%{"tag" => "DET", "word" => "the"}, %{"tag" => "ADJ", "word" => "lazy"},
     %{"tag" => "NOUN", "word" => "dog"}],
    [%{"tag" => "PUNC", "word" => "."}]]]}}
```

The "!" variant for each function also exists, which will return just the service struct or raise an error.