circe/async-circe
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases Wiki Activity

Fixed documentation

Browse source
This commit is contained in:
famfo 2022-01-05 11:53:57 +01:00
parent 32fb07646b
commit 8ed4820e0b
9 changed files with 63 additions and 147 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
Cargo.toml
View file

@ -8,7 +8,7 @@ license = "Unlicense"
name = "async-circe"
readme = "README.md"
repository = "https://git.karx.xyz/circe/async-circe.git"
version = "0.2.2"
version = "0.2.3"
[dependencies.toml]
version = "0.5"

17
README.md
View file

@ -11,21 +11,30 @@
To start using Circe, just add the crate to your `Cargo.toml`, and then follow the example below.
```rust
use circe::{Client, Config, Command};
use async_circe::{commands::Command, Client, Config};
fn main() -> Result<(), std::io::Error> {
let config = Default::default();
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), tokio::io::Error> {
let config = Config::new(
&["#chaos", "#async-circe"],
"karx.xyz",
Some("+B"),
Some("async-circe"),
6697,
"circe",
);
let mut client = Client::new(config).await.unwrap();
client.identify().await.unwrap();
loop {
if let Ok(ref command) = client.read().await {
if let Some(command) = client.read().await? {
if let Command::PRIVMSG(nick, channel, message) = command {
println!("{} in {}: {}", nick, channel, message);
}
}
}
}
```
Happy hacking!

2
examples/basic-config/Cargo.lock generated
View file

@ -4,7 +4,7 @@ version = 3
[[package]]
name = "async-circe"
version = "0.2.0"
version = "0.2.2"
dependencies = [
"native-tls",
"tokio",

2
examples/basic-config/src/main.rs
View file

@ -14,7 +14,7 @@ async fn main() -> Result<(), tokio::io::Error> {
client.identify().await.unwrap();
loop {
if let Some(ref command) = client.read().await? {
if let Some(command) = client.read().await? {
if let Command::PRIVMSG(nick, channel, message) = command {
println!("{} in {}: {}", nick, channel, message);
}

2
examples/config-from-toml/Cargo.lock generated
View file

@ -4,7 +4,7 @@ version = 3
[[package]]
name = "async-circe"
version = "0.2.0"
version = "0.2.2"
dependencies = [
"native-tls",
"serde",

2
examples/config-from-toml/src/main.rs
View file

@ -7,7 +7,7 @@ async fn main() -> Result<(), std::io::Error> {
client.identify().await.unwrap();
loop {
if let Some(ref command) = client.read().await? {
if let Some(command) = client.read().await? {
if let Command::PRIVMSG(nick, channel, message) = command {
println!("{} in {}: {}", nick, channel, message);
}

4
examples/debugging/src/main.rs
View file

@ -3,7 +3,7 @@ use async_circe::{commands::Command, Client, Config};
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), tokio::io::Error> {
// This tells tracing to show the debug log when the binary is run with
// CIRCE_LOG="debug"
// CIRCE_LOG="tracing"
tracing_subscriber::fmt()
.with_env_filter(tracing_subscriber::EnvFilter::from_env("CIRCE_LOG"))
.init();
@ -20,7 +20,7 @@ async fn main() -> Result<(), tokio::io::Error> {
client.identify().await.unwrap();
loop {
if let Some(ref command) = client.read().await? {
if let Some(command) = client.read().await? {
if let Command::PRIVMSG(nick, channel, message) = command {
println!("{} in {}: {}", nick, channel, message);
}

75
src/commands.rs
View file

@ -17,15 +17,12 @@ pub enum Command {
// SQUIT <server> <comment>
//
/// Request information about the admin of a given server.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.admin("libera.chat").await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -34,15 +31,12 @@ pub enum Command {
String,
),
/// Set the status of the client.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.away("afk").await?;
/// # Ok(())
/// # }
/// ```
AWAY(
/// Message
@ -51,15 +45,12 @@ pub enum Command {
#[doc(hidden)]
CAP(CapMode),
/// Invite someone to a channel.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.invite("liblemonirc", "#async_circe").await?;
/// # Ok(())
/// # }
/// ```
INVITE(
/// User
@ -68,30 +59,24 @@ pub enum Command {
String,
),
/// Join a channel.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.join("#main").await?;
/// # Ok(())
/// # }
/// ```
JOIN(
/// Channel
String,
),
/// List available channels on an IRC, or users in a channel.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.list(None, None).await?;
/// # Ok(())
/// # }
/// ```
LIST(
/// Channel
@ -100,15 +85,12 @@ pub enum Command {
Option<String>,
),
/// Set the mode for a user.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.mode("test", Some("+B")).await?;
/// # Ok(())
/// # }
/// ```
MODE(
/// Channel
@ -117,15 +99,12 @@ pub enum Command {
Option<String>,
),
/// Get all the people online in channels.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.names("#main,#async_circe", None).await?;
/// # Ok(())
/// # }
/// ```
NAMES(
/// Channel
@ -134,30 +113,24 @@ pub enum Command {
Option<String>,
),
/// Change your nickname on a server.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.nick("Not async-circe").await?;
/// # Ok(())
/// # }
/// ```
NICK(
/// Nickname
String,
),
/// Authentificate as an operator on a server.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.oper("username", "password").await?;
/// # Ok(())
/// # }
/// ```
OPER(
/// Username
@ -168,15 +141,12 @@ pub enum Command {
/// Everything that is not a command
OTHER(String),
/// Leave a channel.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.part("#main").await?;
/// # Ok(())
/// # }
/// ```
PART(
/// Target
@ -185,29 +155,23 @@ pub enum Command {
#[doc(hidden)]
PASS(String),
/// Tests the presence of a connection to a server.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.ping("libera.chat", None).await?;
/// # Ok(())
/// # }
/// ```
PING(String),
#[doc(hidden)]
PONG(String),
/// Send a message to a channel.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.privmsg("#main", "Hello").await?;
/// # Ok(())
/// # }
/// ```
PRIVMSG(
/// Source Nickname
@ -218,15 +182,12 @@ pub enum Command {
String,
),
/// Leave the IRC server you are connected to.
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.quit(None).await?;
/// # Ok(())
/// # }
/// ```
QUIT(
/// Leave message
@ -234,27 +195,21 @@ pub enum Command {
),
/// Get the topic of a channel.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.topic("#main", None).await?;
/// # Ok(())
/// # }
/// ```
/// Set the topic of a channel.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.topic("#main", Some("main channel")).await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.

104
src/lib.rs
View file

@ -1,5 +1,5 @@
//! A simple IRC crate written in rust
//! ```no_run
//! ```run_fut
//! use async_circe::{commands::Command, Client, Config};
//!
//! #[tokio::main(flavor = "current_thread")]
@ -73,13 +73,10 @@ pub struct Config {
impl Client {
/// Creates a new client with a given [`Config`].
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// let mut client = Client::new(config).await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns error if the client could not connect to the host.
@ -116,14 +113,11 @@ impl Client {
/// Identify user and joins the in the [`Config`] specified channels.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// client.identify().await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns error if the client could not write to the stream.
@ -203,9 +197,8 @@ impl Client {
/// Read data coming from the IRC as a [`commands::Command`].
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # use async_circe::*;
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
@ -218,7 +211,6 @@ impl Client {
/// # break;
/// }
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -248,15 +240,13 @@ impl Client {
/// Request information about the admin of a given server.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # use async_circe::*;
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.admin("libera.chat").await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -267,15 +257,12 @@ impl Client {
/// Set the status of the client.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.away("afk").await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -296,15 +283,12 @@ impl Client {
/// Invite someone to a channel.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.invite("liblemonirc", "#async_circe").await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -316,15 +300,12 @@ impl Client {
/// Join a channel.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.join("#main").await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -335,15 +316,12 @@ impl Client {
/// List available channels on an IRC, or users in a channel.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.list(None, None).await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -362,15 +340,12 @@ impl Client {
/// Set the mode for a user.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.mode("test", Some("+B")).await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -385,15 +360,12 @@ impl Client {
/// Get all the people online in channels.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.names("#main,#async_circe", None).await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -409,15 +381,12 @@ impl Client {
/// Change your nickname on a server.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.nick("Not async-circe").await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -428,15 +397,12 @@ impl Client {
/// Authentificate as an operator on a server.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.oper("username", "password").await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -448,15 +414,12 @@ impl Client {
/// Leave a channel.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.part("#main").await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -473,15 +436,12 @@ impl Client {
/// Tests the presence of a connection to a server.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.ping("libera.chat", None).await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -504,15 +464,12 @@ impl Client {
/// Send a message to a channel.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.privmsg("#main", "Hello").await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -524,15 +481,13 @@ impl Client {
/// Leave the IRC server you are connected to.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # use async_circe::*;
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.quit(None).await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -553,27 +508,22 @@ impl Client {
/// Get the topic of a channel.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # use async_circe::*;
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.topic("#main", None).await?;
/// # Ok(())
/// # }
/// ```
/// Set the topic of a channel.
/// # Example
/// ```no_run
/// # #[tokio::main(flavor = "current_thread")]
/// # async fn main() -> Result<(), tokio::io::Error> {
/// ```run_fut
/// # let config = Default::default();
/// # let mut client = Client::new(config).await?;
/// # client.identify().await?;
/// client.topic("#main", Some("main channel")).await?;
/// # Ok(())
/// # }
/// ```
/// # Errors
/// Returns IO errors from the TcpStream.
@ -605,6 +555,7 @@ impl Config {
/// Create a new config for the client
/// # Example
/// ```rust
/// # use async_circe::Config;
/// let config = Config::new(
/// &["#main", "#async_circe"],
/// "karx.xyz",
@ -659,9 +610,10 @@ impl Config {
/// Allows for configuring async-circe at runtime.
/// # Example
/// ```no_run
/// ```run_fut
/// # use async_circe::Config;
/// let config = Config::runtime_config(
/// vev!["#main".to_string(), "#async_circe".to_string()],
/// vec!["#main".to_string(), "#async_circe".to_string()],
/// "karx.xyz".to_string(),
/// Some("+B".to_string()),
/// Some("async-circe".to_string()),
@ -717,7 +669,7 @@ impl Config {
/// port = 6667
/// username = "circe"
/// ```
/// ```no_run
/// ```run_fut
/// let config = Config::from_toml("Config.toml")?;
/// ```
/// # Errors