From 47687244afd79da84ecd0594dcb548901851c9d7 Mon Sep 17 00:00:00 2001 From: "Tristan B. Velloza Kildaire" Date: Sat, 18 Mar 2023 11:24:01 +0200 Subject: [PATCH] Exceptions - Commented all of `BirchwoodException` - Moved `ErrorType` up to the module-level - Documented `ErrorType` and all of its member enums Client - Fixed usage of `ErrorType` ConnInfo - Documented `ConnectionInfo` - Fixed usage of `ErrorType` --- source/birchwood/client/client.d | 48 ++++++------- source/birchwood/client/exceptions.d | 104 ++++++++++++++++++++++----- source/birchwood/config/conninfo.d | 48 ++++++++++--- 3 files changed, 151 insertions(+), 49 deletions(-) diff --git a/source/birchwood/client/client.d b/source/birchwood/client/client.d index 5c79113..7cb2f73 100644 --- a/source/birchwood/client/client.d +++ b/source/birchwood/client/client.d @@ -9,7 +9,7 @@ import core.thread : Thread, dur; import std.string; import eventy : EventyEvent = Event, Engine, EventType, Signal; import birchwood.config : ConnectionInfo; -import birchwood.client.exceptions : BirchwoodException; +import birchwood.client.exceptions : BirchwoodException, ErrorType; import birchwood.protocol.messages : Message, encodeMessage, decodeMessage, isValidText; import birchwood.client.receiver : ReceiverThread; @@ -190,12 +190,12 @@ public class Client : Thread } else { - throw new BirchwoodException(BirchwoodException.ErrorType.INVALID_CHANNEL_NAME); + throw new BirchwoodException(ErrorType.INVALID_CHANNEL_NAME); } } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } @@ -248,7 +248,7 @@ public class Client : Thread } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } @@ -258,13 +258,13 @@ public class Client : Thread } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } /* If no channels provided at all (error) */ else { - throw new BirchwoodException(BirchwoodException.ErrorType.EMPTY_PARAMS); + throw new BirchwoodException(ErrorType.EMPTY_PARAMS); } } @@ -319,7 +319,7 @@ public class Client : Thread } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } @@ -329,13 +329,13 @@ public class Client : Thread } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } /* If no channels provided at all (error) */ else { - throw new BirchwoodException(BirchwoodException.ErrorType.EMPTY_PARAMS); + throw new BirchwoodException(ErrorType.EMPTY_PARAMS); } } @@ -403,7 +403,7 @@ public class Client : Thread } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } @@ -413,18 +413,18 @@ public class Client : Thread } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } /* If no recipients provided at all (error) */ else { - throw new BirchwoodException(BirchwoodException.ErrorType.EMPTY_PARAMS); + throw new BirchwoodException(ErrorType.EMPTY_PARAMS); } } @@ -451,12 +451,12 @@ public class Client : Thread } else { - throw new BirchwoodException(BirchwoodException.ErrorType.INVALID_NICK_NAME); + throw new BirchwoodException(ErrorType.INVALID_NICK_NAME); } } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } @@ -509,7 +509,7 @@ public class Client : Thread } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } @@ -519,18 +519,18 @@ public class Client : Thread } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } else { - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } /* If no channels provided at all (error) */ else { - throw new BirchwoodException(BirchwoodException.ErrorType.EMPTY_PARAMS); + throw new BirchwoodException(ErrorType.EMPTY_PARAMS); } } @@ -556,13 +556,13 @@ public class Client : Thread else { //TODO: Invalid channel name - throw new BirchwoodException(BirchwoodException.ErrorType.INVALID_CHANNEL_NAME); + throw new BirchwoodException(ErrorType.INVALID_CHANNEL_NAME); } } else { //TODO: Illegal characters - throw new BirchwoodException(BirchwoodException.ErrorType.ILLEGAL_CHARACTERS); + throw new BirchwoodException(ErrorType.ILLEGAL_CHARACTERS); } } @@ -749,13 +749,13 @@ public class Client : Thread } catch(SocketOSException e) { - throw new BirchwoodException(BirchwoodException.ErrorType.CONNECT_ERROR); + throw new BirchwoodException(ErrorType.CONNECT_ERROR); } } // TODO: Do actual liveliness check here else { - throw new BirchwoodException(BirchwoodException.ErrorType.ALREADY_CONNECTED); + throw new BirchwoodException(ErrorType.ALREADY_CONNECTED); } } @@ -799,7 +799,7 @@ public class Client : Thread /* If above then throw an exception */ else { - throw new BirchwoodException(BirchwoodException.ErrorType.COMMAND_TOO_LONG); + throw new BirchwoodException(ErrorType.COMMAND_TOO_LONG); } } diff --git a/source/birchwood/client/exceptions.d b/source/birchwood/client/exceptions.d index 4aaac53..ae5a1a6 100644 --- a/source/birchwood/client/exceptions.d +++ b/source/birchwood/client/exceptions.d @@ -1,40 +1,112 @@ +/** + * Exception handling + */ module birchwood.client.exceptions; import std.conv : to; +/** + * The type of error to be used + * with BirchwoodException + */ +public enum ErrorType +{ + /** + * If the provided connection information + * is invalid, such as incorrect hostname, + * invalid nick + */ + INVALID_CONN_INFO, + + /** + * If an attempt to call connect() is made + * when already connected + */ + ALREADY_CONNECTED, + + /** + * If there is an erroring opening a connection + * to the endpoint server + */ + CONNECT_ERROR, + + /** + * If invalid parameter information is provided + * to an IRC command method + */ + EMPTY_PARAMS, + + /** + * If an invalid channel name is provided + */ + INVALID_CHANNEL_NAME, + + /** + * If an invalid nickname is provided + */ + INVALID_NICK_NAME, + + /** + * If illegal characters exist within the + * message + */ + ILLEGAL_CHARACTERS, + + /** + * If the final encoded IRC message + * is too long to send to the server + */ + COMMAND_TOO_LONG +} + +/** + * A runtime exception in the Birchwood library + */ public class BirchwoodException : Exception { - // TODO: Move outside one level - public enum ErrorType - { - INVALID_CONN_INFO, - ALREADY_CONNECTED, - CONNECT_ERROR, - EMPTY_PARAMS, - INVALID_CHANNEL_NAME, - INVALID_NICK_NAME, - ILLEGAL_CHARACTERS, - COMMAND_TOO_LONG - } - + /** + * The specific type of error occurred + */ private ErrorType errType; - /* Auxillary error information */ - /* TODO: Make these actually Object */ + /** + * Auxillary information + */ private string auxInfo; + /** + * Constructs a new exception with the given sub-error type + * and infers the auxillary information based on said sub-error + * type + * + * Params: + * errType = the sub-error type + */ this(ErrorType errType) { super("BirchwoodError("~to!(string)(errType)~")"~(auxInfo.length == 0 ? "" : " "~auxInfo)); this.errType = errType; } - + + /** + * Constructs a new exception with the given sub-error type + * and auxillary information + * + * Params: + * errType = the sub-error type + * auxInfo = the auxillary information + */ this(ErrorType errType, string auxInfo) { this(errType); this.auxInfo = auxInfo; } + /** + * Retrieve the specific error which occurred + * + * Returns: the ErrorType of the error + */ public ErrorType getType() { return errType; diff --git a/source/birchwood/config/conninfo.d b/source/birchwood/config/conninfo.d index 2eebd76..9e83fb0 100644 --- a/source/birchwood/config/conninfo.d +++ b/source/birchwood/config/conninfo.d @@ -1,10 +1,10 @@ /** - * COnfiguration-related types + * Configuration-related types */ module birchwood.config.conninfo; import std.socket : SocketException, Address, getAddress; -import birchwood.client.exceptions : BirchwoodException; +import birchwood.client.exceptions; /** * Represents the connection details for a server @@ -12,21 +12,46 @@ import birchwood.client.exceptions : BirchwoodException; */ public struct ConnectionInfo { - /* Server address information */ + /** + * Server address + */ private Address addrInfo; + + /** + * Nickname to use + */ private string nickname; - /* Misc. */ - /* TODO: Make final/const (find out difference) */ + /** + * Size to use to dequeue bytes + * from socket in read-loop + */ private ulong bulkReadSize; - /* Client behaviour (TODO: what is sleep(0), like nothing) */ + //TODO: Make this a Duration + /** + * Time to wait (in seconds) between + * sending messages + */ private ulong fakeLag; - /* The quit message */ + /** + * Quit message + */ public const string quitMessage; /* TODO: before publishing change this bulk size */ + + /** + * Constructs a new ConnectionInfo instance with the + * provided details + * + * Params: + * addrInfo = the server's endpoint + * nickname = the nickname to use + * bulkReadSize = the dequeue read size + * quitMessage = the message to use when quitting + */ private this(Address addrInfo, string nickname, ulong bulkReadSize = 20, string quitMessage = "birchwood client disconnecting...") { this.addrInfo = addrInfo; @@ -38,6 +63,11 @@ public struct ConnectionInfo this.fakeLag = 1; } + /** + * Retrieve the read-dequeue size + * + * Returns: the number of bytes + */ public ulong getBulkReadSize() { return this.bulkReadSize; @@ -95,7 +125,7 @@ public struct ConnectionInfo /* Username check */ if(!nickname.length) { - throw new BirchwoodException(BirchwoodException.ErrorType.INVALID_CONN_INFO); + throw new BirchwoodException(ErrorType.INVALID_CONN_INFO); } /* TODO: Add feature to choose which address to use, prefer v4 or v6 type of thing */ @@ -105,7 +135,7 @@ public struct ConnectionInfo } catch(SocketException e) { - throw new BirchwoodException(BirchwoodException.ErrorType.INVALID_CONN_INFO); + throw new BirchwoodException(ErrorType.INVALID_CONN_INFO); } }