Elefren

A Wrapper for the Mastodon API.

Documentation

A wrapper around the API for Mastodon

Installation

To add elefren to your project, add the following to the [dependencies] section of your Cargo.toml

elefren = "0.18"

Usage

To use this crate in your project, add this to your crate root (lib.rs, main.rs, etc):

extern crate elefren;

Example

In your Cargo.toml, make sure you enable the toml feature:

[dependencies]
elefren = { version = "0.18", features = ["toml"] }

// src/main.rs
extern crate elefren;

use std::error::Error;

use elefren::prelude::*;
use elefren::helpers::toml; // requires `features = ["toml"]`
use elefren::helpers::cli;

fn main() -> Result<(), Box<Error>> {
    let mastodon = if let Ok(data) = toml::from_file("mastodon-data.toml") {
        Mastodon::from(data)
    } else {
        register()?
    };

    let you = mastodon.verify_credentials()?;

    println!("{:#?}", you);

    Ok(())
}

fn register() -> Result<Mastodon, Box<Error>> {
    let registration = Registration::new("https://mastodon.social")
                                    .client_name("elefren-examples")
                                    .build()?;
    let mastodon = cli::authenticate(registration)?;

    // Save app data for using on the next run.
    toml::to_file(&*mastodon, "mastodon-data.toml")?;

    Ok(mastodon)
}

It also supports the Streaming API:

use elefren::prelude::*;
use elefren::entities::event::Event;

use std::error::Error;

fn main() -> Result<(), Box<Error>> {
    let data = Data {
      base: "".into(),
      client_id: "".into(),
      client_secret: "".into(),
      redirect: "".into(),
      token: "".into(),
    };

    let client = Mastodon::from(data);

    for event in client.streaming_user()? {
        match event {
            Event::Update(ref status) => { /* .. */ },
            Event::Notification(ref notification) => { /* .. */ },
            Event::Delete(ref id) => { /* .. */ },
            Event::FiltersChanged => { /* .. */ },
        }
    }
    Ok(())
}

Relationship to Mammut

This library was forked from Mammut around elefren commit 6c37ecb1e1. I started this fork as a place to experiment with some of the changes I wanted to make to Mammut, and ended up diverging enough that I didn't really want to spend the time trying to get everything merged back.

Some of the major differences between this and mammut are:

• Compatibility with newer mastodon versions. Elefren supports new API calls introduced in Mastodon 2.4 and 2.5, and 2.6 support is being worked on.
• Compatibility with other implementations of the Mastodon API. One design goal of elefren is to be compatible with as many implementations of the Mastodon API as possible. Currently, this means the GlitchSoc fork of Mastodon, and Pleroma. I do not guarantee that support is 100% there, but if you find any inconsistencies, it is a bug and I hope you can take the time to open an issue here
• Multiple bug fixes

I have a couple big features on the horizon, the first being a comprehensive test suite that I'm currently working on, which should help us test for inconsistencies and issues between the different versions of the Mastodon API that elefren aims to support. After that, I will be trying to get support for the Mastodon Streaming API merged in, though that might need to wait until rust's async story is a little more stable.

For a complete list of changes, see the Changelog.