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]
use std::sync::{Mutex, MutexGuard};
use std::io::{BufferedReader, BufferedWriter, IoResult, TcpStream};
use data::kinds::{IrcWriter, IrcReader};
use data::message::Message;
/// A thread-safe connection
/// A thread-safe connection.
#[experimental]
pub struct Connection<T, U> where T: IrcWriter, U: IrcReader {
writer: Mutex<T>,
@ -13,7 +13,7 @@ pub struct Connection<T, U> where T: IrcWriter, U: IrcReader {
}
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]
pub fn connect(host: &str, port: u16) -> IoResult<Connection<BufferedWriter<TcpStream>, BufferedReader<TcpStream>>> {
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 {
/// Creates a new connection from any arbitrary IrcWriter and IrcReader
/// Creates a new connection from any arbitrary IrcWriter and IrcReader.
#[experimental]
pub fn new(writer: T, reader: U) -> Connection<T, U> {
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]
pub fn send(&self, message: Message) -> IoResult<()> {
let mut send = self.writer.lock();
@ -39,13 +39,13 @@ impl<T, U> Connection<T, U> where T: IrcWriter, U: IrcReader {
send.flush()
}
/// Receives a single line from this connection
/// Receives a single line from this connection.
#[experimental]
pub fn recv(&self) -> IoResult<String> {
self.reader.lock().read_line()
}
/// Acquires the Writer lock
/// Acquires the Writer lock.
#[experimental]
pub fn writer<'a>(&'a self) -> MutexGuard<'a, T> {
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]
use std::io::{InvalidInput, IoError, IoResult};
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]
#[deriving(Show, PartialEq)]
pub enum Command<'a> {
@ -131,7 +131,7 @@ pub enum Command<'a> {
}
impl<'a> Command<'a> {
/// Converts a Command into a Message
/// Converts a Command into a Message.
#[stable]
pub fn to_message(self) -> Message {
match self {
@ -226,7 +226,7 @@ impl<'a> Command<'a> {
}
}
/// Converts a Message into a Command
/// Converts a Message into a Command.
#[stable]
pub fn from_message(m: &'a Message) -> IoResult<Command<'a>> {
/* 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]
fn invalid_input() -> IoError {
IoError {

28
src/data/config.rs
View file

@ -1,36 +1,36 @@
//! JSON configuration files using libserialize
//! JSON configuration files using libserialize.
#![stable]
use std::collections::HashMap;
use std::io::fs::File;
use std::io::{InvalidInput, IoError, IoResult};
use serialize::json::decode;
/// Configuration data
/// Configuration data.
#[deriving(Clone, Decodable, PartialEq, Show)]
#[unstable]
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>,
/// The bot's nickname
/// The bot's nickname.
pub nickname: String,
/// The bot's username
/// The bot's username.
pub username: String,
/// The bot's real name
/// The bot's real name.
pub realname: String,
/// The bot's password
/// The bot's password.
pub password: String,
/// The server to connect to
/// The server to connect to.
pub server: String,
/// The port to connect on
/// The port to connect on.
pub port: u16,
/// A list of channels to join on connection
/// A list of channels to join on connection.
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>,
}
impl Config {
/// Loads a JSON configuration from the desired path
/// Loads a JSON configuration from the desired path.
#[stable]
pub fn load(path: Path) -> IoResult<Config> {
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]
pub fn load_utf8(path: &str) -> IoResult<Config> {
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]
pub fn is_owner(&self, nickname: &str) -> bool {
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]
use std::from_str::FromStr;
/// IRC Message data
/// IRC Message data.
#[experimental]
#[deriving(Clone, PartialEq, Show)]
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>,
/// 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,
/// The command arguments
/// The command arguments.
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.
pub suffix: Option<String>,
}
impl Message {
/// Creates a new Message
/// Creates a new Message.
#[experimental]
pub fn new(prefix: Option<&str>, command: &str, args: Option<Vec<&str>>, suffix: Option<&str>)
-> 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]
pub fn into_string(&self) -> String {
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]
pub use data::config::Config;
@ -6,14 +6,14 @@ pub use data::message::Message;
pub use data::command::Command;
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]
/// Trait describing all possible Writers for this library
/// Trait describing all possible Writers for this library.
#[unstable]
pub trait IrcWriter: 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]
pub trait IrcReader: 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;
/// Trait describing core Server functionality
/// Trait describing core Server functionality.
#[experimental]
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;
/// Sends a Command to this Server
/// Sends a Command to this Server.
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>;
}
/// A thread-safe implementation of an IRC Server connection
/// A thread-safe implementation of an IRC Server connection.
#[experimental]
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>,
/// The configuration used with this connection
/// The configuration used with this connection.
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 {
/// 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]
pub fn from_connection(config: Config, conn: Connection<T, U>) -> IrcServer<'a, T, U> {
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> {
&self.conn
}
/// Handles messages internally for basic bot functionality
/// Handles messages internally for basic bot functionality.
#[experimental]
fn handle_message(&self, message: &Message) {
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]
pub struct ServerIterator<'a, T, U> where T: IrcWriter, U: IrcReader {
pub server: &'a IrcServer<'a, T, U>
}
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]
pub fn new(server: &'a IrcServer<'a, T, U>) -> ServerIterator<'a, T, U> {
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]
use std::io::IoResult;
@ -8,7 +8,7 @@ use data::config::Config;
use data::kinds::{IrcReader, IrcWriter};
use server::{Server, ServerIterator};
/// Functionality-providing wrapper for Server
/// Functionality-providing wrapper for Server.
#[experimental]
pub struct Wrapper<'a, T, U> where T: IrcWriter, U: IrcReader {
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 {
/// Creates a new Wrapper from the given Server
/// Creates a new Wrapper from the given Server.
#[experimental]
pub fn new(server: &'a Server<'a, T, U>) -> Wrapper<'a, T, U> {
Wrapper { server: server }
}
/// Sends a NICK and USER to identify
/// Sends a NICK and USER to identify.
#[experimental]
pub fn identify(&self) -> IoResult<()> {
try!(self.server.send(NICK(self.server.config().nickname[])));
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]
pub fn send_pong(&self, msg: &str) -> IoResult<()> {
self.server.send(PONG(msg, None))
}
/// Joins the specified channel or chanlist
/// Joins the specified channel or chanlist.
#[experimental]
pub fn send_join(&self, chanlist: &str) -> IoResult<()> {
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]
pub fn send_oper(&self, username: &str, password: &str) -> IoResult<()> {
self.server.send(OPER(username, password))
}
/// Sends a message to the specified target
/// Sends a message to the specified target.
#[experimental]
pub fn send_privmsg(&self, target: &str, message: &str) -> IoResult<()> {
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(())
}
/// 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]
pub fn send_topic(&self, channel: &str, topic: &str) -> IoResult<()> {
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]
pub fn send_kill(&self, target: &str, message: &str) -> IoResult<()> {
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]
pub fn send_kick(&self, chanlist: &str, nicklist: &str, message: &str) -> IoResult<()> {
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]
pub fn send_mode(&self, target: &str, mode: &str, modeparams: &str) -> IoResult<()> {
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]
pub fn send_samode(&self, target: &str, mode: &str, modeparams: &str) -> IoResult<()> {
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]
pub fn send_sanick(&self, old_nick: &str, new_nick: &str) -> IoResult<()> {
self.server.send(SANICK(old_nick, new_nick))
}
/// Invites a user to the specified channel
/// Invites a user to the specified channel.
#[experimental]
pub fn send_invite(&self, nick: &str, chan: &str) -> IoResult<()> {
self.server.send(INVITE(nick, chan))