Crate twitch_message

Expand description

This is a crate to parse chat messages from https://www.twitch.tv

This crate does not provide any I/O rather just parsing of a &str into typed messages.

A quick walkthrough:

use twitch_message::messages::*;
// get some data from somewhere
let data: &str = read_line();

// parse returns a `ParseResult` which contains the remaining data (if any) and the parsed message
let result = twitch_message::parse(data)?;
let msg: Message<'_> = result.message;

match msg.kind {
    MessageKind::Ready => {
        let ready = msg.as_typed_message::<Ready>().unwrap();
        println!("connected as: {name}", name = ready.name);
    }
    MessageKind::Privmsg => {
        let pm = msg.as_typed_message::<Privmsg>().unwrap();
        println!("[{channel}] {sender}: {data}",
            channel = pm.channel,
            sender = pm.sender,
            data = pm.data
        );
    }
    MessageKind::Ping => {
        let ping = msg.as_typed_message::<Ping>().unwrap();
        let resp = twitch_message::encode::pong(&ping.token);

        // you can format data to various 'sinks'
        use twitch_message::encode::Formattable;
        let mut out = String::new();
        resp.format(&mut out)?;
        assert_eq!(out, "PONG :1234567890\r\n");
    }
    _ => {}
}

Parsing

There are various parse methods provided by this crate:

parse

This will parse a single message, returning any remaining data

parse_many

This will return an iterator over possibly many messages in the data

parse_as

This is a shorthand for parse + Message::as_typed_message()

parse_badges

This allows you to parse badges from a string

parse_emotes

This allows you to parse emotes from a Twitch emote string + the associated data portion

Typed messages

Once you parse data into a Message, you can further narrow it to a specific type via two methods:

as_typed_message will borrow from the message, forgoing any further allocations.

into_typed_message will clone the data so you’ll have an owned ('static) version of the message

The argument (type) used for these are one of the main structs found in the messages module.

Ownership

If you have a Message<'a> or some sub type (found in messages) and want it to be 'static, a trait is provided:

IntoStatic

This trait is implemented for all of the types. Once you import it, you can do ty.into_static() to get a 'static version of the type.

Why this trait instead of std::borrow::ToOwned? This trait allows more specific lifetime clauses and doesn’t require T: Clone. But in general, its basically used the same way.

Builders

A few builders are provided:

These allow you to construct messages for testing, or for custom purposes (mocking/faking, etc)

Encoding

The encode module provides a typed way of constructing messages to send to Twitch.

By default, only encoding to a core::fmt::Write source (e.g. a String) is supported, via the Format and Formattable traits.

If you enable the std feature (see features), you will have access to the Encode and Encodable traits which operate on a std::io::Write source. (e.g. a Vec<u8> or std::net::TcpStream)

Examples

Format/Formattable

// this adds the # to the channel, if its missing
let pm = twitch_message::encode::privmsg("museun", "hello, world.");

// using `Formattable`
use twitch_message::encode::Formattable;
let mut buf = String::new();
pm.format(&mut buf)?;
assert_eq!(buf, "PRIVMSG #museun :hello, world.\r\n");

// using `Format`
use twitch_message::encode::Format;
let mut buf = String::new();
buf.format_msg(pm)?;
assert_eq!(buf, "PRIVMSG #museun :hello, world.\r\n");

Encode/Encodable

// this adds the # to the channel, if its missing
let pm = twitch_message::encode::privmsg("museun", "hello, world.");

// using `Encodable`
use twitch_message::encode::Encodable;
let mut buf = Vec::new();
pm.encode(&mut buf)?;
assert_eq!(buf, b"PRIVMSG #museun :hello, world.\r\n");

// using `Encode`
use twitch_message::encode::Encode;
let mut buf = Vec::new();
buf.encode_msg(pm)?;
assert_eq!(buf, b"PRIVMSG #museun :hello, world.\r\n");

Features

Feature	Description
default	there are no default features
ping	enables the `PingTracker`
std	enables the `Encode` and `Encodable` traits
serde	enables `serde` derives on the types
hashbrown	enables using `hashbrown` for the internal `HashMap`
sync	enables using `std::sync::Mutex` over `std::cell::RefCell` see `sharing data`
parking_lot	same as `sync` except uses a `parking_lot::Mutex`