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`

§Utilities

§PingTracker

A PingTracker is provided, and is entirely optional (enabled with the ping feature).

This is a simple type to help you determine when you should respond to a PING message.

§Tag (un)escaping

IRCv3 requires tags to be escaped.

This crate provides a method to escape them, and to unescape them.

NOTE You don’t have to worry about the escape-status of Tags, interally these are used.

These methods are provided for your own use cases.

Twitch chat reference: link

Modules§

builders: Builders for constructing your own types.
encode: This module provides encoding of typed messages
escape: String escaping helpers
messages: Messages

Structs§

Badge: A badge attached to a message
Color: A RGB color triplet
Emote: An emote attached to a message
ParseResult: Representation of a possibly partially parse
PingTrackerping: A simple type to track PINGs and if you should PONG
Tags: Tags are metadata attached to many Twitch messages.

Enums§

Error: Errors produced by this crate
Prefix: An IRC-styled prefix.

Constants§

ANONYMOUS_LOGIN: An anonymous login. This’ll allow you to read messages without an OAuth token
TWITCH_IRC_ADDRESS: The Twitch IRC (tcp) address
TWITCH_IRC_ADDRESS_TLS: The Twitch IRC (tcp/tls) address
TWITCH_TLS_DOMAIN: The TLS domain for Twitch
TWITCH_WS_ADDRESS: The Twitch WebSocket address
TWITCH_WS_ADDRESS_TLS: The Twitch WebSocket TLS address

Traits§

IntoStatic: A trait for converting a T: ’a to a T: ’static

Functions§

parse: Attempt to parse a message.
parse_as: A helper parse function for parsing a string as a specific typed message
parse_badges: Parse badges from a string
parse_emotes: Parse emotes from a tag value and associated data
parse_many: Parses potentionally many messages from the input.

Type Aliases§

BadgeInfo: Currently an alias for Badge

Crate twitch_messageCopy item path