# Wiki Elixir

Unofficial Elixir client modules for connecting to Wikipedia and other MediaWiki sites.  Supports Action, EventStreams, and Ores.

API reference for the current version: [Documentation and examples](https://hexdocs.pm/wiki_elixir/api-reference.html)

Overview:
* `Wiki.Action` connects to the [Action API](https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page),
a rich set of commands to query or edit almost anything on a wiki.
* `Wiki.EventStreams` to access [EventStreams](https://wikitech.wikimedia.org/wiki/Event_Platform/EventStreams),
a real-time feed of events.
* `Wiki.Ores` to access the [ORES](https://www.mediawiki.org/wiki/ORES) service [API](https://ores.wikimedia.org/v3/),
machine-learning models for estimating revision and edit quality.

This library is beta-quality, and written by a beginning Elixir programmer so
please suggest improvements.  The public interface will evolve, and this
[0.x](https://semver.org/) series in particular are likely to include breaking changes
between versions.  These will be documented in the [change log](CHANGELOG.md).

## Installation

Install this package by adding `wiki_elixir` to your dependencies in `mix.exs`,

```elixir
def deps do
  [
    {:wiki_elixir, "~> 0"}
  ]
end
```

Documentation is generated with `mix docs`.

## Usage

A simple call to the action API,

```elixir
Wiki.Action.new("https://de.wikipedia.org/w/api.php")
|> Wiki.Action.get(
  action: :query,
  meta: :siteinfo,
  siprop: :statistics
)
|> (&(&1.result)).()
|> Jason.encode!(pretty: true)
|> IO.puts()
```
```json
{
  "batchcomplete": true,
  "query": {
    "statistics": {
      "activeusers": 19948,
      "admins": 187,
      "articles": 2581769,
      "edits": 211058765,
      "images": 130162,
      "jobs": 0,
      "pages": 7159441,
      "queued-massmessages": 0,
      "users": 3712677
    }
  }
}
```

See the module documentation for detailed usage and more examples.

### Error handling

Methods are all assertive, and will throw a `RuntimeError` with details about the
API error, or a `Tesla.Error` if a network failure is detected.

### Defaults

These parameters are set by default, but can be overridden by including again in an outer caller,

* The `:format` parameter defaults to `:json`.
* `:formatversion` defaults to `2`.

A few configuration variables are available under the `:wiki_elixir` application,
but setting is not mandatory.  Example overrides can be seen in
[config/test.exs](config/test.exs), in this case to mock network access.

* `:eventsource_adapter` - Defaults to `HTTPoison`, this will be used for the
EventStreams HTTP client.
* `:eventstream_endpoint` - API endpoint for `Wiki.EventStreams`, might be
overridden to target a staging server for example.
* `:ores_endpoint` - API endpoint for `Wiki.Ores`.
* `:tesla_adapter` - This will fall back to `Tesla.Adapter.Hackney`, as a stable
client which performs certificate validation.
* `:user_agent` - Sent in request headers, defaults to `wiki_elixir/<version>`...

## Development

Find the [project homepage](https://gitlab.com/adamwight/wiki_elixir) on GitLab.
To contribute, please write a bug or merge request, or contact the author.

Several linters are configured, and may be run directly or called transparently
by installing the git pre-push hook,

```shell script
mix git_hooks.install
```

Then, `git push` will run all tests by default.  To push without passing tests, `git push --no-verify` to a branch.

To generate a test coverage report,
```shell script
mix coveralls.html
```