cowirc 0.2.0

/*
 * This file is part of CowIRC.
 *
 * CowIRC is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * CowIRC is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with CowIRC. If not, see <http://www.gnu.org/licenses/>.
 */

use crate::Message;
use std::fmt;

/// Represents different IRC events from the server.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum IncomingIrcEvent {
    Join(String, String),
    Part(String, String, Option<String>),
    Privmsg(String, String, String),
    Notice(String, String, String),
    Kick(String, String, String, String),
    Mode(String, String, String),
    Ping(String),
    Welcome(String),
    Isupport(Vec<(String, Option<String>)>),
    Cap(String, Vec<String>),
    Topic(String, String, String),
    Names(String, Vec<String>),
    EndOfNames(String),
    WhoisUser(String, String, String, String),
    WhoisChannels(String, Vec<String>),
    WhoisServer(String, String, String),
    WhoisLoggedInAs(String, String),
    WhoisIdle(String, String),
    EndOfWhois(String),
    WhoisSecure(String, String),
    Unknown(String),
}

/// Represents errors that might occur parsing the server response.
#[derive(Debug)]
pub enum IncomingIrcEventError {
    ParserError(crate::parser::Error),
    MissingParameter(String),
    MissingSource,
    MissingKey,
}

impl fmt::Display for IncomingIrcEventError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            Self::ParserError(e) => write!(f, "Parser error: {e}"),
            Self::MissingParameter(s) => write!(f, "Missing parameter: {s}"),
            Self::MissingSource => write!(f, "Missing source"),
            Self::MissingKey => write!(f, "Missing key"),
        }
    }
}

impl IncomingIrcEvent {
    /// Handles a `Join` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if a source for the Join is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = String::from(":nick!ident@host JOIN #channel");
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Join(channel, nick) => {
    ///         println!("Channel: {channel}");
    ///         println!("Nick: {nick}");
    ///     },
    ///     _ => eprintln!("error: not a `Join` event!"),
    /// }
    /// ```
    pub fn handle_join(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let channel = parsed_message.get_param(0)?;
        let nickname = &parsed_message
            .source
            .as_ref()
            .ok_or(IncomingIrcEventError::MissingSource)?
            .nickname;
        Ok((
            Self::Join(channel.to_string(), nickname.to_string()),
            parsed_message,
        ))
    }

    /// Handles a `Part` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if a source for the Part is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = String::from(":nick!ident@host PART #channel :Goodbye, world!");
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Part(channel, nick, part_message) => {
    ///         println!("Channel: {channel}");
    ///         println!("Nick: {nick}");
    ///         println!("Part Message: {:?}", part_message)
    ///     },
    ///     _ => eprintln!("error: not a `Part` event!"),
    /// }
    /// ```
    pub fn handle_part(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let channel = parsed_message.get_param(0)?;
        let part_message = parsed_message
            .get_param(1)
            .map_or(None, |part_message| Some(part_message.to_string()));
        let nickname = &parsed_message
            .source
            .as_ref()
            .ok_or(IncomingIrcEventError::MissingSource)?
            .nickname;
        Ok((
            Self::Part(channel.to_string(), nickname.to_string(), part_message),
            parsed_message,
        ))
    }

    /// Handles a `Privmsg` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if a source or target for the Privmsg is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = String::from(":nick!ident@host PRIVMSG #channel :Hello, world!");
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Privmsg(channel, nick, message) => {
    ///         println!("Channel: {channel}");
    ///         println!("Nick: {nick}");
    ///         println!("Message: {message}")
    ///     },
    ///     _ => eprintln!("error: not a `Privmsg` event!"),
    /// }
    /// ```
    pub fn handle_privmsg(
        parsed_message: Message,
    ) -> Result<(Self, Message), IncomingIrcEventError> {
        let target = parsed_message.get_param(0)?;
        let message = parsed_message.get_param(1)?;
        let nickname = &parsed_message
            .source
            .as_ref()
            .ok_or(IncomingIrcEventError::MissingSource)?
            .nickname;
        Ok((
            Self::Privmsg(
                target.to_string(),
                nickname.to_string(),
                message.to_string(),
            ),
            parsed_message,
        ))
    }

    /// Handles a `Notice` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if a source or target for the Notice is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = String::from(":nick!ident@host NOTICE #channel :Hello, world!");
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Notice(channel, nick, message) => {
    ///         println!("Channel: {channel}");
    ///         println!("Nick: {nick}");
    ///         println!("Message: {message}")
    ///     },
    ///     _ => eprintln!("error: not a `Notice` event!"),
    /// }
    /// ```
    pub fn handle_notice(
        parsed_message: Message,
    ) -> Result<(Self, Message), IncomingIrcEventError> {
        let target = parsed_message.get_param(0)?;
        let nickname = &parsed_message
            .source
            .as_ref()
            .ok_or(IncomingIrcEventError::MissingSource)?
            .nickname;
        let message = parsed_message.get_param(1)?;
        Ok((
            Self::Notice(
                target.to_string(),
                nickname.to_string(),
                message.to_string(),
            ),
            parsed_message,
        ))
    }

    /// Handles a `Kick` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if a source, channel, nickname or reason for the Kick is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = String::from(":kicker!ident@host KICK #channel nickname :You have been kicked");
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Kick(channel, nickname, kicker, reason) => {
    ///     println!("Channel: {channel}");
    ///     println!("Nickname: {nickname}");
    ///     println!("Kicker: {kicker}");
    ///     println!("Reason: {reason}");
    ///     },
    ///     _ => eprintln!("error: not a `Kick` event!"),
    /// }
    /// ```
    pub fn handle_kick(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let channel = parsed_message.get_param(0)?;
        let nickname = parsed_message.get_param(1)?;
        let kicker = &parsed_message
            .source
            .as_ref()
            .ok_or(IncomingIrcEventError::MissingSource)?
            .nickname;
        let reason = parsed_message.get_param(2)?;
        Ok((
            Self::Kick(
                channel.to_string(),
                nickname.to_string(),
                kicker.to_string(),
                reason.to_string(),
            ),
            parsed_message,
        ))
    }

    /// Handles a `Mode` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if a target or mode change for the Mode is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = String::from(":irc.server.com MODE #channel +o nickname");
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Mode(target, mode_change, mode_args) => {
    ///         println!("Target: {target}");
    ///         println!("Mode Change: {mode_change}");
    ///         println!("Mode Arguments: {mode_args}");
    ///     },
    ///     _ => eprintln!("error: not a `Mode` event!"),
    /// }
    /// ```
    pub fn handle_mode(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let target = parsed_message.get_param(0)?;
        let mode_change = parsed_message.get_param(1)?;
        let params = parsed_message.params();
        let mode_args = params.get(2..).unwrap_or(&[]);
        Ok((
            Self::Mode(
                target.to_string(),
                mode_change.to_string(),
                mode_args.join(" "),
            ),
            parsed_message,
        ))
    }

    /// Handles a `Ping` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if a server for the PING is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = String::from("PING :irc.server.com");
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Ping(server) => {
    ///         println!("Server: {server}");
    ///     },
    ///     _ => eprintln!("error: not a `Ping` event!"),
    /// }
    /// ```
    pub fn handle_ping(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let server = parsed_message.get_param(0)?;
        Ok((Self::Ping(server.to_string()), parsed_message))
    }

    /// Handles a `Cap` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the subcommand or capabilities are missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = String::from(":irc.server.com CAP * ACK :sasl multi-prefix");
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Cap(subcommand, capabilities) => {
    ///         println!("Subcommand: {subcommand}");
    ///         println!("Capabilities: {}", capabilities.join(" "));
    ///     },
    ///     _ => eprintln!("error: not a `Cap` event!"),
    /// }
    /// ```
    pub fn handle_cap(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let subcommand = parsed_message.get_param(1)?;
        let capabilities = parsed_message.get_param(2)?;
        let tokens: Vec<String> = capabilities
            .split_whitespace()
            .map(std::string::ToString::to_string)
            .collect();
        Ok((Self::Cap(subcommand.to_string(), tokens), parsed_message))
    }

    /// Handles a `Welcome` event,
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the source for the welcome message is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = String::from(":irc.server.com 001 nickname :Welcome to the IRC Server");
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Welcome(message) => {
    ///         println!("Welcome Message: {message}");
    ///     },
    ///     _ => eprintln!("error: not a `Welcome` event!"),
    /// }
    /// ```
    pub fn handle_001(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let message = parsed_message.get_param(1)?;
        let nickname = &parsed_message
            .source
            .as_ref()
            .ok_or(IncomingIrcEventError::MissingSource)?
            .nickname;
        Ok((
            Self::Welcome(format!("{nickname}: {message}")),
            parsed_message,
        ))
    }

    /// Handles an `Isupport` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if a key for the parts is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = ":irc.server.com 005 nickname CHANMODES=eIbq,k,flj,CFLMPQRSTcgimnprstuz CHANLIMIT=#:250 PREFIX=(ov)@+ MAXLIST=bqeI:100 MODES=4 NETWORK=Irc.Server STATUSMSG=@+ CASEMAPPING=rfc1459 NICKLEN=16 MAXNICKLEN=16 CHANNELLEN=50 TOPICLEN=390 :are supported by this server";
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Isupport(capabilities) => {
    ///         for (key, value) in capabilities {
    ///             match value {
    ///                 Some(val) => println!("{}: {}", key, val),
    ///                 None => println!("{}", key),
    ///             }
    ///         }
    ///     },
    ///     _ => eprintln!("error: not an `Isupport` event!"),
    /// }
    /// ```
    pub fn handle_005(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let isupports = parsed_message.params()[1..].to_vec();
        let mut parsed_isupports = Vec::new();
        for isupport in isupports {
            let mut parts = isupport.splitn(2, '=');
            let key = match parts.next() {
                Some(key) => key.to_string(),
                None => return Err(IncomingIrcEventError::MissingKey),
            };

            let value = parts.next().map(std::string::ToString::to_string);
            parsed_isupports.push((key, value));
        }
        Ok((Self::Isupport(parsed_isupports), parsed_message))
    }

    /// Handles a `WhoisUser` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the target, username, host or realname is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = ":irc.server.com 311 nickname target username host * :real name";
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::WhoisUser(target, username, host, realname) => {
    ///         println!("Target: {target}");
    ///         println!("Username: {username}");
    ///         println!("Host: {host}");
    ///         println!("Real Name: {realname}");
    ///     },
    ///     _ => eprintln!("error: not a `WhoisUser` event!"),
    /// }
    /// ```
    pub fn handle_311(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let target = parsed_message.get_param(1)?;
        let username = parsed_message.get_param(2)?;
        let host = parsed_message.get_param(3)?;
        let realname = parsed_message.get_param(5)?;
        Ok((
            Self::WhoisUser(
                target.to_string(),
                username.to_string(),
                host.to_string(),
                realname.to_string(),
            ),
            parsed_message,
        ))
    }

    /// Handles a `WhoisServer` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the target, server or server info is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = ":irc.server.com 312 nick anothernick irc.server.com :Earth";
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::WhoisServer(target, server, server_info) => {
    ///         println!("Target: {target}");
    ///         println!("Server: {server}");
    ///         println!("Server Info: {server_info}");
    ///     },
    ///     _ => eprintln!("error: not a `WhoisServer` event!"),
    /// }
    /// ```
    pub fn handle_312(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let target = parsed_message.get_param(1)?;
        let server = parsed_message.get_param(2)?;
        let server_info = parsed_message.get_param(3)?;
        Ok((
            Self::WhoisServer(
                target.to_string(),
                server.to_string(),
                server_info.to_string(),
            ),
            parsed_message,
        ))
    }

    /// Handles a `WhoisIdle` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the `target` or `idle_time` is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = ":irc.server.com 317 nick anothernick 1800";
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::WhoisIdle(target, idle_time) => {
    ///         println!("Target: {target}");
    ///         println!("Idle Time: {idle_time} seconds");
    ///     },
    ///     _ => eprintln!("error: not a `317` event!"),
    /// }
    /// ```
    pub fn handle_317(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let target = parsed_message.get_param(1)?;
        let idle_time = parsed_message.get_param(2)?;
        Ok((
            Self::WhoisIdle(target.to_string(), idle_time.to_string()),
            parsed_message,
        ))
    }

    /// Handles an `EndOfWhois` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the target is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = ":irc.server.com 318 nick anothernick :End of /WHOIS list.";
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::EndOfWhois(target) => {
    ///         println!("Target: {target}");
    ///     },
    ///     _ => eprintln!("error: not a `EndOfWhois` event!"),
    /// }
    /// ```
    pub fn handle_318(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let target = parsed_message.get_param(1)?;
        Ok((Self::EndOfWhois(target.to_string()), parsed_message))
    }

    /// Handles a `WhoisChannels` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the target or channels are missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = ":irc.server.com 319 mynick anothernick :#channel";
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::WhoisChannels(target, channels) => {
    ///         println!("Target: {target}");
    ///         println!("Channels: {}", channels.join(", "));
    ///     },
    ///     _ => eprintln!("error: not a `WhoisChannels` event!"),
    /// }
    /// ```
    pub fn handle_319(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let target = parsed_message.get_param(1)?;
        let channels = parsed_message
            .get_param(2)?
            .split(' ')
            .map(std::string::ToString::to_string)
            .collect();
        Ok((
            Self::WhoisChannels(target.to_string(), channels),
            parsed_message,
        ))
    }

    /// Handles a `WhoisLoggedInAs` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the target or nickname are missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = ":irc.server.com 330 mynick anothernick anothernick :is logged in as";
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::WhoisLoggedInAs(target, nickname) => {
    ///         println!("Target: {target}");
    ///         println!("Logged in as: {nickname}");
    ///     },
    ///     _ => eprintln!("error: not a `WhoisLoggedInAs` event!"),
    /// }
    /// ```
    pub fn handle_330(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let target = parsed_message.get_param(1)?;
        let nickname = parsed_message.get_param(2)?;
        Ok((
            Self::WhoisLoggedInAs(target.to_string(), nickname.to_string()),
            parsed_message,
        ))
    }

    /// Handles a `Topic` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the channel, topic, or source are missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = ":irc.server.com 332 nick #channel :Welcome to the channel!";
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Topic(channel, nickname, topic) => {
    ///         println!("Channel: {channel}");
    ///         println!("Set by: {nickname}");
    ///         println!("Topic: {topic}");
    ///     },
    ///     _ => eprintln!("error: not a `Topic` event!"),
    /// }
    /// ```
    pub fn handle_332(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let channel = parsed_message.get_param(1)?;
        let topic = parsed_message.get_param(2)?;
        let nickname = &parsed_message
            .source
            .as_ref()
            .ok_or(IncomingIrcEventError::MissingSource)?
            .nickname;
        Ok((
            Self::Topic(channel.to_string(), nickname.to_string(), topic.to_string()),
            parsed_message,
        ))
    }

    /// Handles a `Names` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the channel or list of `names` is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = ":irc.server.com 353 nick @ #chanel :nick @anothernick";
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::Names(channel, names) => {
    ///         println!("Channel: {channel}");
    ///         println!("Names: {}", names.join(", "));
    ///     },
    ///     _ => eprintln!("error: not a `Names` event!"),
    /// }
    /// ```
    pub fn handle_353(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let channel = parsed_message.get_param(2)?;
        let names = parsed_message.get_param(3)?;
        let names: Vec<String> = names
            .split(' ')
            .map(std::string::ToString::to_string)
            .collect();
        Ok((Self::Names(channel.to_string(), names), parsed_message))
    }

    /// Handles an `EndOfNames` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the channel is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = ":irc.server.com 366 nick #channel :End of /NAMES list.";
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::EndOfNames(channel) => {
    ///         println!("Channel: {channel}");
    ///     },
    ///     _ => eprintln!("error: not a `EndOfNames` event!"),
    /// }
    /// ```
    pub fn handle_366(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let channel = parsed_message.get_param(1)?;
        Ok((Self::EndOfNames(channel.to_string()), parsed_message))
    }

    /// Handles a `WhoisSecure` event.
    ///
    /// # Arguments
    ///
    /// * `parsed_message` - `Message` struct containing the parsed version of the server response.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return `IncomingIrcEventError` if the target or the message is missing.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let response = ":irc.server.com 671 nick anothernick :is using a secure connection";
    /// let (event, parsed_response) = IncomingIrcEvent::new(&response).unwrap();
    /// println!("Parsed response: {:?}", parsed_response);
    /// match event {
    ///     IncomingIrcEvent::WhoisSecure(target, message) => {
    ///         println!("Target: {target}");
    ///         println!("Secure Connection: {message}");
    ///     },
    ///     _ => eprintln!("error: not a `WhoisSecure` event!"),
    /// }
    /// ```
    pub fn handle_671(parsed_message: Message) -> Result<(Self, Message), IncomingIrcEventError> {
        let target = parsed_message.get_param(1)?;
        let message = parsed_message.get_param(2)?;
        Ok((
            Self::WhoisSecure(target.to_string(), message.to_string()),
            parsed_message,
        ))
    }

    /// Parses the input string and handles the corresponding IRC event.
    ///
    /// # Arguments
    ///
    /// * `input` - A string containing the raw IRC message.
    ///
    /// # Returns
    ///
    /// * `<Result(Self, Message), IncomingIrcEventError>` - A result containing either a tuple of
    /// an instantiated Enum `IncomingIrcEvent` with the handled event and an instantiated `Message`
    /// struct containing the parsed version of the server response, or on failure an error of type
    /// `IncomingIrcEventError` with more details.
    ///
    /// # Errors
    ///
    /// Will return an `IncomingIrcEventError` if the parsing or handling of the IRC event encounters an error.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use cowirc::event_handler::IncomingIrcEvent;
    ///
    /// let input = ":nick!user@host JOIN #channel";
    /// let (event, parsed_message) = IncomingIrcEvent::new(&input).unwrap();
    /// println!("Parsed message: {:?}", parsed_message);
    /// match event {
    ///     // Handle desired IRC events
    ///     _ => eprintln!("error: unrecognized event!"),
    /// }
    /// ```
    pub fn new(input: &str) -> Result<(Self, Message), IncomingIrcEventError> {
        let parsed_message =
            Message::from(input.to_string()).map_err(IncomingIrcEventError::ParserError)?;
        match parsed_message.command.to_uppercase().as_str() {
            "JOIN" => Self::handle_join(parsed_message),
            "PART" => Self::handle_part(parsed_message),
            "PRIVMSG" => Self::handle_privmsg(parsed_message),
            "NOTICE" => Self::handle_notice(parsed_message),
            "KICK" => Self::handle_kick(parsed_message),
            "MODE" => Self::handle_mode(parsed_message),
            "PING" => Self::handle_ping(parsed_message),
            "CAP" => Self::handle_cap(parsed_message),
            "001" => Self::handle_001(parsed_message),
            "005" => Self::handle_005(parsed_message),
            "311" => Self::handle_311(parsed_message),
            "312" => Self::handle_312(parsed_message),
            "317" => Self::handle_317(parsed_message),
            "318" => Self::handle_318(parsed_message),
            "319" => Self::handle_319(parsed_message),
            "330" => Self::handle_330(parsed_message),
            "332" => Self::handle_332(parsed_message),
            "353" => Self::handle_353(parsed_message),
            "366" => Self::handle_366(parsed_message),
            "671" => Self::handle_671(parsed_message),
            _ => Ok((Self::Unknown(input.to_string()), parsed_message)),
        }
    }
}