[−][src]Crate twitchchat
A simple "connection-less" twitch chat crate
This crate simply read lines from an std::io::Read
and produces data
types for the corresponding messages, and takes an std::io::Write
which
can produce messages that twitch understands.
'Theory' of operation
First, by creating a Client
from a
Read/Write pair (such as a cloned TcpStream) then calling
Client::register
with a
filled-out UserConfig
will connect you to
Twitch. Once connected, you can
Client::wait_for_ready
and the client will read (blocking) until Twitch sends a
GlobalUserState
message,
which it'll fill out a LocalUser
with
various information.
Once connected, you can
- use
Client::join
to join a channel. - use
Client::on
to set up a message filter. - use
Client::read_message
to read a message (and pump the filters). - or do various other things
Message filters, and why blocking in them is a bad idea
The client provides a very simplistic callback registration system
To use it, you simply just register
a closure with the client via its
Client::on
method. It uses the
type of the closures argument, one of
these to create a filter
When Client::read_message
is called, it'll check these filters and send a clone of the requested message
to the callback. Because it does this on same thread as the
Client::read_message
call, you can lock up the system by simplying diverging.
The client is thread safe, and clonable so one could call
Client::read_message
with ones own sychronization scheme to allow for a simplistic thread pool,
but its best just to send the message off to a channel elsewhere
A simple example
use std::net::TcpStream; use twitchchat::{commands::PrivMsg, Capability, Client}; use twitchchat::{TWITCH_IRC_ADDRESS, UserConfig}; // create a simple TcpStream let read = TcpStream::connect(TWITCH_IRC_ADDRESS).expect("to connect"); let write = read .try_clone() .expect("must be able to clone the tcpstream"); // your password and your nickname // the twitch oauth token must be prefixed with `oauth:your_token_here` let (pass, nick) = (std::env::var("MY_TWITCH_OAUTH_TOKEN").unwrap(), "my_name"); let config = UserConfig::builder() .token(pass) .nick(nick) .build() .unwrap(); // client takes a std::io::Read and an std::io::Write let mut client = Client::new(read, write); // register with the user configuration client.register(config).unwrap(); // wait for everything to be ready (blocks) let user = client.wait_for_ready().unwrap(); println!( "connected with {} (id: {}). our color is: {}", user.display_name.unwrap(), user.user_id, user.color.unwrap_or_default() ); // when we receive a commands::PrivMsg print out who sent it, and the message // this can be done at any time, but its best to do it early client.on(|msg: PrivMsg| { // this prints out name: msg let name = msg.display_name().unwrap_or_else(|| msg.irc_name()); println!("{}: {}", name, msg.message()) }); // join a channel client.join("museun").unwrap(); // sends a message to the channel client.send("museun", "VoHiYo").unwrap(); // blocks the thread, but any callbacks set in the .on handlers will get their messages client.run();
TestStream
TestStream
is a simple TcpStream-like mock.
It lets you inject/read its internal buffers, allowing you to easily write
unit tests for the Client
UserConfig
UserConfig
is required to Client::register
(e.g. complete the connection) with Twitch
use twitchchat::UserConfig; let my_token = std::env::var("MY_TWITCH_OAUTH_TOKEN").unwrap(); let my_name = "my_name_123"; let config = UserConfig::builder() .nick(my_name) // sets you nick .token(my_token) // sets you password (e.g. oauth token. must start with `oauth:`) // capabilities these are enabled by default. so using these "toggles" the flag (e.g. flips a boolean) .membership() // this disables the membership CAP .commands() // this disables the commands CAP .tags() // this disables the tags CAP .build() // create the config .unwrap(); // returns an Option, None if nick/token aren't semi-valid
The irc module
The irc
module contains a very simplistic
representation of the IRC protocol.
Modules
commands | An assortment of Twitch commands |
helpers | Helpers for writing tests |
irc | IRC-related stuff |
Structs
Badge | Badges attached to a message |
Channel | Simple channel wrapper. |
Client | Client for interacting with Twitch's chat. |
Emotes | Emotes are little pictograms used inline in twitch messages |
LocalUser | Information gathered during the |
RGB | A 24-bit triplet for hex colors. Defaults to White |
Token | A Token returned by the |
UserConfig | Configuration used to complete the 'registration' with the irc server |
Enums
BadgeKind | BadgeKind are the |
Capability | Capabilities allow you to get more data from twitch |
Error | An error that the |
Message | Messages created by the |
TwitchColor | These are the default Twitch colors |
Constants
TWITCH_IRC_ADDRESS | The Twitch IRC address for non-TLS connections |
TWITCH_IRC_ADDRESS_TLS | The Twitch IRC address for TLS connections |
Traits
ClientExt | Client extensions |
Functions
colors | A helper method that returns a const array of |