DGNum/rust-irc
6
0
Fork 0
Code Issues 1 Pull requests 3 Projects Releases Packages Wiki Activity Actions

Rustdoc comments now end consistently in periods.

Browse source
This commit is contained in:
Aaron Weiss 2014-11-06 15:23:02 -05:00
parent 8d37f71c3a
commit 2b7129c74a
7 changed files with 69 additions and 65 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
src/conn.rs
View file

@ -1,11 +1,11 @@
//! Thread-safe connections on any IrcWriters and IrcReaders //! Thread-safe connections on any IrcWriters and IrcReaders.
#![experimental] #![experimental]
use std::sync::{Mutex, MutexGuard}; use std::sync::{Mutex, MutexGuard};
use std::io::{BufferedReader, BufferedWriter, IoResult, TcpStream}; use std::io::{BufferedReader, BufferedWriter, IoResult, TcpStream};
use data::kinds::{IrcWriter, IrcReader}; use data::kinds::{IrcWriter, IrcReader};
use data::message::Message; use data::message::Message;
/// A thread-safe connection /// A thread-safe connection.
#[experimental] #[experimental]
pub struct Connection<T, U> where T: IrcWriter, U: IrcReader { pub struct Connection<T, U> where T: IrcWriter, U: IrcReader {
writer: Mutex<T>, writer: Mutex<T>,
@ -13,7 +13,7 @@ pub struct Connection<T, U> where T: IrcWriter, U: IrcReader {
} }
impl Connection<BufferedWriter<TcpStream>, BufferedReader<TcpStream>> { impl Connection<BufferedWriter<TcpStream>, BufferedReader<TcpStream>> {
/// Creates a thread-safe TCP connection to the specified server /// Creates a thread-safe TCP connection to the specified server.
#[experimental] #[experimental]
pub fn connect(host: &str, port: u16) -> IoResult<Connection<BufferedWriter<TcpStream>, BufferedReader<TcpStream>>> { pub fn connect(host: &str, port: u16) -> IoResult<Connection<BufferedWriter<TcpStream>, BufferedReader<TcpStream>>> {
let socket = try!(TcpStream::connect(format!("{}:{}", host, port)[])); let socket = try!(TcpStream::connect(format!("{}:{}", host, port)[]));
@ -22,7 +22,7 @@ impl Connection<BufferedWriter<TcpStream>, BufferedReader<TcpStream>> {
} }
impl<T, U> Connection<T, U> where T: IrcWriter, U: IrcReader { impl<T, U> Connection<T, U> where T: IrcWriter, U: IrcReader {
/// Creates a new connection from any arbitrary IrcWriter and IrcReader /// Creates a new connection from any arbitrary IrcWriter and IrcReader.
#[experimental] #[experimental]
pub fn new(writer: T, reader: U) -> Connection<T, U> { pub fn new(writer: T, reader: U) -> Connection<T, U> {
Connection { Connection {
@ -31,7 +31,7 @@ impl<T, U> Connection<T, U> where T: IrcWriter, U: IrcReader {
} }
} }
/// Sends a Message over this connection /// Sends a Message over this connection.
#[experimental] #[experimental]
pub fn send(&self, message: Message) -> IoResult<()> { pub fn send(&self, message: Message) -> IoResult<()> {
let mut send = self.writer.lock(); let mut send = self.writer.lock();
@ -39,13 +39,13 @@ impl<T, U> Connection<T, U> where T: IrcWriter, U: IrcReader {
send.flush() send.flush()
} }
/// Receives a single line from this connection /// Receives a single line from this connection.
#[experimental] #[experimental]
pub fn recv(&self) -> IoResult<String> { pub fn recv(&self) -> IoResult<String> {
self.reader.lock().read_line() self.reader.lock().read_line()
} }
/// Acquires the Writer lock /// Acquires the Writer lock.
#[experimental] #[experimental]
pub fn writer<'a>(&'a self) -> MutexGuard<'a, T> { pub fn writer<'a>(&'a self) -> MutexGuard<'a, T> {
self.writer.lock() self.writer.lock()

10
src/data/command.rs
View file

@ -1,9 +1,9 @@
//! Enumeration of all available client commands //! Enumeration of all available client commands.
#![stable] #![stable]
use std::io::{InvalidInput, IoError, IoResult}; use std::io::{InvalidInput, IoError, IoResult};
use data::message::Message; use data::message::Message;
/// List of all client commands as defined in [RFC 2812](http://tools.ietf.org/html/rfc2812) /// List of all client commands as defined in [RFC 2812](http://tools.ietf.org/html/rfc2812).
#[stable] #[stable]
#[deriving(Show, PartialEq)] #[deriving(Show, PartialEq)]
pub enum Command<'a> { pub enum Command<'a> {
@ -131,7 +131,7 @@ pub enum Command<'a> {
} }
impl<'a> Command<'a> { impl<'a> Command<'a> {
/// Converts a Command into a Message /// Converts a Command into a Message.
#[stable] #[stable]
pub fn to_message(self) -> Message { pub fn to_message(self) -> Message {
match self { match self {
@ -226,7 +226,7 @@ impl<'a> Command<'a> {
} }
} }
/// Converts a Message into a Command /// Converts a Message into a Command.
#[stable] #[stable]
pub fn from_message(m: &'a Message) -> IoResult<Command<'a>> { pub fn from_message(m: &'a Message) -> IoResult<Command<'a>> {
/* FIXME: Re-write this using match as so: /* FIXME: Re-write this using match as so:
@ -757,7 +757,7 @@ impl<'a> Command<'a> {
} }
} }
/// Produces an invalid_input IoError /// Produces an invalid_input IoError.
#[stable] #[stable]
fn invalid_input() -> IoError { fn invalid_input() -> IoError {
IoError { IoError {

28
src/data/config.rs
View file

@ -1,36 +1,36 @@
//! JSON configuration files using libserialize //! JSON configuration files using libserialize.
#![stable] #![stable]
use std::collections::HashMap; use std::collections::HashMap;
use std::io::fs::File; use std::io::fs::File;
use std::io::{InvalidInput, IoError, IoResult}; use std::io::{InvalidInput, IoError, IoResult};
use serialize::json::decode; use serialize::json::decode;
/// Configuration data /// Configuration data.
#[deriving(Clone, Decodable, PartialEq, Show)] #[deriving(Clone, Decodable, PartialEq, Show)]
#[unstable] #[unstable]
pub struct Config { pub struct Config {
/// A list of the owners of the bot by nickname /// A list of the owners of the bot by nickname.
pub owners: Vec<String>, pub owners: Vec<String>,
/// The bot's nickname /// The bot's nickname.
pub nickname: String, pub nickname: String,
/// The bot's username /// The bot's username.
pub username: String, pub username: String,
/// The bot's real name /// The bot's real name.
pub realname: String, pub realname: String,
/// The bot's password /// The bot's password.
pub password: String, pub password: String,
/// The server to connect to /// The server to connect to.
pub server: String, pub server: String,
/// The port to connect on /// The port to connect on.
pub port: u16, pub port: u16,
/// A list of channels to join on connection /// A list of channels to join on connection.
pub channels: Vec<String>, pub channels: Vec<String>,
/// A map of additional options to be stored in config /// A map of additional options to be stored in config.
pub options: HashMap<String, String>, pub options: HashMap<String, String>,
} }
impl Config { impl Config {
/// Loads a JSON configuration from the desired path /// Loads a JSON configuration from the desired path.
#[stable] #[stable]
pub fn load(path: Path) -> IoResult<Config> { pub fn load(path: Path) -> IoResult<Config> {
let mut file = try!(File::open(&path)); let mut file = try!(File::open(&path));
@ -42,13 +42,13 @@ impl Config {
}) })
} }
/// Loads a JSON configuration using the string as a UTF-8 path /// Loads a JSON configuration using the string as a UTF-8 path.
#[stable] #[stable]
pub fn load_utf8(path: &str) -> IoResult<Config> { pub fn load_utf8(path: &str) -> IoResult<Config> {
Config::load(Path::new(path)) Config::load(Path::new(path))
} }
/// Determines whether or not the nickname provided is the owner of the bot /// Determines whether or not the nickname provided is the owner of the bot.
#[stable] #[stable]
pub fn is_owner(&self, nickname: &str) -> bool { pub fn is_owner(&self, nickname: &str) -> bool {
self.owners[].contains(&String::from_str(nickname)) self.owners[].contains(&String::from_str(nickname))

16
src/data/message.rs
View file

@ -1,24 +1,24 @@
//! Messages to and from the server //! Messages to and from the server.
#![experimental] #![experimental]
use std::from_str::FromStr; use std::from_str::FromStr;
/// IRC Message data /// IRC Message data.
#[experimental] #[experimental]
#[deriving(Clone, PartialEq, Show)] #[deriving(Clone, PartialEq, Show)]
pub struct Message { pub struct Message {
/// The message prefix (or source) as defined by [RFC 2812](http://tools.ietf.org/html/rfc2812) /// The message prefix (or source) as defined by [RFC 2812](http://tools.ietf.org/html/rfc2812).
pub prefix: Option<String>, pub prefix: Option<String>,
/// The IRC command as defined by [RFC 2812](http://tools.ietf.org/html/rfc2812) /// The IRC command as defined by [RFC 2812](http://tools.ietf.org/html/rfc2812).
pub command: String, pub command: String,
/// The command arguments /// The command arguments.
pub args: Vec<String>, pub args: Vec<String>,
/// The message suffix as defined by [RFC 2812](http://tools.ietf.org/html/rfc2812) /// The message suffix as defined by [RFC 2812](http://tools.ietf.org/html/rfc2812).
/// This is the only part of the message that is allowed to contain spaces. /// This is the only part of the message that is allowed to contain spaces.
pub suffix: Option<String>, pub suffix: Option<String>,
} }
impl Message { impl Message {
/// Creates a new Message /// Creates a new Message.
#[experimental] #[experimental]
pub fn new(prefix: Option<&str>, command: &str, args: Option<Vec<&str>>, suffix: Option<&str>) pub fn new(prefix: Option<&str>, command: &str, args: Option<Vec<&str>>, suffix: Option<&str>)
-> Message { -> Message {
@ -30,7 +30,7 @@ impl Message {
} }
} }
/// Converts a Message into a String according to the IRC protocol /// Converts a Message into a String according to the IRC protocol.
#[experimental] #[experimental]
pub fn into_string(&self) -> String { pub fn into_string(&self) -> String {
let mut ret = String::new(); let mut ret = String::new();

8
src/data/mod.rs
View file

@ -1,4 +1,4 @@
//! Data related to IRC functionality //! Data related to IRC functionality.
#![experimental] #![experimental]
pub use data::config::Config; pub use data::config::Config;
@ -6,14 +6,14 @@ pub use data::message::Message;
pub use data::command::Command; pub use data::command::Command;
pub mod kinds { pub mod kinds {
//! Trait definitions of appropriate Writers and Buffers for use with this library //! Trait definitions of appropriate Writers and Buffers for use with this library.
#![unstable] #![unstable]
/// Trait describing all possible Writers for this library /// Trait describing all possible Writers for this library.
#[unstable] #[unstable]
pub trait IrcWriter: Writer + Sized + Send + 'static {} pub trait IrcWriter: Writer + Sized + Send + 'static {}
impl<T> IrcWriter for T where T: Writer + Sized + Send + 'static {} impl<T> IrcWriter for T where T: Writer + Sized + Send + 'static {}
/// Trait describing all possible Readers for this library /// Trait describing all possible Readers for this library.
#[unstable] #[unstable]
pub trait IrcReader: Buffer + Sized + Send + 'static {} pub trait IrcReader: Buffer + Sized + Send + 'static {}
impl<T> IrcReader for T where T: Buffer + Sized + Send + 'static {} impl<T> IrcReader for T where T: Buffer + Sized + Send + 'static {}

24
src/server/mod.rs
View file

@ -9,23 +9,23 @@ use data::message::Message;
pub mod utils; pub mod utils;
/// Trait describing core Server functionality /// Trait describing core Server functionality.
#[experimental] #[experimental]
pub trait Server<'a, T, U> { pub trait Server<'a, T, U> {
/// Gets the configuration being used with this Server /// Gets the configuration being used with this Server.
fn config(&self) -> &Config; fn config(&self) -> &Config;
/// Sends a Command to this Server /// Sends a Command to this Server.
fn send(&self, _: Command) -> IoResult<()>; fn send(&self, _: Command) -> IoResult<()>;
/// Gets an Iterator over Messages received by this Server /// Gets an Iterator over Messages received by this Server.
fn iter(&'a self) -> ServerIterator<'a, T, U>; fn iter(&'a self) -> ServerIterator<'a, T, U>;
} }
/// A thread-safe implementation of an IRC Server connection /// A thread-safe implementation of an IRC Server connection.
#[experimental] #[experimental]
pub struct IrcServer<'a, T, U> where T: IrcWriter, U: IrcReader { pub struct IrcServer<'a, T, U> where T: IrcWriter, U: IrcReader {
/// The thread-safe IRC connection /// The thread-safe IRC connection.
conn: Connection<T, U>, conn: Connection<T, U>,
/// The configuration used with this connection /// The configuration used with this connection.
config: Config config: Config
} }
@ -61,7 +61,7 @@ impl<'a, T, U> Server<'a, T, U> for IrcServer<'a, T, U> where T: IrcWriter, U: I
} }
impl<'a, T, U> IrcServer<'a, T, U> where T: IrcWriter, U: IrcReader { impl<'a, T, U> IrcServer<'a, T, U> where T: IrcWriter, U: IrcReader {
/// Creates an IRC server from the specified configuration, and any arbitrary Connection /// Creates an IRC server from the specified configuration, and any arbitrary Connection.
#[experimental] #[experimental]
pub fn from_connection(config: Config, conn: Connection<T, U>) -> IrcServer<'a, T, U> { pub fn from_connection(config: Config, conn: Connection<T, U>) -> IrcServer<'a, T, U> {
IrcServer { IrcServer {
@ -70,12 +70,12 @@ impl<'a, T, U> IrcServer<'a, T, U> where T: IrcWriter, U: IrcReader {
} }
} }
/// Gets a reference to the IRC server's connection /// Gets a reference to the IRC server's connection.
pub fn conn(&self) -> &Connection<T, U> { pub fn conn(&self) -> &Connection<T, U> {
&self.conn &self.conn
} }
/// Handles messages internally for basic bot functionality /// Handles messages internally for basic bot functionality.
#[experimental] #[experimental]
fn handle_message(&self, message: &Message) { fn handle_message(&self, message: &Message) {
if message.command[] == "PING" { if message.command[] == "PING" {
@ -89,14 +89,14 @@ impl<'a, T, U> IrcServer<'a, T, U> where T: IrcWriter, U: IrcReader {
} }
} }
/// An Iterator over an IrcServer's incoming Messages /// An Iterator over an IrcServer's incoming Messages.
#[experimental] #[experimental]
pub struct ServerIterator<'a, T, U> where T: IrcWriter, U: IrcReader { pub struct ServerIterator<'a, T, U> where T: IrcWriter, U: IrcReader {
pub server: &'a IrcServer<'a, T, U> pub server: &'a IrcServer<'a, T, U>
} }
impl<'a, T, U> ServerIterator<'a, T, U> where T: IrcWriter, U: IrcReader { impl<'a, T, U> ServerIterator<'a, T, U> where T: IrcWriter, U: IrcReader {
/// Creates a new ServerIterator for the desired IrcServer /// Creates a new ServerIterator for the desired IrcServer.
#[experimental] #[experimental]
pub fn new(server: &'a IrcServer<'a, T, U>) -> ServerIterator<'a, T, U> { pub fn new(server: &'a IrcServer<'a, T, U>) -> ServerIterator<'a, T, U> {
ServerIterator { ServerIterator {

34
src/server/utils.rs
View file

@ -1,4 +1,4 @@
//! Utilities and shortcuts for working with IRC servers //! Utilities and shortcuts for working with IRC servers.
#![experimental] #![experimental]
use std::io::IoResult; use std::io::IoResult;
@ -8,7 +8,7 @@ use data::config::Config;
use data::kinds::{IrcReader, IrcWriter}; use data::kinds::{IrcReader, IrcWriter};
use server::{Server, ServerIterator}; use server::{Server, ServerIterator};
/// Functionality-providing wrapper for Server /// Functionality-providing wrapper for Server.
#[experimental] #[experimental]
pub struct Wrapper<'a, T, U> where T: IrcWriter, U: IrcReader { pub struct Wrapper<'a, T, U> where T: IrcWriter, U: IrcReader {
server: &'a Server<'a, T, U> + 'a server: &'a Server<'a, T, U> + 'a
@ -29,38 +29,38 @@ impl<'a, T, U> Server<'a, T, U> for Wrapper<'a, T, U> where T: IrcWriter, U: Irc
} }
impl<'a, T, U> Wrapper<'a, T, U> where T: IrcWriter, U: IrcReader { impl<'a, T, U> Wrapper<'a, T, U> where T: IrcWriter, U: IrcReader {
/// Creates a new Wrapper from the given Server /// Creates a new Wrapper from the given Server.
#[experimental] #[experimental]
pub fn new(server: &'a Server<'a, T, U>) -> Wrapper<'a, T, U> { pub fn new(server: &'a Server<'a, T, U>) -> Wrapper<'a, T, U> {
Wrapper { server: server } Wrapper { server: server }
} }
/// Sends a NICK and USER to identify /// Sends a NICK and USER to identify.
#[experimental] #[experimental]
pub fn identify(&self) -> IoResult<()> { pub fn identify(&self) -> IoResult<()> {
try!(self.server.send(NICK(self.server.config().nickname[]))); try!(self.server.send(NICK(self.server.config().nickname[])));
self.server.send(USER(self.server.config().username[], "0", self.server.config().realname[])) self.server.send(USER(self.server.config().username[], "0", self.server.config().realname[]))
} }
/// Sends a PONG with the specified message /// Sends a PONG with the specified message.
#[experimental] #[experimental]
pub fn send_pong(&self, msg: &str) -> IoResult<()> { pub fn send_pong(&self, msg: &str) -> IoResult<()> {
self.server.send(PONG(msg, None)) self.server.send(PONG(msg, None))
} }
/// Joins the specified channel or chanlist /// Joins the specified channel or chanlist.
#[experimental] #[experimental]
pub fn send_join(&self, chanlist: &str) -> IoResult<()> { pub fn send_join(&self, chanlist: &str) -> IoResult<()> {
self.server.send(JOIN(chanlist, None)) self.server.send(JOIN(chanlist, None))
} }
/// Attempts to oper up using the specified username and password /// Attempts to oper up using the specified username and password.
#[experimental] #[experimental]
pub fn send_oper(&self, username: &str, password: &str) -> IoResult<()> { pub fn send_oper(&self, username: &str, password: &str) -> IoResult<()> {
self.server.send(OPER(username, password)) self.server.send(OPER(username, password))
} }
/// Sends a message to the specified target /// Sends a message to the specified target.
#[experimental] #[experimental]
pub fn send_privmsg(&self, target: &str, message: &str) -> IoResult<()> { pub fn send_privmsg(&self, target: &str, message: &str) -> IoResult<()> {
for line in message.split_str("\r\n") { for line in message.split_str("\r\n") {
@ -69,7 +69,8 @@ impl<'a, T, U> Wrapper<'a, T, U> where T: IrcWriter, U: IrcReader {
Ok(()) Ok(())
} }
/// Sets the topic of a channel or requests the current one /// Sets the topic of a channel or requests the current one.
/// If `topic` is an empty string, it won't be included in the message.
#[experimental] #[experimental]
pub fn send_topic(&self, channel: &str, topic: &str) -> IoResult<()> { pub fn send_topic(&self, channel: &str, topic: &str) -> IoResult<()> {
self.server.send(TOPIC(channel, if topic.len() == 0 { self.server.send(TOPIC(channel, if topic.len() == 0 {
@ -79,13 +80,14 @@ impl<'a, T, U> Wrapper<'a, T, U> where T: IrcWriter, U: IrcReader {
})) }))
} }
/// Kills the target with the provided message /// Kills the target with the provided message.
#[experimental] #[experimental]
pub fn send_kill(&self, target: &str, message: &str) -> IoResult<()> { pub fn send_kill(&self, target: &str, message: &str) -> IoResult<()> {
self.server.send(KILL(target, message)) self.server.send(KILL(target, message))
} }
/// Kicks the listed nicknames from the listed channels with a comment /// Kicks the listed nicknames from the listed channels with a comment.
/// If `message` is an empty string, it won't be included in the message.
#[experimental] #[experimental]
pub fn send_kick(&self, chanlist: &str, nicklist: &str, message: &str) -> IoResult<()> { pub fn send_kick(&self, chanlist: &str, nicklist: &str, message: &str) -> IoResult<()> {
self.server.send(KICK(chanlist, nicklist, if message.len() == 0 { self.server.send(KICK(chanlist, nicklist, if message.len() == 0 {
@ -95,7 +97,8 @@ impl<'a, T, U> Wrapper<'a, T, U> where T: IrcWriter, U: IrcReader {
})) }))
} }
/// Changes the mode of the target /// Changes the mode of the target.
/// If `modeparmas` is an empty string, it won't be included in the message.
#[experimental] #[experimental]
pub fn send_mode(&self, target: &str, mode: &str, modeparams: &str) -> IoResult<()> { pub fn send_mode(&self, target: &str, mode: &str, modeparams: &str) -> IoResult<()> {
self.server.send(MODE(target, mode, if modeparams.len() == 0 { self.server.send(MODE(target, mode, if modeparams.len() == 0 {
@ -105,7 +108,8 @@ impl<'a, T, U> Wrapper<'a, T, U> where T: IrcWriter, U: IrcReader {
})) }))
} }
/// Changes the mode of the target by force /// Changes the mode of the target by force.
/// If `modeparams` is an empty string, it won't be included in the message.
#[experimental] #[experimental]
pub fn send_samode(&self, target: &str, mode: &str, modeparams: &str) -> IoResult<()> { pub fn send_samode(&self, target: &str, mode: &str, modeparams: &str) -> IoResult<()> {
self.server.send(SAMODE(target, mode, if modeparams.len() == 0 { self.server.send(SAMODE(target, mode, if modeparams.len() == 0 {
@ -115,13 +119,13 @@ impl<'a, T, U> Wrapper<'a, T, U> where T: IrcWriter, U: IrcReader {
})) }))
} }
/// Forces a user to change from the old nickname to the new nickname /// Forces a user to change from the old nickname to the new nickname.
#[experimental] #[experimental]
pub fn send_sanick(&self, old_nick: &str, new_nick: &str) -> IoResult<()> { pub fn send_sanick(&self, old_nick: &str, new_nick: &str) -> IoResult<()> {
self.server.send(SANICK(old_nick, new_nick)) self.server.send(SANICK(old_nick, new_nick))
} }
/// Invites a user to the specified channel /// Invites a user to the specified channel.
#[experimental] #[experimental]
pub fn send_invite(&self, nick: &str, chan: &str) -> IoResult<()> { pub fn send_invite(&self, nick: &str, chan: &str) -> IoResult<()> {
self.server.send(INVITE(nick, chan)) self.server.send(INVITE(nick, chan))