Struct twitchchat::Client

pub struct Client<R> { /* fields omitted */ }

Client for interacting with Twitch's chat.

It wraps a Read, Write pair

use twitchchat::{helpers::TestStream, Client, sync_adapters};
let stream = TestStream::new();
// create a synchronous read and write adapter (shorthand for SyncReadAdapter::new() and SyncWriteAdapter::new())
let (r, w) = sync_adapters(stream.clone(), stream.clone());
let mut client = Client::new(r,w); // moves the r,w
// register, join, on, etc
client.run().unwrap();

Methods

impl<R: ReadAdapter> Client<R>

pub fn new<W>(reader: R, writer: W) -> Self where
    W: WriteAdapter + Send + 'static, 

Create a new Client from a Read, Write pair

This client is clonable, and thread safe.

pub fn into_reader(self) -> R::Reader

Consumes the client, returning the reader

pub fn run(self) -> Result<(), Error>

Runs, consuming all messages.

This also pumping them through Client::on filters

pub fn register<U>(&mut self, config: U) -> Result<(), Error> where
    U: Borrow<UserConfig>, 

Registers with the server uses the provided UserConfig

This is a very useful step, after you make the client and set up your initial filters

You should call this to send your OAuth token and Nickname

This also sends the Capabilities in the correct order

Usage

let config = UserConfig::builder()
                .token(std::env::var("MY_PASSWORD").unwrap())
                .nick("museun")
                .build()
                .unwrap();
client.register(config).unwrap();
// we should be connected now
// this'll block until everything is read
let _ = client.wait_for_ready().unwrap();

pub fn wait_for_ready(&mut self) -> Result<LocalUser, Error>

Waits for the GLOBALUSERSTATE before continuing, discarding any messages received

Returns some useful information about your user

This blocks until the twitch registration is completed, this relies on the Tags Capability being sent.

Usage:

match client.wait_for_ready() {
    Ok(user) => println!("user id: {}", user.user_id),
    Err(err) => panic!("failed to finish registration: {}", err)
};
// we can be sure that we're ready to join
client.writer().join("some_channel").unwrap();

pub fn wait_for_irc_ready(&mut self) -> Result<String, Error>

Like wait_for_ready but waits for the end of the IRC MOTD

This will generally happen before GLOBALUSERSTATE but don't rely on that

Returns the username assigned to you by the server

Usage:

match client.wait_for_irc_ready() {
    Ok(name) => println!("end of motd, our name is: {}", name),
    Err(err) => panic!("failed to finish registration: {}", err),
};
// we can be sure that we're ready to join
client.writer().join("some_channel").unwrap();

pub fn read_message(&mut self) -> Result<Message, Error>

Reads a Message

This 'pumps' the messages through the filter system

Using this will drive the client (blocking for a read, then producing messages). Usage:

// block the thread (i.e. wait for the client to close down)    
while let Ok(msg) = client.read_message() {
    // match msg {
    // .. stuff
    // }
}

// or incrementally calling `client.read_message()`
// when you want the next message

impl<R> Client<R>

pub fn on<F, T>(&mut self, f: F) -> Token where
    F: FnMut(T, Writer) + 'static + Send + Sync,
    T: From<Message>,
    T: MessageFilter, 

When a message is received run this function with it and a clone of the Writer.

The type of the closure determines what is filtered

Usage:

use twitchchat::commands::*;
let pm_tok = client.on(|msg: PrivMsg, w: Writer| {
    // msg is now a `twitchchat::commands::PrivMsg`
});
let join_tok = client.on(|msg: Join, w: Writer| {
    // msg is now a `twitchchat::commands::Join`
});

// if a PRIVMSG or JOIN is parsed here
// the corresponding closure, above, will run
client.read_message();

The available filters are the same names as the structs in commands

When Client::read_message is called, it'll send a copy of the matching message to these filters.

Multiple filters can be 'registered' for the same type

Use the returned token to remove the filter, by passing it to the Client::off method

pub fn off(&mut self, tok: Token) -> bool

Remove a previously registered message filter, using the token returned by on

Returns true if this filter existed

pub fn handler<H>(&mut self, handler: H) -> Token where
    H: Handler + Send + Sync + 'static, 

Add a Handler to the internal filtering

When Client::read_message is called, it'll send a RC message to the appropriate function.

Use the returned token to remove the filter, by passing it to the Client::remove_handler method

pub fn remove_handler(&mut self, tok: Token) -> bool

Remove a previously added handler, using the returned token

Returns true if this handler existed

pub fn writer(&self) -> Writer

Get a clone of the writer